@terpjs/react-core 0.1.0

package/src/dataview/types.ts

@@ -0,0 +1,249 @@
+import type { ReactNode } from "react";
+
+import type { UiText } from "../uiText";
+
+/**
+ * Query descriptor the DataView emits — the only contract with the data layer.
+ * A {@link DataViewRepository} receives this and returns one {@link DataViewResult} page;
+ * the component never fetches or filters on its own.
+ */
+export interface DataViewQuery {
+  pagination: { pageIndex: number; pageSize: number };
+  sorting: { id: string; desc: boolean }[];
+  filters: { id: string; value: unknown }[];
+  search: string;
+  /** Broadened search scope active (e.g. include archived/closed records). */
+  searchBroadened: boolean;
+}
+
+/** Uniform page result every repository returns. */
+export interface DataViewResult<T> {
+  rows: T[];
+  totalCount: number;
+}
+
+/**
+ * The repository abstraction. DataView only ever talks to this — swapping in-memory ↔ HTTP
+ * data requires zero changes to any component file (dependency inversion / open-closed).
+ *
+ * @example
+ * ```ts
+ * const repo = new InMemoryDataViewRepository(tickets, {
+ *   getRowId: (t) => t.id,
+ *   searchFields: ["title", "assignee"],
+ * });
+ * <DataView repository={repo} columns={columns} />
+ * ```
+ */
+export interface DataViewRepository<T> {
+  query(q: DataViewQuery, signal?: AbortSignal): Promise<DataViewResult<T>>;
+  /** Stable row identity — selection/expansion must survive re-sorts and refetches. */
+  getRowId(row: T): string;
+  /** Capability flags let the component adapt (e.g. hide the search box). */
+  capabilities: {
+    /** true → manual sorting/filtering/pagination; the repo does the work per query. */
+    serverSide: boolean;
+    search: boolean;
+    /** Supports the "search everything" broadened toggle. */
+    searchScope: boolean;
+  };
+  /**
+   * Optional facet support: the distinct values of one column across the full data set
+   * (client-side repositories can provide it cheaply; server-side ones may omit it).
+   */
+  getFacetedValues?(columnId: string): unknown[];
+}
+
+/** Everything the user customises about a view, persisted per stable `viewId`. */
+export interface DataViewState {
+  columnVisibility: Record<string, boolean>;
+  columnOrder: string[];
+  /** User-resized widths in px. */
+  columnSizing: Record<string, number>;
+  /** Client-side views only. */
+  sorting: { id: string; desc: boolean }[];
+  /** Client-side views only. */
+  filters: { id: string; value: unknown }[];
+  search: string;
+}
+
+/**
+ * Where a user's view customisations live. DataView never touches `localStorage`
+ * directly — it loads/saves through this seam, so preferences can move to any store
+ * (server-backed, in-memory for tests) without touching a component file.
+ */
+export interface ViewStateRepository {
+  load(viewId: string): DataViewState | undefined;
+  save(viewId: string, state: DataViewState): void;
+}
+
+/** An empty {@link DataViewState} — the fallback when nothing was persisted yet. */
+export function emptyDataViewState(): DataViewState {
+  return {
+    columnVisibility: {},
+    columnOrder: [],
+    columnSizing: {},
+    sorting: [],
+    filters: [],
+    search: "",
+  };
+}
+
+/** Slot a column occupies in the responsive card layout. */
+export type DataViewMobileSlot = "title" | "subtitle" | "status" | "date";
+
+/** Typed column meta the DataView-specific features read. */
+export interface DataViewColumnMeta {
+  /** Human-readable name used in the column-settings menu (falls back to the header). */
+  label?: UiText;
+  /** Slot in the auto-composed card layout. */
+  mobileSlot?: DataViewMobileSlot;
+  /** Fixed width hint (number = px, or any CSS length). */
+  width?: number | string;
+}
+
+/** Generic, typed column definition for {@link DataView}. */
+export interface DataViewColumn<T> {
+  /** Stable id — used for sorting/filter ids, visibility, ordering and sizing. */
+  id: string;
+  /** Header content. */
+  header: UiText;
+  /** The raw value of this column for a row (used by default cell rendering). */
+  accessor?: (row: T) => unknown;
+  /** Custom cell renderer; defaults to `String(accessor(row))`. */
+  cell?: (row: T) => ReactNode;
+  /** Whether the header offers the 3-state sort toggle (default true). */
+  enableSorting?: boolean;
+  meta?: DataViewColumnMeta;
+}
+
+/** A per-row action rendered by {@link DataView}'s actions column (or in card view). */
+export interface DataViewRowAction<T> {
+  label: UiText;
+  icon?: ReactNode;
+  onClick?: (row: T) => void;
+  variant?: "default" | "destructive";
+  /** Boolean or predicate of the row. */
+  disabled?: boolean | ((row: T) => boolean);
+  /** Boolean or predicate of the row. */
+  hidden?: boolean | ((row: T) => boolean);
+  /** Render beside the ellipsis menu in "menu" layout. */
+  inline?: boolean;
+  /**
+   * Fully custom control; custom controls always render inline and own their
+   * interaction surface (DataView only stops row-click propagation around them).
+   */
+  render?: (row: T) => ReactNode;
+}
+
+/** A batch action shown in the selection toolbar. */
+export interface DataViewBatchAction<T> {
+  label: UiText;
+  icon?: ReactNode;
+  onClick: (rows: T[]) => void;
+  /**
+   * Invoked instead of `onClick` when select-all-across-pages mode is active
+   * (the current page's rows are still passed for context).
+   */
+  onSelectAll?: (rows: T[]) => void;
+  variant?: "default" | "destructive";
+  /** Render as a button in the toolbar; otherwise it goes into the overflow menu. */
+  inline?: boolean;
+}
+
+/** Caller-owned wiring of the broadened "search everything" toggle. */
+export interface DataViewSearchScope {
+  broadened: boolean;
+  onBroadenedChange: (broadened: boolean) => void;
+  /** Button label while the scope is narrow (e.g. "Search everything"). */
+  label: UiText;
+  /** Button label while the scope is broadened (e.g. "Searching everything"). */
+  broadenedLabel: UiText;
+}
+
+/** Every user-facing string the DataView renders, overridable per instance. */
+export interface DataViewStrings {
+  searchPlaceholder: UiText;
+  clearSearch: UiText;
+  clearFilters: UiText;
+  viewOptions: UiText;
+  columns: UiText;
+  moveUp: UiText;
+  moveDown: UiText;
+  tableView: UiText;
+  cardView: UiText;
+  pageSize: UiText;
+  resultsRange: UiText; // "{from}–{to} of {total} results"
+  pageOf: UiText; // "Page {page} of {pages}"
+  firstPage: UiText;
+  previousPage: UiText;
+  nextPage: UiText;
+  lastPage: UiText;
+  selectAllPage: UiText;
+  selectRow: UiText;
+  selected: UiText; // "{count} selected"
+  selectAllResults: UiText; // "Select all {total} results"
+  clearSelection: UiText;
+  moreActions: UiText;
+  actions: UiText;
+  openRow: UiText; // "Open details: {label}"
+  expandRow: UiText;
+  collapseRow: UiText;
+  empty: UiText;
+  loading: UiText;
+  refreshing: UiText;
+  errorTitle: UiText;
+  resizeColumn: UiText;
+}
+
+export const DEFAULT_DATA_VIEW_STRINGS: DataViewStrings = {
+  searchPlaceholder: "Search…",
+  clearSearch: "Clear search",
+  clearFilters: "Clear filters",
+  viewOptions: "View options",
+  columns: "Columns",
+  moveUp: "Move up",
+  moveDown: "Move down",
+  tableView: "Table view",
+  cardView: "Card view",
+  pageSize: "Rows per page",
+  resultsRange: "{from}–{to} of {total} results",
+  pageOf: "Page {page} of {pages}",
+  firstPage: "First page",
+  previousPage: "Previous page",
+  nextPage: "Next page",
+  lastPage: "Last page",
+  selectAllPage: "Select all rows on this page",
+  selectRow: "Select row",
+  selected: "{count} selected",
+  selectAllResults: "Select all {total} results",
+  clearSelection: "Clear selection",
+  moreActions: "More actions",
+  actions: "Actions",
+  openRow: "Open details: {label}",
+  expandRow: "Expand row",
+  collapseRow: "Collapse row",
+  empty: "Nothing to show.",
+  loading: "Loading…",
+  refreshing: "Refreshing…",
+  errorTitle: "Could not load data.",
+  resizeColumn: "Resize column",
+};
+
+/** Tiny `{placeholder}` formatter for the countable strings above. */
+export function formatDataViewString(
+  template: string,
+  values: Record<string, string | number>,
+): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in values ? String(values[key]) : match,
+  );
+}
+
+/** Resolve a row-action boolean-or-predicate flag against a row. */
+export function resolveRowFlag<T>(
+  flag: boolean | ((row: T) => boolean) | undefined,
+  row: T,
+): boolean {
+  return typeof flag === "function" ? flag(row) : flag === true;
+}

