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

packages/tree-dnd/src/types.ts
264 строки8 KB
Урядышев Павел Александрович
refactor(tree-dnd): исправления после дизайн-ревью
09 июл 2025, 18:02
09 июл 2025, 18:02f866ce9
import { DataRef } from '@dnd-kit/core'
import {
  TreeItem as PvTreeItem,
  TreeProps as PvTreeProps,
  TreeImperativeHandlersRef as PvTreeImperativeHandlersRef,
  TreeNodeItem as PvTreeNodeItem,
  TreeHandlers,
} from '@v-uik/tree'
import { TreeClasses } from './classes'
import { TreeComponents } from './defaultComponents'
import { TreeGetters, TreeDragModeType } from './common'
import { UseDraggableCursorProps } from './hooks'

export type TreeNodeDragEvent = Event

export type TreeNodeItemMetaDnd = {
  /**
   * Ключ родительского узла дерева.
   *
   * @inner
   */
  parentKey?: React.Key
  /**
   * Глубина узла дерева.
   *
   * @inner
   */
  depth?: number
  /**
   * Индекс узла в плоском дереве.
   *
   * @inner
   */
  index?: number
  /**
   * Массив ключей всех родительских узлов дерева.
   *
   * @inner
   */
  allParentKeys?: React.Key[]
}

export type TreeNodeItem<TItem = TreeItem> = Omit<
  PvTreeNodeItem<TItem>,
  'children'
> & {
  /**
   * Метаданные о перетаскивании узла дерева.
   *
   * @inner
   */
  $metaDnd: TreeNodeItemMetaDnd
  /**
   * Массив дочерних узлов дерева.
   *
   * @inner
   */
  children?: TreeNodeItem<TItem>[]
}

export type TreeNodeDragCollisionData<TItem = TreeItem> = {
  /**
   * Объект данных для узла дерева, в который перетаскивается узел.
   *
   * @inner
   */
  nodeDropTarget?: TreeNodeItem<TItem>
  /**
   * Кортеж узлов дерева, между которыми перетаскивается узел.
   *
   * @inner
   */
  nodesBetween?: [
    TreeNodeItem<TItem> | undefined,
    TreeNodeItem<TItem> | undefined
  ]
  /**
   * Ключ зоны, в которую перетаскивается узел.
   *
   * @inner
   */
  dropzoneKey?: React.Key
  /**
   * Является ли зона, в которую перетаскивается узел, верхней частью узла.
   *
   * @inner
   */
  isDropZoneUpper?: boolean
  /**
   * Является ли зона, в которую перетаскивается узел, нижней частью узла.
   *
   * @inner
   */
  isDropZoneLower?: boolean
  /**
   * Является ли зона, в которую перетаскивается узел, центральной частью узла.
   *
   * @inner
   */
  isDropZoneTarget?: boolean
  /**
   * Ключ узла дерева, к которой принадлежит зона для вложения.
   */
  dropzoneOwnerNodeKey?: React.Key
}

export type TreeItem = Omit<PvTreeItem, 'children'> & {
  /**
   * Флаг для включения функциональности перетаскивания узлов дерева.
   *
   * @inner
   */
  draggable?: boolean
  /**
   * Флаг для включения функциональности вложения узлов дерева.
   *
   * @inner
   */
  dropTarget?: boolean
  /**
   * Массив дочерних узлов.
   *
   * @inner
   */
  children?: TreeItem[]
}

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

export type TreeImperativeHandlersRef<TItem = TreeItem> = Omit<
  PvTreeImperativeHandlersRef<TItem>,
  'getters'
> &
  Required<GettersProps<TItem>>

export type TreeProps<TItem = TreeItem> = Omit<
  PvTreeProps<TItem>,
  'components' | 'classes' | 'getters' | 'dataSource'
