@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/radio-group/react/Radio.tsx

@@ -0,0 +1,144 @@
+"use client";
+
+import {
+  use,
+  useId,
+  useImperativeHandle,
+  useRef,
+  type ChangeEvent,
+  type ChangeEventHandler,
+  type InputHTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { describeField } from "../../shared/core/field";
+import type { RadioSize } from "../core/types";
+import { RadioGroupContext } from "./context";
+import { cx, type RadioSlot } from "./props";
+
+export interface RadioProps
+  extends Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "type" | "size" | "checked" | "defaultChecked" | "onChange"
+  > {
+  /** The value this choice contributes to its group. */
+  value: string;
+  /** Selected (controlled). Inside a RadioGroup the group decides instead. */
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?(checked: boolean): void;
+  onChange?: ChangeEventHandler<HTMLInputElement>;
+  label?: ReactNode;
+  description?: ReactNode;
+  error?: ReactNode;
+  size?: RadioSize;
+  classNames?: Partial<Record<RadioSlot, string>>;
+  /** The `<input>` element. */
+  ref?: Ref<HTMLInputElement>;
+}
+
+/**
+ * One choice, as a native radio. Inside a `RadioGroup` the group owns the
+ * value; on its own it behaves like any other radio sharing a `name`.
+ *
+ * Nothing here manages focus: radios that share a `name` already roam with the
+ * arrow keys, skip the disabled ones, wrap around and leave one tab stop for
+ * the whole group — in every browser, and without JavaScript.
+ */
+export function Radio(props: RadioProps) {
+  const {
+    ref,
+    value,
+    checked: checkedProp,
+    defaultChecked = false,
+    onCheckedChange,
+    onChange,
+    label,
+    description,
+    error,
+    size,
+    className,
+    classNames,
+    style,
+    id: idProp,
+    disabled,
+    required,
+    name,
+    "aria-describedby": describedByProp,
+    ...inputProps
+  } = props;
+
+  const group = use(RadioGroupContext);
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const inputRef = useRef<HTMLInputElement>(null);
+  useImperativeHandle(ref, () => inputRef.current as HTMLInputElement, []);
+
+  const [own, setOwn] = useControllableState(checkedProp, defaultChecked);
+  const checked = group !== null ? group.value === value : own;
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    if (group !== null) group.select(value);
+    else setOwn(event.target.checked);
+    onChange?.(event);
+    onCheckedChange?.(event.target.checked);
+  };
+
+  const isDisabled = disabled ?? group?.disabled;
+  const invalid = Boolean(error) || (group?.invalid ?? false);
+  const describedBy = describeField(id, { extra: describedByProp, description, error });
+
+  return (
+    <div
+      className={cx("rd-root", classNames?.root, className)}
+      style={style}
+      data-size={size ?? group?.size ?? "md"}
+      data-variant={group?.variant ?? "default"}
+      data-checked={checked || undefined}
+      data-disabled={isDisabled || undefined}
+      data-invalid={invalid ? "" : undefined}
+    >
+      <span className={cx("rd-control", classNames?.control)}>
+        <input
+          {...inputProps}
+          ref={inputRef}
+          id={id}
+          type="radio"
+          className={cx("rd-input", classNames?.input)}
+          checked={checked}
+          value={value}
+          name={name ?? group?.name}
+          disabled={isDisabled}
+          // Every radio in a group carries `required`, which is how a browser
+          // validates the group as a whole rather than one button in it.
+          required={required ?? group?.required}
+          aria-invalid={invalid || undefined}
+          aria-describedby={describedBy}
+          onChange={handleChange}
+        />
+        <span className="rd-dot" aria-hidden="true" />
+      </span>
+
+      {(label || description || error) && (
+        <span className="rd-text">
+          {label && (
+            <label htmlFor={id} className={cx("rd-label", classNames?.label)}>
+              {label}
+            </label>
+          )}
+          {description && (
+            <span id={`${id}-description`} className={cx("rd-description", classNames?.description)}>
+              {description}
+            </span>
+          )}
+          {error && (
+            <span id={`${id}-error`} className={cx("rd-error", classNames?.error)} role="alert">
+              {error}
+            </span>
+          )}
+        </span>
+      )}
+    </div>
+  );
+}

