@terpjs/react-core 0.1.0

package/src/UserMenu.test.tsx

@@ -0,0 +1,166 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { TerpProvider, useAuth } from "./TerpProvider";
+import { UserMenu, userInitials } from "./UserMenu";
+import { LOCALE_EN, LocaleProvider } from "./locale";
+import { ThemeProvider } from "./theme";
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  window.localStorage.clear();
+  document.documentElement.removeAttribute("data-theme");
+});
+
+function LogInOnMount() {
+  const auth = useAuth();
+  useEffect(() => {
+    void auth.login({ email: "jane.doe@example.com", password: "pw" });
+  }, []);
+  return null;
+}
+
+function stubAuthFetch() {
+  const fetchMock = vi.fn<typeof fetch>(async (input) => {
+    const url = (input as Request).url;
+    if (url.endsWith("/api/v1/auth/login")) {
+      return jsonResponse({ access_token: "token", token_type: "bearer" });
+    }
+    if (url.endsWith("/api/v1/auth/logout")) {
+      return new Response(null, { status: 204 });
+    }
+    return jsonResponse({
+      id: "u1",
+      email: "jane.doe@example.com",
+      role_rank: 20,
+      role_name: "editor",
+    });
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("userInitials", () => {
+  it("derives initials from the email's local part", () => {
+    expect(userInitials("jane.doe@example.com")).toBe("JD");
+    expect(userInitials("admin@example.test")).toBe("A");
+    expect(userInitials("@example.test")).toBe("?");
+  });
+});
+
+describe("UserMenu", () => {
+  it("renders nothing while signed out", () => {
+    stubAuthFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <UserMenu />
+      </TerpProvider>,
+    );
+    expect(screen.queryByRole("button", { name: "Account menu" })).not.toBeInTheDocument();
+  });
+
+  it("shows the avatar initials, email and role, and opens the panel", async () => {
+    stubAuthFetch();
+    render(
+      <ThemeProvider>
+        <LocaleProvider locales={{ en: LOCALE_EN, nl: { label: "Nederlands" } }}>
+          <TerpProvider baseUrl="https://api.test">
+            <LogInOnMount />
+            <UserMenu />
+          </TerpProvider>
+        </LocaleProvider>
+      </ThemeProvider>,
+    );
+    const trigger = await screen.findByRole("button", { name: "Account menu" });
+    expect(screen.getByText("JD")).toBeInTheDocument();
+    expect(screen.getByText("jane.doe@example.com")).toBeInTheDocument();
+    expect(screen.getByText("editor")).toBeInTheDocument();
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    // The panel shows the identity block and offers sign-out (Settings needs onSettings).
+    expect(screen.getAllByText("jane.doe@example.com")).toHaveLength(2);
+    expect(screen.queryByRole("menuitem", { name: "Settings" })).not.toBeInTheDocument();
+    expect(screen.getByRole("menuitem", { name: "Sign out" })).toBeInTheDocument();
+  });
+
+  it("opens the settings page and closes the panel", async () => {
+    stubAuthFetch();
+    const onSettings = vi.fn();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <UserMenu onSettings={onSettings} />
+      </TerpProvider>,
+    );
+    fireEvent.click(await screen.findByRole("button", { name: "Account menu" }));
+    fireEvent.click(screen.getByRole("menuitem", { name: "Settings" }));
+    expect(onSettings).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("menuitem", { name: "Sign out" })).not.toBeInTheDocument();
+  });
+
+  it("shows only the avatar on the trigger when collapsed", async () => {
+    stubAuthFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <UserMenu collapsed />
+      </TerpProvider>,
+    );
+    const trigger = await screen.findByRole("button", { name: "Account menu" });
+    expect(screen.getByText("JD")).toBeInTheDocument();
+    expect(screen.queryByText("jane.doe@example.com")).not.toBeInTheDocument();
+    expect(trigger.style.width).toBe("100%");
+    expect(trigger.style.boxSizing).toBe("border-box");
+    expect(trigger.style.justifyContent).toBe("center");
+    expect(trigger.style.padding).toBe("0px");
+    // The identity still surfaces inside the opened panel.
+    fireEvent.click(trigger);
+    expect(screen.getByText("jane.doe@example.com")).toBeInTheDocument();
+  });
+
+  it("signs out via the menu (revokes the token server-side)", async () => {
+    const fetchMock = stubAuthFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <UserMenu />
+      </TerpProvider>,
+    );
+    fireEvent.click(await screen.findByRole("button", { name: "Account menu" }));
+    fireEvent.click(screen.getByRole("menuitem", { name: "Sign out" }));
+    await waitFor(() =>
+      expect(
+        fetchMock.mock.calls.some(([input]) =>
+          (input as Request).url.endsWith("/api/v1/auth/logout"),
+        ),
+      ).toBe(true),
+    );
+  });
+
+  it("closes on Escape", async () => {
+    stubAuthFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <UserMenu />
+      </TerpProvider>,
+    );
+    const trigger = await screen.findByRole("button", { name: "Account menu" });
+    fireEvent.click(trigger);
+    expect(screen.getByRole("menuitem", { name: "Sign out" })).toBeInTheDocument();
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(screen.queryByRole("menuitem", { name: "Sign out" })).not.toBeInTheDocument();
+  });
+});

