@ticatec/topside-elements 1.0.0

package/dist/data_display/tree_view/README_CN.md

@@ -0,0 +1,240 @@
+# 树形视图组件 (TreeView)
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `onContextMenu` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+分层树形组件，用于展示嵌套或平铺层次结构数据（基于 `HierarchyTree`），支持图标替换（如文件夹打开/关闭、文件类型徽章）、按需懒加载、选中项绑定和右键菜单。
+
+## 特性
+
+- **图标替换与定制**：支持 `nodeIcon` Snippet 与 `iconField` 函数，轻松实现文件夹打开（📂）/关闭（📁）状态切换及文件类型图标展示。
+- **层次数据结构**：基于 `HierarchyTree`（来自 `@ticatec/hierarchy-data`）管理层级，从扁平数据（`getKey`/`getParentKey`）自动构建树。
+- **动态展开与深层控制**：支持 `defaultExpandDepth` 初始展开深度与单击箭头切换展开。
+- **选择状态双向绑定**：支持 `bind:activeNode` 响应式绑定选中节点。
+- **异步懒加载**：支持 `lazyLoader` 按需加载子节点，加载过程中自动显示 loading 图标。
+- **右键菜单集成**：支持 `oncontextmenu` 在节点上唤起 `ContextMenu` 右键菜单。
+- **可访问性**：容器带 `role="tree"`，支持 `onfocus`/`onblur` 焦点事件。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import TreeView from "@ticatec/topside-elements/TreeView";
+import {HierarchyTree} from "@ticatec/topside-elements/TreeNodes";
+```
+
+## 属性 (Props)
+
+| 名称 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `tree` | `HierarchyTree<any>` | 必填 | 层次树模型实例，负责维护父子关系与节点索引 |
+| `textField` | `string \| GetText<any>` | 必填 | 节点数据中提取显示文本的字段名或函数 |
+| `iconField` | `string \| GetIcon<any>` | - | 节点图标字段名，或根据节点与展开状态返回图标（图片路径/CSS 类名）的函数 |
+| `nodeIcon` | `Snippet<[NodeIconContext]>` | - | Svelte 5 Snippet，用于完全自定义节点图标（如文件夹打开/关闭）。优先级高于 `iconField` |
+| `chevronIcon` | `Snippet<[ChevronIconContext]>` | - | Svelte 5 Snippet，用于自定义分支展开/折叠箭头；不传则使用默认的 ▾ / ▸ 字符 |
+| `style` | `string` | `''` | 容器内联样式 |
+| `class` | `string` | `''` | 容器附加 CSS 类名 |
+| `lazyLoader` | `TreeLazyLoader \| null` | `null` | 异步懒加载子节点的接口 |
+| `activeNode` | `any` | `null` | 当前选中的节点（支持 `bind:activeNode` 双向绑定） |
+| `defaultExpandDepth` | `number` | `0` | 初始展开深度（0 = 全折叠，1 = 展开根节点，依此类推） |
+| `isVisible` | `NodeVisibleFun` | - | 控制节点可见性的过滤函数 |
+| `onchange` | `OnNodeSelectionChange` | - | 节点选择变化时的回调函数（返回 `false` 可取消本次选择） |
+| `onfocus` | `(event: FocusEvent) => void` | - | 树容器获得焦点时的回调 |
+| `onblur` | `(event: FocusEvent) => void` | - | 树容器失去焦点时的回调 |
+| `oncontextmenu` | `OnContextMenu` | - | 右键菜单事件的回调函数 |
+| `title` | `string` | - | 显示在树顶部的标题，点击标题会触发一次"取消选中"（`activeNode` 置为 `null`） |
+
+## 类型定义
+
+### GetText
+
+```typescript
+type GetText<T> = (item: T) => string;
+```
+
+### GetIcon
+
+```typescript
+type GetIcon<T> = (node: IHierarchyData<T>, expanded: boolean) => string | undefined;
+```
+
+### NodeIconContext / ChevronIconContext
+
+```typescript
+interface NodeIconContext {
+  node: IHierarchyData<any>;
+  expanded: boolean;
+  isBranch: boolean;
+}
+
+interface ChevronIconContext {
+  expanded: boolean;
+  loading: boolean;
+}
+```
+
+### TreeLazyLoader
+
+```typescript
+interface TreeLazyLoader {
+  /** 判断该节点是否是可展开的枝节点 */
+  isBranch: (node: IHierarchyData<any>) => boolean;
+  /** 加载子节点数据（返回纯数据对象数组，由组件内部调用 tree.appendChild 挂载） */
+  load: (node: IHierarchyData<any>) => Promise<Array<any>>;
+}
+```
+
+### OnNodeSelectionChange
+
+```typescript
+type OnNodeSelectionChange = (node: IHierarchyData<any>) => Promise<boolean>;
+```
+
+返回 `false` 可以阻止本次选中；返回 `true` 或 `undefined`/`null` 都会正常选中。
+
+### NodeVisibleFun
+
+```typescript
+type NodeVisibleFun = (node: IHierarchyData<any>) => boolean;
+```
+
+### OnContextMenu
+
+```typescript
+type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+回调收到的是节点的原始数据（`node.data`），不是 `IHierarchyData` 节点本身。
+
+---
+
+## 示例：基础用法
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/topside-elements/TreeView";
+  import {HierarchyTree} from "@ticatec/topside-elements/TreeNodes";
+
+  const flatData = [
+    { id: '1', parentId: null, name: 'Root 1' },
+    { id: '1-1', parentId: '1', name: 'Child 1-1' },
+  ];
+
+  const tree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  tree.setData(flatData);
+
+  let activeNode = $state<any>(null);
+</script>
+
+<TreeView
+  {tree}
+  textField="name"
+  defaultExpandDepth={1}
+  bind:activeNode
+/>
+```
+
+## 示例：实现文件目录树（文件夹打开/关闭 + TypeScript 图标）
+
+通过 `nodeIcon` Snippet，可以根据 `{ node, expanded }` 动态替换图标：
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/topside-elements/TreeView";
+  import {HierarchyTree} from "@ticatec/topside-elements/TreeNodes";
+
+  const fileTreeData = [
+    { id: 'src', parentId: null, name: 'src', isDir: true },
+    { id: 'src/business', parentId: 'src', name: 'business', isDir: true },
+    { id: 'src/business/AccessLog.ts', parentId: 'src/business', name: 'AccessLog.ts', isDir: false, fileType: 'ts' },
+    { id: 'src/business/AccessLogDAO.ts', parentId: 'src/business', name: 'AccessLogDAO.ts', isDir: false, fileType: 'ts' },
+  ];
+
+  const fileTree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  fileTree.setData(fileTreeData);
+
+  let activeFile = $state<any>(null);
+</script>
+
+{#snippet customFileIcon({ node, expanded })}
+  {#if node.data.isDir}
+    <!-- 文件夹图标 (展开: 打开文件夹 📂, 折叠: 关闭文件夹 📁) -->
+    {#if expanded}
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="#EAB308">
+        <path d="M19 20H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v1L19 20z" opacity="0.4"/>
+        <path d="M4 10h17l-2.5 9h-15L4 10z"/>
+      </svg>
+    {:else}
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="#CA8A04">
+        <path d="M10 4H4c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V8c0-1.1-.9-2-2-2h-8l-2-2z"/>
+      </svg>
+    {/if}
+  {:else if node.data.fileType === 'ts'}
+    <!-- TS 文件徽章 -->
+    <span style="background: #3178C6; color: #fff; font-size: 9px; font-weight: 800; padding: 1px 3px; border-radius: 3px;">
+      TS
+    </span>
+  {/if}
+{/snippet}
+
+<TreeView
+  tree={fileTree}
+  textField="name"
+  defaultExpandDepth={3}
+  nodeIcon={customFileIcon}
+  bind:activeNode={activeFile}
+/>
+```
+
+## 示例：异步懒加载
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/topside-elements/TreeView";
+  import {HierarchyTree} from "@ticatec/topside-elements/TreeNodes";
+  import type {IHierarchyData} from "@ticatec/topside-elements/TreeNodes";
+  import type {TreeLazyLoader} from "@ticatec/topside-elements/types";
+
+  const lazyTree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  lazyTree.setData([
+    { id: 'root-1', name: '项目 A（点击展开懒加载）', hasChildren: true }
+  ]);
+
+  const lazyLoader: TreeLazyLoader = {
+    isBranch: (node: IHierarchyData<any>) => Boolean(node.data.hasChildren),
+    load: async (node: IHierarchyData<any>) => {
+      await new Promise((resolve) => setTimeout(resolve, 600));
+      return [
+        { id: `${node.data.id}-sub1`, parentId: node.data.id, name: `${node.data.name} - 模块 1` },
+        { id: `${node.data.id}-sub2`, parentId: node.data.id, name: `${node.data.name} - 模块 2` }
+      ];
+    }
+  };
+</script>
+
+<TreeView tree={lazyTree} textField="name" {lazyLoader} />
+```
+
+---
+
+## 样式定制
+
+树形视图支持以下 CSS 自定义属性：
+
+- `--topside-treeview-chevron-color`：展开/折叠箭头的默认颜色
+- `--topside-treeview-chevron-hover-color`：悬停时箭头的颜色
+- `--topside-treeview-item-bg`：悬停与选中状态的行背景颜色
+- `--topside-treeview-item-selected-color`：选中节点文字的颜色

package/dist/data_display/tree_view/TreeNodeView.svelte

@@ -0,0 +1,227 @@
+<script lang="ts">
+    import iconLoading from "../../assets/loading.gif";
+    import type { OnContextMenu } from "../../overlay/context-menu/ContextMenuItem";
+    import type { IHierarchyData } from "../../lib";
+    import type { Snippet } from 'svelte';
+    import type { GetIcon, NodeIconContext, ChevronIconContext } from './TreeView.svelte';
+
+    type GetText<T> = (item: T) => string;
+
+    interface Props {
+        node: IHierarchyData<any>;
+        textField: string | GetText<any>;
+        iconField?: string | GetIcon<any>;
+        nodeIcon?: Snippet<[NodeIconContext]>;
+        chevronIcon?: Snippet<[ChevronIconContext]>;
+        activeNode: any;
+        expandable: boolean;
+        expanded: boolean;
+        loading?: boolean;
+        ontoggle: () => void;
+        onselect: (node: IHierarchyData<any>) => Promise<void>;
+        oncontextmenu?: OnContextMenu;
+    }
+
+    let {
+        node,
+        textField,
+        iconField,
+        nodeIcon,
+        chevronIcon,
+        activeNode,
+        expandable,
+        expanded,
+        loading = false,
+        ontoggle,
+        onselect,
+        oncontextmenu
+    }: Props = $props();
+
+    let nodeText = $derived(
+        typeof textField == 'string'
+            ? node.data?.[textField] ?? ''
+            : textField(node.data)
+    );
+
+    let nodeIconValue = $derived.by(() => {
+        if (!iconField) return undefined;
+        if (typeof iconField === 'string') {
+            return node.data?.[iconField];
+        }
+        return iconField(node, expanded);
+    });
+
+    let isSelected = $derived(
+        activeNode === node ||
+        activeNode === node.data ||
+        (activeNode != null && typeof activeNode === 'object' && ('data' in activeNode ? activeNode.data === node.data : false))
+    );
+
+    const handleIconClick = async (e: MouseEvent) => {
+        e.stopPropagation();
+        e.preventDefault();
+        await ontoggle();
+    }
+
+    const handleRowClick = async () => {
+        await onselect(node);
+    }
+
+    const handleRowKeyDown = async (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            await handleRowClick();
+        }
+    }
+
+    const handleIconKeyDown = async (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            e.stopPropagation();
+            await ontoggle();
+        }
+    }
+
+    const handleContextMenu = (event: MouseEvent) => {
+        oncontextmenu?.(event, node);
+    }
+</script>
+
+<div class="tree-node" class:expanded style="padding-left: {node.level * 16}px">
+    <div class="node-item" class:selected={isSelected} onclick={handleRowClick} onkeydown={handleRowKeyDown}
+         oncontextmenu={handleContextMenu} role="treeitem" tabindex="0" aria-selected={isSelected}
+         aria-expanded={expandable ? expanded : undefined}>
+
+        <div class="item-chevron">
+            {#if expandable}
+                {#if loading}
+                    <img alt="loading" class="chevron-img" src={iconLoading}/>
+                {:else if chevronIcon}
+                    <span role="button" tabindex="0" aria-label={expanded ? 'Collapse' : 'Expand'} onclick={handleIconClick} onkeydown={handleIconKeyDown} class="chevron-btn">
+                        {@render chevronIcon({ expanded, loading })}
+                    </span>
+                {:else}
+                    <span role="button" tabindex="0" aria-label={expanded ? 'Collapse' : 'Expand'} onclick={handleIconClick} onkeydown={handleIconKeyDown} class="chevron-btn default-arrow">
+                        {expanded ? '▾' : '▸'}
+                    </span>
+                {/if}
+            {:else}
+                <span class="chevron-spacer"></span>
+            {/if}
+        </div>
+
+        {#if nodeIcon}
+            <div class="node-type-icon">
+                {@render nodeIcon({ node, expanded, isBranch: expandable })}
+            </div>
+        {:else if nodeIconValue}
+            <div class="node-type-icon">
+                {#if typeof nodeIconValue === 'string' && (nodeIconValue.startsWith('data:') || nodeIconValue.startsWith('http') || nodeIconValue.startsWith('/') || nodeIconValue.endsWith('.png') || nodeIconValue.endsWith('.svg') || nodeIconValue.endsWith('.gif'))}
+                    <img src={nodeIconValue} alt="" class="type-icon-img" />
+                {:else}
+                    <i class={nodeIconValue}></i>
+                {/if}
+            </div>
+        {/if}
+
+        <span class="item-text">{nodeText}</span>
+    </div>
+</div>
+
+<style>
+    .tree-node {
+        position: relative;
+        width: 100%;
+        padding: 2px 8px 2px 0;
+        box-sizing: border-box;
+
+        .node-item {
+            position: relative;
+            white-space: nowrap;
+            display: flex;
+            height: 30px;
+            box-sizing: border-box;
+            align-items: center;
+            border-radius: 6px;
+            z-index: 5;
+            padding: 0 4px;
+            cursor: pointer;
+
+            .item-chevron {
+                box-sizing: border-box;
+                width: 18px;
+                height: 18px;
+                flex: 0 0 auto;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+
+                .chevron-btn {
+                    cursor: pointer;
+                    font-size: 14px;
+                    line-height: 1;
+                    color: var(--topside-treeview-chevron-color, #6b7280);
+                    user-select: none;
+                    transition: color 0.15s ease;
+
+                    &:hover {
+                        color: var(--topside-treeview-chevron-hover-color, #111827);
+                    }
+                }
+
+                .chevron-spacer {
+                    width: 18px;
+                }
+
+                .chevron-img {
+                    width: 14px;
+                    height: 14px;
+                }
+            }
+
+            .node-type-icon {
+                flex: 0 0 auto;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                margin-left: 2px;
+                margin-right: 6px;
+
+                .type-icon-img {
+                    width: 16px;
+                    height: 16px;
+                    object-fit: contain;
+                }
+            }
+
+            .item-text {
+                display: inline-block;
+                flex: 1 1 auto;
+                box-sizing: border-box;
+                cursor: pointer;
+                overflow: hidden;
+                text-overflow: ellipsis;
+                font-size: 13px;
+                line-height: 1.4;
+            }
+
+            &:hover {
+                background-color: var(--topside-treeview-item-bg, #EEF4FF);
+            }
+
+            &.selected {
+                background-color: var(--topside-treeview-item-bg, #EEF4FF);
+            }
+
+            &.selected .item-text {
+                color: var(--topside-treeview-item-selected-color, #0061FF);
+                font-weight: 600;
+            }
+
+            &:focus-visible {
+                outline: 2px solid var(--topside-primary-border-color, #298DFF);
+                outline-offset: -2px;
+            }
+        }
+    }
+</style>

package/dist/data_display/tree_view/TreeNodeView.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { OnContextMenu } from "../../overlay/context-menu/ContextMenuItem";
+import type { IHierarchyData } from "../../lib";
+import type { Snippet } from 'svelte';
+import type { GetIcon, NodeIconContext, ChevronIconContext } from './TreeView.svelte';
+type GetText<T> = (item: T) => string;
+interface Props {
+    node: IHierarchyData<any>;
+    textField: string | GetText<any>;
+    iconField?: string | GetIcon<any>;
+    nodeIcon?: Snippet<[NodeIconContext]>;
+    chevronIcon?: Snippet<[ChevronIconContext]>;
+    activeNode: any;
+    expandable: boolean;
+    expanded: boolean;
+    loading?: boolean;
+    ontoggle: () => void;
+    onselect: (node: IHierarchyData<any>) => Promise<void>;
+    oncontextmenu?: OnContextMenu;
+}
+declare const TreeNodeView: import("svelte").Component<Props, {}, "">;
+type TreeNodeView = ReturnType<typeof TreeNodeView>;
+export default TreeNodeView;