package/src/errorMessages.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ErrorState } from "./ErrorState";
+import { ErrorMessagesProvider, useErrorMessage } from "./errorMessages";
+import { UiTextProvider } from "./uiText";
+import { ApiError } from "./unwrap";
+
+afterEach(cleanup);
+
+function Probe({ error }: { error: unknown }) {
+  const messageForCode = useErrorMessage();
+  return <output>{messageForCode(error) ?? "(none)"}</output>;
+}
+
+describe("useErrorMessage", () => {
+  it("maps a known code to the default client-owned copy", () => {
+    render(<Probe error={new ApiError("backend detail", { code: "stale_data", status: 409 })} />);
+
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "This item was changed by someone else. Refresh and try again.",
+    );
+  });
+
+  it("returns null for unknown codes and non-envelope errors", () => {
+    render(
+      <>
+        <Probe error={new ApiError("backend detail", { code: "freight_locked", status: 409 })} />
+        <Probe error={new Error("plain")} />
+        <Probe error="boom" />
+      </>,
+    );
+
+    for (const status of screen.getAllByRole("status")) {
+      expect(status).toHaveTextContent("(none)");
+    }
+  });
+
+  it("lets nested providers override and extend the map, resolving UiText descriptors", () => {
+    render(
+      <ErrorMessagesProvider
+        messages={{
+          stale_data: { id: "errors.stale", message: "Someone edited this. Reload." },
+        }}
+      >
+        <ErrorMessagesProvider messages={{ freight_locked: "This freight is locked." }}>
+          <Probe error={new ApiError("x", { code: "stale_data", status: 409 })} />
+          <Probe error={new ApiError("x", { code: "freight_locked", status: 409 })} />
+        </ErrorMessagesProvider>
+      </ErrorMessagesProvider>,
+    );
+
+    const statuses = screen.getAllByRole("status");
+    expect(statuses[0]).toHaveTextContent("Someone edited this. Reload.");
+    expect(statuses[1]).toHaveTextContent("This freight is locked.");
+  });
+});
+
+describe("ErrorState with coded errors", () => {
+  it("prefers the mapped message over the backend detail for known codes", () => {
+    render(
+      <ErrorState
+        error={new ApiError("Backend-produced detail.", { code: "permission_denied", status: 403 })}
+      />,
+    );
+
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "You do not have permission to do this.",
+    );
+    expect(screen.queryByText("Backend-produced detail.")).not.toBeInTheDocument();
+  });
+
+  it("falls back to the backend detail for unknown codes", () => {
+    render(
+      <UiTextProvider>
+        <ErrorState error={new ApiError("Module-specific detail.", { code: "freight_locked", status: 409 })} />
+      </UiTextProvider>,
+    );
+
+    expect(screen.getByRole("alert")).toHaveTextContent("Module-specific detail.");
+  });
+});

