@terpjs/react-core 0.9.0 → 0.11.0

package/src/ui/Button.test.tsx

@@ -38,12 +38,78 @@ describe("Button", () => {
     expect(button.textContent).toBe("iDo it");
   });
 
+  it("names a non-default size and leaves the standard control unmarked", () => {
+    // md is the absence of an attribute, because the standard control's geometry IS the base
+    // rule — the shape density already uses, where "comfortable" matches no rule either. So
+    // this asserts the absence as deliberately as it asserts the presence: stamping
+    // data-size="md" would be harmless but would make the sheet's two-rule split read as an
+    // omission.
+    const { rerender } = render(<Button size="sm">Small</Button>);
+    expect(screen.getByRole("button", { name: "Small" })).toHaveAttribute("data-size", "sm");
+    rerender(<Button size="lg">Large</Button>);
+    expect(screen.getByRole("button", { name: "Large" })).toHaveAttribute("data-size", "lg");
+    rerender(<Button>Standard</Button>);
+    const standard = screen.getByRole("button", { name: "Standard" });
+    expect(standard.hasAttribute("data-size")).toBe(false);
+    expect(standard.getAttribute("style")).toBeNull();
+  });
+
+  it("fills its container from an attribute rather than an inline width", () => {
+    // The point of the prop: `style={{ width: "100%" }}` is the only other way there, and app
+    // modules may not write it (ADR 0059) — so full width was a shape the framework could
+    // produce and its consumers could not ask for. The absence of a style attribute is the
+    // half that matters, because an inline width would outrank the app theme.css that ADR 0094
+    // exists to empower.
+    render(<Button fullWidth>Wide</Button>);
+    const button = screen.getByRole("button", { name: "Wide" });
+    expect(button).toHaveAttribute("data-full-width", "true");
+    expect(button.getAttribute("style")).toBeNull();
+  });
+
+  it("marks a loading button busy, disables it, and shows the spinner in the icon slot", () => {
+    render(
+      <Button loading icon={<span data-testid="ico">i</span>}>
+        Saving
+      </Button>,
+    );
+    const button = screen.getByRole("button", { name: "Saving" });
+    expect(button).toHaveAttribute("data-loading", "true");
+    expect(button).toHaveAttribute("aria-busy", "true");
+    // Disabled, so a second click cannot start the same request twice — the reason the state
+    // exists at all rather than being decoration on a still-live control.
+    expect(button).toBeDisabled();
+    // The spinner REPLACES the icon rather than joining it, so the button's width does not
+    // jump as it enters and leaves the state.
+    expect(screen.queryByTestId("ico")).toBeNull();
+    expect(button.querySelector('[data-terp="spinner-ring"]')).not.toBeNull();
+    expect(button.getAttribute("style")).toBeNull();
+  });
+
+  it("keeps a loading button disabled even when the caller says otherwise", () => {
+    // `disabled={false}` and `loading` together is a real combination — a form that computes
+    // one from validity and the other from the request in flight — and the request has to
+    // win, or the state is advisory.
+    render(
+      <Button loading disabled={false}>
+        Saving
+      </Button>,
+    );
+    expect(screen.getByRole("button", { name: "Saving" })).toBeDisabled();
+  });
+
   it("still forwards an explicit style, so framework callers keep their escape", () => {
     // The sheet owns the base, and the escape still has to work: a caller may pass a measured
     // value the sheet has no business owning, and it wins because a style attribute outranks
-    // any author rule (ADR 0094 §3). It is no longer LoginView's full-width submit, which is
-    // what this comment used to cite — a fixed 100% is layout policy rather than a measured
-    // value, and the sheet could reach it, so it is a rule on the login form now.
+    // any author rule (ADR 0094 §3).
+    //
+    // This comment has now cited three different homes for the same 100%, which is the useful
+    // part of it. First it was LoginView's inline style. Then a rule on the login form's group,
+    // because a fixed 100% is layout policy rather than a measured value and the sheet could
+    // reach it — with a prop declined as API the package did not need for one internal caller.
+    // Now it is `fullWidth`, because the constraint that mattered was never the internal caller:
+    // app modules may not write `style` at all, so full width was a shape the framework could
+    // produce and its consumers could not ask for. The group rule is gone and LoginView passes
+    // the prop. The escape below is unaffected either way, which is why it is still here.
     render(<Button style={{ width: "100%" }}>Wide</Button>);
     expect(screen.getByRole("button", { name: "Wide" }).style.width).toBe("100%");
   });

