# 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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/panels` owns the version-1 widget/control registries, factories, parser,
  analyzer, rule checks, formatting and reference transformations. Existing scalar forms
  and legacy `multiline`/static-option definitions remain compatible.
- `@bytesmap/flow/panel-state` owns initialization, validation, selection identity and
  submission resolution. API inputs cannot replace the saved workflow or its bindings.
- `@bytesmap/ui/patterns/panel-widget`, `panel-field` and `panel-runtime` render that
  model. `panel-record-presentation` owns record identity and field rendering;
  `panel-display-settings` owns their shared configuration. `panel-widget-library`,
  `panel-widget-settings` and `panel-field-settings`
  provide its shared editors. App code supplies metadata, navigation and transport.
- `panels.catalog` returns 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](https://bytesmap.com/docs/automate/workflows.md). 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.