Skip to content

Host component registry and renderer

Issues #115 and #130 introduce and extend the production React renderer in apps/web/src/plugin-ui/renderer. It consumes an already validated and resolved page; resource submission, action invocation, metadata resolution, and tenant editing remain separate concerns.

Security and failure boundary

  • Metadata selects components only from HostComponentRegistry.
  • Every component declares allowed hosts, props, child behavior, slots, keyboard behavior, and accessibility semantics.
  • Raw style, CSS/class, colour, and background props are rejected. Host CSS uses semantic tokens so plugins cannot bypass themes or forced-colour rules.
  • Unknown, disabled, host-incompatible, invalid, or failed components produce a contained fallback. Ordinary users see no plugin or binding details; development diagnostics include the page, node, component, sources, and first invalid property.
  • React escapes all metadata text. No HTML, script, arbitrary event handler, or plugin CSS execution path exists in this renderer.
  • Literal and resolved binding values are validated against the target component's declared prop shape before rendering. Diagnostics identify the failed binding name but never include its value.

Initial registry

Component Props Children / slots Keyboard and semantics
platform.ui.page title, description, icon required Main landmark and one level-one heading; optional route focus target.
platform.ui.stack gap required Neutral vertical layout; document order.
platform.ui.grid columns required Responsive grid; collapses without changing reading order.
platform.ui.split none required; primary, secondary Responsive two-region layout; source order remains primary first.
platform.ui.section title, description optional Labelled section with level-two heading.
platform.ui.card title, description optional Article with level-three heading.
platform.ui.tabs label, tabs required Arrow Left/Right and Home/End select tabs; tab/tabpanel relationships are explicit.
platform.ui.accordion title, open optional Native details/summary; Enter and Space toggle.
platform.ui.text text, tone none Escaped paragraph text.
platform.ui.alert title, variant optional Status semantics except danger, which uses an assertive alert.
platform.ui.field.text name, label, description, error, value, type, required, disabled, read_only none Native labelled input with described-by and invalid relationships.
platform.ui.field.select name, label, description, error, value, options, required, disabled none Native labelled select and options.
platform.ui.collection-controls label required Search landmark grouping query, filter, and sort controls.
platform.ui.query-input label, placeholder, value, action, parameter, submit_label none Native search input; Enter or the apply button invokes only the declared action.
platform.ui.query-select label, value, options, action, parameter none Native filter/sort select; change invokes only the declared action.
platform.ui.collection label, resource, items, fields, empty_title, empty_description, selected_id, select_action, selection_parameter, presentation, identity_label, identity_sort, sort_action, sort_parameter, sort, sort_direction, open_action, open_parameter, open_label none Labelled semantic list with row/card presentation, or a captioned table (presentation: table; stacked rows on compact hosts) whose first column names each row; sortable headers are toggle buttons with aria-sort set from sort_direction (ascending by default); an optional open action renders a named button per item; Arrow keys and Home/End move focus between selectable items.
platform.ui.filter-chips label, chips, clear_action, clear_label none Active filters as chips with named remove buttons and an optional clear-all; renders nothing when empty.
platform.ui.record-preview label, empty_title, empty_description optional selected record Complementary preview region with a bounded empty state.
platform.ui.highlights label, resource, record, fields, icon optional action groups Record identity with an optional decorative object tile, a definition list of configured key fields, and child action groups in reading order.
platform.ui.path label, stages, current, empty_description none Navigation landmark with an ordered stage list; the current stage carries aria-current="step", earlier stages are marked complete; read-only.
platform.ui.timeline label, items, empty_title, empty_description none Ordered activity entries with title, description, actor and a machine-readable time; bounded empty state.
platform.ui.record-summary label, resource, record, fields, show_identity none Labelled optional identity and definition list containing only configured caller-readable fields.
platform.ui.relationship-list label, resource, items, fields, select_action, selection_parameter, empty_title, empty_description, presentation none Labelled semantic list for declared related records; optional native-button selection uses the collection keyboard contract.
platform.ui.cursor label, previous_action, next_action, previous_cursor, next_cursor, parameter, previous_label, next_label none Navigation landmark with disabled native buttons when opaque cursors are absent.
platform.ui.state variant, title, description, lines optional recovery action Loading, empty, error, denied, archived, and unavailable semantics; denied text is host-owned and non-disclosing.
platform.ui.table label, columns, rows none Captioned table and scoped headers; internal/desktop/portal only.
platform.ui.action-bar label required Labelled action group; buttons remain in document order.
platform.ui.action label, variant, disabled none Native button; #117 supplies invocation and state behavior.
platform.ui.dialog title, open required Native labelled dialog; full focus/close action integration belongs to #117.
platform.ui.slot label, kind optional Stable card/action/related-list/timeline target; empty slots render no landmark or chrome.
platform.ui.fragment fragment_id required Neutral reusable-fragment boundary.
platform.ui.loading label, lines none Polite named loading status; reduced motion is inherited.
platform.ui.empty title, description optional action Explanatory heading, description, and optional action.
platform.ui.denied title, description none Non-disclosing permission state.
platform.ui.error title, description optional recovery action Contained assertive failure state.

Localized strings use <property>_key references resolved against the caller's message catalogue, with safe host-provided fallbacks. The renderer records the locale and host on its root for diagnostics and future hydration checks.

Collection and record data boundary

Collection items and record summaries have a deliberately small caller-safe shape: stable id, display title, optional description and archived state, plus a values map. A component renders only keys declared in its fields list and present as readable in the named caller-safe resource descriptor. Labels come from that filtered descriptor rather than arbitrary data-source content. Additional or forbidden values and labels are never dumped or serialized into page markup. Each requested display field has a stable key and an optional host-owned format hint.

Page bindings may supply these props from a literal, context, field, or declared data source. The host resolves bindings before prop validation. Unknown binding targets, invalid item/record shapes, raw styling targets, or missing required bound values produce the same contained fallback as malformed literal props. Query and cursor controls can override only parameters declared with a literal placeholder on a registered metadata action. Field, context, and data-source parameters are resolved by the host and cannot be replaced by control input. The interaction adapter remains responsible for URL/history and API behavior.

Collection selection uses native buttons. Arrow keys move focus without changing selection; activation invokes the declared selection action. Compact and narrow layouts change rows to cards without changing DOM order. Opaque cursors are passed back unchanged and are never decoded by the renderer.

Responsive and development fixtures

The fixture in renderer/fixtures.ts is rendered unchanged with wide and compact form-factor classes. Layout containers use minmax(0, …), bounded overflow, and a single-column narrow breakpoint. The development-only /__ui showcase renders the fixture alongside the base primitives so component and token changes remain reviewable. Automated tests cover semantics, localization, narrow/wide output, unsupported hosts, disabled/unknown components, prop rejection, renderer failure containment, and development diagnostic redaction.