af-motion 0.0.0-stage → 1.0.0

package/dist/core/svg-morph/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * AF Motion SVG Morphing Engine Contracts
+ *
+ * Framework-independent contracts for SVG path parsing, normalization,
+ * shape conversion, cubic Bézier alignment, interpolation, and animation.
+ */
+import type { AnimationControls, AnimationOptions } from "../animation.js";
+export declare const SVG_MORPH_SPEC_VERSION = "1.0.0";
+/**
+ * Standard SVG Path Command Types.
+ */
+export type SVGCommandType = "M" | "m" | "L" | "l" | "H" | "h" | "V" | "v" | "C" | "c" | "S" | "s" | "Q" | "q" | "T" | "t" | "A" | "a" | "Z" | "z";
+/**
+ * A parsed SVG command with its raw type and parameter numbers.
+ */
+export interface SVGPathCommand {
+    readonly type: SVGCommandType;
+    readonly params: readonly number[];
+}
+/**
+ * A 2D point tuple [x, y].
+ */
+export type SVGPointTuple = readonly [number, number];
+/**
+ * A canonical cubic Bézier curve segment:
+ * Start point is the endpoint of the previous segment (or M).
+ * Control point 1: [cp1x, cp1y]
+ * Control point 2: [cp2x, cp2y]
+ * End point: [x, y]
+ */
+export interface CubicSegment {
+    readonly type: "C";
+    readonly cp1: SVGPointTuple;
+    readonly cp2: SVGPointTuple;
+    readonly end: SVGPointTuple;
+}
+/**
+ * MoveTo segment starting a subpath.
+ */
+export interface MoveSegment {
+    readonly type: "M";
+    readonly point: SVGPointTuple;
+}
+/**
+ * ClosePath segment closing the current subpath.
+ */
+export interface CloseSegment {
+    readonly type: "Z";
+}
+/**
+ * A canonical segment is either M, C, or Z.
+ */
+export type CanonicalSegment = MoveSegment | CubicSegment | CloseSegment;
+/**
+ * A subpath is a sequence of canonical segments beginning with M.
+ */
+export interface CanonicalSubpath {
+    readonly segments: readonly CanonicalSegment[];
+    readonly isClosed: boolean;
+    readonly totalLength?: number;
+}
+/**
+ * Fully normalized SVG path composed of canonical subpaths.
+ */
+export interface NormalizedPath {
+    readonly subpaths: readonly CanonicalSubpath[];
+    readonly totalSegments: number;
+}
+/**
+ * Options for path normalization and segment alignment.
+ */
+export interface NormalizeOptions {
+    /** Maximum number of segments to subdivide to (if aligning paths). */
+    readonly targetSegmentCount?: number;
+    /** Whether to align closed path start points to minimize morph rotation distance. Defaults to true. */
+    readonly alignStartPoints?: boolean;
+    /** Precision decimals for formatted output. Defaults to 3. */
+    readonly precision?: number;
+}
+/**
+ * Configuration for SVG shape conversion.
+ */
+export interface SVGCircleProps {
+    readonly cx: number;
+    readonly cy: number;
+    readonly r: number;
+}
+export interface SVGRectProps {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly rx?: number;
+    readonly ry?: number;
+}
+export interface SVGEllipseProps {
+    readonly cx: number;
+    readonly cy: number;
+    readonly rx: number;
+    readonly ry: number;
+}
+export interface SVGPolygonProps {
+    readonly points: string | readonly (readonly [number, number])[];
+}
+export interface SVGPolylineProps {
+    readonly points: string | readonly (readonly [number, number])[];
+}
+/**
+ * A compiled morph pairing between two normalized paths.
+ */
+export interface Morph {
+    readonly from: NormalizedPath;
+    readonly to: NormalizedPath;
+    readonly precision: number;
+}
+/**
+ * Options for compiling a morph between two paths.
+ */
+export interface MorphOptions {
+    /** Number of decimal places in interpolated path strings. Defaults to 3. */
+    readonly precision?: number;
+    /** Whether to align closed path start points to minimize morph rotation. Defaults to true. */
+    readonly alignStartPoints?: boolean;
+}
+/**
+ * Options for animating an SVG morph.
+ */
+export interface MorphAnimationOptions extends AnimationOptions {
+    /** Precision decimals in interpolated path string output. Defaults to 3. */
+    readonly precision?: number;
+    /** Whether to align start points on closed shapes. Defaults to true. */
+    readonly alignStartPoints?: boolean;
+    /** Custom progress update callback receiving interpolated path string and progress. */
+    readonly onProgress?: (pathData: string, progress: number) => void;
+}
+/**
+ * Controls for managing active SVG morph animations.
+ */
+export interface MorphAnimationControls extends AnimationControls {
+    /** Interpolates and applies a specific progress value (0 to 1). */
+    interpolate(progress: number): string;
+    /** Cancels the animation and optionally restores the original path. */
+    destroy(restoreOriginal?: boolean): void;
+}

