Components and forms
Display records, collect typed inputs and connect explicit actions.
Panels compose a reusable interface over saved queries and published workflows. A query provides data, widgets display or collect values, and an explicit submission runs the connected workflow. The same definition and renderer power the editor, dashboard views and SDK hosts. Business concepts such as customers, support cases and account upgrades are authored configurations, not special widget types.
Widget library
| Widget | Configuration and behavior |
|---|---|
| Table | Query result, explicit record key, visible columns, formatting, search, sorting, pagination and row density. |
| Record list | List or responsive cards, identity/cover images, status labels, detail fields, search, pagination and record actions. |
| Record details | A bound record with optional identity header, labelled values, display formats and configurable row/grid layout. |
| Form | Typed inputs grouped in sections, defaults, validation, conditions, query filters or a published workflow submission. |
| Action button | Published workflow, connected view, or supported page effect; editable label and button style. |
| Metric | A bound value with number/currency/percentage/date formatting and an optional caption. |
| Progress | Explicit value and maximum bindings with a caption and display format. |
| Text | Fixed or bound content, with optional Markdown rendered by the shared safe Markdown component. |
| Section | A heading and description to organize a panel. |
Every widget has a title, optional description, visibility/interaction rules, width, content-fitting or explicit height, and a card/plain surface. Widgets can be reordered, resized, duplicated and removed. The editor supports undo/redo, keyboard arrangement and a phone preview. Narrow layouts adapt without overwriting the saved desktop layout.
Dashboard app items fit their view content by default, with one page scroll and
paginated records. Choose a height explicitly to create a bounded viewport;
the saved item then uses heightMode: 'fixed', with h in 72px units.
Fit height to content restores heightMode: 'content'. Width-only changes
preserve that choice. A widget's explicit height is in pixels and includes its
header; charts use the remaining plot space. Horizontal bars use a quantitative
x and categorical y; unambiguous older definitions with swapped axis types
are normalized without changing their data or chart mark.
Charts continue to use the existing chart engine and dashboard grid. A dashboard can place any supported chart beside these panels; widgets do not introduce a second query or chart execution engine.
Table search, sorting and pagination apply to the loaded result. Use saved query parameters and query operators to filter or order the complete database result. A truncated result remains identified as such; client-side search cannot discover rows that were never loaded.
Lists and record details share PanelRecordIdentity: title, subtitle, avatar/cover image,
image shape and a status badge. Lists offer compact/comfortable density and automatic or
one-to-four card columns; detail grids offer one-to-three columns. These settings adapt to
the containing panel's width, including narrow modals, without rewriting the saved layout.
Display fields share PanelFormat and the same UI renderer across tables, collections and
details. Formats include numbers, dates, currency, percent, JSON, status badges, images and
links. Badge mappings give exact source values readable labels and semantic colors; unknown
values keep their text and default color. Empty-value labels and hiding empty detail fields
are optional. Formatting never changes raw records, selection keys or workflow inputs.
Numbers and dates use the current locale, preserving precise decimal/bigint strings.
Images retain their geometry while loading or failing and accept only safe web/relative
URLs. Detail links open safely; selectable rows display the link value without nesting a
second interactive target inside the record selection button.
Collections expose configured menu actions through a visible per-record button as well as right-click and Shift+F10. Chart and record actions use the same interaction dispatcher for filters, saved views in a modal/drawer/page, and published workflows. The menu button does not run a primary action. A custom panel combines record details, forms and buttons using the same component definitions as a dashboard View.
Data-entry controls
| Group | Controls |
|---|---|
| Text | Text, long text, email, URL |
| Numbers | Number, slider |
| Choices | Dropdown, multiple choice, radio group, checkbox, switch |
| Dates | Date, date & time, time |
| Structured data | JSON record or list with an explicit value schema |
Fields define their names and types independently from their presentation. Choosing a
published workflow offers Create fields from workflow, which copies its declared
input schema and connects those bindings. Field names never infer business meaning:
an input named email remains a string until its author chooses the email control.
Renaming a field updates references to it; duplicating a widget updates its internal
references without rewriting literal data.
Each field can have help text, a placeholder where supported, width, required/read-only
behavior, an initial binding, compatible control selection and typed constraints.
Adjacent inputs with the same optional section share a heading and a responsive field
grid. Field order, visibility, values and submission rules remain unchanged. Forms also
configure submit-button style and action alignment independently from workflow behavior.
Text limits, numeric ranges, list limits and custom validation are checked both in the
browser and by the shared submit operation. Calendar values use strict parsing; exact
decimal and large integer strings retain their precision.
Choices can come from a static label/value list or a connected query with explicit value and label columns. Values retain the declared scalar type; duplicate or invalid choices are excluded and submissions must use available choices. Query output metadata populates column selectors without executing data. When native query output cannot be determined statically, enter its exact column names.
Visibility, disabled, required and custom-validation conditions reuse the workflow rule engine, including nested AND/OR/NOT predicates. Conditions can bind form values, record selections, query results and trusted user context. Incomplete rules remain editable, appear in Checks and prevent execution/publication. Temporarily unfilled or invalid typed values do not crash visibility evaluation.
Required booleans require a valid boolean; false is a valid value. To require consent
or another specifically true value, configure a validation rule that checks true.
Hidden or read-only fields use their configured defaults on submission, so a previously
editable stale value is not silently submitted.
Authoring flow
- Open Views → New view. Its Flow canvas shares the source, component and workflow nodes. Switch to Design to arrange components. The searchable component library shows visual silhouettes; click a component or drag it into place.
- Use Data flows to connect saved visual or native queries. Choose their result steps and bind parameters. Only source/schema metadata is loaded during setup.
- Select a component to edit Content, Appearance, Actions or Rules. Display fields expand individually and can be reordered. Form inputs have a focused editor with Back navigation. Appearance uses the shared UI tokens; no component-specific theme is needed.
- Under Actions, choose a form's On submit behavior. Apply query filters refreshes the selected datasets, or the queries that depend on that form. Run a published workflow pins an action revision and maps its inputs. Workflow forms can show a custom success message or reset after success; a reset button is optional for either behavior.
- Use a component's preview action or Preview view to open the preview dialog. Save the panel before Load data or a real workflow test. Editing, saving, arranging and switching between Flow and Design do not execute queries or actions. Unsaved previews let authors inspect controls with execution disabled.
- Add the saved View to a dashboard or target it from an interaction. Creating a View from a dashboard retains its parent and saves/attaches back to that dashboard. Publish the dashboard to approve its bindings for viewers and operators.
Dataset dependencies follow bindings rather than visual order. A selected record can initialize fields and load dependent queries. Responses belonging to an older selection are discarded. Normal refreshes preserve edited field values; changing record selection initializes the new record. A successful action uses the shared dashboard refresh cycle so sibling charts and panels see the committed change.
Shared contracts and access
@bytesmap/flow/panelsowns the version-1 widget/control registries, factories, parser, analyzer, rule checks, formatting and reference transformations. Existing scalar forms and legacymultiline/static-option definitions remain compatible.@bytesmap/flow/panel-stateowns initialization, validation, selection identity and submission resolution. API inputs cannot replace the saved workflow or its bindings.@bytesmap/ui/patterns/panel-widget,panel-fieldandpanel-runtimerender that model.panel-record-presentationowns record identity and field rendering;panel-display-settingsowns their shared configuration.panel-widget-library,panel-widget-settingsandpanel-field-settingsprovide its shared editors. App code supplies metadata, navigation and transport.panels.catalogreturns widget types, field controls, display formats and factory defaults. HTTP/native SDK, CLI, MCP and assistant tools use the same operation catalog and platform implementations; there is no separate widget execution path.
Project/item grants apply to reusable queries, panels and workflows. A published dashboard freezes its approved dependencies and workflow revisions. Viewer/Operator/Editor/Manager access and individual sharing use the existing resource-grant system. Tokens and MCP permissions intersect current user access. Revocation and stale publications are checked again at execution. Widget conditions are presentation and input-validation rules; database ownership/transition rules belong in workflows, with database permissions/RLS still effective.
The widgets do not expand native write capabilities. PostgreSQL single-record insert/update uses the existing checked transaction and stale-record rules. HTTP and notification effects, automatic conditions and scheduling use workflow automation. Bulk/delete/ upsert nodes, file uploads, arbitrary scripts and third-party widget plugins are separate extensions, not implied by structured input support.
Extending and verifying
Add a widget/control to the headless registry and parser first, then its analyzer/state behavior, shared renderer and settings. Add no API-specific or app-specific copy of the model. Test compatibility, typed values, invalid states and permissions before exposing it through the catalog. Binding and rule editors should be reused.
panel-widgets.test.ts in Flow tests the protocol, precision, conditions, choices,
dependency ordering and reference transformations. Platform tests exercise real isolated
PostgreSQL execution, publication, scope revocation, invalid submissions and request replay.
Native SDK tests consume the same catalog and submit operations.
Browser tests cover authoring, every control's typed submission, query metadata without execution, save/reopen, conditional editing, drag/resize, accessible errors and dashboard navigation/refresh. Screens are reviewed in Light, Dark and Dim, on narrow layouts and with keyboard focus. The fixtures never connect to a user's database.