Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Interface Designer Toolbox Controls

Learn through a task, then consult the exact property reference

Choose controls by the business interaction: capture an answer, arrange content, display admitted records, navigate, act deliberately, or explain process state. The current node reference is generated from the actual authorable contract, including property keys, help/options, defaults and events. The procedures below explain the current native surfaces and their capability boundaries; a catalog entry does not establish that every property/source combination executes.

Business need Start with Confirm before publishing
Employee answers Typed input control and explicit bind target Required/validation behavior and target type.
Page arrangement Layout container, direction and responsive settings Actual parent/child and opaque-leaf rules.
Record analysis Supported governed source plus native data-control adapter Shape, identity, paging/filter capability and current access.
Manager work Task list plus native TaskViewer Actual task participant/form/claim/receipt authority.
Progress explanation Bound tracking control Real admitted data rather than design-time sample seeds.

Controls inherit native server authorization. Disabling a business-state option with a reason differs from rendering a permission-denied action. The four cases below are written procedures, not executed browser evidence.

Example UIAI-INTERFACE_TOOLBOX_CONTROLS-01 — Build an understandable leave-entry form

Scenario and inputs. Mohammad will enter a first day, last day and reason in the people-ops demonstration. Nadia owns the draft and may configure its published interface. The dates14–18December2026 and reason Annual leave are synthetic values, not employee account identifiers.

Procedure. Start with the native Form root. Add two Date inputs and a TextArea, give each a meaningful label, and bind them to declared Date/Text inputs. Use the property editor's required and validation surfaces rather than storing arbitrary display strings as dates. Provide helpful field-level messages and inspect keyboard order, accessible names and focus after an error. Use separate fields when the downstream rule declares separate dates; choose DateRange only when its actual destination type/shape is supported.

Expected result. The user sees an input interaction matching the data contract. Captured values and validation state are separate from persistence; no leave record is saved until an admitted rule/action does so. The property reference describes actual editor keys and options instead of making every node a free-form text control.

Failure and recovery. Correct a missing or incompatible bind destination through its declared input/record contract. An invalid date range needs clear validation and retained user edits. Do not use a read-only display value, a fake success message or a hidden privileged action to simulate a working form.

Sources. Input/property composition, actual bind choices, control contract.

Example UIAI-INTERFACE_TOOLBOX_CONTROLS-02 — Compose responsive application chrome

Scenario and inputs. Nadia is designing the Leave requests shell for desktop and phone. The authorized overview/request pages already exist. A start-edge navigation position should follow the reading direction, while an arbitrary physical left placement may not fit both languages.

Procedure. Use the shell's actual region controls, AppHeader and NavMenu according to the chosen preset. Add a ContentOutlet only where supported target-area routing is needed; inspect its main/secondary role in the native builder. Check the generated node defaults/options before choosing placement, dimensions or responsive overrides. Preview representative viewport widths and direction, and inspect the navigation's labels and current-page behavior.

Expected result. Structural layout and runtime-owned regions remain distinguishable. An opaque outlet does not render arbitrary authored children; inserting another control should use its parent or a neighboring region. Design-time seeds and layout options describe the intended authoring contract, not proof that every external target rendered successfully.

Failure and recovery. If content disappears after inserting into a leaf target, move it to an actual supported parent rather than adding more hidden children in Code. Repair unsupported placement values using the current option catalog. Preserve unsaved form work when navigating or replacing a region, and use the native discard/stay decision instead of forcing a route change.

Sources. Opaque and leaf targets, current placement properties, guarded shell transitions.

Example UIAI-INTERFACE_TOOLBOX_CONTROLS-03 — Open actual assigned work in TaskViewer

Scenario and inputs. Sara's admitted task list contains a real task ID for the synthetic leave request. A TaskViewer is meant to render that task's work surface; it is not a general form renderer whose author can supply a different form, workspace or performer.

Procedure. Select Task viewer from the native palette. Set taskId to the actual selected task ID or a supported expression producing it. Choose perform only when interactive work is intended; readOnly shows metadata rather than a disabled executable form. Configure summary/comments/attachments according to the design while retaining their independent permissions. Keep one active interactive viewer in its composition and allow the native host to select the task's exact pinned form.

Expected result. The task's current participants, claim state, form and canonical completion behavior own the experience. Authoring properties cannot change the authenticated workspace, identity, form version or output allowlist. The native selected/completed event payloads remain scoped to the task ID; universal supported signal behavior has its separate contract.

Failure and recovery. An unavailable task or revoked participant access must remain unavailable. Do not add a formKey override, authored children or another interactive viewer to bypass the task host. Read the canonical receipt after actual completion and reconcile uncertain outcomes instead of manufacturing a success event.

Sources. TaskViewer properties, authenticated task host, event payloads.

Example UIAI-INTERFACE_TOOLBOX_CONTROLS-04 — Choose an executable analytic source

Scenario and inputs. Nadia wants a leave-request count and a chart of admitted records. The source catalog may expose several categories, but catalog membership does not mean every control can execute every category. A reusable QUERY result is not automatically a direct Chart or Metric adapter.

Procedure. Select the desired control, open its native Connect data flow and inspect the source's actual shape and capabilities. Choose a supported published-record, Fabric or process source as applicable to that control. Configure fields/aggregation through the native plan editor and inspect its generated contract. For rule-query collections, use only the supported grid/list path with its own paging/search/filter/sort restrictions, rather than copying a Chart binding from a different adapter.

Expected result. The selected adapter and control agree on collection shape, identity and supported operations. A schema-compatible JSON object alone is not evidence of executable data. Current capability restrictions remain explicit, including direct rule-query restrictions for governed Chart/Metric plans and control-specific Lifecycle data support.

Failure and recovery. Keep an unsupported category unavailable; do not invent a preview dataset, silently drop server filters or bypass source permission. Change to an admitted adapter that actually expresses the intended analysis, or ask the source/control owner about the missing capability. A failed query is unavailable, not a trustworthy count of zero.

Sources. Governed source admission, native control contracts, data-source capability contract.

This manual combines source-backed control guidance with explicitly qualified composition recommendations. Current source/capabilities decide which adapters and actions are available; retained verification counts and screenshots belong to their original candidates and are not certification of current master. The capability matrix and source catalog explain the per-control limits.

Design canvas actions and direct layout editing

In Design, right-click a control on the canvas or in Outline to open its action menu. The same menu opens from a focused control with the Context Menu key or Shift+F10. It shows the target, available actions, keyboard shortcuts, and a reason for actions that cannot run. Right-clicking an unselected control selects it; right-clicking one of several selected controls keeps the group. “Nest into previous” is available only when the preceding sibling can contain the selected control. Move up, down, and out also follow the document rules; a direct child of the required Form or Dashboard root cannot move outside that root. Right-click an empty column slot to Paste directly into that column. Preview and published Live do not display these authoring menus or guides. Native text fields keep their browser editing menu.

Click a control to select it. Ctrl-click (Cmd-click on macOS) toggles controls and Shift-click selects a contiguous range in Outline order. When a selected container includes a selected child, Copy and Cut operate on the container once. Copy captures a snapshot that can be pasted repeatedly into another draft in the same workspace; each Paste creates fresh identities and keeps references between copied controls. A Paste that would leave an external reference unresolved is refused with an explanation and does not change the draft. Clipboard contents stay in the current browser tab and are cleared on workspace or principal change.

Open Select in the right-click menu for All or Similar objects. All selects every editable control on the current Design surface, including controls nested in a collapsed Outline branch; the protected Form or Dashboard root stays out of the batch so Cut remains available for its editable children. Similar objects selects controls of exactly the same type as the right-clicked control across that surface. Both actions replace the previous selection and work from canvas or Outline; they do not change the draft or Undo history. Open the Select submenu with a pointer or Right Arrow. Use Left Arrow or Escape to return to the main menu. These selections feed the same Copy, Cut, Delete, and Properties flows as manual multi-selection. App Shell page and region switches have separate selection scopes.

The Design right-click menu stays left-to-right, including when the authored interface canvas is right-to-left and when the menu opens from a control, empty canvas, column slot, or Outline. Icons lead from the left, menu text aligns left, and the Select submenu opens with Right Arrow and closes with Left Arrow. Changing the interface direction changes the canvas, while this editor action menu and the surrounding Studio toolbar stay left-to-right.

Cut leaves controls in place with a pending appearance until a valid Paste moves them. It only moves within the same draft and surface. Escape, a replacement Copy/Cut, or leaving that surface cancels the pending move without changing the draft. A stale draft or invalid destination refuses the move. A successful batch Paste or move is one Undo/Redo step. Use the regular Save action to keep the changed draft; a save conflict must be resolved before publishing.

The designer header keeps Save status and Recovery visible while you work. “Saved locally” means this browser has preserved the edit; the same status says whether the remote save is pending, in progress, or blocked. “Saved remotely” confirms the server save. Offline or local-storage failures appear in the same header status area. Open Recovery by mouse or keyboard to review or export local copies and the full text of a save error. The editing canvas stays in place as these states change.

