@ixfx/components 0.6.2 → 0.7.0

package/docs-user/detail-list.md

@@ -0,0 +1,398 @@
+# `ixfx-detail-list`
+
+A list that scales horizontally, not vertically. Items are laid out in equal-width columns; they flow top→bottom down a column, then wrap to the top of the next column to the right. The component has a fixed vertical extent and scrolls horizontally.
+
+Selection semantics match `ixfx-vertical-list` — same modes, same `list-*` events, same keyboard gestures — but navigation is a 2-D grid (Up/Down move within a column, Left/Right jump columns).
+
+---
+
+## Contents
+
+1. [Quick start](#quick-start)
+2. [Item types](#item-types)
+3. [Properties](#properties)
+4. [Selection](#selection)
+5. [Interaction modes](#interaction-modes)
+6. [Custom checkbox](#custom-checkbox)
+7. [Events](#events)
+8. [Keyboard navigation](#keyboard-navigation)
+9. [Incremental search](#incremental-search)
+10. [Filter predicate](#filter-predicate)
+11. [Sorting](#sorting)
+12. [Asynchronous data](#asynchronous-data)
+13. [CSS variables](#css-variables)
+14. [CSS parts](#css-parts)
+
+---
+
+## Quick start
+
+### Declarative HTML items
+
+```html
+<ixfx-detail-list id="my-list" selection-mode="single">
+  <li>Alpha</li>
+  <li>Bravo</li>
+  <li>Charlie</li>
+</ixfx-detail-list>
+
+<script type="module">
+  import '@ixfx/components';
+
+  const list = document.querySelector('#my-list');
+  list.addEventListener('list-select', ({ detail }) => {
+    const [item] = detail.selected;
+    console.log('selected:', item?.textContent);
+  });
+</script>
+```
+
+Items flow down columns (vertically) then wrap to the next column:
+
+```
+Alpha    Golf     November  Uniform
+Bravo    Hotel    Oscar    Victor
+Charlie  India    Papa     Whiskey
+Delta    Juliett  Quebec   X-ray
+Echo     Kilo     Romeo    Yankee
+Foxtrot  Lima     Sierra   Zulu
+```
+
+### Programmatic items
+
+```typescript
+import type { DetailListElement } from '@ixfx/components';
+
+const list = document.querySelector<DetailListElement>('ixfx-detail-list')!;
+
+list.addItem('Document A');
+list.addItem('Image 01.png');
+
+// Or pass an element directly
+const li = document.createElement('li');
+li.textContent = 'Custom item';
+list.addItem(li);
+```
+
+---
+
+## Item types
+
+### Plain `<li>` elements
+
+The simplest item type. Items are positioned by CSS flexbox into columns.
+
+```html
+<ixfx-detail-list>
+  <li>Item one</li>
+  <li>Item two</li>
+</ixfx-detail-list>
+```
+
+**Attributes supported on `<li>`:**
+
+| Attribute | Description |
+|---|---|
+| `data-search-label` | Override searchable text (defaults to `textContent`) |
+| `data-key` | Stable identity for selection persistence across sort/rebuild |
+| `data-value` | Alternative to `data-key` |
+| `data-icon` | Icon name to display (injects `<ixfx-icon>`) |
+| `not-checked` | In `checked` mode, renders without a checkbox and cannot be checked |
+| `hidden` | Hides the item from view and navigation |
+
+### Object items
+
+Pass an array of objects and configure how to display them:
+
+```typescript
+const files = [
+  { name: 'Report Q1.pdf', size: 220, kind: 'doc' },
+  { name: 'Photo 01.png', size: 1400, kind: 'img' },
+  { name: 'Notes.txt', size: 3, kind: 'doc' },
+];
+
+list.items = files;
+list.displayProperty = 'name';
+list.keyProperty = 'name'; // Preserves selection across rebuilds
+```
+
+**Object-related properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `items` | `readonly unknown[]` | Array of objects to render |
+| `displayProperty` | `string` | Property name to use as label |
+| `keyProperty` | `string` | Property name for stable identity |
+| `iconProperty` | `string` | Property name for icon name |
+| `formatter` | `(item: unknown, index: number) => string \| Node` | Custom renderer |
+
+```typescript
+list.formatter = (item, index) => {
+  const file = item as { name: string; size: number };
+  return `${file.name} (${file.size} KB)`;
+};
+```
+
+Retrieve the original data for an element:
+
+```typescript
+const data = list.getItemData(liElement);
+```
+
+---
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|---|---|---|---|---|
+| `selectionMode` | `selection-mode` | `'single' \| 'multiple' \| 'none'` | `'single'` | How selection works |
+| `interactionMode` | `interaction-mode` | `'implicit' \| 'standard' \| 'manual' \| 'checked' \| 'sticky' \| 'vscode'` | `'standard'` | Click/keyboard behavior |
+| `sort` | `sort` | `'none' \| 'ascending' \| 'descending'` | `'none'` | Sort direction |
+| `sortBy` | `sort-by` | `string` | — | Object property to sort by |
+| `sortComparator` | — | `(a, b) => number` | — | Custom sort function |
+| `filterPredicate` | — | `(el: Element) => boolean` | — | Filter visible items |
+| `itemWrap` | `item-wrap` | `'stop' \| 'wrap'` | `'stop'` | Keyboard wrap behavior |
+| `provider` | — | `IDataProvider` | — | Async data source |
+| `checkboxRenderer` | — | `function \| object` | — | Custom checkbox |
+
+---
+
+## Selection
+
+### Getters
+
+```typescript
+const selected = list.selectedItem;       // First selected element or undefined
+const allSelected = list.selectedItems;   // Array of all selected elements
+```
+
+### Methods
+
+```typescript
+list.select(item);          // Select an item
+list.deselect(item);       // Deselect an item
+list.selectMany([item1, item2]); // Select multiple
+list.clearSelection();     // Clear all selections
+list.selectAll();          // Select all visible items (if permitted)
+```
+
+---
+
+## Interaction modes
+
+| Mode | Description |
+|---|---|
+| `standard` | Click replaces selection. Ctrl+click toggles. Shift+click creates range. Cmd+A selects all. |
+| `implicit` | Click always replaces selection (no modifier support). |
+| `checked` | Checkbox column toggles selection; rows marked `not-checked` have no checkbox. |
+| `sticky` | Every click toggles. Cmd+A selects all. |
+| `vscode` | Like `standard`, but Shift+Arrow extends selection range. |
+| `manual` | No auto-selection; drive state via `select()` / `deselect()` programmatically. |
+
+---
+
+## Custom checkbox
+
+In `checked` mode, provide a custom checkbox renderer:
+
+```typescript
+list.checkboxRenderer = (checked) => checked
+  ? html`<span>✓</span>`
+  : html``;
+```
+
+Or use the shorthand object form:
+
+```typescript
+list.checkboxRenderer = { checked: '✓', unchecked: '' };
+```
+
+---
+
+## Events
+
+| Event | Detail | Description |
+|---|---|---|
+| `list-select` | `{ selected: Element[] }` | Selection changed |
+| `list-tickle` | `{ item: Element }` | Hover/focus cursor moved |
+| `list-activate` | `{ item: Element }` | Item activated (Enter/double-click) |
+| `list-item-click` | `{ item: Element }` | Item clicked |
+
+```typescript
+list.addEventListener('list-select', (e) => {
+  console.log('Selected:', [...e.detail.selected].map(el => el.textContent));
+});
+```
+
+---
+
+## Keyboard navigation
+
+The list must have focus for keyboard navigation. Click an item to focus, or set `tabindex="0"` on the element.
+
+| Key | Action |
+|---|---|
+| ↑ / ↓ | Move up/down within the current column |
+| ← / → | Jump to previous/next column (same row) |
+| Home | Jump to first item |
+| End | Jump to last item |
+| Enter | Activate item (fires `list-activate`) |
+| Space | Toggle selection (in modes that support it) |
+| Escape | Clear selection / close search |
+| Ctrl+F | Open incremental search |
+| Ctrl+A | Select all (in modes that support it) |
+
+### Wrapping
+
+Set `item-wrap="wrap"` to enable wraparound navigation:
+
+```html
+<ixfx-detail-list item-wrap="wrap">...</ixfx-detail-list>
+```
+
+With wrapping:
+- Down from last row → first row of next column (or first column if at end)
+- Up from first row → last row of previous column (or last column if at start)
+- Right from last column → first column
+- Left from first column → last column
+
+---
+
+## Incremental search
+
+Press Ctrl+F (or Cmd+F on Mac) to open the search overlay. Type to filter items in real-time using fuzzy matching.
+
+Search matches against `data-search-label` (or `textContent` as fallback). Use `data-search-label` to match against a different string than what's displayed:
+
+```html
+<li data-search-label="document a alpha">Document A</li>
+```
+
+### Highlight styling
+
+Matched characters are highlighted with the `detail-list-search` highlight key. Style matches with:
+
+```css
+::highlight(detail-list-search) {
+  background: yellow;
+  color: black;
+}
+```
+
+---
+
+## Filter predicate
+
+Use `filterPredicate` to programmatically hide items:
+
+```typescript
+// Show only .doc files
+list.filterPredicate = (el) => el.getAttribute('data-kind') === 'doc';
+
+// Clear filter
+list.filterPredicate = undefined;
+```
+
+Filtered items are hidden from view, keyboard navigation, and selection.
+
+---
+
+## Sorting
+
+### Simple sort
+
+```typescript
+list.sort = 'ascending';  // or 'descending'
+```
+
+### Sort by property
+
+```typescript
+list.sortBy = 'size';  // Sort by 'size' property
+list.sort = 'ascending';
+```
+
+### Custom comparator
+
+```typescript
+list.sortComparator = (a, b) => {
+  // Sort by kind first, then by label
+  const kindCompare = a.data.kind.localeCompare(b.data.kind);
+  if (kindCompare !== 0) return kindCompare;
+  return a.label.localeCompare(b.label);
+};
+```
+
+The comparator receives `{ element, data, label }` where:
+- `element` — the `<li>` DOM element
+- `data` — the original object from `items` array
+- `label` — the display string
+
+---
+
+## Asynchronous data
+
+Use a `provider` for async data loading:
+
+### Promise provider
+
+```typescript
+list.provider = async () => {
+  const response = await fetch('/api/items');
+  return response.json();
+};
+```
+
+### Streaming provider
+
+```typescript
+list.provider = async function*() {
+  for (let i = 0; i < 100; i++) {
+    yield [{ id: i, name: `Item ${i}` }];
+    await delay(100);
+  }
+}();
+```
+
+The provider function can return:
+- A promise that resolves to an array
+- An async iterable that yields arrays (streaming)
+
+Streaming providers extend columns to the right as batches arrive.
+
+---
+
+## CSS variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `--detail-list-bg` | `surface-3` | Background color |
+| `--detail-list-text` | `surface-3-text` | Text color |
+| `--detail-list-border` | `border` | Border color |
+| `--detail-list-radius` | `radius-s` | Border radius |
+| `--detail-list-column-width` | `220px` | Width of each column |
+| `--detail-list-column-gap` | `8px` | Gap between columns |
+| `--detail-list-item-height` | `28px` | Height of each item |
+| `--detail-list-item-padding` | `0 var(--space-m)` | Item padding |
+| `--detail-list-scrollbar-width` | `auto` | Scrollbar width |
+| `--detail-list-scrollbar-gutter` | `auto` | Scrollbar gutter |
+| `--detail-list-scrollbar-color` | `auto` | Scrollbar color |
+
+Plus all `--item-bg-*`, `--item-text-*` variables from the theme for selection/tickle states.
+
+---
+
+## CSS parts
+
+| Part | Description |
+|---|---|
+| `list` | The `<ul>` container |
+| `search-overlay` | The Ctrl+F search overlay |
+| `checkbox` | The checkbox element (in `checked` mode) |
+| `loading` | The loading indicator |
+
+```css
+ixfx-detail-list::part(search-overlay) {
+  background: rgba(0, 0, 0, 0.8);
+}
+```

package/docs-user/dock.md

@@ -0,0 +1,310 @@
+# Dock (`ixfx-dock-host` / `ixfx-dock-panel`)
+
+Dockable, movable panels like VS Code / Photoshop. Drag a panel by its
+titlebar (solo) or its tab (tabbed) over another panel; depending on cursor
+position it becomes a **tab** in that group or **splits** the target to the
+top/bottom/left/right. Infinitely composable, serializable, and restrictable.
+
+```
+<ixfx-dock-host layout='{"version":1,"root":{…}}'>
+  <ixfx-dock-panel panel-id="explorer" title="Explorer" closable>…</ixfx-dock-panel>
+  <ixfx-dock-panel panel-id="editor" title="Editor" closable>…</ixfx-dock-panel>
+</ixfx-dock-host>
+```
+
+## Architecture
+
+- **Flat panel pool + model-driven host.** Panels stay direct light-DOM
+  children of the host for their whole life — they are never reparented
+  within a host. The host owns an in-memory `DockNode` tree (`dock-model.ts`),
+  renders split/tab scaffolding in shadow DOM, and projects panels into leaves
+  via `slot="dock-panel-{id}"`. Moving a panel = model mutation → re-render →
+  slot reassignment; panel DOM and state are never destroyed.
+- **Split nodes** render as a single `ixfx-split-layout` (n-way) with one
+  wrapper child per child node. Splits of the *other* direction are emitted as
+  nested `<ixfx-split-layout>` directly (the split element recurses into them).
+  Per-child weights ride on `size` attributes; stack collapse rides on
+  `collapsed` / `when-small` attributes.
+- **Stack (leaf) nodes** always render the same chrome: an `ixfx-tab-list`
+  strip (with generated `ixfx-tab-list-item`s, one per panel) plus a single
+  body slot for the active panel — so titlebars are consistent whether a stack
+  holds one panel or many. Docked panels are `presentation="tabbed"`
+  (content only); the tab item is the drag handle and carries title / icon /
+  close / per-panel toolbar. `ixfx-tab-panels` is deliberately not used — the
+  host owns slot projection. Panels outside a host (or not currently docked)
+  render `presentation="solo"` with an `ixfx-titlebar` and flat content.
+
+## Data model (`types.ts` / `dock-model.ts`)
+
+```ts
+type DockLayout   = { version: 1; root: DockNode };
+type DockNode     = DockSplitNode | DockStackNode;
+type DockSplitNode = { kind: 'split'; direction: 'row' | 'column';
+                       sizes: number[]; children: DockNode[] };
+type DockStackNode = { kind: 'stack'; panels: string[]; active: string;
+                       collapsed?: boolean; preCollapseSize?: string };
+```
+
+`direction` uses `ixfx-split-layout`'s flexbox sense: `row` = side by side,
+`column` = stacked. A "split horizontal" drop (horizontal divider, panels
+stacked vertically) maps to `direction: "column"`.
+
+`normalize()` runs after every mutation: empty stacks are removed, ≤1-child
+splits dissolve, same-direction child splits flatten into their parent,
+`sizes` stays parallel to `children`, and `active` always points at a member.
+The tree is plain and mutable, owned exclusively by the host.
+
+## Drop targeting — the 5-zone model
+
+While dragging, the host overlay highlights the resulting region:
+
+| Region | Operation | Result |
+|---|---|---|
+| leaf centre (~50% box) | `tabs` | insert into that stack (at the hovered strip gap when over the strip) |
+| leaf left / right band | `split-vertical` | new stack beside the leaf |
+| leaf top / bottom band | `split-horizontal` | new stack above/below the leaf |
+| host gutter / edges (outside all leaves) | split **root** | new stack against the whole host |
+
+When the target's parent split already matches the drop direction the new
+stack is inserted beside it (50/50 weight split); otherwise the target is
+wrapped in a new split. `Escape` or `pointercancel` cancels with no mutation.
+
+## Junction resize
+
+Where a parent gutter line meets a nested split's gutter (T and + crossings
+of three or four panels), the host renders a small hover-revealed handle
+(colour: `--dock-junction-color`, default `var(--accent)`). Dragging it
+starts the vertical and horizontal gutter drags at once via
+`ixfx-split-layout`'s `beginGutterDrag()`, resizing all adjacent panels with
+one gesture — as in VS Code. Handle positions are recomputed on renders,
+split resizes, and host resizes; handles are hidden during dock drags.
+
+## Restrictions
+
+- Host `accepts` attribute: space-separated `tabs`, `horizontal`, `vertical`,
+  convenience `all`; `""` / `none` rejects everything. Default allows all.
+- Panel `accepts` attribute: applies when that panel is a **solo** drop
+  target. Default unrestricted.
+- `host.canAccept = (panelId, op) => boolean` — finest-grained veto, consulted
+  per candidate zone.
+
+A zone lights up only if all three allow it; disallowed zones are inert.
+
+## Events
+
+`ixfx-dock-host`: `dock-change` (`{ layout }` after structural mutations),
+`dock-panel-added`, `dock-panel-removed`, `dock-panel-activated`,
+`dock-panel-drag-start`.
+
+Cross-window (see [Cross-window docking](#cross-window-docking-electron-etc)):
+`dock-panel-drag-out` / `dock-panel-drag-in`
+(`{ panelId, clientX, clientY, screenX, screenY }`) when the drag pointer
+leaves / re-enters every host's bounds, and `dock-panel-tear-out`
+(`{ panelId, snapshot, clientX, clientY, screenX, screenY }`) when a panel is
+released with no host under the pointer.
+
+`ixfx-dock-panel`: `dock-panel-drag-start` (`{ panelId, pointerId, clientX,
+clientY }`), plus `close` / `toggle` forwarded from its `ixfx-titlebar`.
+The panel removes itself on close; the host's pool sync routes that through
+the model and emits `dock-panel-removed` + `dock-change`.
+
+The host consumes `ixfx-split-layout` events: `ixfx-split-resize` /
+`ixfx-split-change` (live gutter weights folded into `DockSplitNode.sizes`),
+`ixfx-split-collapse` / `ixfx-split-expand` (→ `DockStackNode.collapsed`), and
+`ixfx-split-close` (cancelable — prevented and rerouted so panel elements
+survive, re-homed into the first other stack).
+
+## Public API — `ixfx-dock-host`
+
+```ts
+saveLayout(): DockLayout                 // folds live split weights from the DOM
+loadLayout(layout: DockLayout): void
+addPanel(panel: DockPanelElement | DockPanelInit, target?: {
+  stack?: string; index?: number; op?: DockOperation   // stack = a panel-id in the target stack
+}): void
+removePanel(panelId: string): boolean    // removes the element from the DOM too
+activatePanel(panelId: string): boolean
+getPanelIds(): string[]
+canAccept?: (panelId: string, op: DockOperation) => boolean
+
+// Cross-window hooks (serializable in/out; no element handoff)
+getPanelSnapshot(panelId: string): DockPanelSnapshot | null
+detachPanel(panelId: string): DockPanelSnapshot | null   // snapshot + removePanel
+queryDropTarget(x: number, y: number, panelId?: string): DockDropTarget | null
+previewExternalDrop(x: number, y: number, panelId?: string): DockDropTarget | null
+endExternalDrop(): void
+acceptExternalPanel(snap: DockPanelSnapshot | DockPanelInit,
+                    at?: { clientX: number; clientY: number }): DockPanelElement | null
+```
+
+The optional `layout` attribute accepts `DockLayout` JSON as the initial
+layout; without it, all pooled panels go into one root stack in source order.
+Panels present in the pool but missing from a loaded layout are appended to
+the first stack.
+
+## Cross-host drags
+
+Panels can be dragged between hosts (register via the shared drag
+coordinator automatically). The source host releases the panel from its model
+and the target host adopts the element — the one sanctioned reparent
+(`connectedCallback` re-runs on the panel; it holds no per-host state).
+`panel-id` must be unique across all hosts that can exchange panels.
+
+This works only *within one document*. The drag coordinator is module state, so
+it never spans separate windows (`BrowserWindow` / `WebContentsView` / a popped
+`window.open`). Moving a panel across that boundary is described next.
+
+## Cross-window docking (Electron, etc.)
+
+The dock deliberately ships **no** window/IPC/Node dependency. Instead it
+exposes the events and methods an outer coordinator (your Electron main
+process, a `SharedWorker`, `BroadcastChannel`, `postMessage`…) needs to move a
+panel between windows. Nothing DOM crosses the boundary — you transport a
+plain, structured-clone-safe **`DockPanelSnapshot`** and rebuild the panel on
+the far side.
+
+```ts
+interface DockPanelSnapshot {           // structured-clone safe
+  panelId: string; title: string; iconName: string;
+  closable: boolean; collapsible: boolean; accepts: string;
+  contentHTML: string;   // best-effort innerHTML snapshot; see note below
+}
+interface DockDropTarget {              // serializable hit-test result
+  operation: 'tabs' | 'split-horizontal' | 'split-vertical';
+  targetPath: number[];  // stack path in the target host model; [] = root
+  side: 'before' | 'after';
+  gapIndex?: number;
+}
+```
+
+> **`contentHTML`** is a convenience for panels whose body is static markup.
+> If a panel holds live state, framework-managed DOM, canvas/WebGL, or running
+> timers, ignore it and rebuild the body from your own model in the new window
+> (you already do this to render the panel the first time). The snapshot is
+> identity + chrome; content ownership stays with your app.
+
+### 1. Panel → new window (tear-out)
+
+While a drag is in progress the host fires boundary events as the pointer
+leaves and re-enters the union of all host rects:
+
+| Event | When | Use |
+|---|---|---|
+| `dock-panel-drag-out` | pointer left every host | start a native drag image / detached preview window that follows the cursor |
+| `dock-panel-drag-in`  | pointer came back over a host | tear down that preview; the in-page drop overlay takes over again |
+| `dock-panel-tear-out` | released with no host under the pointer | create the real window and move the panel |
+
+All three carry `clientX/clientY` (source viewport) **and** `screenX/screenY`
+(desktop) so the receiver can place a window. `dock-panel-tear-out` also
+carries a ready-made `snapshot`.
+
+```ts
+host.addEventListener('dock-panel-tear-out', (e) => {
+  const { snapshot, screenX, screenY } = e.detail;
+  window.dockBridge.openPanelWindow({ snapshot, screenX, screenY });   // → main process
+  host.detachPanel(snapshot.panelId);   // snapshot already taken; drop it here
+});
+```
+
+```ts
+// main process
+ipcMain.handle('dock:open-panel-window', (_e, { snapshot, screenX, screenY }) => {
+  const win = new BrowserWindow({ x: screenX - 40, y: screenY - 20, width: 480, height: 360, /* … */ });
+  win.loadFile('panel-window.html');
+  win.webContents.once('did-finish-load', () =>
+    win.webContents.send('dock:mount-panel', snapshot));
+});
+```
+
+```ts
+// panel-window.html renderer — a host that starts empty
+ipcRenderer.on('dock:mount-panel', (_e, snapshot) => {
+  document.querySelector('ixfx-dock-host').acceptExternalPanel(snapshot);
+});
+```
+
+Because `pointerup` outside the OS window is not reliably delivered to a
+renderer, prefer starting a native follow-the-cursor window on
+`dock-panel-drag-out` and finalising from the **main** process on the global
+mouse-up, rather than depending on `dock-panel-tear-out` firing. `tear-out`
+is the best-effort path for release inside the window but between hosts.
+
+### 2. Window → this host (tear-in)
+
+Detecting an OS-level window drag is the app's job — Electron gives you the
+screen cursor (`screen.getCursorScreenPoint()`) and window bounds
+(`win.getBounds()`), so the main process can tell, per frame, when a dragged
+panel-window is hovering another window and where. Forward that to the target
+renderer, which drives the host imperatively:
+
+```ts
+// target renderer, fed pointer position + the dragged panel's snapshot over IPC
+ipcRenderer.on('dock:external-drag-move', (_e, { snapshot, clientX, clientY }) => {
+  host.previewExternalDrop(clientX, clientY, snapshot.panelId);   // lights the overlay
+});
+ipcRenderer.on('dock:external-drag-leave', () => host.endExternalDrop());
+ipcRenderer.on('dock:external-drag-drop', (_e, { snapshot, clientX, clientY }) => {
+  const placed = host.acceptExternalPanel(snapshot, { clientX, clientY });
+  if (placed) ipcRenderer.send('dock:close-source-window');   // panel now lives here
+});
+```
+
+`previewExternalDrop` / `queryDropTarget` return the `DockDropTarget` that a
+drop at that point would produce (or `null` when the point misses the host or
+the zone is vetoed by `accepts` / `canAccept`), so the coordinator can also
+show a yes/no cursor on the source side. `acceptExternalPanel` honours the
+same restrictions and falls back to the first stack when `at` is omitted or
+outside the host.
+
+### Coordinate spaces
+
+Events give you both. `client*` is the source renderer's viewport;
+`screen*` is the desktop. To convert a desktop point into a target renderer's
+viewport, the app subtracts that window's content bounds (main process:
+`win.getContentBounds()`), accounting for `devicePixelRatio`. Keep the
+conversion in the coordinator — the component only ever speaks the two spaces
+it can measure.
+
+### Identity
+
+`panelId` must be unique across every host that can exchange panels, in every
+window. `acceptExternalPanel` returns `null` if that id is already docked in
+the target host (adopt / focus it yourself instead).
+
+## Serialization
+
+`saveLayout()` folds live gutter weights from each rendered
+`ixfx-split-layout` (via `getSizes()`) into `DockSplitNode.sizes` before
+serializing, so a save → drag → save round-trip preserves user adjustments.
+`DockStackNode.collapsed` / `preCollapseSize` serialize so a saved layout can
+restore collapse state without a live element.
+
+## CSS variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `--dock-drop-zone-color` | drop highlight colour | `var(--accent)` |
+| `--dock-drop-zone-opacity` | drop highlight opacity | `0.25` |
+| `--dock-collapsed-size` | collapsed stack track size | `40px` |
+| `--dock-tab-height` | tab item height, uniform across all leaf strips | `30px` |
+| `--dock-split-bar-size` | thickness of the split-layout bars between leaves | `2px` |
+| `--dock-junction-color` | junction resize handle affordance colour | `var(--accent)` |
+
+Splitter styling delegates to `ixfx-split-layout` (`--split-*`); solo panel
+chrome delegates to `ixfx-titlebar`, and the leaf body is the docked panel
+surface. Each leaf carries a hairline border (`var(--border-subtle)`) with
+slight rounding (`var(--radius-m)`). An empty
+host renders a placeholder; replace its content with
+`<div slot="empty">…</div>`.
+
+## Deviations from the original plan (and why)
+
+- **Tab-strip reorder** is handled by the dock drag coordinator (gap-index
+  insertion) rather than `ixfx-tab-list`'s own `drag-mode="reorder"` — running
+  both would race two ghosts for the same pointer. The gap computation
+  reuses the tab-list midpoint rule.
+- **Closing a leaf via `ixfx-split-close`** re-homes its panels into the first
+  other stack (or the pool if none) instead of dropping them on the floor.
+- **Group toolbar** renders per-strip split buttons (`↕` / `↔`) that split the
+  stack's active panel out — host-authored chrome in the strip's toolbar slot,
+  as the plan describes.