@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/tabs.md

@@ -0,0 +1,211 @@
+<!-- index: ./index.md -->
+# tabs
+
+`data-ui="tabs"` · Switches between panels of related content.
+
+## Import
+
+```ts
+import {
+  provideTabsDefaults,
+  SlTab,
+  SlTabActions,
+  SlTabEnd,
+  SlTabList,
+  SlTabPanel,
+  SlTabPanelContent,
+  SlTabs,
+  SlTabStart,
+} from '@slotted/angular/tabs';
+```
+
+Selector: `[slTabs], [slTabList], [slTab], [slTabStart], [slTabEnd], [slTabPanel], ng-template[slTabPanelContent], [slTabActions]` · exportAs: `slTabs, slTabList, slTab, slTabStart, slTabEnd, slTabPanel, slTabActions`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  SlDescriptionList,
+  SlDescriptionListDescription,
+  SlDescriptionListItem,
+  SlDescriptionListTerm,
+} from '@slotted/angular/description-list';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTab, SlTabList, SlTabPanel, SlTabs } from '@slotted/angular/tabs';
+import { SlText } from '@slotted/angular/typography';
+
+const SECTIONS = [
+  {
+    value: 'summary',
+    label: 'Summary',
+    pairs: [
+      ['Customer', 'Harbor & Pine'],
+      ['Placed', 'September 8, 2026'],
+      ['Payment terms', 'Net 30'],
+      ['Total', '$1,240.00'],
+    ],
+  },
+  {
+    value: 'items',
+    label: 'Items',
+    pairs: [
+      ['Oak shelf, 90 cm', '4 × $180.00'],
+      ['Wall bracket, steel', '8 × $24.00'],
+      ['Assembly kit', '1 × $328.00'],
+    ],
+  },
+  {
+    value: 'shipments',
+    label: 'Shipments',
+    pairs: [
+      ['Carrier', 'Atlas Freight'],
+      ['Tracking', 'AF-2210-4471'],
+      ['Expected', 'September 12, 2026'],
+    ],
+  },
+];
+
+const ACTIVITY = [
+  'Sep 9, 14:02 — Picked at Reno, NV',
+  'Sep 8, 16:45 — Payment approved',
+  'Sep 8, 16:41 — Order placed by Dana Whitfield',
+];
+
+@Component({
+  selector: 'app-tabs-basic',
+  imports: [
+    SlDescriptionList,
+    SlDescriptionListDescription,
+    SlDescriptionListItem,
+    SlDescriptionListTerm,
+    SlStack,
+    SlTab,
+    SlTabList,
+    SlTabPanel,
+    SlTabs,
+    SlText,
+  ],
+  template: `
+    <div slTabs defaultValue="summary">
+      <div slTabList aria-label="Order SO-1187">
+        @for (section of sections; track section.value) {
+          <div slTab [value]="section.value">{{ section.label }}</div>
+        }
+        <div slTab value="activity">Activity</div>
+      </div>
+      @for (section of sections; track section.value) {
+        <div slTabPanel [value]="section.value">
+          <div slDescriptionList>
+            @for (pair of section.pairs; track pair[0]) {
+              <div slDescriptionListItem>
+                <dt slDescriptionListTerm>{{ pair[0] }}</dt>
+                <dd slDescriptionListDescription>{{ pair[1] }}</dd>
+              </div>
+            }
+          </div>
+        </div>
+      }
+      <div slTabPanel value="activity">
+        <div slStack [gap]="2">
+          @for (entry of activity; track entry) {
+            <span slText size="sm">{{ entry }}</span>
+          }
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class TabsBasic {
+  protected readonly sections = SECTIONS;
+  protected readonly activity = ACTIVITY;
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slTabs | yes |
+| `list` | the element carrying slTabList, with role="tablist" | yes |
+| `item` | the slTab host, with role="presentation" | yes |
+| `tab` | button[role="tab"], or a[role="tab"] with href | yes |
+| `start` | the element carrying slTabStart | no |
+| `label` | span | yes |
+| `end` | the element carrying slTabEnd | no |
+| `dismiss` | button | no |
+| `panel` | the element carrying slTabPanel, with role="tabpanel" | yes |
+| `scroll` | button | no |
+| `actions` | the element carrying slTabActions | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | slTabs | The value of the selected tab. Passing it makes the selection controlled for the life of the component; without it, slTabs keeps the selection and starts from defaultValue. |
+| `defaultValue` | `string` | — | slTabs | The value an uncontrolled slTabs starts from, read once. When it is unset, no tab is selected and no panel is shown. |
+| `activation` | `'automatic' \| 'manual'` | automatic | slTabs, provideTabsDefaults | Whether moving focus to a tab also selects it. The APG recommends automatic when panels show without a noticeable delay, and manual when a panel has to be fetched. |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slTabs, provideTabsDefaults | Which way the list runs, and so which arrow keys move between tabs. A horizontal list ignores Up and Down, so those keys keep scrolling the page. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slTabs, provideTabsDefaults | The control step of the list: height, type, padding and inner gap, all from the control scales the theme restates per density. |
+| `variant` | `'line' \| 'contained'` | line | slTabs, provideTabsDefaults | How the list is drawn. Both variants paint the accent marker, which keeps the selected tab visible in the high-contrast scheme, where every surface is flattened. |
+| `track` | `'line' \| 'none'` | line | slTabs, provideTabsDefaults | Whether the list draws the line its tabs stand on. none is for a list placed on a line the page already draws, such as a card header’s edge or a table’s rule, where two hairlines a pixel apart read as one smudge. The marker then sits on the item’s own edge, on the line that is there. |
+| `fit` | `'auto' \| 'equal'` | auto | slTabs, provideTabsDefaults | Whether each tab is as wide as its label or takes an equal share of the line. equal cuts a label longer than its share with an ellipsis; auto never cuts a label and scrolls the list instead. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | slTabs, provideTabsDefaults | When a panel’s content exists: only while its tab is selected (active), from its first selection on (lazy), or from the start (eager). A panel that is not selected carries the hidden attribute. Angular creates projected content with the page; write a panel’s content in <ng-template slTabPanelContent> for mount to decide when it is created. |
+| `loop` | `boolean` | true | slTabs, provideTabsDefaults | Whether the arrow keys wrap past the ends of the list. |
+| `disabled` | `boolean` | false | slTabs | Disables every tab with the native attribute, which also makes the arrow keys skip them, and dims the track. |
+| `value, on slTab` | `string` | — | slTab | What this tab selects, and what the value of slTabs holds. It reaches the DOM as data-value, which the keyboard reads. |
+| `disabled, on slTab` | `boolean` | from slTabs, or false | slTab | Disables this tab only, so one tab can be unavailable in a working list. Unset rather than false, so the tab follows slTabs. |
+| `dismissible` | `boolean` | false | slTab | Draws the close button and binds Delete on the tab, announced through aria-keyshortcuts. |
+| `dismissLabel` | `string` | — | slTab | The accessible name of the close button, required whenever it is drawn. Name what closes: “Close customers.sql” rather than “Close”. |
+| `slTabStart` | `directive` | — | an element inside slTab | Marks the content before the label, such as an icon, and places it in the start part beside the words. |
+| `slTabEnd` | `directive` | — | an element inside slTab | Marks the content after the label, such as a badge with a count, and places it in the end part beside the words. |
+| `controls` | `string` | — | slTab | The id of the region this tab controls when it is not a slTabPanel, such as a table the selected value filters. aria-controls names that region. |
+| `href` | `string` | — | slTab | Renders the tab as a link. A plain click selects the tab without navigating; a click with a modifier key is left to the browser, which opens the address in a new browser tab or window. |
+| `value, on slTabPanel` | `string` | — | slTabPanel | The tab this panel belongs to. slTabs wires the pair with ids generated from the value. |
+| `exportAs` | `slTabs \| slTabList \| slTab \| slTabPanel \| slTabActions \| slTabStart \| slTabEnd` | — | every directive | A template reaches an instance by name: #tabs="slTabs" gives a page select(value, reason), the resolved axes and the ids, for a view a router changes. |
+| `the element you write it on` | `any element` | — | every directive | The five roots are directives on your own elements, so a list can be a nav and slTabs a section. The tab control itself cannot be replaced: it holds the role, the value and the keyboard, and href covers the substitution that matters. |
+| `ng-content` | `projected content` | — | slTab, slTabPanel, slTabActions | The label, the panel content and the actions are your own markup. Under mount="active", a closed panel keeps its projected content out of the DOM, but Angular creates projected components with the page. |
+| `slTabPanelContent` | `ng-template directive` | — | a direct child of slTabPanel | Holds a panel’s content as a template that mount instantiates: on selection and destroyed after under active, on first selection and kept under lazy, up front under eager. |
+| `provideTabsDefaults()` | `{ activation, orientation, size, variant, track, fit, mount, loop }` | — | an injector | The eight settings an application decides once, in the bootstrap providers, on a route or on a component. A value set on one slTabs still wins. |
+| `aria-label, on slTabList` | `string` | — | slTabList | The name of the set of views. slTabs writes no name of its own; aria-labelledby works the same way. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<string \| undefined>` | Before the selection moves. The request carries the new value, the previous value (undefined while no tab is selected), the reason (pointer, keyboard, remove or programmatic), the originating event, and cancel(), which keeps the current tab. |
+| `tabDismiss` | `TabsDismissRequest, which also carries the value being closed` | Before a tab is closed, by Delete or by its close button. The request carries the reason (pointer or keyboard) and cancel(), which stops both the dismissal and the selection move that would follow it. Tabs removes nothing itself: remove the tab from your own data. |
+| `click, keydown, focus, on each slTab` | `the element’s own events` | When the tab’s control fires them. A listener bound on the slTab host runs after the tab’s own handler. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `activation` | `automatic`, `manual` | `automatic` |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `line`, `contained` | `line` |
+| `track` | `line`, `none` | `line` |
+| `fit` | `auto`, `equal` | `auto` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+
+## Rules
+
+- Tabs implements the WAI-ARIA APG Tabs pattern (w3.org/WAI/ARIA/apg/patterns/tabs/) and its whole keyboard table: Tab enters the list on the selected tab and leaves to the panel, the arrow keys of the list’s direction move focus and wrap at both ends, Home and End reach the first and last enabled tab, Enter and Space select under manual activation, and Delete closes a dismissible tab. A horizontal list does not listen for Up and Down, so those keys keep scrolling the page while focus is in the list.
+- After a dismissal, focus follows the pattern: the next tab, the previous one when the closed tab was last, or the list itself when no tab is left, which is why the list carries tabindex="-1". The selection follows the same rule, with the reason remove.
+- The close button is outside the arrow-key sequence and inside the accessibility tree. A screen reader reaches and presses it; from the keyboard, Delete closes the focused tab, and the tab announces the key with aria-keyshortcuts. In the arrow-key sequence, close buttons would double the presses it takes to cross the list.
+- The paging controls are aria-hidden and outside the Tab sequence, because the arrow keys reach every tab and scroll it into view. Cloudscape’s guidance warns against extra Tab stops between a tab list and its panel.
+- A list that starts to overflow scrolls the selected tab into view once its paging controls are drawn, so the selected tab is not left behind the end control.
+- Each tab names its panel with aria-controls and each panel names its tab with aria-labelledby. The ids come from the value, with the characters an id cannot hold escaped rather than replaced, so two values that differ only by a space never share a panel.
+- The selected tab is never shown by colour alone: the marker is a bar the width of a thick border, which stays visible in the high-contrast scheme, where the theme paints every surface Canvas and the fill of the contained variant disappears.
+- A panel carries tabindex="0", so the Tab key reaches it from the list. The pattern permits that stop even when the panel’s first content is focusable.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-font-weight`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-letter-spacing`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-tabs-actions-gap`, `--slotted-tabs-active-background`, `--slotted-tabs-active-marker-color`, `--slotted-tabs-color`, `--slotted-tabs-contained-background`, `--slotted-tabs-contained-selected-background`, `--slotted-tabs-dismiss-active-background`, `--slotted-tabs-dismiss-active-color`, `--slotted-tabs-dismiss-color`, `--slotted-tabs-dismiss-hover-background`, `--slotted-tabs-dismiss-hover-color`, `--slotted-tabs-fade-size`, `--slotted-tabs-gap`, `--slotted-tabs-hover-background`, `--slotted-tabs-hover-color`, `--slotted-tabs-hover-marker-color`, `--slotted-tabs-list-gap`, `--slotted-tabs-marker-color`, `--slotted-tabs-scroll-color`, `--slotted-tabs-selected-color`, `--slotted-tabs-track-color`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [tabs.examples.md](./tabs.examples.md).