From 76bf741fc950e7d9507ff563e0f01016668dd05e Mon Sep 17 00:00:00 2001
From: Paul Sealock <psealock@gmail.com>
Date: Thu, 20 Sep 2018 17:07:37 +1200
Subject: [PATCH] Advanced Filters: update README

---
 .../components/filters/advanced/README.md     | 144 +++++++++++-------
 1 file changed, 88 insertions(+), 56 deletions(-)

diff --git a/plugins/woocommerce-admin/client/components/filters/advanced/README.md b/plugins/woocommerce-admin/client/components/filters/advanced/README.md
index 69fbd338422..e629bd15c7d 100644
--- a/plugins/woocommerce-admin/client/components/filters/advanced/README.md
+++ b/plugins/woocommerce-admin/client/components/filters/advanced/README.md
@@ -1,73 +1,105 @@
 Advanced Filters
 ============
 
-Displays a configurable set of filters which can modify query parameters.
+Displays a configurable set of filters which can modify query parameters. Display, behavior, and types of filters can be designated by a configuration object.
 
-## How to use:
+## Example Config
+
+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
-import AdvancedFilters from 'components/advanced-filters';
-
-filters = {
-	status: {
-		label: __( 'Order Status', 'wc-admin' ),
-		addLabel: __( 'Order Status', 'wc-admin' ),
-		rules: [
-			{ value: 'is', label: __( 'Is', 'wc-admin' ) },
-			{ value: 'is-not', label: __( 'Is Not', 'wc-admin' ) },
-		],
-		input: {
-			component: 'SelectControl',
-			options: [
-				{ value: 'pending', label: __( 'Pending', 'wc-admin' ) },
-				{ value: 'processing', label: __( 'Processing', 'wc-admin' ) },
-				{ value: 'on-hold', label: __( 'On Hold', 'wc-admin' ) },
+const config = {
+	title: _x(
+		'Orders Match {{select /}} Filters',
+		'A sentence describing filters for Orders. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ',
+		'wc-admin'
+	),
+	filters: {
+		status: {
+			labels: {
+				add: __( 'Order Status', 'wc-admin' ),
+				remove: __( 'Remove order status filter', 'wc-admin' ),
+				rule: __( 'Select an order status filter match', 'wc-admin' ),
+				/* translators: A sentence describing an Order Status filter. See screen shot for context: https://cloudup.com/cSsUY9VeCVJ */
+				title: __( 'Order Status {{rule /}} {{filter /}}', 'wc-admin' ),
+				filter: __( 'Select an order status', 'wc-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 */
+					label: _x( 'Is', 'order status', 'wc-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 */
+					label: _x( 'Is Not', 'order status', 'wc-admin' ),
+				},
 			],
+			input: {
+				component: 'SelectControl',
+				options: Object.keys( orderStatuses ).map( key => ( {
+					value: key,
+					label: orderStatuses[ key ],
+				} ) ),
+			},
 		},
 	},
-	product: {
-		label: __( 'Product', 'wc-admin' ),
-		addLabel: __( 'Products', 'wc-admin' ),
-		rules: [
-			{ value: 'includes', label: __( 'Includes', 'wc-admin' ) },
-			{ value: 'excludes', label: __( 'Excludes', 'wc-admin' ) },
-			{ value: 'is', label: __( 'Is', 'wc-admin' ) },
-			{ value: 'is-not', label: __( 'Is Not', 'wc-admin' ) },
-		],
-		input: {
-			component: 'FormTokenField',
-		},
-	},
-};
+  };
+```
 
-render: function() {
-  return (
-    <AdvancedFilters config={ filters } />
-  );
+## 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' },
+	],
 }
 ```
 
+`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,
+	} ) ),
+}
+```
+
+`type`: A string Autocompleter type used by the [Search Component](https://github.com/woocommerce/wc-admin/tree/master/client/components/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.
+
+### Numerical Value
+under development.
+
+### Numerical Range
+under development.
+
 ## AdvancedFilters Props
 
 * `config` (required): The configuration object required to render filters
-* `filterTitle` (required): Name of this filter, used in translations
 * `path` (required): The `path` parameter supplied by React-Router
-* `query`: The query string represented in object form
-
-## config object jsDoc
-
-```js
-/**
- * @type filterConfig {{
- * 	key: {
- * 		label: {string},
- * 		addLabel: {string},
- * 		rules: [{{ value:{string}, label:{string} }}],
- * 		input: {
- * 			component: {string},
- * 			[options]: [*]
- * 		},
- * 	}
- * }}
- */
-```
+* `query`: The url query string represented in object form