@lab206/ui 0.1.0

package/src/components/Transition.tsx

@@ -0,0 +1,155 @@
+import { effect } from "@lab206/core";
+import { component, type ComponentProps } from "@lab206/dom";
+import { cx } from "../utils.js";
+import { createStyleSheet } from "../styles.js";
+
+export type TransitionProps = {
+  /** Show / hide the child */
+  show: boolean | (() => boolean);
+  /** CSS name prefix — generates name-enter, name-enter-active, name-exit, name-exit-active */
+  name?: string;
+  /** Fallback duration (ms) if no transitionend fires */
+  duration?: number;
+  class?: string | (() => string);
+  children?: unknown;
+};
+
+const ensure = createStyleSheet(
+  "transition",
+  `
+.pu-transition { display: contents; }
+.pu-fade-enter { opacity: 0; }
+.pu-fade-enter-active {
+  opacity: 1;
+  transition: opacity var(--pu-duration) var(--pu-ease-out);
+}
+.pu-fade-exit { opacity: 1; }
+.pu-fade-exit-active {
+  opacity: 0;
+  transition: opacity var(--pu-duration) var(--pu-ease);
+}
+.pu-collapse-enter {
+  overflow: hidden;
+  max-height: 0;
+  opacity: 0;
+}
+.pu-collapse-enter-active {
+  overflow: hidden;
+  max-height: 40rem;
+  opacity: 1;
+  transition:
+    max-height var(--pu-duration-slow) var(--pu-ease-out),
+    opacity var(--pu-duration) var(--pu-ease-out);
+}
+.pu-collapse-exit {
+  overflow: hidden;
+  max-height: 40rem;
+  opacity: 1;
+}
+.pu-collapse-exit-active {
+  overflow: hidden;
+  max-height: 0;
+  opacity: 0;
+  transition:
+    max-height var(--pu-duration-slow) var(--pu-ease),
+    opacity var(--pu-duration) var(--pu-ease);
+}
+@media (prefers-reduced-motion: reduce) {
+  .pu-fade-enter-active,
+  .pu-fade-exit-active,
+  .pu-collapse-enter-active,
+  .pu-collapse-exit-active { transition: none; }
+}
+`,
+);
+
+/**
+ * Enter/exit CSS transitions around children.
+ * Default name `"pu-fade"`; also built-in `"pu-collapse"`.
+ */
+export const Transition = component((raw: TransitionProps) => {
+  ensure();
+  const props = raw as ComponentProps<TransitionProps>;
+  const name = () => props.name ?? "pu-fade";
+  const duration = () => props.duration ?? 220;
+
+  const host = document.createElement("div");
+  host.className = "pu-transition";
+  let childHost: HTMLElement | null = null;
+  let phase: "void" | "in" | "out" = "void";
+
+  const resolveChild = (): Node | null => {
+    const c = props.children;
+    if (c == null || c === false) return null;
+    if (c instanceof Node) return c;
+    if (typeof c === "function") {
+      const r = (c as () => unknown)();
+      if (r instanceof Node) return r;
+      if (r == null) return null;
+      return document.createTextNode(String(r));
+    }
+    return document.createTextNode(String(c));
+  };
+
+  const show = () => {
+    const s = props.show;
+    return typeof s === "function" ? !!(s as () => boolean)() : !!s;
+  };
+
+  effect(() => {
+    const on = show();
+    const n = name();
+    const doc = host.ownerDocument;
+    ensure(doc);
+    const win = doc.defaultView ?? window;
+
+    if (on) {
+      if (phase === "in") return;
+      phase = "in";
+      host.replaceChildren();
+      const wrap = doc.createElement("div");
+      wrap.className = cx(
+        typeof props.class === "function" ? props.class() : props.class,
+      );
+      const node = resolveChild();
+      if (node) wrap.appendChild(node);
+      childHost = wrap;
+      host.appendChild(wrap);
+      wrap.classList.add(`${n}-enter`);
+      // force reflow
+      void wrap.offsetWidth;
+      wrap.classList.add(`${n}-enter-active`);
+      const done = () => {
+        wrap.classList.remove(`${n}-enter`, `${n}-enter-active`);
+      };
+      const t = win.setTimeout(done, duration());
+      wrap.addEventListener("transitionend", done, { once: true });
+      return () => win.clearTimeout(t);
+    }
+
+    // exit
+    if (phase === "void" || !childHost) {
+      host.replaceChildren();
+      phase = "void";
+      return;
+    }
+    if (phase === "out") return;
+    phase = "out";
+    const wrap = childHost;
+    wrap.classList.remove(`${n}-enter`, `${n}-enter-active`);
+    wrap.classList.add(`${n}-exit`);
+    void wrap.offsetWidth;
+    wrap.classList.add(`${n}-exit-active`);
+    const finish = () => {
+      if (phase !== "out") return;
+      host.replaceChildren();
+      childHost = null;
+      phase = "void";
+    };
+    const t = win.setTimeout(finish, duration());
+    wrap.addEventListener("transitionend", finish, { once: true });
+    return () => win.clearTimeout(t);
+  });
+
+  return host;
+});

