@flightdev/transitions 0.2.0

package/dist/types-BA4L37s4.d.ts

@@ -0,0 +1,272 @@
+/**
+ * @flightdev/transitions - Core Types
+ *
+ * Type definitions for the Flight Transitions system.
+ * Following 2026 best practices with strict TypeScript.
+ */
+/**
+ * Native ViewTransition interface (matches browser API)
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition
+ */
+interface ViewTransition {
+    /** Promise that resolves when the DOM update callback completes */
+    readonly updateCallbackDone: Promise<void>;
+    /** Promise that resolves when pseudo-element tree is ready to animate */
+    readonly ready: Promise<void>;
+    /** Promise that resolves when animation completes and new view is interactive */
+    readonly finished: Promise<void>;
+    /** Skip the transition animation */
+    skipTransition(): void;
+}
+/**
+ * Options for starting a view transition
+ */
+interface ViewTransitionOptions {
+    /** Unique name for CSS targeting via view-transition-name */
+    name?: string;
+    /** Skip the transition entirely (instant swap) */
+    skipTransition?: boolean;
+    /** Custom CSS classes applied during transition phases */
+    classes?: {
+        /** Class added to old (leaving) snapshot */
+        old?: string;
+        /** Class added to new (entering) snapshot */
+        new?: string;
+    };
+    /** Types for the transition (used with @view-transition types) */
+    types?: string[];
+}
+/**
+ * Result from startViewTransition wrapper
+ */
+interface ViewTransitionResult {
+    /** Promise resolving when ready to animate */
+    readonly ready: Promise<void>;
+    /** Promise resolving when animation finishes */
+    readonly finished: Promise<void>;
+    /** Promise resolving when DOM update callback completes */
+    readonly updateCallbackDone: Promise<void>;
+    /** Skip the remaining animation */
+    skipTransition(): void;
+    /** Whether native API was used */
+    readonly isNative: boolean;
+}
+/** Built-in transition preset names */
+type TransitionPreset = 'fade' | 'fade-scale' | 'slide-left' | 'slide-right' | 'slide-up' | 'slide-down' | 'scale' | 'scale-fade' | 'morph' | 'flip' | 'none';
+/** Direction for directional transitions */
+type TransitionDirection = 'forward' | 'back' | 'auto';
+/** CSS properties that can be animated */
+type AnimatableProperty = 'opacity' | 'transform' | 'clip-path' | 'filter' | 'background-color' | 'color' | string;
+/**
+ * Keyframe definition for a transition phase
+ */
+interface TransitionKeyframe {
+    /** Starting CSS values */
+    from: Partial<Record<AnimatableProperty, string>>;
+    /** Ending CSS values */
+    to: Partial<Record<AnimatableProperty, string>>;
+}
+/**
+ * Custom transition definition
+ */
+interface CustomTransition {
+    /** Name identifier for the transition */
+    name?: string;
+    /** Animation for the leaving element */
+    leave?: TransitionKeyframe;
+    /** Animation for the entering element */
+    enter?: TransitionKeyframe;
+    /** Duration in milliseconds */
+    duration?: number | {
+        leave?: number;
+        enter?: number;
+    };
+    /** Easing function(s) */
+    easing?: string | {
+        leave?: string;
+        enter?: string;
+    };
+    /** Delay before animation starts */
+    delay?: number | {
+        leave?: number;
+        enter?: number;
+    };
+    /** CSS fill mode */
+    fill?: FillMode;
+}
+/** Animation fill mode */
+type FillMode = 'none' | 'forwards' | 'backwards' | 'both';
+/**
+ * Resolved transition (preset or custom normalized to common format)
+ */
+interface ResolvedTransition {
+    name: string;
+    leave: {
+        keyframes: Keyframe[];
+        options: KeyframeAnimationOptions;
+    };
+    enter: {
+        keyframes: Keyframe[];
+        options: KeyframeAnimationOptions;
+    };
+}
+/**
+ * Configuration for page-level transitions
+ */
+interface PageTransitionConfig {
+    /** Default transition for all navigations */
+    default?: TransitionPreset | CustomTransition | false;
+    /** Transition for back navigation (overrides default) */
+    backTransition?: TransitionPreset | CustomTransition | false;
+    /** Duration override */
+    duration?: number;
+    /** Easing override */
+    easing?: string;
+    /** How to handle prefers-reduced-motion */
+    reduceMotion?: ReduceMotionBehavior;
+    /** Callback before transition starts */
+    onStart?: (context: TransitionContext) => void;
+    /** Callback after transition completes */
+    onComplete?: (context: TransitionContext) => void;
+}
+/** Behavior for users with reduced motion preference */
+type ReduceMotionBehavior = 'respect-system' | 'always-reduce' | 'ignore';
+/**
+ * Context passed to transition callbacks
+ */
+interface TransitionContext {
+    /** The URL being navigated from */
+    from: string;
+    /** The URL being navigated to */
+    to: string;
+    /** Navigation direction */
+    direction: TransitionDirection;
+    /** The transition being used */
+    transition: ResolvedTransition;
+    /** Timestamp when transition started */
+    startTime: number;
+}
+/**
+ * Configuration for layout-level transitions
+ */
+interface LayoutTransitionConfig {
+    /** Default layout transition */
+    default?: TransitionPreset | CustomTransition | false;
+    /** Whether layout persists during page transitions */
+    persist?: boolean;
+    /** Shared elements configuration */
+    sharedElements?: SharedElementConfig[];
+}
+/**
+ * Shared element transition configuration
+ */
+interface SharedElementConfig {
+    /** Unique identifier matching elements across pages */
+    name: string;
+    /** Animation type for the shared element */
+    animation?: 'morph' | 'crossfade' | 'none';
+    /** Duration for the shared element animation */
+    duration?: number;
+    /** Easing for the shared element animation */
+    easing?: string;
+}
+/**
+ * Props for component-level transitions
+ */
+interface TransitionProps {
+    /** Whether the child should be shown */
+    show?: boolean;
+    /** Transition type */
+    type?: TransitionPreset | CustomTransition;
+    /** Duration override */
+    duration?: number;
+    /** Appear on initial mount */
+    appear?: boolean;
+    /** Mode for enter/leave sequencing */
+    mode?: 'in-out' | 'out-in' | 'simultaneous';
+    /** Callback when enter transition starts */
+    onEnterStart?: () => void;
+    /** Callback when enter transition completes */
+    onEnterComplete?: () => void;
+    /** Callback when leave transition starts */
+    onLeaveStart?: () => void;
+    /** Callback when leave transition completes */
+    onLeaveComplete?: () => void;
+}
+/**
+ * Props for transition groups (list animations)
+ */
+interface TransitionGroupProps {
+    /** Tag to render as container */
+    as?: keyof HTMLElementTagNameMap;
+    /** Transition for items */
+    type?: TransitionPreset | CustomTransition;
+    /** Duration for each item */
+    duration?: number;
+    /** Stagger delay between items */
+    stagger?: number;
+    /** Whether to animate on initial render */
+    appear?: boolean;
+}
+/**
+ * Global transitions configuration (for flight.config.ts)
+ */
+interface TransitionsConfig {
+    /** Enable transitions globally */
+    enabled?: boolean;
+    /** Use native View Transitions API when available */
+    viewTransitions?: boolean;
+    /** Default page transition */
+    pageTransition?: TransitionPreset | CustomTransition | false;
+    /** Default layout transition */
+    layoutTransition?: TransitionPreset | CustomTransition | false;
+    /** Global duration default */
+    duration?: number;
+    /** Global easing default */
+    easing?: string;
+    /** Reduced motion behavior */
+    reduceMotion?: ReduceMotionBehavior;
+    /** Enable cross-document (MPA) transitions */
+    crossDocument?: boolean;
+}
+/**
+ * Internal transition state
+ */
+interface TransitionState {
+    isTransitioning: boolean;
+    direction: TransitionDirection;
+    phase: 'idle' | 'leaving' | 'entering' | 'complete';
+    currentTransition: ResolvedTransition | null;
+    fromPath: string | null;
+    toPath: string | null;
+}
+/** Listener for transition state changes */
+type TransitionListener = (state: TransitionState) => void;
+/** Extract the resolved transition type from preset or custom */
+type TransitionInput = TransitionPreset | CustomTransition | false;
+/** Navigation options extended with transition support */
+interface NavigateWithTransitionOptions {
+    /** Replace current history entry */
+    replace?: boolean;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** State to pass to new route */
+    state?: Record<string, unknown>;
+    /** Transition to use (overrides page default) */
+    transition?: TransitionInput;
+    /** Force transition even if globally disabled */
+    forceTransition?: boolean;
+}
+/** Link props extended with transition support */
+interface LinkWithTransitionProps {
+    /** Target URL */
+    href: string;
+    /** Transition for this link */
+    transition?: TransitionInput;
+    /** Prefetch transition assets on hover */
+    prefetchTransition?: boolean;
+    /** Replace instead of push */
+    replace?: boolean;
+}
+
+export type { AnimatableProperty as A, CustomTransition as C, FillMode as F, LayoutTransitionConfig as L, NavigateWithTransitionOptions as N, PageTransitionConfig as P, ResolvedTransition as R, SharedElementConfig as S, TransitionPreset as T, ViewTransition as V, ViewTransitionOptions as a, ViewTransitionResult as b, TransitionDirection as c, TransitionKeyframe as d, ReduceMotionBehavior as e, TransitionContext as f, TransitionProps as g, TransitionGroupProps as h, TransitionsConfig as i, TransitionState as j, TransitionListener as k, TransitionInput as l, LinkWithTransitionProps as m };

