@terpjs/react-core 0.1.0

package/src/sso.ts

@@ -0,0 +1,142 @@
+import type { TerpClient, TerpClientFor } from "@terpjs/contract";
+
+import { unwrap } from "./unwrap";
+
+/**
+ * The SSO seam over the OIDC capability's SPA-shaped endpoints (ADR 0058):
+ *
+ * - `GET  /api/v1/oidc/{provider}/authorize` opens a flow and returns the IdP
+ *   authorize URL the client navigates to; and
+ * - `POST /api/v1/oidc/{provider}/callback` relays what the IdP appended to the
+ *   redirect URI and mints a normal Terp session (`access_token` + the same
+ *   httpOnly refresh cookie a password login sets).
+ *
+ * The endpoints are app-mounted (the OIDC capability is opt-in), so they are not
+ * part of the baked base-profile contract; the wire shapes below mirror the
+ * capability's DTOs, which the shipped capability keeps stable.
+ */
+
+/** Response of `GET /oidc/{provider}/authorize` — the URL to navigate to. */
+interface AuthorizationRequest {
+  provider: string;
+  authorization_url: string;
+}
+
+/** Response of `POST /oidc/{provider}/callback` — a normal Terp access token. */
+interface SsoAccessToken {
+  access_token: string;
+  token_type: string;
+}
+
+/** The OIDC capability's SPA endpoints, typed for the shared contract client. */
+interface OidcPaths {
+  "/api/v1/oidc/{provider}/authorize": {
+    get: {
+      parameters: { path: { provider: string }; query?: never; header?: never; cookie?: never };
+      requestBody?: never;
+      responses: {
+        200: {
+          headers: { [name: string]: unknown };
+          content: { "application/json": AuthorizationRequest };
+        };
+      };
+    };
+  };
+  "/api/v1/oidc/{provider}/callback": {
+    post: {
+      parameters: { path: { provider: string }; query?: never; header?: never; cookie?: never };
+      requestBody: { content: { "application/json": { code: string; state: string } } };
+      responses: {
+        200: {
+          headers: { [name: string]: unknown };
+          content: { "application/json": SsoAccessToken };
+        };
+      };
+    };
+  };
+}
+
+/** A configured SSO provider, as the login screen presents it. */
+export interface SsoProvider {
+  /** Provider name as mounted on the backend (the `{provider}` path segment). */
+  name: string;
+  /** Display label for the provider button (defaults to the name). */
+  label?: string;
+}
+
+/** Default SPA path prefix the IdP redirects back to: `/auth/callback/{provider}`. */
+export const DEFAULT_SSO_CALLBACK_PATH = "/auth/callback";
+
+function oidcClient(client: TerpClient): TerpClientFor<OidcPaths> {
+  return client as unknown as TerpClientFor<OidcPaths>;
+}
+
+/** Open an SSO flow: fetch the IdP authorize URL for `provider`. */
+export async function fetchSsoAuthorizationUrl(
+  client: TerpClient,
+  provider: string,
+): Promise<string> {
+  const data = unwrap(
+    await oidcClient(client).GET("/api/v1/oidc/{provider}/authorize", {
+      params: { path: { provider } },
+    }),
+  );
+  return data.authorization_url;
+}
+
+/** Finish an SSO flow: relay the IdP's `code`/`state` and receive a Terp access token. */
+export async function completeSsoCallback(
+  client: TerpClient,
+  provider: string,
+  payload: { code: string; state: string },
+): Promise<string> {
+  const data = unwrap(
+    await oidcClient(client).POST("/api/v1/oidc/{provider}/callback", {
+      params: { path: { provider } },
+      body: { code: payload.code, state: payload.state },
+    }),
+  );
+  return data.access_token;
+}
+
+/** What the IdP appended to the redirect URI, parsed from the current location. */
+export interface SsoCallbackParams {
+  provider: string;
+  code: string;
+  state: string;
+}
+
+/** True when `pathname` sits under the SSO callback prefix (an IdP redirect landed here). */
+export function isSsoCallbackLocation(
+  location: { pathname: string },
+  callbackPath: string = DEFAULT_SSO_CALLBACK_PATH,
+): boolean {
+  const prefix = callbackPath.endsWith("/") ? callbackPath : `${callbackPath}/`;
+  return location.pathname.startsWith(prefix);
+}
+
+/**
+ * Parse an in-flight SSO redirect out of a location. Returns the provider + code/state
+ * when `pathname` is `{callbackPath}/{provider}` and both query params are present,
+ * else null (a normal boot, or an IdP error redirect carrying no code).
+ */
+export function parseSsoCallback(
+  location: { pathname: string; search: string },
+  callbackPath: string = DEFAULT_SSO_CALLBACK_PATH,
+): SsoCallbackParams | null {
+  const prefix = callbackPath.endsWith("/") ? callbackPath : `${callbackPath}/`;
+  if (!location.pathname.startsWith(prefix)) {
+    return null;
+  }
+  const provider = decodeURIComponent(location.pathname.slice(prefix.length).replace(/\/+$/, ""));
+  if (provider.length === 0 || provider.includes("/")) {
+    return null;
+  }
+  const query = new URLSearchParams(location.search);
+  const code = query.get("code");
+  const state = query.get("state");
+  if (!code || !state) {
+    return null;
+  }
+  return { provider, code, state };
+}

