@terpjs/react-core 0.1.0

package/src/HubPage.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { HubCard, HubPage } from "./HubPage";
+
+afterEach(cleanup);
+
+describe("HubPage", () => {
+  it("renders the h1 title and a grid of cards", () => {
+    render(
+      <HubPage title="Administration">
+        <HubCard to="/users" title="Users" description="Manage accounts" />
+        <HubCard to="/roles" title="Roles" />
+      </HubPage>,
+    );
+
+    expect(screen.getByRole("heading", { level: 1, name: "Administration" })).toBeInTheDocument();
+    expect(screen.queryByRole("navigation", { name: "Breadcrumb" })).not.toBeInTheDocument();
+    expect(screen.getAllByText("Administration")).toHaveLength(1);
+    expect(screen.getByRole("list")).toHaveStyle({ gridAutoRows: "1fr" });
+    expect(screen.getByRole("link", { name: /Users/ })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /Roles/ })).toBeInTheDocument();
+    expect(screen.getByText("Manage accounts")).toBeInTheDocument();
+  });
+
+  it("uses the normal breadcrumb frame when the hub is nested", () => {
+    render(
+      <HubPage title="Administration" parents={[{ label: "Home", to: "/" }]}>
+        <HubCard to="/users" title="Users" />
+      </HubPage>,
+    );
+
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toHaveTextContent(
+      "HomeAdministration",
+    );
+    expect(screen.getByRole("link", { name: "Home" })).toHaveAttribute("href", "/");
+  });
+
+  it("keeps the base Page breadcrumbs prop as a compatibility alias", () => {
+    render(
+      <HubPage title="Administration" breadcrumbs={[{ label: "Home", to: "/" }]}>
+        <HubCard to="/users" title="Users" />
+      </HubPage>,
+    );
+    expect(screen.getByRole("link", { name: "Home" })).toHaveAttribute("href", "/");
+  });
+});
+
+describe("HubCard", () => {
+  it("links the whole card to its destination by default", () => {
+    render(
+      <HubPage title="Hub">
+        <HubCard to="/users" title="Users" />
+      </HubPage>,
+    );
+
+    expect(screen.getByRole("link", { name: "Users" })).toHaveAttribute("href", "/users");
+  });
+
+  it("renders through the supplied link renderer and shows the live stat", () => {
+    render(
+      <HubPage title="Hub">
+        <HubCard
+          to="/users"
+          title="Users"
+          stat={<span>142 active</span>}
+          renderLink={({ to, children }) => (
+            <a href={to} data-router="stack">
+              {children}
+            </a>
+          )}
+        />
+      </HubPage>,
+    );
+
+    const link = screen.getByRole("link", { name: /Users/ });
+    expect(link).toHaveAttribute("data-router", "stack");
+    expect(screen.getByText("142 active")).toBeInTheDocument();
+  });
+
+  it("reserves the same internal tracks when optional card content is absent", () => {
+    render(
+      <HubPage title="Hub">
+        <HubCard to="/short" title="Short" />
+        <HubCard to="/full" title="Full" description="Description" stat="12" />
+      </HubPage>,
+    );
+
+    const bodies = screen.getAllByText(/Short|Full/, { selector: "strong" }).map(
+      (title) => title.closest('[data-terp="hubcard-body"]'),
+    );
+    expect(bodies).toHaveLength(2);
+    for (const body of bodies) {
+      expect(body).toHaveStyle({
+        gridTemplateRows: "auto minmax(3rem, 1fr) auto",
+        minHeight: "10rem",
+      });
+    }
+    const shortBody = bodies[0]!;
+    expect(shortBody.querySelector('[data-terp="hubcard-description"]')).toHaveStyle({
+      visibility: "hidden",
+    });
+    expect(shortBody.querySelector('[data-terp="hubcard-stat"]')).toHaveStyle({
+      visibility: "hidden",
+    });
+  });
+});

package/src/HubPage.tsx

