TEDY resource navigation — TxResource architecture

How TEDY presents a terminology resource (Code System / Value Set / Map Set / Structure Definition / Structure Map): its list → resource → version navigation, the shared resource bar, and cross-resource work contexts. This follows the HELEX frontend architecture (emr/docs/architecture/frontend) and advances the earlier ad-hoc shell.

Principles (from HELEX frontend architecture)

• URL is the source of truth for {resource, version, tab}. Tabs are links; the active tab is derived from the route, not local state (05-routing-navigation).
• Single detail component keyed by id === 'new'; view ⇄ edit is an in-page ResourceForm mode toggle — no separate /:id/edit route (17-frontend-conventions §11). Create success navigates with { replace: true }.
• Work contexts (parked/pinned resources across types) use the platform’s generic context-switching framework — WorkContext + contextTypeRegistry
  • the connected context bar — with an explicit Pin action (no auto-park) (09-context-handling).
• Naming: Tx* for the terminology-resource UI (aligns with the @helex/tx terminology namespace); Tedy* for TEDY-app-specific pieces.

Components

TxResourceBar (built)

The shared, sticky resource bar shown on every resource/version page:

• Identity — a short resource-type marker (CS / VS / MS / SD / SM) + localized title, with a Pin toggle (see cross-resource work contexts below).
• Submenu tabs — URL-driven; the active tab comes from the route. Tab set per resource type (below). routeFor(mode) injects /versions/{version} when a version is active, so the same submenu serves the resource and version levels.
• Version area — an All versions dropdown when unversioned; the version code + a status marker when a version is active. Selecting a version drills into it (/{type}/{id}/versions/{version}/{mode}, replace).
• × unselect — version → resource (same tab, replace); resource → list.

Version is a path segment, never a query param.

Tab matrix

¹ CS Properties only when the CS has a Coding-typed property. ² Checklist privilege-gated. ³ Content = the FSH/JSON (Structure Definition) or composed FML (Structure Map), read-only for now. ⁴ Structure Maps have no backend versioning, so the bar shows no version dropdown/drill-in and there are only resource-level tabs.

• Metadata is the single detail component (view + in-page edit toggle) — no /:id/edit route (HELEX convention).
• Value Set rules and Map Set associations are edited inside the respective version summary (they are not top-level tabs).
• Structure Definition / Structure Map live outside /ts (/structure-definitions, /transformation-definitions) and use numeric ids; both render on the same TxResourceBar — SD versioned, SM version-less — proving the bar is not tied to the /ts resource shape.

Cross-resource work contexts (pins) — delivered

Pinning uses the platform WorkContext framework, not a bespoke bar:

• The TxResourceBar Pin toggle openContext()s the resource into the shared Redux contextSlice (sessionStorage-persisted); un-pinning closeContext()s it.
• The platform’s connected context bar (already rendered by the app chrome, ConnectedPatientContextBar) shows the pinned resources — across all five types — as switchable tabs (select → navigate its activePath; × → close).
• registerTedyContextTypes() registers the five context-type codes at bootstrap.
• The bar keeps a pinned context’s activePath current (setContextPath) and re-activates it (switchToContext) as you move between a resource’s tabs, so the platform bar stays on-screen.

No ad-hoc open-resources store — that was removed in P4. (Two known limits: the platform bar hides on list/non-resource pages, and dev-guest reload clears pins because re-auth dispatches clearSession; real OIDC keeps them across F5.)

Routes

Layout routes render TxResourceBar + <Outlet>:

/{type}                                   → list (id === 'new' handled by the detail route)
/{type}/:id/(summary|details|concepts|properties|provenances|checklists)
/{type}/:id/versions/:versionCode/(summary|concepts|properties|provenances|checklists)
/{type}/:id/versions/new

No /:id/edit (view⇄edit is in-page). Each leaf is a page body that reads the version from the path.

Build plan

All three resources are migrated onto TxResourceBar. Code System was the reference slice; Value Set and Map Set followed the same shape.

• P1 — TxResourceBar ✅ built (sticky bar, URL-driven tabs, version dropdown, ×, back control, routeFor/selectVersion/unselect).
• P2 — URL layout routes (list → :id/{mode} → :id/versions/:versionCode/{mode}) rendering TxResourceBar + <Outlet>. ✅ Code System, Value Set, Map Set ({CodeSystem,ValueSet,MapSet}ResourceLayout), resource + version levels; version is a path segment, no ?version.
• P3 — tab bodies mapped to modes: Summary, Metadata (in-page edit toggle on the details route — no /:id/edit), Concepts, Provenance, and CS Properties (Coding-gated) / Checklist. ✅ Code System (six tabs), Value Set (Summary · Metadata · Concepts(expansion) · Provenance), Map Set (Summary · Metadata · Provenance), with provenance/checklist clients + hooks (/ts/{resource}/{id}/provenances, /ts/checklists).
• P3b — move Value Set rule editor + Map Set associations grid into the respective version summary pages. ✅ both (the compose rule-set editor and the associations grid render in the version-level Summary).
• P4 — remove the ad-hoc open-resources store + per-resource shells. ✅ TedyResourceShell, openResourceStore, and shellActions deleted.
• P5 — verify the route hierarchy end-to-end. ✅ all resources (list → resource → version, every tab, real provenance / associations data, version status marker).
• P6 — cross-resource pins via the platform WorkContext framework. ✅ Pin toggle + platform context bar (see above).
• P7 — Structure Definition + Structure Map on the same bar (outside /ts, numeric ids; SD versioned, SM version-less). ✅ list / create / detail with Summary · Metadata · Content.

Differences from the earlier TEDY implementation