package/source/components/radio-group/react/RadioGroup.tsx

@@ -0,0 +1,179 @@
+"use client";
+
+import { useCallback, useId, useMemo, type CSSProperties, type ReactNode } from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { describeField } from "../../shared/core/field";
+import { hasEnabledOption, normalizeOptions, resolveValue } from "../core/group";
+import type {
+  RadioGroupLocaleText,
+  RadioOption,
+  RadioOrientation,
+  RadioSize,
+  RadioVariant,
+} from "../core/types";
+import { Radio } from "./Radio";
+import { RadioGroupContext, type RadioGroupContextValue } from "./context";
+import { defaultRadioGroupText } from "./locale";
+import { cx, type RadioGroupSlot } from "./props";
+
+export interface RadioGroupProps {
+  /** The chosen value (controlled). `null` for nothing chosen. */
+  value?: string | null;
+  defaultValue?: string | null;
+  onValueChange?(value: string | null): void;
+  /** Render these choices, or pass `<Radio value="…">` children. Plain strings work too. */
+  options?: readonly (string | RadioOption)[];
+  children?: ReactNode;
+  /** The question the choices answer, shown as the group's legend. */
+  label?: ReactNode;
+  description?: ReactNode;
+  error?: ReactNode;
+  required?: boolean;
+  disabled?: boolean;
+  /** Form field name shared by every radio. One is generated when it is left out. */
+  name?: string;
+  size?: RadioSize;
+  /** Default `vertical`. */
+  orientation?: RadioOrientation;
+  /** Default `default`. `card` draws each choice as a tile. */
+  variant?: RadioVariant;
+  /**
+   * Offer a button that empties the group. Radios cannot be unselected by
+   * clicking or by keyboard — that is the control's nature, not an oversight —
+   * so an optional choice needs either this or a "None" option of its own.
+   */
+  clearable?: boolean;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<RadioGroupSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<RadioGroupLocaleText>;
+}
+
+/** A labelled set of radios sharing one value. */
+export function RadioGroup(props: RadioGroupProps) {
+  const {
+    value,
+    defaultValue,
+    onValueChange,
+    options,
+    children,
+    label,
+    description,
+    error,
+    required = false,
+    disabled = false,
+    name: nameProp,
+    size,
+    orientation = "vertical",
+    variant = "default",
+    clearable = false,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  // Radios are grouped by their name, so one is needed whether or not the
+  // group posts with a form: without it, two groups on a page share arrows.
+  const name = nameProp ?? `${id}-radio`;
+  const text = useMemo(() => ({ ...defaultRadioGroupText, ...localeText }), [localeText]);
+  const [current, setCurrent] = useControllableState<string | null>(value, defaultValue ?? null);
+
+  const items = useMemo(() => (options ? normalizeOptions(options) : null), [options]);
+  // With children rather than options there is nothing to check the value
+  // against, so it is taken as given.
+  const selected = items ? resolveValue(items, current) : (current ?? null);
+
+  const commit = useCallback(
+    (next: string | null) => {
+      setCurrent(next);
+      onValueChange?.(next);
+    },
+    [setCurrent, onValueChange],
+  );
+
+  const context = useMemo<RadioGroupContextValue>(
+    () => ({
+      value: selected,
+      select: commit,
+      name,
+      disabled,
+      required,
+      invalid: Boolean(error),
+      size,
+      variant,
+    }),
+    [selected, commit, name, disabled, required, error, size, variant],
+  );
+
+  const showClear = clearable && selected !== null && hasEnabledOption(items ?? [], disabled);
+  const describedBy = describeField(id, { description, error });
+
+  return (
+    <fieldset
+      id={id}
+      className={cx("rd-group", classNames?.root, className)}
+      style={style}
+      // A disabled fieldset disables every control inside it natively.
+      disabled={disabled}
+      // A fieldset is a plain group by default, which is right for checkboxes
+      // and wrong here: a set of radios is one control with one value, and
+      // screen readers say so and count the choices ("2 of 3") only for
+      // radiogroup. The legend is repeated as the name, because overriding the
+      // role is not guaranteed to carry a fieldset's own naming with it.
+      role="radiogroup"
+      aria-labelledby={label ? `${id}-legend` : undefined}
+      aria-describedby={describedBy}
+      data-orientation={orientation}
+      data-variant={variant}
+      data-invalid={error ? "" : undefined}
+    >
+      {label && (
+        <legend id={`${id}-legend`} className={cx("rd-legend", classNames?.legend)} data-required={required || undefined}>
+          {label}
+        </legend>
+      )}
+      {description && (
+        <span id={`${id}-description`} className={cx("rd-description", classNames?.description)}>
+          {description}
+        </span>
+      )}
+
+      <RadioGroupContext value={context}>
+        <div className={cx("rd-items", classNames?.items)}>
+          {items
+            ? items.map((option) => (
+                <Radio
+                  key={option.value}
+                  value={option.value}
+                  label={option.label}
+                  description={option.description}
+                  disabled={option.disabled}
+                />
+              ))
+            : children}
+        </div>
+      </RadioGroupContext>
+
+      {showClear && (
+        <button
+          type="button"
+          className={cx("rd-clear", classNames?.clear)}
+          onClick={() => commit(null)}
+        >
+          {text.clear}
+        </button>
+      )}
+
+      {error && (
+        <span id={`${id}-error`} className={cx("rd-error", classNames?.error)} role="alert">
+          {error}
+        </span>
+      )}
+    </fieldset>
+  );
+}

package/source/components/radio-group/react/context.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { createContext } from "react";
+import type { RadioSize, RadioVariant } from "../core/types";
+
+export interface RadioGroupContextValue {
+  value: string | null;
+  select(value: string): void;
+  name: string;
+  disabled: boolean;
+  required: boolean;
+  invalid: boolean;
+  size?: RadioSize;
+  variant: RadioVariant;
+}
+
+/** Lets each Radio inside a RadioGroup read the group's value and change it. */
+export const RadioGroupContext = createContext<RadioGroupContextValue | null>(null);

package/source/components/radio-group/react/locale.ts

@@ -0,0 +1,5 @@
+import type { RadioGroupLocaleText } from "../core/types";
+
+export const defaultRadioGroupText: RadioGroupLocaleText = {
+  clear: "Clear",
+};

package/source/components/radio-group/react/props.ts

@@ -0,0 +1,12 @@
+export type RadioSlot =
+  | "root"
+  | "control"
+  | "input"
+  | "label"
+  | "description"
+  | "error";
+
+export type RadioGroupSlot = "root" | "legend" | "description" | "items" | "clear" | "error";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/radio-group/styles.css

@@ -0,0 +1,269 @@
+/*
+ * Radio and RadioGroup styles.
+ *
+ * The button is the native <input type="radio"> with `appearance: none`, so it
+ * keeps native behavior: arrow keys roam the group, one tab stop, and the
+ * whole group validates as one required field. Tokens read the shared --gbs-*
+ * variables when they are set on an ancestor (set them on :root to theme every
+ * component at once). Rules are unlayered: they beat a framework reset on
+ * specificity, and lose to anything you pass through `className`. With
+ * Tailwind v4, import this file after the framework and inside its components
+ * layer - see the README.
+ */
+
+.rd-root,
+.rd-group {
+  --rd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --rd-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --rd-border: var(--gbs-border-control, light-dark(#a1a1aa, #52525b));
+  --rd-card-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --rd-input-bg: var(--gbs-input-bg, var(--dg-input-bg, light-dark(#ffffff, #121216)));
+  --rd-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --rd-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --rd-accent-soft: var(--gbs-accent-soft, var(--dg-accent-soft, light-dark(#eff6ff, #172554)));
+  --rd-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --rd-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --rd-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --rd-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --rd-size: 16px;
+
+  color-scheme: inherit;
+  font-size: var(--rd-font-size);
+  line-height: 1.4;
+  color: var(--rd-fg);
+}
+
+:where(.dark, [data-theme="dark"]) :is(.rd-root, .rd-group) {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) :is(.rd-root, .rd-group) {
+  color-scheme: light;
+}
+
+:where(.rd-root, .rd-group) *,
+:where(.rd-root, .rd-group) *::before,
+:where(.rd-root, .rd-group) *::after {
+  box-sizing: border-box;
+}
+
+/* ---------------------------------------------------------------- radio */
+
+.rd-root {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  min-width: 0;
+}
+.rd-root[data-size="sm"] {
+  --rd-size: 14px;
+  --rd-font-size: 12px;
+}
+.rd-root[data-size="lg"] {
+  --rd-size: 20px;
+  --rd-font-size: 14px;
+}
+
+.rd-control {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  /* Line the button up with the first line of the label. */
+  height: calc(var(--rd-font-size) * 1.4);
+}
+
+.rd-input {
+  width: var(--rd-size);
+  height: var(--rd-size);
+  margin: 0;
+  border: 1px solid var(--rd-border);
+  border-radius: 50%;
+  appearance: none;
+  background: var(--rd-input-bg);
+  cursor: pointer;
+  transition:
+    border-color 120ms ease,
+    background-color 120ms ease;
+}
+.rd-input:hover:not(:disabled) {
+  border-color: var(--rd-accent);
+}
+.rd-input:checked {
+  border-color: var(--rd-accent);
+  border-width: 2px;
+}
+.rd-input:focus-visible {
+  outline: 2px solid var(--rd-focus);
+  outline-offset: 2px;
+}
+
+/* The dot is a separate element rather than a border trick, so its size can
+   follow the control's and it can animate in. */
+.rd-dot {
+  position: absolute;
+  width: calc(var(--rd-size) / 2);
+  height: calc(var(--rd-size) / 2);
+  border-radius: 50%;
+  background: var(--rd-accent);
+  scale: 0;
+  transition: scale 120ms ease;
+  pointer-events: none;
+}
+.rd-input:checked ~ .rd-dot {
+  scale: 1;
+}
+
+.rd-root[data-invalid] .rd-input {
+  border-color: var(--rd-danger);
+}
+/* Only the button dims. Fading the whole choice takes its label below the
+   contrast floor, and someone still has to be able to read the option they
+   cannot pick. */
+.rd-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.rd-root[data-disabled] .rd-dot {
+  opacity: 0.5;
+}
+
+.rd-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.rd-label {
+  font-weight: 500;
+  cursor: pointer;
+}
+.rd-root[data-disabled] .rd-label {
+  color: var(--rd-muted);
+  cursor: not-allowed;
+}
+.rd-description {
+  color: var(--rd-muted);
+  text-wrap: pretty;
+}
+.rd-error {
+  color: var(--rd-danger);
+  text-wrap: pretty;
+}
+
+/* ----------------------------------------------------------------- card */
+
+.rd-root[data-variant="card"] {
+  position: relative;
+  align-items: flex-start;
+  padding: 12px;
+  border: 1px solid var(--rd-card-border);
+  border-radius: var(--rd-radius);
+  background: var(--rd-input-bg);
+  cursor: pointer;
+  transition:
+    border-color 120ms ease,
+    background-color 120ms ease;
+}
+.rd-root[data-variant="card"]:hover:not([data-disabled]) {
+  background: var(--rd-hover);
+}
+.rd-root[data-variant="card"][data-checked] {
+  border-color: var(--rd-accent);
+  background: var(--rd-accent-soft);
+}
+/* Muted grey clears 4.5:1 on white but only reaches 4.44:1 on the tinted
+   background of a selected card, so it moves a step towards the text colour
+   there rather than the description quietly failing contrast. */
+.rd-root[data-variant="card"][data-checked] .rd-description {
+  color: color-mix(in oklab, var(--rd-muted) 72%, var(--rd-fg));
+}
+/* The whole tile is the target: the input covers it, so a press anywhere
+   lands on the radio itself rather than on a label that forwards it. */
+.rd-root[data-variant="card"] .rd-input::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: var(--rd-radius);
+}
+.rd-root[data-variant="card"]:has(.rd-input:focus-visible) {
+  outline: 2px solid var(--rd-focus);
+  outline-offset: 2px;
+}
+.rd-root[data-variant="card"] .rd-input:focus-visible {
+  outline: none;
+}
+
+/* ---------------------------------------------------------------- group */
+
+.rd-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.rd-legend {
+  padding: 0;
+  font-weight: 500;
+}
+.rd-legend[data-required]::after {
+  content: " *";
+  color: var(--rd-danger);
+}
+
+.rd-items {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 0;
+}
+.rd-group[data-orientation="horizontal"] .rd-items {
+  flex-flow: row wrap;
+  gap: 16px;
+}
+.rd-group[data-variant="card"][data-orientation="horizontal"] .rd-items {
+  gap: 8px;
+}
+.rd-group[data-variant="card"][data-orientation="horizontal"] .rd-root {
+  flex: 1 1 180px;
+}
+
+.rd-clear {
+  align-self: flex-start;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--rd-accent);
+  font: inherit;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+.rd-clear:focus-visible {
+  outline: 2px solid var(--rd-focus);
+  outline-offset: 2px;
+  border-radius: 3px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rd-input,
+  .rd-dot,
+  .rd-root[data-variant="card"] {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .rd-input {
+    border: 1px solid CanvasText;
+  }
+  .rd-dot {
+    background: Highlight;
+  }
+  .rd-root[data-variant="card"][data-checked] {
+    border-color: Highlight;
+  }
+}

package/source/components/shared/README.md

@@ -0,0 +1,54 @@
+# Shared
+
+The small amount of code every component needs. It is not a component and is
+not chosen from the installer's list: `shared/` is copied into `component-lib/`
+with any install, and each component reaches it at exactly `../../shared/…`.
+
+```ts
+import { cx } from "../../shared/core/cx";
+import { describeField } from "../../shared/core/field";
+import { AnchoredPopover } from "../../shared/react/Popover";
+```
+
+| Export | Where | What it is |
+| --- | --- | --- |
+| `cx(...names)` | `core/cx` | Joins class names, dropping anything falsy. |
+| `countCharacters(value)` | `core/text` | Grapheme-accurate length for character counters. |
+| `describeField(id, parts)` | `core/field` | The `aria-describedby` for a control, from its hint, description and error. |
+| `useControllableState(value, default)` | `react/useControllableState` | One value that may be controlled or owned by the component. |
+| `AnchoredPopover` | `react/Popover` | Anchored popover on the native Popover API: top layer, light dismiss, flipping. |
+| `Svg` and the shared glyphs | `react/icons` | The icon base, plus every glyph more than one component draws. |
+
+`core/` is framework-free and `react/` is `"use client"`, the same split every
+component uses.
+
+## The rules
+
+**Only `shared/` is shared.** A component never imports another component: each
+is copied into a project on its own, so a sibling it reached for might not be
+there. `__tests__/boundaries.test.ts` enforces this, along with the ban on
+third-party imports.
+
+**`shared/` never imports a component.** It has to stand on its own, and a
+back-edge would make the folder uninstallable without the component it points
+at.
+
+**Changes here are additive.** Installing a component overwrites `shared/` with
+the version that component was built against, and the other components already
+in the project keep running against it. So add exports, add optional parameters,
+and leave existing signatures alone; if something genuinely has to change shape,
+ship it under a new name. `version.ts` and `version.json` are bumped together on
+every change, and the installer compares them to refuse a downgrade.
+
+**Nothing component-specific.** A hook only one component uses belongs in that
+component, where it can change freely. This folder is for what is provably
+duplicated: a shape drawn by two components, a rule two controls must agree on.
+
+## What deliberately stays out
+
+`useCombobox`, `useDatePicker` and the grid's state live with their components:
+they are the component, not a primitive. The grid also keeps its own controlled
+state, because it is one object of nine independent slices rather than a single
+value, and `useControllableState` would obscure more than it saved. A component
+inside a `CheckboxGroup` defers to the group instead, and only falls back to
+`useControllableState` when it stands alone.