@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/data_display/list_box/README.md

@@ -0,0 +1,156 @@
+# ListBox
+
+A list component with optional header / footer snippets, built-in search, lazy loading, and single / multiple selection modes.
+
+> Svelte 5 component. Custom header/footer/load-more content is passed as **Snippets** (`header`, `footer`, `loadMoreIndicator`).
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```svelte
+<script lang="ts">
+  import ListBox from '@ticatec/uniface-element/ListBox';
+  import type { FunFilter, ListLazyLoader, LoadResult } from '@ticatec/uniface-element/types';
+</script>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `list` | `Array<any>` | `undefined` | Items to render. Required unless using `lazyLoader` |
+| `itemRender` | `SvelteComponent` | `undefined` | Component used to render each item. Receives `{ item, readonly, selected, ...item$props }` |
+| `item$props` | `any` | `undefined` | Extra props spread onto every `itemRender` instance |
+| `selectMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | Selection behavior. `'multiple'` renders a checkbox per row |
+| `selectedItem` | `any` | `undefined` | Currently selected item in single mode (one-way in; component mirrors into local state) |
+| `selectedList` | `Array<any>` | `[]` | Selected items in multiple mode. **Bindable** — use `bind:selectedList` |
+| `readonly` | `boolean` | `false` | Disables selection and hides the search box |
+| `filter` | `FunFilter \| null` | `null` | If set, a search box appears at the top |
+| `lazyLoader` | `ListLazyLoader \| null` | `null` | If set, replaces `list` with a paginated source. Search box appears and infinite-scroll is wired up |
+| `filterText` | `string` | `undefined` | Initial / controlled filter text |
+| `title` | `string` | `undefined` | Plain-text title shown in the header (ignored if `header` snippet is provided) |
+| `round` | `boolean` | `false` | Adds a border radius (`--uniface-radius`) |
+| `class` | `string` | `undefined` | Extra class on the root |
+| `style` | `string \| null` | `null` | Inline CSS on the root |
+| `header` | `Snippet` | `undefined` | Custom header content (overrides `title`) |
+| `footer` | `Snippet` | `undefined` | Custom footer content |
+| `loadMoreIndicator` | `Snippet` | `undefined` | Custom "loading more" indicator shown at the bottom while `hasMore` |
+| `onSelectChange` | `(item: any) => void` | `undefined` | Single-mode: fires when the selected item changes (also fires with `null` when filter resets selection) |
+| `onItemDblClick` | `(item: any) => void` | `undefined` | Single-mode only |
+| `onItemClick` | `(item: any) => void` | `undefined` | Non-single modes |
+
+## Types
+
+```ts
+type FunFilter      = (item: any, text: string) => boolean;
+type ListLazyLoader = (text: string, pageNo: number) => Promise<LoadResult>;
+
+interface LoadResult {
+  list: Array<any>;
+  hasMore: boolean;
+}
+```
+
+> `pageNo` is **1-based** in the actual implementation (the type-doc comment saying "from 0" is wrong). First call is `lazyLoader('', 1)`.
+
+## Selection model
+
+- **`selectMode='none'`** — no selection visuals, no callbacks. `onItemClick` still fires.
+- **`selectMode='single'`** — click an item to select; `onSelectChange(item)` fires. `selectedItem` is mirrored into local state on prop change.
+- **`selectMode='multiple'`** — checkbox per row; the checked set is stored in `selectedList` (use `bind:selectedList`). Clicking the row label toggles the same checkbox.
+
+## Examples
+
+### Single-select with filter
+
+```svelte
+<script lang="ts">
+  import ListBox from '@ticatec/uniface-element/ListBox';
+  import UserItem from './UserItem.svelte';
+
+  const users = [
+    { id: 1, name: 'Alice', email: 'alice@example.com' },
+    { id: 2, name: 'Bob',   email: 'bob@example.com' },
+  ];
+
+  const filter = (item: any, text: string) =>
+    item.name.toLowerCase().includes(text.toLowerCase()) ||
+    item.email.toLowerCase().includes(text.toLowerCase());
+
+  const onSelectChange = (item: any) => console.log('selected', item);
+</script>
+
+<ListBox
+  list={users}
+  itemRender={UserItem}
+  selectMode="single"
+  {filter}
+  title="Users"
+  round
+  onSelectChange={onSelectChange}
+  style="height: 400px;"
+/>
+```
+
+### Multiple-select with `bind:selectedList`
+
+```svelte
+<script lang="ts">
+  let selected: any[] = [];
+</script>
+
+<ListBox list={users} itemRender={UserItem} selectMode="multiple" bind:selectedList={selected} />
+
+<button disabled={selected.length === 0} onclick={() => console.log(selected)}>OK</button>
+```
+
+### Lazy-loaded list with custom footer
+
+```svelte
+<script lang="ts">
+  const lazyLoader = async (text: string, pageNo: number) => {
+    const res = await fetch(`/api/users?q=${text}&page=${pageNo}`);
+    return res.json() as Promise<{ list: any[]; hasMore: boolean }>;
+  };
+</script>
+
+<ListBox itemRender={UserItem} selectMode="single" {lazyLoader} title="Search users">
+  {#snippet footer()}
+    <div style="padding: 4px 8px; color: #888;">End of list</div>
+  {/snippet}
+</ListBox>
+```
+
+When `lazyLoader` is set:
+- The component calls it on mount with `('', 1)`.
+- Search box debounces (50ms idle) before re-querying from page 1.
+- Scrolling to the bottom triggers the next page until `hasMore === false`.
+
+## Styling
+
+CSS custom variables consumed by the SCSS (override on the root or any ancestor):
+
+| Variable | Used on |
+|----------|---------|
+| `--uniface-list-box-border-color` | Outer border |
+| `--uniface-list-box-header-surface` | Header background |
+| `--uniface-list-box-header-height` | Header height |
+| `--uniface-list-box-header-margin` | Header padding |
+| `--uniface-list-box-header-bottom-border` | Border below header |
+| `--uniface-list-box-hover-surface` | Row hover background |
+| `--uniface-list-box-selected-surface` | Selected row background |
+| `--uniface-listbox-separator-color` | Row separator |
+| `--uniface-list-box-footer-surface` | Footer background |
+| `--uniface-list-box-fotter-top-border` | Border above footer (typo preserved from source) |
+| `--uniface-radius` | Border radius when `round` is on |
+
+## Accessibility
+
+- Single-mode rows are clickable; the `cursor: pointer` hint is applied via the `selectable` class.
+- Read-only mode disables selection and hides the search box.
+- The component relies on the consumer's `itemRender` for in-row semantics (labels, roles, etc.).

