@aceshooting/lyra-ui 4.2.0 → 5.1.0

package/llms/components/lr-entity-card.md

@@ -0,0 +1,64 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-entity-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/entity-card/entity-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraEntityCard`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/entity-card/entity-card.class.js`
+- **Family** `components/retrieval/` — 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-entity-card`
+
+A dossier card for one knowledge-graph entity: type badge, description, key/value property rows,
+degree, community chip, plus a built-in "focus in graph" action. Never fetches or focuses a graph
+itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
+`focusNode(id, options?)`.
+
+**Properties:**
+- `entity: LyraEntity | null = null` (attribute: false) — `LyraEntity { id: string; label: string;
+  type?: string; description?: string; properties?: Record<string, string | number>; degree?:
+  number; communityId?: string }`; field names deliberately mirror `lr-graph`'s `GraphNode`
+  additions, so a graph node adapts into a `LyraEntity` with no mapping table; `null` renders the
+  empty state
+- `types: NodeTypeStyle[] = []` (attribute: false) — the same `lr-graph.nodeTypes`/
+  `lr-graph-legend.types` entry shape, resolving `entity.type` to a label/color/shape for the badge
+- `communityLabel: string = ''` (attribute `community-label`) — override text for the community chip
+- `showFocusButton: boolean = true` (attribute `show-focus-button`)
+
+**Events:** `lr-entity-activate` (`detail: { id }`, the built-in focus button was activated).
+
+**Slots:** default (extra body content below the property rows, e.g. a `lr-neighbor-list`),
+`actions` (extra header actions alongside the built-in focus button).
+
+**CSS parts:** `base`, `header`, `type-badge`, `title` (`role="heading" aria-level="3"` by default),
+`description`, `properties`, `property` (one key/value row), `degree`, `community`, `actions`,
+`focus-button`, `empty` (shown when `entity` is `null`).
+
+**Themeable custom properties:** shared tokens only; a data-driven `entity.type` color is applied as
+sanitized inline `--lr-badge-*` overrides on the type badge only (the one "type color is
+data-driven by design" exception this library already grants graph nodes) — every other color comes
+from tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lr-entity-card id="card"></lr-entity-card>
+<script>
+  document.getElementById('card').entity = {
+    id: 'e1', label: 'Ada Lovelace', type: 'person',
+    description: 'Mathematician', properties: { born: 1815 }, degree: 4,
+  };
+  document.getElementById('card').addEventListener('lr-entity-activate', (e) => graph.focusNode(e.detail.id));
+</script>
+```
+
+**Known gotchas:**
+- The type badge's data-driven background uses an 8% (not this codebase's usual 16%) quiet-tint mix
+  against `--lr-color-surface` — the lower percentage is required to hold WCAG AA 4.5:1 text
+  contrast for arbitrary, unvetted type colors (even 10% isn't safe margin for every hue in the
+  palette).
+
+---

package/llms/components/lr-entity-chip.md

@@ -0,0 +1,50 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-entity-chip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/entity-chip/entity-chip.js';` (registers the tag; side-effect import)
+- **Class** `LyraEntityChip`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/entity-chip/entity-chip.class.js`
+- **Family** `components/retrieval/` — 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-entity-chip`
+
+An inline `@entity` mention for agent prose: flow content, keyboard-focusable, with a hover/focus
+preview popover. The knowledge-graph sibling of `lr-citation-badge`, reusing its interaction
+contract wholesale. Carries ids through events only — no entity data resolution, no navigation.
+
+**Properties:**
+- `entityId: string = ''` (attribute `entity-id`)
+- `label: string = ''` — the chip's visible text
+- `type: string = ''` (reflected) — lets a host theme per type from CSS, e.g.
+  `lr-entity-chip[type='person'] { --lr-entity-chip-color: ... }`
+- `typeLabel?: string` (attribute `type-label`) — optional spoken/visible type qualifier
+
+**Events:** `lr-entity-activate` (`detail: { id }`, click, or Enter while focused),
+`lr-entity-open` (`detail: { id }`, dblclick, or Space while focused).
+
+**Slots:** default — rich preview content (typically a compact `lr-entity-card`), shown in a
+floating popover on hover/focus. No content means no popover and no hover affordance at all.
+
+**CSS parts:** `base` (the clickable `<button>`), `label`, `popover`.
+
+**Themeable custom properties:** `--lr-entity-chip-color` (default `var(--lr-color-brand)`,
+text/accent color), `--lr-entity-chip-bg` (default `var(--lr-color-brand-quiet)`),
+`--lr-entity-chip-border` (default `transparent`, the chip's `--lr-border-width-thin` outline).
+
+**Optional peer deps:** none.
+
+```html
+<p>…first described by <lr-entity-chip entity-id="e1" label="Ada Lovelace" type="person">
+  <lr-entity-card slot=""></lr-entity-card>
+</lr-entity-chip>.</p>
+```
+
+**Known gotchas:**
+- Reuses `lr-citation-badge`'s exact "real preview content" detection (an assigned element with no
+  other `slot`, or non-whitespace text) to decide whether a popover exists at all.
+
+---

