@ticatec/topside-elements 1.0.0

package/dist/navigation/tabs/README_CN.md

@@ -0,0 +1,353 @@
+# Tabs 标签页组件
+
+水平标签页条，支持溢出滚动、可选的关闭/刷新图标、`tabRender` 钩子做完全自定义的 tab 内容，以及默认的 `children` snippet 装面板主体。`tabs` 和 `activeTab` 都可双向绑定。
+
+## 功能特性
+
+- **`bind:tabs` 和 `bind:activeTab`** —— 数组/对象双向流动。通过 × 图标关闭 tab 会自动更新父组件状态
+- **挂载时自动选首个 tab** —— 挂载时 `activeTab` 为 null 且 `tabs.length > 0` 时，首个 tab 变为 active
+- **智能 active 比较** —— 用 `keyField`（默认 `'id'`）做 active tab 匹配，不是引用相等。规避 `$state` proxy 重新包装的问题
+- **通过 `tabRender` 自定义 tab 内容** —— 传渲染函数，接收 `{ tab, closeTab, reloadTab, closable }`，完全控制 tab 外观
+- **逐 tab 可关闭** —— `closable` 是 `boolean | (tab => boolean)`。函数形式按 tab 单独判断
+- **刷新图标** —— 通过提供 `onrefresh` 显示每个 tab 的刷新图标。仅在 active tab 上可见
+- **溢出滚动** —— tab 超出条宽时左右滚动箭头淡入，通过 Svelte `Tween` 动画
+- **可选 `simple` 样式** —— 扁平无边框，用底部彩色边框标记 active
+- **`maxTabWidth`** —— 限制 tab 宽度，文字用 `…` 截断
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Tabs from '@ticatec/topside-elements/Tabs';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/Tabs';
+
+  let tabs = $state([
+    { id: 1, text: '首页' },
+    { id: 2, text: '产品' },
+    { id: 3, text: '关于' }
+  ]);
+
+  let activeTab = $state(tabs[0]);
+</script>
+
+<Tabs {tabs} bind:activeTab>
+  <div style="padding: 16px;">
+    <h2>{activeTab.text}</h2>
+    <p>{activeTab.text} 标签页的内容。</p>
+  </div>
+</Tabs>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `tabs` | `Array<any>` | `$bindable([])` | tab 对象数组。双向绑定 —— 关闭 tab 会更新这个数组 |
+| `activeTab` | `any` | `$bindable(undefined)` | 当前 active tab。双向绑定。挂载时若 undefined **自动选 `tabs[0]`** |
+| `textField` | `string` | `'text'` | 每个 tab 上用于显示文字的属性名（仅当未设 `tabRender` 时使用） |
+| `keyField` | `string` | `'id'` | 用于比较 tab 是否 active 的属性名 —— `$state` proxy 引用相等会失效，所以这个属性对可靠匹配是必需的 |
+| `simple` | `boolean` | `false` | 扁平无边框样式，active 用底部彩色边框标记 |
+| `closable` | `boolean \| TabActionHandler` | `false` | `true` = 所有 tab 可关闭（除了最后一个）；函数 = 逐 tab 判断。**关闭按钮只在 hover 时出现**，且仅 `tabs.length > 1` 时 |
+| `maxTabWidth` | `number \| undefined` | `undefined` | tab 最大像素宽度。文字用 `…` 截断 |
+| `scrollStep` | `number` | `100` | 左/右箭头点击一次滚动的像素 |
+| `tabRender` | `TabRender \| undefined` | `undefined` | 自定义渲染函数。作为 `<TabRender {tab} closeTab={...} reloadTab={...} closable={...} />` 调用 —— 仅在设置了对应的 `onremove`/`onrefresh` 时才接收 close/reload handler |
+| `onrefresh` | `TabActionHandler \| undefined` | `undefined` | 点击 tab 刷新图标时调用。**仅当此 prop 提供时**才渲染刷新图标，且仅在 active tab 上 |
+| `onremove` | `TabActionHandler \| undefined` | `undefined` | 点击 tab × 时调用。**可为 async；返回假值取消移除。** 默认行为（无 handler）总是允许移除 |
+| `style` | `string \| undefined` | `undefined` | 外层 wrapper 的内联 CSS |
+| `class` | `string \| undefined` | `undefined` | 外层 wrapper 的额外 CSS 类 |
+| `children` | `Snippet \| undefined` | `undefined` | 面板主体 —— 你为 active tab 准备的内容。渲染在 tab 条下方，总是渲染（不依赖 active tab） |
+
+## TabActionHandler / TabRender 类型
+
+```typescript
+type TabActionHandler = (tab: any) => void;
+// （库内声明，但 onremove 的返回值也会被读 —— 见下）
+type TabRender = (tab: any) => any;
+```
+
+> **`onremove` 按异步读取。** 虽然 `TabActionHandler` 类型是 `(tab) => void`，源码做 `await onremove(tab)` 并把解析值当作"可关闭"布尔。返回 `false`（或 Promise 解析为假值），tab **不**会被移除。
+
+## 布局
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│ .topside-tab-panel                                          │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ .topside-tabs-wrap                                     │ │
+│  │  [←]  [Tab 1] [Tab 2] [Tab 3 active ×] [Tab 4]    [→]  │ │
+│  │  ↑ scroll-left   (溢出时水平滚动)                       │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ .tab-content (flex 1 1 auto, overflow hidden)          │ │
+│  │   {children}                                           │ │
+│  └────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────┘
+```
+
+tab 条取自然高度；面板主体填满剩余空间。滚动箭头仅在溢出时淡入。
+
+## Active Tab 比较
+
+组件用基于 `keyField` 的比较，因为 `$state` proxy 不保留引用相等：
+
+```js
+const isActive = (tab) => {
+  if (tab == null || activeTab == null) return false;
+  const a = tab[keyField];
+  const b = activeTab[keyField];
+  if (a != null && b != null) return a === b;
+  return false;
+};
+```
+
+含义：
+
+- **你的 tab 必须有唯一 `id`**（或你设的 `keyField`）。否则没有任何 tab 视觉上"active"
+- **不要传无 key 的普通对象**如 `{ text: 'X' }` —— `isActive` 永远返回 false，看不到 active 样式
+
+## 关闭与刷新行为
+
+| 操作 | 何时出现 | handler |
+|------|---------|---------|
+| 关闭（×）图标 | hover 时，且 `tabs.length > 1` 且 `closable` 对该 tab 解析为真 | `onremove`（若设，可通过假返回值否决） |
+| 刷新（⟳）图标 | 仅 active tab，仅当提供 `onrefresh` 时 | `onrefresh` |
+
+active tab 关闭时：
+
+1. 右侧下一个 tab 变 active
+2. 若关闭的是最后一个 tab，新的末尾 tab 变 active
+3. DOM 更新后重新检查溢出、更新滚动箭头
+
+## 示例
+
+### 可关闭 tab + 确认
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/Tabs';
+
+  let tabs = $state([
+    { id: 1, text: '文档 1', dirty: false },
+    { id: 2, text: '文档 2', dirty: true },   // 有未保存改动
+    { id: 3, text: '文档 3', dirty: false }
+  ]);
+
+  let activeTab = $state(tabs[0]);
+
+  // 返回 false 取消关闭
+  async function handleRemove(tab: any) {
+    if (tab.dirty) {
+      return confirm(`关闭 ${tab.text}？未保存的改动会丢失。`);
+    }
+    return true;
+  }
+</script>
+
+<Tabs
+  {tabs}
+  bind:activeTab
+  closable={true}
+  onremove={handleRemove}
+  style="height: 320px;"
+>
+  <div style="padding: 16px;">
+    <h3>{activeTab.text}</h3>
+    <p>Tab id：{activeTab.id}</p>
+  </div>
+</Tabs>
+```
+
+### 逐 tab 判断可关闭
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/Tabs';
+
+  let tabs = $state([
+    { id: 'home',     text: '首页',   pinned: true  },   // 不可关闭
+    { id: 'inbox',    text: '收件箱', pinned: false },
+    { id: 'settings', text: '设置',   pinned: false }
+  ]);
+
+  let activeTab = $state(tabs[0]);
+
+  // pinned 的 tab 不可关闭
+  const isClosable = (tab: any) => !tab.pinned;
+</script>
+
+<Tabs
+  {tabs}
+  bind:activeTab
+  closable={isClosable}
+/>
+```
+
+### 可刷新的 active tab
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/Tabs';
+
+  let tabs = $state([
+    { id: 1, text: '收件箱' },
+    { id: 2, text: '已发送' }
+  ]);
+  let activeTab = $state(tabs[0]);
+
+  async function refresh(tab: any) {
+    console.log('刷新', tab.text);
+    await fetch(`/api/refresh/${tab.id}`);
+  }
+</script>
+
+<Tabs {tabs} bind:activeTab onrefresh={refresh}>
+  <!-- 面板内容 -->
+</Tabs>
+```
+
+### 自定义 tab 渲染（tabRender）
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/Tabs';
+  import CustomTabContent from './CustomTabContent.svelte';
+
+  let tabs = $state([...]);
+  let activeTab = $state(tabs[0]);
+</script>
+
+<Tabs
+  {tabs}
+  bind:activeTab
+  tabRender={CustomTabContent}
+  closable={true}
+  onremove={async () => true}
+/>
+```
+
+`CustomTabContent` 接收 `{ tab, closeTab, reloadTab, closable }` 作为 props —— 渲染自己的标签、图标、徽章等。
+
+### 简约样式（无边框）
+
+```svelte
+<Tabs {tabs} bind:activeTab simple>
+  <!-- 内容 -->
+</Tabs>
+```
+
+简约模式下 tab 无边框、无关闭图标、无刷新图标。active tab 用 2px 彩色底边标记。
+
+### 限制 tab 宽度
+
+```svelte
+<Tabs {tabs} bind:activeTab maxTabWidth={160}>
+  <!-- 内容 -->
+</Tabs>
+```
+
+设置 `--topside-tab-max-width: 160px`。长 tab 名用 `…` 截断。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="topside-tab-panel {className}" style="...">
+  <div>
+    <div class="topside-tabs-wrap" class:simple>
+      <div class="scroll-left" style="visibility: {showLeft}">
+        <i class="icon_google_arrow_left" onclick={...}></i>
+      </div>
+      <div class="tabs-panel" style="overflow: hidden;">
+        <div style="position: relative; left: {-scrollX.current}px">
+          <!-- 每个 tab -->
+          <div class="topside-tab {active ? 'active' : ''}" onclick={...} aria-hidden="true">
+            <!-- 自定义 tabRender 或默认 -->
+            <span>{tab[textField]}</span>
+            <i class="icon_google_refresh tab-refresh" onclick={reloadTab}></i>   <!-- 仅 active tab -->
+            <i class="icon_google_clear tab-action" onclick={closeTab}></i>       <!-- 仅 hover -->
+          </div>
+        </div>
+      </div>
+      <div class="scroll-right" style="visibility: {showRight}">
+        <i class="icon_google_arrow_right" onclick={...}></i>
+      </div>
+    </div>
+    <div class="tab-content">
+      <!-- children snippet -->
+    </div>
+  </div>
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--topside-tab-border-color` | tab 边框（默认模式下除底部外的所有边） |
+| `--topside-tab-bg` | 面板主体背景 + active tab 背景（让它们视觉上融合） |
+| `--topside-tab-inactive-background-color` | 非激活 tab 背景 |
+| `--topside-tab-hover-text-color` | hover 文字色 |
+| `--topside-tab-active-text-color` | active tab 文字色 |
+| `--topside-tab-header-radius` | 每个 tab 的左上/右上圆角 |
+| `--topside-tab-action-background` | 关闭图标后的背景（在淡色 tab 上确保可见） |
+| `--topside-primary-hover-text-color` | 滚动箭头 hover 色 |
+| `--topside-tab-max-width` | 通过 `maxTabWidth` prop 设置（CSS 用 `var(--topside-tab-max-width, none)`） |
+
+## 行为说明
+
+- **挂载时 `activeTab` 自动选 `tabs[0]`**（若 undefined）。后续 `tabs=[]` 时 `activeTab` 保持最后值
+- **关闭 active tab 选下一个**（或关闭末尾时选前一个）。组件内部处理 —— 你不需要在 `onremove` 里管
+- **`onremove` 被 await 且返回值有意义。** 类型写 `(tab) => void`，但源码按 `Promise<boolean>` 读。返回假值取消
+- **`onrefresh` 是即发即弃。** 无否决、不读返回值
+- **关闭图标只在 hover 时出现。** 触屏设备没有 hover 态，无法关闭 tab
+- **单个 tab 不能关闭。** 即使 `closable={true}`，× 图标也仅在 `tabs.length > 1` 时渲染
+- **刷新图标只在 active tab 上。** 非激活 tab 无论 `onrefresh` 都没有刷新图标
+- **tab 文字截断**：设了 `maxTabWidth` 时；否则 tab 按内容增长
+- **`tabRender` 接收的 close/reload 回调仅在对应 prop 提供时。** 没有 `onrefresh` 时 `reloadTab` 是 `null`。源码里有个怪：close handler 由 `onrefresh != null` 触发（应该是 bug —— 见下）
+- **Tween 动画滚动** —— 左/右箭头点击 300ms cubic-out 缓动
+
+## 已知怪异
+
+1. **`tabRender` 里的 `closeTab` 回调由 `onrefresh != null` 触发**（源码：`closeTab={onrefresh != null ? closeTab(tab) : null}`）。看起来是 typo —— 应该检查 `onremove != null`。结果是：用了 `tabRender` 想要关闭行为但不要刷新时，传给你的渲染器的 `closeTab` prop 是 `null`。变通：同时传一个 no-op `onrefresh={() => {}}`
+
+2. **每个 tab 都有 `aria-hidden="true"`。** 整个 tab 条对屏幕阅读器不可见。没有 `role="tab"`、`aria-selected`、`aria-controls`。与 Navigator 和 Pagination 同样的 a11y 限制
+
+3. **`children` 总是渲染。** 即使 `activeTab` 为 null，面板主体也会展示你放在 `<Tabs>...</Tabs>` 里的内容。自己用 `{#if activeTab}` 守护
+
+4. **滚动箭头用 `visibility: hidden`，不是 `display: none`。** 它们仍占 24px。出现/消失时布局不移动
+
+## 无障碍访问（重大限制）
+
+1. **每个 tab 都有 `aria-hidden="true"`** —— 屏幕阅读器看不到
+2. **没有 `role="tablist"` / `role="tab"` / `aria-selected`。** 标准 tab 语义缺失
+3. **没有 tab 间键盘导航** —— Tab 键穿过页面，不在 tab 之间移动
+4. **关闭/刷新图标是 `<i onclick>`** —— 键盘不可激活
+5. **active 状态仅靠颜色和字重传达** —— 无文字替代
+
+对屏幕阅读器/键盘用户来说，这个组件不可用。需要 a11y 时 fork 它，或把每个 tab 包成 `<button>` + `role="tab"` + `aria-selected`。
+
+## 最佳实践
+
+1. **永远给 tab 唯一 `id`**（或把 `keyField` 设为你的唯一字段）。否则没有 tab 会显示为 active
+2. **用 `bind:activeTab` 和 `bind:tabs`** —— 两者都为双向绑定设计。手动单向状态同步脆弱
+3. **用 `{#if activeTab}` 守护 `children`** —— 组件不守护，undefined 的 active tab 访问字段会抛错
+4. **`onremove` 返回 `false` 否决** —— async handler 工作；tab 等 promise
+5. **触屏不要依赖 hover 关闭 tab。** 移动端用户需要关闭 tab 时提供替代 UI
+6. **`simple` 模式彻底丢掉关闭/刷新图标。** 用于静态 tab 集合
+7. **`maxTabWidth` 让长 tab 名保持整洁** —— 配合溢出滚动用
+
+## 相关组件
+
+- [Navigator](../navigator/README_CN.md) —— 垂直步骤导航（不同 UX，类似角色）
+- [Breadcrumbs](../breadcrumbs/README_CN.md) —— 层级路径