@blac/react 2.0.0 → 2.0.1

package/README.md

@@ -1,194 +1,272 @@
 # @blac/react
 
-A powerful React integration for the Blac state management library, providing seamless integration between React components and Blac's reactive state management system.
-
-## Features
-
-- 🔄 Automatic re-rendering when relevant state changes
-- 🎯 Fine-grained dependency tracking
-- 🔍 Property access tracking for optimized updates
-- 🎨 TypeScript support with full type inference
-- ⚡️ Efficient state management with minimal boilerplate
-- 🔄 Support for isolated and shared bloc instances
-- 🎯 Custom dependency selectors for precise control
-
-## Important: Arrow Functions Required
-
-All methods in Bloc or Cubit classes must use arrow function syntax (`method = () => {}`) instead of the traditional method syntax (`method() {}`). This is because arrow functions automatically bind `this` to the class instance. Without this binding, methods called from React components would lose their context and could not access instance properties like `this.state` or `this.emit()`.
-
-```tsx
-// Correct way to define methods in your Bloc/Cubit classes
-class CounterBloc extends Cubit<CounterState> {
-  increment = () => {
-    this.emit({ ...this.state, count: this.state.count + 1 });
-  }
-
-  decrement = () => {
-    this.emit({ ...this.state, count: this.state.count - 1 });
-  }
-}
-
-// Incorrect way (will cause issues when called from React):
-class CounterBloc extends Cubit<CounterState> {
-  increment() { // ❌ Will lose 'this' context when called from components
-    this.emit({ ...this.state, count: this.state.count + 1 });
-  }
-}
-```
+React integration for the BlaC state management library with automatic re-render optimization.
 
 ## Installation
 
 ```bash
-npm install @blac/react
+npm install @blac/react @blac/core
 # or
-yarn add @blac/react
+pnpm add @blac/react @blac/core
 # or
-pnpm add @blac/react
+yarn add @blac/react @blac/core
 ```
 
 ## Quick Start
 
 ```tsx
+import { Cubit } from '@blac/core';
 import { useBloc } from '@blac/react';
-import { CounterBloc } from './CounterBloc';
+
+class CounterCubit extends Cubit<{ count: number }> {
+  constructor() {
+    super({ count: 0 });
+  }
+
+  increment = () => this.emit({ count: this.state.count + 1 });
+  decrement = () => this.emit({ count: this.state.count - 1 });
+}
 
 function Counter() {
-  const [state, counterBloc] = useBloc(CounterBloc);
+  const [state, counter] = useBloc(CounterCubit);
 
   return (
     <div>
       <p>Count: {state.count}</p>
-      <button onClick={() => counterBloc.increment()}>Increment</button>
+      <button onClick={counter.increment}>+</button>
+      <button onClick={counter.decrement}>-</button>
     </div>
   );
 }
 ```
 
-## Usage
+## Hooks
 
-### Basic Usage
+### useBloc
 
-The `useBloc` hook provides a simple way to connect your React components to Blac's state management system:
+Connects a component to a state container with automatic re-renders on state changes.
 
 ```tsx
-const [state, bloc] = useBloc(YourBloc);
+const [state, bloc, ref] = useBloc(MyBloc);
 ```
 
-### Advanced Configuration
+**Returns:** `[state, bloc, ref]`
+
+- `state` - Current state (reactive)
+- `bloc` - The bloc instance for calling methods
+- `ref` - Component reference for isolated instances
 
-The hook accepts configuration options for more control:
+#### Tracking Modes
+
+**Auto-tracking (default):** Automatically detects which properties you access and only re-renders when those change.
 
 ```tsx
-const [state, bloc] = useBloc(YourBloc, {
-  id: 'custom-id', // Optional: Custom identifier for the bloc
-  props: { /* ... */ }, // Optional: Props to pass to the bloc
-  onMount: (bloc) => { /* ... */ }, // Optional: Callback when bloc is mounted (similar to useEffect(<>, []))
-  dependencySelector: (newState, oldState) => [/* ... */], // Optional: Custom dependency tracking
+function UserProfile() {
+  const [state, user] = useBloc(UserBloc);
+
+  // Only re-renders when state.name changes
+  // (state.email changes won't cause re-render)
+  return <h1>{state.name}</h1>;
+}
+```
+
+**Manual dependencies:** Explicit dependency array like `useEffect`.
+
+```tsx
+function Counter() {
+  const [state] = useBloc(CounterBloc, {
+    dependencies: (state) => [state.count],
+  });
+
+  return <p>{state.count}</p>;
+}
+```
+
+**No tracking:** Returns full state, re-renders on any change.
+
+```tsx
+function FullState() {
+  const [state] = useBloc(MyBloc, { autoTrack: false });
+
+  return <pre>{JSON.stringify(state)}</pre>;
+}
+```
+
+#### Options
+
+```tsx
+useBloc(MyBloc, {
+  // Tracking mode
+  autoTrack: true, // Enable/disable auto-tracking (default: true)
+  dependencies: (state) => [state.prop], // Manual dependencies
+
+  // Instance management
+  instanceId: 'unique-id', // Custom instance identifier
+  props: { userId: 123 }, // Props passed to bloc
+
+  // Lifecycle callbacks
+  onMount: (bloc) => console.log('Mounted', bloc),
+  onUnmount: (bloc) => console.log('Unmounted', bloc),
 });
 ```
 
