Add documentation

packages/interface/README.md

@@ -1,3 +1,77 @@
-# Interface
+# (Experimental) Interface
+
+The Interface Package contains the basis the start a modern WordPress screen as "core/edit-post" and "core/edit-site". The package offers a store and a set of components. The store is useful to contain common data required by a screen (e.g., active areas). The information is persisted across screen reloads. The components allow one to implement functionality like a sidebar and allow a screen to be extended by third-party plugins by default.
+
+
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/interface --save
+```
+
+_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
+
+
+### API Usage
+
+
+
+#### Store
+
+#### Single Active Area Functionality
+
+This functionality allows controlling which area is active in situations where just one area can be active at a given time.
+It can be used, for example, to control which modal is active or which sidebar is enabled.
+
+The API exposes a single action `setSingleActiveArea`, and a single selector `getSingleActiveArea`.
+
+The action `setSingleActiveArea` receives a scope and the area that should be active in a given scope or `undefined` if no area should be active (e.g., the area is closed.)
+
+The selector `getSingleActiveArea` receives the scope and returns the area that is active in that scope or `undefined` if no area is active.
+
+Bellow are some examples of the action and selector used together:
+```js
+wp.data.dispatch( 'core/interface' ).setSingleActiveArea( 'edit-site/complementary-area', 'edit-site/block-inspector'  );
+
+wp.data.select( 'core/interface' ).getSingleActiveArea( 'edit-site/complementary-area' ); -> "edit-site/block-inspector"
+
+wp.data.dispatch( 'core/interface' ).setSingleActiveArea( 'edit-site/complementary-area', 'edit-site/global-styles'  );
+
+wp.data.select( 'core/interface' ).getSingleActiveArea( 'edit-site/complementary-area' ); -> "edit-site/global-styles"
+
+wp.data.dispatch( 'core/interface' ).setSingleActiveArea( 'edit-site/complementary-area' );
+
+wp.data.select( 'core/interface' ).getSingleActiveArea( 'edit-site/complementary-area' ); -> undefined
+```
+
+#### Multiple Active Area Functionality
+
+This functionality allows controlling which areas are active in situations where multiple areas can be active at the same time.
+It can be used, for example, to control which panels are open are which items should appear in an area for favorites.
+
+Similar to the single active area the API exposes a single action `setMultipleActiveAreaEnableState`, and a single selector `isMultipleActiveAreaActive`.
+
+The action `setMultipleActiveAreaEnableState` receives a scope, the identifier of the area, and a boolean if true the are should be active if false the area should not be active.
+
+The selector `isMultipleActiveAreaActive` receives the scope, the identifier of the area, and returns true if an area is active and false otherwise.
+Bellow are some examples of the action and selector used together:
+```js
+wp.data.select( 'core/interface' ).isMultipleActiveAreaActive( 'edit-post/complementary-area', 'edit-post/block-patterns-sidebar' ); -> false
+
+wp.data.dispatch( 'core/interface' ).setMultipleActiveAreaEnableState( 'edit-post/complementary-area', 'edit-post/block-patterns-sidebar', true );
+
+wp.data.select( 'core/interface' ).isMultipleActiveAreaActive( 'edit-post/complementary-area', 'edit-post/block-patterns-sidebar' ); -> true
+```
+
+
+### Components
+
+Four components are exposed. The components are based on slot & fill paradigm two components are "fills" and two components are "slots".
+
+`ComplementaryArea` and `ComplementaryArea.Slot` form a slot fill pair to render complementary areas. Multiple `ComplementaryArea` components representing different complementary areas may be rendered at the same time, but only one appears on the slot depending on which complementary area is enabled.
+
+`PinnedItems` and `PinnedItems.Slot`form a slot fill pair to render pinned items or areas of "favorites". `ComplementaryArea` component makes use of `PinnedItems` and automatically adds a pinned item for the complementary areas marked as favorite.
 
-(Experimental) Interface Package

packages/interface/src/components/complementary-area/README.md

@@ -0,0 +1,115 @@
+ComplementaryArea
+=============================
+
+`ComplementaryArea` is a component to render complementary areas like sidebars. Its implementation is based on slot & fill.
+Multiple areas may be added in a given time, but only one is visible; the component renders the required artifacts to control which area is visible. The component allows, for example, to have multiple plugins rendering their sidebars, the user only sees one of the sidebars, but can switch which sidebar is active.
+
+The contents passed to ComplementaryArea are rendered in the ComplementaryArea.Slot corresponding to their scope if the complementary area is enabled.
+
+Besides rendering the complimentary area, the component renders a button in `PinnedItems` that allows opening the complementary area. The button only appears if the complementary is marked as favorite. By default, the complementary area headers rendered contain a button to mark and unmark areas as favorites.
+
+## Props
+
+### children
+
+The content to be displayed within the complementary area.
+
+- Type: `Element`
+- Required: Yes
+
+### closeLabel
+
+Label of the button that allows to close the complementary area.
+
+- Type: `String`
+- Required: No
+- Default: "Close plugin"
+
+### complementaryAreaIdentifier
+
+Identifier of the complementary area. The string is saved on the store and allows to identify which of the sidebars is active.
+
+- Type: `String`
+- Required: No
+- Default: Concatenation of `name` of the plugin extracted from the context (when available) with the "name" of the sidebar passed as a property.
+
+### header
+
+In cases where a custom header is desirable, the prop could be used. It can contain the contents that should be drawn on the header.
+
+- Type: `Element`
+- Required: No
+
+### headerClassName
+
+A className passed to the header container.
+
+- Type: `String`
+- Required: No
+
+### icon
+
+The icon to render.
+
+- Type: `Function|WPComponent|null`
+- Required: No
+- Default: `null`
+
+### name
+
+Name of the complementary area. The name of the complementarity area is concatenated with the name of the plugin to form the identifier of the complementary area. The name of the plugin is extracted from the plugin context where the sidebar is rendered. If there is no plugin context available or there is a need to specify a custom identifier, please use the `complementaryAreaIdentifier` property instead.
+
+- Type: `String`
+- Required: No
+
+### panelClassName
+
+A className passed to the panel that contains the contents of the sidebar.
+
+- Type: `String`
+- Required: No
+- Default: `null`
+
+### scope
+
+The scope of the complementary area e.g: "core/edit-post", "core/edit-site", "myplugin/custom-screen-a",
+
+- Type: `String`
+- Required: Yes
+
+### smallScreenTitle
+
+In small screens, the complementary area may take up the entire screen. 
+`smallScreenTitle` allows displaying a title above the complementary area, so the user is more aware of what the area refers to.
+
+- Type: `String`
+- Required: No
+
+### title
+
+Human friendly title of the complementary area.
+
+- Type: `String`
+- Required: Yes
+
+### toggleShortcut
+
+Keyboard shortcut that allows opening and closing the area. Passed to the button that allows the same action, so the user sees a visual indication that there is a keyboard shortcut.
+
+- Type: `String|Object`
+- Required: No
+
+ComplementaryArea.Slot
+=============================
+
+A slot that renders the currently active ComplementaryArea.
+
+## Props
+
+### scope
+
+The scope of the complementary area e.g: "core/edit-post", "core/edit-site", "myplugin/custom-screen-a",
+
+- Type: `String`
+- Required: Yes
+

packages/interface/src/components/pinned-items/README.md

@@ -0,0 +1,38 @@
+PinnedItems
+=============================
+
+There are situations where a screen has an area for favorites or pinned items.
+This Component allows adding items to that area. Most of the time, the Component should not be used directly as, for example, `ComplementaryArea` Component already renders PinnedItems that allow opening complementary areas marked as favorite.
+When used directly, items should not unconditionally add items should only be added if they are marked as "favorite" or verify other conditions.
+
+## Props
+
+### children
+
+The content to be displayed for the pinned items. Most of the time, a button with an icon should be used.
+
+- Type: `Element`
+- Required: Yes
+
+### scope
+
+The scope of the pinned items area e.g: "core/edit-post", "core/edit-site", "myplugin/custom-screen-a",
+
+- Type: `String`
+- Required: Yes
+
+PinnedItems.Slot
+=============================
+
+A slot that renders the pinned items.
+
+## Props
+
+### scope
+
+The scope of the pinned items area e.g: "core/edit-post", "core/edit-site", "myplugin/custom-screen-a",
+
+- Type: `String`
+- Required: Yes
+
+