package/src/ui/Button.tsx

@@ -1,13 +1,39 @@
 import type { ButtonHTMLAttributes, ReactNode } from "react";
 
+import { InlineSpinner } from "../LoadingState";
 import { injectTerpStyles } from "../styles";
 
 injectTerpStyles();
 
 export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
 
+/** Control size: `"md"` is the standard control and needs no attribute (see below). */
+export type ButtonSize = "sm" | "md" | "lg";
+
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: ButtonVariant;
+  /**
+   * Control size (default `"md"`). Changes the height, the horizontal padding and the label
+   * size together; composes with `data-density`, so a `"sm"` button inside a compact subtree
+   * is shorter still.
+   */
+  size?: ButtonSize;
+  /**
+   * The action is in flight: shows a spinner in the icon slot, marks the control
+   * `aria-busy` and disables it, so a second click cannot start the request twice.
+   *
+   * The spinner replaces `icon` rather than joining it, which keeps the button's width from
+   * jumping as it enters and leaves the state.
+   */
+  loading?: boolean;
+  /**
+   * Fill the container's inline size instead of the label's.
+   *
+   * It exists because the alternative was `style={{ width: "100%" }}`, which app modules may
+   * not write (ADR 0059) — so full width was a shape the framework could produce and its
+   * consumers could not ask for.
+   */
+  fullWidth?: boolean;
   /** Optional leading icon, rendered before `children` (e.g. `<Icon name="plus" />`). */
   icon?: ReactNode;
 }
@@ -20,23 +46,50 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  * matched on the `data-terp` / `data-variant` attributes set below (ADR 0094). So the
  * variant is a fact about the element rather than a style object chosen in here — which
  * is what a test should assert, and what an app's `theme.css` can restyle.
+ *
+ * `size`, `loading` and `fullWidth` are all closed sets, so all three are attributes with a
+ * rule each (ADR 0094 §3). Two details about how they are stamped are deliberate:
+ *
+ * `data-size` appears only for `"sm"` and `"lg"`. The standard control's geometry IS the base
+ * rule, so `md` is the absence of an attribute — the same shape density takes, where
+ * "comfortable" is the token sheet's `:root` value and the attribute for it matches no rule.
+ * (`data-variant` is stamped even for its default because `primary` has a rule of its own;
+ * the two idioms differ for that reason rather than by accident.)
+ *
+ * `loading` sets `disabled` as well, and the sizes are expressed as a `calc()` off the
+ * density token rather than as heights of their own, so density keeps composing with all
+ * three sizes without a second family of tokens to keep in step.
  */
 export function Button({
   variant = "primary",
+  size = "md",
+  loading = false,
+  fullWidth = false,
   icon,
   type = "button",
+  disabled,
   children,
   ...rest
 }: ButtonProps) {
+  const leading = loading ? <InlineSpinner size={14} /> : icon;
   return (
-    <button type={type} data-terp="button" data-variant={variant} {...rest}>
-      {icon !== undefined && (
+    <button
+      type={type}
+      data-terp="button"
+      data-variant={variant}
+      data-size={size === "md" ? undefined : size}
+      data-loading={loading ? "true" : undefined}
+      data-full-width={fullWidth ? "true" : undefined}
+      disabled={disabled === true || loading}
+      aria-busy={loading ? true : undefined}
+      {...rest}
+    >
+      {leading !== undefined && leading !== null && (
         <span aria-hidden="true" data-terp="button-icon">
-          {icon}
+          {leading}
         </span>
       )}
       {children}
     </button>
   );
 }
-

package/src/ui/Card.test.tsx

@@ -41,4 +41,17 @@ describe("Card", () => {
     const card = screen.getByText("alleen inhoud").closest('[data-terp="card"]');
     expect(card?.querySelector('[data-terp="card-header"]')).toBeNull();
   });
+  it("names the plain variant and leaves the boxed default unmarked", () => {
+    // The chrome-less titled region. A variant rather than a `Section` component of its own,
+    // because a chrome-less region is this element with three declarations removed — a second
+    // component would have meant six more markers describing the same DOM, and a `Surface` is
+    // a Card with no title, which this already is.
+    const { rerender } = render(<Card variant="plain" title="Plain">body</Card>);
+    const plain = screen.getByRole("heading", { name: "Plain" }).closest("section");
+    expect(plain).toHaveAttribute("data-variant", "plain");
+    rerender(<Card title="Boxed">body</Card>);
+    const boxed = screen.getByRole("heading", { name: "Boxed" }).closest("section");
+    expect(boxed!.hasAttribute("data-variant")).toBe(false);
+    expect(boxed!.getAttribute("style")).toBeNull();
+  });
 });

