# @aceshooting/lyra-ui

> Free, independent, MIT-licensed Lit web components — an open-source alternative to Shoelace and
> Web Awesome. Lyra combines accessible form controls, layout and overlay primitives, dashboards,
> charts, data visualization, document viewers, and Conversation & Agent UI. Selected components
> keep documented Web Awesome-compatible public names under a `lr-` prefix to ease migration; the
> implementation, design tokens, localization runtime and release surface are standalone.

Every component styles itself through this library's own `--lr-theme-*` design tokens with hardcoded
fallbacks, so it works standalone with no theme or runtime dependency.

## Which file to read

Prefer the narrow file. `llms-full.txt` is the whole catalog concatenated and costs several hundred
thousand tokens; you almost never want all of it. `llms/index.md` is the source of truth for the
current element count and complete tag list.

- [llms/index.md](./llms/index.md): every tag, its exact import path, and a one-line purpose —
  **start here** to pick a component.
- [llms/components/<tag>.md](./llms/components/): the full API of one component (properties,
  events, slots, CSS parts, themeable custom properties, usage snippet, gotchas). The path is
  derived from the tag name, so no search is needed: `llms/components/lr-table.md`.
- [llms/shared.md](./llms/shared.md): library-wide behavior — status/deprecation, importing and the
  guarded autoloader, events, forms, theming/native styles, localization/RTL, TypeScript/frameworks,
  SSR, shared utilities, the `@aceshooting/lyra-ui/ai` data types, and testing.
- [llms/tokens.md](./llms/tokens.md): every design token, including its theme input and fallback or
  its derived value, as applicable.
- [llms/peers.md](./llms/peers.md): which optional peer dependency each component needs.
- [llms/migration.md](./llms/migration.md): every pinned `wa-*`/`sl-*` mapping's
  exact/rewritten/warning/conceptual/unsupported decision and safe codemod rules.
- [CHANGELOG.md](./CHANGELOG.md): chronological release notes, including breaking changes and
  post-major minor/patch additions and fixes — read it before upgrading.
