@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-flag.md

@@ -0,0 +1,160 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-flag`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/flag/flag.js';` (registers the tag; side-effect import)
+- **Class** `LyraFlag`, also available unregistered from `@aceshooting/lyra-ui/components/media/flag/flag.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** `@aceshooting/lyra-flags` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-flag`
+
+Country/language flag image. Flag artwork ships in a **separate, optional peer package**
+(`@aceshooting/lyra-flags`) — importing `lyra-ui` core never pulls in flag image weight.
+
+**Properties:**
+- `country?: string` (ISO 3166-1 alpha-2, e.g. `"fr"` — takes precedence over `language`)
+- `language?: string` (BCP-47-ish tag, e.g. `"en"`/`"en-US"`, resolved to a representative country
+  via `languageToCountry()`)
+- `src?: string` (a pre-resolved flag image URL — takes precedence over `country`/`language` and
+  skips the peer-package lookup/loading-skeleton round trip entirely; mainly useful to avoid even
+  the small per-flag async hop when you already have the URL at build time, e.g. from
+  `import frUrl from '@aceshooting/lyra-flags/flags/fr.svg?url'`. `label` is effectively required
+  alongside `src` since there's no `country`/`language` to derive a fallback `alt` from.)
+- `label?: string` (accessible name / `alt` text — **defaults to a localized, human-readable region
+  name derived from the *resolved country* code via `Intl.DisplayNames` if omitted**, see gotchas)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — takes precedence over `label`
+  and the derived region name; an explicit empty value marks the image decorative
+- `round: boolean = false` (reflected — circular crop)
+- `variant?: 'compact' | 'standard' | 'detailed'` (attribute `variant`, not reflected — picks a
+  fidelity tier for the ~65 codes whose source art embeds a coat of arms/seal/emblem; every other
+  code resolves to the same file regardless of `variant`. `'compact'` = a tiny WebP raster for
+  icon-scale use (menus, language pickers, ~12–28px); `'standard'` (the effective default, when both
+  `variant` and `detailed` are unset) = the icon-optimized vector for card/row sizes (~28–96px);
+  `'detailed'` = the pristine full-fidelity vector for hero-scale display. Takes precedence over the
+  deprecated `detailed` below. No effect when `src` is set.)
+- `detailed: boolean = false` (reflected — **deprecated: use `variant="detailed"` instead**. Kept as
+  an alias for one minor cycle — when `variant` is left unset, `detailed` still maps to the detailed
+  tier — scheduled for removal in the next major. No effect when `src` is set.)
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `image`
+
+**Themeable custom properties:** `--lr-flag-radius` (default `calc(var(--lr-radius) * 0.33)` —
+non-`round` corner radius), `--lr-flag-aspect-ratio` (default `4 / 3`), and
+`--lr-flag-object-fit` (default `cover`); also consumes `--lr-color-border` for the inset ring.
+
+**Optional peer deps:** `@aceshooting/lyra-flags` — required for the component to actually render an
+image when `country` or `language` is used. Import `components/flag/flag-peer.js` once to opt into
+that resolver; a pre-resolved `src` works without the peer registration entry. If the peer is not
+installed, renders an empty template (see gotchas).
+
+Also exported from the package root:
+`languageToCountry(language: string): string | undefined` and the `LANGUAGE_TO_COUNTRY` lookup
+table (region subtag wins, e.g. `en-US` → `us`; plain `en` → `gb`; override the table per-app if you
+need different defaults), plus `localeNativeName(tag: string): string`.
+
+`localeNativeName()` returns a BCP-47 tag's **endonym** — the locale's name written in that locale
+itself (`'fr'` → `français`, `'pt-BR'` → `português (Brasil)`). That is what a language switcher
+should list, so a reader who understands none of the current UI language can still find their own.
+It derives from `Intl.DisplayNames`, so no name table ships with the library and results follow the
+browser's own ICU data; the underlying instance comes from a shared memoized cache, since a picker
+does one lookup per offered locale on every render pass. A tag with no display name resolves to the
+tag itself, and so does a structurally invalid one — `Intl.DisplayNames` throws a `RangeError` on
+those rather than falling back, and a language picker should degrade to showing the raw tag rather
+than tearing down the render. Pair it with `languageToCountry()` for the flag half of the same row.
+
+**Locale picker recipe.** A locale picker is a composition, not a component: `<lr-popover>` supplies
+the light-dismiss surface, `<lr-flag>` the country mark, `localeNativeName()` the endonym, and
+`aria-current="true"` marks the active choice. Which locales exist is the app's decision, so the app
+owns the list. Set `lang` on each row so assistive tech pronounces the endonym in its own language,
+and use `variant="compact"` at icon scale.
+
+```html
+<lr-popover placement="bottom-start">
+  <button slot="trigger">
+    <lr-flag language="fr" label="" style="height: 1rem"></lr-flag>
+    <span>français</span>
+  </button>
+  <ul role="list">
+    <!-- one <li><button lang="pt-BR" aria-current="false"> … </button></li> per offered locale -->
+  </ul>
+</lr-popover>
+```
+
+```js
+import { localeNativeName, languageToCountry } from '@aceshooting/lyra-ui';
+
+const rows = ['en', 'fr', 'de', 'pt-BR', 'ja', 'ar'].map((tag) => ({
+  tag,
+  name: localeNativeName(tag),   // endonym, e.g. "português (Brasil)"
+  country: languageToCountry(tag), // flag code for the same row
+}));
+```
+
+```html
+<lr-flag country="fr" label="France"></lr-flag>
+<lr-flag language="en-US" round></lr-flag>
+<lr-flag country="es" variant="compact"></lr-flag>  <!-- tiny WebP raster, icon-scale -->
+<lr-flag country="es" variant="detailed"></lr-flag> <!-- pristine full-fidelity vector -->
+```
+
+```bash
+pnpm add @aceshooting/lyra-flags   # required peer — without it, <lr-flag> renders nothing
+```
+
+```js
+import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';
+```
+
+**Known gotchas:**
+- `country`/`language` resolution is opt-in through `components/flag/flag-peer.js`; the root barrel
+  registers the component without importing the optional flag asset graph. Requires the optional
+  peer `@aceshooting/lyra-flags` to actually render an image; without it the component still shows a
+  `<lr-skeleton variant="rect">` placeholder (with `aria-busy="true"` on
+  the host) while resolving, then settles into an **empty template** plus a one-time `console.warn`
+  once the resolver rejects (lazy `import()`, cached module-wide so the warning fires only once per
+  page even with many `<lr-flag>` instances).
+- Rendering is async even when the peer *is* installed: `src` resolves after an `import()` +
+  resolver call, so there's a brief loading-skeleton window on first paint/attribute change — don't
+  assume the `<img>` exists synchronously right after setting `country`/`language`.
+- if both `aria-label` and `label` are omitted, the accessible name (`alt`) falls back to a localized
+  region name via `Intl.DisplayNames([effectiveLocale], { type: 'region' })` (e.g. `"United Kingdom"`) instead of
+  a bare code — for `language="en"` that's derived from `"GB"` (the mapped country), not `"EN"` (the
+  language tag itself). Falls back further to the bare uppercase code if `Intl.DisplayNames` throws
+  for an unrecognized region or isn't available. You can still pass an explicit `label` (e.g.
+  `"France"`) to override the derived name.
+- an invalid `country` (anything not matching the ISO 3166-1 alpha-2 shape, e.g. containing `../`)
+  is rejected before it ever reaches the peer's `flagUrl()` resolver — treated the same as an
+  unknown/missing flag rather than being passed through. `languageToCountry()`'s region-subtag path
+  is validated against that same alpha-2 shape too (not just a bare length-2 check), so a malformed
+  region such as `"en-01"` correctly falls through to the `LANGUAGE_TO_COUNTRY[base]` lookup instead
+  of being accepted verbatim as a country code.
+- rapidly reassigning `country`/`language`/`src` no longer risks a stale resolution overwriting a
+  newer one: each resolver call is tagged with a token captured at the time it was kicked off, and a
+  `.then()` that fires after a later change (or after the field was cleared) is discarded instead of
+  clobbering the rendered image/`loading`.
+- `country`/`language` resolve through `@aceshooting/lyra-flags`'s `flagUrl(code)`, which lazily
+  fetches one requested flag at runtime. A bundler may still emit the complete reachable lazy-chunk
+  graph because every supported code has a literal loader import; use a literal asset subpath
+  import when the deployment artifact must be pruned. If you already have a flag's URL at build
+  time, `src` skips the peer-package round trip (and its loading-skeleton flash) entirely.
+- 65 of `@aceshooting/lyra-flags`' 249 flags (any whose design includes a detailed coat of
+  arms/seal/emblem, e.g. `es`, `pt`, `sv`) ship **three** fidelity tiers, selected via the `variant`
+  property (`flagUrl(code, { variant })` under the hood): `"compact"` — a tiny WebP raster for
+  icon-scale use (menus, language pickers, dense lists); `"standard"` — the default, the
+  icon-optimized vector for card/row sizes, ~65% smaller on average than the pristine source for the
+  65 affected codes with no visible fidelity loss at that scale; `"detailed"` — the pristine
+  full-fidelity vector, for hero-scale display where the extra illustrative detail is actually
+  visible. The other 184 codes resolve to the same file regardless of `variant` — a safe no-op. The
+  older boolean `detailed` attribute predates `variant` and is now **deprecated**
+  (`variant="detailed"` is the replacement); left unset, `variant` falls back to honoring `detailed`
+  for one more minor version before removal.
+
+---

