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

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # @gears-frontx/react
 
-React bindings and hooks for HAI3 applications. Provides the React integration layer with MFE (Microfrontend) support.
+React bindings and hooks for FrontX applications. Provides the React integration layer with MFE (Microfrontend) support.
 
 ## React Layer
 
@@ -8,44 +8,166 @@ This package is part of the **React Layer (L3)** - it depends only on @gears-fro
 
 ## Core Concepts
 
-### HAI3Provider
+### Gears FrontXProvider
 
-Wrap your app with HAI3Provider to enable all hooks:
+Wrap your app with Gears FrontXProvider to enable all hooks:
 
 ```tsx
-import { HAI3Provider } from '@gears-frontx/react';
+import { Gears FrontXProvider } from '@gears-frontx/react';
 
 function App() {
   return (
-    <HAI3Provider>
+    <Gears FrontXProvider>
       <YourApp />
-    </HAI3Provider>
+    </Gears FrontXProvider>
   );
 }
 
 // With configuration
-<HAI3Provider config={{ devMode: true }}>
+<Gears FrontXProvider config={{ devMode: true }}>
   <YourApp />
-</HAI3Provider>
+</Gears FrontXProvider>
 
-// With pre-built app
-const app = createHAI3().use(screensets()).build();
-<HAI3Provider app={app}>
+// With pre-built app (host-style shell; host typically also uses queryCache())
+const app = createGears FrontX().use(screensets()).use(queryCache()).build();
+<Gears FrontXProvider app={app}>
   <YourApp />
-</HAI3Provider>
+</Gears FrontXProvider>
+
+// Child MFE app — canonical bootstrap matches src/mfe_packages/*/init.ts:
+// apiRegistry.register / initialize before .build; createGears FrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
+// registerSlice after .build when slices exist.
+const mfeApp = createGears FrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
+<Gears FrontXProvider app={mfeApp}>
+  <YourApp />
+</Gears FrontXProvider>
+```
+
+The shared `QueryClient` is created and owned by the `queryCache()` framework plugin at L2.
+`Gears FrontXProvider` resolves that client from the app instance — it does not create its own `QueryClient`.
+
+When the host uses `queryCache()` and the child MFE app uses `queryCacheShared()` (with `effects()` and `mock()` on the same chain as in repo MFE inits), both roots join the same shared `QueryClient` while keeping separate React trees. `ThemeAwareReactLifecycle` relies on that shared plugin-owned client through the app instance. If the shared client is missing for a mounted MFE, the lifecycle now fails explicitly instead of silently falling back.
+
+For separate roots, build each app with the appropriate query-cache plugin (`queryCache()` for the host, `queryCacheShared()` for child MFE shells) so every tree joins the same cache through plugin composition. Host apps should register domains/extensions during bootstrap; **`ExtensionDomainSlot`** is the preferred host-side renderer for screen slots while the framework wires `mount_ext`.
+
+### Data Fetching with Endpoint Descriptors
+
+Services define endpoints as descriptors. Components consume them via `useApiQuery` and `useApiMutation`. No manual query keys, no `queryOptions()` calls.
+
+```tsx
+import { useApiQuery, useApiMutation, apiRegistry } from '@gears-frontx/react';
+import { AccountsApiService } from '../api/AccountsApiService';
+
+function ProfileScreen() {
+  const service = apiRegistry.getService(AccountsApiService);
+
+  // Read — pass descriptor directly
+  const { data, isLoading, error } = useApiQuery(service.getCurrentUser);
+
+  // Read with params
+  const { data: user } = useApiQuery(service.getUser({ id: '123' }));
+
+  // Write with optimistic update
+  const { mutateAsync, isPending } = useApiMutation({
+    endpoint: service.updateProfile,
+    onMutate: async (variables, { queryCache }) => {
+      await queryCache.cancel(service.getCurrentUser);
+      const snapshot = queryCache.get(service.getCurrentUser);
+      queryCache.set(service.getCurrentUser, (old) => ({
+        ...old, user: { ...old.user, ...variables }
+      }));
+      return { snapshot };
+    },
+    onError: (_err, _vars, context, { queryCache }) => {
+      if (context?.snapshot) {
+        queryCache.set(service.getCurrentUser, context.snapshot);
+      }
+    },
+    onSettled: async (_data, _err, _vars, _ctx, { queryCache }) => {
+      await queryCache.invalidate(service.getCurrentUser);
+    },
+  });
+
+  // Per-endpoint cache override (rare)
+  const { data: config } = useApiQuery(service.getConfig, { staleTime: 0 });
+}
+```
+
+Cache keys are derived automatically by the service — `QueryCache` methods accept
+endpoint descriptors directly (e.g., `queryCache.get(service.getCurrentUser)`).
+
+### SSE Streaming with Stream Descriptors
+
+Services declare SSE endpoints as stream descriptors. Components consume them via `useApiStream`, which manages the connection lifecycle automatically (connect on mount, disconnect on unmount).
+
+```tsx
+import { useApiStream, apiRegistry } from '@gears-frontx/react';
+import { ChatApiService } from '../api/ChatApiService';
+
+function ChatStream() {
+  const service = apiRegistry.getService(ChatApiService);
+
+  // Latest event only (default mode)
+  const { data, status, error } = useApiStream(service.messageStream);
+
+  // Accumulate all events
+  const { events, status: streamStatus } = useApiStream(
+    service.messageStream,
+    { mode: 'accumulate' }
+  );
+
+  // Deferred connection (enabled: false)
+  const [active, setActive] = useState(false);
+  const { data: msg, disconnect } = useApiStream(
+    service.messageStream,
+    { enabled: active }
+  );
+
+  if (status === 'connecting') return <Loading />;
+  if (status === 'error') return <Error error={error} />;
+
+  return <div>{data?.text}</div>;
+}
 ```
 
