# API Reference {#api-reference}


Complete reference of types, injection tokens, interfaces, and helper functions exported by the Plugin UI packages.


## @gauzy/plugin-ui {#gauzyplugin-ui}



### Core Types {#core-types}



#### PluginUiDefinition {#pluginuidefinition}


The main configuration object for a UI plugin.

```typescript
interface PluginUiDefinition {
  id: string;
  module?: Type<any>;
  loadModule?: () => Promise<Type<any>>;
  bootstrap?: (injector: Injector) => void | Promise<void>;
  location?: string;
  plugins?: PluginUiDefinition[];
  options?: Record<string, unknown>;
  routes?: PluginRouteInput[];
  navMenu?: PluginNavContribution[];
  featureKey?: unknown;
  permissionKeys?: unknown[];
  dependsOn?: string[];
  extensions?: PageExtensionDefinition[];
  tabs?: PluginTabInput[];
  translations?: Record<string, Record<string, any>>;
  translationNamespace?: string;
  settings?: PluginSettingsSchema;
  version?: string;
  peerPlugins?: Record<string, string>;
  loadStrategy?: 'eager' | 'lazy' | 'preload';
}
```


#### PluginUiConfig {#pluginuiconfig}


Application-level plugin configuration.

```typescript
interface PluginUiConfig {
  defaultLanguage: string;
  defaultLocale: string;
  fallbackLocale?: string;
  availableLanguages: string[];
  availableLocales: string[];
  startWeekOn?: DayOfWeek;
  plugins: PluginUiDefinition[];
}
```


#### PageExtensionDefinition {#pageextensiondefinition}


Describes a UI extension contributed to an extension slot.

```typescript
interface PageExtensionDefinition {
  id: string;
  slotId: string;
  component?: Type<any>;
  loadComponent?: () => Promise<Type<any>>;
  order?: number;
  title?: string;
  description?: string;
  pluginId?: string;
  hidden?: boolean;
  visible?: (context: ExtensionVisibilityContext) => boolean | Promise<boolean>;
  permissions?: string[];
  permissionsAny?: string[];
  featureKey?: string;
  wrapper?: ExtensionWrapperConfig;
  lifecycle?: ExtensionLifecycleHooks;
  metadata?: ExtensionMetadata;
}
```


#### DayOfWeek {#dayofweek}


```typescript
enum DayOfWeek {
  Sunday = 0,
  Monday = 1,
  Tuesday = 2,
  Wednesday = 3,
  Thursday = 4,
  Friday = 5,
  Saturday = 6
}
```


#### PluginUiServices {#pluginuiservices}


Passed to `PluginUiModule.init()` to bridge the plugin system to the host application:

```typescript
interface PluginUiServices {
  navBuilder?: Type<IDeclarativeNavBuilder>;
  routeRegistry?: Type<IDeclarativePageRouteRegistry>;
  tabRegistry?: Type<IDeclarativePageTabRegistry>;
  translateService?: Type<IPluginTranslateService>;
  permissionChecker?: Type<IPluginPermissionChecker>;
  featureChecker?: Type<IPluginFeatureChecker>;
}
```

All fields are optional. Values are **Angular type references** (classes), not instances.


### Injection Tokens {#injection-tokens}


| Token | Type | Description |
|-------|------|-------------|
| `PLUGIN_UI_CONFIG` | `PluginUiConfig` | The full plugin configuration |
| `PLUGIN_OPTIONS` | `Record<string, unknown>` | Per-plugin options (in plugin's child injector) |
| `PLUGIN_DEFINITION` | `PluginUiDefinition` | The plugin's own definition (in plugin's child injector) |
| `PLUGIN_ACTIVATION_PREDICATE` | `(def: PluginUiDefinition) => boolean` | Custom activation filter |
| `PLUGIN_NAV_BUILDER` | `IDeclarativeNavBuilder` | Navigation menu builder |
| `PLUGIN_ROUTE_REGISTRY` | `IDeclarativePageRouteRegistry` | Route registry |
| `PLUGIN_TAB_REGISTRY` | `IDeclarativePageTabRegistry` | Tab registry |
| `PLUGIN_TRANSLATE_SERVICE` | `IPluginTranslateService` | Translation service |
| `PLUGIN_TRANSLATE_DELEGATE` | `TranslateService` | Backing @ngx-translate/core service |
| `PLUGIN_TRANSLATE_STORE_DELEGATE` | `TranslateStore` | Backing @ngx-translate/core store |
| `PLUGIN_APP_STORE` | `IPluginAppStore` | Backing application store (permissions/features) |
| `PLUGIN_PERMISSION_CHECKER` | `IPluginPermissionChecker` | Permission checker |
| `PLUGIN_FEATURE_CHECKER` | `IPluginFeatureChecker` | Feature flag checker |


### Service Interfaces {#service-interfaces}



#### IPluginPermissionChecker {#ipluginpermissionchecker}


```typescript
interface IPluginPermissionChecker {
  hasAllPermissions(...permissions: string[]): boolean;
}
```


#### IPluginFeatureChecker {#ipluginfeaturechecker}


