@pixodesk/svg-animator-web 1.0.8 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/dist/index.cjs +953 -611
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +50 -3
  4. package/dist/index.d.ts +50 -3
  5. package/dist/index.js +953 -611
  6. package/dist/index.js.map +1 -1
  7. package/dist/index.min.cjs +1 -1
  8. package/dist/index.min.js +1 -1
  9. package/dist/index.umd.js +953 -611
  10. package/dist/index.umd.js.map +1 -1
  11. package/dist/index.umd.min.js +1 -1
  12. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -2,6 +2,10 @@ type FillMode = 'forwards' | 'backwards' | 'both' | 'none';
2
2
  type PlaybackDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
3
3
  declare const PX_ANIM_SRC_ATTR_NAME = "data-px-animation-src";
4
4
  declare const PX_ANIM_ATTR_NAME = "_px_animator";
5
+ type StartOn = 'load' | 'mouseOver' | 'click' | 'scrollIntoView';
6
+ type StartOnExtra = StartOn | 'programmatic';
7
+ type OutAction = 'continue' | 'pause' | 'reset' | 'reverse';
8
+ type JsMode = "auto" | "webapi" | "frames";
5
9
  /**
6
10
  * Easing function definition.
7
11
  * Can be a named reference to a predefined easing or a cubic-bezier array [x1, y1, x2, y2].
@@ -27,6 +31,46 @@ interface PxKeyframe {
27
31
  /** Short alias for "easing" */
28
32
  e?: PxEasingOrRef;
29
33
  }
34
+ /**
35
+ * Defines how a property's keyframe animation is extended beyond its defined keyframe range
36
+ * by continuously repeating a chosen segment of the sequence.
37
+ *
38
+ * The repeated segment is a contiguous run of keyframe *intervals* (gaps between consecutive
39
+ * keyframes). Which end of the sequence is repeated is controlled by `before`, and whether
40
+ * each repetition plays in the same direction or alternates is controlled by `alternate`.
41
+ */
42
+ interface PxLoop {
43
+ /**
44
+ * Number of keyframe intervals (gaps between consecutive keyframes) that form the repeating
45
+ * segment.
46
+ *
47
+ * - `undefined` → the entire keyframe sequence is used as the loop segment.
48
+ * - `N` → only the first `N` intervals (when `before: true`) or the last `N` intervals
49
+ * (when `before: false`) are looped. Clamped to `[1, keyframes.length - 1]`.
50
+ */
51
+ segmentCount?: number;
52
+ /**
53
+ * Selects which end of the keyframe sequence is looped.
54
+ *
55
+ * - `true` → the source segment is taken from the *start* of the keyframe sequence.
56
+ * The animation is extended *before* the first keyframe — useful for intro loops
57
+ * that run before the main timeline begins.
58
+ *
59
+ * - `false` (default) → the source segment is taken from the *end* of the keyframe sequence.
60
+ * The animation is extended *after* the last keyframe — useful for idle or outro
61
+ * loops that continue once the main timeline has finished.
62
+ */
63
+ before?: boolean;
64
+ /**
65
+ * Controls playback direction on each successive loop iteration.
66
+ *
67
+ * - `false` (default) → **cycle**: every iteration replays the segment in the same direction.
68
+ *
69
+ * - `true` → **pingpong**: iterations alternate between forward and backward playback
70
+ * (even iterations play forward, odd iterations play in reverse).
71
+ */
72
+ alternate?: boolean;
73
+ }
30
74
  /**
31
75
  * Animation definition for a single CSS/SVG property.
32
76
  * Contains an array of keyframes that define how the property changes over time.
@@ -36,6 +80,9 @@ interface PxPropertyAnimation {
36
80
  keyframes?: PxKeyframe[];
37
81
  /** Short alias for "keyframes" */
38
82
  kfs?: PxKeyframe[];
83
+ /** Optional loop configuration. When set, the keyframe sequence is extended beyond its defined
84
+ * range by repeating a chosen segment. See {@link PxLoop} for details. */
85
+ loop?: PxLoop | boolean;
39
86
  }
40
87
  /**
41
88
  * Complete animation definition containing one or more property animations.
@@ -55,7 +102,7 @@ interface PxAnimationDefinition {
55
102
  */
