@pixodesk/svg-animator-core 1.0.26 → 1.0.27

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.
package/dist/index.d.cts CHANGED
@@ -1274,6 +1274,75 @@ declare const PxDefsSchema: PxSchema<{} & {
1274
1274
  };
1275
1275
  /** Reusable definitions library for easings, animations, and styles. */
1276
1276
  type PxDefs = PxInfer<typeof PxDefsSchema>;
1277
+ /** The subject's journey phases across the scrollport (see scroll-timeline.design.md §4
1278
+ * for the exact `u`-space intervals each phase maps to). */
1279
+ type PxScrollPhase = 'cover' | 'contain' | 'entry' | 'exit' | 'entry-crossing' | 'exit-crossing';
1280
+ declare const PxScrollRangePointSchema: PxSchema<{} & {
1281
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1282
+ fraction?: number | undefined;
1283
+ }, false> & {
1284
+ readonly _shape: {
1285
+ phase: PxSchema<"cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined, true>;
1286
+ fraction: PxSchema<number | undefined, true>;
1287
+ };
1288
+ };
1289
+ type PxScrollRangePoint = PxInfer<typeof PxScrollRangePointSchema>;
1290
+ /** The `range` sub-object — named so consumers can derive its keys. */
1291
+ declare const PxScrollRangeSchema: PxSchema<{} & {
1292
+ start?: ({} & {
1293
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1294
+ fraction?: number | undefined;
1295
+ }) | undefined;
1296
+ end?: ({} & {
1297
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1298
+ fraction?: number | undefined;
1299
+ }) | undefined;
1300
+ }, false> & {
1301
+ readonly _shape: {
1302
+ start: PxSchema<({} & {
1303
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1304
+ fraction?: number | undefined;
1305
+ }) | undefined, true>;
1306
+ end: PxSchema<({} & {
1307
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1308
+ fraction?: number | undefined;
1309
+ }) | undefined, true>;
1310
+ };
1311
+ };
1312
+ declare const PxScrollSchema: PxSchema<{} & {
1313
+ driver?: "custom" | "native" | undefined;
1314
+ kind?: "view" | "scroll" | undefined;
1315
+ axis?: "x" | "y" | "block" | "inline" | undefined;
1316
+ source?: "nearest" | "root" | undefined;
1317
+ range?: ({} & {
1318
+ start?: ({} & {
1319
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1320
+ fraction?: number | undefined;
1321
+ }) | undefined;
1322
+ end?: ({} & {
1323
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1324
+ fraction?: number | undefined;
1325
+ }) | undefined;
1326
+ }) | undefined;
1327
+ }, false> & {
1328
+ readonly _shape: {
1329
+ driver: PxSchema<"custom" | "native" | undefined, true>;
1330
+ kind: PxSchema<"view" | "scroll" | undefined, true>;
1331
+ axis: PxSchema<"x" | "y" | "block" | "inline" | undefined, true>;
1332
+ source: PxSchema<"nearest" | "root" | undefined, true>;
1333
+ range: PxSchema<({} & {
1334
+ start?: ({} & {
1335
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1336
+ fraction?: number | undefined;
1337
+ }) | undefined;
1338
+ end?: ({} & {
1339
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1340
+ fraction?: number | undefined;
1341
+ }) | undefined;
1342
+ }) | undefined, true>;
1343
+ };
1344
+ };
1345
+ type PxScroll = PxInfer<typeof PxScrollSchema>;
1277
1346
  declare const PxAnimatorConfigSchema: PxSchema<{} & {
1278
1347
  mode?: "auto" | "waapi" | "frames" | undefined;
1279
1348
  duration?: number | undefined;
@@ -1557,6 +1626,22 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
1557
1626
  autoOrient?: boolean | undefined;
1558
1627
  }>)[]> | undefined;
1559
1628
  timelineSource?: string | undefined;
1629
+ scroll?: ({} & {
1630
+ driver?: "custom" | "native" | undefined;
1631
+ kind?: "view" | "scroll" | undefined;
1632
+ axis?: "x" | "y" | "block" | "inline" | undefined;
1633
+ source?: "nearest" | "root" | undefined;
1634
+ range?: ({} & {
1635
+ start?: ({} & {
1636
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1637
+ fraction?: number | undefined;
1638
+ }) | undefined;
1639
+ end?: ({} & {
1640
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1641
+ fraction?: number | undefined;
1642
+ }) | undefined;
1643
+ }) | undefined;
1644
+ }) | undefined;
1560
1645
  debugInstName?: string | undefined;
1561
1646
  }, false> & {
1562
1647
  readonly _shape: {
@@ -1842,6 +1927,22 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
1842
1927
  autoOrient?: boolean | undefined;
1843
1928
  }>)[]> | undefined, true>;
1844
1929
  timelineSource: PxSchema<string | undefined, true>;
