@gears-frontx/react 0.2.0-alpha.0 → 0.2.0-alpha.15

package/llms.txt

@@ -6,9 +6,9 @@ Part of the FrontX React Layer (L3) - depends on @gears-frontx/framework. Peer d
 
 ## Core API
 
-- [Gears FrontXProvider](https://frontx.dev/docs/react/provider): Root context provider
-- [MFE Components](https://frontx.dev/docs/react/mfe): ExtensionDomainSlot, MfeProvider, RefContainerProvider
-- `Gears FrontXProvider` resolves the shared `QueryClient` from `queryCache()` / `queryCacheShared()` through the app instance; mounted MFEs reuse the host cache by building their local app with `queryCacheShared()`, which joins the same shared `QueryClient` without mutating L1 contracts
+- [FrontXProvider](https://frontx.dev/docs/react/provider): Root context provider
+- [MFE Components](https://frontx.dev/docs/react/mfe): ExtensionDomainSlot, MfeProvider
+- `FrontXProvider` resolves the shared `QueryClient` from `queryCache()` / `queryCacheShared()` through the app instance; mounted MFEs reuse the host cache by building their local app with `queryCacheShared()`, which joins the same shared `QueryClient` without mutating L1 contracts
 
 ## Hooks
 
@@ -26,23 +26,27 @@ Part of the FrontX React Layer (L3) - depends on @gears-frontx/framework. Peer d
 | Hook | Purpose |
 |------|---------|
 | `useMfeBridge()` | Access MFE bridge (child MFEs) |
-| `useSharedProperty()` | Subscribe to shared property changes |
+| `useSharedProperty()` | Subscribe to shared property changes, via `MfeContext` or an explicit `bridge` option |
 | `useHostAction()` | Invoke actions on host application |
 | `useDomainExtensions()` | Subscribe to extensions in a domain |
 
 ## Quick Start
 
 ```tsx
-import { Gears FrontXProvider, useTranslation, useFrontX } from '@gears-frontx/react';
+import { createFrontX, FrontXProvider, presets, useTranslation, useFrontX } from '@gears-frontx/react';
+
+// One app per runtime, built once at module level (the full preset here;
+// `presets.full({ microfrontends: config })` also adds microfrontends)
+const app = createFrontX().useAll(presets.full()).build();
 
 // Wrap app with provider
 function App() {
   return (
-    <Gears FrontXProvider>
+    <FrontXProvider app={app}>
       <Layout>
         <MainScreen />
       </Layout>
-    </Gears FrontXProvider>
+    </FrontXProvider>
   );
 }
 
@@ -81,15 +85,17 @@ function LayoutScreen() {
 ### Using MFE Bridge
 
 ```tsx
-import { useMfeBridge, useSharedProperty, Gears FrontX_ACTION_LOAD_EXT, Gears FrontX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { useMfeBridge, useSharedProperty, FRONTX_ACTION_LOAD_EXT, FRONTX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function MyExtension() {
   const bridge = useMfeBridge();
-  const theme = useSharedProperty(Gears FrontX_SHARED_PROPERTY_THEME);
+  const theme = useSharedProperty(FRONTX_SHARED_PROPERTY_THEME);
 
-  const handleAction = async () => {
-    await bridge.executeActionsChain({
-      action: { type: Gears FrontX_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
+  // executeActionsChain is acceptance-only: it returns void, never throws,
+  // and never yields anything to await for the chain's own execution.
+  const handleAction = () => {
+    bridge.executeActionsChain({
+      action: { type: FRONTX_ACTION_LOAD_EXT, target: 'screen', payload: { subject: 'other' } }
     });
   };
 
@@ -97,6 +103,26 @@ function MyExtension() {
 }
 ```
 
+### Shared Properties Without MfeProvider
+
+`useSharedProperty(propertyTypeId, options)` takes an explicit `bridge` for components that never mount `MfeProvider`, plus a `fallback` returned until the host publishes the property (only `undefined` is substituted; a published `null` is a value). With `fallback` set the result type is `T`. There is no consumer-side validation option: the host validates published values against the property's schema before delivery, so `T` is the caller's declaration of that schema.
+
+```tsx
+import { useSharedProperty } from '@gears-frontx/react';
+import type { ChildMfeBridge } from '@gears-frontx/framework';
+
+function StandaloneComponent({ bridge }: { bridge: ChildMfeBridge }) {
+  const label = useSharedProperty<string>(LABEL_PROPERTY_ID, {
+    bridge,
+    fallback: 'Untitled',
+  });
+
+  return <span>{label}</span>;
+}
+```
+
+Omitting `bridge` falls back to `MfeContext`; the hook still throws when neither is available. Changing `bridge` or `propertyTypeId` moves the subscription and the value follows on the same render.
+
 ### Subscribing to Domain Extensions
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gears-frontx/react",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.15",
   "description": "React bindings and hooks for FrontX framework",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,37 +26,39 @@
   "files": [
     "dist",
     "CLAUDE.md",
-    "llms.txt",
-    "commands"
+    "llms.txt"
   ],
   "scripts": {
     "build": "tsup",
-    "type-check": "tsc --noEmit",
+    "type-check": "tsc --noEmit && npm run type-check:test",
     "type-check:test": "tsc -p tsconfig.test.json",
     "test": "npm run test:unit",
     "test:unit": "vitest --run --passWithNoTests=false",
     "test:unit:watch": "vitest --watch"
   },
   "devDependencies": {
-    "@reduxjs/toolkit": "^2.5.0",
-    "@tanstack/react-query": "^5.90.0",
+    "@reduxjs/toolkit": "2.12.0",
+    "@tanstack/react-query": "5.101.4",
     "@testing-library/react": "16.3.2",
-    "@types/react": "^19.0.8",
-    "@types/react-redux": "^7.1.33",
+    "@types/node": "^24.0.0",
+    "@types/react": "19.2.18",
+    "@types/react-redux": "7.1.34",
     "@vitejs/plugin-react": "4.3.4",
     "@vitest/coverage-v8": "4.1.4",
     "jsdom": "26.1.0",
-    "react": "^19.2.4",
-    "react-redux": "^9.1.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.4.2",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-redux": "9.3.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
     "vitest": "4.1.4"
   },
   "peerDependencies": {
     "@gears-frontx/framework": "*",
-    "@tanstack/react-query": ">=5.0.0",
-    "react": "^19.2.4",
-    "react-redux": ">=8.0.0"
+    "@tanstack/react-query": "5.101.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-redux": "9.3.0"
   },
   "peerDependenciesMeta": {
     "@gears-frontx/framework": {
@@ -65,6 +67,9 @@
     "react": {
       "optional": false
     },
+    "react-dom": {
+      "optional": false
+    },
     "react-redux": {
       "optional": false
     },

package/commands/frontx-duplicate-screenset.md

@@ -1,58 +0,0 @@
-<!-- @standalone -->
-# frontx: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
-frontx 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 `frontx 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/frontx-new-component.md

@@ -1,57 +0,0 @@
-<!-- @standalone -->
-# frontx:new-component - Add New UI Component
-
-## AI WORKFLOW (REQUIRED)
-1) Read `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** any unit-test, validation, or testing steps in this command (project-owned overrides take precedence over defaults here).
-2) Check for existing equivalent in project (e.g. components/ui/) and configured UI library first.
-3) Gather requirements from user.
-4) 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
-<!-- @cpt-begin:cpt-frontx-flow-unit-test-generation-and-agent-verification-agent-verify:p1:inst-agent-implement-and-test -->
-If creating a shared composite in `src/components/`, add or update a component test for its stable behavior.
-Run `npm run test:unit`, `npm run type-check`, `npm run arch:check`, and `npm run dev` (or the equivalent commands for this project's configured package manager) and apply any stricter triggers or conventions from `.ai/project/targets/UNIT_TESTING.md`. Apply constraints from workflow step 1.
-<!-- @cpt-end:cpt-frontx-flow-unit-test-generation-and-agent-verification-agent-verify:p1:inst-agent-implement-and-test -->
-Test component in UI.
-
-## TESTING
-- REQUIRED: Load `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** interpreting unit-test requirements elsewhere in this command.
-- REQUIRED: Follow `.ai/project/targets/UNIT_TESTING.md` for `__test-utils__/` placement and durable, non-placeholder assertions when adding or updating tests.
-
-## 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.
-- REQUIRED: New shared composite components in `src/components/` include a colocated or nearby unit test when the behavior is stable.

package/commands/frontx-new-mfe.md

@@ -1,153 +0,0 @@
-<!-- @standalone -->
-# frontx:new-mfe - Create New Microfrontend Package
-
-## PREREQUISITES (CRITICAL - STOP IF FAILED)
-
-1. MFE must be associated with a screenset
-2. Screenset must exist (run `frontx-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/react';
-import { mfeApp } from './init';
-import { YourScreen } from './screens/YourScreen';
-
-class Lifecycle extends ThemeAwareReactLifecycle {
-  constructor() {
-    super(mfeApp);
-  }
-
-  protected renderContent(bridge: ChildMfeBridge): React.ReactNode {
-    return <YourScreen bridge={bridge} />;
-  }
-}
-
-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
-- `frontx-new-screenset.md` for screenset creation

package/commands/frontx-new-screen.md

@@ -1,45 +0,0 @@
-<!-- @standalone -->
-# frontx:new-screen - Add New Screen
-
-## AI WORKFLOW (REQUIRED)
-1) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
-2) Read `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** planning unit tests, validation, or any test-related tasks in this command (project-owned overrides take precedence over defaults here).
-3) Gather requirements from user (including UI sections).
-4) 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 or update a screen test that covers stable render or behavior for the new screen and place any test-only helpers in a sibling `__test-utils__/` folder.
-6) Add to menu if requested.
-7) Validate: run `test:unit`, `type-check`, and `arch:check` via this project's package manager per `.ai/project/targets/UNIT_TESTING.md` (which defines the exact commands). Apply constraints from workflow step 2.
-8) 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
-
-## TESTING
-- REQUIRED: Load `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** interpreting unit-test requirements elsewhere in this command.
-- REQUIRED: Use neutral fixtures, translation mocks, and stable keys, roles, or IDs instead of placeholder-derived copy when adding or updating generated screen tests.
-
-## 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/frontx-new-screenset.md

@@ -1,57 +0,0 @@
-<!-- @standalone -->
-# frontx:new-screenset - Create New Screenset
-
-## PREREQUISITES (CRITICAL - STOP IF FAILED)
-Run `frontx --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) Read `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** planning unit tests, validation, or any test-related tasks in this command (project-owned overrides take precedence over defaults here).
-4) Gather requirements from user (including UI sections).
-5) 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 `frontx 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 and endpoint descriptors:
-   - Read endpoints: `readonly prop = this.protocol(RestEndpointProtocol).query<T>('/path')`
-   - Write endpoints: `readonly prop = this.protocol(RestEndpointProtocol).mutation<T, V>('PUT', '/path')`
-   - NO queryOptions, NO manual query key factories outside the service
-   - Screens use `useApiQuery(service.prop)` and `useApiMutation({ endpoint: service.prop })`
-5) Add or update starter unit tests for stable generated behavior.
-6) Validate: run `test:unit`, `type-check`, `arch:check`, and `lint` via this project's package manager per `.ai/project/targets/UNIT_TESTING.md` (which defines the exact commands). Apply constraints from workflow step 3.
-7) 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 and endpoint descriptors
-
-## TESTING
-- REQUIRED: Load `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** interpreting unit-test requirements elsewhere in this command.
-- REQUIRED: Preserve the generated API-contract test and `HomeScreen` smoke test unless the new behavior replaces that baseline intentionally.