@ticatec/topside-elements 1.0.0

package/dist/form/options_select/README_CN.md

@@ -0,0 +1,368 @@
+# OptionsSelect
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `disableOptions`, `mandatory` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+单选下拉选择器。用户不输入文字 —— 点击、（可选地）过滤、从列表中选一项。基于共享的 `CommonPicker` + `Popover` 渲染，所以继承本库所有下拉组件共用的表面色 / 阴影 / 边框 token。
+
+> 这是**单选**组件。多选见 [OptionsMultiSelect](../options_multi_select/README_CN.md)；树形级联见 [CascadeOptionSelect](../cascade_options_select/README_CN.md)。
+
+## 特性
+
+- **单选**：`value` 绑定到选项的 key 字段（默认 `code`）。
+- **自定义字段映射**：`keyField` / `textField` —— 你的选项对象不必是 `{code, text}` 形状。
+- **隐藏或禁用单个选项**：通过 `hideOptions` / `disabledOptions`。
+- **可选的快速过滤** —— 传入 `filterFunction`，下拉框顶部就会长出一个搜索框。**不再有 `quickFilter` 布尔开关**；`filterFunction` 的存在与否就是开关。
+- **自定义项渲染**：`itemRender` —— 传 `{component, props}`，子组件接收 `item` / `disabled` / `onclick`。
+- **只读与禁用模式** —— 取代旧的 `displayMode` 枚举。
+- **必填模式** —— 隐藏清空（×）按钮，用户无法把字段清回空。
+- **紧凑模式** —— 适用于表格单元格和密集表单。
+- **`error` / `tooltip` / `theme`** —— 与 form-editor 家族其它组件共享的透传属性。
+- **键盘支持**：Backspace / Delete 清空、Escape 关闭、弹窗打开时 Tab 被锁定在编辑器内。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import OptionsSelect from "@ticatec/topside-elements/OptionsSelect";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/topside-elements/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="选择一门语言" />
+```
+
+## 属性（Props）
+
+`OptionsSelect` 继承自 `PickerProps`，因此所有通用编辑器属性（`variant`、`compact`、`disabled`、`readonly`、`clearable={false}`、`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` 在 `options` 中找不到对应项时的显示文本。适用于"已保存的值已从列表移除"这类场景。 |
+| `disabledOptions` | `Array<string>` | `[]` | 要渲染但禁用（变灰）的选项 key 列表。 |
+| `hideOptions` | `Array<string>` | `[]` | 完全不渲染的选项 key 列表。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉风格。 |
+| `compact` | `boolean` | `false` | 紧凑布局，用于表格单元格和行内表单。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— 渲染只读输入框，无弹窗。 |
+| `readonly` | `boolean` | `false` | 只读 —— 视觉同 disabled，但语义是"查看，不可编辑"。 |
+| `clearable` | `boolean` | `true` | 是否允许清空（显示清空按钮）。旧名 `mandatory` 语义相反（`mandatory={true}` = `clearable={false}`），5.1.0 已移除。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本。触发编辑器的 error 状态（通常是红色边框）。 |
+| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
+| `theme` | `string` | — | 渲染为弹窗根的 `data-theme`，便于作用域样式覆盖。 |
+| `menu$height` | `number` | `0` | 下拉的固定高度（px）。`0` 表示 `auto`（CSS 默认 `max-height: 30vh` 生效）。 |
+| `itemRender` | `{ component: any; props?: Record<string, any> } \| undefined` | — | 自定义每项渲染的 Svelte 组件。子组件接收 `item`、`disabled`、`onclick`。 |
+| `filterFunction` | `((option: any, keyword: string) => boolean) \| undefined` | — | **传入后**，下拉顶部会出现搜索框，并对每个选项调用此函数过滤。不传则展示平铺列表。 |
+| `noResultsText` | `string` | `"No results found"` | 过滤后列表为空时显示的文本。 |
+| `onchange` | `(value: any) => void` | — | 用户选中时触发**一次**，参数是**完整的选项对象**（不是 key）。父组件编程式修改 `value` 不会触发 `onchange`。 |
+| `onfocus` | `(e: FocusEvent) => void` | — | 输入框获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | — | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onchange` | `(value: any) => void` | 用户选中时触发，参数是**完整的选项对象**（不是 key）。 |
+| `onfocus` | `(e: FocusEvent) => void` | 输入框获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | 输入框失焦。在弹窗关闭且焦点真正离开编辑器后触发。 |
+
+## 方法
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `focus()` | `() => void` | 让输入框获取焦点。内部延迟 50 ms，等弹窗挂载完。 |
+
+通过 `bind:this` 使用：
+
+```svelte
+<script>
+  let picker;
+</script>
+
+<OptionsSelect bind:this={picker} {options} bind:value />
+<button onclick={() => picker.focus()}>聚焦</button>
+```
+
+## `itemRender` —— 自定义项渲染
+
+传 `{component, props?}`。子组件接收：
+
+| 属性 | 来源 |
+|------|------|
+| `item` | 当前选项对象。 |
+| `disabled` | 选项 key 在 `disabledOptions` 中时为 `true`。 |
+| `onclick` | 内部处理函数 —— 点击时调用它来选中这一项。 |
+| `...props` | 你放在 `itemRender.props` 里的任何属性都会展开到组件上。 |
+
+```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
+<!-- 调用方 -->
+<script lang="ts">
+  import OptionsSelect from "@ticatec/topside-elements/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 } }}
+/>
+```
+
+## 示例
+
+### 带变更回调的货币选择
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/topside-elements/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="选择货币"
+  onchange={handleChange}
+/>
+```
+
+### 禁用 + 隐藏选项
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/topside-elements/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"
+  disabledOptions={["ARCHIVED"]}
+  hideOptions={["CANCELLED"]}
+  mandatory
+/>
+```
+
+### 带自定义过滤的快速搜索
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/topside-elements/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" }
+  ];
+
+  // 命中 name / sku / 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="没有匹配的商品"
+/>
+```
+
+### 两个选择器联动
+
+当下游选择器的选项列表依赖上游时，在上游有值之前用 `disabled` 拦住下游：
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from "@ticatec/topside-elements/OptionsSelect";
+
+  let category = $state<string | null>(null);
+  let product  = $state<string | null>(null);
+
+  const categories = [
+    { id: "electronics", name: "Electronics" },
+    { id: "clothing",    name: "Clothing" }
+  ];
+
+  // 随 category 变化重新计算
+  let products = $derived(
+    category === "electronics"
+      ? [{ sku: "E001", name: "Laptop" }, { sku: "E002", name: "Smartphone" }]
+      : category === "clothing"
+        ? [{ sku: "C001", name: "T-Shirt" }, { sku: "C002", name: "Jeans" }]
+        : []
+  );
+
+  // category 变了就把 product 清空
+  $effect(() => {
+    category; // 跟踪
+    product = null;
+  });
+</script>
+
+<OptionsSelect
+  {options: categories}
+  keyField="id"
+  textField="name"
+  bind:value={category}
+  placeholder="选择分类"
+/>
+
+<OptionsSelect
+  {options: products}
+  keyField="sku"
+  textField="name"
+  bind:value={product}
+  placeholder={category ? "选择商品" : "请先选择分类"}
+  disabled={!category}
+/>
+```
+
+## 样式
+
+下拉有两层 CSS：
+
+1. **弹出层外壳** —— 浮动面板本身。由 `topside-options-popover.scss` 和 `Popover` 组件样式化。
+2. **选项行** —— 弹出层内部每个 `<div class="option-item">`。
+
+两层都读取 `topside-root.scss` 中的 token。token 在浅色与深色块里**都有定义**，深色模式自动生效。
+
+### Token 参考
+
+| Token | Light 默认 | Dark 默认 | 用途 |
+|-------|-----------|----------|------|
+| `--topside-popover-layer-color-surface` | `var(--topside-color-surface)` | `#262626` | 弹出层背景。 |
+| `--topside-popover-layer-color` | `#1f2937` | `#e5e7eb` | 弹出层文本色。 |
+| `--topside-popover-layer-color-border` | `#e5e7eb` | `rgba(255,255,255,0.08)` | 弹出层边框。 |
+| `--topside-popover-item-color-surface-hover` | `#f3f4f6` | `rgba(255,255,255,0.08)` | 选项行 hover 背景。 |
+| `--topside-popover-item-color-hover` | `#111827` | `#ffffff` | 选项行 hover 文本色。 |
+| `--topside-option-item-margin` | `6px 8px` | *(继承)* | 选项行 padding。 |
+
+### 自定义
+
+```css
+/* 全局收紧选项行 */
+:root {
+  --topside-option-item-margin: 4px 6px;
+  --topside-popover-item-color-surface-hover: #eef2ff;
+  --topside-popover-item-color-hover: #4338ca;
+}
+
+/* 定义 disabled token */
+:root {
+  --topside-disabled-color: #94a3b8;
+}
+
+/* 按实例主题化：传 theme="brand" */
+[data-theme="brand"] .topside-popover .contents {
+  --topside-popover-layer-color-surface: #1e1b4b;
+  --topside-popover-layer-color: #e0e7ff;
+}
+```
+
+## 行为说明
+
+### 获焦 / 失焦生命周期
+
+- 点击输入框打开弹窗，触发 `onfocus`。
+- 选中一项会关闭弹窗并**把焦点还给输入框** —— 此时不会触发 `onblur`。
+- 点击外部、按 Escape、Backspace+Delete 清空都会关闭弹窗；如果焦点确实离开了编辑器，触发 `onblur`（延迟约 50 ms）。
+- 弹窗打开时 Tab 被拦截，焦点留在编辑器内。
+
+### 只读 / 禁用渲染
+
+两者都渲染一个普通 `<input readonly>`，显示文本。清空（×）按钮、下拉箭头、弹窗都不渲染。
+
+### `emptyText` 与 `placeholder`
+
+- `placeholder` 是输入框的原生 placeholder 属性 —— `value` 为空时显示。
+- `emptyText` 覆盖**显示文本**，用于当前 `value` 在 `options` 中找不到对应项的场景。
+
+## 无障碍
+
+- 弹窗通过 `Popover` 用 portal 渲染到 `document.body`；scroll 和 resize 监听保持对齐。
+- 外部点击关闭弹窗（用 `useCapture: true` 注册）。
+- 键盘：Backspace/Delete 清空，Escape 关闭，弹窗打开时 Tab 被锁。
+- 完整的 ARIA combobox 语义需要外层 `<label>` / `FormField` 配合 `error` 文本。
+
+## 相关组件
+
+- [OptionsMultiSelect](../options_multi_select/README_CN.md) —— 多选变体。
+- [CascadeOptionSelect](../cascade_options_select/README_CN.md) —— 树形级联选择。
+- [LookupEditor](../lookup_editor/README_CN.md) —— 大列表 / 远程数据的懒加载选择器。

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

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

package/dist/form/options_select/index.js

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

package/dist/form/prompts_text_editor/PromptsTextEditor.svelte

@@ -0,0 +1,96 @@
+<script lang="ts">
+    import CommonEditor from "../common_editor/CommonEditor.svelte";
+    import Popover from "../../overlay/common/Popover.svelte";
+    import {eventFilter} from "../../utils/prefixFilter";
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+    import CommonPopupEditor from "../common_editor/CommonPopupEditor.svelte";
+
+    interface Props extends CommonFieldProps {
+        value?: string;
+        prefix?: string;
+        suffix?: string;
+        /** 候选提示词列表 */
+        options?: Array<string>;
+        menu$height?: number;
+
+        [key: `input\$${string}`]: any;
+    }
+
+    let {
+        variant,
+        theme,
+        compact = false,
+        disabled = false,
+        readonly = false,
+        style,
+        value = $bindable(),
+        prefix,
+        suffix,
+        tooltip,
+        placeholder,
+        options = [],
+        menu$height = 0,
+        onchange,
+        ...restProps
+    }: Props = $props();
+
+    let editorRef: any;
+    let editor: HTMLInputElement;
+
+    export function focus() {
+        editor?.focus();
+    }
+
+    const eventHandlers = $derived(eventFilter(restProps));
+
+    const handleHintClick = (item: string) => (e: MouseEvent) => {
+        value = item;
+        // 选中候选词即提交；手输的内容由 input 原生 change（失焦 / 回车）提交
+        onchange?.(item);
+        editor?.focus();
+        editorRef?.close();
+        e.stopPropagation();
+        e.preventDefault();
+    };
+
+    const handleHintKeyDown = (item: string) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleHintClick(item)(e as unknown as MouseEvent);
+        }
+    };
+
+
+
+    const clear = () => {
+        value = undefined;
+        onchange?.(undefined);
+    }
+
+
+    const mh = $derived(`height: ${menu$height > 0 ? menu$height + 'px' : 'auto'}`);
+
+</script>
+
+
+<CommonPopupEditor bind:this={editorRef} {variant} {theme} {compact} {style} {tooltip} {disabled} {readonly} {prefix} autoFit
+                   {suffix} {clear} textValue={value}>
+    <input bind:this={editor} bind:value {disabled} {readonly} {placeholder} {...eventHandlers}
+           onchange={() => onchange?.(value)}/>
+
+    {#snippet popup()}
+        <div class="options-popover" style={mh} role="listbox">
+            {#each options as word}
+                <div
+                        class="option-item"
+                        style="padding-left: 12px; padding-right: 12px"
+                        onclick={handleHintClick(word)}
+                        onkeydown={handleHintKeyDown(word)}
+                        role="option" tabindex="0" aria-selected={word === value}
+                >
+                    <span>{word}</span>
+                </div>
+            {/each}
+        </div>
+    {/snippet}
+</CommonPopupEditor>

package/dist/form/prompts_text_editor/PromptsTextEditor.svelte.d.ts

@@ -0,0 +1,15 @@
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+interface Props extends CommonFieldProps {
+    value?: string;
+    prefix?: string;
+    suffix?: string;
+    /** 候选提示词列表 */
+    options?: Array<string>;
+    menu$height?: number;
+    [key: `input\$${string}`]: any;
+}
+declare const PromptsTextEditor: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type PromptsTextEditor = ReturnType<typeof PromptsTextEditor>;
+export default PromptsTextEditor;