Output List
Compact artifact rows with controlled selection and independent actions.
Usage
import { OutputList } from '@commenda/pathfinder/output-list';
<OutputList
items={outputs}
selectedId={activeArtifactId}
onSelectionChange={setActiveArtifactId}
onOpen={openArtifact}
actionConfig={{
onDownload: downloadArtifact,
onSaveToDocuments: saveArtifact,
}}
disclosureConfig={{ open: outputsOpen, onOpenChange: setOutputsOpen }}
/>;Pass stable IDs and newest-first items. Opening, downloading, saving, permissions, and persistence belong to the application. The menu offers download/save only when callbacks are supplied; set an item's actions.download or actions.saveToDocuments to false to omit that action for a particular artifact. Menu actions never activate the row.
Empty, loading, and collapsed
Documents, files and plans Commenda makes in this chat show up here.
Initial loading shows four skeleton lines. Refreshing a populated list keeps its rows visible. A collapsed section shows the loaded artifact count. Use disclosureConfig.defaultOpen for local state, or open with onOpenChange to persist the preference in your app.
Responsive output panel
Keep the conversation here. Open an output to focus its existing artifact tab; the application supplies its editor or preview.
The example composes Output List and Run List in a 292px column. At viewport widths of 1280px and above it starts visible; from 1024px to 1279px it starts hidden with a header toggle. Below 1024px, the toggle opens a modal bottom Sheet. These layout and preference choices remain in the host, so a compact card is also usable outside chat.
Complete workflow
Choose a suggested prompt, add the simulated ledger attachment, send, answer the entity question, and open the generated workpaper. This example composes Composer, Attachment, Conversation, Message, Reasoning, Tool Call, Question Card, Response Recap, and the output panel. Timers simulate upload and processing; there is no backend, real file upload/download, artifact viewer, or editor. Stop cancels the pending simulated response; a temporarily dismissed question can be reopened.
Overflow and interaction
Titles and kind labels truncate without moving the icon or menu. The full title remains in the accessible name and native title tooltip. Touch devices keep the menu button visible; hover devices reveal it on hover or keyboard focus. Removing a focused row moves focus to the next available row or section trigger.
API reference
| Prop | Type | Behavior |
|---|---|---|
itemsRequired | readonly OutputItem[] | Stable IDs, newest-first order |
onOpenRequired | (id: string) => void | Open the app's artifact preview |
selectedId | string|null | Controlled active artifact |
onSelectionChange | (id: string) => void | Selection request; does not persist internally |
actionConfig | ObjectView fields | Callbacks receive the artifact ID |
disclosureConfig | OutputDisclosureConfigView fields · 2 shapes | Controlled or local disclosure |
loadingConfig | ObjectView fields | Initial skeletons / busy state |
title | string | Defaults to Outputs |
emptyLabel | string | Empty-state explanation |
className | string | Host width and placement |
actionConfigObject fields
| Field | Type | Requirement |
|---|---|---|
onDownload | ((id: string) => void) | Optional |
onSaveToDocuments | ((id: string) => void) | Optional |
disclosureConfigObject fields
Choose one of these 2 shapes. Do not combine fields excluded by the selected shape.
Option 1
| Field | Type | Requirement |
|---|---|---|
open | boolean | Required |
onOpenChange | (open: boolean) => void | Required |
Do not supply: defaultOpen.
Option 2
| Field | Type | Requirement |
|---|---|---|
defaultOpen | boolean | Optional |
onOpenChange | ((open: boolean) => void) | Optional |
Do not supply: open.
loadingConfigObject fields
| Field | Type | Requirement |
|---|---|---|
isLoading | boolean | Required |
label | string | Optional |
OutputItem includes id, title, optional kindLabel, disabled, and actions. kind is document, plan, workpaper, pdf, csv, file, or record. A file can specify fileType; a record requires an icon such as its country flag. Other kinds can override their icon too. Prefer user-facing artifact names and localized kind labels.
Design rules
- OUTPUT-01: Use 32px rows, a 40px header, 12px card radius, 6px body padding, and 2px row gaps. Do not add a shadow or bold the selected title.
- OUTPUT-02: Show artifact titles and kinds, never internal tool names. The host supplies newest-first order without date headers.
- OUTPUT-03: Keep row opening and menu actions independent. Do not place buttons inside another button. The app owns storage, routing, permissions, and disclosure persistence.
- OUTPUT-04: New rows fade in and displaced rows slide for the base duration; keyboard-focused lists and reduced-motion users get immediate updates. Retain stable keys and restore focus after removal.
Metadata uses Soft Pearl 800 for readable contrast at 12px, a deliberate contrast adjustment from Figma's lighter 700. The header disclosure uses the existing Base UI measured-height pattern; only infrequent disclosure changes animate height, while insertion animates opacity and transforms.