@elevasis/sdk 1.10.0 → 1.12.0

package/reference/scaffold/recipes/gate-by-feature-or-admin.md

@@ -1,158 +1,117 @@
----
-title: Gate by Feature or Admin
-description: Decision table and step-by-step recipes for gating routes, nav items, and UI elements by feature flag or admin role.
----
-
-# Gate by Feature or Admin
-
-End-to-end: gate a route, nav item, or UI element. Steps are sequential.
-
-See [glossary.md](../reference/glossary.md) under **FeatureGuard**, **AdminGuard**, **featureId**, **featureKey**, **Settings asymmetry**, and **MembershipFeatureConfig**. See [contracts.md](../reference/contracts.md) for `MembershipFeatureConfig` shape and the settings-asymmetry callout.
-
-For the three-concept model in full detail, see [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md).
-
----
-
-## 1. Decide: feature-level or admin-level?
-
-| Scenario                                                                         | Gate to use                                                            |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Surface should be off by default for all members, toggled org-wide or per member | `FeatureGuard` + `featureKey` on nav entry                             |
-| Surface is always visible to authenticated members but restricted to admins only | `AdminGuard` + `requiresAdmin` on nav entry                            |
-| Surface is both feature-gated and admin-only                                     | Both: `FeatureGuard` wrapping `AdminGuard`, plus both nav-entry fields |
-
-Do not substitute one for the other. `FeatureGuard` reads feature flags; `AdminGuard` reads admin role. They are independent.
-
----
-
-## 2. Feature gate -- org level
-
-Ensure a feature object with the matching `id` exists in the org model. File: `core/config/organization-model.ts`.
-
-```ts
-import { defineOrganizationModel, OPERATIONS_FEATURE_ID, SALES_FEATURE_ID } from '@elevasis/core/organization-model'
-
-// In the features[] array inside defineOrganizationModel:
-features: [
-  // ... existing features
-  { id: 'analytics', label: 'Analytics', enabled: false, entityIds: [], surfaceIds: [], resourceIds: [], capabilityIds: [] }
-]
-```
-
-Use typed constants for the 7 platform features (`SALES_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, etc.); use string literals for project-specific features you invent. In this example, `'analytics'` is a project-local feature and stays as a string literal.
-
-See [add-a-feature.md](add-a-feature.md) step 2 for the full feature object shape.
-
-Set `enabled: true` to enable for all members by default.
-
----
-
-## 3. Feature gate -- route level
-
-Wrap the route layout with `FeatureGuard` inside `ProtectedRoute`. The template-local `FeatureGuard` resolves key aliases automatically.
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
-
-function AnalyticsLayout() {
-  return (
-    <ProtectedRoute>
-      <FeatureGuard featureKey="analytics">
-        <Outlet />
-      </FeatureGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-`FeatureGuard` redirects to `/` with a Mantine notification when the feature is off. All child routes under this layout are automatically protected -- no need to repeat the guard in children.
-
-Import path: `@/features/auth/guards/FeatureGuard` (template-local). Do not import `FeatureGuard` from `@elevasis/ui/features` -- that version does not close over the local org model. See [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) for the import-paths table.
-
----
-
-## 4. Admin gate -- route level
-
-Wrap with `AdminGuard` inside `ProtectedRoute`. `AdminGuard` redirects non-admins to `redirectTo` (default `/`).
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { AdminGuard } from '@elevasis/ui/auth'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/admin')({ component: AdminLayout })
-
-function AdminLayout() {
-  return (
-    <ProtectedRoute>
-      <AdminGuard>
-        <Outlet />
-      </AdminGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-Import path: `@elevasis/ui/auth` (published). Always nest inside `ProtectedRoute` -- the guard depends on the user profile being loaded.
-
----
-
-## 5. Nav-item visibility
-
-Declare `featureKey` on the nav entry to have the shell auto-hide it when the feature is off. Declare `requiresAdmin: true` to hide it for non-admin members.
-
-```ts
-// In FeatureModule.navEntry (manifest-backed features):
-navEntry: {
-  label: 'Analytics',
-  icon: IconChartBar,
-  link: '/analytics',
-  featureKey: 'analytics'   // optional -- featureId already gates the whole module
-}
-
-// In nav-items.ts (app-local nav):
-{ label: 'Analytics', icon: IconChartBar, link: '/analytics', featureKey: 'analytics' }
-{ label: 'Admin',     icon: IconShield,   link: '/admin',     requiresAdmin: true }
-```
-
-`featureKey` on a nav entry is a display hint only -- it does not protect the route. Always pair with a route-level `FeatureGuard`. See [glossary.md](../reference/glossary.md) under **featureId vs featureKey** for the distinction. When the `featureKey` is one of the 7 platform features, prefer the typed constant (e.g., `featureKey: SALES_FEATURE_ID`) over a string literal to catch renames at compile time.
-
----
-
-## 6. Per-member override
-
-`MembershipFeatureConfig.features` (stored in `org_memberships.config`) overrides org-level defaults per member. Full shape is in [contracts.md](../reference/contracts.md#membershipfeatureconfig).
-
-```ts
-// Disable analytics for a specific member (stored in their membership record):
-{
-  features: { analytics: false }
-}
-```
-
-`MembershipFeatureConfig.features` is `Record<string, boolean>` -- a dynamic map keyed by feature ID. Any feature ID from the org model can be overridden per member without schema changes.
-
-**Settings asymmetry -- read this before writing membership config.** The `settings` feature is intentionally excluded from per-member overrides: settings access is controlled by `requiresAdmin` and `AdminGuard`, not per-member feature flags. Writing a `settings` key to `org_memberships.config` has no effect. See [contracts.md](../reference/contracts.md#membershipfeatureconfig) for the full callout, and [glossary.md](../reference/glossary.md) under **Settings asymmetry**.
-
-Membership config is read/written directly via the Supabase client (`org_memberships.config` column). There is no dedicated API route for bulk updates.
-
----
-
-## 7. Verify
-
-State matrix -- confirm each combination:
-
-| Org feature enabled | Member override | Admin     | Expected result                               |
-| ------------------- | --------------- | --------- | --------------------------------------------- |
-| true                | (absent)        | any       | Route accessible, nav visible                 |
-| true                | false           | any       | Route redirects, nav hidden                   |
-| false               | (absent)        | any       | Route redirects, nav hidden                   |
-| false               | true            | any       | Route redirects (org gate wins)               |
-| true                | (absent)        | non-admin | Admin-gated route redirects, admin nav hidden |
-| true                | (absent)        | admin     | Admin-gated route accessible, nav visible     |
-
-Check each gate independently: feature toggle in `core/config/organization-model.ts`, membership config in `org_memberships.config`, and admin status in the user profile.
+---
+title: Gate by Feature or Admin
+description: Decision table and recipes for gating routes, sidebar entries, and UI elements by Organization Model feature ID or admin role.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Gate by Feature or Admin
+
+Feature visibility starts in `core/config/organization-model.ts`. Routes still enforce access with guards.
+
+## Decide the gate
+
+| Scenario | Gate to use |
+| --- | --- |
+| Surface can be enabled or disabled per organization/member | `FeatureGuard` with the feature ID |
+| Surface is always available to members but restricted to admins | `AdminGuard` plus `requiresAdmin: true` on the feature node |
+| Surface is both feature-gated and admin-only | Both guards, plus `requiresAdmin: true` on the feature node |
+
+## Feature gate in the org model
+
+Add or update the feature in `features`.
+
+```ts
+features: [
+  {
+    id: 'analytics',
+    label: 'Analytics',
+    enabled: false,
+    path: '/analytics',
+    icon: 'chart',
+    uiPosition: 'sidebar-primary'
+  }
+]
+```
+
+Set `enabled: true` to enable it for all members by default. Dotted IDs such as `analytics.reports` inherit feature state and shell placement from their ancestors unless they declare their own value.
+
+## Route-level feature gate
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="analytics">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+The sidebar is derived from `OrganizationModel.features`; hiding a node there is display behavior only. Keep route guards in place for direct URL access.
+
+## Admin-only route
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { AdminGuard } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({ component: AdminLayout })
+
+function AdminLayout() {
+  return (
+    <ProtectedRoute>
+      <AdminGuard>
+        <Outlet />
+      </AdminGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+Pair the route guard with the feature node:
+
+```ts
+{
+  id: 'admin',
+  label: 'Admin',
+  enabled: true,
+  path: '/admin',
+  uiPosition: 'sidebar-bottom',
+  requiresAdmin: true
+}
+```
+
+## Per-member override
+
+`MembershipFeatureConfig.features` in `org_memberships.config` overrides enabled state per member.
+
+```ts
+{
+  features: { analytics: false }
+}
+```
+
+Settings and admin-only pages should use admin checks, not per-member feature flags.
+
+## Verify
+
+Check the state matrix:
+
+| Org feature enabled | Member override | Admin | Expected result |
+| --- | --- | --- | --- |
+| true | absent | any | Route accessible, sidebar visible |
+| true | false | any | Route redirects, sidebar hidden |
+| false | absent | any | Route redirects, sidebar hidden |
+| true | absent | non-admin | Admin route redirects, admin sidebar hidden |
+| true | absent | admin | Admin route accessible, admin sidebar visible |

package/reference/scaffold/recipes/index.md

@@ -2,6 +2,9 @@
 title: Pathway Recipes
 description: Terse end-to-end walkthroughs for the three most common authoring tasks -- adding a feature, adding a resource, and gating access.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Pathway Recipes