@falcon-ui/falcon-ui 1.0.0

package/types/components/tree/src/tree.d.ts

@@ -0,0 +1,448 @@
+import type { Component, ComponentPublicInstance, CSSProperties, ExtractPublicPropTypes, PropType } from 'vue';
+import type { TreeClassValue, TreeData, TreeIndex, TreeKey, TreeNode, TreeNodeClassName, TreeNodeClassNameInfo, TreeNodeModel, TreeNodeProps, TreeSemanticDOM, TreeSemanticRecord, TreeShowLine, TreeShowLineOptions, TreeSwitcherIconMode } from './tree-types';
+export interface TreeCheckedKeysObject {
+    checked: TreeKey[];
+    halfChecked: TreeKey[];
+}
+export type TreeCheckedKeys = TreeKey[] | TreeCheckedKeysObject;
+export type TreeLoadData = (node: TreeNode) => Promise<unknown>;
+export type TreeSwitcherLoadingIcon = Component;
+export type TreeFilterTreeNode = (node: TreeNode) => boolean;
+export type TreeAllowDropType = 'prev' | 'inner' | 'next';
+export type TreeNodeDropType = 'before' | 'after' | 'inner' | 'none';
+export type TreeAllowDrag = (node: TreeNode) => boolean;
+export type TreeAllowDrop = (draggingNode: TreeNode, dropNode: TreeNode, type: TreeAllowDropType) => boolean;
+export type TreeInteractionEvent = MouseEvent | KeyboardEvent;
+export type TreeScrollAlign = 'top' | 'bottom' | 'auto';
+export interface TreeScrollToOptions {
+    key: TreeKey;
+    align?: TreeScrollAlign;
+    offset?: number;
+}
+export interface TreeExpose {
+    scrollTo: (options: TreeScrollToOptions) => void;
+}
+export interface TreeInteractionStateConfig {
+    disabledKeys?: TreeKey[];
+    unselectableKeys?: TreeKey[];
+    disabledCheckboxKeys?: TreeKey[];
+    hiddenCheckboxKeys?: TreeKey[];
+}
+export interface TreeInteractionStateSets {
+    disabledKeySet: Set<TreeKey>;
+    unselectableKeySet: Set<TreeKey>;
+    disabledCheckboxKeySet: Set<TreeKey>;
+    hiddenCheckboxKeySet: Set<TreeKey>;
+}
+/**
+ * Tree 语义化样式回调接收当前组件公开 props 快照。
+ */
+export interface TreeSemanticInfo {
+    props: TreeProps;
+}
+interface TreeClassNamesResolver {
+    (info: TreeSemanticInfo): TreeSemanticRecord<TreeClassValue>;
+}
+interface TreeStylesResolver {
+    (info: TreeSemanticInfo): TreeSemanticRecord<CSSProperties>;
+}
+export type TreeClassNames = TreeSemanticRecord<TreeClassValue> | TreeClassNamesResolver;
+export type TreeStyles = TreeSemanticRecord<CSSProperties> | TreeStylesResolver;
+/**
+ * 首版使用稳定的默认字段映射，保证常规树数据可直接渲染。
+ */
+export declare const treeNodePropsDefaults: Required<TreeNodeProps>;
+/**
+ * 阶段 3 在基础树结构之外，正式开放默认展开与受控展开相关契约。
+ */
+export declare const treeProps: {
+    readonly data: {
+        readonly type: PropType<TreeData[]>;
+        readonly default: () => never[];
+    };
+    readonly showLine: {
+        readonly type: PropType<TreeShowLine>;
+        readonly default: false;
+    };
+    readonly switcherIcon: {
+        readonly type: PropType<TreeSwitcherIconMode>;
+        readonly default: "arrow";
+    };
+    readonly switcherLoadingIcon: {
+        readonly type: PropType<TreeSwitcherLoadingIcon>;
+        readonly default: import("vue").DefineComponent<{}, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+    };
+    readonly selectable: {
+        readonly type: BooleanConstructor;
+        readonly default: true;
+    };
+    readonly multiple: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly checkable: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly checkStrictly: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly props: {
+        readonly type: PropType<TreeNodeProps>;
+        readonly default: () => {
+            label: string;
+            children: string;
+            isLeaf: string;
+        };
+    };
+    readonly classNames: {
+        readonly type: PropType<TreeClassNames>;
+    };
+    readonly nodeClassName: {
+        readonly type: PropType<TreeNodeClassName>;
+    };
+    readonly styles: {
+        readonly type: PropType<TreeStyles>;
+    };
+    readonly defaultExpandAll: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly defaultExpandedKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly expandedKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly autoExpandParent: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly defaultExpandParent: {
+        readonly type: BooleanConstructor;
+        readonly default: true;
+    };
+    readonly accordion: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly defaultSelectedKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly selectedKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly disabledKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly unselectableKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly defaultCheckedKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly checkedKeys: {
+        readonly type: PropType<TreeCheckedKeys>;
+    };
+    readonly disabledCheckboxKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly hiddenCheckboxKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly loadData: {
+        readonly type: PropType<TreeLoadData>;
+    };
+    readonly loadedKeys: {
+        readonly type: PropType<TreeKey[]>;
+    };
+    readonly draggable: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+    readonly allowDrag: {
+        readonly type: PropType<TreeAllowDrag>;
+    };
+    readonly allowDrop: {
+        readonly type: PropType<TreeAllowDrop>;
+    };
+    readonly filterTreeNode: {
+        readonly type: PropType<TreeFilterTreeNode>;
+    };
+};
+export type TreeProps = ExtractPublicPropTypes<typeof treeProps>;
+/**
+ * 树节点展开事件统一返回本次节点状态与当前源展开键集合。
+ */
+export interface TreeExpandEvent {
+    expanded: boolean;
+    node: TreeData;
+    key: TreeKey;
+    expandedKeys: TreeKey[];
+}
+/**
+ * 树节点选中事件统一返回当前节点结果与最新选中集合。
+ */
+export interface TreeSelectEvent {
+    selected: boolean;
+    node: TreeNode;
+    selectedNodes: TreeNode[];
+    key: TreeKey;
+    event: TreeInteractionEvent;
+}
+/**
+ * 树节点勾选事件统一返回当前节点结果与最新勾选集合。
+ */
+export interface TreeCheckEvent {
+    checked: boolean;
+    node: TreeNode;
+    checkedNodes: TreeNode[];
+    halfCheckedKeys: TreeKey[];
+    key: TreeKey;
+    event: TreeInteractionEvent;
+}
+/**
+ * 树节点异步加载完成事件统一返回当前节点与最新已加载键集合。
+ */
+export interface TreeLoadEvent {
+    node: TreeNode;
+    key: TreeKey;
+    loadedKeys: TreeKey[];
+}
+/**
+ * 节点组件实例通过 Vue public instance 向外暴露。
+ */
+export type TreeNodeInstance = ComponentPublicInstance | null;
+export type TreeExpandedNode = TreeNode & {
+    expanded: boolean;
+};
+/**
+ * `node-click` 事件固定采用 Element Plus 风格的多参数出参。
+ */
+export type TreeNodeClickArgs = [
+    data: TreeData,
+    node: TreeNode,
+    component: TreeNodeInstance,
+    event: TreeInteractionEvent
+];
+/**
+ * `dblclick` 事件固定采用 Element Plus 风格的多参数出参。
+ */
+export type TreeNodeDblclickArgs = [
+    data: TreeData,
+    node: TreeNode,
+    component: TreeNodeInstance,
+    event: MouseEvent
+];
+export type TreeNodeRightClickArgs = [
+    data: TreeData,
+    node: TreeNode,
+    component: TreeNodeInstance,
+    event: MouseEvent
+];
+/**
+ * `node-expand` / `node-collapse` 事件固定采用 Element Plus 风格的多参数出参。
+ */
+export type TreeNodeToggleArgs = [
+    data: TreeData,
+    node: TreeExpandedNode,
+    instance: TreeNodeInstance
+];
+/**
+ * `select` 事件固定采用双参数出参。
+ */
+export type TreeSelectArgs = [selectedKeys: TreeKey[], event: TreeSelectEvent];
+/**
+ * `check` 事件固定采用双参数出参。
+ */
+export type TreeCheckArgs = [checkedKeys: TreeCheckedKeys, event: TreeCheckEvent];
+/**
+ * `load` 事件固定采用双参数出参。
+ */
+export type TreeLoadArgs = [loadedKeys: TreeKey[], event: TreeLoadEvent];
+/**
+ * `node-drag-start` 事件对齐 Element Plus 多参数出参。
+ */
+export type TreeNodeDragStartArgs = [node: TreeNode, event: DragEvent];
+/**
+ * `node-drag-enter` / `node-drag-over` / `node-drag-leave` 事件对齐 Element Plus。
+ */
+export type TreeNodeDragTargetArgs = [draggingNode: TreeNode, dropNode: TreeNode, event: DragEvent];
+/**
+ * `node-drag-end` 事件对齐 Element Plus。
+ */
+export type TreeNodeDragEndArgs = [
+    draggingNode: TreeNode,
+    dropNode: TreeNode | null,
+    dropType: TreeNodeDropType,
+    event: DragEvent
+];
+/**
+ * `node-drop` 仅在非 none 落点触发。
+ */
+export type TreeNodeDropArgs = [
+    draggingNode: TreeNode,
+    dropNode: TreeNode,
+    dropType: Exclude<TreeNodeDropType, 'none'>,
+    event: DragEvent
+];
+/**
+ * 判断当前值是否为树组件允许使用的节点键类型。
+ */
+export declare const isTreeKey: (value: unknown) => value is TreeKey;
+/**
+ * 判断当前值是否为 `{ checked, halfChecked }` 形态的勾选结果对象。
+ */
+export declare const isTreeCheckedKeysObject: (value: unknown) => value is TreeCheckedKeysObject;
+/**
+ * 判断当前值是否满足树组件允许的勾选结果输入形态。
+ */
+export declare const isTreeCheckedKeys: (value: unknown) => value is TreeCheckedKeys;
+/**
+ * 阶段 3 正式开放展开状态双向同步与展开事件。
+ */
+export declare const treeEmits: {
+    /**
+     * 请求外部同步当前源展开键集合。
+     */
+    readonly 'update:expandedKeys': (value: TreeKey[]) => boolean;
+    /**
+     * 请求外部同步当前源选中键集合。
+     */
+    readonly 'update:selectedKeys': (value: TreeKey[]) => boolean;
+    /**
+     * 请求外部同步当前源勾选键集合。
+     */
+    readonly 'update:checkedKeys': (value: TreeCheckedKeys) => boolean;
+    /**
+     * 请求外部同步当前已完成异步加载的节点键集合。
+     */
+    readonly 'update:loadedKeys': (value: TreeKey[]) => boolean;
+    /**
+     * 节点展开状态切换后抛出当前节点的展开结果。
+     */
+    readonly expand: (event: TreeExpandEvent) => boolean;
+    /**
+     * 节点被点击时抛出节点数据、节点对象、组件实例与鼠标事件。
+     */
+    readonly 'node-click': (data: TreeData, node: TreeNode, component: TreeNodeInstance, event: TreeInteractionEvent) => boolean;
+    /**
+     * 节点内容区被双击时抛出节点数据、节点对象、组件实例与鼠标事件。
+     */
+    readonly dblclick: (data: TreeData, node: TreeNode, component: TreeNodeInstance, event: MouseEvent) => boolean;
+    readonly 'right-click': (data: TreeData, node: TreeNode, component: TreeNodeInstance, event: MouseEvent) => boolean;
+    /**
+     * 节点被选中或取消选中时抛出最新选中结果。
+     */
+    readonly select: (selectedKeys: TreeKey[], event: TreeSelectEvent) => boolean;
+    /**
+     * 节点复选框勾选状态切换后抛出当前勾选结果。
+     */
+    readonly check: (checkedKeys: TreeCheckedKeys, event: TreeCheckEvent) => boolean;
+    /**
+     * 节点异步加载完成后抛出最新已加载结果。
+     */
+    readonly load: (loadedKeys: TreeKey[], event: TreeLoadEvent) => boolean;
+    /**
+     * 节点被用户展开时抛出切换后的节点对象与组件实例。
+     */
+    readonly 'node-expand': (data: TreeData, node: TreeExpandedNode, instance: TreeNodeInstance) => boolean;
+    /**
+     * 节点被用户收起时抛出切换后的节点对象与组件实例。
+     */
+    readonly 'node-collapse': (data: TreeData, node: TreeExpandedNode, instance: TreeNodeInstance) => boolean;
+    /**
+     * 节点开始拖拽时抛出拖拽源节点。
+     */
+    readonly 'node-drag-start': (node: TreeNode, event: DragEvent) => boolean;
+    /**
+     * 拖拽进入节点落点区域时抛出当前拖拽源和目标节点。
+     */
+    readonly 'node-drag-enter': (draggingNode: TreeNode, dropNode: TreeNode, event: DragEvent) => boolean;
+    /**
+     * 拖拽悬停在节点落点区域时抛出当前拖拽源和目标节点。
+     */
+    readonly 'node-drag-over': (draggingNode: TreeNode, dropNode: TreeNode, event: DragEvent) => boolean;
+    /**
+     * 拖拽离开节点落点区域时抛出当前拖拽源和目标节点。
+     */
+    readonly 'node-drag-leave': (draggingNode: TreeNode, dropNode: TreeNode, event: DragEvent) => boolean;
+    /**
+     * 节点拖拽结束时抛出拖拽源、目标和投放类型。
+     */
+    readonly 'node-drag-end': (draggingNode: TreeNode, dropNode: TreeNode | null, dropType: TreeNodeDropType, event: DragEvent) => boolean;
+    /**
+     * 节点成功投放时抛出拖拽源、目标和投放类型。
+     */
+    readonly 'node-drop': (draggingNode: TreeNode, dropNode: TreeNode, dropType: "inner" | "before" | "after", event: DragEvent) => boolean;
+};
+export type TreeEmits = typeof treeEmits;
+/**
+ * 将用户传入的部分映射与默认映射合并，统一生成内部字段配置。
+ */
+export declare const resolveTreeNodePropsConfig: (propsConfig?: TreeNodeProps) => Required<TreeNodeProps>;
+/**
+ * 将单个原始节点转换为内部标准化节点。
+ */
+export declare const normalizeTreeNode: (rawNode: TreeData, level: number, propsConfig?: TreeNodeProps, interactionStateSets?: TreeInteractionStateSets, parent?: TreeNodeModel | null, isLastSibling?: boolean, lineTrackEnds?: boolean[]) => TreeNodeModel;
+/**
+ * 在递归树结构之外，同时建立扁平索引，供后续阶段复用。
+ */
+export declare const buildTreeIndex: (data: TreeData[], propsConfig?: TreeNodeProps, interactionStateConfig?: TreeInteractionStateConfig) => TreeIndex;
+/**
+ * 过滤无效、重复或已从树结构中移除的展开键。
+ */
+export declare const filterTreeExpandedKeys: (keys: TreeKey[] | undefined, keyNodeMap: Map<TreeKey, TreeNodeModel>) => TreeKey[];
+export declare const normalizeAccordionExpandedKeys: (expandedKeys: TreeKey[], parentKeyMap: Map<TreeKey, TreeKey | null>) => TreeKey[];
+/**
+ * 过滤无效、重复或已从树结构中移除的选中键。
+ */
+export declare const filterTreeSelectedKeys: (keys: TreeKey[] | undefined, keyNodeMap: Map<TreeKey, TreeNodeModel>) => TreeKey[];
+/**
+ * 过滤无效、重复或已从树结构中移除的勾选键。
+ */
+export declare const filterTreeCheckedKeys: (keys: TreeKey[] | undefined, keyNodeMap: Map<TreeKey, TreeNodeModel>) => TreeKey[];
+/**
+ * 过滤无效、重复或已从树结构中移除的异步加载完成键。
+ */
+export declare const filterTreeLoadedKeys: (keys: TreeKey[] | undefined, keyNodeMap: Map<TreeKey, TreeNodeModel>) => TreeKey[];
+/**
+ * 清理集合中已经失效的节点键，供非受控状态在数据更新后裁剪缓存。
+ */
+export declare const pruneTreeKeySet: (keys: Set<TreeKey>, keyNodeMap: Map<TreeKey, TreeNodeModel>) => Set<TreeKey>;
+/**
+ * 收集当前树中所有可展开节点的 key，供 `defaultExpandAll` 初始化使用。
+ */
+export declare const collectExpandableTreeKeys: (nodes: TreeNodeModel[]) => TreeKey[];
+/**
+ * 基于父节点索引补齐源展开键的全部祖先节点键。
+ */
+export declare const collectAncestorExpandedKeys: (sourceExpandedKeys: TreeKey[], parentKeyMap: Map<TreeKey, TreeKey | null>) => Set<TreeKey>;
+/**
+ * 根据源展开键生成最终用于渲染的展开集合，可按需补齐祖先节点。
+ */
+export declare const createEffectiveExpandedKeySet: ({ sourceExpandedKeys, parentKeyMap, includeAncestorKeys, accordion }: {
+    sourceExpandedKeys: TreeKey[];
+    parentKeyMap: Map<TreeKey, TreeKey | null>;
+    includeAncestorKeys: boolean;
+    accordion?: boolean;
+}) => Set<TreeKey>;
+interface CreateTreeEventNodeOptions {
+    node: TreeNodeModel;
+    resolveExpanded?: undefined;
+}
+interface CreateExpandedTreeEventNodeOptions {
+    node: TreeNodeModel;
+    resolveExpanded: (nodeKey: TreeKey) => boolean;
+}
+/**
+ * 根据内部节点模型构造对外事件节点对象，并按需附带展开状态。
+ */
+export declare function createTreeEventNode(options: CreateExpandedTreeEventNodeOptions): TreeExpandedNode;
+export declare function createTreeEventNode(options: CreateTreeEventNodeOptions): TreeNode;
+/**
+ * 统一解析对象形式和工厂函数形式的语义化记录。
+ */
+export declare const resolveTreeSemanticRecord: <T>(source: TreeSemanticRecord<T> | ((info: TreeSemanticInfo) => TreeSemanticRecord<T>) | undefined, info: TreeSemanticInfo) => TreeSemanticRecord<T>;
+export type { TreeClassValue, TreeData, TreeIndex, TreeKey, TreeNode, TreeNodeClassName, TreeNodeClassNameInfo, TreeNodeModel, TreeNodeProps, TreeSemanticDOM, TreeSemanticRecord, TreeShowLine, TreeShowLineOptions, TreeSwitcherIconMode };