```typescript
interface IPluginFeatureChecker {
  isFeatureEnabled(featureKey: string): boolean;
}
```


#### IPluginTranslateService {#iplugintranslateservice}


```typescript
interface IPluginTranslateService {
  instant(key: string, params?: Record<string, any>): string;
  get(key: string, params?: Record<string, any>): Observable<string>;
  onLangChange: EventEmitter<{ lang: string }>;
  currentLang: string;
  setTranslation(lang: string, translations: Record<string, any>, shouldMerge?: boolean): void;
}
```


#### IDeclarativeNavBuilder {#ideclarativenavbuilder}


```typescript
interface IDeclarativeNavBuilder {
  addNavMenuItem(item: PluginNavItemInput, sectionId?: string): void;
  removeNavMenuItem(itemId: string): void;
}
```


#### IDeclarativePageRouteRegistry {#ideclarativepagerouteregistry}


```typescript
interface IDeclarativePageRouteRegistry {
  registerPageRoute(route: PluginRouteInput): void;
}
```


#### IDeclarativePageTabRegistry {#ideclarativepagetabregistry}


```typescript
interface IDeclarativePageTabRegistry {
  registerPageTab(tab: PluginTabInput): void;
}
```


### Lifecycle Interfaces {#lifecycle-interfaces}


```typescript
interface IOnPluginUiBootstrap {
  ngOnPluginBootstrap(): void | Promise<void>;
}

interface IOnPluginUiDestroy {
  ngOnPluginDestroy(): void | Promise<void>;
}

interface IOnPluginAfterBootstrap {
  ngOnPluginAfterBootstrap(): void | Promise<void>;
}

interface IOnPluginBeforeDestroy {
  ngOnPluginBeforeDestroy(): void | Promise<void>;
}

interface IOnPluginBeforeRouteActivate {
  ngOnPluginBeforeRouteActivate(): boolean | Promise<boolean>;
}

interface IOnPluginConfigChange {
  ngOnPluginConfigChange(config: Record<string, unknown>): void;
}
```


### Helper Functions {#helper-functions}



#### Plugin Definition {#plugin-definition}


| Function | Signature | Description |
|----------|-----------|-------------|
| `defineDeclarativePlugin` | `(id: string, config: Partial<PluginUiDefinition>) => PluginUiDefinition` | Create a declarative plugin (auto-generates bootstrap callback) |
| `definePlugin` | `(id: string, module: Type \| LazyLoader, options?) => PluginUiDefinition` | Create a module-based plugin (smart loader detection via `typeof fn === 'function' && !fn.prototype`) |
| `definePluginGroup` | `(id: string, module: Type, options: { plugins, ... }) => PluginUiDefinition` | Create a plugin group with `.init()` method |
| `applyDeclarativeRegistrations` | `(def: PluginUiDefinition, services: { navBuilder?, pageRouteRegistry?, pageTabRegistry?, pageExtensionRegistry? }) => void` | Register routes, nav, tabs, and extensions from a definition |
| `getUIPluginModules` | `(defs: PluginUiDefinition[]) => Type<any>[]` | Extract Angular modules from definitions |
| `getUIPluginModulesWithDefinitions` | `(defs: PluginUiDefinition[]) => { module, definition }[]` | Extract modules paired with definitions |


#### Plugin Utilities {#plugin-utilities}


| Function | Signature | Description |
|----------|-----------|-------------|
| `orderPluginsByDependencies` | `(defs: PluginUiDefinition[]) => PluginUiDefinition[]` | Topological sort by dependencies |
| `flattenPlugins` | `(defs: PluginUiDefinition[]) => PluginUiDefinition[]` | Flatten nested plugin groups |
| `collectPluginIds` | `(defs: PluginUiDefinition[]) => Set<string>` | Collect all plugin IDs |
| `isPluginActive` | `(def: PluginUiDefinition) => boolean` | Check activation status |
| `getPluginsByLocation` | `(defs: PluginUiDefinition[], location: string) => PluginUiDefinition[]` | Filter by location |
| `getPluginDefinition` | `(defs: PluginUiDefinition[], id: string) => PluginUiDefinition \| undefined` | Find by ID |


#### Config Management {#config-management}


| Function | Signature | Description |
|----------|-----------|-------------|
| `getPluginUiConfig` | `() => PluginUiConfig` | Get current config |
| `setPluginUiConfig` | `(config: PluginUiConfig) => void` | Set config |
| `resetPluginUiConfig` | `() => void` | Reset to defaults |


#### Dependency Validation {#dependency-validation}


| Function | Signature | Description |
|----------|-----------|-------------|
| `validatePluginDependencies` | `(defs: PluginUiDefinition[]) => ValidationResult` | Validate dependency graph |
| `logDependencyValidation` | `(result: ValidationResult) => void` | Log validation results |
| `checkVersionCompatibility` | `(defs: PluginUiDefinition[]) => CompatResult` | Check peer version ranges |


#### i18n {#i18n}


| Function | Signature | Description |
|----------|-----------|-------------|
| `namespaceTranslations` | `(ns: string, translations: object) => object` | Wrap translations in namespace |
| `filterNewTranslationKeys` | `(existing: object, incoming: object) => object` | Strip existing keys |