package/llms/components/lr-flow-canvas.md

@@ -0,0 +1,125 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-flow-canvas`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/flow-canvas/flow-canvas.js';` (registers the tag; side-effect import)
+- **Class** `LyraFlowCanvas`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-canvas/flow-canvas.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-flow-canvas`
+
+A pannable/zoomable DAG workflow canvas: positions HTML node cards, draws SVG edges between their
+handles, runs a shared layered auto-layout for unpositioned nodes, and owns all selection/drag/
+connect interaction as controlled events. Readonly (viewer) by default; opt into editor gestures
+individually via `nodes-draggable`, `connectable`, `droppable`. Never mutates `nodes` or `edges`
+itself — every edit intent is an event the host applies, mirroring `lr-stepper`/`lr-table`'s
+controlled-component contract.
+
+**Properties:**
+- `nodes: FlowNode[] = []` (attribute: false) — `FlowNode { id: string; type?: string; position?: {
+  x, y }; data?: Record<string, unknown>; accessibleLabel?: string; inputs?: FlowHandle[]; outputs?:
+  FlowHandle[] }`; a node with no `position` is placed by the layered auto-layout, and `data.label`/
+  `data.description` feed the default `<lr-flow-node>` card when no matching light-DOM child exists
+- `edges: FlowEdge[] = []` (attribute: false) — `FlowEdge { id: string; source: string; target:
+  string; sourceHandle?: string; targetHandle?: string; label?: string; tone?: 'accent' | 'success' |
+  'warning' | 'danger' | 'neutral' }` (source/target are node ids; `label` draws at the edge midpoint,
+  unlike `lr-graph`'s spoken-only `GraphLink.label`)
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — downstream layout/handle axis
+- `nodesDraggable: boolean = false` (attribute `nodes-draggable`)
+- `connectable: boolean = false`
+- `droppable: boolean = false` — accepts drops carrying the `FLOW_PALETTE_MIME_TYPE` payload a
+  `lr-node-palette` drag sets, emitting `lr-node-add`
+- `locked: boolean = false` (reflected) — freezes pan/zoom/drag/connect without touching the other
+  gesture flags
+- `selectedNodeIds: string[] = []`, `selectedEdgeIds: string[] = []` (attribute: false) — controlled;
+  the host assigns these back from `lr-selection-change`
+- `minZoom: number = 0.25` (attribute `min-zoom`), `maxZoom: number = 2` (attribute `max-zoom`)
+- `grid: number = 8` — snap step in content px for drags/nudges/drop positions (`0` disables
+  snapping); also the dotted background's base spacing
+- `layerGap: number = 64` (attribute `layer-gap`), `nodeGap: number = 24` (attribute `node-gap`) —
+  auto-layout layer/sibling spacing
+- `decorations: FlowRunDecorations | null = null` (attribute: false) — `Record<nodeOrEdgeId,
+  FlowRunDecoration>`, `FlowRunDecoration { status: 'pending'|'running'|'success'|'error'|'denied';
+  progress?: number; durationMs?: number; detail?: string }`; pushed onto adopted `lr-flow-node`
+  cards, typically supplied via a `lr-flow-run-overlay`
+- `accessibleLabel: string | null = null` (attribute `aria-label`)
+- `viewport` (read-only getter) — `{ x, y, zoom }`, the current pan/zoom state
+
+**Methods:** `setViewport({ x, y, zoom })`, `zoomIn()`, `zoomOut()`, `resetZoom()`,
+`fit(options?: { padding?: number })` (frames every node), `focusNode(id, options?: { zoom? })`
+(pans/zooms to one node and moves roving focus onto it), `toContentPoint(clientX, clientY)` (maps a
+pointer position to content coordinates, RTL-aware), `registerCompanion(cb: (snapshot:
+FlowStructureSnapshot) => void): () => void` — the subscription `lr-flow-minimap` uses to read
+live node/edge/viewport geometry without this canvas ever importing the minimap.
+
+**Events:** `lr-node-click` (`detail: { id }`), `lr-edge-click` (`detail: { id, source, target
+}`), `lr-selection-change` (`detail: { nodeIds, edgeIds }`), `lr-node-move` (`detail: { id,
+position, previous }`), `lr-connect` (`detail: { source, target, sourceHandle, targetHandle }`),
+`lr-node-add` (`detail: { type, position }`, from a palette drop), `lr-selection-delete`
+(`detail: { nodeIds, edgeIds }`), `lr-viewport-change` (`detail: { x, y, zoom }`),
+`lr-layout-change` (`detail: { positions }`, fired after an auto-layout pass places previously
+unpositioned nodes).
+
+**Slots:** default (`lr-flow-node` children adopted by `node-id`; a non-matching child is ignored
+with a console warning), `top-start`, `top-end` (floating corner overlays), `bottom-start` (e.g.
+`lr-flow-controls`), `bottom-end` (e.g. `lr-flow-minimap`).
+
+**CSS parts:** `base`, `viewport`, `background`, `edges`, `edge`, `edge-label`, `arrowhead`, `stub`
+(a dangling-edge stub line), `connection-line` (in-progress connect gesture), `node`, `empty`,
+`live-region`, `edge-list` (a visually hidden list of every edge).
+
+**Themeable custom properties:** `--lr-flow-canvas-grid-size` (default `8px`, dotted background
+spacing — the canvas also writes it inline as `${grid}px` from the `grid` property, which wins over
+the stylesheet fallback whenever a grid is in effect), `--lr-flow-canvas-march-duration` (default
+`var(--lr-transition-ambient)`, running-edge march animation duration), and
+`--lr-flow-canvas-node-current-outline-color` (default `var(--lr-color-brand)`) — the outline color
+of the current (`aria-current`) node. Like every state-scoped custom property in this library it is
+an inline `var()` fallback at its point of use rather than a `:host` declaration, so it can be set on
+the element *or any ancestor*. It exists because Shadow Parts forbids an attribute selector after
+`::part()` — `::part(node)[aria-current='true']` is invalid CSS — so the current node could otherwise
+only be restyled by overriding the library-wide `--lr-color-brand` token, repainting everything else
+that reads it. The same restriction motivates three more state-scoped outline colors:
+`--lr-flow-canvas-node-connect-invalid-outline-color` (default `var(--lr-color-danger)`) — outline of
+a node that is an invalid connect-gesture drop target; `--lr-flow-canvas-node-connect-target-outline-color`
+(default `var(--lr-color-brand)`) — outline of a node that is a valid connect-gesture drop target; and
+`--lr-flow-canvas-drop-active-outline-color` (default `var(--lr-color-brand)`) — outline of the
+viewport itself while a palette item is dragged over it (`droppable`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-flow-canvas id="canvas" nodes-draggable connectable droppable style="height:480px"></lr-flow-canvas>
+<lr-flow-controls slot="bottom-start" for="canvas"></lr-flow-controls>
+<lr-flow-minimap slot="bottom-end" for="canvas"></lr-flow-minimap>
+<script>
+  const canvas = document.getElementById('canvas');
+  canvas.nodes = [
+    { id: 'a', data: { label: 'Fetch' } },
+    { id: 'b', data: { label: 'Transform' } },
+  ];
+  canvas.edges = [{ id: 'a-b', source: 'a', target: 'b' }];
+  canvas.addEventListener('lr-node-move', (e) => {
+    canvas.nodes = canvas.nodes.map((n) => (n.id === e.detail.id ? { ...n, position: e.detail.position } : n));
+  });
+</script>
+```
+
+**Known gotchas:**
+- Fully controlled: `nodes`/`edges`/`selectedNodeIds`/`selectedEdgeIds` are never mutated
+  internally — `lr-node-move`, `lr-selection-change`, `lr-connect`, `lr-node-add`, and
+  `lr-selection-delete` are all requests the host applies back, same contract as `lr-table`.
+- Auto-layout (via the dependency-free `layeredLayout()` util) only ever positions nodes that are
+  missing an explicit `position`; a node the host has already positioned is left exactly where it is
+  and used as a fixed anchor for the rest of the layout pass.
+- `droppable` only accepts drags carrying the exact `FLOW_PALETTE_MIME_TYPE` MIME type a
+  `lr-node-palette` drag sets — the two components can never disagree on the payload shape because
+  they share one exported constant.
+- Pan/drag/zoom track the pointer's physical direction; under an RTL ancestor the pan and node-drag
+  deltas are mirrored so content still visually follows the cursor, matching every other
+  RTL-mirrored surface in this library.
+
+---

