@stapel/workspaces-react 0.5.0 → 0.7.0

package/llms.txt

@@ -1,6 +1,6 @@
-# @stapel/workspaces-react 0.5.0
+# @stapel/workspaces-react 0.7.0
 
-Headless React flow pair for stapel-workspaces (contract >=0.4 <0.5) — business + state, zero visual opinion.
+Headless React flow pair for stapel-workspaces (contract >=0.8 <0.9) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
 verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
 
@@ -16,37 +16,50 @@ verification-403 interception, i18n engine, analytics facade, TanStack Query lay
 ## Layers
 api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
 
+## Machines (createFlowMachine; analytics funnel flow.<id>.<step>)
+- createInviteAcceptFlow
+
 ## Documented flows (flows.json — canonical id, steps, endpoints)
 
 ## Operations (typed; use the named op, never a path string)
 Request/response schema names are in manifest.json + the generated types.
-- workspaces_api_v1_create: POST /workspaces/api/v1/
-- workspaces_api_v1_destroy: DELETE /workspaces/api/v1/{workspace_id}
-- workspaces_api_v1_internal_members_retrieve: GET /workspaces/api/v1/internal/{workspace_id}/members/{user_id}
-- workspaces_api_v1_internal_users_personal_create: POST /workspaces/api/v1/internal/users/{user_id}/personal
-- workspaces_api_v1_invitations_accept_create: POST /workspaces/api/v1/invitations/accept
-- workspaces_api_v1_members_destroy: DELETE /workspaces/api/v1/{workspace_id}/members/{user_id}
-- workspaces_api_v1_members_invite_create: POST /workspaces/api/v1/{workspace_id}/members/invite
-- workspaces_api_v1_members_list: GET /workspaces/api/v1/{workspace_id}/members
-- workspaces_api_v1_members_partial_update: PATCH /workspaces/api/v1/{workspace_id}/members/{user_id}
-- workspaces_api_v1_partial_update: PATCH /workspaces/api/v1/{workspace_id}
-- workspaces_api_v1_retrieve: GET /workspaces/api/v1/
-- workspaces_api_v1_retrieve_2: GET /workspaces/api/v1/{workspace_id}
+Paths are relative to `/workspaces/api/v1/`.
+- workspaces_api_v1_create: POST /
+- workspaces_api_v1_destroy: DELETE /{workspace_id}
+- workspaces_api_v1_internal_members_retrieve: GET /internal/{workspace_id}/members/{user_id}
+- workspaces_api_v1_internal_users_personal_create: POST /internal/users/{user_id}/personal
+- workspaces_api_v1_invitations_accept_create: POST /invitations/accept
+- workspaces_api_v1_invitations_claim_create: POST /invitations/{token}/claim
+- workspaces_api_v1_invitations_decline_create: POST /invitations/{token}/decline
+- workspaces_api_v1_invitations_retrieve: GET /invitations/{token}
+- workspaces_api_v1_members_destroy: DELETE /{workspace_id}/members/{user_id}
+- workspaces_api_v1_members_invite_create: POST /{workspace_id}/members/invite
+- workspaces_api_v1_members_list: GET /{workspace_id}/members
+- workspaces_api_v1_members_partial_update: PATCH /{workspace_id}/members/{user_id}
+- workspaces_api_v1_members_provision_create: POST /{workspace_id}/members/provision
+- workspaces_api_v1_partial_update: PATCH /{workspace_id}
+- workspaces_api_v1_retrieve: GET /
+- workspaces_api_v1_retrieve_2: GET /{workspace_id}
+- workspaces_api_v1_roles_retrieve: GET /roles
 
 ## Query hooks (server state; keys come only from the key factory)
 - useAcceptInvitation (mutation) → acceptInvitation
+- useClaimInvitation (mutation) → claimInvitation
 - useCreateWorkspace (mutation) → createWorkspace
+- useDeclineInvitation (mutation) → declineInvitation
 - useDeleteWorkspace (mutation) → deleteWorkspace
+- useInvitationPreview (query) → getInvitationPreview
 - useInviteMembers (mutation) → inviteMembers
 - useMembers (query) → listMembers
 - useRemoveMember (mutation) → removeMember
+- useRoles (query) → listRoles
 - useUpdateMemberRole (mutation) → updateMemberRole
 - useUpdateWorkspace (mutation) → updateWorkspace
 - useWorkspace (query) → getWorkspace
 - useWorkspaces (query) → listWorkspaces
 
 ## Errors (render t(code, params); UX from remediation)