1930
+ scroll: PxSchema<({} & {
1931
+ driver?: "custom" | "native" | undefined;
1932
+ kind?: "view" | "scroll" | undefined;
1933
+ axis?: "x" | "y" | "block" | "inline" | undefined;
1934
+ source?: "nearest" | "root" | undefined;
1935
+ range?: ({} & {
1936
+ start?: ({} & {
1937
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1938
+ fraction?: number | undefined;
1939
+ }) | undefined;
1940
+ end?: ({} & {
1941
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1942
+ fraction?: number | undefined;
1943
+ }) | undefined;
1944
+ }) | undefined;
1945
+ }) | undefined, true>;
1845
1946
  debugInstName: PxSchema<string | undefined, true>;
1846
1947
  };
1847
1948
  };
@@ -17654,6 +17755,22 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
17654
17755
  autoOrient?: boolean | undefined;
17655
17756
  }>)[]> | undefined;
17656
17757
  timelineSource?: string | undefined;
17758
+ scroll?: ({} & {
17759
+ driver?: "custom" | "native" | undefined;
17760
+ kind?: "view" | "scroll" | undefined;
17761
+ axis?: "x" | "y" | "block" | "inline" | undefined;
17762
+ source?: "nearest" | "root" | undefined;
17763
+ range?: ({} & {
17764
+ start?: ({} & {
17765
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
17766
+ fraction?: number | undefined;
17767
+ }) | undefined;
17768
+ end?: ({} & {
17769
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
17770
+ fraction?: number | undefined;
17771
+ }) | undefined;
17772
+ }) | undefined;
17773
+ }) | undefined;
17657
17774
  debugInstName?: string | undefined;
17658
17775
  }) | undefined;
17659
17776
  }, false> & {
@@ -17944,6 +18061,22 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
17944
18061
  autoOrient?: boolean | undefined;
17945
18062
  }>)[]> | undefined;
17946
18063
  timelineSource?: string | undefined;
18064
+ scroll?: ({} & {
18065
+ driver?: "custom" | "native" | undefined;
18066
+ kind?: "view" | "scroll" | undefined;
18067
+ axis?: "x" | "y" | "block" | "inline" | undefined;
18068
+ source?: "nearest" | "root" | undefined;
18069
+ range?: ({} & {
18070
+ start?: ({} & {
18071
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18072
+ fraction?: number | undefined;
18073
+ }) | undefined;
18074
+ end?: ({} & {
18075
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18076
+ fraction?: number | undefined;
18077
+ }) | undefined;
18078
+ }) | undefined;
18079
+ }) | undefined;
17947
18080
  debugInstName?: string | undefined;
17948
18081
  }) | undefined, true>;
17949
18082
  };
@@ -18253,6 +18386,22 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
18253
18386
  autoOrient?: boolean | undefined;
18254
18387
  }>)[]> | undefined;
18255
18388
  timelineSource?: string | undefined;
18389
+ scroll?: ({} & {
18390
+ driver?: "custom" | "native" | undefined;
18391
+ kind?: "view" | "scroll" | undefined;
18392
+ axis?: "x" | "y" | "block" | "inline" | undefined;
18393
+ source?: "nearest" | "root" | undefined;
18394
+ range?: ({} & {
18395
+ start?: ({} & {
18396
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18397
+ fraction?: number | undefined;
18398
+ }) | undefined;
18399
+ end?: ({} & {
18400
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18401
+ fraction?: number | undefined;
18402
+ }) | undefined;
18403
+ }) | undefined;
18404
+ }) | undefined;
18256
18405
  debugInstName?: string | undefined;
18257
18406
  }) | undefined;
18258
18407
  id?: string | undefined;
@@ -21222,6 +21371,22 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
21222
21371
  autoOrient?: boolean | undefined;
21223
21372
  }>)[]> | undefined;
21224
21373
  timelineSource?: string | undefined;
21374
+ scroll?: ({} & {
21375
+ driver?: "custom" | "native" | undefined;
21376
+ kind?: "view" | "scroll" | undefined;
21377
+ axis?: "x" | "y" | "block" | "inline" | undefined;
21378
+ source?: "nearest" | "root" | undefined;
21379
+ range?: ({} & {
21380
+ start?: ({} & {
21381
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
21382
+ fraction?: number | undefined;
21383
+ }) | undefined;
21384
+ end?: ({} & {
21385
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
21386
+ fraction?: number | undefined;
21387
+ }) | undefined;
21388
+ }) | undefined;
21389
+ }) | undefined;
21225
21390
  debugInstName?: string | undefined;
21226
21391
  }) | undefined, true>;
21227
21392
  id: PxSchema<string | undefined, true>;
