API Reference

/**
 * Describes a registered application within the system,
  including its type, unique identifier, and URL.
 *
 * @typedef {Object} RegisteredApp
 * @property {number} id - The unique identifier of the application.
 * @property {string} name - Optional. The name of the application.
 * @property {string} url - The URL where the application is hosted.
 * @property {string} path - The path where the application is hosted.
 * @property {string} slug - A short, unique string used to identify the application.
 * @property {string} subSlug - Optional. A short, unique slug fragment used to identify each of multiple client applications.
 * @property {RegisteredAppType} type - The type of the application.
 */
type RegisteredApp = {
  id: number;
  name?: string;
  url: string;
  path: string;
  slug: string;
  subSlug?: string;
  type: RegisteredAppType;
};

/**
 * Represents the type of a registered application within the system.
 *
 * @typedef {('full_page' | 'plugin')} RegisteredAppType
 */
type RegisteredAppType = 'full_page' | 'plugin';

/**
 * Provides a mechanism for navigating within the application.
 *
 * @typedef {Object} ApplicationNavigation
 * @property {(payload: ApplicationNavigationPayload) => void} navigate - A function that performs navigation to the
    specified URL.
 */
interface ApplicationNavigation {
  navigate: (payload: ApplicationNavigationPayload) => void;
}
 
interface ApplicationNavigationPayload {
  path: string;
  id?: number;
}

/**
 * Provides a mechanism for navigating within the shell application.
 *
 * @typedef {Object} ShellNavigation
 * @property {(payload: ShellNavigationPayload) => void} navigate - A function that performs navigation to the
    specified URL.
 * @property {(payload: ShellNavigationPayload) => string | undefined} resolveUrl - Optional. Returns the absolute
    url the host would navigate to for the given payload, without navigating, or nothing when it has none. Its
    result, without any query string or hash, is broadcast to the app as `ApplicationData.shellBaseUrl`.
 */
interface ShellNavigation {
  navigate: (payload: ShellNavigationPayload) => void;
  resolveUrl?: (payload: ShellNavigationPayload) => string | undefined;
}

/**
 * Defines the structure of the payload for navigation within the shell application.
 *
 * @typedef {Object} ShellNavigationPayload
 * @property {number | UUID} id - Optional. The unique identifier of the navigation target.
 * @property {string} path - The path to navigate to.
 * @property {boolean} external - Optional. Indicates if the navigation is external.
 * @property {boolean} newTab - Optional. Indicates if the navigation should open in a new browser tab. The shell
    forwards the flag to the host untouched and opens no window of its own, since only the host knows its own url
    grammar.
 */
interface ShellNavigationPayload {
  id?: number | UUID;
  path: string;
  external?: boolean;
  newTab?: boolean;
}

/**
 * A flexible data structure for storing application-wide shared
  data. This type is used to hold and distribute shared data across micro
  frontends, such as user preferences or session information.
 *
 * @property {Record<string, string>} searchParams - Optional. The search params of the application.
 * @property {string} shellBaseUrl - Optional. The absolute base url of the shell application, added by the shell to
    the copy of the data each app receives. It is omitted entirely when the host implements no
    `ShellNavigation.resolveUrl` or that call yields nothing.
 */
interface ApplicationData {
  searchParams?: Record<string, string>;
  shellBaseUrl?: string;
  [key: string]: any;
}

/**
 * Defines actions that can be shared across applications,
  including default UI actions and custom actions.
 *
 * @typedef {Object} ApplicationActions
 * @property {(title: string, content: string) => void} showModalDialog - Optional. A function to show a modal dialog.
 * @property {(title: string, content: string) => boolean} showConfirmationDialog - Optional. A function to show a confirmation dialog.
 * @property {(
    content: string,
    type: 'success' | 'warning' | 'error' | 'loading' | 'destroy'
  ) => void} showToast - Optional. A function to show a toast message.
 * @property {(title: string, content: string) => void} showErrorMessage - Optional. A function to display an error message.
 * @property {(uuid: UUID, path: string, context?: unknown, size?: ApplicationModalSize, closeIconColor?: string) => void} showRichModal - Optional. A function to show a rich modal.
 * @property {(keys: string[]) => void} removeSearchParams - Optional. A function to remove search parameters from the URL.
 * @property {(searchParams: Record<string, string | number>) => void} setSearchParams - Optional. A function to set search parameters in the URL.
 * @property {{
    [key: string]: (...args: any[]) => any;
  }} actions - These custom actions are application-specific operations that micro frontends can
invoke.
 */
interface ApplicationActions {
  // Default actions
  showModalDialog?: (title: string, content: string) => void;
  showConfirmationDialog?: (title: string, content: string) => boolean;
  showToast?: (
    content: string,
    type: 'success' | 'warning' | 'error' | 'loading' | 'destroy'
  ) => void;
  showErrorMessage?: (title: string, content: string) => void;
  showRichModal?: (
    uuid: UUID,
    path: string,
    context?: unknown,
    size?: ApplicationModalSize,
    closeIconColor?: string
  ) => void;
  removeSearchParams?: (keys: string[]) => void;
  setSearchParams?: (searchParams: Record<string, string | number>) => void;
  // Custom actions
  actions: {
    [key: string]: (...args: any[]) => any;
  };
}

/**
 * Defines the size configuration for application modals.
 *
 * @typedef {Object} ApplicationModalSize
 * @property {number | string} maxWidth - Optional. The maximum width of the modal.
 * @property {number | string} maxHeight - Optional. The maximum height of the modal.
 */
type ApplicationModalSize = {
  maxWidth?: number | string;
  maxHeight?: number | string;
};

/**
 * Additional parameters to be passed to the plugin micro app.
 */
interface ApplicationParams {
  [key: string]: string | number | boolean | string[] | number[];
}

/**
 * Defines the shape of the context state used by the AppShellProvider.
 *
 * @typedef {Object} AppShellContextState
 * @property {RegisteredApp[]} apps - The list of registered micro frontend applications.
 * @property {Map<number, PluginApplicationConfig | FullpageApplicationConfig>} configs - Stores configuration for each registered app.
 * @property {(payload: ApplicationNavigationPayload) => void} navigate - Provides a mechanism for navigating within the main application.
 * @property {React.MutableRefObject<Map<number, HTMLIFrameElement>>} frames - Optional. References to iframe elements for each micro frontend.
 * @property {React.MutableRefObject<Map<number | UUID, Framebus>>} buses - Optional. Framebus instances for each registered app.
 * @property {Map<number | UUID, AppInstanceInfo>} instances - Optional. App instances by base path.
 * @property {Map<UUID, number | UUID>} modals - Optional. UUID values for defined rich modals.
 * @property {Map<UUID, unknown>} modalContext - Optional. Context data for a modal.
 */
interface AppShellContextState {
  apps: RegisteredApp[];
  configs: Map<
    number | UUID,
    PluginApplicationConfig | FullpageApplicationConfig
  >;
  navigate: (payload: ApplicationNavigationPayload) => void;
  frames?: React.MutableRefObject<Map<number | UUID, HTMLIFrameElement>>;
  buses?: React.MutableRefObject<Map<number | UUID, Framebus>>;
  instances: Map<number | UUID, AppInstanceInfo>;
  modals?: Map<UUID, number | UUID>;
  modalContext?: Map<UUID, unknown>;
}
 
interface AppInstanceInfo {
  id: number | UUID;
  basePath: string;
  config: FullpageApplicationConfig | PluginApplicationConfig;
  iframe: HTMLIFrameElement;
  bus: Framebus;
}