package/dist/data_display/list_box/README_CN.md

@@ -0,0 +1,156 @@
+# ListBox 列表框
+
+列表组件，可选 header / footer snippet、内置搜索框、懒加载、单选 / 多选。
+
+> Svelte 5 组件。header / footer / 加载更多 通过 **Snippet** 传入（`header`、`footer`、`loadMoreIndicator`）。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```svelte
+<script lang="ts">
+  import ListBox from '@ticatec/uniface-element/ListBox';
+  import type { FunFilter, ListLazyLoader, LoadResult } from '@ticatec/uniface-element/types';
+</script>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `list` | `Array<any>` | `undefined` | 要渲染的数据。不使用 `lazyLoader` 时必填 |
+| `itemRender` | `SvelteComponent` | `undefined` | 渲染每个 item 的组件。收到 `{ item, readonly, selected, ...item$props }` |
+| `item$props` | `any` | `undefined` | 额外 props，会展开传给每个 `itemRender` 实例 |
+| `selectMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | 选择行为。`'multiple'` 会给每行加一个 checkbox |
+| `selectedItem` | `any` | `undefined` | 单选模式下当前选中的 item（单向输入；组件会镜像到内部状态） |
+| `selectedList` | `Array<any>` | `[]` | 多选模式下选中的 items。**可绑定** —— 用 `bind:selectedList` |
+| `readonly` | `boolean` | `false` | 禁用选择，隐藏搜索框 |
+| `filter` | `FunFilter \| null` | `null` | 设置后顶部会出现搜索框 |
+| `lazyLoader` | `ListLazyLoader \| null` | `null` | 设置后用分页数据源代替 `list`，自动出现搜索框 + 滚动到底加载下一页 |
+| `filterText` | `string` | `undefined` | 初始 / 受控的过滤文本 |
+| `title` | `string` | `undefined` | 标题纯文本。传了 `header` snippet 时被忽略 |
+| `round` | `boolean` | `false` | 加圆角（`--uniface-radius`） |
+| `class` | `string` | `undefined` | 根节点附加 class |
+| `style` | `string \| null` | `null` | 根节点内联 CSS |
+| `header` | `Snippet` | `undefined` | 自定义 header（覆盖 `title`） |
+| `footer` | `Snippet` | `undefined` | 自定义 footer |
+| `loadMoreIndicator` | `Snippet` | `undefined` | 自定义"加载更多"指示器，`hasMore` 时显示在底部 |
+| `onSelectChange` | `(item: any) => void` | `undefined` | 单选模式：选中变化时触发（过滤重置时也会以 `null` 触发一次） |
+| `onItemDblClick` | `(item: any) => void` | `undefined` | 仅单选模式 |
+| `onItemClick` | `(item: any) => void` | `undefined` | 仅非 single 模式 |
+
+## 类型
+
+```ts
+type FunFilter      = (item: any, text: string) => boolean;
+type ListLazyLoader = (text: string, pageNo: number) => Promise<LoadResult>;
+
+interface LoadResult {
+  list: Array<any>;
+  hasMore: boolean;
+}
+```
+
+> `pageNo` 是 **从 1 开始** 的（`types.ts` 里"从 0 开始"的注释是错的）。首次调用是 `lazyLoader('', 1)`。
+
+## 选择模型
+
+- **`selectMode='none'`** —— 没有选择视觉，没有回调。`onItemClick` 仍会触发。
+- **`selectMode='single'`** —— 点击 item 选中，触发 `onSelectChange(item)`。`selectedItem` 变化时会镜像到内部状态。
+- **`selectMode='multiple'`** —— 每行一个 checkbox；选中集合存在 `selectedList`（用 `bind:selectedList`）。点行标签也会切换同一个 checkbox。
+
+## 示例
+
+### 单选 + 过滤
+
+```svelte
+<script lang="ts">
+  import ListBox from '@ticatec/uniface-element/ListBox';
+  import UserItem from './UserItem.svelte';
+
+  const users = [
+    { id: 1, name: 'Alice', email: 'alice@example.com' },
+    { id: 2, name: 'Bob',   email: 'bob@example.com' },
+  ];
+
+  const filter = (item: any, text: string) =>
+    item.name.toLowerCase().includes(text.toLowerCase()) ||
+    item.email.toLowerCase().includes(text.toLowerCase());
+
+  const onSelectChange = (item: any) => console.log('selected', item);
+</script>
+
+<ListBox
+  list={users}
+  itemRender={UserItem}
+  selectMode="single"
+  {filter}
+  title="Users"
+  round
+  {onSelectChange}
+  style="height: 400px;"
+/>
+```
+
+### 多选 + `bind:selectedList`
+
+```svelte
+<script lang="ts">
+  let selected: any[] = [];
+</script>
+
+<ListBox list={users} itemRender={UserItem} selectMode="multiple" bind:selectedList={selected} />
+
+<button disabled={selected.length === 0} onclick={() => console.log(selected)}>OK</button>
+```
+
+### 懒加载 + 自定义 footer
+
+```svelte
+<script lang="ts">
+  const lazyLoader = async (text: string, pageNo: number) => {
+    const res = await fetch(`/api/users?q=${text}&page=${pageNo}`);
+    return res.json() as Promise<{ list: any[]; hasMore: boolean }>;
+  };
+</script>
+
+<ListBox itemRender={UserItem} selectMode="single" {lazyLoader} title="用户搜索">
+  {#snippet footer()}
+    <div style="padding: 4px 8px; color: #888;">到底了</div>
+  {/snippet}
+</ListBox>
+```
+
+`lazyLoader` 启用后：
+- 挂载时以 `('', 1)` 调用一次
+- 搜索框 50ms 防抖，从第 1 页重新查
+- 滚动到底自动加载下一页，直到 `hasMore === false`
+
+## 样式定制
+
+SCSS 中消费的 CSS 变量（在根或任意祖先覆盖）：
+
+| 变量 | 用处 |
+|------|------|
+| `--uniface-list-box-border-color` | 外边框 |
+| `--uniface-list-box-header-surface` | header 背景 |
+| `--uniface-list-box-header-height` | header 高度 |
+| `--uniface-list-box-header-margin` | header 内边距 |
+| `--uniface-list-box-header-bottom-border` | header 下方分隔线 |
+| `--uniface-list-box-hover-surface` | 行悬停背景 |
+| `--uniface-list-box-selected-surface` | 选中行背景 |
+| `--uniface-listbox-separator-color` | 行分隔线 |
+| `--uniface-list-box-footer-surface` | footer 背景 |
+| `--uniface-list-box-fotter-top-border` | footer 上方分隔线（注意 `fotter` 拼写沿用源码） |
+| `--uniface-radius` | 开启 `round` 时的圆角 |
+
+## 无障碍
+
+- 单选模式下整行可点；`selectable` class 加上 `cursor: pointer`
+- 只读模式禁用选择并隐藏搜索框
+- 行内的语义（label、role 等）依赖使用方传入的 `itemRender`