package/src/errorMessages.tsx

@@ -0,0 +1,79 @@
+import { createContext, useCallback, useContext, useMemo } from "react";
+import type { ReactNode } from "react";
+
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+/**
+ * Client-owned messages for the platform's stable error codes.
+ *
+ * The backend serialises every failure into the uniform envelope
+ * `{ code, detail, request_id }`: `code` is a stable machine identifier from
+ * the typed `AppError` taxonomy (`terp.core.errors`), `detail` the message the
+ * backend produced. Mapping codes to copy here lets the UI evolve (and
+ * localise) failure wording without a backend deploy; codes without an entry
+ * simply fall back to the backend `detail`, so the map never has to be
+ * complete. Values are {@link UiText}, resolved through the UiText seam like
+ * every other framework string.
+ */
+export type ErrorMessages = Record<string, UiText>;
+
+/**
+ * English defaults for the core `AppError` taxonomy. Apps override or extend
+ * per code via {@link ErrorMessagesProvider} — including codes their own
+ * backend modules add.
+ */
+export const DEFAULT_ERROR_MESSAGES: ErrorMessages = {
+  bad_request: "The request could not be processed.",
+  validation_failed: "Some fields are invalid. Check the form and try again.",
+  invalid_token: "Your session is invalid. Sign in again.",
+  authentication_required: "Sign in to continue.",
+  permission_denied: "You do not have permission to do this.",
+  not_found: "This item could not be found.",
+  conflict: "This conflicts with the current state. Refresh and try again.",
+  stale_data: "This item was changed by someone else. Refresh and try again.",
+};
+
+const ErrorMessagesContext = createContext<ErrorMessages>(DEFAULT_ERROR_MESSAGES);
+
+export interface ErrorMessagesProviderProps {
+  /** Per-code overrides and additions, merged over any outer provider's map. */
+  messages: ErrorMessages;
+  children: ReactNode;
+}
+
+/**
+ * Override or extend the code→message map for a subtree. Wrap the app once to
+ * localise the built-in codes and register module-specific ones; nests, so a
+ * module can add its own codes without touching the app shell.
+ */
+export function ErrorMessagesProvider({ messages, children }: ErrorMessagesProviderProps) {
+  const parent = useContext(ErrorMessagesContext);
+  const value = useMemo(() => ({ ...parent, ...messages }), [parent, messages]);
+  return <ErrorMessagesContext.Provider value={value}>{children}</ErrorMessagesContext.Provider>;
+}
+
+/**
+ * Resolve a caught failure to display copy: the mapped message for the error's
+ * stable `code` when one is registered, else `null` (callers fall back to the
+ * error's own message — the backend `detail`). Reads the error's `code`
+ * property, as carried by `ApiError` thrown from `unwrap`.
+ */
+export function useErrorMessage(): (error: unknown) => string | null {
+  const messages = useContext(ErrorMessagesContext);
+  const resolve = useUiText();
+  return useCallback(
+    (error: unknown) => {
+      if (error === null || typeof error !== "object") {
+        return null;
+      }
+      const { code } = error as { code?: unknown };
+      if (typeof code !== "string") {
+        return null;
+      }
+      const message = messages[code];
+      return message === undefined ? null : resolve(message);
+    },
+    [messages, resolve],
+  );
+}