package/src/ui/Card.tsx

@@ -7,8 +7,27 @@ import type { UiText } from "../uiText";
 
 injectTerpStyles();
 
+/** Chrome, or none: `"plain"` keeps the heading and drops the box. */
+export type CardVariant = "boxed" | "plain";
+
 export interface CardProps
   extends Omit<HTMLAttributes<HTMLElement>, "style" | "title"> {
+  /**
+   * Whether the block carries a box (default `"boxed"`) or just its heading (`"plain"`).
+   *
+   * `"plain"` is the labelled-region case: a titled group inside something that is already a
+   * surface, where a second border reads as a frame around a frame. The commonest instance is
+   * a section whose body is a `DataView` — boxed, the table gets a border inside a border and
+   * loses its full width.
+   *
+   * It is a variant rather than a `Section` component of its own, and that is a decision worth
+   * knowing. A chrome-less titled region is exactly this element with three declarations
+   * removed: `Card` already renders a `<section>` with an `<h3>` and stacks its children on
+   * the token scale. A second component would have meant six more markers describing the same
+   * DOM, and a `Surface` — the third name the diagnosis suggested — is a `Card` with no title,
+   * which this already is. Two names for one box is the `LoadingButton` mistake.
+   */
+  variant?: CardVariant;
   /** Optional section heading, rendered as an `<h3>` in the card's header row. */
   title?: UiText;
   /** Optional muted one-liner under the title (what this block is about). */
@@ -31,6 +50,7 @@ export interface CardProps
  * spacing scale.
  */
 export function Card({
+  variant = "boxed",
   title,
   description,
   actions,
@@ -42,7 +62,14 @@ export function Card({
   const resolve = useUiText();
   const hasHeader = title !== undefined || actions !== undefined;
   return (
-    <Component {...rest} data-terp="card" data-gap={String(gap)}>
+    <Component
+      {...rest}
+      data-terp="card"
+      // `boxed` is the base rule, so its attribute would describe the default twice — the
+      // idiom density, Button's `md` and Grid's `auto` all use.
+      data-variant={variant === "boxed" ? undefined : variant}
+      data-gap={String(gap)}
+    >
       {hasHeader ? (
         <div data-terp="card-header">
           <div data-terp="card-heading">

package/src/ui/Checkbox.tsx

@@ -1,4 +1,4 @@
-import type { InputHTMLAttributes } from "react";
+import type { ChangeEvent, InputHTMLAttributes } from "react";
 
 import { injectTerpStyles } from "../styles";
 import { useUiText } from "../uiText";
@@ -25,7 +25,15 @@ export function Checkbox({ label, checked, defaultChecked, onChange, style, ...r
         data-terp="checkbox"
         checked={checked}
         defaultChecked={defaultChecked}
-        onChange={(event) => onChange?.(event.currentTarget.checked)}
+        // Attached only when there is something to call, exactly as Select does and for the
+        // reason stated there: an unconditional handler silences React's own "you provided a
+        // `checked` prop to a form field without an `onChange` handler" guard, so a caller who
+        // pinned `checked` and forgot the handler gets a control that looks operable, never
+        // changes, and says nothing about it. The spread form is what keeps the prop absent
+        // rather than present-and-undefined, which React treats as the same mistake.
+        {...(onChange !== undefined
+          ? { onChange: (event: ChangeEvent<HTMLInputElement>) => onChange(event.currentTarget.checked) }
+          : {})}
       />
       <span>{resolve(label)}</span>
     </label>

package/src/ui/Combobox.test.tsx

@@ -31,6 +31,55 @@ describe("Combobox", () => {
     expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
   });
 
+  it("matches a needle that the host's own case fold would have hidden", () => {
+    // The filter used to fold with `toLocaleLowerCase`, which asks the host what lowercase means.
+    // Turkish has two i's, and folded there `Italy` becomes `ıtaly` — dotless — which does not
+    // contain the `i` the user typed. Every option with a capital I disappeared for a Turkish
+    // visitor and for nobody else, and folding BOTH sides the same way does not help: the needle
+    // comes from a keyboard and the haystack from a server.
+    //
+    // The host is simulated rather than assumed, because the suite runs on nl-NL and a test that
+    // merely typed `i` would pass under the bug here and fail only in Istanbul. The prototype
+    // patch is scoped to this test and restored in `finally`.
+    const original = String.prototype.toLocaleLowerCase;
+    // Confirm the hazard is real on this ICU build before relying on it as the mechanism.
+    expect(original.call("Italy", "tr")).not.toContain("i");
+    String.prototype.toLocaleLowerCase = function turkish(this: string) {
+      return original.call(this, "tr");
+    };
+    try {
+      render(
+        <Combobox
+          aria-label="Country"
+          options={[...options, { value: "it", label: "Italy" }]}
+          onChange={vi.fn()}
+        />,
+      );
+      const input = screen.getByRole("combobox", { name: /Country/ });
+      fireEvent.focus(input);
+      // BOTH cases, because each catches a different half and neither catches the other.
+      //
+      // Lowercase is the real defect: the user types the dotted `i` their keyboard produces,
+      // Turkish folds the label to the dotless `ıtaly`, and the option vanishes. The ORIGINAL
+      // code folded both sides with the host locale, which is self-consistent — "ıtal" does
+      // occur in "ıtaly" — so a capital-I needle passes under the very bug this test exists
+      // for. The first version of this test asserted only the capital, and was green against
+      // it.
+      //
+      // Capital is still needed: it is the only case that fails when the NEEDLE alone reverts
+      // to the host fold, which lowercase cannot see because folding "ital" changes nothing.
+      for (const needle of ["ital", "Ital"]) {
+        fireEvent.change(input, { target: { value: needle } });
+        expect(
+          screen.getByRole("option", { name: "Italy" }),
+          `typing ${needle} must still match Italy on a Turkish host`,
+        ).toBeInTheDocument();
+      }
+    } finally {
+      String.prototype.toLocaleLowerCase = original;
+    }
+  });
+
   it("supports controlled value, Field labels, ARIA active option and keyboard navigation", () => {
     const onChange = vi.fn();
     render(
@@ -78,3 +127,93 @@ describe("Combobox", () => {
     expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
   });
 });
+
+describe("Combobox multiple", () => {
+  it("accumulates a set, keeps the list open, and clears the filter between picks", () => {
+    // The reason this mode exists: a set-valued field had no control, and the absence
+    // produced comma-separated text boxes with the legal values in a grey hint beside them
+    // — a closed enum typed as free text, so validation the value set could have enforced
+    // was lost. Picking one member of a set is almost never the last thing a user wants, so
+    // the list staying open is the behaviour, not a detail.
+    const onChange = vi.fn();
+    render(<Combobox multiple aria-label="Fields" options={options} onChange={onChange} />);
+    const input = screen.getByRole("combobox", { name: "Fields" });
+
+    fireEvent.focus(input);
+    fireEvent.click(screen.getByRole("option", { name: "Netherlands" }));
+    expect(onChange).toHaveBeenLastCalledWith(["nl"], [options[0]]);
+    // Still open, and the filter is empty so the next pick starts from the whole list.
+    expect(screen.getByRole("listbox")).toBeInTheDocument();
+    expect(input).toHaveValue("");
+
+    fireEvent.click(screen.getByRole("option", { name: "France" }));
+    expect(onChange).toHaveBeenLastCalledWith(["nl", "fr"], [options[0], options[3]]);
+
+    // Selecting an already-chosen option removes it — one control, both directions.
+    fireEvent.click(screen.getByRole("option", { name: "Netherlands" }));
+    expect(onChange).toHaveBeenLastCalledWith(["fr"], [options[3]]);
+  });
+
+  it("says it is multi-selectable and marks every chosen option", () => {
+    render(<Combobox multiple aria-label="Fields" options={options} defaultValue={["nl", "fr"]} defaultOpen />);
+    expect(screen.getByRole("listbox")).toHaveAttribute("aria-multiselectable", "true");
+    expect(screen.getByRole("option", { name: "Netherlands" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("option", { name: "France" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("option", { name: "Belgium" })).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("gives every token a remove control whose name says which token it removes", () => {
+    // N identical "Remove" buttons is not a keyboard-accessible token field: the name has to
+    // carry the option, or a screen-reader user cannot tell which one they are about to
+    // remove. These are real buttons and real tab stops — the accessible half of the
+    // Backspace shortcut rather than a duplicate of it, because a shortcut is only
+    // discoverable if you already know about it.
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple aria-label="Fields" options={options} defaultValue={["nl", "fr"]} onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Remove Netherlands" }));
+    expect(onChange).toHaveBeenLastCalledWith(["fr"], [options[3]]);
+  });
+
+  it("removes the last token on Backspace only when the filter is empty", () => {
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple aria-label="Fields" options={options} defaultValue={["nl", "fr"]} onChange={onChange} />,
+    );
+    const input = screen.getByRole("combobox", { name: "Fields" });
+
+    // With text in the box, Backspace belongs to the text: eating a token here would
+    // delete a selection while the user thinks they are correcting a typo.
+    fireEvent.change(input, { target: { value: "Bel" } });
+    fireEvent.keyDown(input, { key: "Backspace" });
+    expect(onChange).not.toHaveBeenCalled();
+
+    fireEvent.change(input, { target: { value: "" } });
+    fireEvent.keyDown(input, { key: "Backspace" });
+    expect(onChange).toHaveBeenLastCalledWith(["nl"], [options[0]]);
+  });
+
+  it("keeps a controlled set when the parent declines the change", () => {
+    // The same invariant single mode has: the control shows what the prop says, not what
+    // was clicked. A token that appears because it was clicked and not because the parent
+    // accepted it is a field that disagrees with the state it is bound to.
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple aria-label="Fields" options={options} value={["nl"]} onChange={onChange} defaultOpen />,
+    );
+    fireEvent.click(screen.getByRole("option", { name: "France" }));
+    expect(onChange).toHaveBeenLastCalledWith(["nl", "fr"], [options[0], options[3]]);
+    expect(screen.getByRole("button", { name: "Remove Netherlands" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Remove France" })).toBeNull();
+  });
+
+  it("clears the whole set through the clear control", () => {
+    const onChange = vi.fn();
+    render(
+      <Combobox multiple clearable aria-label="Fields" options={options} defaultValue={["nl", "fr"]} onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Clear all selections" }));
+    expect(onChange).toHaveBeenLastCalledWith([], []);
+  });
+});