@elevasis/sdk 1.44.3 → 1.45.0

package/reference/scaffold/ui/feature-shell.mdx

@@ -1,63 +1,73 @@
----
-title: System Shell & Provider Runtime
-description: Current system shell contract for Organization Model systems, manifests, route matching, sidebars, and breadcrumbs.
----
+---
+title: System Shell & Provider Runtime
+description: Current system shell contract for Organization Model systems, manifests, route matching, sidebars, and breadcrumbs.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-## Overview
-
-The system shell derives app navigation from `OrganizationModel.systems`. System manifests provide implementation hooks such as icons and sidebars; they do not own structural navigation.
-
-## Source Of Truth
-
-- `packages/core/src/organization-model/defaults.ts` -- default system list
-- `packages/core/src/organization-model/helpers.ts` -- `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`
-- `packages/ui/src/features/registry/types.ts` -- `SystemModule`
-- `packages/ui/src/provider/ElevasisSystemsProvider.tsx` -- runtime resolver
-- `packages/ui/src/components/navigation/useBreadcrumbs.ts` -- breadcrumb derivation
-
-## SystemModule
-
-```ts
-export interface SystemModule {
-  key: string
-  systemId: string
-  capabilityIds?: string[]
-  icon?: SystemIconComponent
-  sidebar?: SystemSidebarComponent
-  organizationGraph?: { systemId: string }
-}
-```
-
-`systemId` must match an Organization Model system ID. Structural fields such as route lists, nav labels, and nested links belong on `OrganizationModel.systems`.
-
-## Shell Model
-
-`useElevasisSystems()` exposes `shellModel`:
-
-```ts
-{
-  systems,
-  findByPath,
-  findById,
-  childrenOf,
-  ancestorsOf,
-  parentOf,
-  topLevel,
-  uiPositionFor,
-  requiresAdminFor,
-  devOnlyFor
-}
-```
-
-Sidebar rendering walks `topLevel()` and `childrenOf(id)`. Breadcrumbs resolve `findByPath(location.pathname)` and then map `ancestorsOf(id)`.
-
-## Access
-
-System access is keyed by Organization Model system ID. `requiresAdmin` and `devOnly` inherit from ancestor system nodes and are applied when deriving visible sidebar entries.
-
+
+## Overview
+
+The system shell derives app navigation from `OrganizationModel.systems`. System manifests provide implementation hooks such as icons and sidebars; they do not own structural navigation.
+
+## Source Of Truth
+
+- `packages/core/src/organization-model/defaults.ts` -- default system list
+- `packages/core/src/organization-model/helpers.ts` -- `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`
+- `packages/ui/src/features/registry/types.ts` -- `SystemModule`
+- `packages/ui/src/provider/ElevasisSystemsProvider.tsx` -- runtime resolver
+- `packages/ui/src/components/navigation/useBreadcrumbs.ts` -- breadcrumb derivation
+
+## SystemModule
+
+{/* doc-snippet:skip: shape excerpt from features/registry/types.ts -- SystemIconComponent and SystemSidebarComponent are shown unimported here for readability */}
+
+```ts
+export interface SystemModule {
+  key: string
+  systemId?: string
+  routePrefixes?: string[]
+  capabilityIds?: string[]
+  icon?: SystemIconComponent
+  sidebar?: SystemSidebarComponent
+  sidebarWidth?: number | ((context: { currentPath: string }) => number)
+  organizationGraph?: OrganizationGraphSystemBridge
+}
+
+interface OrganizationGraphSystemBridge {
+  systemId?: string
+}
+```
+
+`systemId` must match an Organization Model system ID when present. Navigation-only app modules may omit `systemId` and use `routePrefixes` instead (see "Manifests for Navigation-Only Modules" below). `sidebarWidth` overrides the default 250px shell sidebar width. Structural fields such as route lists, nav labels, and nested links belong on `OrganizationModel.systems`.
+
+## Shell Model
+
+`useElevasisSystems()` exposes `shellModel`:
+
+{/* doc-snippet:skip: shape excerpt shown as a bare field list, not a standalone object literal or interface */}
+
+```ts
+{
+  systems,
+  findByPath,
+  findById,
+  childrenOf,
+  ancestorsOf,
+  parentOf,
+  topLevel,
+  uiPositionFor,
+  requiresAdminFor,
+  devOnlyFor
+}
+```
+
+Sidebar rendering walks `topLevel()` and `childrenOf(id)`. Breadcrumbs resolve `findByPath(location.pathname)` and then map `ancestorsOf(id)`.
+
+## Access
+
+System access is keyed by Organization Model system ID. `requiresAdmin` and `devOnly` inherit from ancestor system nodes and are applied when deriving visible sidebar entries.
+
 Routes still need guards:
 
 ```tsx
@@ -68,8 +78,215 @@ Routes still need guards:
 </ProtectedRoute>
 ```
 
