@ticatec/topside-elements 1.0.0

package/dist/form/options_multi_select/OptionsMultiSelect.svelte.d.ts

@@ -0,0 +1,21 @@
+import type PickerProps from "../common_editor/CommonPickerProps";
+import type { KeyboardEvents } from "../events";
+interface Props extends PickerProps, KeyboardEvents {
+    menu$height?: number;
+    value?: string;
+    delimiter?: string;
+    options: Array<any>;
+    keyField?: string;
+    textField?: string;
+    emptyText?: string;
+    /** 要渲染但禁用的选项 key 列表 */
+    disabledOptions?: Array<string>;
+    hideOptions?: Array<string>;
+    tagColor?: string;
+    tagVariant?: 'borderless' | 'border' | 'round';
+}
+declare const OptionsMultiSelect: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type OptionsMultiSelect = ReturnType<typeof OptionsMultiSelect>;
+export default OptionsMultiSelect;

package/dist/form/options_multi_select/README.md

@@ -0,0 +1,251 @@
+# OptionsMultiSelect
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `disableOptions` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A multi-selection dropdown picker. Selected items render inline as removable tags; the dropdown shows a checkbox per option. The bound `value` is a **delimited string** (default `;`), not an array — convenient for storing straight into a single text column.
+
+> This is the **multi-select** picker. For single-select see [OptionsSelect](../options_select/README.md); for cascading (tree-shaped) data see [CascadeOptionSelect](../cascade_options_select/README.md).
+
+## Features
+
+- **Multi-select** with checkbox dropdown — click the checkbox *or* anywhere on the row to toggle.
+- **Tag display** of the current selection, each with an inline × to remove individually.
+- **Clear-all (×)** appears inline next to the tags whenever at least one item is selected.
+- **Delimited-string `value`** — `"A;B;C"`-style. Set `delimiter` to use a different separator (`,` / `|` / etc.).
+- **`onchange` fires the array** of selected keys, regardless of the storage delimiter. So you always get a clean `Array<string>` to work with.
+- **Custom field mapping** via `keyField` / `textField`.
+- **Hide or disable individual options** via `hideOptions` / `disabledOptions`.
+- **Tag styling** — `tagVariant` (`borderless` / `border` / `round`) and `tagColor` (`"0"` … `"12"`, mapped to the `--topside-tag-g{n}-color` tokens).
+- **Compact mode** — switches tags to their small size variant for table cells and dense forms.
+- **Read-only / disabled** modes — tags render without the × buttons; dropdown is suppressed.
+- **Shared form-editor props** — `variant`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur`.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  // value is a delimited string, e.g. "JS;TS;PY"
+  let value = $state("");
+
+  const options = [
+    { code: "JS", text: "JavaScript" },
+    { code: "TS", text: "TypeScript" },
+    { code: "PY", text: "Python" },
+    { code: "GO", text: "Go" }
+  ];
+
+  function handleChange(keys: string[]) {
+    console.log("selected keys:", keys);
+  }
+</script>
+
+<OptionsMultiSelect {options} bind:value onchange={handleChange} placeholder="Pick languages" />
+```
+
+## Props
+
+`OptionsMultiSelect` extends `PickerProps`, so it inherits `variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`, `onfocus` / `onblur` / `onchange` automatically.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` (bindable) | `""` | The selected keys joined by `delimiter`. Empty string = nothing selected. |
+| `options` | `Array<any>` | — | Full option list. |
+| `keyField` | `string` | `"code"` | Property used as the option's identity. |
+| `textField` | `string` | `"text"` | Property used as the option's display text. |
+| `delimiter` | `string` | `";"` | Separator for joining keys in `value`. |
+| `placeholder` | `string` | — | Shown when nothing is selected. |
+| `emptyText` | `string` | — | Shown when nothing is selected, in place of the placeholder. Useful for "All items" or "No filter" labels in read-only mode. |
+| `disabledOptions` | `Array<string>` | `[]` | Keys rendered but unclickable (dimmed checkbox). |
+| `hideOptions` | `Array<string>` | `[]` | Keys not rendered at all. |
+| `tagColor` | `string` | — | Maps to the `--topside-tag-g{n}-color` token family. Accepts `"0"` … `"12"`. |
+| `tagVariant` | `'borderless' \| 'border' \| 'round'` | `'border'` | Visual style of each tag. |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Editor variant. |
+| `compact` | `boolean` | `false` | Renders tags in small size (`--topside-tag-height-sm`). |
+| `disabled` | `boolean` | `false` | Fully disabled — no × on tags, no dropdown. |
+| `readonly` | `boolean` | `false` | Read-only — same visual as disabled, "view-only" semantics. |
+| `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 popover for scoped CSS. |
+| `menu$height` | `number` | `0` | Fixed dropdown height in px. `0` means `auto`. |
+| `onchange` | `(keys: string[]) => void` | — | Fires whenever the selection changes (add / remove / clear). **Always receives the array of selected keys**, not the delimited string. |
+| `onfocus` | `(e: FocusEvent) => void` | — | Editor focus. |
+| `onblur` | `(e: FocusEvent) => void` | — | Editor blur, after the popup has closed and focus truly left. |
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `onchange` | `(keys: string[]) => void` | Fires whenever the selection changes. **Always receives the array of selected keys**, not the delimited string. |
+| `onfocus` | `(e: FocusEvent) => void` | Editor focus. |
+| `onblur` | `(e: FocusEvent) => void` | Editor blur, after the popup has closed and focus truly left. |
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `focus()` | `() => void` | Moves focus to the editor. Internally deferred 50 ms so the popup can mount. |
+
+```svelte
+<script>
+  let picker;
+</script>
+
+<OptionsMultiSelect bind:this={picker} {options} bind:value />
+<button onclick={() => picker.focus()}>Focus</button>
+```
+
+## Tag Color Reference
+
+| `tagColor` | Default token | Hue |
+|------------|---------------|-----|
+| `"0"` | `--topside-tag-g0-color` | Neutral gray |
+| `"1"` | `--topside-tag-g1-color` | Blue |
+| `"2"` | `--topside-tag-g2-color` | Green |
+| `"3"` | `--topside-tag-g3-color` | Red |
+| `"4"` | `--topside-tag-g4-color` | Yellow / amber |
+| `"5"` | `--topside-tag-g5-color` | Pink |
+| `"6"` | `--topside-tag-g6-color` | Cyan |
+| `"7"` | `--topside-tag-g7-color` | Orange-red |
+| `"8"` | `--topside-tag-g8-color` | Orange |
+| `"9"` | `--topside-tag-g9-color` | Indigo |
+| `"10"` | `--topside-tag-g10-color` | Purple |
+| `"11"` | `--topside-tag-g11-color` | Lime |
+| `"12"` | `--topside-tag-g12-color` | Slate (with paired `*-bg` / `*-border`) |
+
+## Examples
+
+### Custom delimiter
+
+Use `,` instead of `;` for CSV-style storage:
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  let csv = $state("JS,TS");
+  const options = [
+    { code: "JS", text: "JavaScript" },
+    { code: "TS", text: "TypeScript" },
+    { code: "PY", text: "Python" }
+  ];
+</script>
+
+<OptionsMultiSelect {options} bind:value={csv} delimiter="," />
+```
+
+### Hide / disable options
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  let value = $state("");
+  const options = [
+    { code: "DRAFT",     text: "Draft" },
+    { code: "REVIEW",    text: "In Review" },
+    { code: "PUBLISHED", text: "Published" },
+    { code: "ARCHIVED",  text: "Archived" }
+  ];
+</script>
+
+<OptionsMultiSelect
+  {options}
+  bind:value
+  disabledOptions={["ARCHIVED"]}
+  hideOptions={["DRAFT"]}
+  placeholder="Visible statuses"
+/>
+```
+
+### Colored round tags
+
+```svelte
+<OptionsMultiSelect
+  {options}
+  bind:value
+  tagColor="3"
+  tagVariant="round"
+  variant="outlined"
+/>
+```
+
+### Compact in a table cell
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  const roles = [
+    { code: "READ",  text: "Read" },
+    { code: "WRITE", text: "Write" },
+    { code: "ADMIN", text: "Admin" }
+  ];
+
+  let users = $state([
+    { id: 1, name: "Alice", roles: "READ;WRITE" },
+    { id: 2, name: "Bob",   roles: "READ" }
+  ]);
+</script>
+
+<table>
+  <thead><tr><th>User</th><th>Roles</th></tr></thead>
+  <tbody>
+    {#each users as user (user.id)}
+      <tr>
+        <td>{user.name}</td>
+        <td>
+          <OptionsMultiSelect
+            {options: roles}
+            bind:value={user.roles}
+            compact
+            variant="outlined"
+          />
+        </td>
+      </tr>
+    {/each}
+  </tbody>
+</table>
+```
+
+## Behavior Notes
+
+### How `value` and `onchange` stay in sync
+
+| Action | Effect |
+|--------|--------|
+| User checks a checkbox or clicks a row | `value` updates to the new delimited string; `onchange` fires with the new `Array<string>`. |
+| User clicks the × on a tag | `value` shrinks; `onchange` fires with the shorter array. |
+| User clicks the clear-all × | `value` becomes `""`; `onchange` fires with `[]`. |
+| Parent writes to `value` externally | The internal `selectedList` resyncs from the new string; tags re-render. **`onchange` does NOT fire** — the parent is the source of truth, no echo. |
+
+### Read-only / disabled rendering
+
+Both modes hide the clear-all × and per-tag ×, hide the dropdown arrow, and suppress popup open. The difference is semantic: `readonly` is "view, don't edit" (still accessible to AT), `disabled` is "grey out, ignore" (typically dimmed).
+
+## Accessibility
+
+- Each option row contains a real `<input type="checkbox">` via the `<CheckBox>` component — keyboard and AT users get standard checkbox semantics.
+- The dropdown is rendered via `Popover` through a portal; scroll/resize listeners keep it aligned.
+- Outside-click closes the popup (registered with `useCapture: true`).
+- For form-level ARIA, wrap with `<label>` / `FormField` and supply `error` text.
+
+## Related Components
+
+- [OptionsSelect](../options_select/README.md) — single-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.

package/dist/form/options_multi_select/README_CN.md

@@ -0,0 +1,242 @@
+# OptionsMultiSelect
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `disableOptions` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+多选下拉选择器。选中的项以内置可删除 tag 的形式行内展示；下拉里每个选项是一个 checkbox。绑定的 `value` 是**分隔符拼接的字符串**（默认 `;`），不是数组 —— 适合直接存进一个文本列。
+
+> 这是**多选**组件。单选见 [OptionsSelect](../options_select/README_CN.md)；树形级联见 [CascadeOptionSelect](../cascade_options_select/README_CN.md)。
+
+## 特性
+
+- **多选** + checkbox 下拉 —— 点 checkbox 或者点行任意位置都能切换。
+- **Tag 形式展示**当前选中项，每个 tag 自带 × 可单独删除。
+- **全部清空（×）**在有选中项时出现在 tag 旁边。
+- **`value` 是分隔字符串** —— `"A;B;C"` 这种形式。改 `delimiter` 可以换分隔符（`,` / `|` 等）。
+- **`onchange` 拿到的是数组** —— 不管存储用什么分隔符，回调始终给你干净的 `Array<string>`。
+- **自定义字段映射**：`keyField` / `textField`。
+- **隐藏 / 禁用单个选项**：`hideOptions` / `disabledOptions`。
+- **Tag 样式**：`tagVariant`（`borderless` / `border` / `round`）+ `tagColor`（`"0"` … `"12"`，对应 `--topside-tag-g{n}-color` 这组 token）。
+- **紧凑模式** —— 切到 tag 的小尺寸，适合表格单元格和密集表单。
+- **只读 / 禁用** —— tag 不显示 ×；下拉不弹。
+- **共享的 form-editor 属性** —— `variant`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur`。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  // value 是分隔符拼接的字符串，例如 "JS;TS;PY"
+  let value = $state("");
+
+  const options = [
+    { code: "JS", text: "JavaScript" },
+    { code: "TS", text: "TypeScript" },
+    { code: "PY", text: "Python" },
+    { code: "GO", text: "Go" }
+  ];
+
+  function handleChange(keys: string[]) {
+    console.log("当前选中的 keys:", keys);
+  }
+</script>
+
+<OptionsMultiSelect {options} bind:value onchange={handleChange} placeholder="选择语言" />
+```
+
+## 属性（Props）
+
+`OptionsMultiSelect` 继承自 `PickerProps`，因此自动获得 `variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`、`onfocus` / `onblur` / `onchange`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string`（可绑定） | `""` | 选中的 keys 用 `delimiter` 拼接成的字符串。空串表示未选。 |
+| `options` | `Array<any>` | — | 完整的选项列表。 |
+| `keyField` | `string` | `"code"` | 作为选项身份的字段。 |
+| `textField` | `string` | `"text"` | 显示用的字段。 |
+| `delimiter` | `string` | `";"` | `value` 拼接用的分隔符。 |
+| `placeholder` | `string` | — | 没有选中时输入框的占位文字。 |
+| `emptyText` | `string` | — | 没有选中时**替换** placeholder 显示的文字。常用于只读模式下显示"全部"或"不限"。 |
+| `disabledOptions` | `Array<string>` | `[]` | 要渲染但禁用（checkbox 变灰）的 keys。 |
+| `hideOptions` | `Array<string>` | `[]` | 完全不渲染的 keys。 |
+| `tagColor` | `string` | — | 对应 `--topside-tag-g{n}-color` 这组 token。可填 `"0"` … `"12"`。 |
+| `tagVariant` | `'borderless' \| 'border' \| 'round'` | `'border'` | tag 的视觉风格。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 编辑器风格。 |
+| `compact` | `boolean` | `false` | 把 tag 切到小尺寸（`--topside-tag-height-sm`）。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— tag 没 ×，无下拉。 |
+| `readonly` | `boolean` | `false` | 只读 —— 视觉同 disabled，语义是"查看，不可编辑"。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本，触发编辑器的 error 状态。 |
+| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
+| `theme` | `string` | — | 渲染为弹窗根的 `data-theme`，用于作用域样式覆盖。 |
+| `menu$height` | `number` | `0` | 下拉的固定高度（px）。`0` 表示 `auto`。 |
+| `onchange` | `(keys: string[]) => void` | — | 选中状态变化时触发（增 / 删 / 清空）。**始终传入 keys 数组**，不是分隔字符串。 |
+| `onfocus` | `(e: FocusEvent) => void` | — | 编辑器获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | — | 编辑器失焦，在弹窗关闭且焦点真正离开之后触发。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onchange` | `(keys: string[]) => void` | 选中状态变化时触发。**始终传入 keys 数组**，不是分隔字符串。 |
+| `onfocus` | `(e: FocusEvent) => void` | 编辑器获焦。 |
+| `onblur` | `(e: FocusEvent) => void` | 编辑器失焦，在弹窗关闭且焦点真正离开之后触发。 |
+
+## 方法
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `focus()` | `() => void` | 让编辑器获得焦点。内部延迟 50 ms，等弹窗挂载完。 |
+
+## Tag 颜色参考
+
+| `tagColor` | 对应 token | 色相 |
+|------------|-----------|------|
+| `"0"` | `--topside-tag-g0-color` | 中性灰 |
+| `"1"` | `--topside-tag-g1-color` | 蓝 |
+| `"2"` | `--topside-tag-g2-color` | 绿 |
+| `"3"` | `--topside-tag-g3-color` | 红 |
+| `"4"` | `--topside-tag-g4-color` | 黄 / 琥珀 |
+| `"5"` | `--topside-tag-g5-color` | 粉 |
+| `"6"` | `--topside-tag-g6-color` | 青 |
+| `"7"` | `--topside-tag-g7-color` | 橙红 |
+| `"8"` | `--topside-tag-g8-color` | 橙 |
+| `"9"` | `--topside-tag-g9-color` | 靛蓝 |
+| `"10"` | `--topside-tag-g10-color` | 紫 |
+| `"11"` | `--topside-tag-g11-color` | 黄绿 |
+| `"12"` | `--topside-tag-g12-color` | 灰蓝（带专属 `*-bg` / `*-border`） |
+
+## 示例
+
+### 自定义分隔符
+
+用 `,` 替代 `;`，CSV 风格存储：
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  let csv = $state("JS,TS");
+  const options = [
+    { code: "JS", text: "JavaScript" },
+    { code: "TS", text: "TypeScript" },
+    { code: "PY", text: "Python" }
+  ];
+</script>
+
+<OptionsMultiSelect {options} bind:value={csv} delimiter="," />
+```
+
+### 隐藏 / 禁用选项
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  let value = $state("");
+  const options = [
+    { code: "DRAFT",     text: "Draft" },
+    { code: "REVIEW",    text: "In Review" },
+    { code: "PUBLISHED", text: "Published" },
+    { code: "ARCHIVED",  text: "Archived" }
+  ];
+</script>
+
+<OptionsMultiSelect
+  {options}
+  bind:value
+  disabledOptions={["ARCHIVED"]}
+  hideOptions={["DRAFT"]}
+  placeholder="可见状态"
+/>
+```
+
+### 圆角彩色 tag
+
+```svelte
+<OptionsMultiSelect
+  {options}
+  bind:value
+  tagColor="3"
+  tagVariant="round"
+  variant="outlined"
+/>
+```
+
+### 表格内的紧凑用法
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from "@ticatec/topside-elements/OptionsMultiSelect";
+
+  const roles = [
+    { code: "READ",  text: "Read" },
+    { code: "WRITE", text: "Write" },
+    { code: "ADMIN", text: "Admin" }
+  ];
+
+  let users = $state([
+    { id: 1, name: "Alice", roles: "READ;WRITE" },
+    { id: 2, name: "Bob",   roles: "READ" }
+  ]);
+</script>
+
+<table>
+  <thead><tr><th>用户</th><th>角色</th></tr></thead>
+  <tbody>
+    {#each users as user (user.id)}
+      <tr>
+        <td>{user.name}</td>
+        <td>
+          <OptionsMultiSelect
+            {options: roles}
+            bind:value={user.roles}
+            compact
+            variant="outlined"
+          />
+        </td>
+      </tr>
+    {/each}
+  </tbody>
+</table>
+```
+
+## 行为说明
+
+### `value` 与 `onchange` 怎么保持同步
+
+| 动作 | 结果 |
+|------|------|
+| 用户勾选 checkbox 或点行 | `value` 更新成新的分隔字符串；`onchange` 触发，传入新的 `Array<string>`。 |
+| 用户点 tag 上的 × | `value` 缩短；`onchange` 触发，传入更短的数组。 |
+| 用户点全部清空 × | `value` 变成 `""`；`onchange` 触发，传入 `[]`。 |
+| 父组件外部改 `value` | 内部 `selectedList` 从新串重建，tag 重渲染。**`onchange` 不触发** —— 父组件是变更源，不回弹。 |
+
+### 只读 / 禁用渲染
+
+两种模式下都会隐藏全部清空 × 与每个 tag 的 ×、隐藏下拉箭头、抑制弹窗打开。语义不同：`readonly` 是"看，但不能改"（仍可被读屏访问），`disabled` 是"灰掉，忽略"。
+
+## 无障碍
+
+- 每个选项行通过 `<CheckBox>` 组件渲染真实的 `<input type="checkbox">` —— 键盘和读屏用户拿到的是标准 checkbox 语义。
+- 弹窗通过 `Popover` 用 portal 渲染到 `document.body`。
+- 外部点击关闭弹窗（用 `useCapture: true` 注册）。
+- 表单级 ARIA 需要外层 `<label>` / `FormField` 配合 `error` 文本。
+
+## 相关组件
+
+- [OptionsSelect](../options_select/README_CN.md) —— 单选变体。
+- [CascadeOptionSelect](../cascade_options_select/README_CN.md) —— 树形级联选择。
+- [LookupEditor](../lookup_editor/README_CN.md) —— 大列表 / 远程数据的懒加载选择器。

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

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

package/dist/form/options_multi_select/index.js

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