@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-callout.md

@@ -0,0 +1,42 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-callout`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/callout/callout.js';` (registers the tag; side-effect import)
+- **Class** `LyraCallout`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/callout/callout.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-callout`
+
+An inline status, warning, or error surface. Set `inline` for lightweight reactive form or mutation
+errors without panel chrome.
+
+**Properties:** `variant: 'neutral'|'brand'|'success'|'warning'|'danger' = 'neutral'` (reflected —
+also picks `[part="base"]`'s role: `alert` for `danger`, `status` otherwise), `heading: string = ''`,
+`closable: boolean = false` (reflected), `inline: boolean = false` (reflected), `open: boolean = true`
+(reflected — `false` renders nothing at all), and `accessibleLabel: string = ''`
+(`accessible-label`; falls back to a plain host `aria-label` attribute when unset).
+
+**Events:** cancelable `lr-close` (no detail); the callout sets `open = false` after the event
+unless a listener calls `preventDefault()`.
+
+**Slots:** default message, `heading` (rendered alongside the `heading` property), `icon`.
+
+**CSS parts:** `base`, `icon` (hidden while the `icon` slot is empty), `content`, `heading`,
+`message` (wrapper around the default slot), `close-button` (the close control's hit target, always
+at least `--lr-icon-button-size` in both the panel and `inline` treatments), `close-icon` (the
+visible "×" glyph inside it — this is what shrinks under `inline`, so the hit target never does).
+
+**Themeable custom properties:** `--lr-callout-background`, `--lr-callout-color`,
+`--lr-callout-border` — the trio each `:host([variant])` rule rewrites (same
+surface/text/border → `*-quiet`/loud/loud scheme as `lr-badge`). `inline` drops the border,
+background, and panel padding regardless of what these are set to. `--lr-callout-close-hover-bg`
+(default `var(--lr-color-brand-quiet)`) — the close button's `:hover` background, deliberately
+decoupled from `--lr-callout-background` (which every non-neutral `variant` also retargets for the
+panel itself) so a consumer can retint the hover fill — e.g. to keep it visibly distinct from a
+`variant="brand"` panel, which shares the same default token — without a collateral effect on the
+panel background, and vice versa.

package/llms/components/lr-card.md

@@ -0,0 +1,88 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/card/card.js';` (registers the tag; side-effect import)
+- **Class** `LyraCard`, also available unregistered from `@aceshooting/lyra-ui/components/layout/card/card.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-card`
+
+A generic, styled bordered content container — the "small bordered surface with padding" idiom common
+to hero highlights, clickable grid tiles, and management-list items. A direct `<lr-*>` counterpart
+to `<wa-card>`'s contract, staying slot-compatible with `lr-result-card` where they overlap.
+
+**Properties:**
+- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'outlined'`
+  (reflected) — `'outlined'` (the default) is a plain bordered surface; `'filled'` swaps the border
+  for a quiet brand-tinted background; `'filled-outlined'` keeps the border and adds that same tinted
+  background; `'accent'` drops the border for a single colored accent stripe on the leading edge;
+  `'plain'` has no border or background at all.
+- `interactive: boolean = false` (reflected) — opt-in clickable-tile behavior: the hover/focus-visible
+  treatment (border-color shift, `cursor: pointer`) plus, when `href` is **not** also set, real
+  activation semantics — `[part='base']` becomes focusable (`tabindex="0"`), responds to
+  Enter/Space, and emits `lr-card-activate`. With `href` set, the root is already a real `<a>`, so
+  native navigation *is* the activation and `lr-card-activate` never fires. `false` (the default)
+  reproduces a plain static card: no `tabindex`, no listeners, no events.
+- `href?: string` — when set, the card's root renders as a real `<a href=...>` instead of a `<div>`,
+  for a whole-card link (e.g. a wide CTA tile). Unset (the default) renders a plain `<div>`.
+
+**Events:** `lr-card-activate` (no detail) — the whole card was activated, by click or by
+Enter/Space while `[part='base']` has focus. Only fired while `interactive` is set **without**
+`href`. Never fired for an interaction that originated in a slotted control, so a card can keep its
+own action buttons (see the gotchas below).
+
+**Slots:** default (the card body), `header` (header row content, rendered above the body), `media`
+(media content, e.g. an image, rendered above the header), `footer` (footer content, rendered below
+the body), `actions` (small header controls, rendered alongside the header content).
+
+**CSS parts:** `base` (the outer container — a `<div>`, or an `<a>` when `href` is set), `media`
+(wrapper around the `media` slot, hidden entirely when empty), `header` (wrapper around the `header`
+slot and `actions`, hidden entirely when both are empty), `actions` (wrapper around the `actions`
+slot, hidden entirely when empty), `body` (wrapper around the default slot), `footer` (wrapper around
+the `footer` slot, hidden entirely when empty).
+
+**Themeable custom properties:** shared tokens only — `--lr-color-border`/`-surface`/`-brand`/
+`-brand-quiet`, `--lr-radius`, `--lr-space-s`/`-m`, `--lr-transition-fast`,
+`--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-card appearance="outlined" interactive href="/reports/42">
+  <img slot="media" src="/thumb.png" alt="" />
+  <span slot="header">Q3 Report</span>
+  <span slot="actions"><lr-chip tone="success">Ready</lr-chip></span>
+  Revenue up 12% quarter-over-quarter.
+  <span slot="footer">Updated 2 days ago</span>
+</lr-card>
+```
+
+**Known gotchas:**
+- every `appearance` renders on the *same* `[part="base"]` element — there's no separate element per
+  variant, so a `::part(base)` override applies uniformly regardless of `appearance`.
+- slot-presence (`header`/`media`/`footer`/`actions`) is tracked in JS, not via CSS `:empty` (a
+  `[part]` wrapper always contains a literal `<slot>` child, so `:empty` never matches) — the same
+  pattern `lr-empty`/`lr-widget` use.
+- **an `interactive` card without `href` deliberately carries no `role="button"`.** A card is a
+  *container* — it routinely holds slotted buttons and links — and `role="button"` around focusable
+  descendants is the `nested-interactive` accessibility violation this library's own a11y gate
+  enforces. (`lr-chip`'s `toggleable` mode *can* carry `role="button"` because it forbids focusable
+  children outright.) The consequence is that the card is announced as a plain focusable region, so
+  give it your own `aria-label` when the content doesn't already name it.
+- because there is no `role="button"` to disambiguate, "did the user aim at the card or at a control
+  inside it?" is answered at event time: the composed path from the original target up to
+  `[part='base']` is walked, and `lr-card-activate` is suppressed if anything along the way is
+  itself a control (a link, `button`, `input`, `select`, `textarea`, `label`, `summary`,
+  `contenteditable`, anything carrying a `tabindex` other than `-1`, or an ARIA widget role such as
+  `button`/`link`/`checkbox`/`switch`/`radio`/`menuitem`/`option`/`tab`/`textbox`/`slider`/
+  `spinbutton`). Using the *composed*
+  path is what makes this work through a slotted component's own shadow root — a click on
+  `<lr-button>` retargets to the host, but its composed path still contains the internal native
+  `<button>`.
+
+---

package/llms/components/lr-carousel-item.md

@@ -0,0 +1,29 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-carousel-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/carousel/carousel-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraCarouselItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/carousel/carousel-item.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-carousel-item`
+
+Optional semantic wrapper for one slide in `<lr-carousel>`. The carousel also accepts arbitrary
+slotted elements, so this element is useful when a migration needs the explicit item tag.
+
+**Slots:** default slide content.
+
+**CSS parts:** `base`.
+
+```html
+<lr-carousel>
+  <lr-carousel-item>Dashboard overview</lr-carousel-item>
+  <lr-carousel-item>Dashboard details</lr-carousel-item>
+</lr-carousel>
+```
+
+---

