@aceshooting/lyra-ui 6.0.0 → 6.2.0

package/CHANGELOG.md

@@ -1,5 +1,190 @@
 # Changelog
 
+## 6.2.0
+
+### Minor Changes
+
+- 7af01bf: Add `href`, `target`, and `download` to `<lr-button>`, giving it a real `<a>` anchor mode instead of
+  a `<button>` that a consumer has to wrap or intercept.
+
+  `rel` is derived from `target` rather than being independently settable, so a `target="_blank"`
+  button cannot ship without `rel="noopener noreferrer"`. Hrefs are validated through the internal
+  link allowlist; a `download` paired with a `mailto:` href falls back to the native `<button>`, since
+  `mailto:` names no retrievable bytes.
+
+- 7af01bf: Round out the chart components so app code stops reaching into raw `config` passthrough.
+
+  - `data-labels` and `stack-totals` boolean attributes on `<lr-chart>` and its subclasses render
+    value and stacked-total labels using themed tick colors and `--lr-font-*`, replacing hand-rolled
+    `afterDatasetsDraw` painters with hardcoded colors. These require the new optional peer
+    `chartjs-plugin-datalabels` (see the separate peer-dependency note); the plugin registers
+    per chart instance, never globally.
+  - `Series.pointRadius` accepts an array for per-point sizing, and `Series.segmentColors` maps to
+    Chart.js segment coloring.
+  - `seriesPalette()` is now public, so app code can read the resolved, dark-aware chart ramp instead
+    of re-resolving `--lr-theme-color-chart-N` through `getComputedStyle` itself.
+  - Charts re-theme automatically via a shared `ThemeWatcher` controller when the ambient theme
+    changes.
+  - `<lr-lite-chart>` renders a real `<table part="data-table">` screen-reader alternative when there
+    is more than one series; the previous flat `<ul>` degenerated for multi-series data.
+
+- 7af01bf: Add `chartjs-plugin-datalabels` (`^2.2.0`) as a new **optional** peer dependency, backing the new
+  `data-labels`/`stack-totals` chart attributes.
+
+  It is optional in the same sense as the other chart peers: install it only if you use those two
+  attributes. Without it, charts render exactly as before and the label layer fails closed rather than
+  throwing.
+
+- 8e0540a: Add five agentic AI / RAG roadmap components: `lr-agent-eval-dashboard`, `lr-approval-queue`, `lr-embedding-explorer`, `lr-knowledge-base-admin`, and `lr-rag-answer`.
+- 7af01bf: Fill several gaps in the form-control surface that were pushing logic onto consumers.
+
+  - `<lr-input>` and `<lr-textarea>` gain `minlength`/`maxlength` constraints wired into the validity
+    bridge, so length violations participate in constraint validation instead of being advisory.
+    Length is counted in code points, so astral characters count as one.
+  - `<lr-select>` and `<lr-combobox>` now emit value-carrying `lr-change` events, and their `input`/
+    `change` events carry a typed detail — no more `as unknown as { value }` at every call site.
+  - `<lr-card>` gains `target` for anchor-mode cards, with `rel="noopener noreferrer"` derived from it
+    rather than settable on its own.
+  - `<lr-combobox>` accepts an `AbortSignal` for `source` and a configurable `source-delay`
+    (default 200ms), so a fast typist no longer races stale in-flight results.
+
+- 7af01bf: Assorted layout and accessibility improvements.
+
+  - `<lr-split>`'s `defaultSizes` accepts CSS length strings (`['200px', 50]`) alongside percentages,
+    resolved against the measured container and renormalized — a fixed-width sidebar no longer needs a
+    `firstUpdated()` measure-and-convert dance.
+  - `<lr-table>` gains typed `accessible-label`/`caption` properties and warns in development when a
+    grid ships with no accessible name.
+  - `<lr-popover>` gains `hide({ focusTrigger })` for explicit focus return on programmatic close.
+  - `<lr-segmented>` auto-reveals the selection when `value` is set programmatically, and exposes
+    `scrollToValue()`.
+  - `<lr-heatmap>` warns when no 2D canvas context is available instead of silently rendering nothing.
+  - `<lr-file-input>` shows visible, localized rejection feedback per reason, replacing the sr-only
+    count-only message.
+  - `<lr-tool-result-view>` renderers can signal failure via a reflected `status`.
+  - `gemstoneGlyph()` defaults its fill to `currentColor` and carries an intrinsic `1em` box.
+
+- ad9165a: Add `mode="gemstone"` to `<lr-swatch-picker>`, shared gemstone accent data and glyph helpers, and
+  apply the selected shine animation to custom icon swatches as well as plain color fills.
+- 7af01bf: Add opt-in `storage-key` persistence to `<lr-table>`, `<lr-widget>`, and `<lr-app-rail>`, so layout
+  state survives a reload without every application rebuilding the same `localStorage` plumbing.
+
+  Set `storage-key` to persist `<lr-table>`'s `showAllColumns`, `<lr-widget>`'s `collapsed` state, and
+  `<lr-app-rail>`'s open state and width. The attribute is unset by default — behavior without it is
+  unchanged. All three share one internal helper with the `try`/`catch` handling needed for
+  environments where `localStorage` throws (private mode, disabled storage, cross-origin frames).
+
+- 7af01bf: Add theming tokens for surfaces that previously forced consumers through `::part()` overrides.
+
+  - `<lr-icon-button>`: `--lr-icon-button-background`, `--lr-icon-button-background-hover`, and
+    `--lr-icon-button-color`, so a bordered or tinted icon button no longer needs `::part(button)`.
+  - `<lr-button>`: `--lr-button-shadow` (default `none`) for themed elevation.
+  - `<lr-table>`: sorted-header theming tokens, plus a specificity fix so consumer `::part()` rules can
+    actually win against the internal sort-state rule.
+  - `<lr-select>` and `<lr-model-select>`: selected-state tokens; `<lr-combobox>` gains the matching
+    `option-selected` token indirection.
+  - `<lr-empty>`: `--lr-empty-compact-font-size` for compact heading typography.
+  - `<lr-typing-indicator>`: `--lr-typing-duration`, so its speed is no longer keyed off the shared
+    `--lr-transition-ambient`.
+  - `<lr-conversation-item>`: tokenized active-row indicator part.
+
+  Every token's `var()` fallback is the value it replaces, so unset rendering is unchanged.
+
+- 7af01bf: Add `@aceshooting/lyra-ui/theme.js` — a zero-dependency theme runtime and no-flash bootstrap, so
+  applications stop rebuilding mode/accent persistence by hand.
+
+  The new subpath exports `setLyraTheme(theme)`, `getLyraTheme()`, the `LyraTheme`/`LyraThemeMode`
+  (`'light' | 'dark' | 'auto'`) types, and `lyraThemeBootstrap` — a string of head-script source you
+  inline before first paint to apply the persisted theme without a flash of the wrong mode. Theme
+  changes persist to `localStorage` and announce themselves with an `lr-theme-change` event.
+
+  The runtime deliberately does not include WCAG contrast math: deriving an accessible palette from a
+  single brand color is application product logic, not a library concern.
+
+### Patch Changes
+
+- 7af01bf: Fix several rendering and correctness bugs.
+
+  - `<lr-chart>`: a `valueFormatter` no longer corrupts the **category** axis. Formatted indices
+    (`"0"`, `"1"`, `"2"`) were rendering in place of the category labels, because the tick callback was
+    wired to every axis rather than only the value axes.
+  - `<lr-diff-view>`: normalize CRLF and lone-CR line endings, so a Windows-authored file no longer
+    diffs as entirely changed.
+  - `<lr-app-rail>`: anchor the resizer to `:host`, pin `overflow-x`, and free fixed-position popups
+    that were being clipped by the rail.
+  - `<lr-button>`: collapse empty start/end adornment wrappers, which were reserving visible space for
+    slots with nothing in them.
+  - `<lr-swatch-picker>`: keep the selected glow on gemstone swatches.
+
+- a656a10: Add a tokenized active-row indicator part to `lr-conversation-item` and export it through data-mode `lr-thread-list` rows.
+- 203cbce: Forward host `aria-describedby` values to `lr-checkbox`'s internal checkbox role.
+- 983dd04: Validate download anchors against a stricter URL allowlist than navigation anchors. A `mailto:` URL
+  is a legitimate navigation destination but names no retrievable bytes, so pairing it with a
+  `download` attribute produced an affordance that could never download anything.
+
+  `safeDownloadHref()` (internal) is now `safeLinkHref()` minus `mailto:`, and the download sinks use
+  it: `<lr-document-viewer>` and `<lr-document-preview>` omit their download link for a `mailto:`
+  `src`, `<lr-media-card>` falls back to its inert file chip, and `<lr-button>` falls back to the
+  native `<button>` when `download` is set alongside a `mailto:` `href` (a `mailto:` href _without_
+  `download` still renders the anchor, unchanged).
+
+  Behavior change: the `safeLinkHref()` re-exported from the package root is `<lr-media-card>`'s
+  download-sink wrapper, so it now returns `null` for `mailto:` where it previously returned the URL.
+  The general-purpose navigation validator is unchanged.
+
+- 88dfe78: Add `LyraTreeEventMap` so `<lr-tree>`'s `lr-node-toggle`, `lr-node-select`, and `lr-reorder` events are typed on listeners (`addEventListener`), matching every other component with public events.
+- a595ec7: Give `<lr-widget>`'s collapse-button `aria-label` its own dedicated locale keys,
+  `widgetCollapse`/`widgetExpand`, instead of borrowing `<lr-dock-panel>`'s `dockPanelCollapse`/
+  `dockPanelExpand`. Default English strings are unchanged ("Collapse panel"/"Expand panel"). If you
+  had registered a locale under the old borrowed `dockPanel*` keys specifically to translate
+  `<lr-widget>`'s collapse button, move that override to `widgetCollapse`/`widgetExpand` —
+  `<lr-dock-panel>`'s own keys and behavior are unaffected.
+
+## 6.1.0
+
+### Minor Changes
+
+- f9e1e18: Make `lr-app-rail`'s `lr-toggle` event cancelable: a listener calling `preventDefault()` keeps the
+  rail open/closed as it was. The one exception is the forced close that fires when `mode` leaves
+  `'mobile'` while open, which stays unconditional since it's a consistency fix-up rather than a
+  user dismissal.
+- f9e1e18: Add themeable `--*-gap`/`--*-radius` CSS custom properties to `lr-input`, `lr-select`, and
+  `lr-combobox` (gap + radius), `lr-chip`/`lr-badge`/`lr-tag` (radius), and `lr-icon-button`
+  (radius) — extending the pattern `lr-button` already shipped, so these values can be retuned
+  without a `::part()` override. Every default is unchanged.
+- f6d966e: Add an optional `country` field to `lr-locale-picker`'s `locales` catalog entries, letting a
+  consumer override a row's derived flag (e.g. showing Lebanon's flag for an `ar` row instead of
+  the library's default Saudi Arabia mapping).
+- 3c9f478: Make `lr-reorder-list`'s `lr-reorder` event cancelable: a listener calling `preventDefault()`
+  holds the move (reflecting `pending` on the affected `lr-reorder-item`) until the host calls the
+  new `finalizePendingMove()`/`revertPendingMove()` methods — mirroring `lr-confirm-bar`'s cancelable
+  approve/deny pattern, for hosts that persist the new order asynchronously.
+- f9e1e18: Make `lr-token-input`'s `lr-remove` event cancelable: a listener calling `preventDefault()` (for
+  example to run async removal validation, or to protect a token) keeps the token in place instead
+  of it being removed unconditionally. Scoped to direct removal; multi-candidate paste/edit flows
+  are unaffected.
+
+### Patch Changes
+
+- a4c4825: Fix `lr-agent-workspace` never emitting its documented `lr-retrieval-select` event when a row is
+  selected in the built-in retrieval results, and leaking the internal `lr-retrieval-results`'s raw
+  `lr-select` event through under the wrong name instead.
+- f9e1e18: Fix `lr-date-input`'s `selectionDirection` getter returning `undefined` instead of `null` before
+  the internal input has rendered, despite its declared `LyraDateInputSelectionDirection | null`
+  return type.
+- 2dabe8e: Fix `lr-icon-button`'s bare-SVG-geometry fallback rendering slotted stroke-style icon path data
+  (no fill/stroke of its own) as a solid black shape instead of an outline, by giving
+  `[part="fallback"]` the same `fill`/`stroke`/`stroke-width`/`stroke-linecap`/`stroke-linejoin`
+  defaults `lr-icon`'s own wrapper svg already has.
+- f9e1e18: Fix `lr-retrieval-results` and `lr-menu` leaking a wrapped child's own event under the wrong
+  name alongside the documented, consolidated one: `lr-retrieval-results` leaked `lr-virtual-list`'s
+  `lr-load-more` and `lr-chunk-inspector`'s `lr-chunk-open` (the latter also carrying an
+  undocumented extra `anchor` field); `lr-menu` leaked `lr-menu-item`'s raw `lr-menu-item-select`
+  alongside the documented `lr-menu-select`.
+- cc90b3a: Fix two `lr-thread-list` bugs: a row click fired `lr-select` twice (the correct re-emit plus the
+  original bare event leaking through unstopped), and content slotted into `slot="empty"` rendered
+  unconditionally instead of only when the list has zero visible threads.
+
 ## 6.0.0
 
 ### Major Changes

