@blac/react 2.0.12 → 2.0.14

package/dist/types.d.ts

@@ -1,33 +1,63 @@
-import type { ExtractState, StateContainerConstructor } from '@blac/core';
-import { InstanceReadonlyState } from '@blac/core';
+import type { ExtractArgs, ExtractState, InstanceReadonlyState, StateContainerConstructor } from '@blac/core';
 import type { RefObject } from 'react';
 /**
- * Configuration options for useBloc hook
- * @template TBloc - The state container type
+ * Conditional `args` field: required when the bloc declares Args, forbidden
+ * (type `never`) when the bloc uses the default `void` Args.
  */
-export interface UseBlocOptions<TBloc extends StateContainerConstructor> {
-    /** Custom instance identifier */
+type ArgsOption<T extends StateContainerConstructor> = ExtractArgs<T> extends void ? {
+    args?: never;
+} : {
+    args: ExtractArgs<T>;
+};
+/**
+ * Configuration options for {@link useBloc}.
+ *
+ * @template TBloc - The state container constructor type
+ *
+ * @remarks
+ * The `dependencies` option from BlaC v1 has been removed — use `select`
+ * instead. Codemod: rename `dependencies` → `select`; the return value is
+ * still a tuple/array compared per-index via `Object.is`.
+ */
+export type UseBlocOptions<TBloc extends StateContainerConstructor> = ArgsOption<TBloc> & {
+    /**
+     * Per-consumer instance identifier. Overrides any `instanceId` provided
+     * by an ancestor {@link BlocProvider}.
+     */
     instanceId?: string | number;
-    /** Manual dependency array like useEffect (disables autoTrack) */
-    dependencies?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack?: boolean;
-    /** Callback invoked when bloc instance mounts */
+    /**
+     * Per-consumer re-render selector. When provided, the hook re-renders
+     * only when the returned array's elements change (Object.is per index).
+     * When omitted, auto-tracking is used: any state path read during the
+     * render is observed, and the hook re-renders when any of those paths
+     * change.
+     *
+     * Keep the selector referentially stable across renders (e.g. via
+     * `useCallback`) — passing a fresh function each render forces the
+     * subscription to re-key, which the underlying channel treats as a new
+     * consumer.
+     */
+    select?: (state: ExtractState<TBloc>, bloc: InstanceReadonlyState<TBloc>) => unknown[];
+    /** Callback invoked when this consumer mounts. */
     onMount?: (bloc: InstanceType<TBloc>) => void;
-    /** Callback invoked when bloc instance unmounts */
+    /**
+     * Callback invoked when this consumer unmounts. Fires *before* the
+     * registry releases its ref, so the bloc is still alive when this runs.
+     */
     onUnmount?: (bloc: InstanceType<TBloc>) => void;
-}
+};
 /**
- * Tuple return type from useBloc hook containing state, bloc instance, and ref
- * - [0] Current state value (with optional state type override)
+ * Tuple return type from {@link useBloc}.
+ * - [0] Current state value
  * - [1] State container instance (bloc) for calling actions
  * - [2] Ref object for accessing component ref (advanced use cases)
  *
- * @template TBloc - The state container type
+ * @template TBloc - The state container constructor type
  */
 export type UseBlocReturn<TBloc extends StateContainerConstructor, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
 /**
- * Internal ref structure for component-bloc binding
+ * Internal ref structure for component-bloc binding.
  * @internal
  */
 export type ComponentRef = Record<string, never>;
+export {};

package/dist/useBloc.d.ts

@@ -1,35 +1,46 @@
-import { type ExtractState, type StateContainerConstructor } from '@blac/adapter';
+import { type ExtractState, type StateContainerConstructor } from '@blac/core';
 import type { UseBlocOptions, UseBlocReturn } from './types';
 /**
- * React hook that connects a component to a state container with automatic re-render on state changes.
+ * 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
+ * Two tracking modes:
+ * - **Auto-tracking** (default): the returned state value is a proxy that
+ *   records read paths during render. The component re-renders when any
+ *   recorded path changes. Backed by `@dirtytalk/structural`'s
+ *   {@link trackRender} + the container's path-scoped `DirtyChannel`.
+ * - **Manual select**: pass `options.select` to opt out of auto-tracking.
+ *   The hook re-renders only when the returned array's elements change
+ *   (per-index `Object.is`). This replaces the v1 `dependencies` option.
+ *
+ * Lifecycle:
+ * - The bloc is acquired from the registry on mount and released on
+ *   unmount. The instance key is the explicit `options.instanceId`, then
+ *   the surrounding {@link BlocProvider} context, then the default key.
+ * - `options.onMount` fires after the bloc is acquired; `options.onUnmount`
+ *   fires *before* the registry releases its ref, so the bloc is still
+ *   alive when the callback runs.
  *
  * @template T - The state container constructor type (inferred from BlocClass)
  * @param BlocClass - The state container class to connect to
- * @param options - Configuration options for tracking mode and instance management
- * @returns Tuple with [state, bloc instance, ref]
+ * @param options - Configuration options
+ * @returns Tuple of `[state, bloc, ref]`
  *
  * @example Basic usage
  * ```ts
- * const [state, myBloc, ref] = useBloc(MyBloc);
+ * const [state, bloc] = useBloc(MyBloc);
  * ```
  *
- * @example With manual dependencies
+ * @example Manual select (replaces v1 `dependencies`)
  * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   dependencies: (state) => [state.count]
+ * const [state, bloc] = useBloc(MyBloc, {
+ *   select: (state) => [state.count],
  * });
  * ```
  *
- * @example With named instance
+ * @example Named instance
  * ```ts
- * const [state, myBloc] = useBloc(MyBloc, {
- *   instanceId: 'unique-id'
- * });
+ * const [state, bloc] = useBloc(MyBloc, { instanceId: 'cart-42' });
  * ```
  */
 export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState<T>>;

package/dist/utils/instance-keys.d.ts

@@ -7,4 +7,6 @@
  * @param providedId - User-provided instance ID (from options)
  * @returns Instance key string or undefined for default
  */
-export declare function generateInstanceKey(providedId?: string | number): string | undefined;
+export declare function generateInstanceKey(
+  providedId?: string | number,
+): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/react",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "description": "React bindings for BlaC — useBloc hook with automatic re-render optimization",
@@ -65,13 +65,13 @@
     "bloc-pattern"
   ],
   "dependencies": {
-    "@blac/adapter": "^2.0.13"
+    "@dirtytalk/structural": "^0.0.2"
   },
   "peerDependencies": {
     "@testing-library/react": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "@blac/core": "^2.0.12"
+    "@blac/core": "^2.0.14"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -102,7 +102,7 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@latest",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
     "vite-plus": "latest",
-    "@blac/core": "2.0.12"
+    "@blac/core": "2.0.14"
   },
   "scripts": {
     "dev": "vp pack --watch",