packages/tree/src/types.ts - develop - bearury/ui-kit-ce

packages/tree/src/types.ts
441 строка16 KB
Pavel Uryadyshev
feat(tree-dnd): реализован новый компонент Tree с поддержкой drag-and-drop
09 июл 2025, 13:07
09 июл 2025, 13:07a06fe68
import {
  TreeItem,
  UseTreeProps,
  UseTreeReturnProps,
  TreeNodeItem,
  UseKeyboardReturnProps,
  TreeGetters,
} from './hooks'
import { TreeSizeType, TreeFocusModeType } from './common'
import { TreeClasses } from './classes'
import {
  ComponentPropsWithRefFix,
  ComponentPropsWithAttributes,
} from '@v-uik/common'
import { TreeComponents } from './defaultComponents'

export type TreeProps<TItem = TreeItem> = UseTreeProps<TItem> &
  TreeBaseProps<TItem> &
  TreeAdditionalProps<TItem> &
  GettersProps<TItem>

export type TreeRenderAdditionalControlData<TItem = TreeItem> =
  TreeBaseComponentProps<TItem>

export type TreeHandlers<TItem = TreeItem> = Pick<
  UseTreeReturnProps<TItem>,
  'toggleCheck' | 'toggleExpand' | 'toggleSelect' | 'toggleSelectRange'
>

export type TreeControlConfig<TItem = TreeItem> = {
  /**
   * Идентификатор узла дерева.
   */
  id: React.Key
  /**
   * Функция, которая отрисовывает компонент дополнительного элемента управления для узла дерева.
   *
   * @param {TreeRenderAdditionalControlData<TItem>} data Объект данных для отрисовки дополнительного элемента управления.
   *
   * @returns Компонент для отрисовки дополнительного элемента управления для узла дерева.
   */
  renderControl?: (
    data: TreeRenderAdditionalControlData<TItem>
  ) => React.ReactNode | null
}