-### Dependency Tracking
+### useBlocActions
 
-The hook automatically tracks which state properties are accessed in your component and only triggers re-renders when those specific properties change:
+Connects to a state container without subscribing to state changes. Use for calling actions without re-renders, or for stateless containers.
 
 ```tsx
-function UserProfile() {
-  const [state, userBloc] = useBloc(UserBloc);
+const bloc = useBlocActions(MyBloc);
+```
 
-  // Only re-renders when state.name changes
-  return <h1>{state.name}</h1>;
+**Use cases:**
+
+```tsx
+// Stateless services (analytics, navigation, etc.)
+function TrackButton() {
+  const analytics = useBlocActions(AnalyticsService);
+
+  return (
+    <button onClick={() => analytics.trackClick('button')}>Click me</button>
+  );
+}
+
+// Actions-only (no state subscription)
+function IncrementButton() {
+  const counter = useBlocActions(CounterCubit);
+
+  return <button onClick={counter.increment}>+</button>;
 }
 ```
 
-This also works for getters on the Bloc or Cubit class:
+#### Options
 
 ```tsx
-function UserProfile() {
-  const [, userBloc] = useBloc(UserBloc);
+useBlocActions(MyBloc, {
+  instanceId: 'unique-id', // Custom instance identifier
+  props: { config: value }, // Props passed to bloc
+  onMount: (bloc) => bloc.initialize(),
+  onUnmount: (bloc) => bloc.cleanup(),
+});
+```
+
+## Instance Management
+
+### Shared Instances (Default)
+
+By default, all components using the same bloc class share one instance:
+
+```tsx
+function ComponentA() {
+  const [state] = useBloc(CounterCubit);
+  // Uses shared instance
+}
+
+function ComponentB() {
+  const [state] = useBloc(CounterCubit);
+  // Uses same shared instance
+}
+```
+
+### Isolated Instances
+
+For component-scoped state, use the `@blac({ isolated: true })` decorator:
+
+```tsx
+import { Cubit, blac } from '@blac/core';
+
+@blac({ isolated: true })
+class FormCubit extends Cubit<FormState> {
+  // ...
+}
+
+function FormA() {
+  const [state] = useBloc(FormCubit);
+  // Gets its own instance
+}
+
+function FormB() {
+  const [state] = useBloc(FormCubit);
+  // Gets a different instance
+}
+```
+
+### Named Instances
+
+Share instances across specific components with `instanceId`:
+
+```tsx
+function EditorA() {
+  const [state] = useBloc(EditorCubit, { instanceId: 'editor-1' });
+}
+
+function EditorB() {
+  const [state] = useBloc(EditorCubit, { instanceId: 'editor-1' });
+  // Same instance as EditorA
+}
 
-  // Only re-renders when the return value from the getter formattedName changes
-  return <h1>{userBloc.formattedName}</h1>;
+function EditorC() {
+  const [state] = useBloc(EditorCubit, { instanceId: 'editor-2' });
+  // Different instance
 }
 ```
 
-### Custom Dependency Selector
+## Configuration
 
-For more control over when your component re-renders, you can provide a custom dependency selector:
+Configure global behavior:
 
 ```tsx
-const [state, bloc] = useBloc(YourBloc, {
-  dependencySelector: (newState, oldState) => [
-    newState.specificField,
-    newState.anotherField
-  ]
+import { configureBlacReact } from '@blac/react';
+
+configureBlacReact({
+  autoTrack: true, // Enable auto-tracking by default (default: true)
 });
 ```
 
 ## API Reference
 
-### useBloc Hook
+### useBloc
 