package/llms/components/lr-carousel.md

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-carousel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/carousel/carousel.js';` (registers the tag; side-effect import)
+- **Class** `LyraCarousel`, also available unregistered from `@aceshooting/lyra-ui/components/layout/carousel/carousel.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-carousel`
+
+Accessible carousel for arbitrary slotted slide elements. It shows one assigned element at a time,
+adds slide semantics and localized position labels, and provides keyboard, button, and indicator
+navigation.
+
+**Properties:**
+- `index: number = 0` (attribute `index`, reflected) — active slide index
+- `loop: boolean = false` (attribute `loop`, reflected) — wraps navigation at either end
+- `autoplay: boolean = false` (attribute `autoplay`, reflected) and `autoplayInterval: number = 5000`
+  (attribute `autoplay-interval`) — optional timed advance; autoplay is disabled under reduced motion
+- `showIndicators: boolean = true` (attribute `show-indicators`) — renders slide indicator buttons
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — fallback landmark name; a host
+  `aria-label` takes precedence
+
+**Methods:** `next()`, `previous()`, and `goTo(index)` update the active index and emit
+`lr-slide-change` (`detail: { index }`).
+
+**CSS parts:** `base` (the `role="region"` landmark), `viewport` (the keyboard-focusable slide
+viewport), `track`, `controls`, `previous-button`, `next-button`, `previous-glyph`/`next-glyph` (the
+chevron inside each, mirrored under RTL), `indicators`, `indicator` (one indicator's hit target,
+sized to the shared minimum tappable size), and `indicator-dot` (the compact visible dot inside it).
+
+**Themeable custom properties:** `--lr-carousel-indicator-current-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-carousel-indicator-current-border-color` (default
+`var(--lr-color-brand)`) — background and border color of the current slide's `indicator-dot`
+(`[aria-current='true']`). Same state-hook mechanics as `<lr-widget>`'s view-toggle pair above:
+inline `var()` fallbacks, never declared on `:host`, so either can be set on the element or on any
+ancestor; unset, each falls back to the token the rule used before. This shape is what makes the
+current indicator addressable at all — `::part(indicator)[aria-current='true']` is invalid CSS, so
+hijacking a library-wide color token was previously the only lever.
+
+```html
+<lr-carousel aria-label="Screenshots">
+  <img alt="Dashboard overview" src="overview.png">
+  <img alt="Dashboard details" src="details.png">
+</lr-carousel>
+```
+
+---

