@ticatec/topside-elements 1.0.0

package/dist/general/button/README.md

@@ -0,0 +1,361 @@
+# Button Component
+
+A versatile button component with multiple variants, sizes, and types, supporting icons, tooltips, custom styling, and comprehensive event handling.
+
+## Features
+
+- **Multiple Types**: Default, primary, secondary, third, and forth button styles
+- **Size Options**: Big, medium, and small sizes
+- **Icon Support**: Optional icon display with flexible positioning
+- **Variant Styles**: Plain and round variants
+- **Tooltip Support**: Built-in tooltip via `data-tip` attribute
+- **Keyboard Accessible**: Full Tab focus support with visible focus state
+- **Event Handling**: Click event support with disabled state protection
+- **Accessibility**: Proper semantic button element with disabled state
+- **Custom Styling**: Flexible style customization via inline styles and CSS variables
+- **Theming**: Theme name prop + token-based CSS variables for full color customization
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Button from '@ticatec/topside-elements/Button';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  const handleClick = (event) => {
+    console.log('Button clicked!', event);
+  };
+</script>
+
+<Button
+  label="Click Me"
+  type="primary"
+  onclick={handleClick}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'` | `'default'` | Button type/style variant |
+| `label` | `string` | `''` | Button text label. Ignored when `children` is provided. |
+| `variant` | `'plain' \| 'round' \| ''` | `''` | Button variant style (plain = sharp corners, round = pill shape) |
+| `disabled` | `boolean` | `false` | Whether the button is disabled (prevents click events, hides tooltip, removes from tab order) |
+| `size` | `'big' \| 'medium' \| 'small'` | `'medium'` | Button size |
+| `onclick` | `(event: MouseEvent) => void` | - | Click event handler (not fired when disabled) |
+| `icon` | `string \| null` | `null` | CSS icon class name (e.g., `icon_google_save`). Rendered as `<i class={icon}>` before the label. |
+| `theme` | `string` | - | Theme variant name; appended as an extra CSS class on the button for scoped overrides |
+| `tooltip` | `string` | - | Tooltip text shown on hover. Suppressed when `disabled={true}`. |
+| `style` | `string` | `''` | Custom inline CSS styles applied to the `<button>` element |
+| `autofocus` | `boolean` | `false` | Whether to auto-focus the button on mount |
+| `children` | `Snippet` | - | Custom content snippet. Takes precedence over `label` when both are provided. |
+| `data-*` | `any` | - | Any `data-*` attribute is passed through to the underlying `<button>` |
+
+## Events
+
+| Event | Parameters | Description |
+|-------|------------|-------------|
+| `onclick` | `event: MouseEvent` | Fired when button is clicked. Blocked when `disabled={true}` (handler also calls `preventDefault` + `stopPropagation` in that case). |
+
+## Content Priority
+
+When more than one content source is provided, the button uses this priority:
+
+1. `children` — if present, renders the snippet and ignores `label`.
+2. `label` — rendered as `<span style="flex: 1 1 auto">{label}</span>` when non-empty and no `children`.
+
+`icon` is independent: if non-null, it's always rendered before the content.
+
+```svelte
+<!-- icon + label -->
+<Button icon="icon_google_save" label="Save" />
+
+<!-- icon + children (label ignored) -->
+<Button icon="icon_google_save" label="Ignored">
+  <strong>Custom</strong> content
+</Button>
+```
+
+## Basic Examples
+
+### Simple Button
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  const handleSave = () => {
+    console.log('Save clicked');
+  };
+</script>
+
+<Button label="Save" type="primary" onclick={handleSave} />
+```
+
+### Button with Icon
+
+```svelte
+<Button
+  label="Save"
+  icon="icon_google_save"
+  type="primary"
+  tooltip="Save (Ctrl+S)"
+  onclick={handleSave}
+/>
+```
+
+### Icon-Only Button (no label)
+
+```svelte
+<Button
+  icon="icon_google_add"
+  tooltip="Add new item"
+  onclick={handleAdd}
+/>
+```
+
+## Detailed Examples
+
+### Form Submit Button with Loading State
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  let isSubmitting = false;
+
+  const handleSubmit = async () => {
+    isSubmitting = true;
+    try {
+      await submitForm();
+    } finally {
+      isSubmitting = false;
+    }
+  };
+</script>
+
+<Button
+  label={isSubmitting ? 'Submitting...' : 'Submit'}
+  type="primary"
+  disabled={isSubmitting}
+  icon={isSubmitting ? '' : 'icon_google_save'}
+  tooltip={isSubmitting ? 'Please wait...' : 'Submit form'}
+  onclick={handleSubmit}
+/>
+```
+
+### Two-Click Confirmation Delete
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  let showConfirm = false;
+
+  const handleDelete = () => {
+    if (showConfirm) {
+      console.log('Deleting...');
+      showConfirm = false;
+    } else {
+      showConfirm = true;
+      setTimeout(() => (showConfirm = false), 3000);
+    }
+  };
+</script>
+
+<Button
+  label={showConfirm ? 'Click Again to Confirm' : 'Delete'}
+  type={showConfirm ? 'primary' : 'secondary'}
+  icon="icon_google_delete"
+  tooltip={showConfirm ? 'Confirm delete' : 'Delete item'}
+  onclick={handleDelete}
+/>
+```
+
+### Custom Content via Children Snippet
+
+```svelte
+<Button type="primary" onclick={handleClick}>
+  <i class="icon_google_cloud"></i>
+  <span style="display: flex; flex-direction: column; line-height: 1.1; text-align: left;">
+    <strong>Sync</strong>
+    <small style="font-size: 11px; opacity: 0.75;">Cloud storage</small>
+  </span>
+</Button>
+```
+
+## Button Types
+
+The component supports five button types for visual hierarchy:
+
+```svelte
+<Button label="Default" type="default" onclick={handleClick} />
+<Button label="Primary" type="primary" onclick={handleClick} />
+<Button label="Secondary" type="secondary" onclick={handleClick} />
+<Button label="Third" type="third" onclick={handleClick} />
+<Button label="Forth" type="forth" onclick={handleClick} />
+```
+
+## Button Sizes
+
+Three size options are available:
+
+```svelte
+<Button label="Small" size="small" onclick={handleClick} />
+<Button label="Medium" size="medium" onclick={handleClick} />
+<Button label="Big" size="big" onclick={handleClick} />
+```
+
+## Button Variants
+
+Two visual variants modify the button shape:
+
+```svelte
+<Button label="Default radius" onclick={handleClick} />
+<Button label="Plain" variant="plain" onclick={handleClick} />
+<Button label="Round" variant="round" onclick={handleClick} />
+```
+
+## Disabled State
+
+```svelte
+<Button
+  label="Disabled"
+  disabled={true}
+  tooltip="This button is disabled"
+/>
+```
+
+Disabled buttons:
+- Cannot be clicked (`onclick` not fired; click handler calls `preventDefault` + `stopPropagation`)
+- Are not keyboard-focusable (`tabindex="-1"`)
+- Do not show tooltips (`data-tip` is nulled)
+- Display with disabled visual styling (gray surface, `cursor: not-allowed`)
+
+## DOM Structure & CSS Classes
+
+Rendered output:
+
+```html
+<button
+  class="topside-button common-button {variant} {size} {type} {theme}"
+  class:disabled
+  tabindex="0|-1"
+  data-tip="..."
+>
+  <i class="{icon}"></i>          <!-- only when icon != null -->
+  <span style="flex: 1 1 auto">{label}</span>   <!-- when no children, label non-empty -->
+  <!-- or {@render children()} -->
+</button>
+```
+
+Override styles by targeting these classes:
+
+```css
+/* All Buttons */
+.topside-button { ... }
+
+/* Only the standard label-button (not IconButton / TextButton) */
+.topside-button.common-button { ... }
+
+/* Specific type */
+.topside-button.primary { ... }
+.topside-button.secondary:hover { ... }
+
+/* Specific size */
+.topside-button.small { ... }
+.topside-button.big { ... }
+
+/* Variant */
+.topside-button.round { ... }
+.topside-button.plain { ... }
+
+/* Disabled */
+.topside-button.disabled { ... }
+
+/* Custom theme name passed via `theme="my-theme"` */
+.topside-button.my-theme { ... }
+```
+
+## Theming via CSS Variables
+
+All colors are driven by CSS variables, so you can theme the button globally or per-scope:
+
+```css
+:root {
+  /* Plain (default) */
+  --topside-button-plain-color: #374151;
+  --topside-button-plain-color-surface: #ffffff;
+  --topside-button-plain-color-surface-hover: #f3f4f6;
+  --topside-button-plain-color-surface-active: #e5e7eb;
+  --topside-button-plain-border-color: #d1d5db;
+
+  /* Primary */
+  --topside-button-primary-color: #ffffff;
+  --topside-button-primary-color-surface: #2563eb;
+  --topside-button-primary-color-surface-hover: #1d4ed8;
+  --topside-button-primary-color-surface-active: #1e40af;
+  --topside-button-primary-border-color: #2563eb;
+
+  /* Secondary / Third / Forth — same surface/hover/active/border pattern */
+  --topside-button-secondary-color: ...;
+  --topside-button-third-color: ...;
+  --topside-button-forth-color: ...;
+
+  /* Disabled */
+  --topside-button-disabled-color: #9ca3af;
+  --topside-button-disabled-color-surface: #f3f4f6;
+  --topside-button-disabled-border-color: #e5e7eb;
+
+  /* Geometry */
+  --topside-button-height: 32px;
+  --topside-button-height-big: 40px;
+  --topside-button-height-small: 26px;
+  --topside-button-minimal-size: 64px;
+  --topside-button-margin: 12px;
+  --topside-button-spacing: 6px;
+  --topside-button-radius-round: 999px;
+  --topside-button-color-gap: #ffffff; /* focus ring inner gap */
+}
+```
+
+Scope a theme with the `theme` prop and a matching CSS selector:
+
+```svelte
+<Button theme="danger" label="Delete" type="primary" />
+```
+
+```css
+.topside-button.danger.primary {
+  --topside-button-primary-color-surface: #dc2626;
+  --topside-button-primary-color-surface-hover: #b91c1c;
+  --topside-button-primary-color-surface-active: #991b1b;
+}
+```
+
+## Accessibility
+
+The Button component follows accessibility best practices:
+- Uses semantic `<button>` element
+- Supports keyboard navigation (Tab, Enter, Space)
+- Visible focus ring via `:focus-visible` box-shadow
+- Proper disabled state handling (`disabled` attr + `tabindex="-1"` + visual styling)
+- Tooltip via `data-tip` attribute (consumed by the app-level tooltip overlay)
+- `autofocus` for programmatic focus management
+
+## Related Components
+
+- [IconButton](./IconButton_README.md) — round, icon-only button
+- [TextButton](./TextButton_README.md) — borderless text-only button

package/dist/general/button/README_CN.md

@@ -0,0 +1,357 @@
+# Button 按钮组件
+
+一个功能丰富的按钮组件，支持多种类型、尺寸和变体，内置图标、提示框和自定义样式支持。
+
+## 功能特性
+
+- **多种类型**：默认、主要、次要、第三级、第四级五种按钮样式
+- **尺寸选项**：大、中、小三种尺寸
+- **图标支持**：可选图标，渲染在文字之前
+- **变体样式**：平面（plain，无圆角）和圆角（round，胶囊形）
+- **提示框支持**：通过 `data-tip` 属性内置提示框
+- **键盘访问**：完整的 Tab 焦点支持，焦点状态可见
+- **事件处理**：点击事件支持，禁用状态下自动拦截
+- **无障碍访问**：语义化按钮元素，正确处理禁用状态
+- **自定义样式**：内联 style + CSS 变量双层定制
+- **主题化**：`theme` 属性 + 基于 CSS 变量的颜色令牌
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Button from '@ticatec/topside-elements/Button';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  const handleClick = (event) => {
+    console.log('按钮被点击!', event);
+  };
+</script>
+
+<Button
+  label="点击我"
+  type="primary"
+  onclick={handleClick}
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `type` | `'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'` | `'default'` | 按钮类型/样式变体 |
+| `label` | `string` | `''` | 按钮文本标签。提供 `children` 时本字段被忽略 |
+| `variant` | `'plain' \| 'round' \| ''` | `''` | 按钮形状变体（plain = 无圆角，round = 胶囊圆角） |
+| `disabled` | `boolean` | `false` | 是否禁用（拦截点击、隐藏 tooltip、移出 Tab 序列） |
+| `size` | `'big' \| 'medium' \| 'small'` | `'medium'` | 按钮尺寸 |
+| `onclick` | `(event: MouseEvent) => void` | - | 点击事件处理器（禁用时不触发） |
+| `icon` | `string \| null` | `null` | CSS 图标类名（如 `icon_google_save`），渲染为 `<i class={icon}>`，置于文字之前 |
+| `theme` | `string` | - | 主题名；追加为按钮的额外 CSS 类，便于做局部样式覆盖 |
+| `tooltip` | `string` | - | 悬停提示框文本。`disabled={true}` 时自动隐藏 |
+| `style` | `string` | `''` | 应用到 `<button>` 上的内联 CSS |
+| `autofocus` | `boolean` | `false` | 挂载时是否自动聚焦 |
+| `children` | `Snippet` | - | 自定义内容片段。同时提供 `label` 时优先使用 `children` |
+| `data-*` | `any` | - | 任意 `data-*` 属性会透传到内部 `<button>` 元素 |
+
+## 事件
+
+| 事件 | 参数 | 描述 |
+|------|------|-------------|
+| `onclick` | `event: MouseEvent` | 按钮被点击时触发。`disabled={true}` 时不触发（同时会调用 `preventDefault` + `stopPropagation`） |
+
+## 内容优先级
+
+同时提供多种内容来源时，按以下优先级渲染：
+
+1. `children` —— 若提供，渲染 snippet，忽略 `label`
+2. `label` —— 无 `children` 且非空时，渲染为 `<span style="flex: 1 1 auto">{label}</span>`
+
+`icon` 是独立的：只要不为 `null`，就总是渲染在内容之前。
+
+```svelte
+<!-- icon + label -->
+<Button icon="icon_google_save" label="保存" />
+
+<!-- icon + children（label 被忽略） -->
+<Button icon="icon_google_save" label="被忽略">
+  <strong>自定义</strong> 内容
+</Button>
+```
+
+## 基本示例
+
+### 简单按钮
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  const handleSave = () => {
+    console.log('保存成功');
+  };
+</script>
+
+<Button label="保存" type="primary" onclick={handleSave} />
+```
+
+### 带图标的按钮
+
+```svelte
+<Button
+  label="保存"
+  icon="icon_google_save"
+  type="primary"
+  tooltip="保存 (Ctrl+S)"
+  onclick={handleSave}
+/>
+```
+
+### 纯图标按钮（无文字）
+
+```svelte
+<Button
+  icon="icon_google_add"
+  tooltip="添加新项目"
+  onclick={handleAdd}
+/>
+```
+
+## 详细示例
+
+### 表单提交按钮（带加载状态）
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  let isSubmitting = false;
+
+  const handleSubmit = async () => {
+    isSubmitting = true;
+    try {
+      await submitForm();
+    } finally {
+      isSubmitting = false;
+    }
+  };
+</script>
+
+<Button
+  label={isSubmitting ? '提交中...' : '提交'}
+  type="primary"
+  disabled={isSubmitting}
+  icon={isSubmitting ? '' : 'icon_google_save'}
+  tooltip={isSubmitting ? '请稍候...' : '提交表单'}
+  onclick={handleSubmit}
+/>
+```
+
+### 二次确认删除按钮
+
+```svelte
+<script>
+  import Button from '@ticatec/topside-elements/Button';
+
+  let showConfirm = false;
+
+  const handleDelete = () => {
+    if (showConfirm) {
+      console.log('正在删除...');
+      showConfirm = false;
+    } else {
+      showConfirm = true;
+      setTimeout(() => (showConfirm = false), 3000);
+    }
+  };
+</script>
+
+<Button
+  label={showConfirm ? '再次点击确认' : '删除'}
+  type={showConfirm ? 'primary' : 'secondary'}
+  icon="icon_google_delete"
+  tooltip={showConfirm ? '确认删除' : '删除项目'}
+  onclick={handleDelete}
+/>
+```
+
+### 通过 children 自定义内容
+
+```svelte
+<Button type="primary" onclick={handleClick}>
+  <i class="icon_google_cloud"></i>
+  <span style="display: flex; flex-direction: column; line-height: 1.1; text-align: left;">
+    <strong>同步</strong>
+    <small style="font-size: 11px; opacity: 0.75;">云端存储</small>
+  </span>
+</Button>
+```
+
+## 按钮类型
+
+五种类型用于区分操作优先级：
+
+```svelte
+<Button label="默认" type="default" onclick={handleClick} />
+<Button label="主要" type="primary" onclick={handleClick} />
+<Button label="次要" type="secondary" onclick={handleClick} />
+<Button label="第三级" type="third" onclick={handleClick} />
+<Button label="第四级" type="forth" onclick={handleClick} />
+```
+
+## 按钮尺寸
+
+```svelte
+<Button label="小型" size="small" onclick={handleClick} />
+<Button label="中型" size="medium" onclick={handleClick} />
+<Button label="大型" size="big" onclick={handleClick} />
+```
+
+## 按钮变体
+
+```svelte
+<Button label="默认圆角" onclick={handleClick} />
+<Button label="平面" variant="plain" onclick={handleClick} />
+<Button label="圆角" variant="round" onclick={handleClick} />
+```
+
+## 禁用状态
+
+```svelte
+<Button
+  label="已禁用"
+  disabled={true}
+  tooltip="此按钮已禁用"
+/>
+```
+
+禁用状态的按钮：
+- 无法点击（不触发 `onclick`，点击处理器会调用 `preventDefault` + `stopPropagation`）
+- 不可键盘聚焦（`tabindex="-1"`）
+- 不显示提示框（`data-tip` 被置为 null）
+- 显示禁用样式（灰底，`cursor: not-allowed`）
+
+## DOM 结构与 CSS 类
+
+实际渲染产物：
+
+```html
+<button
+  class="topside-button common-button {variant} {size} {type} {theme}"
+  class:disabled
+  tabindex="0|-1"
+  data-tip="..."
+>
+  <i class="{icon}"></i>          <!-- icon != null 时才有 -->
+  <span style="flex: 1 1 auto">{label}</span>   <!-- 无 children 且 label 非空时 -->
+  <!-- 或 {@render children()} -->
+</button>
+```
+
+按这些类名做样式覆盖：
+
+```css
+/* 所有 Button */
+.topside-button { ... }
+
+/* 仅标准带文字按钮（不含 IconButton / TextButton） */
+.topside-button.common-button { ... }
+
+/* 指定类型 */
+.topside-button.primary { ... }
+.topside-button.secondary:hover { ... }
+
+/* 指定尺寸 */
+.topside-button.small { ... }
+.topside-button.big { ... }
+
+/* 指定形状 */
+.topside-button.round { ... }
+.topside-button.plain { ... }
+
+/* 禁用 */
+.topside-button.disabled { ... }
+
+/* theme 属性传入的自定义主题名 */
+.topside-button.my-theme { ... }
+```
+
+## 通过 CSS 变量做主题化
+
+所有颜色都由 CSS 变量驱动，可以全局或局部覆盖：
+
+```css
+:root {
+  /* Plain（默认） */
+  --topside-button-plain-color: #374151;
+  --topside-button-plain-color-surface: #ffffff;
+  --topside-button-plain-color-surface-hover: #f3f4f6;
+  --topside-button-plain-color-surface-active: #e5e7eb;
+  --topside-button-plain-border-color: #d1d5db;
+
+  /* Primary */
+  --topside-button-primary-color: #ffffff;
+  --topside-button-primary-color-surface: #2563eb;
+  --topside-button-primary-color-surface-hover: #1d4ed8;
+  --topside-button-primary-color-surface-active: #1e40af;
+  --topside-button-primary-border-color: #2563eb;
+
+  /* Secondary / Third / Forth —— 同样的 surface/hover/active/border 套路 */
+  --topside-button-secondary-color: ...;
+  --topside-button-third-color: ...;
+  --topside-button-forth-color: ...;
+
+  /* 禁用 */
+  --topside-button-disabled-color: #9ca3af;
+  --topside-button-disabled-color-surface: #f3f4f6;
+  --topside-button-disabled-border-color: #e5e7eb;
+
+  /* 几何参数 */
+  --topside-button-height: 32px;
+  --topside-button-height-big: 40px;
+  --topside-button-height-small: 26px;
+  --topside-button-minimal-size: 64px;
+  --topside-button-margin: 12px;
+  --topside-button-spacing: 6px;
+  --topside-button-radius-round: 999px;
+  --topside-button-color-gap: #ffffff; /* 焦点环内层留白 */
+}
+```
+
+用 `theme` 属性 + 对应选择器做局部主题：
+
+```svelte
+<Button theme="danger" label="删除" type="primary" />
+```
+
+```css
+.topside-button.danger.primary {
+  --topside-button-primary-color-surface: #dc2626;
+  --topside-button-primary-color-surface-hover: #b91c1c;
+  --topside-button-primary-color-surface-active: #991b1b;
+}
+```
+
+## 无障碍访问
+
+Button 组件遵循无障碍访问最佳实践：
+- 使用语义化 `<button>` 元素
+- 支持键盘导航（Tab、Enter、Space）
+- `:focus-visible` 通过 box-shadow 显示可见焦点环
+- 正确处理禁用状态（`disabled` 属性 + `tabindex="-1"` + 视觉样式）
+- 通过 `data-tip` 属性支持提示框（由应用层 tooltip overlay 消费）
+- `autofocus` 支持程序化焦点管理
+
+## 相关组件
+
+- [IconButton](./IconButton_README_CN.md) —— 圆形纯图标按钮
+- [TextButton](./TextButton_README_CN.md) —— 无边框纯文字按钮