@humanspeak/svelte-motion 0.4.5 → 0.4.6

package/README.md

@@ -44,7 +44,7 @@ Goal: Framer Motion API parity for Svelte where common React examples can be tra
 | Drag (`drag`, constraints, momentum, controls, callbacks) | Supported                       |
 | `AnimatePresence` (`initial`, `mode`, `onExitComplete`)   | Supported                       |
 | Layout (`layout`, `layout="position"`)                    | Supported (single-element FLIP) |
-| Shared layout (`layoutId`)                                | Supported                       |
+| Shared layout (`layoutId`, `LayoutGroup`, `layoutScroll`) | Supported                       |
 | Pan gesture API (`whilePan`, `onPan*`)                    | Not yet supported               |
 | `MotionConfig` parity beyond `transition`                 | Partial                         |
 | `reducedMotion`, `features`, `transformPagePoint`         | Not yet supported               |
@@ -280,7 +280,6 @@ Validated against current source and test suite (local run):
 
 ## Known gaps vs Framer Motion
 
-- No shared layout API (`layoutId`, `LayoutGroup`).
 - No pan gesture API (`whilePan`, `onPan*`).
 - `whileInView` does not yet expose Framer-style viewport options.
 - `MotionConfig` currently only provides `transition` defaults.

package/dist/components/LayoutGroup.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte'
+    import {
+        chainLayoutGroupId,
+        getLayoutGroupContext,
+        setLayoutGroupContext
+    } from './layoutGroup.context'
+
+    /**
+     * Scope `layoutId` shared-layout animations to a subtree.
+     *
+     * Wrap a region in `<LayoutGroup id="…">` so descendants' `layoutId`
+     * snapshots / consumes are prefixed with the group's id. Two groups
+     * containing the same `layoutId` values won't cross-animate — useful
+     * for repeated UI patterns (multiple tab indicators, kanban columns,
+     * sibling carousels) where each instance should animate independently.
+     *
+     * Mirrors framer-motion's `<LayoutGroup>` (`inherit` defaults to true
+     * — descendants chain onto the parent group's id, so nested groups
+     * yield `"parent-child"`).
+     *
+     * @prop id Stable identifier for this group's scope. When omitted,
+     *     the LayoutGroup is a transparent grouping with no own id
+     *     (still useful for `inherit={false}` to break out of an outer
+     *     group's scope, e.g. an embedded widget).
+     * @prop inherit `true` (default) — chain onto the parent group's id.
+     *     `'id'` — same as `true` in this implementation; accepted for
+     *     drop-in compatibility with framer-motion examples. In
+     *     framer-motion, `'id'` inherits the id but breaks the internal
+     *     projection-tree group. We don't have a projection-tree group
+     *     (our snapshot/consume registry doesn't need sibling
+     *     coordination), so `'id'` and `true` behave identically.
+     *     `false` — start a fresh scope, ignoring any outer LayoutGroup.
+     * @prop children Slot rendered inside the group context.
+     *
+     * @example
+     * ```svelte
+     * <LayoutGroup id="tabs-a">
+     *     <Tabs />
+     * </LayoutGroup>
+     * <LayoutGroup id="tabs-b">
+     *     <Tabs /> <!-- same layoutId values, independent animations -->
+     * </LayoutGroup>
+     * ```
+     *
+     * @see https://motion.dev/docs/react-layout-animations#scoped-layout-animations
+     */
+    const {
+        id,
+        inherit = true,
+        children
+    }: {
+        id?: string
+        inherit?: boolean | 'id'
+        children?: Snippet
+    } = $props()
+
+    // setContext is one-shot at component init, so reading `id` and `inherit`
+    // here captures their initial values intentionally — the scope id is
+    // fixed for this subtree's lifetime. The warning would only matter if we
+    // wanted descendants to react to prop changes, which we explicitly don't.
+    // svelte-ignore state_referenced_locally
+    const shouldInheritId = inherit === true || inherit === 'id'
+    const effectiveId = shouldInheritId ? chainLayoutGroupId(getLayoutGroupContext(), id) : id
+    setLayoutGroupContext(effectiveId)
+</script>
+
+{@render children?.()}

