Actions

The AppShell library enables seamless interaction between the application shell and its micro frontends through a robust action system. This system allows the app shell to expose a set of predefined (“default”) actions and supports the definition of custom actions tailored to specific needs.

Overview

Actions are mechanisms through which micro frontends can request the app shell to perform certain operations. These operations might include displaying messages, navigating between pages, or invoking more complex logic defined within the app shell.

Default Actions

Default actions are predefined operations that the AppShell library recommends implementing to ensure a consistent user experience across different parts of the application. These actions cover common functionalities such as displaying modals, confirmation dialogs, and toast messages. By utilizing a standardized set of actions, micro frontends can leverage these functionalities without directly managing their implementations, which might vary depending on the libraries or frameworks used.

Implementing Default Actions

Implementing default actions within the AppShell involves defining functions that handle the desired behavior for each action. These functions are then made available to micro frontends through the AppShellProvider context.

const defaultActions = {
  showModalDialog: (title, content) => {
    // Implementation for showing a modal dialog
  },
  showConfirmationDialog: (title, content) => {
    // Implementation for showing a confirmation dialog
  },
  showToast: (content, type) => {
    // Implementation for showing a toast message
  },
  showErrorMessage: (title, content) => {
    // Implementation for showing an error message dialog
  },
  showRichModal: (uuid, path, context) => {
    // Implementation for showing a rich modal
  }
};

• showModalDialog(title, content): Displays a modal dialog with the provided title and content. This can be used for informational messages, forms, or any content that requires user attention while preventing interaction with the rest of the application.
• showConfirmationDialog(title, content): Presents a dialog asking for user confirmation. Useful for actions that require explicit user consent or acknowledgment, such as deleting data or confirming a significant action.
• showToast(content, type): Shows a brief, non-intrusive message to the user. Toasts are typically used for feedback about an operation’s success, warning, or failure.
• showErrorMessage(title, content): Utilized to inform the user of an error in a prominent way. It can provide details about what went wrong and potential steps to resolve the issue.
• showRichModal(uuid, path, context): Displays a rich-contentful modal with the specified path and context. This modal is suitable for displaying complex modals. An example implementation with rich modal integration is here.

Custom Actions

Beyond the default actions, the AppShell allows for the definition of custom actions. These are application-specific operations that micro frontends can invoke.

Defining Custom Actions

Custom actions are defined in a similar manner to default actions, but they are tailored to the specific functionalities of your application. These actions are then registered in the AppShellProvider, making them accessible to micro frontends.

const customActions = {
  performLogout: () => {
    // Logic to perform user logout
  },
  fetchData: async (resourceId) => {
    // Logic to fetch data
    return { ... };
  }
};

Now you can pass the actions to AppShellProvider component.

import { AppShellProvider, type ApplicationActions } from '@akinon/app-shell';
 
const App = () => {
  const actions: ApplicationActions = {
    ...defaultActions,
    actions: {
      ...customActions
    }
  };
 
  return (
    <AppShellProvider
      apps={...}
      navigation={...}
      data={...}
      actions={actions}>
      {/* Your application components go here */}
    </AppShellProvider>
  );
};
 
export default App;

Type

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

Through the implementation of both default and custom actions, AppShell offers a flexible and robust mechanism for micro frontends to interact with shared functionalities. To learn more about how to consume shared data in micro applications see AppClient’s documentation.