@@ -23979,6 +24144,53 @@ interface PxValidationResult {
23979
24144
  */
23980
24145
  declare function isPxElementFileFormatDeep(fileJson: any): PxValidationResult;
23981
24146
 
24147
+ /** Is this document scroll-driven? (`animator.timelineSource === 'scroll'`) */
24148
+ declare function isScrollTimeline(config: PxAnimatorConfig | undefined): boolean;
24149
+ /**
24150
+ * The seek-space length (ms) a scroll progress of 1 maps to: duration × finite
24151
+ * iterations. `'infinite'` is meaningless on a finite progress timeline (see design doc
24152
+ * D4) — treated as 1 with the read-side warning left to the consumer.
24153
+ */
24154
+ declare function scrollTotalDurationMs(config: PxAnimatorConfig | undefined): number;
24155
+ /**
24156
+ * A named phase's interval in `u`-space.
24157
+ *
24158
+ * `u` is the subject's "journey distance": with `sTop` = subject's leading edge in
24159
+ * scrollport coordinates, `u = vpSize − sTop` — 0 exactly when the subject is about to
24160
+ * enter (leading edge at the scrollport's trailing edge), growing as the user scrolls.
24161
+ * The `min`/`max` pairs make every formula valid BOTH for a subject smaller than the
24162
+ * scrollport and one larger than it (where "fully visible" flips to "covers the
24163
+ * scrollport") — the same case split CSS specifies for its named timeline ranges.
24164
+ */
24165
+ declare function scrollPhaseInterval(phase: PxScrollPhase, subjectSize: number, scrollportSize: number): [number, number];
24166
+ /**
24167
+ * `kind: 'view'` progress ∈ [0, 1]: where the subject's journey sits within the
24168
+ * configured range.
24169
+ *
24170
+ * @param subjectStart subject's leading edge in scrollport coordinates
24171
+ * (`subjectRect.top − scrollportRect.top` on the resolved axis)
24172
+ * @param subjectSize subject size on the axis
24173
+ * @param scrollportSize scrollport size on the axis
24174
+ *
24175
+ * A degenerate/inverted range (uStart ≥ uEnd — e.g. zero-size subject with an `entry`
24176
+ * range) reports 1 once the point is passed, 0 before — never NaN.
24177
+ */
24178
+ declare function scrollViewProgress(subjectStart: number, subjectSize: number, scrollportSize: number, range: PxScroll['range'] | undefined): number;
24179
+ /**
24180
+ * `kind: 'scroll'` progress ∈ [0, 1]: the scroller's offset ratio mapped through the
24181
+ * range (phases don't exist here — `fraction` is of the total scroll range).
24182
+ *
24183
+ * `maxOffset === 0` (nothing to scroll) reports 1, matching the CSS spec's rule that a
24184
+ * zero-length timeline is at 100%.
24185
+ */
24186
+ declare function scrollOffsetProgress(offset: number, maxOffset: number, range: PxScroll['range'] | undefined): number;
24187
+ /**
24188
+ * Resolve a logical axis to a physical one. `block`/`inline` are writing-mode relative:
24189
+ * in horizontal writing (`horizontal-tb`, the default) block flows vertically; in
24190
+ * vertical writing modes it flows horizontally.
24191
+ */
24192
+ declare function scrollResolveAxis(axis: PxScroll['axis'] | undefined, writingMode: string | undefined): 'x' | 'y';
24193
+
23982
24194
  /**
23983
24195
  * Converts a PxBezierPath to an SVG path string.
23984
24196
  * Control points (i, o) are treated as ABSOLUTE coordinates.
@@ -24486,4 +24698,4 @@ interface EffectDiff {
24486
24698
  */
24487
24699
  declare function diffInEffect(a: VmNode, b: VmNode): Array<EffectDiff>;
24488
24700
 
24489
- export { type ApplyResult, COLOUR_ATTR_NAMES, CSS_ONLY_STYLE_PROPS, DEFAULT_DURATION_MS, DISALLOWED_SVG_TAGS_LOWER, type ExtendPathOpts, type ExtendedPath, type FillMode, type GlyphCharBox, type GlyphCharBoxAlongPath, type GlyphMaterialiseOpts, INTERNAL_ATTRS, type JsMode, type KeysMatch, LOOP_JUMP_SHIFT_MS, type MaterialiseAllOptions, type MotionPathMaterialisationOptions, type MotionPathSample, type OutAction, PCT_BASED_ATTR_NAMES, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, type PathPoint, type PathSampler, type PlaybackDirection, type PxAnimatable, type PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, type PxAnimationDefinition, PxAnimationDefinitionSchema, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, type PxAttrValue, PxAttrValueSchema, type PxBasicAnimatorAPI, type PxBezierPath, PxBezierPathSchema, type PxBinding, PxBindingSchema, type PxCloneEffect, PxCloneEffectSchema, type PxCreateElement, type PxDefs, PxDefsSchema, PxEasingOrRefSchema, type PxEffects, PxEffectsSchema, type PxElementAnimation, PxElementAnimationSchema, type PxFillGradientEffect, PxFillGradientEffectSchema, type PxGlyph, type PxGlyphFont, PxGradientSpreadMethod, type PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, type PxInfer, type PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, type PxLoop, PxLoopExtend, PxLoopSchema, type PxMaskedByEffect, PxMaskedByEffectSchema, type PxNode, PxNodeBase, PxNodeSchema, type PxPlatformAdapter, type PxPropertyAnimation, PxPropertyAnimationSchema, type PxRepeaterEffect, PxRepeaterEffectSchema, type PxRetimeEffect, PxRetimeEffectSchema, type PxSchema, type PxSchemaDesc, type PxStrokeGradientEffect, PxStrokeGradientEffectSchema, type PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, type PxTextPathEffect, PxTextPathEffectSchema, type PxTransformByEffect, PxTransformByEffectSchema, type PxTransformPartKey, type PxTransformParts, PxTransformPartsSchema, type PxTransformValue, PxTransformValueSchema, type PxTrigger, PxTriggerSchema, type PxTrimPathEffect, PxTrimPathEffectSchema, PxTrimSubPaths, type PxValidationContext, type PxValidationResult, type RemoveIndex, STYLE_ATTR_NAMES, type StartOn, TEXT_ATTR, TEXT_CONTENT_ATTR, TRANSFORM_FN_NAMES, type Vec2, applyPlayerEffects, bezierToSvgPath, calcAnimationValues, camelCaseToKebabWordIfNeeded, clamp, collectSampleTimes, composeTransformParts, createBasicFrameLoopAnimator, createPathSampler, cubicBezier, deepClone, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, generateUniqueId, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalisedBindings, getNormalizedProps, interpolateBeziers, interpolateValue, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, kebabToCamelCaseWord, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, propAnimIsMotionPath, px, resolveStyle, reverseEasing, sanitiseAttributeValue, schemaKeys, shiftAnimatable, splitEasing, subdivideCubicBezier, toRGBA, validateNodeEffects, visualModelAt };
24701
+ export { type ApplyResult, COLOUR_ATTR_NAMES, CSS_ONLY_STYLE_PROPS, DEFAULT_DURATION_MS, DISALLOWED_SVG_TAGS_LOWER, type ExtendPathOpts, type ExtendedPath, type FillMode, type GlyphCharBox, type GlyphCharBoxAlongPath, type GlyphMaterialiseOpts, INTERNAL_ATTRS, type JsMode, type KeysMatch, LOOP_JUMP_SHIFT_MS, type MaterialiseAllOptions, type MotionPathMaterialisationOptions, type MotionPathSample, type OutAction, PCT_BASED_ATTR_NAMES, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, type PathPoint, type PathSampler, type PlaybackDirection, type PxAnimatable, type PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, type PxAnimationDefinition, PxAnimationDefinitionSchema, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, type PxAttrValue, PxAttrValueSchema, type PxBasicAnimatorAPI, type PxBezierPath, PxBezierPathSchema, type PxBinding, PxBindingSchema, type PxCloneEffect, PxCloneEffectSchema, type PxCreateElement, type PxDefs, PxDefsSchema, PxEasingOrRefSchema, type PxEffects, PxEffectsSchema, type PxElementAnimation, PxElementAnimationSchema, type PxFillGradientEffect, PxFillGradientEffectSchema, type PxGlyph, type PxGlyphFont, PxGradientSpreadMethod, type PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, type PxInfer, type PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, type PxLoop, PxLoopExtend, PxLoopSchema, type PxMaskedByEffect, PxMaskedByEffectSchema, type PxNode, PxNodeBase, PxNodeSchema, type PxPlatformAdapter, type PxPropertyAnimation, PxPropertyAnimationSchema, type PxRepeaterEffect, PxRepeaterEffectSchema, type PxRetimeEffect, PxRetimeEffectSchema, type PxSchema, type PxSchemaDesc, type PxScroll, type PxScrollPhase, type PxScrollRangePoint, PxScrollRangePointSchema, PxScrollRangeSchema, PxScrollSchema, type PxStrokeGradientEffect, PxStrokeGradientEffectSchema, type PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, type PxTextPathEffect, PxTextPathEffectSchema, type PxTransformByEffect, PxTransformByEffectSchema, type PxTransformPartKey, type PxTransformParts, PxTransformPartsSchema, type PxTransformValue, PxTransformValueSchema, type PxTrigger, PxTriggerSchema, type PxTrimPathEffect, PxTrimPathEffectSchema, PxTrimSubPaths, type PxValidationContext, type PxValidationResult, type RemoveIndex, STYLE_ATTR_NAMES, type StartOn, TEXT_ATTR, TEXT_CONTENT_ATTR, TRANSFORM_FN_NAMES, type Vec2, applyPlayerEffects, bezierToSvgPath, calcAnimationValues, camelCaseToKebabWordIfNeeded, clamp, collectSampleTimes, composeTransformParts, createBasicFrameLoopAnimator, createPathSampler, cubicBezier, deepClone, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, generateUniqueId, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalisedBindings, getNormalizedProps, interpolateBeziers, interpolateValue, isPxElementFileFormat, isPxElementFileFormatDeep, isScrollTimeline, jsonElementFactory, kebabToCamelCaseWord, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, propAnimIsMotionPath, px, resolveStyle, reverseEasing, sanitiseAttributeValue, schemaKeys, scrollOffsetProgress, scrollPhaseInterval, scrollResolveAxis, scrollTotalDurationMs, scrollViewProgress, shiftAnimatable, splitEasing, subdivideCubicBezier, toRGBA, validateNodeEffects, visualModelAt };
package/dist/index.d.ts CHANGED
@@ -1274,6 +1274,75 @@ declare const PxDefsSchema: PxSchema<{} & {
1274
1274
  };
1275
1275
  /** Reusable definitions library for easings, animations, and styles. */
1276
1276
  type PxDefs = PxInfer<typeof PxDefsSchema>;
1277
+ /** The subject's journey phases across the scrollport (see scroll-timeline.design.md §4
1278
+ * for the exact `u`-space intervals each phase maps to). */
1279
+ type PxScrollPhase = 'cover' | 'contain' | 'entry' | 'exit' | 'entry-crossing' | 'exit-crossing';
1280
+ declare const PxScrollRangePointSchema: PxSchema<{} & {
1281
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1282
+ fraction?: number | undefined;
1283
+ }, false> & {
1284
+ readonly _shape: {
1285
+ phase: PxSchema<"cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined, true>;
1286
+ fraction: PxSchema<number | undefined, true>;
1287
+ };
1288
+ };
1289
+ type PxScrollRangePoint = PxInfer<typeof PxScrollRangePointSchema>;
1290
+ /** The `range` sub-object — named so consumers can derive its keys. */
1291
+ declare const PxScrollRangeSchema: PxSchema<{} & {
1292
+ start?: ({} & {
1293
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1294
+ fraction?: number | undefined;
1295
+ }) | undefined;
1296
+ end?: ({} & {
1297
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1298
+ fraction?: number | undefined;
1299
+ }) | undefined;
1300
+ }, false> & {
1301
+ readonly _shape: {
1302
+ start: PxSchema<({} & {
1303
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1304
+ fraction?: number | undefined;
1305
+ }) | undefined, true>;
1306
+ end: PxSchema<({} & {
1307
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1308
+ fraction?: number | undefined;
1309
+ }) | undefined, true>;
1310
+ };
1311
+ };
1312
+ declare const PxScrollSchema: PxSchema<{} & {
1313
+ driver?: "custom" | "native" | undefined;
1314
+ kind?: "view" | "scroll" | undefined;
1315
+ axis?: "x" | "y" | "block" | "inline" | undefined;
1316
+ source?: "nearest" | "root" | undefined;
1317
+ range?: ({} & {
1318
+ start?: ({} & {
1319
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1320
+ fraction?: number | undefined;
1321
+ }) | undefined;
1322
+ end?: ({} & {
1323
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1324
+ fraction?: number | undefined;
1325
+ }) | undefined;
1326
+ }) | undefined;
1327
+ }, false> & {
1328
+ readonly _shape: {
1329
+ driver: PxSchema<"custom" | "native" | undefined, true>;
1330
+ kind: PxSchema<"view" | "scroll" | undefined, true>;
1331
+ axis: PxSchema<"x" | "y" | "block" | "inline" | undefined, true>;
1332
+ source: PxSchema<"nearest" | "root" | undefined, true>;
1333
+ range: PxSchema<({} & {
1334
+ start?: ({} & {
1335
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1336
+ fraction?: number | undefined;
1337
+ }) | undefined;
1338
+ end?: ({} & {
1339
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1340
+ fraction?: number | undefined;
1341
+ }) | undefined;
1342
+ }) | undefined, true>;
1343
+ };
1344
+ };
1345
+ type PxScroll = PxInfer<typeof PxScrollSchema>;
1277
1346
  declare const PxAnimatorConfigSchema: PxSchema<{} & {
1278
1347
  mode?: "auto" | "waapi" | "frames" | undefined;
1279
1348
  duration?: number | undefined;
@@ -1557,6 +1626,22 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
1557
1626
  autoOrient?: boolean | undefined;
1558
1627
  }>)[]> | undefined;
