@pixodesk/svg-animator-rn 1.0.21

package/src/PxRnTracks.test.ts

@@ -0,0 +1,185 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+import { describe, expect, it } from 'vitest';
+import { generateNewIds, materialiseAllInTree, PxAnimatorEngine, type PxAnimatedSvgDocument } from '@pixodesk/svg-animator-core';
+import { compileTracks, sampleProps } from './PxRnTracks';
+import { toRnPropName } from './PxRnPropNames';
+
+function makeDoc(): PxAnimatedSvgDocument {
+    return {
+        type: 'svg',
+        viewBox: '0 0 200 200',
+        animator: { mode: 'frames', duration: 1000, iterations: 2, direction: 'alternate' },
+        children: [
+            {
+                type: 'rect',
+                id: 'r1',
+                x: 0, y: 0, width: 50, height: 50, fill: '#3b82f6',
+                animate: {
+                    opacity: { keyframes: [{ time: 0, value: 1 }, { time: 1000, value: 0 }] },
+                    fill: { keyframes: [{ time: 0, value: '#3b82f6' }, { time: 1000, value: '#ec4899' }] },
+                    'stroke-width': { keyframes: [{ time: 0, value: 1 }, { time: 1000, value: 5 }] },
+                },
+            },
+            {
+                type: 'g',
+                id: 'g1',
+                animate: {
+                    translate: { keyframes: [{ time: 0, value: [0, 0] }, { time: 1000, value: [100, 100] }] },
+                },
+                children: [{ type: 'circle', cx: 0, cy: 0, r: 10, fill: '#000' }],
+            },
+        ],
+    };
+}
+
+function compile(doc = makeDoc(), opts?: Parameters<typeof compileTracks>[1]) {
+    const materialised = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.frames));
+    return compileTracks(materialised, opts);
+}
+
+describe('compileTracks', () => {
+    it('captures animator config (duration, iterations, direction, fill default)', () => {
+        const tracks = compile();
+        expect(tracks.duration).toBe(1000);
+        expect(tracks.iterations).toBe(2);
+        expect(tracks.direction).toBe('alternate');
+        expect(tracks.fill).toBe('forwards');
+        expect(tracks.sampleCount).toBeGreaterThanOrEqual(2);
+        expect(tracks.stepMs * (tracks.sampleCount - 1)).toBeCloseTo(1000, 6);
+    });
+
+    it('produces one track set per animated element', () => {
+        const tracks = compile();
+        expect(tracks.elements.length).toBe(2);
+    });
+
+    it('samples numeric props with endpoint accuracy (opacity 1 → 0)', () => {
+        const tracks = compile();
+        const rect = tracks.elements.find(e => 'opacity' in e.props)!;
+        const op = rect.props.opacity;
+        expect(op[0]).toBe(1);
+        expect(op[op.length - 1]).toBe(0);
+        // midpoint ≈ 0.5 (linear)
+        expect(+op[Math.floor(op.length / 2)]).toBeCloseTo(0.5, 1);
+    });
+
+    it('converts attr names to react-native-svg prop names (stroke-width → strokeWidth)', () => {
+        const tracks = compile();
+        const rect = tracks.elements.find(e => 'opacity' in e.props)!;
+        expect(rect.props.strokeWidth).toBeDefined();
+        expect(rect.props['stroke-width']).toBeUndefined();
+        expect(+rect.props.strokeWidth[0]).toBe(1);
+        expect(+rect.props.strokeWidth[rect.props.strokeWidth.length - 1]).toBe(5);
+    });
+
+    it('samples colour props as rgba strings', () => {
+        const tracks = compile();
+        const rect = tracks.elements.find(e => 'fill' in e.props)!;
+        expect(String(rect.props.fill[0])).toMatch(/^rgba\(/);
+        expect(String(rect.props.fill[rect.props.fill.length - 1])).toMatch(/^rgba\(/);
+        expect(rect.props.fill[0]).not.toBe(rect.props.fill[rect.props.fill.length - 1]);
+    });
+
+    it('samples transforms as composed transform strings', () => {
+        const tracks = compile();
+        const g = tracks.elements.find(e => 'transform' in e.props)!;
+        expect(String(g.props.transform[0])).toContain('translate(0');
+        expect(String(g.props.transform[g.props.transform.length - 1])).toContain('translate(100');
+    });
+
+    it('respects sampleRate and maxSamples options', () => {
+        const coarse = compile(makeDoc(), { sampleRate: 10 });
+        expect(coarse.sampleCount).toBe(11); // 1s at 10/s + endpoint
+        const capped = compile(makeDoc(), { sampleRate: 1000, maxSamples: 50 });
+        expect(capped.sampleCount).toBe(50);
+    });
+
+    it('every track array is fully populated (no holes)', () => {
+        const tracks = compile();
+        for (const el of tracks.elements) {
+            for (const arr of Object.values(el.props)) {
+                expect(arr.length).toBe(tracks.sampleCount);
+                expect(arr.every(v => v !== undefined)).toBe(true);
+            }
+        }
+    });
+});
+
+describe('sampleProps', () => {
+    it('indexes the nearest sample and clamps at both ends', () => {
+        const tracks = compile();
+        const rect = tracks.elements.find(e => 'opacity' in e.props)!;
+        const { stepMs, sampleCount } = tracks;
+
+        expect(sampleProps(rect, 0, stepMs, sampleCount).opacity).toBe(1);
+        expect(sampleProps(rect, 1000, stepMs, sampleCount).opacity).toBe(0);
+        // out-of-range clamps
+        expect(sampleProps(rect, -50, stepMs, sampleCount).opacity).toBe(1);
+        expect(sampleProps(rect, 5000, stepMs, sampleCount).opacity).toBe(0);
+        // midpoint
+        expect(+sampleProps(rect, 500, stepMs, sampleCount).opacity).toBeCloseTo(0.5, 1);
+    });
+});
+
+describe('toRnPropName', () => {
+    it('camelCases kebab attrs and maps known overrides', () => {
+        expect(toRnPropName('stroke-width')).toBe('strokeWidth');
+        expect(toRnPropName('fill')).toBe('fill');
+        expect(toRnPropName('xlink:href')).toBe('href');
+    });
+    it('drops web-only props', () => {
+        expect(toRnPropName('class')).toBeUndefined();
+        expect(toRnPropName('style')).toBeUndefined();
+    });
+});
+
+describe('length-list props (stroke-dasharray)', () => {
+    it('compiles stroke-dasharray into number arrays (rn-svg native shape)', () => {
+        const doc: PxAnimatedSvgDocument = {
+            type: 'svg', viewBox: '0 0 100 100',
+            animator: { mode: 'frames', duration: 1000 },
+            children: [{
+                type: 'path', id: 'p', d: 'M 0 50 L 100 50', stroke: '#000', fill: 'none',
+                effects: { trimPath: { range: { keyframes: [{ time: 0, value: [0, 0.1] }, { time: 1000, value: [0, 1] }] } } },
+            }],
+        };
+        const materialised = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.webapi));
+        const tracks = compileTracks(materialised);
+        const el = tracks.elements.find(e => 'strokeDasharray' in e.props)!;
+        expect(el).toBeDefined();
+        const first = el.props.strokeDasharray[0];
+        expect(Array.isArray(first)).toBe(true);
+        expect((first as number[]).every(n => typeof n === 'number' && Number.isFinite(n))).toBe(true);
+        expect((first as number[]).length % 2).toBe(0);
+    });
+});
+
+describe('animated <use> flattening (webapi materialisation)', () => {
+    it('inlines animated <use> clones so no live references remain', () => {
+        const doc: PxAnimatedSvgDocument = {
+            type: 'svg', viewBox: '0 0 300 200',
+            animator: { mode: 'frames', duration: 2000 },
+            children: [
+                { type: 'defs', children: [{ type: 'g', id: 'sym', children: [{
+                    type: 'circle', id: 'c', cx: 30, cy: 40, r: 16, fill: '#f59e0b',
+                    animate: { cy: { keyframes: [{ time: 0, value: 40 }, { time: 2000, value: 160 }] } },
+                }] }] },
+                { type: 'use', id: 'u1', href: '#sym' },
+                { type: 'use', id: 'u2', href: '#sym', x: 80, effects: { clone: { baseId: 'sym', retime: { start: -600 } } } },
+            ],
+        };
+        const materialised = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.webapi));
+        const countUse = (n: any): number =>
+            (n.type === 'use' ? 1 : 0) + (n.children || []).reduce((s: number, c: any) => s + countUse(c), 0);
+        expect(countUse(materialised)).toBe(0);
+
+        const tracks = compileTracks(materialised);
+        const cyTracks = tracks.elements.filter(e => 'cy' in e.props);
+        expect(cyTracks.length).toBe(2);
+        expect(cyTracks[0].props.cy[0]).not.toBe(cyTracks[1].props.cy[0]);
+    });
+});

