@terpjs/react-core 0.1.0

package/src/Breadcrumbs.tsx

@@ -0,0 +1,110 @@
+import type { CSSProperties, ReactNode } from "react";
+
+import { injectTerpStyles } from "./styles";
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+injectTerpStyles();
+
+/** One breadcrumb: a label plus, for ancestor levels, the path it links back to. */
+export interface BreadcrumbItem {
+  /** The crumb text (e.g. the module title, or the record's display name). */
+  label: UiText;
+  /** Destination path for ancestor crumbs; the current page's crumb omits it. */
+  to?: string;
+}
+
+/** Turns an ancestor crumb into the active stack's link (keeps the trail router-agnostic). */
+export type RenderBreadcrumbLink = (item: { label: string; to: string }) => ReactNode;
+
+export interface BreadcrumbsProps {
+  /** The trail, outermost first; the last item is the current page. */
+  items: readonly BreadcrumbItem[];
+  /** Link renderer for ancestor crumbs (default: a plain `<a href>`); pass the stack's `Link`. */
+  renderLink?: RenderBreadcrumbLink;
+}
+
+const navStyle: CSSProperties = {
+  fontSize: "var(--font-size-sm)",
+  color: "var(--color-neutral-600)",
+};
+
+const listStyle: CSSProperties = {
+  listStyle: "none",
+  margin: 0,
+  padding: 0,
+  display: "flex",
+  flexWrap: "wrap",
+  alignItems: "center",
+  gap: "var(--space-2)",
+};
+
+const currentStyle: CSSProperties = {
+  color: "var(--color-neutral-900)",
+  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
+};
+
+const separatorStyle: CSSProperties = {
+  display: "inline-flex",
+  color: "var(--color-neutral-400)",
+  lineHeight: 0,
+};
+
+function ChevronSeparator() {
+  return (
+    <svg
+      aria-hidden="true"
+      focusable={false}
+      width="0.85em"
+      height="0.85em"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="m9 6 6 6-6 6" />
+    </svg>
+  );
+}
+
+const defaultRenderLink: RenderBreadcrumbLink = (item) => <a href={item.to}>{item.label}</a>;
+
+/**
+ * The breadcrumb trail every page shows through the remaining layers (shell -> overview ->
+ * detail). Accessible by construction: a `nav` landmark labelled "Breadcrumb", an ordered
+ * list, and `aria-current="page"` on the final crumb. Router-agnostic — `renderLink` turns
+ * an ancestor crumb into the active stack's link, exactly like `AppShell`'s `renderLink`.
+ */
+export function Breadcrumbs({ items, renderLink = defaultRenderLink }: BreadcrumbsProps) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  return (
+    <nav aria-label={strings.breadcrumbsLabel} data-terp="breadcrumbs" style={navStyle}>
+      <ol style={listStyle}>
+        {items.map((item, index) => {
+          const isLast = index === items.length - 1;
+          const label = resolve(item.label);
+          return (
+            <li key={`${index}-${label}`} style={listStyle}>
+              {!isLast && item.to !== undefined ? (
+                renderLink({ label, to: item.to })
+              ) : (
+                <span aria-current={isLast ? "page" : undefined} style={isLast ? currentStyle : undefined}>
+                  {label}
+                </span>
+              )}
+              {!isLast && (
+                <span aria-hidden="true" style={separatorStyle}>
+                  <ChevronSeparator />
+                </span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}
+

package/src/ConfirmDialog.tsx

@@ -0,0 +1,170 @@
+import { useEffect, useId, useRef } from "react";
+import type { CSSProperties, ReactNode } from "react";
+
+import { Button } from "./ui/Button";
+import { injectTerpStyles } from "./styles";
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+injectTerpStyles();
+
+export interface ConfirmDialogProps {
+  /** Whether the dialog is shown (controlled). */
+  open: boolean;
+  /** Called with `false` when the user dismisses (cancel, backdrop click, Escape). */
+  onOpenChange: (open: boolean) => void;
+  /** Called when the user confirms. The caller closes the dialog when the action settles. */
+  onConfirm: () => void;
+  /** Short question — what is about to happen. */
+  title: UiText;
+  /** Optional consequence explanation. */
+  description?: ReactNode;
+  /** Confirm-button label; defaults to the `confirm` string. */
+  confirmLabel?: UiText;
+  /** Cancel-button label; defaults to the `cancel` string. */
+  cancelLabel?: UiText;
+  /** Style the confirm button as destructive (delete / remove / deactivate). */
+  destructive?: boolean;
+  /** Keep the dialog inert while the confirmed action is in flight: disables both
+   * buttons and blocks Escape / backdrop dismissal until the action settles. */
+  isPending?: boolean;
+  /** Disable confirmation until required dialog input is valid. */
+  confirmDisabled?: boolean;
+}
+
+const dialogStyle: CSSProperties = {
+  width: "100%",
+  maxWidth: "26rem",
+  padding: 0,
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-lg)",
+  boxShadow: "var(--shadow-lg)",
+  background: "var(--color-neutral-0)",
+  color: "var(--color-neutral-900)",
+};
+
+const bodyStyle: CSSProperties = {
+  display: "grid",
+  gap: "var(--space-3)",
+  padding: "var(--space-6)",
+};
+
+const dialogTitleStyle: CSSProperties = {
+  margin: 0,
+  fontSize: "var(--font-size-lg)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+  letterSpacing: 0,
+  color: "var(--color-neutral-900)",
+};
+
+const descriptionStyle: CSSProperties = {
+  color: "var(--color-neutral-600)",
+  fontSize: "var(--font-size-sm)",
+  lineHeight: 1.5,
+};
+
+const footerStyle: CSSProperties = {
+  display: "flex",
+  justifyContent: "flex-end",
+  gap: "var(--space-2)",
+  marginTop: "var(--space-2)",
+};
+
+/**
+ * The shared confirmation dialog — replaces `window.confirm()` with an accessible,
+ * token-styled modal. Use it before any destructive or irreversible action (delete,
+ * remove, deactivate), with `destructive` marking the confirm button.
+ *
+ * Built on the native `<dialog>` element via `showModal()`, so the platform provides
+ * the modal contract for free: initial focus, focus trapping, focus restore to the
+ * opener, Escape handling, and top-layer rendering (never clipped by ancestor
+ * overflow/transform, always above toasts). Dismissal is possible via the cancel
+ * button, backdrop click, or Escape — except while `isPending`, which keeps the
+ * dialog inert until the confirmed action settles. The element stays mounted while
+ * closed (hidden by the UA `dialog:not([open])` rule) so closing goes through
+ * `close()` — the step that restores focus to the opener.
+ */
+export function ConfirmDialog({
+  open,
+  onOpenChange,
+  onConfirm,
+  title,
+  description,
+  confirmLabel,
+  cancelLabel,
+  destructive,
+  isPending,
+  confirmDisabled,
+}: ConfirmDialogProps) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  const titleId = useId();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog === null) {
+      return;
+    }
+    if (open && !dialog.open) {
+      dialog.showModal();
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    // The top layer blocks interaction with the page but not scrolling behind it.
+    const previous = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = previous;
+    };
+  }, [open]);
+
+  return (
+    <dialog
+      ref={dialogRef}
+      data-terp="dialog"
+      aria-labelledby={titleId}
+      style={dialogStyle}
+      onCancel={(event) => {
+        // Escape: stay controlled — never let the platform close the element itself.
+        event.preventDefault();
+        if (isPending !== true) {
+          onOpenChange(false);
+        }
+      }}
+      onClick={(event) => {
+        // A click on the backdrop targets the <dialog> element itself.
+        if (event.target === dialogRef.current && isPending !== true) {
+          onOpenChange(false);
+        }
+      }}
+    >
+      <div style={bodyStyle}>
+        <h2 id={titleId} style={dialogTitleStyle}>
+          {resolve(title)}
+        </h2>
+        {description !== undefined && (
+          <div style={descriptionStyle}>{description}</div>
+        )}
+        <div style={footerStyle}>
+          <Button variant="secondary" disabled={isPending} onClick={() => onOpenChange(false)}>
+            {resolve(cancelLabel ?? strings.cancel)}
+          </Button>
+          <Button
+            variant={destructive ? "danger" : "primary"}
+            disabled={isPending || confirmDisabled}
+            onClick={onConfirm}
+          >
+            {resolve(confirmLabel ?? strings.confirm)}
+          </Button>
+        </div>
+      </div>
+    </dialog>
+  );
+}

package/src/DetailPage.tsx

@@ -0,0 +1,28 @@
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+import type { BreadcrumbItem } from "./Breadcrumbs";
+import { LayoutSlotContext } from "./layoutContract";
+
+export interface DetailPageProps extends Omit<PageProps, "breadcrumbs"> {
+  /**
+   * The overview (and any intermediate layers) this record lives under, outermost first.
+   * Every ancestor crumb must link back up, so `to` is required — a detail page is never
+   * orphaned from its overview.
+   */
+  parents: readonly (BreadcrumbItem & { to: string })[];
+}
+
+/**
+ * The detail (level-3) page archetype: one record's screen, reached from an overview. It is a
+ * `Page` whose breadcrumb trail is the ancestor layers plus the record itself (`title`), so
+ * users can always navigate back up — the shell -> overview -> detail layering by construction.
+ * With a layout contract active (ADR 0079), the body slot accepts only the contract's record
+ * components (e.g. `DetailList` / `Stack` / `Tabs`) — refused fail closed otherwise.
+ */
+export function DetailPage({ parents, ...page }: DetailPageProps) {
+  return (
+    <LayoutSlotContext.Provider value="DetailPage">
+      <Page breadcrumbs={parents} {...page} />
+    </LayoutSlotContext.Provider>
+  );
+}

package/src/EmptyState.tsx

@@ -0,0 +1,74 @@
+import type { CSSProperties, ReactNode } from "react";
+
+import { Icon } from "./icons";
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+export interface EmptyStateProps {
+  /**
+   * Optional leading visual (any rendered node — react-core takes no icon dependency).
+   * Defaults to a muted inbox glyph so the block always has a recognisable frame.
+   */
+  icon?: ReactNode;
+  /** Short title — what is missing. */
+  title: UiText;
+  /** Optional explanation — why it's missing, or what to do next. */
+  description?: ReactNode;
+  /** Optional call to action (typically a `Button`). */
+  action?: ReactNode;
+}
+
+const wrapStyle: CSSProperties = {
+  display: "grid",
+  justifyItems: "center",
+  gap: "var(--space-3)",
+  padding: "var(--space-8) var(--space-6)",
+  textAlign: "center",
+  color: "var(--color-neutral-600)",
+  border: "1px dashed var(--color-neutral-300)",
+  borderRadius: "var(--radius-lg)",
+  background: "var(--color-neutral-0)",
+};
+
+const iconStyle: CSSProperties = {
+  color: "var(--color-neutral-400)",
+  display: "inline-flex",
+};
+
+const titleStyle: CSSProperties = {
+  margin: 0,
+  color: "var(--color-neutral-900)",
+  fontSize: "var(--font-size-base)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+};
+
+const descriptionStyle: CSSProperties = {
+  color: "var(--color-neutral-600)",
+  fontSize: "var(--font-size-sm)",
+  lineHeight: 1.5,
+  maxWidth: "36ch",
+};
+
+/**
+ * The standard "nothing here yet" block: use whenever a query legitimately returns zero
+ * rows, a module is not wired to data yet, or a feature is gated. One recognisable empty
+ * UX platform-wide tells the user "this is not an error — there is just nothing to show",
+ * and the `action` slot turns the dead end into the obvious next step.
+ */
+export function EmptyState({ icon, title, description, action }: EmptyStateProps) {
+  const resolve = useUiText();
+  const leading = icon ?? (
+    <span style={iconStyle}>
+      <Icon name="inbox" size="2rem" />
+    </span>
+  );
+  return (
+    <div data-terp="empty-state" style={wrapStyle}>
+      {leading}
+      <p style={titleStyle}>{resolve(title)}</p>
+      {description !== undefined && <div style={descriptionStyle}>{description}</div>}
+      {action}
+    </div>
+  );
+}
+

package/src/ErrorState.tsx

@@ -0,0 +1,108 @@
+import type { CSSProperties, ReactNode } from "react";
+
+import { useErrorMessage } from "./errorMessages";
+import { Icon } from "./icons";
+import { useStrings, useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+/**
+ * Best-effort human-readable message for a caught failure. `unwrap` already throws
+ * `Error`s carrying the backend envelope's `detail`, so most callers just surface
+ * `error.message`; raw envelope objects (`detail` / `code`) and plain strings are
+ * also understood. Returns `null` when nothing useful can be derived.
+ */
+export function describeError(error: unknown): string | null {
+  if (typeof error === "string" && error.length > 0) {
+    return error;
+  }
+  if (error instanceof Error && error.message.length > 0) {
+    return error.message;
+  }
+  if (error !== null && typeof error === "object") {
+    const envelope = error as { detail?: unknown; code?: unknown };
+    if (typeof envelope.detail === "string" && envelope.detail.length > 0) {
+      return envelope.detail;
+    }
+    if (typeof envelope.code === "string" && envelope.code.length > 0) {
+      return envelope.code;
+    }
+  }
+  return null;
+}
+
+export interface ErrorStateProps {
+  /** Optional leading visual (any rendered node — react-core takes no icon dependency). */
+  icon?: ReactNode;
+  /** Short title — what failed. Defaults to the `errorTitle` string. */
+  title?: UiText;
+  /**
+   * Explanation. When omitted and `error` is set, the message is the registered
+   * copy for the error's stable `code` (see `useErrorMessage`), falling back to
+   * {@link describeError}, so the platform error envelope surfaces consistently.
+   */
+  description?: ReactNode;
+  /** The caught failure — used to derive `description` when none is given. */
+  error?: unknown;
+  /** Optional call to action (typically a retry `Button`). */
+  action?: ReactNode;
+}
+
+const wrapStyle: CSSProperties = {
+  display: "grid",
+  justifyItems: "center",
+  gap: "var(--space-3)",
+  padding: "var(--space-6)",
+  textAlign: "center",
+  color: "var(--color-neutral-700)",
+  background: "var(--color-status-danger-soft)",
+  border: "1px solid var(--color-status-danger)",
+  borderRadius: "var(--radius-lg)",
+};
+
+const titleStyle: CSSProperties = {
+  margin: 0,
+  color: "var(--color-status-danger)",
+  fontSize: "var(--font-size-base)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+};
+
+const iconStyle: CSSProperties = {
+  color: "var(--color-status-danger)",
+  display: "inline-flex",
+};
+
+const descriptionStyle: CSSProperties = {
+  color: "var(--color-neutral-700)",
+  fontSize: "var(--font-size-sm)",
+  lineHeight: 1.5,
+  maxWidth: "48ch",
+};
+
+/**
+ * The standard "something went wrong" block: use whenever a query fails (404 / 403 /
+ * network) and the page frame is already rendered. Announced as an `alert` so assistive
+ * tech hears the failure; the message comes from the platform error envelope by default,
+ * so failures read the same platform-wide. Pairs with `Page`'s `errorState` slot.
+ */
+export function ErrorState({ icon, title, description, error, action }: ErrorStateProps) {
+  const strings = useStrings();
+  const resolve = useUiText();
+  const messageForCode = useErrorMessage();
+  const message =
+    description ??
+    (error !== undefined ? (messageForCode(error) ?? describeError(error)) : null);
+  const leading =
+    icon ?? (
+      <span style={iconStyle}>
+        <Icon name="x" size="1.75rem" />
+      </span>
+    );
+  return (
+    <div role="alert" data-terp="error-state" style={wrapStyle}>
+      {leading}
+      <p style={titleStyle}>{resolve(title ?? strings.errorTitle)}</p>
+      {message !== null && message !== undefined && <div style={descriptionStyle}>{message}</div>}
+      {action}
+    </div>
+  );
+}

package/src/Field.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Field } from "./Field";
+import { Input } from "./ui/Input";
+import { Select } from "./ui/Select";
+import { Textarea } from "./ui/Textarea";
+
+afterEach(cleanup);
+
+describe("Field", () => {
+  it("labels its control (accessible association) and shows hint + error", () => {
+    render(
+      <Field label="Email" hint="we never share it" error="required">
+        <Input defaultValue="" />
+      </Field>,
+    );
+    // The control is reachable by its label text (implicit association via the wrapping <label>).
+    expect(screen.getByLabelText("Email")).toBeInTheDocument();
+    expect(screen.getByText("we never share it")).toBeInTheDocument();
+    expect(screen.getByText("required")).toBeInTheDocument();
+  });
+
+  it("renders no error node when error is null", () => {
+    render(
+      <Field label="Name" error={null}>
+        <Input defaultValue="" />
+      </Field>,
+    );
+    expect(screen.getByLabelText("Name")).toBeInTheDocument();
+  });
+});
+
+describe("Select / Textarea primitives", () => {
+  it("render token-styled controls reachable by their Field label", () => {
+    render(
+      <>
+        <Field label="Status">
+          <Select defaultValue="open">
+            <option value="open">open</option>
+            <option value="done">done</option>
+          </Select>
+        </Field>
+        <Field label="Notes">
+          <Textarea defaultValue="" />
+        </Field>
+      </>,
+    );
+    expect(screen.getByLabelText("Status")).toBeInTheDocument();
+    expect(screen.getByLabelText("Notes")).toBeInTheDocument();
+  });
+});

package/src/Field.tsx

@@ -0,0 +1,51 @@
+import type { CSSProperties, ReactNode } from "react";
+
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+const fieldStyle: CSSProperties = { display: "grid", gap: "var(--space-1)" };
+const labelStyle: CSSProperties = {
+  fontWeight: "var(--font-weight-medium)" as never,
+  fontSize: "var(--font-size-sm)",
+  color: "var(--color-neutral-700)",
+};
+const hintStyle: CSSProperties = {
+  color: "var(--color-neutral-500)",
+  fontSize: "var(--font-size-xs)",
+};
+const errorStyle: CSSProperties = {
+  color: "var(--color-status-danger)",
+  fontSize: "var(--font-size-xs)",
+  fontWeight: "var(--font-weight-medium)" as never,
+};
+
+export interface FieldProps {
+  /** The field label (also the control's accessible name — the control is wrapped in the `<label>`). */
+  label: UiText;
+  /** The control: an `<Input>`, `<Select>`, or `<Textarea>`. */
+  children: ReactNode;
+  /** A field-level error (e.g. mapped from a 422), shown under the control. */
+  error?: string | null;
+  /** Optional helper text under the control. */
+  hint?: string;
+}
+
+/**
+ * A labelled form field: wraps a control in a `<label>` (so the label is its accessible name with no
+ * id wiring) and renders an optional hint + a field-level error. Compose it with the token-styled
+ * `Input` / `Select` / `Textarea` primitives to build a multi-field form — the centralized, accessible
+ * way every module authors inputs.
+ */
+export function Field({ label, children, error, hint }: FieldProps) {
+  const resolve = useUiText();
+  return (
+    <div style={fieldStyle}>
+      <label style={fieldStyle}>
+        <span style={labelStyle}>{resolve(label)}</span>
+        {children}
+      </label>
+      {hint !== undefined && <span style={hintStyle}>{hint}</span>}
+      {error !== undefined && error !== null && <span style={errorStyle}>{error}</span>}
+    </div>
+  );
+}