1559
1628
  timelineSource?: string | undefined;
1629
+ scroll?: ({} & {
1630
+ driver?: "custom" | "native" | undefined;
1631
+ kind?: "view" | "scroll" | undefined;
1632
+ axis?: "x" | "y" | "block" | "inline" | undefined;
1633
+ source?: "nearest" | "root" | undefined;
1634
+ range?: ({} & {
1635
+ start?: ({} & {
1636
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1637
+ fraction?: number | undefined;
1638
+ }) | undefined;
1639
+ end?: ({} & {
1640
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1641
+ fraction?: number | undefined;
1642
+ }) | undefined;
1643
+ }) | undefined;
1644
+ }) | undefined;
1560
1645
  debugInstName?: string | undefined;
1561
1646
  }, false> & {
1562
1647
  readonly _shape: {
@@ -1842,6 +1927,22 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
1842
1927
  autoOrient?: boolean | undefined;
1843
1928
  }>)[]> | undefined, true>;
1844
1929
  timelineSource: PxSchema<string | undefined, true>;
1930
+ scroll: PxSchema<({} & {
1931
+ driver?: "custom" | "native" | undefined;
1932
+ kind?: "view" | "scroll" | undefined;
1933
+ axis?: "x" | "y" | "block" | "inline" | undefined;
1934
+ source?: "nearest" | "root" | undefined;
1935
+ range?: ({} & {
1936
+ start?: ({} & {
1937
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1938
+ fraction?: number | undefined;
1939
+ }) | undefined;
1940
+ end?: ({} & {
1941
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
1942
+ fraction?: number | undefined;
1943
+ }) | undefined;
1944
+ }) | undefined;
1945
+ }) | undefined, true>;
1845
1946
  debugInstName: PxSchema<string | undefined, true>;
