From b5f8772bde21b95dbfb3fc5fd7777c7ba052c26c Mon Sep 17 00:00:00 2001
From: Alexandr Isaev <aisaev188@yandex-team.ru>
Date: Wed, 10 Jan 2024 12:41:25 +0300
Subject: [PATCH] feat: add simple examples in doc, fix some review issues

---
 src/components/TreeSelect/TreeSelect.scss     |   6 +
 src/components/TreeSelect/TreeSelect.tsx      |  24 +++-
 .../__stories__/TreeSelect.stories.tsx        |   1 -
 .../WithFiltrationAndControlsExample.tsx      |  32 ++---
 src/components/TreeSelect/types.ts            |   2 +
 .../__stories__/components/FlattenList.tsx    |   2 +-
 .../components/PopupWithTogglerList.tsx       |   2 +-
 .../__stories__/components/RecursiveList.tsx  |   2 +-
 .../useList/__stories__/useList.mdx           | 109 +++++++++++++++++-
 .../components/ListItemView/ListItemView.tsx  |   8 +-
 .../__stories__/ListItemView.stories.tsx      |  50 ++++++--
 src/components/useList/types.ts               |   2 +-
 12 files changed, 199 insertions(+), 41 deletions(-)

diff --git a/src/components/TreeSelect/TreeSelect.scss b/src/components/TreeSelect/TreeSelect.scss
index a12d97fa41..ad7cf33af3 100644
--- a/src/components/TreeSelect/TreeSelect.scss
+++ b/src/components/TreeSelect/TreeSelect.scss
@@ -3,6 +3,12 @@
 $block: '.#{variables.$ns}tree-select';
 
 #{$block} {
