@ticatec/topside-elements 1.0.0

package/dist/general/icon/README.md

@@ -0,0 +1,255 @@
+# Icon Component
+
+A wrapper around icon-font glyphs (e.g. Google Material Icons) with optional click handling, debouncing, theming, disabled state, and tooltip support.
+
+## Features
+
+- **Icon-font friendly**: Renders `<i class={name}>` so any icon-font CSS (Material Icons, Font Awesome, etc.) works
+- **Optional click handler**: Pass `onclick` to make the icon interactive; the wrapper auto-adds a `clickable` class
+- **Async-aware debounce**: Awaits the handler, then enforces an extra 200ms cooldown before the next click
+- **Disabled state**: Filters the icon to grayscale, blocks clicks, hides the tooltip
+- **Tooltip**: Built-in via the `data-tip` attribute (consumed by the app-level tooltip overlay)
+- **Theming**: `theme` prop adds an extra CSS class for scoped overrides
+- **No text selection**: `onmousedown` calls `preventDefault()` so dragging doesn't select adjacent text
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Icon from '@ticatec/topside-elements/Icon';
+```
+
+> **Prerequisite**: You must load an icon-font CSS yourself (e.g. `@ticatec/uniface-google-material-icons`). The component only emits `<i class={name}>` — it does not bundle the font.
+
+## Basic Usage
+
+```svelte
+<script>
+  import Icon from '@ticatec/topside-elements/Icon';
+
+  function handleDelete() {
+    console.log('Delete clicked');
+  }
+</script>
+
+<!-- Decorative -->
+<Icon name="icon_google_edit" />
+
+<!-- Clickable -->
+<Icon name="icon_google_delete" onclick={handleDelete} tooltip="Delete" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | **required** | CSS class name of the glyph (e.g. `"icon_google_edit"`) |
+| `onclick` | `MouseClickHandler \| null` | `null` | Click handler. May be `async`; the icon waits for it to resolve before re-enabling. |
+| `style` | `string` | `''` | Inline CSS on the wrapper `<div>`. Use for `color`, `font-size`, layout — these inherit into the `<i>`. |
+| `theme` | `string` | `''` | Extra CSS class appended to the wrapper for scoped overrides |
+| `class` | `string` | `''` | Extra CSS class appended to the wrapper (same slot as `theme`) |
+| `tooltip` | `string \| undefined` | - | Tooltip text shown on hover. Suppressed when `disabled={true}`. |
+| `disabled` | `boolean` | `false` | Blocks clicks, applies grayscale filter, sets `cursor: not-allowed`, hides tooltip |
+
+## Events
+
+| Event | Parameters | Description |
+|-------|------------|-------------|
+| `onclick` | `event: MouseEvent` | Fired on click. Blocked when `disabled={true}`. The handler may be async — see debounce notes below. |
+
+## Click Debouncing
+
+The wrapper guards against rapid clicks:
+
+```ts
+async function handleClickEvent(e: MouseEvent) {
+  if (disabled) return;
+  if (onclick != null && respClick) {
+    respClick = false;
+    await onclick?.(e);               // 1. await your handler
+    await new Promise(r => setTimeout(r, 200));  // 2. + 200ms cooldown
+    respClick = true;                  // 3. re-enable
+  }
+}
+```
+
+Total lockout window = **handler duration + 200ms**. For a synchronous handler this is ~200ms; for an async fetch it's however long the fetch takes plus 200ms.
+
+When `onclick` is `null`, the icon is non-interactive (no `clickable` class, default cursor, no debounce guard).
+
+## Disabled State
+
+When `disabled={true}`:
+
+- Click handler returns immediately (no `onclick` call, no debounce lockout)
+- The wrapper gets `class:disabled` → `cursor: not-allowed` and `filter: grayscale(1)`
+- `data-tip` is set to `null`, so the tooltip overlay will not show
+
+```svelte
+<Icon name="icon_google_settings" disabled tooltip="Not available" />
+```
+
+## DOM Structure & CSS Classes
+
+Rendered output:
+
+```html
+<div
+  class="topside-icon {theme} {className}"
+  class:clickable     <!-- when onclick != null && !disabled -->
+  class:disabled      <!-- when disabled -->
+  onmousedown="event.preventDefault()"
+  aria-hidden="true"
+  data-tip="..."      <!-- null when disabled or no tooltip -->
+>
+  <i class="{name}"></i>
+</div>
+```
+
+Built-in styles:
+
+```css
+.topside-icon {
+  display: block;
+  cursor: default;
+  box-sizing: border-box;
+  text-align: center;
+}
+.topside-icon.clickable { cursor: pointer; }
+.topside-icon.clickable:active { position: relative; top: 1px; }  /* press feedback */
+.topside-icon.disabled { cursor: not-allowed; filter: grayscale(1); }
+```
+
+Override styles by targeting the wrapper or the inner `<i>`:
+
+```css
+/* sizing via wrapper — inherits into <i> */
+.topside-icon { font-size: 20px; color: #6b7280; }
+
+/* hover color when clickable */
+.topside-icon.clickable:hover { color: #2563eb; }
+
+/* theme-scoped overrides */
+.topside-icon.danger { color: #dc2626; }
+```
+
+## Basic Examples
+
+### A Row of Decorative Icons
+
+```svelte
+<div style="display: flex; gap: 16px;">
+  <Icon name="icon_google_edit" />
+  <Icon name="icon_google_delete" />
+  <Icon name="icon_google_save" />
+  <Icon name="icon_google_download" />
+</div>
+```
+
+### Clickable Icons with Tooltips
+
+```svelte
+<script>
+  function handleEdit() { console.log('Edit'); }
+  function handleDelete() { console.log('Delete'); }
+</script>
+
+<div style="display: flex; gap: 16px;">
+  <Icon name="icon_google_edit"   onclick={handleEdit}   tooltip="Edit" />
+  <Icon name="icon_google_delete" onclick={handleDelete} tooltip="Delete" />
+</div>
+```
+
+### Async Click Handler
+
+Because the wrapper awaits your handler, you can fetch data without worrying about double-fire:
+
+```svelte
+<script>
+  let saving = $state(false);
+  async function save() {
+    saving = true;
+    try {
+      await api.save();
+    } finally {
+      saving = false;            // icon is still in cooldown for 200ms after this
+    }
+  }
+</script>
+
+<Icon name="icon_google_save" onclick={save} disabled={saving} tooltip="Save" />
+```
+
+## Detailed Examples
+
+### Toolbar
+
+```svelte
+<script>
+  function handleCopy()  { console.log('Copy'); }
+  function handlePaste() { console.log('Paste'); }
+  function handleCut()   { console.log('Cut'); }
+</script>
+
+<div class="toolbar" style="display: flex; gap: 8px; padding: 8px;">
+  <Icon name="icon_google_content_copy"  onclick={handleCopy}  tooltip="Copy" />
+  <Icon name="icon_google_content_paste" onclick={handlePaste} tooltip="Paste" />
+  <Icon name="icon_google_content_cut"   onclick={handleCut}   tooltip="Cut" />
+</div>
+```
+
+### Theming & Custom Style
+
+```svelte
+<!-- Theme name passed through as a CSS class -->
+<Icon name="icon_google_settings" theme="theme-dark" />
+
+<!-- Custom color/size via inline style (inherits into <i>) -->
+<Icon name="icon_google_favorite" style="color: #FF685B; font-size: 32px;" tooltip="Favorite" />
+
+<!-- Custom CSS class -->
+<Icon name="icon_google_share" class="my-custom-icon" tooltip="Share" />
+```
+
+```css
+.my-custom-icon {
+  transition: transform 0.15s ease;
+}
+.my-custom-icon.clickable:hover {
+  transform: scale(1.15);
+}
+```
+
+## Common Icon Names
+
+The component itself is font-agnostic. The standard library ships Google Material Icons (`icon_google_*`):
+
+| Icon | Class |
+|------|-------|
+| Edit | `icon_google_edit` |
+| Delete | `icon_google_delete` |
+| Save | `icon_google_save` |
+| Add | `icon_google_add` |
+| Close | `icon_google_close` |
+| Check | `icon_google_check` |
+| Clear | `icon_google_clear` |
+| Search | `icon_google_search` |
+| Settings | `icon_google_settings` |
+| Download | `icon_google_download` |
+
+## Accessibility
+
+- The wrapper is `aria-hidden="true"` because the icon is decorative by default.
+- If the icon conveys meaning as the sole element of an action, supply a `tooltip` and ensure the surrounding UI gives context (or pair with a visually-hidden label).
+- Press feedback (`top: 1px` on `:active`) gives a tactile click cue.
+- Disabled state is communicated both visually (grayscale) and behaviorally (no click, no tooltip).
+
+## Related Components
+
+- [Button](../button/README.md) — standard label button with optional icon
+- [IconButton](../button/IconButton_README.md) — round, icon-only button variant

