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

Merge pull request woocommerce/woocommerce-admin#2872 from woocommerce/update/2844-devdocs-like-calypso 

Update DevDocs to be more Calypso-like
This commit is contained in:
Jeff Stieler 2019-09-23 07:59:32 -07:00 committed by GitHub
parent 5a66f70d21 1c7c051414
commit 628e53c7fa
148 changed files with 2688 additions and 3954 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
plugins/woocommerce-admin/bin/generate-docs/index.js
View File

@ -15,7 +15,6 @@ const {
ANALYTICS_FOLDER, ANALYTICS_FOLDER,
PACKAGES_FOLDER, PACKAGES_FOLDER,
DOCS_FOLDER, DOCS_FOLDER,
deleteExistingDocs,
getExportedFileList, getExportedFileList,
getMdFileName, getMdFileName,
getRealFilePaths, getRealFilePaths,
@ -38,13 +37,10 @@ const fileCollections = [
const tocSections = []; const tocSections = [];
fileCollections.forEach( fileCollection => { fileCollections.forEach( fileCollection => {
// Start by wiping the existing docs. **Change this if we end up manually editing docs**
deleteExistingDocs( fileCollection.route );
// Read components file to get a list of exported files, convert that to a list of absolute paths to public components. // Read components file to get a list of exported files, convert that to a list of absolute paths to public components.
const files = getRealFilePaths( getExportedFileList( path.resolve( fileCollection.folder, 'index.js' ) ), fileCollection.folder ); const files = getRealFilePaths( getExportedFileList( path.resolve( fileCollection.folder, 'index.js' ) ), fileCollection.folder );
// Build documentation // Build documentation for components missing them
buildComponentDocs( files, fileCollection.route ); buildComponentDocs( files, fileCollection.route );
// Concatenate TOC contents // Concatenate TOC contents
@ -87,7 +83,18 @@ function buildComponentDocs( files, route ) {
* @param { boolean } multiple If there are multiple exports in this file, we need to use a different resolver. * @param { boolean } multiple If there are multiple exports in this file, we need to use a different resolver.
*/ */
function buildDocs( fileName, route, content, multiple = false ) { function buildDocs( fileName, route, content, multiple = false ) {
const mdFileName = getMdFileName( fileName, route ); let mdFileName = getMdFileName( fileName, route );
// We symlink our package docs.
if ( 'packages' === route ) {
mdFileName = mdFileName.replace( 'docs/components/packages', 'packages/components/src' );
}
if ( fs.existsSync( mdFileName ) ) {
// Don't overwrite existing files.
return;
}
let markdown; let markdown;
try { try {
@ -118,6 +125,7 @@ function buildDocs( fileName, route, content, multiple = false ) {
function generateMarkdown( docObject ) { function generateMarkdown( docObject ) {
let markdownString = getTitle( docObject.displayName ) + '\n'; let markdownString = getTitle( docObject.displayName ) + '\n';
markdownString += getDescription( docObject.description ) + '\n'; markdownString += getDescription( docObject.description ) + '\n';
markdownString += '## Usage\n\n```jsx\n```\n\n';
markdownString += getProps( docObject.props ); markdownString += getProps( docObject.props );
return markdownString + '\n'; return markdownString + '\n';
} }

46
plugins/woocommerce-admin/bin/generate-docs/lib/file-system.js
View File

@ -18,27 +18,6 @@ const ANALYTICS_FOLDER = path.resolve( __dirname, '../../../client/analytics/com
const PACKAGES_FOLDER = path.resolve( __dirname, '../../../packages/components/src/' ); const PACKAGES_FOLDER = path.resolve( __dirname, '../../../packages/components/src/' );
const DOCS_FOLDER = path.resolve( __dirname, '../../../docs/components/' ); const DOCS_FOLDER = path.resolve( __dirname, '../../../docs/components/' );
/**
* Remove all files in existing docs folder.
* @param { String } route Route of the folder to clean.
*/
function deleteExistingDocs( route ) {
const folderRoute = path.resolve( DOCS_FOLDER, route );
if ( ! isDirectory( folderRoute ) ) {
fs.mkdirSync( folderRoute );
return;
}
const files = fs.readdirSync( folderRoute );
files.map( file => {
if ( 'README.md' === file ) {
return;
}
fs.unlinkSync( path.resolve( folderRoute, file ) );
} );
}
/** /**
* Get an array of files exported from in the given file * Get an array of files exported from in the given file
* *
@ -83,7 +62,13 @@ function getMdFileName( filepath, route, absolute = true ) {
if ( ! fileParts || ! fileParts[ 1 ] ) { if ( ! fileParts || ! fileParts[ 1 ] ) {
return; return;
} }
const name = fileParts[ 1 ].replace( 'src/', '' ).split( '/' )[ 0 ]; let name = fileParts[ 1 ].replace( 'src/', '' ).split( '/' )[ 0 ];
// Package components have a different structure.
if ( 'packages' === route ) {
name += '/README';
}
if ( ! absolute ) { if ( ! absolute ) {
return name + '.md'; return name + '.md';
} }
@ -119,20 +104,6 @@ function getRealFilePaths( files, basePath = PACKAGES_FOLDER ) {
} ); } );
} }
/**
* Check if a directory exists and is not a file.
*
* @param { string } dir A directory path to test.
* @return { boolean } True if this path exists and is a directory.
*/
function isDirectory( dir ) {
if ( ! fs.existsSync( dir ) ) {
return false;
}
const stats = fs.statSync( dir );
return stats && stats.isDirectory();
}
/** /**
* Check if a file exists and is not a directory. * Check if a file exists and is not a directory.
* *
@ -159,7 +130,7 @@ function getTocSection( files, route, title ) {
const mdFiles = files.map( f => getMdFileName( f, route, false ) ).sort(); const mdFiles = files.map( f => getMdFileName( f, route, false ) ).sort();
const toc = uniq( mdFiles ).map( doc => { const toc = uniq( mdFiles ).map( doc => {
const name = camelCaseDash( doc.replace( '.md', '' ) ); const name = camelCaseDash( doc.replace( '.md', '' ).split( '/' )[ 0 ] );
return ` * [${ name }](components/${ route }/${ doc })`; return ` * [${ name }](components/${ route }/${ doc })`;
} ); } );
@ -173,7 +144,6 @@ module.exports = {
DOCS_FOLDER, DOCS_FOLDER,
ANALYTICS_FOLDER, ANALYTICS_FOLDER,
PACKAGES_FOLDER, PACKAGES_FOLDER,
deleteExistingDocs,
getExportedFileList, getExportedFileList,
getMdFileName, getMdFileName,
getRealFilePaths, getRealFilePaths,

35
plugins/woocommerce-admin/bin/generate-docs/lib/formatting.js
View File

@ -42,15 +42,20 @@ function getDescription( description = '' ) {
* @return { string } Formatted string. * @return { string } Formatted string.
*/ */
function getProp( propName, prop ) { function getProp( propName, prop ) {
const lines = [ '### `' + propName + '`\n' ]; const cols = [ '`' + propName + '`' ];
prop.required && lines.push( '- **Required**' );
lines.push( '- Type: ' + getPropType( prop.type, propName ) );
lines.push( '- Default: ' + getPropDefaultValue( prop.defaultValue ) );
lines.push( '' );
prop.description && lines.push( prop.description );
lines.push( '' );
return lines.join( '\n' ); cols.push( getPropType( prop.type, propName ) );
cols.push( '`' + getPropDefaultValue( prop.defaultValue ) + '`' );
let description = ( prop.description || '' ).replace( /(\r\n|\n|\r)+/gm, ' ' ).replace( /\.$/, '' );
if ( prop.required ) {
description = '(required) ' + description;
}
cols.push( description );
return cols.join( ' | ' );
} }
/** /**
@ -63,7 +68,7 @@ function getPropDefaultValue( value ) {
if ( value && value.value ) { if ( value && value.value ) {
return '`' + value.value + '`'; return '`' + value.value + '`';
} }
return 'null'; return '`null`';
} }
/** /**
@ -76,8 +81,13 @@ function getProps( props = {} ) {
if ( Object.keys( props ).length < 1 ) { if ( Object.keys( props ).length < 1 ) {
return ''; return '';
} }
const title = 'Props'; const title = '### Props';
const lines = [ title, stringOfLength( '-', title.length ), '' ]; const lines = [
title,
'',
'Name | Type | Default | Description',
'--- | --- | --- | ---',
];
Object.keys( props ).map( key => { Object.keys( props ).map( key => {
lines.push( getProp( key, props[ key ] ) ); lines.push( getProp( key, props[ key ] ) );
} ); } );
@ -145,8 +155,7 @@ function getPropType( type ) {
* @return { string } Formatted string. * @return { string } Formatted string.
*/ */
function getTitle( name ) { function getTitle( name ) {
const title = '`' + name + '` (component)'; return name + '\n===\n';
return title + '\n' + stringOfLength( '=', title.length ) + '\n';
} }
/** /**

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

@ -4,9 +4,19 @@
*/ */
import { Component } from '@wordpress/element'; import { Component } from '@wordpress/element';
import marked from 'marked'; 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 { class Docs extends Component {
state = { state = {
@ -18,15 +28,14 @@ class Docs extends Component {
} }
getReadme() { getReadme() {
const { filePath, docPath } = this.props; const { filePath } = this.props;
const readme = require( `../../docs/components/${ docPath }/${ filePath }.md` ); const readme = require( `../../packages/components/src/${ filePath }/README.md` );
if ( ! readme ) { if ( ! readme ) {
return; return;
} }
const html = marked( readme );
this.setState( { this.setState( { readme } );
readme: htmlToReactParser.parse( html ),
} );
} }
render() { render() {
@ -34,12 +43,14 @@ class Docs extends Component {
if ( ! readme ) { if ( ! readme ) {
return null; 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; export default Docs;

68
plugins/woocommerce-admin/client/devdocs/example.js
View File

@ -2,78 +2,40 @@
/** /**
* External dependencies * External dependencies
*/ */
import codeBlocks from 'gfm-code-blocks';
import { Component } from '@wordpress/element'; import { Component } from '@wordpress/element';
import { LiveError, LivePreview, LiveProvider } from 'react-live'; import React from 'react';
// Used to provide scope in LivePreview
import { addFilter } from '@wordpress/hooks';
import { withState } from '@wordpress/compose';
import * as wpComponents from '@wordpress/components';
import Gridicon from 'gridicons';
import PropTypes from 'prop-types';
/**
* Internal dependencies
*/
import * as components from 'components';
import * as pkgComponents from '@woocommerce/components';
class Example extends Component { class Example extends Component {
state = { state = {
code: null, example: null,
}; };
componentDidMount() { componentDidMount() {
this.getCode(); this.getExample();
} }
async getCode() { async getExample() {
let readme; let exampleComponent;
try { try {
readme = require( `components/src/${ this.props.filePath }/example.md` ); exampleComponent = require( `components/src/${ this.props.filePath }/docs/example` );
} catch ( e ) { } catch ( e ) {
readme = require( `components/${ this.props.filePath }/example.md` ); console.error( e );
} }
if ( ! readme ) {
if ( ! exampleComponent ) {
return; return;
} }
// Example to render is the first jsx code block that appears in the readme this.setState( {
let code = codeBlocks( readme ).find( block => 'jsx' === block.lang ).code; example: React.createElement( exampleComponent.default || exampleComponent ),
} );
// react-live cannot resolve imports in real time, so we get rid of them
// (dependencies will be injected via the scope property).
code = code.replace( /^.*import.*$/gm, '' );
code = `${ code } render( <${ this.props.render } /> );`;
this.setState( { code } );
} }
render() { render() {
const { code } = this.state; const { example } = this.state;
const scope = {
...wpComponents,
...components,
...pkgComponents,
Component,
withState,
PropTypes,
addFilter,
Gridicon,
};
return code ? ( return <div className="woocommerce-devdocs__example">{ example }</div>;
<LiveProvider
code={ code }
scope={ scope }
className="woocommerce-devdocs__example"
noInline={ true }
>
<LiveError />
<LivePreview />
</LiveProvider>
) : null;
} }
} }

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

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

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

@ -3,7 +3,7 @@
* External dependencies * External dependencies
*/ */
import classnames from 'classnames'; import classnames from 'classnames';
import { Component } from '@wordpress/element'; import { Component, Fragment } from '@wordpress/element';
import { find, get } from 'lodash'; import { find, get } from 'lodash';
/** /**
@ -22,18 +22,16 @@ const camelCaseToSlug = name => {
const getExampleData = example => { const getExampleData = example => {
const componentName = get( example, 'component' ); const componentName = get( example, 'component' );
const filePath = get( example, 'filePath', camelCaseToSlug( componentName ) ); const filePath = get( example, 'filePath', camelCaseToSlug( componentName ) );
const render = get( example, 'render', `My${ componentName }` );
return { return {
componentName, componentName,
filePath, filePath,
render,
}; };
}; };
export default class extends Component { export default class extends Component {
render() { render() {
const { params: { component } } = this.props; const { query: { component } } = this.props;
const className = classnames( 'woocommerce_devdocs', { const className = classnames( 'woocommerce_devdocs', {
'is-single': component, 'is-single': component,
'is-list': ! component, 'is-list': ! component,
@ -48,51 +46,51 @@ export default class extends Component {
return ( return (
<div className={ className }> <div className={ className }>
{ exampleList.map( example => { { exampleList.map( example => {
const { componentName, filePath, render, docPath } = getExampleData( example ); const { componentName, filePath } = getExampleData( example );
const cardClasses = classnames( const cardClasses = classnames(
'woocommerce-devdocs__card', 'woocommerce-devdocs__card',
`woocommerce-devdocs__card--${ filePath }`, `woocommerce-devdocs__card--${ filePath }`,
'woocommerce-analytics__card' 'woocommerce-analytics__card'
); );
return ( return (
<Card <Fragment key={ componentName }>
key={ componentName } <Card
className={ cardClasses } key={ `${ componentName }-example` }
title={ className={ cardClasses }
component ? ( title={
componentName component ? (
) : ( componentName
<Link ) : (
href={ `admin.php?page=wc-admin&path=/devdocs/${ filePath }` } <Link
type="wc-admin" href={ `admin.php?page=wc-admin&path=/devdocs&component=${ filePath }` }
> type="wc-admin"
{ componentName } >
</Link> { componentName }
) </Link>
} )
action={ }
component ? ( action={
<Link href={ '?page=wc-admin&path=/devdocs' } type="wc-admin"> component ? (
Full list <Link href={ '?page=wc-admin&path=/devdocs' } type="wc-admin">
</Link> Full list
) : null </Link>
} ) : null
> }
<ComponentExample >
asyncName={ componentName } <ComponentExample
component={ componentName } asyncName={ componentName }
filePath={ filePath } component={ componentName }
render={ render } filePath={ filePath }
/> />
</Card>
{ component && ( { component && (
<ComponentDocs <ComponentDocs
key={ `${ componentName }-readme` }
componentName={ componentName } componentName={ componentName }
filePath={ filePath } filePath={ filePath }
docPath={ docPath }
/> />
) } ) }
</Card> </Fragment>
); );
} ) } } ) }
</div> </div>

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); linear-gradient(90deg, rgba($core-grey-dark-800, 0.025) 1px, transparent 1px);
background-size: 32px 32px, 32px 32px, 8px 8px, 8px 8px; background-size: 32px 32px, 32px 32px, 8px 8px, 8px 8px;
background-position: -1px -1px, -1px -1px, -1px -1px, -1px -1px; background-position: -1px -1px, -1px -1px, -1px -1px, -1px -1px;
.woocommerce-chart {
margin: 0;
}
} }
.woocommerce-devdocs__docs { .woocommerce-devdocs__docs {
max-width: 600px; max-width: 720px;
margin: 0 auto; margin: 0 auto;
padding: $gap; padding: $gap;
@ -54,5 +58,44 @@
h4 code { h4 code {
font-size: 0.9em; 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;
}
} }
} }

17
plugins/woocommerce-admin/client/layout/controller.js
View File

@ -32,13 +32,16 @@ export const getPages = () => {
pages.push( { pages.push( {
container: DevDocs, container: DevDocs,
path: '/devdocs', path: '/devdocs',
breadcrumbs: [ 'Documentation' ], breadcrumbs: ( { location } ) => {
wpOpenMenu: 'toplevel_page_woocommerce', const searchParams = new URLSearchParams( location.search );
} ); const component = searchParams.get( 'component' );
pages.push( {
container: DevDocs, if ( component ) {
path: '/devdocs/:component', return [ [ '/devdocs', 'Documentation' ], component ];
breadcrumbs: ( { match } ) => [ [ '/devdocs', 'Documentation' ], match.params.component ], }
return [ 'Documentation' ];
},
wpOpenMenu: 'toplevel_page_woocommerce', wpOpenMenu: 'toplevel_page_woocommerce',
} ); } );
} }

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'; @import 'node_modules/@automattic/color-studio/dist/color-variables.scss';
$transparent: rgba(255, 255, 255, 0);
// Greys // Greys
$core-grey-light-100: #f8f9f9; $core-grey-light-100: #f8f9f9;
$core-grey-light-200: #f3f4f5; $core-grey-light-200: #f3f4f5;

80
plugins/woocommerce-admin/docs/components/_sidebar.md
View File

@ -8,43 +8,43 @@
* [ReportSummary](components/analytics/report-summary.md) * [ReportSummary](components/analytics/report-summary.md)
* [ReportTable](components/analytics/report-table.md) * [ReportTable](components/analytics/report-table.md)
* [Package components](components/packages/) * [Package components](components/packages/)
* [AdvancedFilters](components/packages/advanced-filters.md) * [AdvancedFilters](components/packages/advanced-filters/README.md)
* [AnimationSlider](components/packages/animation-slider.md) * [AnimationSlider](components/packages/animation-slider/README.md)
* [Autocomplete](components/packages/autocomplete.md) * [Autocomplete](components/packages/autocomplete/README.md)
* [Calendar](components/packages/calendar.md) * [Calendar](components/packages/calendar/README.md)
* [Card](components/packages/card.md) * [Card](components/packages/card/README.md)
* [Chart](components/packages/chart.md) * [Chart](components/packages/chart/README.md)
* [CompareFilter](components/packages/compare-filter.md) * [CompareFilter](components/packages/compare-filter/README.md)
* [Count](components/packages/count.md) * [Count](components/packages/count/README.md)
* [DateRangeFilterPicker](components/packages/date-range-filter-picker.md) * [DateRangeFilterPicker](components/packages/date-range-filter-picker/README.md)
* [Date](components/packages/date.md) * [Date](components/packages/date/README.md)
* [DropdownButton](components/packages/dropdown-button.md) * [DropdownButton](components/packages/dropdown-button/README.md)
* [EllipsisMenu](components/packages/ellipsis-menu.md) * [EllipsisMenu](components/packages/ellipsis-menu/README.md)
* [EmptyContent](components/packages/empty-content.md) * [EmptyContent](components/packages/empty-content/README.md)
* [FilterPicker](components/packages/filter-picker.md) * [FilterPicker](components/packages/filter-picker/README.md)
* [Filters](components/packages/filters.md) * [Filters](components/packages/filters/README.md)
* [Flag](components/packages/flag.md) * [Flag](components/packages/flag/README.md)
* [Form](components/packages/form.md) * [Form](components/packages/form/README.md)
* [Gravatar](components/packages/gravatar.md) * [Gravatar](components/packages/gravatar/README.md)
* [ImageAsset](components/packages/image-asset.md) * [ImageAsset](components/packages/image-asset/README.md)
* [Link](components/packages/link.md) * [Link](components/packages/link/README.md)
* [List](components/packages/list.md) * [List](components/packages/list/README.md)
* [OrderStatus](components/packages/order-status.md) * [OrderStatus](components/packages/order-status/README.md)
* [Pagination](components/packages/pagination.md) * [Pagination](components/packages/pagination/README.md)
* [ProductImage](components/packages/product-image.md) * [ProductImage](components/packages/product-image/README.md)
* [Rating](components/packages/rating.md) * [Rating](components/packages/rating/README.md)
* [SearchListControl](components/packages/search-list-control.md) * [SearchListControl](components/packages/search-list-control/README.md)
* [Search](components/packages/search.md) * [Search](components/packages/search/README.md)
* [SectionHeader](components/packages/section-header.md) * [SectionHeader](components/packages/section-header/README.md)
* [Section](components/packages/section.md) * [Section](components/packages/section/README.md)
* [SegmentedSelection](components/packages/segmented-selection.md) * [SegmentedSelection](components/packages/segmented-selection/README.md)
* [SimpleSelectControl](components/packages/simple-select-control.md) * [SimpleSelectControl](components/packages/simple-select-control/README.md)
* [Spinner](components/packages/spinner.md) * [Spinner](components/packages/spinner/README.md)
* [SplitButton](components/packages/split-button.md) * [SplitButton](components/packages/split-button/README.md)
* [Stepper](components/packages/stepper.md) * [Stepper](components/packages/stepper/README.md)
* [Summary](components/packages/summary.md) * [Summary](components/packages/summary/README.md)
* [Table](components/packages/table.md) * [Table](components/packages/table/README.md)
* [Tag](components/packages/tag.md) * [Tag](components/packages/tag/README.md)
* [TextControlWithAffixes](components/packages/text-control-with-affixes.md) * [TextControlWithAffixes](components/packages/text-control-with-affixes/README.md)
* [ViewMoreList](components/packages/view-more-list.md) * [ViewMoreList](components/packages/view-more-list/README.md)
* [WebPreview](components/packages/web-preview.md) * [WebPreview](components/packages/web-preview/README.md)

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. Component that renders the chart in reports.
Props ## Usage
-----
### `filters` ```jsx
```
- Type: Array ### Props
- Default: null
Filters available for that report. Name | Type | Default | Description
--- | --- | --- | ---
### `isRequesting` `filters` | Array | ``null`` | Filters available for that report
`isRequesting` | Boolean | ``false`` | Whether there is an API call running
- Type: Boolean `itemsLabel` | String | ``null`` | Label describing the legend items
- Default: `false` `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
Whether there is an API call running. `path` | String | ``null`` | (required) Current path
`primaryData` | Object | ``{
### `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: `{
data: { data: {
intervals: [], intervals: [],
}, },
isError: false, isError: false,
isRequesting: false, isRequesting: false,
}` }`` | Primary data to display in the chart
`query` | Object | ``null`` | (required) The query string represented in object form
Primary data to display in the chart. `secondaryData` | Object | ``{
### `query`
- **Required**
- Type: Object
- Default: null
The query string represented in object form.
### `secondaryData`
- Type: Object
- Default: `{
data: { data: {
intervals: [], intervals: [],
}, },
isError: false, isError: false,
isRequesting: false, isRequesting: false,
}` }`` | Secondary data to display in the chart
`selectedChart` | Object
Secondary data to display in the chart.
### `selectedChart`
- **Required**
- Type: Object
- key: String - Key of the selected chart. - key: String - Key of the selected chart.
- label: String - Chart label. - label: String - Chart label.
- order: One of: 'asc', 'desc' - order: One of: 'asc', 'desc'
- orderby: String - Order by query argument. - orderby: String - Order by query argument.
- type: One of: 'average', 'number', 'currency' - type: One of: 'average', 'number', 'currency' | ``null`` | (required) Properties of the selected chart
- Default: null
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 Component to render when there is an error in a report component due to data
not being loaded or being invalid. not being loaded or being invalid.
Props ## Usage
-----
### `className` ```jsx
```
- Type: String ### Props
- 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.
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. Component to render summary numbers in reports.
Props ## Usage
-----
### `charts` ```jsx
```
- **Required** ### Props
- Type: Array
- Default: null
Properties of all the charts available for that report. Name | Type | Default | Description
--- | --- | --- | ---
### `endpoint` `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`
- **Required** `limitProperties` | Array | ``null`` | Allows specifying properties different from the `endpoint` that will be used to limit the items when there is an active search
- Type: String `query` | Object | ``null`` | (required) The query string represented in object form
- Default: null `isRequesting` | Boolean | ``null`` | Whether there is an API call running
`selectedChart` | Object
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
- key: String - Key of the selected chart. - key: String - Key of the selected chart.
- label: String - Chart label. - label: String - Chart label.
- order: One of: 'asc', 'desc' - order: One of: 'asc', 'desc'
- orderby: String - Order by query argument. - orderby: String - Order by query argument.
- type: One of: 'average', 'number', 'currency' - type: One of: 'average', 'number', 'currency' | ``null`` | (required) Properties of the selected chart
- Default: null `summaryData` | Object | ``{
Properties of the selected chart.
### `summaryData`
- Type: Object
- Default: `{
totals: { totals: {
primary: {}, primary: {},
secondary: {}, secondary: {},
}, },
isError: false, isError: false,
isRequesting: false, isRequesting: false,
}` }`` | Data to display in the SummaryNumbers
`report` | String | ``null`` | Report name, if different than the endpoint
Data to display in the SummaryNumbers.
### `report`
- Type: String
- Default: 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. Component that extends `TableCard` to facilitate its usage in reports.
Props ## Usage
-----
### `columnPrefsKey` ```jsx
```
- Type: String ### Props
- Default: null
The key for user preferences settings for column visibility. Name | Type | Default | Description
--- | --- | --- | ---
### `endpoint` `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`
- Type: String `extendItemsMethodNames` | Object
- 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
- getError: String - getError: String
- isRequesting: String - isRequesting: String
- load: String - 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
- Default: null `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
Name of the methods available via `select( 'wc-api' )` that will be used to `getSummary` | Function | ``null`` | A function that returns the summary object to build the table
load more data for table items. If omitted, no call will be made and only `itemIdField` | String | ``null`` | The name of the property in the item object which contains the id
the data returned by the reports endpoint will be used. `primaryData` | Object | ``{}`` | Primary data of that report. If it's not provided, it will be automatically loaded via the provided `endpoint`
`tableData` | Object | ``{
### `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: `{
items: { items: {
data: [], data: [],
totalResults: 0, totalResults: 0,
}, },
query: {}, query: {},
}` }`` | 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
Table data of that report. If it's not provided, it will be automatically `title` | String | ``null`` | (required) String to display as the title of the table
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.

1
plugins/woocommerce-admin/docs/components/packages Symbolic link
View File

@ -0,0 +1 @@
../../packages/components/src/

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

@ -1,38 +0,0 @@
Package Components
==================
This folder contains the WooCommerce-created components. These are exported onto a global, `wc.components`, for general use.
## How to use:
For any files not imported into `components/index.js` (`analytics/*`, `layout/*`, `dashboard/*`, etc), we can use `import { Card, etc … } from @woocommerce/components`.
For any `component/*` files, we should import from component-specific paths, not from `component/index.js`, to prevent circular dependencies. See `components/card/index.js` for an example.
```jsx
import { Card, Link } from '@woocommerce/components';
render: function() {
return (
<Card title="Card demo">
Card content with an <Link href="/">example link.</Link>
</Card>
);
}
```
## For external development
External developers will need to enqueue the components library, `wc-components`, and then can access them from the global.
```jsx
const { Card, Link } = wc.components;
render: function() {
return (
<Card title="Card demo">
Card content with an <Link href="/">example link.</Link>
</Card>
);
}
```

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.

233
plugins/woocommerce-admin/package-lock.json generated
View File

@ -5224,33 +5224,6 @@
"integrity": "sha1-M3dm2hWAEhD92VbCLpxokaudAzc=", "integrity": "sha1-M3dm2hWAEhD92VbCLpxokaudAzc=",
"dev": true "dev": true
}, },
"buble": {
"version": "0.19.8",
"resolved": "https://registry.npmjs.org/buble/-/buble-0.19.8.tgz",
"integrity": "sha512-IoGZzrUTY5fKXVkgGHw3QeXFMUNBFv+9l8a4QJKG1JhG3nCMHTdEX1DCOg8568E2Q9qvAQIiSokv6Jsgx8p2cA==",
"requires": {
"acorn": "^6.1.1",
"acorn-dynamic-import": "^4.0.0",
"acorn-jsx": "^5.0.1",
"chalk": "^2.4.2",
"magic-string": "^0.25.3",
"minimist": "^1.2.0",
"os-homedir": "^2.0.0",
"regexpu-core": "^4.5.4"
},
"dependencies": {
"acorn-dynamic-import": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/acorn-dynamic-import/-/acorn-dynamic-import-4.0.0.tgz",
"integrity": "sha512-d3OEjQV4ROpoflsnUA8HozoIR504TFxNivYEUi6uwz0IYhBkTDXGuWlNdMtybRt3nqVx/L6XqMt0FxkXuWKZhw=="
},
"os-homedir": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/os-homedir/-/os-homedir-2.0.0.tgz",
"integrity": "sha512-saRNz0DSC5C/I++gFIaJTXoFJMRwiP5zHar5vV3xQ2TkgEw6hDCcU5F272JjUylpiVgBrZNQHnfjkLabTfb92Q=="
}
}
},
"buffer": { "buffer": {
"version": "4.9.1", "version": "4.9.1",
"resolved": "https://registry.npmjs.org/buffer/-/buffer-4.9.1.tgz", "resolved": "https://registry.npmjs.org/buffer/-/buffer-4.9.1.tgz",
@ -5878,16 +5851,6 @@
"resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.0.tgz", "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.0.tgz",
"integrity": "sha512-Rd3se6QB+sO1TwqZjscQrurpEPIfO0/yYnSin6Q/rD3mOutHvUrCAhJub3r90uNb+SESBuE0QYoB90YdfatsRg==" "integrity": "sha512-Rd3se6QB+sO1TwqZjscQrurpEPIfO0/yYnSin6Q/rD3mOutHvUrCAhJub3r90uNb+SESBuE0QYoB90YdfatsRg=="
}, },
"component-props": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/component-props/-/component-props-1.1.1.tgz",
"integrity": "sha1-+bffm5kntubZfJvScqqGdnDzSUQ="
},
"component-xor": {
"version": "0.0.4",
"resolved": "https://registry.npmjs.org/component-xor/-/component-xor-0.0.4.tgz",
"integrity": "sha1-xV2DzMG5TNUImk6T+niRxyY+Wao="
},
"concat-map": { "concat-map": {
"version": "0.0.1", "version": "0.0.1",
"resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@ -6752,15 +6715,6 @@
"sha.js": "^2.4.8" "sha.js": "^2.4.8"
} }
}, },
"create-react-context": {
"version": "0.2.3",
"resolved": "https://registry.npmjs.org/create-react-context/-/create-react-context-0.2.3.tgz",
"integrity": "sha512-CQBmD0+QGgTaxDL3OX1IDXYqjkp2It4RIbcb99jS6AEg27Ga+a9G3JtK6SIu0HBwPLZlmwt9F7UwWA4Bn92Rag==",
"requires": {
"fbjs": "^0.8.0",
"gud": "^1.0.0"
}
},
"cross-env": { "cross-env": {
"version": "5.2.1", "version": "5.2.1",
"resolved": "https://registry.npmjs.org/cross-env/-/cross-env-5.2.1.tgz", "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-5.2.1.tgz",
@ -7846,15 +7800,6 @@
"@babel/runtime": "^7.1.2" "@babel/runtime": "^7.1.2"
} }
}, },
"dom-iterator": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/dom-iterator/-/dom-iterator-1.0.0.tgz",
"integrity": "sha512-7dsMOQI07EMU98gQM8NSB3GsAiIeBYIPKpnxR3c9xOvdvBjChAcOM0iJ222I3p5xyiZO9e5oggkNaCusuTdYig==",
"requires": {
"component-props": "1.1.1",
"component-xor": "0.0.4"
}
},
"dom-scroll-into-view": { "dom-scroll-into-view": {
"version": "1.2.1", "version": "1.2.1",
"resolved": "https://registry.npmjs.org/dom-scroll-into-view/-/dom-scroll-into-view-1.2.1.tgz", "resolved": "https://registry.npmjs.org/dom-scroll-into-view/-/dom-scroll-into-view-1.2.1.tgz",
@ -9302,8 +9247,7 @@
}, },
"ansi-regex": { "ansi-regex": {
"version": "2.1.1", "version": "2.1.1",
"bundled": true, "bundled": true
"optional": true
}, },
"aproba": { "aproba": {
"version": "1.2.0", "version": "1.2.0",
@ -9321,13 +9265,11 @@
}, },
"balanced-match": { "balanced-match": {
"version": "1.0.0", "version": "1.0.0",
"bundled": true, "bundled": true
"optional": true
}, },
"brace-expansion": { "brace-expansion": {
"version": "1.1.11", "version": "1.1.11",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"balanced-match": "^1.0.0", "balanced-match": "^1.0.0",
"concat-map": "0.0.1" "concat-map": "0.0.1"
@ -9340,18 +9282,15 @@
}, },
"code-point-at": { "code-point-at": {
"version": "1.1.0", "version": "1.1.0",
"bundled": true, "bundled": true
"optional": true
}, },
"concat-map": { "concat-map": {
"version": "0.0.1", "version": "0.0.1",
"bundled": true, "bundled": true
"optional": true
}, },
"console-control-strings": { "console-control-strings": {
"version": "1.1.0", "version": "1.1.0",
"bundled": true, "bundled": true
"optional": true
}, },
"core-util-is": { "core-util-is": {
"version": "1.0.2", "version": "1.0.2",
@ -9454,8 +9393,7 @@
}, },
"inherits": { "inherits": {
"version": "2.0.3", "version": "2.0.3",
"bundled": true, "bundled": true
"optional": true
}, },
"ini": { "ini": {
"version": "1.3.5", "version": "1.3.5",
@ -9465,7 +9403,6 @@
"is-fullwidth-code-point": { "is-fullwidth-code-point": {
"version": "1.0.0", "version": "1.0.0",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"number-is-nan": "^1.0.0" "number-is-nan": "^1.0.0"
} }
@ -9478,20 +9415,17 @@
"minimatch": { "minimatch": {
"version": "3.0.4", "version": "3.0.4",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"brace-expansion": "^1.1.7" "brace-expansion": "^1.1.7"
} }
}, },
"minimist": { "minimist": {
"version": "0.0.8", "version": "0.0.8",
"bundled": true, "bundled": true
"optional": true
}, },
"minipass": { "minipass": {
"version": "2.3.5", "version": "2.3.5",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"safe-buffer": "^5.1.2", "safe-buffer": "^5.1.2",
"yallist": "^3.0.0" "yallist": "^3.0.0"
@ -9508,7 +9442,6 @@
"mkdirp": { "mkdirp": {
"version": "0.5.1", "version": "0.5.1",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"minimist": "0.0.8" "minimist": "0.0.8"
} }
@ -9581,8 +9514,7 @@
}, },
"number-is-nan": { "number-is-nan": {
"version": "1.0.1", "version": "1.0.1",
"bundled": true, "bundled": true
"optional": true
}, },
"object-assign": { "object-assign": {
"version": "4.1.1", "version": "4.1.1",
@ -9592,7 +9524,6 @@
"once": { "once": {
"version": "1.4.0", "version": "1.4.0",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"wrappy": "1" "wrappy": "1"
} }
@ -9668,8 +9599,7 @@
}, },
"safe-buffer": { "safe-buffer": {
"version": "5.1.2", "version": "5.1.2",
"bundled": true, "bundled": true
"optional": true
}, },
"safer-buffer": { "safer-buffer": {
"version": "2.1.2", "version": "2.1.2",
@ -9699,7 +9629,6 @@
"string-width": { "string-width": {
"version": "1.0.2", "version": "1.0.2",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"code-point-at": "^1.0.0", "code-point-at": "^1.0.0",
"is-fullwidth-code-point": "^1.0.0", "is-fullwidth-code-point": "^1.0.0",
@ -9717,7 +9646,6 @@
"strip-ansi": { "strip-ansi": {
"version": "3.0.1", "version": "3.0.1",
"bundled": true, "bundled": true,
"optional": true,
"requires": { "requires": {
"ansi-regex": "^2.0.0" "ansi-regex": "^2.0.0"
} }
@ -9756,13 +9684,11 @@
}, },
"wrappy": { "wrappy": {
"version": "1.0.2", "version": "1.0.2",
"bundled": true, "bundled": true
"optional": true
}, },
"yallist": { "yallist": {
"version": "3.0.3", "version": "3.0.3",
"bundled": true, "bundled": true
"optional": true
} }
} }
}, },
@ -10019,19 +9945,6 @@
"safe-buffer": "^5.1.1" "safe-buffer": "^5.1.1"
} }
}, },
"gfm-code-block-regex": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/gfm-code-block-regex/-/gfm-code-block-regex-1.0.0.tgz",
"integrity": "sha1-u4PH1ihOa1ty+gIZilisDSViFdI="
},
"gfm-code-blocks": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/gfm-code-blocks/-/gfm-code-blocks-1.0.0.tgz",
"integrity": "sha1-YU0hBZuETGu8nViMCJslxOi8zw0=",
"requires": {
"gfm-code-block-regex": "^1.0.0"
}
},
"git-raw-commits": { "git-raw-commits": {
"version": "2.0.0", "version": "2.0.0",
"resolved": "https://registry.npmjs.org/git-raw-commits/-/git-raw-commits-2.0.0.tgz", "resolved": "https://registry.npmjs.org/git-raw-commits/-/git-raw-commits-2.0.0.tgz",
@ -10878,67 +10791,6 @@
"resolved": "https://registry.npmjs.org/html-tags/-/html-tags-2.0.0.tgz", "resolved": "https://registry.npmjs.org/html-tags/-/html-tags-2.0.0.tgz",
"integrity": "sha1-ELMKOGCF9Dzt41PMj6fLDe7qZos=" "integrity": "sha1-ELMKOGCF9Dzt41PMj6fLDe7qZos="
}, },
"html-to-react": {
"version": "1.4.1",
"resolved": "https://registry.npmjs.org/html-to-react/-/html-to-react-1.4.1.tgz",
"integrity": "sha512-Ys2gGxF8LBF9bD8tbnsU0xgEDOTC3Sy81mtpIH/61hSqGE1l4QetnN1yv0oAK/PuvwABmiNS+ggqvuzo+GfoiA==",
"requires": {
"domhandler": "^3.0",
"htmlparser2": "^4.0",
"lodash.camelcase": "^4.3.0",
"ramda": "^0.26"
},
"dependencies": {
"dom-serializer": {
"version": "0.2.1",
"resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-0.2.1.tgz",
"integrity": "sha512-sK3ujri04WyjwQXVoK4PU3y8ula1stq10GJZpqHIUgoGZdsGzAGu65BnU3d08aTVSvO7mGPZUc0wTEDL+qGE0Q==",
"requires": {
"domelementtype": "^2.0.1",
"entities": "^2.0.0"
}
},
"domelementtype": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.0.1.tgz",
"integrity": "sha512-5HOHUDsYZWV8FGWN0Njbr/Rn7f/eWSQi1v7+HsUVwXgn8nWWlL64zKDkS0n8ZmQ3mlWOMuXOnR+7Nx/5tMO5AQ=="
},
"domhandler": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/domhandler/-/domhandler-3.0.0.tgz",
"integrity": "sha512-eKLdI5v9m67kbXQbJSNn1zjh0SDzvzWVWtX+qEI3eMjZw8daH9k8rlj1FZY9memPwjiskQFbe7vHVVJIAqoEhw==",
"requires": {
"domelementtype": "^2.0.1"
}
},
"domutils": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/domutils/-/domutils-2.0.0.tgz",
"integrity": "sha512-n5SelJ1axbO636c2yUtOGia/IcJtVtlhQbFiVDBZHKV5ReJO1ViX7sFEemtuyoAnBxk5meNSYgA8V4s0271efg==",
"requires": {
"dom-serializer": "^0.2.1",
"domelementtype": "^2.0.1",
"domhandler": "^3.0.0"
}
},
"entities": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/entities/-/entities-2.0.0.tgz",
"integrity": "sha512-D9f7V0JSRwIxlRI2mjMqufDrRDnx8p+eEOz7aUM9SuvF8gsBzra0/6tbjl1m8eQHrZlYj6PxqE00hZ1SAIKPLw=="
},
"htmlparser2": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-4.0.0.tgz",
"integrity": "sha512-cChwXn5Vam57fyXajDtPXL1wTYc8JtLbr2TN76FYu05itVVVealxLowe2B3IEznJG4p9HAYn/0tJaRlGuEglFQ==",
"requires": {
"domelementtype": "^2.0.1",
"domhandler": "^3.0.0",
"domutils": "^2.0.0",
"entities": "^2.0.0"
}
}
}
},
"htmlparser2": { "htmlparser2": {
"version": "3.10.1", "version": "3.10.1",
"resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-3.10.1.tgz", "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-3.10.1.tgz",
@ -12898,11 +12750,6 @@
"integrity": "sha1-DM8tiRZq8Ds2Y8eWU4t1rG4RTZ0=", "integrity": "sha1-DM8tiRZq8Ds2Y8eWU4t1rG4RTZ0=",
"dev": true "dev": true
}, },
"lodash.camelcase": {
"version": "4.3.0",
"resolved": "https://registry.npmjs.org/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz",
"integrity": "sha1-soqmKIorn8ZRA1x3EfZathkDMaY="
},
"lodash.clonedeep": { "lodash.clonedeep": {
"version": "4.5.0", "version": "4.5.0",
"resolved": "https://registry.npmjs.org/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz", "resolved": "https://registry.npmjs.org/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz",
@ -13097,14 +12944,6 @@
"integrity": "sha512-OHhSbtcviqMPt7yfw5ef5aghS2jzFVKEFyCJndQt2YpSQ9qRVSEv2axSJI1paVThEu+FFGs584h/1YhxjVqajA==", "integrity": "sha512-OHhSbtcviqMPt7yfw5ef5aghS2jzFVKEFyCJndQt2YpSQ9qRVSEv2axSJI1paVThEu+FFGs584h/1YhxjVqajA==",
"dev": true "dev": true
}, },
"magic-string": {
"version": "0.25.3",
"resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.25.3.tgz",
"integrity": "sha512-6QK0OpF/phMz0Q2AxILkX2mFhi7m+WMwTRg0LQKq/WBB0cDP4rYH3Wp4/d3OTXlrPLVJT/RFqj8tFeAR4nk8AA==",
"requires": {
"sourcemap-codec": "^1.4.4"
}
},
"make-dir": { "make-dir": {
"version": "2.1.0", "version": "2.1.0",
"resolved": "https://registry.npmjs.org/make-dir/-/make-dir-2.1.0.tgz", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-2.1.0.tgz",
@ -18309,11 +18148,6 @@
"resolved": "https://registry.npmjs.org/railroad-diagrams/-/railroad-diagrams-1.0.0.tgz", "resolved": "https://registry.npmjs.org/railroad-diagrams/-/railroad-diagrams-1.0.0.tgz",
"integrity": "sha1-635iZ1SN3t+4mcG5Dlc3RVnN234=" "integrity": "sha1-635iZ1SN3t+4mcG5Dlc3RVnN234="
}, },
"ramda": {
"version": "0.26.1",
"resolved": "https://registry.npmjs.org/ramda/-/ramda-0.26.1.tgz",
"integrity": "sha512-hLWjpy7EnsDBb0p+Z3B7rPi3GDeRG5ZtiI33kJhTt+ORCd38AbAIjB/9zRIUoeTbE/AVX5ZkU7m6bznsvrf8eQ=="
},
"randexp": { "randexp": {
"version": "0.4.6", "version": "0.4.6",
"resolved": "https://registry.npmjs.org/randexp/-/randexp-0.4.6.tgz", "resolved": "https://registry.npmjs.org/randexp/-/randexp-0.4.6.tgz",
@ -18529,41 +18363,6 @@
"resolved": "https://registry.npmjs.org/react-lifecycles-compat/-/react-lifecycles-compat-3.0.4.tgz", "resolved": "https://registry.npmjs.org/react-lifecycles-compat/-/react-lifecycles-compat-3.0.4.tgz",
"integrity": "sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA==" "integrity": "sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA=="
}, },
"react-live": {
"version": "1.12.0",
"resolved": "https://registry.npmjs.org/react-live/-/react-live-1.12.0.tgz",
"integrity": "sha512-zFEpY01fJORF0IiyONqvjwPLBBDp155Ive6tU8ZmetmT2p4XWUKHstnlu4Cayia+n7iu58Owytztu43yvSin8g==",
"requires": {
"buble": "^0.19.3",
"core-js": "^2.4.1",
"create-react-context": "^0.2.3",
"dom-iterator": "^1.0.0",
"prismjs": "1.6",
"prop-types": "^15.5.8",
"unescape": "^0.2.0"
},
"dependencies": {
"clipboard": {
"version": "1.7.1",
"resolved": "https://registry.npmjs.org/clipboard/-/clipboard-1.7.1.tgz",
"integrity": "sha1-Ng1taUbpmnof7zleQrqStem1oWs=",
"optional": true,
"requires": {
"good-listener": "^1.2.2",
"select": "^1.1.2",
"tiny-emitter": "^2.0.0"
}
},
"prismjs": {
"version": "1.6.0",
"resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.6.0.tgz",
"integrity": "sha1-EY2V+3pm26InLjQ7NF9SNmWds2U=",
"requires": {
"clipboard": "^1.5.5"
}
}
}
},
"react-moment-proptypes": { "react-moment-proptypes": {
"version": "1.6.0", "version": "1.6.0",
"resolved": "https://registry.npmjs.org/react-moment-proptypes/-/react-moment-proptypes-1.6.0.tgz", "resolved": "https://registry.npmjs.org/react-moment-proptypes/-/react-moment-proptypes-1.6.0.tgz",
@ -20215,11 +20014,6 @@
"resolved": "https://registry.npmjs.org/source-map-url/-/source-map-url-0.4.0.tgz", "resolved": "https://registry.npmjs.org/source-map-url/-/source-map-url-0.4.0.tgz",
"integrity": "sha1-PpNdfd1zYxuXZZlW1VEo6HtQhKM=" "integrity": "sha1-PpNdfd1zYxuXZZlW1VEo6HtQhKM="
}, },
"sourcemap-codec": {
"version": "1.4.6",
"resolved": "https://registry.npmjs.org/sourcemap-codec/-/sourcemap-codec-1.4.6.tgz",
"integrity": "sha512-1ZooVLYFxC448piVLBbtOxFcXwnymH9oUF8nRd3CuYDVvkRBxRl6pB4Mtas5a4drtL+E8LDgFkQNcgIw6tc8Hg=="
},
"spawn-command": { "spawn-command": {
"version": "0.0.2-1", "version": "0.0.2-1",
"resolved": "https://registry.npmjs.org/spawn-command/-/spawn-command-0.0.2-1.tgz", "resolved": "https://registry.npmjs.org/spawn-command/-/spawn-command-0.0.2-1.tgz",
@ -21517,11 +21311,6 @@
"util-deprecate": "^1.0.2" "util-deprecate": "^1.0.2"
} }
}, },
"unescape": {
"version": "0.2.0",
"resolved": "https://registry.npmjs.org/unescape/-/unescape-0.2.0.tgz",
"integrity": "sha1-t4ubYMhvFinfGBv1Pu47yNY2fd8="
},
"unherit": { "unherit": {
"version": "1.1.2", "version": "1.1.2",
"resolved": "https://registry.npmjs.org/unherit/-/unherit-1.1.2.tgz", "resolved": "https://registry.npmjs.org/unherit/-/unherit-1.1.2.tgz",

3
plugins/woocommerce-admin/package.json
View File

@ -93,10 +93,8 @@
"debug": "3.2.6", "debug": "3.2.6",
"dompurify": "1.0.11", "dompurify": "1.0.11",
"emoji-flags": "1.2.0", "emoji-flags": "1.2.0",
"gfm-code-blocks": "1.0.0",
"gridicons": "3.3.1", "gridicons": "3.3.1",
"history": "4.9.0", "history": "4.9.0",
"html-to-react": "1.4.1",
"interpolate-components": "1.1.1", "interpolate-components": "1.1.1",
"marked": "0.7.0", "marked": "0.7.0",
"memoize-one": "5.1.1", "memoize-one": "5.1.1",
@ -105,7 +103,6 @@
"qs": "6.8.0", "qs": "6.8.0",
"react-click-outside": "3.0.1", "react-click-outside": "3.0.1",
"react-dates": "17.2.0", "react-dates": "17.2.0",
"react-live": "1.12.0",
"react-router-dom": "5.0.1", "react-router-dom": "5.0.1",
"react-transition-group": "2.9.0", "react-transition-group": "2.9.0",
"redux": "4.0.4" "redux": "4.0.4"

166
plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md
View File

@ -1,17 +1,18 @@
Advanced Filters Advanced Filters
============ ===
Displays a configurable set of filters which can modify query parameters. Display, behavior, and types of filters can be designated by a configuration object. Displays a configurable set of filters which can modify query parameters. Display, behavior, and types of filters can be designated by a configuration object.
## Example Config ## Usage
Below is a config example complete with translation strings. Advanced Filters makes use of [interpolateComponents](https://github.com/Automattic/interpolate-components#readme) to organize sentence structure, resulting in a filter visually represented as a sentence fragment in any language. Below is a config example complete with translation strings. Advanced Filters makes use of [interpolateComponents](https://github.com/Automattic/interpolate-components#readme) to organize sentence structure, resulting in a filter visually represented as a sentence fragment in any language.
```jsx ```js
const config = { const config = {
title: _x( title: __(
// A sentence describing filters for Orders
// See screen shot for context: https://cloudup.com/cSsUY9VeCVJ
'Orders Match {{select /}} Filters', 'Orders Match {{select /}} Filters',
'A sentence describing filters for Orders. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ',
'woocommerce-admin' 'woocommerce-admin'
), ),
filters: { filters: {
@ -20,19 +21,24 @@ const config = {
add: __( 'Order Status', 'woocommerce-admin' ), add: __( 'Order Status', 'woocommerce-admin' ),
remove: __( 'Remove order status filter', 'woocommerce-admin' ), remove: __( 'Remove order status filter', 'woocommerce-admin' ),
rule: __( 'Select an order status filter match', 'woocommerce-admin' ), rule: __( 'Select an order status filter match', 'woocommerce-admin' ),
/* translators: A sentence describing an Order Status filter. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ */ // A sentence describing an Order Status filter
// See screen shot for context: https://cloudup.com/cSsUY9VeCVJ
title: __( 'Order Status {{rule /}} {{filter /}}', 'woocommerce-admin' ), title: __( 'Order Status {{rule /}} {{filter /}}', 'woocommerce-admin' ),
filter: __( 'Select an order status', 'woocommerce-admin' ), filter: __( 'Select an order status', 'woocommerce-admin' ),
}, },
rules: [ rules: [
{ {
value: 'is', value: 'is',
/* translators: Sentence fragment, logical, "Is" refers to searching for orders matching a chosen order status. Screenshot for context: https://cloudup.com/cSsUY9VeCVJ */ // Sentence fragment, logical, "Is"
// Refers to searching for orders matching a chosen order status
// Screenshot for context: https://cloudup.com/cSsUY9VeCVJ
label: _x( 'Is', 'order status', 'woocommerce-admin' ), label: _x( 'Is', 'order status', 'woocommerce-admin' ),
}, },
{ {
value: 'is_not', value: 'is_not',
/* translators: Sentence fragment, logical, "Is Not" refers to searching for orders that don\'t match a chosen order status. Screenshot for context: https://cloudup.com/cSsUY9VeCVJ */ // Sentence fragment, logical, "Is Not"
// Refers to searching for orders that don't match a chosen order status
// Screenshot for context: https://cloudup.com/cSsUY9VeCVJ
label: _x( 'Is Not', 'order status', 'woocommerce-admin' ), label: _x( 'Is Not', 'order status', 'woocommerce-admin' ),
}, },
], ],
@ -45,61 +51,143 @@ const config = {
}, },
}, },
}, },
}; };
``` ```
When filters are applied, the query string will be modified using a combination of rule names and selected filter values.
Taking the above configuration as an example, applying the filter will result in a query parameter like `status_is=pending` or `status_is_not=cancelled`.
### Props
Name | Type | Default | Description
--- | --- | --- | ---
`config` | Object | `null` | (required) The configuration object required to render filters. See example above.
`path` | String | `null` | (required) Name of this filter, used in translations.
`query` | Object | `null` | The query string represented in object form.
`onAdvancedFilterAction` | Function | `null` | Function to be called after an advanced filter action has been taken.
## Input Components ## Input Components
### SelectControl ### SelectControl
Render a select component with options. Render a select component with options.
```jsx ```js
input: { const config = {
component: 'SelectControl', ...,
options: [ filters: {
{ label: 'Apples', key: 'apples' }, fruit: {
{ label: 'Oranges', key: 'oranges' }, input: {
{ label: 'Bananas', key: 'bananas' }, component: 'SelectControl',
{ label: 'Cherries', key: 'cherries' }, options: [
], { label: 'Apples', key: 'apples' },
} { label: 'Oranges', key: 'oranges' },
{ label: 'Bananas', key: 'bananas' },
{ label: 'Cherries', key: 'cherries' },
],
},
},
},
};
``` ```
`options`: An array of objects with `key` and `label` properties. `options`: An array of objects with `key` and `label` properties.
### Search ### Search
Render an input for users to search and select using an autocomplete. Render an input for users to search and select using an autocomplete.
```jsx ```js
input: { const config = {
component: 'Search', ...,
type: 'products', filters: {
getLabels: getRequestByIdString( NAMESPACE + 'products', product => ( { product: {
id: product.id, input: {
label: product.name, component: 'Search',
} ) ), type: 'products',
} getLabels: getRequestByIdString( NAMESPACE + 'products', product => ( {
id: product.id,
label: product.name,
} ) ),
},
},
},
};
``` ```
`type`: A string Autocompleter type used by the [Search Component](https://github.com/woocommerce/woocommerce-admin/tree/master/packages/components/src/search). `type`: A string Autocompleter type used by the [Search Component](https://github.com/woocommerce/woocommerce-admin/tree/master/packages/components/src/search).
`getLabels`: A function returning a Promise resolving to an array of objects with `id` and `label` properties. `getLabels`: A function returning a Promise resolving to an array of objects with `id` and `label` properties.
### Date ### Date
under development.
### Date Range Renders an input or two inputs allowing a user to filter based on a date value or range of values.
under development.
### Numerical Value ```js
under development. const config = {
...,
filters: {
registered: {
rules: [
{
value: 'before',
label: __( 'Before', 'woocommerce-admin' ),
},
{
value: 'after',
label: __( 'After', 'woocommerce-admin' ),
},
{
value: 'between',
label: __( 'Between', 'woocommerce-admin' ),
},
],
input: {
component: 'Date',
},
},
},
};
```
### Numerical Range
under development.
## AdvancedFilters Props ### Numeric Value
* `config` (required): The configuration object required to render filters Renders an input or two inputs allowing a user to filter based on a numeric value or range of values. Can also render inputs for currency values.
* `path` (required): The `path` parameter supplied by React-Router
* `query`: The url query string represented in object form Valid rule values are `after`, `before`, and `between`. Use any combination you'd like.
```js
const config = {
...,
filters: {
quantity: {
rules: [
{
value: 'lessthan',
label: __( 'Less Than', 'woocommerce-admin' ),
},
{
value: 'morethan',
label: __( 'More Than', 'woocommerce-admin' ),
},
{
value: 'between',
label: __( 'Between', 'woocommerce-admin' ),
},
],
input: {
component: 'Number',
},
},
},
};
```
Valid rule values are `lessthan`, `morethan`, and `between`. Use any combination you'd like.
Specify `input.type` as `'currency'` if you'd like to render currency inputs, which respects store currency locale.

20
plugins/woocommerce-admin/packages/components/src/advanced-filters/example.md → plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js
View File

@ -1,9 +1,14 @@
```jsx /** @format */
/**
* Internal dependencies
*/
import { AdvancedFilters } from '@woocommerce/components'; import { AdvancedFilters } from '@woocommerce/components';
const { orderStatuses } = wcSettings; const { orderStatuses } = wcSettings;
const path = (new URL(document.location)).searchParams.get('path') || '/devdocs'; const path = ( new URL( document.location ) ).searchParams.get( 'path' ) || '/devdocs';
const query = {}; const query = {
component: 'advanced-filters',
};
const advancedFilters = { const advancedFilters = {
title: 'Orders Match {{select /}} Filters', title: 'Orders Match {{select /}} Filters',
@ -41,7 +46,7 @@ const advancedFilters = {
remove: 'Remove products filter', remove: 'Remove products filter',
rule: 'Select a product filter match', rule: 'Select a product filter match',
title: '{{title}}Product{{/title}} {{rule /}} {{filter /}}', title: '{{title}}Product{{/title}} {{rule /}} {{filter /}}',
filter:'Select products', filter: 'Select products',
}, },
rules: [ rules: [
{ {
@ -70,8 +75,8 @@ const advancedFilters = {
input: { input: {
component: 'SelectControl', component: 'SelectControl',
options: [ options: [
{ value: 'new', label: 'New', }, { value: 'new', label: 'New' },
{ value: 'returning', label: 'Returning', }, { value: 'returning', label: 'Returning' },
], ],
defaultOption: 'new', defaultOption: 'new',
}, },
@ -130,7 +135,7 @@ const advancedFilters = {
}, },
}; };
const MyAdvancedFilters = () => ( export default () => (
<AdvancedFilters <AdvancedFilters
path={ path } path={ path }
query={ query } query={ query }
@ -138,4 +143,3 @@ const MyAdvancedFilters = () => (
config={ advancedFilters } config={ advancedFilters }
/> />
); );
```

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

15
plugins/woocommerce-admin/packages/components/src/animation-slider/example.md → plugins/woocommerce-admin/packages/components/src/animation-slider/docs/example.js
View File

@ -1,7 +1,15 @@
```jsx /** @format */
/**
* Internal dependencies
*/
import { AnimationSlider } from '@woocommerce/components'; import { AnimationSlider } from '@woocommerce/components';
class MyAnimationSlider extends Component { /**
* External dependencies
*/
import { Component } from '@wordpress/element';
export default class MyAnimationSlider extends Component {
constructor() { constructor() {
super(); super();
this.state = { this.state = {
@ -39,7 +47,7 @@ class MyAnimationSlider extends Component {
return ( return (
<div> <div>
<AnimationSlider animationKey={ page } animate={ animate }> <AnimationSlider animationKey={ page } animate={ animate }>
{ status => ( { () => (
<div style={ style }> <div style={ style }>
{ pages[ page ] } { pages[ page ] }
</div> </div>
@ -55,4 +63,3 @@ class MyAnimationSlider extends Component {
); );
} }
} }
```

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

45
plugins/woocommerce-admin/packages/components/src/autocomplete/example.md → plugins/woocommerce-admin/packages/components/src/autocomplete/docs/example.js
View File

@ -1,6 +1,13 @@
```jsx /**
* Internal dependencies
*/
import { Autocomplete } from '@woocommerce/components'; import { Autocomplete } from '@woocommerce/components';
/**
* External dependencies
*/
import { withState } from '@wordpress/compose';
const options = [ const options = [
{ {
key: 'apple', key: 'apple',
@ -15,73 +22,69 @@ const options = [
{ {
key: 'banana', key: 'banana',
label: 'Banana', label: 'Banana',
keywords: ['best', 'fruit'], keywords: [ 'best', 'fruit' ],
value: { id: 'banana' } value: { id: 'banana' },
}, },
{ {
key: 'blueberry', key: 'blueberry',
label: 'Blueberry', label: 'Blueberry',
value: { id: 'blueberry' } value: { id: 'blueberry' },
}, },
{ {
key: 'cherry', key: 'cherry',
label: 'Cherry', label: 'Cherry',
value: { id: 'cherry' } value: { id: 'cherry' },
}, },
{ {
key: 'cantaloupe', key: 'cantaloupe',
label: 'Cantaloupe', label: 'Cantaloupe',
value: { id: 'cantaloupe' } value: { id: 'cantaloupe' },
}, },
{ {
key: 'dragonfruit', key: 'dragonfruit',
label: 'Dragon Fruit', label: 'Dragon Fruit',
value: { id: 'dragonfruit' } value: { id: 'dragonfruit' },
}, },
{ {
key: 'elderberry', key: 'elderberry',
label: 'Elderberry', label: 'Elderberry',
value: { id: 'elderberry' } value: { id: 'elderberry' },
}, },
]; ];
const onChange = (selected) => {
console.log( selected );
}
const MyAutocomplete = withState( { export default withState( {
singleSelected: [], singleSelected: [],
multipleSelected: [], multipleSelected: [],
inlineSelected: [], inlineSelected: [],
} )( ( { singleSelected, multipleSelected, inlineSelected, setState } ) => ( } )( ( { singleSelected, multipleSelected, inlineSelected, setState } ) => (
<div> <div>
<Autocomplete <Autocomplete
label='Single value' label="Single value"
onChange={ ( selected ) => setState( { singleSelected: selected } ) } onChange={ ( selected ) => setState( { singleSelected: selected } ) }
options={ options } options={ options }
placeholder='Start typing to filter options...' placeholder="Start typing to filter options..."
selected={ singleSelected } selected={ singleSelected }
/> />
<br/> <br />
<Autocomplete <Autocomplete
label='Inline tags' label="Inline tags"
multiple multiple
inlineTags inlineTags
onChange={ ( selected ) => setState( { inlineSelected: selected } ) } onChange={ ( selected ) => setState( { inlineSelected: selected } ) }
options={ options } options={ options }
placeholder='Start typing to filter options...' placeholder="Start typing to filter options..."
selected={ inlineSelected } selected={ inlineSelected }
/> />
<br/> <br />
<Autocomplete <Autocomplete
hideBeforeSearch hideBeforeSearch
label='Hidden options before search' label="Hidden options before search"
multiple multiple
onChange={ ( selected ) => setState( { multipleSelected: selected } ) } onChange={ ( selected ) => setState( { multipleSelected: selected } ) }
options={ options } options={ options }
placeholder='Start typing to filter options...' placeholder="Start typing to filter options..."
selected={ multipleSelected } selected={ multipleSelected }
showClearButton showClearButton
/> />
</div> </div>
) ); ) );
```

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

25
plugins/woocommerce-admin/packages/components/src/calendar/example.md → plugins/woocommerce-admin/packages/components/src/calendar/docs/example.js
View File

@ -1,10 +1,23 @@
```jsx /** @format */
import { DateRange, DatePicker } from '@woocommerce/components'; /**
* Internal dependencies
*/
import {
DateRange,
DatePicker,
H,
Section,
} from '@woocommerce/components';
/**
* External dependencies
*/
import moment from 'moment'; import moment from 'moment';
import { withState } from '@wordpress/compose';
const dateFormat = 'MM/DD/YYYY'; const dateFormat = 'MM/DD/YYYY';
const MyDateRange = withState( { export default withState( {
after: null, after: null,
afterText: '', afterText: '',
before: null, before: null,
@ -12,7 +25,7 @@ const MyDateRange = withState( {
afterError: null, afterError: null,
beforeError: null, beforeError: null,
focusedInput: 'startDate', focusedInput: 'startDate',
} )( ( { after, afterText, before, beforeText, afterError, beforeError, focusedInput, setState } ) => { } )( ( { after, afterText, before, beforeText, afterError, focusedInput, setState } ) => {
function onRangeUpdate( update ) { function onRangeUpdate( update ) {
setState( update ); setState( update );
} }
@ -40,7 +53,6 @@ const MyDateRange = withState( {
isInvalidDate={ date => moment().isBefore( moment( date ), 'date' ) } isInvalidDate={ date => moment().isBefore( moment( date ), 'date' ) }
/> />
</Section> </Section>
<H>Date Picker</H> <H>Date Picker</H>
<Section component={ false }> <Section component={ false }>
<DatePicker <DatePicker
@ -53,6 +65,5 @@ const MyDateRange = withState( {
/> />
</Section> </Section>
</div> </div>
) );
} ); } );
```

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

16
plugins/woocommerce-admin/packages/components/src/card/docs/example.js Normal file
View File

@ -0,0 +1,16 @@
/** @format */
/**
* Internal dependencies
*/
import { Card } from '@woocommerce/components';
export default () => (
<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>
);

14
plugins/woocommerce-admin/packages/components/src/card/example.md
View File

@ -1,14 +0,0 @@
```jsx
import { Card } from '@woocommerce/components';
const MyCard = () => (
<div>
<Card title={ "Store Performance" } description={ "Key performance metrics" }>
<p>Your stuff in a Card.</p>
</Card>
<Card title={ "Inactive Card" } isInactive={ true }>
<p>This Card is grayed out and has no box-shadow.</p>
</Card>
</div>
);
```

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

74
plugins/woocommerce-admin/packages/components/src/chart/docs/example.js Normal file
View File

@ -0,0 +1,74 @@
/** @format */
/**
* Internal dependencies
*/
import { Chart } from '@woocommerce/components';
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,
},
},
];
export default () => (
<div>
<Chart data={ data } title="Example Chart" layout="item-comparison" />
</div>
);

36
plugins/woocommerce-admin/packages/components/src/chart/example.md
View File

@ -1,36 +0,0 @@
```jsx
import { Chart } from '@woocommerce/components';
const data = [
{
date: '2018-05-30T00:00:00',
Hoodie: { value: 21599 },
Sunglasses: { value: 38537 },
Cap: { value: 106010 },
},
{
date: '2018-05-31T00:00:00',
Hoodie: { value: 14205 },
Sunglasses: { value: 24721 },
Cap: { value: 70131 },
},
{
date: '2018-06-01T00:00:00',
Hoodie: { value: 10581 },
Sunglasses: { value: 19991 },
Cap: { value: 53552 },
},
{
date: '2018-06-02T00:00:00',
Hoodie: { value: 9250 },
Sunglasses: { value: 16072 },
Cap: { value: 47821 },
},
];
const MyChart = () => (
<div>
<Chart data={ data } title="Example Chart" layout="item-comparison" />
</div>
);
```

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

10
plugins/woocommerce-admin/packages/components/src/compare-filter/example.md → plugins/woocommerce-admin/packages/components/src/compare-filter/docs/example.js
View File

@ -1,7 +1,10 @@
```jsx /** @format */
/**
* Internal dependencies
*/
import { CompareFilter } from '@woocommerce/components'; import { CompareFilter } from '@woocommerce/components';
const path = (new URL(document.location)).searchParams.get('path') || '/devdocs'; const path = ( new URL( document.location ) ).searchParams.get( 'path' ) || '/devdocs';
const query = {}; const query = {};
const compareFilter = { const compareFilter = {
type: 'products', type: 'products',
@ -17,7 +20,6 @@ const compareFilter = {
}, },
}; };
const MyCompareFilter = () => ( export default () => (
<CompareFilter path={ path } query={ query } { ...compareFilter } /> <CompareFilter path={ path } query={ query } { ...compareFilter } />
); );
```

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

8
plugins/woocommerce-admin/packages/components/src/count/example.md → plugins/woocommerce-admin/packages/components/src/count/docs/example.js
View File

@ -1,7 +1,9 @@
```jsx /** @format */
/**
* Internal dependencies
*/
import { Count } from '@woocommerce/components'; import { Count } from '@woocommerce/components';
const MyCount = () => ( export default () => (
<Count count={ 33 } /> <Count count={ 33 } />
); );
```

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

@ -1,4 +1,4 @@
Date Picker Date Range Picker
=== ===
Select a range of dates or single dates Select a range of dates or single dates
@ -6,7 +6,11 @@ Select a range of dates or single dates
## Usage ## Usage
```jsx ```jsx
<DatePicker key={ JSON.stringify( query ) } path={ path } query={ query } />
<DateRangeFilterPicker
key="daterange"
onRangeSelect={ () => {} }
/>
``` ```
### Props ### Props
@ -15,17 +19,16 @@ Required props are marked with `*`.
Name | Type | Default | Description 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 `query` | Object | `{}` | The query string represented in object form
`path`* | `string` | none | The `path` parameter supplied by React-Router `onRangeSelect` | Function | `null` | Callback called when selection is made
`query` | `object` | `{}` | The query string represented in object form
## URL as the source of truth ## 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. The Date Range 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 URL Parameter | Default | Possible Values
--- | --- | --- --- | --- | ---
`period` | `today` | `today`, `yesterday`, `week`, `last_week`, `month`, `last_month`, `quarter`, `last_quarter`, `year`, `last_year`, `custom` `period` | `today` | `today`, `yesterday`, `week`, `last_week`, `month`, `last_month`, `quarter`, `last_quarter`, `year`, `last_year`, `custom`
`compare` | `previous_period` | `previous_period`, `previous_year` `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) `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) `end` | none | end date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)

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

@ -0,0 +1,15 @@
/** @format */
/**
* Internal dependencies
*/
import { DateRangeFilterPicker } from '@woocommerce/components';
const query = {};
export default () => (
<DateRangeFilterPicker
key="daterange"
query={ query }
onRangeSelect={ () => {} }
/>
);

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

@ -1,13 +0,0 @@
```jsx
import DateRangeFilterPicker from '@woocommerce/components';
const query = {};
const MyDateRangeFilterPicker = () => (
<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

9
plugins/woocommerce-admin/packages/components/src/date/docs/example.js Normal file
View File

@ -0,0 +1,9 @@
/** @format */
/**
* Internal dependencies
*/
import { Date } from '@woocommerce/components';
export default () => (
<Date date="2019-01-01" />
);

7
plugins/woocommerce-admin/packages/components/src/date/example.md
View File

@ -1,7 +0,0 @@
```jsx
import { Date } from '@woocommerce/components';
const MyDate = () => (
<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

14
plugins/woocommerce-admin/packages/components/src/dropdown-button/example.md → plugins/woocommerce-admin/packages/components/src/dropdown-button/docs/example.js
View File

@ -1,8 +1,15 @@
```jsx /** @format */
import { Dropdown } from '@wordpress/components'; /**
* Internal dependencies
*/
import { DropdownButton } from '@woocommerce/components'; import { DropdownButton } from '@woocommerce/components';
const MyDropdownButton = () => ( /**
* External dependencies
*/
import { Dropdown } from '@wordpress/components';
export default () => (
<Dropdown <Dropdown
renderToggle={ ( { isOpen, onToggle } ) => ( renderToggle={ ( { isOpen, onToggle } ) => (
<DropdownButton <DropdownButton
@ -16,4 +23,3 @@ const MyDropdownButton = () => (
) } ) }
/> />
); );
```

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

52
plugins/woocommerce-admin/packages/components/src/ellipsis-menu/docs/example.js Normal file
View File

@ -0,0 +1,52 @@
/** @format */
/**
* Internal dependencies
*/
import {
EllipsisMenu,
MenuItem,
MenuTitle,
} from '@woocommerce/components';
/**
* External dependencies
*/
import { withState } from '@wordpress/compose';
import { Fragment } from '@wordpress/element';
import { Icon } from '@wordpress/components';
export default withState( {
showCustomers: true,
showOrders: true,
} )( ( { setState, showCustomers, showOrders } ) => (
<EllipsisMenu label="Choose which analytics to display"
renderContent={ ( { onToggle } ) => (
<Fragment>
<MenuTitle>Display Stats</MenuTitle>
<MenuItem
isCheckbox
isClickable
checked={ showCustomers }
onInvoke={ () => setState( { showCustomers: ! showCustomers } ) }
>
Show Customers
</MenuItem>
<MenuItem
isCheckbox
isClickable
checked={ showOrders }
onInvoke={ () => setState( { showOrders: ! showOrders } ) }
>
Show Orders
</MenuItem>
<MenuItem
isClickable
onInvoke={ onToggle }
>
<Icon icon="no-alt" />
Close Menu
</MenuItem>
</Fragment>
) }
/>
) );

40
plugins/woocommerce-admin/packages/components/src/ellipsis-menu/example.md
View File

@ -1,40 +0,0 @@
```jsx
import { EllipsisMenu, MenuItem, MenuTitle, Button } from '@woocommerce/components';
const MyEllipsisMenu = withState( {
showCustomers: true,
showOrders: true,
} )( ( { setState, showCustomers, showOrders } ) => (
<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>
);
} }
/>
) );
```

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

8
plugins/woocommerce-admin/packages/components/src/empty-content/example.md → plugins/woocommerce-admin/packages/components/src/empty-content/docs/example.js
View File

@ -1,7 +1,10 @@
```jsx /** @format */
/**
* Internal dependencies
*/
import { EmptyContent } from '@woocommerce/components'; import { EmptyContent } from '@woocommerce/components';
const MyEmptyContent = () => ( export default () => (
<EmptyContent <EmptyContent
title="Nothing here" title="Nothing here"
message="Some descriptive text" message="Some descriptive text"
@ -9,4 +12,3 @@ const MyEmptyContent = () => (
actionURL="#" actionURL="#"
/> />
); );
```

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

@ -1,5 +1,5 @@
Filter Picker Filter Picker
============= ===
Modify a url query parameter via a dropdown selection of configurable options. This component manipulates the `filter` query parameter. 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 ### Props
* `filters` (required): An array of filters and subFilters to construct the menu Name | Type | Default | Description
* `path` (required): The `path` parameter supplied by React-Router --- | --- | --- | ---
* `query`: The query string represented in object form `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 ### `filters` structure
The `filters` prop is an array of filter objects. Each filter object should have the following format: 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. - `chartMode`: One of: 'item-comparison', 'time-comparison'
* `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. - `component`: String - A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented.
* `value` (required): The value for this filter, used to set the `filter` query param when clicked, if there are no `subFilters`. - `label`: String - The label for this filter. Optional only for custom component filters.
* `path`: An array representing the "path" to this filter, if nested. See the Lunch > Pescatarian > Snapper example above. - `path`: String - An array representing the "path" to this filter, if nested.
* `component`: A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented. - `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`.

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

@ -0,0 +1,48 @@
/** @format */
/**
* Internal dependencies
*/
import { FilterPicker } from '@woocommerce/components';
const path = ( new URL( document.location ) ).searchParams.get( 'path' ) || '/devdocs';
const query = {
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' },
],
};
export default () => (
<FilterPicker config={ config } path={ path } query={ query } />
);

46
plugins/woocommerce-admin/packages/components/src/filter-picker/example.md
View File

@ -1,46 +0,0 @@
```jsx
import { FilterPicker } from '@woocommerce/components';
const path = (new URL(document.location)).searchParams.get('path') || '/devdocs';
const query = {
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' },
],
};
const MyFilterPicker = () => (
<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

22
plugins/woocommerce-admin/packages/components/src/filters/example.md → plugins/woocommerce-admin/packages/components/src/filters/docs/example.js
View File

@ -1,5 +1,14 @@
```jsx /** @format */
import { ReportFilters } from '@woocommerce/components'; /**
* Internal dependencies
*/
import {
AdvancedFilters,
CompareFilter,
H,
ReportFilters,
Section,
} from '@woocommerce/components';
const { orderStatuses } = wcSettings; const { orderStatuses } = wcSettings;
const path = ''; const path = '';
@ -53,7 +62,7 @@ const advancedFilters = {
remove: 'Remove products filter', remove: 'Remove products filter',
rule: 'Select a product filter match', rule: 'Select a product filter match',
title: 'Product {{rule /}} {{filter /}}', title: 'Product {{rule /}} {{filter /}}',
filter:'Select products', filter: 'Select products',
}, },
rules: [ rules: [
{ {
@ -82,8 +91,8 @@ const advancedFilters = {
input: { input: {
component: 'SelectControl', component: 'SelectControl',
options: [ options: [
{ value: 'new', label: 'New', }, { value: 'new', label: 'New' },
{ value: 'returning', label: 'Returning', }, { value: 'returning', label: 'Returning' },
], ],
defaultOption: 'new', defaultOption: 'new',
}, },
@ -156,7 +165,7 @@ const compareFilter = {
}, },
}; };
const MyReportFilters = () => ( export default () => (
<div> <div>
<H>Date picker only</H> <H>Date picker only</H>
<Section component={ false }> <Section component={ false }>
@ -188,4 +197,3 @@ const MyReportFilters = () => (
</Section> </Section>
</div> </div>
); );
```

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

14
plugins/woocommerce-admin/packages/components/src/flag/example.md → plugins/woocommerce-admin/packages/components/src/flag/docs/example.js
View File

@ -1,22 +1,22 @@
```jsx /** @format */
import { Flag } from '@woocommerce/components'; /**
* Internal dependencies
*/
import { Flag, H, Section } from '@woocommerce/components';
const MyFlag = () => ( export default () => (
<div> <div>
<H>Default (inherits parent font size)</H> <H>Default (inherits parent font size)</H>
<Section component={ false }> <Section component={ false }>
<Flag code="VU" /> <Flag code="VU" />
</Section> </Section>
<H>Large</H> <H>Large</H>
<Section component={ false }> <Section component={ false }>
<Flag code="VU" size={ 48 } /> <Flag code="VU" size={ 48 } />
</Section> </Section>
<H>Invalid Country Code</H> <H>Invalid Country Code</H>
<Section component={ false }> <Section component={ false }>
<Flag code="invalid country code" /> <Flag code="invalid country code" />
</Section> </Section>
</div> </div>
); );
```

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` | | `{}` |

28
plugins/woocommerce-admin/packages/components/src/form/example.md → plugins/woocommerce-admin/packages/components/src/form/docs/example.js
View File

@ -1,7 +1,20 @@
```jsx /** @format */
import { Button, CheckboxControl, RadioControl, SelectControl, TextControl } from '@wordpress/components'; /**
* Internal dependencies
*/
import { Form } from '@woocommerce/components'; import { Form } from '@woocommerce/components';
/**
* External dependencies
*/
import {
Button,
CheckboxControl,
RadioControl,
SelectControl,
TextControl,
} from '@wordpress/components';
const validate = ( values ) => { const validate = ( values ) => {
const errors = {}; const errors = {};
if ( ! values.firstName ) { if ( ! values.firstName ) {
@ -16,13 +29,12 @@ const validate = ( values ) => {
const onSubmitCallback = ( values ) => console.log( values ); const onSubmitCallback = ( values ) => console.log( values );
const initialValues = { firstName: '', lastName: '', select: '3', checkbox: true, radio: '2' }; const initialValues = { firstName: '', lastName: '', select: '3', checkbox: true, radio: '2' };
const MyForm = () => ( export default () => (
<Form validate={ validate } onSubmitCallback={ onSubmitCallback } initialValues={ initialValues }> <Form validate={ validate } onSubmitCallback={ onSubmitCallback } initialValues={ initialValues }>
{ ( { { ( {
getInputProps, getInputProps,
values, values,
errors, errors,
setValue,
handleSubmit, handleSubmit,
} ) => ( } ) => (
<div> <div>
@ -35,7 +47,7 @@ const MyForm = () => (
{ ...getInputProps( 'lastName' ) } { ...getInputProps( 'lastName' ) }
/> />
<SelectControl <SelectControl
label='Select' label="Select"
options={ [ options={ [
{ label: 'Option 1', value: '1' }, { label: 'Option 1', value: '1' },
{ label: 'Option 2', value: '2' }, { label: 'Option 2', value: '2' },
@ -44,11 +56,11 @@ const MyForm = () => (
{ ...getInputProps( 'select' ) } { ...getInputProps( 'select' ) }
/> />
<CheckboxControl <CheckboxControl
label='Checkbox' label="Checkbox"
{ ...getInputProps( 'checkbox' ) } { ...getInputProps( 'checkbox' ) }
/> />
<RadioControl <RadioControl
label='Radio' label="Radio"
options={ [ options={ [
{ label: 'Option 1', value: '1' }, { label: 'Option 1', value: '1' },
{ label: 'Option 2', value: '2' }, { label: 'Option 2', value: '2' },
@ -71,5 +83,3 @@ const MyForm = () => (
) } ) }
</Form> </Form>
); );
```

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

Some files were not shown because too many files have changed in this diff Show More