@terpjs/react-core 0.1.0

package/src/ui/Select.tsx

@@ -0,0 +1,40 @@
+import type { CSSProperties, SelectHTMLAttributes } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { CONTROL_TEXT_STYLE } from "./controlStyles";
+
+injectTerpStyles();
+
+// SVG chevron rendered via a data URL background — keeps the token-only styling
+// contract while giving <select> a consistent affordance across platforms.
+const chevronUrl =
+  "url(\"data:image/svg+xml;charset=UTF-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20' fill='none' stroke='%2364748b' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m5 8 5 5 5-5'/%3E%3C/svg%3E\")";
+
+const selectStyle: CSSProperties = {
+  ...CONTROL_TEXT_STYLE,
+  lineHeight: 1.2,
+  maxWidth: "100%",
+  minWidth: 0,
+  minHeight: "2.25rem",
+  padding: "0 calc(var(--space-3) + 1.25rem) 0 var(--space-3)",
+  border: "1px solid var(--color-neutral-300)",
+  borderRadius: "var(--radius-md)",
+  color: "var(--color-neutral-900)",
+  background: `${chevronUrl} no-repeat right var(--space-2) center / 1rem 1rem, var(--color-neutral-0)`,
+  boxSizing: "border-box",
+  appearance: "none",
+  WebkitAppearance: "none",
+  MozAppearance: "none",
+};
+
+export type SelectProps = SelectHTMLAttributes<HTMLSelectElement>;
+
+/**
+ * Token-styled select — use instead of a raw `<select>` (the module-boundary rule). Pass `<option>`
+ * children as usual. The `data-terp="input"` marker opts the element into the shared focus
+ * ring; a subtle SVG chevron replaces the native affordance for a consistent look.
+ */
+export function Select({ style, ...rest }: SelectProps) {
+  return <select data-terp="input" {...rest} style={{ ...selectStyle, ...style }} />;
+}
+

package/src/ui/Switch.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 { Switch } from "./Switch";
+
+afterEach(cleanup);
+
+describe("Switch", () => {
+  it("renders an accessible switch and reports checked changes", () => {
+    const onChange = vi.fn();
+    render(<Switch label="Email alerts" checked={false} onChange={onChange} />);
+    const toggle = screen.getByRole("switch", { name: "Email alerts" });
+    fireEvent.click(toggle);
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+});

package/src/ui/Switch.tsx

@@ -0,0 +1,53 @@
+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: "2.25rem",
+  blockSize: "1.25rem",
+  accentColor: "var(--color-brand-primary)",
+  cursor: "pointer",
+  transition: "background-color 150ms ease",
+};
+
+export interface SwitchProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange" | "role"> {
+  label: UiText;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onChange?: (checked: boolean) => void;
+}
+
+/** Token-styled labelled switch for boolean settings. */
+export function Switch({ label, checked, defaultChecked, onChange, style, ...rest }: SwitchProps) {
+  const resolve = useUiText();
+  return (
+    <label style={{ ...labelStyle, ...style }}>
+      <input
+        {...rest}
+        type="checkbox"
+        role="switch"
+        data-terp="switch"
+        checked={checked}
+        defaultChecked={defaultChecked}
+        onChange={(event) => onChange?.(event.currentTarget.checked)}
+        style={inputStyle}
+      />
+      <span>{resolve(label)}</span>
+    </label>
+  );
+}
+

package/src/ui/Tabs.test.tsx

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Tabs } from "./Tabs";
+
+const tabs = [
+  { value: "overview", label: "Overview", content: <p>Overview panel</p> },
+  { value: "audit", label: "Audit", content: <p>Audit panel</p> },
+];
+
+afterEach(cleanup);
+
+describe("Tabs", () => {
+  it("renders tabs and switches uncontrolled selection by click", () => {
+    render(<Tabs label="Sections" tabs={tabs} defaultValue="overview" />);
+    expect(screen.getByRole("tablist", { name: "Sections" })).toBeInTheDocument();
+    expect(screen.getByRole("tabpanel")).toHaveTextContent("Overview panel");
+    fireEvent.click(screen.getByRole("tab", { name: "Audit" }));
+    expect(screen.getByRole("tabpanel")).toHaveTextContent("Audit panel");
+  });
+
+  it("reports controlled changes and supports arrow navigation", () => {
+    const onChange = vi.fn();
+    render(<Tabs label="Sections" tabs={tabs} value="overview" onChange={onChange} />);
+    fireEvent.keyDown(screen.getByRole("tablist"), { key: "ArrowRight" });
+    expect(onChange).toHaveBeenCalledWith("audit");
+  });
+});

