@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/motion-mix.cjs

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.motionMix = motionMix;
+// The public Motion `mix` utility. Pin: motion-dom/src/utils/mix/{index,complex,immediate,number}
+// and value/types/color. H1 (REQ-VALUETYPE-016): arm SELECTION is the pin's `getMixer`, dispatching
+// on the ORIGIN alone, and the arms the pin owns outright — array, object, color object,
+// CSS-variable token, and the non-mixable fallback — run the pin's own algorithms, output-reference
+// reuse included. The remaining string arm still executes through core's ONE value seam
+// (parseValue → mix → transformValue): its per-family laws are unchanged here, and its recorded
+// divergences from the pin — REQ-VALUETYPE-004/007/008 value-seam strictness and
+// REQ-VALUETYPE-005/006 color-syntax capability — stay owned by those requirements and by their own
+// doctrine-census rows, never by this file. REQ-VALUETYPE-015's both-visible discrete pair is no
+// longer among them: H3 closed it, and the seam publishes the pin's zero-slot constant.
+//
+// Exported publicly as `mix` by the PRODUCT entries only — the core-root `mix` name stays the
+// SPEC-VALUE-TYPES typed seam.
+const value_types_1 = require("./value-types/index.cjs");
+const color_1 = require("./value-types/color.cjs");
+// pin mix/number.ts: unclamped linear interpolation through raw JavaScript arithmetic — a
+// non-numeric operand yields NaN, it does not refuse.
+function mixNumber(from, to, progress) {
+    return from + (to - from) * progress;
+}
+function numberMixer(from, to) {
+    return (p) => mixNumber(from, to, p);
+}
+// pin mix/immediate.ts: the origin until progress passes zero, then the target.
+function mixImmediate(from, to) {
+    return (p) => (p > 0 ? to : from);
+}
+// pin animation/utils/is-css-variable.ts, reproduced verbatim (prefix guard + comment-stripped
+// single-variable pattern). Native has no CSS custom properties to resolve, so the pin's immediate
+// arm IS the faithful behavior — a refusal here would be a stricter native policy.
+const SINGLE_CSS_VARIABLE_RE = /var\(--(?:[\w-]+\s*|[\w-]+\s*,(?:\s*[^)(\s]|\s*\((?:[^)(]|\([^)(]*\))*\))+\s*)\)$/iu;
+function isCssVariableToken(value) {
+    if (!value.startsWith('var(--'))
+        return false;
+    return SINGLE_CSS_VARIABLE_RE.test((value.split('/*')[0] ?? '').trim());
+}
+// pin value/types/utils/single-color-regex.ts, reproduced verbatim (flags included) — the pin's
+// colour RECOGNIZER. Core's own `isColor` is deliberately WIDER (a named-colour table,
+// whitespace-padded channels — `motion.color-syntax-capability`), so this replica exists to answer
+// the one question `colorMixer`'s degrade path cannot answer with core's recognizer: which PIN arm
+// would own the pair. The reproduced stringification fault depends on it (LOOP Decision 53), and
+// the differential's boundary rows pin both sides.
+const SINGLE_COLOR_REGEX = /^(?:#[\da-f]{3,8}|(?:rgb|hsl)a?\((?:-?[\d.]+%?[,\s]+){2}-?[\d.]+%?\s*(?:[,/]\s*)?(?:\b\d+(?:\.\d+)?|\.\d+)?%?\))$/iu;
+// pin value/types/color/index.ts `color.test` for the OBJECT arm: an own `red` property is an RGBA
+// record, an own `hue` property an HSLA record. `Object.hasOwn` is the modern spelling of the pin's
+// `Object.prototype.hasOwnProperty.call` and answers identically.
+function isColorObject(value) {
+    return Object.hasOwn(value, 'red') || Object.hasOwn(value, 'hue');
+}
+const NOT_A_COLOR = { kind: 'not-a-color' };
+function asRgba(value) {
+    if (typeof value === 'string') {
+        if (!(0, color_1.isColor)(value))
+            return NOT_A_COLOR;
+        const verdict = (0, color_1.parseColorVerdict)(value);
+        return verdict.refusal === null
+            ? { kind: 'rgba', value: verdict.parsed }
+            : { kind: 'unparseable', refusal: verdict.refusal };
+    }
+    if (typeof value !== 'object' || value === null)
+        return NOT_A_COLOR;
+    if (Object.hasOwn(value, 'red'))
+        return { kind: 'rgba', value: value };
+    if (Object.hasOwn(value, 'hue')) {
+        const hsla = value;
+        return {
+            kind: 'rgba',
+            value: (0, color_1.hslaToRgba)(hsla.hue, hsla.saturation, hsla.lightness, hsla.alpha),
+        };
+    }
+    return NOT_A_COLOR;
+}
+// The pin's factory-time stringification of the endpoint that failed `asRgba`, reproduced so the
+// same TypeError escapes at the same moment (LOOP Decision 53). Which pin arm would own the pair
+// decides which operation the pin would fault on:
+//   - a `singleColorRegex` string origin, or a colour RECORD (the pin's object branch sends
+//     red/hue records to `mixColor` too): `mixColor`'s `asRGBA` interpolates the endpoint into its
+//     `warning()` template literal BEFORE returning false — throwing on a `Symbol`, an object with
+//     no `toString`, or a throwing `toString`; a nullish target stringifies fine there.
+//   - any other string origin core recognizes (a named colour, whitespace-padded rgb — the pairs
+//     core's WIDER recognizer routes here): `mixComplex`'s `analyseComplexValue`
+//     (value/types/complex/index.ts:21-22) opens with `const originalValue = value.toString()` and
+//     immediately parses the result with `.replace(complexRegex, …)` — throwing on a nullish
+//     target, on a target with no `toString`, AND on a `toString` that returns a non-string
+//     (`originalValue.replace is not a function`); tolerating a `Symbol` (its `toString` returns
+//     a string).
+// For every pair the pin tolerates the operation is inert and the caller's step stands. `from` is
+// never the failing endpoint here: `getMixer` only routes origins `asRgba` resolves.
+function pinStringification(from, to) {
+    if (typeof from === 'string' && !SINGLE_COLOR_REGEX.test(from)) {
+        return pinComplexStringification(to);
+    }
+    return `${to}`;
+}
+// pin value/types/complex/index.ts `analyseComplexValue`'s fault surface, operation for operation:
+// `const originalValue = value.toString()` then `originalValue.replace(complexRegex, …)`. The
+// parameter is NAMED `value` because V8 quotes the receiver's source text in the TypeError, so the
+// pin's message escapes byte-identically only under the pin's own identifier (the precedent is
+// `arrayMixer`'s `blendValue`). The parse that follows the replace is the pin's semantics, not
+// its fault surface, and is not reproduced. One acknowledged tail: the pin's `tokenised.split(...)`
+// on the replace RESULT can still throw there (a `toString` returning a non-primitive object with
+// a hostile `replace`) and is not reproduced — a contract-breaking constructed input, recorded by
+// the confirming review as a non-blocking minor.
+function pinComplexStringification(value) {
+    const originalValue = value.toString();
+    return originalValue.replace(/$/, '');
+}
+function colorMixer(from, to) {
+    const fromColor = asRgba(from);
+    const toColor = asRgba(to);
+    if (fromColor.kind === 'unparseable')
+        throw new Error(fromColor.refusal);
+    if (toColor.kind === 'unparseable')
+        throw new Error(toColor.refusal);
+    if (fromColor.kind === 'not-a-color' || toColor.kind === 'not-a-color') {
+        pinStringification(from, to);
+        return mixImmediate(from, to);
+    }
+    const fromRgba = fromColor.value;
+    const toRgba = toColor.value;
+    return (p) => (0, color_1.transformColor)((0, color_1.mixColor)(fromRgba, toRgba, p));
+}
+// The one core value seam (SPEC-VALUE-TYPES §3) — the pin's `mixComplex` position in the dispatch
+// table. A non-string target has no decomposition here, so it stays the seam's own loud
+// cross-family refusal (REQ-VALUETYPE-008, `motion.value-seam-strictness`).
+function seamMixer(from, to) {
+    if (typeof to !== 'string') {
+        throw new Error(`mix: cannot mix ${JSON.stringify(from)} with ${JSON.stringify(to)} — a value-seam origin ` +
+            'needs a string target of one value family (REQ-VALUETYPE-008)');
+    }
+    const fromTyped = (0, value_types_1.parseValue)(from);
+    const toTyped = (0, value_types_1.parseValue)(to);
+    return (p) => {
+        const committed = (0, value_types_1.transformValue)((0, value_types_1.mix)(fromTyped, toTyped, p));
+        return typeof committed === 'number' ? String(committed) : committed;
+    };
+}
+// pin mix/complex.ts `mixArray`: the ORIGIN governs length and arm choice, and ONE output array is
+// mutated in place and handed back on every call.
+function arrayMixer(from, to) {
+    const origin = from;
+    const target = to;
+    const output = [...origin];
+    const numValues = output.length;
+    // Named `blendValue` to match the pin's own local: `Array#map` SKIPS holes, so a sparse origin
+    // leaves a hole here and the call below raises the pin's `blendValue[i] is not a function`
+    // TypeError — byte-identical only if the identifier is. Guarding the hole instead would suppress
+    // a pin fault of exactly the class LOOP Decision 25 keeps.
+    const blendValue = origin.map((value, i) => getMixer(value)(value, target[i]));
+    return (p) => {
+        for (let i = 0; i < numValues; i++) {
+            output[i] = blendValue[i](p);
+        }
+        return output;
+    };
+}
+// pin mix/complex.ts `mixObject`: a UNION snapshot of both sides, only both-defined keys blended,
+// and ONE output object mutated in place and handed back on every call. `for…in` and the direct
+// `origin[key]` read are the pin's own operations — a null origin against a populated target
+// raises the pin's `TypeError` here, which the fidelity presumption keeps rather than guarding.
+function objectMixer(from, to) {
+    const origin = from;
+    const target = to;
+    const output = { ...origin, ...target };
+    const blendValue = {};
+    for (const key in output) {
+        if (origin[key] !== undefined && target[key] !== undefined) {
+            blendValue[key] = getMixer(origin[key])(origin[key], target[key]);
+        }
+    }
+    return (p) => {
+        for (const key in blendValue) {
+            output[key] = blendValue[key](p);
+        }
+        return output;
+    };
+}
+// pin mix/complex.ts `getMixer`, branch for branch. `typeof from === 'object'` deliberately
+// includes `null`, exactly as the pin's does.
+function getMixer(from) {
+    if (typeof from === 'number')
+        return numberMixer;
+    if (typeof from === 'string') {
+        if (isCssVariableToken(from))
+            return mixImmediate;
+        return (0, color_1.isColor)(from) ? colorMixer : seamMixer;
+    }
+    if (Array.isArray(from))
+        return arrayMixer;
+    if (typeof from === 'object') {
+        return from !== null && isColorObject(from) ? colorMixer : objectMixer;
+    }
+    return mixImmediate;
+}
+function motionMix(from, to, p) {
+    // pin mix/index.ts: the immediate form requires all THREE arguments to be numbers; otherwise the
+    // third is ignored and the factory is returned.
+    if (typeof from === 'number' && typeof to === 'number' && typeof p === 'number') {
+        return mixNumber(from, to, p);
+    }
+    return getMixer(from)(from, to);
+}

package/dist/motion-mix.d.cts

@@ -0,0 +1,3 @@
+export type MotionMixer<T> = (p: number) => T;
+export declare function motionMix(from: number, to: number, p: number): number;
+export declare function motionMix<T>(from: T, to: T): MotionMixer<T>;

package/dist/motion-mix.d.ts

@@ -0,0 +1,3 @@
+export type MotionMixer<T> = (p: number) => T;
+export declare function motionMix(from: number, to: number, p: number): number;
+export declare function motionMix<T>(from: T, to: T): MotionMixer<T>;

package/dist/motion-mix.js

@@ -0,0 +1,202 @@
+// The public Motion `mix` utility. Pin: motion-dom/src/utils/mix/{index,complex,immediate,number}
+// and value/types/color. H1 (REQ-VALUETYPE-016): arm SELECTION is the pin's `getMixer`, dispatching
+// on the ORIGIN alone, and the arms the pin owns outright — array, object, color object,
+// CSS-variable token, and the non-mixable fallback — run the pin's own algorithms, output-reference
+// reuse included. The remaining string arm still executes through core's ONE value seam
+// (parseValue → mix → transformValue): its per-family laws are unchanged here, and its recorded
+// divergences from the pin — REQ-VALUETYPE-004/007/008 value-seam strictness and
+// REQ-VALUETYPE-005/006 color-syntax capability — stay owned by those requirements and by their own
+// doctrine-census rows, never by this file. REQ-VALUETYPE-015's both-visible discrete pair is no
+// longer among them: H3 closed it, and the seam publishes the pin's zero-slot constant.
+//
+// Exported publicly as `mix` by the PRODUCT entries only — the core-root `mix` name stays the
+// SPEC-VALUE-TYPES typed seam.
+import { mix as mixTyped, parseValue, transformValue } from "./value-types/index.js";
+import { hslaToRgba, isColor, mixColor, parseColorVerdict, transformColor, } from "./value-types/color.js";
+// pin mix/number.ts: unclamped linear interpolation through raw JavaScript arithmetic — a
+// non-numeric operand yields NaN, it does not refuse.
+function mixNumber(from, to, progress) {
+    return from + (to - from) * progress;
+}
+function numberMixer(from, to) {
+    return (p) => mixNumber(from, to, p);
+}
+// pin mix/immediate.ts: the origin until progress passes zero, then the target.
+function mixImmediate(from, to) {
+    return (p) => (p > 0 ? to : from);
+}
+// pin animation/utils/is-css-variable.ts, reproduced verbatim (prefix guard + comment-stripped
+// single-variable pattern). Native has no CSS custom properties to resolve, so the pin's immediate
+// arm IS the faithful behavior — a refusal here would be a stricter native policy.
+const SINGLE_CSS_VARIABLE_RE = /var\(--(?:[\w-]+\s*|[\w-]+\s*,(?:\s*[^)(\s]|\s*\((?:[^)(]|\([^)(]*\))*\))+\s*)\)$/iu;
+function isCssVariableToken(value) {
+    if (!value.startsWith('var(--'))
+        return false;
+    return SINGLE_CSS_VARIABLE_RE.test((value.split('/*')[0] ?? '').trim());
+}
+// pin value/types/utils/single-color-regex.ts, reproduced verbatim (flags included) — the pin's
+// colour RECOGNIZER. Core's own `isColor` is deliberately WIDER (a named-colour table,
+// whitespace-padded channels — `motion.color-syntax-capability`), so this replica exists to answer
+// the one question `colorMixer`'s degrade path cannot answer with core's recognizer: which PIN arm
+// would own the pair. The reproduced stringification fault depends on it (LOOP Decision 53), and
+// the differential's boundary rows pin both sides.
+const SINGLE_COLOR_REGEX = /^(?:#[\da-f]{3,8}|(?:rgb|hsl)a?\((?:-?[\d.]+%?[,\s]+){2}-?[\d.]+%?\s*(?:[,/]\s*)?(?:\b\d+(?:\.\d+)?|\.\d+)?%?\))$/iu;
+// pin value/types/color/index.ts `color.test` for the OBJECT arm: an own `red` property is an RGBA
+// record, an own `hue` property an HSLA record. `Object.hasOwn` is the modern spelling of the pin's
+// `Object.prototype.hasOwnProperty.call` and answers identically.
+function isColorObject(value) {
+    return Object.hasOwn(value, 'red') || Object.hasOwn(value, 'hue');
+}
+const NOT_A_COLOR = { kind: 'not-a-color' };
+function asRgba(value) {
+    if (typeof value === 'string') {
+        if (!isColor(value))
+            return NOT_A_COLOR;
+        const verdict = parseColorVerdict(value);
+        return verdict.refusal === null
+            ? { kind: 'rgba', value: verdict.parsed }
+            : { kind: 'unparseable', refusal: verdict.refusal };
+    }
+    if (typeof value !== 'object' || value === null)
+        return NOT_A_COLOR;
+    if (Object.hasOwn(value, 'red'))
+        return { kind: 'rgba', value: value };
+    if (Object.hasOwn(value, 'hue')) {
+        const hsla = value;
+        return {
+            kind: 'rgba',
+            value: hslaToRgba(hsla.hue, hsla.saturation, hsla.lightness, hsla.alpha),
+        };
+    }
+    return NOT_A_COLOR;
+}
+// The pin's factory-time stringification of the endpoint that failed `asRgba`, reproduced so the
+// same TypeError escapes at the same moment (LOOP Decision 53). Which pin arm would own the pair
+// decides which operation the pin would fault on:
+//   - a `singleColorRegex` string origin, or a colour RECORD (the pin's object branch sends
+//     red/hue records to `mixColor` too): `mixColor`'s `asRGBA` interpolates the endpoint into its
+//     `warning()` template literal BEFORE returning false — throwing on a `Symbol`, an object with
+//     no `toString`, or a throwing `toString`; a nullish target stringifies fine there.
+//   - any other string origin core recognizes (a named colour, whitespace-padded rgb — the pairs
+//     core's WIDER recognizer routes here): `mixComplex`'s `analyseComplexValue`
+//     (value/types/complex/index.ts:21-22) opens with `const originalValue = value.toString()` and
+//     immediately parses the result with `.replace(complexRegex, …)` — throwing on a nullish
+//     target, on a target with no `toString`, AND on a `toString` that returns a non-string
+//     (`originalValue.replace is not a function`); tolerating a `Symbol` (its `toString` returns
+//     a string).
+// For every pair the pin tolerates the operation is inert and the caller's step stands. `from` is
+// never the failing endpoint here: `getMixer` only routes origins `asRgba` resolves.
+function pinStringification(from, to) {
+    if (typeof from === 'string' && !SINGLE_COLOR_REGEX.test(from)) {
+        return pinComplexStringification(to);
+    }
+    return `${to}`;
+}
+// pin value/types/complex/index.ts `analyseComplexValue`'s fault surface, operation for operation:
+// `const originalValue = value.toString()` then `originalValue.replace(complexRegex, …)`. The
+// parameter is NAMED `value` because V8 quotes the receiver's source text in the TypeError, so the
+// pin's message escapes byte-identically only under the pin's own identifier (the precedent is
+// `arrayMixer`'s `blendValue`). The parse that follows the replace is the pin's semantics, not
+// its fault surface, and is not reproduced. One acknowledged tail: the pin's `tokenised.split(...)`
+// on the replace RESULT can still throw there (a `toString` returning a non-primitive object with
+// a hostile `replace`) and is not reproduced — a contract-breaking constructed input, recorded by
+// the confirming review as a non-blocking minor.
+function pinComplexStringification(value) {
+    const originalValue = value.toString();
+    return originalValue.replace(/$/, '');
+}
+function colorMixer(from, to) {
+    const fromColor = asRgba(from);
+    const toColor = asRgba(to);
+    if (fromColor.kind === 'unparseable')
+        throw new Error(fromColor.refusal);
+    if (toColor.kind === 'unparseable')
+        throw new Error(toColor.refusal);
+    if (fromColor.kind === 'not-a-color' || toColor.kind === 'not-a-color') {
+        pinStringification(from, to);
+        return mixImmediate(from, to);
+    }
+    const fromRgba = fromColor.value;
+    const toRgba = toColor.value;
+    return (p) => transformColor(mixColor(fromRgba, toRgba, p));
+}
+// The one core value seam (SPEC-VALUE-TYPES §3) — the pin's `mixComplex` position in the dispatch
+// table. A non-string target has no decomposition here, so it stays the seam's own loud
+// cross-family refusal (REQ-VALUETYPE-008, `motion.value-seam-strictness`).
+function seamMixer(from, to) {
+    if (typeof to !== 'string') {
+        throw new Error(`mix: cannot mix ${JSON.stringify(from)} with ${JSON.stringify(to)} — a value-seam origin ` +
+            'needs a string target of one value family (REQ-VALUETYPE-008)');
+    }
+    const fromTyped = parseValue(from);
+    const toTyped = parseValue(to);
+    return (p) => {
+        const committed = transformValue(mixTyped(fromTyped, toTyped, p));
+        return typeof committed === 'number' ? String(committed) : committed;
+    };
+}
+// pin mix/complex.ts `mixArray`: the ORIGIN governs length and arm choice, and ONE output array is
+// mutated in place and handed back on every call.
+function arrayMixer(from, to) {
+    const origin = from;
+    const target = to;
+    const output = [...origin];
+    const numValues = output.length;
+    // Named `blendValue` to match the pin's own local: `Array#map` SKIPS holes, so a sparse origin
+    // leaves a hole here and the call below raises the pin's `blendValue[i] is not a function`
+    // TypeError — byte-identical only if the identifier is. Guarding the hole instead would suppress
+    // a pin fault of exactly the class LOOP Decision 25 keeps.
+    const blendValue = origin.map((value, i) => getMixer(value)(value, target[i]));
+    return (p) => {
+        for (let i = 0; i < numValues; i++) {
+            output[i] = blendValue[i](p);
+        }
+        return output;
+    };
+}
+// pin mix/complex.ts `mixObject`: a UNION snapshot of both sides, only both-defined keys blended,
+// and ONE output object mutated in place and handed back on every call. `for…in` and the direct
+// `origin[key]` read are the pin's own operations — a null origin against a populated target
+// raises the pin's `TypeError` here, which the fidelity presumption keeps rather than guarding.
+function objectMixer(from, to) {
+    const origin = from;
+    const target = to;
+    const output = { ...origin, ...target };
+    const blendValue = {};
+    for (const key in output) {
+        if (origin[key] !== undefined && target[key] !== undefined) {
+            blendValue[key] = getMixer(origin[key])(origin[key], target[key]);
+        }
+    }
+    return (p) => {
+        for (const key in blendValue) {
+            output[key] = blendValue[key](p);
+        }
+        return output;
+    };
+}
+// pin mix/complex.ts `getMixer`, branch for branch. `typeof from === 'object'` deliberately
+// includes `null`, exactly as the pin's does.
+function getMixer(from) {
+    if (typeof from === 'number')
+        return numberMixer;
+    if (typeof from === 'string') {
+        if (isCssVariableToken(from))
+            return mixImmediate;
+        return isColor(from) ? colorMixer : seamMixer;
+    }
+    if (Array.isArray(from))
+        return arrayMixer;
+    if (typeof from === 'object') {
+        return from !== null && isColorObject(from) ? colorMixer : objectMixer;
+    }
+    return mixImmediate;
+}
+export function motionMix(from, to, p) {
+    // pin mix/index.ts: the immediate form requires all THREE arguments to be numbers; otherwise the
+    // third is ignored and the factory is returned.
+    if (typeof from === 'number' && typeof to === 'number' && typeof p === 'number') {
+        return mixNumber(from, to, p);
+    }
+    return getMixer(from)(from, to);
+}