Skip to content

view.mdx

Latest commit

 

History

History
866 lines (618 loc) · 50.1 KB

view.mdx

File metadata and controls

866 lines (618 loc) · 50.1 KB
Raw
title View
description View protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

HTTP Method Enum & HTTP Request Schema

Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.

**Source:** `packages/spec/src/ui/view.zod.ts`

TypeScript Usage

import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormButtonConfig, FormField, FormSection, FormView, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, ListView, NavigationConfig, NavigationMode, ObjectListView, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, View, ViewData, ViewFilterRule, ViewItem, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormButtonConfig, FormField, FormSection, FormView, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, ListView, NavigationConfig, NavigationMode, ObjectListView, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, View, ViewData, ViewFilterRule, ViewItem, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';

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

AddRecordConfig

Add record entry point configuration

Properties

Property Type Required Description
enabled boolean ✅ Show the add record entry point
position Enum<'top' | 'bottom' | 'both'> ✅ Position of the add record button
mode Enum<'inline' | 'form' | 'modal'> ✅ How to add a new record
formView string optional Named form view to use when mode is "form" or "modal"

AppearanceConfig

Appearance and visualization configuration

Properties

Property Type Required Description
showDescription boolean ✅ Show the view description text
allowedVisualizations Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>[] optional Whitelist of visualization types users can switch between (e.g. ["grid", "gallery", "kanban"])

CalendarConfig

Properties

Property Type Required Description
startDateField string ✅ Field providing the event start date/time
endDateField string optional Field providing the event end date/time (defaults to a single-day event)
titleField string ✅ Field displayed as the event title
colorField string optional Field whose value determines the event color

ColumnSummary

Aggregation function for column footer summary

Allowed Values

  • none
  • count
  • count_empty
  • count_filled
  • count_unique
  • percent_empty
  • percent_filled
  • sum
  • avg
  • min
  • max

FormButtonConfig

Properties

Property Type Required Description
show boolean optional Whether the button is rendered (renderer default applies when omitted)
label string optional Button label (i18n-capable; renderer default when omitted)

FormField

Properties

Property Type Required Description
field string ✅ Field name (snake_case)
type Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'time' | 'boolean' | 'toggle' | 'select' | 'multiselect' | 'radio' | 'checkboxes' | 'lookup' | 'master_detail' | 'tree' | 'user' | 'image' | 'file' | 'avatar' | 'video' | 'audio' | 'formula' | 'summary' | 'autonumber' | 'composite' | 'repeater' | 'record' | 'location' | 'address' | 'code' | 'json' | 'color' | 'rating' | 'slider' | 'signature' | 'qrcode' | 'progress' | 'tags' | 'vector'> optional Field type (auto-infers widget if omitted)
options { label: string; value: string; color?: string; default?: boolean; … }[] optional Options for select/multiselect/radio/checkboxes fields
reference string optional Target object name for lookup/master_detail fields
maxLength number optional Maximum character length (for text/textarea/email/url/phone)
minLength number optional Minimum character length
min number optional Minimum value (for number/currency/percent/slider)
max number optional Maximum value
precision number optional Total digits (for number/currency)
scale number optional Decimal places
multiple boolean optional Allow multiple values (for select/lookup/file/image)
label string optional Display label override
placeholder string optional Placeholder text
helpText string optional Help/hint text
readonly boolean optional Read-only override
immutable boolean optional Editable on create, locked once the record exists (e.g. machine names).
required boolean optional Required override
hidden boolean optional Hidden override
colSpan integer optional [legacy — prefer span] Absolute column span (1-4). Fragile when the column count is derived per surface (mobile 1 / modal 2 / page 3-4): a fixed span only lines up at the width the author imagined. The renderer clamps it to the current column count. Prefer span.
span Enum<'auto' | 'full'> optional Relative field width. 'auto' (default — omit it): the renderer sizes the field from its widget type × the current column count (wide widgets like textarea/richtext/json/file/subform take the whole row). 'full': whole row at any column count. Prefer this over the absolute colSpan.
widget string optional Custom widget/component name (overrides type-based inference)
language string optional Code editor language (for type=code)
fields [FormField](#formfield)[] optional Sub-fields for composite/repeater/record types
keyField { field?: string; label?: string; placeholder?: string; helpText?: string; … } optional Key column config for record-typed fields
dependsOn string optional Parent field name for cascading
visibleWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL) — field shown only when TRUE. Root: record+current_user (runtime forms) or data (metadata forms). e.g. Precord.priority == 'urgent'
visibleOn string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional [DEPRECATED → visibleWhen] Visibility predicate (CEL). Normalized to visibleWhen at parse.
disclosure Enum<'inline' | 'popover'> optional Composite rendering: inline bordered box (default) or a summary line + gear popover (progressive disclosure).

