@manohub/app-kit 0.1.0

package/dist/components/app-tree.d.ts

@@ -0,0 +1,273 @@
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+/** 树节点：至少要有主键与标签，子节点字段名可用 `childrenKey` 指定 */
+export interface AppTreeNode {
+    [key: string]: unknown;
+}
+/**
+ * 树（**自建**，不封装 farris）。
+ *
+ * ## 视觉与几何规范来源
+ *
+ * 对齐 `@aihub/theme` 的 Tree（`src/components/tree.css` 令牌 + `playground/components/tree.html` 标记）：
+ * 节点行高 30（紧凑档 28）、圆角 6（`--ui-radius-control`）、字号 13、滑过 Ne11、点击瞬态 #F4F5F9、
+ * 选中 Au02 底 + Th03 字、箭头 8px（收起态转 −90°）、缩进 = 基础内距 8 + level × 步进 10（**无上限**）。
+ *
+ * 两处与主题包的**有意差异**（不改视觉，只改承载方式）：
+ * 1. **缩进步进由 CSS 变量承载**：主题包用 typed `attr(data-level type(<number>))` 一步算出；
+ *    为兼容尚无该能力的引擎，本组件同时下发 `data-level`（数据、供 CSS/测试钩子）与
+ *    `--ak-tree-level`（公式仍在 CSS 内，见 components.css）。不用行内 paddingLeft —— 那样
+ *    步进值就散落在 JS 里，改了令牌对不上。
+ * 2. **交互分工**：主题包的约定是「点行即展开/收拢，选中由行内选择件驱动」；本组件没有内嵌选择件，
+ *    故沿用「点箭头展开/收拢、点行选中」（`onSelect`）—— 消费方靠 `onSelect` 拿选中，展开态受控。
+ *
+ * ## 为什么自建（对照计划登记的退路）
+ *
+ * farris `FTreeView` 实测结论：① 是列模板式网格（节点内容可用 `columnTemplate` 承载）；
+ * ② **只在挂载时填充一次可见行，data 变化不刷新**（仓内唯一的适配器
+ * `apps/skill/src/features/skill/farris-file-tree.tsx` 正是用 `key` 强制重挂绕行）；
+ * ③ 层级缩进不可控、节点图标走 farris 图标字体类。
+ *
+ * 而本组件的硬需求是「数据更新时**不丢**用户已展开的节点 / 滚动位置 / 焦点」——
+ * 与 ② 直接冲突（重挂必然丢展开态）；缩进又要按设计稿精确控制（③）。因此按计划
+ * 登记的退路改为自建：契约完整（含受控展开态）、零 farris 耦合、可在无浏览器环境测试。
+ *
+ * ## 与数据变化的关系
+ *
+ * 自建后**不需要**「nodes 变就重建」这种逃生舱：渲染直接跟随 `nodes`，
+ * 展开态由 `expandedKeys`（受控）或内部状态（非受控）持有，数据刷新不会改变展开态。
+ * `treeKey` 仅作为极端场景的强制重挂出口保留。
+ *
+ * @example 受控展开 + 计数徽标
+ * <AppTree nodes={treeNodes.value} rowKey="id" labelKey="name"
+ *   selected={selectedId.value} onSelect={(n) => select(n.id)}
+ *   expandedKeys={expandedKeys.value} onExpandChange={(k) => (expandedKeys.value = k)}
+ *   renderNode={(n) => <AppBadge>{countOfDomain(n.id)}</AppBadge>} />
+ */
+export declare const AppTree: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    nodes: {
+        type: PropType<AppTreeNode[]>;
+        required: true;
+    };
+    /** 节点主键：字段名或取值函数 */
+    rowKey: {
+        type: PropType<string | ((node: AppTreeNode) => string)>;
+        required: true;
+    };
+    /** 标签字段名（默认 'label'） */
+    labelKey: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 子节点字段名（默认 'children'） */
+    childrenKey: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 受控选中（行主键值） */
+    selected: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onSelect: {
+        type: PropType<(node: AppTreeNode) => void>;
+        default: undefined;
+    };
+    /** 节点附加内容（计数徽标等），渲染在标签之后 */
+    renderNode: {
+        type: PropType<(node: AppTreeNode) => unknown>;
+        default: undefined;
+    };
+    /** 尺寸档：md 舒适（行高 30）/ sm 紧凑（行高 28），与主题包 Tree 的 M/S 档一致 */
+    size: {
+        type: PropType<"md" | "sm">;
+        default: string;
+    };
+    /** 受控展开集（传了就完全受控，内部不再自持） */
+    expandedKeys: {
+        type: PropType<string[]>;
+        default: undefined;
+    };
+    /** 非受控展开初值 */
+    defaultExpandedKeys: {
+        type: PropType<string[]>;
+        default: () => never[];
+    };
+    onExpandChange: {
+        type: PropType<(keys: string[]) => void>;
+        default: undefined;
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 空态文案 */
+    empty: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 空态操作按钮（如「新建」）；与 `onEmptyAction` 同时传才渲染 */
+    emptyActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onEmptyAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    /**
+     * 错误态（truthy 即触发）。
+     *
+     * **构造器顺序同 `AppTable.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
+     * 空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。
+     *
+     * 有它之前，消费方只能把错误文案塞进 `empty`：错误被渲染成空态语义（无错误插画、无重试入口），
+     * 用户看不出「是没数据还是加载挂了」。
+     */
+    error: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    /** 错误态标题（默认「加载失败」）；字符串错误原文会自动作为副文案显示 */
+    errorTitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 错误态操作按钮（如「重试」）；与 `onErrorAction` 同时传才渲染 */
+    errorActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onErrorAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    /** 强制重挂逃生舱（正常数据刷新不需要它） */
+    treeKey: {
+        type: PropType<string | number>;
+        default: undefined;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    nodes: {
+        type: PropType<AppTreeNode[]>;
+        required: true;
+    };
+    /** 节点主键：字段名或取值函数 */
+    rowKey: {
+        type: PropType<string | ((node: AppTreeNode) => string)>;
+        required: true;
+    };
+    /** 标签字段名（默认 'label'） */
+    labelKey: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 子节点字段名（默认 'children'） */
+    childrenKey: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 受控选中（行主键值） */
+    selected: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onSelect: {
+        type: PropType<(node: AppTreeNode) => void>;
+        default: undefined;
+    };
+    /** 节点附加内容（计数徽标等），渲染在标签之后 */
+    renderNode: {
+        type: PropType<(node: AppTreeNode) => unknown>;
+        default: undefined;
+    };
+    /** 尺寸档：md 舒适（行高 30）/ sm 紧凑（行高 28），与主题包 Tree 的 M/S 档一致 */
+    size: {
+        type: PropType<"md" | "sm">;
+        default: string;
+    };
+    /** 受控展开集（传了就完全受控，内部不再自持） */
+    expandedKeys: {
+        type: PropType<string[]>;
+        default: undefined;
+    };
+    /** 非受控展开初值 */
+    defaultExpandedKeys: {
+        type: PropType<string[]>;
+        default: () => never[];
+    };
+    onExpandChange: {
+        type: PropType<(keys: string[]) => void>;
+        default: undefined;
+    };
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 空态文案 */
+    empty: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 空态操作按钮（如「新建」）；与 `onEmptyAction` 同时传才渲染 */
+    emptyActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onEmptyAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    /**
+     * 错误态（truthy 即触发）。
+     *
+     * **构造器顺序同 `AppTable.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
+     * 空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。
+     *
+     * 有它之前，消费方只能把错误文案塞进 `empty`：错误被渲染成空态语义（无错误插画、无重试入口），
+     * 用户看不出「是没数据还是加载挂了」。
+     */
+    error: {
+        type: PropType<any>;
+        default: undefined;
+    };
+    /** 错误态标题（默认「加载失败」）；字符串错误原文会自动作为副文案显示 */
+    errorTitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 错误态操作按钮（如「重试」）；与 `onErrorAction` 同时传才渲染 */
+    errorActionText: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    onErrorAction: {
+        type: PropType<() => void>;
+        default: undefined;
+    };
+    /** 强制重挂逃生舱（正常数据刷新不需要它） */
+    treeKey: {
+        type: PropType<string | number>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    onSelect: (node: AppTreeNode) => void;
+    size: "sm" | "md";
+    loading: boolean;
+    error: any;
+    empty: string;
+    errorTitle: string;
+    emptyActionText: string;
+    onEmptyAction: () => void;
+    errorActionText: string;
+    onErrorAction: () => void;
+    labelKey: string;
+    childrenKey: string;
+    selected: string;
+    renderNode: (node: AppTreeNode) => unknown;
+    expandedKeys: string[];
+    defaultExpandedKeys: string[];
+    onExpandChange: (keys: string[]) => void;
+    treeKey: string | number;
+}, SlotsType<{
+    default?: () => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/components/app-tree.js

@@ -0,0 +1,222 @@
+import { defineComponent, ref, computed, watch, createVNode } from "vue";
+import { AppQueryState } from "../atoms/app-query-state.js";
+const AppTree = /* @__PURE__ */ defineComponent({
+  name: "AppTree",
+  inheritAttrs: false,
+  props: {
+    nodes: {
+      type: Array,
+      required: true
+    },
+    /** 节点主键：字段名或取值函数 */
+    rowKey: {
+      type: [String, Function],
+      required: true
+    },
+    /** 标签字段名（默认 'label'） */
+    labelKey: {
+      type: String,
+      default: "label"
+    },
+    /** 子节点字段名（默认 'children'） */
+    childrenKey: {
+      type: String,
+      default: "children"
+    },
+    /** 受控选中（行主键值） */
+    selected: {
+      type: String,
+      default: void 0
+    },
+    onSelect: {
+      type: Function,
+      default: void 0
+    },
+    /** 节点附加内容（计数徽标等），渲染在标签之后 */
+    renderNode: {
+      type: Function,
+      default: void 0
+    },
+    /** 尺寸档：md 舒适（行高 30）/ sm 紧凑（行高 28），与主题包 Tree 的 M/S 档一致 */
+    size: {
+      type: String,
+      default: "md"
+    },
+    /** 受控展开集（传了就完全受控，内部不再自持） */
+    expandedKeys: {
+      type: Array,
+      default: void 0
+    },
+    /** 非受控展开初值 */
+    defaultExpandedKeys: {
+      type: Array,
+      default: () => []
+    },
+    onExpandChange: {
+      type: Function,
+      default: void 0
+    },
+    loading: {
+      type: Boolean,
+      default: false
+    },
+    /** 空态文案 */
+    empty: {
+      type: String,
+      default: "暂无数据"
+    },
+    /** 空态操作按钮（如「新建」）；与 `onEmptyAction` 同时传才渲染 */
+    emptyActionText: {
+      type: String,
+      default: void 0
+    },
+    onEmptyAction: {
+      type: Function,
+      default: void 0
+    },
+    /**
+     * 错误态（truthy 即触发）。
+     *
+     * **构造器顺序同 `AppTable.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
+     * 空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。
+     *
+     * 有它之前，消费方只能把错误文案塞进 `empty`：错误被渲染成空态语义（无错误插画、无重试入口），
+     * 用户看不出「是没数据还是加载挂了」。
+     */
+    error: {
+      type: [String, Boolean, Object, Number, Array],
+      default: void 0
+    },
+    /** 错误态标题（默认「加载失败」）；字符串错误原文会自动作为副文案显示 */
+    errorTitle: {
+      type: String,
+      default: "加载失败"
+    },
+    /** 错误态操作按钮（如「重试」）；与 `onErrorAction` 同时传才渲染 */
+    errorActionText: {
+      type: String,
+      default: void 0
+    },
+    onErrorAction: {
+      type: Function,
+      default: void 0
+    },
+    /** 强制重挂逃生舱（正常数据刷新不需要它） */
+    treeKey: {
+      type: [String, Number],
+      default: void 0
+    }
+  },
+  slots: Object,
+  setup(props, {
+    slots,
+    attrs
+  }) {
+    const nodeKey = (node) => typeof props.rowKey === "function" ? props.rowKey(node) : String(node[props.rowKey] ?? "");
+    const childrenOf = (node) => {
+      const children = node[props.childrenKey];
+      return Array.isArray(children) ? children : [];
+    };
+    const innerExpanded = ref([...props.defaultExpandedKeys]);
+    const expandedSet = computed(() => new Set(props.expandedKeys ?? innerExpanded.value));
+    const isExpanded = (key) => expandedSet.value.has(key);
+    const toggleExpand = (key) => {
+      const next = new Set(expandedSet.value);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      const list = [...next];
+      if (props.expandedKeys === void 0) innerExpanded.value = list;
+      props.onExpandChange?.(list);
+    };
+    watch(() => props.defaultExpandedKeys, (next) => {
+      if (props.expandedKeys === void 0) innerExpanded.value = [...next];
+    });
+    const handleSelect = (node) => {
+      props.onSelect?.(node);
+    };
+    const flatten = () => {
+      const rows = [];
+      const walk = (list, depth) => {
+        for (const node of list) {
+          const key = nodeKey(node);
+          rows.push({
+            node,
+            depth,
+            key
+          });
+          if (isExpanded(key)) walk(childrenOf(node), depth + 1);
+        }
+      };
+      walk(props.nodes, 0);
+      return rows;
+    };
+    return () => {
+      if (props.loading) {
+        return createVNode(AppQueryState, {
+          "loading": true,
+          "skeletonRows": 6
+        }, null);
+      }
+      if (props.error) {
+        return createVNode(AppQueryState, {
+          "error": props.error,
+          "errorTitle": props.errorTitle,
+          "errorDescription": typeof props.error === "string" ? props.error : void 0,
+          "errorActionText": props.errorActionText,
+          "onErrorAction": props.onErrorAction
+        }, null);
+      }
+      if (props.nodes.length === 0) {
+        return createVNode(AppQueryState, {
+          "empty": props.empty,
+          "emptyActionText": props.emptyActionText,
+          "onEmptyAction": props.onEmptyAction
+        }, null);
+      }
+      const rows = flatten().map(({
+        node,
+        depth,
+        key
+      }) => {
+        const children = childrenOf(node);
+        const hasChildren = children.length > 0;
+        const expanded = isExpanded(key);
+        const selected = props.selected !== void 0 && props.selected === key;
+        return createVNode("div", {
+          "class": "ak-tree__row",
+          "key": key,
+          "role": "treeitem",
+          "aria-selected": selected,
+          "aria-expanded": hasChildren ? expanded : void 0,
+          "data-selected": selected ? "true" : void 0,
+          "data-level": depth,
+          "style": {
+            "--ak-tree-level": depth
+          },
+          "onClick": () => handleSelect(node)
+        }, [hasChildren ? createVNode("span", {
+          "class": "ak-tree__caret",
+          "data-expanded": expanded ? "true" : "false",
+          "onClick": (event) => {
+            event.stopPropagation();
+            toggleExpand(key);
+          }
+        }, null) : createVNode("span", {
+          "class": "ak-tree__caret ak-tree__caret--empty"
+        }, null), createVNode("span", {
+          "class": "ak-tree__label"
+        }, [String(node[props.labelKey] ?? "")]), props.renderNode ? createVNode("span", {
+          "class": "ak-tree__extra"
+        }, [props.renderNode(node)]) : null]);
+      });
+      return createVNode("div", {
+        "key": props.treeKey,
+        "class": [attrs.class, "ak-tree", props.size === "sm" ? "ak-tree--compact" : ""].filter(Boolean).join(" "),
+        "role": "tree"
+      }, [rows, slots.default?.()]);
+    };
+  }
+});
+export {
+  AppTree
+};