@terpjs/react-core 0.1.0

package/src/ui/Badge.tsx

@@ -0,0 +1,48 @@
+import type { CSSProperties } from "react";
+
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+
+export type BadgeTone = "neutral" | "info" | "success" | "warning" | "danger";
+
+export interface BadgeProps {
+  label: UiText;
+  tone?: BadgeTone;
+}
+
+const toneColor: Record<BadgeTone, string> = {
+  neutral: "var(--color-neutral-600)",
+  info: "var(--color-status-info)",
+  success: "var(--color-status-success)",
+  warning: "var(--color-status-warning)",
+  danger: "var(--color-status-danger)",
+};
+
+const toneSoft: Record<BadgeTone, string> = {
+  neutral: "var(--color-neutral-100)",
+  info: "var(--color-status-info-soft)",
+  success: "var(--color-status-success-soft)",
+  warning: "var(--color-status-warning-soft)",
+  danger: "var(--color-status-danger-soft)",
+};
+
+const badgeStyle = (tone: BadgeTone): CSSProperties => ({
+  display: "inline-flex",
+  alignItems: "center",
+  border: `1px solid ${toneSoft[tone]}`,
+  borderRadius: "var(--radius-full)",
+  padding: "2px var(--space-2)",
+  color: toneColor[tone],
+  background: toneSoft[tone],
+  fontSize: "var(--font-size-xs)",
+  fontWeight: "var(--font-weight-semibold)" as never,
+  lineHeight: 1.4,
+  whiteSpace: "nowrap",
+});
+
+/** Small token-styled status pill — flat soft tint with a matching text colour. */
+export function Badge({ label, tone = "neutral" }: BadgeProps) {
+  const resolve = useUiText();
+  return <span style={badgeStyle(tone)}>{resolve(label)}</span>;
+}
+

package/src/ui/Button.test.tsx

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Button } from "./Button";
+
+afterEach(cleanup);
+
+describe("Button", () => {
+  it("renders an accessible button with a default type and token styling", () => {
+    render(<Button>Save</Button>);
+    const button = screen.getByRole("button", { name: "Save" });
+    expect(button).toHaveAttribute("type", "button");
+    expect(button).toHaveAttribute("data-terp", "button");
+    expect(button).toHaveAttribute("data-variant", "primary");
+    expect(button.style.background).toContain("var(--color-brand-primary)");
+  });
+
+  it("renders the ghost variant with a transparent background", () => {
+    render(<Button variant="ghost">Cancel</Button>);
+    const button = screen.getByRole("button", { name: "Cancel" });
+    expect(button).toHaveAttribute("data-variant", "ghost");
+    expect(button.style.background).toBe("transparent");
+  });
+
+  it("renders a leading icon before the children", () => {
+    render(
+      <Button icon={<span data-testid="ico">i</span>}>Do it</Button>,
+    );
+    const button = screen.getByRole("button", { name: "Do it" });
+    const icon = screen.getByTestId("ico");
+    expect(button.contains(icon)).toBe(true);
+    expect(button.textContent).toBe("iDo it");
+  });
+});
+

package/src/ui/Button.tsx

@@ -0,0 +1,95 @@
+import type { ButtonHTMLAttributes, CSSProperties, ReactNode } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { CONTROL_TEXT_STYLE } from "./controlStyles";
+
+injectTerpStyles();
+
+export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  /** Optional leading icon, rendered before `children` (e.g. `<Icon name="plus" />`). */
+  icon?: ReactNode;
+}
+
+const baseStyle: CSSProperties = {
+  ...CONTROL_TEXT_STYLE,
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: "var(--space-2)",
+  fontWeight: "var(--font-weight-medium)" as never,
+  lineHeight: 1.2,
+  width: "fit-content",
+  maxWidth: "100%",
+  minHeight: "2.25rem",
+  padding: "0 var(--space-4)",
+  border: "1px solid transparent",
+  borderRadius: "var(--radius-md)",
+  boxSizing: "border-box",
+  cursor: "pointer",
+  whiteSpace: "normal",
+  textAlign: "center",
+};
+
+const variantStyle: Record<ButtonVariant, CSSProperties> = {
+  primary: {
+    background: "var(--color-brand-primary)",
+    color: "var(--color-brand-primary-contrast)",
+    boxShadow: "var(--shadow-sm)",
+  },
+  secondary: {
+    background: "var(--color-neutral-0)",
+    color: "var(--color-neutral-900)",
+    borderColor: "var(--color-neutral-300)",
+  },
+  danger: {
+    background: "var(--color-status-danger)",
+    color: "var(--color-neutral-0)",
+  },
+  ghost: {
+    background: "transparent",
+    color: "var(--color-neutral-700)",
+  },
+};
+
+const iconWrapStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  flexShrink: 0,
+};
+
+/**
+ * Token-styled button — use instead of a raw `<button>` (the module-boundary rule). It
+ * styles only via the design-token CSS variables, so it themes with the app. Hover,
+ * active and `:focus-visible` states are layered on via the injected react-core sheet,
+ * keyed by the `data-terp` / `data-variant` attributes set below.
+ */
+export function Button({
+  variant = "primary",
+  icon,
+  style,
+  type = "button",
+  children,
+  ...rest
+}: ButtonProps) {
+  return (
+    <button
+      type={type}
+      data-terp="button"
+      data-variant={variant}
+      {...rest}
+      style={{ ...baseStyle, ...variantStyle[variant], ...style }}
+    >
+      {icon !== undefined && (
+        <span aria-hidden="true" style={iconWrapStyle}>
+          {icon}
+        </span>
+      )}
+      {children}
+    </button>
+  );
+}
+

