@elevasis/sdk 1.10.0 → 1.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli.cjs +22 -142
- package/dist/index.d.ts +127 -154
- package/dist/index.js +15 -139
- package/dist/test-utils/index.d.ts +59 -62
- package/dist/worker/index.js +4 -2
- package/package.json +2 -2
- package/reference/deployment/provided-features.mdx +40 -267
- package/reference/examples/organization-model.ts +96 -564
- package/reference/packages/core/src/organization-model/README.md +101 -97
- package/reference/resources/types.mdx +72 -163
- package/reference/scaffold/core/organization-graph.mdx +89 -272
- package/reference/scaffold/core/organization-model.mdx +149 -320
- package/reference/scaffold/recipes/add-a-feature.md +102 -158
- package/reference/scaffold/recipes/add-a-resource.md +85 -158
- package/reference/scaffold/recipes/customize-organization-model.md +141 -400
- package/reference/scaffold/recipes/gate-by-feature-or-admin.md +114 -158
- package/reference/scaffold/reference/contracts.md +62 -148
- package/reference/scaffold/reference/feature-registry.md +8 -8
- package/reference/scaffold/reference/glossary.md +71 -105
- package/reference/scaffold/ui/feature-flags-and-gating.md +27 -232
- package/reference/scaffold/ui/feature-shell.mdx +50 -219
- package/reference/scaffold/ui/recipes.md +62 -397
|
@@ -11,13 +11,13 @@ description: Auto-generated catalog of registered feature manifests. Do not edit
|
|
|
11
11
|
|
|
12
12
|
| Feature Key | Feature ID | Nav Label | Domains | Routes |
|
|
13
13
|
| --- | --- | --- | --- | --- |
|
|
14
|
-
| `crm` | `crm` |
|
|
15
|
-
| `delivery` | `—` |
|
|
16
|
-
| `lead-gen` | `lead-gen` |
|
|
17
|
-
| `monitoring` | `monitoring` |
|
|
18
|
-
| `operations` | `operations` |
|
|
19
|
-
| `seo` | `seo` | — | — |
|
|
20
|
-
| `settings` | `settings` |
|
|
14
|
+
| `crm` | `sales.crm` | — | — | — |
|
|
15
|
+
| `delivery` | `—` | — | — | — |
|
|
16
|
+
| `lead-gen` | `sales.lead-gen` | — | — | — |
|
|
17
|
+
| `monitoring` | `monitoring` | — | — | — |
|
|
18
|
+
| `operations` | `operations` | — | — | — |
|
|
19
|
+
| `seo` | `seo` | — | — | — |
|
|
20
|
+
| `settings` | `settings` | — | — | — |
|
|
21
21
|
|
|
22
22
|
> **Note:** `auth` and `dashboard` are not in the registry — they are app-shell concerns, not gated features.
|
|
23
23
|
|
|
@@ -27,7 +27,7 @@ Feature IDs defined in `DEFAULT_ORGANIZATION_MODEL.features` (`packages/core/src
|
|
|
27
27
|
|
|
28
28
|
```typescript
|
|
29
29
|
// FeatureSchema: { id, label, enabled, color?, icon?, entityIds, surfaceIds, resourceIds, capabilityIds }
|
|
30
|
-
type DefaultFeatureId = 'submitted-requests'
|
|
30
|
+
type DefaultFeatureId = 'dashboard' | 'sales' | 'sales.crm' | 'sales.lead-gen' | 'projects' | 'operations' | 'operations.graph' | 'operations.command-view' | 'operations.overview' | 'operations.resources' | 'operations.command-queue' | 'operations.sessions' | 'operations.task-scheduler' | 'monitoring' | 'monitoring.activity-log' | 'monitoring.execution-logs' | 'monitoring.execution-health' | 'monitoring.cost-analytics' | 'monitoring.notifications' | 'monitoring.submitted-requests' | 'settings' | 'settings.account' | 'settings.appearance' | 'settings.organization' | 'settings.credentials' | 'settings.api-keys' | 'settings.webhooks' | 'settings.deployments' | 'admin' | 'admin.system-health' | 'admin.organizations' | 'admin.users' | 'admin.design-showcase' | 'admin.debug' | 'archive' | 'archive.agent-chat' | 'archive.execution-runner' | 'seo'
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
These are the built-in feature IDs. The `featureId` field on a `FeatureModule` manifest must match the `id` of a feature in the organization model to enable access-flag gating.
|
|
@@ -1,105 +1,71 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Glossary
|
|
3
|
-
description: Terminology disambiguation for Organization OS concepts used in the template scaffold,
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Glossary
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
**
|
|
17
|
-
|
|
18
|
-
**
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
**
|
|
23
|
-
|
|
24
|
-
**
|
|
25
|
-
|
|
26
|
-
**
|
|
27
|
-
|
|
28
|
-
**
|
|
29
|
-
|
|
30
|
-
**
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
**
|
|
37
|
-
|
|
38
|
-
**
|
|
39
|
-
|
|
40
|
-
**
|
|
41
|
-
|
|
42
|
-
**
|
|
43
|
-
|
|
44
|
-
**
|
|
45
|
-
|
|
46
|
-
**
|
|
47
|
-
|
|
48
|
-
**
|
|
49
|
-
|
|
50
|
-
**
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
**Settings asymmetry** -- `settings` is a valid feature ID (org-level, present in `OrganizationModel.features` with `enabled: true` by default). `MembershipFeatureConfig.features` is now `Record<string, boolean>`, so `settings` can technically be overridden per member, but the convention is still to gate settings visibility via `requiresAdmin` on the nav entry and `AdminGuard` on routes rather than per-member feature overrides.
|
|
73
|
-
|
|
74
|
-
**Subshell / Sidebar** -- the feature-scoped UI region rendered when the current route matches a manifest's `subshellRoutes`. Each `FeatureModule.sidebar` is a `ComponentType`. Consumers customize by composing the feature's published sidebar primitives (`CrmSidebar`, `CrmSidebarMiddle`, etc.) and assigning their component to `manifest.sidebar`.
|
|
75
|
-
|
|
76
|
-
**Surface** -- a navigable view in `OrganizationModel.navigation.surfaces`. Identified by a dotted `id` (e.g., `sales.pipeline`). Has `path`, `surfaceType`, optional `featureId` gate (replaces the former `featureKey` field), and cross-reference arrays (`featureIds`, `entityIds`, `resourceIds`, `capabilityIds`). Distinct from "page": a surface is the org-model declaration; a page is the React component rendered at the route.
|
|
77
|
-
|
|
78
|
-
**Topology** -- resource relationships (`triggers`, `uses`, `approval`) declared in `DeploymentSpec.relationships` and `HumanCheckpointDefinition.routesTo`. Used for Command View graph edges.
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
## Package-Boundary Cheat Sheet
|
|
83
|
-
|
|
84
|
-
**`@elevasis/core`** (published npm)
|
|
85
|
-
|
|
86
|
-
- `OrganizationModel`, `OrganizationModelFeature`, `OrganizationModelSurface`, `OrganizationModelResourceMapping`
|
|
87
|
-
- `OrganizationModelIdentity`, `OrganizationModelCustomers`, `OrganizationModelOfferings`, `OrganizationModelRoles`, `OrganizationModelGoals`
|
|
88
|
-
- `OrganizationModelStatuses`, `OrganizationModelOperations`
|
|
89
|
-
- `TechStackEntrySchema`, `OrganizationModelTechStackEntry`
|
|
90
|
-
- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
|
|
91
|
-
- `MembershipFeatureConfig`
|
|
92
|
-
|
|
93
|
-
**`@elevasis/ui`** (published npm)
|
|
94
|
-
|
|
95
|
-
- `FeatureModule`, `FeatureNavEntry`, `FeatureNavLink`
|
|
96
|
-
- `ResolvedFeatureModule`, `ResolvedShellNavItem`
|
|
97
|
-
- `FeatureGuard`, `AdminGuard`, `ProtectedRoute`
|
|
98
|
-
- `ElevasisFeaturesProvider`, `ElevasisCoreProvider`, `useElevasisFeatures`
|
|
99
|
-
- `createFeatureAccessHook`
|
|
100
|
-
|
|
101
|
-
**`foundations/`** (local source package -- not published)
|
|
102
|
-
|
|
103
|
-
- `canonicalOrganizationModel` -- passed to `ElevasisFeaturesProvider`
|
|
104
|
-
- `organizationModel` -- enriched shape for app-local code
|
|
105
|
-
- Workflow I/O schemas (`types/index.ts`)
|
|
1
|
+
---
|
|
2
|
+
title: Glossary
|
|
3
|
+
description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Glossary
|
|
7
|
+
|
|
8
|
+
## Terms
|
|
9
|
+
|
|
10
|
+
**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
|
|
11
|
+
|
|
12
|
+
**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
|
|
13
|
+
|
|
14
|
+
**DeploymentSpec** -- resource collection for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints.
|
|
15
|
+
|
|
16
|
+
**Feature** -- either a platform capability, a shell `FeatureModule`, or an Organization Model feature node. In the current shell contract, Organization Model feature nodes drive sidebar hierarchy and access state.
|
|
17
|
+
|
|
18
|
+
**FeatureGuard** -- route-level feature gate from `@elevasis/ui/features/auth`.
|
|
19
|
+
|
|
20
|
+
**FeatureModule** -- manifest contract a shell feature provides to `ElevasisFeaturesProvider`. Key fields are `key`, `featureId`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional graph bridge metadata.
|
|
21
|
+
|
|
22
|
+
**featureId** -- the `FeatureModule` field that must match an `OrganizationModel.features[].id`.
|
|
23
|
+
|
|
24
|
+
**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
|
|
25
|
+
|
|
26
|
+
**Graph node ID** -- kind-prefixed cross-collection identifier such as `feature:sales.crm`, `integration:instantly`, or `resource:lead-import`.
|
|
27
|
+
|
|
28
|
+
**Manifest** -- a runtime declaration for a feature or resource collection.
|
|
29
|
+
|
|
30
|
+
**MembershipFeatureConfig** -- per-member feature override config: `{ features?: Record<string, boolean> }`.
|
|
31
|
+
|
|
32
|
+
**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `features`, `branding`, `navigation`, `sales`, `prospecting`, `projects`, `identity`, `customers`, `offerings`, `roles`, `goals`, `statuses`, and `operations`.
|
|
33
|
+
|
|
34
|
+
**OrganizationModelFeature** -- feature node in `OrganizationModel.features`. Fields include `id`, `label`, `description`, `enabled`, `path`, `icon`, `color`, `uiPosition`, `requiresAdmin`, and `devOnly`.
|
|
35
|
+
|
|
36
|
+
**Provider / ElevasisFeaturesProvider** -- runtime that registers manifests, resolves feature access against the org model, and exposes shell helpers through `useElevasisFeatures()`.
|
|
37
|
+
|
|
38
|
+
**Resource** -- deployable workflow, agent, trigger, integration, external resource, or human checkpoint in a `DeploymentSpec`. Resources bind to the Organization Model graph through metadata `links` and are grouped for operations with `category`.
|
|
39
|
+
|
|
40
|
+
**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
|
|
41
|
+
|
|
42
|
+
**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
|
|
43
|
+
|
|
44
|
+
**Settings asymmetry** -- settings is a feature node, but individual access is normally governed by admin checks rather than user-facing feature toggles.
|
|
45
|
+
|
|
46
|
+
**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `features`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `uiPositionFor`, `requiresAdminFor`, and `devOnlyFor`.
|
|
47
|
+
|
|
48
|
+
**Subshell / Sidebar** -- feature-scoped UI region rendered when the current route matches a feature whose manifest supplies a sidebar.
|
|
49
|
+
|
|
50
|
+
**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
|
|
51
|
+
|
|
52
|
+
## Package Boundary
|
|
53
|
+
|
|
54
|
+
**`@elevasis/core`**
|
|
55
|
+
|
|
56
|
+
- `OrganizationModel`, `OrganizationModelFeature`
|
|
57
|
+
- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
|
|
58
|
+
- `MembershipFeatureConfig`
|
|
59
|
+
- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
|
|
60
|
+
|
|
61
|
+
**`@elevasis/ui`**
|
|
62
|
+
|
|
63
|
+
- `FeatureModule`
|
|
64
|
+
- `FeatureGuard`, `AdminGuard`, `ProtectedRoute`
|
|
65
|
+
- `ElevasisFeaturesProvider`, `ElevasisCoreProvider`, `useElevasisFeatures`
|
|
66
|
+
|
|
67
|
+
**External project source**
|
|
68
|
+
|
|
69
|
+
- `canonicalOrganizationModel`
|
|
70
|
+
- `organizationModel`
|
|
71
|
+
- workflow I/O schemas
|
|
@@ -1,251 +1,46 @@
|
|
|
1
|
-
|
|
2
|
-
title: Feature Flags & Gating
|
|
3
|
-
description: End-to-end recipe for the three gating concepts -- featureKey nav visibility, FeatureGuard route gate, AdminGuard / requiresAdmin. One doc resolves confusion that scored 2/5 in scaffold eval.
|
|
4
|
-
---
|
|
1
|
+
# Feature Flags And Gating
|
|
5
2
|
|
|
6
|
-
|
|
3
|
+
Feature visibility is keyed by Organization Model feature ID.
|
|
7
4
|
|
|
8
|
-
|
|
5
|
+
## Where Visibility Comes From
|
|
9
6
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
7
|
+
- `features[].enabled` in the organization model defines the baseline.
|
|
8
|
+
- Membership feature config can override individual feature IDs.
|
|
9
|
+
- `requiresAdmin` hides sidebar entries from non-admins.
|
|
10
|
+
- `devOnly` hides sidebar entries outside development mode.
|
|
13
11
|
|
|
14
|
-
|
|
12
|
+
The shell derives visible sidebar entries from `shellModel.topLevel()` and `shellModel.childrenOf(id)`.
|
|
15
13
|
|
|
16
|
-
##
|
|
14
|
+
## Route Guards
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
| Concept | What it gates | Where it applies | How it works |
|
|
21
|
-
| ------------------------------ | -------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
22
|
-
| `featureKey` on a nav entry | Whether a nav item is visible in the sidebar | `navEntry` in a feature manifest or `nav-items.ts` | The shell reads the organization model and hides items whose `featureKey` is disabled |
|
|
23
|
-
| `FeatureGuard` component | Whether a route subtree is accessible | Route layout files (`ui/src/routes/*.tsx`) | Reads org + membership access and redirects with a notification if the feature is off |
|
|
24
|
-
| `AdminGuard` / `requiresAdmin` | Whether an admin-only surface is accessible | Route layout files and manifest nav entries | Reads `profile.is_platform_admin`; redirects non-admins to `/` |
|
|
25
|
-
|
|
26
|
-
The three concepts work together but are independent. Hiding a nav item does not protect a route -- you must also wrap the route in `FeatureGuard`. Showing a nav item does not grant access.
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
## End-to-End Chain
|
|
31
|
-
|
|
32
|
-
This section walks through the template's feature gating flow. Features are declared as objects in
|
|
33
|
-
the org model with a direct `id` field. `FeatureModule.featureId` matches that `id` exactly -- no
|
|
34
|
-
alias layer exists.
|
|
35
|
-
|
|
36
|
-
If you need a brand-new feature such as `analytics`, add a feature object to the `features[]`
|
|
37
|
-
defaults array in the org model and author a matching manifest. See [add-a-feature.md](../recipes/add-a-feature.md).
|
|
38
|
-
|
|
39
|
-
### Step 1: Declare the feature in `organization-model.ts`
|
|
40
|
-
|
|
41
|
-
File: `foundations/config/organization-model.ts`
|
|
42
|
-
|
|
43
|
-
```ts
|
|
44
|
-
const foundationOrganizationModelOverride = defineOrganizationModel({
|
|
45
|
-
features: [
|
|
46
|
-
{ id: 'crm', label: 'CRM', enabled: true, entityIds: [...], surfaceIds: [...] },
|
|
47
|
-
{ id: 'lead-gen', label: 'Lead Gen', enabled: true, entityIds: [...], surfaceIds: [...] },
|
|
48
|
-
{ id: 'projects', label: 'Projects', enabled: true, entityIds: [...], surfaceIds: [...] },
|
|
49
|
-
// ... other features
|
|
50
|
-
],
|
|
51
|
-
// ... rest of model
|
|
52
|
-
})
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
The `features[]` array is the source of truth for org-model gates. The 7 default feature IDs are
|
|
56
|
-
`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, and `seo`. Each feature
|
|
57
|
-
object's `enabled` field controls whether that feature is on by default for the org.
|
|
58
|
-
|
|
59
|
-
### Step 2: Wire `featureKey` on a nav item
|
|
60
|
-
|
|
61
|
-
Nav items come from one of two places: the manifest `navEntry` (for features registered through `ElevasisFeaturesProvider`) or the local `nav-items.ts` config (for app-local nav).
|
|
62
|
-
|
|
63
|
-
**Manifest nav entry** (preferred for platform features):
|
|
64
|
-
|
|
65
|
-
```ts
|
|
66
|
-
// Published shared manifest
|
|
67
|
-
import type { FeatureModule } from '@elevasis/ui/provider'
|
|
68
|
-
import { crmManifest } from '@elevasis/ui/features/crm'
|
|
69
|
-
|
|
70
|
-
const manifest: FeatureModule = crmManifest
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
`featureId` on the `FeatureModule` is what drives whether the entire shared feature (including its
|
|
74
|
-
nav entry) is visible. Each manifest sets `featureId` to the matching `feature.id` value from the
|
|
75
|
-
org model (e.g., `crmManifest.featureId = 'crm'`, `leadGenManifest.featureId = 'lead-gen'`,
|
|
76
|
-
`projectsManifest.featureId = 'projects'`). The shell hides the nav entry when org or membership
|
|
77
|
-
access disables that feature ID.
|
|
78
|
-
|
|
79
|
-
**Local nav-items.ts** (for one-off items not part of a registered feature):
|
|
80
|
-
|
|
81
|
-
```ts
|
|
82
|
-
// ui/src/config/nav-items.ts
|
|
83
|
-
export const navItems: ExtendedLinksGroupProps[] = [
|
|
84
|
-
{ label: 'Dashboard', icon: IconDashboard, link: '/' },
|
|
85
|
-
{ label: 'CRM', icon: IconBriefcase, link: '/crm', featureKey: 'crm' }
|
|
86
|
-
]
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
When `featureKey` is set on a nav item in `nav-items.ts`, the shell hides that item if
|
|
90
|
-
`isFeatureEnabled(featureKey)` returns false. The key must match a `feature.id` value in the org
|
|
91
|
-
model -- no alias mapping is applied.
|
|
92
|
-
|
|
93
|
-
### Step 3: Wrap the route in `FeatureGuard`
|
|
94
|
-
|
|
95
|
-
File: `ui/src/routes/crm.tsx` (TanStack Router layout file for the `/crm` subtree)
|
|
16
|
+
Navigation visibility is cosmetic. Always guard routes directly:
|
|
96
17
|
|
|
97
18
|
```tsx
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
component: RouteComponent
|
|
104
|
-
})
|
|
105
|
-
|
|
106
|
-
function RouteComponent() {
|
|
107
|
-
return (
|
|
108
|
-
<ProtectedRoute>
|
|
109
|
-
<FeatureGuard featureKey="crm">
|
|
110
|
-
<Outlet />
|
|
111
|
-
</FeatureGuard>
|
|
112
|
-
</ProtectedRoute>
|
|
113
|
-
)
|
|
114
|
-
}
|
|
19
|
+
<ProtectedRoute>
|
|
20
|
+
<FeatureGuard featureKey="sales.crm">
|
|
21
|
+
<Outlet />
|
|
22
|
+
</FeatureGuard>
|
|
23
|
+
</ProtectedRoute>
|
|
115
24
|
```
|
|
116
25
|
|
|
117
|
-
|
|
118
|
-
(the template's wrapper around `createFeatureAccessHook`), checks the effective org-plus-membership
|
|
119
|
-
access, and redirects to `/` with a Mantine notification if the feature is off. The layout pattern
|
|
120
|
-
means every child route under `/crm` is automatically protected without repeating the guard.
|
|
121
|
-
|
|
122
|
-
All existing feature routes in the template follow this exact pattern: `operations.tsx`,
|
|
123
|
-
`projects.tsx`, `lead-gen.tsx`, `crm.tsx`, and `monitoring.tsx`.
|
|
124
|
-
|
|
125
|
-
### Step 4: Check in a component via `useFeatureAccess`
|
|
126
|
-
|
|
127
|
-
For conditional UI within a component (showing or hiding a button, panel, or section based on a feature flag), use the `useFeatureAccess` hook directly.
|
|
26
|
+
For admin-only routes:
|
|
128
27
|
|
|
129
28
|
```tsx
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
const { hasFeature } = useFeatureAccess()
|
|
134
|
-
|
|
135
|
-
return (
|
|
136
|
-
<div>
|
|
137
|
-
<CoreMetrics />
|
|
138
|
-
{hasFeature('crm') && <CrmSummaryPanel />}
|
|
139
|
-
</div>
|
|
140
|
-
)
|
|
141
|
-
}
|
|
29
|
+
<AdminGuard>
|
|
30
|
+
<SystemHealthPage />
|
|
31
|
+
</AdminGuard>
|
|
142
32
|
```
|
|
143
33
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
The hook is defined in `ui/src/lib/hooks/useFeatureAccess.ts`. It wraps
|
|
147
|
-
`createFeatureAccessHook` from `@elevasis/ui/hooks` and resolves feature IDs directly against the
|
|
148
|
-
org model's `features[]` array -- no alias mapping is applied.
|
|
149
|
-
|
|
150
|
-
---
|
|
151
|
-
|
|
152
|
-
## Admin Gating
|
|
153
|
-
|
|
154
|
-
Admin gating is separate from feature gating. It restricts surfaces to users with `profile.is_platform_admin === true`.
|
|
155
|
-
|
|
156
|
-
### `requiresAdmin` on a manifest nav entry
|
|
34
|
+
## Adding A Gated Feature
|
|
157
35
|
|
|
158
36
|
```ts
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
label: '
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
}
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
Setting `requiresAdmin: true` on a `FeatureNavEntry` causes the shell to hide that nav item for non-admin users. This is purely a visibility concern -- the route is still accessible by URL. Always combine with a route-level `AdminGuard`.
|
|
169
|
-
|
|
170
|
-
### `AdminGuard` in a route
|
|
171
|
-
|
|
172
|
-
```tsx
|
|
173
|
-
// ui/src/routes/admin.tsx
|
|
174
|
-
import { ProtectedRoute } from '@/features/auth'
|
|
175
|
-
import { AdminGuard } from '@elevasis/ui/auth'
|
|
176
|
-
import { createFileRoute, Outlet } from '@tanstack/react-router'
|
|
177
|
-
|
|
178
|
-
export const Route = createFileRoute('/admin')({
|
|
179
|
-
component: RouteComponent
|
|
180
|
-
})
|
|
181
|
-
|
|
182
|
-
function RouteComponent() {
|
|
183
|
-
return (
|
|
184
|
-
<ProtectedRoute>
|
|
185
|
-
<AdminGuard fallback={<AppShellLoader />}>
|
|
186
|
-
<Outlet />
|
|
187
|
-
</AdminGuard>
|
|
188
|
-
</ProtectedRoute>
|
|
189
|
-
)
|
|
190
|
-
}
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
`AdminGuard` reads `profile.is_platform_admin` from the initialization context. Non-admins are redirected to `redirectTo` (default `/`). Always nest inside `ProtectedRoute` so that the user profile is loaded before the guard runs.
|
|
194
|
-
|
|
195
|
-
### `AdminGuard` in a component
|
|
196
|
-
|
|
197
|
-
```tsx
|
|
198
|
-
import { AdminGuard } from '@elevasis/ui/auth'
|
|
199
|
-
|
|
200
|
-
function SettingsPage() {
|
|
201
|
-
return (
|
|
202
|
-
<>
|
|
203
|
-
<GeneralSettings />
|
|
204
|
-
<AdminGuard>
|
|
205
|
-
<DangerZone />
|
|
206
|
-
</AdminGuard>
|
|
207
|
-
</>
|
|
208
|
-
)
|
|
37
|
+
{
|
|
38
|
+
id: 'analytics',
|
|
39
|
+
label: 'Analytics',
|
|
40
|
+
enabled: true,
|
|
41
|
+
path: '/analytics',
|
|
42
|
+
uiPosition: 'sidebar-primary'
|
|
209
43
|
}
|
|
210
44
|
```
|
|
211
45
|
|
|
212
|
-
Use
|
|
213
|
-
|
|
214
|
-
### When to use each
|
|
215
|
-
|
|
216
|
-
- `requiresAdmin` on `navEntry`: hide the nav item for non-admins (cosmetic only, always pair with route guard)
|
|
217
|
-
- `AdminGuard` wrapping a route's `Outlet`: protect the entire route subtree
|
|
218
|
-
- `AdminGuard` wrapping a component section: protect part of a page
|
|
219
|
-
|
|
220
|
-
---
|
|
221
|
-
|
|
222
|
-
## Import Paths
|
|
223
|
-
|
|
224
|
-
| Symbol | Import path | Notes |
|
|
225
|
-
| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
226
|
-
| `FeatureGuard` | `@/features/auth/guards/FeatureGuard` | Template-local wrapper; uses `useFeatureAccess` from `@/lib/hooks/useFeatureAccess` |
|
|
227
|
-
| `AdminGuard` | `@elevasis/ui/auth` | Published from `@elevasis/ui` |
|
|
228
|
-
| `useFeatureAccess` | `@/lib/hooks/useFeatureAccess` | Template-local wrapper around `createFeatureAccessHook` from `@elevasis/ui/hooks` |
|
|
229
|
-
| `createFeatureAccessHook` | `@elevasis/ui/hooks` | Factory for building a feature-access hook; already consumed by the template wrapper |
|
|
230
|
-
| `ProtectedRoute` | `@elevasis/ui/auth` or `@/features/auth` | Ensures user is authenticated before any guard runs |
|
|
231
|
-
|
|
232
|
-
The template's `FeatureGuard` (`@/features/auth/guards/FeatureGuard`) is not the same as the published `FeatureGuard` from `@elevasis/ui/features`. The template version closes over the local `useFeatureAccess` hook and the resolved org model, so it checks feature IDs against your project's feature array. Use the template-local version.
|
|
233
|
-
|
|
234
|
-
---
|
|
235
|
-
|
|
236
|
-
## Common Mistakes
|
|
237
|
-
|
|
238
|
-
- **Using a feature ID that does not exist in the org model.** `FeatureModule.featureId` and
|
|
239
|
-
`featureKey` on nav entries must match a `feature.id` value in the org model's `features[]`
|
|
240
|
-
array. The provider throws at startup if an unknown ID is declared. To add a brand-new feature
|
|
241
|
-
such as `analytics`, first add it to the `features[]` array in `foundations/config/organization-model.ts`.
|
|
242
|
-
|
|
243
|
-
- **Using `FeatureGuard` on a nav item instead of a route.** `FeatureGuard` is a React component that redirects on mount. Placing it inside a nav item or link will fire a redirect whenever the sidebar renders. Gate nav visibility with `featureKey` on the nav entry or `featureId` on the manifest; gate route access with `FeatureGuard` in the route layout.
|
|
244
|
-
|
|
245
|
-
- **Confusing `requiresAdmin` with `AdminGuard`.** `requiresAdmin` on a `FeatureNavEntry` is a display hint read by the shell nav renderer -- it hides the nav item but does not block the route. `AdminGuard` is a React component that actively redirects. You need both if you want the nav hidden and the route blocked.
|
|
246
|
-
|
|
247
|
-
- **Placing `FeatureGuard` or `AdminGuard` outside `ProtectedRoute`.** Both guards depend on the user profile being loaded. Unauthenticated users will see a redirect loop or a blank screen if the profile is not yet available. Always nest guards inside `ProtectedRoute`.
|
|
248
|
-
|
|
249
|
-
- **Using `hasFeature` from `useFeatureAccess` as a route guard.** `hasFeature` is for conditional
|
|
250
|
-
rendering inside components. A user can still navigate directly to a URL and reach the route
|
|
251
|
-
component. Use `FeatureGuard` in the route file for actual access control.
|
|
46
|
+
Use the same ID in `FeatureGuard featureKey` and `FeatureModule.featureId`.
|