@c.a.f/infrastructure-react 1.0.2 → 1.0.4

package/.build/Ploc/usePloc.d.ts

@@ -1,15 +1,20 @@
 import type { Ploc } from "@c.a.f/core";
+/** Infers the state type S from a Ploc subclass P (P extends Ploc<S>) */
+type PlocState<P> = P extends Ploc<infer S> ? S : never;
 /**
  * React hook that subscribes to a Ploc and returns the current state and the Ploc instance.
  * Handles subscription on mount, syncs when the ploc reference changes, and unsubscribes on unmount.
+ * The return type preserves the concrete ploc type (e.g. UserPloc) so methods like loadUsers() are typed.
  *
  * @param ploc - A Ploc instance (from @c.a.f/core)
- * @returns A tuple of [currentState, ploc]
+ * @returns A tuple of [currentState, ploc] with the same ploc type as passed in
  *
  * @example
  * ```tsx
  * const [state, userPloc] = usePloc(userPloc);
+ * await userPloc.loadUsers(); // typed correctly
  * return <span>{state.name}</span>;
  * ```
  */
-export declare function usePloc<T>(ploc: Ploc<T>): [T, Ploc<T>];
+export declare function usePloc<P extends Ploc<PlocState<P>>>(ploc: P): [PlocState<P>, P];
+export {};

package/.build/Ploc/usePloc.js

@@ -2,13 +2,15 @@ import { useEffect, useState } from "react";
 /**
  * React hook that subscribes to a Ploc and returns the current state and the Ploc instance.
  * Handles subscription on mount, syncs when the ploc reference changes, and unsubscribes on unmount.
+ * The return type preserves the concrete ploc type (e.g. UserPloc) so methods like loadUsers() are typed.
  *
  * @param ploc - A Ploc instance (from @c.a.f/core)
- * @returns A tuple of [currentState, ploc]
+ * @returns A tuple of [currentState, ploc] with the same ploc type as passed in
  *
  * @example
  * ```tsx
  * const [state, userPloc] = usePloc(userPloc);
+ * await userPloc.loadUsers(); // typed correctly
  * return <span>{state.name}</span>;
  * ```
  */

package/.build/Provider/CAFContext.d.ts

@@ -0,0 +1,25 @@
+/// <reference types="react" />
+import type { Ploc } from "@c.a.f/core";
+import type { UseCase } from "@c.a.f/core";
+/**
+ * Value provided by CAFProvider. Allows descendants to access Plocs and UseCases by key.
+ * Use useCAFContext() to read, or usePlocFromContext / useUseCaseFromContext for typed access by key.
+ */
+export interface CAFContextValue {
+    /** Plocs registered at the root, keyed by string (e.g. "user", "auth"). */
+    plocs: Record<string, Ploc<unknown>>;
+    /** UseCases registered at the root, keyed by string (e.g. "createUser", "login"). */
+    useCases: Record<string, UseCase<any[], any>>;
+}
+export declare const CAFContext: import("react").Context<CAFContextValue>;
+/**
+ * Hook to access the CAF context (Plocs and UseCases registered by CAFProvider).
+ * Returns the context value; use .plocs[key] or .useCases[key] to get instances.
+ * When used outside CAFProvider, returns the default empty registry (no throw).
+ *
+ * @example
+ * const { plocs, useCases } = useCAFContext();
+ * const userPloc = plocs["user"] as UserPloc | undefined;
+ * const createUser = useCases["createUser"];
+ */
+export declare function useCAFContext(): CAFContextValue;

package/.build/Provider/CAFContext.js