package/src/PxRnTracks.ts

@@ -0,0 +1,150 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+import {
+    calcAnimationValues,
+    getAnimatorConfig,
+    getNormalisedBindings,
+    DEFAULT_DURATION_MS,
+    PxAnimatorEngine,
+    type PxAnimatedSvgDocument,
+    type PxAnimationDefinition,
+} from '@pixodesk/svg-animator-core';
+import { toRnPropName, toRnPropValue } from './PxRnPropNames';
+
+/**
+ * Sampled animation tracks for ONE element: prop name → per-sample values.
+ *
+ * The compiler densely samples every animated property through core's
+ * `calcAnimationValues` — the exact function the web frames engine renders
+ * with — so RN playback is value-identical to the web player. Easing, loops,
+ * transform composition, colour interpolation and path morphing are all baked
+ * into the samples at compile time; the UI-thread worklet only indexes arrays.
+ */
+export interface PxElementTracks {
+    /** Element id (after id regeneration). */
+    id: string;
+    /** react-native-svg prop name → one value per sample. */
+    props: Record<string, Array<string | number | Array<number>>>;
+}
+
+export interface PxCompiledTracks {
+    /** Per-iteration duration, ms. */
+    duration: number;
+    /** Iteration count (Infinity for 'infinite'). */
+    iterations: number;
+    /** 'normal' | 'reverse' | 'alternate' | 'alternate-reverse' */
+    direction: string;
+    /** Delay before start, ms (positive = wait). */
+    delay: number;
+    /** WAAPI-style fill mode (default 'forwards'). */
+    fill: string;
+    /** Sample step, ms. */
+    stepMs: number;
+    /** Number of samples per iteration (>= 2; sample i is at time i*stepMs). */
+    sampleCount: number;
+    /** Tracks for every animated element. */
+    elements: Array<PxElementTracks>;
+}
+
+export interface CompileTracksOptions {
+    /** Target sample rate, samples/second. Default 60 (one per frame). */
+    sampleRate?: number;
+    /** Hard cap on samples per iteration (memory guard). Default 600. */
+    maxSamples?: number;
+}
+
+
+
+/**
+ * Compiles a MATERIALISED document (run `materialiseAllInTree(doc, 'frames')`
+ * + `generateNewIds` first) into densely sampled per-element tracks.
+ */
+export function compileTracks(doc: PxAnimatedSvgDocument, opts?: CompileTracksOptions): PxCompiledTracks {
+    const config = getAnimatorConfig(doc) || {};
+
+    const duration = +(config.duration || DEFAULT_DURATION_MS);
+    const _iterations = config.iterations;
+    let iterations = 1;
+    if (typeof _iterations === 'number') iterations = _iterations || 1;
+    if (_iterations === 'infinite') iterations = Infinity;
+    if (iterations < 1) iterations = 1;
+
+    const sampleRate = opts?.sampleRate ?? 60;
+    const maxSamples = opts?.maxSamples ?? 600;
+    let sampleCount = Math.max(2, Math.round((duration / 1000) * sampleRate) + 1);
+    if (sampleCount > maxSamples) sampleCount = maxSamples;
+    const stepMs = duration / (sampleCount - 1);
+
+    const bindings = getNormalisedBindings(doc, PxAnimatorEngine.frames) || [];
+
+    const elements: Array<PxElementTracks> = [];
+    for (const binding of bindings) {
+        const animDef = binding.animate;
+        if (!animDef || typeof animDef !== 'object' || Array.isArray(animDef)) continue;
+
+        const props: Record<string, Array<string | number | Array<number>>> = {};
+        for (let i = 0; i < sampleCount; i++) {
+            const t = i === sampleCount - 1 ? duration : i * stepMs;
+            const values = calcAnimationValues(animDef as PxAnimationDefinition, t);
+            for (const [attr, value] of Object.entries(values)) {
+                const rnProp = toRnPropName(attr);
+                if (!rnProp) continue;
+                let arr = props[rnProp];
+                if (!arr) {
+                    arr = props[rnProp] = new Array(sampleCount);
+                    // A prop can appear late (e.g. attrs whose first kf is
+                    // beyond t=0) — backfill earlier samples with the first
+                    // computed value so the array is always fully populated.
+                    for (let j = 0; j < i; j++) arr[j] = toRnPropValue(rnProp, value);
+                }
+                arr[i] = toRnPropValue(rnProp, value);
+            }
+        }
+        // Forward-fill any holes (attr disappeared from a later sample).
+        for (const arr of Object.values(props)) {
+            for (let i = 1; i < sampleCount; i++) {
+                if (arr[i] === undefined) arr[i] = arr[i - 1];
+            }
+        }
+
+        if (Object.keys(props).length > 0) {
+            elements.push({ id: binding.id, props });
+        }
+    }
+
+    return {
+        duration,
+        iterations,
+        direction: config.direction || 'normal',
+        delay: config.delay || 0,
+        fill: config.fill ?? 'forwards',
+        stepMs,
+        sampleCount,
+        elements,
+    };
+}
+
+/**
+ * Worklet-safe sample lookup: returns the per-prop values at time `tMs`
+ * (already mapped into a single iteration by the caller). Kept deliberately
+ * trivial — runs on the UI thread every frame.
+ */
+export function sampleProps(
+    tracks: PxElementTracks,
+    tMs: number,
+    stepMs: number,
+    sampleCount: number
+): Record<string, string | number | Array<number>> {
+    'worklet';
+    let idx = Math.round(tMs / stepMs);
+    if (idx < 0) idx = 0;
+    if (idx >= sampleCount) idx = sampleCount - 1;
+    const out: Record<string, string | number | Array<number>> = {};
+    for (const key in tracks.props) {
+        out[key] = tracks.props[key][idx];
+    }
+    return out;
+}

