@lab206/ui 0.1.0

package/src/index.ts

@@ -0,0 +1,243 @@
+/**
+ * @lab206/ui — integrated design system (styling + components)
+ *
+ * Layers: tokens → primitives → optional utilities (see docs/STYLING.md)
+ *
+ * 1. import "@lab206/ui/theme.css"   // tokens + base + utilities
+ * 2. createTheme().bind(); createDensity().bind();
+ * 3. Use Button, Field, Stack… (prefer primitives over raw utilities)
+ * 4. Forms: <Input bind={signal} /> + Field error={…} — see docs/USABILITY.md
+ *
+ * Edit brand in: packages/ui/src/styles/tokens.css
+ * Author new primitives: createStyleSheet + component() — see docs/COMPONENTS.md
+ * Public docs hub: docs/README.md
+ */
+
+export { createTheme } from "./theme.js";
+export type { ThemeMode, ThemeController } from "./theme.js";
+
+export { createDensity } from "./density.js";
+export type { Density, DensityController } from "./density.js";
+
+export { createPalette } from "./palette.js";
+export type { PaletteId, PaletteController } from "./palette.js";
+
+export { cx, puId } from "./utils.js";
+
+export { createStyleSheet, styleVars } from "./styles.js";
+export {
+  readProp,
+  readBool,
+  readStr,
+  readNum,
+  type MaybeReactive,
+} from "./reactive.js";
+export { trapFocus } from "./focusTrap.js";
+export { attachOverlay } from "./overlay.js";
+export type { OverlayAttachOptions, OverlayContext } from "./overlay.js";
+export {
+  listRovingItems,
+  applyRovingTabIndex,
+  focusRovingItem,
+  handleRovingKeydown,
+  initRovingFocus,
+} from "./rovingFocus.js";
+export type { RovingKeyOptions } from "./rovingFocus.js";
+
+export {
+  firstError,
+  required,
+  minLength,
+  maxLength,
+  emailFormat,
+  matches,
+  validateForm,
+  eventValue,
+  eventChecked,
+  bindInput,
+  bindString,
+  bindSelect,
+  bindChecked,
+  asSelectBind,
+  createField,
+} from "./form.js";
+export type {
+  FieldError,
+  Bindable,
+  FieldHandle,
+  CreateFieldOptions,
+} from "./form.js";
+
+export { MOTION_PRESETS, motionVars } from "./motion.js";
+export type { MotionPreset, MotionPresetName } from "./motion.js";
+
+export {
+  devWarnOnce,
+  warnIfThemeMissing,
+  warnPossibleSnapshotValue,
+  setDevWarnings,
+  installDevWarnings,
+} from "./dev.js";
+
+// —— Layout ——
+export { Stack } from "./components/Stack.js";
+export type { StackProps } from "./components/Stack.js";
+
+export { Grid } from "./components/Grid.js";
+export type { GridProps } from "./components/Grid.js";
+
+export { Container } from "./components/Container.js";
+export type { ContainerProps } from "./components/Container.js";
+
+export { Divider } from "./components/Divider.js";
+export type { DividerProps } from "./components/Divider.js";
+
+export { AspectRatio } from "./components/AspectRatio.js";
+export type { AspectRatioProps } from "./components/AspectRatio.js";
+
+export { ScrollArea } from "./components/ScrollArea.js";
+export type { ScrollAreaProps } from "./components/ScrollArea.js";
+
+export { Collapse } from "./components/Collapse.js";
+export type { CollapseProps } from "./components/Collapse.js";
+
+// —— Type ——
+export { Text } from "./components/Text.js";
+export type { TextProps } from "./components/Text.js";
+
+export { Code } from "./components/Code.js";
+export type { CodeProps } from "./components/Code.js";
+
+export { Kbd } from "./components/Kbd.js";
+export type { KbdProps } from "./components/Kbd.js";
+
+export { Link } from "./components/Link.js";
+export type { LinkProps } from "./components/Link.js";
+
+// —— Forms ——
+export { Button } from "./components/Button.js";
+export type { ButtonProps, ButtonVariant, ButtonSize } from "./components/Button.js";
+
+export { Input } from "./components/Input.js";
+export type { InputProps } from "./components/Input.js";
+
+export { Textarea } from "./components/Textarea.js";
+export type { TextareaProps } from "./components/Textarea.js";
+
+export { Select } from "./components/Select.js";
+export type { SelectProps, SelectOption } from "./components/Select.js";
+
+export { Label } from "./components/Label.js";
+export type { LabelProps } from "./components/Label.js";
+
+export { Field } from "./components/Field.js";
+export type { FieldProps } from "./components/Field.js";
+
+export { Switch } from "./components/Switch.js";
+export type { SwitchProps } from "./components/Switch.js";
+
+export { Checkbox } from "./components/Checkbox.js";
+export type { CheckboxProps } from "./components/Checkbox.js";
+
+export { RadioGroup } from "./components/Radio.js";
+export type { RadioGroupProps, RadioOption } from "./components/Radio.js";
+
+export { Slider } from "./components/Slider.js";
+export type { SliderProps } from "./components/Slider.js";
+
+export { NumberInput } from "./components/NumberInput.js";
+export type { NumberInputProps } from "./components/NumberInput.js";
+
+export { ToggleGroup } from "./components/ToggleGroup.js";
+export type { ToggleGroupProps, ToggleOption } from "./components/ToggleGroup.js";
+
+export { Combobox } from "./components/Combobox.js";
+export type { ComboboxProps, ComboboxOption } from "./components/Combobox.js";
+
+// —— Surfaces & chrome ——
+export { Card } from "./components/Card.js";
+export type { CardProps } from "./components/Card.js";
+
+export { Badge } from "./components/Badge.js";
+export type { BadgeProps } from "./components/Badge.js";
+
+export { Chip } from "./components/Chip.js";
+export type { ChipProps, ChipTone } from "./components/Chip.js";
+
+export { Avatar } from "./components/Avatar.js";
+export type { AvatarProps, AvatarSize } from "./components/Avatar.js";
+
+// —— Feedback ——
+export { Alert } from "./components/Alert.js";
+export type { AlertProps, AlertTone } from "./components/Alert.js";
+
+export { Spinner } from "./components/Spinner.js";
+export type { SpinnerProps, SpinnerSize } from "./components/Spinner.js";
+
+export { Progress } from "./components/Progress.js";
+export type { ProgressProps } from "./components/Progress.js";
+
+export { Skeleton } from "./components/Skeleton.js";
+export type { SkeletonProps } from "./components/Skeleton.js";
+
+export { Empty } from "./components/Empty.js";
+export type { EmptyProps } from "./components/Empty.js";
+
+export { Stat } from "./components/Stat.js";
+export type { StatProps } from "./components/Stat.js";
+
+export { Toaster, createToaster } from "./components/Toast.js";
+export type {
+  ToasterProps,
+  ToastController,
+  ToastItem,
+  ToastTone,
+} from "./components/Toast.js";
+
+// —— Navigation & structure ——
+export { Tabs } from "./components/Tabs.js";
+export type { TabsProps, TabItem } from "./components/Tabs.js";
+
+export { Accordion } from "./components/Accordion.js";
+export type { AccordionProps, AccordionItem } from "./components/Accordion.js";
+
+export { Breadcrumb } from "./components/Breadcrumb.js";
+export type { BreadcrumbProps, BreadcrumbItem } from "./components/Breadcrumb.js";
+
+export { Pagination } from "./components/Pagination.js";
+export type { PaginationProps } from "./components/Pagination.js";
+
+export { Steps } from "./components/Steps.js";
+export type { StepsProps, StepItem } from "./components/Steps.js";
+
+export { Timeline } from "./components/Timeline.js";
+export type { TimelineProps, TimelineItem } from "./components/Timeline.js";
+
+export { List } from "./components/List.js";
+export type { ListProps, ListItemData } from "./components/List.js";
+
+export { Table } from "./components/Table.js";
+export type { TableProps, TableColumn } from "./components/Table.js";
+
+// —— Overlays ——
+export { Dialog } from "./components/Dialog.js";
+export type { DialogProps } from "./components/Dialog.js";
+
+export { Drawer } from "./components/Drawer.js";
+export type { DrawerProps } from "./components/Drawer.js";
+
+export { Tooltip } from "./components/Tooltip.js";
+export type { TooltipProps } from "./components/Tooltip.js";
+
+export { Popover } from "./components/Popover.js";
+export type { PopoverProps } from "./components/Popover.js";
+
+export { Menu } from "./components/Menu.js";
+export type { MenuProps, MenuItem } from "./components/Menu.js";
+
+export { Command } from "./components/Command.js";
+export type { CommandProps, CommandItem } from "./components/Command.js";
+
+// —— Motion ——
+export { Transition } from "./components/Transition.js";
+export type { TransitionProps } from "./components/Transition.js";