@@ -0,0 +1,19 @@
+import { createContext, useContext } from "react";
+const defaultValue = {
+    plocs: {},
+    useCases: {},
+};
+export const CAFContext = createContext(defaultValue);
+/**
+ * Hook to access the CAF context (Plocs and UseCases registered by CAFProvider).
+ * Returns the context value; use .plocs[key] or .useCases[key] to get instances.
+ * When used outside CAFProvider, returns the default empty registry (no throw).
+ *
+ * @example
+ * const { plocs, useCases } = useCAFContext();
+ * const userPloc = plocs["user"] as UserPloc | undefined;
+ * const createUser = useCases["createUser"];
+ */
+export function useCAFContext() {
+    return useContext(CAFContext);
+}

package/.build/Provider/CAFProvider.d.ts

@@ -0,0 +1,42 @@
+import React, { type ReactNode } from "react";
+import type { Ploc } from "@c.a.f/core";
+import type { UseCase } from "@c.a.f/core";
+export interface CAFProviderProps {
+    /**
+     * Plocs to provide to the tree, keyed by string.
+     * Descendants can access via useCAFContext().plocs[key] or usePlocFromContext(key).
+     */
+    plocs?: Record<string, Ploc<unknown>>;
+    /**
+     * UseCases to provide to the tree, keyed by string.
+     * Descendants can access via useCAFContext().useCases[key] or useUseCaseFromContext(key).
+     */
+    useCases?: Record<string, UseCase<any[], any>>;
+    children: ReactNode;
+}
+/**
+ * Root-level provider for Plocs and UseCases. Register instances by key so any descendant
+ * can access them without prop drilling.
+ *
+ * @example Single provider at app root
+ * ```tsx
+ * const userPloc = useMemo(() => new UserPloc(userRepo), [userRepo]);
+ * const createUser = useMemo(() => new CreateUser(repo), [repo]);
+ *
+ * <CAFProvider plocs={{ user: userPloc }} useCases={{ createUser }}>
+ *   <App />
+ * </CAFProvider>
+ * ```
+ *
+ * @example Nested providers (e.g. feature-specific Plocs)
+ * ```tsx
+ * <CAFProvider plocs={{ user: userPloc }}>
+ *   <CAFProvider plocs={{ dashboard: dashboardPloc }}>
+ *     <Dashboard />
+ *   </CAFProvider>
+ * </CAFProvider>
+ * ```
+ * Inner provider does not merge with outer; use a single provider at root with all keys, or
+ * ensure children only rely on the nearest provider's keys.
+ */
+export declare function CAFProvider({ plocs, useCases, children }: CAFProviderProps): React.JSX.Element;

package/.build/Provider/CAFProvider.js

@@ -0,0 +1,34 @@
+import React from "react";
+import { CAFContext } from "./CAFContext";
+/**
+ * Root-level provider for Plocs and UseCases. Register instances by key so any descendant
+ * can access them without prop drilling.
+ *
+ * @example Single provider at app root
+ * ```tsx
+ * const userPloc = useMemo(() => new UserPloc(userRepo), [userRepo]);
+ * const createUser = useMemo(() => new CreateUser(repo), [repo]);
+ *
+ * <CAFProvider plocs={{ user: userPloc }} useCases={{ createUser }}>
+ *   <App />
+ * </CAFProvider>
+ * ```
+ *
+ * @example Nested providers (e.g. feature-specific Plocs)
+ * ```tsx
+ * <CAFProvider plocs={{ user: userPloc }}>
+ *   <CAFProvider plocs={{ dashboard: dashboardPloc }}>
+ *     <Dashboard />
+ *   </CAFProvider>
+ * </CAFProvider>
+ * ```
+ * Inner provider does not merge with outer; use a single provider at root with all keys, or
+ * ensure children only rely on the nearest provider's keys.
+ */
+export function CAFProvider({ plocs = {}, useCases = {}, children }) {
+    const value = {
+        plocs: { ...plocs },
+        useCases: { ...useCases },
+    };
+    return React.createElement(CAFContext.Provider, { value: value }, children);
+}

package/.build/Provider/index.d.ts