Grid, Columns, Stack, Section, Card, Container, Toolbar, Widget, and Dashboard display their effective columns in Design, including empty slots. Drop a toolbox control or Paste into a labelled slot for exact placement. Columns starts with two tracks when newly added; existing documents retain their authored layout. Drag a boundary between two columns to adjust their ratio, or focus the boundary and use arrow keys, then Enter to commit. Escape cancels a preview. The Properties panel shows the custom ratio and Reset action. A boundary is unavailable when the active layout stacks into one column or uses an automatically calculated count.

At browser widths of 900 px or less, Outline starts collapsed so the canvas remains usable. Use the labeled Outline rail to expand it, then its collapse button to return to the wider canvas. This compact behavior does not change the saved desktop Outline preference.

Find a control in Outline. Press / or Ctrl+F (Cmd+F on macOS) while Outline or the canvas has focus, and type part of a control's caption, its type, or the field it is bound to. The match ignores case.

  • What stays visible: only the matching controls and their parents, in place, opening any branch you had collapsed. Each match shows its nearest parents (for example … › Details › Line items; hover for the full path) and its bound field, so two controls with the same label can be told apart.
  • Choosing a match: use the arrow keys to move between rows and Enter to select one, or Enter in the search box to select the first match. The canvas then scrolls to the control. If it sits in an accordion panel, tab or step that is closed, the canvas opens it for you. This is only a view: the page's saved settings, such as which panel opens by default, do not change.
  • Repeaters: a control inside a repeater is selected once, as the authored control; its sample rows are not separate controls.
  • Escape, the clear button, or deleting the text clears the search, keeps the found control selected, and makes sure it is visible in Outline.
  • Going back: Back to <previous control> (or Alt+Left) returns to the control you had selected before the search, and to where the canvas was scrolled. Back follows that control even if you moved it, and disappears if it was deleted. Inside the designer, Alt+Left never acts as the browser's Back button.
  • Closed panels: selecting any control in a closed panel, tab or step opens it on the canvas. A control in a disabled panel is still selected, and Outline says that the canvas cannot open its panel.
  • Branches you toggle while searching keep your choice after you clear the search.
  • Many matches: at most 50 are listed, with the total and a hint to refine.
  • No matches: Outline says so and offers to clear the search.
  • Saving: searching, revealing and going back never change the saved interface.
  • Outside Outline and the canvas, Ctrl+F stays the browser's own find.

Select a control to reveal its outer-item width handle. Drag it, or use arrow keys and Enter, to set its width; Escape cancels a preview. This works on text, action, composite, data, and container controls. A Grid drag may also set a span when the control crosses a track boundary. Width, span, and column ratios can be authored at the active responsive breakpoint; the panel distinguishes an inherited value from a local override. The context menu's Reset width and span action clears both values at the active breakpoint. Desktop · 1440 and 1920 edit the root values; Desktop · 1280 edits the xl override. Compare Design and Preview at the same device setting before publishing, then check the published Live screen. Editor panes can change the available content width, so compare column and control proportions at a matching content width. Internal fields of a data grid and Rich Text table columns use their own editors.

This report documents the controls currently exposed by the Studio Interface Designer toolbox, the properties shown in the Properties panel, and the intended use of each control. It reflects the frontend implementation in Toolbox.tsx, propertySchema.ts, controlHelp.ts, and nodeRegistry.ts.

Scope and behavior

The toolbox is grouped by Layout, Controls, Data, Display, Navigation, Actions and Tracking. The current insertable inventory is defined by studio/frontend/src/features/designer/propertySchema.ts (PALETTE); the tables below also contain design guidance and dated acceptance evidence, so they are not an evergreen generated count. An item can be clicked to insert it at the current selection/root or dragged to a canvas drop zone. The toolbox supports text search and hover/focus help with a live preview where available. NavMenu is available only when editing an App Shell.

This is the curated toolbox, not the entire closed screen vocabulary. It includes author-facing types such as RichText, RadioGroup, Accordion, and Modal; additional renderer-only vocabulary may still exist outside the palette.

How to read the property inventory

The Properties panel composes common bundles with control-specific fields. The bundle codes below summarize recurring concepts. They are not a substitute for the exact per-control reference: some controls add, omit or specialize properties.

Property editor types

Editor type Meaning
text, textarea, number Direct scalar entry.
color CSS color, pasted value, or theme token.
icon Inflow business-icon selector.
select Choice from a defined option list.
expr Static value or InflowEL expression.
exprbool Boolean literal or conditional expression.
density Compact/cozy/comfortable selector.
statePreview Design-time sample/empty/loading/error/permission state selector.
columns, options, validate, messages Structured editors for those collections.
responsive Per-breakpoint width, span, and hidden settings.

Shared property bundles

B0 — Recurring base concepts

  • General: name; label for non-containers or title for containers.
  • Visibility: visibleWhen.
  • Layout: width, span, align, height, margin, responsive.
  • Style: background, color, border, radius, fontSize, fontWeight, textAlign.
  • Accessibility: help.
  • Advanced: read-only id.

B1 — Input controls, in addition to B0

  • Value/binding: bind, defaultValue, placeholder.
  • Validation: required, validate.
  • Behavior: readOnly, disabled.
  • Advanced: messages (empty, error, loading, unauthorized, validationFailed).
  • Option controls additionally receive options and optionAlign. optionAlign is available for Select, MultiSelect, RadioGroup, CheckboxGroup, SegmentedControl, ComboBox, and TreeSelect; Auto follows the nearest interface/layout direction (left in LTR, right in RTL).

B2 — Container controls, in addition to B0

  • Layout: direction, gap, padding.
  • Advanced: messages.
  • Layout-oriented containers Stack, Grid, Columns, Section, Card, and Toolbar additionally receive numeric columns for child reflow. (Tabs, Divider, and Spacer do not.)

B3 — Data-container controls, in addition to B2

  • Data: rows, columns.
  • Search/paging: paging.mode (none, paged, cursor).
  • Actions/events: selection.mode (none, single, multi), onRowClick.
  • Layout/state: density, stickyHeader, dataState, hiddenWhenEmpty.
  • State messages use the structured messages editor.
  • DataGrid, EditableGrid, and Table also receive columns.auto; Subform also receives rows.mode.

B4 — Display controls, in addition to B0

  • Value: bindable/expression-capable value.
  • Advanced: messages.

B5 — Action controls, in addition to B0

  • General: variant (primary, secondary, danger, quiet).

B6 — Tracking controls, in addition to B0

  • Data: dataSource (static, expression, process, task, dataModel, api) and bindable boundValue.
  • Behavior: hiddenWhenEmpty.
  • Tracking controls do not currently receive the structured messages field.

Toolbox inventory

Layout

Control (type) Bundle Control-specific properties Use
Stack (Stack) B2 + columns None Basic wrapper that lays children out in a row or column.
Grid (Grid) B2 + columns None; new nodes default to 2 columns Arrange children into equal grid columns.
Columns (Columns) B2 + columns None Create a multi-column layout row.
Section (Section) B2 + columns collapsible, defaultExpanded Group related fields in a titled, optionally collapsible block.
Card (Card) B2 + columns subtitle Present related content in a bordered card with title/subtitle.
Tabs (Tabs) B2 None Organize child panels so one tab is visible at a time.
Toolbar (Toolbar) B2 + columns None Create a horizontal action/control bar.
Divider (Divider) B2 None Visually separate content with a horizontal rule.
Spacer (Spacer) B2 None Insert intentional empty space between items.

Controls

Control (type) Bundle Control-specific properties Use
Text (Text) B1 minLength, maxLength, pattern, trim Capture a single line of text.
Text area (TextArea) B1 rows, maxLength, autoResize Capture longer, multi-line text.
Number (Number) B1 min, max, step, decimalPlaces Capture a numeric value with range and increment rules.
Select (Select) B1 + options searchable, multiple, allowEmpty Choose from a configured or data-bound option list.
Checkbox (Checkbox) B1 None Capture one true/false choice.
Date (Date) B1 format, minDate, maxDate, disablePast, disableFuture Choose a date subject to formatting and range constraints.
File upload (FileUpload) B1 accept, maxSize, maxFiles, multiple Upload one or more files subject to type and size limits.

Data

Control (type) Bundle Control-specific properties Use
Data grid (DataGrid) B3 + columns.auto None Render a bound collection as a feature-rich data grid.
Editable grid (EditableGrid) B3 + columns.auto None Display and edit records inline in a grid.
Lookup (RecordPicker) B1 displayColumn, searchColumns Search a data source and select a record; “Lookup” is the toolbox label, not a separate node type.
Tree grid (TreeGrid) B3 None Display hierarchical records in expandable grid rows.
Pivot grid (PivotGrid) B3 None Summarize and pivot multidimensional data.
Repeater (Repeater) B3 None Repeat a child template for each record in a collection.
Table (Table) B3 + columns.auto None Present a collection in a simpler tabular form.
Record view (RecordView) B3 None Present the fields of one record.
Chart (Chart) B4 + data binding Chart data (Connect data or Build chart data), point activation, refresh, freshness and state messages; chart type is chosen in the chart builder (bar, line, area, pie, donut, scatter) Plot governed data as a chart. Height is controlled by the shared height property.
Metric (Metric) B4 prefix, suffix Show one headline value with a label and optional units.
Subform (Subform) B3 + rows.mode None Embed another form inline, using bound records or static sample rows.

