react-blocks.contract.json

{
  "version": 2,
  "adr": "ADR-0081",
  "source": "GENERATED from the REACT_BLOCKS definition in the '@objectstack/spec/ui' module — data props from the spec zod schemas, binding/controlled/callback from the React overlay.",
  "note": "Props each component accepts in kind:'react' page source. Reference blocks by their PascalCase tag. kind: data=declarative config (from the spec schema) · binding=connects to data · controlled=React state · callback=React function. These blocks are for DATA. Live data: const adapter = useAdapter(); adapter.find/findOne/create/update. STYLING (ADR-0065) — a page's source is runtime metadata, so the console's build-time Tailwind NEVER scans it: utility classNAMES silently produce no CSS. Do NOT use Tailwind className in page source. (a) Layout/chrome: inline style={} with hsl(var(--token)) theme colors — e.g. color:'hsl(var(--foreground))', background:'hsl(var(--card))', border:'1px solid hsl(var(--border))', and px/flex for layout. (b) Overlays: render <ObjectForm formType='drawer'|'modal' open onOpenChange> (a pre-styled Sheet/Dialog) — never hand-roll a fixed inset-0 backdrop.",
  "blocks": [
    {
      "tag": "ObjectForm",
      "schemaType": "object-form",
      "summary": "Server-connected create/edit/view form for one object. Config props come from the spec FormView schema; bind + wire it with the React props below.",
      "specSchema": true,
      "props": [
        {
          "name": "objectName",
          "type": "string",
          "kind": "binding",
          "required": true,
          "description": "The object this block binds to (server-connected)."
        },
        {
          "name": "formType",
          "type": "'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal'",
          "kind": "binding",
          "required": false,
          "description": "Form presentation; drawer/modal render the form in a built-in overlay (use drawerSide/drawerWidth/modalSize)."
        },
        {
          "name": "fields",
          "type": "string[]",
          "kind": "binding",
          "required": false,
          "description": "Limit/order the fields shown (defaults to the object form fields)."
        },
        {
          "name": "initialValues",
          "type": "Record<string, any>",
          "kind": "binding",
          "required": false,
          "description": "Prefill values in create mode."
        },
        {
          "name": "mode",
          "type": "'create' | 'edit' | 'view'",
          "kind": "controlled",
          "required": false,
          "description": "Create a new record, or edit/view an existing one — drive from React state."
        },
        {
          "name": "recordId",
          "type": "string | number",
          "kind": "controlled",
          "required": false,
          "description": "Which record to load (edit/view). The hook for master/detail."
        },
        {
          "name": "onSuccess",
          "type": "(record) => void",
          "kind": "callback",
          "required": false,
          "description": "Called after a successful save with the saved record (e.g. close a panel + reload)."
        },
        {
          "name": "onError",
          "type": "(error: Error) => void",
          "kind": "callback",
          "required": false,
          "description": "Called when the save fails."
        },
        {
          "name": "onCancel",
          "type": "() => void",
          "kind": "callback",
          "required": false,
          "description": "Called when the user cancels."
        },
        {
          "name": "submitHandler",
          "type": "(values) => any | Promise<any>",
          "kind": "callback",
          "required": false,
          "description": "Custom persistence instead of the default create/update."
        },
        {
          "name": "layout",
          "type": "'vertical' | 'horizontal' | 'inline' | 'grid'",
          "kind": "data",
          "required": false,
          "description": "Field layout direction"
        },
        {
          "name": "columns",
          "type": "integer",
          "kind": "data",
          "required": false,
          "description": "Number of columns for the form body"
        },
        {
          "name": "tabPosition",
          "type": "'top' | 'bottom' | 'left' | 'right'",
          "kind": "data",
          "required": false,
          "description": "Tab strip position (tabbed forms)"
        },
        {
          "name": "drawerSide",
          "type": "'top' | 'bottom' | 'left' | 'right'",
          "kind": "data",
          "required": false,
          "description": "Drawer side (drawer forms)"
        },
        {
          "name": "drawerWidth",
          "type": "string",
          "kind": "data",
          "required": false,
          "description": "[DEPRECATED → size buckets] Drawer width, e.g. \"480px\". A pixel width cannot be chosen without knowing the client viewport — the renderer derives it."
        },
        {
          "name": "modalSize",
          "type": "'sm' | 'default' | 'lg' | 'xl' | 'full'",
          "kind": "data",
          "required": false,
          "description": "Modal size (modal forms)"
        },
        {
          "name": "splitDirection",
          "type": "'horizontal' | 'vertical'",
          "kind": "data",
          "required": false,
          "description": "Split orientation (split forms)"
        },
        {
          "name": "sections",
          "type": "any[]",
          "kind": "data",
          "required": false,
          "description": ""
        },
        {
          "name": "subforms",
          "type": "object[]",
          "kind": "data",
          "required": false,
          "description": "Inline master-detail child collections"
        },
        {
          "name": "submitBehavior",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "Post-submit behavior"
        }
      ]
    },
    {
      "tag": "ListView",
      "schemaType": "list-view",
      "summary": "Server-connected object table with toolbar and switchable visualizations (grid/kanban/calendar/gantt/…). Config props come from the spec ListView schema.",
      "specSchema": true,
      "props": [
        {
          "name": "objectName",
          "type": "string",
          "kind": "binding",
          "required": true,
          "description": "The object this block binds to (server-connected)."
        },
        {
          "name": "viewType",
          "type": "'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map'",
          "kind": "binding",
          "required": false,
          "description": "Which visualization to render (default grid). How you get a kanban/calendar/gantt of the object."
        },
        {
          "name": "navigation",
          "type": "{ mode: 'page' | 'drawer' | 'modal' | 'split' | 'none' }",
          "kind": "binding",
          "required": false,
          "description": "What a row click does. Use { mode: \"none\" } when you handle clicks via onRowClick."
        },
        {
          "name": "fields",
          "type": "string[]",
          "kind": "binding",
          "required": false,
          "description": "Limit/order the columns shown (defaults to the object list fields)."
        },
        {
          "name": "options",
          "type": "Record<string, any>",
          "kind": "binding",
          "required": false,
          "description": "View-type-specific options bag (kanban/calendar/gantt extras); prefer the typed spec props where they exist."
        },
        {
          "name": "filters",
          "type": "FilterArray e.g. ['status','=','active']",
          "kind": "controlled",
          "required": false,
          "description": "ObjectQL base filter; drive from React state for tabbed/searched lists. ([field, op, value]; ops =, !=, >, <, contains, in; compound: [\"and\", […], […]])."
        },
        {
          "name": "onRowClick",
          "type": "(record) => void",
          "kind": "callback",
          "required": false,
          "description": "Called with the clicked row's record — the hook for master/detail."
        },
        {
          "name": "onNavigate",
          "type": "(recordId, action: 'view' | 'edit') => void",
          "kind": "callback",
          "required": false,
          "description": "Called for page-level navigation."
        },
        {
          "name": "columns",
          "type": "string[] | object[]",
          "kind": "data",
          "required": true,
          "description": "Fields to display as columns"
        },
        {
          "name": "sort",
          "type": "string | object[]",
          "kind": "data",
          "required": false,
          "description": ""
        },
        {
          "name": "searchableFields",
          "type": "string[]",
          "kind": "data",
          "required": false,
          "description": "Fields enabled for search"
        },
        {
          "name": "userFilters",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "End-user quick-filter bar: dropdown/toggle fields or tab presets. Omit to let the renderer derive filters from select/boolean fields"
        },
        {
          "name": "pagination",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "Pagination configuration"
        },
        {
          "name": "grouping",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "Group records by one or more fields"
        },
        {
          "name": "rowHeight",
          "type": "'compact' | 'short' | 'medium' | 'tall' | 'extra_tall'",
          "kind": "data",
          "required": false,
          "description": "Row height / density setting"
        },
        {
          "name": "selection",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "Row selection configuration"
        },
        {
          "name": "rowActions",
          "type": "string[]",
          "kind": "data",
          "required": false,
          "description": "Actions available for individual row items"
        },
        {
          "name": "inlineEdit",
          "type": "boolean",
          "kind": "data",
          "required": false,
          "description": "Allow inline editing of records directly in the list view"
        }
      ]
    },
    {
      "tag": "ObjectChart",
      "schemaType": "object-chart",
      "summary": "Chart over an object’s aggregated data. Bind objectName + aggregate; the axes name the aggregate’s RESULT COLUMNS (see chartAggregateResultKeys).",
      "specSchema": true,
      "props": [
        {
          "name": "objectName",
          "type": "string",
          "kind": "binding",
          "required": true,
          "description": "The object this block binds to (server-connected)."
        },
        {
          "name": "aggregate",
          "type": "{ field?: string; function: 'count' | 'sum' | 'avg' | 'min' | 'max'; groupBy: string | { field: string; dateGranularity?: 'day' | 'week' | 'month' | 'quarter' | 'year' } }",
          "kind": "binding",
          "required": false,
          "description": "Aggregation run against objectName. Result rows are keyed by the RAW FIELD NAMES: one column named after groupBy (the category) and one named after field (the value; the literal \"count\" for a fieldless count). Bind xAxis.field / yAxis[].field / series[].name to those names."
        },
        {
          "name": "data",
          "type": "any[]",
          "kind": "binding",
          "required": false,
          "description": "Static/precomputed data to chart directly instead of binding via objectName + aggregate."
        },
        {
          "name": "filter",
          "type": "FilterArray",
          "kind": "controlled",
          "required": false,
          "description": "ObjectQL filter scoping the data; drive from React state."
        },
        {
          "name": "type",
          "type": "'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'combo' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot'",
          "kind": "data",
          "required": true,
          "description": ""
        },
        {
          "name": "title",
          "type": "string",
          "kind": "data",
          "required": false,
          "description": "Chart title"
        },
        {
          "name": "subtitle",
          "type": "string",
          "kind": "data",
          "required": false,
          "description": "Chart subtitle"
        },
        {
          "name": "description",
          "type": "string",
          "kind": "data",
          "required": false,
          "description": "Accessibility description — announced to screen readers as the chart’s label"
        },
        {
          "name": "height",
          "type": "number",
          "kind": "data",
          "required": false,
          "description": "Fixed plot height in pixels (overrides the container default)"
        },
        {
          "name": "xAxis",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "X-Axis configuration"
        },
        {
          "name": "yAxis",
          "type": "object[]",
          "kind": "data",
          "required": false,
          "description": "Y-Axis configuration (support dual axis)"
        },
        {
          "name": "series",
          "type": "object[]",
          "kind": "data",
          "required": false,
          "description": "Defined series configuration"
        },
        {
          "name": "colors",
          "type": "string[] | object",
          "kind": "data",
          "required": false,
          "description": "Color palette (string[]) or value→color map ({ value: color })"
        },
        {
          "name": "showLegend",
          "type": "boolean",
          "kind": "data",
          "required": false,
          "description": "Display legend"
        },
        {
          "name": "showDataLabels",
          "type": "boolean",
          "kind": "data",
          "required": false,
          "description": "Display data labels"
        },
        {
          "name": "annotations",
          "type": "object[]",
          "kind": "data",
          "required": false,
          "description": "Reference lines/bands drawn over the plot: { type: \"line\" | \"region\", axis: \"x\" | \"y\", value, endValue?, color?, label?, style? }"
        },
        {
          "name": "interaction",
          "type": "object",
          "kind": "data",
          "required": false,
          "description": "Interaction toggles: { tooltips?, brush? }"
        }
      ]
    },
    {
      "tag": "Block",
      "schemaType": "(any)",
      "summary": "Escape hatch — render any registered component by type. <Block type=\"object-kanban\" objectName=\"task\" /> etc. Not a way back to the record:* family: those need a record page's record context and are rejected here too (#4413).",
      "specSchema": false,
      "props": [
        {
          "name": "type",
          "type": "string",
          "kind": "binding",
          "required": true,
          "description": "The registered component type to render."
        }
      ]
    }
  ]
}