@@ -0,0 +1,3 @@
+export { CAFContext, useCAFContext, type CAFContextValue } from "./CAFContext";
+export { CAFProvider, type CAFProviderProps } from "./CAFProvider";
+export { usePlocFromContext, useUseCaseFromContext } from "./useContextHooks";

package/.build/Provider/index.js

@@ -0,0 +1,3 @@
+export { CAFContext, useCAFContext } from "./CAFContext";
+export { CAFProvider } from "./CAFProvider";
+export { usePlocFromContext, useUseCaseFromContext } from "./useContextHooks";

package/.build/Provider/useContextHooks.d.ts

@@ -0,0 +1,34 @@
+import type { Ploc, UseCase } from "@c.a.f/core";
+/**
+ * Hook to get a Ploc from the nearest CAFProvider by key.
+ * Returns `undefined` when the key is not registered or when used outside a provider
+ * (default context has empty plocs). Use the generic for type-safe access.
+ *
+ * @param key - Key used when registering the Ploc in CAFProvider (e.g. "user", "auth")
+ * @returns The Ploc instance or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * const userPloc = usePlocFromContext<UserPloc>("user");
+ * if (!userPloc) return <NotFound />;
+ * const [state, ploc] = usePloc(userPloc);
+ * return <span>{state.name}</span>;
+ * ```
+ */
+export declare function usePlocFromContext<P extends Ploc<unknown>>(key: string): P | undefined;
+/**
+ * Hook to get a UseCase from the nearest CAFProvider by key.
+ * Returns `undefined` when the key is not registered or when used outside a provider
+ * (default context has empty useCases). Use generics for type-safe args and result.
+ *
+ * @param key - Key used when registering the UseCase in CAFProvider (e.g. "createUser", "login")
+ * @returns The UseCase instance or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * const createUser = useUseCaseFromContext<[CreateUserInput], User>("createUser");
+ * if (!createUser) return null;
+ * const { execute, loading } = useUseCase(createUser);
+ * ```
+ */
+export declare function useUseCaseFromContext<TArgs extends any[], TResult>(key: string): UseCase<TArgs, TResult> | undefined;

package/.build/Provider/useContextHooks.js

@@ -0,0 +1,40 @@
+import { useCAFContext } from "./CAFContext";
+/**
+ * Hook to get a Ploc from the nearest CAFProvider by key.
+ * Returns `undefined` when the key is not registered or when used outside a provider
+ * (default context has empty plocs). Use the generic for type-safe access.
+ *
+ * @param key - Key used when registering the Ploc in CAFProvider (e.g. "user", "auth")
+ * @returns The Ploc instance or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * const userPloc = usePlocFromContext<UserPloc>("user");
+ * if (!userPloc) return <NotFound />;
+ * const [state, ploc] = usePloc(userPloc);
+ * return <span>{state.name}</span>;
+ * ```
+ */
+export function usePlocFromContext(key) {
+    const { plocs } = useCAFContext();
+    return plocs[key];
+}
+/**
+ * Hook to get a UseCase from the nearest CAFProvider by key.
+ * Returns `undefined` when the key is not registered or when used outside a provider
+ * (default context has empty useCases). Use generics for type-safe args and result.
+ *
+ * @param key - Key used when registering the UseCase in CAFProvider (e.g. "createUser", "login")
+ * @returns The UseCase instance or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * const createUser = useUseCaseFromContext<[CreateUserInput], User>("createUser");
+ * if (!createUser) return null;
+ * const { execute, loading } = useUseCase(createUser);
+ * ```
+ */
+export function useUseCaseFromContext(key) {
+    const { useCases } = useCAFContext();
+    return useCases[key];
+}

package/.build/index.d.ts

@@ -5,3 +5,4 @@ export * from './Ploc';
 export * from './UseCase';
 export * from './ErrorBoundary';
 export * from './DevTools';
+export * from './Provider';

package/.build/index.js

@@ -5,3 +5,4 @@ export * from './Ploc';
 export * from './UseCase';
 export * from './ErrorBoundary';
 export * from './DevTools';