@@ -0,0 +1,204 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
+
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+import { useLayoutContract, verifySlotChildren } from "./layoutContract";
+import { injectTerpStyles } from "./styles";
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+injectTerpStyles();
+
+export type HubPageProps = Omit<
+  PageProps,
+  "isLoading" | "loadingState" | "error" | "errorState"
+> & {
+  /** Parent trail for nested hubs; aliases the base Page's `breadcrumbs` prop. */
+  parents?: PageProps["breadcrumbs"];
+};
+
+const gridStyle: CSSProperties = {
+  display: "grid",
+  gridTemplateColumns: "repeat(auto-fit, minmax(min(16rem, 100%), 1fr))",
+  gridAutoRows: "1fr",
+  gap: "var(--space-4)",
+  alignItems: "stretch",
+  listStyle: "none",
+  margin: 0,
+  padding: 0,
+};
+
+/**
+ * The landing / hub page archetype: a `Page` whose body is a responsive grid of
+ * {@link HubCard} links into the sub-areas of a domain. Use it as a module index that
+ * adds discovery value (each card can carry a live `stat`, making the hub a lightweight
+ * dashboard) — never as a mandatory speed-bump in front of a single frequently-used list.
+ */
+export function HubPage({ children, parents, breadcrumbs, ...page }: HubPageProps) {
+  // The runtime half of the slot-typed layout contract control (ADR 0079) for the hub
+  // grid: with a contract active, every rendered child of the grid must be a HubCard
+  // (its data-terp marker) — verified one macrotask after mount, refused fail closed.
+  const contract = useLayoutContract();
+  const gridRef = useRef<HTMLUListElement>(null);
+  const [slotViolation, setSlotViolation] = useState<string | null>(null);
+  useEffect(() => {
+    if (contract === null) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      const grid = gridRef.current;
+      if (grid === null) {
+        return;
+      }
+      setSlotViolation(verifySlotChildren(contract, "HubPage", [...grid.children]));
+    }, 0);
+    return () => clearTimeout(timer);
+  });
+  if (slotViolation !== null) {
+    throw new Error(slotViolation);
+  }
+  return (
+    <Page {...page} breadcrumbs={parents ?? breadcrumbs}>
+      <ul ref={gridRef} style={gridStyle}>
+        {children}
+      </ul>
+    </Page>
+  );
+}
+
+/** Wraps a card's content in the active stack's link (keeps the hub router-agnostic). */
+export type RenderHubCardLink = (props: { to: string; children: ReactNode }) => ReactNode;
+
+export interface HubCardProps {
+  /** Destination path of the sub-area the card opens. */
+  to: string;
+  /** Card title (the sub-area's name). */
+  title: UiText;
+  /** Short explanation of the area. */
+  description?: UiText;
+  /** Optional leading icon (any rendered node — react-core takes no icon dependency). */
+  icon?: ReactNode;
+  /**
+   * Optional live summary (e.g. "142 active - 3 inactive"). Turns the hub into a
+   * lightweight dashboard rather than a duplicate of the sidebar.
+   */
+  stat?: ReactNode;
+  /** Link renderer (default: a plain `<a href>`); pass the stack's `Link`, like `AppShell`. */
+  renderLink?: RenderHubCardLink;
+}
+
+const cardStyle: CSSProperties = {
+  height: "100%",
+  minHeight: 0,
+};
+
+const cardBodyStyle: CSSProperties = {
+  display: "grid",
+  gridTemplateRows: "auto minmax(3rem, 1fr) auto",
+  gap: "var(--space-2)",
+  height: "100%",
+  minHeight: "10rem",
+  padding: "var(--space-4)",
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-lg)",
+  background: "var(--color-neutral-0)",
+  color: "var(--color-neutral-900)",
+  boxSizing: "border-box",
+};
+
+const cardTitleRowStyle: CSSProperties = {
+  margin: 0,
+  display: "flex",
+  alignItems: "center",
+  gap: "var(--space-3)",
+};
+
+const iconTileStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  width: "2.25rem",
+  height: "2.25rem",
+  flexShrink: 0,
+  borderRadius: "var(--radius-md)",
+  background: "var(--color-brand-primary-soft)",
+  color: "var(--color-brand-primary)",
+};
+
+const titleTextStyle: CSSProperties = {
+  color: "var(--color-neutral-900)",
+  fontSize: "var(--font-size-base)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+  transition: "color 150ms ease",
+};
+
+const descriptionStyle: CSSProperties = {
+  margin: 0,
+  color: "var(--color-neutral-600)",
+  fontSize: "var(--font-size-sm)",
+  lineHeight: 1.5,
+};
+
+const emptyDescriptionStyle: CSSProperties = { ...descriptionStyle, visibility: "hidden" };
+
+const statStyle: CSSProperties = {
+  color: "var(--color-neutral-900)",
+  fontSize: "var(--font-size-sm)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+};
+const emptyStatStyle: CSSProperties = { ...statStyle, visibility: "hidden" };
+
+const linkStyle: CSSProperties = {
+  textDecoration: "none",
+  color: "inherit",
+  display: "block",
+  height: "100%",
+  minHeight: 0,
+};
+
+const defaultRenderLink: RenderHubCardLink = ({ to, children }) => (
+  <a href={to} data-terp="hubcard-link" style={linkStyle}>
+    {children}
+  </a>
+);
+
+/**
+ * A single navigable card inside a {@link HubPage}: icon + title, a short description of
+ * the area, and an optional live `stat`. The whole card is one link, rendered through
+ * `renderLink` so the hub stays router-agnostic.
+ */
+export function HubCard({
+  to,
+  title,
+  description,
+  icon,
+  stat,
+  renderLink = defaultRenderLink,
+}: HubCardProps) {
+  const resolve = useUiText();
+  return (
+    <li data-terp="hubcard" style={cardStyle}>
+      {renderLink({
+        to,
+        children: (
+          <span data-terp="hubcard-body" style={cardBodyStyle}>
+            <span style={cardTitleRowStyle}>
+              {icon !== undefined && <span style={iconTileStyle}>{icon}</span>}
+              <strong data-terp="hubcard-title" style={titleTextStyle}>
+                {resolve(title)}
+              </strong>
+            </span>
+            <span data-terp="hubcard-description" style={description === undefined ? emptyDescriptionStyle : descriptionStyle}>
+              {description === undefined ? " " : resolve(description)}
+            </span>
+            <span data-terp="hubcard-stat" style={stat === undefined ? emptyStatStyle : statStyle}>
+              {stat ?? " "}
+            </span>
+          </span>
+        ),
+      })}
+    </li>
+  );
+}
+

package/src/LoadingState.test.tsx

@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { InlineSpinner, LoadingState } from "./LoadingState";
+import { UiTextProvider } from "./uiText";
+
+afterEach(cleanup);
+
+describe("LoadingState", () => {
+  it("is a status region with the default loading label", () => {
+    render(<LoadingState />);
+
+    expect(screen.getByRole("status")).toHaveTextContent("Loading...");
+  });
+
+  it("resolves an explicit UiText label and honours string overrides", () => {
+    render(
+      <UiTextProvider strings={{ loading: "Laden…" }}>
+        <LoadingState />
+        <LoadingState label={{ id: "tasks.loading", message: "Loading tasks…" }} />
+      </UiTextProvider>,
+    );
+
+    const statuses = screen.getAllByRole("status");
+    expect(statuses[0]).toHaveTextContent("Laden…");
+    expect(statuses[1]).toHaveTextContent("Loading tasks…");
+  });
+});
+
+describe("InlineSpinner", () => {
+  it("renders a decorative svg hidden from assistive tech", () => {
+    const { container } = render(<InlineSpinner size={24} />);
+
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+    expect(svg).toHaveAttribute("width", "24");
+  });
+});

package/src/LoadingState.tsx

@@ -0,0 +1,96 @@
+import type { CSSProperties } from "react";
+
+import { injectTerpStyles } from "./styles";
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+injectTerpStyles();
+
+export interface InlineSpinnerProps {
+  /** Diameter in pixels; default 16. Inherits `currentColor`. */
+  size?: number;
+}
+
+/**
+ * Compact inline loading spinner for table cells, buttons, and tight layouts —
+ * just the spinning glyph, no label (it is hidden from assistive tech). Use
+ * {@link LoadingState} for a full loading block that announces itself.
+ * Rendered as an SVG so react-core takes no icon dependency; the rotation uses
+ * a CSS animation (respects `prefers-reduced-motion`).
+ */
+export function InlineSpinner({ size = 16 }: InlineSpinnerProps) {
+  return (
+    <span
+      aria-hidden="true"
+      data-terp="spinner-ring"
+      style={{
+        display: "inline-block",
+        verticalAlign: "middle",
+        width: size,
+        height: size,
+        lineHeight: 0,
+      }}
+    >
+      <svg
+        aria-hidden="true"
+        width={size}
+        height={size}
+        viewBox="0 0 24 24"
+        fill="none"
+        style={{ display: "block" }}
+      >
+        <circle
+          cx="12"
+          cy="12"
+          r="10"
+          stroke="currentColor"
+          strokeOpacity="0.2"
+          strokeWidth="3"
+        />
+        <path
+          d="M12 2a10 10 0 0 1 10 10"
+          stroke="currentColor"
+          strokeWidth="3"
+          strokeLinecap="round"
+        />
+      </svg>
+    </span>
+  );
+}
+
+export interface LoadingStateProps {
+  /** Short description of what is loading; defaults to the `loading` string. */
+  label?: UiText;
+}
+
+const wrapStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: "var(--space-2)",
+  padding: "var(--space-6)",
+  color: "var(--color-neutral-500)",
+  fontSize: "var(--font-size-sm)",
+};
+
+const spinnerColorStyle: CSSProperties = { color: "var(--color-brand-primary)" };
+
+/**
+ * Standard inline loading indicator: a spinner plus a short label, announced
+ * as a `status` live region. Use it when a query is pending and the page shell
+ * is already rendered; pairs with `Page`'s loading slot. Use {@link InlineSpinner}
+ * when only the glyph fits.
+ */
+export function LoadingState({ label }: LoadingStateProps) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  return (
+    <div role="status" data-terp="loading-state" style={wrapStyle}>
+      <span style={spinnerColorStyle}>
+        <InlineSpinner size={20} />
+      </span>
+      <span>{resolve(label ?? strings.loading)}</span>
+    </div>
+  );
+}
+

