@ixfx/components 0.6.2 → 0.7.1

package/docs-user/split-layout.md

@@ -1,6 +1,6 @@
-# Split Layout
+# N-Way Split Layout
 
-A Lit web component that lays out two elements within a container with a split bar to adjust their proportions.
+A Lit web component that lays out any number of panels along one axis with draggable gutters between them.
 
 ---
 
@@ -10,245 +10,211 @@ A Lit web component that lays out two elements within a container with a split b
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `layout` | `vertical` \| `horizontal` | `vertical` | Split orientation. `vertical` creates left/right panels, `horizontal` creates top/bottom panels. |
-| `sizeA` | `String` | `""` | CSS size for panel A (slot `a`). Can use relative (`50%`) or absolute (`100px`) values. Empty string defaults to `auto`. |
-| `sizeB` | `String` | `""` | CSS size for panel B (slot `b`). Same format as `sizeA`. |
-| `fixedA` | `Boolean` | `false` | If `true`, `sizeA` is calculated in pixels rather than percentage of whole. |
-| `fixedB` | `Boolean` | `false` | If `true`, `sizeB` is calculated in pixels rather than percentage of whole. |
-| `collapsible` | `Boolean` | `false` | If `true`, panels can be collapsed by dragging the handle to the edge. The other panel expands to fill the space. |
-| `minSizeA` | `String` | `""` | Minimum size for panel A (e.g., `"100px"` or `"20%"`). Empty means no minimum. |
-| `maxSizeA` | `String` | `""` | Maximum size for panel A. Empty means no maximum. |
-| `minSizeB` | `String` | `""` | Minimum size for panel B. |
-| `maxSizeB` | `String` | `""` | Maximum size for panel B. |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `collapsedA` | `Boolean` (reflects attribute) | `true` if panel A is currently collapsed. |
-| `collapsedB` | `Boolean` (reflects attribute) | `true` if panel B is currently collapsed. |
-
-### CSS Variables
+| `direction` | `row` \| `column` | `row` | Split direction. `row` creates side-by-side panels, `column` creates stacked panels. |
+| `sizes` | string | `''` | Positional weight shorthand, e.g. `"1 2 1"`, applied to children lacking an explicit `size`. |
+| `storageKey` | string | `''` | Enables `localStorage` persistence. |
+| `gutterSize` | string | — | Convenience mirror of `--split-gutter-size`. |
+| `snap` | string | — | Convenience mirror of `--split-snap`. |
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--handle-size` | `2px` | Width/height of the split bar |
-| `--handle-colour` | `transparent` | Colour of the split bar |
-| `--handle-hover-colour` | `var(--surface-6)` | Colour of handle when hovering |
-| `--handle-active-colour` | `var(--accent)` | Colour of handle when being dragged |
-| `--handle-bg` | `var(--handle-colour)` | Background colour of the grab handle rectangle |
-| `--handle-grab-colour` | `var(--surface-muted-text)` | Colour of the grab handle dots |
-| `--handle-grab-dot-size` | `3px` | Diameter of each grab handle dot |
-| `--handle-grab-size` | `16px` | Length of the grab handle |
-| `--handle-grab-thickness` | `8px` | Thickness of the grab handle |
-
-### Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `ixfx-split-collapsed` | `{ panel: 'A' \| 'B', collapsed: boolean }` | Fired when a panel is collapsed or uncollapsed via drag. |
+---
+
+## `ixfx-split-panel`
+
+The `ixfx-split-panel` element wraps panel content and provides sizing constraints.
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `id` | string | generated | Identity for persistence + events. |
+| `size` / `weight` | number | `1` | Flex weight. |
+| `fixed` | boolean \| length | `false` | `fixed` or `fixed="200px"` → non-flexible px track. |
+| `min` | length (`px`/`%`) | `0` | Resolved to px against the group's container. |
+| `max` | length | — | |
+| `when-small` | `prevent` \| `collapse` \| `close` | `prevent` | Behaviour past `min`. |
+| `collapsed` | boolean | `false` | Reflected; toggled by the controller. |
+| `snap` | length | `--split-snap` | Per-panel hysteresis override. |
 
 ---
 
 ## Basic Usage
 
-### Vertical Split (Left/Right)
+### Three-Panel Row
 
 ```html