package/src/ui/Tabs.tsx

@@ -0,0 +1,128 @@
+import { useId, useMemo, useState } from "react";
+import type { CSSProperties, KeyboardEvent, ReactNode } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+import { CONTROL_TEXT_STYLE } from "./controlStyles";
+
+injectTerpStyles();
+
+const rootStyle: CSSProperties = { display: "grid", gap: "var(--space-3)" };
+const tabListStyle: CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "var(--space-1)",
+  borderBlockEnd: "1px solid var(--color-neutral-200)",
+};
+const tabStyle = (selected: boolean): CSSProperties => ({
+  ...CONTROL_TEXT_STYLE,
+  fontWeight: (selected
+    ? "var(--font-weight-semibold)"
+    : "var(--font-weight-medium)") as never,
+  padding: "var(--space-2) var(--space-3)",
+  border: 0,
+  borderBlockEnd: selected ? "2px solid var(--color-brand-primary)" : "2px solid transparent",
+  color: selected ? "var(--color-brand-primary)" : "var(--color-neutral-600)",
+  background: "transparent",
+  cursor: "pointer",
+  marginBlockEnd: "-1px",
+});
+const panelStyle: CSSProperties = { color: "var(--color-neutral-900)" };
+
+export interface TabItem {
+  value: string;
+  label: UiText;
+  content: ReactNode;
+  disabled?: boolean;
+}
+
+export interface TabsProps {
+  tabs: readonly TabItem[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  label?: UiText;
+}
+
+/** In-page tab set with controlled/uncontrolled selection and arrow-key navigation. */
+export function Tabs({ tabs, value, defaultValue, onChange, label }: TabsProps) {
+  const baseId = useId();
+  const resolve = useUiText();
+  const enabledTabs = useMemo(() => tabs.filter((tab) => !tab.disabled), [tabs]);
+  const firstValue = enabledTabs[0]?.value ?? tabs[0]?.value ?? "";
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? firstValue);
+  const selectedValue = value ?? uncontrolledValue;
+  const selectedTab = tabs.find((tab) => tab.value === selectedValue) ?? enabledTabs[0] ?? tabs[0];
+
+  function select(next: string) {
+    if (value === undefined) {
+      setUncontrolledValue(next);
+    }
+    onChange?.(next);
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    if (!["ArrowRight", "ArrowDown", "ArrowLeft", "ArrowUp", "Home", "End"].includes(event.key)) {
+      return;
+    }
+    event.preventDefault();
+    if (enabledTabs.length === 0) {
+      return;
+    }
+    const currentIndex = Math.max(
+      0,
+      enabledTabs.findIndex((tab) => tab.value === selectedTab?.value),
+    );
+    const nextIndex =
+      event.key === "Home"
+        ? 0
+        : event.key === "End"
+          ? enabledTabs.length - 1
+          : event.key === "ArrowRight" || event.key === "ArrowDown"
+            ? (currentIndex + 1) % enabledTabs.length
+            : (currentIndex - 1 + enabledTabs.length) % enabledTabs.length;
+    const next = enabledTabs[nextIndex];
+    if (next) {
+      select(next.value);
+      document.getElementById(`${baseId}-tab-${next.value}`)?.focus();
+    }
+  }
+
+  return (
+    <div data-terp="tabs" style={rootStyle}>
+      <div role="tablist" aria-label={label === undefined ? undefined : resolve(label)} style={tabListStyle} onKeyDown={onKeyDown}>
+        {tabs.map((tab) => {
+          const selected = tab.value === selectedTab?.value;
+          return (
+            <button
+              key={tab.value}
+              id={`${baseId}-tab-${tab.value}`}
+              type="button"
+              role="tab"
+              data-terp="tab"
+              aria-selected={selected}
+              aria-controls={`${baseId}-panel-${tab.value}`}
+              tabIndex={selected ? 0 : -1}
+              disabled={tab.disabled}
+              onClick={() => select(tab.value)}
+              style={tabStyle(selected)}
+            >
+              {resolve(tab.label)}
+            </button>
+          );
+        })}
+      </div>
+      {selectedTab && (
+        <div
+          id={`${baseId}-panel-${selectedTab.value}`}
+          role="tabpanel"
+          aria-labelledby={`${baseId}-tab-${selectedTab.value}`}
+          style={panelStyle}
+        >
+          {selectedTab.content}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/ui/Textarea.tsx

@@ -0,0 +1,27 @@
+import type { CSSProperties, TextareaHTMLAttributes } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { CONTROL_TEXT_STYLE } from "./controlStyles";
+
+injectTerpStyles();
+
+const textareaStyle: CSSProperties = {
+  ...CONTROL_TEXT_STYLE,
+  lineHeight: 1.4,
+  padding: "var(--space-2) var(--space-3)",
+  border: "1px solid var(--color-neutral-300)",
+  borderRadius: "var(--radius-md)",
+  color: "var(--color-neutral-900)",
+  background: "var(--color-neutral-0)",
+  boxSizing: "border-box",
+};
+
+export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+
+/**
+ * Token-styled multiline input — use instead of a raw `<textarea>` (the module-boundary rule).
+ */
+export function Textarea({ style, ...rest }: TextareaProps) {
+  return <textarea data-terp="input" {...rest} style={{ ...textareaStyle, ...style }} />;
+}
+

package/src/ui/Tooltip.test.tsx

@@ -0,0 +1,28 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Button } from "./Button";
+import { Tooltip } from "./Tooltip";
+
+afterEach(cleanup);
+
+describe("Tooltip", () => {
+  it("describes its trigger and opens on focus and hover", () => {
+    render(
+      <Tooltip content="More information">
+        <Button>Help</Button>
+      </Tooltip>,
+    );
+    const trigger = screen.getByRole("button", { name: "Help" });
+    const tooltip = screen.getByRole("tooltip", { hidden: true });
+    expect(trigger).toHaveAttribute("aria-describedby", tooltip.id);
+    expect(tooltip).not.toBeVisible();
+    fireEvent.focus(trigger);
+    expect(tooltip).toBeVisible();
+    fireEvent.blur(trigger);
+    expect(tooltip).not.toBeVisible();
+    fireEvent.mouseEnter(trigger.parentElement!);
+    expect(tooltip).toBeVisible();
+  });
+});

package/src/ui/Tooltip.tsx

@@ -0,0 +1,67 @@
+import { cloneElement, isValidElement, useId, useState } from "react";
+import type { CSSProperties, FocusEvent, MouseEvent, ReactElement } from "react";
+
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+
+const wrapperStyle: CSSProperties = { position: "relative", display: "inline-flex" };
+const tooltipStyle: CSSProperties = {
+  position: "absolute",
+  zIndex: 1,
+  insetBlockEnd: "calc(100% + var(--space-1))",
+  insetInlineStart: 0,
+  maxInlineSize: "min(18rem, calc(100vw - 2 * var(--space-4)))",
+  padding: "var(--space-1) var(--space-2)",
+  borderRadius: "var(--radius-sm)",
+  color: "var(--color-neutral-0)",
+  background: "var(--color-neutral-900)",
+  fontSize: "var(--font-size-xs)",
+  fontWeight: "var(--font-weight-medium)" as never,
+  lineHeight: 1.4,
+  boxShadow: "var(--shadow-md)",
+  pointerEvents: "none",
+  whiteSpace: "normal",
+};
+
+export interface TooltipProps {
+  content: UiText;
+  children: ReactElement;
+}
+
+interface TriggerHandlers {
+  onFocus?: (event: FocusEvent) => void;
+  onBlur?: (event: FocusEvent) => void;
+  onMouseEnter?: (event: MouseEvent) => void;
+  onMouseLeave?: (event: MouseEvent) => void;
+  "aria-describedby"?: string;
+}
+
+/** Accessible focus/hover tooltip. */
+export function Tooltip({ content, children }: TooltipProps) {
+  const id = useId();
+  const resolve = useUiText();
+  const [open, setOpen] = useState(false);
+
+  if (!isValidElement<TriggerHandlers>(children)) {
+    return children;
+  }
+
+  return (
+    <span style={wrapperStyle} onMouseEnter={() => setOpen(true)} onMouseLeave={() => setOpen(false)}>
+      {cloneElement(children, {
+        "aria-describedby": id,
+        onFocus: (event: FocusEvent) => {
+          children.props.onFocus?.(event);
+          setOpen(true);
+        },
+        onBlur: (event: FocusEvent) => {
+          children.props.onBlur?.(event);
+          setOpen(false);
+        },
+      })}
+      <span id={id} role="tooltip" hidden={!open} style={tooltipStyle}>
+        {resolve(content)}
+      </span>
+    </span>
+  );
+}

package/src/ui/controlStyles.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties } from "react";
+
+/** Stable typography for interactive controls, independent of surrounding display text. */
+export const CONTROL_TEXT_STYLE: CSSProperties = {
+  fontFamily: "var(--font-family-sans)",
+  fontSize: "var(--font-size-sm)",
+  fontWeight: "var(--font-weight-normal)" as CSSProperties["fontWeight"],
+  lineHeight: 1.25,
+};

package/src/uiText.test.tsx

@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Page } from "./Page";
+import { ResourceList } from "./ResourceList";
+import { TerpProvider } from "./TerpProvider";
+import { resolveUiText, UiTextProvider } from "./uiText";
+
+afterEach(cleanup);
+
+describe("resolveUiText", () => {
+  it("passes plain strings through and falls back to a descriptor's message", () => {
+    expect(resolveUiText("Tasks")).toBe("Tasks");
+    expect(resolveUiText({ id: "tasks.title", message: "Tasks" })).toBe("Tasks");
+  });
+});
+
+describe("UiTextProvider", () => {
+  it("components use the bundled defaults without a provider", () => {
+    render(
+      <Page title="Tasks" isLoading>
+        x
+      </Page>,
+    );
+    expect(screen.getByText("Loading...")).toBeInTheDocument();
+  });
+
+  it("overrides framework strings per key", () => {
+    render(
+      <UiTextProvider strings={{ loading: "Laden..." }}>
+        <Page title="Taken" isLoading>
+          x
+        </Page>
+      </UiTextProvider>,
+    );
+    expect(screen.getByText("Laden...")).toBeInTheDocument();
+    expect(screen.queryByText("Loading...")).not.toBeInTheDocument();
+  });
+
+  it("routes UiText props through a custom resolver (the i18n runtime hook)", () => {
+    render(
+      <UiTextProvider
+        resolveText={(text) =>
+          typeof text === "string" ? text : `[${text.id}] ${text.message}`
+        }
+      >
+        <Page title={{ id: "tasks.title", message: "Tasks" }}>x</Page>
+      </UiTextProvider>,
+    );
+    expect(
+      screen.getByRole("heading", { level: 1, name: "[tasks.title] Tasks" }),
+    ).toBeInTheDocument();
+  });
+
+  it("nested providers merge string overrides", () => {
+    render(
+      <UiTextProvider strings={{ loading: "Laden..." }}>
+        <UiTextProvider strings={{ emptyList: "Nog niets." }}>
+          <Page title="Taken" isLoading>
+            x
+          </Page>
+        </UiTextProvider>
+      </UiTextProvider>,
+    );
+    expect(screen.getByText("Laden...")).toBeInTheDocument();
+  });
+
+  it("localises ResourceList's empty message and create button", () => {
+    render(
+      <TerpProvider baseUrl="http://api.test">
+        <UiTextProvider strings={{ emptyList: "Nog niets.", add: "Toevoegen" }}>
+          <ResourceList
+            resource={{
+              items: [],
+              loading: false,
+              error: null,
+              cause: null,
+              create: async () => {},
+              reload: async () => {},
+              mutate: async (run: () => Promise<unknown>) => {
+                await run();
+              },
+            }}
+            renderItem={() => null}
+            createPlaceholder="Titel"
+          />
+        </UiTextProvider>
+      </TerpProvider>,
+    );
+    expect(screen.getByText("Nog niets.")).toBeInTheDocument();
+  });
+});