FormSection

Properties

Property Type Required Description
name string optional Stable section identifier for i18n lookup (snake_case)
label string optional Display label (plain string; i18n keys are auto-generated by the framework)
description string optional Optional description rendered under the section header.
collapsible boolean optional
collapsed boolean optional
visibleWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL) — section shown only when TRUE. Root: record+current_user (runtime forms) or data (metadata forms).
visibleOn string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional [DEPRECATED → visibleWhen] Visibility predicate (CEL). Hides the whole section when false. Normalized to visibleWhen at parse.
columns Enum<'1' | '2' | '3' | '4'> | '1' | '2' | '3' | '4' optional
fields string | { field: string; type?: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'time' | 'boolean' | 'toggle' | 'select' | 'multiselect' | 'radio' | 'checkboxes' | 'lookup' | 'master_detail' | 'tree' | 'user' | 'image' | 'file' | 'avatar' | 'video' | 'audio' | 'formula' | 'summary' | 'autonumber' | 'composite' | 'repeater' | 'record' | 'location' | 'address' | 'code' | 'json' | 'color' | 'rating' | 'slider' | 'signature' | 'qrcode' | 'progress' | 'tags' | 'vector'>; options?: { label: string; value: string; color?: string; default?: boolean; … }[]; reference?: string; … }[] ✅

FormView

Properties

