@ticatec/topside-elements 1.0.0

package/dist/form/group_box/group-check-box/README.md

@@ -0,0 +1,336 @@
+# GroupCheckBox
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../../docs/NAMING.md); the old names `itemStyle` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A multi-select group of checkboxes wrapped in the shared form editor shell. Options are rendered in a horizontal row; the bound `value` can be either a **delimiter-joined string** or a **bitmask number**.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+```
+
+## Features
+
+- Multi-select from a configurable `options` list
+- String storage (`"a;b;c"`) or bit storage (`bitBase`)
+- Per-option disable (`disabledOptions`) and hide (`hideOptions`)
+- Custom key/label fields (`keyField` / `textField`)
+- Form shell: `variant`, `error`, `tooltip`, `compact`, `readonly`, `disabled`
+- `onchange` only on user interaction (not external `value` writes)
+- Programmatic `focus()` on the first enabled checkbox
+
+## Basic Usage
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const options = [
+    { code: "js", text: "JavaScript" },
+    { code: "ts", text: "TypeScript" },
+    { code: "py", text: "Python" },
+    { code: "go", text: "Go" },
+  ];
+
+  let selectedLanguages = $state("");
+</script>
+
+<GroupCheckBox
+  {options}
+  bind:value={selectedLanguages}
+  onchange={(value) => console.log("Selected:", value)}
+/>
+
+<p>Value: {selectedLanguages || "(none)"}</p>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| number` | required | Selected value. Bindable via `bind:value`. String mode: delimited keys; bit mode: number |
+| `options` | `Array<Record<string, any>>` | required | Option objects |
+| `keyField` | `string` | `"code"` | Field used as option key / stored value |
+| `textField` | `string` | `"text"` | Field used as checkbox label |
+| `delimiter` | `string` | `";"` | Join separator in string mode |
+| `bitBase` | `boolean` | `false` | Use bitmask storage instead of a string |
+| `disabled` | `boolean` | `false` | Disable the whole group |
+| `readonly` | `boolean` | `false` | Read-only; checkboxes cannot be toggled |
+| `compact` | `boolean` | `false` | Compact row height and checkbox size |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Form editor visual style |
+| `error` | `string` | — | Error message on the form shell |
+| `tooltip` | `string` | — | Hover tooltip |
+| `disabledOptions` | `string[]` | `[]` | Keys of options that stay disabled |
+| `hideOptions` | `string[]` | `[]` | Keys of options that are not rendered |
+| `style` | `string` | `""` | Inline style on the form editor |
+| `item$style` | `string` | `""` | Inline style applied to each `CheckBox` |
+| `class` | `string` | `""` | Extra class on the form editor |
+| `onchange` | `(value: string \| number) => void` | — | Fired after a **user** toggle; receives the new `value` |
+| `onfocus` | `(e: FocusEvent) => void` | — | First focus into the group |
+| `onblur` | `(e: FocusEvent) => void` | — | Focus leaves the group (not when moving between items) |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Focus the first non-disabled checkbox input |
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  let group;
+  const options = [
+    { code: "a", text: "Option A" },
+    { code: "b", text: "Option B" },
+  ];
+  let value = $state("");
+</script>
+
+<button type="button" onclick={() => group?.focus()}>Focus group</button>
+<GroupCheckBox bind:this={group} {options} bind:value={value} />
+```
+
+## Value Formats
+
+### String mode (`bitBase={false}`, default)
+
+Selected keys are joined with `delimiter` (default `";"`):
+
+| Selection | `value` |
+|-----------|---------|
+| None | `""` |
+| One | `"js"` |
+| Several | `"js;ts;py"` |
+
+Order follows the `options` array order, not click order.
+
+### Bit mode (`bitBase={true}`)
+
+Each option’s **index** in `options` maps to a bit:
+
+| Option index | Bit | Weight |
+|--------------|-----|--------|
+| 0 | bit 0 | `1` |
+| 1 | bit 1 | `2` |
+| 2 | bit 2 | `4` |
+| 3 | bit 3 | `8` |
+
+Example: options at index 0 and 2 selected → `value = 1 + 4 = 5`.
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const permissions = [
+    { code: "read", text: "Read" },   // bit 0 → 1
+    { code: "write", text: "Write" }, // bit 1 → 2
+    { code: "delete", text: "Delete" }, // bit 2 → 4
+    { code: "admin", text: "Admin" }, // bit 3 → 8
+  ];
+
+  let userPermissions = $state(0); // e.g. 5 = read + delete
+</script>
+
+<GroupCheckBox
+  options={permissions}
+  bitBase
+  bind:value={userPermissions}
+  onchange={(v) => console.log(v, v.toString(2))}
+/>
+```
+
+Keep `options` order stable when using bit mode; reordering changes bit meanings.
+
+## Examples
+
+### Custom fields and delimiter
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const departments = [
+    { id: "eng", name: "Engineering" },
+    { id: "sales", name: "Sales" },
+    { id: "hr", name: "HR" },
+  ];
+
+  let selected = $state("");
+</script>
+
+<GroupCheckBox
+  options={departments}
+  keyField="id"
+  textField="name"
+  delimiter=","
+  variant="outlined"
+  bind:value={selected}
+/>
+
+<p>{selected}</p>
+<!-- e.g. "eng,sales" -->
+```
+
+### Disable or hide individual options
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const options = [
+    { code: "read", text: "Read" },
+    { code: "write", text: "Write" },
+    { code: "delete", text: "Delete" },
+    { code: "admin", text: "Admin" },
+  ];
+
+  let value = $state("read");
+</script>
+
+<GroupCheckBox
+  {options}
+  bind:value={value}
+  disabledOptions={["admin"]}
+  hideOptions={["delete"]}
+/>
+```
+
+### Variants and compact layout
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const colors = [
+    { code: "red", text: "Red" },
+    { code: "blue", text: "Blue" },
+    { code: "green", text: "Green" },
+  ];
+
+  let selected = $state("");
+</script>
+
+<GroupCheckBox {options: colors} bind:value={selected} />
+<GroupCheckBox options={colors} variant="outlined" bind:value={selected} />
+<GroupCheckBox options={colors} variant="filled" bind:value={selected} />
+<GroupCheckBox options={colors} compact bind:value={selected} />
+```
+
+### Read-only and disabled
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const skills = [
+    { code: "js", text: "JavaScript" },
+    { code: "ts", text: "TypeScript" },
+    { code: "svelte", text: "Svelte" },
+  ];
+
+  let value = $state("js;svelte");
+</script>
+
+<GroupCheckBox options={skills} bind:value={value} />
+<GroupCheckBox options={skills} value={value} readonly />
+<GroupCheckBox options={skills} value={value} disabled />
+```
+
+### Form field with error and focus
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+  import FormField from "@ticatec/topside-elements/FormField";
+
+  const interests = [
+    { code: "sports", text: "Sports" },
+    { code: "music", text: "Music" },
+    { code: "travel", text: "Travel" },
+  ];
+
+  let interestsValue = $state("");
+  let error = $state(/** @type {string | undefined} */ (undefined));
+  let group;
+
+  function submit() {
+    if (!interestsValue) {
+      error = "Select at least one interest";
+      group?.focus();
+      return;
+    }
+    error = undefined;
+    console.log("submit", interestsValue);
+  }
+</script>
+
+<FormField label="Interests" {error}>
+  <GroupCheckBox
+    bind:this={group}
+    options={interests}
+    variant="outlined"
+    bind:value={interestsValue}
+    {error}
+    onchange={() => {
+      error = undefined;
+    }}
+  />
+</FormField>
+
+<button type="button" onclick={submit}>Submit</button>
+```
+
+## Behavior
+
+1. Each visible option is a nested `CheckBox` in a horizontal flex row (class `group-check-box`).
+2. External `value` changes recompute internal checked states (`$effect` → `generateCheckboxStates`).
+3. User toggles update `value`, then fire `onchange` once (tracked with an internal user-change flag). Programmatic `value` updates do **not** call `onchange`.
+4. After a value change, the local `error` prop variable is cleared inside the component (parent-driven `error` should still be managed by the parent for form validation).
+5. `onfocus` fires when focus enters the group; `onblur` when focus leaves the container (moving between checkboxes does not blur).
+6. `disabled` disables every checkbox; `disabledOptions` only specific keys; `hideOptions` removes options from the DOM.
+7. Row height is `38px` by default, `26px` when `compact`.
+
+## Layout & Styling
+
+- Root list: `.group-check-box` — `display: flex; flex-direction: row; align-items: center`
+- Compact: `.group-check-box.compact`
+- Shell chrome (border, fill, error) comes from `FormEditor` via `variant` / `error` / `tooltip`
+- Per-item look: `item$style` on each checkbox; checkbox tokens are those of [`CheckBox`](../../checkbox/README.md)
+
+```svelte
+<GroupCheckBox
+  options={options}
+  bind:value={value}
+  variant="outlined"
+  style="min-width: 320px;"
+  item$style="margin-right: 4px;"
+/>
+```
+
+## Accessibility
+
+- Built on native `input[type="checkbox"]` (via `CheckBox`)
+- Tab moves between enabled checkboxes; Space toggles
+- `focus()` jumps to the first enabled checkbox
+- Prefer wrapping with `FormField` (or similar) for a visible group label
+
+## Notes
+
+- String mode empty selection is `""`, not `null` / `undefined`.
+- Bit mode uses **option index**, not the key string, for bit positions.
+- Prefer stable `options` arrays; for bit mode, never reorder without migrating stored numbers.
+- For a single boolean, use [`CheckBox`](../../checkbox/README.md); for exclusive single choice, use [`GroupRadioBox`](../group-radio-box/README.md).
+
+## Related Components
+
+- [CheckBox](../../checkbox/README.md) — single boolean checkbox
+- [GroupRadioBox](../group-radio-box/README.md) — single selection group
+- [OptionsMultiSelect](../../options_multi_select/README.md) — multi-select dropdown

package/dist/form/group_box/group-check-box/README_CN.md

@@ -0,0 +1,336 @@
+# GroupCheckBox 组复选框
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../../docs/NAMING_CN.md) 中的名字；旧名 `itemStyle` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+多选复选框组，包在共享表单编辑器外壳中。选项横向排列；绑定的 `value` 可以是**分隔符拼接的字符串**，也可以是**位掩码数字**。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+```
+
+## 功能特性
+
+- 从可配置的 `options` 中多选
+- 字符串存储（`"a;b;c"`）或位存储（`bitBase`）
+- 按选项禁用（`disabledOptions`）与隐藏（`hideOptions`）
+- 自定义键 / 标签字段（`keyField` / `textField`）
+- 表单外壳：`variant`、`error`、`tooltip`、`compact`、`readonly`、`disabled`
+- `onchange` 仅在用户操作时触发（外部改写 `value` 不触发）
+- 支持 `focus()` 聚焦第一个可用复选框
+
+## 基本用法
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const options = [
+    { code: "js", text: "JavaScript" },
+    { code: "ts", text: "TypeScript" },
+    { code: "py", text: "Python" },
+    { code: "go", text: "Go" },
+  ];
+
+  let selectedLanguages = $state("");
+</script>
+
+<GroupCheckBox
+  {options}
+  bind:value={selectedLanguages}
+  onchange={(value) => console.log("已选择:", value)}
+/>
+
+<p>值: {selectedLanguages || "（无）"}</p>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string \| number` | 必需 | 选中值，支持 `bind:value`。字符串模式为分隔键；位模式为数字 |
+| `options` | `Array<Record<string, any>>` | 必需 | 选项对象数组 |
+| `keyField` | `string` | `"code"` | 作为选项键 / 存储值的字段名 |
+| `textField` | `string` | `"text"` | 作为复选框标签的字段名 |
+| `delimiter` | `string` | `";"` | 字符串模式下的拼接分隔符 |
+| `bitBase` | `boolean` | `false` | 是否使用位掩码存储 |
+| `disabled` | `boolean` | `false` | 禁用整组 |
+| `readonly` | `boolean` | `false` | 只读，不可切换 |
+| `compact` | `boolean` | `false` | 紧凑行高与复选框尺寸 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 表单编辑器视觉样式 |
+| `error` | `string` | — | 表单外壳错误信息 |
+| `tooltip` | `string` | — | 悬停提示 |
+| `disabledOptions` | `string[]` | `[]` | 保持禁用的选项键 |
+| `hideOptions` | `string[]` | `[]` | 不渲染的选项键 |
+| `style` | `string` | `""` | 表单编辑器内联样式 |
+| `item$style` | `string` | `""` | 应用到每个 `CheckBox` 的内联样式 |
+| `class` | `string` | `""` | 表单编辑器额外 CSS 类 |
+| `onchange` | `(value: string \| number) => void` | — | **用户**切换后回调，参数为新的 `value` |
+| `onfocus` | `(e: FocusEvent) => void` | — | 焦点进入组时触发 |
+| `onblur` | `(e: FocusEvent) => void` | — | 焦点离开组时触发（在组内选项间移动不触发） |
+
+## 方法
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 聚焦第一个未禁用的复选框 |
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  let group;
+  const options = [
+    { code: "a", text: "选项 A" },
+    { code: "b", text: "选项 B" },
+  ];
+  let value = $state("");
+</script>
+
+<button type="button" onclick={() => group?.focus()}>聚焦组</button>
+<GroupCheckBox bind:this={group} {options} bind:value={value} />
+```
+
+## 值格式
+
+### 字符串模式（`bitBase={false}`，默认）
+
+选中键用 `delimiter`（默认 `";"`）拼接：
+
+| 选择 | `value` |
+|------|---------|
+| 无 | `""` |
+| 单项 | `"js"` |
+| 多项 | `"js;ts;py"` |
+
+顺序与 `options` 数组顺序一致，与点击顺序无关。
+
+### 位模式（`bitBase={true}`）
+
+每个选项在 `options` 中的**下标**对应一个二进制位：
+
+| 选项下标 | 位 | 权值 |
+|----------|----|------|
+| 0 | bit 0 | `1` |
+| 1 | bit 1 | `2` |
+| 2 | bit 2 | `4` |
+| 3 | bit 3 | `8` |
+
+示例：选中下标 0 与 2 → `value = 1 + 4 = 5`。
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const permissions = [
+    { code: "read", text: "读取" },   // bit 0 → 1
+    { code: "write", text: "写入" },  // bit 1 → 2
+    { code: "delete", text: "删除" }, // bit 2 → 4
+    { code: "admin", text: "管理员" }, // bit 3 → 8
+  ];
+
+  let userPermissions = $state(0); // 例如 5 = 读取 + 删除
+</script>
+
+<GroupCheckBox
+  options={permissions}
+  bitBase
+  bind:value={userPermissions}
+  onchange={(v) => console.log(v, v.toString(2))}
+/>
+```
+
+使用位模式时请保持 `options` 顺序稳定；重排会改变位含义。
+
+## 示例
+
+### 自定义字段与分隔符
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const departments = [
+    { id: "eng", name: "工程部" },
+    { id: "sales", name: "销售部" },
+    { id: "hr", name: "人力资源" },
+  ];
+
+  let selected = $state("");
+</script>
+
+<GroupCheckBox
+  options={departments}
+  keyField="id"
+  textField="name"
+  delimiter=","
+  variant="outlined"
+  bind:value={selected}
+/>
+
+<p>{selected}</p>
+<!-- 例如 "eng,sales" -->
+```
+
+### 禁用或隐藏部分选项
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const options = [
+    { code: "read", text: "读取" },
+    { code: "write", text: "写入" },
+    { code: "delete", text: "删除" },
+    { code: "admin", text: "管理员" },
+  ];
+
+  let value = $state("read");
+</script>
+
+<GroupCheckBox
+  {options}
+  bind:value={value}
+  disabledOptions={["admin"]}
+  hideOptions={["delete"]}
+/>
+```
+
+### 样式变体与紧凑布局
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const colors = [
+    { code: "red", text: "红" },
+    { code: "blue", text: "蓝" },
+    { code: "green", text: "绿" },
+  ];
+
+  let selected = $state("");
+</script>
+
+<GroupCheckBox options={colors} bind:value={selected} />
+<GroupCheckBox options={colors} variant="outlined" bind:value={selected} />
+<GroupCheckBox options={colors} variant="filled" bind:value={selected} />
+<GroupCheckBox options={colors} compact bind:value={selected} />
+```
+
+### 只读与禁用
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+
+  const skills = [
+    { code: "js", text: "JavaScript" },
+    { code: "ts", text: "TypeScript" },
+    { code: "svelte", text: "Svelte" },
+  ];
+
+  let value = $state("js;svelte");
+</script>
+
+<GroupCheckBox options={skills} bind:value={value} />
+<GroupCheckBox options={skills} value={value} readonly />
+<GroupCheckBox options={skills} value={value} disabled />
+```
+
+### 表单校验与聚焦
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/topside-elements/GroupCheckBox";
+  import FormField from "@ticatec/topside-elements/FormField";
+
+  const interests = [
+    { code: "sports", text: "运动" },
+    { code: "music", text: "音乐" },
+    { code: "travel", text: "旅行" },
+  ];
+
+  let interestsValue = $state("");
+  let error = $state(/** @type {string | undefined} */ (undefined));
+  let group;
+
+  function submit() {
+    if (!interestsValue) {
+      error = "请至少选择一个兴趣";
+      group?.focus();
+      return;
+    }
+    error = undefined;
+    console.log("提交", interestsValue);
+  }
+</script>
+
+<FormField label="兴趣" {error}>
+  <GroupCheckBox
+    bind:this={group}
+    options={interests}
+    variant="outlined"
+    bind:value={interestsValue}
+    {error}
+    onchange={() => {
+      error = undefined;
+    }}
+  />
+</FormField>
+
+<button type="button" onclick={submit}>提交</button>
+```
+
+## 行为说明
+
+1. 每个可见选项是嵌套的 `CheckBox`，横向 flex 排列（类名 `group-check-box`）。
+2. 外部 `value` 变化会重新计算内部勾选状态（`$effect` → `generateCheckboxStates`）。
+3. 用户切换会更新 `value`，再触发一次 `onchange`（内部用用户操作标记）。程序化改写 `value` **不会**调用 `onchange`。
+4. 值变化时组件内部会清空本地 `error` 变量；父组件侧的校验错误仍应由父组件维护。
+5. `onfocus` 在焦点进入组时触发；`onblur` 在焦点离开容器时触发（在组内选项间移动不触发）。
+6. `disabled` 禁用全部；`disabledOptions` 仅禁用指定键；`hideOptions` 从 DOM 中移除选项。
+7. 行高默认 `38px`，`compact` 时为 `26px`。
+
+## 布局与样式
+
+- 列表根节点：`.group-check-box` — `display: flex; flex-direction: row; align-items: center`
+- 紧凑：`.group-check-box.compact`
+- 边框 / 填充 / 错误等外壳样式来自 `FormEditor` 的 `variant` / `error` / `tooltip`
+- 单项外观：`item$style`；复选框主题变量见 [`CheckBox`](../../checkbox/README_CN.md)
+
+```svelte
+<GroupCheckBox
+  options={options}
+  bind:value={value}
+  variant="outlined"
+  style="min-width: 320px;"
+  item$style="margin-right: 4px;"
+/>
+```
+
+## 无障碍访问
+
+- 基于原生 `input[type="checkbox"]`（通过 `CheckBox`）
+- Tab 在可用复选框间移动；Space 切换
+- `focus()` 跳到第一个可用复选框
+- 建议用 `FormField`（或同类）提供组级可见标签
+
+## 注意事项
+
+- 字符串模式空选为 `""`，不是 `null` / `undefined`。
+- 位模式按**选项下标**占位，而不是按 key 字符串。
+- 保持 `options` 稳定；位模式下勿随意重排，除非同步迁移已存数值。
+- 单个布尔值用 [`CheckBox`](../../checkbox/README_CN.md)；互斥单选用 [`GroupRadioBox`](../group-radio-box/README_CN.md)。
+
+## 相关组件
+
+- [CheckBox](../../checkbox/README_CN.md) — 单个布尔复选框
+- [GroupRadioBox](../group-radio-box/README_CN.md) — 单选组
+- [OptionsMultiSelect](../../options_multi_select/README_CN.md) — 下拉多选

package/dist/form/group_box/group-check-box/index.d.ts

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

package/dist/form/group_box/group-check-box/index.js

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