package/llms/components/lr-flow-controls.md

@@ -0,0 +1,58 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-flow-controls`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/flow-controls/flow-controls.js';` (registers the tag; side-effect import)
+- **Class** `LyraFlowControls`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-controls/flow-controls.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-flow-controls`
+
+The canvas's button cluster: zoom in/out, fit, and interaction lock, so every flow surface ships the
+same affordances without hosts rebuilding them. Manipulates only view state, never `nodes`/`edges` —
+no editing commands live here.
+
+**Properties:**
+- `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
+- `orientation: 'vertical' | 'horizontal' = 'vertical'` (reflected) — button-cluster layout axis
+- `hideLock: boolean = false` (attribute `hide-lock`) — omits the lock/unlock toggle button
+- `appearance: FlowControlsAppearance = 'card'` (reflected) — `'card' | 'plain'`; `'plain'` drops
+  `[part="base"]`'s border, background, padding, corner radius and its floating-surface `box-shadow`,
+  for a cluster placed in a host toolbar or panel that already draws its own surface. There is
+  deliberately no `compact`: the padding is already the smallest spacing step and the only remaining
+  room is the buttons' `--lr-icon-button-size` hit-area floor
+
+**Events:** none dispatched directly — each button calls the resolved canvas's own `zoomIn()`/
+`zoomOut()`/`fit()`, or toggles its `locked` property.
+
+**Slots:** default — extra host buttons appended to the cluster, styled by the same group.
+
+**CSS parts:** `base` (the `role="group"` wrapper; drops its floating-surface chrome under
+`appearance="plain"`), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted when `hideLock`).
+
+**Themeable custom properties:** shared tokens only — `--lr-icon-button-size` (each button's minimum
+hit area, unchanged by `appearance`), `--lr-shadow`, `--lr-color-surface`, `--lr-color-border`,
+`--lr-radius`, `--lr-space-2xs`, `--lr-focus-ring-width`/`-color`/`-offset`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-flow-canvas id="canvas" style="height:480px">
+  <lr-flow-controls slot="bottom-start" for="canvas"></lr-flow-controls>
+</lr-flow-canvas>
+```
+
+**Known gotchas:**
+- `for` resolution is identical to `lr-flow-minimap`/`lr-flow-run-overlay`: an explicit id, else
+  the nearest ancestor canvas — none of the three companions import `LyraFlowCanvas` as a value, only
+  its types, so registration order between them and the canvas never matters.
+- `appearance="plain"` drops the `box-shadow` along with the border and background — unlike most
+  `plain` escapes in this library, which only reset the border/background/padding/radius. A lift
+  shadow with no surface under it reads as a stray smudge, so the whole floating-surface treatment
+  goes together (same as `lr-flow-run-overlay`'s `plain`).
+
+---

package/llms/components/lr-flow-minimap.md

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-flow-minimap`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/flow-minimap/flow-minimap.js';` (registers the tag; side-effect import)
+- **Class** `LyraFlowMinimap`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-minimap/flow-minimap.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-flow-minimap`
+
+A corner overview map of a `lr-flow-canvas`: scaled node rectangles plus a draggable viewport
+rectangle, for orientation and fast navigation on canvases larger than the screen. Draws no edges
+(nodes only, matching the React Flow/n8n minimap convention) and never reads `nodes` itself —
+geometry always comes from the canvas's `registerCompanion()` snapshots, so the two can never
+disagree.
+
+**Properties:**
+- `for: string = ''` — id of the target `lr-flow-canvas`; when empty, the nearest ancestor canvas
+  is used (the slotted-into-a-corner-slot case, the primary wiring)
+- `label: string = ''` — accessible name for the map region; falls back to a host `aria-label`, then
+  a localized default
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `map` (the scaled SVG), `node` (one rect per node), `viewport` (the
+draggable, focusable view rectangle).
+
+**Themeable custom properties:** `--lr-flow-minimap-inline-size` (default `12rem`),
+`--lr-flow-minimap-block-size` (default `8rem`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-flow-canvas id="canvas" style="height:480px">
+  <lr-flow-minimap slot="bottom-end" for="canvas"></lr-flow-minimap>
+</lr-flow-canvas>
+```
+
+**Known gotchas:**
+- Never resolves `nodes`/`edges` on its own — it subscribes to `registerCompanion()` and repaints
+  from whatever snapshot the canvas last pushed, so it can only ever show what the canvas itself
+  currently renders.
+- Dragging the viewport rectangle calls the canvas's `setViewport()` directly; there's no separate
+  event to wire up.
+
+---

