@elevasis/sdk 1.10.0 → 1.11.0

package/reference/scaffold/ui/recipes.md

@@ -1,20 +1,12 @@
 ---
 title: UI Recipes
-description: Copy-paste recipes for common UI tasks -- add a page, add a nav item, add a feature-scoped component, change theme tokens.
+description: Current recipes for adding pages, feature-gated routes, feature components, theme tokens, Organization Model sidebar entries, and executable resources.
 ---
 
 # UI Recipes
 
-**Status:** 🟢 Stable
-
-Copy-paste starting points for the five most common UI tasks. Each recipe shows the complete file contents or a tight diff first, then explains what each part does. For deeper background on auth, feature flags, or customization, follow the links at the bottom of each section.
-
----
-
 ## 1. Add a Top-Level Page
 
-### Code
-
 Create `ui/src/routes/my-feature.index.tsx`:
 
 ```tsx
@@ -42,36 +34,26 @@ function MyFeatureRouteComponent() {
 }
 ```
 
-Then add a nav entry in `ui/src/config/nav-items.ts`:
+Add the sidebar entry as a feature node in `core/config/organization-model.ts`:
 
 ```ts
-import { IconStar } from '@tabler/icons-react'
-
-export const navItems: ExtendedLinksGroupProps[] = [
-  { label: organizationModel.navigation.homeLabel, icon: IconDashboard, link: '/' },
-  { label: 'My Feature', icon: IconStar, link: '/my-feature' },  // Add this
+features: [
+  {
+    id: 'my-feature',
+    label: 'My Feature',
+    enabled: true,
+    path: '/my-feature',
+    icon: 'star',
+    uiPosition: 'sidebar-primary'
+  }
 ]
 ```
 
-### Explanation
-
-- **Route path:** TanStack Router derives the path from the filename. `my-feature.index.tsx` maps to `/my-feature/`. The `.index` suffix means this is the default child (index route), not a layout.
-- **`ProtectedRoute`:** redirects unauthenticated users to `/login?returnTo=<current-path>` and shows a full-screen loader while auth is initializing. Always wrap top-level pages with it.
-- **Layout components:** `AppTopbarAdjusterWrapper` adds the correct top padding to clear the topbar. `AppShellContentContainer` constrains the content to the main column. `PageContainer` adds consistent horizontal padding.
-- **`routeTree.gen.ts`:** TanStack Router regenerates this file on `pnpm dev`. Never edit it by hand.
-- **Nav item:** Icons come from `@tabler/icons-react`. No other icon library.
+TanStack Router derives the path from the filename. The sidebar is derived from `OrganizationModel.features`.
 
-If the page should only appear when a feature flag is enabled, add `featureKey` to the nav item and wrap the route content with `FeatureGuard` (see recipe 1a below). If the page is admin-only, add `requiresAdmin: true` to the nav item and nest `AdminGuard` inside `ProtectedRoute`.
+## 2. Add a Feature-Gated Page
 
----
-
-## 1a. Add a Feature-Gated Top-Level Page
-
-If the page should only be visible and accessible when a feature is enabled, add `featureKey` to the nav item and wrap the route component with `FeatureGuard`.
-
-### Code
-
-`ui/src/routes/my-feature.index.tsx` (change from recipe 1):
+Wrap the route with `FeatureGuard` and use the same feature ID as the org model node.
 
 ```tsx
 import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
@@ -93,29 +75,11 @@ function MyFeatureRouteComponent() {
 }
 ```
 
-`ui/src/config/nav-items.ts` (add `featureKey`):
-
-```ts
-{ label: 'My Feature', icon: IconStar, link: '/my-feature', featureKey: 'my-feature' }
-```
-
-### Explanation
+Set `enabled: false` in the feature node to hide it by default. Use `requiresAdmin: true` on the feature node plus `AdminGuard` in the route for admin-only pages.
 
-- **`featureKey` on nav item:** hides the nav entry when the feature is disabled for the organization or the current membership.
-- **`FeatureGuard` on the route:** hard-stops at the route boundary when someone navigates directly to the URL. Shows a notification and redirects to `/` when access is denied.
-- **Feature keys** are declared in `foundations/config/organization-model.ts` under `features.enabled`. Add a new key there before using it in a guard.
+## 3. Add a Nested Page
 
