From 32a75ecb587d7a00822fa821b6c4d411d5cf9043 Mon Sep 17 00:00:00 2001 From: Michel Weststrate Date: Wed, 16 Dec 2020 05:51:23 -0800 Subject: [PATCH] Restructure extending docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Summary: This diff restructures the 'extending' section of the docs, and rebrands it to 'creating plugins'. It then restructures this section into 4 top-level items * Tutorial * Desktop plugin APIs * Client plugin APIs * Workflow Pages are put under the relevant sections, including pages which were before under internal. Some pages that didn't relate directly to plugin development have been moved to other top level sections (e.g. testing RN). I didn't do de-duplication between pages yet, that will be done in the next diff. Overview of changes: * Extending -> Creating Plugins * Moved Extending > Other platforms to Setup > Other platforms (as this is about clients, not plugins) * Moved Internal FB plugin development stuff into Creating Plugins * Separated Creating Plugins into ‘Tutorial’, Desktop API Reference, Cient API Reference, Workflow * Remove TypeScript strict page, we are already strict * Moved QPL linters to api docs and named id QPL lints * Grouped the different pages on extending Layout plugin (needs deduping still) * Warning about avoiding custom styling in general * Moved internal index page to the top of the navigation of FB Internal, rather than at the bottom Reviewed By: passy Differential Revision: D25585172 fbshipit-source-id: ba2aa891395097d6aa101809084b915f115ee69d --- docs/extending/create-table-plugin.mdx | 7 ++ docs/extending/styling-components.mdx | 34 ++++++--- website/docusaurus.config.js | 2 +- website/sidebars.js | 95 ++++++++++++++------------ 4 files changed, 84 insertions(+), 54 deletions(-) diff --git a/docs/extending/create-table-plugin.mdx b/docs/extending/create-table-plugin.mdx index 5a5fe12dd..88b7b0274 100644 --- a/docs/extending/create-table-plugin.mdx +++ b/docs/extending/create-table-plugin.mdx @@ -3,6 +3,13 @@ id: create-table-plugin title: Create Table Plugin --- +
+ +The following mechanism isn't supported yet by the Sandy plugin architecture. +Please remove `flipper-plugin` from the plugin dependencies if you want to use `createTablePlugin`. + +
+ A very common kind of Flipper plugin is a plugin which fetches some structured data from the device and presents it in a table. To make building these kinds of plugins as easy as possible we have created an abstraction we call `createTablePlugin`. This is a function which manages the complexities of building a table plugin but still allows you to customize many things to suite your needs. diff --git a/docs/extending/styling-components.mdx b/docs/extending/styling-components.mdx index 43a1aa979..861ce5451 100644 --- a/docs/extending/styling-components.mdx +++ b/docs/extending/styling-components.mdx @@ -3,7 +3,18 @@ id: styling-components title: Styling 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 built-in components. +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Link from '@docusaurus/Link'; + +Flipper ships with its own design system which is based on [Ant Design](https://ant.design/). +In general, custom styling should be needed rarily, as Ant Design provides a very extensive set of [components](https://ant.design/components/overview/). + +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 compoents can be found in the API Reference and are further documented +in the Flipper Style Guide which can be found in Flipper under `View > Flipper style guide`. + +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. ## Basic tags @@ -23,7 +34,8 @@ const MyInput = styled.input({ ... }); ## Extending Flipper Components -It's very common for components to require customizing Flipper's components in some way. For example changing colors, alignment, or wrapping behavior. Flippers components can be wrapped using the `styled` function which allows adding or overwriting existing style rules. +In some cases it is required to customize Ant or Flipper's components in some way. For example changing colors, alignment, or wrapping behavior. +Flippers components can be wrapped using the `styled` function which allows adding or overwriting existing style rules. ```javascript import {Layout, styled} from 'flipper-plugin'; @@ -32,10 +44,8 @@ const Container = styled(Layout.Container)({ alignItems: 'center', }); -class MyComponent extends Component { - render() { - return ...; - } +function MyComponent { + return ...; } ``` @@ -49,7 +59,7 @@ The style object can also be returned from a function for dynamic values. Props const MyView = styled.div( props => ({ fontSize: 10, - color: => (props.disabled ? colors.red : colors.black), + color: => (props.disabled ? 'red' : 'black'), }) ); @@ -60,7 +70,13 @@ const MyView = styled.div( Pseudo-classes can be used like this: ```javascript -'&:hover': {color: colors.red}` +'&:hover': {color: 'red'}` +``` + +Children can be matched by using normal CSS selectors. This makes it possible to customize Ant components as well: + +```javascript +'.ant-btn-primary': {color: 'yellow'} ``` ## Colors @@ -69,5 +85,5 @@ The `theme` module contains all standard colors used by Flipper. All available c The colors exposed here will handle dark mode automatically, so it is recommended to use those colors over hardcoded ones. ```javascript -import {theme} from 'flipper' +import {theme} from 'flipper-plugin' ``` diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index e7e688676..af954a82a 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -42,7 +42,7 @@ const siteConfig = { }, { to: 'docs/tutorial/intro', - label: 'Extending', + label: 'Creating Plugins', position: 'right', }, { diff --git a/website/sidebars.js b/website/sidebars.js index 9e12fe20a..38b965c6a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -7,7 +7,7 @@ * @format */ -const {fbContent, fbInternalOnly} = require('internaldocs-fb-helpers'); +const {fbInternalOnly} = require('internaldocs-fb-helpers'); module.exports = { features: { @@ -46,6 +46,13 @@ module.exports = { 'getting-started/react-native-android', 'getting-started/react-native-ios', 'troubleshooting', + { + 'Other Platforms': [ + 'extending/new-clients', + 'extending/establishing-a-connection', + 'extending/supporting-layout', + ], + }, ], 'Plugin Setup': [ 'setup/layout-plugin', @@ -71,70 +78,70 @@ module.exports = { 'tutorial/js-custom', 'tutorial/js-publishing', ], - 'Plugin Development': [ - 'extending/js-setup', + 'Desktop plugin APIs': [ 'extending/flipper-plugin', - 'extending/create-table-plugin', 'extending/styling-components', + 'extending/create-table-plugin', 'extending/search-and-filter', + fbInternalOnly({ + 'QPL linting': ['fb/building-a-linter', 'fb/active-linters'], + }), + { + 'Deprecated APIs': [ + 'extending/ui-components', + 'extending/js-plugin-api', + ], + }, + ], + 'Client plugin APIs': [ 'extending/create-plugin', - 'extending/client-plugin-lifecycle', 'extending/send-data', 'extending/error-handling', 'extending/testing', - 'extending/debugging', - ...fbInternalOnly(['extending/fb/desktop-plugin-releases']), - ], - 'Deprecated APIs': ['extending/ui-components', 'extending/js-plugin-api'], - // end-internal-sidebars-example - 'Other Platforms': [ - 'extending/new-clients', - 'extending/establishing-a-connection', - 'extending/supporting-layout', - ], - Internals: [ 'extending/arch', + 'extending/client-plugin-lifecycle', 'extending/layout-inspector', - 'extending/testing-rn', - 'extending/public-releases', + ...fbInternalOnly([ + { + Android: [ + 'fb/android-plugin-development-Android-interacting-0', + 'fb/android-plugin-development-testing-android-plugins-0', + ], + }, + { + iOS: [ + 'fb/ios-plugin-development-sending-data-to-an-ios-plugin-0', + 'fb/ios-plugin-development-testing-ios-plugins-0', + ], + }, + ]), + ], + Workflow: [ + 'extending/js-setup', + 'extending/debugging', + ...fbInternalOnly([ + 'extending/fb/desktop-plugin-releases', + 'fb/developmentworkflow', + 'fb/TypeScript', + 'fb/adding-npm-dependencies-0', + 'fb/adding-analytics-0', + ]), ], }, 'fb-internal': { 'FB Internal': fbInternalOnly([ + 'fb/index', + 'extending/public-releases', 'fb/release-infra', 'fb/LauncherConfig', 'fb/Flipper-fbsource-Pinning', 'fb/Flipper-Release-Cycle', - 'fb/Flipper-Strict-TypeScript', + 'fb/Add-Support-Group-to-Flipper-Support-Form', 'fb/Help-Updating-Flipper', + 'extending/testing-rn', { 'Internal Plugins': ['fb/plugins'], }, - { - 'Plugin Development': [ - 'fb/developmentworkflow', - 'fb/TypeScript', - 'fb/adding-npm-dependencies-0', - 'fb/adding-analytics-0', - { - Android: [ - 'fb/android-plugin-development-Android-interacting-0', - 'fb/android-plugin-development-testing-android-plugins-0', - ], - }, - { - iOS: [ - 'fb/ios-plugin-development-sending-data-to-an-ios-plugin-0', - 'fb/ios-plugin-development-testing-ios-plugins-0', - ], - }, - 'fb/Add-Support-Group-to-Flipper-Support-Form', - ], - }, - { - Lints: ['fb/building-a-linter', 'fb/active-linters'], - }, - 'fb/index', ]), }, };