@pixodesk/svg-animator-web 1.0.17 → 1.0.18

package/dist/index.d.cts

@@ -547,6 +547,38 @@ declare const PxTriggerSchema: PxSchema<{} & {
 };
 /** Defines when and how an animation should be triggered. */
 type PxTrigger = PxInfer<typeof PxTriggerSchema>;
+declare const PxGlyphSchema: PxSchema<{
+    width: number;
+    d: string;
+} & {}, false> & {
+    readonly _shape: {
+        width: PxSchema<number, false>;
+        d: PxSchema<string, false>;
+    };
+};
+type PxGlyph = PxInfer<typeof PxGlyphSchema>;
+declare const PxGlyphFontSchema: PxSchema<{
+    fFamily: string;
+    style: string;
+    ascent: number;
+    unitsPerEm: number;
+    glyphs: Record<string, {
+        width: number;
+        d: string;
+    } & {}>;
+} & {}, false> & {
+    readonly _shape: {
+        fFamily: PxSchema<string, false>;
+        style: PxSchema<string, false>;
+        ascent: PxSchema<number, false>;
+        unitsPerEm: PxSchema<number, false>;
+        glyphs: PxSchema<Record<string, {
+            width: number;
+            d: string;
+        } & {}>, false>;
+    };
+};
+type PxGlyphFont = PxInfer<typeof PxGlyphFontSchema>;
 declare const PxDefsSchema: PxSchema<{} & {
     easings?: Record<string, [number, number, number, number]> | undefined;
     animations?: Record<string, Record<string, {} & {
@@ -584,6 +616,16 @@ declare const PxDefsSchema: PxSchema<{} & {
         autoOrient?: boolean | undefined;
     }>> | undefined;
     styles?: Record<string, any> | undefined;
+    glyphs?: Record<string, {
+        fFamily: string;
+        style: string;
+        ascent: number;
+        unitsPerEm: number;
+        glyphs: Record<string, {
+            width: number;
+            d: string;
+        } & {}>;
+    } & {}> | undefined;
 }, false> & {
     readonly _shape: {
         easings: PxSchema<Record<string, [number, number, number, number]> | undefined, true>;
@@ -622,6 +664,16 @@ declare const PxDefsSchema: PxSchema<{} & {
             autoOrient?: boolean | undefined;
         }>> | undefined, true>;
         styles: PxSchema<Record<string, any> | undefined, true>;
+        glyphs: PxSchema<Record<string, {
+            fFamily: string;
+            style: string;
+            ascent: number;
+            unitsPerEm: number;
+            glyphs: Record<string, {
+                width: number;
+                d: string;
+            } & {}>;
+        } & {}> | undefined, true>;
     };
 };
 /** Reusable definitions library for easings, animations, and styles. */
@@ -676,6 +728,16 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
             autoOrient?: boolean | undefined;
         }>> | undefined;
         styles?: Record<string, any> | undefined;