Implementation note: Chart and Metric appear in the Data toolbox group but are display controls in the node registry, so they use B4 plus their own data-binding sections (Connect data / chart and metric builders) rather than the B3 grid properties.

Display

Control (type) Bundle Control-specific properties Use
Heading (Heading) B4 headingLevel (H2, H3, H4, Plain text) Display a section or content heading with an explicit semantic level.
Prose (Prose) B4 None Display a block of body text.
Image (Image) B4 src, alt, fit (cover, contain, fill, none), optimizeImageDelivery (default false) Pick a Documents image or bind a Repeater's document ID with ${document_content_path(item.imageDocumentId)}; the Image control loads the document with the viewer's workspace and DMS permissions. HTTPS and root-relative non-DMS image URLs remain supported. Unsafe fixed protocols fail publication and unsafe evaluated values render the empty state.
Badge (Badge) B4 preset, variant (soft, solid, outline) Display a compact status pill using a preset or data-driven text/color. Shared color supplies its base color.
Control (type) Bundle Control-specific properties Use
Nav menu (NavMenu) B2 placement (top, start) Add top or start-edge navigation, optionally seeded from business functions. Available only in App Shells.

Actions

Control (type) Bundle Control-specific properties Use
Button (Button) B5 size, loading, confirm Run an action, with optional loading state and confirmation prompt.
Link (Link) B5 href, newTab Navigate to a static or expression-driven URL.

Tracking

All tracking controls render immediately with representative sample defaults until a real source or expression is bound.

Control (type) Bundle Control-specific properties Use
Progress Bar (ProgressBar) B6 value, min, max, showPercentage, animated, striped, trackColor; shared color is the fill Show overall progress for a request, task, or process.
Step Progress (StepProgress) B6 orientation, showIcons, showLabels, showStatus, completedColor, activeColor, pendingColor Show process stages as connected steps with state.
Timeline (Timeline) B6 sortOrder, showIcons, showActor, showTimestamp, icon Show a dated activity/history feed.
Status Badge (StatusBadge) B6 status, icon, badgeStyle, iconPosition, showIcon, showLabel Show the current status as a colored pill with an icon.
Current Step Card (CurrentStepCard) B6 stepName, status, assignedTo, dueAt, icon, showAssignee, showDueDate; shared color is the accent Summarize the active workflow step, owner, and due date/SLA.
SLA Indicator (SlaIndicator) B6 status, icon, displayMode, showCountdown Indicate whether a task/process is on track, due soon, or overdue.
Task Assignment (TaskAssignment) B6 assignedGroup, claimedUser, assignmentStatus, icon, showAvatar, showWaitingTime Show who owns or has claimed a task and how long it has waited.
Process Summary (ProcessSummary) B6 processName, status, currentStep, progress, slaStatus, icon, layout, showProgress, showSla Present a compact overview of process status, step, progress, and SLA.
Approval Trail (ApprovalTrail) B6 showApprover, showDecision, showComment, showTimestamp, icon, approvedColor, rejectedColor Show approval decisions without the full activity timeline.
Tracking Table (TrackingTable) B6 icon, rowKeyField, showStatusIcons, showRowActions, pagination, search Present process steps or tasks in a searchable, pageable table with stable identity-backed row actions.
Tracking Header (TrackingHeader) B6 status, currentStep, assignedTo, progress, icon, layout, showProgressBar, showStatusBadge, stickyTop Add a compact tracking strip to the top of a detail page.

Property semantics and important constraints

  • name is the author-facing internal reference; id is generated by the system and read-only.
  • visibleWhen, bindable values, and expression-enabled booleans can be driven by InflowEL rather than fixed values.
  • Ordinary field destinations use compatible declared input (ri:/inputs:) or data (data:) members through the native picker. Local action/selection results have their own supported destination editors; do not treat every local path as an ordinary editable field binding.
  • responsive stores per-breakpoint overrides for sm, md, lg, and xl.
  • span affects placement inside a parent grid; container columns controls how that container reflows children. Data-control columns is instead a structured list of displayed fields.
  • messages can override empty, error, loading, unauthorized, and validation-failed text where that structured editor is available.
  • Data-control dataState is a design-time preview and does not replace the real bound source.
  • Selection uses the control's actual supported mode, governed identity and local result destination. Current source capabilities and the selected profile determine its scope; it is not a permission grant.

Read the current control contract before configuring it

The exact property inventory is maintained in the generated node reference. It includes current property labels, stored keys, editor kinds, groups, default node seeds and advertised event payloads for every actual authorable control. The abbreviated bundles above explain recurring concepts; they are not an exhaustive assertion that every type exposes every shared property. Per-control schema and specialized editors decide applicability.

For a routine field, choose its declared destination in Data Binding, its default/computed value in Value, required rules in Validation, and conditional presentation in Visibility. A binding destination is not an arbitrary expression slot. Scalar expression support defaults to enabled unless explicitly false or read-only; composite builders own structured mappings. The current inspector group order is General, Value, Data Binding, Validation, Visibility, Behavior, Columns Fields, Search Filters Sort Paging, Actions, Layout, Style, Events, States, Accessibility and Advanced. Empty groups do not render.

Earlier July design studies and third-party review proposals mixed desired behavior with implementation facts. They remain available in the original source history; they are not current product instructions. This maintained guide uses the current property model, native inspector dispatch and control contract.

Data views and complex dashboards: no-code authoring guide

Choose the source and the intended interaction

Decide which admitted business object to show, whether the user reads or edits it, which fields/aggregations are needed, and how selection or an explicit action should affect another component. Then select the control whose actual adapter supports those needs. DataGrid, EditableGrid, TreeGrid, PivotGrid, RecordView, Chart, Metric and collection-template controls have different authoring and runtime contracts. A category appearing in the shared catalog does not promise every control can execute it.

Design the loading, empty, failure and responsive experience alongside the successful result. Permission-denied objects/actions remain absent; neutral unavailable direct-link behavior is distinct from a transient load failure. Design-time sample rows are not customer data or proof that a source resolved.

Current implementation boundary

The current designer combines design-time representative states with governed published runtimes. Representative rows remain preview-only; a published control never substitutes them for an unresolved source.

  • DataGrid provides governed searching, filtering, sorting, paging, selection, and standard data states. EditableGrid now adds authoritative published-record create/update/delete, per-row and Save-all modes, atomic or partial batch semantics, optimistic conflict detection, retry-safe idempotency, protected-field enforcement, import repair, and unsaved-navigation protection. Only edits made against an exact published record source persist; Designer sample edits remain local.
  • Table renders configured columns, rows, and row actions but has a simpler experience than DataGrid.
  • RecordPicker has governed published remote search and stable-key selection. Representative records are used only in the explicitly labelled design preview; published runtime never substitutes sample results for an unresolved source.
  • RecordView now has its dedicated governed source, field, layout, null-policy, and master-detail wizard plus published single-record resolution. Metric now has its complete governed aggregate, format, comparison, threshold, filter, and supporting-record slice; remaining Chart dashboard-data enhancements are documented below.
  • PivotGrid now has a governed no-code builder, server-authoritative aggregation, cardinality preflight, date hierarchies, totals, bounded drill-to-records, exact-decimal rendering, and responsive published views. TreeGrid now has a governed no-code builder, all three hierarchy modes, relationship-aware traversal, server-authoritative lazy branches, bounded projections, and responsive published views.
  • Repeater renders the authored child template for governed live rows, with design-time sample fallback only when no runtime collection is connected.
  • Subform can repeat a bound collection, embed an exact published child interface, or edit a governed one/many record relationship. The no-code inspector pins the child version, proposes type-compatible input mappings for review, stores accepted parent paths as evaluated expressions, and configures header visibility/style, relationship paging/search/filter/sort/selection, parent or independent save scope, add/edit/remove/unlink/reorder permissions, and empty behavior. The runtime rederives the immutable relationship and field capabilities, uses opaque handles and optimistic tokens, rejects cycles and stale/cross-scope requests, and joins child validation into the parent summary.
  • Parent-scope Subform submission atomically persists the staged related-child mutations, including batches spanning multiple Subforms. It does not persist the parent record itself; parent-record persistence remains the responsibility of the parent form/process submit path.
  • Live form rendering evaluates rule-bound DataGrid, EditableGrid, and Table rows from reactive interface state and uses governed endpoints for published-record and relationship sources. It never substitutes design samples for a resolved runtime source.

Internal prototype-only publishing (implemented safety gate)

