@ticatec/uniface-element 5.0.4 → 5.1.0

package/dist/layouts/page/README_CN.md

@@ -7,7 +7,7 @@
 - **固定 48px header**：标题、可选注释（副标题，截断）、可选 back 或 reload 图标
 - **弹性内容区**：占满剩余高度，裁剪溢出
 - **可选圆角和阴影**（`round` / `shadow`，默认都开）
-- **三种 header 定制钩子**：文本 props（`title` / `comment`）、`headerExt` snippet 加额外 header 内容、完整 `pageHeader` snippet 完全替换
+- **三种 header 定制钩子**：文本 props（`title` / `comment`）、`headerExtra` snippet 加额外 header 内容、完整 `header` snippet 完全替换
 - **异步感知的导航动作**：`goBack` / `reload` 是 `() => any`（可为 async） —— 透传给 Icon 的防抖点击处理器
 - **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
 
@@ -23,7 +23,7 @@ npm install @ticatec/uniface-element
 import Page, { PageHeader, type PageAction } from '@ticatec/uniface-element/Page';
 ```
 
-`PageHeader` 是命名导出，需要单独用时可以导入（多数场景下用 `pageHeader` snippet 覆盖就够了）。
+`PageHeader` 是命名导出，需要单独用时可以导入（多数场景下用 `header` snippet 覆盖就够了）。
 
 ## 基本用法
 
@@ -52,8 +52,8 @@ import Page, { PageHeader, type PageAction } from '@ticatec/uniface-element/Page
 | `content$style` | `string` | `''` | 内容区的内联 CSS（如 `padding: 16px;`） |
 | `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
 | `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
-| `pageHeader` | `Snippet<[string, string?, PageAction?, PageAction?]> \| undefined` | `undefined` | **替换**默认 PageHeader。Snippet 参数：`(title, comment, goBack, reload)` |
-| `headerExt` | `Snippet \| undefined` | `undefined` | 默认 PageHeader 右侧的额外内容。设置了 `pageHeader` snippet 时被忽略（那时布局你自己控） |
+| `header` | `Snippet<[string, string?, PageAction?, PageAction?]> \| undefined` | `undefined` | **替换**默认 PageHeader。Snippet 参数：`(title, comment, goBack, reload)` |
+| `headerExtra` | `Snippet \| undefined` | `undefined` | 默认 PageHeader 右侧的额外内容。设置了 `header` snippet 时被忽略（那时布局你自己控） |
 | `children` | `Snippet \| undefined` | `undefined` | body 内容 |
 
 > **`goBack` 和 `reload` 互斥。** 两者都设 → 只渲染 `goBack`（back 图标）。`reload` 图标只在 `goBack` 缺席时出现。这是设计如此 —— 该槽位只装一个前置图标。
@@ -75,7 +75,7 @@ type PageAction = () => any;
 │  │ .uniface-page (round + shadow)                 │  │
 │  │  ┌──────────────────────────────────────────┐  │  │
 │  │  │ .uniface-page-header (height: 48px)      │  │  │
-│  │  │ [← back] 标题  注释…     [headerExt]      │  │  │
+│  │  │ [← back] 标题  注释…     [headerExtra]      │  │  │
 │  │  ├──────────────────────────────────────────┤  │  │
 │  │  │ .page-container (flex 1, overflow hidden)│  │  │
 │  │  │   {children}                             │  │  │
@@ -135,13 +135,13 @@ type PageAction = () => any;
 </Page>
 ```
 
-### Header 扩展（headerExt snippet）
+### Header 扩展（headerExtra snippet）
 
 在默认 header 右侧加操作按钮：
 
 ```svelte
 <Page title="设置">
-  {#snippet headerExt()}
+  {#snippet headerExtra()}
     <button onclick={save}>保存</button>
     <button onclick={reset}>重置</button>
   {/snippet}
@@ -150,13 +150,13 @@ type PageAction = () => any;
 </Page>
 ```
 