-<ixfx-split-layout layout="vertical" style="width: 100%; height: 400px;">
-  <div slot="a" style="background: var(--surface-3);">Left Panel</div>
-  <div slot="b" style="background: var(--surface-5);">Right Panel</div>
+<ixfx-split-layout direction="row" sizes="1 2 1" style="width: 100%; height: 400px;">
+  <ixfx-split-panel>Left Panel</ixfx-split-panel>
+  <ixfx-split-panel>Center Panel</ixfx-split-panel>
+  <ixfx-split-panel>Right Panel</ixfx-split-panel>
 </ixfx-split-layout>
 ```
 
-### Horizontal Split (Top/Bottom)
+### Column Layout
 
 ```html
-<ixfx-split-layout layout="horizontal" style="width: 100%; height: 400px;">
-  <div slot="a" style="background: var(--surface-3);">Top Panel</div>
-  <div slot="b" style="background: var(--surface-5);">Bottom Panel</div>
+<ixfx-split-layout direction="column" style="width: 100%; height: 400px;">
+  <ixfx-split-panel>Top Panel</ixfx-split-panel>
+  <ixfx-split-panel>Bottom Panel</ixfx-split-panel>
 </ixfx-split-layout>
 ```
 
 ### With Fixed Panel
 
 ```html
-<!-- Left panel fixed at 200px, right panel takes remaining space -->
-<ixfx-split-layout fixedA layout="vertical" style="width: 100%; height: 400px;">
-  <div slot="a" style="background: var(--surface-3);">Left Panel (200px)</div>
-  <div slot="b" style="background: var(--surface-5);">Right Panel (flexible)</div>
+<ixfx-split-layout direction="row" style="width: 100%; height: 400px;">
+  <ixfx-split-panel fixed="200px">Left (200px)</ixfx-split-panel>
+  <ixfx-split-panel>Right (flexible)</ixfx-split-panel>
 </ixfx-split-layout>
 ```
 
----
-
-## Collapsible Panels
-
-When `collapsible` is set, dragging a split bar to the edge collapses that panel. The other panel expands to fill the space. Dragging away from the edge uncollapses the panel.
+### With Min/Max Constraints
 
 ```html
-<ixfx-split-layout collapsible layout="horizontal" style="width: 100%; height: 400px;">
-  <div slot="a" style="background: var(--surface-3);">Top Panel</div>
-  <div slot="b" style="background: var(--surface-5);">Bottom Panel</div>
+<ixfx-split-layout direction="row" style="width: 100%; height: 400px;">
+  <ixfx-split-panel min="100px" max="70%">Left</ixfx-split-panel>
+  <ixfx-split-panel min="50px">Right</ixfx-split-panel>
 </ixfx-split-layout>
 ```
 
-### Collapse Events
-
-```javascript
-const split = document.querySelector('ixfx-split-layout[collapsible]');
-
-split.addEventListener('ixfx-split-collapsed', ({ detail }) => {
-  console.log(`Panel ${detail.panel} is now ${detail.collapsed ? 'collapsed' : 'uncollapsed'}`);
-});
-```
-
 ---
 
-## Min/Max Size Constraints
+## When-Small Behaviour
+
+The `when-small` attribute controls what happens when a panel is dragged past its minimum size:
 
-Use `minSizeA`, `maxSizeA`, `minSizeB`, and `maxSizeB` to constrain panel sizes:
+- `prevent` (default) — Stop at `min`. Cascade continues to next panel.
+- `collapse` — If pointer travels past threshold, collapse the panel. Drag back to restore.
+- `close` — If pointer travels past threshold, show closing affordance. On release, emit cancelable `ixfx-split-close`.
 
 ```html
-<ixfx-split-layout 
-  minSizeA="100px" 
-  maxSizeA="70%" 
-  minSizeB="50px"
-  layout="horizontal" 
-  style="width: 100%; height: 400px;">
-  <div slot="a" style="background: var(--surface-3);">Top Panel</div>
-  <div slot="b" style="background: var(--surface-5);">Bottom Panel</div>
-</ixfx-split-layout>
+<ixfx-split-panel when-small="collapse">Collapsible Panel</ixfx-split-panel>
 ```
 
-**Constraint rules:**
-- **Min constraints take precedence**: If both panels' minimums exceed 100% combined, they're scaled proportionally
-- **Max constraints are secondary**: If a max constraint conflicts with a min constraint, the max is ignored to satisfy the min
-- **The constrained panel gets clamped**: The other panel receives the remaining space
-
 ---
 
-## Nested Splits with Two-Way Corner Resize
-
-When a `ixfx-split-layout` is nested inside slot A of an outer split, a corner zone appears at the intersection of the two split bars. This enables simultaneous resize of both splits.
-
-```
-┌─────────────────┬────────────┐
-│                 │            │
-│   ┌─────────────┤            │
-│   │   Editor    │            │
-│   │             │            │
-│   ├─────────────┤  Sidebar   │
-│   │  Terminal   │            │
-│   │             │            │
-│   └─────────────┘            │
-└─────────────────┴────────────┘
-         ↑
-    Corner Zone
-    (drag here for two-way resize)
-```
+## Nested Splits
 
-### Structure
+Nested `<ixfx-split-layout>` elements create sub-groups:
 
 ```html