package/src/ssr.test.tsx

@@ -0,0 +1,45 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { AppShell } from "./AppShell";
+import { DataView } from "./dataview/DataView";
+import type { DataViewRepository } from "./dataview/types";
+
+interface Row {
+  id: string;
+  name: string;
+}
+
+const repository: DataViewRepository<Row> = {
+  query: async () => ({ rows: [], totalCount: 0 }),
+  getRowId: (row) => row.id,
+  capabilities: { serverSide: false, search: false, searchScope: false },
+};
+
+describe("server rendering", () => {
+  it("renders responsive shell and DataView defaults without browser globals", () => {
+    expect(typeof window).toBe("undefined");
+
+    const shell = renderToString(
+      <AppShell
+        title="Terp"
+        nav={[{ label: "Home", to: "/", icon: "home" }]}
+        renderLink={(item, children, context) => (
+          <a href={item.to} style={context.style}>{children}</a>
+        )}
+      >
+        <p>content</p>
+      </AppShell>,
+    );
+    const view = renderToString(
+      <DataView
+        repository={repository}
+        columns={[{ id: "name", header: "Name", accessor: (row) => row.name }]}
+      />,
+    );
+
+    expect(shell).toContain("content");
+    expect(shell).toContain("Home");
+    expect(view).toContain('data-terp="dataview"');
+  });
+});

package/src/styles.test.ts

@@ -0,0 +1,21 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+
+import { TERP_STYLES_ID, injectTerpStyles } from "./styles";
+
+afterEach(() => {
+  document.querySelectorAll(`style#${TERP_STYLES_ID}`).forEach((node) => node.remove());
+});
+
+describe("injectTerpStyles", () => {
+  it("appends the stylesheet once and is idempotent on re-invocation", () => {
+    injectTerpStyles();
+    injectTerpStyles();
+    injectTerpStyles();
+    const nodes = document.querySelectorAll(`style#${TERP_STYLES_ID}`);
+    expect(nodes.length).toBe(1);
+    expect(nodes[0]?.textContent ?? "").toContain("data-terp");
+    expect(nodes[0]?.textContent ?? "").toContain('[data-terp="input"][type="number"]');
+    expect(nodes[0]?.textContent ?? "").toContain("::-webkit-inner-spin-button");
+  });
+});

package/src/styles.ts