#### Events {#events}


| Function | Signature | Description |
|----------|-----------|-------------|
| `definePluginEvent<T>` | `(pluginId: string, eventName: string) => PluginEventContract<T>` | Define a typed event |
| `bindEventToBus` | `(contract: PluginEventContract<T>, bus: PluginEventBusService) => TypedEventHandle<T>` | Bind event to bus |


### Services {#services}


| Service | Description |
|---------|-------------|
| `PluginUiRegistryService` | Central plugin registry |
| `PageExtensionRegistryService` | Extension slot registry |
| `PluginEventBusService` | Cross-plugin event bus |
| `PluginEventSchemaRegistry` | Event schema documentation |
| `PluginSettingsRegistryService` | Plugin settings storage |
| `PluginServiceRegistryService` | Cross-plugin service registry |
| `PluginHealthService` | Boot time and error monitoring |
| `PluginDevToolsService` | Debug introspection |
| `DynamicPluginLoaderService` | Runtime plugin load/unload |
| `UiBridgeRegistryService` | Framework bridge registry |


### Components {#components}


| Component | Selector | Description |
|-----------|----------|-------------|
| `PageExtensionSlotComponent` | `gau-page-extension-slot` | Renders extensions for a slot |


### Constants {#constants}


| Constant | Description |
|----------|-------------|
| `PAGE_EXTENSION_SLOTS` | Well-known slot ID strings |

---


## @gauzy/ui-react {#gauzyui-react}



### Hooks {#hooks}


| Hook | Signature | Description |
|------|-----------|-------------|
| `useInjector` | `() => Injector` | Access Angular injector |
| `useObservable` | `<T>(obs$: Observable<T>, initial: T) => T` | Subscribe to Observable |
| `usePluginState` | `<T>(pluginId, key, initial) => [T, (v: T) => void]` | Shared plugin state |
| `usePluginSettings` | `(pluginId: string) => Record<string, any>` | All plugin settings |
| `usePluginSetting` | `<T>(pluginId, key, defaultValue) => T` | Single setting value |
| `useTranslation` | `() => { t, currentLang }` | Reactive translations |
| `usePluginEvents` | `() => PluginEventBusService` | Raw event bus access |
| `usePluginEvent` | `(eventName: string) => { emit, on }` | Basic event handle |
| `useTypedEvent` | `<T>(contract) => TypedEventHandle<T>` | Type-safe event handle |
| `useTypedEventListener` | `<T>(contract, callback) => void` | Auto-subscribed listener |
| `useDynamicPlugin` | `(pluginId) => { load, unload, isLoaded }` | Dynamic plugin control |


### Components & Directives {#components--directives}


| Export | Description |
|--------|-------------|
| `ReactHostDirective` | `[gaReactHost]` — mount React in Angular |
| `LazyReactHostDirective` | `[gaReactLazyHost]` — lazy mount React in Angular |
| `PluginErrorBoundary` | React error boundary with recovery |
| `NgContextProvider` | React context providing Angular injector |
| `NgBridgeContext` | React context object |
| `useBridgeContext` | Access bridge context from React |


### Bridge {#bridge}


| Export | Description |
|--------|-------------|
| `ReactBridge` | Bridge class with mount/unmount |
| `createReactBridge` | Factory function |
| `provideReactBridge` | Angular provider helper |
| `REACT_BRIDGE` | Injection token |


### Extension Helpers {#extension-helpers}


| Function | Description |
|----------|-------------|
| `defineReactExtension(config)` | Create eager React extension definition |
| `defineLazyReactExtension(config)` | Create lazy React extension definition |
| `isReactExtension(ext)` | Type guard for React extensions |

---


## @gauzy/ui-react-components {#gauzyui-react-components}



### Components {#components-1}


| Component | Props | Description |
|-----------|-------|-------------|
| `Card` | `CardProps` (`variant?: 'default' \| 'accent'`) | Card container |
| `CardHeader` | — | Card header section |
| `CardTitle` | — | Card title text |
| `CardDescription` | — | Card description text |
| `CardAction` | — | Card action area |
| `CardContent` | — | Card body content |
| `CardFooter` | — | Card footer section |
| `WidgetCard` | Widget-specific props | Pre-styled stat card |
| `Progress` | `ProgressProps` (`value: number`) | Progress bar |
| `ColorDots` | `ColorDotsProps` | Color indicator dots |


### Design Tokens {#design-tokens}


```typescript
import { theme } from '@gauzy/ui-react-components';

theme.colors     // { primary, textPrimary, textSecondary, background, border, ... }
theme.shadows    // { card, elevated }
theme.spacing    // { xs, sm, md, lg, xl }
theme.fonts      // { family, sizeBase, sizeSmall, sizeLarge }
theme.radii      // { sm, md, lg }
```


### Utilities {#utilities}


| Function | Description |
|----------|-------------|
| `formatDuration(seconds: number)` | Format seconds as "Xh Ym" |
| `currentWeekRange()` | Get current week start/end dates |
| `todayRange()` | Get today's start/end timestamps |