# API Reference

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

#### AppClientProvider

The root provider component that enables communication with the shell application.

```tsx
import { AppClientProvider } from '@akinon/app-client';
```

**Props**

| Property   | Type                                                   | Required | Default     | Description                            |
| ---------- | ------------------------------------------------------ | -------- | ----------- | -------------------------------------- |
| `children` | `ReactNode`                                            | Yes      | -           | Child components                       |
| `config`   | `FullpageApplicationConfig \| PluginApplicationConfig` | Yes      | -           | Application configuration              |
| `eventBus` | `Framebus`                                             | No       | `undefined` | Custom framebus instance (for testing) |

**Usage**

```tsx
<AppClientProvider config={{ isDev: true }}>
  <App />
</AppClientProvider>
```

***

#### MultiAppProvider

Enables multiple client applications to be served from a single URL with different base paths.

```tsx
import { MultiAppProvider } from '@akinon/app-client';
```

**Props**

| Property      | Type             | Required | Description                     |
| ------------- | ---------------- | -------- | ------------------------------- |
| `children`    | `ReactNode`      | Yes      | Child components                |
| `multiConfig` | `MultiAppConfig` | Yes      | Configuration for multiple apps |

**Usage**

```tsx
const multiConfig: MultiAppConfig = {
  apps: {
    firstApp: {
      basePath: '/first-app',
      type: 'full_page',
      config: {
        isDev: true,
        menu: [{ path: '/dashboard', label: 'Dashboard' }]
      }
    },
    secondApp: {
      basePath: '/second-app',
      type: 'full_page',
      config: {
        isDev: true,
        menu: [{ path: '/settings', label: 'Settings' }]
      }
    }
  },
  defaultApp: 'firstApp'
};

<MultiAppProvider multiConfig={multiConfig}>
  <App />
</MultiAppProvider>
```

***

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

#### useAppClient

Access the client context for communicating with the shell.

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

const { data, navigate, showToast, invokeAction } = useAppClient();
```

**Return Value: `AppClientContextState`**

| Property                 | Type                                                  | Description                 |
| ------------------------ | ----------------------------------------------------- | --------------------------- |
| `data`                   | `ApplicationData \| undefined`                        | Shared data from shell      |
| `params`                 | `ApplicationParams \| undefined`                      | Plugin parameters           |
| `isLoading`              | `boolean`                                             | Data loading state          |
| `modalContext`           | `unknown`                                             | Rich modal context data     |
| `locale`                 | `string`                                              | Current locale              |
| `navigate`               | `(payload: ShellNavigationPayload) => void`           | Request shell navigation    |
| `invokeAction`           | `<T>(key: string, ...args: unknown[]) => Promise<T>`  | Invoke custom action        |
| `showModalDialog`        | `(options: ModalDialogOptions) => boolean`            | Show modal dialog           |
| `showConfirmationDialog` | `(options: ConfirmDialogOptions) => boolean`          | Show confirmation           |
| `showToast`              | `(content: string, type: ToastType) => boolean`       | Show toast                  |
| `showErrorMessage`       | `(title: string, content: string) => boolean`         | Show error                  |
| `showRichModal`          | `(path, context?, size?, closeIconColor?) => boolean` | Show rich modal             |
| `removeSearchParams`     | `(keys: string \| string[]) => void`                  | Remove URL params           |
| `setSearchParams`        | `(params: Record<string, string \| number>) => void`  | Set URL params              |
| `onLocaleChange`         | `(callback: (locale: string) => void) => () => void`  | Subscribe to locale changes |

***

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

#### AppClientContextState

The context state provided by `AppClientProvider`.

```typescript
interface AppClientContextState {
  data?: ApplicationData;
  params?: ApplicationParams;
  isLoading: boolean;
  invokeAction: <T = unknown>(actionKey: string, ...args: unknown[]) => Promise<T>;
  navigate: (payload: ShellNavigationPayload) => void;
  showModalDialog?: (options: {
    title: string;
    content: string;
    onConfirm?: () => void;
    onCancel?: () => void;
  }) => boolean;
  showConfirmationDialog?: (options: {
    title: string;
    content: string;
    onConfirm?: (data: unknown) => void;
    onCancel?: () => void;
  }) => boolean;
  showToast?: (
    content: string,
    type: 'success' | 'warning' | 'error' | 'loading' | 'destroy'
  ) => boolean;
  showErrorMessage?: (title: string, content: string) => boolean;
  showRichModal?: (
    path: string,
    context?: unknown,
    size?: ApplicationModalSize,
    closeIconColor?: string
  ) => boolean;
  removeSearchParams?: (keys: string | string[]) => void;
  setSearchParams?: (searchParams: Record<string, string | number>) => void;
  locale: string;
  onLocaleChange: (callback: (newLocale: string) => void) => () => void;
  modalContext?: unknown;
}
```

***

#### FullpageApplicationConfig

Configuration for fullpage applications.

```typescript
interface FullpageApplicationConfig extends ApplicationConfig {
  menu: Page[];
  navigation?: ApplicationNavigation;
}

