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

Fetch component usage documentation from local README.md. 

Format documentation like Calypso, include usage section.
This commit is contained in:
Jeff Stieler 2019-08-29 14:41:21 -07:00
parent 134f472484
commit a0efb6967f
94 changed files with 1918 additions and 3170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
plugins/woocommerce-admin/client/devdocs/docs.js
View File

@ -4,9 +4,19 @@
*/
import { Component } from '@wordpress/element';
import marked from 'marked';
import { Parser } from 'html-to-react';
import Prism from 'prismjs';
import 'prismjs/components/prism-jsx';
const htmlToReactParser = new Parser();
// Alias `javascript` language to `es6`
Prism.languages.es6 = Prism.languages.javascript;
// Configure marked to use Prism for code-block highlighting.
marked.setOptions( {
highlight: function( code, language ) {
const syntax = Prism.languages[ language ];
return syntax ? Prism.highlight( code, syntax ) : code;
},
} );
class Docs extends Component {
state = {
@ -18,15 +28,14 @@ class Docs extends Component {
}
getReadme() {
const { filePath, docPath } = this.props;
const readme = require( `../../docs/components/${ docPath }/${ filePath }.md` );
const { filePath } = this.props;
const readme = require( `../../packages/components/src/${ filePath }/README.md` );
if ( ! readme ) {
return;
}
const html = marked( readme );
this.setState( {
readme: htmlToReactParser.parse( html ),
} );
this.setState( { readme } );
}
render() {
@ -34,12 +43,14 @@ class Docs extends Component {
if ( ! readme ) {
return null;
}
return <div className="woocommerce-devdocs__docs">{ readme }</div>;
return (
<div
className="woocommerce-devdocs__docs"
//eslint-disable-next-line react/no-danger
dangerouslySetInnerHTML={ { __html: marked( readme ) } }
/>
);
}
}
Docs.defaultProps = {
docPath: 'packages',
};
export default Docs;

4
plugins/woocommerce-admin/client/devdocs/examples.json
View File

@ -2,7 +2,7 @@
{ "component": "AdvancedFilters" },
{ "component": "AnimationSlider" },
{ "component": "Autocomplete" },
{ "component": "Calendar", "render": "MyDateRange" },
{ "component": "Calendar" },
{ "component": "Card" },
{ "component": "Chart" },
{ "component": "CompareFilter" },
@ -31,7 +31,7 @@
{ "component": "Spinner" },
{ "component": "SplitButton" },
{ "component": "Stepper" },
{ "component": "Summary", "render": "MySummaryList" },
{ "component": "Summary" },
{ "component": "Table" },
{ "component": "Tag" },
{ "component": "TextControlWithAffixes" },

6
plugins/woocommerce-admin/client/devdocs/index.js
View File

@ -22,12 +22,10 @@ const camelCaseToSlug = name => {
const getExampleData = example => {
const componentName = get( example, 'component' );
const filePath = get( example, 'filePath', camelCaseToSlug( componentName ) );
const render = get( example, 'render', `My${ componentName }` );
return {
componentName,
filePath,
render,
};
};
@ -48,7 +46,7 @@ export default class extends Component {
return (
<div className={ className }>
{ exampleList.map( example => {
const { componentName, filePath, render, docPath } = getExampleData( example );
const { componentName, filePath } = getExampleData( example );
const cardClasses = classnames(
'woocommerce-devdocs__card',
`woocommerce-devdocs__card--${ filePath }`,
@ -83,7 +81,6 @@ export default class extends Component {
asyncName={ componentName }
component={ componentName }
filePath={ filePath }
render={ render }
/>
</Card>
{ component && (
@ -91,7 +88,6 @@ export default class extends Component {
key={ `${ componentName }-readme` }
componentName={ componentName }
filePath={ filePath }
docPath={ docPath }
/>
) }
</Fragment>

45
plugins/woocommerce-admin/client/devdocs/style.scss
View File

@ -36,10 +36,14 @@
linear-gradient(90deg, rgba($core-grey-dark-800, 0.025) 1px, transparent 1px);
background-size: 32px 32px, 32px 32px, 8px 8px, 8px 8px;
background-position: -1px -1px, -1px -1px, -1px -1px, -1px -1px;
.woocommerce-chart {
margin: 0;
}
}
.woocommerce-devdocs__docs {
max-width: 600px;
max-width: 720px;
margin: 0 auto;
padding: $gap;
@ -54,5 +58,44 @@
h4 code {
font-size: 0.9em;
}
table {
border-collapse: collapse;
border-spacing: 0;
th,
td {
border-bottom: 1px solid $core-grey-light-700;
text-align: left;
}
th {
padding: 0.25em 3em 0.25em 0;
}
td {
padding: 1.17em 3em 1.17em 0;
}
}
// From wp-calypso: client/devdocs/style.scss
pre {
padding: 8px;
background: $white;
background-color: $white;
}
code {
background-color: $white;
border-radius: 3px;
font-size: 15px;
padding: 2px 6px;
max-width: 100px;
}
pre > code {
background-color: $transparent;
padding: 2px 0;
}
}
}

2
plugins/woocommerce-admin/client/stylesheets/abstracts/_colors.scss
View File

@ -2,6 +2,8 @@
@import 'node_modules/@automattic/color-studio/dist/color-variables.scss';
$transparent: rgba(255, 255, 255, 0);
// Greys
$core-grey-light-100: #f8f9f9;
$core-grey-light-200: #f3f4f5;

101
plugins/woocommerce-admin/docs/components/analytics/report-chart.md
View File

@ -1,100 +1,41 @@
`ReportChart` (component)
=========================
ReportChart
===
Component that renders the chart in reports.
Props
-----
## Usage
### `filters`
```jsx
```
- Type: Array
- Default: null
### Props
Filters available for that report.
### `isRequesting`
- Type: Boolean
- Default: `false`
Whether there is an API call running.
### `itemsLabel`
- Type: String
- Default: null
Label describing the legend items.
### `limitProperties`
- Type: Array
- Default: null
Allows specifying properties different from the `endpoint` that will be used
to limit the items when there is an active search.
### `mode`
- Type: String
- Default: null
`items-comparison` (default) or `time-comparison`, this is used to generate correct
ARIA properties.
### `path`
- **Required**
- Type: String
- Default: null
Current path
### `primaryData`
- Type: Object
- Default: `{
Name | Type | Default | Description
--- | --- | --- | ---
`filters` | Array | ``null`` | Filters available for that report
`isRequesting` | Boolean | ``false`` | Whether there is an API call running
`itemsLabel` | String | ``null`` | Label describing the legend items
`limitProperties` | Array | ``null`` | Allows specifying properties different from the `endpoint` that will be used to limit the items when there is an active search
`mode` | String | ``null`` | `items-comparison` (default) or `time-comparison`, this is used to generate correct ARIA properties
`path` | String | ``null`` | (required) Current path
`primaryData` | Object | ``{
data: {
intervals: [],
},
isError: false,
isRequesting: false,
}`
Primary data to display in the chart.
### `query`
- **Required**
- Type: Object
- Default: null
The query string represented in object form.
### `secondaryData`
- Type: Object
- Default: `{
}`` | Primary data to display in the chart
`query` | Object | ``null`` | (required) The query string represented in object form
`secondaryData` | Object | ``{
data: {
intervals: [],
},
isError: false,
isRequesting: false,
}`
Secondary data to display in the chart.
### `selectedChart`
- **Required**
- Type: Object
}`` | Secondary data to display in the chart
`selectedChart` | Object
- key: String - Key of the selected chart.
- label: String - Chart label.
- order: One of: 'asc', 'desc'
- orderby: String - Order by query argument.
- type: One of: 'average', 'number', 'currency'
- Default: null
Properties of the selected chart.
- type: One of: 'average', 'number', 'currency' | ``null`` | (required) Properties of the selected chart

34
plugins/woocommerce-admin/docs/components/analytics/report-error.md
View File

@ -1,30 +1,18 @@
`ReportError` (component)
=========================
ReportError
===
Component to render when there is an error in a report component due to data
not being loaded or being invalid.
Props
-----
## Usage
### `className`
```jsx
```
- Type: String
- Default: `''`
Additional class name to style the component.
### `isError`
- Type: Boolean
- Default: null
Boolean representing whether there was an error.
### `isEmpty`
- Type: Boolean
- Default: null
Boolean representing whether the issue is that there is no data.
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | ``''`` | Additional class name to style the component
`isError` | Boolean | ``null`` | Boolean representing whether there was an error
`isEmpty` | Boolean | ``null`` | Boolean representing whether the issue is that there is no data

86
plugins/woocommerce-admin/docs/components/analytics/report-summary.md
View File

@ -1,84 +1,34 @@
`ReportSummary` (component)
===========================
ReportSummary
===
Component to render summary numbers in reports.
Props
-----
## Usage
### `charts`
```jsx
```
- **Required**
- Type: Array
- Default: null
### Props
Properties of all the charts available for that report.
### `endpoint`
- **Required**
- Type: String
- Default: null
The endpoint to use in API calls to populate the Summary Numbers.
For example, if `taxes` is provided, data will be fetched from the report
`taxes` endpoint (ie: `/wc/v4/reports/taxes/stats`). If the provided endpoint
doesn't exist, an error will be shown to the user with `ReportError`.
### `limitProperties`
- Type: Array
- Default: null
Allows specifying properties different from the `endpoint` that will be used
to limit the items when there is an active search.
### `query`
- **Required**
- Type: Object
- Default: null
The query string represented in object form.
### `isRequesting`
- Type: Boolean
- Default: null
Whether there is an API call running.
### `selectedChart`
- **Required**
- Type: Object
Name | Type | Default | Description
--- | --- | --- | ---
`charts` | Array | ``null`` | (required) Properties of all the charts available for that report
`endpoint` | String | ``null`` | (required) The endpoint to use in API calls to populate the Summary Numbers. For example, if `taxes` is provided, data will be fetched from the report `taxes` endpoint (ie: `/wc/v4/reports/taxes/stats`). If the provided endpoint doesn't exist, an error will be shown to the user with `ReportError`
`limitProperties` | Array | ``null`` | Allows specifying properties different from the `endpoint` that will be used to limit the items when there is an active search
`query` | Object | ``null`` | (required) The query string represented in object form
`isRequesting` | Boolean | ``null`` | Whether there is an API call running
`selectedChart` | Object
- key: String - Key of the selected chart.
- label: String - Chart label.
- order: One of: 'asc', 'desc'
- orderby: String - Order by query argument.
- type: One of: 'average', 'number', 'currency'
- Default: null
Properties of the selected chart.
### `summaryData`
- Type: Object
- Default: `{
- type: One of: 'average', 'number', 'currency' | ``null`` | (required) Properties of the selected chart
`summaryData` | Object | ``{
totals: {
primary: {},
secondary: {},
},
isError: false,
isRequesting: false,
}`
Data to display in the SummaryNumbers.
### `report`
- Type: String
- Default: null
Report name, if different than the endpoint.
}`` | Data to display in the SummaryNumbers
`report` | String | ``null`` | Report name, if different than the endpoint

113
plugins/woocommerce-admin/docs/components/analytics/report-table.md
View File

@ -1,105 +1,34 @@
`ReportTable` (component)
=========================
ReportTable
===
Component that extends `TableCard` to facilitate its usage in reports.
Props
-----
## Usage
### `columnPrefsKey`
```jsx
```
- Type: String
- Default: null
### Props
The key for user preferences settings for column visibility.
### `endpoint`
- Type: String
- Default: null
The endpoint to use in API calls to populate the table rows and summary.
For example, if `taxes` is provided, data will be fetched from the report
`taxes` endpoint (ie: `/wc/v4/reports/taxes` and `/wc/v4/reports/taxes/stats`).
If the provided endpoint doesn't exist, an error will be shown to the user
with `ReportError`.
### `extendItemsMethodNames`
- Type: Object
Name | Type | Default | Description
--- | --- | --- | ---
`columnPrefsKey` | String | ``null`` | The key for user preferences settings for column visibility
`endpoint` | String | ``null`` | The endpoint to use in API calls to populate the table rows and summary. For example, if `taxes` is provided, data will be fetched from the report `taxes` endpoint (ie: `/wc/v4/reports/taxes` and `/wc/v4/reports/taxes/stats`). If the provided endpoint doesn't exist, an error will be shown to the user with `ReportError`
`extendItemsMethodNames` | Object
- getError: String
- isRequesting: String
- load: String
- Default: null
Name of the methods available via `select( 'wc-api' )` that will be used to
load more data for table items. If omitted, no call will be made and only
the data returned by the reports endpoint will be used.
### `getHeadersContent`
- **Required**
- Type: Function
- Default: null
A function that returns the headers object to build the table.
### `getRowsContent`
- **Required**
- Type: Function
- Default: null
A function that returns the rows array to build the table.
### `getSummary`
- Type: Function
- Default: null
A function that returns the summary object to build the table.
### `itemIdField`
- Type: String
- Default: null
The name of the property in the item object which contains the id.
### `primaryData`
- Type: Object
- Default: `{}`
Primary data of that report. If it's not provided, it will be automatically
loaded via the provided `endpoint`.
### `tableData`
- Type: Object
- Default: `{
- load: String | ``null`` | Name of the methods available via `select( 'wc-api' )` that will be used to load more data for table items. If omitted, no call will be made and only the data returned by the reports endpoint will be used
`getHeadersContent` | Function | ``null`` | (required) A function that returns the headers object to build the table
`getRowsContent` | Function | ``null`` | (required) A function that returns the rows array to build the table
`getSummary` | Function | ``null`` | A function that returns the summary object to build the table
`itemIdField` | String | ``null`` | The name of the property in the item object which contains the id
`primaryData` | Object | ``{}`` | Primary data of that report. If it's not provided, it will be automatically loaded via the provided `endpoint`
`tableData` | Object | ``{
items: {
data: [],
totalResults: 0,
},
query: {},
}`
Table data of that report. If it's not provided, it will be automatically
loaded via the provided `endpoint`.
### `tableQuery`
- Type: Object
- Default: `{}`
Properties to be added to the query sent to the report table endpoint.
### `title`
- **Required**
- Type: String
- Default: null
String to display as the title of the table.
}`` | Table data of that report. If it's not provided, it will be automatically loaded via the provided `endpoint`
`tableQuery` | Object | ``{}`` | Properties to be added to the query sent to the report table endpoint
`title` | String | ``null`` | (required) String to display as the title of the table

49
plugins/woocommerce-admin/docs/components/packages/advanced-filters.md
View File

@ -1,49 +0,0 @@
`AdvancedFilters` (component)
=============================
Displays a configurable set of filters which can modify query parameters.
Props
-----
### `config`
- **Required**
- Type: Object
- title: String
- filters: Object
- labels: Object
- add: String
- remove: String
- rule: String
- title: String
- filter: String
- rules: Array
Object
- input: Object
- Default: null
The configuration object required to render filters.
### `path`
- **Required**
- Type: String
- Default: null
Name of this filter, used in translations.
### `query`
- Type: Object
- Default: `{}`
The query string represented in object form.
### `onAdvancedFilterAction`
- Type: Function
- Default: `() => {}`
Function to be called after an advanced filter action has been taken.

39
plugins/woocommerce-admin/docs/components/packages/animation-slider.md
View File

@ -1,39 +0,0 @@
`AnimationSlider` (component)
=============================
This component creates slideable content controlled by an animate prop to direct the contents to slide left or right.
All other props are passed to `CSSTransition`. More info at http://reactcommunity.org/react-transition-group/css-transition
Props
-----
### `children`
- **Required**
- Type: Function
- Default: null
A function returning rendered content with argument status, reflecting `CSSTransition` status.
### `animationKey`
- **Required**
- Type: *
- Default: null
A unique identifier for each slideable page.
### `animate`
- Type: One of: null, 'left', 'right'
- Default: null
null, 'left', 'right', to designate which direction to slide on a change.
### `onExited`
- Type: Function
- Default: null
A function to be executed after a transition is complete, passing the containing ref as the argument.

141
plugins/woocommerce-admin/docs/components/packages/autocomplete.md
View File

@ -1,141 +0,0 @@
`Autocomplete` (component)
==========================
A search box which filters options while typing,
allowing a user to select from an option from a filtered list.
Props
-----
### `className`
- Type: String
- Default: null
Class name applied to parent div.
### `excludeSelectedOptions`
- Type: Boolean
- Default: `true`
Exclude already selected options from the options list.
### `onFilter`
- Type: Function
- Default: `identity`
Add or remove items to the list of options after filtering,
passed the array of filtered options and should return an array of options.
### `getSearchExpression`
- Type: Function
- Default: `identity`
Function to add regex expression to the filter the results, passed the search query.
### `help`
- Type: One of type: string, node
- Default: null
Help text to be appended beneath the input.
### `inlineTags`
- Type: Boolean
- Default: `false`
Render tags inside input, otherwise render below input.
### `label`
- Type: String
- Default: null
A label to use for the main input.
### `onChange`
- Type: Function
- Default: `noop`
Function called when selected results change, passed result list.
### `onSearch`
- Type: Function
- Default: `noop`
Function to run after the search query is updated, passed the search query.
### `options`
- **Required**
- Type: Array
- isDisabled: Boolean
- key: One of type: number, string
- keywords: Array
String
- label: String
- value: *
- Default: null
An array of objects for the options list. The option along with its key, label and
value will be returned in the onChange event.
### `placeholder`
- Type: String
- Default: null
A placeholder for the search input.
### `selected`
- Type: Array
- key: One of type: number, string
- label: String
- Default: `[]`
An array of objects describing selected values. If the label of the selected
value is omitted, the Tag of that value will not be rendered inside the
search box.
### `maxResults`
- Type: Number
- Default: `0`
A limit for the number of results shown in the options menu. Set to 0 for no limit.
### `multiple`
- Type: Boolean
- Default: `false`
Allow multiple option selections.
### `showClearButton`
- Type: Boolean
- Default: `false`
Render a 'Clear' button next to the input box to remove its contents.
### `hideBeforeSearch`
- Type: Boolean
- Default: `false`
Only show list options after typing a search query.
### `staticList`
- Type: Boolean
- Default: `false`
Render results list positioned statically instead of absolutely.

139
plugins/woocommerce-admin/docs/components/packages/calendar.md
View File

@ -1,139 +0,0 @@
`DatePicker` (component)
========================
Props
-----
### `date`
- Type: Object
- Default: null
A moment date object representing the selected date. `null` for no selection.
### `disabled`
- Type: Boolean
- Default: null
Whether the input is disabled.
### `text`
- Type: String
- Default: null
The date in human-readable format. Displayed in the text input.
### `error`
- Type: String
- Default: null
A string error message, shown to the user.
### `onUpdate`
- **Required**
- Type: Function
- Default: null
A function called upon selection of a date or input change.
### `dateFormat`
- **Required**
- Type: String
- Default: null
The date format in moment.js-style tokens.
### `isInvalidDate`
- Type: Function
- Default: null
A function to determine if a day on the calendar is not valid
`DateRange` (component)
=======================
This is wrapper for a [react-dates](https://github.com/airbnb/react-dates) powered calendar.
Props
-----
### `after`
- Type: Object
- Default: null
A moment date object representing the selected start. `null` for no selection.
### `afterError`
- Type: String
- Default: null
A string error message, shown to the user.
### `afterText`
- Type: String
- Default: null
The start date in human-readable format. Displayed in the text input.
### `before`
- Type: Object
- Default: null
A moment date object representing the selected end. `null` for no selection.
### `beforeError`
- Type: String
- Default: null
A string error message, shown to the user.
### `beforeText`
- Type: String
- Default: null
The end date in human-readable format. Displayed in the text input.
### `focusedInput`
- Type: String
- Default: null
String identifying which is the currently focused input (start or end).
### `isInvalidDate`
- Type: Function
- Default: null
A function to determine if a day on the calendar is not valid
### `onUpdate`
- **Required**
- Type: Function
- Default: null
A function called upon selection of a date.
### `shortDateFormat`
- **Required**
- Type: String
- Default: null
The date format in moment.js-style tokens.

50
plugins/woocommerce-admin/docs/components/packages/card.md
View File

@ -1,50 +0,0 @@
`Card` (component)
==================
A basic card component with a header. The header can contain a title, an action, and an `EllipsisMenu` menu.
Props
-----
### `action`
- Type: ReactNode
- Default: null
One "primary" action for this card, appears in the card header.
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `description`
- Type: One of type: string, node
- Default: null
The description displayed beneath the title.
### `isInactive`
- Type: Boolean
- Default: null
Boolean representing whether the card is inactive or not.
### `menu`
- Type: (custom validator)
- Default: null
An `EllipsisMenu`, with filters used to control the content visible in this card
### `title`
- Type: One of type: string, node
- Default: null
The title to use for this card.

224
plugins/woocommerce-admin/docs/components/packages/chart.md
View File

@ -1,224 +0,0 @@
`Chart` (component)
===================
A chart container using d3, to display timeseries data with an interactive legend.
Props
-----
### `allowedIntervals`
- Type: Array
- Default: null
Allowed intervals to show in a dropdown.
### `baseValue`
- Type: Number
- Default: `0`
Base chart value. If no data value is different than the baseValue, the
`emptyMessage` will be displayed if provided.
### `chartType`
- Type: One of: 'bar', 'line'
- Default: `'line'`
Chart type of either `line` or `bar`.
### `data`
- Type: Array
- Default: `[]`
An array of data.
### `dateParser`
- Type: String
- Default: `'%Y-%m-%dT%H:%M:%S'`
Format to parse dates into d3 time format
### `emptyMessage`
- Type: String
- Default: null
The message to be displayed if there is no data to render. If no message is provided,
nothing will be displayed.
### `filterParam`
- Type: String
- Default: null
Name of the param used to filter items. If specified, it will be used, in combination
with query, to detect which elements are being used by the current filter and must be
displayed even if their value is 0.
### `itemsLabel`
- Type: String
- Default: null
Label describing the legend items.
### `mode`
- Type: One of: 'item-comparison', 'time-comparison'
- Default: `'time-comparison'`
`item-comparison` (default) or `time-comparison`, this is used to generate correct
ARIA properties.
### `path`
- Type: String
- Default: null
Current path
### `query`
- Type: Object
- Default: null
The query string represented in object form
### `interactiveLegend`
- Type: Boolean
- Default: `true`
Whether the legend items can be activated/deactivated.
### `interval`
- Type: One of: 'hour', 'day', 'week', 'month', 'quarter', 'year'
- Default: `'day'`
Interval specification (hourly, daily, weekly etc).
### `intervalData`
- Type: Object
- Default: null
Information about the currently selected interval, and set of allowed intervals for the chart. See `getIntervalsForQuery`.
### `isRequesting`
- Type: Boolean
- Default: `false`
Render a chart placeholder to signify an in-flight data request.
### `legendPosition`
- Type: One of: 'bottom', 'side', 'top'
- Default: null
Position the legend must be displayed in. If it's not defined, it's calculated
depending on the viewport width and the mode.
### `legendTotals`
- Type: Object
- Default: null
Values to overwrite the legend totals. If not defined, the sum of all line values will be used.
### `screenReaderFormat`
- Type: One of type: string, func
- Default: `'%B %-d, %Y'`
A datetime formatting string or overriding function to format the screen reader labels.
### `showHeaderControls`
- Type: Boolean
- Default: `true`
Wether header UI controls must be displayed.
### `title`
- Type: String
- Default: null
A title describing this chart.
### `tooltipLabelFormat`
- Type: One of type: string, func
- Default: `'%B %-d, %Y'`
A datetime formatting string or overriding function to format the tooltip label.
### `tooltipValueFormat`
- Type: One of type: string, func
- Default: `','`
A number formatting string or function to format the value displayed in the tooltips.
### `tooltipTitle`
- Type: String
- Default: null
A string to use as a title for the tooltip. Takes preference over `tooltipLabelFormat`.
### `valueType`
- Type: String
- Default: null
What type of data is to be displayed? Number, Average, String?
### `xFormat`
- Type: String
- Default: `'%d'`
A datetime formatting string, passed to d3TimeFormat.
### `x2Format`
- Type: String
- Default: `'%b %Y'`
A datetime formatting string, passed to d3TimeFormat.
### `yBelow1Format`
- Type: String
- Default: null
A number formatting string, passed to d3Format.
### `yFormat`
- Type: String
- Default: null
A number formatting string, passed to d3Format.
`ChartPlaceholder` (component)
==============================
`ChartPlaceholder` displays a large loading indiciator for use in place of a `Chart` while data is loading.
Props
-----
### `height`
- Type: Number
- Default: `0`

57
plugins/woocommerce-admin/docs/components/packages/compare-filter.md
View File

@ -1,57 +0,0 @@
`CompareFilter` (component)
===========================
Displays a card + search used to filter results as a comparison between objects.
Props
-----
### `getLabels`
- **Required**
- Type: Function
- Default: null
Function used to fetch object labels via an API request, returns a Promise.
### `labels`
- Type: Object
- placeholder: String - Label for the search placeholder.
- title: String - Label for the card title.
- update: String - Label for button which updates the URL/report.
- Default: `{}`
Object of localized labels.
### `param`
- **Required**
- Type: String
- Default: null
The parameter to use in the querystring.
### `path`
- **Required**
- Type: String
- Default: null
The `path` parameter supplied by React-Router
### `query`
- Type: Object
- Default: `{}`
The query string represented in object form
### `type`
- **Required**
- Type: String
- Default: null
Which type of autocompleter should be used in the Search

25
plugins/woocommerce-admin/docs/components/packages/count.md
View File

@ -1,25 +0,0 @@
`Count` (component)
===================
Display a number with a styled border.
Props
-----
### `count`
- **Required**
- Type: Number
- Default: null
Value of the number to be displayed.
### `label`
- Type: String
- Default: `''`
A translated label with the number in context, used for screen readers.

23
plugins/woocommerce-admin/docs/components/packages/date-range-filter-picker.md
View File

@ -1,23 +0,0 @@
`DateRangeFilterPicker` (component)
===================================
Select a range of dates or single dates.
Props
-----
### `onRangeSelect`
- **Required**
- Type: Function
- Default: null
Callback called when selection is made.
### `query`
- Type: Object
- Default: `{}`
The query string represented in object form.

39
plugins/woocommerce-admin/docs/components/packages/date.md
View File

@ -1,39 +0,0 @@
`Date` (component)
==================
Use the `Date` component to display accessible dates or times.
Props
-----
### `date`
- **Required**
- Type: One of type: string, object
- Default: null
Date to use in the component.
### `machineFormat`
- Type: String
- Default: `'Y-m-d H:i:s'`
Date format used in the `datetime` prop of the `time` element.
### `screenReaderFormat`
- Type: String
- Default: `'F j, Y'`
Date format used for screen readers.
### `visibleFormat`
- Type: String
- Default: `'Y-m-d'`
Date format displayed in the page.

27
plugins/woocommerce-admin/docs/components/packages/dropdown-button.md
View File

@ -1,27 +0,0 @@
`DropdownButton` (component)
============================
A button useful for a launcher of a dropdown component. The button is 100% width of its container and displays
single or multiple lines rendered as `<span/>` elments.
@param { object } props Props passed to component.
Props
-----
### `labels`
- **Required**
- Type: Array
- Default: null
An array of elements to be rendered as the content of the button.
### `isOpen`
- Type: Boolean
- Default: null
Boolean describing if the dropdown in open or not.

89
plugins/woocommerce-admin/docs/components/packages/ellipsis-menu.md
View File

@ -1,89 +0,0 @@
`EllipsisMenu` (component)
==========================
This is a dropdown menu hidden behind a vertical ellipsis icon. When clicked, the inner MenuItems are displayed.
Props
-----
### `label`
- **Required**
- Type: String
- Default: null
The label shown when hovering/focusing on the icon button.
### `renderContent`
- Type: Function
- Default: null
A function returning `MenuTitle`/`MenuItem` components as a render prop. Arguments from Dropdown passed as function arguments.
`MenuItem` (component)
======================
`MenuItem` is used to give the item an accessible wrapper, with the `menuitem` role and added keyboard functionality (`onInvoke`).
`MenuItem`s can also be deemed "clickable", though this is disabled by default because generally the inner component handles
the click event.
Props
-----
### `checked`
- Type: Boolean
- Default: null
Whether the menu item is checked or not. Only relevant for menu items with `isCheckbox`.
### `children`
- Type: ReactNode
- Default: null
A renderable component (or string) which will be displayed as the content of this item. Generally a `ToggleControl`.
### `isCheckbox`
- Type: Boolean
- Default: `false`
Whether the menu item is a checkbox (will render a FormToggle and use the `menuitemcheckbox` role).
### `isClickable`
- Type: Boolean
- Default: `false`
Boolean to control whether the MenuItem should handle the click event. Defaults to false, assuming your child component
handles the click event.
### `onInvoke`
- **Required**
- Type: Function
- Default: null
A function called when this item is activated via keyboard ENTER or SPACE; or when the item is clicked
(only if `isClickable` is set).
`MenuTitle` (component)
=======================
`MenuTitle` is another valid Menu child, but this does not have any accessibility attributes associated
(so this should not be used in place of the `EllipsisMenu` prop `label`).
Props
-----
### `children`
- Type: ReactNode
- Default: null
A renderable component (or string) which will be displayed as the content of this item.

95
plugins/woocommerce-admin/docs/components/packages/empty-content.md
View File

@ -1,95 +0,0 @@
`EmptyContent` (component)
==========================
A component to be used when there is no data to show.
It can be used as an opportunity to provide explanation or guidance to help a user progress.
Props
-----
### `title`
- **Required**
- Type: String
- Default: null
The title to be displayed.
### `message`
- Type: String
- Default: null
An additional message to be displayed.
### `illustration`
- Type: String
- Default: `'/empty-content.svg'`
The url string of an image path. Prefix with `/` to load an image relative to the plugin directory.
### `illustrationHeight`
- Type: Number
- Default: null
Height to use for the illustration.
### `illustrationWidth`
- Type: Number
- Default: `400`
Width to use for the illustration.
### `actionLabel`
- **Required**
- Type: String
- Default: null
Label to be used for the primary action button.
### `actionURL`
- Type: String
- Default: null
URL to be used for the primary action button.
### `actionCallback`
- Type: Function
- Default: null
Callback to be used for the primary action button.
### `secondaryActionLabel`
- Type: String
- Default: null
Label to be used for the secondary action button.
### `secondaryActionURL`
- Type: String
- Default: null
URL to be used for the secondary action button.
### `secondaryActionCallback`
- Type: Function
- Default: null
Callback to be used for the secondary action button.
### `className`
- Type: String
- Default: null
Additional CSS classes.

52
plugins/woocommerce-admin/docs/components/packages/filter-picker.md
View File

@ -1,52 +0,0 @@
`FilterPicker` (component)
==========================
Modify a url query parameter via a dropdown selection of configurable options.
This component manipulates the `filter` query parameter.
Props
-----
### `config`
- **Required**
- Type: Object
- label: String - A label above the filter selector.
- staticParams: Array - Url parameters to persist when selecting a new filter.
- param: String - The url paramter this filter will modify.
- defaultValue: String - The default paramter value to use instead of 'all'.
- showFilters: Function - Determine if the filter should be shown. Supply a function with the query object as an argument returning a boolean.
- filters: Array
- chartMode: One of: 'item-comparison', 'time-comparison'
- component: String - A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented.
- label: String - The label for this filter. Optional only for custom component filters.
- path: String - An array representing the "path" to this filter, if nested.
- subFilters: Array - An array of more filter objects that act as "children" to this item.
This set of filters is shown if the parent filter is clicked.
- value: String - The value for this filter, used to set the `filter` query param when clicked, if there are no `subFilters`.
- Default: null
An array of filters and subFilters to construct the menu.
### `path`
- **Required**
- Type: String
- Default: null
The `path` parameter supplied by React-Router.
### `query`
- Type: Object
- Default: `{}`
The query string represented in object form.
### `onFilterSelect`
- Type: Function
- Default: `() => {}`
Function to be called after filter selection.

68
plugins/woocommerce-admin/docs/components/packages/filters.md
View File

@ -1,68 +0,0 @@
`ReportFilters` (component)
===========================
Add a collection of report filters to a page. This uses `DatePicker` & `FilterPicker` for the "basic" filters, and `AdvancedFilters`
or a comparison card if "advanced" or "compare" are picked from `FilterPicker`.
Props
-----
### `advancedFilters`
- Type: Object
- Default: `{}`
Config option passed through to `AdvancedFilters`
### `filters`
- Type: Array
- Default: `[]`
Config option passed through to `FilterPicker` - if not used, `FilterPicker` is not displayed.
### `path`
- **Required**
- Type: String
- Default: null
The `path` parameter supplied by React-Router
### `query`
- Type: Object
- Default: `{}`
The query string represented in object form
### `showDatePicker`
- Type: Boolean
- Default: `true`
Whether the date picker must be shown.
### `onDateSelect`
- Type: Function
- Default: `() => {}`
Function to be called after date selection.
### `onFilterSelect`
- Type: Function
- Default: null
Function to be called after filter selection.
### `onAdvancedFilterAction`
- Type: Function
- Default: null
Function to be called after an advanced filter action has been taken.

38
plugins/woocommerce-admin/docs/components/packages/flag.md
View File

@ -1,38 +0,0 @@
`Flag` (component)
==================
Use the `Flag` component to display a country's flag using the operating system's emojis.
React component.
Props
-----
### `code`
- Type: String
- Default: null
Two letter, three letter or three digit country code.
### `order`
- Type: Object
- Default: null
An order can be passed instead of `code` and the code will automatically be pulled from the billing or shipping data.
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `size`
- Type: Number
- Default: null
Supply a font size to be applied to the emoji flag.

51
plugins/woocommerce-admin/docs/components/packages/form.md
View File

@ -1,51 +0,0 @@
`Form` (component)
==================
A form component to handle form state and provide input helper props.
Props
-----
### `children`
- Type: *
- Default: null
A renderable component in which to pass this component's state and helpers.
Generally a number of input or other form elements.
### `errors`
- Type: Object
- Default: `{}`
Object of all initial errors to store in state.
### `initialValues`
- Type: Object
- Default: `{}`
Object key:value pair list of all initial field values.
### `onSubmitCallback`
- Type: Function
- Default: `noop`
Function to call when a form is submitted with valid fields.
### `validate`
- Type: Function
- Default: `noop`
A function that is passed a list of all values and
should return an `errors` object with error response.
### `touched`
- Type: undefined
- Default: `{}`

45
plugins/woocommerce-admin/docs/components/packages/gravatar.md
View File

@ -1,45 +0,0 @@
`Gravatar` (component)
======================
Display a users Gravatar.
Props
-----
### `user`
- Type: One of type: object, string
- Default: null
The address to hash for displaying a Gravatar. Can be an email address or WP-API user object.
### `alt`
- Type: String
- Default: null
Text to display as the image alt attribute.
### `title`
- Type: String
- Default: null
Text to use for the image's title
### `size`
- Type: Number
- Default: `60`
Default 60. The size of Gravatar to request.
### `className`
- Type: String
- Default: null
Additional CSS classes.

25
plugins/woocommerce-admin/docs/components/packages/image-asset.md
View File

@ -1,25 +0,0 @@
`ImageAsset` (component)
========================
A component that loads an image, allowing images to be loaded relative to the main asset/plugin folder.
Props are passed through to `<img />`
Props
-----
### `src`
- **Required**
- Type: String
- Default: null
Image location to pass through to `<img />`.
### `alt`
- **Required**
- Type: String
- Default: null
Alt text to pass through to `<img />`.

24
plugins/woocommerce-admin/docs/components/packages/link.md
View File

@ -1,24 +0,0 @@
`Link` (component)
==================
Use `Link` to create a link to another resource. It accepts a type to automatically
create wp-admin links, wc-admin links, and external links.
Props
-----
### `href`
- **Required**
- Type: String
- Default: null
The resource to link to.
### `type`
- Type: One of: 'wp-admin', 'wc-admin', 'external'
- Default: `'wc-admin'`
Type of link. For wp-admin and wc-admin, the correct prefix is appended.

32
plugins/woocommerce-admin/docs/components/packages/list.md
View File

@ -1,32 +0,0 @@
`List` (component)
==================
List component to display a list of items.
Props
-----
### `className`
- Type: String
- Default: null
Additional class name to style the component.
### `items`
- **Required**
- Type: Array
- after: ReactNode - Content displayed after the list item text.
- before: ReactNode - Content displayed before the list item text.
- className: String - Additional class name to style the list item.
- description: String - Description displayed beneath the list item title.
- content: One of type: string, node
- href: String - Href attribute used in a Link wrapped around the item.
- onClick: Function - Content displayed after the list item text.
- target: String - Target attribute used for Link wrapper.
- title: String - Title displayed for the list item.
- Default: null
An array of list items.

25
plugins/woocommerce-admin/docs/components/packages/order-status.md
View File

@ -1,25 +0,0 @@
`OrderStatus` (component)
=========================
Use `OrderStatus` to display a badge with human-friendly text describing the current order status.
Props
-----
### `order`
- **Required**
- Type: Object
- Default: null
The order to display a status for.
### `className`
- Type: String
- Default: null
Additional CSS classes.

54
plugins/woocommerce-admin/docs/components/packages/pagination.md
View File

@ -1,54 +0,0 @@
`Pagination` (component)
========================
Use `Pagination` to allow navigation between pages that represent a collection of items.
The component allows for selecting a new page and items per page options.
Props
-----
### `page`
- **Required**
- Type: Number
- Default: null
The current page of the collection.
### `onPageChange`
- Type: Function
- Default: `noop`
A function to execute when the page is changed.
### `perPage`
- **Required**
- Type: Number
- Default: null
The amount of results that are being displayed per page.
### `onPerPageChange`
- Type: Function
- Default: `noop`
A function to execute when the per page option is changed.
### `total`
- **Required**
- Type: Number
- Default: null
The total number of results.
### `className`
- Type: String
- Default: null
Additional classNames.

50
plugins/woocommerce-admin/docs/components/packages/product-image.md
View File

@ -1,50 +0,0 @@
`ProductImage` (component)
==========================
Use `ProductImage` to display a product's or variation's featured image.
If no image can be found, a placeholder matching the front-end image
placeholder will be displayed.
Props
-----
### `width`
- Type: Number
- Default: `60`
The width of image to display.
### `height`
- Type: Number
- Default: `60`
The height of image to display.
### `className`
- Type: String
- Default: `''`
Additional CSS classes.
### `product`
- Type: Object
- Default: null
Product or variation object. The image to display will be pulled from
`product.images` or `variation.image`.
See https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties
and https://woocommerce.github.io/woocommerce-rest-api-docs/#product-variation-properties
### `alt`
- Type: String
- Default: null
Text to use as the image alt attribute.

75
plugins/woocommerce-admin/docs/components/packages/rating.md
View File

@ -1,75 +0,0 @@
`Rating` (component)
====================
Use `Rating` to display a set of stars, filled, empty or half-filled, that represents a
rating in a scale between 0 and the prop `totalStars` (default 5).
Props
-----
### `rating`
- Type: Number
- Default: `0`
Number of stars that should be filled. You can pass a partial number of stars like `2.5`.
### `totalStars`
- Type: Number
- Default: `5`
The total number of stars the rating is out of.
### `size`
- Type: Number
- Default: `18`
The size in pixels the stars should be rendered at.
### `className`
- Type: String
- Default: null
Additional CSS classes.
`ProductRating` (component)
===========================
Display a set of stars representing the product's average rating.
Props
-----
### `product`
- **Required**
- Type: Object
- Default: null
A product object containing a `average_rating`.
See https://woocommerce.github.io/woocommerce-rest-api-docs/#products.
`ReviewRating` (component)
==========================
Display a set of stars representing the review's rating.
Props
-----
### `review`
- **Required**
- Type: Object
- Default: null
A review object containing a `rating`.
See https://woocommerce.github.io/woocommerce-rest-api-docs/#retrieve-product-reviews.

190
plugins/woocommerce-admin/docs/components/packages/search-list-control.md
View File

@ -1,190 +0,0 @@
`SearchListControl` (component)
===============================
Component to display a searchable, selectable list of items.
Props
-----
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `isHierarchical`
- Type: Boolean
- Default: null
Whether the list of items is hierarchical or not. If true, each list item is expected to
have a parent property.
### `isLoading`
- Type: Boolean
- Default: null
Whether the list of items is still loading.
### `isSingle`
- Type: Boolean
- Default: null
Restrict selections to one item.
### `list`
- Type: Array
- id: Number
- name: String
- Default: null
A complete list of item objects, each with id, name properties. This is displayed as a
clickable/keyboard-able list, and possibly filtered by the search term (searches name).
### `messages`
- Type: Object
- clear: String - A more detailed label for the "Clear all" button, read to screen reader users.
- list: String - Label for the list of selectable items, only read to screen reader users.
- noItems: String - Message to display when the list is empty (implies nothing loaded from the server
or parent component).
- noResults: String - Message to display when no matching results are found. %s is the search term.
- search: String - Label for the search input
- selected: Function - Label for the selected items. This is actually a function, so that we can pass
through the count of currently selected items.
- updated: String - Label indicating that search results have changed, read to screen reader users.
- Default: null
Messages displayed or read to the user. Configure these to reflect your object type.
See `defaultMessages` above for examples.
### `onChange`
- **Required**
- Type: Function
- Default: null
Callback fired when selected items change, whether added, cleared, or removed.
Passed an array of item objects (as passed in via props.list).
### `onSearch`
- Type: Function
- Default: null
Callback fired when the search field is used.
### `renderItem`
- Type: Function
- Default: null
Callback to render each item in the selection list, allows any custom object-type rendering.
### `selected`
- **Required**
- Type: Array
- Default: null
The list of currently selected items.
### `search`
- Type: String
- Default: null
### `setState`
- Type: Function
- Default: null
### `debouncedSpeak`
- Type: Function
- Default: null
### `instanceId`
- Type: Number
- Default: null
`SearchListItem` (component)
============================
Props
-----
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `countLabel`
- Type: ReactNode
- Default: null
Label to display if `showCount` is set to true. If undefined, it will use `item.count`.
### `depth`
- Type: Number
- Default: `0`
Depth, non-zero if the list is hierarchical.
### `item`
- Type: Object
- Default: null
Current item to display.
### `isSelected`
- Type: Boolean
- Default: null
Whether this item is selected.
### `isSingle`
- Type: Boolean
- Default: null
Whether this should only display a single item (controls radio vs checkbox icon).
### `onSelect`
- Type: Function
- Default: null
Callback for selecting the item.
### `search`
- Type: String
- Default: `''`
Search string, used to highlight the substring in the item name.
### `showCount`
- Type: Boolean
- Default: `false`
Toggles the "count" bubble on/off.

84
plugins/woocommerce-admin/docs/components/packages/search.md
View File

@ -1,84 +0,0 @@
`Search` (component)
====================
A search box which autocompletes results while typing, allowing for the user to select an existing object
(product, order, customer, etc). Currently only products are supported.
Props
-----
### `allowFreeTextSearch`
- Type: Boolean
- Default: `false`
Render additional options in the autocompleter to allow free text entering depending on the type.
### `className`
- Type: String
- Default: null
Class name applied to parent div.
### `onChange`
- Type: Function
- Default: `noop`
Function called when selected results change, passed result list.
### `type`
- **Required**
- Type: One of: 'categories', 'countries', 'coupons', 'customers', 'downloadIps', 'emails', 'orders', 'products', 'taxes', 'usernames', 'variations'
- Default: null
The object type to be used in searching.
### `placeholder`
- Type: String
- Default: null
A placeholder for the search input.
### `selected`
- Type: Array
- id: One of type: number, string
- label: String
- Default: `[]`
An array of objects describing selected values. If the label of the selected
value is omitted, the Tag of that value will not be rendered inside the
search box.
### `inlineTags`
- Type: Boolean
- Default: `false`
Render tags inside input, otherwise render below input.
### `showClearButton`
- Type: Boolean
- Default: `false`
Render a 'Clear' button next to the input box to remove its contents.
### `staticResults`
- Type: Boolean
- Default: `false`
Render results list positioned statically instead of absolutely.
### `disabled`
- Type: Boolean
- Default: `false`
Whether the control is disabled or not.

30
plugins/woocommerce-admin/docs/components/packages/section-header.md
View File

@ -1,30 +0,0 @@
`SectionHeader` (component)
===========================
A header component. The header can contain a title, actions via children, and an `EllipsisMenu` menu.
Props
-----
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `menu`
- Type: (custom validator)
- Default: null
An `EllipsisMenu`, with filters used to control the content visible in this card
### `title`
- **Required**
- Type: One of type: string, node
- Default: null
The title to use for this card.

38
plugins/woocommerce-admin/docs/components/packages/section.md
View File

@ -1,38 +0,0 @@
`H` (component)
===============
These components are used to frame out the page content for accessible heading hierarchy. Instead of defining fixed heading levels
(`h2`, `h3`, …) you can use `<H />` to create "section headings", which look to the parent `<Section />`s for the appropriate
heading level.
`Section` (component)
=====================
The section wrapper, used to indicate a sub-section (and change the header level context).
Props
-----
### `component`
- Type: One of type: func, string, bool
- Default: null
The wrapper component for this section. Optional, defaults to `div`. If passed false, no wrapper is used. Additional props
passed to Section are passed on to the component.
### `children`
- Type: ReactNode
- Default: null
The children inside this section, rendered in the `component`. This increases the context level for the next heading used.

56
plugins/woocommerce-admin/docs/components/packages/segmented-selection.md
View File

@ -1,56 +0,0 @@
`SegmentedSelection` (component)
================================
Create a panel of styled selectable options rendering stylized checkboxes and labels
Props
-----
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `options`
- **Required**
- Type: Array
- value: String
- label: String
- Default: null
An Array of options to render. The array needs to be composed of objects with properties `label` and `value`.
### `selected`
- Type: String
- Default: null
Value of selected item.
### `onSelect`
- **Required**
- Type: Function
- Default: null
Callback to be executed after selection
### `name`
- **Required**
- Type: String
- Default: null
This will be the key in the key and value arguments supplied to `onSelect`.
### `legend`
- **Required**
- Type: String
- Default: null
Create a legend visible to screen readers.

53
plugins/woocommerce-admin/docs/components/packages/simple-select-control.md
View File

@ -1,53 +0,0 @@
`SimpleSelectControl` (component)
=================================
A component for displaying a material styled 'simple' select control.
Props
-----
### `className`
- Type: String
- Default: null
Additional class name to style the component.
### `label`
- Type: String
- Default: null
A label to use for the main select element.
### `options`
- Type: Array
- value: String - Input value for this option.
- label: String - Label for this option.
- disabled: Boolean - Disable the option.
- Default: null
An array of options to use for the dropddown.
### `onChange`
- Type: Function
- Default: null
A function that receives the value of the new option that is being selected as input.
### `value`
- Type: String
- Default: null
The currently value of the select element.
### `help`
- Type: One of type: string, node
- Default: null
If this property is added, a help text will be generated using help property as the content.

15
plugins/woocommerce-admin/docs/components/packages/spinner.md
View File

@ -1,15 +0,0 @@
`Spinner` (component)
=====================
Spinner - An indeterminate circular progress indicator.
Props
-----
### `className`
- Type: String
- Default: null
Additional class name to style the component.

63
plugins/woocommerce-admin/docs/components/packages/split-button.md
View File

@ -1,63 +0,0 @@
`SplitButton` (component)
=========================
A component for displaying a button with a main action plus a secondary set of actions behind a menu toggle.
Props
-----
### `isPrimary`
- Type: Boolean
- Default: `false`
Whether the button is styled as a primary button.
### `mainIcon`
- Type: ReactNode
- Default: null
Icon for the main button.
### `mainLabel`
- Type: String
- Default: null
Label for the main button.
### `onClick`
- Type: Function
- Default: `noop`
Function to activate when the the main button is clicked.
### `menuLabel`
- Type: String
- Default: null
Label to display for the menu of actions, used as a heading on the mobile popover and for accessible text.
### `controls`
- **Required**
- Type: Array
- icon: One of type: string, element
- label: String - Label displayed for this button.
- onClick: Function - Click handler for this button.
- Default: null
An array of additional actions. Accepts additional icon, label, and onClick props.
### `className`
- Type: String
- Default: null
Additional CSS classes.

50
plugins/woocommerce-admin/docs/components/packages/stepper.md
View File

@ -1,50 +0,0 @@
`Stepper` (component)
=====================
A stepper component to indicate progress in a set number of steps.
Props
-----
### `className`
- Type: String
- Default: null
Additional class name to style the component.
### `currentStep`
- **Required**
- Type: String
- Default: null
The current step's key.
### `steps`
- **Required**
- Type: Array
- key: String - Key used to identify step.
- label: String - Label displayed in stepper.
- description: String - Description displayed beneath the label.
- isComplete: Boolean - Optionally mark a step complete regardless of step index.
- content: ReactNode - Content displayed when the step is active.
- Default: null
An array of steps used.
### `isVertical`
- Type: Boolean
- Default: `false`
If the stepper is vertical instead of horizontal.
### `isPending`
- Type: Boolean
- Default: `false`
Optionally mark the current step as pending to show a spinner.

141
plugins/woocommerce-admin/docs/components/packages/summary.md
View File

@ -1,141 +0,0 @@
`SummaryList` (component)
=========================
A container element for a list of SummaryNumbers. This component handles detecting & switching to
the mobile format on smaller screens.
Props
-----
### `children`
- **Required**
- Type: Function
- Default: null
A function returning a list of `<SummaryNumber />`s
### `label`
- Type: String
- Default: `__( 'Performance Indicators', 'woocommerce-admin' )`
An optional label of this group, read to screen reader users.
`SummaryNumber` (component)
===========================
A component to show a value, label, and an optional change percentage. Can also act as a link to a specific report focus.
Props
-----
### `delta`
- Type: Number
- Default: null
A number to represent the percentage change since the last comparison period - positive numbers will show
a green up arrow, negative numbers will show a red down arrow, and zero will show a flat right arrow.
If omitted, no change value will display.
### `href`
- Type: String
- Default: `''`
An internal link to the report focused on this number.
### `isOpen`
- Type: Boolean
- Default: `false`
Boolean describing whether the menu list is open. Only applies in mobile view,
and only applies to the toggle-able item (first in the list).
### `label`
- **Required**
- Type: String
- Default: null
A string description of this value, ex "Revenue", or "New Customers"
### `onToggle`
- Type: Function
- Default: null
A function used to switch the given SummaryNumber to a button, and called on click.
### `prevLabel`
- Type: String
- Default: `__( 'Previous Period:', 'woocommerce-admin' )`
A string description of the previous value's timeframe, ex "Previous Year:".
### `prevValue`
- Type: One of type: number, string
- Default: null
A string or number value to display - a string is allowed so we can accept currency formatting.
If omitted, this section won't display.
### `reverseTrend`
- Type: Boolean
- Default: `false`
A boolean used to indicate that a negative delta is "good", and should be styled like a positive (and vice-versa).
### `selected`
- Type: Boolean
- Default: `false`
A boolean used to show a highlight style on this number.
### `value`
- Type: One of type: number, string
- Default: null
A string or number value to display - a string is allowed so we can accept currency formatting.
### `onLinkClickCallback`
- Type: Function
- Default: `noop`
A function to be called after a SummaryNumber, rendered as a link, is clicked.
`SummaryListPlaceholder` (component)
====================================
`SummaryListPlaceholder` behaves like `SummaryList` but displays placeholder summary items instead of data.
This can be used while loading data.
Props
-----
### `numberOfItems`
- **Required**
- Type: Number
- Default: null
An integer with the number of summary items to display.
### `numberOfRows`
- Type: undefined
- Default: `5`

378
plugins/woocommerce-admin/docs/components/packages/table.md
View File

@ -1,378 +0,0 @@
`TableCard` (component)
=======================
This is an accessible, sortable, and scrollable table for displaying tabular data (like revenue and other analytics data).
It accepts `headers` for column headers, and `rows` for the table content.
`rowHeader` can be used to define the index of the row header (or false if no header).
`TableCard` serves as Card wrapper & contains a card header, `<Table />`, `<TableSummary />`, and `<Pagination />`.
This includes filtering and comparison functionality for report pages.
Props
-----
### `compareBy`
- Type: String
- Default: null
The string to use as a query parameter when comparing row items.
### `compareParam`
- Type: String
- Default: `'filter'`
Url query parameter compare function operates on
### `headers`
- Type: Array
- hiddenByDefault: Boolean
- defaultSort: Boolean
- isSortable: Boolean
- key: String
- label: String
- required: Boolean
- Default: null
An array of column headers (see `Table` props).
### `labels`
- Type: Object
- compareButton: String
- downloadButton: String
- helpText: String
- placeholder: String
- Default: null
Custom labels for table header actions.
### `ids`
- Type: Array
Number
- Default: null
A list of IDs, matching to the row list so that ids[ 0 ] contains the object ID for the object displayed in row[ 0 ].
### `isLoading`
- Type: Boolean
- Default: `false`
Defines if the table contents are loading.
It will display `TablePlaceholder` component instead of `Table` if that's the case.
### `onQueryChange`
- Type: Function
- Default: `noop`
A function which returns a callback function to update the query string for a given `param`.
### `onColumnsChange`
- Type: Function
- Default: `noop`
A function which returns a callback function which is called upon the user changing the visiblity of columns.
### `onSearch`
- Type: Function
- Default: `noop`
A function which is called upon the user searching in the table header.
### `onSort`
- Type: Function
- Default: `undefined`
A function which is called upon the user changing the sorting of the table.
### `downloadable`
- Type: Boolean
- Default: `false`
Whether the table must be downloadable. If true, the download button will appear.
### `onClickDownload`
- Type: Function
- Default: null
A callback function called when the "download" button is pressed. Optional, if used, the download button will appear.
### `query`
- Type: Object
- Default: `{}`
An object of the query parameters passed to the page, ex `{ page: 2, per_page: 5 }`.
### `rowHeader`
- Type: One of type: number, bool
- Default: `0`
An array of arrays of display/value object pairs (see `Table` props).
### `rows`
- Type: Array
Array
- display: ReactNode
- value: One of type: string, number, bool
- Default: `[]`
Which column should be the row header, defaults to the first item (`0`) (see `Table` props).
### `rowsPerPage`
- **Required**
- Type: Number
- Default: null
The total number of rows to display per page.
### `searchBy`
- Type: String
- Default: null
The string to use as a query parameter when searching row items.
### `showMenu`
- Type: Boolean
- Default: `true`
Boolean to determine whether or not ellipsis menu is shown.
### `summary`
- Type: Array
- label: ReactNode
- value: One of type: string, number
- Default: null
An array of objects with `label` & `value` properties, which display in a line under the table.
Optional, can be left off to show no summary.
### `title`
- **Required**
- Type: String
- Default: null
The title used in the card header, also used as the caption for the content in this table.
### `totalRows`
- **Required**
- Type: Number
- Default: null
The total number of rows (across all pages).
### `baseSearchQuery`
- Type: Object
- Default: `{}`
Pass in query parameters to be included in the path when onSearch creates a new url.
`EmptyTable` (component)
========================
`EmptyTable` displays a blank space with an optional message passed as a children node
with the purpose of replacing a table with no rows.
It mimics the same height a table would have according to the `numberOfRows` prop.
Props
-----
### `numberOfRows`
- Type: Number
- Default: `5`
An integer with the number of rows the box should occupy.
`TablePlaceholder` (component)
==============================
`TablePlaceholder` behaves like `Table` but displays placeholder boxes instead of data. This can be used while loading.
Props
-----
### `query`
- Type: Object
- Default: null
An object of the query parameters passed to the page, ex `{ page: 2, per_page: 5 }`.
### `caption`
- **Required**
- Type: String
- Default: null
A label for the content in this table.
### `headers`
- Type: Array
- hiddenByDefault: Boolean
- defaultSort: Boolean
- isSortable: Boolean
- key: String
- label: ReactNode
- required: Boolean
- Default: null
An array of column headers (see `Table` props).
### `numberOfRows`
- Type: Number
- Default: `5`
An integer with the number of rows to display.
`TableSummary` (component)
==========================
A component to display summarized table data - the list of data passed in on a single line.
Props
-----
### `data`
- Type: Array
- Default: null
An array of objects with `label` & `value` properties, which display on a single line.
`Table` (component)
===================
A table component, without the Card wrapper. This is a basic table display, sortable, but no default filtering.
Row data should be passed to the component as a list of arrays, where each array is a row in the table.
Headers are passed in separately as an array of objects with column-related properties. For example,
this data would render the following table.
```js
const headers = [ { label: 'Month' }, { label: 'Orders' }, { label: 'Revenue' } ];
const rows = [
[
{ display: 'January', value: 1 },
{ display: 10, value: 10 },
{ display: '$530.00', value: 530 },
],
[
{ display: 'February', value: 2 },
{ display: 13, value: 13 },
{ display: '$675.00', value: 675 },
],
[
{ display: 'March', value: 3 },
{ display: 9, value: 9 },
{ display: '$460.00', value: 460 },
],
]
```
| Month | Orders | Revenue |
| ---------|--------|---------|
| January | 10 | $530.00 |
| February | 13 | $675.00 |
| March | 9 | $460.00 |
Props
-----
### `ariaHidden`
- Type: Boolean
- Default: `false`
Controls whether this component is hidden from screen readers. Used by the loading state, before there is data to read.
Don't use this on real tables unless the table data is loaded elsewhere on the page.
### `caption`
- **Required**
- Type: String
- Default: null
A label for the content in this table
### `className`
- Type: String
- Default: null
Additional CSS classes.
### `headers`
- Type: Array
- defaultSort: Boolean - Boolean, true if this column is the default for sorting. Only one column should have this set.
- defaultOrder: String - String, asc|desc if this column is the default for sorting. Only one column should have this set.
- isLeftAligned: Boolean - Boolean, true if this column should be aligned to the left.
- isNumeric: Boolean - Boolean, true if this column is a number value.
- isSortable: Boolean - Boolean, true if this column is sortable.
- key: String - The API parameter name for this column, passed to `orderby` when sorting via API.
- label: ReactNode - The display label for this column.
- required: Boolean - Boolean, true if this column should always display in the table (not shown in toggle-able list).
- screenReaderLabel: String - The label used for screen readers for this column.
- Default: `[]`
An array of column headers, as objects.
### `onSort`
- Type: Function
- Default: `noop`
A function called when sortable table headers are clicked, gets the `header.key` as argument.
### `query`
- Type: Object
- Default: `{}`
The query string represented in object form
### `rows`
- **Required**
- Type: Array
Array
- display: ReactNode - Display value, used for rendering- strings or elements are best here.
- value: One of type: string, number, bool
- Default: null
An array of arrays of display/value object pairs.
### `rowHeader`
- Type: One of type: number, bool
- Default: `0`
Which column should be the row header, defaults to the first item (`0`) (but could be set to `1`, if the first col
is checkboxes, for example). Set to false to disable row headers.

47
plugins/woocommerce-admin/docs/components/packages/tag.md
View File

@ -1,47 +0,0 @@
`Tag` (component)
=================
This component can be used to show an item styled as a "tag", optionally with an `X` + "remove"
or with a popover that is shown on click.
Props
-----
### `id`
- Type: One of type: number, string
- Default: null
The ID for this item, used in the remove function.
### `label`
- **Required**
- Type: String
- Default: null
The name for this item, displayed as the tag's text.
### `popoverContents`
- Type: ReactNode
- Default: null
Contents to display on click in a popover
### `remove`
- Type: Function
- Default: null
A function called when the remove X is clicked. If not used, no X icon will display.
### `screenReaderLabel`
- Type: String
- Default: null
A more descriptive label for screen reader users. Defaults to the `name` prop.

69
plugins/woocommerce-admin/docs/components/packages/text-control-with-affixes.md
View File

@ -1,69 +0,0 @@
`TextControlWithAffixes` (component)
====================================
This component is essentially a wrapper (really a reimplementation) around the
TextControl component that adds support for affixes, i.e. the ability to display
a fixed part either at the beginning or at the end of the text input.
Props
-----
### `label`
- Type: String
- Default: null
If this property is added, a label will be generated using label property as the content.
### `help`
- Type: String
- Default: null
If this property is added, a help text will be generated using help property as the content.
### `type`
- Type: String
- Default: `'text'`
Type of the input element to render. Defaults to "text".
### `value`
- **Required**
- Type: String
- Default: null
The current value of the input.
### `className`
- Type: String
- Default: null
The class that will be added with "components-base-control" to the classes of the wrapper div.
If no className is passed only components-base-control is used.
### `onChange`
- **Required**
- Type: Function
- Default: null
A function that receives the value of the input.
### `prefix`
- Type: ReactNode
- Default: null
Markup to be inserted at the beginning of the input.
### `suffix`
- Type: ReactNode
- Default: null
Markup to be appended at the end of the input.

18
plugins/woocommerce-admin/docs/components/packages/view-more-list.md
View File

@ -1,18 +0,0 @@
`ViewMoreList` (component)
==========================
This component displays a 'X more' button that displays a list of items on a popover when clicked.
Props
-----
### `items`
- Type: Array
ReactNode
- Default: `[]`
Items to list in the popover

45
plugins/woocommerce-admin/docs/components/packages/web-preview.md
View File

@ -1,45 +0,0 @@
`WebPreview` (component)
========================
WebPreview component to display an iframe of another page.
Props
-----
### `className`
- Type: String
- Default: null
Additional class name to style the component.
### `loadingContent`
- Type: ReactNode
- Default: `<Spinner />`
Content shown when iframe is still loading.
### `onLoad`
- Type: Function
- Default: `noop`
Function to fire when iframe content is loaded.
### `src`
- **Required**
- Type: String
- Default: null
Iframe src to load.
### `title`
- **Required**
- Type: String
- Default: null
Iframe title.

24
plugins/woocommerce-admin/packages/components/src/animation-slider/README.md Normal file
View File

@ -0,0 +1,24 @@
AnimationSlider
===
This component creates slideable content controlled by an animate prop to direct the contents to slide left or right.
All other props are passed to `CSSTransition`. More info at http://reactcommunity.org/react-transition-group/css-transition
## Usage
```jsx
<AnimationSlider animationKey="1" animate="right">
{ ( status ) => (
<span>One (1)</span>
) }
</AnimationSlider>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`children` | function | `null` | (required) A function returning rendered content with argument status, reflecting `CSSTransition` status
`animationKey` | any | `null` | (required) A unique identifier for each slideable page
`animate` | string | `null` | null, 'left', 'right', to designate which direction to slide on a change
`onExited` | function | `null` | A function to be executed after a transition is complete, passing the containing ref as the argument

52
plugins/woocommerce-admin/packages/components/src/autocomplete/README.md Normal file
View File

@ -0,0 +1,52 @@
Autocomplete
===
A search box which filters options while typing,
allowing a user to select from an option from a filtered list.
## Usage
```jsx
const options = [
{
key: 'apple',
label: 'Apple',
value: { id: 'apple' },
},
{
key: 'apricot',
label: 'Apricot',
value: { id: 'apricot' },
},
];
<Autocomplete
label="Single value"
onChange={ ( selected ) => setState( { singleSelected: selected } ) }
options={ options }
placeholder="Start typing to filter options..."
selected={ singleSelected }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | string | `null` | Class name applied to parent div
`excludeSelectedOptions` | boolean | `true` | Exclude already selected options from the options list
`onFilter` | function | `identity` | Add or remove items to the list of options after filtering, passed the array of filtered options and should return an array of options.
`getSearchExpression` | function | `identity` | Function to add regex expression to the filter the results, passed the search query
`help` | string\|node | `null` | Help text to be appended beneath the input
`inlineTags` | boolean | `false` | Render tags inside input, otherwise render below input
`label` | string | `null` | A label to use for the main input
`onChange` | function | `noop` | Function called when selected results change, passed result list
`onSearch` | function | `noop` | Function to run after the search query is updated, passed the search query
`options` | array | `null` | (required) An array of objects for the options list. The option along with its key, label and value will be returned in the onChange event
`placeholder` | string | `null` | A placeholder for the search input
`selected` | array | `[]` | An array of objects describing selected values. If the label of the selected value is omitted, the Tag of that value will not be rendered inside the search box
`maxResults` | number | `0` | A limit for the number of results shown in the options menu. Set to 0 for no limit
`multiple` | boolean | `false` | Allow multiple option selections
`showClearButton` | boolean | `false` | Render a 'Clear' button next to the input box to remove its contents
`hideBeforeSearch` | boolean | `false` | Only show list options after typing a search query
`staticList` | boolean | `false` | Render results list positioned statically instead of absolutely

65
plugins/woocommerce-admin/packages/components/src/calendar/README.md Normal file
View File

@ -0,0 +1,65 @@
DatePicker
===
## Usage
```jsx
<DatePicker
date={ date }
text={ text }
error={ error }
onUpdate={ ( { date, text, error } ) => setState( { date, text, error } ) }
dateFormat="MM/DD/YYYY"
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`date` | Object | `null` | A moment date object representing the selected date. `null` for no selection
`disabled` | Boolean | `null` | Whether the input is disabled
`text` | String | `null` | The date in human-readable format. Displayed in the text input
`error` | String | `null` | A string error message, shown to the user
`onUpdate` | Function | `null` | (required) A function called upon selection of a date or input change
`dateFormat` | String | `null` | (required) The date format in moment.js-style tokens
`isInvalidDate` | Function | `null` | A function to determine if a day on the calendar is not valid
DateRange
===
This is wrapper for a [react-dates](https://github.com/airbnb/react-dates) powered calendar.
## Usage
```jsx
<DateRange
after={ after }
afterText={ afterText }
before={ before }
beforeText={ beforeText }
onUpdate={ ( update ) => setState( update ) }
shortDateFormat="MM/DD/YYYY"
focusedInput="startDate"
isInvalidDate={ date => (
// not a future date
moment().isBefore( moment( date ), 'date' )
) }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`after` | Object | `null` | A moment date object representing the selected start. `null` for no selection
`afterError` | String | `null` | A string error message, shown to the user
`afterText` | String | `null` | The start date in human-readable format. Displayed in the text input
`before` | Object | `null` | A moment date object representing the selected end. `null` for no selection
`beforeError` | String | `null` | A string error message, shown to the user
`beforeText` | String | `null` | The end date in human-readable format. Displayed in the text input
`focusedInput` | String | `null` | String identifying which is the currently focused input (start or end)
`isInvalidDate` | Function | `null` | A function to determine if a day on the calendar is not valid
`onUpdate` | Function | `null` | (required) A function called upon selection of a date
`shortDateFormat` | String | `null` | (required) The date format in moment.js-style tokens

28
plugins/woocommerce-admin/packages/components/src/card/README.md Normal file
View File

@ -0,0 +1,28 @@
Card
===
A basic card component with a header. The header can contain a title, an action, and an `EllipsisMenu` menu.
## Usage
```jsx
<div>
<Card title="Store Performance" description="Key performance metrics">
<p>Your stuff in a Card.</p>
</Card>
<Card title="Inactive Card" isInactive>
<p>This Card is grayed out and has no box-shadow.</p>
</Card>
</div>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`action` | ReactNode | `null` | One "primary" action for this card, appears in the card header
`className` | String | `null` | Additional CSS classes
`description` | One of type: string, node | `null` | The description displayed beneath the title
`isInactive` | Boolean | `null` | Boolean representing whether the card is inactive or not
`menu` | (custom validator) | `null` | An `EllipsisMenu`, with filters used to control the content visible in this card
`title` | One of type: string, node | `null` | The title to use for this card

106
plugins/woocommerce-admin/packages/components/src/chart/README.md Normal file
View File

@ -0,0 +1,106 @@
Chart
===
A chart container using d3, to display timeseries data with an interactive legend.
## Usage
```jsx
const data = [
{
date: '2018-05-30T00:00:00',
Hoodie: {
label: 'Hoodie',
value: 21599,
},
Sunglasses: {
label: 'Sunglasses',
value: 38537,
},
Cap: {
label: 'Cap',
value: 106010,
},
},
{
date: '2018-05-31T00:00:00',
Hoodie: {
label: 'Hoodie',
value: 14205,
},
Sunglasses: {
label: 'Sunglasses',
value: 24721,
},
Cap: {
label: 'Cap',
value: 70131,
},
},
{
date: '2018-06-01T00:00:00',
Hoodie: {
label: 'Hoodie',
value: 10581,
},
Sunglasses: {
label: 'Sunglasses',
value: 19991,
},
Cap: {
label: 'Cap',
value: 53552,
},
},
{
date: '2018-06-02T00:00:00',
Hoodie: {
label: 'Hoodie',
value: 9250,
},
Sunglasses: {
label: 'Sunglasses',
value: 16072,
},
Cap: {
label: 'Cap',
value: 47821,
},
},
];
<Chart data={ data } title="Example Chart" layout="item-comparison" />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`allowedIntervals` | Array | `null` | Allowed intervals to show in a dropdown
`baseValue` | Number | `0` | Base chart value. If no data value is different than the baseValue, the `emptyMessage` will be displayed if provided
`chartType` | One of: 'bar', 'line' | `'line'` | Chart type of either `line` or `bar`
`data` | Array | `[]` | An array of data
`dateParser` | String | `'%Y-%m-%dT%H:%M:%S'` | Format to parse dates into d3 time format
`emptyMessage` | String | `null` | The message to be displayed if there is no data to render. If no message is provided, nothing will be displayed
`filterParam` | String | `null` | Name of the param used to filter items. If specified, it will be used, in combination with query, to detect which elements are being used by the current filter and must be displayed even if their value is 0
`itemsLabel` | String | `null` | Label describing the legend items
`mode` | One of: 'item-comparison', 'time-comparison' | `'time-comparison'` | `item-comparison` (default) or `time-comparison`, this is used to generate correct ARIA properties
`path` | String | `null` | Current path
`query` | Object | `null` | The query string represented in object form
`interactiveLegend` | Boolean | `true` | Whether the legend items can be activated/deactivated
`interval` | One of: 'hour', 'day', 'week', 'month', 'quarter', 'year' | `'day'` | Interval specification (hourly, daily, weekly etc)
`intervalData` | Object | `null` | Information about the currently selected interval, and set of allowed intervals for the chart. See `getIntervalsForQuery`
`isRequesting` | Boolean | `false` | Render a chart placeholder to signify an in-flight data request
`legendPosition` | One of: 'bottom', 'side', 'top' | `null` | Position the legend must be displayed in. If it's not defined, it's calculated depending on the viewport width and the mode
`legendTotals` | Object | `null` | Values to overwrite the legend totals. If not defined, the sum of all line values will be used
`screenReaderFormat` | One of type: string, func | `'%B %-d, %Y'` | A datetime formatting string or overriding function to format the screen reader labels
`showHeaderControls` | Boolean | `true` | Wether header UI controls must be displayed
`title` | String | `null` | A title describing this chart
`tooltipLabelFormat` | One of type: string, func | `'%B %-d, %Y'` | A datetime formatting string or overriding function to format the tooltip label
`tooltipValueFormat` | One of type: string, func | `','` | A number formatting string or function to format the value displayed in the tooltips
`tooltipTitle` | String | `null` | A string to use as a title for the tooltip. Takes preference over `tooltipLabelFormat`
`valueType` | String | `null` | What type of data is to be displayed? Number, Average, String?
`xFormat` | String | `'%d'` | A datetime formatting string, passed to d3TimeFormat
`x2Format` | String | `'%b %Y'` | A datetime formatting string, passed to d3TimeFormat
`yBelow1Format` | String | `null` | A number formatting string, passed to d3Format
`yFormat` | String | `null` | A number formatting string, passed to d3Format

60
plugins/woocommerce-admin/packages/components/src/chart/docs/example.js
View File

@ -7,27 +7,63 @@ import { Chart } from '@woocommerce/components';
const data = [
{
date: '2018-05-30T00:00:00',
Hoodie: { value: 21599 },
Sunglasses: { value: 38537 },
Cap: { value: 106010 },
Hoodie: {
label: 'Hoodie',
value: 21599,
},
Sunglasses: {
label: 'Sunglasses',
value: 38537,
},
Cap: {
label: 'Cap',
value: 106010,
},
},
{
date: '2018-05-31T00:00:00',
Hoodie: { value: 14205 },
Sunglasses: { value: 24721 },
Cap: { value: 70131 },
Hoodie: {
label: 'Hoodie',
value: 14205,
},
Sunglasses: {
label: 'Sunglasses',
value: 24721,
},
Cap: {
label: 'Cap',
value: 70131,
},
},
{
date: '2018-06-01T00:00:00',
Hoodie: { value: 10581 },
Sunglasses: { value: 19991 },
Cap: { value: 53552 },
Hoodie: {
label: 'Hoodie',
value: 10581,
},
Sunglasses: {
label: 'Sunglasses',
value: 19991,
},
Cap: {
label: 'Cap',
value: 53552,
},
},
{
date: '2018-06-02T00:00:00',
Hoodie: { value: 9250 },
Sunglasses: { value: 16072 },
Cap: { value: 47821 },
Hoodie: {
label: 'Hoodie',
value: 9250,
},
Sunglasses: {
label: 'Sunglasses',
value: 16072,
},
Cap: {
label: 'Cap',
value: 47821,
},
},
];

36
plugins/woocommerce-admin/packages/components/src/compare-filter/README.md Normal file
View File

@ -0,0 +1,36 @@
CompareFilter
===
Displays a card + search used to filter results as a comparison between objects.
## Usage
```jsx
const path = ''; // from React Router
const getLabels = () => Promise.resolve( [] );
const labels = {
helpText: 'Select at least two products to compare',
placeholder: 'Search for products to compare',
title: 'Compare Products',
update: 'Compare',
};
<CompareFilter
type="products"
param="product"
path={ path }
getLabels={ getLabels }
labels={ labels }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`getLabels` | Function | `null` | (required) Function used to fetch object labels via an API request, returns a Promise
`labels` | Object | `{}` | Object of localized labels
`param` | String | `null` | (required) The parameter to use in the querystring
`path` | String | `null` | (required) The `path` parameter supplied by React-Router
`query` | Object | `{}` | The query string represented in object form
`type` | String | `null` | (required) Which type of autocompleter should be used in the Search

17
plugins/woocommerce-admin/packages/components/src/count/README.md Normal file
View File

@ -0,0 +1,17 @@
Count
===
Display a number with a styled border.
## Usage
```jsx
<Count count={ 33 } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`count` | Number | `null` | (required) Value of the number to be displayed
`label` | String | `''` | A translated label with the number in context, used for screen readers

23
plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/README.md
View File

@ -6,7 +6,11 @@ Select a range of dates or single dates
## Usage
```jsx
<DatePicker key={ JSON.stringify( query ) } path={ path } query={ query } />
<DatePicker
key="daterange"
onRangeSelect={ () => {} }
/>
```
### Props
@ -15,17 +19,16 @@ Required props are marked with `*`.
Name | Type | Default | Description
------- | -------- | ------- | ---
`key`* | string | none | Force a recalculation or reset of internal state when this key changes. Useful for a url change, for instance
`path`* | `string` | none | The `path` parameter supplied by React-Router
`query` | `object` | `{}` | The query string represented in object form
`query` | Object | `{}` | The query string represented in object form
`onRangeSelect` | Function | `null` | Callback called when selection is made
## URL as the source of truth
The Date Picker reads parameters from the URL querystring and updates them by creating a link to reflect newly selected parameters, which is rendered as the "Update" button.
URL Parameter | Default | Possible Values
--- | --- | ---
`period` | `today` | `today`, `yesterday`, `week`, `last_week`, `month`, `last_month`, `quarter`, `last_quarter`, `year`, `last_year`, `custom`
`compare` | `previous_period` | `previous_period`, `previous_year`
`start` | none | start date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)
`end` | none | end date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)
URL Parameter | Default | Possible Values
--- | --- | ---
`period` | `today` | `today`, `yesterday`, `week`, `last_week`, `month`, `last_month`, `quarter`, `last_quarter`, `year`, `last_year`, `custom`
`compare` | `previous_period` | `previous_period`, `previous_year`
`start` | none | start date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)
`end` | none | end date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)

10
plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/docs/example.js
View File

@ -7,9 +7,9 @@ import { DateRangeFilterPicker } from '@woocommerce/components';
const query = {};
export default () => (
<DateRangeFilterPicker
key="daterange"
query={ query }
onRangeSelect={ () => {} }
/>
<DateRangeFilterPicker
key="daterange"
query={ query }
onRangeSelect={ () => {} }
/>
);

19
plugins/woocommerce-admin/packages/components/src/date/README.md Normal file
View File

@ -0,0 +1,19 @@
Date
===
Use the `Date` component to display accessible dates or times.
## Usage
```jsx
<Date date="2019-01-01" />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`date` | One of type: string, object | `null` | (required) Date to use in the component
`machineFormat` | String | `'Y-m-d H:i:s'` | Date format used in the `datetime` prop of the `time` element
`screenReaderFormat` | String | `'F j, Y'` | Date format used for screen readers
`visibleFormat` | String | `'Y-m-d'` | Date format displayed in the page

2
plugins/woocommerce-admin/packages/components/src/date/docs/example.js
View File

@ -5,5 +5,5 @@
import { Date } from '@woocommerce/components';
export default () => (
<Date date="2019-01-01" />
<Date date="2019-01-01" />
);

28
plugins/woocommerce-admin/packages/components/src/dropdown-button/README.md Normal file
View File

@ -0,0 +1,28 @@
DropdownButton
===
A button useful for a launcher of a dropdown component. The button is 100% width of its container and displays single or multiple lines rendered as `<span/>` elments.
## Usage
```jsx
<Dropdown
renderToggle={ ( { isOpen, onToggle } ) => (
<DropdownButton
onClick={ onToggle }
isOpen={ isOpen }
labels={ [ 'All Products Sold' ] }
/>
) }
renderContent={ () => (
<p>Dropdown content here</p>
) }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`labels` | Array | `null` | (required) An array of elements to be rendered as the content of the button
`isOpen` | Boolean | `null` | Boolean describing if the dropdown in open or not

97
plugins/woocommerce-admin/packages/components/src/ellipsis-menu/README.md Normal file
View File

@ -0,0 +1,97 @@
EllipsisMenu
===
This is a dropdown menu hidden behind a vertical ellipsis icon. When clicked, the inner MenuItems are displayed.
## Usage
```jsx
<EllipsisMenu label="Choose which analytics to display"
renderContent={ ( { onToggle } )=> {
return (
<div>
<MenuTitle>Display Stats</MenuTitle>
<MenuItem onInvoke={ () => setState( { showCustomers: ! showCustomers } ) }>
<ToggleControl
label="Show Customers"
checked={ showCustomers }
onChange={ () => setState( { showCustomers: ! showCustomers } ) }
/>
</MenuItem>
<MenuItem onInvoke={ () => setState( { showOrders: ! showOrders } ) }>
<ToggleControl
label="Show Orders"
checked={ showOrders }
onChange={ () => setState( { showOrders: ! showOrders } ) }
/>
</MenuItem>
<MenuItem onInvoke={ onToggle }>
<Button
label="Close menu"
onClick={ onToggle }
>
Close Menu
</Button>
</MenuItem>
</div>
);
} }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`label` | String | `null` | (required) The label shown when hovering/focusing on the icon button
`renderContent` | Function | `null` | A function returning `MenuTitle`/`MenuItem` components as a render prop. Arguments from Dropdown passed as function arguments
MenuItem
===
`MenuItem` is used to give the item an accessible wrapper, with the `menuitem` role and added keyboard functionality (`onInvoke`).
`MenuItem`s can also be deemed "clickable", though this is disabled by default because generally the inner component handles
the click event.
## Usage
```jsx
<MenuItem onInvoke={ onToggle }>
<Button
label="Close menu"
onClick={ onToggle }
>
Close Menu
</Button>
</MenuItem>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`checked` | Boolean | `null` | Whether the menu item is checked or not. Only relevant for menu items with `isCheckbox`
`children` | ReactNode | `null` | A renderable component (or string) which will be displayed as the content of this item. Generally a `ToggleControl`
`isCheckbox` | Boolean | `false` | Whether the menu item is a checkbox (will render a FormToggle and use the `menuitemcheckbox` role)
`isClickable` | Boolean | `false` | Boolean to control whether the MenuItem should handle the click event. Defaults to false, assuming your child component handles the click event
`onInvoke` | Function | `null` | (required) A function called when this item is activated via keyboard ENTER or SPACE; or when the item is clicked (only if `isClickable` is set)
MenuTitle
===
`MenuTitle` is another valid Menu child, but this does not have any accessibility attributes associated
(so this should not be used in place of the `EllipsisMenu` prop `label`).
## Usage
```jsx
<MenuTitle>Display Stats</MenuTitle>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`children` | ReactNode | `null` | A renderable component (or string) which will be displayed as the content of this item

33
plugins/woocommerce-admin/packages/components/src/empty-content/README.md Normal file
View File

@ -0,0 +1,33 @@
EmptyContent
===
A component to be used when there is no data to show.
It can be used as an opportunity to provide explanation or guidance to help a user progress.
## Usage
```jsx
<EmptyContent
title="Nothing here"
message="Some descriptive text"
actionLabel="Reload page"
actionURL="#"
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`title` | String | `null` | (required) The title to be displayed
`message` | String | `null` | An additional message to be displayed
`illustration` | String | `'/empty-content.svg'` | The url string of an image path. Prefix with `/` to load an image relative to the plugin directory
`illustrationHeight` | Number | `null` | Height to use for the illustration
`illustrationWidth` | Number | `400` | Width to use for the illustration
`actionLabel` | String | `null` | (required) Label to be used for the primary action button
`actionURL` | String | `null` | URL to be used for the primary action button
`actionCallback` | Function | `null` | Callback to be used for the primary action button
`secondaryActionLabel` | String | `null` | Label to be used for the secondary action button
`secondaryActionURL` | String | `null` | URL to be used for the secondary action button
`secondaryActionCallback` | Function | `null` | Callback to be used for the secondary action button
`className` | String | `null` | Additional CSS classes

33
plugins/woocommerce-admin/packages/components/src/filter-picker/README.md
View File

@ -1,5 +1,5 @@
Filter Picker
=============
===
Modify a url query parameter via a dropdown selection of configurable options. This component manipulates the `filter` query parameter.
@ -44,16 +44,31 @@ const renderFilterPicker = () => {
### Props
* `filters` (required): An array of filters and subFilters to construct the menu
* `path` (required): The `path` parameter supplied by React-Router
* `query`: The query string represented in object form
Name | Type | Default | Description
--- | --- | --- | ---
`config` | Object | `null` | (required) An array of filters and subFilters to construct the menu
`path` | String | `null` | (required) The `path` parameter supplied by React-Router
`query` | Object | `{}` | The query string represented in object form
`onFilterSelect` | Function | `() => {}` | Function to be called after filter selection
### `config` structure
The `config` prop has the following structure:
- `label`: String - A label above the filter selector.
- `staticParams`: Array - Url parameters to persist when selecting a new filter.
- `param`: String - The url paramter this filter will modify.
- `defaultValue`: String - The default paramter value to use instead of 'all'.
- `showFilters`: Function - Determine if the filter should be shown. Supply a function with the query object as an argument returning a boolean.
- `filters`: Array - Array of filter objects.
### `filters` structure
The `filters` prop is an array of filter objects. Each filter object should have the following format:
* `label`: The label for this filter. Optional only for custom component filters.
* `subFilters`: An array of more filter objects that act as "children" to this item. This set of filters is shown if the parent filter is clicked.
* `value` (required): The value for this filter, used to set the `filter` query param when clicked, if there are no `subFilters`.
* `path`: An array representing the "path" to this filter, if nested. See the Lunch > Pescatarian > Snapper example above.
* `component`: A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented.
- `chartMode`: One of: 'item-comparison', 'time-comparison'
- `component`: String - A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented.
- `label`: String - The label for this filter. Optional only for custom component filters.
- `path`: String - An array representing the "path" to this filter, if nested.
- `subFilters`: Array - An array of more filter objects that act as "children" to this item. This set of filters is shown if the parent filter is clicked.
- `value`: String - The value for this filter, used to set the `filter` query param when clicked, if there are no `subFilters`.

68
plugins/woocommerce-admin/packages/components/src/filter-picker/docs/example.js
View File

@ -6,43 +6,43 @@ import { FilterPicker } from '@woocommerce/components';
const path = ( new URL( document.location ) ).searchParams.get( 'path' ) || '/devdocs';
const query = {
meal: 'breakfast',
meal: 'breakfast',
};
const config = {
label: 'Meal',
staticParams: [],
param: 'meal',
showFilters: () => true,
filters: [
{ label: 'Breakfast', value: 'breakfast' },
{
label: 'Lunch',
value: 'lunch',
subFilters: [
{ label: 'Meat', value: 'meat', path: [ 'lunch' ] },
{ label: 'Vegan', value: 'vegan', path: [ 'lunch' ] },
{
label: 'Pescatarian',
value: 'fish',
path: [ 'lunch' ],
subFilters: [
{ label: 'Snapper', value: 'snapper', path: [ 'lunch', 'fish' ] },
{ label: 'Cod', value: 'cod', path: [ 'lunch', 'fish' ] },
// Specify a custom component to render (Work in Progress)
{
label: 'Other',
value: 'other_fish',
path: [ 'lunch', 'fish' ],
component: 'OtherFish',
},
],
},
],
},
{ label: 'Dinner', value: 'dinner' },
],
label: 'Meal',
staticParams: [],
param: 'meal',
showFilters: () => true,
filters: [
{ label: 'Breakfast', value: 'breakfast' },
{
label: 'Lunch',
value: 'lunch',
subFilters: [
{ label: 'Meat', value: 'meat', path: [ 'lunch' ] },
{ label: 'Vegan', value: 'vegan', path: [ 'lunch' ] },
{
label: 'Pescatarian',
value: 'fish',
path: [ 'lunch' ],
subFilters: [
{ label: 'Snapper', value: 'snapper', path: [ 'lunch', 'fish' ] },
{ label: 'Cod', value: 'cod', path: [ 'lunch', 'fish' ] },
// Specify a custom component to render (Work in Progress)
{
label: 'Other',
value: 'other_fish',
path: [ 'lunch', 'fish' ],
component: 'OtherFish',
},
],
},
],
},
{ label: 'Dinner', value: 'dinner' },
],
};
export default () => (
<FilterPicker config={ config } path={ path } query={ query } />
<FilterPicker config={ config } path={ path } query={ query } />
);

18
plugins/woocommerce-admin/packages/components/src/filters/README.md Normal file
View File

@ -0,0 +1,18 @@
ReportFilters
===
Add a collection of report filters to a page. This uses `DatePicker` & `FilterPicker` for the "basic" filters, and `AdvancedFilters`
or a comparison card if "advanced" or "compare" are picked from `FilterPicker`.
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`advancedFilters` | Object | `{}` | Config option passed through to `AdvancedFilters`
`filters` | Array | `[]` | Config option passed through to `FilterPicker` - if not used, `FilterPicker` is not displayed
`path` | String | `null` | (required) The `path` parameter supplied by React-Router
`query` | Object | `{}` | The query string represented in object form
`showDatePicker` | Boolean | `true` | Whether the date picker must be shown
`onDateSelect` | Function | `() => {}` | Function to be called after date selection
`onFilterSelect` | Function | `null` | Function to be called after filter selection
`onAdvancedFilterAction` | Function | `null` | Function to be called after an advanced filter action has been taken

21
plugins/woocommerce-admin/packages/components/src/flag/README.md Normal file
View File

@ -0,0 +1,21 @@
Flag
===
Use the `Flag` component to display a country's flag using the operating system's emojis.
React component.
## Usage
```jsx
<Flag code="VU" size={ 48 } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`code` | String | `null` | Two letter, three letter or three digit country code
`order` | Object | `null` | An order can be passed instead of `code` and the code will automatically be pulled from the billing or shipping data
`className` | String | `null` | Additional CSS classes
`size` | Number | `null` | Supply a font size to be applied to the emoji flag

47
plugins/woocommerce-admin/packages/components/src/form/README.md Normal file
View File

@ -0,0 +1,47 @@
Form
===
A form component to handle form state and provide input helper props.
## Usage
```jsx
const initialValues = { firstName: '' };
<Form
onSubmitCallback={ ( values ) => {} }
initialValues={ initialValues }
>
{ ( {
getInputProps,
values,
errors,
handleSubmit,
} ) => (
<div>
<TextControl
label={ 'First Name' }
{ ...getInputProps( 'firstName' ) }
/>
<Button
isPrimary
onClick={ handleSubmit }
disabled={ Object.keys( errors ).length }
>
Submit
</Button>
</div>
) }
</Form>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`children` | * | `null` | A renderable component in which to pass this component's state and helpers. Generally a number of input or other form elements
`errors` | Object | `{}` | Object of all initial errors to store in state
`initialValues` | Object | `{}` | Object key:value pair list of all initial field values
`onSubmitCallback` | Function | `noop` | Function to call when a form is submitted with valid fields
`validate` | Function | `noop` | A function that is passed a list of all values and should return an `errors` object with error response
`touched` | | `{}` |

23
plugins/woocommerce-admin/packages/components/src/gravatar/README.md Normal file
View File

@ -0,0 +1,23 @@
Gravatar
===
Display a users Gravatar.
## Usage
```jsx
<Gravatar
user="email@example.org"
size={ 48 }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`user` | One of type: object, string | `null` | The address to hash for displaying a Gravatar. Can be an email address or WP-API user object
`alt` | String | `null` | Text to display as the image alt attribute
`title` | String | `null` | Text to use for the image's title
`size` | Number | `60` | Default 60. The size of Gravatar to request
`className` | String | `null` | Additional CSS classes

21
plugins/woocommerce-admin/packages/components/src/image-asset/README.md Normal file
View File

@ -0,0 +1,21 @@
ImageAsset
===
A component that loads an image, allowing images to be loaded relative to the main asset/plugin folder.
Props are passed through to `<img />`
## Usage
```jsx
<ImageAsset
src="https://cldup.com/6L9h56D9Bw.jpg"
alt="An illustration of sunglasses"
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`src` | String | `null` | (required) Image location to pass through to `<img />`
`alt` | String | `null` | (required) Alt text to pass through to `<img />`

23
plugins/woocommerce-admin/packages/components/src/link/README.md Normal file
View File

@ -0,0 +1,23 @@
Link
===
Use `Link` to create a link to another resource. It accepts a type to automatically
create wp-admin links, wc-admin links, and external links.
## Usage
```jsx
<Link
href="edit.php?post_type=shop_coupon"
type="wp-admin"
>
Coupons
</Link>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`href` | String | `null` | (required) The resource to link to
`type` | One of: 'wp-admin', 'wc-admin', 'external' | `'wc-admin'` | Type of link. For wp-admin and wc-admin, the correct prefix is appended

51
plugins/woocommerce-admin/packages/components/src/list/README.md Normal file
View File

@ -0,0 +1,51 @@
List
===
List component to display a list of items.
## Usage
```jsx
const listItems = [
{
title: 'List item title',
description: 'List item description text',
},
{
before: <Gridicon icon="star" />,
title: 'List item with before icon',
description: 'List item description text',
},
{
before: <Gridicon icon="star" />,
after: <Gridicon icon="chevron-right" />,
title: 'List item with before and after icons',
description: 'List item description text',
},
{
title: 'Clickable list item',
description: 'List item description text',
onClick: () => alert( 'List item clicked' ),
},
];
<List items={ listItems } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional class name to style the component
`items` | Array | `null` | (required) An array of list items
`items` structure:
* `after`: ReactNode - Content displayed after the list item text.
* `before`: ReactNode - Content displayed before the list item text.
* `className`: String - Additional class name to style the list item.
* `description`: String - Description displayed beneath the list item title.
* `href`: String - Href attribute used in a Link wrapped around the item.
* `onClick`: Function - Called when the list item is clicked.
* `target`: String - Target attribute used for Link wrapper.
* `title`: String - Title displayed for the list item.

2
plugins/woocommerce-admin/packages/components/src/list/index.js
View File

@ -117,7 +117,7 @@ List.propTypes = {
*/
href: PropTypes.string,
/**
* Content displayed after the list item text.
* Called when the list item is clicked.
*/
onClick: PropTypes.func,
/**

19
plugins/woocommerce-admin/packages/components/src/order-status/README.md Normal file
View File

@ -0,0 +1,19 @@
OrderStatus
===
Use `OrderStatus` to display a badge with human-friendly text describing the current order status.
## Usage
```jsx
const order = { status: 'processing' }; // Use a real WooCommerce Order here.
<OrderStatus order={ order } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`order` | Object | `null` | (required) The order to display a status for. See: https://woocommerce.github.io/woocommerce-rest-api-docs/#order-properties
`className` | String | `null` | Additional CSS classes

28
plugins/woocommerce-admin/packages/components/src/pagination/README.md Normal file
View File

@ -0,0 +1,28 @@
Pagination
===
Use `Pagination` to allow navigation between pages that represent a collection of items.
The component allows for selecting a new page and items per page options.
## Usage
```jsx
<Pagination
page={ 1 }
perPage={ 10 }
total={ 500 }
onPageChange={ ( newPage ) => setState( { page: newPage } ) }
onPerPageChange={ ( newPerPage ) => setState( { perPage: newPerPage } ) }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`page` | Number | `null` | (required) The current page of the collection
`onPageChange` | Function | `noop` | A function to execute when the page is changed
`perPage` | Number | `null` | (required) The amount of results that are being displayed per page
`onPerPageChange` | Function | `noop` | A function to execute when the per page option is changed
`total` | Number | `null` | (required) The total number of results
`className` | String | `null` | Additional classNames

31
plugins/woocommerce-admin/packages/components/src/product-image/README.md Normal file
View File

@ -0,0 +1,31 @@
ProductImage
===
Use `ProductImage` to display a product's or variation's featured image.
If no image can be found, a placeholder matching the front-end image
placeholder will be displayed.
## Usage
```jsx
// Use a real WooCommerce Product here.
const product = {
images: [
{
src: 'https://cldup.com/6L9h56D9Bw.jpg',
},
],
};
<ProductImage product={ product } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`width` | Number | `60` | The width of image to display
`height` | Number | `60` | The height of image to display
`className` | String | `''` | Additional CSS classes
`product` | Object | `null` | Product or variation object. The image to display will be pulled from `product.images` or `variation.image`. See https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties and https://woocommerce.github.io/woocommerce-rest-api-docs/#product-variation-properties
`alt` | String | `null` | Text to use as the image alt attribute

2
plugins/woocommerce-admin/packages/components/src/product-image/docs/example.js
View File

@ -10,7 +10,7 @@ export default () => (
<ProductImage product={ { images: [] } } />
<ProductImage product={ { images: [
{
src: 'https://i.cloudup.com/pt4DjwRB84-3000x3000.png',
src: 'https://cldup.com/6L9h56D9Bw.jpg',
},
] } } />
</div>

62
plugins/woocommerce-admin/packages/components/src/rating/README.md Normal file
View File

@ -0,0 +1,62 @@
Rating
===
Use `Rating` to display a set of stars, filled, empty or half-filled, that represents a
rating in a scale between 0 and the prop `totalStars` (default 5).
## Usage
```jsx
<Rating rating={ 2.5 } totalStars={ 6 } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`rating` | Number | `0` | Number of stars that should be filled. You can pass a partial number of stars like `2.5`
`totalStars` | Number | `5` | The total number of stars the rating is out of
`size` | Number | `18` | The size in pixels the stars should be rendered at
`className` | String | `null` | Additional CSS classes
ProductRating
===
Display a set of stars representing the product's average rating.
## Usage
```jsx
// Use a real WooCommerce Product here.
const product = { average_rating: 3.5 };
<ProductRating product={ product } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`product` | Object | `null` | (required) A product object containing a `average_rating`. See https://woocommerce.github.io/woocommerce-rest-api-docs/#products
ReviewRating
===
Display a set of stars representing the review's rating.
## Usage
```jsx
// Use a real WooCommerce Review here.
const review = { rating: 5 };
<ReviewRating review={ review } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`review` | Object | `null` | (required) A review object containing a `rating`. See https://woocommerce.github.io/woocommerce-rest-api-docs/#retrieve-product-reviews

73
plugins/woocommerce-admin/packages/components/src/search-list-control/README.md Normal file
View File

@ -0,0 +1,73 @@
SearchListControl
===
Component to display a searchable, selectable list of items.
## Usage
```jsx
<SearchListControl
list={ list }
isLoading={ loading }
selected={ selected }
onChange={ items => setState( { selected: items } ) }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional CSS classes
`isHierarchical` | Boolean | `null` | Whether the list of items is hierarchical or not. If true, each list item is expected to have a parent property
`isLoading` | Boolean | `null` | Whether the list of items is still loading
`isSingle` | Boolean | `null` | Restrict selections to one item
`list` | Array | `null` | A complete list of item objects, each with id, name properties. This is displayed as a clickable/keyboard-able list, and possibly filtered by the search term (searches name)
`messages` | Object | `null` | Messages displayed or read to the user. Configure these to reflect your object type. See `defaultMessages` above for examples
`onChange` | Function | `null` | (required) Callback fired when selected items change, whether added, cleared, or removed. Passed an array of item objects (as passed in via props.list)
`onSearch` | Function | `null` | Callback fired when the search field is used
`renderItem` | Function | `null` | Callback to render each item in the selection list, allows any custom object-type rendering
`selected` | Array | `null` | (required) The list of currently selected items
`search` | String | `null` |
`setState` | Function | `null` |
`debouncedSpeak` | Function | `null` |
`instanceId` | Number | `null` |
### `list` item structure:
- `id`: Number
- `name`: String
### `messages` object structure:
- `clear`: String - A more detailed label for the "Clear all" button, read to screen reader users.
- `list`: String - Label for the list of selectable items, only read to screen reader users.
- `noItems`: String - Message to display when the list is empty (implies nothing loaded from the server
or parent component).
- `noResults`: String - Message to display when no matching results are found. %s is the search term.
- `search`: String - Label for the search input
- `selected`: Function - Label for the selected items. This is actually a function, so that we can pass
through the count of currently selected items.
- `updated`: String - Label indicating that search results have changed, read to screen reader users.
SearchListItem
===
## Usage
Used implicitly by `SearchListControl` when the `renderItem` prop is omitted.
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional CSS classes
`countLabel` | ReactNode | `null` | Label to display if `showCount` is set to true. If undefined, it will use `item.count`
`depth` | Number | `0` | Depth, non-zero if the list is hierarchical
`item` | Object | `null` | Current item to display
`isSelected` | Boolean | `null` | Whether this item is selected
`isSingle` | Boolean | `null` | Whether this should only display a single item (controls radio vs checkbox icon)
`onSelect` | Function | `null` | Callback for selecting the item
`search` | String | `''` | Search string, used to highlight the substring in the item name
`showCount` | Boolean | `false` | Toggles the "count" bubble on/off

36
plugins/woocommerce-admin/packages/components/src/search/README.md Normal file
View File

@ -0,0 +1,36 @@
Search
===
A search box which autocompletes results while typing, allowing for the user to select an existing object
(product, order, customer, etc). Currently only products are supported.
## Usage
```jsx
<Search
type="products"
placeholder="Search for a product"
selected={ selected }
onChange={ items => setState( { selected: items } ) }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`allowFreeTextSearch` | Boolean | `false` | Render additional options in the autocompleter to allow free text entering depending on the type
`className` | String | `null` | Class name applied to parent div
`onChange` | Function | `noop` | Function called when selected results change, passed result list
`type` | One of: 'categories', 'countries', 'coupons', 'customers', 'downloadIps', 'emails', 'orders', 'products', 'taxes', 'usernames', 'variations' | `null` | (required) The object type to be used in searching
`placeholder` | String | `null` | A placeholder for the search input
`selected` | Array | `[]` | An array of objects describing selected values. If the label of the selected value is omitted, the Tag of that value will not be rendered inside the search box.
`inlineTags` | Boolean | `false` | Render tags inside input, otherwise render below input
`showClearButton` | Boolean | `false` | Render a 'Clear' button next to the input box to remove its contents
`staticResults` | Boolean | `false` | Render results list positioned statically instead of absolutely
`disabled` | Boolean | `false` | Whether the control is disabled or not
### `selected` item structure:
- `id`: One of type: number, string
- `label`: String

18
plugins/woocommerce-admin/packages/components/src/section-header/README.md Normal file
View File

@ -0,0 +1,18 @@
SectionHeader
===
A header component. The header can contain a title, actions via children, and an `EllipsisMenu` menu.
## Usage
```jsx
<SectionHeader title="Section Title" />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional CSS classes
`menu` | (custom validator) | `null` | An `EllipsisMenu`, with filters used to control the content visible in this card
`title` | One of type: string, node | `null` | (required) The title to use for this card

38
plugins/woocommerce-admin/packages/components/src/section/README.md Normal file
View File

@ -0,0 +1,38 @@
H
===
These components are used to frame out the page content for accessible heading hierarchy. Instead of defining fixed heading levels
(`h2`, `h3`, …) you can use `<H />` to create "section headings", which look to the parent `<Section />`s for the appropriate
heading level.
## Usage
```jsx
<div>
<H>Header using a contextual level (h3)</H>
<Section component="article">
<p>This is an article component wrapper.</p>
<H>Another header with contextual level (h4)</H>
<Section component={ false }>
<p>There is no wrapper component here.</p>
<H>This is an h5</H>
</Section>
</Section>
</div>
```
Section
===
The section wrapper, used to indicate a sub-section (and change the header level context).
## Usage
See above
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`component` | One of type: func, string, bool | `null` | The wrapper component for this section. Optional, defaults to `div`. If passed false, no wrapper is used. Additional props passed to Section are passed on to the component
`children` | ReactNode | `null` | The children inside this section, rendered in the `component`. This increases the context level for the next heading used

39
plugins/woocommerce-admin/packages/components/src/segmented-selection/README.md Normal file
View File

@ -0,0 +1,39 @@
SegmentedSelection
===
Create a panel of styled selectable options rendering stylized checkboxes and labels
## Usage
```jsx
<SegmentedSelection
options={ [
{ value: 'one', label: 'One' },
{ value: 'two', label: 'Two' },
{ value: 'three', label: 'Three' },
{ value: 'four', label: 'Four' },
] }
selected={ selected }
legend="Select a number"
onSelect={ ( data ) => setState( { selected: data[ name ] } ) }
name={ name }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional CSS classes
`options` | Array | `null` | (required) An Array of options to render. The array needs to be composed of objects with properties `label` and `value`
`selected` | String | `null` | Value of selected item
`onSelect` | Function | `null` | (required) Callback to be executed after selection
`name` | String | `null` | (required) This will be the key in the key and value arguments supplied to `onSelect`
`legend` | String | `null` | (required) Create a legend visible to screen readers
### `options` structure
The `options` array needs to be composed of objects with properties:
- `value`: String - Input value for this option.
- `label`: String - Label for this option.

45
plugins/woocommerce-admin/packages/components/src/simple-select-control/README.md Normal file
View File

@ -0,0 +1,45 @@
SimpleSelectControl
===
A component for displaying a material styled 'simple' select control.
## Usage
```jsx
const petOptions = [
{
value: 'cat',
label: 'Cat',
},
{
value: 'dog',
label: 'Dog',
},
];
<SimpleSelectControl
label="What is your favorite pet?"
onChange={ value => this.setState( { pet: value } ) }
options={ petOptions }
value={ pet }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional class name to style the component
`label` | String | `null` | A label to use for the main select element
`options` | Array | `null` | An array of options to use for the dropddown
`onChange` | Function | `null` | A function that receives the value of the new option that is being selected as input
`value` | String | `null` | The currently value of the select element
`help` | One of type: string, node | `null` | If this property is added, a help text will be generated using help property as the content
### `options` structure
The `options` array needs to be composed of objects with properties:
- `value`: String - Input value for this option.
- `label`: String - Label for this option.
- `disabled`: Boolean - Disable the option.

16
plugins/woocommerce-admin/packages/components/src/spinner/README.md Normal file
View File

@ -0,0 +1,16 @@
Spinner
===
Spinner - An indeterminate circular progress indicator.
## Usage
```jsx
<Spinner />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional class name to style the component

46
plugins/woocommerce-admin/packages/components/src/split-button/README.md Normal file
View File

@ -0,0 +1,46 @@
SplitButton
===
A component for displaying a button with a main action plus a secondary set of actions behind a menu toggle.
## Usage
```jsx
<SplitButton
isPrimary
mainLabel="Primary Button"
menuLabel="Select an action"
onClick={ () => alert( 'Primary Main Action clicked' ) }
controls={ [
{
label: 'Up',
onClick: () => alert( 'Primary Up clicked' ),
},
{
label: 'Down',
icon: <Gridicon icon="arrow-down" />,
onClick: () => alert( 'Primary Down clicked' ),
},
] }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`isPrimary` | Boolean | `false` | Whether the button is styled as a primary button
`mainIcon` | ReactNode | `null` | Icon for the main button
`mainLabel` | String | `null` | Label for the main button
`onClick` | Function | `noop` | Function to activate when the the main button is clicked
`menuLabel` | String | `null` | Label to display for the menu of actions, used as a heading on the mobile popover and for accessible text
`controls` | Array | `null` | (required) An array of additional actions. Accepts additional icon, label, and onClick props
`className` | String | `null` | Additional CSS classes
### `controls` structure
Array of additional actions with properties:
- `icon`: One of type: string, element
- `label`: String - Label displayed for this button.
- `onClick`: Function - Click handler for this button.

49
plugins/woocommerce-admin/packages/components/src/stepper/README.md Normal file
View File

@ -0,0 +1,49 @@
Stepper
===
A stepper component to indicate progress in a set number of steps.
## Usage
```jsx
const steps = [
{
key: 'first',
label: 'First',
description: 'Step item description',
content: <div>First step content.</div>,
},
{
key: 'second',
label: 'Second',
description: 'Step item description',
content: <div>Second step content.</div>,
},
];
<Stepper
steps={ steps }
currentStep="first"
isPending={ true }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional class name to style the component
`currentStep` | String | `null` | (required) The current step's key
`steps` | Array | `null` | (required) An array of steps used
`isVertical` | Boolean | `false` | If the stepper is vertical instead of horizontal
`isPending` | Boolean | `false` | Optionally mark the current step as pending to show a spinner
### `steps` structure
Array of step objects with properties:
- `key:` String - Key used to identify step.
- `label`: String - Label displayed in stepper.
- `description`: String - Description displayed beneath the label.
- `isComplete`: Boolean - Optionally mark a step complete regardless of step index.
- `content`: ReactNode - Content displayed when the step is active.

82
plugins/woocommerce-admin/packages/components/src/summary/README.md Normal file
View File

@ -0,0 +1,82 @@
SummaryList
===
A container element for a list of SummaryNumbers. This component handles detecting & switching to the mobile format on smaller screens.
## Usage
```jsx
<SummaryList>
{ () => {
return [
<SummaryNumber
key="revenue"
value={ '$829.40' }
label="Gross Revenue"
delta={ 29 }
href="/analytics/report"
/>,
<SummaryNumber
key="refunds"
value={ '$24.00' }
label="Refunds"
delta={ -10 }
href="/analytics/report"
selected
/>,
];
} }
</SummaryList>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`children` | Function | `null` | (required) A function returning a list of `<SummaryNumber />`s
`label` | String | `__( 'Performance Indicators', 'woocommerce-admin' )` | An optional label of this group, read to screen reader users
SummaryNumber
===
A component to show a value, label, and an optional change percentage. Can also act as a link to a specific report focus.
## Usage
See above
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`delta` | Number | `null` | A number to represent the percentage change since the last comparison period - positive numbers will show a green up arrow, negative numbers will show a red down arrow, and zero will show a flat right arrow. If omitted, no change value will display
`href` | String | `''` | An internal link to the report focused on this number
`isOpen` | Boolean | `false` | Boolean describing whether the menu list is open. Only applies in mobile view, and only applies to the toggle-able item (first in the list)
`label` | String | `null` | (required) A string description of this value, ex "Revenue", or "New Customers"
`onToggle` | Function | `null` | A function used to switch the given SummaryNumber to a button, and called on click
`prevLabel` | String | `__( 'Previous Period:', 'woocommerce-admin' )` | A string description of the previous value's timeframe, ex "Previous Year:"
`prevValue` | One of type: number, string | `null` | A string or number value to display - a string is allowed so we can accept currency formatting. If omitted, this section won't display
`reverseTrend` | Boolean | `false` | A boolean used to indicate that a negative delta is "good", and should be styled like a positive (and vice-versa)
`selected` | Boolean | `false` | A boolean used to show a highlight style on this number
`value` | One of type: number, string | `null` | A string or number value to display - a string is allowed so we can accept currency formatting
`onLinkClickCallback` | Function | `noop` | A function to be called after a SummaryNumber, rendered as a link, is clicked
SummaryListPlaceholder
===
`SummaryListPlaceholder` behaves like `SummaryList` but displays placeholder summary items instead of data. This can be used while loading data.
## Usage
```jsx
<SummaryListPlaceholder numberOfItems={ 2 } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`numberOfItems` | Number | `null` | (required) An integer with the number of summary items to display
`numberOfRows` | | `5` |

251
plugins/woocommerce-admin/packages/components/src/table/README.md Normal file
View File

@ -0,0 +1,251 @@
TableCard
===
This is an accessible, sortable, and scrollable table for displaying tabular data (like revenue and other analytics data).
It accepts `headers` for column headers, and `rows` for the table content.
`rowHeader` can be used to define the index of the row header (or false if no header).
`TableCard` serves as Card wrapper & contains a card header, `<Table />`, `<TableSummary />`, and `<Pagination />`.
This includes filtering and comparison functionality for report pages.
## Usage
```jsx
const headers = [
{ key: 'month', label: 'Month' },
{ key: 'orders', label: 'Orders' },
{ key: 'revenue', label: 'Revenue' },
];
const rows = [
[
{ display: 'January', value: 1 },
{ display: 10, value: 10 },
{ display: '$530.00', value: 530 },
],
[
{ display: 'February', value: 2 },
{ display: 13, value: 13 },
{ display: '$675.00', value: 675 },
],
[
{ display: 'March', value: 3 },
{ display: 9, value: 9 },
{ display: '$460.00', value: 460 },
],
];
const summary = [
{ label: 'Gross Income', value: '$830.00' },
{ label: 'Taxes', value: '$96.32' },
{ label: 'Shipping', value: '$50.00' },
];
<TableCard
title="Revenue Last Week"
rows={ rows }
headers={ headers }
query={ { page: 2 } }
rowsPerPage={ 7 }
totalRows={ 10 }
summary={ summary }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`compareBy` | String | `null` | The string to use as a query parameter when comparing row items
`compareParam` | String | `'filter'` | Url query parameter compare function operates on
`headers` | Array | `null` | An array of column headers (see `Table` props)
`labels` | Object | `null` | Custom labels for table header actions
`ids` | Array | `null` | A list of IDs, matching to the row list so that ids[ 0 ] contains the object ID for the object displayed in row[ 0 ]
`isLoading` | Boolean | `false` | Defines if the table contents are loading. It will display `TablePlaceholder` component instead of `Table` if that's the case
`onQueryChange` | Function | `noop` | A function which returns a callback function to update the query string for a given `param`
`onColumnsChange` | Function | `noop` | A function which returns a callback function which is called upon the user changing the visiblity of columns
`onSearch` | Function | `noop` | A function which is called upon the user searching in the table header
`onSort` | Function | `undefined` | A function which is called upon the user changing the sorting of the table
`downloadable` | Boolean | `false` | Whether the table must be downloadable. If true, the download button will appear
`onClickDownload` | Function | `null` | A callback function called when the "download" button is pressed. Optional, if used, the download button will appear
`query` | Object | `{}` | An object of the query parameters passed to the page, ex `{ page: 2, per_page: 5 }`
`rowHeader` | One of type: number, bool | `0` | An array of arrays of display/value object pairs (see `Table` props)
`rows` | Array | `[]` | Which column should be the row header, defaults to the first item (`0`) (see `Table` props)
`rowsPerPage` | Number | `null` | (required) The total number of rows to display per page
`searchBy` | String | `null` | The string to use as a query parameter when searching row items
`showMenu` | Boolean | `true` | Boolean to determine whether or not ellipsis menu is shown
`summary` | Array | `null` | An array of objects with `label` & `value` properties, which display in a line under the table. Optional, can be left off to show no summary
`title` | String | `null` | (required) The title used in the card header, also used as the caption for the content in this table
`totalRows` | Number | `null` | (required) The total number of rows (across all pages)
`baseSearchQuery` | Object | `{}` | Pass in query parameters to be included in the path when onSearch creates a new url
### `labels` structure
Table header action labels object with properties:
- `compareButton`: String - Compare button label
- `downloadButton`: String - Download button label
- `helpText`: String -
- `placeholder`: String -
### `summary` structure
Array of summary items objects with properties:
- `label`: ReactNode
- `value`: One of type: string, number
EmptyTable
===
`EmptyTable` displays a blank space with an optional message passed as a children node
with the purpose of replacing a table with no rows.
It mimics the same height a table would have according to the `numberOfRows` prop.
## Usage
```jsx
<EmptyTable>
There are no entries.
</EmptyTable>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`numberOfRows` | Number | `5` | An integer with the number of rows the box should occupy
TablePlaceholder
===
`TablePlaceholder` behaves like `Table` but displays placeholder boxes instead of data. This can be used while loading.
## Usage
```jsx
const headers = [
{ key: 'month', label: 'Month' },
{ key: 'orders', label: 'Orders' },
{ key: 'revenue', label: 'Revenue' },
];
<TablePlaceholder
caption="Revenue Last Week"
headers={ headers }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`query` | Object | `null` | An object of the query parameters passed to the page, ex `{ page: 2, per_page: 5 }`
`caption` | String | `null` | (required) A label for the content in this table
`headers` | Array | `null` | An array of column headers (see `Table` props)
`numberOfRows` | Number | `5` | An integer with the number of rows to display
TableSummary
===
A component to display summarized table data - the list of data passed in on a single line.
## Usage
```jsx
const summary = [
{ label: 'Gross Income', value: '$830.00' },
{ label: 'Taxes', value: '$96.32' },
{ label: 'Shipping', value: '$50.00' },
];
<TableSummary data={ summary } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`data` | Array | `null` | An array of objects with `label` & `value` properties, which display on a single line
Table
===
A table component, without the Card wrapper. This is a basic table display, sortable, but no default filtering.
Row data should be passed to the component as a list of arrays, where each array is a row in the table.
Headers are passed in separately as an array of objects with column-related properties. For example,
this data would render the following table.
```js
const headers = [ { label: 'Month' }, { label: 'Orders' }, { label: 'Revenue' } ];
const rows = [
[
{ display: 'January', value: 1 },
{ display: 10, value: 10 },
{ display: '$530.00', value: 530 },
],
[
{ display: 'February', value: 2 },
{ display: 13, value: 13 },
{ display: '$675.00', value: 675 },
],
[
{ display: 'March', value: 3 },
{ display: 9, value: 9 },
{ display: '$460.00', value: 460 },
],
]
```
| Month | Orders | Revenue |
| ---------|--------|---------|
| January | 10 | $530.00 |
| February | 13 | $675.00 |
| March | 9 | $460.00 |
## Usage
```jsx
<Table
caption="Revenue Last Week"
rows={ rows }
headers={ headers }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`ariaHidden` | Boolean | `false` | Controls whether this component is hidden from screen readers. Used by the loading state, before there is data to read. Don't use this on real tables unless the table data is loaded elsewhere on the page
`caption` | String | `null` | (required) A label for the content in this table
`className` | String | `null` | Additional CSS classes
`headers` | Array | `[]` | An array of column headers, as objects
`onSort` | Function | `noop` | A function called when sortable table headers are clicked, gets the `header.key` as argument
`query` | Object | `{}` | The query string represented in object form
`rows` | Array | `null` | (required) An array of arrays of display/value object pairs
`rowHeader` | One of type: number, bool | `0` | Which column should be the row header, defaults to the first item (`0`) (but could be set to `1`, if the first col is checkboxes, for example). Set to false to disable row headers
### `headers` structure
Array of column header objects with properties:
- `defaultSort`: Boolean - Boolean, true if this column is the default for sorting. Only one column should have this set.
- `defaultOrder`: String - String, asc|desc if this column is the default for sorting. Only one column should have this set.
- `isLeftAligned`: Boolean - Boolean, true if this column should be aligned to the left.
- `isNumeric`: Boolean - Boolean, true if this column is a number value.
- `isSortable`: Boolean - Boolean, true if this column is sortable.
- `key`: String - The API parameter name for this column, passed to `orderby` when sorting via API.
- `label`: ReactNode - The display label for this column.
- `required`: Boolean - Boolean, true if this column should always display in the table (not shown in toggle-able list).
- `screenReaderLabel`: String - The label used for screen readers for this column.
### `rows` structure
Array of arrays representing rows and columns. Column object properties:
- `display`: ReactNode - Display value, used for rendering - strings or elements are best here.
- `value`: One of type: string, number, bool

25
plugins/woocommerce-admin/packages/components/src/tag/README.md Normal file
View File

@ -0,0 +1,25 @@
Tag
===
This component can be used to show an item styled as a "tag", optionally with an `X` + "remove"
or with a popover that is shown on click.
## Usage
```jsx
<Tag label="My tag" id={ 1 } />
<Tag label="Removable tag" id={ 2 } remove={ noop } />
<Tag label="Tag with popover" popoverContents={ ( <p>This is a popover</p> ) } />
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`id` | One of type: number, string | `null` | The ID for this item, used in the remove function
`label` | String | `null` | (required) The name for this item, displayed as the tag's text
`popoverContents` | ReactNode | `null` | Contents to display on click in a popover
`remove` | Function | `null` | A function called when the remove X is clicked. If not used, no X icon will display
`screenReaderLabel` | String | `null` | A more descriptive label for screen reader users. Defaults to the `name` prop

37
plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/README.md Normal file
View File

@ -0,0 +1,37 @@
TextControlWithAffixes
===
This component is essentially a wrapper (really a reimplementation) around the
TextControl component that adds support for affixes, i.e. the ability to display
a fixed part either at the beginning or at the end of the text input.
## Usage
```jsx
<TextControlWithAffixes
suffix="%"
label="Text field with a suffix"
value={ fourth }
onChange={ value => setState( { fourth: value } ) }
/>
<TextControlWithAffixes
prefix="$"
label="Text field with prefix and help text"
value={ fifth }
onChange={ value => setState( { fifth: value } ) }
help="This is some help text."
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`label` | String | `null` | If this property is added, a label will be generated using label property as the content
`help` | String | `null` | If this property is added, a help text will be generated using help property as the content
`type` | String | `'text'` | Type of the input element to render. Defaults to "text"
`value` | String | `null` | (required) The current value of the input
`className` | String | `null` | The class that will be added with "components-base-control" to the classes of the wrapper div. If no className is passed only components-base-control is used
`onChange` | Function | `null` | (required) A function that receives the value of the input
`prefix` | ReactNode | `null` | Markup to be inserted at the beginning of the input
`suffix` | ReactNode | `null` | Markup to be appended at the end of the input

20
plugins/woocommerce-admin/packages/components/src/view-more-list/README.md Normal file
View File

@ -0,0 +1,20 @@
ViewMoreList
===
This component displays a 'X more' button that displays a list of items on a popover when clicked.
## Usage
```jsx
<ViewMoreList
items={ [ <i>Lorem</i>, <i>Ipsum</i>, <i>Dolor</i>, <i>Sit</i> ] }
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`items` | Array | `[]` | `ReactNodes` to list in the popover

23
plugins/woocommerce-admin/packages/components/src/web-preview/README.md Normal file
View File

@ -0,0 +1,23 @@
WebPreview
===
WebPreview component to display an iframe of another page.
## Usage
```jsx
<WebPreview
title="My Web Preview"
src="https://themes.woocommerce.com/?name=galleria"
/>
```
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`className` | String | `null` | Additional class name to style the component
`loadingContent` | ReactNode | `<Spinner />` | Content shown when iframe is still loading
`onLoad` | Function | `noop` | Function to fire when iframe content is loaded
`src` | String | `null` | (required) Iframe src to load
`title` | String | `null` | (required) Iframe title