@terpjs/react-core 0.1.0

package/src/ui/Menu.test.tsx

@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Menu, MenuItem } from "./Menu";
+
+const items = ["Archive", "Duplicate", "Delete"];
+
+afterEach(cleanup);
+
+describe("Menu", () => {
+  it("portals the panel outside clipping ancestors without treating panel clicks as outside", () => {
+    render(
+      <div data-testid="clip" style={{ overflow: "hidden" }}>
+        <Menu trigger="Open" triggerLabel="Actions">
+          {({ close }) => <MenuItem label="Archive" onSelect={() => close()} />}
+        </Menu>
+      </div>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Actions" }));
+    const menu = screen.getByRole("menu");
+    expect(screen.getByTestId("clip")).not.toContainElement(menu);
+    expect(menu.parentElement).toHaveStyle({
+      fontFamily: "var(--font-family-sans)",
+      color: "var(--color-neutral-900)",
+    });
+    fireEvent.pointerDown(menu);
+    expect(menu).toBeInTheDocument();
+  });
+
+  it("opens, roves enabled items, selects and restores trigger focus", () => {
+    const onDelete = vi.fn();
+    render(
+      <Menu trigger="⋯" triggerLabel="More actions">
+        {({ close }) => (
+          <>
+            <MenuItem label="Archive" onSelect={() => {}} />
+            <MenuItem label="Duplicate" disabled onSelect={() => {}} />
+            <MenuItem label="Delete" destructive onSelect={() => { onDelete(); close(true); }} />
+          </>
+        )}
+      </Menu>,
+    );
+
+    const trigger = screen.getByRole("button", { name: "More actions" });
+    fireEvent.click(trigger);
+    const menu = screen.getByRole("menu");
+    expect(screen.getByRole("menuitem", { name: "Archive" })).toHaveFocus();
+    fireEvent.keyDown(menu, { key: "ArrowDown" });
+    expect(screen.getByRole("menuitem", { name: "Delete" })).toHaveFocus();
+    fireEvent.click(screen.getByRole("menuitem", { name: "Delete" }));
+    expect(onDelete).toHaveBeenCalledOnce();
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+    expect(trigger).toHaveFocus();
+  });
+
+  it("closes on Escape and outside click", () => {
+    render(
+      <Menu trigger="Open" triggerLabel="Actions">
+        {() => items.map((item) => <MenuItem key={item} label={item} onSelect={() => {}} />)}
+      </Menu>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Actions" }));
+    fireEvent.keyDown(screen.getByRole("menu"), { key: "Escape" });
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Actions" }));
+    fireEvent.pointerDown(document.body);
+    expect(screen.queryByRole("menu")).not.toBeInTheDocument();
+  });
+
+  it("reports one controlled close for one outside pointer interaction", () => {
+    const onOpenChange = vi.fn();
+    render(
+      <Menu trigger="Open" triggerLabel="Actions" open onOpenChange={onOpenChange}>
+        {() => <MenuItem label="Archive" onSelect={() => {}} />}
+      </Menu>,
+    );
+
+    fireEvent.pointerDown(document.body);
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+});

package/src/ui/Menu.tsx

@@ -0,0 +1,216 @@
+import { useRef } from "react";
+import type { CSSProperties, KeyboardEvent, ReactNode } from "react";
+
+import { Icon } from "../icons";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+import { CONTROL_TEXT_STYLE } from "./controlStyles";
+import { Popover } from "./Popover";
+import type { PopoverAlign, PopoverPlacement } from "./Popover";
+
+const triggerStyle: CSSProperties = {
+  ...CONTROL_TEXT_STYLE,
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  minHeight: "2rem",
+  gap: "var(--space-1)",
+  padding: "var(--space-1) var(--space-2)",
+  background: "transparent",
+  color: "var(--color-neutral-700)",
+  border: "1px solid var(--color-neutral-300)",
+  borderRadius: "var(--radius-md)",
+  cursor: "pointer",
+};
+
+const menuStyle: CSSProperties = { display: "grid", gap: "var(--space-1)" };
+
+const itemStyle = (destructive: boolean, disabled: boolean): CSSProperties => ({
+  ...CONTROL_TEXT_STYLE,
+  display: "flex",
+  alignItems: "center",
+  gap: "var(--space-2)",
+  width: "100%",
+  padding: "var(--space-2)",
+  background: "transparent",
+  border: "none",
+  borderRadius: "var(--radius-sm)",
+  textAlign: "left",
+  justifyContent: "flex-start",
+  cursor: disabled ? "not-allowed" : "pointer",
+  color: disabled
+    ? "var(--color-neutral-300)"
+    : destructive
+      ? "var(--color-status-danger)"
+      : "var(--color-neutral-900)",
+});
+
+export interface MenuProps {
+  trigger: ReactNode;
+  triggerLabel: UiText;
+  children: (api: { close: (restoreFocus?: boolean) => void }) => ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  align?: PopoverAlign;
+  placement?: PopoverPlacement;
+  triggerStyle?: CSSProperties;
+  panelStyle?: CSSProperties;
+}
+
+/** Dropdown menu built on Popover with roving focus and ARIA menu semantics. */
+export function Menu({
+  trigger,
+  triggerLabel,
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+  align = "end",
+  placement = "bottom",
+  triggerStyle: triggerStyleOverride,
+  panelStyle,
+}: MenuProps) {
+  const resolve = useUiText();
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  function focusItem(direction: 1 | -1 | "first" | "last") {
+    const items = menuItems(menuRef.current).filter((item) => !item.disabled);
+    if (items.length === 0) {
+      return;
+    }
+    const currentIndex = items.findIndex((item) => item === document.activeElement);
+    const nextIndex = direction === "first"
+      ? 0
+      : direction === "last"
+        ? items.length - 1
+        : currentIndex < 0
+          ? 0
+          : (currentIndex + direction + items.length) % items.length;
+    items[nextIndex]?.focus();
+  }
+
+  return (
+    <Popover
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      align={align}
+      placement={placement}
+      panelStyle={panelStyle}
+      trigger={
+        <button
+          type="button"
+          data-terp="iconbutton"
+          aria-label={resolve(triggerLabel)}
+          aria-haspopup="menu"
+          style={{ ...triggerStyle, ...triggerStyleOverride }}
+        >
+          {trigger}
+        </button>
+      }
+    >
+      {({ close }) => (
+        <div
+          ref={(node) => {
+            menuRef.current = node;
+            if (node !== null && !node.contains(document.activeElement)) {
+              menuItems(node).find((item) => !item.disabled)?.focus();
+            }
+          }}
+          role="menu"
+          data-terp="menu"
+          style={menuStyle}
+          onKeyDown={(event: KeyboardEvent<HTMLDivElement>) => {
+            switch (event.key) {
+              case "Escape":
+                event.preventDefault();
+                close(true);
+                break;
+              case "ArrowDown":
+                event.preventDefault();
+                focusItem(1);
+                break;
+              case "ArrowUp":
+                event.preventDefault();
+                focusItem(-1);
+                break;
+              case "Home":
+                event.preventDefault();
+                focusItem("first");
+                break;
+              case "End":
+                event.preventDefault();
+                focusItem("last");
+                break;
+              case "Tab":
+                close(false);
+                break;
+              default:
+                break;
+            }
+          }}
+        >
+          {children({ close })}
+        </div>
+      )}
+    </Popover>
+  );
+}
+
+
+export interface MenuItemProps {
+  label: UiText;
+  icon?: ReactNode;
+  /** Marks one choice in a mutually exclusive menu (renders `menuitemradio`). */
+  selected?: boolean;
+  destructive?: boolean;
+  disabled?: boolean;
+  onSelect: () => void;
+}
+
+/** One actionable item inside a Menu. */
+export function MenuItem({
+  label,
+  icon,
+  selected,
+  destructive = false,
+  disabled = false,
+  onSelect,
+}: MenuItemProps) {
+  const resolve = useUiText();
+  return (
+    <button
+      type="button"
+      role={selected === undefined ? "menuitem" : "menuitemradio"}
+      aria-checked={selected}
+      data-terp="menu-item"
+      data-selected={selected === true ? "true" : undefined}
+      tabIndex={-1}
+      disabled={disabled}
+      onClick={() => {
+        if (!disabled) {
+          onSelect();
+        }
+      }}
+      style={itemStyle(destructive, disabled)}
+    >
+      {icon !== undefined && <span aria-hidden="true" style={{ display: "inline-flex" }}>{icon}</span>}
+      {resolve(label)}
+      {selected === true && (
+        <span aria-hidden="true" style={{ display: "inline-flex", marginLeft: "auto" }}>
+          <Icon name="check" />
+        </span>
+      )}
+    </button>
+  );
+}
+
+function menuItems(menu: HTMLDivElement | null): HTMLButtonElement[] {
+  if (menu === null) {
+    return [];
+  }
+  return Array.from(
+    menu.querySelectorAll<HTMLButtonElement>('[role="menuitem"], [role="menuitemradio"]'),
+  );
+}

package/src/ui/Popover.tsx

@@ -0,0 +1,218 @@
+import { cloneElement, useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import type { CSSProperties, KeyboardEvent, ReactElement, ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+import { injectTerpStyles } from "../styles";
+
+injectTerpStyles();
+
+export type PopoverPlacement = "bottom" | "top";
+export type PopoverAlign = "start" | "end";
+
+export interface PopoverProps {
+  trigger: ReactElement;
+  children: (api: { close: (restoreFocus?: boolean) => void; panelId: string }) => ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  placement?: PopoverPlacement;
+  align?: PopoverAlign;
+  focusOnOpen?: boolean;
+  panelStyle?: CSSProperties;
+}
+
+const rootStyle: CSSProperties = { position: "relative", display: "inline-flex" };
+
+const basePanelStyle: CSSProperties = {
+  position: "fixed",
+  zIndex: 60,
+  minWidth: "12rem",
+  padding: "var(--space-1)",
+  fontFamily: "var(--font-family-sans)",
+  color: "var(--color-neutral-900)",
+  background: "var(--color-neutral-0)",
+  border: "1px solid var(--color-neutral-200)",
+  borderRadius: "var(--radius-lg)",
+  boxShadow: "var(--shadow-lg)",
+};
+
+const VIEWPORT_GUTTER = 8;
+const PANEL_GAP = 4;
+
+interface PanelPosition {
+  left: number;
+  top: number;
+  visibility: CSSProperties["visibility"];
+}
+
+/** Anchored disclosure panel with outside-click, Escape close and focus return. */
+export function Popover({
+  trigger,
+  children,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  placement = "bottom",
+  align = "end",
+  focusOnOpen = false,
+  panelStyle,
+}: PopoverProps) {
+  const panelId = useId();
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const isOpen = open ?? uncontrolledOpen;
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [panelPosition, setPanelPosition] = useState<PanelPosition>({
+    left: 0,
+    top: 0,
+    visibility: "hidden",
+  });
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (open === undefined) {
+        setUncontrolledOpen(next);
+      }
+      onOpenChange?.(next);
+    },
+    [onOpenChange, open],
+  );
+
+  const close = useCallback(
+    (restoreFocus = true) => {
+      setOpen(false);
+      if (restoreFocus) {
+        triggerRef.current?.focus();
+      }
+    },
+    [setOpen],
+  );
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    if (focusOnOpen) {
+      window.setTimeout(() => {
+        const first = panelRef.current?.querySelector<HTMLElement>(
+          'button:not(:disabled), [href], input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])',
+        );
+        (first ?? panelRef.current)?.focus();
+      }, 0);
+    }
+    function onPointerDown(event: PointerEvent) {
+      const root = rootRef.current;
+      const panel = panelRef.current;
+      if (
+        root !== null &&
+        event.target instanceof Node &&
+        !root.contains(event.target) &&
+        !panel?.contains(event.target)
+      ) {
+        close(false);
+      }
+    }
+    function onKeyDown(event: globalThis.KeyboardEvent) {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        close(true);
+      }
+    }
+    document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [close, focusOnOpen, isOpen]);
+
+  useLayoutEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    function updatePosition() {
+      const trigger = triggerRef.current;
+      const panel = panelRef.current;
+      if (trigger === null || panel === null) {
+        return;
+      }
+      const anchor = trigger.getBoundingClientRect();
+      const panelRect = panel.getBoundingClientRect();
+      const below = anchor.bottom + PANEL_GAP;
+      const above = anchor.top - panelRect.height - PANEL_GAP;
+      const preferredTop = placement === "bottom" ? below : above;
+      const fallbackTop = placement === "bottom" ? above : below;
+      const fitsPreferred = preferredTop >= VIEWPORT_GUTTER &&
+        preferredTop + panelRect.height <= window.innerHeight - VIEWPORT_GUTTER;
+      const rawTop = fitsPreferred ? preferredTop : fallbackTop;
+      const rawLeft = align === "end"
+        ? anchor.right - panelRect.width
+        : anchor.left;
+      setPanelPosition({
+        left: Math.max(
+          VIEWPORT_GUTTER,
+          Math.min(rawLeft, window.innerWidth - panelRect.width - VIEWPORT_GUTTER),
+        ),
+        top: Math.max(
+          VIEWPORT_GUTTER,
+          Math.min(rawTop, window.innerHeight - panelRect.height - VIEWPORT_GUTTER),
+        ),
+        visibility: "visible",
+      });
+    }
+    updatePosition();
+    window.addEventListener("resize", updatePosition);
+    window.addEventListener("scroll", updatePosition, true);
+    return () => {
+      window.removeEventListener("resize", updatePosition);
+      window.removeEventListener("scroll", updatePosition, true);
+    };
+  }, [align, isOpen, placement]);
+
+  const triggerProps = trigger.props as Record<string, unknown>;
+  const cloned = cloneElement(trigger, {
+    ref: (node: HTMLElement | null) => {
+      triggerRef.current = node;
+      const originalRef = (trigger as ReactElement & { ref?: React.Ref<HTMLElement> }).ref;
+      if (typeof originalRef === "function") {
+        originalRef(node);
+      } else if (originalRef && typeof originalRef === "object") {
+        (originalRef as React.MutableRefObject<HTMLElement | null>).current = node;
+      }
+    },
+    "aria-expanded": isOpen,
+    "aria-controls": isOpen ? panelId : undefined,
+    onClick: (event: MouseEvent) => {
+      (triggerProps.onClick as ((event: MouseEvent) => void) | undefined)?.(event);
+      if (!event.defaultPrevented) {
+        setOpen(!isOpen);
+      }
+    },
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => {
+      (triggerProps.onKeyDown as ((event: KeyboardEvent<HTMLElement>) => void) | undefined)?.(event);
+      if (!event.defaultPrevented && (event.key === "ArrowDown" || event.key === "ArrowUp") && !isOpen) {
+        event.preventDefault();
+        setOpen(true);
+      }
+    },
+  } as Partial<typeof trigger.props>);
+
+  return (
+    <div ref={rootRef} data-terp="popover" style={rootStyle}>
+      {cloned}
+      {isOpen && createPortal(
+        <div
+          id={panelId}
+          ref={panelRef}
+          data-terp="popover-panel"
+          tabIndex={-1}
+          style={{ ...basePanelStyle, ...panelStyle, ...panelPosition }}
+        >
+          {children({ close, panelId })}
+        </div>,
+        document.body,
+      )}
+    </div>
+  );
+}