1846
1947
  };
1847
1948
  };
@@ -17654,6 +17755,22 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
17654
17755
  autoOrient?: boolean | undefined;
17655
17756
  }>)[]> | undefined;
17656
17757
  timelineSource?: string | undefined;
17758
+ scroll?: ({} & {
17759
+ driver?: "custom" | "native" | undefined;
17760
+ kind?: "view" | "scroll" | undefined;
17761
+ axis?: "x" | "y" | "block" | "inline" | undefined;
17762
+ source?: "nearest" | "root" | undefined;
17763
+ range?: ({} & {
17764
+ start?: ({} & {
17765
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
17766
+ fraction?: number | undefined;
17767
+ }) | undefined;
17768
+ end?: ({} & {
17769
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
17770
+ fraction?: number | undefined;
17771
+ }) | undefined;
17772
+ }) | undefined;
17773
+ }) | undefined;
17657
17774
  debugInstName?: string | undefined;
17658
17775
  }) | undefined;
17659
17776
  }, false> & {
@@ -17944,6 +18061,22 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
17944
18061
  autoOrient?: boolean | undefined;
17945
18062
  }>)[]> | undefined;
17946
18063
  timelineSource?: string | undefined;
18064
+ scroll?: ({} & {
18065
+ driver?: "custom" | "native" | undefined;
18066
+ kind?: "view" | "scroll" | undefined;
18067
+ axis?: "x" | "y" | "block" | "inline" | undefined;
18068
+ source?: "nearest" | "root" | undefined;
18069
+ range?: ({} & {
18070
+ start?: ({} & {
18071
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18072
+ fraction?: number | undefined;
18073
+ }) | undefined;
18074
+ end?: ({} & {
18075
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18076
+ fraction?: number | undefined;
18077
+ }) | undefined;
18078
+ }) | undefined;
18079
+ }) | undefined;
17947
18080
  debugInstName?: string | undefined;