package/llms/components/lr-flow-node.md

@@ -0,0 +1,77 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-flow-node`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/flow-node/flow-node.js';` (registers the tag; side-effect import)
+- **Class** `LyraFlowNode`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-node/flow-node.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-flow-node`
+
+The card a workflow node renders as: header/body/toolbar chrome, tool-lifecycle status tones, and
+the named connection-handle elements edges anchor to. Used as `lr-flow-canvas`'s default card and
+as a slotted override; also renders standalone (palette previews, docs). Purely presentational —
+activation, selection, movement, and connection are all `lr-flow-canvas` events; this component
+owns none of that.
+
+**Properties:**
+- `nodeId: string = ''` (attribute `node-id`)
+- `heading: string = ''`
+- `status: 'pending' | 'running' | 'success' | 'error' | 'denied' | null = null` (reflected)
+- `progress: number | null = null` — renders a determinate `[part="progress"]` bar when set
+- `statusDetail: string = ''` (attribute `status-detail`) — appended to the status line
+- `durationMs: number | null = null` (attribute `duration-ms`) — formatted into the status line
+- `selected: boolean = false` (reflected)
+- `compact: boolean = false` (reflected) — tighter card padding for dense canvases and palette
+  previews; the border, background, shadow and the `selected`/`status="running"` treatments all stay
+- `inputs: FlowHandle[] = [{ id: 'in' }]`, `outputs: FlowHandle[] = [{ id: 'out' }]` (attribute:
+  false) — `FlowHandle { id: string; label?: string }`
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — which physical edge handles
+  render on; mirrors the adopting canvas's own `orientation`
+
+**Events:** none — purely presentational, activation/drag/connect all live on `lr-flow-canvas`.
+
+**Slots:** default (body content), `icon` (leading header glyph), `header` (replaces the built-in
+heading row entirely), `toolbar` (action row at the block-end edge).
+
+**CSS parts:** `base` (the row wrapping the input handles, the card and the output handles — it
+carries no card chrome of its own), `card` (the bordered, filled node card), `header`, `icon`,
+`heading`, `status` (never color-only — always paired with text), `progress`, `body`, `toolbar`,
+`handle` (every handle dot), `handle-input`, `handle-output`.
+
+**Themeable custom properties:** `--lr-flow-node-min-inline-size` (default `11rem`),
+`--lr-flow-node-compact-padding` (default `var(--lr-space-xs)`) and `--lr-flow-node-compact-gap`
+(default `var(--lr-space-2xs)`) — `[part="card"]`'s padding and row gap while `compact` — and
+`--lr-flow-node-selected-border` (default `var(--lr-color-brand)`) — the card's border color while
+`selected`. Like the other state-scoped custom properties here they are inline `var()` fallbacks at
+their point of use rather than `:host` declarations, so they can be set on the element *or any
+ancestor* (a canvas retunes every card at once); overriding the selection color otherwise means
+hijacking the library-wide `--lr-color-brand` token and repainting everything else that reads it.
+`--lr-flow-node-running-border` (default `var(--lr-color-brand)`) — the card's border color while
+`status="running"`, independent of `--lr-flow-node-selected-border` so a consumer can retint just one
+of the two states without the other following along — and `--lr-flow-node-running-glow` (default
+`var(--lr-color-brand-quiet)`) — the box-shadow color of the running-state ring around the card, and
+the pulse keyframes' peak color.
+
+**Optional peer deps:** none.
+
+```html
+<lr-flow-node node-id="a" heading="Fetch" status="running" progress="40"></lr-flow-node>
+```
+
+**Known gotchas:**
+- A running node's card pulses (`?data-pulse`) unless `prefers-reduced-motion` is set — the same
+  reduced-motion exception every animated surface in this library follows.
+- `status` drives a status chip with a localized label plus `statusDetail`/`durationMs`, never a
+  color-only indicator.
+- All card chrome lives on `[part="card"]`, not `[part="base"]` — `base` is only the flex row that
+  holds the input handles, the card and the output handles. Style the box through `::part(card)`.
+- `--lr-flow-node-min-inline-size` was previously overridden by a duplicate declaration and had no
+  effect. It now sets the card's minimum inline size again, so a node that was relying on the card
+  collapsing below `11rem` will render wider than it used to.
+
+---

package/llms/components/lr-flow-run-overlay.md

@@ -0,0 +1,60 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-flow-run-overlay`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/flow-run-overlay/flow-run-overlay.js';` (registers the tag; side-effect import)
+- **Class** `LyraFlowRunOverlay`, also available unregistered from `@aceshooting/lyra-ui/components/data/flow-run-overlay/flow-run-overlay.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-flow-run-overlay`
+
+Execution-state presentation for a `lr-flow-canvas`: pushes a `FlowRunDecorations` map into the
+resolved canvas (the canvas itself renders the node/edge paint) and renders a compact run-summary
+strip. Does not execute, poll, or time anything — pure pushed state; `durationMs` is host-computed.
+
+**Properties:**
+- `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
+- `decorations: FlowRunDecorations = {}` (attribute: false) — `Record<nodeOrEdgeId,
+  FlowRunDecoration>`, pushed verbatim onto the resolved canvas's own `decorations` property
+- `hideSummary: boolean = false` (attribute `hide-summary`) — omits the "{done} of {total} steps
+  complete" strip, keeping only the decoration push
+- `label: string = ''` — accessible name for the summary strip
+- `appearance: 'card'|'plain' = 'card'` (reflected) — `'plain'` removes the border, background,
+  shadow, padding and radius, so a summary strip dropped straight into a host toolbar that already
+  draws its own frame does not double it. `'card'` is the standalone floating-strip presentation and
+  is unchanged.
+
+**Events:** none dispatched directly.
+
+**Slots:** default — extra host chrome appended to the strip (e.g. a cancel button or a usage
+badge).
+
+**CSS parts:** `base`, `summary` (the "{done} of {total} steps complete" line), `count` (one per
+status present, text + tone dot, never color-only), `live-region` (step-transition announcement).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-flow-canvas id="canvas" style="height:480px">
+  <lr-flow-run-overlay slot="top-start" for="canvas"></lr-flow-run-overlay>
+</lr-flow-canvas>
+<script>
+  document.querySelector('lr-flow-run-overlay').decorations = {
+    a: { status: 'success', durationMs: 820 },
+    b: { status: 'running', progress: 40 },
+  };
+</script>
+```
+
+**Known gotchas:**
+- Purely a pushed-state conduit: it never starts, stops, or times a run itself — the host recomputes
+  `decorations` (including `durationMs`) on whatever cadence its own execution engine ticks at.
+- `for` resolution matches `lr-flow-minimap`/`lr-flow-controls`.
+
+---

