@gears-frontx/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,590 @@
+import * as React from 'react';
+import React__default, { RefObject } from 'react';
+import { H as HAI3ProviderProps, U as UseTranslationReturn, a as UseScreenTranslationsReturn, b as UseFormattersReturn, c as UseThemeReturn, M as MfeContextValue } from './types-Cp8Zm5s0.js';
+export { d as MfeContext, e as UseAppDispatchReturn, f as UseAppSelector, g as UseHAI3Return, u as useMfeContext } from './types-Cp8Zm5s0.js';
+import { HAI3App, AppDispatch, RootState, TranslationMap, TranslationLoader, ChildMfeBridge, Extension, ContainerProvider, ScreensetsRegistry, ParentMfeBridge, EventPayloadMap as EventPayloadMap$1, EventBus } from '@gears-frontx/framework';
+export { ACCOUNTS_DOMAIN, Action, ActionsChain, ApiPlugin, ApiPluginBase, ApiPluginErrorContext, ApiProtocol, ApiRequestContext, ApiResponseContext, ApiServiceConfig, AppDispatch, BaseApiService, BasePluginHooks, ChangeThemePayload, ChildMfeBridge, ContainerProvider, EventHandler, EventSourceLike, Extension, ExtensionDomain, ExtensionPresentation, ExtensionRegistrationState, FRONTX_ACTION_LOAD_EXT, FRONTX_ACTION_MOUNT_EXT, FRONTX_ACTION_UNMOUNT_EXT, FRONTX_MFE_ENTRY_MF, FRONTX_OVERLAY_DOMAIN, FRONTX_POPUP_DOMAIN, FRONTX_SCREEN_DOMAIN, FRONTX_SCREEN_EXTENSION_TYPE, FRONTX_SHARED_PROPERTY_LANGUAGE, FRONTX_SHARED_PROPERTY_THEME, FRONTX_SIDEBAR_DOMAIN, FooterConfig, FooterState, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, HeaderConfig, HeaderState, HeaderUser, I18nConfig, I18nRegistry, I18nRegistryImpl, I18nRegistryType, JSONSchema, JsonCompatible, JsonObject, JsonPrimitive, JsonValue, LAYOUT_SLICE_NAME, Language, LanguageDisplayMode, LanguageMetadata, LayoutDomain, LayoutDomainReducers, LayoutDomainState, LayoutState, LifecycleHook, LifecycleStage, LoadExtPayload, MOCK_PLUGIN, MenuItem, MenuState, MfeBridgeFactory, MfeEntry, MfeEntryLifecycle, MfeEntryMF, MfeHandler, MfeHandlerMF, MfeState, MockEventSource, MockEvents, MockMap, MockState, MockTogglePayload, MountExtPayload, OverlayConfig, OverlayState, ParentMfeBridge, PluginClass, PluginFactory, PluginLifecycle, PluginProvides, PopupConfig, PopupSliceState, PopupState, Preset, Presets, ProtocolClass, ProtocolPluginType, ReducerPayload, RegisterExtensionPayload, RestMockConfig, RestMockPlugin, RestPlugin, RestPluginHooks, RestPluginWithConfig, RestProtocol, RestProtocolConfig, RestRequestContext, RestResponseContext, RestShortCircuitResponse, RootState, RootStateWithLayout, SUPPORTED_LANGUAGES, ScreenExtension, ScreenState, ScreensetsConfig, ScreensetsRegistry, ScreensetsRegistryConfig, ScreensetsRegistryFactory, SetLanguagePayload, SharedProperty, ShortCircuitResponse, ShowPopupPayload, SidebarPosition, SidebarState, SliceObject, SseConnectContext, SseMockConfig, SseMockEvent, SseMockPlugin, SsePlugin, SsePluginHooks, SsePluginWithConfig, SseProtocol, SseProtocolConfig, SseShortCircuitResponse, Subscription, TENANT_SLICE_NAME, Tenant, TenantChangedPayload, TenantClearedPayload, TenantEvents, TenantState, TextDirection, ThemeConfig, ThemeRegistry, TranslationDictionary, TranslationLoader, TranslationMap, TypeSystemPlugin, UnmountExtPayload, UnregisterExtensionPayload, ValidationError, ValidationResult, apiRegistry, changeTenant, clearActiveScreen, clearTenant, clearTenantAction, clearUser, closeAllPopups, closePopup, closeTopPopup, createHAI3, createHAI3App, createI18nRegistry, createShadowRoot, createSlice, createStore, createThemeRegistry, effects, extensionScreenSchema, extractGtsPackage, footerActions, footerSlice, getLanguageMetadata, getStore, gtsPlugin, hasSlice, headerActions, headerSlice, hideOverlay, i18n, i18nRegistry, initMockEffects, initTenantEffects, injectCssVariables, isMockPlugin, isRestShortCircuit, isShortCircuit, isSseShortCircuit, languageSchema, layout, layoutDomainReducers, layoutReducer, loadExtension, menuActions, menuSlice, microfrontends, mock, mockActions, mockSlice, mountExtension, navigateTo, openPopup, overlayActions, overlayDomain, overlaySlice, popupActions, popupDomain, popupSlice, presets, registerExtension, registerSlice, screenActions, screenDomain, screenSlice, screensets, screensetsRegistryFactory, selectExtensionError, selectExtensionState, selectRegisteredExtensions, setActiveScreen, setFooterConfig, setFooterVisible, setHeaderLoading, setMenuCollapsed, setMenuConfig, setMenuItems, setMenuVisible, setMockEnabled, setOverlayVisible, setScreenLoading, setSidebarCollapsed, setSidebarConfig, setSidebarContent, setSidebarPosition, setSidebarTitle, setSidebarVisible, setSidebarWidth, setTenant, setTenantLoading, setTenantLoadingState, setUser, showOverlay, sidebarActions, sidebarDomain, sidebarSlice, tenantActions, tenantReducer, tenantSlice, themeSchema, themes, toggleMenu, toggleMockMode, toggleSidebar, unmountExtension, unregisterExtension } from '@gears-frontx/framework';
+import { TypedUseSelectorHook } from 'react-redux';
+
+/**
+ * HAI3 Provider - Main provider component for HAI3 applications
+ *
+ * React Layer: L3 (Depends on @gears-frontx/framework)
+ */
+
+/**
+ * HAI3 Provider Component
+ *
+ * Provides the HAI3 application context to all child components.
+ * Creates the HAI3 app instance with the full preset by default.
+ *
+ * @example
+ * ```tsx
+ * // Default - creates app with full preset
+ * <HAI3Provider>
+ *   <App />
+ * </HAI3Provider>
+ *
+ * // With configuration
+ * <HAI3Provider config={{ devMode: true }}>
+ *   <App />
+ * </HAI3Provider>
+ *
+ * // With pre-built app
+ * const app = createHAI3().use(screensets()).use(microfrontends()).build();
+ * <HAI3Provider app={app}>
+ *   <App />
+ * </HAI3Provider>
+ *
+ * // With MFE bridge (for MFE components)
+ * <HAI3Provider mfeBridge={{ bridge, extensionId, domainId }}>
+ *   <MyMfeApp />
+ * </HAI3Provider>
+ * ```
+ */
+declare const HAI3Provider: React__default.FC<HAI3ProviderProps>;
+
+/**
+ * HAI3 Context
+ * Holds the HAI3 app instance for the application.
+ */
+declare const HAI3Context: React.Context<HAI3App | null>;
+/**
+ * Use the HAI3 context.
+ * Throws if used outside of HAI3Provider.
+ *
+ * @returns The HAI3 app instance
+ */
+declare function useHAI3(): HAI3App;
+
+/**
+ * useAppDispatch Hook - Type-safe dispatch hook
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Type-safe dispatch hook.
+ *
+ * @returns The typed dispatch function
+ *
+ * @example
+ * ```tsx
+ * const dispatch = useAppDispatch();
+ * dispatch(someAction());
+ * ```
+ */
+declare function useAppDispatch(): AppDispatch;
+
+/**
+ * useAppSelector Hook - Type-safe selector hook
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Type-safe selector hook.
+ *
+ * @example
+ * ```tsx
+ * const activeScreen = useAppSelector(selectActiveScreen);
+ * const menuCollapsed = useAppSelector(selectMenuCollapsed);
+ * ```
+ */
+declare const useAppSelector: TypedUseSelectorHook<RootState>;
+
+/**
+ * useTranslation Hook - Translation utilities
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for accessing translation utilities.
+ *
+ * @returns Translation utilities
+ *
+ * @example
+ * ```tsx
+ * const { t, language, setLanguage, isRTL } = useTranslation();
+ *
+ * return (
+ *   <div dir={isRTL ? 'rtl' : 'ltr'}>
+ *     <h1>{t('common:app.title')}</h1>
+ *     <p>{t('common:app.welcome', { name: 'John' })}</p>
+ *   </div>
+ * );
+ * ```
+ */
+declare function useTranslation(): UseTranslationReturn;
+
+/**
+ * useScreenTranslations Hook - Screen-level translation loading
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for loading screen-level translations.
+ * Use this in screen components to lazy-load translations.
+ * Automatically reloads translations when language changes.
+ *
+ * @param screensetId - The screenset ID
+ * @param screenId - The screen ID
+ * @param translations - Either a TranslationMap object or a TranslationLoader function
+ *   (from I18nRegistry.createLoader)
+ * @returns Loading state
+ *
+ * @example
+ * ```tsx
+ * // Option 1: Using I18nRegistry.createLoader (recommended)
+ * const translations = I18nRegistry.createLoader({
+ *   en: () => import('./i18n/en.json'),
+ *   es: () => import('./i18n/es.json'),
+ * });
+ *
+ * // Option 2: Using raw TranslationMap
+ * const translations = {
+ *   en: () => import('./i18n/en.json'),
+ *   es: () => import('./i18n/es.json'),
+ * };
+ *
+ * export const HomeScreen: React.FC = () => {
+ *   const { isLoaded, error } = useScreenTranslations(
+ *     'demo',
+ *     'home',
+ *     translations
+ *   );
+ *
+ *   if (!isLoaded) return <LoadingSpinner />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *
+ *   return <div>...</div>;
+ * };
+ * ```
+ */
+declare function useScreenTranslations(screensetId: string, screenId: string, translations: TranslationMap | TranslationLoader): UseScreenTranslationsReturn;
+
+/**
+ * useFormatters Hook - Locale-aware formatters
+ *
+ * Returns formatters that use i18nRegistry.getLanguage() internally.
+ * Calls useTranslation() so the component re-renders when language changes.
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for accessing locale-aware formatters (date, number, currency, sort).
+ *
+ * Formatters use the current app language from i18nRegistry.getLanguage().
+ * Re-renders when language changes via useTranslation() subscription.
+ *
+ * @returns Object with formatDate, formatTime, formatDateTime, formatRelative,
+ *   formatNumber, formatPercent, formatCompact, formatCurrency, compareStrings, createCollator
+ *
+ * @example
+ * ```tsx
+ * const { formatDate, formatCurrency } = useFormatters();
+ * return (
+ *   <span>{formatDate(new Date(), 'short')}</span>
+ *   <span>{formatCurrency(99.99, 'USD')}</span>
+ * );
+ * ```
+ */
+declare function useFormatters(): UseFormattersReturn;
+
+/**
+ * useTheme Hook - Theme utilities
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for theme utilities.
+ *
+ * @returns Theme utilities
+ *
+ * @example
+ * ```tsx
+ * const { currentTheme, themes, setTheme } = useTheme();
+ *
+ * return (
+ *   <select
+ *     value={currentTheme}
+ *     onChange={(e) => setTheme(e.target.value)}
+ *   >
+ *     {themes.map((theme) => (
+ *       <option key={theme.id} value={theme.id}>
+ *         {theme.name}
+ *       </option>
+ *     ))}
+ *   </select>
+ * );
+ * ```
+ */
+declare function useTheme(): UseThemeReturn;
+
+/**
+ * MFE Provider - Provides MFE context to child components
+ *
+ * Wraps MFE components with bridge and metadata.
+ * Used by the MFE mounting system.
+ *
+ * React Layer: L3 (Depends on @gears-frontx/framework)
+ */
+
+/**
+ * MFE Provider Props
+ */
+interface MfeProviderProps {
+    /** MFE context value */
+    value: MfeContextValue;
+    /** Child components */
+    children: React__default.ReactNode;
+}
+/**
+ * MFE Provider Component
+ *
+ * Provides MFE bridge and metadata to child components.
+ * Used by the MFE mounting system to wrap MFE components.
+ *
+ * @example
+ * ```tsx
+ * <MfeProvider value={{ bridge, extensionId, domainId }}>
+ *   <MyMfeComponent />
+ * </MfeProvider>
+ * ```
+ */
+declare const MfeProvider: React__default.FC<MfeProviderProps>;
+
+/**
+ * useMfeBridge Hook - MFE bridge access
+ *
+ * Returns the ChildMfeBridge from context for communication with host.
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for accessing the MFE bridge.
+ *
+ * Returns the ChildMfeBridge instance for communication with the host.
+ * Must be used within a MfeProvider (i.e., inside an MFE component).
+ *
+ * @returns Child MFE bridge
+ *
+ * @example
+ * ```tsx
+ * function MyMfeComponent() {
+ *   const bridge = useMfeBridge();
+ *
+ *   // Bridge methods:
+ *   // bridge.executeActionsChain(chain);
+ *   // bridge.subscribeToProperty(propertyTypeId, callback);
+ *
+ *   return <div>Domain: {bridge.domainId}</div>;
+ * }
+ * ```
+ */
+declare function useMfeBridge(): ChildMfeBridge;
+
+/**
+ * useSharedProperty Hook - Shared property subscription
+ *
+ * Subscribes to shared property updates from the host.
+ *
+ * React Layer: L3
+ */
+/**
+ * Hook for subscribing to a shared property.
+ *
+ * Subscribes to property updates from the host and returns the current value.
+ * Must be used within a MfeProvider (i.e., inside an MFE component).
+ *
+ * NOTE: This hook provides the interface and uses useSyncExternalStore with a stub subscription.
+ * Full bridge subscription should be implemented when bridge methods are available.
+ *
+ * @param _propertyTypeId - Type ID of the shared property to subscribe to (currently unused)
+ * @returns Current property value
+ *
+ * @example
+ * ```tsx
+ * function MyMfeComponent() {
+ *   const userData = useSharedProperty('gts.frontx.mfes.comm.shared_property.v1~myapp.user_data.v1');
+ *
+ *   return <div>User: {userData?.name}</div>;
+ * }
+ * ```
+ */
+declare function useSharedProperty<T = unknown>(propertyTypeId: string): T | undefined;
+
+/**
+ * useHostAction Hook - Host action requests
+ *
+ * Returns a callback to request host actions via the bridge.
+ *
+ * React Layer: L3
+ */
+/**
+ * Hook for requesting host actions.
+ *
+ * Returns a callback function that sends an actions chain to the host.
+ * Must be used within a MfeProvider (i.e., inside an MFE component).
+ *
+ * NOTE: This hook provides the interface. Bridge executeActionsChain() delegates to the registry.
+ *
+ * @param actionTypeId - Type ID of the action to request
+ * @returns Callback function to request the action with payload
+ *
+ * @example
+ * ```tsx
+ * function MyMfeComponent() {
+ *   const requestNavigation = useHostAction('gts.frontx.mfes.comm.action.v1~myapp.navigate.v1');
+ *
+ *   const handleClick = () => {
+ *     requestNavigation({ path: '/dashboard' });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Navigate</button>;
+ * }
+ * ```
+ */
+declare function useHostAction<TPayload extends Record<string, unknown> = Record<string, unknown>>(actionTypeId: string): (payload?: TPayload) => void;
+
+/**
+ * useDomainExtensions Hook - Domain extension list subscription
+ *
+ * Subscribes to store changes to detect when extensions are registered or unregistered,
+ * and returns the current list of extensions for a domain.
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for observing extensions registered for a domain.
+ *
+ * Subscribes to the HAI3 store to detect registration state changes,
+ * and returns the current list of extensions for the specified domain.
+ *
+ * @param domainId - Domain ID to query extensions for
+ * @returns Array of extensions currently registered for the domain
+ *
+ * @example
+ * ```tsx
+ * function SidebarExtensions() {
+ *   const extensions = useDomainExtensions('gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1');
+ *
+ *   return (
+ *     <div>
+ *       {extensions.map(ext => (
+ *         <div key={ext.id}>{ext.id}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useDomainExtensions(domainId: string): Extension[];
+
+/**
+ * useRegisteredPackages Hook - Registered GTS packages subscription
+ *
+ * Subscribes to store changes to detect when extensions are registered or unregistered,
+ * and returns the current list of registered GTS packages.
+ *
+ * React Layer: L3
+ */
+/**
+ * Hook for observing registered GTS packages.
+ *
+ * Subscribes to the HAI3 store to detect registration state changes,
+ * and returns the current list of GTS packages extracted from registered
+ * extensions.
+ *
+ * ARCHITECTURAL NOTE ON STORE SUBSCRIPTION COUPLING:
+ * This hook uses `useSyncExternalStore` with `app.store.subscribe`, which
+ * fires on any Redux dispatch. Since `registerExtension()` dispatches to
+ * the mfe store slice, the subscription WILL trigger when packages change.
+ * The `getSnapshot` function calls `screensetsRegistry.getRegisteredPackages()`
+ * which reads the private `packages` Map. This works because every package
+ * map mutation (in registerExtension/unregisterExtension) is always
+ * accompanied by a store dispatch in the same serializer callback.
+ *
+ * IMPORTANT: If a future change mutates the packages map WITHOUT a store
+ * dispatch, this hook would fail to re-render. Keep this coupling documented.
+ *
+ * @returns Array of GTS package strings currently registered
+ *
+ * @example
+ * ```tsx
+ * function PackageList() {
+ *   const packages = useRegisteredPackages();
+ *
+ *   return (
+ *     <div>
+ *       {packages.map(pkg => (
+ *         <div key={pkg}>{pkg}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useRegisteredPackages(): string[];
+
+/**
+ * useActivePackage Hook - Active GTS package subscription
+ *
+ * Subscribes to store changes and returns the GTS package of the currently
+ * mounted screen extension.
+ *
+ * React Layer: L3
+ */
+/**
+ * Hook for observing the active GTS package (the package of the currently
+ * mounted screen extension).
+ *
+ * Subscribes to the HAI3 store to detect mount state changes, and returns
+ * the GTS package extracted from the currently mounted screen extension's ID.
+ *
+ * Returns `undefined` if no screen extension is currently mounted.
+ *
+ * @returns GTS package string of the active screen extension, or undefined
+ *
+ * @example
+ * ```tsx
+ * function ActivePackageIndicator() {
+ *   const activePackage = useActivePackage();
+ *
+ *   if (!activePackage) {
+ *     return <div>No active screen</div>;
+ *   }
+ *
+ *   return <div>Active package: {activePackage}</div>;
+ * }
+ * ```
+ */
+declare function useActivePackage(): string | undefined;
+
+/**
+ * Ref Container Provider
+ *
+ * Concrete ContainerProvider that wraps a React ref.
+ * Created by React components (like ExtensionDomainSlot) for use
+ * by framework-level domain registration code.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Concrete ContainerProvider that wraps a React ref.
+ *
+ * This provider reads the container element from a React ref at mount time.
+ * It is designed to be created by React components but passed to domain
+ * registration code (framework-level).
+ *
+ * Usage pattern:
+ * 1. React component creates a ref via `useRef<HTMLDivElement>(null)`
+ * 2. Framework-level code creates `RefContainerProvider` wrapping the ref
+ * 3. Framework-level code passes the provider to `registerDomain(domain, provider)`
+ * 4. When mount_ext is dispatched, the provider returns `ref.current`
+ */
+declare class RefContainerProvider extends ContainerProvider {
+    private readonly containerRef;
+    constructor(containerRef: RefObject<HTMLDivElement>);
+    getContainer(_extensionId: string): Element;
+    releaseContainer(_extensionId: string): void;
+}
+
+/**
+ * Extension Domain Slot Component
+ *
+ * React component that renders extensions within a domain slot.
+ * Manages extension lifecycle (mount/unmount) and provides rendering context.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Props for ExtensionDomainSlot component
+ */
+interface ExtensionDomainSlotProps {
+    /**
+     * The screensets registry instance
+     */
+    registry: ScreensetsRegistry;
+    /**
+     * The domain ID for this slot
+     */
+    domainId: string;
+    /**
+     * The extension ID to render in this slot
+     */
+    extensionId: string;
+    /**
+     * Optional CSS class name for the container
+     */
+    className?: string;
+    /**
+     * Optional callback when extension is mounted
+     */
+    onMounted?: (bridge: ParentMfeBridge) => void;
+    /**
+     * Optional callback when extension is unmounted
+     */
+    onUnmounted?: () => void;
+    /**
+     * Optional error callback
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Optional loading component
+     */
+    loadingComponent?: React__default.ReactNode;
+    /**
+     * Optional error component renderer
+     */
+    errorComponent?: (error: Error) => React__default.ReactNode;
+}
+/**
+ * Extension Domain Slot Component
+ *
+ * Renders an extension within a domain slot. Manages the extension lifecycle:
+ * - Mounts the extension on component mount
+ * - Unmounts the extension on component unmount
+ * - Handles loading and error states
+ *
+ * @example
+ * ```tsx
+ * <ExtensionDomainSlot
+ *   registry={registry}
+ *   domainId="gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1"
+ *   extensionId="gts.frontx.mfes.ext.extension.v1~myapp.sidebar.widget.v1"
+ *   className="sidebar-slot"
+ * />
+ * ```
+ */
+declare function ExtensionDomainSlot(props: ExtensionDomainSlotProps): React__default.ReactElement;
+
+/**
+ * @gears-frontx/react - React Bindings
+ *
+ * This package provides:
+ * - HAI3Provider context provider
+ * - Type-safe hooks for state and actions
+ * - MFE context, hooks, and components
+ *
+ * Layer: L3 (Depends on @gears-frontx/framework)
+ */
+
+interface EventPayloadMap extends EventPayloadMap$1 {
+}
+/**
+ * Re-export eventBus with augmented EventPayloadMap type.
+ * This ensures that code importing eventBus from @gears-frontx/react gets
+ * type-safe access to both framework events and app-layer augmented events.
+ */
+declare const eventBus: EventBus<EventPayloadMap>;
+
+export { type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, HAI3Context, HAI3Provider, HAI3ProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, RefContainerProvider, UseFormattersReturn, UseScreenTranslationsReturn, UseThemeReturn, UseTranslationReturn, eventBus, useActivePackage, useAppDispatch, useAppSelector, useDomainExtensions, useFormatters, useHAI3, useHostAction, useMfeBridge, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };