cortena-ui 1.4.2 → 1.6.0

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

@@ -0,0 +1,257 @@
+"use client";
+
+import * as React from "react";
+import { Button } from "@/components/button";
+import { Checkbox } from "@/components/checkbox";
+import { EmptyState } from "@/components/empty-state";
+import { ErrorBanner } from "@/components/error-banner";
+import { LoadingSkeleton } from "@/components/loading-skeleton";
+import { SectionCard } from "@/components/section-card";
+import { Spinner } from "@/components/spinner";
+import { useAdminPermissions } from "./context";
+import { adminErrorMessage, type AdminPermissionMatrix } from "./types";
+
+function grantsEqual(a: Record<string, string[]>, b: Record<string, string[]>): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    const left = [...(a[key] ?? [])].sort();
+    const right = [...(b[key] ?? [])].sort();
+    if (left.length !== right.length) return false;
+    if (left.some((value, i) => value !== right[i])) return false;
+  }
+  return true;
+}
+
+/**
+ * `/admin/permissions` — the extension's own roles × actions matrix, the one
+ * document `may()` reads (§13.2, P-14).
+ *
+ * A grid of checkboxes, and nothing clever: rows are the roles the extension
+ * declares, columns are the actions it declares, and a tick is a grant. The
+ * screen holds a draft rather than writing per click — a permission matrix is
+ * edited as a whole thought, and a half-applied one is a security hole with a
+ * progress spinner over it — so the edits accumulate, Save PUTs the document
+ * and Discard throws the draft away.
+ *
+ * The roles and the actions are both read-only here: they are the extension's
+ * declared vocabulary, changed in its source, not in an admin screen.
+ */
+export function AdminMatrix() {
+  const { matrix, matrixState, saveMatrix } = useAdminPermissions();
+  const [draft, setDraft] = React.useState<Record<string, string[]> | null>(null);
+  const [saving, setSaving] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  // Re-seed when a different document arrives: a reload, the optimistic copy
+  // this screen just wrote, or the rollback that put the server's back.
+  // Adjusting state during render, not an effect.
+  //
+  // The error is deliberately NOT cleared here. A failed save rolls the
+  // optimistic copy back, which lands as exactly this re-seed, in the same
+  // batch as the message — clearing it would wipe the message that explains
+  // why the grid just moved. Save and Discard clear it instead.
+  const [seeded, setSeeded] = React.useState<AdminPermissionMatrix | null>(matrix);
+  if (matrix !== seeded) {
+    setSeeded(matrix);
+    setDraft(null);
+  }
+
+  if (matrixState.error) {
+    return <ErrorBanner message={matrixState.error.message} onRetry={matrixState.reload} />;
+  }
+  if (!matrix) {
+    return <LoadingSkeleton preset="table" data-slot="admin-matrix-loading" />;
+  }
+
+  const grants = draft ?? matrix.grants;
+  const dirty = draft !== null && !grantsEqual(draft, matrix.grants);
+
+  const toggle = (role: string, action: string, checked: boolean) => {
+    setDraft((prev) => {
+      const base = prev ?? matrix.grants;
+      const current = base[role] ?? [];
+      const next = checked
+        ? current.includes(action)
+          ? current
+          : [...current, action]
+        : current.filter((a) => a !== action);
+      return { ...base, [role]: next };
+    });
+  };
+
+  const save = async () => {
+    if (!draft) return;
+    setSaving(true);
+    setError(null);
+    try {
+      // Only what the grid showed. A key whose grants are all off is dropped
+      // rather than written back as an empty array, so revoking an unknown
+      // role really removes it from the document.
+      const grants = Object.fromEntries(
+        Object.entries(draft).filter(([, actions]) => actions.length > 0),
+      );
+      await saveMatrix({ roles: matrix.roles, actions: matrix.actions, grants });
+      setDraft(null);
+    } catch (err) {
+      // `saveMatrix` has already put the stored document back, so the grid is
+      // showing the server's grants again rather than an edit that never
+      // landed. The envelope's own message says why (§15.6).
+      setError(adminErrorMessage(err));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  /**
+   * Grants naming a role or an action the extension no longer declares.
+   *
+   * They exist routinely: a release renames `document.write` or retires
+   * `reviewer`, and the stored document keeps the old key. Rendering only the
+   * declared vocabulary hid them — and Save then PUT the whole `grants` object
+   * back, so every invisible grant was rewritten, unchanged, by an
+   * administrator who had just been looking at the screen and believed they
+   * had seen the whole policy. `may()` reads the document, not this grid, so
+   * a hidden `reviewer: ["admin.manage"]` is live permission nobody can see or
+   * revoke.
+   *
+   * The rule `role-assignment.tsx` already follows for a retired role: show
+   * it, mark it, and let it be taken away.
+   */
+  const grantedRoles = Object.keys(grants).filter((role) => (grants[role] ?? []).length > 0);
+  const unknownRoles = grantedRoles.filter((role) => !matrix.roles.includes(role)).sort();
+  const grantedActions = [...new Set(Object.values(grants).flat())];
+  const unknownActions = grantedActions.filter((a) => !matrix.actions.includes(a)).sort();
+  const roleRows = [...matrix.roles, ...unknownRoles];
+  const actionColumns = [...matrix.actions, ...unknownActions];
+  const hasUnknown = unknownRoles.length > 0 || unknownActions.length > 0;
+
+  const empty = roleRows.length === 0 || actionColumns.length === 0;
+
+  return (
+    <div data-slot="admin-matrix" className="flex flex-col gap-3">
+      {error ? <ErrorBanner message={error} data-slot="admin-matrix-error" /> : null}
+      <SectionCard
+        title="Permissions"
+        description="This extension's own matrix, in its own database. One policy function reads it, and every route and every MCP tool goes through that function."
+        actions={
+          empty ? null : (
+            <>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={!dirty || saving}
+                onClick={() => {
+                  setDraft(null);
+                  setError(null);
+                }}
+              >
+                Discard
+              </Button>
+              <Button size="sm" disabled={!dirty || saving} onClick={save}>
+                {saving ? <Spinner tone="inverse" /> : null}
+                Save
+              </Button>
+            </>
+          )
+        }
+        flush={!empty}
+      >
+        {empty ? (
+          <EmptyState
+            size="compact"
+            title="Nothing declared yet"
+            description="The matrix is the roles and actions this extension declares. Until it declares both, there is nothing to grant."
+          />
+        ) : (
+          <div className="overflow-x-auto">
+            <table
+              data-slot="admin-matrix-grid"
+              className="w-full border-collapse text-[length:var(--ds-text-caption-lg)]"
+            >
+              <caption className="sr-only">Roles and the actions each one grants</caption>
+              <thead>
+                <tr className="bg-[var(--ds-muted)] text-[color:var(--ds-muted-foreground)]">
+                  <th
+                    scope="col"
+                    className="sticky left-0 z-10 bg-[var(--ds-muted)] px-4 py-2.5 text-left font-medium"
+                  >
+                    Role
+                  </th>
+                  {actionColumns.map((action) => (
+                    <th
+                      key={action}
+                      scope="col"
+                      data-action={action}
+                      data-unknown={unknownActions.includes(action) ? "" : undefined}
+                      title={
+                        unknownActions.includes(action)
+                          ? "This extension no longer declares this action"
+                          : undefined
+                      }
+                      className="whitespace-nowrap px-3 py-2.5 text-center font-medium"
+                    >
+                      {action}
+                      {unknownActions.includes(action) ? (
+                        <span className="ml-1 text-[color:var(--ds-warning)]">(unknown)</span>
+                      ) : null}
+                    </th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {roleRows.map((role) => (
+                  <tr
+                    key={role}
+                    data-slot="admin-matrix-row"
+                    data-role={role}
+                    data-unknown={unknownRoles.includes(role) ? "" : undefined}
+                    className="border-t border-[var(--ds-border-subtle)]"
+                  >
+                    <th
+                      scope="row"
+                      className="sticky left-0 z-10 bg-[var(--ds-card)] px-4 py-2 text-left font-medium text-[color:var(--ds-foreground)]"
+                    >
+                      {role}
+                      {unknownRoles.includes(role) ? (
+                        <span
+                          data-slot="admin-matrix-unknown"
+                          className="ml-1 font-normal text-[length:var(--ds-text-caption)] text-[color:var(--ds-warning)]"
+                        >
+                          unknown role
+                        </span>
+                      ) : null}
+                    </th>
+                    {actionColumns.map((action) => {
+                      const checked = (grants[role] ?? []).includes(action);
+                      return (
+                        <td key={action} className="px-3 py-2 text-center">
+                          <Checkbox
+                            checked={checked}
+                            data-role={role}
+                            data-action={action}
+                            aria-label={`${role} may ${action}`}
+                            onCheckedChange={(next) => toggle(role, action, Boolean(next))}
+                          />
+                        </td>
+                      );
+                    })}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+            {hasUnknown ? (
+              <p
+                data-slot="admin-matrix-unknown-note"
+                className="px-4 py-2.5 text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]"
+              >
+                Rows and columns marked unknown are grants on a role or an action this
+                extension no longer declares. They are still live — untick them and save to
+                remove them.
+              </p>
+            ) : null}
+          </div>
+        )}
+      </SectionCard>
+    </div>
+  );
+}

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

@@ -0,0 +1,204 @@
+"use client";
+
+import * as React from "react";
+import { Badge } from "@/components/badge";
+import { Button } from "@/components/button";
+import { Chip } from "@/components/chip";
+import { DataTable, createColumnHelper } from "@/components/data-table";
+import { ErrorBanner } from "@/components/error-banner";
+import { directRolesOf, effectiveRolesWithOverride, useAdminPermissions } from "./context";
+import { EffectiveRoles, RoleAssignmentDialog } from "./role-assignment";
+import { groupsOf, sourceGroupOf, type AdminMemberRow, type AdminPrincipal } from "./types";
+
+const helper = /* @__PURE__ */ createColumnHelper<AdminMemberRow>();
+
+function statusVariant(status: string): "default" | "success" | "warning" | "destructive" {
+  const s = status.toLowerCase();
+  if (s === "active") return "success";
+  if (s === "invited" || s === "pending") return "warning";
+  if (s === "suspended" || s === "disabled" || s === "removed") return "destructive";
+  return "default";
+}
+
+function formatLastActive(value: string | null | undefined): string {
+  if (!value) return "Never";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}
+
+/**
+ * `/admin/members` — the join described in §13.3, on the DataTable **server**
+ * source: an org's membership is unbounded, so it is paged, searched and
+ * sorted by the extension's own endpoint.
+ *
+ * The left half of every row is cortena-auth's and read-only: the person,
+ * their status, and the groups they belong to. The right half is the
+ * extension's: the direct assignment, and the effective roles `may()` resolves
+ * from it plus every group's roles, each labelled with its source. Only the
+ * direct assignment is editable, and the groups column disappears entirely
+ * when the org has no groups.
+ */
+export function AdminMembers() {
+  const { api, hasGroups, groupsUnknown, groupsState, revision, memberRoles, reconcileMembers } =
+    useAdminPermissions();
+  const [editing, setEditing] = React.useState<AdminPrincipal | null>(null);
+  const [editingRoles, setEditingRoles] = React.useState<readonly string[]>([]);
+
+  const columns = React.useMemo(
+    () =>
+      helper.columns([
+        helper.accessor("name", {
+          header: "Member",
+          cell: ({ row }) => (
+            <div className="flex flex-col">
+              <span className="font-medium text-[color:var(--ds-foreground)]">
+                {row.original.name}
+              </span>
+              <span className="text-[length:var(--ds-text-caption)] text-[color:var(--ds-muted-foreground)]">
+                {row.original.email}
+              </span>
+            </div>
+          ),
+          meta: { label: "Member" },
+        }),
+        helper.accessor("status", {
+          header: "Status",
+          cell: ({ row }) => (
+            <Badge variant={statusVariant(row.original.status)}>{row.original.status}</Badge>
+          ),
+          // Deliberately not a faceted filter: a server source loads one page,
+          // so the facets would have to be a fixed list, and membership status
+          // is cortena-auth's vocabulary rather than this component's to
+          // invent. The search box already reaches it.
+          meta: { label: "Status" },
+        }),
+        ...(hasGroups || groupsUnknown
+          ? [
+              helper.display({
+                id: "groups",
+                header: "Groups",
+                cell: ({ row }) => {
+                  const groups = groupsOf(row.original);
+                  if (groups.length === 0) {
+                    return (
+                      <span className="text-[length:var(--ds-text-caption)] text-[color:var(--ds-text-tertiary)]">
+                        None
+                      </span>
+                    );
+                  }
+                  return (
+                    <div className="flex flex-wrap items-center gap-1">
+                      {groups.map((group) => (
+                        <Chip key={group.id} size="sm" data-group={group.id}>
+                          {group.name}
+                        </Chip>
+                      ))}
+                    </div>
+                  );
+                },
+                meta: {
+                  label: "Groups",
+                  exportValue: (row: AdminMemberRow) =>
+                    groupsOf(row)
+                      .map((g) => g.name)
+                      .join(", "),
+                },
+                enableSorting: false,
+              }),
+            ]
+          : []),
+        helper.display({
+          id: "effectiveRoles",
+          header: "Effective roles",
+          cell: ({ row }) => (
+            <EffectiveRoles roles={effectiveRolesWithOverride(row.original, memberRoles)} />
+          ),
+          meta: {
+            label: "Effective roles",
+            exportValue: (row: AdminMemberRow) =>
+              effectiveRolesWithOverride(row, memberRoles)
+                .map((entry) => {
+                  const group = sourceGroupOf(entry.source);
+                  return group ? `${entry.role} (via ${group.name})` : entry.role;
+                })
+                .join(", "),
+          },
+          enableSorting: false,
+        }),
+        helper.accessor("lastActiveAt", {
+          header: "Last active",
+          cell: ({ row }) => formatLastActive(row.original.lastActiveAt),
+          meta: { label: "Last active" },
+        }),
+        helper.display({
+          id: "actions",
+          header: () => <span className="sr-only">Actions</span>,
+          cell: ({ row }) => (
+            <div className="flex justify-end">
+              <Button
+                variant="outline"
+                size="sm"
+                aria-label={`Edit roles for ${row.original.name}`}
+                onClick={() => {
+                  setEditingRoles(directRolesOf(row.original, memberRoles));
+                  setEditing({
+                    kind: "user",
+                    id: row.original.userId,
+                    name: row.original.name,
+                  });
+                }}
+              >
+                Edit roles
+              </Button>
+            </div>
+          ),
+          meta: { align: "end", exportable: false },
+          enableSorting: false,
+          enableHiding: false,
+        }),
+      ]),
+    [hasGroups, groupsUnknown, memberRoles],
+  );
+
+  return (
+    <div data-slot="admin-members" className="flex flex-col gap-3">
+      {/* A failed `groups.list()` renders exactly like an org with no groups:
+          every inherited role silently disappears and the effective-roles
+          column reads as a fact about the member. Say so instead. */}
+      {groupsState.error ? (
+        <ErrorBanner
+          data-slot="admin-members-groups-error"
+          message={`Group membership could not be loaded, so inherited roles may be missing. ${groupsState.error.message}`}
+          onRetry={groupsState.reload}
+        />
+      ) : null}
+      <DataTable
+        columns={columns}
+        dataSource={{
+          kind: "server",
+          fetch: async (query, signal) => {
+            const result = await api.members.list(query, signal);
+            // The server has spoken: any optimistic entry it now agrees with
+            // has done its job and is retired.
+            reconcileMembers(result.rows);
+            return result;
+          },
+          // The revision is part of the cache scope, so a successful write —
+          // to this member or to a group they belong to — invalidates the page
+          // rather than leaving a stale resolution on screen.
+          queryKey: ["cortena-admin-members", revision],
+        }}
+        getRowId={(row) => row.userId}
+        searchPlaceholder="Search members…"
+        emptyMessage="No members"
+        exportFileName="members"
+      />
+      <RoleAssignmentDialog
+        principal={editing}
+        current={editingRoles}
+        onOpenChange={(open) => !open && setEditing(null)}
+      />
+    </div>
+  );
+}