package/llms/components/lr-format-bytes.md

@@ -0,0 +1,31 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-format-bytes`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/format/format-bytes.js';` (registers the tag; side-effect import)
+- **Class** `LyraFormatBytes`, also available unregistered from `@aceshooting/lyra-ui/components/utility/format/format-bytes.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-format-bytes`
+
+Byte-size output via `Intl.NumberFormat`'s `style: 'unit'` (`unitDisplay: 'short'`), so the unit
+name is localized too. Text-only host — no CSS parts, events, or own tokens; locale resolution and
+`Intl`-instance caching are as described under `lr-format-number` above.
+
+**Properties:**
+- `value: number = 0` — a byte count
+- `unitStep: number = 1024` (attribute `unit-step`) — set `1000` for SI (kB/MB) instead of binary
+- `decimals: number = 1` — maximum fraction digits on the scaled amount
+
+**Slots:** default — fallback content, rendered only when `value` is not finite.
+
+The unit ladder is fixed at `byte`, `kilobyte`, `megabyte`, `gigabyte`, `terabyte`, `petabyte` and
+saturates at the top; the index is `floor(log|value| / log(unitStep))`, and `0` always formats as
+bytes. `unitStep` is normalized to a finite number `> 1` (a step of exactly `1` would divide by
+`log(1) === 0`) falling back to `1024`; `decimals` is clamped to `[0, 10]` — an out-of-range value
+would otherwise throw a `RangeError` from `maximumFractionDigits`. Note that `unitStep: 1024` still
+prints the SI-named `kB`/`MB` units, not `KiB`/`MiB` — `Intl` has no binary unit names.