package/src/motion.ts

@@ -0,0 +1,62 @@
+/**
+ * Motion language — named enter/exit class presets for Transition / CSS.
+ *
+ * Use with `<Transition name="pu-fade" show={…}>` or apply classes yourself.
+ * All presets respect `prefers-reduced-motion` via Transition's built-in CSS
+ * and global base.css rules.
+ */
+
+export type MotionPreset = {
+  /** Class prefix for Transition `name` prop */
+  name: string;
+  /** Human label */
+  label: string;
+  /** When to use */
+  use: string;
+  /** Suggested duration ms */
+  duration: number;
+};
+
+/** Built-in Transition names shipped in Transition.tsx styles. */
+export const MOTION_PRESETS: readonly MotionPreset[] = [
+  {
+    name: "pu-fade",
+    label: "Fade",
+    use: "Default enter/exit for overlays, panels, soft content swaps",
+    duration: 220,
+  },
+  {
+    name: "pu-collapse",
+    label: "Collapse",
+    use: "Accordion-like height expand/collapse (max-height)",
+    duration: 360,
+  },
+] as const;
+
+export type MotionPresetName = (typeof MOTION_PRESETS)[number]["name"];
+
+/**
+ * CSS custom-property recipe for one-off motion on a node
+ * (pair with your own transition: rules).
+ */
+export function motionVars(opts: {
+  duration?: string | number;
+  ease?: "out" | "spring" | "default";
+}): Record<string, string> {
+  const duration =
+    opts.duration == null
+      ? "var(--pu-duration)"
+      : typeof opts.duration === "number"
+        ? `${opts.duration}ms`
+        : opts.duration;
+  const ease =
+    opts.ease === "spring"
+      ? "var(--pu-ease-spring)"
+      : opts.ease === "out"
+        ? "var(--pu-ease-out)"
+        : "var(--pu-ease)";
+  return {
+    "--pu-motion-duration": duration,
+    "--pu-motion-ease": ease,
+  };
+}

