# `lr-ingestion-queue` - **Import** `import '@aceshooting/lyra-ui/components/lr-ingestion-queue.js';` (stable tag alias; registers the tag) - **Class** `LyraIngestionQueue`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js` - **Family** `components/retrieval/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.1.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecations** none - **Optional peers** none - **Themeable via** 17 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-ingestion-queue` Controlled list of documents moving through an ingestion pipeline: stage badge, progress, chunk/ embedding counts, retry attempts, errors, and retry/cancel requests. Never ingests anything itself. Nonstring failure details use the localized failed-stage label for row text and fresh failure announcements. Omitted details stay omitted. Formatting uses the effective locale, and historical failures remain silent on mount. **Properties:** - `items: IngestionQueueItem[] = []` (attribute: false) — `IngestionQueueItem { id: string; document: DocumentRef; stage: IngestionStage; progress?: number; chunkCount?: number; embeddedChunkCount?: number; attempts?: number; error?: string }` (exported here). `document` is **`DocumentRef` from `@aceshooting/lyra-ui/ai`** (`{ id, name, mimeType?, uri?, version? }`), not a divergent name/mimeType pair, so a caller can reuse the same list a `DocumentRef`-typed knowledge-base view already holds. `IngestionStage = 'queued' | 'uploading' | 'extracting' | 'chunking' | 'embedding' | 'indexing' | 'done' | 'failed' | 'cancelled'` — the first six are in-flight (in pipeline order), the last three terminal. `progress` is 0–100 _within the current stage_ (omitted/non-finite renders an indeterminate indicator, and it is only meaningful during an active non-`'queued'` stage). `embeddedChunkCount` renders only alongside a defined `chunkCount`. `error` renders only while `stage === 'failed'`. A missing or unrecognized runtime stage renders as a localized neutral `unknown` state with no progress, retry, or cancel affordance, allowing a newer backend stage to fail safely. Controlled — pass a new array to update - `label?: string` — fallback name for the stable region; omission uses localized `ingestionQueueLabel`. A non-empty host `aria-label` makes the host the sole overall owner (the region omits its duplicate role/name); an explicitly empty host label stays empty - `virtualizeAt: number = 100` (attribute `virtualize-at`) — item count above which the list renders through an internal `lr-virtual-list`. Exclusive, like every other `virtualize-at` in this family: exactly this many items still render as a plain list. Before 9.0.0 this was spelled `virtualizeThreshold`/`virtualize-threshold` _and_ compared inclusively (`>=`), so a migration that only renames the attribute shifts the switchover point by one item - `announce: boolean = false` (reflected) — opt-in: announce the failures the queue **already carries** the first time it mounts, instead of staying silent until a row fails later. The mount-time pass reuses the one announcement path a later failure takes — the same shared assertive light-DOM region, the same locale-aware conjunction list of the caller-supplied `item.error` strings, and the same `[part="failure-live"]` mirror — so an opted-in mount reads exactly what a live failure would. Set it where the queue is created in response to something the user just did: a retried ingestion run that mounts a fresh queue already holding `stage="failed"` rows would otherwise never speak them. Leave it unset for a queue that is part of the page a user is arriving on — those rows render in document order and repeating them is noise. Read once per element lifetime: a later reconnection or adoption stages the same rows again rather than replaying the announcement, and failures added or changed after mount announce either way. A queue carrying no `stage="failed"` row with an `error` announces nothing. Remove any host `role="status"`/`role="alert"` hand-added before this property existed once it is set — otherwise the initial failures are announced twice, through the native role and again through the shared sink Queue item ids must be nonblank and unique. Malformed rows and later duplicates are omitted first-wins before empty state, counts, virtualization, failure announcements, rendering, or actions. **Events:** - `lr-retry` (`detail: IngestionRetryEventDetail` = `RetryEventDetail & { itemId: string }` = `{ attempt: number; messageId?: string; itemId: string }`) — `attempt` is the attempt about to be made: the displayed nonnegative finite-integer `item.attempts` value plus one (invalid, negative, or fractional inputs are normalized first). Only offered on `'failed'` rows. - `lr-cancel` (`detail: IngestionCancelEventDetail` = `CancelEventDetail & { itemId: string }` = `{ reason?: string; itemId: string }`) — this component never supplies `reason` itself. Only offered on non-terminal rows (`'queued'` plus the five active stages). Both `RetryEventDetail` and `CancelEventDetail` come from `@aceshooting/lyra-ui/ai`. **Slots:** none. **CSS parts:** `base`, `list`, `item`, `item-header`, `item-name`, `item-meta`, `item-stage` (the per-item stage label), `item-progress`, `item-chunk-count`, `item-embedding-status` (the "N of M chunks embedded" text, only once both `chunkCount` and `embeddedChunkCount` are set), `item-attempts` (only once `attempts > 0`), `item-error` (only for `stage="failed"` with `error` set), `failure-live` (the visually hidden, `aria-hidden` mirror of the last announced batch of fresh failures), `item-actions`, `retry-button`, `cancel-button`, `empty`. `failure-live` is a styling and inspection surface and carries no live-region role of its own. The announcement itself goes to the library's shared **light-DOM** assertive region, appended to the consumer's `` and marked `data-lr-live-region="assertive"`, because a live region inside a shadow root is not reliably announced (JAWS with Firefox ignores one outright). What is announced is unchanged: only failures added or transitioned _after_ mount, so historical failed rows stay visible without being re-announced. Read that document-level region rather than `::part(failure-live)`. In virtualized mode (above `virtualizeAt`) the rows live in the internal `lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`, `item-meta`, `item-stage`, `item-chunk-count`, `item-embedding-status`, `item-attempts`, `item-error`, `item-actions`, `retry-button` and `cancel-button` are forwarded out through `exportparts`, so every documented row part remains reachable as `lr-ingestion-queue::part(...)` above and below the virtualization threshold. **Themeable custom properties:** `--lr-ingestion-queue-max-height` (default `none`) — non-virtualized mode only: caps how tall the list grows before it scrolls internally. No effect once virtualized — retheme the internal list via `lr-virtual-list { --lr-virtual-list-height: … }` instead. **Optional peer deps:** none. ---