@tobiasoberpaul/mdk 0.1.1 → 0.2.0

package/README.md

@@ -25,4 +25,6 @@ Your component manages layout, visibility, focus and accessibility. MDK handles
 
 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).
+
 Licensed under [MIT](LICENSE).

package/dist/index.d.ts

@@ -28,3 +28,5 @@ export type { MotionPlacement, MotionPositionOptions } from './position.js';
 export { captureMotionLayout, animateMotionLayout } from './layout.js';
 export { bindScrollMotion } from './scroll.js';
 export type { ScrollMotionOptions } from './scroll.js';
+export { createPresenceMotion } from './presence.js';
+export type { PresenceMotion, PresenceMotionOptions } from './presence.js';

package/dist/index.js

@@ -13,3 +13,4 @@ export { bindMotionInteractions, createInteractiveMotion } from './interactions.
 export { positionMotion } from './position.js';
 export { captureMotionLayout, animateMotionLayout } from './layout.js';
 export { bindScrollMotion } from './scroll.js';
+export { createPresenceMotion } from './presence.js';

package/dist/presence.d.ts

@@ -0,0 +1,15 @@
+import type { MotionState, Options, Transition } from './core/lifecycle.js';
+export interface PresenceMotionOptions extends Pick<Options, 'initiallyOpen'> {
+    /** Create a fresh MDK transition using the lifecycle options supplied by the adapter. */
+    createTransition(lifecycle: Pick<Options, 'initiallyOpen' | 'onStateChange'>): Transition;
+    /** 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;
+}
+export interface PresenceMotion {
+    readonly state: MotionState;
+    setOpen(open: boolean): void;
+    destroy(): void;
+}
+/** Drive MDK from a component's existing open/close signals. */
+export declare function createPresenceMotion(options: PresenceMotionOptions): PresenceMotion;

package/dist/presence.js

@@ -0,0 +1,51 @@
+/** Drive MDK from a component's existing open/close signals. */
+export function createPresenceMotion(options) {
+    const { createTransition, setPresent } = options;
+    let open = options.initiallyOpen ?? false;
+    let destroyed = false;
+    let controller;
+    if (setPresent) {
+        controller = createTransition({
+            initiallyOpen: open,
+            onStateChange(state) {
+                if (state === 'opening')
+                    setPresent(true);
+                if (state === 'closed')
+                    setPresent(false);
+            }
+        });
+    }
+    return {
+        get state() {
+            if (destroyed)
+                return 'destroyed';
+            return controller?.state ?? (open ? 'open' : 'closed');
+        },
+        setOpen(next) {
+            if (destroyed || next === open)
+                return;
+            open = next;
+            if (next) {
+                controller ?? (controller = createTransition({ initiallyOpen: false }));
+                controller.open();
+            }
+            else if (setPresent) {
+                controller?.close();
+            }
+            else {
+                // The host already owns visibility. Release visual styles for the next entry.
+                controller?.destroy();
+                controller = undefined;
+            }
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            const pendingExit = controller?.state === 'closing';
+            controller?.destroy();
+            if (pendingExit)
+                setPresent?.(false);
+        }
+    };
+}

package/docs/LIBRARY.md

@@ -77,6 +77,39 @@ Use your design system's real dialog, drawer, popover, toast or card instead of
 this minimal surface. Native dialogs require their component integration to
 call `showModal()` / close at the appropriate lifecycle points.
 
+## Animate an existing component
+
+Use `createPresenceMotion` when a popover, drawer or menu already owns its
+interaction. Forward its existing open and close signals to `setOpen`. The
+adapter uses the selected MDK controller for animation. The integration keeps
+its existing positioning, focus, keyboard and dismissal behavior.
+
+```ts
+import { createGrowTransition, createPresenceMotion } from '@tobiasoberpaul/mdk';
+import '@tobiasoberpaul/mdk/motion.css';
+
+const motion = createPresenceMotion({
+  initiallyOpen: !surface.hidden,
+  createTransition: lifecycle => createGrowTransition({ content: surface, ...lifecycle }),
+  setPresent: present => { surface.hidden = !present; },
+});
+
+// Forward the component's existing open/close requests to motion.setOpen(open).
+// On cleanup, unsubscribe from the component and call motion.destroy().
+```
+
+With `setPresent`, the adapter shows the surface synchronously before measurement
+and hides it after the exit settles. Use the component's supported presence
+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)`
+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.
+
 ## Public behavior factories
 
 | Factory | Behavior | Required additions to shared options |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tobiasoberpaul/mdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist",
@@ -18,7 +18,7 @@
     "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",
-    "dev": "npm run build && npm run build:examples && node scripts/serve.mjs",
+    "dev": "npm run build:site && node scripts/serve.mjs",
     "test": "npm run build && npm run build:examples && playwright test",
     "build:site": "npm run build && npm run build:examples && node scripts/build-site.mjs",
     "mcp": "node ai/mcp-server.mjs",
@@ -30,6 +30,7 @@
     "@db-ux/core-foundations": "6.2.0",
     "@db-ux/db-theme": "7.2.0",
     "@db-ux/react-core-components": "6.2.0",
+    "@mdx-js/esbuild": "3.1.1",
     "@playwright/test": "1.48.2",
     "@radix-ui/react-dialog": "1.3.1",
     "@radix-ui/react-dropdown-menu": "2.2.1",
@@ -44,12 +45,12 @@
     "clsx": "2.1.1",
     "esbuild": "0.21.5",
     "lucide-react": "1.66.0",
+    "picomatch": "4.0.7",
     "react": "19.2.0",
     "react-dom": "19.2.0",
     "tailwind-merge": "2.6.0",
     "tailwindcss": "3.4.17",
-    "typescript": "5.7.3",
-    "picomatch": "4.0.7"
+    "typescript": "5.7.3"
   },
   "description": "Framework-independent, reversible UI motion with CSS tokens and the Web Animations API.",
   "main": "./dist/index.js",
@@ -74,7 +75,6 @@
   "sideEffects": [
     "**/*.css"
   ],
-
   "publishConfig": {
     "access": "public"
   },