@ticatec/topside-elements 1.0.0

package/dist/navigation/progress_step_bar/README.md

@@ -0,0 +1,247 @@
+# 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
+
+- **Three statuses per step**: `Pending` (gray number), `Processing` (solid blue circle), `Completed` (blue tinted circle with checkmark)
+- **Connector line**: drawn via CSS `linear-gradient` between adjacent circles; the line color follows step status (blue when completed, gray when pending)
+- **Horizontal or vertical layout**: horizontal default, vertical for sidebars
+- **Optional comment per step**: smaller secondary text under the topic
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+
+  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 {items} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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 |
+
+## ProgressStep Type
+
+```typescript
+interface ProgressStep {
+  title: string;              // Step title (required)
+  comment?: string;           // Optional secondary text shown below the title
+  status: ProgressStepStatus; // Current status
+}
+```
+
+## ProgressStepStatus Enum
+
+```typescript
+enum ProgressStepStatus {
+  Pending    = 'pending',     // Gray number, gray text
+  Processing = 'processing',  // Solid blue circle with white number, blue text
+  Completed  = 'completed',   // Blue-tinted circle with checkmark (✔), dark gray text
+}
+```
+
+The enum value is also the CSS class on each step block (`Pending` → `.pending`, etc.).
+
+## Visual Design
+
+```text
+Horizontal:
+
+   ●─────●─────○─────○
+   1     2     3     4
+   Reg   Ver   Setup Done
+   Done  ...
+
+Vertical:
+
+   ●
+   │ 1
+   │ Registration
+   │
+   ●
+   │ 2
+   │ Verification
+   │
+   ○
+     3
+     Setup
+```
+
+Filled circles (●) are completed or processing; outlined circles (○) are pending. The connecting line is blue when the step is `Completed`, gray when `Pending`.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="topside-progress-step-container {direction}" data-theme="..." style="...">
+  <div class="container-panel">
+    <!-- per step -->
+    <div class="progress-step-block {status} {direction}">
+      <div class="step-indicator">
+        <div>
+          <span>✔</span>          <!-- Completed -->
+          <!-- OR -->
+          <span>{pos}</span>      <!-- Pending / Processing -->
+        </div>
+      </div>
+      <div class="step-text {status}">
+        <div class="step-topic"><span>{title}</span></div>
+        <!-- only if comment provided -->
+        <div class="step-comment"><span>{comment}</span></div>
+      </div>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--topside-progress-step-bar-color-surface` | Container background (also used as the "background behind the line" so the line appears to break around the circle) |
+| `--topside-progress-step-bar-bg` | Foreground inside processing circle (default white) |
+| `--topside-progress-step-pending-color` | Pending circle border + line + text (gray) |
+| `--topside-progress-step-completed-color` | Completed title/comment text (dark gray) |
+| `--topside-progress-step-completed-icon-color` | Completed circle border + checkmark + line (blue) |
+| `--topside-progress-step-completed-icon-bg` | Completed circle background (light blue tint) |
+| `--topside-progress-step-processing-color` | Processing circle fill + title text (blue) |
+
+### How the connector line works
+
+Each step's `background` is a `linear-gradient` that draws a 2px horizontal (or vertical) line at the indicator's center. The circle itself sits on top with a same-color background, making it look like the line breaks around the circle. Status-specific classes override the gradient color.
+
+This is fragile — if you change `--topside-progress-step-bar-color-surface` to a non-solid background (image, gradient), the line will visually leak through the circle.
+
+## Examples
+
+### Dynamic Progress (Svelte 5 runes)
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+
+  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 >= items.length) return;
+
+    items[currentIdx].status = ProgressStepStatus.Processing;
+
+    setTimeout(() => {
+      items[currentIdx].status = ProgressStepStatus.Completed;
+      currentIdx++;
+
+      if (currentIdx < items.length) {
+        items[currentIdx].status = ProgressStepStatus.Processing;
+        advance();
+      }
+    }, 1500);
+  }
+
+  advance();
+</script>
+
+<ProgressStepBar {items} />
+```
+
+### Vertical Layout
+
+```svelte
+<div style="height: 480px;">
+  <ProgressStepBar {items} direction="vertical" />
+</div>
+```
+
+Vertical mode fills the parent's height — make sure the parent has a height or the layout collapses.
+
+### Pure Display (Static Steps)
+
+For a "your order is at step N" type view:
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+
+  const orderSteps: ProgressStep[] = [
+    { 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 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 `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.
+
+## Accessibility
+
+- **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: {title}, {status}"` on each block in a fork for screen-reader support.
+- No keyboard interaction (purely display, so this is fine).
+
+## Known Quirks
+
+1. **The connector line is implemented via `background` gradient** on each step block. If you change the surface color (`--topside-progress-step-bar-color-surface`) to a non-solid background, the line will leak through the circles.
+
+## Best Practices
+
+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).
+6. **For interactive step nav, use [Navigator](../navigator/README.md)** instead — this component is display-only.
+
+## Related Components
+
+- [Navigator](../navigator/README.md) — interactive step navigation (clickable items)
+- [ProgressSteps](../progress_steps/README.md) — sibling step component (if present)

package/dist/navigation/progress_step_bar/README_CN.md

@@ -0,0 +1,247 @@
+# ProgressStepBar 步骤进度条组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `steps`, `topic` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+多步骤进度指示器，按顺序显示各步骤的完成状态。渲染带编号的圆圈，圆圈之间用线连接；每步是 `Pending`、`Processing` 或 `Completed`。支持横向（默认）和纵向布局。纯展示组件 —— 无点击 handler。
+
+## 功能特性
+
+- **三种状态**：`Pending`（灰色数字）、`Processing`（实心蓝圆）、`Completed`（蓝色淡背景圆 + 对勾）
+- **连接线**：通过 CSS `linear-gradient` 在相邻圆圈之间画线；线颜色跟随步骤状态（已完成蓝、未开始灰）
+- **横向或纵向布局**：横向默认，纵向用于侧边栏
+- **每步可选注释**：在 topic 下方显示较小的次要文字
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+
+  const items: ProgressStep[] = [
+    { title: '注册',   comment: '完善资料',     status: ProgressStepStatus.Completed },
+    { title: '验证',   comment: '验证邮箱',     status: ProgressStepStatus.Processing },
+    { title: '设置',   comment: '配置偏好',     status: ProgressStepStatus.Pending }
+  ];
+</script>
+
+<ProgressStepBar {items} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `items` | `ProgressStep[]` | _(必填)_ | 有序步骤列表。每项在数组中的位置决定其编号（显示为 `idx + 1`） |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 布局方向。横向 = 从左到右一行；纵向 = 从上到下一列 |
+| `style` | `string`\| undefined` | `undefined`  | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+
+## ProgressStep 类型
+
+```typescript
+interface ProgressStep {
+  title: string;              // 步骤标题（必填）
+  comment?: string;           // 可选的次要文字，显示在 title 下方
+  status: ProgressStepStatus; // 当前状态
+}
+```
+
+## ProgressStepStatus 枚举
+
+```typescript
+enum ProgressStepStatus {
+  Pending    = 'pending',     // 灰色数字、灰色文字
+  Processing = 'processing',  // 实心蓝圆 + 白色数字、蓝色文字
+  Completed  = 'completed',   // 蓝色淡背景圆 + 对勾（✔）、深灰文字
+}
+```
+
+枚举值也是每个步骤块上的 CSS 类（`Pending` → `.pending` 等）。
+
+## 视觉设计
+
+```text
+横向：
+
+   ●─────●─────○─────○
+   1     2     3     4
+   注册   验证   设置   完成
+   完成   ...
+
+纵向：
+
+   ●
+   │ 1
+   │ 注册
+   │
+   ●
+   │ 2
+   │ 验证
+   │
+   ○
+     3
+     设置
+```
+
+实心圆（●）是已完成或进行中；空心圆（○）是未开始。连接线在步骤 `Completed` 时为蓝色，`Pending` 时为灰色。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="topside-progress-step-container {direction}" data-theme="..." style="...">
+  <div class="container-panel">
+    <!-- 每步 -->
+    <div class="progress-step-block {status} {direction}">
+      <div class="step-indicator">
+        <div>
+          <span>✔</span>          <!-- Completed -->
+          <!-- 或 -->
+          <span>{pos}</span>      <!-- Pending / Processing -->
+        </div>
+      </div>
+      <div class="step-text {status}">
+        <div class="step-topic"><span>{title}</span></div>
+        <!-- 仅提供 comment 时 -->
+        <div class="step-comment"><span>{comment}</span></div>
+      </div>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--topside-progress-step-bar-color-surface` | 容器背景（也用作"线后面的背景"，让线看起来在圆圈处中断） |
+| `--topside-progress-step-bar-bg` | 进行中圆圈内的前景色（默认白） |
+| `--topside-progress-step-pending-color` | 未开始圆圈边框 + 线 + 文字（灰） |
+| `--topside-progress-step-completed-color` | 已完成 title / comment 文字（深灰） |
+| `--topside-progress-step-completed-icon-color` | 已完成圆圈边框 + 对勾 + 线（蓝） |
+| `--topside-progress-step-completed-icon-bg` | 已完成圆圈背景（淡蓝） |
+| `--topside-progress-step-processing-color` | 进行中圆圈填充 + title 文字（蓝） |
+
+### 连接线怎么画的
+
+每个步骤的 `background` 是个 `linear-gradient`，在指示器中心画一条 2px 横线（或竖线）。圆圈本身在上面，背景同色，让线看起来在圆圈处断开。状态相关的类覆盖 gradient 颜色。
+
+这个机制脆弱 —— 把 `--topside-progress-step-bar-color-surface` 改成非纯色背景（图片、渐变），线会从圆圈里漏出来。
+
+## 示例
+
+### 动态进度（Svelte 5 runes）
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+
+  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 >= items.length) return;
+
+    items[currentIdx].status = ProgressStepStatus.Processing;
+
+    setTimeout(() => {
+      items[currentIdx].status = ProgressStepStatus.Completed;
+      currentIdx++;
+
+      if (currentIdx < items.length) {
+        items[currentIdx].status = ProgressStepStatus.Processing;
+        advance();
+      }
+    }, 1500);
+  }
+
+  advance();
+</script>
+
+<ProgressStepBar {items} />
+```
+
+### 纵向布局
+
+```svelte
+<div style="height: 480px;">
+  <ProgressStepBar {items} direction="vertical" />
+</div>
+```
+
+纵向模式会填满父容器高度 —— 确保父容器有高度，否则布局会塌。
+
+### 纯展示（静态步骤）
+
+用于"你的订单在第 N 步"这类视图：
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/topside-elements/ProgressStepBar';
+
+  const orderSteps: ProgressStep[] = [
+    { title: '下单',       status: ProgressStepStatus.Completed },
+    { title: '支付成功',   status: ProgressStepStatus.Completed },
+    { title: '已发货',     status: ProgressStepStatus.Processing },
+    { title: '派送中',     status: ProgressStepStatus.Pending },
+    { title: '已签收',     status: ProgressStepStatus.Pending }
+  ];
+</script>
+
+<ProgressStepBar items={orderSteps} />
+```
+
+## 行为说明
+
+- **纯展示。** 无点击 handler —— 用户不能在步骤间跳转。需要交互式步骤导航用 [Navigator](../navigator/README_CN.md)
+- **响应式。** 修改 `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
+
+## 无障碍访问
+
+- **纯视觉。** 没有 ARIA role、processing 步骤没有 `aria-current`、指示器没有 `aria-label`
+- 对勾 `✔` 是字面 Unicode 文字 —— 屏幕阅读器会读成"对勾"。觉得吵的话在 fork 里换成图标字体 + `aria-hidden="true"`
+- 步骤状态（Pending / Processing / Completed）只靠颜色 + 圆圈填充传达 —— 没有文字替代。fork 时在每个块上加 `aria-label="第 N 步：{title}，{status}"` 支持屏幕阅读器
+- 无键盘交互（纯展示，所以没问题）
+
+## 已知怪异
+
+1. **连接线通过每个步骤块的 `background` gradient 实现。** 把 surface 色（`--topside-progress-step-bar-color-surface`）改成非纯色背景（图片、渐变），线会从圆圈里漏出来
+
+## 最佳实践
+
+1. **`items` 数组用 `$state`**，需要实时进度更新时。修改 `items[i].status` 触发重渲染
+2. **`title` 保持简短** —— 会用 `…` 截断。详情移到 `comment`
+3. **`direction="vertical"` 只在高度受限的父容器里用**（侧边栏、抽屉）。否则会塌
+4. **同时只一个 `Processing` 步骤** —— 多了视觉混乱。把之前的标 `Completed`
+5. **颜色通过 CSS 变量覆盖**，不要改内部类样式 —— 结构脆弱（见连接线说明）
+6. **需要交互式步骤导航用 [Navigator](../navigator/README_CN.md)** —— 这个组件是纯展示
+
+## 相关组件
+
+- [Navigator](../navigator/README_CN.md) —— 交互式步骤导航（可点击项）
+- [ProgressSteps](../progress_steps/README_CN.md) —— 同类步骤组件（如果存在）

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

@@ -0,0 +1,6 @@
+import ProgressStepBar from "./ProgressStepBar.svelte";
+import { ProgressStepStatus } from "./ProgressStep";
+import type ProgressStep from "./ProgressStep";
+export default ProgressStepBar;
+export { ProgressStepStatus };
+export { type ProgressStep };

package/dist/navigation/progress_step_bar/index.js

@@ -0,0 +1,5 @@
+import ProgressStepBar from "./ProgressStepBar.svelte";
+import { ProgressStepStatus } from "./ProgressStep";
+export default ProgressStepBar;
+export { ProgressStepStatus };
+export {};