package/llms/components/lr-chart.md

@@ -0,0 +1,149 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-chart` (core)
+
+Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simplified
+`Series`-based attribute surface and a raw Chart.js `config` passthrough (mirrors Web Awesome's
+`wa-chart` `config` property).
+
+**Properties:**
+- `type: LyraChartType = 'line'` — `LyraChartType = 'line' | 'bar' | 'scatter' | 'pie' | 'doughnut' |
+  'radar' | 'polarArea' | 'bubble'` — every type string the typed `lr-*-chart` subclasses lock `type` to is
+  already a first-class member, so `<lr-chart type="pie">` needs no subclass or cast to work;
+  unknown runtime attribute/property values fall back to `line` before reaching Chart.js
+- `labels: string[] = []` (attribute: false)
+- `datasets: Series[] = []` (attribute: false) — `Series { label: string; data?: (number|null)[];
+  points?: {x,y,label?}[]; color?: string|string[]; fill?: boolean; width?: number; dash?: boolean;
+  noTooltip?: boolean; axis?: 'y'|'y2'; pointColors?: string[]; pointRadius?: number; type?:
+  'line'|'bar' }`
+- `legend: boolean = false`
+- `legendPosition: LyraChartLegendPosition = 'top'` (attribute `legend-position`) — places the
+  legend at `top`, `right`, `bottom`, or `left`; `auto` chooses right above 480px and bottom below
+  that allocation width
+- `valueFormatter?: LyraChartValueFormatter` (attribute: false) — formats numeric tick, tooltip,
+  and legend values; the callback receives the value and `'tick'`, `'tooltip'`, or `'legend'`
+  context
+- `area: boolean = false`
+- `zoom: boolean = false` — wheel/drag/pinch zoom on the `x` axis only (pan disabled, and the zoom
+  range is limited to the original data extent); shows the `reset-zoom-button` while zoomed
+- `height: string = '280px'`
+- `xLabel: string = ''` (attribute `x-label`)
+- `yLabel: string = ''` (attribute `y-label`)
+- `y2Label: string = ''` (attribute `y2-label`)
+- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
+- `horizontal: boolean = false` — sets `options.indexAxis = 'y'`, Chart.js's own mechanism for
+  horizontal bars (also flips `line`/`area` types onto a horizontal category axis)
+- `stacked: boolean = false` — stacks the `x`/`y`(/`y2`) scale entries `buildScales()` returns; only
+  meaningful for `bar`/`line` types (scatter/bubble's linear `x` scale and the radial `r` scale used
+  by radar/polar-area are out of scope)
+- `config?: Partial<ChartConfiguration>` (attribute: false) — deep-merged over the generated
+  config; any nested key wins without clobbering sibling generated keys. This is the raw Chart.js
+  escape hatch, so a caller-supplied `config.type` is passed through rather than normalized.
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — canvas name override; a host
+  `aria-label` has highest precedence
+- `accessibleDescription: string = ''` (attribute `accessible-description`) — overrides the
+  localized data/trend summary
+- `showDataTable: boolean = false` (attribute `show-data-table`) — makes the always-available
+  accessible data table visible rather than screen-reader-only
+- `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
+  canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
+  drawn
+
+**Methods:** `resetZoom()` (reset any active zoom/pan to the original view), `refreshTheme()`
+(forces a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style —
+the escape hatch for a consumer's own theme-toggle handler to call when it flips something, e.g. a
+`data-theme` attribute, that doesn't otherwise change any `lr-chart` property)
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`, fired on zoom-complete and on
+`resetZoom()`), `lr-point-click` (fired when a click lands on, or nearest to — intersect-only —
+a data point/segment, for any chart type, not just bar; `detail: { datasetIndex: number, index:
+number, label: string | undefined, value: unknown }`)
+
+**Slots:** `data-table` — an optional consumer-provided accessible table alternative; `center` —
+optional overlay content positioned at the chart area's center, useful for doughnut and pie totals.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center` (the
+chart-area-centered wrapper for the `center` slot), `error` (`role="alert"` message rendered in
+place of `canvas` when the optional `chart.js` peer dependency fails to load)
+
+**Themeable custom properties:** `--lr-chart-height` (set programmatically on the host from the
+`height` property — must be read from the host, not a shadow-tree descendant, since custom
+properties only cascade downward); `--lr-chart-grid-color` (default `var(--lr-color-border)`),
+`--lr-chart-tick-color` (default `var(--lr-color-text-quiet)`), `--lr-chart-legend-color`
+(default `var(--lr-color-text)`), `--lr-chart-tooltip-bg` (default `var(--lr-color-surface)`),
+`--lr-chart-tooltip-text` (default `var(--lr-color-text)`) — each resolved fresh via
+`getComputedStyle` on every draw (Chart.js renders to canvas, not the DOM, so it can't consume CSS
+`var()` directly), driving the grid lines, tick labels **and axis titles** (`xLabel`/`yLabel`/
+`y2Label` title text reuses `--lr-chart-tick-color` too — there's no separate title-color token),
+legend text, and tooltip background/text respectively; plus shared `--lr-space-xs`.
+
+**Optional peer deps:** `chart.js` (mandatory peer, lazy-imported on every `connectedCallback()`
+regardless of `zoom`), `chartjs-plugin-zoom` (lazy-imported *additionally* only when `zoom` is — or
+later becomes — `true`; never fetched for a chart that keeps `zoom` unset/false, since the plugin
+has a hard dependency on `hammerjs`). Both loads are memoized once per page via `chart-loader.ts`
+(`loadChartJs()` / `loadChartJsWithZoom()`), registering only the tree-shaken controller/element/scale
+subset actually used.
+
+```html
+<lr-chart type="line" x-label="Day" y-label="kWh" legend></lr-chart>
+<script>
+  const c = document.querySelector('lr-chart');
+  c.labels = ['Mon', 'Tue', 'Wed'];
+  c.datasets = [{ label: 'Production', data: [12, 19, 7], color: '#2563eb' }];
+</script>
+```
+
+**Known gotchas:**
+- supported `type` values are normalized before reaching Chart.js; unknown runtime attribute or
+  property values fall back to `line`. Each typed `lr-*-chart` subclass (e.g.
+  `llms/components/lr-bar-chart.md`) locks its *own* `type` via a real prototype accessor — a
+  genuine runtime lock, not just a compile-time default.
+- no global theme-broadcast event exists to auto-retheme an already-drawn chart on a theme switch —
+  a consumer flipping something upstream (e.g. a `data-theme` attribute) that doesn't otherwise
+  change any `lr-chart` property must call `refreshTheme()` itself to make Chart.js re-read the
+  `--lr-chart-*` tokens above.
+- generated `scales` are keyed off the *effective* type (`config.type` ?? `type`, see
+  `effectiveType()`) and are type-appropriate: no scale at all for `type="pie"`/`"doughnut"` (true of
+  `<lr-chart type="pie">` directly, not just the `lr-pie-chart`/`lr-doughnut-chart` subclasses),
+  and a single radial `r` scale (respecting `beginAtZero`) for `type="radar"`/`"polarArea"`
+  (`lr-radar-chart`/`lr-polar-area-chart`), instead of always generating the cartesian `x`/`y`/
+  `y2` block. `xLabel`/`yLabel`/`y2Label` are still silently inert for all four of those types (a
+  radial scale and "no scale" both have nowhere to put an axis title) — reach a titled radial scale
+  only via raw `config`.
+- No `chartjs-plugin-annotation` is registered by default — reachable only by importing it
+  separately and using the raw `config` passthrough (Chart.js's registry is a global singleton).
+- while the `chart.js` peer is resolving, `render()` swaps in a `<lr-skeleton variant="rect">` for
+  the canvas, and the **host element itself** (not the skeleton) carries `aria-busy="true"` — set/
+  cleared in `updated()` off the private `loading` state (same lazy-load pattern as
+  `lr-graph`/`lr-map`/`lr-flag`). Chart.js's own ~1000ms draw-in animation only ever fires on
+  initial construction or a type change that rebuilds the `Chart` instance (every in-place data
+  update already passes `'none'` to `Chart#update()` and never animates regardless); that
+  construction-time animation is additionally skipped outright under `prefers-reduced-motion: reduce`.
+  The raw `config` passthrough is deep-merged with `__proto__`/`constructor`/`prototype` keys skipped
+  unconditionally, so a JSON-sourced `config` (e.g. parsed from an API response) can't reach up and
+  pollute `Object.prototype` through the merge.
+- lazy-redraw + change gating: an `IntersectionObserver` gates `draw()` — while the host is scrolled
+  off-screen, property changes that would otherwise trigger a Chart.js redraw are skipped (and a
+  single redraw fires once it re-enters the viewport). Independently, `updated()` only reaches
+  Chart.js when at least one of `type`, `labels`, `datasets`, `legend`, `legendPosition`, the
+  internal resolved auto legend position, `valueFormatter`, `area`, `height`, `xLabel`, `yLabel`,
+  `y2Label`, `beginAtZero`, `horizontal`, `stacked`, `config`, `zoom`, `locale`, `strings`, or the
+  internal loading state actually changed in that update (so an unrelated property/state update, or
+  a bare `requestUpdate()`, draws nothing). `refreshTheme()` calls `draw()` directly and is
+  unaffected by either gate — it always redraws, since a theme change isn't reflected in any tracked
+  property.
+- Chart.js receives `effectiveLocale`; generated summary values use the same locale. Cartesian y/y2
+  axes swap logical sides under RTL, and host `aria-label` is forwarded to the canvas and data-table
+  caption.
+
+---

package/llms/components/lr-chat-composer.md

@@ -0,0 +1,152 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-chat-composer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/chat-composer/chat-composer.js';` (registers the tag; side-effect import)
+- **Class** `LyraChatComposer`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/chat-composer/chat-composer.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-chat-composer`
+
+The message input for a chat/agent conversation surface: an auto-resizing `<textarea>` plus a
+built-in send/stop button. Deliberately no label/hint/error chrome — a composite chat-input
+control, not a labeled form field; wrap it in your own layout for that context. **Form-associated**
+via the shared `FormAssociated` mixin (same shape as
+`<lr-date-input>`) — `name: string = ''`, `value: string = ''`, `disabled: boolean = false`
+(reflected), `required: boolean = false` (reflected) are all inherited, along with
+`checkValidity()`/`reportValidity()`, so it participates in native `<form>` submission/validation/
+reset like any other text control.
+
+The inner textarea mirrors `required` through native `required`/`aria-required`. Its
+`aria-invalid` remains false until the textarea has been blurred, then follows the host's
+`ElementInternals` validity as `value` or `required` changes. A native validation attempt also
+reveals the invalid state, and `form.reset()` clears the touched presentation.
+
+**Properties (own):**
+- `placeholder: string = ''`
+- `minRows: number = 1` (attribute `min-rows`) — floored to `1` at render time
+- `maxRows: number = 8` (attribute `max-rows`) — floored to at least `minRows`
+- `status: ChatComposerStatus = 'idle'` (reflected) — `'idle' | 'sending' | 'streaming'`; drives the
+  built-in button's icon/label (send vs. stop) and whether Enter still submits
+- `appearance: ChatComposerAppearance = 'card'` (reflected) — `'card' | 'plain'`; `'plain'` drops
+  `[part="base"]`'s border, background, padding and corner radius so a composer docked inside a chat
+  panel, dialog footer or toolbar that already draws its own border doesn't double the frame. The
+  focus affordance is swapped, not dropped — see **Known gotchas**
+- `submitOnEnter: boolean = true` (reflected, attribute `submit-on-enter`) — when `false`, Enter
+  always inserts a newline instead of submitting
+- `submitDisabled: boolean = false` (reflected, attribute `submit-disabled`) — consumer-controlled
+  validation gate; while idle, disables the built-in Send button and suppresses Enter/click
+  submission without disabling the textarea or a busy-state Stop action
+- `stoppable: boolean = true` (reflected) — when false, busy states keep a disabled Send button
+  instead of exposing a Stop action
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — names the internal textarea;
+  wins over placeholder and the localized composer label
+- `spellcheck: boolean = true` — forwarded to the internal `<textarea>`
+- `autocapitalize: string = ''` — forwarded to the internal `<textarea>`; empty omits the attribute
+- `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the internal `<textarea>`
+  (Safari/WebKit-specific); empty omits the attribute. Named `autoCorrect`, not `autocorrect`, only
+  to dodge a `lib.dom.d.ts` collision with `HTMLElement`'s own `boolean`-typed `autocorrect` IDL
+  member; the host attribute is explicitly mapped to plain `autocorrect`.
+- `wrap: 'hard' | 'soft' | 'off' = 'soft'`, `autocomplete: string = ''`, `inputMode: string = ''`
+  (attribute `inputmode`), and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to
+  the native textarea
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters
+
+**Methods (own):** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and
+`setRangeText()` forward to the textarea; `setRangeText()` synchronizes reactive/form value and
+auto-sizing. `checkValidity()`/`reportValidity()` remain inherited.
+
+**Events:**
+- `lr-input` (`detail: { value }`) — fired on every user-driven edit of the textarea, not a
+  programmatic `.value` assignment
+- `lr-submit` (`detail: { value }`) — fired by Enter (per `submit-on-enter`) or the built-in
+  button while `status="idle"` and `submitDisabled` is false. `detail.value` is always the exact, untrimmed current value;
+  trimming is left to the consumer. Submitting does **not** clear `value`
+- `lr-stop` (no detail) — fired by the built-in button while `status` is `"sending"` or
+  `"streaming"`
+- `blur` (no detail) — re-dispatched from the internal `<textarea>`'s own `blur`, bubbling and
+  composed unlike the native event
+- `focus` (no detail) — re-dispatched from the internal `<textarea>`'s own `focus`, for the same
+  reason as `blur`
+
+**Slots:** `leading` (content before the textarea, e.g. an attach-file trigger button), `chips` (an
+attachment tray rendered above the input row), `trailing` (overrides the built-in send/stop button
+entirely when it has assigned content)
+
+**CSS parts:** `base`, `chips`, `row`, `leading`, `textarea`, `trailing`, `action-button`
+
+**Themeable custom properties:** `--lr-chat-composer-busy-bg` (default `var(--lr-color-text-quiet)`)
+— `[part="action-button"]`'s background while `status` is `"sending"` or `"streaming"` (the busy/stop
+treatment). Scoped separately from the shared `--lr-color-text-quiet` token, which
+`[part="textarea"]`'s placeholder color also reads — overriding this cssprop recolors only the busy
+button, not the placeholder too (the same shared-token-collision fix `<lr-chat-message>`'s own
+user-bubble background pair documents). Plus shared tokens `--lr-space-xs`, `--lr-space-s`,
+`--lr-color-border`, `--lr-color-surface`, `--lr-color-brand`, `--lr-color-on-brand`,
+`--lr-color-text-quiet`, `--lr-radius`, `--lr-icon-button-size`, `--lr-transition-fast`,
+`--lr-opacity-disabled`, `--lr-focus-ring-width`, `--lr-focus-ring-color`, `--lr-focus-ring-offset`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-chat-composer
+  id="composer"
+  name="message"
+  placeholder="Message the assistant…"
+  min-rows="1"
+  max-rows="8"
+></lr-chat-composer>
+<script type="module">
+  const composer = document.getElementById('composer');
+  composer.addEventListener('lr-submit', (e) => {
+    sendMessage(e.detail.value);
+    composer.value = ''; // the composer never clears itself
+    composer.status = 'sending';
+  });
+  composer.addEventListener('lr-stop', () => stopGeneration());
+</script>
+```
+
+Auto-resize (`resizeTextarea()`) reads the textarea's own *computed* line-height/padding/border at
+call time rather than assuming a fixed px-per-row constant, so it stays correct under a consumer's
+own font-size/line-height overrides; it grows between `min-rows` and `max-rows`, then switches to
+internal scrolling (`overflow-y: auto`) past `max-rows`. A `ResizeObserver` on the textarea itself
+also re-runs this fit (one animation frame later, to avoid a `ResizeObserver`-loop console error)
+whenever the textarea's own *width* changes — a sidebar collapsing, a responsive breakpoint, a
+window resize — even though `value`/`min-rows`/`max-rows` never did, since the same text now wraps
+across a different number of lines. Enter-to-send only fires while
+`submit-on-enter` is `true` (the default): plain Enter submits and prevents the default newline;
+Shift+Enter always inserts a newline regardless of `submit-on-enter`; an IME composition step
+(checked via `isComposing`, with `keyCode === 229` as a defense-in-depth fallback for browsers that
+report `isComposing` inconsistently) is never treated as a submit trigger; and while `status` isn't
+`"idle"`, Enter is left alone to insert a newline instead of resubmitting — the textarea itself is
+**not** auto-disabled during `sending`/`streaming`, so a user can keep composing their next message
+while a previous one is in flight. While idle, `submitDisabled` suppresses Enter/click submission
+and disables only the built-in Send button; editing and busy-state Stop behavior remain available.
+
+**Known gotchas:**
+- `lr-submit` never clears `value` — the consumer must clear it once a submission is actually
+  accepted, so a failed send can leave the text in place for retry.
+- While `status !== 'idle'`, only the built-in button's behavior changes (it emits `lr-stop`
+  instead of `lr-submit`); the textarea keeps accepting input and Enter keeps inserting newlines
+  rather than being blocked.
+- Auto-resize requires a concrete, unitless `line-height` on the textarea (the component sets
+  `line-height: 1.5` in its own styles) — the UA default of `normal` has no single resolved px
+  figure to measure rows against, so overriding `line-height` to a keyword breaks row sizing.
+- The `trailing` slot fully replaces the built-in action button rather than rendering alongside it —
+  once it has assigned content, the library's send/stop icon, its `aria-label`, and its
+  `status`-driven busy styling all disappear, so a custom trailing control needs its own send/stop
+  handling.
+- `[part="chips"]`/`[part="leading"]` are hidden via a JS-tracked `[hidden]` attribute rather than a
+  CSS `:empty` selector, because each always contains a literal `<slot>` child regardless of
+  assigned content.
+- Under `appearance="card"` the only focus affordance is a border-color shift on `[part="base"]`
+  (the internal `<textarea>` sets `outline: none`). `appearance="plain"` removes that border, so it
+  swaps in a different affordance rather than losing focus visibility: an underline across the whole
+  input row, drawn as an inset `box-shadow` from `--lr-focus-ring-width`/`--lr-focus-ring-color` so
+  it costs no layout. If you restyle `[part="base"]` under `plain`, keep a focus indicator.
+
+---