@elevasis/sdk 1.9.0 → 1.11.0

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

@@ -1,241 +1,72 @@
 ---
 title: Feature Shell & Provider Runtime
-description: Organization OS UI Shell Runtime and Features layer architecture covering FeatureModule manifests, ElevasisFeaturesProvider, route-to-sidebar dispatch, and organization-model-aware runtime resolution.
+description: Current feature shell contract for flat Organization Model features, manifests, route matching, sidebars, and breadcrumbs.
 ---
 
 ## Overview
 
-Within Organization OS, the feature shell spans two layers: the **UI Shell Runtime** that resolves shared nav/sidebar behavior, and the **Features** layer that declares what each feature contributes. It lets command-center and external template consumers compose the same nav, sidebars, and subshell routes from a small set of manifests. It is intentionally a thin layer: manifests describe what a feature contributes, the provider resolves that into a runtime shell model, and consumers still own their own routes, branding, and app-local nav.
+The feature shell derives app navigation from `OrganizationModel.features`. Feature manifests provide implementation hooks such as icons and sidebars; they no longer own structural navigation.
 
-Three layers participate, and the word "feature" means something different in each:
+## Source Of Truth
 
-- **Platform capabilities** -- product-facing areas documented under `technical/features/` (Execution Engine, Workflows, Agents, Operations, etc.). These are not one-to-one with shell features.
-- **Shell features** -- features in `packages/ui/src/features/*`. Seven are manifest-backed (`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`); two are utility features without manifests (`auth`, `dashboard`).
-- **Organization-model features** -- feature objects in `@repo/core/organization-model` with shape `{ id, label, enabled, entityIds, surfaceIds, resourceIds, capabilityIds }`. The 7 defaults are `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`. See [Organization Model](../core/organization-model.mdx).
+- `packages/core/src/organization-model/defaults.ts` -- default flat feature list
+- `packages/core/src/organization-model/helpers.ts` -- `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`
+- `packages/ui/src/features/registry/types.ts` -- `FeatureModule`
+- `packages/ui/src/provider/ElevasisFeaturesProvider.tsx` -- runtime resolver
+- `packages/ui/src/components/navigation/useBreadcrumbs.ts` -- breadcrumb derivation
 
-One shell feature can contain several platform capabilities; a manifest's `featureId` directly matches `feature.id` in the org model with no alias layer.
+## FeatureModule
 
-## Source of Truth
+```ts
+export interface FeatureModule {
+  key: string
+  featureId: string
+  capabilityIds?: string[]
+  icon?: FeatureIconComponent
+  sidebar?: FeatureSidebarComponent
+  organizationGraph?: { featureId: string }
+}
+```
 
-- `packages/ui/src/features/registry/types.ts` -- `FeatureModule` contract
-- `packages/ui/src/features/registry/manifests.ts` -- published `FEATURE_MANIFESTS` convenience map
-- `packages/ui/src/provider/ElevasisFeaturesProvider.tsx` -- runtime composition
-- `packages/ui/src/provider/FeatureShell.tsx` -- route-to-sidebar dispatch
-- `packages/ui/src/provider/resolvers/{RouteResolver,NavResolver}.ts` -- pure path/nav helpers
-- `packages/ui/src/provider/validateManifests.ts` -- startup-time manifest validation
-- `packages/ui/src/provider/published.ts` -- headless published barrel
-- `apps/command-center/src/routes/__root.tsx` -- reference composition
+`featureId` must match an Organization Model feature ID. Structural fields such as route lists, nav labels, and nested links belong on `OrganizationModel.features`.
 
-## The FeatureModule Contract
+## Shell Model
 
-A `FeatureModule` describes one shell feature's contribution. Fields:
+`useElevasisFeatures()` exposes `shellModel`:
 
