@zyncat/ui 0.11.0 → 0.12.0

package/src/motion/flip.ts

@@ -1,6 +1,7 @@
 'use client';
 
 import { useLayoutEffect, useRef, type RefObject } from 'react';
+
 import {
   dropShared,
   flip,
@@ -15,6 +16,10 @@ import { UIMotion } from '../tokens/motion-tokens';
 
 export type FlipTuning = FlipOptions;
 
+const sharedOwner = new Map<string, HTMLElement>();
+
+const usable = (box: Box | null): box is Box => !!box && box.width > 0 && box.height > 0;
+
 export function useFlip<T extends HTMLElement>(
   sharedId: string | null,
   tuning: FlipTuning = {},
@@ -23,21 +28,33 @@ export function useFlip<T extends HTMLElement>(
   const ref = useRef<T | null>(null);
   const privateBox = useRef<Box | null>(null);
   const playing = useRef<{ play: Playback; el: T } | null>(null);
-  const { scale, timing } = tuning;
+  const interrupted = useRef<Box | null>(null);
+  const { size, timing } = tuning;
 
   useLayoutEffect(() => {
     const el = ref.current;
     if (!el || !enabled) return;
     const live = playing.current;
-    const from = live && live.el === el ? measure(el) : sharedId === null ? privateBox.current : readShared(sharedId);
+    let from: Box | null;
+    if (live && live.el === el) from = measure(el);
+    else if (interrupted.current) from = interrupted.current;
+    else if (sharedId === null) from = privateBox.current;
+    else from = sharedOwner.get(sharedId) === el ? null : readShared(sharedId);
     live?.play.stop();
     const settled = measure(el);
     if (sharedId === null) privateBox.current = settled;
-    else keepShared(sharedId, settled);
-    const next = from && !UIMotion.reduced ? flip(el, from, { scale, timing }) : null;
+    else {
+      keepShared(sharedId, settled);
+      sharedOwner.set(sharedId, el);
+    }
+    const next = usable(from) && !UIMotion.reduced ? flip(el, from, { size, timing }) : null;
     playing.current = next ? { play: next, el } : null;
+    interrupted.current = next ? from : null;
     next?.finished.then(() => {
-      if (playing.current?.play === next) playing.current = null;
+      if (playing.current?.play === next) {
+        playing.current = null;
+        interrupted.current = null;
+      }
     });
   });
 
@@ -45,14 +62,16 @@ export function useFlip<T extends HTMLElement>(
     if (!enabled || sharedId === null) return;
     return () => {
       const live = playing.current;
-      if (live) {
-        const box = measure(live.el);
-        if (box.width && box.height) keepShared(sharedId, box);
-        live.play.stop();
-      }
+      let box: Box | null = live ? measure(live.el) : null;
+      live?.play.stop();
+      playing.current = null;
+      if (!usable(box)) box = ref.current ? measure(ref.current) : null;
+      if (usable(box)) keepShared(sharedId, box);
       const mine = readShared(sharedId);
       queueMicrotask(() => {
         if (readShared(sharedId) === mine) dropShared(sharedId);
+        const owner = sharedOwner.get(sharedId);
+        if (owner && !owner.isConnected) sharedOwner.delete(sharedId);
       });
     };
   }, [sharedId, enabled]);

package/src/motion/glide.tsx

@@ -1,7 +1,8 @@
 'use client';
 
 import { useRef, type RefObject } from 'react';
-import { animate } from '../engine';
+
+import { animate, flip, measure, set } from '../engine';
 import { UIMotion as SM } from '../tokens/motion-tokens';
 
 export type GlideApi = ReturnType<typeof useGlide>;
@@ -14,24 +15,20 @@ export function useGlide<T extends HTMLElement>(containerRef: RefObject<T | null
     const box = containerRef.current,
       pill = ref.current;
     if (!box || !pill || !target) return;
-    const was = pill.getBoundingClientRect();
+    const was = measure(pill);
     const b = box.getBoundingClientRect();
     const t = target.getBoundingClientRect();
     const s = box.offsetWidth ? b.width / box.offsetWidth : 1;
-    pill.style.translate = `${(t.left - b.left) / s + box.scrollLeft}px ${(t.top - b.top) / s + box.scrollTop}px`;
-    pill.style.width = `${t.width / s}px`;
-    pill.style.height = `${t.height / s}px`;
-    const now = pill.getBoundingClientRect();
+    set(pill, {
+      x: [(t.left - b.left) / s + box.scrollLeft],
+      y: [(t.top - b.top) / s + box.scrollTop],
+      width: [t.width / s],
+      height: [t.height / s],
+    });
     animate(pill, { opacity: [1], timing: { duration: SM.dur.fast, ease: SM.ease.standard } });
-    const glided = visible.current && !SM.reduced;
+    const glided = visible.current && !SM.reduced && was.width > 0 && was.height > 0;
     visible.current = true;
-    if (!glided) return;
-    const timing = { ...SM.t.settle, fill: 'none' as const };
-    animate(
-      pill,
-      { x: [was.left - now.left, 0], y: [was.top - now.top, 0], timing, composite: 'add' },
-      { width: [was.width, now.width], height: [was.height, now.height], timing },
-    );
+    if (glided) flip(pill, was, { size: 'morph', timing: SM.t.settle });
   }
 
   function leave() {

package/src/motion/glide.usage.md

@@ -0,0 +1,15 @@
+# Glide / GlidePill - @zyncat/ui/glide
+
+Group: primitives
+
+A persistent background pill that glides smoothly between hovered/active elements.
+
+Container must be `position: relative`.
+
+```tsx
+const glide = useGlide(containerRef); // { ref, enter, leave } - pass the whole thing to GlidePill
+<nav ref={containerRef} onPointerLeave={glide.leave}>
+  <GlidePill glide={glide} className="my-pill" />
+  <button onPointerEnter={(e) => glide.enter(e.currentTarget)}>Item 1</button>
+</nav>;
+```

package/src/motion/motion-timing.ts

@@ -1,6 +1,6 @@
-import { UIMotion, type MotionTransition } from '../tokens/motion-tokens';
 import type { DurationToken, EaseToken } from '../tokens/motion-scale';
-import { resolveDirection, type DisableableAnimation } from './timing';
+import { UIMotion, type MotionTransition } from '../tokens/motion-tokens';
+import { resolveDirection, type DisableableAnimation, type TimingDirection } from './timing';
 
 export interface DirectionDefault {
   duration: DurationToken;
@@ -23,7 +23,7 @@ export function resolveMotionTiming(
 ): MotionTimings {
   if (animation === null) return { open: { duration: 0 }, close: { duration: 0 } };
 
-  const build = (dir: 'open' | 'close'): MotionTransition => {
+  const build = (dir: TimingDirection): MotionTransition => {
     const durToken = (animation && resolveDirection(animation.duration, dir)) || defaults[dir].duration;
     const easeToken = (animation && resolveDirection(animation.ease, dir)) || defaults[dir].ease;
     return { duration: UIMotion.dur[durToken], ease: UIMotion.ease[easeToken] };

package/src/motion/presence.tsx

@@ -2,8 +2,8 @@
 
 import {
   Children,
-  Fragment,
   createElement,
+  Fragment,
   isValidElement,
   useEffect,
   useRef,
@@ -11,6 +11,7 @@ import {
   type ReactElement,
   type ReactNode,
 } from 'react';
+
 import { PresenceContext } from './presence-context';
 
 interface Entry {
@@ -20,6 +21,7 @@ interface Entry {
 }
 
 type Claims = Map<string, Set<object>>;
+type Latest = Map<string, ReactElement>;
 
 interface Tracked {
   shown: Entry[];
@@ -34,13 +36,14 @@ function toEntries(children: ReactNode): Entry[] {
   return out;
 }
 
-function withExiting(previous: Entry[], incoming: Entry[], claims: Claims): Entry[] {
+function withExiting(previous: Entry[], incoming: Entry[], claims: Claims, latest: Latest): Entry[] {
   const live = new Set(incoming.map((entry) => entry.key));
   const merged: Entry[] = incoming.map((entry) => ({ ...entry }));
   previous.forEach((entry, index) => {
     if (live.has(entry.key)) return;
     if (!claims.get(entry.key)?.size) return;
-    merged.splice(index, 0, entry.exiting ? entry : { ...entry, exiting: true });
+    const node = latest.get(entry.key) ?? entry.node;
+    merged.splice(index, 0, entry.exiting ? entry : { ...entry, node, exiting: true });
   });
   return merged;
 }
@@ -60,6 +63,8 @@ export function Presence({ children, initial = true, mode = 'sync', onExitComple
   const incoming = toEntries(children);
   const signature = incoming.map((entry) => entry.key).join('|');
   const claims = useRef<Claims>(new Map());
+  const latest = useRef<Latest>(new Map());
+  for (const entry of incoming) latest.current.set(entry.key, entry.node);
   const [tracked, setTracked] = useState<Tracked>({ shown: incoming, signature });
   const bornAtMount = useRef(new Set(incoming.map((entry) => entry.key)));
   const wasExiting = useRef(false);
@@ -68,15 +73,17 @@ export function Presence({ children, initial = true, mode = 'sync', onExitComple
 
   let shown = tracked.shown;
   if (tracked.signature !== signature) {
-    shown = withExiting(tracked.shown, incoming, claims.current);
+    shown = withExiting(tracked.shown, incoming, claims.current, latest.current);
     setTracked({ shown, signature });
   }
 
-  const drop = (key: string) =>
+  const drop = (key: string) => {
+    latest.current.delete(key);
     setTracked((previous) => {
       const next = previous.shown.filter((entry) => entry.key !== key || !entry.exiting);
       return next.length === previous.shown.length ? previous : { ...previous, shown: next };
     });
+  };
 
   const claimExit = (key: string) => (): (() => void) => {
     let tokens = claims.current.get(key);

package/src/motion/presets.ts

@@ -0,0 +1,13 @@
+import type { Layer } from '../engine';
+
+type LayerTiming = Layer['timing'];
+
+export const popIn = (scale: number, timing: LayerTiming): Layer => ({ opacity: [0, 1], scale: [scale, 1], timing });
+
+export const popOut = (scale: number, timing: LayerTiming): Layer => ({ opacity: [0], scale: [scale], timing });
+
+export const slideIn = (distance: number, timing: LayerTiming): Layer => ({
+  x: [distance, 0],
+  opacity: [0, 1],
+  timing,
+});

package/src/motion/timing.ts

@@ -1,4 +1,5 @@
 import type { CSSProperties } from 'react';
+
 import type { DurationToken, EaseToken } from '../tokens/motion-scale';
 
 export type TimingDirection = 'open' | 'close';

package/src/motion/use-motion.ts

@@ -1,6 +1,7 @@
 'use client';
 
 import { useLayoutEffect, useRef, type RefObject } from 'react';
+
 import { animate, type Layer, type Playback } from '../engine';
 import { usePresence } from './presence-context';
 
@@ -34,6 +35,7 @@ export function useMotion(ref: RefObject<HTMLElement | null>, { animate, exit, i
   const presence = usePresence();
   const playing = useRef<Playback[]>([]);
   const mounted = useRef(false);
+  const exiting = useRef(false);
   const spec = useRef({ animate, exit, initial });
   spec.current = { animate, exit, initial };
   const release = useRef<(() => void) | null>(null);
@@ -64,11 +66,22 @@ export function useMotion(ref: RefObject<HTMLElement | null>, { animate, exit, i
   }, deps ?? []); // eslint-disable-line react-hooks/exhaustive-deps
 
   useLayoutEffect(() => {
-    if (presence.isPresent || !ownsExit) return;
     const el = ref.current;
+    if (presence.isPresent) {
+      if (!exiting.current) return;
+      exiting.current = false;
+      stop();
+      if (el) playing.current = run(spec.current.animate, el);
+      return;
+    }
+    if (!ownsExit) return;
+    exiting.current = true;
     stop();
-    playing.current = el ? run(spec.current.exit, el) : [];
-    allSettled(playing.current).then(() => release.current?.());
+    const exitPlays = el ? run(spec.current.exit, el) : [];
+    playing.current = exitPlays;
+    allSettled(exitPlays).then(() => {
+      if (playing.current === exitPlays) release.current?.();
+    });
   }, [presence.isPresent]); // eslint-disable-line react-hooks/exhaustive-deps
 
   useLayoutEffect(() => stop, []);

package/src/styles.css

@@ -1,11 +1,16 @@
 /* Zyncat UI base layer - import ONCE at your app root:  import '@zyncat/ui/styles.css';
    Fonts, design tokens (:root variables) and the shared `glass` utility.
 
+   Everything the library ships sits in the `zyncat` cascade layers, so any unlayered
+   rule in your own stylesheets beats the library without specificity games.
+
    Per-component CSS is NOT here on purpose: every component imports its own
    stylesheet, so the consumer's bundler code-splits and lazy-loads it with the
    component. This file is only the always-needed global layer.
    Order matters: fonts - primitives - semantics - shared utilities. */
 
+@layer zyncat.tokens, zyncat.components;
+
 @import './tokens/fonts.css';
 
 @import './tokens/color.css';

package/src/tokens/avatar.css

@@ -1,20 +1,24 @@
 /* Avatar tokens - reserved identity palette + lit-from-above face finish. */
 
-:root {
-  --avatar-1-bg: oklch(0.945 0.04 250);
-  --avatar-1-fg: oklch(0.45 0.08 250);
-  --avatar-2-bg: oklch(0.945 0.04 292);
-  --avatar-2-fg: oklch(0.45 0.08 292);
-  --avatar-3-bg: oklch(0.945 0.04 334);
-  --avatar-3-fg: oklch(0.45 0.08 334);
-  --avatar-4-bg: oklch(0.945 0.04 5);
-  --avatar-4-fg: oklch(0.45 0.08 5);
-  --avatar-5-bg: oklch(0.945 0.04 55);
-  --avatar-5-fg: oklch(0.45 0.08 55);
-  --avatar-6-bg: oklch(0.945 0.04 125);
-  --avatar-6-fg: oklch(0.45 0.08 125);
+@layer zyncat.tokens, zyncat.components;
 
-  /* Surface finish - white sheen from top, cool near-black shade from bottom (never pure black). */
-  --avatar-sheen: oklch(1 0 0 / 0.35);
-  --avatar-shade: oklch(0.225 0.012 264 / 0.05);
+@layer zyncat.tokens {
+  :root {
+    --avatar-1-bg: oklch(0.945 0.04 250);
+    --avatar-1-fg: oklch(0.45 0.08 250);
+    --avatar-2-bg: oklch(0.945 0.04 292);
+    --avatar-2-fg: oklch(0.45 0.08 292);
+    --avatar-3-bg: oklch(0.945 0.04 334);
+    --avatar-3-fg: oklch(0.45 0.08 334);
+    --avatar-4-bg: oklch(0.945 0.04 5);
+    --avatar-4-fg: oklch(0.45 0.08 5);
+    --avatar-5-bg: oklch(0.945 0.04 55);
+    --avatar-5-fg: oklch(0.45 0.08 55);
+    --avatar-6-bg: oklch(0.945 0.04 125);
+    --avatar-6-fg: oklch(0.45 0.08 125);
+
+    /* Surface finish - white sheen from top, cool near-black shade from bottom (never pure black). */
+    --avatar-sheen: oklch(1 0 0 / 0.35);
+    --avatar-shade: oklch(0.225 0.012 264 / 0.05);
+  }
 }

package/src/tokens/color.css

@@ -1,58 +1,69 @@
-/* Color primitives - the closed neutral + status ramps. */
-
-:root {
-  --gray-0: oklch(1 0 0);
-  --gray-25: oklch(0.992 0.0015 264);
-  --gray-50: oklch(0.984 0.003 264);
-  --gray-100: oklch(0.968 0.004 264);
-  --gray-150: oklch(0.948 0.005 264);
-  --gray-200: oklch(0.922 0.006 264);
-  --gray-300: oklch(0.872 0.008 264);
-  --gray-400: oklch(0.765 0.01 264);
-  --gray-500: oklch(0.642 0.012 264);
-  --gray-600: oklch(0.532 0.013 264);
-  --gray-700: oklch(0.422 0.013 264);
-  --gray-800: oklch(0.305 0.012 264);
-  --gray-900: oklch(0.225 0.01 264);
-  --gray-950: oklch(0.165 0.008 264);
-
-  --teal-50: oklch(0.972 0.02 198);
-  --teal-100: oklch(0.935 0.04 198);
-  --teal-200: oklch(0.88 0.066 198);
-  --teal-300: oklch(0.795 0.092 198);
-  --teal-400: oklch(0.705 0.112 198);
-  --teal-500: oklch(0.63 0.118 198);
-  --teal-600: oklch(0.56 0.114 198);
-  --teal-700: oklch(0.478 0.1 198);
-  --teal-800: oklch(0.4 0.082 198);
-  --teal-900: oklch(0.32 0.062 198);
-
-  --green-50: oklch(0.965 0.028 152);
-  --green-500: oklch(0.62 0.13 152);
-  --green-600: oklch(0.548 0.122 152);
-  --green-700: oklch(0.462 0.1 152);
-
-  --amber-50: oklch(0.972 0.034 75);
-  --amber-500: oklch(0.76 0.14 75);
-  --amber-600: oklch(0.7 0.142 75);
-  --amber-700: oklch(0.56 0.118 75);
-
-  --red-50: oklch(0.968 0.02 27);
-  --red-300: oklch(0.8 0.09 27);
-  --red-400: oklch(0.64 0.2 27);
-  --red-500: oklch(0.602 0.196 27);
-  --red-600: oklch(0.545 0.196 27);
-  --red-700: oklch(0.478 0.172 27);
-
-  /* Wash tints - glassy active/selected fills that let the surface show through; low alpha per hue.
+/* Color primitives - the closed neutral + status ramps.
+   The neutral ramp is a cool ink gray: the accent hue (198) at whisper chroma throughout,
+   arced to peak at the mid steps (500-700) and fall away at both ends - chrome, fills and
+   text share one temperature with the teal accent instead of fighting it. The canvas is
+   pure white, so the ramp reads as ink on paper rather than a tinted wash; the light fills
+   (100-150) sit airy so a recessed well never turns into a heavy slab. Lightness is the
+   contrast spine - retune chroma freely, move an L step and every text-on-surface pair
+   moves with it. */
+
+@layer zyncat.tokens, zyncat.components;
+
+@layer zyncat.tokens {
+  :root {
+    --gray-0: oklch(1 0 0);
+    --gray-25: oklch(0.992 0.002 198);
+    --gray-50: oklch(0.984 0.003 198);
+    --gray-100: oklch(0.97 0.004 198);
+    --gray-150: oklch(0.954 0.005 198);
+    --gray-200: oklch(0.924 0.006 198);
+    --gray-300: oklch(0.874 0.007 198);
+    --gray-400: oklch(0.765 0.009 198);
+    --gray-500: oklch(0.642 0.011 198);
+    --gray-600: oklch(0.532 0.012 198);
+    --gray-700: oklch(0.422 0.012 198);
+    --gray-800: oklch(0.305 0.01 198);
+    --gray-900: oklch(0.225 0.008 198);
+    --gray-950: oklch(0.165 0.007 198);
+
+    --teal-50: oklch(0.972 0.02 198);
+    --teal-100: oklch(0.935 0.04 198);
+    --teal-200: oklch(0.88 0.066 198);
+    --teal-300: oklch(0.795 0.092 198);
+    --teal-400: oklch(0.705 0.112 198);
+    --teal-500: oklch(0.63 0.118 198);
+    --teal-600: oklch(0.56 0.114 198);
+    --teal-700: oklch(0.478 0.1 198);
+    --teal-800: oklch(0.4 0.082 198);
+    --teal-900: oklch(0.32 0.062 198);
+
+    --green-50: oklch(0.965 0.028 152);
+    --green-500: oklch(0.62 0.13 152);
+    --green-600: oklch(0.548 0.122 152);
+    --green-700: oklch(0.462 0.1 152);
+
+    --amber-50: oklch(0.972 0.034 75);
+    --amber-500: oklch(0.76 0.14 75);
+    --amber-600: oklch(0.7 0.142 75);
+    --amber-700: oklch(0.56 0.118 75);
+
+    --red-50: oklch(0.968 0.02 27);
+    --red-300: oklch(0.8 0.09 27);
+    --red-400: oklch(0.64 0.2 27);
+    --red-500: oklch(0.602 0.196 27);
+    --red-600: oklch(0.545 0.196 27);
+    --red-700: oklch(0.478 0.172 27);
+
+    /* Wash tints - glassy active/selected fills that let the surface show through; low alpha per hue.
      -strong is the press step of the gray wash (hover 6% < press 10%). */
-  --gray-wash: oklch(0.42 0.012 264 / 0.06);
-  --gray-wash-strong: oklch(0.42 0.012 264 / 0.1);
-  --teal-wash: oklch(0.63 0.118 198 / 0.05);
-  --green-wash: oklch(0.62 0.13 152 / 0.1);
-  --amber-wash: oklch(0.76 0.14 75 / 0.12);
-  --red-wash: oklch(0.602 0.196 27 / 0.1);
-
-  /* Cool near-black shadow ink - pure black looks muddy on a cool canvas. */
-  --shadow-rgb: 13 18 30;
+    --gray-wash: color-mix(in oklab, var(--gray-700) 6%, transparent);
+    --gray-wash-strong: color-mix(in oklab, var(--gray-700) 10%, transparent);
+    --teal-wash: oklch(0.63 0.118 198 / 0.05);
+    --green-wash: oklch(0.62 0.13 152 / 0.1);
+    --amber-wash: oklch(0.76 0.14 75 / 0.12);
+    --red-wash: oklch(0.602 0.196 27 / 0.1);
+
+    /* Cool near-black shadow ink - matches the cool neutral ramp on the white canvas. */
+    --shadow-rgb: 15 22 25;
+  }
 }