@ticatec/topside-elements 1.0.0

package/dist/form/input_options_select/InputOptionsSelect.svelte

@@ -0,0 +1,257 @@
+<script lang="ts">
+    import loadingGif from "../../assets/loading.gif";
+    import CommonPicker from "../common_editor/CommonPicker.svelte";
+    import type CommonPickerProps from "../common_editor/CommonPickerProps";
+    import type {ListLazyLoader, RetrieveOptionText} from "../../types";
+
+    interface Props extends CommonPickerProps {
+        text?: string;
+        value?: any;
+        keyField?: string;
+        textField?: string;
+        retrieveText?: RetrieveOptionText;
+        /** 是否显示选项 code */
+        showCode?: boolean;
+        menu$height?: number;
+        itemRender?: any;
+        lazyLoader?: ListLazyLoader;
+        oninput?: (value: string) => void;
+    }
+
+    let {
+        variant,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        clearable,
+        error,
+        tooltip,
+        theme,
+        style,
+        placeholder,
+        text,
+        value = $bindable(),
+        keyField = 'code',
+        textField = "text",
+        retrieveText,
+        showCode = false,
+        menu$height = 0,
+        itemRender: ItemRender = undefined,
+        lazyLoader,
+        onchange,
+        onfocus,
+        onblur,
+        oninput,
+    }: Props = $props();
+
+
+    let scrollElement: HTMLElement | undefined = $state(undefined);
+
+    let inputText = $state('');
+    let options = $state<Array<any>>([]);
+    let loading = $state(false);
+    let hasFocus = $state(false);
+    let isOpen = $state(false);
+
+    let idleTime = 0;
+    let interval: ReturnType<typeof setInterval> | undefined;
+    let pageNo = 0;
+    let isBusy = false;
+    let hasMore = false;
+    let loadingController: AbortController | null = null;
+    let composing = false;
+    let isUserTyping = false;
+
+    const mh = $derived(
+        `min-height: 80px; ${menu$height > 0 ? 'height: ' + menu$height + 'px;' : 'max-height: 300px;'} overflow-y: auto;`
+    );
+
+    const getDisplayText = (item: any) =>
+        retrieveText?.(item) ?? item[textField ?? keyField];
+
+    const lazyLoad = async (searchText: string, page: number, isLoadMore = false) => {
+        if (loadingController) {
+            loadingController.abort();
+        }
+        loadingController = new AbortController();
+        const currentController = loadingController;
+
+        loading = true;
+        if (!isLoadMore) {
+            isBusy = true;
+        }
+
+        try {
+            const res = await lazyLoader!(searchText, page);
+            if (currentController.signal.aborted) return;
+
+            options = page === 1 ? res.list : [...options, ...res.list];
+            hasMore = res.hasMore;
+            pageNo = page;
+        } catch (e) {
+            if (currentController.signal.aborted) return;
+            console.error('LazyLoader error:', e);
+            if (page === 1) {
+                options = [];
+                hasMore = false;
+            }
+        } finally {
+            if (!currentController.signal.aborted) {
+                loading = false;
+                isBusy = false;
+                loadingController = null;
+            }
+        }
+    };
+
+    const delayReload = () => {
+        const searchText = inputText;
+
+        if (interval) {
+            clearInterval(interval);
+        }
+        if (loadingController) {
+            loadingController.abort();
+            loadingController = null;
+            loading = false;
+            isBusy = false;
+        }
+
+        options = [];
+        hasMore = false;
+
+        idleTime = 0;
+        interval = setInterval(() => {
+            idleTime += 100;
+            if (idleTime >= 200) {
+                clearInterval(interval);
+                if (searchText && searchText.length > 0) {
+                    lazyLoad(searchText, 1, false);
+                }
+            }
+        }, 100);
+    };
+
+    const handleInputText = (s: string) => {
+        inputText = s;
+        oninput?.(s);
+        if (lazyLoader != null) {
+            delayReload();
+        }
+    };
+
+    const loadMore = () => {
+        if (hasMore && !isBusy) {
+            lazyLoad(inputText, pageNo + 1, true);
+        }
+    };
+
+    const handleScroll = (event: Event) => {
+        const target = event.target as HTMLElement;
+        const {scrollTop, scrollHeight, clientHeight} = target;
+        if (scrollTop + clientHeight >= scrollHeight - 20 && hasMore && !isBusy) {
+            loadMore();
+        }
+    };
+
+    const handleItemClick = (data: any) => () => {
+        isUserTyping = false;
+        const newValue = data[keyField];
+        if (newValue !== value) {
+            value = newValue;
+            onchange?.(data);
+        }
+        text = retrieveText?.(data) ?? data[textField??keyField];
+        //editor?.focus();
+        isOpen = false;
+    };
+
+    const handleItemKeyDown = (data: any) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleItemClick(data)();
+        }
+    };
+
+    const handleInput = (event: Event) => {
+        isUserTyping = true;
+        if (!composing) {
+            value = null;
+            const s = (event.target as HTMLInputElement).value;
+            handleInputText(s);
+        }
+    };
+
+    const oncompositionstart = () => {
+        composing = true;
+    };
+
+    const oncompositionend = (event: CompositionEvent) => {
+        composing = false;
+        value = null;
+        const s = (event.target as HTMLInputElement).value;
+        handleInputText(s);
+    };
+
+    // 清空按钮 / 键盘清空都走这里：统一通知 onchange（与 Lookup / ColorPicker / OptionsMultiSelect 一致）
+    // 选择时 onchange 交回的是选项对象，清空时为 null
+    const clear = () => {
+        const had = value != null;
+        value = null;
+        text = '';
+        inputText = '';
+        if (had) onchange?.(null);
+    };
+
+
+    // Popup visibility follows options/loading state.
+    $effect(() => {
+        isOpen = options.length > 0 || loading;
+    });
+
+</script>
+
+<CommonPicker
+        {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" >
+        {#if loading}
+            <div class="loading-indicator">
+                <img src={loadingGif} alt="loading" width="16" height="16"/>
+            </div>
+        {/if}
+    </div>
+    {#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)}
+                     role="option" tabindex="0" aria-selected={op[keyField] === value}>
+                    {#if ItemRender}
+                        <ItemRender item={op}/>
+                    {:else}
+                        <div style="padding: 6px 8px">
+                            <span>{getDisplayText(op)}</span>
+                        </div>
+                    {/if}
+                </div>
+            {/each}
+        </div>
+    {/snippet}
+</CommonPicker>
+
+<style>
+
+    .loading-indicator {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        right: 8px;
+        display: flex;
+        align-items: center;
+        pointer-events: none;
+    }
+
+</style>

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

@@ -0,0 +1,18 @@
+import type CommonPickerProps from "../common_editor/CommonPickerProps";
+import type { ListLazyLoader, RetrieveOptionText } from "../../types";
+interface Props extends CommonPickerProps {
+    text?: string;
+    value?: any;
+    keyField?: string;
+    textField?: string;
+    retrieveText?: RetrieveOptionText;
+    /** 是否显示选项 code */
+    showCode?: boolean;
+    menu$height?: number;
+    itemRender?: any;
+    lazyLoader?: ListLazyLoader;
+    oninput?: (value: string) => void;
+}
+declare const InputOptionsSelect: import("svelte").Component<Props, {}, "value">;
+type InputOptionsSelect = ReturnType<typeof InputOptionsSelect>;
+export default InputOptionsSelect;

package/dist/form/input_options_select/README.md

@@ -0,0 +1,73 @@
+# InputOptionsSelect
+
+> **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).
+
+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
+
+- **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/topside-elements/InputOptionsSelect";
+import type {ListLazyLoader} from "@ticatec/topside-elements/types";
+```
+
+## Basic usage
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/topside-elements/InputOptionsSelect";
+  import type {ListLazyLoader} from "@ticatec/topside-elements/types";
+
+  let value = $state<string | null>(null);
+  let text = $state('');
+
+  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 bind:value {text} lazyLoader={loadCustomers} placeholder="Type to search customers"
+                    onchange={(item) => text = item?.text ?? ''}/>
+```
+
+## Props
+
+Props inherited from `CommonPickerProps` are not repeated here.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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`.

package/dist/form/input_options_select/README_CN.md

@@ -0,0 +1,73 @@
+# InputOptionsSelect
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `mandatory` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+可输入的远程检索选择器：用户在输入框里键入关键字，组件通过 `lazyLoader` 分页拉取候选项并在下方面板展示，点击某一项后把它的 key 写入 `value`。适合候选数据量大、必须走服务端检索的场景（客户、产品、地址快速定位）。
+
+> 与 `OptionsSelect` 的区别：`OptionsSelect` 接收完整的 `options` 数组做本地筛选；`InputOptionsSelect` **没有** `options` 属性，所有候选都来自 `lazyLoader`。
+
+## 特性
+
+- **输入即检索**：停止输入 200ms 后调用 `lazyLoader(text, 1)`；继续输入会中止上一次未完成的请求。
+- **滚动分页**：面板滚到底部时调用 `lazyLoader(text, pageNo + 1)`，直到返回 `hasMore: false`。
+- **`value` 是选项的 key**：由 `keyField` 决定；显示文本由 `textField` 或 `retrieveText` 决定。
+- **自定义项渲染**：`itemRender` 传入一个接收 `item` 的 Svelte 组件。
+- **不可清空模式**：`clearable={false}` 隐藏清空按钮。
+- **共享的表单字段属性**：继承 `CommonPickerProps`（`variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`）。
+
+## 引入
+
+```typescript
+import InputOptionsSelect from "@ticatec/topside-elements/InputOptionsSelect";
+import type {ListLazyLoader} from "@ticatec/topside-elements/types";
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from "@ticatec/topside-elements/InputOptionsSelect";
+  import type {ListLazyLoader} from "@ticatec/topside-elements/types";
+
+  let value = $state<string | null>(null);
+  let text = $state('');
+
+  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 bind:value {text} lazyLoader={loadCustomers} placeholder="输入客户名称检索"
+                    onchange={(item) => text = item?.text ?? ''}/>
+```
+
+## 属性（Props）
+
+继承 `CommonPickerProps` 的属性不再重复列出。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `any`（可绑定） | — | 选中项的 key（`item[keyField]`）。用户重新输入时会被置为 `null`。 |
+| `text` | `string` | — | 输入框当前显示的文本。组件在选中项后会更新它；初始化时由调用方传入已选项的显示文本。 |
+| `lazyLoader` | `ListLazyLoader` | — | `(text, pageNo) => Promise<{list, hasMore}>`。**必需**，否则输入不会触发任何检索。 |
+| `keyField` | `string` | `"code"` | 作为 `value` 的字段。 |
+| `textField` | `string` | `"text"` | 默认显示文本字段。 |
+| `retrieveText` | `(item) => string` | — | 自定义显示文本；返回值优先于 `textField`。 |
+| `itemRender` | Svelte 组件 | — | 自定义每一项的渲染，组件接收 `item` 属性。 |
+| `menu$height` | `number` | `0` | 面板固定高度（px）；`0` 表示自适应，最高 300px。 |
+| `clearable` | `boolean` | `true` | 是否显示清空按钮；`false` 时用户不能把值清空。 |
+| `onchange` | `(item: any) => void` | — | 用户点击选中某一项时触发，参数是**完整的选项对象**。清空或重新输入不会触发。 |
+
+## 行为说明
+
+- 只有输入非空文本才会检索；清空输入不会调用 `lazyLoader`。
+- 面板在 `options.length > 0 || loading` 时打开，检索结果为空时自动关闭。
+- `readonly` / `disabled` 时输入框不可编辑，也不会检索。
+
+## 相关组件
+
+- `OptionsSelect`：本地选项数组的单选下拉。
+- `LookupEditor`：通过弹出查找界面选择复杂对象。
+- `ListBox`：同样支持 `lazyLoader` 的列表框。

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/input_options_select/index.js

@@ -0,0 +1,2 @@
+import InputOptionsSelect from "./InputOptionsSelect.svelte";
+export default InputOptionsSelect;

package/dist/form/lookup_editor/LookupEditor.svelte

@@ -0,0 +1,85 @@
+<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 {
+        /** 是否允许清空（显示清空按钮），默认 true */
+        clearable?: boolean;
+        value?: any;
+        text?: string;
+        onaction?: () => void;
+        leadingIcon?: Snippet;
+    }
+
+    let {
+        leadingIcon,
+        theme,
+        style,
+        tooltip,
+        error,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        clearable = true,
+        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?.();
+        }
+    };
+
+    const handleActionKeyDown = (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleActionClick();
+        }
+    };
+
+</script>
+
+<CommonEditor {theme} {clear} {style} {tooltip} {error} {readonly} {disabled} {compact} {variant} {leadingIcon} textValue={text??''} {clearable}>
+    <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="button" tabindex="-1" aria-label="Lookup"
+               onmousedown={(event: MouseEvent)=> {event.preventDefault()}}
+               onclick={handleActionClick} onkeydown={handleActionKeyDown}></i>
+        {/if}
+    {/snippet}
+</CommonEditor>
+
+<style>
+    .action_icon {
+        cursor: pointer;
+    }
+
+    .action_icon:active {
+        position: relative;
+        top: 1px;
+    }
+</style>

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

@@ -0,0 +1,16 @@
+import type { Snippet } from "svelte";
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+interface Props extends CommonFieldProps {
+    /** 是否允许清空（显示清空按钮），默认 true */
+    clearable?: 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;