cortena-ui 1.4.2 → 1.6.0

package/src/components/admin-permissions/context.tsx

@@ -0,0 +1,376 @@
+"use client";
+
+import * as React from "react";
+import {
+  adminErrorMessage,
+  effectiveRolesOf,
+  type AdminEffectiveRole,
+  type AdminGroupRow,
+  type AdminMemberRow,
+  type AdminPermissionMatrix,
+  type AdminPermissionsApi,
+  type AdminPrincipal,
+} from "./types";
+
+/**
+ * One async read, with the abort a screen needs when it unmounts mid-flight.
+ * Small on purpose: the composition fetches three documents of its own (the
+ * matrix, the licence, the groups) and the members list is a DataTable on the
+ * server source, which owns its own fetching.
+ */
+export interface Resource<T> {
+  data: T | null;
+  error: Error | null;
+  loading: boolean;
+  reload: () => void;
+}
+
+export function useResource<T>(
+  load: ((signal: AbortSignal) => Promise<T>) | undefined,
+  deps: React.DependencyList,
+): Resource<T> {
+  const [state, setState] = React.useState<{
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+  }>({ data: null, error: null, loading: Boolean(load) });
+  const [tick, setTick] = React.useState(0);
+  // The consumer's `api` is usually an object literal, so its methods are new
+  // on every parent render. Reading the latest through a ref keeps a render
+  // from cancelling and refiring the request it just made.
+  const loadRef = React.useRef(load);
+  React.useEffect(() => {
+    loadRef.current = load;
+  });
+
+  React.useEffect(() => {
+    const run = loadRef.current;
+    if (!run) {
+      setState({ data: null, error: null, loading: false });
+      return;
+    }
+    const controller = new AbortController();
+    setState((s) => ({ ...s, loading: true }));
+    run(controller.signal).then(
+      (data) => {
+        if (!controller.signal.aborted) setState({ data, error: null, loading: false });
+      },
+      (err: unknown) => {
+        if (controller.signal.aborted) return;
+        // `adminErrorMessage` unconditionally, not only for a non-Error: the
+        // broker's envelope hangs off an `Error("HTTP 403")`, and taking the
+        // Error's own message showed the status where §15.6 asks for the
+        // server's sentence.
+        setState({ data: null, error: new Error(adminErrorMessage(err)), loading: false });
+      },
+    );
+    return () => controller.abort();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...deps, tick]);
+
+  return { ...state, reload: React.useCallback(() => setTick((t) => t + 1), []) };
+}
+
+/** `user:<id>` / `group:<id>` — the key an optimistic write is filed under. */
+export function principalKey(principal: AdminPrincipal): string {
+  return `${principal.kind}:${principal.id}`;
+}
+
+export interface AdminPermissionsContextValue {
+  api: AdminPermissionsApi;
+  /** The declared vocabulary and matrix. `null` until it loads, or when it failed. */
+  matrix: AdminPermissionMatrix | null;
+  matrixState: Resource<AdminPermissionMatrix>;
+  /** Write the matrix. Optimistic: the grid shows the new grants before the PUT lands. */
+  saveMatrix: (next: AdminPermissionMatrix) => Promise<void>;
+  /**
+   * True when the API offers groups *and* the org actually has some. Every
+   * group affordance is hidden otherwise.
+   */
+  hasGroups: boolean;
+  /**
+   * True while the answer to `hasGroups` is not known yet — the list is in
+   * flight, or it failed.
+   *
+   * `hasGroups === false` used to mean three different things at once: this
+   * API has no groups, this org has none, and `groups.list()` blew up. The
+   * third renders identically to the second, so a member who inherits
+   * "reviewer" from Legal is shown with no roles at all and an administrator
+   * reads that as a fact about the member. A failure has to look like a
+   * failure.
+   */
+  groupsUnknown: boolean;
+  groups: AdminGroupRow[];
+  groupsState: Resource<{ rows: AdminGroupRow[]; roles: Record<string, string[]> }>;
+  /** group id → the roles it carries, including any not yet confirmed by the server. */
+  groupRoles: Readonly<Record<string, string[]>>;
+  /** Bumped after a successful assignment, so the members source refetches. */
+  revision: number;
+  /** Direct member roles written since the last refetch, by user id. */
+  memberRoles: ReadonlyMap<string, string[]>;
+  /**
+   * Assign a principal's direct roles. Optimistic: the screen shows the new
+   * roles immediately and puts the old ones back if the call rejects, then
+   * rethrows so the caller can show the envelope's message.
+   */
+  assignRoles: (principal: AdminPrincipal, roles: string[]) => Promise<void>;
+  /**
+   * Hand back rows the server has just answered with, so any optimistic entry
+   * the server now agrees with can be dropped. See `memberRoles`.
+   */
+  reconcileMembers: (rows: readonly AdminMemberRow[]) => void;
+}
+
+/** Same roles, order-insensitively — which is all an assignment is. */
+function sameRoles(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  const left = [...a].sort();
+  const right = [...b].sort();
+  return left.every((role, i) => role === right[i]);
+}
+
+const AdminPermissionsContext =
+  /* @__PURE__ */ React.createContext<AdminPermissionsContextValue | null>(null);
+
+export function useAdminPermissions(): AdminPermissionsContextValue {
+  const value = React.useContext(AdminPermissionsContext);
+  if (!value) {
+    throw new Error("AdminPermissions parts must be rendered inside <AdminPermissions>");
+  }
+  return value;
+}
+
+const NO_GROUP_ROLES: Readonly<Record<string, string[]>> = /* @__PURE__ */ Object.freeze({});
+
+export function AdminPermissionsProvider({
+  api,
+  children,
+}: {
+  api: AdminPermissionsApi;
+  children: React.ReactNode;
+}) {
+  const matrixState = useResource<AdminPermissionMatrix>(
+    React.useCallback((signal: AbortSignal) => api.permissions.get(signal), [api]),
+    [api],
+  );
+
+  const groupsApi = api.groups;
+  const loadGroups = React.useCallback(
+    async (signal: AbortSignal) => {
+      const [rows, roles] = await Promise.all([groupsApi!.list(signal), groupsApi!.roles(signal)]);
+      return { rows, roles };
+    },
+    [groupsApi],
+  );
+  const groupsState = useResource(groupsApi ? loadGroups : undefined, [loadGroups, Boolean(groupsApi)]);
+
+  const [revision, setRevision] = React.useState(0);
+  /** Optimistic layers. Both are keyed by principal id and win over the server's copy. */
+  const [memberRoles, setMemberRoles] = React.useState<ReadonlyMap<string, string[]>>(
+    () => new Map(),
+  );
+  const [groupOverrides, setGroupOverrides] = React.useState<ReadonlyMap<string, string[]>>(
+    () => new Map(),
+  );
+  const [matrixOverride, setMatrixOverride] = React.useState<AdminPermissionMatrix | null>(null);
+  /**
+   * Principals whose write the server has ACCEPTED.
+   *
+   * The optimistic entry has two jobs and they end at different moments: it
+   * covers the round trip (until the call resolves), and it covers the gap
+   * before the list refetches (until a response mentions the principal). Once
+   * both are done the entry is not optimism, it is a permanent local truth —
+   * and a second administrator's change to the same principal would never
+   * appear, however many times the page refetched.
+   */
+  const settled = React.useRef({ members: new Set<string>(), groups: new Set<string>() });
+
+  const serverGroupRoles = groupsState.data?.roles;
+  const groupRoles = React.useMemo(() => {
+    if (!serverGroupRoles && groupOverrides.size === 0) return NO_GROUP_ROLES;
+    const merged: Record<string, string[]> = { ...(serverGroupRoles ?? {}) };
+    for (const [id, roles] of groupOverrides) merged[id] = roles;
+    return merged;
+  }, [serverGroupRoles, groupOverrides]);
+
+  const assignRoles = React.useCallback(
+    async (principal: AdminPrincipal, roles: string[]) => {
+      const next = [...roles];
+      if (principal.kind === "user") {
+        // Optimistic, then rolled back to exactly what was there before —
+        // absent, if this member had never been written from this screen.
+        const previous = memberRoles.get(principal.id);
+        setMemberRoles((prev) => new Map(prev).set(principal.id, next));
+        try {
+          await api.members.setRoles(principal.id, next);
+          settled.current.members.add(principal.id);
+        } catch (error) {
+          setMemberRoles((prev) => {
+            const back = new Map(prev);
+            if (previous === undefined) back.delete(principal.id);
+            else back.set(principal.id, previous);
+            return back;
+          });
+          throw error;
+        }
+      } else {
+        if (!api.groups) throw new Error("This API has no groups");
+        const previous = groupOverrides.get(principal.id);
+        setGroupOverrides((prev) => new Map(prev).set(principal.id, next));
+        try {
+          await api.groups.setRoles(principal.id, next);
+          settled.current.groups.add(principal.id);
+        } catch (error) {
+          setGroupOverrides((prev) => {
+            const back = new Map(prev);
+            if (previous === undefined) back.delete(principal.id);
+            else back.set(principal.id, previous);
+            return back;
+          });
+          throw error;
+        }
+      }
+      // A group's roles change what every one of its members inherits, so the
+      // members page is refetched rather than left showing a stale resolution.
+      setRevision((r) => r + 1);
+      if (principal.kind === "group") {
+        // And the groups document is re-read, which is what retires the
+        // optimistic layer for this group: an override that outlives the
+        // server's agreement is a row that can no longer be corrected by
+        // anyone else.
+        groupsState.reload();
+      }
+    },
+    [api, memberRoles, groupOverrides, groupsState],
+  );
+
+  /**
+   * Drop a member override the server has caught up with.
+   *
+   * The optimistic entry exists to cover the gap between a PATCH and the next
+   * list; once the list agrees, keeping it is not optimism but a permanent
+   * local truth. A second administrator's change to the same member would
+   * then never appear, however many times the page refetched — the row would
+   * go on showing what THIS browser last wrote, for the life of the tab.
+   */
+  const reconcileMembers = React.useCallback((rows: readonly AdminMemberRow[]) => {
+    setMemberRoles((prev) => {
+      if (prev.size === 0) return prev;
+      let next: Map<string, string[]> | null = null;
+      for (const row of rows) {
+        const pending = prev.get(row.userId);
+        if (!pending) continue;
+        // Either the server already agrees, or the write it acknowledged has
+        // now been through a list — in which case this row IS the truth, even
+        // when it says something else, because somebody else changed it.
+        if (sameRoles(pending, row.extensionRoles ?? []) || settled.current.members.has(row.userId)) {
+          settled.current.members.delete(row.userId);
+          next ??= new Map(prev);
+          next.delete(row.userId);
+        }
+      }
+      return next ?? prev;
+    });
+  }, []);
+
+  // The same rule for groups: an override the server now echoes is retired.
+  React.useEffect(() => {
+    if (!serverGroupRoles) return;
+    setGroupOverrides((prev) => {
+      if (prev.size === 0) return prev;
+      let next: Map<string, string[]> | null = null;
+      for (const [id, roles] of prev) {
+        if (sameRoles(roles, serverGroupRoles[id] ?? []) || settled.current.groups.has(id)) {
+          settled.current.groups.delete(id);
+          next ??= new Map(prev);
+          next.delete(id);
+        }
+      }
+      return next ?? prev;
+    });
+  }, [serverGroupRoles]);
+
+  const saveMatrix = React.useCallback(
+    async (next: AdminPermissionMatrix) => {
+      const previous = matrixOverride;
+      setMatrixOverride(next);
+      try {
+        const saved = await api.permissions.put(next);
+        if (saved) setMatrixOverride(saved);
+      } catch (error) {
+        setMatrixOverride(previous);
+        throw error;
+      }
+      setRevision((r) => r + 1);
+    },
+    [api, matrixOverride],
+  );
+
+  const matrix = matrixOverride ?? matrixState.data;
+  const groups = groupsState.data?.rows ?? [];
+
+  const value = React.useMemo<AdminPermissionsContextValue>(
+    () => ({
+      api,
+      matrix,
+      matrixState,
+      saveMatrix,
+      hasGroups: Boolean(api.groups) && groups.length > 0,
+      groupsUnknown: Boolean(api.groups) && (groupsState.loading || groupsState.error !== null),
+      groups,
+      groupsState,
+      groupRoles,
+      revision,
+      memberRoles,
+      assignRoles,
+      reconcileMembers,
+    }),
+    // `groups` is derived from `groupsState`, which is in the list.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      api,
+      matrix,
+      matrixState,
+      saveMatrix,
+      groupsState,
+      groupRoles,
+      revision,
+      memberRoles,
+      assignRoles,
+      reconcileMembers,
+    ],
+  );
+
+  return <AdminPermissionsContext value={value}>{children}</AdminPermissionsContext>;
+}
+
+/**
+ * The direct roles to show for a member: what the server sent, unless this
+ * screen has since written something else. A PATCH is not visible in the list
+ * until the source refetches, and on the local (no `QueryClientProvider`)
+ * strategy that may be a page change away — so the write is remembered rather
+ * than the row lying about it.
+ */
+export function directRolesOf(
+  row: AdminMemberRow,
+  memberRoles: ReadonlyMap<string, string[]>,
+): string[] {
+  return memberRoles.get(row.userId) ?? row.extensionRoles ?? [];
+}
+
+/**
+ * The effective roles to show for a member after a local write. Inherited
+ * entries stay the server's — this screen does not know who belongs to which
+ * group — and the direct ones are replaced by whatever was just assigned.
+ */
+export function effectiveRolesWithOverride(
+  row: AdminMemberRow,
+  memberRoles: ReadonlyMap<string, string[]>,
+): AdminEffectiveRole[] {
+  const override = memberRoles.get(row.userId);
+  const server = effectiveRolesOf(row);
+  if (!override) return server;
+  const inherited = server.filter((entry) => entry.source !== "direct");
+  const direct = override.map((role) => ({ role, source: "direct" as const }));
+  return [...direct, ...inherited];
+}

