@ticatec/uniface-element 5.0.5 → 5.1.1

package/dist/navigation/pagination/Pagination.svelte

@@ -1,33 +1,35 @@
 <script lang="ts">
 
 
-    import type {OnPageChange} from "../../types";
+    import type {OnPageChange, Size} from "../../types";
 
     interface Props {
         pageCount: number;
         pageNo?: number;
-        type?: 'plain' | 'round' | 'circle';
+        /** 形状：plain / round / circle */
+        variant?: 'plain' | 'round' | 'circle';
         style?: string;
-        big?: boolean;
+        /** 尺寸档位；'large' 对应旧的 big */
+        size?: Size;
         theme?: string;
         onchange?: OnPageChange;
     }
 
     let {
         pageCount = 0,
-        pageNo = 1,
-        type = "round",
+        pageNo = $bindable(1),
+        variant = "round",
         style = '',
-        big = false,
+        size = 'medium',
         theme,
         onchange
     }: Props = $props();
 
     let pagination = $state<Array<number | null>>([]);
 
-    // Derived rather than mutating the pageNo prop directly: pageNo isn't
-    // $bindable, so writing to it only ever changed a local copy for one
-    // render and never reached the parent.
+    // Clamp the (bindable) pageNo into range without writing it back: the parent
+    // owns the value; user navigation goes through changePage() which updates the
+    // binding and then notifies via onchange.
     let normalizedPageNo = $derived.by(() => {
         if (pageCount <= 0) return 0;
         if (pageNo < 1) return 1;
@@ -67,9 +69,15 @@
         pagination = arr;
     }
 
+    // Single exit point for user navigation: update the two-way binding first, then notify.
+    const changePage = (value: number) => {
+        pageNo = value;
+        onchange?.(value);
+    };
+
     const selectPage = (value: number) => () => {
         if (normalizedPageNo != value) {
-            onchange?.(value);
+            changePage(value);
         }
     };
 
@@ -84,11 +92,11 @@
     let hasNext = $derived(pageCount > 0 && normalizedPageNo < pageCount);
 
     const goPrev = () => {
-        if (hasPrev) onchange?.(normalizedPageNo - 1);
+        if (hasPrev) changePage(normalizedPageNo - 1);
     };
 
     const goNext = () => {
-        if (hasNext) onchange?.(normalizedPageNo + 1);
+        if (hasNext) changePage(normalizedPageNo + 1);
     };
 
     const handleNavKeyDown = (action: () => void) => (e: KeyboardEvent) => {
@@ -103,7 +111,7 @@
     });
 </script>
 
-<div class="uniface-pagination-panel {type}" class:big {style} data-theme={theme} role="navigation" aria-label="Pagination">
+<div class="uniface-pagination-panel {variant}" class:big={size === 'large'} {style} data-theme={theme} role="navigation" aria-label="Pagination">
     <div class="uniface-page-nav" class:disabled={!hasPrev} role="button" tabindex={hasPrev ? 0 : -1}
          aria-label="Previous page" aria-disabled={!hasPrev} onclick={goPrev} onkeydown={handleNavKeyDown(goPrev)}>
         <i class="icon_google_keyboard_arrow_left" aria-hidden="true"></i>
@@ -249,7 +257,7 @@
         height: 3em;
     }
 
