af-motion 0.0.0-stage → 1.0.0

package/dist/core/transitions/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * AF Motion Automatic Transitions & Page Routing Contracts
+ *
+ * Framework-independent contracts for entrance, exit, page transitions,
+ * shared-element motion, direction awareness, and transition coordination.
+ */
+import type { AnimatableProperties } from "../animate.js";
+import type { ComponentCategory } from "../animation-intelligence/types.js";
+export declare const TRANSITION_SPEC_VERSION = "1.0.0";
+export type TransitionPattern = "fade" | "slide" | "scale" | "reveal" | "clip-reveal" | "blur" | "shared-element" | "coordinated";
+export declare const TRANSITION_PATTERNS: readonly TransitionPattern[];
+export type TransitionDirection = "in" | "out" | "up" | "down" | "left" | "right" | "forward" | "backward";
+export declare const TRANSITION_DIRECTIONS: readonly TransitionDirection[];
+export type TransitionMode = "together" | "out-in" | "in-out";
+export type TransitionState = "unmounted" | "entering" | "entered" | "exiting" | "exited";
+export interface SharedElementRect {
+    readonly top: number;
+    readonly left: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface TransitionConfig {
+    readonly pattern?: TransitionPattern;
+    readonly direction?: TransitionDirection;
+    readonly duration?: number;
+    readonly delay?: number;
+    readonly easing?: string;
+    readonly distance?: number | string;
+    readonly scale?: number;
+    readonly blur?: number | string;
+    readonly clipDirection?: "top" | "bottom" | "left" | "right" | "center";
+    readonly stagger?: number;
+    readonly respectReducedMotion?: boolean;
+    readonly sharedElementId?: string;
+    readonly componentType?: ComponentCategory;
+    readonly visualStyle?: string;
+    readonly motionDNA?: string;
+    readonly properties?: Readonly<AnimatableProperties>;
+}
+export interface PageTransitionConfig {
+    readonly pattern?: TransitionPattern;
+    readonly mode?: TransitionMode;
+    readonly enter?: TransitionConfig;
+    readonly exit?: TransitionConfig;
+    readonly duration?: number;
+    readonly easing?: string;
+    readonly directionAware?: boolean;
+}
+export interface TransitionDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly pattern: TransitionPattern;
+    readonly properties: Readonly<AnimatableProperties>;
+    readonly duration: number;
+    readonly delay: number;
+    readonly easing: string;
+    readonly respectReducedMotion: boolean;
+    readonly reducedMotionProperties?: Readonly<AnimatableProperties>;
+    readonly stagger?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface PageTransitionDefinition {
+    readonly mode: TransitionMode;
+    readonly enter: TransitionDefinition;
+    readonly exit: TransitionDefinition;
+    readonly directionAware: boolean;
+}
+export type SharedElementRole = "source" | "destination" | "auto";
+export interface SharedElementStyles {
+    opacity: number;
+    borderRadius: string;
+    transform: string;
+    zIndex: string;
+    boxShadow?: string;
+    backgroundColor?: string;
+}
+export interface SharedElementSnapshot {
+    id: string;
+    role: SharedElementRole;
+    element: HTMLElement | null;
+    rect: SharedElementRect;
+    styles: SharedElementStyles;
+    timestamp: number;
+    nestedUnder?: string;
+}
+export interface SharedElementRegistrationOptions {
+    role?: SharedElementRole;
+    nestedUnder?: string;
+    zIndex?: number;
+    keepMounted?: boolean;
+    crossfade?: boolean;
+    interpolateBorderRadius?: boolean;
+}
+export interface SharedElementTransitionConfig {
+    duration?: number;
+    easing?: string;
+    delay?: number;
+    crossfade?: boolean;
+    interpolateBorderRadius?: boolean;
+    interpolateTransforms?: boolean;
+    clipPath?: boolean | "inset" | "circle";
+    respectReducedMotion?: boolean;
+    overlayContainer?: HTMLElement;
+    onStart?: () => void;
+    onUpdate?: (progress: number) => void;
+    onComplete?: () => void;
+    onCancel?: () => void;
+}
+export type SharedElementTransitionState = "idle" | "measuring" | "animating" | "paused" | "completed" | "cancelled";
+export interface SharedElementTransitionController {
+    readonly state: SharedElementTransitionState;
+    readonly progress: number;
+    readonly isPlaying: boolean;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    seek(progress: number): void;
+    cancel(): void;
+    finish(): void;
+    retarget(newDestination: HTMLElement | SharedElementRect): void;
+    getState(): SharedElementTransitionState;
+}
+export interface CreateSharedElementTransitionOptions {
+    id?: string;
+    source?: HTMLElement | string | SharedElementRect;
+    destination?: HTMLElement | string | SharedElementRect;
+    config?: SharedElementTransitionConfig;
+    registry?: any;
+}
+export type ViewTransitionStrategy = "native-first" | "custom-only" | "shared-element";
+export type ViewTransitionPresetName = "fade" | "crossfade" | "slide" | "scale" | "zoom" | "shared-element" | "shared-element-crossfade" | "reveal" | "clip-path-reveal" | "directional-nav" | "morph";
+export interface ViewTransitionOptions {
+    strategy?: ViewTransitionStrategy;
+    preset?: ViewTransitionPresetName;
+    direction?: TransitionDirection;
+    duration?: number;
+    easing?: string;
+    beforeTransition?: () => void | Promise<void>;
+    afterTransition?: () => void | Promise<void>;
+    onComplete?: () => void;
+    onError?: (error: unknown) => void;
+    onCancel?: () => void;
+    sharedElements?: string[] | SharedElementTransitionConfig;
+    respectReducedMotion?: boolean;
+    types?: string[];
+}
+export type ViewTransitionStatus = "idle" | "pending" | "ready" | "animating" | "finished" | "skipped" | "failed";
+export interface ViewTransitionInstance {
+    readonly ready: Promise<void>;
+    readonly updateCallbackDone: Promise<void>;
+    readonly finished: Promise<void>;
+    readonly status: ViewTransitionStatus;
+    skipTransition(): void;
+}
+export interface SharedElementGroupItem {
+    id: string;
+    source?: HTMLElement | SharedElementRect;
+    destination?: HTMLElement | SharedElementRect;
+    config?: SharedElementTransitionConfig;
+    nestedUnder?: string;
+}
+export interface SharedElementGroupOptions {
+    duration?: number;
+    easing?: string;
+    stagger?: number;
+    order?: "forward" | "reverse" | "center-out";
+    respectReducedMotion?: boolean;
+    onStart?: () => void;
+    onComplete?: () => void;
+    onCancel?: () => void;
+}
+export interface SharedElementGroupController {
+    readonly state: SharedElementTransitionState;
+    readonly progress: number;
+    readonly isPlaying: boolean;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    seek(progress: number): void;
+    cancel(): void;
+    finish(): void;
+    getState(): SharedElementTransitionState;
+}

package/dist/core/transitions/view-transition.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AF Motion View Transition Engine & Browser-Native Adapter
+ *
+ * Framework-independent view transition orchestration with automatic fallback,
+ * lifecycle promises (ready, updateCallbackDone, finished), shared-element sync,
+ * and seamless integration with document.startViewTransition().
+ */
+import type { ViewTransitionInstance, ViewTransitionOptions, ViewTransitionStatus } from "./types.js";
+/**
+ * Returns current view transition state.
+ */
+export declare function getViewTransitionState(): ViewTransitionStatus;
+/**
+ * Feature detection for browser-native document.startViewTransition().
+ */
+export declare function isViewTransitionSupported(): boolean;
+/**
+ * Starts a view transition, using document.startViewTransition() when available
+ * or falling back seamlessly to AF Motion's FLIP orchestration.
+ */
+export declare function startViewTransition(updateFn: () => void | Promise<void>, options?: ViewTransitionOptions): ViewTransitionInstance;
+/**
+ * Creates a reusable view transition orchestrator function.
+ */
+export declare function createViewTransition(defaultOptions?: ViewTransitionOptions): (updateFn: () => void | Promise<void>, overrideOptions?: ViewTransitionOptions) => ViewTransitionInstance;

package/dist/core/typography/engine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AF Motion Kinetic Typography Engine
+ *
+ * Core engine providing text animation orchestrators, presets resolution,
+ * multi-unit staggering, motion path synchronization, and choreography timelines.
+ */
+import type { TypographyAnimationControls, TypographyAnimationOptions, TypographyTimeline } from "./types.js";
+/**
+ * Creates and runs a kinetic typography animation on a target element or selector.
+ */
+export declare function animateText(target: HTMLElement | string, options?: TypographyAnimationOptions): TypographyAnimationControls;
+/**
+ * Alias for animateText.
+ */
+export declare function createTextAnimation(target: HTMLElement | string, options?: TypographyAnimationOptions): TypographyAnimationControls;
+/**
+ * Creates a kinetic typography timeline for choreographed multi-step text sequences.
+ */
+export declare function createTypographyTimeline(): TypographyTimeline;

package/dist/core/typography/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Kinetic Typography Subsystem
+ *
+ * Framework-independent kinetic typography engine supporting character/word/line
+ * segmentation, customizable typography animation presets, staggers, text transitions,
+ * motion path synchronization, and choreographed timelines.
+ */
+export * from "./types.js";
+export * from "./segmenter.js";
+export * from "./properties.js";
+export * from "./presets.js";
+export * from "./stagger.js";
+export * from "./path-motion.js";
+export * from "./transitions.js";
+export * from "./engine.js";

package/dist/core/typography/path-motion.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AF Motion Kinetic Typography Motion Path Integration
+ *
+ * Positions and orients segmented typography units along 2D and 3D motion paths
+ * using AF Motion's Motion Path Engine.
+ */
+import type { MotionPathDefinition } from "../motion-path/types.js";
+import type { TypographyUnit } from "./types.js";
+export interface TextPathOptions {
+    /** Normalized path offset for the first character (0..1). Defaults to 0. */
+    pathOffset?: number;
+    /** Automatically orient characters along path tangent. Defaults to true. */
+    autoRotate?: boolean;
+    /** Fixed rotation offset in degrees. Defaults to 0. */
+    rotationOffset?: number;
+    /** Whether the text path forms a closed loop. Defaults to false. */
+    loop?: boolean;
+    /** Transform owner token for transform layering. */
+    transformOwner?: object;
+}
+/**
+ * Positions an array of typography units along a motion path at a specific global progress.
+ */
+export declare function applyTextToMotionPath(units: ReadonlyArray<TypographyUnit>, pathDefinition: MotionPathDefinition, globalProgress: number, options?: TextPathOptions): void;

package/dist/core/typography/presets.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AF Motion Kinetic Typography Presets
+ *
+ * Highly configurable, production-grade typography animation presets.
+ */
+import type { TypographyPresetDefinition, TypographyPresetName, TypographyPresetOptions } from "./types.js";
+/**
+ * Returns a configured typography preset definition by name.
+ */
+export declare function getTypographyPreset(name: TypographyPresetName, options?: TypographyPresetOptions): TypographyPresetDefinition;
+/**
+ * Lists all built-in typography preset identifiers.
+ */
+export declare function listTypographyPresets(): TypographyPresetName[];

package/dist/core/typography/properties.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AF Motion Kinetic Typography Properties & Style Evaluator
+ *
+ * Interpolates and applies typographic style states (transforms, opacity, blur,
+ * spacing, colors) using AF Motion's transform layering system.
+ */
+import type { TypographyStyleState } from "./types.js";
+/**
+ * Linearly interpolates between two TypographyStyleState objects.
+ */
+export declare function interpolateTypographyState(from: TypographyStyleState | undefined, to: TypographyStyleState | undefined, progress: number): TypographyStyleState;
+/**
+ * Applies interpolated typographic styles to a DOM element.
+ */
+export declare function applyTypographyStyle(element: HTMLElement, state: TypographyStyleState, owner: object): void;
+/**
+ * Resets inline styles and transform layers for a typography unit.
+ */
+export declare function clearTypographyStyle(element: HTMLElement, owner: object): void;

package/dist/core/typography/segmenter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AF Motion Kinetic Typography Segmentation Engine
+ *
+ * Deterministic text segmentation into Unicode grapheme characters, words,
+ * rendered lines, and paragraphs, with full emoji/combining-mark support,
+ * RTL handling, and accessibility preservation.
+ */
+import type { SegmentationResult, SegmentTextOptions, TypographyUnit } from "./types.js";
+/**
+ * Segments a raw string into grapheme clusters (characters) aware of emojis and combining marks.
+ */
+export declare function segmentCharacters(text: string, locales?: string | string[]): string[];
+/**
+ * Segments a raw string into words while preserving whitespace and punctuation.
+ */
+export declare function segmentWords(text: string): string[];
+/**
+ * Segments a raw string into paragraphs.
+ */
+export declare function segmentParagraphs(text: string): string[];
+/**
+ * Segments raw text string into units based on mode.
+ */
+export declare function segmentTextString(text: string, options?: SegmentTextOptions): TypographyUnit[];
+/**
+ * Segments a DOM element or text string into kinetic typography units.
+ */
+export declare function segmentText(target: HTMLElement | string, options?: SegmentTextOptions): SegmentationResult;
+/**
+ * Public splitText API wrapping segmentText with backward compatibility.
+ */
+export declare function splitText(target: HTMLElement | string, options?: SegmentTextOptions): SegmentationResult;

package/dist/core/typography/stagger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Kinetic Typography Stagger & Choreography Engine
+ *
+ * Computes deterministic unit delays and ordering using forward, reverse,
+ * center-out, edges-in, and seeded pseudo-random permutations.
+ */
+import type { StaggerConfig, TypographyUnit } from "./types.js";
+/**
+ * Generates an array of normalized stagger factors (0..1) for each unit.
+ */
+export declare function computeStaggerFactors(total: number, config?: StaggerConfig): number[];
+/**
+ * Computes individual unit start delays in milliseconds.
+ */
+export declare function computeUnitDelays(units: ReadonlyArray<TypographyUnit>, stagger?: number | StaggerConfig): number[];

package/dist/core/typography/transitions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Kinetic Typography Transitions
+ *
+ * Implements stateful text morphing and transitions between arbitrary strings:
+ * character replacement, rolling text, scramble transitions, and crossfades.
+ */
+import type { TypographyAnimationControls, TypographyTransitionOptions } from "./types.js";
+/**
+ * Transitions an element's text content from current to next string.
+ */
+export declare function createTextTransition(target: HTMLElement | string, nextText: string, options?: TypographyTransitionOptions): TypographyAnimationControls;

package/dist/core/typography/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * AF Motion Kinetic Typography Engine Contracts & Types
+ *
+ * Framework-independent contracts for text segmentation, kinetic typographic
+ * properties, presets, staggers, text transitions, and motion path integration.
+ */
+import type { EasingOption } from "../../easing/easings.js";
+import type { MotionPathDefinition } from "../motion-path/types.js";
+export type TypographySegmentationMode = "characters" | "words" | "lines" | "paragraphs" | "custom";
+export interface TypographyUnit {
+    readonly id: string;
+    readonly text: string;
+    readonly index: number;
+    readonly total: number;
+    readonly type: TypographySegmentationMode;
+    readonly element?: HTMLElement;
+    readonly parentIndex?: number;
+    readonly isWhitespace: boolean;
+}
+export interface SegmentTextOptions {
+    /** Segmentation granularity. Defaults to "words". */
+    by?: TypographySegmentationMode;
+    /** Base CSS class applied to each wrapper span. Defaults to "af-kinetic-unit". */
+    className?: string;
+    /** Whether to retain and wrap whitespace. Defaults to true. */
+    preserveWhitespace?: boolean;
+    /** BCP 47 language tag(s) for locale-aware segmentation. */
+    locales?: string | string[];
+    /** Custom splitter function when by is "custom". */
+    customSegmenter?: (text: string) => string[];
+    /** Preserves accessibility by applying aria-label to root and aria-hidden to units. Defaults to true. */
+    aria?: boolean;
+}
+export interface SegmentationResult {
+    readonly units: ReadonlyArray<TypographyUnit>;
+    readonly rootElement?: HTMLElement;
+    readonly originalText: string;
+    restore(): void;
+    destroy(): void;
+}
+export interface TypographyStyleState {
+    opacity?: number;
+    translateX?: number | string;
+    translateY?: number | string;
+    translateZ?: number | string;
+    rotate?: number;
+    rotateX?: number;
+    rotateY?: number;
+    rotateZ?: number;
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    skewX?: number;
+    skewY?: number;
+    blur?: number;
+    letterSpacing?: number | string;
+    wordSpacing?: number | string;
+    color?: string;
+    transformOrigin?: string;
+}
+export type StaggerOrder = "forward" | "reverse" | "center-out" | "edges-in" | "random";
+export interface StaggerConfig {
+    /** Delay between consecutive units in milliseconds. */
+    each?: number;
+    /** Ordering strategy. Defaults to "forward". */
+    from?: StaggerOrder | number;
+    /** Easing applied across the stagger sequence. */
+    ease?: EasingOption;
+    /** Deterministic seed for random stagger order. Defaults to 42. */
+    seed?: number;
+    /** Custom calculation callback returning delay offset in milliseconds. */
+    custom?: (index: number, total: number, unit: TypographyUnit) => number;
+}
+export type TypographyPresetName = "fade-in" | "fade-up" | "fade-down" | "slide-in" | "scale-reveal" | "blur-reveal" | "rotate-reveal" | "character-wave" | "word-stagger" | "line-reveal" | "typewriter" | "text-scramble" | "split-reveal" | "bounce-characters" | "elastic-entrance" | "highlight-sweep";
+export interface TypographyPresetOptions {
+    duration?: number;
+    delay?: number;
+    distance?: number;
+    direction?: "up" | "down" | "left" | "right";
+    stagger?: number | StaggerConfig;
+    scrambleCharset?: string;
+    highlightColor?: string;
+}
+export interface TypographyPresetDefinition {
+    name: TypographyPresetName;
+    from: TypographyStyleState;
+    to: TypographyStyleState;
+    defaultDuration: number;
+    defaultEasing: EasingOption;
+    defaultBy: TypographySegmentationMode;
+    defaultStagger?: StaggerConfig;
+}
+export interface TypographyAnimationOptions {
+    by?: TypographySegmentationMode;
+    preset?: TypographyPresetName;
+    presetOptions?: TypographyPresetOptions;
+    from?: TypographyStyleState;
+    to?: TypographyStyleState;
+    duration?: number;
+    delay?: number;
+    easing?: EasingOption;
+    stagger?: number | StaggerConfig;
+    motionPath?: MotionPathDefinition;
+    pathOffset?: number;
+    autoRotate?: boolean;
+    repeat?: number;
+    yoyo?: boolean;
+    respectReducedMotion?: boolean;
+    transformOwner?: object;
+    onStart?: () => void;
+    onUpdate?: (progress: number) => void;
+    onProgress?: (progress: number, unitIndex: number) => void;
+    onComplete?: () => void;
+    onCancel?: () => void;
+}
+export interface TypographyAnimationControls {
+    seek(progress: number): void;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    setPlaybackRate(rate: number): void;
+    getPlaybackRate(): number;
+    cancel(): void;
+    finish(): void;
+    destroy(): void;
+    readonly finished: Promise<void>;
+}
+export type TypographyTransitionType = "crossfade" | "character-replace" | "word-replace" | "line-replace" | "rolling-text" | "scramble-transition" | "sequential-replace";
+export interface TypographyTransitionOptions {
+    type?: TypographyTransitionType;
+    duration?: number;
+    delay?: number;
+    easing?: EasingOption;
+    stagger?: number | StaggerConfig;
+    scrambleCharset?: string;
+    onStart?: () => void;
+    onComplete?: () => void;
+    onCancel?: () => void;
+}
+export interface TypographyTimelineStep {
+    target: HTMLElement | string;
+    options: TypographyAnimationOptions;
+    position?: number | string;
+}
+export interface TypographyTimeline {
+    add(target: HTMLElement | string, options: TypographyAnimationOptions, position?: number | string): TypographyTimeline;
+    play(): void;
+    pause(): void;
+    seek(progress: number): void;
+    reverse(): void;
+    cancel(): void;
+    readonly duration: number;
+    readonly finished: Promise<void>;
+}

package/dist/core/utils/safe-json.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AF Motion — Shared Input, JSON, and Code-Generation Safety Utilities
+ *
+ * Zero Node.js built-ins: safe for core, browser, React, MCP, AI, and CLI consumers.
+ */
+/**
+ * Type guard checking that a value is a non-null, non-array plain object record.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * JSON.parse wrapper that strips prototype-pollution keys (`__proto__`, `constructor`, `prototype`)
+ * and enforces an optional maximum character payload length.
+ */
+export declare function parseSafeJson<T = unknown>(raw: string, options?: {
+    maxLength?: number;
+}): T;
+/**
+ * Checks whether a value contains circular object references without throwing.
+ */
+export declare function hasCircularReference(value: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * Safely stringifies arbitrary data without throwing on circular references or BigInt.
+ */
+export declare function safeJsonStringify(value: unknown, space?: number): string;
+/**
+ * Escapes user-controlled text for safe embedding inside JSX text nodes.
+ * Neutralizes `{`, `}`, `<`, `>` so expressions or tags cannot inject code.
+ */
+export declare function escapeJsxText(value: unknown): string;
+/**
+ * Sanitizes an identifier or attribute value used in HTML/JSX `data-*` attributes.
+ */
+export declare function sanitizeAttributeValue(value: unknown, fallback?: string): string;
+/**
+ * Sanitizes a JavaScript/TypeScript PascalCase component or function identifier.
+ */
+export declare function sanitizeCodeIdentifier(value: unknown, fallback?: string): string;
+/**
+ * Sanitizes text inserted into JS/TS block comments so comment terminators cannot close them early.
+ */
+export declare function sanitizeCommentText(value: unknown): string;
+/**
+ * Sanitizes a CSS token/value inserted into style strings or CSS variable maps
+ * so characters like `;`, `{`, `}`, `<`, `>`, quotes, and newlines cannot break out.
+ */
+export declare function sanitizeCssValue(value: unknown, fallback?: string): string;
+/**
+ * Strips local filesystem paths and stack trace lines from error messages surfaced to external callers.
+ */
+export declare function sanitizeExternalErrorMessage(err: unknown, fallback?: string): string;