@ticatec/topside-elements 1.0.0

package/dist/form/switch/README.md

@@ -0,0 +1,231 @@
+# Switch Component
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `checkLabel`, `uncheckLabel` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A toggle switch component for binary on/off states. The switch displays labeled "On"/"Off" states with smooth sliding animation and customizable label text. Ideal for enabling or disabling features, toggling settings, and managing boolean preferences.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Switch from "@ticatec/topside-elements/Switch";
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let notificationsEnabled = true;
+</script>
+
+<Switch bind:value={notificationsEnabled} />
+
+<p>Notifications: {notificationsEnabled ? 'On' : 'Off'}</p>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `boolean` | `false` | Toggle state of the switch (supports two-way binding with `bind:value`) |
+| `checkedText` | `string` | `"On"` | Label displayed when the switch is in the checked/on state |
+| `uncheckedText` | `string` | `"Off"` | Label displayed when the switch is in the unchecked/off state |
+| `readonly` | `boolean` | `false` | Whether the switch is read-only (cannot be toggled) |
+| `disabled` | `boolean` | `false` | Whether the switch is disabled |
+
+## Basic Examples
+
+### Toggle Feature On/Off
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let darkMode = false;
+  let autoSave = true;
+  let soundEffects = false;
+</script>
+
+<div class="settings">
+  <Switch label="Dark Mode" bind:value={darkMode} />
+  <p>Dark mode is {darkMode ? 'enabled' : 'disabled'}</p>
+  
+  <Switch label="Auto Save" bind:value={autoSave} />
+  <p>Auto save is {autoSave ? 'enabled' : 'disabled'}</p>
+  
+  <Switch label="Sound Effects" bind:value={soundEffects} />
+  <p>Sound effects are {soundEffects ? 'enabled' : 'disabled'}</p>
+</div>
+
+<style>
+  .settings {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    max-width: 400px;
+  }
+</style>
+```
+
+### Custom Labels
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let wifiEnabled = true;
+</script>
+
+<Switch 
+  bind:value={wifiEnabled} 
+  checkedText="Connected" 
+  uncheckedText="Disconnected" 
+/>
+
+<p>WiFi: {wifiEnabled ? 'Connected' : 'Disconnected'}</p>
+```
+
+### Readonly and Disabled States
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let lockedFeature = true;
+  let readonlyFeature = false;
+</script>
+
+<div class="states-demo">
+  <h3>Normal Switch</h3>
+  <Switch bind:value={lockedFeature} />
+
+  <h3>Read-only Switch</h3>
+  <Switch bind:value={readonlyFeature} readonly />
+
+  <h3>Disabled Switch</h3>
+  <Switch value={lockedFeature} disabled />
+</div>
+
+<style>
+  .states-demo {
+    display: flex;
+    flex-direction: column;
+    gap: 24px;
+    max-width: 400px;
+  }
+</style>
+```
+
+### Settings Panel
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let settings = {
+    darkMode: false,
+    notifications: true,
+    autoUpdate: false,
+    analytics: true
+  };
+</script>
+
+<div class="settings-panel">
+  <h3>Application Settings</h3>
+  
+  <div class="setting-row">
+    <Switch bind:value={settings.darkMode} />
+    <span>Dark Mode</span>
+  </div>
+  
+  <div class="setting-row">
+    <Switch bind:value={settings.notifications} />
+    <span>Notifications</span>
+  </div>
+  
+  <div class="setting-row">
+    <Switch bind:value={settings.autoUpdate} />
+    <span>Auto Update</span>
+  </div>
+  
+  <div class="setting-row">
+    <Switch bind:value={settings.analytics} />
+    <span>Usage Analytics</span>
+  </div>
+</div>
+
+<style>
+  .settings-panel {
+    max-width: 400px;
+    padding: 20px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+  
+  .setting-row {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    margin: 12px 0;
+  }
+</style>
+```
+
+## CSS Custom Properties
+
+The Switch component supports the following CSS custom properties for theming:
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--topside-switch-width` | `100px` | Width of the switch track |
+| `--topside-switch-height` | `30px` | Height of the switch track |
+| `--topside-switch-radius` | `30px` | Border radius (creates pill shape) |
+| `--topside-switch-knob-size` | `22px` | Size of the sliding knob |
+| `--topside-switch-knob-offset` | `5px` | Left offset of the knob |
+| `--topside-switch-color-surface` | `#FFFFFF` | Background color (unchecked) |
+| `--topside-switch-color-border` | `#ADB5BD` | Border color (unchecked) |
+| `--topside-switch-color-knob` | `#ADB5BD` | Knob color (unchecked) |
+| `--topside-switch-color-text-unchecked` | `#6B7280` | Text color (unchecked) |
+| `--topside-switch-color-surface-checked` | `#42A5F5` | Background color (checked) |
+| `--topside-switch-color-border-checked` | `#42A5F5` | Border color (checked) |
+| `--topside-switch-color-knob-checked` | `#FFFFFF` | Knob color (checked) |
+| `--topside-switch-color-text-checked` | `#FFFFFF` | Text color (checked) |
+| `--topside-switch-color-focus-ring` | `#42A5F5` | Focus ring color |
+| `--topside-switch-color-surface-disabled` | `#F1F5F9` | Background color (disabled) |
+| `--topside-switch-color-border-disabled` | `#E2E8F0` | Border color (disabled) |
+| `--topside-switch-color-knob-disabled` | `#CBD5E1` | Knob color (disabled) |
+| `--topside-switch-color-surface-checked-disabled` | `#E2E8F0` | Checked background (disabled) |
+| `--topside-switch-color-border-checked-disabled` | `#E2E8F0` | Checked border (disabled) |
+| `--topside-switch-color-text-disabled` | `#94A3B8` | Text color (disabled) |
+
+## Features
+
+- **Two-way Binding**: Supports `bind:value` for reactive state management
+- **Custom Labels**: Configurable on/off text via `checkedText` and `uncheckedText` props
+- **Smooth Animation**: CSS transition for sliding knob and color changes
+- **Disabled State**: Non-interactive switch with visual feedback
+- **Read-only State**: Display-only mode that prevents toggling
+- **Accessible**: Proper keyboard support and ARIA attributes
+- **CSS Customization**: Extensive CSS custom properties for theming
+
+## Best Practices
+
+1. Use Switch for binary on/off decisions (yes/no, enable/disable)
+2. Provide clear label text explaining what the toggle controls
+3. Consider using `readonly` for settings that cannot be changed in the current context
+4. Use CSS custom properties for consistent theming across your application
+5. Group related switches in a settings panel for better UX
+
+## Related Components
+
+- `CheckBox` - For multiple selection options
+- `RadioButton` - For single selection from mutually exclusive options
+- `GroupCheckBox` - For grouped multi-selection checkboxes
+- `GroupRadioBox` - For grouped single-selection radio buttons

