@stapel/workspaces-react 0.16.0 → 0.19.0

package/src/default/parts.tsx

@@ -0,0 +1,308 @@
+/**
+ * The small pieces every screen in this pair's default skin is built from.
+ *
+ * Not exported from `./index.ts`: these are the skin's own vocabulary, not
+ * product surfaces a host mounts. They live in one file because the visual
+ * pass found the same three things drawn differently on each screen — a
+ * person rendered as a bare email here and a truncated id there, a page walk
+ * with no way back, a muted caption at three different sizes.
+ *
+ * Every dimension is a `@stapel/tokens` step. Colour comes from antd's token
+ * layer through `SkinTheme`, never from a literal.
+ */
+import { useId } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { Avatar, Button, Flex, Tag, Typography } from "antd";
+import { STAPEL_UI_KEYS, useT } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import { ErrorAlert } from "@stapel/tokens-antd/skin";
+import { spacing, fontSize } from "@stapel/tokens";
+
+/** The muted sentence that sits under a control or beside a value. */
+export function Muted(props: {
+  readonly children: ReactNode;
+  readonly testId?: string | undefined;
+}): ReactElement {
+  return (
+    <Typography.Text
+      type="secondary"
+      style={{ fontSize: fontSize.xs.fontSize }}
+      {...(props.testId !== undefined ? { "data-testid": props.testId } : {})}
+    >
+      {props.children}
+    </Typography.Text>
+  );
+}
+
+/** One letter for a person with no picture. Never an id: the monogram of a
+ * name, or of the mailbox part of an address, and a neutral glyph when there
+ * is neither. */
+function monogram(name: string | null, email: string | null): string {
+  const source = (name ?? email ?? "").trim();
+  const first = source.charAt(0);
+  return first === "" ? "·" : first.toUpperCase();
+}
+
+/**
+ * A person, drawn the same way on every screen of this pair: monogram, the
+ * name they go by, the address underneath.
+ *
+ * The rule the visual pass forced: an id never reaches the glass. A member
+ * whose profile has no name shows the invited ADDRESS as the primary line and
+ * says so, rather than showing a truncated UUID or an em dash.
+ */
+export function PersonLine(props: {
+  readonly name: string | null | undefined;
+  readonly email: string | null | undefined;
+  /** Rendered under the address — "Joined 3 days ago", a suspension reason. */
+  readonly caption?: ReactNode;
+  /** Tags beside the name (suspended, provisioned, two-factor). */
+  readonly tags?: ReactNode;
+  readonly testId?: string | undefined;
+}): ReactElement {
+  const name = props.name?.trim() ? props.name.trim() : null;
+  const email = props.email?.trim() ? props.email.trim() : null;
+  const primary = name ?? email;
+  return (
+    <Flex
+      gap={spacing["3"]}
+      align="flex-start"
+      {...(props.testId !== undefined ? { "data-testid": props.testId } : {})}
+    >
+      <Avatar size="small" aria-hidden>
+        {monogram(name, email)}
+      </Avatar>
+      <Flex vertical gap={spacing["0"]} style={{ minWidth: 0 }}>
+        <Flex gap={spacing["2"]} align="center" wrap>
+          <Typography.Text strong>{primary}</Typography.Text>
+          {props.tags}
+        </Flex>
+        {name !== null && email !== null && <Muted>{email}</Muted>}
+        {props.caption !== undefined && <Muted>{props.caption}</Muted>}
+      </Flex>
+    </Flex>
+  );
+}
+
+/** A neutral status pill. `tone` picks antd's semantic colour, so it survives
+ * the dark swap — a hex here would not. */
+export function StatusTag(props: {
+  readonly tone: "neutral" | "success" | "warning" | "danger" | "info";
+  readonly children: ReactNode;
+  readonly testId?: string | undefined;
+}): ReactElement {
+  const color =
+    props.tone === "success"
+      ? "success"
+      : props.tone === "warning"
+        ? "warning"
+        : props.tone === "danger"
+          ? "error"
+          : props.tone === "info"
+            ? "processing"
+            : "default";
+  return (
+    <Tag
+      color={color}
+      {...(props.testId !== undefined ? { "data-testid": props.testId } : {})}
+    >
+      {props.children}
+    </Tag>
+  );
+}
+
+/**
+ * The anchor pager three screens share.
+ *
+ * Two buttons and a position, and nothing that pretends to be a page NUMBER
+ * the contract cannot supply: the wire addresses a page by the previous
+ * page's opaque cursor, so "jump to page 7" is not a question this API can be
+ * asked. The index shown is the count of steps THIS screen has taken, which
+ * is a true statement about the walk rather than about the roster.
+ */
+export function AnchorPager(props: {
+  readonly hasPrev: boolean;
+  readonly hasNext: boolean;
+  readonly onPrev: () => void;
+  readonly onNext: () => void;
+  readonly prevLabel: string;
+  readonly nextLabel: string;
+  readonly position: string;
+  readonly testId?: string | undefined;
+}): ReactElement | null {
+  if (!props.hasPrev && !props.hasNext) return null;
+  return (
+    <Flex
+      justify="space-between"
+      align="center"
+      gap={spacing["3"]}
+      style={{ marginTop: spacing["4"] }}
+      {...(props.testId !== undefined ? { "data-testid": props.testId } : {})}
+    >
+      <Button
+        size="small"
+        onClick={props.onPrev}
+        disabled={!props.hasPrev}
+        data-disabled-reason="first page of the walk — there is nothing before it"
+        data-analytics="none"
+        data-analytics-reason="local-ui-page-walk"
+        data-testid="workspaces-pager-prev"
+      >
+        {props.prevLabel}
+      </Button>
+      <Muted>{props.position}</Muted>
+      <Button
+        size="small"
+        onClick={props.onNext}
+        disabled={!props.hasNext}
+        data-disabled-reason="the server says this page is the last one"
+        data-analytics="none"
+        data-analytics-reason="local-ui-page-walk"
+        data-testid="workspaces-pager-next"
+      >
+        {props.nextLabel}
+      </Button>
+    </Flex>
+  );
+}
+
+/** One control on a list row, with the verdict that decides whether it opens. */
+export interface RowActionSpec {
+  readonly key: string;
+  readonly gate: ActionAvailability;
+  readonly label: ReactNode;
+  readonly onClick: () => void;
+  readonly danger?: boolean;
+  readonly testId?: string | undefined;
+}
+
+/**
+ * A list row's controls, and the refusal behind them stated ONCE.
+ *
+ * `GatedButton` prints the reason under every control it switches off, which
+ * is right for a lone button and wrong for a row: three refused controls print
+ * the same sentence three times, and a list of such rows becomes a wall of
+ * repeated apology — six copies of "This invitation was already accepted,
+ * declined, revoked or expired" on one 390px screen. The reason is a fact
+ * about the ROW, not about each button, so it is rendered once, as a footnote
+ * spanning the row, with every disabled control's `aria-describedby` pointing
+ * at it.
+ *
+ * Two nodes come back, meant to be direct children of the row's flex
+ * container: the controls, and the full-width footnote. Keeping the footnote
+ * OUT of the action column is what stops a refused row from growing a second
+ * geometry while its neighbours stay on one line.
+ *
+ * `reason` overrides the collected sentences where the screen has a better
+ * single one — a terminal invitation refuses three controls for one reason
+ * that the row's own status tag already names.
+ */
+export function RowActions(props: {
+  readonly actions: readonly RowActionSpec[];
+  readonly reason?: string | undefined;
+  readonly testId?: string | undefined;
+}): ReactElement {
+  const t = useT();
+  const reasonId = useId();
+
+  const collected: string[] = [];
+  if (props.reason !== undefined) {
+    collected.push(props.reason);
+  } else {
+    const seen = new Set<string>();
+    for (const action of props.actions) {
+      if (action.gate.available) continue;
+      if (seen.has(action.gate.block.code)) continue;
+      seen.add(action.gate.block.code);
+      collected.push(t(action.gate.block.code, action.gate.block.params));
+    }
+  }
+  const anyBlocked = props.actions.some((action) => !action.gate.available);
+
+  return (
+    <>
+      <Flex gap={spacing["2"]} align="center" wrap>
+        {props.actions.map((action) => (
+          <Button
+            key={action.key}
+            type="link"
+            size="small"
+            danger={action.danger === true}
+            disabled={!action.gate.available}
+            {...(anyBlocked && !action.gate.available
+              ? { "aria-describedby": reasonId }
+              : {})}
+            onClick={action.onClick}
+            data-analytics="none"
+            data-analytics-reason="passthrough — the caller's onClick carries the tracked action"
+            {...(action.testId !== undefined ? { "data-testid": action.testId } : {})}
+          >
+            {action.label}
+          </Button>
+        ))}
+      </Flex>
+      {collected.length > 0 && (
+        <div
+          id={reasonId}
+          data-stapel-gated-reason=""
+          style={{ flexBasis: "100%", minWidth: 0 }}
+          {...(props.testId !== undefined ? { "data-testid": props.testId } : {})}
+        >
+          {collected.map((sentence) => (
+            <div key={sentence}>
+              <Muted>{sentence}</Muted>
+            </div>
+          ))}
+        </div>
+      )}
+    </>
+  );
+}
+
+/**
+ * A failed read, said once, in a shape a 390px screen can hold.
+ *
+ * The substrate's `ErrorAlert` puts its retry in antd's `action` slot, which
+ * is a column beside the message — at phone width the sentence is squeezed
+ * into ~110px and breaks a word per line. Until the substrate stacks it
+ * (VC-B6, filed), the retry goes UNDER the alert here, where it has the whole
+ * width at any viewport.
+ */
+export function LoadFailure(props: {
+  readonly error: unknown;
+  readonly onRetry?: (() => void) | undefined;
+  readonly testId?: string | undefined;
+}): ReactElement {
+  const t = useT();
+  return (
+    <Flex vertical gap={spacing["3"]} align="flex-start">
+      <ErrorAlert
+        thrown={props.error}
+        style={{ width: "100%" }}
+        {...(props.testId !== undefined ? { testId: props.testId } : {})}
+      />
+      {props.onRetry !== undefined && (
+        <Button
+          onClick={props.onRetry}
+          data-analytics="none"
+          data-analytics-reason="retry of a failed read; the read hook reports its own outcome"
+          data-testid={props.testId !== undefined ? `${props.testId}-retry` : undefined}
+        >
+          {t(STAPEL_UI_KEYS.retry)}
+        </Button>
+      )}
+    </Flex>
+  );
+}
+
+/** The gap between the stacked blocks of a screen. One number, one place. */
+export const SCREEN_STACK: CSSProperties = {
+  display: "grid",
+  gap: spacing["4"],
+};
+
+/** The gap between the fields inside one block. */
+export const FIELD_STACK: CSSProperties = {
+  display: "grid",
+  gap: spacing["3"],
+};

