@aceshooting/lyra-ui 2.12.0 → 3.0.0

package/README.md

@@ -2,24 +2,18 @@
 
 [![CI](https://github.com/aceshooting/lyra-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/aceshooting/lyra-ui/actions/workflows/ci.yml)
 
-**Web Awesome, plus.** Free, clean-room [Lit](https://lit.dev) web components — a companion to
-[Web Awesome](https://webawesome.com) that provides open-source equivalents of selected,
-documented Web Awesome **Pro** surfaces (form controls, date pickers, toasts, charts, …), *plus*
-dozens of original components Web Awesome has no equivalent for at all — dashboard atoms, a chart
-family, temporal/graph/map visualizations, and (newest) a full **Conversation & Agent UI** family
-for building chat/agent products: message bubbles, streaming text, tool-call chips and approval
-dialogs, citations, model/settings pickers, and more. Token-compatible with Web Awesome, so the
-mirrored components look native inside a WA app, and everything is fully usable standalone.
-
-> **Independent project.** Not affiliated with or endorsed by Web Awesome, and no `wa-` prefix or
-> Web Awesome trademark/branding is used here. For components that *do* have a Web Awesome
-> counterpart, this package gives you a free, open-source component wherever Web Awesome Pro
-> normally charges — the public API (attributes, slots, events, CSS parts) mirrors Web Awesome's
-> own documented surface under the `lyra-` prefix. Read the migration notes and component entry
-> before treating a migration as a drop-in swap — but every implementation in this package is original
-> (clean-room; no Web Awesome Pro source was ever available to or copied by this project). Most of
-> the library, and all of the Conversation & Agent UI family, has no Web Awesome counterpart to
-> mirror in the first place — see the "Mirrors" column in the tables below.
+**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 133 custom elements, native custom-element APIs,
+tree-shakeable imports, its own `--lyra-*` design tokens, built-in localization and RTL support,
+and no runtime dependency on either project.
+
+> **Independent implementation.** Lyra is not affiliated with, endorsed by, or a fork or rebrand of
+> Shoelace or Web Awesome. Selected Web Awesome-compatible components retain documented public names
+> under the `lyra-` prefix to make migration easier; component notes identify differences. Shoelace
+> users get a separate `sl-*` migration map because the APIs are not identical. No competitor runtime,
+> theme, token namespace, or source code is required by Lyra.
 
 ## Install
 
@@ -105,11 +99,12 @@ toast({ message: 'Saved', variant: 'success' });
 - **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 two above.
 
-## Migrating from Web Awesome Pro
+## Migrating from Web Awesome or Shoelace
 
-For every component marked with a `wa-*` counterpart in the "Mirrors" column, the documented
-compatible surface (attributes, slots, events, CSS parts, and custom properties) uses the same
-public names under the `lyra-` prefix. Read the component notes before migrating: for example,
+For a component marked with a `wa-*` counterpart in the "Mirrors" column, Lyra keeps the documented
+public vocabulary where practical: attributes, slots, events, CSS parts, and custom properties use
+the same names under the `lyra-` prefix. This makes many migrations a predictable import and tag-name
+change, while the component notes remain authoritative for intentional differences. For example,
 Lyra's combobox uses `with-clear`, while Web Awesome's equivalent uses `clearable`.
 
 ```
@@ -117,6 +112,25 @@ Lyra's combobox uses `with-clear`, while Web Awesome's equivalent uses `clearabl
 <wa-date-input value="2026-07-15">           →  <lyra-date-input value="2026-07-15">
 ```
 
+Shoelace is now a historical predecessor to Web Awesome, but its component vocabulary remains
+familiar to many teams. Lyra provides a conceptual migration path rather than claiming a drop-in
+`sl-*` replacement:
+
+| Shoelace | Lyra | Migration note |
+|---|---|---|
+| `<sl-button>` | `<lyra-button>` | Check `variant`, `appearance`, and loading behavior. |
+| `<sl-input>` / `<sl-textarea>` | `<lyra-input>` / `<lyra-textarea>` | Preserve the native editing and form contract; review label/error markup. |
+| `<sl-select>` / `<sl-option>` | `<lyra-select>` / `<lyra-option>` | Review option and value events. |
+| `<sl-dialog>` / `<sl-drawer>` | `<lyra-dialog>` / `<lyra-drawer>` | Review close reasons, focus behavior, and slots. |
+| `<sl-card>` / `<sl-badge>` / `<sl-callout>` | `<lyra-card>` / `<lyra-badge>` / `<lyra-callout>` | Review appearance tokens and dismiss events. |
+| `<sl-spinner>` / `<sl-progress-bar>` | `<lyra-spinner>` / `<lyra-progress-bar>` | Built-in status copy is localized through Lyra's runtime. |
+
+For either migration, update the package import, replace the custom-element prefix, run the
+component's accessibility story, and check its API notes for behavior that cannot be inferred from
+the tag name alone. Lyra's own `--lyra-theme-*` variables are the only theme inputs it reads. For a
+staged Web Awesome migration, map existing values explicitly in application CSS; Lyra does not read
+competitor token variables itself.
+
 Everything else in the tables below — marked `— (extra)` — has no Web Awesome equivalent to
 migrate *from* in the first place, so there's nothing to rename: install the package and import
 what you need (see Usage above). That's most of this library, including every dashboard atom
@@ -130,9 +144,43 @@ Awesome has no chat/agent UI component family at all.
 Every component is built on the same three guarantees, verified across the whole library rather
 than opt-in per component:
 
-**Theming.** Components read Web Awesome's `--wa-*` design tokens (with `--lyra-*` fallbacks).
-Inside a WA app they inherit your theme automatically; standalone, they use sensible defaults —
-override any `--lyra-*`/`--wa-*` custom property to retheme.
+**Theming.** Components read independent `--lyra-theme-*` variables and standalone defaults. Lyra
+does not depend on another library's theme or token namespace. For a ready-made light/dark base
+theme, import `@aceshooting/lyra-ui/theme.css` once and toggle `.lyra-light`/`.lyra-dark` (or the
+matching `data-lyra-theme` attribute) on an ancestor:
+
+```css
+@import '@aceshooting/lyra-ui/theme.css';
+```
+
+```html
+<body class="lyra-dark">
+  <lyra-button variant="brand">Save</lyra-button>
+</body>
+```
+
+Applications can override any `--lyra-theme-*` input directly:
+
+```css
+:root {
+  --lyra-theme-color-surface-default: #101827;
+  --lyra-theme-color-text-normal: #f8fafc;
+  --lyra-theme-color-brand-fill-loud: #60a5fa;
+  --lyra-theme-font-size-m: 1rem;
+  --lyra-theme-border-radius-m: 0.5rem;
+}
+```
+
+See `internal/tokens.styles.ts` for the complete shared token list. Component-specific `--lyra-*`
+custom properties remain available for local overrides.
+
+**Frontend quality guarantees.** Every component is designed as a native custom element and tested
+for the contract that applies to its shape: semantic roles and accessible names inside shadow DOM,
+keyboard navigation, bubbling/composed public events, native form association and validity, logical
+CSS for RTL, narrow-container layouts, reduced motion, and forced-colors behavior. Form controls
+expose label, hint, error, focus, editing, reset, and validity behavior instead of hiding the useful
+native contract behind a private input. Heavy integrations such as Chart.js, MapLibre, D3, Shiki,
+Markdown, phone-number metadata, and flag artwork remain optional peer dependencies.
 
 **Internationalization.** Every built-in string (button labels, status announcements,
 `aria-label`s) resolves through a small runtime, in two ways you can combine:
@@ -154,14 +202,23 @@ No rebuild, no per-locale bundle, no per-component API to learn — register the
 every component that uses that key picks it up reactively, including ones added after your app's
 first render.
 
+Lyra's default messages are English fallbacks, while applications own the translated catalog. Date,
+number, byte, relative-time, and calendar formatting use the browser's `Intl` APIs and the resolved
+locale. Consumer-provided labels, values, file names, and message content are never altered by the
+localization layer. The same runtime also covers accessible names, descriptions, validation messages,
+live-region announcements, empty states, status labels, and action buttons; use `.strings` for a
+component-specific override when needed.
+
 **RTL.** Set `dir="rtl"` on `<html>` or any ancestor (or just a `lang` whose default direction is
 RTL, e.g. `ar`/`he`/`fa`) — every component mirrors its layout automatically via CSS logical
 properties and swaps directional keyboard navigation (e.g. the arrow keys in a date grid or a
-roving-tabindex list) to match. No per-component RTL flag or opt-in needed.
+roving-tabindex list) to match. This covers Arabic, Hebrew, Persian, Urdu, and other RTL locales
+through inherited direction; no per-component RTL flag or opt-in is needed. Components do not force
+their own `dir`, so they remain composable inside mixed-direction layouts.
 
 ## Components
 
-The catalog below lists all 97 tags in the current Custom Elements Manifest, grouped by
+The catalog below lists all 133 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.
 
@@ -178,7 +235,12 @@ API details.
 | `<lyra-sparkline>` | `wa-sparkline` | Zero-dependency inline SVG |
 | `<lyra-textarea>` | `wa-textarea` | Form-associated multiline field with label/hint/error chrome, auto-resize, native editing passthrough, and caret APIs |
 | `<lyra-input>` | `wa-input` | Form-associated single-line field (`text`/`password`/`email`/`number`) with label/hint/error chrome and a built-in password-visibility toggle |
+| `<lyra-number-input>` + `<lyra-time-input>` | `wa-number-input` / `wa-time-input` | Native number/time aliases retaining Lyra form and event contracts |
+| `<lyra-color-picker>` | `wa-color-picker` | Form-associated native color picker with label/hint chrome |
 | `<lyra-button>` | `wa-button` | Generic action-button primitive (`variant`/`appearance`/`size`/`loading`), owns `type="submit"`/`"reset"` via the closest ancestor `<form>` |
+| `<lyra-radio>` + `<lyra-radio-group>` | `wa-radio` / `wa-radio-group` | Form-associated single-choice controls with roving arrow-key navigation and group validation |
+| `<lyra-spinner>` | `wa-spinner` | Localized indeterminate busy indicator with reduced-motion support |
+| `<lyra-progress-bar>` + `<lyra-progress-ring>` | `wa-progress-bar` / `wa-progress-ring` | Determinate or indeterminate progress indicators |
 | `<lyra-flag>` | — (extra) | Country/language flags for i18n pickers — needs the optional peer `@aceshooting/lyra-flags` |
 
 **Dashboard atoms**
@@ -187,8 +249,12 @@ API details.
 |-----------|---------|-------|
 | `<lyra-empty>` | — (extra) | Generic empty/no-data state |
 | `<lyra-skeleton>` | — (extra) | Loading placeholder (pulse/sheen) |
+| `<lyra-scroller>` | `wa-scroller` | Responsive overflow surface with optional navigation controls |
+| `<lyra-resize-observer>` | `wa-resize-observer` | Lifecycle-managed ResizeObserver for slotted elements |
+| `<lyra-intersection-observer>` | `wa-intersection-observer` | Lifecycle-managed IntersectionObserver for slotted elements |
+| `<lyra-mutation-observer>` | `wa-mutation-observer` | Lifecycle-managed MutationObserver for slotted elements |
 | `<lyra-stat>` | — (extra) | KPI/stat card with trend pill and an optional breakdown row list; either can carry an `exactValue` shown as a hover/focus tooltip alongside the rounded/formatted display value |
-| `<lyra-table>` | — (extra) | Presentational, sort/select-aware data table; a column's responsive `priority` (`medium`/`low`) hides it first as the container narrows, with a reveal-columns button to force hidden columns back |
+| `<lyra-table>` | — (extra) | Sort/select-aware data table with optional controlled filtering, client/server-friendly pagination, loading state, consumer-owned inline editing, expandable rows, sticky columns, and responsive `priority` columns |
 | `<lyra-pagination>` | — (extra) | Controlled previous/next and validated page-jump navigation with a localized range summary, loading/empty states, RTL icons, and container-responsive stacking |
 | `<lyra-gauge>` | — (extra) | Radial, full-circle ring, or linear meter with a per-instance fill token |
 | `<lyra-export-button>` | — (extra) | Injection-safe CSV/JSON downloads plus event-handled custom format descriptors and controlled busy state |
@@ -196,6 +262,10 @@ API details.
 | `<lyra-split>` | — (extra) | Resizable panel layout; one pane can opt into responsive `collapse` (`"start"`/`"end"`) to a fixed-width rail, then a floating overlay card, as the split's container narrows |
 | `<lyra-widget>` | — (extra) | Card shell with collapsible header, fullscreen, and customizable chrome |
 | `<lyra-word-cloud>` | — (extra) | Zero-dependency SVG word/tag cloud, spiral-placed by weight |
+| `<lyra-badge>` + `<lyra-tag>` | `wa-badge` / `wa-tag` | Compact semantic status labels |
+| `<lyra-callout>` | `wa-callout` | Dismissible inline status, warning, and error message surface |
+| `<lyra-divider>` | `wa-divider` | Horizontal or vertical semantic separator |
+| `<lyra-rating>` | `wa-rating` | Keyboard-accessible star rating slider |
 
 **Temporal & graph**
 
@@ -207,6 +277,12 @@ API details.
 | `<lyra-graph>` | — (extra) | Force-directed node-link diagram with pan/zoom/drag, directed/styled relationship links, and rich accessible metadata — needs the optional peer deps `d3-force`, `d3-drag`, `d3-zoom`, `d3-selection` |
 | `<lyra-tree>` + `<lyra-tree-node>` | — (extra) | Expand/collapse hierarchy with structured icon/label/description/badge rows, optional richer accessible labels, and APG tree keyboard navigation |
 
+**Overlays**
+
+| Component | Mirrors | Notes |
+|-----------|---------|-------|
+| `<lyra-popover>` + `<lyra-tooltip>` + `<lyra-dropdown>` | `wa-popover` / `wa-tooltip` / `wa-dropdown` | Floating UI-positioned, RTL-aware overlay primitives with light dismiss and trigger ARIA wiring |
+
 **Charts**
 
 | Component | Mirrors | Notes |
@@ -265,10 +341,17 @@ each one-liner below.
 | `<lyra-slider>` | — (extra) | Numeric range control (e.g. an LLM "temperature" setting), form-associated, mirrors native `<input type="range">` semantics |
 | `<lyra-context-meter>` | — (extra) | Segmented bar/ring occupancy meter for a token budget or context window, split across labeled categories |
 | `<lyra-dialog>` + `confirm()` | — (extra) | General-purpose modal/overlay (focus-trapped, Escape/backdrop-dismissible, scroll-locking, dialog stacking); `confirm()` is a promise-based `window.confirm()` replacement built on it |
+| `<lyra-drawer>` | — (extra) | Modal panel anchored to the logical start/end edge or top/bottom, sharing dialog focus, dismissal, stacking, and scroll-lock behavior |
+| `<lyra-carousel>` | `wa-carousel` | Accessible slotted-slide carousel with keyboard navigation, indicators, looping, and reduced-motion-aware autoplay |
+| `<lyra-carousel-item>` | `wa-carousel-item` | Optional semantic slide wrapper for carousel content |
+| `<lyra-button-group>` | `wa-button-group` | Responsive semantic grouping for related action controls |
+| `<lyra-image-comparer>` | `wa-image-comparer` | Before/after slotted surfaces with a keyboard-accessible range divider |
+| `<lyra-zoomable-frame>` | `wa-zoomable-frame` | Bounded zoom and scrollable panning for slotted content or an image source |
 | `<lyra-tabs>` | — (extra) | Tab strip over direct light-DOM panels; WAI-ARIA APG automatic-activation keyboard pattern |
 | `<lyra-checkbox>` | — (extra) | Boolean form control, `role="checkbox"` with a visual/`indeterminate` mixed state |
 | `<lyra-switch>` | — (extra) | Boolean toggle-switch form control, `role="switch"` on/off semantics |
 | `<lyra-menu>` + `<lyra-menu-item>` | — (extra) | Anchored dropdown menu around a consumer-supplied trigger; WAI-ARIA "menu button" pattern with real roving focus (not a listbox) |
+| `<lyra-dropdown-item>` | `wa-dropdown-item` | Drop-in naming alias for `<lyra-menu-item>`, including checkbox items and roving focus |
 | `<lyra-chip>` + `<lyra-chip-group>` | — (extra) | Content-agnostic label pill (tag/filter/scope indicator) and a flex-wrap group with a "+N" overflow indicator |
 | `<lyra-kbd>` | — (extra) | Keyboard-shortcut chip; renders platform-appropriate glyphs (⌘ vs. Ctrl) from a single `"mod+k"`-style `keys` string |
 | `<lyra-result-card>` + `<lyra-result-field>` | — (extra) | Small bordered card + label/value row shell, for giving custom `lyra-tool-result-view` renderers a consistent look with no bespoke box |
@@ -281,6 +364,9 @@ each one-liner below.
 | `<lyra-diff-view>` | — (extra) | Real two-string line diff (LCS-aligned), rendered as interleaved unified-diff output |
 | `<lyra-poll-status>` | — (extra) | "Next scheduled refresh" countdown with a built-in pause control and live-region announcements |
 | `<lyra-code-block-core>` | — (extra) | Build-lean `lyra-code-block` variant for a consumer whose `languages` map already covers every language it renders — never references shiki's full ~200-language table |
+| `<lyra-details>` + `<lyra-accordion>` + `<lyra-accordion-item>` | `wa-details` / `wa-accordion` | Native disclosure and coordinated accordion panels |
+| `<lyra-breadcrumb>` + `<lyra-breadcrumb-item>` | `wa-breadcrumb` | Responsive navigation trail |
+| `<lyra-format-number>` + `<lyra-format-date>` + `<lyra-format-bytes>` + `<lyra-relative-time>` | `wa-format-*` / `wa-relative-time` | Locale-aware formatting primitives |
 
 ## Known limitations