@nativescript/core/ui/transition/shared-transition.d.ts

A JavaScript library providing an easy to use api for interacting with iOS and Android platform APIs.

import type { Transition, TransitionNavigationType, SharedTransitionTagPropertiesToMatch } from '.';
import { Observable } from '../../data/observable';
import { ViewBase } from '../core/view-base';
import type { View } from '../core/view';
import type { PanGestureEventData } from '../gestures';
export declare enum SharedTransitionAnimationType {
    present = 0,
    dismiss = 1
}
type SharedTransitionEventAction = 'present' | 'dismiss' | 'interactiveStart' | 'interactiveFinish';
export type SharedTransitionEventDataPayload = {
    id: number;
    type: TransitionNavigationType;
    action?: SharedTransitionEventAction;
    percent?: number;
};
export type SharedTransitionEventData = {
    eventName: string;
    data: SharedTransitionEventDataPayload;
};
export type SharedRect = {
    x?: number;
    y?: number;
    width?: number;
    height?: number;
};
export type SharedProperties = SharedRect & {
    opacity?: number;
    scale?: {
        x?: number;
        y?: number;
    };
    /**
     * (iOS only) Page-level corner radius to animate alongside the transition.
     * Useful for sheet-style modals where the top corners are rounded at the
     * starting offscreen position and flatten as the page reaches fullscreen
     * (and vice versa for dismiss). Top-left + top-right corners are masked.
     */
    cornerRadius?: number;
};
/**
 * Properties which can be set on individual Shared Elements
 */
export type SharedTransitionTagProperties = SharedProperties & {
    /**
     * The visual stacking order where 0 is at the bottom.
     * Shared elements are stacked one on top of the other during each transition.
     * By default they are not ordered in any particular fashion.
     */
    zIndex?: number;
    /**
     * Collection of properties to match and animate on each shared element.
     *
     * Defaults to: 'backgroundColor', 'cornerRadius', 'borderWidth', 'borderColor'
     *
     * Tip: Using an empty array, [], for view or layer will avoid copying any properties if desired.
     */
    propertiesToMatch?: SharedTransitionTagPropertiesToMatch;
    /**
     *
     */
    callback?: (view: View, action: SharedTransitionEventAction) => Promise<void>;
};
export type SharedSpringProperties = {
    tension?: number;
    friction?: number;
    mass?: number;
    delay?: number;
    velocity?: number;
    animateOptions?: any;
};
type SharedTransitionPageProperties = SharedProperties & {
    /**
     * (iOS Only) Allow "independent" elements found only on one of the screens to take part in the animation.
     * Note: This feature will be brought to Android in a future release.
     */
    sharedTransitionTags?: {
        [key: string]: SharedTransitionTagProperties;
    };
    /**
     * Spring animation settings.
     * Defaults to 140 tension with 10 friction.
     */
    spring?: SharedSpringProperties;
};
type SharedTransitionPageWithDurationProperties = SharedTransitionPageProperties & {
    /**
     * Linear duration in milliseconds
     * Note: When this is defined, it will override spring options and use only linear animation.
     */
    duration?: number | undefined | null;
};
export interface SharedTransitionInteractiveOptions {
    /**
     * When the pan exceeds this percentage and you let go, finish the transition.
     * Default 0.5
     */
    finishThreshold?: number;
    /**
     * You can create your own percent formula used for determing the interactive value.
     * By default, we handle this via a formula like this for an interactive page back transition:
     * - return eventData.deltaX / (eventData.ios.view.bounds.size.width / 2);
     * @param eventData PanGestureEventData
     * @returns The percentage value to be used as the finish/cancel threshold
     */
    percentFormula?: (eventData: PanGestureEventData) => number;
    /**
     * (iOS only) Apple Music–style "morph" interactive dismiss.
     *
     * Instead of fading the destination and animating shared snapshots, the
     * entire destination view scales + translates with the user's finger.
     *  - If released past `finishThreshold`, the view morphs into the matching
     *    source element's frame and the transition completes.
     *  - If released before the threshold, the view springs back to its
     *    fullscreen position.
     *
     * Set to `true` for the default tuning. Pass an object to customize.
     */
    morph?: boolean | {
        /** Smallest scale applied at maximum drag distance. Default 0.5. */
        minScale?: number;
    };
    /**
     * (iOS only) Drop shadow rendered behind the destination view during the
     * interactive dismiss — gives the view a sense of depth/elevation as it
     * morphs back toward the source (Apple Music–style).
     * Note: This feature will be brought to Android in a future release.
     *
     * - `true` applies sensible defaults
     *   (color black, opacity 0.3, radius 30, offset (0, 8)).
     * - Pass an object to customize any field.
     * - Omit / `false` to skip.
     */
    shadow?: boolean | SharedTransitionInteractiveDismissShadow;
}
export interface SharedTransitionInteractiveDismissShadow {
    /** Hex / named color string or `Color` instance. Default `'#000'`. */
    color?: string | {
        ios?: any;
    };
    /** 0–1. Default `0.3`. */
    opacity?: number;
    /** Blur radius in points. Default `30`. */
    radius?: number;
    /** Offset in points. Default `{ x: 0, y: 8 }`. */
    offset?: {
        x?: number;
        y?: number;
    };
}
export interface SharedTransitionConfig {
    /**
     * Interactive transition settings. (iOS only at the moment)
     */
    interactive?: {
        /**
         * Whether you want to allow interactive dismissal.
         * Defaults to using 'pan' gesture for dismissal however you can customize your own.
         */
        dismiss?: SharedTransitionInteractiveOptions;
    };
    /**
     * View settings applied to the incoming page to start your transition with.
     */
    pageStart?: SharedTransitionPageProperties;
    /**
     * View settings applied to the incoming page to end your transition with.
     */
    pageEnd?: SharedTransitionPageWithDurationProperties;
    /**
     * View settings applied to the outgoing page in your transition.
     */
    pageOut?: SharedTransitionPageWithDurationProperties;
    /**
     * View settings to return to the original page with.
     */
    pageReturn?: SharedTransitionPageWithDurationProperties & {
        /**
         * In some cases you may want the returning animation to start with the original opacity,
         * instead of beginning where it ended up on pageEnd.
         * Note: you can try enabling this property in cases where your return animation doesn't appear correct.
         */
        useStartOpacity?: boolean;
    };
}
export interface SharedTransitionState extends SharedTransitionConfig {
    /**
     * (Internally used) Preconfigured transition or your own custom configured one.
     */
    instance?: Transition;
    /**
     * Page which will start the transition.
     */
    page?: ViewBase;
    activeType?: SharedTransitionAnimationType;
    toPage?: ViewBase;
    /**
     * Whether interactive transition has began.
     */
    interactiveBegan?: boolean;
    /**
     * Whether interactive transition was cancelled.
     */
    interactiveCancelled?: boolean;
}
declare class SharedTransitionObservable extends Observable {
    on(eventNames: string, callback: (data: SharedTransitionEventData) => void, thisArg?: any): void;
}
/**
 * Shared Element Transitions (preview)
 * Allows you to auto animate between shared elements on two different screesn to create smooth navigational experiences.
 * View components can define sharedTransitionTag="name" alone with a transition through this API.
 */
