@motion.page/sdk 1.1.4 → 1.2.1

package/dist/utils/TextSplitter/helpers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * TextSplitter helpers — non-destructive split upgrades plus the mask-wrapper
+ * and gradient-text post-processing passes.
+ *
+ * These operate on an existing SplitResult / ElementSplitState and never touch
+ * the module-level splitStateMap directly (state is passed in by the class).
+ */
+import type { SplitType, SplitOptions, SplitResult, ElementSplitState } from './types';
+/**
+ * Attempt to upgrade an existing split to satisfy a new type request without
+ * destroying existing DOM references.
+ *
+ * Returns the appropriate span array on success, or null if the upgrade is
+ * not possible (caller must fall back to a full revert + re-split).
+ */
+export declare function tryUpgrade(element: HTMLElement, state: ElementSplitState, type: SplitType, options?: SplitOptions): HTMLElement[] | null;
+/**
+ * Return the appropriate span array from a SplitResult for the requested type.
+ * Chars have highest priority, then words, then lines.
+ */
+export declare function getSpansForType(result: SplitResult, type: string): HTMLElement[];
+/**
+ * Build a combined data-split attribute value from existing and requested types,
+ * ordered as: lines, words, chars (broadest → most granular).
+ */
+export declare function buildTypeString(existingTypes: string[], requestedTypes: string[]): string;
+/**
+ * Walk a word span's text nodes and replace them with individual char spans,
+ * appending each new span to the provided `chars` array.
+ *
+ * Used when upgrading an existing 'words' split to include 'chars'.
+ * The word span itself is NOT moved or recreated — only its text node
+ * children are swapped out, so existing references to the word span remain valid.
+ */
+export declare function nestCharsInElement(parent: HTMLElement, chars: HTMLElement[]): void;
+/**
+ * Wrap each split element in a parent with overflow:hidden for clip-reveal.
+ * The wrapper clips content so animating y:'100%' creates a reveal effect.
+ */
+export declare function applyMaskWrappers(result: SplitResult): void;
+/**
+ * Detect if the split element uses `background-clip: text` (gradient text)
+ * and propagate the gradient through all generated spans so text stays visible.
+ *
+ * Without this, inline-block split spans inherit `-webkit-text-fill-color: transparent`
+ * but NOT the parent's gradient background, making the text invisible.
+ *
+ * IMPORTANT: We copy the computed background-image directly instead of using
+ * `background: inherit` because `background` is NOT an inherited CSS property.
+ * When the split element contains intermediate wrapper elements (e.g.
+ * `<h1><span class="line"><span class="accent">word</span></span></h1>`),
+ * `inherit` resolves to `none` at each intermediate element, breaking the chain.
+ * Copying the resolved value ensures the gradient reaches every split span
+ * regardless of DOM depth.
+ */
+export declare function propagateGradientText(element: HTMLElement, result: SplitResult): void;

package/dist/utils/TextSplitter/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * TextSplitter barrel — preserves the public import path `../utils/TextSplitter`.
+ *
+ * Re-exports the exact public surface the original single-file module had:
+ *   - class `TextSplitter`
+ *   - type `SplitType` (re-exported from the shared SDK types)
+ *   - interface `SplitOptions`
+ *
+ * The SDKRegistry self-registration side effect lives in `./TextSplitter`
+ * (co-located with the class), so importing this barrel still registers the
+ * implementation on SDKRegistry at module load — the behaviour the SDK entry
+ * relies on. It is intentionally NOT a separate bare `import './register'`:
+ * the chunked SDK bundler does not inline bare side-effect imports and would
+ * leak a raw `import` statement into the standalone bundle.
+ */
+export { TextSplitter } from './TextSplitter';
+export type { SplitType, SplitOptions } from './types';

