@rootnative/inertia-svg 0.0.0-alpha.1 → 0.0.0-alpha.2

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { useRef, useMemo, useEffect } from 'react';
-import { Path } from 'react-native-svg';
+import { useRef, useEffect, useMemo } from 'react';
+import { Path, Circle, Rect, Line } from 'react-native-svg';
 import Animated, { useSharedValue, useAnimatedProps } from 'react-native-reanimated';
-import { useShouldReduceMotion, resolveTransition } from '@rootnative/inertia';
+import { useShouldReduceMotion, useNamedTransitions, resolveTransition, resolveNamedTransition } from '@rootnative/inertia';
 import { jsx } from 'react/jsx-runtime';
 
 // src/MotionPath.tsx
@@ -347,12 +347,241 @@ If you need to swap to a structurally different path, remount with key={...}.`
     }
   );
 }
+var NO_ANIMATION2 = { type: "no-animation" };
+function pickTransition2(transition, key, registry) {
+  if (!transition) return void 0;
+  if (typeof transition === "string" || "type" in transition) {
+    return resolveNamedTransition(transition, registry);
+  }
+  return resolveNamedTransition(
+    transition[key],
+    registry
+  );
+}
+function createMotionSvgComponent(Component, config) {
+  const AnimatedComponent = Animated.createAnimatedComponent(
+    Component
+  );
+  const numericKeys = config.animatableProps;
+  const colorKeys = config.colorProps ?? [];
+  const arrayKeys = config.arrayProps ?? [];
+  function MotionSvgComponent(props) {
+    const { initial, animate, transition, ...rest } = props;
+    const statics = rest;
+    const seedSource = initial === false ? animate : initial ?? void 0;
+    const reduce = useShouldReduceMotion();
+    const registry = useNamedTransitions();
+    const mountRef = useRef(null);
+    if (mountRef.current === null) {
+      const engaged2 = {};
+      const engagedNumeric2 = [];
+      const engagedColor2 = [];
+      const engagedArray2 = [];
+      const arrayLengths2 = {};
+      const anim2 = animate;
+      const seed2 = seedSource;
+      for (const k of numericKeys) {
+        engaged2[k] = seed2?.[k] !== void 0 || anim2?.[k] !== void 0 || statics[k] !== void 0;
+        if (engaged2[k]) engagedNumeric2.push(k);
+      }
+      for (const k of colorKeys) {
+        engaged2[k] = seed2?.[k] !== void 0 || anim2?.[k] !== void 0 || statics[k] !== void 0;
+        if (engaged2[k]) engagedColor2.push(k);
+      }
+      for (const k of arrayKeys) {
+        const src = seed2?.[k] ?? statics[k] ?? anim2?.[k];
+        arrayLengths2[k] = Array.isArray(src) ? src.length : 0;
+        engaged2[k] = arrayLengths2[k] > 0;
+        if (engaged2[k]) engagedArray2.push(k);
+      }
+      mountRef.current = {
+        engaged: engaged2,
+        engagedNumeric: engagedNumeric2,
+        engagedColor: engagedColor2,
+        engagedArray: engagedArray2,
+        arrayLengths: arrayLengths2
+      };
+    }
+    const {
+      engaged,
+      engagedNumeric,
+      engagedColor,
+      engagedArray,
+      arrayLengths
+    } = mountRef.current;
+    const seed = seedSource;
+    const anim = animate;
+    const numericSvs = {};
+    for (const k of numericKeys) {
+      numericSvs[k] = useSharedValue(
+        seed?.[k] ?? statics[k] ?? 0
+      );
+    }
+    const colorSvs = {};
+    for (const k of colorKeys) {
+      colorSvs[k] = useSharedValue(
+        seed?.[k] ?? statics[k] ?? "transparent"
+      );
+    }
+    const arraySvs = {};
+    for (const k of arrayKeys) {
+      const len = arrayLengths[k];
+      const seedArr = seed?.[k] ?? statics[k] ?? anim?.[k];
+      const svs = [];
+      for (let i = 0; i < len; i++) {
+        svs.push(useSharedValue(Number(seedArr?.[i]) || 0));
+      }
+      arraySvs[k] = svs;
+    }
+    if (__DEV__) {
+      for (const k of arrayKeys) {
+        const v = statics[k];
+        if (Array.isArray(v) && engaged[k] && v.length !== arrayLengths[k]) {
+          throw new Error(
+            `[inertia-svg] ${k} length changed after mount (${arrayLengths[k]} \u2192 ${v.length}). Array props are locked at first render \u2014 remount with key={...} to change the length.`
+          );
+        }
+      }
+    }
+    for (const k of numericKeys) {
+      const target = anim?.[k];
+      useEffect(() => {
+        if (target === void 0) return;
+        if (!engaged[k]) {
+          if (__DEV__) warnNotEngaged(k);
+          return;
+        }
+        const cfg = reduce ? NO_ANIMATION2 : pickTransition2(transition, k, registry);
+        numericSvs[k].value = resolveTransition(cfg, target);
+      }, [target, reduce, transition]);
+    }
+    for (const k of colorKeys) {
+      const target = anim?.[k];
+      useEffect(() => {
+        if (target === void 0) return;
+        if (!engaged[k]) {
+          if (__DEV__) warnNotEngaged(k);
+          return;
+        }
+        const cfg = reduce ? NO_ANIMATION2 : pickTransition2(transition, k, registry);
+        colorSvs[k].value = resolveTransition(cfg, target);
+      }, [target, reduce, transition]);
+    }
+    for (const k of arrayKeys) {
+      const target = anim?.[k];
+      const sig = target ? target.join(",") : void 0;
+      useEffect(() => {
+        if (target === void 0) return;
+        if (!engaged[k]) {
+          if (__DEV__) warnNotEngaged(k);
+          return;
+        }
+        const len = arrayLengths[k];
+        if (target.length !== len) {
+          if (__DEV__) {
+            throw new Error(
+              `[inertia-svg] animate.${k} length mismatch (${len} \u2192 ${target.length}). Array props are locked at first render \u2014 remount with key={...} to change the length.`
+            );
+          }
+          return;
+        }
+        const cfg = reduce ? NO_ANIMATION2 : pickTransition2(transition, k, registry);
+        const svs = arraySvs[k];
+        for (let i = 0; i < len; i++) {
+          svs[i].value = resolveTransition(cfg, target[i] ?? 0);
+        }
+      }, [sig, reduce, transition]);
+    }
+    const animatedProps = useAnimatedProps(() => {
+      "worklet";
+      const out = {};
+      for (let i = 0; i < engagedNumeric.length; i++) {
+        const k = engagedNumeric[i];
+        out[k] = numericSvs[k].value;
+      }
+      for (let i = 0; i < engagedColor.length; i++) {
+        const k = engagedColor[i];
+        out[k] = colorSvs[k].value;
+      }
+      for (let i = 0; i < engagedArray.length; i++) {
+        const k = engagedArray[i];
+        const svs = arraySvs[k];
+        const arr = new Array(svs.length);
+        for (let j = 0; j < svs.length; j++) arr[j] = svs[j].value;
+        out[k] = arr;
+      }
+      return out;
+    });
+    return (
+      // `animatedProps` overrides every engaged key each frame; the static
+      // props in `rest` are the first-render seeds so the element renders
+      // before the first effect tick. The cast sheds Reanimated's strict-prop
+      // constraint that the worklet's return type can't express — the runtime
+      // shape is the same.
+      /* @__PURE__ */ jsx(AnimatedComponent, { animatedProps, ...statics })
+    );
+  }
+  const base = Component.displayName ?? Component.name ?? "SvgComponent";
+  MotionSvgComponent.displayName = `Motion${base}`;
+  return MotionSvgComponent;
+}
+function warnNotEngaged(key) {
+  console.warn(
+    `[inertia-svg] animate.${key} was introduced after mount \u2014 the key wasn't present at mount (static prop, initial, or animate), so its animated value can't render. Include ${key} at mount or remount with key={...}.`
+  );
+}
+var MotionCircle = createMotionSvgComponent(Circle, {
+  animatableProps: [
+    "cx",
+    "cy",
+    "r",
+    "strokeWidth",
+    "strokeOpacity",
+    "fillOpacity",
+    "opacity",
+    "strokeDashoffset"
+  ],
+  colorProps: ["fill", "stroke"],
+  arrayProps: ["strokeDasharray"]
+});
+var MotionRect = createMotionSvgComponent(Rect, {
+  animatableProps: [
+    "x",
+    "y",
+    "width",
+    "height",
+    "rx",
+    "ry",
+    "strokeWidth",
+    "strokeOpacity",
+    "fillOpacity",
+    "opacity",
+    "strokeDashoffset"
+  ],
+  colorProps: ["fill", "stroke"],
+  arrayProps: ["strokeDasharray"]
+});
+var MotionLine = createMotionSvgComponent(Line, {
+  animatableProps: [
+    "x1",
+    "y1",
+    "x2",
+    "y2",
+    "strokeWidth",
+    "strokeOpacity",
+    "opacity",
+    "strokeDashoffset"
+  ],
+  colorProps: ["stroke"],
+  arrayProps: ["strokeDasharray"]
+});
 
 // src/index.ts
 var MotionSvg = {
-  Path: MotionPath
+  Path: MotionPath,
+  Circle: MotionCircle,
+  Rect: MotionRect,
+  Line: MotionLine
 };
 
-export { MotionPath, MotionSvg, diffTemplate, flattenParams, parsePathD, serializePath, templateOf };
-//# sourceMappingURL=index.mjs.map
-//# sourceMappingURL=index.mjs.map
+export { MotionCircle, MotionLine, MotionPath, MotionRect, MotionSvg, createMotionSvgComponent, diffTemplate, flattenParams, parsePathD, serializePath, templateOf };

package/llms.txt

@@ -10,7 +10,7 @@
 
 `@rootnative/inertia-svg` adds animatable SVG primitives built on [`react-native-svg`](https://github.com/software-mansion/react-native-svg). It is an **optional** sibling package — install it only when you need to morph paths or animate `fill` / `stroke`. The core library has no required `react-native-svg` dependency.
 
-`MotionPath` wraps `<Path>` and accepts the same `initial` / `animate` / `transition` shape as the core `Motion.*` primitives, with animatable keys for the path data (`d`) plus color and numeric paint properties.
+`MotionPath` wraps `<Path>` and accepts the same `initial` / `animate` / `transition` shape as the core `Motion.*` primitives, with animatable keys for the path data (`d`) plus color and numeric paint properties. Prebuilt [`MotionCircle` / `MotionRect` / `MotionLine`](#shapes) cover the other common shapes, and the [`createMotionSvgComponent`](#factory) factory behind them wraps any `react-native-svg` element.
 
 ## Install
 
@@ -52,7 +52,7 @@ import { MotionSvg } from '@rootnative/inertia-svg'
 ;<MotionSvg.Path d={SOURCE_D} animate={{ d: TARGET_D }} />
 ```
 