export declare class SharedTransition {
    /**
     * Configure a custom transition with presentation/dismissal options.
     * @param transition The custom Transition instance.
     * @param options
     * @returns a configured SharedTransition instance for use with navigational APIs.
     */
    static custom(transition: Transition, options?: SharedTransitionConfig): {
        instance: Transition;
    };
    /**
     * Whether a transition is in progress or not.
     * Note: used internally however exposed in case custom state ordering is needed.
     * Updated when transitions start/end/cancel.
     */
    static inProgress: boolean;
    /**
     * Listen to various shared element transition events.
     * @returns Observable
     */
    static events(): SharedTransitionObservable;
    /**
     * When the transition starts.
     */
    static startedEvent: string;
    /**
     * When the transition finishes.
     */
    static finishedEvent: string;
    /**
     * When the interactive transition cancels.
     */
    static interactiveCancelledEvent: string;
    /**
     * When the interactive transition updates with the percent value.
     */
    static interactiveUpdateEvent: string;
    /**
     * Notify a Shared Transition event.
     * @param id transition instance id
     * @param eventName Shared Transition event name
     * @param type TransitionNavigationType
     * @param action SharedTransitionEventAction
     */
    static notifyEvent(eventName: string, data: SharedTransitionEventDataPayload): void;
    /**
     * Enable to see various console logging output of Shared Element Transition behavior.
     */
    static DEBUG: boolean;
    /**
     * Update transition state.
     * @param id Transition instance id
     * @param state SharedTransitionState
     */
    static updateState(id: number, state: SharedTransitionState): void;
    /**
     * Get current state for any transition.
     * @param id Transition instance id
     */
    static getState(id: number): SharedTransitionState;
    /**
     * Finish transition state.
     * @param id Transition instance id
     */
    static finishState(id: number): void;
    /**
     * Register an NS view subtree that should be searched for sharedTransitionTag
     * elements in addition to the source page. Use this for views that are attached
     * to the native UI but aren't reachable from the page via the NS view tree —
     * for example, a TabView's `iosBottomAccessory`. The root and any of its
     * descendants with a `sharedTransitionTag` will then participate in transitions
     * originating from any page.
     *
     * Registration is idempotent. Pair with `unregisterExternalRoot` on teardown
     * to avoid leaking detached views into future transitions.
     */
    static registerExternalRoot(root: ViewBase): void;
    /**
     * Remove a previously registered external root. No-op if the root wasn't
     * registered.
     */
    static unregisterExternalRoot(root: ViewBase): void;
    /**
     * Gather view collections based on sharedTransitionTag details.
     * @param fromPage Page moving away from
     * @param toPage Page moving to
     * @returns Collections of views pertaining to shared elements or particular pages
     */
    static getSharedElements(fromPage: ViewBase, toPage: ViewBase): {
        sharedElements: Array<View>;
        presented: Array<View>;
        presenting: Array<View>;
    };
}
/**
 * Get dimensional rectangle (x,y,width,height) from properties with fallbacks for any undefined values.
 * @param props combination of properties conformed to SharedTransitionPageProperties
 * @param defaults fallback properties when props doesn't contain a value for it
 * @returns { x,y,width,height }
 */
export declare function getRectFromProps(props: SharedTransitionPageProperties, defaults?: SharedRect): SharedRect;
/**
 * Get spring properties with default fallbacks for any undefined values.
 * @param props various spring related properties conforming to SharedSpringProperties
 * @returns
 */
export declare function getSpringFromProps(props: SharedSpringProperties): {
    tension: number;
    friction: number;
    mass: number;
    velocity: number;
    delay: number;
};
/**
 * Page starting defaults for provided type.
 * @param type TransitionNavigationType
 * @returns { x,y,width,height }
 */
export declare function getPageStartDefaultsForType(type: TransitionNavigationType): {
    x: number;
    y: number;
    width: number;
    height: number;
};
export {};