Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

clarify intentions / purpose of different component folders in docs (https://github.com/woocommerce/woocommerce-blocks/pull/3025) 

* add high-level docs about our components & remove stale detail info

* use current collection/folder naming in docs:
- let's rename js/components in a separate PR
- split paragraphs on to separate lines to improve future diffs

* rename storybook.md => components.md and update link/summary

* tweak component collection docs:
- base have more stringent requirements, since they can be used anywhere
- editor components are less strict and can assume editor context

* clarify js/base/components readme in line with main doc

* remove line about editor components being specialised to woo blocks
This commit is contained in:
Rua Haszard 2020-08-27 08:15:16 +12:00 committed by GitHub
parent 96836fa117
commit 77aa2a33a3
5 changed files with 52 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
plugins/woocommerce-blocks/assets/js/base/components/README.md Normal file
View File

@ -0,0 +1,5 @@
# WooCommerce Blocks - General Purpose Components
These are shared components used in WooCommerce blocks, and may be used in the store front end (shopper experience) as well as the editor or admin dashboard.
See [_Components & Storybook_](docs/contributors/storybook.md) doc for more information.

45
plugins/woocommerce-blocks/assets/js/components/README.md
View File

@ -1,45 +1,8 @@
# Components
# WooCommerce Blocks - Editor Components
These are shared components used by the blocks. If there's a component that is more universally useful, it should go into [`@woocommerce/components`](https://github.com/woocommerce/woocommerce-admin/tree/master/packages/components)– these components are specific to the Gutenberg context.
These are shared components used in WooCommerce blocks for the editor (Gutenberg) UI.
The `*-control` components here are designed to exist in the `InspectorControls` sidebar, or in a Placeholder component for the "edit state" of a block.
Many of our blocks need rich, smart components to provide an interface for selecting or configuring blocks with WooCommerce data. Often there are multiple blocks that need such components. Components in this collection are used in multiple blocks, and may include logic for working with Woo data specifically (e.g. products, shipping methods, product categories).
## `GridContentControl`
See [_Components & Storybook_](docs/contributors/storybook.md) doc for more information.
A combination of toggle controls for content visibility in product grids.
## `GridLayoutControl`
A combination of range controls for product grid layout settings.
## `ProductOrderbyControl`
A pre-configured SelectControl for product orderby settings.
## `ProductAttributeTermControl`
A component using [`SearchListControl`](https://woocommerce.github.io/woocommerce-admin/#/components/packages/search-list-control) to show product attributes as selectable options. Only allows for selecting attribute terms from one attribute at a time (multiple terms can be selected).
## `ProductCategoryControl`
A component using [`SearchListControl`](https://woocommerce.github.io/woocommerce-admin/#/components/packages/search-list-control) to show product categories as selectable options. Options are displayed in hierarchy. Can select multiple categories.
## `ProductControl`
A component using [`SearchListControl`](https://woocommerce.github.io/woocommerce-admin/#/components/packages/search-list-control) to show products as selectable options. Only one product can be selected at a time.
## `ProductsControl`
A component using [`SearchListControl`](https://woocommerce.github.io/woocommerce-admin/#/components/packages/search-list-control) to show products as selectable options. Multiple products can be selected at once.
## Icons
These are a collection of custom icons used by the blocks or components, usually from Material.
## Utilities
There are some functions that work across components, these have been extracted into this utilities folder.
## Block Title
A block that is responsible for showing the title for some of our blocks.

2
plugins/woocommerce-blocks/docs/contributors/README.md
View File

@ -8,7 +8,7 @@ This folder contains documentation for developers and contributors looking to ge
| [Coding Guidelines](coding-guidelines.md) | This doc covers development best practices. |
| [Smoke Testing](smoke-testing.md) | This doc explains how to smoke test key Blocks functionality. |
| [JavaScript Testing](javascript-testing.md) | This doc explains how to run automated JavaScript tests. |
| [Component Testing & Development (with Storybook)](storybook.md) | This doc explains how to use Storybook to test and develop components in isolation. |
| [Developing Components (& Storybook)](components.md) | This doc outlines where our reusable components live, and how to test them in Storybook. |
| [Block Script Assets](block-assets.md) | This doc explains how Block Script Assets are loaded and used. |
| [JS build system](js-build-system.md) | This doc explains how JavaScript files are built. |
| [CSS build system](css-build-system.md) | This doc explains how CSS is built. |

42
plugins/woocommerce-blocks/docs/contributors/components.md Normal file
View File

@ -0,0 +1,42 @@
# Storybook & Components
This repo includes [Storybook](https://storybook.js.org) tooling so we can test and develop components in isolation.
The storybook is automatically built and published to [GitHub pages](https://woocommerce.github.io/woocommerce-gutenberg-products-block/) on every push to the main branch. See [travis.yml](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/.travis.yml) for details.
https://woocommerce.github.io/woocommerce-gutenberg-products-block/
## Where are our components?
We have components in a few folders, for different contexts.
- [`assets/js/base/components`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/main/assets/js/base/components)
- [`assets/js/components`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/main/assets/js/components)
- [`assets/js/icons`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/main/assets/js/icons)
__`assets/js/base/components`__ are used in front-end code, as well as editor & admin.
These components help us build consistent interfaces across the front end (shopper) experience and elsewhere.
Because they can be used in the front end and editor, components in this folder should:
- Perform efficiently - i.e. not adversely affect page performance/experience.
- Have lean dependencies - i.e. not bloat the payload unnecessarily.
- Look consistent in common themes; ideally should allow themes to adjust appearance as necessary.
__`assets/js/components`__ are used in the editor UI for our blocks.
They allow us to build a consistent and powerful UI for merchants for authoring content relating to Woo data - e.g. selecting products or product attributes. Because they are focused on the editor, they can rely on known editor dependencies and optimise styling for the editor only.
__`assets/js/icons`__ is a suite of icons and SVG images that we use in our interfaces.
For more info about individual components, refer to [Storybook](https://woocommerce.github.io/woocommerce-gutenberg-products-block/) or individual readme files.
## How to run Storybook locally and test components
- `npm run storybook`
- Point your browser at port 6006, e.g. http://localhost:6006
- Play with components 🎛!
## How to add a story for a component
- Add a `stories` folder alongside the component.
- Add stories in `.js` files in this folder.
If you're stuck, copy source of an existing story to get started.

20
plugins/woocommerce-blocks/docs/contributors/storybook.md
View File

@ -1,20 +0,0 @@
# Storybook
This repo includes [Storybook](https://storybook.js.org) tooling so we can test and develop components in isolation.
The storybook is automatically built and published to [GitHub pages](https://woocommerce.github.io/woocommerce-gutenberg-products-block/) on every push to the main branch. See [travis.yml](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/.travis.yml) for details.
https://woocommerce.github.io/woocommerce-gutenberg-products-block/
## How to run Storybook locally and test components
- `npm run storybook`
- Point your browser at port 6006, e.g. http://localhost:6006
- Play with components 🎛!
## How to add a story for a component
- Add a `stories` folder alongside the component.
- Add stories in `.js` files in this folder.
If you're stuck, copy source of an existing story to get started.