@gears-frontx/react 0.1.0

package/CLAUDE.md

@@ -0,0 +1,421 @@
+# @gears-frontx/react
+
+React bindings and hooks for HAI3 applications. Provides the React integration layer with MFE (Microfrontend) support.
+
+## React Layer
+
+This package is part of the **React Layer (L3)** - it depends only on @gears-frontx/framework (not directly on SDK packages) and provides React-specific components and hooks.
+
+## Core Concepts
+
+### HAI3Provider
+
+Wrap your app with HAI3Provider to enable all hooks:
+
+```tsx
+import { HAI3Provider } from '@gears-frontx/react';
+
+function App() {
+  return (
+    <HAI3Provider>
+      <YourApp />
+    </HAI3Provider>
+  );
+}
+
+// With configuration
+<HAI3Provider config={{ devMode: true }}>
+  <YourApp />
+</HAI3Provider>
+
+// With pre-built app
+const app = createHAI3().use(screensets()).build();
+<HAI3Provider app={app}>
+  <YourApp />
+</HAI3Provider>
+```
+
+### Available Hooks
+
+#### useHAI3
+
+Access the HAI3 app instance:
+
+```tsx
+import { useHAI3 } from '@gears-frontx/react';
+
+function MyComponent() {
+  const app = useHAI3();
+
+  // Access MFE-enabled registry
+  const extensions = app.screensetsRegistry.getRegisteredExtensions();
+
+  // Access MFE actions
+  await app.actions.loadExtension({ extensionId: 'home' });
+  await app.actions.mountExtension({ extensionId: 'home', domainId: 'screen', container });
+}
+```
+
+#### useAppDispatch / useAppSelector
+
+Type-safe Redux hooks:
+
+```tsx
+import { useAppDispatch, useAppSelector } from '@gears-frontx/react';
+
+function MyComponent() {
+  const dispatch = useAppDispatch();
+  const activeScreen = useAppSelector((state) => state.layout.screen.activeScreen);
+}
+```
+
+#### useTranslation
+
+Access translation utilities:
+
+```tsx
+import { useTranslation } from '@gears-frontx/react';
+
+function MyComponent() {
+  const { t, language, setLanguage, isRTL } = useTranslation();
+
+  return (
+    <div dir={isRTL ? 'rtl' : 'ltr'}>
+      <h1>{t('common:title')}</h1>
+      <p>{t('common:welcome', { name: 'John' })}</p>
+    </div>
+  );
+}
+```
+
+#### useScreenTranslations
+
+Load screen-level translations:
+
+```tsx
+import { useScreenTranslations } from '@gears-frontx/react';
+
+const translations = {
+  en: () => import('./i18n/en.json'),
+  es: () => import('./i18n/es.json'),
+};
+
+function HomeScreen() {
+  const { isLoaded, error } = useScreenTranslations('demo', 'home', translations);
+
+  if (!isLoaded) return <Loading />;
+  if (error) return <Error error={error} />;
+
+  return <div>...</div>;
+}
+```
+
+#### useTheme
+
+Access theme utilities:
+
+```tsx
+import { useTheme } from '@gears-frontx/react';
+
+function ThemeToggle() {
+  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>
+  );
+}
+```
+
+### MFE Hooks
+
+#### useMfeBridge
+
+Access the MFE bridge for child MFEs:
+
+```tsx
+import { useMfeBridge } from '@gears-frontx/react';
+import { HAI3_ACTION_LOAD_EXT, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+
+function MyExtension() {
+  const bridge = useMfeBridge();
+
+  // Execute actions chain on parent
+  await bridge.executeActionsChain({
+    action: { type: HAI3_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
+  });
+
+  // Get shared property
+  const theme = bridge.getProperty(HAI3_SHARED_PROPERTY_THEME);
+}
+```
+
+#### useSharedProperty
+
+Subscribe to shared property changes:
+
+```tsx
+import { useSharedProperty, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+
+function ThemedComponent() {
+  const theme = useSharedProperty(HAI3_SHARED_PROPERTY_THEME);
+
+  return <div style={{ backgroundColor: theme?.primaryColor }}>...</div>;
+}
+```
+
+#### useHostAction
+
+Invoke actions on the host application:
+
+```tsx
+import { useHostAction, HAI3_ACTION_LOAD_EXT } from '@gears-frontx/react';
+
+function MyExtension() {
+  const loadExtension = useHostAction(HAI3_ACTION_LOAD_EXT);
+
+  const handleClick = () => {
+    loadExtension({ extensionId: 'other' });
+  };
+
+  return <button onClick={handleClick}>Load Extension</button>;
+}
+```
+
+#### useDomainExtensions
+
+Subscribe to extensions in a domain:
+
+```tsx
+import { useDomainExtensions } from '@gears-frontx/react';
+
+function ScreenList() {
+  const screenExtensions = useDomainExtensions('screen');
+
+  return (
+    <ul>
+      {screenExtensions.map((ext) => (
+        <li key={ext.id}>{ext.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+#### useRegisteredPackages
+
+Subscribe to registered GTS packages:
+
+```tsx
+import { useRegisteredPackages } from '@gears-frontx/react';
+
+function PackageList() {
+  const packages = useRegisteredPackages();
+
+  return (
+    <ul>
+      {packages.map((pkg) => (
+        <li key={pkg}>{pkg}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+#### useActivePackage
+
+Subscribe to the active GTS package (the package of the currently mounted screen extension):
+
+```tsx
+import { useActivePackage } from '@gears-frontx/react';
+
+function ActivePackageIndicator() {
+  const activePackage = useActivePackage();
+
+  if (!activePackage) {
+    return <div>No active screen</div>;
+  }
+
+  return <div>Active: {activePackage}</div>;
+}
+```
+
+### MFE Components
+
+#### MfeProvider
+
+Provide MFE context for child extensions:
+
+```tsx
+import { MfeProvider } from '@gears-frontx/react';
+
+function MfeHost() {
+  return (
+    <MfeProvider bridge={parentBridge}>
+      <ExtensionContainer />
+    </MfeProvider>
+  );
+}
+```
+
+#### ExtensionDomainSlot
+
+Render extensions into a domain slot:
+
+```tsx
+import { ExtensionDomainSlot } from '@gears-frontx/react';
+
+function LayoutScreen() {
+  return (
+    <div>
+      <ExtensionDomainSlot
+        domainId="screen"
+        containerRef={screenContainerRef}
+        fallback={<Loading />}
+      />
+    </div>
+  );
+}
+```
+
+#### RefContainerProvider
+
+Provide container references for MFE mounting:
+
+```tsx
+import { RefContainerProvider } from '@gears-frontx/react';
+
+function Layout() {
+  return (
+    <RefContainerProvider>
+      <ScreenContainer />
+      <SidebarContainer />
+    </RefContainerProvider>
+  );
+}
+```
+
+### Components
+
+## Key Rules
+
+1. **Wrap with HAI3Provider** - Required for all hooks to work
+2. **Use hooks for state access** - Don't import selectors directly from @gears-frontx/framework
+3. **Lazy load translations** - Use `useScreenTranslations` for screen-level i18n
+4. **Use MFE hooks for extensions** - `useMfeBridge`, `useSharedProperty`, `useHostAction`, `useDomainExtensions`
+5. **NO Layout components here** - Layout and UI components belong in L4 (user's project via CLI scaffolding)
+
+## Re-exports
+
+For convenience, this package re-exports everything from @gears-frontx/framework:
+
+- All SDK primitives (eventBus, createStore, etc.)
+- All plugins (screensets, themes, layout, microfrontends, etc.)
+- All registries and factory functions
+- All types (including MFE types)
+- All MFE actions, selectors, and domain constants
+
+This allows users to import everything from `@gears-frontx/react` without needing `@gears-frontx/framework` directly.
+
+## Exports
+
+### Components
+- `HAI3Provider` - Main context provider
+- `MfeProvider` - MFE context provider
+- `ExtensionDomainSlot` - Domain slot renderer
+- `RefContainerProvider` - Container reference provider
+
+### Hooks
+- `useHAI3` - Access app instance
+- `useAppDispatch` - Typed dispatch
+- `useAppSelector` - Typed selector
+- `useTranslation` - Translation utilities
+- `useScreenTranslations` - Screen translation loading
+- `useTheme` - Theme utilities
+- `useMfeBridge` - Access MFE bridge
+- `useSharedProperty` - Subscribe to shared property
+- `useHostAction` - Invoke host action
+- `useDomainExtensions` - Subscribe to domain extensions
+- `useRegisteredPackages` - Subscribe to registered GTS packages
+- `useActivePackage` - Subscribe to active GTS package
+
+### Context
+- `HAI3Context` - React context (for advanced use)
+- `MfeContext` - MFE context (for advanced use)
+
+### Types
+- `HAI3ProviderProps`
+- `MfeProviderProps`, `ExtensionDomainSlotProps`
+- `UseTranslationReturn`, `UseThemeReturn`
+- All types from @gears-frontx/framework
+
+## Migration from Legacy API
+
+The `useNavigation` hook has been removed. Use MFE hooks and actions instead:
+
+### Removed Hook
+- `useNavigation()` (replaced by MFE actions and hooks)
+
+### Migration Examples
+
+**OLD**: Navigate using hook
+```tsx
+import { useNavigation } from '@gears-frontx/react';
+
+function MyComponent() {
+  const { navigateToScreen } = useNavigation();
+
+  return (
+    <button onClick={() => navigateToScreen('demo', 'home')}>
+      Go Home
+    </button>
+  );
+}
+```
+
+**NEW**: Mount extension using app actions
+```tsx
+import { useHAI3 } from '@gears-frontx/react';
+
+function MyComponent() {
+  const app = useHAI3();
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const handleNavigate = async () => {
+    if (containerRef.current) {
+      await app.actions.mountExtension({
+        extensionId: 'home',
+        domainId: 'screen',
+        container: containerRef.current,
+      });
+    }
+  };
+
+  return (
+    <>
+      <button onClick={handleNavigate}>Go Home</button>
+      <div ref={containerRef} />
+    </>
+  );
+}
+```
+
+**NEW (Alternative)**: Use ExtensionDomainSlot
+```tsx
+import { ExtensionDomainSlot } from '@gears-frontx/react';
+
+function MyComponent() {
+  return (
+    <ExtensionDomainSlot
+      domainId="screen"
+      containerRef={screenContainerRef}
+      fallback={<Loading />}
+    />
+  );
+}
+```
+
+See the MFE migration guide in the project documentation for detailed migration steps.

package/commands/hai3-duplicate-screenset.md

@@ -0,0 +1,58 @@
+<!-- @standalone -->
+# hai3:duplicate-screenset - Duplicate Screenset
+
+## AI WORKFLOW (REQUIRED)
+1) Read .ai/targets/SCREENSETS.md before starting.
+2) Gather requirements from user.
+3) Follow steps below.
+
+REQUIRED: Copy folder and update ids.ts only (2 steps, 96% reduction).
+REQUIRED: Pass arch:check with zero errors.
+REQUIRED: Test via Chrome DevTools MCP (never skip).
+
+## GATHER REQUIREMENTS
+Ask user for:
+- SOURCE screenset name (existing screenset to copy).
+- TARGET screenset name (camelCase, single word preferred).
+- TARGET category: Drafts | Mockups | Production.
+
+## STEP 1: Copy Screenset via CLI
+```bash
+hai3 screenset copy SOURCE TARGET --category={category}
+```
+The CLI automatically:
+- Copies all files (screens, slices, actions, events, effects, API, icons, i18n).
+- Updates ids.ts with TARGET_SCREENSET_ID and all SCREEN_IDs.
+- Everything auto-updates via template literals:
+  - Event enums: ${TARGET_SCREENSET_ID}/${DOMAIN_ID}/eventName.
+  - Icon IDs: ${TARGET_SCREENSET_ID}:iconName.
+  - API domain: ${TARGET_SCREENSET_ID}:serviceName.
+  - Redux state key.
+- Screenset auto-discovered (no manual registration).
+
+## STEP 2: Validate
+```bash
+npm run type-check
+npm run arch:check
+npm run lint
+grep -rn "OLD_SCREENSET_ID" src/screensets/TARGET/  # Must return 0 matches
+```
+
+## STEP 3: Test via Chrome DevTools MCP
+STOP: If MCP connection is broken, fix it first. NEVER skip testing.
+- npm run dev.
+- Verify TARGET in screenset selector.
+- Click TARGET screenset in dev panel.
+- Verify URL changes to target screenset.
+- Check 0 console errors.
+- Test all primary features.
+- Verify auto-discovery worked (screenset appears without manual registration).
+
+## CHECKLIST
+- [ ] Gather requirements (source, target name, category).
+- [ ] Run `hai3 screenset copy SOURCE TARGET --category={category}`.
+- [ ] Run type-check (MUST pass).
+- [ ] Run arch:check (MUST pass).
+- [ ] Run lint (MUST pass).
+- [ ] Verify zero occurrences of old screenset ID.
+- [ ] Test via Chrome DevTools MCP (NEVER skip).

package/commands/hai3-new-component.md

@@ -0,0 +1,48 @@
+<!-- @standalone -->
+# hai3:new-component - Add New UI Component
+
+## AI WORKFLOW (REQUIRED)
+1) Check for existing equivalent in project (e.g. components/ui/) and configured UI library first.
+2) Gather requirements from user.
+3) Implement.
+
+## CHECK EXISTING COMPONENTS FIRST
+- REQUIRED: Read `frontx.config.json` to find the `uikit` value.
+- If uikit is a third-party package (not `shadcn` or `none`): read its exports from `node_modules/<package>/` to check for existing components.
+- REQUIRED: Before creating a new component, scan the project AND the configured UI library for existing equivalents.
+- REQUIRED: Reuse existing components if equivalent exists.
+
+## GATHER REQUIREMENTS
+Ask user for:
+- Component name (e.g., "DataTable", "ColorPicker").
+- Component description and props.
+
+## IF SCREENSET COMPONENT
+
+### STEP 0: Determine Subfolder
+- components/ui/: Base UI primitives (shadcn components or custom).
+- screens/{screen}/components/: Screen-specific components.
+- components/: Shared composites used across screens.
+
+### STEP 1: Implementation
+
+#### 1.1 Create Component
+File: src/components/ui/{ComponentName}.tsx (base primitives)
+  or: src/screens/{screen}/components/{ComponentName}.tsx (screen-specific)
+  or: src/components/{ComponentName}.tsx (shared composites)
+- Must be reusable within the MFE.
+- NO Redux or state management.
+- Accept value/onChange pattern for state.
+
+#### 1.2 Export
+Export from local index if needed.
+
+#### 1.3 Validation
+Run: npm run arch:check && npm run dev
+Test component in UI.
+
+## RULES
+- REQUIRED: Check existing project UI components first; create new only if missing.
+- FORBIDDEN: Redux, business logic, side effects in components.
+- FORBIDDEN: Inline styles outside components/ui/.
+- REQUIRED: Accept value/onChange pattern for state.

package/commands/hai3-new-mfe.md

@@ -0,0 +1,166 @@
+<!-- @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