@pixodesk/svg-animator-rn 1.0.21 → 1.0.24

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { PxAnimatedSvgDocument, FillMode, PlaybackDirection, PxNode } from '@pixodesk/svg-animator-core';
-import React, { ReactElement, ComponentType, ReactNode } from 'react';
+import { PxAnimatedSvgDocument, FillMode, PlaybackDirection, OutAction, PxDefs, PxNode } from '@pixodesk/svg-animator-core';
+import React, { ReactElement, ComponentType, ReactNode, Component, ErrorInfo } from 'react';
 
 /** Imperative playback API — mirrors ReactAnimatorApi from svg-animator-react. */
 interface RnAnimatorApi {
@@ -33,6 +33,13 @@ interface PixodeskSvgAnimatorProps {
     fill?: FillMode;
     /** Playback direction. */
     direction?: PlaybackDirection;
+    /** Snap back to the start state after a natural finish. */
+    resetOnFinish?: boolean;
+    /**
+     * What a second tap does when `startOn: 'click'` is active.
+     * Defaults to the document's `trigger.outAction`, else `'pause'`.
+     */
+    outAction?: OutAction;
     /** When true, honours the document trigger (`startOn: 'load'` plays on mount). */
     autoplay?: boolean;
     /** Starts playback unconditionally. */
@@ -50,6 +57,17 @@ interface PixodeskSvgAnimatorProps {
     onPause?: () => void;
     onCancel?: () => void;
     onFinish?: () => void;
+    /**
+     * Called when a document cannot be compiled or rendered. The component
+     * renders {@link fallback} instead of throwing, so a single broken
+     * animation never takes down the screen around it.
+     *
+     * Only JavaScript failures reach this — a crash inside react-native-svg's
+     * native renderer bypasses JavaScript entirely.
+     */
+    onError?: (error: Error, componentStack?: string) => void;
+    /** Rendered in place of the animation after a failure. Default: nothing. */
+    fallback?: (error: Error) => ReactElement | null;
 }
 /**
  * React Native component for rendering and controlling Pixodesk SVG animations.
@@ -61,25 +79,31 @@ interface PixodeskSvgAnimatorProps {
  * `withTiming`/`withRepeat` on the UI thread, with per-element worklets
  * indexing the precompiled tracks. No JS-thread frame loop.
  */
-declare function PixodeskSvgAnimator({ doc, duration, delay, iterations, fill, direction, autoplay, play, pause, apiRef, time, timeMs, onPlay, onStop, onPause, onCancel, onFinish, }: PixodeskSvgAnimatorProps): ReactElement | null;
+declare function PixodeskSvgAnimator({ doc, duration, delay, iterations, fill, direction, resetOnFinish, outAction: outActionProp, autoplay, play, pause, apiRef, time, timeMs, onPlay, onStop, onPause, onCancel, onFinish, onError, fallback, }: PixodeskSvgAnimatorProps): ReactElement | null;
 
 interface RenderRnNodeOptions {
     /** Collects non-fatal issues (unsupported tags, dropped attrs). */
     warnings?: Array<string>;
+    /** `definitions` from the document, used to resolve named `style` presets. */
+    defs?: PxDefs;
     /**
      * Wraps the created element for animated nodes: receives the resolved
      * component + static props and returns the element to mount (the animator
      * substitutes an Animated component wired to its tracks). Return undefined
      * to keep the plain static element.
+     *
+     * `key` is handed over SEPARATELY and is deliberately absent from `props`:
+     * React 19 warns when a props object containing `key` is spread into JSX,
+     * and implementations of this hook do exactly that.
      */
-    decorate?: (node: PxNode, Component: ComponentType<any>, props: Record<string, any>, children: ReactNode) => ReactElement | undefined;
+    decorate?: (node: PxNode, Component: ComponentType<any>, props: Record<string, any>, children: ReactNode, key: string | number | undefined) => ReactElement | undefined;
 }
 /**
  * Converts core-normalised wire props into react-native-svg props: RN prop
  * naming, sanitisation (same security rules as the web renderer), numeric
  * coercion where possible.
  */
-declare function toRnProps(props: Record<string, any>, warnings?: Array<string>): Record<string, any>;
+declare function toRnProps(props: Record<string, any>, warnings?: Array<string>, tag?: string): Record<string, any>;
 /**
  * Renders a (materialised) PxNode tree to react-native-svg elements.
  * Mirrors the web `renderNode` contract: unsupported/dangerous tags are
@@ -87,6 +111,59 @@ declare function toRnProps(props: Record<string, any>, warnings?: Array<string>)
  */
 declare function renderRnNode(node: PxNode, opts?: RenderRnNodeOptions, key?: string | number): ReactElement | null;
 
+interface PxRnErrorBoundaryProps {
+    children: ReactNode;
+    /** Rendered instead of the children once something has thrown. */
+    fallback?: (error: Error) => ReactNode;
+    onError?: (error: Error, info?: string) => void;
+}
+interface State {
+    error: Error | null;
+}
+/**
+ * Keeps one bad animation from taking down the screen around it.
+ *
+ * A throw anywhere in the rendered SVG tree — an unsupported prop shape, a
+ * react-native-svg internal, a reanimated attachment failure — otherwise
+ * unmounts the whole React tree above it. Here it is contained to this one
+ * animation, reported through `onError`, and replaced by `fallback`.
+ *
+ * NOTE the limit: this catches JavaScript errors only. A crash INSIDE the
+ * native renderer (see `openClosedTextPathTargets` for a real example) never
+ * reaches JavaScript and cannot be caught here — those have to be avoided
+ * rather than handled.
+ */
+declare class PxRnErrorBoundary extends Component<PxRnErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(prev: PxRnErrorBoundaryProps): void;
+    render(): ReactNode;
+}
+
+/**
+ * Gives every `<textPath>` that follows a CLOSED path its own OPEN copy of it.
+ *
+ * WHY: react-native-svg's native text-on-path layout crashes the app —
+ * an uncatchable `NSRangeException` on iOS — for this combination.
+ * `RNSVGTSpan.mm` skips glyphs outside `[startOfRendering, endOfRendering]`,
+ * but for a closed path it sets those bounds to `startOffset … startOffset +
+ * pathLength` instead of `0 … pathLength`. Any glyph past the end of the path
+ * therefore survives the bounds check and reaches `getPosAndTan`, whose
+ * `indexOfObjectPassingTest` returns `NSNotFound` — and indexing the lengths
+ * array with `NSNotFound` throws. A non-zero `startOffset` on a closed path is
+ * all it takes, and animating `startOffset` guarantees hitting it.
+ *
+ * Opening the path restores the `0 … pathLength` bounds, so out-of-range
+ * glyphs are skipped as intended. The copy is private to the `<textPath>`, so
+ * anything else drawing the same path still gets the closed original. For a
+ * shape whose ends already meet (a circle, the usual case) the removed segment
+ * has zero length and nothing changes visually at all.
+ *
+ * Returns the document unchanged — the same object — when nothing matches.
+ */
+declare function openClosedTextPathTargets(doc: PxNode, warnings?: Array<string>): PxNode;
+
 /**
  * Sampled animation tracks for ONE element: prop name → per-sample values.
  *
@@ -113,6 +190,8 @@ interface PxCompiledTracks {
     delay: number;
     /** WAAPI-style fill mode (default 'forwards'). */
     fill: string;
+    /** When true, snap back to the start after a natural finish. */
+    resetOnFinish: boolean;
     /** Sample step, ms. */
     stepMs: number;
     /** Number of samples per iteration (>= 2; sample i is at time i*stepMs). */
@@ -125,6 +204,15 @@ interface CompileTracksOptions {
     sampleRate?: number;
     /** Hard cap on samples per iteration (memory guard). Default 600. */
     maxSamples?: number;
+    /**
+     * Sample values in the form the NATIVE react-native-svg views expect
+     * (currently: `transform` as a 6-number matrix rather than an SVG string).
+     *
+     * Defaults to `false` — the plain SVG form, which is what react-native-web
+     * hands straight to the DOM. Only the component knows the platform, so it
+     * decides; every consumer that does not opt in keeps DOM-compatible values.
+     */
+    native?: boolean;
 }
 /**
  * Compiles a MATERIALISED document (run `materialiseAllInTree(doc, 'frames')`
@@ -135,8 +223,13 @@ declare function compileTracks(doc: PxAnimatedSvgDocument, opts?: CompileTracksO
  * 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.
+ *
+ * `native = true` applies {@link NATIVE_PROP_NAME} — pass it only on the
+ * reanimated animated-props path of a real device. Props that are applied by
+ * re-rendering through React (and therefore still pass through react-native-svg's
+ * JS layer), and every value on the web, must keep the wire name.
  */
-declare function sampleProps(tracks: PxElementTracks, tMs: number, stepMs: number, sampleCount: number): Record<string, string | number | Array<number>>;
+declare function sampleProps(tracks: PxElementTracks, tMs: number, stepMs: number, sampleCount: number, native?: boolean): Record<string, string | number | Array<number>>;
 
 /**
  * Converts one normalised wire attribute name (camelCase after core's
@@ -152,7 +245,10 @@ declare function toRnPropName(attrName: string): string | undefined;
  * 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.
+ *
+ * Keys are the wire-format `node.type` values, which follow SVG's own casing
+ * (`clipPath`, `feGaussianBlur`, `linearGradient`, …).
  */
 declare const RN_SVG_COMPONENTS: Record<string, ComponentType<any>>;
 
-export { type CompileTracksOptions, PixodeskSvgAnimator, type PixodeskSvgAnimatorProps, type PxCompiledTracks, type PxElementTracks, RN_SVG_COMPONENTS, type RenderRnNodeOptions, type RnAnimatorApi, compileTracks, PixodeskSvgAnimator as default, renderRnNode, sampleProps, toRnPropName, toRnProps };
+export { type CompileTracksOptions, PixodeskSvgAnimator, type PixodeskSvgAnimatorProps, type PxCompiledTracks, type PxElementTracks, PxRnErrorBoundary, type PxRnErrorBoundaryProps, RN_SVG_COMPONENTS, type RenderRnNodeOptions, type RnAnimatorApi, compileTracks, PixodeskSvgAnimator as default, openClosedTextPathTargets, renderRnNode, sampleProps, toRnPropName, toRnProps };