56
103
  interface PxTrigger {
57
104
  /** Event that starts the animation */
58
- startOn?: 'load' | 'mouseOver' | 'click' | 'scrollIntoView' | 'programmatic';
105
+ startOn?: StartOnExtra;
59
106
  /** Action to take when the trigger condition is no longer met (e.g., mouse leaves) */
60
107
  outAction?: 'continue' | 'pause' | 'reset' | 'reverse';
61
108
  /** Percentage of element visibility required to trigger (0-1). Only applies to scrollIntoView. */
@@ -67,7 +114,7 @@ interface PxTrigger {
67
114
  */
68
115
  interface PxAnimatorConfig {
69
116
  /** JavaScript animation implementation strategy */
70
- mode?: "auto" | "webapi" | "frames";
117
+ mode?: JsMode;
71
118
  /** Total animation duration in milliseconds */
72
119
  duration?: number;
73
120
  /** Delay before animation starts in milliseconds */
@@ -393,4 +440,4 @@ declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
393
440
  */
394
441
  declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean): PxAnimatorAPI | null;
395
442
 
396
- export { COLOUR_ATTR_NAMES, type FillMode, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimationDefinition, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, type PxBezierPath, type PxBinding, type PxDefs, type PxElementAnimation, type PxKeyframe, type PxNode, type PxPlatformAdapter, type PxPropertyAnimation, type PxSvgNode, type PxTrigger, type PxValidationResult, STYLE_ATTR_NAMES, TRANSFORM_FN_NAMES, calcAnimationValues, camelCaseToKebabWordIfNeeded, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, loadTagAnimators, getNormalisedBindings as normalizeDocument, renderNode, setupAnimationTriggers, toRGBA };
443
+ export { COLOUR_ATTR_NAMES, type FillMode, type JsMode, type OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimationDefinition, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, type PxBezierPath, type PxBinding, type PxDefs, type PxElementAnimation, type PxKeyframe, type PxNode, type PxPlatformAdapter, type PxPropertyAnimation, type PxSvgNode, type PxTrigger, type PxValidationResult, STYLE_ATTR_NAMES, type StartOn, TRANSFORM_FN_NAMES, calcAnimationValues, camelCaseToKebabWordIfNeeded, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, loadTagAnimators, getNormalisedBindings as normalizeDocument, renderNode, setupAnimationTriggers, toRGBA };
package/dist/index.d.ts CHANGED
@@ -2,6 +2,10 @@ type FillMode = 'forwards' | 'backwards' | 'both' | 'none';
2
2
  type PlaybackDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
3
3
  declare const PX_ANIM_SRC_ATTR_NAME = "data-px-animation-src";
4
4
  declare const PX_ANIM_ATTR_NAME = "_px_animator";
5
+ type StartOn = 'load' | 'mouseOver' | 'click' | 'scrollIntoView';
6
+ type StartOnExtra = StartOn | 'programmatic';
7
+ type OutAction = 'continue' | 'pause' | 'reset' | 'reverse';
8
+ type JsMode = "auto" | "webapi" | "frames";
5
9
  /**
6
10
  * Easing function definition.
7
11
  * Can be a named reference to a predefined easing or a cubic-bezier array [x1, y1, x2, y2].
@@ -27,6 +31,46 @@ interface PxKeyframe {
27
31
  /** Short alias for "easing" */
28
32
  e?: PxEasingOrRef;
29
33
  }
34
+ /**
35
+ * Defines how a property's keyframe animation is extended beyond its defined keyframe range
36
+ * by continuously repeating a chosen segment of the sequence.
37
+ *
38
+ * The repeated segment is a contiguous run of keyframe *intervals* (gaps between consecutive
39
+ * keyframes). Which end of the sequence is repeated is controlled by `before`, and whether
40
+ * each repetition plays in the same direction or alternates is controlled by `alternate`.
41
+ */
42
+ interface PxLoop {
43
+ /**
44
+ * Number of keyframe intervals (gaps between consecutive keyframes) that form the repeating
45
+ * segment.
46
+ *
47
+ * - `undefined` → the entire keyframe sequence is used as the loop segment.
48
+ * - `N` → only the first `N` intervals (when `before: true`) or the last `N` intervals
49
+ * (when `before: false`) are looped. Clamped to `[1, keyframes.length - 1]`.
50
+ */
51
+ segmentCount?: number;
52
+ /**
53
+ * Selects which end of the keyframe sequence is looped.
54
+ *
55
+ * - `true` → the source segment is taken from the *start* of the keyframe sequence.
56
+ * The animation is extended *before* the first keyframe — useful for intro loops
57
+ * that run before the main timeline begins.
58
+ *
59
+ * - `false` (default) → the source segment is taken from the *end* of the keyframe sequence.
60
+ * The animation is extended *after* the last keyframe — useful for idle or outro
61
+ * loops that continue once the main timeline has finished.
62
+ */
63
+ before?: boolean;
64
+ /**
65
+ * Controls playback direction on each successive loop iteration.
66
+ *
67
+ * - `false` (default) → **cycle**: every iteration replays the segment in the same direction.
68
+ *
69
+ * - `true` → **pingpong**: iterations alternate between forward and backward playback
70
+ * (even iterations play forward, odd iterations play in reverse).
71
+ */
72
+ alternate?: boolean;
73
+ }
30
74
  /**
31
75
  * Animation definition for a single CSS/SVG property.
32
76
  * Contains an array of keyframes that define how the property changes over time.
@@ -36,6 +80,9 @@ interface PxPropertyAnimation {
36
80
  keyframes?: PxKeyframe[];
37
81
  /** Short alias for "keyframes" */
38
82
  kfs?: PxKeyframe[];
83
+ /** Optional loop configuration. When set, the keyframe sequence is extended beyond its defined
84
+ * range by repeating a chosen segment. See {@link PxLoop} for details. */
85
+ loop?: PxLoop | boolean;
39
86
  }