+export * from './Provider';

package/README.md

@@ -249,6 +249,73 @@ function UserComponent({ userPloc }: { userPloc: UserPloc }) {
 
 The DevTools data is also exposed to `window.__CAF_DEVTOOLS__` for React DevTools extension integration.
 
+### CAFProvider (Ploc/UseCase provisioning)
+
+Register Plocs and UseCases at the app root so any descendant can access them without prop drilling. Use a single provider with all keys, or nest providers for feature-specific instances.
+
+**Wiring at app root:** Create your Plocs and UseCases once (e.g. in the root component or a bootstrap module), pass them into `CAFProvider` by key, and wrap your app. Any descendant can then read them via `usePlocFromContext(key)` or `useUseCaseFromContext(key)` without prop drilling.
+
+**Minimal example (wrap app, inject Ploc, consume in child):**
+
+```tsx
+import { CAFProvider, usePlocFromContext, usePloc } from '@c.a.f/infrastructure-react';
+
+// Root: wrap app and inject Plocs by key
+function main() {
+  const counterPloc = new CounterPloc(0);
+  root.render(
+    <CAFProvider plocs={{ counter: counterPloc }}>
+      <App />
+    </CAFProvider>
+  );
+}
+
+// Child: consume from context (no props)
+function Counter() {
+  const ploc = usePlocFromContext<CounterPloc>('counter');
+  if (!ploc) return null;
+  const [state, p] = usePloc(ploc);
+  return <button onClick={() => p.increment()}>{state}</button>;
+}
+```
+
+**Recommended: single provider at root**
+
+```typescript
+import { CAFProvider, usePlocFromContext, useUseCaseFromContext, usePloc, useUseCase } from '@c.a.f/infrastructure-react';
+
+// At app root: create Plocs/UseCases (e.g. with useMemo) and pass by key
+function AppRoot() {
+  const userPloc = useMemo(() => new UserPloc(userRepo), [userRepo]);
+  const createUser = useMemo(() => new CreateUser(repo), [repo]);
+
+  return (
+    <CAFProvider plocs={{ user: userPloc }} useCases={{ createUser }}>
+      <App />
+    </CAFProvider>
+  );
+}
+
+// In any descendant: typed hooks (return undefined if key not registered)
+function UserProfile() {
+  const userPloc = usePlocFromContext<UserPloc>('user');
+  if (!userPloc) return null;
+  const [state, ploc] = usePloc(userPloc);
+  return <span>{state.name}</span>;
+}
+
+function CreateUserForm() {
+  const createUser = useUseCaseFromContext<[CreateUserInput], User>('createUser');
+  if (!createUser) return null;
+  const { execute, loading, error } = useUseCase(createUser);
+  // ...
+}
+```
+
+You can also use `useCAFContext()` and read `.plocs[key]` / `.useCases[key]` when you need the raw registry. When the key is missing or outside a provider, `usePlocFromContext` and `useUseCaseFromContext` return `undefined` (no throw).
+
+**Nested providers:** Inner provider does not merge with outer; children see only the nearest provider’s `plocs` / `useCases`. Prefer one root provider with all keys.
+
 ### useRouteManager
 
 Hook that provides a `RouteManager` from `@c.a.f/core`:
@@ -297,6 +364,11 @@ function MyComponent() {
 - `useUseCase` — Hook that wraps UseCase execution with loading/error/data state management; handles RequestResult subscriptions automatically
 - `CAFErrorBoundary` — Error Boundary component that catches errors from Ploc/UseCase execution; provides error context via React Context
 - `useCAFError` — Hook to access error context from CAFErrorBoundary
+- `CAFProvider` — Root-level provider for Plocs and UseCases (by key); descendants access via `useCAFContext()` or typed hooks
+- `useCAFContext` — Hook to read the CAF context (`plocs` and `useCases` registries from the nearest `CAFProvider`)
+- `usePlocFromContext` — Hook to get a Ploc by key from context; returns `undefined` if key not registered (generic for type safety)
+- `useUseCaseFromContext` — Hook to get a UseCase by key from context; returns `undefined` if key not registered (generics for args/result)
+- `CAFContext` — React context used by `CAFProvider` (for advanced use)
 - `usePlocDevTools` — Hook that provides DevTools for a Ploc instance; enables state tracking and time-travel debugging
 - `useUseCaseDevTools` — Hook that provides DevTools for UseCase execution tracking
 - `useCAFDevTools` — Main hook that provides centralized DevTools access; tracks all Plocs and UseCases

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@c.a.f/infrastructure-react",
-  "type": "module",
-  "version": "1.0.2",
-  "description": "Clean Architecture Frontend (CAF) — React adapters: usePloc, useUseCase, CAFErrorBoundary, DevTools, useRouteManager, useRouteRepository.",
-  "keywords": [
-    "clean-architecture-frontend",
-    "clean-architecture",
-    "caf",
-    "infrastructure",
-    "react",
-    "routing",
-    "hooks",
-    "ploc",
-    "state-management",
-    "devtools",
-    "debugging"
-  ],
-  "author": "ali aslani <aliaslani.mm@gmail.com>",
-  "license": "MIT",
-  "repository": "https://github.com/ialiaslani/caf.git",
-  "main": "./.build/index.js",
-  "module": "./.build/index.js",
-  "types": "./.build/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./.build/index.d.ts",
-      "import": "./.build/index.js",
-      "node": "./.build/index.js",
-      "default": "./.build/index.js"
-    }
-  },
-  "files": [
-    ".build"
-  ],
-  "scripts": {
-    "build": "tsc --build",
-    "start": "tsc --watch",
-    "prepublishOnly": "npm run build",
-    "test": "node_modules/.bin/vitest run",
-    "test:watch": "node_modules/.bin/vitest"
-  },
-  "dependencies": {
-    "@c.a.f/core": "^1.0.3",
-    "@c.a.f/devtools": "^1.0.2",
-    "react-router-dom": "^6.23.1"
-  },
-  "peerDependencies": {
-    "react": ">=16.8.0"
-  },
-  "devDependencies": {
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/jest-dom": "^6.1.5",
-    "@testing-library/react": "^16.0.0",
-    "happy-dom": "^15.11.7",
-    "vitest": "^2.1.0"
-  }
-}
+{
+  "name": "@c.a.f/infrastructure-react",
+  "type": "module",
+  "version": "1.0.4",
+  "description": "Clean Architecture Frontend (CAF) — React adapters: usePloc, useUseCase, CAFErrorBoundary, DevTools, useRouteManager, useRouteRepository.",
+  "keywords": [
+    "clean-architecture-frontend",
+    "clean-architecture",
+    "caf",
+    "infrastructure",
+    "react",
+    "routing",
+    "hooks",
+    "ploc",
+    "state-management",
+    "devtools",
+    "debugging"
+  ],
+  "author": "ali aslani <aliaslani.mm@gmail.com>",
+  "license": "MIT",
+  "repository": "https://github.com/ialiaslani/caf.git",
+  "main": "./.build/index.js",
+  "module": "./.build/index.js",
+  "types": "./.build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./.build/index.d.ts",
+      "import": "./.build/index.js",
+      "node": "./.build/index.js",
+      "default": "./.build/index.js"
+    }
+  },
+  "files": [
+    ".build"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "start": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "node_modules/.bin/vitest run",
+    "test:watch": "node_modules/.bin/vitest"
+  },
+  "dependencies": {
+    "@c.a.f/core": "^1.0.3",
+    "@c.a.f/devtools": "^1.0.2",
+    "react-router-dom": "^6.23.1"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.1.5",
+    "@testing-library/react": "^16.0.0",
+    "happy-dom": "^15.11.7",
+    "vitest": "^2.1.0"
+  }
+}