+`useApiStream` returns `{ data, events, status, error, disconnect }`:
+- `data` — latest event payload (set in both modes)
+- `events` — all received events when `mode: 'accumulate'`; empty array in `'latest'` mode
+- `status` — connection lifecycle state, `StreamStatus` (see below)
+- `error` — the last connect attempt's error; retained until the next connect attempt resets it, so check `status` rather than `error` truthiness
+- `disconnect()` — close the connection manually
+
+#### Status lifecycle
+
+`status` is a `StreamStatus`: `'idle' | 'connecting' | 'connected' | 'disconnected' | 'error'`.
+
+The TSDoc block on `useApiStream` in `src/hooks/useApiStream.ts` is the detailed and authoritative state-machine reference, including teardown edge cases. This guide summarizes consumer-facing usage and gating.
+
+`disconnect()` closes the connection and does not reconnect. There is no reconnect function: to open a new connection, change the descriptor key, change `mode`, or toggle `enabled` back to true.
+
+#### The `enabled` option
+
+`enabled` (default `true`) gates whether the hook connects at all. While it is false the hook never calls the descriptor's `connect()` and ordinarily holds `status: 'idle'` (calling `disconnect()` while disabled is the one exception — see the TSDoc). Flipping it to true re-runs the connect effect and starts a fresh connection; flipping it back to false tears the connection down and returns `status` to `'idle'`.
+
+Tearing down via `enabled` does not clear `data` or `events` — a descriptor-key or `mode` change, or re-enabling, does. A component reading `data` while the stream is disabled still sees the last event from the previous connection.
+
+Gating advice, since `'idle'` covers both "not started yet" and "deferred by `enabled`":
+
+- Gate the loading state on `'connecting'` alone. Treating `'idle'` as loading renders a permanent spinner for a stream deliberately held at `enabled: false`.
+- Handle `'idle'` as "not started / deferred". A component that both defers and shows loading should key its spinner off its own active flag, not off `'idle'`.
+- Check `status === 'error'` rather than the truthiness of `error` to render failures.
+
 ### Available Hooks
 
-#### useHAI3
+#### useFrontX
 