+        glyphs?: Record<string, {
+            fFamily: string;
+            style: string;
+            ascent: number;
+            unitsPerEm: number;
+            glyphs: Record<string, {
+                width: number;
+                d: string;
+            } & {}>;
+        } & {}> | undefined;
     }) | undefined;
     animate?: Record<string, string | Record<string, {} & {
         keyframes?: ({} & {
@@ -797,6 +859,16 @@ declare const PxAnimatorConfigSchema: PxSchema<{} & {
                 autoOrient?: boolean | undefined;
             }>> | undefined;
             styles?: Record<string, any> | undefined;
+            glyphs?: Record<string, {
+                fFamily: string;
+                style: string;
+                ascent: number;
+                unitsPerEm: number;
+                glyphs: Record<string, {
+                    width: number;
+                    d: string;
+                } & {}>;
+            } & {}> | undefined;
         }) | undefined, true>;
         animate: PxSchema<Record<string, string | Record<string, {} & {
             keyframes?: ({} & {
@@ -1843,6 +1915,13 @@ declare const PxTextAlongPathEffectSchema: PxSchema<{
     };
 };
 type PxTextAlongPathEffect = PxInfer<typeof PxTextAlongPathEffectSchema>;
+declare const PxTextEffectSchema: PxSchema<{} & {
+    useGlyphs?: boolean | undefined;
+}, false> & {
+    readonly _shape: {
+        useGlyphs: PxSchema<boolean | undefined, true>;
+    };
+};
 declare const PxEffectsSchema: PxSchema<{} & {
     transformation?: ({} & {
         translate?: [number, number] | ({
@@ -2193,6 +2272,9 @@ declare const PxEffectsSchema: PxSchema<{} & {
             autoOrient?: boolean | undefined;
         }) | undefined;
     }) | undefined;
+    text?: ({} & {
+        useGlyphs?: boolean | undefined;
+    }) | undefined;
 }, false> & {
     readonly _shape: {
         transformation: PxSchema<({} & {
@@ -2544,6 +2626,9 @@ declare const PxEffectsSchema: PxSchema<{} & {
                 autoOrient?: boolean | undefined;
             }) | undefined;
         }) | undefined, true>;
+        text: PxSchema<({} & {
+            useGlyphs?: boolean | undefined;
+        }) | undefined, true>;
     };
 };
 type PxEffects = PxInfer<typeof PxEffectsSchema>;
@@ -2920,6 +3005,9 @@ declare const PxNodeBase: PxSchema<{
                 autoOrient?: boolean | undefined;
             }) | undefined;
         }) | undefined;
+        text?: ({} & {
+            useGlyphs?: boolean | undefined;
+        }) | undefined;
     }) | undefined;
     animate?: string | Record<string, {} & {
         keyframes?: ({} & {
@@ -3346,6 +3434,9 @@ declare const PxNodeBase: PxSchema<{
                     autoOrient?: boolean | undefined;
                 }) | undefined;
             }) | undefined;
+            text?: ({} & {
+                useGlyphs?: boolean | undefined;
+            }) | undefined;
         }) | undefined, true>;
         animate: PxSchema<string | Record<string, {} & {
             keyframes?: ({} & {
@@ -3489,6 +3580,16 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
                 autoOrient?: boolean | undefined;
             }>> | undefined;
             styles?: Record<string, any> | undefined;
+            glyphs?: Record<string, {
+                fFamily: string;
+                style: string;
+                ascent: number;
+                unitsPerEm: number;
+                glyphs: Record<string, {
+                    width: number;
+                    d: string;
+                } & {}>;
+            } & {}> | undefined;
         }) | undefined;
         animate?: Record<string, string | Record<string, {} & {
             keyframes?: ({} & {
@@ -3615,6 +3716,16 @@ declare const PxSvgNodeExtra: PxSchema<{} & {
                     autoOrient?: boolean | undefined;
                 }>> | undefined;
                 styles?: Record<string, any> | undefined;
+                glyphs?: Record<string, {
+                    fFamily: string;
+                    style: string;
+                    ascent: number;
+                    unitsPerEm: number;
+                    glyphs: Record<string, {
+                        width: number;
+                        d: string;
+                    } & {}>;
+                } & {}> | undefined;
             }) | undefined;
             animate?: Record<string, string | Record<string, {} & {
                 keyframes?: ({} & {
@@ -3760,6 +3871,16 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
                 autoOrient?: boolean | undefined;
             }>> | undefined;
             styles?: Record<string, any> | undefined;
+            glyphs?: Record<string, {
+                fFamily: string;
+                style: string;
+                ascent: number;
+                unitsPerEm: number;
+                glyphs: Record<string, {
+                    width: number;
+                    d: string;
+                } & {}>;
+            } & {}> | undefined;
         }) | undefined;
         animate?: Record<string, string | Record<string, {} & {
             keyframes?: ({} & {
@@ -4183,6 +4304,9 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
                 autoOrient?: boolean | undefined;
             }) | undefined;
         }) | undefined;