17948
18081
  }) | undefined, true>;
17949
18082
  };
@@ -18253,6 +18386,22 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
18253
18386
  autoOrient?: boolean | undefined;
18254
18387
  }>)[]> | undefined;
18255
18388
  timelineSource?: string | undefined;
18389
+ scroll?: ({} & {
18390
+ driver?: "custom" | "native" | undefined;
18391
+ kind?: "view" | "scroll" | undefined;
18392
+ axis?: "x" | "y" | "block" | "inline" | undefined;
18393
+ source?: "nearest" | "root" | undefined;
18394
+ range?: ({} & {
18395
+ start?: ({} & {
18396
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18397
+ fraction?: number | undefined;
18398
+ }) | undefined;
18399
+ end?: ({} & {
18400
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
18401
+ fraction?: number | undefined;
18402
+ }) | undefined;
18403
+ }) | undefined;
18404
+ }) | undefined;
18256
18405
  debugInstName?: string | undefined;
18257
18406
  }) | undefined;
18258
18407
  id?: string | undefined;
@@ -21222,6 +21371,22 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
21222
21371
  autoOrient?: boolean | undefined;
21223
21372
  }>)[]> | undefined;
21224
21373
  timelineSource?: string | undefined;
21374
+ scroll?: ({} & {
21375
+ driver?: "custom" | "native" | undefined;
21376
+ kind?: "view" | "scroll" | undefined;
21377
+ axis?: "x" | "y" | "block" | "inline" | undefined;
21378
+ source?: "nearest" | "root" | undefined;
21379
+ range?: ({} & {
21380
+ start?: ({} & {
21381
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
21382
+ fraction?: number | undefined;
21383
+ }) | undefined;
21384
+ end?: ({} & {
21385
+ phase?: "cover" | "contain" | "entry" | "exit" | "entry-crossing" | "exit-crossing" | undefined;
21386
+ fraction?: number | undefined;
21387
+ }) | undefined;
21388
+ }) | undefined;
21389
+ }) | undefined;
21225
21390
  debugInstName?: string | undefined;
21226
21391
  }) | undefined, true>;
21227
21392
  id: PxSchema<string | undefined, true>;