package/dist/utils/TextSplitter/splitDom.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TextSplitter DOM-walking split functions.
+ *
+ * The actual text-node → span splitting passes (words, chars, words+chars, and
+ * the layout-measuring lines pass) plus the small HTML-serialization helpers the
+ * lines pass relies on. Each function preserves existing element wrappers like
+ * `<span class="accent">word</span>` and recurses into child elements.
+ */
+import type { SplitResult } from './types';
+/**
+ * Split text nodes into word spans, preserving existing element wrappers.
+ * Recurses into child elements so `<span class="accent">word</span>` keeps
+ * its wrapper and the text inside is split within it.
+ */
+export declare function splitWordsDom(parent: HTMLElement, result: SplitResult): void;
+/**
+ * Split text nodes into character spans, preserving existing element wrappers.
+ *
+ * Characters are grouped by word inside implicit wrapper spans with
+ * `white-space: nowrap` so the browser never breaks a word across lines
+ * (matching GSAP SplitText behaviour). Only the char spans are exposed
+ * as animatable elements — the word wrappers are transparent to consumers.
+ */
+export declare function splitCharsDom(parent: HTMLElement, result: SplitResult): void;
+/**
+ * Split text nodes into word spans containing character spans.
+ * Preserves existing element wrappers.
+ */
+export declare function splitWordsWithCharsDom(parent: HTMLElement, result: SplitResult): void;
+/**
+ * Split with line detection (requires layout measurement).
+ *
+ * Strategy:
+ * 1. DOM-walk to split into word spans (preserving element wrappers)
+ * 2. Measure each word span's vertical position to group into lines
+ * 3. Wrap each line group in a line span
+ */
+export declare function splitWithLinesDom(element: HTMLElement, needsWords: boolean, needsChars: boolean, result: SplitResult): void;
+/**
+ * Get the chain of wrapper elements between a word span and the root element.
+ * Returns outermost-first order (root's direct child → … → word's parent).
+ */
+export declare function getWrapperChain(word: HTMLElement, root: HTMLElement): HTMLElement[];
+/**
+ * Serialize an element's opening tag, preserving all attributes (class, style, data-*, etc).
+ */
+export declare function openTag(el: HTMLElement): string;
+/**
+ * Escape HTML special characters
+ */
+export declare function escapeHtml(str: string): string;

package/dist/utils/TextSplitter/state.d.ts

@@ -0,0 +1,8 @@
+/**
+ * TextSplitter module state.
+ *
+ * A single WeakMap holds per-element split state, keyed by the split element.
+ * It replaces the old originalContentMap + splitResultMap pair.
+ */
+import type { ElementSplitState } from './types';
+export declare const splitStateMap: WeakMap<Element, ElementSplitState>;

