@ixfx/components 0.7.2 → 0.7.4

package/docs-user/data-grid.md

@@ -65,6 +65,30 @@ grid.getRowKey = (row, i) => row.key ?? row.id ?? String(i);
 
 Reassign `rows` to update. Sorting is derived from `sortState`.
 
+When the row set changes without a wholesale replace — rows spliced in, rows
+filtered out — the new rows fade in and, for ~0.3s afterwards, every row slides
+to its new position instead of snapping (so an inserted row's neighbours make
+room and a removed row's gap closes). Skipped under `prefers-reduced-motion:
+reduce`; timing is `--data-grid-row-move-duration` (default `200ms`).
+
+### Streaming appends — `appendRows()`
+
+Reassigning `rows` re-runs `_applySort([...rows])` + `_rebuildFlat()` every
+time — O(n log n) per batch, quadratic over a full load. When feeding the grid
+from a stream (paged fetch, incremental scan), use `appendRows()` instead:
+
+```ts
+for await (const batch of stream) {
+  grid.appendRows(batch);
+}
+```
+
+It still sets `rows` to a new array reference (reactivity preserved) but
+**bypasses the `rows` setter's full rebuild** — the derived arrays are extended
+over the appended slice only. When a sort is active the new rows show unsorted
+for one frame, then a single coalesced re-sort runs. Scroll position, selection
+and cursor are preserved across the append.
+
 ---
 
 ## Selection & interaction
@@ -76,7 +100,19 @@ Reassign `rows` to update. Sorting is derived from `sortState`.
 
 See `ixfx-vertical-list` README for mode table. Data-grid adds checkbox column in `checked` mode.
 
-Programmatic: selection is `Set<string>` of row keys (`_selectedKeys` private, read via events).
+### Programmatic selection & cursor
+
+```ts
+grid.selectedKeys;                 // ReadonlySet<string> of selected row keys
+grid.selectedKeys = ['r3', 'r7'];  // replace (clamped to known rows, single-mode keeps the last)
+grid.selectKeys(['r3', 'r7']);     // alias of the setter
+
+grid.tickleRow('r7');              // move the row cursor + scroll it into view
+grid.tickledKey;                   // row key under the cursor, or undefined
+```
+
+The setter fires `datagrid-select` `{ selectedKeys, previous }` only when the
+selection actually changes.
 
 ---
 
@@ -194,6 +230,10 @@ Demo: `Score` is random float `0–100` with 0–3 decimals, `align:'right'`, `f
 
 Gear menu (`ixfx-menu-trigger` placement `bottom-end`, `inset-area: block-end span-inline-end`) lists `Columns` (check-items) and `Group by` (radio). Toggle visibility via `col.visible=false` or menu. Event: `datagrid-column-visibility` `{key, visible}`.
 
+`column-menu` attribute: `auto` (default) renders the gear menu; `none`
+suppresses it entirely. `col.visible` + `datagrid-column-visibility` still give
+full external control, so `none` lets a host own the column-visibility UI.
+
 Other events: `datagrid-column-reorder` `{from,to,columns}`, `datagrid-column-resize` `{key,width}`, `datagrid-cell-click` `{rowKey,colKey,rowIndex,colIndex}`, `datagrid-cell-edit` `{rowKey,colKey,oldValue,newValue}`.
 
 ---
@@ -218,6 +258,7 @@ Grid is focusable (`tabindex=0`). When not editing:
 | Variable | Default | Description |
 |---|---|---|
 | `--data-grid-row-height` | `28px` | Row height |
+| `--data-grid-row-move-duration` | `200ms` | Insertion / removal animation duration |
 | `--data-grid-header-height` | `32px` | Header height |
 | `--data-grid-bg` | `var(--surface-3)` | Grid background |
 | `--data-grid-header-bg` | `var(--surface-2)` | Header background |
@@ -239,10 +280,18 @@ No `::part` exports yet (header/row/cell are shadow-internal).
 | `startRowEdit` | `(rowKey)` | Open row editors |
 | `stopEdit` | `()` | Cancel editors |
 | `getVisibleRange` | `()=>{startRow,endRow,startCol,endCol}` | Virtual window |
+| `appendRows` | `(rows)` | Add rows without a full re-sort/rebuild — for streaming |
+| `selectKeys` / `set selectedKeys` | `(keys)` | Replace the selection by row key |
+| `tickleRow` | `(key)` | Move the row cursor and scroll it into view |
+
+| Getter | Type | |
+|---|---|---|
+| `selectedKeys` | `ReadonlySet<string>` | Selected row keys |
+| `tickledKey` | `string \| undefined` | Row key under the cursor |
 
 ---
 
 ## Demo
 
-`demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability + `Edit first row` (manual).
+`demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability/`column-menu` + `Edit first row` (manual), a `Stream +5,000 rows` button (`appendRows`), and `selectKeys` / `tickleRow` buttons.
 

package/docs-user/detail-list.md

@@ -8,20 +8,35 @@ Selection semantics match `ixfx-vertical-list` — same modes, same `list-*` eve
 
 ## 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)
+- [`ixfx-detail-list`](#ixfx-detail-list)
+  - [Contents](#contents)
+  - [Quick start](#quick-start)
+    - [Declarative HTML items](#declarative-html-items)
+    - [Programmatic items](#programmatic-items)
+  - [Item types](#item-types)
+    - [Plain `<li>` elements](#plain-li-elements)
+    - [Object items](#object-items)
+  - [Properties](#properties)
+  - [Selection](#selection)
+    - [Getters](#getters)
+    - [Methods](#methods)
+  - [Interaction modes](#interaction-modes)
+  - [Custom checkbox](#custom-checkbox)
+  - [Events](#events)
+  - [Keyboard navigation](#keyboard-navigation)
+    - [Wrapping](#wrapping)
+  - [Incremental search](#incremental-search)
+    - [Highlight styling](#highlight-styling)
+  - [Filter predicate](#filter-predicate)
+  - [Sorting](#sorting)
+    - [Simple sort](#simple-sort)
+    - [Sort by property](#sort-by-property)
+    - [Custom comparator](#custom-comparator)
+  - [Asynchronous data](#asynchronous-data)
+    - [Promise provider](#promise-provider)
+    - [Streaming provider](#streaming-provider)
+  - [CSS variables](#css-variables)
+  - [CSS parts](#css-parts)
 
 ---
 
@@ -72,8 +87,17 @@ list.addItem('Image 01.png');
 const li = document.createElement('li');
 li.textContent = 'Custom item';
 list.addItem(li);
+
+// removeItem / removeItems return a Promise that resolves once the row is gone
+list.removeItems(list.selectedItems);
 ```
 
+Rows added mid-list collapse + fade in; `removeItem` / `removeItems` collapse +
+fade them out before detaching, so the rows around them slide to make or close
+the gap. A bulk populate isn't animated, and it's all skipped under
+`prefers-reduced-motion: reduce` (`--ixfx-list-item-move-duration`, default
+`200ms`).
+
 ---
 
 ## Item types
@@ -176,6 +200,35 @@ list.clearSelection();     // Clear all selections
 list.selectAll();          // Select all visible items (if permitted)
 ```
 
+### Key-based selection
+
+`Element` references die when the item set is rebuilt (re-fetch, re-sort,
+filter). Drive selection by a stable **`data-key`** (or `data-value`) instead —
+the Element API is unchanged, the key API is additive. Object items built from
+`items` / a provider get their key stamped automatically from `keyProperty`.
+
+```typescript
+list.selectKeys(['row-3', 'row-7']);   // replace selection; unknown keys ignored
+list.addSelectedKeys(['row-9']);       // multi-select modes only
+list.removeSelectedKeys(['row-3']);
+list.selectedKeys;                     // ReadonlySet<string>
+
+list.focusKey('row-7');                // move cursor to an item + scroll into view
+list.tickledKey;                       // key under the cursor, or undefined
+
+list.addEventListener('list-select', ({ detail }) => {
+  console.log([...detail.selectedKeys]);   // carried alongside detail.selected
+});
+```
+
+Restore a selection across a data reload:
+
+```typescript
+const keep = [...list.selectedKeys];
+list.items = await fetchRows();         // Element refs are stale...
+list.selectKeys(keep);                  // ...keys still resolve
+```
+
 ---
 
 ## Interaction modes
@@ -373,13 +426,25 @@ Streaming providers extend columns to the right as batches arrive.
 | `--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-item-padding` | `0 var(--space-xs)` | 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.
 
+To explicitly size columns to the widest visible item, call `fitColumnWidth()`. It
+returns the applied width in pixels and does not run automatically:
+
+```ts
+const width = await list.fitColumnWidth();
+console.log(`Column width: ${width}px`);
+```
+
+The resulting pixel value is set on the element itself and overrides an inherited
+`--detail-list-column-width` value. Lists otherwise continue to use the configured
+CSS variable or the default `220px` width.
+
 ---
 
 ## CSS parts

package/docs-user/grid-list.md

@@ -0,0 +1,274 @@
+# `ixfx-grid-list`
+
+A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
+with selection, keyboard navigation, and captions. Windowed rendering keeps the
+DOM small regardless of item count; the same component does a wrapping grid, a
+single vertical column, or a horizontally-scrolling strip.
+
+---
+
+## Contents
+
+1. [Quick start](#quick-start)
+2. [Items & keys](#items--keys)
+3. [Sizing & layout](#sizing--layout)
+4. [Captions](#captions)
+5. [Orientation](#orientation)
+6. [Selection](#selection)
+7. [Cursor](#cursor)
+8. [Events](#events)
+9. [Keyboard](#keyboard)
+10. [Virtualisation](#virtualisation)
+11. [CSS parts](#css-parts)
+12. [Choosing a list component](#choosing-a-list-component)
+
+---
+
+## Quick start
+
+```html
+<ixfx-grid-list id="grid" selection-mode="single" item-size="120" gap="8">
+  <div class="tile" data-key="a" data-label="Apple">🍎</div>
+  <div class="tile" data-key="b" data-label="Banana">🍌</div>
+  <div class="tile" data-key="c" data-label="Cherry">🍒</div>
+</ixfx-grid-list>
+
+<script type="module">
+  import '@ixfx/components/grid-list';
+
+  const grid = document.querySelector('#grid');
+  grid.addEventListener('list-select', ({ detail }) => {
+    console.log([...detail.selectedKeys]);
+  });
+</script>
+```
+
+Items are **light-DOM children**. Each is projected into its own virtualised
+cell via a named `<slot>`. Add or remove children at any time — a
+`MutationObserver` picks the change up and re-renders.
+
+```typescript
+import type { GridListElement } from '@ixfx/components/grid-list';
+
+const grid = document.querySelector<GridListElement>('#grid')!;
+for (const item of data) {
+  const el = document.createElement('div');
+  el.className = 'tile';
+  el.dataset.key = item.id;
+  el.dataset.label = item.name;
+  el.textContent = item.glyph;
+  grid.appendChild(el);
+}
+```
+
+---
+
+## Items & keys
+
+| Item attribute | Purpose |
+|---|---|
+| `data-key` (or `data-value`) | Stable identity — for key-based selection, `focusKey`, and `visibleKeys()`. Recommended on every item. |
+| `data-label` | Caption text (see [Captions](#captions)). Alternatively put the text in a `[data-grid-list-caption]` descendant. |
+| `not-checked` | Item can't be tickled / checked (skipped by the cursor). |
+| `hidden` | Item is excluded from layout and navigation. |
+
+---
+
+## Sizing & layout
+
+| Property / attribute | Default | Description |
+|---|---|---|
+| `itemSize` / `item-size` | `160` | Cell width in px. Also the square's height for `separate` / `under` / `overlaid` / `hidden`. |
+| `gap` | `8` | Gap between cells, px. |
+| `captionHeight` / `caption-height` | `24` | Height reserved for the caption band in `separate` / `under`. |
+
+Values are clamped and rounded. Changing `item-size` / `gap` re-anchors the
+scroll on the item nearest the viewport centre (zoom stays put rather than
+jumping to the top-left corner).
+
+---
+
+## Captions
+
+`caption-style` — how the caption relates to the content:
+
+| value | layout |
+|---|---|
+| `hidden` | No caption. Cell height = `item-size`. |
+| `separate` | Content in a square; caption a **detached** label below it. Square and caption highlight independently (macOS Finder icon view). |
+| `under` (default) | One box: content on top, caption strip **inside** it below. One selection outline. |
+| `overlaid` | Caption floats over the content. |
+
+`caption-align` — `left` \| `middle` (default) \| `right`. Text alignment; also
+positions the pill in `separate`.
+
+`overlaid` only:
+
+- `caption-position` — `top` \| `middle` \| `bottom` (default).
+- `caption-backdrop` — `scrim` (default, flat translucent panel) \| `gradient`
+  (fades away from the caption edge) \| `blur` (frosted) \| `none` (text +
+  shadow, no panel).
+
+```html
+<ixfx-grid-list caption-style="separate" caption-align="left"></ixfx-grid-list>
+<ixfx-grid-list caption-style="overlaid" caption-position="top" caption-backdrop="gradient"></ixfx-grid-list>
+```
+
+---
+
+## Orientation
+
+`orientation`:
+
+| value | layout | scrolls |
+|---|---|---|
+| `grid` (default) | wraps across as many columns as fit | vertically |
+| `row` | a single row of items | **horizontally** |
+| `column` | a single column of items | vertically |
+
+`row` is the virtualised horizontal strip; `column` is the recommended
+large-list replacement for `ixfx-vertical-list`.
+
+---
+
+## Selection
+
+`selection-mode` (`none` \| `single` \| `multiple`) and `interaction-mode`
+(`standard` \| `implicit` \| `manual` \| `checked` \| `sticky` \| `vscode`) match
+the other list components — see the `ixfx-vertical-list` README for the mode
+table.
+
+### Element API
+
+```typescript
+grid.select(el);              // replace with one item
+grid.selectMany([a, b]);      // selection-mode="multiple" only
+grid.deselect(el);
+grid.clearSelection();
+grid.selectAll();
+grid.selectedItems;           // ReadonlySet<Element>
+```
+
+### Key-based selection
+
+`Element` references die when the item set is rebuilt. With a `data-key` on each
+item, drive selection by key instead — additive, the Element API is unchanged.
+
+```typescript
+grid.selectKeys(['a', 'c']);        // replace; unknown keys ignored
+grid.addSelectedKeys(['b']);        // multi-select modes only
+grid.removeSelectedKeys(['a']);
+grid.selectedKeys;                  // ReadonlySet<string>
+
+grid.addEventListener('list-select', ({ detail }) => {
+  console.log([...detail.selectedKeys]);   // alongside detail.selected
+});
+```
+
+Restore across a reload:
+
+```typescript
+const keep = [...grid.selectedKeys];
+grid.replaceChildren(...(await fetchTiles()));
+grid.selectKeys(keep);
+```
+
+---
+
+## Cursor
+
+The "tickled" cursor follows hover (mouse) or arrow keys (keyboard).
+
+```typescript
+grid.focusKey('b');      // move the cursor to an item and scroll it into view
+grid.tickledKey;         // key under the cursor, or undefined
+```
+
+---
+
+## Events
+
+All bubble and are `composed`.
+
+| Event | Detail | When |
+|---|---|---|
+| `list-select` | `{ selected, previous, selectedKeys }` | Selection changes by any means |
+| `list-activate` | `{ item }` | Double-click or `Enter` on an item |
+| `list-item-click` | `{ item }` | Single click / `Enter` |
+| `list-tickle` | `{ item }` | Cursor moves onto an item |
+| `grid-list-viewport-change` | `{ visibleKeys }` | Scroll, resize, or content change — the rendered window moved |
+
+---
+
+## Keyboard
+
+| Key | `grid` | `row` / `column` |
+|---|---|---|
+| `ArrowLeft` / `ArrowRight` | ∓1 item | ∓1 item |
+| `ArrowUp` / `ArrowDown` | ∓/± one row | ∓1 item |
+| `Home` / `End` | first / last | first / last |
+| `PageUp` / `PageDown` | ± one screen of rows | ± one screen of items |
+| `Enter` | activate | activate |
+| `Space` | toggle selection | toggle selection |
+| `Escape` | clear selection | clear selection |
+| `Ctrl` / `Cmd` + `A` | select all (multi modes) | select all (multi modes) |
+
+---
+
+## Virtualisation
+
+Only the cells in (or near) the viewport are in the DOM.
+
+```typescript
+grid.count;             // total items
+grid.renderedCount;     // cells currently in the shadow DOM
+grid.visibleKeys();     // data-key of items in the current window
+```
+
+`grid-list` handles tens of thousands of children in every orientation.
+
+---
+
+## Scroll fade & insertion animation
+
+The scrollable edge is fade-masked whenever there's more content that way — a
+zero-JS `scroll-timeline` mask (`scroll-fade-y` for `grid` / `column`,
+`scroll-fade-x` for `row`). See `docs/infra-theming.md` → *Scroll Fade*; tune the
+reach with `--scroll-fade-width` (default `30px`).
+
+When the child list changes **mid-list** (not a first populate or a wholesale
+`replaceChildren`), the cells slide to their new position rather than snapping —
+so an inserted item's neighbours make room and a removed item's gap closes — and
+a freshly inserted cell also fades in. The transition is confined to a short
+window after the mutation, so it never fires during scroll virtualisation, and
+it's suppressed under `prefers-reduced-motion: reduce`. Duration:
+`--grid-list-item-move-duration` (default `200ms`).
+
+---
+
+## CSS parts
+
+| Part | Element |
+|---|---|
+| `viewport` | The scroll container |
+| `item` | A cell |
+| `thumb` | The square holding the slotted content |
+| `caption` | The caption element (absent for `caption-style="hidden"`) |
+
+Host CSS custom properties: `--grid-list-item-bg`, `--grid-list-radius`,
+`--grid-list-gap`, `--grid-list-item-move-duration` (insertion animation,
+default `200ms`), `--scroll-fade-width` (edge fade reach, default `30px`), plus
+the shared `--item-bg-*` / `--accent` theme tokens.
+
+---
+
+## Choosing a list component
+
+- **Large lists** — prefer `ixfx-grid-list` with `orientation="column"` over
+  `ixfx-vertical-list`. `vertical-list` renders every child; `grid-list` is
+  windowed.
+- **Small, declarative, richly-slotted lists** — `ixfx-vertical-list` stays the
+  simpler choice.
+- **Horizontal virtualised strip** — `ixfx-grid-list` with `orientation="row"`.
+- **Tabular data with columns / sort / grouping / inline edit** —
+  `ixfx-data-grid`.

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.7.2",
-  "generated": "2026-09-06T14:04:51.476Z",
+  "version": "0.7.4",
+  "generated": "2026-09-08T16:59:30.569Z",
   "components": [
     {
       "name": "ac-text",
@@ -63,6 +63,11 @@
       "summary": "Primitives for typical form layout with responsive label positioning and data binding.",
       "path": "docs-user/form.md"
     },
+    {
+      "name": "grid-list",
+      "summary": "A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —",
+      "path": "docs-user/grid-list.md"
+    },
     {
       "name": "grouped-item-lister",
       "summary": "A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own",
@@ -235,6 +240,10 @@
     }
   ],
   "overviews": [
+    {
+      "name": "infra-tickled.md",
+      "path": "docs-user/infra-tickled.md"
+    },
     {
       "name": "user-catalog.md",
       "path": "docs-user/user-catalog.md"

package/docs-user/infra-tickled.md

@@ -0,0 +1,163 @@
+# Tickled items
+
+An item is **tickled** when it is under active attention — pointer hovering over it, or keyboard cursor on it. Only one item is tickled at a time — a single logical cursor regardless of input mechanism.
+
+**Tickled state is controlled via the `.tickled` CSS class** (applied by `TickledController`). The `tickledItemStyles` provides base styling that all tickled components should use.
+
+---
+
+## TickledController
+
+`TickledController` is a Lit `ReactiveController` from `src/interaction/index.js` that manages this state for you.
+
+### Direct-render setup (items in your template)
+
+```ts
+import { TickledController, tickledStyles, tickledItemStyles } from '../interaction/index.js';
+
+class MyList extends LitElement {
+  static override styles = [
+    tickledStyles,
+    tickledItemStyles,
+    css`
+      .item.selected { background: var(--item-bg-selected); }
+    `
+  ];
+
+  private tickled = new TickledController(this, {
+    getItems: () => this.items.map((_, i) => ({ id: i })),
+  });
+
+  protected override render() {
+    return html`
+      <div
+        data-input-mode=${this.tickled.inputMode}
+        @pointerleave=${() => this.tickled.clearTickled()}
+        @keydown=${this.#handleKeyDown}
+      >
+        ${this.items.map((item, i) => html`
+          <div
+            class="item ${this.tickled.isTickled(i) ? 'tickled' : ''}"
+            @pointerenter=${() => this.tickled.handlePointerEnter(i)}
+          >${item}</div>
+        `)}
+      </div>
+    `;
+  }
+
+  #handleKeyDown(e: KeyboardEvent) {
+    if (e.key === 'ArrowDown') { e.preventDefault(); this.tickled.handleKeyboardNavigation('next'); }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); this.tickled.handleKeyboardNavigation('previous'); }
+    else if (e.key === 'Home') { e.preventDefault(); this.tickled.handleKeyboardNavigation('first'); }
+    else if (e.key === 'End') { e.preventDefault(); this.tickled.handleKeyboardNavigation('last'); }
+  }
+}
+```
+
+### Slotted-content setup
+
+Lit's reactive rendering doesn't touch slotted elements, so you must sync DOM classes manually via `onStateChange`.
+
+```ts
+private tickled = new TickledController<number>(this, {
+  getItems: () => this._slottedItems().map((_, i) => ({ id: i })),
+  onStateChange: () => this._syncTickled(),
+});
+
+// Must run in willUpdate so :host gets data-input-mode before paint
+override willUpdate(changed: Map<PropertyKey, unknown>) {
+  super.willUpdate(changed);
+  this.setAttribute('data-input-mode', this.tickled.inputMode);
+}
+
+private _slottedItems(): HTMLElement[] {
+  const slot = this.shadowRoot?.querySelector('slot');
+  return Array.from(slot?.assignedElements() ?? []) as HTMLElement[];
+}
+
+private _syncTickled() {
+  this._slottedItems().forEach((item, i) => {
+    const isTickled = this.tickled.isTickled(i);
+    if (isTickled && this.tickled.inputMode === 'keyboard') {
+      item.classList.add('tickled');
+    } else {
+      item.classList.remove('tickled');
+    }
+    item.tabIndex = isTickled ? 0 : -1;
+  });
+}
+```
+
+For slotted content, set `data-input-mode` on `:host` (not on an inner div) so `tickledStyles` CSS variables cascade through the shadow boundary to slotted elements.
+
+---
+
+## CSS variable contract
+
+All `--item-*` state variables are defined in `src/style.css` (the theme). `tickledItemStyles` applies them to `.item` elements — it no longer sets defaults of its own for the colour/state variables.
+
+See [infra-theming.md](./infra-theming.md#item-states) for the full variable listing and their theme values.
+
+The layout variables (`--item-padding`, `--item-border-radius`, `--item-icon-spacing`, `--item-bg`) are also defined in `style.css` with defaults derived from the spacing/radius tokens.
+
+## Base item styles
+
+`tickledItemStyles` provides these base styles:
+
+```css
+.item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--item-icon-spacing);
+  padding: var(--item-padding);
+  background: var(--item-bg);
+  border: var(--item-border);
+  border-radius: var(--item-border-radius);
+  transition: background var(--transition), border-color var(--transition);
+}
+
+.item.tickled {
+  background: var(--item-bg-tickled);
+  border-color: var(--item-border-tickled);
+  color: var(--item-text-tickled);
+}
+
+.item.selected {
+  background: var(--item-bg-selected);
+  border-color: var(--item-border-selected);
+  color: var(--item-text-selected);
+}
+
+.item.selected.tickled {
+  background: var(--item-bg-selected-tickled);
+  outline: 2px dashed var(--surface-3);
+  outline-offset: -2px;
+}
+```
+
+---
+
+## Controller API
+
+**Constructor:** `new TickledController<T>(host, config)`
+
+Config:
+- `getItems: () => readonly { id: T; enabled?: boolean }[]` — called on each render
+- `onStateChange?: () => void` — fired after every state mutation (required for slotted content)
+- `onTickle?: (id: T | undefined) => void` — called only when the tickled id *changes* (useful for opening submenus)
+- `initialInputMode?: 'keyboard' | 'mouse'`
+
+Properties: `inputMode`, `tickledId`
+
+Methods: `isTickled(id)`, `handlePointerEnter(id)`, `handleKeyboardNavigation('next'|'previous'|'first'|'last'|T)`, `clearTickled()`, `setTickled(id)`, `setInputMode(mode)`
+
+---
+
+## Checklist
+
+- [ ] `tickledStyles` and `tickledItemStyles` included in `static styles`
+- [ ] Components use `tickledItemStyles` base styles, override only for component-specific needs
+- [ ] `data-input-mode` set on the correct element (container div for direct-render; `:host` via `willUpdate` for slotted)
+- [ ] `@pointerenter` on each item, `@pointerleave` on container
+- [ ] Keyboard navigation calls `handleKeyboardNavigation`
+- [ ] Slotted components: `onStateChange` + `_syncTickled()` implemented; `.tickled` class only added in keyboard mode