-For the full three-concept model (`featureKey` / `FeatureGuard` / `AdminGuard`), see `./feature-flags-and-gating.md`.
-
----
-
-## 2. Add a Nested Page
-
-Nested pages live under a layout file. The layout file holds shared guards and the `<Outlet />`. Child routes hold the actual page.
-
-### Code
-
-First, ensure the layout file exists. For a new section called `reporting`, create `ui/src/routes/reporting.tsx`:
+Create a layout file for the section and child route files under the same directory.
 
 ```tsx
 import { createFileRoute, Outlet } from '@tanstack/react-router'
@@ -134,400 +98,101 @@ function ReportingLayoutComponent() {
 }
 ```
 
-Then create the child page at `ui/src/routes/reporting/overview.index.tsx`:
-
-```tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { AppShellContentContainer, AppTopbarAdjusterWrapper, PageContainer } from '@elevasis/ui/layout'
-import { ReportingOverviewPage } from '@/features/reporting/components/ReportingOverviewPage'
-
-export const Route = createFileRoute('/reporting/overview/')({
-  component: ReportingOverviewRouteComponent
-})
-
-function ReportingOverviewRouteComponent() {
-  return (
-    <AppTopbarAdjusterWrapper>
-      <AppShellContentContainer>
-        <PageContainer>
-          <ReportingOverviewPage />
-        </PageContainer>
-      </AppShellContentContainer>
-    </AppTopbarAdjusterWrapper>
-  )
-}
-```
-
-For a page with a dynamic param (e.g., `/reporting/reports/$reportId`), name the file `reporting/reports.$reportId.index.tsx`:
+Add dotted feature nodes for the sidebar hierarchy:
 
-```tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { SubshellContentContainer, PageContainer } from '@elevasis/ui/layout'
-import { ReportDetailPage } from '@/features/reporting/components/ReportDetailPage'
-
-export const Route = createFileRoute('/reporting/reports/$reportId/')({
-  component: ReportDetailRouteComponent
-})
-
-function ReportDetailRouteComponent() {
-  const { reportId } = Route.useParams()
-
-  return (
-    <SubshellContentContainer>
-      <PageContainer>
-        <ReportDetailPage reportId={reportId} />
-      </PageContainer>
-    </SubshellContentContainer>
-  )
-}
+```ts
+{ id: 'reporting', label: 'Reporting', enabled: true, uiPosition: 'sidebar-primary' },
+{ id: 'reporting.overview', label: 'Overview', enabled: true, path: '/reporting/overview' },
+{ id: 'reporting.reports', label: 'Reports', enabled: true, path: '/reporting/reports' }
 ```
 
-### Explanation
-
-- **Layout file:** `reporting.tsx` matches the `/reporting` prefix. TanStack Router renders child routes into its `<Outlet />`. Guards placed here apply to every child automatically -- no need to repeat `ProtectedRoute` in every child.
-- **File naming convention:** `reporting/overview.index.tsx` maps to `/reporting/overview/`. The directory matches the layout prefix; the file maps to the path segment.
-- **Dynamic params:** `$reportId` in the filename becomes a typed param. `Route.useParams()` returns `{ reportId: string }` with full type safety -- no casting needed.
-- **`SubshellContentContainer` vs `AppShellContentContainer`:** use `SubshellContentContainer` inside sections that already have a shared subshell (like operations). Use `AppShellContentContainer` for top-level full-width pages.
-- **Guards in children:** if the layout already wraps `ProtectedRoute`, children do not need to repeat it. Add `FeatureGuard` in the layout if the entire section is gated.
-
----
-
-## 3. Add a Feature-Scoped Component
-
-### When to use `ui/src/features/<name>/`
-
-Create a feature directory when:
-
-- Logic is reused across two or more route files, OR
-- The feature owns its own context, custom hooks, or local state that does not belong to a single route.
-
-Keep it inline (in the route file itself, or in a one-off component file next to the route) when:
+Containers omit `path`; leaves provide `path`.
 
-- The component is used in exactly one place and has no shared state.
+## 4. Add a Feature-Scoped Component
 
-### Code
+Use `ui/src/features/<name>/` when logic is shared across routes or owns local state.
 
-Standard feature directory layout:
-
-```
+```text
 ui/src/features/reporting/
   components/
-    ReportingOverviewPage.tsx   # The top-level page component
-    ReportCard.tsx              # Smaller, reusable UI piece
+    ReportingOverviewPage.tsx
+    ReportCard.tsx
   hooks/
-    useReports.ts               # TanStack Query data hook
+    useReports.ts
   utils/
-    formatReportDate.ts         # Pure helper
-  types.ts                      # Feature-specific TypeScript types
-```
-
-`ui/src/features/reporting/hooks/useReports.ts`:
-
-```ts
-import { useQuery } from '@tanstack/react-query'
-import { useApiClient } from '@/lib/hooks/useApiClient'
-
-export function useReports() {
-  const { apiRequest, isOrganizationReady } = useApiClient()
-
-  return useQuery({
-    queryKey: ['reports'],
-    queryFn: () => apiRequest('/reports', { method: 'GET' }),
-    enabled: isOrganizationReady
-  })
-}
+    formatReportDate.ts
+  types.ts
 ```
 
-`ui/src/features/reporting/components/ReportingOverviewPage.tsx`:
+Use `@/*` imports for app-local cross-feature imports and keep route layout concerns in route files.
 
-```tsx
-import { Stack, Text } from '@mantine/core'
-import { useReports } from '../hooks/useReports'
-import { ReportCard } from './ReportCard'
-
-export function ReportingOverviewPage() {
-  const { data: reports, isLoading } = useReports()
-
-  if (isLoading) return <Text>Loading...</Text>
-
-  return (
-    <Stack>
-      {reports?.map((report) => (
-        <ReportCard key={report.id} report={report} />
-      ))}
-    </Stack>
-  )
-}
-```
+## 5. Change Theme Tokens
 
-### Explanation
-
-- **`@/*` alias:** resolves to `ui/src/*`. Use it for all cross-feature imports (e.g., `@/lib/hooks/useApiClient`, `@/features/auth`). Never use relative paths that cross feature boundaries.
-- **Server state in Query, client state in Zustand:** if data comes from an API, it belongs in a `useQuery` hook, not a Zustand slice. Zustand is for client-only UI state (open/close, selection, optimistic updates).
-- **`useApiClient`:** from `@/lib/hooks/useApiClient`. Returns `apiRequest` (an authenticated fetch wrapper) and `isOrganizationReady` (use this as `enabled` to avoid firing requests before the org is loaded).
-- **`SubshellContentContainer` / `PageContainer`:** added in the route file, not in the feature component. Feature components should be layout-agnostic -- the route decides the shell treatment.
-- **No React, no Node imports in `foundations/`:** types shared between frontend and `operations/` live in `foundations/`. Feature components live only in `ui/src/features/`.
-
----
-
-## 4. Change Theme Tokens
-
-### Code
-
-Edit `ui/src/config/theme.ts`. The most common task is changing the primary color and brand feel for the `default` preset:
+Edit `ui/src/config/theme.ts`.
 
 ```ts
-// ui/src/config/theme.ts  (diff -- change the default preset's dark token block)
-
 default: {
   label: 'Default',
-  description: 'My project brand theme',
-  colors: ['#7c3aed', '#080808', '#f2f2f5'],  // [primary, background, surface-light]
+  description: 'Project brand theme',
+  colors: ['#2563eb', '#080808', '#f2f2f5'],
   dark: {
-    primary: '#7c3aed',           // Brand color (buttons, links, accents)
-    primaryContrast: '#ffffff',   // Text on primary-colored elements
-    background: '#050507',        // Page background
-    surface: '#0f0f14',           // Cards, modals, elevated panels
-    surfaceHover: '#1a1a22',      // Hover state for surfaces
+    primary: '#2563eb',
+    primaryContrast: '#ffffff',
+    background: '#050507',
+    surface: '#0f0f14',
+    surfaceHover: '#1a1a22',
     text: '#ffffff',
     textDimmed: '#b0b0c0',
     textSubtle: '#888898',
-    border: 'rgba(255, 255, 255, 0.07)',
-    // ... keep remaining tokens
-  },
-  // light: { ... },
-  framework: {
-    defaultRadius: 'md',           // Global border radius ('xs' | 'sm' | 'md' | 'lg' | 'xl')
-    fontFamily: '"Inter", sans-serif',
-    headings: { fontFamily: '"Inter", sans-serif', fontWeight: '600' }
-  }
-}
-```
-
-To set the preset that loads by default for new users, change `defaultPreset` at the bottom of the file:
-
-```ts
-export const defaultPreset = 'default'   // was 'tactical'
-export const defaultColorScheme = 'dark' as const
-```
-
-To add a completely new named preset (selectable from appearance settings), append it to `themePresets`:
-
-```ts
-export const themePresets: Record<string, ThemePreset> = {
-  ...presets,
-  default: { /* ... */ },
-  'acme-brand': {
-    label: 'Acme Brand',
-    description: 'Acme Corp official brand',
-    colors: ['#2563eb', '#0a0a0a', '#f5f5f5'],
-    dark: {
-      primary: '#2563eb',
-      primaryContrast: '#fff',
-      background: '#0a0a0a',
-      surface: '#111827',
-      surfaceHover: '#1f2937',
-      text: '#f9fafb',
-      textDimmed: '#9ca3af',
-      textSubtle: '#6b7280',
-      border: 'rgba(255,255,255,0.08)',
-      error: '#ef4444',
-      warning: '#f59e0b',
-      success: '#10b981',
-      glassBackground: 'rgba(10, 10, 10, 0.5)',
-      glassBlur: 'blur(20px) saturate(160%)',
-      shadow: '0 1px 3px rgba(0,0,0,0.4), 0 8px 24px -8px rgba(0,0,0,0.5)',
-      cardShadow: 'inset 0 1px 0 rgba(255,255,255,0.06), 0 2px 8px rgba(0,0,0,0.3)',
-      durationFast: '150ms',
-      durationNormal: '250ms',
-      easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
-      destructiveFg: '#ffffff',
-      fontHeading: '"Inter", sans-serif',
-      fontSans: '"Inter", sans-serif'
-    },
-    light: { /* ... mirror pattern with light-mode values */ },
-    framework: { defaultRadius: 'md', fontFamily: '"Inter", sans-serif' },
-    fontImports: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap']
+    border: 'rgba(255, 255, 255, 0.07)'
   }
 }
 ```
 
-### Explanation
-
-- **All tokens flow into CSS variables automatically.** `primary` becomes `--color-primary`, `background` becomes `--color-background`, `glassBackground` becomes `--glass-background`, and so on. Every component that references those CSS variables (the sidebar, topbar, cards, modals) picks up the change immediately without touching component code.
-- **`framework` field:** maps directly to Mantine theme overrides. `defaultRadius` and `fontFamily` are the most commonly changed values. Component-level overrides can go here too (see the JSDoc in `theme.ts` for the pattern).
-- **`colors` array:** the three-element shorthand is `[primary, darkBackground, lightSurface]`. It is used by the appearance settings preview swatch only -- the actual runtime values come from `dark.*` and `light.*`.
-- **Appearance settings:** users can switch presets from the settings UI. The `defaultPreset` and `defaultColorScheme` exports set what loads for a user who has never changed their preference.
-- **`ui/src/config/README.md`:** contains the deeper guide for `background.tsx` (full-page background treatment) and `loader.tsx` (global spinner customization), which are separate from the theme preset system.
-
----
-
-## 5. Add a Nav Item
-
-Nav items live in `ui/src/config/nav-items.ts`. The current (pre-foundations-refactor) pattern is to add entries directly to the `navItems` array.
-
-### Code
-
-`ui/src/config/nav-items.ts`:
-
-```ts
-import { IconDashboard, IconChartBar, IconUsers, IconSettings } from '@tabler/icons-react'
-import { LinksGroupProps } from '@elevasis/ui/layout'
-import { organizationModel } from '@foundation/config/organization-model'
-
-export const navItems: ExtendedLinksGroupProps[] = [
-  // Top-level link (no submenu)
-  { label: organizationModel.navigation.homeLabel, icon: IconDashboard, link: '/' },
-
-  // Top-level link gated by feature flag
-  { label: 'Reporting', icon: IconChartBar, link: '/reporting', featureKey: 'reporting' },
-
-  // Group with sub-links
-  {
-    label: 'Team',
-    icon: IconUsers,
-    featureKey: 'operations',   // hides entire group when feature is off
-    links: [
-      { label: 'Members', link: '/team/members' },
-      { label: 'Roles', link: '/team/roles', featureKey: 'settings' },  // sub-link can have its own key
-    ]
-  },
-
-  // Admin-only top-level link
-  { label: 'Settings', icon: IconSettings, link: '/settings/account', requiresAdmin: true }
-]
-```
-
-### Explanation
-
-- **`featureKey`:** when set on a group, the entire group (including its sub-links) is hidden when the feature is disabled. When set on a sub-link, only that link is hidden.
-- **`requiresAdmin`:** hides the entry for non-admin users. Combine with `ProtectedRoute` + `AdminGuard` on the actual route to enforce the restriction at the route level too.
-- **Icon library:** `@tabler/icons-react` only. Never Lucide, Heroicons, or others.
-- **Dashboard entry:** `organizationModel.navigation.homeLabel` resolves to `'Dashboard'` from `foundations/config/organization-model.ts`. Use it instead of a hard-coded string so the label stays consistent with the rest of the shell.
-
-**Upcoming change (foundations-refactor Step 8):** the nav customization pattern will become cleaner. Published feature manifests will export a `CRM_ITEMS` array (and equivalents for other features), and the sidebar will accept an `items` prop to swap or extend those arrays without editing `nav-items.ts`. When that ships, `./customization.md` will show the updated pattern. For now, `nav-items.ts` is the canonical place for host-local nav additions.
-
----
-
-## Cross-References
-
-- `./index.md` -- shell architecture, auth flow, route structure overview
-- `./feature-flags-and-gating.md` -- full three-concept gating model (featureKey / FeatureGuard / AdminGuard)
-- `./customization.md` -- customizing feature sidebars and pages via manifest composition
-- `ui/src/config/README.md` -- deeper guide for theme, background, and loader config files
-- `external/_template/.claude/rules/frontend.md` -- concise agent-oriented frontend conventions
-
----
+All tokens flow into CSS variables. Change `defaultPreset` to alter the initial preset for new users.
 
 ## 6. Execute a Resource from a Surface
 
-Resources (workflows, agents, triggers) deploy to the Elevasis platform and can be triggered from any feature surface. This recipe shows how to declare the resource on a surface via the org model, share its input schema via `foundations/types/`, and render a button that executes it.
-
-### The Three Foundations Layers
-
-- **Org model** (`foundations/config/organization-model.ts`): semantic metadata -- which surfaces exist, what resources map to them, labels and colors.
-- **Entity contracts** (`foundations/types/entities.ts`): typed shapes for Project, Deal, etc. -- extend `BaseProject`, `BaseDeal` from `@elevasis/core/entities`.
-- **Resource I/O** (`foundations/types/index.ts`): Zod schemas for workflow inputs/outputs.
-
-### Code
-
-#### 1. Declare the resource on a surface
-
-`foundations/config/organization-model.ts`:
-
-```ts
-import { defineOrganizationModel, CRM_PIPELINE_SURFACE_ID } from '@elevasis/core/organization-model'
-
-export const organizationOverride = defineOrganizationModel({
-  branding: { /* ... */ },
-  resourceMappings: [
-    {
-      id: 'crm.pipeline.write-note',
-      surfaceId: CRM_PIPELINE_SURFACE_ID,
-      resourceId: 'my-project-write-note-workflow',
-      resourceType: 'workflow',
-      label: 'Write Note',
-      color: 'blue',
-      featureIds: ['crm'],
-      entityIds: ['crm.deal'],
-      capabilityIds: []
-    }
-  ]
-})
-```
-
-#### 2. Share the input schema
-
-`foundations/types/index.ts`:
+Declare the resource relationship in resource metadata:
 
 ```ts
-import { z } from 'zod'
-
-export const writeNoteInputSchema = z.object({
-  dealId: z.string(),
-  note: z.string().min(1).max(2000)
-})
-
-export type WriteNoteInput = z.infer<typeof writeNoteInputSchema>
+config: {
+  resourceId: 'write-note',
+  name: 'Write Note',
+  type: 'workflow',
+  version: '1.0.0',
+  status: 'prod',
+  links: [{ nodeId: 'feature:sales.crm', kind: 'operates-on' }],
+  category: 'production'
+}
 ```
 
