@ticatec/topside-elements 1.0.0

package/dist/form/checkbox/README_CN.md

@@ -0,0 +1,366 @@
+# CheckBox 复选框
+
+用于布尔选择的复选框组件。支持选中、未选中与半选（indeterminate）状态，双向绑定、键盘无障碍访问、紧凑布局，以及通过 CSS 自定义属性进行主题定制。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import CheckBox from "@ticatec/topside-elements/CheckBox";
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let isChecked = $state(false);
+</script>
+
+<CheckBox
+  label="接受条款和条件"
+  bind:value={isChecked}
+  onchange={(value) => console.log("复选框状态变化:", value)}
+/>
+
+<p>状态: {isChecked ? "已同意" : "未同意"}</p>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `label` | `string \| null` | `null` | 复选框旁显示的文本标签 |
+| `value` | `boolean` | — | 选中状态，支持 `bind:value` 双向绑定 |
+| `indeterminate` | `boolean` | `false` | 半选状态（部分选中），由父组件控制 |
+| `readonly` | `boolean` | `false` | 只读：可聚焦，但不可切换 |
+| `disabled` | `boolean` | `false` | 禁用：不可交互，并使用禁用样式 |
+| `compact` | `boolean` | `false` | 紧凑模式，缩小尺寸与内边距 |
+| `theme` | `string` | — | 主题名，会写入根节点的 `data-theme` |
+| `style` | `string` | — | 应用到根容器的内联样式 |
+| `onchange` | `(value: boolean) => void` | — | 选中状态变化时回调，参数为最新布尔值 |
+| `onfocus` | `(event: FocusEvent) => void` | — | 获得焦点时回调 |
+| `onblur` | `(event: FocusEvent) => void` | — | 失去焦点时回调 |
+
+## 方法
+
+| 方法 | 描述 |
+|------|------|
+| `focus()` | 以编程方式使原生 checkbox 获得焦点 |
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let checkbox;
+  let value = $state(false);
+</script>
+
+<button type="button" onclick={() => checkbox?.focus()}>聚焦</button>
+<button type="button" onclick={() => (value = !value)}>切换</button>
+
+<CheckBox bind:this={checkbox} label="程序化控制" bind:value={value} />
+```
+
+## 示例
+
+### 简单复选框
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let agreed = $state(false);
+</script>
+
+<CheckBox label="我同意条款" bind:value={agreed} />
+<p>状态: {agreed ? "已同意" : "未同意"}</p>
+```
+
+### 带变化处理
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let notifications = $state(true);
+
+  function handleNotificationChange(value) {
+    console.log("通知设置:", value ? "启用" : "禁用");
+  }
+</script>
+
+<CheckBox
+  label="启用通知"
+  bind:value={notifications}
+  onchange={handleNotificationChange}
+/>
+```
+
+### 半选状态（全选）
+
+`indeterminate` 用于部分选中场景（例如子项只选中一部分时的“全选”）。父组件需要自行计算并同步 `value` 与 `indeterminate`。
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let childItems = $state([
+    { id: 1, name: "项目 1", checked: true },
+    { id: 2, name: "项目 2", checked: false },
+    { id: 3, name: "项目 3", checked: true },
+  ]);
+
+  let checkedCount = $derived(childItems.filter((item) => item.checked).length);
+  let parentChecked = $derived(checkedCount === childItems.length);
+  let parentIndeterminate = $derived(
+    checkedCount > 0 && checkedCount < childItems.length
+  );
+
+  function handleParentChange(value) {
+    childItems = childItems.map((item) => ({ ...item, checked: value }));
+  }
+
+  function handleChildChange(id, value) {
+    childItems = childItems.map((item) =>
+      item.id === id ? { ...item, checked: value } : item
+    );
+  }
+</script>
+
+<CheckBox
+  label="全选"
+  value={parentChecked}
+  indeterminate={parentIndeterminate}
+  onchange={handleParentChange}
+/>
+
+{#each childItems as item (item.id)}
+  <div style="margin-left: 20px;">
+    <CheckBox
+      label={item.name}
+      bind:value={item.checked}
+      onchange={(value) => handleChildChange(item.id, value)}
+    />
+  </div>
+{/each}
+```
+
+### 禁用与只读
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+</script>
+
+<CheckBox label="禁用未选中" value={false} disabled />
+<CheckBox label="禁用已选中" value={true} disabled />
+
+<CheckBox label="只读未选中" value={false} readonly />
+<CheckBox label="只读已选中" value={true} readonly />
+```
+
+### 紧凑模式
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let normalValue = $state(false);
+  let compactValue = $state(false);
+</script>
+
+<div style="display: flex; gap: 16px; align-items: center;">
+  <CheckBox label="普通" bind:value={normalValue} />
+  <CheckBox label="紧凑" bind:value={compactValue} compact />
+</div>
+```
+
+### 事件处理
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let value = $state(false);
+  let focusCount = $state(0);
+</script>
+
+<CheckBox
+  label="交互式复选框"
+  bind:value={value}
+  onchange={(newValue) => console.log("值变化为:", newValue)}
+  onfocus={() => {
+    focusCount += 1;
+    console.log("复选框获得焦点");
+  }}
+  onblur={() => console.log("复选框失去焦点")}
+/>
+
+<p>当前值: {value}</p>
+<p>聚焦次数: {focusCount}</p>
+```
+
+### 表单集成
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+
+  let formData = $state({
+    newsletter: false,
+    terms: false,
+    privacy: false,
+  });
+
+  let canSubmit = $derived(formData.terms && formData.privacy);
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    if (canSubmit) {
+      console.log("表单提交:", formData);
+    }
+  }
+</script>
+
+<form onsubmit={handleSubmit}>
+  <CheckBox
+    label="订阅邮件（可选）"
+    bind:value={formData.newsletter}
+  />
+  <CheckBox
+    label="我接受服务条款 *"
+    bind:value={formData.terms}
+  />
+  <CheckBox
+    label="我接受隐私政策 *"
+    bind:value={formData.privacy}
+  />
+
+  <button type="submit" disabled={!canSubmit}>提交</button>
+</form>
+```
+
+### 自定义样式
+
+```svelte
+<script>
+  import CheckBox from "@ticatec/topside-elements/CheckBox";
+</script>
+
+<CheckBox
+  label="自定义样式复选框"
+  value={true}
+  style="padding: 12px; background: #f0f8ff; border: 2px solid #007acc; border-radius: 8px; font-weight: 500;"
+/>
+```
+
+## 行为说明
+
+1. **切换**：点击方框或标签可在选中 / 未选中间切换（`readonly` 或 `disabled` 时除外）。
+2. **绑定**：`bind:value` 与原生 checkbox 的 `checked` 状态同步。
+3. **变更回调**：`onchange` 在状态更新后收到最新布尔值。
+4. **半选**：`indeterminate={true}` 会设置原生 indeterminate 外观；父组件应在全选或全不选时清除该状态。
+5. **只读**：点击无效，但仍可聚焦。
+6. **禁用**：点击无效，使用禁用样式，并在 input 上设置原生 `disabled`。
+7. **紧凑模式**：使用 compact 相关 CSS 变量定义的更小尺寸。
+8. **主题**：`theme` 会写入根元素的 `data-theme`，便于主题样式覆盖。
+
+## CSS 自定义属性
+
+CheckBox 通过 CSS 自定义属性进行主题定制（下列为浅色主题默认值）：
+
+| 属性 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-checkbox-text-color` | `#374151` | 标签文字颜色 |
+| `--topside-checkbox-color-border` | `#BBC1E1` | 未选中边框色 |
+| `--topside-checkbox-color-border-hover` | `#409EFF` | 悬停边框色 |
+| `--topside-checkbox-color-disabled` | `#94A3B8` | 禁用文字颜色 |
+| `--topside-checkbox-bg` | `#FFFFFF` | 未选中背景 |
+| `--topside-checkbox-bg-active` | `#409EFF` | 选中背景 |
+| `--topside-checkbox-bg-disabled` | `#F1F5F9` | 禁用背景 |
+| `--topside-checkbox-checkmark-color` | `#FFFFFF` | 对勾颜色 |
+| `--topside-checkbox-checkmark-color-disabled` | `#94A3B8` | 禁用对勾颜色 |
+| `--topside-checkbox-bg-indeterminate` | `rgba(64, 158, 255, 0.2)` | 半选背景 |
+| `--topside-checkbox-color-indeterminate` | `#409EFF` | 半选横杠 / 边框色 |
+| `--topside-checkbox-size` | `21px` | 方框尺寸 |
+| `--topside-checkbox-padding` | `4px` | 外层内边距 |
+| `--topside-checkbox-label-padding-left` | `2px` | 标签左内边距 |
+| `--topside-checkbox-label-padding-right` | `6px` | 标签右内边距 |
+| `--topside-checkbox-check-width` | `5px` | 对勾宽度 |
+| `--topside-checkbox-check-height` | `9px` | 对勾高度 |
+| `--topside-checkbox-check-left` | `7px` | 对勾左边距 |
+| `--topside-checkbox-check-top` | `4px` | 对勾上边距 |
+| `--topside-checkbox-check-rotation` | `43deg` | 选中时对勾旋转角度 |
+| `--topside-checkbox-compact-size` | `17px` | 紧凑模式方框尺寸 |
+| `--topside-checkbox-compact-check-left` | `5px` | 紧凑模式对勾左边距 |
+| `--topside-checkbox-compact-check-top` | `2px` | 紧凑模式对勾上边距 |
+
+覆盖示例：
+
+```css
+.my-checkbox-area {
+  --topside-checkbox-bg-active: #10b981;
+  --topside-checkbox-color-border-hover: #10b981;
+  --topside-checkbox-size: 18px;
+}
+```
+
+## 无障碍访问
+
+- 使用原生 `input[type="checkbox"]`，语义正确，便于辅助技术识别
+- 通过包裹的 `<label>` 关联标签文字
+- 键盘支持：
+  - **Tab** — 移入 / 移出焦点
+  - **Space** — 聚焦时切换状态（浏览器默认行为）
+- **焦点指示**：键盘聚焦（`:focus-visible`）时，标签文字显示下划线，偏移 4px（紧凑模式为 2px）；方框本身样式不变
+- 只读与禁用交互在组件内被拦截
+- 半选状态会同步到原生 input，保证视觉与无障碍行为一致
+
+### 最佳实践
+
+```svelte
+<!-- 使用清晰、可理解的标签 -->
+<CheckBox label="启用双重认证" />
+
+<!-- 相关选项分组 -->
+<fieldset>
+  <legend>通知偏好</legend>
+  <CheckBox label="邮件通知" bind:value={email} />
+  <CheckBox label="短信通知" bind:value={sms} />
+  <CheckBox label="推送通知" bind:value={push} />
+</fieldset>
+
+<!-- 明确标识必选项 -->
+<CheckBox label="我同意服务条款 *" bind:value={terms} />
+```
+
+## 功能特性
+
+- 选中 / 未选中 / 半选状态
+- `bind:value` 双向绑定
+- `onchange`、`onfocus`、`onblur` 回调
+- 只读与禁用模式
+- 紧凑布局
+- 通过 `data-theme` 挂载主题
+- `focus()` 程序化聚焦
+- 完整 CSS 自定义属性主题体系
+
+## 浏览器支持
+
+- 支持完整表单控件的现代浏览器
+- 兼容 Svelte 5+
+- 响应式与触控友好
+
+## 相关组件
+
+- `Switch` — 二元开 / 关滑动开关
+- `RadioButton` — 互斥单选
+- `GroupCheckBox` — 分组多选复选框
+- `GroupRadioBox` — 分组单选按钮

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

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