-### 完全替换 header（pageHeader snippet）
+### 完全替换 header（header snippet）
 
 替换整个 header。snippet 接收 `(title, comment, goBack, reload)`：
 
 ```svelte
 <Page title="搜索结果" goBack={() => history.back()}>
-  {#snippet pageHeader(title, comment, goBack, reload)}
+  {#snippet header(title, comment, goBack, reload)}
     <div style="display: flex; align-items: center; gap: 12px; padding: 0 16px;">
       {#if goBack}
         <Icon name="icon_google_keyboard_backspace" onclick={goBack} />
@@ -172,7 +172,7 @@ type PageAction = () => any;
 </Page>
 ```
 
-> 用 `pageHeader` 覆盖时，`headerExt` snippet **被忽略** —— 扩展内容由你在 snippet 里自己渲染
+> 用 `header` 覆盖时，`headerExtra` snippet **被忽略** —— 扩展内容由你在 snippet 里自己渲染
 
 ### 极简（无圆角、无阴影）
 
@@ -200,7 +200,7 @@ type PageAction = () => any;
 <div class="uniface-page-wrapper" style="..." data-theme="...">
   <div class="uniface-page" class:round class:shadow>
     <div class="uniface-page-header">
-      <!-- pageHeader snippet 或默认 PageHeader -->
+      <!-- header snippet 或默认 PageHeader -->
     </div>
     <div class="page-container" style="{content$style}">
       <!-- children -->
@@ -209,7 +209,7 @@ type PageAction = () => any;
 </div>
 ```
 
-### 默认 PageHeader（未提供 `pageHeader` snippet 时）
+### 默认 PageHeader（未提供 `header` snippet 时）
 
 ```html
 <!-- goBack 或 reload 图标，只渲染一个 -->
@@ -220,7 +220,7 @@ type PageAction = () => any;
 <div class="page-topic"><span>{title}</span></div>
 <div class="page-comment"><span>{comment}</span></div>   <!-- 仅 comment 非空时 -->
 
