@ogygie/ui 0.0.0-stage → 0.16.0

package/src/DataTable.tsx

@@ -0,0 +1,161 @@
+/**
+ * @intent The data table of every Ogygie screen (D39): typed columns, sorting
+ * by header (TanStack Table v9 owns the model and the state, this file owns
+ * the markup), figures right-aligned in tabular figures with their unit, a
+ * skeleton for the loading state and the empty state DELEGATED to the caller
+ * (an EmptyState says why the table is empty; a table never says it alone).
+ * Every header is a node the product translates. TanStack Table is an
+ * OPTIONAL peer carried by this entry point only (`@ogygie/ui/data-table`).
+ */
+import { useMemo, useState, type ReactNode } from "react";
+import {
+  createColumnHelper,
+  createSortedRowModel,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_basic,
+  sortFn_datetime,
+  sortFn_text,
+  tableFeatures,
+  useTable,
+  type RowData,
+  type SortingState,
+} from "@tanstack/react-table";
+
+const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric, basic: sortFn_basic, datetime: sortFn_datetime, text: sortFn_text },
+});
+
+export type SortableValue = string | number | boolean | null | undefined;
+
+export interface DataTableColumn<TRow extends RowData> {
+  id: string;
+  header: ReactNode;
+  cell: (row: TRow) => ReactNode;
+  /** The value the column sorts on. Absent, the column does not sort. */
+  sortValue?: (row: TRow) => SortableValue;
+  /** Figures read right-aligned, in tabular figures (AGENTS.md §Front). */
+  align?: "start" | "end";
+}
+
+export interface DataTableProps<TRow extends RowData> {
+  rows: ReadonlyArray<TRow>;
+  /** Keep this array stable (module scope or useMemo): the model is rebuilt when it changes. */
+  columns: ReadonlyArray<DataTableColumn<TRow>>;
+  rowKey: (row: TRow) => string;
+  /** The table's accessible name, translated — read by screen readers only. */
+  caption?: ReactNode;
+  initialSort?: { id: string; desc: boolean };
+  /** Rendered INSTEAD of the table when there is no row — an EmptyState that says why. Absent, the headers render alone. */
+  emptyState?: ReactNode;
+}
+
+function alignClassOf(align: "start" | "end" | undefined): string {
+  return align === "end" ? "text-right tabular-nums" : "text-left";
+}
+
+export function DataTable<TRow extends RowData>(props: DataTableProps<TRow>) {
+  const descriptors = useMemo(() => new Map(props.columns.map((column) => [column.id, column])), [props.columns]);
+  const columns = useMemo(() => {
+    const helper = createColumnHelper<typeof features, TRow>();
+    return helper.columns(
+      props.columns.map((column) => {
+        const sortValue = column.sortValue;
+        return sortValue === undefined
+          ? helper.display({ id: column.id, enableSorting: false })
+          : helper.accessor((row: TRow) => sortValue(row) ?? undefined, { id: column.id, sortUndefined: "last" });
+      }),
+    );
+  }, [props.columns]);
+  const [sorting, setSorting] = useState<SortingState>(props.initialSort === undefined ? [] : [props.initialSort]);
+  const table = useTable({
+    features,
+    columns,
+    data: props.rows,
+    getRowId: (row) => props.rowKey(row),
+    state: { sorting },
+    onSortingChange: setSorting,
+    enableSortingRemoval: false,
+  });
+
+  if (props.rows.length === 0 && props.emptyState !== undefined) {
+    return <>{props.emptyState}</>;
+  }
+
+  return (
+    <div data-pattern="DataTable" className="overflow-x-auto rounded-md border border-border bg-surface-raised">
+      <table className="w-full border-collapse text-sm text-text">
+        {props.caption !== undefined && <caption className="sr-only">{props.caption}</caption>}
+        <thead className="bg-surface text-xs font-medium uppercase tracking-wide text-text-muted">
+          {table.getHeaderGroups().map((group) => (
+            <tr key={group.id}>
+              {group.headers.map((header) => {
+                const descriptor = descriptors.get(header.column.id);
+                const sorted = header.column.getIsSorted();
+                const canSort = header.column.getCanSort();
+                return (
+                  <th
+                    key={header.id}
+                    scope="col"
+                    aria-sort={sorted === "asc" ? "ascending" : sorted === "desc" ? "descending" : undefined}
+                    className={`px-3 py-2 ${alignClassOf(descriptor?.align)}`}
+                  >
+                    {canSort ? (
+                      <button
+                        type="button"
+                        onClick={header.column.getToggleSortingHandler()}
+                        data-sorted={sorted === false ? "none" : sorted}
+                        className="inline-flex items-center gap-1 uppercase hover:text-text"
+                      >
+                        {descriptor?.header}
+                        <span aria-hidden="true" className={sorted === false ? "opacity-40" : ""}>
+                          {sorted === "asc" ? "▲" : sorted === "desc" ? "▼" : "⇅"}
+                        </span>
+                      </button>
+                    ) : (
+                      descriptor?.header
+                    )}
+                  </th>
+                );
+              })}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {table.getRowModel().rows.map((row) => (
+            <tr key={row.id} className="border-t border-border hover:bg-surface">
+              {row.getAllCells().map((cell) => {
+                const descriptor = descriptors.get(cell.column.id);
+                return (
+                  <td key={cell.id} className={`px-3 py-2 ${alignClassOf(descriptor?.align)}`}>
+                    {descriptor?.cell(row.original)}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/** The loading state of a table: a header bar and pulsing rows, `role="status"`. */
+export function DataTableSkeleton({ rows = 5 }: { rows?: number }) {
+  return (
+    <div role="status" aria-busy="true" data-pattern="DataTable.Skeleton" className="animate-pulse rounded-md border border-border bg-surface-raised">
+      <div className="h-9 rounded-t-md bg-surface" />
+      {Array.from({ length: rows }, (_, index) => (
+        <div key={index} className="flex gap-3 border-t border-border px-3 py-3">
+          <div className="h-4 w-1/4 rounded-sm bg-border" />
+          <div className="h-4 w-1/2 rounded-sm bg-border" />
+          <div className="ml-auto h-4 w-12 rounded-sm bg-border" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+DataTable.Skeleton = DataTableSkeleton;

package/src/EditableText.test.tsx

@@ -0,0 +1,107 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the inline editor (spec ogygie-ui B5): plain text for a
+ * reader, a button for an editor, a focused field on click, save on blur or
+ * Enter, abandon on Escape, a blank draft refused without a write, the
+ * character count at a bound, an inactive control while a write is pending.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { EditableText } from "./EditableText.js";
+
+describe("EditableText", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ un lecteur ALORS le texte nu, jamais un contrôle inactif", () => {
+    const { container } = render(<EditableText value="First grade" onSave={() => undefined} placeholder="Unnamed" editable={false} ariaLabel="Label" />);
+    expect(container.querySelector("button")).toBeNull();
+    expect(screen.getByText("First grade")).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ une valeur vide ALORS le placeholder, en italique", () => {
+    render(<EditableText value="" onSave={() => undefined} placeholder="Unnamed" editable ariaLabel="Label" />);
+    expect(screen.getByText("Unnamed").className).toContain("italic");
+  });
+
+  it("ÉTANT DONNÉ un éditeur QUAND il clique, tape et quitte le champ ALORS la valeur est enregistrée", () => {
+    const onSave = vi.fn();
+    render(<EditableText value="First grade" onSave={onSave} placeholder="Unnamed" editable ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    const field = screen.getByRole("textbox", { name: "Label" });
+    expect(document.activeElement).toBe(field);
+    fireEvent.change(field, { target: { value: "Second grade" } });
+    fireEvent.blur(field);
+    expect(onSave).toHaveBeenCalledWith("Second grade");
+    expect(screen.getByRole("button", { name: "Label" })).toBeDefined();
+  });
+
+  it("QUAND la valeur n'a pas changé ALORS rien n'est écrit", () => {
+    const onSave = vi.fn();
+    render(<EditableText value="First grade" onSave={onSave} placeholder="Unnamed" editable ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    fireEvent.keyDown(screen.getByRole("textbox", { name: "Label" }), { key: "Enter" });
+    expect(onSave).not.toHaveBeenCalled();
+  });
+
+  it("QUAND Échap est pressé ALORS le brouillon est abandonné", () => {
+    const onSave = vi.fn();
+    render(<EditableText value="First grade" onSave={onSave} placeholder="Unnamed" editable ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    const field = screen.getByRole("textbox", { name: "Label" });
+    fireEvent.change(field, { target: { value: "Draft" } });
+    fireEvent.keyDown(field, { key: "Escape" });
+    expect(onSave).not.toHaveBeenCalled();
+    expect(screen.getByRole("button", { name: "Label" }).textContent).toBe("First grade");
+  });
+
+  it("QUAND le brouillon est blanc ALORS il est refusé sans écriture, et la valeur revient", () => {
+    const onSave = vi.fn();
+    render(<EditableText value="First grade" onSave={onSave} placeholder="Unnamed" editable ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    const field = screen.getByRole("textbox", { name: "Label" });
+    fireEvent.change(field, { target: { value: "   " } });
+    fireEvent.blur(field);
+    expect(onSave).not.toHaveBeenCalled();
+    expect(screen.getByRole("button", { name: "Label" }).textContent).toBe("First grade");
+  });
+
+  it("QUAND le contrat accepte le vide (allowEmpty) ALORS un brouillon vide s'enregistre", () => {
+    const onSave = vi.fn();
+    render(<EditableText value="Note" onSave={onSave} placeholder="Unnamed" editable allowEmpty ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    const field = screen.getByRole("textbox", { name: "Label" });
+    fireEvent.change(field, { target: { value: "" } });
+    fireEvent.blur(field);
+    expect(onSave).toHaveBeenCalledWith("");
+  });
+
+  it("ÉTANT DONNÉ une borne ALORS le champ la porte et le compteur suit le brouillon", () => {
+    render(<EditableText value="abc" onSave={() => undefined} placeholder="Unnamed" editable maxLength={5} ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    const field = screen.getByRole("textbox", { name: "Label" });
+    expect((field).getAttribute("maxlength")).toBe("5");
+    expect(screen.getByRole("status").textContent).toBe("3 / 5");
+    fireEvent.change(field, { target: { value: "abcde" } });
+    expect(screen.getByRole("status").className).toContain("text-warning");
+  });
+
+  it("ÉTANT DONNÉ multiline ALORS un textarea, qui garde Entrée pour la ligne suivante", () => {
+    const onSave = vi.fn();
+    render(<EditableText value="Note" onSave={onSave} placeholder="Unnamed" editable multiline ariaLabel="Label" />);
+    fireEvent.click(screen.getByRole("button", { name: "Label" }));
+    const field = screen.getByRole("textbox", { name: "Label" });
+    expect(field.tagName).toBe("TEXTAREA");
+    fireEvent.change(field, { target: { value: "Note\nmore" } });
+    fireEvent.keyDown(field, { key: "Enter" });
+    expect(onSave).not.toHaveBeenCalled();
+    fireEvent.blur(field);
+    expect(onSave).toHaveBeenCalledWith("Note\nmore");
+  });
+
+  it("ÉTANT DONNÉ une écriture en cours ALORS le contrôle est inactif et occupé", () => {
+    render(<EditableText value="First grade" onSave={() => undefined} placeholder="Unnamed" editable pending ariaLabel="Label" />);
+    const button = screen.getByRole("button", { name: "Label" });
+    expect((button as HTMLButtonElement).disabled).toBe(true);
+    expect((button).getAttribute("aria-busy")).toBe("true");
+  });
+});

package/src/EditableText.tsx

@@ -0,0 +1,117 @@
+/**
+ * @intent Text that is written where it is read (D39): a click turns the value
+ * into a field, leaving it saves, Escape abandons. No form, no submit button.
+ * A read-only viewer gets plain text, never a disabled control: a button one
+ * cannot press is a promise the screen does not keep. A blank draft is refused
+ * without a write unless the contract allows it; a bounded field stops at its
+ * bound and shows how much is used. One component for both apps of a product
+ * — the two copies it replaces had already diverged (astorg-ai-pdlc).
+ */
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { CharacterCount } from "./CharacterCount.js";
+
+export interface EditableTextProps {
+  value: string;
+  onSave: (value: string) => void;
+  /** Shown dimmed when the value is empty. */
+  placeholder: ReactNode;
+  editable: boolean;
+  multiline?: boolean;
+  /** The contract's bound: the field stops there and shows how much is used. */
+  maxLength?: number;
+  /** A blank or whitespace-only draft is refused without a write, unless the contract accepts an empty text. */
+  allowEmpty?: boolean;
+  /** A write in flight: the text stays, the control is inactive. */
+  pending?: boolean;
+  className?: string;
+  /** The accessible name of the control — a translated string from the product. */
+  ariaLabel: string;
+}
+
+export function EditableText(props: EditableTextProps) {
+  const { value, editable, multiline = false, className = "", ariaLabel, maxLength, allowEmpty = false, pending = false } = props;
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(value);
+  const field = useRef<HTMLTextAreaElement & HTMLInputElement>(null);
+
+  useEffect(() => {
+    if (editing) field.current?.focus();
+  }, [editing]);
+
+  const commit = (): void => {
+    setEditing(false);
+    if (draft === value) return;
+    if (!allowEmpty && draft.trim() === "") {
+      setDraft(value);
+      return;
+    }
+    props.onSave(draft);
+  };
+  const abandon = (): void => {
+    setDraft(value);
+    setEditing(false);
+  };
+
+  const shown = value === "" ? <span className="italic text-text-muted">{props.placeholder}</span> : value;
+
+  if (!editable) {
+    return (
+      <span data-pattern="EditableText" className={className}>
+        {shown}
+      </span>
+    );
+  }
+
+  if (editing) {
+    const shared = {
+      ref: field,
+      value: draft,
+      "aria-label": ariaLabel,
+      ...(maxLength === undefined ? {} : { maxLength }),
+      onChange: (event: { target: { value: string } }) => setDraft(event.target.value),
+      onBlur: commit,
+      className: `w-full rounded-sm border border-focus bg-surface-raised px-1.5 py-1 text-inherit outline-none ${className}`,
+    };
+    const control = multiline ? (
+      <textarea
+        {...shared}
+        rows={4}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") abandon();
+        }}
+      />
+    ) : (
+      <input
+        {...shared}
+        onKeyDown={(event) => {
+          if (event.key === "Enter") commit();
+          if (event.key === "Escape") abandon();
+        }}
+      />
+    );
+    return (
+      <span data-pattern="EditableText" data-state="editing">
+        {control}
+        {maxLength !== undefined && <CharacterCount length={draft.length} max={maxLength} />}
+      </span>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      data-pattern="EditableText"
+      data-state={pending ? "pending" : "read"}
+      aria-label={ariaLabel}
+      aria-busy={pending ? "true" : undefined}
+      disabled={pending}
+      onClick={() => {
+        setDraft(value);
+        setEditing(true);
+      }}
+      className={`w-full rounded-sm border border-transparent px-1.5 py-1 text-left hover:border-border hover:bg-surface disabled:opacity-60 ${className}`}
+    >
+      {shown}
+    </button>
+  );
+}

package/src/EmptyState.test.tsx

@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the empty state (spec ogygie-ui B4): title, explanation and
+ * at most one action, every text coming from the caller.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { EmptyState } from "./EmptyState.js";
+
+describe("EmptyState", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ un titre, une explication et une action ALORS les trois se lisent", () => {
+    render(<EmptyState title="No row yet" explanation="Create the first one." action={<button type="button">Create</button>} />);
+    expect(screen.getByText("No row yet")).toBeDefined();
+    expect(screen.getByText("Create the first one.")).toBeDefined();
+    expect(screen.getByRole("button", { name: "Create" })).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ aucune action ALORS aucun bouton", () => {
+    const { container } = render(<EmptyState title="No match" explanation="Widen the filter." />);
+    expect(container.querySelector("button")).toBeNull();
+    expect(container.querySelector("[data-pattern='EmptyState']")).not.toBeNull();
+  });
+});

package/src/EmptyState.tsx

@@ -0,0 +1,30 @@
+/**
+ * @intent An explicit empty state (D39): a title that names the CAUSE, an
+ * explanation that says what would fill it, and ONE creation action at most —
+ * an empty screen is the first screen every new user sees. The two causes of
+ * an empty view are told with different words by the caller (nothing recorded
+ * yet, or a filter that matches nothing): confusing them makes a reader doubt
+ * the data when they only searched too narrowly. Every text is a prop: the
+ * product translates, the pattern lays out.
+ */
+import type { ReactNode } from "react";
+
+export interface EmptyStateProps {
+  title: ReactNode;
+  explanation: ReactNode;
+  /** One creation action at most. */
+  action?: ReactNode;
+}
+
+export function EmptyState({ title, explanation, action }: EmptyStateProps) {
+  return (
+    <div
+      data-pattern="EmptyState"
+      className="rounded-md border border-dashed border-border bg-surface-raised px-6 py-10 text-center"
+    >
+      <p className="text-base font-medium text-text">{title}</p>
+      <p className="mt-1 text-sm text-text-muted">{explanation}</p>
+      {action !== undefined && <div className="mt-4 flex justify-center">{action}</div>}
+    </div>
+  );
+}

package/src/ErrorBanner.test.tsx

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the error surface (spec ogygie-ui B3): an OgygieFailure is
+ * shown in full — message, code, status, cause, suggested fix — under the
+ * product's title; anything else degrades to its message; a retry is a button
+ * the product labels.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { OgygieFailure, ogygieError } from "@ogygie/core/errors";
+import { ErrorBanner } from "./ErrorBanner.js";
+
+const failure = new OgygieFailure(
+  ogygieError({ code: "GRADE_IN_USE", message: "The row is still referenced.", file: null, cause: "3 holders", suggestedFix: "Move the holders first." }),
+  409,
+);
+
+describe("ErrorBanner", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ une OgygieFailure ALORS message, code, statut, cause et correction sont lisibles", () => {
+    render(<ErrorBanner error={failure} title="This change could not be saved" kind="save" />);
+    const alert = screen.getByRole("alert");
+    expect((alert).getAttribute("data-code")).toBe("GRADE_IN_USE");
+    expect((alert).getAttribute("data-kind")).toBe("save");
+    expect(screen.getByText("This change could not be saved")).toBeDefined();
+    expect(screen.getByText("The row is still referenced.")).toBeDefined();
+    expect(alert.textContent).toContain("GRADE_IN_USE · 409 — 3 holders");
+    expect(screen.getByText("Move the holders first.")).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ une erreur quelconque ALORS son message mène, sans code", () => {
+    render(<ErrorBanner error={new Error("boom")} />);
+    const alert = screen.getByRole("alert");
+    expect((alert).hasAttribute("data-code")).toBe(false);
+    expect((alert).getAttribute("data-kind")).toBe("load");
+    expect(screen.getByText("boom")).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ un retry ALORS un bouton libellé par le produit le déclenche", () => {
+    const onClick = vi.fn();
+    render(<ErrorBanner error={failure} retry={{ label: "Try again", onClick }} />);
+    fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/ErrorBanner.tsx

@@ -0,0 +1,58 @@
+/**
+ * @intent Shows a failed view without taking the whole screen down (D39): the
+ * sentence the product puts on it, the failure's message, then its code, its
+ * cause and its suggested fix — so a reader can say what happened and an agent
+ * can act on it. The rest of the screen stays usable. Accepts ANY thrown
+ * value: an OgygieFailure is displayed in full, anything else degrades to its
+ * message. No text of its own: the title and the retry label come translated
+ * from the product.
+ */
+import type { ReactNode } from "react";
+import { failureOf, messageOf, statusOf } from "./failures.js";
+
+export interface ErrorBannerProps {
+  error: unknown;
+  /** The sentence above the failure, worded by the product. Absent, the failure's message leads. */
+  title?: ReactNode;
+  /** A refused WRITE is not a view that failed to load: the product words its title accordingly, the banner marks it for styling and tests. */
+  kind?: "load" | "save";
+  /** A way back: re-run the read, close the panel. */
+  retry?: { label: ReactNode; onClick: () => void };
+}
+
+export function ErrorBanner({ error, title, kind = "load", retry }: ErrorBannerProps) {
+  const failure = failureOf(error);
+  const status = statusOf(error);
+  const message = messageOf(error);
+  return (
+    <div
+      role="alert"
+      data-pattern="ErrorBanner"
+      data-kind={kind}
+      data-code={failure?.code}
+      className="rounded-md border border-danger/40 bg-surface-raised px-4 py-3 text-sm text-text"
+    >
+      {title !== undefined && <p className="font-medium text-danger">{title}</p>}
+      <p className={title === undefined ? "font-medium text-danger" : "mt-1"}>{message}</p>
+      {failure !== null && (
+        <p className="mt-1 font-mono text-xs text-text-muted">
+          {failure.code}
+          {status === null ? "" : ` · ${status}`}
+          {failure.cause === "" ? "" : ` — ${failure.cause}`}
+        </p>
+      )}
+      {failure !== null && failure.suggestedFix !== "" && (
+        <p className="mt-1 text-xs text-text-muted">{failure.suggestedFix}</p>
+      )}
+      {retry !== undefined && (
+        <button
+          type="button"
+          onClick={retry.onClick}
+          className="mt-3 rounded-sm border border-border bg-surface px-3 py-1 text-xs font-medium text-text hover:bg-surface-raised"
+        >
+          {retry.label}
+        </button>
+      )}
+    </div>
+  );
+}

package/src/ScreenState.test.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the one screen-state component (spec ogygie-ui B2): denied
+ * before error, error before loading, loading before empty, the body last and
+ * only with data — each state carrying its data-state for a test to read.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { OgygieFailure, ogygieError } from "@ogygie/core/errors";
+import { ScreenState } from "./ScreenState.js";
+import { failedQuery, pendingQuery, readyQuery } from "./query-like.js";
+
+const denied = new OgygieFailure(ogygieError({ code: "WORKSPACE_OWNER_REQUIRED", message: "Only an owner may do this.", file: null, cause: "role member", suggestedFix: "Ask an owner." }), 403);
+const broken = new OgygieFailure(ogygieError({ code: "CONTRACT_BROKEN", message: "The answer violates its contract.", file: null, cause: "items.0.code", suggestedFix: "Align both sides." }), 200);
+
+const copy = { title: "Nothing here yet", explanation: "Create the first row." };
+const stateOf = (container: HTMLElement): string | null => container.querySelector("[data-pattern='ScreenState']")?.getAttribute("data-state") ?? null;
+
+describe("ScreenState", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ une lecture en attente ALORS le squelette, et rien d'autre", () => {
+    const { container } = render(<ScreenState query={pendingQuery<string[]>()}>{(rows) => <ul>{rows.length}</ul>}</ScreenState>);
+    expect(stateOf(container)).toBe("loading");
+    expect((screen.getByRole("status")).getAttribute("aria-busy")).toBe("true");
+  });
+
+  it("ÉTANT DONNÉ une lecture en attente avec un chargement fourni ALORS il remplace le squelette", () => {
+    render(
+      <ScreenState query={pendingQuery<string[]>()} loading={<p>custom skeleton</p>}>
+        {() => null}
+      </ScreenState>,
+    );
+    expect(screen.getByText("custom skeleton")).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ une lecture en erreur ALORS un ErrorBanner avec le code, titré par le produit", () => {
+    const { container } = render(
+      <ScreenState query={failedQuery(broken)} errorTitle="This view could not be loaded">
+        {() => null}
+      </ScreenState>,
+    );
+    expect(stateOf(container)).toBe("error");
+    expect((screen.getByRole("alert")).getAttribute("data-code")).toBe("CONTRACT_BROKEN");
+    expect(screen.getByText("This view could not be loaded")).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ un refus 403 et une copie d'accès refusé ALORS l'explication, jamais un bandeau d'erreur", () => {
+    const { container } = render(
+      <ScreenState query={failedQuery(denied)} accessDenied={{ title: "Owners only", explanation: "Ask an owner." }}>
+        {() => null}
+      </ScreenState>,
+    );
+    expect(stateOf(container)).toBe("denied");
+    expect(screen.getByText("Owners only")).toBeDefined();
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  it("ÉTANT DONNÉ un refus 403 sans copie ALORS le bandeau d'erreur dit le code", () => {
+    const { container } = render(<ScreenState query={failedQuery(denied)}>{() => null}</ScreenState>);
+    expect(stateOf(container)).toBe("error");
+    expect((screen.getByRole("alert")).getAttribute("data-code")).toBe("WORKSPACE_OWNER_REQUIRED");
+  });
+
+  it("ÉTANT DONNÉ le verdict de l'appelant (denied) ALORS l'explication avant toute lecture, même servie", () => {
+    const { container } = render(
+      <ScreenState query={readyQuery(["a"])} denied accessDenied={{ title: "Owners only", explanation: "Ask an owner." }}>
+        {(rows) => <p>{rows.join()}</p>}
+      </ScreenState>,
+    );
+    expect(stateOf(container)).toBe("denied");
+    expect(screen.queryByText("a")).toBeNull();
+  });
+
+  it("ÉTANT DONNÉ une collection vide et une copie d'état vide ALORS l'EmptyState avec son action", () => {
+    const { container } = render(
+      <ScreenState query={readyQuery<string[]>([])} isEmpty={(rows) => rows.length === 0} emptyState={{ ...copy, action: <button type="button">Add</button> }}>
+        {() => <p>body</p>}
+      </ScreenState>,
+    );
+    expect(stateOf(container)).toBe("empty");
+    expect(screen.getByRole("button", { name: "Add" })).toBeDefined();
+    expect(screen.queryByText("body")).toBeNull();
+  });
+
+  it("ÉTANT DONNÉ une collection vide sans copie ALORS le corps reçoit la collection vide", () => {
+    render(
+      <ScreenState query={readyQuery<string[]>([])} isEmpty={(rows) => rows.length === 0}>
+        {(rows) => <p>body {rows.length}</p>}
+      </ScreenState>,
+    );
+    expect(screen.getByText("body 0")).toBeDefined();
+  });
+
+  it("ÉTANT DONNÉ des données servies ALORS le corps, sans enveloppe d'état", () => {
+    const { container } = render(
+      <ScreenState query={readyQuery(["a", "b"])} isEmpty={(rows) => rows.length === 0} emptyState={copy}>
+        {(rows) => <ul>{rows.map((row) => <li key={row}>{row}</li>)}</ul>}
+      </ScreenState>,
+    );
+    expect(stateOf(container)).toBeNull();
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+  });
+});