cortena-ui 1.4.2 → 1.5.0

package/src/components/admin-permissions/role-assignment.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+import { Users } from "lucide-react";
+import * as React from "react";
+import { Button } from "@/components/button";
+import { Checkbox } from "@/components/checkbox";
+import { Chip } from "@/components/chip";
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/dialog";
+import { ErrorBanner } from "@/components/error-banner";
+import { Spinner } from "@/components/spinner";
+import { cn } from "@/lib/cn";
+import { useAdminPermissions } from "./context";
+import {
+  adminErrorMessage,
+  sourceGroupOf,
+  type AdminEffectiveRole,
+  type AdminPrincipal,
+} from "./types";
+
+/**
+ * The effective-roles cell. Every role carries the assignment that granted it:
+ * nothing for a direct one, and the group's name for an inherited one. This is
+ * the whole point of §13.4 and P-43 — an administrator who cannot see why
+ * somebody has a permission removes the wrong assignment and believes the job
+ * is done.
+ */
+export function EffectiveRoles({
+  roles,
+  className,
+}: {
+  roles: readonly AdminEffectiveRole[];
+  className?: string;
+}) {
+  if (roles.length === 0) {
+    return (
+      <span
+        data-slot="admin-effective-roles-empty"
+        className="text-[length:var(--ds-text-caption)] text-[color:var(--ds-text-tertiary)]"
+      >
+        No roles
+      </span>
+    );
+  }
+  return (
+    <div
+      data-slot="admin-effective-roles"
+      className={cn("flex flex-wrap items-center gap-1", className)}
+    >
+      {roles.map((entry, index) => {
+        const group = sourceGroupOf(entry.source);
+        return (
+          <Chip
+            key={`${entry.role}-${group?.id ?? "direct"}-${index}`}
+            size="sm"
+            variant={group ? "outline" : "accent"}
+            data-role={entry.role}
+            data-source={group ? group.id : "direct"}
+            title={
+              group
+                ? `${entry.role} — via group ${group.name}`
+                : `${entry.role} — assigned directly`
+            }
+          >
+            {entry.role}
+            {group ? (
+              <span className="inline-flex items-center gap-1 text-[color:var(--ds-text-tertiary)]">
+                <Users aria-hidden />
+                via {group.name}
+              </span>
+            ) : null}
+          </Chip>
+        );
+      })}
+    </div>
+  );
+}
+
+/** A plain list of directly assigned roles, for the group list. */
+export function DirectRoles({ roles }: { roles: readonly string[] }) {
+  if (roles.length === 0) {
+    return (
+      <span
+        data-slot="admin-direct-roles-empty"
+        className="text-[length:var(--ds-text-caption)] text-[color:var(--ds-text-tertiary)]"
+      >
+        None
+      </span>
+    );
+  }
+  return (
+    <div data-slot="admin-direct-roles" className="flex flex-wrap items-center gap-1">
+      {roles.map((role) => (
+        <Chip key={role} size="sm" variant="accent" data-role={role}>
+          {role}
+        </Chip>
+      ))}
+    </div>
+  );
+}
+
+export interface RoleAssignmentDialogProps {
+  /** The principal being edited. A user and a group take the same dialog. */
+  principal: AdminPrincipal | null;
+  /** The principal's current direct assignment. */
+  current: readonly string[];
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * The one editor for a role assignment, for both principal kinds (DESIGN-D22).
+ * It offers the roles the extension declared and nothing else; a role already
+ * assigned that the matrix no longer declares is still listed, marked, and
+ * removable, because hiding it would leave a grant nobody can see or revoke.
+ */
+export function RoleAssignmentDialog({
+  principal,
+  current,
+  onOpenChange,
+}: RoleAssignmentDialogProps) {
+  const { matrix, assignRoles } = useAdminPermissions();
+  const [selected, setSelected] = React.useState<readonly string[]>(current);
+  const [saving, setSaving] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  // Re-seed whenever a different principal is opened — the documented
+  // adjust-state-during-render pattern, not an effect, so the dialog never
+  // paints one principal's roles under another principal's name.
+  const key = principal ? `${principal.kind}:${principal.id}` : null;
+  const [seededKey, setSeededKey] = React.useState<string | null>(key);
+  if (key !== seededKey) {
+    setSeededKey(key);
+    setSelected(current);
+    setError(null);
+  }
+
+  const declared = matrix?.roles ?? [];
+  const retired = current.filter((role) => !declared.includes(role));
+  const options = [...declared, ...retired];
+
+  const toggle = (role: string, checked: boolean) => {
+    setSelected((prev) => (checked ? [...prev, role] : prev.filter((r) => r !== role)));
+  };
+
+  const save = async () => {
+    if (!principal) return;
+    setSaving(true);
+    setError(null);
+    try {
+      await assignRoles(principal, [...selected]);
+      onOpenChange(false);
+    } catch (err) {
+      // The envelope's own message, not a house one (§15.6). The optimistic
+      // write has already been rolled back by `assignRoles`.
+      setError(adminErrorMessage(err));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Dialog open={principal !== null} onOpenChange={(open) => !open && onOpenChange(false)}>
+      <DialogContent data-slot="admin-role-dialog">
+        <DialogHeader>
+          <DialogTitle>Edit roles</DialogTitle>
+          <DialogDescription>
+            {principal?.kind === "group" ? (
+              <>
+                Every member of <strong>{principal.name ?? principal.id}</strong> inherits the roles
+                you select here, as soon as they join.
+              </>
+            ) : (
+              <>
+                Direct assignment for <strong>{principal?.name ?? principal?.id}</strong>. Roles
+                inherited from a group are changed on the group, not here.
+              </>
+            )}
+          </DialogDescription>
+        </DialogHeader>
+        <DialogBody className="flex flex-col gap-2">
+          {error ? <ErrorBanner message={error} data-slot="admin-role-dialog-error" /> : null}
+          {options.length === 0 ? (
+            <p className="text-[length:var(--ds-text-body-sm)] text-[color:var(--ds-muted-foreground)]">
+              This extension has not declared any roles yet.
+            </p>
+          ) : (
+            <ul className="flex flex-col gap-0.5" data-slot="admin-role-options">
+              {options.map((role) => {
+                const checked = selected.includes(role);
+                return (
+                  <li key={role}>
+                    <label
+                      className={cn(
+                        "flex cursor-pointer items-center gap-2.5 rounded-[var(--ds-radius-md)] px-2 py-1.5",
+                        "text-[length:var(--ds-text-body-sm)] text-[color:var(--ds-foreground)]",
+                        "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+                        "hover:bg-[var(--ds-hover)]",
+                      )}
+                    >
+                      {/* No `aria-label`: the wrapping <label> already names
+                          the box, and Base UI points `aria-labelledby` at it.
+                          Both would compute the name as "author author". */}
+                      <Checkbox
+                        checked={checked}
+                        onCheckedChange={(next) => toggle(role, Boolean(next))}
+                      />
+                      <span className="flex-1">{role}</span>
+                      {declared.includes(role) ? null : (
+                        <Chip size="sm" variant="outline" title="Not in the declared vocabulary">
+                          retired
+                        </Chip>
+                      )}
+                    </label>
+                  </li>
+                );
+              })}
+            </ul>
+          )}
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)} disabled={saving}>
+            Cancel
+          </Button>
+          <Button onClick={save} disabled={saving || options.length === 0}>
+            {saving ? <Spinner tone="inverse" /> : null}
+            Save roles
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

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

@@ -0,0 +1,169 @@
+"use client";
+
+import * as React from "react";
+import { Button } from "@/components/button";
+import { Chip } from "@/components/chip";
+import { DataTable, createColumnHelper } from "@/components/data-table";
+import { EmptyState } from "@/components/empty-state";
+import { ErrorBanner } from "@/components/error-banner";
+import { SectionCard } from "@/components/section-card";
+import { useAdminPermissions } from "./context";
+import { DirectRoles, RoleAssignmentDialog } from "./role-assignment";
+import type { AdminGroupRow, AdminPrincipal } from "./types";
+
+const helper = /* @__PURE__ */ createColumnHelper<AdminGroupRow>();
+
+/**
+ * `/admin/roles` — the extension's own vocabulary, and the group principals
+ * that hold it.
+ *
+ * Two halves. The first is what each declared role grants, read straight off
+ * the matrix, so an administrator deciding whether to hand somebody "editor"
+ * can see what "editor" means without leaving the screen. The second is group
+ * assignment: the other kind of principal a role attaches to (DESIGN-D22,
+ * P-42), on the same screen as the users because it is the same decision.
+ *
+ * The groups list is a **client** source, and the members list is not, for one
+ * reason: an org's groups are a short, bounded list that arrives in a single
+ * `groups.list()`, so paging it server-side would be a round-trip per keypress
+ * for nothing. Where the groups come from — a directory sync, or somebody
+ * typing them into cortena-auth — is invisible here by design.
+ *
+ * The whole section disappears when the api has no `groups`, and equally when
+ * it has some and the org has none.
+ */
+export function AdminRoles() {
+  const { matrix, hasGroups, groups, groupsState, groupRoles } = 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: "Group",
+          cell: ({ row }) => (
+            <span className="font-medium text-[color:var(--ds-foreground)]">
+              {row.original.name}
+            </span>
+          ),
+          meta: { label: "Group" },
+        }),
+        helper.accessor("memberCount", {
+          header: "Members",
+          cell: ({ row }) => row.original.memberCount ?? "—",
+          meta: { align: "end", label: "Members" },
+        }),
+        helper.display({
+          id: "roles",
+          header: "Roles",
+          cell: ({ row }) => <DirectRoles roles={groupRoles[row.original.id] ?? []} />,
+          meta: {
+            label: "Roles",
+            exportValue: (row: AdminGroupRow) => (groupRoles[row.id] ?? []).join(", "),
+          },
+          enableSorting: false,
+        }),
+        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(groupRoles[row.original.id] ?? []);
+                  setEditing({ kind: "group", id: row.original.id, name: row.original.name });
+                }}
+              >
+                Edit roles
+              </Button>
+            </div>
+          ),
+          meta: { align: "end", exportable: false },
+          enableSorting: false,
+          enableHiding: false,
+        }),
+      ]),
+    [groupRoles],
+  );
+
+  const roles = matrix?.roles ?? [];
+
+  return (
+    <div data-slot="admin-roles" className="flex flex-col gap-6">
+      <SectionCard
+        title="Roles"
+        description="Declared by this extension. Nothing on the platform reads these names, so they are the extension's to choose."
+      >
+        {roles.length === 0 ? (
+          <EmptyState
+            size="compact"
+            title="No roles declared"
+            description="Roles come from this extension's permissions document. Until it declares some, there is nothing to assign."
+          />
+        ) : (
+          <ul data-slot="admin-role-list" className="flex flex-col gap-2">
+            {roles.map((role) => {
+              const granted = matrix?.grants[role] ?? [];
+              return (
+                <li
+                  key={role}
+                  data-slot="admin-role-summary"
+                  data-role={role}
+                  className="flex flex-col gap-1.5 rounded-[var(--ds-radius-md)] border border-[var(--ds-border-subtle)] bg-[var(--ds-muted)] px-3 py-2.5"
+                >
+                  <span className="text-[length:var(--ds-text-body-sm)] font-semibold text-[color:var(--ds-foreground)]">
+                    {role}
+                  </span>
+                  {granted.length === 0 ? (
+                    <span className="text-[length:var(--ds-text-caption)] text-[color:var(--ds-text-tertiary)]">
+                      Grants nothing yet
+                    </span>
+                  ) : (
+                    <div className="flex flex-wrap items-center gap-1">
+                      {granted.map((action) => (
+                        <Chip key={action} size="sm" variant="outline" data-action={action}>
+                          {action}
+                        </Chip>
+                      ))}
+                    </div>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </SectionCard>
+
+      {groupsState.error ? (
+        <ErrorBanner message={groupsState.error.message} onRetry={groupsState.reload} />
+      ) : null}
+
+      {hasGroups ? (
+        <SectionCard
+          title="Groups"
+          description="Groups are cortena-auth's and read-only here. Every member of a group inherits the roles assigned to it, with no assignment write of their own."
+          flush
+        >
+          <DataTable
+            columns={columns}
+            dataSource={{ kind: "client", rows: groups }}
+            getRowId={(row) => row.id}
+            searchPlaceholder="Search groups…"
+            emptyMessage="No groups"
+            exportFileName="groups"
+          />
+        </SectionCard>
+      ) : null}
+
+      <RoleAssignmentDialog
+        principal={editing}
+        current={editingRoles}
+        onOpenChange={(open) => !open && setEditing(null)}
+      />
+    </div>
+  );
+}

package/src/components/admin-permissions/types.ts

@@ -0,0 +1,231 @@
+/**
+ * The contract AdminPermissions renders, from §13.3 of
+ * "How to create a Cortena extension" (DESIGN-D11, amended by DESIGN-D22).
+ *
+ * The composition ships **no vocabulary of its own**. Every role, every action
+ * and every grant on screen arrives through the `api` prop; every principal
+ * arrives through it too. That is what lets two extensions with completely
+ * different role models look like one product — and it is why nothing in this
+ * folder has a default role list, a default action list, or an opinion about
+ * what "admin" means.
+ *
+ * The split the screen is built around:
+ *
+ * | cortena-auth owns | the extension owns |
+ * | --- | --- |
+ * | who the user is, their org membership and status | every role it recognises |
+ * | the groups, their names and their membership | the roles × actions matrix |
+ * | the licence | which principal holds which role |
+ *
+ * So the person half of the members list is read-only here, the group half is
+ * read-only too, and the roles beside them are the only editable thing.
+ *
+ * Where the groups come from is deliberately invisible: an extension asks
+ * `api.groups` for `{ id, name, memberCount }` and never learns whether that
+ * is a directory sync, an SCIM push or a hand-made list in cortena-auth.
+ */
+
+import type { TableQuery, TableResult } from "@/components/data-table";
+
+/**
+ * A role is assigned to a principal, never to a user id (DESIGN-D22, §13.4).
+ * Both kinds are edited on the same screen and through the same dialog; only
+ * the method underneath differs.
+ */
+export interface AdminPrincipal {
+  kind: "user" | "group";
+  /** cortena-auth user id, or cortena-auth group id. */
+  id: string;
+  /** Display name, for the dialog title. */
+  name?: string;
+}
+
+/** A group, as a member's row refers to it. Defined and maintained in cortena-auth. */
+export interface AdminGroupRef {
+  id: string;
+  name: string;
+}
+
+/**
+ * Why a member holds an effective role: assigned to them directly, or carried
+ * by a group they belong to. Never dropped from the rendering — an
+ * administrator who cannot see *why* somebody has a permission removes the
+ * wrong assignment and believes the job is done (P-43).
+ */
+export type AdminRoleSource = "direct" | { group: AdminGroupRef };
+
+/** One entry of `effectiveRoles`: the role, and the assignment that granted it. */
+export interface AdminEffectiveRole {
+  role: string;
+  source: AdminRoleSource;
+}
+
+/**
+ * A row of `members.list`. A join: the person and their groups are
+ * cortena-auth's and read-only; `extensionRoles` is the extension's own direct
+ * assignment; `effectiveRoles` is the per-request resolution of direct +
+ * inherited that `may()` performs, rendered — never a stored table (P-43).
+ */
+export interface AdminMemberRow {
+  userId: string;
+  name: string;
+  email: string;
+  status: string;
+  /** ISO timestamp, or null when the user has never signed in. */
+  lastActiveAt: string | null;
+  groups: AdminGroupRef[];
+  extensionRoles: string[];
+  effectiveRoles: AdminEffectiveRole[];
+}
+
+/**
+ * A row of `groups.list` — read-only as to the group itself. The roles a group
+ * carries are the extension's and come back separately from `groups.roles()`,
+ * because the group list is identity's and the assignment map is not.
+ */
+export interface AdminGroupRow {
+  id: string;
+  name: string;
+  memberCount: number;
+}
+
+/** `licence.get` — a read-through display of cortena-auth's licence. */
+export interface AdminLicence {
+  plan: string;
+  seats: number | null;
+  seatsUsed: number | null;
+  features: string[];
+}
+
+/**
+ * `permissions.get` / `permissions.put` — the extension's own matrix, in the
+ * extension's own database. This is the source of truth that both the REST
+ * routes and the MCP tools enforce through one `may()` (§13.2, P-14).
+ */
+export interface AdminPermissionMatrix {
+  roles: string[];
+  actions: string[];
+  /** role → the actions it grants. A role absent from the map grants nothing. */
+  grants: Record<string, string[]>;
+}
+
+/**
+ * Everything the composition talks to, one namespace per resource in §13.3.
+ *
+ * `groups` is the only optional member, and it is optional for a reason rather
+ * than for convenience: an extension whose cortena-auth tenant has no groups
+ * omits it, and every group affordance disappears instead of rendering empty.
+ * It disappears equally when `groups.list()` comes back empty — an empty
+ * "Groups" section reads as a broken feature, and there is nothing an
+ * administrator can do about it from here.
+ */
+export interface AdminPermissionsApi {
+  members: {
+    /** `GET .../admin/members` — the DataTable server source. */
+    list: (query: TableQuery, signal?: AbortSignal) => Promise<TableResult<AdminMemberRow>>;
+    /** `PATCH .../admin/members/:userId { extensionRoles }` — direct assignment only. */
+    setRoles: (userId: string, roles: string[]) => Promise<void>;
+  };
+  groups?: {
+    /** `GET .../admin/groups` — read-only; the whole list, small enough to be a client source. */
+    list: (signal?: AbortSignal) => Promise<AdminGroupRow[]>;
+    /** The extension's assignment: group id → the roles that group carries. */
+    roles: (signal?: AbortSignal) => Promise<Record<string, string[]>>;
+    /** `PATCH .../admin/groups/:groupId { extensionRoles }` */
+    setRoles: (groupId: string, roles: string[]) => Promise<void>;
+  };
+  licence: {
+    /** `GET .../admin/licence` — read-only, always. */
+    get: (signal?: AbortSignal) => Promise<AdminLicence>;
+  };
+  permissions: {
+    /** `GET .../admin/permissions` */
+    get: (signal?: AbortSignal) => Promise<AdminPermissionMatrix>;
+    /** `PUT .../admin/permissions` */
+    put: (
+      matrix: AdminPermissionMatrix,
+      signal?: AbortSignal,
+    ) => Promise<AdminPermissionMatrix | void>;
+  };
+}
+
+/** The four screens, named after their paths under `admin/`. */
+export type AdminRoute = "members" | "roles" | "licence" | "permissions";
+
+export const ADMIN_ROUTES: readonly AdminRoute[] = [
+  "members",
+  "roles",
+  "licence",
+  "permissions",
+];
+
+export const ADMIN_ROUTE_LABELS: Record<AdminRoute, string> = {
+  members: "Members",
+  roles: "Roles",
+  licence: "Licence",
+  permissions: "Permissions",
+};
+
+/**
+ * The broker's error envelope (§15.6). A failed mutation must show what the
+ * server said — "assigneeId: Required" and "Invalid input" cost the same to
+ * produce and differ by a whole round-trip — so the rejection is unwrapped
+ * rather than replaced with a house message.
+ */
+export interface AdminErrorEnvelope {
+  ok: false;
+  status?: number;
+  code?: string;
+  message: string;
+  details?: unknown;
+}
+
+function envelopeMessage(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const message = (value as { message?: unknown }).message;
+  return typeof message === "string" && message.length > 0 ? message : null;
+}
+
+/**
+ * The message to show for a rejection.
+ *
+ * A fetch wrapper usually rejects with an `Error` and hangs the parsed
+ * envelope off it, so the envelope is preferred over the generic
+ * `"HTTP 403"` the Error itself carries. A rejection that *is* the envelope,
+ * and a plain `Error`, both work as well.
+ */
+export function adminErrorMessage(error: unknown): string {
+  if (error && typeof error === "object") {
+    const carrier = error as { envelope?: unknown; body?: unknown; error?: unknown };
+    const nested =
+      envelopeMessage(carrier.envelope) ??
+      envelopeMessage(carrier.body) ??
+      envelopeMessage(carrier.error);
+    if (nested) return nested;
+  }
+  if (error instanceof Error) return error.message || "Something went wrong";
+  const direct = envelopeMessage(error);
+  if (direct) return direct;
+  return String(error);
+}
+
+/** Tolerates a server that omits an array the contract says is required. */
+export function groupsOf(row: AdminMemberRow): AdminGroupRef[] {
+  return row.groups ?? [];
+}
+
+/**
+ * The effective roles to render. When the server sends none, the direct
+ * assignments are shown as direct — which is what they are — rather than the
+ * screen inventing an inheritance it cannot know about.
+ */
+export function effectiveRolesOf(row: AdminMemberRow): AdminEffectiveRole[] {
+  if (row.effectiveRoles?.length) return row.effectiveRoles;
+  return (row.extensionRoles ?? []).map((role) => ({ role, source: "direct" as const }));
+}
+
+/** The group behind an effective role, or `null` for a direct assignment. */
+export function sourceGroupOf(source: AdminRoleSource): AdminGroupRef | null {
+  if (source === "direct" || !source) return null;
+  return source.group ?? null;
+}