@ticatec/topside-elements 1.0.0

package/dist/overlay/tooltip/README.md

@@ -0,0 +1,334 @@
+# Tooltip
+
+A global tooltip system that automatically detects and shows contextual hints when users hover over elements with the `data-tip` attribute.
+
+## Features
+
+- **Automatic Detection**: Uses event delegation to automatically detect elements with `data-tip` attribute.
+- **Smart Positioning**: Automatically chooses top/bottom position based on available space.
+- **Edge-Aware Alignment**: Adjusts horizontal alignment (left/center/right) to prevent screen overflow.
+- **Markdown Support**: Renders rich text with bold, italic, code, lists, and more via snarkdown.
+- **Delayed Display**: Configurable delay (default 200ms) to prevent flickering.
+- **Auto Hide**: Hides when the mouse leaves the element — and also when the element itself goes away (removed from the DOM, hidden by `display:none` / `visibility:hidden`, or its `data-tip` cleared), on scroll, and when the window loses focus.
+- **Zero Boilerplate**: Just add `data-tip` attribute, no JavaScript needed.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Tooltip from "@ticatec/topside-elements/Tooltip";
+```
+
+## Basic Usage
+
+Add the `data-tip` attribute to any element:
+
+```svelte
+<button data-tip="Save your current work">Save</button>
+<button data-tip="Cancel all changes">Cancel</button>
+
+<!-- With markdown formatting -->
+<button data-tip="**Bold** and *italic* text">Click me</button>
+
+<!-- Multi-line with \n -->
+<button data-tip="Save changes\nShortcut: `Ctrl+S`">Save</button>
+
+<!-- Dynamic content -->
+<div data-tip={errorMessage || null}>
+  {errorMessage ? 'Error occurred' : 'Success'}
+</div>
+```
+
+## Component Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `delay` | `number` | `200` | Delay in milliseconds before showing tooltip. |
+| `offset` | `number` | `6` | Distance in pixels from target element. |
+
+## data-tip Attribute
+
+### Basic Usage
+
+```html
+<div data-tip="Your tooltip text">Content</div>
+```
+
+### Line Breaks
+
+Use `\n` for line breaks:
+
+```svelte
+<button data-tip="Line 1\nLine 2\nLine 3">Multi-line</button>
+```
+
+### Dynamic/Conditional Tooltips
+
+```svelte
+<!-- Shows tooltip only when condition is true -->
+<div data-tip={condition ? 'Show when true' : null}>
+  Conditional tooltip
+</div>
+
+<!-- Error-based tooltip -->
+<input
+  data-tip={error || 'Enter a valid value'}
+  class:error={error}
+/>
+
+<!-- Disabled state handling -->
+<button
+  data-tip={disabled ? null : 'Click to submit'}
+  {disabled}
+>
+  Submit
+</button>
+```
+
+## Markdown Support
+
+Tooltips support markdown for rich text formatting (rendered via [snarkdown](https://github.com/AlexanderMMiller/snarkdown)):
+
+### Supported Syntax
+
+| Markdown | Output |
+|----------|--------|
+| `**bold**` | **bold** |
+| `*italic*` or `_italic_` | *italic* |
+| `` `code` `` | `inline code` |
+| `---` | Horizontal rule |
+| `- item` | Bullet list |
+| `1. item` | Numbered list |
+| `[link](url)` | Clickable link |
+| `> quote` | Blockquote |
+
+### Markdown Examples
+
+**Bold and emphasis:**
+```svelte
+<button data-tip="**Important**: Click *carefully*">
+  Action
+</button>
+```
+
+**Code and shortcuts:**
+```svelte
+<button data-tip="Save document\n\nShortcut: `Ctrl+S`">
+  Save
+</button>
+```
+
+**Lists:**
+```svelte
+<button data-tip="**Export options**\n\n- PDF format\n- Include images\n- High quality">
+  Export
+</button>
+```
+
+## Positioning Behavior
+
+The tooltip automatically adjusts its position to stay within the viewport:
+
+1. **Vertical Position**: Chooses top or bottom based on available space.
+2. **Horizontal Alignment**:
+   - **Center** (default) - When there's enough horizontal space.
+   - **Left-aligned** - When near the left edge of screen.
+   - **Right-aligned** - When near the right edge of screen.
+
+```svelte
+<!-- These will automatically adjust position -->
+<button data-tip="Centered tooltip">Middle</button>
+<button data-tip="Left-aligned tooltip" style="margin-left: 0;">Left edge</button>
+<button data-tip="Right-aligned tooltip" style="margin-right: 0;">Right edge</button>
+```
+
+## Dismissal Behavior
+
+A tooltip is dismissed when any of the following happens:
+
+| Trigger | Why it matters |
+| --- | --- |
+| The pointer leaves the element (`mouseleave`) | The normal case. |
+| The element is removed from the DOM | A destroyed component, a closed dialog, a re-rendered row: the browser does **not** reliably fire `mouseleave` for a node that disappears under the cursor, so the tooltip watches the element and hides itself. |
+| The element (or an ancestor) becomes hidden | `display:none`, `visibility:hidden`, a collapsed panel, a switched tab. |
+| `data-tip` / `data-tooltip` is cleared | E.g. a validation error tooltip whose error has just been fixed. Changing the text instead updates the tooltip in place. |
+| The page or any scroll container scrolls | The tooltip is `position: fixed`; without this it would drift away from its target. |
+| The window loses focus | Alt-tabbing away while hovering. |
+
+This is handled internally (a `MutationObserver` is attached only while a tooltip is pending or visible, so there is no cost when idle) — nothing is required from the calling code.
+
+## Styling & Theming
+
+### CSS Variables
+
+Configure these in your global CSS:
+
+```css
+:root {
+  --topside-tooltip-margin: 8px 16px;
+  --topside-tooltip-color-surface: #FFFFE1;
+  --topside-tooltip-color: #374151;
+  --topside-tooltip-radius: 8px;
+  --topside-tooltip-box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+}
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--topside-tooltip-margin` | `8px 16px` | Padding around tooltip content. |
+| `--topside-tooltip-color-surface` | `#FFFFE1` | Background color. |
+| `--topside-tooltip-color` | `#374151` | Text color. |
+| `--topside-tooltip-radius` | `8px` | Corner radius. |
+| `--topside-tooltip-box-shadow` | `0 2px 8px rgba(0,0,0,0.15)` | Drop shadow. |
+
+### Theme Examples
+
+**Light Theme (Default):**
+```css
+:root {
+  --topside-tooltip-color-surface: #FFFFE1;
+  --topside-tooltip-color: #374151;
+}
+```
+
+**Dark Theme:**
+```css
+[data-theme="dark"] {
+  --topside-tooltip-color-surface: #374151;
+  --topside-tooltip-color: #F1F5F9;
+  --topside-tooltip-box-shadow: 0 2px 8px rgba(255, 255, 255, 0.1);
+}
+```
+
+**Blue Theme:**
+```css
+:root {
+  --topside-tooltip-color-surface: #298DFF;
+  --topside-tooltip-color: #FFFFFF;
+}
+```
+
+### Custom Styling
+
+Target the `.topside-tooltip` class in your global CSS:
+
+```css
+.topside-tooltip {
+  font-size: 14px;
+  font-weight: 500;
+  max-width: 300px;
+}
+```
+
+## Best Practices
+
+1. **Keep it brief**: Tooltips should be short and to the point.
+2. **Meaningful content**: Provide genuinely helpful information.
+3. **Use markdown**: Leverage formatting for clarity (bold for emphasis, code for shortcuts).
+4. **Don't hide critical info**: Tooltips are supplementary, not primary content.
+5. **Consider accessibility**: Hover-only tooltips may not work on touch devices.
+
+## Examples
+
+### Form Field Tooltips
+
+```svelte
+<script>
+  let username = '';
+  let email = '';
+</script>
+
+<input
+  type="text"
+  bind:value={username}
+  placeholder="Enter username"
+  data-tip="**Username requirements**:\n\n- 3-20 characters\n- Letters and numbers only"
+/>
+
+<input
+  type="email"
+  bind:value={email}
+  placeholder="Enter email"
+  data-tip="We'll use this for account recovery and notifications"
+/>
+```
+
+### Icon Toolbar
+
+```svelte
+<script>
+  import IconButton from '@ticatec/topside-elements/IconButton';
+</script>
+
+<div class="toolbar">
+  <IconButton icon="icon_google_edit" data-tip="Edit this item" />
+  <IconButton icon="icon_google_delete" data-tip="**Delete**\n\n- Cannot be undone\n- Requires confirmation" />
+  <IconButton icon="icon_google_share" data-tip="Share with others" />
+  <IconButton icon="icon_google_download" data-tip="Download file\nShortcut: `Ctrl+D`" />
+</div>
+```
+
+### Dynamic Status Tooltips
+
+```svelte
+<script>
+  let status = 'active';
+  let lastActive = '2 hours ago';
+
+  $: statusTooltip = status === 'active'
+    ? `**User is active**\n\nLast seen: ${lastActive}`
+    : '**User is inactive**\n\nAccount has been deactivated';
+</script>
+
+<div class="status-badge" data-tip={statusTooltip}>
+  {status}
+</div>
+```
+
+### Data Table with Contextual Tooltips
+
+```svelte
+<script>
+  let users = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User' }
+  ];
+</script>
+
+<table>
+  {#each users as user}
+    <tr>
+      <td data-tip="{user.name}\n{user.email}">{user.name}</td>
+      <td data-tip="**Role:** {user.role}">{user.role}</td>
+    </tr>
+  {/each}
+</table>
+```
+
+## Accessibility Notes
+
+- Tooltips are mouse-hover dependent and may not work on touch devices.
+- For critical information, consider using inline text or other accessible alternatives.
+- Screen readers may not announce `data-tip` content.
+- Consider adding `aria-label` as a fallback.
+
+## Performance
+
+- Event delegation ensures minimal overhead.
+- Single global instance handles all tooltips.
+- Automatic cleanup prevents memory leaks.
+- No manual event listener management needed.
+
+## Related Components
+
+- [MessageBox](../message-box/README.md) — For modal information dialogs.
+- [Toast](../toast/README.md) — For notification messages.
+- [Dialog](../dialog/README.md) — For complex interactive content.
+- [Drawer](../drawer/README.md) — Slide-out side panel.
+- [ContextMenu](../context-menu/README.md) — Right-click context menu.
+- [Indicator](../indicator/README.md) — Full-screen loading spinner.