@@ -0,0 +1,302 @@
+/**
+ * The one interaction-state stylesheet for react-core.
+ *
+ * Components keep their inline token styles as the visible base (so tests can
+ * still assert `element.style.background` etc.); this sheet layers hover,
+ * active, focus-visible and small animation polish on top, keyed by
+ * `data-terp` / `data-variant` attributes the components already set. That
+ * keeps the boundary lint's inline-style rule intact (react-core itself is
+ * allowed to inject a stylesheet — the rule targets *app modules*), while
+ * giving every button, link, tab, row and menu real interaction states.
+ *
+ * Because the base styles are inline (`style={}` wins the cascade over author
+ * stylesheets, even for `:hover` / `:focus` / `:disabled` rules), every
+ * interaction-state declaration that overrides an inline base property is
+ * marked `!important`. The rules are state-scoped (hover / focus / disabled
+ * only), so the escalation cannot leak into resting styles.
+ *
+ * The injector is idempotent, SSR-safe (guarded on `document`), and appends
+ * the rules through `textContent` — never `innerHTML` — so no HTML sink is
+ * touched.
+ */
+
+/** The `<style>` element id used to detect a prior injection. */
+export const TERP_STYLES_ID = "terp-core-styles";
+
+/** The interaction-state rules layered over the component's inline base styles. */
+export const TERP_STYLES_CSS = `
+/* Document reset: the app shell owns the full canvas. Without this the
+   browser's default 8px body margin leaves the document's own (white)
+   canvas visible as a ring around the shell — most obvious in Studio's
+   preview iframe and in dark mode. The body carries the same canvas token
+   as the shell so overscroll never flashes white. */
+html, body {
+  margin: 0;
+}
+body {
+  background: var(--color-neutral-50);
+}
+/* Border-box baseline: react-core sizes components as padding-inclusive
+   (e.g. LoginView's 100vh page with padding, inputs at width:100% with
+   padding) and app modules cannot ship a stylesheet of their own, so the
+   framework owns this. Under the browser default (content-box) a
+   min-height:100vh + padding screen overflows the viewport by exactly its
+   padding — phantom scrollbars on pages that fit. */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+/* Shared focus-visible ring: every interactive element that opts in via
+   [data-terp] shows a soft outline ring. !important lets the ring beat
+   inline base box-shadows (e.g. the primary button's resting shadow) so
+   keyboard focus is always visible. */
+[data-terp]:focus-visible {
+  outline: 2px solid transparent;
+  outline-offset: 1px;
+  box-shadow: 0 0 0 3px var(--color-focus-ring) !important;
+}
+
+/* Buttons ------------------------------------------------------------------ */
+[data-terp="button"] {
+  transition: background-color 150ms ease, color 150ms ease,
+    border-color 150ms ease, box-shadow 150ms ease, transform 100ms ease;
+}
+[data-terp="button"][data-variant="primary"]:hover:not(:disabled) {
+  background: var(--color-brand-primary-hover) !important;
+}
+[data-terp="button"][data-variant="secondary"]:hover:not(:disabled) {
+  background: var(--color-neutral-100) !important;
+  border-color: var(--color-neutral-300) !important;
+}
+[data-terp="button"][data-variant="ghost"]:hover:not(:disabled) {
+  background: var(--color-neutral-100) !important;
+  color: var(--color-neutral-900) !important;
+}
+[data-terp="button"][data-variant="danger"]:hover:not(:disabled) {
+  filter: brightness(0.94);
+}
+[data-terp="button"]:active:not(:disabled) {
+  transform: translateY(1px);
+}
+[data-terp="button"]:disabled {
+  opacity: 0.55;
+  cursor: not-allowed !important;
+}
+
+/* Icon-only buttons (header toggle, dismissers, pagination). */
+[data-terp="iconbutton"] {
+  transition: background-color 150ms ease, color 150ms ease, box-shadow 150ms ease;
+}
+[data-terp="iconbutton"]:hover:not(:disabled) {
+  background: var(--color-neutral-100) !important;
+  color: var(--color-neutral-900) !important;
+}
+[data-terp="iconbutton"]:disabled {
+  opacity: 0.4;
+  cursor: not-allowed !important;
+}
+
+/* Inputs / selects / textareas -------------------------------------------- */
+[data-terp="input"] {
+  transition: border-color 150ms ease, box-shadow 150ms ease;
+}
+[data-terp="input"]:hover:not(:disabled):not(:focus) {
+  border-color: var(--color-neutral-400, var(--color-neutral-500)) !important;
+}
+[data-terp="input"]:focus,
+[data-terp="input"]:focus-visible {
+  outline: none;
+  border-color: var(--color-brand-primary) !important;
+  box-shadow: 0 0 0 3px var(--color-focus-ring) !important;
+}
+[data-terp="input"]::placeholder {
+  color: var(--color-neutral-500);
+  opacity: 1;
+}
+[data-terp="input"] option {
+  color: var(--color-neutral-900);
+  background: var(--color-neutral-0);
+}
+[data-terp="input"]:disabled {
+  /* background-color (not the background shorthand) so the Select's chevron,
+     drawn as a background-image, survives the disabled state. */
+  background-color: var(--color-neutral-50) !important;
+  color: var(--color-neutral-500) !important;
+  cursor: not-allowed !important;
+}
+[data-terp="input"][aria-invalid="true"] {
+  border-color: var(--color-status-danger) !important;
+}
+/* Number steppers are browser chrome and cannot be token-themed consistently.
+   Keep keyboard/wheel/manual numeric input while removing the mismatched arrows. */
+[data-terp="input"][type="number"] {
+  appearance: textfield;
+  -moz-appearance: textfield;
+}
+[data-terp="input"][type="number"]::-webkit-inner-spin-button,
+[data-terp="input"][type="number"]::-webkit-outer-spin-button {
+  appearance: none;
+  -webkit-appearance: none;
+  margin: 0;
+}
+
+/* Checkboxes / radios / switches ------------------------------------------- */
+[data-terp="checkbox"]:disabled,
+[data-terp="radio"]:disabled,
+[data-terp="switch"]:disabled {
+  cursor: not-allowed !important;
+}
+label:has([data-terp="checkbox"]:disabled),
+label:has([data-terp="radio"]:disabled),
+label:has([data-terp="switch"]:disabled) {
+  cursor: not-allowed !important;
+  color: var(--color-neutral-500) !important;
+}
+
+/* Sidebar navigation links (from the shell or any app-provided <a>). The hover
+   rule skips the active route's link (aria-current="page") so the brand-soft
+   active highlight is not washed out on hover. */
+[data-terp="appshell-nav"] a {
+  transition: background-color 150ms ease, color 150ms ease;
+}
+[data-terp="appshell-nav"] a:hover:not([aria-current="page"]) {
+  background: var(--color-neutral-100) !important;
+  color: var(--color-neutral-900) !important;
+}
+[data-terp="appshell-nav"][data-collapsed="true"] {
+  overflow-x: hidden;
+  scrollbar-width: none;
+}
+[data-terp="appshell-nav"][data-collapsed="true"]::-webkit-scrollbar {
+  width: 0;
+  height: 0;
+}
+[data-terp="appshell-brand"] {
+  transition: background-color 150ms ease;
+}
+[data-terp="appshell-brand"]:hover {
+  background: var(--color-neutral-100) !important;
+}
+
+/* Tabs -------------------------------------------------------------------- */
+[data-terp="tab"] {
+  transition: background-color 150ms ease, color 150ms ease, border-color 150ms ease;
+  border-top-left-radius: var(--radius-sm);
+  border-top-right-radius: var(--radius-sm);
+}
+[data-terp="tab"]:hover:not(:disabled):not([aria-selected="true"]) {
+  color: var(--color-neutral-900) !important;
+  background: var(--color-neutral-100) !important;
+}
+[data-terp="tab"]:disabled {
+  opacity: 0.5;
+  cursor: not-allowed !important;
+}
+
+/* Hub cards --------------------------------------------------------------- */
+[data-terp="hubcard-link"],
+[data-terp="hubcard"] a {
+  text-decoration: none;
+  color: inherit;
+  display: block;
+  height: 100%;
+  min-height: 0;
+}
+[data-terp="hubcard"] {
+  transition: border-color 150ms ease, box-shadow 150ms ease, transform 150ms ease;
+}
+[data-terp="hubcard"]:hover {
+  border-color: var(--color-brand-primary) !important;
+  box-shadow: var(--shadow-sm);
+  transform: translateY(-1px);
+}
+[data-terp="hubcard"]:hover [data-terp="hubcard-title"] {
+  color: var(--color-brand-primary) !important;
+}
+
+/* Breadcrumb links -------------------------------------------------------- */
+[data-terp="breadcrumbs"] a {
+  color: var(--color-neutral-600);
+  text-decoration: none;
+  transition: color 150ms ease;
+}
+[data-terp="breadcrumbs"] a:hover {
+  color: var(--color-neutral-900);
+  text-decoration: underline;
+}
+
+/* DataView table row hover ------------------------------------------------- */
+[data-terp="dataview-table"] tbody tr {
+  transition: background-color 150ms ease;
+}
+[data-terp="dataview-table"] tbody tr:hover td {
+  background: var(--color-neutral-50);
+}
+[data-terp="dataview-row"]:focus-within td,
+[data-terp="dataview-card"]:focus-within {
+  background: var(--color-brand-primary-soft) !important;
+}
+
+/* Menu items (UserMenu, DataView row-actions / column settings). */
+[data-terp="menu-item"] {
+  transition: background-color 150ms ease, color 150ms ease;
+  border-radius: var(--radius-sm);
+}
+[data-terp="menu-item"]:hover:not(:disabled) {
+  background: var(--color-neutral-100) !important;
+  color: var(--color-neutral-900) !important;
+}
+[data-terp="menu-item"][data-selected="true"] {
+  background: var(--color-brand-primary-soft) !important;
+  color: var(--color-brand-primary) !important;
+}
+
+/* Dialogs: ::backdrop cannot be set inline, so the dim layer lives here and
+   matches the mobile drawer backdrop for one consistent overlay darkness. */
+[data-terp="dialog"]::backdrop {
+  background: rgb(0 0 0 / 0.4);
+}
+
+/* Spinner keyframes for the LoadingState ring. */
+@keyframes terp-spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+[data-terp="spinner-ring"] {
+  animation: terp-spin 0.8s linear infinite;
+}
+
+/* Respect the user's reduced-motion preference — kill transitions and the
+   spinner animation everywhere the sheet applies them. */
+@media (prefers-reduced-motion: reduce) {
+  [data-terp],
+  [data-terp="appshell-nav"] a,
+  [data-terp="dataview-table"] tbody tr {
+    transition: none !important;
+  }
+  [data-terp="spinner-ring"] { animation: none !important; }
+}
+`;
+
+/**
+ * Inject the react-core interaction-state stylesheet once per document.
+ *
+ * SSR-safe: no-op when `document` is undefined. Idempotent: the sheet element
+ * is keyed by {@link TERP_STYLES_ID}, so repeated calls (from any component's
+ * module scope) attach the rules exactly once. Content is set via
+ * `textContent` — never `innerHTML` — so no HTML-injection sink is touched.
+ */
+export function injectTerpStyles(): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+  if (document.getElementById(TERP_STYLES_ID) !== null) {
+    return;
+  }
+  const el = document.createElement("style");
+  el.id = TERP_STYLES_ID;
+  el.textContent = TERP_STYLES_CSS;
+  document.head.appendChild(el);
+}

