@aceshooting/lyra-ui 6.0.0 → 6.2.0

package/llms/components/lr-widget.md

@@ -6,6 +6,7 @@
 - **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 14 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -42,6 +43,10 @@ position) survives the transition.
   view externally; also updated internally when a view toggle is clicked.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the label-derived fullscreen
   dialog name.
+- `storageKey?: string` (attribute `storage-key`) — when set, persists `collapsed` to `localStorage`
+  under `lr-widget:${storageKey}` and restores it on the next mount (mirrors `lr-app-rail`'s/
+  `lr-table`'s identical `storage-key` pattern). Without a `storageKey` there is no persistence and
+  storage is never touched — listen for `lr-collapse-change` and persist the state yourself.
 
 **Events:** `lr-collapse-change` (`detail: { collapsed }`, the new state), `lr-fullscreen-change`
 (`detail: { fullscreen }` — also fired when fullscreen is exited via Escape or a backdrop click, not
@@ -104,6 +109,9 @@ space for a persistent sidebar/toolbar that should stay visible instead of being
 fullscreen panel/backdrop — it overrides the default `var(--lr-space-l)` inset on every side for
 both `[part="base"]` and `[part="backdrop"]`. Set `compact` for tighter header/body padding.
 
+The collapse-button `aria-label` is localized via its own `widgetCollapse` (default `'Collapse
+panel'`) and `widgetExpand` (default `'Expand panel'`) keys.
+
 **Known gotchas:**
 - a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
   shared overlay registration and re-acquires the scroll lock if `fullscreen` was still `true`
@@ -111,5 +119,10 @@ both `[part="base"]` and `[part="backdrop"]`. Set `compact` for tighter header/b
   between, so `willUpdate()` alone wouldn't otherwise notice.
 - `collapsed` hides the body via `hidden` rather than an animated height transition — collapsing is
   instant, not a slide.
+- prior to this release the collapse-button `aria-label` was localized through `lr-dock-panel`'s
+  own `dockPanelCollapse`/`dockPanelExpand` keys (a borrowed, differently-named pair). A locale
+  registered against those keys specifically to target `lr-widget`'s collapse button should move
+  to `widgetCollapse`/`widgetExpand`; the default English strings are unchanged, and `lr-dock-panel`
+  itself is unaffected.
 
 ---

package/llms/components/lr-word-cloud.md

@@ -6,6 +6,7 @@
 - **Class** `LyraWordCloud`, also available unregistered from `@aceshooting/lyra-ui/components/data/word-cloud/word-cloud.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 10 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -42,6 +43,12 @@ visually-hidden `[part="live-region"]` (`role="status" aria-live="polite"`) anno
   90° for denser packing
 - `palette?: string[]` (attribute: false) — custom categorical colors, cycled by word index (or by
   `group`); defaults to the `--lr-word-cloud-color-1..8` tokens
+- `legend: WordCloudLegendItem[] = []` (attribute: false) — optional named `{ label, color }`
+  entries for explaining explicit `words[].color`/group color overrides; when omitted, the
+  component derives entries from grouped and explicitly colored words
+- `showLegend: boolean = false` (attribute `show-legend`, reflected) — renders the supplied or
+  derived legend below the cloud; the color key is an accessible list and does not change word
+  activation or palette selection
 
 **Methods:** `refreshTheme(): void` — forces a relayout so the `--lr-font` custom property is
 re-read from computed style (font-family affects the canvas text measurement layout depends on);
@@ -55,8 +62,8 @@ the currently-focused word — a no-op if nothing is focused yet)
 
 **CSS parts:** `base`, `svg`, `word` (each `<text>`), `focus-ring` (the rect around the roving-focus
 cursor's word), `live-region` (visually-hidden `role="status" aria-live="polite"` announcement text),
-`empty` (the no-data placeholder — hardcoded `"No data"` text, no property to customize it, unlike
-`lr-empty`/`lr-table`)
+`legend`/`legend-item`/`legend-swatch`/`legend-label` (the optional static color key), and `empty`
+(the no-data placeholder)
 
 **Themeable custom properties:** `--lr-word-cloud-color-1`, `--lr-word-cloud-color-2`,
 `--lr-word-cloud-color-3`, `--lr-word-cloud-color-4`, `--lr-word-cloud-color-5`,

package/llms/components/lr-xml-viewer.md

@@ -6,6 +6,7 @@
 - **Class** `LyraXmlViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/xml-viewer/xml-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 16 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/components/lr-zoomable-frame.md

@@ -6,6 +6,7 @@
 - **Class** `LyraZoomableFrame`, also available unregistered from `@aceshooting/lyra-ui/components/media/zoomable-frame/zoomable-frame.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 7 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-251 custom elements, grouped by the source family they live in.
+256 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
@@ -243,7 +243,7 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-voice-picker` · conversation/voice-picker/voice-picker.js — a TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s closed-dropdown/free-text-combobox dual mode, stale-va...
 - `lr-agent-workspace` · conversation/agent-workspace/agent-workspace.js — a responsive, controlled shell for an AI conversation and its supporting agent state.
 
-## Agent tooling, tool calls & evaluation — `components/agent-tools/` (29)
+## Agent tooling, tool calls & evaluation — `components/agent-tools/` (31)
 
 - `lr-tool-call-chip` · agent-tools/tool-call-chip/tool-call-chip.js — a compact inline pill representing one tool/ function call an agent made mid-conversation, e.g.
 - `lr-tool-result-view` · agent-tools/tool-result-view/tool-result-view.js — renders a tool call's result via whichever custom renderer a host app has registered for it (see `registerToolRenderer()` in `registry.ts...
@@ -274,8 +274,10 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-evaluation-run` · agent-tools/evaluation-run/evaluation-run.js — an evaluation batch's live progress: an overall `<lr-progress-bar>` counting terminal (done/error/cancelled) examples against the batch t...
 - `lr-policy-summary` · agent-tools/policy-summary/policy-summary.js — a read-only list of guardrail, permission, privacy, and tool-policy decisions, each carrying an `allow` / `deny` / `needs-review` state a...
 - `lr-tool-timeline` · agent-tools/tool-timeline/tool-timeline.js — a chronological list of an agent run's tool/function calls, each rendered through `<lr-tool-call-chip>` (name/status/duration) and `<lr-t...
+- `lr-agent-eval-dashboard` · agent-tools/agent-eval-dashboard/agent-eval-dashboard.js — a controlled evaluation overview with metric cards, a trend chart, and run-status history.
+- `lr-approval-queue` · agent-tools/approval-queue/approval-queue.js — a controlled queue of tool calls that need human approval, with a keyboard-accessible request list and a single reused `<lr-tool-approval...
 
-## Retrieval, knowledge graph & grounding — `components/retrieval/` (24)
+## Retrieval, knowledge graph & grounding — `components/retrieval/` (27)
 
 - `lr-graph` · retrieval/graph/graph.js — a force-directed node-link diagram with pan/zoom/drag.
 - `lr-node-palette` · retrieval/node-palette/node-palette.js — the searchable, categorized node library for workflow editors: drag an item onto a canvas, or place it by keyboard.
@@ -301,3 +303,6 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-retrieval-results` · retrieval/retrieval-results/retrieval-results.js — the orchestration-level ranked-chunk-list surface: takes raw `RetrievalChunk[]` (the shared retrieval-and-grounding type from `src/ai/typ...
 - `lr-retrieval-search` · retrieval/retrieval-search/retrieval-search.js — - the query bar for a retrieval/RAG surface: query text, an active- filter/scope chip row, a vector/keyword/hybrid mode selector, and loa...
 - `lr-retrieval-trace` · retrieval/retrieval-trace/retrieval-trace.js — a retrieval pipeline's stage timeline (query rewriting, embedding, retrieval, reranking, filtering), rendered through `<lr-span-waterfall...
+- `lr-rag-answer` · retrieval/rag-answer/rag-answer.js — a controlled grounded-answer surface combining sanitized Markdown, citation badges, a grounding assessment, and source previews.
+- `lr-embedding-explorer` · retrieval/embedding-explorer/embedding-explorer.js — a dependency-free, accessible 2D embedding projection viewer.
+- `lr-knowledge-base-admin` · retrieval/knowledge-base-admin/knowledge-base-admin.js — a responsive operations shell composing the existing controlled source inventory and ingestion queue into one tabbed knowledge-base view.

package/llms/peers.md

@@ -2,7 +2,7 @@
 
 # Optional peer dependencies
 
-All 25 peers are **optional**: nothing here is needed to install or use the library,
+All 26 peers are **optional**: nothing here is needed to install or use the library,
 and no component imports one eagerly. Install a peer only when you use a component that needs it.
 
 **How they load.** A component that needs a peer resolves it through a dynamic `import()` on first
@@ -18,6 +18,7 @@ If the peer is genuinely absent, the component falls back to an empty/degraded r
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.4.0` | `lr-box-plot` |
 | `chart.js` | `^4.5.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
+| `chartjs-plugin-datalabels` | `^2.2.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
 | `chartjs-plugin-zoom` | `^2.2.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
 | `d3-drag` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
 | `d3-force` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |

package/llms/shared.md

@@ -190,6 +190,94 @@ dark palette — that fallback applies only where no real `--lr-theme-*` value i
 The token layer also sets `:host([hidden]) { display: none !important; }` and an inherited
 `box-sizing: border-box` reset.
 
+### Theme mode/accent runtime (`@aceshooting/lyra-ui/theme.js`)
+
+Flipping the mode class/attribute above is something every app ends up hand-rolling — persist a
+choice, apply it on load, avoid the flash of wrong theme before the app boots. `theme.js` is that
+runtime, published as its own subpath: **zero dependencies, no Lit, no component imports, and no
+side effects on import**, so an app can persist and apply a theme without pulling the component
+graph into its first-paint bundle.
+
+```ts
+import { setLyraTheme, getLyraTheme } from '@aceshooting/lyra-ui/theme.js';
+
+setLyraTheme({ mode: 'dark' });                  // unspecified fields keep their current value
+setLyraTheme({ accent: '#7c3aed' });             // mode stays 'dark'
+getLyraTheme();                                  // → { mode: 'dark', accent: '#7c3aed' }
+setLyraTheme({ mode: 'auto', accent: null });    // clears the override and the accent
+```
+
+- **`setLyraTheme({ mode?, accent? })`** persists to `localStorage['lyra-theme']`, applies to
+  `document.documentElement`, and dispatches `lr-theme-change` on `window` with
+  `detail: { mode, accent }`. Fields you omit keep their current value; pass `null` to clear the
+  accent. It **never throws** — when `localStorage` is unavailable (private browsing, quota, a
+  sandboxed iframe) it degrades to apply-without-persist, and the "fields you omit keep their
+  current value" rule still holds across calls in that state: the merge falls back to the last
+  theme applied in this session rather than to the default.
+- **`getLyraTheme()`** returns `{ mode, accent }`, defaulting to `{ mode: 'auto', accent: null }`
+  when nothing is stored or the stored value is malformed. Storage is re-read on every call — no
+  in-memory cache — so a value written by another tab or a previous session is picked up cold.
+  Where storage is unreadable or unwritable it reports the theme last applied, so the return value
+  always describes what the document is actually showing and a toggle UI bound to it stays in sync.
+- **`mode`** is `'light' | 'dark' | 'auto'`. `'light'`/`'dark'` set **both `data-lr-theme`** (the
+  attribute `theme.css` actually keys its palette blocks on) **and `data-theme`** (the generic
+  attribute canvas-rendered components watch, so `lr-chart`/`lr-heatmap`/`lr-qr-code` repaint on
+  the switch rather than keeping stale colors — see `llms/components/lr-chart.md`). `'auto'`
+  removes both, which means **no override — not "follow the OS"**:
+  - **With `theme.css` imported** (the setup this section is nested under), its `:root` block sets
+    the full light palette unconditionally and that file ships no `prefers-color-scheme` block, so
+    `'auto'` renders **light** whatever the OS is set to.
+  - **Without `theme.css`**, no real `--lr-theme-*` value is set, so the token layer's
+    `prefers-color-scheme: dark` fallback described above does apply and bare components follow
+    the OS.
+
+  To follow the OS *alongside* `theme.css`, resolve the preference yourself and pass a concrete
+  mode — `setLyraTheme` deliberately does no `matchMedia` work of its own:
+  ```ts
+  const os = matchMedia('(prefers-color-scheme: dark)');
+  const sync = () => setLyraTheme({ mode: os.matches ? 'dark' : 'light' });
+  sync();
+  os.addEventListener('change', sync);
+  ```
+- **`accent`** is written to `--lr-theme-accent` as an inline custom property on the root element.
+  This is a **hook for your CSS, not a token the library reads** — no lyra-ui component consumes
+  `--lr-theme-accent`. Point the real inputs at it to make it retint anything, **writing one rule
+  per mode**:
+  ```css
+  :root { --lr-theme-color-brand-fill-loud: var(--lr-theme-accent, #0969da); }
+  .lr-dark,
+  [data-lr-theme='dark'] { --lr-theme-color-brand-fill-loud: var(--lr-theme-accent, #4ea0f0); }
+  ```
+  **Each arm's fallback must carry that mode's own value.** A single `:root` rule flattens both
+  modes to one color whenever the accent is unset (`accent: null`, the default): `:root` and
+  `[data-lr-theme='dark']` have equal specificity and both match `<html>` — the element
+  `setLyraTheme` writes `data-lr-theme` onto — so a consumer stylesheet loaded after `theme.css`
+  wins the tie on source order and pins the light-mode blue in dark mode. Copy each fallback from
+  the matching palette block in `theme.css` (`#0969da` light / `#4ea0f0` dark here).
+
+  Because that is a `--lr-theme-*` input, it reaches every nested shadow root — see "Where an
+  override actually reaches" above for why setting a `--lr-*` token instead would not.
+
+**No-flash bootstrap.** `lyraThemeBootstrap` is a self-contained IIFE **string** (not a function),
+meant to be inlined into a `<script>` in `<head>` **before any stylesheet**, so the persisted theme
+is on the root element before first paint. It is a string precisely so this can happen in an
+unbundled `<script>` context without shipping or parsing the module:
+
+```html
+<head>
+  <script>/* server-inlines lyraThemeBootstrap here */</script>
+  <link rel="stylesheet" href="/theme.css" />
+</head>
+```
+
+It reads the same storage key, applies the same two attributes and `--lr-theme-accent`, and
+swallows any error — malformed storage or a blocked `localStorage` leaves the document untouched
+rather than throwing before your app loads.
+
+**This runtime does no color math.** It stores and applies whatever accent string you give it; it
+does not validate the value, compute a palette from it, or check contrast against any surface.
+Verifying that an accent meets WCAG contrast against the light *and* dark palettes is yours.
+
 ## Localization: `locale`, `strings`, and the locale runtime
 
 Every built-in string — button labels, accessible names, descriptions, validation messages, status