package/src/ui/Card.test.tsx

@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Card } from "./Card";
+
+afterEach(cleanup);
+
+describe("Card", () => {
+  it("renders a bordered token-styled section with a semantic h3 title", () => {
+    render(
+      <Card title="Bezetting per persoon" description="Uren per maand.">
+        <p>body</p>
+      </Card>,
+    );
+    const heading = screen.getByRole("heading", { level: 3, name: "Bezetting per persoon" });
+    expect(heading).toBeInTheDocument();
+    const card = heading.closest('[data-terp="card"]') as HTMLElement;
+    expect(card.tagName).toBe("SECTION");
+    expect(card.style.border).toContain("var(--color-neutral-200)");
+    expect(card.style.background).toContain("var(--color-neutral-0)");
+    expect(screen.getByText("Uren per maand.")).toBeInTheDocument();
+    expect(screen.getByText("body")).toBeInTheDocument();
+  });
+
+  it("renders the actions slot in the header row", () => {
+    render(
+      <Card title="Projecten" actions={<button type="button">Nieuw</button>}>
+        inhoud
+      </Card>,
+    );
+    expect(screen.getByRole("button", { name: "Nieuw" })).toBeInTheDocument();
+  });
+
+  it("renders headerless with children only", () => {
+    render(<Card>alleen inhoud</Card>);
+    const card = screen.getByText("alleen inhoud").closest('[data-terp="card"]');
+    expect(card?.querySelector('[data-terp="card-header"]')).toBeNull();
+  });
+});

package/src/ui/Card.tsx

@@ -0,0 +1,92 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
+
+import type { SpaceToken } from "../layout";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+
+export interface CardProps
+  extends Omit<HTMLAttributes<HTMLElement>, "style" | "title"> {
+  /** 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). */
+  description?: UiText;
+  /** Optional right-hand slot in the header row (filters, a legend, an action). */
+  actions?: ReactNode;
+  /** The rendered element — `"section"` by default (a titled block of a page). */
+  as?: "section" | "article" | "div" | "aside";
+  /** Gap between body children, as a step on the token spacing scale (default `3`). */
+  gap?: SpaceToken;
+  children?: ReactNode;
+}
+
+const cardStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  background: "var(--color-neutral-0)",
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-lg)",
+  padding: "var(--space-4)",
+  minWidth: 0,
+};
+
+const headerStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  flexWrap: "wrap",
+  gap: "var(--space-3)",
+};
+
+const titleStyle: CSSProperties = {
+  margin: 0,
+  fontSize: "var(--font-size-base)",
+  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
+  lineHeight: 1.3,
+};
+
+const descriptionStyle: CSSProperties = {
+  margin: 0,
+  color: "var(--color-neutral-600)",
+  fontSize: "var(--font-size-sm)",
+};
+
+/**
+ * A token-styled surface that groups one block of a page — the sanctioned way to give
+ * sections visual separation (border + background + padding) without module CSS. An
+ * optional header row carries a semantic `<h3>` title, a muted description and an
+ * `actions` slot; the body stacks its children on the token spacing scale.
+ */
+export function Card({
+  title,
+  description,
+  actions,
+  as: Component = "section",
+  gap = 3,
+  children,
+  ...rest
+}: CardProps) {
+  const resolve = useUiText();
+  const hasHeader = title !== undefined || actions !== undefined;
+  return (
+    <Component {...rest} data-terp="card" style={{ ...cardStyle, gap: `var(--space-${gap})` }}>
+      {hasHeader ? (
+        <div data-terp="card-header" style={headerStyle}>
+          <div style={{ minWidth: 0 }}>
+            {title !== undefined ? <h3 style={titleStyle}>{resolve(title)}</h3> : null}
+            {description !== undefined ? (
+              <p style={descriptionStyle}>{resolve(description)}</p>
+            ) : null}
+          </div>
+          {actions !== undefined ? (
+            <div data-terp="card-actions" style={{ flexShrink: 0 }}>
+              {actions}
+            </div>
+          ) : null}
+        </div>
+      ) : description !== undefined ? (
+        <p style={descriptionStyle}>{resolve(description)}</p>
+      ) : null}
+      {children}
+    </Component>
+  );
+}