package/dist/form/checkbox/index.js

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

package/dist/form/color_picker/ColorPicker.svelte

@@ -0,0 +1,173 @@
+<script lang="ts">
+
+    import CommonPicker from "../common_editor/CommonPicker.svelte";
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+
+    interface Props extends CommonFieldProps {
+        value?: string;
+    }
+
+    // The manually-typed value must resolve to exactly #RRGGBB. An 8-digit #RRGGBBAA
+    // form was supported briefly, but <input type="color"> has no concept of alpha —
+    // the swatch always showed just the RGB portion and nothing in the UI ever
+    // rendered the transparency, so the last 2 digits had no visible effect. Dropped
+    // rather than half-implemented; revisit with a real alpha-aware swatch (checkered
+    // background + rgba preview) if this is needed later.
+    const HEX_PATTERN = /^#[0-9a-fA-F]{6}$/;
+    const DEFAULT_SWATCH = '#000000';
+
+    // CommonPicker always renders its own internal <input> in the non-readonly branch,
+    // even when a `children` snippet is also supplied — it doesn't apply the same
+    // "children replaces the default input" rule that its readonly branch does. Every
+    // other consumer works around this by never passing `children` in the first place
+    // (DatePicker, OptionsSelect...) except OptionsMultiSelect, which needs custom
+    // content (its tag list) the same way ColorPicker needs its swatch+hex layout —
+    // it hides CommonPicker's own input via `input$style` (shrink to 1x1, transparent,
+    // click-through) so only the custom children are visible. Same fix here: without
+    // this, edit mode showed CommonPicker's own empty input fighting for space with our
+    // swatch, while readonly mode (which only renders `children`) looked correct.
+    const HIDDEN_INTERNAL_INPUT_STYLE = 'position: absolute; left: 0; top: 0; width: 1px; height: 1px; opacity: 0; pointer-events: none';
+
+    let {
+        variant,
+        theme,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        value = $bindable<string | undefined>("#000000"),
+        style,
+        placeholder,
+        error,
+        tooltip,
+        onchange,
+        onfocus,
+        onblur
+    }: Props = $props();
+
+    let editor: HTMLInputElement | undefined = $state();
+    let textInput: HTMLInputElement | undefined = $state();
+
+    // Editing buffer for the manual hex field, kept separate from `value` so the user
+    // can type through transient/incomplete states (e.g. "#3b8") without every
+    // keystroke being validated against the full #RRGGBB format — validation only
+    // happens on commit (blur / Enter).
+    let textValue = $state(value ?? '');
+
+    $effect(() => {
+        textValue = value ?? '';
+    });
+
+    let swatchValue = $derived(value && HEX_PATTERN.test(value) ? value : DEFAULT_SWATCH);
+
+    export function focus() {
+        editor?.focus();
+    }
+
+    const clean = () => {
+        value = undefined;
+        onchange?.(undefined);
+    }
+
+    const handleActionIconClick = () => {
+        if (!readonly && !disabled) {
+            editor?.click();
+        }
+    }
+
+    const handleSwatchChange = (event: Event) => {
+        const newValue = (event.target as HTMLInputElement).value;
+        value = newValue;
+        onchange?.(newValue);
+    }
+
+    // The native color picker dialog opens on `click`, and preventing the default
+    // action here blocks it — this is the only reliable way to make the swatch
+    // non-interactive for `readonly`, since <input type="color"> ignores the
+    // `readonly` attribute entirely. Using the native `disabled` attribute instead
+    // would work too, but it also greys the swatch out, which conflates readonly
+    // with disabled (see the component README: readonly stays fully visible,
+    // disabled is dimmed).
+    const handleColorInputClick = (event: MouseEvent) => {
+        if (readonly) {
+            event.preventDefault();
+        }
+    }
+
+    const handleColorInputKeydown = (event: KeyboardEvent) => {
+        if (readonly && (event.key === 'Enter' || event.key === ' ')) {
+            event.preventDefault();
+        }
+    }
+
+    const commitTextValue = () => {
+        let candidate = textValue.trim();
+        if (candidate && !candidate.startsWith('#')) {
+            candidate = `#${candidate}`;
+        }
+        if (HEX_PATTERN.test(candidate)) {
+            textValue = candidate;
+            if (candidate !== value) {
+                value = candidate;
+                onchange?.(candidate);
+            }
+        } else {
+            // Doesn't resolve to a valid #RRGGBB value on commit — revert to the last
+            // known-good value rather than accepting a malformed color.
+            textValue = value ?? '';
+        }
+    }
+
+    // Only '#' and hex digits are allowed while typing; the exact length requirement
+    // is enforced separately on commit (see commitTextValue), since rejecting
+    // incomplete input on every keystroke would make it impossible to type a value
+    // character by character.
+    const handleTextKeydown = (event: KeyboardEvent) => {
+        const allowKeys = ['Backspace', 'Delete', 'Tab', 'ArrowLeft', 'ArrowRight', 'Home', 'End'];
+        if (allowKeys.includes(event.key) || event.metaKey || event.ctrlKey) return;
+        if (event.key === 'Enter') {
+            event.preventDefault();
+            textInput?.blur();
+            return;
+        }
+        if (event.key === 'Escape') {
+            textValue = value ?? '';
+            textInput?.blur();
+            return;
+        }
+        if (!/^[0-9a-fA-F#]$/.test(event.key)) {
+            event.preventDefault();
+        }
+    }
+
+    const handleTextPaste = (event: ClipboardEvent) => {
+        const pasted = event.clipboardData?.getData('text') ?? '';
+        if (/[^0-9a-fA-F#]/.test(pasted)) {
+            event.preventDefault();
+        }
+    }
+
+    // Defense in depth against anything that bypasses handleTextKeydown (IME, mobile
+    // virtual keyboards, drag-and-drop text) — strip disallowed characters and cap at
+    // one leading '#' plus 6 hex digits.
+    const handleTextInput = () => {
+        const hasHash = textValue.startsWith('#');
+        const hexOnly = textValue.replace(/#/g, '').replace(/[^0-9a-fA-F]/g, '').slice(0, 6);
+        const sanitized = (hasHash ? '#' : '') + hexOnly;
+        if (sanitized !== textValue) {
+            textValue = sanitized;
+        }
+    }
+
+</script>
+
+<CommonPicker {variant} {style} {theme} {error} {tooltip} {compact} {placeholder} class="multiple" iconName="icon_google_color_lens"
+              autoFit clear={clean} textValue={value} {readonly} {disabled} {onfocus} {onblur} onIconClick={handleActionIconClick}
+              input$style={HIDDEN_INTERNAL_INPUT_STYLE}>
+    <div style="width: 100%; display: flex; overflow: hidden; flex-direction: row; align-items: center; height: 100%; gap: 8px">
+        <input bind:this={editor} style="flex: 0 0 auto; width: 40%; height: 80%; border-radius: 8px;" type="color" value={swatchValue} {disabled}
+               tabindex={readonly ? -1 : 0} onclick={handleColorInputClick} onkeydown={handleColorInputKeydown} onchange={handleSwatchChange}/>
+        <input bind:this={textInput} style="flex: 0 0 auto; width: 50%; text-align: center" class="text-editor" bind:value={textValue}
+               readonly={readonly} {disabled} {placeholder} maxlength="7" spellcheck="false" autocomplete="off"
+               onblur={commitTextValue} onkeydown={handleTextKeydown} onpaste={handleTextPaste} oninput={handleTextInput}/>
+    </div>
+</CommonPicker>

package/dist/form/color_picker/ColorPicker.svelte.d.ts

@@ -0,0 +1,9 @@
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+interface Props extends CommonFieldProps {
+    value?: string;
+}
+declare const ColorPicker: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type ColorPicker = ReturnType<typeof ColorPicker>;
+export default ColorPicker;