package/src/theme.test.tsx

@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { THEME_STORAGE_KEY, ThemeProvider, ThemeToggle } from "./theme";
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+  document.documentElement.removeAttribute("data-theme");
+});
+
+describe("ThemeProvider + ThemeToggle", () => {
+  it("defaults to the system theme (no data-theme attribute)", () => {
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.hasAttribute("data-theme")).toBe(false);
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    expect(screen.getByRole("menuitemradio", { name: "System" })).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("applies an explicit choice to <html data-theme> and persists it", () => {
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    fireEvent.click(screen.getByRole("menuitemradio", { name: "Dark" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+    expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("dark");
+  });
+
+  it("restores a persisted choice over the app default", () => {
+    window.localStorage.setItem(THEME_STORAGE_KEY, "light");
+    render(
+      <ThemeProvider defaultTheme="dark">
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.getAttribute("data-theme")).toBe("light");
+  });
+
+  it("switching back to system removes the attribute (OS preference wins)", () => {
+    render(
+      <ThemeProvider defaultTheme="dark">
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    fireEvent.click(screen.getByRole("menuitemradio", { name: "System" }));
+    expect(document.documentElement.hasAttribute("data-theme")).toBe(false);
+  });
+
+  it("ThemeToggle renders nothing outside a ThemeProvider", () => {
+    render(<ThemeToggle />);
+    expect(screen.queryByLabelText("Theme")).not.toBeInTheDocument();
+  });
+
+  it("ignores a corrupt persisted value", () => {
+    window.localStorage.setItem(THEME_STORAGE_KEY, "neon");
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    expect(screen.getByRole("menuitemradio", { name: "System" })).toHaveAttribute("aria-checked", "true");
+  });
+});