-52 keys (full catalog: manifest.json §errors). By remediation: fix_input 24 · retry 12 · contact_support 5 · verify 5 · wait_and_retry 5 · reauthenticate 1.
+60 keys (full catalog: manifest.json §errors). By remediation: fix_input 28 · retry 12 · contact_support 7 · wait_and_retry 6 · verify 5 · reauthenticate 2.
 Param-bearing keys (interpolation slots matter):
 - error.400.field.blank [400] → fix_input {field}
 - error.400.field.does_not_exist [400] → fix_input {field}
@@ -59,6 +72,9 @@ Param-bearing keys (interpolation slots matter):
 - error.400.field.null [400] → fix_input {field}
 - error.400.field.required [400] → fix_input {field}
 - error.400.field.unique [400] → fix_input {field}
+- error.402.member_limit_reached [402] → fix_input {limit}
+- error.403.membership_suspended [403] → fix_input {reason}
+- error.403.missing_capability [403] → contact_support {capability}
 - error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
 
 ## Analytics events (typed; defineEvent → events.json, drift-gated)
@@ -82,13 +98,22 @@ const { tracked } = useTracked();
 
 ## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
 - workspaces.accept → <AcceptInvitation> [default]  demo/AcceptInvitation.demo.tsx
+- workspaces.can → <Can> [default]  demo/Can.demo.tsx
+- workspaces.invite-accept → <InviteAcceptFlow> [default]  demo/InviteAcceptFlow.demo.tsx
 - workspaces.list → <WorkspaceList> [default]  demo/WorkspaceList.demo.tsx
 - workspaces.members → <Members> [default]  demo/Members.demo.tsx
 - workspaces.provider → <WorkspacesProvider> [default]  demo/Workspaces.demo.tsx