- [llms-full.txt](./llms-full.txt): all of the above component sections in one file.
- [README.md](./README.md): install, catalog, theming, accessibility, and package-level commands.
- [Live docs site](https://aceshooting.github.io/lyra-ui/): interactive examples per component —
  useful for a human reviewer, redundant for an assistant reading these files.

Claude Code users can install the matching skill (component APIs, theming rules, migration
codemods) from the marketplace at <https://github.com/aceshooting/lyra-ui>.

## Rules that apply to every component

- Prefer the stable tag-shaped registration path
  `@aceshooting/lyra-ui/components/<tag>.js`, for example `components/lr-input.js`. Existing
  family-shaped registration paths remain supported; class-only and helper modules still use their
  owning family paths. `llms/index.md` lists the exact supported paths.
- Theme only by setting `--lr-theme-*` custom properties; never hardcode a value that fights them.
- Lyra-specific events are `lr-`-prefixed `CustomEvent`s, bubbling and composed, with payload on
  `event.detail`; native wrappers may also relay the exact native events listed in their sections.
- Form controls are form-associated: they participate in native `<form>` submission and validation.
- Every built-in string is localizable via `registerLyraLocale()` or a per-instance `.strings`.
- Locale selection does not set writing direction; inherit an explicit `dir="rtl"` for RTL layout.

## When no component fits, file it

Check `llms/index.md` first — most apparent gaps are a different name, not a missing component. If
nothing fits, **ask the user for explicit agreement before filing anything** (filing sends their
description to an external service — never do it as a silent side effect of noticing a gap), then
`POST` to `https://www.lyra-ui.com/api/v1/feature-requests` with `title`, `description`, and
`searched_for` (the terms tried). `name`/`email` are accepted but optional contact fields — ask the
user before adding either, and never invent, guess, or reuse one from context. The response's
`matches` often names an existing component — read it before telling the user the gap is real. See
`llms/shared.md`'s "When no component fits, file it" for the full payload, response shape, and
privacy rules.

## Component catalog

- **Form controls & inputs** (`components/forms/`, 29) — `lr-combobox`, `lr-option`, `lr-select`, `lr-date-picker`, `lr-date-input`, `lr-textarea`, `lr-button`, `lr-icon-button`, `lr-input`, `lr-number-input`, `lr-time-input`, `lr-native-time-input`, `lr-phone-input`, `lr-time-range`, `lr-swatch-picker`, `lr-checkbox`, `lr-switch`, `lr-slider`, `lr-radio`, `lr-radio-button`, `lr-otp-input`, `lr-radio-group`, `lr-checkbox-group`, `lr-token-input`, `lr-code-editor`, `lr-color-picker`, `lr-emoji-picker`, `lr-rubric-form`, `lr-locale-picker`

- **Data display, dashboards & flow canvas** (`components/data/`, 26) — `lr-sparkline`, `lr-stat`, `lr-data-grid`, `lr-table`, `lr-pagination`, `lr-gauge`, `lr-funnel`, `lr-word-cloud`, `lr-heatmap`, `lr-sequence-strip`, `lr-tree`, `lr-tree-item`, `lr-flow-canvas`, `lr-flow-node`, `lr-flow-minimap`, `lr-flow-controls`, `lr-flow-run-status`, `lr-context-meter`, `lr-calendar`, `lr-timeline`, `lr-timeline-item`, `lr-file-tree`, `lr-env-list`, `lr-document-library`, `lr-graph-query-builder`, `lr-condition-builder`

- **Layout, navigation & structure** (`components/layout/`, 36) — `lr-multi-split`, `lr-split-panel`, `lr-widget`, `lr-carousel`, `lr-carousel-item`, `lr-button-group`, `lr-scroller`, `lr-tab-group`, `lr-stepper`, `lr-tab`, `lr-tab-panel`, `lr-control-group`, `lr-reorder-list`, `lr-reorder-item`, `lr-segmented`, `lr-virtual-list`, `lr-app-rail`, `lr-app-rail-item`, `lr-app-rail-group`, `lr-responsive-panel`, `lr-menu-label`, `lr-menu`, `lr-menu-item`, `lr-dropdown-item`, `lr-dock-panel`, `lr-card`, `lr-command-palette`, `lr-details`, `lr-accordion`, `lr-accordion-item`, `lr-breadcrumb`, `lr-breadcrumb-item`, `lr-dashboard-grid`, `lr-drilldown-panel`, `lr-filter-bar`, `lr-page`

- **Overlays, status & feedback** (`components/overlays/`, 21) — `lr-toast`, `lr-toast-item`, `lr-empty`, `lr-skeleton`, `lr-drawer`, `lr-dialog`, `lr-chip`, `lr-chip-group`, `lr-kbd`, `lr-popup`, `lr-popover`, `lr-tooltip`, `lr-dropdown`, `lr-spinner`, `lr-progress-bar`, `lr-progress-ring`, `lr-badge`, `lr-tag`, `lr-alert`, `lr-callout`, `lr-rating`

- **Utilities, formatting & observers** (`components/utility/`, 20) — `lr-export-button`, `lr-copy-button`, `lr-resize-observer`, `lr-intersection-observer`, `lr-mutation-observer`, `lr-json-viewer`, `lr-live-region`, `lr-poll-status`, `lr-mention-popover`, `lr-diff-view`, `lr-icon`, `lr-visually-hidden`, `lr-divider`, `lr-format-number`, `lr-format-date`, `lr-format-bytes`, `lr-relative-time`, `lr-known-date`, `lr-random-content`, `lr-tour`

- **Media, files & maps** (`components/media/`, 22) — `lr-flag`, `lr-sequence-playback`, `lr-map`, `lr-drop-zone`, `lr-file-input`, `lr-image-comparer`, `lr-zoomable-frame`, `lr-pan-zoom`, `lr-attachment-chip`, `lr-file-icon`, `lr-media-card`, `lr-attachment-trigger`, `lr-avatar`, `lr-animated-image`, `lr-animation`, `lr-avatar-group`, `lr-lightbox`, `lr-qr-code`, `lr-image-viewer`, `lr-av-player`, `lr-video`, `lr-video-playlist`

- **Charts** (`components/charts/`, 12) — `lr-chart`, `lr-lite-chart`, `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`, `lr-histogram`, `lr-box-plot`

- **Document & file viewers** (`components/viewers/`, 23) — `lr-document-preview`, `lr-document-viewer`, `lr-docx-viewer`, `lr-email-viewer`, `lr-calendar-viewer`, `lr-archive-viewer`, `lr-ebook-viewer`, `lr-pptx-viewer`, `lr-svg-viewer`, `lr-html-viewer`, `lr-dataset-viewer`, `lr-contact-viewer`, `lr-pdf-viewer`, `lr-spreadsheet-viewer`, `lr-csv-viewer`, `lr-include`, `lr-highlight-layer`, `lr-page-rail`, `lr-notebook-viewer`, `lr-xml-viewer`, `lr-document-compare`, `lr-geojson-viewer`, `lr-geojson-view`

- **Conversation & chat UI** (`components/conversation/`, 34) — `lr-markdown`, `lr-markdown-core`, `lr-chat-message`, `lr-typing-indicator`, `lr-chat-composer`, `lr-stream-status`, `lr-conversation-item`, `lr-model-select`, `lr-streaming-text`, `lr-streaming-text-core`, `lr-generation-metrics`, `lr-code-block`, `lr-code-block-core`, `lr-model-settings-panel`, `lr-audio-visualizer`, `lr-branch-picker`, `lr-message-actions`, `lr-message-feedback`, `lr-push-to-talk`, `lr-transcript-feed`, `lr-handoff-divider`, `lr-chat-viewport`, `lr-suggestion-chips`, `lr-thread-list`, `lr-checkpoint`, `lr-usage-badge`, `lr-widget-renderer`, `lr-voice-picker`, `lr-agent-workspace`, `lr-message-parts`, `lr-prompt-input`, `lr-prompt-queue`, `lr-selection-toolbar`, `lr-realtime-session`

- **Agent tooling, tool calls & evaluation** (`components/agent-tools/`, 35) — `lr-tool-call-chip`, `lr-tool-result-view`, `lr-tool-result-dialog`, `lr-tool-select-dialog`, `lr-thinking-panel`, `lr-stack-trace`, `lr-tool-approval-dialog`, `lr-tool-param-form`, `lr-result-card`, `lr-result-field`, `lr-compare-panel`, `lr-span-waterfall`, `lr-task-list`, `lr-terminal`, `lr-trace-tree`, `lr-activity-feed`, `lr-commit-card`, `lr-test-results`, `lr-confirm-bar`, `lr-browser-frame`, `lr-artifact-panel`, `lr-agent-run`, `lr-agent-trace`, `lr-context-inspector`, `lr-eval-dataset`, `lr-eval-result`, `lr-eval-run`, `lr-policy-summary`, `lr-tool-timeline`, `lr-agent-eval-dashboard`, `lr-approval-queue`, `lr-mcp-app`, `lr-prompt-studio`, `lr-json-schema-viewer`, `lr-subagent-panel`

- **Retrieval, knowledge graph & grounding** (`components/retrieval/`, 30) — `lr-graph`, `lr-node-palette`, `lr-graph-legend`, `lr-entity-card`, `lr-entity-chip`, `lr-neighbor-list`, `lr-path-strip`, `lr-community-card`, `lr-chunk-inspector`, `lr-source-picker`, `lr-provenance-panel`, `lr-mind-map`, `lr-citation-badge`, `lr-source-list`, `lr-source-card`, `lr-entity-dossier`, `lr-grounding-summary`, `lr-ingestion-queue`, `lr-knowledge-base`, `lr-knowledge-graph-explorer`, `lr-memory-panel`, `lr-retrieval-results`, `lr-retrieval-search`, `lr-retrieval-trace`, `lr-rag-answer`, `lr-embedding-explorer`, `lr-knowledge-base-admin`, `lr-claim-evidence`, `lr-retrieval-compare`, `lr-rag-eval-dashboard`