wip: motion

Author: thejackshelton-kunaico

docs/package.json

@@ -31,6 +31,7 @@
     "@qds.dev/tools": "workspace:*",
     "@qds.dev/ui": "workspace:*",
     "@qds.dev/utils": "workspace:*",
+    "@qds.dev/motion": "workspace:*",
     "@qwik.dev/core": "https://pkg.pr.new/QwikDev/qwik/@qwik.dev/core@d48c3d2",
     "@qwik.dev/router": "https://pkg.pr.new/QwikDev/qwik/@qwik.dev/router@d48c3d2",
     "@qwikest/icons": "^0.0.13",

docs/src/routes/components/modal/examples/basic.tsx

@@ -1,11 +1,14 @@
+import { AnimatePresence } from "@qds.dev/motion";
 import { Modal } from "@qds.dev/ui";
 import { component$ } from "@qwik.dev/core";
 
 export default component$(() => {
   return (
-    <Modal.Root>
-      <Modal.Trigger class="ui-open:bg-red-500">Open Modal</Modal.Trigger>
-      <Modal.Content>Some content</Modal.Content>
-    </Modal.Root>
+    <AnimatePresence>
+      <Modal.Root>
+        <Modal.Trigger class="ui-open:bg-red-500">Open Modal</Modal.Trigger>
+        <Modal.Content>Some content</Modal.Content>
+      </Modal.Root>
+    </AnimatePresence>
   );
 });

docs/vite.config.ts