-- `key` -- unique stable identifier (e.g., `'crm'`, `'projects'`)
-- `featureId` -- **required**; the `feature.id` value from the org model that this module maps to; used by `useFeatureAccess()` for gating
-- `capabilityIds` -- semantic references into the organization model
-- `navEntry` -- top-level nav contribution (label, icon, optional `link`, optional nested `links`, optional `requiresAdmin`, optional onboarding-tour ID, optional `featureKey` override when nav identity must diverge from access identity)
-- `sidebar` -- optional `ComponentType` for the feature's subshell sidebar
-- `subshellRoutes` -- routes the feature owns under its subshell
-- `organizationGraph` -- **Operations-only**; bridges a manifest to an organization-model surface (ignored by other features)
+```ts
+{
+  features,
+  findByPath,
+  findById,
+  childrenOf,
+  ancestorsOf,
+  parentOf,
+  topLevel,
+  uiPositionFor,
+  requiresAdminFor,
+  devOnlyFor
+}
+```
 
-`FeatureModule.label` has been removed; nav labels resolve from `navEntry.label` or from the matching organization-model feature's `label` field.
+Sidebar rendering walks `topLevel()` and `childrenOf(id)`. Breadcrumbs resolve `findByPath(location.pathname)` and then map `ancestorsOf(id)`.
 
-Manifests are validated at provider registration via `validateManifests()`. Unknown `featureId` or `capabilityIds` (measured against the resolved organization model) throw with all violations collected into one error.
+## Access
 
-### ResolvedFeatureModule
+Feature access is keyed by Organization Model feature ID. `requiresAdmin` and `devOnly` inherit from ancestor feature nodes and are applied when deriving visible sidebar entries.
 
-`ResolvedFeatureModule` extends `FeatureModule` with two additional fields added during provider resolution:
+Routes still need guards:
 
-- `access: ResolvedFeatureAccess` -- `{ featureId: string, enabled: boolean }` -- the resolved access state for this feature
-- `semantics: ResolvedFeatureSemantics` -- `{ capabilityIds, surfaceIds, surfaces }` -- merged semantic identifiers derived from both manifest declarations and organization-model surface data
+```tsx
+<ProtectedRoute>
+  <FeatureGuard featureKey="sales.crm">
+    <Outlet />
+  </FeatureGuard>
+</ProtectedRoute>
+```
 
-`ResolvedFeatureSemantics.surfaces` carries the full `OrganizationModelSurface[]` objects (not just IDs), so consumers can inspect surface metadata without a separate lookup.
+Use `AdminGuard` for pages that require platform-admin privileges.
 
-## Provider Architecture
+## External Shells
 
