@vielzeug/codex 26.10.1 → 26.10.2

package/data/catalog.json

@@ -73,7 +73,7 @@
         "coins"
       ],
       "slug": "arsenal",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -123,7 +123,7 @@
         "refine"
       ],
       "slug": "assay",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -165,7 +165,7 @@
         "ward"
       ],
       "slug": "clockwork",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -197,7 +197,7 @@
         "refine"
       ],
       "slug": "codex",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -267,7 +267,7 @@
         "spell"
       ],
       "slug": "coins",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -308,7 +308,7 @@
         "rune"
       ],
       "slug": "conduit",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -353,7 +353,7 @@
         "postmaster"
       ],
       "slug": "courier",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -399,7 +399,7 @@
         "refine"
       ],
       "slug": "dnd",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -441,7 +441,7 @@
         "herald"
       ],
       "slug": "familiar",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -508,7 +508,7 @@
         "courier"
       ],
       "slug": "flux",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -526,6 +526,7 @@
       "exports": [
         "createListNavigation",
         "createGridNavigation",
+        "createQuickLookGrid",
         "captureFocus",
         "restoreFocus",
         "rescueFocus"
@@ -537,7 +538,8 @@
         "keyboard",
         "accessibility",
         "list navigation",
-        "grid navigation"
+        "grid navigation",
+        "quick look"
       ],
       "name": "@vielzeug/focus",
       "related": [
@@ -546,7 +548,7 @@
         "ore"
       ],
       "slug": "focus",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -587,7 +589,7 @@
         "assay"
       ],
       "slug": "forge",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -625,7 +627,7 @@
         "keymap"
       ],
       "slug": "gesture",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -669,7 +671,7 @@
         "familiar"
       ],
       "slug": "herald",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -712,7 +714,7 @@
         "tempo"
       ],
       "slug": "illusionist",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -757,7 +759,7 @@
         "ore"
       ],
       "slug": "keymap",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -804,7 +806,7 @@
         "vault"
       ],
       "slug": "ledger",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -850,7 +852,7 @@
         "courier"
       ],
       "slug": "lingua",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -888,7 +890,7 @@
         "herald"
       ],
       "slug": "mesh",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -925,7 +927,7 @@
         "ore"
       ],
       "slug": "necromancer",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -965,7 +967,7 @@
         "prism"
       ],
       "slug": "orbit",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1029,7 +1031,7 @@
         "orbit"
       ],
       "slug": "ore",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1073,7 +1075,7 @@
         "ripple"
       ],
       "slug": "postmaster",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1116,7 +1118,7 @@
         "orbit"
       ],
       "slug": "prism",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1180,7 +1182,7 @@
         "clockwork"
       ],
       "slug": "pulse",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1298,7 +1300,7 @@
         "keymap"
       ],
       "slug": "refine",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1351,7 +1353,7 @@
         "ledger"
       ],
       "slug": "ripple",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1405,7 +1407,7 @@
         "familiar"
       ],
       "slug": "rune",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1446,7 +1448,7 @@
         "refine"
       ],
       "slug": "sandbox",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1497,7 +1499,7 @@
         "ripple"
       ],
       "slug": "scout",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1550,7 +1552,7 @@
         "refine"
       ],
       "slug": "scroll",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1597,7 +1599,7 @@
         "gesture"
       ],
       "slug": "sentinel",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1637,7 +1639,7 @@
         "refine"
       ],
       "slug": "sigil",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1701,7 +1703,7 @@
         "wayfinder"
       ],
       "slug": "sourcerer",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1760,7 +1762,7 @@
         "vault"
       ],
       "slug": "spell",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1799,7 +1801,7 @@
         "ripple"
       ],
       "slug": "tandem",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1840,7 +1842,7 @@
         "herald"
       ],
       "slug": "tavern",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1908,7 +1910,7 @@
         "vault"
       ],
       "slug": "tempo",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -1959,7 +1961,7 @@
         "ripple"
       ],
       "slug": "vault",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -2005,7 +2007,7 @@
         "refine"
       ],
       "slug": "ward",