-<ixfx-split-layout layout="vertical" style="width: 100%; height: 400px;">
-  <!-- Nested split is a direct child of slot A -->
-  <ixfx-split-layout slot="a" layout="horizontal" style="width: 100%; height: 100%;">
-    <div slot="a" style="background: var(--surface);">Editor</div>
-    <div slot="b" style="background: var(--surface-3);">Terminal</div>
+<ixfx-split-layout direction="row" style="width: 100%; height: 400px;">
+  <ixfx-split-layout direction="column" style="width: 100%; height: 100%;">
+    <ixfx-split-panel>Editor</ixfx-split-panel>
+    <ixfx-split-panel>Terminal</ixfx-split-panel>
   </ixfx-split-layout>
-  <div slot="b" style="background: var(--surface-5);">Sidebar</div>
+  <ixfx-split-panel>Sidebar</ixfx-split-panel>
 </ixfx-split-layout>
 ```
 
-**Note**: For the corner zone to appear, the nested split must be a direct child of slot A (no wrapper elements between the split and slot A).
+---
 
-### Corner Zone Behavior
+## Events
 
-- **Visual indicator**: A small magenta circle (12px) appears at the intersection point
-- **Cursor change**: Shows `nwse-resize` cursor when hovering over the corner zone (for vertical-outer/horizontal-inner splits)
-- **Two-way resize**: Dragging the corner zone adjusts both the outer vertical split and the inner horizontal split simultaneously
-- **Position tracking**: The corner zone follows the split bars as they move, staying at their intersection
+| Name | Detail | Cancelable | When |
+|---|---|---|---|
+| `ixfx-split-resize` | `{ sizes: Record<string, number>; groupId: string }` | no | Drag end, `setSizes`, `collapse`/`expand`. |
+| `ixfx-split-collapse` | `{ id: string; index: number }` | no | Panel collapsed (drag or API). |
+| `ixfx-split-expand` | `{ id: string; index: number }` | no | Panel expanded. |
+| `ixfx-split-close` | `{ id: string; index: number }` | **yes** | Before a panel is removed; `preventDefault()` vetoes. |
+| `ixfx-split-change` | `{ layout: LayoutSnapshot }` | no | After any size/structure change (persistence hook). |
 
 ---
 
-## CSS Customisation
+## CSS Custom Properties
 
-### Handle Styling
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--split-gutter-size` | `6px` | Width/height of gutters |
+| `--split-gutter-color` | `transparent` | Gutter background |
+| `--split-gutter-hover-color` | `var(--surface-6)` | Gutter on hover |
+| `--split-gutter-active-color` | `var(--accent)` | Gutter while dragging |
+| `--split-collapsed-size` | `0px` | Size of collapsed panels |
+| `--split-snap` | `24px` | Snap/hysteresis distance |
+| `--split-grab-color` | `var(--border-subtle-color)` | Grab handle dot colour |
+| `--split-grab-dot-size` | `3px` | Grab handle dot size |
+| `--split-grab-size` | `16px` | Grab handle length |
+| `--split-grab-thickness` | `8px` | Grab handle thickness |
 
-```css
-ixfx-split-layout {
-  --handle-size: 4px;
-  --handle-colour: var(--surface-4);
-  --handle-hover-colour: var(--surface-6);
-  --handle-active-colour: var(--accent);
-}
-```
+---
 
-### Grab Handle
+## Programmatic Control
 
-When `--handle-size` is greater than `5px`, a grab handle appears in the center of the split bar. The grab handle consists of a rectangle with three dots arranged perpendicular to the split direction:
+### Getting/Setting Sizes
 
