@ticatec/uniface-element 0.3.23 → 5.0.0

package/dist/form/cascade_options_select/CascadeOptionSelect.svelte

@@ -0,0 +1,161 @@
+<script lang="ts">
+    import {tick} from "svelte";
+    import iconLoading from "../../assets/loading.gif";
+    import OptionsBox from "./OptionsBox.svelte";
+    import {CommonPicker} from "../common_editor";
+    import type CommonPickerProps from "../common_editor/CommonPickerProps";
+    import type {IsLeafDetermine} from "./isLeafDetermine";
+
+    import type {KeyboardEvents} from "../common_editor/EditorEvents";
+
+    type OnSelectOption = (item: any) => Promise<Array<any>>;
+
+    interface Props extends CommonPickerProps, KeyboardEvents {
+        value: any;
+        nodes?: Array<any>;
+        keyField?: string;
+        textField?: string;
+        abbrField?: string;
+        childrenField?: string;
+        emptyText?: string;
+        checkLeaf?: IsLeafDetermine | null;
+        menu$height?: number;
+        box$style?: string;
+        onSelect?: OnSelectOption;
+    }
+
+    let {
+        variant,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        mandatory = false,
+        error,
+        tooltip,
+        theme,
+        style,
+        placeholder,
+        value = $bindable(),
+        nodes = $bindable([]),
+        keyField = "code",
+        textField = "text",
+        abbrField = "abbr",
+        childrenField = "children",
+        emptyText,
+        checkLeaf = null,
+        menu$height = 150,
+        box$style = "",
+        onSelect,
+        onchange,
+        onfocus,
+        onblur,
+    }: Props = $props();
+
+    let isOpen = $state(false);
+    let busy = $state(false);
+    let selectedItems = $state<Array<any>>([]);
+    let list = $state<Array<Array<any>>>([nodes ?? []]);
+    let contentPanel: HTMLDivElement | undefined = $state(undefined);
+
+    let picker: CommonPicker;
+
+    export const focus = () => {
+        setTimeout(() => {
+            picker?.focus();
+        }, 50);
+    };
+
+    const mh = $derived(` width: 400px; height: ${menu$height}px`);
+    const textValue = $derived(
+        selectedItems.length > 0
+            ? selectedItems[selectedItems.length - 1][textField]
+            : (emptyText ?? "")
+    );
+
+    // Re-seed the cascade from the top whenever the incoming top-level nodes change.
+    $effect(() => {
+        if (nodes && nodes.length > 0) {
+            list = [nodes];
+        }
+    });
+
+    const selectOption = (level: number) => async (item: any) => {
+        value = item?.[keyField];
+        const newList = list.slice(0, level + 1);
+        selectedItems = level === 0 ? [item] : [...selectedItems.slice(0, level), item];
+
+        const isLeaf = checkLeaf == null ? false : checkLeaf(item);
+        if (!isLeaf) {
+            if (item[childrenField] == null && onSelect != null) {
+                busy = true;
+                const children = (await onSelect(item)) ?? [];
+                busy = false;
+                item[childrenField] = children;
+                if (children.length > 0) {
+                    list = [...newList, children];
+                    await tick();
+                    if (contentPanel) contentPanel.scrollLeft = contentPanel.scrollWidth;
+                } else {
+                    isOpen = false;
+                    picker?.focus();
+                }
+            } else if (item[childrenField] && item[childrenField].length > 0) {
+                list = [...newList, item[childrenField]];
+                await tick();
+                if (contentPanel) contentPanel.scrollLeft = contentPanel.scrollWidth;
+            } else {
+                isOpen = false;
+                picker?.focus();
+            }
+        } else {
+            isOpen = false;
+            picker?.focus();
+        }
+        onchange?.(value);
+    };
+
+    const cleanData = () => {
+        value = null;
+        selectedItems = [];
+        list = [nodes ?? []];
+        onchange?.(null);
+    };
+</script>
+
+<CommonPicker
+    bind:this={picker}
+    {error} {tooltip} {variant} {style} {compact}
+    {textValue} {readonly} {placeholder} {disabled}
+    bind:isOpen
+    {theme} {value} {mandatory}
+    clear={cleanData}
+    {onfocus} {onblur}>
+    {#snippet popupLayer()}
+        <div class="cascade-options-popover" style={mh}>
+            <div style="height: 100%; position: relative">
+                <div
+                    bind:this={contentPanel}
+                    style="width: 100%; height: 100%; display: flex; flex-direction: row; overflow: auto">
+                    {#each list as node, idx (idx)}
+                        <OptionsBox
+                            options={node}
+                            {keyField}
+                            textField={abbrField}
+                            {box$style}
+                            onSelect={selectOption(idx)}
+                            selectedItem={selectedItems[idx]}/>
+                    {/each}
+                </div>
+                {#if busy}
+                    <div style="position: absolute; top: 0; bottom: 0; left: 0; right: 0; background-color: #e1e1e110;">
+                        <div style="position: relative; width: 100%; height: 100%; display: flex; flex-direction: column; justify-content: center">
+                            <div style="width: 100px; margin: 0 auto; text-align: center; background-color: #f0f0f0; border-radius: 4px; padding: 8px 12px; box-sizing: border-box;">
+                                <img src={iconLoading} alt="" width="32" height="32"/>
+                            </div>
+                        </div>
+                    </div>
+                {/if}
+            </div>
+        </div>
+    {/snippet}
+</CommonPicker>

package/dist/form/cascade_options_select/CascadeOptionSelect.svelte.d.ts

@@ -0,0 +1,22 @@
+import type CommonPickerProps from "../common_editor/CommonPickerProps";
+import type { IsLeafDetermine } from "./isLeafDetermine";
+import type { KeyboardEvents } from "../common_editor/EditorEvents";
+type OnSelectOption = (item: any) => Promise<Array<any>>;
+interface Props extends CommonPickerProps, KeyboardEvents {
+    value: any;
+    nodes?: Array<any>;
+    keyField?: string;
+    textField?: string;
+    abbrField?: string;
+    childrenField?: string;
+    emptyText?: string;
+    checkLeaf?: IsLeafDetermine | null;
+    menu$height?: number;
+    box$style?: string;
+    onSelect?: OnSelectOption;
+}
+declare const CascadeOptionSelect: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value" | "nodes">;
+type CascadeOptionSelect = ReturnType<typeof CascadeOptionSelect>;
+export default CascadeOptionSelect;

package/dist/form/cascade_options_select/CascadePanel.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+    import iconLoading from "../assets/loading.gif";
+    import OptionsBox from "./OptionsBox.svelte";
+    import type {OnSelectHandler} from "../../types";
+
+
+    export let nodes: Array<Array<any>>;
+    export let keyField: string;
+    export let textField: string;
+    export let box$style: string;
+    export let onSelect: OnSelectHandler<any>;
+
+    export let selectedItems:Array<any> = [];
+    let busy: boolean = false;
+
+    const selectOption = (level: number) => (item: any) => {
+        if (level == 0) {
+            selectedItems = [item];
+            nodes = [nodes[0]];
+        } else if (level == selectedItems.length - 1) {
+            selectedItems.pop();
+            selectedItems = [...selectedItems, item];
+        } else if (level < selectedItems.length) {
+            selectedItems.splice(level);
+            nodes.splice(level+1);
+            selectedItems = [...selectedItems, item];
+        } else if (level == selectedItems.length) {
+            selectedItems = [...selectedItems, item];
+        }
+        onSelect?.(item);
+    }
+
+
+</script>
+<div style="width: 100%; height: 100%; position: relative">
+    <div style="width: 100%; height: 100%; display: flex; flex-direction: row; overflow: auto">
+        {#each nodes as node, idx}
+            <OptionsBox options={node} {keyField} {textField} {box$style} onSelect={selectOption(idx)}
+                        selectedItem={selectedItems[idx]}/>
+        {/each}
+    </div>
+    {#if busy}
+    <div style="position: absolute; top: 0; bottom: 0; left: 0; right: 0; background-color: #e1e1e110;">
+        <div style="position: relative; width: 100%; height: 100%; display: flex; flex-direction: column; justify-content: center">
+            <div style="width: 100px; margin: 0 auto; text-align: center; background-color: #f0f0f0; border-radius: 4px; padding: 8px 12px; box-sizing: border-box;">
+                <img src={iconLoading} alt="loading" width="32" height="32"/>
+            </div>
+        </div>
+    </div>
+    {/if}
+
+</div>

package/dist/form/cascade_options_select/CascadePanel.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { OnSelectHandler } from "../../types";
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const CascadePanel: $$__sveltets_2_IsomorphicComponent<{
+    nodes: Array<Array<any>>;
+    keyField: string;
+    textField: string;
+    box$style: string;
+    onSelect: OnSelectHandler<any>;
+    selectedItems?: Array<any>;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type CascadePanel = InstanceType<typeof CascadePanel>;
+export default CascadePanel;

package/dist/form/cascade_options_select/OptionsBox.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+    import type { OnSelectHandler } from "../../types";
+
+    interface Props {
+        options: Array<any>;
+        onSelect: OnSelectHandler<any>;
+        selectedItem: any;
+        keyField: string;
+        textField: string;
+        box$style: string;
+    }
+
+    let {
+        options,
+        onSelect,
+        selectedItem,
+        keyField,
+        textField,
+        box$style
+    }: Props = $props();
+
+    const handleItemClick = (item: any) => (e: MouseEvent) => {
+        selectedItem = item;
+        onSelect(item);
+    }
+</script>
+
+<div class="cascade-column" style={box$style}>
+    {#each options as op (op[keyField])}
+        <div class="option-item" class:selected={op[keyField] === (selectedItem ?? {})[keyField]}
+             aria-hidden="true" onclick={handleItemClick(op)}>
+            <span>{op[textField]}</span>
+        </div>
+    {/each}
+</div>

package/dist/form/cascade_options_select/OptionsBox.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { OnSelectHandler } from "../../types";
+interface Props {
+    options: Array<any>;
+    onSelect: OnSelectHandler<any>;
+    selectedItem: any;
+    keyField: string;
+    textField: string;
+    box$style: string;
+}
+declare const OptionsBox: import("svelte").Component<Props, {}, "">;
+type OptionsBox = ReturnType<typeof OptionsBox>;
+export default OptionsBox;

package/dist/form/cascade_options_select/README.md

@@ -0,0 +1,188 @@
+# CascadeOptionSelect
+
+A cascading (hierarchical) multi-select picker where child options only appear once a parent option is selected. Renders as a dropdown list of checkboxes with indented child rows — the visual language matches a tree view without requiring you to build one from scratch.
+
+## Features
+
+- **Cascading tree structure** — child options auto-load when parent is checked; collapse/expand via click.
+- **Multi-select with checkboxes** — each option gets a real `<input type="checkbox">`.
+- **Auto-select children** — when a parent is checked, all its children are checked too (and vice versa).
+- **Custom field mapping** — `keyField` / `textField` / `childrenField` define how your tree-shaped data maps to the picker.
+- **`onchange` returns a flat array** of selected keys regardless of tree depth.
+- **Compact mode** for dense UIs.
+- **Disabled / readonly** modes — dropdown suppressed, tree rendered as plain text.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "electronics",
+      text: "Electronics",
+      children: [
+        { id: "phones", text: "Phones" },
+        { id: "laptops", text: "Laptops" }
+      ]
+    },
+    {
+      id: "clothing",
+      text: "Clothing",
+      children: [
+        { id: "shirts", text: "Shirts" },
+        { id: "pants", text: "Pants" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="Select categories" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` (bindable) | `""` | Selected keys joined by delimiter (default `;`). |
+| `options` | `Array<any>` | — | Full tree data structure. |
+| `keyField` | `string` | `"id"` | Property used as the option's identity. |
+| `textField` | `string` | `"text"` | Property used as the option's display text. |
+| `childrenField` | `string` | `"children"` | Property name where child options live. |
+| `delimiter` | `string` | `";"` | Separator for joining keys in `value`. |
+| `placeholder` | `string` | — | Shown when nothing is selected. |
+| `emptyText` | `string` | — | Shown when nothing is selected, in place of the placeholder. |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Editor variant. |
+| `compact` | `boolean` | `false` | Compact layout for dense UIs. |
+| `disabled` | `boolean` | `false` | Fully disabled — dropdown suppressed. |
+| `readonly` | `boolean` | `false` | Read-only — tree rendered as plain text. |
+| `style` | `string` | — | Inline CSS on the editor root. |
+| `error` | `string` | — | Validation error text. |
+| `tooltip` | `string` | — | Hover tooltip on the editor. |
+| `theme` | `string` | — | Rendered as `data-theme` on the popover. |
+| `menu$height` | `number` | `0` | Fixed dropdown height in px. `0` means `auto`. |
+| `onchange` | `(keys: string[]) => void` | — | Fires when selection changes. Always receives the array of selected keys. |
+| `onfocus` | `(e: FocusEvent) => void` | — | Editor focus. |
+| `onblur` | `(e: FocusEvent) => void` | — | Editor blur, after the popup has closed and focus truly left. |
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `onchange` | `(keys: string[]) => void` | Fires when selection changes. Always receives the array of selected keys. |
+| `onfocus` | `(e: FocusEvent) => void` | Editor focus. |
+| `onblur` | `(e: FocusEvent) => void` | Editor blur, after the popup has closed and focus truly left. |
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `focus()` | `() => void` | Moves focus to the editor. Internally deferred 50 ms. |
+
+## Examples
+
+### Custom field mapping
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+
+  let value = $state("");
+
+  // Data shaped differently from the default
+  const options = [
+    {
+      category: "Food",
+      items: [
+        { id: "fruits", label: "Fruits" },
+        { id: "vegetables", label: "Vegetables" }
+      ]
+    },
+    {
+      category: "Drinks",
+      items: [
+        { id: "coffee", label: "Coffee" },
+        { id: "tea", label: "Tea" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect
+  {options}
+  keyField="category"
+  textField="category"
+  childrenField="items"
+  bind:value
+  placeholder="Select categories"
+/>
+```
+
+### Deeply nested tree
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "east",
+      text: "East Asia",
+      children: [
+        {
+          id: "cn",
+          text: "China",
+          children: [
+            { id: "beijing", text: "Beijing" },
+            { id: "shanghai", text: "Shanghai" }
+          ]
+        },
+        {
+          id: "jp",
+          text: "Japan",
+          children: [
+            { id: "tokyo", text: "Tokyo" },
+            { id: "osaka", text: "Osaka" }
+          ]
+        }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="Select cities" />
+```
+
+### With delimiter
+
+```svelte
+<CascadeOptionSelect
+  {options}
+  bind:value
+  delimiter=","
+  placeholder="Use commas"
+/>
+```
+
+## Related Components
+
+- [OptionsSelect](../options_select/README.md) — single-select variant.
+- [OptionsMultiSelect](../options_multi_select/README.md) — flat multi-select variant.
+- [LookupEditor](../lookup_editor/README.md) — lazy-loading picker for large / remote option lists.

package/dist/form/cascade_options_select/README_CN.md

@@ -0,0 +1,188 @@
+# CascadeOptionSelect
+
+树形级联多选选择器。子选项在父选项被选中时才显示。以下拉树形复选框列表的形式渲染 —— 不需要你从零搭建树形视图。
+
+## 特性
+
+- **级联树结构** —— 勾选父选项时自动加载并展示子选项；点击可展开/折叠。
+- **多选 + 复选框** —— 每个选项都有一个真实的 `<input type="checkbox">`。
+- **父子联动** —— 勾选父选项时，所有子选项也自动勾选（反之亦然）。
+- **自定义字段映射** —— `keyField` / `textField` / `childrenField` 定义树形数据如何映射到选择器。
+- **`onchange` 返回扁平数组** —— 不管树深度如何，回调始终是选中的 keys 数组。
+- **紧凑模式** —— 适用于密集 UI。
+- **禁用 / 只读** —— 下拉被抑制，树以纯文本形式渲染。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 引入
+
+```typescript
+import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "electronics",
+      text: "Electronics",
+      children: [
+        { id: "phones", text: "Phones" },
+        { id: "laptops", text: "Laptops" }
+      ]
+    },
+    {
+      id: "clothing",
+      text: "Clothing",
+      children: [
+        { id: "shirts", text: "Shirts" },
+        { id: "pants", text: "Pants" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="选择分类" />
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string`（可绑定） | `""` | 选中的 keys 用分隔符（默认 `;`）拼接。 |
+| `options` | `Array<any>` | — | 完整的树形数据。 |
+| `keyField` | `string` | `"id"` | 作为选项身份的字段。 |
+| `textField` | `string` | `"text"` | 显示用的字段。 |
+| `childrenField` | `string` | `"children"` | 子选项所在的字段名。 |
+| `delimiter` | `string` | `";"` | `value` 拼接用的分隔符。 |
+| `placeholder` | `string` | — | 没有选中时显示的文字。 |
+| `emptyText` | `string` | — | 没有选中时**替换** placeholder 显示的文字。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 编辑器风格。 |
+| `compact` | `boolean` | `false` | 紧凑布局。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— 下拉被抑制。 |
+| `readonly` | `boolean` | `false` | 只读 —— 树以纯文本形式渲染。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本。 |
+| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
+| `theme` | `string` | — | 渲染为弹窗根的 `data-theme`。 |
+| `menu$height` | `number` | `0` | 下拉的固定高度（px）。`0` 表示 `auto`。 |
+| `onchange` | `(keys: string[]) => void` | — | 选中状态变化时触发。**始终传入 keys 数组**。 |
+| `onfocus` | `(e: FocusEvent) => void` | — | 编辑器获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | — | 编辑器失焦，在弹窗关闭且焦点真正离开之后触发。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onchange` | `(keys: string[]) => void` | 选中状态变化时触发。**始终传入 keys 数组**。 |
+| `onfocus` | `(e: FocusEvent) => void` | 编辑器获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | 编辑器失焦，在弹窗关闭且焦点真正离开之后触发。 |
+
+## 方法
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `focus()` | `() => void` | 让编辑器获得焦点。内部延迟 50 ms。 |
+
+## 示例
+
+### 自定义字段映射
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+
+  let value = $state("");
+
+  // 数据形状不同于默认
+  const options = [
+    {
+      category: "Food",
+      items: [
+        { id: "fruits", label: "Fruits" },
+        { id: "vegetables", label: "Vegetables" }
+      ]
+    },
+    {
+      category: "Drinks",
+      items: [
+        { id: "coffee", label: "Coffee" },
+        { id: "tea", label: "Tea" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect
+  {options}
+  keyField="category"
+  textField="category"
+  childrenField="items"
+  bind:value
+  placeholder="选择分类"
+/>
+```
+
+### 深层嵌套的树
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/uniface-element/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "east",
+      text: "East Asia",
+      children: [
+        {
+          id: "cn",
+          text: "China",
+          children: [
+            { id: "beijing", text: "Beijing" },
+            { id: "shanghai", text: "Shanghai" }
+          ]
+        },
+        {
+          id: "jp",
+          text: "Japan",
+          children: [
+            { id: "tokyo", text: "Tokyo" },
+            { id: "osaka", text: "Osaka" }
+          ]
+        }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="选择城市" />
+```
+
+### 自定义分隔符
+
+```svelte
+<CascadeOptionSelect
+  {options}
+  bind:value
+  delimiter=","
+  placeholder="用逗号分隔"
+/>
+```
+
+## 相关组件
+
+- [OptionsSelect](../options_select/README_CN.md) —— 单选变体。
+- [OptionsMultiSelect](../options_multi_select/README_CN.md) —— 平面多选变体。
+- [LookupEditor](../lookup_editor/README_CN.md) —— 大列表 / 远程数据的懒加载选择器。