@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/navigation/pagination/README.md

@@ -0,0 +1,248 @@
+# Pagination Component
+
+A page-number pagination bar with smart ellipsis layout. Renders numbered buttons (1 … N-2 N-1 N, etc.) based on the current page, with three visual variants and a `big` size option. **No prev/next/first/last buttons** — just numbered pages.
+
+## Features
+
+- **Smart page range**: always shows first page, last page, and a window around the current page; uses `...` gaps to keep the bar compact for large page counts
+- **Three visual variants**: `plain` (text only), `round` (default, 4px-radius bordered squares), `circle` (perfectly round)
+- **`big` size mode**: 3em buttons instead of 2em
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+- **Skips redundant clicks**: clicking the already-selected page does nothing
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Pagination from '@ticatec/uniface-element/Pagination';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/uniface-element/Pagination';
+
+  let currentPage = $state(1);
+  const totalPages = 10;
+
+  function onPageChange(page: number) {
+    currentPage = page;
+    console.log('Page changed to:', page);
+  }
+</script>
+
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+/>
+```
+
+> **`pageNo` is NOT two-way bindable.** You must update your own state in the `onchange` handler — `bind:pageNo` is not supported. If you forget, the UI will never move off page 1.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `pageCount` | `number` | `0` | Total number of pages. With 0, nothing renders. |
+| `pageNo` | `number` | `1` | Current page. **Clamped internally** to `[1, pageCount]` for rendering — but the clamp does not propagate back to the parent. Keep your state in range yourself. |
+| `type` | `'plain' \| 'round' \| 'circle'` | `'round'` | Visual variant. `plain` = text-only no border, `round` = bordered with 4px radius, `circle` = bordered with 50% radius. |
+| `big` | `boolean` | `false` | 3em buttons (default 2em) |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
+| `onchange` | `((page: number) => void) \| undefined` | `undefined` | Fires when a page number is clicked. **Not fired when the clicked page equals the current `pageNo`.** |
+
+## Page Display Logic
+
+The bar always centers around the current page; gaps (`...`) replace runs of hidden middle pages. Branches by `pageCount` and `pageNo`:
+
+| `pageCount` | `pageNo` location | Rendered sequence |
+|-------------|-------------------|-------------------|
+| `< 6` | anywhere | `1 2 3 ... N` (all pages, no gaps) |
+| `≥ 6` | first or second | `1 2 3 … N` |
+| `≥ 6` | last or second-to-last | `1 … N-2 N-1 N` |
+| `≥ 6` | third | `1 2 3 4 … N` |
+| `≥ 6` | third-to-last | `1 … N-3 N-2 N-1 N` |
+| `≥ 6` | anywhere else | `1 … P-1 P P+1 … N` |
+
+So with `pageCount=20` and `pageNo=10`, the bar shows: `1 … 9 10 11 … 20`.
+
+## Examples
+
+### Data Table with Pagination
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/uniface-element/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;
+    // Replace with your real fetch
+    data = Array.from({ length: itemsPerPage }, (_, i) => ({
+      id: startIndex + i + 1,
+      name: `Item ${startIndex + i + 1}`
+    }));
+  }
+
+  async function onPageChange(page: number) {
+    currentPage = page;
+    await loadData(page);
+  }
+
+  loadData(currentPage);
+</script>
+
+<table>
+  <thead><tr><th>ID</th><th>Name</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;"
+/>
+```
+
+### Plain Variant (Text-Only)
+
+```svelte
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  type="plain"
+/>
+```
+
+Plain mode is good for compact UIs (e.g. inside a card header) — no borders, only the active page is bolded.
+
+### Circle Variant + Big Size
+
+```svelte
+<Pagination
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onchange={onPageChange}
+  type="circle"
+  big
+/>
+```
+
+### With Custom Prev/Next Buttons
+
+The component renders only page numbers — wrap it to add prev/next:
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  import Button from '@ticatec/uniface-element/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="‹ Prev" disabled={page === 1}        onclick={() => go(-1)} />
+  <Pagination pageNo={page} pageCount={total} onchange={(p) => page = p} />
+  <Button label="Next ›" disabled={page === total}    onclick={() => go(1)} />
+</div>
+```
+
+## DOM Structure & CSS
+
+```html
+<div class="uniface-pagination-panel {type}" class:big data-theme="..." style="...">
+  <!-- page number -->
+  <div class="uniface-page-no" onclick={...} aria-hidden="true" class:selected>
+    <span tabindex="-1">{page}</span>
+  </div>
+
+  <!-- gap -->
+  <div class="uniface-page-gap"><span>...</span></div>
+  ...
+</div>
+```
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--uniface-default-text-color` | Default page number text color |
+| `--uniface-default-text-hover-color` | Hover border color |
+| `--uniface-default-active-text-color` | Active page text color (active = pressed) |
+| `--uniface-default-active-border-color` | Selected page border color |
+| `--uniface-pagination-selected-color` | Selected page text color (when pressed — rare) |
+| `--uniface-pagination-selected-background-color` | Plain variant selected text color |
+| `--uniface-primary-border-color` | Default page border color |
+| `--uniface-button-primary-border-color` | Plain hover/active text color + selected background |
+
+> The variable naming is inconsistent (`default-text-hover-color` is used for hover *border*, `pagination-selected-color` is used for `:active` of selected). Pin to the table above when overriding.
+
+### Variant-specific styles
+
+- **`plain`**: no border, transparent background. Selected page is bolded; hover/active change text color.
+- **`round`** (default): 1px border, `border-radius: 4px`. Hover changes border color; active gets blue text + 1px downward press.
+- **`circle`**: same as `round` but `border-radius: 50%`.
+- **`big`**: buttons become 3em × 3em (default 2em × 2em).
+
+### Alignment
+
+The wrapper has `text-align: center` by default. CSS classes `.align-left` and `.align-right` exist but **no prop exposes them** — set `style="text-align: left;"` on the wrapper directly if you need it.
+
+## Behavior Notes
+
+- **`pageNo` is clamped internally** for rendering (`[1, pageCount]`), but the clamp is local — your parent state isn't updated. If you pass `pageNo=50` with `pageCount=10`, the bar renders page 10 as selected, but your state still says 50. Keep your state in range.
+- **`onchange` is not fired for the current page.** Clicking the selected page is a no-op.
+- **No prev/next/first/last buttons.** Render your own around the component if you need them.
+- **`pageCount < 6` shows all pages** (no gaps). With `pageCount=5` you get `1 2 3 4 5`.
+- **Re-render on every prop change.** `buildPagination` runs in a `$effect`, so changing `pageNo`, `pageCount` rebuilds the array. Cheap; don't worry about it.
+- **The bar is `overflow: hidden`** — if the parent is narrow, buttons may clip. There's no scroll/wrap fallback.
+- **Every page button is `aria-hidden="true"`** with `tabindex="-1"` inside. See a11y below.
+
+## Accessibility (Significant Limitations)
+
+Same pattern as Navigator — this component is **not keyboard or screen-reader accessible**:
+
+1. **Every page button has `aria-hidden="true"`** — invisible to screen readers.
+2. **Inner `<span tabindex="-1">`** — explicitly removed from tab order.
+3. **`<div onclick>`** — not a real button. No Enter/Space, no `role="button"`.
+4. **Selected state conveyed by color alone** — no `aria-current="page"` or text alternative.
+5. **No focus styles.**
+
+For accessible pagination, fork the component or wrap each page number in a real `<button>` with `aria-label="Page N"` and `aria-current="page"` on the active one.
+
+## Best Practices
+
+1. **Update `pageNo` in your `onchange` handler** — there's no `bind:`.
+2. **Clamp your state to `[1, pageCount]`** — don't rely on the component's internal clamp leaking back.
+3. **Pair with prev/next buttons** if your users need them — the component is page-numbers-only.
+4. **Use `type="plain"` for compact UIs** (card headers, sidebars). `round` and `circle` work better in spacious footer bars.
+5. **Use `big` for touch UIs** — the default 2em buttons are small for fingers.
+6. **Don't rely on keyboard navigation** — see a11y note above.
+
+## Related Components
+
+- [PaginationPanel](../pagination_panel/README.md) — fuller-featured pagination (if it exists in your version)

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/uniface-element
+```
+
+## 导入
+
+```typescript
+import Pagination from '@ticatec/uniface-element/Pagination';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import Pagination from '@ticatec/uniface-element/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/uniface-element/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/uniface-element/Pagination';
+  import Button from '@ticatec/uniface-element/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="uniface-pagination-panel {type}" class:big data-theme="..." style="...">
+  <!-- 页码 -->
+  <div class="uniface-page-no" onclick={...} aria-hidden="true" class:selected>
+    <span tabindex="-1">{page}</span>
+  </div>
+
+  <!-- 间隔 -->
+  <div class="uniface-page-gap"><span>...</span></div>
+  ...
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--uniface-default-text-color` | 默认页码文字色 |
+| `--uniface-default-text-hover-color` | hover 边框色 |
+| `--uniface-default-active-text-color` | active 页文字色（active = 按下） |
+| `--uniface-default-active-border-color` | 选中页边框色 |
+| `--uniface-pagination-selected-color` | 选中页文字色（按下时 —— 罕见） |
+| `--uniface-pagination-selected-background-color` | 纯文本变体的选中文字色 |
+| `--uniface-primary-border-color` | 默认页边框色 |
+| `--uniface-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/progress_step_bar/ProgressStepBar.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+    import type ProgressStep from "./ProgressStep";
+    import ProgressStepBlock from "./ProgressStepBlock.svelte";
+
+    interface Props {
+        steps: Array<ProgressStep>;
+        direction?: 'vertical' | 'horizontal';
+        style?: string;
+        theme?: string;
+    }
+
+    let {
+        steps,
+        direction = 'horizontal',
+        style,
+        theme
+    }: Props = $props();
+
+</script>
+
+<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}
+    </div>
+</div>
+
+<style>
+
+    .uniface-progress-step-container {
+        position: relative;
+        width: 100%;
+        padding: 12px 8px;
+        background-color: var(--uniface-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;
+    }
+
+    .uniface-progress-step-container.vertical {
+        height: 100%;
+    }
+
+    .uniface-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,10 @@
+import type ProgressStep from "./ProgressStep";
+interface Props {
+    steps: Array<ProgressStep>;
+    direction?: 'vertical' | 'horizontal';
+    style?: string;
+    theme?: string;
+}
+declare const ProgressStepBar: import("svelte").Component<Props, {}, "">;
+type ProgressStepBar = ReturnType<typeof ProgressStepBar>;
+export default ProgressStepBar;