@zyncat/ui 0.8.0

package/src/components/dev/motion-devtools.css

@@ -0,0 +1,265 @@
+/* MotionDevtools - a floating dev overlay, styled on-brand with the design system's own
+   surface tokens so the <Button>/<Checkbox>/<Collapse> it dogfoods render natively.
+
+   Collapsed it's a small pill (gauge + current factor); opening morphs it into the full panel.
+   The width eases (CSS transition) in step with the <Collapse>-driven body height, so it grows
+   as one piece and never teleports. Everything that would change size on open lives INSIDE the
+   Collapse, so nothing clips while the pill is still narrow.
+
+   The one non-negotiable trick: it RESETS --duration-* to their canonical values on its own
+   root. The engine scales those tokens globally to slow the app; without this local reset the
+   panel's own controls - and this very expand/collapse - would slow down with everything else.
+   A motion debugger must stay crisp while the app runs in slow-mo. Token fallbacks keep it
+   legible if dropped in without the base layer. */
+
+.mdt {
+  /* immune to the global slow-mo the engine applies to --duration-* */
+  --duration-fast: 140ms;
+  --duration-base: 200ms;
+  --duration-slow: 300ms;
+  --duration-slower: 450ms;
+  --duration-slowest: 900ms;
+  --duration-spin: 600ms;
+  --duration-pulse: 1600ms;
+
+  --mdt-offset: 16px;
+  --mdt-surface: color-mix(in oklab, var(--bg-surface, #fff) 88%, transparent);
+
+  position: fixed;
+  z-index: 2147483000; /* above every app layer, including tooltips */
+  display: flex;
+  color: var(--text-body, oklch(0.35 0.01 264));
+  font-family: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+  -webkit-font-smoothing: antialiased;
+}
+
+.mdt--top-left {
+  top: var(--mdt-offset);
+  left: var(--mdt-offset);
+}
+.mdt--top-right {
+  top: var(--mdt-offset);
+  right: var(--mdt-offset);
+}
+.mdt--bottom-left {
+  bottom: var(--mdt-offset);
+  left: var(--mdt-offset);
+}
+.mdt--bottom-right {
+  bottom: var(--mdt-offset);
+  right: var(--mdt-offset);
+}
+
+/* ---------- card (pill when collapsed, panel when open) ---------- */
+
+.mdt__panel {
+  box-sizing: border-box;
+  /* Compact pill when collapsed; eases to the full panel width in step with the <Collapse>
+     body height below, so the whole thing morphs open and never teleports. */
+  width: 128px;
+  padding: 5px;
+  border: 1px solid var(--border-subtle, oklch(0.92 0.004 264));
+  border-radius: var(--radius-xl, 0.75rem);
+  background: var(--mdt-surface);
+  backdrop-filter: blur(16px) saturate(1.6);
+  -webkit-backdrop-filter: blur(16px) saturate(1.6);
+  box-shadow: var(--shadow-lg, 0 12px 28px oklch(0 0 0 / 0.1));
+  animation: mdt-in var(--duration-base) var(--ease-entrance, ease);
+  transition:
+    width var(--duration-slow) var(--ease-entrance, ease),
+    box-shadow var(--duration-slow) var(--ease-entrance, ease);
+}
+.mdt__panel.is-open {
+  width: 232px;
+  box-shadow: var(--shadow-xl, 0 24px 48px oklch(0 0 0 / 0.16));
+}
+
+@keyframes mdt-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.985);
+  }
+}
+
+/* ---------- pill / header (the toggle) ---------- */
+
+.mdt__head {
+  appearance: none;
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.3125rem 0.4375rem;
+  border: 0;
+  border-radius: var(--radius-md, 0.375rem);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition: background var(--duration-fast) var(--ease-standard, ease);
+}
+.mdt__head:hover {
+  background: var(--neutral-wash, oklch(0.5 0.01 264 / 0.07));
+}
+.mdt__head:focus-visible {
+  outline: none;
+  box-shadow: var(--ring-accent, 0 0 0 3px oklch(0.7 0.12 185 / 0.35));
+}
+
+.mdt__glyph {
+  color: var(--text-subtle, oklch(0.6 0.01 264));
+  flex: none;
+  display: block;
+}
+.mdt--active .mdt__glyph {
+  color: var(--accent, oklch(0.62 0.12 185));
+}
+.mdt--paused .mdt__glyph {
+  color: var(--warning, oklch(0.72 0.13 75));
+}
+.mdt__spacer {
+  flex: 1;
+}
+.mdt__badge {
+  font-size: 0.75rem;
+  font-weight: 650;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  padding: 0.1875rem 0.4375rem;
+  border-radius: var(--radius-full, 999px);
+  color: var(--text-muted, oklch(0.55 0.01 264));
+  background: var(--neutral-wash, oklch(0.5 0.01 264 / 0.08));
+  white-space: nowrap;
+}
+.mdt--active .mdt__badge {
+  color: var(--text-on-accent, #fff);
+  background: var(--accent, oklch(0.62 0.12 185));
+}
+.mdt--paused .mdt__badge {
+  color: var(--text-on-accent, #fff);
+  background: var(--warning, oklch(0.72 0.13 75));
+}
+.mdt__chevron {
+  color: var(--text-subtle, oklch(0.6 0.01 264));
+  flex: none;
+  transition: transform var(--duration-base) var(--ease-standard, ease);
+}
+.mdt__chevron--open {
+  transform: rotate(180deg);
+}
+
+/* ---------- body (inside <Collapse>) ---------- */
+
+.mdt__body {
+  box-sizing: border-box;
+  /* Hold a stable layout width so controls don't reflow as the card animates open; the
+     collapsed pill is narrower, so this overflows and is clipped by <Collapse>'s overflow. */
+  width: 100%;
+  min-width: 208px;
+  display: flex;
+  flex-direction: column;
+  gap: 0.8125rem;
+  padding: 0.625rem 0.375rem 0.375rem;
+}
+
+.mdt__title {
+  font-size: 0.6875rem;
+  font-weight: 650;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--text-subtle, oklch(0.6 0.01 264));
+}
+.mdt__readout {
+  display: flex;
+  align-items: baseline;
+  gap: 0.375rem;
+  margin-top: -0.375rem;
+}
+.mdt__value {
+  font-size: 1.5rem;
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  color: var(--text-strong, oklch(0.25 0.01 264));
+}
+.mdt__unit {
+  font-size: 0.75rem;
+  color: var(--text-muted, oklch(0.55 0.01 264));
+  font-weight: 500;
+}
+
+.mdt__slider {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 100%;
+  height: 4px;
+  border-radius: 999px;
+  background: linear-gradient(
+    to right,
+    var(--accent, oklch(0.62 0.12 185)) 0%,
+    var(--accent, oklch(0.62 0.12 185)) var(--mdt-fill, 0%),
+    var(--bg-muted, oklch(0.93 0.004 264)) var(--mdt-fill, 0%)
+  );
+  cursor: pointer;
+  margin: 0;
+}
+.mdt__slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: var(--bg-surface, #fff);
+  border: 2px solid var(--accent, oklch(0.62 0.12 185));
+  box-shadow: var(--shadow-sm, 0 1px 2px oklch(0 0 0 / 0.15));
+}
+.mdt__slider::-moz-range-thumb {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: var(--bg-surface, #fff);
+  border: 2px solid var(--accent, oklch(0.62 0.12 185));
+  box-shadow: var(--shadow-sm, 0 1px 2px oklch(0 0 0 / 0.15));
+}
+.mdt__slider:focus-visible {
+  outline: none;
+}
+.mdt__slider:focus-visible::-webkit-slider-thumb {
+  box-shadow: var(--ring-accent, 0 0 0 3px oklch(0.7 0.12 185 / 0.35));
+}
+.mdt__slider:focus-visible::-moz-range-thumb {
+  box-shadow: var(--ring-accent, 0 0 0 3px oklch(0.7 0.12 185 / 0.35));
+}
+
+/* preset chip grid + action row - children are DS <Button>s */
+.mdt__chips {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 0.25rem;
+}
+.mdt__chips .btn {
+  padding-inline: 0;
+  min-width: 0;
+}
+.mdt__row {
+  display: flex;
+  gap: 0.375rem;
+}
+.mdt__row .btn {
+  flex: 1;
+}
+
+.mdt__opt {
+  border-top: 1px solid var(--border-subtle, oklch(0.92 0.004 264));
+  padding-top: 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.mdt__hint {
+  font-size: 0.6875rem;
+  line-height: 1.45;
+  color: var(--text-subtle, oklch(0.6 0.01 264));
+  margin: 0;
+}

package/src/components/dev/slowmo-engine.ts

@@ -0,0 +1,230 @@
+import { clock } from '../../engine';
+
+export interface SlowmoState {
+  /** 1 = real time. >1 = that many times slower (4 = quarter speed). */
+  factor: number;
+  /** Freeze motion in place - useful for inspecting a transition mid-flight. */
+  paused: boolean;
+}
+
+export interface SlowmoOptions {
+  /** Also scale setTimeout/setInterval so duration-coupled JS cleanups don't truncate
+   *  slowed CSS. Turn off if stretched app timers get in your way. @default true */
+  scaleTimers: boolean;
+}
+
+const CANONICAL: Record<string, number> = {
+  '--duration-fast': 140,
+  '--duration-base': 200,
+  '--duration-slow': 300,
+  '--duration-slower': 450,
+  '--duration-slowest': 900,
+  '--duration-spin': 600,
+  '--duration-pulse': 1600,
+};
+const DURATION_TOKENS = Object.keys(CANONICAL);
+const COLLAPSED_MS = 4;
+const FROZEN_MS = 600_000;
+const MAX_TIMER_DELAY = 2 ** 30;
+
+const clamp = (min: number, max: number, v: number) => (v < min ? min : v > max ? max : v);
+const hasDOM = typeof document !== 'undefined' && typeof window !== 'undefined';
+
+const state: SlowmoState = { factor: 1, paused: false };
+const options: SlowmoOptions = { scaleTimers: true };
+const listeners = new Set<(s: SlowmoState) => void>();
+
+let active = false;
+let baseMs: Record<string, number> = {};
+
+type SetTimer = (handler: TimerHandler, timeout?: number, ...args: unknown[]) => number;
+let origSetTimeout: SetTimer | null = null;
+let origSetInterval: SetTimer | null = null;
+
+type AnimateFn = (this: Element, ...args: unknown[]) => Animation;
+let origAnimate: AnimateFn | null = null;
+const trackedRates = new Map<Animation, number>();
+
+function readBaseMs(token: string): number {
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(token).trim();
+  const n = raw.endsWith('ms') ? parseFloat(raw) : raw.endsWith('s') ? parseFloat(raw) * 1000 : parseFloat(raw);
+  if (isNaN(n) || n <= COLLAPSED_MS) return CANONICAL[token];
+  return n;
+}
+
+function applyCssTokens() {
+  const root = document.documentElement.style;
+  for (const token of DURATION_TOKENS) {
+    const ms = state.paused ? FROZEN_MS : baseMs[token] * state.factor;
+    root.setProperty(token, `${ms}ms`);
+  }
+}
+
+function clearCssTokens() {
+  const root = document.documentElement.style;
+  for (const token of DURATION_TOKENS) root.removeProperty(token);
+}
+
+function scaleDelay(delay?: number): number | undefined {
+  if (typeof delay !== 'number' || !isFinite(delay)) return delay;
+  return Math.min(delay * state.factor, MAX_TIMER_DELAY);
+}
+
+function patchTimers() {
+  if (origSetTimeout) return;
+  origSetTimeout = window.setTimeout as unknown as SetTimer;
+  origSetInterval = window.setInterval as unknown as SetTimer;
+  const nativeTimeout = origSetTimeout.bind(window);
+  const nativeInterval = origSetInterval.bind(window);
+  window.setTimeout = ((h: TimerHandler, t?: number, ...a: unknown[]) =>
+    nativeTimeout(h, scaleDelay(t), ...a)) as typeof window.setTimeout;
+  window.setInterval = ((h: TimerHandler, t?: number, ...a: unknown[]) =>
+    nativeInterval(h, scaleDelay(t), ...a)) as typeof window.setInterval;
+}
+
+function restoreTimers() {
+  if (origSetTimeout) window.setTimeout = origSetTimeout as typeof window.setTimeout;
+  if (origSetInterval) window.setInterval = origSetInterval as typeof window.setInterval;
+  origSetTimeout = origSetInterval = null;
+}
+
+function liveRate(): number {
+  return state.paused ? 0 : 1 / state.factor;
+}
+
+function track(anim: Animation, original: number) {
+  if (trackedRates.has(anim)) return;
+  trackedRates.set(anim, original);
+  const forget = () => trackedRates.delete(anim);
+  anim.finished.then(forget).catch(forget);
+}
+
+function patchAnimate() {
+  if (origAnimate) return;
+  origAnimate = Element.prototype.animate as unknown as AnimateFn;
+  const original = origAnimate;
+  Element.prototype.animate = function (this: Element, ...args: unknown[]): Animation {
+    const anim = original.apply(this, args);
+    try {
+      track(anim, anim.playbackRate);
+      anim.playbackRate = liveRate();
+    } catch {}
+    return anim;
+  } as typeof Element.prototype.animate;
+}
+
+function restoreAnimate() {
+  if (origAnimate) Element.prototype.animate = origAnimate as typeof Element.prototype.animate;
+  origAnimate = null;
+}
+
+function sweepExisting() {
+  const rate = liveRate();
+  for (const anim of document.getAnimations()) {
+    try {
+      track(anim, anim.playbackRate);
+      anim.playbackRate = rate;
+    } catch {}
+  }
+}
+
+function applyTrackedRates() {
+  const rate = liveRate();
+  for (const anim of trackedRates.keys()) {
+    try {
+      anim.playbackRate = rate;
+    } catch {}
+  }
+}
+
+function restoreTrackedRates() {
+  for (const [anim, original] of trackedRates) {
+    try {
+      anim.playbackRate = original;
+    } catch {}
+  }
+  trackedRates.clear();
+}
+
+function applyEngineClock() {
+  clock.scale = state.paused ? Infinity : state.factor;
+}
+
+function install() {
+  active = true;
+  baseMs = {};
+  for (const token of DURATION_TOKENS) baseMs[token] = readBaseMs(token);
+  applyCssTokens();
+  applyEngineClock();
+  if (options.scaleTimers) patchTimers();
+  patchAnimate();
+  sweepExisting();
+}
+
+function reconfigure() {
+  applyCssTokens();
+  applyEngineClock();
+  applyTrackedRates();
+}
+
+function uninstall() {
+  active = false;
+  clearCssTokens();
+  clock.scale = 1;
+  restoreTimers();
+  restoreAnimate();
+  restoreTrackedRates();
+}
+
+function notify() {
+  const snapshot = { ...state };
+  for (const cb of listeners) cb(snapshot);
+}
+
+export function shouldBeActive(factor: number, paused: boolean): boolean {
+  return factor > 1 || paused;
+}
+
+/** Imperative control surface - drive slow-mo from a console, a hotkey, or the panel.
+ *  Safe to call during SSR (no-ops the DOM work, still tracks state for hydration). */
+export const motionSlowmo = {
+  /** Current state (a copy). */
+  get(): SlowmoState {
+    return { ...state };
+  },
+
+  /** Merge a partial state. factor is clamped to [1, 64]. */
+  set(patch: Partial<SlowmoState>): void {
+    if (typeof patch.factor === 'number') state.factor = clamp(1, 64, patch.factor);
+    if (typeof patch.paused === 'boolean') state.paused = patch.paused;
+
+    if (hasDOM) {
+      const wantActive = shouldBeActive(state.factor, state.paused);
+      if (!active && wantActive) install();
+      else if (active && !wantActive) uninstall();
+      else if (active) reconfigure();
+    }
+    notify();
+  },
+
+  /** Tune engine behaviour (e.g. stop scaling timers). Applies immediately if active. */
+  configure(patch: Partial<SlowmoOptions>): void {
+    if (typeof patch.scaleTimers === 'boolean' && patch.scaleTimers !== options.scaleTimers) {
+      options.scaleTimers = patch.scaleTimers;
+      if (active) options.scaleTimers ? patchTimers() : restoreTimers();
+    }
+  },
+
+  /** Convenience: back to real time and unpaused. */
+  reset(): void {
+    this.set({ factor: 1, paused: false });
+  },
+
+  /** Subscribe to state changes; returns an unsubscribe fn. */
+  subscribe(cb: (s: SlowmoState) => void): () => void {
+    listeners.add(cb);
+    return () => listeners.delete(cb);
+  },
+};
+
+export type MotionSlowmo = typeof motionSlowmo;

package/src/components/internal/glass/glass.css

@@ -0,0 +1,100 @@
+/* Glass surface - translucent tint + backdrop blur + a sheen layer; consumer sets --glass-tint and --glass-fg. */
+
+.glass {
+  --glass-fg: var(--text-body);
+  --glass-tint: var(--glass-tint-neutral);
+
+  position: relative;
+  isolation: isolate; /* local stacking for the sheen */
+  color: var(--glass-fg);
+
+  background: var(--glass-tint);
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
+  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturate));
+  box-shadow:
+    var(--glass-highlight),
+    inset 0 0 0 var(--border-hairline) color-mix(in oklab, var(--glass-fg) 22%, transparent),
+    var(--glass-shadow);
+
+  transition:
+    transform var(--duration-base) var(--ease-standard),
+    box-shadow var(--duration-base) var(--ease-standard),
+    background-color var(--duration-base) var(--ease-standard);
+}
+
+/* Sheen on its own layer so hover animates opacity/transform - gradients can't transition directly. */
+.glass::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  border-radius: inherit;
+  background: var(--glass-sheen);
+  opacity: var(--glass-sheen-rest);
+  pointer-events: none;
+  transition:
+    opacity var(--duration-base) var(--ease-standard),
+    transform var(--duration-slow) var(--ease-entrance);
+}
+.glass > * {
+  position: relative;
+  z-index: 1;
+} /* content rides above the sheen */
+
+.glass--strong {
+  --glass-blur: var(--glass-blur-strong);
+}
+
+.glass--interactive:hover {
+  transform: translateY(calc(var(--space-px) * -1));
+  box-shadow:
+    var(--glass-highlight),
+    inset 0 0 0 var(--border-hairline) color-mix(in oklab, var(--glass-fg) 26%, transparent),
+    var(--glass-shadow-hover);
+}
+.glass--interactive:hover::before {
+  opacity: var(--glass-sheen-hover);
+  transform: translateY(-8%);
+}
+
+/* Glint - one-shot light sweep; add .glass-glint to fire, remove after it ends (sits above content, z-index 2). */
+.glass-glint::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  border-radius: inherit;
+  pointer-events: none;
+  opacity: 0; /* resting state is invisible - no mid-sweep flash */
+  background: linear-gradient(118deg, transparent 36%, rgb(255 255 255 / 0.7) 50%, transparent 64%);
+  animation: glass-glint var(--duration-slow) var(--ease-standard) 1 forwards;
+}
+@keyframes glass-glint {
+  0% {
+    opacity: 0;
+    transform: translateX(-28%);
+  }
+  40% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+    transform: translateX(28%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .glass,
+  .glass::before {
+    transition: none;
+  }
+  .glass--interactive:hover {
+    transform: none;
+  }
+  .glass--interactive:hover::before {
+    transform: none;
+  }
+  .glass-glint::after {
+    animation: none;
+  }
+}

package/src/components/internal/glass/glint.ts

@@ -0,0 +1,9 @@
+import { UIMotion } from '../../../tokens/motion-tokens';
+
+export function fireGlint(el: HTMLElement): () => void {
+  el.classList.remove('glass-glint');
+  void el.offsetWidth;
+  el.classList.add('glass-glint');
+  const id = setTimeout(() => el.classList.remove('glass-glint'), UIMotion.dur.slow * 1000 + 80);
+  return () => clearTimeout(id);
+}

package/src/components/internal/hooks/use-controllable.ts

@@ -0,0 +1,21 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+export function useControllable<T, Meta = unknown>(
+  value: T | undefined,
+  defaultValue: T,
+  onChange?: (next: T, meta?: Meta) => void,
+): [T, (next: T, meta?: Meta) => void] {
+  const controlled = value !== undefined;
+  const [inner, setInner] = useState<T>(defaultValue);
+  const val = controlled ? (value as T) : inner;
+  const commit = useCallback(
+    (next: T, meta?: Meta) => {
+      if (!controlled) setInner(next);
+      if (onChange) onChange(next, meta);
+    },
+    [controlled, onChange],
+  );
+  return [val, commit];
+}

package/src/components/internal/hooks/use-scroll-edges.ts

@@ -0,0 +1,46 @@
+'use client';
+
+import { useCallback, useEffect, useRef, type RefObject } from 'react';
+
+export interface ScrollEdges {
+  top: boolean;
+  bottom: boolean;
+  left: boolean;
+  right: boolean;
+}
+
+export function useScrollEdges(
+  ref: RefObject<HTMLElement | null>,
+  onChange: (edges: ScrollEdges, el: HTMLElement) => void,
+  { content = false }: { content?: boolean } = {},
+): () => void {
+  const cb = useRef(onChange);
+  cb.current = onChange;
+  const sync = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    cb.current(
+      {
+        top: el.scrollTop > 1,
+        bottom: el.scrollTop + el.clientHeight < el.scrollHeight - 1,
+        left: el.scrollLeft > 1,
+        right: el.scrollLeft + el.clientWidth < el.scrollWidth - 1,
+      },
+      el,
+    );
+  }, [ref]);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    sync();
+    el.addEventListener('scroll', sync, { passive: true });
+    const ro = new ResizeObserver(sync);
+    ro.observe(el);
+    if (content && el.firstElementChild) ro.observe(el.firstElementChild);
+    return () => {
+      el.removeEventListener('scroll', sync);
+      ro.disconnect();
+    };
+  }, [sync, content]);
+  return sync;
+}