package/src/UserMenu.tsx

@@ -0,0 +1,125 @@
+import type { CSSProperties } from "react";
+
+import { Icon } from "./icons";
+import { useAuth } from "./TerpProvider";
+import { Menu, MenuItem } from "./ui/Menu";
+import { CONTROL_TEXT_STYLE } from "./ui/controlStyles";
+import { useStrings } from "./uiText";
+
+/** Initials for the avatar: the first letters of the email's local-part words. */
+export function userInitials(email: string): string {
+  const local = email.split("@")[0] ?? "";
+  const words = local.split(/[._+-]+/).filter((word) => word.length > 0);
+  const initials = words.slice(0, 2).map((word) => word[0]!.toUpperCase());
+  return initials.join("") || "?";
+}
+
+const triggerStyle: CSSProperties = {
+  ...CONTROL_TEXT_STYLE,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "flex-start",
+  gap: "var(--space-2)",
+  width: "100%",
+  boxSizing: "border-box",
+  padding: "var(--space-2)",
+  textAlign: "left",
+  color: "var(--color-neutral-900)",
+  background: "transparent",
+  border: "1px solid transparent",
+  borderRadius: "var(--radius-md)",
+  cursor: "pointer",
+};
+
+const collapsedTriggerStyle: CSSProperties = {
+  justifyContent: "center",
+  gap: 0,
+  padding: 0,
+};
+
+const avatarStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: "2rem",
+  height: "2rem",
+  flexShrink: 0,
+  borderRadius: "var(--radius-full)",
+  background: "var(--color-brand-primary)",
+  color: "var(--color-brand-primary-contrast)",
+  fontSize: "var(--font-size-sm)",
+  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
+};
+
+const identityStyle: CSSProperties = { display: "grid", minWidth: 0, fontSize: "var(--font-size-sm)" };
+const emailStyle: CSSProperties = { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" };
+const roleStyle: CSSProperties = { color: "var(--color-neutral-600)" };
+const panelIdentityStyle: CSSProperties = {
+  display: "grid",
+  gap: "var(--space-1)",
+  padding: "var(--space-2)",
+  marginBottom: "var(--space-1)",
+  borderBottom: "1px solid var(--color-neutral-200)",
+  fontSize: "var(--font-size-sm)",
+  overflowWrap: "anywhere",
+};
+
+export interface UserMenuProps {
+  /** Icon-rail mode: show only the avatar on the trigger (the shell's collapsed state). */
+  collapsed?: boolean;
+  /** Opens the settings / profile page; rendered as the menu's first item when provided. */
+  onSettings?: () => void;
+}
+
+/** The signed-in user's account menu. */
+export function UserMenu({ collapsed = false, onSettings }: UserMenuProps = {}) {
+  const auth = useAuth();
+  const strings = useStrings();
+  const user = auth.currentUser();
+  if (user === null) {
+    return null;
+  }
+
+  const trigger = (
+    <>
+      <span aria-hidden="true" style={avatarStyle}>{userInitials(user.email)}</span>
+      {!collapsed && (
+        <span style={identityStyle}>
+          <span style={emailStyle}>{user.email}</span>
+          <span style={roleStyle}>{user.role_name}</span>
+        </span>
+      )}
+    </>
+  );
+
+  return (
+    <Menu
+      trigger={trigger}
+      triggerLabel={strings.accountMenu}
+      placement="top"
+      align="start"
+      triggerStyle={collapsed ? { ...triggerStyle, ...collapsedTriggerStyle } : triggerStyle}
+      panelStyle={{ minWidth: "14rem", padding: "var(--space-2)" }}
+    >
+      {({ close }) => (
+        <>
+          <div style={panelIdentityStyle}>
+            <span>{user.email}</span>
+            <span style={roleStyle}>{user.role_name}</span>
+          </div>
+          {onSettings !== undefined && (
+            <MenuItem
+              label={strings.settings}
+              icon={<Icon name="user" />}
+              onSelect={() => {
+                close(true);
+                onSettings();
+              }}
+            />
+          )}
+          <MenuItem label={strings.signOut} icon={<Icon name="logout" />} onSelect={() => void auth.logout()} />
+        </>
+      )}
+    </Menu>
+  );
+}

package/src/admin/AdminHub.tsx

@@ -0,0 +1,108 @@
+import { Link } from "@tanstack/react-router";
+import { useEffect, useState } from "react";
+
+import { HubCard, HubPage } from "../HubPage";
+import type { RenderHubCardLink } from "../HubPage";
+import type { AdminAreaSections } from "../bootstrap";
+import { NavIcon } from "../icons";
+import { useTerpClient } from "../TerpProvider";
+import { unwrap } from "../unwrap";
+import { useStrings } from "../uiText";
+
+const renderLink: RenderHubCardLink = ({ to, children }) => <Link to={to}>{children}</Link>;
+
+interface HubStats {
+  users: number | null;
+  groups: number | null;
+}
+
+/**
+ * Live totals for the hub cards (a `limit=1` page carries the exact total).
+ * A section the app dropped never fires its call — its capability may not be
+ * mounted at all.
+ */
+function useHubStats(sections: Required<AdminAreaSections>): HubStats {
+  const client = useTerpClient();
+  const [stats, setStats] = useState<HubStats>({ users: null, groups: null });
+  const { users: wantUsers, groups: wantGroups } = sections;
+  useEffect(() => {
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        const [users, groups] = await Promise.all([
+          wantUsers
+            ? client.GET("/api/v1/users/", {
+                params: { query: { limit: 1 } },
+                signal: controller.signal,
+              })
+            : null,
+          wantGroups
+            ? client.GET("/api/v1/groups/", {
+                params: { query: { limit: 1 } },
+                signal: controller.signal,
+              })
+            : null,
+        ]);
+        setStats({
+          users: users !== null ? unwrap(users).total : null,
+          groups: groups !== null ? unwrap(groups).total : null,
+        });
+      } catch {
+        // The cards stay navigable without their stat lines (e.g. offline, races).
+      }
+    })();
+    return () => controller.abort();
+  }, [client, wantUsers, wantGroups]);
+  return stats;
+}
+
+/**
+ * The packaged admin hub (`/admin`): one card per administration area — users,
+ * groups and the audit log — with live totals where they are cheap to know.
+ * The sidebar's single "Admin" entry opens this hub; the overviews breadcrumb
+ * back to it, keeping the hub -> overview -> detail layering every Terp screen
+ * follows. `sections` (default: all) mirrors the app's `adminArea` selection —
+ * a dropped section loses its card and its stat call.
+ */
+export function AdminHub({ sections }: { sections?: AdminAreaSections } = {}) {
+  const strings = useStrings();
+  const selected = {
+    users: sections?.users !== false,
+    groups: sections?.groups !== false,
+    audit: sections?.audit !== false,
+  };
+  const stats = useHubStats(selected);
+  return (
+    <HubPage title={strings.admin} parents={[{ label: strings.home, to: "/" }]}>
+      {selected.users && (
+        <HubCard
+          to="/admin/users"
+          title={strings.adminUsers}
+          description={strings.adminUsersDescription}
+          icon={<NavIcon name="users" label={strings.adminUsers} />}
+          stat={stats.users !== null ? String(stats.users) : undefined}
+          renderLink={renderLink}
+        />
+      )}
+      {selected.groups && (
+        <HubCard
+          to="/admin/groups"
+          title={strings.adminGroups}
+          description={strings.adminGroupsDescription}
+          icon={<NavIcon name="shield" label={strings.adminGroups} />}
+          stat={stats.groups !== null ? String(stats.groups) : undefined}
+          renderLink={renderLink}
+        />
+      )}
+      {selected.audit && (
+        <HubCard
+          to="/admin/audit"
+          title={strings.adminAudit}
+          description={strings.adminAuditDescription}
+          icon={<NavIcon name="audit" label={strings.adminAudit} />}
+          renderLink={renderLink}
+        />
+      )}
+    </HubPage>
+  );
+}