-- **Vertical split**: Rectangle with 3 vertical dots (⋮)
-- **Horizontal split**: Rectangle with 3 horizontal dots (⁝)
+```javascript
+const split = document.querySelector('ixfx-split-layout');
 
-```css
-ixfx-split-layout {
-  --handle-bg: var(--handle-colour);         /* Rectangle background */
-  --handle-grab-colour: var(--surface-muted-text); /* Dot colour */
-  --handle-grab-dot-size: 3px;               /* Dot diameter */
-  --handle-grab-size: 16px;                 /* Rectangle length */
-  --handle-grab-thickness: 8px;             /* Rectangle thickness */
-}
-```
+// Get all panel sizes
+console.log(split.getSizes());
+// { "p-1": 0.25, "p-2": 0.5, "p-3": 0.25 }
 
-### Hide Collapsed Panels Completely
+// Set sizes by array (positional)
+split.setSizes([1, 2, 1]);
 
-```css
-ixfx-split-layout[data-collapsed-a] slot[name="a"] {
-  display: none;
-}
+// Set sizes by object (id -> weight)
+split.setSizes({ "my-panel": 0.3 });
 ```
 
----
+### Collapse/Expand
 
-## Programmatic Control
+```javascript
+// Collapse a panel
+split.collapse('panel-id');
+
+// Expand a panel
+split.expand('panel-id');
 
-### Setting Sizes
+// Toggle
+split.toggle('panel-id');
+```
+
+### Close Panel (Cancelable)
 
 ```javascript
-const split = document.querySelector('ixfx-split-layout');
+split.addEventListener('ixfx-split-close', (e) => {
+  if (someCondition) {
+    e.preventDefault(); // Veto the close
+  }
+});
 
-// Set to 30% / 70%
-split.sizeA = '30%';
-split.sizeB = '70%';
+split.closePanel('panel-id');
+```
+
+### Manual Gutter Drags
 
-// Set to fixed pixel widths
-split.fixedA = true;
-split.sizeA = '200px'; // Panel A is 200px
-// Panel B automatically gets remaining space
+```javascript
+// Bounding rects of the gutter elements, in gutter index order
+split.getGutterRects();
 
-// Collapse a panel programmatically
-split.collapsedA = true;
-split.collapsedB = false;
+// Start dragging gutter 0 as if the user pressed at (x, y); the drag then
+// follows pointer `pointerId` until pointerup. Returns false when the index
+// is out of range or the layout isn't ready.
+split.beginGutterDrag(0, event.pointerId, event.clientX, event.clientY);
 ```
 
-### Reading State
+`beginGutterDrag` is meant for composite resize affordances — e.g. a corner
+handle that starts this drag alongside perpendicular drags on other nested
+layouts, resizing several splits with one gesture.
+
+### Layout Serialization
 
 ```javascript
