From 4940a9adc0fb036aa2b39b0c67283ac75443be53 Mon Sep 17 00:00:00 2001 From: Isaev Alexandr Date: Fri, 29 Mar 2024 19:14:17 +0300 Subject: [PATCH] fix(useList): added missing imports to docs (#1466) Co-authored-by: Alexandr Isaev --- .../TreeList/__stories__/TreeList.mdx | 42 ++++- .../useList/__stories__/useList.mdx | 162 ++++++++++++------ src/components/useList/index.ts | 1 + src/unstable.ts | 10 ++ 4 files changed, 158 insertions(+), 57 deletions(-) diff --git a/src/components/TreeList/__stories__/TreeList.mdx b/src/components/TreeList/__stories__/TreeList.mdx index b7d734cea4..1a3a93f9b8 100644 --- a/src/components/TreeList/__stories__/TreeList.mdx +++ b/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[] = ['one', 'two', 'free', 'four', 'five']; @@ -40,7 +43,11 @@ const items: ListItemType[] = ['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[] = [ {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[] = [ {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'; + { return ; }} -/> +/>; ``` #### 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'; + ); }} -/> +/>; ``` ### onItemClick @@ -330,6 +352,8 @@ Render custom list container. Item's click callback. It also will be called on keyboard actions. ```tsx +import {unstable_TreeList as TreeList} from '@gravity-ui/uikit/unstable'; + { // just do it! }} -/> +/>; ``` #### onItemClick function argument object: diff --git a/src/components/useList/__stories__/useList.mdx b/src/components/useList/__stories__/useList.mdx index b817ee07da..574c4f03bf 100644 --- a/src/components/useList/__stories__/useList.mdx +++ b/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[] = ['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[] = [ {data: 'one'}, {data: 'two', children: [{data: 'tree', children: [{data: 'four'}, {data: 'five'}]}]}, @@ -117,11 +124,7 @@ function List() { expandedById={expandedById} > {(id) => { - const { - data, - props, - context: _context, - } = getItemRenderState({ + const {props} = getItemRenderState({ id: String(i), mapItemDataToProps: (title) => ({title}), onItemClick, @@ -129,7 +132,7 @@ function List() { ...listState, }); - return ; + return ; }} ))} @@ -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(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; selectedById: Record; @@ -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[] = [ {title: 'some title 1', subtitle: 'some subtitle 1', icon: }, {title: 'some title 2', subtitle: 'some subtitle 2', icon: }, ]; @@ -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[] = [{data: {text: 'one'}}, {data: {text: 'two'}}] + {items.map((item, index) => ( - {(id) => } + {(id) => { + const {props} = getItemRenderState({ + qa: 'some-qa-id', + id, + multiple: false, + size: 'm', + mapItemDataToProps: (item) => ({title: item.title}), + ...list, + ...listState, + }); + + return ; + }} ))} - +; ``` ## 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(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 ``` diff --git a/src/components/useList/index.ts b/src/components/useList/index.ts index d0e2d25615..c2237d6d36 100644 --- a/src/components/useList/index.ts +++ b/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'; diff --git a/src/unstable.ts b/src/unstable.ts index 37200971c7..00cac2ba1d 100644 --- a/src/unstable.ts +++ b/src/unstable.ts @@ -4,6 +4,16 @@ export { useListState as unstable_useListState, useListFilter as unstable_useListFilter, useListKeydown as unstable_useListKeydown, + ListItemView as unstable_ListItemView, + type ListItemViewProps as unstable_ListItemViewProps, + ListContainerView as unstable_ListContainerView, + type ListContainerViewProps as unstable_ListContainerViewProps, + type ListItemType as unstable_ListItemType, + type ListItemId as unstable_ListItemId, + getItemRenderState as unstable_getItemRenderState, + scrollToListItem as unstable_scrollToListItem, + getListItemQa as unstable_getListItemQa, + getListParsedState as unstable_getListParsedState, } from './components/useList'; export { TreeSelect as unstable_TreeSelect,