diff --git a/plugins/woocommerce-admin/bin/generate-docs/index.js b/plugins/woocommerce-admin/bin/generate-docs/index.js index 1dad2018b15..f2ea1e1da9e 100755 --- a/plugins/woocommerce-admin/bin/generate-docs/index.js +++ b/plugins/woocommerce-admin/bin/generate-docs/index.js @@ -15,7 +15,6 @@ const { ANALYTICS_FOLDER, PACKAGES_FOLDER, DOCS_FOLDER, - deleteExistingDocs, getExportedFileList, getMdFileName, getRealFilePaths, @@ -38,13 +37,10 @@ const fileCollections = [ const tocSections = []; 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. const files = getRealFilePaths( getExportedFileList( path.resolve( fileCollection.folder, 'index.js' ) ), fileCollection.folder ); - // Build documentation + // Build documentation for components missing them buildComponentDocs( files, fileCollection.route ); // 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. */ 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; try { @@ -118,6 +125,7 @@ function buildDocs( fileName, route, content, multiple = false ) { function generateMarkdown( docObject ) { let markdownString = getTitle( docObject.displayName ) + '\n'; markdownString += getDescription( docObject.description ) + '\n'; + markdownString += '## Usage\n\n```jsx\n```\n\n'; markdownString += getProps( docObject.props ); return markdownString + '\n'; } diff --git a/plugins/woocommerce-admin/bin/generate-docs/lib/file-system.js b/plugins/woocommerce-admin/bin/generate-docs/lib/file-system.js index 20fcad5e392..bc2b944e1e2 100644 --- a/plugins/woocommerce-admin/bin/generate-docs/lib/file-system.js +++ b/plugins/woocommerce-admin/bin/generate-docs/lib/file-system.js @@ -18,27 +18,6 @@ const ANALYTICS_FOLDER = path.resolve( __dirname, '../../../client/analytics/com const PACKAGES_FOLDER = path.resolve( __dirname, '../../../packages/components/src/' ); 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 * @@ -83,7 +62,13 @@ function getMdFileName( filepath, route, absolute = true ) { if ( ! fileParts || ! fileParts[ 1 ] ) { 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 ) { 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. * @@ -159,7 +130,7 @@ function getTocSection( files, route, title ) { const mdFiles = files.map( f => getMdFileName( f, route, false ) ).sort(); 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 })`; } ); @@ -173,7 +144,6 @@ module.exports = { DOCS_FOLDER, ANALYTICS_FOLDER, PACKAGES_FOLDER, - deleteExistingDocs, getExportedFileList, getMdFileName, getRealFilePaths, diff --git a/plugins/woocommerce-admin/bin/generate-docs/lib/formatting.js b/plugins/woocommerce-admin/bin/generate-docs/lib/formatting.js index 6445f55209c..c1b985d47f8 100644 --- a/plugins/woocommerce-admin/bin/generate-docs/lib/formatting.js +++ b/plugins/woocommerce-admin/bin/generate-docs/lib/formatting.js @@ -42,15 +42,20 @@ function getDescription( description = '' ) { * @return { string } Formatted string. */ function getProp( propName, prop ) { - const lines = [ '### `' + propName + '`\n' ]; - 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( '' ); + const cols = [ '`' + propName + '`' ]; - 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 ) { return '`' + value.value + '`'; } - return 'null'; + return '`null`'; } /** @@ -76,8 +81,13 @@ function getProps( props = {} ) { if ( Object.keys( props ).length < 1 ) { return ''; } - const title = 'Props'; - const lines = [ title, stringOfLength( '-', title.length ), '' ]; + const title = '### Props'; + const lines = [ + title, + '', + 'Name | Type | Default | Description', + '--- | --- | --- | ---', + ]; Object.keys( props ).map( key => { lines.push( getProp( key, props[ key ] ) ); } ); @@ -145,8 +155,7 @@ function getPropType( type ) { * @return { string } Formatted string. */ function getTitle( name ) { - const title = '`' + name + '` (component)'; - return title + '\n' + stringOfLength( '=', title.length ) + '\n'; + return name + '\n===\n'; } /** diff --git a/plugins/woocommerce-admin/client/devdocs/docs.js b/plugins/woocommerce-admin/client/devdocs/docs.js index 2c0070bcb98..e43768e6cbc 100644 --- a/plugins/woocommerce-admin/client/devdocs/docs.js +++ b/plugins/woocommerce-admin/client/devdocs/docs.js @@ -4,9 +4,19 @@ */ import { Component } from '@wordpress/element'; import marked from 'marked'; -import { Parser } from 'html-to-react'; +import Prism from 'prismjs'; +import 'prismjs/components/prism-jsx'; -const htmlToReactParser = new Parser(); +// Alias `javascript` language to `es6` +Prism.languages.es6 = Prism.languages.javascript; + +// Configure marked to use Prism for code-block highlighting. +marked.setOptions( { + highlight: function( code, language ) { + const syntax = Prism.languages[ language ]; + return syntax ? Prism.highlight( code, syntax ) : code; + }, +} ); class Docs extends Component { state = { @@ -18,15 +28,14 @@ class Docs extends Component { } getReadme() { - const { filePath, docPath } = this.props; - const readme = require( `../../docs/components/${ docPath }/${ filePath }.md` ); + const { filePath } = this.props; + const readme = require( `../../packages/components/src/${ filePath }/README.md` ); + if ( ! readme ) { return; } - const html = marked( readme ); - this.setState( { - readme: htmlToReactParser.parse( html ), - } ); + + this.setState( { readme } ); } render() { @@ -34,12 +43,14 @@ class Docs extends Component { if ( ! readme ) { return null; } - return
{ readme }
; + return ( +
+ ); } } -Docs.defaultProps = { - docPath: 'packages', -}; - export default Docs; diff --git a/plugins/woocommerce-admin/client/devdocs/example.js b/plugins/woocommerce-admin/client/devdocs/example.js index d99d4cf2b77..345794c3731 100755 --- a/plugins/woocommerce-admin/client/devdocs/example.js +++ b/plugins/woocommerce-admin/client/devdocs/example.js @@ -2,78 +2,40 @@ /** * External dependencies */ -import codeBlocks from 'gfm-code-blocks'; import { Component } from '@wordpress/element'; -import { LiveError, LivePreview, LiveProvider } from 'react-live'; -// 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'; +import React from 'react'; class Example extends Component { state = { - code: null, + example: null, }; componentDidMount() { - this.getCode(); + this.getExample(); } - async getCode() { - let readme; + async getExample() { + let exampleComponent; + try { - readme = require( `components/src/${ this.props.filePath }/example.md` ); + exampleComponent = require( `components/src/${ this.props.filePath }/docs/example` ); } catch ( e ) { - readme = require( `components/${ this.props.filePath }/example.md` ); + console.error( e ); } - if ( ! readme ) { + + if ( ! exampleComponent ) { return; } - // Example to render is the first jsx code block that appears in the readme - let code = codeBlocks( readme ).find( block => 'jsx' === block.lang ).code; - - // 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 } ); + this.setState( { + example: React.createElement( exampleComponent.default || exampleComponent ), + } ); } render() { - const { code } = this.state; - const scope = { - ...wpComponents, - ...components, - ...pkgComponents, - Component, - withState, - PropTypes, - addFilter, - Gridicon, - }; + const { example } = this.state; - return code ? ( - - - - - ) : null; + return
{ example }
; } } diff --git a/plugins/woocommerce-admin/client/devdocs/examples.json b/plugins/woocommerce-admin/client/devdocs/examples.json index 9e91a568204..0ffd6e4c637 100644 --- a/plugins/woocommerce-admin/client/devdocs/examples.json +++ b/plugins/woocommerce-admin/client/devdocs/examples.json @@ -2,7 +2,7 @@ { "component": "AdvancedFilters" }, { "component": "AnimationSlider" }, { "component": "Autocomplete" }, - { "component": "Calendar", "render": "MyDateRange" }, + { "component": "Calendar" }, { "component": "Card" }, { "component": "Chart" }, { "component": "CompareFilter" }, @@ -31,7 +31,7 @@ { "component": "Spinner" }, { "component": "SplitButton" }, { "component": "Stepper" }, - { "component": "Summary", "render": "MySummaryList" }, + { "component": "Summary" }, { "component": "Table" }, { "component": "Tag" }, { "component": "TextControlWithAffixes" }, diff --git a/plugins/woocommerce-admin/client/devdocs/index.js b/plugins/woocommerce-admin/client/devdocs/index.js index ce9648e3841..2ae99e2fee8 100755 --- a/plugins/woocommerce-admin/client/devdocs/index.js +++ b/plugins/woocommerce-admin/client/devdocs/index.js @@ -3,7 +3,7 @@ * External dependencies */ import classnames from 'classnames'; -import { Component } from '@wordpress/element'; +import { Component, Fragment } from '@wordpress/element'; import { find, get } from 'lodash'; /** @@ -22,18 +22,16 @@ const camelCaseToSlug = name => { const getExampleData = example => { const componentName = get( example, 'component' ); const filePath = get( example, 'filePath', camelCaseToSlug( componentName ) ); - const render = get( example, 'render', `My${ componentName }` ); return { componentName, filePath, - render, }; }; export default class extends Component { render() { - const { params: { component } } = this.props; + const { query: { component } } = this.props; const className = classnames( 'woocommerce_devdocs', { 'is-single': component, 'is-list': ! component, @@ -48,51 +46,51 @@ export default class extends Component { return (
{ exampleList.map( example => { - const { componentName, filePath, render, docPath } = getExampleData( example ); + const { componentName, filePath } = getExampleData( example ); const cardClasses = classnames( 'woocommerce-devdocs__card', `woocommerce-devdocs__card--${ filePath }`, 'woocommerce-analytics__card' ); return ( - - { componentName } - - ) - } - action={ - component ? ( - - Full list - - ) : null - } - > - - + + + { componentName } + + ) + } + action={ + component ? ( + + Full list + + ) : null + } + > + + { component && ( ) } - + ); } ) }
diff --git a/plugins/woocommerce-admin/client/devdocs/style.scss b/plugins/woocommerce-admin/client/devdocs/style.scss index a61b3e738a8..31f1ca09e5e 100644 --- a/plugins/woocommerce-admin/client/devdocs/style.scss +++ b/plugins/woocommerce-admin/client/devdocs/style.scss @@ -36,10 +36,14 @@ linear-gradient(90deg, rgba($core-grey-dark-800, 0.025) 1px, transparent 1px); background-size: 32px 32px, 32px 32px, 8px 8px, 8px 8px; background-position: -1px -1px, -1px -1px, -1px -1px, -1px -1px; + + .woocommerce-chart { + margin: 0; + } } .woocommerce-devdocs__docs { - max-width: 600px; + max-width: 720px; margin: 0 auto; padding: $gap; @@ -54,5 +58,44 @@ h4 code { font-size: 0.9em; } + + table { + border-collapse: collapse; + border-spacing: 0; + + th, + td { + border-bottom: 1px solid $core-grey-light-700; + text-align: left; + } + + th { + padding: 0.25em 3em 0.25em 0; + } + + td { + padding: 1.17em 3em 1.17em 0; + } + } + + // From wp-calypso: client/devdocs/style.scss + pre { + padding: 8px; + background: $white; + background-color: $white; + } + + code { + background-color: $white; + border-radius: 3px; + font-size: 15px; + padding: 2px 6px; + max-width: 100px; + } + + pre > code { + background-color: $transparent; + padding: 2px 0; + } } } diff --git a/plugins/woocommerce-admin/client/layout/controller.js b/plugins/woocommerce-admin/client/layout/controller.js index f0d8df47b28..2d9fe04c34d 100644 --- a/plugins/woocommerce-admin/client/layout/controller.js +++ b/plugins/woocommerce-admin/client/layout/controller.js @@ -32,13 +32,16 @@ export const getPages = () => { pages.push( { container: DevDocs, path: '/devdocs', - breadcrumbs: [ 'Documentation' ], - wpOpenMenu: 'toplevel_page_woocommerce', - } ); - pages.push( { - container: DevDocs, - path: '/devdocs/:component', - breadcrumbs: ( { match } ) => [ [ '/devdocs', 'Documentation' ], match.params.component ], + breadcrumbs: ( { location } ) => { + const searchParams = new URLSearchParams( location.search ); + const component = searchParams.get( 'component' ); + + if ( component ) { + return [ [ '/devdocs', 'Documentation' ], component ]; + } + + return [ 'Documentation' ]; + }, wpOpenMenu: 'toplevel_page_woocommerce', } ); } diff --git a/plugins/woocommerce-admin/client/stylesheets/abstracts/_colors.scss b/plugins/woocommerce-admin/client/stylesheets/abstracts/_colors.scss index c1b0db9d481..e99479268aa 100644 --- a/plugins/woocommerce-admin/client/stylesheets/abstracts/_colors.scss +++ b/plugins/woocommerce-admin/client/stylesheets/abstracts/_colors.scss @@ -2,6 +2,8 @@ @import 'node_modules/@automattic/color-studio/dist/color-variables.scss'; +$transparent: rgba(255, 255, 255, 0); + // Greys $core-grey-light-100: #f8f9f9; $core-grey-light-200: #f3f4f5; diff --git a/plugins/woocommerce-admin/docs/components/_sidebar.md b/plugins/woocommerce-admin/docs/components/_sidebar.md index d2131c7017a..ec7cd478f73 100644 --- a/plugins/woocommerce-admin/docs/components/_sidebar.md +++ b/plugins/woocommerce-admin/docs/components/_sidebar.md @@ -8,43 +8,43 @@ * [ReportSummary](components/analytics/report-summary.md) * [ReportTable](components/analytics/report-table.md) * [Package components](components/packages/) - * [AdvancedFilters](components/packages/advanced-filters.md) - * [AnimationSlider](components/packages/animation-slider.md) - * [Autocomplete](components/packages/autocomplete.md) - * [Calendar](components/packages/calendar.md) - * [Card](components/packages/card.md) - * [Chart](components/packages/chart.md) - * [CompareFilter](components/packages/compare-filter.md) - * [Count](components/packages/count.md) - * [DateRangeFilterPicker](components/packages/date-range-filter-picker.md) - * [Date](components/packages/date.md) - * [DropdownButton](components/packages/dropdown-button.md) - * [EllipsisMenu](components/packages/ellipsis-menu.md) - * [EmptyContent](components/packages/empty-content.md) - * [FilterPicker](components/packages/filter-picker.md) - * [Filters](components/packages/filters.md) - * [Flag](components/packages/flag.md) - * [Form](components/packages/form.md) - * [Gravatar](components/packages/gravatar.md) - * [ImageAsset](components/packages/image-asset.md) - * [Link](components/packages/link.md) - * [List](components/packages/list.md) - * [OrderStatus](components/packages/order-status.md) - * [Pagination](components/packages/pagination.md) - * [ProductImage](components/packages/product-image.md) - * [Rating](components/packages/rating.md) - * [SearchListControl](components/packages/search-list-control.md) - * [Search](components/packages/search.md) - * [SectionHeader](components/packages/section-header.md) - * [Section](components/packages/section.md) - * [SegmentedSelection](components/packages/segmented-selection.md) - * [SimpleSelectControl](components/packages/simple-select-control.md) - * [Spinner](components/packages/spinner.md) - * [SplitButton](components/packages/split-button.md) - * [Stepper](components/packages/stepper.md) - * [Summary](components/packages/summary.md) - * [Table](components/packages/table.md) - * [Tag](components/packages/tag.md) - * [TextControlWithAffixes](components/packages/text-control-with-affixes.md) - * [ViewMoreList](components/packages/view-more-list.md) - * [WebPreview](components/packages/web-preview.md) \ No newline at end of file + * [AdvancedFilters](components/packages/advanced-filters/README.md) + * [AnimationSlider](components/packages/animation-slider/README.md) + * [Autocomplete](components/packages/autocomplete/README.md) + * [Calendar](components/packages/calendar/README.md) + * [Card](components/packages/card/README.md) + * [Chart](components/packages/chart/README.md) + * [CompareFilter](components/packages/compare-filter/README.md) + * [Count](components/packages/count/README.md) + * [DateRangeFilterPicker](components/packages/date-range-filter-picker/README.md) + * [Date](components/packages/date/README.md) + * [DropdownButton](components/packages/dropdown-button/README.md) + * [EllipsisMenu](components/packages/ellipsis-menu/README.md) + * [EmptyContent](components/packages/empty-content/README.md) + * [FilterPicker](components/packages/filter-picker/README.md) + * [Filters](components/packages/filters/README.md) + * [Flag](components/packages/flag/README.md) + * [Form](components/packages/form/README.md) + * [Gravatar](components/packages/gravatar/README.md) + * [ImageAsset](components/packages/image-asset/README.md) + * [Link](components/packages/link/README.md) + * [List](components/packages/list/README.md) + * [OrderStatus](components/packages/order-status/README.md) + * [Pagination](components/packages/pagination/README.md) + * [ProductImage](components/packages/product-image/README.md) + * [Rating](components/packages/rating/README.md) + * [SearchListControl](components/packages/search-list-control/README.md) + * [Search](components/packages/search/README.md) + * [SectionHeader](components/packages/section-header/README.md) + * [Section](components/packages/section/README.md) + * [SegmentedSelection](components/packages/segmented-selection/README.md) + * [SimpleSelectControl](components/packages/simple-select-control/README.md) + * [Spinner](components/packages/spinner/README.md) + * [SplitButton](components/packages/split-button/README.md) + * [Stepper](components/packages/stepper/README.md) + * [Summary](components/packages/summary/README.md) + * [Table](components/packages/table/README.md) + * [Tag](components/packages/tag/README.md) + * [TextControlWithAffixes](components/packages/text-control-with-affixes/README.md) + * [ViewMoreList](components/packages/view-more-list/README.md) + * [WebPreview](components/packages/web-preview/README.md) \ No newline at end of file diff --git a/plugins/woocommerce-admin/docs/components/analytics/report-chart.md b/plugins/woocommerce-admin/docs/components/analytics/report-chart.md index 5e9c77aff12..902e1973987 100644 --- a/plugins/woocommerce-admin/docs/components/analytics/report-chart.md +++ b/plugins/woocommerce-admin/docs/components/analytics/report-chart.md @@ -1,100 +1,41 @@ -`ReportChart` (component) -========================= +ReportChart +=== Component that renders the chart in reports. -Props ------ +## Usage -### `filters` +```jsx +``` -- Type: Array -- Default: null +### Props -Filters available for that report. - -### `isRequesting` - -- Type: Boolean -- Default: `false` - -Whether there is an API call running. - -### `itemsLabel` - -- Type: String -- Default: null - -Label describing the legend items. - -### `limitProperties` - -- Type: Array -- Default: null - -Allows specifying properties different from the `endpoint` that will be used -to limit the items when there is an active search. - -### `mode` - -- Type: String -- Default: null - -`items-comparison` (default) or `time-comparison`, this is used to generate correct -ARIA properties. - -### `path` - -- **Required** -- Type: String -- Default: null - -Current path - -### `primaryData` - -- Type: Object -- Default: `{ +Name | Type | Default | Description +--- | --- | --- | --- +`filters` | Array | ``null`` | Filters available for that report +`isRequesting` | Boolean | ``false`` | Whether there is an API call running +`itemsLabel` | String | ``null`` | Label describing the legend items +`limitProperties` | Array | ``null`` | Allows specifying properties different from the `endpoint` that will be used to limit the items when there is an active search +`mode` | String | ``null`` | `items-comparison` (default) or `time-comparison`, this is used to generate correct ARIA properties +`path` | String | ``null`` | (required) Current path +`primaryData` | Object | ``{ data: { intervals: [], }, isError: false, isRequesting: false, -}` - -Primary data to display in the chart. - -### `query` - -- **Required** -- Type: Object -- Default: null - -The query string represented in object form. - -### `secondaryData` - -- Type: Object -- Default: `{ +}`` | Primary data to display in the chart +`query` | Object | ``null`` | (required) The query string represented in object form +`secondaryData` | Object | ``{ data: { intervals: [], }, isError: false, isRequesting: false, -}` - -Secondary data to display in the chart. - -### `selectedChart` - -- **Required** -- Type: Object +}`` | Secondary data to display in the chart +`selectedChart` | Object - key: String - Key of the selected chart. - label: String - Chart label. - order: One of: 'asc', 'desc' - orderby: String - Order by query argument. - - type: One of: 'average', 'number', 'currency' -- Default: null - -Properties of the selected chart. - + - type: One of: 'average', 'number', 'currency' | ``null`` | (required) Properties of the selected chart diff --git a/plugins/woocommerce-admin/docs/components/analytics/report-error.md b/plugins/woocommerce-admin/docs/components/analytics/report-error.md index a9ba042d6ba..8ea67f18442 100644 --- a/plugins/woocommerce-admin/docs/components/analytics/report-error.md +++ b/plugins/woocommerce-admin/docs/components/analytics/report-error.md @@ -1,30 +1,18 @@ -`ReportError` (component) -========================= +ReportError +=== Component to render when there is an error in a report component due to data not being loaded or being invalid. -Props ------ +## Usage -### `className` +```jsx +``` -- Type: String -- Default: `''` - -Additional class name to style the component. - -### `isError` - -- Type: Boolean -- Default: null - -Boolean representing whether there was an error. - -### `isEmpty` - -- Type: Boolean -- Default: null - -Boolean representing whether the issue is that there is no data. +### Props +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | ``''`` | Additional class name to style the component +`isError` | Boolean | ``null`` | Boolean representing whether there was an error +`isEmpty` | Boolean | ``null`` | Boolean representing whether the issue is that there is no data diff --git a/plugins/woocommerce-admin/docs/components/analytics/report-summary.md b/plugins/woocommerce-admin/docs/components/analytics/report-summary.md index f326af6248e..b2908c6b282 100644 --- a/plugins/woocommerce-admin/docs/components/analytics/report-summary.md +++ b/plugins/woocommerce-admin/docs/components/analytics/report-summary.md @@ -1,84 +1,34 @@ -`ReportSummary` (component) -=========================== +ReportSummary +=== Component to render summary numbers in reports. -Props ------ +## Usage -### `charts` +```jsx +``` -- **Required** -- Type: Array -- Default: null +### Props -Properties of all the charts available for that report. - -### `endpoint` - -- **Required** -- Type: String -- Default: null - -The endpoint to use in API calls to populate the Summary Numbers. -For example, if `taxes` is provided, data will be fetched from the report -`taxes` endpoint (ie: `/wc/v4/reports/taxes/stats`). If the provided endpoint -doesn't exist, an error will be shown to the user with `ReportError`. - -### `limitProperties` - -- Type: Array -- Default: null - -Allows specifying properties different from the `endpoint` that will be used -to limit the items when there is an active search. - -### `query` - -- **Required** -- Type: Object -- Default: null - -The query string represented in object form. - -### `isRequesting` - -- Type: Boolean -- Default: null - -Whether there is an API call running. - -### `selectedChart` - -- **Required** -- Type: Object +Name | Type | Default | Description +--- | --- | --- | --- +`charts` | Array | ``null`` | (required) Properties of all the charts available for that report +`endpoint` | String | ``null`` | (required) The endpoint to use in API calls to populate the Summary Numbers. For example, if `taxes` is provided, data will be fetched from the report `taxes` endpoint (ie: `/wc/v4/reports/taxes/stats`). If the provided endpoint doesn't exist, an error will be shown to the user with `ReportError` +`limitProperties` | Array | ``null`` | Allows specifying properties different from the `endpoint` that will be used to limit the items when there is an active search +`query` | Object | ``null`` | (required) The query string represented in object form +`isRequesting` | Boolean | ``null`` | Whether there is an API call running +`selectedChart` | Object - key: String - Key of the selected chart. - label: String - Chart label. - order: One of: 'asc', 'desc' - orderby: String - Order by query argument. - - type: One of: 'average', 'number', 'currency' -- Default: null - -Properties of the selected chart. - -### `summaryData` - -- Type: Object -- Default: `{ + - type: One of: 'average', 'number', 'currency' | ``null`` | (required) Properties of the selected chart +`summaryData` | Object | ``{ totals: { primary: {}, secondary: {}, }, isError: false, isRequesting: false, -}` - -Data to display in the SummaryNumbers. - -### `report` - -- Type: String -- Default: null - -Report name, if different than the endpoint. - +}`` | Data to display in the SummaryNumbers +`report` | String | ``null`` | Report name, if different than the endpoint diff --git a/plugins/woocommerce-admin/docs/components/analytics/report-table.md b/plugins/woocommerce-admin/docs/components/analytics/report-table.md index 01da3a6404e..6ced7aee14a 100644 --- a/plugins/woocommerce-admin/docs/components/analytics/report-table.md +++ b/plugins/woocommerce-admin/docs/components/analytics/report-table.md @@ -1,105 +1,34 @@ -`ReportTable` (component) -========================= +ReportTable +=== Component that extends `TableCard` to facilitate its usage in reports. -Props ------ +## Usage -### `columnPrefsKey` +```jsx +``` -- Type: String -- Default: null +### Props -The key for user preferences settings for column visibility. - -### `endpoint` - -- Type: String -- Default: null - -The endpoint to use in API calls to populate the table rows and summary. -For example, if `taxes` is provided, data will be fetched from the report -`taxes` endpoint (ie: `/wc/v4/reports/taxes` and `/wc/v4/reports/taxes/stats`). -If the provided endpoint doesn't exist, an error will be shown to the user -with `ReportError`. - -### `extendItemsMethodNames` - -- Type: Object +Name | Type | Default | Description +--- | --- | --- | --- +`columnPrefsKey` | String | ``null`` | The key for user preferences settings for column visibility +`endpoint` | String | ``null`` | The endpoint to use in API calls to populate the table rows and summary. For example, if `taxes` is provided, data will be fetched from the report `taxes` endpoint (ie: `/wc/v4/reports/taxes` and `/wc/v4/reports/taxes/stats`). If the provided endpoint doesn't exist, an error will be shown to the user with `ReportError` +`extendItemsMethodNames` | Object - getError: String - isRequesting: String - - load: String -- Default: null - -Name of the methods available via `select( 'wc-api' )` that will be used to -load more data for table items. If omitted, no call will be made and only -the data returned by the reports endpoint will be used. - -### `getHeadersContent` - -- **Required** -- Type: Function -- Default: null - -A function that returns the headers object to build the table. - -### `getRowsContent` - -- **Required** -- Type: Function -- Default: null - -A function that returns the rows array to build the table. - -### `getSummary` - -- Type: Function -- Default: null - -A function that returns the summary object to build the table. - -### `itemIdField` - -- Type: String -- Default: null - -The name of the property in the item object which contains the id. - -### `primaryData` - -- Type: Object -- Default: `{}` - -Primary data of that report. If it's not provided, it will be automatically -loaded via the provided `endpoint`. - -### `tableData` - -- Type: Object -- Default: `{ + - load: String | ``null`` | Name of the methods available via `select( 'wc-api' )` that will be used to load more data for table items. If omitted, no call will be made and only the data returned by the reports endpoint will be used +`getHeadersContent` | Function | ``null`` | (required) A function that returns the headers object to build the table +`getRowsContent` | Function | ``null`` | (required) A function that returns the rows array to build the table +`getSummary` | Function | ``null`` | A function that returns the summary object to build the table +`itemIdField` | String | ``null`` | The name of the property in the item object which contains the id +`primaryData` | Object | ``{}`` | Primary data of that report. If it's not provided, it will be automatically loaded via the provided `endpoint` +`tableData` | Object | ``{ items: { data: [], totalResults: 0, }, query: {}, -}` - -Table data of that report. If it's not provided, it will be automatically -loaded via the provided `endpoint`. - -### `tableQuery` - -- Type: Object -- Default: `{}` - -Properties to be added to the query sent to the report table endpoint. - -### `title` - -- **Required** -- Type: String -- Default: null - -String to display as the title of the table. - +}`` | Table data of that report. If it's not provided, it will be automatically loaded via the provided `endpoint` +`tableQuery` | Object | ``{}`` | Properties to be added to the query sent to the report table endpoint +`title` | String | ``null`` | (required) String to display as the title of the table diff --git a/plugins/woocommerce-admin/docs/components/packages b/plugins/woocommerce-admin/docs/components/packages new file mode 120000 index 00000000000..6c38499736b --- /dev/null +++ b/plugins/woocommerce-admin/docs/components/packages @@ -0,0 +1 @@ +../../packages/components/src/ \ No newline at end of file diff --git a/plugins/woocommerce-admin/docs/components/packages/README.md b/plugins/woocommerce-admin/docs/components/packages/README.md deleted file mode 100644 index 036d81e0fa3..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/README.md +++ /dev/null @@ -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 content with an example link. - - ); -} -``` - -## 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 content with an example link. - - ); -} -``` diff --git a/plugins/woocommerce-admin/docs/components/packages/advanced-filters.md b/plugins/woocommerce-admin/docs/components/packages/advanced-filters.md deleted file mode 100644 index 928491b72f3..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/advanced-filters.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/animation-slider.md b/plugins/woocommerce-admin/docs/components/packages/animation-slider.md deleted file mode 100644 index 6b85ea4e136..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/animation-slider.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/autocomplete.md b/plugins/woocommerce-admin/docs/components/packages/autocomplete.md deleted file mode 100644 index 5542502a96a..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/autocomplete.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/calendar.md b/plugins/woocommerce-admin/docs/components/packages/calendar.md deleted file mode 100644 index 968b80ef485..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/calendar.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/card.md b/plugins/woocommerce-admin/docs/components/packages/card.md deleted file mode 100644 index c0f6d486fef..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/card.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/chart.md b/plugins/woocommerce-admin/docs/components/packages/chart.md deleted file mode 100644 index 271589c1586..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/chart.md +++ /dev/null @@ -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` - - diff --git a/plugins/woocommerce-admin/docs/components/packages/compare-filter.md b/plugins/woocommerce-admin/docs/components/packages/compare-filter.md deleted file mode 100644 index 131078d435e..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/compare-filter.md +++ /dev/null @@ -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 - diff --git a/plugins/woocommerce-admin/docs/components/packages/count.md b/plugins/woocommerce-admin/docs/components/packages/count.md deleted file mode 100644 index 49f780dc9f8..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/count.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/date-range-filter-picker.md b/plugins/woocommerce-admin/docs/components/packages/date-range-filter-picker.md deleted file mode 100644 index dc7b503a9cb..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/date-range-filter-picker.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/date.md b/plugins/woocommerce-admin/docs/components/packages/date.md deleted file mode 100644 index 9221bf3ac8d..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/date.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/dropdown-button.md b/plugins/woocommerce-admin/docs/components/packages/dropdown-button.md deleted file mode 100644 index 7a060cc4770..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/dropdown-button.md +++ /dev/null @@ -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 `` 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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/ellipsis-menu.md b/plugins/woocommerce-admin/docs/components/packages/ellipsis-menu.md deleted file mode 100644 index d4593a82fc6..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/ellipsis-menu.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/empty-content.md b/plugins/woocommerce-admin/docs/components/packages/empty-content.md deleted file mode 100644 index e4fc768d53b..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/empty-content.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/filter-picker.md b/plugins/woocommerce-admin/docs/components/packages/filter-picker.md deleted file mode 100644 index 9f75b9222be..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/filter-picker.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/filters.md b/plugins/woocommerce-admin/docs/components/packages/filters.md deleted file mode 100644 index 46a0117c0ed..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/filters.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/flag.md b/plugins/woocommerce-admin/docs/components/packages/flag.md deleted file mode 100644 index a3c64007c30..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/flag.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/form.md b/plugins/woocommerce-admin/docs/components/packages/form.md deleted file mode 100644 index 80e887fa03e..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/form.md +++ /dev/null @@ -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: `{}` - - diff --git a/plugins/woocommerce-admin/docs/components/packages/gravatar.md b/plugins/woocommerce-admin/docs/components/packages/gravatar.md deleted file mode 100644 index 1de04af4aca..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/gravatar.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/image-asset.md b/plugins/woocommerce-admin/docs/components/packages/image-asset.md deleted file mode 100644 index 8d4607feafa..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/image-asset.md +++ /dev/null @@ -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 `` - -Props ------ - -### `src` - -- **Required** -- Type: String -- Default: null - -Image location to pass through to ``. - -### `alt` - -- **Required** -- Type: String -- Default: null - -Alt text to pass through to ``. - diff --git a/plugins/woocommerce-admin/docs/components/packages/link.md b/plugins/woocommerce-admin/docs/components/packages/link.md deleted file mode 100644 index 10ae1479688..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/link.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/list.md b/plugins/woocommerce-admin/docs/components/packages/list.md deleted file mode 100644 index cb6ea370b70..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/list.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/order-status.md b/plugins/woocommerce-admin/docs/components/packages/order-status.md deleted file mode 100644 index e3c7587db46..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/order-status.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/pagination.md b/plugins/woocommerce-admin/docs/components/packages/pagination.md deleted file mode 100644 index d0f81e8af99..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/pagination.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/product-image.md b/plugins/woocommerce-admin/docs/components/packages/product-image.md deleted file mode 100644 index 95110491732..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/product-image.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/rating.md b/plugins/woocommerce-admin/docs/components/packages/rating.md deleted file mode 100644 index e2e06a119ff..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/rating.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/search-list-control.md b/plugins/woocommerce-admin/docs/components/packages/search-list-control.md deleted file mode 100644 index f365cb562c5..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/search-list-control.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/search.md b/plugins/woocommerce-admin/docs/components/packages/search.md deleted file mode 100644 index 92d7adf471c..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/search.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/section-header.md b/plugins/woocommerce-admin/docs/components/packages/section-header.md deleted file mode 100644 index db04c9d5630..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/section-header.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/section.md b/plugins/woocommerce-admin/docs/components/packages/section.md deleted file mode 100644 index eca3de3e2c1..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/section.md +++ /dev/null @@ -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 `` to create "section headings", which look to the parent `
`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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/segmented-selection.md b/plugins/woocommerce-admin/docs/components/packages/segmented-selection.md deleted file mode 100644 index 8e4177630c6..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/segmented-selection.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/simple-select-control.md b/plugins/woocommerce-admin/docs/components/packages/simple-select-control.md deleted file mode 100644 index 6033257ba2f..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/simple-select-control.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/spinner.md b/plugins/woocommerce-admin/docs/components/packages/spinner.md deleted file mode 100644 index 37631cf42e2..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/spinner.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/split-button.md b/plugins/woocommerce-admin/docs/components/packages/split-button.md deleted file mode 100644 index fd92fc5da61..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/split-button.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/stepper.md b/plugins/woocommerce-admin/docs/components/packages/stepper.md deleted file mode 100644 index 25b1245fd0f..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/stepper.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/summary.md b/plugins/woocommerce-admin/docs/components/packages/summary.md deleted file mode 100644 index 1640d857937..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/summary.md +++ /dev/null @@ -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 ``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` - - diff --git a/plugins/woocommerce-admin/docs/components/packages/table.md b/plugins/woocommerce-admin/docs/components/packages/table.md deleted file mode 100644 index 75460a6dd41..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/table.md +++ /dev/null @@ -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, ``, ``, and ``. -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/tag.md b/plugins/woocommerce-admin/docs/components/packages/tag.md deleted file mode 100644 index c60cd369f5d..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/tag.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/text-control-with-affixes.md b/plugins/woocommerce-admin/docs/components/packages/text-control-with-affixes.md deleted file mode 100644 index 06a8688093c..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/text-control-with-affixes.md +++ /dev/null @@ -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. - diff --git a/plugins/woocommerce-admin/docs/components/packages/view-more-list.md b/plugins/woocommerce-admin/docs/components/packages/view-more-list.md deleted file mode 100644 index 19cb4591823..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/view-more-list.md +++ /dev/null @@ -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 - diff --git a/plugins/woocommerce-admin/docs/components/packages/web-preview.md b/plugins/woocommerce-admin/docs/components/packages/web-preview.md deleted file mode 100644 index 2dbe8b09698..00000000000 --- a/plugins/woocommerce-admin/docs/components/packages/web-preview.md +++ /dev/null @@ -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: `` - -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. - diff --git a/plugins/woocommerce-admin/package-lock.json b/plugins/woocommerce-admin/package-lock.json index c61eb6b352d..858a47c031d 100644 --- a/plugins/woocommerce-admin/package-lock.json +++ b/plugins/woocommerce-admin/package-lock.json @@ -5224,33 +5224,6 @@ "integrity": "sha1-M3dm2hWAEhD92VbCLpxokaudAzc=", "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": { "version": "4.9.1", "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", "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": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", @@ -6752,15 +6715,6 @@ "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": { "version": "5.2.1", "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-5.2.1.tgz", @@ -7846,15 +7800,6 @@ "@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": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/dom-scroll-into-view/-/dom-scroll-into-view-1.2.1.tgz", @@ -9302,8 +9247,7 @@ }, "ansi-regex": { "version": "2.1.1", - "bundled": true, - "optional": true + "bundled": true }, "aproba": { "version": "1.2.0", @@ -9321,13 +9265,11 @@ }, "balanced-match": { "version": "1.0.0", - "bundled": true, - "optional": true + "bundled": true }, "brace-expansion": { "version": "1.1.11", "bundled": true, - "optional": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -9340,18 +9282,15 @@ }, "code-point-at": { "version": "1.1.0", - "bundled": true, - "optional": true + "bundled": true }, "concat-map": { "version": "0.0.1", - "bundled": true, - "optional": true + "bundled": true }, "console-control-strings": { "version": "1.1.0", - "bundled": true, - "optional": true + "bundled": true }, "core-util-is": { "version": "1.0.2", @@ -9454,8 +9393,7 @@ }, "inherits": { "version": "2.0.3", - "bundled": true, - "optional": true + "bundled": true }, "ini": { "version": "1.3.5", @@ -9465,7 +9403,6 @@ "is-fullwidth-code-point": { "version": "1.0.0", "bundled": true, - "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -9478,20 +9415,17 @@ "minimatch": { "version": "3.0.4", "bundled": true, - "optional": true, "requires": { "brace-expansion": "^1.1.7" } }, "minimist": { "version": "0.0.8", - "bundled": true, - "optional": true + "bundled": true }, "minipass": { "version": "2.3.5", "bundled": true, - "optional": true, "requires": { "safe-buffer": "^5.1.2", "yallist": "^3.0.0" @@ -9508,7 +9442,6 @@ "mkdirp": { "version": "0.5.1", "bundled": true, - "optional": true, "requires": { "minimist": "0.0.8" } @@ -9581,8 +9514,7 @@ }, "number-is-nan": { "version": "1.0.1", - "bundled": true, - "optional": true + "bundled": true }, "object-assign": { "version": "4.1.1", @@ -9592,7 +9524,6 @@ "once": { "version": "1.4.0", "bundled": true, - "optional": true, "requires": { "wrappy": "1" } @@ -9668,8 +9599,7 @@ }, "safe-buffer": { "version": "5.1.2", - "bundled": true, - "optional": true + "bundled": true }, "safer-buffer": { "version": "2.1.2", @@ -9699,7 +9629,6 @@ "string-width": { "version": "1.0.2", "bundled": true, - "optional": true, "requires": { "code-point-at": "^1.0.0", "is-fullwidth-code-point": "^1.0.0", @@ -9717,7 +9646,6 @@ "strip-ansi": { "version": "3.0.1", "bundled": true, - "optional": true, "requires": { "ansi-regex": "^2.0.0" } @@ -9756,13 +9684,11 @@ }, "wrappy": { "version": "1.0.2", - "bundled": true, - "optional": true + "bundled": true }, "yallist": { "version": "3.0.3", - "bundled": true, - "optional": true + "bundled": true } } }, @@ -10019,19 +9945,6 @@ "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": { "version": "2.0.0", "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", "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": { "version": "3.10.1", "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-3.10.1.tgz", @@ -12898,11 +12750,6 @@ "integrity": "sha1-DM8tiRZq8Ds2Y8eWU4t1rG4RTZ0=", "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": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz", @@ -13097,14 +12944,6 @@ "integrity": "sha512-OHhSbtcviqMPt7yfw5ef5aghS2jzFVKEFyCJndQt2YpSQ9qRVSEv2axSJI1paVThEu+FFGs584h/1YhxjVqajA==", "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": { "version": "2.1.0", "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", "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": { "version": "0.4.6", "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", "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": { "version": "1.6.0", "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", "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": { "version": "0.0.2-1", "resolved": "https://registry.npmjs.org/spawn-command/-/spawn-command-0.0.2-1.tgz", @@ -21517,11 +21311,6 @@ "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": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/unherit/-/unherit-1.1.2.tgz", diff --git a/plugins/woocommerce-admin/package.json b/plugins/woocommerce-admin/package.json index 8d8361e129c..0c4209ed636 100644 --- a/plugins/woocommerce-admin/package.json +++ b/plugins/woocommerce-admin/package.json @@ -93,10 +93,8 @@ "debug": "3.2.6", "dompurify": "1.0.11", "emoji-flags": "1.2.0", - "gfm-code-blocks": "1.0.0", "gridicons": "3.3.1", "history": "4.9.0", - "html-to-react": "1.4.1", "interpolate-components": "1.1.1", "marked": "0.7.0", "memoize-one": "5.1.1", @@ -105,7 +103,6 @@ "qs": "6.8.0", "react-click-outside": "3.0.1", "react-dates": "17.2.0", - "react-live": "1.12.0", "react-router-dom": "5.0.1", "react-transition-group": "2.9.0", "redux": "4.0.4" diff --git a/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md b/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md index b3f48e0c565..3696e931937 100644 --- a/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md +++ b/plugins/woocommerce-admin/packages/components/src/advanced-filters/README.md @@ -1,17 +1,18 @@ 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. -## 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. -```jsx +```js const config = { - title: _x( + title: __( + // A sentence describing filters for Orders + // See screen shot for context: https://cloudup.com/cSsUY9VeCVJ 'Orders Match {{select /}} Filters', - 'A sentence describing filters for Orders. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ', 'woocommerce-admin' ), filters: { @@ -20,19 +21,24 @@ const config = { add: __( 'Order Status', 'woocommerce-admin' ), remove: __( 'Remove order status filter', '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' ), filter: __( 'Select an order status', 'woocommerce-admin' ), }, rules: [ { 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' ), }, { 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' ), }, ], @@ -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 + ### SelectControl Render a select component with options. -```jsx -input: { - component: 'SelectControl', - options: [ - { label: 'Apples', key: 'apples' }, - { label: 'Oranges', key: 'oranges' }, - { label: 'Bananas', key: 'bananas' }, - { label: 'Cherries', key: 'cherries' }, - ], -} +```js +const config = { + ..., + filters: { + fruit: { + input: { + component: 'SelectControl', + 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. + ### Search Render an input for users to search and select using an autocomplete. -```jsx -input: { - component: 'Search', - type: 'products', - getLabels: getRequestByIdString( NAMESPACE + 'products', product => ( { - id: product.id, - label: product.name, - } ) ), -} +```js +const config = { + ..., + filters: { + product: { + input: { + 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). `getLabels`: A function returning a Promise resolving to an array of objects with `id` and `label` properties. + ### Date -under development. -### Date Range -under development. +Renders an input or two inputs allowing a user to filter based on a date value or range of values. -### Numerical Value -under development. +```js +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 -* `path` (required): The `path` parameter supplied by React-Router -* `query`: The url query string represented in object form +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. + +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. diff --git a/plugins/woocommerce-admin/packages/components/src/advanced-filters/example.md b/plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js similarity index 89% rename from plugins/woocommerce-admin/packages/components/src/advanced-filters/example.md rename to plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js index 36b990f1a2d..ec408d5b1d8 100644 --- a/plugins/woocommerce-admin/packages/components/src/advanced-filters/example.md +++ b/plugins/woocommerce-admin/packages/components/src/advanced-filters/docs/example.js @@ -1,9 +1,14 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { AdvancedFilters } from '@woocommerce/components'; const { orderStatuses } = wcSettings; -const path = (new URL(document.location)).searchParams.get('path') || '/devdocs'; -const query = {}; +const path = ( new URL( document.location ) ).searchParams.get( 'path' ) || '/devdocs'; +const query = { + component: 'advanced-filters', +}; const advancedFilters = { title: 'Orders Match {{select /}} Filters', @@ -41,7 +46,7 @@ const advancedFilters = { remove: 'Remove products filter', rule: 'Select a product filter match', title: '{{title}}Product{{/title}} {{rule /}} {{filter /}}', - filter:'Select products', + filter: 'Select products', }, rules: [ { @@ -70,8 +75,8 @@ const advancedFilters = { input: { component: 'SelectControl', options: [ - { value: 'new', label: 'New', }, - { value: 'returning', label: 'Returning', }, + { value: 'new', label: 'New' }, + { value: 'returning', label: 'Returning' }, ], defaultOption: 'new', }, @@ -130,7 +135,7 @@ const advancedFilters = { }, }; -const MyAdvancedFilters = () => ( +export default () => ( ( config={ advancedFilters } /> ); -``` \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/animation-slider/README.md b/plugins/woocommerce-admin/packages/components/src/animation-slider/README.md new file mode 100644 index 00000000000..c1967ebaefb --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/animation-slider/README.md @@ -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 + + { ( status ) => ( + One (1) + ) } + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/animation-slider/example.md b/plugins/woocommerce-admin/packages/components/src/animation-slider/docs/example.js similarity index 83% rename from plugins/woocommerce-admin/packages/components/src/animation-slider/example.md rename to plugins/woocommerce-admin/packages/components/src/animation-slider/docs/example.js index 9eef50f6dce..5cce259350d 100644 --- a/plugins/woocommerce-admin/packages/components/src/animation-slider/example.md +++ b/plugins/woocommerce-admin/packages/components/src/animation-slider/docs/example.js @@ -1,7 +1,15 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { AnimationSlider } from '@woocommerce/components'; -class MyAnimationSlider extends Component { +/** + * External dependencies + */ +import { Component } from '@wordpress/element'; + +export default class MyAnimationSlider extends Component { constructor() { super(); this.state = { @@ -39,7 +47,7 @@ class MyAnimationSlider extends Component { return (
- { status => ( + { () => (
{ pages[ page ] }
@@ -55,4 +63,3 @@ class MyAnimationSlider extends Component { ); } } -``` diff --git a/plugins/woocommerce-admin/packages/components/src/autocomplete/README.md b/plugins/woocommerce-admin/packages/components/src/autocomplete/README.md new file mode 100644 index 00000000000..7c8e1d5b0ff --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/autocomplete/README.md @@ -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' }, + }, +]; + + 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 diff --git a/plugins/woocommerce-admin/packages/components/src/autocomplete/example.md b/plugins/woocommerce-admin/packages/components/src/autocomplete/docs/example.js similarity index 67% rename from plugins/woocommerce-admin/packages/components/src/autocomplete/example.md rename to plugins/woocommerce-admin/packages/components/src/autocomplete/docs/example.js index bd46fb4fae2..d842eee2bd2 100644 --- a/plugins/woocommerce-admin/packages/components/src/autocomplete/example.md +++ b/plugins/woocommerce-admin/packages/components/src/autocomplete/docs/example.js @@ -1,6 +1,13 @@ -```jsx +/** + * Internal dependencies + */ import { Autocomplete } from '@woocommerce/components'; +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + const options = [ { key: 'apple', @@ -15,73 +22,69 @@ const options = [ { key: 'banana', label: 'Banana', - keywords: ['best', 'fruit'], - value: { id: 'banana' } + keywords: [ 'best', 'fruit' ], + value: { id: 'banana' }, }, { key: 'blueberry', label: 'Blueberry', - value: { id: 'blueberry' } + value: { id: 'blueberry' }, }, { key: 'cherry', label: 'Cherry', - value: { id: 'cherry' } + value: { id: 'cherry' }, }, { key: 'cantaloupe', label: 'Cantaloupe', - value: { id: 'cantaloupe' } + value: { id: 'cantaloupe' }, }, { key: 'dragonfruit', label: 'Dragon Fruit', - value: { id: 'dragonfruit' } + value: { id: 'dragonfruit' }, }, { key: 'elderberry', label: 'Elderberry', - value: { id: 'elderberry' } + value: { id: 'elderberry' }, }, ]; -const onChange = (selected) => { - console.log( selected ); -} -const MyAutocomplete = withState( { +export default withState( { singleSelected: [], multipleSelected: [], inlineSelected: [], } )( ( { singleSelected, multipleSelected, inlineSelected, setState } ) => (
setState( { singleSelected: selected } ) } options={ options } - placeholder='Start typing to filter options...' + placeholder="Start typing to filter options..." selected={ singleSelected } /> -
+
setState( { inlineSelected: selected } ) } options={ options } - placeholder='Start typing to filter options...' + placeholder="Start typing to filter options..." selected={ inlineSelected } /> -
+
setState( { multipleSelected: selected } ) } options={ options } - placeholder='Start typing to filter options...' + placeholder="Start typing to filter options..." selected={ multipleSelected } showClearButton />
) ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/calendar/README.md b/plugins/woocommerce-admin/packages/components/src/calendar/README.md new file mode 100644 index 00000000000..424642bf8de --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/calendar/README.md @@ -0,0 +1,65 @@ +DatePicker +=== + +## Usage + +```jsx + 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 + 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 diff --git a/plugins/woocommerce-admin/packages/components/src/calendar/example.md b/plugins/woocommerce-admin/packages/components/src/calendar/docs/example.js similarity index 72% rename from plugins/woocommerce-admin/packages/components/src/calendar/example.md rename to plugins/woocommerce-admin/packages/components/src/calendar/docs/example.js index 36f2a131f24..873b2516907 100644 --- a/plugins/woocommerce-admin/packages/components/src/calendar/example.md +++ b/plugins/woocommerce-admin/packages/components/src/calendar/docs/example.js @@ -1,10 +1,23 @@ -```jsx -import { DateRange, DatePicker } from '@woocommerce/components'; +/** @format */ +/** + * Internal dependencies + */ +import { + DateRange, + DatePicker, + H, + Section, +} from '@woocommerce/components'; + +/** + * External dependencies + */ import moment from 'moment'; +import { withState } from '@wordpress/compose'; const dateFormat = 'MM/DD/YYYY'; -const MyDateRange = withState( { +export default withState( { after: null, afterText: '', before: null, @@ -12,19 +25,19 @@ const MyDateRange = withState( { afterError: null, beforeError: null, focusedInput: 'startDate', -} )( ( { after, afterText, before, beforeText, afterError, beforeError, focusedInput, setState } ) => { +} )( ( { after, afterText, before, beforeText, afterError, focusedInput, setState } ) => { function onRangeUpdate( update ) { setState( update ); } - + function onDatePickerUpdate( { date, text, error } ) { - setState( { - after: date, + setState( { + after: date, afterText: text, afterError: error, } ); } - + return (
Date Range Picker @@ -40,19 +53,17 @@ const MyDateRange = withState( { isInvalidDate={ date => moment().isBefore( moment( date ), 'date' ) } /> - Date Picker
moment( date ).day() === 1 } />
- ) + ); } ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/card/README.md b/plugins/woocommerce-admin/packages/components/src/card/README.md new file mode 100644 index 00000000000..2fef18e870f --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/card/README.md @@ -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 +
+ +

Your stuff in a Card.

+ + +

This Card is grayed out and has no box-shadow.

+ +
+``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/card/docs/example.js b/plugins/woocommerce-admin/packages/components/src/card/docs/example.js new file mode 100644 index 00000000000..f5a06039cce --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/card/docs/example.js @@ -0,0 +1,16 @@ +/** @format */ +/** + * Internal dependencies + */ +import { Card } from '@woocommerce/components'; + +export default () => ( +
+ +

Your stuff in a Card.

+ + +

This Card is grayed out and has no box-shadow.

+ +
+); diff --git a/plugins/woocommerce-admin/packages/components/src/card/example.md b/plugins/woocommerce-admin/packages/components/src/card/example.md deleted file mode 100644 index 647fc4c0fb1..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/card/example.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -import { Card } from '@woocommerce/components'; - -const MyCard = () => ( -
- -

Your stuff in a Card.

- - -

This Card is grayed out and has no box-shadow.

- -
-); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/chart/README.md b/plugins/woocommerce-admin/packages/components/src/chart/README.md new file mode 100644 index 00000000000..7baabc05bd3 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/chart/README.md @@ -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, + }, + }, +]; + + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/chart/docs/example.js b/plugins/woocommerce-admin/packages/components/src/chart/docs/example.js new file mode 100644 index 00000000000..5fb5d3f14b9 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/chart/docs/example.js @@ -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 () => ( +
+ +
+); diff --git a/plugins/woocommerce-admin/packages/components/src/chart/example.md b/plugins/woocommerce-admin/packages/components/src/chart/example.md deleted file mode 100644 index 6cb7758e072..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/chart/example.md +++ /dev/null @@ -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 = () => ( -
- -
-); -``` \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/compare-filter/README.md b/plugins/woocommerce-admin/packages/components/src/compare-filter/README.md new file mode 100644 index 00000000000..bb3d1372a83 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/compare-filter/README.md @@ -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', +}; + + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/compare-filter/example.md b/plugins/woocommerce-admin/packages/components/src/compare-filter/docs/example.js similarity index 73% rename from plugins/woocommerce-admin/packages/components/src/compare-filter/example.md rename to plugins/woocommerce-admin/packages/components/src/compare-filter/docs/example.js index e670bed8038..579ba9c2162 100644 --- a/plugins/woocommerce-admin/packages/components/src/compare-filter/example.md +++ b/plugins/woocommerce-admin/packages/components/src/compare-filter/docs/example.js @@ -1,7 +1,10 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ 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 compareFilter = { type: 'products', @@ -17,7 +20,6 @@ const compareFilter = { }, }; -const MyCompareFilter = () => ( +export default () => ( ); -``` \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/count/README.md b/plugins/woocommerce-admin/packages/components/src/count/README.md new file mode 100644 index 00000000000..1e784f406bd --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/count/README.md @@ -0,0 +1,17 @@ +Count +=== + +Display a number with a styled border. + +## Usage + +```jsx + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/count/example.md b/plugins/woocommerce-admin/packages/components/src/count/docs/example.js similarity index 52% rename from plugins/woocommerce-admin/packages/components/src/count/example.md rename to plugins/woocommerce-admin/packages/components/src/count/docs/example.js index b70955645dc..7df0e56b657 100644 --- a/plugins/woocommerce-admin/packages/components/src/count/example.md +++ b/plugins/woocommerce-admin/packages/components/src/count/docs/example.js @@ -1,7 +1,9 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { Count } from '@woocommerce/components'; -const MyCount = () => ( +export default () => ( ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/README.md b/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/README.md index bf4808c59b3..59efb5a4e93 100644 --- a/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/README.md +++ b/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/README.md @@ -1,4 +1,4 @@ -Date Picker +Date Range Picker === Select a range of dates or single dates @@ -6,7 +6,11 @@ Select a range of dates or single dates ## Usage ```jsx - + + {} } +/> ``` ### Props @@ -15,17 +19,16 @@ Required props are marked with `*`. Name | Type | Default | Description ------- | -------- | ------- | --- -`key`* | string | none | Force a recalculation or reset of internal state when this key changes. Useful for a url change, for instance -`path`* | `string` | none | The `path` parameter supplied by React-Router -`query` | `object` | `{}` | The query string represented in object form +`query` | Object | `{}` | The query string represented in object form +`onRangeSelect` | Function | `null` | Callback called when selection is made ## URL as the source of truth -The Date Picker reads parameters from the URL querystring and updates them by creating a link to reflect newly selected parameters, which is rendered as the "Update" button. +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 - --- | --- | --- - `period` | `today` | `today`, `yesterday`, `week`, `last_week`, `month`, `last_month`, `quarter`, `last_quarter`, `year`, `last_year`, `custom` - `compare` | `previous_period` | `previous_period`, `previous_year` - `start` | none | start date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - `end` | none | end date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) +URL Parameter | Default | Possible Values +--- | --- | --- +`period` | `today` | `today`, `yesterday`, `week`, `last_week`, `month`, `last_month`, `quarter`, `last_quarter`, `year`, `last_year`, `custom` +`compare` | `previous_period` | `previous_period`, `previous_year` +`start` | none | start date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) +`end` | none | end date for custom periods `2018-04-15`. [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) diff --git a/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/docs/example.js b/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/docs/example.js new file mode 100644 index 00000000000..72c7af8375b --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/docs/example.js @@ -0,0 +1,15 @@ +/** @format */ +/** + * Internal dependencies + */ +import { DateRangeFilterPicker } from '@woocommerce/components'; + +const query = {}; + +export default () => ( + {} } + /> +); diff --git a/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/example.md b/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/example.md deleted file mode 100644 index 9a7c8c96c87..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/date-range-filter-picker/example.md +++ /dev/null @@ -1,13 +0,0 @@ -```jsx -import DateRangeFilterPicker from '@woocommerce/components'; - -const query = {}; - -const MyDateRangeFilterPicker = () => ( - {} } - /> -); -``` \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/date/README.md b/plugins/woocommerce-admin/packages/components/src/date/README.md new file mode 100644 index 00000000000..f949df6cc4f --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/date/README.md @@ -0,0 +1,19 @@ +Date +=== + +Use the `Date` component to display accessible dates or times. + +## Usage + +```jsx + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/date/docs/example.js b/plugins/woocommerce-admin/packages/components/src/date/docs/example.js new file mode 100644 index 00000000000..e827e41ad39 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/date/docs/example.js @@ -0,0 +1,9 @@ +/** @format */ +/** + * Internal dependencies + */ +import { Date } from '@woocommerce/components'; + +export default () => ( + +); diff --git a/plugins/woocommerce-admin/packages/components/src/date/example.md b/plugins/woocommerce-admin/packages/components/src/date/example.md deleted file mode 100644 index 4466ca29d8d..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/date/example.md +++ /dev/null @@ -1,7 +0,0 @@ -```jsx -import { Date } from '@woocommerce/components'; - -const MyDate = () => ( - -); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/dropdown-button/README.md b/plugins/woocommerce-admin/packages/components/src/dropdown-button/README.md new file mode 100644 index 00000000000..aa0ac5b6203 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/dropdown-button/README.md @@ -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 `` elments. + +## Usage + +```jsx + ( + + ) } + renderContent={ () => ( +

Dropdown content here

+ ) } +/> +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/dropdown-button/example.md b/plugins/woocommerce-admin/packages/components/src/dropdown-button/docs/example.js similarity index 77% rename from plugins/woocommerce-admin/packages/components/src/dropdown-button/example.md rename to plugins/woocommerce-admin/packages/components/src/dropdown-button/docs/example.js index f2f75e8427c..b6cee289066 100644 --- a/plugins/woocommerce-admin/packages/components/src/dropdown-button/example.md +++ b/plugins/woocommerce-admin/packages/components/src/dropdown-button/docs/example.js @@ -1,8 +1,15 @@ -```jsx -import { Dropdown } from '@wordpress/components'; +/** @format */ +/** + * Internal dependencies + */ import { DropdownButton } from '@woocommerce/components'; -const MyDropdownButton = () => ( +/** + * External dependencies + */ +import { Dropdown } from '@wordpress/components'; + +export default () => ( ( ( ) } /> ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/README.md b/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/README.md new file mode 100644 index 00000000000..593bd6b2662 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/README.md @@ -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 + { + return ( +
+ Display Stats + setState( { showCustomers: ! showCustomers } ) }> + setState( { showCustomers: ! showCustomers } ) } + /> + + setState( { showOrders: ! showOrders } ) }> + setState( { showOrders: ! showOrders } ) } + /> + + + + +
+ ); + } } +/> +``` + +### 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 + + + +``` + +### 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 +Display Stats +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`children` | ReactNode | `null` | A renderable component (or string) which will be displayed as the content of this item diff --git a/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/docs/example.js b/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/docs/example.js new file mode 100644 index 00000000000..891f0c8149b --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/docs/example.js @@ -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 } ) => ( + ( + + Display Stats + setState( { showCustomers: ! showCustomers } ) } + > + Show Customers + + setState( { showOrders: ! showOrders } ) } + > + Show Orders + + + + Close Menu + + + ) } + /> +) ); diff --git a/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/example.md b/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/example.md deleted file mode 100644 index 77719df68f1..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/ellipsis-menu/example.md +++ /dev/null @@ -1,40 +0,0 @@ -```jsx -import { EllipsisMenu, MenuItem, MenuTitle, Button } from '@woocommerce/components'; - -const MyEllipsisMenu = withState( { - showCustomers: true, - showOrders: true, -} )( ( { setState, showCustomers, showOrders } ) => ( - { - return ( -
- Display Stats - setState( { showCustomers: ! showCustomers } ) }> - setState( { showCustomers: ! showCustomers } ) } - /> - - setState( { showOrders: ! showOrders } ) }> - setState( { showOrders: ! showOrders } ) } - /> - - - - -
- ); - } } - /> -) ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/empty-content/README.md b/plugins/woocommerce-admin/packages/components/src/empty-content/README.md new file mode 100644 index 00000000000..4e9d63495d5 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/empty-content/README.md @@ -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 + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/empty-content/example.md b/plugins/woocommerce-admin/packages/components/src/empty-content/docs/example.js similarity index 71% rename from plugins/woocommerce-admin/packages/components/src/empty-content/example.md rename to plugins/woocommerce-admin/packages/components/src/empty-content/docs/example.js index 5bd24386bcf..2a878b82e6f 100644 --- a/plugins/woocommerce-admin/packages/components/src/empty-content/example.md +++ b/plugins/woocommerce-admin/packages/components/src/empty-content/docs/example.js @@ -1,7 +1,10 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { EmptyContent } from '@woocommerce/components'; -const MyEmptyContent = () => ( +export default () => ( ( actionURL="#" /> ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/filter-picker/README.md b/plugins/woocommerce-admin/packages/components/src/filter-picker/README.md index d8acb292953..bc9b0eeb8f3 100644 --- a/plugins/woocommerce-admin/packages/components/src/filter-picker/README.md +++ b/plugins/woocommerce-admin/packages/components/src/filter-picker/README.md @@ -1,5 +1,5 @@ Filter Picker -============= +=== Modify a url query parameter via a dropdown selection of configurable options. This component manipulates the `filter` query parameter. @@ -44,16 +44,31 @@ const renderFilterPicker = () => { ### Props -* `filters` (required): An array of filters and subFilters to construct the menu -* `path` (required): The `path` parameter supplied by React-Router -* `query`: The query string represented in object form +Name | Type | Default | Description +--- | --- | --- | --- +`config` | Object | `null` | (required) An array of filters and subFilters to construct the menu +`path` | String | `null` | (required) The `path` parameter supplied by React-Router +`query` | Object | `{}` | The query string represented in object form +`onFilterSelect` | Function | `() => {}` | Function to be called after filter selection + +### `config` structure + +The `config` prop has the following structure: + +- `label`: String - A label above the filter selector. +- `staticParams`: Array - Url parameters to persist when selecting a new filter. +- `param`: String - The url paramter this filter will modify. +- `defaultValue`: String - The default paramter value to use instead of 'all'. +- `showFilters`: Function - Determine if the filter should be shown. Supply a function with the query object as an argument returning a boolean. +- `filters`: Array - Array of filter objects. ### `filters` structure The `filters` prop is an array of filter objects. Each filter object should have the following format: -* `label`: The label for this filter. Optional only for custom component filters. -* `subFilters`: An array of more filter objects that act as "children" to this item. This set of filters is shown if the parent filter is clicked. -* `value` (required): The value for this filter, used to set the `filter` query param when clicked, if there are no `subFilters`. -* `path`: An array representing the "path" to this filter, if nested. See the Lunch > Pescatarian > Snapper example above. -* `component`: A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented. +- `chartMode`: One of: 'item-comparison', 'time-comparison' +- `component`: String - A custom component used instead of a button, might have special handling for filtering. TBD, not yet implemented. +- `label`: String - The label for this filter. Optional only for custom component filters. +- `path`: String - An array representing the "path" to this filter, if nested. +- `subFilters`: Array - An array of more filter objects that act as "children" to this item. This set of filters is shown if the parent filter is clicked. +- `value`: String - The value for this filter, used to set the `filter` query param when clicked, if there are no `subFilters`. diff --git a/plugins/woocommerce-admin/packages/components/src/filter-picker/docs/example.js b/plugins/woocommerce-admin/packages/components/src/filter-picker/docs/example.js new file mode 100644 index 00000000000..a6f02e5664a --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/filter-picker/docs/example.js @@ -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 () => ( + +); diff --git a/plugins/woocommerce-admin/packages/components/src/filter-picker/example.md b/plugins/woocommerce-admin/packages/components/src/filter-picker/example.md deleted file mode 100644 index 0576f08b768..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/filter-picker/example.md +++ /dev/null @@ -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 = () => ( - -); -``` \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/filters/README.md b/plugins/woocommerce-admin/packages/components/src/filters/README.md new file mode 100644 index 00000000000..bc86705f7c3 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/filters/README.md @@ -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 diff --git a/plugins/woocommerce-admin/packages/components/src/filters/example.md b/plugins/woocommerce-admin/packages/components/src/filters/docs/example.js similarity index 92% rename from plugins/woocommerce-admin/packages/components/src/filters/example.md rename to plugins/woocommerce-admin/packages/components/src/filters/docs/example.js index 95e04d278c8..3d8f27e28fe 100644 --- a/plugins/woocommerce-admin/packages/components/src/filters/example.md +++ b/plugins/woocommerce-admin/packages/components/src/filters/docs/example.js @@ -1,5 +1,14 @@ -```jsx -import { ReportFilters } from '@woocommerce/components'; +/** @format */ +/** + * Internal dependencies + */ +import { + AdvancedFilters, + CompareFilter, + H, + ReportFilters, + Section, +} from '@woocommerce/components'; const { orderStatuses } = wcSettings; const path = ''; @@ -53,7 +62,7 @@ const advancedFilters = { remove: 'Remove products filter', rule: 'Select a product filter match', title: 'Product {{rule /}} {{filter /}}', - filter:'Select products', + filter: 'Select products', }, rules: [ { @@ -82,8 +91,8 @@ const advancedFilters = { input: { component: 'SelectControl', options: [ - { value: 'new', label: 'New', }, - { value: 'returning', label: 'Returning', }, + { value: 'new', label: 'New' }, + { value: 'returning', label: 'Returning' }, ], defaultOption: 'new', }, @@ -156,7 +165,7 @@ const compareFilter = { }, }; -const MyReportFilters = () => ( +export default () => (
Date picker only
@@ -188,4 +197,3 @@ const MyReportFilters = () => (
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/flag/README.md b/plugins/woocommerce-admin/packages/components/src/flag/README.md new file mode 100644 index 00000000000..ad848c2021b --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/flag/README.md @@ -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 + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/flag/example.md b/plugins/woocommerce-admin/packages/components/src/flag/docs/example.js similarity index 67% rename from plugins/woocommerce-admin/packages/components/src/flag/example.md rename to plugins/woocommerce-admin/packages/components/src/flag/docs/example.js index ddf919c4df6..d8bf702d9ed 100644 --- a/plugins/woocommerce-admin/packages/components/src/flag/example.md +++ b/plugins/woocommerce-admin/packages/components/src/flag/docs/example.js @@ -1,22 +1,22 @@ -```jsx -import { Flag } from '@woocommerce/components'; +/** @format */ +/** + * Internal dependencies + */ +import { Flag, H, Section } from '@woocommerce/components'; -const MyFlag = () => ( +export default () => (
Default (inherits parent font size)
- +
- Large
- Invalid Country Code
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/form/README.md b/plugins/woocommerce-admin/packages/components/src/form/README.md new file mode 100644 index 00000000000..533aefbd522 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/form/README.md @@ -0,0 +1,47 @@ +Form +=== + +A form component to handle form state and provide input helper props. + +## Usage + +```jsx +const initialValues = { firstName: '' }; + +
{} } + initialValues={ initialValues } +> + { ( { + getInputProps, + values, + errors, + handleSubmit, + } ) => ( +
+ + +
+ ) } + +``` + +### 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` | | `{}` | diff --git a/plugins/woocommerce-admin/packages/components/src/form/example.md b/plugins/woocommerce-admin/packages/components/src/form/docs/example.js similarity index 85% rename from plugins/woocommerce-admin/packages/components/src/form/example.md rename to plugins/woocommerce-admin/packages/components/src/form/docs/example.js index a10617039a3..7e6e7721c59 100644 --- a/plugins/woocommerce-admin/packages/components/src/form/example.md +++ b/plugins/woocommerce-admin/packages/components/src/form/docs/example.js @@ -1,7 +1,20 @@ -```jsx -import { Button, CheckboxControl, RadioControl, SelectControl, TextControl } from '@wordpress/components'; +/** @format */ +/** + * Internal dependencies + */ import { Form } from '@woocommerce/components'; +/** + * External dependencies + */ +import { + Button, + CheckboxControl, + RadioControl, + SelectControl, + TextControl, +} from '@wordpress/components'; + const validate = ( values ) => { const errors = {}; if ( ! values.firstName ) { @@ -16,13 +29,12 @@ const validate = ( values ) => { const onSubmitCallback = ( values ) => console.log( values ); const initialValues = { firstName: '', lastName: '', select: '3', checkbox: true, radio: '2' }; -const MyForm = () => ( +export default () => (
{ ( { getInputProps, values, errors, - setValue, handleSubmit, } ) => (
@@ -35,7 +47,7 @@ const MyForm = () => ( { ...getInputProps( 'lastName' ) } /> ( { ...getInputProps( 'select' ) } /> ( ) } ); -``` - \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/gravatar/README.md b/plugins/woocommerce-admin/packages/components/src/gravatar/README.md new file mode 100644 index 00000000000..71add04555d --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/gravatar/README.md @@ -0,0 +1,23 @@ +Gravatar +=== + +Display a users Gravatar. + +## Usage + +```jsx + +``` + +### 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 diff --git a/plugins/woocommerce-admin/packages/components/src/gravatar/example.md b/plugins/woocommerce-admin/packages/components/src/gravatar/docs/example.js similarity index 61% rename from plugins/woocommerce-admin/packages/components/src/gravatar/example.md rename to plugins/woocommerce-admin/packages/components/src/gravatar/docs/example.js index fa58b707b9d..1f0b45e2a44 100644 --- a/plugins/woocommerce-admin/packages/components/src/gravatar/example.md +++ b/plugins/woocommerce-admin/packages/components/src/gravatar/docs/example.js @@ -1,10 +1,12 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { Gravatar } from '@woocommerce/components'; -const MyGravatar = () => ( +export default () => ( ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/image-asset/README.md b/plugins/woocommerce-admin/packages/components/src/image-asset/README.md new file mode 100644 index 00000000000..308a0944e9a --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/image-asset/README.md @@ -0,0 +1,21 @@ +ImageAsset +=== + +A component that loads an image, allowing images to be loaded relative to the main asset/plugin folder. +Props are passed through to `` + +## Usage + +```jsx + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`src` | String | `null` | (required) Image location to pass through to `` +`alt` | String | `null` | (required) Alt text to pass through to `` diff --git a/plugins/woocommerce-admin/packages/components/src/image-asset/example.md b/plugins/woocommerce-admin/packages/components/src/image-asset/docs/example.js similarity index 68% rename from plugins/woocommerce-admin/packages/components/src/image-asset/example.md rename to plugins/woocommerce-admin/packages/components/src/image-asset/docs/example.js index 2f3a7c5f937..d4e82c92d1f 100644 --- a/plugins/woocommerce-admin/packages/components/src/image-asset/example.md +++ b/plugins/woocommerce-admin/packages/components/src/image-asset/docs/example.js @@ -1,10 +1,12 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { ImageAsset } from '@woocommerce/components'; -const MyImageAsset = () => ( +export default () => ( ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/link/README.md b/plugins/woocommerce-admin/packages/components/src/link/README.md new file mode 100644 index 00000000000..8c1fe40056c --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/link/README.md @@ -0,0 +1,23 @@ +Link +=== + +Use `Link` to create a link to another resource. It accepts a type to automatically +create wp-admin links, wc-admin links, and external links. + +## Usage + +```jsx + + Coupons + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`href` | String | `null` | (required) The resource to link to +`type` | One of: 'wp-admin', 'wc-admin', 'external' | `'wc-admin'` | Type of link. For wp-admin and wc-admin, the correct prefix is appended diff --git a/plugins/woocommerce-admin/packages/components/src/link/example.md b/plugins/woocommerce-admin/packages/components/src/link/docs/example.js similarity index 66% rename from plugins/woocommerce-admin/packages/components/src/link/example.md rename to plugins/woocommerce-admin/packages/components/src/link/docs/example.js index 31707102d9d..1a6a1f9736f 100644 --- a/plugins/woocommerce-admin/packages/components/src/link/example.md +++ b/plugins/woocommerce-admin/packages/components/src/link/docs/example.js @@ -1,7 +1,10 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { Link } from '@woocommerce/components'; -const MyLink = () => ( +export default () => ( ( Coupons ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/list/README.md b/plugins/woocommerce-admin/packages/components/src/list/README.md new file mode 100644 index 00000000000..6005f5b9077 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/list/README.md @@ -0,0 +1,51 @@ +List +=== + +List component to display a list of items. + +## Usage + +```jsx +const listItems = [ + { + title: 'List item title', + description: 'List item description text', + }, + { + before: , + title: 'List item with before icon', + description: 'List item description text', + }, + { + before: , + after: , + title: 'List item with before and after icons', + description: 'List item description text', + }, + { + title: 'Clickable list item', + description: 'List item description text', + onClick: () => alert( 'List item clicked' ), + }, +]; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional class name to style the component +`items` | Array | `null` | (required) An array of list items + +`items` structure: + +* `after`: ReactNode - Content displayed after the list item text. +* `before`: ReactNode - Content displayed before the list item text. +* `className`: String - Additional class name to style the list item. +* `description`: String - Description displayed beneath the list item title. +* `href`: String - Href attribute used in a Link wrapped around the item. +* `onClick`: Function - Called when the list item is clicked. +* `target`: String - Target attribute used for Link wrapper. +* `title`: String - Title displayed for the list item. \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/list/example.md b/plugins/woocommerce-admin/packages/components/src/list/docs/example.js similarity index 87% rename from plugins/woocommerce-admin/packages/components/src/list/example.md rename to plugins/woocommerce-admin/packages/components/src/list/docs/example.js index 45fe3be82fc..fa723ded715 100644 --- a/plugins/woocommerce-admin/packages/components/src/list/example.md +++ b/plugins/woocommerce-admin/packages/components/src/list/docs/example.js @@ -1,5 +1,12 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { List } from '@woocommerce/components'; + +/** + * External dependencies + */ import Gridicon from 'gridicons'; const listItems = [ @@ -25,9 +32,8 @@ const listItems = [ }, ]; -const MyList = () => ( +export default () => (
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/list/index.js b/plugins/woocommerce-admin/packages/components/src/list/index.js index d8123135c92..e5ca69cf805 100644 --- a/plugins/woocommerce-admin/packages/components/src/list/index.js +++ b/plugins/woocommerce-admin/packages/components/src/list/index.js @@ -117,7 +117,7 @@ List.propTypes = { */ href: PropTypes.string, /** - * Content displayed after the list item text. + * Called when the list item is clicked. */ onClick: PropTypes.func, /** diff --git a/plugins/woocommerce-admin/packages/components/src/order-status/README.md b/plugins/woocommerce-admin/packages/components/src/order-status/README.md new file mode 100644 index 00000000000..3475aaea72a --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/order-status/README.md @@ -0,0 +1,19 @@ +OrderStatus +=== + +Use `OrderStatus` to display a badge with human-friendly text describing the current order status. + +## Usage + +```jsx +const order = { status: 'processing' }; // Use a real WooCommerce Order here. + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`order` | Object | `null` | (required) The order to display a status for. See: https://woocommerce.github.io/woocommerce-rest-api-docs/#order-properties +`className` | String | `null` | Additional CSS classes diff --git a/plugins/woocommerce-admin/packages/components/src/order-status/example.md b/plugins/woocommerce-admin/packages/components/src/order-status/docs/example.js similarity index 76% rename from plugins/woocommerce-admin/packages/components/src/order-status/example.md rename to plugins/woocommerce-admin/packages/components/src/order-status/docs/example.js index 99d647ddd54..52739c0c15c 100644 --- a/plugins/woocommerce-admin/packages/components/src/order-status/example.md +++ b/plugins/woocommerce-admin/packages/components/src/order-status/docs/example.js @@ -1,11 +1,13 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { OrderStatus } from '@woocommerce/components'; -const MyOrderStatus = () => ( +export default () => (
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/pagination/README.md b/plugins/woocommerce-admin/packages/components/src/pagination/README.md new file mode 100644 index 00000000000..ec9a30d8507 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/pagination/README.md @@ -0,0 +1,28 @@ +Pagination +=== + +Use `Pagination` to allow navigation between pages that represent a collection of items. +The component allows for selecting a new page and items per page options. + +## Usage + +```jsx + setState( { page: newPage } ) } + onPerPageChange={ ( newPerPage ) => setState( { perPage: newPerPage } ) } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`page` | Number | `null` | (required) The current page of the collection +`onPageChange` | Function | `noop` | A function to execute when the page is changed +`perPage` | Number | `null` | (required) The amount of results that are being displayed per page +`onPerPageChange` | Function | `noop` | A function to execute when the per page option is changed +`total` | Number | `null` | (required) The total number of results +`className` | String | `null` | Additional classNames diff --git a/plugins/woocommerce-admin/packages/components/src/pagination/docs/example.js b/plugins/woocommerce-admin/packages/components/src/pagination/docs/example.js new file mode 100644 index 00000000000..e2366e240f9 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/pagination/docs/example.js @@ -0,0 +1,23 @@ +/** @format */ +/** + * Internal dependencies + */ +import { Pagination } from '@woocommerce/components'; + +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + +export default withState( { + page: 2, + perPage: 50, +} )( ( { page, perPage, setState } ) => ( + setState( { page: newPage } ) } + onPerPageChange={ ( newPerPage ) => setState( { perPage: newPerPage } ) } + /> +) ); diff --git a/plugins/woocommerce-admin/packages/components/src/pagination/example.md b/plugins/woocommerce-admin/packages/components/src/pagination/example.md deleted file mode 100644 index 9efcb6f965c..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/pagination/example.md +++ /dev/null @@ -1,16 +0,0 @@ -```jsx -import { Pagination } from '@woocommerce/components'; - -const MyPagination = withState( { - page: 2, - perPage: 50, -} )( ( { page, perPage, setState } ) => ( - setState( { page } ) } - onPerPageChange={ ( perPage ) => setState( { perPage } ) } - /> -) ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/product-image/README.md b/plugins/woocommerce-admin/packages/components/src/product-image/README.md new file mode 100644 index 00000000000..79b9a89231d --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/product-image/README.md @@ -0,0 +1,31 @@ +ProductImage +=== + +Use `ProductImage` to display a product's or variation's featured image. +If no image can be found, a placeholder matching the front-end image +placeholder will be displayed. + +## Usage + +```jsx +// Use a real WooCommerce Product here. +const product = { + images: [ + { + src: 'https://cldup.com/6L9h56D9Bw.jpg', + }, + ], +}; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`width` | Number | `60` | The width of image to display +`height` | Number | `60` | The height of image to display +`className` | String | `''` | Additional CSS classes +`product` | Object | `null` | Product or variation object. The image to display will be pulled from `product.images` or `variation.image`. See https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties and https://woocommerce.github.io/woocommerce-rest-api-docs/#product-variation-properties +`alt` | String | `null` | Text to use as the image alt attribute diff --git a/plugins/woocommerce-admin/packages/components/src/product-image/example.md b/plugins/woocommerce-admin/packages/components/src/product-image/docs/example.js similarity index 65% rename from plugins/woocommerce-admin/packages/components/src/product-image/example.md rename to plugins/woocommerce-admin/packages/components/src/product-image/docs/example.js index 598f63aa517..ae32b7f2bc4 100644 --- a/plugins/woocommerce-admin/packages/components/src/product-image/example.md +++ b/plugins/woocommerce-admin/packages/components/src/product-image/docs/example.js @@ -1,15 +1,17 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { ProductImage } from '@woocommerce/components'; -const MyProductImage = () => ( +export default () => (
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/rating/README.md b/plugins/woocommerce-admin/packages/components/src/rating/README.md new file mode 100644 index 00000000000..929d94396b1 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/rating/README.md @@ -0,0 +1,62 @@ +Rating +=== + +Use `Rating` to display a set of stars, filled, empty or half-filled, that represents a +rating in a scale between 0 and the prop `totalStars` (default 5). + +## Usage + +```jsx + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`rating` | Number | `0` | Number of stars that should be filled. You can pass a partial number of stars like `2.5` +`totalStars` | Number | `5` | The total number of stars the rating is out of +`size` | Number | `18` | The size in pixels the stars should be rendered at +`className` | String | `null` | Additional CSS classes + + +ProductRating +=== + +Display a set of stars representing the product's average rating. + +## Usage + +```jsx +// Use a real WooCommerce Product here. +const product = { average_rating: 3.5 }; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`product` | Object | `null` | (required) A product object containing a `average_rating`. See https://woocommerce.github.io/woocommerce-rest-api-docs/#products + + +ReviewRating +=== + +Display a set of stars representing the review's rating. + +## Usage + +```jsx +// Use a real WooCommerce Review here. +const review = { rating: 5 }; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`review` | Object | `null` | (required) A review object containing a `rating`. See https://woocommerce.github.io/woocommerce-rest-api-docs/#retrieve-product-reviews diff --git a/plugins/woocommerce-admin/packages/components/src/rating/example.md b/plugins/woocommerce-admin/packages/components/src/rating/docs/example.js similarity index 86% rename from plugins/woocommerce-admin/packages/components/src/rating/example.md rename to plugins/woocommerce-admin/packages/components/src/rating/docs/example.js index 86f53e45b6f..ac94800d42e 100644 --- a/plugins/woocommerce-admin/packages/components/src/rating/example.md +++ b/plugins/woocommerce-admin/packages/components/src/rating/docs/example.js @@ -1,7 +1,10 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { ReviewRating, ProductRating, Rating } from '@woocommerce/components'; -const MyRating = () => { +export default () => { const product = { average_rating: 3.5 }; const review = { rating: 5 }; @@ -22,4 +25,3 @@ const MyRating = () => {
); }; -``` diff --git a/plugins/woocommerce-admin/packages/components/src/search-list-control/README.md b/plugins/woocommerce-admin/packages/components/src/search-list-control/README.md new file mode 100644 index 00000000000..5b7ae365533 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/search-list-control/README.md @@ -0,0 +1,73 @@ +SearchListControl +=== + +Component to display a searchable, selectable list of items. + +## Usage + +```jsx + setState( { selected: items } ) } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional CSS classes +`isHierarchical` | Boolean | `null` | Whether the list of items is hierarchical or not. If true, each list item is expected to have a parent property +`isLoading` | Boolean | `null` | Whether the list of items is still loading +`isSingle` | Boolean | `null` | Restrict selections to one item +`list` | Array | `null` | A complete list of item objects, each with id, name properties. This is displayed as a clickable/keyboard-able list, and possibly filtered by the search term (searches name) +`messages` | Object | `null` | Messages displayed or read to the user. Configure these to reflect your object type. See `defaultMessages` above for examples +`onChange` | Function | `null` | (required) Callback fired when selected items change, whether added, cleared, or removed. Passed an array of item objects (as passed in via props.list) +`onSearch` | Function | `null` | Callback fired when the search field is used +`renderItem` | Function | `null` | Callback to render each item in the selection list, allows any custom object-type rendering +`selected` | Array | `null` | (required) The list of currently selected items +`search` | String | `null` | +`setState` | Function | `null` | +`debouncedSpeak` | Function | `null` | +`instanceId` | Number | `null` | + +### `list` item structure: + + - `id`: Number + - `name`: String + +### `messages` object structure: + + - `clear`: String - A more detailed label for the "Clear all" button, read to screen reader users. + - `list`: String - Label for the list of selectable items, only read to screen reader users. + - `noItems`: String - Message to display when the list is empty (implies nothing loaded from the server +or parent component). + - `noResults`: String - Message to display when no matching results are found. %s is the search term. + - `search`: String - Label for the search input + - `selected`: Function - Label for the selected items. This is actually a function, so that we can pass +through the count of currently selected items. + - `updated`: String - Label indicating that search results have changed, read to screen reader users. + + +SearchListItem +=== + +## Usage + +Used implicitly by `SearchListControl` when the `renderItem` prop is omitted. + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional CSS classes +`countLabel` | ReactNode | `null` | Label to display if `showCount` is set to true. If undefined, it will use `item.count` +`depth` | Number | `0` | Depth, non-zero if the list is hierarchical +`item` | Object | `null` | Current item to display +`isSelected` | Boolean | `null` | Whether this item is selected +`isSingle` | Boolean | `null` | Whether this should only display a single item (controls radio vs checkbox icon) +`onSelect` | Function | `null` | Callback for selecting the item +`search` | String | `''` | Search string, used to highlight the substring in the item name +`showCount` | Boolean | `false` | Toggles the "count" bubble on/off diff --git a/plugins/woocommerce-admin/packages/components/src/search-list-control/example.md b/plugins/woocommerce-admin/packages/components/src/search-list-control/docs/example.js similarity index 79% rename from plugins/woocommerce-admin/packages/components/src/search-list-control/example.md rename to plugins/woocommerce-admin/packages/components/src/search-list-control/docs/example.js index 016ba6bd79b..8646eacd73d 100644 --- a/plugins/woocommerce-admin/packages/components/src/search-list-control/example.md +++ b/plugins/woocommerce-admin/packages/components/src/search-list-control/docs/example.js @@ -1,7 +1,15 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { SearchListControl } from '@woocommerce/components'; -const MySearchListControl = withState( { +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + +export default withState( { selected: [], loading: true, } )( ( { selected, loading, setState } ) => { @@ -26,4 +34,3 @@ const MySearchListControl = withState( {
); } ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/search/README.md b/plugins/woocommerce-admin/packages/components/src/search/README.md new file mode 100644 index 00000000000..4855a4f7077 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/search/README.md @@ -0,0 +1,36 @@ +Search +=== + +A search box which autocompletes results while typing, allowing for the user to select an existing object +(product, order, customer, etc). Currently only products are supported. + +## Usage + +```jsx + setState( { selected: items } ) } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`allowFreeTextSearch` | Boolean | `false` | Render additional options in the autocompleter to allow free text entering depending on the type +`className` | String | `null` | Class name applied to parent div +`onChange` | Function | `noop` | Function called when selected results change, passed result list +`type` | One of: 'categories', 'countries', 'coupons', 'customers', 'downloadIps', 'emails', 'orders', 'products', 'taxes', 'usernames', 'variations' | `null` | (required) The object type to be used in searching +`placeholder` | String | `null` | A placeholder for the search input +`selected` | Array | `[]` | An array of objects describing selected values. If the label of the selected value is omitted, the Tag of that value will not be rendered inside the search box. +`inlineTags` | Boolean | `false` | Render tags inside input, otherwise render below input +`showClearButton` | Boolean | `false` | Render a 'Clear' button next to the input box to remove its contents +`staticResults` | Boolean | `false` | Render results list positioned statically instead of absolutely +`disabled` | Boolean | `false` | Whether the control is disabled or not + +### `selected` item structure: + +- `id`: One of type: number, string +- `label`: String \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/search/example.md b/plugins/woocommerce-admin/packages/components/src/search/docs/example.js similarity index 73% rename from plugins/woocommerce-admin/packages/components/src/search/example.md rename to plugins/woocommerce-admin/packages/components/src/search/docs/example.js index b02a6d2e682..3631f58964a 100644 --- a/plugins/woocommerce-admin/packages/components/src/search/example.md +++ b/plugins/woocommerce-admin/packages/components/src/search/docs/example.js @@ -1,7 +1,15 @@ -```jsx -import { Search } from '@woocommerce/components'; +/** @format */ +/** + * Internal dependencies + */ +import { H, Search, Section } from '@woocommerce/components'; -const MySearch = withState( { +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + +export default withState( { selected: [], inlineSelected: [], } )( ( { selected, inlineSelected, setState } ) => ( @@ -27,4 +35,3 @@ const MySearch = withState( { ) ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/section-header/README.md b/plugins/woocommerce-admin/packages/components/src/section-header/README.md new file mode 100644 index 00000000000..fc67819a165 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/section-header/README.md @@ -0,0 +1,18 @@ +SectionHeader +=== + +A header component. The header can contain a title, actions via children, and an `EllipsisMenu` menu. + +## Usage + +```jsx + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional CSS classes +`menu` | (custom validator) | `null` | An `EllipsisMenu`, with filters used to control the content visible in this card +`title` | One of type: string, node | `null` | (required) The title to use for this card diff --git a/plugins/woocommerce-admin/packages/components/src/section-header/docs/example.js b/plugins/woocommerce-admin/packages/components/src/section-header/docs/example.js new file mode 100644 index 00000000000..8d6c44b71f5 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/section-header/docs/example.js @@ -0,0 +1,7 @@ +/** @format */ +/** + * Internal dependencies + */ +import { SectionHeader } from '@woocommerce/components'; + +export default () => ; diff --git a/plugins/woocommerce-admin/packages/components/src/section-header/example.md b/plugins/woocommerce-admin/packages/components/src/section-header/example.md deleted file mode 100644 index 0a23804dc5b..00000000000 --- a/plugins/woocommerce-admin/packages/components/src/section-header/example.md +++ /dev/null @@ -1,5 +0,0 @@ -```jsx -import { SectionHeader } from '@woocommerce/components'; - -const MySectionHeader = () => ; -``` diff --git a/plugins/woocommerce-admin/packages/components/src/section/README.md b/plugins/woocommerce-admin/packages/components/src/section/README.md new file mode 100644 index 00000000000..85675dc9154 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/section/README.md @@ -0,0 +1,38 @@ +H +=== + +These components are used to frame out the page content for accessible heading hierarchy. Instead of defining fixed heading levels +(`h2`, `h3`, …) you can use `` to create "section headings", which look to the parent `
`s for the appropriate +heading level. + +## Usage + +```jsx +
+ Header using a contextual level (h3) +
+