-console.log('Panel A size:', split.sizeA);
-console.log('Panel B size:', split.sizeB);
-console.log('Is A collapsed?', split.collapsedA);
-console.log('Is B collapsed?', split.collapsedB);
+// Get current layout
+const layout = split.getLayout();
+// { version: 1, root: { kind: 'group', id: 'g-0', children: [...] } }
+
+// Restore a layout
+split.setLayout(layout);
 ```
 
 ---
 
-## Implementation Notes
+## Persistence
+
+Set `storage-key` to enable automatic localStorage persistence:
+
+```html
+<ixfx-split-layout storage-key="my-app-layout" ...>
+```
 
-- Uses Shadow DOM for style encapsulation
-- Slots use `display: block` and `overflow: hidden` by default
-- When no size is specified for a panel, it defaults to `auto` (fill remaining space)
-- When both sizes are empty, both default to `50%`
-- The split bar is `flex-shrink: 0` to prevent it from collapsing
-- Nested splits detect their parent through slot assignment and automatically enable corner resize
+The layout is saved automatically after each change and restored on page load.

package/docs-user/tabs.md

@@ -52,8 +52,42 @@ Manages tab selection and keyboard navigation.
 | `orientation`       | `'horizontal' \| 'vertical-stack' \| 'vertical-side'` | `'horizontal'` | Layout direction |
 | `flip`              | `boolean`                          | `false`        | Flip indicator to opposite side   |
 | `scrollable`        | `boolean`                          | `false`        | Enable scroll overflow. When set, vertical mousewheel on horizontal lists scrolls horizontally (and vice-versa for vertical lists). |
+| `shrink`            | `boolean`                          | `false`        | When set, tabs size to content (intrinsic width for horizontal, intrinsic height for vertical) instead of stretching to fill the container |
 | `drag-mode`         | `'off' \| 'reorder'`                | `'off'`        | Pointer-driven reordering within the list (sets `grab` cursor on items) |
 
+### Slots
+
+| Slot        | Description                                                                 |
+|-------------|-----------------------------------------------------------------------------|
+| *(default)* | `ixfx-tab-list-item` elements.                                              |
+| `toolbar`   | Toolbar items shown after the tabs. For `orientation="horizontal"` this is right-justified after the tabs and does not scroll with `scrollable`. Put an `ixfx-toolbar` in this slot to get automatic overflow handling. Plain buttons/elements work as well. |
+
+Toolbar example (with overflow):
+
+```html
+<ixfx-tab-list>
+  <ixfx-tab-list-item selected for="p1">Tab A</ixfx-tab-list-item>
+  <ixfx-tab-list-item for="p2">Tab B</ixfx-tab-list-item>
+
+  <ixfx-toolbar slot="toolbar" invisible-groups style="--toolbar-bg:transparent; --toolbar-border:none; --toolbar-padding:0;">
+    <ixfx-button>New</ixfx-button>
+    <ixfx-button>Save</ixfx-button>
+    <ixfx-button>Export</ixfx-button>
+  </ixfx-toolbar>
+</ixfx-tab-list>
+```
+
+For a simple toolbar without overflow, use plain buttons:
+
+```html
+<ixfx-tab-list>
+  <ixfx-tab-list-item>Tab A</ixfx-tab-list-item>
+  <button slot="toolbar" type="button" class="tab-toolbar-btn">Action</button>
+</ixfx-tab-list>
+```
+
+When `orientation="vertical-stack"` / `vertical-side`, the toolbar slot appears after the tabs in the column direction (below the tabs). It is still outside the scrollable tab area.
+
 ### Events
 
 | Event    | Detail                                               | Description               |
@@ -222,9 +256,15 @@ All `--ixfx-*` properties use internal bridge variables to work across the Shado
 | Property                          | Default               | Description                                                                 |
 |-----------------------------------|----------------------|-----------------------------------------------------------------------------|
 | `--ixfx-selected-tab-color`       | `var(--surface-2-text)` | Text color when selected. Can be set on `ixfx-tab-list` or individual items |
+| `--ixfx-selected-tab-icon-color`  | `var(--accent)` | Leading icon color when selected (close/toolbar icons unaffected). Can be set on `ixfx-tab-list` or individual items |
 | `--ixfx-selected-tab-border-width`| `1px`                | Border width when selected                                                   |
 | `--ixfx-selected-tab-weight`     | `bold`               | Font weight when selected                                                   |
+| `--ixfx-selected-tab-text-decoration` | `none`           | Text decoration when selected (e.g. `underline`)                           |
+| `--ixfx-selected-tab-text-decoration-color` | `var(--accent)` | Color of the text decoration when selected                                   |
+| `--ixfx-selected-tab-text-decoration-thickness` | `0px`        | Thickness of the text decoration line when selected                          |
+| `--ixfx-selected-tab-text-decoration-offset` | `2px`     | Space between text and text decoration when selected                         |
 | `--ixfx-tab-selected-background`  | `var(--surface-5)`   | Background when selected. Can be set on `ixfx-tab-list` or individual items |
+| `--ixfx-tab-hover-background`     | *(resting background)* | Background on hover. Unset by default, so each state keeps its resting background. Can be set on `ixfx-tab-list` or individual items |
 | `--ixfx-tab-padding`              | `var(--space-m)`     | Inner padding of each tab. Can be set on `ixfx-tab-list` or individual items |
 
 Example — set custom padding on a single tab:
@@ -244,6 +284,20 @@ Example — set custom padding for all tabs in a list:
 </ixfx-tab-list>
 ```
 
+Example — thick text underline instead of a border indicator:
+
+```html
+<ixfx-tab-list style="
+  --ixfx-selected-tab-border-width: 0;
+  --ixfx-selected-tab-text-decoration: underline;
+  --ixfx-selected-tab-text-decoration-thickness: 3px;
+  --ixfx-selected-tab-text-decoration-offset: 4px;
+">
+  <ixfx-tab-list-item selected>Overview</ixfx-tab-list-item>
+  <ixfx-tab-list-item>Details</ixfx-tab-list-item>
+</ixfx-tab-list>
+```
+
 ### CSS parts
 
 | Part       | Description              |

package/docs-user/titlebar.md

