@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/form/input_options_select/README_CN.md

@@ -0,0 +1,246 @@
+# InputOptionsSelect
+
+带可展开选项列表的文本输入组件。与纯 `OptionsSelect` 下拉框不同，这个组件从普通文本输入开始 —— 输入内容时会实时过滤选项，匹配的选项在下方面板中展开。适合用户经常输入部分值而非浏览的场景。
+
+> 可以理解为 `<input>` 和 `<select>` 之间的桥梁。输入过滤，点击选中。
+
+## 特性
+
+- **文本输入 + 下拉** —— 输入时实时过滤选项；下拉面板显示匹配的选项。
+- **单选** —— 点击选项选中该项并关闭下拉。
+- **`value` 是选项的 key** —— 绑定到你指定的 `keyField`。
+- **自定义字段映射** —— `keyField` / `textField` 定义选项对象的映射方式。
+- **自定义选项文本检索** —— 传 `retrieveOptionText` 可格式化或转换下拉中显示的文本。
+- **隐藏 / 禁用单个选项** —— `hideOptions` / `disableOptions`。
+- **快速过滤** —— `filterFunction` 控制过滤逻辑。
+- **必填模式** —— 隐藏清空按钮，用户无法把字段清空。
+- **紧凑模式** —— 适用于表格单元格和密集表单。
+- **禁用 / 只读** —— 下拉被抑制，渲染普通输入框。
+- **共享的 form-editor 属性** —— `variant`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`。
+- **键盘导航** —— 方向键移动选中、Enter 确认、Escape 关闭、下拉打开时 Tab 被锁住。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 引入
+
+```typescript
+import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+
+  let value = $state<string | null>(null);
+
+  const options = [
+    { code: "JS", text: "JavaScript" },
+    { code: "TS", text: "TypeScript" },
+    { code: "PY", text: "Python" },
+    { code: "GO", text: "Go" }
+  ];
+</script>
+
+<InputOptionsSelect {options} bind:value placeholder="输入搜索..." />
+```
+
+## 属性（Props）
+
+`InputOptionsSelect` 继承自 `CommonFieldProps`，因此自动获得 `variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `any`（可绑定） | — | 选中项的 key。`bind:value={...}` 双向同步；外部修改会更新显示文本。 |
+| `options` | `Array<any>` | — | 完整的选项对象数组。 |
+| `keyField` | `string` | `"code"` | 作为选项身份的字段。 |
+| `textField` | `string` | `"text"` | 显示用的字段。 |
+| `placeholder` | `string` | — | `value` 为空时输入框的占位文字。 |
+| `emptyText` | `string` | — | 当 `value` 找不到对应选项时显示的文本。 |
+| `disableOptions` | `Array<string>` | `[]` | 要渲染但禁用（变灰）的选项 key。 |
+| `hideOptions` | `Array<string>` | `[]` | 完全不渲染的选项 key。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉风格。 |
+| `compact` | `boolean` | `false` | 紧凑布局。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— 普通输入框，无下拉。 |
+| `readonly` | `boolean` | `false` | 只读 —— 视觉同 disabled，语义是"查看，不可编辑"。 |
+| `mandatory` | `boolean` | `false` | 隐藏清空（×）按钮。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本，触发编辑器的 error 状态。 |
+| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
+| `theme` | `string` | — | 渲染为下拉根的 `data-theme`，用于作用域样式覆盖。 |
+| `itemRender` | `{ component: any; props?: Record<string, any> } \| undefined` | — | 自定义每项渲染的 Svelte 组件。子组件接收 `item`、`disabled`、`onclick`。 |
+| `filterFunction` | `((option: any, keyword: string) => boolean) \| undefined` | — | 过滤函数。传入后，输入时会按每个选项调用。 |
+| `noResultsText` | `string` | `"No results found"` | 过滤后列表为空时显示的文本。 |
+| `retrieveOptionText` | `(option: any) => string \| null \| undefined` | — | 可选的文本转换函数。接收选项对象，返回要显示的文本。返回 `undefined` 时使用 `textField` 的原始值。 |
+| `onchange` | `(value: any) => void` | — | 用户选中时触发**一次**，参数是**完整的选项对象**（不是 key）。父组件编程式修改 `value` 不会触发。 |
+| `onfocus` | `(e: FocusEvent) => void` | — | 输入框获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | — | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onchange` | `(value: any) => void` | 用户选中时触发，参数是**完整的选项对象**（不是 key）。 |
+| `onfocus` | `(e: FocusEvent) => void` | 输入框获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
+
+## `retrieveOptionText`
+
+这个钩子可以格式化或转换输入框和下拉中显示的文本。它接收完整的选项对象，返回显示字符串。
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+
+  let value = $state<string | null>(null);
+
+  const options = [
+    { code: 1001, text: "张三",   age: 30, department: "工程部" },
+    { code: 1002, text: "李四",   age: 25, department: "市场部" },
+    { code: 1003, text: "王五",   age: 35, department: "工程部" }
+  ];
+
+  // 下拉中显示 "张三 (工程部)"
+  const retrieveOptionText = (option: any) => {
+    return `${option.text} (${option.department})`;
+  };
+</script>
+
+<InputOptionsSelect
+  {options}
+  bind:value
+  retrieveOptionText={retrieveOptionText}
+  placeholder="搜索员工..."
+/>
+```
+
+## `itemRender`
+
+传 `{component, props?}`。子组件接收：
+
+| 属性 | 来源 |
+|------|------|
+| `item` | 当前选项对象。 |
+| `disabled` | 选项 key 在 `disableOptions` 中时为 `true`。 |
+| `onclick` | 内部处理函数 —— 点击时调用它来选中这一项。 |
+| `...props` | 你放在 `itemRender.props` 里的属性都会展开到组件上。 |
+
+## 示例
+
+### 员工搜索，自定义下拉文本格式
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+
+  let value = $state<string | null>(null);
+
+  const employees = [
+    { id: "E001", name: "Alice", dept: "Engineering", email: "alice@example.com" },
+    { id: "E002", name: "Bob",   dept: "Marketing",  email: "bob@example.com" },
+    { id: "E003", name: "Carol", dept: "Engineering", email: "carol@example.com" },
+    { id: "E004", name: "Dave",  dept: "Sales",      email: "dave@example.com" }
+  ];
+
+  // 下拉中显示 "Alice (Engineering)"
+  const retrieveOptionText = (emp: any) => `${emp.name} (${emp.dept})`;
+
+  // 按 name / dept / email 任一字段过滤
+  const filter = (emp: any, keyword: string) =>
+    !keyword || [emp.name, emp.dept, emp.email].some(v =>
+      v.toLowerCase().includes(keyword.toLowerCase())
+    );
+</script>
+
+<InputOptionsSelect
+  {options: employees}
+  keyField="id"
+  textField="name"
+  bind:value={value}
+  retrieveOptionText={retrieveOptionText}
+  filterFunction={filter}
+  placeholder="搜索员工..."
+/>
+```
+
+### 禁用 / 隐藏选项
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+
+  let value = $state<string | null>(null);
+
+  const statuses = [
+    { code: "ACTIVE",    text: "Active" },
+    { code: "SUSPENDED", text: "Suspended" },
+    { code: "BANNED",    text: "Banned" },
+    { code: "DELETED",   text: "Deleted" }
+  ];
+</script>
+
+<InputOptionsSelect
+  {options: statuses}
+  bind:value={value}
+  disableOptions={["BANNED"]}
+  hideOptions={["DELETED"]}
+  placeholder="选择状态"
+/>
+```
+
+### 只读模式
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+
+  let value = $state("E001");
+
+  const options = [
+    { code: "E001", text: "Alice" },
+    { code: "E002", text: "Bob" }
+  ];
+</script>
+
+<InputOptionsSelect
+  {options}
+  bind:value={value}
+  readonly
+/>
+```
+
+## 行为说明
+
+### 与 OptionsSelect 的区别
+
+| 方面 | InputOptionsSelect | OptionsSelect |
+|------|-------------------|---------------|
+| 输入方式 | `<input>` + 实时过滤 | 点击打开下拉框 |
+| 过滤时机 | 逐字符触发，客户端过滤 | 点击打开后过滤 |
+| 适用场景 | 用户经常输入的场景 | 用户浏览的场景 |
+
+### 只读 / 禁用渲染
+
+两种模式都渲染普通 `<input readonly>`，显示文本。清空按钮、下拉箭头、下拉面板都不渲染。
+
+### `emptyText` 与 `placeholder`
+
+- `placeholder` —— 输入框的原生占位文字，`value` 为空时显示。
+- `emptyText` —— 覆盖显示文本，用于当前 `value` 在 `options` 中找不到对应项的场景。
+
+## 无障碍
+
+- 下拉通过 `Popover`（portal 渲染到 `document.body`）实现，有 scroll/resize 监听。
+- 键盘：方向键移动选中，Enter 确认，Escape 关闭，下拉打开时 Tab 被锁。
+- 完整的 ARIA 需要外层 `<label>` / `FormField` 配合 `error` 文本。
+
+## 相关组件
+
+- [OptionsSelect](../options_select/README_CN.md) —— 纯下拉变体。
+- [OptionsMultiSelect](../options_multi_select/README_CN.md) —— 多选变体。
+- [LookupEditor](../lookup_editor/README_CN.md) —— 大列表 / 远程数据的懒加载选择器。

package/dist/form/input_options_select/index.d.ts

@@ -0,0 +1,4 @@
+import InputOptionsSelect from "./InputOptionsSelect.svelte";
+import type { RetrieveOptionText } from "../../types";
+export default InputOptionsSelect;
+export type { RetrieveOptionText };

package/dist/form/lookup_editor/LookupEditor.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+    import type {Snippet} from "svelte";
+    import CommonEditor from "../common_editor/CommonEditor.svelte";
+    import Icon from "../../general/icon";
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+
+
+    interface Props extends CommonFieldProps {
+        mandatory?: boolean;
+        value?: any;
+        text?: string;
+        onaction?: () => void;
+        leadingIcon?: Snippet;
+    }
+
+    let {
+        theme,
+        style,
+        tooltip,
+        error,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        mandatory = false,
+        variant,
+        value = $bindable(),
+        text,
+        placeholder,
+        onaction,
+        onchange,
+        onfocus,
+        onblur
+    }: Props = $props();
+
+    let editor: HTMLInputElement | undefined = $state(undefined);
+
+    export function focus() {
+        editor?.focus();
+    }
+
+    export function clear() {
+        value = null;
+        text = '';
+        onchange?.(null);
+    }
+
+    const handleActionClick = () => {
+        if (!disabled && !readonly) {
+            onaction?.();
+        }
+    };
+
+</script>
+
+<CommonEditor {theme} {clear} {style} {tooltip} {error} {readonly} {disabled} {compact} {variant} textValue={text??''} canClean={!mandatory}>
+    <input bind:this={editor} {placeholder} readonly value={text ?? ''} {onfocus} {onblur}/>
+    {#snippet trailingIcon()}
+        {#if !disabled && !readonly}
+            <i class="icon_google_arrow_drop_down action_icon" role="list" aria-hidden="true"
+               onmousedown={(event: MouseEvent)=> {event.preventDefault()}}
+               onclick={handleActionClick}></i>
+        {/if}
+    {/snippet}
+</CommonEditor>
+
+<style>
+    .action_icon {
+        visibility: hidden;
+        cursor: pointer;
+    }
+
+    .action_icon:active {
+        position: relative;
+        top: 1px;
+    }
+
+    :global(.uniface-common-editor:hover) .action_icon,
+    :global(.uniface-common-editor:focus-within) .action_icon {
+        visibility: visible;
+    }
+</style>

package/dist/form/lookup_editor/LookupEditor.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from "svelte";
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+interface Props extends CommonFieldProps {
+    mandatory?: boolean;
+    value?: any;
+    text?: string;
+    onaction?: () => void;
+    leadingIcon?: Snippet;
+}
+declare const LookupEditor: import("svelte").Component<Props, {
+    focus: () => void;
+    clear: () => void;
+}, "value">;
+type LookupEditor = ReturnType<typeof LookupEditor>;
+export default LookupEditor;

package/dist/form/lookup_editor/README.md

@@ -0,0 +1,345 @@
+# LookupEditor
+
+A lazy-loading picker for large or remote option lists. The user types into the input, and the picker makes an API call to fetch matching options. The response is expected to be an array of `{code: any, text: string}` objects. When an option is selected, the input shows the text and `value` holds the code.
+
+> Think of it as a search-driven `<select>`. Great for user lookup, product lookup, or any scenario where the full option list doesn't fit in memory.
+
+## Features
+
+- **Lazy loading** — fetches options on demand via `onLookup` callback.
+- **Input-driven** — typing triggers the lookup, options appear in a dropdown.
+- **Single selection** — click an option to select it.
+- **`onaction` event** — fires when the action icon (↓) is clicked. Use this to open a custom lookup dialog.
+- **Custom field mapping** — `codeField` / `textField` define how lookup results map to value / display.
+- **`text` prop** — display text shown in the input. Set this externally to show a label without changing `value`.
+- **`clear()` method** — programmatically clears the value and text.
+- **Disabled / readonly** modes — dropdown suppressed, renders a plain input.
+- **Keyboard navigation** — arrow keys move selection, Enter selects, Escape closes, Tab is contained while dropdown is open.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+
+  // Simulated API call
+  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("Action clicked - open custom dialog");
+  }
+</script>
+
+<LookupEditor
+  onlookup={lookupUsers}
+  onaction={handleAction}
+  bind:value={value}
+  placeholder="Search users..."
+/>
+```
+
+## Props
+
+`LookupEditor` extends `CommonFieldProps`, so it inherits `variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur` / `onchange`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `any` (bindable) | — | The selected option's code. `bind:value={...}` round-trips; setting it externally updates the display text. |
+| `text` | `string` | — | Display text shown in the input. If set externally, overrides the auto-generated text from the selected option. |
+| `codeField` | `string` | `"code"` | Property used as the option's identity. |
+| `textField` | `string` | `"text"` | Property used as the option's display text. |
+| `placeholder` | `string` | — | Shown when `value` is empty. |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Visual style variant. |
+| `compact` | `boolean` | `false` | Dense layout for table cells and inline forms. |
+| `disabled` | `boolean` | `false` | Fully disabled — plain input, no dropdown. |
+| `readonly` | `boolean` | `false` | Read-only — same visual as disabled, "view, don't edit". |
+| `style` | `string` | — | Inline CSS on the editor root. |
+| `error` | `string` | — | Validation error text — triggers the editor's error state. |
+| `tooltip` | `string` | — | Hover tooltip on the editor. |
+| `theme` | `string` | — | Rendered as `data-theme` on the dropdown for scoped styling. |
+| `onlookup` | `(keyword: string) => Promise<Array<any>>` | — | **Required.** Async function that fetches matching options given a keyword. Must return an array of `{code, text}` objects. |
+| `onaction` | `() => void` | — | Fires when the action icon (↓) is clicked. Use this to open a custom lookup dialog or perform a different action. |
+| `onchange` | `(value: any) => void` | — | Fires once when the user picks an item. Receives the **full option object** (not just the code). Does not fire on programmatic `value` changes. |
+| `onfocus` | `(e: FocusEvent) => void` | — | Input focus. |
+| `onblur` | `(e: FocusEvent) => void` | — | Input blur. Fires after the popup closes and focus truly left the editor. |
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `onlookup` | `(keyword: string) => Promise<Array<any>>` | Fires when the user types. Must fetch and return matching options. |
+| `onaction` | `() => void` | Fires when the action icon (↓) is clicked. |
+| `onchange` | `(value: any) => void` | Fires once when the user picks an item. Receives the **full option object**. |
+| `onfocus` | `(e: FocusEvent) => void` | Input focus. |
+| `onblur` | `(e: FocusEvent) => void` | Input blur. Fires after the popup closes and focus truly left the editor. |
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `focus()` | `() => void` | Moves focus to the editor input. |
+| `clear()` | `() => void` | Programmatically clears the value and text. Resets to empty state. |
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let editor;
+
+  const lookupUsers = async (keyword: string) => {
+    // ... fetch logic
+  };
+
+  function handleClear() {
+    editor.clear();
+  }
+</script>
+
+<LookupEditor bind:this={editor} {lookupUsers} bind:value placeholder="Search users..." />
+<button onclick={handleClear}>Clear</button>
+```
+
+## `onlookup` — lazy loading
+
+The `onlookup` callback is the heart of this component. It receives the current input value as `keyword` and must return a promise that resolves to an array of `{code, text}` objects.
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+
+  // Real API call
+  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="Search products..."
+/>
+```
+
+## Examples
+
+### Employee lookup with custom action
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+  let isDialogOpen = $state(false);
+
+  // Simulated API
+  const lookupEmployees = async (keyword: string) => {
+    const allEmployees = [
+      { code: "E001", text: "Alice Johnson (Engineering)" },
+      { code: "E002", text: "Bob Smith (Marketing)" },
+      { code: "E003", text: "Carol Williams (Engineering)" },
+      { code: "E004", text: "Dave Brown (Sales)" }
+    ];
+    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="Search employees..."
+/>
+
+{#if isDialogOpen}
+  <div class="modal-overlay" onclick={closeDialog}>
+    <div class="modal" onclick={(e: Event) => e.stopPropagation()}>
+      <h3>Add New Employee</h3>
+      <form>
+        <input type="text" placeholder="Name" />
+        <input type="text" placeholder="Email" />
+        <button type="button" onclick={closeDialog}>Close</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>
+```
+
+### Product lookup with action
+
+```svelte
+<script lang="ts">
+  import LookupEditor from "@ticatec/uniface-element/LookupEditor";
+
+  let value = $state<string | null>(null);
+
+  const lookupProducts = async (keyword: string) => {
+    // Simulated API with delay
+    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("Action clicked - open product catalog");
+  }
+</script>
+
+<LookupEditor
+  onlookup={lookupProducts}
+  onaction={handleAction}
+  bind:value={value}
+  placeholder="Search products..."
+/>
+```
+
+### Disabled / readonly modes
+
+```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 (disabled)"
+  />
+  <LookupEditor
+    onlookup={lookupEmployees}
+    bind:value={readonlyValue}
+    readonly
+    text="Bob (readonly)"
+  />
+</div>
+```
+
+## Behavior Notes
+
+### How `value` and `text` interact
+
+| Action | Effect |
+|--------|--------|
+| User selects an option | `value` is set to the option's code; `text` is auto-generated from the option's text field. |
+| Parent sets `value` externally | The input displays the text from the matched option (if available), or falls back to the raw code. |
+| Parent sets `text` externally | The input shows the custom text, regardless of `value`. |
+| Parent sets both | The input shows `text` (if set); `value` determines the internal state. |
+
+### `clear()` method
+
+Calling `clear()` resets both `value` and `text` to empty. Useful for reset buttons or form clearing.
+
+### Read-only / disabled rendering
+
+Both modes render a plain `<input readonly>` with the display text. The clear (×) button, dropdown arrow, and dropdown are all suppressed.
+
+## Accessibility
+
+- Dropdown uses `Popover` (portal to `document.body`) with scroll/resize listeners.
+- Keyboard: Arrow keys move selection, Enter selects, Escape closes, Tab is contained while dropdown is open.
+- For full ARIA, wrap with `<label>` / `FormField` and provide `error` text.
+
+## Related Components
+
+- [OptionsSelect](../options_select/README.md) — static dropdown variant.
+- [InputOptionsSelect](../input_options_select/README.md) — client-side filtered variant.
+- [CascadeOptionSelect](../cascade_options_select/README.md) — tree-shaped cascading picker.