This is an article component wrapper.

+ Another header with contextual level (h4) +
+

There is no wrapper component here.

+ This is an h5 +
+
+
+``` + +Section +=== + +The section wrapper, used to indicate a sub-section (and change the header level context). + +## Usage + +See above + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`component` | One of type: func, string, bool | `null` | The wrapper component for this section. Optional, defaults to `div`. If passed false, no wrapper is used. Additional props passed to Section are passed on to the component +`children` | ReactNode | `null` | The children inside this section, rendered in the `component`. This increases the context level for the next heading used diff --git a/plugins/woocommerce-admin/packages/components/src/section/example.md b/plugins/woocommerce-admin/packages/components/src/section/docs/example.js similarity index 77% rename from plugins/woocommerce-admin/packages/components/src/section/example.md rename to plugins/woocommerce-admin/packages/components/src/section/docs/example.js index f0faad6fe91..dec07199419 100644 --- a/plugins/woocommerce-admin/packages/components/src/section/example.md +++ b/plugins/woocommerce-admin/packages/components/src/section/docs/example.js @@ -1,10 +1,13 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { H, Section } from '@woocommerce/components'; -const MySection = () => ( +export default () => (
Header using a contextual level (h3) -
+

This is an article component wrapper.

Another header with contextual level (h4)
@@ -14,4 +17,3 @@ const MySection = () => (
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/segmented-selection/README.md b/plugins/woocommerce-admin/packages/components/src/segmented-selection/README.md new file mode 100644 index 00000000000..75202cb1f5b --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/segmented-selection/README.md @@ -0,0 +1,39 @@ +SegmentedSelection +=== + +Create a panel of styled selectable options rendering stylized checkboxes and labels + +## Usage + +```jsx + setState( { selected: data[ name ] } ) } + name={ name } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional CSS classes +`options` | Array | `null` | (required) An Array of options to render. The array needs to be composed of objects with properties `label` and `value` +`selected` | String | `null` | Value of selected item +`onSelect` | Function | `null` | (required) Callback to be executed after selection +`name` | String | `null` | (required) This will be the key in the key and value arguments supplied to `onSelect` +`legend` | String | `null` | (required) Create a legend visible to screen readers + +### `options` structure + +The `options` array needs to be composed of objects with properties: + +- `value`: String - Input value for this option. +- `label`: String - Label for this option. \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/segmented-selection/example.md b/plugins/woocommerce-admin/packages/components/src/segmented-selection/docs/example.js similarity index 64% rename from plugins/woocommerce-admin/packages/components/src/segmented-selection/example.md rename to plugins/woocommerce-admin/packages/components/src/segmented-selection/docs/example.js index ee3c1b3de48..5019001b4f3 100644 --- a/plugins/woocommerce-admin/packages/components/src/segmented-selection/example.md +++ b/plugins/woocommerce-admin/packages/components/src/segmented-selection/docs/example.js @@ -1,9 +1,17 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { SegmentedSelection } from '@woocommerce/components'; +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + const name = 'number'; -const MySegmentedSelection = withState( { +export default withState( { selected: 'two', } )( ( { selected, setState } ) => ( setState( { selected: data[name] } ) } + onSelect={ ( data ) => setState( { selected: data[ name ] } ) } name={ name } /> ) ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/simple-select-control/README.md b/plugins/woocommerce-admin/packages/components/src/simple-select-control/README.md new file mode 100644 index 00000000000..38a97a9c5d0 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/simple-select-control/README.md @@ -0,0 +1,45 @@ +SimpleSelectControl +=== + +A component for displaying a material styled 'simple' select control. + +## Usage + +```jsx +const petOptions = [ + { + value: 'cat', + label: 'Cat', + }, + { + value: 'dog', + label: 'Dog', + }, +]; + + this.setState( { pet: value } ) } + options={ petOptions } + value={ pet } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional class name to style the component +`label` | String | `null` | A label to use for the main select element +`options` | Array | `null` | An array of options to use for the dropddown +`onChange` | Function | `null` | A function that receives the value of the new option that is being selected as input +`value` | String | `null` | The currently value of the select element +`help` | One of type: string, node | `null` | If this property is added, a help text will be generated using help property as the content + +### `options` structure + +The `options` array needs to be composed of objects with properties: + +- `value`: String - Input value for this option. +- `label`: String - Label for this option. +- `disabled`: Boolean - Disable the option. \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/simple-select-control/example.md b/plugins/woocommerce-admin/packages/components/src/simple-select-control/docs/example.js similarity index 77% rename from plugins/woocommerce-admin/packages/components/src/simple-select-control/example.md rename to plugins/woocommerce-admin/packages/components/src/simple-select-control/docs/example.js index 969811d3016..4090f6c8b84 100644 --- a/plugins/woocommerce-admin/packages/components/src/simple-select-control/example.md +++ b/plugins/woocommerce-admin/packages/components/src/simple-select-control/docs/example.js @@ -1,8 +1,15 @@ - -```jsx +/** @format */ +/** + * Internal dependencies + */ import { SimpleSelectControl } from '@woocommerce/components'; -class MySimpleSelectControl extends Component { +/** + * External dependencies + */ +import { Component } from '@wordpress/element'; + +export default class MySimpleSelectControl extends Component { constructor() { super(); this.state = { @@ -47,4 +54,3 @@ class MySimpleSelectControl extends Component { ); } } -``` \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/spinner/README.md b/plugins/woocommerce-admin/packages/components/src/spinner/README.md new file mode 100644 index 00000000000..b85003bd1eb --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/spinner/README.md @@ -0,0 +1,16 @@ +Spinner +=== + +Spinner - An indeterminate circular progress indicator. + +## Usage + +```jsx + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional class name to style the component diff --git a/plugins/woocommerce-admin/packages/components/src/spinner/example.md b/plugins/woocommerce-admin/packages/components/src/spinner/docs/example.js similarity index 54% rename from plugins/woocommerce-admin/packages/components/src/spinner/example.md rename to plugins/woocommerce-admin/packages/components/src/spinner/docs/example.js index a226a0906a3..11398a97adf 100644 --- a/plugins/woocommerce-admin/packages/components/src/spinner/example.md +++ b/plugins/woocommerce-admin/packages/components/src/spinner/docs/example.js @@ -1,9 +1,11 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { Spinner } from '@woocommerce/components'; -const MySpinner = () => ( +export default () => (
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/split-button/README.md b/plugins/woocommerce-admin/packages/components/src/split-button/README.md new file mode 100644 index 00000000000..d6d86bacdc5 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/split-button/README.md @@ -0,0 +1,46 @@ +SplitButton +=== + +A component for displaying a button with a main action plus a secondary set of actions behind a menu toggle. + +## Usage + +```jsx + alert( 'Primary Main Action clicked' ) } + controls={ [ + { + label: 'Up', + onClick: () => alert( 'Primary Up clicked' ), + }, + { + label: 'Down', + icon: , + onClick: () => alert( 'Primary Down clicked' ), + }, + ] } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`isPrimary` | Boolean | `false` | Whether the button is styled as a primary button +`mainIcon` | ReactNode | `null` | Icon for the main button +`mainLabel` | String | `null` | Label for the main button +`onClick` | Function | `noop` | Function to activate when the the main button is clicked +`menuLabel` | String | `null` | Label to display for the menu of actions, used as a heading on the mobile popover and for accessible text +`controls` | Array | `null` | (required) An array of additional actions. Accepts additional icon, label, and onClick props +`className` | String | `null` | Additional CSS classes + +### `controls` structure + +Array of additional actions with properties: + +- `icon`: One of type: string, element +- `label`: String - Label displayed for this button. +- `onClick`: Function - Click handler for this button. \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/split-button/example.md b/plugins/woocommerce-admin/packages/components/src/split-button/docs/example.js similarity index 90% rename from plugins/woocommerce-admin/packages/components/src/split-button/example.md rename to plugins/woocommerce-admin/packages/components/src/split-button/docs/example.js index e9bc9cc782f..43374a87635 100644 --- a/plugins/woocommerce-admin/packages/components/src/split-button/example.md +++ b/plugins/woocommerce-admin/packages/components/src/split-button/docs/example.js @@ -1,7 +1,15 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { SplitButton } from '@woocommerce/components'; -const MySplitButton = () => ( +/** + * External dependencies + */ +import Gridicon from 'gridicons'; + +export default () => (
( />
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/stepper/README.md b/plugins/woocommerce-admin/packages/components/src/stepper/README.md new file mode 100644 index 00000000000..07ad76f7bc6 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/stepper/README.md @@ -0,0 +1,49 @@ +Stepper +=== + +A stepper component to indicate progress in a set number of steps. + +## Usage + +```jsx +const steps = [ + { + key: 'first', + label: 'First', + description: 'Step item description', + content:
First step content.
, + }, + { + key: 'second', + label: 'Second', + description: 'Step item description', + content:
Second step content.
, + }, +]; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional class name to style the component +`currentStep` | String | `null` | (required) The current step's key +`steps` | Array | `null` | (required) An array of steps used +`isVertical` | Boolean | `false` | If the stepper is vertical instead of horizontal +`isPending` | Boolean | `false` | Optionally mark the current step as pending to show a spinner + +### `steps` structure + +Array of step objects with properties: + +- `key:` String - Key used to identify step. +- `label`: String - Label displayed in stepper. +- `description`: String - Description displayed beneath the label. +- `isComplete`: Boolean - Optionally mark a step complete regardless of step index. +- `content`: ReactNode - Content displayed when the step is active. \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/stepper/example.md b/plugins/woocommerce-admin/packages/components/src/stepper/docs/example.js similarity index 90% rename from plugins/woocommerce-admin/packages/components/src/stepper/example.md rename to plugins/woocommerce-admin/packages/components/src/stepper/docs/example.js index 15322df670e..8101fa9244e 100644 --- a/plugins/woocommerce-admin/packages/components/src/stepper/example.md +++ b/plugins/woocommerce-admin/packages/components/src/stepper/docs/example.js @@ -1,7 +1,15 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { Stepper } from '@woocommerce/components'; -const MyStepper = withState( { +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + +export default withState( { currentStep: 'first', isComplete: false, isPending: false, @@ -48,13 +56,13 @@ const MyStepper = withState( { ) : (
); } ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/summary/README.md b/plugins/woocommerce-admin/packages/components/src/summary/README.md new file mode 100644 index 00000000000..35fef945143 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/summary/README.md @@ -0,0 +1,82 @@ +SummaryList +=== + +A container element for a list of SummaryNumbers. This component handles detecting & switching to the mobile format on smaller screens. + +## Usage + +```jsx + + { () => { + return [ + , + , + ]; + } } + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`children` | Function | `null` | (required) A function returning a list of ``s +`label` | String | `__( 'Performance Indicators', 'woocommerce-admin' )` | An optional label of this group, read to screen reader users + + +SummaryNumber +=== + +A component to show a value, label, and an optional change percentage. Can also act as a link to a specific report focus. + +## Usage + +See above + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`delta` | Number | `null` | A number to represent the percentage change since the last comparison period - positive numbers will show a green up arrow, negative numbers will show a red down arrow, and zero will show a flat right arrow. If omitted, no change value will display +`href` | String | `''` | An internal link to the report focused on this number +`isOpen` | Boolean | `false` | Boolean describing whether the menu list is open. Only applies in mobile view, and only applies to the toggle-able item (first in the list) +`label` | String | `null` | (required) A string description of this value, ex "Revenue", or "New Customers" +`onToggle` | Function | `null` | A function used to switch the given SummaryNumber to a button, and called on click +`prevLabel` | String | `__( 'Previous Period:', 'woocommerce-admin' )` | A string description of the previous value's timeframe, ex "Previous Year:" +`prevValue` | One of type: number, string | `null` | A string or number value to display - a string is allowed so we can accept currency formatting. If omitted, this section won't display +`reverseTrend` | Boolean | `false` | A boolean used to indicate that a negative delta is "good", and should be styled like a positive (and vice-versa) +`selected` | Boolean | `false` | A boolean used to show a highlight style on this number +`value` | One of type: number, string | `null` | A string or number value to display - a string is allowed so we can accept currency formatting +`onLinkClickCallback` | Function | `noop` | A function to be called after a SummaryNumber, rendered as a link, is clicked + + +SummaryListPlaceholder +=== + +`SummaryListPlaceholder` behaves like `SummaryList` but displays placeholder summary items instead of data. This can be used while loading data. + +## Usage + +```jsx + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`numberOfItems` | Number | `null` | (required) An integer with the number of summary items to display +`numberOfRows` | | `5` | diff --git a/plugins/woocommerce-admin/packages/components/src/summary/example.md b/plugins/woocommerce-admin/packages/components/src/summary/docs/example.js similarity index 87% rename from plugins/woocommerce-admin/packages/components/src/summary/example.md rename to plugins/woocommerce-admin/packages/components/src/summary/docs/example.js index af417e4270c..e0b30ed0a50 100644 --- a/plugins/woocommerce-admin/packages/components/src/summary/example.md +++ b/plugins/woocommerce-admin/packages/components/src/summary/docs/example.js @@ -1,7 +1,10 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { SummaryList, SummaryNumber } from '@woocommerce/components'; -const MySummaryList = () => ( +export default () => ( { () => { return [ @@ -25,9 +28,8 @@ const MySummaryList = () => ( value={ '$49.90' } label="Coupons" href="/analytics/report" - /> + />, ]; } } ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/table/README.md b/plugins/woocommerce-admin/packages/components/src/table/README.md new file mode 100644 index 00000000000..d35a9220ba1 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/table/README.md @@ -0,0 +1,251 @@ +TableCard +=== + +This is an accessible, sortable, and scrollable table for displaying tabular data (like revenue and other analytics data). +It accepts `headers` for column headers, and `rows` for the table content. +`rowHeader` can be used to define the index of the row header (or false if no header). + +`TableCard` serves as Card wrapper & contains a card header, `
`, ``, and ``. +This includes filtering and comparison functionality for report pages. + +## Usage + +```jsx +const headers = [ + { key: 'month', label: 'Month' }, + { key: 'orders', label: 'Orders' }, + { key: 'revenue', label: 'Revenue' }, +]; +const rows = [ + [ + { display: 'January', value: 1 }, + { display: 10, value: 10 }, + { display: '$530.00', value: 530 }, + ], + [ + { display: 'February', value: 2 }, + { display: 13, value: 13 }, + { display: '$675.00', value: 675 }, + ], + [ + { display: 'March', value: 3 }, + { display: 9, value: 9 }, + { display: '$460.00', value: 460 }, + ], +]; +const summary = [ + { label: 'Gross Income', value: '$830.00' }, + { label: 'Taxes', value: '$96.32' }, + { label: 'Shipping', value: '$50.00' }, +]; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`compareBy` | String | `null` | The string to use as a query parameter when comparing row items +`compareParam` | String | `'filter'` | Url query parameter compare function operates on +`headers` | Array | `null` | An array of column headers (see `Table` props) +`labels` | Object | `null` | Custom labels for table header actions +`ids` | Array | `null` | A list of IDs, matching to the row list so that ids[ 0 ] contains the object ID for the object displayed in row[ 0 ] +`isLoading` | Boolean | `false` | Defines if the table contents are loading. It will display `TablePlaceholder` component instead of `Table` if that's the case +`onQueryChange` | Function | `noop` | A function which returns a callback function to update the query string for a given `param` +`onColumnsChange` | Function | `noop` | A function which returns a callback function which is called upon the user changing the visiblity of columns +`onSearch` | Function | `noop` | A function which is called upon the user searching in the table header +`onSort` | Function | `undefined` | A function which is called upon the user changing the sorting of the table +`downloadable` | Boolean | `false` | Whether the table must be downloadable. If true, the download button will appear +`onClickDownload` | Function | `null` | A callback function called when the "download" button is pressed. Optional, if used, the download button will appear +`query` | Object | `{}` | An object of the query parameters passed to the page, ex `{ page: 2, per_page: 5 }` +`rowHeader` | One of type: number, bool | `0` | An array of arrays of display/value object pairs (see `Table` props) +`rows` | Array | `[]` | Which column should be the row header, defaults to the first item (`0`) (see `Table` props) +`rowsPerPage` | Number | `null` | (required) The total number of rows to display per page +`searchBy` | String | `null` | The string to use as a query parameter when searching row items +`showMenu` | Boolean | `true` | Boolean to determine whether or not ellipsis menu is shown +`summary` | Array | `null` | An array of objects with `label` & `value` properties, which display in a line under the table. Optional, can be left off to show no summary +`title` | String | `null` | (required) The title used in the card header, also used as the caption for the content in this table +`totalRows` | Number | `null` | (required) The total number of rows (across all pages) +`baseSearchQuery` | Object | `{}` | Pass in query parameters to be included in the path when onSearch creates a new url + +### `labels` structure + +Table header action labels object with properties: + +- `compareButton`: String - Compare button label +- `downloadButton`: String - Download button label +- `helpText`: String - +- `placeholder`: String - + +### `summary` structure + +Array of summary items objects with properties: + +- `label`: ReactNode +- `value`: One of type: string, number + + +EmptyTable +=== + +`EmptyTable` displays a blank space with an optional message passed as a children node +with the purpose of replacing a table with no rows. +It mimics the same height a table would have according to the `numberOfRows` prop. + +## Usage + +```jsx + + There are no entries. + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`numberOfRows` | Number | `5` | An integer with the number of rows the box should occupy + + +TablePlaceholder +=== + +`TablePlaceholder` behaves like `Table` but displays placeholder boxes instead of data. This can be used while loading. + +## Usage + +```jsx +const headers = [ + { key: 'month', label: 'Month' }, + { key: 'orders', label: 'Orders' }, + { key: 'revenue', label: 'Revenue' }, +]; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`query` | Object | `null` | An object of the query parameters passed to the page, ex `{ page: 2, per_page: 5 }` +`caption` | String | `null` | (required) A label for the content in this table +`headers` | Array | `null` | An array of column headers (see `Table` props) +`numberOfRows` | Number | `5` | An integer with the number of rows to display + + +TableSummary +=== + +A component to display summarized table data - the list of data passed in on a single line. + +## Usage + +```jsx +const summary = [ + { label: 'Gross Income', value: '$830.00' }, + { label: 'Taxes', value: '$96.32' }, + { label: 'Shipping', value: '$50.00' }, +]; + + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`data` | Array | `null` | An array of objects with `label` & `value` properties, which display on a single line + + +Table +=== + +A table component, without the Card wrapper. This is a basic table display, sortable, but no default filtering. + +Row data should be passed to the component as a list of arrays, where each array is a row in the table. +Headers are passed in separately as an array of objects with column-related properties. For example, +this data would render the following table. + +```js +const headers = [ { label: 'Month' }, { label: 'Orders' }, { label: 'Revenue' } ]; +const rows = [ + [ + { display: 'January', value: 1 }, + { display: 10, value: 10 }, + { display: '$530.00', value: 530 }, + ], + [ + { display: 'February', value: 2 }, + { display: 13, value: 13 }, + { display: '$675.00', value: 675 }, + ], + [ + { display: 'March', value: 3 }, + { display: 9, value: 9 }, + { display: '$460.00', value: 460 }, + ], +] +``` + +| Month | Orders | Revenue | +| ---------|--------|---------| +| January | 10 | $530.00 | +| February | 13 | $675.00 | +| March | 9 | $460.00 | + +## Usage + +```jsx +
+``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`ariaHidden` | Boolean | `false` | Controls whether this component is hidden from screen readers. Used by the loading state, before there is data to read. Don't use this on real tables unless the table data is loaded elsewhere on the page +`caption` | String | `null` | (required) A label for the content in this table +`className` | String | `null` | Additional CSS classes +`headers` | Array | `[]` | An array of column headers, as objects +`onSort` | Function | `noop` | A function called when sortable table headers are clicked, gets the `header.key` as argument +`query` | Object | `{}` | The query string represented in object form +`rows` | Array | `null` | (required) An array of arrays of display/value object pairs +`rowHeader` | One of type: number, bool | `0` | Which column should be the row header, defaults to the first item (`0`) (but could be set to `1`, if the first col is checkboxes, for example). Set to false to disable row headers + +### `headers` structure + +Array of column header objects with properties: + +- `defaultSort`: Boolean - Boolean, true if this column is the default for sorting. Only one column should have this set. +- `defaultOrder`: String - String, asc|desc if this column is the default for sorting. Only one column should have this set. +- `isLeftAligned`: Boolean - Boolean, true if this column should be aligned to the left. +- `isNumeric`: Boolean - Boolean, true if this column is a number value. +- `isSortable`: Boolean - Boolean, true if this column is sortable. +- `key`: String - The API parameter name for this column, passed to `orderby` when sorting via API. +- `label`: ReactNode - The display label for this column. +- `required`: Boolean - Boolean, true if this column should always display in the table (not shown in toggle-able list). +- `screenReaderLabel`: String - The label used for screen readers for this column. + +### `rows` structure + +Array of arrays representing rows and columns. Column object properties: + +- `display`: ReactNode - Display value, used for rendering - strings or elements are best here. +- `value`: One of type: string, number, bool \ No newline at end of file diff --git a/plugins/woocommerce-admin/packages/components/src/table/example.md b/plugins/woocommerce-admin/packages/components/src/table/docs/example.js similarity index 59% rename from plugins/woocommerce-admin/packages/components/src/table/example.md rename to plugins/woocommerce-admin/packages/components/src/table/docs/example.js index 164771e2604..d2473d0c1d0 100644 --- a/plugins/woocommerce-admin/packages/components/src/table/example.md +++ b/plugins/woocommerce-admin/packages/components/src/table/docs/example.js @@ -1,7 +1,23 @@ -```jsx -import { TableCard } from '@woocommerce/components'; +/** @format */ +/** + * Internal dependencies + */ +import { + Card, + EmptyTable, + H, + Section, + Table, + TableCard, + TablePlaceholder, + TableSummary, +} from '@woocommerce/components'; + +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; -const noop = () => {}; const headers = [ { key: 'month', label: 'Month' }, { key: 'orders', label: 'Orders' }, @@ -30,7 +46,11 @@ const summary = [ { label: 'Shipping', value: '$50.00' }, ]; -const MyTable = () => ( +export default withState( { + query: { + paged: 1, + }, +} )( ( { query, setState } ) => (
TableCard
@@ -38,8 +58,16 @@ const MyTable = () => ( title="Revenue Last Week" rows={ rows } headers={ headers } - onQueryChange={ noop } - query={ { page: 2 } } + onQueryChange={ + ( param ) => ( + ( value ) => setState( { + query: { + [ param ]: value, + }, + } ) + ) + } + query={ query } rowsPerPage={ 7 } totalRows={ 10 } summary={ summary } @@ -48,11 +76,13 @@ const MyTable = () => ( Table only
-
+ +
+ Summary only @@ -62,10 +92,12 @@ const MyTable = () => ( Placeholder
- + + +
Empty Table @@ -75,5 +107,4 @@ const MyTable = () => ( -); -``` +) ); diff --git a/plugins/woocommerce-admin/packages/components/src/tag/README.md b/plugins/woocommerce-admin/packages/components/src/tag/README.md new file mode 100644 index 00000000000..f8c11057bc5 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/tag/README.md @@ -0,0 +1,25 @@ +Tag +=== + +This component can be used to show an item styled as a "tag", optionally with an `X` + "remove" +or with a popover that is shown on click. + + + +## Usage + +```jsx + + +This is a popover

) } /> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`id` | One of type: number, string | `null` | The ID for this item, used in the remove function +`label` | String | `null` | (required) The name for this item, displayed as the tag's text +`popoverContents` | ReactNode | `null` | Contents to display on click in a popover +`remove` | Function | `null` | A function called when the remove X is clicked. If not used, no X icon will display +`screenReaderLabel` | String | `null` | A more descriptive label for screen reader users. Defaults to the `name` prop diff --git a/plugins/woocommerce-admin/packages/components/src/tag/example.md b/plugins/woocommerce-admin/packages/components/src/tag/docs/example.js similarity index 78% rename from plugins/woocommerce-admin/packages/components/src/tag/example.md rename to plugins/woocommerce-admin/packages/components/src/tag/docs/example.js index 7f3843c92f5..4dcc85a842d 100644 --- a/plugins/woocommerce-admin/packages/components/src/tag/example.md +++ b/plugins/woocommerce-admin/packages/components/src/tag/docs/example.js @@ -1,13 +1,15 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { Tag } from '@woocommerce/components'; const noop = () => {}; -const MyTag = () => ( +export default () => (
This is a popover

) } />
); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/README.md b/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/README.md new file mode 100644 index 00000000000..19b92cd032c --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/README.md @@ -0,0 +1,37 @@ +TextControlWithAffixes +=== + +This component is essentially a wrapper (really a reimplementation) around the +TextControl component that adds support for affixes, i.e. the ability to display +a fixed part either at the beginning or at the end of the text input. + +## Usage + +```jsx + setState( { fourth: value } ) } +/> + setState( { fifth: value } ) } + help="This is some help text." +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`label` | String | `null` | If this property is added, a label will be generated using label property as the content +`help` | String | `null` | If this property is added, a help text will be generated using help property as the content +`type` | String | `'text'` | Type of the input element to render. Defaults to "text" +`value` | String | `null` | (required) The current value of the input +`className` | String | `null` | The class that will be added with "components-base-control" to the classes of the wrapper div. If no className is passed only components-base-control is used +`onChange` | Function | `null` | (required) A function that receives the value of the input +`prefix` | ReactNode | `null` | Markup to be inserted at the beginning of the input +`suffix` | ReactNode | `null` | Markup to be appended at the end of the input diff --git a/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/example.md b/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/docs/example.js similarity index 87% rename from plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/example.md rename to plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/docs/example.js index 1bc6e5c75de..d9444d847d3 100644 --- a/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/example.md +++ b/plugins/woocommerce-admin/packages/components/src/text-control-with-affixes/docs/example.js @@ -1,7 +1,15 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { TextControlWithAffixes } from '@woocommerce/components'; -const MyTextControlWithAffixes = withState( { +/** + * External dependencies + */ +import { withState } from '@wordpress/compose'; + +export default withState( { first: '', second: '', third: '', @@ -43,4 +51,3 @@ const MyTextControlWithAffixes = withState( { /> ) ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/view-more-list/README.md b/plugins/woocommerce-admin/packages/components/src/view-more-list/README.md new file mode 100644 index 00000000000..e5753fd95be --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/view-more-list/README.md @@ -0,0 +1,20 @@ +ViewMoreList +=== + +This component displays a 'X more' button that displays a list of items on a popover when clicked. + + + +## Usage + +```jsx +Lorem, Ipsum, Dolor, Sit ] } +/> +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`items` | Array | `[]` | `ReactNodes` to list in the popover diff --git a/plugins/woocommerce-admin/packages/components/src/view-more-list/example.md b/plugins/woocommerce-admin/packages/components/src/view-more-list/docs/example.js similarity index 67% rename from plugins/woocommerce-admin/packages/components/src/view-more-list/example.md rename to plugins/woocommerce-admin/packages/components/src/view-more-list/docs/example.js index 7b35758c58a..8016816b4ca 100644 --- a/plugins/woocommerce-admin/packages/components/src/view-more-list/example.md +++ b/plugins/woocommerce-admin/packages/components/src/view-more-list/docs/example.js @@ -1,9 +1,11 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { ViewMoreList } from '@woocommerce/components'; -const MyViewMoreList = () => ( +export default () => ( Lorem, Ipsum, Dolor, Sit ] } /> ); -``` diff --git a/plugins/woocommerce-admin/packages/components/src/web-preview/README.md b/plugins/woocommerce-admin/packages/components/src/web-preview/README.md new file mode 100644 index 00000000000..4b094258548 --- /dev/null +++ b/plugins/woocommerce-admin/packages/components/src/web-preview/README.md @@ -0,0 +1,23 @@ +WebPreview +=== + +WebPreview component to display an iframe of another page. + +## Usage + +```jsx + +``` + +### Props + +Name | Type | Default | Description +--- | --- | --- | --- +`className` | String | `null` | Additional class name to style the component +`loadingContent` | ReactNode | `` | Content shown when iframe is still loading +`onLoad` | Function | `noop` | Function to fire when iframe content is loaded +`src` | String | `null` | (required) Iframe src to load +`title` | String | `null` | (required) Iframe title diff --git a/plugins/woocommerce-admin/packages/components/src/web-preview/example.md b/plugins/woocommerce-admin/packages/components/src/web-preview/docs/example.js similarity index 69% rename from plugins/woocommerce-admin/packages/components/src/web-preview/example.md rename to plugins/woocommerce-admin/packages/components/src/web-preview/docs/example.js index ee748472d8e..f0765167371 100644 --- a/plugins/woocommerce-admin/packages/components/src/web-preview/example.md +++ b/plugins/woocommerce-admin/packages/components/src/web-preview/docs/example.js @@ -1,9 +1,11 @@ -```jsx +/** @format */ +/** + * Internal dependencies + */ import { WebPreview } from '@woocommerce/components'; -const MyWebPreview = () => ( +export default () => (
); -```