type TreeBaseProps<TItem = TreeItem> = {
  /**
   * Размер дерева.
   *
   * @inner
   */
  size?: TreeSizeType
  /**
   * Флаг заблокированного дерева.
   *
   * @inner
   */
  disabled?: boolean
  /**
   * Флаг для выключения функциональности скрытия/раскрытия.
   *
   * @inner
   */
  disableExpand?: boolean
  /**
   * Флаг для включения функциональности чекбоксов.
   *
   * @inner
   */
  checkable?: boolean
  /**
   * Флаг для включения функциональности выбора узлов дерева.
   *
   * @inner
   */
  selectable?: boolean
  /**
   * Максимальное количество строк, которое будет отображаться в контенте узла дерева. Контент, который не помещается в заданное количество строк
   * будет скрываться за троеточием.
   *
   * @inner
   */
  maxContentLines?: number
  /**
   * Флаг для отображения иконок у узлов дерева.
   *
   * @inner
   */
  showIcons?: boolean
  /**
   * Флаг для отображения путей до элементов дерева.
   *
   * @inner
   */
  showTrails?: boolean
  /**
   * Флаг для включения половины базового отступа для узлов дерева.
   *
   * @inner
   */
  withHalfLevelSpacer?: boolean
  /**
   * Флаг для выключения возможности скрытия/раскрытия узла дерева при клике на узел.
   *
   * @inner
   */
  disableFocusTreeOnItemClick?: boolean

  /**
   * Базовый отступ узлов дерева.
   *
   * @inner
   */
  levelSpacer?: number
  /**
   * Флаг для включения функциональности множественного выбора узлов дерева. Актуально только для `selectMode="strict"` и `selectable="true"`.
   *
   * @inner
   */
  multipleSelect?: boolean
  /**
   * Флаг отключения рамки фокуса вокруг узла при нажатии на кнопку скрытия/раскрытия.
   *
   * @inner
   */
  disableFocusEffectOnExpanderClick?: boolean
  /**
   * Флаг отключения рамки фокуса вокруг узла при нажатии на чекбокс.
   *
   * @inner
   */
  disableFocusEffectOnCheckboxClick?: boolean
  /**
   * Флаг отключения рамки фокуса вокруг узла при нажатии сам узел.
   *
   * @inner
   */
  disableFocusEffectOnClick?: boolean
  /**
   * Режим фокуса на узел дерева. При значении `default` повторный фокус на дерево будет отображать рамку вокруг
   * прошлого сфокусированного узла. При значении `selected` повторный фокус на дерево будет отображать рамку вокруг первого
   * выбранного узла (при `selectable="true"`).
   *
   * @inner
   */
  focusMode?: TreeFocusModeType
  /**
   * Функция обратного вызова, которая срабатывает при нажатии клавиатуры на сфокусированном дереве.
   *
   * @param {React.KeyboardEvent<HTMLUListElement>} event Объект события нажатия клавиатуры.
   * @param {TreeNodeItem<TItem>} node Выбранный узел дерева.
   * @param {TreeHandlers} handlers Объект С функциями для работы с деревом.
   *
   * @returns Если функция возвращает значение, то поведение управления с клавиатуры по умолчанию отключается.
   */
  onTreeKeyDown?: (
    event: React.KeyboardEvent<HTMLUListElement>,
    node: TreeNodeItem<TItem>,
    handlers: TreeHandlers<TItem>
  ) => void | boolean
  /**
   * Функция обратного вызова, которая срабатывает при нажатии кнопки мыши на узел дерева.
   *
   * @param {React.KeyboardEvent<HTMLUListElement>} event Объект события нажатия кнопки мыши.
   * @param {TreeNodeItem<TItem>} node Выбранный узел дерева.
   * @param {TreeHandlers} handlers Объект С функциями для работы с деревом.
   *
   * @returns Если функция возвращает значение, то поведение нажатия кнопки мыши по умолчанию отключается.
   */
  onNodeClick?: (
    event: React.MouseEvent<HTMLLIElement, MouseEvent>,
    node: TreeNodeItem<TItem>,
    handlers: TreeHandlers<TItem>
  ) => void | boolean
  /**
   * Функция для получения HTML-свойств для кнопки скрытия/раскрытия узла дерева.
   *
   * @param {TreeNodeItem<TItem>} node Узел Дерева.
   *
   * @returns HTML-свойства для кнопки скрытия/раскрытия узла дерева.
   */
  getExpandButtonInnerProps?: (
    node: TreeNodeItem<TItem>
  ) => ComponentPropsWithAttributes<ComponentPropsWithRefFix<'button'>>
  /**
   * Функция для получения HTML-свойств для элемента дерева.
   *
   * @param {TreeNodeItem<TItem>} node Узел Дерева.
   *
   * @returns HTML-свойства для элемента дерева.
   */
  getItemInnerProps?: (
    node: TreeNodeItem<TItem>
  ) => ComponentPropsWithAttributes<ComponentPropsWithRefFix<'li'>>
  /**
   * Функция для получения HTML-свойств для группы дочерних узлов дерева.
   *
   * @param {TreeNodeItem<TItem>} node Узел Дерева.
   *
   * @returns HTML-свойства для группы дочерних узлов дерева.
   */
  getNodeGroupInnerProps?: (
    node: TreeNodeItem<TItem>
  ) => ComponentPropsWithAttributes<ComponentPropsWithRefFix<'ul'>>
  /**
   * Функция для получения HTML-свойств для узла дерева.
   *
   * @param {TreeNodeItem<TItem>} node Узел Дерева.
   *
   * @returns HTML-свойства для узла дерева.
   */
  getNodeInnerProps?: (
    node: TreeNodeItem<TItem>
  ) => ComponentPropsWithAttributes<ComponentPropsWithRefFix<'span'>>
  /**
   * Функция для получения HTML-свойств для элемента label вокруг чекбокса.
   *
   * @param {TreeNodeItem<TItem>} node Узел Дерева.
   *
   * @returns HTML-свойства для элемента label вокруг чекбокса.
   */
  getLabelCheckboxInnerProps?: (
    node: TreeNodeItem<TItem>
  ) => ComponentPropsWithAttributes<ComponentPropsWithRefFix<'label'>>
  /**
   * Флаг, или функция обратного вызова, возвращающая флаг, для выключения возможности скрытия/раскрытия узла дерева при клике на узел.
   *
   * @param {React.KeyboardEvent<HTMLUListElement>} event Объект события нажатия кнопки мыши.
   * @param {TreeNodeItem<TItem>} node Целевой узел дерева.
   *
   * @returns Возвращает `true`, если возможность скрытия/раскрытия узла дерева должна быть выключена.
   */
  disableExpandOnClick?:
    | boolean
    | ((
        event: React.MouseEvent<HTMLLIElement, MouseEvent>,
        node: TreeNodeItem<TItem>
      ) => boolean)
  /**
   * Флаг, или функция обратного вызова, возвращающая флаг, для включения возможности отмечать чекбокс при клике на узел.
   *
   * @param {React.KeyboardEvent<HTMLUListElement>} event Объект события нажатия кнопки мыши.
   * @param {TreeNodeItem<TItem>} node Целевой узел дерева.
   *
   * @returns Возвращает `true`, если возможность отмечать чекбокс должна быть включена.
   */
  enableCheckOnClick?:
    | boolean
    | ((
        event: React.MouseEvent<HTMLLIElement, MouseEvent>,
        node: TreeNodeItem<TItem>
      ) => boolean)
  /**
   * Флаг, или функция обратного вызова, возвращающая флаг, для выключения возможности выбора дерева при клике на узел.
   *
   * @param {React.KeyboardEvent<HTMLUListElement>} event Объект события нажатия кнопки мыши.
   * @param {TreeNodeItem<TItem>} node Целевой узел дерева.
   *
   * @returns Возвращает `true`, если возможность выбора узла дерева должна быть выключена.
   */
  disableSelectOnClick?:
    | boolean
    | ((
        event: React.MouseEvent<HTMLLIElement, MouseEvent>,
        node: TreeNodeItem<TItem>
      ) => boolean)
  /**
   * Флаг, или объект с настройками, для включения возможности автоматической прокрутки контейнера с деревом до сфокусированного узла при управлении с клавиатуры.
   *
   * @inner
   */
  enableScrollToFocusedNode?: boolean | ScrollIntoViewOptions
  /**
   * Массив с конфигурацией компонентов, которые будут отрисованы слева от основного контента узла в виде элементов управления.
   *
   * @inner
   */
  suffixControls?: TreeControlConfig[]
  /**
   * Массив с конфигурацией компонентов, которые будут отрисованы справа от основного контента узла в виде элементов управления.
   *
   * @inner
   */
  prefixControls?: TreeControlConfig[]
}

