@oddkin/components 0.0.0-stage → 1.0.0-beta.1

package/agent/references/components/odd-split-button.md

@@ -0,0 +1,92 @@
+# `<odd-split-button>` (OddkinSplitButton)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Actions. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+A primary action with a menu of related actions beside it: two independent targets in one
+element, a primary button and a menu button (odd-menu, whose parts it forwards). Menu items come from `<option value>`
+(the value is the item's `id`), `<optgroup label>`, and `<hr>` children, or from `items`; other
+children are the primary button's content.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/split-button';`
+- Class: `import { OddkinSplitButton } from '@oddkin/components/split-button';`
+- Dependency (menu): `<odd-menu>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | string | '' | Reported as the `odd-action` detail `id` when the primary half is pressed. |
+| `items` | none: assign as a property | readonly MenuItemRecord[] \| undefined | undefined | The menu's entries; when set, `<option>`, `<optgroup>`, and `<hr>` children are ignored. |
+| `appearance` | `appearance` (reflects) | "primary" \| "secondary" \| "ghost" | 'secondary' | Visual emphasis of both halves, as on odd-button. |
+| `size` | `size` (reflects) | "sm" \| "md" \| "lg" | 'md' | Size of both halves, as on odd-button. |
+| `disabled` | `disabled` (reflects) | boolean | false | Disables both halves. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a busy indicator in the primary half, which then ignores presses. |
+| `strings` | none: assign as a property | Partial<{ more: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `odd-action` | CustomEvent<NavigationActionDetail> | user (authored) | The primary half reports `{ id: value, action: "primary" }`; a menu item reports `{ id, action: "select" }`, and cancelling that keeps the menu open. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The primary button's content. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `group` | Each group's heading. |
+| `item` | Each menu item. |
+| `menu` | Every menu surface: the menu and its submenus. |
+| `primary` | The primary button. |
+| `separator` | Each separator. |
+| `spinner` | The loading indicator in the primary button. |
+| `submenu` | Each submenu surface. |
+| `trigger` | The button that opens the menu. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A frequent action with a few alternatives: "Save" with "Save as" and "Save a copy", "Merge" with merge strategies. (src/split-button/split-button.ts:45)
+- Not for: Unrelated actions (use separate buttons or odd-toolbar); only a list of actions (use odd-menu). (src/split-button/split-button.ts:46)
+- Accessibility: Two buttons in the Tab order: the primary action, named by its content, and the menu button, named by `strings.more` (with `aria-haspopup="menu"` and `aria-expanded`). `loading` keeps the primary button focusable and sets `aria-disabled`; announce progress separately if it matters. (src/split-button/split-button.ts:42)
+- Keyboard: Tab moves between the two buttons. The menu button follows odd-menu: Enter, Space, and Down open the menu on its first item, Up on its last. (src/split-button/split-button.ts:43)
+
+## Examples
+
+- `example:odd-split-button/default` in src/split-button/split-button.examples.ts (package source), preview roles role:splitAction
+- `example:odd-split-button/disabled` in src/split-button/split-button.examples.ts (package source)
+- `example:odd-split-button/fromData` in src/split-button/split-button.examples.ts (package source)
+- `example:odd-split-button/loading` in src/split-button/split-button.examples.ts (package source)
+- `example:odd-split-button/secondary` in src/split-button/split-button.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-split-button/itemsAttribute` produces `usage.attribute.propertyOnly`; correct: `example:odd-split-button/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-split-panel.md

@@ -0,0 +1,89 @@
+# `<odd-split-panel>` (OddkinSplitPanel)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Layout. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Two panes side by side or stacked, with a separator the user drags or moves with the keyboard
+(APG window splitter). Nest split panels for more panes.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/split-panel';`
+- Class: `import { OddkinSplitPanel } from '@oddkin/components/split-panel';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `orientation` (reflects) | "vertical" \| "horizontal" | 'horizontal' | Panes side by side (horizontal) or stacked (vertical). |
+| `position` | `position` | number | 50 | Size of the start pane, in percent of the element, between `min` and `max`. |
+| `min` | `min` | number | 0 | Smallest `position`, in percent. |
+| `max` | `max` | number | 100 | Largest `position`, in percent. |
+| `collapsed` | `collapsed` (reflects) | boolean | false | Hides the start pane; Enter on the separator toggles it, keeping `position`. |
+| `label` | `label` | string | '' | Names the separator. |
+| `strings` | none: assign as a property | Partial<{ label: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | While dragging and after each key: `position` (or `collapsed`) has changed. |
+| `change` | CustomEvent | user (authored) | When a drag ends with a new position, and after each key that changed it. |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| `end` | The second pane; it takes the rest. |
+| `start` | The first pane (inline start, or top when stacked); the separator sets its size. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The grid of both panes and the separator. |
+| `end` | The wrapper of the end pane. |
+| `separator` | The separator. |
+| `start` | The wrapper of the start pane (hidden while collapsed). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-split-panel-separator-size` | Thickness of the separator. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Two regions the user resizes, such as a file list beside an editor or a preview under code. (src/split-panel/split-panel.ts:39)
+- Not for: A fixed page layout (use the layout recipes); hiding content without resizing (use odd-disclosure). (src/split-panel/split-panel.ts:40)
+- Accessibility: The separator is a focusable `separator` named by `label` (default `strings.label`, "Resize") with `aria-valuenow` (the start pane's size in percent, 0 while collapsed), `aria-valuemin`, `aria-valuemax`, and `aria-controls` naming the start pane. A collapsed start pane is hidden, so its content leaves the Tab order and the accessibility tree. Name each pane's content (for example with headings) so the separator's purpose is clear. (src/split-panel/split-panel.ts:36)
+- Keyboard: Tab reaches the separator. Left and Right move it by 1% (Up and Down when stacked; mirrored right to left); Home and End go to `min` and `max`; Enter collapses the start pane or restores it. (src/split-panel/split-panel.ts:37)
+- Limitations: Stacked panes need a height on the element; side-by-side panes take their content's height. (src/split-panel/split-panel.ts:41)
+
+## Examples
+
+- `example:odd-split-panel/collapsed` in src/split-panel/split-panel.examples.ts (package source)
+- `example:odd-split-panel/default` in src/split-panel/split-panel.examples.ts (package source), preview roles role:splitPanel
+- `example:odd-split-panel/stacked` in src/split-panel/split-panel.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-split-panel/orientationColumn` produces `usage.attribute.value`; correct: `example:odd-split-panel/stacked`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-split-panel-separator-size`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-stat.md

@@ -0,0 +1,84 @@
+# `<odd-stat>` (OddkinStat)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Display. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+One metric: its `label`, its `value`, and the context in the default slot ("+8.2% this month").
+`trend` adds an arrow for the direction of change, without saying whether it is good: the
+signed value in the context says it in words. While `loading` a placeholder stands in for the
+value; an empty `value` says "Data not available".
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/stat';`
+- Class: `import { OddkinStat } from '@oddkin/components/stat';`
+- Dependency (skeleton): `<odd-skeleton>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | What the value measures. |
+| `value` | `value` | string | '' | The value, formatted: "1,284", "$4.2M", "98.6%". |
+| `trend` | `trend` (reflects) | "none" \| "increase" \| "decrease" | 'none' | An arrow for the direction of change, with no colour for good or bad. |
+| `loading` | `loading` (reflects) | boolean | false | Shows a placeholder for the value. |
+| `strings` | none: assign as a property | Partial<{ loading: string; unavailable: string; }> \| undefined | undefined | Localized string overrides. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The context: the signed change and its period, or a comparison ("Across 12 teams"). |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The stat's surface. |
+| `context` | The trend arrow and the context. |
+| `label` | The label. |
+| `placeholder` | The loading placeholder (an `odd-skeleton`). |
+| `value` | The value ("—" when there is none). |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: A key figure on a dashboard or summary: a count, a total, a rate, with its change. (src/stat/stat.ts:21)
+- Not for: Progress toward a goal (use a progress bar); several figures compared side by side (use a table or chart). (src/stat/stat.ts:22)
+- Accessibility: Read in order: label, value, context. Put the sign and the period in the context ("+8.2% this month"): the arrow is decorative. While `loading` the element is busy (`aria-busy`) and says `strings.loading`; without a value it says `strings.unavailable` and the dash is hidden. (src/stat/stat.ts:19)
+
+## Examples
+
+- `example:odd-stat/decrease` in src/stat/stat.examples.ts (package source)
+- `example:odd-stat/default` in src/stat/stat.examples.ts (package source), preview roles role:stat
+- `example:odd-stat/loading` in src/stat/stat.examples.ts (package source)
+- `example:odd-stat/neutral` in src/stat/stat.examples.ts (package source)
+- `example:odd-stat/unavailable` in src/stat/stat.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-stat/trendUp` produces `usage.attribute.value`; correct: `example:odd-stat/default`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-status-marker.md

@@ -0,0 +1,78 @@
+# `<odd-status-marker>` (OddkinStatusMarker)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Display. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+The status marker of a timeline event or a step (Figma's Event marker and Step status): a circle
+with the built-in glyph for `status`, or its own content (a step number) while idle. Decorative:
+hidden from assistive technology, so the list and the words beside it carry the meaning. The
+`.odd-timeline` and `.odd-stepper` recipes size and colour it; alone it has its own look.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/status-marker';`
+- Class: `import { OddkinStatusMarker } from '@oddkin/components/status-marker';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `status` | `status` (reflects) | "idle" \| "pending" \| "complete" \| "failed" | 'idle' | Idle: the content or a dot. Pending: a busy ring. Complete: a check. Failed: a warning glyph. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | Content while idle: a step number. Empty: a dot. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The circle. |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-status-marker-size` | The circle's size (default `control.height.sm`). |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Timeline events and steps, inside the `.odd-timeline` and `.odd-stepper` recipes. (src/status-marker/status-marker.ts:14)
+- Not for: Status on its own (use a badge, which carries words); a progress value (use a progress bar). (src/status-marker/status-marker.ts:15)
+- Accessibility: Hidden from assistive technology: say the status in words beside it ("Complete", "Needs attention"). (src/status-marker/status-marker.ts:12)
+
+## Examples
+
+- `example:odd-status-marker/default` in src/status-marker/status-marker.examples.ts (package source), preview roles role:statusMarker
+- `example:odd-status-marker/failed` in src/status-marker/status-marker.examples.ts (package source)
+- `example:odd-status-marker/past` in src/status-marker/status-marker.examples.ts (package source)
+- `example:odd-status-marker/pending` in src/status-marker/status-marker.examples.ts (package source)
+- `example:odd-status-marker/step` in src/status-marker/status-marker.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-status-marker/statusError` produces `usage.attribute.value`; correct: `example:odd-status-marker/failed`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-status-marker-size`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-switch.md

@@ -0,0 +1,110 @@
+# `<odd-switch>` (OddkinSwitch)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Forms. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+An on/off setting that participates in forms like a checkbox: a native checkbox with
+`role="switch"` in the shadow root, drawn as a track and thumb, labelled by the slotted text.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/switch';`
+- Class: `import { OddkinSwitch } from '@oddkin/components/switch';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `name` (reflects) | string \| undefined | undefined | Name submitted with the form. Reflected: a form-associated element submits under its name attribute. |
+| `disabled` | `disabled` (reflects) | boolean | false | Prevents interaction and submission. |
+| `description` | `description` | string | '' | Help text below the label. |
+| `error` | `error` | string | '' | Error message; marks the field invalid (custom validity) while set. |
+| `defaultChecked` | `checked` | boolean | false | Initial checkedness; the `checked` attribute, as on native checkboxes. |
+| `value` | `value` | string | 'on' | Submitted with the form while checked. |
+| `required` | `required` (reflects) | boolean | false | Must be checked to submit. |
+| `strings` | none: assign as a property | Partial<{ on: string; off: string; }> \| undefined | undefined | Localized string overrides. |
+| `form` | none (read-only) | HTMLFormElement \| null |  | The form this field belongs to, if any. |
+| `validity` | none (read-only) | ValidityState |  | The field's validity, as on a native form control. |
+| `validationMessage` | none (read-only) | string |  | The message the browser would show for the field's invalid state, or empty. |
+| `willValidate` | none (read-only) | boolean |  | Whether the field takes part in constraint validation (false while disabled or read-only). |
+| `checked` | none: assign as a property | boolean |  | The current checkedness. Setting it (or toggling) detaches it from `defaultChecked`. |
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `checkValidity()` | Whether the field is valid; when not, fires `invalid` at it, as on native controls. |
+| `reportValidity()` | As `checkValidity()`, and an invalid field also shows its error to the user. |
+| `setCustomValidity()` | As on native controls; the message is also shown, since it sets `error`. An empty string clears it. |
+| `formResetCallback()` | Native callback: the owning form was reset. |
+| `formStateRestoreCallback()` | Native callback: restore after navigation or autofill restore. |
+| `formDisabledCallback()` | Native callback: an ancestor fieldset's disabled state changed. |
+| `formAssociatedCallback()` | Native callback: the form owner changed (moved, `form` attribute, or the named form). |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | Native `input` events cross the shadow boundary once; declared here for metadata and sync. |
+| `change` | CustomEvent | user (authored) | Re-dispatched at the host when the user toggles (native `change` is not composed). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The label; names the switch. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `control` | The native checkbox with `role="switch"` (the drawn track). |
+| `description` | Help text, referenced by `aria-describedby`. |
+| `error` | The error message, referenced by `aria-describedby`. |
+| `field` | Wrapper of the switch row, description, and error. |
+| `label` | The label text beside the track. |
+| `state` | The visible on/off text (`strings.on`, `strings.off`), hidden from assistive technology. |
+| `thumb` | The thumb inside the track. |
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+| Name | Description |
+| --- | --- |
+| `user-invalid` |  |
+
+## Guidance (authored)
+
+- Use for: A setting that takes effect at once, such as turning notifications on or off. (src/switch/switch.ts:25)
+- Not for: A choice confirmed with a submit button (use odd-checkbox); one choice among several (use odd-radio-group). (src/switch/switch.ts:26)
+- Accessibility: The slotted text names the switch through its `<label>`; the role announces on and off, so the visible state text is hidden from assistive technology. Description and error are announced through `aria-describedby`. (src/switch/switch.ts:22)
+- Keyboard: Space toggles; Tab order as a native checkbox. (src/switch/switch.ts:23)
+- Limitations: Validation bubbles anchor to the inner checkbox. (src/switch/switch.ts:27)
+
+## Examples
+
+- `example:odd-switch/checked` in src/switch/switch.examples.ts (package source)
+- `example:odd-switch/default` in src/switch/switch.examples.ts (package source), preview roles role:switch
+- `example:odd-switch/description` in src/switch/switch.examples.ts (package source)
+- `example:odd-switch/disabled` in src/switch/switch.examples.ts (package source)
+- `example:odd-switch/strings` in src/switch/switch.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-switch/onAttribute` produces `usage.attribute.unknown`; correct: `example:odd-switch/checked`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-tab-panel.md

@@ -0,0 +1,66 @@
+# `<odd-tab-panel>` (OddkinTabPanel)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Navigation. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+One panel of `odd-tabs`: its tab's text, its value, and the content shown while its tab is
+selected. `odd-tabs` assigns it to a tab panel inside its own shadow root, so the tab and the
+panel reference each other while the content stays in the light DOM.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/tab-panel';`
+- Class: `import { OddkinTabPanel } from '@oddkin/components/tab-panel';`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | The text of its tab. |
+| `value` | `value` | string | '' | Identifies the panel in `odd-tabs` `value`; without it, its position ("0", "1", …). |
+| `disabled` | `disabled` (reflects) | boolean | false | Its tab cannot be selected. |
+
+## Events
+
+None.
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | The panel content. |
+
+## Parts
+
+None.
+
+## CSS custom properties
+
+None.
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: The content of one tab of odd-tabs. (src/tab-panel/tab-panel.ts:12)
+- Not for: Content outside odd-tabs (use a section with a heading). (src/tab-panel/tab-panel.ts:13)
+- Accessibility: The surrounding `odd-tabs` gives the panel `role="tabpanel"`, names it by its tab, and hides it while another tab is selected; on its own it has no role. (src/tab-panel/tab-panel.ts:10)
+
+## Examples
+
+- `example:odd-tab-panel/default` in src/tab-panel/tab-panel.examples.ts (package source), preview roles role:tabPanel
+
+## Customization
+
+- Levels: 2, 3 (authored)
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`

package/agent/references/components/odd-tabs.md

@@ -0,0 +1,89 @@
+# `<odd-tabs>` (OddkinTabs)
+
+Package `@oddkin/components` 1.0.0-beta.1 · category Navigation. Generated from `custom-elements.json` and `oddkin.metadata.json`; facts are extracted unless marked authored or verified.
+
+Tabs that switch between related panels (APG tabs). Panels are `odd-tab-panel` children; the
+element draws a tab for each and assigns each panel to a tab panel inside its own shadow root
+(manual slot assignment), so each tab and its panel reference each other while the content
+stays in the light DOM.
+
+## Import and register
+
+- Register: `import '@oddkin/components/define/tabs';`
+- Class: `import { OddkinTabs } from '@oddkin/components/tabs';`
+- Dependency (panel): `<odd-tab-panel>`
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | string | '' | Names the tab list. |
+| `value` | `value` | string | '' | The selected panel's `value` (its position when it has none). Without a match, the first enabled panel shows. |
+| `orientation` | `orientation` (reflects) | "vertical" \| "horizontal" | 'horizontal' | Tabs in a row above the panel, or in a column beside it. |
+| `activation` | `activation` | "automatic" \| "manual" | 'automatic' | Select a tab when it receives focus, or only with Enter or Space (APG). |
+
+## Events
+
+| Event | Type | Intent | Description |
+| --- | --- | --- | --- |
+| `input` | CustomEvent | user (authored) | The user selected another tab. |
+| `change` | CustomEvent | user (authored) | The user selected another tab (the selection is committed at once). |
+
+## Slots
+
+| Name | Description |
+| --- | --- |
+| (default) | `odd-tab-panel` children; other children are not shown. |
+
+## Parts
+
+| Name | Description |
+| --- | --- |
+| `base` | The surface. |
+| `list` | The tab list. |
+| `panel` | Each tab panel, around its `odd-tab-panel`. |
+| `tab` | Each tab (a button). |
+
+## CSS custom properties
+
+| Name | Description |
+| --- | --- |
+| `--odd-tabs-background` | Background of the surface. |
+| `--odd-tabs-radius` | Corner radius of the surface. |
+
+## Custom states
+
+None.
+
+## Guidance (authored)
+
+- Use for: Switching between related views of the same subject in place. (src/tabs/tabs.ts:42)
+- Not for: Page navigation (use links or odd-side-nav); a choice of value in a form (use a radio group or segmented control); steps of a process. (src/tabs/tabs.ts:43)
+- Accessibility: A `tablist` named by `label`, with `tab` buttons (`aria-selected`, `aria-controls`) and `tabpanel` regions named by their tab. The panel shown is focusable, so its content is reachable even without focusable content. (src/tabs/tabs.ts:39)
+- Keyboard: Tab reaches the selected tab, then the panel. Arrow keys move between tabs (Left and Right, or Up and Down when vertical; mirrored right to left), Home and End go to the first and last; disabled tabs are skipped. With `activation="automatic"` a focused tab is selected; with `manual`, Enter or Space selects it. (src/tabs/tabs.ts:40)
+
+## Examples
+
+- `example:odd-tabs/default` in src/tabs/tabs.examples.ts (package source), preview roles role:tabs
+- `example:odd-tabs/disabledTab` in src/tabs/tabs.examples.ts (package source)
+- `example:odd-tabs/manual` in src/tabs/tabs.examples.ts (package source)
+- `example:odd-tabs/vertical` in src/tabs/tabs.examples.ts (package source)
+
+Explained mistakes (never use these as patterns):
+
+- `example:odd-tabs/orientationColumn` produces `usage.attribute.value`; correct: `example:odd-tabs/vertical`
+
+## Customization
+
+- Levels: 1, 2, 3 (authored)
+- Variables: `--odd-tabs-background`, `--odd-tabs-radius`
+
+## Contracts
+
+- `contract:core/binding-rule`
+- `contract:core/properties`
+- `contract:core/events`
+- `contract:core/lifecycle`
+- `contract:core/update-complete`
+- `contract:core/scope`
+- `contract:core/composition`