@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/navigation/navigator/README_CN.md

@@ -0,0 +1,302 @@
+# Navigator 步骤导航组件
+
+垂直的步骤 / 向导导航器。把项目渲染为可点击列表，左侧有连接的竖线，当前项有圆形标记，每项有状态颜色（完成 / 警告 / 未开始），还可以选择性高亮。专为多步表单和引导式流程设计。
+
+## 功能特性
+
+- **垂直向导路径**：每项通过 CSS gradient 渲染一段左侧竖线；首项 / 末项渲染半段，让线从首项顶部开始、末项底部结束
+- **三种状态**：`Completed`、`Warning`（红点）、`NotStart`（斜体、变淡） —— 通过 `retrieveStatus` 回调驱动
+- **当前项标记**：active 项左侧显示 15px 圆形边框
+- **高亮数组**：给任意项加"看我"颜色（比如有错误的项）
+- **`activeItem` 双向绑定**：`bind:activeItem` 在点击时自动更新，不需要 `itemClickHandler`
+- **纵向滚动**，内容溢出时
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: '第一步' },
+    { text: '第二步' },
+    { text: '第三步' },
+    { text: '第四步' }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // activeItem 之前的标 Completed，之后的标 NotStart
+  function getStepStatus(item: any): NavItemStatus {
+    return steps.indexOf(item) <= steps.indexOf(activeItem)
+      ? NavItemStatus.Completed
+      : NavItemStatus.NotStart;
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  retrieveStatus={getStepStatus}
+/>
+```
+
+用 `bind:activeItem` 后，点击项直接更新 `activeItem`。不需要 `itemClickHandler` —— 除非要跑副作用（埋点、校验、路由切换）。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `items` | `Array<any>` | _(必填)_ | 导航项。每项**必须有 `text` 属性**作为标签。其他字段随你 |
+| `activeItem` | `any` | `$bindable(undefined)` | 当前 active 项。**`bind:activeItem`** 双向绑定；点击时组件先把点击项赋给它，再调 `itemClickHandler` |
+| `highlights` | `Array<any>` | `[]` | 要高亮的项（如出错的项）。按引用相等匹配 |
+| `itemClickHandler` | `((item: any) => void) \| undefined` | `undefined` | 每次点击调用，**在 `activeItem` 更新之后**。用于副作用；如果用了 `bind:activeItem` 就不需要它做状态更新 |
+| `retrieveStatus` | `((item: any) => NavItemStatus) \| undefined` | `undefined` | 返回每项的状态。**不传时所有项默认 `Completed`** |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+
+> **项按引用匹配。** `activeItem === item` 和 `highlights.indexOf(item)` 都用引用相等。不要在渲染间重建数组或克隆项 —— active / 高亮状态会丢。
+
+## NavItemStatus 枚举
+
+```typescript
+enum NavItemStatus {
+  Completed = 'nav-completed',  // 默认文字色
+  Warning   = 'nav-warning',    // 同色 + 右侧红点
+  NotStart  = 'nav-not-start',  // 变淡 + 斜体
+}
+```
+
+CSS 类名就是枚举值（`NavItemStatus.Completed === 'nav-completed'`），加到每项的 wrapper 上。
+
+## 布局
+
+```text
+┌─────────────────────────┐
+│ .uniface-navigator-panel │   (overflow:hidden，整高)
+│ ┌─────────────────────┐ │
+│ │ .navigator-content  │ │   (overflow-y:auto)
+│ │                     │ │
+│ │  ┃ ● 第一步         │ │   ← active（圆形标记 + 加粗）
+│ │  ┃   第二步         │ │   ← completed
+│ │  ┃   第三步       • │ │   ← warning（右侧红点）
+│ │  ┃   第四步         │ │   ← not-start（斜体、变淡）
+│ │                     │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+竖线是每项背景上的 CSS `linear-gradient`。首项 / 末项用半高 gradient，让线不超出视觉起止点。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="uniface-navigator-panel" style="...">
+  <div class="navigator-content">
+    <!-- 每项 -->
+    <div
+      class="uniface-navigator-item {retrieveStatus(item) ?? 'nav-completed'}"
+      class:active={activeItem === item}
+      class:highlight={highlights.indexOf(item) > -1}
+      aria-hidden="true"
+      onclick={() => handleClick(item)}
+    >
+      <span>{item.text}</span>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS 变量（都作用域在 `.uniface-navigator-panel`）
+
+| 变量 | 用途 |
+|------|------|
+| `--uniface-navigator-background-color` | 面板背景 |
+| `--uniface-navigator-vertical-padding` | 面板上下 padding |
+| `--uniface-navigator-completed-text-color` | `Completed` 项颜色 |
+| `--uniface-navigator-not-start-text-color` | `NotStart` 项颜色 |
+| `--uniface-navigator-warning-dot-color` | `Warning` 红点颜色 |
+| `--uniface-navigator-hover-text-color` | hover 色（非 active 项） |
+| `--uniface-navigator-active-text-color` | active 项颜色 + 标记边框色 |
+| `--uniface-navigator-active-text-weight` | active 项字重（默认 `600`） |
+| `--uniface-navigator-highlight-text-color` | 高亮色 |
+
+单实例覆盖：
+
+```svelte
+<div style="--uniface-navigator-active-text-color: #dc2626;">
+  <Navigator ... />
+</div>
+```
+
+或全局：
+
+```css
+:root {
+  --uniface-navigator-active-text-color: #0061ff;
+}
+```
+
+### 视觉标记
+
+- **active 项**：15px 圆（`.active::before`），4px 边框用 `--uniface-navigator-active-text-color`，白底，位置 `left: 5px; top: 50%`。active 项禁用 hover（`cursor: default`）
+- **warning 项**：6px 红点（`.nav-warning::after`），位置 `right: 8px; top: 30%`
+- **连接线**：每项背景上的 CSS `linear-gradient` 创建 1px 竖线，距左 12-13px。首项：上半段（线从项的垂直中线开始）。末项：下半段。中间项：整高
+
+## 示例
+
+### 多步向导 + 导航控件
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: '个人信息' },
+    { text: '联系方式' },
+    { text: '偏好设置' },
+    { text: '确认' }
+  ];
+
+  let activeItem = $state(steps[0]);
+  let highlights = $state<any>([]);
+
+  function getStepStatus(item: any): NavItemStatus {
+    const idx = steps.indexOf(item);
+    const currentIdx = steps.indexOf(activeItem);
+    if (idx < currentIdx) return NavItemStatus.Completed;
+    if (idx === currentIdx) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleClick(item: any) {
+    // 只允许回到已完成的步骤
+    if (steps.indexOf(item) > steps.indexOf(activeItem)) {
+      // 撤销 Navigator 已经做的 activeItem 改动
+      activeItem = steps.find(s => s === arguments[0]) ?? activeItem;
+    }
+  }
+
+  function next() {
+    const idx = steps.indexOf(activeItem);
+    if (idx < steps.length - 1) activeItem = steps[idx + 1];
+  }
+
+  function prev() {
+    const idx = steps.indexOf(activeItem);
+    if (idx > 0) activeItem = steps[idx - 1];
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  highlights={highlights}
+  retrieveStatus={getStepStatus}
+  itemClickHandler={handleClick}
+/>
+
+<div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
+  <h2>{activeItem.text}</h2>
+  <p>该步骤的内容。</p>
+  <div style="display: flex; gap: 8px;">
+    <button onclick={prev}>上一步</button>
+    <button onclick={next}>下一步</button>
+  </div>
+</div>
+```
+
+### 出错项（高亮 + 警告）
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: '账户',   hasError: false },
+    { text: '资料',   hasError: true  },   // 这一步有问题
+    { text: '确认',   hasError: false }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // 高亮任何出错的步骤
+  const highlights = steps.filter(s => s.hasError);
+
+  function getStatus(item: any): NavItemStatus {
+    if (item.hasError) return NavItemStatus.Warning;
+    return steps.indexOf(item) <= steps.indexOf(activeItem)
+      ? NavItemStatus.Completed
+      : NavItemStatus.NotStart;
+  }
+</script>
+
+<Navigator
+  items={steps}
+  bind:activeItem
+  {highlights}
+  retrieveStatus={getStatus}
+/>
+```
+
+### 仅展示（无点击导航）
+
+要纯展示（不可点）：
+
+```svelte
+<Navigator
+  items={steps}
+  activeItem={steps[steps.length - 1]}   {/* 末项视觉上 active */}
+  retrieveStatus={getStatus}
+/>
+```
+
+点击仍然会内部更新 `activeItem`（如果用了 `bind:` 或 `itemClickHandler`），但你可以两个都不传，让组件事实上只展示。没有 `bind:` 或 `itemClickHandler` 时内部状态仍然更新，但没人能知道。
+
+## 行为说明
+
+- **项按引用匹配，不是值。** 渲染间重建 `items` 数组（如 `.map`）会丢失 `activeItem` / `highlights` 匹配。保持 `items` 引用稳定
+- **`retrieveStatus` 不传时默认 `Completed`**。忘了传的话每项看起来都是"已完成"
+- **每次点击内部都更新 `activeItem`**，即使不用 `bind:` 或不传 `itemClickHandler`。组件内部自洽 —— 但父组件不会知道
+- **`handleClick` 先执行 `activeItem = item`**，再执行 `itemClickHandler?.(item)`。如果想**阻止** active 变更（比如用户没完成前置步骤），需要在 `itemClickHandler` 内部把 `activeItem` 设回去。没有 `canActivate` 谓词
+- **每项都有 `aria-hidden="true"`** —— 尽管是可点击 div，但屏幕阅读器看不到。这是 a11y 问题 —— 见下
+- **长标签横向裁剪**，不换行。wrapper 是单行
+
+## 无障碍访问（重大限制）
+
+这个组件有**已知的 a11y 问题**，你需要知道：
+
+1. **每项都有 `aria-hidden="true"`。** 整个导航对屏幕阅读器不可见 —— 它们不会朗读项、active 状态或状态颜色
+2. **项是 `<div onclick>`，不是 `<button>`。** 没有键盘焦点、没有 Enter/Space 激活、没有 `role="link"` 或 `role="button"`
+3. **状态只靠颜色传达**（Completed vs NotStart）外加 Warning 的小红点。没有文字替代
+4. **没有键盘用户的焦点样式**
+
+需要键盘可访问的步骤导航，自己用 `<button>` 包每一项并通过 snippet 传标签，或 fork 这个组件。视觉设计不错；语义不行。
+
+## 最佳实践
+
+1. **保持 `items` 引用稳定。** 定义一次（模块作用域或不重新赋值的 `$state`）。每次渲染 map 会破坏 active / 高亮匹配
+2. **用 `bind:activeItem`** 而不是 `itemClickHandler` 做纯状态同步。`itemClickHandler` 只在需要副作用时加
+3. **永远传 `retrieveStatus`**，除非你真的想每项默认看起来都是已完成
+4. **`Warning` + `highlights` 一起用**做错误状态 —— 红点抓眼球，高亮色加强
+5. **只能向后的向导**，在 `itemClickHandler` 里撤销越界点击的 active 变更。没有内置守卫
+6. **不要给键盘 / 屏幕阅读器用户用这个。** 见上面 a11y 说明
+
+## 相关组件
+
+- [Breadcrumbs](../breadcrumbs/README_CN.md) —— 水平路径式导航（这个是垂直步骤式）
+- [NavigatorMenu](../nav_menu/README_CN.md) —— 完整层级菜单

package/dist/navigation/pagination/Pagination.svelte

@@ -0,0 +1,192 @@
+<script lang="ts">
+
+
+    import type {OnPageChange} from "../../types";
+
+    interface Props {
+        pageCount: number;
+        pageNo?: number;
+        type?: 'plain' | 'round' | 'circle';
+        style?: string;
+        big?: boolean;
+        theme?: string;
+        onchange?: OnPageChange;
+    }
+
+    let {
+        pageCount = 0,
+        pageNo = 1,
+        type = "round",
+        style = '',
+        big = false,
+        theme,
+        onchange
+    }: Props = $props();
+
+    let pagination = $state<Array<number | null>>([]);
+
+    const buildPagination = () => {
+        if (pageNo < 1) {
+            pageNo = 1;
+        } else if (pageNo > pageCount) {
+            pageNo = pageCount;
+        }
+        const arr: Array<number | null> = [1];
+        if (pageCount < 6) {
+            for (let i = 2; i <= pageCount; i++) {
+                arr.push(i);
+            }
+        } else {
+            if (pageNo == 1 || pageNo == 2) {
+                arr.push(2, 3, null, pageCount);
+            } else if (pageNo == pageCount || pageNo == pageCount - 1) {
+                arr.push(null, pageCount - 2, pageCount - 1, pageCount);
+            } else if (pageNo == 3) {
+                arr.push(2, 3, 4, null, pageCount);
+            } else if (pageNo == pageCount - 2) {
+                arr.push(null, pageCount - 3, pageCount - 2, pageCount - 1, pageCount);
+            } else {
+                arr.push(null);
+                for (let i = pageNo - 1; i <= pageNo + 1; i++) {
+                    arr.push(i);
+                }
+                arr.push(null);
+                arr.push(pageCount);
+            }
+        }
+        pagination = arr;
+    }
+
+    const selectPage = (value: number) => (e: MouseEvent) => {
+        if (pageNo != value) {
+            onchange?.(value);
+        }
+    };
+
+    $effect(() => {
+        buildPagination();
+    });
+</script>
+
+<div class="uniface-pagination-panel {type}" class:big {style} data-theme={theme}>
+    {#each pagination as page}
+        {#if page}
+            <div class="uniface-page-no" onclick={selectPage(page)} aria-hidden="true" class:selected={page === pageNo}>
+                <span tabindex="-1">
+                    {page}
+                </span>
+            </div>
+        {:else}
+            <div class="uniface-page-gap">
+                <span>...</span>
+            </div>
+        {/if}
+    {/each}
+</div>
+
+<style>
+    .uniface-pagination-panel {
+        width: 100%;
+        overflow: hidden;
+        white-space: nowrap;
+        text-align: center;
+        position: relative;
+        user-select: none;
+    }
+
+    .uniface-pagination-panel.align-left {
+        text-align: left;
+    }
+
+    .uniface-pagination-panel.align-right {
+        text-align: right;
+    }
+
+    .uniface-page-gap,
+    .uniface-page-no {
+        position: relative;
+        display: inline-block;
+        margin: 0 8px;
+        overflow: hidden;
+        width: 2em;
+        height: 2em;
+    }
+
+    .uniface-page-gap span,
+    .uniface-page-no span {
+        display: inline-block;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        text-align: center;
+        line-height: 2em;
+    }
+
+    .uniface-page-no {
+        border-radius: 4px;
+        color: var(--uniface-default-text-color, #374151);
+        border: 1px solid var(--uniface-primary-border-color, #E2E8F0);
+        cursor: pointer;
+    }
+
+    .uniface-page-no:hover {
+        border-color: var(--uniface-default-text-hover-color, #298DFF80);
+    }
+
+    .uniface-page-no:active {
+        top: 1px;
+        color: var(--uniface-default-active-text-color, #0061FF);
+    }
+
+    .uniface-page-no.selected {
+        color: var(--uniface-default-active-text-color, #0061FF);
+        border-color: var(--uniface-default-active-border-color, #0061FF80);
+        cursor: default;
+    }
+
+    .uniface-page-no.selected:active {
+        top: 0;
+        color: var(--uniface-pagination-selected-color, #ffffff);
+        background-color: var(--uniface-button-primary-border-color, #42A5F5);
+    }
+
+    /* Plain type */
+    .uniface-pagination-panel.plain .uniface-page-no {
+        background-color: inherit;
+        border: none;
+    }
+
+    .uniface-pagination-panel.plain .uniface-page-no span {
+        color: #7f7f7f;
+    }
+
+    .uniface-pagination-panel.plain .uniface-page-no:hover span {
+        background-color: inherit;
+        color: var(--uniface-button-primary-border-color, #42A5F5);
+    }
+
+    .uniface-pagination-panel.plain .uniface-page-no:active span {
+        color: var(--uniface-button-primary-border-color, #42A5F5);
+    }
+
+    .uniface-pagination-panel.plain .uniface-page-no.selected span {
+        font-weight: 600;
+        color: var(--uniface-pagination-selected-background-color, #333333);
+    }
+
+    /* Circle type */
+    .uniface-pagination-panel.circle .uniface-page-no {
+        border-radius: 50%;
+    }
+
+    /* Big size */
+    .uniface-pagination-panel.big .uniface-page-gap,
+    .uniface-pagination-panel.big .uniface-page-no {
+        width: 3em;
+        height: 3em;
+    }
+
+    .uniface-pagination-panel.big .uniface-page-gap span,
+    .uniface-pagination-panel.big .uniface-page-no span {
+        line-height: 3em;
+    }
+</style>

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

@@ -0,0 +1,13 @@
+import type { OnPageChange } from "../../types";
+interface Props {
+    pageCount: number;
+    pageNo?: number;
+    type?: 'plain' | 'round' | 'circle';
+    style?: string;
+    big?: boolean;
+    theme?: string;
+    onchange?: OnPageChange;
+}
+declare const Pagination: import("svelte").Component<Props, {}, "">;
+type Pagination = ReturnType<typeof Pagination>;
+export default Pagination;