Sample or unbound data controls block normal publication. For an internal design review, an administrator may explicitly enable the non-production prototype exception with screens.prototype.enabled, restrict it to DEV and/or STAGING with screens.prototype.allowedEnvironments, and cap unresolved controls with screens.prototype.maximumUnresolvedDataControls. PRODUCTION is rejected at configuration load and again at runtime; it can never be allowlisted.

The no-code workflow is:

  1. Clear the canvas selection and open Interface settings.
  2. Review the administrator-provided environment decision and limit.
  3. Turn on Internal prototype only. The designer stores prototypeOnly: true in the interface document and shows a persistent warning that sample data may be visible.
  4. Validate and publish. The exception suppresses only the sample/unbound-source blockers when the current workspace and unresolved-control count satisfy policy. Structural, expression, refresh-governance, permission, and all other validation errors still block publication.
  5. Turn the switch off before production readiness and connect every data control to a runtime source.

The switch fails closed while policy is loading, when the policy endpoint is unavailable, when the administrator disabled the exception, in an unapproved environment, or above the unresolved-control limit. A published prototype retains a visible runtime banner and data-agent-state="prototype-only"; it must never be presented as a production dashboard.

The sections below distinguish current control contracts from optional composition recommendations. Use each actual native editor and its admitted capabilities; unsupported categories are not repaired by inventing raw configuration.

Connect data through the control's actual editor

Save the interface before connecting a governed source. For supported grid/list controls, Connect data opens the admitted catalog; Replace connected data revisits a saved connection. Read the actual source descriptor, source/version/path, governed fields, capabilities and available interactions. Review the generated configuration before applying it. A design sample is explicitly labelled and does not establish a production connection.

Connect data establishes the source. EditableGrid's editing profile separately declares writable fields and mutation policy; RecordView, Chart, Metric, TreeGrid and PivotGrid have their own plan/profile editors. A successful catalog lookup does not grant record writes, authorize provider disclosure or guarantee all interaction modes. Resolve a real source/capability failure rather than removing its gate.

Sources: grid/list Connect data, open/replace and save prerequisite, governed analytic admission.

Rule-result interaction execution

Published rule-result sources use one of three explicit V2 strategies. The strategy is part of the immutable screen version; the browser cannot choose or replace it at runtime.

  • Complete local is for a complete, bounded collection. Declared search, filters, sorting, offset paging, relationships, and selection run in the shared safe collection runtime. Controls expose only their implemented subset; Table, for example, supports local sorting but not grid-style filters or selection.
  • Native query is for published QUERY rules. The interface sends binding ids and typed values only. The server resolves the authored paths, applies the viewport inside the governed query runtime before paging, and returns authoritative offset metadata. Native query paging is offset-based.
  • Typed rule inputs is for a rule whose published inputs already represent search, filter, sorting, relationship, or page arguments. The server maps each operation to the authored input name and reads offset/cursor metadata only from the authored response paths.

Remote pages are never re-filtered or re-sorted in the browser. Unknown bindings, duplicate operations, unsupported operators, unsafe values, cursor/offset mismatches, and page sizes above the published maximum fail closed.

Review the selected source's actual field types, cardinality, identity and supported operations. Choose compatible fields and bounded paging deliberately. Remote pages must keep their server-side filters/sorts rather than be silently reinterpreted in the browser. After a source replacement, revisit columns, filters, selection/result destinations and row actions because they depend on that source's real contract.

Data Grid (DataGrid)

Use it for: operational lists that need searching, filtering, sorting, paging, selection, and row actions. This should be the default recommendation for collections with more than roughly 20 records or more than four meaningful fields.

Minimal no-code setup

  1. Drop Data grid and choose Connect data.
  2. Select the collection/report. The designer previews rows and generates columns.
  3. In Fields, keep suggested columns or use Add all/Search/checkboxes. Drag to reorder.
  4. For each field, choose a display recipe: Plain text, Status badge, Currency, Number, Date/time, Person, Link, Image, or Custom (Advanced).
  5. Choose a default sort using “Newest first,” “A–Z,” “Highest first,” or a selected field/direction.
  6. Enable Search and accept recommended searchable fields; add filter chips from enum, boolean, date, relation, and numeric fields.
  7. Choose selection: None, One row, or Many rows. If selected, choose where the selected record(s) are stored.
  8. Configure “When a row is opened” by choosing Open record view, Open drawer, Navigate, or Do nothing.
  9. Choose paging based on source size; default to server paging for large/remote sources.
  10. Preview all states and phone layout, then publish.

Column links and row actions

  • Open Configure data grid → Fields, then choose Link as the column's format. The complete governed-link editor appears with that column. Add, edit, remove, reorder, enable, or disable its actions; choose linked business text, a cell icon, a row action, or the default row-open action. Set Action purpose to Standard navigation or Open a task, then set the business label and action icon in the same column configuration.
  • Choose destinations in the searchable destination dialog. Published Interfaces and App Shell pages are pinned to an exact published version; App Shell links also pin the page. Map declared destination inputs from the selected row, an Interface input, a local value, a constant, or an expression.
  • Published Interfaces, App Shell pages, and Task Viewers can open as a page, modal, drawer, or embedded surface. Record Viewer opens as a modal. Internal pages, web addresses, and dynamic destinations use page navigation.
  • Lifecycle-report insertion preconfigures the applicable Link column from the chosen task destination, version/page, presentation, and activation. Reopening Configure DataGrid shows those exact values in the standard column editor. Changing the report context preserves the DataGrid actions, and changing an action preserves the report source, columns, paging, layout, and styles.
  • Runtime evaluates mappings against the exact clicked row. Server paging does not preload other pages or change the row identity.

Smart defaults and safeguards

  • Choose 5–7 high-value columns, keeping identifiers and technical audit fields hidden by default.
  • Use the record’s stable primary key for row identity automatically.
  • Make status enum fields badges and monetary fields localized currency.
  • Recommend sticky header only for long scroll regions.
  • Never perform client-only searching/sorting when the source is server-paged; generate source parameters transparently.
  • Explain when a filter cannot be pushed to the source and may produce incomplete results.

Complex-dashboard use

  • Allow the grid to consume shared dashboard filters automatically.
  • Let clicking a chart point filter/highlight matching grid rows.
  • Allow saved views such as “My open requests” and “Overdue this week.”
  • Support a compact summary bar above the grid showing count, total, and selected count.

Editable Grid (EditableGrid)

Use it for: bulk entry and controlled inline editing of related records, line items, allocations, schedules, or decision-table-like rows. Do not recommend it for complex single-record forms.

Minimal no-code setup

  1. Drop Editable grid and choose the writable record collection or relationship.
  2. Select Edit existing, Add rows, Delete rows, and whether changes save Per row or All at once.
  3. Accept inferred column editors based on field type: Text, Number, Date, Checkbox, Select, Lookup, or Read-only calculated value.
  4. Mark required fields and choose validation presets. Cross-column checks use the visual condition builder.
  5. Choose how new rows obtain defaults: model default, current user, today, copied parent value, or rule.
  6. Choose the row key and concurrency behavior from safe presets: Prevent overwrite, Refresh and compare, or Last write wins only where allowed.
  7. Configure Add, Save, Cancel, Delete, duplicate-row, and import actions through checkboxes and sentence summaries.
  8. Preview valid, invalid, unsaved, saving, conflict, and failed-save states.

Smart defaults and safeguards

  • Infer editability from permissions and model metadata; show forbidden fields read-only with a reason.
  • Never allow editing primary keys, audit fields, formulas, or protected relationships unless the model explicitly permits it.
  • Keep dirty rows visibly marked and prevent navigation with unsaved changes without confirmation.
  • Provide spreadsheet paste/import with a validation preview and per-cell error repair.
  • Require explicit confirmation for destructive bulk deletion.

Implemented runtime contract (source reference; not executed by this refresh): a connected, exact published record type is loaded through a bounded server query. The server derives readable and operation-specific writable fields from the immutable published screen and authoritative model metadata; browser-supplied source, field, permission, and version overrides fail closed. Per-row save and Save-all are both implemented. Save-all requires an explicit atomic or partial policy: atomic rolls back the whole batch, while partial returns ordered per-row saved/conflict/error outcomes and retries only unresolved rows with stable idempotency keys. Opaque record handles and signed baselines detect stale updates/deletes, and the UI preserves drafts for repair, current-value comparison, or authoritative reload. CSV/TSV import is bounded, neutralizes spreadsheet formulas, previews validation, and supports per-cell repair before the same governed write path revalidates the rows.

Delete the server would refuse (SCRUM-3796). The editable-grid query response (POST /api/screens/{screenKey}/editable-grid-query) carries a boolean deleteAvailability. It is computed by the record write service's own delete policy for the grid's exact target: true when the workspace allows permanent removal, or when it does not but the record type supports the governed Archive that the delete becomes; false when neither holds or the grid does not allow delete. When it is false the grid does not render Delete selected or a saved row's Delete, and does not register the selection.delete command; a new unsaved draft keeps its Delete. A missing field means available. Restrictions that depend on the row (active related records) are still reported when the row is saved, and the server refuses an unavailable delete regardless of the field. After a row save is refused because the workspace forbids permanent deletion and the type cannot be archived, the banner states the refusal and offers no retry; cancel the row's delete mark instead.