-```typescript
-function useBloc<B extends BlocConstructor<BlocGeneric>>(
-  bloc: B,
-  options?: BlocHookOptions<InstanceType<B>>
-): [BlocState<InstanceType<B>>, InstanceType<B>]
+```tsx
+function useBloc<T extends StateContainerConstructor>(
+  BlocClass: T,
+  options?: UseBlocOptions<T>,
+): [ExtractState<T>, InstanceType<T>, ComponentRef];
 ```
 
-#### Options
+### useBlocActions
+
+```tsx
+function useBlocActions<T extends StateContainerConstructor>(
+  BlocClass: T,
+  options?: UseBlocActionsOptions<InstanceType<T>>,
+): InstanceType<T>;
+```
+
+### UseBlocOptions
+
+| Option         | Type               | Description                          |
+| -------------- | ------------------ | ------------------------------------ |
+| `autoTrack`    | `boolean`          | Enable auto-tracking (default: true) |
+| `dependencies` | `(state) => any[]` | Manual dependency selector           |
+| `instanceId`   | `string \| number` | Custom instance identifier           |
+| `props`        | `P`                | Props passed to bloc constructor     |
+| `onMount`      | `(bloc) => void`   | Called when component mounts         |
+| `onUnmount`    | `(bloc) => void`   | Called when component unmounts       |
+
+### UseBlocActionsOptions
+
+| Option       | Type               | Description                      |
+| ------------ | ------------------ | -------------------------------- |
+| `instanceId` | `string \| number` | Custom instance identifier       |
+| `props`      | `P`                | Props passed to bloc constructor |
+| `onMount`    | `(bloc) => void`   | Called when component mounts     |
+| `onUnmount`  | `(bloc) => void`   | Called when component unmounts   |
+
+## Compatibility
 
-- `id?: string` - Custom identifier for the bloc instance
-- `props?: InferPropsFromGeneric<B>` - Props to pass to the bloc
-- `onMount?: (bloc: B) => void` - Callback function invoked when the react component (the consumer) is connected to the bloc instance
-- `dependencySelector?: BlocHookDependencyArrayFn<B>` - Function to select dependencies for re-renders
-
-## Best Practices
-
-1. **Use Isolated Blocs**: When you need component-specific state, use isolated blocs:
-   ```tsx
-   class MyIsolatedBloc extends BlocBase {
-     static isolated = true;
-     // ... rest of your bloc implementation
-   }
-   ```
-
-2. **Use Custom Identifiers**: When you need multiple independent instances of the same Bloc type, use custom identifiers to manage different state contexts:
-   ```tsx
-   // In a chat application with multiple chat rooms
-   function ChatRoom({ roomId }: { roomId: string }) {
-     const [state, chatBloc] = useBloc(ChatBloc, {
-       id: `chat-${roomId}`, // Each room gets its own instance
-       props: { roomId }
-     });
-
-     return (
-       <div>
-         <h2>Room: {roomId}</h2>
-         {state.messages.map(msg => (
-           <Message key={msg.id} message={msg} />
-         ))}
-       </div>
-     );
-   }
-
-   // Usage:
-   function ChatApp() {
-     return (
-       <div>
-         <ChatRoom roomId="general" />
-         <ChatRoom roomId="support" />
-       </div>
-     );
-   }
-   ```
-
-3. **Optimize Re-renders**: Let the hook track dependencies automatically unless you have a specific need for custom dependency tracking.
-
-4. **Type Safety**: Take advantage of TypeScript's type inference for better development experience and catch errors early.
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
+- React 18.0+ or React 19.0+
+- Works with React Compiler
+- Supports concurrent rendering via `useSyncExternalStore`
 
 ## License
 

package/dist/index.cjs

@@ -0,0 +1,260 @@
+let react = require("react");
+let _blac_core = require("@blac/core");
+
+//#region src/utils/instance-keys.ts
+/**
+* Instance key generation utilities for React integration
+*/
+/**
+* Generate an instance key for a bloc
+*
+* Logic:
+* - If user provides instanceId, use it (convert number to string)
+* - If isolated, generate or reuse a unique key for this component
+* - Otherwise, return undefined (use default key)
+*
+* @param componentRef - React component reference (persists across remounts)
+* @param isIsolated - Whether the bloc is isolated
+* @param providedId - User-provided instance ID (from options)
+* @returns Instance key string or undefined for default
+*/
+function generateInstanceKey(componentRef, isIsolated, providedId) {
+	if (providedId !== void 0) return typeof providedId === "number" ? String(providedId) : providedId;
+	if (isIsolated) {
+		if (!componentRef.__blocInstanceId) componentRef.__blocInstanceId = (0, _blac_core.generateIsolatedKey)();
+		return componentRef.__blocInstanceId;
+	}
+}
+
+//#endregion
+//#region src/config.ts
+const defaultConfig = { autoTrack: true };
+let globalConfig = { ...defaultConfig };
+/**
+* Configure global defaults for @blac/react hooks.
+*
+* @example
+* ```ts
+* import { configureBlacReact } from '@blac/react';
+*
+* // Disable auto-tracking globally
+* configureBlacReact({
+*   autoTrack: false
+* });
+* ```
+*
+* @param config - Partial configuration to merge with defaults
+*/
+function configureBlacReact(config) {
+	globalConfig = {
+		...globalConfig,
+		...config
+	};
+}
+/**
+* Get the current global configuration.
+* @internal
+*/
+function getBlacReactConfig() {
+	return globalConfig;
+}
+/**
+* Reset configuration to defaults (useful for testing).
+* @internal
+*/
+function resetBlacReactConfig() {
+	globalConfig = { ...defaultConfig };
+}
+
+//#endregion
+//#region src/useBloc.ts
+function determineTrackingMode(options) {
+	const globalConfig$1 = getBlacReactConfig();
+	const autoTrackEnabled = options?.autoTrack !== void 0 ? options.autoTrack : globalConfig$1.autoTrack;
+	return {
+		useManualDeps: options?.dependencies !== void 0,
+		autoTrackEnabled
+	};
+}
+/**
+* React hook that connects a component to a state container with automatic re-render on state changes.
+*
+* Supports three tracking modes:
+* - **Auto-tracking** (default): Automatically detects accessed state properties via Proxy
+* - **Manual dependencies**: Explicit dependency array like useEffect
+* - **No tracking**: Returns full state without optimization
+*
+* **Note:** This hook does NOT support stateless containers (StatelessCubit, StatelessVertex).
+* Use `useBlocActions()` instead for stateless containers.
+*
+* @template T - The state container constructor type (inferred from BlocClass)
+* @param BlocClass - The state container class to connect to (must not be stateless)
+* @param options - Configuration options for tracking mode and instance management
+* @returns Tuple with [state, bloc instance, ref]
+*
+* @example Basic usage
+* ```ts
+* const [state, myBloc, ref] = useBloc(MyBloc);
+* ```
+*
+* @example With manual dependencies
+* ```ts
+* const [state, myBloc] = useBloc(MyBloc, {
+*   dependencies: (state) => [state.count]
+* });
+* ```
+*
+* @example With isolated instance
+* ```ts
+* const [state, myBloc] = useBloc(MyBloc, {
+*   instanceId: 'unique-id'
+* });
+* ```
+*/
+function useBloc(BlocClass, options) {
+	const componentRef = (0, react.useRef)({});
+	const initialPropsRef = (0, react.useRef)(options?.props);
+	const isStateless = (0, _blac_core.isStatelessClass)(BlocClass);
+	const isIsolated = (0, _blac_core.isIsolatedClass)(BlocClass);
+	const [bloc, subscribe, getSnapshot, instanceKey, adapterState, rawInstance] = (0, react.useMemo)(() => {
+		if (isStateless) {
+			console.error(`[BlaC] useBloc() does not support stateless containers. "${BlocClass.name}" is a StatelessCubit or StatelessVertex. Use useBlocActions() instead for stateless containers.`);
+			const instance$1 = (0, _blac_core.acquire)(BlocClass, "default");
+			return [
+				instance$1,
+				() => () => {},
+				() => ({}),
+				void 0,
+				null,
+				instance$1
+			];
+		}
+		const instanceKey$1 = generateInstanceKey(componentRef.current, isIsolated, options?.instanceId);
+		const instance = (0, _blac_core.acquire)(BlocClass, instanceKey$1, { props: initialPropsRef.current });
+		if (initialPropsRef.current !== void 0) instance.updateProps(initialPropsRef.current);
+		const { useManualDeps, autoTrackEnabled } = determineTrackingMode(options);
+		let subscribeFn;
+		let getSnapshotFn;
+		let adapterState$1;
+		if (useManualDeps && options?.dependencies) {
+			adapterState$1 = (0, _blac_core.manualDepsInit)(instance);
+			subscribeFn = (0, _blac_core.manualDepsSubscribe)(instance, adapterState$1, { dependencies: options.dependencies });
+			getSnapshotFn = (0, _blac_core.manualDepsSnapshot)(instance, adapterState$1, { dependencies: options.dependencies });
+		} else if (!autoTrackEnabled) {
+			adapterState$1 = (0, _blac_core.noTrackInit)(instance);
+			subscribeFn = (0, _blac_core.noTrackSubscribe)(instance);
+			getSnapshotFn = (0, _blac_core.noTrackSnapshot)(instance);
+		} else {
+			adapterState$1 = (0, _blac_core.autoTrackInit)(instance);
+			subscribeFn = (0, _blac_core.autoTrackSubscribe)(instance, adapterState$1);
+			getSnapshotFn = (0, _blac_core.autoTrackSnapshot)(instance, adapterState$1);
+		}
+		return [
+			adapterState$1.proxiedBloc,
+			subscribeFn,
+			getSnapshotFn,
+			instanceKey$1,
+			adapterState$1,
+			instance
+		];
+	}, [
+		BlocClass,
+		isStateless,
+		isIsolated,
+		options?.instanceId
+	]);
+	const state = (0, react.useSyncExternalStore)(subscribe, getSnapshot);
+	const [, forceUpdate] = (0, react.useReducer)((x) => x + 1, 0);
+	const externalDepsManager = (0, react.useRef)(new _blac_core.ExternalDepsManager());
+	(0, react.useEffect)(() => {
+		if (isStateless) return;
+		if (options?.props !== initialPropsRef.current) rawInstance.updateProps(options?.props);
+	}, [
+		options?.props,
+		rawInstance,
+		isStateless
+	]);
+	(0, react.useEffect)(() => {
+		if (isStateless || !adapterState) return;
+		(0, _blac_core.disableGetterTracking)(adapterState, rawInstance);
+		externalDepsManager.current.updateSubscriptions(adapterState.getterState, rawInstance, forceUpdate);
+	});
+	(0, react.useEffect)(() => {
+		if (isStateless) return;
+		if (options?.onMount) options.onMount(bloc);
+		return () => {
+			externalDepsManager.current.cleanup();
+			if (options?.onUnmount) options.onUnmount(bloc);
+			(0, _blac_core.release)(BlocClass, instanceKey);
+			if (isIsolated && !rawInstance.isDisposed) rawInstance.dispose();
+		};
+	}, []);
+	return [
+		state,
+		bloc,
+		componentRef
+	];
+}
+
+//#endregion
+//#region src/useBlocActions.ts
+/**
+* React hook that connects to a state container instance without triggering re-renders.
+* Use this when you only need to call actions on the bloc without subscribing to state changes.
+*
+* **This is the recommended hook for stateless containers** (StatelessCubit, StatelessVertex).
+* It also works with regular Cubit/Vertex when you don't need state subscriptions.
+*
+* @template T - The state container constructor type (inferred from BlocClass)
+* @param BlocClass - The state container class to connect to (supports both stateful and stateless)
+* @param options - Configuration options for instance management and lifecycle
+* @returns The state container instance for calling actions
+*
+* @example Basic usage with stateless container
+* ```ts
+* class AnalyticsService extends StatelessCubit {
+*   trackEvent(name: string) { ... }
+* }
+*
+* const analytics = useBlocActions(AnalyticsService);
+* analytics.trackEvent('page_view');
+* ```
+*
+* @example With stateful container (no re-renders)
+* ```ts
+* const myBloc = useBlocActions(MyBloc);
+* myBloc.someMethod(); // Won't cause re-renders
+* ```
+*
+* @example With isolated instance
+* ```ts
+* const myBloc = useBlocActions(MyBloc, {
+*   instanceId: 'unique-id'
+* });
+* ```
+*/
+function useBlocActions(BlocClass, options) {
+	const componentRef = (0, react.useRef)({});
+	const initialPropsRef = (0, react.useRef)(options?.props);
+	const [bloc, instanceKey] = (0, react.useMemo)(() => {
+		const isIsolated = (0, _blac_core.isIsolatedClass)(BlocClass);
+		const instanceKey$1 = generateInstanceKey(componentRef.current, isIsolated, options?.instanceId);
+		return [(0, _blac_core.acquire)(BlocClass, instanceKey$1, { props: initialPropsRef.current }), instanceKey$1];
+	}, [BlocClass]);
+	(0, react.useEffect)(() => {
+		if (options?.onMount) options.onMount(bloc);
+		return () => {
+			if (options?.onUnmount) options.onUnmount(bloc);
+			(0, _blac_core.release)(BlocClass, instanceKey);
+			if ((0, _blac_core.isIsolatedClass)(BlocClass) && !bloc.isDisposed) bloc.dispose();
+		};
+	}, []);
+	return bloc;
+}
+
+//#endregion
+exports.configureBlacReact = configureBlacReact;
+exports.resetBlacReactConfig = resetBlacReactConfig;
+exports.useBloc = useBloc;
+exports.useBlocActions = useBlocActions;
+//# sourceMappingURL=index.cjs.map