package/dist/form/switch/README_CN.md

@@ -0,0 +1,255 @@
+# 开关组件 (Switch)
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `checkLabel`, `uncheckLabel` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+一个用于二元开/关状态的切换开关组件，支持平滑的滑动动画和自定义标签文字。非常适合启用或禁用功能、切换设置和管理布尔偏好。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Switch from "@ticatec/topside-elements/Switch";
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let 通知开关 = true;
+</script>
+
+<Switch bind:value={通知开关} />
+
+<p>通知：{通知开关 ? '开启' : '关闭'}</p>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `value` | `boolean` | `false` | 开关状态（支持 `bind:value` 双向绑定） |
+| `checkedText` | `string` | `"On"` | 开关打开时显示的标签文字 |
+| `uncheckedText` | `string` | `"Off"` | 开关关闭时显示的标签文字 |
+| `readonly` | `boolean` | `false` | 是否为只读状态（不可切换） |
+| `disabled` | `boolean` | `false` | 是否禁用开关 |
+
+## 基本示例
+
+### 功能开关
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let 深色模式 = false;
+  let 自动保存 = true;
+  let 音效 = false;
+</script>
+
+<div class="设置容器">
+  <Switch bind:value={深色模式} />
+  <p>深色模式：{深色模式 ? '已启用' : '已禁用'}</p>
+  
+  <Switch bind:value={自动保存} />
+  <p>自动保存：{自动保存 ? '已启用' : '已禁用'}</p>
+  
+  <Switch bind:value={音效} />
+  <p>音效：{音效 ? '已启用' : '已禁用'}</p>
+</div>
+
+<style>
+  .设置容器 {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    max-width: 400px;
+  }
+</style>
+```
+
+### 自定义标签文字
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let wifi已连接 = true;
+</script>
+
+<Switch 
+  bind:value={wifi已连接} 
+  checkedText="已连接" 
+  uncheckedText="未连接" 
+/>
+
+<p>WiFi：{wifi已连接 ? '已连接' : '未连接'}</p>
+```
+
+### 只读和禁用状态
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let 锁定功能 = true;
+  let 只读功能 = false;
+</script>
+
+<div class="状态演示">
+  <h3>普通开关</h3>
+  <Switch bind:value={锁定功能} />
+
+  <h3>只读开关</h3>
+  <Switch bind:value={只读功能} readonly />
+
+  <h3>禁用开关</h3>
+  <Switch value={锁定功能} disabled />
+</div>
+
+<style>
+  .状态演示 {
+    display: flex;
+    flex-direction: column;
+    gap: 24px;
+    max-width: 400px;
+  }
+</style>
+```
+
+### 设置面板与变更处理
+
+```svelte
+<script>
+  import Switch from "@ticatec/topside-elements/Switch";
+  
+  let 设置 = {
+    深色模式: false,
+    通知: true,
+    自动更新: false,
+    数据分析: true
+  };
+  
+  const 处理设置变更 = (键名) => (值) => {
+    设置[键名] = 值;
+    console.log(`${键名}: ${值 ? '已启用' : '已禁用'}`);
+    localStorage.setItem('用户设置', JSON.stringify(设置));
+  };
+  
+  // 恢复已保存的设置
+  const 已保存的 = localStorage.getItem('用户设置');
+  if (已保存的) {
+    设置 = JSON.parse(已保存的);
+  }
+</script>
+
+<div class="设置面板">
+  <h3>应用设置</h3>
+  
+  <div class="设置行">
+    <Switch
+      bind:value={设置.深色模式}
+      onchange={处理设置变更('深色模式')}
+    />
+    <span>深色模式</span>
+  </div>
+  
+  <div class="设置行">
+    <Switch
+      bind:value={设置.通知}
+      onchange={处理设置变更('通知')}
+    />
+    <span>通知</span>
+  </div>
+  
+  <div class="设置行">
+    <Switch
+      bind:value={设置.自动更新}
+      onchange={处理设置变更('自动更新')}
+    />
+    <span>自动更新</span>
+  </div>
+  
+  <div class="设置行">
+    <Switch
+      bind:value={设置.数据分析}
+      onchange={处理设置变更('数据分析')}
+    />
+    <span>使用分析</span>
+  </div>
+</div>
+
+<style>
+  .设置面板 {
+    max-width: 400px;
+    padding: 20px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+  
+  .设置行 {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    margin: 12px 0;
+  }
+</style>
+```
+
+## CSS 自定义属性
+
+Switch 组件支持以下 CSS 自定义属性进行主题定制：
+
+| 属性 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-switch-width` | `100px` | 开关轨道宽度 |
+| `--topside-switch-height` | `30px` | 开关轨道高度 |
+| `--topside-switch-radius` | `30px` | 圆角（形成药丸形状） |
+| `--topside-switch-knob-size` | `22px` | 滑动按钮大小 |
+| `--topside-switch-knob-offset` | `5px` | 按钮左侧偏移 |
+| `--topside-switch-color-surface` | `#FFFFFF` | 关闭状态背景色 |
+| `--topside-switch-color-border` | `#ADB5BD` | 关闭状态边框颜色 |
+| `--topside-switch-color-knob` | `#ADB5BD` | 关闭状态按钮颜色 |
+| `--topside-switch-color-text-unchecked` | `#6B7280` | 关闭状态文字颜色 |
+| `--topside-switch-color-surface-checked` | `#42A5F5` | 开启状态背景色 |
+| `--topside-switch-color-border-checked` | `#42A5F5` | 开启状态边框颜色 |
+| `--topside-switch-color-knob-checked` | `#FFFFFF` | 开启状态按钮颜色 |
+| `--topside-switch-color-text-checked` | `#FFFFFF` | 开启状态文字颜色 |
+| `--topside-switch-color-focus-ring` | `#42A5F5` | 聚焦环颜色 |
+| `--topside-switch-color-surface-disabled` | `#F1F5F9` | 禁用状态背景色 |
+| `--topside-switch-color-border-disabled` | `#E2E8F0` | 禁用状态边框颜色 |
+| `--topside-switch-color-knob-disabled` | `#CBD5E1` | 禁用状态按钮颜色 |
+| `--topside-switch-color-surface-checked-disabled` | `#E2E8F0` | 禁用状态下开启状态背景色 |
+| `--topside-switch-color-border-checked-disabled` | `#E2E8F0` | 禁用状态下开启状态边框颜色 |
+| `--topside-switch-color-text-disabled` | `#94A3B8` | 禁用状态文字颜色 |
+
+## 功能特性
+
+- **双向绑定**：支持 `bind:value` 实现响应式状态管理
+- **自定义标签**：通过 `checkedText` 和 `uncheckedText` 属性自定义开/关文字
+- **平滑动画**：滑动按钮和颜色变化的 CSS 过渡动画
+- **禁用状态**：非交互式的禁用开关，带有视觉反馈
+- **只读状态**：仅展示模式的开关，防止用户切换
+- **无障碍访问**：完善的键盘支持和 ARIA 属性
+- **CSS 定制**：丰富的 CSS 自定义属性支持主题化
+
+## 最佳实践
+
+1. 开关组件适用于二元选择（是/否、启用/禁用）
+2. 为每个开关提供清晰的标签，说明所控制的功能
+3. 在需要展示但不可更改的场景中使用 `readonly` 属性
+4. 使用 CSS 自定义属性保持应用内的主题一致性
+5. 将相关的开关分组到设置面板中，提升用户体验
+
+## 相关组件
+
+- `CheckBox` - 用于多选场景
+- `RadioButton` - 用于互斥的单选场景
+- `GroupCheckBox` - 用于分组多选复选框
+- `GroupRadioBox` - 用于分组单选按钮

package/dist/form/switch/Switch.svelte

@@ -0,0 +1,138 @@
+<script lang="ts">
+    interface Props {
+        /** 开启状态显示的文字 */
+        checkedText?: string;
+        /** 关闭状态显示的文字 */
+        uncheckedText?: string;
+        readonly?: boolean;
+        disabled?: boolean;
+        value?: boolean;
+    }
+
+    let {
+        checkedText = "On",
+        uncheckedText = "Off",
+        readonly = false,
+        disabled = false,
+        value = $bindable(false)
+    }: Props = $props();
+
+    const toggleSwitch = (e: MouseEvent) => {
+        if (readonly || disabled) {
+            e.stopPropagation();
+            e.preventDefault();
+        }
+    };
+</script>
+
+<div class="switch-box">
+    <label class="switch" class:readonly class:disabled>
+        <input type="checkbox" bind:checked={value} disabled={disabled} aria-readonly={readonly} onclick={toggleSwitch}>
+        <span class="slider" aria-hidden="true"></span>
+        <span class="text" aria-hidden="true">{value ? uncheckedText : checkedText}</span>
+    </label>
+</div>
+
+<style>
+    .switch-box input[type="checkbox"] {
+        visibility: hidden;
+        display: none;
+    }
+
+    .switch-box,
+    .switch-box::after,
+    .switch-box::before {
+        box-sizing: border-box;
+    }
+
+    .switch-box .switch {
+        font-size: 15px;
+        position: relative;
+        display: inline-block;
+        width: var(--topside-switch-width, 100px);
+        height: var(--topside-switch-height, 30px);
+    }
+
+    .switch-box .switch .text {
+        position: absolute;
+        line-height: var(--topside-switch-height, 30px);
+        right: 10px;
+        color: var(--topside-switch-color-text-unchecked, #6B7280);
+        user-select: none;
+        transition: color 0.3s;
+    }
+
+    .switch-box .switch input {
+        opacity: 0;
+        width: 0;
+        height: 0;
+    }
+
+    .switch-box .slider {
+        position: absolute;
+        cursor: pointer;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background-color: var(--topside-switch-color-surface, #FFFFFF);
+        border: 1px solid var(--topside-switch-color-border, #ADB5BD);
+        transition: .4s;
+        border-radius: var(--topside-switch-radius, 30px);
+    }
+
+    .switch-box .slider::before {
+        position: absolute;
+        content: "";
+        height: var(--topside-switch-knob-size, 22px);
+        width: var(--topside-switch-knob-size, 22px);
+        border-radius: calc(var(--topside-switch-knob-size, 22px) / 2);
+        left: var(--topside-switch-knob-offset, 5px);
+        bottom: 3px;
+        background-color: var(--topside-switch-color-knob, #ADB5BD);
+        transition: .4s;
+    }
+
+    .switch-box input:checked ~ .text {
+        color: var(--topside-switch-color-text-checked, #FFFFFF);
+        left: 10px;
+        right: unset;
+    }
+
+    .switch-box .disabled .text {
+        color: var(--topside-switch-color-text-disabled, #94A3B8);
+    }
+
+    .switch-box input:checked + .slider {
+        background-color: var(--topside-switch-color-surface-checked, #42A5F5);
+        border: 1px solid var(--topside-switch-color-border-checked, #42A5F5);
+    }
+
+    .switch-box input:focus + .slider {
+        box-shadow: 0 0 1px var(--topside-switch-color-focus-ring, #42A5F5);
+    }
+
+    .switch-box input:checked + .slider::before {
+        transform: translateX(65px);
+        background-color: var(--topside-switch-color-knob-checked, #FFFFFF);
+    }
+
+    .switch-box .readonly .slider {
+        cursor: default;
+    }
+
+    .switch-box .disabled .slider {
+        background-color: var(--topside-switch-color-surface-disabled, #F1F5F9);
+        border-color: var(--topside-switch-color-border-disabled, #E2E8F0);
+        cursor: default;
+    }
+
+    .switch-box .disabled .slider::before {
+        background-color: var(--topside-switch-color-knob-disabled, #CBD5E1);
+    }
+
+    .switch-box .disabled input:checked + .slider {
+        background-color: var(--topside-switch-color-surface-checked-disabled, #E2E8F0);
+        border-color: var(--topside-switch-color-border-checked-disabled, #E2E8F0);
+    }
+</style>

package/dist/form/switch/Switch.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    /** 开启状态显示的文字 */
+    checkedText?: string;
+    /** 关闭状态显示的文字 */
+    uncheckedText?: string;
+    readonly?: boolean;
+    disabled?: boolean;
+    value?: boolean;
+}
+declare const Switch: import("svelte").Component<Props, {}, "value">;
+type Switch = ReturnType<typeof Switch>;
+export default Switch;

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

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

package/dist/form/switch/index.js

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