@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/navigation/progress_step_bar/README_CN.md

@@ -0,0 +1,245 @@
+# ProgressStepBar 步骤进度条组件
+
+多步骤进度指示器，按顺序显示各步骤的完成状态。渲染带编号的圆圈，圆圈之间用线连接；每步是 `Pending`、`Processing` 或 `Completed`。支持横向（默认）和纵向布局。纯展示组件 —— 无点击 handler。
+
+## 功能特性
+
+- **三种状态**：`Pending`（灰色数字）、`Processing`（实心蓝圆）、`Completed`（蓝色淡背景圆 + 对勾）
+- **连接线**：通过 CSS `linear-gradient` 在相邻圆圈之间画线；线颜色跟随步骤状态（已完成蓝、未开始灰）
+- **横向或纵向布局**：横向默认，纵向用于侧边栏
+- **每步可选注释**：在 topic 下方显示较小的次要文字
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+
+  const steps: ProgressStep[] = [
+    { topic: '注册',   comment: '完善资料',     status: ProgressStepStatus.Completed },
+    { topic: '验证',   comment: '验证邮箱',     status: ProgressStepStatus.Processing },
+    { topic: '设置',   comment: '配置偏好',     status: ProgressStepStatus.Pending }
+  ];
+</script>
+
+<ProgressStepBar {steps} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `steps` | `ProgressStep[]` | _(必填)_ | 有序步骤列表。每项在数组中的位置决定其编号（显示为 `idx + 1`） |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 布局方向。横向 = 从左到右一行；纵向 = 从上到下一列 |
+| `style` | `string`\| undefined` | `undefined`  | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+
+## ProgressStep 类型
+
+```typescript
+interface ProgressStep {
+  topic: string;              // 步骤标题（必填）
+  comment?: string;           // 可选的次要文字，显示在 topic 下方
+  status: ProgressStepStatus; // 当前状态
+}
+```
+
+## ProgressStepStatus 枚举
+
+```typescript
+enum ProgressStepStatus {
+  Pending    = 'pending',     // 灰色数字、灰色文字
+  Processing = 'processing',  // 实心蓝圆 + 白色数字、蓝色文字
+  Completed  = 'completed',   // 蓝色淡背景圆 + 对勾（✔）、深灰文字
+}
+```
+
+枚举值也是每个步骤块上的 CSS 类（`Pending` → `.pending` 等）。
+
+## 视觉设计
+
+```text
+横向：
+
+   ●─────●─────○─────○
+   1     2     3     4
+   注册   验证   设置   完成
+   完成   ...
+
+纵向：
+
+   ●
+   │ 1
+   │ 注册
+   │
+   ●
+   │ 2
+   │ 验证
+   │
+   ○
+     3
+     设置
+```
+
+实心圆（●）是已完成或进行中；空心圆（○）是未开始。连接线在步骤 `Completed` 时为蓝色，`Pending` 时为灰色。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="uniface-progress-step-container {direction}" data-theme="..." style="...">
+  <div class="container-panel">
+    <!-- 每步 -->
+    <div class="progress-step-block {status} {direction}">
+      <div class="step-indicator">
+        <div>
+          <span>✔</span>          <!-- Completed -->
+          <!-- 或 -->
+          <span>{pos}</span>      <!-- Pending / Processing -->
+        </div>
+      </div>
+      <div class="step-text {status}">
+        <div class="step-topic"><span>{topic}</span></div>
+        <!-- 仅提供 comment 时 -->
+        <div class="step-comment"><span>{comment}</span></div>
+      </div>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--uniface-progress-step-bar-color-surface` | 容器背景（也用作"线后面的背景"，让线看起来在圆圈处中断） |
+| `--uniface-progress-step-bar-bg` | 进行中圆圈内的前景色（默认白） |
+| `--uniface-progress-step-pending-color` | 未开始圆圈边框 + 线 + 文字（灰） |
+| `--uniface-progress-step-completed-color` | 已完成 topic / comment 文字（深灰） |
+| `--uniface-progress-step-completed-icon-color` | 已完成圆圈边框 + 对勾 + 线（蓝） |
+| `--uniface-progress-step-completed-icon-bg` | 已完成圆圈背景（淡蓝） |
+| `--uniface-progress-step-processing-color` | 进行中圆圈填充 + topic 文字（蓝） |
+
+### 连接线怎么画的
+
+每个步骤的 `background` 是个 `linear-gradient`，在指示器中心画一条 2px 横线（或竖线）。圆圈本身在上面，背景同色，让线看起来在圆圈处断开。状态相关的类覆盖 gradient 颜色。
+
+这个机制脆弱 —— 把 `--uniface-progress-step-bar-color-surface` 改成非纯色背景（图片、渐变），线会从圆圈里漏出来。
+
+## 示例
+
+### 动态进度（Svelte 5 runes）
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+
+  let steps = $state<ProgressStep[]>([
+    { topic: '初始化',   comment: '正在设置...',   status: ProgressStepStatus.Pending },
+    { topic: '数据加载', comment: '正在获取...',   status: ProgressStepStatus.Pending },
+    { topic: '处理中',   comment: '正在分析...',   status: ProgressStepStatus.Pending },
+    { topic: '完成',     comment: '正在收尾...',   status: ProgressStepStatus.Pending }
+  ]);
+
+  let currentIdx = 0;
+
+  function advance() {
+    if (currentIdx >= steps.length) return;
+
+    steps[currentIdx].status = ProgressStepStatus.Processing;
+
+    setTimeout(() => {
+      steps[currentIdx].status = ProgressStepStatus.Completed;
+      currentIdx++;
+
+      if (currentIdx < steps.length) {
+        steps[currentIdx].status = ProgressStepStatus.Processing;
+        advance();
+      }
+    }, 1500);
+  }
+
+  advance();
+</script>
+
+<ProgressStepBar {steps} />
+```
+
+### 纵向布局
+
+```svelte
+<div style="height: 480px;">
+  <ProgressStepBar {steps} direction="vertical" />
+</div>
+```
+
+纵向模式会填满父容器高度 —— 确保父容器有高度，否则布局会塌。
+
+### 纯展示（静态步骤）
+
+用于"你的订单在第 N 步"这类视图：
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+
+  const orderSteps: ProgressStep[] = [
+    { topic: '下单',       status: ProgressStepStatus.Completed },
+    { topic: '支付成功',   status: ProgressStepStatus.Completed },
+    { topic: '已发货',     status: ProgressStepStatus.Processing },
+    { topic: '派送中',     status: ProgressStepStatus.Pending },
+    { topic: '已签收',     status: ProgressStepStatus.Pending }
+  ];
+</script>
+
+<ProgressStepBar steps={orderSteps} />
+```
+
+## 行为说明
+
+- **纯展示。** 无点击 handler —— 用户不能在步骤间跳转。需要交互式步骤导航用 [Navigator](../navigator/README_CN.md)
+- **响应式。** 修改 `steps[i].status`（用 `$state` 数组）UI 就更新。组件通过 Svelte 5 响应式重渲染
+- **`topic` 用 `…` 截断**（`white-space: nowrap; text-overflow: ellipsis`）。保持 topic 简短
+- **`comment` 可多行**，但本身不截断 —— 长注释可能破坏布局
+- **首步无左 margin**；后续步骤横向 `margin-left: 8px`，纵向无 margin（因为线是竖向连接的）
+- **末步保留线**为了视觉连续 —— 有 `.progress-step-block:last-child` 规则但横向模式下为空。纵向模式下末步的线被 unset
+
+## 无障碍访问
+
+- **纯视觉。** 没有 ARIA role、processing 步骤没有 `aria-current`、指示器没有 `aria-label`
+- 对勾 `✔` 是字面 Unicode 文字 —— 屏幕阅读器会读成"对勾"。觉得吵的话在 fork 里换成图标字体 + `aria-hidden="true"`
+- 步骤状态（Pending / Processing / Completed）只靠颜色 + 圆圈填充传达 —— 没有文字替代。fork 时在每个块上加 `aria-label="第 N 步：{topic}，{status}"` 支持屏幕阅读器
+- 无键盘交互（纯展示，所以没问题）
+
+## 已知怪异
+
+1. **连接线通过每个步骤块的 `background` gradient 实现。** 把 surface 色（`--uniface-progress-step-bar-color-surface`）改成非纯色背景（图片、渐变），线会从圆圈里漏出来
+
+## 最佳实践
+
+1. **`steps` 数组用 `$state`**，需要实时进度更新时。修改 `steps[i].status` 触发重渲染
+2. **`topic` 保持简短** —— 会用 `…` 截断。详情移到 `comment`
+3. **`direction="vertical"` 只在高度受限的父容器里用**（侧边栏、抽屉）。否则会塌
+4. **同时只一个 `Processing` 步骤** —— 多了视觉混乱。把之前的标 `Completed`
+5. **颜色通过 CSS 变量覆盖**，不要改内部类样式 —— 结构脆弱（见连接线说明）
+6. **需要交互式步骤导航用 [Navigator](../navigator/README_CN.md)** —— 这个组件是纯展示
+
+## 相关组件
+
+- [Navigator](../navigator/README_CN.md) —— 交互式步骤导航（可点击项）
+- [ProgressSteps](../progress_steps/README_CN.md) —— 同类步骤组件（如果存在）