Unauthorized and load-failed states (SCRUM-3820). While the grid shows "You cannot edit these records." or "Editable records could not be loaded.", it renders no editing control and registers no row.add, import.open, selection.delete or changes.apply-preview command, and its editing handlers refuse. The same holds while a published source is first loading. A first load refused as unauthorized always ends in the unauthorized state. If a later reload is refused while unsaved edits exist, the edits stay with the message "These records could not be refreshed, and saving may be refused." The server still decides each save; a refused save shows Discard drafts and reload access. Without unsaved edits, a refused reload shows the unauthorized state.

Follow-ups (SCRUM-3823). A grid refreshed by a rule result reads deleteAvailability from editable-grid-hydrate as well, so it hides a refused Delete too. Save-all offers no "Try saving again" after the workspace refuses a delete it cannot archive, or after a refused reload kept the drafts; fix or cancel the drafts, then use Save all. This applies to a published query source and, since SCRUM-3839, to a grid refreshed by a rule result: a refused refresh of either keeps the drafts, shows and announces "These records could not be refreshed, and saving may be refused.", and offers no "Try saving again". Since SCRUM-3854 (decision N-014), a refresh that finds the records missing (not found) reads exactly as a refused one, on both paths: with drafts it shows the same sentence and no retry, and a first load that finds nothing shows the same unauthorized state. A refresh that fails for another reason, such as a lost connection, keeps the drafts and still offers the retry. If the records change before a started save runs (for example, a new rule result arrives), the grid sends nothing and the banner reads "These records changed while saving. Reload and try again." If the screen context the records need is not available when the grid loads, the load-failed banner reads "The screen context these records need is not available. Reload the page and try again." A save that finds the records missing (not found) is an ordinary save failure and keeps its retry. While the grid shows "Editable records could not be loaded." with an enabled Retry, the agent command <grid>.state.error.retry is enabled and reloads the same way.

Required columns and number cells (SCRUM-1804). In Configure editable grid → Fields and editors, check Require a value for <column> to stop people from saving a row while that cell is empty. Columns that the published data model already requires are shown checked and locked. A column that only existing rows can edit (not new rows) cannot be marked required; the option is shown unavailable with the reason. Number cells only accept numbers: if someone types text a number cell cannot read, the cell shows "<column> must be a number." and the row cannot be saved until it is corrected or cancelled. Clearing an optional cell is still allowed and saves the field as empty. The server independently refuses any update that clears a field the published data model requires (DATA_MODEL_RECORD_VALUE_INVALID, naming the field). If a column becomes required after rows were saved with it empty, those rows keep working for unrelated edits (the empty value is not re-sent), but a row cannot be saved with that column cleared; fill the empty values before relying on the requirement.

Release status (2026-07-16): Ready. The final isolated browser run proved bounded paging, page-scoped selection, search/filter/sort, UI create/update/delete, reload persistence, 403 denial, LTR/RTL isolation, 390 px responsive rendering, and accessibility/agent identifiers. Evidence is recorded in agent-findings/editable-grid-subform-release-qa/final-runtime-certification-1784233496.md.

Designer sample rows are still non-persistent by design. Publication requires an exact writable source, stable identity, explicit operations, protected-field reasons, and a complete save/conflict contract.

Lookup (RecordPicker)

Use it for: selecting a related record or using a record as a dashboard filter, such as Customer, Owner, Department, or Process.

Minimal no-code setup

  1. Select Connect data and choose a published record source. The source must prove server paging, remote search, field visibility, and server-side permission filtering; otherwise configuration remains disabled with a reason.
  2. Open Configure lookup. The stable key is taken from the published primary key and is never offered as the friendly display label.
  3. Choose one primary display field and, optionally, a different secondary field. Only visible, executable, single-valued fields are enabled. The preview shows the same two-line result style used after publication.
  4. Choose one to eight approved search fields. Collection-valued, hidden, non-searchable, and source-unsupported fields stay visible but disabled with an explanation.
  5. Optionally add up to twenty fixed filters. The designer chooses the value editor and permitted operators from the governed field type: text supports is and contains; Boolean and identity fields support is; number, date, and date-time fields also support ordered comparisons. Users do not type SQL or expressions.
  6. Choose the compatible rule input or local value that receives the selected stable key. Complete-record targets are disabled because the saved binding is deliberately a key; the selection event still carries the bounded, governed projected record for no-code actions.
  7. Decide whether the selection may be cleared. Required Lookups keep this off automatically. Review the generated business sentence, resolve any schema drift through the offered compatible replacements, and apply.
  8. To use the Lookup as a dashboard filter, create a Lookup selection interaction. The target picker lists every compatible control and also shows incompatible or denied controls with safe reasons. Add each desired target; reopening the recipe shows the saved affected controls.

Published behavior

  • Search starts after a short 250 ms debounce. A newer search cancels the older request and late responses cannot replace current results.
  • The server reloads the published interface and derives the source, fields, filters, and projection from that version. The browser sends only the screen version, control id, search text, and bounded page request.
  • Loading, empty, error, unauthorized, and stale states are explicit. A recoverable later failure keeps the last good options marked as out of date.
  • Result rows are capped at 25, use unique stable keys, and contain only the configured governed scalar fields. Undeclared server fields are discarded.
  • Keyboard users can open and move through the combobox, select with Enter, close with Escape, clear where allowed, and retain deterministic focus.

Smart defaults and safeguards

  • Prefer human fields such as name/title and add code/email as secondary text.
  • Search only indexed/approved fields and debounce remote search automatically.
  • Store the stable record key while showing the human label.
  • When used as a dashboard filter, automatically connect compatible data controls and show the affected-control count.

Relationship members: a nested member such as order.customer.region.name is valid when every relationship hop is governed, readable, bounded, and single-valued and the terminal member is an executable scalar. The response preserves that nested shape while removing undeclared siblings. A one-to-many member such as order.lines.product is not flattened into a scalar Lookup field; use the child record type or a governed flattened view instead.

Current verified boundary: the governed published Lookup is single-select. Multiple selection, recent-record suggestions, and create-new-from-Lookup are not part of this verified slice and must not be implied by the designer.

Tree Grid (TreeGrid)

Use it for: hierarchical data such as organizations, categories, accounts, work breakdown structures, parent/child tasks, and nested locations.

Minimal no-code setup

  1. Connect a hierarchical source.
  2. Choose hierarchy mode: Parent field, Children collection, or Path/level field.
  3. Confirm the identity, parent, and display fields using visual sample rows.
  4. Select supporting columns and their formats.
  5. Choose initially expanded depth, expand-on-row-click behavior, and lazy loading for large trees.
  6. Choose selection rules: any node, leaves only, one branch, or multiple nodes.
  7. Configure row open/action and Empty/Loading/Error per branch.

Smart defaults and safeguards

  • Detect parent/children relationships from the data model.
  • Warn about cycles, orphan rows, duplicate keys, and excessive initial expansion.
  • Preserve expansion and selection while filters refresh.
  • On phones, switch to an indented list with priority fields rather than a wide table.

Current contract: TreeGrid has a governed hierarchy plan and published renderer, including current hierarchy modes, bounded projections, lazy branches and selection rules. Configure only the admitted source/mode/fields exposed by its native editor. Design samples are not a substitute for a resolved published hierarchy. Inspect Tree source and behavior dispatch and the hierarchy parity tests; these source references do not claim this documentation executed the runtime.

Pivot Grid (PivotGrid)

Use it for: multidimensional summaries such as spend by department/month, cases by status/region, or hours by team/project. Recommend a normal grid when users need individual records rather than aggregates.

Minimal no-code setup

  1. Connect a report/query source with dimensions and numeric measures.
  2. Drag or pick fields into Rows, Columns, Values, and optional Filters zones.
  3. For each value, choose Sum, Count, Average, Minimum, Maximum, Distinct count, or a governed measure.
  4. Choose totals/subtotals and number formatting.
  5. Choose default expansion depth and whether a value click drills to source records.
  6. Preview sparse data, null values, large cardinality, and phone behavior.

Smart defaults and safeguards

  • Classify text/date/enum fields as dimensions and numeric fields as measures.
  • Suggest a date hierarchy (Year → Quarter → Month) without requiring derived expressions.
  • Estimate cell count before running and require filters/aggregation for oversized pivots.
  • Keep ad-hoc SQL and arbitrary formulas out; advanced measures should be governed report/rule definitions.

Current state: PivotGrid uses a governed no-code field-zone builder and a server-authoritative aggregation runtime. Authors choose published dimensions, measures, filters, date hierarchy, totals/subtotals, formats, expansion, and drill behavior without SQL. Authoritative preflight blocks missing, stale, or unsafe cardinality evidence before publish; published rendering enforces the configured source-row and cell limits and issues only bounded, one-time drill grants. The isolated implementation evidence is recorded in docs/verification-2026-07-13-pivotgrid.md; the authoritative requirement manifest remains the release-status source and must not be promoted until the current integrated regression, browser, and manual-review gates pass.

