Actions

Client applications can invoke actions defined in the shell application.

This allows micro-frontends to trigger shell functionality such as showing toasts, opening modals, or calling custom business logic.

Action Types

There are two types of actions:

1. Default Actions - Built-in UI actions (toast, modal, confirmation)

2. Custom Actions - Application-specific actions defined by the shell

Using Default Actions

Default actions are available directly from useAppClient:

import { useAppClient } from '@akinon/app-client';

const MyComponent = () => {
  const { 
    showToast, 
    showModalDialog, 
    showConfirmationDialog,
    showErrorMessage,
    showRichModal 
  } = useAppClient();

  // Use these functions to invoke default actions
};

showToast

Display a brief notification message:

const NotificationExample = () => {
  const { showToast } = useAppClient();

  const handleSuccess = () => {
    showToast('Operation completed successfully!', 'success');
  };

  const handleError = () => {
    showToast('Something went wrong', 'error');
  };

  const handleWarning = () => {
    showToast('Please review your input', 'warning');
  };

  const handleLoading = () => {
    showToast('Processing...', 'loading');
  };

  const clearToasts = () => {
    showToast('', 'destroy');
  };

  return (
    <div>
      <button onClick={handleSuccess}>Success</button>
      <button onClick={handleError}>Error</button>
      <button onClick={handleWarning}>Warning</button>
      <button onClick={handleLoading}>Loading</button>
      <button onClick={clearToasts}>Clear All</button>
    </div>
  );
};

showConfirmationDialog

Display a confirmation dialog with callbacks:

const DeleteButton = ({ itemId }: { itemId: string }) => {
  const { showConfirmationDialog, showToast } = useAppClient();

  const handleDelete = () => {
    showConfirmationDialog({
      title: 'Delete Item',
      content: 'Are you sure you want to delete this item? This action cannot be undone.',
      onConfirm: async () => {
        await deleteItem(itemId);
        showToast('Item deleted', 'success');
      },
      onCancel: () => {
        console.log('Deletion cancelled');
      }
    });
  };

  return <button onClick={handleDelete}>Delete</button>;
};

showModalDialog

Display an informational modal:

const InfoButton = () => {
  const { showModalDialog } = useAppClient();

  const showInfo = () => {
    showModalDialog({
      title: 'About This Feature',
      content: 'This feature allows you to manage your orders efficiently.'
    });
  };

  return <button onClick={showInfo}>Info</button>;
};

showErrorMessage

Display an error message prominently:

const ErrorHandler = () => {
  const { showErrorMessage } = useAppClient();

  const handleApiError = (error: Error) => {
    showErrorMessage('Request Failed', error.message);
  };

  return <ApiConsumer onError={handleApiError} />;
};

showRichModal

Open a rich modal with micro-frontend content:

const ProductList = () => {
  const { showRichModal } = useAppClient();

  const openProductDetail = (productId: string) => {
    showRichModal(
      `/products/${productId}`,           // path
      { productId, mode: 'view' },        // context (accessible via modalContext)
      { maxWidth: 800, maxHeight: '90vh' }, // size
      '#333333'                            // closeIconColor
    );
  };

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>
          {product.name}
          <button onClick={() => openProductDetail(product.id)}>
            View Details
          </button>
        </li>
      ))}
    </ul>
  );
};

Using Custom Actions

Custom actions are invoked via invokeAction:

import { useAppClient } from '@akinon/app-client';

const CustomActionExample = () => {
  const { invokeAction, showToast, showErrorMessage } = useAppClient();

  const handleLogout = async () => {
    try {
      await invokeAction('performLogout');
      showToast('Logged out successfully', 'success');
    } catch (error) {
      showErrorMessage('Logout Failed', error.message);
    }
  };

  const fetchUserData = async (userId: number) => {
    try {
      const userData = await invokeAction('fetchUserData', userId);
      console.log('User data:', userData);
      return userData;
    } catch (error) {
      showErrorMessage('Fetch Failed', error.message);
    }
  };

  const refreshPermissions = async () => {
    const result = await invokeAction('refreshPermissions');
    if (result.success) {
      showToast('Permissions updated', 'success');
    }
  };

  return (
    <div>
      <button onClick={handleLogout}>Logout</button>
      <button onClick={() => fetchUserData(123)}>Fetch User</button>
      <button onClick={refreshPermissions}>Refresh Permissions</button>
    </div>
  );
};

URL Search Params

Manage URL search parameters via shell actions:

const FilterComponent = () => {
  const { setSearchParams, removeSearchParams, data } = useAppClient();

  const applyFilters = (filters: Record<string, string>) => {
    setSearchParams({
      ...filters,
      page: 1
    });
  };

  const clearFilters = () => {
    removeSearchParams(['category', 'status', 'page']);
  };

  return (
    <div>
      <p>Current: {JSON.stringify(data?.searchParams)}</p>
      <button onClick={() => applyFilters({ category: 'electronics' })}>
        Electronics
      </button>
      <button onClick={clearFilters}>Clear</button>
    </div>
  );
};

Accessing Modal Context

When opened via showRichModal, access the context:

// Parent component calls:
// showRichModal('/product-detail', { productId: '123', mode: 'edit' })

// In the modal content:
const ProductDetailModal = () => {
  const { modalContext } = useAppClient();
  
  const context = modalContext as { productId: string; mode: string };

  return (
    <div>
      <h1>Product Detail</h1>
      <p>ID: {context?.productId}</p>
      <p>Mode: {context?.mode}</p>
    </div>
  );
};

Best Practices

1. Error Handling

Always wrap action invocations in try-catch:

const handleAction = async () => {
  try {
    const result = await invokeAction('riskyAction');
    showToast('Success!', 'success');
  } catch (error) {
    showErrorMessage('Action Failed', error.message);
  }
};

2. Loading States

Show loading indicators during async actions:

const AsyncActionButton = () => {
  const { invokeAction, showToast } = useAppClient();
  const [isLoading, setIsLoading] = useState(false);

  const handleClick = async () => {
    setIsLoading(true);
    try {
      await invokeAction('longRunningAction');
      showToast('Done!', 'success');
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Run Action'}
    </button>
  );
};

3. Type Safety

Type your action results:

interface UserData {
  id: number;
  name: string;
  email: string;
}

const fetchUser = async (userId: number): Promise<UserData> => {
  const result = await invokeAction<UserData>('fetchUserData', userId);
  return result;
};

Next Steps

• Navigation - Client-side navigation

• Hooks - Complete useAppClient reference