package/llms/components/lr-format-date.md

@@ -0,0 +1,33 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-format-date`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/format/format-date.js';` (registers the tag; side-effect import)
+- **Class** `LyraFormatDate`, also available unregistered from `@aceshooting/lyra-ui/components/utility/format/format-date.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-format-date`
+
+`Intl.DateTimeFormat` output. Text-only host — no CSS parts, events, or own tokens; locale
+resolution and `Intl`-instance caching are as described under `lr-format-number` above.
+
+**Properties:**
+- `date: string | number | Date = ''` — a `Date`, or anything the `Date` constructor accepts
+- `year: Intl.DateTimeFormatOptions['year'] = 'numeric'`, `month: … = 'long'`, `day: … = 'numeric'`
+  — the granular option set
+- `dateStyle?: 'full'|'long'|'medium'|'short'` (attribute `date-style`), `timeStyle?: …`
+  (attribute `time-style`) — the preset-style set
+- `timeZone?: string` (attribute `time-zone`) — an IANA zone name, forwarded through **both** option
+  sets
+
+Setting either `dateStyle` or `timeStyle` switches the component to the preset-style set and the
+granular `year`/`month`/`day` are then ignored entirely (`Intl` throws when the two are mixed); leave
+both unset to use the granular set. An unparseable `date` renders the default slot. An invalid
+`timeZone` throws a `RangeError` inside `Intl`, which is caught and retried once without the zone —
+so the output falls back to the browser's local zone instead of failing to render.
+
+**Slots:** default — fallback content for an invalid/unparseable `date`.

