@pixodesk/svg-animator-web 1.0.30 → 1.0.35

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
-export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, JsMode, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterialiseAllOptions, MotionPathMaterialisationOptions, MotionPathSample, OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, PathPoint, PathSampler, PlaybackDirection, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
+import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxAnimatorConfigPatch, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
+export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterialiseAllOptions, MotionPathMaterialisationOptions, MotionPathSample, OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, PathPoint, PathSampler, PlaybackDirection, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigMergeResult, PxAnimatorConfigPatch, PxAnimatorConfigSchema, PxAnimatorConfigShortcuts, PxAnyKeyframe, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCloneWithout, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopDirection, PxLoopRepeatAt, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxNormalisedKeyframe, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxStrokeTrimSubPaths, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTimelineEngine, PxTimelineEngineExtra, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyAnimatorConfig, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, foldAnimatorConfigShortcuts, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, mergeAnimatorConfig, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateDocument, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
 
 /**
  * DOM specialisations of the platform-neutral animator API types.
@@ -34,7 +34,7 @@ declare const PX_ANIMATOR_DATA_KEY = "data";
  * @param containerElement Optional selector or element to render the SVG into.
  * @returns An PxAnimatorAPI instance to programmatically control the animation.
  */
-declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element): PxAnimatorAPI;
+declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element, config?: PxAnimatorConfigPatch, resetDocDefaults?: boolean): PxAnimatorAPI;
 
 interface PxAnimatorOptions {
     /** URL to fetch the animation document from. Provide either this or `data`, not both. */
@@ -47,6 +47,31 @@ interface PxAnimatorOptions {
     callbacks?: PxAnimatorCallbacksConfig;
     /** CSS selector or element to render the SVG into. */
     container?: string | Element;
+    /**
+     * Per-instance override of the document's `animator` config — the same shape as
+     * `animator` in SCHEMA.md, deep-merged over what the document says, so one file can play
+     * twice on a page with different timing. `null` at any slot DELETES that key, which is
+     * how you restore a default that absence means.
+     *
+     * Also accepts a JSON STRING of the same object. Strings are immune to property mangling,
+     * so that form survives a build that renames object keys (see docs/library/minification.md).
+     */
+    config?: PxAnimatorConfigPatch | string;
+    /**
+     * Ignore the document's own playback settings and start from the player's defaults, with
+     * `config` applied on top. The lookup tables (`definitions`, `animateById`) are kept
+     * either way — resetting those would leave the animation with nothing to animate.
+     */
+    resetDocDefaults?: boolean;
+    /** Shortcut for `config.timeline.duration` (ms). Wins over the same key inside `config`. */
+    duration?: number;
+    /** Shortcut for `config.timeline.delay` (ms). */
+    delay?: number;
+    /** Shortcut for `config.timeline.iterations`. */
+    iterations?: number | 'infinite';
+    /** Shortcut for `config.timeline.trigger.startOn`. Typed from the WIRE, so it includes
+     *  `'programmatic'` — the value that says "nothing starts this but a `play()` call". */
+    startOn?: PxTrigger['startOn'];
 }
 /**
  * Creates an animator instance to control SVG animations.
@@ -117,7 +142,7 @@ declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: P
  * @param forceEvenIfHasUnsupportedAttrs If true, an animator will be created even if some CSS properties are not supported.
  * @returns An PxAnimatorAPI instance, or null if unsupported features are used and not forced.
  */
-/** `driver: 'native'` payload (see PxScrollDriver.createNativeScrollTimeline): the
+/** Native scroll-timeline payload (`timeline.engine: 'native'` / `auto`; see PxScrollDriver.createNativeScrollTimeline): the
  *  browser-native timeline every Animation attaches to, plus optional range offsets. */
 interface PxWebApiScrollTimeline {
     timeline: AnimationTimeline;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
-export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, JsMode, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterialiseAllOptions, MotionPathMaterialisationOptions, MotionPathSample, OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, PathPoint, PathSampler, PlaybackDirection, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
+import { PxAnimatorAPI as PxAnimatorAPI$1, PxBasicAnimatorAPI as PxBasicAnimatorAPI$1, PxAnimatedSvgDocument, PxPlatformAdapter, PxAnimatorCallbacksConfig, PxAnimatorConfigPatch, PxTrigger, PxNode, PxDefs } from '@pixodesk/svg-animator-core';
+export { ApplyResult, COLOUR_ATTR_NAMES, ExtendPathOpts, ExtendedPath, FillMode, GlyphCharBox, GlyphCharBoxAlongPath, GlyphMaterialiseOpts, KeysMatch, MISSING_GLYPH_CLASS_NAME, MaterialiseAllOptions, MotionPathMaterialisationOptions, MotionPathSample, OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, PathPoint, PathSampler, PlaybackDirection, PxAnimatable, PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, PxAnimationDefinition, PxAnimationDefinitionSchema, PxAnimatorCallbacksConfig, PxAnimatorConfig, PxAnimatorConfigMergeResult, PxAnimatorConfigPatch, PxAnimatorConfigSchema, PxAnimatorConfigShortcuts, PxAnyKeyframe, PxAttrValue, PxAttrValueSchema, PxBezierPath, PxBezierPathSchema, PxBinding, PxBindingSchema, PxCloneEffect, PxCloneEffectSchema, PxCloneWithout, PxCreateElement, PxDefs, PxDefsSchema, PxEasingOrRefSchema, PxEffects, PxEffectsSchema, PxElementAnimation, PxElementAnimationSchema, PxFillGradientEffect, PxFillGradientEffectSchema, PxGlyph, PxGlyphFont, PxGradientSpreadMethod, PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, PxInfer, PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, PxLoop, PxLoopDirection, PxLoopRepeatAt, PxLoopSchema, PxMaskedByEffect, PxMaskedByEffectSchema, PxNode, PxNodeBase, PxNodeSchema, PxNormalisedKeyframe, PxPlatformAdapter, PxPropertyAnimation, PxPropertyAnimationSchema, PxRepeaterEffect, PxRepeaterEffectSchema, PxRetimeEffect, PxRetimeEffectSchema, PxSchema, PxSchemaDesc, PxStrokeGradientEffect, PxStrokeGradientEffectSchema, PxStrokeTrimEffect, PxStrokeTrimEffectSchema, PxStrokeTrimSubPaths, PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, PxTextPathEffect, PxTextPathEffectSchema, PxTimelineEngine, PxTimelineEngineExtra, PxTransformByEffect, PxTransformByEffectSchema, PxTransformPartKey, PxTransformParts, PxTransformPartsSchema, PxTransformValue, PxTransformValueSchema, PxTrigger, PxTriggerSchema, PxValidationContext, PxValidationResult, RemoveIndex, STYLE_ATTR_NAMES, StartOn, TRANSFORM_FN_NAMES, Vec2, applyAnimatorConfig, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createBasicFrameLoopAnimator, createPathSampler, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, foldAnimatorConfigShortcuts, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, mergeAnimatorConfig, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, schemaKeys, shiftAnimatable, toRGBA, validateDocument, validateNodeEffects, visualModelAt } from '@pixodesk/svg-animator-core';
 
 /**
  * DOM specialisations of the platform-neutral animator API types.
@@ -34,7 +34,7 @@ declare const PX_ANIMATOR_DATA_KEY = "data";
  * @param containerElement Optional selector or element to render the SVG into.
  * @returns An PxAnimatorAPI instance to programmatically control the animation.
  */
-declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element): PxAnimatorAPI;
+declare function createAnimatorImpl(doc: PxAnimatedSvgDocument, adapter?: PxPlatformAdapter, callbacks?: PxAnimatorCallbacksConfig, containerElement?: string | Element, config?: PxAnimatorConfigPatch, resetDocDefaults?: boolean): PxAnimatorAPI;
 
 interface PxAnimatorOptions {
     /** URL to fetch the animation document from. Provide either this or `data`, not both. */
@@ -47,6 +47,31 @@ interface PxAnimatorOptions {
     callbacks?: PxAnimatorCallbacksConfig;
     /** CSS selector or element to render the SVG into. */
     container?: string | Element;
+    /**
+     * Per-instance override of the document's `animator` config — the same shape as
+     * `animator` in SCHEMA.md, deep-merged over what the document says, so one file can play
+     * twice on a page with different timing. `null` at any slot DELETES that key, which is
+     * how you restore a default that absence means.
+     *
+     * Also accepts a JSON STRING of the same object. Strings are immune to property mangling,
+     * so that form survives a build that renames object keys (see docs/library/minification.md).
+     */
+    config?: PxAnimatorConfigPatch | string;
+    /**
+     * Ignore the document's own playback settings and start from the player's defaults, with
+     * `config` applied on top. The lookup tables (`definitions`, `animateById`) are kept
+     * either way — resetting those would leave the animation with nothing to animate.
+     */
+    resetDocDefaults?: boolean;
+    /** Shortcut for `config.timeline.duration` (ms). Wins over the same key inside `config`. */
+    duration?: number;
+    /** Shortcut for `config.timeline.delay` (ms). */
+    delay?: number;
+    /** Shortcut for `config.timeline.iterations`. */
+    iterations?: number | 'infinite';
+    /** Shortcut for `config.timeline.trigger.startOn`. Typed from the WIRE, so it includes
+     *  `'programmatic'` — the value that says "nothing starts this but a `play()` call". */
+    startOn?: PxTrigger['startOn'];
 }
 /**
  * Creates an animator instance to control SVG animations.
@@ -117,7 +142,7 @@ declare function createFrameLoopAnimator(doc: PxAnimatedSvgDocument, adapter?: P
  * @param forceEvenIfHasUnsupportedAttrs If true, an animator will be created even if some CSS properties are not supported.
  * @returns An PxAnimatorAPI instance, or null if unsupported features are used and not forced.
  */
-/** `driver: 'native'` payload (see PxScrollDriver.createNativeScrollTimeline): the
+/** Native scroll-timeline payload (`timeline.engine: 'native'` / `auto`; see PxScrollDriver.createNativeScrollTimeline): the
  *  browser-native timeline every Animation attaches to, plus optional range offsets. */
 interface PxWebApiScrollTimeline {
     timeline: AnimationTimeline;