@capgo/capacitor-transitions 8.0.1

package/dist/react/index.d.mts

@@ -0,0 +1,400 @@
+/**
+ * Core types for @capgo/capacitor-transitions
+ * Framework-agnostic page transitions for Capacitor apps
+ */
+/** Direction of the navigation transition */
+type TransitionDirection = 'forward' | 'back' | 'root' | 'none';
+/** Platform-specific animation styles */
+type TransitionPlatform = 'ios' | 'android' | 'auto';
+/** Whether the edge swipe-back gesture is enabled, disabled, or native-detected */
+type SwipeGestureOption = boolean | 'auto';
+/** Which parts of the page to animate */
+type TransitionTarget = 'header' | 'content' | 'footer' | 'all';
+/** Animation easing presets */
+type TransitionEasing = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ios' | 'android' | string;
+/** Configuration for a single transition animation */
+interface TransitionConfig {
+    /** Duration in milliseconds (default: 540 for iOS, 280/200 for Android forward/back) */
+    duration?: number;
+    /** Easing function (default: 'ios' or 'android' based on platform) */
+    easing?: TransitionEasing;
+    /** Direction of transition */
+    direction?: TransitionDirection;
+    /** Which elements to animate (default: 'all') */
+    targets?: TransitionTarget[];
+    /** Custom animation keyframes for entering element */
+    enterKeyframes?: Keyframe[];
+    /** Custom animation keyframes for leaving element */
+    leaveKeyframes?: Keyframe[];
+    /** Callback before animation starts */
+    onStart?: () => void;
+    /** Callback after animation completes */
+    onComplete?: () => void;
+    /** Whether to use View Transitions API when available (default: false) */
+    useViewTransitions?: boolean;
+}
+/** Resolved platform type (excludes 'auto') */
+type ResolvedPlatform = 'ios' | 'android';
+/** Global configuration for the transition system */
+interface TransitionGlobalConfig {
+    /** Default platform style (default: 'auto') */
+    platform?: TransitionPlatform;
+    /** Default duration in ms */
+    duration?: number;
+    /** Default easing */
+    easing?: TransitionEasing;
+    /** Whether to use View Transitions API (default: false) */
+    useViewTransitions?: boolean;
+    /** Custom platform detection function */
+    detectPlatform?: () => ResolvedPlatform;
+}
+/** State of a page in the navigation stack */
+interface PageState {
+    /** Unique identifier for the page */
+    id: string;
+    /** The page element */
+    element: HTMLElement;
+    /** Header element if present */
+    header?: HTMLElement;
+    /** Content element if present */
+    content?: HTMLElement;
+    /** Footer element if present */
+    footer?: HTMLElement;
+    /** Whether this page is currently visible */
+    isActive: boolean;
+    /** Scroll position to restore */
+    scrollPosition?: {
+        x: number;
+        y: number;
+    };
+    /** Any custom data attached to this page */
+    data?: Record<string, unknown>;
+}
+/** Navigation event details */
+interface NavigationEvent {
+    /** Direction of navigation */
+    direction: TransitionDirection;
+    /** Page being navigated from */
+    from?: PageState;
+    /** Page being navigated to */
+    to: PageState;
+    /** Whether animation should be skipped */
+    skipAnimation?: boolean;
+}
+/** Lifecycle hooks for page transitions */
+interface TransitionLifecycle {
+    /** Called before the page becomes visible (before animation) */
+    onWillEnter?: (event: NavigationEvent) => void | Promise<void>;
+    /** Called after the page becomes visible (after animation) */
+    onDidEnter?: (event: NavigationEvent) => void | Promise<void>;
+    /** Called before the page leaves (before animation) */
+    onWillLeave?: (event: NavigationEvent) => void | Promise<void>;
+    /** Called after the page leaves (after animation) */
+    onDidLeave?: (event: NavigationEvent) => void | Promise<void>;
+}
+/** Result of a transition animation */
+interface TransitionResult {
+    /** Whether the transition completed successfully */
+    success: boolean;
+    /** Duration of the transition in ms */
+    duration: number;
+    /** Any error that occurred */
+    error?: Error;
+}
+
+/**
+ * Transition Controller
+ * Orchestrates page transitions and manages the navigation stack
+ */
+
+/**
+ * Transition Controller
+ * Central manager for all page transitions
+ */
+declare class TransitionController {
+    private config;
+    private pageStack;
+    private currentAnimations;
+    private isAnimating;
+    private interactiveBackTransition;
+    private lifecycleCallbacks;
+    constructor(config?: TransitionGlobalConfig);
+    /**
+     * Get the resolved platform
+     */
+    get platform(): 'ios' | 'android';
+    /**
+     * Get the current page state
+     */
+    get currentPage(): PageState | undefined;
+    /**
+     * Get the page stack
+     */
+    get stack(): readonly PageState[];
+    /**
+     * Check if an animation is in progress
+     */
+    get animating(): boolean;
+    /**
+     * Update global configuration
+     */
+    configure(config: Partial<TransitionGlobalConfig>): void;
+    /**
+     * Register lifecycle callbacks for a page
+     */
+    registerLifecycle(pageId: string, lifecycle: TransitionLifecycle): void;
+    /**
+     * Unregister lifecycle callbacks for a page
+     */
+    unregisterLifecycle(pageId: string): void;
+    /**
+     * Create a page state from an element
+     */
+    createPageState(element: HTMLElement, options?: {
+        id?: string;
+        data?: Record<string, unknown>;
+    }): PageState;
+    /**
+     * Navigate to a new page (push)
+     */
+    push(enteringEl: HTMLElement, config?: TransitionConfig): Promise<TransitionResult>;
+    /**
+     * Navigate back (pop)
+     */
+    pop(config?: TransitionConfig): Promise<TransitionResult>;
+    /**
+     * Start an interactive iOS-style back transition using the cached previous page.
+     */
+    beginInteractiveBack(config?: TransitionConfig): boolean;
+    /**
+     * Move the current interactive back transition to a progress step from 0 to 1.
+     */
+    stepInteractiveBack(step: number): void;
+    /**
+     * Complete or cancel the current interactive back transition.
+     */
+    endInteractiveBack(shouldComplete: boolean, releaseDuration: number, commitStack: boolean): Promise<void>;
+    /**
+     * Cancel the current interactive back transition immediately.
+     */
+    cancelInteractiveBack(): void;
+    /**
+     * Replace all pages with a new root
+     */
+    setRoot(enteringEl: HTMLElement, config?: TransitionConfig): Promise<TransitionResult>;
+    /**
+     * Main navigation method
+     */
+    navigate(enteringEl: HTMLElement, config?: TransitionConfig): Promise<TransitionResult>;
+    /**
+     * Navigate between two known page states
+     */
+    private navigateWithStates;
+    /**
+     * Update page visibility after animation
+     */
+    private updatePageVisibility;
+    private getAnimationDuration;
+    private playInteractiveAnimationsTo;
+    /**
+     * Resolve configured easing presets after platform/direction are known.
+     */
+    private resolveTransitionEasing;
+    /**
+     * Remove styles that should only exist while a page is actively transitioning.
+     */
+    private clearTransitionOnlyStyles;
+    private clearPagePartTransitionStyles;
+    /**
+     * Prepare entering/leaving elements for a View Transition capture.
+     * Entering page must be hidden in the "old" snapshot.
+     */
+    private prepareViewTransitionElements;
+    /**
+     * Assign view transition names to a page's layout parts.
+     */
+    private applyViewTransitionNames;
+    /**
+     * Clear view transition names for one or more page states.
+     */
+    private clearViewTransitionNames;
+    /**
+     * Clear view transition names from all known pages plus transient states.
+     */
+    private clearAllKnownViewTransitionNames;
+    /**
+     * Resolve page parts lazily to avoid timing issues with custom-element setup.
+     */
+    private resolvePageParts;
+    /**
+     * Save scroll position for a page
+     */
+    saveScrollPosition(pageId: string): void;
+    /**
+     * Restore scroll position for a page
+     */
+    restoreScrollPosition(pageId: string): void;
+    /**
+     * Remove a page from the stack (used when cleaning up)
+     */
+    removePage(pageId: string): void;
+    /**
+     * Clear all pages
+     */
+    clear(): void;
+}
+
+/**
+ * React bindings for @capgo/capacitor-transitions
+ * Helper functions for using web components in React
+ */
+
+/**
+ * Initialize the transition system
+ */
+declare function initTransitions(config?: TransitionGlobalConfig): TransitionController;
+/**
+ * Get the global transition controller
+ */
+declare function getController(): TransitionController;
+/**
+ * Get/set the current transition direction
+ */
+declare function getDirection(): TransitionDirection;
+declare function setDirection(direction: TransitionDirection): void;
+/**
+ * Set up a router outlet element
+ * Call this in useEffect with a ref to the cap-router-outlet element
+ */
+declare function setupRouterOutlet(element: HTMLElement, options?: {
+    keepInDom?: boolean;
+    maxCached?: number;
+    platform?: 'ios' | 'android' | 'auto';
+    duration?: number;
+    swipeGesture?: SwipeGestureOption;
+}): void;
+/**
+ * Set up a page element with lifecycle callbacks
+ * Call this in useEffect with a ref to the cap-page element
+ * Returns a cleanup function to call in the effect cleanup
+ *
+ * @example
+ * ```tsx
+ * function MyPage() {
+ *   const pageRef = useRef<HTMLElement>(null)
+ *
+ *   useEffect(() => {
+ *     if (pageRef.current) {
+ *       return setupPage(pageRef.current, {
+ *         onDidEnter: () => console.log('entered'),
+ *         onDidLeave: () => console.log('left'),
+ *       })
+ *     }
+ *   }, [])
+ *
+ *   return <cap-page ref={pageRef}>...</cap-page>
+ * }
+ * ```
+ */
+declare function setupPage(element: HTMLElement, callbacks?: {
+    onWillEnter?: (event: NavigationEvent) => void;
+    onDidEnter?: (event: NavigationEvent) => void;
+    onWillLeave?: (event: NavigationEvent) => void;
+    onDidLeave?: (event: NavigationEvent) => void;
+}): () => void;
+/**
+ * Create a transition-aware navigate function
+ * Wraps your router's navigate function to set the direction before navigating
+ *
+ * @example
+ * ```tsx
+ * const navigate = useNavigate()
+ * const transitionNavigate = createTransitionNavigate(navigate)
+ *
+ * // Forward navigation
+ * transitionNavigate('/details/1')
+ *
+ * // Back navigation
+ * transitionNavigate('/', 'back')
+ * ```
+ */
+declare function createTransitionNavigate(navigate: (to: string) => void): (to: string, direction?: TransitionDirection) => void;
+
+type CapElementAttributes = {
+    key?: unknown;
+    ref?: unknown;
+    children?: unknown;
+    id?: string;
+    class?: string;
+    className?: string;
+    style?: unknown;
+    slot?: string;
+    role?: string;
+    part?: string;
+    title?: string;
+    tabIndex?: number;
+    [attribute: `data-${string}`]: unknown;
+    [attribute: `aria-${string}`]: unknown;
+    [eventHandler: `on${string}`]: unknown;
+};
+type Booleanish = boolean | 'true' | 'false';
+interface CapTransitionsIntrinsicElements {
+    'cap-router-outlet': CapElementAttributes & {
+        platform?: 'ios' | 'android' | 'auto';
+        duration?: number | string;
+        'keep-in-dom'?: Booleanish;
+        'max-cached'?: number | string;
+        'swipe-gesture'?: boolean | 'true' | 'false' | 'auto';
+    };
+    'cap-page': CapElementAttributes & {
+        'cache-scroll'?: Booleanish;
+        'data-direction'?: 'forward' | 'back' | 'root' | 'none';
+    };
+    'cap-header': CapElementAttributes & {
+        translucent?: Booleanish;
+        collapse?: string;
+    };
+    'cap-content': CapElementAttributes & {
+        fullscreen?: Booleanish;
+        'scroll-x'?: Booleanish;
+        'scroll-y'?: Booleanish;
+    };
+    'cap-footer': CapElementAttributes & {
+        translucent?: Booleanish;
+    };
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'cap-router-outlet': CapTransitionsIntrinsicElements['cap-router-outlet'];
+            'cap-page': CapTransitionsIntrinsicElements['cap-page'];
+            'cap-header': CapTransitionsIntrinsicElements['cap-header'];
+            'cap-content': CapTransitionsIntrinsicElements['cap-content'];
+            'cap-footer': CapTransitionsIntrinsicElements['cap-footer'];
+        }
+    }
+}
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements {
+            'cap-router-outlet': CapTransitionsIntrinsicElements['cap-router-outlet'];
+            'cap-page': CapTransitionsIntrinsicElements['cap-page'];
+            'cap-header': CapTransitionsIntrinsicElements['cap-header'];
+            'cap-content': CapTransitionsIntrinsicElements['cap-content'];
+            'cap-footer': CapTransitionsIntrinsicElements['cap-footer'];
+        }
+    }
+}
+declare module 'react/jsx-runtime' {
+    namespace JSX {
+        interface IntrinsicElements {
+            'cap-router-outlet': CapTransitionsIntrinsicElements['cap-router-outlet'];
+            'cap-page': CapTransitionsIntrinsicElements['cap-page'];
+            'cap-header': CapTransitionsIntrinsicElements['cap-header'];
+            'cap-content': CapTransitionsIntrinsicElements['cap-content'];
+            'cap-footer': CapTransitionsIntrinsicElements['cap-footer'];
+        }
+    }
+}
+
+export { type NavigationEvent, type SwipeGestureOption, TransitionController, type TransitionDirection, type TransitionGlobalConfig, createTransitionNavigate, getController, getDirection, initTransitions, setDirection, setupPage, setupRouterOutlet };