Component

Empty Properties Schema

Source: packages/spec/src/ui/component.zod.ts

TypeScript Usage

import { AIChatWindowProps, ElementButtonPropsSchema, ElementFilterPropsSchema, ElementFormPropsSchema, ElementImagePropsSchema, ElementMetadataViewerPropsSchema, ElementNumberPropsSchema, ElementRecordPickerPropsSchema, ElementTextInputPropsSchema, ElementTextPropsSchema, ObjectCalendarPropsSchema, ObjectFormPropsSchema, ObjectGridPropsSchema, ObjectKanbanPropsSchema, ObjectMasterDetailFormPropsSchema, ObjectMetricPropsSchema, PageAccordionProps, PageCardProps, PageContainerProps, PageHeaderProps, PageTabsProps, RecordActivityProps, RecordAlertActionSchema, RecordAlertProps, RecordChatterProps, RecordDetailsProps, RecordHighlightsField, RecordHighlightsProps, RecordHistoryProps, RecordPathProps, RecordQuickActionsProps, RecordReferenceRailProps, RecordRelatedListProps, ReferenceRailEntrySchema } from '@objectstack/spec/ui';
import type { ElementNumberProps, ElementRecordPickerProps, ObjectCalendarProps, ObjectFormProps, ObjectGridProps, ObjectKanbanProps, ObjectMasterDetailFormProps, ObjectMetricProps, PageContainerProps, RecordAlertAction, RecordAlertProps, RecordHighlightsField, RecordHistoryProps, RecordPathProps, RecordQuickActionsProps, RecordReferenceRailProps, ReferenceRailEntry } from '@objectstack/spec/ui';

// Validate data
const result = AIChatWindowProps.parse(data);

AIChatWindowProps

Properties