package/src/overlay.ts

@@ -0,0 +1,232 @@
+import { trapFocus } from "./focusTrap.js";
+
+/**
+ * Shared overlay runtime for Dialog · Drawer · Popover · Command · Menu.
+ *
+ * Goals (FOUNDATION week 2):
+ * - One place for Escape, body scroll lock, focus trap, outside dismiss
+ * - Stacked layers: only the topmost Escape / outside-dismiss handler fires
+ * - Scroll lock is ref-counted (two dialogs open → one unlock when both close)
+ * - ownerDocument-aware (Lab iframes)
+ */
+
+export type OverlayContext = {
+  doc: Document;
+  win: Window & typeof globalThis;
+  root: HTMLElement | null;
+};
+
+export type OverlayAttachOptions = {
+  /** Overlay root (for document + outside-click containment). */
+  getRoot: () => HTMLElement | null;
+  /** Panel to focus-trap; omit for non-modal popovers/menus. */
+  getFocusRoot?: () => HTMLElement | null;
+  /** Close / dismiss callback. */
+  onClose: () => void;
+  /** Lock document.body scroll while open. Default false. */
+  scrollLock?: boolean;
+  /** Escape closes (topmost only). Default true. */
+  escape?: boolean;
+  /** Pointer down outside `getRoot()` closes (topmost only). Default false. */
+  dismissOutside?: boolean;
+  /**
+   * Optional override for “inside” detection (portaled lists, multi-node roots).
+   * When omitted, uses `getRoot()?.contains(node)`.
+   */
+  isInside?: (node: Node) => boolean;
+  /**
+   * Run after deferred attach (refs ready). Return optional extra cleanup
+   * (e.g. Popover reposition on scroll/resize).
+   */
+  onAttach?: (ctx: OverlayContext) => (() => void) | void;
+};
+
+type Layer = {
+  id: number;
+  doc: Document;
+  onClose: () => void;
+  escape: boolean;
+  dismissOutside: boolean;
+  /** Root for outside-click tests */
+  getRoot: () => HTMLElement | null;
+  isInside?: (node: Node) => boolean;
+};
+
+let nextLayerId = 1;
+const layers: Layer[] = [];
+
+function topLayer(
+  doc: Document,
+  pred: (l: Layer) => boolean,
+): Layer | undefined {
+  for (let i = layers.length - 1; i >= 0; i--) {
+    const l = layers[i]!;
+    if (l.doc === doc && pred(l)) return l;
+  }
+  return undefined;
+}
+
+function pushLayer(layer: Layer): () => void {
+  layers.push(layer);
+  return () => {
+    const i = layers.findIndex((l) => l.id === layer.id);
+    if (i >= 0) layers.splice(i, 1);
+  };
+}
+
+/** Per-document scroll lock refcount. */
+const scrollLocks = new WeakMap<Document, { count: number; prev: string }>();
+
+function lockBodyScroll(doc: Document): () => void {
+  let entry = scrollLocks.get(doc);
+  if (!entry) {
+    entry = { count: 0, prev: doc.body.style.overflow };
+    scrollLocks.set(doc, entry);
+  }
+  if (entry.count === 0) {
+    entry.prev = doc.body.style.overflow;
+    doc.body.style.overflow = "hidden";
+  }
+  entry.count++;
+  return () => {
+    const e = scrollLocks.get(doc);
+    if (!e) return;
+    e.count--;
+    if (e.count <= 0) {
+      e.count = 0;
+      doc.body.style.overflow = e.prev;
+    }
+  };
+}
+
+/**
+ * Attach overlay behaviors while open. Call from an `effect` when open is true;
+ * return the dispose as the effect cleanup.
+ *
+ * Attach is deferred one macrotask so `ref` callbacks have run.
+ *
+ * @example
+ * ```ts
+ * effect(() => {
+ *   if (!isOpen()) return;
+ *   return attachOverlay({
+ *     getRoot: () => rootEl,
+ *     getFocusRoot: () => panelEl,
+ *     onClose: () => props.onClose?.(),
+ *     scrollLock: true,
+ *   });
+ * });
+ * ```
+ */
+export function attachOverlay(options: OverlayAttachOptions): () => void {
+  const escape = options.escape !== false;
+  const dismissOutside = !!options.dismissOutside;
+  const scrollLock = !!options.scrollLock;
+
+  let disposed = false;
+  const cleanups: Array<() => void> = [];
+
+  const attach = () => {
+    if (disposed) return;
+
+    const root = options.getRoot();
+    const doc = root?.ownerDocument ?? document;
+    const win = (doc.defaultView ?? window) as Window & typeof globalThis;
+    const focusRoot = options.getFocusRoot?.() ?? null;
+
+    const layer: Layer = {
+      id: nextLayerId++,
+      doc,
+      onClose: options.onClose,
+      escape,
+      dismissOutside,
+      getRoot: options.getRoot,
+      ...(options.isInside ? { isInside: options.isInside } : {}),
+    };
+    cleanups.push(pushLayer(layer));
+
+    if (scrollLock) {
+      cleanups.push(lockBodyScroll(doc));
+    }
+
+    if (escape) {
+      const onKey = (e: KeyboardEvent) => {
+        if (e.key !== "Escape") return;
+        const top = topLayer(doc, (l) => l.escape);
+        if (!top || top.id !== layer.id) return;
+        e.preventDefault();
+        e.stopPropagation();
+        options.onClose();
+      };
+      win.addEventListener("keydown", onKey, true);
+      cleanups.push(() => win.removeEventListener("keydown", onKey, true));
+    }
+
+    if (dismissOutside) {
+      const contains = (node: Node) => {
+        if (options.isInside) return options.isInside(node);
+        const r = options.getRoot();
+        return !!(r && r.contains(node));
+      };
+      const onPointer = (e: Event) => {
+        const top = topLayer(doc, (l) => l.dismissOutside);
+        if (!top || top.id !== layer.id) return;
+        const t = e.target as Node | null;
+        if (!t) return;
+        if (contains(t)) return;
+        options.onClose();
+      };
+      // Skip the opening interaction
+      const skipTimer = win.setTimeout(() => {
+        if (disposed) return;
+        doc.addEventListener("pointerdown", onPointer, true);
+      }, 0);
+      cleanups.push(() => {
+        win.clearTimeout(skipTimer);
+        doc.removeEventListener("pointerdown", onPointer, true);
+      });
+    }
+
+    if (focusRoot) {
+      cleanups.push(trapFocus(focusRoot));
+    }
+
+    const extra = options.onAttach?.({ doc, win, root });
+    if (typeof extra === "function") cleanups.push(extra);
+  };
+
+  const win =
+    typeof window !== "undefined"
+      ? window
+      : (undefined as unknown as Window | undefined);
+  const timer = win?.setTimeout(attach, 0);
+  if (timer != null && win) {
+    cleanups.push(() => win.clearTimeout(timer));
+  } else {
+    attach();
+  }
+
+  return () => {
+    disposed = true;
+    // LIFO cleanup for stable lock / stack order
+    for (let i = cleanups.length - 1; i >= 0; i--) {
+      try {
+        cleanups[i]!();
+      } catch {
+        /* ignore */
+      }
+    }
+    cleanups.length = 0;
+  };
+}
+
+/** Test helper — current stack depth (all documents). */
+export function __overlayStackSize(): number {
+  return layers.length;
+}
+
+/** Test helper — clear stack (does not restore scroll). */
+export function __resetOverlayStack(): void {
+  layers.length = 0;
+  nextLayerId = 1;
+}