package/src/LoginView.test.tsx

@@ -0,0 +1,57 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { LoginView } from "./LoginView";
+import { TerpProvider } from "./TerpProvider";
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function stubFetch() {
+  // The provider probes /auth/refresh on mount; a 401 keeps the session signed out.
+  vi.stubGlobal(
+    "fetch",
+    vi.fn<typeof fetch>(async () => json({}, 401)),
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("LoginView dev credentials", () => {
+  it("offers no fill button unless devCredentials is passed", async () => {
+    stubFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LoginView />
+      </TerpProvider>,
+    );
+    await screen.findByRole("heading", { name: "Sign in" });
+    expect(screen.queryByRole("button", { name: "Fill dev credentials" })).toBeNull();
+  });
+
+  it("fills the form with the dev credentials on click", async () => {
+    stubFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LoginView
+          devCredentials={{
+            email: "admin@example.test",
+            password: "correct horse battery staple",
+          }}
+        />
+      </TerpProvider>,
+    );
+    fireEvent.click(await screen.findByRole("button", { name: "Fill dev credentials" }));
+    expect(screen.getByPlaceholderText("Email")).toHaveValue("admin@example.test");
+    expect(screen.getByPlaceholderText("Password")).toHaveValue("correct horse battery staple");
+  });
+});