@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/switch/react/Switch.tsx

@@ -0,0 +1,219 @@
+"use client";
+
+import {
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type ChangeEventHandler,
+  type InputHTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { describeField } from "../../shared/core/field";
+import { adopt, idleToggle, request, settle } from "../core/toggle";
+import type { SwitchLabelPosition, SwitchLocaleText, SwitchSize } from "../core/types";
+import { defaultSwitchText } from "./locale";
+import { cx, type SwitchSlot } from "./props";
+
+export interface SwitchProps
+  extends Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "type" | "size" | "checked" | "defaultChecked" | "onChange" | "role"
+  > {
+  /** On or off (controlled). */
+  checked?: boolean;
+  defaultChecked?: boolean;
+  /**
+   * Fires with the new state. Return a promise and the switch stays on the new
+   * setting with a busy indicator until it resolves, then puts itself back if
+   * it rejects — see [Saving](#saving).
+   */
+  onCheckedChange?(checked: boolean): void | Promise<unknown>;
+  onChange?: ChangeEventHandler<HTMLInputElement>;
+  /** Posted with the form when the switch is on. Default `"on"`, as for a checkbox. */
+  value?: string;
+  label?: ReactNode;
+  description?: ReactNode;
+  error?: ReactNode;
+  size?: SwitchSize;
+  /** Default `end`: the label after the track. `start` puts the track on the right, for settings rows. */
+  labelPosition?: SwitchLabelPosition;
+  /** Show the busy state and block presses from outside, e.g. while a form saves. */
+  loading?: boolean;
+  classNames?: Partial<Record<SwitchSlot, string>>;
+  localeText?: Partial<SwitchLocaleText>;
+  /** The `<input>` element. */
+  ref?: Ref<HTMLInputElement>;
+}
+
+/**
+ * A native checkbox with `role="switch"`, styled as a track and thumb. It posts
+ * with forms, works with form libraries, and is announced as "on"/"off" rather
+ * than "checked", which is what a setting that takes effect immediately should
+ * say.
+ */
+export function Switch(props: SwitchProps) {
+  const {
+    ref,
+    checked: checkedProp,
+    defaultChecked = false,
+    onCheckedChange,
+    onChange,
+    onKeyDown,
+    value,
+    label,
+    description,
+    error,
+    size = "md",
+    labelPosition = "end",
+    loading = false,
+    className,
+    classNames,
+    style,
+    localeText,
+    id: idProp,
+    disabled,
+    readOnly,
+    required,
+    name,
+    "aria-describedby": describedByProp,
+    ...inputProps
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultSwitchText, ...localeText }), [localeText]);
+  const inputRef = useRef<HTMLInputElement>(null);
+  useImperativeHandle(ref, () => inputRef.current as HTMLInputElement, []);
+
+  const [state, setState] = useState(() => idleToggle(checkedProp ?? defaultChecked));
+  const controlled = checkedProp !== undefined;
+
+  // A controlled value is the truth, and a new one ends anything still in
+  // flight. Adjusted while rendering rather than in an effect, so the switch
+  // never paints the old setting for a frame first.
+  const [seen, setSeen] = useState(checkedProp);
+  if (checkedProp !== seen) {
+    setSeen(checkedProp);
+    if (checkedProp !== undefined) setState((current) => adopt(current, checkedProp));
+  }
+
+  // Between changes the prop wins outright, so a parent that declines a change
+  // — by not updating the value it passed — puts the switch back by itself.
+  const checked = controlled && state.pending === null ? checkedProp : state.checked;
+  const saving = state.pending !== null || loading;
+  const locked = Boolean(disabled) || readOnly === true || saving;
+
+  const change = useCallback(
+    (next: boolean) => {
+      const result = onCheckedChange?.(next);
+      // Only a thenable turns the switch busy; a plain handler is done already.
+      if (typeof (result as Promise<unknown> | undefined)?.then !== "function") {
+        setState((current) => settle(request(current, next), next, true));
+        return;
+      }
+      setState((current) => request(current, next));
+      void (result as Promise<unknown>).then(
+        () => setState((current) => settle(current, next, true)),
+        () => setState((current) => settle(current, next, false)),
+      );
+    },
+    [onCheckedChange],
+  );
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    if (locked) {
+      // readOnly does nothing on a checkbox, so the change has to be undone.
+      event.preventDefault();
+      event.target.checked = checked;
+      return;
+    }
+    onChange?.(event);
+    change(event.target.checked);
+  };
+
+  // The ARIA switch pattern: the arrows set a side rather than toggling.
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented || locked) return;
+    const rtl = event.currentTarget.matches(":dir(rtl)");
+    const on = rtl ? "ArrowLeft" : "ArrowRight";
+    const off = rtl ? "ArrowRight" : "ArrowLeft";
+    if (event.key !== on && event.key !== off) return;
+    event.preventDefault();
+    const next = event.key === on;
+    if (next !== checked) change(next);
+  };
+
+  const invalid = Boolean(error);
+  const describedBy = describeField(id, { extra: describedByProp, description, error });
+
+  return (
+    <div
+      className={cx("sw-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-label-position={labelPosition}
+      data-disabled={disabled || undefined}
+      data-readonly={readOnly || undefined}
+      data-saving={saving || undefined}
+      data-invalid={invalid ? "" : undefined}
+    >
+      <span className={cx("sw-control", classNames?.control)}>
+        <input
+          {...inputProps}
+          ref={inputRef}
+          id={id}
+          type="checkbox"
+          role="switch"
+          className={cx("sw-input", classNames?.input)}
+          checked={checked}
+          value={value}
+          name={name}
+          disabled={disabled}
+          required={required}
+          aria-readonly={readOnly || undefined}
+          aria-busy={saving || undefined}
+          aria-invalid={invalid || undefined}
+          aria-describedby={describedBy}
+          onChange={handleChange}
+          onKeyDown={handleKeyDown}
+        />
+        <span className={cx("sw-track", classNames?.track)} aria-hidden="true">
+          <span className={cx("sw-thumb", classNames?.thumb)} />
+        </span>
+      </span>
+
+      {(label || description || error) && (
+        <span className="sw-text">
+          {label && (
+            <label htmlFor={id} className={cx("sw-label", classNames?.label)} data-required={required || undefined}>
+              {label}
+            </label>
+          )}
+          {description && (
+            <span id={`${id}-description`} className={cx("sw-description", classNames?.description)}>
+              {description}
+            </span>
+          )}
+          {error && (
+            <span id={`${id}-error`} className={cx("sw-error", classNames?.error)} role="alert">
+              {error}
+            </span>
+          )}
+        </span>
+      )}
+
+      {/* Only the fact that something is being saved needs announcing; the
+          switch already reads its own new state. */}
+      <span className="sw-sr-only" role="status">
+        {saving ? text.saving : ""}
+      </span>
+    </div>
+  );
+}

package/source/components/switch/react/locale.ts

@@ -0,0 +1,5 @@
+import type { SwitchLocaleText } from "../core/types";
+
+export const defaultSwitchText: SwitchLocaleText = {
+  saving: "Saving\u2026",
+};

package/source/components/switch/react/props.ts

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

package/source/components/switch/styles.css

@@ -0,0 +1,227 @@
+/*
+ * Switch styles.
+ *
+ * The control is the native <input type="checkbox" role="switch"> with
+ * `appearance: none`, drawn as a track and a thumb, so it keeps native
+ * behavior and posts with forms. 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.
+ */
+
+.sw-root {
+  --sw-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --sw-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --sw-track: var(--gbs-subtle, light-dark(#d4d4d8, #3f3f46));
+  --sw-thumb: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #f4f4f5)));
+  --sw-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --sw-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --sw-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --sw-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --sw-height: 20px;
+  --sw-width: 36px;
+  --sw-gap: 3px;
+  --sw-duration: 160ms;
+
+  color-scheme: inherit;
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  min-width: 0;
+  font-size: var(--sw-font-size);
+  line-height: 1.4;
+  color: var(--sw-fg);
+}
+
+:where(.dark, [data-theme="dark"]) .sw-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .sw-root {
+  color-scheme: light;
+}
+
+:where(.sw-root) *,
+:where(.sw-root) *::before,
+:where(.sw-root) *::after {
+  box-sizing: border-box;
+}
+
+.sw-root[data-size="sm"] {
+  --sw-height: 16px;
+  --sw-width: 28px;
+  --sw-gap: 2px;
+  --sw-font-size: 12px;
+}
+.sw-root[data-size="lg"] {
+  --sw-height: 24px;
+  --sw-width: 44px;
+  --sw-font-size: 14px;
+}
+
+/* The label first, the track pushed to the far edge: a settings row. */
+.sw-root[data-label-position="start"] {
+  flex-direction: row-reverse;
+  justify-content: space-between;
+}
+
+/* -------------------------------------------------------------- control */
+
+.sw-control {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  /* Line the track up with the first line of the label. */
+  align-items: center;
+  height: calc(var(--sw-font-size) * 1.4);
+}
+
+.sw-input {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  appearance: none;
+  background: none;
+  cursor: pointer;
+}
+.sw-input:disabled {
+  cursor: not-allowed;
+}
+.sw-root[data-readonly] .sw-input {
+  cursor: default;
+}
+
+.sw-track {
+  display: inline-flex;
+  align-items: center;
+  width: var(--sw-width);
+  height: var(--sw-height);
+  padding: var(--sw-gap);
+  border-radius: 999px;
+  background: var(--sw-track);
+  transition: background-color var(--sw-duration) ease;
+}
+
+.sw-thumb {
+  width: calc(var(--sw-height) - var(--sw-gap) * 2);
+  height: calc(var(--sw-height) - var(--sw-gap) * 2);
+  border-radius: 50%;
+  background: var(--sw-thumb);
+  box-shadow: 0 1px 2px light-dark(rgb(0 0 0 / 0.25), rgb(0 0 0 / 0.5));
+  /* `translate` rather than `margin-inline-start`, so it animates on the
+     compositor and mirrors itself in right-to-left layouts. */
+  translate: 0;
+  transition: translate var(--sw-duration) ease;
+}
+
+.sw-input:checked + .sw-track {
+  background: var(--sw-accent);
+}
+.sw-input:checked + .sw-track .sw-thumb {
+  translate: calc(var(--sw-width) - var(--sw-height)) 0;
+}
+.sw-control:dir(rtl) .sw-input:checked + .sw-track .sw-thumb {
+  translate: calc((var(--sw-width) - var(--sw-height)) * -1) 0;
+}
+
+.sw-input:focus-visible + .sw-track {
+  outline: 2px solid var(--sw-focus);
+  outline-offset: 2px;
+}
+.sw-input:hover:not(:disabled) + .sw-track {
+  background: color-mix(in oklab, var(--sw-track) 88%, var(--sw-fg));
+}
+.sw-input:checked:hover:not(:disabled) + .sw-track {
+  background: color-mix(in oklab, var(--sw-accent) 88%, black);
+}
+
+.sw-root[data-invalid] .sw-track {
+  outline: 1px solid var(--sw-danger);
+  outline-offset: 1px;
+}
+/* Only the track dims; the label keeps its contrast, as the Checkbox's does. */
+.sw-input:disabled + .sw-track {
+  opacity: 0.5;
+}
+
+/* The thumb keeps turning while the change is being saved. */
+.sw-root[data-saving] .sw-thumb {
+  border: 2px solid transparent;
+  border-top-color: var(--sw-accent);
+  animation: sw-spin 700ms linear infinite;
+}
+.sw-root[data-saving] .sw-input {
+  cursor: progress;
+}
+
+@keyframes sw-spin {
+  to {
+    rotate: 1turn;
+  }
+}
+
+/* ----------------------------------------------------------------- text */
+
+.sw-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.sw-label {
+  font-weight: 500;
+  cursor: pointer;
+}
+.sw-root[data-disabled] .sw-label {
+  color: var(--sw-muted);
+  cursor: not-allowed;
+}
+.sw-label[data-required]::after {
+  content: " *";
+  color: var(--sw-danger);
+}
+.sw-description {
+  color: var(--sw-muted);
+  text-wrap: pretty;
+}
+.sw-error {
+  color: var(--sw-danger);
+  text-wrap: pretty;
+}
+
+.sw-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sw-root {
+    --sw-duration: 0s;
+  }
+  .sw-root[data-saving] .sw-thumb {
+    animation-duration: 2s;
+  }
+}
+
+@media (forced-colors: active) {
+  .sw-track {
+    border: 1px solid CanvasText;
+  }
+  .sw-input:checked + .sw-track {
+    background: Highlight;
+  }
+  .sw-thumb {
+    background: CanvasText;
+  }
+}

package/source/components/tabs/README.md

@@ -0,0 +1,32 @@
+# Tabs
+
+Accessible tabs for React 19 following the WAI-ARIA tabs pattern, styled to
+match the rest of the library. No runtime dependencies besides React.
+
+```ts
+import { Tab, TabList, TabPanel, Tabs } from "@/components/tabs";
+import "@/components/tabs/styles.css";
+```
+
+```tsx
+<Tabs defaultValue="overview">
+  <TabList aria-label="Project">
+    <Tab value="overview">Overview</Tab>
+    <Tab value="activity" badge={3}>Activity</Tab>
+    <Tab value="billing" disabled>Billing</Tab>
+  </TabList>
+  <TabPanel value="overview">…</TabPanel>
+  <TabPanel value="activity">…</TabPanel>
+</Tabs>
+```
+
+**Tabs:** `value` / `defaultValue` / `onValueChange`, `orientation`
+(`horizontal` `vertical`), `activation` (`automatic` `manual`), `variant` (`line`
+`pills` `enclosed`), `size`, `keepMounted`.
+**Tab:** `value`, `disabled`, `icon`, `badge`.
+**TabPanel:** `value`, `keepMounted`.
+
+Arrow keys move between tabs (swapped in right-to-left layouts), Home and End
+jump, and disabled tabs are skipped. `keepMounted` keeps hidden panels' state
+using React's `<Activity>`. `nextTab` and `tabDomId` are exported from the
+framework-free `core`.

package/source/components/tabs/core/index.ts

@@ -0,0 +1,3 @@
+// Framework-free: keyboard movement and ids for the tabs pattern.
+export { nextTab, tabDomId } from "./navigation";
+export type * from "./types";

package/source/components/tabs/core/navigation.ts

@@ -0,0 +1,54 @@
+import type { NavigationOptions } from "./types";
+
+/**
+ * The tab a key moves to, skipping disabled tabs, or null when the key isn't a
+ * tab key (or there is nowhere to go). Follows the WAI-ARIA tabs pattern.
+ */
+export function nextTab(
+  tabs: readonly { disabled?: boolean }[],
+  current: number,
+  key: string,
+  options: NavigationOptions = {},
+): number | null {
+  const { orientation = "horizontal", rtl = false, loop = true } = options;
+  const count = tabs.length;
+  if (count === 0) return null;
+
+  const horizontal = orientation === "horizontal";
+  const previousKey = horizontal ? (rtl ? "ArrowRight" : "ArrowLeft") : "ArrowUp";
+  const nextKey = horizontal ? (rtl ? "ArrowLeft" : "ArrowRight") : "ArrowDown";
+
+  const scan = (start: number, step: 1 | -1): number | null => {
+    let index = start;
+    for (let visited = 0; visited < count; visited++) {
+      if (index < 0 || index >= count) {
+        if (!loop) return null;
+        index = (index + count) % count;
+      }
+      if (!tabs[index].disabled) return index;
+      index += step;
+    }
+    return null;
+  };
+
+  switch (key) {
+    case nextKey:
+      return scan(current + 1, 1);
+    case previousKey:
+      return scan(current - 1, -1);
+    case "Home":
+      return scan(0, 1);
+    case "End":
+      return scan(count - 1, -1);
+    default:
+      return null;
+  }
+}
+
+/**
+ * A DOM id for a tab or panel. Values may contain spaces or symbols, so they are
+ * percent-encoded with `_` in place of `%`, which keeps different values distinct.
+ */
+export function tabDomId(base: string, part: "tab" | "panel", value: string): string {
+  return `${base}-${part}-${encodeURIComponent(value).replace(/[%.!~*'()]/g, "_")}`;
+}

package/source/components/tabs/core/types.ts

@@ -0,0 +1,16 @@
+export type TabsOrientation = "horizontal" | "vertical";
+
+/** `automatic` selects a tab as soon as it gets focus; `manual` waits for Enter or Space. */
+export type TabsActivation = "automatic" | "manual";
+
+export type TabsVariant = "line" | "pills" | "enclosed";
+
+export type TabsSize = "sm" | "md" | "lg";
+
+export interface NavigationOptions {
+  orientation?: TabsOrientation;
+  /** Right-to-left: the horizontal arrow keys swap. */
+  rtl?: boolean;
+  /** Wrap from the last tab to the first. Default true. */
+  loop?: boolean;
+}

package/source/components/tabs/index.ts

@@ -0,0 +1,5 @@
+export { Tab, TabList, TabPanel, Tabs } from "./react/Tabs";
+export type { TabListProps, TabPanelProps, TabProps, TabsProps } from "./react/Tabs";
+export { TabsContext, useTabsContext } from "./react/context";
+export type { TabsContextValue } from "./react/context";
+export * from "./core";