Property Type Required Description
type Enum<'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal'> optional
layout Enum<'vertical' | 'horizontal' | 'inline' | 'grid'> optional Field layout direction
columns integer optional Number of columns for the form body
title string optional Form title
description string optional Form description
defaultTab string optional Initially active tab (tabbed forms)
tabPosition Enum<'top' | 'bottom' | 'left' | 'right'> optional Tab strip position (tabbed forms)
allowSkip boolean optional Allow skipping steps (wizard forms)
showStepIndicator boolean optional Show the step indicator (wizard forms)
splitDirection Enum<'horizontal' | 'vertical'> optional Split orientation (split forms)
splitSize number optional Primary split panel size, % (split forms)
splitResizable boolean optional Whether the split is resizable (split forms)
drawerSide Enum<'top' | 'bottom' | 'left' | 'right'> optional Drawer side (drawer forms)
drawerWidth string optional [DEPRECATED → size buckets] Drawer width, e.g. "480px". A pixel width cannot be chosen without knowing the client viewport — the renderer derives it.
modalSize Enum<'sm' | 'default' | 'lg' | 'xl' | 'full'> optional Modal size (modal forms)
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 configuration (defaults to "object" provider)
sections { name?: string; label?: string; description?: string; collapsible?: boolean; … }[] optional
groups { name?: string; label?: string; description?: string; collapsible?: boolean; … }[] optional
subforms { childObject: string; relationshipField?: string; columns?: any[]; amountField?: string; … }[] optional Inline master-detail child collections
defaultSort { field: string; order?: Enum<'asc' | 'desc'> }[] optional Default sort order for related list views within this form
sharing { enabled?: boolean; publicLink?: string; password?: string; allowedDomains?: string[]; … } optional Public sharing configuration for this form
submitBehavior { kind: 'thank-you'; title?: string; message?: string } | { kind: 'redirect'; url: string; delayMs?: integer } | { kind: 'continue' } | { kind: 'next-record' } optional Post-submit behavior
buttons { submit?: object; cancel?: object; reset?: object } optional [EXPERIMENTAL — NOT ENFORCED, #2998] Form action-button visibility & labels. Renderer wiring pending in ObjectUI (objectui#2545).
defaults Record<string, any> optional [EXPERIMENTAL — NOT ENFORCED, #2998] Initial field values for create-mode forms (spec home for ObjectUI initialValues). Renderer wiring pending (objectui#2545).
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes for the form view

GalleryConfig

Gallery/card view configuration

Properties

Property Type Required Description
coverField string optional Attachment/image field to display as card cover
coverFit Enum<'cover' | 'contain'> ✅ Image fit mode for card cover
cardSize Enum<'small' | 'medium' | 'large'> ✅ Card size in gallery view
titleField string optional Field to display as card title
visibleFields string[] optional Fields to display on card body

GanttConfig

Properties

Property Type Required Description
startDateField string ✅ Field providing the task start date
endDateField string ✅ Field providing the task end date
titleField string ✅ Field displayed as the task title
progressField string optional Field providing the task completion percentage
dependenciesField string optional Field listing the task's predecessor (dependency) record ids
colorField string optional Field that drives the bar color
parentField string optional Field holding the parent task id (builds the summary → step tree)
typeField string optional Field whose value maps to task/summary/milestone
baselineStartField string optional Baseline (planned) start field
baselineEndField string optional Baseline (planned) end field
groupByField string optional Field to group leaf tasks by (synthesized summary rows)
resourceView boolean optional Render a per-resource workload histogram instead of the timeline
assigneeField string optional Resource field to bucket load by (resource view)
effortField string optional Per-task load units (resource view; default 1)
capacity number optional Per-resource capacity ceiling; loads above this flag overload
tooltipFields string | { field: string; label?: string }[] optional Fields to surface in the hover tooltip, in display order
quickFilters { field: string; label?: string; options?: string | { value: string | number; label?: string }[] }[] optional Multi-select filter dropdowns rendered above the chart
autoZoomToFilter boolean optional When true (default), filtering zooms the range to the filtered tasks

GanttQuickFilter

Properties

Property Type Required Description
field string ✅ Record field / dot-path the dimension filters on
label string optional Trigger label (falls back to the field label)
options string | { value: string | number; label?: string }[] optional Explicit option override for fixed enums

GroupingConfig

Record grouping configuration

Properties

Property Type Required Description
fields { field: string; order: Enum<'asc' | 'desc'>; collapsed: boolean }[] ✅ Fields to group by (supports up to 3 levels)

GroupingField

Properties

Property Type Required Description
field string ✅ Field name to group by
order Enum<'asc' | 'desc'> ✅ Group sort order
collapsed boolean ✅ Collapse groups by default

KanbanConfig

Properties

Property Type Required Description
groupByField string ✅ Field to group columns by (usually status/select)
summarizeField string optional Field to sum at top of column (e.g. amount)
columns string[] ✅ Fields to show on cards

ListChartConfig

List chart view configuration

Properties

Property Type Required Description
chartType Enum<'bar' | 'line' | 'pie' | 'area' | 'scatter'> ✅ Chart visualisation type
dataset string ✅ Dataset name to bind (ADR-0021)
dimensions string[] optional Dimension names — X/group/split
values string[] ✅ Measure names — Y (at least one)

ListColumn

Properties

Property Type Required Description
field string ✅ Field name (snake_case)
label string optional Display label override
width number optional Column width in pixels
align Enum<'left' | 'center' | 'right'> optional Text alignment
hidden boolean optional Hide column by default
sortable boolean optional Allow sorting by this column
resizable boolean optional Allow resizing this column
wrap boolean optional Allow text wrapping
type string optional Renderer type override (e.g., "currency", "date")
pinned Enum<'left' | 'right'> optional Pin/freeze column to left or right side
summary Enum<'none' | 'count' | 'count_empty' | 'count_filled' | 'count_unique' | 'percent_empty' | 'percent_filled' | 'sum' | 'avg' | 'min' | 'max'> optional Footer aggregation function for this column
link boolean optional Functions as the primary navigation link (triggers View navigation)
action string optional Registered Action ID to execute when clicked

ListView

Properties

Property Type Required Description
name string optional Internal view name (lowercase snake_case)
label string optional Display label (plain string; i18n keys are auto-generated by the framework)
type Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'> optional
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 configuration (defaults to "object" provider)
columns string[] | { field: string; label?: string; width?: number; align?: Enum<'left' | 'center' | 'right'>; … }[] ✅ Fields to display as columns
filter { field: string; operator?: Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal' | 'in' | 'not_in' | 'is_empty' | 'is_not_empty' | 'is_null' | 'is_not_null' | 'before' | 'after' | 'between'>; value?: string | number | boolean | null | string | number[] }[] optional Filter criteria (JSON Rules)
sort string | { field: string; order: Enum<'asc' | 'desc'> }[] optional
searchableFields string[] optional Fields enabled for search
filterableFields string[] optional Legacy shorthand for userFilters.fields — bare field names enabled for end-user filtering. Prefer userFilters
userFilters { element?: Enum<'dropdown' | 'tabs' | 'toggle'>; fields?: { field: string; label?: string; type?: Enum<'select' | 'multi-select' | 'boolean' | 'date-range' | 'text'>; options?: { value: string | number | boolean; label: string; color?: string }[]; … }[]; tabs?: { name: string; label?: string; icon?: string; view?: string; … }[]; showAllRecords?: boolean } optional End-user quick-filter bar: dropdown/toggle fields or tab presets. Omit to let the renderer derive filters from select/boolean fields
resizable boolean optional Enable column resizing
striped boolean optional Striped row styling
bordered boolean optional Show borders
compactToolbar boolean optional Collapse Group/Color/Density/Hide-fields into a single View settings popover
selection { type?: Enum<'none' | 'single' | 'multiple'> } optional Row selection configuration
navigation { mode?: Enum<'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none'>; view?: string; preventNavigation?: boolean; openNewTab?: boolean; … } optional Configuration for item click navigation (page, drawer, modal, etc.)
pagination { pageSize?: integer; pageSizeOptions?: integer[] } optional Pagination configuration
kanban { groupByField: string; summarizeField?: string; columns: string[] } optional Kanban-board configuration — applies when the view renders as a kanban layout
calendar { startDateField: string; endDateField?: string; titleField: string; colorField?: string } optional Calendar configuration — applies when the view renders as a calendar layout
gantt Record<string, any> optional Gantt-timeline configuration — applies when the view renders as a gantt layout
gallery { coverField?: string; coverFit?: Enum<'cover' | 'contain'>; cardSize?: Enum<'small' | 'medium' | 'large'>; titleField?: string; … } optional Gallery/card view configuration
timeline { startDateField: string; endDateField?: string; titleField: string; groupByField?: string; … } optional Timeline view configuration
chart { chartType?: Enum<'bar' | 'line' | 'pie' | 'area' | 'scatter'>; dataset: string; dimensions?: string[]; values: string[] } optional List chart view configuration
tree Record<string, any> optional Tree/hierarchy configuration — applies when the view renders as a tree layout
description string optional View description for documentation/tooltips
sharing { type?: Enum<'personal' | 'collaborative'>; lockedBy?: string } optional View sharing and access configuration
rowHeight Enum<'compact' | 'short' | 'medium' | 'tall' | 'extra_tall'> optional Row height / density setting
grouping { fields: { field: string; order?: Enum<'asc' | 'desc'>; collapsed?: boolean }[] } optional Group records by one or more fields
rowColor { field: string; colors?: Record<string, string> } optional Color rows based on field value
hiddenFields string[] optional Fields to hide in this specific view
fieldOrder string[] optional Explicit field display order for this view
rowActions string[] optional Actions available for individual row items
bulkActions string[] optional Actions available when multiple rows are selected
bulkActionDefs Record<string, any>[] optional Rich bulk action definitions (schema-driven, executed via BulkActionDialog)
virtualScroll boolean optional Enable virtual scrolling for large datasets
conditionalFormatting { condition: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; style: Record<string, string> }[] optional Conditional formatting rules for list rows
inlineEdit boolean optional Allow inline editing of records directly in the list view
exportOptions Enum<'csv' | 'xlsx' | 'pdf' | 'json'>[] optional Available export format options
userActions { sort?: boolean; search?: boolean; filter?: boolean; refresh?: boolean; … } optional User action toggles for the view toolbar
appearance { showDescription?: boolean; allowedVisualizations?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>[] } optional Appearance and visualization configuration
tabs { name: string; label?: string; icon?: string; view?: string; … }[] optional Tab definitions for multi-tab view interface
addRecord { enabled?: boolean; position?: Enum<'top' | 'bottom' | 'both'>; mode?: Enum<'inline' | 'form' | 'modal'>; formView?: string } optional Add record entry point configuration
showRecordCount boolean optional Show record count at the bottom of the list
allowPrinting boolean optional Allow users to print the view
emptyState { title?: string; message?: string; icon?: string } optional Empty state configuration when no records found
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes for the list view
responsive { breakpoint?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>; hiddenOn?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>[]; columns?: object; order?: object } optional Responsive layout configuration
performance { lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' | 'cache-first' | 'network-first' | 'stale-while-revalidate'>; prefetch?: boolean; … } optional Performance optimization settings

NavigationConfig

Properties

Property Type Required Description
mode Enum<'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none'> ✅
view string optional Name of the form view to use for details (e.g. "summary_view", "edit_form")
preventNavigation boolean ✅ Disable standard navigation entirely
openNewTab boolean ✅ Force open in new tab (applies to page mode)
size Enum<'auto' | 'sm' | 'md' | 'lg' | 'xl' | 'full'> ✅ [#2578] Overlay size bucket for drawer/modal detail: 'auto' (default — renderer derives from field count + viewport; AI writes nothing) or a coarse override sm/md/lg/xl/full. Prefer this over the pixel width; page mode ignores it.
width string | number optional [DEPRECATED → size] Pixel/percent width of the drawer/modal (e.g. "600px"). A pixel width cannot be chosen at authoring time without knowing the client viewport — use the size bucket.

NavigationMode

Allowed Values

  • page
  • drawer
  • modal
  • split
  • popover
  • new_window
  • none

ObjectListView

Properties

Property Type Required Description
name string optional Internal view name (lowercase snake_case)
label string optional Display label (plain string; i18n keys are auto-generated by the framework)
type Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'> optional
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 configuration (defaults to "object" provider)
columns string[] | { field: string; label?: string; width?: number; align?: Enum<'left' | 'center' | 'right'>; … }[] ✅ Fields to display as columns
filter { field: string; operator?: Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal' | 'in' | 'not_in' | 'is_empty' | 'is_not_empty' | 'is_null' | 'is_not_null' | 'before' | 'after' | 'between'>; value?: string | number | boolean | null | string | number[] }[] optional Filter criteria (JSON Rules)
sort string | { field: string; order: Enum<'asc' | 'desc'> }[] optional
searchableFields string[] optional Fields enabled for search
filterableFields string[] optional Legacy shorthand for userFilters.fields — bare field names enabled for end-user filtering. Prefer userFilters
resizable boolean optional Enable column resizing
striped boolean optional Striped row styling
bordered boolean optional Show borders
compactToolbar boolean optional Collapse Group/Color/Density/Hide-fields into a single View settings popover
selection { type?: Enum<'none' | 'single' | 'multiple'> } optional Row selection configuration
navigation { mode?: Enum<'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none'>; view?: string; preventNavigation?: boolean; openNewTab?: boolean; … } optional Configuration for item click navigation (page, drawer, modal, etc.)
pagination { pageSize?: integer; pageSizeOptions?: integer[] } optional Pagination configuration
kanban { groupByField: string; summarizeField?: string; columns: string[] } optional Kanban-board configuration — applies when the view renders as a kanban layout
calendar { startDateField: string; endDateField?: string; titleField: string; colorField?: string } optional Calendar configuration — applies when the view renders as a calendar layout
gantt Record<string, any> optional Gantt-timeline configuration — applies when the view renders as a gantt layout
gallery { coverField?: string; coverFit?: Enum<'cover' | 'contain'>; cardSize?: Enum<'small' | 'medium' | 'large'>; titleField?: string; … } optional Gallery/card view configuration
timeline { startDateField: string; endDateField?: string; titleField: string; groupByField?: string; … } optional Timeline view configuration
chart { chartType?: Enum<'bar' | 'line' | 'pie' | 'area' | 'scatter'>; dataset: string; dimensions?: string[]; values: string[] } optional List chart view configuration
tree Record<string, any> optional Tree/hierarchy configuration — applies when the view renders as a tree layout
description string optional View description for documentation/tooltips
sharing { type?: Enum<'personal' | 'collaborative'>; lockedBy?: string } optional View sharing and access configuration
rowHeight Enum<'compact' | 'short' | 'medium' | 'tall' | 'extra_tall'> optional Row height / density setting
grouping { fields: { field: string; order?: Enum<'asc' | 'desc'>; collapsed?: boolean }[] } optional Group records by one or more fields
rowColor { field: string; colors?: Record<string, string> } optional Color rows based on field value
hiddenFields string[] optional Fields to hide in this specific view
fieldOrder string[] optional Explicit field display order for this view
rowActions string[] optional Actions available for individual row items
bulkActions string[] optional Actions available when multiple rows are selected
bulkActionDefs Record<string, any>[] optional Rich bulk action definitions (schema-driven, executed via BulkActionDialog)
virtualScroll boolean optional Enable virtual scrolling for large datasets
conditionalFormatting { condition: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; style: Record<string, string> }[] optional Conditional formatting rules for list rows
inlineEdit boolean optional Allow inline editing of records directly in the list view
exportOptions Enum<'csv' | 'xlsx' | 'pdf' | 'json'>[] optional Available export format options
userActions { sort?: boolean; search?: boolean; filter?: boolean; refresh?: boolean; … } optional User action toggles for the view toolbar
appearance { showDescription?: boolean; allowedVisualizations?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>[] } optional Appearance and visualization configuration
tabs { name: string; label?: string; icon?: string; view?: string; … }[] optional Tab definitions for multi-tab view interface
addRecord { enabled?: boolean; position?: Enum<'top' | 'bottom' | 'both'>; mode?: Enum<'inline' | 'form' | 'modal'>; formView?: string } optional Add record entry point configuration
showRecordCount boolean optional Show record count at the bottom of the list
allowPrinting boolean optional Allow users to print the view
emptyState { title?: string; message?: string; icon?: string } optional Empty state configuration when no records found
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes for the list view
responsive { breakpoint?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>; hiddenOn?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>[]; columns?: object; order?: object } optional Responsive layout configuration
performance { lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' | 'cache-first' | 'network-first' | 'stale-while-revalidate'>; prefetch?: boolean; … } optional Performance optimization settings
userFilters { element?: Enum<'dropdown' | 'toggle'>; fields?: { field: string; label?: string; type?: Enum<'select' | 'multi-select' | 'boolean' | 'date-range' | 'text'>; options?: { value: string | number | boolean; label: string; color?: string }[]; … }[] } optional

ObjectUserFilters

Properties

Property Type Required Description
element Enum<'dropdown' | 'toggle'> ✅ Filter control style on object views: "dropdown" (per-field value chips). "toggle" is deprecated. "tabs" is page-only — use listViews for named presets.
fields { field: string; label?: string; type?: Enum<'select' | 'multi-select' | 'boolean' | 'date-range' | 'text'>; options?: { value: string | number | boolean; label: string; color?: string }[]; … }[] optional Fields exposed as quick filters (dropdown/toggle elements)

PaginationConfig

Properties

Property Type Required Description
pageSize integer ✅ Number of records per page
pageSizeOptions integer[] optional Available page size options

RowColorConfig

Row color configuration based on field values

Properties

Property Type Required Description
field string ✅ Field to derive color from (typically a select/status field)
colors Record<string, string> optional Map of field value to color (hex/token)

RowHeight

Row height / density setting for list view

Allowed Values

  • compact
  • short
  • medium
  • tall
  • extra_tall

SelectionConfig

Properties

Property Type Required Description
type Enum<'none' | 'single' | 'multiple'> ✅ Selection mode

TimelineConfig

Timeline view configuration

Properties

Property Type Required Description
startDateField string ✅ Field for timeline item start date
endDateField string optional Field for timeline item end date
titleField string ✅ Field to display as timeline item title
groupByField string optional Field to group timeline rows
colorField string optional Field to determine item color
scale Enum<'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'> ✅ Default timeline scale

TreeConfig

Properties

Property Type Required Description
parentField string optional Single-parent pointer field (auto-detected from the object schema when omitted)
labelField string optional Field rendered indented in the first column (defaults to "name")
fields string[] optional Additional fields rendered as flat columns alongside the label
defaultExpandedDepth integer optional Initial expansion depth (0 = roots only; omit = expand all)

UserActionsConfig

User action toggles for the view toolbar

Properties

Property Type Required Description
sort boolean ✅ Allow users to sort records
search boolean ✅ Allow users to search records
filter boolean ✅ Allow users to filter records
refresh boolean ✅ Allow users to reload the view data from the backend without a full page reload
rowHeight boolean ✅ Allow users to toggle row height/density
addRecordForm boolean ✅ Add records through a form instead of inline
editInline boolean ✅ Allow users to edit records inline — click a cell to edit it with the field's type-aware widget (the same control the form uses). Off by default: the list is read-only unless the author opts in.
buttons string[] optional Custom action button IDs to show in the toolbar

UserFilterField

Quick-filter field configuration

Properties

Property Type Required Description
field string ✅ Field name on the source object (must exist — checked by reference diagnostics)
label string optional Display label override (defaults to the field label)
type Enum<'select' | 'multi-select' | 'boolean' | 'date-range' | 'text'> optional Filter control type. Omit to infer from the field definition
options { value: string | number | boolean; label: string; color?: string }[] optional Static options. Omit to derive from the field definition (select options / lookup records)
showCount boolean optional Show per-option record counts
defaultValues string | number | boolean[] optional Pre-selected values when the view loads

UserFilters

End-user quick-filter configuration (Airtable "User filters" parity)

Properties

Property Type Required Description
element Enum<'dropdown' | 'tabs' | 'toggle'> ✅ Filter control style: "dropdown" (per-field value selectors) or "tabs" (named presets). "toggle" is deprecated.
fields { field: string; label?: string; type?: Enum<'select' | 'multi-select' | 'boolean' | 'date-range' | 'text'>; options?: { value: string | number | boolean; label: string; color?: string }[]; … }[] optional Fields exposed as quick filters (dropdown/toggle elements)
tabs { name: string; label?: string; icon?: string; view?: string; … }[] optional Named filter presets rendered as tabs (tabs element). Reuses ViewTabSchema
showAllRecords boolean optional Show an "All records" tab before the presets (tabs element)

View

Properties

Property Type Required Description
list { name?: string; label?: string; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>; data?: { provider: 'object'; object: string } | { provider: 'api'; read?: object; write?: object } | { provider: 'value'; items: any[] } | { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … } optional
form { type?: Enum<'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal'>; layout?: Enum<'vertical' | 'horizontal' | 'inline' | 'grid'>; columns?: integer; title?: string; … } optional
listViews Record<string, { name?: string; label?: string; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>; data?: { provider: 'object'; object: string } | { provider: 'api'; read?: object; write?: object } | { provider: 'value'; items: any[] } | { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }> optional Additional named list views (views mode — dropdown userFilters allowed, no tabs; ADR-0047)
formViews Record<string, { type?: Enum<'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal'>; layout?: Enum<'vertical' | 'horizontal' | 'inline' | 'grid'>; columns?: integer; title?: string; … }> optional Additional named form views
protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } optional Package author protection block — lock policy for this view.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

ViewData

Union Options

This schema accepts one of the following structures:

Option 1

Properties

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

Option 2

Properties

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)

Option 3

Properties

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

Option 4

Properties

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.

ViewFilterRule

View filter rule

Properties

Property Type Required Description
field string ✅ Field name to filter on
operator Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal' | 'in' | 'not_in' | 'is_empty' | 'is_not_empty' | 'is_null' | 'is_not_null' | 'before' | 'after' | 'between'> ✅ Filter operator
value string | number | boolean | null | string | number[] optional Filter value

ViewItem

Union Options

This schema accepts one of the following structures:

Option 1

Properties

Property Type Required Description
viewKind 'list' ✅
config { name?: string; label?: string; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>; data?: { provider: 'object'; object: string } | { provider: 'api'; read?: object; write?: object } | { provider: 'value'; items: any[] } | { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … } ✅ List-family view configuration.
name string ✅ Globally-unique view id, <object>.<viewKey>.
object string ✅ Bound object name — the foreign key used to aggregate views.
label string optional Display label (supports i18n).
isDefault boolean optional Whether this is the object's default view in the switcher.
order integer optional Sort order within the object's view switcher / left rail.
scope Enum<'package' | 'shared' | 'personal'> optional Identity layer (defaults to package for source-loaded views).
owner string optional Owner user id — set when scope is personal.
hidden boolean optional Hidden from the switcher (per-user / per-org declutter).
protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } optional Package author protection block — lock policy for this view.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

Option 2

Properties

Property Type Required Description
viewKind 'form' ✅
config { type?: Enum<'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal'>; layout?: Enum<'vertical' | 'horizontal' | 'inline' | 'grid'>; columns?: integer; title?: string; … } ✅ Form view configuration.
name string ✅ Globally-unique view id, <object>.<viewKey>.
object string ✅ Bound object name — the foreign key used to aggregate views.
label string optional Display label (supports i18n).
isDefault boolean optional Whether this is the object's default view in the switcher.
order integer optional Sort order within the object's view switcher / left rail.
scope Enum<'package' | 'shared' | 'personal'> optional Identity layer (defaults to package for source-loaded views).
owner string optional Owner user id — set when scope is personal.
hidden boolean optional Hidden from the switcher (per-user / per-org declutter).
protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } optional Package author protection block — lock policy for this view.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

ViewKind

Whether config is a ListView (list family) or a FormView.

Allowed Values

  • list
  • form

ViewScope

View identity layer: package | shared | personal.

Allowed Values

  • package
  • shared
  • personal

ViewSharing

View sharing and access configuration

Properties

Property Type Required Description
type Enum<'personal' | 'collaborative'> ✅ View ownership type
lockedBy string optional User who locked the view configuration

ViewTab

Tab configuration for multi-tab view interface

Properties

Property Type Required Description
name string ✅ Tab identifier (snake_case)
label string optional Display label
icon string optional Tab icon name
view string optional Referenced list view name from listViews
filter { field: string; operator: Enum<'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'greater_than' | 'less_than' | 'greater_than_or_equal' | 'less_than_or_equal' | 'in' | 'not_in' | 'is_empty' | 'is_not_empty' | 'is_null' | 'is_not_null' | 'before' | 'after' | 'between'>; value?: string | number | boolean | null | string | number[] }[] optional Tab-specific filter criteria
order integer optional Tab display order
pinned boolean ✅ Pin tab (cannot be removed by users)
isDefault boolean ✅ Set as the default active tab
visible boolean ✅ Tab visibility

VisualizationType

Visualization type that users can switch to

Allowed Values

  • grid
  • kanban
  • gallery
  • calendar
  • timeline
  • gantt
  • map
  • chart
  • tree