package/src/ui/Radio.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 { RadioGroup } from "./Radio";
+
+afterEach(cleanup);
+
+describe("RadioGroup", () => {
+  it("renders an accessible group and reports selected values", () => {
+    const onChange = vi.fn();
+    render(
+      <RadioGroup
+        label="Status"
+        name="status"
+        value="open"
+        onChange={onChange}
+        options={[
+          { value: "open", label: "Open" },
+          { value: "closed", label: "Closed" },
+        ]}
+      />,
+    );
+    expect(screen.getByRole("group", { name: "Status" })).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "Open" })).toBeChecked();
+    fireEvent.click(screen.getByRole("radio", { name: "Closed" }));
+    expect(onChange).toHaveBeenCalledWith("closed");
+  });
+});

package/src/ui/Radio.tsx

@@ -0,0 +1,127 @@
+import { useId, useState } from "react";
+import type { CSSProperties, InputHTMLAttributes, ReactNode } from "react";
+
+import { injectTerpStyles } from "../styles";
+import { useUiText } from "../uiText";
+import type { UiText } from "../uiText";
+
+injectTerpStyles();
+
+const groupStyle: CSSProperties = { display: "grid", gap: "var(--space-2)", border: 0, padding: 0, margin: 0 };
+const legendStyle: CSSProperties = {
+  fontWeight: "var(--font-weight-medium)" as never,
+  padding: 0,
+  marginBlockEnd: "var(--space-1)",
+  fontSize: "var(--font-size-sm)",
+  color: "var(--color-neutral-700)",
+};
+const optionsStyle: CSSProperties = { display: "grid", gap: "var(--space-2)" };
+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 RadioProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "checked" | "defaultChecked" | "onChange" | "value"> {
+  label: UiText;
+  value: string;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onChange?: (checked: boolean) => void;
+}
+
+/** Token-styled labelled radio — usually rendered by {@link RadioGroup}. */
+export function Radio({ label, value, checked, defaultChecked, onChange, style, ...rest }: RadioProps) {
+  const resolve = useUiText();
+  return (
+    <label style={{ ...labelStyle, ...style }}>
+      <input
+        {...rest}
+        type="radio"
+        data-terp="radio"
+        value={value}
+        checked={checked}
+        defaultChecked={defaultChecked}
+        onChange={(event) => onChange?.(event.currentTarget.checked)}
+        style={inputStyle}
+      />
+      <span>{resolve(label)}</span>
+    </label>
+  );
+}
+
+export interface RadioOption {
+  value: string;
+  label: UiText;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+  label: UiText;
+  name?: string;
+  options?: readonly RadioOption[];
+  children?: ReactNode;
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  disabled?: boolean;
+}
+
+/** Accessible token-styled radio group; pass `options` for the standard generated radios. */
+export function RadioGroup({
+  label,
+  name,
+  options,
+  children,
+  value,
+  defaultValue,
+  onChange,
+  disabled = false,
+}: RadioGroupProps) {
+  const generatedName = useId();
+  const resolve = useUiText();
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? "");
+  const selected = value ?? uncontrolledValue;
+  const groupName = name ?? generatedName;
+
+  function select(next: string) {
+    if (value === undefined) {
+      setUncontrolledValue(next);
+    }
+    onChange?.(next);
+  }
+
+  return (
+    <fieldset style={groupStyle}>
+      <legend style={legendStyle}>{resolve(label)}</legend>
+      <div style={optionsStyle}>
+        {options?.map((option) => (
+          <Radio
+            key={option.value}
+            name={groupName}
+            value={option.value}
+            label={option.label}
+            checked={selected === option.value}
+            disabled={disabled || option.disabled}
+            onChange={(checked) => {
+              if (checked) {
+                select(option.value);
+              }
+            }}
+          />
+        ))}
+        {children}
+      </div>
+    </fieldset>
+  );
+}