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

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,51 +8,180 @@ This package is part of the **React Layer (L3)** - it depends only on @gears-fro
 
 ## Core Concepts
 
-### HAI3Provider
+### FrontXProvider
 
-Wrap your app with HAI3Provider to enable all hooks:
+Wrap your app with FrontXProvider to enable all hooks. A runtime builds exactly one app, once at module level; the provider never creates one. The three compositions below are alternatives: choose one per runtime.
 
 ```tsx
-import { HAI3Provider } from '@gears-frontx/react';
+import { createFrontX, FrontXProvider, presets } from '@gears-frontx/react';
+
+// Alternative 1: the full preset
+const app = createFrontX({ devMode: true }).useAll(presets.full()).build();
 
 function App() {
   return (
-    <HAI3Provider>
+    <FrontXProvider app={app}>
       <YourApp />
-    </HAI3Provider>
+    </FrontXProvider>
   );
 }
 
-// With configuration
-<HAI3Provider config={{ devMode: true }}>
-  <YourApp />
-</HAI3Provider>
+```
+
+Alternative 2: a host shell with a custom plugin set (a host typically uses `queryCache()`):
+
+```tsx
+const app = createFrontX().use(effects()).use(queryCache()).build();
+```
+
+Alternative 3: a child MFE app. The canonical bootstrap matches `src/mfe_packages/*/init.ts`: `apiRegistry.register` / `initialize` before `.build()`, `registerSlice` after `.build()` when slices exist:
+
+```tsx
+const app = createFrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
+```
+
+The shared `QueryClient` is created and owned by the `queryCache()` framework plugin at L2.
+`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 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({ teamId }: { teamId?: string }) {
+  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 });
 
-// With pre-built app
-const app = createHAI3().use(screensets()).build();
-<HAI3Provider app={app}>
-  <YourApp />
-</HAI3Provider>
+  // Conditional query: stays idle until enabled (not on the suspense hooks).
+  // The hook still needs a descriptor on every render, so one is built with a
+  // stand-in id; while enabled is false it is not fetched automatically, and
+  // refetch would still fetch it, so do not call refetch before teamId is set.
+  const { data: team } = useApiQuery(service.getTeam({ id: teamId ?? '' }), { enabled: Boolean(teamId) });
+}
 ```
 
+Cache keys are derived automatically by the service — `QueryCache` methods accept
+endpoint descriptors directly (e.g., `queryCache.get(service.getCurrentUser)`).
+
+The `queryCache` a mutation callback receives is bound to the cache scope (mock mode, tenant, session) the mutation started under: once that scope changes, its writes (`set`, `remove`, `invalidate`, `invalidateMany`, `cancel`) do nothing and reads still work, so a response or snapshot from the old scope never lands in the new cache. Nothing else is scope-bound: a `useQueryCache()` handle, the raw `QueryClient`, `cache/*` eventBus emits and per-call `mutate(vars, { onSuccess })` options write to whatever scope is current, so a write after an `await` or inside a mutation callback must go through the callback's `queryCache`.
+
+### 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();
+  const extensions = app.mfeRegistry.getExtensionsForDomain('screen');
 
-  // Access MFE actions
-  await app.actions.loadExtension({ extensionId: 'home' });
-  await app.actions.mountExtension({ extensionId: 'home', domainId: 'screen', container });
+  // Access MFE actions — fire-and-forget: each dispatches an actions chain
+  // through the acceptance-only registry surface and returns nothing to
+  // await.
+  app.actions.loadExtension('home');
+  app.actions.mountExtension('home');
 }
 ```
 
@@ -138,47 +267,78 @@ 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 { FRONTX_ACTION_LOAD_EXT, 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' } }
-  });
+  const handleLoad = () => {
+    // executeActionsChain is acceptance-only: it returns void, never
+    // throws, and never yields anything to await for the chain's own
+    // execution.
+    bridge.executeActionsChain({
+      action: { type: FRONTX_ACTION_LOAD_EXT, target: 'screen', payload: { subject: 'other' } }
+    });
+  };
 
   // Get shared property
-  const theme = bridge.getProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = bridge.getProperty(FRONTX_SHARED_PROPERTY_THEME);
 }
 ```
 
 #### useSharedProperty
 