-#### 3. Render the button
-
-`ui/src/features/crm/components/DealPanel.tsx`:
+Render it with `RunResourceButton`:
 
 ```tsx
 import { RunResourceButton } from '@elevasis/ui/components'
-import { organizationModel } from '@foundation/config/organization-model'
 import { writeNoteInputSchema } from '@foundation/types'
 
 export function DealPanel({ dealId }: { dealId: string }) {
   return (
     <RunResourceButton
-      resourceId="my-project-write-note-workflow"
+      resourceId="write-note"
       resourceType="workflow"
-      organizationModel={organizationModel}
+      label="Write Note"
       getInput={() => ({
         schema: writeNoteInputSchema,
         defaults: { dealId }
       })}
-      onSuccess={(result) => console.log('Started:', result.executionId)}
     />
   )
 }
 ```
 
-The three `getInput` shapes:
+`links[].nodeId` binds the resource into the Organization Model graph. `category` drives operational filtering for production, diagnostic, internal, and testing resources.
 
-```tsx
-// Plain object (no form) -- executes immediately on click
-getInput={() => ({ dealId, note: 'Auto-generated' })}
-
-// Mixed (form for unfixed fields) -- modal opens with dealId pre-filled
-getInput={() => ({ schema: writeNoteInputSchema, defaults: { dealId } })}
-
-// Full form -- modal opens with all fields blank
-getInput={() => ({ schema: writeNoteInputSchema })}
-```
-
-#### 4. Optionally listen for live execution logs
-
-```tsx
-import { useExecutionLogSSE, useMergedExecution } from '@elevasis/ui/hooks'
-// Pass the SSE manager from your app's sse.ts wrapper and apiUrl from config.
-// For the full live-logs pattern see:
-// apps/command-center/src/features/operations/executions/
-```
-
-### How It Works
-
-- `RunResourceButton` inspects what `getInput()` returns: a plain object triggers execution immediately; `{ schema, defaults? }` opens a `ZodFormRenderer` modal so the user can fill in missing fields before submitting.
-- Label and color resolve in order: explicit props > `resourceMappings` entry matching `resourceId` > default `'Run'`. The `icon` prop is prop-only and is never inferred from the mapping.
-- `ZodFormRenderer` introspects the Zod schema at runtime and renders Mantine fields for each top-level key. Unsupported Zod types (nested objects, arrays, unions) fall back to a JSON textarea so the form always renders regardless of schema complexity.
-- Typed feature and surface constants (e.g. `CRM_PIPELINE_SURFACE_ID`) come from `@elevasis/core/organization-model`. See Issue 4 constants for the full list.
-- Entity contracts (Deal, Project) live in `foundations/types/entities.ts` and extend base types from `@elevasis/core/entities` -- see the entity recipe for the full shape.
-
-### Cross-References
+## Cross-References
 
-- `./feature-flags-and-gating.md` -- gating a surface or button by feature key or admin role
-- `@foundation/types/entities.ts` -- Deal, Project, and other entity contracts for this project
-- Recipe 5 (Add a Nav Item) -- how surfaces and nav entries are wired together
+- `./feature-flags-and-gating.md` -- feature and admin access model
+- `./feature-shell.mdx` -- provider and sidebar derivation
+- `./customization.md` -- feature sidebar customization
+- `ui/src/config/README.md` -- theme, background, and loader config