# Report library A React block (a whole screen) in [Beamline](https://beamline.io/)'s [Research & design](https://beamline.io/components/apps/research-design) app. Live demo: https://beamline.io/components/report-library A business's reports in one place. The directory: reports by topic and group with search, each with what it answers; one this person can't open says why; Build a custom report is its own way in. The custom report: records to report on (changing them takes out the columns, filters and grouping they don't have, and says which), columns in an order set by Move up and Move down, filters built as rules (an unfinished one said and left out), rows grouped with a total per group drawn as a donut, sorted with empty values last. Beside it the preview counts matched of eligible records, shows empty as empty (never 0, never in a total) and says when it is behind the definition, with Update; a run that fails says why. Not saved and a refused save are said; saving keeps the definition apart from the results. ## Use it for - Operations software (farms, workshops, clinics, warehouses) whose people pick a standard report or build their own from records: columns, filters, grouping and a total. - A reports area with topics, restricted reports and a custom route. ## Not for - A metric chart over time ([report-builder](https://beamline.io/components/report-builder)). - A product analytics dashboard ([product-analytics](https://beamline.io/components/product-analytics)). - Exploring a big table row by row ([data-grid](https://beamline.io/components/data-grid)). ## Anatomy - view switch: All reports / Custom report - directory: topic tabs with counts and search; groups of report rows (title, what it answers, or a lock and why it's restricted); Build a custom report - custom report setup: name; Data (records, and what a change took out), Columns (ordered list with Move up, Move down, Remove; Add a column), Filters (the query builder with its count), Grouping (group by, total in each group, sort by); Not saved / Saved, Save report - preview: matched of eligible, an unfinished-filter note, behind-the-definition notice with Update the preview (or the run's failure), the donut of group totals, the table with a heading row per group (count and total) and empty cells as a dash ## States - new dataset - columns empty - columns reordered - invalid filter - optional settings skipped - saving - save refused - saved - stale results - grouped results - dataset changed (fields taken out) - permission failure (run refused) - restricted report - no search results - stale directory figures - no matching rows ## Keyboard - Tab through the view switch, the setup's tabs (arrow keys) and each column's Move up, Move down and Remove - the query builder's own keys - Update the preview is a button in the notice ## Motion None beyond the parts' own; the preview dims while it is behind. Nothing moves at rest. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `reports` (required) | `ReportEntry[]` | — | | | `topics` (required) | `string[]` | — | | | `areas` (required) | `ReportArea[]` | — | | | `definition` | `ReportDefinition` | — | The custom report being built (controlled) or its start. | | `defaultDefinition` | `ReportDefinition` | — | | | `onDefinitionChange` | `((d: ReportDefinition) => void)` | — | | | `saved` | `ReportDefinition \| null` | — | The report as last saved: the composer says Not saved while it differs. Null: never saved. | | `onRun` | `((d: ReportDefinition) => Promise)` | — | Runs a definition for the preview; reject with why (a dataset this person can't read). | | `onSave` | `((d: ReportDefinition) => void \| Promise)` | — | | | `onOpenReport` | `((id: string) => void)` | — | | | `staleSince` | `number \| null` | — | When the directory's figures were last refreshed (ms), shown when they are behind. | | `view` | `"custom" \| "directory"` | — | | | `defaultView` | `"custom" \| "directory"` | — | | | `onViewChange` | `((v: "directory" \| "custom") => void)` | — | | | `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` | — | Receives the documented native target or imperative handle; omitted by default. | ## Built from - [segmented-control](https://beamline.io/components/segmented-control) - tabs - [search-field](https://beamline.io/components/search-field) - input - select - [query-builder](https://beamline.io/components/query-builder) - [pie-chart](https://beamline.io/components/pie-chart) - alert - button ## Dependencies `lucide-react` ## Import ```tsx import { ReportLibrary } from "@beamline/report-library"; ``` ## Get it Report library is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect) ## More in Research & design - [Research synthesis](https://beamline.io/components/research-synthesis): A research study turned into evidence in one place. Transcripts: passages marked as accepted highlights or as the assistant's suggestions (dashed)… - [Study setup](https://beamline.io/components/study-setup): Set up an unmoderated test and its screener. Test: what's tested (a website, a prototype by its share link, an app by its store page), who takes it… - [Study flow](https://beamline.io/components/study-flow): A study's blocks in order, each with where people go next. A block that routes by its answer (multiple choice, scale, open question, prototype task) has… - [Participant review](https://beamline.io/components/participant-review): One participant's session, answer by answer, beside the list of everyone who took the study. The list filters (finished, left early, with a recording)… - [Click heatmap](https://beamline.io/components/click-heatmap): One screen of a usability task as it looked (your prototype's frame or a page built from your parts, scaled into a phone) with where people clicked over… - [Tree test](https://beamline.io/components/tree-test): A tree test: build a navigation tree and read where people went. Build: pages added at the top or under any page, indented under the page above or moved… - [Prototype task](https://beamline.io/components/prototype-task): A prototype task in a study. The linked prototype refreshes from the design keeping the task and paths (a start screen gone from the new version said, a… - [Task results](https://beamline.io/components/task-results): A usability task's results, from headline outcomes down to paths and screens. Outcomes (direct success, indirect success, gave up) say their share and… - [Matrix question](https://beamline.io/components/matrix-question): A matrix question and the participant's side of it, side by side. Rows (up to ten) share one set of choices (two to seven); Enter adds a row, several… - [Prototype review](https://beamline.io/components/prototype-review): Reviewing a design file's clickable prototype. Present: the board on a stage with its wireframe, the flow chosen (an unavailable one can't be), Back… - [Report builder](https://beamline.io/components/report-builder): Build a chart from your metrics without code: choose metrics, how to group them over time, an optional breakdown, filters, the range and the chart, see… - [Review page builder](https://beamline.io/components/review-page-builder): Building the page reviewers use to go through records one by one. The queue of records (one with no title shows its id instead of a blank); the record as… - [Database builder](https://beamline.io/components/database-builder): What a database does for the people who use it, built in one place. Templates: starting values per property (a relation default points at an existing… - [Workflow builder](https://beamline.io/components/workflow-builder): Automation rules for a SaaS without code: a trigger, conditions built with the query builder that branch into Yes and No, actions and waits, drawn as a… - [Workflow library](https://beamline.io/components/workflow-library): The automation library: every automation as a row (what starts it, whether it's live, a draft or paused, who owns it, when it last ran, and its runs this… - [Drawing board](https://beamline.io/components/drawing-board): A whiteboard a team already knows how to use, like FigJam: tools in a floating bar at the bottom (Select V, Hand H, Sticky note S, Shape R/O/D, Connector… - [Model workbench](https://beamline.io/components/model-workbench): A CAD model's workbench around a large isometric scene of its bodies, each shaded from its material's appearance with a soft ground shadow and an axis… - [Component properties](https://beamline.io/components/component-properties): A design system component from three sides. Its variants as a matrix on two chosen properties, the others filtering it, each cell drawing the variant; a… - [Slot editor](https://beamline.io/components/slot-editor): Slots in a design system component, from making to filling. The main component's layer tree with a checkbox per layer: a nested frame converts to a slot… Part of [Beamline UI: polished, editable React components and complete screens for custom applications](https://beamline.io/). [Build your own style from any look; tokens, fonts, radii, motion; not only colours](https://beamline.io/docs/customize).