+- workspaces.role-select → <RoleSelect> [default]  demo/RoleSelect.demo.tsx
 Each source file is the canonical usage snippet (open the default variant).
 
 ## Snippets
 ```tsx
+// A flow machine drives state; you render each step.
+const flow = createInviteAcceptFlow({ api: useWorkspacesApi() });
+const s = useFlow(flow.machine);
+if (s.step.endsWith('Error')) return <p>{t(s.error.code, s.error.params)}</p>;
+```
+```tsx
 // Error rendering + remediation branch (one pattern for every pair).
 const r = explainWorkspacesError(err.code); // 'wait_and_retry' | 'verify' | ...
 return <Alert action={r}>{t(err.code, err.params)}</Alert>;

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/workspaces-react",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "backend": {
     "module": "stapel-workspaces",
-    "contract": ">=0.4 <0.5"
+    "contract": ">=0.8 <0.9"
   },
   "layers": [
     "api",
@@ -14,7 +14,9 @@
     "i18n"
   ],
   "flows": {},
-  "machines": [],
+  "machines": [
+    "createInviteAcceptFlow"
+  ],
   "operations": {
     "workspaces_api_v1_create": {
       "method": "POST",
@@ -51,6 +53,27 @@
       "request": "InvitationAcceptRequest",
       "response": "MemberResponse"
     },
+    "workspaces_api_v1_invitations_claim_create": {
+      "method": "POST",
+      "path": "/workspaces/api/v1/invitations/{token}/claim",
+      "tag": "Members",
+      "request": null,
+      "response": "InvitationClaimResponse"
+    },
+    "workspaces_api_v1_invitations_decline_create": {
+      "method": "POST",
+      "path": "/workspaces/api/v1/invitations/{token}/decline",
+      "tag": "Members",
+      "request": null,
+      "response": null
+    },
+    "workspaces_api_v1_invitations_retrieve": {
+      "method": "GET",
+      "path": "/workspaces/api/v1/invitations/{token}",
+      "tag": "Members",
+      "request": null,
+      "response": "InvitationPreviewResponse"
+    },
     "workspaces_api_v1_members_destroy": {
       "method": "DELETE",
       "path": "/workspaces/api/v1/{workspace_id}/members/{user_id}",
@@ -79,6 +102,13 @@
       "request": "PatchedMemberUpdateRequest",
       "response": "MemberResponse"
     },
+    "workspaces_api_v1_members_provision_create": {
+      "method": "POST",
+      "path": "/workspaces/api/v1/{workspace_id}/members/provision",
+      "tag": "Members",
+      "request": "ProvisionMemberRequest",
+      "response": "ProvisionMemberResponse"
+    },
     "workspaces_api_v1_partial_update": {
       "method": "PATCH",
       "path": "/workspaces/api/v1/{workspace_id}",
@@ -99,6 +129,13 @@
       "tag": "Workspaces",
       "request": null,
       "response": "WorkspaceResponse"
+    },
+    "workspaces_api_v1_roles_retrieve": {
+      "method": "GET",
+      "path": "/workspaces/api/v1/roles",
+      "tag": "Workspaces",
+      "request": null,
+      "response": "RoleListResponse"
     }
   },
   "hooks": {
@@ -106,12 +143,21 @@
       "kind": "mutation",
       "operation": "acceptInvitation",
       "invalidates": [
+        [
+          "workspaces",
+          "invitation-preview",
+          "{token}"
+        ],
         [
           "workspaces",
           "list"
         ]
       ]
     },
+    "useClaimInvitation": {
+      "kind": "mutation",
+      "operation": "claimInvitation"
+    },
     "useCreateWorkspace": {
       "kind": "mutation",
       "operation": "createWorkspace",
@@ -122,6 +168,17 @@
         ]
       ]
     },
+    "useDeclineInvitation": {
+      "kind": "mutation",
+      "operation": "declineInvitation",
+      "invalidates": [
+        [
+          "workspaces",
+          "invitation-preview",
+          "{token}"
+        ]
+      ]
+    },
     "useDeleteWorkspace": {
       "kind": "mutation",
       "operation": "deleteWorkspace",
@@ -137,6 +194,15 @@
         ]
       ]
     },
+    "useInvitationPreview": {
+      "kind": "query",
+      "operation": "getInvitationPreview",
+      "queryKey": [
+        "workspaces",
+        "invitation-preview",
+        "{token}"
+      ]
+    },
     "useInviteMembers": {
       "kind": "mutation",
       "operation": "inviteMembers",
@@ -169,6 +235,14 @@
         ]
       ]
     },
+    "useRoles": {
+      "kind": "query",
+      "operation": "listRoles",
+      "queryKey": [
+        "workspaces",
+        "roles"
+      ]
+    },
     "useUpdateMemberRole": {
       "kind": "mutation",
       "operation": "updateMemberRole",
@@ -325,6 +399,11 @@
       "params": [],
       "remediation": "fix_input"
     },
+    "error.400.invalid_provision_username": {
+      "status": 400,
+      "params": [],
+      "remediation": "fix_input"
+    },
     "error.400.invalid_role": {
       "status": 400,
       "params": [],
@@ -335,6 +414,11 @@
       "params": [],
       "remediation": "fix_input"
     },
+    "error.400.invitation_declined": {
+      "status": 400,
+      "params": [],
+      "remediation": "contact_support"
+    },
     "error.400.invitation_expired": {
       "status": 400,
       "params": [],
@@ -370,6 +454,18 @@
       "params": [],
       "remediation": "reauthenticate"
     },
+    "error.402.entitlement_required": {
+      "status": 402,
+      "params": [],
+      "remediation": "fix_input"
+    },
+    "error.402.member_limit_reached": {
+      "status": 402,
+      "params": [
+        "limit"
+      ],
+      "remediation": "fix_input"
+    },
     "error.402.payment_required": {
       "status": 402,
       "params": [],
@@ -390,6 +486,20 @@
       "params": [],
       "remediation": "fix_input"
     },
+    "error.403.membership_suspended": {
+      "status": 403,
+      "params": [
+        "reason"
+      ],
+      "remediation": "fix_input"
+    },
+    "error.403.missing_capability": {
+      "status": 403,
+      "params": [
+        "capability"
+      ],
+      "remediation": "contact_support"
+    },
     "error.403.network_blocked": {
       "status": 403,
       "params": [],
@@ -455,6 +565,11 @@
       "params": [],
       "remediation": "fix_input"
     },
+    "error.409.email_already_registered": {
+      "status": 409,
+      "params": [],
+      "remediation": "reauthenticate"
+    },
     "error.410.gone": {
       "status": 410,
       "params": [],
@@ -501,6 +616,11 @@
       "status": 500,
       "params": [],
       "remediation": "contact_support"
+    },
+    "error.503.auth_unavailable": {
+      "status": 503,
+      "params": [],
+      "remediation": "wait_and_retry"
     }
   },
   "events": {
@@ -522,6 +642,34 @@
       ],
       "source": "demo/AcceptInvitation.demo.tsx"
     },
+    {
+      "id": "workspaces.can",
+      "title": "Capability gate",
+      "description": "The headless Can gates UI on the caller's my_capabilities in a workspace, with the backend's wildcard matcher (* and prefix.*) ported client-side. Static children render only when allowed; the render-prop variant hands the verdict out for disabled-state UI. UI convenience only — the backend re-checks every operation.",
+      "component": "Can",
+      "tokens": [
+        "card-bg",
+        "card-border"
+      ],
+      "variants": [
+        "default"
+      ],
+      "source": "demo/Can.demo.tsx"
+    },
+    {
+      "id": "workspaces.invite-accept",
+      "title": "Invite accept flow",
+      "description": "The headless InviteAcceptFlow drives the /invite/{token} journey: public preview routing (accept prompt / wrong account / login / claim), the grant_token hand-off seam to auth (onLoginGrant), the basic-data slot, and accept/decline. Every screen is the host's; InviteAcceptPage is the reference skin.",
+      "component": "InviteAcceptFlow",
+      "tokens": [
+        "card-bg",
+        "button-primary-bg"
+      ],
+      "variants": [
+        "default"
+      ],
+      "source": "demo/InviteAcceptFlow.demo.tsx"
+    },
     {
       "id": "workspaces.list",
       "title": "Workspace list",
@@ -562,6 +710,20 @@
         "default"
       ],
       "source": "demo/Workspaces.demo.tsx"
+    },
+    {
+      "id": "workspaces.role-select",
+      "title": "Role select (registry)",
+      "description": "The headless RoleSelect reads the effective role registry (builtin four + the deployment's STAPEL_WORKSPACES[\"ROLES\"] overlay) from GET /roles and resolves labels via workspaces.role.<key> with a raw-name fallback — role UI stops hardcoding the builtin four.",
+      "component": "RoleSelect",
+      "tokens": [
+        "card-bg",
+        "card-border"
+      ],
+      "variants": [
+        "default"
+      ],
+      "source": "demo/RoleSelect.demo.tsx"
     }
   ],
   "i18nKeys": [
@@ -582,8 +744,10 @@
     "error.400.field.required",
     "error.400.field.unique",
     "error.400.invalid_ad_id",
+    "error.400.invalid_provision_username",
     "error.400.invalid_role",
     "error.400.invitation_already_used",
+    "error.400.invitation_declined",
     "error.400.invitation_expired",
     "error.400.invitation_revoked",
     "error.400.validation_error",
@@ -591,10 +755,14 @@
     "error.400.verification_invalid_factor",
     "error.400.workspace_slug_taken",
     "error.401.unauthorized",
+    "error.402.entitlement_required",
+    "error.402.member_limit_reached",
     "error.402.payment_required",
     "error.403.forbidden",
     "error.403.forbidden_workspace",
     "error.403.last_owner_cannot_be_removed",
+    "error.403.membership_suspended",
+    "error.403.missing_capability",
     "error.403.network_blocked",
     "error.403.verification_enrollment_required",
     "error.403.verification_required",
@@ -608,6 +776,7 @@
     "error.406.not_acceptable",
     "error.408.request_timeout",
     "error.409.conflict",
+    "error.409.email_already_registered",
     "error.410.gone",
     "error.413.payload_too_large",
     "error.415.unsupported_media_type",
@@ -617,10 +786,35 @@
     "error.429.rate_limit",
     "error.429.too_many_requests",
     "error.500.internal",
+    "error.503.auth_unavailable",
     "workspaces.accept.accept",
     "workspaces.accept.accepted",
     "workspaces.accept.accepting",
     "workspaces.error.unknown",
+    "workspaces.invite.acceptTitle",
+    "workspaces.invite.accepted",
+    "workspaces.invite.basicDataContinueCta",
+    "workspaces.invite.basicDataTitle",
+    "workspaces.invite.claiming",
+    "workspaces.invite.createAccountCta",
+    "workspaces.invite.declineCta",
+    "workspaces.invite.declined",
+    "workspaces.invite.emailLine",
+    "workspaces.invite.exchangeFailed",
+    "workspaces.invite.exchanging",
+    "workspaces.invite.joinCta",
+    "workspaces.invite.loading",
+    "workspaces.invite.loginTitle",
+    "workspaces.invite.newUserHint",
+    "workspaces.invite.retryCta",
+    "workspaces.invite.roleLine",
+    "workspaces.invite.switchAccountCta",
+    "workspaces.invite.unavailable.accepted",
+    "workspaces.invite.unavailable.declined",
+    "workspaces.invite.unavailable.expired",
+    "workspaces.invite.unavailable.revoked",
+    "workspaces.invite.wrongAccount",
+    "workspaces.invite.wrongAccountHint",
     "workspaces.list.create",
     "workspaces.list.creating",
     "workspaces.list.empty",
@@ -641,6 +835,10 @@
     "workspaces.members.subtitle",
     "workspaces.members.title",
     "workspaces.members.update_role",
+    "workspaces.role.admin",
+    "workspaces.role.member",
+    "workspaces.role.owner",
+    "workspaces.role.viewer",
     "workspaces.settings.danger_zone.delete",
     "workspaces.settings.danger_zone.delete_confirm",
     "workspaces.settings.danger_zone.title",
@@ -655,7 +853,10 @@
   "exports": {
     "runtime": [
       "AcceptInvitation",
+      "Can",
+      "InviteAcceptFlow",
       "Members",
+      "RoleSelect",
       "WORKSPACES_ERRORS",
       "WORKSPACES_ERROR_CODES",
       "WORKSPACES_FLOWS",
@@ -663,21 +864,31 @@
       "WorkspaceList",
       "WorkspacesProvider",
       "WorkspacesRuntimeContext",
+      "capabilityMatches",
       "createFlowMachine",
+      "createInviteAcceptFlow",
       "createWorkspacesApi",
       "createWorkspacesRuntime",
+      "emailMatchesMask",
       "explainWorkspacesError",
       "flowEndpoints",
+      "hasCapability",
       "isErrorCode",
+      "maskEmail",
       "registerWorkspacesI18n",
       "toFlowError",
       "useAcceptInvitation",
+      "useCapabilities",
+      "useClaimInvitation",
       "useCreateWorkspace",
+      "useDeclineInvitation",
       "useDeleteWorkspace",
       "useFlow",
+      "useInvitationPreview",
       "useInviteMembers",
       "useMembers",
       "useRemoveMember",
+      "useRoles",
       "useUpdateMemberRole",
       "useUpdateWorkspace",
       "useWorkspace",
@@ -691,6 +902,8 @@
     ],
     "types": [
       "AcceptInvitationBag",
+      "CanBag",
+      "CapabilitiesResult",
       "CreateWorkspacesRuntimeOptions",
       "FlowEndpoint",
       "FlowError",
@@ -699,6 +912,12 @@
       "FlowStateBase",
       "Invitation",
       "InvitationAccept",
+      "InvitationClaim",
+      "InvitationPreview",
+      "InviteAcceptFlowBag",
+      "InviteAcceptFlowController",
+      "InviteAcceptFlowDeps",
+      "InviteAcceptState",
       "MemberData",
       "MemberInvite",
       "MemberInviteResult",
@@ -708,6 +927,9 @@
       "MembersBag",
       "MembersParams",
       "Remediation",
+      "RoleInfo",
+      "RoleList",
+      "RoleSelectBag",
       "Schemas",
       "WorkspaceCreate",
       "WorkspaceData",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/workspaces-react",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Headless React flow pair for stapel-workspaces: typed API client, TanStack Query hooks, flow machines, headless components, and i18n keys. Zero visual opinion.",
   "license": "MIT",
   "repository": {
@@ -49,7 +49,7 @@
     {
       "name": "i18n/ru subpath (opt-in locale: en floor + generated ru + ru UI)",
       "path": "dist/i18n/ru.js",
-      "limit": "3.5 KB"
+      "limit": "5 KB"
     },
     {
       "name": "default — the settings skin (antd) must stay out of the main bundle",
@@ -82,9 +82,9 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/core": "^0.5.0",
-    "@stapel/showcase": "^0.2.0",
-    "@stapel/tokens": "^0.4.0"
+    "@stapel/core": "^0.8.0",
+    "@stapel/tokens": "^0.5.0",
+    "@stapel/showcase": "^0.2.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/workspaces-react",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "defined": [],
   "flows": []
 }