@ticatec/uniface-element 0.3.22 → 5.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/uniface-element
+```
+
+## Import
+
+```typescript
+import Icon from '@ticatec/uniface-element/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/uniface-element/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="uniface-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
+.uniface-icon {
+  display: block;
+  cursor: default;
+  box-sizing: border-box;
+  text-align: center;
+}
+.uniface-icon.clickable { cursor: pointer; }
+.uniface-icon.clickable:active { position: relative; top: 1px; }  /* press feedback */
+.uniface-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> */
+.uniface-icon { font-size: 20px; color: #6b7280; }
+
+/* hover color when clickable */
+.uniface-icon.clickable:hover { color: #2563eb; }
+
+/* theme-scoped overrides */
+.uniface-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/uniface-element
+```
+
+## 导入
+
+```typescript
+import Icon from '@ticatec/uniface-element/Icon';
+```
+
+> **前置依赖**：你需要自行加载图标字体 CSS（例如 `@ticatec/uniface-google-material-icons`）。组件只输出 `<i class={name}>`，不带字体。
+
+## 基本用法
+
+```svelte
+<script>
+  import Icon from '@ticatec/uniface-element/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="uniface-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
+.uniface-icon {
+  display: block;
+  cursor: default;
+  box-sizing: border-box;
+  text-align: center;
+}
+.uniface-icon.clickable { cursor: pointer; }
+.uniface-icon.clickable:active { position: relative; top: 1px; }  /* 按下反馈 */
+.uniface-icon.disabled { cursor: not-allowed; filter: grayscale(1); }
+```
+
+通过外壳或内部 `<i>` 选择器做覆盖：
+
+```css
+/* 通过外壳定尺寸 —— 继承到 <i> */
+.uniface-icon { font-size: 20px; color: #6b7280; }
+
+/* 可点击时 hover 配色 */
+.uniface-icon.clickable:hover { color: #2563eb; }
+
+/* 主题隔离 */
+.uniface-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/separator/README.md

@@ -0,0 +1,203 @@
+# Separator Component
+
+A **vertical** divider — a 1px-wide line whose height you control. Designed to sit between items in a flex row to visually separate them.
+
+> **Not for horizontal rules.** This component renders a 1px-wide, N-pixel-tall vertical bar. If you need a horizontal divider between stacked sections, use a plain `<div style="height: 1px; background: ..."></div>` or a `<hr>` instead.
+
+## Features
+
+- **Vertical divider**: fixed 1px width, configurable height
+- **Theme token**: color driven by the `--uniface-separator-color` CSS variable
+- **Override-friendly**: `style` prop is appended after `height`, so any inline CSS wins
+- **Zero layout noise**: `position: relative` plays nicely inside flex/grid parents
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Separator from '@ticatec/uniface-element/Separator';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Separator from '@ticatec/uniface-element/Separator';
+</script>
+
+<div style="display: flex; align-items: center; gap: 16px;">
+  <span>Left</span>
+  <Separator />
+  <span>Right</span>
+</div>
+```
+
+The default height is `24px`, so the divider is 24px tall and 1px wide.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `height` | `string` | `'24px'` | CSS height value of the divider (e.g. `'24px'`, `'60px'`, `'100%'`) |
+| `style` | `string` | `undefined` | Extra inline CSS. Appended after `height`, so it can override height, color, etc. |
+
+## Events
+
+None.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="uniface-separator" style="height: 24px; {your-style}"></div>
+```
+
+Built-in styles:
+
+```css
+.uniface-separator {
+  position: relative;
+  width: 1px;
+  background-color: var(--uniface-separator-color, #E2E8F0);
+}
+```
+
+### CSS Custom Properties
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--uniface-separator-color` | `#E2E8F0` | Background color of the divider |
+
+Set it globally to theme every Separator, or scope it:
+
+```css
+:root {
+  --uniface-separator-color: #d1d5db;
+}
+
+/* only inside dark toolbars */
+.dark-toolbar {
+  --uniface-separator-color: #475569;
+}
+```
+
+## Basic Examples
+
+### Default Height (24px)
+
+```svelte
+<div style="display: flex; align-items: center; gap: 16px;">
+  <span>A</span>
+  <Separator />
+  <span>B</span>
+</div>
+```
+
+### Custom Height
+
+```svelte
+<div style="display: flex; align-items: center; gap: 16px; height: 80px;">
+  <span>Item</span>
+  <Separator height="60px" />   <!-- shorter than the row -->
+  <span>Item</span>
+  <Separator height="100%" />   <!-- full row height -->
+  <span>Item</span>
+</div>
+```
+
+### Custom Color
+
+```svelte
+<Separator style="background-color: #e53e3e;" />
+```
+
+Or via the theme token:
+
+```svelte
+<div style="--uniface-separator-color: #e53e3e;">
+  <Separator />
+</div>
+```
+
+## Detailed Examples
+
+### Toolbar Dividers
+
+A common pattern: separate groups of action buttons in a toolbar.
+
+```svelte
+<script>
+  import Separator from '@ticatec/uniface-element/Separator';
+  import IconButton from '@ticatec/uniface-element/IconButton';
+</script>
+
+<div style="display: flex; align-items: center; gap: 8px; padding: 8px;">
+  <!-- File group -->
+  <IconButton icon="icon_google_create_new_folder" />
+  <IconButton icon="icon_google_save" />
+  <IconButton icon="icon_google_open_in_new" />
+
+  <Separator />
+
+  <!-- Edit group -->
+  <IconButton icon="icon_google_content_copy" />
+  <IconButton icon="icon_google_content_paste" />
+  <IconButton icon="icon_google_content_cut" />
+
+  <Separator />
+
+  <!-- Danger group -->
+  <IconButton icon="icon_google_delete" />
+</div>
+```
+
+### Header Layout
+
+Split a page header into left/right zones:
+
+```svelte
+<header style="display: flex; align-items: center; gap: 24px; height: 56px;">
+  <div class="brand">MyApp</div>
+  <Separator height="32px" />
+  <nav class="menu">...</nav>
+  <div style="flex: 1 1 auto;"></div>   <!-- spacer -->
+  <Separator height="32px" />
+  <div class="user">Hi, Henry</div>
+</header>
+```
+
+### Style Override via `style` Prop
+
+Because `style` is appended after `height`, later declarations win — you can override height, color, or even width:
+
+```svelte
+<!-- Taller, red -->
+<Separator style="height: 48px; background-color: #ef4444;" />
+
+<!-- Dashed vertical line -->
+<Separator style="height: 100%; width: 0; border-left: 1px dashed #94a3b8; background: transparent;" />
+```
+
+## Best Practices
+
+1. **Use between horizontal items** — that's what the 1px width is for.
+2. **For horizontal rules between stacked content**, don't use this component — use a `<hr>` or a 1px-tall `<div>`.
+3. **Keep height consistent** within a single toolbar/header (e.g. always `24px` or always `60%`).
+4. **Theme via the CSS variable** rather than per-instance `style`, so you can re-skin the whole app in one place.
+
+## Accessibility
+
+- Pure decoration; no interactive semantics.
+- The wrapper renders as a `<div>` with no ARIA attributes — screen readers ignore it.
+- Don't rely on a Separator alone to convey section boundaries; pair it with semantic headings or `<section>` elements.
+
+## Related Components
+
+- [Button](../button/README.md) — standard button (often used between Separators in toolbars)
+- [IconButton](../button/IconButton_README.md) — round icon button, common in toolbars next to Separators