@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/navigation/breadcrumbs/Breadcrumbs.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+    import type Breadcrumb from "./Breadcrumb";
+
+    interface Props {
+        items?: Array<Breadcrumb>;
+        separator?: string;
+        theme?: string;
+        onclick?: (event: MouseEvent, item: any) => void;
+        style?: string;
+        leadingSeparator?: boolean;
+    }
+
+    let {
+        items = [],
+        separator = "/",
+        theme,
+        onclick,
+        style = "",
+        leadingSeparator = false
+    }: Props = $props();
+
+    const handleClick = (item: Breadcrumb, isLast: boolean) => (event: MouseEvent) => {
+        if (!isLast && onclick) {
+            onclick(event, item.data);
+        }
+    };
+
+</script>
+
+<div class="uniface-breadcrumbs" {style} data-theme={theme}>
+    {#each items as item, idx}
+        {@const isLast = idx === items.length - 1}
+        {@const showSeparator = idx > 0 || leadingSeparator}
+        <div class:last_child={isLast}>
+            {#if showSeparator}
+                <span>{separator}</span>
+            {/if}
+            <a class="breadcrumb"
+               class:interactive={!isLast}
+               onclick={handleClick(item, isLast)}
+               tabindex={isLast ? -1 : 0}
+               aria-current={isLast ? "page" : undefined}
+               href={isLast ? undefined : '#'}>
+                {item.label}
+            </a>
+        </div>
+    {/each}
+</div>
+
+<style>
+    .uniface-breadcrumbs {
+        width: 100%;
+        display: flex;
+        flex-direction: row;
+        flex-wrap: nowrap;
+        overflow: hidden;
+        user-select: none;
+        color: var(--uniface-breadcrumbs-color);
+        gap: var(--uniface-breadcrumbs-spacing);
+        padding: var(--uniface-breadcrumbs-padding);
+    }
+
+    .breadcrumb {
+        margin: 0 6px;
+        color: inherit;
+        text-decoration: none;
+        outline: none;
+    }
+
+    .breadcrumb.interactive {
+        cursor: pointer;
+        color: var(--uniface-breadcrumbs-color);
+    }
+
+    .breadcrumb.interactive:hover {
+        color: var(--uniface-breadcrumbs-color-hover);
+    }
+
+    .breadcrumb.interactive:focus-visible {
+        color: var(--uniface-breadcrumbs-color-hover);
+        text-decoration: underline;
+        text-underline-offset: 4px;
+    }
+
+    .breadcrumb.interactive:active {
+        color: var(--uniface-breadcrumbs-color-active);
+        font-weight: 600;
+    }
+
+
+</style>

package/dist/navigation/breadcrumbs/Breadcrumbs.svelte.d.ts

@@ -0,0 +1,12 @@
+import type Breadcrumb from "./Breadcrumb";
+interface Props {
+    items?: Array<Breadcrumb>;
+    separator?: string;
+    theme?: string;
+    onclick?: (event: MouseEvent, item: any) => void;
+    style?: string;
+    leadingSeparator?: boolean;
+}
+declare const Breadcrumbs: import("svelte").Component<Props, {}, "">;
+type Breadcrumbs = ReturnType<typeof Breadcrumbs>;
+export default Breadcrumbs;

package/dist/navigation/breadcrumbs/README.md

@@ -0,0 +1,257 @@
+# Breadcrumbs Component
+
+A horizontal breadcrumb trail showing the user's location in a hierarchy. Items render as `<a>` tags; non-last items are clickable, the last item is marked as the current page (`aria-current="page"`).
+
+## Features
+
+- **Array-driven**: pass `Breadcrumb[]` (`{ label, data }`) — no nested tree required
+- **Custom separator**: any string (`/` by default), shown between items
+- **Optional leading separator**: for prefixing the trail (e.g. a home icon)
+- **Last item is non-interactive**: gets `aria-current="page"`, `tabindex="-1"`, no `href`, no click handler
+- **Full keyboard support**: Tab through items, Enter to activate, `:focus-visible` underline
+- **Click handler receives `data`, not the breadcrumb object** — `onclick(event, data)` fires for every non-last item
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+  const items: Breadcrumb[] = [
+    { label: 'Home',         data: { path: '/' } },
+    { label: 'Products',     data: { path: '/products' } },
+    { label: 'Electronics',  data: { path: '/products/electronics' } },
+    { label: 'Smartphones',  data: { path: '/products/electronics/smartphones' } }
+  ];
+
+  function handleClick(event: MouseEvent, data: any) {
+    event.preventDefault();      // the <a href="#"> would jump to top otherwise
+    console.log('Navigate to:', data.path);
+  }
+</script>
+
+<Breadcrumbs items={items} onclick={handleClick} />
+```
+
+> **Call `event.preventDefault()` in your handler.** Each non-last item is an `<a href="#">`, so without `preventDefault` the page jumps to the top on every click.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Breadcrumb[]` | `[]` | Breadcrumb trail. Each item has `label` (display text) and `data` (payload passed to the click handler). |
+| `separator` | `string` | `'/'` | String rendered between items (and before the first item if `leadingSeparator` is on) |
+| `onclick` | `((event: MouseEvent, data: any) => void) \| undefined` | `undefined` | Click handler. **Only fires for non-last items.** The last item (current page) is not clickable. |
+| `leadingSeparator` | `boolean` | `false` | Show the separator before the first item too |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
+
+## Breadcrumb Type
+
+```typescript
+interface Breadcrumb {
+  label: string;   // Display text
+  data: any;       // Payload passed to onclick as the 2nd argument
+}
+```
+
+`data` is `any` — store whatever your router needs (route path, category id, etc.).
+
+## Layout
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│ .uniface-breadcrumbs (flex row, nowrap, overflow:hidden)│
+│  [Home] / [Products] / [Electronics] / [Smartphones*]   │
+│                                              ↑           │
+│                                    last_child (current)  │
+└─────────────────────────────────────────────────────────┘
+```
+
+The trail is `flex-wrap: nowrap; overflow: hidden` — long trails clip on the right, they don't wrap to a second line. If you expect long trails, consider truncating `items` yourself before passing them in.
+
+Each item is wrapped in a `<div class:last_child={isLast}>` with the separator `<span>` (if shown) and the `<a class="breadcrumb">` inside.
+
+## DOM Structure & CSS
+
+Rendered output (4 items, last one is current):
+
+```html
+<div class="uniface-breadcrumbs" data-theme="...">
+  <!-- item 0 (not last) -->
+  <div>
+    <span>/</span>                      <!-- only when idx > 0 OR leadingSeparator -->
+    <a class="breadcrumb interactive" tabindex="0" href="#">
+      Home
+    </a>
+  </div>
+
+  <!-- item 1, 2 (same pattern) -->
+
+  <!-- item 3 (LAST) -->
+  <div class="last_child">
+    <span>/</span>
+    <a class="breadcrumb" tabindex="-1" aria-current="page">
+      Smartphones
+    </a>
+  </div>
+</div>
+```
+
+Key differences on the last item:
+- No `interactive` class → no cursor, no hover/focus styles
+- `tabindex="-1"` → skipped in tab order
+- `aria-current="page"` → announced by screen readers as "current page"
+- No `href` attribute → not a link
+- The wrapper div gets `last_child` class (currently no CSS rule uses it — hook for your own styling)
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--uniface-breadcrumbs-color` | Text color (default + interactive) |
+| `--uniface-breadcrumbs-color-hover` | Hover / focus-visible color |
+| `--uniface-breadcrumbs-color-active` | Active (press) color |
+| `--uniface-breadcrumbs-spacing` | Gap between items |
+| `--uniface-breadcrumbs-padding` | Outer wrapper padding |
+
+### Built-in styles
+
+```css
+.uniface-breadcrumbs {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: nowrap;
+  overflow: hidden;
+  user-select: none;
+  gap: var(--uniface-breadcrumbs-spacing);
+}
+
+.breadcrumb {
+  margin: 0 6px;
+  color: inherit;
+  text-decoration: none;
+  outline: none;
+}
+
+.breadcrumb.interactive              { cursor: pointer; }
+.breadcrumb.interactive:hover        { color: var(--uniface-breadcrumbs-color-hover); }
+.breadcrumb.interactive:focus-visible{
+  color: var(--uniface-breadcrumbs-color-hover);
+  text-decoration: underline;
+  text-underline-offset: 4px;
+}
+.breadcrumb.interactive:active       { color: var(--uniface-breadcrumbs-color-active); font-weight: 600; }
+```
+
+## Examples
+
+### E-commerce Category Trail
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+  const items: Breadcrumb[] = [
+    { label: 'All Categories', data: { categoryId: null } },
+    { label: 'Electronics',    data: { categoryId: 'electronics' } },
+    { label: 'Computers',      data: { categoryId: 'computers' } },
+    { label: 'Laptops',        data: { categoryId: 'laptops' } }
+  ];
+
+  function goToCategory(event: MouseEvent, data: any) {
+    event.preventDefault();
+    if (data.categoryId) {
+      goto(`/categories/${data.categoryId}`);
+    } else {
+      goto('/categories');
+    }
+  }
+</script>
+
+<Breadcrumbs
+  items={items}
+  onclick={goToCategory}
+  separator=" › "
+  style="padding: 8px 16px;"
+/>
+```
+
+### With Leading Separator
+
+For visual prefix (e.g. when you want a home icon before the first item):
+
+```svelte
+<Breadcrumbs items={items} onclick={...} leadingSeparator />
+```
+
+Renders: `/ Home / Products / Current`. Useful when the breadcrumbs sit next to other UI and need a visual delimiter.
+
+### Custom Separator (Icon Font)
+
+```svelte
+<Breadcrumbs items={items} onclick={...} separator="›" />
+```
+
+The separator is plain text rendered in a `<span>`. To use an icon, replace the component or render your own trail.
+
+### Truncating Long Trails
+
+For deep hierarchies, truncate before passing in:
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+  const full: Breadcrumb[] = [...];   // 10 levels deep
+
+  // Show first 2, ellipsis, last 2
+  $: items = full.length > 5
+    ? [...full.slice(0, 2), { label: '…', data: { skipped: true } }, ...full.slice(-2)]
+    : full;
+</script>
+
+<Breadcrumbs items={items} onclick={handleClick} />
+```
+
+## Behavior Notes
+
+- **Last item is non-interactive.** No click handler fires for it, no `href`, no `tabindex`. It represents the current page.
+- **Items render as `<a href="#">`.** Without `event.preventDefault()` in your handler, clicking jumps to the page top.
+- **`onclick` is called for every non-last item** — you decide where to navigate based on `data`.
+- **Long trails clip, not wrap.** Consider truncation for deep hierarchies.
+- **`user-select: none`** on the wrapper — labels can't be selected.
+- **No `last_child` CSS rule exists**, but the class is on the wrapper div — use it for your own styling (e.g. bold the current page).
+
+## Accessibility
+
+- Each non-last item is a real `<a>` with `tabindex="0"` and a `:focus-visible` underline.
+- The last item has `aria-current="page"` — screen readers announce it as the current page.
+- The separator `<span>` is plain text — screen readers will read it (e.g. "Home slash Products slash ..."). If this is noisy, hide it with `aria-hidden="true"` in your own fork.
+- Color is the only differentiator between interactive and non-interactive items — ensure your theme keeps contrast sufficient for both states.
+
+## Best Practices
+
+1. **Always `event.preventDefault()` in `onclick`** — items are `<a href="#">` and will jump otherwise.
+2. **Pass router-relevant data via the `data` field** — route paths, IDs, query params. The component doesn't care what's inside.
+3. **Truncate long trails before rendering** — the component clips overflow rather than wrapping or scrolling.
+4. **The last item should match the current URL** — that's what `aria-current="page"` implies. Don't pass a "future" or "next" item as the last entry.
+5. **Use `leadingSeparator` only when there's a visual reason** (sits next to other nav). Otherwise the leading slash looks odd.
+6. **Don't rely on color alone** — both interactive and non-interactive items use the same base color in some themes; the cursor and underline are the real signals.
+
+## Related Components
+
+- [NavigatorMenu](../nav_menu/README.md) — full hierarchical menu (Breadcrumbs shows the *path*, NavigatorMenu shows the *tree*)

package/dist/navigation/breadcrumbs/README_CN.md

@@ -0,0 +1,257 @@
+# Breadcrumbs 面包屑组件
+
+水平面包屑路径，显示用户在层级中的位置。每项渲染为 `<a>` 标签 —— 非末项可点击，末项被标记为当前页（`aria-current="page"`）。
+
+## 功能特性
+
+- **数组驱动**：传 `Breadcrumb[]`（`{ label, data }`） —— 不需要嵌套树
+- **自定义分隔符**：任意字符串（默认 `/`），渲染在各项之间
+- **可选前置分隔符**：用于路径开头（如 home 图标之后）
+- **末项不可交互**：加 `aria-current="page"`、`tabindex="-1"`、无 `href`、无 click handler
+- **完整键盘支持**：Tab 在各项间切换、Enter 激活、`:focus-visible` 下划线
+- **点击 handler 收到的是 `data` 不是 breadcrumb 对象** —— `onclick(event, data)` 对每个非末项触发
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+  const items: Breadcrumb[] = [
+    { label: '首页',     data: { path: '/' } },
+    { label: '产品',     data: { path: '/products' } },
+    { label: '电子产品', data: { path: '/products/electronics' } },
+    { label: '智能手机', data: { path: '/products/electronics/smartphones' } }
+  ];
+
+  function handleClick(event: MouseEvent, data: any) {
+    event.preventDefault();      // 否则 <a href="#"> 会跳到顶部
+    console.log('导航到:', data.path);
+  }
+</script>
+
+<Breadcrumbs items={items} onclick={handleClick} />
+```
+
+> **handler 里要调 `event.preventDefault()`。** 每个非末项是 `<a href="#">`，不阻止默认行为的话每次点击都会跳到页面顶部。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `items` | `Breadcrumb[]` | `[]` | 面包屑路径。每项有 `label`（显示文字）和 `data`（透传给 click handler 的负载） |
+| `separator` | `string` | `'/'` | 渲染在各项之间的字符串（`leadingSeparator` 开时也在首项前渲染） |
+| `onclick` | `((event: MouseEvent, data: any) => void) \| undefined` | `undefined` | 点击 handler。**仅对非末项触发**。末项（当前页）不可点 |
+| `leadingSeparator` | `boolean` | `false` | 在首项之前也显示分隔符 |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+
+## Breadcrumb 类型
+
+```typescript
+interface Breadcrumb {
+  label: string;   // 显示文字
+  data: any;       // 作为第 2 个参数传给 onclick 的负载
+}
+```
+
+`data` 是 `any` —— 装路由器需要的任何东西（路径、分类 ID 等）。
+
+## 布局
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│ .uniface-breadcrumbs (flex row, nowrap, overflow:hidden)│
+│  [首页] / [产品] / [电子产品] / [智能手机*]              │
+│                                          ↑               │
+│                                last_child（当前页）      │
+└─────────────────────────────────────────────────────────┘
+```
+
+路径是 `flex-wrap: nowrap; overflow: hidden` —— 长路径在右侧裁掉，不换行到第二行。预期路径会很长的话，自己先截断 `items` 再传。
+
+每项包在 `<div class:last_child={isLast}>` 里，里面有分隔符 `<span>`（如果显示）和 `<a class="breadcrumb">`。
+
+## DOM 结构与 CSS
+
+实际渲染（4 项，末项是当前页）：
+
+```html
+<div class="uniface-breadcrumbs" data-theme="...">
+  <!-- 第 0 项（非末） -->
+  <div>
+    <span>/</span>                      <!-- 仅 idx > 0 或 leadingSeparator 时 -->
+    <a class="breadcrumb interactive" tabindex="0" href="#">
+      首页
+    </a>
+  </div>
+
+  <!-- 第 1、2 项（同模式） -->
+
+  <!-- 第 3 项（末项） -->
+  <div class="last_child">
+    <span>/</span>
+    <a class="breadcrumb" tabindex="-1" aria-current="page">
+      智能手机
+    </a>
+  </div>
+</div>
+```
+
+末项的关键差异：
+- 没有 `interactive` 类 → 无 cursor，无 hover/focus 样式
+- `tabindex="-1"` → 不在 Tab 序列
+- `aria-current="page"` → 屏幕阅读器朗读为"当前页"
+- 没有 `href` 属性 → 不是链接
+- 外层 div 加 `last_child` 类（当前无 CSS 规则使用 —— 你自己写样式的钩子）
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--uniface-breadcrumbs-color` | 文字色（默认 + 可交互） |
+| `--uniface-breadcrumbs-color-hover` | hover / focus-visible 色 |
+| `--uniface-breadcrumbs-color-active` | active（按下）色 |
+| `--uniface-breadcrumbs-spacing` | 各项间距 |
+| `--uniface-breadcrumbs-padding` | 外层 wrapper 的 padding |
+
+### 内置样式
+
+```css
+.uniface-breadcrumbs {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: nowrap;
+  overflow: hidden;
+  user-select: none;
+  gap: var(--uniface-breadcrumbs-spacing);
+}
+
+.breadcrumb {
+  margin: 0 6px;
+  color: inherit;
+  text-decoration: none;
+  outline: none;
+}
+
+.breadcrumb.interactive              { cursor: pointer; }
+.breadcrumb.interactive:hover        { color: var(--uniface-breadcrumbs-color-hover); }
+.breadcrumb.interactive:focus-visible{
+  color: var(--uniface-breadcrumbs-color-hover);
+  text-decoration: underline;
+  text-underline-offset: 4px;
+}
+.breadcrumb.interactive:active       { color: var(--uniface-breadcrumbs-color-active); font-weight: 600; }
+```
+
+## 示例
+
+### 电商分类路径
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+  const items: Breadcrumb[] = [
+    { label: '全部分类', data: { categoryId: null } },
+    { label: '电子产品', data: { categoryId: 'electronics' } },
+    { label: '计算机',   data: { categoryId: 'computers' } },
+    { label: '笔记本',   data: { categoryId: 'laptops' } }
+  ];
+
+  function goToCategory(event: MouseEvent, data: any) {
+    event.preventDefault();
+    if (data.categoryId) {
+      goto(`/categories/${data.categoryId}`);
+    } else {
+      goto('/categories');
+    }
+  }
+</script>
+
+<Breadcrumbs
+  items={items}
+  onclick={goToCategory}
+  separator=" › "
+  style="padding: 8px 16px;"
+/>
+```
+
+### 带前置分隔符
+
+用于视觉前缀（如想在首项前放 home 图标）：
+
+```svelte
+<Breadcrumbs items={items} onclick={...} leadingSeparator />
+```
+
+渲染：`/ 首页 / 产品 / 当前`。面包屑旁边贴其他 UI、需要视觉分隔时有用。
+
+### 自定义分隔符
+
+```svelte
+<Breadcrumbs items={items} onclick={...} separator="›" />
+```
+
+分隔符是渲染在 `<span>` 里的纯文本。要用图标得自己换组件或自己渲染路径。
+
+### 截断长路径
+
+层级深时，先截断再传：
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs, { type Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+
+  const full: Breadcrumb[] = [...];   // 10 层深
+
+  // 显示首 2 项、省略号、末 2 项
+  $: items = full.length > 5
+    ? [...full.slice(0, 2), { label: '…', data: { skipped: true } }, ...full.slice(-2)]
+    : full;
+</script>
+
+<Breadcrumbs items={items} onclick={handleClick} />
+```
+
+## 行为说明
+
+- **末项不可交互。** 不触发 click handler，无 `href`、无 `tabindex`。代表当前页
+- **各项渲染为 `<a href="#">`。** handler 不调 `preventDefault()` 的话，点击会跳到页面顶部
+- **`onclick` 对每个非末项触发** —— 根据 `data` 决定导航到哪
+- **长路径裁剪不换行。** 深层级考虑自己截断
+- **`user-select: none`** 在 wrapper 上 —— 标签不可选中
+- **没有 `last_child` CSS 规则**，但 wrapper div 上有这个类 —— 自己写样式时用（如把当前页加粗）
+
+## 无障碍访问
+
+- 每个非末项是真正的 `<a>`，有 `tabindex="0"` 和 `:focus-visible` 下划线
+- 末项有 `aria-current="page"` —— 屏幕阅读器朗读为"当前页"
+- 分隔符 `<span>` 是纯文本 —— 屏幕阅读器会读出来（如"首页 斜杠 产品 斜杠 …"）。觉得吵的话在自己的分支里加 `aria-hidden="true"`
+- 颜色是可交互与不可交互项的唯一区分 —— 确保你的主题在两个状态下都保持足够对比度
+
+## 最佳实践
+
+1. **`onclick` 里永远 `event.preventDefault()`** —— 各项是 `<a href="#">`，否则会跳顶
+2. **路由相关数据通过 `data` 字段传** —— 路径、ID、query 参数。组件不在乎里面是什么
+3. **长路径渲染前自己截断** —— 组件是裁剪溢出，不是换行或滚动
+4. **末项应该匹配当前 URL** —— 这是 `aria-current="page"` 暗示的语义。别把"未来"或"下一步"项作为末项
+5. **`leadingSeparator` 只在有视觉理由时用**（旁边贴其他导航）。否则前置斜杠显得奇怪
+6. **不要只靠颜色区分** —— 某些主题下可交互和不可交互项底色相同；光标和下划线才是真信号
+
+## 相关组件
+
+- [NavigatorMenu](../nav_menu/README_CN.md) —— 完整层级菜单（Breadcrumbs 显示*路径*，NavigatorMenu 显示*树*）

package/dist/navigation/nav_menu/MenuItem.d.ts

@@ -0,0 +1,7 @@
+import type { IHierarchyData } from "../../lib";
+export default interface MenuItem {
+    [key: string]: any;
+}
+export interface MenuNode extends IHierarchyData<MenuItem> {
+}
+export type OnMenuClick = (item: MenuItem) => void;

package/dist/navigation/nav_menu/Menus.d.ts

@@ -0,0 +1,12 @@
+import { HierarchyTree } from "../../lib";
+import type { IHierarchyData } from "../../lib";
+import type MenuItem from "./MenuItem";
+export default class Menus extends HierarchyTree<MenuItem> {
+    /**
+     * 删除所有"空目录"节点。
+     *
+     * @param predicate 判定一个节点是否是目录（目录类型 + 无子节点时删除）。
+     *                  典型实现：`(node) => node.data.type === 'folder'`。
+     */
+    removeEmptyDirectory(predicate: (node: IHierarchyData<MenuItem>) => boolean): void;
+}

package/dist/navigation/nav_menu/Menus.js

@@ -0,0 +1,15 @@
+import { HierarchyTree } from "../../lib";
+export default class Menus extends HierarchyTree {
+    /**
+     * 删除所有"空目录"节点。
+     *
+     * @param predicate 判定一个节点是否是目录（目录类型 + 无子节点时删除）。
+     *                  典型实现：`(node) => node.data.type === 'folder'`。
+     */
+    removeEmptyDirectory(predicate) {
+        const empties = this.filter((node) => predicate(node) && node.isLeaf);
+        for (const node of empties) {
+            this.remove(node.data);
+        }
+    }
+}