-Access the HAI3 app instance:
+Access the FrontX app instance:
 
 ```tsx
-import { useHAI3 } from '@gears-frontx/react';
+import { useFrontX } from '@gears-frontx/react';
 
 function MyComponent() {
-  const app = useHAI3();
+  const app = useFrontX();
 
   // Access MFE-enabled registry
   const extensions = app.screensetsRegistry.getRegisteredExtensions();
@@ -138,18 +260,18 @@ 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';
+import { Gears FrontX_ACTION_LOAD_EXT, Gears FrontX_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' } }
+    action: { type: Gears FrontX_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
   });
 
   // Get shared property
-  const theme = bridge.getProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = bridge.getProperty(Gears FrontX_SHARED_PROPERTY_THEME);
 }
 ```
 
@@ -158,10 +280,10 @@ function MyExtension() {
 Subscribe to shared property changes:
 
 ```tsx
-import { useSharedProperty, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { useSharedProperty, Gears FrontX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function ThemedComponent() {
-  const theme = useSharedProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = useSharedProperty(Gears FrontX_SHARED_PROPERTY_THEME);
 
   return <div style={{ backgroundColor: theme?.primaryColor }}>...</div>;
 }
@@ -172,10 +294,10 @@ function ThemedComponent() {
 Invoke actions on the host application:
 
 ```tsx
-import { useHostAction, HAI3_ACTION_LOAD_EXT } from '@gears-frontx/react';
+import { useHostAction, Gears FrontX_ACTION_LOAD_EXT } from '@gears-frontx/react';
 
 function MyExtension() {
-  const loadExtension = useHostAction(HAI3_ACTION_LOAD_EXT);
+  const loadExtension = useHostAction(Gears FrontX_ACTION_LOAD_EXT);
 
   const handleClick = () => {
     loadExtension({ extensionId: 'other' });
@@ -254,7 +376,7 @@ import { MfeProvider } from '@gears-frontx/react';
 
 function MfeHost() {
   return (
-    <MfeProvider bridge={parentBridge}>
+    <MfeProvider value={{ bridge: parentBridge, extensionId: 'home', domainId: 'screen' }}>
       <ExtensionContainer />
     </MfeProvider>
   );
@@ -270,17 +392,27 @@ import { ExtensionDomainSlot } from '@gears-frontx/react';
 
 function LayoutScreen() {
   return (
-    <div>
-      <ExtensionDomainSlot
-        domainId="screen"
-        containerRef={screenContainerRef}
-        fallback={<Loading />}
-      />
-    </div>
+    <ExtensionDomainSlot
+      registry={registry}
+      domainId="screen"
+      extensionId="home"
+      loadingComponent={<Loading />}
+    />
   );
 }
 ```
 
+`ExtensionDomainSlot` is the preferred host-side renderer for screen MFEs. It
+owns mount/unmount and loading/error UI while host bootstrap handles domain
+registration and shared property setup before slot-driven `mount_ext`.
+The host `QueryClient` is reused by MFE React trees through
+`queryCacheShared()`, not by embedding a `QueryClient` on `MfeMountContext`
+or expecting host React context inside Shadow DOM.
+
+When the domain's `ContainerProvider` must point at the same DOM node rendered
+by the slot, pass `containerRef` to `ExtensionDomainSlot` and share that ref
+with `RefContainerProvider`.
+
 #### RefContainerProvider
 
 Provide container references for MFE mounting:
@@ -302,11 +434,14 @@ function Layout() {
 
 ## Key Rules
 
-1. **Wrap with HAI3Provider** - Required for all hooks to work
+1. **Wrap with Gears FrontXProvider** - 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)
+3. **Use endpoint descriptors for data** - `useApiQuery(service.endpoint)` for REST, `useApiStream(service.stream)` for SSE — not `queryOptions()` or manual key factories
+4. **Service is the cache contract** - The service IS the data layer; cache keys are derived automatically
+5. **QueryCache uses descriptors** - `queryCache.get(service.endpoint)`, not raw key arrays
+6. **Lazy load translations** - Use `useScreenTranslations` for screen-level i18n
+7. **Use MFE hooks for extensions** - `useMfeBridge`, `useSharedProperty`, `useHostAction`, `useDomainExtensions`
+8. **NO Layout components here** - Layout and UI components belong in L4 (user's project via CLI scaffolding)
 
 ## Re-exports
 
@@ -323,15 +458,19 @@ This allows users to import everything from `@gears-frontx/react` without needin
 ## Exports
 
 ### Components
-- `HAI3Provider` - Main context provider
+- `Gears FrontXProvider` - Main context provider
 - `MfeProvider` - MFE context provider
 - `ExtensionDomainSlot` - Domain slot renderer
 - `RefContainerProvider` - Container reference provider
 
 ### Hooks
-- `useHAI3` - Access app instance
+- `useFrontX` - Access app instance
 - `useAppDispatch` - Typed dispatch
 - `useAppSelector` - Typed selector
+- `useApiQuery` - Declarative data fetch from endpoint descriptor; returns `ApiQueryResult<TData>`
+- `useApiMutation` - Declarative mutation with endpoint descriptor and optimistic update support; returns `ApiMutationResult<TData>`
+- `useApiStream` - Declarative SSE streaming from stream descriptor; returns `ApiStreamResult<TEvent>`
+- `useQueryCache` - Restricted query cache access (accepts descriptors or raw keys)
 - `useTranslation` - Translation utilities
 - `useScreenTranslations` - Screen translation loading
 - `useTheme` - Theme utilities
@@ -343,14 +482,20 @@ This allows users to import everything from `@gears-frontx/react` without needin
 - `useActivePackage` - Subscribe to active GTS package
 
 ### Context
-- `HAI3Context` - React context (for advanced use)
+- `Gears FrontXContext` - React context (for advanced use)
 - `MfeContext` - MFE context (for advanced use)
 
 ### Types
-- `HAI3ProviderProps`
+- `Gears FrontXProviderProps`
+- `ApiQueryResult<TData>` - Gears FrontX-owned query result type (data, error, isLoading, refetch, etc.)
+- `ApiMutationResult<TData>` - Gears FrontX-owned mutation result type (mutateAsync, isPending, error, reset, etc.)
+- `ApiStreamResult<TEvent>` - Gears FrontX-owned stream result type (data, events, status, error, disconnect)
+- `ApiStreamOptions` - Stream hook options (mode, enabled)
+- `QueryCache` - Restricted cache interface (accepts descriptors or raw keys)
+- `MutationCallbackContext` - Context with queryCache injected into mutation callbacks
 - `MfeProviderProps`, `ExtensionDomainSlotProps`
 - `UseTranslationReturn`, `UseThemeReturn`
-- All types from @gears-frontx/framework
+- All types from @gears-frontx/framework (including `EndpointDescriptor`, `MutationDescriptor`, `StreamDescriptor`, `StreamStatus`)
 
 ## Migration from Legacy API
 
@@ -378,10 +523,10 @@ function MyComponent() {
 
 **NEW**: Mount extension using app actions
 ```tsx
-import { useHAI3 } from '@gears-frontx/react';
+import { useFrontX } from '@gears-frontx/react';
 
 function MyComponent() {
-  const app = useHAI3();
+  const app = useFrontX();
   const containerRef = useRef<HTMLDivElement>(null);
 
   const handleNavigate = async () => {
@@ -403,16 +548,17 @@ function MyComponent() {
 }
 ```
 
-**NEW (Alternative)**: Use ExtensionDomainSlot
+**NEW (Preferred for host screen slots)**: Use ExtensionDomainSlot
 ```tsx
 import { ExtensionDomainSlot } from '@gears-frontx/react';
 
 function MyComponent() {
   return (
     <ExtensionDomainSlot
+      registry={app.screensetsRegistry}
       domainId="screen"
-      containerRef={screenContainerRef}
-      fallback={<Loading />}
+      extensionId="home"
+      loadingComponent={<Loading />}
     />
   );
 }