Editor Features
The Editor component is the most important and complex feature of the blong-browser framework. It
combines a schema-driven form, a configurable toolbar, a rich layout system, and a set of advanced
interaction patterns into a single composable component that covers the majority of entity editing
use cases.
This document is a feature guide: one section per capability, each with the goal it serves, the
props and schema keys that drive it, and — where one exists — the Storybook story that shows it
running. The interactive examples live in the Editor/… story group under
core/blong-browser/src/components/Editor/stories/, and the pictures of them are captured by
core/blong-browser/test/docs.play.ts; the loaded and empty forms at the top of the page are the
demo/blong-marine Coral entity, captured by demo/blong-marine/test/docs.play.ts.
The stories are runnable: cd core/blong-browser && npm run storybook serves them on port 6006 (the
conventions are in the Storybook pattern). Three
of them are also embedded below, live from the published Storybook — the toolbar, design mode
and the cascaded dropdowns — each showing its committed picture first and opening the running
component on a click. The rest are one section away from their story's name.
The Editor with a record loaded — a tabbed portal, the toolbar, and a form whose widgets are all derived from the model's schema: a text field, a select-button group, dropdowns, a number spinner, a checkbox, a date picker and a textarea, with the required fields marked from the schema's own rules.

For implementation reference see core/blong-browser/src/components/Editor/. For usage patterns see
Modular UI.
1. Load / Save Lifecycle
The Editor manages the complete load-edit-save cycle for a single entity.
Goal: Given an action name for loading and an action name for saving, the Editor handles all the async plumbing — showing skeletons while loading, tracking dirty state, enabling/disabling the Save button, and handling server-side validation errors.
Key props:
loadAction— method name whose result populates the formloadParams— static params for the load actionsaveAction— method name called on submitvalue— static initial value (skipsloadAction)onSave— callback fired after a successful save
The same Editor in its New state, before anything has been loaded or typed. The toolbar's Save and Reset buttons are present but disabled, which is the dirty-state plumbing this section describes:

2. Toolbar
The Editor renders a PrimeReact Toolbar above and/or below the form.
Goal: Provide standard Save / Reset / Edit toggle buttons with correct enable/disable states derived from form dirty state, plus extensible left and right button slots for realm-specific actions.
Key behaviours:
- In read mode with
editable: true: Edit (pencil) button - In edit mode: Save and Reset buttons (disabled when form is untouched)
toolbarprop — additional buttons on the left sidetoolbarRightprop — additional buttons on the right sidedesignable— adds a cog button that activates design mode- Save button shows a popover with server validation error summary
The Editor and Editor/TableToolbar stories cover the toolbar states: the Edit button in read
mode, the Save / Reset pair in both enabled and untouched states, and the extra left and right
button slots. The Toolbar story fills the left slot with four realm actions beside Save and Reset:

The same story, live — press any toolbar button and the editor behind it answers:
3. Validation
Goal: Provide immediate, precise feedback when the user makes an error — both from client-side rules derived from the JSON Schema and from errors returned by the server on save.
Sub-features:
- Client-side required — fields marked
required: truein the schema show inline errors on submit without a server round-trip - Server-side field errors —
{validation: [{field, message}]}in the server response pushes errors into react-hook-form; each error appears inline beneath its field - Server error summary —
error.printstring shown in an OverlayPanel anchored to the Save button
The Editor/Validation story exercises both halves: submitting an empty required field shows the
client-side rule, and a failing save shows a {validation: [{field, message}]} response pushed back
under the offending field with error.print in the popover.
The client half, photographed from that story: the required Name was cleared and the form submitted, so the rule appears beneath the field and the app raises its own summary toast:

4. Cards and Layouts
Goal: Organise fields into named groups (cards) and arrange those groups on the page in a configurable layout — without writing layout-specific JSX.
Cards
A card is a named group of fields rendered as a labelled container inside a PrimeFlex grid
column. Cards are defined in ICardConfig:
label— card headingwidgetsorfields— ordered list of field names from the schemaclassName— PrimeFlex column class (e.g.'col-12 md:col-6')permission— hide the card when the user lacks this permissionhidden— render fields as hidden inputs, visible in layout onlycollapsible— add a collapse toggle to the card headerwatch+match— conditional visibility based on form field values (see Master-Detail and Polymorphic Cards below)
Layout Types
| Type | Config shape | Description |
|---|---|---|
| Flat | an array of rows | Column array; stacked arrays place cards side by side |
| Tabs | {items: [...]} | Horizontal tab bar; each tab shows a set of cards |
| Steps | {type: 'steps', items: [...]} | Wizard-style; last step's Next button submits the form |
| Split | {type: 'split', panels: [...]} | A panel beside the content — the sidebar layouts |
The layout type is derived rather than declared twice: a bare array is flat, type: 'split' selects
the split layout, and an object carrying items is a tab or step layout depending on its type.
Tabs and split panels support component injection — an item can carry a full React component (e.g.
an Explorer) instead of a list of cards.
Each layout has a story: Editor/TabbedLayout, Editor/ThumbIndexLayout (tab orientation),
Editor/Explorer (the split layout, with an Explorer injected into a panel),
Editor/ResponsiveLayout and Editor/PortalComponent.
The tab layout on the Coral entity, from the Tabs story — layouts.edit is an object carrying
items here, where the flat layout is an array:

5. Schema-Driven Widget Resolution
Goal: Automatically select the correct input widget for each field from the JSON Schema type,
format, and widget.type property — so that no widget configuration is needed for standard fields.
The built-in registry (core/blong-browser/src/widgets/index.ts) maps a widget type to a component,
and a suite can add its own through registry.register(). The registered types are:
- Text and numbers —
input,text/textArea,number,integer,bigint,currency,percent,password,mask - Dates and times —
date,time,dateTime,dateRange - Choice —
boolean/checkbox,select,dropdown,dropdownTree,autocomplete,chips,multiSelect,multiSelectPanel,multiSelectTree,selectTable,multiSelectTreeTable - Structured —
table(an editable DataTable),navigator,json,component - Files —
file,image,imageUpload
resolveWidgetType() in Card.tsx picks one. The order is narrower than "format first":
- an explicit
widget.type format—date,date-time/dateTime,timetype === 'boolean'→booleanwidget.dropdown→dropdown; otherwisewidget.options→select- a field name ending in
Description→textArea type—integer,number,bigintanyOf— resolved from the first non-nullbranch- otherwise
input
There are two switches, not one. The one above runs when the schema is loaded (schema/registry.ts,
resolveWidget), and it is the one that reads the server's schema: an explicit x-widget.type
wins, then the JSON type (boolean, integer, number, bigint), then the first non-null anyOf
branch, then an enum becomes a select, and finally a field name heuristic picks date,
dateTime, time, password or textArea (a name containing Description or Notes). Whatever
it decides is stored on the enriched field. The second runs when a card renders (Card.tsx,
resolveWidgetType) and falls back through widget.type, format, type === 'boolean',
widget.dropdown, widget.options, a name ending in Description, the numeric types, anyOf, and
input.
The extension keys the first switch understands are declared in one place — x-filter,
x-filterable, x-sort, x-cards and x-widget — and an unknown x- key is reported rather than
silently ignored.
5b. Custom widgets and field-change events
A realm can supply its own widget through the editors prop of Form or Editor: a component that
receives Input, Label and ErrorLabel factories and declares the fields it owns in a static
properties array, so the layout treats those fields as one row. The Editor/CustomEditors story
shows the smallest real one — a period and a unit rendered together:

A widget talks back to the form with a method name rather than an emitter. methods on the form
maps a name to a function, and a field's widget.onChange: 'handleA' (or the form's onFieldChange
default) is dispatched before the value is written: the method receives {field, value, form} with
form.getValues/form.setValue, and returning false aborts the change while a thrown error is
logged and the change dropped. The Editor/Events story computes a read-only total from two fields
that way, and its EventsFormAPI variant shows a widget's visible/enabled subscribed to a value
path. A separate, global event bus (blongEvents, section 14) carries action lifecycle events and
is not the per-field mechanism.
6. Loading States
Goal: Provide visual feedback during data loading without layout shifts, so the user understands something is happening and does not interact with stale data.
While the loadAction is pending, each field renders an animated <Skeleton> placeholder at the
same size as the real input. The toolbar is disabled during loading.
The Editor/Loading story holds that state still — its coralCoralLoad never resolves — so the
skeletons are the whole picture, in the layout the fields will have:

7. Design Mode
Goal: Allow authorised users (e.g. system administrators) to rearrange the field layout, change widget types, and toggle field visibility at runtime — without a code deployment or development effort.
Design mode is activated by the cog button in the toolbar (designable={true}). While active:
- Cards and fields become draggable (dnd-kit, through
design/useDesignable.ts) - A
PropertyEditorside panel shows and edits the properties of the selected element DesignAddCardButtonandDesignAddFieldButtonadd new elementsDesignToolbarcarries save, undo and redo — the provider keeps a history of config revisionssaveConfig()hands the edited config to anonSavecallback supplied by the hostEditor.stories.tsxenters design mode throughinitialDesignMode
The persistence is the host's job, and nothing is persisted today: Editor wraps its content in
DesignModeProvider without an onSave, so saveConfig() returns immediately and the edits live
only in the provider's state for the lifetime of the page.
The Design story opens in design mode over the Coral entity — the card grips, the design toolbar
in place of Save, and the PropertyEditor on the right for the field the play function selected:

Live: the grips answer to a drag, and the property panel edits the field the story selected.
8. Master-Detail
Goal: Edit the selected row of an inline table directly in a detail card, without opening a separate page, for compact relational editing workflows.
A detail card sets watch: '$.selected.tableName'. Widget names in the detail card use the
$.edit.tableName.fieldName path convention. Changes update the in-memory row array; the parent
form's Save button persists the whole structure.
Polymorphic variant: multiple detail cards each with a match condition on the selected row — only
the matching card is shown at a time.
See the Editor/MasterDetail story, and Editor/MasterDetailPolymorphic for the match variant.
The picture is the first of those with its first row selected, so the detail card holds the row a
reader would otherwise have to imagine:

8b. Declared master-detail
The card above is hand-built. A model can declare the relationship instead, and the generator
expands it: IModelSpec.details takes one entry per child object, and the defaults turn each into a
sibling array property of the master's key, an editable table widget, a card and a tab in the edit
layout. The declarations in realm/blong-access/ are the reference
(details: [{object: 'credential'}, {object: 'role'}] on the user model).
Two behaviours follow from that shape and are worth knowing when writing a handler for it.
The child rows are read with the master: the generic database adapter discovers the detail
tables through their foreign keys and returns their rows as sibling arrays in get, persists them
on add, and replaces them on edit (delete-then-reinsert). A save therefore sends the whole
structure, and the validation for it is generated from the same declaration.
On the browse page, deleting a master refreshes the table: the default Delete action is declared
with refresh: true, which invalidates the find and get queries, and the adapter deletes detail
rows before their master so a foreign key does not block it. Inside an open form, deleting a row
from a detail table only removes it from the form array — nothing is persisted until the parent is
saved.
9. Cascaded Dropdowns
Goal: Filter a child dropdown's options based on the selected value of a parent dropdown, enabling hierarchical selection (e.g. continent → country → city) without any custom event handling.
A child dropdown widget declares widget.parent: 'parentFieldName'. When the parent value changes,
the child dropdown filters its options to entries whose parent property matches the new parent
value. The name says where the value is read — in a model that is the field's full path
(competition.sportId), because that is where the form stores it — and an option is matched under
the field's own name (sportId), the name the row and the dropdown answer use.
widget.optionsFilter is the explicit form for an option that carries the key under another name.
A pick the child already holds is dropped when the reader replaces that parent, and kept when the
form is merely loading the record it was saved in.
See the Editor/CascadedDropdowns story. Its three fields are the continent → country → city chain,
and the open city list holds the one city of the selected country rather than all ten; the
NestedCascade variant declares the same chain under a group, the shape a model produces:

The cascade is the part a picture cannot show: open Country, pick one, and the city list below it narrows to that country's cities.
10. Cascaded Tables
Goal: Filter a child table's rows based on the selected row of a parent table, enabling parent-child list views in a single page.
The child table widget declares widget.parent: '$.selected.parentTable' and
widget.master: {childKey: 'parentKey'}. Rows in the child table are filtered to those matching the
selected parent row.
See Editor/CascadedTables, and Editor/CascadedTablesVariant for the three-level case. In the
first, the document table holds the selected person's three documents and the attachment table that
document's two pages:

11. Polymorphic Layout (typeField)
Goal: Switch the active editor layout automatically when a discriminator field changes (e.g.
switching between 'personal' and 'corporate' layouts when the customerType field changes).
The typeField prop on the Editor watches a specific field; when its value changes, the Editor
selects the matching layout key (e.g. editPersonal, editCorporate).
Status: not implemented. typeField is not a prop of the Editor — the Editor/TypeField story
is a stub that shows the target data shape (a static type field over a tabbed layout) and says so in
its own header comment. What exists today is the mechanism the feature would build on: an explicit
layout key, chosen by the caller, with {mode}{Layout} fallbacks.
12. Static and Dynamic Pivot
Goal: Pre-populate an editable table with a fixed set of rows derived from either static reference data (static pivot) or a live dropdown list (dynamic pivot), so users edit per-row values rather than managing the row list itself.
Examples: a permissions matrix (one row per permission), a weekday schedule (one row per day).
- Static pivot —
pivot.examplesprovides the seed rows - Dynamic pivot —
pivot.dropdownnames a dropdown list whose entries seed the rows;pivot.joinmaps the seed key to the row key field, andpivot.defaultsseeds the cells of a row the first time it is created
Stored rows are overlaid onto the seed rows by matching every join pair, so a row that exists
appears filled and a slot that does not yet exist appears empty; saving a cell for a seed row that
had none creates that row.
Four limits are real rather than incidental. A pivot table has no Add, no Delete and no multi-select checkbox — its rows come from the declaration. A pivot whose editable cells are all toggles is toggle-only, with no row editor. A named pivot dropdown is loaded once through the dropdown registry, so rows are as fresh as that load. And writing a pivot needs a handler that reconciles the whole array: the generic CRUD adapter does not do it.
See the Editor/Pivot story, which shows both halves — a weekday schedule built from
pivot.examples, and a permissions matrix whose rows come from pivot.dropdown:

13. File Upload
Goal: Let a user pick a file — an image, a document — inside the form, with a preview where a picture makes sense.
What exists is the widget half, in core/blong-browser/src/widgets/:
file—FileWidget, a basic PrimeReactFileUploadwithcustomUpload.acceptandmaxSize(default 5 MB) come fromwidget, and the chosenFileis handed to the form throughonChange.image/imageUpload—ImageWidget/ImageUploadWidget,accept="image/*",maxSizedefault 2 MB, a preview through PrimeReactImage, andwidget.basePathto prefix a stored relative path. The upload variant accepts either a URL string or an array ofFileobjects.
Not implemented: the transport. There is no multipart/form-data path anywhere in the
repository, and no realm uses a file or image field yet, so a chosen File simply rides along
in the form value — what the receiving action does with it is the realm's decision. A form-aware
upload step is planned, not present.
14. Event Bus Integration
Goal: Allow external code (analytics, logging, toasts) to observe form interactions without prop-drilling.
blongEvents (core/blong-browser/src/lib/eventBus.ts) is a typed singleton: on(event, listener)
returns an unsubscribe function, and the dispatch wrapper emits action:before, action:success
and action:error with {method, params} plus {result} or {error}. The Storybook
withDispatch decorator uses this to show success toasts after mutations, and the Editor/Events
story subscribes to all three.
15. The form-based explorer
The generated browse page is an Editor in a split layout: a navigator widget on the left, a
table with a listAction in the middle, a detail panel on the right, and action buttons on the
editor's toolbar. The Editor/Explorer stories are that composition written out by hand, and they
supersede the older standalone Explorer component's stories for generated pages: the standalone
component is still there for a page that wants a table and filters without an editor around them.

16. What made it usable
Three defects in the generated editor were worth fixing at the framework level, because every page inherits them.
A keystroke re-rendered the world. handleFormChange called setLocalValue and setIsDirty on
every change, which re-rendered the editor, the form and every widget. Neither call was needed: the
dirty flag comes from the form library through onDirtyChange. Two regression tests now pin it —
typing in one field must not re-render a sibling widget.
Saving ignored what the server said. The save path wrote the value the client had just submitted
and then re-read the form, discarding whatever the server added (timestamps, computed fields). It
now uses the response: const savedValue = result ?? formValue, and the form rebases on it.
One context carried everything. Every consumer subscribed to a context that held the form values, the errors, the table selections and the loading flags, so any change re-rendered all of them. The context is split now: a stable one for the schema, the cards and the callbacks, and a slower one for the selections, read-only and loading state, with the values reached through a getter instead of a subscription.