@ticatec/topside-elements 1.0.0

package/dist/navigation/navigator/README.md

@@ -0,0 +1,304 @@
+# Navigator Component
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `itemClickHandler` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A vertical step / wizard navigator. Renders items as a clickable list with a connecting vertical line on the left, an active marker (filled circle), per-item status colors (completed / warning / not-start), and optional highlights. Designed for multi-step forms and guided workflows.
+
+## Features
+
+- **Vertical wizard trail**: each item gets a left-aligned line segment via CSS gradient; first/last items render half-segments so the line starts at the top of the first item and ends at the bottom of the last
+- **Three status states**: `Completed`, `Warning` (red dot), `NotStart` (italic, dimmed) — drive them via a `retrieveStatus` callback
+- **Active marker**: the active item shows a 15px bordered circle on the left
+- **Highlights array**: extra "look at me" color for arbitrary items (e.g. items with errors)
+- **Two-way bindable `activeItem`**: `bind:activeItem` updates on click without needing `onItemClick`
+- **Scrolls vertically** when items overflow
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+
+  const steps = [
+    { text: 'Step 1' },
+    { text: 'Step 2' },
+    { text: 'Step 3' },
+    { text: 'Step 4' }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // Mark items before activeItem as Completed, after as NotStart
+  function getStepStatus(item: any): NavItemStatus {
+    return steps.indexOf(item) <= steps.indexOf(activeItem)
+      ? NavItemStatus.Completed
+      : NavItemStatus.NotStart;
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  retrieveStatus={getStepStatus}
+/>
+```
+
+With `bind:activeItem`, clicking an item updates `activeItem` directly. No `onItemClick` needed unless you want to run side effects (analytics, validation, route change).
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Array<any>` | _(required)_ | Nav items. Each **must have a `text` property** for the label. Other fields are yours. |
+| `activeItem` | `any` | `$bindable(undefined)` | Currently active item. **`bind:activeItem`** for two-way binding; on click, the component assigns the clicked item here before calling `onItemClick`. |
+| `highlights` | `Array<any>` | `[]` | Items to highlight (e.g. items with errors). Matched by reference equality. |
+| `onItemClick` | `((item: any) => void) \| undefined` | `undefined` | Called on every click, **after** `activeItem` is updated. Use for side effects; not needed for state updates if you `bind:activeItem`. |
+| `retrieveStatus` | `((item: any) => NavItemStatus) \| undefined` | `undefined` | Returns the status for each item. **If omitted, all items default to `Completed`.** |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+
+> **Items matched by reference.** `activeItem === item` and `highlights.indexOf(item)` both use reference equality. Don't reconstruct arrays or clone items between renders — the active / highlight state will be lost.
+
+## NavItemStatus Enum
+
+```typescript
+enum NavItemStatus {
+  Completed = 'nav-completed',  // Default text color
+  Warning   = 'nav-warning',    // Same color + red dot on the right
+  NotStart  = 'nav-not-start',  // Dimmed + italic
+}
+```
+
+The CSS class is the enum value (`NavItemStatus.Completed === 'nav-completed'`), applied to each item's wrapper.
+
+## Layout
+
+```text
+┌─────────────────────────┐
+│ .topside-navigator-panel │   (overflow:hidden, full height)
+│ ┌─────────────────────┐ │
+│ │ .navigator-content  │ │   (overflow-y:auto)
+│ │                     │ │
+│ │  ┃ ● Step 1         │ │   ← active (circle marker, bold)
+│ │  ┃   Step 2         │ │   ← completed
+│ │  ┃   Step 3       • │ │   ← warning (red dot right)
+│ │  ┃   Step 4         │ │   ← not-start (italic, dimmed)
+│ │                     │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+The vertical line is a CSS `linear-gradient` on each item's background. The first/last items get half-height gradients so the line doesn't extend past the visual start/end.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="topside-navigator-panel" style="...">
+  <div class="navigator-content">
+    <!-- per item -->
+    <div
+      class="topside-navigator-item {retrieveStatus(item) ?? 'nav-completed'}"
+      class:active={activeItem === item}
+      class:highlight={highlights.indexOf(item) > -1}
+      aria-hidden="true"
+      onclick={() => handleClick(item)}
+    >
+      <span>{item.text}</span>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS Variables (all scoped to `.topside-navigator-panel`)
+
+| Variable | Purpose |
+|----------|---------|
+| `--topside-navigator-background-color` | Panel background |
+| `--topside-navigator-vertical-padding` | Panel top/bottom padding |
+| `--topside-navigator-completed-text-color` | `Completed` item color |
+| `--topside-navigator-not-start-text-color` | `NotStart` item color |
+| `--topside-navigator-warning-dot-color` | `Warning` red dot color |
+| `--topside-navigator-hover-text-color` | Hover color (non-active items) |
+| `--topside-navigator-active-text-color` | Active item color + marker border |
+| `--topside-navigator-active-text-weight` | Active item font weight (default `600`) |
+| `--topside-navigator-highlight-text-color` | Highlight color |
+
+Override per-instance:
+
+```svelte
+<div style="--topside-navigator-active-text-color: #dc2626;">
+  <Navigator ... />
+</div>
+```
+
+Or globally:
+
+```css
+:root {
+  --topside-navigator-active-text-color: #0061ff;
+}
+```
+
+### Visual markers
+
+- **Active item**: a 15px circle (`.active::before`) with a 4px border in `--topside-navigator-active-text-color`, white fill, positioned at `left: 5px; top: 50%`. Hover is suppressed on active items (`cursor: default`).
+- **Warning item**: a 6px red dot (`.nav-warning::after`) at `right: 8px; top: 30%`.
+- **Connecting line**: CSS `linear-gradient` on each item's background creates a 1px vertical line at `12-13px` from the left. First item: top half (so the line starts at the item's vertical center). Last item: bottom half. Middle items: full height.
+
+## Examples
+
+### Multi-Step Wizard with Navigation Controls
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+
+  const steps = [
+    { text: 'Personal Info' },
+    { text: 'Contact Details' },
+    { text: 'Preferences' },
+    { text: 'Review' }
+  ];
+
+  let activeItem = $state(steps[0]);
+  let highlights = $state<any>([]);
+
+  function getStepStatus(item: any): NavItemStatus {
+    const idx = steps.indexOf(item);
+    const currentIdx = steps.indexOf(activeItem);
+    if (idx < currentIdx) return NavItemStatus.Completed;
+    if (idx === currentIdx) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleClick(item: any) {
+    // Only allow navigating back to completed steps
+    if (steps.indexOf(item) > steps.indexOf(activeItem)) {
+      // revert the activeItem change Navigator already applied
+      activeItem = steps.find(s => s === arguments[0]) ?? activeItem;
+    }
+  }
+
+  function next() {
+    const idx = steps.indexOf(activeItem);
+    if (idx < steps.length - 1) activeItem = steps[idx + 1];
+  }
+
+  function prev() {
+    const idx = steps.indexOf(activeItem);
+    if (idx > 0) activeItem = steps[idx - 1];
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  highlights={highlights}
+  retrieveStatus={getStepStatus}
+  onItemClick={handleClick}
+/>
+
+<div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
+  <h2>{activeItem.text}</h2>
+  <p>Content for this step.</p>
+  <div style="display: flex; gap: 8px;">
+    <button onclick={prev}>Previous</button>
+    <button onclick={next}>Next</button>
+  </div>
+</div>
+```
+
+### Items with Errors (highlights + warning)
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+
+  const steps = [
+    { text: 'Account',  hasError: false },
+    { text: 'Profile',  hasError: true  },   // this one has issues
+    { text: 'Confirm',  hasError: false }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // Highlight any step with errors
+  const highlights = steps.filter(s => s.hasError);
+
+  function getStatus(item: any): NavItemStatus {
+    if (item.hasError) return NavItemStatus.Warning;
+    return steps.indexOf(item) <= steps.indexOf(activeItem)
+      ? NavItemStatus.Completed
+      : NavItemStatus.NotStart;
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  {highlights}
+  retrieveStatus={getStatus}
+/>
+```
+
+### Status-Only (No Click Navigation)
+
+If you want display-only (no click):
+
+```svelte
+<Navigator
+  items={steps}
+  activeItem={steps[steps.length - 1]}   {/* last item visually active */}
+  retrieveStatus={getStatus}
+/>
+```
+
+Clicks will still update `activeItem` internally (if `bind:` or `onItemClick` is set), but you can omit both and let the component be effectively display-only. Without `bind:` or `onItemClick`, internal state still updates but no one hears about it.
+
+## Behavior Notes
+
+- **Items matched by reference, not value.** Reconstructing the `items` array (e.g. via `.map`) on every render will lose `activeItem` / `highlights` matching. Keep `items` referentially stable.
+- **`retrieveStatus` defaults to `Completed`** when omitted. If you forget to pass it, every item will look "done".
+- **`activeItem` is updated internally on every click**, even if you don't `bind:` or pass `onItemClick`. The component is internally consistent — but the parent won't know.
+- **`handleClick` runs `activeItem = item` first**, then `onItemClick?.(item)`. If you want to **prevent** the active change (e.g. user hasn't completed prerequisites), you need to undo it inside `onItemClick` by setting `activeItem` back. There's no `canActivate` predicate.
+- **`aria-hidden="true"` on every item** — despite being clickable divs, they're hidden from screen readers. This is an a11y issue; see below.
+- **Long labels clip horizontally**, not wrap. The wrapper is single-line.
+
+## Accessibility (Significant Limitations)
+
+This component has **known a11y problems** you should be aware of:
+
+1. **Every item has `aria-hidden="true"`.** The entire navigation is invisible to screen readers — they won't announce items, the active state, or status colors.
+2. **Items are `<div onclick>`, not `<button>`.** No keyboard focus, no Enter/Space activation, no `role="link"` or `role="button"`.
+3. **Status is conveyed by color alone** (Completed vs NotStart) plus a small red dot for Warning. No text alternative.
+4. **No focus styles** for keyboard users.
+
+If you need keyboard-accessible step navigation, wrap each item in your own `<button>` and pass labels via the snippet pattern, or fork the component. The visual design is good; the semantics are not.
+
+## Best Practices
+
+1. **Keep `items` referentially stable.** Define it once (module scope or `$state` that you don't reassign). Mapping on every render breaks active/highlight matching.
+2. **Use `bind:activeItem`** instead of `onItemClick` for plain state sync. Add `onItemClick` only for side effects.
+3. **Always provide `retrieveStatus`** unless you really want every item to look completed by default.
+4. **Use `Warning` + `highlights` together** for error states — the red dot catches the eye, the highlight color reinforces it.
+5. **For forward-only wizards**, undo the active change in `onItemClick` if the user clicks ahead. There's no built-in guard.
+6. **Don't rely on this for keyboard / screen-reader users.** See a11y note above.
+
+## Related Components
+
+- [Breadcrumbs](../breadcrumbs/README.md) — horizontal path-style navigation (this is vertical step-style)
+- [NavigatorMenu](../nav_menu/README.md) — full hierarchical menu

package/dist/navigation/navigator/README_CN.md

@@ -0,0 +1,304 @@
+# Navigator 步骤导航组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `itemClickHandler` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+垂直的步骤 / 向导导航器。把项目渲染为可点击列表，左侧有连接的竖线，当前项有圆形标记，每项有状态颜色（完成 / 警告 / 未开始），还可以选择性高亮。专为多步表单和引导式流程设计。
+
+## 功能特性
+
+- **垂直向导路径**：每项通过 CSS gradient 渲染一段左侧竖线；首项 / 末项渲染半段，让线从首项顶部开始、末项底部结束
+- **三种状态**：`Completed`、`Warning`（红点）、`NotStart`（斜体、变淡） —— 通过 `retrieveStatus` 回调驱动
+- **当前项标记**：active 项左侧显示 15px 圆形边框
+- **高亮数组**：给任意项加"看我"颜色（比如有错误的项）
+- **`activeItem` 双向绑定**：`bind:activeItem` 在点击时自动更新，不需要 `onItemClick`
+- **纵向滚动**，内容溢出时
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+
+  const steps = [
+    { text: '第一步' },
+    { text: '第二步' },
+    { text: '第三步' },
+    { text: '第四步' }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // activeItem 之前的标 Completed，之后的标 NotStart
+  function getStepStatus(item: any): NavItemStatus {
+    return steps.indexOf(item) <= steps.indexOf(activeItem)
+      ? NavItemStatus.Completed
+      : NavItemStatus.NotStart;
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  retrieveStatus={getStepStatus}
+/>
+```
+
+用 `bind:activeItem` 后，点击项直接更新 `activeItem`。不需要 `onItemClick` —— 除非要跑副作用（埋点、校验、路由切换）。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `items` | `Array<any>` | _(必填)_ | 导航项。每项**必须有 `text` 属性**作为标签。其他字段随你 |
+| `activeItem` | `any` | `$bindable(undefined)` | 当前 active 项。**`bind:activeItem`** 双向绑定；点击时组件先把点击项赋给它，再调 `onItemClick` |
+| `highlights` | `Array<any>` | `[]` | 要高亮的项（如出错的项）。按引用相等匹配 |
+| `onItemClick` | `((item: any) => void) \| undefined` | `undefined` | 每次点击调用，**在 `activeItem` 更新之后**。用于副作用；如果用了 `bind:activeItem` 就不需要它做状态更新 |
+| `retrieveStatus` | `((item: any) => NavItemStatus) \| undefined` | `undefined` | 返回每项的状态。**不传时所有项默认 `Completed`** |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+
+> **项按引用匹配。** `activeItem === item` 和 `highlights.indexOf(item)` 都用引用相等。不要在渲染间重建数组或克隆项 —— active / 高亮状态会丢。
+
+## NavItemStatus 枚举
+
+```typescript
+enum NavItemStatus {
+  Completed = 'nav-completed',  // 默认文字色
+  Warning   = 'nav-warning',    // 同色 + 右侧红点
+  NotStart  = 'nav-not-start',  // 变淡 + 斜体
+}
+```
+
+CSS 类名就是枚举值（`NavItemStatus.Completed === 'nav-completed'`），加到每项的 wrapper 上。
+
+## 布局
+
+```text
+┌─────────────────────────┐
+│ .topside-navigator-panel │   (overflow:hidden，整高)
+│ ┌─────────────────────┐ │
+│ │ .navigator-content  │ │   (overflow-y:auto)
+│ │                     │ │
+│ │  ┃ ● 第一步         │ │   ← active（圆形标记 + 加粗）
+│ │  ┃   第二步         │ │   ← completed
+│ │  ┃   第三步       • │ │   ← warning（右侧红点）
+│ │  ┃   第四步         │ │   ← not-start（斜体、变淡）
+│ │                     │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+竖线是每项背景上的 CSS `linear-gradient`。首项 / 末项用半高 gradient，让线不超出视觉起止点。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="topside-navigator-panel" style="...">
+  <div class="navigator-content">
+    <!-- 每项 -->
+    <div
+      class="topside-navigator-item {retrieveStatus(item) ?? 'nav-completed'}"
+      class:active={activeItem === item}
+      class:highlight={highlights.indexOf(item) > -1}
+      aria-hidden="true"
+      onclick={() => handleClick(item)}
+    >
+      <span>{item.text}</span>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS 变量（都作用域在 `.topside-navigator-panel`）
+
+| 变量 | 用途 |
+|------|------|
+| `--topside-navigator-background-color` | 面板背景 |
+| `--topside-navigator-vertical-padding` | 面板上下 padding |
+| `--topside-navigator-completed-text-color` | `Completed` 项颜色 |
+| `--topside-navigator-not-start-text-color` | `NotStart` 项颜色 |
+| `--topside-navigator-warning-dot-color` | `Warning` 红点颜色 |
+| `--topside-navigator-hover-text-color` | hover 色（非 active 项） |
+| `--topside-navigator-active-text-color` | active 项颜色 + 标记边框色 |
+| `--topside-navigator-active-text-weight` | active 项字重（默认 `600`） |
+| `--topside-navigator-highlight-text-color` | 高亮色 |
+
+单实例覆盖：
+
+```svelte
+<div style="--topside-navigator-active-text-color: #dc2626;">
+  <Navigator ... />
+</div>
+```
+
+或全局：
+
+```css
+:root {
+  --topside-navigator-active-text-color: #0061ff;
+}
+```
+
+### 视觉标记
+
+- **active 项**：15px 圆（`.active::before`），4px 边框用 `--topside-navigator-active-text-color`，白底，位置 `left: 5px; top: 50%`。active 项禁用 hover（`cursor: default`）
+- **warning 项**：6px 红点（`.nav-warning::after`），位置 `right: 8px; top: 30%`
+- **连接线**：每项背景上的 CSS `linear-gradient` 创建 1px 竖线，距左 12-13px。首项：上半段（线从项的垂直中线开始）。末项：下半段。中间项：整高
+
+## 示例
+
+### 多步向导 + 导航控件
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+
+  const steps = [
+    { text: '个人信息' },
+    { text: '联系方式' },
+    { text: '偏好设置' },
+    { text: '确认' }
+  ];
+
+  let activeItem = $state(steps[0]);
+  let highlights = $state<any>([]);
+
+  function getStepStatus(item: any): NavItemStatus {
+    const idx = steps.indexOf(item);
+    const currentIdx = steps.indexOf(activeItem);
+    if (idx < currentIdx) return NavItemStatus.Completed;
+    if (idx === currentIdx) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleClick(item: any) {
+    // 只允许回到已完成的步骤
+    if (steps.indexOf(item) > steps.indexOf(activeItem)) {
+      // 撤销 Navigator 已经做的 activeItem 改动
+      activeItem = steps.find(s => s === arguments[0]) ?? activeItem;
+    }
+  }
+
+  function next() {
+    const idx = steps.indexOf(activeItem);
+    if (idx < steps.length - 1) activeItem = steps[idx + 1];
+  }
+
+  function prev() {
+    const idx = steps.indexOf(activeItem);
+    if (idx > 0) activeItem = steps[idx - 1];
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  highlights={highlights}
+  retrieveStatus={getStepStatus}
+  onItemClick={handleClick}
+/>
+
+<div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
+  <h2>{activeItem.text}</h2>
+  <p>该步骤的内容。</p>
+  <div style="display: flex; gap: 8px;">
+    <button onclick={prev}>上一步</button>
+    <button onclick={next}>下一步</button>
+  </div>
+</div>
+```
+
+### 出错项（高亮 + 警告）
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/topside-elements/Navigator';
+
+  const steps = [
+    { text: '账户',   hasError: false },
+    { text: '资料',   hasError: true  },   // 这一步有问题
+    { text: '确认',   hasError: false }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // 高亮任何出错的步骤
+  const highlights = steps.filter(s => s.hasError);
+
+  function getStatus(item: any): NavItemStatus {
+    if (item.hasError) return NavItemStatus.Warning;
+    return steps.indexOf(item) <= steps.indexOf(activeItem)
+      ? NavItemStatus.Completed
+      : NavItemStatus.NotStart;
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  {highlights}
+  retrieveStatus={getStatus}
+/>
+```
+
+### 仅展示（无点击导航）
+
+要纯展示（不可点）：
+
+```svelte
+<Navigator
+  items={steps}
+  activeItem={steps[steps.length - 1]}   {/* 末项视觉上 active */}
+  retrieveStatus={getStatus}
+/>
+```
+
+点击仍然会内部更新 `activeItem`（如果用了 `bind:` 或 `onItemClick`），但你可以两个都不传，让组件事实上只展示。没有 `bind:` 或 `onItemClick` 时内部状态仍然更新，但没人能知道。
+
+## 行为说明
+
+- **项按引用匹配，不是值。** 渲染间重建 `items` 数组（如 `.map`）会丢失 `activeItem` / `highlights` 匹配。保持 `items` 引用稳定
+- **`retrieveStatus` 不传时默认 `Completed`**。忘了传的话每项看起来都是"已完成"
+- **每次点击内部都更新 `activeItem`**，即使不用 `bind:` 或不传 `onItemClick`。组件内部自洽 —— 但父组件不会知道
+- **`handleClick` 先执行 `activeItem = item`**，再执行 `onItemClick?.(item)`。如果想**阻止** active 变更（比如用户没完成前置步骤），需要在 `onItemClick` 内部把 `activeItem` 设回去。没有 `canActivate` 谓词
+- **每项都有 `aria-hidden="true"`** —— 尽管是可点击 div，但屏幕阅读器看不到。这是 a11y 问题 —— 见下
+- **长标签横向裁剪**，不换行。wrapper 是单行
+
+## 无障碍访问（重大限制）
+
+这个组件有**已知的 a11y 问题**，你需要知道：
+
+1. **每项都有 `aria-hidden="true"`。** 整个导航对屏幕阅读器不可见 —— 它们不会朗读项、active 状态或状态颜色
+2. **项是 `<div onclick>`，不是 `<button>`。** 没有键盘焦点、没有 Enter/Space 激活、没有 `role="link"` 或 `role="button"`
+3. **状态只靠颜色传达**（Completed vs NotStart）外加 Warning 的小红点。没有文字替代
+4. **没有键盘用户的焦点样式**
+
+需要键盘可访问的步骤导航，自己用 `<button>` 包每一项并通过 snippet 传标签，或 fork 这个组件。视觉设计不错；语义不行。
+
+## 最佳实践
+
+1. **保持 `items` 引用稳定。** 定义一次（模块作用域或不重新赋值的 `$state`）。每次渲染 map 会破坏 active / 高亮匹配
+2. **用 `bind:activeItem`** 而不是 `onItemClick` 做纯状态同步。`onItemClick` 只在需要副作用时加
+3. **永远传 `retrieveStatus`**，除非你真的想每项默认看起来都是已完成
+4. **`Warning` + `highlights` 一起用**做错误状态 —— 红点抓眼球，高亮色加强
+5. **只能向后的向导**，在 `onItemClick` 里撤销越界点击的 active 变更。没有内置守卫
+6. **不要给键盘 / 屏幕阅读器用户用这个。** 见上面 a11y 说明
+
+## 相关组件
+
+- [Breadcrumbs](../breadcrumbs/README_CN.md) —— 水平路径式导航（这个是垂直步骤式）
+- [NavigatorMenu](../nav_menu/README_CN.md) —— 完整层级菜单

package/dist/navigation/navigator/index.d.ts

@@ -0,0 +1,4 @@
+import Navigator from "./Navigator.svelte";
+import { NavItemStatus } from "./NavItemStatus";
+export default Navigator;
+export { NavItemStatus };

package/dist/navigation/navigator/index.js

@@ -0,0 +1,4 @@
+import Navigator from "./Navigator.svelte";
+import { NavItemStatus } from "./NavItemStatus";
+export default Navigator;
+export { NavItemStatus };