@stapel/workspaces-react 0.6.0 → 0.8.0

package/src/default/MembersManager.tsx

@@ -4,6 +4,14 @@
  * инвайты)"). Built entirely on this pair's EXISTING `Members` headless
  * wrapper (`useMembers`/`useInviteMembers`/`useUpdateMemberRole`/
  * `useRemoveMember`) — no new backend surface.
+ *
+ * Roles come from the EFFECTIVE registry via the `RoleSelect` headless
+ * (GET /roles, org-program §A2) — not a hardcoded builtin four: a deployment
+ * that overlays `STAPEL_WORKSPACES["ROLES"]` (e.g. a `secretary`) sees its
+ * roles here with `workspaces.role.<key>` labels (client-bundle merge,
+ * raw-name fallback). `owner` is offered only in the member-row select (the
+ * backend enforces "only an owner grants owner" and last-owner protection);
+ * the invite dialog filters it out, as before.
  */
 import { useState } from "react";
 import type { ReactElement } from "react";
@@ -11,175 +19,177 @@ import { Alert, Button, Card, Input, Modal, Popconfirm, Select, Table, Typograph
 import type { TableProps } from "antd";
 import { useT } from "@stapel/core";
 import { Members } from "../headless/Members.js";
-import type { Member, WorkspaceRole } from "../api/types.js";
+import { RoleSelect } from "../headless/RoleSelect.js";
+import type { RoleSelectBag } from "../headless/RoleSelect.js";
+import type { Member } from "../api/types.js";
 import { WORKSPACES_I18N_KEYS } from "../i18n/keys.js";
 
 export interface MembersManagerProps {
   workspaceId: string;
   /**
    * Whether the caller may invite, change roles, and remove members. The
-   * host already knows the caller's own role in this workspace (e.g. from
-   * `useWorkspace(workspaceId).data?.my_role`); this component doesn't
-   * re-derive it — pass `false` for a read-only roster (e.g. a `viewer`/
-   * `member` looking at their teammates). Default `true`.
+   * host already knows the caller's own verdict in this workspace (e.g.
+   * `useCapabilities(workspaceId).can("members.invite")`, or the coarser
+   * `my_role`); this component doesn't re-derive it — pass `false` for a
+   * read-only roster. Default `true`.
    */
   canManage?: boolean;
 }
 
-const ROLES: readonly WorkspaceRole[] = ["owner", "admin", "member", "viewer"];
-
-const ROLE_KEY: Record<
-  WorkspaceRole,
-  "roleOwner" | "roleAdmin" | "roleMember" | "roleViewer"
-> = {
-  owner: "roleOwner",
-  admin: "roleAdmin",
-  member: "roleMember",
-  viewer: "roleViewer",
-};
-
-function isWorkspaceRole(value: string): value is WorkspaceRole {
-  return (ROLES as readonly string[]).includes(value);
-}
+const DEFAULT_INVITE_ROLE = "member";
 
 export function MembersManager(props: MembersManagerProps): ReactElement {
   const t = useT();
   const canManage = props.canManage ?? true;
   const [inviteOpen, setInviteOpen] = useState(false);
   const [emailsText, setEmailsText] = useState("");
-  const [inviteRole, setInviteRole] = useState<WorkspaceRole>("member");
+  const [inviteRole, setInviteRole] = useState<string>(DEFAULT_INVITE_ROLE);
 
   return (
-    <Members workspaceId={props.workspaceId}>
-      {({ members, isLoading, isError, error, invite, isInviting, updateRole, remove }) => {
-        function openInvite(): void {
-          setEmailsText("");
-          setInviteRole("member");
-          setInviteOpen(true);
-        }
+    <RoleSelect>
+      {(rolesBag: RoleSelectBag) => (
+        <Members workspaceId={props.workspaceId}>
+          {({ members, isLoading, isError, error, invite, isInviting, updateRole, remove }) => {
+            const { labelFor } = rolesBag;
+            const roleOptions = rolesBag.roles.map((r) => ({
+              value: r.role,
+              label: labelFor(r.role),
+            }));
+            const inviteRoleOptions = roleOptions.filter(
+              (o) => o.value !== "owner"
+            );
 
-        function submitInvite(): void {
-          const emails = emailsText
-            .split(/[,\s]+/)
-            .map((e) => e.trim())
-            .filter((e) => e.length > 0);
-          if (emails.length === 0) return;
-          invite({ emails, role: inviteRole });
-          setInviteOpen(false);
-        }
+            function openInvite(): void {
+              setEmailsText("");
+              setInviteRole(DEFAULT_INVITE_ROLE);
+              setInviteOpen(true);
+            }
 
-        const columns: TableProps<Member>["columns"] = [
-          {
-            title: "Email",
-            dataIndex: "email",
-            key: "email",
-            render: (value: string | null) => value ?? "—",
-          },
-          {
-            title: t(WORKSPACES_I18N_KEYS.membersInviteRoleLabel),
-            key: "role",
-            render: (_: unknown, member: Member) => {
-              const role = isWorkspaceRole(member.role) ? member.role : "member";
-              return canManage ? (
-                <Select<WorkspaceRole>
-                  value={role}
-                  style={{ width: 140 }}
-                  onChange={(next) => updateRole({ userId: member.user_id, role: next })}
-                  options={ROLES.map((r) => ({ value: r, label: t(WORKSPACES_I18N_KEYS[ROLE_KEY[r]]) }))}
-                />
-              ) : (
-                <span>{t(WORKSPACES_I18N_KEYS[ROLE_KEY[role]])}</span>
-              );
-            },
-          },
-          ...(canManage
-            ? [
-                {
-                  title: "",
-                  key: "actions",
-                  render: (_: unknown, member: Member) => (
-                    <Popconfirm
-                      title={t(WORKSPACES_I18N_KEYS.membersRemoveConfirm)}
-                      onConfirm={() => remove(member.user_id)}
-                    >
-                      <Button danger type="link">
-                        {t(WORKSPACES_I18N_KEYS.membersRemove)}
-                      </Button>
-                    </Popconfirm>
+            function submitInvite(): void {
+              const emails = emailsText
+                .split(/[,\s]+/)
+                .map((e) => e.trim())
+                .filter((e) => e.length > 0);
+              if (emails.length === 0) return;
+              invite({ emails, role: inviteRole });
+              setInviteOpen(false);
+            }
+
+            const columns: TableProps<Member>["columns"] = [
+              {
+                title: "Email",
+                dataIndex: "email",
+                key: "email",
+                render: (value: string | null) => value ?? "—",
+              },
+              {
+                title: t(WORKSPACES_I18N_KEYS.membersInviteRoleLabel),
+                key: "role",
+                render: (_: unknown, member: Member) =>
+                  canManage ? (
+                    <Select<string>
+                      value={member.role}
+                      style={{ width: 160 }}
+                      loading={rolesBag.isLoading}
+                      onChange={(next) => updateRole({ userId: member.user_id, role: next })}
+                      // A member's CURRENT role may be missing from the
+                      // registry options (a deployment removed an overlay
+                      // role) — antd shows the raw value then, which matches
+                      // labelFor's raw-name fallback contract.
+                      options={roleOptions}
+                    />
+                  ) : (
+                    <span>{labelFor(member.role)}</span>
                   ),
-                },
-              ]
-            : []),
-        ];
+              },
+              ...(canManage
+                ? [
+                    {
+                      title: "",
+                      key: "actions",
+                      render: (_: unknown, member: Member) => (
+                        <Popconfirm
+                          title={t(WORKSPACES_I18N_KEYS.membersRemoveConfirm)}
+                          onConfirm={() => remove(member.user_id)}
+                        >
+                          <Button danger type="link">
+                            {t(WORKSPACES_I18N_KEYS.membersRemove)}
+                          </Button>
+                        </Popconfirm>
+                      ),
+                    },
+                  ]
+                : []),
+            ];
 
-        return (
-          <Card data-testid="members-manager">
-            <div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start", gap: 16 }}>
-              <div>
-                <Typography.Title level={4} style={{ marginTop: 0 }}>
-                  {t(WORKSPACES_I18N_KEYS.membersTitle)}
-                </Typography.Title>
-                <Typography.Text type="secondary">{t(WORKSPACES_I18N_KEYS.membersSubtitle)}</Typography.Text>
-              </div>
-              {canManage && (
-                <Button
-                  type="primary"
-                  onClick={openInvite}
-                  data-analytics="none"
-                  data-analytics-reason="local-ui-open-invite-dialog"
-                >
-                  {t(WORKSPACES_I18N_KEYS.membersInvite)}
-                </Button>
-              )}
-            </div>
+            return (
+              <Card data-testid="members-manager">
+                <div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start", gap: 16 }}>
+                  <div>
+                    <Typography.Title level={4} style={{ marginTop: 0 }}>
+                      {t(WORKSPACES_I18N_KEYS.membersTitle)}
+                    </Typography.Title>
+                    <Typography.Text type="secondary">{t(WORKSPACES_I18N_KEYS.membersSubtitle)}</Typography.Text>
+                  </div>
+                  {canManage && (
+                    <Button
+                      type="primary"
+                      onClick={openInvite}
+                      data-analytics="none"
+                      data-analytics-reason="local-ui-open-invite-dialog"
+                    >
+                      {t(WORKSPACES_I18N_KEYS.membersInvite)}
+                    </Button>
+                  )}
+                </div>
 
-            {isError && error && (
-              <Alert style={{ marginTop: 12 }} type="error" showIcon message={error.message} />
-            )}
+                {isError && error && (
+                  <Alert style={{ marginTop: 12 }} type="error" showIcon message={error.message} />
+                )}
 
-            <Table<Member>
-              style={{ marginTop: 16 }}
-              size="small"
-              loading={isLoading}
-              rowKey={(member) => member.id}
-              dataSource={members as Member[]}
-              columns={columns}
-              pagination={false}
-            />
+                <Table<Member>
+                  style={{ marginTop: 16 }}
+                  size="small"
+                  loading={isLoading}
+                  rowKey={(member) => member.id}
+                  dataSource={members as Member[]}
+                  columns={columns}
+                  pagination={false}
+                />
 
-            <Modal
-              title={t(WORKSPACES_I18N_KEYS.membersInviteDialogTitle)}
-              open={inviteOpen}
-              onCancel={() => setInviteOpen(false)}
-              onOk={submitInvite}
-              okButtonProps={{ loading: isInviting, disabled: emailsText.trim().length === 0 }}
-            >
-              <div style={{ display: "grid", gap: 12 }}>
-                <div>
-                  <Typography.Text>{t(WORKSPACES_I18N_KEYS.membersInviteEmailsLabel)}</Typography.Text>
-                  <Input
-                    value={emailsText}
-                    onChange={(e) => setEmailsText(e.target.value)}
-                    placeholder={t(WORKSPACES_I18N_KEYS.membersInviteEmailsPlaceholder)}
-                  />
-                </div>
-                <div>
-                  <Typography.Text>{t(WORKSPACES_I18N_KEYS.membersInviteRoleLabel)}</Typography.Text>
-                  <Select<WorkspaceRole>
-                    value={inviteRole}
-                    onChange={setInviteRole}
-                    style={{ width: "100%" }}
-                    options={ROLES.filter((r) => r !== "owner").map((r) => ({
-                      value: r,
-                      label: t(WORKSPACES_I18N_KEYS[ROLE_KEY[r]]),
-                    }))}
-                  />
-                </div>
-              </div>
-            </Modal>
-          </Card>
-        );
-      }}
-    </Members>
+                <Modal
+                  title={t(WORKSPACES_I18N_KEYS.membersInviteDialogTitle)}
+                  open={inviteOpen}
+                  onCancel={() => setInviteOpen(false)}
+                  onOk={submitInvite}
+                  okButtonProps={{ loading: isInviting, disabled: emailsText.trim().length === 0 }}
+                >
+                  <div style={{ display: "grid", gap: 12 }}>
+                    <div>
+                      <Typography.Text>{t(WORKSPACES_I18N_KEYS.membersInviteEmailsLabel)}</Typography.Text>
+                      <Input
+                        value={emailsText}
+                        onChange={(e) => setEmailsText(e.target.value)}
+                        placeholder={t(WORKSPACES_I18N_KEYS.membersInviteEmailsPlaceholder)}
+                      />
+                    </div>
+                    <div>
+                      <Typography.Text>{t(WORKSPACES_I18N_KEYS.membersInviteRoleLabel)}</Typography.Text>
+                      <Select<string>
+                        value={inviteRole}
+                        onChange={setInviteRole}
+                        style={{ width: "100%" }}
+                        loading={rolesBag.isLoading}
+                        options={inviteRoleOptions}
+                      />
+                    </div>
+                  </div>
+                </Modal>
+              </Card>
+            );
+          }}
+        </Members>
+      )}
+    </RoleSelect>
   );
 }

package/src/default/index.ts

@@ -15,3 +15,5 @@ export { WorkspaceSettings } from "./WorkspaceSettings.js";
 export type { WorkspaceSettingsProps } from "./WorkspaceSettings.js";
 export { MembersManager } from "./MembersManager.js";
 export type { MembersManagerProps } from "./MembersManager.js";
+export { InviteAcceptPage } from "./InviteAcceptPage.js";
+export type { InviteAcceptPageProps } from "./InviteAcceptPage.js";

package/src/flows/inviteAcceptFlow.ts

@@ -0,0 +1,289 @@
+import type { Analytics } from "@stapel/core";
+import { createFlowMachine } from "@stapel/core";
+import type { FlowMachine } from "@stapel/core";
+import type { WorkspacesApi } from "../api/workspacesApi.js";
+import type { InvitationPreview, Member } from "../api/types.js";
+import { emailMatchesMask } from "../model/emailMask.js";
+import { toFlowError } from "./errors.js";
+import type { FlowError } from "./errors.js";
+
+/**
+ * The `/invite/{token}` journey (org-program §B4) as a flow machine:
+ *
+ * ```
+ * preview → (session && email match)      → acceptPrompt [accept/decline]
+ *         → (session && email mismatch)   → wrongAccount (logout CTA)
+ *         → (no session, email_registered)→ loginRequired (host's login slot)
+ *         → (no session, new user)        → newUser → claim →
+ *              grantIssued (grant_token handed OUT) → [host exchanges at auth]
+ *              → basicData (host's initial-setup slot) → acceptPrompt
+ * ```
+ *
+ * Non-`pending` invitations (expired / revoked / accepted / declined) park in
+ * the terminal `unavailable` step — the page renders the matching copy.
+ *
+ * ## The grant_token seam (deliberate pair boundary)
+ *
+ * `claim` mints a login grant that must be exchanged at AUTH's
+ * `POST /grant/exchange/` — an endpoint of the auth pair, and pairs do NOT
+ * depend on each other (no auth-react peer dependency here). The flow
+ * therefore parks in `grantIssued` and hands `grantToken` OUT via the
+ * `onLoginGrant` callback; the HOST connects the two pairs:
+ *
+ * ```tsx
+ * <InviteAcceptFlow token={token}
+ *   onLoginGrant={async (grant) => {
+ *     const r = await authApi.exchangeLoginGrant(grant); // auth-react
+ *     session.adopt(r);                                  // full session
+ *   }}>
+ * ```
+ *
+ * then calls `grantExchanged()` (the default `InviteAcceptPage` does this
+ * automatically when the host's `onLoginGrant` promise resolves), which moves
+ * the flow to `basicData` — the host's profiles-react `InitialSetupPrompt`
+ * slot — and `completeBasicData()` finally reaches `acceptPrompt`. The
+ * account created by the exchange IS the invited email's account (verified by
+ * construction), so no re-match happens on that path.
+ *
+ * ## Session/email detection
+ *
+ * The pair has no auth dependency, so the CALLER supplies the signed-in
+ * email (`sessionEmail`, e.g. auth-react's `useAuthSessionState().user?.email`
+ * — or any other session source; null/undefined = no session). Match against
+ * the preview's MASKED email is decided client-side by masking the known
+ * email with the same algorithm (see `model/emailMask.ts`); the backend's
+ * real email-match on accept/decline stays the enforcement point — a mask
+ * collision merely shows the prompt, the accept then surfaces the 403.
+ */
+export type InviteAcceptState =
+  | { readonly step: "idle" }
+  | { readonly step: "loadingPreview" }
+  | { readonly step: "previewError"; readonly error: FlowError }
+  /** Terminal: the invitation is not pending (expired/revoked/accepted/declined). */
+  | {
+      readonly step: "unavailable";
+      readonly preview: InvitationPreview;
+      readonly status: string;
+    }
+  /** Signed in with a non-matching account — logout CTA (host slot). */
+  | { readonly step: "wrongAccount"; readonly preview: InvitationPreview }
+  /** No session, account exists — the host's login slot; call
+   * `sessionEstablished(email)` once signed in. */
+  | { readonly step: "loginRequired"; readonly preview: InvitationPreview }
+  /** No session, no account — deliberate CTA before minting the grant. */
+  | { readonly step: "newUser"; readonly preview: InvitationPreview }
+  | { readonly step: "claiming"; readonly preview: InvitationPreview }
+  | {
+      readonly step: "claimError";
+      readonly preview: InvitationPreview;
+      readonly error: FlowError;
+    }
+  /** The grant is out via `onLoginGrant` — waiting for the host to exchange
+   * it at auth and call `grantExchanged()`. */
+  | {
+      readonly step: "grantIssued";
+      readonly preview: InvitationPreview;
+      readonly grantToken: string;
+    }
+  /** Host's basic-data slot (profiles-react InitialSetupPrompt canon, §B5). */
+  | { readonly step: "basicData"; readonly preview: InvitationPreview }
+  | { readonly step: "acceptPrompt"; readonly preview: InvitationPreview }
+  | { readonly step: "accepting"; readonly preview: InvitationPreview }
+  | { readonly step: "declining"; readonly preview: InvitationPreview }
+  | {
+      readonly step: "acceptError";
+      readonly preview: InvitationPreview;
+      readonly error: FlowError;
+    }
+  | {
+      readonly step: "accepted";
+      readonly member: Member;
+      readonly preview: InvitationPreview;
+    }
+  | { readonly step: "declined"; readonly preview: InvitationPreview };
+
+export interface InviteAcceptFlow {
+  readonly machine: FlowMachine<InviteAcceptState>;
+  /** Fetch the preview and route per §B4. `sessionEmail` = the signed-in
+   * account's email, or null when there is no session. */
+  load(sessionEmail: string | null): Promise<void>;
+  /** From `newUser`/`claimError`: mint the login grant (`onLoginGrant` fires
+   * with the token; the flow parks in `grantIssued`). */
+  claim(): Promise<void>;
+  /** From `loginRequired`/`wrongAccount`: a session now exists (host's login
+   * slot finished, or the user switched accounts) — re-route on its email. */
+  sessionEstablished(email: string): void;
+  /** From `grantIssued`: the host exchanged the grant at auth — proceed to
+   * the basic-data step. */
+  grantExchanged(): void;
+  /** From `basicData`: the initial-setup slot finished — show the accept prompt. */
+  completeBasicData(): void;
+  accept(): Promise<void>;
+  decline(): Promise<void>;
+  reset(): void;
+}
+
+export interface InviteAcceptFlowDeps {
+  readonly api: WorkspacesApi;
+  /** The invite token from the `/invite/{token}` URL — a bearer secret. */
+  readonly token: string;
+  readonly analytics?: Analytics | null;
+  /** The grant_token hand-off seam (see the module doc). A credential:
+   * exchange it, never log it. */
+  readonly onLoginGrant?: (grantToken: string) => void;
+  readonly onAccepted?: (member: Member) => void;
+  readonly onDeclined?: () => void;
+}
+
+/**
+ * Flow id: stapel-workspaces annotates no `@flow_step` yet (its
+ * `docs/flows.json` is empty — the pair's flow registry is the zero-flow
+ * shim), so this id is pair-local until the backend documents the flow;
+ * switch to the generated registry id when it lands.
+ */
+const FLOW_ID = "workspaces.invite_accept";
+
+function routeSignedIn(
+  preview: InvitationPreview,
+  email: string
+): InviteAcceptState {
+  return emailMatchesMask(email, preview.email_masked)
+    ? { step: "acceptPrompt", preview }
+    : { step: "wrongAccount", preview };
+}
+
+function routePreview(
+  preview: InvitationPreview,
+  sessionEmail: string | null
+): InviteAcceptState {
+  if (preview.status !== "pending") {
+    return { step: "unavailable", preview, status: preview.status };
+  }
+  if (sessionEmail !== null && sessionEmail !== "") {
+    return routeSignedIn(preview, sessionEmail);
+  }
+  return preview.email_registered
+    ? { step: "loginRequired", preview }
+    : { step: "newUser", preview };
+}
+
+export function createInviteAcceptFlow(
+  deps: InviteAcceptFlowDeps
+): InviteAcceptFlow {
+  const machine = createFlowMachine<InviteAcceptState>({
+    id: FLOW_ID,
+    initial: { step: "idle" },
+    analytics: deps.analytics ?? null,
+  });
+
+  async function load(sessionEmail: string | null): Promise<void> {
+    await machine.run(
+      { step: "loadingPreview" },
+      () => deps.api.getInvitationPreview(deps.token),
+      {
+        resolve: (preview) => routePreview(preview, sessionEmail),
+        reject: (error): InviteAcceptState => ({
+          step: "previewError",
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function claim(): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "newUser" && s.step !== "claimError") return;
+    const { preview } = s;
+    await machine.run(
+      { step: "claiming", preview },
+      () => deps.api.claimInvitation(deps.token),
+      {
+        resolve: (r): InviteAcceptState => {
+          deps.onLoginGrant?.(r.grant_token);
+          return { step: "grantIssued", preview, grantToken: r.grant_token };
+        },
+        reject: (error): InviteAcceptState => ({
+          step: "claimError",
+          preview,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function sessionEstablished(email: string): void {
+    const s = machine.getState();
+    if (s.step !== "loginRequired" && s.step !== "wrongAccount") return;
+    machine.to(routeSignedIn(s.preview, email));
+  }
+
+  function grantExchanged(): void {
+    const s = machine.getState();
+    if (s.step !== "grantIssued") return;
+    machine.to({ step: "basicData", preview: s.preview });
+  }
+
+  function completeBasicData(): void {
+    const s = machine.getState();
+    if (s.step !== "basicData") return;
+    machine.to({ step: "acceptPrompt", preview: s.preview });
+  }
+
+  async function accept(): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "acceptPrompt" && s.step !== "acceptError") return;
+    const { preview } = s;
+    await machine.run(
+      { step: "accepting", preview },
+      () => deps.api.acceptInvitation({ token: deps.token }),
+      {
+        resolve: (member): InviteAcceptState => {
+          deps.onAccepted?.(member);
+          return { step: "accepted", member, preview };
+        },
+        reject: (error): InviteAcceptState => ({
+          step: "acceptError",
+          preview,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  async function decline(): Promise<void> {
+    const s = machine.getState();
+    if (s.step !== "acceptPrompt" && s.step !== "acceptError") return;
+    const { preview } = s;
+    await machine.run(
+      { step: "declining", preview },
+      () => deps.api.declineInvitation(deps.token),
+      {
+        resolve: (): InviteAcceptState => {
+          deps.onDeclined?.();
+          return { step: "declined", preview };
+        },
+        reject: (error): InviteAcceptState => ({
+          step: "acceptError",
+          preview,
+          error: toFlowError(error),
+        }),
+      }
+    );
+  }
+
+  function reset(): void {
+    machine.to({ step: "idle" });
+  }
+
+  return {
+    machine,
+    load,
+    claim,
+    sessionEstablished,
+    grantExchanged,
+    completeBasicData,
+    accept,
+    decline,
+    reset,
+  };
+}