@pixodesk/svg-animator-core 1.0.21 → 1.0.22

package/README.md

@@ -0,0 +1,127 @@
+# animator-core
+
+[![CI](https://github.com/pixodesk/pixodesk-svg-animator/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pixodesk/pixodesk-svg-animator/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Platform-neutral core of the Pixodesk SVG animator: the document schema, the
+effect materialisers, the interpolation engine and the path sampler — with **no
+DOM dependency at all**. It is what every player shares, so the web player and
+the React Native player produce identical values from the same document.
+
+# 🚧 **Status - This project is currently under development.**
+
+## Do I need this package?
+
+Usually **no**. If you just want to play an animation, install a player:
+
+| You are building for | Install |
+|---|---|
+| Browser (vanilla JS) | [`@pixodesk/svg-animator-web`](../svg-animator-web/README.md) |
+| React | [`@pixodesk/svg-animator-react`](../svg-animator-react/README.md) |
+| Vue | [`@pixodesk/svg-animator-vue`](../svg-animator-vue/README.md) |
+| React Native | [`@pixodesk/svg-animator-rn`](../svg-animator-rn/README.md) 🧪 |
+
+Each of those depends on this package and re-exports what you need.
+
+Install it **directly** when you want to work with documents rather than play
+them — validating them, transforming them, flattening them for a renderer of
+your own, or computing values at a given time without rendering anything.
+
+```bash
+npm install @pixodesk/svg-animator-core
+```
+
+## Why it exists
+
+A player has to answer two very different questions:
+
+1. **What should be on screen at time _t_?** — schema, effects, easing,
+   interpolation, path sampling. Pure computation, identical on every platform.
+2. **How do I put it there?** — DOM elements, WAAPI, `react-native-svg`.
+   Platform-specific.
+
+Everything in category 1 lives here. The package compiles without the TypeScript
+`dom` library, so a stray `document` reference is a build error rather than a
+runtime crash on a non-browser platform.
+
+## What's inside
+
+| Area | Exports |
+|---|---|
+| **Schema & types** | `PxAnimatedSvgDocumentSchema`, `PxNodeSchema`, `PxEffectsSchema`, … plus every `Px*` TypeScript type and the `px` schema builder |
+| **Validation** | `isPxElementFileFormat`, `isPxElementFileFormatDeep`, `validateNodeEffects` |
+| **Materialisers** | `materialiseAllInTree`, `applyPlayerEffects`, `materialiseInternalLoopsInTree`, `materialiseMotionPathsInTree`, `materialiseAnimatedUseInstances` |
+| **Interpolation** | `calcAnimationValues`, `interpolateValue`, `getNormalisedBindings` |
+| **Sampling / geometry** | `createPathSampler`, `evaluateMotionPathSegment`, bezier helpers, `cubicBezier`, `splitEasing` |
+| **Text** | `materialiseGlyphText`, `layoutGlyphTextChars`, `extendedPathForBrowser` |
+| **Node helpers** | `getNormalizedProps`, `sanitiseAttributeValue`, `resolveStyle`, `generateNewIds` |
+| **Playback engine** | `createBasicFrameLoopAnimator` + the `PxPlatformAdapter` interface |
+
+## The materialisation pipeline
+
+`materialiseAllInTree(doc, engine)` is the single entry point that turns a
+lightweight editor document into a flat tree any renderer can walk:
+
+1. **Effects** — `node.effects` (transformation, repeater, maskedBy, trimPath,
+   clone/retime, gradients, textPath) become real nodes, wrappers and defs.
+2. **Loops** — each property's `loop` is expanded into explicit keyframes.
+3. **Motion paths** — tangented `transform` keyframes plus `autoOrient` are
+   sampled into plain `{translate, rotate}` keyframes.
+4. **Animated `<use>`** — replaced by `<g>` + a deep clone with fresh ids.
+
+Steps 3 and 4 run when `engine` is `webapi`. Pass `webapi` for **any renderer
+without live `<use>` propagation** — that includes `react-native-svg` — and
+`frames` only for the DOM, which resolves `<use>` references natively.
+
+```ts
+import {
+    materialiseAllInTree, generateNewIds, calcAnimationValues,
+    getNormalisedBindings, PxAnimatorEngine,
+} from '@pixodesk/svg-animator-core';
+
+// Flatten once …
+const flat = generateNewIds(materialiseAllInTree(doc, PxAnimatorEngine.webapi));
+
+// … then ask for values at any time, with no renderer involved.
+for (const binding of getNormalisedBindings(flat, PxAnimatorEngine.frames) ?? []) {
+    const values = calcAnimationValues(binding.animate, 500); // t = 500 ms
+    console.log(binding.id, values);   // → { opacity: '0.5', transform: 'translate(…)' }
+}
+```
+
+This is exactly how the React Native player precomputes its animation tracks, and
+how the frames engine renders each tick in the browser — same function, same
+numbers.
+
+## Writing your own player
+
+Implement `PxPlatformAdapter` and hand it to `createBasicFrameLoopAnimator`; the
+engine handles timing, delay, direction, iterations, fill, playback rate and the
+lifecycle callbacks, then calls you with plain attribute writes.
+
+```ts
+import { createBasicFrameLoopAnimator, type PxPlatformAdapter } from '@pixodesk/svg-animator-core';
+
+const adapter: PxPlatformAdapter = {
+    isConnected: () => true,
+    setAttribute: (id, attrName, value) => { /* apply to your element */ },
+};
+
+const api = createBasicFrameLoopAnimator(flatDoc, adapter, {
+    onFinish: () => console.log('done'),
+});
+api.play();
+```
+
+Frame scheduling resolves `requestAnimationFrame` from `globalThis` at call time
+and falls back to `setTimeout`, so the engine works in browsers, React Native and
+test environments with faked timers.
+
+## Versioning
+
+Every package in this repo is released in lockstep. A player depends on the
+matching core version (`^x.y.z`), so upgrading a player upgrades the core with it.
+
+## License
+
+[MIT](../../LICENSE) © [Pixodesk](https://pixodesk.com)

package/dist/index.cjs

@@ -72,6 +72,7 @@ __export(index_exports, {
   PxEffectsSchema: () => PxEffectsSchema,
   PxElementAnimationSchema: () => PxElementAnimationSchema,
   PxFillGradientEffectSchema: () => PxFillGradientEffectSchema,
+  PxGradientGeometryAnimationSchema: () => PxGradientGeometryAnimationSchema,
   PxGradientSpreadMethod: () => PxGradientSpreadMethod,
   PxGradientStopSchema: () => PxGradientStopSchema,
   PxGradientType: () => PxGradientType,
@@ -725,6 +726,7 @@ var PxAnimatorConfigSchema = implementsInterface()(px.object({
   resetOnFinish: px.boolean().optional(),
   definitions: PxDefsSchema.optional(),
   animate: px.record(PxElementAnimationSchema).optional(),
+  timeline: px.string().optional(),
   debug: px.boolean().optional(),
   debugInstName: px.string().optional()
 }));
@@ -816,6 +818,17 @@ var PxAnimatableGradientStopsSchema = px.union([
   px.object({ value: px.array(PxGradientStopSchema) }),
   px.object({ keyframes: px.array(PxKeyframeSchema) })
 ]);
+var PxGradientGeometryAnimationSchema = implementsInterface()(px.object({
+  gradientX1: PxPropertyAnimationSchema.optional(),
+  gradientY1: PxPropertyAnimationSchema.optional(),
+  gradientX2: PxPropertyAnimationSchema.optional(),
+  gradientY2: PxPropertyAnimationSchema.optional(),
+  gradientCx: PxPropertyAnimationSchema.optional(),
+  gradientCy: PxPropertyAnimationSchema.optional(),
+  gradientFx: PxPropertyAnimationSchema.optional(),
+  gradientFy: PxPropertyAnimationSchema.optional(),
+  gradientR: PxPropertyAnimationSchema.optional()
+}));
 var PxFillGradientEffectSchema = implementsInterface()(px.object({
   type: px.enum([PxGradientType.linear, PxGradientType.radial]),
   p1: px.tuple([px.number(), px.number()]).optional(),
@@ -826,7 +839,8 @@ var PxFillGradientEffectSchema = implementsInterface()(px.object({
   stops: PxAnimatableGradientStopsSchema.optional(),
   gradientUnits: px.string().optional(),
   spreadMethod: px.string().optional(),
-  gradientTransform: px.string().optional()
+  gradientTransform: px.string().optional(),
+  animate: PxGradientGeometryAnimationSchema.optional()
 }));
 var PxStrokeGradientEffectSchema = PxFillGradientEffectSchema;
 var PxTextPathEffectSchema = implementsInterface()(px.object({
@@ -2839,17 +2853,34 @@ function partsRecord(part, value, origin) {
   return rec;
 }
 function readAnimatable(raw) {
+  var _a, _b;
   if (raw === void 0) return { kind: "absent" /* Absent */ };
   if (Array.isArray(raw)) return { kind: "static" /* Static */, value: raw };
   if (typeof raw === "object") {
     const obj = raw;
-    if (obj.keyframes) {
-      return { kind: "animated" /* Animated */, keyframes: obj.keyframes, autoOrient: obj.autoOrient, loop: obj.loop };
+    const kfs = (_a = obj.keyframes) != null ? _a : obj.kfs;
+    if (kfs) {
+      return { kind: "animated" /* Animated */, keyframes: kfs.map(normaliseKeyframe), autoOrient: obj.autoOrient, loop: obj.loop };
     }
-    if (obj.value !== void 0) return { kind: "static" /* Static */, value: obj.value };
+    const staticValue = (_b = obj.value) != null ? _b : obj.v;
+    if (staticValue !== void 0) return { kind: "static" /* Static */, value: staticValue };
   }
   return { kind: "static" /* Static */, value: raw };
 }
+function normaliseKeyframe(kf) {
+  if (!kf || typeof kf !== "object") return kf;
+  const k = kf;
+  if (k.t === void 0 && k.v === void 0 && k.e === void 0 && k.to === void 0 && k.ti === void 0) {
+    return kf;
+  }
+  const out = __spreadValues({}, k);
+  if (out.time === void 0 && k.t !== void 0) out.time = k.t;
+  if (out.value === void 0 && k.v !== void 0) out.value = k.v;
+  if (out.easing === void 0 && k.e !== void 0) out.easing = k.e;
+  if (out.tangentOut === void 0 && k.to !== void 0) out.tangentOut = k.to;
+  if (out.tangentIn === void 0 && k.ti !== void 0) out.tangentIn = k.ti;
+  return out;
+}
 function readStaticOrigin(raw, ctx) {
   var _a;
   const o = readAnimatable(raw);
@@ -5754,6 +5785,7 @@ function subtractMultiset(a, b) {
   PxEffectsSchema,
   PxElementAnimationSchema,
   PxFillGradientEffectSchema,
+  PxGradientGeometryAnimationSchema,
   PxGradientSpreadMethod,
   PxGradientStopSchema,
   PxGradientType,