interface Page {
  path: string;
  label: string | { [language: string]: string };
}

interface ApplicationNavigation {
  navigate: (payload: { path: string }) => void;
}
```

***

#### PluginApplicationConfig

Configuration for plugin applications.

```typescript
interface PluginApplicationConfig extends ApplicationConfig {
  placeholderId: string | string[];
}
```

***

#### ApplicationConfig

Base configuration interface.

```typescript
interface ApplicationConfig {
  isDev?: boolean;
  forceRedirect?: boolean;
}
```

***

#### ShellNavigationPayload

Payload for navigation requests.

```typescript
interface ShellNavigationPayload {
  path: string;
  external?: boolean;
}
```

***

#### ApplicationData

Shared data from the shell.

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

***

#### ApplicationParams

Parameters for plugin applications.

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

***

#### ApplicationModalSize

Modal size configuration.

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

***

#### MultiAppConfig

Configuration for multiple applications.

```typescript
interface MultiAppConfig {
  apps: Record<string, AppConfig>;
  defaultApp?: string;
}

interface AppConfig {
  basePath: string;
  type: 'full_page' | 'plugin';
  config: FullpageApplicationConfig | PluginApplicationConfig;
}
```

***

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

AppClient listens for and emits the following events:

<table><thead><tr><th width="218.17578125">Event</th><th width="167.76953125">Direction</th><th>Description</th></tr></thead><tbody><tr><td><code>SET_CONFIG</code></td><td>Client → Shell</td><td>Client sends its configuration</td></tr><tr><td><code>SET_DATA</code></td><td>Shell → Client</td><td>Shell sends shared data</td></tr><tr><td><code>SET_APP_ID</code></td><td>Shell → Client</td><td>Shell sends app identifier</td></tr><tr><td><code>SET_MODAL_CONTEXT</code></td><td>Shell → Client</td><td>Shell sends modal context</td></tr><tr><td><code>SET_PARAMS</code></td><td>Shell → Client</td><td>Shell sends plugin parameters</td></tr><tr><td><code>INVOKE_ACTION</code></td><td>Client → Shell</td><td>Client invokes custom action</td></tr><tr><td><code>INVOKE_DEFAULT_ACTION</code></td><td>Client → Shell</td><td>Client invokes default action</td></tr><tr><td><code>NAVIGATE</code></td><td>Client → Shell</td><td>Client requests navigation</td></tr><tr><td><code>NAVIGATE_CHILD</code></td><td>Shell → Client</td><td>Shell triggers client navigation</td></tr><tr><td><code>ACTION_CONFIRMED</code></td><td>Shell → Client</td><td>Shell confirms an action</td></tr><tr><td><code>ACTION_CANCELED</code></td><td>Shell → Client</td><td>Shell cancels an action</td></tr><tr><td><code>LOCALE_CHANGED</code></td><td>Shell → Client</td><td>Shell notifies locale change</td></tr><tr><td><code>SET_HEIGHT</code></td><td>Client → Shell</td><td>Client sends iframe height</td></tr></tbody></table>

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

{% hint style="warning" %}
If you navigate using `navigate()` from within a rich modal, the shell automatically navigates the parent client and closes the modal. To navigate within a rich modal without closing it, use your own navigation logic (e.g., React Router).
{% endhint %}

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

* Introduction - Getting started with AppClient
* Hooks - Using the useAppClient hook
* Configuration - Application configuration


---

# 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/client-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.