Skip to main content

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.

The Editor with a Coral record loaded

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 form
  • loadParams — static params for the load action
  • saveAction — method name called on submit
  • value — static initial value (skips loadAction)
  • 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:

The Editor on a new, empty form


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)
  • toolbar prop — additional buttons on the left side
  • toolbarRight prop — additional buttons on the right side
  • designable — 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 editor toolbar with four realm actions in its left-hand slot

The same story, live — press any toolbar button and the editor behind it answers:

Editor/Toolbar — the left slot filled with four realm actionsOpen in Storybook

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: true in 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.print string 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:

A required field showing its inline error and the validation 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 heading
  • widgets or fields — ordered list of field names from the schema
  • className — PrimeFlex column class (e.g. 'col-12 md:col-6')
  • permission — hide the card when the user lacks this permission
  • hidden — render fields as hidden inputs, visible in layout only
  • collapsible — add a collapse toggle to the card header
  • watch + match — conditional visibility based on form field values (see Master-Detail and Polymorphic Cards below)

Layout Types​

TypeConfig shapeDescription
Flatan array of rowsColumn 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:

A form under a horizontal tab bar with three tabs


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":

  1. an explicit widget.type
  2. format — date, date-time / dateTime, time
  3. type === 'boolean' → boolean
  4. widget.dropdown → dropdown; otherwise widget.options → select
  5. a field name ending in Description → textArea
  6. type — integer, number, bigint
  7. anyOf — resolved from the first non-null branch
  8. 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 custom editor rendering a number and a unit side by side in one row

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:

Every field of the form replaced by a skeleton placeholder


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 PropertyEditor side panel shows and edits the properties of the selected element
  • DesignAddCardButton and DesignAddFieldButton add new elements
  • DesignToolbar carries save, undo and redo — the provider keeps a history of config revisions
  • saveConfig() hands the edited config to an onSave callback supplied by the host
  • Editor.stories.tsx enters design mode through initialDesignMode

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:

Design mode: gripped cards and a property panel open beside the form

Live: the grips answer to a drag, and the property panel edits the field the story selected.

Editor/Design — card grips and the property panel, runningOpen in Storybook

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:

A table and a detail card editing the selected row

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:

Cascaded dropdowns with the city list filtered to the selected country

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.

Editor/CascadedDropdowns — continent, country and city, filtering each otherOpen in Storybook

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:

Three tables, each filtered by the selection in the one before it


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.examples provides the seed rows
  • Dynamic pivot — pivot.dropdown names a dropdown list whose entries seed the rows; pivot.join maps the seed key to the row key field, and pivot.defaults seeds 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:

A weekday schedule and a permissions matrix, each seeded from a different source


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 PrimeReact FileUpload with customUpload. accept and maxSize (default 5 MB) come from widget, and the chosen File is handed to the form through onChange.
  • image / imageUpload — ImageWidget / ImageUploadWidget, accept="image/*", maxSize default 2 MB, a preview through PrimeReact Image, and widget.basePath to prefix a stored relative path. The upload variant accepts either a URL string or an array of File objects.

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.

The explorer: a category tree, a table and a detail panel under the editor toolbar

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.