package/src/feedback.test.tsx

@@ -0,0 +1,167 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ConfirmDialog } from "./ConfirmDialog";
+import { EmptyState } from "./EmptyState";
+import { describeError, ErrorState } from "./ErrorState";
+import { UiTextProvider } from "./uiText";
+import { Button } from "./ui/Button";
+
+afterEach(cleanup);
+
+describe("EmptyState", () => {
+  it("renders title, description, and the action slot", () => {
+    render(
+      <EmptyState
+        title="No tasks yet"
+        description="Create your first task to get going."
+        action={<Button>New task</Button>}
+      />,
+    );
+
+    expect(screen.getByText("No tasks yet")).toBeInTheDocument();
+    expect(screen.getByText("Create your first task to get going.")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "New task" })).toBeInTheDocument();
+  });
+});
+
+describe("describeError", () => {
+  it("derives a message from Errors, envelope objects, and strings", () => {
+    expect(describeError(new Error("task not found"))).toBe("task not found");
+    expect(describeError({ detail: "task not found", code: "not_found" })).toBe(
+      "task not found",
+    );
+    expect(describeError({ code: "not_found" })).toBe("not_found");
+    expect(describeError("boom")).toBe("boom");
+    expect(describeError(42)).toBeNull();
+    expect(describeError(null)).toBeNull();
+  });
+});
+
+describe("ErrorState", () => {
+  it("is an alert with a default title and the derived error message", () => {
+    render(<ErrorState error={new Error("task not found")} />);
+
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveTextContent("Something went wrong.");
+    expect(alert).toHaveTextContent("task not found");
+  });
+
+  it("prefers an explicit description and localises the title", () => {
+    render(
+      <UiTextProvider strings={{ errorTitle: "Er ging iets mis." }}>
+        <ErrorState description="Try again later." error={new Error("ignored")} />
+      </UiTextProvider>,
+    );
+
+    expect(screen.getByRole("alert")).toHaveTextContent("Er ging iets mis.");
+    expect(screen.getByText("Try again later.")).toBeInTheDocument();
+    expect(screen.queryByText("ignored")).not.toBeInTheDocument();
+  });
+});
+
+describe("ConfirmDialog", () => {
+  it("is closed (not modal) while open is false", () => {
+    render(
+      <ConfirmDialog open={false} onOpenChange={() => {}} onConfirm={() => {}} title="Delete?" />,
+    );
+    // The element stays mounted (so closing runs close(), which restores opener focus)
+    // but is not shown: no `open` attribute means the UA hides it.
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it("closes via close() when open flips back to false", () => {
+    const { rerender } = render(
+      <ConfirmDialog open onOpenChange={() => {}} onConfirm={() => {}} title="Delete?" />,
+    );
+    expect(screen.getByRole("dialog")).toBeInTheDocument();
+    rerender(
+      <ConfirmDialog open={false} onOpenChange={() => {}} onConfirm={() => {}} title="Delete?" />,
+    );
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it("confirms and cancels through the labelled buttons", () => {
+    const onConfirm = vi.fn();
+    const onOpenChange = vi.fn();
+    render(
+      <ConfirmDialog
+        open
+        onOpenChange={onOpenChange}
+        onConfirm={onConfirm}
+        title="Delete this task?"
+        description="This cannot be undone."
+        destructive
+      />,
+    );
+
+    expect(screen.getByRole("dialog", { name: "Delete this task?" })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Confirm" }));
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("dismisses on Escape (native cancel) while idle", () => {
+    const onOpenChange = vi.fn();
+    render(
+      <ConfirmDialog open onOpenChange={onOpenChange} onConfirm={() => {}} title="Delete?" />,
+    );
+
+    const dialog = screen.getByRole("dialog");
+    const cancelEvent = new Event("cancel", { cancelable: true });
+    fireEvent(dialog, cancelEvent);
+    expect(cancelEvent.defaultPrevented).toBe(true);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("blocks Escape and backdrop dismissal and disables buttons while pending", () => {
+    const onOpenChange = vi.fn();
+    render(
+      <ConfirmDialog
+        open
+        onOpenChange={onOpenChange}
+        onConfirm={() => {}}
+        title="Delete?"
+        isPending
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: "Confirm" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Cancel" })).toBeDisabled();
+    const dialog = screen.getByRole("dialog");
+    fireEvent(dialog, new Event("cancel", { cancelable: true }));
+    fireEvent.click(dialog);
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it("dismisses on backdrop click while idle, but not on clicks inside the panel", () => {
+    const onOpenChange = vi.fn();
+    render(
+      <ConfirmDialog
+        open
+        onOpenChange={onOpenChange}
+        onConfirm={() => {}}
+        title="Delete?"
+        description="Body copy"
+      />,
+    );
+
+    fireEvent.click(screen.getByText("Body copy"));
+    expect(onOpenChange).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole("dialog"));
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("locks body scroll while open and restores it on close", () => {
+    const { rerender } = render(
+      <ConfirmDialog open onOpenChange={() => {}} onConfirm={() => {}} title="Delete?" />,
+    );
+    expect(document.body.style.overflow).toBe("hidden");
+    rerender(
+      <ConfirmDialog open={false} onOpenChange={() => {}} onConfirm={() => {}} title="Delete?" />,
+    );
+    expect(document.body.style.overflow).toBe("");
+  });
+});