-Subscribe to shared property changes:
+Subscribe to shared property changes. Two forms: the context form reads the bridge from `MfeContext`, and the options form accepts an explicit bridge and a fallback.
+
+**Context form** — `useSharedProperty(propertyTypeId)`. Reads the bridge from `MfeContext` and throws if no `MfeProvider` is mounted. Returns the value (or `undefined` if the host has not published it), updating on every host publish.
 
 ```tsx
-import { useSharedProperty, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { useSharedProperty, FRONTX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function ThemedComponent() {
-  const theme = useSharedProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = useSharedProperty(FRONTX_SHARED_PROPERTY_THEME);
 
   return <div style={{ backgroundColor: theme?.primaryColor }}>...</div>;
 }
 ```
 
+**Options form** — `useSharedProperty(propertyTypeId, { bridge, fallback })`. Use it for components that never mount `MfeProvider`, or to show a value until the host publishes one.
+
+```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>;
+}
+```
+
+`UseSharedPropertyOptions<T>` fields:
+
+- `bridge` — bridge to read the property from, bypassing `MfeContext`. Pass it when the calling component never mounts `MfeProvider` (for example, a component that receives its bridge as a prop or from a non-React entry point). When omitted, the hook falls back to the bridge from `MfeContext` and throws if no `MfeProvider` is mounted. Changing `bridge` or `propertyTypeId` moves the subscription to the new source and the returned value follows on the same render.
+- `fallback` — value returned while the host has not published the property yet. Only `undefined` is substituted; a published `null` is a real value and comes through as-is. With `fallback` set the hook returns `T` rather than `T | undefined`. It may be passed inline on every render without affecting the subscription.
+
+There is no consumer-side validation option on purpose: the host validates every published value against the property's schema before it reaches any MFE (`TypeSystemPlugin.register()` throws on a mismatch and the update is never stored or delivered). `T` is the caller's declaration of that schema, as with `useState<T>`.
+
+Both forms read through `useSyncExternalStore`, so the first render shows the host's current value and the result is tearing-protected under concurrent rendering. The TSDoc block on `useSharedProperty` in `src/mfe/hooks/useSharedProperty.ts` is the authoritative reference; this guide summarizes consumer-facing usage.
+
 #### useHostAction
 
 Invoke actions on the host application:
 
 ```tsx
-import { useHostAction, HAI3_ACTION_LOAD_EXT } from '@gears-frontx/react';
+import { useHostAction, FRONTX_ACTION_LOAD_EXT } from '@gears-frontx/react';
 
 function MyExtension() {
-  const loadExtension = useHostAction(HAI3_ACTION_LOAD_EXT);
+  const loadExtension = useHostAction(FRONTX_ACTION_LOAD_EXT);
 
   const handleClick = () => {
-    loadExtension({ extensionId: 'other' });
+    loadExtension({ subject: 'other' });
   };
 
   return <button onClick={handleClick}>Load Extension</button>;
@@ -254,7 +414,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 +430,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 +472,14 @@ function Layout() {
 
 ## Key Rules
 
-1. **Wrap with HAI3Provider** - Required for all hooks to work
+1. **Wrap with 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,34 +496,45 @@ This allows users to import everything from `@gears-frontx/react` without needin
 ## Exports
 
 ### Components
-- `HAI3Provider` - Main context provider
+- `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
 - `useMfeBridge` - Access MFE bridge
-- `useSharedProperty` - Subscribe to shared property
+- `useSharedProperty` - Subscribe to shared property, via `MfeContext` or an explicit bridge
 - `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)
+- `FrontXContext` - React context (for advanced use)
 - `MfeContext` - MFE context (for advanced use)
 
 ### Types
-- `HAI3ProviderProps`
+- `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`
+- `UseSharedPropertyOptions<T>` - Options for `useSharedProperty` (bridge, fallback)
 - `UseTranslationReturn`, `UseThemeReturn`
-- All types from @gears-frontx/framework
+- All types from @gears-frontx/framework (including `EndpointDescriptor`, `MutationDescriptor`, `StreamDescriptor`, `StreamStatus`)
 
 ## Migration from Legacy API
 
@@ -378,19 +562,17 @@ 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 () => {
+  const handleNavigate = () => {
     if (containerRef.current) {
-      await app.actions.mountExtension({
-        extensionId: 'home',
-        domainId: 'screen',
-        container: containerRef.current,
-      });
+      // Fire-and-forget: dispatches an actions chain through the
+      // acceptance-only registry surface and returns nothing to await.
+      app.actions.mountExtension('home');
     }
   };
 
@@ -403,16 +585,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.mfeRegistry}
       domainId="screen"
-      containerRef={screenContainerRef}
-      fallback={<Loading />}
+      extensionId="home"
+      loadingComponent={<Loading />}
     />
   );
 }