package/dist/general/icon/README_CN.md

@@ -0,0 +1,255 @@
+# Icon 图标组件
+
+图标字体的薄封装（如 Google Material Icons），支持可选的点击处理、防抖、主题切换、禁用状态与 tooltip。
+
+## 功能特性
+
+- **图标字体友好**：渲染 `<i class={name}>`，任意图标字体 CSS（Material Icons、Font Awesome 等）都能用
+- **可选点击处理**：传 `onclick` 让图标可交互，外壳自动加 `clickable` 类
+- **异步感知防抖**：先 await 你的 handler，再额外加 200ms 冷却
+- **禁用状态**：图标灰度化、拦截点击、隐藏 tooltip
+- **提示框**：通过 `data-tip` 属性（由应用层 tooltip overlay 消费）
+- **主题化**：`theme` 属性追加 CSS 类，便于局部样式覆盖
+- **不选中文本**：`onmousedown` 调用 `preventDefault()`，拖拽时不会选中旁边文字
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Icon from '@ticatec/topside-elements/Icon';
+```
+
+> **前置依赖**：你需要自行加载图标字体 CSS（例如 `@ticatec/uniface-google-material-icons`）。组件只输出 `<i class={name}>`，不带字体。
+
+## 基本用法
+
+```svelte
+<script>
+  import Icon from '@ticatec/topside-elements/Icon';
+
+  function handleDelete() {
+    console.log('删除点击');
+  }
+</script>
+
+<!-- 装饰性 -->
+<Icon name="icon_google_edit" />
+
+<!-- 可点击 -->
+<Icon name="icon_google_delete" onclick={handleDelete} tooltip="删除" />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `name` | `string` | **必填** | 图标的 CSS 类名（如 `"icon_google_edit"`） |
+| `onclick` | `MouseClickHandler \| null` | `null` | 点击处理函数；可为 `async`，组件会 await 完才放行下一次点击 |
+| `style` | `string` | `''` | 外层 `<div>` 的内联 CSS。`color`、`font-size` 等会继承到内部 `<i>` |
+| `theme` | `string` | `''` | 追加到外壳的额外 CSS 类，便于局部样式隔离 |
+| `class` | `string` | `''` | 追加到外壳的额外 CSS 类（与 `theme` 同槽位） |
+| `tooltip` | `string \| undefined` | - | 悬停 tooltip 文本。`disabled={true}` 时自动隐藏 |
+| `disabled` | `boolean` | `false` | 拦截点击、加灰度滤镜、`cursor: not-allowed`、隐藏 tooltip |
+
+## 事件
+
+| 事件 | 参数 | 描述 |
+|------|------|-------------|
+| `onclick` | `event: MouseEvent` | 点击时触发。`disabled={true}` 时不触发。handler 可为 async，详见防抖说明 |
+
+## 点击防抖
+
+外壳对快速点击做了保护：
+
+```ts
+async function handleClickEvent(e: MouseEvent) {
+  if (disabled) return;
+  if (onclick != null && respClick) {
+    respClick = false;
+    await onclick?.(e);               // 1. 等你的 handler 跑完
+    await new Promise(r => setTimeout(r, 200));  // 2. 再加 200ms 冷却
+    respClick = true;                  // 3. 重新放行
+  }
+}
+```
+
+总锁定时间 = **handler 耗时 + 200ms**。同步 handler 约 200ms；async fetch 则是 fetch 时间 + 200ms。
+
+`onclick` 为 `null` 时图标不可交互（无 `clickable` 类、默认光标、不进入防抖逻辑）。
+
+## 禁用状态
+
+`disabled={true}` 时：
+
+- 点击 handler 直接 return（不调 `onclick`、不占用防抖窗口）
+- 外壳加 `class:disabled` → `cursor: not-allowed` + `filter: grayscale(1)`
+- `data-tip` 被置为 `null`，tooltip overlay 不会显示
+
+```svelte
+<Icon name="icon_google_settings" disabled tooltip="不可用" />
+```
+
+## DOM 结构与 CSS 类
+
+实际渲染：
+
+```html
+<div
+  class="topside-icon {theme} {className}"
+  class:clickable     <!-- onclick != null && !disabled 时 -->
+  class:disabled      <!-- disabled 时 -->
+  onmousedown="event.preventDefault()"
+  aria-hidden="true"
+  data-tip="..."      <!-- disabled 或无 tooltip 时为 null -->
+>
+  <i class="{name}"></i>
+</div>
+```
+
+内置样式：
+
+```css
+.topside-icon {
+  display: block;
+  cursor: default;
+  box-sizing: border-box;
+  text-align: center;
+}
+.topside-icon.clickable { cursor: pointer; }
+.topside-icon.clickable:active { position: relative; top: 1px; }  /* 按下反馈 */
+.topside-icon.disabled { cursor: not-allowed; filter: grayscale(1); }
+```
+
+通过外壳或内部 `<i>` 选择器做覆盖：
+
+```css
+/* 通过外壳定尺寸 —— 继承到 <i> */
+.topside-icon { font-size: 20px; color: #6b7280; }
+
+/* 可点击时 hover 配色 */
+.topside-icon.clickable:hover { color: #2563eb; }
+
+/* 主题隔离 */
+.topside-icon.danger { color: #dc2626; }
+```
+
+## 基本示例
+
+### 一排装饰性图标
+
+```svelte
+<div style="display: flex; gap: 16px;">
+  <Icon name="icon_google_edit" />
+  <Icon name="icon_google_delete" />
+  <Icon name="icon_google_save" />
+  <Icon name="icon_google_download" />
+</div>
+```
+
+### 带 tooltip 的可点击图标
+
+```svelte
+<script>
+  function handleEdit() { console.log('编辑'); }
+  function handleDelete() { console.log('删除'); }
+</script>
+
+<div style="display: flex; gap: 16px;">
+  <Icon name="icon_google_edit"   onclick={handleEdit}   tooltip="编辑" />
+  <Icon name="icon_google_delete" onclick={handleDelete} tooltip="删除" />
+</div>
+```
+
+### 异步点击 handler
+
+外壳会 await 你的 handler，所以 fetch 期间不会被双击触发：
+
+```svelte
+<script>
+  let saving = $state(false);
+  async function save() {
+    saving = true;
+    try {
+      await api.save();
+    } finally {
+      saving = false;            // 此后还有 200ms 冷却
+    }
+  }
+</script>
+
+<Icon name="icon_google_save" onclick={save} disabled={saving} tooltip="保存" />
+```
+
+## 详细示例
+
+### 工具栏
+
+```svelte
+<script>
+  function handleCopy()  { console.log('复制'); }
+  function handlePaste() { console.log('粘贴'); }
+  function handleCut()   { console.log('剪切'); }
+</script>
+
+<div class="toolbar" style="display: flex; gap: 8px; padding: 8px;">
+  <Icon name="icon_google_content_copy"  onclick={handleCopy}  tooltip="复制" />
+  <Icon name="icon_google_content_paste" onclick={handlePaste} tooltip="粘贴" />
+  <Icon name="icon_google_content_cut"   onclick={handleCut}   tooltip="剪切" />
+</div>
+```
+
+### 主题与自定义样式
+
+```svelte
+<!-- theme 作为 CSS 类追加 -->
+<Icon name="icon_google_settings" theme="theme-dark" />
+
+<!-- 内联自定义颜色/尺寸（继承到 <i>） -->
+<Icon name="icon_google_favorite" style="color: #FF685B; font-size: 32px;" tooltip="收藏" />
+
+<!-- 自定义 CSS 类 -->
+<Icon name="icon_google_share" class="my-custom-icon" tooltip="分享" />
+```
+
+```css
+.my-custom-icon {
+  transition: transform 0.15s ease;
+}
+.my-custom-icon.clickable:hover {
+  transform: scale(1.15);
+}
+```
+
+## 常用图标名
+
+组件本身与字体解耦。标准库内置 Google Material Icons（`icon_google_*`）：
+
+| 图标 | 类名 |
+|------|------|
+| 编辑 | `icon_google_edit` |
+| 删除 | `icon_google_delete` |
+| 保存 | `icon_google_save` |
+| 添加 | `icon_google_add` |
+| 关闭 | `icon_google_close` |
+| 确认 | `icon_google_check` |
+| 清除 | `icon_google_clear` |
+| 搜索 | `icon_google_search` |
+| 设置 | `icon_google_settings` |
+| 下载 | `icon_google_download` |
+
+## 无障碍访问
+
+- 外壳默认 `aria-hidden="true"`，因为图标本身是装饰性的
+- 若图标是某个操作的唯一视觉表达，建议加 `tooltip` 并保证周围 UI 有上下文（或搭配 visually-hidden label）
+- `:active` 时的 `top: 1px` 提供按下触感反馈
+- 禁用状态通过视觉（灰度）和行为（不响应、无 tooltip）双重传达
+
+## 相关组件
+
+- [Button](../button/README_CN.md) —— 标准带文字按钮，可选图标
+- [IconButton](../button/IconButton_README_CN.md) —— 圆形纯图标按钮变体

package/dist/general/icon/index.d.ts

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

package/dist/general/icon/index.js

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