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;
}

/**
 * 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.
 */
interface ApplicationData {
  [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) => void} showRichModal - Optional. A function to show a rich modal.
 * @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) => void;
  // Custom actions
  actions: {
    [key: string]: (...args: any[]) => any;
  };
}

/**
 * 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;
}