package/src/PxRnTypeMap.ts

@@ -0,0 +1,64 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+import {
+    Circle,
+    ClipPath,
+    Defs,
+    Ellipse,
+    G,
+    Image,
+    Line,
+    LinearGradient,
+    Marker,
+    Mask,
+    Path,
+    Pattern,
+    Polygon,
+    Polyline,
+    RadialGradient,
+    Rect,
+    Stop,
+    Svg,
+    Symbol as SvgSymbol,
+    Text as SvgText,
+    TextPath,
+    TSpan,
+    Use,
+} from 'react-native-svg';
+import type { ComponentType } from 'react';
+
+/**
+ * SVG tag → react-native-svg component. Tags not in this map are skipped at
+ * render time (with a warning collected by the renderer) — they go on the
+ * feature-gap list rather than crashing the tree.
+ */
+export const RN_SVG_COMPONENTS: Record<string, ComponentType<any>> = {
+    svg: Svg,
+    g: G,
+    rect: Rect,
+    circle: Circle,
+    ellipse: Ellipse,
+    line: Line,
+    path: Path,
+    polygon: Polygon,
+    polyline: Polyline,
+    text: SvgText,
+    tspan: TSpan,
+    textPath: TextPath,
+    defs: Defs,
+    linearGradient: LinearGradient,
+    radialGradient: RadialGradient,
+    stop: Stop,
+    use: Use,
+    symbol: SvgSymbol,
+    mask: Mask,
+    clipPath: ClipPath,
+    pattern: Pattern,
+    marker: Marker,
+    image: Image,
+};
+
+export { toRnPropName } from './PxRnPropNames';

package/src/index.ts

@@ -0,0 +1,15 @@
+/*---------------------------------------------------------------------------------------
+ * Copyright (c) Pixodesk LTD.
+ * Licensed under the MIT License. See the LICENSE file in the project root for details.
+ *---------------------------------------------------------------------------------------*/
+
+export { PixodeskSvgAnimator, default } from './PixodeskSvgAnimator';
+export type { PixodeskSvgAnimatorProps, RnAnimatorApi } from './PixodeskSvgAnimator';
+
+export { renderRnNode, toRnProps } from './PxRnRender';
+export type { RenderRnNodeOptions } from './PxRnRender';
+
+export { compileTracks, sampleProps } from './PxRnTracks';
+export type { CompileTracksOptions, PxCompiledTracks, PxElementTracks } from './PxRnTracks';
+
+export { RN_SVG_COMPONENTS, toRnPropName } from './PxRnTypeMap';