@tobiasoberpaul/mdk 0.2.0 → 0.4.0

package/README.md

@@ -23,7 +23,9 @@ toggle.addEventListener('click', () => motion.toggle());
 
 Your component manages layout, visibility, focus and accessibility. MDK handles the visual transition, including reversal and the system's reduced-motion preference.
 
-The library includes Grow, Extract, Morph, Slide and Content transitions. See the [library guide](https://github.com/TOberpaul/animations/blob/main/docs/LIBRARY.md) for the API, CSS tokens and integration patterns.
+For an existing popover or menu, use `createPresenceMotion` to connect its open and close signals. Use `resize: 'transform'` with `createGrowTransition` for local growth on a surface positioned by the host. [Integration guide](https://github.com/TOberpaul/animations/blob/main/docs/LIBRARY.md#animate-an-existing-component)
+
+The library includes Grow, Extract, Morph, Slide and Fade. See the [library guide](https://github.com/TOberpaul/animations/blob/main/docs/LIBRARY.md) for the API, CSS tokens and integration patterns.
 
 Coding assistants can access the MDK reference and integration examples through the public MCP server. See the [MCP setup](https://github.com/TOberpaul/animations/blob/main/docs/AI_INTEGRATION.md#hosted-mcp).
 

package/dist/behaviors.js

@@ -7,13 +7,11 @@ export const motionBehaviors = {
 };
 /** Canonical naming shared by declarative integration and consuming components. */
 export function getMotionKind(content) {
-    const names = [...Object.keys(motionBehaviors), 'liquid', 'content'];
+    const names = [...Object.keys(motionBehaviors), 'content'];
     const classes = names.filter(name => content.classList.contains(`motion-${name}`));
     const raw = content.dataset.motion ?? (classes.length === 1 ? classes[0] : undefined);
     if (raw === 'content')
         return 'fade';
-    if (raw === 'liquid')
-        return content.hasAttribute('data-motion-replace-trigger') ? 'morph' : 'extract';
     if (!raw || !Object.prototype.hasOwnProperty.call(motionBehaviors, raw))
         throw new Error('Set data-motion to grow, extract, morph, slide or fade, or use one matching motion-* class.');
     return raw;

package/dist/core/animation.js

@@ -52,7 +52,7 @@ export function createTransition(options, pattern, tracks, behavior = {}) {
                 }
                 const requestedEasing = token(content, `easing-${pattern}`);
                 const easing = CSS.supports('animation-timing-function', requestedEasing) ? requestedEasing : token(content, 'easing-standard');
-                const recipe = motionBehaviors[(pattern === 'scale' ? 'grow' : pattern === 'liquid' ? 'extract' : pattern === 'content' ? 'fade' : pattern)];
+                const recipe = motionBehaviors[(pattern === 'scale' ? 'grow' : pattern === 'transfer' ? 'extract' : pattern === 'content' ? 'fade' : pattern)];
                 const descriptions = tracks();
                 time *= behavior.durationScale?.() ?? 1;
                 const reveal = options.reveal ? (Array.isArray(options.reveal) ? options.reveal : [options.reveal]) : [];

package/dist/core/resize.d.ts

@@ -11,4 +11,4 @@ export interface ResizeOptions extends Options {
     overlay?: SVGSVGElement;
 }
 /** Shared physical resizing with a trigger edge or local origin. */
-export declare function createResizeTransition(options: ResizeOptions, pattern: 'morph' | 'scale'): Transition;
+export declare function createResizeTransition(options: ResizeOptions, pattern: 'morph' | 'scale', transform?: boolean): Transition;

package/dist/core/resize.js

@@ -1,10 +1,12 @@
 import { createTransition } from './animation.js';
 import { growthAnchor, growthInsets, localScale, morphGeometry, resizeGeometry } from './geometry.js';
-import { overshootToken, numberToken, token } from './tokens.js';
+import { lengthToken, overshootToken, numberToken, token } from './tokens.js';
 import { fixedContentTracks } from './content-layout.js';
 /** Shared physical resizing with a trigger edge or local origin. */
-export function createResizeTransition(options, pattern) {
+export function createResizeTransition(options, pattern, transform = false) {
     const { content, trigger, overlay } = options;
+    if (transform && overlay)
+        throw new Error('Transform Grow does not support an SVG surface overlay.');
     const sameElement = trigger === content;
     if (sameElement && options.initiallyOpen)
         throw new Error('A same-element morph must initialize in its closed layout.');
@@ -32,6 +34,8 @@ export function createResizeTransition(options, pattern) {
             }
             options.onStateChange?.(state);
         } }, pattern, () => {
+        if (transform)
+            return transformGrowTracks(options);
         const edgeGeometry = !trigger || sameElement ? undefined : morphGeometry(trigger, content);
         const factor = trigger ? undefined : numberToken(content, 'scale-from');
         const collapseAxis = !trigger ? factor === 0 ? options.axis ?? 'both' : undefined : sameElement ? undefined : edgeGeometry.from.height === 0 ? 'height' : 'width';
@@ -39,7 +43,7 @@ export function createResizeTransition(options, pattern) {
             left: to.left + to.width * (options.axis === 'height' ? 0 : 1 - factor) * ax, top: to.top + to.height * (options.axis === 'width' ? 0 : 1 - factor) * ay,
             width: to.width * (options.axis === 'height' ? 1 : factor), height: to.height * (options.axis === 'width' ? 1 : factor)
         });
-        const g = resizeGeometry(content, source, trigger ? edgeGeometry?.origin : token(content, 'scale-origin'), collapseAxis);
+        const g = resizeGeometry(content, source, trigger ? edgeGeometry?.origin : scaleOrigin(content), collapseAxis);
         const style = getComputedStyle(content);
         const base = style.transform;
         const shadow = style.boxShadow;
@@ -125,12 +129,103 @@ export function createResizeTransition(options, pattern) {
             result.push({ element: overlay, easing: 'linear', frames: frames.map(frame => ({
                     ...frame, visibility: 'visible'
                 })) });
-        if (options.backdrop) {
-            const native = options.backdrop === 'native';
-            const element = native ? content : options.backdrop;
-            const pseudoElement = native ? '::backdrop' : undefined;
-            result.push({ element, pseudoElement, easing, frames: [{ opacity: 0 }, { opacity: getComputedStyle(element, pseudoElement).opacity }] });
-        }
+        addBackdropTrack(result, options, easing);
         return result;
     }, { keepVisibleWhenClosed: sameElement });
 }
+function addBackdropTrack(tracks, { content, backdrop }, easing) {
+    if (!backdrop)
+        return;
+    const element = backdrop === 'native' ? content : backdrop;
+    const pseudoElement = backdrop === 'native' ? '::backdrop' : undefined;
+    tracks.push({ element, pseudoElement, easing, frames: [{ opacity: 0 }, { opacity: getComputedStyle(element, pseudoElement).opacity }] });
+}
+function scaleOrigin(content) {
+    const origin = token(content, 'scale-origin');
+    if (!/\b(?:inline|block)-(?:start|end)\b/.test(origin))
+        return origin;
+    const { direction, writingMode } = getComputedStyle(content);
+    const horizontal = writingMode === 'horizontal-tb';
+    const inline = horizontal ? ['left', 'right'] : writingMode === 'sideways-lr' ? ['bottom', 'top'] : ['top', 'bottom'];
+    if (direction === 'rtl')
+        inline.reverse();
+    const block = horizontal ? ['top', 'bottom'] : writingMode.endsWith('-rl') ? ['right', 'left'] : ['left', 'right'];
+    return origin.replace(/\b(inline|block)-(start|end)\b/g, (_, axis, edge) => (axis === 'inline' ? inline : block)[edge === 'start' ? 0 : 1]);
+}
+function measureScaleOrigin(content, style, origin, width, height) {
+    const probe = content.ownerDocument.createElement('span');
+    probe.style.cssText = 'all:initial;position:fixed;visibility:hidden;pointer-events:none;transition:none!important;animation:none!important';
+    for (const name of ['font-size', 'font-family', 'line-height']) {
+        probe.style.setProperty(name, style.getPropertyValue(name));
+    }
+    const contentBox = style.transformBox === 'content-box' || style.transformBox === 'fill-box';
+    const inset = (side) => contentBox
+        ? parseFloat(style.getPropertyValue('padding-' + side)) + parseFloat(style.getPropertyValue('border-' + side + '-width'))
+        : 0;
+    const left = inset('left'), top = inset('top');
+    probe.style.width = `${Math.max(0, width - left - inset('right'))}px`;
+    probe.style.height = `${Math.max(0, height - top - inset('bottom'))}px`;
+    const read = () => getComputedStyle(probe).transformOrigin.split(' ').map(parseFloat);
+    let hostOrigin = style.transformOrigin.split(' ').map(parseFloat);
+    const parent = contentBox ? content : content.ownerDocument.body;
+    // Resolve keywords and percentages without starting a CSS transition on the host surface.
+    parent.appendChild(probe);
+    try {
+        // Resolved host styles can report percentages in border-box pixels even
+        // when transforms use the content box. Inherit onto the sized probe.
+        if (contentBox) {
+            probe.style.setProperty('transform-origin', 'inherit', 'important');
+            hostOrigin = read();
+        }
+        probe.style.setProperty('transform-origin', origin, 'important');
+        const [x, y] = read();
+        return { x: x + left, y: y + top, dx: x - hostOrigin[0], dy: y - hostOrigin[1] };
+    }
+    finally {
+        probe.remove();
+    }
+}
+function transformGrowTracks(options) {
+    const { content, axis } = options;
+    const style = getComputedStyle(content);
+    const opacity = style.opacity;
+    const origin = scaleOrigin(content);
+    if (!CSS.supports('transform-origin', origin))
+        throw new Error('Invalid --motion-scale-origin.');
+    const { width, height } = localScale(content, content.getBoundingClientRect());
+    if (!width || !height)
+        throw new Error('Grow content must be measurable before animation.');
+    const { x, y, dx, dy } = measureScaleOrigin(content, style, origin, width, height);
+    const end = numberToken(content, 'scale-geometry-end');
+    if (end <= 0 || end > 1)
+        throw new Error('Scale geometry end must satisfy 0 < end <= 1.');
+    const requested = token(content, 'easing-scale');
+    const easing = CSS.supports('animation-timing-function', requested) ? requested : token(content, 'easing-standard');
+    const from = numberToken(content, 'scale-from');
+    const frame = (offset, sx, sy) => ({
+        offset, easing,
+        // Append a local scale around the motion origin while preserving the host origin.
+        transform: `translate(${dx * (1 - sx)}px, ${dy * (1 - sy)}px) scale(${sx}, ${sy})`,
+    });
+    const frames = [frame(0, axis === 'height' ? 1 : from, axis === 'width' ? 1 : from)];
+    const overshoot = Math.min(overshootToken(content, 'scale-overshoot', width, height), lengthToken(content, 'overshoot-max'));
+    if (overshoot > 0) {
+        const peak = numberToken(content, 'scale-peak-offset');
+        if (peak <= 0 || peak >= end)
+            throw new Error('Scale peak must satisfy 0 < peak < geometry end.');
+        frames.push(frame(peak, axis === 'height' ? 1 : 1 + overshoot / Math.max(Math.abs(x), Math.abs(width - x)), axis === 'width' ? 1 : 1 + overshoot / Math.max(Math.abs(y), Math.abs(height - y))));
+    }
+    frames.push(frame(end, 1, 1));
+    if (end < 1)
+        frames.push(frame(1, 1, 1));
+    const tracks = [
+        { element: content, frames, easing: 'linear', composite: 'add' },
+        { element: content, easing: 'linear', frames: [
+                { offset: 0, easing, opacity: numberToken(content, 'scale-opacity') },
+                { offset: end, opacity },
+                ...(end < 1 ? [{ offset: 1, opacity }] : []),
+            ] },
+    ];
+    addBackdropTrack(tracks, options, easing);
+    return tracks;
+}

package/dist/core/tokens.js

@@ -45,9 +45,9 @@ export function lengthToken(element, name) {
 }
 /** Proportional overshoot per edge, capped by the pattern's CSS length budget. */
 export function overshootToken(element, name, width, height) {
-    const percentage = token(element, 'overshoot-min');
+    const percentage = getComputedStyle(element).getPropertyValue('--motion-overshoot-ratio').trim() || token(element, 'overshoot-min');
     if (!/^\d+(?:\.\d+)?%$/.test(percentage))
-        throw new Error('--motion-overshoot-min must be a non-negative percentage.');
+        throw new Error('--motion-overshoot-ratio must be a non-negative percentage.');
     const style = getComputedStyle(element);
     const w = width ?? parseFloat(style.width), h = height ?? parseFloat(style.height);
     return Math.min(Math.min(w, h) * parseFloat(percentage) / 100, lengthToken(element, name));

package/dist/index.d.ts

@@ -1,6 +1,4 @@
 export { createMorphTransition } from './transitions/morph.js';
-export { createLiquidMorphTransition } from './transitions/liquid.js';
-export type { LiquidMorphOptions, LiquidMorphTransition } from './transitions/liquid.js';
 export type { MorphOptions } from './transitions/morph.js';
 export { createSlideTransition } from './transitions/slide.js';
 export type { SlideOptions } from './transitions/slide.js';

package/dist/index.js

@@ -1,5 +1,4 @@
 export { createMorphTransition } from './transitions/morph.js';
-export { createLiquidMorphTransition } from './transitions/liquid.js';
 export { createSlideTransition } from './transitions/slide.js';
 export { createScaleTransition } from './transitions/scale.js';
 export { createContentTransition } from './transitions/content.js';

package/dist/layout.js

@@ -10,6 +10,8 @@ export function captureMotionLayout(element) {
 /** Animate a component-owned CSS layout change from its captured visual state. */
 export function animateMotionLayout(element, from) {
     active.get(element)?.cancel();
+    if (typeof element.animate !== 'function')
+        return () => { };
     const to = captureMotionLayout(element);
     if (element.ownerDocument.defaultView.matchMedia('(prefers-reduced-motion: reduce)').matches || duration(element, 'morph') === 0)
         return () => { };

package/dist/presence.d.ts

@@ -5,6 +5,8 @@ export interface PresenceMotionOptions extends Pick<Options, 'initiallyOpen'> {
     /** Supply only if the integration can synchronously show and hide the surface.
      * Without this callback, call setOpen(true) after the host has shown the surface. */
     setPresent?(present: boolean): void;
+    /** Reflect data-motion-state on this surface. Its CSS must keep the surface visible during closing. */
+    stateTarget?: HTMLElement;
 }
 export interface PresenceMotion {
     readonly state: MotionState;

package/dist/presence.js

@@ -1,19 +1,25 @@
 /** Drive MDK from a component's existing open/close signals. */
 export function createPresenceMotion(options) {
-    const { createTransition, setPresent } = options;
+    const { createTransition, setPresent, stateTarget } = options;
+    const stateAttribute = 'data-motion-state';
+    const originalState = stateTarget?.getAttribute(stateAttribute);
     let open = options.initiallyOpen ?? false;
     let destroyed = false;
     let controller;
-    if (setPresent) {
+    if (setPresent || stateTarget) {
         controller = createTransition({
             initiallyOpen: open,
             onStateChange(state) {
+                if (state === 'destroyed')
+                    return;
+                stateTarget?.setAttribute(stateAttribute, state);
                 if (state === 'opening')
-                    setPresent(true);
+                    setPresent?.(true);
                 if (state === 'closed')
-                    setPresent(false);
+                    setPresent?.(false);
             }
         });
+        stateTarget?.setAttribute(stateAttribute, controller.state);
     }
     return {
         get state() {
@@ -29,7 +35,7 @@ export function createPresenceMotion(options) {
                 controller ?? (controller = createTransition({ initiallyOpen: false }));
                 controller.open();
             }
-            else if (setPresent) {
+            else if (setPresent || stateTarget) {
                 controller?.close();
             }
             else {
@@ -44,6 +50,10 @@ export function createPresenceMotion(options) {
             destroyed = true;
             const pendingExit = controller?.state === 'closing';
             controller?.destroy();
+            if (originalState == null)
+                stateTarget?.removeAttribute(stateAttribute);
+            else
+                stateTarget?.setAttribute(stateAttribute, originalState);
             if (pendingExit)
                 setPresent?.(false);
         }

package/dist/styles/motion.css

@@ -58,19 +58,19 @@
   --motion-scale-origin: center center;
   --motion-slide-distance: 100%;
   --motion-slide-peak-offset: .8;
-  --motion-duration-liquid: var(--motion-duration);
-  --motion-easing-liquid: var(--motion-easing-standard);
-  --motion-liquid-geometry-end: .8;
-  --motion-liquid-reveal-offset: .3;
-  --motion-liquid-reveal-end: var(--motion-liquid-geometry-end);
-  --motion-liquid-reveal-blur: var(--motion-reveal-blur);
-  --motion-liquid-volume-offset: .18;
-  --motion-liquid-source-hide-start: var(--motion-liquid-reveal-offset);
-  --motion-liquid-source-hide-end: var(--motion-liquid-reveal-end);
-  --motion-liquid-source-blur: var(--motion-liquid-reveal-blur);
-  --motion-liquid-peak-offset: .5;
+  --motion-duration-transfer: var(--motion-duration);
+  --motion-easing-transfer: var(--motion-easing-standard);
+  --motion-transfer-geometry-end: .8;
+  --motion-transfer-reveal-offset: .3;
+  --motion-transfer-reveal-end: var(--motion-transfer-geometry-end);
+  --motion-transfer-reveal-blur: var(--motion-reveal-blur);
+  --motion-transfer-volume-offset: .18;
+  --motion-transfer-source-hide-start: var(--motion-transfer-reveal-offset);
+  --motion-transfer-source-hide-end: var(--motion-transfer-reveal-end);
+  --motion-transfer-source-blur: var(--motion-transfer-reveal-blur);
+  --motion-transfer-peak-offset: .5;
   --motion-overshoot-max: .75rem;
 }
 @media (prefers-reduced-motion: reduce) {
-  :root { --motion-duration-morph: 0ms; --motion-duration-slide: 0ms; --motion-duration-scale: 0ms; --motion-duration-backdrop: 0ms; }
+  :root { --motion-duration-morph: 0ms; --motion-duration-slide: 0ms; --motion-duration-scale: 0ms; --motion-duration-backdrop: 0ms; --motion-duration-content: 0ms; --motion-duration-transfer: 0ms; }
 }

package/dist/transitions/extract.d.ts

@@ -1,5 +1,5 @@
-import { type LiquidMorphOptions } from './liquid.js';
+import { type SurfaceTransferOptions } from './surface-transfer.js';
 import type { Transition } from '../core/lifecycle.js';
-export type ExtractOptions = Omit<LiquidMorphOptions, 'replaceTrigger'>;
+export type ExtractOptions = Omit<SurfaceTransferOptions, 'replaceTrigger'>;
 /** Extract a new surface while retaining the original trigger. */
 export declare function createExtractTransition(options: ExtractOptions): Transition;

package/dist/transitions/extract.js

@@ -1,5 +1,5 @@
-import { createLiquidMorphTransition } from './liquid.js';
+import { createSurfaceTransfer } from './surface-transfer.js';
 /** Extract a new surface while retaining the original trigger. */
 export function createExtractTransition(options) {
-    return createLiquidMorphTransition({ ...options, replaceTrigger: false });
+    return createSurfaceTransfer({ ...options, replaceTrigger: false });
 }

package/dist/transitions/grow.d.ts

@@ -1,6 +1,8 @@
 import { type ResizeOptions } from '../core/resize.js';
 import type { Transition } from '../core/lifecycle.js';
 export interface GrowOptions extends ResizeOptions {
+    /** Use visual scaling for local Grow. Trigger-edge Grow always uses physical resizing. */
+    resize?: 'metrics' | 'transform';
 }
 /** Grow from a trigger edge, or from the configured local origin without a trigger. */
 export declare function createGrowTransition(options: GrowOptions): Transition;

package/dist/transitions/grow.js

@@ -1,5 +1,5 @@
 import { createResizeTransition } from '../core/resize.js';
 /** Grow from a trigger edge, or from the configured local origin without a trigger. */
 export function createGrowTransition(options) {
-    return createResizeTransition(options, options.trigger ? 'morph' : 'scale');
+    return createResizeTransition(options, options.trigger ? 'morph' : 'scale', !options.trigger && options.resize === 'transform');
 }

package/dist/transitions/morph.d.ts

@@ -1,5 +1,5 @@
-import { type LiquidMorphOptions } from './liquid.js';
+import { type SurfaceTransferOptions } from './surface-transfer.js';
 import type { Transition } from '../core/lifecycle.js';
-export type MorphOptions = Omit<LiquidMorphOptions, 'replaceTrigger'>;
+export type MorphOptions = Omit<SurfaceTransferOptions, 'replaceTrigger'>;
 /** The source becomes the target; the integration manages original-trigger visibility. */
 export declare function createMorphTransition(options: MorphOptions): Transition;

package/dist/transitions/morph.js

@@ -1,5 +1,5 @@
-import { createLiquidMorphTransition } from './liquid.js';
+import { createSurfaceTransfer } from './surface-transfer.js';
 /** The source becomes the target; the integration manages original-trigger visibility. */
 export function createMorphTransition(options) {
-    return createLiquidMorphTransition({ ...options, replaceTrigger: true });
+    return createSurfaceTransfer({ ...options, replaceTrigger: true });
 }

package/dist/transitions/scale.d.ts

@@ -3,5 +3,5 @@ export interface ScaleOptions extends Options {
     backdrop?: HTMLElement | 'native';
     axis?: 'width' | 'height';
 }
-/** The same resize behavior, starting at the component's configured origin. */
+/** @deprecated Use createGrowTransition for local growth. */
 export declare function createScaleTransition(options: ScaleOptions): Transition;

package/dist/transitions/scale.js

@@ -1,5 +1,5 @@
 import { createGrowTransition } from './grow.js';
-/** The same resize behavior, starting at the component's configured origin. */
+/** @deprecated Use createGrowTransition for local growth. */
 export function createScaleTransition(options) {
     return createGrowTransition(options);
 }

package/dist/transitions/{liquid.d.ts → surface-transfer.d.ts}

@@ -1,5 +1,5 @@
 import type { Options, Transition } from '../core/lifecycle.js';
-export interface LiquidMorphOptions extends Options {
+export interface SurfaceTransferOptions extends Options {
     /** Distinct node: retain the source. Same node as content: become the target.
      * For the same node, prepare the expanded layout synchronously on opening
      * and restore its compact layout only on closed. Initialize closed. */
@@ -8,6 +8,5 @@ export interface LiquidMorphOptions extends Options {
      * trigger. The component hides/shows that trigger in onStateChange. */
     replaceTrigger?: boolean;
 }
-export type LiquidMorphTransition = Transition;
-/** One liquid behavior for separate surfaces and a trigger becoming the target. */
-export declare function createLiquidMorphTransition(options: LiquidMorphOptions): LiquidMorphTransition;
+/** Shared surface and foreground animation for Extract and Morph. */
+export declare function createSurfaceTransfer(options: SurfaceTransferOptions): Transition;

package/dist/transitions/{liquid.js → surface-transfer.js}

@@ -38,12 +38,12 @@ function visibleBackground(element) {
     const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
     return `rgb(${r},${g},${b})`;
 }
-/** One liquid behavior for separate surfaces and a trigger becoming the target. */
-export function createLiquidMorphTransition(options) {
+/** Shared surface and foreground animation for Extract and Morph. */
+export function createSurfaceTransfer(options) {
     const sameElement = options.trigger === options.content;
     const replacesTrigger = sameElement || options.replaceTrigger;
     if (replacesTrigger && options.initiallyOpen)
-        throw new Error('A replacing liquid morph must initialize in its closed layout.');
+        throw new Error('A replacing transfer morph must initialize in its closed layout.');
     let previous = options.initiallyOpen ? 'open' : 'closed';
     let closed;
     let overlay;
@@ -78,7 +78,7 @@ export function createLiquidMorphTransition(options) {
                 remove();
             }
             options.onStateChange?.(state);
-        } }, 'liquid', () => {
+        } }, 'transfer', () => {
         remove();
         const { content, trigger } = options;
         const box = content.getBoundingClientRect(), source = replacesTrigger ? closed.rect : trigger.getBoundingClientRect();
@@ -88,7 +88,7 @@ export function createLiquidMorphTransition(options) {
         const width = px(style.width) + (style.boxSizing === 'border-box' ? 0 : extraX);
         const height = px(style.height) + (style.boxSizing === 'border-box' ? 0 : extraY);
         if (!width || !height || !source.width || !source.height)
-            throw new Error('Liquid morph elements must be measurable.');
+            throw new Error('Surface transfer elements must be measurable.');
         const scaleX = box.width / width, scaleY = box.height / height;
         const left = (source.left - box.left) / scaleX, top = (source.top - box.top) / scaleY;
         const sw = source.width / scaleX, sh = source.height / scaleY;
@@ -102,10 +102,10 @@ export function createLiquidMorphTransition(options) {
         const borderFrom = replacesTrigger ? closed.border : triggerStyle.borderTopColor, borderTo = style.borderTopColor;
         const swell = overshootToken(content, 'overshoot-max', sw, sh);
         const overshoot = overshootToken(content, 'overshoot-max', width, height);
-        const volume = numberToken(content, 'liquid-volume-offset'), peak = numberToken(content, 'liquid-peak-offset');
-        const end = numberToken(content, 'liquid-geometry-end');
+        const volume = numberToken(content, 'transfer-volume-offset'), peak = numberToken(content, 'transfer-peak-offset');
+        const end = numberToken(content, 'transfer-geometry-end');
         if (!(swell >= 0 && overshoot >= 0 && volume > 0 && volume < peak && peak < end && end < 1))
-            throw new Error('Invalid liquid geometry tokens.');
+            throw new Error('Invalid transfer geometry tokens.');
         // The initial volume phase swells the trigger symmetrically. Only the target
         // grows away from its component-owned anchor; preserve their envelope.
         const anchor = explicitMotionAnchor(content) ?? growthAnchor(source, box);
@@ -140,9 +140,9 @@ export function createLiquidMorphTransition(options) {
         triggerCopy = replacesTrigger ? closed.copy.cloneNode(true) : copyTrigger(trigger);
         Object.assign(triggerCopy.style, { position: 'absolute', left: (left - px(style.borderLeftWidth)) + 'px', top: (top - px(style.borderTopWidth)) + 'px', width: sw + 'px', height: sh + 'px', boxSizing: 'border-box', margin: '0', transform: 'none', transition: 'none', animation: 'none', background: 'transparent', borderColor: 'transparent', boxShadow: 'none', pointerEvents: 'none', zIndex: '0' });
         content.append(triggerCopy);
-        const revealStart = numberToken(content, 'liquid-reveal-offset'), revealEnd = numberToken(content, 'liquid-reveal-end');
+        const revealStart = numberToken(content, 'transfer-reveal-offset'), revealEnd = numberToken(content, 'transfer-reveal-end');
         if (revealStart < 0 || revealStart >= revealEnd || revealEnd > 1)
-            throw new Error('Invalid liquid reveal offsets.');
+            throw new Error('Invalid transfer reveal offsets.');
         const clipFrames = [];
         // Include the exact volume/peak poses, so frame inspection
         // reach the configured percentage without resampling error.
@@ -186,13 +186,13 @@ export function createLiquidMorphTransition(options) {
         ];
         const overlapsTarget = source.left < box.right && source.right > box.left && source.top < box.bottom && source.bottom > box.top;
         if (replacesTrigger || overlapsTarget) {
-            const hideStart = numberToken(content, 'liquid-source-hide-start');
-            const hideEnd = numberToken(content, 'liquid-source-hide-end');
-            const blur = token(content, 'liquid-source-blur');
+            const hideStart = numberToken(content, 'transfer-source-hide-start');
+            const hideEnd = numberToken(content, 'transfer-source-hide-end');
+            const blur = token(content, 'transfer-source-blur');
             if (hideStart < 0 || hideStart >= hideEnd || hideEnd > 1)
-                throw new Error('Liquid source hide offsets must satisfy 0 <= start < end <= 1.');
+                throw new Error('Transfer source hide offsets must satisfy 0 <= start < end <= 1.');
             if (!CSS.supports('filter', `blur(${blur})`))
-                throw new Error('Liquid source blur must be a valid non-negative CSS length.');
+                throw new Error('Transfer source blur must be a valid non-negative CSS length.');
             const sourceStyle = getComputedStyle(triggerCopy), filter = sourceStyle.filter;
             const blurred = `${filter === 'none' ? '' : `${filter} `}blur(${blur})`;
             // Crossfade both contents over the same interval, without moving the

package/docs/LIBRARY.md

@@ -23,14 +23,14 @@ content, unless reflow is intentional (the three-column layout).
 The package name is `@tobiasoberpaul/mdk`.
 
 ```ts
-import { createScaleTransition } from '@tobiasoberpaul/mdk';
+import { createGrowTransition } from '@tobiasoberpaul/mdk';
 import '@tobiasoberpaul/mdk/motion.css';
 
 const surface = document.querySelector<HTMLElement>('#dialog')!;
 const trigger = document.querySelector<HTMLButtonElement>('#open')!;
 surface.inert = true;
 
-const transition = createScaleTransition({
+const transition = createGrowTransition({
   content: surface,
   reveal: [...surface.children].filter((node): node is HTMLElement => node instanceof HTMLElement),
   onStateChange(state) {
@@ -104,21 +104,53 @@ mechanism in this callback. The same surface must remain mounted through exit.
 Keep requested open state separate from visual presence so a new open request
 can reverse an in-progress exit.
 
-If the host hides itself immediately, omit `setPresent`. Call `setOpen(true)`
+If the host can hold presence through CSS, pass `stateTarget: surface`. The
+adapter reflects `opening`, `open`, `closing` and `closed` in
+`data-motion-state` and restores any previous value on teardown. Let the
+host's CSS keep the surface rendered at its normal open opacity during
+`closing`, so the animation can measure and fade it.
+Forward the host's requested state, independently of the held visibility,
+so reopening can reverse the exit. Keep focus and interaction rules in the host.
+
+If the host hides itself immediately, omit both `setPresent` and `stateTarget`. Call `setOpen(true)`
 after the host has made its surface visible and positioned it, then call
 `setOpen(false)` when it hides. This mode plays entry and releases the effect
 on close. It requires a reliable signal from the host integration. Disable any
 competing host animation on the same surface.
 
+## Grow on a host-positioned surface
+
+For a popover positioned by its host, opt into transform-based local Grow:
+
+```ts
+const motion = createGrowTransition({ content: surface, resize: 'transform' });
+```
+
+Use `--motion-scale-origin: inline-end block-start` for logical placement in
+either text direction or writing mode. Use `right top` for a physical anchor.
+Omit `trigger` when the component owns positioning and you want local growth.
+Pass `trigger` only to grow from the trigger's edge. Use
+`--motion-scale-from` for its starting scale. MDK adds the animation to the
+host transform and leaves layout dimensions and insets alone. The whole surface
+scales visually, including its border and content. Set `--motion-overshoot-max: 0`
+to turn off overshoot. This mode works with `createPresenceMotion`.
+MDK resolves the motion origin without changing the surface's own
+`transform-origin`, so host CSS transitions on that property stay independent.
+The anchor follows the surface's `transform-box`, including `content-box`.
+Origin and dimensions are measured at the start of each animation.
+
+The default `resize: 'metrics'` still resizes the actual surface. Grow with a
+`trigger` continues to use trigger-edge geometry. The local transform mode
+supports HTML surfaces without an SVG overlay.
+
 ## Public behavior factories
 
 | Factory | Behavior | Required additions to shared options |
 | --- | --- | --- |
-| `createGrowTransition` | Grow from a configured origin or trigger edge | Optional `trigger`, `axis`, `backdrop` |
-| `createScaleTransition` | Origin-based Grow compatibility factory | Optional `axis`, `backdrop` |
+| `createGrowTransition` | Grow from a configured origin or trigger edge | Optional `trigger`, `axis`, `backdrop`, `resize` |
+| `createScaleTransition` | Deprecated alias for local Grow | Optional `axis`, `backdrop` |
 | `createExtractTransition` | Extract a new surface while retaining the trigger | `trigger` |
 | `createMorphTransition` | Transform the trigger into the target surface | `trigger` |
-| `createLiquidMorphTransition` | Source volume → encompassing surface → target | `trigger`; optional `replaceTrigger` |
 | `createSlideTransition` | Bounded translate3d entry or two-pane shift | Optional `side`, `mode`, `outgoing`, `backdrop` |
 | `createContentTransition` | Fixed slide + blur + fade | Optional `items`, `reveal`, `timing` |
 | `createMotion` | Selects a factory from markup | See declarative integration below |
@@ -132,7 +164,7 @@ opacity and blur. Explicit `items` for Content must not be nested.
 
 ### Grow
 
-`createScaleTransition` preserves the component's base transform and reads its
+`createGrowTransition` preserves the component's base transform and reads its
 origin from `--motion-scale-origin`. The library default is `.92` for
 `--motion-scale-from`; the demos set `0` for fully collapsed opening.
 
@@ -158,16 +190,17 @@ Public factories, declarative markup and example titles use the same meanings:
 
 Migration: the earlier `createMorphTransition` name referred to trigger-edge Grow.
 Use `createGrowTransition` for that old behavior. `createMorphTransition` now
-means replacing Morph, consistent with the examples. The lower-level
-`createLiquidMorphTransition` remains available with an explicit
-`replaceTrigger` flag, and `createScaleTransition` remains an origin-Grow alias.
+means replacing Morph, consistent with the examples. To migrate from the former
+Liquid API or markup, use Extract when the source stays visible and Morph when
+the source becomes the target. Use the `--motion-transfer-*` and
+`--motion-duration-transfer` tokens for the shared animation settings.
 
 Extract retains the original trigger. Replacing Morph snapshots its foreground,
 then crossfades that foreground into target content while one material surface
 moves between the geometries. The integration hides/inerts the real trigger
 until closed and restores it afterward. This avoids nested interactive controls.
 
-Liquid animates a temporary HTML surface with CSS dimensions, corners, background and borders. It removes the temporary surface and foreground
+Extract and Morph animate a temporary HTML surface with CSS dimensions, corners, background and borders. They remove the temporary surface and foreground
 copy at rest. The resting UI is the real HTML component. Trigger swelling is a
 phase of the click animation; there is no press/hold feature or press/release API.
 
@@ -178,7 +211,7 @@ the right edge. Both buttons remain visible and the main action is independent.
 
 ### Material source and composite inputs
 
-Liquid reads material values from `content`. If a component wrapper is
+Extract and Morph read material values from `content`. If a component wrapper is
 transparent/borderless but a nested input paints the real material, explicitly
 prepare a surface with the input's background, border and radius before the
 motion snapshot. During travel, prevent the inner control from painting a second
@@ -234,12 +267,10 @@ const transition = createMotion({
 | `data-motion-axis` | Grow axis: `width` or `height` |
 | `data-motion-side` | Slide entry side |
 | `data-motion-timing` | Content: `per-item` (default) or `total` |
-| `data-motion-replace-trigger` | Presence enables replacing Liquid |
 
 An explicit `data-motion` takes precedence over classes. Without it, use exactly
 one matching class. Declarative `morph` selects the replacing Morph factory directly.
-The old `liquid` / `motion-liquid` spelling remains a compatibility path; its
-`data-motion-replace-trigger` flag retains its original meaning. Recreate the controller to change behavior after
+Recreate the controller to change behavior after
 initialization. Change CSS tokens for per-trip visual parameters.
 
 ## Content progression and ordering
@@ -333,9 +364,9 @@ can be overridden locally on a surface or globally.
 
 | Token | Library default / meaning |
 | --- | --- |
-| `--motion-duration` | `300ms`; aliases for morph, scale, liquid, slide, content, backdrop |
+| `--motion-duration` | `300ms`; aliases for morph, scale, transfer, slide, content, backdrop |
 | `--motion-easing-standard` | `cubic-bezier(.42, 0, .58, 1)`; symmetric open/close |
-| `--motion-overshoot-min` | `15%` of the surface's shorter side |
+| `--motion-overshoot-ratio` | `15%` of the surface's shorter side by default. When unset, reads the legacy `--motion-overshoot-min` token. |
 | `--motion-overshoot-max` | `.75rem` cap shared by trigger and target; morph/scale alias this |
 | `--motion-content-progressive` | `1` (enabled by default); set to `0` to disable |
 | `--motion-content-stagger` | `.08`, fraction of base duration for Content |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tobiasoberpaul/mdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "files": [
     "dist",
@@ -14,7 +14,7 @@
     "./motion.css": "./dist/styles/motion.css"
   },
   "scripts": {
-    "build": "tsc && node scripts/copy-css.mjs",
+    "build": "node scripts/clean-dist.mjs && tsc && node scripts/copy-css.mjs",
     "build:examples": "node scripts/build-db-react.mjs && node scripts/build-shadcn.mjs",
     "build:shadcn": "node scripts/build-shadcn.mjs",
     "analytics": "node context-starter/analytics/serve.mjs . --codex-history",