@elevasis/sdk 1.4.0 → 1.5.1

package/reference/scaffold/ui/recipes.md

@@ -0,0 +1,418 @@
+---
+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.
+---
+
+# 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
+import { createFileRoute } from '@tanstack/react-router'
+import { ProtectedRoute } from '@/features/auth'
+import { AppShellContentContainer, AppTopbarAdjusterWrapper, PageContainer } from '@elevasis/ui/layout'
+import { MyFeaturePage } from '@/features/my-feature/components/MyFeaturePage'
+
+export const Route = createFileRoute('/my-feature/')({
+  component: MyFeatureRouteComponent
+})
+
+function MyFeatureRouteComponent() {
+  return (
+    <ProtectedRoute>
+      <AppTopbarAdjusterWrapper>
+        <AppShellContentContainer>
+          <PageContainer>
+            <MyFeaturePage />
+          </PageContainer>
+        </AppShellContentContainer>
+      </AppTopbarAdjusterWrapper>
+    </ProtectedRoute>
+  )
+}
+```
+
+Then add a nav entry in `ui/src/config/nav-items.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
+]
+```
+
+### 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.
+
+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`.
+
+---
+
+## 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):
+
+```tsx
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+
+function MyFeatureRouteComponent() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="my-feature">
+        <AppTopbarAdjusterWrapper>
+          <AppShellContentContainer>
+            <PageContainer>
+              <MyFeaturePage />
+            </PageContainer>
+          </AppShellContentContainer>
+        </AppTopbarAdjusterWrapper>
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`ui/src/config/nav-items.ts` (add `featureKey`):
+
+```ts
+{ label: 'My Feature', icon: IconStar, link: '/my-feature', featureKey: 'my-feature' }
+```
+
+### Explanation
+
+- **`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.
+
+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`:
+
+```tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { ProtectedRoute } from '@/features/auth'
+
+export const Route = createFileRoute('/reporting')({
+  component: ReportingLayoutComponent
+})
+
+function ReportingLayoutComponent() {
+  return (
+    <ProtectedRoute>
+      <Outlet />
+    </ProtectedRoute>
+  )
+}
+```
+
+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`:
+
+```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>
+  )
+}
+```
+
+### 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:
+
+- The component is used in exactly one place and has no shared state.
+
+### Code
+
+Standard feature directory layout:
+
+```
+ui/src/features/reporting/
+  components/
+    ReportingOverviewPage.tsx   # The top-level page component
+    ReportCard.tsx              # Smaller, reusable UI piece
+  hooks/
+    useReports.ts               # TanStack Query data hook
+  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 '@/shared/api'
+
+export function useReports() {
+  const { apiRequest, isOrganizationReady } = useApiClient()
+
+  return useQuery({
+    queryKey: ['reports'],
+    queryFn: () => apiRequest('/reports', { method: 'GET' }),
+    enabled: isOrganizationReady
+  })
+}
+```
+
+`ui/src/features/reporting/components/ReportingOverviewPage.tsx`:
+
+```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>
+  )
+}
+```
+
+### Explanation
+
+- **`@/*` alias:** resolves to `ui/src/*`. Use it for all cross-feature imports (e.g., `@/shared/api`, `@/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 `@/shared/api`. 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:
+
+```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]
+  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
+    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']
+  }
+}
+```
+
+### 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