@onlynative/inertia-svg 0.0.1-alpha.3

package/README.md

@@ -0,0 +1,96 @@
+# @onlynative/inertia-svg
+
+[![npm](https://img.shields.io/npm/v/@onlynative/inertia-svg.svg)](https://www.npmjs.com/package/@onlynative/inertia-svg)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Animatable SVG primitives for [`@onlynative/inertia`](../core), built on [`react-native-svg`](https://github.com/software-mansion/react-native-svg).
+
+`MotionPath` accepts the same `initial` / `animate` / `transition` shape as the core `Motion.*` primitives, with animatable keys for the path data (`d`), color paint (`fill`, `stroke`), and numeric paint (`strokeWidth`, opacities, `strokeDashoffset`).
+
+## Install
+
+```sh
+pnpm add @onlynative/inertia-svg react-native-svg
+```
+
+`react-native-svg` works in bare React Native projects as well as Expo.
+
+**Peer dependencies:** `@onlynative/inertia` (workspace or installed), `react >=19.0.0`, `react-native >=0.81.0`, `react-native-reanimated >=4.0.0`, `react-native-svg >=15.0.0`.
+
+## Usage
+
+```tsx
+import Svg from 'react-native-svg'
+import { MotionPath } from '@onlynative/inertia-svg'
+
+export function Heart({ beating }) {
+  return (
+    <Svg viewBox="0 0 100 100" width={120} height={120}>
+      <MotionPath
+        d="M 50 30 L 70 12 L 90 30 L 50 88 L 10 30 L 30 12 Z"
+        fill="#ef4444"
+        stroke="#991b1b"
+        strokeWidth={3}
+        animate={{
+          d: beating
+            ? 'M 50 28 L 71 10 L 92 28 L 50 92 L 8 28 L 29 10 Z'
+            : 'M 50 30 L 70 12 L 90 30 L 50 88 L 10 30 L 30 12 Z',
+        }}
+        transition={{ type: 'spring', tension: 200, friction: 10 }}
+      />
+    </Svg>
+  )
+}
+```
+
+The static `d` prop sets the visual on first render and **locks the command sequence** for the component's lifetime. Every target `d` (via `initial` or `animate`) must produce the same command letters in the same order after implicit-repeat expansion. To switch between structurally different shapes, remount with a new `key`.
+
+## Animatable props
+
+| Key                | Type     | Notes                                                                                             |
+| ------------------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `d`                | `string` | Path morph via element-wise scalar interpolation. Source and target must share the same template. |
+| `fill`             | `string` | Color, interpolated by Reanimated's color setter.                                                 |
+| `stroke`           | `string` | Color.                                                                                            |
+| `strokeWidth`      | `number` | Numeric.                                                                                          |
+| `strokeOpacity`    | `number` | 0–1.                                                                                              |
+| `fillOpacity`      | `number` | 0–1.                                                                                              |
+| `opacity`          | `number` | 0–1.                                                                                              |
+| `strokeDashoffset` | `number` | Useful for "draw-in" animations on a dashed stroke.                                               |
+
+Per-property transitions are supported — pass a `{ [key]: TransitionConfig }` shape to `transition` instead of a single config, e.g.
+
+```tsx
+transition={{
+  d: { type: 'spring', tension: 160, friction: 14 },
+  fill: { type: 'timing', duration: 300 },
+}}
+```
+
+## Structural compatibility
+
+```
+✅ M 0 0 L 10 10 Z       ↔ M 50 50 L 80 80 Z       same template: M L Z
+✅ M 0 0 10 10 20 20     ↔ M 0 0 L 30 30 L 40 40   same after implicit-repeat expansion (M → L)
+❌ M 0 0 L 10 10 Z       ↔ M 0 0 L 10 10           segment count differs
+❌ M 0 0 L 10 10         ↔ M 0 0 l 10 10           absolute vs relative are distinct templates
+❌ M 0 0 L 10 10         ↔ M 0 0 C 1 1 2 2 3 3     command letters differ
+```
+
+In dev, the component throws on template mismatches at mount, when `animate.d` changes shape, or when the static `d` prop itself changes shape between renders. In production those errors degrade to a no-op snap so a single bad target doesn't crash the screen.
+
+Path resampling between structurally different shapes (flubber-style) is out of scope for v0.2. For arbitrary shape swaps, remount with `key={...}`.
+
+## Reduced motion
+
+`MotionPath` participates in `<MotionConfig reducedMotion>` just like the core primitives — when the OS reduce-motion setting is on (or you pass `reducedMotion="always"`), every animated property snaps directly to its target.
+
+## What this package doesn't do (v0.2)
+
+- Other SVG shapes (`Circle`, `Rect`, `Line`, `Ellipse`) — land in a follow-up once the `MotionPath` API is validated.
+- Path resampling between arbitrary shapes.
+- Morphing an `L` into a `C` (or other across-command interpolation). Element-wise scalar interpolation is intentional.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,188 @@
+import * as react from 'react';
+import { PathProps } from 'react-native-svg';
+import { TransitionConfig } from '@onlynative/inertia';
+
+/**
+ * Animatable target snapshot for a `MotionSvg.Path`. Every field is optional
+ * — include only the dimensions you want to animate; the rest fall back to
+ * the static props on the component.
+ *
+ * `d` morphs the path geometry. The target path **must produce the same
+ * command sequence** as the source after implicit-repeat expansion (same
+ * letters in the same order, e.g. `M L L L Z`). Element-wise numeric
+ * interpolation is the morphing model — see `parsePathD` for the
+ * normalization rules.
+ */
+interface PathAnimate {
+    d?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    fillOpacity?: number;
+    opacity?: number;
+    strokeDashoffset?: number;
+}
+/** The animatable dimensions of a `MotionSvg.Path`. */
+type PathStateShape = {
+    [K in keyof Required<PathAnimate>]: PathAnimate[K];
+};
+/**
+ * Per-property transition map. Top-level entries on `transition` apply to all
+ * properties unless overridden by a per-key entry here.
+ */
+type PathPerPropertyTransition = {
+    [K in keyof PathStateShape]?: TransitionConfig;
+};
+/**
+ * Transition shape accepted by `MotionSvg.Path`. Either a single top-level
+ * transition applied to every animated dimension, or a per-property map.
+ */
+type PathTransition = TransitionConfig | PathPerPropertyTransition;
+
+interface MotionPathProps extends Omit<PathProps, 'd' | 'fill' | 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'fillOpacity' | 'opacity' | 'strokeDashoffset'> {
+    /**
+     * Initial path data. **The command sequence is locked at first render** —
+     * every target `d` passed via `animate` / `initial` must produce the same
+     * command letters in the same order after implicit-repeat expansion. To
+     * morph between structurally different paths, remount with a new `key`.
+     */
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    fillOpacity?: number;
+    opacity?: number;
+    strokeDashoffset?: number;
+    /**
+     * Initial frame override. When present, the component mounts displaying
+     * these values, then animates to `animate` on the next effect. Pass `false`
+     * to skip the initial-mount animation entirely.
+     */
+    initial?: PathAnimate | false;
+    /** Target animation state. */
+    animate?: PathAnimate;
+    /**
+     * Transition config — either a single `TransitionConfig` applied to every
+     * animated dimension, or a per-property map. Per-property entries win over
+     * the top-level transition.
+     */
+    transition?: PathTransition;
+}
+/**
+ * Animatable `<Path>` from `react-native-svg`. Wraps `Path` with declarative
+ * `initial` / `animate` / `transition` props.
+ *
+ * Animatable dimensions:
+ * - `d` — path morph via element-wise scalar interpolation. Source and target
+ *   must share the same command sequence (e.g. both `M L L L Z`).
+ * - `fill`, `stroke` — color strings, interpolated via Reanimated's native
+ *   color animation.
+ * - `strokeWidth`, `strokeOpacity`, `fillOpacity`, `opacity`,
+ *   `strokeDashoffset` — numeric, spring or timing-driven.
+ *
+ * Example:
+ * ```tsx
+ * <Svg viewBox="0 0 100 100">
+ *   <MotionPath
+ *     d="M 50 20 L 80 80 L 20 80 Z"
+ *     animate={{ d: "M 50 80 L 80 20 L 20 20 Z", fill: '#7c3aed' }}
+ *     transition={{ type: 'spring', tension: 140, friction: 12 }}
+ *     fill="#0ea5e9"
+ *   />
+ * </Svg>
+ * ```
+ */
+declare function MotionPath(props: MotionPathProps): react.JSX.Element;
+
+/**
+ * SVG path-string utilities used by `MotionSvg.Path`. Everything here runs on
+ * the JS thread — paths are tokenized into a normalized command list at mount
+ * and when `animate.d` changes; the worklet only ever consumes flat number
+ * arrays + a frozen command template.
+ *
+ * Path morphing in v0.2 requires **structural compatibility**: the source and
+ * every target `d` must produce the same command sequence (same command
+ * letters, in the same order, after implicit-repeat expansion). Element-wise
+ * numeric interpolation is the entire morphing model — we do not resample
+ * paths or insert/remove commands. Same-shape morphs (e.g. a heart breathing,
+ * a chevron flipping, a check mark tracing in) are the supported use case.
+ */
+/**
+ * A single normalized path command after implicit-repeat expansion. The cmd
+ * letter is preserved (absolute vs relative — case is meaningful to the SVG
+ * renderer). `args` always has exactly `CMD_ARGS[cmd]` entries.
+ */
+interface PathSegment {
+    cmd: string;
+    args: number[];
+}
+/**
+ * Parse a path `d` string into a flat list of normalized segments. Implicit
+ * repeats are expanded — `M 0 0 10 10 20 20` becomes three segments
+ * (`M 0 0`, `L 10 10`, `L 20 20`) so the segment list can be compared and
+ * interpolated 1:1 against another path.
+ */
+declare function parsePathD(d: string): PathSegment[];
+/**
+ * The frozen "shape" of a path — just command letters and arg widths. Two
+ * paths are morphable iff their templates are equal.
+ */
+interface PathTemplate {
+    cmds: ReadonlyArray<string>;
+    /** Flat width per segment, indexed parallel to `cmds`. */
+    widths: ReadonlyArray<number>;
+    /** Total scalar count across all segments — `widths.reduce((a,b)=>a+b,0)`. */
+    size: number;
+}
+declare function templateOf(segments: ReadonlyArray<PathSegment>): PathTemplate;
+/** Flatten a parsed segment list into a single number array (length === size). */
+declare function flattenParams(segments: ReadonlyArray<PathSegment>): number[];
+/**
+ * Verify a target template matches the source. Returns `null` on match or a
+ * descriptive error string on mismatch — callers throw in `__DEV__` and
+ * silently snap to the target in production.
+ */
+declare function diffTemplate(source: PathTemplate, target: PathTemplate): string | null;
+/**
+ * Build a path `d` string from a template + flat param array. Runs inside the
+ * worklet on the UI thread, so it must not capture any JS-thread closures or
+ * use Array.prototype helpers that allocate intermediates the Hermes runtime
+ * boxes into JS objects. Manual loops + `+=` string concat keep the worklet
+ * cheap.
+ *
+ * MUST be a worklet — call sites in `MotionPath` wrap it with `'worklet'` via
+ * `useAnimatedProps`.
+ */
+declare function serializePath(template: PathTemplate, params: ReadonlyArray<number>): string;
+
+/**
+ * `@onlynative/inertia-svg` — animatable SVG primitives for
+ * `@onlynative/inertia`.
+ *
+ * v0.2 surface:
+ * - `MotionPath` / `MotionSvg.Path` — animatable `<Path>` over
+ *   `react-native-svg`. Supports path morphing on the `d` attribute (source
+ *   and target must share the same command sequence) plus animatable
+ *   `fill`, `stroke`, `strokeWidth`, `strokeOpacity`, `fillOpacity`,
+ *   `opacity`, and `strokeDashoffset` with the same `initial` /
+ *   `animate` / `transition` shape as the core `Motion.*` primitives.
+ *
+ * Additional shape primitives (`Circle`, `Rect`, `Line`, `Ellipse`) land in
+ * a follow-up once the path morphing API is validated. Path normalization
+ * (resampling between structurally different paths) is out of scope for
+ * v0.2 — use structurally-compatible source/target paths and remount with
+ * `key={...}` to switch shape.
+ */
+
+/**
+ * Namespace bundling every animatable SVG primitive. Use `MotionSvg.Path` for
+ * autocomplete-friendly grouping or import `MotionPath` directly — both
+ * point at the same component.
+ */
+declare const MotionSvg: {
+    readonly Path: typeof MotionPath;
+};
+
+export { MotionPath, type MotionPathProps, MotionSvg, type PathAnimate, type PathPerPropertyTransition, type PathSegment, type PathStateShape, type PathTemplate, type PathTransition, diffTemplate, flattenParams, parsePathD, serializePath, templateOf };

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+import * as react from 'react';
+import { PathProps } from 'react-native-svg';
+import { TransitionConfig } from '@onlynative/inertia';
+
+/**
+ * Animatable target snapshot for a `MotionSvg.Path`. Every field is optional
+ * — include only the dimensions you want to animate; the rest fall back to
+ * the static props on the component.
+ *
+ * `d` morphs the path geometry. The target path **must produce the same
+ * command sequence** as the source after implicit-repeat expansion (same
+ * letters in the same order, e.g. `M L L L Z`). Element-wise numeric
+ * interpolation is the morphing model — see `parsePathD` for the
+ * normalization rules.
+ */
+interface PathAnimate {
+    d?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    fillOpacity?: number;
+    opacity?: number;
+    strokeDashoffset?: number;
+}
+/** The animatable dimensions of a `MotionSvg.Path`. */
+type PathStateShape = {
+    [K in keyof Required<PathAnimate>]: PathAnimate[K];
+};
+/**
+ * Per-property transition map. Top-level entries on `transition` apply to all
+ * properties unless overridden by a per-key entry here.
+ */
+type PathPerPropertyTransition = {
+    [K in keyof PathStateShape]?: TransitionConfig;
+};
+/**
+ * Transition shape accepted by `MotionSvg.Path`. Either a single top-level
+ * transition applied to every animated dimension, or a per-property map.
+ */
+type PathTransition = TransitionConfig | PathPerPropertyTransition;
+
+interface MotionPathProps extends Omit<PathProps, 'd' | 'fill' | 'stroke' | 'strokeWidth' | 'strokeOpacity' | 'fillOpacity' | 'opacity' | 'strokeDashoffset'> {
+    /**
+     * Initial path data. **The command sequence is locked at first render** —
+     * every target `d` passed via `animate` / `initial` must produce the same
+     * command letters in the same order after implicit-repeat expansion. To
+     * morph between structurally different paths, remount with a new `key`.
+     */
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    fillOpacity?: number;
+    opacity?: number;
+    strokeDashoffset?: number;
+    /**
+     * Initial frame override. When present, the component mounts displaying
+     * these values, then animates to `animate` on the next effect. Pass `false`
+     * to skip the initial-mount animation entirely.
+     */
+    initial?: PathAnimate | false;
+    /** Target animation state. */
+    animate?: PathAnimate;
+    /**
+     * Transition config — either a single `TransitionConfig` applied to every
+     * animated dimension, or a per-property map. Per-property entries win over
+     * the top-level transition.
+     */
+    transition?: PathTransition;
+}
+/**
+ * Animatable `<Path>` from `react-native-svg`. Wraps `Path` with declarative
+ * `initial` / `animate` / `transition` props.
+ *
+ * Animatable dimensions:
+ * - `d` — path morph via element-wise scalar interpolation. Source and target
+ *   must share the same command sequence (e.g. both `M L L L Z`).
+ * - `fill`, `stroke` — color strings, interpolated via Reanimated's native
+ *   color animation.
+ * - `strokeWidth`, `strokeOpacity`, `fillOpacity`, `opacity`,
+ *   `strokeDashoffset` — numeric, spring or timing-driven.
+ *
+ * Example:
+ * ```tsx
+ * <Svg viewBox="0 0 100 100">
+ *   <MotionPath
+ *     d="M 50 20 L 80 80 L 20 80 Z"
+ *     animate={{ d: "M 50 80 L 80 20 L 20 20 Z", fill: '#7c3aed' }}
+ *     transition={{ type: 'spring', tension: 140, friction: 12 }}
+ *     fill="#0ea5e9"
+ *   />
+ * </Svg>
+ * ```
+ */
+declare function MotionPath(props: MotionPathProps): react.JSX.Element;
+
+/**
+ * SVG path-string utilities used by `MotionSvg.Path`. Everything here runs on
+ * the JS thread — paths are tokenized into a normalized command list at mount
+ * and when `animate.d` changes; the worklet only ever consumes flat number
+ * arrays + a frozen command template.
+ *
+ * Path morphing in v0.2 requires **structural compatibility**: the source and
+ * every target `d` must produce the same command sequence (same command
+ * letters, in the same order, after implicit-repeat expansion). Element-wise
+ * numeric interpolation is the entire morphing model — we do not resample
+ * paths or insert/remove commands. Same-shape morphs (e.g. a heart breathing,
+ * a chevron flipping, a check mark tracing in) are the supported use case.
+ */
+/**
+ * A single normalized path command after implicit-repeat expansion. The cmd
+ * letter is preserved (absolute vs relative — case is meaningful to the SVG
+ * renderer). `args` always has exactly `CMD_ARGS[cmd]` entries.
+ */
+interface PathSegment {
+    cmd: string;
+    args: number[];
+}
+/**
+ * Parse a path `d` string into a flat list of normalized segments. Implicit
+ * repeats are expanded — `M 0 0 10 10 20 20` becomes three segments
+ * (`M 0 0`, `L 10 10`, `L 20 20`) so the segment list can be compared and
+ * interpolated 1:1 against another path.
+ */
+declare function parsePathD(d: string): PathSegment[];
+/**
+ * The frozen "shape" of a path — just command letters and arg widths. Two
+ * paths are morphable iff their templates are equal.
+ */
+interface PathTemplate {
+    cmds: ReadonlyArray<string>;
+    /** Flat width per segment, indexed parallel to `cmds`. */
+    widths: ReadonlyArray<number>;
+    /** Total scalar count across all segments — `widths.reduce((a,b)=>a+b,0)`. */
+    size: number;
+}
+declare function templateOf(segments: ReadonlyArray<PathSegment>): PathTemplate;
+/** Flatten a parsed segment list into a single number array (length === size). */
+declare function flattenParams(segments: ReadonlyArray<PathSegment>): number[];
+/**
+ * Verify a target template matches the source. Returns `null` on match or a
+ * descriptive error string on mismatch — callers throw in `__DEV__` and
+ * silently snap to the target in production.
+ */
+declare function diffTemplate(source: PathTemplate, target: PathTemplate): string | null;
+/**
+ * Build a path `d` string from a template + flat param array. Runs inside the
+ * worklet on the UI thread, so it must not capture any JS-thread closures or
+ * use Array.prototype helpers that allocate intermediates the Hermes runtime
+ * boxes into JS objects. Manual loops + `+=` string concat keep the worklet
+ * cheap.
+ *
+ * MUST be a worklet — call sites in `MotionPath` wrap it with `'worklet'` via
+ * `useAnimatedProps`.
+ */
+declare function serializePath(template: PathTemplate, params: ReadonlyArray<number>): string;
+
+/**
+ * `@onlynative/inertia-svg` — animatable SVG primitives for
+ * `@onlynative/inertia`.
+ *
+ * v0.2 surface:
+ * - `MotionPath` / `MotionSvg.Path` — animatable `<Path>` over
+ *   `react-native-svg`. Supports path morphing on the `d` attribute (source
+ *   and target must share the same command sequence) plus animatable
+ *   `fill`, `stroke`, `strokeWidth`, `strokeOpacity`, `fillOpacity`,
+ *   `opacity`, and `strokeDashoffset` with the same `initial` /
+ *   `animate` / `transition` shape as the core `Motion.*` primitives.
+ *
+ * Additional shape primitives (`Circle`, `Rect`, `Line`, `Ellipse`) land in
+ * a follow-up once the path morphing API is validated. Path normalization
+ * (resampling between structurally different paths) is out of scope for
+ * v0.2 — use structurally-compatible source/target paths and remount with
+ * `key={...}` to switch shape.
+ */
+
+/**
+ * Namespace bundling every animatable SVG primitive. Use `MotionSvg.Path` for
+ * autocomplete-friendly grouping or import `MotionPath` directly — both
+ * point at the same component.
+ */
+declare const MotionSvg: {
+    readonly Path: typeof MotionPath;
+};
+
+export { MotionPath, type MotionPathProps, MotionSvg, type PathAnimate, type PathPerPropertyTransition, type PathSegment, type PathStateShape, type PathTemplate, type PathTransition, diffTemplate, flattenParams, parsePathD, serializePath, templateOf };