@ticatec/uniface-element 5.0.4 → 5.1.0

package/dist/form/input_options_select/InputOptionsSelect.svelte

@@ -10,7 +10,8 @@
         keyField?: string;
         textField?: string;
         retrieveText?: RetrieveOptionText;
-        displayCode?: boolean;
+        /** 是否显示选项 code */
+        showCode?: boolean;
         menu$height?: number;
         itemRender?: any;
         lazyLoader?: ListLazyLoader;
@@ -22,7 +23,7 @@
         disabled = false,
         readonly = false,
         compact = false,
-        mandatory = false,
+        clearable,
         error,
         tooltip,
         theme,
@@ -33,13 +34,14 @@
         keyField = 'code',
         textField = "text",
         retrieveText,
-        displayCode = false,
+        showCode = false,
         menu$height = 0,
         itemRender: ItemRender = undefined,
         lazyLoader,
         onchange,
         onfocus,
         onblur,
+        oninput,
     }: Props = $props();
 
 
@@ -132,6 +134,7 @@
 
     const handleInputText = (s: string) => {
         inputText = s;
+        oninput?.(s);
         if (lazyLoader != null) {
             delayReload();
         }
@@ -170,7 +173,7 @@
         }
     };
 
-    const oninput = (event: Event) => {
+    const handleInput = (event: Event) => {
         isUserTyping = true;
         if (!composing) {
             value = null;
@@ -205,9 +208,9 @@
 </script>
 
 <CommonPicker
-        {variant} {style} {compact} {tooltip} {error} {mandatory} textValue={text}
-        {readonly} {disabled} {theme} {placeholder} {value} {onblur} {onfocus} displayAction={false}
-        bind:isOpen {clear} {oninput} {oncompositionstart} {oncompositionend} input$readonly={false}
+        {variant} {style} {compact} {tooltip} {error} {clearable} textValue={text}
+        {readonly} {disabled} {theme} {placeholder} {value} {onblur} {onfocus} showAction={false}
+        bind:expanded={isOpen} {clear} oninput={handleInput} {oncompositionstart} {oncompositionend} input$readonly={false}
         autoFit>
 
     <div class="option-field" >
@@ -217,7 +220,7 @@
             </div>
         {/if}
     </div>
-    {#snippet popupLayer()}
+    {#snippet popup()}
         <div class="options-popover" bind:this={scrollElement} style={mh} onscroll={handleScroll} role="listbox">
             {#each options as op (op[keyField])}
                 <div class="option-item" onclick={handleItemClick(op)} onkeydown={handleItemKeyDown(op)}

package/dist/form/input_options_select/InputOptionsSelect.svelte.d.ts

@@ -6,7 +6,8 @@ interface Props extends CommonPickerProps {
     keyField?: string;
     textField?: string;
     retrieveText?: RetrieveOptionText;
-    displayCode?: boolean;
+    /** 是否显示选项 code */
+    showCode?: boolean;
     menu$height?: number;
     itemRender?: any;
     lazyLoader?: ListLazyLoader;

package/dist/form/input_options_select/README.md

@@ -1,247 +1,73 @@
 # InputOptionsSelect
 
-A text-input component with an expandable option list. Unlike the pure `OptionsSelect` dropdown, this one starts as a normal text input — typing filters the options and they appear in a dropdown below. Great for scenarios where users frequently type partial values rather than browsing.
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `mandatory` were removed in 5.1.0 (no compatibility aliases are kept).
 
-> Think of it as the bridge between a plain `<input>` and a `<select>`. Type to filter, pick to select.
+A type-to-search picker backed by a remote loader: the user types a keyword, the component fetches candidates page by page through `lazyLoader` and shows them in a panel below the input; clicking an item writes its key into `value`. Use it when the candidate set is large and must be searched on the server (customers, products, addresses).
+
+> Difference from `OptionsSelect`: `OptionsSelect` takes a full `options` array and filters locally; `InputOptionsSelect` has **no** `options` prop — every candidate comes from `lazyLoader`.
 
 ## Features
 
-- **Text input + dropdown** — typing filters options in real time; dropdown shows matching items.
-- **Single selection** — clicking an option selects it and closes the dropdown.
-- **`value` is the option key** — bound to whatever your `keyField` says.
-- **Custom field mapping** — `keyField` / `textField` define how option objects map to value / display.
-- **Custom option retrieval** — pass `retrieveOptionText` to format or transform the text that appears in the dropdown and the input.
-- **Hide / disable individual options** — `hideOptions` / `disableOptions`.
-- **Quick filter** — `filterFunction` controls which options pass the filter check.
-- **Mandatory mode** — hides the clear button so users can't empty the field.
-- **Compact mode** — for dense UIs like table cells.
-- **Disabled / readonly** — dropdown suppressed, renders a plain input.
-- **Shared form-editor props** — `variant`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur` / `onchange`.
-- **Keyboard navigation** — arrow keys move selection, Enter selects, Escape closes, Tab is contained while the dropdown is open.
-
-## Installation
-
-```bash
-npm install @ticatec/uniface-element
-```
+- **Search as you type**: 200 ms after typing stops it calls `lazyLoader(text, 1)`; further typing aborts the pending request.
+- **Scroll paging**: reaching the bottom of the panel calls `lazyLoader(text, pageNo + 1)` until `hasMore: false` is returned.
+- **`value` is the option key** (`keyField`); the display text comes from `textField` or `retrieveText`.
+- **Custom item rendering** via `itemRender` (a Svelte component receiving `item`).
+- **Non-clearable mode**: `clearable={false}` hides the clear button.
+- **Shared field props** inherited from `CommonPickerProps` (`variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur` / `onchange`).
 
 ## Import
 
 ```typescript
 import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+import type {ListLazyLoader} from "@ticatec/uniface-element/types";
 ```
 
-## Basic Usage
+## Basic usage
 
 ```svelte
 <script lang="ts">
   import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
+  import type {ListLazyLoader} from "@ticatec/uniface-element/types";
 
   let value = $state<string | null>(null);
+  let text = $state('');
 
-  const options = [
-    { code: "JS", text: "JavaScript" },
-    { code: "TS", text: "TypeScript" },
-    { code: "PY", text: "Python" },
-    { code: "GO", text: "Go" }
-  ];
+  const loadCustomers: ListLazyLoader = async (keyword, pageNo) => {
+    const res = await fetch(`/api/customers?q=${encodeURIComponent(keyword)}&page=${pageNo}`);
+    const data = await res.json();          // { list: [...], hasMore: boolean }
+    return {list: data.list, hasMore: data.hasMore};
+  };
 </script>
 
-<InputOptionsSelect {options} bind:value placeholder="Type to search..." />
+<InputOptionsSelect bind:value {text} lazyLoader={loadCustomers} placeholder="Type to search customers"
+                    onchange={(item) => text = item?.text ?? ''}/>
 ```
 
 ## Props
 
-`InputOptionsSelect` extends `CommonFieldProps`, so it inherits `variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur` / `onchange`.
+Props inherited from `CommonPickerProps` are not repeated here.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value` | `any` (bindable) | — | The selected option's key. `bind:value={...}` round-trips; setting it externally updates the display text. |
-| `options` | `Array<any>` | — | Full list of option objects. |
-| `keyField` | `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. |
-| `emptyText` | `string` | — | Shown when no option matches `value`. Useful for "saved value no longer exists" cases. |
-| `disableOptions` | `Array<string>` | `[]` | Keys rendered but unclickable (dimmed). |
-| `hideOptions` | `Array<string>` | `[]` | Keys not rendered at all. |
-| `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". |
-| `mandatory` | `boolean` | `false` | Hides the clear (×) button. |
-| `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. |
-| `itemRender` | `{ component: any; props?: Record<string, any> } \| undefined` | — | Custom Svelte component per option row. Receives `item`, `disabled`, `onclick`. |
-| `filterFunction` | `((option: any, keyword: string) => boolean) \| undefined` | — | Filter function. If provided, it is called per option during typing. |
-| `noResultsText` | `string` | `"No results found"` | Text shown when the filtered list is empty. |
-| `retrieveOptionText` | `(option: any) => string \| null \| undefined` | — | Optional transformer. Receives the option object and returns the text to display. If it returns `undefined`, the option's `textField` value is used as-is. |
-| `onchange` | `(value: any) => void` | — | Fires once when the user picks an item. Receives the **full option object**. 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 |
-|-------|-----------|-------------|
-| `onchange` | `(value: any) => void` | Fires once when the user picks an item. Receives the **full option object** (not the key). |
-| `onfocus` | `(e: FocusEvent) => void` | Input focus. |
-| `onblur` | `(e: FocusEvent) => void` | Input blur. Fires after the popup closes and focus truly left the editor. |
-
-## `retrieveOptionText`
-
-This hook lets you format or transform the text that appears in the input and dropdown. It receives the full option object and returns the display string.
-
-```svelte
-<script lang="ts">
-  import InputOptionsSelect from "@ticatec/uniface-element/InputOptionsSelect";
-
-  let value = $state<string | null>(null);
-
-  const options = [
-    { code: 1001, text: "John Doe",   age: 30, department: "Engineering" },
-    { code: 1002, text: "Jane Smith", age: 25, department: "Marketing" },
-    { code: 1003, text: "Bob Lee",    age: 35, department: "Engineering" }
-  ];
-
-  // Show "John Doe (Engineering)" instead of just the name
-  const retrieveOptionText = (option: any) => {
-    return `${option.text} (${option.department})`;
-  };
-</script>
-
-<InputOptionsSelect
-  {options}
-  bind:value
-  retrieveOptionText={retrieveOptionText}
-  placeholder="Search employees..."
-/>
-```
-
-## `itemRender`
-
-Pass `{component, props?}`. The component receives:
-
-| Prop | Source |
-|------|--------|
-| `item` | The current option object. |
-| `disabled` | `true` when the option's key is in `disableOptions`. |
-| `onclick` | Internal handler — call this to select the item. |
-| `...props` | Anything from `itemRender.props` is spread onto the component. |
-
-## Examples
-
-### Employee search with custom text format
-
-```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" }
-  ];
-
-  // Show "Alice (Engineering)" in the dropdown
-  const retrieveOptionText = (emp: any) => `${emp.name} (${emp.dept})`;
-
-  // Filter by name, dept, or 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="Search employees..."
-/>
-```
-
-### Disabled / hidden options
-
-```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="Select status"
-/>
-```
-
-### Read-only mode
-
-```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
-/>
-```
-
-## Behavior Notes
-
-### How it differs from OptionsSelect
-
-| Aspect | InputOptionsSelect | OptionsSelect |
-|--------|-------------------|---------------|
-| Input type | `<input>` with live filtering | Click-only dropdown |
-| Filtering | Per-character, client-side | Click to open, then filter |
-| Typing | Types into the input, options follow | Clicks to open the picker |
-| Best for | Users who type often | Users who browse |
-
-### 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.
-
-### `emptyText` vs `placeholder`
-
-- `placeholder` — native input placeholder, shown when `value` is empty.
-- `emptyText` — overrides the display text when `value` doesn't match any option in `options`.
-
-## 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) — pure dropdown variant.
-- [OptionsMultiSelect](../options_multi_select/README.md) — multi-select variant.
-- [LookupEditor](../lookup_editor/README.md) — lazy-loading picker for large / remote option lists.
+| `value` | `any` (bindable) | — | Key of the selected item (`item[keyField]`). Reset to `null` when the user types again. |
+| `text` | `string` | — | Text currently shown in the input. Updated by the component after a selection; pass the display text of a pre-selected item on init. |
+| `lazyLoader` | `ListLazyLoader` | — | `(text, pageNo) => Promise<{list, hasMore}>`. **Required** — without it typing triggers no search. |
+| `keyField` | `string` | `"code"` | Field used as `value`. |
+| `textField` | `string` | `"text"` | Default display-text field. |
+| `retrieveText` | `(item) => string` | — | Custom display text; takes precedence over `textField`. |
+| `itemRender` | Svelte component | — | Custom renderer for each item; receives an `item` prop. |
+| `menu$height` | `number` | `0` | Fixed panel height in px; `0` means auto with a 300 px cap. |
+| `clearable` | `boolean` | `true` | Whether the clear button is shown; with `false` the user cannot empty the value. |
+| `onchange` | `(item: any) => void` | — | Fired when the user clicks an item; receives the **whole option object**. Clearing or retyping does not fire it. |
+
+## Behavior notes
+
+- Only non-empty text triggers a search; clearing the input does not call `lazyLoader`.
+- The panel opens while `options.length > 0 || loading` and closes automatically when a search returns nothing.
+- With `readonly` / `disabled` the input is not editable and no search runs.
+
+## Related components
+
+- `OptionsSelect` — single select over a local options array.
+- `LookupEditor` — pick complex objects through a popup lookup UI.
+- `ListBox` — a list box that also supports `lazyLoader`.