package/dist/components/LayoutGroup.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    id?: string;
+    inherit?: boolean | 'id';
+    children?: Snippet;
+};
+declare const LayoutGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type LayoutGroup = ReturnType<typeof LayoutGroup>;
+export default LayoutGroup;

package/dist/components/layoutGroup.context.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Identifier for a `<LayoutGroup>` subtree. Descendants prefix their
+ * `layoutId` lookups with this so two `<LayoutGroup>`s containing the
+ * same `layoutId` values don't cross-animate.
+ *
+ * `undefined` means "no enclosing LayoutGroup" — the descendant uses
+ * `layoutId` verbatim against the global registry, preserving the
+ * existing un-grouped behaviour.
+ */
+export type LayoutGroupContext = string | undefined;
+/**
+ * Publish a LayoutGroup id for descendants. Called by `<LayoutGroup>`
+ * after computing its own (possibly inherited and chained) id.
+ */
+export declare const setLayoutGroupContext: (id: LayoutGroupContext) => void;
+/**
+ * Read the nearest LayoutGroup id, or `undefined` if not inside one.
+ *
+ * `_MotionContainer.svelte` reads this to prefix `layoutId` when
+ * snapshotting and consuming against the registry, so shared-layout
+ * animations stay scoped to the surrounding group.
+ */
+export declare const getLayoutGroupContext: () => LayoutGroupContext;
+/**
+ * Combine a parent group's id with a descendant LayoutGroup's own id
+ * to produce the effective scope id. Mirrors framer-motion's chaining
+ * (`"parent-id"` + `"-"` + `"own-id"`).
+ *
+ * Either side can be `undefined`; the result is the other one, or
+ * `undefined` if both are absent.
+ */
+export declare const chainLayoutGroupId: (parent: LayoutGroupContext, own: string | undefined) => LayoutGroupContext;
+/**
+ * Apply a LayoutGroup scope to a raw `layoutId` for registry lookups.
+ * Returns the un-prefixed id when no group is in scope.
+ */
+export declare const scopeLayoutId: (groupId: LayoutGroupContext, layoutId: string) => string;

package/dist/components/layoutGroup.context.js

@@ -0,0 +1,41 @@
+import { getContext, setContext } from 'svelte';
+const LAYOUT_GROUP_CONTEXT_KEY = Symbol('layout-group');
+/**
+ * Publish a LayoutGroup id for descendants. Called by `<LayoutGroup>`
+ * after computing its own (possibly inherited and chained) id.
+ */
+export const setLayoutGroupContext = (id) => {
+    setContext(LAYOUT_GROUP_CONTEXT_KEY, id);
+};
+/**
+ * Read the nearest LayoutGroup id, or `undefined` if not inside one.
+ *
+ * `_MotionContainer.svelte` reads this to prefix `layoutId` when
+ * snapshotting and consuming against the registry, so shared-layout
+ * animations stay scoped to the surrounding group.
+ */
+export const getLayoutGroupContext = () => {
+    return getContext(LAYOUT_GROUP_CONTEXT_KEY);
+};
+/**
+ * Combine a parent group's id with a descendant LayoutGroup's own id
+ * to produce the effective scope id. Mirrors framer-motion's chaining
+ * (`"parent-id"` + `"-"` + `"own-id"`).
+ *
+ * Either side can be `undefined`; the result is the other one, or
+ * `undefined` if both are absent.
+ */
+export const chainLayoutGroupId = (parent, own) => {
+    if (!parent)
+        return own;
+    if (!own)
+        return parent;
+    return `${parent}-${own}`;
+};
+/**
+ * Apply a LayoutGroup scope to a raw `layoutId` for registry lookups.
+ * Returns the un-prefixed id when no group is in scope.
+ */
+export const scopeLayoutId = (groupId, layoutId) => {
+    return groupId ? `${groupId}::${layoutId}` : layoutId;
+};

package/dist/html/_MotionContainer.svelte