package/src/palette.ts

@@ -0,0 +1,70 @@
+import { signal, effect, type Signal } from "@lab206/core";
+
+/**
+ * Preview palettes for the design system.
+ * - `instrument` — current default (cool navy + green signal)
+ * - `dual` — dual electric (navy primary + cyan secondary; green = success only)
+ */
+export type PaletteId = "instrument" | "dual";
+
+export interface PaletteController {
+  id: Signal<PaletteId>;
+  set(id: PaletteId): void;
+  toggle(): void;
+  /** Apply `data-pu-palette` on documentElement (or target). */
+  bind(target?: Element): () => void;
+}
+
+const STORAGE_KEY = "pu-palette";
+
+function readStored(): PaletteId | null {
+  if (typeof localStorage === "undefined") return null;
+  try {
+    const v = localStorage.getItem(STORAGE_KEY);
+    if (v === "instrument" || v === "dual") return v;
+  } catch {
+    /* private mode */
+  }
+  return null;
+}
+
+function writeStored(id: PaletteId) {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(STORAGE_KEY, id);
+  } catch {
+    /* private mode */
+  }
+}
+
+/**
+ * Switchable token palette via `data-pu-palette` on `<html>`.
+ * Default: `dual` for preview (option 3); flip to `instrument` to restore the prior look.
+ */
+export function createPalette(initial: PaletteId = "dual"): PaletteController {
+  // Prefer last choice so “Instrument” sticks after you flip back
+  const start = readStored() ?? initial;
+  const id = signal<PaletteId>(start);
+
+  function set(next: PaletteId) {
+    id.set(next);
+    writeStored(next);
+  }
+
+  function toggle() {
+    set(id() === "dual" ? "instrument" : "dual");
+  }
+
+  function bind(target?: Element) {
+    const el =
+      target ??
+      (typeof document !== "undefined" ? document.documentElement : null);
+    if (!el) return () => {};
+
+    return effect(() => {
+      el.setAttribute("data-pu-palette", id());
+    });
+  }
+
+  return { id, set, toggle, bind };
+}

