react-blocks.md

title	React-tier component contract
description	Props each injected component accepts in kind:'react' page source (ADR-0081). GENERATED from packages/spec/src/ui/react-blocks.ts — do not edit by hand.

{/* GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not edit. */}

React-tier component contract (ADR-0081)

Props each component accepts in kind:'react' page source. Reference blocks by their PascalCase tag. kind: data=declarative config (from the spec schema) · binding=connects to data · controlled=React state · callback=React function. These blocks are for DATA. Live data: const adapter = useAdapter(); adapter.find/findOne/create/update. STYLING (ADR-0065) — a page's source is runtime metadata, so the console's build-time Tailwind NEVER scans it: utility classNAMES silently produce no CSS. Do NOT use Tailwind className in page source. (a) Layout/chrome: inline style={} with hsl(var(--token)) theme colors — e.g. color:'hsl(var(--foreground))', background:'hsl(var(--card))', border:'1px solid hsl(var(--border))', and px/flex for layout. (b) Overlays: render <ObjectForm formType='drawer'|'modal' open onOpenChange> (a pre-styled Sheet/Dialog) — never hand-roll a fixed inset-0 backdrop.

kind: data = declarative config (from the spec schema — the authoritative source) · binding = connects the block to data · controlled = drive from React state · callback = a React function the block calls.

<ObjectForm> — object-form

Server-connected create/edit/view form for one object. Config props come from the spec FormView schema; bind + wire it with the React props below.

prop	type	kind	required	description
objectName	string	binding	✓	The object this block binds to (server-connected).
formType	'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal'	binding		Form presentation; drawer/modal render the form in a built-in overlay (use drawerSide/drawerWidth/modalSize).
fields	string[]	binding		Limit/order the fields shown (defaults to the object form fields).
initialValues	Record<string, any>	binding		Prefill values in create mode.
mode	'create' | 'edit' | 'view'	controlled		Create a new record, or edit/view an existing one — drive from React state.
recordId	string | number	controlled		Which record to load (edit/view). The hook for master/detail.
onSuccess	(record) => void	callback		Called after a successful save with the saved record (e.g. close a panel + reload).
onError	(error: Error) => void	callback		Called when the save fails.
onCancel	() => void	callback		Called when the user cancels.
submitHandler	(values) => any | Promise<any>	callback		Custom persistence instead of the default create/update.
layout	'vertical' | 'horizontal' | 'inline' | 'grid'	data		Field layout direction
columns	integer	data		Number of columns for the form body
tabPosition	'top' | 'bottom' | 'left' | 'right'	data		Tab strip position (tabbed forms)
drawerSide	'top' | 'bottom' | 'left' | 'right'	data		Drawer side (drawer forms)
drawerWidth	string	data		[DEPRECATED → size buckets] Drawer width, e.g. "480px". A pixel width cannot be chosen without knowing the client viewport — the renderer derives it.
modalSize	'sm' | 'default' | 'lg' | 'xl' | 'full'	data		Modal size (modal forms)
splitDirection	'horizontal' | 'vertical'	data		Split orientation (split forms)
sections	any[]	data
subforms	object[]	data		Inline master-detail child collections
submitBehavior	object	data		Post-submit behavior

<ListView> — list-view

Server-connected object table with toolbar and switchable visualizations (grid/kanban/calendar/gantt/…). Config props come from the spec ListView schema.

prop	type	kind	required	description
objectName	string	binding	✓	The object this block binds to (server-connected).
viewType	'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map'	binding		Which visualization to render (default grid). How you get a kanban/calendar/gantt of the object.
navigation	{ mode: 'page' | 'drawer' | 'modal' | 'split' | 'none' }	binding		What a row click does. Use { mode: "none" } when you handle clicks via onRowClick.
fields	string[]	binding		Limit/order the columns shown (defaults to the object list fields).
options	Record<string, any>	binding		View-type-specific options bag (kanban/calendar/gantt extras); prefer the typed spec props where they exist.
filters	FilterArray e.g. ['status','=','active']	controlled		ObjectQL base filter; drive from React state for tabbed/searched lists. ([field, op, value]; ops =, !=, >, <, contains, in; compound: ["and", […], […]]).
onRowClick	(record) => void	callback		Called with the clicked row's record — the hook for master/detail.
onNavigate	(recordId, action: 'view' | 'edit') => void	callback		Called for page-level navigation.
columns	string[] | object[]	data	✓	Fields to display as columns
sort	string | object[]	data
searchableFields	string[]	data		Fields enabled for search
userFilters	object	data		End-user quick-filter bar: dropdown/toggle fields or tab presets. Omit to let the renderer derive filters from select/boolean fields
pagination	object	data		Pagination configuration
grouping	object	data		Group records by one or more fields
rowHeight	'compact' | 'short' | 'medium' | 'tall' | 'extra_tall'	data		Row height / density setting
selection	object	data		Row selection configuration
rowActions	string[]	data		Actions available for individual row items
inlineEdit	boolean	data		Allow inline editing of records directly in the list view