@@ -0,0 +1,102 @@
+# Titlebar
+
+Standalone titlebar chrome extracted from `ixfx-panel`: title text, icon, toolbar slot, close button and an optional collapse/expand caret. Use it when you need a panel-style header without the collapsible content wrapper (custom layouts, dock headers, section bars).
+
+```html
+<ixfx-titlebar title="Settings" icon-name="settings" collapsible>
+  <div slot="toolbar">
+    <button type="button"><ixfx-icon name="printer"></ixfx-icon></button>
+  </div>
+</ixfx-titlebar>
+```
+
+`ixfx-panel` composes this component internally, so the two stay visually in sync.
+
+---
+
+## `ixfx-titlebar`
+
+### Properties / attributes
+
+| Attribute / Property      | Type                                              | Default        | Description                                                     |
+|--------------------------|---------------------------------------------------|----------------|-----------------------------------------------------------------|
+| `title`                  | string                                            | `''`           | Title text                                                      |
+| `icon-name`              | string                                            | `''`           | Icon name from the registry                                     |
+| `orientation`            | `'horizontal'` \| `'vertical'`                    | `'horizontal'` | Layout direction of the bar                                     |
+| `variant`                | `'titlebar'` \| `'midline'`                       | `'titlebar'`   | Visual style (same variants as `ixfx-panel`)                    |
+| `closable`               | boolean                                           | `false`        | Shows a close button that fires `close`                         |
+| `collapsible`            | boolean                                           | `false`        | Shows the caret and enables toggle behaviour (opt-in)           |
+| `collapsed`              | boolean                                           | `false`        | Collapsed state (controls caret rotation / label)               |
+| `toggle-interaction`     | `'implicit'` \| `'explicit'` \| `'disabled'`      | `'implicit'`   | How users can toggle (only when `collapsible` is present)       |
+
+### Collapsible vs toggle interaction
+
+The caret is shown only when `collapsible` is present **and** `toggle-interaction` is not `disabled`. When `collapsible` is absent, `toggle-interaction` is inert and no `toggle` events fire.
+
+| `collapsible` | `toggle-interaction` | Behaviour                                              |
+|---------------|----------------------|--------------------------------------------------------|
+| absent        | any                  | No caret, no user toggle                               |
+| present       | `implicit`           | Clicking the caret or anywhere in the bar toggles      |
+| present       | `explicit`           | Only clicking the caret toggles                        |
+| present       | `disabled`           | Caret hidden, no user toggle (programmatic only)       |
+
+Unlike `ixfx-panel`, toggling only flips the `collapsed` property and fires `toggle` — there is no content to hide. And unlike `ixfx-panel`, `close` does **not** remove the element; the host decides what closing means.
+
+### Slots
+
+| Slot        | Description                                      |
+|-------------|--------------------------------------------------|
+| `toolbar`   | Buttons or other elements right-aligned in the bar |
+
+Clicking toolbar content never toggles, even with `toggle-interaction="implicit"`.
+
+### Events
+
+| Event    | Detail                             | Description                              |
+|----------|------------------------------------|------------------------------------------|
+| `toggle` | `{ collapsed: boolean }`           | Fired when collapsed state changes       |
+| `close`  | —                                  | Fired when the close button is clicked   |
+
+```js
+const bar = document.querySelector('ixfx-titlebar');
+
+bar.addEventListener('toggle', e => {
+  console.log('Collapsed:', e.detail.collapsed);
+});
+
+bar.addEventListener('close', () => {
+  console.log('Close requested');
+});
+```
+
+### Icons
+
+Icon names resolve against the icon registry. Register custom icons with `registerIcon(name, svgString)` from `src/icons/registry.ts`.
+
+Built-in icon names: `check`, `chevron-down`, `chevron-right`, `close`.
+
+---
+
+## Visual variants
+
+Same `titlebar` (default) and `midline` styles as `ixfx-panel`, including vertical orientation support:
+
+```html
+<ixfx-titlebar title="Settings" variant="midline" icon-name="settings" collapsible></ixfx-titlebar>
+<ixfx-titlebar title="Device" orientation="vertical" icon-name="server" collapsible></ixfx-titlebar>
+```
+
+---
+
+## TypeScript types
+
+```ts
+import type { TitlebarOrientation, TitlebarVariant, TitlebarToggleInteraction, TitlebarToggleDetail } from 'ixfxfun-components';
+```
+
+---
+
+## See also
+
+- [`ixfx-panel`](../panel/README.md) — Collapsible panel that composes this titlebar
+- [`ixfx-icon`](../icons/README.md) — Icon component used by the titlebar