package/dist/core/transform.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sets one effect's contribution to an element's transform. Contributions from different
+ * owners are composed in insertion order after the element's original transform, so effects
+ * sharing an element neither overwrite nor wipe each other. An empty value keeps the layer
+ * registered but contributes nothing.
+ */
+export declare function setTransformLayer(element: HTMLElement, owner: object, value: string): void;
+export declare function getTransformBase(element: HTMLElement): {
+    value: string | null;
+    priority: string;
+};
+export declare function setTransformBase(element: HTMLElement, value: string | null, priority?: string): void;
+/**
+ * Removes an owner's contribution. When the last layer is removed the original inline
+ * transform is restored exactly (or the property removed if there was none).
+ */
+export declare function removeTransformLayer(element: HTMLElement, owner: object): void;
+/**
+ * Prepares a container element for overlay effects (e.g. borderBeam, ripple, shine, spotlight),
+ * ensuring relative positioning and isolation without clobbering other active effects on the container.
+ */
+export declare function acquireEffectTarget(element: HTMLElement): void;
+/**
+ * Releases a container element acquired by an overlay effect. Styles are restored only once
+ * all overlay effects sharing the element have been released.
+ */
+export declare function releaseEffectTarget(element: HTMLElement): void;

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

@@ -0,0 +1,45 @@
+/**
+ * AF Motion Transition Controller
+ *
+ * Framework-independent transition orchestration: state tracking, enter/exit
+ * sequencing, interruption resolution, cleanup, and reduced-motion handling.
+ */
+import type { AnimationControls } from "../animation.js";
+import type { TransitionConfig, TransitionState } from "./types.js";
+export interface TransitionControllerOptions {
+    readonly enterConfig?: TransitionConfig;
+    readonly exitConfig?: TransitionConfig;
+    readonly onStateChange?: (state: TransitionState) => void;
+    readonly onEntered?: () => void;
+    readonly onExited?: () => void;
+}
+export declare class TransitionController {
+    private state;
+    private currentControls;
+    private readonly enterDef;
+    private readonly exitDef;
+    private readonly options;
+    constructor(options?: TransitionControllerOptions);
+    getState(): TransitionState;
+    private setState;
+    /**
+     * Executes the entrance animation on a target element.
+     */
+    enter(target: HTMLElement | SVGElement, callbacks?: {
+        onComplete?: () => void;
+    }): AnimationControls | null;
+    /**
+     * Executes the exit animation on a target element.
+     */
+    exit(target: HTMLElement | SVGElement, callbacks?: {
+        onComplete?: () => void;
+    }): AnimationControls | null;
+    /**
+     * Cancels any currently executing transition.
+     */
+    cancel(): void;
+    /**
+     * Cleans up all resources and active animations.
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * AF Motion Automatic Transition Engine
+ *
+ * Deterministic generation of entrance, exit, and page transitions with
+ * direction awareness, shared-element movement, and intelligence-guided timing.
+ */
+import type { AnimatableProperties } from "../animate.js";
+import type { PageTransitionConfig, PageTransitionDefinition, TransitionConfig, TransitionDefinition, TransitionPattern } from "./types.js";
+/**
+ * Generates animatable properties for an entrance or exit transition.
+ */
+export declare function generateTransitionProperties(pattern: TransitionPattern, type: "enter" | "exit", config?: TransitionConfig): AnimatableProperties;
+/**
+ * Creates an entrance transition definition.
+ */
+export declare function createEntranceTransition(config?: TransitionConfig): TransitionDefinition;
+/**
+ * Creates an exit transition definition.
+ */
+export declare function createExitTransition(config?: TransitionConfig): TransitionDefinition;
+/**
+ * Creates a coordinated enter/exit page transition definition.
+ */
+export declare function createPageTransition(config?: PageTransitionConfig, navContext?: {
+    direction?: "forward" | "backward";
+}): PageTransitionDefinition;

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

@@ -0,0 +1,30 @@
+/**
+ * AF Motion Shared Element Group & Nested Transitions
+ *
+ * Coordinated transitions across multiple shared elements with staggered timing,
+ * parent-child hierarchy compensation, and unified playback controls.
+ */
+import type { SharedElementGroupController, SharedElementGroupItem, SharedElementGroupOptions, SharedElementTransitionState } from "./types.js";
+export declare class SharedElementGroupTransitionImpl implements SharedElementGroupController {
+    private _state;
+    private _progress;
+    private _isPlaying;
+    private controllers;
+    private readonly options;
+    constructor(items: SharedElementGroupItem[], options?: SharedElementGroupOptions);
+    get state(): SharedElementTransitionState;
+    get progress(): number;
+    get isPlaying(): boolean;
+    getState(): SharedElementTransitionState;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    seek(progress: number): void;
+    cancel(): void;
+    finish(): void;
+}
+/**
+ * Creates a synchronized transition controller for a group of shared elements.
+ */
+export declare function createSharedElementGroupTransition(items: SharedElementGroupItem[], options?: SharedElementGroupOptions): SharedElementGroupController;

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

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Automatic Transitions & Shared Element Module
+ *
+ * Entrance, exit, page-transition, shared-element FLIP motion, group coordination,
+ * view transition orchestration, and browser-native View Transition integration.
+ */
+export * from "./types.js";
+export * from "./shared-element.js";
+export * from "./shared-element-transition.js";
+export * from "./view-transition.js";
+export * from "./group-transition.js";
+export * from "./presets.js";
+export * from "./engine.js";
+export * from "./controller.js";
+export * from "./schema.js";

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

@@ -0,0 +1,16 @@
+/**
+ * AF Motion View Transition Presets
+ *
+ * Configurable presets for full-view and shared-element transitions:
+ * fade, crossfade, slide, scale, zoom, reveal, clip-path, directional-nav, and SVG morph.
+ */
+import type { ViewTransitionOptions, ViewTransitionPresetName } from "./types.js";
+export declare const VIEW_TRANSITION_PRESETS: Record<ViewTransitionPresetName, ViewTransitionOptions>;
+/**
+ * Returns a configured ViewTransitionOptions object from preset name with optional overrides.
+ */
+export declare function getViewTransitionPreset(name: ViewTransitionPresetName, overrides?: Partial<ViewTransitionOptions>): ViewTransitionOptions;
+/**
+ * Lists all registered view transition preset names.
+ */
+export declare function listAvailableViewTransitionPresets(): ViewTransitionPresetName[];

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

@@ -0,0 +1,71 @@
+/**
+ * AF Motion Transitions Schema & AI Motion Registry Integration
+ *
+ * Machine-readable capability definitions and discovery helpers for
+ * automatic entrance, exit, and page transitions.
+ */
+import { type TransitionDirection, type TransitionMode, type TransitionPattern } from "./types.js";
+export declare const AUTOMATIC_TRANSITION_CAPABILITY: {
+    id: string;
+    name: string;
+    category: "transition";
+    description: string;
+    tags: string[];
+    version: string;
+    parameters: {
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    }[];
+    supportedTargets: string[];
+    signature: {
+        importStatement: string;
+        invocation: string;
+        exampleCode: string;
+    };
+    controls: string[];
+    callbacks: string[];
+    reducedMotion: "static-fallback";
+    compatibility: {
+        browser: boolean;
+        ssr: boolean;
+        requiresCanvas: boolean;
+    };
+};
+export declare const PAGE_TRANSITION_CAPABILITY: {
+    id: string;
+    name: string;
+    category: "transition";
+    description: string;
+    tags: string[];
+    version: string;
+    parameters: {
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    }[];
+    supportedTargets: string[];
+    signature: {
+        importStatement: string;
+        invocation: string;
+        exampleCode: string;
+    };
+    controls: string[];
+    callbacks: never[];
+    reducedMotion: "static-fallback";
+    compatibility: {
+        browser: boolean;
+        ssr: boolean;
+        requiresCanvas: boolean;
+    };
+};
+export declare function getAvailableTransitionPatterns(): readonly TransitionPattern[];
+export declare function getAvailableTransitionDirections(): readonly TransitionDirection[];
+export declare function getAvailableTransitionModes(): readonly TransitionMode[];
+export declare function registerTransitionCapabilities(registry: {
+    registerCapability: (cap: any, opts?: any) => void;
+}): void;

package/dist/core/transitions/shared-element-transition.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AF Motion Shared Element Transition Controller & Engine
+ *
+ * FLIP-based geometry interpolation, crossfading, border-radius blending,
+ * interruption handling, nested compensation, and RAF-driven lifecycle control.
+ */
+import type { CreateSharedElementTransitionOptions, SharedElementRect, SharedElementTransitionController, SharedElementTransitionState } from "./types.js";
+export declare class SharedElementTransitionImpl implements SharedElementTransitionController {
+    private _state;
+    private _progress;
+    private _isPlaying;
+    private animControls;
+    private readonly layerOwner;
+    private readonly id;
+    private readonly config;
+    private readonly registry;
+    private sourceEl;
+    private destEl;
+    private sourceSnapshot;
+    private sourceRect;
+    private destRect;
+    private deltaX;
+    private deltaY;
+    private scaleX;
+    private scaleY;
+    private startRadius;
+    private targetRadius;
+    private initialDestStyles;
+    private cloneOverlay;
+    private resolveStartPromise;
+    constructor(options?: CreateSharedElementTransitionOptions);
+    get state(): SharedElementTransitionState;
+    get progress(): number;
+    get isPlaying(): boolean;
+    getState(): SharedElementTransitionState;
+    /**
+     * Prepares and measures elements for the FLIP transition.
+     */
+    private measure;
+    /**
+     * Applies the initial inverted FLIP state before painting.
+     */
+    private applyInitialFLIP;
+    /**
+     * Applies interpolated position, scale, opacity, and border radius at given progress (0 to 1).
+     */
+    private applyProgress;
+    /**
+     * Cleans up all inline styles, transform layers, and clone overlays.
+     */
+    private cleanup;
+    /**
+     * Starts the shared element transition.
+     */
+    start(): Promise<void>;
+    /**
+     * Pauses the transition mid-flight.
+     */
+    pause(): void;
+    /**
+     * Resumes a paused transition.
+     */
+    resume(): void;
+    /**
+     * Reverses the transition direction back toward the source pose.
+     */
+    reverse(): void;
+    /**
+     * Seeks immediately to a normalized progress value (0 to 1).
+     */
+    seek(progress: number): void;
+    /**
+     * Cancels the transition immediately and resets element to initial state.
+     */
+    cancel(): void;
+    /**
+     * Fast-forwards the transition to the finished state (progress 1).
+     */
+    finish(): void;
+    /**
+     * Smoothly retargets an ongoing transition to a new destination rect or element.
+     */
+    retarget(newDestination: HTMLElement | SharedElementRect): void;
+}
+/**
+ * Creates a shared element transition controller between source and destination elements.
+ */
+export declare function createSharedElementTransition(options?: CreateSharedElementTransitionOptions): SharedElementTransitionController;

package/dist/core/transitions/shared-element.d.ts

@@ -0,0 +1,84 @@
+/**
+ * AF Motion Shared Element Transition Engine
+ *
+ * Lightweight, framework-independent registry and FLIP layout delta solver
+ * for seamless shared-element movement between views, cards, modals, and pages.
+ */
+import type { AnimatableProperties } from "../animate.js";
+import type { SharedElementRect, SharedElementRegistrationOptions, SharedElementRole, SharedElementSnapshot } from "./types.js";
+export declare class SharedElementRegistry {
+    private readonly elements;
+    private readonly sources;
+    private readonly destinations;
+    private readonly optionsMap;
+    private readonly capturedRects;
+    private readonly snapshots;
+    /**
+     * Registers an active DOM element under a shared-element ID with optional role and hierarchy metadata.
+     */
+    register(id: string, element: HTMLElement, options?: SharedElementRegistrationOptions): void;
+    /**
+     * Unregisters a shared-element ID (or specific role).
+     */
+    unregister(id: string, role?: SharedElementRole): void;
+    /**
+     * Captures and stores the current bounding client rect for a shared element.
+     * Backward-compatible with Prompt 83 API.
+     */
+    captureRect(id: string, rect?: SharedElementRect): SharedElementRect | null;
+    /**
+     * Captures a rich snapshot including geometry, computed styles, and parent relationship.
+     */
+    capture(id: string, role?: SharedElementRole, rect?: SharedElementRect): SharedElementSnapshot | null;
+    /**
+     * Captures snapshots for all registered elements.
+     */
+    captureAll(role?: SharedElementRole): Map<string, SharedElementSnapshot>;
+    /**
+     * Retrieves the last captured bounding rect for an element.
+     */
+    getCapturedRect(id: string): SharedElementRect | null;
+    /**
+     * Retrieves the last captured snapshot for an element.
+     */
+    getSnapshot(id: string, role?: SharedElementRole): SharedElementSnapshot | null;
+    /**
+     * Retrieves the live DOM element registered under an ID and optional role.
+     */
+    getElement(id: string, role?: SharedElementRole): HTMLElement | null;
+    /**
+     * Returns matching source and destination elements or snapshots for a given ID.
+     */
+    getMatch(id: string): {
+        source: HTMLElement | SharedElementSnapshot | null;
+        destination: HTMLElement | SharedElementSnapshot | null;
+    };
+    /**
+     * Checks whether an ID is registered.
+     */
+    has(id: string, role?: SharedElementRole): boolean;
+    /**
+     * Returns parent shared-element ID if nested.
+     */
+    getNestedUnder(id: string): string | undefined;
+    /**
+     * Computes FLIP inverse transform properties from sourceRect to targetRect.
+     */
+    computeTransform(sourceRect: SharedElementRect, targetRect: SharedElementRect): AnimatableProperties;
+    /**
+     * Clears all stored element references and captured geometry.
+     */
+    clear(): void;
+}
+/**
+ * Creates an independent SharedElementRegistry instance.
+ */
+export declare function createSharedElementRegistry(): SharedElementRegistry;
+/**
+ * Default global SharedElementRegistry singleton.
+ */
+export declare const sharedElementRegistry: SharedElementRegistry;
+/**
+ * Helper to register a shared element in the global registry.
+ */
+export declare function registerSharedElement(id: string, element: HTMLElement, options?: SharedElementRegistrationOptions): () => void;