@salutejs/plasma-new-hope 0.141.0-canary.1422.10721189833.0 → 0.141.0-canary.1422.10737462879.0

package/emotion/es/components/Combobox/Combobox.template-doc.mdx

@@ -0,0 +1,344 @@
+---
+id: combobox
+title: Combobox
+---
+
+import { PropsTable, Description, StorybookLink } from '@site/src/components';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Combobox
+
+<Description name="Combobox" />
+<PropsTable name="Combobox" />
+
+## Использование
+Обязательным параметром является только `items`. Внутри items может быть такой же вложенный массив items. Формат следующий:
+
+```tsx
+type Items = Array<{
+        /**
+         *  Значение у item
+         */
+        value: string;
+        /**
+         * Метка-подпись к item
+         */
+        label: string;
+        /**
+         * Список дочерних items.
+         */
+        items?: Array<ItemOption>;
+        /**
+         * Item не активен
+         */
+        disabled?: boolean;
+        /**
+         * Слот для контента слева
+         */
+        contentLeft?: ReactNode;
+        /**
+         * Слот для контента справа
+         */
+        contentRight?: ReactNode;
+    }>;
+```
+
+Тип выбора комбобокса - одиночный или множественный зависит от типа `value` и `onChange`. В одиночном value - `string`, в множественном - `Array<string>`.\
+
+
+## Примеры
+
+<Tabs>
+    <TabItem value="single" label="Single" default>
+        ```tsx live
+        import React from 'react';
+        import { Combobox } from '@salutejs/{{ package }}';
+
+        export function App() {
+            const [value, setValue] = useState('');
+
+            const items = [
+                {
+                    value: 'north_america',
+                    label: 'Северная Америка',
+                },
+                {
+                    value: 'south_america',
+                    label: 'Южная Америка',
+                    items: [
+                        {
+                            value: 'brazil',
+                            label: 'Бразилия',
+                        },
+                        {
+                            value: 'argentina',
+                            label: 'Аргентина',
+                        },
+                    ],
+                },
+            ];
+
+            return (
+                <div style=\{{ display: 'flex', gap: '30px', height: '300px' }}>
+                    <div style=\{{width: '300px'}}>
+                        <Combobox
+                            items={items}
+                            value={value}
+                            onChange={setValue}
+                            placeholder="Placeholder"
+                            label="Label"
+                            helperText="Helper text"
+                        />
+                    </div>
+                </div>
+            );
+        }
+        ```
+    </TabItem>
+    <TabItem value="multiple" label="Multiple">
+        ```tsx live
+        import React from 'react';
+        import { Combobox } from '@salutejs/{{ package }}';
+
+        export function App() {
+            const [value, setValue] = useState([]);
+
+            const items = [
+                {
+                    value: 'north_america',
+                    label: 'Северная Америка',
+                },
+                {
+                    value: 'south_america',
+                    label: 'Южная Америка',
+                    items: [
+                        {
+                            value: 'brazil',
+                            label: 'Бразилия',
+                        },
+                        {
+                            value: 'argentina',
+                            label: 'Аргентина',
+                        },
+                    ],
+                },
+            ];
+
+            return (
+                <div style=\{{ display: 'flex', gap: '30px', height: '300px' }}>
+                    <div style=\{{width: '300px'}}>
+                        <Combobox
+                            multiple
+                            items={items}
+                            value={value}
+                            onChange={setValue}
+                            placeholder="Placeholder"
+                            label="Label"
+                            helperText="Helper text"
+                        />
+                    </div>
+                </div>
+            );
+        }
+        ```
+    </TabItem>
+    <TabItem value="predefined" label="Predefined">
+        Есть возможность задать значения по дефолту (главное, чтобы они находились в `items`). Также можно управлять состоянием снаружи селекта.
+
+        ```tsx live
+        import React from 'react';
+        import { Combobox, Button } from '@salutejs/{{ package }}';
+
+        export function App() {
+            const [multipleValue, setMultipleValue] = useState(['brazil', 'north_america']);
+
+            const items = [
+                {
+                    value: 'north_america',
+                    label: 'Северная Америка',
+                },
+                {
+                    value: 'south_america',
+                    label: 'Южная Америка',
+                    items: [
+                        {
+                            value: 'brazil',
+                            label: 'Бразилия',
+                        },
+                        {
+                            value: 'argentina',
+                            label: 'Аргентина',
+                        },
+                    ],
+                },
+            ];
+
+            return (
+                <div style=\{{ display: 'flex', gap: '30px', height: '300px' }}>
+                    <div style=\{{width: '300px'}}>
+                        <Combobox
+                            multiple
+                            items={items}
+                            value={multipleValue}
+                            onChange={setMultipleValue}
+                            placeholder="Placeholder"
+                            label="Label"
+                            helperText="Helper text"
+                        />
+                    </div>
+
+                    <Button onClick={() => setMultipleValue([])}>Очистить</Button>
+                </div>
+            );
+        }
+        ```
+    </TabItem>
+    <TabItem value="portal" label="Portal">
+        Иногда возникает необходимость вынесения выпадающего списка на уровни выше в DOM. К примеру, когда у родительского блока имеется скролл, и список будет обрезаться, чего хотелось бы избежать.\
+        Для такой реализации имеется пропс `portal`, который принимает либо `ref` либо `id` html-тега.\
+        Также нужно прокинуть проп `listWidth`, чтобы явно задать ширину списку. Если этого не сделать, то будет взята ширина 100% от блока, на который ведет ссылка портала.
+
+        ```tsx live
+        import React, { useRef } from 'react';
+        import { Combobox } from '@salutejs/{{ package }}';
+
+        export function App() {
+            const [value, setValue] = useState('');
+
+            const items = [
+                {
+                    value: 'north_america',
+                    label: 'Северная Америка',
+                },
+                {
+                    value: 'south_america',
+                    label: 'Южная Америка',
+                    items: [
+                        {
+                            value: 'brazil',
+                            label: 'Бразилия',
+                        },
+                        {
+                            value: 'argentina',
+                            label: 'Аргентина',
+                        },
+                    ],
+                },
+            ];
+
+            const ref = useRef(null)
+
+            return (
+                <div style=\{{ height: '300px' }} ref={ref}>
+                    <div style=\{{width: '300px'}}>
+                        <Combobox
+                            items={items}
+                            value={value}
+                            onChange={setValue}
+                            placeholder="Placeholder"
+                            label="Label"
+                            helperText="Helper text"
+                            portal={ref}
+                            listWidth="300px"
+                        />
+                    </div>
+                </div>
+            );
+        }
+        ```
+    </TabItem>
+    <TabItem value="uncontrolled" label="Uncontrolled">
+        `value` и `onChange` - опциональные параметры. Если вы хотите `uncontrolled` вариант компонента - их пробрасывать необязательно.
+
+       ```tsx live
+        import React from 'react';
+        import { Combobox } from '@salutejs/{{ package }}';
+
+        export function App() {
+            const items = [
+                {
+                    value: 'north_america',
+                    label: 'Северная Америка',
+                },
+                {
+                    value: 'south_america',
+                    label: 'Южная Америка',
+                    items: [
+                        {
+                            value: 'brazil',
+                            label: 'Бразилия',
+                        },
+                        {
+                            value: 'argentina',
+                            label: 'Аргентина',
+                        },
+                    ],
+                },
+            ];
+
+            return (
+                <div style=\{{ height: '300px' }}>
+                    <div style=\{{width: '300px'}}>
+                        <Combobox
+                            items={items}
+                            placeholder="Placeholder"
+                            label="Label"
+                            helperText="Helper text"
+                        />
+                    </div>
+                </div>
+            );
+        }
+        ```
+    </TabItem>
+    <TabItem value="alwaysOpened" label="Always opened">
+        Свойство alwaysOpened позволяет отображать Combobox всегда открытым. При этом closeAfterSelect игнорируется.
+
+       ```tsx live
+        import React from 'react';
+        import { Combobox } from '@salutejs/{{ package }}';
+
+        export function App() {
+            const items = [
+                {
+                    value: 'north_america',
+                    label: 'Северная Америка',
+                },
+                {
+                    value: 'south_america',
+                    label: 'Южная Америка',
+                    items: [
+                        {
+                            value: 'brazil',
+                            label: 'Бразилия',
+                        },
+                        {
+                            value: 'argentina',
+                            label: 'Аргентина',
+                        },
+                    ],
+                },
+            ];
+
+            return (
+                <div style=\{{ height: '300px' }}>
+                    <div style=\{{width: '300px'}}>
+                        <Combobox
+                            items={items}
+                            placeholder="Placeholder"
+                            label="Label"
+                            helperText="Helper text"
+                            alwaysOpened
+                        />
+                    </div>
+                </div>
+            );
+        }
+        ```
+    </TabItem>
+</Tabs>
+
+## Клавиатурная навигация
+
+Данный компонент соответствует требования W3C: [Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) и частично [TreeView](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).