package/src/components/admin-permissions/index.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+export { AdminPermissions } from "./admin-permissions";
+export type { AdminPermissionsProps } from "./admin-permissions";
+export { AdminMembers } from "./members";
+export { AdminRoles } from "./roles";
+export { AdminLicenceScreen } from "./licence";
+export { AdminMatrix } from "./matrix";
+export { DirectRoles, EffectiveRoles, RoleAssignmentDialog } from "./role-assignment";
+export type { RoleAssignmentDialogProps } from "./role-assignment";
+export { useAdminPermissions, AdminPermissionsProvider } from "./context";
+export type { AdminPermissionsContextValue } from "./context";
+export {
+  ADMIN_ROUTES,
+  ADMIN_ROUTE_LABELS,
+  adminErrorMessage,
+  effectiveRolesOf,
+  sourceGroupOf,
+} from "./types";
+export type {
+  AdminEffectiveRole,
+  AdminErrorEnvelope,
+  AdminGroupRef,
+  AdminGroupRow,
+  AdminLicence,
+  AdminMemberRow,
+  AdminPermissionMatrix,
+  AdminPermissionsApi,
+  AdminPrincipal,
+  AdminRoleSource,
+  AdminRoute,
+} from "./types";

package/src/components/admin-permissions/licence.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import * as React from "react";
+import { Badge } from "@/components/badge";
+import { Chip } from "@/components/chip";
+import { ErrorBanner } from "@/components/error-banner";
+import { LoadingSkeleton } from "@/components/loading-skeleton";
+import { Progress, ProgressLabel, ProgressValue } from "@/components/progress";
+import { SectionCard } from "@/components/section-card";
+import { useAdminPermissions, useResource } from "./context";
+import type { AdminLicence } from "./types";
+
+/**
+ * `/admin/licence` — a read-through display of cortena-auth's licence, and
+ * nothing else.
+ *
+ * There is no edit control on this screen by design: the licence is not the
+ * extension's to change, and a disabled field would suggest it might be. What
+ * the administrator needs from here is the answer to "have we run out of
+ * seats", which is why seats are a bar rather than two numbers in a sentence.
+ */
+export function AdminLicenceScreen() {
+  const { api } = useAdminPermissions();
+  const load = React.useCallback((signal: AbortSignal) => api.licence.get(signal), [api]);
+  const { data, error, loading, reload } = useResource<AdminLicence>(load, [load]);
+
+  if (error) {
+    return <ErrorBanner message={error.message} onRetry={reload} />;
+  }
+  if (loading && !data) {
+    return <LoadingSkeleton preset="card" data-slot="admin-licence-loading" />;
+  }
+  if (!data) return null;
+
+  const seats = typeof data.seats === "number" ? data.seats : null;
+  const used = typeof data.seatsUsed === "number" ? data.seatsUsed : null;
+  const features = data.features ?? [];
+
+  return (
+    <div data-slot="admin-licence" className="flex flex-col gap-6">
+      <SectionCard
+        title="Licence"
+        description="Held by cortena-auth for this organisation. It is shown here and changed there."
+        actions={
+          <Badge variant="info" data-slot="admin-licence-plan">
+            {data.plan}
+          </Badge>
+        }
+      >
+        {seats === null ? (
+          <p className="text-[length:var(--ds-text-body-sm)] text-[color:var(--ds-muted-foreground)]">
+            This plan does not meter seats.
+          </p>
+        ) : (
+          <Progress value={used ?? 0} max={seats} data-slot="admin-licence-seats">
+            <ProgressLabel>Seats used</ProgressLabel>
+            {/* Base UI hands the formatted value to a render function; the raw
+                count against the cap is what an administrator is looking for. */}
+            <ProgressValue>{() => `${used ?? 0} of ${seats}`}</ProgressValue>
+          </Progress>
+        )}
+      </SectionCard>
+
+      <SectionCard
+        title="Features"
+        description="What this licence entitles the organisation to. A feature is not a permission: it says the org may use something, not that this user may."
+      >
+        {features.length === 0 ? (
+          <p className="text-[length:var(--ds-text-body-sm)] text-[color:var(--ds-muted-foreground)]">
+            No features listed on this licence.
+          </p>
+        ) : (
+          <div className="flex flex-wrap items-center gap-1.5" data-slot="admin-licence-features">
+            {features.map((feature) => (
+              <Chip key={feature} data-feature={feature}>
+                {feature}
+              </Chip>
+            ))}
+          </div>
+        )}
+      </SectionCard>
+    </div>
+  );
+}