package/README.md

@@ -1,4 +1,4 @@
-# Lyra UI
+# Lyra UI: UI, made light 🪶 ✨
 
 [![CI](https://github.com/aceshooting/lyra-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/aceshooting/lyra-ui/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/aceshooting/lyra-ui/branch/main/graph/badge.svg)](https://codecov.io/gh/aceshooting/lyra-ui)
@@ -27,7 +27,7 @@
 **Lyra UI — the free, independent web-component alternative.** A MIT-licensed [Lit](https://lit.dev)
 library for accessible forms, dashboards, charts, data visualization, and Conversation & Agent UI.
 It is a practical open-source alternative to [Shoelace](https://shoelace.style/) and
-[Web Awesome](https://webawesome.com/), with 251 custom elements, native custom-element APIs,
+[Web Awesome](https://webawesome.com/), with 256 custom elements, native custom-element APIs,
 tree-shakeable imports, its own `--lr-*` design tokens, built-in localization and RTL support,
 and no runtime dependency on either project.
 
@@ -137,7 +137,7 @@ from `custom-elements.json`.
 
 **Claude Code users:** this repo is also a plugin marketplace — installing the `lyra-ui` plugin gives
 Claude the same reference as a skill, plus `/lyra-ui:migrate-from-wa`,
-`/lyra-ui:migrate-from-shoelace` and `/lyra-ui:update-lyra` commands.
+`/lyra-ui:migrate-from-shoelace` and `/lyra-ui:update` commands.
 
 **Contributing to this repo itself?** See [`../../AGENTS.md`](../../AGENTS.md) instead — that's a
 contributor guide for agents working *on* lyra-ui, not the same document as the above.
@@ -354,7 +354,7 @@ coverage automatically from the bundled `web-types.json` — JetBrains IDEs pick
 
 ## Components
 
-The catalog below lists all 251 tags in the current Custom Elements Manifest, grouped by
+The catalog below lists all 256 tags in the current Custom Elements Manifest, grouped by
 capability. The manifest and live docs are the authoritative sources for the complete generated
 API details.
 
@@ -461,6 +461,7 @@ API details.
 | `<lr-knowledge-graph-explorer>` | — (extra) | Orchestration-level surface for exploring a knowledge graph — the `lr-graph` canvas plus entity search, type filters, neighborhood expansion, pinned nodes, path finding between pins, and a details overlay; composes `lr-graph`, `lr-graph-legend`, `lr-entity-card`, `lr-neighbor-list`, `lr-path-strip`, and `lr-popover.showAt()` rather than re-implementing graph rendering itself |
 | `<lr-graph-query-builder>` | — (extra) | Editor for a single typed relationship/path filter (`GraphQuery`) over a knowledge graph — start/end entity anchors, relationship-type and node-type pickers with a removable active-filter chip display, a traversal direction, a min/max hop range, validation, and a host-persisted saved-query list; a serializable query model for GraphRAG workflows |
 | `<lr-entity-dossier>` | — (extra) | Full entity detail surface — a persistent header (`lr-entity-card` plus a confidence `lr-stat`) above an `lr-tabs` strip for Relationships (`lr-neighbor-list`), Supporting chunks (`lr-chunk-inspector`), and Provenance (`lr-provenance-panel`); pure layout, never fetches or mutates graph/document state |
+| `<lr-embedding-explorer>` | — (extra) | Accessible SVG projection of host-provided embedding points with cluster coloring, filtering, roving keyboard focus, and `lr-point-select`; it never computes embeddings or owns dimensionality reduction |
 
 **Retrieval & grounding**
 
@@ -471,6 +472,7 @@ API details.
 | `<lr-retrieval-trace>` | — (extra) | Retrieval pipeline's stage timeline (query rewriting, embedding, retrieval, reranking, filtering) rendered through `lr-span-waterfall`, plus a disclosure list exposing each stage's evidence (chunks via `lr-chunk-inspector`, free-form text, and/or metadata); never fetches or computes retrieval results itself |
 | `<lr-grounding-summary>` | — (extra) | Claim-level scorecard for one generated answer — supported/unsupported claim counts, citation coverage, an optional confidence score, warnings, and (when supplied) a list of evidence citations; composes `lr-stat` and `lr-citation-badge`, pure projection and event conduit |
 | `<lr-context-inspector>` | — (extra) | Inspection view of the exact context assembled for a model call — per-segment token estimates via `lr-context-meter`, source attribution via `lr-citation-badge`, copy/export affordances, and truncation-boundary/redaction-marker rendering; pure projection, never fetches, estimates, or redacts itself |
+| `<lr-rag-answer>` | — (extra) | Grounded answer surface composing sanitized Markdown, claim-level grounding summary, citation badges, and source cards; controlled, localized, and emits citation/retry events without fetching data |
 
 **Knowledge base & document management**
 
@@ -480,6 +482,7 @@ API details.
 | `<lr-ingestion-queue>` | — (extra) | Controlled list of documents moving through an ingestion pipeline (upload → text extraction → chunking → embedding → indexing), each row showing its stage, progress, chunk/embedding counts, and a retry or cancel affordance; presentation only, virtualizes at or above `virtualizeThreshold` items |
 | `<lr-document-library>` | — (extra) | Searchable, filterable inventory of documents with versions, tags, owners, freshness, and bulk selection; composes `lr-table` for the grid and `lr-input`/`lr-combobox` for search and tag-facet filtering — a controlled data view, no upload/sync/mutation of its own |
 | `<lr-document-compare>` | — (extra) | Side-by-side or inline comparison of two document versions, composed from `lr-diff-view` (`view="diff"`, the default) and `lr-document-preview` (`view="side-by-side"`), with proportional scroll sync and matching-highlight activation keeping the two independent preview panes aligned |
+| `<lr-knowledge-base-admin>` | — (extra) | Tabbed knowledge-base operations shell composing source management and ingestion queue views; controlled, action-forwarding, and suitable for host-owned settings content |
 
 **Agent runs & observability**
 
@@ -491,6 +494,7 @@ API details.
 | `<lr-tool-timeline>` | — (extra) | Chronological list of an agent run's tool/function calls, each rendered through `lr-tool-call-chip` (name/status/duration) and `lr-tool-result-view` (args/result), with per-entry retry counts, sensitive-field redaction, and a shared `lr-tool-approval-dialog` for entries gated behind human approval |
 | `<lr-memory-panel>` | — (extra) | Agent working-memory surface — short-term context and long-term memories, each item's confidence and optional grounding provenance via `lr-provenance-panel`, with add/remove/forget actions gated behind an `lr-confirm-bar` confirmation step |
 | `<lr-policy-summary>` | — (extra) | Read-only list of guardrail, permission, privacy, and tool-policy decisions (`allow`/`deny`/`needs-review`), each with an always-visible, accessible explanation never conveyed by color alone; composes `lr-badge` and `lr-callout`, with `lr-details` for optional richer detail |
+| `<lr-approval-queue>` | — (extra) | Keyboard-accessible pending human-approval list composing `lr-tool-approval-dialog`; forwards namespaced selection, decision, and close events without owning persistence |
 
 **Dashboards & orchestration**
 
@@ -508,6 +512,7 @@ API details.
 | `<lr-eval-dataset>` | — (extra) | Dataset management for an evaluation suite — a filterable/taggable list of `EvalExample` rows via `lr-table`, an `lr-chip`/`lr-chip-group` tag-based browse filter, and add/remove/import/export affordances; fully controlled, never mutates `examples` or performs I/O itself |
 | `<lr-evaluation-run>` | — (extra) | Evaluation batch's live progress — an overall `lr-progress-bar` counting terminal (done/error/cancelled) examples against the batch total, plus one `lr-details` disclosure per example showing input/output, an optional `lr-grounding-summary`, and an optional `lr-tool-timeline` |
 | `<lr-eval-result>` | — (extra) | Rubric scoring, human review, and comparison across a single evaluation example's runs — composes `lr-table` for the runs comparison table, `lr-rubric-form` for the selected run's human-review scoring, and `lr-diff-view` to compare a run's output against a baseline run |
+| `<lr-agent-eval-dashboard>` | — (extra) | Evaluation metric dashboard with locale-aware KPI cards, optional trend chart, and selectable run history; controlled and emits metric/run selection events |
 
 **Overlays**
 
@@ -519,11 +524,11 @@ API details.
 
 | Component | Mirrors | Notes |
 |-----------|---------|-------|
-| `<lr-chart>` | `wa-chart` | Core Chart.js wrapper (`Series`-based, plus raw `config` passthrough) — needs the optional peer deps `chart.js`, `chartjs-plugin-zoom` |
+| `<lr-chart>` | `wa-chart` | Core Chart.js wrapper (`Series`-based, plus raw `config` passthrough) with bounded `appendData()` streaming and `exportData('csv'|'png')` — needs the optional peer deps `chart.js`, `chartjs-plugin-zoom` |
 | `<lr-bar-chart>`, `<lr-line-chart>`, `<lr-pie-chart>`, `<lr-doughnut-chart>`, `<lr-scatter-chart>`, `<lr-bubble-chart>`, `<lr-radar-chart>`, `<lr-polar-area-chart>` | `wa-chart` | Typed `<lr-chart>` subclasses with `type` locked — same optional peer deps as `<lr-chart>` |
 | `<lr-box-plot>` | — (extra) | Box-and-whisker chart from precomputed five-number summaries — needs `chart.js`, `chartjs-plugin-zoom`, and `@sgratzl/chartjs-chart-boxplot` |
 | `<lr-histogram>` | — (extra) | Bins raw values (`binValues()`) and renders a bar chart — same optional peer deps as `<lr-chart>` |
-| `<lr-lite-chart>` | — (extra) | Dependency-free bar/line chart (plain SVG/DOM) — **no optional peer deps**, for projects that forbid a charting dependency outright |
+| `<lr-lite-chart>` | — (extra) | Dependency-free bar/line chart (plain SVG/DOM) with bounded `appendData()` streaming and `exportData('csv'|'svg')` — **no optional peer deps**, for projects that forbid a charting dependency outright |
 
 **Map & file-input**