@stapel/workspaces-react 0.8.0 → 0.10.0

package/src/index.ts

@@ -60,6 +60,7 @@ export {
   useInvitations,
   useInfiniteInvitations,
   useRoles,
+  useInstanceShape,
   useInvitationPreview,
   useCapabilities,
   useCapabilityGate,
@@ -88,6 +89,8 @@ export {
   useInviteMembers,
   useUpdateMemberRole,
   useRemoveMember,
+  useRenameMember,
+  useRenameInvitation,
   useAcceptInvitation,
   useClaimInvitation,
   useDeclineInvitation,
@@ -98,6 +101,8 @@ export {
 } from "./model/mutations.js";
 export type {
   MemberRoleChange,
+  MemberRename,
+  InvitationRename,
   MemberPasswordResetVars,
 } from "./model/mutations.js";
 
@@ -122,6 +127,8 @@ export type {
   InvitationClaim,
   MemberPasswordReset,
   MemberPasswordResetResult,
+  DisplayNameUpdate,
+  DisplayNameResult,
   ProvisionedUserPolicy,
   WorkspaceSecuritySettings,
   RoleInfo,

package/src/model/mutations.ts

@@ -5,6 +5,7 @@ import type {
 } from "@tanstack/react-query";
 import type { StapelApiError } from "@stapel/core";
 import type {
+  DisplayNameResult,
   Invitation,
   Member,
   MemberInvite,
@@ -22,7 +23,7 @@ import { useWorkspacesApi } from "./context.js";
 import { workspacesQueryKeys } from "./queryKeys.js";
 
 /**
- * Write hooks (frontend-standard §2 — "мутации с инвалидацией"). Each mutation
+ * Write hooks (frontend-standard §2 — mutations invalidate on success). Each mutation
  * invalidates exactly the server state it can move. Membership and ownership are
  * server truth (roles gate access in other services via the membership cache),
  * so NONE of these are optimistic (frontend-core-architecture §2.6: optimistic
@@ -179,6 +180,132 @@ export function useRemoveMember(
   return useMutation(options);
 }
 
+/** The variable for {@link useRenameMember}: whose name, and the new one.
+ * `displayName` is nullable because clearing IS a supported outcome — blank,
+ * whitespace-only and `null` all mean "no name for this person" to the
+ * backend, which then answers with an empty string. */
+export interface MemberRename {
+  readonly userId: string;
+  readonly displayName: string | null;
+}
+
+/**
+ * Correct a co-member's display name (PATCH /{id}/members/{userId}/name,
+ * stapel-workspaces ≥0.19.0) — the roster-side fix an owner/admin applies
+ * without waiting for the person themselves.
+ *
+ * **Capability `members.role.change`**, not `members.invite`: ask
+ * {@link "./queries.js".useCapabilityGate}(workspaceId,
+ * "members.role.change") before offering the affordance. It is `standard`, so
+ * no step-up is demanded (contrast {@link useResetMemberPassword}). Anonymous
+ * callers are denied outright, and only an owner may rename an owner.
+ *
+ * **What the write moves, and hence what is invalidated.** The backend writes
+ * the CANONICAL name — stapel-profiles' `Profile.display_name` through the
+ * in-process profiles seam — not the membership's local
+ * `display_name_hint`, which goes dark the moment a real profile exists. So
+ * the stale set is not "the page this row was on": it is EVERY cached roster,
+ * in every workspace, because `MemberResponse.display_name` is a live lookup
+ * of that one canonical value. Hence
+ * {@link "./queryKeys.js".workspacesQueryKeys.membersAll}, the workspace-less
+ * prefix — invalidating `members(workspaceId)` would leave the same person
+ * showing their old name on every other roster the session has open. A
+ * rename can also move a row out of an active `search` filter, which the
+ * prefix covers too (every page, every filter).
+ *
+ * A host that ALSO renders `@stapel/profiles-react` data for this person owns
+ * the other half: this pair never reaches into another pair's query namespace
+ * (the same seam discipline as `InviteAcceptFlow`'s basic-data slot), so
+ * invalidate `profilesQueryKeys.profile(userId)` yourself there.
+ *
+ * **Errors** arrive in the single dialect, keyed: the four display-name rules
+ * borrowed verbatim from stapel-profiles
+ * (`error.400.display_name_too_short` / `_forbidden_chars` /
+ * `_invisible_chars` / `_emoji`), over-length as the fleet-standard
+ * `error.400.field.max_length` with `{field, max_length}` (no bespoke code),
+ * and `error.503.profiles_unavailable` where stapel-profiles does not run in
+ * the deployment's process — an honest refusal rather than a 200 over a write
+ * that did not happen. Render them with `explainWorkspacesError` / `t(code,
+ * params)` like every other key.
+ */
+export function useRenameMember(
+  workspaceId: string
+): UseMutationResult<DisplayNameResult, StapelApiError, MemberRename> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    DisplayNameResult,
+    StapelApiError,
+    MemberRename
+  > = {
+    mutationFn: ({ userId, displayName }) =>
+      api.renameMember(workspaceId, userId, { display_name: displayName }),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.membersAll(),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/** The variable for {@link useRenameInvitation}: which pending invitation, and
+ * the corrected name hint (nullable for the same reason as
+ * {@link MemberRename}). */
+export interface InvitationRename {
+  readonly invitationId: string;
+  readonly displayName: string | null;
+}
+
+/**
+ * Fix a pending invitation's name hint (PATCH
+ * /{id}/invitations/{invitationId}/name, stapel-workspaces ≥0.19.0) — the
+ * same correction as {@link useRenameMember}, one step earlier. The invitee
+ * has not accepted, so there is no profile of theirs to write and the name
+ * lives on the invitation; `accept_invitation` copies it onto the membership.
+ * Before this endpoint the only fix for a typo in an invitee's name was
+ * revoke-and-re-invite, which re-mails the person.
+ *
+ * **The same capability as the member rename** (`members.role.change`, not
+ * the invitation surface's `members.invite`) — the hint IS the member's name
+ * after acceptance, so splitting them would let a role fix a name that
+ * reverts.
+ *
+ * Only a PENDING invitation is editable; a terminal one refuses with the
+ * keyed answers revoke gives (`error.400.invitation_already_used` /
+ * `_revoked` / `_declined` / `_expired`), and an accepted invitation's name
+ * is the member's name now — use {@link useRenameMember}. Validation is the
+ * same stapel-profiles canon, so the same four display-name keys surface
+ * here.
+ *
+ * Invalidation is deliberately NARROWER than the member rename's: the hint is
+ * a workspace-local column on one invitation, not a shared canonical name, so
+ * only this workspace's invitation lists (every page and the infinite walk —
+ * the bare 3-tuple prefix) can be showing it.
+ */
+export function useRenameInvitation(
+  workspaceId: string
+): UseMutationResult<DisplayNameResult, StapelApiError, InvitationRename> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<
+    DisplayNameResult,
+    StapelApiError,
+    InvitationRename
+  > = {
+    mutationFn: ({ invitationId, displayName }) =>
+      api.renameInvitation(workspaceId, invitationId, {
+        display_name: displayName,
+      }),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitations(workspaceId),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
 /**
  * Withdraw a live invitation (POST /{id}/invitations/{invitationId}/revoke,
  * #109). The variable is the invitation id; the reply is the UPDATED row, so

package/src/model/queries.ts

@@ -9,6 +9,7 @@ import type { StapelApiError } from "@stapel/core";
 import type {
   InvitationPage,
   InvitationPreview,
+  InstanceShape,
   InvitationsParams,
   MemberPage,
   MembersParams,
@@ -173,6 +174,35 @@ export function useRoles(): UseQueryResult<
   });
 }
 
+/**
+ * Deployment shape (GET /instance, unauthenticated).
+ *
+ * Answers the question a screen must ask BEFORE deciding what to show
+ * someone with no workspace: is this a closed deployment (`landing:
+ * "none"` — no workspace exists and none can be created) or a public cloud
+ * (`"personal"` — one exists and the screen can lead there)?
+ *
+ * Why a hook instead of a profile field: the reader is exactly the person
+ * who has no access — kicked out of their workspace, or having left it. So
+ * the request deliberately does NOT wait for a session, unlike {@link
+ * useRoles}: waiting would mean never answering the one person it exists for.
+ *
+ * The data is static per deployment — it only changes alongside the
+ * deployment itself, so the cache lives until page reload and is never
+ * refetched.
+ */
+export function useInstanceShape(): UseQueryResult<
+  InstanceShape,
+  StapelApiError
+> {
+  const api = useWorkspacesApi();
+  return useQuery({
+    queryKey: workspacesQueryKeys.instance(),
+    queryFn: () => api.getInstanceShape(),
+    staleTime: Infinity,
+  });
+}
+
 /**
  * Public invitation preview (GET /invitations/{token}, AllowAny — org-program
  * §B2): what the `/invite/{token}` page renders BEFORE any auth decision.

package/src/model/queryKeys.ts

@@ -1,7 +1,7 @@
 import type { InvitationsParams, MembersParams } from "../api/types.js";
 
 /**
- * Namespaced TanStack Query keys (frontend-standard §2 — "ключи неймспейснуты").
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
  * Everything under the `"workspaces"` root so a host can invalidate the whole
  * module or match a single resource. Persist scope is per-user via core's query
  * runtime (`setPersistUser`). Explicit tuple return types satisfy
@@ -14,6 +14,7 @@ export const workspacesQueryKeys: {
   list(): readonly ["workspaces", "list"];
   detail(workspaceId: string): readonly ["workspaces", "detail", string];
   members(workspaceId: string): readonly ["workspaces", "members", string];
+  membersAll(): readonly ["workspaces", "members"];
   membersPage(
     workspaceId: string,
     params: MembersParams
@@ -34,6 +35,7 @@ export const workspacesQueryKeys: {
     InvitationsParams,
   ];
   roles(): readonly ["workspaces", "roles"];
+  instance(): readonly ["workspaces", "instance"];
   invitationPreview(
     token: string
   ): readonly ["workspaces", "invitation-preview", string];
@@ -44,6 +46,13 @@ export const workspacesQueryKeys: {
   // The bare 3-tuple is a valid prefix of membersPage's 4-tuple, so
   // invalidating `members(workspaceId)` (mutations.ts) drops every page.
   members: (workspaceId) => [ROOT, "members", workspaceId],
+  // EVERY workspace's roster, not one. Not a read key — nothing fetches it —
+  // but the invalidation scope of a write that moves a name the whole fleet
+  // shares: `MemberResponse.display_name` is a live lookup in
+  // stapel-profiles, so a rename lands on the person's CANONICAL name and
+  // every roster that lists them is stale at once, not just the one the
+  // admin happened to be looking at.
+  membersAll: () => [ROOT, "members"],
   membersPage: (workspaceId, params) => [ROOT, "members", workspaceId, params],
   // Same prefix trick as `members`: the bare 3-tuple invalidates every page
   // (and the infinite list, which keys on it) after a revoke / resend.
@@ -65,6 +74,7 @@ export const workspacesQueryKeys: {
     filters,
   ],
   roles: () => [ROOT, "roles"],
+  instance: () => [ROOT, "instance"],
   // NOTE: the key carries the invite TOKEN (a secret). Core's query persist
   // scope is per-user and the preview response is already public-by-design
   // (masked email only) — but hosts logging query keys should treat this one