@terpjs/react-core 0.8.0 → 0.10.0

package/src/layout.test.tsx

@@ -2,7 +2,7 @@
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 
-import { DetailList, Stack } from "./layout";
+import { DetailList, Divider, Grid, Stack } from "./layout";
 
 afterEach(cleanup);
 
@@ -51,6 +51,77 @@ describe("Stack", () => {
     expect(el.style.display).toBe("");
   });
 
+  it("splits a responsive prop into a narrow attribute and a wide one", () => {
+    // jsdom evaluates no media query, so the unit-level claim is the attributes and nothing
+    // more — which is the honest boundary. That the rules then apply at the right width is a
+    // browser fact, held by the `stack-responsive-*` specimen pair at 420 and 900.
+    render(
+      <Stack
+        data-testid="toolbar"
+        direction={{ narrow: "column", wide: "row" }}
+        gap={{ narrow: 2, wide: 4 }}
+      >
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("toolbar");
+    expect(el).toHaveAttribute("data-direction", "column");
+    expect(el).toHaveAttribute("data-direction-wide", "row");
+    expect(el).toHaveAttribute("data-gap", "2");
+    expect(el).toHaveAttribute("data-gap-wide", "4");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("stamps no wide attribute when the prop is not responsive", () => {
+    // The back-compatibility claim, asserted as absence: every Stack in every consuming app
+    // passes scalars, so it must render exactly the attributes it always did — which is why
+    // adding the feature moved no baseline anywhere.
+    render(
+      <Stack data-testid="plain" direction="row" gap={4}>
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("plain");
+    expect(el).toHaveAttribute("data-direction", "row");
+    expect(el).toHaveAttribute("data-gap", "4");
+    expect(el.hasAttribute("data-direction-wide")).toBe(false);
+    expect(el.hasAttribute("data-gap-wide")).toBe(false);
+  });
+
+  it("accepts a responsive gap of 0, which a falsy check would drop", () => {
+    // `gap: 0` is a legal step and the only one that is falsy, so a `value.wide || undefined`
+    // anywhere in the split would silently render the narrow gap at every width.
+    render(
+      <Stack data-testid="zero" gap={{ narrow: 4, wide: 0 }}>
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("zero")).toHaveAttribute("data-gap-wide", "0");
+  });
+
+  it("names padding on the token scale, including the falsy zero step", () => {
+    // `padding={0}` is a legal step and the only falsy one, so a truthiness check anywhere in
+    // the stamp would silently drop it and inherit the container's inset instead.
+    const { rerender } = render(
+      <Stack data-testid="padded" padding={4}>
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("padded")).toHaveAttribute("data-padding", "4");
+    rerender(
+      <Stack data-testid="padded" padding={0}>
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("padded")).toHaveAttribute("data-padding", "0");
+    rerender(
+      <Stack data-testid="padded">
+        <span>a</span>
+      </Stack>,
+    );
+    expect(screen.getByTestId("padded").hasAttribute("data-padding")).toBe(false);
+  });
+
   it("works as a form (submit handler fires)", () => {
     let submitted = false;
     render(
@@ -70,7 +141,133 @@ describe("Stack", () => {
   });
 });
 
+describe("Grid", () => {
+  it("leaves every default unstamped, because the defaults ARE the base rule", () => {
+    // auto columns, the sm track floor and stretched cells are what the base rule declares, so
+    // their attributes would describe the standard shape a second time. Same idiom as density's
+    // "comfortable" and Button's md — and asserted as absence, deliberately, because a later
+    // change that starts stamping them would leave the sheet with two accounts of one default.
+    render(
+      <Grid data-testid="grid">
+        <span>a</span>
+      </Grid>,
+    );
+    const el = screen.getByTestId("grid");
+    expect(el.tagName).toBe("DIV");
+    expect(el).toHaveAttribute("data-terp", "grid");
+    expect(el).toHaveAttribute("data-gap", "4");
+    expect(el.hasAttribute("data-columns")).toBe(false);
+    expect(el.hasAttribute("data-min-column")).toBe(false);
+    expect(el.hasAttribute("data-align")).toBe(false);
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a fixed count, the element and the gap", () => {
+    render(
+      <Grid data-testid="grid" as="ul" columns={3} gap={2}>
+        <li>a</li>
+      </Grid>,
+    );
+    const el = screen.getByTestId("grid");
+    expect(el.tagName).toBe("UL");
+    // A number prop, a text attribute: `columns={3}` has to produce "3" or the rule misses.
+    expect(el).toHaveAttribute("data-columns", "3");
+    expect(el).toHaveAttribute("data-gap", "2");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a non-default track floor, and only while the columns are auto", () => {
+    // `minColumn` is meaningless at a fixed count — the tracks are counted, not floored — so
+    // stamping it there would put an attribute on the element that no rule reads and that a
+    // reader would take for an active choice.
+    const { rerender } = render(
+      <Grid data-testid="grid" minColumn="lg">
+        <span>a</span>
+      </Grid>,
+    );
+    expect(screen.getByTestId("grid")).toHaveAttribute("data-min-column", "lg");
+    rerender(
+      <Grid data-testid="grid" columns={2} minColumn="lg">
+        <span>a</span>
+      </Grid>,
+    );
+    const fixed = screen.getByTestId("grid");
+    expect(fixed).toHaveAttribute("data-columns", "2");
+    expect(fixed.hasAttribute("data-min-column")).toBe(false);
+  });
+
+  it("keeps alignment an attribute, unlike Stack's, and takes no style", () => {
+    // The deliberate divergence: Stack's align is an open set of CSS keywords and stays inline
+    // (ADR 0094 §3); Grid's is a closed four, so it is an attribute and Grid renders no inline
+    // style at all. That is what keeps a new primitive out of the inline-style ledger.
+    render(
+      <Grid data-testid="grid" align="center">
+        <span>a</span>
+      </Grid>,
+    );
+    const el = screen.getByTestId("grid");
+    expect(el).toHaveAttribute("data-align", "center");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+});
+
+describe("Divider", () => {
+  it("is an hr, so the separation reaches the accessibility tree", () => {
+    // A bordered div is what a module reaches for without a primitive, and it says nothing to
+    // a screen reader. The element is the point of the component.
+    render(<Divider data-testid="rule" />);
+    const el = screen.getByTestId("rule");
+    expect(el.tagName).toBe("HR");
+    expect(el).toHaveAttribute("data-terp", "divider");
+    expect(el.hasAttribute("data-orientation")).toBe(false);
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("announces a vertical rule as one, which hr does not imply", () => {
+    render(<Divider data-testid="rule" orientation="vertical" />);
+    const el = screen.getByTestId("rule");
+    expect(el).toHaveAttribute("data-orientation", "vertical");
+    expect(el).toHaveAttribute("aria-orientation", "vertical");
+  });
+});
+
 describe("DetailList", () => {
+  it("leaves the inline default unstamped, and marks each row", () => {
+    // `inline` and one column are the base rule. The row marker is new and load-bearing: the
+    // aligned layout turns the wrapper into `display: contents` so the dt and dd become grid
+    // items of the dl itself, which is the only way to align labels across rows without
+    // changing the DOM — and a rule cannot reach an unmarked wrapper.
+    render(<DetailList data-testid="dl" items={[{ label: "Owner", value: "Ada" }]} />);
+    const el = screen.getByTestId("dl");
+    expect(el.hasAttribute("data-layout")).toBe(false);
+    expect(el.hasAttribute("data-columns")).toBe(false);
+    expect(el.querySelector('[data-terp="detail-list-row"]')).not.toBeNull();
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a layout and a column count", () => {
+    render(
+      <DetailList
+        data-testid="dl"
+        layout="aligned"
+        columns={2}
+        items={[{ label: "Owner", value: "Ada" }]}
+      />,
+    );
+    const el = screen.getByTestId("dl");
+    expect(el).toHaveAttribute("data-layout", "aligned");
+    expect(el).toHaveAttribute("data-columns", "2");
+  });
+
+  it("puts no colon in the markup, because two layouts must not have one", () => {
+    // The colon is a rule on the inline layout, not a text node — `aligned` and `stacked` must
+    // not carry one, and no rule can withdraw a text node. It is decorative either way: the
+    // dt/dd pairing is what carries the relationship to assistive tech, so moving it out of the
+    // markup also stops it being read aloud.
+    render(<DetailList items={[{ label: "Owner", value: "Ada" }]} />);
+    expect(screen.getByText("Owner").textContent).toBe("Owner");
+  });
+
   it("renders label/value pairs as a definition list", () => {
     render(
       <DetailList

package/src/layout.tsx

@@ -6,13 +6,45 @@ import type { UiText } from "./uiText";
 /** The spacing scale — indexes into the `--space-*` design tokens (no arbitrary pixel gaps). */
 export type SpaceToken = 0 | 1 | 2 | 3 | 4 | 6 | 8;
 
+/**
+ * A value, or one value below the framework's viewport cutover and another above it.
+ *
+ * There is one cutover and not a scale of them, deliberately: `wide` is the complement of the
+ * width at which the shell becomes a drawer and the DataView becomes cards, so a responsive
+ * `Stack` changes over at exactly the moment the chrome around it does. A second breakpoint is
+ * a rule per value per breakpoint in the sheet, and nothing has asked for one — the same reason
+ * the density scale has two steps rather than five.
+ */
+export type Responsive<T> = T | { narrow: T; wide: T };
+
+/** Split a possibly-responsive prop into its two halves. */
+function responsive<T>(value: Responsive<T>): { narrow: T; wide: T | undefined } {
+  return value !== null && typeof value === "object" && "narrow" in value
+    ? { narrow: value.narrow, wide: value.wide }
+    : { narrow: value as T, wide: undefined };
+}
+
 export interface StackProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
   /** The rendered element (`"div"` by default; use `"form"`, `"section"`, `"ul"`, …). */
   as?: ElementType;
-  /** Main axis: `"column"` (default) stacks, `"row"` lines up. */
-  direction?: "column" | "row";
+  /**
+   * Main axis: `"column"` (default) stacks, `"row"` lines up.
+   *
+   * Takes a {@link Responsive} pair for the toolbar case — `{ narrow: "column", wide: "row" }`
+   * is a row of controls that stacks below the cutover, which was previously inexpressible
+   * without a `style` an app module may not write.
+   */
+  direction?: Responsive<"column" | "row">;
   /** Gap between children, as a step on the token spacing scale (default `2`). */
-  gap?: SpaceToken;
+  gap?: Responsive<SpaceToken>;
+  /**
+   * Inset around the children, as a step on the token spacing scale (default none).
+   *
+   * The dimension the diagnosis named first — "no padding" — and the one that made a padded
+   * region reachable only through a `Card`, whose border and background came with it whether
+   * they were wanted or not.
+   */
+  padding?: SpaceToken;
   /** Cross-axis alignment (e.g. `"center"`, `"start"`, `"end"`, `"stretch"`). */
   align?: CSSProperties["alignItems"];
   /** Main-axis distribution (e.g. `"space-between"`, `"center"`, `"end"`). */
@@ -33,6 +65,7 @@ export function Stack({
   as: Component = "div",
   direction = "column",
   gap = 2,
+  padding,
   align,
   justify,
   wrap = false,
@@ -49,18 +82,140 @@ export function Stack({
           ...(align !== undefined ? { alignItems: align } : undefined),
           ...(justify !== undefined ? { justifyContent: justify } : undefined),
         };
+  // A responsive prop is two attributes, and the wide half is stamped only when it was asked
+  // for — so a non-responsive Stack renders exactly the attributes it always did and every
+  // existing baseline is untouched by construction.
+  const directions = responsive(direction);
+  const gaps = responsive(gap);
   return (
     <Component
       {...rest}
       data-terp="stack"
-      data-direction={direction}
-      data-gap={String(gap)}
+      data-direction={directions.narrow}
+      data-direction-wide={directions.wide}
+      data-gap={String(gaps.narrow)}
+      data-gap-wide={gaps.wide === undefined ? undefined : String(gaps.wide)}
+      data-padding={padding === undefined ? undefined : String(padding)}
       data-wrap={wrap ? "true" : undefined}
       style={alignment}
     />
   );
 }
 
+/** Fixed column count, or `"auto"` — as many columns as fit above `minColumn`. */
+export type GridColumns = 1 | 2 | 3 | 4 | "auto";
+
+/** Track floor for an `"auto"` grid: the width below which a column stops being one. */
+export type GridMinColumn = "xs" | "sm" | "md" | "lg";
+
+export interface GridProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /** The rendered element (`"div"` by default; use `"ul"`, `"section"`, `"dl"`, …). */
+  as?: ElementType;
+  /**
+   * Columns: a fixed count, or `"auto"` (the default) for as many as fit above
+   * {@link GridProps.minColumn}.
+   *
+   * `"auto"` is the responsive answer and it takes no breakpoint: the track floor makes the
+   * grid reflow to whatever its **container** can hold, which is what a caller almost always
+   * means and is more nearly right than a viewport query — a grid inside a narrow panel
+   * should go one-column whatever the window is doing.
+   */
+  columns?: GridColumns;
+  /** Track floor for an `"auto"` grid (default `"sm"`); ignored at a fixed count. */
+  minColumn?: GridMinColumn;
+  /** Gap between cells, as a step on the token spacing scale (default `4`). */
+  gap?: SpaceToken;
+  /** Inset around the cells, as a step on the token spacing scale (default none). */
+  padding?: SpaceToken;
+  /**
+   * Block alignment of each cell within its row (default `"stretch"`).
+   *
+   * A closed set of four, unlike `Stack`'s `align` — see the note on {@link Grid}.
+   */
+  align?: "start" | "center" | "end" | "stretch";
+  children?: ReactNode;
+}
+
+/**
+ * The two-dimensional layout primitive, and the one that lifts a real ceiling: with `Stack`
+ * as the entire vocabulary, a two-column form could not be expressed at all, so a fifteen-field
+ * form shipped as one long vertical run. App modules may not write `style` or `className`
+ * (ADR 0059), so that was not awkwardness — it was unbuildable.
+ *
+ * Every prop is a closed set and becomes a `data-*` attribute with a rule each, so `Grid`
+ * renders **no inline style** and stays out of the inline-style ledger (ADR 0097). Three
+ * consequences of that are worth knowing, because each was a choice:
+ *
+ * - **`align` takes four values, where `Stack`'s takes any alignment keyword.** The divergence
+ *   is deliberate rather than an oversight. `Stack`'s is open because it was already inline
+ *   when ADR 0094 drew the line, and an open vocabulary stays inline; a *new* component picks
+ *   the closed set so it needs no `style` at all. `justify` is absent for the same reason it
+ *   would be least useful: a grid's tracks already fill their container, so distributing them
+ *   is a question about the tracks rather than the cells, and no consumer has asked.
+ * - **`minColumn` is a scale, not a length.** `Icon`'s `size` takes any CSS length and stays
+ *   inline for it; a grid's column floor could have gone the same way. It is a scale instead
+ *   for the reason `Stack`'s `gap` is a token index: so there are no arbitrary widths. An app
+ *   wanting 17.5rem cannot have it, which is the same trade `gap` already makes.
+ * - **There is no `span`,** and therefore no twelve-column option. A span system needs a child
+ *   component to carry it, and a `columns={12}` with no way to span is a grid of twelve narrow
+ *   cells rather than a layout system — worse than not offering it.
+ */
+export function Grid({
+  as: Component = "div",
+  columns = "auto",
+  minColumn = "sm",
+  gap = 4,
+  padding,
+  align = "stretch",
+  ...rest
+}: GridProps) {
+  return (
+    <Component
+      {...rest}
+      data-terp="grid"
+      // The defaults are the base rule, so their attributes match nothing and are left off —
+      // the shape density and Button's `md` already use. String(columns) rather than the
+      // number, because a `data-` attribute is text and `columns={2}` must produce "2".
+      data-columns={columns === "auto" ? undefined : String(columns)}
+      data-min-column={columns === "auto" && minColumn !== "sm" ? minColumn : undefined}
+      data-gap={String(gap)}
+      data-padding={padding === undefined ? undefined : String(padding)}
+      data-align={align === "stretch" ? undefined : align}
+    />
+  );
+}
+
+export interface DividerProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /** `"horizontal"` (default) rules across a column; `"vertical"` separates a row. */
+  orientation?: "horizontal" | "vertical";
+}
+
+/**
+ * A rule between two groups of content — `Separator` under its other common name, shipped
+ * once rather than twice.
+ *
+ * An `<hr>`, so the separation is in the accessibility tree rather than only in the pixels; a
+ * bordered `<div>` is what a module reaches for when it has no primitive, and it says nothing
+ * to a screen reader. The vertical form carries `aria-orientation`, which `<hr>` does not
+ * imply.
+ *
+ * The vertical case needs a height from somewhere and deliberately does not invent one: it
+ * stretches to its flex or grid line, so it works between the items of a row `Stack` and is
+ * zero-height in a plain block parent. That is the one thing about it worth knowing before
+ * reaching for it, and the reason its specimen renders inside a fixed-height row.
+ */
+export function Divider({ orientation = "horizontal", ...rest }: DividerProps) {
+  return (
+    <hr
+      {...rest}
+      data-terp="divider"
+      // Horizontal is the base rule, so only the vertical case carries an attribute.
+      data-orientation={orientation === "vertical" ? "vertical" : undefined}
+      aria-orientation={orientation === "vertical" ? "vertical" : undefined}
+    />
+  );
+}
+
 export interface DetailItem {
   /** The item's label (rendered as `<dt>`). */
   label: UiText;
@@ -68,23 +223,65 @@ export interface DetailItem {
   value: ReactNode;
 }
 
+/** How a pair is arranged. */
+export type DetailListLayout = "inline" | "aligned" | "stacked";
+
 export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>, "style"> {
   /** The label/value pairs to render, in order. */
   items: readonly DetailItem[];
+  /**
+   * How each pair reads (default `"inline"` — `Label: value` on one line).
+   *
+   * `"aligned"` puts every label in a shared left column, so the values line up; `"stacked"`
+   * puts the label above its value, which is what a narrow column or a long value wants.
+   *
+   * The default is the old behaviour on purpose: this component is in the `standard` layout
+   * contract's detail-page slot, so every governed detail screen already renders one.
+   */
+  layout?: DetailListLayout;
+  /** Pairs per row (default `1`). */
+  columns?: 1 | 2;
 }
 
 /**
  * Token-styled label/value pairs as a semantic `<dl>` — record metadata on a detail page,
- * an expanded row's summary. Centralizes the "Label: value" pattern so modules never
- * hand-style definition lists.
+ * an expanded row's summary.
+ *
+ * A real grid rather than an inline run, which is the thing the diagnosis was pointing at: nine
+ * pairs including two 64-character digests, "through an inline run 4px apart with no
+ * alignment". Two fixes rather than one, and the second was the actual defect:
+ *
+ * - `layout="aligned"` gives the labels a shared column. The row wrapper becomes
+ *   `display: contents` so the `<dt>` and `<dd>` are grid items of the `<dl>` itself — no DOM
+ *   change, and the only way to align across rows without one.
+ * - **The tracks are floored at zero.** An implicit grid column is `auto`, which floors at
+ *   *min-content* — so a 64-character digest with nothing to break on widened the column and
+ *   pushed the list past its container. `minmax(0, 1fr)` is what stops that, and it is the same
+ *   declaration `Grid`'s fixed counts need for the same reason.
+ *
+ * The colon lives in the sheet rather than in the markup, because it belongs to the inline
+ * layout alone — `aligned` and `stacked` must not have one, and a text node cannot be
+ * withdrawn by a rule. It is decorative either way: the `<dt>` / `<dd>` pairing is what carries
+ * the relationship to assistive tech.
  */
-export function DetailList({ items, ...rest }: DetailListProps) {
+export function DetailList({
+  items,
+  layout = "inline",
+  columns = 1,
+  ...rest
+}: DetailListProps) {
   const text = useUiText();
   return (
-    <dl {...rest} data-terp="detail-list">
+    <dl
+      {...rest}
+      data-terp="detail-list"
+      // `inline` and one column are the base rule, so neither stamps an attribute.
+      data-layout={layout === "inline" ? undefined : layout}
+      data-columns={columns === 1 ? undefined : String(columns)}
+    >
       {items.map((item, index) => (
-        <div key={index}>
-          <dt data-terp="detail-list-term">{text(item.label)}: </dt>
+        <div key={index} data-terp="detail-list-row">
+          <dt data-terp="detail-list-term">{text(item.label)}</dt>
           <dd data-terp="detail-list-value">{item.value}</dd>
         </div>
       ))}