@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/navigation/nav_menu/README_CN.md

@@ -0,0 +1,222 @@
+# NavigatorMenu 导航菜单组件
+
+基于 Svelte 5 构建的分层导航菜单组件，支持具有展开/折叠功能的嵌套菜单项。
+
+## 特性
+
+- **分层结构**：支持多级嵌套菜单项
+- **展开/折叠**：点击展开或折叠菜单部分
+- **平滑动画**：子菜单滑动过渡效果
+- **可定制**：灵活的文本字段配置
+- **点击处理**：菜单项选择的事件回调
+- **CSS 变量**：可使用 CSS 变量进行主题化
+- **递归渲染**：自动处理嵌套菜单结构
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import { NavigatorMenu } from '@ticatec/uniface-element/NavigatorMenu';
+import type MenuItem from '@ticatec/uniface-element/MenuItem';
+```
+
+或者在同一项目中使用：
+```typescript
+import { NavigatorMenu } from '$lib/nav-menu';
+import type MenuItem from '$lib/nav-menu/MenuItem';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  let menuItems = $state([
+    {
+      item: { label: '仪表板', path: '/dashboard' },
+      children: []
+    },
+    {
+      item: { label: '项目', path: '/projects' },
+      children: [
+        { item: { label: '进行中', path: '/projects/active' } },
+        { item: { label: '已归档', path: '/projects/archived' } }
+      ]
+    }
+  ]);
+
+  function handleMenuClick(item) {
+    console.log('点击了：', item);
+  }
+</script>
+
+<NavigatorMenu
+  menuItems={menuItems}
+  textField="label"
+  onItemClick={handleMenuClick}
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 必填 | 描述 |
+|------|------|------|-------------|
+| `menuItems` | `Array<MenuItem>` | 是 | 菜单项对象数组 |
+| `textField` | `string \| GetText<MenuItem>` | 是 | 字段名称或获取显示文本的函数 |
+| `onItemClick` | `(item: MenuItem) => void` | 是 | 点击菜单项时的回调 |
+| `style` | `string` | 否 | 自定义内联样式 |
+
+## MenuItem 结构
+
+```typescript
+interface MenuItem {
+  item: {
+    [key: string]: any;  // 您的数据对象
+    label?: string;      // 显示文本（如果使用字符串 textField）
+  };
+  children?: MenuItem[];  // 嵌套菜单项
+  expand?: boolean;      // 初始展开状态
+}
+```
+
+## 示例
+
+### 简单菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const simpleMenu = [
+    { item: { name: '首页', icon: 'home' } },
+    { item: { name: '关于', icon: 'info' } },
+    { item: { name: '联系', icon: 'mail' } }
+  ];
+</script>
+
+<NavigatorMenu
+  menuItems={simpleMenu}
+  textField="name"
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+### 嵌套菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const nestedMenu = [
+    {
+      item: { title: '产品' },
+      expand: true,
+      children: [
+        { item: { title: '电子产品', category: 'electronics' } },
+        { item: { title: '服装', category: 'clothing' } },
+        {
+          item: { title: '更多' },
+          children: [
+            { item: { title: '图书' } },
+            { item: { title: '玩具' } }
+          ]
+        }
+      ]
+    },
+    {
+      item: { title: '服务' },
+      children: [
+        { item: { title: '咨询' } },
+        { item: { title: '支持' } }
+      ]
+    }
+  ];
+</script>
+
+<NavigatorMenu
+  menuItems={nestedMenu}
+  textField="title"
+  onItemClick={(item) => navigate(item.path)}
+/>
+```
+
+### 自定义文本函数
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const customMenu = [
+    {
+      item: { firstName: '张', lastName: '三', role: '管理员' },
+      children: []
+    }
+  ];
+
+  function getText(item) {
+    return `${item.firstName}${item.lastName} (${item.role})`;
+  }
+</script>
+
+<NavigatorMenu
+  menuItems={customMenu}
+  textField={getText}
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+## 样式定制
+
+### CSS 变量
+
+```css
+:root {
+  --nav-menu-bg: #ffffff;
+  --nav-menu-color: #374151;
+  --nav-menu-hover-bg: #81D4FA;
+  --nav-menu-hover-color: #374151;
+}
+```
+
+### 深色主题
+
+```css
+.theme-dark {
+  --nav-menu-bg: #1a1a1a;
+  --nav-menu-color: #e0e0e0;
+  --nav-menu-hover-bg: #3a3a3a;
+  --nav-menu-hover-color: #e0e0e0;
+}
+```
+
+## 行为
+
+### 展开/折叠
+
+- 点击带有子项的菜单项切换其展开状态
+- 点击叶子项（无子项）触发 `onItemClick`
+- 200ms 防抖防止快速点击
+- 箭头指示器（▲）显示在可展开项上
+
+### 动画
+
+- 子菜单使用 `slide` 过渡，持续 200ms
+- 平滑的展开/折叠动画
+
+## 最佳实践
+
+1. **一致的结构**：在各层级保持菜单项结构一致
+2. **深度限制**：避免嵌套超过 3-4 层以提高可用性
+3. **性能**：对于非常大的菜单，考虑虚拟化
+4. **标签**：使用清晰简洁的文本标签
+5. **图标**：考虑添加图标以获得更好的视觉层次
+
+## 注意事项
+
+- 组件自动处理嵌套项的递归渲染
+- `expand` 属性控制初始展开状态
+- 文本字段可以是字符串键或用于自定义显示逻辑的函数

package/dist/navigation/navigator/Navigator.svelte

@@ -0,0 +1,155 @@
+<script lang="ts">
+    import {NavItemStatus} from "./NavItemStatus";
+
+    type ItemClickHandler = (item: any) => void;
+    type RetrieveItemStatus = (item: any) => NavItemStatus;
+
+    interface Props {
+        items: Array<any>;
+        activeItem?: any;
+        style?: string;
+        highlights?: Array<any>;
+        itemClickHandler?: ItemClickHandler;
+        retrieveStatus?: RetrieveItemStatus;
+    }
+
+    let {
+        items,
+        activeItem = $bindable(),
+        style = "",
+        highlights = [],
+        itemClickHandler,
+        retrieveStatus
+    }: Props = $props();
+
+    const handleClick = (item: any) => {
+        activeItem = item;
+        itemClickHandler?.(item);
+    };
+</script>
+
+<div class="uniface-navigator-panel" {style}>
+    <div class="navigator-content">
+        {#each items as item}
+            <div class="uniface-navigator-item {retrieveStatus?.(item) ?? NavItemStatus.Completed}"
+                 class:active={activeItem === item}
+                 class:highlight={highlights.indexOf(item) > -1}
+                 aria-hidden="true"
+                 onclick={() => handleClick(item)}>
+                <span>{item.text}</span>
+            </div>
+        {/each}
+    </div>
+</div>
+
+<style>
+    .uniface-navigator-panel {
+        --uniface-navigator-background-color: var(--uniface-application-bg);
+        --uniface-navigator-vertical-padding: 16px;
+        --uniface-navigator-completed-text-color: #374151;
+        --uniface-navigator-not-start-text-color: #6B7280;
+        --uniface-navigator-warning-dot-color: #C62828;
+        --uniface-navigator-hover-text-color: #298DFF;
+        --uniface-navigator-active-text-color: #0061FF;
+        --uniface-navigator-active-text-weight: 600;
+        --uniface-navigator-highlight-text-color: #0061FF;
+
+        position: relative;
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        overflow: hidden;
+        background-color: var(--uniface-navigator-background-color);
+    }
+
+    .navigator-content {
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        overflow-y: auto;
+        overflow-x: hidden;
+        position: relative;
+        user-select: none;
+    }
+
+    .uniface-navigator-item {
+        font-size: 12px;
+        padding: 4px 8px 4px 24px;
+        position: relative;
+        background: linear-gradient(to right, transparent 12px, lightgray 12px, lightgray 13px, transparent 13px);
+    }
+
+    .uniface-navigator-item:first-child {
+        background-size: 100% 60%;
+        background-position: bottom;
+        background-repeat: no-repeat;
+    }
+
+    .uniface-navigator-item:last-child {
+        background-size: 100% 60%;
+        background-position: top;
+        background-repeat: no-repeat;
+    }
+
+    .uniface-navigator-item.nav-completed {
+        color: var(--uniface-navigator-completed-text-color);
+    }
+
+    .uniface-navigator-item.nav-warning {
+        color: var(--uniface-navigator-completed-text-color);
+        position: relative;
+    }
+
+    .uniface-navigator-item.nav-warning::after {
+        content: "";
+        position: absolute;
+        right: 8px;
+        top: 30%;
+        transform: translateY(-50%);
+        width: 6px;
+        height: 6px;
+        border-radius: 50%;
+        background-color: var(--uniface-navigator-warning-dot-color);
+    }
+
+    .uniface-navigator-item.nav-not-start {
+        color: var(--uniface-navigator-not-start-text-color);
+        font-style: italic;
+    }
+
+    .uniface-navigator-item:hover {
+        color: var(--uniface-navigator-hover-text-color);
+        cursor: pointer;
+    }
+
+    .uniface-navigator-item.highlight {
+        color: var(--uniface-navigator-highlight-text-color);
+    }
+
+    .uniface-navigator-item.active {
+        color: var(--uniface-navigator-active-text-color);
+        font-weight: var(--uniface-navigator-active-text-weight);
+    }
+
+    .uniface-navigator-item.active::before {
+        content: "";
+        position: absolute;
+        left: 5px;
+        top: 50%;
+        transform: translateY(-50%);
+        width: 15px;
+        height: 15px;
+        border: 4px solid var(--uniface-navigator-active-text-color);
+        border-radius: 50%;
+        background-color: white;
+    }
+
+    .uniface-navigator-item.active:hover {
+        color: var(--uniface-navigator-active-text-color);
+        cursor: default;
+    }
+
+    .uniface-navigator-item.active.nav-not-start {
+        font-style: normal;
+    }
+</style>

package/dist/navigation/navigator/Navigator.svelte.d.ts

@@ -0,0 +1,14 @@
+import { NavItemStatus } from "./NavItemStatus";
+type ItemClickHandler = (item: any) => void;
+type RetrieveItemStatus = (item: any) => NavItemStatus;
+interface Props {
+    items: Array<any>;
+    activeItem?: any;
+    style?: string;
+    highlights?: Array<any>;
+    itemClickHandler?: ItemClickHandler;
+    retrieveStatus?: RetrieveItemStatus;
+}
+declare const Navigator: import("svelte").Component<Props, {}, "activeItem">;
+type Navigator = ReturnType<typeof Navigator>;
+export default Navigator;

package/dist/navigation/navigator/README.md

@@ -0,0 +1,302 @@
+# Navigator Component
+
+A vertical step / wizard navigator. Renders items as a clickable list with a connecting vertical line on the left, an active marker (filled circle), per-item status colors (completed / warning / not-start), and optional highlights. Designed for multi-step forms and guided workflows.
+
+## Features
+
+- **Vertical wizard trail**: each item gets a left-aligned line segment via CSS gradient; first/last items render half-segments so the line starts at the top of the first item and ends at the bottom of the last
+- **Three status states**: `Completed`, `Warning` (red dot), `NotStart` (italic, dimmed) — drive them via a `retrieveStatus` callback
+- **Active marker**: the active item shows a 15px bordered circle on the left
+- **Highlights array**: extra "look at me" color for arbitrary items (e.g. items with errors)
+- **Two-way bindable `activeItem`**: `bind:activeItem` updates on click without needing `itemClickHandler`
+- **Scrolls vertically** when items overflow
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: 'Step 1' },
+    { text: 'Step 2' },
+    { text: 'Step 3' },
+    { text: 'Step 4' }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // Mark items before activeItem as Completed, after as 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}
+/>
+```
+
+With `bind:activeItem`, clicking an item updates `activeItem` directly. No `itemClickHandler` needed unless you want to run side effects (analytics, validation, route change).
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Array<any>` | _(required)_ | Nav items. Each **must have a `text` property** for the label. Other fields are yours. |
+| `activeItem` | `any` | `$bindable(undefined)` | Currently active item. **`bind:activeItem`** for two-way binding; on click, the component assigns the clicked item here before calling `itemClickHandler`. |
+| `highlights` | `Array<any>` | `[]` | Items to highlight (e.g. items with errors). Matched by reference equality. |
+| `itemClickHandler` | `((item: any) => void) \| undefined` | `undefined` | Called on every click, **after** `activeItem` is updated. Use for side effects; not needed for state updates if you `bind:activeItem`. |
+| `retrieveStatus` | `((item: any) => NavItemStatus) \| undefined` | `undefined` | Returns the status for each item. **If omitted, all items default to `Completed`.** |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+
+> **Items matched by reference.** `activeItem === item` and `highlights.indexOf(item)` both use reference equality. Don't reconstruct arrays or clone items between renders — the active / highlight state will be lost.
+
+## NavItemStatus Enum
+
+```typescript
+enum NavItemStatus {
+  Completed = 'nav-completed',  // Default text color
+  Warning   = 'nav-warning',    // Same color + red dot on the right
+  NotStart  = 'nav-not-start',  // Dimmed + italic
+}
+```
+
+The CSS class is the enum value (`NavItemStatus.Completed === 'nav-completed'`), applied to each item's wrapper.
+
+## Layout
+
+```text
+┌─────────────────────────┐
+│ .uniface-navigator-panel │   (overflow:hidden, full height)
+│ ┌─────────────────────┐ │
+│ │ .navigator-content  │ │   (overflow-y:auto)
+│ │                     │ │
+│ │  ┃ ● Step 1         │ │   ← active (circle marker, bold)
+│ │  ┃   Step 2         │ │   ← completed
+│ │  ┃   Step 3       • │ │   ← warning (red dot right)
+│ │  ┃   Step 4         │ │   ← not-start (italic, dimmed)
+│ │                     │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+The vertical line is a CSS `linear-gradient` on each item's background. The first/last items get half-height gradients so the line doesn't extend past the visual start/end.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="uniface-navigator-panel" style="...">
+  <div class="navigator-content">
+    <!-- per item -->
+    <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 Variables (all scoped to `.uniface-navigator-panel`)
+
+| Variable | Purpose |
+|----------|---------|
+| `--uniface-navigator-background-color` | Panel background |
+| `--uniface-navigator-vertical-padding` | Panel top/bottom padding |
+| `--uniface-navigator-completed-text-color` | `Completed` item color |
+| `--uniface-navigator-not-start-text-color` | `NotStart` item color |
+| `--uniface-navigator-warning-dot-color` | `Warning` red dot color |
+| `--uniface-navigator-hover-text-color` | Hover color (non-active items) |
+| `--uniface-navigator-active-text-color` | Active item color + marker border |
+| `--uniface-navigator-active-text-weight` | Active item font weight (default `600`) |
+| `--uniface-navigator-highlight-text-color` | Highlight color |
+
+Override per-instance:
+
+```svelte
+<div style="--uniface-navigator-active-text-color: #dc2626;">
+  <Navigator ... />
+</div>
+```
+
+Or globally:
+
+```css
+:root {
+  --uniface-navigator-active-text-color: #0061ff;
+}
+```
+
+### Visual markers
+
+- **Active item**: a 15px circle (`.active::before`) with a 4px border in `--uniface-navigator-active-text-color`, white fill, positioned at `left: 5px; top: 50%`. Hover is suppressed on active items (`cursor: default`).
+- **Warning item**: a 6px red dot (`.nav-warning::after`) at `right: 8px; top: 30%`.
+- **Connecting line**: CSS `linear-gradient` on each item's background creates a 1px vertical line at `12-13px` from the left. First item: top half (so the line starts at the item's vertical center). Last item: bottom half. Middle items: full height.
+
+## Examples
+
+### Multi-Step Wizard with Navigation Controls
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: 'Personal Info' },
+    { text: 'Contact Details' },
+    { text: 'Preferences' },
+    { text: 'Review' }
+  ];
+
+  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) {
+    // Only allow navigating back to completed steps
+    if (steps.indexOf(item) > steps.indexOf(activeItem)) {
+      // revert the activeItem change Navigator already applied
+      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>Content for this step.</p>
+  <div style="display: flex; gap: 8px;">
+    <button onclick={prev}>Previous</button>
+    <button onclick={next}>Next</button>
+  </div>
+</div>
+```
+
+### Items with Errors (highlights + warning)
+
+```svelte
+<script lang="ts">
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: 'Account',  hasError: false },
+    { text: 'Profile',  hasError: true  },   // this one has issues
+    { text: 'Confirm',  hasError: false }
+  ];
+
+  let activeItem = $state(steps[0]);
+
+  // Highlight any step with errors
+  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}
+/>
+```
+
+### Status-Only (No Click Navigation)
+
+If you want display-only (no click):
+
+```svelte
+<Navigator
+  items={steps}
+  activeItem={steps[steps.length - 1]}   {/* last item visually active */}
+  retrieveStatus={getStatus}
+/>
+```
+
+Clicks will still update `activeItem` internally (if `bind:` or `itemClickHandler` is set), but you can omit both and let the component be effectively display-only. Without `bind:` or `itemClickHandler`, internal state still updates but no one hears about it.
+
+## Behavior Notes
+
+- **Items matched by reference, not value.** Reconstructing the `items` array (e.g. via `.map`) on every render will lose `activeItem` / `highlights` matching. Keep `items` referentially stable.
+- **`retrieveStatus` defaults to `Completed`** when omitted. If you forget to pass it, every item will look "done".
+- **`activeItem` is updated internally on every click**, even if you don't `bind:` or pass `itemClickHandler`. The component is internally consistent — but the parent won't know.
+- **`handleClick` runs `activeItem = item` first**, then `itemClickHandler?.(item)`. If you want to **prevent** the active change (e.g. user hasn't completed prerequisites), you need to undo it inside `itemClickHandler` by setting `activeItem` back. There's no `canActivate` predicate.
+- **`aria-hidden="true"` on every item** — despite being clickable divs, they're hidden from screen readers. This is an a11y issue; see below.
+- **Long labels clip horizontally**, not wrap. The wrapper is single-line.
+
+## Accessibility (Significant Limitations)
+
+This component has **known a11y problems** you should be aware of:
+
+1. **Every item has `aria-hidden="true"`.** The entire navigation is invisible to screen readers — they won't announce items, the active state, or status colors.
+2. **Items are `<div onclick>`, not `<button>`.** No keyboard focus, no Enter/Space activation, no `role="link"` or `role="button"`.
+3. **Status is conveyed by color alone** (Completed vs NotStart) plus a small red dot for Warning. No text alternative.
+4. **No focus styles** for keyboard users.
+
+If you need keyboard-accessible step navigation, wrap each item in your own `<button>` and pass labels via the snippet pattern, or fork the component. The visual design is good; the semantics are not.
+
+## Best Practices
+
+1. **Keep `items` referentially stable.** Define it once (module scope or `$state` that you don't reassign). Mapping on every render breaks active/highlight matching.
+2. **Use `bind:activeItem`** instead of `itemClickHandler` for plain state sync. Add `itemClickHandler` only for side effects.
+3. **Always provide `retrieveStatus`** unless you really want every item to look completed by default.
+4. **Use `Warning` + `highlights` together** for error states — the red dot catches the eye, the highlight color reinforces it.
+5. **For forward-only wizards**, undo the active change in `itemClickHandler` if the user clicks ahead. There's no built-in guard.
+6. **Don't rely on this for keyboard / screen-reader users.** See a11y note above.
+
+## Related Components
+
+- [Breadcrumbs](../breadcrumbs/README.md) — horizontal path-style navigation (this is vertical step-style)
+- [NavigatorMenu](../nav_menu/README.md) — full hierarchical menu