package/src/density.ts

@@ -0,0 +1,46 @@
+import { effect, signal, type Signal } from "@lab206/core";
+
+export type Density = "comfortable" | "compact";
+
+export interface DensityController {
+  density: Signal<Density>;
+  setDensity(next: Density): void;
+  toggle(): void;
+  /** Apply `data-pu-density` (default: document.documentElement) */
+  bind(target?: Element): () => void;
+}
+
+/**
+ * Control spacing / control height density via CSS tokens.
+ *
+ * @example
+ * ```ts
+ * const density = createDensity("comfortable");
+ * density.bind();
+ * density.setDensity("compact");
+ * ```
+ */
+export function createDensity(initial: Density = "comfortable"): DensityController {
+  const density = signal<Density>(initial);
+
+  function setDensity(next: Density) {
+    density.set(next);
+  }
+
+  function toggle() {
+    density.update((d) => (d === "comfortable" ? "compact" : "comfortable"));
+  }
+
+  function bind(target?: Element) {
+    const el =
+      target ??
+      (typeof document !== "undefined" ? document.documentElement : null);
+    if (!el) return () => {};
+
+    return effect(() => {
+      el.setAttribute("data-pu-density", density());
+    });
+  }
+
+  return { density, setDensity, toggle, bind };
+}

package/src/dev.ts

@@ -0,0 +1,87 @@
+/**
+ * Lightweight development warnings for common Powers mistakes.
+ * No-ops when `NODE_ENV === "production"` or when disabled.
+ *
+ * Call `installDevWarnings()` once from your app bootstrap (demos do this).
+ */
+
+const g = globalThis as unknown as {
+  process?: { env?: { NODE_ENV?: string } };
+  __POWER_UI_DEV__?: boolean;
+  __POWER_UI_WARNED__?: Set<string>;
+};
+
+function isDev(): boolean {
+  if (g.__POWER_UI_DEV__ === false) return false;
+  if (g.__POWER_UI_DEV__ === true) return true;
+  const env = g.process?.env?.NODE_ENV;
+  if (env === "production") return false;
+  // Browser demos / Vite: treat as dev unless explicitly production
+  return true;
+}
+
+function warnedSet(): Set<string> {
+  if (!g.__POWER_UI_WARNED__) g.__POWER_UI_WARNED__ = new Set();
+  return g.__POWER_UI_WARNED__;
+}
+
+/** Log a unique warning once per key (console.warn). */
+export function devWarnOnce(key: string, message: string): void {
+  if (!isDev()) return;
+  const set = warnedSet();
+  if (set.has(key)) return;
+  set.add(key);
+  // eslint-disable-next-line no-console
+  console.warn(`[Powers] ${message}`);
+}
+
+/**
+ * After first paint, check that design tokens exist (theme.css imported).
+ * Safe to call multiple times.
+ */
+export function warnIfThemeMissing(doc: Document = document): void {
+  if (!isDev() || typeof doc === "undefined") return;
+  queueMicrotask(() => {
+    try {
+      const cs = doc.defaultView?.getComputedStyle(doc.documentElement);
+      const accent = cs?.getPropertyValue("--pu-color-accent")?.trim();
+      if (!accent) {
+        devWarnOnce(
+          "theme-css",
+          'Missing design tokens. Import once at the app root: import "@lab206/ui/theme.css"; then createTheme().bind().',
+        );
+      }
+    } catch {
+      /* ignore */
+    }
+  });
+}
+
+/**
+ * Heuristic: plain-string `value` on a named control often means the author
+ * wrote `value={email()}` (snapshot) instead of `bind={email}` / `value={email}`.
+ * Only warns when `bound` is not used.
+ */
+export function warnPossibleSnapshotValue(
+  control: string,
+  opts: { hasBind?: boolean; valueIsPlainString?: boolean },
+): void {
+  if (!isDev() || opts.hasBind || !opts.valueIsPlainString) return;
+  devWarnOnce(
+    `snapshot-${control}`,
+    `${control}: value is a plain string. If you meant a live signal, pass the signal itself: bind={email} or value={email} — not value={email()}.`,
+  );
+}
+
+/** Enable/disable all Powers dev warnings. */
+export function setDevWarnings(enabled: boolean): void {
+  g.__POWER_UI_DEV__ = enabled;
+}
+
+/** Install theme check (call once from demo / template main). */
+export function installDevWarnings(): void {
+  if (!isDev()) return;
+  if (typeof document !== "undefined") {
+    warnIfThemeMissing(document);
+  }
+}

