@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-animation.md

@@ -0,0 +1,73 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-animation`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/animation/animation.js';` (registers the tag; side-effect import)
+- **Class** `LyraAnimation`, also available unregistered from `@aceshooting/lyra-ui/components/media/animation/animation.class.js`
+- **Family** `components/media/` — 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-animation`
+
+Declaratively animates one slotted element through the native Web Animations API.
+
+**Properties:**
+- `name: LyraAnimationPreset = 'none'` — `'none' | 'fade-in' | 'fade-out' | 'zoom-in' | 'zoom-out' |
+  'slide-in-start' | 'slide-in-end' | 'slide-out-start' | 'slide-out-end' | 'slide-in-up' |
+  'slide-in-down' | 'bounce' | 'pulse' | 'spin' | 'shake'`. The four `-start`/`-end` slide presets
+  are logical: "start" is physically left under `ltr`, right under `rtl`.
+- `keyframes?: Keyframe[]` (attribute: false) — raw WAAPI keyframes; always wins over `name`.
+- `play: boolean = false` (reflected) — playback intent.
+- `delay: number = 0`, `duration: number = 1000`, `endDelay: number = 0` (attribute `end-delay`),
+  `easing: string = 'linear'`, `fill: FillMode = 'auto'`, `direction: PlaybackDirection = 'normal'`,
+  `iterations: number = Infinity`, `iterationStart: number = 0` (attribute `iteration-start`),
+  `playbackRate: number = 1` (attribute `playback-rate`) — straight WAAPI timing. `direction` is
+  the WAAPI `PlaybackDirection`, unrelated to text direction.
+- `timingPreset: LyraAnimationTimingPreset = 'custom'` (attribute `timing-preset`, reflected) —
+  `'custom' | 'fast' | 'base' | 'ambient'`. Anything other than `'custom'` derives `duration` and
+  `easing` from the matching `--lr-transition-*` token (read off computed style and decomposed into
+  the numeric ms + easing string WAAPI needs), ignoring the `duration`/`easing` properties.
+- `respectReducedMotion: boolean = true` (attribute `respect-reduced-motion`, reflected) — under
+  `prefers-reduced-motion: reduce`, caps playback at one iteration and calls `finish()` immediately
+  instead of playing, so the target snaps to its resolved end state; `lr-start`/`lr-finish` still
+  fire in order.
+- `playOnVisible: boolean = false` (attribute `play-on-visible`, reflected) — starts playback via
+  `IntersectionObserver` once the target intersects. `playOnVisibleRepeat: boolean = false`
+  (attribute `play-on-visible-repeat`, reflected) — re-plays on each re-entry and pauses on exit;
+  when unset the observer disconnects after the first trigger. `root: Element | null = null` and
+  `threshold: number | number[] = 0` (both attribute: false) plus `rootMargin: string = '0px'`
+  (attribute `root-margin`) configure that observer.
+- `currentTime: number` — the underlying `Animation.currentTime` (`0` when no animation exists);
+  writable, forwarded to the animation when one exists.
+
+**Methods:** `start()` (sugar for `play = true` — named `start` because `play` is already a
+property), `pause()` (`play = false`), `finish()`, `cancel()`.
+
+**Events:** `lr-start` (a new animation was created and playback began/restarted), `lr-finish`
+(natural end, including the reduced-motion instant-finish path), `lr-cancel` (the public `cancel()`
+method or external cancellation). `lr-finish`/`lr-cancel` both reset `play` to `false`.
+
+**Slots:** default slot — the element to animate. A second slotted element is accepted without
+error but ignored.
+
+**CSS parts:** none (`:host { display: contents }`; the animated element is light-DOM content).
+
+**Themeable custom properties:** `--lr-animation-slide-distance` (default `100%` — travel distance
+for the slide presets), `--lr-animation-zoom-scale` (default `0.5` — start/end scale for
+`zoom-in`/`zoom-out`), `--lr-animation-bounce-height` (default `25%` — peak lift of `bounce`),
+`--lr-animation-shake-distance` (default `4%` — horizontal travel of `shake`).
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- `iterations` defaults to `Infinity` (mirrors the upstream Web Awesome/Shoelace contract) — a named
+  preset plays forever unless you set `iterations="1"`.
+- changing any timing/keyframe property rebuilds the animation from scratch; the rebuild's internal
+  `cancel()` is deliberately silent (no `lr-cancel`), only the public `cancel()` emits.
+- the slide presets read the inherited text direction only when the animation is (re)built — an
+  animation already mid-flight is not re-mirrored if an ancestor `dir` flips.
+- reduced-motion handling is entirely in JS; the shared shadow-DOM reduced-motion CSS block can't
+  reach light-DOM slotted content driven by `Element.animate()`.

package/llms/components/lr-app-rail-item.md

@@ -0,0 +1,229 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-app-rail-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/app-rail/app-rail-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraAppRailItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/app-rail/app-rail-item.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-app-rail` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-app-rail`
+
+A responsive navigation rail that adapts across three presentations as the *viewport* narrows (not
+this element's own inline size): `'full'` (nav items show icon + label, inline), `'icon-only'` (a
+narrower inline rail, icons only), and `'mobile'` (hidden behind a toggle button; opening it shows a
+focus-trapped floating overlay over the page). First-party invention (no Web Awesome equivalent).
+Breakpoints are viewport-width `matchMedia()` queries against `icon-only-breakpoint`/
+`mobile-breakpoint`, not a `ResizeObserver` on this element — presentation tracks the actual device/
+window width the way a native OS shell's navigation does, not however much horizontal space a
+particular layout happens to give it. `[part="base"]` (the inline `'full'`/`'icon-only'`
+presentation) and `[part="panel"]` (the mobile overlay) are the *same* element promoted in place
+across modes (mirrors `<lr-widget>`'s fullscreen mode) — never both at once, and slotted nav
+content is never duplicated.
+
+Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
+`[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
+`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
+width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
+breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
+automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
+accessor itself, which still takes full priority.
+
+**Properties:**
+- `mode: AppRailMode` (custom accessor, reflected) — the getter always returns one of the three real
+  modes (`'full'|'icon-only'|'mobile'`), never `'auto'`. The setter accepts
+  `AppRailModeInput` (`AppRailMode | 'auto'`): assigning `'full'`/`'icon-only'`/`'mobile'` forces
+  that mode and stops the element responding to breakpoint changes; assigning the write-only
+  sentinel `'auto'` releases the force and immediately re-syncs to the current viewport width,
+  resuming automatic tracking. Settable via the `mode` attribute too (`mode="icon-only"`,
+  `mode="auto"`).
+- `iconOnlyBreakpoint: string = '960px'` (attribute `icon-only-breakpoint`) — any valid CSS length,
+  used directly in a `(max-width: ...)` media query; below it the rail switches from `'full'` to
+  `'icon-only'`.
+- `mobileBreakpoint: string = '600px'` (attribute `mobile-breakpoint`) — same mechanism; below it the
+  rail switches from `'icon-only'` to `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to
+  produce all three states as the viewport narrows.
+- `open: boolean = false` (reflected) — whether the mobile floating overlay is shown. Only meaningful
+  while `mode` is `'mobile'` — the value is preserved (not reset) while another mode is active, but
+  no overlay chrome renders until `mode` is `'mobile'` again. Set this directly, or use the built-in
+  toggle button — there is no separate `show()`/`hide()` pair.
+- `label: string = 'Navigation'` — accessible name for the rail's navigation landmark, and for its
+  dialog role while the mobile overlay is open. A host-level `aria-label` attribute (see below)
+  takes precedence over this when both are set.
+- `preferredMode?: 'full' | 'icon-only' | null` (attribute `preferred-mode`) — manually prefers
+  `'full'` or `'icon-only'` for the non-mobile breakpoint axis, while `mobile-breakpoint` continues to
+  be tracked automatically regardless — e.g. a user's manual collapse toggle that should still yield
+  to a genuinely too-narrow-for-any-inline-rail viewport. Only consulted while `mode` isn't
+  force-pinned via its own accessor (see above) — that continues to take full priority, unchanged.
+  Unset (the default, `null`) reproduces the original breakpoint-only behavior exactly.
+- `hideToggle: boolean = false` (reflected, attribute `hide-toggle`) — suppresses the built-in mobile
+  `[part='toggle']` hamburger/close button entirely, for a consumer that already owns an external
+  mobile-menu toggle wired to this rail's own `open` property. `false` (the default) reproduces the
+  exact existing output; note `open` still has no built-in external trigger of its own once this is
+  set, since `lr-toggle` only fires from the toggle button being activated.
+- `resizable: boolean = false` (reflected) — opts a continuously draggable width in for the `'full'`
+  state, exposing a `[part='resizer']` handle clamped to `[minRailWidthPx, maxRailWidthPx]`. `false`
+  (the default) renders no resizer and leaves the fixed-width `--lr-app-rail-width` CSS token
+  exactly as before this property existed.
+- `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
+  `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
+  width.
+- `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `dragging: boolean = false` (reflected) — `true` for the duration of an active pointer-driven
+  resize drag (not a keyboard step); reflected so a consumer (or this component's own styles) can
+  suppress `[part='base']`'s `transition: inline-size` during the drag, which otherwise visibly
+  "chases" the pointer instead of tracking it 1:1. Effectively read-only (this component owns the
+  transitions), but a plain reflected property like every other boolean here.
+
+Also settable as a plain `aria-label` attribute (not a reactive property): overrides the computed
+`label`/localized-default accessible name on both the navigation landmark and the mobile dialog
+role, matching `<lr-date-input>`'s `accessibleLabel`.
+
+**Events:** `lr-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
+effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
+fired for a redundant reassignment to the mode already in effect), `lr-toggle`
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
+built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
+mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly),
+`lr-rail-resize` (`detail: AppRailResizeDetail` = `{ widthPx: number }`; the `resizable` rail's
+width changed via drag or keyboard stepping — not fired when a consumer sets `railWidthPx` directly).
+
+**Slots:** default (nav items — generic slotted content, e.g. `<a>`/`<button>` elements the consumer
+builds with its own icon+label structure; clicking anywhere in this slot closes the mobile overlay if
+open), `header` (logo/brand content, shown above the nav items in every mode), `footer` (a trailing
+user/settings trigger, shown below the nav items).
+
+**CSS parts:** `base`, `header`, `nav`, `footer`, `toggle` (hidden via CSS outside `'mobile'` mode, or
+entirely via `hideToggle`), `backdrop`, `panel` (`base`/`panel` are mutually exclusive on the same
+underlying element — see above), `resizer` (the `resizable` opt-in's drag handle, only rendered while
+`resizable` and `mode` is `'full'`; its hit target is `--lr-icon-button-size`-wide), `resizer-track`
+(the slim 3px visible drag line centered inside that hit target, tinted `--lr-color-brand` on hover).
+
+**Themeable custom properties:** `--lr-app-rail-width` (default `15rem` — the inline rail width in
+`'full'` mode), `--lr-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
+mode), `--lr-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
+width), `--lr-app-rail-overlay-color` (default `var(--lr-color-overlay)` — the mobile backdrop scrim
+color; component-specific since no shared token exists), plus shared tokens (`--lr-color-border`,
+`--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`, `--lr-color-brand-quiet`,
+`--lr-space-*`, `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`,
+`--lr-focus-ring-*`, `--lr-transition-base`). `resizable`'s width is driven entirely by
+`railWidthPx`'s inline `inline-size` style rather than a new custom property.
+
+**Optional peer deps:** none.
+
+```html
+<lr-app-rail label="Main navigation" icon-only-breakpoint="960px" mobile-breakpoint="600px" resizable>
+  <span slot="header"><img src="/logo.svg" alt="Acme" /></span>
+  <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+  <a href="/settings" aria-label="Settings"><svg aria-hidden="true">...</svg><span>Settings</span></a>
+  <span slot="footer"><button>Profile</button></span>
+</lr-app-rail>
+<script type="module">
+  const rail = document.querySelector('lr-app-rail');
+  rail.addEventListener('lr-rail-resize', (e) => localStorage.setItem('railWidthPx', String(e.detail.widthPx)));
+</script>
+```
+```ts
+rail.mode = 'icon-only'; // force a presentation regardless of viewport width
+rail.mode = 'auto';      // release the force, resume live breakpoint tracking
+```
+
+The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
+boolean, preferredMode?: 'full' | 'icon-only' | null): AppRailMode` resolver (plus the
+`AppRailMode`/`AppRailModeInput`/`AppRailModeChangeDetail`/`AppRailToggleDetail`/`AppRailResizeDetail`
+types) — the same logic the element's internal `matchMedia` listeners call, exposed standalone so a
+consumer can compute or unit-test the same resolution without a real browser window. `mobileMatches`
+wins over everything else when true (the viewport is narrower than both breakpoints at once);
+otherwise `preferredMode` (when set) wins over `iconOnlyMatches`.
+
+The mobile state keeps its own panel template rather than nesting `<lr-dialog>`, while its modal
+behavior participates in the shared overlay stack. It is a plain `<div>` with an explicit
+`role="navigation"` (swapping to `role="dialog"` while the overlay is open) rather than a literal
+`<nav>` tag, since a
+`<nav>`'s implicit role can't be overridden to `role="dialog"` without an `aria-allowed-role`
+violation. In `'icon-only'` mode, slotted nav items lose their visible text label — give each one a
+real accessible name (`aria-label`, visually hidden text, or `title`) regardless, since this
+component only lays out whatever is slotted and can't inspect or fix up a consumer's own markup.
+
+**Known gotchas:**
+- `mode`'s setter accepts the wider `AppRailModeInput` (including the `'auto'` sentinel) but the
+  getter's return type is the narrower `AppRailMode` — assigning `'auto'` is a one-way instruction,
+  not a value read back later; there is no `isForced`-style property to check whether the rail is
+  currently locked to a mode or tracking the viewport.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint` after first render tears down and rebuilds
+  the `matchMedia` listeners, but does not itself un-force a previously-forced `mode` — if a consumer
+  set `mode = 'icon-only'`, changing the breakpoints won't resume auto-tracking until `mode = 'auto'`
+  is set explicitly.
+- leaving `'mobile'` mode while `open` (via a breakpoint crossing or a forced `mode` reassignment)
+  auto-closes the overlay through the same path as the toggle button, so `lr-toggle` still fires
+  and the scroll lock/focus trap still release normally — a consumer listening only for explicit
+  toggle-button clicks would miss this closure.
+- the mobile panel is also given `inert` whenever `mode === 'mobile'` and `open` is `false` — it's
+  removed from the accessibility tree and tab order via `inert` at the same time it's hidden visually
+  via `transform: translateX(-100%)`, both applied simultaneously rather than one implying the other.
+- the offscreen slide direction for the mobile panel is flipped for RTL via a `:dir(rtl)` CSS
+  selector (`translateX(100%)`), not through the shared `internal/rtl.ts` JS helper used for pointer/
+  keyboard math elsewhere in this library — a physical `transform` isn't expressible with logical
+  properties, so this one case is handled purely in CSS.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if the overlay was still active
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- `resizable`'s drag handle is pointer-only (`pointerdown`/`pointermove`/`pointerup`/
+  `pointercancel`/`lostpointercapture`) plus discrete Left/Right-arrow keyboard stepping (8px per
+  press, RTL-aware) — there's no dedicated touch gesture beyond what Pointer Events already unify.
+- reassigning `railWidthPx` while `resizable` is unset has no visible effect on the rendered width —
+  the fixed-width `--lr-app-rail-width` token still governs `'full'`-mode width until `resizable`
+  is also set.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint`/`preferredMode` does not itself un-force a
+  previously-forced `mode` — same caveat as above, `preferredMode` is only consulted while `mode`
+  isn't force-pinned.
+
+### `lr-app-rail-item`
+
+An explicit navigation item for `<lr-app-rail>`. It renders an accessible link when `href` is
+set and enabled, otherwise a button; the rail can add its `icon-only` presentation state without
+removing the label from the accessibility tree.
+
+**Properties:**
+- `href: string = ''` — optional destination. Without it, the item renders as a button.
+- `target: string = ''` — optional link target.
+- `disabled: boolean = false` (reflected) — prevents activation while retaining the item in the rail.
+- `active: boolean = false` (reflected) — marks this as the destination for the current page/view;
+  reflects `aria-current="page"` on `[part='base']` and drives the active visual treatment. The rail
+  has no built-in routing, so the consumer sets this per item (e.g. by comparing `href` against the
+  current location).
+- `tooltip: boolean = false` (reflected) — opt-in hover/focus flyout (`[part='tooltip']`) showing
+  this item's label text while the rail's `icon-only` mode (set externally by the parent
+  `<lr-app-rail>` as the viewport narrows) hides it from view. No effect outside icon-only mode,
+  since the label is already visible there. `false` (the default) reproduces the exact existing
+  output.
+
+**Slots:** default (the visible label), `icon` (the leading icon, hidden from assistive technology
+when the item has an explicit `aria-label`).
+
+**CSS parts:** `base`, `icon`, `label`, `tooltip` (the hover/focus label flyout, only rendered while
+`tooltip` is set, the item is `icon-only`, and it is hovered or focused).
+
+**Themeable custom properties:** `--lr-app-rail-item-current-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-app-rail-item-current-color` (default
+`var(--lr-color-brand)`) — background and text/icon color of the `active` (`aria-current="page"`)
+item. Both are scoped to `[aria-current='page']` only and declared as inline `var()` fallbacks at
+the point of use, never on `:host`, so either can be set on the item itself *or on any ancestor* —
+including on `<lr-app-rail>` or a wrapper above it, to tint every item's active state at once.
+`::part(base)[aria-current='page']` is invalid CSS (Shadow Parts forbids an attribute selector after
+`::part()`), so before these hooks the only lever was overriding the library-wide
+`--lr-color-brand-quiet`/`--lr-color-brand` tokens, which repainted every other element reading
+them. Unset, each falls back to the token its rule used before.
+
+**Optional peer deps:** none.
+
+---

package/llms/components/lr-app-rail.md

@@ -0,0 +1,229 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-app-rail`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/app-rail/app-rail.js';` (registers the tag; side-effect import)
+- **Class** `LyraAppRail`, also available unregistered from `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-app-rail-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-app-rail`
+
+A responsive navigation rail that adapts across three presentations as the *viewport* narrows (not
+this element's own inline size): `'full'` (nav items show icon + label, inline), `'icon-only'` (a
+narrower inline rail, icons only), and `'mobile'` (hidden behind a toggle button; opening it shows a
+focus-trapped floating overlay over the page). First-party invention (no Web Awesome equivalent).
+Breakpoints are viewport-width `matchMedia()` queries against `icon-only-breakpoint`/
+`mobile-breakpoint`, not a `ResizeObserver` on this element — presentation tracks the actual device/
+window width the way a native OS shell's navigation does, not however much horizontal space a
+particular layout happens to give it. `[part="base"]` (the inline `'full'`/`'icon-only'`
+presentation) and `[part="panel"]` (the mobile overlay) are the *same* element promoted in place
+across modes (mirrors `<lr-widget>`'s fullscreen mode) — never both at once, and slotted nav
+content is never duplicated.
+
+Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
+`[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
+`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
+width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
+breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
+automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
+accessor itself, which still takes full priority.
+
+**Properties:**
+- `mode: AppRailMode` (custom accessor, reflected) — the getter always returns one of the three real
+  modes (`'full'|'icon-only'|'mobile'`), never `'auto'`. The setter accepts
+  `AppRailModeInput` (`AppRailMode | 'auto'`): assigning `'full'`/`'icon-only'`/`'mobile'` forces
+  that mode and stops the element responding to breakpoint changes; assigning the write-only
+  sentinel `'auto'` releases the force and immediately re-syncs to the current viewport width,
+  resuming automatic tracking. Settable via the `mode` attribute too (`mode="icon-only"`,
+  `mode="auto"`).
+- `iconOnlyBreakpoint: string = '960px'` (attribute `icon-only-breakpoint`) — any valid CSS length,
+  used directly in a `(max-width: ...)` media query; below it the rail switches from `'full'` to
+  `'icon-only'`.
+- `mobileBreakpoint: string = '600px'` (attribute `mobile-breakpoint`) — same mechanism; below it the
+  rail switches from `'icon-only'` to `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to
+  produce all three states as the viewport narrows.
+- `open: boolean = false` (reflected) — whether the mobile floating overlay is shown. Only meaningful
+  while `mode` is `'mobile'` — the value is preserved (not reset) while another mode is active, but
+  no overlay chrome renders until `mode` is `'mobile'` again. Set this directly, or use the built-in
+  toggle button — there is no separate `show()`/`hide()` pair.
+- `label: string = 'Navigation'` — accessible name for the rail's navigation landmark, and for its
+  dialog role while the mobile overlay is open. A host-level `aria-label` attribute (see below)
+  takes precedence over this when both are set.
+- `preferredMode?: 'full' | 'icon-only' | null` (attribute `preferred-mode`) — manually prefers
+  `'full'` or `'icon-only'` for the non-mobile breakpoint axis, while `mobile-breakpoint` continues to
+  be tracked automatically regardless — e.g. a user's manual collapse toggle that should still yield
+  to a genuinely too-narrow-for-any-inline-rail viewport. Only consulted while `mode` isn't
+  force-pinned via its own accessor (see above) — that continues to take full priority, unchanged.
+  Unset (the default, `null`) reproduces the original breakpoint-only behavior exactly.
+- `hideToggle: boolean = false` (reflected, attribute `hide-toggle`) — suppresses the built-in mobile
+  `[part='toggle']` hamburger/close button entirely, for a consumer that already owns an external
+  mobile-menu toggle wired to this rail's own `open` property. `false` (the default) reproduces the
+  exact existing output; note `open` still has no built-in external trigger of its own once this is
+  set, since `lr-toggle` only fires from the toggle button being activated.
+- `resizable: boolean = false` (reflected) — opts a continuously draggable width in for the `'full'`
+  state, exposing a `[part='resizer']` handle clamped to `[minRailWidthPx, maxRailWidthPx]`. `false`
+  (the default) renders no resizer and leaves the fixed-width `--lr-app-rail-width` CSS token
+  exactly as before this property existed.
+- `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
+  `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
+  width.
+- `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `dragging: boolean = false` (reflected) — `true` for the duration of an active pointer-driven
+  resize drag (not a keyboard step); reflected so a consumer (or this component's own styles) can
+  suppress `[part='base']`'s `transition: inline-size` during the drag, which otherwise visibly
+  "chases" the pointer instead of tracking it 1:1. Effectively read-only (this component owns the
+  transitions), but a plain reflected property like every other boolean here.
+
+Also settable as a plain `aria-label` attribute (not a reactive property): overrides the computed
+`label`/localized-default accessible name on both the navigation landmark and the mobile dialog
+role, matching `<lr-date-input>`'s `accessibleLabel`.
+
+**Events:** `lr-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
+effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
+fired for a redundant reassignment to the mode already in effect), `lr-toggle`
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
+built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
+mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly),
+`lr-rail-resize` (`detail: AppRailResizeDetail` = `{ widthPx: number }`; the `resizable` rail's
+width changed via drag or keyboard stepping — not fired when a consumer sets `railWidthPx` directly).
+
+**Slots:** default (nav items — generic slotted content, e.g. `<a>`/`<button>` elements the consumer
+builds with its own icon+label structure; clicking anywhere in this slot closes the mobile overlay if
+open), `header` (logo/brand content, shown above the nav items in every mode), `footer` (a trailing
+user/settings trigger, shown below the nav items).
+
+**CSS parts:** `base`, `header`, `nav`, `footer`, `toggle` (hidden via CSS outside `'mobile'` mode, or
+entirely via `hideToggle`), `backdrop`, `panel` (`base`/`panel` are mutually exclusive on the same
+underlying element — see above), `resizer` (the `resizable` opt-in's drag handle, only rendered while
+`resizable` and `mode` is `'full'`; its hit target is `--lr-icon-button-size`-wide), `resizer-track`
+(the slim 3px visible drag line centered inside that hit target, tinted `--lr-color-brand` on hover).
+
+**Themeable custom properties:** `--lr-app-rail-width` (default `15rem` — the inline rail width in
+`'full'` mode), `--lr-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
+mode), `--lr-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
+width), `--lr-app-rail-overlay-color` (default `var(--lr-color-overlay)` — the mobile backdrop scrim
+color; component-specific since no shared token exists), plus shared tokens (`--lr-color-border`,
+`--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`, `--lr-color-brand-quiet`,
+`--lr-space-*`, `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`,
+`--lr-focus-ring-*`, `--lr-transition-base`). `resizable`'s width is driven entirely by
+`railWidthPx`'s inline `inline-size` style rather than a new custom property.
+
+**Optional peer deps:** none.
+
+```html
+<lr-app-rail label="Main navigation" icon-only-breakpoint="960px" mobile-breakpoint="600px" resizable>
+  <span slot="header"><img src="/logo.svg" alt="Acme" /></span>
+  <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+  <a href="/settings" aria-label="Settings"><svg aria-hidden="true">...</svg><span>Settings</span></a>
+  <span slot="footer"><button>Profile</button></span>
+</lr-app-rail>
+<script type="module">
+  const rail = document.querySelector('lr-app-rail');
+  rail.addEventListener('lr-rail-resize', (e) => localStorage.setItem('railWidthPx', String(e.detail.widthPx)));
+</script>
+```
+```ts
+rail.mode = 'icon-only'; // force a presentation regardless of viewport width
+rail.mode = 'auto';      // release the force, resume live breakpoint tracking
+```
+
+The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
+boolean, preferredMode?: 'full' | 'icon-only' | null): AppRailMode` resolver (plus the
+`AppRailMode`/`AppRailModeInput`/`AppRailModeChangeDetail`/`AppRailToggleDetail`/`AppRailResizeDetail`
+types) — the same logic the element's internal `matchMedia` listeners call, exposed standalone so a
+consumer can compute or unit-test the same resolution without a real browser window. `mobileMatches`
+wins over everything else when true (the viewport is narrower than both breakpoints at once);
+otherwise `preferredMode` (when set) wins over `iconOnlyMatches`.
+
+The mobile state keeps its own panel template rather than nesting `<lr-dialog>`, while its modal
+behavior participates in the shared overlay stack. It is a plain `<div>` with an explicit
+`role="navigation"` (swapping to `role="dialog"` while the overlay is open) rather than a literal
+`<nav>` tag, since a
+`<nav>`'s implicit role can't be overridden to `role="dialog"` without an `aria-allowed-role`
+violation. In `'icon-only'` mode, slotted nav items lose their visible text label — give each one a
+real accessible name (`aria-label`, visually hidden text, or `title`) regardless, since this
+component only lays out whatever is slotted and can't inspect or fix up a consumer's own markup.
+
+**Known gotchas:**
+- `mode`'s setter accepts the wider `AppRailModeInput` (including the `'auto'` sentinel) but the
+  getter's return type is the narrower `AppRailMode` — assigning `'auto'` is a one-way instruction,
+  not a value read back later; there is no `isForced`-style property to check whether the rail is
+  currently locked to a mode or tracking the viewport.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint` after first render tears down and rebuilds
+  the `matchMedia` listeners, but does not itself un-force a previously-forced `mode` — if a consumer
+  set `mode = 'icon-only'`, changing the breakpoints won't resume auto-tracking until `mode = 'auto'`
+  is set explicitly.
+- leaving `'mobile'` mode while `open` (via a breakpoint crossing or a forced `mode` reassignment)
+  auto-closes the overlay through the same path as the toggle button, so `lr-toggle` still fires
+  and the scroll lock/focus trap still release normally — a consumer listening only for explicit
+  toggle-button clicks would miss this closure.
+- the mobile panel is also given `inert` whenever `mode === 'mobile'` and `open` is `false` — it's
+  removed from the accessibility tree and tab order via `inert` at the same time it's hidden visually
+  via `transform: translateX(-100%)`, both applied simultaneously rather than one implying the other.
+- the offscreen slide direction for the mobile panel is flipped for RTL via a `:dir(rtl)` CSS
+  selector (`translateX(100%)`), not through the shared `internal/rtl.ts` JS helper used for pointer/
+  keyboard math elsewhere in this library — a physical `transform` isn't expressible with logical
+  properties, so this one case is handled purely in CSS.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if the overlay was still active
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- `resizable`'s drag handle is pointer-only (`pointerdown`/`pointermove`/`pointerup`/
+  `pointercancel`/`lostpointercapture`) plus discrete Left/Right-arrow keyboard stepping (8px per
+  press, RTL-aware) — there's no dedicated touch gesture beyond what Pointer Events already unify.
+- reassigning `railWidthPx` while `resizable` is unset has no visible effect on the rendered width —
+  the fixed-width `--lr-app-rail-width` token still governs `'full'`-mode width until `resizable`
+  is also set.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint`/`preferredMode` does not itself un-force a
+  previously-forced `mode` — same caveat as above, `preferredMode` is only consulted while `mode`
+  isn't force-pinned.
+
+### `lr-app-rail-item`
+
+An explicit navigation item for `<lr-app-rail>`. It renders an accessible link when `href` is
+set and enabled, otherwise a button; the rail can add its `icon-only` presentation state without
+removing the label from the accessibility tree.
+
+**Properties:**
+- `href: string = ''` — optional destination. Without it, the item renders as a button.
+- `target: string = ''` — optional link target.
+- `disabled: boolean = false` (reflected) — prevents activation while retaining the item in the rail.
+- `active: boolean = false` (reflected) — marks this as the destination for the current page/view;
+  reflects `aria-current="page"` on `[part='base']` and drives the active visual treatment. The rail
+  has no built-in routing, so the consumer sets this per item (e.g. by comparing `href` against the
+  current location).
+- `tooltip: boolean = false` (reflected) — opt-in hover/focus flyout (`[part='tooltip']`) showing
+  this item's label text while the rail's `icon-only` mode (set externally by the parent
+  `<lr-app-rail>` as the viewport narrows) hides it from view. No effect outside icon-only mode,
+  since the label is already visible there. `false` (the default) reproduces the exact existing
+  output.
+
+**Slots:** default (the visible label), `icon` (the leading icon, hidden from assistive technology
+when the item has an explicit `aria-label`).
+
+**CSS parts:** `base`, `icon`, `label`, `tooltip` (the hover/focus label flyout, only rendered while
+`tooltip` is set, the item is `icon-only`, and it is hovered or focused).
+
+**Themeable custom properties:** `--lr-app-rail-item-current-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-app-rail-item-current-color` (default
+`var(--lr-color-brand)`) — background and text/icon color of the `active` (`aria-current="page"`)
+item. Both are scoped to `[aria-current='page']` only and declared as inline `var()` fallbacks at
+the point of use, never on `:host`, so either can be set on the item itself *or on any ancestor* —
+including on `<lr-app-rail>` or a wrapper above it, to tint every item's active state at once.
+`::part(base)[aria-current='page']` is invalid CSS (Shadow Parts forbids an attribute selector after
+`::part()`), so before these hooks the only lever was overriding the library-wide
+`--lr-color-brand-quiet`/`--lr-color-brand` tokens, which repainted every other element reading
+them. Unset, each falls back to the token its rule used before.
+
+**Optional peer deps:** none.
+
+---

package/llms/components/lr-archive-viewer.md

@@ -0,0 +1,42 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-archive-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraArchiveViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `jszip` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-archive-viewer`
+
+Lists entry names and human-readable uncompressed sizes inside a `.zip` archive using the optional
+`jszip` peer. It is listing-only: entry content is never rendered or previewed. Each entry's size is
+read straight from JSZip's local file header (`uncompressedSize`) when available, falling back to
+fully decompressing only the rare entry missing that header field. The list composes
+`<lr-virtual-list>` for large archives.
+
+**Properties:** `src` and `name` are strings — `name` (or a host-level `aria-label`) names the
+listing region as `role="region"`; with neither set, the region is unnamed.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
+`spinner`, and `error`. A directory row's name element carries both `entry-name` and
+`entry-name-dir` (a part list), so `::part(entry-name-dir)` selects only directory names while
+`::part(entry-name)` still selects every name. Entry rows are rendered into the embedded
+`<lr-virtual-list>`'s own shadow root and forwarded with `exportparts`, so
+`lr-archive-viewer::part(entry)` (and every other row part above) reaches them from a consuming
+stylesheet.
+
+**Exports:** `ArchiveEntry` — `{ name: string; dir: boolean; size: number }`.
+
+**Optional peer dependency:** install `jszip` with `pnpm add jszip`. The lazy registry registers
+`application/zip` and `application/x-zip-compressed`, with a `.zip` filename fallback, and imports
+the viewer only when a matching archive is opened. `.tar`, `.rar`, and other archive formats fall
+through to `<lr-document-preview>`'s generic download fallback.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the entry listing.