@ticatec/uniface-element 0.3.23 → 5.0.1

package/dist/form/options_select/OptionsSelect.svelte

@@ -0,0 +1,188 @@
+<script lang="ts">
+
+    import CommonPicker from "../common_editor/CommonPicker.svelte";
+    import SearchBox from "../search_box/SearchBox.svelte";
+    import type CommonPickerProps from "../common_editor/CommonPickerProps";
+    import i18nRes from "../../i18nRes";
+
+    interface Props extends CommonPickerProps {
+        emptyText?: string;
+        value: any;
+        options: Array<any>;
+        keyField?: string;
+        textField?: string;
+        menu$height?: number;
+        disableOptions?: Array<string>;
+        hideOptions?: Array<string>;
+        itemRender?: any;
+        filterPlaceholder?: string;
+        filterFunction?: (option: any, keyword: string) => boolean;
+        noResultsText?: string;
+    }
+
+    let {
+        variant,
+        disabled = false,
+        readonly = false,
+        mandatory = false,
+        compact = false,
+        error,
+        tooltip,
+        theme,
+        value = $bindable(),
+        options,
+        style,
+        placeholder,
+        keyField = "code",
+        textField = "text",
+        emptyText,
+        menu$height = 0,
+        disableOptions = [],
+        hideOptions = [],
+        onchange,
+        onfocus,
+        onblur,
+        filterPlaceholder = i18nRes.common.filterPlaceholder.toString(),
+        filterFunction,
+        noResultsText = i18nRes.common.noResultsText.toString(),
+        itemRender,
+    }: Props = $props();
+
+
+    let searchBox: SearchBox | undefined = $state(undefined);
+    let editor: HTMLElement | undefined = $state(undefined);
+    let isOpen = $state(false);
+    let hasFocus = $state(false);
+    let filterText: string | undefined = $state(undefined);
+
+    const textValue = $derived.by(() => {
+        let item = (options || []).find(el => String(el[keyField]) === String(value));
+        return item == null ? (emptyText ?? '') : String(item[textField] ?? '');
+    });
+
+    const defaultFilterFunction = (option: any, keyword: string): boolean => {
+        if (!keyword || keyword.length === 0) return true;
+        const text = String(option[textField] || '').toLowerCase();
+        return text.includes(keyword.toLowerCase());
+    }
+
+    const getFilteredOptions = (keyword?: string): Array<any> => {
+        if (!keyword || keyword.trim() == '') {
+            return options ? [...options] : [];
+        } else {
+            const filterFn = filterFunction || defaultFilterFunction;
+            return (options || []).filter(op => filterFn(op, keyword));
+        }
+    }
+
+    const searchOptions = (event: Event) => {
+        doSearch(filterText);
+    };
+
+    const doSearch = (keyword?: string) => {
+        filterText = keyword ?? '';
+    }
+
+    export const focus = () => {
+        setTimeout(() => {
+            picker?.focus();
+        }, 50);
+    }
+
+    let filteredOptions = $derived(getFilteredOptions(filterText));
+    const mh = $derived(`height: ${menu$height > 0 ? menu$height + 'px' : 'auto'}`);
+
+    $effect(() => {
+        if (isOpen) {
+            if (filterFunction != null) {
+                setTimeout(() => {
+                    searchBox?.focus();
+                    filterText = "";
+                    doSearch(filterText);
+                }, 50);
+            } else {
+                picker?.focus();
+            }
+        }
+    });
+
+    // 监听popup关闭，如果是点击外部关闭且之前有焦点，触发blur
+    $effect(() => {
+        if (!isOpen && hasFocus) {
+            // 延迟检查，如果input仍然有焦点，说明是选择项目导致的关闭
+            setTimeout(() => {
+                if (document.activeElement !== editor &&
+                    (!searchBox || document.activeElement !== (searchBox as any).element)) {
+                    hasFocus = false;
+                    onblur?.(new FocusEvent('blur'));
+                }
+            }, 50);
+        }
+    });
+
+
+    const handleItemClick = (data: any) => () => {
+        if (disableOptions.indexOf(data[keyField]) < 0) {
+            value = data[keyField];
+            onchange?.(data);
+            isOpen = false;
+            picker?.focus();
+        }
+    }
+
+
+    let picker: CommonPicker;
+
+</script>
+
+<CommonPicker bind:this={picker} {error} {tooltip} {variant} {style} {compact} {textValue} {readonly} {placeholder} {disabled} bind:isOpen
+              {theme} {value} clear={()=> {value = undefined}} {mandatory} {onfocus} {onblur}>
+    {#snippet popupLayer()}
+        <div class="uniface-options-popover" style={mh}>
+            {#if filterFunction != null}
+                <div class="quick-filter-box">
+                    <SearchBox
+                            bind:value={filterText}
+                            bind:this={searchBox}
+                            oninput={searchOptions}
+                            onblur={()=> {focus()}}
+                            onkeydown={(event: KeyboardEvent) => {if (event.key === 'Escape') {isOpen = false}}}
+                            placeholder={filterPlaceholder}/>
+                </div>
+            {/if}
+            {#if filteredOptions.length === 0}
+                <div class="no-results">
+                    <span>{noResultsText}</span>
+                </div>
+            {:else}
+                {#each filteredOptions as op}
+                    {#if hideOptions.indexOf(op[keyField]) < 0}
+                        {#if itemRender != null}
+                            {@const ItemComp = itemRender.component}
+                            <ItemComp {...itemRender.props} item={op}
+                                      disabled={disableOptions.indexOf(op[keyField])>-1}
+                                      onclick={handleItemClick(op)}/>
+                        {:else}
+                            <div class="option-item" class:disabled={disableOptions.indexOf(op[keyField])>-1} aria-hidden="true"
+                                 onclick={handleItemClick(op)}>
+                                <span>{op[textField]}</span>
+                            </div>
+                        {/if}
+                    {/if}
+                {/each}
+            {/if}
+        </div>
+    {/snippet}
+</CommonPicker>
+
+<style>
+    .no-results {
+        position: relative;
+        width: 100%;
+        padding: var(--uniface-option-item-margin);
+        line-height: 1.5em;
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+    }
+</style>

package/dist/form/options_select/OptionsSelect.svelte.d.ts

@@ -0,0 +1,20 @@
+import type CommonPickerProps from "../common_editor/CommonPickerProps";
+interface Props extends CommonPickerProps {
+    emptyText?: string;
+    value: any;
+    options: Array<any>;
+    keyField?: string;
+    textField?: string;
+    menu$height?: number;
+    disableOptions?: Array<string>;
+    hideOptions?: Array<string>;
+    itemRender?: any;
+    filterPlaceholder?: string;
+    filterFunction?: (option: any, keyword: string) => boolean;
+    noResultsText?: string;
+}
+declare const OptionsSelect: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type OptionsSelect = ReturnType<typeof OptionsSelect>;
+export default OptionsSelect;

package/dist/form/options_select/README.md

@@ -0,0 +1,369 @@
+# OptionsSelect
+
+A single-selection dropdown picker. The user types nothing — they click, optionally filter, and pick one option from a list. Renders via the shared `CommonPicker` + `Popover` chrome, so it inherits the same surface/shadow/border tokens every dropdown in the library uses.
+
+> This is the **single-select** picker. For multi-select see [OptionsMultiSelect](../options_multi_select/README.md); for cascading (tree-shaped) data see [CascadeOptionSelect](../cascade_options_select/README.md).
+
+## Features
+
+- **Single selection** with `value` bound to the option's key field (default `code`).
+- **Custom field mapping** via `keyField` / `textField` — your option objects don't need to be shaped `{code, text}`.
+- **Hide or disable individual options** through `hideOptions` / `disableOptions`.
+- **Optional quick filter** — pass a `filterFunction` and the dropdown grows a search box at the top. No separate `quickFilter` boolean anymore; the presence of `filterFunction` is the toggle.
+- **Custom item rendering** through `itemRender` — supply `{component, props}`, receive `item` / `disabled` / `onclick`.
+- **Read-only & disabled modes** — replaces the old `displayMode` enum.
+- **Mandatory mode** — hides the clear (×) button so the user can't empty the field.
+- **Compact mode** for table cells and dense forms.
+- **`error` / `tooltip` / `theme`** pass-throughs shared with the rest of the form-editor family.
+- **Keyboard support**: Backspace / Delete clears, Escape closes, Tab is contained while the popup is open.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+
+  let selected = $state<string | null>(null);
+
+  const options = [
+    { code: "JS", text: "JavaScript" },
+    { code: "TS", text: "TypeScript" },
+    { code: "PY", text: "Python" }
+  ];
+</script>
+
+<OptionsSelect {options} bind:value={selected} placeholder="Pick a language" />
+```
+
+## Props
+
+`OptionsSelect` extends `PickerProps`, so all the common editor props (`variant`, `compact`, `disabled`, `readonly`, `mandatory`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur` / `onchange`) are available out of the box.
+
+| 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>` | — | The full list of option objects. |
+| `keyField` | `string` | `"code"` | Property name to use as the option's identity / value. |
+| `textField` | `string` | `"text"` | Property name to display. |
+| `placeholder` | `string` | — | Shown in the input when `value` is empty. |
+| `emptyText` | `string` | — | Overrides the display text when no option matches `value`. Useful for "the saved value is no longer in the list" cases. |
+| `disableOptions` | `Array<string>` | `[]` | Keys of options that should render but be unclickable (dimmed). |
+| `hideOptions` | `Array<string>` | `[]` | Keys of options that should not render 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 — renders a read-only input, no popup. |
+| `readonly` | `boolean` | `false` | Read-only — same visual as disabled but semantics are "view, don't edit". |
+| `mandatory` | `boolean` | `false` | Hides the clear (×) button. The user must pick something; they can't go back to empty. |
+| `style` | `string` | — | Inline CSS on the editor root. |
+| `error` | `string` | — | Validation error text. Triggers the editor's error state (typically a red border). |
+| `tooltip` | `string` | — | Hover tooltip on the editor. |
+| `theme` | `string` | — | Rendered as `data-theme` on the popover for scoped styling overrides. |
+| `menu$height` | `number` | `0` | Fixed dropdown height in px. `0` means `auto` (CSS default `max-height: 30vh` applies). |
+| `itemRender` | `{ component: any; props?: Record<string, any> } \| undefined` | — | Custom Svelte component for each item. Receives `item`, `disabled`, `onclick` plus any `props` you spread. |
+| `filterFunction` | `((option: any, keyword: string) => boolean) \| undefined` | — | **If provided**, a search box appears at the top of the dropdown and this function is called per option. Omit it for a flat list. |
+| `noResultsText` | `string` | `"No results found"` | Text shown when the filtered list is empty. |
+| `onchange` | `(value: any) => void` | — | Fires once when the user picks an item. Receives the **full option object** (not the key). Does not fire on programmatic `value` changes from the parent — `onchange` is user-action-only. |
+| `onfocus` | `(e: FocusEvent) => void` | — | Input focus. |
+| `onblur` | `(e: FocusEvent) => void` | — | Input blur. Fires after the popup closes and focus has 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 has truly left the editor. |
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `focus()` | `() => void` | Focuses the editor input. Internally deferred by 50 ms so the popover has time to mount. |
+
+Use it via `bind:this`:
+
+```svelte
+<script>
+  let picker;
+</script>
+
+<OptionsSelect bind:this={picker} {options} bind:value />
+<button onclick={() => picker.focus()}>Focus the picker</button>
+```
+
+## `itemRender` — custom item rendering
+
+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 on click to select the item. |
+| `...props` | Anything you put in `itemRender.props` is spread onto the component. |
+
+```svelte
+<!-- PriorityItem.svelte -->
+<script lang="ts">
+  let { item, disabled = false, onclick, showIcon = true } = $props();
+</script>
+
+<div class="priority-item" class:disabled {onclick} role="option">
+  {#if showIcon}<span class="dot" style="background:{item.color}"></span>{/if}
+  <span>{item.label}</span>
+</div>
+
+<style>
+  .priority-item { display: flex; align-items: center; gap: 8px; padding: 6px 8px; cursor: pointer; }
+  .priority-item.disabled { opacity: .4; cursor: not-allowed; }
+  .dot { width: 8px; height: 8px; border-radius: 50%; }
+</style>
+```
+
+```svelte
+<!-- Consumer -->
+<script lang="ts">
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+  import PriorityItem from "./PriorityItem.svelte";
+
+  let value = $state("MEDIUM");
+  const options = [
+    { level: "LOW",    label: "Low",    color: "#4caf50" },
+    { level: "MEDIUM", label: "Medium", color: "#ff9800" },
+    { level: "HIGH",   label: "High",   color: "#f44336" }
+  ];
+</script>
+
+<OptionsSelect
+  {options}
+  keyField="level"
+  textField="label"
+  bind:value
+  itemRender={{ component: PriorityItem, props: { showIcon: true } }}
+/>
+```
+
+## Examples
+
+### Currency picker with change handler
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+
+  let currency = $state("USD");
+  const currencies = [
+    { code: "USD", text: "US Dollar" },
+    { code: "EUR", text: "Euro" },
+    { code: "GBP", text: "British Pound" },
+    { code: "JPY", text: "Japanese Yen" },
+    { code: "CNY", text: "Chinese Yuan" }
+  ];
+
+  function handleChange(v: any) {
+    console.log("changed:", v);
+  }
+</script>
+
+<OptionsSelect
+  {options: currencies}
+  bind:value={currency}
+  variant="outlined"
+  placeholder="Select currency"
+  onchange={handleChange}
+/>
+```
+
+### Disabled + hidden options
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+
+  let status = $state("PENDING");
+  const statuses = [
+    { code: "PENDING",    text: "Pending" },
+    { code: "IN_PROGRESS", text: "In Progress" },
+    { code: "REVIEW",     text: "Under Review" },
+    { code: "COMPLETED",  text: "Completed" },
+    { code: "CANCELLED",  text: "Cancelled" },
+    { code: "ARCHIVED",   text: "Archived" }
+  ];
+</script>
+
+<OptionsSelect
+  {options: statuses}
+  bind:value={status}
+  variant="outlined"
+  disableOptions={["ARCHIVED"]}
+  hideOptions={["CANCELLED"]}
+  mandatory
+/>
+```
+
+### Quick filter with custom function
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+
+  let sku = $state<string | null>(null);
+  const products = [
+    { sku: "LAPTOP-001", name: "Laptop",     category: "Electronics" },
+    { sku: "PHONE-002",  name: "Smartphone", category: "Electronics" },
+    { sku: "SHIRT-003",  name: "T-Shirt",    category: "Clothing" },
+    { sku: "PANTS-004",  name: "Jeans",      category: "Clothing" }
+  ];
+
+  // Match against name, sku, or category
+  const filter = (op: any, keyword: string) =>
+    !keyword || [op.name, op.sku, op.category].some(v => v.toLowerCase().includes(keyword.toLowerCase()));
+</script>
+
+<OptionsSelect
+  {options: products}
+  keyField="sku"
+  textField="name"
+  bind:value={sku}
+  filterFunction={filter}
+  noResultsText="No matching products"
+/>
+```
+
+### Cascading two pickers
+
+When one picker's selection drives another's option list, gate the downstream picker with `disabled` until the upstream has a value:
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/uniface-element/OptionsSelect";
+
+  let category = $state<string | null>(null);
+  let product  = $state<string | null>(null);
+
+  const categories = [
+    { id: "electronics", name: "Electronics" },
+    { id: "clothing",    name: "Clothing" }
+  ];
+
+  // Re-computed whenever category changes
+  let products = $derived(
+    category === "electronics"
+      ? [{ sku: "E001", name: "Laptop" }, { sku: "E002", name: "Smartphone" }]
+      : category === "clothing"
+        ? [{ sku: "C001", name: "T-Shirt" }, { sku: "C002", name: "Jeans" }]
+        : []
+  );
+
+  // Reset product when category changes
+  $effect(() => {
+    category; // track
+    product = null;
+  });
+</script>
+
+<OptionsSelect
+  {options: categories}
+  keyField="id"
+  textField="name"
+  bind:value={category}
+  placeholder="Select category"
+/>
+
+<OptionsSelect
+  {options: products}
+  keyField="sku"
+  textField="name"
+  bind:value={product}
+  placeholder={category ? "Select product" : "Select category first"}
+  disabled={!category}
+/>
+```
+
+## Styling
+
+Two layers of CSS apply to the dropdown:
+
+1. **Popover chrome** — the floating panel itself. Styled by `uniface-options-popover.scss` and the `Popover` component.
+2. **Option rows** — each `<div class="option-item">` inside the popover.
+
+Both layers read tokens from `uniface-root.scss`. The tokens **exist in light + dark** blocks, so dark mode works automatically.
+
+### Token reference
+
+| Token | Light default | Dark default | Used for |
+|-------|--------------|--------------|----------|
+| `--uniface-popover-layer-color-surface` | `var(--uniface-color-surface)` | `#262626` | Popover background. |
+| `--uniface-popover-layer-color` | `#1f2937` | `#e5e7eb` | Popover text color. |
+| `--uniface-popover-layer-color-border` | `#e5e7eb` | `rgba(255,255,255,0.08)` | Popover border. |
+| `--uniface-popover-layer-shadow` | `0 4px 6px -1px rgba(0,0,0,.05), 0 10px 15px -3px rgba(0,0,0,.08)` | `0 4px 12px rgba(0,0,0,.5), 0 16px 32px rgba(0,0,0,.4)` | Popover box-shadow. |
+| `--uniface-popover-item-color-surface-hover` | `#f3f4f6` | `rgba(255,255,255,0.08)` | Option row hover background. |
+| `--uniface-popover-item-color-hover` | `#111827` | `#ffffff` | Option row hover text color. |
+| `--uniface-popover-item-color-surface-active` | `#eff6ff` | `rgba(59,130,246,0.16)` | Option row `:active` background. |
+| `--uniface-popover-item-color-active` | `#2563eb` | `#60a5fa` | Option row `:active` text color. |
+| `--uniface-option-item-margin` | `6px 8px` | *(inherits)* | Option row padding. |
+
+### Customizing
+
+```css
+/* Tighten option rows app-wide */
+:root {
+  --uniface-option-item-margin: 4px 6px;
+  --uniface-popover-item-color-surface-hover: #eef2ff;
+  --uniface-popover-item-color-hover: #4338ca;
+}
+
+/* Define the (currently undefined) disabled token */
+:root {
+  --uniface-disabled-color: #94a3b8;
+}
+
+/* Per-instance theme: pass theme="brand" */
+[data-theme="brand"] .uniface-popover .contents {
+  --uniface-popover-layer-color-surface: #1e1b4b;
+  --uniface-popover-layer-color: #e0e7ff;
+}
+```
+
+## Behavior Notes
+
+### Focus + blur lifecycle
+
+- Clicking the input opens the popup and fires `onfocus`.
+- Selecting an item closes the popup and **returns focus to the input** — `onblur` does not fire yet.
+- Clicking outside, pressing Escape, or Backspace+Delete clears the value and closes the popup; if focus has truly left the editor, `onblur` fires (delayed ~50 ms to distinguish "selection click" from "lost focus").
+- Tab is intercepted while the popup is open so focus stays inside the editor.
+
+### Read-only / disabled rendering
+
+Both render a plain `<input readonly>` with the display text. The clear (×) button, dropdown arrow, and popup are all suppressed. `mandatory` has no effect in these modes.
+
+### `emptyText` vs `placeholder`
+
+- `placeholder` is the input's native placeholder attribute — shown when `value` is empty.
+- `emptyText` overrides the **display text** when the current `value` doesn't match any option in `options`.
+
+## Accessibility
+
+- The popup is rendered via `Popover` using a portal to `document.body`; scroll and resize listeners keep it aligned.
+- Outside-click closes the popup (registered with `useCapture: true`).
+- Keyboard: Backspace/Delete clears, Escape closes, Tab is contained while open.
+- For full ARIA combobox semantics, wrap with a `<label>` / `FormField` and provide `error` text — the underlying `FormEditor` wires `aria-invalid` from `error`.
+
+## Related Components
+
+- [OptionsMultiSelect](../options_multi_select/README.md) — multi-select variant.
+- [CascadeOptionSelect](../cascade_options_select/README.md) — tree-shaped cascading picker.
+- [LookupEditor](../lookup_editor/README.md) — lazy-loading picker for large / remote option lists.