package/src/focusTrap.ts

@@ -0,0 +1,61 @@
+const FOCUSABLE =
+  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
+function listFocusable(root: HTMLElement): HTMLElement[] {
+  return [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(
+    (el) => !el.hasAttribute("disabled") && el.offsetParent !== null,
+  );
+}
+
+/**
+ * Trap Tab focus inside `root` (for Dialog / Command / Drawer).
+ * Returns a dispose that removes the listener and restores prior focus.
+ */
+export function trapFocus(root: HTMLElement): () => void {
+  const doc = root.ownerDocument;
+  const prev = doc.activeElement as HTMLElement | null;
+
+  const focusFirst = () => {
+    const items = listFocusable(root);
+    (items[0] ?? root).focus?.();
+  };
+
+  // Defer so open animation / mount finishes
+  const win = doc.defaultView ?? window;
+  const t = win.setTimeout(focusFirst, 0);
+
+  const onKey = (e: KeyboardEvent) => {
+    if (e.key !== "Tab") return;
+    const items = listFocusable(root);
+    if (items.length === 0) {
+      e.preventDefault();
+      return;
+    }
+    const first = items[0]!;
+    const last = items[items.length - 1]!;
+    const active = doc.activeElement as HTMLElement | null;
+    if (e.shiftKey) {
+      if (active === first || !root.contains(active)) {
+        e.preventDefault();
+        last.focus();
+      }
+    } else if (active === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  };
+
+  doc.addEventListener("keydown", onKey, true);
+
+  return () => {
+    win.clearTimeout(t);
+    doc.removeEventListener("keydown", onKey, true);
+    if (prev && typeof prev.focus === "function") {
+      try {
+        prev.focus();
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+}

package/src/form.ts

@@ -0,0 +1,269 @@
+/**
+ * Lightweight form helpers — pure functions for Field `error` props,
+ * two-way bind helpers, and a small `createField` pattern.
+ *
+ * No schema DSL. Keep validation next to signals.
+ *
+ * @example Preferred control wiring
+ * ```tsx
+ * const email = signal("");
+ * <Input bind={email} />
+ * // or spread: <Input {...bindText(email)} />
+ * ```
+ *
+ * @example Validation
+ * ```tsx
+ * const emailError = () => firstError(required(email()), emailFormat(email()));
+ * <Field label="Email" error={emailError}><Input bind={email} /></Field>
+ * ```
+ */
+
+import { signal, type Signal } from "@lab206/core";
+
+export type FieldError = string | undefined | null | false;
+
+/** Anything that behaves like a writable signal (Powers signal). */
+export type Bindable<T> = {
+  (): T;
+  set: (value: T) => void;
+};
+
+/** First truthy message wins (empty string / false / null skipped). */
+export function firstError(
+  ...msgs: Array<FieldError | (() => FieldError)>
+): string {
+  for (const m of msgs) {
+    const v = typeof m === "function" ? m() : m;
+    if (v) return String(v);
+  }
+  return "";
+}
+
+export function required(
+  value: unknown,
+  message = "Required",
+): FieldError {
+  if (value == null) return message;
+  if (typeof value === "string" && value.trim() === "") return message;
+  if (Array.isArray(value) && value.length === 0) return message;
+  return "";
+}
+
+export function minLength(
+  value: string,
+  min: number,
+  message?: string,
+): FieldError {
+  if (!value) return "";
+  if (value.length < min) {
+    return message ?? `At least ${min} characters`;
+  }
+  return "";
+}
+
+export function maxLength(
+  value: string,
+  max: number,
+  message?: string,
+): FieldError {
+  if (!value) return "";
+  if (value.length > max) {
+    return message ?? `At most ${max} characters`;
+  }
+  return "";
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export function emailFormat(
+  value: string,
+  message = "Enter a valid email",
+): FieldError {
+  if (!value || !value.trim()) return "";
+  return EMAIL_RE.test(value.trim()) ? "" : message;
+}
+
+export function matches(
+  value: string,
+  other: string,
+  message = "Does not match",
+): FieldError {
+  if (!value && !other) return "";
+  return value === other ? "" : message;
+}
+
+/**
+ * Run a map of field → error string. Returns `{ ok, errors }`.
+ * Use after submit or whenever you want a full-form snapshot.
+ */
+export function validateForm<K extends string>(
+  fields: Record<K, () => FieldError>,
+): { ok: boolean; errors: Partial<Record<K, string>> } {
+  const errors: Partial<Record<K, string>> = {};
+  let ok = true;
+  for (const key of Object.keys(fields) as K[]) {
+    const msg = fields[key]!();
+    if (msg) {
+      errors[key] = String(msg);
+      ok = false;
+    }
+  }
+  return { ok, errors };
+}
+
+/** Read string value from an input / textarea / select event. */
+export function eventValue(e: Event): string {
+  const t = e.currentTarget ?? e.target;
+  // Duck-type (works in happy-dom / SSR stubs without instanceof globals)
+  if (t && typeof t === "object" && "value" in t) {
+    return String((t as { value: unknown }).value ?? "");
+  }
+  return "";
+}
+
+/** Read checked state from a checkbox / switch-like event. */
+export function eventChecked(e: Event): boolean {
+  const t = e.currentTarget ?? e.target;
+  if (t && typeof t === "object" && "checked" in t) {
+    return !!(t as { checked: unknown }).checked;
+  }
+  return false;
+}
+
+/**
+ * Props to spread onto `Input` / `Textarea` for two-way signal binding.
+ *
+ * Prefer the control’s `bind={signal}` prop when available.
+ * Named `bindInput` (not `bindText`) so it doesn’t clash with `@lab206/dom`’s
+ * DOM `bindText` helper.
+ */
+export function bindInput(sig: Bindable<string>): {
+  value: Bindable<string>;
+  onInput: (e: Event) => void;
+} {
+  return {
+    value: sig,
+    onInput: (e: Event) => {
+      sig.set(eventValue(e));
+    },
+  };
+}
+
+/** Alias of bindInput. */
+export const bindString = bindInput;
+
+/**
+ * Props to spread onto `Select` for two-way signal binding.
+ * Prefer `bind={signal}` on Select when available.
+ */
+export function bindSelect(sig: Bindable<string>): {
+  value: Bindable<string>;
+  onChange: (e: Event) => void;
+} {
+  return {
+    value: sig,
+    onChange: (e: Event) => {
+      sig.set(eventValue(e));
+    },
+  };
+}
+
+/**
+ * Adapt a typed string-union signal (`Signal<"a" | "b">`) for `<Select bind={…} />`.
+ */
+export function asSelectBind<T extends string>(sig: {
+  (): T;
+  set: (value: T) => void;
+}): Bindable<string> {
+  const bound = (() => sig()) as unknown as Bindable<string>;
+  bound.set = (value: string) => {
+    sig.set(value as T);
+  };
+  return bound;
+}
+
+/**
+ * Props for checkbox / switch patterns that use `checked` + `onChange(boolean)`.
+ */
+export function bindChecked(sig: Bindable<boolean>): {
+  checked: Bindable<boolean>;
+  onChange: (checked: boolean) => void;
+} {
+  return {
+    checked: sig,
+    onChange: (checked: boolean) => {
+      sig.set(checked);
+    },
+  };
+}
+
+export type CreateFieldOptions = {
+  /** Initial string value */
+  initial?: string;
+  /**
+   * Validate when touched (or always if `validateWhen: "always"`).
+   * Return a message or falsy.
+   */
+  validate?: (value: string) => FieldError;
+  /** Default `"touched"` — only show errors after blur/submit. */
+  validateWhen?: "touched" | "always";
+};
+
+export type FieldHandle = {
+  /** Writable signal — pass to `bind={field.value}` or `value={field.value}` */
+  value: Signal<string>;
+  touched: Signal<boolean>;
+  /** Accessor for Field `error={field.error}` */
+  error: () => string;
+  /** Mark touched (call on blur or before submit) */
+  touch: () => void;
+  /** Reset value + untouched */
+  reset: (next?: string) => void;
+  /** Current string (sugar for value()) */
+  get: () => string;
+  set: (v: string) => void;
+};
+
+/**
+ * One field’s state: value signal + touched + error accessor.
+ *
+ * @example
+ * ```tsx
+ * const name = createField({
+ *   validate: (v) => required(v, "Name required"),
+ * });
+ *
+ * <Field label="Name" required error={name.error}>
+ *   <Input bind={name.value} onBlur={name.touch} />
+ * </Field>
+ *
+ * // on submit:
+ * name.touch();
+ * if (name.error()) return;
+ * ```
+ */
+export function createField(options: CreateFieldOptions = {}): FieldHandle {
+  const initial = options.initial ?? "";
+  const value = signal(initial);
+  const touched = signal(false);
+  const when = options.validateWhen ?? "touched";
+
+  const error = (): string => {
+    if (when === "touched" && !touched()) return "";
+    if (!options.validate) return "";
+    return firstError(options.validate(value()));
+  };
+
+  return {
+    value,
+    touched,
+    error,
+    touch: () => touched.set(true),
+    reset: (next = initial) => {
+      value.set(next);
+      touched.set(false);
+    },
+    get: () => value(),
+    set: (v: string) => value.set(v),
+  };
+}