Appearance
Semantic widget catalogue #
Reference inventory of the facets, supporting widgets, and page archetypes used when a Product Application presents records in the Customer Portal. You author these through semantic composition; the portal maps them onto fixed page types (board, timeline, capacity, ledger) rather than a free-form widget designer.
To preview fixtures locally, run the portal frontend and open /dev/semantic-widgets. Each entry below has a stable #docs-slug you can deep-link or screenshot. Recapture gallery stages with:
bash
SEMANTIC_WIDGET_GALLERY_URL=http://localhost:5175/dev/semantic-widgets \
npm run capture:semantic-widget-galleryIn a workplace #
Facets rarely appear alone. A capacity page stacks them per record; a board or timeline arranges the same widgets for a different job. These gallery fixtures show the four page archetypes and a multi-facet record stack in context.
Semantic facets #
First-class composition components (semantic_composition.facets[].component). Required binding slots stay empty in composition v1 so older kits remain publishable. Treat the slots below as the authoring checklist for new facets.
| Name | component | Docs slug | Recommended binding slots | Typical archetypes |
|---|---|---|---|---|
| Asset status | asset_status | #asset-status | state, reason, since, device_online, level, threshold, player/display/content signals | board, timeline, capacity, ledger |
| Compliance series | compliance_series | #compliance-series | value / reading, threshold_low, threshold_high, unit, device_online | timeline, capacity, board |
| Credential entitlement | credential_entitlement | #credential-entitlement | identity / identifier, entitlement, balance, expires_at, status | ledger, board |
| Current fill | level_capacity | #level-capacity | quantity, capacity, threshold_low / _low_low / _high / _high_high, unit, device_online, name | capacity, board, ledger |
| Volume history chart | timeseries | #timeseries-bands | value, unit, band_ll, band_l, band_h, band_hh, device_online | capacity, timeline, board |
| Maintenance asset | maintenance_asset | #maintenance-asset | runtime, service_due, last_service, status, device_online, name | board, timeline, ledger |
| Media display state | media_display_state | #media-display-state | expected/applied labels and generations, screenshot fields, player_state, display_state, sync_state, device_online | board, ledger |
| Resource meter | resource_meter | #resource-meter | instantaneous / value / reading, unit, cumulative, device_online | capacity, board, timeline, ledger |
| Setpoint schedule | setpoint_schedule | #setpoint-schedule | setpoint / desired, actual, schedule, override, zone, device_online | board, timeline, ledger |
| State machine | state_machine | #state-machine | state, mode, job, fault, interlock, phase, device_online | board, timeline, ledger |
| Transaction | transaction | #transaction | phase, identity, quantity, amount, status, settled_at, credential | timeline, ledger, board |
Asset status #
asset_status · #asset-status
Compliance series #
compliance_series · #compliance-series
Credential entitlement #
credential_entitlement · #credential-entitlement
Current fill #
level_capacity · #level-capacity
Live snapshot of fill vs capacity. Not a history chart. Pair with volume history when operators need trend.
Volume history chart #
timeseries · #timeseries-bands
Maintenance asset #
maintenance_asset · #maintenance-asset
Media display state #
media_display_state · #media-display-state
Resource meter #
resource_meter · #resource-meter
Setpoint schedule #
setpoint_schedule · #setpoint-schedule
State machine #
state_machine · #state-machine
Transaction #
transaction · #transaction
Supporting widgets #
Shared display pieces used inside facets and capacity stacks. They are not authored as facets[].component values.
| Name | Key | Docs slug | Role |
|---|---|---|---|
| Asset status signals | AssetStatusSignals | #asset-status-signals | Compact status chip row |
| Expected vs applied | ExpectedVsApplied | #expected-vs-applied | Signage content match summary |
| Media preview frame | MediaPreviewFrame | #media-preview-frame | Screenshot with live/stale/offline caption |
| Watch camera + scrubber | MediaWatchHost | #media-marker-rail | Camera player, scrubber, and shared event marker rail |
| Event overlays on chart | chart overlays | #event-lane | Alarm and threshold markers on the volume history chart |
| Offline sync status | OfflineSyncStatusPanel | #offline-sync-status | Offline dataset sync health |
| Stream freshness chip | StreamFieldFreshnessChip | #stream-freshness-chip | Small live/stale/offline chip |
Event overlays and the media marker rail share the same normalized event points for a record. Bind the camera on the record (camera_device), not by inferring a camera from the network alone.
Asset status signals #
AssetStatusSignals · #asset-status-signals
Expected vs applied #
ExpectedVsApplied · #expected-vs-applied
Media preview frame #
MediaPreviewFrame · #media-preview-frame
Watch camera + scrubber #
MediaWatchHost · #media-marker-rail
Event overlays on chart #
#event-lane
Offline sync status #
OfflineSyncStatusPanel · #offline-sync-status
Stream freshness chip #
StreamFieldFreshnessChip · #stream-freshness-chip
Composition stacks #
| Name | Key | Docs slug | Role |
|---|---|---|---|
| Record composition stack | RecordCompositionStack | #record-composition-stack | Ordered multi-facet stack for one record; provides shared overlay events to child hosts |
See the stack figure under In a workplace.
Page archetypes #
| Name | page_type | Docs slug | Role |
|---|---|---|---|
| Board | board | #page-board | Lane board for work-in-progress records |
| Capacity | capacity | #page-capacity | Grid of records with facet stacks and optional timeseries overlays |
| Ledger | ledger | #page-ledger | Append-oriented tabular history |
| Timeline | timeline | #page-timeline | Chronological event / setpoint / playback timeline |
Capacity pages select facets with config.facet_keys and overlays with config.overlay_event_keys. See Semantic composition.
Freshness contract #
Every semantic surface must distinguish:
| State | Meaning |
|---|---|
live | Value is current within the facet freshness window |
stale | Last-known value shown with captured-at context |
offline | Bound device unreachable; do not imply current physical state |
unknown | No trustworthy value yet |
Configure freshness.telemetry_stale_after_seconds (and screenshot policy where relevant) on each facet.