Property	Type	Required	Description
mode	`Enum<'float' \| 'sidebar' \| 'inline'>`	optional (default: `"float"`)	Display mode for the chat window
agentId	`string`	optional	Specific AI agent to use
context	`Record<string, any>`	optional	Contextual data to pass to the AI
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `AIChatWindowProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementButtonProps

Properties

Property	Type	Required	Description
label	`string \| Record<string, string>`	✅	Button display label
variant	`Enum<'primary' \| 'secondary' \| 'danger' \| 'ghost' \| 'link'>`	optional (default: `"primary"`)	Button visual variant
size	`Enum<'small' \| 'medium' \| 'large'>`	optional (default: `"medium"`)	Button size
icon	`string`	optional	Lucide icon name rendered inside the button, left or right of the label per `iconPosition`. Read on this component — the renderer resolves it through `lucide-react`'s `icons` map via the shared `resolveIcon` helper every `action:*` site uses (a PascalCase normaliser plus a one-entry rename map), NOT the `LazyIcon` slot the container icons use; the two paths accept different spellings, and an unknown name here renders nothing rather than a fallback glyph.
iconPosition	`Enum<'left' \| 'right'>`	optional (default: `"left"`)	Icon position relative to label
disabled	`boolean`	optional (default: `false`)	Disable the button
action	`{ type?: Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api' \| 'form'>; name?: string; label?: string \| Record<string, string>; target?: string; … }`	optional	Inline action executed on click
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementButtonProps.action`

Property	Type	Required	Description
type	`Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api' \| 'form'>`	optional (default: `"script"`)	Action functionality type
name	`string`	optional	Machine name (lowercase snake_case)
label	`string \| Record<string, string>`	optional	Display label
target	`string`	optional	URL, Script Name, Flow ID, or API Endpoint. Supports $`{param.X}` and $`{ctx.X}` interpolation.
openIn	`Enum<'self' \| 'new-tab'>`	optional	For type:'url' — where to open `target`. 'new-tab' opens a new browser tab; 'self' navigates in place. When omitted, external/absolute URLs open in a new tab and relative URLs navigate in place. Static execution option — keep it OUT of `params` (which is user-input-collection only).
method	`Enum<'POST' \| 'PATCH' \| 'PUT' \| 'DELETE'>`	optional	HTTP method for type:"api" actions. Defaults to POST.
params	`{ name?: string; field?: string; objectOverride?: string; label?: string \| Record<string, string>; … }[]`	optional	Input parameters required from user — an ActionParam[] DEFINITION array, never a payload map (a static request body goes in `bodyExtra`).
bodyExtra	`Record<string, any>`	optional	Static request-body fields for a type:"api" action, merged last (overrides user params). `{{page.<var>}}` tokens are resolved by the runtime. This — not `params` — is where a payload goes.
confirmText	`string \| Record<string, string>`	optional	Confirmation message before execution. On a registered action, pairing this with a non-empty `params` is refused — that opens a second dialog for one decision; put the question on `description` instead. Correct on a param-LESS action, where the confirm is the only dialog there is.
successMessage	`string \| Record<string, string>`	optional	Success message to show after execution
errorMessage	`string \| Record<string, string>`	optional	Error message to show when the action fails (overrides the raw error).
refreshAfter	`boolean`	optional (default: `false`)	Refresh view after execution
opensInNewTab	`boolean`	optional	Open the action result in a new tab. The renderer pre-opens the tab synchronously on click (popup-blocker-safe) and navigates it to the handler's redirectUrl.

Nested Shape: `ElementButtonProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementFilterProps

Properties

Property	Type	Required	Description
object	`never`	optional	[REMOVED] `element:filter` property `object` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:filter` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion), so every key on this element was a capability claim nothing kept. Delete the `element:filter` component; list surfaces own their filtering — use a view's `userFilters` quick-filter bar or the list toolbar's filter builder. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
fields	`never`	optional	[REMOVED] `element:filter` property `fields` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:filter` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion), so every key on this element was a capability claim nothing kept. Delete the `element:filter` component; list surfaces own their filtering — use a view's `userFilters` quick-filter bar or the list toolbar's filter builder. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
targetVariable	`never`	optional	[REMOVED] `element:filter` property `targetVariable` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:filter` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion), so every key on this element was a capability claim nothing kept. Delete the `element:filter` component; list surfaces own their filtering — use a view's `userFilters` quick-filter bar or the list toolbar's filter builder. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
layout	`never`	optional	[REMOVED] `element:filter` property `layout` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:filter` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion), so every key on this element was a capability claim nothing kept. Delete the `element:filter` component; list surfaces own their filtering — use a view's `userFilters` quick-filter bar or the list toolbar's filter builder. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
showSearch	`never`	optional	[REMOVED] `element:filter` property `showSearch` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:filter` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion), so every key on this element was a capability claim nothing kept. Delete the `element:filter` component; list surfaces own their filtering — use a view's `userFilters` quick-filter bar or the list toolbar's filter builder. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
aria	`never`	optional	[REMOVED] `element:filter` property `aria` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:filter` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion), so every key on this element was a capability claim nothing kept. Delete the `element:filter` component; list surfaces own their filtering — use a view's `userFilters` quick-filter bar or the list toolbar's filter builder. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.

ElementFormProps

Properties

Property	Type	Required	Description
object	`never`	optional	[REMOVED] `element:form` property `object` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:form` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion — "use the object-bound `object-form` block"), so every key on this element was a capability claim nothing kept. Delete the `element:form` component and use the object-bound `object-form` block instead — it is rendered, designer-publishable, and carries the same intent (`objectName`, `fields`, `mode`, `submitText`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
fields	`never`	optional	[REMOVED] `element:form` property `fields` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:form` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion — "use the object-bound `object-form` block"), so every key on this element was a capability claim nothing kept. Delete the `element:form` component and use the object-bound `object-form` block instead — it is rendered, designer-publishable, and carries the same intent (`objectName`, `fields`, `mode`, `submitText`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
mode	`never`	optional	[REMOVED] `element:form` property `mode` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:form` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion — "use the object-bound `object-form` block"), so every key on this element was a capability claim nothing kept. Delete the `element:form` component and use the object-bound `object-form` block instead — it is rendered, designer-publishable, and carries the same intent (`objectName`, `fields`, `mode`, `submitText`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
submitLabel	`never`	optional	[REMOVED] `element:form` property `submitLabel` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:form` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion — "use the object-bound `object-form` block"), so every key on this element was a capability claim nothing kept. Delete the `element:form` component and use the object-bound `object-form` block instead — it is rendered, designer-publishable, and carries the same intent (`objectName`, `fields`, `mode`, `submitText`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
onSubmit	`never`	optional	[REMOVED] `element:form` property `onSubmit` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:form` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion — "use the object-bound `object-form` block"), so every key on this element was a capability claim nothing kept. Delete the `element:form` component and use the object-bound `object-form` block instead — it is rendered, designer-publishable, and carries the same intent (`objectName`, `fields`, `mode`, `submitText`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
aria	`never`	optional	[REMOVED] `element:form` property `aria` was removed in @objectstack/spec 17 (ADR-0049) — the whole `element:form` element is retired: no renderer for it ever shipped in objectui, framework or cloud (Studio's designer palette lists it as a no-renderer exclusion — "use the object-bound `object-form` block"), so every key on this element was a capability claim nothing kept. Delete the `element:form` component and use the object-bound `object-form` block instead — it is rendered, designer-publishable, and carries the same intent (`objectName`, `fields`, `mode`, `submitText`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.

ElementImageProps

Properties

Property	Type	Required	Description
src	`string`	✅	Image URL or attachment field
alt	`string`	optional	Alt text for accessibility
fit	`Enum<'cover' \| 'contain' \| 'fill'>`	optional (default: `"cover"`)	Image object-fit mode
height	`number`	optional	Fixed height in pixels
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementImageProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementMetadataViewerProps

Properties

Property	Type	Required	Description
type	`Enum<'state_machine' \| 'flow' \| 'permission'>`	✅	Metadata view kind (ADR-0051): state_machine \| flow \| permission
name	`string`	✅	Target metadata item name; resolved package-scoped (ADR-0048), then dependencies (ADR-0046 §3.3)
object	`string`	optional	Owning object — required for object-scoped kinds: state_machine is a rule ON an object (ADR-0020), permission renders a matrix FOR one; omit for top-level flow
mode	`Enum<'diagram' \| 'matrix' \| 'summary'>`	optional	Render form; defaults per type (diagram for flow/state_machine, matrix for permission)
detail	`Enum<'business' \| 'technical'>`	optional (default: `"business"`)	Authoring altitude (ADR-0051 §3.4): business collapses technical flow nodes to business steps + approvals. NOT access (cf. book.audience); permission projection is automatic and render-time, never set here
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementMetadataViewerProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementNumberProps

Properties

Property	Type	Required	Description
object	`string`	✅	Source object
field	`string`	optional	Field to aggregate
aggregate	`Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>`	✅	Aggregation function
filter	`any`	optional	Filter criteria
format	`Enum<'number' \| 'currency' \| 'percent'>`	optional	Number display format
prefix	`string`	optional	Prefix text (e.g. "$")
suffix	`string`	optional	Suffix text (e.g. "%")
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementNumberProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementRecordPickerProps

Properties

Property	Type	Required	Description
object	`string`	✅	Object to pick records from
labelField	`string`	optional	Field rendered as each row's text (default `name`)
valueField	`string`	optional	Field whose value is written into the bound page variable (default `id`)
label	`string \| Record<string, string>`	optional	Control label rendered above the select
filter	`any`	optional	Filter criteria for available records
sort	`{ field: string; order: Enum<'asc' \| 'desc'> }[]`	optional	Row order — synonym of the component-level `dataSource.sort`, which takes precedence when both are set
limit	`integer`	optional	Max records offered — synonym of the component-level `dataSource.limit`, which takes precedence when both are set (renderer default 50)
targetVariable	`never`	optional	[REMOVED] `element:record_picker` property `targetVariable` was removed in @objectstack/spec 17 (ADR-0049) — it was a declarative hint no renderer ever read: the live binding runs the other direction, resolved from the page variable whose `source` names this component's `id`, so authoring only `targetVariable` bound nothing while reporting success. Delete the key; to bind the picked record id, declare it on the variable — `variables: [{ name: '<var>', type: 'record_id', source: '<this component id>' }]`. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
placeholder	`string \| Record<string, string>`	optional	Placeholder text
emptyText	`string \| Record<string, string>`	optional	Text shown when the query returns no records (default "No records")
displayField	`never`	optional	[REMOVED] `element:record_picker` property `displayField` was removed in @objectstack/spec 17.0.0 (ADR-0087 D2) — it was a required declaration no renderer ever read, while the renderer honoured `labelField` for the same thing and defaulted to `name`. Rename the key to `labelField`; the value (a field name) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
searchFields	`never`	optional	[REMOVED] `element:record_picker` property `searchFields` was removed in @objectstack/spec 17.0.0 (ADR-0049) — the picker renders a plain single-select with no search input, so no renderer ever read it and it narrowed nothing. Delete the key. To restrict which records the picker offers, use `filter` (or the component-level `dataSource.filter`), which the query path does apply. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
multiple	`never`	optional	[REMOVED] `element:record_picker` property `multiple` was removed in @objectstack/spec 17.0.0 (ADR-0049) — the picker is a single-select `Select` and the bound page variable holds one record id, so `multiple: true` selected nothing extra and reported success. Delete the key; multi-record selection is not implemented on this element. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementRecordPickerProps.sort[number]`

Sort field and direction pair

Property	Type	Required	Description
field	`string`	✅	Field name to sort by
order	`Enum<'asc' \| 'desc'>`	✅	Sort direction

Nested Shape: `ElementRecordPickerProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementTextInputProps

Properties

Property	Type	Required	Description
inputType	`Enum<'text' \| 'email' \| 'number' \| 'tel' \| 'url' \| 'password'>`	optional (default: `"text"`)	Native input type — drives keyboard/validation affordance and how the bound value is coerced (number → numeric).
label	`string \| Record<string, string>`	optional	Field label shown above the input
placeholder	`string \| Record<string, string>`	optional	Placeholder text shown when empty
defaultValue	`string \| number`	optional	Initial value; seeds the bound page variable on mount
required	`boolean`	optional (default: `false`)	Mark the field as required
disabled	`boolean`	optional (default: `false`)	Disable the input
description	`string \| Record<string, string>`	optional	Helper text shown below the input
targetVariable	`never`	optional	[REMOVED] `element:text_input` property `targetVariable` was removed in @objectstack/spec 17 (ADR-0049) — it was a declarative hint no renderer ever read: the live binding runs the other direction, resolved from the page variable whose `source` names this component's `id`, so authoring only `targetVariable` bound nothing while reporting success. Delete the key; to bind the typed value, declare it on the variable — `variables: [{ name: '<var>', type: 'string', source: '<this component id>' }]`. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementTextInputProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ElementTextProps

Properties

Property	Type	Required	Description
content	`string \| Record<string, string>`	✅	Text or Markdown content — a plain string, or an inline locale map
variant	`Enum<'heading' \| 'subheading' \| 'body' \| 'caption'>`	optional (default: `"body"`)	Text style variant
align	`Enum<'left' \| 'center' \| 'right'>`	optional (default: `"left"`)	Text alignment
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `ElementTextProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ObjectCalendarProps

Properties

Property	Type	Required	Description
objectName	`string`	optional	Object this calendar binds to. Optional because the component-level `dataSource` binding can supply the object instead
calendar	`any`	optional	Calendar field config: `{ startDateField, endDateField?, titleField?, colorField?, allDayField? }`
defaultView	`Enum<'month' \| 'week' \| 'day'>`	optional	Initial view mode
filter	`any`	optional	Base query filter
sort	`any`	optional	Sort for the fetched events
data	`any[]`	optional	Pre-fetched records — skips the internal fetch
staticData	`any[]`	optional	Static inline records
locale	`string`	optional	Locale override for the calendar chrome
loading	`boolean`	optional	External loading state (honoured only alongside `data`)

ObjectFormProps

Properties

Property	Type	Required	Description
objectName	`string`	optional	Object this form creates/edits. Optional because the component-level `dataSource` binding can supply the object instead
recordId	`string \| number`	optional	Record to load (edit/view modes)
mode	`Enum<'create' \| 'edit' \| 'view'>`	optional	Form mode
formType	`Enum<'simple' \| 'tabbed' \| 'wizard' \| 'split' \| 'drawer' \| 'modal'>`	optional	Form presentation
layout	`Enum<'vertical' \| 'horizontal' \| 'inline' \| 'grid'>`	optional	Field layout
columns	`number`	optional	Field columns in grid layout
fields	`any[]`	optional	Limit/order the fields shown
customFields	`any`	optional	Custom field definitions merged into the generated set
sections	`any[]`	optional	Form sections (`{ label, description?, fields }` — wizard steps / tab panes)
title	`string \| Record<string, string>`	optional	Form title
description	`string \| Record<string, string>`	optional	Form description (rendered by the drawer/modal presentations)
defaultTab	`string`	optional	Initially active tab (tabbed)
tabPosition	`Enum<'top' \| 'bottom' \| 'left' \| 'right'>`	optional	Tab strip position (tabbed)
allowSkip	`boolean`	optional	Allow skipping steps (wizard)
showStepIndicator	`boolean`	optional	Show the step indicator (wizard)
splitDirection	`Enum<'horizontal' \| 'vertical'>`	optional	Split direction (split)
splitSize	`number`	optional	Split panel size in percent (split)
splitResizable	`boolean`	optional	Allow resizing the split (split)
drawerSide	`Enum<'top' \| 'bottom' \| 'left' \| 'right'>`	optional	Drawer side (drawer)
drawerWidth	`string \| number`	optional	Drawer width (drawer)
modalSize	`Enum<'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'>`	optional	Modal size (modal)
modalCloseButton	`boolean`	optional	Show the modal close button (modal)
contentLayout	`any`	optional	Modal content layout config (modal)
confirmOnDiscard	`boolean`	optional	Confirm before discarding edits (drawer/modal)
submitText	`string \| Record<string, string>`	optional	Submit button label
cancelText	`string \| Record<string, string>`	optional	Cancel button label
nextText	`string \| Record<string, string>`	optional	Next-step button label (wizard)
prevText	`string \| Record<string, string>`	optional	Previous-step button label (wizard)
showSubmit	`boolean`	optional	Show the submit button
showCancel	`boolean`	optional	Show the cancel button
showReset	`boolean`	optional	Show the reset button
submitBehavior	`any`	optional	What happens after a successful submit (`{ kind: 'thank-you' \| …, title?, message? }`)
successMessage	`string \| Record<string, string>`	optional	Toast message on successful submit
resetOnSuccess	`boolean`	optional	Reset the form after a successful submit
navigateOnSuccess	`any`	optional	Navigate after a successful submit
readOnly	`boolean`	optional	Render every field read-only
initialValues	`Record<string, any>`	optional	Prefill values (create mode)
initialData	`Record<string, any>`	optional	Alternate spelling of `initialValues` the renderer also reads
mobile	`any`	optional	Mobile presentation overrides

ObjectGridProps

Properties

Property	Type	Required	Description
objectName	`string`	optional	Object this grid binds to. Optional because the component-level `dataSource` binding can supply the object instead
label	`string \| Record<string, string>`	optional	Grid label — used as the table caption and export file title
title	`string \| Record<string, string>`	optional	Fallback for `label` (the renderer reads `label \|\| title`)
columns	`any[]`	optional	Columns: field names or column definition objects
fields	`any[]`	optional	Field list fallback used when `columns` is absent
filter	`any`	optional	Base query filter (ObjectQL filter array/AST) — lowered to the wire `$filter`. THE key, singular — not the plural misspelling
defaultFilters	`any`	optional	Legacy base-filter fallback, read only when `filter` is absent. Prefer `filter`
sort	`any`	optional	Initial sort (array of `{ field, order }`)
defaultSort	`never`	optional	[REMOVED] `object-grid` property `defaultSort` was removed in @objectstack/spec 17 (ADR-0049) — it was the legacy second spelling of `sort`: a single `{ field, order }` pair read only when `sort` was absent, so one intent had two spellings and a grid authoring both silently ignored this one. Rename the key to `sort` and wrap the value in an array (`defaultSort: { field, order }` becomes `sort: [{ field, order }]`); the pair itself is unchanged. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
pagination	`any`	optional	Pagination config (`{ pageSize, pageSizeOptions, … }`); its presence enables paging
pageSize	`number`	optional	Flat page-size shorthand; `pagination.pageSize` wins when both are set
showPagination	`boolean`	optional	Show the pager (read only when `pagination` is absent)
searchableFields	`string[]`	optional	Fields the toolbar search queries; a non-empty list enables search
showSearch	`boolean`	optional	Show the search box (read only when `searchableFields` is absent)
rowHeight	`any`	optional	Row density mode (e.g. compact / comfortable)
grouping	`any`	optional	Row grouping config
aggregations	`any`	optional	Group aggregation config (sum/avg/… per column)
conditionalFormatting	`any`	optional	Conditional row/cell formatting rules
rowColor	`any`	optional	Row color rules
selection	`any`	optional	Selection config (`{ type: none \| single \| multiple }`)
selectable	`any`	optional	Legacy selection shorthand, read only when `selection` is absent. Prefer `selection`
rowActions	`any[]`	optional	Per-row action names
bulkActions	`any[]`	optional	Bulk action names shown on selection
batchActions	`any[]`	optional	Alternate spelling the renderer reads FIRST (`batchActions ?? bulkActions`)
bulkActionDefs	`any[]`	optional	Inline bulk-action definitions (full defs, not names)
navigation	`any`	optional	Row-click navigation config (`{ mode: page \| drawer \| modal \| split \| none }`)
editable	`boolean`	optional	Enable inline cell editing
singleClickEdit	`boolean`	optional	Enter cell edit on single click (default true when editable)
resizable	`boolean`	optional	Allow column resize (read before `resizableColumns`)
resizableColumns	`boolean`	optional	Alternate spelling of `resizable` (the renderer reads `resizable ?? resizableColumns`)
reorderableColumns	`boolean`	optional	Allow column drag-reorder
frozenColumns	`number`	optional	How many leading columns stay frozen (default 1)
showColumnTypeIcons	`boolean`	optional	Show field-type icons in column headers
exportOptions	`any`	optional	Export config (`{ formats, streaming }`)
operations	`any`	optional	Operation toggles (`{ export: false, … }`)
data	`{ provider: 'object'; object: string } \| { provider: 'api'; read?: object; write?: object } \| { provider: 'value'; items: any[] } \| { provider: 'schema'; schemaId: string; schema?: Record<string, any> }`	optional	Data source binding (ViewDataSchema — discriminated on `provider`: object \| api \| value \| schema). Static inline rows live at `{ provider: 'value', items: [...] }`; the bare-array shortcut is refused — see migration `object-grid-data-view-data-converged`
staticData	`any[]`	optional	Deprecated bare-array static-rows shortcut the renderer still reads. Prefer `data: { provider: 'value', items: [...] }`

Nested Shape: `ObjectGridProps.data[provider='object']`

Property	Type	Required	Description
provider	`'object'`	✅
object	`string`	✅	Target object name

Nested Shape: `ObjectGridProps.data[provider='api']`

Property	Type	Required	Description
provider	`'api'`	✅
read	`{ url: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>; headers?: Record<string, string>; params?: Record<string, any>; … }`	optional	Configuration for fetching data
write	`{ url: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>; headers?: Record<string, string>; params?: Record<string, any>; … }`	optional	Configuration for submitting data (for forms/editable tables)

Nested Shape: `ObjectGridProps.data[provider='value']`

Property	Type	Required	Description
provider	`'value'`	✅
items	`any[]`	✅	Static data array

Nested Shape: `ObjectGridProps.data[provider='schema']`

Property	Type	Required	Description
provider	`'schema'`	✅
schemaId	`string`	✅	Schema identifier — typically the metadata type name
schema	`Record<string, any>`	optional	Inline JSON Schema (Draft 2020-12). Optional when schemaId is resolvable.

ObjectKanbanProps

Properties

Property	Type	Required	Description
objectName	`string`	optional	Object this board binds to. Optional because the component-level `dataSource` binding can supply the object instead
groupBy	`string`	optional	Field whose values become the board columns
columns	`any[]`	optional	Swimlane definitions (`{ id, title }` per `groupBy` value, or bare value strings) — NOT a field projection
filter	`any`	optional	Base query filter, handed to the wire `$filter`
data	`any[]`	optional	Static inline cards — bypasses the object query
cardTitle	`string`	optional	Field rendered as each card title
titleField	`string`	optional	Legacy fallback for `cardTitle` (the board reads `cardTitle \|\| titleField`). Prefer `cardTitle`
cardFields	`string[]`	optional	Fields rendered on each card
swimlaneField	`string`	optional	Field for horizontal swimlanes (in addition to columns)
grouping	`any`	optional	View grouping config; its first field is the swimlane fallback
quickAdd	`boolean`	optional	Show the per-column quick-add affordance
coverImageField	`string`	optional	Image field rendered as the card cover
conditionalFormatting	`any`	optional	Card conditional formatting rules

ObjectMasterDetailFormProps

Properties

Property	Type	Required	Description
objectName	`string`	optional	PARENT object. Optional because the component-level `dataSource` binding can supply the object instead
recordId	`string \| number`	optional	Parent record to load (edit mode)
mode	`Enum<'create' \| 'edit'>`	optional	Form mode
formType	`Enum<'simple' \| 'tabbed'>`	optional	Parent form presentation — the two variants the renderer honours for the parent half
sections	`any[]`	optional	Parent form sections
fields	`any[]`	optional	Parent fields shown
details	`any[]`	optional	Detail collections (`{ title, childObject, addLabel?, columns?, relationshipField? }` — FK and columns auto-derive from child metadata)
title	`string \| Record<string, string>`	optional	Form title
submitText	`string \| Record<string, string>`	optional	Submit button label
cancelText	`string \| Record<string, string>`	optional	Cancel button label
showSubmit	`boolean`	optional	Show the submit button
initialValues	`Record<string, any>`	optional	Prefill values for the parent (create mode)
initialData	`Record<string, any>`	optional	Alternate spelling of `initialValues` the renderer also reads
taxRateField	`string`	optional	Child field holding the per-line tax rate (line-items totals)

ObjectMetricProps

Properties

Property	Type	Required	Description
objectName	`string`	optional	Object this metric aggregates. Optional because the component-level `dataSource` binding can supply the object instead
label	`string \| Record<string, string>`	optional	Metric label
description	`string \| Record<string, string>`	optional	Helper text under the value
title	`string \| Record<string, string>`	optional	Drill-down panel title; defaults to the metric label
icon	`string`	optional	Lucide icon name drawn in the metric tile header, inside the `colorVariant`-tinted square. Read on this component — `ObjectMetricWidget` forwards it to `MetricWidget`, which resolves it with `getLazyIcon` (the `LazyIcon` module: kebab-case or PascalCase, degrading to the `Database` glyph on an unknown name).
colorVariant	`Enum<'default' \| 'blue' \| 'teal' \| 'orange' \| 'purple' \| 'success' \| 'warning' \| 'danger'>`	optional	Icon container color variant
aggregate	`any`	optional	Aggregation config (`{ field, function, groupBy? }`) run against the object
filter	`any`	optional	Filter the aggregation is scoped by
format	`string`	optional	Number format pattern (e.g. '0,0', '$0,0', '0%')
currency	`string`	optional	ISO currency code (e.g. 'USD') — enables currency formatting
prefix	`string`	optional	Static prefix before the formatted value
suffix	`string`	optional	Static suffix after the formatted value
invert	`boolean`	optional	Display `1 - value` for opposite-signal gauges (compliance/uptime)
variant	`Enum<'card' \| 'bare'>`	optional	Layout variant
fallbackValue	`string \| number`	optional	Static value shown when no data source is available
trend	`any`	optional	Static trend info (`{ value, label, direction }`)
drillDown	`any`	optional	Click-through drill config — opens the underlying records
compareTo	`any`	optional	Period-over-period comparison (`{ kind: 'previousPeriod' \| 'previousYear' }`)

PageAccordionProps

Properties

Property	Type	Required	Description
items	`{ label: string \| Record<string, string>; icon?: string; collapsed: boolean; children: any[] }[]`	✅
allowMultiple	`boolean`	optional (default: `false`)	Allow multiple panels to be expanded simultaneously
variant	`Enum<'flush' \| 'card'>`	optional (default: `"flush"`)	Panel framing: 'flush' draws a divider under each panel; 'card' leaves the border to each panel's own content
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `PageAccordionProps.items[number]`

Property	Type	Required	Description
label	`string \| Record<string, string>`	✅	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
icon	`string`	optional	Lucide icon name rendered in the panel trigger, left of the label. Read on this component — the renderer draws it via `LazyIcon`; contrast the item `value` beside it, which the renderer overwrites with `panel-<index>`.
collapsed	`boolean`	optional (default: `false`)
children	`any[]`	✅	Child components

Nested Shape: `PageAccordionProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

PageCardProps

Properties

Property	Type	Required	Description
title	`string \| Record<string, string>`	optional	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
bordered	`boolean`	optional (default: `true`)
actions	`never`	optional	[REMOVED] `page:card` property `actions` was removed in @objectstack/spec 17.0.0 (ADR-0087 D2) — no renderer ever read it: objectui's card renderer builds its `<Card>` from `title`, `bordered`, `children` and `footer` only, has no actions area, and the component registry never published it as an input, so an authored value was accepted and dropped. Delete the key and author the buttons as components in the card's `children` or `footer` (`element:button`, `record:quick_actions`), which is what actually renders. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
children	`any[]`	optional	Card content components, in order (the card body slot)
body	`never`	optional	[REMOVED] `page:card` property `body` was removed in @objectstack/spec 17.0.0 (ADR-0087 D2) — it was a second spelling of the composition slot every other container calls `children`, and the renderer reads both. Rename the key to `children`; the value (an array of child components) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
footer	`any[]`	optional	Card footer components (slot)
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `PageCardProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

PageContainerProps

Properties

Property	Type	Required	Description
children	`any[]`	optional	Child components rendered inside this container, in order

PageHeaderProps

Properties

Property	Type	Required	Description
title	`string \| Record<string, string>`	optional	Page title. Omit to let the renderer derive the heading from the record (the default for record pages) — set explicitly on non-record pages (dashboard, landing) with no record to derive from.
subtitle	`string \| Record<string, string>`	optional	Page subtitle
icon	`never`	optional	[REMOVED] `page:header` property `icon` was removed in @objectstack/spec 17.0.0 (ADR-0087 D2) — no renderer ever read it: objectui resolves `icon` only per header action (`action.icon`), never off the header's own props bag, and the component registry never published it as an input, so an authored value was accepted and dropped. Delete the key. The header's own identity is drawn by the record chrome (`recordChrome`, on by default) and each action carries its own `icon`. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
breadcrumb	`boolean`	optional (default: `true`)	Show breadcrumb
actions	`string[]`	optional	Action IDs to show in header
recordChrome	`boolean`	optional (default: `true`)	Render the record chrome — the title as a record chip with its follow star and copy-id button. Set false on a non-record page (dashboard, landing) to fall back to the bare heading layout.
showStar	`boolean`	optional (default: `true`)	Show the follow (favourite) star beside the record title. Part of the record chrome — no effect when `recordChrome` is false.
showCopyId	`boolean`	optional (default: `true`)	Show the copy-record-id button beside the record title. Part of the record chrome — no effect when `recordChrome` is false.
maxVisible	`integer`	optional	How many header actions render as inline buttons before the rest fold into the overflow menu (renderer default 3).
mobileMaxVisible	`integer`	optional	The `maxVisible` budget on mobile viewports (renderer default 1).
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `PageHeaderProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

PageTabsProps

Properties

Property	Type	Required	Description
tabStyle	`Enum<'line' \| 'card' \| 'pill'>`	optional (default: `"line"`)	Tab-strip visual style: 'line' underlines the active tab, 'card' frames each tab, 'pill' renders rounded pills
type	`never`	optional	[REMOVED] `page:tabs` property `type` was removed in @objectstack/spec 17.0.0 (ADR-0087 D2) — a props key named `type` collides with the page component's own dispatch key, so it is unauthorable in the flat and JSX carriers and was never validated in them. Rename the key to `tabStyle`; the value (`line` \| `card` \| `pill`) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
position	`Enum<'top' \| 'left'>`	optional (default: `"top"`)
alwaysShowStrip	`boolean`	optional	Render the tab strip even when only one tab is visible (renderer default: a one-tab strip is hidden).
items	`{ label: string \| Record<string, string>; icon?: string; visibleWhen?: string \| object; value?: string; … }[]`	✅
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `PageTabsProps.items[number]`

Property	Type	Required	Description
label	`string \| Record<string, string>`	✅	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
icon	`string`	optional	Lucide icon name rendered in the tab trigger, left of the label. Read on this component — the renderer draws it via `LazyIcon`; contrast the item `key` beside it, which no read point takes and which the alias table answers with `value`.
visibleWhen	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Visibility predicate (CEL) — the whole tab (header + panel) is omitted when FALSE; the renderer falls back to the first visible tab when the active one is hidden. Contract-bound roots: `record`, `current_user` (ADR-0068 aliases `user` / `ctx.user`), `page.<var>`. ⚠️ NOT the same environment as page-component `visibleWhen`: this surface's own evaluator binds `data` to the record ROW (not the data-source adapter) and also spreads the row's bare fields — renderer behaviour, NOT contract-guaranteed. ADR-0089 canonical name — `visible`/`showWhen`/`visibility`/`visibleOn` are all rejected here (not folded in), each with a pointer at this key.
value	`string`	optional	Stable `?tab=` URL token for this tab (default: index-derived `tab-<i>`, which is not durable across item-list changes)
count	`integer`	optional	Badge count shown next to the tab label (default: derived from `record:related_list` descendants)
children	`any[]`	✅	Child components

Nested Shape: `PageTabsProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

RecordActivityProps

Properties

Property	Type	Required	Description
types	`(Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| 'file' \| 'record_create' \| 'record_delete' \| 'approval' \| 'sharing' \| 'system'> \| string)[]`	optional	Feed item kinds to show (default: all). Open vocabulary: the FeedItemType members are the platform built-in kinds, and author-contributed activity kinds (open sys_activity.type vocabulary, ADR-0052 §5b.2) are equally legal — entries are never validated against the built-in set.
filterMode	`Enum<'all' \| 'comments_only' \| 'changes_only' \| 'tasks_only'>`	optional (default: `"all"`)	Default activity filter
showFilterToggle	`boolean`	optional (default: `true`)	Show filter dropdown in panel header
limit	`integer`	optional (default: `20`)	Number of items to load per page
showCompleted	`boolean`	optional (default: `false`)	Include completed activities
unifiedTimeline	`boolean`	optional (default: `true`)	Mix field changes and comments in one timeline (Airtable style)
showCommentInput	`boolean`	optional (default: `true`)	Show "Leave a comment" input at the bottom
enableMentions	`boolean`	optional (default: `true`)	Enable @mentions in comments
enableReactions	`boolean`	optional (default: `false`)	Enable emoji reactions on feed items
enableThreading	`boolean`	optional (default: `false`)	Enable threaded replies on comments
showSubscriptionToggle	`boolean`	optional (default: `true`)	Show bell icon for record-level notification subscription
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordActivityProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

RecordAlertAction

Properties

Property	Type	Required	Description
actionName	`string`	✅	Name of an action declared on this object (`actions[]`) — resolved from object metadata and run through the shared action engine, so confirm/param dialogs, toast and reload behave exactly as in `record:quick_actions`.
label	`string \| Record<string, string>`	optional	CTA button label — a string or an inline locale map, resolved with the same pickLocalized chain as `title`/`body` (default: the action's own label).
variant	`Enum<'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'>`	optional	Button variant — the Button primitive's own vocabulary (renderer default: `destructive` when severity is `error`, else `default`).

RecordAlertProps

Properties

Property	Type	Required	Description
severity	`Enum<'info' \| 'warning' \| 'error' \| 'success'>`	optional	Banner severity — styling, default icon, and the a11y role (`error` renders `role="alert"`/assertive; the rest `role="status"`/polite). Renderer default: `info`.
title	`string \| Record<string, string>`	optional	Banner title — a string or an inline locale map (`{ en, "zh-CN", … }`), resolved to the current language at render (pickLocalized).
body	`string \| Record<string, string>`	optional	Banner body — a string or an inline locale map, resolved like `title`.
visible	`boolean \| string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Visibility predicate evaluated against the record page scope (`record`, `user` + `ctx.*` mirror, `objectName`, `features`) — a boolean literal, a CEL string, or a `{ dialect, source }` envelope. Omit for always-visible; the banner is hidden while the record is still loading either way.
icon	`string`	optional	Lucide icon name (renderer default: the severity's own icon). Read on this component — contrast the rail's refused `icon`, which no render path reads.
action	`{ actionName: string; label?: string \| Record<string, string>; variant?: Enum<'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'> }`	optional	Optional call-to-action button rendered under the body — `{ actionName, label?, variant? }`, resolved from the object's declared actions.
dismissible	`boolean`	optional	Render an X control; dismissal is remembered per object/record in localStorage (renderer default: off).
dismissKey	`string`	optional	Stable key the dismissal is remembered under, so reworded titles do not resurrect a dismissed banner (renderer default: the English resolution of `title`, else the severity).

Nested Shape: `RecordAlertProps.action`

Property	Type	Required	Description
actionName	`string`	✅	Name of an action declared on this object (`actions[]`) — resolved from object metadata and run through the shared action engine, so confirm/param dialogs, toast and reload behave exactly as in `record:quick_actions`.
label	`string \| Record<string, string>`	optional	CTA button label — a string or an inline locale map, resolved with the same pickLocalized chain as `title`/`body` (default: the action's own label).
variant	`Enum<'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'>`	optional	Button variant — the Button primitive's own vocabulary (renderer default: `destructive` when severity is `error`, else `default`).

RecordChatterProps

Properties

Property	Type	Required	Description
position	`Enum<'bottom' \| 'right' \| 'left'>`	optional	Where the panel docks relative to the record body — `right`/`left` dock a side panel, `bottom` renders in flow under the record body (renderer default: `bottom`).
width	`string \| number`	optional	Panel width (e.g., "350px", "30%") — side positions (`right`/`left`) only.
collapsible	`boolean`	optional	Whether the panel can be collapsed (renderer default: off).
defaultCollapsed	`boolean`	optional	Whether the panel starts collapsed (renderer default: off; only meaningful with `collapsible`).
feed	`{ types?: (Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| …> \| string)[]; filterMode: Enum<'all' \| 'comments_only' \| 'changes_only' \| 'tasks_only'>; showFilterToggle: boolean; limit: integer; … }`	optional	Embedded activity feed configuration
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordChatterProps.feed`

Property	Type	Required	Description
types	`(Enum<'comment' \| 'field_change' \| 'task' \| 'event' \| 'email' \| 'call' \| 'note' \| …> \| string)[]`	optional	Feed item kinds to show (default: all). Open vocabulary: the FeedItemType members are the platform built-in kinds, and author-contributed activity kinds (open sys_activity.type vocabulary, ADR-0052 §5b.2) are equally legal — entries are never validated against the built-in set.
filterMode	`Enum<'all' \| 'comments_only' \| 'changes_only' \| 'tasks_only'>`	optional (default: `"all"`)	Default activity filter
showFilterToggle	`boolean`	optional (default: `true`)	Show filter dropdown in panel header
limit	`integer`	optional (default: `20`)	Number of items to load per page
showCompleted	`boolean`	optional (default: `false`)	Include completed activities
unifiedTimeline	`boolean`	optional (default: `true`)	Mix field changes and comments in one timeline (Airtable style)
showCommentInput	`boolean`	optional (default: `true`)	Show "Leave a comment" input at the bottom
enableMentions	`boolean`	optional (default: `true`)	Enable @mentions in comments
enableReactions	`boolean`	optional (default: `false`)	Enable emoji reactions on feed items
enableThreading	`boolean`	optional (default: `false`)	Enable threaded replies on comments
showSubscriptionToggle	`boolean`	optional (default: `true`)	Show bell icon for record-level notification subscription
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordChatterProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

RecordDetailsProps

Properties

Property	Type	Required	Description
columns	`Enum<'1' \| '2' \| '3' \| '4'>`	optional (default: `"2"`)	Number of columns for field layout (1-4)
layout	`never`	optional	[REMOVED] `record:details` property `layout` was removed in @objectstack/spec 17.0.0 (ADR-0087 D2) — its declared `auto` \| `custom` semantics were never implemented: the renderer tests `layout` only against `inline` \| `compact`, two values the schema never permitted, so both legal values took the same branch and the key selected nothing. Delete the key — the body is already chosen by what you author: `sections` renders the explicit groups (the old `custom`), and omitting it falls back to the object's `highlightFields` (the old `auto`). Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.
sections	`{ name?: string; label?: string \| Record<string, string>; columns?: integer; fields: string[]; … }[]`	optional	Field groups rendered as the detail body, in order. Object form: `{ name?, label?, columns?, fields, hideEmpty?, collapsible?, showBorder?, defaultCollapsed?, icon?, description?, headerColor? }`.
fields	`string[]`	optional	Explicit field list to display (optional, overrides highlightFields)
hideFields	`string[]`	optional	Field names to omit from the body — applied to `fields` and to every section's `fields` (used to dedupe fields already shown in `record:highlights` or as the page title)
inlineEdit	`boolean`	optional	Allow inline field editing in the detail body (renderer default: on, where the object itself is editable — set `false` to force it off).
showHeader	`boolean`	optional	Render the detail body's own heading (renderer default: off).
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordDetailsProps.sections[number]`

Property	Type	Required	Description
name	`string`	optional	Stable section identifier for i18n lookup (snake_case) — resolves `objects.<object>._sections.<name>.label`; a nameless section renders its authored label in every locale
label	`string \| Record<string, string>`	optional	Section heading (omit for an untitled, borderless section)
columns	`integer`	optional	Field-grid columns for this section (1-4). Omitted → the renderer derives the width.
fields	`string[]`	✅	Field names rendered in this section, in order
hideEmpty	`boolean`	optional	Hide this section's empty fields (renderer default: on — and a section whose fields are ALL empty then renders nothing at all: no heading, no skeleton). Set `false` to render empty rows, keeping the section's label skeleton on an all-empty record (e.g. a brand-new one).
collapsible	`boolean`	optional	Render this section as a collapsible card — the heading becomes a chevron toggle, initially expanded (renderer default: off).
showBorder	`boolean`	optional	Draw this section's card chrome (renderer default: derived — on for a titled section, off for an untitled one). Set `false` for a borderless titled section, or `true` for a bordered untitled one.
defaultCollapsed	`boolean`	optional	Start a `collapsible: true` section collapsed (renderer default: expanded). Consulted only when `collapsible` is on — a non-collapsible section never reads its collapse state.
icon	`string`	optional	Heading icon, as a lucide icon name (kebab-case, e.g. `building-2`). A value that is not an ASCII identifier (emoji, CJK text) renders as literal text beside the heading instead. Shown where the section heading renders: a titled section, or any collapsible section.
description	`string`	optional	Sub-heading text rendered under the section heading (plain string — the renderer applies no translation to it, unlike `label`). Renders on a titled or collapsible section; a collapsible section hides it while collapsed.
headerColor	`Enum<'muted' \| 'muted/50' \| 'accent' \| 'primary/10' \| 'secondary/10' \| 'destructive/10'>`	optional	Section-header background tint, from the closed six-token vocabulary rendered by objectui's `record:details` header (`muted` \| `muted/50` \| `accent` \| `primary/10` \| `secondary/10` \| `destructive/10`). A value outside the enum is refused at authoring time rather than silently not painting. Omit for an untinted header.

Nested Shape: `RecordDetailsProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

RecordHighlightsField

Highlight field: bare name, or {name,label?,type?,readonly?}

Union Options

This schema accepts one of the following structures:

Option 1

Type: string

Option 2

Properties

Property	Type	Required	Description
name	`string`	✅	Field name on the record
label	`string`	optional	Display label (overrides schema label)
type	`string`	optional	Override cell renderer type (rare)
readonly	`boolean`	optional	Render this chip read-only — suppresses inline editing on the highlight card. Use for hook/automation-maintained columns that must not be hand-edited from the record header.

RecordHighlightsProps

Properties

Property	Type	Required	Description
fields	`(string \| { name: string; label?: string; type?: string; readonly?: boolean })[]`	✅	Key fields to highlight (1-7 fields max, typically displayed as prominent cards). Each item may be a bare field name or `{name, label?, type?, readonly?}` for inline overrides.
layout	`Enum<'horizontal' \| 'vertical'>`	optional (default: `"horizontal"`)	Layout orientation for highlight fields
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordHighlightsProps.fields[number]`

Property	Type	Required	Description
name	`string`	✅	Field name on the record
label	`string`	optional	Display label (overrides schema label)
type	`string`	optional	Override cell renderer type (rare)
readonly	`boolean`	optional	Render this chip read-only — suppresses inline editing on the highlight card. Use for hook/automation-maintained columns that must not be hand-edited from the record header.

Nested Shape: `RecordHighlightsProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

RecordHistoryProps

Properties

Property	Type	Required	Description
limit	`integer`	optional	Maximum history entries displayed, and the `$top` of the self-fetch query (renderer default: 50).
emptyText	`string`	optional	Copy shown when the record has no history. Literal string rendered as-is in EVERY locale (no inline locale map — the timeline renders it as a raw React child; renderer default: "No history yet").
unknownUserText	`string`	optional	Copy substituted when an entry has no resolvable actor. Literal string, every locale (renderer default: "Unknown user").

RecordPathProps

Properties

Property	Type	Required	Description
statusField	`string`	✅	Field name representing the current status/stage
stages	`{ value: string; label: string \| Record<string, string>; terminal?: Enum<'won' \| 'lost'> }[]`	optional	Explicit stage definitions (if not using field metadata)
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordPathProps.stages[number]`

Property	Type	Required	Description
value	`string`	✅
label	`string \| Record<string, string>`	✅	Display label — the default-language string, or an inline locale map (`{ en, "zh-CN" }`) resolved at render time
terminal	`Enum<'won' \| 'lost'>`	optional	Mark this stage a terminus and its kind — overrides the renderer's value/label token heuristic

Nested Shape: `RecordPathProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

RecordQuickActionsProps

Properties

Property	Type	Required	Description
actionNames	`string[]`	optional	Names of actions declared on this object (`actions[]`), in display order. The engine still location-filters named actions. Measured: when omitted (and the host supplies nothing) the bar resolves NO actions and renders its empty placeholder — it does not fall back to "every action at this location", whatever the registration's input list claims.
requiredPermissions	`string[]`	optional	Hide the whole bar unless the current user holds every named permission on this object.
location	`Enum<'list_toolbar' \| 'list_item' \| 'record_header' \| 'record_more' \| 'record_related' \| 'record_section'>`	optional	Which declared action location this bar renders (renderer default: `record_header`).
align	`Enum<'start' \| 'center' \| 'end'>`	optional	Horizontal alignment of the button row (renderer default: `end`).
inline	`boolean`	optional	Render in the flow instead of pulling up into the record-header band. The page header sets this itself when it hosts the bar in its own action slot.
variant	`Enum<'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'>`	optional	Button variant for every action — the Button primitive's own vocabulary; a per-action `variant` on the resolved def wins (renderer default: `default`).
size	`Enum<'default' \| 'sm' \| 'lg' \| 'icon'>`	optional	Button size for every action — the Button primitive's own vocabulary; a per-action `size` wins (renderer default: `sm`).

RecordReferenceRailProps

Properties

Property	Type	Required	Description
entries	`{ objectName: string; relationshipField: string; title?: string; limit?: integer; … }[]`	✅	Related collections to summarize — one compact card per entry (icon-less title, total-count badge, top-N preview rows). An empty rail renders nothing, so at least one entry is required.
hideEmpty	`boolean`	optional	Fold entries whose related count is 0 into a single "+ N empty" expander chip (renderer default: on; set `false` to always render every card).

Nested Shape: `RecordReferenceRailProps.entries[number]`

Property	Type	Required	Description
objectName	`string`	✅	Related object name whose records this card summarizes (e.g. "task", "opportunity_quote")
relationshipField	`string`	✅	Field on the related object that points back to this record (e.g. "account_id")
title	`string`	optional	Literal card title. Rendered as-is in EVERY locale (no inline locale map — the rail renders it as a raw React child); omit to use the related object's localized label.
limit	`integer`	optional	Preview rows per card, and the `$top` of the one query this entry issues (renderer default: 3).
displayField	`string`	optional	Field of the related record rendered in each preview row (renderer fallback when omitted: name / title / subject / label / … / id).

RecordRelatedListProps

Properties

Property	Type	Required	Description
objectName	`string`	✅	Related object name (e.g., "task", "opportunity")
relationshipField	`string`	✅	Field on related object that points to this record (e.g., "account_id")
relationshipValueField	`string`	optional (default: `"id"`)	Parent-record field whose value relationshipField stores (default 'id'; e.g. 'name' for name-keyed junctions).
columns	`string[]`	optional	Fields to display in the related list. Optional: when omitted, columns derive from the related object's highlightFields / default list columns (a related list is just another surface that lists that object). Override chain: child highlightFields → field-level relatedListColumns → this inline list.
sort	`string \| { field: string; order: Enum<'asc' \| 'desc'> }[]`	optional	Sort order for related records
limit	`integer`	optional (default: `5`)	Number of records to display initially
filter	`{ field: string; operator: Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'icontains' \| …>; value?: string \| number \| boolean \| null \| (string \| number)[] }[]`	optional	Additional filter criteria for related records
title	`string \| Record<string, string>`	optional	Custom title for the related list
showViewAll	`boolean`	optional (default: `true`)	Show "View All" link to see all related records
actions	`string[]`	optional	Action IDs available for related records
add	`{ picker: object; linkField?: string; label?: string \| Record<string, string> }`	optional	Add-existing-via-picker config (generic m2m/junction assignment).
aria	`{ ariaLabel?: string \| Record<string, string>; ariaDescribedBy?: string; role?: string }`	optional	ARIA accessibility attributes

Nested Shape: `RecordRelatedListProps.filter[number]`

View filter rule

Property	Type	Required	Description
field	`string`	✅	Field name to filter on
operator	`Enum<'equals' \| 'not_equals' \| 'contains' \| 'not_contains' \| 'icontains' \| …>`	✅	Filter operator
value	`string \| number \| boolean \| null \| (string \| number)[]`	optional	Filter value. The accepted SHAPE depends on the operator: `in` / `not_in` take an array (any length, including []), `between` takes exactly [min, max], every other operator takes a scalar. The unary operators (is_empty / is_not_empty / is_null / is_not_null) take their direction from the operator name and ignore this key.

Nested Shape: `RecordRelatedListProps.add`

Property	Type	Required	Description
picker	`{ object: string; valueField: string; labelField?: string; filter?: object[] }`	✅	Where the Add affordance sources records from.
linkField	`string`	optional	Field on `objectName` that stores the picked record id (junction case). Omit for a 1:m re-parent.
label	`string \| Record<string, string>`	optional	Label for the Add button (default "Add").

Nested Shape: `RecordRelatedListProps.aria`

Property	Type	Required	Description
ariaLabel	`string \| Record<string, string>`	optional	Accessible label for screen readers (WAI-ARIA aria-label). Plain string, or an inline locale map — no translation-bundle slot addresses this key, so a plain string is announced in the source language.
ariaDescribedBy	`string`	optional	ID of element providing additional description (WAI-ARIA aria-describedby)
role	`string`	optional	WAI-ARIA role attribute (e.g., "dialog", "navigation", "alert")

ReferenceRailEntry

Properties

Property	Type	Required	Description
objectName	`string`	✅	Related object name whose records this card summarizes (e.g. "task", "opportunity_quote")
relationshipField	`string`	✅	Field on the related object that points back to this record (e.g. "account_id")
title	`string`	optional	Literal card title. Rendered as-is in EVERY locale (no inline locale map — the rail renders it as a raw React child); omit to use the related object's localized label.
limit	`integer`	optional	Preview rows per card, and the `$top` of the one query this entry issues (renderer default: 3).
displayField	`string`	optional	Field of the related record rendered in each preview row (renderer fallback when omitted: name / title / subject / label / … / id).

Component

On this page