package/dist/view-transition-LSN_PSbm.d.ts

@@ -0,0 +1,97 @@
+import { V as ViewTransition, a as ViewTransitionOptions, b as ViewTransitionResult } from './types-BA4L37s4.js';
+
+/**
+ * @flightdev/transitions - View Transition API Wrapper
+ *
+ * Provides a cross-browser wrapper for the View Transitions API with
+ * automatic fallback for unsupported browsers.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+ */
+
+/**
+ * Check if the browser supports the View Transitions API
+ * @returns true if startViewTransition is available
+ */
+declare function isViewTransitionSupported(): boolean;
+/**
+ * Check if cross-document view transitions are supported
+ * @returns true if @view-transition CSS at-rule is supported
+ */
+declare function isCrossDocumentTransitionSupported(): boolean;
+/**
+ * Start a view transition with automatic fallback
+ *
+ * Uses the native View Transitions API when available, otherwise
+ * provides a compatible fallback that executes the callback immediately.
+ *
+ * @example
+ * ```typescript
+ * const transition = startViewTransition(() => {
+ *   // Update the DOM
+ *   document.getElementById('content').innerHTML = newContent;
+ * });
+ *
+ * // Wait for animation to be ready
+ * await transition.ready;
+ *
+ * // Wait for animation to complete
+ * await transition.finished;
+ * ```
+ */
+declare function startViewTransition(updateCallback: () => void | Promise<void>, options?: ViewTransitionOptions): ViewTransitionResult;
+/**
+ * Options for cross-document (MPA) transitions
+ */
+interface CrossDocumentTransitionOptions {
+    /** Enable transitions for same-origin navigations */
+    enabled?: boolean;
+    /** Types to apply to the transition */
+    types?: string[];
+}
+/**
+ * Enable cross-document view transitions for MPA navigations
+ *
+ * This injects the necessary CSS and sets up event listeners for
+ * pagereveal and pageswap events.
+ *
+ * @example
+ * ```typescript
+ * enableCrossDocumentTransitions({
+ *   enabled: true,
+ *   types: ['slide-left']
+ * });
+ * ```
+ */
+declare function enableCrossDocumentTransitions(options?: CrossDocumentTransitionOptions): () => void;
+interface PageRevealEvent extends Event {
+    readonly viewTransition: ViewTransition | null;
+}
+interface PageSwapEvent extends Event {
+    readonly viewTransition: ViewTransition | null;
+    readonly activation: NavigationActivation | null;
+}
+interface NavigationActivation {
+    readonly entry: NavigationHistoryEntry;
+    readonly from: NavigationHistoryEntry | null;
+    readonly navigationType: NavigationHistoryEntryType;
+}
+interface NavigationHistoryEntry {
+    readonly id: string;
+    readonly index: number;
+    readonly key: string;
+    readonly sameDocument: boolean;
+    readonly url: string | null;
+}
+type NavigationHistoryEntryType = 'push' | 'replace' | 'reload' | 'traverse';
+declare global {
+    interface Document {
+        startViewTransition(callback: () => void | Promise<void>): ViewTransition;
+    }
+    interface WindowEventMap {
+        pagereveal: PageRevealEvent;
+        pageswap: PageSwapEvent;
+    }
+}
+
+export { type CrossDocumentTransitionOptions as C, isCrossDocumentTransitionSupported as a, enableCrossDocumentTransitions as e, isViewTransitionSupported as i, startViewTransition as s };