-<!-- 提供了 headerExt snippet 时 -->
+<!-- 提供了 headerExtra snippet 时 -->
 ```
 
 header 元素内置样式：
@@ -262,20 +262,20 @@ header 元素内置样式：
 - **内容区裁剪溢出**（`overflow: hidden`）—— 不滚动。需要滚动自己包 `overflow: auto` 容器
 - **Page 占满父容器**。外层 wrapper 是 `width: 100%`，内层 page 是 `width: 100%; height: 100%`。放在有尺寸的父容器里
 - **点击防抖**：`goBack` / `reload` 走 [Icon](../../general/icon/README_CN.md) wrapper，会 await handler 后再加 200ms 冷却。快速连击不会重复触发
-- **`pageHeader` snippet 参数**：`(title, comment, goBack, reload)` —— 跟你传的 props 同值。用不用由你
+- **`header` snippet 参数**：`(title, comment, goBack, reload)` —— 跟你传的 props 同值。用不用由你
 
 ## 无障碍访问
 
-- back / reload 图标是 `aria-hidden="true"`（装饰性）。动作仅鼠标触发 —— 没有键盘激活。需要键盘支持就在 `headerExt` 里渲染自己的 `<button>`
-- 标题和注释是普通 `<span>` 文字 —— 无 heading 语义。需要文档大纲在 `pageHeader` snippet 里用 `<h1>` 包标题
+- back / reload 图标是 `aria-hidden="true"`（装饰性）。动作仅鼠标触发 —— 没有键盘激活。需要键盘支持就在 `headerExtra` 里渲染自己的 `<button>`
+- 标题和注释是普通 `<span>` 文字 —— 无 heading 语义。需要文档大纲在 `header` snippet 里用 `<h1>` 包标题
 - 没有 `role="main"` 或 landmark —— 想让 page 被识别为主内容区，自己在外层元素加 `role="main"`
 
 ## 最佳实践
 
 1. **嵌套路由传 `goBack`，实时数据页传 `reload`** —— 两者共用一个槽位，不要同时设
 2. **`comment` 用于上下文** —— 页面用途、记录数、最后更新时间。保持简短，会被截断
-3. **`headerExt` 用于操作**（保存、编辑、筛选），别挤进内容区
-4. **只在需要根本性不同的 header 时才覆盖 `pageHeader`**（比如 header 里放 tabs）。简单加东西用 `headerExt` 就够
+3. **`headerExtra` 用于操作**（保存、编辑、筛选），别挤进内容区
+4. **只在需要根本性不同的 header 时才覆盖 `header`**（比如 header 里放 tabs）。简单加东西用 `headerExtra` 就够
 5. **可滚动内容自己包** —— Page 的内容区是 `overflow: hidden`，不是 `auto`
 6. **配合 `Box` 在 page body 里分块** —— Page 给外壳，Box 给内部卡片
 

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

@@ -6,4 +6,4 @@ export interface MenuNode {
     children?: MenuNode[];
     expand?: boolean;
 }
-export type OnMenuClick = (item: MenuItem) => void;
+export type OnMenuItemClick = (item: MenuItem) => void;

package/dist/navigation/nav_menu/NavigatorMenu.svelte

@@ -1,28 +1,30 @@
 <script lang="ts">
     import {onMount} from "svelte";
+    import type {Direction} from "../../types";
     import type MenuItem from "./MenuItem";
-    import type {MenuNode, OnMenuClick} from "./MenuItem";
+    import type {MenuNode, OnMenuItemClick} from "./MenuItem";
     import NavigatorMenuItem from "./NavigatorMenuItem.svelte";
 
     type GetText<T> = (item: T) => string;
-    type Variant = 'vertical' | 'horizontal';
 
     interface Props {
-        menuItems: Array<MenuNode>;
+        /** 菜单节点列表 */
+        items?: Array<MenuNode>;
         style?: string;
         textField: string | GetText<MenuItem>;
-        onItemClick: OnMenuClick;
-        variant?: Variant;
+        onItemClick: OnMenuItemClick;
+        /** 菜单方向 */
+        direction?: Direction;
         theme?: string;
     }
 
     let {
-        menuItems,
+        items = [],
         style = '',
         textField,
         onItemClick,
-        variant = 'vertical',
-        theme = ''
+        direction = 'vertical',
+        theme
     }: Props = $props();
 
     // 横向模式：当前展开的 root 索引（同时只开一个 dropdown）
@@ -101,11 +103,11 @@
     });
 </script>
 
-{#if variant === 'vertical'}
+{#if direction === 'vertical'}
     <div class="uniface-navigator-menu vertical" {style} data-theme={theme || undefined}>
-        {#if menuItems && menuItems.length > 0}
+        {#if items && items.length > 0}
             <ul>
-                {#each menuItems as menu}
+                {#each items as menu}
                     <NavigatorMenuItem {menu} onMenuItemClick={onItemClick} {textField}/>
                 {/each}
             </ul>
@@ -120,7 +122,7 @@
         {/if}
         <div bind:this={scrollViewport} class="scroll-viewport" onscroll={updateScrollState}>
             <div bind:this={scrollTrack} class="scroll-track">
-                {#each menuItems as root, idx (idx)}
+                {#each items as root, idx (idx)}
                     <div
                         class="root-item"
                         class:open={openRootIdx === idx}
@@ -143,14 +145,14 @@
                 <i aria-hidden="true"></i>
             </button>
         {/if}
-        {#if openRootIdx !== null && menuItems[openRootIdx]?.children?.length}
+        {#if openRootIdx !== null && items[openRootIdx]?.children?.length}
             <div
                 class="dropdown-panel"
                 style:left="{dropdownLeft}px"
                 use:outerClick={() => { openRootIdx = null; }}
             >
                 <ul class="dropdown">
-                    {#each menuItems[openRootIdx].children ?? [] as child}
+                    {#each items[openRootIdx].children ?? [] as child}
                         <NavigatorMenuItem menu={child} onMenuItemClick={handleLeafClickInDropdown} {textField} cascade={true}/>
                     {/each}
                 </ul>

package/dist/navigation/nav_menu/NavigatorMenu.svelte.d.ts

@@ -1,13 +1,15 @@
+import type { Direction } from "../../types";
 import type MenuItem from "./MenuItem";
-import type { MenuNode, OnMenuClick } from "./MenuItem";
+import type { MenuNode, OnMenuItemClick } from "./MenuItem";
 type GetText<T> = (item: T) => string;
-type Variant = 'vertical' | 'horizontal';
 interface Props {
-    menuItems: Array<MenuNode>;
+    /** 菜单节点列表 */
+    items?: Array<MenuNode>;
     style?: string;
     textField: string | GetText<MenuItem>;
-    onItemClick: OnMenuClick;
-    variant?: Variant;
+    onItemClick: OnMenuItemClick;
+    /** 菜单方向 */
+    direction?: Direction;
     theme?: string;
 }
 declare const NavigatorMenu: import("svelte").Component<Props, {}, "">;

package/dist/navigation/nav_menu/NavigatorMenuItem.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
     import {slide, fly} from "svelte/transition";
     import type MenuItem from "./MenuItem";
-    import type {MenuNode, OnMenuClick} from "./MenuItem";
+    import type {MenuNode, OnMenuItemClick} from "./MenuItem";
     import NavigatorMenuItem from "./NavigatorMenuItem.svelte";
 
     type GetText<T> = (item: T) => string;
@@ -9,7 +9,7 @@
     interface Props {
         menu: MenuNode;
         textField: string | GetText<MenuItem>;
-        onMenuItemClick: OnMenuClick;
+        onMenuItemClick: OnMenuItemClick;
         defaultExpand?: boolean;
         /**
          * 子菜单以级联方式展开（向右飞出，空间不够时向左）。

package/dist/navigation/nav_menu/NavigatorMenuItem.svelte.d.ts

@@ -1,11 +1,11 @@
 import type MenuItem from "./MenuItem";
-import type { MenuNode, OnMenuClick } from "./MenuItem";
+import type { MenuNode, OnMenuItemClick } from "./MenuItem";
 import NavigatorMenuItem from "./NavigatorMenuItem.svelte";
 type GetText<T> = (item: T) => string;
 interface Props {
     menu: MenuNode;
     textField: string | GetText<MenuItem>;
-    onMenuItemClick: OnMenuClick;
+    onMenuItemClick: OnMenuItemClick;
     defaultExpand?: boolean;
     /**
      * 子菜单以级联方式展开（向右飞出，空间不够时向左）。

package/dist/navigation/nav_menu/README.md

@@ -1,5 +1,7 @@
 # NavigatorMenu Component
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `menuItems` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A hierarchical navigation menu component built with Svelte 5, supporting nested menu items with expand/collapse functionality.
 
 ## Features
@@ -35,7 +37,7 @@ import type MenuItem from '$lib/nav-menu/MenuItem';
 <script>
   import { NavigatorMenu } from '$lib/nav-menu';
 
-  let menuItems = $state([
+  let items = $state([
     {
       item: { label: 'Dashboard', path: '/dashboard' },
       children: []
@@ -55,7 +57,7 @@ import type MenuItem from '$lib/nav-menu/MenuItem';
 </script>
 
 <NavigatorMenu
-  menuItems={menuItems}
+  items={items}
   textField="label"
   onItemClick={handleMenuClick}
 />
@@ -65,7 +67,7 @@ import type MenuItem from '$lib/nav-menu/MenuItem';
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `menuItems` | `Array<MenuItem>` | Yes | Array of menu item objects |
+| `items` | `Array<MenuItem>` | Yes | Array of menu item objects |
 | `textField` | `string \| GetText<MenuItem>` | Yes | Field name or function to get display text |
 | `onItemClick` | `(item: MenuItem) => void` | Yes | Callback when a menu item is clicked |
 | `style` | `string` | No | Custom inline styles |
@@ -99,7 +101,7 @@ interface MenuItem {
 </script>
 
 <NavigatorMenu
-  menuItems={simpleMenu}
+  items={simpleMenu}
   textField="name"
   onItemClick={(item) => console.log(item)}
 />
@@ -138,7 +140,7 @@ interface MenuItem {
 </script>
 
 <NavigatorMenu
-  menuItems={nestedMenu}
+  items={nestedMenu}
   textField="title"
   onItemClick={(item) => navigate(item.path)}
 />
@@ -163,7 +165,7 @@ interface MenuItem {
 </script>
 
 <NavigatorMenu
-  menuItems={customMenu}
+  items={customMenu}
   textField={getText}
   onItemClick={(item) => console.log(item)}
 />

package/dist/navigation/nav_menu/README_CN.md

@@ -1,5 +1,7 @@
 # NavigatorMenu 导航菜单组件
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `menuItems` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 基于 Svelte 5 构建的分层导航菜单组件，支持具有展开/折叠功能的嵌套菜单项。
 
 ## 特性
@@ -35,7 +37,7 @@ import type MenuItem from '$lib/nav-menu/MenuItem';
 <script>
   import { NavigatorMenu } from '$lib/nav-menu';
 
-  let menuItems = $state([
+  let items = $state([
     {
       item: { label: '仪表板', path: '/dashboard' },
       children: []
@@ -55,7 +57,7 @@ import type MenuItem from '$lib/nav-menu/MenuItem';
 </script>
 
 <NavigatorMenu
-  menuItems={menuItems}
+  items={items}
   textField="label"
   onItemClick={handleMenuClick}
 />
@@ -65,7 +67,7 @@ import type MenuItem from '$lib/nav-menu/MenuItem';
 
 | 属性 | 类型 | 必填 | 描述 |
 |------|------|------|-------------|
-| `menuItems` | `Array<MenuItem>` | 是 | 菜单项对象数组 |
+| `items` | `Array<MenuItem>` | 是 | 菜单项对象数组 |
 | `textField` | `string \| GetText<MenuItem>` | 是 | 字段名称或获取显示文本的函数 |
 | `onItemClick` | `(item: MenuItem) => void` | 是 | 点击菜单项时的回调 |
 | `style` | `string` | 否 | 自定义内联样式 |
@@ -99,7 +101,7 @@ interface MenuItem {
 </script>
 
 <NavigatorMenu
-  menuItems={simpleMenu}
+  items={simpleMenu}
   textField="name"
   onItemClick={(item) => console.log(item)}
 />
@@ -138,7 +140,7 @@ interface MenuItem {
 </script>
 
 <NavigatorMenu
-  menuItems={nestedMenu}
+  items={nestedMenu}
   textField="title"
   onItemClick={(item) => navigate(item.path)}
 />
@@ -163,7 +165,7 @@ interface MenuItem {
 </script>
 
 <NavigatorMenu
-  menuItems={customMenu}
+  items={customMenu}
   textField={getText}
   onItemClick={(item) => console.log(item)}
 />

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

@@ -1,8 +1,8 @@
 import NavigatorMenu from "./NavigatorMenu.svelte";
 import type MenuItem from "./MenuItem";
 import type { MenuNode } from "./MenuItem";
-import type { OnMenuClick } from "./MenuItem";
+import type { OnMenuItemClick } from "./MenuItem";
 import Menus from "./Menus";
 export default NavigatorMenu;
-export type { MenuItem, MenuNode, OnMenuClick };
+export type { MenuItem, MenuNode, OnMenuItemClick };
 export { Menus };

package/dist/navigation/navigator/Navigator.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
     import {NavItemStatus} from "./NavItemStatus";
 
-    type ItemClickHandler = (item: any) => void;
+    type OnItemClick = (item: any) => void;
     type RetrieveItemStatus = (item: any) => NavItemStatus;
 
     interface Props {
@@ -9,7 +9,8 @@
         activeItem?: any;
         style?: string;
         highlights?: Array<any>;
-        itemClickHandler?: ItemClickHandler;
+        /** 项点击回调 */
+        onItemClick?: OnItemClick;
         retrieveStatus?: RetrieveItemStatus;
     }
 
@@ -18,13 +19,13 @@
         activeItem = $bindable(),
         style = "",
         highlights = [],
-        itemClickHandler,
+        onItemClick,
         retrieveStatus
     }: Props = $props();
 
     const handleClick = (item: any) => {
         activeItem = item;
-        itemClickHandler?.(item);
+        onItemClick?.(item);
     };
 
     const handleKeyDown = (item: any) => (e: KeyboardEvent) => {

package/dist/navigation/navigator/Navigator.svelte.d.ts

@@ -1,12 +1,13 @@
 import { NavItemStatus } from "./NavItemStatus";
-type ItemClickHandler = (item: any) => void;
+type OnItemClick = (item: any) => void;
 type RetrieveItemStatus = (item: any) => NavItemStatus;
 interface Props {
     items: Array<any>;
     activeItem?: any;
     style?: string;
     highlights?: Array<any>;
-    itemClickHandler?: ItemClickHandler;
+    /** 项点击回调 */
+    onItemClick?: OnItemClick;
     retrieveStatus?: RetrieveItemStatus;
 }
 declare const Navigator: import("svelte").Component<Props, {}, "activeItem">;

package/dist/navigation/navigator/README.md

@@ -1,5 +1,7 @@
 # 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
@@ -8,7 +10,7 @@ A vertical step / wizard navigator. Renders items as a clickable list with a con
 - **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 `itemClickHandler`
+- **Two-way bindable `activeItem`**: `bind:activeItem` updates on click without needing `onItemClick`
 - **Scrolls vertically** when items overflow
 
 ## Installation
@@ -53,16 +55,16 @@ import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
 />
 ```
 
