React Dashboard Widget Platform

Standard React widget composition, identity, layout, drafts, help, and interaction contracts.

Details

The widget platform is the standard composition model for React dashboard views. It preserves extensive personalization without turning every shareable App into an unrelated page implementation.

Three identities

Never collapse these identities into one namespace:

1. Widget type identifies a reusable renderer and its typed contract, such as Quick Capture.
2. View slot identifies the purpose a widget serves in one view, such as the Journal capture role.
3. Widget instance identifies one placement, layout record, and local-state owner.

A required slot may accept a replacement renderer that satisfies the same contract. Requiredness therefore attaches to purpose, not permanently to a default widget type.

Placement availability

Each slot is one of:

• required — removing it would make the view unusable or violate its core purpose;
• default-on — present in the recommended layout but removable; or
• default-off — available from the catalog without occupying the initial layout.

Journal requires Capture and Day Timeline. Running Notes is default-on.

Renderer boundary

Renderers receive typed UI input and emit declared intents. Local presentation state can remain local. Outward reads, mutations, navigation, downloads, or external actions declare semantic effects so the host can enforce mode safety without guessing from buttons, keyboard events, timers, or fetch calls.

Layout and personalization

Dashboard Core owns layout editing, constraint enforcement, collision feedback, reset, undo/redo, and portable personalization patches. The grid library remains an implementation detail rather than part of persisted view state. The Customize view entry control lives in the app shell navbar and activates when the mounted view registers a customize session, so grid views everywhere share one entry point while other surfaces leave it disabled.

Desktop customization uses the grid. Mobile uses document flow and drag-reordering of a canonical sequence. Responsive changes may reflow or scroll content, but they must not silently remove primary controls or hide that a capability exists.

WidgetHost supplies the renderer's measured content-box width in presentation.width; the grid estimate is only a fallback before a positive measurement. The frame reuses the shared container-measurement hook, so opening a sibling assistance dock, resizing a grid cell, or re-homing a durable widget updates presentation without remounting its renderer or changing draft identity. Responsive widgets must use this available width, not assume the whole browser viewport belongs to them.

Workspace side panels

A contextual side panel belongs beside the normal content area, below the view's page chrome; it is not a grid widget and does not squeeze global navigation. The shared layout primitive owns the orange drag divider, keyboard resizing, reset-to-default gesture and width persistence. Co-work and form AI help use that same primitive while retaining their own responsive and content policies. Stored preferences contain only layout sizes.

A responsive presentation change must not end a live form conversation or discard an unsent message. Assistable standard widgets share the keep-alive placement mechanism without becoming App-owned durable widgets: host draft persistence, Arrange inertness, Preview forks and effect fences still apply. Only real removal, replacement, identity or editing-lifetime changes detach the form. Contextual Hover Help uses the existing provider around the visible view.

Operate, Arrange, and Preview

• Operate enables normal widget interaction and outward effects.
• Arrange enables layout controls while widget bodies remain inert.
• Preview freezes layout, forks drafts, permits local interaction, and simulates or blocks outward effects.

Canceling Preview discards the forked preview state; it never claims to roll back an effect that already reached another system.

App-owned durable widgets are the exception to both Arrange inertness and Preview's draft fork and effect simulation. A durable widget owns its own persistence and stays live in Operate, Arrange, and Preview alike, so its edits are always real and saved, never sandboxed. Because Preview then has nothing to sandbox on an all-durable view, such a view offers Arrange only, a generic rule keyed off definition.durable. A mixed view keeps Preview with honest copy that says the standard widgets are simulated while the live cards stay live and save.

App-owned durable widgets

A widget definition may declare itself durable. Dashboard Core then keeps its renderer mounted for the life of the view in a keep-alive host above the grid and re-homes the same DOM into the widget's cell across layout remounts, so live client state such as an editor's document, cursor, and scroll survives customize toggles, interaction recovery, and the mobile switch. A durable widget is one cohesive App-owned surface. Like a single-surface view it may hold live state and talk to its own routes and the event stream directly, while every identity, input, and dispatch invariant is retained: its snapshot input stays JSON, it emits declared intents, and it never receives the provider or mutates a sibling. A durable widget owns its own persistence and saves its live state through its own app-owned seams, so its edits are always real and it declares one instance per view and no host drafts. The Co-work workspace card is the first durable widget.

Host-owned working state and interaction surfaces

Widgets declare meaningful drafts; the host owns persistence, schema versions, revisions, clearing, and cross-tab behavior. Draft identity includes profile/workspace, publisher App, view, widget instance, widget type, draft name, and scope. Widgets do not persist arbitrary DOM inputs or create incompatible storage formats.

An eligible widget may additionally declare assistableDrafts, referencing the shared machine-readable form schema. Dashboard Core binds a contextual assistance dock to that exact host-owned draft; it is not a separate placeable chat widget or a Co-work editor adapter. Typed allowlisted patches update visible fields, preserve concurrent user edits, and expose conditional Undo. Submission remains the App's explicit human action. See services/dashboard/react/assisted-drafts.

Short-lived notices and confirmation requests are reusable dashboard infrastructure. They are distinct from the durable notification/request system. Contextual Hover Help is another host mode with layered ownership: Dashboard, view placement, widget, and primitive. Help and Customize are mutually exclusive.

Optional explanations belong on existing controls or headings through shared Hover Help. Current state, validation, required disclosures, confirmations, and recovery actions remain visible without Help; they must also work on narrow layouts where Hover Help is unavailable.

See services/dashboard/react for contribution hosting and migration boundaries, and services/dashboard/react/appearance for the visual contract every widget must honor.