@ticatec/topside-elements 1.0.0

package/dist/navigation/pagination/README_CN.md

@@ -0,0 +1,248 @@
+# Pagination 分页组件
+
+带智能省略号布局的页码分页条。根据当前页渲染数字按钮（1 … N-2 N-1 N 等），三种视觉变体 + `big` 大尺寸选项。**没有上一页/下一页/首页/末页按钮** —— 只有数字页码。
+
+## 功能特性
+
+- **智能页码范围**：始终显示首页、末页以及当前页附近的窗口；用 `...` 间隔压缩大页数下的宽度
+- **三种视觉变体**：`plain`（纯文本）、`round`（默认，4px 圆角边框）、`circle`（正圆）
+- **`big` 大尺寸**：3em 按钮（默认 2em）
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+- **重复点击忽略**：点击已选中的页码不做任何事
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Pagination from '@ticatec/topside-elements/Pagination';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/topside-elements/Pagination';
+
+  let currentPage = $state(1);
+  const totalPages = 10;
+
+  function onPageChange(page: number) {
+    currentPage = page;
+    console.log('页面切换到:', page);
+  }
+</script>
+
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+/>
+```
+
+> **`pageNo` 不可双向绑定。** 必须在 `onchange` handler 里更新自己的状态 —— 不支持 `bind:pageNo`。忘了的话 UI 永远停在第 1 页。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `pageCount` | `number` | `0` | 总页数。为 0 时不渲染任何东西 |
+| `pageNo` | `number` | `1` | 当前页。**内部会夹到** `[1, pageCount]` 用于渲染 —— 但夹取不回传给父组件。自己保持状态在范围内 |
+| `type` | `'plain' \| 'round' \| 'circle'` | `'round'` | 视觉变体。`plain` = 纯文本无边框、`round` = 1px 边框 4px 圆角、`circle` = 1px 边框 50% 圆角 |
+| `big` | `boolean` | `false` | 3em 按钮（默认 2em） |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+| `onchange` | `((page: number) => void) \| undefined` | `undefined` | 点击页码时触发。**点击当前 `pageNo` 不触发** |
+
+## 页码显示逻辑
+
+页码条始终围绕当前页中心展开；用 `...` 间隔代替连续的隐藏中间页。按 `pageCount` 和 `pageNo` 分支：
+
+| `pageCount` | `pageNo` 位置 | 渲染序列 |
+|-------------|---------------|---------|
+| `< 6` | 任意 | `1 2 3 ... N`（所有页，无间隔） |
+| `≥ 6` | 第一或第二 | `1 2 3 … N` |
+| `≥ 6` | 末尾或倒数第二 | `1 … N-2 N-1 N` |
+| `≥ 6` | 第三 | `1 2 3 4 … N` |
+| `≥ 6` | 倒数第三 | `1 … N-3 N-2 N-1 N` |
+| `≥ 6` | 其他位置 | `1 … P-1 P P+1 … N` |
+
+所以 `pageCount=20`、`pageNo=10` 时，条带显示：`1 … 9 10 11 … 20`。
+
+## 示例
+
+### 带分页的数据表
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/topside-elements/Pagination';
+
+  let currentPage = $state(1);
+  const totalPages = 20;
+  const itemsPerPage = 10;
+
+  let data = $state<any[]>([]);
+
+  async function loadData(page: number) {
+    const startIndex = (page - 1) * itemsPerPage;
+    // 换成你自己的 fetch
+    data = Array.from({ length: itemsPerPage }, (_, i) => ({
+      id: startIndex + i + 1,
+      name: `项目 ${startIndex + i + 1}`
+    }));
+  }
+
+  async function onPageChange(page: number) {
+    currentPage = page;
+    await loadData(page);
+  }
+
+  loadData(currentPage);
+</script>
+
+<table>
+  <thead><tr><th>ID</th><th>名称</th></tr></thead>
+  <tbody>
+    {#each data as item (item.id)}
+      <tr><td>{item.id}</td><td>{item.name}</td></tr>
+    {/each}
+  </tbody>
+</table>
+
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  style="margin-top: 20px;"
+/>
+```
+
+### 纯文本变体
+
+```svelte
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  type="plain"
+/>
+```
+
+纯文本模式适合紧凑 UI（如卡片 header 内）—— 无边框，只有 active 页加粗。
+
+### 圆形变体 + 大尺寸
+
+```svelte
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  type="circle"
+  big
+/>
+```
+
+### 配自定义上一页 / 下一页按钮
+
+组件只渲染页码 —— 自己包一层加上下页按钮：
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/topside-elements/Pagination';
+  import Button from '@ticatec/topside-elements/Button';
+
+  let page = $state(1);
+  const total = 20;
+
+  function go(delta: number) {
+    const next = Math.min(Math.max(1, page + delta), total);
+    if (next !== page) page = next;
+  }
+</script>
+
+<div style="display: flex; align-items: center; gap: 8px; justify-content: center;">
+  <Button label="‹ 上一页" disabled={page === 1}     onclick={() => go(-1)} />
+  <Pagination pageNo={page} pageCount={total} onchange={(p) => page = p} />
+  <Button label="下一页 ›" disabled={page === total} onclick={() => go(1)} />
+</div>
+```
+
+## DOM 结构与 CSS
+
+```html
+<div class="topside-pagination-panel {type}" class:big data-theme="..." style="...">
+  <!-- 页码 -->
+  <div class="topside-page-no" onclick={...} aria-hidden="true" class:selected>
+    <span tabindex="-1">{page}</span>
+  </div>
+
+  <!-- 间隔 -->
+  <div class="topside-page-gap"><span>...</span></div>
+  ...
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--topside-default-text-color` | 默认页码文字色 |
+| `--topside-default-text-hover-color` | hover 边框色 |
+| `--topside-default-active-text-color` | active 页文字色（active = 按下） |
+| `--topside-default-active-border-color` | 选中页边框色 |
+| `--topside-pagination-selected-color` | 选中页文字色（按下时 —— 罕见） |
+| `--topside-pagination-selected-background-color` | 纯文本变体的选中文字色 |
+| `--topside-primary-border-color` | 默认页边框色 |
+| `--topside-button-primary-border-color` | 纯文本 hover/active 文字色 + 选中背景 |
+
+> 变量命名不一致（`default-text-hover-color` 用于 hover *边框*、`pagination-selected-color` 用于选中的 `:active`）。覆盖时按上表为准。
+
+### 各变体样式
+
+- **`plain`**：无边框，背景透明。选中页加粗；hover/active 改文字色
+- **`round`**（默认）：1px 边框，`border-radius: 4px`。hover 改边框色；active 蓝字 + 1px 下沉
+- **`circle`**：同 round，但 `border-radius: 50%`
+- **`big`**：按钮变 3em × 3em（默认 2em × 2em）
+
+### 对齐
+
+wrapper 默认 `text-align: center`。CSS 类 `.align-left` 和 `.align-right` 存在但**没有 prop 暴露** —— 需要时直接在 wrapper 上写 `style="text-align: left;"`。
+
+## 行为说明
+
+- **`pageNo` 内部夹取**用于渲染（`[1, pageCount]`），但夹取是局部的 —— 不会回传给父组件。传 `pageNo=50` 配 `pageCount=10`，条带渲染第 10 页为选中，但你的状态还是 50。自己保持状态在范围内
+- **`onchange` 对当前页不触发。** 点选中页是空操作
+- **没有上一页/下一页/首页/末页按钮。** 需要就自己渲染
+- **`pageCount < 6` 显示所有页码**（无间隔）。`pageCount=5` → `1 2 3 4 5`
+- **每次 prop 变化都重建。** `buildPagination` 在 `$effect` 里跑，`pageNo`、`pageCount` 变都会重建数组。开销小，不用担心
+- **条带是 `overflow: hidden`** —— 父容器窄时按钮可能被裁。没有滚动/换行兜底
+- **每个页码按钮是 `aria-hidden="true"`** + 内部 `tabindex="-1"`。见下面 a11y
+
+## 无障碍访问（重大限制）
+
+跟 Navigator 同样的模式 —— 这个组件**键盘和屏幕阅读器都不可访问**：
+
+1. **每个页码按钮 `aria-hidden="true"`** —— 屏幕阅读器看不到
+2. **内部 `<span tabindex="-1">`** —— 显式从 Tab 序列移除
+3. **`<div onclick>`** —— 不是真正的 button。没有 Enter/Space、没有 `role="button"`
+4. **选中状态只靠颜色传达** —— 没有 `aria-current="page"` 或文字替代
+5. **没有焦点样式**
+
+要做可访问的分页，fork 组件或把每个页码包成真正的 `<button>`，加 `aria-label="第 N 页"` 和 active 页的 `aria-current="page"`。
+
+## 最佳实践
+
+1. **`onchange` handler 里更新 `pageNo`** —— 没有 `bind:`
+2. **状态夹到 `[1, pageCount]`** —— 别指望组件的内部夹取能漏回来
+3. **配上 / 下页按钮**，如果用户需要 —— 组件只渲染页码
+4. **紧凑 UI 用 `type="plain"`**（卡片 header、侧边栏）。`round` 和 `circle` 适合宽底部条带
+5. **触屏 UI 用 `big`** —— 默认 2em 按钮对手指偏小
+6. **不要依赖键盘导航** —— 见上面 a11y 说明
+
+## 相关组件
+
+- [PaginationPanel](../pagination_panel/README_CN.md) —— 功能更全的分页（如果你的版本里有）

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

@@ -0,0 +1,2 @@
+import Pagination from "./Pagination.svelte";
+export default Pagination;

package/dist/navigation/pagination/index.js

@@ -0,0 +1,2 @@
+import Pagination from "./Pagination.svelte";
+export default Pagination;

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

@@ -0,0 +1,20 @@
+export declare enum ProgressStepStatus {
+    Pending = "pending",
+    Processing = "processing",
+    Completed = "completed"
+}
+export default interface ProgressStep {
+    /**
+     *
+     */
+    /** 步骤标题 */
+    title: string;
+    /**
+     *
+     */
+    comment?: string;
+    /**
+     *
+     */
+    status: ProgressStepStatus;
+}

package/dist/navigation/progress_step_bar/ProgressStep.js

@@ -0,0 +1,6 @@
+export var ProgressStepStatus;
+(function (ProgressStepStatus) {
+    ProgressStepStatus["Pending"] = "pending";
+    ProgressStepStatus["Processing"] = "processing";
+    ProgressStepStatus["Completed"] = "completed";
+})(ProgressStepStatus || (ProgressStepStatus = {}));

package/dist/navigation/progress_step_bar/ProgressStepBar.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+    import type ProgressStep from "./ProgressStep";
+    import ProgressStepBlock from "./ProgressStepBlock.svelte";
+
+    interface Props {
+        /** 步骤列表 */
+        items?: Array<ProgressStep>;
+        direction?: 'vertical' | 'horizontal';
+        style?: string;
+        theme?: string;
+    }
+
+    let {
+        items = [],
+        direction = 'horizontal',
+        style,
+        theme
+    }: Props = $props();
+
+</script>
+
+<div class="topside-progress-step-container {direction}" data-theme={theme} {style}>
+    <div class="container-panel">
+        {#each items as step, idx}
+            <ProgressStepBlock pos={idx+1} status={step.status} comment={step.comment} title={step.title} {direction}/>
+        {/each}
+    </div>
+</div>
+
+<style>
+
+    .topside-progress-step-container {
+        position: relative;
+        width: 100%;
+        padding: 12px 8px;
+        background-color: var(--topside-progress-step-bar-color-surface, #ffffff);
+    }
+
+    .container-panel {
+        width: 100%;
+        display: flex;
+        flex-direction: row;
+        justify-items: flex-start;
+        background-color: inherit;
+        z-index: 2;
+    }
+
+    .topside-progress-step-container.vertical {
+        height: 100%;
+    }
+
+    .topside-progress-step-container.vertical .container-panel {
+        flex-direction: column;
+        height: 100%;
+    }
+</style>

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

@@ -0,0 +1,11 @@
+import type ProgressStep from "./ProgressStep";
+interface Props {
+    /** 步骤列表 */
+    items?: Array<ProgressStep>;
+    direction?: 'vertical' | 'horizontal';
+    style?: string;
+    theme?: string;
+}
+declare const ProgressStepBar: import("svelte").Component<Props, {}, "">;
+type ProgressStepBar = ReturnType<typeof ProgressStepBar>;
+export default ProgressStepBar;

package/dist/navigation/progress_step_bar/ProgressStepBlock.svelte

@@ -0,0 +1,197 @@
+<script lang="ts">
+    import {ProgressStepStatus} from "./ProgressStep";
+
+    interface Props {
+        status: ProgressStepStatus;
+        pos?: number;
+        title: string;
+        comment?: string;
+        style?: string;
+        direction: 'vertical' | 'horizontal';
+    }
+
+    let {
+        status,
+        pos = 1,
+        title,
+        comment = '',
+        style = '',
+        direction
+    }: Props = $props();
+
+
+</script>
+
+<div class="progress-step-block {status} {direction}" {style}>
+    <div class="step-indicator">
+        <div>
+            {#if status === ProgressStepStatus.Completed}
+                <span>✔</span>
+            {:else}
+                <span>{pos}</span>
+            {/if}
+        </div>
+    </div>
+    <div class="step-text {status}">
+        <div class="step-topic" >
+            <span>{title}</span>
+        </div>
+        {#if comment}
+            <div class="step-comment">
+                <span>{comment}</span>
+            </div>
+        {/if}
+    </div>
+</div>
+
+<style>
+
+    .progress-step-block {
+        flex: 1 1;
+        min-width: 100px;
+        display: flex;
+        flex-direction: row;
+        justify-items: flex-start;
+        color: var(--topside-progress-step-pending-color, #B3BCCA);
+        margin-left: 8px;
+        background-color: inherit;
+        background: linear-gradient(to bottom, transparent 12px,
+                var(--topside-progress-step-pending-color, #B3BCCA) 12px,
+                var(--topside-progress-step-pending-color, #B3BCCA) 14px,
+                transparent 14px);
+    }
+
+    .progress-step-block:first-child {
+        margin-left: 0;
+    }
+
+    .progress-step-block:first-child .step-indicator {
+        margin-left: 0;
+    }
+
+    .step-indicator {
+        flex: 0 0 auto;
+        padding-right: 12px;
+        margin-left: 12px;
+    }
+
+    .step-indicator > div {
+        background-color: var(--topside-progress-step-bar-color-surface);
+        display: inline-block;
+    }
+
+    .step-indicator span {
+        display: inline-block;
+        text-align: center;
+        width: 24px;
+        height: 24px;
+        line-height: 24px;
+        border-radius: 50%;
+        border: 1px solid var(--topside-progress-step-pending-color, #B3BCCA);
+        font-size: 1.1em;
+    }
+
+    .progress-step-block.completed {
+        background: linear-gradient(to bottom, transparent 12px,
+                var(--topside-progress-step-completed-icon-color, #0061FF) 12px,
+                var(--topside-progress-step-completed-icon-color, #0061FF) 14px,
+                transparent 14px);
+    }
+
+    .progress-step-block.completed .step-indicator span {
+        border: 1px solid var(--topside-progress-step-completed-icon-color, #0061FF);
+    }
+
+    .step-text {
+        width: 100%;
+        overflow: hidden;
+    }
+
+    .step-topic {
+        width: 100%;
+        background-color: transparent;
+        line-height: 24px;
+        overflow: hidden;
+    }
+
+    .step-topic span {
+        display: inline-block;
+        background-color: var(--topside-progress-step-bar-color-surface);
+        padding-right: 6px;
+        padding-left: 6px;
+        max-width: 100%;
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
+        vertical-align: top;
+    }
+
+    .progress-step-block:last-child .step-topic {
+        background-color: var(--topside-progress-step-bar-color-surface);
+    }
+
+    .progress-step-block.processing .step-topic {
+        color: var(--topside-progress-step-processing-color, #0061FF);
+    }
+
+    .progress-step-block.processing .step-indicator span {
+        background-color: var(--topside-progress-step-processing-color, #0061FF);
+        color: var(--topside-progress-step-bar-bg, #ffffff);
+    }
+
+    .progress-step-block.completed .step-topic {
+        color: var(--topside-progress-step-completed-color, #374151);
+    }
+
+    .progress-step-block.completed .step-indicator span {
+        background-color: var(--topside-progress-step-completed-icon-bg, #0061FF1A);
+        color: var(--topside-progress-step-completed-icon-color, #0061FF);
+    }
+
+    .step-comment {
+        line-height: 1.4;
+        font-size: 0.9em;
+    }
+
+    .progress-step-block.completed .step-comment {
+        color: var(--topside-progress-step-completed-color, #374151);
+    }
+
+    /* Vertical styles */
+    .progress-step-block.vertical {
+        margin-left: 0;
+        background: linear-gradient(to right, transparent 12px, var(--topside-progress-step-pending-color, #B3BCCA) 14px,
+                var(--topside-progress-step-pending-color, #B3BCCA) 14px, transparent 13px);
+    }
+
+    .progress-step-block.vertical.completed {
+        background: linear-gradient(to right, transparent 12px, var(--topside-progress-step-completed-icon-color, #0061FF) 14px,
+                var(--topside-progress-step-completed-icon-color, #0061FF) 14px, transparent 13px);
+    }
+
+    .progress-step-block.vertical .step-indicator {
+        margin-left: 0;
+    }
+
+    .progress-step-block.vertical .step-indicator > div {
+        background: var(--topside-progress-step-bar-color-surface);
+        padding: 4px 0;
+    }
+
+    .progress-step-block.vertical:last-child {
+        background: unset;
+    }
+
+    .progress-step-block.vertical .step-topic span {
+        padding-left: 0;
+        display: block;
+    }
+
+    .progress-step-block.vertical:last-child {
+        background: unset;
+    }
+
+    .progress-step-block.vertical:last-child .step-indicator > div {
+        background: transparent;
+    }
+</style>

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

@@ -0,0 +1,12 @@
+import { ProgressStepStatus } from "./ProgressStep";
+interface Props {
+    status: ProgressStepStatus;
+    pos?: number;
+    title: string;
+    comment?: string;
+    style?: string;
+    direction: 'vertical' | 'horizontal';
+}
+declare const ProgressStepBlock: import("svelte").Component<Props, {}, "">;
+type ProgressStepBlock = ReturnType<typeof ProgressStepBlock>;
+export default ProgressStepBlock;