Framework-owned UI Surface Library

Pharos renders a reusable library of framework-owned UI elements from checked fixture data.

The dynamic app includes a visible reference implementation rendered by the native runtime rather than app-local imperative glue.

Why this exists

Generated CRUD pages are already framework-owned, but real apps also need reusable page elements outside raw CRUD tables.

This UI surface library gives app authors a checked declarative way to describe:

typed input controls
bounded choice controls
summary and detail display elements
repeated record layouts
layout and action composition primitives
tooltip-friendly operator guidance

The native runtime owns the rendering contract for those elements.

Surface contract

The canonical authored source is:

apps/dynamic_app/data/contracts/ui-elements.yml

The compiled runtime artifact is emitted under the built app output as JSON.

The reference surface row is:

surface_id: dynamic_app_ui_lib
surface_kind: ui_lib

That row may declare either:

sections as the primary structured path
examples as the compatibility fallback path

Section shape

A section groups related element examples together.

Example shape:

section_id: inputs_and_widgets
title: Inputs and widgets
intro: Use these controls when a declarative action needs typed operator input without
  custom runtime glue.
layout: grid
examples: []

Section fields:

section_id stable identifier for the section
title visible section heading
intro visible app-author and operator guidance
layout section wrapper hint such as grid or stack
examples array of element declarations

Element declaration shape

Every UI element declaration uses the canonical identity and type contract:

id is the stable element identifier; example_id and element_id are legacy and are not accepted
element_type selects the canonical element family, such as input, select, textarea, or button
input_type selects the HTML input subtype when element_type is input; the legacy widget field is not accepted in UI element fixtures
name is the submitted field name for form controls

Declarations may also carry presentation data such as title, label, usage, tooltip, options, rows, cards, panels, or buttons. These values do not replace the canonical id, element_type, input_type, and name fields where those fields apply.

Current element types

Inputs and text capture

input

- current widgets include text, email, number, time, date, search, and url

textarea

Choice controls

select
radio_group
checkbox
checkbox_group

Display elements

card
list
detail
table
badge_list
stat_group

Layout and action composition

split_layout
card_grid
button_row

Rendering ownership

Apps own:

which sections exist
which examples are shown
labels, usage text, tooltips, and visible copy
option lists and record-like demo values
canonical control fragments under apps/<app_id>/templates/shared/fragments/ui_*.html

Raw <input>, <select>, <textarea>, and <button> markup must live only in those app-owned canonical UI fragments. Page bodies and feature-specific fragments compose the canonical fragments instead of maintaining duplicate renderers.

Pharos owns:

HTML rendering
element semantics
shared layout wrappers
compatibility behavior between sections and examples
the visible contract used by the live dynamic app and future framework-owned surfaces

Guidance for app authors

Use the dynamic app as the canonical visible reference:

run the native dynamic app check
open the rendered home page
inspect each section and tooltip

Validation flow:

scripts/check.sh ui canonical checks fixture field names, rejects duplicate legacy renderer paths, and inventories raw control markup outside canonical app-owned UI fragments
sh scripts/build_native.sh
sh scripts/check.sh dynamic-app native-runtime

The canonical UI check is a source-policy check only. It does not render templates or add runtime behavior.

Delivered UI library scope

The shipped UI library covers:

typed inputs and text capture controls
choice controls for bounded selections
record-display elements for summary and detail views
reusable layout primitives for grouped content and action areas
declarative labels, usage guidance, and tooltips rendered by the native runtime

Generated surface composition crossover

The UI library also extends into generated-admin page composition.

Generated-admin surfaces can point at app-owned composition files under generated_admin/, for example:

apps/ucal/generated_admin/service.yaml
apps/ucal/generated_admin/business_availability.yaml

Those files use the JSON-compatible YAML subset so the native runtime can load them directly while keeping the authoring source app-owned.