jens/flipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Replace style guide references

Browse Source 
Summary:
allow-large-files
See D34339758

Reviewed By: jknoxville

Differential Revision: D34378570

fbshipit-source-id: ad451afc1774e6d38902d510629ce1b92457adf0
This commit is contained in:
Andrey Goncharov
2022-02-22 07:58:26 -08:00
committed by Facebook GitHub Bot
parent 342c316c84
commit bed23c586b
4 changed files with 24 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/extending/flipper-plugin.mdx
View File

@@ -821,7 +821,7 @@ const [showWhitespace, setShowWhitespace] = useLocalStorageState(
### Layout.* ### Layout.*
Layout elements can be used to organize the screen layout. Layout elements can be used to organize the screen layout.
See `View > Flipper Style Guide` inside the Flipper application for more details. See [the style guide](style-guide.mdx) for more details.
### DataTable ### DataTable
### DataFormatter ### DataFormatter
@@ -933,7 +933,7 @@ Shows a loading spinner. Accept an optional `size` to make the spinner larger /
### NUX ### NUX
An element that can be used to provide a New User eXperience: Hints that give a one time introduction to new features to the current user. An element that can be used to provide a New User eXperience: Hints that give a one time introduction to new features to the current user.
See `View > Flipper Style Guide` inside the Flipper application for more details. See [the style guide](style-guide.mdx) for more details.
### FileSelector ### FileSelector
@@ -964,12 +964,12 @@ It doesn't really matter where exactly this component is used in your layout, as
An element that can be used to track user interactions. An element that can be used to track user interactions.
An example scuba query can be found [here](https://fburl.com/scuba/infinity_analytics_events/xryoq5j7). An example scuba query can be found [here](https://fburl.com/scuba/infinity_analytics_events/xryoq5j7).
See `View > Flipper Style Guide` inside the Flipper application for more details. See [the style guide](style-guide.mdx) for more details.
### TrackingScope ### TrackingScope
Defines the location of underlying Tracked elements more precisely. Defines the location of underlying Tracked elements more precisely.
See `View > Flipper Style Guide` inside the Flipper application for more details. See [the style guide](style-guide.mdx) for more details.
### withTrackingScope ### withTrackingScope
@@ -981,7 +981,7 @@ Higher order component that wraps a component automatically in a [`TrackingScope
Provides a standard set of colors and spacings, used by the Flipper style guide. Provides a standard set of colors and spacings, used by the Flipper style guide.
The colors exposed here support dark mode. The colors exposed here support dark mode.
See `View > Flipper Style Guide` inside the Flipper application for more details. See [the style guide](style-guide.mdx) for more details.
## Utilities ## Utilities
@@ -1074,7 +1074,7 @@ Given a string or React element, returns a text representation of that element,
### path ### path
A set of utilizities to handle file paths. A subset of Node.js' [path](https://nodejs.org/api/path.html). A set of utilizities to handle file paths. A subset of Node.js' [path](https://nodejs.org/api/path.html).
<!-- Docs copied from https://github.com/nodejs/node/blob/master/doc/api/path.md --> <!-- Docs copied from https://github.com/nodejs/node/blob/master/doc/api/path.md -->
#### `path.basename(path[, ext])` #### `path.basename(path[, ext])`

30
docs/extending/sandy-migration.mdx
View File

@@ -6,7 +6,7 @@ title: Migrating a plugin to Sandy
Migrating a plugin to the new Sandy plugin architecture consists of 3 steps: Migrating a plugin to the new Sandy plugin architecture consists of 3 steps:
1. Enabling Sandy for a plugin. 1. Enabling Sandy for a plugin.
2. Update state and connection management to use the Sandy APIs. 2. Update state and connection management to use the Sandy APIs.
3. Update the UI to use Sandy / Antd components only. 3. Update the UI to use Sandy / Antd components only.
## Opting in to Sandy ## Opting in to Sandy
@@ -45,12 +45,12 @@ The goal of this step is to use and leave the plugin UI largely as is but conver
<FbInternalOnly> <FbInternalOnly>
For every plugin, we generated a task on our [Sandy Plugin Migration](https://www.internalfb.com/tasks?folder_filters&q=1341478626215302&group_by_type=MANUAL) dashboard. Completing this step corresponds to completing the `[flipper][sandy] convert plugin 'xxxx' to use Sandy APIs` task. For every plugin, we generated a task on our [Sandy Plugin Migration](https://www.internalfb.com/tasks?folder_filters&q=1341478626215302&group_by_type=MANUAL) dashboard. Completing this step corresponds to completing the `[flipper][sandy] convert plugin 'xxxx' to use Sandy APIs` task.
If you start this task, please assign yourself as owner and link it in the diff. If you start this task, please assign yourself as owner and link it in the diff.
</FbInternalOnly> </FbInternalOnly>
Comparing to 'classic' plugins, there are a few fundamental differences when it comes to the plugin structure of Sandy plugins. Comparing to 'classic' plugins, there are a few fundamental differences when it comes to the plugin structure of Sandy plugins.
A class extending from `FlipperPlugin` which is exported as `default` is _no longer_ used to define a plugin. A class extending from `FlipperPlugin` which is exported as `default` is _no longer_ used to define a plugin.
Instead, a plugin definition consists of two parts: Instead, a plugin definition consists of two parts:
1. A definition of the state and logic of our plugin that is exported under the name `plugin`: `export function plugin(client: PluginClient<Events, Methods>) { ... }`. Most of the state and all connection logic will move here. 1. A definition of the state and logic of our plugin that is exported under the name `plugin`: `export function plugin(client: PluginClient<Events, Methods>) { ... }`. Most of the state and all connection logic will move here.
@@ -62,7 +62,7 @@ The `plugin` function is called exactly once when a plugin is set up for an appl
even when the user is navigating away. even when the user is navigating away.
It used to be necessary to use `persistedState` for this kind of state, but that is no longer the case. It used to be necessary to use `persistedState` for this kind of state, but that is no longer the case.
In contrast, the `Component` component is mounted whenever the user _opens_ the plugin, so any state stored locally in that React component will be lost if the user navigates away. In contrast, the `Component` component is mounted whenever the user _opens_ the plugin, so any state stored locally in that React component will be lost if the user navigates away.
We recommend avoiding that, and store state, including selection, in the `plugin` definition instead, using the `createState` abstraction. We recommend avoiding that, and store state, including selection, in the `plugin` definition instead, using the `createState` abstraction.
The relation between `plugin`, its parameter `client`, and how to use it in your `Component` definition is documented in detail in the [Plugin Declaration section](../tutorial/js-custom.mdx#the-plugin-declaration). The relation between `plugin`, its parameter `client`, and how to use it in your `Component` definition is documented in detail in the [Plugin Declaration section](../tutorial/js-custom.mdx#the-plugin-declaration).
@@ -74,7 +74,7 @@ This step is completed if the plugin follows the next `plugin` / `component` str
### Tips: ### Tips:
* To quickly verify the plugin compiles, the simplest way is to keep `yarn tsc -w` running in the `desktop` folder. * To quickly verify the plugin compiles, the simplest way is to keep `yarn tsc -w` running in the `desktop` folder.
* Similarly `yarn watch` can be used to run the unit tests in watch mode. Use the `p` key to filter for your specific plugin if `jest` doesn't do so automatically. * Similarly `yarn watch` can be used to run the unit tests in watch mode. Use the `p` key to filter for your specific plugin if `jest` doesn't do so automatically.
* Example of migrating the network plugin to use Sandy APIs. D24108772 / [Github commit](https://github.com/facebook/flipper/commit/fdde2761ef054e44f399c846a2eae6baba03861e) * Example of migrating the network plugin to use Sandy APIs. D24108772 / [Github commit](https://github.com/facebook/flipper/commit/fdde2761ef054e44f399c846a2eae6baba03861e)
* Example of migrating the example plugin to use Sandy APIs. D22308265 / [Github commit](https://github.com/facebook/flipper/commit/babc88e472612c66901d21d289bd217ef28ee385#diff-a145be72bb13a4675dcc8cbac5e55abcd9a542cc92f5c781bd7d3749f13676fc) * Example of migrating the example plugin to use Sandy APIs. D22308265 / [Github commit](https://github.com/facebook/flipper/commit/babc88e472612c66901d21d289bd217ef28ee385#diff-a145be72bb13a4675dcc8cbac5e55abcd9a542cc92f5c781bd7d3749f13676fc)
@@ -82,7 +82,7 @@ This step is completed if the plugin follows the next `plugin` / `component` str
* These steps typically does not involve change much the UI or touch other files than `index.tsx`. Typically, the root component needs to be changed, but most other components can remain as is. However, if a ManagedTable is used (see the next section), it might be easier to already convert the table in this step. * These steps typically does not involve change much the UI or touch other files than `index.tsx`. Typically, the root component needs to be changed, but most other components can remain as is. However, if a ManagedTable is used (see the next section), it might be easier to already convert the table in this step.
* Sandy has first class support for unit testing your plugin and mocking device interactions. Please do set up unit tests per documentation linked above! * Sandy has first class support for unit testing your plugin and mocking device interactions. Please do set up unit tests per documentation linked above!
* If the original plugin definition contained `state`, it is recommended to create one new state atoms (`createState`) per field in the original `state`, rather than having one big atom. * If the original plugin definition contained `state`, it is recommended to create one new state atoms (`createState`) per field in the original `state`, rather than having one big atom.
* If the original plugin definition contained `persistedState`, it is recommended to create one new state atoms (`createState`) per field in the original `state`, rather than having one big atom. By setting the `persist` [option](flipper-plugin.mdx#options) of the state, you can make sure this piece of state becomes part of the import / export functionality of Flipper. Which is important if the data stored here is relevant for bug reports. * If the original plugin definition contained `persistedState`, it is recommended to create one new state atoms (`createState`) per field in the original `state`, rather than having one big atom. By setting the `persist` [option](flipper-plugin.mdx#options) of the state, you can make sure this piece of state becomes part of the import / export functionality of Flipper. Which is important if the data stored here is relevant for bug reports.
* For deeply nested state updates, using `state.update` is often simpler than using `state.set`, as it uses [immer](https://immerjs.github.io/immer/) under the hood to make immutable state updates straight forward. * For deeply nested state updates, using `state.update` is often simpler than using `state.set`, as it uses [immer](https://immerjs.github.io/immer/) under the hood to make immutable state updates straight forward.
* For the same reason, you don't need to shallowly clone your state anymore, as long as `state.update` is used for state updates. * For the same reason, you don't need to shallowly clone your state anymore, as long as `state.update` is used for state updates.
* When dealing a lot with promises, using [`async` / `await`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) is usually simpler. * When dealing a lot with promises, using [`async` / `await`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) is usually simpler.
@@ -106,23 +106,23 @@ Some abstractions that used to be (for example) static methods on `FlipperPlugin
<FbInternalOnly> <FbInternalOnly>
For every plugin, we generated a tasks on our [Sandy Plugin Migration](https://www.internalfb.com/tasks?folder_filters&q=1341478626215302&group_by_type=MANUAL) dashboard. Completing this step corresponds to completing the `[flipper][sandy] convert plugin 'xxxx's UI to use ant.design` task. For every plugin, we generated a tasks on our [Sandy Plugin Migration](https://www.internalfb.com/tasks?folder_filters&q=1341478626215302&group_by_type=MANUAL) dashboard. Completing this step corresponds to completing the `[flipper][sandy] convert plugin 'xxxx's UI to use ant.design` task.
If you start this task, please assign yourself as owner and link it in the diff. If you start this task, please assign yourself as owner and link it in the diff.
</FbInternalOnly> </FbInternalOnly>
The goal of this step is to update the UI of the plugin to use Sandy / Ant.design components. The goal of this step is to update the UI of the plugin to use Sandy / Ant.design components.
These will provide a more consistent user experience, usually provide better UX and they support dark mode! These will provide a more consistent user experience, usually provide better UX and they support dark mode!
Roughly speaking this typically involves replacing all imported components with their modern counterpart. Roughly speaking this typically involves replacing all imported components with their modern counterpart.
For Sandy plugins, components can be found here: For Sandy plugins, components can be found here:
* Interactive data displaying components are exposed from `flipper-plugin`: `DataTable` (for tables), `DataInspector` (for JSON trees) and `ElementInspector` (for element trees). * Interactive data displaying components are exposed from `flipper-plugin`: `DataTable` (for tables), `DataInspector` (for JSON trees) and `ElementInspector` (for element trees).
* `flipper-plugin` also provides the primitives to organise the `Layout` of the plugin. * `flipper-plugin` also provides the primitives to organise the `Layout` of the plugin.
* Practically all other, more generic components are provided by [ant.design](https://ant.design/components/overview/), a proven mature open source component library, which is much richer than the components that are offered from `flipper`. * Practically all other, more generic components are provided by [ant.design](https://ant.design/components/overview/), a proven mature open source component library, which is much richer than the components that are offered from `flipper`.
In Sandy, the layout is typically build by using a combination of `Layout.Top` (or `.Right`, `.Left`, `.Bottom`), which divides all available space in a fixed and dynamic section, `Layout.Scrollable`, which takes all available space and provides scrollbars if its content is still greater, and `Layout.Container` which organizes paddings, borders and spacing between elements etc. In Sandy, the layout is typically build by using a combination of `Layout.Top` (or `.Right`, `.Left`, `.Bottom`), which divides all available space in a fixed and dynamic section, `Layout.Scrollable`, which takes all available space and provides scrollbars if its content is still greater, and `Layout.Container` which organizes paddings, borders and spacing between elements etc.
We generally recommend against using `margins`; use padding and `gap` instead. We generally recommend against using `margins`; use padding and `gap` instead.
Ideally, use `theme.spacing` to get standard numbers for margins and paddings instead of hard-coded numbers. Ideally, use `theme.spacing` to get standard numbers for margins and paddings instead of hard-coded numbers.
This will help with achieving consistency in look and feel. This will help with achieving consistency in look and feel.
@@ -130,7 +130,7 @@ This will help with achieving consistency in look and feel.
There are three important resources to check for documentation on the components available: There are three important resources to check for documentation on the components available:
1. If you start Flipper, and go to `View > Flipper style guide`, you will see a general overview of the Flipper design system. It will demonstrate colors, typography and creating layouts including some examples. 1. [Flipper style guide - a general overview of the Flipper design system](style-guide.mdx). It will demonstrate colors, typography and creating layouts including some examples.
2. The [ant.design component overview](https://ant.design/components/overview/) 2. The [ant.design component overview](https://ant.design/components/overview/)
3. The [API reference](flipper-plugin.mdx#ui-components) documentation for the components provided by `flipper-plugin` 3. The [API reference](flipper-plugin.mdx#ui-components) documentation for the components provided by `flipper-plugin`
@@ -139,7 +139,7 @@ There are three important resources to check for documentation on the components
For conversion, the following table maps the old components to the new ones: For conversion, the following table maps the old components to the new ones:
| Old `flipper` component | New component | Providing package | Notes | | Old `flipper` component | New component | Providing package | Notes |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| `DetailsSidebar` | `DetailsSidebar` | `flipper-plugin` | as-is | | `DetailsSidebar` | `DetailsSidebar` | `flipper-plugin` | as-is |
| `Sidebar` | `Layout.Top` (or `.Right`, `.Left`, `.Bottom`) | `flipper-plugin` | Set the `resizable` flag to allow the user to resize the pane. | | | `Sidebar` | `Layout.Top` (or `.Right`, `.Left`, `.Bottom`) | `flipper-plugin` | Set the `resizable` flag to allow the user to resize the pane. | |
| `FlexColumn` / `Pane` / `View` | `Layout.Container` | `flipper-plugin` | Use the `gap` property to provide some spacing between the children!| | `FlexColumn` / `Pane` / `View` | `Layout.Container` | `flipper-plugin` | Use the `gap` property to provide some spacing between the children!|
@@ -159,7 +159,7 @@ Most other components, like `select` elements, tabs, date-pickers, etc etc can a
### Theming & custom styled components ### Theming & custom styled components
Creating your own components / styling using `styled` is still supported. Creating your own components / styling using `styled` is still supported.
But ideally, you should need custom styled components a lot less! But ideally, you should need custom styled components a lot less!
Since Sandy plugins are expected to support dark mode, (use the settings pane to quickly toggle), we recommend to not use hard-coded colors, but instead use one of the semantic colors that are provided through the `theme` object that can be imported from `flipper-plugin`. Since Sandy plugins are expected to support dark mode, (use the settings pane to quickly toggle), we recommend to not use hard-coded colors, but instead use one of the semantic colors that are provided through the `theme` object that can be imported from `flipper-plugin`.
@@ -170,7 +170,7 @@ Tip: it is recommended to keep components as much as possible outside the entry
### Wrapping up ### Wrapping up
This step of the process is completed as soon as there are no imports from the `flipper` package anymore. This step of the process is completed as soon as there are no imports from the `flipper` package anymore.
Don't forget to remove `flipper` from the `peerDependencies` in the `package.json` section if present. Don't forget to remove `flipper` from the `peerDependencies` in the `package.json` section if present.
Feel free to reach out to the Flipper team for any questions! Feel free to reach out to the Flipper team for any questions!

4
docs/extending/styling-components.mdx
View File

@@ -11,7 +11,7 @@ In general, custom styling should be needed rarily, as Ant Design provides a ver
To build plugin layout and data visualization Flipper ships with an additional set of components through the `flipper-plugin` package. To build plugin layout and data visualization Flipper ships with an additional set of components through the `flipper-plugin` package.
The list of available additional components can be found in the <Link to={useBaseUrl('/docs/extending/flipper-plugin#ui-components')}>API Reference</Link> and are further documented The list of available additional components can be found in the <Link to={useBaseUrl('/docs/extending/flipper-plugin#ui-components')}>API Reference</Link> and are further documented
in the Flipper Style Guide which can be found in Flipper under `View > Flipper style guide`. in [the style guide](style-guide.mdx).
In case you still need customly styled components, In case you still need customly styled components,
we are using [emotion](https://emotion.sh) to style our components. For more details on how this works, please refer to emotion's documentation. We heavily use their [Styled Components](https://emotion.sh/docs/styled) approach, which allows you to extend our and Ant's built-in components. we are using [emotion](https://emotion.sh) to style our components. For more details on how this works, please refer to emotion's documentation. We heavily use their [Styled Components](https://emotion.sh/docs/styled) approach, which allows you to extend our and Ant's built-in components.
@@ -81,7 +81,7 @@ Children can be matched by using normal CSS selectors. This makes it possible to
## Colors ## Colors
The `theme` module contains all standard colors used by Flipper. All available colors can be previewed by starting Flipper and opening `View > Flipper Style Guide`. The `theme` module contains all standard colors used by Flipper. All available colors can be previewed in [the style guide](style-guide.mdx).
The colors exposed here will handle dark mode automatically, so it is recommended to use those colors over hardcoded ones. The colors exposed here will handle dark mode automatically, so it is recommended to use those colors over hardcoded ones.
```javascript ```javascript

2
docs/tutorial/js-custom.mdx
View File

@@ -179,7 +179,7 @@ The assertions are provided by [Jest](https://jestjs.io/), and `toMatchInlineSna
So far, in `index.tsx`, our `Component` didn't do anything useful yet. Time to build some nice UI. So far, in `index.tsx`, our `Component` didn't do anything useful yet. Time to build some nice UI.
Flipper leverages Ant design, so any [official Ant component](https://ant.design/components/overview/) can be used in Flipper plugins. Flipper leverages Ant design, so any [official Ant component](https://ant.design/components/overview/) can be used in Flipper plugins.
The styling system used by Flipper can be found by starting Flipper, and opening `View > Flipper Style Guide`. The styling system used by Flipper can be found at [the style guide](../extending/style-guide.mdx).
The different `Layout` elements are documented there as well. The different `Layout` elements are documented there as well.
```tsx ```tsx