@shopify/app-bridge-host/HostProvider.d.ts

App Bridge Host contains components and middleware to be consumed by the app's host, as well as the host itself. The middleware and `Frame` component are responsible for facilitating communication between the client and host, and used to act on actions se

import React from 'react';
import { Middleware as ReduxMiddleware, Store as ReduxStore } from 'redux';
import { buildMiddleware } from './Middleware';
import { ReducerMap, Store } from './store';
import { TrackingEventPayload, Application, ApiClientConfig } from './types';
import { Props as HostProps } from './Host';
import { ApiContext } from './api';
/**
 * The current pathname, search params and hash
 * @internal
 * */
export interface Location {
    pathname: string;
    search?: string;
    hash?: string;
}
/**
 * The method to call when attempting to update the router history
 * When the return value is a string or `true`, the router update will be blocked
 * @internal
 * */
export interface Prompt {
    (nextLocation?: Location): string | false | void;
}
/**
 * The interface for the Navigation Context
 * @public
 * */
export interface RouterContext {
    /** The `handle` or `apiKey` for the current app */
    appRoot: string;
    hostname: string;
    href: string;
    /** The router to be to handle router actions */
    history: {
        replace(pathOrNextLocation: string | Location): void;
        push(pathOrNextLocation: string | Location): void;
        block?(prompt?: boolean | string | Prompt): () => void;
    };
    location: Location;
    open(url?: string, target?: string): void;
}
/**
 * The interface for the HostProvider
 * @public
 * */
export interface Props extends React.PropsWithChildren<HostProps> {
    /** Configuration of the app to load */
    config?: ApiClientConfig;
    /** Optional handler for when App Bridge actions are dispatched */
    dispatchClientEventHandler?: (trackingEventPayload: TrackingEventPayload) => void;
    /** Required to set the initial app state
     * @remarks feature permissions must be specified using the key `features` which will take effect immediately
     * other state properties (ex. `loading`, `toast`, etc..) will only be set after the relevant reducer has loaded
     */
    initialState: Partial<Store> & Pick<Store, 'features'>;
    /** Set the middleware to use when creating the Redux store */
    middleware?: (ReturnType<typeof buildMiddleware> | ReduxMiddleware)[];
    /** Set the router to use when a Navigation action results in a route change
     * @remarks this is required when using host components that handles navigation
     * for example: MainFrame, ContextualSaveBar and Navigation
     */
    router?: RouterContext;
    /** Enables the Redux dev tools if set to `true` */
    debug?: boolean;
    /** Enables dynamic API to be configured by the Host and provided to clients */
    configureApi?: boolean;
    /**
     * Optional error handler for errors thrown by App Bridge
     * If provided, the errors will be passed to the error handler instead of being thrown.
     */
    errorHandler?: (thrown: unknown) => void;
}
/**
 * The interface for the Host Context that can be
 * consumed by the Host Provider's child components
 * @public
 * */
export type OnRouteChangeListener = (options: RouteChangeOptions) => void;
export interface RouteChangeOptions {
    newUrl: string;
    shouldNotifyClient: boolean;
}
export interface HostContext {
    app: Application;
    api?: ApiContext;
    config: ApiClientConfig;
    addReducer<State>(reducerMap: ReducerMap<State>): void;
    store: ReduxStore;
    addRouteChangeListener(onRouteChangeListener: OnRouteChangeListener): () => void;
    notifyRouteChange(options: RouteChangeOptions): void;
    errorHandler?: (thrown: unknown) => void;
}
/**
 * The context provider for the app, config and addReducer method
 * @public
 * */
export declare const HostContext: React.Context<HostContext | null>;
/**
 * The context provider for the router.
 * Keeps track of the current location and
 * handles history push/replace
 * @public
 * */
export declare const RouterContext: React.Context<RouterContext | null>;
/**
 * A component that creates a dynamic Redux store
 * and renders the Host
 * @public
 * */
export default function HostProvider(props: Props): React.JSX.Element;