@ticatec/topside-elements 1.0.0

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/topside-elements
+```
+
+## Import
+
+```typescript
+import Tabs from '@ticatec/topside-elements/Tabs';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/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
+┌────────────────────────────────────────────────────────────┐
+│ .topside-tab-panel                                          │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ .topside-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/topside-elements/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/topside-elements/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/topside-elements/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/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` 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 `--topside-tab-max-width: 160px`. Long tab names truncate with `…`.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```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">
+          <!-- per tab -->
+          <div class="topside-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 |
+|----------|---------|
+| `--topside-tab-border-color` | Tab border (all sides except bottom in default mode) |
+| `--topside-tab-bg` | Panel body background + active tab background (so they visually merge) |
+| `--topside-tab-inactive-background-color` | Inactive tab background |
+| `--topside-tab-hover-text-color` | Hover text color |
+| `--topside-tab-active-text-color` | Active tab text color |
+| `--topside-tab-header-radius` | Top-left/top-right radius of each tab |
+| `--topside-tab-action-background` | Background behind the close icon (for visibility on tinted tabs) |
+| `--topside-primary-hover-text-color` | Scroll arrow hover color |
+| `--topside-tab-max-width` | Set via `maxTabWidth` prop (CSS uses `var(--topside-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