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

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.