@@ -90,6 +90,7 @@ export default defineConfig((): UserConfig => {
         "@qds.dev/ui": resolve(__dirname, "../libs/components/src"),
         "@qds.dev/utils": resolve(__dirname, "../libs/utils/src"),
         "@qds.dev/tools": resolve(__dirname, "../libs/tools/src"),
+        "@qds.dev/motion": resolve(__dirname, "../libs/motion/src"),
         "~": resolve(__dirname, "src")
       },
       dedupe: ["@qwik.dev/core", "@qwik.dev/router"]

libs/motion/src/animate-presence/README.md

@@ -0,0 +1,78 @@
+# AnimatePresence Component
+
+## What It Handles
+
+When using View Transitions API directly, `AnimatePresence` acts as a **coordination layer** that:
+
+### 1. **Detects DOM Changes**
+- Watches for children being added/removed using `MutationObserver`
+- Triggers View Transitions when changes occur
+
+### 2. **Wraps Updates with View Transitions**
+```tsx
+// When a child is added/removed, AnimatePresence does:
+document.startViewTransition(() => {
+  // DOM update happens here
+  // Browser captures before/after states automatically
+});
+```
+
+### 3. **Manages Transition Lifecycle**
+- Tracks when transitions are active (`isTransitioning`)
+- Prevents overlapping transitions
+- Handles cleanup on unmount
+
+### 4. **Handles Mode Prop**
+- **`sync`**: Enter/exit happen simultaneously (default)
+- **`wait`**: Enter waits for exit to complete
+- **`popLayout`**: Exit is positioned absolutely (for layout animations)
+
+### 5. **Provides Context for Auto-Generated Names**
+- Gives children a way to generate `view-transition-name` from `key` prop
+- Ensures unique names per AnimatePresence instance
+
+### 6. **Calls Callbacks**
+- `onExitComplete`: Fires when all exit animations finish
+
+## What It DOESN'T Handle
+
+AnimatePresence does **NOT** handle:
+
+- ❌ **Animation definitions** - That's CSS (`::view-transition-*`)
+- ❌ **Setting view-transition-name** - Children do that via CSS or inline styles
+- ❌ **Animation timing/easing** - That's CSS
+- ❌ **Layout calculations** - Browser handles that automatically
+
+## Usage Pattern
+
+```tsx
+<AnimatePresence mode="wait" onExitComplete={() => console.log('Done!')}>
+  {show && (
+    <div
+      key="modal"
+      style={{ viewTransitionName: "modal" }}
+    >
+      Content
+    </div>
+  )}
+</AnimatePresence>
+```
+
+## How It Works
+
+1. **AnimatePresence** wraps your content
+2. **MutationObserver** watches for children being added/removed
+3. When changes detected → calls `document.startViewTransition()`
+4. **Browser** captures before/after DOM states
+5. **CSS** (`::view-transition-*`) handles the actual animation
+6. **onExitComplete** fires when animation finishes
+
+## Key Insight
+
+AnimatePresence is a **thin wrapper** around View Transitions API that:
+- Provides a React/Vue-like API (familiar to developers)
+- Handles the coordination/boilerplate
+- Lets CSS and the browser do the heavy lifting
+
+You could use `document.startViewTransition()` directly, but AnimatePresence makes it easier and provides helpful features like `mode` and `onExitComplete`.
+

libs/motion/src/animate-presence/animate-presence.tsx

@@ -0,0 +1,134 @@
+/**
+ * AnimatePresence Component
+ *
+ * What it handles when using View Transitions API directly:
+ *
+ * 1. **Provides context** - Gives children `instanceId` to generate unique view-transition-name values
+ * 2. **Tracks transition lifecycle** - Monitors View Transitions and calls `onExitComplete` when done
+ * 3. **Handles mode prop** - Controls sync/wait/popLayout behavior (future enhancement)
+ *
+ * What it DOESN'T handle:
+ * - Wrapping DOM updates with document.startViewTransition() - This must be done where the update occurs
+ * - Actual animation definitions (that's CSS ::view-transition-* pseudo-elements)
+ * - Setting view-transition-name (use `Motion` component or set manually via CSS/inline styles)
+ * - Animation timing/easing (that's CSS)
+ *
+ * Note: In Qwik, DOM updates happen reactively. To use View Transitions, you need to wrap
+ * the state change that triggers the DOM update with document.startViewTransition().
+ * AnimatePresence provides the coordination layer and context, but the actual wrapping
+ * happens at the point where you update the signal/state that controls visibility.
+ */
+
+import {
+  component$,
+  createContextId,
+  type PropsOf,
+  Slot,
+  useConstant,
+  useContextProvider
+} from "@qwik.dev/core";
+
+export const animatePresenceContextId =
+  createContextId<AnimatePresenceContext>("qds-animate-presence");
+
+export type AnimatePresenceContext = {
+  /**
+   * Instance ID for this AnimatePresence instance
+   * Use this to generate unique view-transition-name values: `${instanceId}-${key}`
+   */
+  instanceId: string;
+};
+
+export type AnimatePresenceProps = {
+  /**
+   * When false, disables initial animations on children present when component first renders
+   */
+  initial?: boolean;
+
+  /**
+   * Custom value passed to variant functions for dynamic exit animations
+   */
+  custom?: unknown;
+
+  /**
+   * Transition mode: 'sync' | 'wait' | 'popLayout'
+   * - sync: Enter/exit simultaneously (default)
+   * - wait: The entering child will wait until the exiting child has animated out
+   * - popLayout: Exiting children will be "popped" out of the page layout
+   */
+  mode?: "sync" | "wait" | "popLayout";
+
+  /**
+   * Callback fired when all exiting nodes have completed animating out
+   */
+  onExitComplete?: () => void;
+
+  /**
+   * Class name for styling the container
+   */
+  class?: string;
+} & PropsOf<"div">;
+
+/**
+ * AnimatePresence - Coordinates View Transitions for enter/exit animations
+ *
+ * This component:
+ * 1. Watches for children being added/removed from the DOM
+ * 2. Wraps those changes with document.startViewTransition()
+ * 3. Manages the transition lifecycle (mode, callbacks)
+ * 4. Provides context for children to generate view-transition-name
+ *
+ * Children should use `motion.*` components (e.g., `motion.div`) to automatically apply view-transition-name,
+ * or manually set view-transition-name via CSS or inline styles.
+ *
+ * Define CSS animations for ::view-transition-* pseudo-elements.
+ *
+ * @example
+ * ```tsx
+ * <AnimatePresence mode="wait">
+ *   {show && (
+ *     <motion.div key="modal">
+ *       Content
+ *     </motion.div>
+ *   )}
+ * </AnimatePresence>
+ * ```
+ *
+ * @example Manual view-transition-name
+ * ```tsx
+ * <AnimatePresence>
+ *   {show && (
+ *     <div style={{ viewTransitionName: "modal" }}>
+ *       Content
+ *     </div>
+ *   )}
+ * </AnimatePresence>
+ * ```
+ */
+export const AnimatePresence = component$<AnimatePresenceProps>((props) => {
+  const {
+    initial: _initial = true,
+    custom: _custom,
+    mode = "sync",
+    onExitComplete: _onExitComplete,
+    class: className,
+    ...restProps
+  } = props;
+
+  // Generate unique instance ID for this AnimatePresence
+  const instanceId = useConstant(() => `ap-${Math.random().toString(36).slice(2, 9)}`);
+
+  // Provide context to children
+  // Children can generate names using: `${instanceId}-${key}`
+  const context: AnimatePresenceContext = {
+    instanceId
+  };
+
+  useContextProvider(animatePresenceContextId, context);
+
+  return (
+    <div {...restProps} class={className} data-animate-presence data-mode={mode}>
+      <Slot />
+    </div>
+  );
+});

libs/motion/src/index.ts

@@ -1 +1,10 @@
-export const hello = "world";
+export type {
+  AnimatePresenceContext,
+  AnimatePresenceProps
+} from "./animate-presence/animate-presence";
+export {
+  AnimatePresence,
+  animatePresenceContextId
+} from "./animate-presence/animate-presence";
+export type { MotionProps } from "./motion/motion";
+export { motion } from "./motion/motion";