@ixfx/components 0.11.4 → 0.11.5

package/docs-user/detail-list.md

@@ -155,6 +155,9 @@ list.keyProperty = 'name'; // Preserves selection across rebuilds
 | `displayProperty` | `string` | Property name to use as label |
 | `keyProperty` | `string` | Property name for stable identity |
 | `iconProperty` | `string` | Property name for icon name |
+| `iconColorProperty` | `string` | Property name for the icon's CSS colour |
+| `textColorProperty` | `string` | Property name for the caption's CSS colour |
+| `badgeProperty` | `string` | Property name for a Finder-style badge |
 | `formatter` | `(item: unknown, index: number) => string \| Node` | Custom renderer |
 
 ```typescript
@@ -170,6 +173,49 @@ Retrieve the original data for an element:
 const data = list.getItemData(liElement);
 ```
 
+### Per-item icon colour, text colour and badges
+
+Three more property-name lookups, in the same idiom as `iconProperty`: each
+names the property on the item object that carries the value.
+
+| Property | Applies to | Value |
+|---|---|---|
+| `icon-color-property` | the injected `<ixfx-icon>` | a CSS colour string |
+| `text-color-property` | the caption | a CSS colour string |
+| `badge-property` | a right-justified slot after the caption | anything Lit can render, or a DOM `Node` |
+
+```typescript
+list.displayProperty = `name`;
+list.iconProperty = `icon`;
+list.iconColorProperty = `iconColor`;
+list.textColorProperty = `textColor`;
+list.badgeProperty = `badge`;
+list.items = [
+  { name: `Report.pdf`, icon: `file`, badge: tagChip(`orange`) },
+  { name: `Overdue.txt`, textColor: `crimson` },
+];
+```
+
+Icons paint from `currentColor`, so `iconColor` recolours the glyph. Both
+colours are applied inline, which means they also win over the selected /
+tickled text colours — pick something legible against both, or leave them off
+and let the component's theming handle selection contrast.
+
+`undefined`, `null`, `''` and `false` all count as "not supplied", so a badge
+can be made conditional without rebuilding the collection:
+
+```typescript
+list.badgeProperty = `badge`;   // rows without a tag simply have no badge
+```
+
+Changing any of these properties (or `items`, `formatter`, `displayProperty`,
+`iconProperty`, `keyProperty`) rebuilds the rows.
+
+The badge lands as a `<span class="item-badge">` in the row's light DOM, with
+its layout applied as inline styles — a `::slotted()` rule can't reach inside a
+slotted `<li>`. Drive it from `--detail-list-badge-gap` (or override with
+`!important`). The icon's own gap is `--detail-list-icon-gap`.
+
 ---
 
 ## Properties

package/docs-user/grid-list.md

