fix(useList): added missing imports to docs (#1466)

Co-authored-by: Alexandr Isaev <[email protected]>

src/components/TreeList/__stories__/TreeList.mdx

@@ -30,7 +30,10 @@ The basic component for working with lists, including tree-like ones. Under the
 ### Basic example:
 
 ```tsx
-import {type ListItemType, TreeList} from '@gravity-ui/uikit';
+import {
+    type unstable_ListItemType as ListItemType,
+    unstable_TreeList as TreeList,
+} from '@gravity-ui/uikit/unstable';
 
 const items: ListItemType<string>[] = ['one', 'two', 'free', 'four', 'five'];
 
@@ -40,7 +43,11 @@ const items: ListItemType<string>[] = ['one', 'two', 'free', 'four', 'five'];
 ### Example with state:
 
 ```tsx
-import {type ListItemType, TreeList} from '@gravity-ui/uikit';
+import {
+    type unstable_ListItemType as ListItemType,
+    unstable_TreeList as TreeList,
+    unstable_useListState as useListState,
+} from '@gravity-ui/uikit/unstable';
 
 const items: ListItemType<string>[] = [
     {title: 'one'},
@@ -105,7 +112,12 @@ Pass a ref to pass a link to the DOM element of the container. For example, in o
 
 ```tsx
 import React from 'react';
-import {type ListItemType, TreeList, Button, Alert} from '@gravity-ui/uikit';
+import {Button, Alert} from '@gravity-ui/uikit';
+import {
+    type unstable_ListItemType as ListItemType,
+    unstable_TreeList sa TreeList,
+    unstable_useListState as useListState,
+} from '@gravity-ui/uikit/unstable';
 
 const items: ListItemType<string>[] = [
     {data: {title: 'one'}},
@@ -202,17 +214,22 @@ Control the default expanded state of items' groups. Default - `true`.
 Redefine the rendering of a list item. For example, add dividers between list items or wrap an item in a link component. As a view component to display a list item, use [ListItemView](/docs/unstable-uselist--docs#listitemview);
 
 ```tsx
+import {
+    unstable_TreeList as TreeList,
+    unstable_ListItemView as ListItemView,
+} from '@gravity-ui/uikit/unstable';
+
 <TreeList
     renderItem={({
-        data,
         props,
-        index,
         renderContainerProps,
-        itemState: {groupState, isLastItem, itemState},
+        context: {groupState, isLastItem, itemState},
+        data,
+        index,
     }) => {
         return <ListItemView {...props} {...renderContainerProps} />;
     }}
-/>
+/>;
 ```
 
 #### renderItem function argument object:
@@ -289,6 +306,11 @@ interface RenderItemProps {
 Render custom list container.
 
 ```tsx
+import {
+    unstable_TreeList as TreeList,
+    unstable_ListContainerView as ListContainerView,
+} from '@gravity-ui/uikit/unstable';
+
 <TreeList
     renderContainer={({
         id,
@@ -322,14 +344,16 @@ Render custom list container.
             </ListContainerView>
         );
     }}
-/>
+/>;
 ```
 
 ### onItemClick
 
 Item's click callback. It also will be called on keyboard actions.
 
 ```tsx
+import {unstable_TreeList as TreeList} from '@gravity-ui/uikit/unstable';
+
 <TreeList
     onItemClick={({
         id,
@@ -345,7 +369,7 @@ Item's click callback. It also will be called on keyboard actions.
     }) => {
         // just do it!
     }}
-/>
+/>;
 ```
 
 #### onItemClick function argument object:

src/components/useList/__stories__/useList.mdx

@@ -37,14 +37,14 @@ The basic idea is that hooks take all the complex logic on themselves, and all y
 
 ```tsx
 import {
-    ListContainerView,
-    type ListItemId,
-    type ListItemType,
-    ListItemView,
-    getItemRenderState,
-    useList,
-    useListKeydown,
-    useListState,
+    type unstable_ListItemId as ListItemId,
+    type unstable_ListItemType as ListItemType,
+    unstable_ListContainerView as ListContainerView,
+    unstable_ListItemView as ListItemView,
+    unstable_getItemRenderState as getItemRenderState,
+    unstable_useList as useList,
+    unstable_useListKeydown as useListKeydown,
+    unstable_useListState as useListState,
 } from '@gravity-ui/uikit/unstable';
 
 const items: ListItemType<string>[] = ['one', 'two', 'free', 'four', 'five'];
@@ -100,6 +100,13 @@ function List() {
 ### tree item structure:
 
 ```tsx
+import {
+    unstable_ListItemRecursiveRenderer as ListItemRecursiveRenderer,
+    unstable_ListContainerView as ListContainerView,
+    unstable_ListItemView as ListItemView,
+    unstable_getItemRenderState as getItemRenderState,
+} from '@gravity-ui/uikit/unstable';
+
 const items: ListItemType<string>[] = [
     {data: 'one'},
     {data: 'two', children: [{data: 'tree', children: [{data: 'four'}, {data: 'five'}]}]},
@@ -117,19 +124,15 @@ function List() {
                     expandedById={expandedById}
                 >
                     {(id) => {
-                        const {
-                            data,
-                            props,
-                            context: _context,
-                        } = getItemRenderState({
+                        const {props} = getItemRenderState({
                             id: String(i),
                             mapItemDataToProps: (title) => ({title}),
                             onItemClick,
                             ...list,
                             ...listState,
                         });
 
-                        return <ListItemView {...props} title={data} />;
+                        return <ListItemView {...props} />;
                     }}
                 </ListItemRecursiveRenderer>
             ))}
@@ -286,6 +289,12 @@ Keyboard support
 -   `enabled` - on/off keyboard support. Use it if you need to change the behavior in runtime;
 
 ```tsx
+import {
+    unstable_useList as useList,
+    unstable_useListKeydown as useListKeydown,
+    unstable_useListState as useListState,
+} from '@gravity-ui/uikit/unstable';
+
 const containerRef = React.useRef<HTMLDivElement>(null);
 const listState = useListState()
 const list = useList(...)
@@ -319,6 +328,11 @@ useListKeydown({
 -   `onFilterUpdate` - callback for changing the filter value;
 
 ```tsx
+import {
+    unstable_useList as useList,
+    unstable_useListKeydown as useListFilter,
+} from '@gravity-ui/uikit/unstable';
+
 const List = () => {
     const {items, filter, onFilterUpdate, filterRef} = useListFilter({
         items: [...]
@@ -345,6 +359,8 @@ const List = () => {
 The basic hook for managing the state of the `List`. You can use your own implementation, the main thing is to understand about the concept of the `state` of the sheet. Which corresponds to the following interface:
 
 ```tsx
+import {unstable_useListState as useListState} from '@gravity-ui/uikit/unstable';
+
 type ListState = {
     disabledById: Record<ListItemId, boolean>;
     selectedById: Record<ListItemId, boolean>;
@@ -371,30 +387,15 @@ const {
 The basic component responsible for the appearance of the list items.
 Use it even if the functionality of the `useList` hook seems redundant to you
 
-#### Props:
+```tsx
+import {
+    type unstable_ListItemType as ListItemType,
+    unstable_ListItemView as ListItemView,
+} from '@gravity-ui/uikit/unstable';
 
--   `id` - required prop. Set `[data-list-item="${id}"]` data attribute. By this it core list engine finds elements to scroll to.
--   `title` - base required prop to use. If passed string, applas default component styles according desig system. Pass you own componnet if you wont custom behaviour;
--   `as` - if needed, override `html` tag. By default - `li`;
--   `size` - the size of the element. This also affects the rounding radius of the list element . By default, `m`. Available sizes are `s`, `m`, `l` and `xl`;
--   `height` - the height of the element in pixels. By default, it is calculated depending on the `size` parameter and the presence of the `subtitle` parameter;
--   `selected` - the selected state of the component; affects the `activeOnHover` if value if the value is different from `undefined`;
--   `active` - the state when the element is in the user's focus, but not selected. It can also be used when you drag an element;
--   `disabled` - the disabled state. It also prevents clicking on an element;
--   `activeOnHover`- directly control hover behaviour;
--   `indentation` - affects the visual indentation of the element content;
--   `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;
--   `startSlot` - custom slot before `title`;
--   `endSlot` - custom slot after `title`;
--   `corners` - Prop to remove default border radiuses from element;
--   `className` - custom class name to mix with;
--   `expanded` - adds a visual representation of a group element if the value is different from `undefined`;
+type Entity = {title: stirng, subtitle: string, icon: React.ReactNode};
 
-```tsx
-const items = [
+const items: ListItemType<Entity>[] = [
     {title: 'some title 1', subtitle: 'some subtitle 1', icon: <Icon data={Grip} size={16} />},
     {title: 'some title 2', subtitle: 'some subtitle 2', icon: <Icon data={Grip} size={16} />},
 ];
@@ -418,6 +419,28 @@ const List = () => {
 };
 ```
 
+#### Props:
+
+-   `id` - required prop. Set `[data-list-item="${id}"]` data attribute. By this it core list engine finds elements to scroll to.
+-   `title` - base required prop to use. If passed string, applas default component styles according desig system. Pass you own componnet if you wont custom behaviour;
+-   `as` - if needed, override `html` tag. By default - `li`;
+-   `size` - the size of the element. This also affects the rounding radius of the list element . By default, `m`. Available sizes are `s`, `m`, `l` and `xl`;
+-   `height` - the height of the element in pixels. By default, it is calculated depending on the `size` parameter and the presence of the `subtitle` parameter;
+-   `selected` - the selected state of the component; affects the `activeOnHover` if value if the value is different from `undefined`;
+-   `active` - the state when the element is in the user's focus, but not selected. It can also be used when you drag an element;
+-   `disabled` - the disabled state. It also prevents clicking on an element;
+-   `activeOnHover`- directly control hover behaviour;
+-   `indentation` - affects the visual indentation of the element content;
+-   `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;
+-   `startSlot` - custom slot before `title`;
+-   `endSlot` - custom slot after `title`;
+-   `corners` - Prop to remove default border radiuses from element;
+-   `className` - custom class name to mix with;
+-   `expanded` - adds a visual representation of a group element if the value is different from `undefined`;
+
 ### ListContainerView
 
 The default container for all custom lists. Contains all html attributes and styles for quick use in your projects.
@@ -454,6 +477,18 @@ For the virtualized version of the list, you need to implement a component with
 -   `style` - optional react `React.CSSProperties` object;
 
 ```tsx
+import {
+    unstable_ListItemView as ListItemView,
+    unstable_ListContainerView as ListContainerView,
+    unstable_ListItemRecursiveRenderer as ListItemRecursiveRenderer,
+    type unstable_ListItemType as ListItemType,
+    unstable_getItemRenderState as getItemRenderState,
+} from '@gravity-ui/uikit/unstable';
+
+type Entity = {text: string}:
+
+const items: ListItemType<Entity>[] = [{data: {text: 'one'}}, {data: {text: 'two'}}]
+
 <ListContainerView ref={containerRef}>
     {items.map((item, index) => (
         <ListItemRecursiveRenderer
@@ -462,10 +497,22 @@ For the virtualized version of the list, you need to implement a component with
             index={index}
             expandedById={expandedById}
         >
-            {(id) => <ListItemView key={id} id={id} title={itemsById[id].title} />}
+            {(id) => {
+                const {props} = getItemRenderState({
+                    qa: 'some-qa-id',
+                    id,
+                    multiple: false,
+                    size: 'm',
+                    mapItemDataToProps: (item) => ({title: item.title}),
+                    ...list,
+                    ...listState,
+                });
+
+                return <ListItemView key={id} id={id} title={itemsById[id].title} />;
+            }}
         </ListItemRecursiveRenderer>
     ))}
-</ListContainerView>
+</ListContainerView>;
 ```
 
 ## Utilitys
@@ -493,6 +540,11 @@ Utility to compute list item height:
 Utility to sroll into list item view by id and ref on container DOM element:
 
 ```tsx
+import {
+    unstable_ListContainerView as ListContainerView,
+    unstable_scrollToListItem as scrollToListItem,
+} from '@gravity-ui/uikit/unstable';
+
 const containerRef = React.useRef<HTMLDivElement>(null);
 // restoring focus when popup opens
 React.useLayoutEffect(() => {
@@ -514,15 +566,24 @@ React.useLayoutEffect(() => {
 Map list state to ListItemView render props;
 
 ```tsx
+import {
+    unstable_ListItemView as ListItemView,
+    unstable_getItemRenderState as getItemRenderState,
+    unstable_useListState as useListState,
+    unstable_useList as useList,
+} from '@gravity-ui/uikit/unstable';
+
 const list = useList();
 const listState = useListState();
 
 const {data, props, context} = getItemRenderState({
     qa: 'some-qa-id',
     id,
-    multiple: false,
+    multiple: true,
     size, // list size
-    onItemClick: (id: ListItemId) => {},
+    onItemClick: (id: ListItemId) => {
+        // ...
+    },
     mapItemDataToProps: (item) => ({title: item.title}),
     ...list,
     ...listState,
@@ -628,19 +689,20 @@ interface ItemContext {
         // array of `id` of nested list items;
         childrenIds: string[];
     };
-    // is the current item the last one in the list
+    // is the current item the last one in the list. For example needed to implement custom infinity lists variants
     isLastItem: boolean;
 }
 ```
 
-    -   `itemState`:
-        -   `parentId?` - id of parant element;
-        -   `indentation` - item nest level;
-    -   `groupState` - exists only if item is group:
-        -   `childrenIds` - List of child element IDs;
-    -   `isLastItem` - if item is last in the list. Useful in cases than you need to do somthing on last item appears. For example, implement custom infinity lists variants
-
 ```tsx
+import {
+    unstable_ListContainerView as ListItemRecursiveRenderer,
+    unstable_ListItemView as ListItemView,
+    unstable_getItemRenderState as getItemRenderState,
+    unstable_useList as useList,
+    unstable_useListState as useListState,
+} from '@gravity-ui/uikit/unstable';
+
 const listState = useListState();
 const list = useList({
     items,
@@ -671,6 +733,8 @@ const handleItemClick = () => {};
 same as `useList` hook functionality in stateless function. Use it if you need to extract initial list state form declaration:
 
 ```tsx
+import {unstable_getListParsedState as getListParsedState} from '@gravity-ui/uikit/unstable';
+
 // custom controlled state from computed initial state
 const [expandedById, setExpanded] = React.useState(
     () => getListParsedState(items).initialState.expandedById,
@@ -683,5 +747,7 @@ Function is used to generate `qa` attributes in list items;
 Also use this function in tests to create a unique data attribute for accessing a specific list item.
 
 ```ts
+import {unstable_getListItemQa as getListItemQa} from '@gravity-ui/uikit/unstable';
+
 await locator.getByTestId(getListItemQa('some-list-qa', '0')); // select the first item in the list if auto-generated `id` are used
 ```

src/components/useList/index.ts

@@ -10,4 +10,5 @@ export * from './utils/computeItemSize';
 export * from './utils/getItemRenderState';
 export * from './utils/scrollToListItem';
 export * from './utils/getListParsedState';
+export * from './utils/getListItemQa';
 export {modToHeight} from './constants';