-      "version": "26.10.0"
+      "version": "26.10.1"
     },
     {
       "availableDocPages": [
@@ -2059,8 +2061,8 @@
         "herald"
       ],
       "slug": "wayfinder",
-      "version": "26.10.0"
+      "version": "26.10.1"
     }
   ],
-  "version": "26.10.0"
+  "version": "26.10.1"
 }

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 41 packages. Version: 26.10.0
+> Complete documentation for 41 packages. Version: 26.10.1
 
 ---
 
@@ -6370,6 +6370,7 @@ list.addEventListener('keydown', (event) => {
 | Zero dependencies | n/a |  |
 | RTL mirroring | Manual | Built in |
 | Grid navigation | Flat only | `createGridNavigation()` |
+| Quick Look grids | Manual Space handling | `createQuickLookGrid()` |
 | Typeahead | Manual | Optional via `typeahead` |
 | Focus restoration | Manual capture | `captureFocus()` / `restoreFocus()` |
 
@@ -6413,6 +6414,7 @@ container.removeEventListener('keydown', onKeydown);
 
 - `createListNavigation()`: pure composite navigation with explicit handled/change results
 - `createGridNavigation()`: two-dimensional arrow-key navigation with fixed or measured columns
+- `createQuickLookGrid()`: tile-grid arrow browsing with a Space preview key for card pickers
 - Orientation and direction support: vertical/horizontal/both with LTR/RTL defaults
 - Dynamic item queries: disabled filtering and loop control
 - Optional typeahead: label-based navigation in key-driven lists
@@ -6439,6 +6441,7 @@ container.removeEventListener('keydown', onKeydown);
 | --- | --- | --- | --- |
 | `createListNavigation()` | Build keyboard navigation for composite widgets | Sync | Apply returned changes to DOM focus |
 | `createGridNavigation()` | Build two-dimensional arrow-key navigation for grids | Sync | Columns resolve per navigation: responsive grids need a getter |
+| `createQuickLookGrid()` | Build arrow-key tile browsing with a preview key for card grids | Sync | The preview key consumes Space: the focused button never activates |
 | `restoreFocus()` | Restore focus to a target or fallback | Sync | Returns `false` when neither target can receive focus |
 | `rescueFocus()` | Re-home focus after the focused element unmounts | Sync | Returns `false` when focus is already on a real element |
 | `captureFocus()` | Capture active focus for one later restoration | Sync | The returned function is one-shot |
@@ -6536,6 +6539,41 @@ Unlike `createListNavigation`, items are not skipped when disabled: skipping in
 
 ---
 
+### `createQuickLookGrid()`
+
+```ts
+function createQuickLookGrid(options: QuickLookGridOptions): QuickLookGrid;
+```
+
+Creates keyboard browsing over a tile grid with a Quick Look key: arrows and Home/End move focus through the items (delegating to `createGridNavigation()`) and `inspectKey` previews the item under the event instead of activating it: the pair every card picker needs.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `QuickLookGridOptions` | Item lookup, active-index source, column resolution, preview key, wrapping, and inspection callback. |
+
+**Returns:** `QuickLookGrid`.
+
+**Example**
+
+```ts
+import { createQuickLookGrid } from '@vielzeug/focus';
+
+const quickLook = createQuickLookGrid({
+  getItems: () => [...grid.querySelectorAll('.tile')],
+  onInspect: (item, index) => previewCard(index),
+});
+
+grid.addEventListener('keydown', (event) => quickLook.handleKeydown(event));
+```
+
+| Member | Return | Contract |
+| --- | --- | --- |
+| `handleKeydown(event)` | `void` | Routes one `keydown`: navigation keys move focus to the reported item, `inspectKey` calls `preventDefault()`/`stopPropagation()` then `onInspect(item, index)`. Unrecognized, already-prevented, composing, modifier, and disabled events pass through. |
+
+`columns` defaults to the rendered row length at the active item (items sharing its top edge), which follows the grid's own responsive wrapping without a media query; supply `columns` to read a track list instead. `getActiveIndex` defaults to the item that is or contains `document.activeElement`; supply it when focus sits on a wrapper around the item. `inspectKey` defaults to `' '` (Space), the platform preview key. The recognizer pairs with a pointer long-press at the call site as the touch counterpart of `onInspect`.
+
+---
+
 ### `restoreFocus()`
 
 ```ts
@@ -6696,6 +6734,20 @@ type GridNavigation = {
   set(index: number): void;
 };
 
+type QuickLookGridOptions = {
+  columns?: GridColumns;
+  disabled?: MaybeGetter;
+  getActiveIndex?: () => number;
+  getItems: () => readonly HTMLElement[];
+  inspectKey?: string;
+  loop?: boolean;
+  onInspect: (item: HTMLElement, index: number) => void;
+};
+
+type QuickLookGrid = {
+  handleKeydown(event: KeyboardEvent): void;
+};
+
 type FocusTarget = HTMLElement | SVGElement | null | undefined | (() => HTMLElement | SVGElement | null | undefined);
 
 type RestoreFocusOptions = {
@@ -6823,6 +6875,25 @@ grid.addEventListener('keydown', (event) => {
 
 `columns` resolves on every navigation, so responsive grids can read a media query and measured grids can read the rendered row length. Clamping is the default; set `loop: true` to wrap moves around the grid's edges by flat index. Items are never skipped when disabled: skipping in two dimensions would break row alignment.
 
+## Browse Card Grids with Quick Look
+
+Use `createQuickLookGrid()` for card pickers, where arrows walk the tiles and Space previews the focused card instead of activating it: the WAI-ARIA Quick Look convention. The primitive pairs the navigation with the preview key, consumes the Space press so the focused button never toggles, and reports the item through `onInspect`:
+
+```ts
+import { createQuickLookGrid } from '@vielzeug/focus';
+
+const tiles = () => [...grid.querySelectorAll('.tile')];
+
+const quickLook = createQuickLookGrid({
+  getItems: tiles,
+  onInspect: (_item, index) => openPreview(index),
+});
+
+grid.addEventListener('keydown', (event) => quickLook.handleKeydown(event));
+```
+
+Leave `columns` unset to measure the rendered row length at the focused tile, which follows the grid's own responsive wrapping without a media query. Supply `getActiveIndex` when focus may sit on a wrapper around the item rather than the item itself. Enter keeps activating the focused tile through its own handler: only the preview key is intercepted. A pointer long-press recognizer is the touch counterpart of `onInspect`; pair them at the call site.
+
 ## Restore Focus
 
 Capture focus before opening a transient surface, then invoke the one-shot restorer when it closes:
@@ -16839,6 +16910,8 @@ interface Datum {
   key: TKey;
   value: number;
   meta?: Record;
+  dash?: string; // stroke-dasharray for this datum's marks, e.g. '5 5'
+  opacity?: number; // opacity multiplier 0-1 for this datum's marks, e.g. 0.4
 }
 
 type ContinuousDatum = Datum;
@@ -16847,6 +16920,7 @@ interface Series {
   name: string;
   data: TDatum[];
   color?: string;
+  id?: string; // stable data-series-id on the series group; defaults to series-
 }
 
 interface ChartEvent {
@@ -16864,6 +16938,23 @@ interface SeriesValue {
 
 Line and area series use `ContinuousDatum`; bar series accept the complete `Datum` key range. On line, area, and bar charts, `datum`/`series` name the series nearest the pointer, and `values` lists every series at that key (a missing value is `undefined`). `originalEvent` is a `MouseEvent`, or a `KeyboardEvent` for keyboard navigation.
 
+#### Per-datum presentation
+
+`dash` and `opacity` style an individual datum's marks without splitting the series — the usual case is a forecast tail where points past "today" are faded or dashed. They are styling-only: interaction, tooltip, and accessibility behavior never change. Support is per chart type:
+
+| Chart | `dash` | `opacity` |
+| --- | --- | --- |
+| Bar | `stroke-dasharray` on the datum's `rect`, plus a 1px series-color stroke so the dash is visible on the fill. | Element `opacity` on the datum's `rect`. |
+| Line | The segment from this datum to the next (Chart.js-style segments). The last datum's `dash` has no segment and is ignored. | That same segment, plus this datum's own point marker. |
+| Area | The top line's segment from this datum to the next (last datum ignored). The fill keeps the series-level treatment. | Same segment on the top line. |
+| Sparkline, pie, radar | Ignored. | Ignored. |
+
+Consecutive datums that share one `dash`/`opacity` render as a single path run. Absent fields keep the series/theme default, and a series with no presentation fields renders byte-identically to a chart that never used them. See [Forecast / emphasis styling](./usage.md#forecast--emphasis-styling).
+
+#### Stable series identity
+
+`Series.id` is rendered as `data-series-id` on the chart's series group (`.prism-line-series`, `.prism-bar-series`, `.prism-area-series`, `.prism-radar-series`) so tooltips, tests, and external CSS can address a series without positional assumptions. Characters outside `[A-Za-z0-9_-]` are replaced with `-`. It defaults to `series-`, which only stays stable while the series order does — set `id` to survive reordering.
+
 ---
 
 ### Chart configurations
@@ -17380,6 +17471,66 @@ const chart = createAreaChart(container, {
 
 `fillOpacity` overrides the theme opacity for one series.
 
+## Forecast / emphasis styling
+
+A single series often mixes points that should look different — actuals plus a
+forecast tail, or a run that crossed a budget. Rather than split the series,
+carry `dash` and `opacity` on the individual datums. They are styling-only:
+tooltips, hover, keyboard, and screen-reader behavior never change.
+
+For a forecast tail, map a parallel `types` array onto the datums:
+
+```ts
+import { createLineChart } from '@vielzeug/prism';
+
+const types = ['REAL', 'REAL', 'FORECAST', 'FORECAST'];
+
+const chart = createLineChart(container, {
+  series: [
+    {
+      name: 'Cost',
+      data: values.map((value, i) => ({
+        key: months[i],
+        value,
+        ...(types[i] === 'FORECAST' ? { dash: '5 5', opacity: 0.4 } : {}),
+      })),
+    },
+  ],
+});
+```
+
+On a line chart, a datum's `dash` styles the segment from that point to the
+next, so the forecast run renders dashed while the actuals stay solid; its
+`opacity` fades that segment and the point marker. The last datum's `dash` has
+no segment to paint and is ignored. On a bar chart, both fields apply to that
+datum's own bar — a `dash` adds a 1px series-color stroke so the dash reads on
+the filled rect. On an area chart they style the top line only; the fill keeps
+its series-level treatment.
+
+The same mapping fades bars:
+
+```ts
+import { createBarChart } from '@vielzeug/prism';
+
+const chart = createBarChart(container, {
+  series: [
+    {
+      name: 'Cost',
+      data: values.map((value, i) => ({
+        key: months[i],
+        value,
+        ...(types[i] === 'FORECAST' ? { dash: '5 5', opacity: 0.4 } : {}),
+      })),
+    },
+  ],
+});
+```
+
+Because the fields live on the data, a normal `update(newSeries)` re-applies
+them; removing the fields on the next update clears the styling. A series with
+no `dash`/`opacity` anywhere renders exactly as it did before these fields
+existed.
+
 ## Pie, Donut, and Semi-circle Charts
 
 All three variants use `createPieChart` with the `variant` field:

package/data/llms.txt

@@ -1,6 +1,6 @@
 # Vielzeug
 
-> 41 focused TypeScript packages. Version: 26.10.0
+> 41 focused TypeScript packages. Version: 26.10.1
 
 Install any package independently: `pnpm add @vielzeug/<name>`
 

package/data/manifest.json

@@ -4,5 +4,5 @@
   "refine": "refine.json",
   "schemaVersion": 1,
   "search": "search.json",
-  "version": "26.10.0"
+  "version": "26.10.1"
 }