@cloud-ru/ds-tree 1.0.0

package/dist/esm/types.d.ts

@@ -0,0 +1,151 @@
+import { ItemProps } from '@cloud-ru/ds-list';
+import { ValueOf, WithSupportProps } from '@cloud-ru/ds-utils';
+import { MouseEvent, MouseEventHandler, ReactNode } from 'react';
+import { SELECTION_MODE, SIZE } from './constants.js';
+export type SelectionMode = ValueOf<typeof SELECTION_MODE>;
+export type Size = ValueOf<typeof SIZE>;
+export type TreeNodeId = string;
+export type BaseTreeNode = WithSupportProps<{
+    /** Идентификатор элемента */
+    id: TreeNodeId;
+    /** Имя элемента */
+    title: string | ((value: Pick<BaseTreeNode, 'id' | 'disabled'>) => ReactNode);
+    /** Является ли элемент деактивированным */
+    disabled?: boolean;
+    /** Обработчик клика по элементу */
+    onClick?: MouseEventHandler;
+    /** CSS-класс */
+    className?: string;
+    /** Ссылка на элемент */
+    href?: string;
+}>;
+export type ChildTreeNode = BaseTreeNode & {
+    /** Иконка дочернего элемента */
+    icon?: ReactNode;
+    nested?: never;
+    expandedIcon?: never;
+    collapsedIcon?: never;
+};
+export type ParentTreeNode = BaseTreeNode & {
+    icon?: never;
+    /** Иконка элемента-родителя в открытом состоянии */
+    expandedIcon?: ReactNode;
+    /** Иконка элемента-родителя в закрытом состоянии */
+    collapsedIcon?: ReactNode;
+    /** Вложенные элементы дерева */
+    nested: (ChildTreeNode | ParentTreeNode)[];
+    /** Имя элемента-родителя (расширяет вариант из `BaseTreeNode` — в callback приходят также `nested`-узлы) */
+    title: string | ((value: Pick<ParentTreeNode, 'id' | 'disabled' | 'nested'>) => ReactNode);
+};
+export type TreeNodeProps = ChildTreeNode | ParentTreeNode;
+export type ParentNode = Pick<TreeNodeProps, 'id' | 'nested'> & {
+    parentNode?: ParentNode;
+};
+export type OnNodeClick = (node: TreeNodeProps, e: MouseEvent) => void;
+export type TreeCommonProps = {
+    /** Данные для отрисовки */
+    data: TreeNodeProps[];
+    /**
+     * Режим выбора элементов:
+     * <br> - `Single` - одиночный выбор
+     * <br> - `Multi` - множественный выбор
+     * <br> - `undefined` - без выбора
+     */
+    selectionMode?: SelectionMode;
+    /** Обработчик клика по элементу дерева */
+    onNodeClick?: OnNodeClick;
+    /** Состояние для раскрытых элементов */
+    expandedNodes?: TreeNodeId[];
+    /** Колбэк при раскрытии/закрытии элементов */
+    onExpand?(expandedKeys: TreeNodeId[], node: TreeNodeProps): void;
+    /** Состояние для выбранных элементов */
+    selected?: TreeNodeId[] | TreeNodeId;
+    /** Колбэк для асинхронной загрузки данных при раскрытии дерева */
+    onDataLoad?(node: TreeNodeProps): Promise<boolean | unknown>;
+    /** Дополнительные действия для элемента-родителя */
+    parentActions?(node: TreeNodeProps): ItemProps[];
+    /** Дополнительные действия для элемента-потомка */
+    nodeActions?(node: TreeNodeProps): ItemProps[];
+    /**
+     * Флаг отвечающий за отображение иконок у элементов дерева
+     * @default true
+     */
+    showIcons?: boolean;
+    /** Флаг отвечающий за отображение линий вложенности */
+    showLines?: boolean;
+    /**
+     * Размер строк дерева (Figma variant `size`).
+     * @default 'm'
+     */
+    size?: Size;
+    /**
+     * Максимальное число строк заголовка узла до обрезки многоточием.
+     * Значение больше 1 разрешает перенос; строка растёт по высоте.
+     * @default 1
+     */
+    titleMaxLines?: number;
+    /** CSS-класс */
+    className?: string;
+};
+export type TreeView = Omit<TreeCommonProps, 'selected' | 'selectionMode'> & {
+    selectionMode?: never;
+    selected?: never;
+    onSelect?: never;
+};
+export type TreeSingleSelect = Omit<TreeCommonProps, 'selected'> & {
+    selectionMode: 'single';
+    /** Состояние для выбраного элемента */
+    /** <br> - При <strong>selectionMode</strong>=`Single` - принимает строку */
+    selected?: TreeNodeId;
+    /** <br> - При <strong>selectionMode</strong>=`Single` - возвращает строку */
+    onSelect?(selectedKey: TreeNodeId, node: TreeNodeProps): void;
+    showToggle?: boolean;
+};
+export type TreeMultiSelect = Omit<TreeCommonProps, 'selected'> & {
+    selectionMode: 'multiple';
+    /**
+     * Состояние для выбраных элементов:
+     * <br> - При <strong>selectionMode</strong>=`Multiple` - принимает массив строк
+     */
+    selected?: TreeNodeId[];
+    /**
+     * Колбэк при изменении выбраных элементов:
+     * <br> - При <strong>selectionMode</strong>=`Multiple` - возвращает массив строк
+     */
+    onSelect?(selectedKeys: TreeNodeId[], node: TreeNodeProps): void;
+};
+export type TreeBaseProps = TreeView | TreeMultiSelect | TreeSingleSelect;
+/**
+ * Расширение `TreeNodeProps` для внутренних helper'ов поиска/сортировки.
+ *
+ * Когда `title` — функция (а не строка), helper'ы не могут отсортировать или
+ * отфильтровать узел по содержимому JSX. `getTitle` даёт строковый ключ, по
+ * которому можно сравнивать узлы.
+ */
+export type ExtendedTreeNodeProps = TreeNodeProps & {
+    /** Возвращает строковый ключ узла для сравнения/поиска, когда `title` — ReactNode. */
+    getTitle?(): string;
+};
+export type PreloadNodeHandler<TTreeNode extends TreeNodeProps> = (node: TreeNodeProps) => Promise<{
+    preloadedChildren: TTreeNode[];
+    updatedTree: TTreeNode[];
+}>;
+export type SearchableTreeDataLoadResult<TTreeNode extends TreeNodeProps, TRecordValue> = {
+    preloadedChildren: TTreeNode[];
+    updatedTree: TTreeNode[];
+    newTreeItemsRecord: Record<string, TRecordValue>;
+};
+/**
+ * Резолвер выделения для multi-select-режима: получает текущий список выбранных
+ * id, целевой узел и его новое состояние, возвращает diff (`added`/`removed`)
+ * относительно входного `selectedKeys`. Используется для кастомных стратегий
+ * каскадирования.
+ */
+export type SelectHandler = (props: {
+    selectedKeys: string[];
+    node: TreeNodeProps;
+    isSelected: boolean;
+}) => {
+    added: string[];
+    removed: string[];
+};

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};