Repeater (Repeater)

Use it for: card lists, feeds, product tiles, approval cards, or any collection whose item layout is richer than table cells.

Minimal no-code setup

  1. Connect the collection.
  2. Choose a starter item layout: Compact row, Card, Media card, Two-column detail, or Blank.
  3. Design one template item using ordinary controls. Binding pickers inside it show “Current item” fields first.
  4. Choose item spacing, columns per device, and item limit/paging.
  5. Add item click, row actions, add/remove/reorder behavior if permitted.
  6. Preview the template with several representative records and long/missing values.

Smart defaults and safeguards

  • Auto-create a strong title, secondary line, status, and primary action from source metadata.
  • Keep item/index variable syntax invisible; display “Current item → Customer name.”
  • Offer “Convert this repeater to Data grid” while preserving source and field mapping.
  • Virtualize or page large collections; do not render hundreds of complex cards at once.

Current implementation boundary: the renderer repeats the authored child subtree for governed resolved records and exposes scoped Current item and Index values. A published reusable query rule that returns a record collection can also power a Repeater through the bounded server adapter. Query inputs, client-side query execution, collection writes/reordering, and query-backed DataGrid/Table-style paging are not implied by this support and remain unavailable until their dedicated governed contracts are implemented.

When the rows cannot be shown: a Repeater (or a row-backed Subform) never shows a machine code. A structurally invalid collection reads This list can't be shown. followed by the reason in plain words, for example Row 1 has no unique id. A collection that could not be loaded reads This list couldn't be loaded., or This list isn't available yet. Save your changes, then reload the page. when the saved source is not available (an unsaved or changed draft). Arabic forms read the Arabic sentences. The same sentence appears in the form error summary after Submit. Agents and tests read the kind from data-agent-error (for example INVALID_ROW_SHAPE), the operation code from data-collection-error (for example SCREEN_COLLECTION_QUERY_TIMEOUT, also on the summary item), the row from data-row-index and a template problem from data-template-path and data-template-error. (SCRUM-3863)

When the list is refused or several rows fail: a list whose load is refused (not signed in, no access, or not found) reads only This is not available to you and offers no Retry, because trying again cannot help; the root's data-agent-state is unauthorized. Any other failure keeps This list couldn't be loaded. and Retry. A failed next page reads the same sentences, never the server's own text; after a refused next page the Next page or Load more control is gone, and the rows already shown stay. When several rows of a connected list fail on the same summary item, the summary shows each distinct sentence once, never a row path; the paths are in data-error-path. A summary item whose field is not known reads the plain label A field, never the field's path. (SCRUM-3871)

Table (Table)

Use it for: compact, mostly static tabular summaries where the richer toolbar, selection, and interaction model of DataGrid is unnecessary.

Minimal no-code setup

  1. Connect the collection.
  2. Accept or select columns and formats.
  3. Choose optional sort and one or more row actions.
  4. Decide whether the result is a short complete list or needs paging.
  5. Preview empty and narrow-screen rendering.

Smart defaults and safeguards

  • Recommend DataGrid when search/filter/selection is added or estimated results are large.
  • Keep Table visually lighter and limit configuration to essentials.
  • Provide a one-click Upgrade to Data grid that preserves source, columns, sort, and actions.
  • Use mobile card reflow or controlled horizontal scrolling based on column priority.

Record View (RecordView)

Use it for: a read-only details panel, master-detail layout, drawer, or summary of one selected record.

Minimal no-code setup

  1. Select a single-record source: screen input, selected grid row, Lookup selection, route parameter, rule result, or current task/process record.
  2. Accept recommended fields, then search/check/reorder them.
  3. Choose a layout recipe: Label/value list, Two-column details, Summary card, or Sections.
  4. Choose field display recipes and hide empty/technical fields.
  5. Add Edit, Open full record, Copy, or related-record actions if permitted.
  6. Preview missing record, partial permissions, and long values.

Smart defaults and safeguards

  • When placed beside a grid, offer “Show the selected row here?” and wire selection automatically.
  • Group fields using data-model sections and relationships.
  • Render nulls consistently as blank, Not provided, or hidden based on one view-level choice.
  • Respect field-level permissions and explain omitted fields in designer preview.

Implemented no-code behavior: Properties opens a four-step Configure record view wizard instead of a raw expression or collection editor. Authors choose one of seven choices across six governed origins: interface input, route record, selected grid row, Lookup selection, published rule result, current process context, or current task context. Each choice saves a structured reference, not an author-written expression. Record declarations use ScreenInput.origin to distinguish ordinary interface input, route parameter, process variable, and task variable ownership; the same declaration supplies the exact published record type used by the view.

The wizard exposes only server-approved readable scalar members. Authors may select, search, relabel, reorder, format, group into sections, and choose a view-level or field-level null policy. Restricted members remain visible with a safe disabled reason and are never returned in the runtime projection. Record View accepts at most 50 visible fields, 12 sections, and eight governed path hops; duplicate, unsafe, stale, collection-valued, or permission-denied paths fail closed.

Published runtime resolves one record without accepting an author-written query. Input and route sources extract the configured primary key from the supplied Record object and send {version, nodeId, origin, recordKey}. Grid and Lookup sources send the scalar identity produced by the selected governed control. A rule reference persists exact ruleKey + ruleVersion; the server executes that published empty-input rule and derives the key, so the browser sends no record key. Process/task references persist contextKind + recordVariable; the browser sends the runtime-owned contextId, and the server resolves the variable after workspace and access checks. The server always reloads the immutable published definition and owns source, key, projection, and permission decisions. Loading, empty, unauthorized, error, and stale states are explicit. Superseded master selections are aborted and late responses cannot replace the newest record.

When a compatible grid is available, the wizard offers Show the selected record from this grid. This saves the grid control id and keeps the view synchronized without code. Label/value, Two-column, Summary card, and Sections layouts are available, with responsive stacking on narrow screens. The apply is atomic: it creates or replaces exactly one V2 gridSelection/lookupSelection -> fillDetail primary-key mapping. DataGrid and EditableGrid support grid selection; RecordPicker supports Lookup selection; Table and TreeGrid are not presented as compatible sources.

The final authoring visual run passed 5/5 browser scenarios. Manual review passed all eight screenshot/review pairs, including the follow-up fixes that separate a restricted-field reason from its label and show the selected source by business name instead of exposing a technical control id. Final release evidence also passes: 232/232 frontend files and 4,149/4,149 tests, production ui-guard, TypeScript and Vite build, 2,022 backend tests, migrations, and the API smoke check. FR-RV-001–005 are verified.

Chart (Chart)

Use it for: trends, comparisons, composition, distribution, or relationships over governed data. The consultant chooses the question (intent) before the chart type.