+        text?: ({} & {
+            useGlyphs?: boolean | undefined;
+        }) | undefined;
     }) | undefined;
     animate?: string | Record<string, {} & {
         keyframes?: ({} & {
@@ -4311,6 +4435,16 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
                     autoOrient?: boolean | undefined;
                 }>> | undefined;
                 styles?: Record<string, any> | undefined;
+                glyphs?: Record<string, {
+                    fFamily: string;
+                    style: string;
+                    ascent: number;
+                    unitsPerEm: number;
+                    glyphs: Record<string, {
+                        width: number;
+                        d: string;
+                    } & {}>;
+                } & {}> | undefined;
             }) | undefined;
             animate?: Record<string, string | Record<string, {} & {
                 keyframes?: ({} & {
@@ -4734,6 +4868,9 @@ declare const PxAnimatedSvgDocumentSchema: PxSchema<{
                     autoOrient?: boolean | undefined;
                 }) | undefined;
             }) | undefined;
+            text?: ({} & {
+                useGlyphs?: boolean | undefined;
+            }) | undefined;
         }) | undefined, true>;
         animate: PxSchema<string | Record<string, {} & {
             keyframes?: ({} & {
@@ -5114,18 +5251,23 @@ declare function getNormalizedProps(props: Record<string, any>): Record<string,
 declare function renderNode(node: PxNode, defs?: PxDefs): Element | null;
 
 /**
- * Creates an animator instance that uses the native Web Animations API.
+ * Element-creation factory — abstracts WHAT an "element" is so the same
+ * geometry/layout code (e.g. the glyph text materialiser) can emit plain wire
+ * nodes here, or the editor's React / px elements when called from the editor.
  *
- * This is the preferred, more performant animator. It will return null if the
- * animation configuration contains properties not supported by the browser's
- * Web Animations API implementation, unless forceEvenIfHasUnsupportedAttrs is true.
- *
- * @param callbacks Optional lifecycle callbacks.
- * @param rootElement Root element.
- * @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.
+ * The signature intentionally mirrors the editor's `createPxElement(type,
+ * props, children, fixReactKeysIfNeeded?)` so the editor's own factory drops in
+ * unchanged.
  */
-declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean): PxAnimatorAPI | null;
+type PxCreateElement<E = any> = (type: string, props: {
+    [k: string]: any;
+}, children?: Array<E> | E | null, fixReactKeysIfNeeded?: boolean) => E;
+/**
+ * Default factory → a plain wire node `{ type, ...props, children? }`.
+ * Drops `undefined` props and empty `children` so output matches the shape the
+ * effects pipeline (and `JSON.stringify`) expects.
+ */
+declare const jsonElementFactory: PxCreateElement<any>;
 
 /**
  * Applier-runtime types: `ApplyContext` (per-run mutable state) and `ApplyResult`
@@ -5145,6 +5287,63 @@ interface ApplyResult {
     errors: Array<string>;
 }
 
+/**
+ * Glyph text materialiser — turns a `<text>`/`<tspan>` subtree into `<path>`
+ * outlines from `definitions.glyphs`, so the text renders with no external font.
+ *
+ *  - HORIZONTAL ({@link materialiseGlyphTextHorizontal}) — left-to-right by
+ *    advance width; honours font-size, text-anchor, letter/word-spacing,
+ *    per-tspan x/y/dx/dy, fill/stroke, nested tspans.
+ *  - ALONG-PATH ({@link materialiseGlyphTextAlongPath}) — each glyph placed and
+ *    rotated to the referenced path's tangent. Static `startOffset` → glyphs
+ *    bake+merge; animated `startOffset` → per-glyph `<path>` with sampled
+ *    `animate.transform`. Ignores per-tspan positioning (a single run).
+ *
+ * Element creation goes through an injected {@link PxCreateElement} factory, so
+ * the SAME layout produces plain wire nodes here (the effects pipeline) or the
+ * editor's React/px elements when the editor calls it — see
+ * {@link materialiseGlyphText}.
+ *
+ * v1 scope (see svga.text.design.md): keyframe-interval easing is linear;
+ * kerning/ligatures, per-tspan opacity, text-level animated fill are out of scope.
+ */
+
+/** Inputs for a glyph materialisation, decoupled from the effects `ApplyContext`
+ *  so the editor can call the materialiser directly. */
+interface GlyphMaterialiseOpts<E = any> {
+    /** Embedded glyph fonts, keyed by `font-family`. */
+    glyphs: Record<string, PxGlyphFont>;
+    /** Element factory — defaults to plain wire nodes ({@link jsonElementFactory}). */
+    create?: PxCreateElement<E>;
+    /** Optional diagnostics sink. */
+    warnings?: Array<string>;
+}
+declare function materialiseGlyphTextHorizontal<E = any>(node: PxNode, opts: GlyphMaterialiseOpts<E>): E;
+declare function materialiseGlyphTextAlongPath<E = any>(node: PxNode, pathD: string | undefined, startOffset: PxAnimatable<number> | undefined, opts: GlyphMaterialiseOpts<E>, textLength?: number): E | null;
+/** Single entry the EDITOR calls: materialises a glyph `<text>` node into the
+ *  factory's element type, choosing along-path when `alongPath` is given. */
+declare function materialiseGlyphText<E = any>(node: PxNode, opts: GlyphMaterialiseOpts<E> & {
+    alongPath?: {
+        pathD?: string;
+        startOffset?: PxAnimatable<number>;
+        textLength?: number;
+    };
+}): E | null;
+
+/**
+ * Creates an animator instance that uses the native Web Animations API.
+ *
+ * This is the preferred, more performant animator. It will return null if the
+ * animation configuration contains properties not supported by the browser's
+ * Web Animations API implementation, unless forceEvenIfHasUnsupportedAttrs is true.
+ *
+ * @param callbacks Optional lifecycle callbacks.
+ * @param rootElement Root element.
+ * @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.
+ */
+declare function createWebApiAnimator(doc: PxAnimatedSvgDocument, callbacks?: PxAnimatorCallbacksConfig, rootElement?: Element | null, forceEvenIfHasUnsupportedAttrs?: boolean): PxAnimatorAPI | null;
+
 /**
  * Applies all player-effects in `root` and returns a materialised copy plus any
  * generated <defs> nodes, warnings and errors. `root` is not mutated.
@@ -5158,7 +5357,7 @@ interface ApplyResult {
  * Pre-pass identifies every element that is the target of a `<use>` with
  * `ref:{type:'content'}` and allocates a fresh "inner" id for it; pass 1 then
  * splits those sources into outer-translate + inner-content layers so the use
- * can target the inner layer (mirrors the editor's heavy materialisation).
+ * can target the inner layer.
  */
 declare function applyPlayerEffects(root: PxNode): ApplyResult;
 
@@ -5182,4 +5381,4 @@ interface EffectDiff {
  */
 declare function diffInEffect(a: VmNode, b: VmNode): Array<EffectDiff>;
 
-export { type ApplyResult, COLOUR_ATTR_NAMES, type FillMode, type JsMode, type KeysMatch, type MaterialiseAllOptions, type MotionPathMaterialisationOptions, type MotionPathSample, type OutAction, PX_ANIMATOR_DATA_KEY, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, type PlaybackDirection, type PxAnimatable, type PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, type PxAnimationDefinition, PxAnimationDefinitionSchema, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, type PxAnimatorOptions, type PxAttrValue, PxAttrValueSchema, type PxBezierPath, PxBezierPathSchema, type PxBinding, PxBindingSchema, type PxCloneEffect, PxCloneEffectSchema, type PxDefs, PxDefsSchema, PxEasingOrRefSchema, type PxEffects, PxEffectsSchema, type PxElementAnimation, PxElementAnimationSchema, type PxFillGradientEffect, PxFillGradientEffectSchema, PxGradientSpreadMethod, type PxGradientStop, PxGradientStopSchema, PxGradientType, PxGradientUnits, type PxInfer, type PxKeyframe, PxKeyframeSchema, 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, type PxTextAlongPathEffect, PxTextAlongPathEffectSchema, type PxTransformPartKey, type PxTransformParts, PxTransformPartsSchema, type PxTransformValue, PxTransformValueSchema, type PxTransformationEffect, PxTransformationEffectSchema, type PxTrigger, PxTriggerSchema, type PxTrimPathEffect, PxTrimPathEffectSchema, type PxValidationContext, type PxValidationResult, type RemoveIndex, STYLE_ATTR_NAMES, type StartOn, TRANSFORM_FN_NAMES, type Vec2, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, describeSchema, diffInEffect, evaluateMotionPathSegment, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, loadTagAnimators, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, renderNode, schemaKeys, setupAnimationTriggers, toRGBA, validateNodeEffects, visualModelAt };
+export { type ApplyResult, COLOUR_ATTR_NAMES, type FillMode, type GlyphMaterialiseOpts, type JsMode, type KeysMatch, type MaterialiseAllOptions, type MotionPathMaterialisationOptions, type MotionPathSample, type OutAction, PX_ANIMATOR_DATA_KEY, PX_ANIM_ATTR_NAME, PX_ANIM_SRC_ATTR_NAME, PX_TRANSFORM_PART_KEYS, type PlaybackDirection, type PxAnimatable, type PxAnimatedSvgDocument, PxAnimatedSvgDocumentSchema, type PxAnimationDefinition, PxAnimationDefinitionSchema, type PxAnimatorAPI, type PxAnimatorCallbacksConfig, type PxAnimatorConfig, PxAnimatorConfigSchema, PxAnimatorEngine, PxAnimatorMode, type PxAnimatorOptions, type PxAttrValue, PxAttrValueSchema, 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, 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, type PxTextAlongPathEffect, PxTextAlongPathEffectSchema, PxTextEffectSchema, type PxTransformPartKey, type PxTransformParts, PxTransformPartsSchema, type PxTransformValue, PxTransformValueSchema, type PxTransformationEffect, PxTransformationEffectSchema, type PxTrigger, PxTriggerSchema, type PxTrimPathEffect, PxTrimPathEffectSchema, type PxValidationContext, type PxValidationResult, type RemoveIndex, STYLE_ATTR_NAMES, type StartOn, TRANSFORM_FN_NAMES, type Vec2, applyPlayerEffects, calcAnimationValues, camelCaseToKebabWordIfNeeded, collectSampleTimes, createAnimator, createAnimatorImpl, createBasicFrameLoopAnimator, createFrameLoopAnimator, createWebApiAnimator, describeSchema, diffInEffect, evaluateMotionPathSegment, generateNewIds, getAnimatorConfig, getBindings, getChildren, getDefs, getNormalizedProps, isPxElementFileFormat, isPxElementFileFormatDeep, jsonElementFactory, loadTagAnimators, materialiseAllInTree, materialiseAnimatedUseInstances, materialiseGlyphText, materialiseGlyphTextAlongPath, materialiseGlyphTextHorizontal, materialiseInternalLoopsInPropAnim, materialiseInternalLoopsInTree, materialiseMotionPathInPropAnim, materialiseMotionPathsInTree, getNormalisedBindings as normalizeDocument, propAnimIsMotionPath, px, renderNode, schemaKeys, setupAnimationTriggers, toRGBA, validateNodeEffects, visualModelAt };