# API Reference

### <mark style="color:red;">Components</mark>

#### AppShellProvider

The root provider component that manages micro-frontend communication and state.

```tsx
import { AppShellProvider } from '@akinon/app-shell';
```

**Props**

| Property     | Type                 | Required | Default | Description                                    |
| ------------ | -------------------- | -------- | ------- | ---------------------------------------------- |
| `apps`       | `RegisteredApp[]`    | Yes      | -       | List of registered micro-frontend applications |
| `navigation` | `ShellNavigation`    | Yes      | -       | Navigation helper functions                    |
| `data`       | `ApplicationData`    | No       | -       | Shared data available to all clients           |
| `actions`    | `ApplicationActions` | No       | -       | Actions that clients can invoke                |

***

#### AppRenderer

Renders fullpage micro-frontend applications.

```tsx
import { AppRenderer } from '@akinon/app-shell';
```

**Props**

| Property | Type     | Required | Default | Description                           |
| -------- | -------- | -------- | ------- | ------------------------------------- |
| `id`     | `number` | Yes      | -       | Unique identifier for the application |
| `path`   | `string` | No       | -       | Path to append to the iframe src URL  |

***

#### PluginRenderer

Renders plugin micro-frontend applications in designated placeholders.

```tsx
import { PluginRenderer } from '@akinon/app-shell';
```

**Props**

| Property        | Type                | Required | Default | Description                                |
| --------------- | ------------------- | -------- | ------- | ------------------------------------------ |
| `placeholderId` | `string`            | Yes      | -       | ID of the placeholder where plugin renders |
| `params`        | `ApplicationParams` | No       | -       | Parameters to pass to the plugin           |

***

#### ModalRenderer

Renders micro-frontend content within a modal.

```tsx
import { ModalRenderer } from '@akinon/app-shell';
```

**Props**

| Property | Type                   | Required | Default | Description                     |
| -------- | ---------------------- | -------- | ------- | ------------------------------- |
| `uuid`   | `UUID`                 | Yes      | -       | Unique identifier for the modal |
| `path`   | `string`               | Yes      | -       | Path to render within the modal |
| `size`   | `ApplicationModalSize` | No       | -       | Size configuration              |

***

### <mark style="color:red;">Hooks</mark>

#### useAppShell

Access the shell context for managing micro-frontend interactions.

```tsx
import { useAppShell } from '@akinon/app-shell';

const { apps, configs, navigate, frames, buses } = useAppShell();
```

**Return Value: `AppShellContextState`**

<table><thead><tr><th width="150.70703125">Property</th><th width="355.60546875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>apps</code></td><td><code>RegisteredApp[]</code></td><td>List of registered applications</td></tr><tr><td><code>configs</code></td><td><code>Map&#x3C;number | UUID, ApplicationConfig></code></td><td>Configuration per app</td></tr><tr><td><code>navigate</code></td><td><code>(payload: NavigationPayload) => void</code></td><td>Navigation function</td></tr><tr><td><code>frames</code></td><td><code>MutableRefObject&#x3C;Map&#x3C;number | UUID, HTMLIFrameElement>></code></td><td>Iframe references</td></tr><tr><td><code>buses</code></td><td><code>MutableRefObject&#x3C;Map&#x3C;number | UUID, Framebus>></code></td><td>Framebus instances</td></tr><tr><td><code>instances</code></td><td><code>Map&#x3C;number | UUID, AppInstanceInfo></code></td><td>App instances</td></tr><tr><td><code>modals</code></td><td><code>Map&#x3C;UUID, number | UUID></code></td><td>Modal UUID mappings</td></tr><tr><td><code>modalContext</code></td><td><code>Map&#x3C;UUID, unknown></code></td><td>Modal context data</td></tr></tbody></table>

***

### <mark style="color:red;">Types</mark>

#### RegisteredApp

Describes a registered micro-frontend application.

```typescript
interface RegisteredApp {
  pk: number;
  name?: string;
  config: {
    web_url: string;
    visible_type: 'full_page' | 'plugin';
    placeholder?: string;
  };
  is_visible: boolean;
  is_active: boolean;
}
```

***

#### ShellNavigation

Navigation helper interface.

```typescript
interface ShellNavigation {
  navigate: (payload: NavigationPayload) => void;
}

interface NavigationPayload {
  path: string;
  id?: number;
}
```

***

#### ApplicationData

Shared data structure.

```typescript
interface ApplicationData {
  searchParams?: Record<string, string>;
  [key: string]: any;
}
```

***

#### ApplicationActions

Actions that clients can invoke.

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

***

#### ApplicationModalSize

Modal size configuration.

```typescript
type ApplicationModalSize = {
  maxWidth?: number | string;
  maxHeight?: number | string;
};
```

***

#### ApplicationParams

Parameters for plugin applications.

```typescript
interface ApplicationParams {
  [key: string]: string | number | boolean | string[] | number[];
}
```

***

#### AppShellContextState

Context state returned by `useAppShell`.

```typescript
interface AppShellContextState {
  apps: RegisteredApp[];
  configs: Map<number | UUID, PluginApplicationConfig | FullpageApplicationConfig>;
  navigate: (payload: NavigationPayload) => 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>;
}
```

***

#### AppInstanceInfo

Information about an app instance.

```typescript
interface AppInstanceInfo {
  id: number | UUID;
  basePath: string;
  config: FullpageApplicationConfig | PluginApplicationConfig;
  iframe: HTMLIFrameElement;
  bus: Framebus;
}
```

***

#### FullpageApplicationConfig

Configuration for fullpage applications.

```typescript
interface FullpageApplicationConfig {
  web_url: string;
  visible_type: 'full_page';
}
```

***

#### PluginApplicationConfig

Configuration for plugin applications.

```typescript
interface PluginApplicationConfig {
  web_url: string;
  visible_type: 'plugin';
  placeholder: string;
}
```

***

### <mark style="color:red;">Events</mark>

AppShell uses the following events for communication (defined in `@akinon/app-shared`):

| Event                   | Direction      | Description                                   |
| ----------------------- | -------------- | --------------------------------------------- |
| `SET_CONFIG`            | Client → Shell | Client sends its configuration                |
| `SET_DATA`              | Shell → Client | Shell sends shared data                       |
| `SET_APP_ID`            | Shell → Client | Shell sends app identifier                    |
| `SET_MODAL_CONTEXT`     | Shell → Client | Shell sends modal context data                |
| `SET_HEIGHT`            | Client → Shell | Client sends its iframe height                |
| `SET_PARAMS`            | Shell → Client | Shell sends plugin parameters                 |
| `INVOKE_ACTION`         | Client → Shell | Client invokes a custom action                |
| `INVOKE_DEFAULT_ACTION` | Client → Shell | Client invokes a default action               |
| `NAVIGATE`              | Client → Shell | Client requests navigation                    |
| `NAVIGATE_CHILD`        | Shell → Client | Shell triggers navigation on child app        |
| `ACTION_CONFIRMED`      | Shell → Client | Shell confirms an action (triggers onConfirm) |
| `ACTION_CANCELED`       | Shell → Client | Shell cancels an action (triggers onCancel)   |
| `LOCALE_CHANGED`        | Shell → Client | Shell notifies locale change                  |

### <mark style="color:red;">Related</mark>

* [Introduction](/akinon-ui/ui-protocol/shell-application/introduction.md) - Getting started with AppShell
* Hooks - Using the [useAppShell](/akinon-ui/ui-protocol/shell-application/useappshell.md) hook
* [Components](/akinon-ui/ui-protocol/shell-application/components.md) - Renderer components


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/akinon-ui/ui-protocol/shell-application/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.