package/llms/components/lr-format-number.md

@@ -0,0 +1,41 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-format-number`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/format/format-number.js';` (registers the tag; side-effect import)
+- **Class** `LyraFormatNumber`, also available unregistered from `@aceshooting/lyra-ui/components/utility/format/format-number.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-format-number`
+
+`Intl.NumberFormat` output.
+
+Shared by all four formatters (`lr-format-number`, `lr-format-date`, `lr-format-bytes`,
+`lr-relative-time`): each is text-only — a `display: inline` host with **no CSS parts, no events, and
+no themeable custom properties of its own** — rendering one formatted string into its shadow root.
+Locale comes from the shared `effectiveLocale` (this element's own `locale`, else the nearest
+inherited `lang`; see `llms/shared.md`) and is passed to `Intl` as `undefined` when it resolves
+empty, which means "the runtime's default locale". Every `Intl` instance is pulled from the shared
+memoized `internal/intl-cache.ts` (one instance per locale + options pair, LRU-capped), so these are
+cheap to use per row in a large table or feed.
+
+**Properties:**
+- `value: number = 0`
+- `currency: string = ''` — an ISO 4217 code (`'EUR'`, `'JPY'`). Non-empty switches the formatter to
+  `style: 'currency'`; empty leaves it at `Intl`'s default decimal style
+- `notation: 'standard' | 'compact' | 'scientific' | 'engineering' = 'standard'`
+- `minimumFractionDigits?: number` (attribute `minimum-fraction-digits`)
+- `maximumFractionDigits?: number` (attribute `maximum-fraction-digits`)
+
+**Slots:** default — fallback content, rendered only when `value` is not finite (`NaN`/`Infinity`,
+e.g. a malformed attribute) or the formatted string is empty.
+
+Both fraction-digit properties are normalized to finite integers clamped to `Intl`'s own accepted
+`[0, 100]`, and swapped if clamping left `minimum > maximum` — either would otherwise throw a
+`RangeError` and crash the render. Leaving one `undefined` passes nothing for it, so `Intl`'s own
+notation-driven defaults still apply; there is no forced default pair. No `percent`/`unit` style and
+no `signDisplay`/`currencyDisplay`/grouping knob — compose `Intl.NumberFormat` directly for those.