@ticatec/topside-elements 1.0.0

package/dist/general/button/TextButton_README_CN.md

@@ -0,0 +1,569 @@
+# TextButton 文本按钮组件
+
+一个极简的基于文本的按钮组件，专为细致的操作、导航链接和次要交互而设计，当完整的按钮外观可能过于突出时使用。
+
+## 功能特性
+
+- **文本优先设计**: 简洁、极简的外观，强调文本内容
+- **多种类型**: 默认、主要、次要、第三级和第四级按钮样式
+- **尺寸选项**: 大、中、小三种尺寸
+- **工具提示支持**: 通过 `data-tip` 属性内置工具提示，支持 Markdown 格式
+- **键盘导航**: 默认 `tabindex={-1}`，取消 Tab 键停留，不影响表单等场景的顺序 Tab 聚焦；支持显式传入 `tabindex` 覆盖
+- **事件处理**: 支持点击事件
+- **无障碍访问**: 使用语义化按钮元素，支持禁用状态
+- **自定义样式**: 灵活的样式定制
+- **Snippet 支持**: 通过 children 属性支持自定义内容
+
+## 基本用法
+
+```svelte
+<script>
+import TextButton from '@ticatec/topside-elements/TextButton';
+
+const handleClick = (event) => {
+  console.log('文本按钮被点击!', event);
+};
+</script>
+
+<TextButton 
+  label="点击我" 
+  onclick={handleClick} 
+/>
+```
+
+## 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `disabled` | `boolean` | `false` | 是否禁用按钮 |
+| `size` | `'big' \| 'medium' \| 'small'` | `'medium'` | 按钮尺寸 |
+| `label` | `string` | `''` | 按钮文本标签 |
+| `type` | `'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'` | `'default'` | 按钮类型/样式 |
+| `onclick` | `(event: MouseEvent) => void` | - | 点击事件处理器 |
+| `style` | `string` | `''` | 自定义CSS样式 |
+| `theme` | `string` | - | 主题变体 |
+| `tooltip` | `string` | - | 工具提示文本（支持Markdown，使用 `\n` 换行） |
+| `children` | `Snippet` | - | 自定义内容片段 |
+| `tabindex` | `number` | `-1` | Tab 键导航顺序（默认为 -1，取消 Tab 键停留） |
+| `outer` | `boolean` | `true` | focused / active 状态时是否带外框（默认为 true，设为 false 时去除聚焦/激活外框） |
+| `variant` | `'plain' \| 'round' \| ''` | `'round'` | 形状变体（默认为 round 胶囊圆角外框，plain 为无圆角直角外框） |
+
+## 按钮类型
+
+```svelte
+<!-- 默认文本按钮 -->
+<TextButton label="默认" type="default" onclick={handleClick} />
+
+<!-- 主要文本按钮 -->
+<TextButton label="主要" type="primary" onclick={handleClick} />
+
+<!-- 次要文本按钮 -->
+<TextButton label="次要" type="secondary" onclick={handleClick} />
+
+<!-- 第三级文本按钮 -->
+<TextButton label="第三级" type="third" onclick={handleClick} />
+
+<!-- 第四级文本按钮 -->
+<TextButton label="第四级" type="forth" onclick={handleClick} />
+```
+
+## 按钮尺寸
+
+```svelte
+<!-- 小型文本按钮 -->
+<TextButton label="小型" size="small" onclick={handleClick} />
+
+<!-- 中型文本按钮（默认） -->
+<TextButton label="中型" size="medium" onclick={handleClick} />
+
+<!-- 大型文本按钮 -->
+<TextButton label="大型" size="big" onclick={handleClick} />
+```
+
+## 工具提示支持
+
+TextButton 组件内置了工具提示功能。当鼠标悬停在按钮上时，会自动显示提示文字。
+
+```svelte
+<!-- 带工具提示的文本按钮 -->
+<TextButton label="保存" tooltip="保存您的工作" type="primary" onclick={handleSave} />
+<TextButton label="取消" tooltip="关闭不保存" onclick={handleCancel} />
+
+<!-- 多行提示带 Markdown -->
+<TextButton
+  label="删除"
+  type="secondary"
+  tooltip="> **警告**：\n> 此操作无法撤销"
+  onclick={handleDelete}
+/>
+
+<!-- 禁用状态的按钮不会显示提示 -->
+<TextButton label="禁用" tooltip="此提示不会显示" disabled={true} />
+```
+
+**注意**：需要在应用中挂载 `Tooltip` 组件才能显示工具提示：
+
+```svelte
+<script>
+  import Tooltip from '@ticatec/topside-elements/Tooltip';
+</script>
+
+<Tooltip />
+<!-- 你的应用内容 -->
+```
+
+## 常见使用场景
+
+### 导航链接
+
+```svelte
+<nav class="breadcrumb">
+  <TextButton label="首页" onclick={() => goto('/')} />
+  <span class="separator">›</span>
+  <TextButton label="产品" onclick={() => goto('/products')} />
+  <span class="separator">›</span>
+  <span>当前页面</span>
+</nav>
+```
+
+### 次要操作
+
+```svelte
+<div class="action-group">
+  <Button label="保存" type="primary" onclick={handleSave} />
+  <TextButton label="取消" onclick={handleCancel} />
+  <TextButton label="保存为草稿" onclick={handleSaveDraft} />
+</div>
+```
+
+### 标签页导航
+
+```svelte
+<script>
+let activeTab = 'overview';
+
+const switchTab = (tab) => (event) => {
+  activeTab = tab;
+};
+</script>
+
+<div class="tabs">
+  <TextButton 
+    label="概览" 
+    type={activeTab === 'overview' ? 'primary' : 'default'}
+    onclick={switchTab('overview')} 
+  />
+  <TextButton 
+    label="详情" 
+    type={activeTab === 'details' ? 'primary' : 'default'}
+    onclick={switchTab('details')} 
+  />
+  <TextButton 
+    label="评价" 
+    type={activeTab === 'reviews' ? 'primary' : 'default'}
+    onclick={switchTab('reviews')} 
+  />
+</div>
+```
+
+### 菜单项
+
+```svelte
+<div class="menu">
+  <TextButton label="个人设置" onclick={openProfile} />
+  <TextButton label="账户" onclick={openAccount} />
+  <TextButton label="偏好设置" onclick={openPreferences} />
+  <TextButton label="退出登录" type="secondary" onclick={logout} />
+</div>
+```
+
+## 事件处理
+
+```svelte
+<script>
+const handleClick = (event) => {
+  console.log('文本按钮被点击:', event);
+};
+</script>
+
+<TextButton
+  label="交互文本"
+  onclick={handleClick}
+/>
+```
+
+## 禁用状态
+
+```svelte
+<TextButton 
+  label="禁用操作" 
+  disabled={true}
+  onclick={handleClick} 
+/>
+```
+
+## 自定义样式
+
+```svelte
+<TextButton 
+  label="自定义样式"
+  style="
+    color: #007acc;
+    text-decoration: underline;
+    font-weight: bold;
+    padding: 4px 8px;
+  "
+  onclick={handleClick}
+/>
+```
+
+## Snippet 用法
+
+使用 `children` 属性提供自定义内容：
+
+```svelte
+<!-- 自定义内容替代标签 -->
+<TextButton onclick={handleCustomAction}>
+  {#snippet children()}
+    <span class="custom-text">
+      <i class="fas fa-arrow-right"></i>
+      了解更多
+    </span>
+  {/snippet}
+</TextButton>
+
+<!-- 丰富内容 -->
+<TextButton onclick={handleRichAction}>
+  {#snippet children()}
+    <div class="rich-content">
+      <strong>高级选项</strong>
+      <small>配置详细设置</small>
+    </div>
+  {/snippet}
+</TextButton>
+```
+
+## 高级示例
+
+### 条件文本按钮
+
+```svelte
+<script>
+let isEditing = false;
+
+const toggleEdit = (event) => {
+  isEditing = !isEditing;
+};
+</script>
+
+<TextButton 
+  label={isEditing ? "保存更改" : "编辑"}
+  type={isEditing ? "primary" : "default"}
+  onclick={toggleEdit}
+/>
+```
+
+### 链接样式按钮
+
+```svelte
+<TextButton 
+  label="访问我们的网站"
+  style="
+    color: #007acc;
+    text-decoration: underline;
+    background: none;
+    border: none;
+    padding: 0;
+  "
+  onclick={() => window.open('https://example.com', '_blank')}
+/>
+```
+
+### 可展开部分
+
+```svelte
+<script>
+let isExpanded = false;
+
+const toggleSection = (event) => {
+  isExpanded = !isExpanded;
+};
+</script>
+
+<div class="expandable-section">
+  <TextButton 
+    label={isExpanded ? "显示更少 ▲" : "显示更多 ▼"}
+    onclick={toggleSection}
+  />
+  
+  {#if isExpanded}
+    <div class="expanded-content">
+      <p>额外的内容放在这里...</p>
+    </div>
+  {/if}
+</div>
+```
+
+### 分页控件
+
+```svelte
+<script>
+let currentPage = 1;
+let totalPages = 10;
+
+const goToPage = (page) => (event) => {
+  if (page >= 1 && page <= totalPages) {
+    currentPage = page;
+  }
+};
+</script>
+
+<div class="pagination">
+  <TextButton 
+    label="上一页"
+    disabled={currentPage === 1}
+    onclick={goToPage(currentPage - 1)}
+  />
+  
+  <span class="page-info">第 {currentPage} 页，共 {totalPages} 页</span>
+  
+  <TextButton 
+    label="下一页"
+    disabled={currentPage === totalPages}
+    onclick={goToPage(currentPage + 1)}
+  />
+</div>
+```
+
+### 过滤选项
+
+```svelte
+<script>
+let activeFilters = new Set();
+
+const toggleFilter = (filter) => (event) => {
+  if (activeFilters.has(filter)) {
+    activeFilters.delete(filter);
+  } else {
+    activeFilters.add(filter);
+  }
+  activeFilters = activeFilters; // 触发响应式更新
+};
+</script>
+
+<div class="filters">
+  <TextButton 
+    label="全部"
+    type={activeFilters.size === 0 ? 'primary' : 'default'}
+    onclick={() => activeFilters = new Set()}
+  />
+  <TextButton 
+    label="活跃"
+    type={activeFilters.has('active') ? 'primary' : 'default'}
+    onclick={toggleFilter('active')}
+  />
+  <TextButton 
+    label="已完成"
+    type={activeFilters.has('completed') ? 'primary' : 'default'}
+    onclick={toggleFilter('completed')}
+  />
+</div>
+```
+
+### 表单操作
+
+```svelte
+<div class="form-actions">
+  <Button label="提交" type="primary" onclick={handleSubmit} />
+  
+  <div class="secondary-actions">
+    <TextButton label="保存为草稿" onclick={saveDraft} />
+    <TextButton label="预览" onclick={showPreview} />
+    <TextButton label="重置" type="secondary" onclick={resetForm} />
+  </div>
+</div>
+
+<style>
+  .form-actions {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    align-items: flex-start;
+  }
+  
+  .secondary-actions {
+    display: flex;
+    gap: 16px;
+  }
+</style>
+```
+
+### 下拉菜单触发器
+
+```svelte
+<script>
+let showDropdown = false;
+
+const toggleDropdown = (event) => {
+  showDropdown = !showDropdown;
+};
+</script>
+
+<div class="dropdown-container">
+  <TextButton 
+    label="选项 ▼"
+    type={showDropdown ? 'primary' : 'default'}
+    onclick={toggleDropdown}
+  />
+  
+  {#if showDropdown}
+    <div class="dropdown-menu">
+      <TextButton label="选项 1" onclick={selectOption1} />
+      <TextButton label="选项 2" onclick={selectOption2} />
+      <TextButton label="选项 3" onclick={selectOption3} />
+    </div>
+  {/if}
+</div>
+```
+
+## 无障碍访问
+
+TextButton 组件遵循无障碍访问最佳实践：
+
+- 使用语义化的 `<button>` 元素
+- 默认设置 `tabindex={-1}`，不接收 Tab 键聚焦，避免在弱化按钮或次要操作中产生大量无谓的 Tab 停顿
+- 支持按需显式指定 `tabindex`（例如 `tabindex={0}`）
+- 正确的禁用状态处理（禁用时始终不可聚焦）
+- 聚焦时显示可见的焦点指示器
+
+### 键盘导航
+
+- **Tab** - 默认跳过（`tabindex={-1}`）；若显式指定为 `0` 则可将焦点移入/移出按钮
+- **Enter / Space** - 焦点在按钮上时激活
+- **焦点可见** - 聚焦时显示外边框（4px），与按钮之间有 2px 透明间隙。外框颜色与按钮类型颜色一致（primary 为蓝色、secondary 为红色等）
+
+### 改善无障碍访问
+
+```svelte
+<!-- 为屏幕阅读器提供上下文 -->
+<TextButton
+  label="删除"
+  tooltip="永久删除此项目"
+  onclick={handleDelete}
+  aria-label="永久删除此项目"
+/>
+
+<!-- 使用 tooltip 提供额外上下文 -->
+<TextButton
+  label="了解更多"
+  tooltip="打开详细信息"
+  onclick={showDetails}
+/>
+```
+
+## 样式定制
+
+组件使用以下 CSS 类：
+
+- `.topside-button` - 基础按钮类
+- `.text-button` - 文本按钮特定样式
+- `.{size}` - 尺寸特定样式（big、medium、small）
+- `.{type}` - 类型特定样式（default、primary 等）
+- `.disabled` - 禁用状态样式
+
+### CSS 变量
+
+```css
+:root {
+  /* 文本按钮颜色 */
+  --text-btn-text: #374151;
+  --text-btn-hover-bg: rgba(0, 0, 0, 0.05);
+  --text-btn-disabled-text: #B3BCCA;
+}
+```
+
+### 嵌入式 CSS
+
+组件使用嵌入式 CSS（无需外部 SCSS 导入）。
+
+### 焦点状态
+
+键盘焦点使用 `:focus-visible` 伪类处理，仅在使用键盘（Tab）聚焦时显示焦点指示器。聚焦时显示与悬停状态相同的背景色。
+
+## 最佳实践
+
+1. **适当的上下文**: 将文本按钮用于次要操作和导航
+2. **清晰的标签**: 提供清楚表明操作的描述性标签
+3. **视觉层次**: 使用不同类型建立适当的视觉层次
+4. **一致的间距**: 在文本按钮之间保持一致的间距
+5. **悬停状态**: 确保悬停状态提供清晰的反馈
+6. **无障碍访问**: 始终考虑键盘导航和屏幕阅读器
+7. **上下文感知**: 确保文本按钮在其周围环境中工作良好
+
+## 常见模式
+
+### 内联操作
+
+```svelte
+<p>
+  您的更改已保存。
+  <TextButton label="撤销" onclick={undoChanges} />
+</p>
+```
+
+### 卡片操作
+
+```svelte
+<div class="card">
+  <h3>文章标题</h3>
+  <p>文章摘要...</p>
+  
+  <div class="card-actions">
+    <TextButton label="阅读更多" type="primary" onclick={readMore} />
+    <TextButton label="分享" onclick={shareArticle} />
+    <TextButton label="保存" onclick={saveArticle} />
+  </div>
+</div>
+```
+
+### 列表项操作
+
+```svelte
+<div class="list-item">
+  <span class="item-name">文档.pdf</span>
+  <div class="item-actions">
+    <TextButton label="下载" onclick={download} />
+    <TextButton label="分享" onclick={share} />
+    <TextButton label="删除" type="secondary" onclick={deleteFile} />
+  </div>
+</div>
+```
+
+## 与其他组件集成
+
+```svelte
+<!-- 与模态框 -->
+<Modal bind:open={showModal}>
+  <h2>确认操作</h2>
+  <p>您确定要继续吗？</p>
+
+  <div class="modal-actions">
+    <Button label="确认" type="primary" onclick={confirm} />
+    <TextButton label="取消" onclick={() => showModal = false} />
+  </div>
+</Modal>
+```
+
+## 浏览器支持
+
+TextButton组件在支持以下特性的所有现代浏览器中工作：
+- ES6+ JavaScript
+- CSS Flexbox
+- 语义化按钮元素
+
+## 性能
+
+- 最小化的样式，快速渲染
+- 内置点击防抖
+- 高效的事件处理
+- 轻量级DOM结构

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