package/src/admin/AuditLogAdmin.tsx

@@ -0,0 +1,116 @@
+import { useMemo } from "react";
+import type { components } from "@terpjs/contract";
+
+import { Page } from "../Page";
+import { useTerpClient } from "../TerpProvider";
+import { DataView, HttpDataViewRepository, useServerDataView } from "../dataview";
+import type { DataViewColumn } from "../dataview";
+import { DetailList } from "../layout";
+import { useStrings } from "../uiText";
+import type { TerpStrings } from "../uiText";
+import { unwrap } from "../unwrap";
+
+import { adminCrumb, renderAdminCrumb } from "./crumbs";
+
+type AuditEventRead = components["schemas"]["AuditEventRead"];
+
+function buildColumns(strings: TerpStrings): DataViewColumn<AuditEventRead>[] {
+  return [
+    {
+      id: "created_at",
+      header: strings.whenColumn,
+      accessor: (e) => e.created_at,
+      cell: (e) => new Date(e.created_at).toLocaleString(),
+      meta: { mobileSlot: "date", width: 170 },
+    },
+    {
+      id: "action",
+      header: strings.actionColumn,
+      accessor: (e) => e.action,
+      meta: { mobileSlot: "status", width: 100 },
+    },
+    {
+      id: "target",
+      header: strings.targetColumn,
+      accessor: (e) => `${e.target_type} ${e.target_id}`,
+      cell: (e) => `${e.target_type} · ${e.target_id.slice(0, 8)}`,
+      meta: { mobileSlot: "title" },
+    },
+    {
+      id: "actor",
+      header: strings.actorColumn,
+      accessor: (e) => e.actor_id ?? "",
+      cell: (e) => (e.actor_id === null ? "—" : e.actor_id.slice(0, 8)),
+      meta: { mobileSlot: "subtitle", width: 110 },
+    },
+  ];
+}
+
+const payloadStyle = {
+  margin: 0,
+  padding: "var(--space-3)",
+  background: "var(--color-neutral-100)",
+  borderRadius: "var(--radius-md)",
+  fontSize: "var(--font-size-sm, 0.875rem)",
+  overflowX: "auto" as const,
+};
+
+/**
+ * The packaged audit-log screen (`/admin/audit`): the append-only trail every
+ * mutation lands in (ADR 0007), newest first as served, read-only by design.
+ * A row expands to the full identifiers and the redacted payload snapshot.
+ */
+export function AuditLogAdmin() {
+  const client = useTerpClient();
+  const strings = useStrings();
+  const serverQuery = useServerDataView({ initialPageSize: 25 });
+
+  const columns = useMemo(() => buildColumns(strings), [strings]);
+  const repository = useMemo(
+    () =>
+      new HttpDataViewRepository<AuditEventRead>({
+        getRowId: (e) => e.id,
+        search: false,
+        request: async ({ skip, limit }, signal) => {
+          const page = unwrap(
+            await client.GET("/api/v1/audit/", {
+              params: { query: { skip, limit } },
+              signal,
+            }),
+          );
+          return { items: page.items, total: page.total };
+        },
+      }),
+    [client],
+  );
+
+  return (
+    <Page
+      title={strings.adminAudit}
+      breadcrumbs={[adminCrumb(strings)]}
+      renderLink={renderAdminCrumb}
+    >
+      <DataView<AuditEventRead>
+        viewId="terp.admin.audit"
+        repository={repository}
+        columns={columns}
+        serverQuery={serverQuery}
+        pageSizeOptions={[25, 50, 100]}
+        renderExpanded={(event) => (
+          <div>
+            <DetailList
+              items={[
+                { label: strings.targetColumn, value: `${event.target_type} ${event.target_id}` },
+                { label: strings.actorColumn, value: event.actor_id ?? "—" },
+                { label: "Request", value: event.request_id ?? "—" },
+              ]}
+            />
+            {event.payload !== null && (
+              <pre style={payloadStyle}>{JSON.stringify(event.payload, null, 2)}</pre>
+            )}
+          </div>
+        )}
+      />
+    </Page>
+  );
+}

