@gears-frontx/react 0.1.0 → 0.2.0-alpha.2

package/commands/hai3-new-mfe.md

@@ -1,166 +0,0 @@
-<!-- @standalone -->
-# hai3:new-mfe - Create New Microfrontend Package
-
-## PREREQUISITES (CRITICAL - STOP IF FAILED)
-
-1. MFE must be associated with a screenset
-2. Screenset must exist (run `hai3-new-screenset` first if needed)
-3. Vite and Module Federation must be configured
-
-## QUICK START
-
-For a screenset named `{screensetName}` with a new MFE:
-
-```bash
-# 1. Create the MFE package in src/mfe_packages/{screensetName}-mfe/
-cp -r packages/cli/template-sources/mfe-package/ src/mfe_packages/{screensetName}-mfe/
-
-# 2. Update variables in package.json and vite.config.ts:
-#    - Replace {{mfeName}} with your screenset name (camelCase)
-#    - Replace {{port}} with available port (3001, 3010, 3020, etc)
-#    - IMPORTANT: set preview script to "vite preview --port {{port}}"
-
-# 3. Install dependencies
-cd src/mfe_packages/{screensetName}-mfe
-npm install
-
-# 4. Create src/lifecycle.tsx that extends ThemeAwareReactLifecycle
-
-# 5. Regenerate MFE manifests so bootstrap.ts picks up the new package
-npm run generate:mfe-manifests
-```
-
-## CONFIGURATION REQUIREMENTS
-
-✅ **Correct preview script** (required for port auto-discovery):
-```json
-"preview": "vite preview --port {{port}}"
-```
-
-✅ **Correct dev script** (for hot reload):
-```json
-"dev": "vite --port {{port}}"
-```
-
-❌ **WRONG** (don't use this for dev):
-```json
-"dev": "vite build && vite preview --port {{port}}"
-```
-
-## PORT ALLOCATION
-
-Reserve ports for MFE packages:
-- **3001**: demo-mfe
-- **3010+**: (next available: 3010, 3020, 3030, ...)
-- **5173**: Main app
-
-## LIFECYCLE TEMPLATE
-
-Create `src/lifecycle.tsx`:
-
-```typescript
-import React from 'react';
-import type { ChildMfeBridge } from '@gears-frontx/react';
-import { ThemeAwareReactLifecycle } from '@gears-frontx/screensets/mfe/handler';
-import { YourScreen } from './screens/YourScreen';
-
-class Lifecycle extends ThemeAwareReactLifecycle {
-  constructor() {
-    super({
-      name: '{screensetName}',
-      version: '1.0.0',
-    });
-  }
-
-  async mount(shadowRoot: ShadowRoot, bridge: ChildMfeBridge) {
-    const div = document.createElement('div');
-    shadowRoot.appendChild(div);
-
-    const style = document.createElement('style');
-    style.textContent = tailwindStyles;
-    shadowRoot.appendChild(style);
-
-    // Render component
-    const root = ReactDOM.createRoot(div);
-    root.render(<YourScreen bridge={bridge} />);
-
-    return { root, div };
-  }
-}
-
-export default new Lifecycle();
-```
-
-## dev:all INTEGRATION (AUTOMATIC)
-
-After creating the MFE and running `npm run generate:mfe-manifests`, the `dev:all`
-script auto-discovers your new package — no manual configuration needed.
-
-`dev-all.ts` scans `src/mfe_packages/*/package.json` and reads the port from the
-`preview` (or `dev`) script using `--port NNNN`. The new MFE will automatically
-appear in the next `npm run dev:all` run.
-
-## VALIDATION
-
-After creation:
-
-```bash
-# Regenerate manifests (required after adding new MFE)
-npm run generate:mfe-manifests
-
-# Validate TypeScript
-npm run type-check
-
-# Check architecture compliance
-npm run arch:check
-
-# Run the dev server (picks up new MFE automatically)
-npm run dev:all
-
-# Verify MFE loads at http://localhost:5173
-# Open Studio Overlay (Ctrl+`) and check screenset
-```
-
-## TROUBLESHOOTING
-
-### Issue: MFE not appearing in screenset selector
-- Run `npm run generate:mfe-manifests` to regenerate manifests
-- Check mfe.json manifest is properly exported
-- Verify extensions are registered in manifest
-- Check browser console for errors
-
-### Issue: dev:all not picking up MFE port
-- Verify `preview` script has `--port NNNN` (e.g., `"vite preview --port 3010"`)
-- Check port is not in use (`lsof -i :3010`)
-- Restart dev server
-
-### Issue: Hot reload not working
-- Verify dev script uses `vite --port` (not `vite build && vite preview`)
-- Check port is not in use
-- Restart dev server
-
-### Issue: Redux/useSelector errors
-- MFE must use mock data (no Redux Provider in isolation)
-- Use `useState` for local state management
-- Do not import Redux hooks (@gears-frontx/react)
-
-## BEST PRACTICES
-
-✅ **DO:**
-- Set `preview` script with `--port NNNN` for port auto-discovery
-- Use mock data with useState for UI-only MFEs
-- Keep MFE logic isolated and simple
-- Use local components (e.g. components/ui/)
-- Run `npm run generate:mfe-manifests` after creating the MFE
-
-❌ **DON'T:**
-- Import Redux hooks directly
-- Use vite build && vite preview in dev mode
-- Create complex state management in MFE
-- Hardcode ports without updating package.json preview script
-
----
-
-See also:
-- `/packages/cli/template-sources/mfe-package/` for templates
-- `hai3-new-screenset.md` for screenset creation

package/commands/hai3-new-screen.md

@@ -1,39 +0,0 @@
-<!-- @standalone -->
-# hai3:new-screen - Add New Screen
-
-## AI WORKFLOW (REQUIRED)
-1) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
-2) Gather requirements from user (including UI sections).
-3) Implement.
-
-## GATHER REQUIREMENTS
-Ask user for:
-- Screenset path (e.g., src/screensets/chat).
-- Screen name (camelCase).
-- UI sections (e.g., "header, form, data table").
-- Add to menu? (Y/N)
-
-## STEP 1: Implementation
-1) Add screen ID to ids.ts.
-2) Create components BEFORE screen file per Component Plan.
-3) Create screen following data flow rules from .ai/targets/EVENTS.md:
-   - Use actions to trigger state changes
-   - FORBIDDEN: Direct slice dispatch from screen
-4) Add i18n with useScreenTranslations(). Export default.
-5) Add to menu if requested.
-6) Validate: `npm run type-check && npm run lint`.
-7) Test via Chrome DevTools MCP (REQUIRED):
-   - Navigate to new screen
-   - Verify screen renders without console errors
-   - Test UI interactions and data flow
-   - Verify translations load correctly
-   - STOP if MCP connection fails
-
-## COMPONENT PLAN
-- REQUIRED: Use local components (e.g. `components/ui/`) — no shared UI kit package.
-- components/ui/: base UI primitives (shadcn components or custom)
-- screens/{screen}/components/: screen-specific components
-
-## DATA FLOW
-- Uses existing screenset events/slices per EVENTS.md
-- Screen dispatches actions, never direct slice updates

package/commands/hai3-new-screenset.md

@@ -1,47 +0,0 @@
-<!-- @standalone -->
-# hai3:new-screenset - Create New Screenset
-
-## PREREQUISITES (CRITICAL - STOP IF FAILED)
-Run `hai3 --version`.
-STOP: If fails, tell user to install.
-FORBIDDEN: Creating screenset manually or by copying peers.
-
-## AI WORKFLOW (REQUIRED)
-1) Check prerequisites above.
-2) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
-3) Gather requirements from user (including UI sections).
-4) Implement.
-
-## GATHER REQUIREMENTS
-Ask user for:
-- Screenset name (camelCase).
-- Category: Drafts | Mockups | Production.
-- Initial screens.
-- UI sections per screen (e.g., "stats cards, charts, activity feed").
-
-## STEP 1: Implementation
-1) Create screenset via `hai3 screenset create` (REQUIRED).
-2) Create components BEFORE screen file per Component Plan.
-3) Implement data flow per .ai/targets/EVENTS.md:
-   - Actions emit events via eventBus.emit()
-   - Effects subscribe and update slices
-   - FORBIDDEN: Direct slice dispatch from components
-4) Add API service with mocks.
-5) Validate: `npm run type-check && npm run arch:check && npm run lint`.
-6) Test via Chrome DevTools MCP (REQUIRED):
-   - Navigate to new screenset
-   - Verify screen renders without console errors
-   - Test user interactions trigger correct events
-   - Verify state updates via Redux DevTools
-   - STOP if MCP connection fails
-
-## COMPONENT PLAN
-- REQUIRED: Use local components (e.g. `components/ui/`) — no shared UI kit package.
-- components/ui/: base UI primitives (shadcn components or custom)
-- components/: multi-screen shared components
-- screens/{screen}/components/: screen-specific components
-
-## DATA FLOW
-- Events: {domain events per EVENTS.md}
-- State: slices/, events/, effects/, actions/
-- API: api/{Name}ApiService.ts with mocks

package/dist/types-Cp8Zm5s0.d.cts

@@ -1,136 +0,0 @@
-import * as React from 'react';
-import { ReactNode } from 'react';
-import { ChildMfeBridge, HAI3Config, HAI3App, RootState, Formatters, Language } from '@gears-frontx/framework';
-
-/**
- * MFE Context Value
- * Contains bridge and metadata about the MFE instance.
- */
-interface MfeContextValue {
-    /** Child bridge for communication with host */
-    bridge: ChildMfeBridge;
-    /** Extension ID */
-    extensionId: string;
-    /** Domain ID where MFE is mounted */
-    domainId: string;
-}
-/**
- * MFE Context
- * Holds the MFE bridge and metadata for child components.
- */
-declare const MfeContext: React.Context<MfeContextValue | null>;
-/**
- * Use the MFE context.
- * Throws if used outside of MFE context.
- *
- * @returns The MFE context value
- */
-declare function useMfeContext(): MfeContextValue;
-
-/**
- * @gears-frontx/react - Type Definitions
- *
- * Core types for HAI3 React bindings.
- * Provides type-safe hooks and components.
- *
- * Now using real imports from @gears-frontx/framework since packages are built together.
- */
-
-type Selector<TResult, TState = RootState> = (state: TState) => TResult;
-type TranslationParams = Record<string, string | number | boolean>;
-/**
- * HAI3 Provider Props
- * Props for the main HAI3Provider component.
- *
- * @example
- * ```tsx
- * <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>
- * ```
- */
-interface HAI3ProviderProps {
-    /** Child components */
-    children: ReactNode;
-    /** HAI3 configuration */
-    config?: HAI3Config;
-    /** Pre-built HAI3 app instance (optional) */
-    app?: HAI3App;
-    /** MFE bridge context (for MFE components) */
-    mfeBridge?: MfeContextValue;
-}
-/**
- * useHAI3 Hook Return Type
- * Returns the HAI3 app instance from context.
- */
-type UseHAI3Return = HAI3App;
-/**
- * useAppSelector Hook
- * Type-safe selector hook for Redux state.
- *
- * @template TResult - The result type of the selector
- */
-type UseAppSelector = <TResult>(selector: Selector<TResult>) => TResult;
-/**
- * useAppDispatch Hook Return Type
- * Returns the typed dispatch function.
- */
-type UseAppDispatchReturn = (action: unknown) => unknown;
-/**
- * useTranslation Hook Return Type
- * Translation utilities.
- */
-interface UseTranslationReturn {
-    /** Translate a key */
-    t: (key: string, params?: TranslationParams) => string;
-    /** Current language */
-    language: Language | null;
-    /** Change language */
-    setLanguage: (language: Language) => void;
-    /** Check if current language is RTL */
-    isRTL: boolean;
-}
-/**
- * useScreenTranslations Hook Return Type
- * Screen-level translation loading state.
- */
-interface UseScreenTranslationsReturn {
-    /** Whether translations are loaded */
-    isLoaded: boolean;
-    /** Loading error (if any) */
-    error: Error | null;
-}
-/**
- * useTheme Hook Return Type
- * Theme utilities.
- */
-interface UseThemeReturn {
-    /** Current theme ID */
-    currentTheme: string | undefined;
-    /** All available themes */
-    themes: Array<{
-        id: string;
-        name: string;
-    }>;
-    /** Change theme */
-    setTheme: (themeId: string) => void;
-}
-/**
- * useFormatters Hook Return Type
- * Locale-aware formatters (locale from i18nRegistry.getLanguage()).
- * References @gears-frontx/i18n Formatters so signatures stay in sync.
- */
-type UseFormattersReturn = Formatters;
-
-export { type HAI3ProviderProps as H, type MfeContextValue as M, type UseTranslationReturn as U, type UseScreenTranslationsReturn as a, type UseFormattersReturn as b, type UseThemeReturn as c, MfeContext as d, type UseAppDispatchReturn as e, type UseAppSelector as f, type UseHAI3Return as g, useMfeContext as u };

package/dist/types-Cp8Zm5s0.d.ts

@@ -1,136 +0,0 @@
-import * as React from 'react';
-import { ReactNode } from 'react';
-import { ChildMfeBridge, HAI3Config, HAI3App, RootState, Formatters, Language } from '@gears-frontx/framework';
-
-/**
- * MFE Context Value
- * Contains bridge and metadata about the MFE instance.
- */
-interface MfeContextValue {
-    /** Child bridge for communication with host */
-    bridge: ChildMfeBridge;
-    /** Extension ID */
-    extensionId: string;
-    /** Domain ID where MFE is mounted */
-    domainId: string;
-}
-/**
- * MFE Context
- * Holds the MFE bridge and metadata for child components.
- */
-declare const MfeContext: React.Context<MfeContextValue | null>;
-/**
- * Use the MFE context.
- * Throws if used outside of MFE context.
- *
- * @returns The MFE context value
- */
-declare function useMfeContext(): MfeContextValue;
-
-/**
- * @gears-frontx/react - Type Definitions
- *
- * Core types for HAI3 React bindings.
- * Provides type-safe hooks and components.
- *
- * Now using real imports from @gears-frontx/framework since packages are built together.
- */
-
-type Selector<TResult, TState = RootState> = (state: TState) => TResult;
-type TranslationParams = Record<string, string | number | boolean>;
-/**
- * HAI3 Provider Props
- * Props for the main HAI3Provider component.
- *
- * @example
- * ```tsx
- * <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>
- * ```
- */
-interface HAI3ProviderProps {
-    /** Child components */
-    children: ReactNode;
-    /** HAI3 configuration */
-    config?: HAI3Config;
-    /** Pre-built HAI3 app instance (optional) */
-    app?: HAI3App;
-    /** MFE bridge context (for MFE components) */
-    mfeBridge?: MfeContextValue;
-}
-/**
- * useHAI3 Hook Return Type
- * Returns the HAI3 app instance from context.
- */
-type UseHAI3Return = HAI3App;
-/**
- * useAppSelector Hook
- * Type-safe selector hook for Redux state.
- *
- * @template TResult - The result type of the selector
- */
-type UseAppSelector = <TResult>(selector: Selector<TResult>) => TResult;
-/**
- * useAppDispatch Hook Return Type
- * Returns the typed dispatch function.
- */
-type UseAppDispatchReturn = (action: unknown) => unknown;
-/**
- * useTranslation Hook Return Type
- * Translation utilities.
- */
-interface UseTranslationReturn {
-    /** Translate a key */
-    t: (key: string, params?: TranslationParams) => string;
-    /** Current language */
-    language: Language | null;
-    /** Change language */
-    setLanguage: (language: Language) => void;
-    /** Check if current language is RTL */
-    isRTL: boolean;
-}
-/**
- * useScreenTranslations Hook Return Type
- * Screen-level translation loading state.
- */
-interface UseScreenTranslationsReturn {
-    /** Whether translations are loaded */
-    isLoaded: boolean;
-    /** Loading error (if any) */
-    error: Error | null;
-}
-/**
- * useTheme Hook Return Type
- * Theme utilities.
- */
-interface UseThemeReturn {
-    /** Current theme ID */
-    currentTheme: string | undefined;
-    /** All available themes */
-    themes: Array<{
-        id: string;
-        name: string;
-    }>;
-    /** Change theme */
-    setTheme: (themeId: string) => void;
-}
-/**
- * useFormatters Hook Return Type
- * Locale-aware formatters (locale from i18nRegistry.getLanguage()).
- * References @gears-frontx/i18n Formatters so signatures stay in sync.
- */
-type UseFormattersReturn = Formatters;
-
-export { type HAI3ProviderProps as H, type MfeContextValue as M, type UseTranslationReturn as U, type UseScreenTranslationsReturn as a, type UseFormattersReturn as b, type UseThemeReturn as c, MfeContext as d, type UseAppDispatchReturn as e, type UseAppSelector as f, type UseHAI3Return as g, useMfeContext as u };