@ticatec/topside-elements 1.0.0

package/dist/form/cascade_options_select/README.md

@@ -0,0 +1,188 @@
+# CascadeOptionSelect
+
+A cascading (hierarchical) multi-select picker where child options only appear once a parent option is selected. Renders as a dropdown list of checkboxes with indented child rows — the visual language matches a tree view without requiring you to build one from scratch.
+
+## Features
+
+- **Cascading tree structure** — child options auto-load when parent is checked; collapse/expand via click.
+- **Multi-select with checkboxes** — each option gets a real `<input type="checkbox">`.
+- **Auto-select children** — when a parent is checked, all its children are checked too (and vice versa).
+- **Custom field mapping** — `keyField` / `textField` / `childrenField` define how your tree-shaped data maps to the picker.
+- **`onchange` returns a flat array** of selected keys regardless of tree depth.
+- **Compact mode** for dense UIs.
+- **Disabled / readonly** modes — dropdown suppressed, tree rendered as plain text.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "electronics",
+      text: "Electronics",
+      children: [
+        { id: "phones", text: "Phones" },
+        { id: "laptops", text: "Laptops" }
+      ]
+    },
+    {
+      id: "clothing",
+      text: "Clothing",
+      children: [
+        { id: "shirts", text: "Shirts" },
+        { id: "pants", text: "Pants" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="Select categories" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` (bindable) | `""` | Selected keys joined by delimiter (default `;`). |
+| `options` | `Array<any>` | — | Full tree data structure. |
+| `keyField` | `string` | `"id"` | Property used as the option's identity. |
+| `textField` | `string` | `"text"` | Property used as the option's display text. |
+| `childrenField` | `string` | `"children"` | Property name where child options live. |
+| `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. |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Editor variant. |
+| `compact` | `boolean` | `false` | Compact layout for dense UIs. |
+| `disabled` | `boolean` | `false` | Fully disabled — dropdown suppressed. |
+| `readonly` | `boolean` | `false` | Read-only — tree rendered as plain text. |
+| `style` | `string` | — | Inline CSS on the editor root. |
+| `error` | `string` | — | Validation error text. |
+| `tooltip` | `string` | — | Hover tooltip on the editor. |
+| `theme` | `string` | — | Rendered as `data-theme` on the popover. |
+| `menu$height` | `number` | `0` | Fixed dropdown height in px. `0` means `auto`. |
+| `onchange` | `(keys: string[]) => void` | — | Fires when selection changes. Always receives the array of selected keys. |
+| `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 when selection changes. Always receives the array of selected keys. |
+| `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. |
+
+## Examples
+
+### Custom field mapping
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+
+  let value = $state("");
+
+  // Data shaped differently from the default
+  const options = [
+    {
+      category: "Food",
+      items: [
+        { id: "fruits", label: "Fruits" },
+        { id: "vegetables", label: "Vegetables" }
+      ]
+    },
+    {
+      category: "Drinks",
+      items: [
+        { id: "coffee", label: "Coffee" },
+        { id: "tea", label: "Tea" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect
+  {options}
+  keyField="category"
+  textField="category"
+  childrenField="items"
+  bind:value
+  placeholder="Select categories"
+/>
+```
+
+### Deeply nested tree
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "east",
+      text: "East Asia",
+      children: [
+        {
+          id: "cn",
+          text: "China",
+          children: [
+            { id: "beijing", text: "Beijing" },
+            { id: "shanghai", text: "Shanghai" }
+          ]
+        },
+        {
+          id: "jp",
+          text: "Japan",
+          children: [
+            { id: "tokyo", text: "Tokyo" },
+            { id: "osaka", text: "Osaka" }
+          ]
+        }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="Select cities" />
+```
+
+### With delimiter
+
+```svelte
+<CascadeOptionSelect
+  {options}
+  bind:value
+  delimiter=","
+  placeholder="Use commas"
+/>
+```
+
+## Related Components
+
+- [OptionsSelect](../options_select/README.md) — single-select variant.
+- [OptionsMultiSelect](../options_multi_select/README.md) — flat multi-select variant.
+- [LookupEditor](../lookup_editor/README.md) — lazy-loading picker for large / remote option lists.

package/dist/form/cascade_options_select/README_CN.md

@@ -0,0 +1,188 @@
+# CascadeOptionSelect
+
+树形级联多选选择器。子选项在父选项被选中时才显示。以下拉树形复选框列表的形式渲染 —— 不需要你从零搭建树形视图。
+
+## 特性
+
+- **级联树结构** —— 勾选父选项时自动加载并展示子选项；点击可展开/折叠。
+- **多选 + 复选框** —— 每个选项都有一个真实的 `<input type="checkbox">`。
+- **父子联动** —— 勾选父选项时，所有子选项也自动勾选（反之亦然）。
+- **自定义字段映射** —— `keyField` / `textField` / `childrenField` 定义树形数据如何映射到选择器。
+- **`onchange` 返回扁平数组** —— 不管树深度如何，回调始终是选中的 keys 数组。
+- **紧凑模式** —— 适用于密集 UI。
+- **禁用 / 只读** —— 下拉被抑制，树以纯文本形式渲染。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "electronics",
+      text: "Electronics",
+      children: [
+        { id: "phones", text: "Phones" },
+        { id: "laptops", text: "Laptops" }
+      ]
+    },
+    {
+      id: "clothing",
+      text: "Clothing",
+      children: [
+        { id: "shirts", text: "Shirts" },
+        { id: "pants", text: "Pants" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="选择分类" />
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string`（可绑定） | `""` | 选中的 keys 用分隔符（默认 `;`）拼接。 |
+| `options` | `Array<any>` | — | 完整的树形数据。 |
+| `keyField` | `string` | `"id"` | 作为选项身份的字段。 |
+| `textField` | `string` | `"text"` | 显示用的字段。 |
+| `childrenField` | `string` | `"children"` | 子选项所在的字段名。 |
+| `delimiter` | `string` | `";"` | `value` 拼接用的分隔符。 |
+| `placeholder` | `string` | — | 没有选中时显示的文字。 |
+| `emptyText` | `string` | — | 没有选中时**替换** placeholder 显示的文字。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 编辑器风格。 |
+| `compact` | `boolean` | `false` | 紧凑布局。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— 下拉被抑制。 |
+| `readonly` | `boolean` | `false` | 只读 —— 树以纯文本形式渲染。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本。 |
+| `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。 |
+
+## 示例
+
+### 自定义字段映射
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+
+  let value = $state("");
+
+  // 数据形状不同于默认
+  const options = [
+    {
+      category: "Food",
+      items: [
+        { id: "fruits", label: "Fruits" },
+        { id: "vegetables", label: "Vegetables" }
+      ]
+    },
+    {
+      category: "Drinks",
+      items: [
+        { id: "coffee", label: "Coffee" },
+        { id: "tea", label: "Tea" }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect
+  {options}
+  keyField="category"
+  textField="category"
+  childrenField="items"
+  bind:value
+  placeholder="选择分类"
+/>
+```
+
+### 深层嵌套的树
+
+```svelte
+<script lang="ts">
+  import CascadeOptionSelect from "@ticatec/topside-elements/CascadeOptionSelect";
+
+  let value = $state("");
+
+  const options = [
+    {
+      id: "east",
+      text: "East Asia",
+      children: [
+        {
+          id: "cn",
+          text: "China",
+          children: [
+            { id: "beijing", text: "Beijing" },
+            { id: "shanghai", text: "Shanghai" }
+          ]
+        },
+        {
+          id: "jp",
+          text: "Japan",
+          children: [
+            { id: "tokyo", text: "Tokyo" },
+            { id: "osaka", text: "Osaka" }
+          ]
+        }
+      ]
+    }
+  ];
+</script>
+
+<CascadeOptionSelect {options} bind:value placeholder="选择城市" />
+```
+
+### 自定义分隔符
+
+```svelte
+<CascadeOptionSelect
+  {options}
+  bind:value
+  delimiter=","
+  placeholder="用逗号分隔"
+/>
+```
+
+## 相关组件
+
+- [OptionsSelect](../options_select/README_CN.md) —— 单选变体。
+- [OptionsMultiSelect](../options_multi_select/README_CN.md) —— 平面多选变体。
+- [LookupEditor](../lookup_editor/README_CN.md) —— 大列表 / 远程数据的懒加载选择器。

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

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

package/dist/form/cascade_options_select/index.js

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

package/dist/form/checkbox/CheckBox.svelte

@@ -0,0 +1,222 @@
+<script lang="ts">
+
+    interface Props {
+        label?: string | null;
+        readonly?: boolean;
+        disabled?: boolean;
+        theme?: string;
+        value?: boolean;
+        indeterminate?: boolean;
+        style?: string;
+        compact?: boolean;
+        onchange?: (value: boolean) => void;
+        onfocus?: (event: FocusEvent) => void;
+        onblur?: (event: FocusEvent) => void;
+    }
+
+    let {
+        label = null,
+        readonly = false,
+        disabled = false,
+        theme,
+        value = $bindable(),
+        indeterminate = false,
+        style,
+        compact = false,
+        onfocus,
+        onblur,
+        onchange
+    }: Props = $props();
+
+
+    let checkbox: HTMLInputElement;
+
+    export function focus() {
+        checkbox?.focus();
+    }
+
+    // 处理点击：拦截 readonly/disabled，清除 indeterminate
+    const handleClick = (e: MouseEvent) => {
+        if (readonly || disabled) {
+            e.preventDefault();
+            e.stopPropagation();
+        }
+    };
+
+    // 处理 change 事件：调用自定义 onchange，传入当前值
+    const handleChange = (e: Event) => {
+        if (readonly || disabled) {
+            e.preventDefault();
+            return;
+        }
+        onchange?.(value ?? false);
+    };
+
+
+    // Sync indeterminate state
+    $effect(() => {
+        if (checkbox) {
+            checkbox.indeterminate = indeterminate;
+        }
+    });
+
+</script>
+
+<div class="topside-checkbox {compact ? 'compact' : ''} {disabled ? 'disabled' : ''}" {style} data-theme={theme}>
+    <label>
+        <input
+                bind:this={checkbox}
+                type="checkbox"
+                bind:checked={value}
+                onclick={handleClick}
+                {onfocus}
+                {onblur}
+                onchange={handleChange}
+                {disabled}
+                {readonly}
+        />
+        {#if label}
+            <span>{label}</span>
+        {/if}
+    </label>
+</div>
+
+<style>@charset "UTF-8";
+.topside-checkbox {
+  display: inline-block;
+  padding: var(--topside-checkbox-padding);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--topside-checkbox-text-color);
+}
+.topside-checkbox label {
+  display: inline-block;
+  width: 100%;
+  text-overflow: ellipsis;
+  overflow: hidden;
+  cursor: pointer;
+}
+.topside-checkbox label > span {
+  line-height: var(--topside-checkbox-size);
+  padding-left: var(--topside-checkbox-label-padding-left);
+  padding-right: var(--topside-checkbox-label-padding-right);
+}
+.topside-checkbox input[type=checkbox]:focus-visible ~ span {
+  text-decoration: underline;
+  text-underline-offset: 4px;
+}
+.topside-checkbox.disabled {
+  color: var(--topside-checkbox-color-disabled);
+}
+.topside-checkbox.disabled label {
+  color: var(--topside-checkbox-color-disabled);
+  cursor: not-allowed;
+}
+.topside-checkbox input[type=checkbox] {
+  --active: var(--topside-checkbox-bg-active);
+  --active-inner: var(--topside-checkbox-checkmark-color);
+  --border: var(--topside-checkbox-color-border);
+  --border-hover: var(--topside-checkbox-color-border-hover);
+  --background: var(--topside-checkbox-bg);
+  --disabled: var(--topside-checkbox-bg-disabled);
+  --disabled-inner: var(--topside-checkbox-checkmark-color-disabled);
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  appearance: none;
+  height: var(--topside-checkbox-size);
+  outline: none;
+  display: inline-block;
+  vertical-align: top;
+  position: relative;
+  margin: 0;
+  cursor: pointer;
+  border: 1px solid var(--bc, var(--border));
+  background: var(--b, var(--background));
+  transition: background 0.3s, border-color 0.3s, box-shadow 0.2s;
+}
+.topside-checkbox input[type=checkbox]:indeterminate {
+  background: var(--topside-checkbox-bg-indeterminate);
+  border-color: var(--topside-checkbox-color-indeterminate);
+}
+.topside-checkbox input[type=checkbox]:indeterminate::before {
+  width: calc(var(--topside-checkbox-size) - 2px);
+  line-height: calc(var(--topside-checkbox-size) - 2px);
+  display: inline-block;
+  text-align: center;
+  content: "–";
+  color: var(--topside-checkbox-color-indeterminate);
+  font-weight: bold;
+}
+.topside-checkbox input[type=checkbox]::after {
+  content: "";
+  display: block;
+  left: 0;
+  top: 0;
+  position: absolute;
+  transition: transform 0.3s ease, opacity 0.2s;
+}
+.topside-checkbox input[type=checkbox]:checked {
+  --b: var(--active);
+  --bc: var(--active);
+}
+.topside-checkbox input[type=checkbox]:disabled {
+  --b: var(--disabled);
+  --bc: var(--border);
+  cursor: not-allowed;
+  opacity: 0.85;
+}
+.topside-checkbox input[type=checkbox]:disabled:checked {
+  --b: var(--disabled);
+  --active-inner: var(--disabled-inner);
+}
+.topside-checkbox input[type=checkbox]:hover:not(:checked):not(:disabled) {
+  --bc: var(--border-hover);
+}
+.topside-checkbox input[type=checkbox]:not(.switch) {
+  width: var(--topside-checkbox-size);
+  border-radius: var(--radius-sm, 2px);
+}
+.topside-checkbox input[type=checkbox]:not(.switch)::after {
+  opacity: var(--o, 0);
+  width: var(--topside-checkbox-check-width);
+  height: var(--topside-checkbox-check-height);
+  border: 2px solid var(--active-inner);
+  border-top: 0;
+  border-left: 0;
+  left: var(--topside-checkbox-check-left);
+  top: var(--topside-checkbox-check-top);
+  transform: rotate(var(--r, 20deg));
+}
+.topside-checkbox input[type=checkbox]:checked:not(.switch) {
+  --o: 1;
+  --r: var(--topside-checkbox-check-rotation);
+}
+.topside-checkbox.compact {
+  padding: 0;
+  color: var(--topside-checkbox-text-color);
+}
+.topside-checkbox.compact input[type=checkbox] {
+  height: var(--topside-checkbox-compact-size);
+}
+.topside-checkbox.compact input[type=checkbox]:indeterminate::before {
+  width: calc(var(--topside-checkbox-compact-size) - 2px);
+  line-height: calc(var(--topside-checkbox-compact-size) - 2px);
+}
+.topside-checkbox.compact input[type=checkbox]:not(.switch) {
+  width: var(--topside-checkbox-compact-size);
+}
+.topside-checkbox.compact input[type=checkbox]:not(.switch)::after {
+  left: var(--topside-checkbox-compact-check-left);
+  top: var(--topside-checkbox-compact-check-top);
+}
+.topside-checkbox.compact input[type=checkbox]:focus-visible ~ span {
+  text-underline-offset: 2px;
+}
+.topside-checkbox.compact label > span {
+  line-height: var(--topside-checkbox-compact-size);
+}
+.topside-checkbox *::before,
+.topside-checkbox *::after {
+  box-sizing: inherit;
+}</style>

package/dist/form/checkbox/CheckBox.svelte.d.ts

@@ -0,0 +1,18 @@
+interface Props {
+    label?: string | null;
+    readonly?: boolean;
+    disabled?: boolean;
+    theme?: string;
+    value?: boolean;
+    indeterminate?: boolean;
+    style?: string;
+    compact?: boolean;
+    onchange?: (value: boolean) => void;
+    onfocus?: (event: FocusEvent) => void;
+    onblur?: (event: FocusEvent) => void;
+}
+declare const CheckBox: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type CheckBox = ReturnType<typeof CheckBox>;
+export default CheckBox;