-Use `AccessKeys.platformAdmin` with `AccessGuard` for pages that require platform-admin privileges.
-
-## External Shells
-
-Host apps pass `SYSTEM_MANIFESTS` or their own `SystemModule[]` into `ElevasisSystemsProvider` and derive sidebar links locally from `shellModel`. There is no separate nav config file to keep in sync.
+Use `AccessKeys.platformAdmin` with `AccessGuard` for pages that require platform-admin privileges. Use exported `AccessKeys` for permission-backed or diagnostic surfaces such as operations, monitoring, settings, and right-panel views.
+
+## Manifests for Navigation-Only Modules
+
+Shared feature manifests may omit `systemId` and own `routePrefixes` instead when the module covers a navigation-only area rather than a semantic System. Route authorization still belongs to `AccessGuard`:
+
+```ts
+// navigation-only module -- no systemId required
+export const manifest = {
+  key: 'operations',
+  routePrefixes: ['/operations'],
+  capabilityIds: ['operations:view'],
+}
+```
+
+Manifest validation does not reject route-only modules. `ElevasisSystemsProvider` resolves surface route prefixes for app-area modules and uses `routePrefixes` for matching when `systemId` is absent. Access checks use System paths or `AccessKeys` constants, not manifest route prefixes.
+
+## Navigation Shape Decisions
+
+| Decision          | Current outcome                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| Business          | Navigation group only, not a System or URL namespace                                                          |
+| Fake Systems      | Dashboard, Finance, Operations, Monitoring, Knowledge, Settings, and Admin are demoted from canonical Systems |
+| `platform`        | Real canonical System owning cross-cutting diagnostics                                                        |
+| `/clients`        | Canonical route; legacy `/business/clients` routes redirect                                                   |
+| Sidebar authoring | `navigation.sidebar` is the source of truth for shell navigation                                              |
+
+## Composition
+
+Host apps pass a system manifest list and a canonical organization model into the provider:
+
+```tsx
+<ElevasisSystemsProvider systems={SYSTEM_MANIFESTS} organizationModel={canonicalOrganizationModel}>
+  <SystemShell>{children}</SystemShell>
+</ElevasisSystemsProvider>
+```
+
+Host apps still own route files, topbar behavior, app branding, and dashboard composition.
+
+## Topbar Action Substrate
+
+The topbar is governed by the Organization Model through a `navigation.topbar` region that is parallel to `navigation.sidebar`. Each entry is a `TopbarActionNode` -- a leaf with no `path` or `surfaceType` -- and a UI registry binds each node's behavior. This mirrors the sidebar manifest pattern exactly: **OM owns data + visibility; the registry owns behavior.**
+
+### OM Schema -- `navigation.topbar`
+
+Declared in `packages/core/src/organization-model/domains/navigation.ts`:
+
+{/* doc-snippet:skip: shape excerpt from domains/navigation.ts -- z and the field schemas (ModelIdSchema, LabelSchema, etc.) are shown unimported here for readability */}
+
+```ts
+// A topbar action node -- no path, no surfaceType
+const TopbarActionNodeSchema = z.object({
+  id: ModelIdSchema,             // stable key the registry binds to
+  label: LabelSchema,            // accessible name / menu fallback
+  tooltip: DescriptionSchema.optional(),
+  icon: IconNameSchema.optional(), // flat token, resolved via icon registry
+  order: z.number().int().optional(),
+  enabled: z.boolean().default(true),
+  devOnly: z.boolean().optional(),
+  requiresAdmin: z.boolean().optional(),
+  targets: SidebarSurfaceTargetsSchema.optional()
+})
+
+// OrganizationModelNavigationSchema gets a topbar field alongside sidebar
+const OrganizationModelNavigationSchema = z.object({
+  sidebar: SidebarNavigationSchema,
+  topbar: z.record(z.string(), TopbarActionNodeSchema).default({})
+})
+```
+
+The `topbar` field is an **append** -- `surfaceType`, surfaces, and the sidebar are untouched.
+
+### UI Registry -- `TopbarActionModule`
+
+Defined in `packages/ui/src/features/registry/types.ts`:
+
+{/* doc-snippet:skip: shape excerpt from features/registry/types.ts -- TablerIconComponent and ReactNode are shown unimported here for readability */}
+
+```ts
+export interface ResolvedTopbarAction {
+  id: string
+  label: string
+  tooltip?: string
+  icon: TablerIconComponent  // resolved from the OM token
+  order: number
+}
+
+export interface TopbarActionModule {
+  key: string                           // matches navigation.topbar[key].id
+  render: (ctx: { node: ResolvedTopbarAction }) => ReactNode
+}
+```
+
+The manifest map lives in `packages/ui/src/features/registry/manifests.ts`:
+
+{/* doc-snippet:skip: shape excerpt from features/registry/manifests.ts -- TopbarActionModule and requestTopbarActionManifest are shown unimported here for readability */}
+
+```ts
+export const TOPBAR_ACTION_MANIFESTS: Record<string, TopbarActionModule> = {
+  request: requestTopbarActionManifest
+  // docs, notifications, orgSwitcher, ... (migrated incrementally)
+}
+```
+
+### Projection and Provider
+
+`packages/ui/src/provider/topbarProjection.ts` mirrors `sidebarProjection.ts`:
+
+- reads `navigation.topbar` from the resolved OM;
+- drops items where `enabled === false`, `devOnly && !isDev`, or `requiresAdmin && !isPlatformAdmin`;
+- resolves `icon` via `getSemanticIconComponent(node.icon)`;
+- sorts by `order`, then id;
+- joins each surviving OM node to its registered module by `node.id === module.key`; skips nodes with no module and modules with no OM node.
+
+`ElevasisSystemsProvider` gains a `topbarActions?: TopbarActionModule[]` prop and exposes `getTopbarActions({ isPlatformAdmin, isDev })`. The provider **defaults `topbarActions` to `Object.values(TOPBAR_ACTION_MANIFESTS)`** when no explicit prop is passed -- so shell-based consumers (`ElevasisAuthenticatedShell`, tenants) get the OM-governed topbar with zero wiring. Pass an explicit array to override or extend.
+
+This is an intentional asymmetry vs `systems`, which defaults to `[]` (tenant-assembled). Topbar behaviors are package-universal; sidebar systems are tenant-assembled.
+
+### Consumer Component -- `<TopbarActions />`
+
+Shipped from `@elevasis/ui/layout`:
+
+```tsx
+export function TopbarActions({ isPlatformAdmin, isDev }: { isPlatformAdmin?: boolean; isDev?: boolean }) {
+  const { getTopbarActions } = useElevasisSystems()
+  return (
+    <>
+      {getTopbarActions({ isPlatformAdmin, isDev }).map(({ node, render }) => (
+        <Fragment key={node.id}>{render({ node })}</Fragment>
+      ))}
+    </>
+  )
+}
+```
+
+`AppTopbar` drops `<TopbarActions />` in among its children. The theme switch and version `Code` remain hardcoded in `Topbar` -- they are not feature actions.
+
+### Governance
+
+Because topbar items are OM nodes with the same gating flags as sidebar surfaces, toggling them requires no new mechanism:
+
+- Toggle: set `enabled: false` to hide an item per tenant.
+- Reorder: change `order`.
+- Gate: `requiresAdmin` / `devOnly` restrict who sees it.
+- Add: declare a new `navigation.topbar` entry and register a matching module.
+
+### Comparison Table
+
+| Aspect           | Sidebar                                  | Topbar                                   |
+| ---------------- | ---------------------------------------- | ---------------------------------------- |
+| OM region        | `navigation.sidebar.primary` / `.bottom` | `navigation.topbar`                      |
+| Node type        | `SidebarSurfaceNode` (has `path`)        | `TopbarActionNode` (no `path`)           |
+| Registry type    | `SystemModule`                           | `TopbarActionModule`                     |
+| Registry map     | `SYSTEM_MANIFESTS`                       | `TOPBAR_ACTION_MANIFESTS`                |
+| Provider prop    | `systems?: SystemModule[]`               | `topbarActions?: TopbarActionModule[]`   |
+| Provider default | `[]` (tenant-assembled)                  | `Object.values(TOPBAR_ACTION_MANIFESTS)` |
+| Context accessor | `getSidebarLinks(opts)`                  | `getTopbarActions(opts)`                 |
+| Projection file  | `sidebarProjection.ts`                   | `topbarProjection.ts`                    |
+| UI consumer      | `Sidebar`                                | `<TopbarActions />`                      |
+
+### File Locations
+
+| Concern              | Path                                                              |
+| -------------------- | ----------------------------------------------------------------- |
+| OM navigation schema | `packages/core/src/organization-model/domains/navigation.ts`      |
+| Registry types       | `packages/ui/src/features/registry/types.ts`                      |
+| Registry map         | `packages/ui/src/features/registry/manifests.ts`                  |
+| Provider             | `packages/ui/src/provider/ElevasisSystemsProvider.tsx`            |
+| Projection           | `packages/ui/src/provider/topbarProjection.ts`                    |
+| Consumer component   | `packages/ui/src/components/layout/topbar/` (`<TopbarActions />`) |
+| CC root wiring       | `apps/command-center/src/routes/__root.tsx` + `AppTopbar.tsx`     |
+
+## External Shells
+
+External templates pass `canonicalOrganizationModel` into `ElevasisSystemsProvider` and derive sidebar links locally from `shellModel`. There is no separate nav config file to keep in sync.
+
+### Operations Subshell and Manifest Mounting
+
+The Operations area uses a dedicated manifest rather than a raw `SystemModule`. `packages/ui/src/features/operations/manifest.ts` exports `operationsManifest`, which supplies `OperationsSidebarRouter`. That router dispatches to route-specific sidebar components by URL prefix:
+
+- `ResourcesSidebar` for `/operations/resources`
+- `ExecutionLogsSidebar` for resource detail pages
+- `CommandQueueSidebarConnected` for `/operations/command-queue`
+- `SystemsSidebar` for `/operations/systems`
+- `SessionsSidebar` for `/operations/sessions`
+
+External project root routes must include `operationsManifest` in the manifest array passed to `ElevasisAuthenticatedShell`/`ElevasisSystemsProvider`. Omitting it means no Operations sidebar appears, even though the Operations routes and API/SSE props (`operationsApiUrl`, `operationsSSEManager`) are wired correctly. The canonical reference is `external/_template/ui/src/routes/__root.tsx`.
+
+The direct fix is always to mount the published manifest rather than duplicate sidebar routing locally. Whether tenant navigation exposes `/operations/systems` or `/operations/sessions` is a product/OM decision separate from the missing-sidebar substrate bug.
+
+`monitoringManifest` and `settingsManifest` follow the same pattern and should be mounted in the same pass when those surfaces are enabled for a project.
+
+## Ownership Boundaries
+
+`ElevasisSystemsProvider` and `SystemShell` own system manifest registration, system-aware nav contribution, provider-scoped system context (`timeRange`, `operationsApiUrl`, `operationsSSEManager`), route-to-sidebar subshell dispatch, and shared shell/page/sidebar extraction for reusable systems.
+
+They do **not** own TanStack file-based route registration, app-specific assistant context hooks, app-specific admin navigation, or project-specific branding and topbar behavior. Consumers keep thin route files and thin app-local wrappers that inject only genuinely app-specific behavior.
+
+## Shared-First Extraction
+
+When migrating a system surface from app-local to shared:
+
+1. Move the reusable shell, sidebar, and page behavior into `packages/ui`.
+2. Leave only thin route glue in consumers.
+3. Keep assistant-context, tenant-guard, and app-specific branding glue local.
+4. Delete dead local wrappers after verification.
+
+Do not leave a duplicate app-local shell after the shared version exists unless there is a documented app-specific divergence.
+
+## Router Standardization
+
+Shared sidebars and shell components prefer `useRouterContext()` by default. Compatibility props such as `currentPath` or `onNavigate` are acceptable only to preserve published API compatibility. Where they remain, treat them as compatibility seams rather than the preferred usage path, default internally to router-context behavior, and do not remove them casually from published surfaces.