@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/form/lookup_editor/README_CN.md

@@ -0,0 +1,345 @@
+# LookupEditor
+
+用于大列表或远程选项的懒加载选择器。用户在输入框中输入内容，选择器会调用 `onlookup` 回调来获取匹配的选项。回调期望返回一个包含 `{code: any, text: string}` 对象数组。选中选项后，输入框显示文本，`value` 持有对应的 code。
+
+> 可以理解为搜索驱动版的 `<select>`。适合用户查找、商品查找，或任何完整选项列表无法放入内存的场景。
+
+## 特性
+
+- **懒加载** —— 通过 `onlookup` 回调按需获取选项。
+- **输入驱动** —— 输入触发查找，选项在下拉中展示。
+- **单选** —— 点击选项选中该项。
+- **`onaction` 事件** —— 点击动作图标（↓）时触发。可用于打开自定义查找对话框。
+- **自定义字段映射** —— `codeField` / `textField` 定义查找结果如何映射到 value / display。
+- **`text` 属性** —— 输入框中显示的文本。外部设置此属性可显示标签，而不改变 `value`。
+- **`clear()` 方法** —— 编程式清空 value 和 text。
+- **禁用 / 只读** 模式 —— 下拉被抑制，渲染普通输入框。
+- **键盘导航** —— 方向键移动选中、Enter 确认、Escape 关闭、下拉打开时 Tab 被锁住。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 引入
+
+```typescript
+import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+
+  // 模拟 API 调用
+  const lookupUsers = async (keyword: string) => {
+    const allUsers = [
+      { code: "U001", text: "Alice Johnson" },
+      { code: "U002", text: "Bob Smith" },
+      { code: "U003", text: "Carol Williams" },
+      { code: "U004", text: "Dave Brown" }
+    ];
+    const keywordLower = keyword.toLowerCase();
+    return allUsers.filter(u =>
+      u.text.toLowerCase().includes(keywordLower)
+    );
+  };
+
+  function handleAction() {
+    console.log("点击了动作按钮 - 打开自定义对话框");
+  }
+</script>
+
+<LookupEditor
+  onlookup={lookupUsers}
+  onaction={handleAction}
+  bind:value={value}
+  placeholder="搜索用户..."
+/>
+```
+
+## 属性（Props）
+
+`LookupEditor` 继承自 `CommonFieldProps`，因此自动获得 `variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `any`（可绑定） | — | 选中项的 code。`bind:value={...}` 双向同步；外部修改会更新显示文本。 |
+| `text` | `string` | — | 输入框中显示的文本。外部设置时，覆盖从选中选项自动生成的文本。 |
+| `codeField` | `string` | `"code"` | 作为选项身份的字段。 |
+| `textField` | `string` | `"text"` | 显示用的字段。 |
+| `placeholder` | `string` | — | `value` 为空时输入框的占位文字。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉风格。 |
+| `compact` | `boolean` | `false` | 紧凑布局。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— 普通输入框，无下拉。 |
+| `readonly` | `boolean` | `false` | 只读 —— 视觉同 disabled，语义是"查看，不可编辑"。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本，触发编辑器的 error 状态。 |
+| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
+| `theme` | `string` | — | 渲染为下拉根的 `data-theme`，用于作用域样式覆盖。 |
+| `onlookup` | `(keyword: string) => Promise<Array<any>>` | — | **必需。** 异步函数，接收关键词并返回匹配的选项数组。必须返回 `{code, text}` 对象数组。 |
+| `onaction` | `() => void` | — | 点击动作图标（↓）时触发。可用于打开自定义查找对话框或执行其他操作。 |
+| `onchange` | `(value: any) => void` | — | 用户选中时触发**一次**，参数是**完整的选项对象**（不只是 code）。父组件编程式修改 `value` 不会触发。 |
+| `onfocus` | `(e: FocusEvent) => void` | — | 输入框获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | — | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onlookup` | `(keyword: string) => Promise<Array<any>>` | 用户输入时触发。必须获取并返回匹配的选项。 |
+| `onaction` | `() => void` | 点击动作图标（↓）时触发。 |
+| `onchange` | `(value: any) => void` | 用户选中时触发，参数是**完整的选项对象**。 |
+| `onfocus` | `(e: FocusEvent) => void` | 输入框获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
+
+## 方法
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `focus()` | `() => void` | 让输入框获取焦点。 |
+| `clear()` | `() => void` | 编程式清空 value 和 text。重置为空状态。 |
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let editor;
+
+  const lookupUsers = async (keyword: string) => {
+    // ... 获取逻辑
+  };
+
+  function handleClear() {
+    editor.clear();
+  }
+</script>
+
+<LookupEditor bind:this={editor} {lookupUsers} bind:value placeholder="搜索用户..." />
+<button onclick={handleClear}>清空</button>
+```
+
+## `onlookup` — 懒加载
+
+`onlookup` 回调是这个组件的核心。它接收当前的输入值作为 `keyword`，必须返回一个 promise，解析为包含 `{code, text}` 对象的数组。
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+
+  // 真实 API 调用
+  const lookupProducts = async (keyword: string) => {
+    const response = await fetch(`/api/products/search?q=${encodeURIComponent(keyword)}`);
+    const data = await response.json();
+    return data.map((product: any) => ({
+      code: product.id,
+      text: `${product.name} - ${product.sku}`
+    }));
+  };
+</script>
+
+<LookupEditor
+  onlookup={lookupProducts}
+  bind:value={value}
+  placeholder="搜索商品..."
+/>
+```
+
+## 示例
+
+### 带自定义动作的员工查找
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+  let isDialogOpen = $state(false);
+
+  // 模拟 API
+  const lookupEmployees = async (keyword: string) => {
+    const allEmployees = [
+      { code: "E001", text: "Alice Johnson (工程部)" },
+      { code: "E002", text: "Bob Smith (市场部)" },
+      { code: "E003", text: "Carol Williams (工程部)" },
+      { code: "E004", text: "Dave Brown (销售部)" }
+    ];
+    const keywordLower = keyword.toLowerCase();
+    return allEmployees.filter(e =>
+      e.text.toLowerCase().includes(keywordLower)
+    );
+  };
+
+  function handleAction() {
+    isDialogOpen = true;
+  }
+
+  function closeDialog() {
+    isDialogOpen = false;
+  }
+</script>
+
+<LookupEditor
+  onlookup={lookupEmployees}
+  onaction={handleAction}
+  bind:value={value}
+  placeholder="搜索员工..."
+/>
+
+{#if isDialogOpen}
+  <div class="modal-overlay" onclick={closeDialog}>
+    <div class="modal" onclick={(e: Event) => e.stopPropagation()}>
+      <h3>添加新员工</h3>
+      <form>
+        <input type="text" placeholder="姓名" />
+        <input type="text" placeholder="邮箱" />
+        <button type="button" onclick={closeDialog}>关闭</button>
+      </form>
+    </div>
+  </div>
+{/if}
+
+<style>
+  .modal-overlay {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.5);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .modal {
+    background: white;
+    padding: 24px;
+    border-radius: 8px;
+    max-width: 400px;
+  }
+  form {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+  button {
+    padding: 8px 16px;
+    background: #3b82f6;
+    color: white;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+  }
+</style>
+```
+
+### 带动作的商品查找
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+
+  const lookupProducts = async (keyword: string) => {
+    // 模拟 API，带延迟
+    await new Promise(resolve => setTimeout(resolve, 500));
+    const allProducts = [
+      { id: "P001", name: "Laptop", sku: "LAP-001" },
+      { id: "P002", name: "Smartphone", sku: "PHN-001" },
+      { id: "P003", name: "Tablet", sku: "TBL-001" },
+      { id: "P004", name: "Monitor", sku: "MON-001" }
+    ];
+    const keywordLower = keyword.toLowerCase();
+    return allProducts
+      .filter(p =>
+        p.name.toLowerCase().includes(keywordLower) ||
+        p.sku.toLowerCase().includes(keywordLower)
+      )
+      .map(p => ({
+        code: p.id,
+        text: `${p.name} - ${p.sku}`
+      }));
+  };
+
+  function handleAction() {
+    console.log("点击了动作按钮 - 打开商品目录");
+  }
+</script>
+
+<LookupEditor
+  onlookup={lookupProducts}
+  onaction={handleAction}
+  bind:value={value}
+  placeholder="搜索商品..."
+/>
+```
+
+### 禁用 / 只读模式
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let disabledValue = $state("E001");
+  let readonlyValue = $state("E002");
+
+  const lookupEmployees = async (keyword: string) => {
+    return [
+      { code: "E001", text: "Alice" },
+      { code: "E002", text: "Bob" },
+      { code: "E003", text: "Carol" }
+    ];
+  };
+</script>
+
+<div style="display: flex; gap: 16px;">
+  <LookupEditor
+    onlookup={lookupEmployees}
+    bind:value={disabledValue}
+    disabled
+    text="Alice (禁用)"
+  />
+  <LookupEditor
+    onlookup={lookupEmployees}
+    bind:value={readonlyValue}
+    readonly
+    text="Bob (只读)"
+  />
+</div>
+```
+
+## 行为说明
+
+### `value` 与 `text` 如何交互
+
+| 动作 | 结果 |
+|------|------|
+| 用户选中选项 | `value` 设为选项的 code；`text` 从选项的 text 字段自动生成。 |
+| 父组件外部设置 `value` | 输入框显示匹配选项的文本（如果有的话），否则回退到原始 code。 |
+| 父组件外部设置 `text` | 输入框显示自定义文本，忽略 `value`。 |
+| 父组件同时设置两者 | 输入框显示 `text`（如果设置了）；`value` 决定内部状态。 |
+
+### `clear()` 方法
+
+调用 `clear()` 会将 `value` 和 `text` 都重置为空。适用于重置按钮或表单清空。
+
+### 只读 / 禁用渲染
+
+两种模式都渲染普通 `<input readonly>`，显示文本。清空按钮、下拉箭头、下拉面板都不渲染。
+
+## 无障碍
+
+- 下拉通过 `Popover`（portal 渲染到 `document.body`）实现，有 scroll/resize 监听。
+- 键盘：方向键移动选中，Enter 确认，Escape 关闭，下拉打开时 Tab 被锁。
+- 完整的 ARIA 需要外层 `<label>` / `FormField` 配合 `error` 文本。
+
+## 相关组件
+
+- [OptionsSelect](../options_select/README_CN.md) —— 静态下拉变体。
+- [InputOptionsSelect](../input_options_select/README_CN.md) —— 客户端过滤变体。
+- [CascadeOptionSelect](../cascade_options_select/README_CN.md) —— 树形级联选择器。

package/dist/form/memo_editor/MemoEditor.svelte

@@ -0,0 +1,171 @@
+<script lang="ts">
+    import FormEditor from "../FormEditor.svelte";
+    import Icon from "../../general/icon";
+    import prefixFilter, {eventFilter} from "../../utils/prefixFilter";
+
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+    import type {KeyboardEvents} from "../common_editor/EditorEvents";
+
+    const excludeAttrs = ['readonly', 'disabled', 'required', 'rows', 'form', 'wrap'];
+
+    interface Props extends CommonFieldProps, KeyboardEvents {
+        class?: string;
+        value?: any;
+        wrap?: "hard" | "soft";
+        resize?: 'none' | 'horizontal' | 'vertical' | 'both';
+        showIndicator?: boolean;
+        maxLength?: number;
+        rows?: number;
+        autoHeight?: boolean;
+
+        [key: `input\$${string}`]: any;
+    }
+
+    let {
+        disabled = false,
+        readonly = false,
+        compact = false,
+        variant,
+        theme,
+        class: className = '',
+        style = '',
+        tooltip,
+        error,
+        value = $bindable(),
+        wrap = 'hard',
+        resize = 'none',
+        showIndicator = false,
+        maxLength,
+        rows = 3,
+        autoHeight = false,
+        onblur,
+        ...restProps
+    }: Props = $props();
+
+    let editor: HTMLTextAreaElement | undefined = $state(undefined);
+
+    let input$ = $derived(prefixFilter(restProps, "input$", excludeAttrs));
+    let events = $derived(eventFilter(restProps));
+    let len = $derived(value?.length ?? 0);
+
+    export function focus() {
+        editor?.focus();
+    }
+
+    const clean = () => {
+        value = '';
+        editor?.focus();
+    };
+
+    let heightStyle = $derived(autoHeight ? 'height: 100%' : 'height: auto');
+
+    // 当允许横向 resize 时，textarea 不能用 width:100%，否则拖拽会溢出容器
+    let allowHorizontal = $derived(resize === 'horizontal' || resize === 'both');
+    let textareaStyle = $derived.by(() => {
+        const widthCss = allowHorizontal ? 'min-width: 100%; width: auto' : 'width: 100%';
+        return `${widthCss}; ${heightStyle}; resize: ${resize}`;
+    });
+
+</script>
+
+<FormEditor {variant} {theme} {error} {tooltip} style="{style}; {heightStyle}" {readonly} {disabled} {compact} className={allowHorizontal ? 'memo-resize-horizontal' : ''}>
+    <div class="memo-inner" style={heightStyle} class:resize-horizontal={allowHorizontal}>
+        <textarea
+                bind:this={editor}
+                style={textareaStyle}
+                class="uniface-memo-editor"
+                {readonly}
+                {disabled}
+                rows={autoHeight ? undefined : rows}
+                {wrap}
+                {maxLength}
+                bind:value
+                {...events}
+                {...input$}
+        ></textarea>
+
+        {#if showIndicator && maxLength && !readonly && !disabled}
+            <div class="uniface-memo-indicator">
+                <span>{len} / {maxLength}</span>
+            </div>
+        {/if}
+
+        {#if !readonly && !disabled && value?.length > 0}
+            <div class="clean-icon" style="position: absolute; top: 2px; right: 2px; z-index: 100">
+                <i class="icon_google_clear" role="none" onmousedown={(event: MouseEvent)=>{event.preventDefault()}}  onclick={clean}></i>
+            </div>
+        {/if}
+    </div>
+</FormEditor>
+
+<style>
+    .memo-inner {
+        position: relative;
+        width: 100%;
+        display: flex;
+        flex-direction: column;
+    }
+
+    /* 横向 resize 时容器跟随 textarea 扩展 */
+    .memo-inner.resize-horizontal {
+        width: auto;
+        min-width: 100%;
+    }
+
+    /* FormEditor 外壳也跟随扩展 */
+    :global(.uniface-form-editor.memo-resize-horizontal) {
+        width: auto;
+        min-width: 100%;
+    }
+
+    .memo-inner .clean-icon {
+        display: none;
+    }
+
+    .memo-inner:focus-within .clean-icon {
+        display: block;
+    }
+
+    .clean-icon:hover {
+        cursor: pointer;
+    }
+
+    .clean-icon:active  {
+        top: 3px;
+    }
+
+    .uniface-memo-editor {
+        background-color: transparent;
+        border: 0 solid transparent;
+        box-sizing: border-box;
+        font-size: 1em;
+        line-height: 1.5em;
+        color: var(--uniface-editor-text-color, #374151);
+        padding: var(--uniface-memo-padding, 6px 8px);
+    }
+
+
+    .uniface-memo-editor:focus {
+        outline: none;
+    }
+
+    .uniface-memo-editor:disabled {
+        color: var(--uniface-editor-outlined-disabled-text-color, #B3BCCA);
+        background-color: var(--uniface-editor-outlined-disabled-backgournd-color, #F1F5F9);
+    }
+
+    .uniface-memo-indicator {
+        position: absolute;
+        bottom: 0;
+        right: 0;
+        padding: 4px 6px;
+        box-sizing: border-box;
+        text-align: right;
+        font-size: 0.9em;
+        color: var(--uniface-editor-indicator-color, #B3BCCA);
+        user-select: none;
+        pointer-events: none;
+        z-index: 10;
+    }
+
+</style>

package/dist/form/memo_editor/MemoEditor.svelte.d.ts

@@ -0,0 +1,18 @@
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+import type { KeyboardEvents } from "../common_editor/EditorEvents";
+interface Props extends CommonFieldProps, KeyboardEvents {
+    class?: string;
+    value?: any;
+    wrap?: "hard" | "soft";
+    resize?: 'none' | 'horizontal' | 'vertical' | 'both';
+    showIndicator?: boolean;
+    maxLength?: number;
+    rows?: number;
+    autoHeight?: boolean;
+    [key: `input\$${string}`]: any;
+}
+declare const MemoEditor: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type MemoEditor = ReturnType<typeof MemoEditor>;
+export default MemoEditor;