package/src/ui/Checkbox.test.tsx

@@ -0,0 +1,17 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Checkbox } from "./Checkbox";
+
+afterEach(cleanup);
+
+describe("Checkbox", () => {
+  it("renders a labelled checkbox and reports checked changes", () => {
+    const onChange = vi.fn();
+    render(<Checkbox label="Accept terms" checked={false} onChange={onChange} />);
+    const checkbox = screen.getByRole("checkbox", { name: "Accept terms" });
+    fireEvent.click(checkbox);
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+});

package/src/ui/Checkbox.tsx

@@ -0,0 +1,51 @@
+import type { CSSProperties, InputHTMLAttributes } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+
+injectTerpStyles();
+
+const labelStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "var(--space-2)",
+  color: "var(--color-neutral-900)",
+  cursor: "pointer",
+  fontSize: "var(--font-size-sm)",
+};
+
+const inputStyle: CSSProperties = {
+  inlineSize: "1rem",
+  blockSize: "1rem",
+  accentColor: "var(--color-brand-primary)",
+  cursor: "pointer",
+};
+
+export interface CheckboxProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange"> {
+  label: UiText;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onChange?: (checked: boolean) => void;
+}
+
+/** Token-styled labelled checkbox — use instead of a raw `<input type="checkbox">`. */
+export function Checkbox({ label, checked, defaultChecked, onChange, style, ...rest }: CheckboxProps) {
+  const resolve = useUiText();
+  return (
+    <label style={{ ...labelStyle, ...style }}>
+      <input
+        {...rest}
+        type="checkbox"
+        data-terp="checkbox"
+        checked={checked}
+        defaultChecked={defaultChecked}
+        onChange={(event) => onChange?.(event.currentTarget.checked)}
+        style={inputStyle}
+      />
+      <span>{resolve(label)}</span>
+    </label>
+  );
+}
+

package/src/ui/Combobox.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Field } from "../Field";
+import { Combobox } from "./Combobox";
+
+const options = [
+  { value: "nl", label: "Netherlands" },
+  { value: "be", label: "Belgium" },
+  { value: "de", label: "Germany", disabled: true },
+  { value: "fr", label: "France" },
+];
+
+afterEach(cleanup);
+
+describe("Combobox", () => {
+  it("filters options and selects an uncontrolled value", () => {
+    const onChange = vi.fn();
+    render(<Combobox aria-label="Country" options={options} onChange={onChange} />);
+    const input = screen.getByRole("combobox", { name: /Country/ });
+    expect(input).toHaveAttribute("aria-expanded", "false");
+    fireEvent.focus(input);
+    expect(input).toHaveAttribute("aria-expanded", "true");
+    fireEvent.change(input, { target: { value: "bel" } });
+    expect(screen.getByRole("option", { name: "Belgium" })).toBeInTheDocument();
+    expect(screen.queryByRole("option", { name: "France" })).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole("option", { name: "Belgium" }));
+    expect(input).toHaveValue("Belgium");
+    expect(onChange).toHaveBeenCalledWith("be", options[1]);
+    expect(screen.queryByRole("listbox")).not.toBeInTheDocument();
+  });
+
+  it("supports controlled value, Field labels, ARIA active option and keyboard navigation", () => {
+    const onChange = vi.fn();
+    render(
+      <Field label="Country" error="Required">
+        <Combobox options={options} value="nl" onChange={onChange} aria-invalid />
+      </Field>,
+    );
+    const input = screen.getByRole("combobox", { name: /Country/ });
+    expect(input).toHaveValue("Netherlands");
+    expect(input).toHaveAttribute("aria-invalid", "true");
+    fireEvent.focus(input);
+    fireEvent.keyDown(input, { key: "ArrowDown" });
+    expect(input).toHaveAttribute("aria-activedescendant", expect.stringContaining("be"));
+    fireEvent.keyDown(input, { key: "End" });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onChange).toHaveBeenCalledWith("fr", options[3]);
+    expect(input).toHaveValue("Netherlands");
+  });
+
+  it("shows loading and disabled states", () => {
+    render(<Combobox aria-label="Assignee" options={[]} loading disabled />);
+    expect(screen.getByRole("combobox", { name: "Assignee" })).toBeDisabled();
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+});