@tobiasoberpaul/mdk 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,8 @@ 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.
 
+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 Content transitions. 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/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,85 @@ 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 transformGrowTracks(options) {
+    const { content, axis } = options;
+    const style = getComputedStyle(content);
+    const hostOrigin = style.transformOrigin.split(' ').map(parseFloat);
+    const opacity = style.opacity;
+    const property = 'transform-origin';
+    const inlineOrigin = content.style.getPropertyValue(property);
+    const priority = content.style.getPropertyPriority(property);
+    const origin = scaleOrigin(content);
+    if (!CSS.supports(property, origin))
+        throw new Error('Invalid --motion-scale-origin.');
+    let x, y;
+    try {
+        content.style.setProperty(property, origin, 'important');
+        [x, y] = style.transformOrigin.split(' ').map(parseFloat);
+    }
+    finally {
+        if (inlineOrigin)
+            content.style.setProperty(property, inlineOrigin, priority);
+        else
+            content.style.removeProperty(property);
+    }
+    const { width, height } = localScale(content, content.getBoundingClientRect());
+    if (!width || !height)
+        throw new Error('Grow content must be measurable before animation.');
+    const dx = x - hostOrigin[0], dy = y - hostOrigin[1];
+    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/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

@@ -72,5 +72,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-liquid: 0ms; }
 }

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/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/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,18 +104,47 @@ 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`.
+
+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` |
@@ -132,7 +161,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.
 
@@ -238,7 +267,7 @@ const transition = createMotion({
 
 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
+The deprecated `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
 initialization. Change CSS tokens for per-trip visual parameters.
 
@@ -335,7 +364,7 @@ can be overridden locally on a surface or globally.
 | --- | --- |
 | `--motion-duration` | `300ms`; aliases for morph, scale, liquid, 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.3.0",
   "type": "module",
   "files": [
     "dist",