@blac/react

@blac/react

React integration for the BlaC state management library with automatic re-render optimization.

Installation

npm install @blac/react @blac/core
# or
pnpm add @blac/react @blac/core
# or
yarn add @blac/react @blac/core

Quick Start

import { Cubit } from '@blac/core';
import { useBloc } from '@blac/react';

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, counter] = useBloc(CounterCubit);

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={counter.increment}>+</button>
      <button onClick={counter.decrement}>-</button>
    </div>
  );
}

Hooks

useBloc

Connects a component to a state container with automatic re-renders on state changes.

const [state, bloc, ref] = useBloc(MyBloc);

Returns: [state, bloc, ref]

• state - Current state (reactive)
• bloc - The bloc instance for calling methods
• ref - Component reference for isolated instances

Tracking Modes

Auto-tracking (default): Automatically detects which properties you access and only re-renders when those change.

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.

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.

function FullState() {
  const [state] = useBloc(MyBloc, { autoTrack: false });

  return <pre>{JSON.stringify(state)}</pre>;
}

Options

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

  // Lifecycle callbacks
  onMount: (bloc) => console.log('Mounted', bloc),
  onUnmount: (bloc) => console.log('Unmounted', bloc),
});

useBlocActions

Connects to a state container without subscribing to state changes. Use for calling actions without re-renders, or for stateless containers.

const bloc = useBlocActions(MyBloc);

Use cases:

// 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>;
}

Options

useBlocActions(MyBloc, {
  instanceId: 'unique-id', // Custom instance identifier
  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:

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:

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:

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:

import { configureBlacReact } from '@blac/react';

configureBlacReact({
  autoTrack: true, // Enable auto-tracking by default (default: true)
});

API Reference

useBloc

function useBloc<T extends StateContainerConstructor>(
  BlocClass: T,
  options?: UseBlocOptions<T>,
): [ExtractState<T>, InstanceType<T>, ComponentRef];

useBlocActions

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
onMount	(bloc) => void	Called when component mounts
onUnmount	(bloc) => void	Called when component unmounts

UseBlocActionsOptions

Option	Type	Description
instanceId	string | number	Custom instance identifier
onMount	(bloc) => void	Called when component mounts
onUnmount	(bloc) => void	Called when component unmounts

Compatibility

• React 18.0+ or React 19.0+
• Works with React Compiler
• Supports concurrent rendering via useSyncExternalStore

License

MIT