package/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "@flightdev/transitions",
+  "version": "0.2.0",
+  "description": "Smooth page, layout, and component transitions for Flight Framework",
+  "keywords": [
+    "flight",
+    "transitions",
+    "view-transitions",
+    "animation",
+    "page-transition",
+    "layout-transition"
+  ],
+  "license": "MIT",
+  "author": "Flight Contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./page": {
+      "types": "./dist/page/index.d.ts",
+      "import": "./dist/page/index.js"
+    },
+    "./layout": {
+      "types": "./dist/layout/index.d.ts",
+      "import": "./dist/layout/index.js"
+    },
+    "./component": {
+      "types": "./dist/component/index.d.ts",
+      "import": "./dist/component/index.js"
+    },
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "import": "./dist/presets/index.js"
+    },
+    "./css": "./dist/css/transitions.css",
+    "./css/view-transitions": "./dist/css/view-transitions.css",
+    "./react": {
+      "types": "./dist/adapters/react/index.d.ts",
+      "import": "./dist/adapters/react/index.js"
+    },
+    "./vue": {
+      "types": "./dist/adapters/vue/index.d.ts",
+      "import": "./dist/adapters/vue/index.js"
+    },
+    "./svelte": {
+      "types": "./dist/adapters/svelte/index.d.ts",
+      "import": "./dist/adapters/svelte/index.js"
+    },
+    "./solid": {
+      "types": "./dist/adapters/solid/index.d.ts",
+      "import": "./dist/adapters/solid/index.js"
+    },
+    "./router": {
+      "types": "./dist/router/index.d.ts",
+      "import": "./dist/router/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./qwik": {
+      "types": "./dist/adapters/qwik/index.d.ts",
+      "import": "./dist/adapters/qwik/index.js"
+    },
+    "./angular": {
+      "types": "./dist/adapters/angular/index.d.ts",
+      "import": "./dist/adapters/angular/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@angular/animations": "^21.0.8",
+    "@angular/common": "^21.0.8",
+    "@angular/core": "^21.0.8",
+    "@angular/platform-browser": "^21.0.8",
+    "@angular/router": "^21.0.8",
+    "@builder.io/qwik": "^1.18.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@angular/animations": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "@angular/platform-browser": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "@angular/router": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "@builder.io/qwik": "^1.0.0 || ^2.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "solid-js": "^1.0.0",
+    "svelte": "^4.0.0 || ^5.0.0",
+    "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "@builder.io/qwik": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@angular/common": {
+      "optional": true
+    },
+    "@angular/platform-browser": {
+      "optional": true
+    },
+    "@angular/animations": {
+      "optional": true
+    },
+    "@angular/router": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "clean": "rimraf dist"
+  }
+}