@@ -0,0 +1,8 @@
+import Button from "./Button.svelte";
+import IconButton from "./IconButton.svelte";
+import TextButton from "./TextButton.svelte";
+import type { ButtonType } from "../../types";
+export default Button;
+export { IconButton };
+export { TextButton };
+export type { ButtonType };

package/dist/general/button/index.js

@@ -0,0 +1,6 @@
+import Button from "./Button.svelte";
+import IconButton from "./IconButton.svelte";
+import TextButton from "./TextButton.svelte";
+export default Button;
+export { IconButton };
+export { TextButton };

package/dist/general/icon/Icon.svelte

@@ -0,0 +1,90 @@
+<script lang="ts">
+    import type {OnClick} from "../../types";
+
+    interface Props {
+        name: string;
+        onclick?: OnClick | null;
+        style?: string;
+        theme?: string;
+        class?: string;
+        tooltip?: string;
+        disabled?: boolean;
+        tabindex?: number;
+    }
+
+    let {
+        name,
+        onclick = null,
+        style = '',
+        theme,
+        class: className = '',
+        tooltip,
+        disabled = false,
+        tabindex
+    }: Props = $props();
+
+    let respClick = $state(true);
+
+    async function handleClickEvent(e: MouseEvent) {
+        if (disabled) return;
+        if (onclick != null && respClick) {
+            respClick = false;
+            await onclick?.(e);
+            await new Promise(resolve => setTimeout(resolve, 200));
+            respClick = true;
+        }
+    }
+
+    const isInteractive = $derived(onclick != null);
+
+    function handleKeyDown(e: KeyboardEvent) {
+        if (isInteractive && !disabled && (e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            handleClickEvent(e as unknown as MouseEvent);
+        }
+    }
+</script>
+
+<!-- role/tabindex are only ever both set together when onclick is provided
+     (isInteractive); svelte-check can't verify that pairing statically. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div
+    class="topside-icon {theme} {className}"
+    class:clickable={onclick!=null && !disabled}
+    class:disabled={disabled}
+    onmousedown={(event: MouseEvent) => {event.preventDefault();}}
+    {style}
+    role={isInteractive ? 'button' : undefined}
+    tabindex={tabindex !== undefined ? tabindex : (isInteractive && !disabled ? 0 : undefined)}
+    aria-disabled={isInteractive ? disabled : undefined}
+    aria-hidden={isInteractive ? undefined : true}
+    aria-label={isInteractive ? (tooltip || undefined) : undefined}
+    data-tip={disabled ? null : tooltip || null}
+    onclick={handleClickEvent}
+    onkeydown={handleKeyDown}
+>
+    <i class={name}></i>
+</div>
+
+<style>
+    .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);
+    }
+</style>

package/dist/general/icon/Icon.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { OnClick } from "../../types";
+interface Props {
+    name: string;
+    onclick?: OnClick | null;
+    style?: string;
+    theme?: string;
+    class?: string;
+    tooltip?: string;
+    disabled?: boolean;
+    tabindex?: number;
+}
+declare const Icon: import("svelte").Component<Props, {}, "">;
+type Icon = ReturnType<typeof Icon>;
+export default Icon;