package/src/reactive.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared prop reading for form / control primitives.
+ *
+ * Prefer `mergeProps` / `createProps` so accessors and signals unwrap on
+ * property access. These helpers still work on *raw* values when needed
+ * (e.g. reading before merge, or defensive double-unwrap).
+ *
+ * Call inside an `effect` (or JSX reactive binding) so dependencies track.
+ */
+
+/** Plain value or zero-arg accessor / signal-like function. */
+export type MaybeReactive<T> = T | (() => T);
+
+/**
+ * Resolve `T | (() => T)`.
+ * - functions with arity 0 (including signals) are called
+ * - multi-arg functions are returned as-is (not used as accessors)
+ * - everything else is returned as-is
+ */
+export function readProp<T>(value: MaybeReactive<T> | null | undefined): T | undefined {
+  if (value == null) return undefined;
+  if (typeof value === "function") {
+    // Signals and zero-arg accessors only
+    if ((value as (...args: unknown[]) => unknown).length === 0) {
+      return (value as () => T)();
+    }
+  }
+  return value as T;
+}
+
+/** Boolean controls (`disabled`, `checked`, …). */
+export function readBool(
+  value: MaybeReactive<boolean> | null | undefined,
+): boolean {
+  return !!readProp(value);
+}
+
+/** String controls (`value`, `placeholder`, …). Nullish → `""`. */
+export function readStr(
+  value: MaybeReactive<string> | null | undefined,
+): string {
+  const v = readProp(value);
+  return v == null ? "" : String(v);
+}
+
+/** Numeric controls. Nullish → `fallback`. */
+export function readNum(
+  value: MaybeReactive<number> | null | undefined,
+  fallback = 0,
+): number {
+  const v = readProp(value);
+  if (v == null || Number.isNaN(Number(v))) return fallback;
+  return Number(v);
+}