@blac/react 2.0.0-rn-12 → 2.0.1

package/README.md

@@ -1,264 +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 with access to state, previous state, and instance
-- 🚀 Optimized re-rendering with intelligent snapshot comparison
-
-## 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]`
 
-The hook accepts configuration options for more control:
-
-```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(<>, []))
-  selector: (currentState, previousState, instance) => [/* ... */], // Optional: Custom dependency tracking
-});
-```
+- `state` - Current state (reactive)
+- `bloc` - The bloc instance for calling methods
+- `ref` - Component reference for isolated instances
 
-### Automatic Dependency Tracking
+#### Tracking Modes
 
-The hook automatically tracks which state properties and bloc instance properties are accessed in your component and only triggers re-renders when those specific values change:
+**Auto-tracking (default):** Automatically detects which properties you access and only re-renders when those change.
 
 ```tsx
 function UserProfile() {
-  const [state, userBloc] = useBloc(UserBloc);
+  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>;
 }
 ```
 
-This also works for getters and computed properties on the Bloc or Cubit class:
+**Manual dependencies:** Explicit dependency array like `useEffect`.
 
 ```tsx
-function UserProfile() {
-  const [state, userBloc] = useBloc(UserBloc);
+function Counter() {
+  const [state] = useBloc(CounterBloc, {
+    dependencies: (state) => [state.count],
+  });
 
-  // Only re-renders when:
-  // - state.firstName changes, OR
-  // - state.lastName changes (because the getter accesses these properties)
-  return <h1>{userBloc.fullName}</h1>; // Assuming fullName is a getter
+  return <p>{state.count}</p>;
 }
 ```
 
-#### How It Works
-
-The dependency tracking system uses JavaScript Proxies to monitor property access during component renders:
+**No tracking:** Returns full state, re-renders on any change.
 
-1. **State Properties**: When you access `state.propertyName`, it's automatically tracked
-2. **Instance Properties**: When you access `bloc.computedValue`, it's automatically tracked  
-3. **Intelligent Comparison**: The system separately tracks state dependencies and instance dependencies to handle edge cases where properties are dynamically added/removed
-4. **Optimized Updates**: Components only re-render when tracked dependencies actually change their values
+```tsx
+function FullState() {
+  const [state] = useBloc(MyBloc, { autoTrack: false });
 
-#### Configuring Proxy Tracking
+  return <pre>{JSON.stringify(state)}</pre>;
+}
+```
 
-By default, BlaC uses proxy-based dependency tracking for optimal performance. You can disable this globally if needed:
+#### Options
 
 ```tsx
-import { Blac } from '@blac/core';
+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),
+});
+```
+
+### useBlocActions
 
-// Disable automatic dependency tracking globally
-Blac.setConfig({ proxyDependencyTracking: false });
+Connects to a state container without subscribing to state changes. Use for calling actions without re-renders, or for stateless containers.
 
-// Now components will re-render on ANY state change
-// unless you provide manual dependencies
+```tsx
+const bloc = useBlocActions(MyBloc);
 ```
 
-When proxy tracking is disabled:
-- Components re-render on any state change (similar to traditional state management)
-- Manual dependencies via the `selector` option still work as expected
-- Useful for debugging or when proxy behavior causes issues
+**Use cases:**
+
+```tsx
+// Stateless services (analytics, navigation, etc.)
+function TrackButton() {
+  const analytics = useBlocActions(AnalyticsService);
 
-For more configuration options, see the [@blac/core documentation](https://www.npmjs.com/package/@blac/core).
+  return (
+    <button onClick={() => analytics.trackClick('button')}>Click me</button>
+  );
+}
 
-### Custom Dependency Selector
+// Actions-only (no state subscription)
+function IncrementButton() {
+  const counter = useBlocActions(CounterCubit);
 
-For more control over when your component re-renders, you can provide a custom dependency selector. The selector function receives the current state, previous state, and bloc instance, and should return an array of values to track:
+  return <button onClick={counter.increment}>+</button>;
+}
+```
+
+#### Options
 
 ```tsx
-const [state, bloc] = useBloc(YourBloc, {
-  selector: (currentState, previousState, instance) => [
-    currentState.specificField,
-    currentState.anotherField,
-    instance.computedValue // You can also track computed properties from the bloc instance
-  ]
+useBlocActions(MyBloc, {
+  instanceId: 'unique-id', // Custom instance identifier
+  props: { config: value }, // Props passed to bloc
+  onMount: (bloc) => bloc.initialize(),
+  onUnmount: (bloc) => bloc.cleanup(),
 });
 ```
 
-The component will only re-render when any of the values in the returned array change (using `Object.is` comparison, similar to React's `useEffect` dependency array).
+## Instance Management
+
+### Shared Instances (Default)
 
-#### Examples of Custom Selectors
+By default, all components using the same bloc class share one instance:
 
-**Track only specific state properties:**
 ```tsx
-const [state, userBloc] = useBloc(UserBloc, {
-  selector: (currentState) => [
-    currentState.name,
-    currentState.email
-  ] // Only re-render when name or email changes, ignore other properties
-});
+function ComponentA() {
+  const [state] = useBloc(CounterCubit);
+  // Uses shared instance
+}
+
+function ComponentB() {
+  const [state] = useBloc(CounterCubit);
+  // Uses same shared instance
+}
 ```
 
-**Track computed values:**
+### Isolated Instances
+
+For component-scoped state, use the `@blac({ isolated: true })` decorator:
+
 ```tsx
-const [state, shoppingCartBloc] = useBloc(ShoppingCartBloc, {
-  selector: (currentState, previousState, instance) => [
-    instance.totalPrice, // Computed getter
-    currentState.items.length // Number of items
-  ] // Only re-render when total price or item count changes
-});
+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
+}
 ```
 
-**Compare with previous state:**
+### Named Instances
+
+Share instances across specific components with `instanceId`:
+
 ```tsx
-const [state, chatBloc] = useBloc(ChatBloc, {
-  selector: (currentState, previousState) => [
-    currentState.messages.length > (previousState?.messages.length || 0) ? 'new-message' : 'no-change'
-  ] // Only re-render when new messages are added, not when existing messages change
+function EditorA() {
+  const [state] = useBloc(EditorCubit, { instanceId: 'editor-1' });
+}
+
+function EditorB() {
+  const [state] = useBloc(EditorCubit, { instanceId: 'editor-1' });
+  // Same instance as EditorA
+}
+
+function EditorC() {
+  const [state] = useBloc(EditorCubit, { instanceId: 'editor-2' });
+  // Different instance
+}
+```
+
+## Configuration
+
+Configure global behavior:
+
+```tsx
+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
-- `selector?: (currentState: BlocState<InstanceType<B>>, previousState: BlocState<InstanceType<B>> | undefined, instance: InstanceType<B>) => unknown[]` - 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. **Choose the Right Dependency Strategy**: 
-   - **Use automatic tracking** (default) for most cases - it's efficient and requires no setup
-   - **Use custom selectors** when you need complex logic, computed comparisons, or want to ignore certain property changes
-   - **Avoid custom selectors** for simple property access - automatic tracking is more efficient
-
-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