@@ -23979,6 +24144,53 @@ interface PxValidationResult {
23979
24144
  */
23980
24145
  declare function isPxElementFileFormatDeep(fileJson: any): PxValidationResult;
23981
24146
 
24147
+ /** Is this document scroll-driven? (`animator.timelineSource === 'scroll'`) */
24148
+ declare function isScrollTimeline(config: PxAnimatorConfig | undefined): boolean;
24149
+ /**
24150
+ * The seek-space length (ms) a scroll progress of 1 maps to: duration × finite
24151
+ * iterations. `'infinite'` is meaningless on a finite progress timeline (see design doc
24152
+ * D4) — treated as 1 with the read-side warning left to the consumer.
24153
+ */
24154
+ declare function scrollTotalDurationMs(config: PxAnimatorConfig | undefined): number;
24155
+ /**
24156
+ * A named phase's interval in `u`-space.
24157
+ *
24158
+ * `u` is the subject's "journey distance": with `sTop` = subject's leading edge in
24159
+ * scrollport coordinates, `u = vpSize − sTop` — 0 exactly when the subject is about to
24160
+ * enter (leading edge at the scrollport's trailing edge), growing as the user scrolls.
24161
+ * The `min`/`max` pairs make every formula valid BOTH for a subject smaller than the
24162
+ * scrollport and one larger than it (where "fully visible" flips to "covers the
24163
+ * scrollport") — the same case split CSS specifies for its named timeline ranges.
24164
+ */
24165
+ declare function scrollPhaseInterval(phase: PxScrollPhase, subjectSize: number, scrollportSize: number): [number, number];
24166
+ /**
24167
+ * `kind: 'view'` progress ∈ [0, 1]: where the subject's journey sits within the
24168
+ * configured range.
24169
+ *
24170
+ * @param subjectStart subject's leading edge in scrollport coordinates
24171
+ * (`subjectRect.top − scrollportRect.top` on the resolved axis)
24172
+ * @param subjectSize subject size on the axis
24173
+ * @param scrollportSize scrollport size on the axis
24174
+ *
24175
+ * A degenerate/inverted range (uStart ≥ uEnd — e.g. zero-size subject with an `entry`
24176
+ * range) reports 1 once the point is passed, 0 before — never NaN.
24177
+ */
24178
+ declare function scrollViewProgress(subjectStart: number, subjectSize: number, scrollportSize: number, range: PxScroll['range'] | undefined): number;
24179
+ /**
24180
+ * `kind: 'scroll'` progress ∈ [0, 1]: the scroller's offset ratio mapped through the
24181
+ * range (phases don't exist here — `fraction` is of the total scroll range).
24182
+ *
24183
+ * `maxOffset === 0` (nothing to scroll) reports 1, matching the CSS spec's rule that a
24184
+ * zero-length timeline is at 100%.
24185
+ */
24186
+ declare function scrollOffsetProgress(offset: number, maxOffset: number, range: PxScroll['range'] | undefined): number;
24187
+ /**
24188
+ * Resolve a logical axis to a physical one. `block`/`inline` are writing-mode relative:
24189
+ * in horizontal writing (`horizontal-tb`, the default) block flows vertically; in
24190
+ * vertical writing modes it flows horizontally.
24191
+ */
24192
+ declare function scrollResolveAxis(axis: PxScroll['axis'] | undefined, writingMode: string | undefined): 'x' | 'y';
24193
+
23982
24194
  /**
23983
24195
  * Converts a PxBezierPath to an SVG path string.
23984
24196
  * Control points (i, o) are treated as ABSOLUTE coordinates.
@@ -24486,4 +24698,4 @@ interface EffectDiff {
24486
24698
  */
24487
24699
  declare function diffInEffect(a: VmNode, b: VmNode): Array<EffectDiff>;
24488
24700
 
24489
- export { type ApplyResult, COLOUR_ATTR_NAMES, CSS_ONLY_STYLE_PROPS, DEFAULT_DURATION_MS, DISALLOWED_SVG_TAGS_LOWER, type ExtendPathOpts, type ExtendedPath, type FillMode, type GlyphCharBox, type GlyphCharBoxAlongPath, type GlyphMaterialiseOpts, INTERNAL_ATTRS, type JsMode, type KeysMatch, LOOP_JUMP_SHIFT_MS, type MaterialiseAllOptions, type MotionPathMaterialisationOptions, type MotionPathSample, type OutAction, PCT_BASED_ATTR_NAMES, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, type PathPoint, type PathSampler, type PlaybackDirection, type PxAnimatable, type PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, type PxAnimationDefinition, PxAnimationDefinitionSchema, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, type PxAttrValue, PxAttrValueSchema, type PxBasicAnimatorAPI, type PxBezierPath, PxBezierPathSchema, type PxBinding, PxBindingSchema, type PxCloneEffect, PxCloneEffectSchema, type PxCreateElement, type PxDefs, PxDefsSchema, PxEasingOrRefSchema, type PxEffects, PxEffectsSchema, type PxElementAnimation, PxElementAnimationSchema, type PxFillGradientEffect, PxFillGradientEffectSchema, type PxGlyph, type PxGlyphFont, PxGradientSpreadMethod, type PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, type PxInfer, type PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, type PxLoop, PxLoopExtend, PxLoopSchema, type PxMaskedByEffect, PxMaskedByEffectSchema, type PxNode, PxNodeBase, PxNodeSchema, type PxPlatformAdapter, type PxPropertyAnimation, PxPropertyAnimationSchema, type PxRepeaterEffect, PxRepeaterEffectSchema, type PxRetimeEffect, PxRetimeEffectSchema, type PxSchema, type PxSchemaDesc, type PxStrokeGradientEffect, PxStrokeGradientEffectSchema, type PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, type PxTextPathEffect, PxTextPathEffectSchema, type PxTransformByEffect, PxTransformByEffectSchema, type PxTransformPartKey, type PxTransformParts, PxTransformPartsSchema, type PxTransformValue, PxTransformValueSchema, type PxTrigger, PxTriggerSchema, type PxTrimPathEffect, PxTrimPathEffectSchema, PxTrimSubPaths, type PxValidationContext, type PxValidationResult, type RemoveIndex, STYLE_ATTR_NAMES, type StartOn, TEXT_ATTR, TEXT_CONTENT_ATTR, TRANSFORM_FN_NAMES, type Vec2, applyPlayerEffects, bezierToSvgPath, calcAnimationValues, camelCaseToKebabWordIfNeeded, clamp, collectSampleTimes, composeTransformParts, createBasicFrameLoopAnimator, createPathSampler, cubicBezier, deepClone, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, generateUniqueId, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalisedBindings, getNormalizedProps, interpolateBeziers, interpolateValue, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, kebabToCamelCaseWord, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, propAnimIsMotionPath, px, resolveStyle, reverseEasing, sanitiseAttributeValue, schemaKeys, shiftAnimatable, splitEasing, subdivideCubicBezier, toRGBA, validateNodeEffects, visualModelAt };
24701
+ export { type ApplyResult, COLOUR_ATTR_NAMES, CSS_ONLY_STYLE_PROPS, DEFAULT_DURATION_MS, DISALLOWED_SVG_TAGS_LOWER, type ExtendPathOpts, type ExtendedPath, type FillMode, type GlyphCharBox, type GlyphCharBoxAlongPath, type GlyphMaterialiseOpts, INTERNAL_ATTRS, type JsMode, type KeysMatch, LOOP_JUMP_SHIFT_MS, type MaterialiseAllOptions, type MotionPathMaterialisationOptions, type MotionPathSample, type OutAction, PCT_BASED_ATTR_NAMES, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, type PathPoint, type PathSampler, type PlaybackDirection, type PxAnimatable, type PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, type PxAnimationDefinition, PxAnimationDefinitionSchema, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, type PxAttrValue, PxAttrValueSchema, type PxBasicAnimatorAPI, type PxBezierPath, PxBezierPathSchema, type PxBinding, PxBindingSchema, type PxCloneEffect, PxCloneEffectSchema, type PxCreateElement, type PxDefs, PxDefsSchema, PxEasingOrRefSchema, type PxEffects, PxEffectsSchema, type PxElementAnimation, PxElementAnimationSchema, type PxFillGradientEffect, PxFillGradientEffectSchema, type PxGlyph, type PxGlyphFont, PxGradientSpreadMethod, type PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, type PxInfer, type PxKeyframe, PxKeyframeSchema, PxKeyframeValueSchema, type PxLoop, PxLoopExtend, PxLoopSchema, type PxMaskedByEffect, PxMaskedByEffectSchema, type PxNode, PxNodeBase, PxNodeSchema, type PxPlatformAdapter, type PxPropertyAnimation, PxPropertyAnimationSchema, type PxRepeaterEffect, PxRepeaterEffectSchema, type PxRetimeEffect, PxRetimeEffectSchema, type PxSchema, type PxSchemaDesc, type PxScroll, type PxScrollPhase, type PxScrollRangePoint, PxScrollRangePointSchema, PxScrollRangeSchema, PxScrollSchema, type PxStrokeGradientEffect, PxStrokeGradientEffectSchema, type PxSvgNode, PxSvgNodeExtra, PxTextEffectSchema, type PxTextPathEffect, PxTextPathEffectSchema, type PxTransformByEffect, PxTransformByEffectSchema, type PxTransformPartKey, type PxTransformParts, PxTransformPartsSchema, type PxTransformValue, PxTransformValueSchema, type PxTrigger, PxTriggerSchema, type PxTrimPathEffect, PxTrimPathEffectSchema, PxTrimSubPaths, type PxValidationContext, type PxValidationResult, type RemoveIndex, STYLE_ATTR_NAMES, type StartOn, TEXT_ATTR, TEXT_CONTENT_ATTR, TRANSFORM_FN_NAMES, type Vec2, applyPlayerEffects, bezierToSvgPath, calcAnimationValues, camelCaseToKebabWordIfNeeded, clamp, collectSampleTimes, composeTransformParts, createBasicFrameLoopAnimator, createPathSampler, cubicBezier, deepClone, describeSchema, diffInEffect, evaluateMotionPathSegment, extendedPathForBrowser, generateNewIds, generateUniqueId, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalisedBindings, getNormalizedProps, interpolateBeziers, interpolateValue, isPxElementFileFormat, isPxElementFileFormatDeep, isScrollTimeline, jsonElementFactory, kebabToCamelCaseWord, layoutGlyphTextChars, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, propAnimIsMotionPath, px, resolveStyle, reverseEasing, sanitiseAttributeValue, schemaKeys, scrollOffsetProgress, scrollPhaseInterval, scrollResolveAxis, scrollTotalDurationMs, scrollViewProgress, shiftAnimatable, splitEasing, subdivideCubicBezier, toRGBA, validateNodeEffects, visualModelAt };