@reliability-design/web 1.4.6 → 1.4.7

package/dist/components/rel-tab/README.md

@@ -1,163 +1,171 @@
-# rel-tab
-
-## Overview
-A tabbed interface component with automatic underline indicator, keyboard navigation, optional badge counts, and disabled states. Features ARIA-compliant navigation with roving tabindex and arrow key support.
-
-## Usage
-```html
-<!-- Basic tabs -->
-<rel-tab id="basicTabs"></rel-tab>
-<script>
-  const tabs = document.getElementById('basicTabs');
-  tabs.tabs = [
-    { label: 'Overview' },
-    { label: 'Details' },
-    { label: 'Settings' }
-  ];
-  tabs.activeIndex = 0;
-</script>
-
-<!-- With badges (notification counts) -->
-<rel-tab id="badgeTabs"></rel-tab>
-<script>
-  const badgeTabs = document.getElementById('badgeTabs');
-  badgeTabs.tabs = [
-    { label: 'Inbox', badge: 5 },
-    { label: 'Drafts', badge: 2 },
-    { label: 'Sent' }
-  ];
-</script>
-
-<!-- With disabled tab -->
-<rel-tab id="disabledTabs"></rel-tab>
-<script>
-  const disabledTabs = document.getElementById('disabledTabs');
-  disabledTabs.tabs = [
-    { label: 'Available' },
-    { label: 'Coming Soon', disabled: true },
-    { label: 'Active' }
-  ];
-</script>
-
-<!-- Listen for tab changes -->
-<rel-tab id="tabsWithListener"></rel-tab>
-<script>
-  const listener = document.getElementById('tabsWithListener');
-  listener.tabs = [
-    { label: 'Tab 1' },
-    { label: 'Tab 2' },
-    { label: 'Tab 3' }
-  ];
-  listener.addEventListener('tab-change', (e) => {
-    console.log('Active tab index:', e.detail);
-  });
-</script>
-
-<!-- Tab content controlled externally -->
-<rel-tab id="contentTabs" activeIndex="0"></rel-tab>
-<div id="tabContent">
-  <div class="panel" data-index="0">Content for Tab 1</div>
-  <div class="panel" data-index="1" style="display:none;">Content for Tab 2</div>
-  <div class="panel" data-index="2" style="display:none;">Content for Tab 3</div>
-</div>
-<script>
-  const contentTabs = document.getElementById('contentTabs');
-  contentTabs.tabs = [
-    { label: 'Tab 1' },
-    { label: 'Tab 2' },
-    { label: 'Tab 3' }
-  ];
-  contentTabs.addEventListener('tab-change', (e) => {
-    document.querySelectorAll('#tabContent .panel').forEach((panel, i) => {
-      panel.style.display = i === e.detail ? 'block' : 'none';
-    });
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `tabs` | `TabItem[]` | `[]` | Array of tab items (see TabItem interface below) |
-| `activeIndex` (reflected) | `number` | `0` | Index of the currently active tab |
-
-### TabItem Interface
-```typescript
-interface TabItem {
-  label: string;       // Display text
-  badge?: number;      // Optional notification count
-  disabled?: boolean;  // Disables interaction
-}
-```
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `tab-change` | `number` (the new active index) | Fired when a different tab is selected |
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Tab panel content (rendered in `.tab-content` wrapper below tabs) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Component-Level Custom Properties
-The component defines CSS custom properties on `:host`:
-
-- `--tab-active-color` - Active tab underline color (default: `--rel-bg-brand`)
-- `--tab-text-default` - Default tab text color (default: `--rel-text-default`)
-- `--tab-text-disabled` - Disabled tab text color (default: `--rel-text-disabled`)
-- `--tab-text-hover` - Hover tab text color (default: `--rel-text-label`)
-- `--tab-underline-height` - Height of active underline (default: `3px`)
-- `--tab-hover-color` - Background color on hover (default: `--rel-bg-neutral-elevated-1`)
-
-### Design Token References
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Font size
-- `--rel-fonts-weight-body-medium` - Font weight
-- `--rel-spacing-sm`, `--rel-spacing-md` - Tab padding
-- `--rel-spacing-2xs` - Gap between label and badge
-- `--rel-border-accent` - Bottom border color (default: `#c4c4c4`)
-- `--rel-border-info` - Focus outline color
-- `--rel-border-radius-xs` - Focus outline border radius
-- `--rel-bg-danger` - Badge background color
-- `--rel-bg-surface` - Badge text color
-
-## Accessibility
-- Uses `role="tablist"` on container and `role="tab"` on each tab
-- Tabs have `aria-selected` and `aria-disabled` attributes
-- Implements roving tabindex (only active tab is focusable via Tab key)
-- Arrow key navigation between tabs
-- Focus visible states with blue outline
-
-### Keyboard Interactions
-- `Tab` - Focus the active tab (or first non-disabled tab)
-- `Arrow Right` - Navigate to next tab (wraps to first, skips disabled)
-- `Arrow Left` - Navigate to previous tab (wraps to last, skips disabled)
-- `Enter / Space` - Activate focused tab
-
-### Focus Behavior
-- Focus outline: 2px blue with -2px offset (inside boundary)
-- Border radius applied to focus outline
-- Focus automatically moves when navigating with arrow keys
-
-## Notes / Edge Cases
-- The **active tab** has a colored underline (3px high by default) at the bottom
-- **Hover effect** (non-active, non-disabled): light gray background
-- **Badges** are circular (16px height, min 16px width) with red background and white text
-- Clicking a disabled tab does nothing (no event dispatched, no index change)
-- Arrow key navigation wraps around (after last tab, goes to first, and vice versa)
-- Arrow key navigation skips disabled tabs
-- When a tab is activated via arrow keys, focus is programmatically moved to that tab
-- The component includes a `.tab-content` wrapper (with 1rem vertical padding) that renders slotted content
-- The `.tab-content` is always visible; consumers must manually show/hide panel content based on `activeIndex`
-- Tabs have a bottom border (1px solid) via `border-bottom` on `.tabs-wrapper`
-- Active tab underline (`position: absolute`, `bottom: 0`) overlays the border
-- Transitions: color (0.2s), background-color (0.2s), transform (0.2s) for smooth interactions
-- The `activeIndex` property is reflected in HTML as an attribute
+# rel-tab
+
+`<rel-tab>` implements the Figma **Tab Item** component (6473:1075) as an underline tab strip with roving-tabindex keyboard navigation, optional count or dot badges and a single shared tabpanel below the strip. Tabs are declared either with slotted `<rel-tab-item>` elements (registered by this folder; they render nothing themselves) or with the `tabs` array property. Use it to switch between peer views of the same content in place; for moving between pages use links or the navbar recipe, and for ordered multi-step flows use `<rel-stepper>`.
+
+## Usage
+
+```html
+<!-- Declarative tabs with badges and a disabled item -->
+<rel-tab id="inbox-tabs" size="medium">
+  <rel-tab-item slot="items" label="Inbox" value="inbox" badge="5"></rel-tab-item>
+  <rel-tab-item slot="items" label="Drafts" value="drafts" badge-dot></rel-tab-item>
+  <rel-tab-item slot="items" label="Archive" value="archive" disabled></rel-tab-item>
+  <div id="inbox-panel">Inbox content.</div>
+</rel-tab>
+
+<script>
+  const tabs = document.getElementById('inbox-tabs');
+  tabs.addEventListener('rel-tab-change', (e) => {
+    const index = e.detail; // number
+    const item = tabs.querySelectorAll('rel-tab-item')[index];
+    document.getElementById('inbox-panel').textContent = `${item.value} content.`;
+  });
+</script>
+
+<!-- Sizes: small (32px), medium (40px), large (48px) -->
+<rel-tab size="small">
+  <rel-tab-item slot="items" label="Overview"></rel-tab-item>
+  <rel-tab-item slot="items" label="Details"></rel-tab-item>
+</rel-tab>
+<rel-tab size="large" activeindex="1">
+  <rel-tab-item slot="items" label="Overview"></rel-tab-item>
+  <rel-tab-item slot="items" label="Details"></rel-tab-item>
+</rel-tab>
+
+<!-- Tabs from the `tabs` property -->
+<rel-tab id="array-tabs"></rel-tab>
+<script>
+  document.getElementById('array-tabs').tabs = [
+    { label: 'Overview' },
+    { label: 'Alerts', badge: 2 },
+    { label: 'Beta', badgeDot: true },
+    { label: 'Coming soon', disabled: true },
+  ];
+</script>
+```
+
+### Deprecated aliases
+
+```html
+<!-- size="sm" / "md" / "lg" → size="small" / "medium" / "large" (still accepted; no console notice is logged) -->
+<rel-tab size="sm">
+  <rel-tab-item slot="items" label="Overview"></rel-tab-item>
+</rel-tab>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-tab.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-tab>` | `RelTab` | `rel-tab.ts` |
+| `<rel-tab-item>` | `RelTabItem` | `rel-tab.ts` |
+
+## API
+
+### `<rel-tab>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `tabs` | `tabs` | `TabItem[]` | `[]` | Tab definitions as `{ label, badge?, badgeDot?, disabled? }` objects — normally set as a property (as an attribute it must be a JSON string). Assign a new array to update; mutating in place does not re-render. Ignored when `<rel-tab-item>` children are slotted into `items`. |
+| `activeIndex` | `activeindex` | `number` | `0` | Zero-based index of the selected tab. Set it to switch tabs programmatically (no event is fired for programmatic changes). Reflected. |
+| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Tab size — styled via :host([size]) rules. Explicit item heights 32 / 40 / 48px (audit 34); `small\|medium\|large` alias `sm\|md\|lg`. Reflected. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-tab-change` | `index` | bubbles / composed | Fired when the user selects a tab by click or keyboard (not on programmatic `activeIndex` changes). Detail: the new active index (number). |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Content of the single tabpanel rendered under the strip (always visible — swap it yourself on `rel-tab-change`) |
+| `items` | `<rel-tab-item>` definitions; when present they take precedence over the `tabs` array |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `list` | The `role="tablist"` row |
+| `item` | Each `role="tab"` element |
+| `label` | The text span inside each tab |
+
+### Tokens / CSS Variables
+
+#### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-tab-active-color` | `var(--tab-active-color)` | Underline colour of the active tab; default `var(--rel-bg-brand)` |
+| `--rel-tab-hover-color` | `var(--tab-hover-color)` | Background of an inactive tab on hover; default `var(--rel-bg-neutral-elevated-1)` |
+| `--rel-tab-text-default` | `var(--tab-text-default)` | Label colour of the active tab; default `var(--rel-text-default)` |
+| `--rel-tab-text-disabled` | `var(--tab-text-disabled)` | Label colour of a disabled tab; default `var(--rel-text-disabled)` |
+| `--rel-tab-text-hover` | `var(--tab-text-hover)` | Label colour while hovering an enabled tab; default `var(--rel-text-label)` |
+| `--rel-tab-underline-height` | `var(--tab-underline-height)` | Thickness of the active underline; default 3px |
+
+### `<rel-tab-item>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Text shown on the tab. |
+| `value` | `value` | `string` | `""` | Optional identifier for the tab. `<rel-tab>` does not read it; look it up from the item at `event.detail` when handling `rel-tab-change`. |
+| `badge` | `badge` | `number` | `0` | Count shown in a small badge after the label; `0` hides the badge. |
+| `badgeDot` | `badge-dot` | `boolean` | `false` | Shows a small dot instead of a numbered badge — takes precedence over `badge`. |
+| `disabled` | `disabled` | `boolean` | `false` | Greys the tab out and skips it in click, arrow-key and Home/End navigation. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The strip is `role="tablist"`; every tab is `role="tab"` with `aria-selected`, `aria-disabled` and `aria-controls` pointing at the shared `role="tabpanel"`, which in turn is `aria-labelledby` the active tab and is focusable (`tabindex="0"`).
+- Roving tabindex: only the active tab is in the Tab order (`tabindex="0"`); other and disabled tabs are `tabindex="-1"`.
+- Arrow keys use automatic activation — moving focus also selects the tab and fires `rel-tab-change`.
+- Focus is shown as a 2px outline inset inside the tab.
+- Disabled tabs ignore clicks and keys and are skipped by arrow, Home and End navigation.
+
+| Key | Action |
+| --- | --- |
+| `ArrowRight` | Selects and focuses the next enabled tab (wraps to the first). |
+| `ArrowLeft` | Selects and focuses the previous enabled tab (wraps to the last). |
+| `Home` | Selects and focuses the first enabled tab. |
+| `End` | Selects and focuses the last enabled tab. |
+| `Enter` / `Space` | Selects the focused tab (no-op when disabled). |
+| `Tab` | Leaves the strip (moves to the tabpanel). |
+
+## Notes / Edge Cases
+
+- There is one always-visible tabpanel (the default slot). The component does not show/hide content per tab — swap or filter the panel content yourself on `rel-tab-change` or by watching `activeIndex`.
+- `rel-tab-change` fires for user selection only; setting `activeIndex` programmatically updates the strip silently.
+- Slotted `<rel-tab-item>` elements take precedence over the `tabs` array. Their `value` is not read by `<rel-tab>` — look it up from the item at `event.detail` when you need an identifier. The `items` slot itself is hidden.
+- `badge-dot` wins over `badge`; a `badge` of `0` renders no badge. Badges use the danger tone on enabled tabs and a neutral inverse tone on disabled tabs.
+- `size` accepts `small` / `medium` / `large` (item heights 32 / 40 / 48px with body-sm / md / lg type); the short forms `sm` / `md` / `lg` are aliases (see Deprecated aliases).
+- Legacy hook aliases still honoured: `--tab-active-color`, `--tab-underline-height`, `--tab-text-default`, `--tab-text-hover`, `--tab-text-disabled` and `--tab-hover-color` are read as fallbacks of the `--rel-tab-*` hooks.