package/dist/utils/TextSplitter/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * TextSplitter types — public options plus internal structural types shared
+ * across the TextSplitter parts.
+ */
+import type { SplitType } from '../../types';
+export type { SplitType };
+export interface SplitOptions {
+    /** Wrap each split element in a parent with overflow:hidden for clip-reveal effects */
+    mask?: boolean;
+    /**
+     * Opaque token identifying the caller (e.g. an AnimationBuilder instance).
+     * When provided, splits are reference-counted: the DOM is only reverted once
+     * all registered consumers release their claim via revert(element, consumer).
+     * A second consumer on the same element triggers a smart DOM upgrade (nesting)
+     * rather than destroying the first consumer's spans.
+     */
+    consumer?: object;
+}
+export interface SplitResult {
+    chars: HTMLElement[];
+    words: HTMLElement[];
+    lines: HTMLElement[];
+    elements: HTMLElement[];
+}
+/**
+ * Per-element split state, held in a module-level WeakMap.
+ * Replaces the old originalContentMap + splitResultMap pair.
+ */
+export interface ElementSplitState {
+    /** The element's innerHTML captured before any split — always the true original. */
+    originalHTML: string;
+    /** The live split result arrays (mutated in-place on upgrades). */
+    result: SplitResult;
+    /**
+     * Set of consumer tokens currently holding a reference to this split.
+     * Empty set means no consumer tracking (single-timeline / legacy callers).
+     */
+    consumers: Set<object>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion.page/sdk",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "description": "High-performance CSS animation SDK with scroll, hover, gesture, and cursor triggers",
   "type": "module",
   "main": "dist/index.js",

package/dist/utils/PropertyParser.d.ts

@@ -1,191 +0,0 @@
-/**
- * PropertyParser - Parse and normalize animation properties
- *
- * Handles:
- * - Transform shortcuts (x, y, rotate, scale, etc.)
- * - Relative values (+=, -=, *=, /=)
- * - Unit parsing and defaulting
- * - Color parsing (hex, rgb, hsl, named, CSS variables) - OPTIONAL
- * - Filter parsing (blur, brightness, contrast, etc.) - OPTIONAL
- * - DrawSVG parsing (SVG stroke animations) - OPTIONAL
- *
- * Optional parsers are loaded conditionally via SDKRegistry.
- * If a parser is not loaded, those property types will be skipped.
- */
-import type { AnimationTarget } from '../types';
-import type { ParsedFilterFunction } from './FilterParser';
-import type { ParsedDrawSVG } from './DrawSVGParser';
-import type { ParsedClipPath } from './ClipPathParser';
-/**
- * Valid property value types for animation
- */
-export type PropertyValue = number | string;
-/**
- * Base fields shared by all parsed property types
- */
-interface ParsedPropertyBase {
-    property: string;
-    isTransform: boolean;
-}
-/**
- * Scalar property (numbers with units)
- */
-interface ParsedScalarProperty extends ParsedPropertyBase {
-    type: 'scalar';
-    startValue: number;
-    endValue: number;
-    unit: string;
-}
-/**
- * Color property (RGBA values)
- */
-interface ParsedColorProperty extends ParsedPropertyBase {
-    type: 'color';
-    startColor: Float32Array;
-    endColor: Float32Array;
-}
-/**
- * Filter property (CSS filters)
- */
-interface ParsedFilterProperty extends ParsedPropertyBase {
-    type: 'filter';
-    startFilters: ParsedFilterFunction[];
-    endFilters: ParsedFilterFunction[];
-}
-/**
- * DrawSVG property (SVG stroke animation)
- */
-interface ParsedDrawSVGProperty extends ParsedPropertyBase {
-    type: 'drawSVG';
-    startDraw: ParsedDrawSVG;
-    endDraw: ParsedDrawSVG;
-    length: number;
-}
-/**
- * Clip-path property (CSS clip-path shape function interpolation)
- */
-interface ParsedClipPathProperty extends ParsedPropertyBase {
-    type: 'clipPath';
-    startClipPath: ParsedClipPath;
-    endClipPath: ParsedClipPath;
-}
-/**
- * Path property (motion along SVG path)
- */
-interface ParsedPathProperty extends ParsedPropertyBase {
-    type: 'path';
-    pathData: string;
-    pathLength: number;
-    startProgress: number;
-    endProgress: number;
-    rotate: boolean;
-    alignOffset: {
-        x: number;
-        y: number;
-    };
-    pathOffset: {
-        x: number;
-        y: number;
-    };
-}
-/**
- * Discriminated union of all parsed property types
- */
-export type ParsedProperty = ParsedScalarProperty | ParsedColorProperty | ParsedFilterProperty | ParsedDrawSVGProperty | ParsedPathProperty | ParsedClipPathProperty;
-/**
- * Check if a property is a transform property
- */
-export declare function isTransformProp(prop: string): boolean;
-/**
- * Check if a property is a color property
- */
-export declare function isColorProp(prop: string): boolean;
-/**
- * Check if a property is the filter property
- */
-export declare function isFilterProp(prop: string): boolean;
-/**
- * Check if a property is the drawSVG property
- */
-export declare function isDrawSVGProp(prop: string): boolean;
-/**
- * Check if a property is the path property (motion path)
- */
-export declare function isPathProp(prop: string): boolean;
-/**
- * Check if a property is the clip-path property (accepts both kebab and camel case)
- */
-export declare function isClipPathProp(prop: string): boolean;
-/**
- * Check if a property is a CSS variable (custom property)
- */
-export declare function isCSSVariable(prop: string): boolean;
-/**
- * Check if a value looks like a color (for CSS variable type detection)
- */
-export declare function looksLikeColor(value: PropertyValue): boolean;
-/**
- * Parse a property value and extract numeric value and unit
- */
-export declare function parseValue(value: PropertyValue): {
-    value: number;
-    unit: string;
-};
-/**
- * Get the default unit for a property
- */
-export declare function getDefaultUnit(prop: string): string;
-/**
- * Get the current computed value of a property from a target
- * Handles both DOM Elements and plain objects
- */
-export declare function getCurrentValue(target: AnimationTarget, prop: string): number;
-/**
- * Convert a pixel value to a target CSS unit by measuring the element in the DOM.
- *
- * Uses the browser's layout engine: temporarily sets `100{targetUnit}` on the
- * element, reads the computed pixel equivalent, then derives the conversion ratio.
- * This handles %, em, rem, vw, vh, vmin, vmax, ch, ex — any unit the browser supports.
- *
- * When the target unit is 'px' or empty, returns the value unchanged (no conversion).
- * Falls back to the raw pixel value if measurement fails (e.g. detached element).
- */
-export declare function convertPxToUnit(element: Element, prop: string, pxValue: number, targetUnit: string): number;
-/**
- * Get the current computed value of a property, converted to the specified unit.
- *
- * Combines getCurrentValue (which always returns px for layout properties)
- * with convertPxToUnit to return the value in the desired CSS unit.
- * Only performs conversion for DOM Element targets with non-px units.
- */
-export declare function getCurrentValueInUnit(target: AnimationTarget, prop: string, targetUnit: string): number;
-/**
- * Get the original CSS value AND unit of a property (excluding inline styles)
- * Returns both value and unit to preserve the original CSS unit (%, rem, em, vh, etc.)
- */
-export declare function getOriginalCSSValueWithUnit(target: Element, prop: string): {
-    value: number;
-    unit: string;
-};
-/**
- * Convert camelCase to kebab-case
- */
-export declare function camelToKebab(str: string): string;
-/**
- * Check if a value is relative (+=, -=, *=, /=)
- */
-export declare function isRelativeValue(value: PropertyValue): boolean;
-/**
- * Get relative operator from value string
- */
-export declare function getRelativeOperator(value: string): '+=' | '-=' | '*=' | '/=' | null;
-/**
- * Calculate relative end value
- */
-export declare function calculateRelativeValue(startValue: number, relativeValue: number, operator: '+=' | '-=' | '*=' | '/='): number;
-/**
- * Parse a property for animation
- * Handles both DOM Elements and plain objects
- */
-export declare function parseProperty(target: AnimationTarget, prop: string, targetValue: PropertyValue, fromValue?: PropertyValue): ParsedProperty;
-export {};

package/dist/utils/TextSplitter.d.ts

@@ -1,164 +0,0 @@
-/**
- * TextSplitter - Split text into animatable elements
- *
- * Splits text content into chars, words, or lines wrapped in spans.
- * Supports nested splitting (e.g., 'chars,words' = words containing char spans).
- *
- * Preserves existing element structure — inline elements like
- * `<span class="accent">word</span>` keep their wrapper and styling.
- * Only text nodes are replaced with split spans.
- *
- * Usage:
- *   const elements = TextSplitter.split(element, 'chars');
- *   const elements = TextSplitter.split(element, 'words');
- *   const elements = TextSplitter.split(element, 'chars,words');
- *
- * Revert:
- *   TextSplitter.revert(element);
- *   TextSplitter.revert(element, consumer); // reference-counted
- */
-import type { SplitType } from '../types';
-export type { SplitType };
-export interface SplitOptions {
-    /** Wrap each split element in a parent with overflow:hidden for clip-reveal effects */
-    mask?: boolean;
-    /**
-     * Opaque token identifying the caller (e.g. an AnimationBuilder instance).
-     * When provided, splits are reference-counted: the DOM is only reverted once
-     * all registered consumers release their claim via revert(element, consumer).
-     * A second consumer on the same element triggers a smart DOM upgrade (nesting)
-     * rather than destroying the first consumer's spans.
-     */
-    consumer?: object;
-}
-interface SplitResult {
-    chars: HTMLElement[];
-    words: HTMLElement[];
-    lines: HTMLElement[];
-    elements: HTMLElement[];
-}
-export declare class TextSplitter {
-    /**
-     * Split text content into animatable elements.
-     *
-     * When `options.consumer` is provided the split is reference-counted.
-     * A second consumer on the same element will have the DOM upgraded
-     * (chars nested inside existing word spans, or word-wraps promoted to
-     * word spans) rather than reverted and rebuilt, so the first consumer's
-     * DOM references remain valid.
-     *
-     * Without a consumer token the function behaves exactly like before:
-     * any existing split is reverted and a fresh split is performed.
-     */
-    static split(element: Element, type: SplitType, options?: SplitOptions): HTMLElement[];
-    /**
-     * Attempt to upgrade an existing split to satisfy a new type request without
-     * destroying existing DOM references.
-     *
-     * Returns the appropriate span array on success, or null if the upgrade is
-     * not possible (caller must fall back to a full revert + re-split).
-     */
-    private static _tryUpgrade;
-    /**
-     * Return the appropriate span array from a SplitResult for the requested type.
-     * Chars have highest priority, then words, then lines.
-     */
-    private static _getSpansForType;
-    /**
-     * Build a combined data-split attribute value from existing and requested types,
-     * ordered as: lines, words, chars (broadest → most granular).
-     */
-    private static _buildTypeString;
-    /**
-     * Walk a word span's text nodes and replace them with individual char spans,
-     * appending each new span to the provided `chars` array.
-     *
-     * Used when upgrading an existing 'words' split to include 'chars'.
-     * The word span itself is NOT moved or recreated — only its text node
-     * children are swapped out, so existing references to the word span remain valid.
-     */
-    private static _nestCharsInElement;
-    /**
-     * Split text nodes into word spans, preserving existing element wrappers.
-     * Recurses into child elements so `<span class="accent">word</span>` keeps
-     * its wrapper and the text inside is split within it.
-     */
-    private static _splitWordsDom;
-    /**
-     * Split text nodes into character spans, preserving existing element wrappers.
-     *
-     * Characters are grouped by word inside implicit wrapper spans with
-     * `white-space: nowrap` so the browser never breaks a word across lines
-     * (matching GSAP SplitText behaviour). Only the char spans are exposed
-     * as animatable elements — the word wrappers are transparent to consumers.
-     */
-    private static _splitCharsDom;
-    /**
-     * Split text nodes into word spans containing character spans.
-     * Preserves existing element wrappers.
-     */
-    private static _splitWordsWithCharsDom;
-    /**
-     * Split with line detection (requires layout measurement).
-     *
-     * Strategy:
-     * 1. DOM-walk to split into word spans (preserving element wrappers)
-     * 2. Measure each word span's vertical position to group into lines
-     * 3. Wrap each line group in a line span
-     */
-    private static _splitWithLinesDom;
-    /**
-     * Wrap each split element in a parent with overflow:hidden for clip-reveal.
-     * The wrapper clips content so animating y:'100%' creates a reveal effect.
-     */
-    private static _applyMaskWrappers;
-    /**
-     * Detect if the split element uses `background-clip: text` (gradient text)
-     * and propagate the gradient through all generated spans so text stays visible.
-     *
-     * Without this, inline-block split spans inherit `-webkit-text-fill-color: transparent`
-     * but NOT the parent's gradient background, making the text invisible.
-     *
-     * IMPORTANT: We copy the computed background-image directly instead of using
-     * `background: inherit` because `background` is NOT an inherited CSS property.
-     * When the split element contains intermediate wrapper elements (e.g.
-     * `<h1><span class="line"><span class="accent">word</span></span></h1>`),
-     * `inherit` resolves to `none` at each intermediate element, breaking the chain.
-     * Copying the resolved value ensures the gradient reaches every split span
-     * regardless of DOM depth.
-     */
-    private static _propagateGradientText;
-    /**
-     * Revert element to original content.
-     *
-     * When `consumer` is provided the revert is reference-counted: the DOM is
-     * only restored once all registered consumers have released via this method.
-     * If the consumer is the last one (or no consumer tracking is active), the
-     * element's innerHTML is restored to the pre-split original immediately.
-     *
-     * Without `consumer` (legacy / forced revert), the DOM is restored regardless
-     * of how many consumers are still registered. All consumer refs are cleared.
-     */
-    static revert(element: Element, consumer?: object): boolean;
-    /**
-     * Check if element has been split
-     */
-    static isSplit(element: Element): boolean;
-    /**
-     * Get split result for an element
-     */
-    static getResult(element: Element): SplitResult | undefined;
-    /**
-     * Get the chain of wrapper elements between a word span and the root element.
-     * Returns outermost-first order (root's direct child → … → word's parent).
-     */
-    private static _getWrapperChain;
-    /**
-     * Serialize an element's opening tag, preserving all attributes (class, style, data-*, etc).
-     */
-    private static _openTag;
-    /**
-     * Escape HTML special characters
-     */
-    private static _escapeHtml;
-}