-The provider layer is composed of several focused context providers. `ElevasisCoreProvider` and `ElevasisFeaturesProvider` are the two consumer-facing entry points; the others are internal building blocks also published for advanced use.
-
-### ElevasisCoreProvider
-
-`ElevasisCoreProvider` is the headless root provider for Elevasis-powered applications. It is pure auth + API with no style side-effects -- no CSS variables, no `data-elevasis-scheme`, no font loading. When `apiUrl` is provided it composes the full provider stack:
-
-`QueryClientProvider` -> `AuthProvider` -> `ApiClientProvider` -> `ProfileProvider` -> `OrganizationProvider` -> `ElevasisServiceProvider` -> `NotificationProvider` -> `InitializationProvider`
-
-Consumers that need Mantine theming use `ElevasisUIProvider` (internal) or `ElevasisProvider` instead. `ElevasisCoreProvider` is exported from `packages/ui/src/provider/published.ts` for headless SDK consumers.
-
-### ElevasisServiceProvider
-
-`ElevasisServiceProvider` (from `ElevasisServiceContext.tsx`) is the standalone service context. It accepts three props directly: `apiRequest`, `organizationId`, and `isReady`. `ElevasisCoreProvider` composes this internally after org resolution; advanced consumers can mount it standalone for testing or embedding.
-
-`useElevasisServices()` reads this context and throws if used outside a provider. Consumed throughout the shared component library wherever API requests are needed.
-
-### AppearanceProvider
-
-`AppearanceProvider` (from `AppearanceContext.tsx`) supplies an `AppearanceConfig` to the tree: `{ background?: ReactNode, loader?: ReactNode }`. The `background` field controls layers rendered behind app content; `loader` controls loading-state elements. Defaults are set in the provider rather than at context creation to avoid importing heavy visual components at module scope.
-
-`useAppearance()` reads this context and throws if used outside a provider.
-
-### NotificationProvider
-
-`NotificationProvider` (from `NotificationContext.tsx`) accepts a pluggable `NotificationAdapter` for routing notifications to any library. The adapter interface is `{ success, error, info, warning, apiError }`. `ElevasisUIProvider` wires the Mantine adapter automatically.
-
-When no provider is present in the tree, `useNotificationAdapter()` falls back to a console-based adapter (not a no-op), so template consumers work without Mantine. The hook never throws.
-
-### Memoization Strategy
-
-All computed values inside `ElevasisFeaturesProvider` are wrapped in `useMemo()` with precise dependency tracking. Resolved features, nav items, shell model, organization graph, and the context value object are each memoized separately so downstream consumers only re-render when their specific inputs change.
-
-## Provider Responsibilities
-
-`ElevasisFeaturesProvider` owns:
-
-- registration of shared feature manifests
-- feature-flag-aware nav contribution
-- route-to-sidebar subshell dispatch (via `shellRuntime.resolveRoute`)
-- provider-scoped shared runtime context
-- resolved shell-model composition and shell-native route matching
-- organization-model-aware nav label and path resolution
-- resolved feature output (no legacy `shellModule` wrapper)
-
-It does **not** own:
-
-- TanStack file-based route registration
-- app branding, topbar behavior, admin entries, assistant/context glue
-
-Consumers keep thin local route wrappers and app-local nav where needed.
-
-## Runtime Flow
-
-1. The app defines a manifest list (often by spreading `FEATURE_MANIFESTS` and overriding entries).
-2. The app optionally resolves an organization model and passes it to the provider.
-3. The provider combines `useFeatureAccess()` with the org model's `features[]` array to compute enabled features.
-4. Nav labels and nav paths resolve from the matching `feature.label` in `organizationModel.features` and from `organizationModel.navigation.surfaces` when present.
-5. The provider exposes `shellModel`, `shellRuntime`, resolved feature access, `organizationGraph`, and shared runtime inputs via `useElevasisFeatures()`.
-6. `FeatureShell` calls `shellRuntime.resolveRoute(currentPath)`:
-   - `matched` -- render the feature's sidebar subshell
-   - `hidden` -- render `FeatureUnavailableState`
-   - `unmatched` -- render plain children (consumer owns the route)
-
-   A route resolves as `hidden` when the matched nav link meets either of these conditions: its `featureKey` fails the `isFeatureEnabled()` check, or its path matches an entry in `disabledSubsectionPaths`. Both checks are applied recursively through nested nav links.
-
-Consumer nav derivation runs locally from `shellModel.navItems`; the provider no longer exposes `visibleNavItems`.
-
-## Provider-Scoped Runtime Context
-
-`useElevasisFeatures()` exposes:
-
-- `shellModel` -- `{ navItems: ResolvedShellNavItem[] }` -- the full resolved nav list
-- `shellRuntime` -- `{ resolveRoute: (path) => ResolvedShellRouteMatch }` -- route dispatch
-- `resolvedFeatures` -- all `ResolvedFeatureModule[]` regardless of enabled state
-- `enabledResolvedFeatures` -- filtered to `access.enabled === true`
-- `timeRange`
-- `operationsApiUrl`, `operationsSSEManager`
-- `deliveryApiUrl`, `deliverySSEManager`
-- `organizationModel`
-- `organizationGraph` (resolved from `operations.organization-graph` surface; see [Organization Graph](../core/organization-graph.mdx))
-- `disabledSubsectionPaths` -- used by consumers like `_template` to hide specific subsections (e.g., `/settings/appearance`)
-- `isFeatureEnabled(key: string): boolean` -- checks both membership flag and organization-model feature state
-- `getResolvedFeature(key: string): ResolvedFeatureModule | undefined` -- looks up a resolved feature by its `key` field (module key, not access key)
-
-## Nav Resolution
-
-### ResolvedShellNavItem
-
-`ResolvedShellNavItem` extends `FeatureNavEntry` with two additional fields:
-
-- `placement: 'primary' | 'bottom'` -- where the item appears in the shell nav; feature manifests always produce `'primary'`; `appShellOverrides.bottomNavItems` produce `'bottom'`
-- `source: 'app' | 'feature'` -- whether the item came from a manifest (`'feature'`) or from `appShellOverrides` (`'app'`)
-- `featureId?: string` -- the feature ID associated with this nav item for gating checks
-
-`shellModel.navItems` contains the merged and filtered list of all `ResolvedShellNavItem`s from both manifest features and `appShellOverrides`.
-
-### filterNavLinks
-
-`filterNavLinks()` in `ElevasisFeaturesProvider.tsx` recursively removes gated and disabled-subsection links from a `FeatureNavLink[]` array. A link is removed if its `featureKey` fails `isFeatureEnabled()` or if its path matches any entry in `disabledSubsectionPaths`. The function recurses into nested `links` arrays before deciding whether a parent with now-empty children should be retained or dropped.
-
-## Access Resolution
-
-Shell feature-module keys map directly to feature IDs in the organization model. There is no alias layer:
-
-- `createFeatureAccessHook` is the factory that produces `useFeatureAccess`. (Old name `createUseFeatureAccess` is re-exported as `@deprecated`.)
-- `FeatureModule.featureId` must match a `feature.id` value in the org model's `features[]` array. The provider throws at startup if the ID is not found.
-- `MembershipFeatureConfig.features` is `Record<string, boolean>` -- a dynamic map keyed by feature ID. Any feature can be overridden per member without schema changes.
-- The provider fallback for missing feature access identity is retired -- explicit `featureId` is required.
-
-## Published Surface
-
-`packages/ui/src/provider/published.ts` is intentionally headless: it exports the provider, types, and hooks, but no Mantine-dependent visual provider pieces. External consumers can adopt the feature/provider contract without pulling the full internal visual surface.
-
-All nine features are published as individual subpath exports from `@elevasis/ui`:
-
-- `@elevasis/ui/features/auth` -- `ProtectedRoute`, `AdminGuard`, `FeatureGuard`, `useUserProfile` (utility feature; no manifest)
-- `@elevasis/ui/features/dashboard` -- `Dashboard`, `ResourceOverview`, `RecentExecutionsByResource`, `UnresolvedErrorsTeaser` (utility feature; no manifest)
-- `@elevasis/ui/features/crm`
-- `@elevasis/ui/features/lead-gen`
-- `@elevasis/ui/features/projects`
-- `@elevasis/ui/features/monitoring`
-- `@elevasis/ui/features/operations`
-- `@elevasis/ui/features/seo`
-- `@elevasis/ui/features/settings`
-
-The `auth` and `dashboard` features are not in `FEATURE_MANIFESTS` and are not registered with `ElevasisFeaturesProvider`. They are standalone published feature modules consumed directly by host apps.
-
-## Composition Patterns
-
-### Command-center composition
-
-`apps/command-center/src/routes/__root.tsx`:
-
-1. imports the mounted manifest list
-2. resolves `COMMAND_CENTER_ORGANIZATION_MODEL`
-3. passes manifests, organization model, time range, operations API URL, and SSE manager to `ElevasisFeaturesProvider`
-4. keeps app-local nav entries for dashboard, admin, archive (passed into `appShellOverrides`)
-5. derives filtered nav locally from `shellModel.navItems`
-6. lets `FeatureShell` dispatch subshell sidebars for matched routes
-
-### appShellOverrides
-
-`appShellOverrides` is an `AppShellOverrides` prop on `ElevasisFeaturesProvider` that lets the host app inject nav items outside the manifest registry:
-
-- `primaryNavItems?: FeatureNavEntry[]` -- prepended before feature nav items in the primary nav position; organization-model label and path resolution is applied to these entries
-- `bottomNavItems?: FeatureNavEntry[]` -- rendered at the bottom of the shell nav; also subject to organization-model resolution and `filterNavLinks` filtering
-
-Both arrays go through the same `isFeatureEnabled()` and `disabledSubsectionPaths` filtering as manifest-derived items. Items whose `featureKey` is disabled, or that have only disabled nested links and no direct `link`, are dropped entirely.
-
-Nine feature modules are published (see **Published Surface** above). Six are currently mounted in command-center: `leadGenManifest`, `crmManifest`, `projectsManifest`, `operationsManifest`, `monitoringManifest`, `settingsManifest`. The remaining three (`seoManifest`, `auth`, `dashboard`) are published but not mounted through `ElevasisFeaturesProvider` in command-center -- `auth` and `dashboard` are utility features consumed directly, while `seoManifest` is available for composition but not wired into the current command-center shell.
-
-### External-consumer composition
-
-External shells consume the published `@elevasis/ui` provider surface. `_template/ui` imports individual manifests, composes a local `FEATURE_MANIFESTS: FeatureModule[]` array, and passes `canonicalOrganizationModel` (from `@foundation/config/organization-model`) into the provider. Host-local nav (home/dashboard) remains app-owned -- the provider covers shared shell features, not total shell ownership.
-
-See [Composition & Extensibility](./composition-extensibility.mdx) for the sidebar/page override patterns consumers use to customize shared features without forking.
-
-## Feature-Specific Sidebar Behavior
-
-### CRM Sidebar
-
-The CRM sidebar (`packages/ui/src/features/crm/sidebar/`) exports `CrmSidebar`, `CrmSidebarTop`, and `CrmSidebarMiddle`. `SavedViewsPanel` lives in `packages/ui/src/features/crm/workbench/SavedViewsPanel.tsx` and is exported from the CRM workbench barrel; it provides the saved contact views panel. It is currently commented out of the default `CrmSidebarMiddle` layout while the CRM sidebar section model is being reworked, but can be re-included explicitly when composing a custom sidebar.
-
-### Operations Sidebar
-
-`OperationsSidebarTop` in `packages/ui/src/features/operations/sidebar/OperationsSidebarTop.tsx` is context-aware by route:
-
-- Returns `null` for sessions (`/operations/sessions`) and command-view (`/operations/command-view`) routes -- these sections own their own top-area UI
-- Shows a "Resource Overview" navigation button for the resources section (`/operations/resources`)
-- Returns `null` for all other paths (e.g., the operations index)
-
-This pattern avoids hardcoding sidebar top content in the parent and lets each operations sub-section declare its own top panel entry point.
-
-## Testing
-
-- `createTestFeaturesProvider` fixture at `packages/ui/src/provider/createTestFeaturesProvider.tsx` (internal; exported from `provider/index.ts`) gives tests a pre-wired provider with configurable organization model and feature access.
-- Resolver modules have focused unit tests (`RouteResolver.test.ts`, `NavResolver.test.ts`).
-- `validateManifests.test.ts` covers manifest validation against the organization model.
-- `ElevasisFeaturesProvider.test.tsx`, `FeatureShell.test.tsx`, and `feature-contract.test.ts` cover runtime composition and the published surface.
-
-## Key Conceptual Distinctions
-
-- **Platform capability vs. shell feature** -- capabilities are the product map; shell features are manifest-backed UI surfaces.
-- **Shell feature key vs. org-model feature id** -- both are the same value (e.g., `crm`). `FeatureModule.featureId` directly matches `feature.id` in the org model; there is no alias layer.
-- **Feature vs. capability** -- a feature object in the org model carries `entityIds`, `surfaceIds`, `resourceIds`, and `capabilityIds`; capabilities are one kind of semantic reference a feature can hold.
-- **Provider-owned vs. consumer-owned** -- provider owns shared manifests, nav contribution, sidebar dispatch, shared runtime context; consumers own route files, branding, topbar behavior, admin entries.
+External templates pass `canonicalOrganizationModel` into `ElevasisFeaturesProvider` and derive sidebar links locally from `shellModel`. There is no separate nav config file to keep in sync.