Initial Commit

openspec/changes/enterprise-react-permissions/proposal.md

@@ -0,0 +1,82 @@
+# OpenSpec Change: enterprise-react-permissions
+
+- **Change ID**: enterprise-react-permissions
+- **Package**: `@suaveplan/react-permissions`
+- **Category**: react
+- **Target path**: `react/auth/react-permissions`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-permissions.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-permissions` on genesis from scratch at enterprise quality. React binding for RBAC/ABAC: `<Can>`, `<PermissionBoundary>`, `<RoleGuard>`, `AbilityProvider`/`AbilityContext`, `createAbilityContext()`, `createContextualCan()`, hooks (`useAbility`, `useCan`, `usePermissionCheck`). Genesis adds Storybook stories, Playwright E2E, `@suaveplan/error`-backed errors, OTel audit events for denied renders, and SSR safety tests.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `PermissionError` |
+| `@suaveplan/types` (`workspace:^`) | Shared types |
+| `@opentelemetry/api` (`catalog:observability`) | `permission.denied` span event |
+
+External: `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+Can, PermissionBoundary, RoleGuard
+AbilityContext, AbilityProvider, createAbilityContext
+useAbilityContext, useAbility, useCan, usePermissionCheck
+createContextualCan
+
+// Types
+CanProps, PermissionBoundaryProps, RoleGuardProps,
+AbilityProviderProps, PermissionCheckResult
+```
+
+---
+
+## New additions for genesis
+
+1. **`PermissionError`** — codes: `PERMISSION_CONTEXT_MISSING`, `PERMISSION_DENIED`.
+2. **OTel `permission.denied` span event** — attributes: `permission.action`, `permission.subject` — emitted when `<Can>` renders null due to denial.
+3. **SSR safety tests** — `AbilityProvider` hydration test.
+4. **Storybook** — `<Can>` allowed/denied, `<PermissionBoundary>` with fallback, `<RoleGuard>` role variants, multi-ability `createAbilityContext` demo.
+5. **Playwright E2E** — render `<Can>`, verify allowed/denied rendering.
+
+---
+
+## File layout
+
+```text
+react/auth/react-permissions/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    components/
+      can/ permission-boundary/ role-guard/
+    context/
+      ability-context/
+    hooks/
+      use-ability/ use-can/ use-permission-check/
+    utils/
+      create-contextual-can/
+    types/
+  e2e/
+    permissions.spec.ts
+```