@aceshooting/lyra-ui 2.13.0 → 3.1.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 148 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
 
@@ -33,6 +27,9 @@ npm install @aceshooting/lyra-ui
 # optional peer: d3-force, d3-drag, d3-zoom, d3-selection, only needed for <lyra-graph>
 # optional peer: chart.js, chartjs-plugin-zoom, only needed for the <lyra-*-chart>/<lyra-histogram> family
 # optional peer: @sgratzl/chartjs-chart-boxplot, only needed for <lyra-box-plot>
+# optional peers: mammoth and dompurify, only needed for <lyra-docx-viewer>
+#   — Mammoth converts DOCX files to semantic HTML instead of pixel-exact Word page layout.
+# optional peer: jszip, only needed for <lyra-archive-viewer>
 # optional peer: maplibre-gl, only needed for <lyra-map> — also import
 #   `maplibre-gl/dist/maplibre-gl.css` yourself once, since lyra-map only
 #   ships its own legend/popup chrome CSS, not maplibre-gl's own stylesheet.
@@ -105,11 +102,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 +115,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 +147,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 +205,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 133 tags in the current Custom Elements Manifest, grouped by
+The catalog below lists all 148 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.
 
@@ -259,7 +319,7 @@ each one-liner below.
 | `<lyra-generation-status>` | — (extra) | Ticking elapsed-time / token-count / throughput readout for an in-progress response, plus a built-in Stop button |
 | `<lyra-stream-status>` | — (extra) | Compact transport-health indicator (`idle`/`connecting`/`streaming`/`stalled`) with heartbeat-aware stall detection via `recordActivity()` |
 | `<lyra-markdown>` | — (extra) | Sanitized Markdown → HTML (GFM tables, fenced code, links); lazy-loads the optional peers `marked` + `dompurify` |
-| `<lyra-code-block>` | — (extra) | Fenced code display with a copy button; lazy-loads the optional peer `shiki` for syntax highlighting, degrades to plain `<pre><code>` without it |
+| `<lyra-code-block>` | — (extra) | Fenced code display with a copy button, optional line numbers, lazy-loaded `shiki` grammars, and built-in GreyCat/GCL highlighting |
 | `<lyra-live-region>` | — (extra) | Throttled/coalesced ARIA live-region announcer for streaming UIs, built on the reusable internal `Announcer` engine |
 | `<lyra-chat-composer>` | — (extra) | Auto-resizing message `<textarea>` + built-in send/stop button; form-associated, Enter-to-send with Shift+Enter/IME handling |
 | `<lyra-attachment-chip>` | — (extra) | Pre-send or sent file chip with thumbnail/size/upload-progress/retry; derives metadata from a real `File` or from persisted server metadata |
@@ -299,6 +359,21 @@ each one-liner below.
 | `<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 |
 | `<lyra-document-preview>` | — (extra) | Format-dispatching document/attachment viewer (`text/*`/JSON inline, `image/*` inline, else a download fallback) plus a host-driven async-conversion status shell |
+| `<lyra-document-viewer>` | — (extra) | Dialog-hosted, format-dispatching full document viewer with a pluggable renderer registry |
+| `<lyra-svg-viewer>` | — (extra) | Optional-DOMPurify sanitized inline SVG document viewer |
+| `<lyra-html-viewer>` | — (extra) | Optional-DOMPurify sanitized inline HTML document viewer |
+| `<lyra-dataset-viewer>` | — (extra) | Optional-PapaParse accessible TSV/PSV/delimited dataset table viewer |
+| `<lyra-contact-viewer>` | — (extra) | vCard contact viewer with support for multiple contacts and common fields |
+| `<lyra-pdf-viewer>` | — (extra) | Optional-PDF.js renderer with pagination, zoom, selectable text, and virtualized page canvases |
+| `<lyra-spreadsheet-viewer>` | — (extra) | Optional-SheetJS `.xlsx`/`.xls` workbook viewer with sheet tabs and virtualized rows |
+| `<lyra-csv-viewer>` | — (extra) | Optional-PapaParse CSV viewer with quoted-field support and virtualized rows |
+| `<lyra-docx-viewer>` | — (extra) | Optional-Mammoth DOCX viewer that renders sanitized semantic HTML |
+| `<lyra-email-viewer>` | — (extra) | Optional-PostalMime `.eml` viewer with sanitized HTML and plain-text fallback |
+| `<lyra-calendar-viewer>` | — (extra) | Optional-ical.js `.ics` viewer for event summaries and times |
+| `<lyra-archive-viewer>` | — (extra) | Lists `.zip` entry names and sizes using the optional `jszip` peer; no content preview |
+| `<lyra-ebook-viewer>` | — (extra) | Renders `.epub` ebooks with the optional `epubjs` peer |
+| `<lyra-pptx-viewer>` | — (extra) | Best-effort client-side `.pptx` viewer with a persistent fidelity notice |
+| `<lyra-file-icon>` | — (extra) | Tokenized, localized file-format badge with MIME and filename fallback metadata |
 | `<lyra-media-card>` | — (extra) | Lightweight inline preview for one already-sent image/video/file attachment inside a rendered chat message |
 | `<lyra-avatar>` | — (extra) | Small, fixed-size identity marker — image, or an initials fallback with `lyra-chip`-style tone recoloring |
 | `<lyra-card>` | — (extra) | Generic bordered content container (`header`/`media`/`footer`/`actions` slots) — a direct `<lyra-*>` counterpart to `wa-card` |