package/src/admin/GroupCreate.tsx

@@ -0,0 +1,90 @@
+import { useNavigate } from "@tanstack/react-router";
+import { useState } from "react";
+import type { FormEvent } from "react";
+
+import { Field } from "../Field";
+import { Icon } from "../icons";
+import { Stack } from "../layout";
+import { Page } from "../Page";
+import { PageActions } from "../PageActions";
+import { useTerpClient } from "../TerpProvider";
+import { useToast } from "../toast";
+import { Button } from "../ui/Button";
+import { Input } from "../ui/Input";
+import { useStrings } from "../uiText";
+import { unwrap } from "../unwrap";
+
+import { adminCrumb, renderAdminCrumb } from "./crumbs";
+
+const FORM_ID = "terp-admin-group-create";
+
+/** Dedicated group-creation page (`/admin/groups/new`). */
+export function GroupCreate() {
+  const client = useTerpClient();
+  const navigate = useNavigate();
+  const strings = useStrings();
+  const toast = useToast();
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [creating, setCreating] = useState(false);
+
+  async function onSubmit(event: FormEvent) {
+    event.preventDefault();
+    setCreating(true);
+    try {
+      const group = unwrap(
+        await client.POST("/api/v1/groups/", { body: { name, description } }),
+      );
+      toast.success(strings.saved);
+      await navigate({
+        to: "/admin/groups/$groupId",
+        params: { groupId: group.id },
+      });
+    } catch (error) {
+      toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+    } finally {
+      setCreating(false);
+    }
+  }
+
+  return (
+    <Page
+      title={strings.createGroup}
+      breadcrumbs={[
+        { ...adminCrumb(strings), to: "/admin" },
+        { label: strings.adminGroups, to: "/admin/groups" },
+      ]}
+      renderLink={renderAdminCrumb}
+      actions={
+        <PageActions
+          secondary={
+            <Button variant="secondary" onClick={() => void navigate({ to: "/admin/groups" })}>
+              {strings.cancel}
+            </Button>
+          }
+          primary={
+            <Button
+              type="submit"
+              form={FORM_ID}
+              icon={<Icon name="plus" />}
+              disabled={creating}
+            >
+              {creating ? strings.working : strings.createGroup}
+            </Button>
+          }
+        />
+      }
+    >
+      <div style={{ maxWidth: "32rem" }}>
+        <Stack id={FORM_ID} as="form" gap={4} onSubmit={onSubmit}>
+          <Field label={strings.groupName}>
+            <Input value={name} onChange={(event) => setName(event.target.value)} required />
+          </Field>
+          <Field label={strings.description}>
+            <Input value={description} onChange={(event) => setDescription(event.target.value)} />
+          </Field>
+        </Stack>
+      </div>
+    </Page>
+  );
+}