From 02e880cad8925a0882d9beb7f20a8a255c232589 Mon Sep 17 00:00:00 2001 From: geido Date: Wed, 20 Oct 2021 15:19:21 +0000 Subject: [PATCH 1/3] Add docs --- .../src/components/Select/Select.stories.tsx | 49 +++++++++++---- .../src/components/Select/Select.tsx | 63 +++++++++++++++++++ 2 files changed, 100 insertions(+), 12 deletions(-) diff --git a/superset-frontend/src/components/Select/Select.stories.tsx b/superset-frontend/src/components/Select/Select.stories.tsx index 938cc040cad53..a86e769fbccdc 100644 --- a/superset-frontend/src/components/Select/Select.stories.tsx +++ b/superset-frontend/src/components/Select/Select.stories.tsx @@ -75,14 +75,15 @@ const selectPositions = [ const ARG_TYPES = { options: { defaultValue: options, - table: { - disable: true, - }, + description: `It defines the options of the Select. + The options can be static, an array of options. + The options can also be async, a promise that returns an array of options. + `, }, ariaLabel: { - table: { - disable: true, - }, + description: `It adds the aria-label tag for accessibility standards. + Must be plain English and localized. + `, }, labelInValue: { defaultValue: true, @@ -101,12 +102,34 @@ const ARG_TYPES = { }, }, mode: { + description: `It defines whether the Select should allow for + the selection of multiple options or single. Single by default. + `, defaultValue: 'single', control: { type: 'inline-radio', options: ['single', 'multiple'], }, }, + allowNewOptions: { + description: `It enables the user to create new options. + Can be used with standard or async select types. + Can be used with any mode, single or multiple. False by default. + `, + }, + invertSelection: { + description: `It shows a stop-outlined icon at the far right of a selected + option instead of the default checkmark. + Useful to better indicate to the user that by clicking on a selected + option it will be de-selected. False by default. + `, + }, + optionFilterProps: { + description: `It allows to define which properties of the option object + should be looked for when searching. + By default label and value. + `, + }, }; const mountHeader = (type: String) => { @@ -149,17 +172,19 @@ InteractiveSelect.argTypes = { ...ARG_TYPES, header: { defaultValue: 'none', + description: `It adds a header on top of the Select. Can be any ReactNode.`, control: { type: 'inline-radio', options: ['none', 'text', 'control'] }, }, pageSize: { - table: { - disable: true, - }, + description: `It defines how many results should be included in the query response. + Works in async mode only (See the options property). + `, }, fetchOnlyOnSearch: { - table: { - disable: true, - }, + description: `It fires a request against the server only after searching. + Works in async mode only (See the options property). + Undefined by default. + `, }, }; diff --git a/superset-frontend/src/components/Select/Select.tsx b/superset-frontend/src/components/Select/Select.tsx index 1578562875ecd..aeb1cf0dba259 100644 --- a/superset-frontend/src/components/Select/Select.tsx +++ b/superset-frontend/src/components/Select/Select.tsx @@ -82,17 +82,80 @@ export type OptionsPagePromise = ( ) => Promise; export interface SelectProps extends PickedSelectProps { + /** + * It enables the user to create new options. + * Can be used with standard or async select types. + * Can be used with any mode, single or multiple. + * False by default. + * */ allowNewOptions?: boolean; + /** + * It adds the aria-label tag for accessibility standards. + * Must be plain English and localized. + */ ariaLabel: string; + /** + * It adds a header on top of the Select. + * Can be any ReactNode. + */ header?: ReactNode; + /** + * It fires a request against the server after + * the first interaction and not on render. + * Works in async mode only (See the options property). + * True by default. + */ lazyLoading?: boolean; + /** + * It defines whether the Select should allow for the + * selection of multiple options or single. + * Single by default. + */ mode?: 'single' | 'multiple'; + /** + * Deprecated. + * Prefer ariaLabel instead. + */ name?: string; // discourage usage + /** + * It allows to define which properties of the option object + * should be looked for when searching. + * By default label and value. + */ optionFilterProps?: string[]; + /** + * It defines the options of the Select. + * The options can be static, an array of options. + * The options can also be async, a promise that returns + * an array of options. + */ options: OptionsType | OptionsPagePromise; + /** + * It defines how many results should be included + * in the query response. + * Works in async mode only (See the options property). + */ pageSize?: number; + /** + * It shows a stop-outlined icon at the far right of a selected + * option instead of the default checkmark. + * Useful to better indicate to the user that by clicking on a selected + * option it will be de-selected. + * False by default. + */ invertSelection?: boolean; + /** + * It fires a request against the server only after + * searching. + * Works in async mode only (See the options property). + * Undefined by default. + */ fetchOnlyOnSearch?: boolean; + /** + * It provides a callback function when an error + * is generated after a request is fired. + * Works in async mode only (See the options property). + */ onError?: (error: string) => void; } From a0b36d20d637e622084ebd66c37000a357ada59c Mon Sep 17 00:00:00 2001 From: geido Date: Mon, 25 Oct 2021 12:44:04 +0000 Subject: [PATCH 2/3] Add overall description --- superset-frontend/src/components/Select/Select.tsx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/superset-frontend/src/components/Select/Select.tsx b/superset-frontend/src/components/Select/Select.tsx index aeb1cf0dba259..ed3cadfdf0836 100644 --- a/superset-frontend/src/components/Select/Select.tsx +++ b/superset-frontend/src/components/Select/Select.tsx @@ -231,6 +231,20 @@ const Error = ({ error }: { error: string }) => ( ); +/** + * This component is a customized version of the Antdesign 4.X Select component + * https://ant.design/components/select/. + * The aim of the component was to combine all the instances of select components throughout the + * project under one and to remove the react-select component entirely. + * This Select component provides an API that is tested against all the different use cases of Superset. + * It limits and overrides the existing Antdesign API in order to keep their usage to the minimum + * and to enforce simplification and standardization. + * It is divided into two macro categories, Static and Async. + * The Static type accepts a static array of options. + * The Async type accepts a promise that will return the options. + * Each of the categories come with different abilities. For a comprehensive guide please refer to + * the storybook in src/components/Select/Select.stories.tsx. + */ const Select = ({ allowNewOptions = false, ariaLabel, From 61a58c431535bbdb1b77489af4a3e47f9442103d Mon Sep 17 00:00:00 2001 From: geido Date: Mon, 25 Oct 2021 19:20:04 +0000 Subject: [PATCH 3/3] Remove trailing space --- superset-frontend/src/components/Select/Select.stories.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/superset-frontend/src/components/Select/Select.stories.tsx b/superset-frontend/src/components/Select/Select.stories.tsx index 67e60163668a3..d64eb78a4c3ad 100644 --- a/superset-frontend/src/components/Select/Select.stories.tsx +++ b/superset-frontend/src/components/Select/Select.stories.tsx @@ -112,7 +112,7 @@ const ARG_TYPES = { }, }, allowNewOptions: { - description: `It enables the user to create new options. + description: `It enables the user to create new options. Can be used with standard or async select types. Can be used with any mode, single or multiple. False by default. `,