> &
  GettersProps<TItem> &
  UseDraggableCursorProps & {
    /**
     * Свойство для переопределения компонентов `Tree`.
     *
     * @inner
     */
    components?: Partial<TreeComponents<TItem>>
    /**
     * CSS классы компонента.
     *
     * @inner
     */
    classes?: TreeClasses
    /**
     * Массив данных для узлов дерева.
     *
     * @inner
     */
    dataSource?: TItem[]
    /**
     * Массив данных для узлов дерева по умолчанию.
     *
     * @inner
     */
    defaultDataSource?: TItem[]
    /**
     * Флаг для выключения функциональности перетаскивания узлов дерева.
     *
     * @inner
     */
    disableDragging?: boolean
    /**
     * Время отклика для старта перетаскивания узлов дерева в миллисекундах.
     *
     * @inner
     */
    dragDelay?: number
    /**
     * Режим перетаскивания узла дерева, где `button` - режим перетаскивания по нажатию кнопки, `node` - режим перетаскивания по нажатию на узел дерева.
     * По умолчанию значение равно `button`.
     *
     * @inner
     */
    dragMode?: TreeDragModeType
    /**
     * Функция обратного вызова, которая срабатывает при изменении массива данных.
     *
     * @param {TItem[]} dataSource Преобразованный массив данных.
     *
     * @returns
     */
    onDataSourceChange?: (dataSource: TItem[]) => void
    /**
     * Функция обратного вызова, которая срабатывает во время старта перетаскивания узла дерева.
     *
     * @param {TreeNodeDragEvent} event Объект события перетаскивания узла.
     * @param {TreeNodeItem<TItem>} node Перетаскиваемый узел дерева.
     * @param {TreeHandlers} handlers Объект С функциями для работы с деревом.
     */
    onNodeDragStart?: (
      event: TreeNodeDragEvent,
      node: TreeNodeItem<TItem>,
      collision: TreeNodeDragCollisionData<TItem>,
      handlers: TreeHandlers<TItem>
    ) => void
    /**
     * Функция обратного вызова, которая срабатывает во время перемещения узла между зонами вложения.
     *
     * @param {TreeNodeDragEvent} event Объект события перетаскивания узла.
     * @param {TreeNodeItem<TItem>} node Перетаскиваемый узел дерева.
     * @param {TreeNodeDragCollisionData<TItem>} collision Объект данных с коллизиями перемещения перетаскиваемого узла дерева.
     * @param {TreeHandlers} handlers Объект с функциями для работы с деревом.
     */
    onNodeDragOver?: (
      event: TreeNodeDragEvent,
      node: TreeNodeItem<TItem>,
      collision: TreeNodeDragCollisionData<TItem>,
      handlers: TreeHandlers<TItem>
    ) => void

    /**
     * Функция обратного вызова, которая срабатывает во время окончания перетаскивания узла дерева.
     *
     * @param {TreeNodeDragEvent} event Объект события перетаскивания узла.
     * @param {TreeNodeItem<TItem>} node Перетаскиваемый узел дерева.
     * @param {TreeNodeDragCollisionData<TItem>} collision Объект данных с коллизиями перемещения перетаскиваемого узла дерева.
     * @param {TreeHandlers} handlers Объект с функциями для работы с деревом.
     */
    onNodeDragEnd?: (
      event: TreeNodeDragEvent,
      node: TreeNodeItem<TItem>,
      collision: TreeNodeDragCollisionData<TItem>,
      handlers: TreeHandlers<TItem>
    ) => void
  }

export type CollisionData = {
  isBetweenDropZone?: boolean
  isDropZoneLower?: boolean
  isDropZoneUpper?: boolean
  dropzoneOwnerNodeKey?: React.Key | null
  overKey?: React.Key | null
  dropTargetKey?: React.Key | null
  nodeKey?: React.Key | null
  nodesBetween?: { key: React.Key; depth: number }[]
  isNodeBetweenParents?: boolean
}

export type CollisionDropTargetContainerData = {
  droppableContainer: {
    data: DataRef<CollisionData>
  }
}

export type TreeSensorContext = React.MutableRefObject<{
  dataSource: TreeItem[]
}>