Modular UI
How to wire blong-browser into a suite and write UI pages for a realm.
See Browser UI for the concept overview.
Adding blong-browser to a Suite
Include the blong-browser realm in the suite's browser.ts entry point alongside the application
realms:
// browser.ts
import {browser} from '@feasibleone/blong';
import pkg from './package.json' with {type: 'json'};
export default browser(blong => ({
url: import.meta.url,
pkg: {name: pkg.name, version: pkg.version},
children: [
async function ui() {
return import('@feasibleone/blong-browser/browser.ts');
},
async function marine() {
return import('./marine/browser.ts');
},
],
config: {
default: {
ui: {},
marine: {},
},
},
}));
The blong-browser realm automatically registers the portal shell, auth handling, backend adapter, storage adapter, and (in storybook/integration environments) the mock adapter. No explicit initialisation is needed.
Branding the Portal
A deployment belongs to somebody, and three places say so: the login screen, the mark at the left of
the menubar, and the empty state the portal draws while no page is open. All three read one block,
inside the inner ui.portal.portal key — the same placement profile has, and not a sibling of it
(D-011):
// suite/blong-suite/browser.ts
config: {
default: {
ui: {
portal: {
portal: {
title: 'Blong Marine',
brand: {
logoUrl: `${import.meta.env.BASE_URL}manta.png`,
orgTitle: 'Feasible One',
orgIcon: 'pi pi-building',
},
},
},
},
},
},
Every field is optional and every one is a value rather than an import: blong-browser ships no
asset of its own, so a suite that omits the block looks exactly as it did before branding existed.
logoUrl (or logoIcon, a PrimeIcons class) is drawn at the height the menubar's own content sets
(--blong-portal-brand-height), so the bar keeps its height whatever the file's pixel size, and the
same file is drawn large in the empty state beside title and the organisation.
Two sources feed those readers, and the difference is deliberate: the login screen paints before a
session exists, so it reads the static browser config, while the menubar and the empty state read
the merged portal config that portalConfigGet composes after login. A new provider key
therefore has to be named in mergePortalConfigs (core/blong-browser/src/portalConfig.ts) as well
as in IPortalConfig, or the shell silently renders without it (@@F-677).
Assets live in the package's public/ folder — vite build copies it to the bundle root, and the
Storybook helper serves it too — and are named through import.meta.env.BASE_URL, which is /s/ in
an app build and / in Storybook.
Contributing Pages from a Realm
A realm contributes pages by placing handler files that end with .component in its layer. The
portal orchestrator discovers them automatically by file-name pattern.
Minimal component handler
// marine/component/marineCoralBrowse.component.ts
import {handler} from '@feasibleone/blong';
export default handler(() => ({
'marine.coral.browse': async () => ({
title: 'Corals',
permission: 'marine.coral.browse',
component: async () => {
const {CoralBrowse} = await import('./CoralBrowse.js');
return CoralBrowse;
},
}),
}));
For the common case of CRUD pages, use the Model System instead — see Schema based UI.
Adding menu items
Place a .portal file in the component layer. The portal orchestrator imports all *.portal files
to build the navigation menu.
// marine/component/marine.portal.ts
import {handler} from '@feasibleone/blong';
export default handler(({handler: {portalMenuItem}}) => ({
async 'marine.portal.params'() {
return {
menu: [
{
title: 'Marine',
items: [
await portalMenuItem('marine.coral.browse'),
await portalMenuItem('marine.family.browse'),
],
},
],
};
},
}));
Using Editor Directly
For pages that need custom logic beyond what the model system provides, use the Editor component
directly in a React component:
import {Editor} from '@feasibleone/blong-browser';
import type {IEnrichedSchema} from '@feasibleone/blong-browser';
export function CoralOpen({schema, coralId}: {schema: IEnrichedSchema; coralId: number}) {
return (
<Editor
schema={schema}
cards={{
main: {
label: 'Coral Details',
widgets: ['coral.coralName', 'coral.familyId', 'coral.maxDepth'],
},
notes: {
label: 'Notes',
widgets: ['coral.description'],
className: 'col-12 md:col-4',
},
}}
layouts={{edit: ['main', 'notes']}}
loadAction="marine.coral.get"
loadParams={{coralId}}
saveAction="marine.coral.edit"
editable
/>
);
}
Using Explorer Directly
The standalone Explorer is a table, a filter panel and a toolbar without an editor around them.
For a generated browse page the composition to follow is Editor in its split layout — a
navigator widget, a table with a listAction and a detail panel — which the Editor/Explorer
stories write out and which the model's browse page builds. The widget catalogue, the pivot and
master-detail mechanics are in the editor features concept; the
declaration that generates the pages is in the model patterns.
import {Explorer} from '@feasibleone/blong-browser';
export function CoralList({schema}: {schema: IEnrichedSchema}) {
return (
<Explorer
schema={schema}
listAction="marine.coral.find"
selectionMode="single"
toolbar={[
{
label: 'Create',
icon: 'pi pi-plus',
action: 'marine.coral.new',
permission: 'marine.coral.new',
},
]}
/>
);
}
Layout Types
Flat layout
layouts={{ edit: ['main', ['contacts', 'notes']] }}
// main = full width; contacts + notes = stacked in second column
Tabbed layout
layouts={{
edit: {
items: [
{id: 'basic', label: 'Basic', icon: 'pi pi-id-card', widgets: ['main']},
{id: 'contacts', label: 'Contacts', icon: 'pi pi-phone', widgets: ['contacts']},
],
},
}}
Steps layout
layouts={{
edit: {
type: 'steps',
items: [
{id: 'step1', label: 'Identity', widgets: ['identity']},
{id: 'step2', label: 'Details', widgets: ['details']},
{id: 'step3', label: 'Review', widgets: ['review']},
],
},
}}
Sidebar (ThumbIndex) layout
layouts={{
edit: {
orientation: 'left',
items: [
{id: 'groupA', label: 'Group A', icon: 'pi pi-cog', widgets: ['card1', 'card2']},
{id: 'groupB', label: 'Group B', icon: 'pi pi-user', widgets: ['card3']},
],
},
}}
Accessing Dispatch and Schema
Inside a React component rendered by blong-browser, use the context hooks:
import {useBlong} from '@feasibleone/blong-browser';
const {dispatch, schemaRegistry} = useBlong();
// Call any registered handler
const result = await dispatch('marine.coral.find', {coralName: 'Brain'});
// Get enriched schema for an object
const schema = await schemaRegistry.resolve('marine.coral');
Test runs console
A realm can contribute an in-app test console: TestRun renders the run model, and TestRunPage
adds a catalog picker with browser and server hosts. The page is linked only under the test-ui
intent. See Test runs for the catalog, transport and server configuration.
Storybook Pattern
Every package that renders components ships a Storybook, and it is the live half of these docs:
a story is a running component with its fixture data, where a page here can only describe one. Run
the one that belongs to the package you are reading about — core/blong-browser for components and
widgets, demo/blong-marine or suite/blong-suite for whole realms, tools/blong-log for the log
viewer:
cd core/blong-browser && npm run storybook # port 6006
cd demo/blong-marine && npm run storybook # port 6007
The stories those commands serve are also published beside these pages, from the same origin, so a page can embed one and the reader gets the component running rather than a picture of it:
Embedding a story
A page embeds a story with one tag, and no import — docs/blong/src/theme/MDXComponents.jsx
registers it for every page, docs and blog alike. site is one of the sites in
docs/blong/storybook-sites.json and id is the story id Storybook puts in its own URL
(?path=/story/<id>).
<StorybookStory
site="browser"
id="editor--toolbar"
title="The Editor's toolbar"
/>
| Attribute | What it does |
|---|---|
site | Which published Storybook to read the story from. Required. |
id | The story id, as in ?path=/story/<id>. Required. |
title | Caption under the frame, and the frame's accessible name. |
height | Live frame height, a CSS length. Defaults to 480px, or 640px with chrome. |
globals | Storybook globals to open the story from, e.g. theme:wood,language:bg. |
chrome | Show Storybook's own UI — sidebar and story toolbar — instead of the bare story canvas. |
poster | A picture to show until the reader asks for the live story, which then opens on a click. |
Three of those are worth a sentence each.
globals is how a page shows a variant rather than a default. The same story opened at
theme:wood is the wood skin of the same editor, language:bg renders its toolbar in Bulgarian and
direction:rtl mirrors the layout — so a page about a variant embeds the variant instead of
describing where to click to see it. The value is the same one a Storybook URL takes, and it
outranks the choices a reader's browser has stored from an earlier visit.
poster is the honest default on a heavy page. Given one, the embed shows the committed
screenshot the page already has and opens the story on a click: the reader is not made to wait for a
Storybook frame to decide whether they want it, and a build with no Storybook staged still shows a
picture. The published trees are not committed — npm run deploy stages them, a plain
npm run build does not — so a page that shows nothing but a live frame is a page that renders an
empty box in a docs-only build.
The poster is drawn at the picture's own shape, not at height: height is the live frame's,
and a poster squeezed into it was cropped left and right on every wide screenshot, which is how a
poster stopped being the page it claimed to show. So a picture is committed at the shape it will be
read at, and height is chosen for the story that replaces it — a frame shorter than the poster is
how a section jumps when the reader clicks.
The poster is written as an import rather than a path, because Docusaurus copies an image into the build only when something imports it:
<StorybookStory poster={require('./img/editor-toolbar.png').default} … />
A plain poster="./img/editor-toolbar.png" looks right and 404s — the build has no such file —
which the docs verify run reports as an image that did not load.
chrome is for the page about the toolbar. The story toolbar is Storybook's own UI, outside the
story canvas, so the only way to show it is to embed the manager rather than the frame. Use it in
the pages that document the toolbar, and leave it out everywhere else: the canvas is what the
application looks like.
Publishing
The sites, their packages and their build commands are the register
docs/blong/storybook-sites.json; staging builds each one and copies it into
docs/blong/static/storybook/<name>/, which Docusaurus serves verbatim under /storybook/<name>/:
cd docs/blong
npm run stage-storybook # build and stage every site
npm run stage-storybook -- --only browser # one site, which is what a page about a widget needs
npm run serve # /storybook/browser/iframe.html is live
npm run serve here is not docusaurus serve, and the difference matters the moment a page embeds
a story: docusaurus serve rewrites /storybook/<name>/ to /storybook/<name> and
iframe.html?id=… to iframe, so a published Storybook's relative bundles resolve one directory
too high (every script 404s) and the preview is handed a URL with no story id (nothing renders).
npm run serve is blong-dev docs serve, which serves the build the way the published site does;
npm run serve:docusaurus keeps the Docusaurus one for anything that does not embed a story.
Two sites rather than one composed build, because a Storybook has exactly one preview file: a
component story is rendered by this package's preview (its in-file withDispatch fixtures, no
platform) and a model page story by a realm's (a platform, a mock adapter, the toolbar). Composing
them would render one of the two against the wrong fixtures — so the split follows the two previews
the packages already have.
Staging also checks every embed: each <StorybookStory> in the docs and the blog has to name a
known site and a story id that the staged site's own index.json serves, so a story renamed in a
package fails the publish rather than leaving a reader with an empty frame.
Two Storybook patterns exist:
Component-level stories (blong-browser internal)
Stories mock the dispatch function to develop and test individual components in isolation. Use the
withDispatch decorator from .storybook/dispatch.js:
// CoralOpen.stories.tsx
import {withDispatch} from '../../../.storybook/dispatch.js';
import {coralEditorFixture, coralStoryValue} from '@feasibleone/blong-marine/meta/storybook.js';
export default {
title: 'marine/CoralOpen',
decorators: [
withDispatch({
coralCoralGet: () => Promise.resolve(coralStoryValue),
coralCoralEdit: params => Promise.resolve(params),
}),
],
};
export const Default = {
render: () => (
<Editor
schema={coralEditorFixture.schema}
cards={coralEditorFixture.cards}
loadAction="coralCoralGet"
saveAction="coralCoralEdit"
editable
/>
),
};
Model page stories (realm package)
For end-to-end model page stories, use the page() / portal() helpers from
@feasibleone/blong-browser/storyHelper and the preview factory defineBlongStorybookPreview,
composing the realm's composed entry (index.browser.ts, which carries the portal port). One
line is the whole preview — the factory owns the toolbar, its persistence and the decorators:
// .storybook/preview.tsx
import {defineBlongStorybookPreview} from '@feasibleone/blong-browser/storybook.tsx';
import browser from '../index.browser.ts';
export default defineBlongStorybookPreview(browser, {backend: true});
Then stories use the page() helper:
// coral/Coral.stories.tsx
import {page} from '@feasibleone/blong-browser/storyHelper';
export const CoralBrowse = page('marine.coral.browse');
export const CoralOpen = page('marine.coral.open', 1);
export const CoralNew = page('marine.coral.new');
export const CoralOpenSplit = page('marine.coral.open', 1, {layout: 'editSplit'});
defineBlongStorybookPreview also accepts {decorators} instead of a browser entry — that is what
blong-browser's own preview passes (withDispatch), and it is how the presentation items below
reach a component story that has no platform. Omit backend: true for those stories: without a
backend adapter there is nothing to point at a gateway.
The story toolbar
The factory installs five Storybook globals, each remembered in localStorage so a reload keeps the
state a reviewer left behind:
| Item | Values | What it drives |
|---|---|---|
Backend | Mock / Live (JSON-RPC) / Live (MLE) | Where the model pages read their data |
Role | the roles of the storybook: section | Which role the live gateway is reached with |
Theme | every THEME_OPTIONS entry | useAppStore.setTheme — the portal's theme switcher |
Language | en, bg by default | useAppStore.setLanguage |
Direction | LTR / RTL | IThemeSelection.direction, so <Theme> flips |
The presentation items are applied through the store rather than a prop, because a platform-loaded
story has no prop to write to: withBlong renders the container the platform built, and <Theme>
lives inside it. Only a choice the reviewer changed is applied (changedStorybookGlobals), so a
story that sets its own args.lang or parameters.theme keeps it until someone uses the toolbar.
Every item is a plain Storybook global, so a state is scriptable — this is how the docs' own screenshots and any Playwright run over Storybook reach a state without clicking:
http://localhost:6007/?path=/story/subject-object--browse&globals=backend:jsonrpc;role:Guest
Mock or live
Backend: Mock is the default: the storybook intent activates the backend adapter's mock, so
every model handler answers from meta/fixture/<subject>Fixture.ts and nothing needs a server.
The two live values load the realm without that mock and switch the adapter to storybookJsonrpc /
storybookMle respectively, so the platform's model handlers travel to a real gateway. A Storybook
dev-server plugin (src/storybookBackend.ts, mounted by defineBlongStorybookMain) supplies what a
story otherwise lacks — a session:
GET /__blong/storybook?role=R&mode=Msets the cookies that tell the following/rpccalls which role and transport they belong to (the plugin cannot sniff that without consuming the request body), and answers with the role's credentials when the mode ismle.Live (JSON-RPC)speaks plain JSON-RPC to the plugin, which logs in as the role's seeded user, adds the bearer token and decrypts the gateway's MLE-encrypted response. Nothing in the page holds a token, and the plugin re-authenticates near expiry on its own.Live (MLE)keeps the page's own encryption: the story logs in with the role's credentials through the platform's own codec, so the key pair the page generated is what signs and encrypts, and the session renews itself like an application's would. The story is held back until that login completes — rendered first, it would fetch without a session, take a 401 and stay empty.
A token is deliberately not minted by the plugin for the page: the gateway encrypts the response to every login, so a token whose keys are supposed to travel per request in the JWE header cannot be read back out of it (measured against a running gateway, not assumed). The reviewer still never sees a login screen — the login is the decorator's, not theirs.
Which users the roles mean, and which gateway is addressed, come from .blong_devrc:
storybook:
target: http://localhost:8080
roles:
Admin:
user: testAdmin
password: testPassword
Operator: opsUser
Without that section the built-in defaults apply: http://localhost:8080 and the seeded test users
Admin/testAdmin, Manager/testManager, Guest/testGuest (password testPassword). The
endpoint is loopback-only and is mounted by the dev server, never by a build — and it does hand the
mle mode's credentials to the page, so point storybook.target at a gateway whose credentials you
would be willing to put in a .blong_devrc.
A realm that wants a role to see something has to grant it: the template's
meta/db/accessAuthorizationMerge.yaml — a production seed, because the roles themselves are
production — gives Admin the full Manage capability, Manager read + edit and
Guest/Customer read-only. All three also carry subject.object.schema — without
it a read-only role gets a 403 for the page's own schema and renders a blank screen rather than a
smaller one, which is how the Role item earns its place: a Guest who can browse but is refused a
save is a different story from an Admin who can do both.
Internationalisation
Translation, the language switcher, PrimeReact locales and the Storybook lang arg have their own
page — see internationalisation. In short: a string child is both the key and the
English fallback, a realm declares its portal.languages and portal.translations, and
PrimeReact's own widget strings arrive through IThemeConfig.languages.
Testing
Add an interaction test with a play() function:
Default.play = async ({canvasElement}) => {
const canvas = within(canvasElement);
// Wait for load
await canvas.findByDisplayValue('Brain Coral');
// Click Edit
await userEvent.click(canvas.getByTitle('Edit'));
// Change a field
await userEvent.clear(canvas.getByLabelText('Coral Name'));
await userEvent.type(canvas.getByLabelText('Coral Name'), 'Star Coral');
// Save
await userEvent.click(canvas.getByTitle('Save'));
};