-    /* Plain type */
+    /* Plain variant */
     .uniface-pagination-panel.plain .uniface-page-no {
         background-color: inherit;
         border: none;
@@ -273,7 +281,7 @@
         color: var(--uniface-pagination-selected-background-color, #333333);
     }
 
-    /* Circle type */
+    /* Circle variant */
     .uniface-pagination-panel.circle .uniface-page-no {
         border-radius: 50%;
     }

package/dist/navigation/pagination/Pagination.svelte.d.ts

@@ -1,13 +1,15 @@
-import type { OnPageChange } from "../../types";
+import type { OnPageChange, Size } from "../../types";
 interface Props {
     pageCount: number;
     pageNo?: number;
-    type?: 'plain' | 'round' | 'circle';
+    /** 形状：plain / round / circle */
+    variant?: 'plain' | 'round' | 'circle';
     style?: string;
-    big?: boolean;
+    /** 尺寸档位；'large' 对应旧的 big */
+    size?: Size;
     theme?: string;
     onchange?: OnPageChange;
 }
-declare const Pagination: import("svelte").Component<Props, {}, "">;
+declare const Pagination: import("svelte").Component<Props, {}, "pageNo">;
 type Pagination = ReturnType<typeof Pagination>;
 export default Pagination;

package/dist/navigation/progress_step_bar/ProgressStep.d.ts

@@ -7,7 +7,8 @@ export default interface ProgressStep {
     /**
      *
      */
-    topic: string;
+    /** 步骤标题 */
+    title: string;
     /**
      *
      */

package/dist/navigation/progress_step_bar/ProgressStepBar.svelte

@@ -3,14 +3,15 @@
     import ProgressStepBlock from "./ProgressStepBlock.svelte";
 
     interface Props {
-        steps: Array<ProgressStep>;
+        /** 步骤列表 */
+        items?: Array<ProgressStep>;
         direction?: 'vertical' | 'horizontal';
         style?: string;
         theme?: string;
     }
 
     let {
-        steps,
+        items = [],
         direction = 'horizontal',
         style,
         theme
@@ -20,8 +21,8 @@
 
 <div class="uniface-progress-step-container {direction}" data-theme={theme} {style}>
     <div class="container-panel">
-        {#each steps as step, idx}
-            <ProgressStepBlock pos={idx+1} status={step.status} comment={step.comment} topic={step.topic} {direction}/>
+        {#each items as step, idx}
+            <ProgressStepBlock pos={idx+1} status={step.status} comment={step.comment} title={step.title} {direction}/>
         {/each}
     </div>
 </div>

package/dist/navigation/progress_step_bar/ProgressStepBar.svelte.d.ts

@@ -1,6 +1,7 @@
 import type ProgressStep from "./ProgressStep";
 interface Props {
-    steps: Array<ProgressStep>;
+    /** 步骤列表 */
+    items?: Array<ProgressStep>;
     direction?: 'vertical' | 'horizontal';
     style?: string;
     theme?: string;

package/dist/navigation/progress_step_bar/ProgressStepBlock.svelte

@@ -4,7 +4,7 @@
     interface Props {
         status: ProgressStepStatus;
         pos?: number;
-        topic: string;
+        title: string;
         comment?: string;
         style?: string;
         direction: 'vertical' | 'horizontal';
@@ -13,7 +13,7 @@
     let {
         status,
         pos = 1,
-        topic,
+        title,
         comment = '',
         style = '',
         direction
@@ -34,7 +34,7 @@
     </div>
     <div class="step-text {status}">
         <div class="step-topic" >
-            <span>{topic}</span>
+            <span>{title}</span>
         </div>
         {#if comment}
             <div class="step-comment">

package/dist/navigation/progress_step_bar/ProgressStepBlock.svelte.d.ts

@@ -2,7 +2,7 @@ import { ProgressStepStatus } from "./ProgressStep";
 interface Props {
     status: ProgressStepStatus;
     pos?: number;
-    topic: string;
+    title: string;
     comment?: string;
     style?: string;
     direction: 'vertical' | 'horizontal';

package/dist/navigation/progress_step_bar/README.md

@@ -1,5 +1,7 @@
 # ProgressStepBar Component
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `steps`, `topic` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A multi-step progress indicator showing sequential steps with their completion status. Renders numbered circles connected by a line; each step is `Pending`, `Processing`, or `Completed`. Supports horizontal (default) and vertical layouts. Pure display — no click handlers.
 
 ## Features
@@ -28,22 +30,22 @@ import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec
 <script lang="ts">
   import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
 
-  const steps: ProgressStep[] = [
-    { topic: 'Registration', comment: 'Complete your profile',   status: ProgressStepStatus.Completed },
-    { topic: 'Verification', comment: 'Verify your email',        status: ProgressStepStatus.Processing },
-    { topic: 'Setup',        comment: 'Configure preferences',    status: ProgressStepStatus.Pending }
+  const items: ProgressStep[] = [
+    { title: 'Registration', comment: 'Complete your profile',   status: ProgressStepStatus.Completed },
+    { title: 'Verification', comment: 'Verify your email',        status: ProgressStepStatus.Processing },
+    { title: 'Setup',        comment: 'Configure preferences',    status: ProgressStepStatus.Pending }
   ];
 </script>
 
-<ProgressStepBar {steps} />
+<ProgressStepBar {items} />
 ```
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `steps` | `ProgressStep[]` | _(required)_ | Ordered list of steps. Each step's position in the array determines its number (`pos` displayed as `idx + 1`). |
-| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. Horizontal = row of left-to-right steps; vertical = column of top-to-bottom steps. |
+| `items` | `ProgressStep[]` | _(required)_ | Ordered list of items. Each step's position in the array determines its number (`pos` displayed as `idx + 1`). |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. Horizontal = row of left-to-right items; vertical = column of top-to-bottom items. |
 | `style` | `string` | `''` | Inline CSS on the outer wrapper |
 | `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
 
@@ -51,8 +53,8 @@ import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec
 
 ```typescript
 interface ProgressStep {
-  topic: string;              // Step title (required)
-  comment?: string;           // Optional secondary text shown below the topic
+  title: string;              // Step title (required)
+  comment?: string;           // Optional secondary text shown below the title
   status: ProgressStepStatus; // Current status
 }
 ```
@@ -113,7 +115,7 @@ Rendered output:
         </div>
       </div>
       <div class="step-text {status}">
-        <div class="step-topic"><span>{topic}</span></div>
+        <div class="step-topic"><span>{title}</span></div>
         <!-- only if comment provided -->
         <div class="step-comment"><span>{comment}</span></div>
       </div>
@@ -130,10 +132,10 @@ Rendered output:
 | `--uniface-progress-step-bar-color-surface` | Container background (also used as the "background behind the line" so the line appears to break around the circle) |
 | `--uniface-progress-step-bar-bg` | Foreground inside processing circle (default white) |
 | `--uniface-progress-step-pending-color` | Pending circle border + line + text (gray) |
-| `--uniface-progress-step-completed-color` | Completed topic/comment text (dark gray) |
+| `--uniface-progress-step-completed-color` | Completed title/comment text (dark gray) |
 | `--uniface-progress-step-completed-icon-color` | Completed circle border + checkmark + line (blue) |
 | `--uniface-progress-step-completed-icon-bg` | Completed circle background (light blue tint) |
-| `--uniface-progress-step-processing-color` | Processing circle fill + topic text (blue) |
+| `--uniface-progress-step-processing-color` | Processing circle fill + title text (blue) |
 
 ### How the connector line works
 
@@ -149,26 +151,26 @@ This is fragile — if you change `--uniface-progress-step-bar-color-surface` to
 <script lang="ts">
   import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
 
-  let steps = $state<ProgressStep[]>([
-    { topic: 'Initialization', comment: 'Setting up...',  status: ProgressStepStatus.Pending },
-    { topic: 'Data Loading',   comment: 'Fetching data...',status: ProgressStepStatus.Pending },
-    { topic: 'Processing',     comment: 'Analyzing...',    status: ProgressStepStatus.Pending },
-    { topic: 'Completion',     comment: 'Finalizing...',   status: ProgressStepStatus.Pending }
+  let items = $state<ProgressStep[]>([
+    { title: 'Initialization', comment: 'Setting up...',  status: ProgressStepStatus.Pending },
+    { title: 'Data Loading',   comment: 'Fetching data...',status: ProgressStepStatus.Pending },
+    { title: 'Processing',     comment: 'Analyzing...',    status: ProgressStepStatus.Pending },
+    { title: 'Completion',     comment: 'Finalizing...',   status: ProgressStepStatus.Pending }
   ]);
 
   let currentIdx = 0;
 
   function advance() {
-    if (currentIdx >= steps.length) return;
+    if (currentIdx >= items.length) return;
 
-    steps[currentIdx].status = ProgressStepStatus.Processing;
+    items[currentIdx].status = ProgressStepStatus.Processing;
 
     setTimeout(() => {
-      steps[currentIdx].status = ProgressStepStatus.Completed;
+      items[currentIdx].status = ProgressStepStatus.Completed;
       currentIdx++;
 
-      if (currentIdx < steps.length) {
-        steps[currentIdx].status = ProgressStepStatus.Processing;
+      if (currentIdx < items.length) {
+        items[currentIdx].status = ProgressStepStatus.Processing;
         advance();
       }
     }, 1500);
@@ -177,14 +179,14 @@ This is fragile — if you change `--uniface-progress-step-bar-color-surface` to
   advance();
 </script>
 
-<ProgressStepBar {steps} />
+<ProgressStepBar {items} />
 ```
 
 ### Vertical Layout
 
 ```svelte
 <div style="height: 480px;">
-  <ProgressStepBar {steps} direction="vertical" />
+  <ProgressStepBar {items} direction="vertical" />
 </div>
 ```
 
@@ -199,22 +201,22 @@ For a "your order is at step N" type view:
   import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
 
   const orderSteps: ProgressStep[] = [
-    { topic: 'Order Placed',    status: ProgressStepStatus.Completed },
-    { topic: 'Payment Cleared', status: ProgressStepStatus.Completed },
-    { topic: 'Shipped',         status: ProgressStepStatus.Processing },
-    { topic: 'Out for Delivery',status: ProgressStepStatus.Pending },
-    { topic: 'Delivered',       status: ProgressStepStatus.Pending }
+    { title: 'Order Placed',    status: ProgressStepStatus.Completed },
+    { title: 'Payment Cleared', status: ProgressStepStatus.Completed },
+    { title: 'Shipped',         status: ProgressStepStatus.Processing },
+    { title: 'Out for Delivery',status: ProgressStepStatus.Pending },
+    { title: 'Delivered',       status: ProgressStepStatus.Pending }
   ];
 </script>
 
-<ProgressStepBar steps={orderSteps} />
+<ProgressStepBar items={orderSteps} />
 ```
 
 ## Behavior Notes
 
 - **Pure display.** No click handlers — users can't jump between steps. Pair with [Navigator](../navigator/README.md) if you need interactive step navigation.
-- **Reactive.** Mutate `steps[i].status` (with `$state` array) and the UI updates. The component re-renders via Svelte 5 reactivity.
-- **`topic` truncates with `…`** (`white-space: nowrap; text-overflow: ellipsis`). Keep topics short.
+- **Reactive.** Mutate `items[i].status` (with `$state` array) and the UI updates. The component re-renders via Svelte 5 reactivity.
+- **`title` truncates with `…`** (`white-space: nowrap; text-overflow: ellipsis`). Keep topics short.
 - **`comment` is multi-line** but doesn't have its own truncation — long comments can break the layout.
 - **First step has no left margin**; subsequent steps use `margin-left: 8px` (horizontal) or no margin (vertical, since the line connects vertically).
 - **Last step keeps the line** for visual continuity — there's a `.progress-step-block:last-child` rule but it's empty in horizontal mode. In vertical mode, the line is unset on the last step.
@@ -223,7 +225,7 @@ For a "your order is at step N" type view:
 
 - **Purely visual.** No ARIA roles, no `aria-current` for the processing step, no `aria-label` on the indicators.
 - The checkmark `✔` is literal Unicode text — screen readers will read "check mark". Consider replacing with an icon font + `aria-hidden="true"` in a fork if it's noisy.
-- Step status (Pending / Processing / Completed) is conveyed by color + circle fill alone — no text alternative. Add `aria-label="Step N: {topic}, {status}"` on each block in a fork for screen-reader support.
+- Step status (Pending / Processing / Completed) is conveyed by color + circle fill alone — no text alternative. Add `aria-label="Step N: {title}, {status}"` on each block in a fork for screen-reader support.
 - No keyboard interaction (purely display, so this is fine).
 
 ## Known Quirks
@@ -232,8 +234,8 @@ For a "your order is at step N" type view:
 
 ## Best Practices
 
-1. **Use `$state` for the `steps` array** if you want live progress updates. Mutating `steps[i].status` re-renders.
-2. **Keep `topic` short** — it truncates with `…`. Move detail to `comment`.
+1. **Use `$state` for the `items` array** if you want live progress updates. Mutating `items[i].status` re-renders.
+2. **Keep `title` short** — it truncates with `…`. Move detail to `comment`.
 3. **Use `direction="vertical"` only inside a height-constrained parent** (sidebar, drawer). Otherwise it collapses.
 4. **One `Processing` step at a time** — having multiple gives a confusing visual. Mark earlier steps `Completed`.
 5. **Override colors via CSS variables**, not by styling the inner classes — the structure is fragile (see connector line note).

package/dist/navigation/progress_step_bar/README_CN.md

@@ -1,5 +1,7 @@
 # ProgressStepBar 步骤进度条组件
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `steps`, `topic` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 多步骤进度指示器，按顺序显示各步骤的完成状态。渲染带编号的圆圈，圆圈之间用线连接；每步是 `Pending`、`Processing` 或 `Completed`。支持横向（默认）和纵向布局。纯展示组件 —— 无点击 handler。
 
 ## 功能特性
@@ -28,21 +30,21 @@ import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec
 <script lang="ts">
   import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
 
-  const steps: ProgressStep[] = [
-    { topic: '注册',   comment: '完善资料',     status: ProgressStepStatus.Completed },
-    { topic: '验证',   comment: '验证邮箱',     status: ProgressStepStatus.Processing },
-    { topic: '设置',   comment: '配置偏好',     status: ProgressStepStatus.Pending }
+  const items: ProgressStep[] = [
+    { title: '注册',   comment: '完善资料',     status: ProgressStepStatus.Completed },
+    { title: '验证',   comment: '验证邮箱',     status: ProgressStepStatus.Processing },
+    { title: '设置',   comment: '配置偏好',     status: ProgressStepStatus.Pending }
   ];
 </script>
 
-<ProgressStepBar {steps} />
+<ProgressStepBar {items} />
 ```
 
 ## 属性
 
 | 属性 | 类型 | 默认值 | 描述 |
 |------|------|---------|-------------|
-| `steps` | `ProgressStep[]` | _(必填)_ | 有序步骤列表。每项在数组中的位置决定其编号（显示为 `idx + 1`） |
+| `items` | `ProgressStep[]` | _(必填)_ | 有序步骤列表。每项在数组中的位置决定其编号（显示为 `idx + 1`） |
 | `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 布局方向。横向 = 从左到右一行；纵向 = 从上到下一列 |
 | `style` | `string`\| undefined` | `undefined`  | 外层 wrapper 的内联 CSS |
 | `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
@@ -51,8 +53,8 @@ import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec
 
 ```typescript
 interface ProgressStep {
-  topic: string;              // 步骤标题（必填）
-  comment?: string;           // 可选的次要文字，显示在 topic 下方
+  title: string;              // 步骤标题（必填）
+  comment?: string;           // 可选的次要文字，显示在 title 下方
   status: ProgressStepStatus; // 当前状态
 }
 ```
@@ -113,7 +115,7 @@ enum ProgressStepStatus {
         </div>
       </div>
       <div class="step-text {status}">
-        <div class="step-topic"><span>{topic}</span></div>
+        <div class="step-topic"><span>{title}</span></div>
         <!-- 仅提供 comment 时 -->
         <div class="step-comment"><span>{comment}</span></div>
       </div>
@@ -130,10 +132,10 @@ enum ProgressStepStatus {
 | `--uniface-progress-step-bar-color-surface` | 容器背景（也用作"线后面的背景"，让线看起来在圆圈处中断） |
 | `--uniface-progress-step-bar-bg` | 进行中圆圈内的前景色（默认白） |
 | `--uniface-progress-step-pending-color` | 未开始圆圈边框 + 线 + 文字（灰） |
-| `--uniface-progress-step-completed-color` | 已完成 topic / comment 文字（深灰） |
+| `--uniface-progress-step-completed-color` | 已完成 title / comment 文字（深灰） |
 | `--uniface-progress-step-completed-icon-color` | 已完成圆圈边框 + 对勾 + 线（蓝） |
 | `--uniface-progress-step-completed-icon-bg` | 已完成圆圈背景（淡蓝） |
-| `--uniface-progress-step-processing-color` | 进行中圆圈填充 + topic 文字（蓝） |
+| `--uniface-progress-step-processing-color` | 进行中圆圈填充 + title 文字（蓝） |
 
 ### 连接线怎么画的
 
@@ -149,26 +151,26 @@ enum ProgressStepStatus {
 <script lang="ts">
   import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
 
-  let steps = $state<ProgressStep[]>([
-    { topic: '初始化',   comment: '正在设置...',   status: ProgressStepStatus.Pending },
-    { topic: '数据加载', comment: '正在获取...',   status: ProgressStepStatus.Pending },
-    { topic: '处理中',   comment: '正在分析...',   status: ProgressStepStatus.Pending },
-    { topic: '完成',     comment: '正在收尾...',   status: ProgressStepStatus.Pending }
+  let items = $state<ProgressStep[]>([
+    { title: '初始化',   comment: '正在设置...',   status: ProgressStepStatus.Pending },
+    { title: '数据加载', comment: '正在获取...',   status: ProgressStepStatus.Pending },
+    { title: '处理中',   comment: '正在分析...',   status: ProgressStepStatus.Pending },
+    { title: '完成',     comment: '正在收尾...',   status: ProgressStepStatus.Pending }
   ]);
 
   let currentIdx = 0;
 
   function advance() {
-    if (currentIdx >= steps.length) return;
+    if (currentIdx >= items.length) return;
 
-    steps[currentIdx].status = ProgressStepStatus.Processing;
+    items[currentIdx].status = ProgressStepStatus.Processing;
 
     setTimeout(() => {
-      steps[currentIdx].status = ProgressStepStatus.Completed;
+      items[currentIdx].status = ProgressStepStatus.Completed;
       currentIdx++;
 
-      if (currentIdx < steps.length) {
-        steps[currentIdx].status = ProgressStepStatus.Processing;
+      if (currentIdx < items.length) {
+        items[currentIdx].status = ProgressStepStatus.Processing;
         advance();
       }
     }, 1500);
@@ -177,14 +179,14 @@ enum ProgressStepStatus {
   advance();
 </script>
 
-<ProgressStepBar {steps} />
+<ProgressStepBar {items} />
 ```
 
 ### 纵向布局
 
 ```svelte
 <div style="height: 480px;">
-  <ProgressStepBar {steps} direction="vertical" />
+  <ProgressStepBar {items} direction="vertical" />
 </div>
 ```
 
@@ -199,22 +201,22 @@ enum ProgressStepStatus {
   import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
 
   const orderSteps: ProgressStep[] = [
-    { topic: '下单',       status: ProgressStepStatus.Completed },
-    { topic: '支付成功',   status: ProgressStepStatus.Completed },
-    { topic: '已发货',     status: ProgressStepStatus.Processing },
-    { topic: '派送中',     status: ProgressStepStatus.Pending },
-    { topic: '已签收',     status: ProgressStepStatus.Pending }
+    { title: '下单',       status: ProgressStepStatus.Completed },
+    { title: '支付成功',   status: ProgressStepStatus.Completed },
+    { title: '已发货',     status: ProgressStepStatus.Processing },
+    { title: '派送中',     status: ProgressStepStatus.Pending },
+    { title: '已签收',     status: ProgressStepStatus.Pending }
   ];
 </script>
 
-<ProgressStepBar steps={orderSteps} />
+<ProgressStepBar items={orderSteps} />
 ```
 
 ## 行为说明
 
 - **纯展示。** 无点击 handler —— 用户不能在步骤间跳转。需要交互式步骤导航用 [Navigator](../navigator/README_CN.md)
-- **响应式。** 修改 `steps[i].status`（用 `$state` 数组）UI 就更新。组件通过 Svelte 5 响应式重渲染
-- **`topic` 用 `…` 截断**（`white-space: nowrap; text-overflow: ellipsis`）。保持 topic 简短
+- **响应式。** 修改 `items[i].status`（用 `$state` 数组）UI 就更新。组件通过 Svelte 5 响应式重渲染
+- **`title` 用 `…` 截断**（`white-space: nowrap; text-overflow: ellipsis`）。保持 topic 简短
 - **`comment` 可多行**，但本身不截断 —— 长注释可能破坏布局
 - **首步无左 margin**；后续步骤横向 `margin-left: 8px`，纵向无 margin（因为线是竖向连接的）
 - **末步保留线**为了视觉连续 —— 有 `.progress-step-block:last-child` 规则但横向模式下为空。纵向模式下末步的线被 unset
@@ -223,7 +225,7 @@ enum ProgressStepStatus {
 
 - **纯视觉。** 没有 ARIA role、processing 步骤没有 `aria-current`、指示器没有 `aria-label`
 - 对勾 `✔` 是字面 Unicode 文字 —— 屏幕阅读器会读成"对勾"。觉得吵的话在 fork 里换成图标字体 + `aria-hidden="true"`
-- 步骤状态（Pending / Processing / Completed）只靠颜色 + 圆圈填充传达 —— 没有文字替代。fork 时在每个块上加 `aria-label="第 N 步：{topic}，{status}"` 支持屏幕阅读器
+- 步骤状态（Pending / Processing / Completed）只靠颜色 + 圆圈填充传达 —— 没有文字替代。fork 时在每个块上加 `aria-label="第 N 步：{title}，{status}"` 支持屏幕阅读器
 - 无键盘交互（纯展示，所以没问题）
 
 ## 已知怪异
@@ -232,8 +234,8 @@ enum ProgressStepStatus {
 
 ## 最佳实践
 
-1. **`steps` 数组用 `$state`**，需要实时进度更新时。修改 `steps[i].status` 触发重渲染
-2. **`topic` 保持简短** —— 会用 `…` 截断。详情移到 `comment`
+1. **`items` 数组用 `$state`**，需要实时进度更新时。修改 `items[i].status` 触发重渲染
+2. **`title` 保持简短** —— 会用 `…` 截断。详情移到 `comment`
 3. **`direction="vertical"` 只在高度受限的父容器里用**（侧边栏、抽屉）。否则会塌
 4. **同时只一个 `Processing` 步骤** —— 多了视觉混乱。把之前的标 `Completed`
 5. **颜色通过 CSS 变量覆盖**，不要改内部类样式 —— 结构脆弱（见连接线说明）

package/dist/navigation/tabs/Tabs.svelte

@@ -4,7 +4,7 @@
     import {Tween} from 'svelte/motion';
     import {cubicOut} from 'svelte/easing';
     import type {Snippet} from "svelte";
-    import type {TabActionHandler, TabCloseHandler, TabRender} from "../../types";
+    import type {OnTabAction, BeforeTabClose, IsTabClosable, TabRender} from "../../types";
 
     interface Props {
         class?: string;
@@ -14,12 +14,19 @@
         style?: string;
         tabs: Array<any>;
         scrollStep?: number;
-        closable?: boolean | TabActionHandler;
+        closable?: boolean | IsTabClosable;
         activeTab?: any;
         maxTabWidth?: number;
         tabRender?: TabRender;
-        onrefresh?: TabActionHandler;
-        onremove?: TabCloseHandler;
+        onrefresh?: OnTabAction;
+        /**
+         * 关闭标签前的否决钩子：返回 false 阻止关闭。
+         */
+        beforeRemove?: BeforeTabClose;
+        /**
+         * 标签被移除后的通知。
+         */
+        onremove?: OnTabAction;
         children?: Snippet;
     }
 
@@ -36,6 +43,7 @@
         maxTabWidth,
         tabRender,
         onrefresh,
+        beforeRemove,
         onremove,
         children
     }: Props = $props();
@@ -128,7 +136,7 @@
     const closeTab = (tab: any) => async (e: MouseEvent) => {
         let pos = tabs.indexOf(tab);
         if (pos > -1) {
-            let canClose = onremove == null ? true : await onremove(tab);
+            const canClose = beforeRemove == null || (await beforeRemove(tab)) !== false;
             if (canClose) {
                 tabs.splice(pos, 1);
                 tabs = [...tabs];
@@ -140,6 +148,7 @@
                 }
                 await tick();
                 checkOverflow();
+                onremove?.(tab);
             }
         }
         e.stopPropagation();

package/dist/navigation/tabs/Tabs.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { Snippet } from "svelte";
-import type { TabActionHandler, TabCloseHandler, TabRender } from "../../types";
+import type { OnTabAction, BeforeTabClose, IsTabClosable, TabRender } from "../../types";
 interface Props {
     class?: string;
     simple?: boolean;
@@ -8,12 +8,19 @@ interface Props {
     style?: string;
     tabs: Array<any>;
     scrollStep?: number;
-    closable?: boolean | TabActionHandler;
+    closable?: boolean | IsTabClosable;
     activeTab?: any;
     maxTabWidth?: number;
     tabRender?: TabRender;
-    onrefresh?: TabActionHandler;
-    onremove?: TabCloseHandler;
+    onrefresh?: OnTabAction;
+    /**
+     * 关闭标签前的否决钩子：返回 false 阻止关闭。
+     */
+    beforeRemove?: BeforeTabClose;
+    /**
+     * 标签被移除后的通知。
+     */
+    onremove?: OnTabAction;
     children?: Snippet;
 }
 declare const Tabs: import("svelte").Component<Props, {}, "tabs" | "activeTab">;

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

@@ -1,4 +1,4 @@
 import Tabs from "./Tabs.svelte";
-import type { TabActionHandler, TabCloseHandler, TabRender } from "../../types";
+import type { OnTabAction, BeforeTabClose, IsTabClosable, TabRender } from "../../types";
 export default Tabs;
-export type { TabActionHandler, TabCloseHandler, TabRender };
+export type { OnTabAction, BeforeTabClose, IsTabClosable, TabRender };