<ObjectChart> — object-chart

Chart over an object’s aggregated data. Config props come from the spec Chart config schema.

prop	type	kind	required	description
objectName	string	binding	✓	The object this block binds to (server-connected).
aggregate	{ field, function, groupBy }	binding		Aggregation: function (sum/avg/count) over field, grouped by groupBy.
data	any[]	binding		Static/precomputed data to chart directly instead of binding via objectName + aggregate.
filter	FilterArray	controlled		ObjectQL filter scoping the data; drive from React state.
showLegend	boolean	data	✓	Display legend
title	string	data		Chart title
series	object[]	data		Defined series configuration
xAxis	object	data		X-Axis configuration
yAxis	object[]	data		Y-Axis configuration (support dual axis)
colors	string[] | object	data		Color palette (string[]) or value→color map ({ value: color })

<RecordDetails> — record:details

Field-detail panel for the bound record. Config props from the spec RecordDetails schema.

prop	type	kind	required	description
objectName	string	binding		The record’s object.
recordId	string | number	controlled		The record to show.
columns	'1' | '2' | '3' | '4'	data	✓	Number of columns for field layout (1-4)
layout	'auto' | 'custom'	data	✓	Layout mode: auto uses object highlightFields, custom uses explicit sections
sections	string[]	data		Section IDs to show (required when layout is "custom")
fields	string[]	data		Explicit field list to display (optional, overrides highlightFields)

<RecordHighlights> — record:highlights

Highlights panel — a strip of key fields. Config props from the spec RecordHighlights schema.

prop	type	kind	required	description
objectName	string	binding		The record’s object.
recordId	string | number	controlled		The record to summarize.
fields	string | object[]	data	✓	Key fields to highlight (1-7 fields max, typically displayed as prominent cards). Each item may be a bare field name or {name, label?, icon?, type?} for inline…
layout	'horizontal' | 'vertical'	data	✓	Layout orientation for highlight fields

<RecordRelatedList> — record:related_list

Related child records via a lookup. Config props from the spec RecordRelatedList schema.

prop	type	kind	required	description
objectName	string	binding		The parent object.
recordId	string | number	controlled		The parent record.
relationshipField	string	data	✓	Field on related object that points to this record (e.g., "account_id")
relationshipValueField	string	data	✓	Parent-record field whose value relationshipField stores (default 'id'; e.g. 'name' for name-keyed junctions).
limit	integer	data	✓	Number of records to display initially
showViewAll	boolean	data	✓	Show "View All" link to see all related records
columns	string[]	data		Fields to display in the related list. Optional: when omitted, columns derive from the related object's highlightFields / default list columns (a related list …
sort	string | object[]	data		Sort order for related records
filter	object[]	data		Additional filter criteria for related records
title	string	data		Custom title for the related list
actions	string[]	data		Action IDs available for related records
add	object	data		Add-existing-via-picker config (generic m2m/junction assignment).

<RecordPath> — record:path

Stage/progress bar driven by a status field. Config props from the spec RecordPath schema.

prop	type	kind	required	description
objectName	string	binding		The record’s object.
recordId	string | number	controlled		The record whose stage to show.
statusField	string	data	✓	Field name representing the current status/stage
stages	object[]	data		Explicit stage definitions (if not using field metadata)

<Block> — (any) (no spec schema — overlay only)

Escape hatch — render any registered component by type. etc.

prop	type	kind	required	description
type	string	binding	✓	The registered component type to render.

Injected scope (closure variables, reference directly — not props)

React · useAdapter · data · variables · page. Kanban/calendar/gantt/timeline/map of an object = <ListView navigation={…} /> with the matching visualization, or <Block type="object-kanban" …/>.