package/dist/navigation/tabs/README.md

@@ -0,0 +1,353 @@
+# Tabs Component
+
+A horizontal tab bar with overflow scrolling, optional close/refresh icons per tab, a `tabRender` hook for fully custom tab content, and a default `children` snippet for the panel body. Both `tabs` and `activeTab` are two-way bindable.
+
+## Features
+
+- **`bind:tabs` and `bind:activeTab`** — both arrays/objects flow both ways. Close a tab via the × icon and the parent state updates automatically.
+- **Auto-select first tab on mount** — if `activeTab` is null when the component mounts and `tabs.length > 0`, the first tab becomes active.
+- **Smart active comparison** — uses `keyField` (default `'id'`) for active-tab matching, not reference equality. Survives `$state` proxy re-wrapping.
+- **Custom tab content via `tabRender`** — pass a render function that receives `{ tab, closeTab, reloadTab, closable }` for full control of tab appearance.
+- **Per-tab closability** — `closable` is `boolean | (tab => boolean)`. Function form decides per-tab.
+- **Refresh icon** — show a refresh icon per tab by providing `onrefresh`. Only visible on the active tab.
+- **Overflow scrolling** — left/right scroll arrows fade in when tabs exceed the bar width, animated via Svelte `Tween`.
+- **Optional `simple` style** — flat, borderless tabs marked by a colored bottom border.
+- **`maxTabWidth`** — cap tab width, text truncates with `…`.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Tabs from '@ticatec/uniface-element/Tabs';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/uniface-element/Tabs';
+
+  let tabs = $state([
+    { id: 1, text: 'Home' },
+    { id: 2, text: 'Products' },
+    { id: 3, text: 'About' }
+  ]);
+
+  let activeTab = $state(tabs[0]);
+</script>
+
+<Tabs {tabs} bind:activeTab>
+  <div style="padding: 16px;">
+    <h2>{activeTab.text}</h2>
+    <p>Content for {activeTab.text} tab.</p>
+  </div>
+</Tabs>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tabs` | `Array<any>` | `$bindable([])` | Tab objects. Two-way bindable — closing a tab updates this array. |
+| `activeTab` | `any` | `$bindable(undefined)` | Currently active tab. Two-way bindable. **Auto-selects `tabs[0]` on mount** if undefined. |
+| `textField` | `string` | `'text'` | Property name on each tab for the display text (only used when `tabRender` is not set) |
+| `keyField` | `string` | `'id'` | Property name used to compare tabs for "is active" — reference equality fails for `$state` proxies, so this is required for reliable matching |
+| `simple` | `boolean` | `false` | Flat borderless style with bottom-border accent on active |
+| `closable` | `boolean \| TabActionHandler` | `false` | `true` = all tabs closable (except the last one); function = per-tab decision. **Close button only appears on hover** and only when `tabs.length > 1`. |
+| `maxTabWidth` | `number \| undefined` | `undefined` | Max tab width in pixels. Text truncates with `…`. |
+| `scrollStep` | `number` | `100` | Pixels scrolled per left/right arrow click |
+| `tabRender` | `TabRender \| undefined` | `undefined` | Custom render function. Called as `<TabRender {tab} closeTab={...} reloadTab={...} closable={...} />` — receives close/reload handlers when the corresponding `onremove`/`onrefresh` props are set. |
+| `onrefresh` | `TabActionHandler \| undefined` | `undefined` | Called when a tab's refresh icon is clicked. Refresh icon only renders when this is provided, and only on the active tab. |
+| `onremove` | `TabActionHandler \| undefined` | `undefined` | Called when a tab's × is clicked. **May be async; return falsy to cancel the removal.** Default behavior (no handler) always allows removal. |
+| `style` | `string \| undefined` | `undefined` | Inline CSS on the outer wrapper |
+| `class` | `string \| undefined` | `undefined` | Extra CSS class on the outer wrapper |
+| `children` | `Snippet \| undefined` | `undefined` | Panel body — your content for the active tab. Rendered below the tab bar, always (not conditional on active tab). |
+
+## TabActionHandler / TabRender Types
+
+```typescript
+type TabActionHandler = (tab: any) => void;
+// (declared in the lib, but onremove's return value is also read — see below)
+type TabRender = (tab: any) => any;
+```
+
+> **`onremove` is read as async.** Although `TabActionHandler` is typed `(tab) => void`, the source does `await onremove(tab)` and treats the resolved value as a "can close" boolean. If you return `false` (or a Promise resolving to falsy), the tab is **not** removed.
+
+## Layout
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│ .uniface-tab-panel                                          │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ .uniface-tabs-wrap                                     │ │
+│  │  [←]  [Tab 1] [Tab 2] [Tab 3 active ×] [Tab 4]    [→]  │ │
+│  │  ↑ scroll-left   (overflow tabs scroll horizontally)   │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ .tab-content (flex 1 1 auto, overflow hidden)          │ │
+│  │   {children}                                           │ │
+│  └────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────┘
+```
+
+The tab bar takes its natural height; the panel body fills the remaining space. Scroll arrows fade in only when overflow exists.
+
+## Active Tab Comparison
+
+The component uses `keyField`-based comparison because `$state` proxies don't preserve reference equality:
+
+```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;
+};
+```
+
+Implications:
+
+- **Your tabs must have a unique `id`** (or whatever you set `keyField` to). Without it, no tab is ever "active" visually.
+- **Don't pass plain unkeyed objects** like `{ text: 'X' }` — `isActive` always returns false and you'll see no active styling.
+
+## Close & Refresh Behavior
+
+| Action | When it appears | Handler |
+|--------|-----------------|---------|
+| Close (×) icon | On hover, only when `tabs.length > 1` AND `closable` resolves truthy for that tab | `onremove` (if set, may veto via falsy return) |
+| Refresh (⟳) icon | Only on the active tab, only when `onrefresh` is provided | `onrefresh` |
+
+When the active tab is closed:
+
+1. The next tab to the right becomes active.
+2. If the closed tab was the last, the new last tab becomes active.
+3. After the DOM updates, overflow is re-checked and scroll arrows update.
+
+## Examples
+
+### Closable Tabs with Confirmation
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/uniface-element/Tabs';
+
+  let tabs = $state([
+    { id: 1, text: 'Document 1', dirty: false },
+    { id: 2, text: 'Document 2', dirty: true },   // unsaved changes
+    { id: 3, text: 'Document 3', dirty: false }
+  ]);
+
+  let activeTab = $state(tabs[0]);
+
+  // Returning false cancels the close
+  async function handleRemove(tab: any) {
+    if (tab.dirty) {
+      return confirm(`Close ${tab.text}? Unsaved changes will be lost.`);
+    }
+    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>
+```
+
+### Per-Tab Closable Decision
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/uniface-element/Tabs';
+
+  let tabs = $state([
+    { id: 'home',    text: 'Home',     pinned: true  },   // can't close
+    { id: 'inbox',   text: 'Inbox',    pinned: false },
+    { id: 'settings',text: 'Settings', pinned: false }
+  ]);
+
+  let activeTab = $state(tabs[0]);
+
+  // Pinned tabs are not closable
+  const isClosable = (tab: any) => !tab.pinned;
+</script>
+
+<Tabs
+  {tabs}
+  bind:activeTab
+  closable={isClosable}
+/>
+```
+
+### Refreshable Active Tab
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/uniface-element/Tabs';
+
+  let tabs = $state([
+    { id: 1, text: 'Inbox' },
+    { id: 2, text: 'Sent' }
+  ]);
+  let activeTab = $state(tabs[0]);
+
+  async function refresh(tab: any) {
+    console.log('Refreshing', tab.text);
+    await fetch(`/api/refresh/${tab.id}`);
+  }
+</script>
+
+<Tabs {tabs} bind:activeTab onrefresh={refresh}>
+  <!-- panel content -->
+</Tabs>
+```
+
+### Custom Tab Rendering (tabRender)
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/uniface-element/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` receives `{ tab, closeTab, reloadTab, closable }` as props — render its own label, icons, badges, etc.
+
+### Simple Style (Borderless)
+
+```svelte
+<Tabs {tabs} bind:activeTab simple>
+  <!-- content -->
+</Tabs>
+```
+
+In simple mode, tabs have no borders, no close icons, no refresh icons. Active tab is marked by a 2px colored bottom border.
+
+### Constrained Tab Width
+
+```svelte
+<Tabs {tabs} bind:activeTab maxTabWidth={160}>
+  <!-- content -->
+</Tabs>
+```
+
+Sets `--uniface-tab-max-width: 160px`. Long tab names truncate with `…`.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="uniface-tab-panel {className}" style="...">
+  <div>
+    <div class="uniface-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">
+          <!-- per tab -->
+          <div class="uniface-tab {active ? 'active' : ''}" onclick={...} aria-hidden="true">
+            <!-- custom tabRender OR default -->
+            <span>{tab[textField]}</span>
+            <i class="icon_google_refresh tab-refresh" onclick={reloadTab}></i>   <!-- active tab only -->
+            <i class="icon_google_clear tab-action" onclick={closeTab}></i>       <!-- hover only -->
+          </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 Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--uniface-tab-border-color` | Tab border (all sides except bottom in default mode) |
+| `--uniface-tab-bg` | Panel body background + active tab background (so they visually merge) |
+| `--uniface-tab-inactive-background-color` | Inactive tab background |
+| `--uniface-tab-hover-text-color` | Hover text color |
+| `--uniface-tab-active-text-color` | Active tab text color |
+| `--uniface-tab-header-radius` | Top-left/top-right radius of each tab |
+| `--uniface-tab-action-background` | Background behind the close icon (for visibility on tinted tabs) |
+| `--uniface-primary-hover-text-color` | Scroll arrow hover color |
+| `--uniface-tab-max-width` | Set via `maxTabWidth` prop (CSS uses `var(--uniface-tab-max-width, none)`) |
+
+## Behavior Notes
+
+- **`activeTab` auto-selects `tabs[0]` on mount** if undefined. If you later set `tabs=[]`, `activeTab` stays at its last value.
+- **Closing the active tab picks the next sibling** (or the previous if closing the last). The component handles this internally — you don't need to in `onremove`.
+- **`onremove` is awaited and its return value matters.** Type says `(tab) => void`, but the source reads it as `Promise<boolean>`. Return falsy to cancel.
+- **`onrefresh` is fire-and-forget.** No veto, no return value checking.
+- **Close icon only on hover.** Users on touch devices have no way to close tabs (no hover state).
+- **Single tab can't be closed.** Even with `closable={true}`, the × icon only renders when `tabs.length > 1`.
+- **Refresh icon only on active tab.** Inactive tabs have no refresh icon regardless of `onrefresh`.
+- **Tab text truncates** when `maxTabWidth` is set; otherwise tabs grow to fit content.
+- **`tabRender` receives close/reload callbacks only when the corresponding prop is set.** Without `onrefresh`, `reloadTab` is `null`. There's a quirk in the source where the close handler is gated by `onrefresh != null` (likely a bug — see below).
+- **Tween-animated scrolling** — 300ms cubic-out easing for left/right arrow clicks.
+
+## Known Quirks
+
+1. **`closeTab` callback in `tabRender` is gated by `onrefresh != null`** (source line: `closeTab={onrefresh != null ? closeTab(tab) : null}`). This looks like a typo — should probably check `onremove != null`. As a result, if you use `tabRender` and want close behavior but no refresh, the `closeTab` prop passed to your renderer will be `null`. Workaround: also pass a no-op `onrefresh={() => {}}`.
+
+2. **`aria-hidden="true"` on every tab.** The entire tab bar is invisible to screen readers. No `role="tab"`, no `aria-selected`, no `aria-controls`. Same a11y limitation as Navigator and Pagination.
+
+3. **`children` is always rendered.** Even if `activeTab` is null, the panel body shows whatever you put inside `<Tabs>...</Tabs>`. Guard with `{#if activeTab}` yourself.
+
+4. **Scroll arrows use `visibility: hidden`, not `display: none`.** They still take up 24px each. Layout doesn't shift when they appear/disappear.
+
+## Accessibility (Significant Limitations)
+
+1. **Every tab has `aria-hidden="true"`** — invisible to screen readers.
+2. **No `role="tablist"` / `role="tab"` / `aria-selected`.** Standard tab semantics are missing.
+3. **No keyboard navigation between tabs** — Tab key moves through the page, not between tabs.
+4. **Close/refresh icons are `<i onclick>`** — not keyboard-activatable.
+5. **Active state conveyed by color and font-weight only** — no text alternative.
+
+For screen-reader/keyboard users, this component is unusable. If accessibility matters, fork it or wrap each tab in a `<button>` with `role="tab"` and `aria-selected`.
+
+## Best Practices
+
+1. **Always give tabs a unique `id`** (or set `keyField` to your unique field). Without it, no tab will ever show as active.
+2. **Use `bind:activeTab` and `bind:tabs`** — both are designed for two-way binding. Manual one-way state sync is fragile.
+3. **Guard `children` with `{#if activeTab}`** — the component doesn't, and an undefined active tab will throw if you access its fields.
+4. **Use `onremove` returning `false` to veto** — async handlers work; the tab waits for the promise.
+5. **Don't rely on hover for tab close on touch devices.** Provide an alternative UI if mobile users need to close tabs.
+6. **`simple` mode drops close/refresh icons entirely.** Use it for static tab sets.
+7. **`maxTabWidth` keeps the bar tidy for long tab names** — pair with overflow scrolling.
+
+## Related Components
+
+- [Navigator](../navigator/README.md) — vertical step navigation (different UX, similar role)
+- [Breadcrumbs](../breadcrumbs/README.md) — hierarchical path