@zyncat/ui 0.11.0 → 0.13.0

package/src/components/primitives/toggle/toggle.css

@@ -1,152 +1,156 @@
-/* Toggle (switch) - immediate on/off; native input hidden, track + thumb painted, thumb travels on a CSS spring. */
+@layer zyncat.tokens, zyncat.components;
 
-.sw {
-  --sw-on-fill: linear-gradient(180deg, var(--accent), var(--accent-hover));
-  --sw-off-fill: var(--bg-muted);
-  --sw-on-border: var(--accent);
-  --sw-off-border: var(--border-strong);
-  --sw-ring: var(--ring-accent);
-  /* track size is the only input; thumb + travel derive from it */
-  --sw-w: var(--control-height);
-  --sw-h: var(--control-switch);
-  --sw-inset: calc(2 * var(--space-px));
-  /* inner track height minus both borders and the gap each side, so the inset is uniform on all edges */
-  --sw-thumb: calc(var(--sw-h) - 2 * var(--border-hairline) - 2 * var(--sw-inset));
-  /* colors read this flag; the thumb is moved by transform, not by it */
-  --on: 0;
+@layer zyncat.components {
+  /* Toggle (switch) - immediate on/off; native input hidden, track + thumb painted, thumb travels on a CSS spring. */
 
-  display: inline-flex;
-  align-items: flex-start;
-  gap: var(--space-3);
-  padding: var(--space-2);
-  border-radius: var(--radius-md);
-  cursor: pointer;
-  -webkit-tap-highlight-color: transparent;
-  transition: background-color var(--duration-fast) var(--ease-standard);
+  .sw {
+    --sw-on-fill: linear-gradient(180deg, var(--accent), var(--accent-hover));
+    --sw-off-fill: var(--bg-muted);
+    --sw-on-border: var(--accent);
+    --sw-off-border: var(--border-strong);
+    --sw-ring: var(--ring-accent);
+    /* track size is the only input; thumb + travel derive from it */
+    --sw-w: var(--control-height);
+    --sw-h: var(--control-switch);
+    --sw-inset: calc(2 * var(--space-px));
+    /* inner track height minus both borders and the gap each side, so the inset is uniform on all edges */
+    --sw-thumb: calc(var(--sw-h) - 2 * var(--border-hairline) - 2 * var(--sw-inset));
+    /* colors read this flag; the thumb is moved by transform, not by it */
+    --sw-checked: 0;
 
-  &:has(:checked) {
-    --on: 1;
-  }
+    display: inline-flex;
+    align-items: flex-start;
+    gap: var(--space-3);
+    padding: var(--space-2);
+    border-radius: var(--radius-md);
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    transition: background-color var(--duration-fast) var(--ease-standard);
 
-  &:not(.sw--disabled):hover {
-    background: var(--bg-muted);
-  }
-  &:not(.sw--disabled):hover:not(:has(:checked)) {
-    --sw-off-border: var(--text-subtle);
-  }
-  &:has(:focus-visible) .sw__track {
-    box-shadow: var(--sw-ring);
-  }
-}
-
-.sw__input {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  margin: 0;
-  padding: 0;
-  border: 0;
-  opacity: 0;
-  clip-path: inset(50%);
-  white-space: nowrap;
-  overflow: hidden;
-}
+    &:has(:checked) {
+      --sw-checked: 1;
+    }
 
-.sw__track {
-  position: relative;
-  flex: none;
-  display: flex;
-  align-items: center;
-  justify-content: flex-start;
-  padding: var(--sw-inset);
-  width: var(--sw-w);
-  height: var(--sw-h);
-  margin-top: calc((var(--leading-body) - var(--sw-h)) / 2);
-  border: var(--border-hairline) solid
-    color-mix(in oklab, var(--sw-on-border) calc(var(--on) * 100%), var(--sw-off-border));
-  border-radius: var(--radius-full);
-  background: var(--sw-off-fill);
-  transform: scale(1);
-  transition:
-    border-color var(--duration-base) var(--ease-standard),
-    background-color var(--duration-base) var(--ease-standard),
-    box-shadow var(--duration-fast) var(--ease-standard),
-    transform var(--duration-fast) var(--ease-spring);
+    &:not(.sw--disabled):hover {
+      background: var(--bg-muted);
+    }
+    &:not(.sw--disabled):hover:not(:has(:checked)) {
+      --sw-off-border: var(--text-subtle);
+    }
+    &:has(:focus-visible) .sw__track {
+      box-shadow: var(--sw-ring);
+    }
+  }
 
-  &::before {
-    content: '';
+  .sw__input {
     position: absolute;
-    inset: 0;
-    border-radius: inherit;
-    background: var(--sw-on-fill);
-    opacity: var(--on);
-    transition: opacity var(--duration-base) var(--ease-standard);
+    width: 1px;
+    height: 1px;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    opacity: 0;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    overflow: hidden;
   }
-}
-/* --tx (travel) + --sx (press-stretch) compose one transform, so press and travel never fight over it */
-.sw__thumb {
-  --tx: 0px;
-  --sx: 1;
-  position: relative;
-  z-index: 1;
-  flex: none;
-  width: var(--sw-thumb);
-  height: var(--sw-thumb);
-  border-radius: var(--radius-full);
-  background: var(--bg-surface);
-  box-shadow: var(--shadow-sm);
-  transform: translateX(var(--tx)) scaleX(var(--sx));
-  transition: transform var(--duration-base) var(--ease-spring);
-}
-/* React-set [data-on] drives travel - no :has() twin to move the thumb out from under the spring and snap it */
-.sw__track[data-on='true'] .sw__thumb {
-  --tx: calc(var(--sw-w) - var(--sw-h));
-}
-.sw__track[data-pressed='true'] {
-  transform: scale(0.96);
-}
-.sw__track[data-pressed='true'] .sw__thumb {
-  --sx: 1.16;
-}
 
-.sw__text {
-  display: grid;
-  gap: var(--space-1);
-}
-.sw__label {
-  font: var(--type-label);
-  color: var(--text-strong);
-}
-.sw__desc {
-  font: var(--type-caption);
-  color: var(--text-muted);
-}
+  .sw__track {
+    position: relative;
+    flex: none;
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    padding: var(--sw-inset);
+    width: var(--sw-w);
+    height: var(--sw-h);
+    margin-top: calc((var(--leading-body) - var(--sw-h)) / 2);
+    border: var(--border-hairline) solid
+      color-mix(in oklab, var(--sw-on-border) calc(var(--sw-checked) * 100%), var(--sw-off-border));
+    border-radius: var(--radius-full);
+    background: var(--sw-off-fill);
+    transform: scale(1);
+    transition:
+      border-color var(--duration-base) var(--ease-standard),
+      background-color var(--duration-base) var(--ease-standard),
+      box-shadow var(--duration-fast) var(--ease-standard),
+      transform var(--duration-fast) var(--ease-spring);
 
-.sw--sm {
-  --sw-w: var(--control-height-sm);
-  --sw-h: var(--space-4);
-  & .sw__label {
-    font: var(--type-caption);
-    font-weight: var(--weight-medium);
+    &::before {
+      content: '';
+      position: absolute;
+      inset: 0;
+      border-radius: inherit;
+      background: var(--sw-on-fill);
+      opacity: var(--sw-checked);
+      transition: opacity var(--duration-base) var(--ease-standard);
+    }
+  }
+  /* --sw-tx (travel) + --sw-sx (press-stretch) compose one transform, so press and travel never fight over it */
+  .sw__thumb {
+    --sw-tx: 0px;
+    --sw-sx: 1;
+    position: relative;
+    z-index: 1;
+    flex: none;
+    width: var(--sw-thumb);
+    height: var(--sw-thumb);
+    border-radius: var(--radius-full);
+    background: var(--bg-surface);
+    box-shadow: var(--shadow-sm);
+    transform: translateX(var(--sw-tx)) scaleX(var(--sw-sx));
+    transition: transform var(--duration-base) var(--ease-spring);
+  }
+  /* React-set [data-on] drives travel - no :has() twin to move the thumb out from under the spring and snap it */
+  .sw__track[data-on='true'] .sw__thumb {
+    --sw-tx: calc(var(--sw-w) - var(--sw-h));
+  }
+  .sw__track[data-pressed='true'] {
+    transform: scale(0.96);
+  }
+  .sw__track[data-pressed='true'] .sw__thumb {
+    --sw-sx: 1.16;
+  }
+
+  .sw__text {
+    display: grid;
+    gap: var(--space-1);
+  }
+  .sw__label {
+    font: var(--type-label);
     color: var(--text-strong);
   }
-  & .sw__track {
-    margin-top: calc((var(--leading-caption) - var(--sw-h)) / 2);
+  .sw__desc {
+    font: var(--type-caption);
+    color: var(--text-muted);
   }
-}
 
-/* disabled leaves the flag untouched, so the thumb keeps its correct position */
-.sw--disabled {
-  cursor: not-allowed;
-  --sw-on-fill: var(--accent-disabled);
-  --sw-off-fill: var(--bg-muted);
-  --sw-on-border: var(--accent-disabled);
-  --sw-off-border: var(--border-default);
-  & .sw__thumb {
-    box-shadow: var(--shadow-xs);
+  .sw--sm {
+    --sw-w: var(--control-height-sm);
+    --sw-h: var(--space-4);
+    & .sw__label {
+      font: var(--type-caption);
+      font-weight: var(--weight-medium);
+      color: var(--text-strong);
+    }
+    & .sw__track {
+      margin-top: calc((var(--leading-caption) - var(--sw-h)) / 2);
+    }
   }
-  & .sw__label,
-  & .sw__desc {
-    color: var(--text-disabled);
+
+  /* disabled leaves the flag untouched, so the thumb keeps its correct position */
+  .sw--disabled {
+    cursor: not-allowed;
+    --sw-on-fill: var(--accent-disabled);
+    --sw-off-fill: var(--bg-muted);
+    --sw-on-border: var(--accent-disabled);
+    --sw-off-border: var(--border-default);
+    & .sw__thumb {
+      box-shadow: var(--shadow-xs);
+    }
+    & .sw__label,
+    & .sw__desc {
+      color: var(--text-disabled);
+    }
   }
 }

package/src/engine/animate.ts

@@ -8,11 +8,12 @@ export interface Playback {
 }
 
 type Vec = [number, number];
-export type Size = number | 'auto';
+export type Length = number | `${number}%`;
+export type Size = Length | 'auto';
 
 export interface Layer {
-  x?: number[];
-  y?: number[];
+  x?: Length[];
+  y?: Length[];
   scale?: number[] | Vec[];
   opacity?: number[];
   width?: Size[];
@@ -21,6 +22,8 @@ export interface Layer {
   composite?: CompositeOperation;
 }
 
+export type Placement = Omit<Layer, 'timing' | 'composite'>;
+
 const RESET: Record<string, string> = { translate: '0px 0px', scale: '1' };
 const AUTO_METRIC = { width: 'offsetWidth', height: 'offsetHeight' } as const;
 const SIZES = ['width', 'height'] as const;
@@ -34,10 +37,14 @@ function measureAuto(el: HTMLElement, key: 'width' | 'height'): number {
   return measured;
 }
 
-function held(list: number[], index: number): number {
+function held<T>(list: T[], index: number): T {
   return list[Math.min(index, list.length - 1)];
 }
 
+function cssLength(value: Length): string {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
 function currentValue(el: HTMLElement, key: string): string {
   const raw = getComputedStyle(el).getPropertyValue(key).trim();
   return raw && raw !== 'none' ? raw : RESET[key];
@@ -51,7 +58,7 @@ function compile(el: HTMLElement, layer: Layer) {
     const x = layer.x?.length ? layer.x : [0];
     const y = layer.y?.length ? layer.y : [0];
     const count = Math.max(x.length, y.length);
-    frames.translate = Array.from({ length: count }, (_, i) => `${held(x, i)}px ${held(y, i)}px`);
+    frames.translate = Array.from({ length: count }, (_, i) => `${cssLength(held(x, i))} ${cssLength(held(y, i))}`);
   }
   if (layer.scale) frames.scale = layer.scale.map((v) => (typeof v === 'number' ? String(v) : `${v[0]} ${v[1]}`));
   if (layer.opacity) frames.opacity = layer.opacity.map(String);
@@ -61,26 +68,42 @@ function compile(el: HTMLElement, layer: Layer) {
     if (!list) continue;
     if (list[list.length - 1] === 'auto') autoKeys.push(key);
     const measured = list.includes('auto') ? measureAuto(el, key) : 0;
-    frames[key] = list.map((v) => `${v === 'auto' ? measured : v}px`);
+    frames[key] = list.map((v) => (v === 'auto' ? `${measured}px` : cssLength(v)));
   }
 
   for (const [key, list] of Object.entries(frames)) if (list.length === 1) list.unshift(currentValue(el, key));
   return { frames, autoKeys };
 }
 
-const owned = new WeakMap<HTMLElement, Map<string, Animation>>();
+function commitIfRendered(animation: Animation): void {
+  try {
+    animation.commitStyles();
+  } catch {}
+}
+
+export interface PropertyHolder {
+  cancel(): void;
+}
 
-function claim(el: HTMLElement, keys: string[], animation: Animation | null): void {
-  const map = owned.get(el) ?? new Map<string, Animation>();
+const owned = new WeakMap<HTMLElement, Map<string, PropertyHolder>>();
+
+export function claim(el: HTMLElement, keys: string[], holder: PropertyHolder | null): void {
+  const map = owned.get(el) ?? new Map<string, PropertyHolder>();
   owned.set(el, map);
   for (const key of keys) {
     const previous = map.get(key);
-    if (previous && previous !== animation) previous.cancel();
-    if (animation) map.set(key, animation);
+    if (previous && previous !== holder) previous.cancel();
+    if (holder) map.set(key, holder);
     else map.delete(key);
   }
 }
 
+export function release(el: HTMLElement, keys: string[], holder: PropertyHolder): void {
+  const map = owned.get(el);
+  if (!map) return;
+  for (const key of keys) if (map.get(key) === holder) map.delete(key);
+}
+
 function play(el: HTMLElement, layer: Layer): Playback | null {
   const { frames, autoKeys } = compile(el, layer);
   const keys = Object.keys(frames);
@@ -111,8 +134,8 @@ function play(el: HTMLElement, layer: Layer): Playback | null {
 
   const finished = animation.finished.then(
     (): void => {
-      if (!autoKeys.length) return;
-      animation.commitStyles();
+      if (!autoKeys.length && !timing?.release) return;
+      commitIfRendered(animation);
       animation.cancel();
       for (const key of autoKeys) el.style.setProperty(key, 'auto');
     },
@@ -139,3 +162,7 @@ export function animate(el: HTMLElement, ...layers: Layer[]): Playback {
     finished: Promise.all(plays.map((started) => started.finished)).then((): void => {}),
   };
 }
+
+export function set(el: HTMLElement, ...placements: Placement[]): void {
+  for (const placement of placements) play(el, { ...placement, timing: { duration: 0 } });
+}

package/src/engine/ease.ts

@@ -98,6 +98,7 @@ export interface Timing extends Omit<MotionTransition, 'ease'> {
   ease?: EaseValue | EaseValue[];
   times?: number[];
   fill?: FillMode;
+  release?: boolean;
 }
 
 export interface ResolvedTiming {

package/src/engine/flip.ts

@@ -10,6 +10,12 @@ export interface Box {
 
 const MOVE_EPSILON = 0.5;
 const SCALE_EPSILON = 0.01;
+const TOP_LEFT = { x: 0, y: 0 };
+
+function transformOrigin(el: HTMLElement): { x: number; y: number } {
+  const [x, y] = getComputedStyle(el).transformOrigin.split(' ');
+  return { x: parseFloat(x), y: parseFloat(y) };
+}
 
 export function measure(el: HTMLElement): Box {
   const rect = el.getBoundingClientRect();
@@ -31,7 +37,8 @@ export function dropShared(key: string): void {
 }
 
 export interface FlipOptions {
-  scale?: boolean;
+  /** How a changed box size is reconciled: cheap scale correction, a real width/height morph, or left alone. */
+  size?: 'scale' | 'morph' | 'none';
   timing?: Timing;
 }
 
@@ -39,21 +46,31 @@ export function flip(el: HTMLElement, from: Box, options: FlipOptions = {}): Pla
   const to = measure(el);
   if (!to.width || !to.height) return null;
 
-  const dx = from.left - to.left;
-  const dy = from.top - to.top;
-  const sx = options.scale === false ? 1 : from.width / to.width;
-  const sy = options.scale === false ? 1 : from.height / to.height;
+  const size = options.size ?? 'scale';
+  const sx = from.width / to.width;
+  const sy = from.height / to.height;
+
+  const moved = Math.abs(from.left - to.left) > MOVE_EPSILON || Math.abs(from.top - to.top) > MOVE_EPSILON;
+  const resized = size !== 'none' && (Math.abs(sx - 1) > SCALE_EPSILON || Math.abs(sy - 1) > SCALE_EPSILON);
+  if (!moved && !resized) return null;
 
-  const moved = Math.abs(dx) > MOVE_EPSILON || Math.abs(dy) > MOVE_EPSILON;
-  const scaled = Math.abs(sx - 1) > SCALE_EPSILON || Math.abs(sy - 1) > SCALE_EPSILON;
-  if (!moved && !scaled) return null;
+  const scaling = resized && size === 'scale';
+  const pivot = scaling ? transformOrigin(el) : TOP_LEFT;
+  const dx = from.left - to.left + pivot.x * (sx - 1);
+  const dy = from.top - to.top + pivot.y * (sy - 1);
 
-  const layer: Layer = { x: [dx, 0], y: [dy, 0], timing: { ...options.timing, fill: 'none' } };
-  if (scaled)
-    layer.scale = [
-      [sx, sy],
-      [1, 1],
-    ];
+  const timing = { ...options.timing, fill: 'none' as const };
+  const layers: Layer[] = [{ x: [dx, 0], y: [dy, 0], timing, composite: 'add' }];
+  if (scaling)
+    layers.push({
+      scale: [
+        [sx, sy],
+        [1, 1],
+      ],
+      timing,
+    });
+  if (resized && size === 'morph')
+    layers.push({ width: [from.width, to.width], height: [from.height, to.height], timing });
 
-  return animate(el, layer);
+  return animate(el, ...layers);
 }

package/src/engine/index.ts

@@ -1,3 +1,4 @@
-export { animate, clock, type Layer, type Playback } from './animate';
+export { animate, set, clock, type Layer, type Placement, type Playback } from './animate';
+export { loop, type LoopOptions, type SimulationFrame } from './loop';
 export { flip, measure, keepShared, readShared, dropShared, type Box, type FlipOptions } from './flip';
 export { startDrag, type PanInfo } from './drag';

package/src/engine/loop.ts

@@ -0,0 +1,97 @@
+import { UIMotion } from '../tokens/motion-tokens';
+import { claim, clock, release, type Playback, type PropertyHolder } from './animate';
+
+export type SimulationFrame = (k: number, dt: number, now: number) => void;
+
+export interface LoopOptions {
+  el?: HTMLElement;
+  claims?: string[];
+  speed?: () => number;
+  snap?: () => void;
+}
+
+const MAX_FRAME_MS = 34;
+const BASE_FRAME_MS = 1000 / 60;
+
+const settled: Playback = { stop() {}, finished: Promise.resolve() };
+
+export function loop(frame: SimulationFrame, options: LoopOptions = {}): Playback {
+  if (UIMotion.reduced) {
+    options.snap?.();
+    return settled;
+  }
+
+  const { el, claims, speed } = options;
+  const keys = el && claims?.length ? claims : null;
+
+  let raf = 0;
+  let stopped = false;
+  let hidden = document.visibilityState === 'hidden';
+  let inView = true;
+  let running = false;
+  let last = 0;
+  let resolveFinished!: () => void;
+  const finished = new Promise<void>((resolve) => (resolveFinished = resolve));
+
+  const step = (now: number) => {
+    raf = 0;
+    if (!running) return;
+    const dt = Math.min(MAX_FRAME_MS, now - last) || BASE_FRAME_MS;
+    last = now;
+    const rate = Number(speed ? speed() : 1);
+    const effective = (isFinite(rate) && rate >= 0 ? rate : 1) / clock.scale;
+    frame((dt / BASE_FRAME_MS) * effective, dt * effective, now);
+    if (running) raf = requestAnimationFrame(step);
+  };
+
+  const sync = () => {
+    const next = !stopped && !hidden && inView;
+    if (next === running) return;
+    running = next;
+    if (running) {
+      last = performance.now();
+      raf = requestAnimationFrame(step);
+    } else if (raf) {
+      cancelAnimationFrame(raf);
+      raf = 0;
+    }
+  };
+
+  const onVisibility = () => {
+    hidden = document.visibilityState === 'hidden';
+    sync();
+  };
+  document.addEventListener('visibilitychange', onVisibility);
+
+  let observer: IntersectionObserver | null = null;
+  if (el && typeof IntersectionObserver !== 'undefined') {
+    observer = new IntersectionObserver((entries) => {
+      inView = entries[entries.length - 1].isIntersecting;
+      sync();
+    });
+    observer.observe(el);
+  }
+
+  const teardown = () => {
+    if (stopped) return;
+    stopped = true;
+    sync();
+    document.removeEventListener('visibilitychange', onVisibility);
+    observer?.disconnect();
+    resolveFinished();
+  };
+
+  const holder: PropertyHolder = { cancel: teardown };
+
+  const stop = () => {
+    if (stopped) return;
+    if (keys && el) release(el, keys, holder);
+    teardown();
+  };
+
+  if (keys && el) claim(el, keys, holder);
+
+  sync();
+
+  return { stop, finished };
+}