No-code setup (as delivered)

  1. Add Chart from the Toolbox (Data group) inside the Form, a layout container, a Repeater or a Subform. With a grid, table, record view, task viewer or input selected, the Chart is added next to it.
  2. Give it data, one of two ways:
    • Connect data — pick a governed source: a published data model record type, a Fabric type or relationship, or a process task list / process KPI. Choose the fields (up to 20 per connection). Sources a chart cannot use are shown disabled with the reason.
    • Build chart data — use a form data list, a Record input's relationship, or a workspace Fabric type.
  3. Edit chart (or Build chart data) walks through: Intent (Trend, Compare, Composition, Distribution, Relationship) → Source → Map data (Count, Sum, Average, Minimum or Maximum; Category; optional Series; Value; what to do with missing values and empty groups) → Present → Review → Apply chart data. Map data uses selectors; fields that cannot play a role are listed with the reason.
  4. Present offers only chart types that fit the intent and mapping (Trend: line/area over a date; Compare: bar, plus line for numbers and dates; Composition: pie/donut over text or yes/no without a series; Distribution: bar over a number without a series; Relationship: scatter over two numbers), plus number/currency/percent format, decimals (0–6), legend, data labels, a reference target, the accessible summary, and the data table.
  5. Optional behaviour in Properties: Save activated value in (the clicked point's key or the whole point, written into a local value; select again to clear), Automations → When a data point is clicked (set a field, call a rule, go to another screen, show a message), Configure refresh (on open, manual, scheduled, event-driven), hide when empty, freshness, state messages, Visible when, layout and style.
  6. On a Dashboard, published-record charts can drive and receive dashboard filters from the Filters & interactions tab when the fields share a business meaning. Forms do not have dashboard filters.

Not available yet: sort order and top-N, axis formatting, drag-and-drop field zones, and report sources.

Safeguards

  • Aggregation happens on the server; categories appear in natural order (numbers and dates by value), with the empty-value group last.
  • Scheduled refresh re-queries on the chosen interval; Event-driven refresh re-queries when any control on the same form fires the chosen event (for example onSelectionChange) and its automation succeeds. Event names apply across the whole form. Changes the system makes by itself — a grid restoring its selection after a refresh, or clearing it when the page or results change — do not trigger refreshes, so two controls cannot refresh each other in a loop. A control filtered by a grid's selection therefore keeps its last result until the performer selects again or it refreshes for another reason. Automatic refresh pauses, and says so, while a grid on the form holds unsaved edits; Manual refresh does not pause.
  • A chart that cannot be resolved (for example one saved by an older Studio over a relationship) shows its own error; the rest of the form still renders.
  • Process Model KPI is computed live from the process's cases each time the chart reads it (spec 108; this fixes SCRUM-2862). It needs a chosen process: the source's process key (lifecycleKey or processDefinitionKey, or an expression that gives one). With no process chosen it returns no rows and does not say why. It gives one row per version and step, over the process's production cases (debug runs are left out). Process Instance KPI and process task lists are live as well.
  • Every chart has an accessible text summary, an optional data table, and keyboard-focusable points.
  • Invalid geometry (negative pie values, non-numeric scatter categories, duplicate points) is shown as an error instead of a misleading chart.

Metric (Metric)

Use it for: one high-value KPI such as Revenue, Open cases, Approval rate, Average cycle time, or SLA breaches.

Minimal no-code setup

  1. Select Connect data, choose one published record type, and finish the governed source mapping.
  2. Select Edit metric, choose Count or a numeric field with Sum, Average, Minimum, or Maximum, then optionally add a visual filter.
  3. Choose Number, Currency, or Percent and configure prefix, suffix, decimal places, compact notation, and locale in the Format step.
  4. For a Target or Budget comparison, enter the baseline and confirm whether higher or lower is favorable. The server computes the comparison and delta; users never maintain a static delta.
  5. Add ordered visual threshold rules with a value, operator, label, tone, and icon.
  6. Publish the dashboard. The runtime reloads the immutable published Metric, rechecks screen/data-model permission and the exact source/type/version/member identities, then performs one bounded server aggregate. Loading, empty, unauthorized, malformed, and transport-error results remain distinct.

Smart defaults and safeguards

  • Combine prefix, suffix, decimals, compact notation, and locale into one Format picker.
  • Calculate delta and trend direction from the chosen comparison instead of asking for a static delta.
  • Do not assume an increase is good; ask or infer semantic direction.
  • Always provide an accessible label including value, unit, comparison, and period.

Verified now: all five Metric requirements (FR-MET-001–FR-MET-005) satisfy their acceptance criteria. Governed numeric aggregation, the combined Format contract, favorable direction, visual thresholds, Target/Budget/Previous-period/Compatible-measure comparisons, metricPredicate, and server-derived metricSupportingRecords are complete. Published values are canonical decimal strings. Repeating aggregate fractions use a documented 15-significant-digit, half-even presentation boundary; oversized integral values and values outside the client-safe magnitude/length contract still fail closed.

Final FR-MET-003/FR-MET-005 verification: Previous period uses a governed direct Date/Timestamp field, explicit Day/ISO-week/Month/Quarter/Year grain, and IANA timezone. The server—not the browser—derives adjacent half-open current/previous windows, returns canonical boundaries for an accurate accessible label, and rejects a conflicting dashboard filter on that date field. Compatible measure reuses the identical source, predicate, dashboard scope, and aggregate kind and requires matching authoritative metricUnit, metricCurrency, and metricGrain: SAME_QUERY metadata. Metric supporting records reload the immutable published Metric plan and rederive its predicate, current-period window, authorized filters, and target projection; the aggregate scalar is never treated as a row value. The final acceptance matrix is 35/35 pass. Release gates are green: backend 2,060/2,060, frontend 4,239/4,239, UI guard plus the 1,841-module production build, 12/12 manually accepted original/review visual pairs, migration no change, and API smoke HTTP 200. These two requirements are verified in the authoritative manifest. The overall Interface Toolbox specification remains NO-GO at 58/253 verified, with 195 release blockers remaining.

Subform (Subform)

Use it for: inline viewing/editing of a related single record or child collection through an existing reusable form definition.

Minimal no-code setup

  1. Choose the reusable form/interface to embed.
  2. Choose One related record or Many related records.
  3. Map parent context to subform inputs using friendly field-to-field rows; auto-map matching names/types.
  4. Keep Show header on for the default title bar, or turn it off for a body-only embed. Header background, title color, title font, and title size style that bar independently from the child form body.
  5. Choose read-only/edit mode and whether child changes save with the parent or independently.
  6. For collections, configure add/remove/reorder permission and limits.
  7. Configure empty relation behavior: Create related record, Select existing, or Show message.
  8. Preview validation, unauthorized, unsaved, and failed-save states.

Smart defaults and safeguards

  • Infer the relation and mapping when dropped inside a bound RecordView/form.
  • Prevent circular embedding and incompatible input mappings.
  • Parent-input choices are stored as expressions and pass the current parent value at runtime. Existing custom literals remain literals; drafts affected by the older bare-path picker are repaired when reopened.
  • Custom header foreground and background colors must be set together and pass WCAG AA contrast. A hidden visual header still gives the Subform region an accessible name.
  • Surface child validation in the parent error summary and navigate to the invalid row/section.
  • Keep static rows explicitly design-only; block publish or require confirmation while unbound.

Implemented runtime contract (source reference; not executed by this refresh): the designer selects an exact published parent type and relationship, pins a reusable child-interface version, and exposes typed parent-to-child mapping with reviewed auto-map suggestions and disabled incompatible choices. One/many cardinality, parent/independent save scope, add/edit/remove (delete or allowed unlink), bounded full-scope reorder, page size, search/filter/sort fields, fixed filter expressions, page-scoped selection, and show/hide empty behavior are configurable without code. The server rederives all relationship, cardinality, permission, projection, and writable-field facts from the immutable publication; sensitive, generated, computed, audit, relationship-owned, stale-version, cross-workspace, forged-handle, and many-to-many requests fail closed.

Independent mode commits one optimistic, audited child transaction at a time. Parent mode stages child intents, joins row errors into the parent summary with exact-field focus, and submits all related mutations through one atomic, retry-safe aggregate. This parent-submit endpoint persists the related child mutations only; it does not create or update the parent record. Circular child embedding and unavailable pinned versions fail closed, and static sample rows still block normal publication.

Release status (2026-07-16): Ready. The final isolated browser run proved row-scoped validation, first-invalid focus, unique labels/IDs, durable add/update/ remove with reload persistence, row-local actions, 403 denial, LTR/RTL isolation, and 390 px responsive rendering. Evidence is recorded in agent-findings/editable-grid-subform-release-qa/final-runtime-certification-1784233496.md.

Assemble a dashboard from admitted components

  1. Create a Dashboard through the native interface wizard and retain its actual draft coordinates.
  2. Add the layout and the specific Metric/Chart/grid controls the business question needs. A complete automatically generated domain dashboard is not assumed.
  3. Connect each control through its supported source/plan editor and review its fields, aggregate, identity and current adapter limits.
  4. Configure dashboard filters and interaction mappings explicitly through the current Filters/interaction surfaces.
  5. Inspect typed valid/empty/failure fixtures and responsive behavior. Save/validate/review impact/publish the actual candidate before inspecting the published ordinary-user experience.

The recipes below are manual composition patterns. They do not name built-in wizard recipes or guarantee automatically generated source wiring.

Dashboard composition recipes

Composition pattern Components to configure Interaction to author
Executive overview KPI Metric row + trend Chart + status Chart + exceptions Table Shared date/org filters; clicking charts opens supporting records.
Operational queue Queue Metrics + status/owner filters + DataGrid + RecordView drawer Grid selection fills RecordView; row actions advance/open/reassign.
Performance analysis Metrics + time Chart + category Chart + PivotGrid All controls share period and organization filters; points/cells drill to DataGrid.
Master-detail searchable DataGrid + RecordView + related Repeater/Subform Selecting a row updates details and related records without page navigation.
Hierarchy explorer Lookup/filter bar + TreeGrid + RecordView + child Metrics Selecting a tree node filters all detail controls to that branch.
Planning/bulk entry summary Metrics + EditableGrid + validation summary Grid edits recalculate metrics locally; Save all persists as one governed action.

Shared dashboard filters

Create explicit dashboard filters against governed compatible fields. Review the selected control, value type, targets and default; do not infer compatibility from a shared display label. Dependent filters additionally need an admitted parent relationship and an explicit option source/display mapping. The actual editor explains incompatible choices and preserves saved mappings for repair instead of guessing a new source.

Sources: dependent filter authoring, interaction source/target mapping.

Create dependent filters without code

Use dependent filters when one business choice narrows the next, such as Country → State → City.

  1. Connect the relevant Chart, Table, or DataGrid to one exact published record source. Confirm that Country, State, and City appear as executable, single-valued governed fields.
  2. In the dashboard Filters tab, create the Country filter and map it to the connected component. Leave its parent as Independent.
  3. Create the State filter. Under Make this filter dependent, choose Country as its parent.
  4. Under Choose where State options come from, select the shared component. When only one governed component is mapped by both Country and State, the designer selects it automatically.
  5. Optionally choose an Option display label such as State name. Only executable scalar fields from that same component are enabled; unavailable fields remain visible with a reason.
  6. Create the City filter in the same way, choosing State as its parent and the same governed component as its option source.
  7. Apply the interaction and review the plain-language summaries. The saved definition contains only stable filter, control, and governed field ids—no expression, SQL, source path, or event payload.

At runtime, State is disabled until Country has a value and City is disabled until State has a value. Changing Country clears State and City before new options load. Changing State clears City. Closing and reopening an option picker starts a fresh bounded request; a late response from an earlier choice cannot replace the current options.

The generated request is server-authoritative:

POST /api/screens/{screenKey}/dashboard-filter-options

It contains the exact published screen version, child filter id, exact authored parent values, optional search, and a limit. Users never configure this request. The server reloads the published dashboard, checks SCREEN_VIEW and DATA_MODEL_VIEW, verifies workspace and applied publication version, derives the source and governed member paths from the option-source component, and returns only bounded {value,label} options plus truncated.

Use relationship members safely

For modeled PostgreSQL record sources, a governed one-to-one chain such as order.customer.region.name can supply a filter field or option label when every hop is one-to-one and the terminal member is an executable scalar. The designer shows the business member; the server resolves the bounded join.

A one-to-many collection cannot be used directly as a scalar field. For an Order → Lines relationship, do not point a filter at order.lines.product and do not expect the browser to choose or flatten a line. Instead:

  • use Order Line as the source and traverse its single Order or Product reference; or
  • publish a governed flattened/aggregate view with the needed scalar result.

Unsupported, collection-valued, cross-source, unreadable, excessive-depth, or cyclic paths remain disabled and fail publication/query validation.

Country → State → City acceptance check

Before publishing a dependent-filter dashboard, perform this check in Preview or Live:

  1. Confirm Country is enabled, while State and City are disabled with readable parent-required reasons.
  2. Open Country with the keyboard, search, select Saudi Arabia, and confirm State becomes enabled while City remains disabled.
  3. Open State, select Riyadh Region, and confirm City becomes enabled.
  4. Open City, select Riyadh City, and confirm the active-filter summary and affected component count update.
  5. Change Country to United States. State and City must clear immediately; no Saudi/Riyadh option may reappear if an older request finishes late.
  6. Clear Country. State and City must return to disabled, clear states without changing unrelated filters, focus, selection, or scroll.
  7. Repeat at 390 px width. Check visible labels, focus order, Escape/close, screen-reader names, and disabled reasons.
  8. In agent mode, confirm the parent, option source, label field, picker, clear, and reset controls have stable domain-keyed data-agent-id values and that loading, ready, empty, error, and validation failures expose data-agent-state.

Configure a field for safe cross-dashboard matching

Before a published record field can participate in automatic cross-filter matching, give it an explicit business meaning in the data-model field Properties panel:

  1. Open the data model, select the record type, and select the field.
  2. In Business meaning, either enter an existing governed identity used by the same business concept, or enter a phrase such as Order fulfillment status under Suggest from a business phrase.
  3. Review the proposed stable identity and choose Use suggestion. The identity is stored with the field and does not change when its display name or technical key is renamed.
  4. Publish the data model, then reconnect or refresh the data component so its governed preview receives the identity.
  5. Open the dashboard Filters tab. Compatible Charts, Tables, and DataGrids now appear as plain-language targets; components with missing, different, many-valued, stale, or non-filterable fields remain disabled with a reason.

The designer never guesses compatibility from a label or technical path. Two fields match only when their published sources explicitly carry the same safe business identity, compatible value type, and scalar cardinality. Clearing the business meaning intentionally removes the field from automatic matching after the model is republished and the component is refreshed.

Cross-filtering and drill-down

Use the current chart-point-to-filter interaction editor for the supported interaction. Choose Source chart, Filter name, a compatible Filter control, target components/governed fields and the policy for clearing the point selection. Review the generated plain-language summary before applying. The editor's compatibility decisions govern which components may participate; an incompatible control is not fixed by copying a raw event payload.

For a grid-row detail panel, Metric supporting-record view, Pivot drill or Lookup dependency, use that control's own supported profile/action/filter contract. These are different interactions, not one universal wiring format. Source: actual chart interaction authoring.

Data freshness, performance, and trust

When designing a dashboard, review these operational concerns against the source/control capabilities; they are review questions, not a promise of automatic behavior:

  • Show source freshness and “Last updated” automatically.
  • Offer refresh policies: On open, Manual, Every N minutes from safe presets, or Event-driven where supported.
  • Share identical source requests between controls and cache governed results.
  • Push filters, sorts, grouping, and paging to the source when supported.
  • Estimate data volume and warn before expensive configurations.
  • Allow partial refresh of one widget without resetting unrelated selection/filter state.
  • Never expose secrets, SQL, access tokens, or unauthorized fields in authoring previews.
  • Test as role/persona so authors can preview partial permission and unauthorized states.

Configure governed refresh limits

Platform administrators configure refresh guardrails in conf/custom_config.properties with the screens.refresh.* settings. The designer reads the permission-checked GET /api/screens/refresh-policy endpoint and then:

  • disables refresh policies that the administrator has not allowed;
  • disables schedule presets faster than minimumScheduleMinutes;
  • estimates affected widgets from shared bindings;
  • estimates monthly requests from the selected schedule or the administrator's open/manual/event assumptions;
  • estimates request cost using estimatedCostPerThousandRequestsUsd;
  • warns at warningFanOut and blocks configurations exceeding maximumFanOut or monthlyRequestBudget; and
  • fails closed with a visible reconnect message when the policy cannot be loaded.

The estimate is planning guidance. Publish validation independently enforces the allowed policy, minimum schedule, maximum fan-out, and monthly request budget, and returns a control/property path for correction. It does not trust the browser's calculation. A host-specific source/dependency graph may identify additional fan-out, so publish validation remains authoritative.

Source of truth

  • Toolbox interaction and Container-only filtering: studio/frontend/src/features/designer/Toolbox.tsx
  • Palette groups, property composition, options, and defaults: studio/frontend/src/features/designer/propertySchema.ts
  • Toolbox descriptions and previews: studio/frontend/src/features/designer/controlHelp.ts
  • Node categories and renderer control mapping: studio/frontend/src/features/screens/nodeRegistry.ts
  • Layout-column behavior: studio/frontend/src/features/screens/islStyle.ts
  • No-code design requirements: docs/ui/no-code-authoring-principles.md
  • Event and options authoring requirements: docs/ui/interface-event-model-spec.md

Image delivery choice — Image, layout backgrounds and header logos

Select the control in Interface Designer. For an Image or App Header logo, open General; for a layout background, open Style. Set Optimize image delivery to Yes to use a smaller private display copy of a DMS image. No ISL is required. No is the default, including older interfaces without this property, and delivers the original image bytes without resizing, recompression or metadata rewriting. The Boolean choice persists with the control through save, Preview, publish and Live. It does not change external/static image URLs.

The choice applies to that control only. For example, a hero can use optimized delivery while a detail image uses original delivery from the same document. Original consumers share one concurrent transfer regardless of display size; optimized consumers share when their display profile also matches. Stored DMS files, versions and normal document downloads remain unchanged in both modes.

Optimized copies support JPEG and still PNG, preserve orientation/aspect ratio, never upscale, remove optional metadata and preserve actual transparency. Opaque images use JPEG quality0.82; transparent PNGs remain PNG. Ordinary images/backgrounds use the current viewport width and device pixel ratio to choose640/1280/2048; header logos use320. Transform input is limited to8MiB,8192px per dimension and16MP, with2MiB maximum output and two concurrent processing jobs per API instance. A declared unsupported/limit/busy refusal can attempt one authorized original delivery; access denial, missing/deleted content, invalid source or arbitrary server failure cannot trigger that fallback.

Private original delivery, including compatible fallback, accepts supported still JPEG/PNG/static WebP with at most16MiB,8192px per dimension and16MP. Unsafe/malformed/animated content becomes a generic unavailable state; a limit never silently switches original mode to optimization. Normal DMS file downloads retain their existing format/size behavior.

Configured pending Images show fixed-interface Loading / جارٍ التحميل while preserving their authored size; unconfigured/unavailable Images use the existing generic missing-image copy. Backgrounds retain authored colors/settings while pending, and headers retain brand/icon geometry. Identical Image/background/logo consumers share authorized work. Removing the final owner aborts unused work and releases its URL; hidden retained tabs and closed overlays do not load their private images, while tab field values remain mounted.

Fresh deliveries enforce current DMS permissions and existing approved CABINET sharing contracts. Optimized delivery rechecks access after processing and audits successful materialization with actor, document, workspace, resolved version, profile and representation. Already delivered mounted pixels cannot be recalled remotely on a later permission change; a new transfer is reauthorized. HTTP abort stops unnecessary client work, but the encrypted storage adapter may finish an already admitted bounded decrypt on the server. No public rendition cache or persisted derivative is created.

Try “document generation”, “integrations” or “first form”.