package/dist/overlay/tooltip/README_CN.md

@@ -0,0 +1,334 @@
+# Tooltip 工具提示
+
+全局工具提示系统，自动检测并显示带有 `data-tip` 属性的元素的工具提示。
+
+## 功能特性
+
+- **自动检测**：使用事件委托自动检测带有 `data-tip` 属性的元素
+- **智能定位**：根据可用空间自动选择上方/下方位置
+- **边缘对齐**：自动调整水平对齐（左/中/右）防止溢出屏幕
+- **Markdown 支持**：支持富文本格式（粗体、斜体、代码、列表等），通过 snarkdown 渲染
+- **延迟显示**：可配置延迟（默认 200 毫秒）防止误触发
+- **自动隐藏**：鼠标离开元素时隐藏；元素本身消失（从 DOM 移除、被 `display:none` / `visibility:hidden` 隐藏、`data-tip` 被清空）、页面滚动、窗口失焦时同样会自动隐藏
+- **零样板代码**：只需添加 `data-tip` 属性，无需编写 JavaScript
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import Tooltip from "@ticatec/topside-elements/Tooltip";
+```
+
+## 基本用法
+
+在任何元素上添加 `data-tip` 属性：
+
+```svelte
+<button data-tip="保存当前工作">保存</button>
+<button data-tip="取消所有更改">取消</button>
+
+<!-- 带 Markdown 格式 -->
+<button data-tip="**粗体**和*斜体*文本">点击我</button>
+
+<!-- 多行文本使用 \n -->
+<button data-tip="保存更改\n快捷键：`Ctrl+S`">保存</button>
+
+<!-- 动态内容 -->
+<div data-tip={errorMessage || null}>
+  {errorMessage ? '发生错误' : '成功'}
+</div>
+```
+
+## 组件属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `delay` | `number` | `200` | 显示提示前的延迟毫秒数 |
+| `offset` | `number` | `6` | 与目标元素的距离（像素） |
+
+## data-tip 属性
+
+### 基本用法
+
+```html
+<div data-tip="你的提示文本">内容</div>
+```
+
+### 换行
+
+使用 `\n` 进行换行：
+
+```svelte
+<button data-tip="第一行\n第二行\n第三行">多行提示</button>
+```
+
+### 动态/条件提示
+
+```svelte
+<!-- 仅在条件为真时显示提示 -->
+<div data-tip={condition ? '条件为真时显示' : null}>
+  条件提示
+</div>
+
+<!-- 基于错误的提示 -->
+<input
+  data-tip={error || '输入有效值'}
+  class:error={error}
+/>
+
+<!-- 禁用状态处理 -->
+<button
+  data-tip={disabled ? null : '点击提交'}
+  {disabled}
+>
+  提交
+</button>
+```
+
+## Markdown 支持
+
+提示支持 Markdown 富文本格式化（通过 [snarkdown](https://github.com/AlexanderMMiller/snarkdown) 渲染）：
+
+### 支持的语法
+
+| Markdown | 输出 |
+|----------|------|
+| `**粗体**` | **粗体** |
+| `*斜体*` 或 `_斜体_` | *斜体* |
+| `` `代码` `` | `行内代码` |
+| `---` | 水平分隔线 |
+| `- 项目` | 无序列表 |
+| `1. 项目` | 有序列表 |
+| `[链接](url)` | 可点击链接 |
+| `> 引用` | 引用块 |
+
+### Markdown 示例
+
+**粗体和强调：**
+```svelte
+<button data-tip="**重要**：请*小心*点击">
+  操作
+</button>
+```
+
+**代码和快捷键：**
+```svelte
+<button data-tip="保存文档\n\n快捷键：`Ctrl+S`">
+  保存
+</button>
+```
+
+**列表：**
+```svelte
+<button data-tip="**导出选项**\n\n- PDF 格式\n- 包含图片\n- 高质量">
+  导出
+</button>
+```
+
+## 定位行为
+
+工具提示会自动调整位置以保持在视口内：
+
+1. **垂直位置**：根据可用空间选择上方或下方
+2. **水平对齐**：
+   - **居中**（默认）- 有足够水平空间时
+   - **左对齐** - 靠近屏幕左边缘时
+   - **右对齐** - 靠近屏幕右边缘时
+
+```svelte
+<!-- 这些会自动调整位置和对齐 -->
+<button data-tip="居中提示">中间</button>
+<button data-tip="左对齐提示" style="margin-left: 0;">左边缘</button>
+<button data-tip="右对齐提示" style="margin-right: 0;">右边缘</button>
+```
+
+## 隐藏时机
+
+出现以下任一情况时，tooltip 都会收起：
+
+| 触发条件 | 说明 |
+| --- | --- |
+| 鼠标离开元素（`mouseleave`） | 常规情况。 |
+| 元素从 DOM 中被移除 | 组件被销毁、对话框关闭、列表行重新渲染等。光标下的节点消失时浏览器**不会**可靠地派发 `mouseleave`，因此 tooltip 会自己监视目标元素并收起——否则它会一直挂在屏幕上无法消除。 |
+| 元素（或其祖先）被隐藏 | `display:none`、`visibility:hidden`、折叠面板、切换标签页等。 |
+| `data-tip` / `data-tooltip` 被清空 | 例如校验错误已修正。若只是文本变化，则原地更新 tooltip 内容。 |
+| 页面或任意滚动容器发生滚动 | tooltip 使用 `position: fixed`，不收起就会与目标元素脱节。 |
+| 窗口失去焦点 | 悬停时切换到其他窗口。 |
+
+这些都由组件内部处理（`MutationObserver` 仅在 tooltip 等待显示或已显示期间才连接，空闲时无任何开销），调用方无需做任何事情。
+
+## 样式与主题定制
+
+### CSS 变量
+
+在全局 CSS 中配置这些变量：
+
+```css
+:root {
+  --topside-tooltip-margin: 8px 16px;
+  --topside-tooltip-color-surface: #FFFFE1;
+  --topside-tooltip-color: #374151;
+  --topside-tooltip-radius: 8px;
+  --topside-tooltip-box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+}
+```
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `--topside-tooltip-margin` | `8px 16px` | 提示框内容内边距 |
+| `--topside-tooltip-color-surface` | `#FFFFE1` | 背景颜色 |
+| `--topside-tooltip-color` | `#374151` | 文字颜色 |
+| `--topside-tooltip-radius` | `8px` | 圆角 |
+| `--topside-tooltip-box-shadow` | `0 2px 8px rgba(0,0,0,0.15)` | 投影 |
+
+### 主题示例
+
+**浅色主题（默认）：**
+```css
+:root {
+  --topside-tooltip-color-surface: #FFFFE1;
+  --topside-tooltip-color: #374151;
+}
+```
+
+**深色主题：**
+```css
+[data-theme="dark"] {
+  --topside-tooltip-color-surface: #374151;
+  --topside-tooltip-color: #F1F5F9;
+  --topside-tooltip-box-shadow: 0 2px 8px rgba(255, 255, 255, 0.1);
+}
+```
+
+**蓝色主题：**
+```css
+:root {
+  --topside-tooltip-color-surface: #298DFF;
+  --topside-tooltip-color: #FFFFFF;
+}
+```
+
+### 自定义样式
+
+在全局 CSS 中定位 `.topside-tooltip` 类：
+
+```css
+.topside-tooltip {
+  font-size: 14px;
+  font-weight: 500;
+  max-width: 300px;
+}
+```
+
+## 最佳实践
+
+1. **保持简洁**：提示文本应简短扼要
+2. **有意义的内容**：提供真正有用的信息
+3. **使用 Markdown**：利用格式提高清晰度（粗体表示强调，代码表示快捷键）
+4. **不要隐藏关键信息**：提示是补充内容，不是主要内容
+5. **考虑无障碍性**：仅支持悬停的提示可能在触摸设备上无法工作
+
+## 示例
+
+### 表单字段提示
+
+```svelte
+<script>
+  let username = '';
+  let email = '';
+</script>
+
+<input
+  type="text"
+  bind:value={username}
+  placeholder="输入用户名"
+  data-tip="**用户名要求**:\n\n- 3-20 个字符\n- 仅限字母和数字"
+/>
+
+<input
+  type="email"
+  bind:value={email}
+  placeholder="输入邮箱"
+  data-tip="我们将使用此邮箱进行账户恢复和通知"
+/>
+```
+
+### 图标工具栏
+
+```svelte
+<script>
+  import IconButton from '@ticatec/topside-elements/IconButton';
+</script>
+
+<div class="toolbar">
+  <IconButton icon="icon_google_edit" data-tip="编辑此项目" />
+  <IconButton icon="icon_google_delete" data-tip="**删除**\n\n- 无法撤销\n- 需要确认" />
+  <IconButton icon="icon_google_share" data-tip="与他人分享" />
+  <IconButton icon="icon_google_download" data-tip="下载文件\n快捷键：`Ctrl+D`" />
+</div>
+```
+
+### 动态状态提示
+
+```svelte
+<script>
+  let status = 'active';
+  let lastActive = '2 小时前';
+
+  $: statusTooltip = status === 'active'
+    ? `**用户活跃**\n\n最后活跃：${lastActive}`
+    : '**用户未激活**\n\n账户已停用';
+</script>
+
+<div class="status-badge" data-tip={statusTooltip}>
+  {status}
+</div>
+```
+
+### 数据表格上下文提示
+
+```svelte
+<script>
+  let users = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User' }
+  ];
+</script>
+
+<table>
+  {#each users as user}
+    <tr>
+      <td data-tip="{user.name}\n{user.email}">{user.name}</td>
+      <td data-tip="**角色：** {user.role}">{user.role}</td>
+    </tr>
+  {/each}
+</table>
+```
+
+## 无障碍性说明
+
+- 工具提示依赖于鼠标悬停，在触摸设备上可能无法工作
+- 对于关键信息，请考虑使用内联文本或其他可访问的替代方案
+- 屏幕阅读器可能不会朗读 `data-tip` 内容
+- 考虑添加 `aria-label` 作为备选方案
+
+## 性能
+
+- 事件委托确保最小开销
+- 单个全局实例处理所有提示
+- 自动清理防止内存泄漏
+- 无需手动管理事件监听器
+
+## 相关组件
+
+- [MessageBox](../message-box/README_CN.md) - 用于模态信息对话框
+- [Toast](../toast/README_CN.md) - 用于通知消息
+- [Dialog](../dialog/README_CN.md) - 用于复杂的交互内容
+- [Drawer](../drawer/README_CN.md) - 侧边滑出面板
+- [ContextMenu](../context-menu/README_CN.md) - 带键盘导航的右键菜单
+- [Indicator](../indicator/README_CN.md) - 全屏加载指示器