type TreeAdditionalProps<TItem = TreeItem> = ComponentPropsWithRefFix<'ul'> & {
  /**
   * CSS классы компонента.
   *
   * @inner
   */
  classes?: TreeClasses
  /**
   * Свойство для переопределения компонентов `Tree`.
   *
   * @inner
   */
  components?: Partial<TreeComponents<TItem>>
  /**
   * Ссылка на компонент, содержащая функции для управления деревом.
   *
   * @inner
   */
  ref?:
    | ((instance: TreeImperativeHandlersRef<TItem> | null) => void)
    | React.RefObject<TreeImperativeHandlersRef<TItem>>
    | null
}

export type TreeNodeListProps<TItem = TreeItem> = UseTreeReturnProps<TItem> &
  TreeBaseProps<TItem> &
  Pick<UseTreeProps<TItem>, 'selectMode' | 'onLoadData'> & {
    /**
     * Различные характеристики узлов дерева.
     *
     * @inner
     */
    lastParentsOnLevelMap?: LastParentsOnLevelMap
  }

export type TreeRootProps<TItem = TreeItem> = UseTreeReturnProps<TItem> &
  TreeBaseProps<TItem> &
  ComponentPropsWithRefFix<'ul'> &
  Pick<UseTreeProps<TItem>, 'selectMode' | 'checkMode'>

export type TreeBaseComponentProps<TItem = TreeItem> = {
  /**
   * Объект данных узла дерева.
   *
   * @inner
   */
  data: TItem
  /**
   * Глубина вложенности узла дерева.
   *
   * @inner
   */
  depth: number
  /**
   * Размер узла дерева.
   *
   * @inner
   */
  size: TreeSizeType
  /**
   * Флаг заблокированного узла дерева.
   *
   * @inner
   */
  disabled: boolean
  /**
   * Ключ узла дерева.
   *
   * @inner
   */
  nodeKey: React.Key
  /**
   * Флаг раскрытого узла дерева.
   *
   * @inner
   */
  expanded: boolean
  /**
   * Флаг выбранного узла дерева.
   *
   * @inner
   */
  selected: boolean
  /**
   * Состояние загрузки узла дерева.
   *
   * @inner
   */
  loading: boolean
}

export type LastParentsOnLevelMap = Record<
  React.Key,
  {
    /**
     * Глубина вложенности узла дерева.
     *
     * @inner
     */
    depth: undefined | number
    /**
     * Ключ родительского узла дерева.
     *
     * @inner
     */
    parentKey: React.Key | undefined | null
  }
>

export type GettersProps<TItem = TreeItem> = {
  /**
   * Объект функций для получения ключевых данных, необходимых для формирования метаданных узлов дерева.
   *
   * @inner
   */
  getters?: Partial<TreeGetters<TItem>>
}

export type TreeImperativeHandlersRef<TItem = TreeItem> =
  UseKeyboardReturnProps &
    TreeHandlers<TItem> &
    Required<GettersProps<TItem>> &
    Pick<
      UseTreeReturnProps<TItem>,
      | 'getTreeNodeVisibleChildren'
      | 'getParentRootNode'
      | 'getTreeNodeData'
      | 'getFlattenedTree'
    > & {
      /**
       * Получить Ref на HTML-узел дерева.
       *
       * @returns Объект-ссылка на HTML-узел дерева.
       */
      getElementRef: () => React.RefObject<HTMLElement>
      /**
       * Получить узел дерева, который сейчас находится в фокусе.
       *
       * @returns Объект данных узла дерева.
       */
      getFocusItem: () => TreeNodeItem<TItem> | undefined

      /**
       * Функция для прокрутки контейнера с деревом до целевого узла.
       *
       * @inner
       *
       * @param {React.Key} key Ключ узла дерева.
       * @param {ScrollIntoViewOptions} options Параметры прокрутки контейнера к узлу дерева.
       *
       * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
       */
      scrollToNode: (key: React.Key, options?: ScrollIntoViewOptions) => void
    }