@@ -69,6 +69,7 @@
         getLayoutScrollContainerRef,
         setLayoutScrollContainer
     } from '../components/layoutScroll.context'
+    import { getLayoutGroupContext, scopeLayoutId } from '../components/layoutGroup.context'
 
     type Props = MotionProps & {
         children?: Snippet
@@ -147,6 +148,15 @@
     // Get layoutId registry (provided by AnimatePresence or a parent LayoutGroup)
     const layoutIdRegistry = getLayoutIdRegistry()
 
+    // Scope layoutId by the surrounding <LayoutGroup>, so identical
+    // layoutId values in two sibling groups don't cross-animate (#311).
+    // Undefined when no group is in scope — descendants behave exactly
+    // as before relative to the global registry.
+    const layoutGroupId = getLayoutGroupContext()
+    const scopedLayoutId = $derived(
+        layoutIdProp ? scopeLayoutId(layoutGroupId, layoutIdProp) : undefined
+    )
+
     // Capture the ancestor `layoutScroll` chain BEFORE we potentially shadow
     // the context with ourselves below — this element's own FLIP measurements
     // must resolve against the *ancestors*' scroll containers, not against
@@ -258,9 +268,9 @@
         // On cleanup (before DOM removal), push last-known rect to registry
         return () => {
             cancelAnimationFrame(rafId)
-            if (layoutIdLastRect && layoutIdProp) {
+            if (layoutIdLastRect && scopedLayoutId) {
                 layoutIdRegistry.snapshot(
-                    layoutIdProp,
+                    scopedLayoutId,
                     layoutIdLastRect,
                     (mergedTransition ?? {}) as AnimationOptions
                 )
@@ -773,9 +783,9 @@
     // Shared layout animation via layoutId.
     // On mount, consume the previous snapshot and FLIP from its position.
     $effect(() => {
-        if (!(element && layoutIdProp && layoutIdRegistry && isLoaded === 'ready')) return
+        if (!(element && scopedLayoutId && layoutIdRegistry && isLoaded === 'ready')) return
 
-        const prev = layoutIdRegistry.consume(layoutIdProp)
+        const prev = layoutIdRegistry.consume(scopedLayoutId)
         if (!prev) return // First appearance, no animation needed
 
         const next = measureRect(element, resolveLayoutScrollAncestors())

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
+import LayoutGroup from './components/LayoutGroup.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
 export { motion } from './motion';
@@ -32,7 +33,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
-export { AnimatePresence, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';
 export { default as MotionAddress } from './html/Address.svelte';

package/dist/index.js

@@ -1,4 +1,5 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
+import LayoutGroup from './components/LayoutGroup.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
 export { motion } from './motion';
@@ -29,7 +30,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time';
 export { useTransform } from './utils/transform';
-export { AnimatePresence, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
 // Named component exports — tree-shakeable alternative to the `motion` object
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Framer Motion for Svelte 5. Declarative motion.<tag> components with AnimatePresence exit animations, gestures (hover, tap, drag, focus, in-view), variants, FLIP layout animations, shared-layout transitions, spring physics, and scroll-linked motion values. The drop-in Framer Motion alternative for Svelte and SvelteKit.",
   "keywords": [
     "svelte",
@@ -114,7 +114,7 @@
     "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
-    "@types/node": "^25.9.0",
+    "@types/node": "^25.9.1",
     "@vitest/coverage-v8": "^4.1.6",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "10.1.8",
@@ -135,16 +135,16 @@
     "prettier-plugin-tailwindcss": "^0.8.0",
     "publint": "^0.3.21",
     "runed": "0.37.1",
-    "svelte": "^5.55.7",
+    "svelte": "^5.55.8",
     "svelte-check": "^4.4.8",
     "svg-tags": "^1.0.0",
     "tailwind-merge": "^3.6.0",
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.3.0",
     "tailwindcss-animate": "^1.0.7",
-    "tsx": "^4.22.2",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.3",
+    "typescript-eslint": "^8.59.4",
     "vite": "^8.0.13",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.6"