From fa6a43c6e592a1b077ffb63143cb3cf090fe5a15 Mon Sep 17 00:00:00 2001
From: Tobias Skarhed <1438972+tskarhed@users.noreply.github.com>
Date: Wed, 15 Apr 2020 10:11:25 +0200
Subject: [PATCH] Docs: Select (#23398)

* Start Select docs

* Writ emore docs

* Apply suggestions from code review

Co-Authored-By: Alex Khomenko <Clarity-89@users.noreply.github.com>

Co-authored-by: Alex Khomenko <Clarity-89@users.noreply.github.com>
---
 .../src/components/Select/Select.mdx          | 133 ++++++++++++++++++
 .../src/components/Select/Select.story.tsx    |   7 +
 .../src/components/Select/mockOptions.tsx     |   3 +-
 .../grafana-ui/src/components/Select/types.ts |   6 +
 4 files changed, 148 insertions(+), 1 deletion(-)
 create mode 100644 packages/grafana-ui/src/components/Select/Select.mdx

diff --git a/packages/grafana-ui/src/components/Select/Select.mdx b/packages/grafana-ui/src/components/Select/Select.mdx
new file mode 100644
index 00000000000..5ca57e225c5
--- /dev/null
+++ b/packages/grafana-ui/src/components/Select/Select.mdx
@@ -0,0 +1,133 @@
+import { Props, Preview } from "@storybook/addon-docs/blocks";
+import { Select, AsyncSelect, MultiSelect, AsyncMultiSelect } from "./Select";
+import { generateOptions } from "./mockOptions";
+
+# Select variants
+
+Select is an input with the ability to search and create new values. It should be used when you have a list of options. If the data has a tree structure, consider using `Cascader` instead.
+Select has some features:
+
+- Search a list of values
+- Select multiple values
+- Select from async data
+- Create custom values that aren't in the list
+
+## Select
+
+Select is the base for every component on this page. The approaches mentioned here are also applicable to `AsyncSelect`, `MultiSelect`, `AsyncMultiSelect`.
+
+### Options format
+
+There are four properties for each option:
+
+- `label` - Text that is visible in the menu.
+- `value` - Could be anything, but is usually a string. Used to identify what is **actually** selected.
+- `description` - Longer description that describes the choice. Use this sparingly.
+- `imgUrl` - URL to an image. Use this when an image or icon provides more context for the option.
+
+```jsx
+const options = [
+  { label: "Basic option", value: 0 },
+  { label: "Option with description", value: 1, description: "this is a description" },
+  {
+    label: "Option with description and image",
+    value: 2,
+    description: "This is a very elaborate description, describing all the wonders in the world.",
+    imgUrl: "https://placekitten.com/40/40",
+  },
+];
+```
+
+### Creatable option
+
+Creatable option is used when you want to be able to add a custom value to the list of options. `allowCustomValue` needs to be true and you must handle the value creation with `onCreateOption`.
+
+```jsx
+import { Select } from "@grafana/ui";
+
+const SelectComponent = () => {
+  const [value, setValue] = useState<SelectableValue<number>>();
+
+  return (
+    <Select
+      options={option}
+      value={value}
+      allowCustomValue
+      onCreateOption={customValue => {
+        setValue(customValue);
+      }}
+    />
+  );
+};
+```
+
+## AsyncSelect
+
+Like regular Select, but handles fetching options asynchronously. Use the `loadOptions` prop for the async function that loads the options. If `defaultOptions` is set to `true`, `loadOptions` will be called when the component is mounted.
+
+```jsx
+
+import { AsyncSelect } from '@grafana/ui';
+
+const basicSelectAsync = () => {
+  const [value, setValue] = useState<SelectableValue<string>>();
+
+  return (
+    <AsyncSelect
+      loadOptions={loadAsyncOptions}
+      defaultOptions
+      value={value}
+      onChange={v => {
+        setValue(v);
+      }}
+      size="md"
+    />
+  );
+};
+
+```
+
+Where the async function could look like this:
+
+```tsx
+const loadAsyncOptions = () => {
+  return new Promise()<Array<SelectableValue<string>>>(resolve => {
+    setTimeout(() => {
+      resolve(options);
+    }, 2000);
+  });
+};
+```
+
+## MultiSelect
+
+Possible to Select multiple values at the same time.
+
+```tsx
+import { MultiSelect } from "@grafana/ui";
+
+const multiSelect = () => {
+  const [value, setValue] = useState<Array<SelectableValue<string>>>([]);
+
+  return (
+    <>
+      <MultiSelect
+        options={options}
+        value={value}
+        onChange={v => {
+          setValue(v);
+        }}
+        size="md"
+      />
+    </>
+  );
+};
+```
+
+## AsyncMultiSelect
+
+Like MultiSelect but handles data asynchronously with the `loadOptions` prop.
+
+## Props
+
+<Props of={Select} />
diff --git a/packages/grafana-ui/src/components/Select/Select.story.tsx b/packages/grafana-ui/src/components/Select/Select.story.tsx
index 18b5d943f32..4dcf2f1027a 100644
--- a/packages/grafana-ui/src/components/Select/Select.story.tsx
+++ b/packages/grafana-ui/src/components/Select/Select.story.tsx
@@ -10,11 +10,18 @@ import { ButtonSelect } from './ButtonSelect';
 import { getIconKnob } from '../../utils/storybook/knobs';
 import kebabCase from 'lodash/kebabCase';
 import { generateOptions } from './mockOptions';
+import mdx from './Select.mdx';
 
 export default {
   title: 'Forms/Select',
   component: Select,
   decorators: [withCenteredStory, withHorizontallyCenteredStory],
+  subcomponents: { AsyncSelect, MultiSelect, AsyncMultiSelect },
+  parameters: {
+    docs: {
+      page: mdx,
+    },
+  },
 };
 
 const loadAsyncOptions = () => {
diff --git a/packages/grafana-ui/src/components/Select/mockOptions.tsx b/packages/grafana-ui/src/components/Select/mockOptions.tsx
index e4d181fb18b..1d03878048e 100644
--- a/packages/grafana-ui/src/components/Select/mockOptions.tsx
+++ b/packages/grafana-ui/src/components/Select/mockOptions.tsx
@@ -1,7 +1,7 @@
 import { SelectableValue } from '@grafana/data';
 import { kebabCase } from 'lodash';
 
-export const generateOptions = () => {
+export const generateOptions = (desc = false) => {
   const values = [
     'Sharilyn Markowitz',
     'Naomi Striplin',
@@ -28,5 +28,6 @@ export const generateOptions = () => {
   return values.map<SelectableValue<string>>(name => ({
     value: kebabCase(name),
     label: name,
+    description: desc ? `This is a description of ${name}` : undefined,
   }));
 };
diff --git a/packages/grafana-ui/src/components/Select/types.ts b/packages/grafana-ui/src/components/Select/types.ts
index 0e0267ed9af..f936d98037b 100644
--- a/packages/grafana-ui/src/components/Select/types.ts
+++ b/packages/grafana-ui/src/components/Select/types.ts
@@ -6,12 +6,15 @@ export type SelectValue<T> = T | SelectableValue<T> | T[] | Array<SelectableValu
 
 export interface SelectCommonProps<T> {
   allowCustomValue?: boolean;
+  /** Focus is set to the Select when rendered*/
   autoFocus?: boolean;
   backspaceRemovesValue?: boolean;
   className?: string;
+  /** Used for custom components. For more information, see `react-select` */
   components?: any;
   defaultValue?: any;
   disabled?: boolean;
+  /**   Function for formatting the text that is displayed when creating a new value*/
   formatCreateLabel?: (input: string) => string;
   getOptionLabel?: (item: SelectableValue<T>) => string;
   getOptionValue?: (item: SelectableValue<T>) => string;
@@ -20,14 +23,17 @@ export interface SelectCommonProps<T> {
   isLoading?: boolean;
   isMulti?: boolean;
   isOpen?: boolean;
+  /** Disables the possibility to type into the input*/
   isSearchable?: boolean;
   maxMenuHeight?: number;
   menuPlacement?: 'auto' | 'bottom' | 'top';
   menuPosition?: 'fixed' | 'absolute';
+  /** The message to display when no options could be found */
   noOptionsMessage?: string;
   onBlur?: () => void;
   onChange: (value: SelectableValue<T>) => {} | void;
   onCloseMenu?: () => void;
+  /** allowCustomValue must be enabled. Function decides what to do with that custom value. */
   onCreateOption?: (value: string) => void;
   onInputChange?: (label: string) => void;
   onKeyDown?: (event: React.KeyboardEvent) => void;