package/llms/components/lr-entity-dossier.md

@@ -0,0 +1,71 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-entity-dossier`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/entity-dossier/entity-dossier.js';` (registers the tag; side-effect import)
+- **Class** `LyraEntityDossier`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/entity-dossier/entity-dossier.class.js`
+- **Family** `components/retrieval/` — 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-entity-dossier`
+
+Entity detail surface: a persistent header (`lr-entity-card` + an optional confidence `lr-stat`)
+above an `lr-tabs` strip for Relationships (`lr-neighbor-list`), Supporting chunks
+(`lr-chunk-inspector`), and Provenance (`lr-provenance-panel`). Pure layout — never fetches, ranks,
+or mutates graph/document state.
+
+**Properties:**
+- `entity: LyraEntity | null = null` (attribute: false) — `lr-entity-card`'s own `LyraEntity`;
+  `null` renders the shared `lr-empty` `noData` state in place of the whole dossier
+- `confidence: LyraEntityDossierConfidence | null = null` (attribute: false) —
+  `LyraEntityDossierConfidence { label: string; value: string; unit?: string; variant?: StatVariant;
+  exactValue?: string; caption?: string; rows?: StatRow[] }` (exported by this module; `StatVariant`
+  and `StatRow` are `lr-stat`'s own types). All caller-supplied domain data, never routed through
+  `localize()`. `null` omits the stat entirely — no placeholder
+- `neighbors: LyraNeighborRow[] = []` (attribute: false) — forwarded verbatim to
+  `lr-neighbor-list.rows` (`{ relation: string; direction: 'in' | 'out' | 'both'; node: LyraEntity }`)
+- `chunks: LyraChunk[] = []` (attribute: false) — forwarded to `lr-chunk-inspector.chunks`; the
+  evidence for *this entity's own* summary/properties
+- `provenance: LyraProvenance | null = null` (attribute: false) — forwarded to
+  `lr-provenance-panel.provenance`; deliberately a separate input from `chunks` (the broader
+  grounding chain, which may span other entities/relationships/communities). Pass the same array to
+  both when the two genuinely coincide
+- `types: NodeTypeStyle[] = []` (attribute: false) — `{ id: string; label: string; color?: string;
+  shape?: 'circle' | 'square' | 'diamond' }`, the `lr-graph.nodeTypes` entry shape; forwarded to both
+  `lr-entity-card` and `lr-provenance-panel`
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  forwarded to both `lr-chunk-inspector` and `lr-provenance-panel`
+- `groupByRelation: boolean = false` (attribute `group-by-relation`) — forwarded to `lr-neighbor-list`
+- `expandable: boolean = false` — forwarded to `lr-neighbor-list`
+- `showFocusButton: boolean = true` (attribute `show-focus-button`) — forwarded to `lr-entity-card`
+- `communityLabel: string = ''` (attribute `community-label`) — forwarded to `lr-entity-card`
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name for the internal
+  `lr-tabs` strip; unset renders the strip with no `aria-label`
+
+**Events:** declares none of its own. Every composed child's event bubbles through unmodified
+(`composed: true`): `lr-entity-activate` (`detail: { id }`), `lr-node-expand` (`detail: { id }`),
+`lr-chunk-open` (`detail: { id, sourceId, anchor? }`), `lr-expand` (`detail: { id, expanded }`),
+`lr-toggle` (`detail: { section, expanded }`), and `lr-tabs-change`
+(`detail: { tabId: LyraEntityDossierTab }`, where `LyraEntityDossierTab = 'relationships' | 'chunks'
+| 'provenance'` — also the `lr-tabs` slot/tab ids).
+
+**Slots:** none.
+
+**CSS parts:** `base` (root, or the empty state's wrapper), `empty` (shown when `entity` is `null`),
+`header`, `entity-card`, `confidence` (only when `confidence` is set), `tabs`, `neighbor-list`,
+`chunk-inspector`, `provenance-panel`.
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- The active tab is internal `@state`, not a controlled property — `lr-tabs` already owns it, and a
+  stale public property re-bound on an unrelated re-render would fight the user's own click.
+- Tab labels reuse each composed child's own `localize()` key (`neighborListLabel`,
+  `chunkInspectorLabel`, `provenancePanelLabel`), so a locale only translates each string once.
+
+---

package/llms/components/lr-env-list.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-env-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/env-list/env-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraEnvList`, also available unregistered from `@aceshooting/lyra-ui/components/data/env-list/env-list.class.js`
+- **Family** `components/data/` — 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-env-list`
+
+A masked key/value list for environment variables and secrets, with per-row reveal and copy.
+Masking is presentational, not a security boundary: the real value sits in a DOM property
+regardless of mask state.
+
+**Properties:** `entries: EnvEntry[] = []` (attribute: false), `revealable: boolean = true`
+(reflected), `copyable: boolean = true` (reflected), and `label: string = ''`.
+
+**Events:** `lr-reveal-change` (`detail: { name, revealed }`) and `lr-copy` (`detail: { text }`,
+the real unmasked value).
+
+**CSS parts:** `base` (the `<dl>` root), `name` (the `<dt>` text), `value-cell` (the `<dd>` wrapping
+an entry's value text and buttons), `value` (carries `data-masked`), `reveal-button`, and
+`copy-button`.

package/llms/components/lr-eval-dataset.md

@@ -0,0 +1,45 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-eval-dataset`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/eval-dataset/eval-dataset.js';` (registers the tag; side-effect import)
+- **Class** `LyraEvalDataset`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/eval-dataset/eval-dataset.class.js`
+- **Family** `components/agent-tools/` — 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-eval-dataset`
+
+Filterable and taggable evaluation-example list with add, remove, import, and export affordances.
+
+**Properties:**
+- `examples: EvalExample[] = []` (attribute: false) — `EvalExample { id: string; input: string;
+  expectedOutput?: string; tags?: string[]; metadata?: Record<string, unknown> }` (exported here).
+  Deliberately its own small shape rather than reusing anything from `src/ai/types.ts` — none of that
+  module's interfaces models "one row of a labeled eval dataset". `input`/`expectedOutput` are plain
+  strings (not structured payloads) to match `lr-data-grid`'s stringifying cell rendering. Fully
+  controlled: add/remove/import/export are all *requests*; the host mutates and passes the array back
+- `searchable: boolean = false` (reflected) — built-in free-text search over `input`,
+  `expectedOutput`, and `tags` (case-insensitive substring)
+- `accept: string = ''` — forwarded to the internal `lr-file-input`'s `accept` (e.g. `'.json,.csv'`);
+  empty accepts any type
+- `exportFormats: ExportFormatOption[] = ['csv', 'json']` (attribute: false) — forwarded to the
+  internal `lr-export-button`
+- `disabled: boolean = false` (reflected) — disables every add/remove/import/export affordance, e.g.
+  while a host-side mutation is still in flight
+- `label: string = ''` — accessible name for the grid region; defaults to the localized
+  `evalDatasetLabel`
+
+**Events:** `lr-example-select` (`detail: { id: string | null }`), `lr-example-add-request`
+(`detail: undefined`), `lr-example-remove-request` (`detail: { id: string }`), `lr-import-request`
+(`detail: { files: File[] }`), `lr-export-request` (`detail: { format: string }`).
+
+**CSS parts:** `base`, `toolbar`, `search`, `search-input`, `tag-filter`, `grid`,
+`add-button`, `remove-button`, `import`, `export`.
+
+**Known gotchas:**
+- Shrinking `examples` out from under live UI state is handled: a `selectedId` that no longer matches
+  any row resets to `null`, and an active tag filter that no longer matches any row's `tags` is
+  dropped rather than silently matching zero rows forever.

package/llms/components/lr-eval-result.md

@@ -0,0 +1,45 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-eval-result`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/eval-result/eval-result.js';` (registers the tag; side-effect import)
+- **Class** `LyraEvalResult`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/eval-result/eval-result.class.js`
+- **Family** `components/agent-tools/` — 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-eval-result`
+
+Rubric scoring and human-review surface for comparing the runs of one evaluation example.
+
+Composes `lr-data-grid` (the comparison table), `lr-rubric-form` (the review surface), and
+`lr-diff-view` (baseline↔selected output diff) rather than re-deriving any of their behavior.
+
+**Properties:**
+- `runs: EvalRunResult[] = []` (attribute: false) — `EvalRunResult { id: string; label: string;
+  model?: string; promptVersion?: string; output: string; scores?: RubricValue; review?: RubricValue }`
+  (exported here). One entry per model or prompt version being compared for a single evaluation
+  example. `scores`/`review` use the same `RubricValue` shape `lr-rubric-form` itself reads and
+  writes, so a `DataGridColumn`'s `value()` accessor and the rubric form's own `value` binding read a
+  run's fields with no conversion
+- `columns: DataGridColumn<EvalRunResult>[] = []` (attribute: false) — plain pass-through to
+  `lr-data-grid.columns`, not re-derived here
+- `rubricKeys: RubricKey[] = []` (attribute: false) — plain pass-through to `lr-rubric-form.keys`
+- `selectedRunId: string = ''` (attribute `selected-run-id`) — the run open for review and the diff's
+  **new** side; falls back to `runs[0]?.id` when empty
+- `baselineRunId: string = ''` (attribute `baseline-run-id`) — the run compared against and the
+  diff's **old** side; falls back to `runs[0]?.id` when empty
+- `reviewSkippable: boolean = false` (attribute `review-skippable`) — shows a Skip control on the
+  review form (forwarded to `lr-rubric-form.skippable`)
+- `disabled: boolean = false` (reflected) — disables the review form's controls only; the comparison
+  grid stays interactive (selecting a run to inspect is not a mutation)
+
+**Events:** `lr-run-select` (`detail: { runId: string }`), `lr-review-input` (`detail: { runId:
+string; value: RubricValue }`), `lr-review-validity-change` (`detail: { runId: string; valid:
+boolean; errors: Record<string, string> }`), `lr-review-submit` (`detail: { runId: string; value:
+RubricValue }`), `lr-review-skip` (`detail: { runId: string }`).
+
+**CSS parts:** `base`, `empty`, `grid`, `diff`, `diff-view`,
+`diff-labels`, `diff-label-old`, `diff-label-new`, `review`.

package/llms/components/lr-evaluation-run.md

@@ -0,0 +1,50 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-evaluation-run`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.js';` (registers the tag; side-effect import)
+- **Class** `LyraEvaluationRun`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/evaluation-run/evaluation-run.class.js`
+- **Family** `components/agent-tools/` — 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-evaluation-run`
+
+Evaluation-batch progress view with overall progress and one disclosure per example. Inputs and
+outputs may render as Markdown or code, with optional grounding and tool-trace sections.
+
+**Properties:**
+- `examples: EvaluationExampleResult[] = []` (attribute: false) — `EvaluationExampleResult { id:
+  string; label?: string; status: AgentStatus; input: string; inputFormat?: EvaluationContentFormat;
+  inputLanguage?: string; output: string; outputFormat?: EvaluationContentFormat; outputLanguage?:
+  string; grounding?: GroundingAssessment; citations?: Citation[]; toolTrace?: ToolTimelineEntry[] }`
+  (exported here). `status` reuses **`AgentStatus` from `@aceshooting/lyra-ui/ai`** (`{ kind:
+  AgentStatusKind; message? }`) — the same run-lifecycle vocabulary an agent step uses — rather than a
+  parallel pass/fail enum; rubric scoring is `lr-eval-result`'s job, not this one's.
+  `EvaluationContentFormat = 'markdown' | 'code'` — `'markdown'` (the default when unset) renders via
+  `lr-markdown`, `'code'` via `lr-code-block` consulting the matching `*Language` field for shiki.
+  `grounding`/`citations` (both from `@aceshooting/lyra-ui/ai`) compose directly into
+  `lr-grounding-summary`'s `assessment`/`citations`, and `toolTrace` directly into
+  `lr-tool-timeline.entries` — no adapters. `citations` is consulted only while `grounding` is also
+  set; an omitted `grounding` or empty `toolTrace` renders no such section for that example. `label`
+  falls back to a localized "Example {index}" (1-based, array order). Controlled and never mutated
+- `total: number | null = null` — the batch's expected total example count. `null` derives it from
+  `examples.length`; set it explicitly while a batch is still streaming and the eventual total is
+  already known
+- `label: string = ''` — header label and accessible-name source; falls back to a localized
+  "Evaluation run"
+
+**Events:** `lr-example-toggle` (`detail: EvaluationExampleToggleDetail` = `{ id: string; expanded:
+boolean }`), `lr-example-citation-select` (`detail: EvaluationCitationSelectDetail` = `{ exampleId:
+string; citation: Citation }` — the nested `lr-grounding-summary`'s own `{ citation }` correlated
+with the example it came from, so a host needn't walk the DOM), `lr-example-tool-approval-decide`
+(`detail: EvaluationToolApprovalDetail` = `ToolTimelineApprovalDetail & { exampleId: string }` =
+`{ invocationId: string; approved: boolean; args?: unknown; exampleId: string }`).
+
+**CSS parts:** `base`, `header`,
+`header-label`, `progress`, `summary`, `counts`, `count`, `examples`, `example`, `example-summary`,
+`example-label`, `example-status`, `input-section`, `input`, `output-section`, `output`,
+`grounding-section`, `grounding-summary`, `tool-trace-section`, `tool-trace`, `section-heading`,
+`live-region`, `empty`.

package/llms/components/lr-export-button.md

@@ -0,0 +1,104 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-export-button`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/export-button/export-button.js';` (registers the tag; side-effect import)
+- **Class** `LyraExportButton`, also available unregistered from `@aceshooting/lyra-ui/components/utility/export-button/export-button.class.js`
+- **Family** `components/utility/` — 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-export-button`
+
+CSV/JSON download button with extensible event-driven formats — either single-format (click exports
+immediately) or multi-format (click opens a small menu).
+
+**Properties:**
+- `rows: Record<string, unknown>[] = []` (attribute: false)
+- `columns: CsvColumn[] = []` (attribute: false) — `{ key, label }`; acts as a field allow-list **and**
+  CSV header-label source for **both** export formats when non-empty. Left empty, **both** CSV and
+  JSON fall back to the union of the rows' own keys (`key`/`label` both set to the key name) instead
+  of CSV degrading to a header-less/blank file while only JSON had a fallback — so an unconfigured
+  export still produces a proper header + data file in either format
+- `filename: string = 'export'`
+- `formats: ExportFormatOption[] = ['csv']` (attribute: false), where `ExportFormatOption` is the
+  built-in `ExportFormat = 'csv' | 'json'` or an `ExportFormatDescriptor = { id: string; label:
+  string; description?: string; extension?: string }`. Descriptor labels/descriptions are
+  consumer-supplied, already-localized copy. Custom ids are event-only; no custom encoder is bundled
+- `disabled: boolean = false` (reflected) — also disables every `[part="menu-item"]` button, not just
+  the trigger
+- `loading: boolean = false` (reflected) — controlled busy state for an async or server-generated
+  export; sets host/trigger `aria-busy` and disables the trigger and menu items. The component does
+  not toggle it automatically
+- `label: string = 'Export'` — trigger button text; also feeds the format-choice menu's `aria-label`
+  as `` `${label} format` `` so assistive tech gets an accessible name for the menu
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the trigger's accessible
+  name and feeds the localized format-menu name without changing the visible label
+- `open: boolean = false` (reflected)
+
+**Methods:** `focus(options?)` and `blur()` forward to the native trigger button.
+
+**Events:** `lr-export` (`detail: { format: string }`, **cancelable** — call `preventDefault()` to
+substitute your own server-generated download instead of the built-in client-side one),
+`lr-export-complete` (`detail: { format: 'csv' | 'json' }`, fires only after a non-cancelled
+built-in download completes), `lr-show`, `lr-hide` (format-menu visibility transitions)
+
+**Slots:** none.
+
+**CSS parts:** `trigger`, `menu`, `menu-item`, `format-label`, `format-description`
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-export-button id="exp" filename="report" label="Export"></lr-export-button>
+<script type="module">
+  const exp = document.getElementById('exp');
+  exp.rows = [{ name: 'Alpha', value: 1 }];
+  exp.columns = [{ key: 'name', label: 'Name' }, { key: 'value', label: 'Value' }];
+  exp.formats = ['csv', 'json']; // shows a format-choice menu instead of exporting immediately
+  exp.addEventListener('lr-export', (e) => console.log('exporting', e.detail.format));
+
+  // Custom formats supply menu copy but remain application-handled.
+  exp.formats = [
+    'csv',
+    { id: 'xlsx', label: 'Excel workbook', description: 'Preserves spreadsheet data types', extension: 'xlsx' },
+  ];
+  exp.addEventListener('lr-export', async (e) => {
+    if (e.detail.format !== 'xlsx') return;
+    e.preventDefault();
+    exp.loading = true;
+    try { await exportWorkbook(exp.rows); }
+    finally { exp.loading = false; }
+  });
+</script>
+```
+
+Package-level CSV utilities (used internally, also exported for standalone use — `import {
+escapeCsvField, buildCsv, downloadBlob } from '@aceshooting/lyra-ui'`):
+```ts
+escapeCsvField(value: unknown): string   // quotes/escapes; neutralizes formula-injection (=,+,@,tab,CR) with a leading apostrophe — a bare leading '-' is deliberately left alone (OWASP guidance: it's not itself formula syntax, and guarding it would mangle ordinary negative numbers)
+buildCsv(rows: Record<string, unknown>[], columns: CsvColumn[]): string  // CRLF-joined, header row included
+downloadBlob(content: string, filename: string, mime: string): void      // triggers a browser download
+```
+
+**Known gotchas:**
+- CSV and JSON are the only built-in encoders. To offer XLSX/PDF/etc., pass an
+  `ExportFormatDescriptor` and handle its id from `lr-export`; custom formats never trigger a
+  download or `lr-export-complete` on their own. A descriptor's optional `extension` is metadata
+  for that handler, not automatic filename handling.
+- CSV formula-injection guarding and the deferred (5s) `URL.revokeObjectURL` (works around Safari
+  cancelling in-flight downloads on immediate revoke) are genuine, safe-to-rely-on strengths.
+- the multi-format menu (`role="menu"`) supports full arrow-key navigation — ArrowUp/ArrowDown move
+  between items (opening the menu and seeding the right one focused, if it was closed), Home/End
+  jump to the first/last item once open, Escape closes it and returns focus to the trigger button,
+  and a completed export also returns focus to the trigger — not just Escape/click-outside as
+  before.
+- the positioned menu is constrained to the inline/block space reported by the positioner, wraps
+  long localized format labels/descriptions, scrolls when necessary, and disables its transition
+  under reduced motion.
+
+---

package/llms/components/lr-file-icon.md

@@ -0,0 +1,34 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-file-icon`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/file-icon/file-icon.js';` (registers the tag; side-effect import)
+- **Class** `LyraFileIcon`, also available unregistered from `@aceshooting/lyra-ui/components/media/file-icon/file-icon.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-file-icon`
+
+Localized, tokenized file-format badge for surrounding upload rows, cards, selectors, and viewer
+headers. The companion `getFileTypeMetadata(mimeType, fileName?)` utility covers common document,
+spreadsheet, presentation, code, archive, image, audio, and video formats. An explicit known MIME
+type wins; filename extension fallback is used only for an empty or `application/octet-stream`
+MIME type. Unknown values return a generic file result.
+
+**Properties:** `mimeType` (attribute `mime-type`), `name`, `size` (bytes; `0` renders no size),
+`label`, `decorative`, and `variant: 'icon' | 'label'`.
+
+**CSS parts:** `base`, `icon`, `label`, and `size`.
+
+**Themeable custom properties:** `--lr-file-icon-size` (default `var(--lr-size-2rem)` — the
+format badge's inline and block size).
+
+**Exports:** `LyraFileTypeMetadata`, `LyraFileTypeIcon`, `LyraFileTypeCategory`,
+`getFileTypeMetadata()`, and `registerFileTypeMetadata()` for application-specific mappings.
+
+```html
+<lr-file-icon mime-type="application/pdf" variant="label"></lr-file-icon>
+```

package/llms/components/lr-file-input.md

@@ -0,0 +1,104 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-file-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/file-input/file-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraFileInput`, also available unregistered from `@aceshooting/lyra-ui/components/media/file-input/file-input.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-file-input`
+
+A drag-drop + click-to-browse file dropzone. Emits raw `File[]` only — no client-side CSV/XLSX/etc.
+parsing (that's left entirely to the host).
+
+**Properties:**
+- `multiple: boolean = false` (reflected)
+- `disabled: boolean = false` (reflected)
+- `accept: string = ''` — a native-`accept`-style string (`.csv,.xlsx`, `text/csv`, `image/*`, or any
+  comma-separated mix); now enforced on **both** the native picker dialog and the drag-drop path, see
+  gotchas
+- `allowedMimeTypes: string[] = []` (attribute: false) — exact MIME-string allowlist
+- `forbiddenMimeTypes: string[] = []` (attribute: false) — exact MIME-string denylist, checked
+  **before** (and takes precedence over) `allowedMimeTypes`
+- `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check)
+- `directory: boolean = false` (reflected) — enables native directory selection where supported
+- `paste: boolean = true` (reflected) — accepts files pasted into the dropzone
+- `label: string = 'Drop files here or click to browse'`
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
+  dropzone/button accessible name without changing visible copy
+- `acceptedMessage: string = '{count} file(s) added.'` (attribute `accepted-message`) — live-region
+  message after an accepted selection; `{count}` is replaced with the accepted count
+- `rejectedMessage: string = '{count} file(s) rejected.'` (attribute `rejected-message`) — live-region
+  message after rejected files; `{count}` is replaced with the rejected count
+
+**Methods:** `openPicker()` programmatically opens the native file dialog; `focus(options?)`
+forwards to the interactive dropzone.
+
+**Events:** `lr-files` (`detail: { files: File[], rejected: RejectedFile[] }`, fired on both drop
+and manual file-picker selection) — `RejectedFile = { file: File; reason: 'type' | 'count' | 'size' | 'directory'
+}`: `'type'` from `accept`/`allowedMimeTypes`/`forbiddenMimeTypes`, `'count'` when a single-file
+input (`multiple` unset) receives more than one file (in which case *all* files are rejected, none
+accepted), `'size'` from `maxFileSize`, or `'directory'` for a dropped folder. `focus`/`blur` fire
+when the semantic dropzone (the actual keyboard-focusable element, not the hidden native `<input>`)
+gains/loses focus.
+
+**Slots:** default slot — custom dropzone content, overrides the `label` attribute text when
+provided. The accessible name always comes from `label` regardless, so icon-only slot content still
+announces correctly.
+
+**CSS parts:** `base`, `input`, `status` (a visually-hidden `role="status" aria-live="polite"`
+element carrying the drag accept/reject announcement)
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-space-l`,
+`--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-color-text-quiet`,
+`--lr-color-success` (drag-accept state), `--lr-color-danger` (drag-reject state),
+`--lr-focus-ring-width/-color/-offset` (`[part="base"]:focus-visible` outline),
+`--lr-opacity-disabled` (`:host([disabled])` dimming).
+
+**Optional peer deps:** none.
+
+```html
+<lr-file-input multiple accept=".csv,.xlsx" allowed-mime-types='["text/csv"]'></lr-file-input>
+<script>
+  document.querySelector('lr-file-input').addEventListener('lr-files', (e) => {
+    console.log('accepted:', e.detail.files, 'rejected:', e.detail.rejected); // rejected[i].reason
+  });
+</script>
+```
+
+Note: `allowedMimeTypes`/`forbiddenMimeTypes` are complex properties (`attribute: false`) — set
+them via JS (`el.allowedMimeTypes = [...]`), not as a JSON string attribute; the snippet above is
+illustrative of intent only.
+
+`accept.ts` exports `matchesAccept(file, accept, assumeExtensionMatch?)` (internal — not
+re-exported from the package root) — parses the same three `accept` forms the browser's native
+picker accepts (extension, exact MIME, `type/*` wildcard) and reports whether a `File` matches. Used
+both for the drop path's real rejection and for the dragenter preview, where a `DataTransferItem` (no
+`.name`, only `.type`) can't evaluate an extension pattern yet — `assumeExtensionMatch: true` treats
+that as a possible match during preview so the drag-over UI doesn't flash a false "reject" state for
+an extension-only `accept` list.
+
+**Known gotchas:**
+- Paste-from-clipboard **is** supported and on by default: a `paste` event on the dropzone reads
+  `e.clipboardData.files` and routes it through the same accept/reject classification as a drop.
+  Set `paste="false"` (or `.paste = false`) to opt out. (The package README's "Known limitations"
+  entry claiming there is no paste support, and none for dragged folders, is stale — both work.)
+- Dragged folders **are** detected via `webkitGetAsEntry()` and reported as
+  `rejected[].reason === 'directory'` (paired with a synthetic zero-byte `File` carrying the folder
+  name), not silently accepted as a phantom file.
+- `maxFileSize` fails safe rather than open: `0` (the default) or `Infinity` mean "no limit", but a
+  `NaN`/negative value — an unparsable `max-file-size` attribute, or a config that hasn't loaded
+  yet — falls back to a 25 MB cap (exported as `DEFAULT_MAX_FILE_SIZE_BYTES`) instead of disabling
+  the check.
+- `maxFileSize`/`accept` extension patterns can't be evaluated during the dragenter preview (no real
+  `File.size`/`.name` available yet from a `DataTransferItem`) — the live preview state (border/
+  background color, `status` announcement) is therefore only a best-effort hint; the authoritative
+  accept/reject decision (and `rejected[].reason`) is always the one made at actual drop time.
+- the click/keyboard-to-browse path is correctly operable (`role="button"`, `tabindex` 0/-1 by
+  disabled, `aria-disabled`, Enter/Space handling).
+
+---

package/llms/components/lr-file-tree.md

@@ -0,0 +1,29 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-file-tree`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/file-tree/file-tree.js';` (registers the tag; side-effect import)
+- **Class** `LyraFileTree`, also available unregistered from `@aceshooting/lyra-ui/components/data/file-tree/file-tree.class.js`
+- **Family** `components/data/` — 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-file-tree`
+
+A file-explorer preset over `<lr-tree>` + `<lr-file-icon>`: path-keyed nodes with
+git-status/diff-count badges, lazy directory loading, and select/open events.
+
+**Properties:** `nodes: FileTreeNode[] = []` (attribute: false), `selectedPath: string | null = null`
+(attribute `selected-path`), and `label: string = ''`.
+
+**Methods:** `setChildren(path, children)` supplies a lazily-loaded directory's children.
+`revealPath(path)` expands every ancestor directory and scrolls the target row into view, resolving
+`true` once found. `expandAll()` and `collapseAll()` forward to the underlying `<lr-tree>`.
+
+**Events:** `lr-file-select` (`detail: { path, node }`, a row was activated), `lr-file-open`
+(`detail: { path, node }`, Enter/click on an already-selected file row), and `lr-load-children`
+(`detail: { path }`, a lazy unloaded directory expanded).
+
+**CSS parts:** `base` — the root wrapper.