-With `bind:activeItem`, clicking an item updates `activeItem` directly. No `itemClickHandler` needed unless you want to run side effects (analytics, validation, route change).
+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 `itemClickHandler`. |
+| `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. |
-| `itemClickHandler` | `((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`. |
+| `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 |
 
@@ -207,7 +209,7 @@ Or globally:
   bind:activeItem
   highlights={highlights}
   retrieveStatus={getStepStatus}
-  itemClickHandler={handleClick}
+  onItemClick={handleClick}
 />
 
 <div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
@@ -265,14 +267,14 @@ If you want display-only (no click):
 />
 ```
 
-Clicks will still update `activeItem` internally (if `bind:` or `itemClickHandler` is set), but you can omit both and let the component be effectively display-only. Without `bind:` or `itemClickHandler`, internal state still updates but no one hears about it.
+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 `itemClickHandler`. The component is internally consistent — but the parent won't know.
-- **`handleClick` runs `activeItem = item` first**, then `itemClickHandler?.(item)`. If you want to **prevent** the active change (e.g. user hasn't completed prerequisites), you need to undo it inside `itemClickHandler` by setting `activeItem` back. There's no `canActivate` predicate.
+- **`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.
 
@@ -290,10 +292,10 @@ If you need keyboard-accessible step navigation, wrap each item in your own `<bu
 ## 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 `itemClickHandler` for plain state sync. Add `itemClickHandler` only for side effects.
+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 `itemClickHandler` if the user clicks ahead. There's no built-in guard.
+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

package/dist/navigation/navigator/README_CN.md

@@ -1,5 +1,7 @@
 # Navigator 步骤导航组件
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `itemClickHandler` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 垂直的步骤 / 向导导航器。把项目渲染为可点击列表，左侧有连接的竖线，当前项有圆形标记，每项有状态颜色（完成 / 警告 / 未开始），还可以选择性高亮。专为多步表单和引导式流程设计。
 
 ## 功能特性
@@ -8,7 +10,7 @@
 - **三种状态**：`Completed`、`Warning`（红点）、`NotStart`（斜体、变淡） —— 通过 `retrieveStatus` 回调驱动
 - **当前项标记**：active 项左侧显示 15px 圆形边框
 - **高亮数组**：给任意项加"看我"颜色（比如有错误的项）
-- **`activeItem` 双向绑定**：`bind:activeItem` 在点击时自动更新，不需要 `itemClickHandler`
+- **`activeItem` 双向绑定**：`bind:activeItem` 在点击时自动更新，不需要 `onItemClick`
 - **纵向滚动**，内容溢出时
 
 ## 安装
@@ -53,16 +55,16 @@ import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
 />
 ```
 
-用 `bind:activeItem` 后，点击项直接更新 `activeItem`。不需要 `itemClickHandler` —— 除非要跑副作用（埋点、校验、路由切换）。
+用 `bind:activeItem` 后，点击项直接更新 `activeItem`。不需要 `onItemClick` —— 除非要跑副作用（埋点、校验、路由切换）。
 
 ## 属性
 
 | 属性 | 类型 | 默认值 | 描述 |
 |------|------|---------|-------------|
 | `items` | `Array<any>` | _(必填)_ | 导航项。每项**必须有 `text` 属性**作为标签。其他字段随你 |
-| `activeItem` | `any` | `$bindable(undefined)` | 当前 active 项。**`bind:activeItem`** 双向绑定；点击时组件先把点击项赋给它，再调 `itemClickHandler` |
+| `activeItem` | `any` | `$bindable(undefined)` | 当前 active 项。**`bind:activeItem`** 双向绑定；点击时组件先把点击项赋给它，再调 `onItemClick` |
 | `highlights` | `Array<any>` | `[]` | 要高亮的项（如出错的项）。按引用相等匹配 |
-| `itemClickHandler` | `((item: any) => void) \| undefined` | `undefined` | 每次点击调用，**在 `activeItem` 更新之后**。用于副作用；如果用了 `bind:activeItem` 就不需要它做状态更新 |
+| `onItemClick` | `((item: any) => void) \| undefined` | `undefined` | 每次点击调用，**在 `activeItem` 更新之后**。用于副作用；如果用了 `bind:activeItem` 就不需要它做状态更新 |
 | `retrieveStatus` | `((item: any) => NavItemStatus) \| undefined` | `undefined` | 返回每项的状态。**不传时所有项默认 `Completed`** |
 | `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
 
@@ -207,7 +209,7 @@ CSS 类名就是枚举值（`NavItemStatus.Completed === 'nav-completed'`），
   bind:activeItem
   highlights={highlights}
   retrieveStatus={getStepStatus}
-  itemClickHandler={handleClick}
+  onItemClick={handleClick}
 />
 
 <div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
@@ -265,14 +267,14 @@ CSS 类名就是枚举值（`NavItemStatus.Completed === 'nav-completed'`），
 />
 ```
 
-点击仍然会内部更新 `activeItem`（如果用了 `bind:` 或 `itemClickHandler`），但你可以两个都不传，让组件事实上只展示。没有 `bind:` 或 `itemClickHandler` 时内部状态仍然更新，但没人能知道。
+点击仍然会内部更新 `activeItem`（如果用了 `bind:` 或 `onItemClick`），但你可以两个都不传，让组件事实上只展示。没有 `bind:` 或 `onItemClick` 时内部状态仍然更新，但没人能知道。
 
 ## 行为说明
 
 - **项按引用匹配，不是值。** 渲染间重建 `items` 数组（如 `.map`）会丢失 `activeItem` / `highlights` 匹配。保持 `items` 引用稳定
 - **`retrieveStatus` 不传时默认 `Completed`**。忘了传的话每项看起来都是"已完成"
-- **每次点击内部都更新 `activeItem`**，即使不用 `bind:` 或不传 `itemClickHandler`。组件内部自洽 —— 但父组件不会知道
-- **`handleClick` 先执行 `activeItem = item`**，再执行 `itemClickHandler?.(item)`。如果想**阻止** active 变更（比如用户没完成前置步骤），需要在 `itemClickHandler` 内部把 `activeItem` 设回去。没有 `canActivate` 谓词
+- **每次点击内部都更新 `activeItem`**，即使不用 `bind:` 或不传 `onItemClick`。组件内部自洽 —— 但父组件不会知道
+- **`handleClick` 先执行 `activeItem = item`**，再执行 `onItemClick?.(item)`。如果想**阻止** active 变更（比如用户没完成前置步骤），需要在 `onItemClick` 内部把 `activeItem` 设回去。没有 `canActivate` 谓词
 - **每项都有 `aria-hidden="true"`** —— 尽管是可点击 div，但屏幕阅读器看不到。这是 a11y 问题 —— 见下
 - **长标签横向裁剪**，不换行。wrapper 是单行
 
@@ -290,10 +292,10 @@ CSS 类名就是枚举值（`NavItemStatus.Completed === 'nav-completed'`），
 ## 最佳实践
 
 1. **保持 `items` 引用稳定。** 定义一次（模块作用域或不重新赋值的 `$state`）。每次渲染 map 会破坏 active / 高亮匹配
-2. **用 `bind:activeItem`** 而不是 `itemClickHandler` 做纯状态同步。`itemClickHandler` 只在需要副作用时加
+2. **用 `bind:activeItem`** 而不是 `onItemClick` 做纯状态同步。`onItemClick` 只在需要副作用时加
 3. **永远传 `retrieveStatus`**，除非你真的想每项默认看起来都是已完成
 4. **`Warning` + `highlights` 一起用**做错误状态 —— 红点抓眼球，高亮色加强
-5. **只能向后的向导**，在 `itemClickHandler` 里撤销越界点击的 active 变更。没有内置守卫
+5. **只能向后的向导**，在 `onItemClick` 里撤销越界点击的 active 变更。没有内置守卫
 6. **不要给键盘 / 屏幕阅读器用户用这个。** 见上面 a11y 说明
 
 ## 相关组件