@@ -340,6 +340,10 @@ grid.itemAdapter = {
   render: f => html`<img src=${f.thumb} loading="lazy" decoding="async">`,
   disabled: f => f.locked,                   // optional — not selectable / tickle-able
   searchableText: f => `${f.name} ${f.ext}`, // optional — search haystack
+  icon: f => fileIcon(f.ext),                // optional — above the cell content
+  iconColor: f => f.tint,                    // optional — CSS colour for that icon
+  textColor: f => f.textTint,                // optional — CSS colour for the caption
+  badge: f => f.tag && tagChip(f.tag),       // optional — inline, before the name
 };
 grid.items = files;                          // readonly FileRecord[]
 ```
@@ -353,6 +357,45 @@ don't rebuild it each host render. Assigning a new `itemAdapter` reference makes
 the grid reconstruct its data source, which is wasteful for a streaming
 collection.
 
+#### Per-item icon, colours and badges
+
+The four optional appearance functions are the Finder-style per-item hooks:
+
+| Function | Renders |
+|---|---|
+| `icon(item, index)` | Inside a sized, centred slot **above** the cell's content. Anything Lit can render. |
+| `iconColor(item, index)` | `color` on that slot. Glyphs painting from `currentColor` are recoloured. |
+| `textColor(item, index)` | `color` on the cell's caption. |
+| `badge(item, index)` | A Finder-style badge, **inline at the head of the caption**, before the filename. |
+
+```typescript
+import { html } from 'lit';
+import { tagChip, stackedTagChips } from './my-tags.js';
+
+grid.itemAdapter = {
+  key: f => f.path,
+  label: f => f.name,
+  render: f => html`<img src=${f.thumb} loading="lazy">`,
+  icon: f => html`<ixfx-icon name="file" style="width:100%;height:100%"></ixfx-icon>`,
+  iconColor: f => f.tint,
+  textColor: f => (f.overdue ? 'crimson' : undefined),
+  badge: f => (f.tags.length > 1 ? stackedTagChips(f.tags) : tagChip(f.tags[0])),
+};
+```
+
+`undefined`, `null`, `''` and `false` all count as "not supplied", so a hook
+can be made conditional without touching the collection. Both colours are
+applied inline, which means they also win over the selected / tickled caption
+colours — pick something legible against both, or leave them off and let the
+component's theming handle selection contrast.
+
+Element mode needs none of this: you own the light-DOM markup, so set the
+colours yourself and put the badge markup wherever you want it.
+
+CSS: `--grid-list-icon-size`, `--grid-list-icon-gap`, `--grid-list-badge-gap`.
+
+Parts: `part="icon"` and `part="badge"` on the wrappers this adds.
+
 | Method | Effect |
 |---|---|
 | `setItems(items)` | Replace the collection. Selection / cursor keep any key still present. |
@@ -425,11 +468,15 @@ it's suppressed under `prefers-reduced-motion: reduce`. Duration:
 | `content` | The rendered content wrapper (data mode) |
 | `thumb` | The square holding the slotted content (element mode) |
 | `caption` | The caption element (absent for `caption-style="hidden"`) |
+| `icon` | The per-item icon wrapper (data mode, when the adapter's `icon` returns something) |
+| `badge` | The per-item badge wrapper (data mode, when the adapter's `badge` returns something) |
 
 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.
+default `200ms`), `--scroll-fade-width` (edge fade reach, default `30px`),
+`--grid-list-icon-size` / `--grid-list-icon-gap` / `--grid-list-badge-gap`
+(per-item appearance, data mode), plus the shared `--item-bg-*` / `--accent`
+theme tokens.
 
 ### Thumbnail well (Finder-style selection)
 

package/docs-user/hyperbolic-tree.md

@@ -11,15 +11,16 @@ It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](.
 1. [Differences from `ixfx-tree-list`](#differences-from-ixfx-tree-list)
 2. [Data model](#data-model)
 3. [Properties](#properties)
-4. [Zoom vs. curvature](#zoom-vs-curvature)
-5. [Weighting](#weighting)
-6. [Targeting a specific node or edge](#targeting-a-specific-node-or-edge)
-7. [Custom edge rendering](#custom-edge-rendering)
-8. [Focus, selection, navigation](#focus-selection-navigation)
-9. [Events](#events)
-10. [Keyboard / pointer interaction](#keyboard--pointer-interaction)
-11. [CSS variables and parts](#css-variables-and-parts)
-12. [Types reference](#types-reference)
+4. [Node shapes](#node-shapes)
+5. [Zoom vs. curvature](#zoom-vs-curvature)
+6. [Weighting](#weighting)
+7. [Targeting a specific node or edge](#targeting-a-specific-node-or-edge)
+8. [Custom edge rendering](#custom-edge-rendering)
+9. [Focus, selection, navigation](#focus-selection-navigation)
+10. [Events](#events)
+11. [Keyboard / pointer interaction](#keyboard--pointer-interaction)
+12. [CSS variables and parts](#css-variables-and-parts)
+13. [Types reference](#types-reference)
 
 ---
 
@@ -36,6 +37,8 @@ It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](.
 
 Same `TreeNode` / `TreeItem` shapes as the rest of the tree family (see [`src/tree/README.md`](../tree/README.md#data-model)), including `root`, `model` (`TreeDataModel`), and `loadChildren` for lazy loading.
 
+Keys only need to be unique **among siblings**: internally each node is identified by its key *path* from the root (`HyperbolicLayoutNode.id`), so data like a file system — where `readme.md` recurs in many folders — lays out and focuses correctly. Key-based lookups that can't know the path (`focusedKey` when given a bare key, `revealKey`, `::part(node-<key>)`) match the first node, depth-first, carrying that key.
+
 ```typescript
 el.root = {
   item: { key: 'root', label: 'My Files' },
@@ -58,12 +61,20 @@ el.root = {
 | `exclusivity` | `TreeExclusivity` | `'none'` | Accepted for interface compatibility, ignored |
 | `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Non-matching nodes (and branches with no matching descendant) are dimmed, not hidden |
 | `maxRadius` (`max-radius`) | `number` | `4` | Tree-graph steps from the focus to lay out and render |
-| `nodeRadius` (`node-radius`) | `number` | `0.05` | Base node dot radius, as a fraction of the disk radius |
+| `nodeShape` (`node-shape`) | `'dot' \| 'box'` | `'dot'` | How nodes are drawn. See [Node shapes](#node-shapes) |
+| `boxMaxChars` (`box-max-chars`) | `number` | `24` | `box` mode: truncate longer labels with `…` (`0` disables) |
+| `minLabelSize` (`min-label-size`) | `number` | `9` | `box` mode: smallest on-screen label size (CSS px) worth drawing; smaller labels become markers |
+| `colorByBranch` (`color-by-branch`) | `boolean` | `false` | Tint each top-level branch (each child of the root, and its subtree) its own hue. See [Branch colours](#branch-colours) |
+| `nodeRadius` (`node-radius`) | `number` | `0.05` | Base node dot radius at the disk center, as a fraction of the disk radius. Shrinks by the disk's conformal factor `1 − \|z\|²` away from the focus, and is capped to stay clear of the nearest neighbouring node |
 | `minNodeRadius` (`min-node-radius`) | `number` | `0.015` | Nodes whose scaled radius falls below this render without a label |
 | `minWeightScale` (`min-weight-scale`) | `number` | `0.6` | Radius multiplier for a node with `weight` at the low end of the currently-visible range |
 | `maxWeightScale` (`max-weight-scale`) | `number` | `1.6` | Radius multiplier for a node with `weight` at the high end of the currently-visible range |
-| `zoom` | `number` | `1` | Post-layout SVG magnification, centered on the focus. See [Zoom vs. curvature](#zoom-vs-curvature) |
+| `zoom` | `number` | `1` | Post-layout (Euclidean) magnification; updated by zoom gestures. See [Zoom vs. curvature](#zoom-vs-curvature) |
 | `curvature` | `number` | `1` | Hyperbolic distance placed between generations — how curved the space itself is. See [Zoom vs. curvature](#zoom-vs-curvature) |
+| `disableZoomGestures` (`disable-zoom-gestures`) | `boolean` | `false` | Turn off zoom gestures — see [Zoom gestures](#zoom-gestures) |
+| `disableRadialLabels` (`disable-radial-labels`) | `boolean` | `false` | Turn off radial labels — every label horizontal. See [Label legibility](#label-legibility) |
+| `disableChildPreview` (`disable-child-preview`) | `boolean` | `false` | Turn off the hover preview of a crowded node's children — see [Child preview](#child-preview) |
+| `siblingSpacing` (`sibling-spacing`) | `number` | `0.5` | Minimum hyperbolic distance between adjacent siblings — see [Crowded fans](#crowded-fans). `0` disables |
 | `focusAnimationDuration` (`focus-animation-duration`) | `number` | `400` | Duration (ms) of the animated re-center on focus change; `0` snaps instantly. Respects `prefers-reduced-motion` |
 | `edgeRenderer` | `HyperbolicEdgeRenderer \| undefined` | `undefined` | Custom renderer for edges, in place of the default geodesic-arc path |
 | `disableKeyboardNavigation` (`disable-keyboard-navigation`) | `boolean` | `false` | Disables the keyboard handlers below |
@@ -74,6 +85,60 @@ el.root = {
 
 ---
 
+## Node shapes
+
+| `nodeShape` | Rendering |
+|---|---|
+| `'dot'` (default) | A filled circle with the label beside it. Labels are greedily thinned where nodes crowd together |
+| `'box'` | A rectangle containing the label, centered on the node. The box scales with the disk's conformal factor (`1 − \|z\|²`), floored at 45% so nearby rings stay readable |
+
+```html
+<ixfx-hyperbolictree-list node-shape="box"></ixfx-hyperbolictree-list>
+```
+
+### Label legibility
+
+Both shapes place labels greedily: the focus first, then selected nodes, then larger (nearer-the-center) nodes. A label is dropped if it would overlap an already-placed one by more than 3% of its area, or — in `box` mode — if it would render below `minLabelSize` px. A box without a label is drawn as a small marker. Hovering (or keyboard-tickling) any node always shows its label, drawn on top, and every node has its full label as a native tooltip.
+
+`--hyperbolictree-font-size` is in **screen px**: the component converts it using its own rendered size, so text is the same size however large the element is. It also stays constant under `zoom`, so zooming in spreads crowded labels apart until they fit, rather than magnifying the overlap.
+
+**Radial labels** (on by default; `disable-radial-labels` turns them off): each label runs along its node's incoming edge, from the neighbour one step nearer the focus. A fan of siblings then only needs room for each label's *height*, not its width, so far more of a crowd stays labelled. Labels on the left half are turned 180° so text never reads upside-down. The focus itself stays horizontal.
+
+### Zoom gestures
+
+On by default; `disable-zoom-gestures` turns them all off. Each one zooms around the pointer, like a map, and updates `zoom`:
+
+| Gesture | When |
+|---|---|
+| Trackpad pinch / Ctrl-⌘-scroll | Whenever the pointer is over the tree |
+| Plain scroll | Only once the tree has keyboard focus (click it first), so scrolling the page past it isn't hijacked. This follows the library's focus-gated wheel convention |
+| Two-finger touch pinch | On empty disk space |
+
+Labels keep their on-screen size while zooming, so zooming in spreads a crowd apart. Boxes that were shrunk towards the edge grow back towards full size, until their labels are legible. Focusing a node pans a zoomed view back so the new focus lands in the middle of the element.
+
+### Child preview
+
+On by default; `disable-child-preview` turns it off. Hovering or keyboard-tickling a node whose children aren't all legible opens a popover listing them. That means some children had their labels culled, or sit beyond `maxRadius`. It shows up to 12 children, then "+N more". Clicking an entry focuses that child and selects it, per `interactionMode`. The popover stays open while the pointer moves onto it, and Escape closes it. Style it with `::part(child-preview)`. Nodes that can show a preview drop their native `<title>` tooltip so the two don't stack. With the preview disabled, every node keeps its tooltip.
+
+### Crowded fans
+
+Panning is a hyperbolic *isometry*: it moves nodes to where the disk magnifies more, but it can never change the hyperbolic distance between them. So if a bushy node's children were laid out nearly on top of each other, no amount of dragging would separate them.
+
+`siblingSpacing` guarantees a minimum hyperbolic distance between adjacent siblings. A child with a thin angular slice is placed further from its parent: `sinh(L) = sinh(spacing/2) / sin(slice/2)`, never less than `curvature`. In the overview, a crowd sits further out, as a neat fan of markers rather than a pile. Dragging it towards the center always spreads it out until the labels fit. Raise `siblingSpacing` if your labels are long and still collide when centered. Lower it to keep crowds closer in the overview.
+
+### Branch colours
+
+`color-by-branch` spreads hues evenly around the colour wheel, one per child of the root, and mixes each into the normal node, box and edge colours. Mixing rather than replacing keeps it in step with the theme, and selected/tickled states still override it. Each node and edge carries `--branch-index` and `--branch-count` (unset on the root) for custom CSS, and these knobs tune the palette:
+
+| Variable | Default |
+|---|---|
+| `--hyperbolictree-branch-hue-start` | `250` |
+| `--hyperbolictree-branch-chroma` | `0.13` |
+| `--hyperbolictree-branch-lightness` | `62%` |
+| `--hyperbolictree-branch-mix` | `55%` |
+
+Style boxes via `--hyperbolictree-box-color` / `--hyperbolictree-box-text` / `--hyperbolictree-box-border`, or `::part(box)` directly.
+
 ## Zoom vs. curvature
 
 Two independent knobs affect how much of the tree is visible and how it's magnified — neither mutates `root`:
@@ -81,7 +146,7 @@ Two independent knobs affect how much of the tree is visible and how it's magnif
 | | What it changes | Effect |
 |---|---|---|
 | `zoom` | A post-layout SVG `scale()`, applied after everything else | Uniformly magnifies/shrinks the rendered disk around the focus. Node positions relative to each other are unchanged — it's a camera zoom, not a re-layout. |
-| `curvature` | The hyperbolic distance placed between each generation (default `1`, matching the standard Poincaré-disk layout) | Raising it pushes each generation further out in hyperbolic terms, so the disk's own `tanh` compression crowds distant generations toward the boundary faster — a stronger fisheye. This *reshapes* the layout (relative sizes/spacing of near vs. far nodes change), which is why increasing it reads as "zooming in" on the focus even at `zoom: 1`. Lowering it spreads generations out more evenly, flattening the view toward a Euclidean-feeling layout. |
+| `curvature` | The minimum hyperbolic distance placed between each generation (default `1`, matching the standard Poincaré-disk layout; bushy nodes' children go further — see `siblingSpacing`) | Raising it pushes each generation further out in hyperbolic terms, so the disk's own `tanh` compression crowds distant generations toward the boundary faster — a stronger fisheye. This *reshapes* the layout (relative sizes/spacing of near vs. far nodes change), which is why increasing it reads as "zooming in" on the focus even at `zoom: 1`. Lowering it spreads generations out more evenly, flattening the view toward a Euclidean-feeling layout. |
 | `maxRadius` | How many tree-graph rings are laid out at all | Independent of both — a window over the tree, not a projection change. |
 
 ```html
@@ -204,7 +269,7 @@ All events **bubble** and are **composed**.
 
 ## Keyboard / pointer interaction
 
-The element must be focused before keyboard navigation works (`disableKeyboardNavigation` turns it off entirely).
+The element must be focused before keyboard navigation works (`disableKeyboardNavigation` turns it off entirely). Any pointer interaction — pressing a node, or starting a pan — moves keyboard focus to the tree, so you can follow a click or drag straight away with the arrow keys.
 
 | Key | Action |
 |---|---|
@@ -214,7 +279,11 @@ The element must be focused before keyboard navigation works (`disableKeyboardNa
 | `Enter` | Select (unless `interactionMode="manual"`) and activate the focused node |
 | `Escape` | Return focus to the root |
 
-Pointer: click a node to focus (and select, per `interactionMode`) it; drag empty disk space to pan.
+Pointer: click a node to focus (and select, per `interactionMode`) it; drag empty disk space to pan. Panning is a true hyperbolic translation — the grabbed point tracks the pointer and the tree never distorts. Focusing a node animates it to the center along the geodesic, keeping the current orientation (no spin).
+
+Any pointer interaction also moves keyboard focus to the tree — see [Keyboard / pointer interaction](#keyboard--pointer-interaction). Ctrl/⌘-scroll or pinch zooms; see [Zoom gestures](#zoom-gestures).
+
+Positions are always computed outward from the focus, one parent→child hop at a time, never from root-anchored coordinates. Root-anchored coordinates run out of floating-point precision about 14 hyperbolic units from the root (depth 5 at `curvature` 3), where whole subtrees would collapse onto one point. Focus-relative positions stay exact however deep you browse.
 
 ## CSS variables and parts
 
@@ -224,7 +293,10 @@ Pointer: click a node to focus (and select, per `interactionMode`) it; drag empt
 | `--hyperbolictree-node-text` | `var(--surface-3-text)` | Label text colour |
 | `--hyperbolictree-edge-color` | `var(--surface-6)` | Edge stroke colour |
 | `--hyperbolictree-boundary-color` | `var(--border-subtle)` | Disk boundary stroke colour |
-| `--hyperbolictree-font-size` | `25px` | Label font size |
+| `--hyperbolictree-font-size` | `13px` | Label font size in screen px (in `box` mode, the size at the focus) |
+| `--hyperbolictree-box-color` | `var(--hyperbolictree-node-color)` | `box` mode fill |
+| `--hyperbolictree-box-text` | `var(--surface-4-text)` | `box` mode label colour. Selected/tickled boxes use `--item-text-selected` / `--item-text-tickled`, paired with their `--item-bg-*` fills |
+| `--hyperbolictree-box-border` | `var(--surface-2)` | `box` mode border |
 | `--node-weight` / `--node-weight-raw` | — | See [Weighting](#weighting) |
 | `--edge-weight` | — | See [Weighting](#weighting) |
 
@@ -234,9 +306,11 @@ Pointer: click a node to focus (and select, per `interactionMode`) it; drag empt
 | `edges` / `nodes` | Group wrappers | |
 | `edge`, `edge-to-<key>`, `edge-from-<key>` | Each edge `<path>` | See [Targeting a specific node or edge](#targeting-a-specific-node-or-edge) |
 | `node`, `node-<key>` | Each node `<g>` | |
-| `hit` | Invisible larger hit-target circle per node | |
-| `dot` | The visible node circle | |
+| `hit` | Invisible larger hit-target circle per node | `dot` mode only |
+| `dot` | The visible node circle | `dot` mode only |
+| `box` | The node rectangle | `box` mode only |
 | `label` | Node label `<text>` | |
+| `child-preview` | The hover popover listing a crowded node's children | See [Child preview](#child-preview) |
 
 ---
 
@@ -245,6 +319,8 @@ Pointer: click a node to focus (and select, per `interactionMode`) it; drag empt
 ```typescript
 type HyperbolicInteractionMode = 'implicit' | 'standard' | 'manual';
 
+type HyperbolicNodeShape = 'dot' | 'box';
+
 type HyperbolicFocusDetail = {
   readonly node: TreeNode;
   readonly previous: TreeNode | undefined;
@@ -260,10 +336,12 @@ type HyperbolicEdgeRenderer = (context: HyperbolicEdgeRenderContext) => unknown;
 
 type HyperbolicLayoutNode = {
   readonly node: TreeNode;
-  readonly key: string;
+  readonly key: string;          // node.item.key — may repeat across branches
+  readonly id: string;           // key-path id, unique across the tree
   readonly depth: number;        // absolute depth from the true root
   readonly ring: number;         // tree-graph steps from the focus (0 = focus itself)
   readonly parentKey: string | undefined;
+  readonly parentId: string | undefined;
   readonly position: Point;      // Poincaré-disk position, focus projected to the origin
   readonly angularShare: number; // angular width (radians) allocated by the parent's partition
   readonly weight: number | undefined;
@@ -273,6 +351,8 @@ type HyperbolicLayoutNode = {
 type HyperbolicLayoutEdge = {
   readonly fromKey: string;
   readonly toKey: string;
+  readonly fromId: string;
+  readonly toId: string;
   readonly from: Point;
   readonly to: Point;
   readonly weightNormalized: number; // average of the two endpoints'

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.11.4",
-  "generated": "2026-09-27T21:46:20.636Z",
+  "version": "0.11.5",
+  "generated": "2026-09-28T21:16:07.854Z",
   "components": [
     {
       "name": "ac-text",

package/docs-user/miller.md

@@ -37,6 +37,8 @@ These can be overridden in your CSS:
 | `--item-hover-bg` | `var(--item-bg-tickled)` | Background on item hover |
 | `--item-selected-bg` | `var(--item-bg-selected)` | Background of selected item |
 | `--item-selected-text` | `var(--item-text-selected)` | Text color of selected item |
+| `--miller-list-badge-gap` | `0.5em` | Space between a per-item label and its right-justified badge |
+| `--icon-size` / `--icon-spacing` | `1em` / `0.3em` | Per-item icon size and gap |
 
 Inherited from theme:
 - `--font-family` - Font family
@@ -165,13 +167,16 @@ el.clearSelection(): void
 
 ```typescript
 type MillerItem = {
-  key: string;        // Unique identifier
-  label: string;      // Display text
-  isLeaf?: boolean;   // If true, clicking never fires 'expand'
-  data?: unknown;     // Arbitrary user data
-  icon?: string;      // Optional icon name
-  tooltip?: string;   // Optional tooltip text
-  value?: string;     // Optional string value
+  key: string;           // Unique identifier
+  label: string;         // Display text
+  isLeaf?: boolean;      // If true, clicking never fires 'expand'
+  data?: unknown;        // Arbitrary user data
+  icon?: string;         // Optional icon name
+  iconColor?: string;    // Optional CSS colour for the icon
+  textColor?: string;    // Optional CSS colour for the label
+  badge?: unknown;       // Optional Finder-style badge (anything Lit can render)
+  tooltip?: string;      // Optional tooltip text
+  value?: string;        // Optional string value
 };
 
 type MillerNode = {
@@ -184,6 +189,46 @@ type MillerConfig = {
 };
 ```
 
+### Per-item icon colour, text colour and badges
+
+`iconColor` and `textColor` are plain CSS colour strings; the icon paints from
+`currentColor`, so `iconColor` recolours the glyph. `badge` is anything Lit
+can render — a `TemplateResult`, a DOM `Node`, or a string — and shows up
+right-justified on the row, after the name and before the expand caret, the
+way Finder's list view shows colour tags.
+
+```typescript
+import { html } from 'lit';
+import { tagChip, stackedTagChips } from './my-tags.js';   // your own SVGs
+
+el.root = {
+  item: { key: 'root', label: 'Documents' },
+  children: [
+    { item: { key: 'a', label: 'Archive.zip', icon: 'file', badge: tagChip('orange') } },
+    {
+      item: {
+        key: 'b',
+        label: 'Overdue.txt',
+        icon: 'file',
+        iconColor: 'var(--accent)',
+        textColor: 'crimson',
+        badge: stackedTagChips(['red', 'yellow']),
+      },
+    },
+  ],
+};
+```
+
+Colours are applied inline, so they also win over the selected / tickled text
+colours — pick something legible against both, or leave them off and let the
+component's theming handle selection contrast. `undefined`, `null`, `''` and
+`false` all count as "not supplied", so a badge can be made conditional.
+
+The badge renders as `<span class="item-badge" part="badge">`, so
+`::part(badge)` works from outside the component.
+
+CSS: `--miller-list-badge-gap`.
+
 ---
 
 ## Basic Usage

package/docs-user/vertical-list.md

@@ -122,9 +122,69 @@ To reflect selection state inside the custom element's shadow DOM, target the `:
 | `itemHeight` / `item-height` | `number` | `0` | Fixed row height in px. Required for `virtualize` — every row must be exactly this tall |
 | `filterPredicate` | `((el: Element) => boolean) \| undefined` | `undefined` | External filter; only items returning `true` are shown |
 | `checkboxRenderer` | `((checked: boolean) => unknown) \| CustomCheckboxOptions \| undefined` | `undefined` | Custom content for the checkbox in `checked` mode. See [Custom checkbox](#custom-checkbox) |
+| `formatter` | `((item: unknown, index: number) => unknown) \| undefined` | `undefined` | Renders one `items` entry into its row. See [Adapter items](#adapter-items) |
+| `keyProperty` / `key-property` | `string` | `''` | Property on each `items` entry used for stable identity |
+| `icon` | `((item, index) => unknown) \| undefined` | `undefined` | Per-item icon, prepended to the row |
+| `iconColor` | `((item, index) => string \| undefined) \| undefined` | `undefined` | CSS colour for that icon |
+| `textColor` | `((item, index) => string \| undefined) \| undefined` | `undefined` | CSS colour for the row's text |
+| `badge` | `((item, index) => unknown) \| undefined` | `undefined` | Finder-style badge, right-justified on the row |
 
 Switching `interactionMode` always clears the current selection.
 
+### Adapter items
+
+Set `items` and the list builds one `<li>` per entry, resolving each row
+through the function-valued properties above. This is the only mode the
+per-item appearance hooks apply to — declarative and programmatic elements
+already own their own markup.
+
+```typescript
+import { html } from 'lit';
+import { tagChip, stackedTagChips } from './my-tags.js';   // your own SVGs
+
+list.keyProperty = 'name';
+list.formatter = item => (item as File).name;
+list.icon = item => fileIcon((item as File).ext);
+list.iconColor = item => (item as File).tint;
+list.textColor = item => (item as File).overdue ? 'crimson' : undefined;
+list.badge = item => {
+  const { tags } = item as File;
+  return tags.length > 1 ? stackedTagChips(tags) : tagChip(tags[0]);
+};
+list.items = files;
+```
+
+- `icon` is prepended to the row in a fixed-size slot; `iconColor` sets that
+  slot's `color`, so glyphs painting from `currentColor` are recoloured.
+- `textColor` is applied to the row itself.
+- `badge` is appended after the text; the row is already a flex row, so the
+  badge self-justifies to the trailing edge.
+
+Both colours are applied inline, so they also win over the selected / tickled
+text colours — pick something legible against both, or leave them off and let
+the component's theming handle selection contrast. `undefined`, `null`, `''`
+and `false` all count as "not supplied", so a hook can be made conditional
+without touching `items`. Changing any of these rebuilds the rows.
+
+All four hooks are skipped when `formatter` returns a full row element (an
+`<li>`, a `[data-list-item]`, or a custom element) — that element owns its own
+markup. See [Item types](#item-types).
+
+The icon and badge land as `<span class="item-icon">` / `<span class="item-badge">`
+in the row's light DOM. Their layout is applied as inline styles — a
+`::slotted()` rule can't reach inside a slotted `<li>` — so override it with
+`!important`, or (better) drive it from the CSS variables above:
+
+```css
+#list-look {
+  --list-item-icon-size: 18px;
+  --list-item-badge-gap: 12px;
+}
+```
+
+Parts: none for these two; they are light-DOM elements you can style with your
+own selectors.
+
 ### `interactionMode`
 
 | Value | Behaviour |
@@ -654,6 +714,9 @@ dispatch. Mirrors `ixfx-grid-list`'s `grid-list-viewport-change`.
 | `--list-radius` | `var(--radius-s)` | Border radius |
 | `--list-item-height` | `28px` | Minimum row height for `<li>` items; set it to match `item-height` when virtualizing |
 | `--list-item-padding` | `4px var(--space-m, 8px)` | Padding for `<li>` items |
+| `--list-item-icon-size` | `1em` | Size of the adapter-mode per-item icon |
+| `--list-item-icon-gap` | `6px` | Space between the adapter-mode icon and the row text |
+| `--list-item-badge-gap` | `8px` | Space between the row text and a right-justified adapter-mode badge |
 | `--item-bg-tickled` | `rgba(0,0,0,0.06)` | Row background when cursor is on it |
 | `--item-bg-selected` | `rgba(25,118,210,1)` | Selected row background |
 | `--item-text-selected` | `#fff` | Selected row text colour |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",

package/dist/data-grid-CfiaBqTA.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"data-grid-CfiaBqTA.d.ts","names":[],"sources":["../src/data-grid/types.ts","../src/data-grid/data-grid.ts"],"mappings":"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"}

package/dist/detail-list-DxQZkK-C.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"detail-list-DxQZkK-C.d.ts","names":[],"sources":["../src/detail-list/types.ts","../src/detail-list/detail-list.ts"],"mappings":";;;;;;;;;;;KACY;;KAGA;WACD,SAAS;WACT;WACA;;;KAIC,wBAAwB,GAAG,gBAAgB,GAAG;;KAG9C,mBAAmB,eAAe,2BAA2B;;;;;;;;;;;;;;;;;;;;cCqH5D,0BAA0B;;EAErC,eAAe;EAGf,iBAAiB;EAGjB,MAAM;EAGN;EAGA,gBAAgB;EAGhB;EAGA,UAAU;EAGV;EAGA,WAAW;EAGX;EAGA;EAGA,mBAAmB,IAAI;;;;;;EAQvB;;EAIA,oBAAoB,gCAAgC;;;;;;EAQpD;;;;;;EAQA;;;;;EAOA,qBAAqB,wBAAwB;EAG7C,mBAAmB,8BAA8B;UAGzC;mBAoBS;UAeT;UAyFA;;WAkGC,QAAM,qBAAA;;MAYX,YAAY;EAoBP;EA8DA;EA2BA;EASA,QAAQ,SAAS;;MA0CtB,gBAAgB;;MAKhB,iBAAiB,YAAY;;;;;;EASjC;EAIA,QAAQ,MAAM,kBAAkB,UAAU;;;;;EAuB1C,WAAW,MAAM,UAAU;;EAW3B,YAAY,OAAO,SAAS,WAAW;EAIvC;;;;;EAYA,SAAS,gBAAgB;;;;;EAgBzB,YAAY,MAAM;;;;;;;;;;EAalB;;;;;;EAsBA,SAAS,WAAW,WAAW,OAAO;EAItC,OAAO,MAAM;EAIb,WAAW,OAAO,SAAS;EAI3B,SAAS,MAAM;EAIf;EAIA;;MAQI,gBAAgB;;MAKhB;;EAMJ,WAAW,MAAM;;EAKjB,gBAAgB,MAAM;;EAKtB,mBAAmB,MAAM;;EAKzB,SAAS;EAgBP,eAAe,0CAA0C,UAAU;UA4a7D;;;;;;;;;EAkBF,kBAAkB;UAwBhB;UAMA;UAgCA;UAiBA;;;;;;;UA2DA;;UAoBA;UAcA;UAYA;UAQA;UA6DA;UAMA;UAIA;UA4EA;UAWA;UAMA;UAKA;SAUQ,sBAAM;EAiJb,wBAAM;;QAsBT;YACI;IACR,oBAAoB;;YAGZ,4BAA4B;;UAGvB,kCAAkC;EACjD,+BAA+B;EAC/B,0BAA0B,yBAAyB"}

package/dist/grid-list-ChgYpUUq.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"grid-list-ChgYpUUq.d.ts","names":[],"sources":["../src/interaction/list-drag-select-controller.ts","../src/interaction/list-selection-controller.ts","../src/interaction/tree-keyboard-controller.ts","../src/grid-list/types.ts","../src/grid-list/grid-list.ts"],"mappings":"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"}