+    max-width: 100%;
+
+    &_width_max {
+        width: 100%;
+    }
+
     &__popup {
         overflow: hidden;
         min-width: 300px;
diff --git a/src/components/TreeSelect/TreeSelect.tsx b/src/components/TreeSelect/TreeSelect.tsx
index aa7c34bef8..b785583774 100644
--- a/src/components/TreeSelect/TreeSelect.tsx
+++ b/src/components/TreeSelect/TreeSelect.tsx
@@ -16,7 +16,7 @@ import {
     useListKeydown,
     useListState,
 } from '../useList';
-import {block} from '../utils/cn';
+import {type CnMods, block} from '../utils/cn';
 
 import {TreeListContainer} from './components/TreeListContainer/TreeListContainer';
 import {useTreeSelectSelection, useValue} from './hooks/useTreeSelectSelection';
@@ -37,6 +37,8 @@ export const TreeSelect = React.forwardRef(function TreeSelect<T>(
         size = 'm',
         items,
         defaultOpen,
+        className,
+        width,
         popupClassName,
         open: propsOpen,
         multiple,
@@ -224,8 +226,24 @@ export const TreeSelect = React.forwardRef(function TreeSelect<T>(
         />
     );
 
+    const mods: CnMods = {
+        ...(width === 'max' && {width}),
+    };
+
+    const inlineStyles: React.CSSProperties = {};
+
+    if (typeof width === 'number') {
+        inlineStyles.width = width;
+    }
+
     return (
-        <Flex direction="column" gap="5" ref={controlWrapRef} className={b()}>
+        <Flex
+            direction="column"
+            gap="5"
+            ref={controlWrapRef}
+            className={b(mods, className)}
+            style={inlineStyles}
+        >
             {togglerNode}
             <SelectPopup
                 ref={controlWrapRef}
@@ -255,7 +273,7 @@ export const TreeSelect = React.forwardRef(function TreeSelect<T>(
                         });
 
                         // assign components scope logic
-                        state.selectable = context.groupState
+                        state.hasSelectionIcon = context.groupState
                             ? groupsBehavior === 'selectable'
                             : undefined;
 
diff --git a/src/components/TreeSelect/__stories__/TreeSelect.stories.tsx b/src/components/TreeSelect/__stories__/TreeSelect.stories.tsx
index 8a48680eb6..ee0de0674e 100644
--- a/src/components/TreeSelect/__stories__/TreeSelect.stories.tsx
+++ b/src/components/TreeSelect/__stories__/TreeSelect.stories.tsx
@@ -25,7 +25,6 @@ import {
     WithItemLinksAndActionsExampleProps,
 } from './components/WithItemLinksAndActionsExample';
 
-// TODO: пример с кастомной структурой данных
 export default {
     title: 'Unstable/TreeSelect',
     component: TreeSelect,
diff --git a/src/components/TreeSelect/__stories__/components/WithFiltrationAndControlsExample.tsx b/src/components/TreeSelect/__stories__/components/WithFiltrationAndControlsExample.tsx
index 0cd53c850f..b4f6abda50 100644
--- a/src/components/TreeSelect/__stories__/components/WithFiltrationAndControlsExample.tsx
+++ b/src/components/TreeSelect/__stories__/components/WithFiltrationAndControlsExample.tsx
@@ -7,7 +7,7 @@ import {Flex, spacing} from '../../../layout';
 import {useListFilter} from '../../../useList';
 import {createRandomizedData} from '../../../useList/__stories__/utils/makeData';
 import {TreeSelect} from '../../TreeSelect';
-import type {TreeSelectProps} from '../../types';
+import type {RenderContainerProps, TreeSelectProps} from '../../types';
 
 import {RenderVirtualizedContainer} from './RenderVirtualizedContainer';
 
@@ -23,7 +23,23 @@ export const WithFiltrationAndControlsExample = ({
     itemsCount = 5,
     ...props
 }: WithFiltrationAndControlsExampleProps) => {
-    const items = React.useMemo(() => createRandomizedData({num: itemsCount}), [itemsCount]);
+    const {items, renderContainer} = React.useMemo(() => {
+        const baseItems = createRandomizedData({num: itemsCount});
+        const containerRenderer = (props: RenderContainerProps<{title: string}>) => {
+            if (props.items.length === 0 && baseItems.length > 0) {
+                return (
+                    <Flex centerContent className={spacing({p: 2})} height="300px">
+                        <Text variant="subheader-1">Nothing found</Text>
+                    </Flex>
+                );
+            }
+
+            return <RenderVirtualizedContainer {...props} />;
+        };
+
+        return {items: baseItems, renderContainer: containerRenderer};
+    }, [itemsCount]);
+
     const [open, onOpenChange] = React.useState(true);
     const [value, setValue] = React.useState<string[]>([]);
     const filterState = useListFilter({items});
@@ -48,17 +64,7 @@ export const WithFiltrationAndControlsExample = ({
                         ref={filterState.filterRef}
                     />
                 }
-                renderContainer={(props) => {
-                    if (props.items.length === 0 && items.length > 0) {
-                        return (
-                            <Flex centerContent className={spacing({p: 2})} height="300px">
-                                <Text variant="subheader-1">Nothing found</Text>
-                            </Flex>
-                        );
-                    }
-
-                    return <RenderVirtualizedContainer {...props} />;
-                }}
+                renderContainer={renderContainer}
                 slotAfterListBody={
                     <Flex gap="2" className={spacing({p: 2})}>
                         <Button
diff --git a/src/components/TreeSelect/types.ts b/src/components/TreeSelect/types.ts
index 000a4bca69..fb8235dd41 100644
--- a/src/components/TreeSelect/types.ts
+++ b/src/components/TreeSelect/types.ts
@@ -50,6 +50,8 @@ interface TreeSelectBaseProps<T> extends QAProps, Partial<Omit<ListState, 'selec
     id?: string | undefined;
     popupClassName?: string;
     popupWidth?: number;
+    width?: 'auto' | 'max' | number;
+    className?: string;
     popupDisablePortal?: boolean;
     multiple?: boolean;
     /**
diff --git a/src/components/useList/__stories__/components/FlattenList.tsx b/src/components/useList/__stories__/components/FlattenList.tsx
index 10cf4017e9..57f359e408 100644
--- a/src/components/useList/__stories__/components/FlattenList.tsx
+++ b/src/components/useList/__stories__/components/FlattenList.tsx
@@ -100,7 +100,7 @@ export const FlattenList = ({itemsCount, size}: FlattenListProps) => {
                             <ListItemView
                                 {...state}
                                 {...item}
-                                selectable={!listContext.groupState}
+                                hasSelectionIcon={!listContext.groupState}
                             />
                         );
                     }}
diff --git a/src/components/useList/__stories__/components/PopupWithTogglerList.tsx b/src/components/useList/__stories__/components/PopupWithTogglerList.tsx
index 998bd58284..af5efa38d8 100644
--- a/src/components/useList/__stories__/components/PopupWithTogglerList.tsx
+++ b/src/components/useList/__stories__/components/PopupWithTogglerList.tsx
@@ -120,7 +120,7 @@ export const PopupWithTogglerList = ({size, itemsCount}: PopupWithTogglerListPro
                                     <ListItemView
                                         {...state}
                                         {...data}
-                                        selectable={!listContext.groupState}
+                                        hasSelectionIcon={!listContext.groupState}
                                     />
                                 );
                             }}
diff --git a/src/components/useList/__stories__/components/RecursiveList.tsx b/src/components/useList/__stories__/components/RecursiveList.tsx
index 81d9b8402e..5fa8773e77 100644
--- a/src/components/useList/__stories__/components/RecursiveList.tsx
+++ b/src/components/useList/__stories__/components/RecursiveList.tsx
@@ -93,7 +93,7 @@ export const RecursiveList = ({size, itemsCount}: RecursiveListProps) => {
                                 <ListItemView
                                     {...state}
                                     {...data}
-                                    selectable={!listContext.groupState}
+                                    hasSelectionIcon={!listContext.groupState}
                                 />
                             );
                         }}
diff --git a/src/components/useList/__stories__/useList.mdx b/src/components/useList/__stories__/useList.mdx
index a88f682f64..2f3f031290 100644
--- a/src/components/useList/__stories__/useList.mdx
+++ b/src/components/useList/__stories__/useList.mdx
@@ -10,27 +10,124 @@ The basic idea is that hooks take all the complex logic on themselves, and all y
 
 `Storybook` provides complex examples how to use this components from this documentation.
 
-### Hooks
+### Hooks:
 
 -   [useList](#uselist-1);
 -   [useListKeydown](#uselistkeydown)
 -   [useListFilter](#uselistfilter);
 -   [useListState](#useliststate);
 
-### Components (View only);
+### Components (View only):
 
 -   [ListItemView](#listitemview);
 -   [ListContainerView](#listcontainerview);
 -   [ListRecursiveRenderer](#listrecursiverenderer);
 
-### Utilitys
+### Utilitys:
 
 -   [computeItemSize](#computeitemsize);
 -   [scrollToListItem](#scrolltolistitem);
 -   [getItemRenderState](#getitemrenderstate);
 -   [getListParsedState](#getlistparsedstate);
 
-## Hooks
+## Quick code snippets for beginners:
+
+### flatten items:
+
+```tsx
+import {
+    ListContainerView,
+    type ListItemId,
+    type ListItemType,
+    ListItemView,
+    getItemRenderState,
+    useList,
+    useListKeydown,
+    useListState,
+} from '@gravity-ui/uikit/unstable';
+
+const items: ListItemType<string>[] = ['one', 'two', 'free', 'four', 'five'];
+
+function List() {
+    const containerRef = React.useRef<HTMLDivElement>(null);
+
+    const listState = useListState();
+    const parsedListState = useList({
+        items,
+        expandedById: listState.expandedById,
+    });
+
+    useListKeydown({
+        onItemClick,
+        containerRef,
+        ...parsedListState,
+        ...listState,
+    });
+
+    return (
+        <ListContainerView ref={containerRef}>
+            {parsedListState.items.map((_, i) => {
+                const [itemData, computedItemProps, _listContext] = getItemRenderState({
+                    id: String(i),
+                    onItemClick,
+                    ...parsedListState,
+                    ...listState,
+                });
+
+                return <ListItemView key={i} {...computedItemProps} title={itemData} />;
+            })}
+        </ListContainerView>
+    );
+
+    // multiple selection
+    function onItemClick(id: ListItemId) {
+        listState.setSelected((prevState) => ({
+            ...prevState,
+            [id]: !prevState[id],
+        }));
+
+        listState.setActiveItemId(id);
+    }
+}
+```
+
+### tree item structure:
+
+```tsx
+const items: ListItemType<string>[] = [
+    {data: 'one'},
+    {data: 'two', children: [{data: 'tree', children: [{data: 'four'}, {data: 'five'}]}]},
+];
+
+function List() {
+    // same as prev example
+    return (
+        <ListContainerView ref={containerRef}>
+            {parsedListState.items.map((item, index) => (
+                <ListItemRecursiveRenderer
+                    key={index}
+                    itemSchema={item}
+                    index={index}
+                    expandedById={expandedById}
+                >
+                    {(id) => {
+                        const [itemData, computedItemProps, _listContext] = getItemRenderState({
+                            id: String(i),
+                            onItemClick,
+                            ...parsedListState,
+                            ...listState,
+                        });
+
+                        return <ListItemView {...computedItemProps} title={itemData} />;
+                    }}
+                </ListItemRecursiveRenderer>
+            ))}
+        </ListContainerView>
+    );
+}
+```
+
+## Hooks:
 
 ### useList
 
@@ -216,7 +313,7 @@ const {
 } = useListState();
 ```
 
-## Components
+## Components:
 
 ### ListItemView
 
@@ -235,7 +332,7 @@ Use it even if the functionality of the `useList` hook seems redundant to you
 -   `disabled` - The disabled state. It also prevents clicking on an element;
 -   `activeOnHover`- By default hovered elements has active styles. You can disable this behavior;
 -   `indentation` - Build in indentation component to render nested views structure;
--   `selectable` - Show selected icon if selected and reserve space for this icon;
+-   `hasSelectionIcon` - Show selected icon if selected and reserve space for this icon;
 -   `onClick` - on item click callback. !Note: if passed this and `disabled` option is `true` click will not be appear;
 -   `style` - optional react `React.CSSProperties` object;
 -   `subtitle` - Slot under `title`. If passed string apply prefefined styles. Or you can pass custom `React.ReactNode` to use you own behaviour;
diff --git a/src/components/useList/components/ListItemView/ListItemView.tsx b/src/components/useList/components/ListItemView/ListItemView.tsx
index 124abff6ee..c35f95c94a 100644
--- a/src/components/useList/components/ListItemView/ListItemView.tsx
+++ b/src/components/useList/components/ListItemView/ListItemView.tsx
@@ -39,7 +39,7 @@ export interface ListItemViewProps extends QAProps, Omit<React.HTMLAttributes<'l
     /**
      * Show selected icon if selected and reserve space for this icon
      */
-    selectable?: boolean;
+    hasSelectionIcon?: boolean;
     /**
      * Note: if passed and `disabled` option is `true` click will not be appear
      */
@@ -90,7 +90,7 @@ export const ListItemView = React.forwardRef(
             corners = true,
             activeOnHover = true,
             className,
-            selectable = true,
+            hasSelectionIcon = true,
             indentation,
             startSlot,
             subtitle,
@@ -114,7 +114,7 @@ export const ListItemView = React.forwardRef(
                 className={b(
                     {
                         active,
-                        selected,
+                        selected: selected && !hasSelectionIcon,
                         activeOnHover,
                         clickable: Boolean(onClick),
                     },
@@ -133,7 +133,7 @@ export const ListItemView = React.forwardRef(
                 {...rest}
             >
                 <Flex gap="2" alignItems="center">
-                    {selectable && (
+                    {hasSelectionIcon && (
                         <Slot>
                             {selected ? (
                                 <Icon
diff --git a/src/components/useList/components/ListItemView/__stories__/ListItemView.stories.tsx b/src/components/useList/components/ListItemView/__stories__/ListItemView.stories.tsx
index 888a7a0e7a..5af6542573 100644
--- a/src/components/useList/components/ListItemView/__stories__/ListItemView.stories.tsx
+++ b/src/components/useList/components/ListItemView/__stories__/ListItemView.stories.tsx
@@ -4,6 +4,8 @@ import type {Meta, StoryFn} from '@storybook/react';
 
 import {Avatar} from '../../../../Avatar';
 import {Flex} from '../../../../layout';
+import {useListState} from '../../../hooks/useListState';
+import type {ListItemId} from '../../../types';
 import {ListItemView as ListItemViewComponent, ListItemViewProps} from '../ListItemView';
 
 export default {
@@ -36,7 +38,7 @@ const stories: ListItemViewProps[] = [
         title,
         size: 'l',
         subtitle,
-        selected: true,
+        hasSelectionIcon: false,
         startSlot: (
             <Avatar imgUrl="https://avatars.mds.yandex.net/get-yapic/69015/enc-137b8b64288fa6fc5ec58c6b83aea00e7723c8fa5638c078312a1134d8ee32ac/islands-retina-50" />
         ),
@@ -53,13 +55,17 @@ const stories: ListItemViewProps[] = [
     },
     {
         id: '5',
+        size: 'l',
+        startSlot: (
+            <Avatar imgUrl="https://avatars.mds.yandex.net/get-yapic/69015/enc-137b8b64288fa6fc5ec58c6b83aea00e7723c8fa5638c078312a1134d8ee32ac/islands-retina-50" />
+        ),
         title,
     },
     {
         id: '6',
         title,
         size: 'l',
-        subtitle,
+        subtitle: 'indentation 1',
         startSlot: (
             <Avatar imgUrl="https://avatars.mds.yandex.net/get-yapic/69015/enc-137b8b64288fa6fc5ec58c6b83aea00e7723c8fa5638c078312a1134d8ee32ac/islands-retina-50" />
         ),
@@ -69,17 +75,41 @@ const stories: ListItemViewProps[] = [
     {
         id: '7',
         expanded: true,
-        selectable: false,
+        size: 'xl',
+        title: 'Group 1',
+    },
+    {
+        id: '8',
+        hasSelectionIcon: false,
+        expanded: true,
         size: 'xl',
         title: 'Group 1',
     },
 ];
 
-const ListItemViewTemplate: StoryFn<ListItemViewProps> = () => (
-    <Flex direction="column" width={300}>
-        {stories.map((props, i) => (
-            <ListItemViewComponent key={i} {...props} />
-        ))}
-    </Flex>
-);
+const ListItemViewTemplate: StoryFn<ListItemViewProps> = () => {
+    const listState = useListState();
+
+    return (
+        <Flex direction="column" width={300}>
+            {stories.map((props, i) => (
+                <ListItemViewComponent
+                    key={i}
+                    {...props}
+                    selected={listState.selectedById[props.id]}
+                    onClick={handleClick(props.id)}
+                />
+            ))}
+        </Flex>
+    );
+
+    function handleClick(id: ListItemId) {
+        return () => {
+            listState.setSelected((prevState) => ({
+                ...prevState,
+                [id]: !prevState[id],
+            }));
+        };
+    }
+};
 export const ListItemView = ListItemViewTemplate.bind({});
diff --git a/src/components/useList/types.ts b/src/components/useList/types.ts
index 28a954935c..77b225dae2 100644
--- a/src/components/useList/types.ts
+++ b/src/components/useList/types.ts
@@ -71,7 +71,7 @@ export type RenderItemState = {
     expanded?: boolean;
     active: boolean;
     indentation: number;
-    selectable?: boolean;
+    hasSelectionIcon?: boolean;
 };
 
 export type ParsedState<T> = {