fix: more docs fixes

gravity-ui · Mar 29, 2024 · 1dbbbf9 · 1dbbbf9
1 parent fb623ac
commit 1dbbbf9
Show file tree

Hide file tree

Showing 8 changed files with 234 additions and 75 deletions.
diff --git a/src/components/TreeList/__stories__/TreeList.mdx b/src/components/TreeList/__stories__/TreeList.mdx
@@ -199,7 +199,7 @@ Control the default expanded state of items' groups. Default - `true`.
 
 ### renderItem
 
-The ability to completely 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);
+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
 <TreeList
@@ -217,23 +217,76 @@ The ability to completely redefine the rendering of a list item. For example, ad
 
 #### renderItem function argument object:
 
--   `data` - access to the original object with the data of the sheet element;
--   `props` - default props generated by the component taking into account the state (whether the element is selected or not, active, disclosed). The set of returned passes corresponds to the result of the function execution [getItemRenderState](/docs/unstable-uselist--docs#item-state-props);
--   `index` - ordinal index of the element, taking into account that with a tree-like data structure, the list elements have a flatten representation;
--   `renderContainerProps` - the passes thrown from the redefined container. In the vast majority of cases, you won't need it, but it's worth knowing that there is such a possibility.;
--   `context` - useful information about the current list item:
-    -   `itemState` - meta info about item
-        -   `indentation` - integer number representing nested list level
-        -   `parentId` - `id` of parent list item;
-    -   `groupState` - An optional parameter. If the list item is also the first item of the nested list:
-        -   `childrenIds` - array of `id` of nested list items;
-    -   `isLastItem` - is the current item the last one in the list;
+```tsx
+type ListItemSize = 's' | 'm' | 'l' | 'xl';
+
+interface RenderItemProps {
+    /**
+     * access to the original object with the data of the list element
+     */
+    data: T;
+    /**
+     * ordinal index of the element, taking into account that with a tree-like data structure, the list elements have a flatten representation;
+     */
+    index: number;
+    /**
+     * default props generated by the component taking into account the state (whether the element is selected or not, active, disclosed). The set of returned passes corresponds to the result of the function execution [getItemRenderState](/docs/unstable-uselist--docs#item-state-props)
+     */
+    props: {
+        // item id;
+        id: string;
+        // qa attribute for tests
+        qa?: string;
+        // item size;
+        size: ListItemSize;
+        // expanded state if item group;
+        expanded?: boolean;
+        // is item active
+        active: boolean;
+        // item nest level;
+        indentation: number;
+        // is item disabled;
+        disabled: boolean;
+        // is item selected;
+        selected?: boolean;
+        // on item click handle if exists;
+        onClick?(): void;
+        // affects the view of the selected items;
+        hasSelectionIcon?: boolean;
+        // one required field of result `mapItemDataToProps` function work;
+        title: React.ReactNode;
+    };
+    /**
+     * during `renderContainer` props you can pass render container context props to items;
+     */
+    renderContainerProps?: Object;
+    /**
+     * useful information about the current list item:
+     */
+    context: {
+        // meta info about item
+        itemState: {
+            // integer number, representing nested list level
+            indentation: number;
+            // `id` of parent list item if it exists
+            parentId?: string;
+        };
+        // An optional parameter. If the list item is also the first item of the nested list
+        groupState: {
+            // array of `id` of nested list items;
+            childrenIds: string[];
+        };
+        // is the current item the last one in the list
+        isLastItem: boolean;
+    };
+}
+```
 
-> Important! Absolutely all the props for [ListItemView](/docs/unstable-uselist--docs#listitemview) can be redefined in the renderItem method. This is the preferred method for changing the view of the sheet elements.
+> Important! Absolutely all the props for [ListItemView](/docs/unstable-uselist--docs#listitemview) can be redefined in the renderItem method. This is the preferred method for changing the view of the list elements.
 
 ### renderContainer
 
-Ability to override default list container `ListContainerView`;
+Render custom list container.
 
 ```tsx
 <TreeList
@@ -274,7 +327,7 @@ Ability to override default list container `ListContainerView`;
 
 ### onItemClick
 
-Ability to define on item click callback. Also this callback will be called with handling keyboard actions
+Item's click callback. It also will be called on keyboard actions.
 
 ```tsx
 <TreeList
@@ -297,16 +350,52 @@ Ability to define on item click callback. Also this callback will be called with
 
 #### onItemClick function argument object:
 
--   `id` - of the current element;
--   `data` - access to the original payload (`T`) list item;
--   `index` - the ordinal index of the element, taking into account that with a tree-like data structure, the list elements have a flatten representation;
--   `selected` - whether the item is selected or not;
--   `disabled` - is the element disabled;
--   `expanded` - are nested child elements hidden;
--   `context` - useful information about the current list item:
-    -   `itemState` - meta info about item
-        -   `indentation` - integer number representing nested list level
-        -   `parentId` - `id` of parent list item;
-    -   `groupState` - An optional parameter. If the list item is also the first item of the nested list:
-        -   `childrenIds` - `id` array of nested elements;
-    -   `isLastItem` - is the current item the last one in the list;
+```tsx
+type OnItemClick<T> = (props: OnItemClickProps<T>) => void;
+
+interface OnItemClickProps<T> {
+    /**
+     * `id` of the current element;
+     */
+    id: string;
+    /**
+     * access to the original payload (`T`) list item;
+     */
+    data: T;
+    /**
+     * the ordinal index of the element, taking into account that with a tree-like data structure, the list elements have a flatten representation;
+     */
+    index: number;
+    /**
+     * whether the item is selected or not;
+     */
+    selected: boolean;
+    /**
+     * is the element disabled;
+     */
+    disabled: boolean;
+    /**
+     * are nested child elements hidden;
+     */
+    expanded: boolean;
+    /**
+     * useful information about the current list item:
+     */
+    context: {
+        // meta info about item
+        itemState: {
+            // integer number, representing nested list level
+            indentation: number;
+            // `id` of parent list item if it exists
+            parentId?: string;
+        };
+        // An optional parameter. If the list item is also the first item of the nested list
+        groupState: {
+            // array of `id` of nested list items;
+            childrenIds: string[];
+        };
+        // is the current item the last one in the list
+        isLastItem: boolean;
+    };
+}
+```
diff --git a/src/components/TreeList/__stories__/stories/WithGroupSelectionAndCustomIconStory.tsx b/src/components/TreeList/__stories__/stories/WithGroupSelectionAndCustomIconStory.tsx
@@ -6,7 +6,7 @@ import {Button} from '../../../Button';
 import {Icon} from '../../../Icon';
 import {Flex, spacing} from '../../../layout';
 import {ListItemView, useListState} from '../../../useList';
-import type {KnownItemStructure} from '../../../useList';
+import type {ListItemCommonProps} from '../../../useList';
 import {createRandomizedData} from '../../../useList/__stories__/utils/makeData';
 import {TreeList} from '../../TreeList';
 import type {TreeListOnItemClick, TreeListProps} from '../../types';
@@ -29,7 +29,7 @@ export interface WithGroupSelectionAndCustomIconStoryProps
     itemsCount?: number;
 }
 
-const mapCustomDataStructureToKnownProps = (props: CustomDataStructure): KnownItemStructure => ({
+const mapCustomDataStructureToKnownProps = (props: CustomDataStructure): ListItemCommonProps => ({
     title: props.a,
 });
 

diff --git a/src/components/TreeList/types.ts b/src/components/TreeList/types.ts
@@ -2,7 +2,7 @@ import type React from 'react';
 
 import type {QAProps} from '../types';
 import type {
-    KnownItemStructure,
+    ListItemCommonProps,
     ListItemId,
     ListItemSize,
     ListItemType,
@@ -67,7 +67,7 @@ export type TreeListRenderContainer<T> = (
     props: TreeListRenderContainerProps<T>,
 ) => React.JSX.Element;
 
-export type TreeListMapItemDataToProps<T> = (item: T) => KnownItemStructure;
+export type TreeListMapItemDataToProps<T> = (item: T) => ListItemCommonProps;
 
 export interface TreeListProps<T> extends QAProps, Partial<ListState> {
     /**

diff --git a/...ents/TreeSelect/__stories__/components/WithGroupSelectionControlledStateAndCustomIcon.tsx b/...ents/TreeSelect/__stories__/components/WithGroupSelectionControlledStateAndCustomIcon.tsx
@@ -6,7 +6,7 @@ import {Button} from '../../../Button';
 import {Icon} from '../../../Icon';
 import {Flex, spacing} from '../../../layout';
 import {ListItemView, getListParsedState} from '../../../useList';
-import type {KnownItemStructure, ListItemId} from '../../../useList';
+import type {ListItemCommonProps, ListItemId} from '../../../useList';
 import {createRandomizedData} from '../../../useList/__stories__/utils/makeData';
 import {TreeSelect} from '../../TreeSelect';
 import type {TreeSelectProps} from '../../types';
@@ -26,7 +26,7 @@ export interface WithGroupSelectionControlledStateAndCustomIconExampleProps
     itemsCount?: number;
 }
 
-const mapCustomDataStructureToKnownProps = (props: CustomDataStructure): KnownItemStructure => ({
+const mapCustomDataStructureToKnownProps = (props: CustomDataStructure): ListItemCommonProps => ({
     title: props.a,
 });