@capgo/capacitor-transitions 8.0.1

package/dist/svelte/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * 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;
+}
+
+/**
+ * Svelte bindings for @capgo/capacitor-transitions
+ */
+
+/**
+ * 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;
+/**
+ * Helper for Svelte actions - use on cap-router-outlet
+ */
+interface SvelteActionReturn<T> {
+    update?: (newOptions: T) => void;
+    destroy?: () => void;
+}
+interface RouterOutletOptions {
+    keepInDom?: boolean;
+    maxCached?: number;
+    platform?: 'ios' | 'android' | 'auto';
+    duration?: number;
+    swipeGesture?: SwipeGestureOption;
+}
+declare function routerOutlet(node: HTMLElement, options?: RouterOutletOptions): SvelteActionReturn<RouterOutletOptions>;
+interface PageCallbacks {
+    onWillEnter?: (event: NavigationEvent) => void;
+    onDidEnter?: (event: NavigationEvent) => void;
+    onWillLeave?: (event: NavigationEvent) => void;
+    onDidLeave?: (event: NavigationEvent) => void;
+}
+/**
+ * Helper for Svelte actions - use on cap-page
+ */
+declare function page(node: HTMLElement, callbacks?: PageCallbacks): SvelteActionReturn<PageCallbacks>;
+/**
+ * Helper for navigation with transitions
+ */
+declare function navigateWithTransition(navigate: (to: string) => void, to: string, direction?: TransitionDirection): void;
+/**
+ * Create a transition-aware navigate function
+ */
+declare function createTransitionNavigate(navigate: (to: string) => void): (to: string, direction?: TransitionDirection) => void;
+
+export { type NavigationEvent, type SwipeGestureOption, TransitionController, type TransitionDirection, type TransitionGlobalConfig, createTransitionNavigate, getController, getDirection, initTransitions, navigateWithTransition, page, routerOutlet, setDirection };