Document finder

A React block (a whole screen) in Beamline's CMS & media app.

Finding documents in a CMS. Search by words in a title or text field; the filters read as a sentence of chips (type, what a field contains, as many as needed, and a reference), each opening to be changed, × removing it, more from Add filter: the documents that reference a chosen one, or that it references. Every result says why it matched (the field the words were in, the type, each condition, the reference). An agent's request is shown with what was asked and the search it ran as plain conditions; showing its search turns the results into an explicit scope where every document is ticked or unticked with the count, and running confirms the action and the titles it will change, touching nothing else. While an agent's search is shown, the documents one condition short of it are listed apart, each saying what it has instead, so what the search left out is seen before it runs.

Use it for

Finding structured documents by field values and links between them, with the reason each one matched.
Narrowing what an agent or a bulk action will touch to an explicit, confirmed list.

Not for

A command palette (command-menu).
Reviewing the agent's changes after it ran (a review screen).

Anatomy

search: words, Type, Reference with its document, field conditions with remove, Add a field condition, Clear
results: the count (or ticked of all when scoped); each document with its tick when scoped, title, type and why it matched
agent: what was asked, what it searched for, Show its search; the scope count and Run

States

no search
results
nothing matches
agent waiting
scoped
unticked
confirming
running

Keyboard

Tab through the search, filters, conditions and results; Space ticks; the run asks first

Props

Prop	Type	Default	Description
`documents` (required)	`FinderDocument[]`	—
`fields` (required)	`FinderField[]`	—	Fields that can be searched, by name and label; "title" is always searched.
`query`	`FinderQuery`	—
`defaultQuery`	`FinderQuery`	—
`onQueryChange`	`((q: FinderQuery) => void)`	—
`agent`	`AgentRequest \| null`	—	An agent's request waiting to be scoped.
`onRun`	`((ids: string[]) => void \| Promise<unknown>)`	—	Runs the agent on exactly these documents.
`className`	`string`	—	Classes on the documented visual root; no override by default.
`style`	`CSSProperties`	—	Inline styles on the documented visual root; no overrides by default.
`ref`	`Ref<HTMLDivElement>`	—	Receives the documented native target or imperative handle; omitted by default.

Built from

search-field
select
combobox
input
checkbox
alert-dialog
button

Dependencies

lucide-react

Import

import { DocumentFinder, EMPTY_QUERY } from "@beamline/document-finder";

Get it

Document finder is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent