| title | React-tier component contract |
|---|---|
| description | Props each injected component accepts in kind:'react' page source (ADR-0081). GENERATED from the REACT_BLOCKS definition in the '@objectstack/spec/ui' module — do not edit by hand. |
{/* GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not edit. */}
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.
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 |
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 |
Chart over an object’s aggregated data. Bind objectName + aggregate; the axes name the aggregate’s RESULT COLUMNS (see chartAggregateResultKeys).
| prop | type | kind | required | description |
|---|---|---|---|---|
objectName |
string |
binding | ✓ | The object this block binds to (server-connected). |
aggregate |
{ field?: string; function: 'count' | 'sum' | 'avg' | 'min' | 'max'; groupBy: string | { field: string; dateGranularity?: 'day' | 'week' | 'month' | 'quarter' | 'year' } } |
binding | Aggregation run against objectName. Result rows are keyed by the RAW FIELD NAMES: one column named after groupBy (the category) and one named after field (the value; the literal "count" for a fieldless count). Bind xAxis.field / yAxis[].field / series[].name to those names. | |
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. | |
type |
'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot' |
data | ✓ | |
title |
string |
data | Chart title | |
subtitle |
string |
data | Chart subtitle | |
description |
string |
data | Accessibility description — announced to screen readers as the chart’s label | |
height |
number |
data | Fixed plot height in pixels (overrides the container default) | |
xAxis |
object |
data | X-Axis configuration | |
yAxis |
object[] |
data | Y-Axis configuration (support dual axis) | |
series |
object[] |
data | Defined series configuration | |
colors |
string[] | object |
data | Color palette (string[]) or value→color map ({ value: color }) | |
showLegend |
boolean |
data | Display legend | |
showDataLabels |
boolean |
data | Display data labels | |
annotations |
object[] |
data | Reference lines/bands drawn over the plot: { type: "line" | "region", axis: "x" | "y", value, endValue?, color?, label?, style? } | |
interaction |
object |
data | Interaction toggles: { tooltips?, brush? } |
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) |
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 |
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). | |
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 | |
limit |
integer |
data | Number of records to display initially | |
filter |
object[] |
data | Additional filter criteria for related records | |
title |
string |
data | Custom title for the related list | |
showViewAll |
boolean |
data | Show "View All" link to see all related records | |
actions |
string[] |
data | Action IDs available for related records | |
add |
object |
data | Add-existing-via-picker config (generic m2m/junction assignment). |
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) |
Escape hatch — render any registered component by type. etc.
| prop | type | kind | required | description |
|---|---|---|---|---|
type |
string |
binding | ✓ | The registered component type to render. |
React · useAdapter · data · variables · page. Kanban/calendar/gantt/timeline/map of an object = <ListView navigation={…} /> with the matching visualization, or <Block type="object-kanban" …/>.