package/src/headless/Members.tsx

@@ -1,30 +1,66 @@
 import type { ReactNode } from "react";
 import { loadStateFromQuery, mapLoad } from "@stapel/core";
 import type { LoadState, StapelApiError } from "@stapel/core";
-import type { Member, MemberInvite } from "../api/types.js";
+import type { Member, MemberInvite, MembersParams } from "../api/types.js";
 import { useMembers } from "../model/queries.js";
 import {
   useInviteMembers,
   useRemoveMember,
+  useRenameMember,
   useUpdateMemberRole,
 } from "../model/mutations.js";
-import type { MemberRoleChange } from "../model/mutations.js";
+import type { MemberRename, MemberRoleChange } from "../model/mutations.js";
+
+/**
+ * Where in the anchor walk the current page sits — the half of the roster a
+ * pager needs and a count of rows cannot supply.
+ *
+ * ANCHOR, not offset: a page is addressed by the opaque `next_anchor` of the
+ * page before it, so a member removed while an admin reads never skews the
+ * next page. There is no "page 3" to jump to, which is why the shape carries
+ * two cursors and no index.
+ */
+export interface MembersPageInfo {
+  readonly hasNext: boolean;
+  readonly hasPrev: boolean;
+  /** Pass as `params.anchor` with `direction: "next"` to walk forward. */
+  readonly nextAnchor: string | null;
+  /** Pass as `params.anchor` with `direction: "prev"` to walk back. */
+  readonly prevAnchor: string | null;
+  /** Rows on THIS page. Never a count of the roster — see `rosterComplete`. */
+  readonly count: number;
+}
 
 /** Render-prop bag for {@link Members}. */
 export interface MembersBag {
   /**
    * The roster read, as a state a skin cannot flatten — render it with core's
-   * `matchList`. This is one page (default 100); a full pager is out of scope
-   * for this renderless view (bring your own via `useMembers`' `params` for
-   * anchor pagination).
+   * `matchList`. This is ONE page: which one is decided by the `params` the
+   * caller passes (default: the newest page, limit 100), and {@link page}
+   * says whether there is another.
    *
    * Separate from {@link writeError} on purpose: "the roster could not be
    * loaded" and "your invite was rejected" are different sentences, and the
    * old merged `isError` could only produce one of them.
    */
   readonly state: LoadState<readonly Member[]>;
-  /** An invite, a role change, or a removal failed. Never the read — that is
-   * {@link state}. */
+  /**
+   * Whether {@link state} holds the WHOLE roster — the read succeeded and the
+   * page reports no `has_next`.
+   *
+   * A skin may only reason about the roster as a set — "is this the last
+   * owner?", "how many admins are there?" — while this is `true`. On one page
+   * of a longer roster those counts are counts of a page, and a control gated
+   * on one would refuse a removal the backend would have allowed, which is a
+   * worse defect than the ungated button it replaced. `false` while the read
+   * is loading or failed: an unknown roster is never a complete one.
+   */
+  readonly rosterComplete: boolean;
+  /** The walk position, or `null` while the page has not arrived. A pager
+   * with no page cannot claim there is a next one. */
+  readonly page: MembersPageInfo | null;
+  /** An invite, a role change, a rename or a removal failed. Never the read —
+   * that is {@link state}. */
   readonly writeError: StapelApiError | null;
   /** Invite one or more emails at a role. */
   invite(body: MemberInvite): void;
@@ -34,6 +70,11 @@ export interface MembersBag {
   updateRole(change: MemberRoleChange): void;
   /** A role-change call is in flight. */
   readonly isUpdatingRole: boolean;
+  /** Correct a member's display name — the CANONICAL one (stapel-profiles),
+   * not a workspace-local note. `displayName: null` clears it. */
+  rename(change: MemberRename): void;
+  /** A rename call is in flight. */
+  readonly isRenaming: boolean;
   /** Remove a member by `userId`. */
   remove(userId: string): void;
   /** A removal call is in flight. */
@@ -43,30 +84,53 @@ export interface MembersBag {
 }
 
 /**
- * Headless member roster — a renderless view + invite / role-change / removal
- * controls over one workspace's members. Wires {@link useMembers},
- * {@link useInviteMembers}, {@link useUpdateMemberRole}, and
- * {@link useRemoveMember} and hands a {@link MembersBag} to `children`; bring your
- * own roster / invite form / role menu. Zero visual opinion (frontend-standard §2).
+ * Headless member roster — a renderless view + invite / role-change / rename /
+ * removal controls over one workspace's members. Wires {@link useMembers},
+ * {@link useInviteMembers}, {@link useUpdateMemberRole},
+ * {@link useRenameMember} and {@link useRemoveMember} and hands a
+ * {@link MembersBag} to `children`; bring your own roster / invite form / role
+ * menu. Zero visual opinion (frontend-standard §2).
+ *
+ * `params` is the anchor page to read — the caller owns the walk, because the
+ * cursor belongs to the screen's state, not to this component's. Omitted, it
+ * reads the newest page, exactly as before.
  *
  * ```tsx
- * <Members workspaceId={id}>
- *   {({ state, invite, updateRole, remove }) => ( ... )}
+ * <Members workspaceId={id} params={{ anchor, direction: "next", search }}>
+ *   {({ state, page, invite, updateRole, remove }) => ( ... )}
  * </Members>
  * ```
  */
 export function Members(props: {
   workspaceId: string;
+  params?: MembersParams;
   children: (bag: MembersBag) => ReactNode;
 }): ReactNode {
-  const query = useMembers(props.workspaceId);
+  const query = useMembers(props.workspaceId, props.params);
   const inviteMutation = useInviteMembers(props.workspaceId);
   const roleMutation = useUpdateMemberRole(props.workspaceId);
+  const renameMutation = useRenameMember(props.workspaceId);
   const removeMutation = useRemoveMember(props.workspaceId);
+  const data = query.data;
   return props.children({
     state: mapLoad(loadStateFromQuery(query), (page) => page.items),
+    rosterComplete: data !== undefined && !data.has_next && !data.has_prev,
+    page:
+      data === undefined
+        ? null
+        : {
+            hasNext: data.has_next,
+            hasPrev: data.has_prev,
+            nextAnchor: data.next_anchor ?? null,
+            prevAnchor: data.prev_anchor ?? null,
+            count: data.count,
+          },
     writeError:
-      inviteMutation.error ?? roleMutation.error ?? removeMutation.error ?? null,
+      inviteMutation.error ??
+      roleMutation.error ??
+      renameMutation.error ??
+      removeMutation.error ??
+      null,
     invite: (body) => {
       inviteMutation.mutate(body);
     },
@@ -75,6 +139,10 @@ export function Members(props: {
       roleMutation.mutate(change);
     },
     isUpdatingRole: roleMutation.isPending,
+    rename: (change) => {
+      renameMutation.mutate(change);
+    },
+    isRenaming: renameMutation.isPending,
     remove: (userId) => {
       removeMutation.mutate(userId);
     },

package/src/headless/RoleSelect.tsx

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import { loadStateFromQuery, useI18n } from "@stapel/core";
 import type { LoadState } from "@stapel/core";
 import type { RoleInfo } from "../api/types.js";
+import { titleCaseKey } from "../model/format.js";
 import { useRoles } from "../model/queries.js";
 
 /** Render-prop bag for {@link RoleSelect}. */
@@ -15,9 +16,15 @@ export interface RoleSelectBag {
    * Display label for a role key: the i18n key `workspaces.role.<key>` when
    * the current locale's merged bundle carries it (the pair ships the builtin
    * four; a client bundle merges its own — e.g. `workspaces.role.secretary`),
-   * else the RAW role key. The raw-name fallback is deliberate: a
-   * deployment-defined role without a translation must still be pickable,
-   * never render as a dotted i18n key.
+   * else the role key TITLE-CASED (`secretary` → `Secretary`, `site_admin` →
+   * `Site admin`).
+   *
+   * Two things this fallback is not. It is never the dotted i18n key: a
+   * deployment-defined role without a translation must still be pickable. And
+   * since the 2026-08-24 visual pass it is no longer the raw token either —
+   * `secretary` rendered lowercase in a list of title-cased builtin roles,
+   * which reads as broken data rather than as a missing translation. The
+   * label is cosmetic; the VALUE stays the registry key everywhere it is sent.
    */
   labelFor(role: string): string;
 }
@@ -52,10 +59,10 @@ export function RoleSelect(props: {
   const i18n = useI18n();
   // Raw bundle lookup, NOT `t()`: `t` falls back to the key itself, which is
   // exactly the wrong fallback here (a deployment role without a translation
-  // must show its raw name, not `workspaces.role.secretary`).
+  // must show a word, not `workspaces.role.secretary`).
   const bundle = i18n.getBundle();
   return props.children({
     state: loadStateFromQuery(query),
-    labelFor: (role) => bundle[`workspaces.role.${role}`] ?? role,
+    labelFor: (role) => bundle[`workspaces.role.${role}`] ?? titleCaseKey(role),
   });
 }