-Additional shape primitives (`Circle`, `Rect`, `Line`, `Ellipse`) will join the namespace in a follow-up release once the path morphing API is validated.
+The namespace also carries the prebuilt shapes: `MotionSvg.Circle`, `MotionSvg.Rect`, and `MotionSvg.Line` — see [Shapes](#shapes) below.
 
 The static `d` prop is required. Its **command sequence is locked at first render** — every target `d` you pass via `animate` or `initial` must produce the same command letters in the same order after implicit-repeat expansion. Element-wise scalar interpolation is the entire morphing model.
 
@@ -133,10 +133,78 @@ If `initial.d` is provided, it must be template-compatible with the static `d`
 
 `MotionPath` participates in [`<MotionConfig reducedMotion>`](./motion-config.md) the same way the core primitives do — when the OS reduce-motion setting is on (or you pass `reducedMotion="always"`), transitions resolve as direct assignment instead of `withSpring` / `withTiming`.
 
-## What this primitive doesn't do (v0.2)
+## Shapes — MotionCircle, MotionRect, MotionLine {#shapes}
+
+Prebuilt animatable wrappers for the common non-path shapes, built with the [factory](#factory) below. Each accepts the same `initial` / `animate` / `transition` shape as `MotionPath`, and `transition` also accepts a [named transition](./motion-config.md#named-transitions) registered on the nearest `<MotionConfig transitions>` — top-level and per-property.
+
+| Component      | Numeric props                                                                                                         | Color props      | Array props       |
+| -------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------------- |
+| `MotionCircle` | `cx`, `cy`, `r`, `strokeWidth`, `strokeOpacity`, `fillOpacity`, `opacity`, `strokeDashoffset`                         | `fill`, `stroke` | `strokeDasharray` |
+| `MotionRect`   | `x`, `y`, `width`, `height`, `rx`, `ry`, `strokeWidth`, `strokeOpacity`, `fillOpacity`, `opacity`, `strokeDashoffset` | `fill`, `stroke` | `strokeDasharray` |
+| `MotionLine`   | `x1`, `y1`, `x2`, `y2`, `strokeWidth`, `strokeOpacity`, `opacity`, `strokeDashoffset`                                 | `stroke`         | `strokeDasharray` |
+
+The canonical `MotionCircle` consumer is a circular progress ring — a static `strokeDasharray` of the circumference with an animated `strokeDashoffset`:
+
+```tsx
+import Svg from 'react-native-svg'
+import { MotionCircle } from '@rootnative/inertia-svg'
+
+const CIRCUMFERENCE = 2 * Math.PI * 45
+
+function ProgressRing({ progress }: { progress: number }) {
+  return (
+    <Svg viewBox="0 0 100 100" width={64} height={64}>
+      <MotionCircle
+        cx={50}
+        cy={50}
+        r={45}
+        stroke="#0ea5e9"
+        strokeWidth={8}
+        fill="none"
+        strokeDasharray={[CIRCUMFERENCE]}
+        strokeDashoffset={CIRCUMFERENCE}
+        animate={{ strokeDashoffset: CIRCUMFERENCE * (1 - progress) }}
+        transition={{ type: 'timing', duration: 300 }}
+      />
+    </Svg>
+  )
+}
+```
+
+Shape-specific rules (they mirror `MotionPath`'s command-sequence lock):
+
+- **Array props lock their length at first render.** `strokeDasharray` interpolates element-wise, so a target with a different length throws in dev and is ignored in production. Remount with a new `key` to change the length.
+- **A key only animates when it's present at mount** — in the static props, `initial`, or `animate`. Keys introduced into `animate` after mount warn in dev and are ignored. Keys never mentioned pass through as ordinary static props, so un-animated attributes keep their element defaults.
+- Numeric keys engaged only via `animate` seed from `0`; colors seed from `'transparent'`. Give the key a static prop or an `initial` value when the mount animation should start elsewhere.
+
+## createMotionSvgComponent {#factory}
+
+The factory behind the prebuilt shapes. Point it at any `react-native-svg` element and declare which props animate and how each interpolates:
+
+```tsx
+import { Ellipse } from 'react-native-svg'
+import { createMotionSvgComponent } from '@rootnative/inertia-svg'
+
+const MotionEllipse = createMotionSvgComponent(Ellipse, {
+  animatableProps: ['cx', 'cy', 'rx', 'ry', 'opacity'], // numeric
+  colorProps: ['fill', 'stroke'], // color strings
+  arrayProps: ['strokeDasharray'], // numeric arrays, length locked at mount
+})
+
+<MotionEllipse
+  cx={50} cy={50} rx={10} ry={20}
+  animate={{ rx: 30, fill: '#7c3aed' }}
+  transition={{ type: 'spring', tension: 180, friction: 14 }}
+/>
+```
+
+Prop keys are inferred from the wrapped component, so a typo in `animatableProps` is a compile error, and the generated component's `animate` / `initial` only accept the declared keys. Everything documented for the shapes above — named transitions, per-property transitions, `initial` semantics, reduced motion, the mount locks — comes from the factory and applies to any component it builds.
+
+`MotionPath` remains hand-rolled: path morphing needs the `d` template machinery the generic factory doesn't model.
+
+## What this package doesn't do
 
 - **Path resampling** between structurally different shapes. Same-template morphs only — the rest is your `key` to remount.
-- **Other SVG shapes** (`Circle`, `Rect`, `Line`, `Ellipse`). They land in a follow-up release; pencil them in if you need them.
 - **Gradient fills inside the SVG**. For gradient fills use `<Defs>` + `<LinearGradient>` from `react-native-svg` and animate the stops via [`MotionLinearGradient`](./gradients.mdx)'s patterns; the path itself just references the gradient by `url(#id)`.
 - **Path command interpolation** (e.g. morphing an `L` into a `C`). Element-wise scalar interpolation is intentional — it's predictable, cheap, and matches what designers reach for 95% of the time.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia-svg",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.2",
   "description": "Animatable SVG primitives (path morphing, fill/stroke) for @rootnative/inertia, built on react-native-svg.",
   "license": "MIT",
   "author": "RootNative",
@@ -46,10 +46,11 @@
     "LICENSE",
     "CHANGELOG.md",
     "!**/__tests__",
+    "!**/__type-tests__",
     "!**/*.test.*"
   ],
   "peerDependencies": {
-    "@rootnative/inertia": ">=0.0.0-alpha.1",
+    "@rootnative/inertia": ">=0.0.0-alpha.2",
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
     "react-native-reanimated": ">=4.0.0",
@@ -68,7 +69,7 @@
     "react-test-renderer": "19.1.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
-    "@rootnative/inertia": "0.0.0-alpha.1"
+    "@rootnative/inertia": "0.0.0-alpha.2"
   },
   "publishConfig": {
     "access": "public"