package/dist/data_display/list_box/index.d.ts

@@ -0,0 +1,5 @@
+import ListBox from "./ListBox.svelte";
+import type { ListLazyLoader, LoadResult, FunFilter } from "../../types";
+import type { LazyLoader } from "../tree_view";
+export default ListBox;
+export type { ListLazyLoader, LazyLoader, FunFilter, LoadResult };

package/dist/data_display/tree_view/README.md

@@ -0,0 +1,244 @@
+# TreeView
+
+A hierarchical tree component for displaying nested or flat hierarchical data (backed by `HierarchyTree`), with support for custom icons (folder open/close, file-type badges), lazy loading, selection binding, and context menus.
+
+## Features
+
+- **Icon customization**: use the `nodeIcon` snippet or the `iconField` function to render folder open (📂) / closed (📁) states and file-type icons.
+- **Hierarchical data**: powered by `HierarchyTree` (from `@ticatec/hierarchy-data`), which builds a tree from flat data via `getKey` / `getParentKey`.
+- **Expansion control**: `defaultExpandDepth` sets the initial expand depth; clicking the chevron toggles a branch.
+- **Two-way selection binding**: `bind:activeNode` reactively tracks the selected node.
+- **Async lazy loading**: `lazyLoader` fetches children on demand and shows a loading icon while the fetch is in flight.
+- **Context menu integration**: `onContextMenu` opens a `ContextMenu` on right-click.
+- **Accessibility**: the container has `role="tree"` and supports `onfocus` / `onblur`.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import TreeView from "@ticatec/uniface-element/TreeView";
+import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+```
+
+## Props
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `tree` | `HierarchyTree<any>` | required | The hierarchy tree model instance that owns the parent/child relationships and node index |
+| `textField` | `string \| GetText<any>` | required | Field name or function used to extract the display text from a node's data |
+| `iconField` | `string \| GetIcon<any>` | - | Field name, or a function of the node and its expanded state, that returns an icon (image path or CSS class) |
+| `nodeIcon` | `Snippet<[NodeIconContext]>` | - | Svelte 5 snippet for fully customizing a node's icon (e.g. folder open/closed). Takes priority over `iconField` |
+| `chevronIcon` | `Snippet<[ChevronIconContext]>` | - | Svelte 5 snippet for customizing the expand/collapse chevron; falls back to the default ▾ / ▸ glyphs |
+| `style` | `string` | `''` | Inline style for the container |
+| `class` | `string` | `''` | Additional CSS class(es) for the container |
+| `lazyLoader` | `TreeLazyLoader \| null` | `null` | Interface for loading child nodes on demand |
+| `activeNode` | `any` | `null` | The currently selected node (supports `bind:activeNode` two-way binding) |
+| `defaultExpandDepth` | `number` | `0` | Initial expand depth (0 = fully collapsed, 1 = expand root nodes, and so on) |
+| `isVisible` | `NodeVisibleFun` | - | Predicate that filters which nodes are visible |
+| `onchange` | `OnNodeSelectionChange` | - | Callback fired when the selection changes; return `false` to cancel the selection |
+| `onfocus` | `(event: FocusEvent) => void` | - | Callback fired when the tree container gains focus |
+| `onblur` | `(event: FocusEvent) => void` | - | Callback fired when the tree container loses focus |
+| `onContextMenu` | `OnContextMenu` | - | Callback fired on right-click, used to show a context menu |
+| `title` | `string` | - | Optional title shown at the top of the tree; clicking it clears the selection (`activeNode` is set to `null`) |
+
+## Types
+
+### GetText
+
+```typescript
+type GetText<T> = (item: T) => string;
+```
+
+### GetIcon
+
+```typescript
+type GetIcon<T> = (node: IHierarchyData<T>, expanded: boolean) => string | undefined;
+```
+
+### NodeIconContext / ChevronIconContext
+
+```typescript
+interface NodeIconContext {
+  node: IHierarchyData<any>;
+  expanded: boolean;
+  isBranch: boolean;
+}
+
+interface ChevronIconContext {
+  expanded: boolean;
+  loading: boolean;
+}
+```
+
+### TreeLazyLoader
+
+```typescript
+interface TreeLazyLoader {
+  /** Whether this node is an expandable branch */
+  isBranch: (node: IHierarchyData<any>) => boolean;
+  /** Load a node's children (plain data objects); the component appends them via tree.appendChild internally */
+  load: (node: IHierarchyData<any>) => Promise<Array<any>>;
+}
+```
+
+### OnNodeSelectionChange
+
+```typescript
+type OnNodeSelectionChange = (node: IHierarchyData<any>) => Promise<boolean>;
+```
+
+Return `false` to prevent the selection from taking effect; returning `true`, `undefined`, or `null` allows it.
+
+### NodeVisibleFun
+
+```typescript
+type NodeVisibleFun = (node: IHierarchyData<any>) => boolean;
+```
+
+### OnContextMenu
+
+```typescript
+type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+The callback receives the node's raw data (`node.data`), not the `IHierarchyData` node itself.
+
+---
+
+## Basic Example
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+
+  const flatData = [
+    { id: '1', parentId: null, name: 'Root 1' },
+    { id: '1-1', parentId: '1', name: 'Child 1-1' },
+  ];
+
+  const tree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  tree.setData(flatData);
+
+  let activeNode = $state<any>(null);
+</script>
+
+<TreeView
+  {tree}
+  textField="name"
+  defaultExpandDepth={1}
+  bind:activeNode
+/>
+```
+
+## Example: File Directory Tree (Folder Open/Closed + TypeScript Badge)
+
+Use the `nodeIcon` snippet to swap icons dynamically based on `{ node, expanded }`:
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+
+  const fileTreeData = [
+    { id: 'src', parentId: null, name: 'src', isDir: true },
+    { id: 'src/business', parentId: 'src', name: 'business', isDir: true },
+    { id: 'src/business/AccessLog.ts', parentId: 'src/business', name: 'AccessLog.ts', isDir: false, fileType: 'ts' },
+    { id: 'src/business/AccessLogDAO.ts', parentId: 'src/business', name: 'AccessLogDAO.ts', isDir: false, fileType: 'ts' },
+  ];
+
+  const fileTree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  fileTree.setData(fileTreeData);
+
+  let activeFile = $state<any>(null);
+</script>
+
+{#snippet customFileIcon({ node, expanded })}
+  {#if node.data.isDir}
+    <!-- Folder icon (expanded: open 📂, collapsed: closed 📁) -->
+    {#if expanded}
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="#EAB308">
+        <path d="M19 20H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v1L19 20z" opacity="0.4"/>
+        <path d="M4 10h17l-2.5 9h-15L4 10z"/>
+      </svg>
+    {:else}
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="#CA8A04">
+        <path d="M10 4H4c-1.1 0-2 .9-2 2v12c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V8c0-1.1-.9-2-2-2h-8l-2-2z"/>
+      </svg>
+    {/if}
+  {:else if node.data.fileType === 'ts'}
+    <!-- TypeScript file badge -->
+    <span style="background: #3178C6; color: #fff; font-size: 9px; font-weight: 800; padding: 1px 3px; border-radius: 3px;">
+      TS
+    </span>
+  {/if}
+{/snippet}
+
+<TreeView
+  tree={fileTree}
+  textField="name"
+  defaultExpandDepth={3}
+  nodeIcon={customFileIcon}
+  bind:activeNode={activeFile}
+/>
+```
+
+## Example: Async Lazy Loading
+
+```svelte
+<script lang="ts">
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import {HierarchyTree} from "@ticatec/uniface-element/TreeNodes";
+  import type {IHierarchyData} from "@ticatec/uniface-element/TreeNodes";
+  import type {TreeLazyLoader} from "@ticatec/uniface-element/types";
+
+  const lazyTree = new HierarchyTree<any>({
+    getKey: (item) => item.id,
+    getParentKey: (item) => item.parentId
+  });
+  lazyTree.setData([
+    { id: 'root-1', name: 'Project A (click to lazy-load)', hasChildren: true }
+  ]);
+
+  const lazyLoader: TreeLazyLoader = {
+    isBranch: (node: IHierarchyData<any>) => Boolean(node.data.hasChildren),
+    load: async (node: IHierarchyData<any>) => {
+      await new Promise((resolve) => setTimeout(resolve, 600));
+      return [
+        { id: `${node.data.id}-sub1`, parentId: node.data.id, name: `${node.data.name} - Module 1` },
+        { id: `${node.data.id}-sub2`, parentId: node.data.id, name: `${node.data.name} - Module 2` }
+      ];
+    }
+  };
+</script>
+
+<TreeView tree={lazyTree} textField="name" {lazyLoader} />
+```
+
+---
+
+## Styling
+
+The tree view supports the following CSS custom properties:
+
+- `--uniface-treeview-chevron-color`: default color of the expand/collapse chevron
+- `--uniface-treeview-chevron-hover-color`: chevron color on hover
+- `--uniface-treeview-item-bg`: row background color for hover/selected state
+- `--uniface-treeview-item-selected-color`: text color of the selected node
+
+## Accessibility
+
+- The tree container uses `role="tree"` for proper semantics.
+- The chevron and each row are clickable/keyboard-reachable interactive elements.
+- Focus state is exposed via `onfocus` and `onblur`.