40
87
  /**
41
88
  * Complete animation definition containing one or more property animations.
@@ -55,7 +102,7 @@ interface PxAnimationDefinition {
55
102
  */
56
103
  interface PxTrigger {
57
104
  /** Event that starts the animation */
58
- startOn?: 'load' | 'mouseOver' | 'click' | 'scrollIntoView' | 'programmatic';
105
+ startOn?: StartOnExtra;
59
106
  /** Action to take when the trigger condition is no longer met (e.g., mouse leaves) */
60
107
  outAction?: 'continue' | 'pause' | 'reset' | 'reverse';
61
108
  /** Percentage of element visibility required to trigger (0-1). Only applies to scrollIntoView. */
@@ -67,7 +114,7 @@ interface PxTrigger {
67
114
  */
68
115
  interface PxAnimatorConfig {
69
116
  /** JavaScript animation implementation strategy */
70
- mode?: "auto" | "webapi" | "frames";
117
+ mode?: JsMode;
71
118
  /** Total animation duration in milliseconds */
72
119
  duration?: number;
73
120
  /** Delay before animation starts in milliseconds */
@@ -393,4 +440,4 @@ declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
393
440
  */
394
441
  declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean): PxAnimatorAPI | null;
395
442
 
396
- export { COLOUR_ATTR_NAMES, type FillMode, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimationDefinition, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, type PxBezierPath, type PxBinding, type PxDefs, type PxElementAnimation, type PxKeyframe, type PxNode, type PxPlatformAdapter, type PxPropertyAnimation, type PxSvgNode, type PxTrigger, type PxValidationResult, STYLE_ATTR_NAMES, TRANSFORM_FN_NAMES, calcAnimationValues, camelCaseToKebabWordIfNeeded, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, loadTagAnimators, getNormalisedBindings as normalizeDocument, renderNode, setupAnimationTriggers, toRGBA };
443
+ export { COLOUR_ATTR_NAMES, type FillMode, type JsMode, type OutAction, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, type PlaybackDirection, type PxAnimatedSvgDocument, type PxAnimationDefinition, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, type PxBezierPath, type PxBinding, type PxDefs, type PxElementAnimation, type PxKeyframe, type PxNode, type PxPlatformAdapter, type PxPropertyAnimation, type PxSvgNode, type PxTrigger, type PxValidationResult, STYLE_ATTR_NAMES, type StartOn, TRANSFORM_FN_NAMES, calcAnimationValues, camelCaseToKebabWordIfNeeded, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, loadTagAnimators, getNormalisedBindings as normalizeDocument, renderNode, setupAnimationTriggers, toRGBA };