@blac/react 2.0.4 → 2.0.5

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Global configuration for @blac/react
+ */
+export interface BlacReactConfig {
+    /** Enable automatic property tracking via Proxy (default: true) */
+    autoTrack: boolean;
+}
+/**
+ * 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
+ */
+export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
+/**
+ * Get the current global configuration.
+ * @internal
+ */
+export declare function getBlacReactConfig(): BlacReactConfig;
+/**
+ * Reset configuration to defaults (useful for testing).
+ * @internal
+ */
+export declare function resetBlacReactConfig(): void;

package/dist/index.d.cts

@@ -1,96 +1,11 @@
-import type { ExtractState } from '@blac/core';
-import { ExtractState as ExtractState_2 } from '@blac/adapter';
-import { InstanceReadonlyState } from '@blac/core';
-import type { RefObject } from 'react';
-import { StateContainerConstructor } from '@blac/adapter';
-import type { StateContainerConstructor as StateContainerConstructor_2 } from '@blac/core';
-
-/**
- * Global configuration for @blac/react
- */
-export declare interface BlacReactConfig {
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack: boolean;
-}
-
-/* Excluded from this release type: ComponentRef */
-
-/**
- * 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
- */
-export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
-
-/**
- * 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
- *
- * @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]
- *
- * @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'
- * });
- * ```
- */
-export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState_2<T>>;
-
-/**
- * Configuration options for useBloc hook
- * @template TBloc - The state container type
- */
-export declare interface UseBlocOptions<TBloc extends StateContainerConstructor_2> {
-    /** Custom instance identifier for shared or isolated instances */
-    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 */
-    onMount?: (bloc: InstanceType<TBloc>) => void;
-    /** Callback invoked when bloc instance unmounts */
-    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)
- * - [1] State container instance (bloc) for calling actions
- * - [2] Ref object for accessing component ref (advanced use cases)
- *
- * @template TBloc - The state container type
- */
-export declare type UseBlocReturn<TBloc extends StateContainerConstructor_2, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
-
-export { }
+/**
+ * React Integration
+ *
+ * Clean integration between React and StateContainer architecture.
+ * Constructor-based API with automatic type inference.
+ * Supports concurrent (useSyncExternalStore) mode for optimal performance.
+ */
+export { useBloc } from './useBloc';
+export { configureBlacReact } from './config';
+export type { BlacReactConfig } from './config';
+export type { UseBlocOptions, UseBlocReturn } from './types';

package/dist/index.d.ts

@@ -1,96 +1,11 @@
-import type { ExtractState } from '@blac/core';
-import { ExtractState as ExtractState_2 } from '@blac/adapter';
-import { InstanceReadonlyState } from '@blac/core';
-import type { RefObject } from 'react';
-import { StateContainerConstructor } from '@blac/adapter';
-import type { StateContainerConstructor as StateContainerConstructor_2 } from '@blac/core';
-
-/**
- * Global configuration for @blac/react
- */
-export declare interface BlacReactConfig {
-    /** Enable automatic property tracking via Proxy (default: true) */
-    autoTrack: boolean;
-}
-
-/* Excluded from this release type: ComponentRef */
-
-/**
- * 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
- */
-export declare function configureBlacReact(config: Partial<BlacReactConfig>): void;
-
-/**
- * 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
- *
- * @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]
- *
- * @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'
- * });
- * ```
- */
-export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState_2<T>>;
-
-/**
- * Configuration options for useBloc hook
- * @template TBloc - The state container type
- */
-export declare interface UseBlocOptions<TBloc extends StateContainerConstructor_2> {
-    /** Custom instance identifier for shared or isolated instances */
-    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 */
-    onMount?: (bloc: InstanceType<TBloc>) => void;
-    /** Callback invoked when bloc instance unmounts */
-    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)
- * - [1] State container instance (bloc) for calling actions
- * - [2] Ref object for accessing component ref (advanced use cases)
- *
- * @template TBloc - The state container type
- */
-export declare type UseBlocReturn<TBloc extends StateContainerConstructor_2, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
-
-export { }
+/**
+ * React Integration
+ *
+ * Clean integration between React and StateContainer architecture.
+ * Constructor-based API with automatic type inference.
+ * Supports concurrent (useSyncExternalStore) mode for optimal performance.
+ */
+export { useBloc } from './useBloc';
+export { configureBlacReact } from './config';
+export type { BlacReactConfig } from './config';
+export type { UseBlocOptions, UseBlocReturn } from './types';

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+import type { ExtractState, StateContainerConstructor } from '@blac/core';
+import { InstanceReadonlyState } from '@blac/core';
+import type { RefObject } from 'react';
+/**
+ * Configuration options for useBloc hook
+ * @template TBloc - The state container type
+ */
+export interface UseBlocOptions<TBloc extends StateContainerConstructor> {
+    /** Custom instance identifier for shared or isolated instances */
+    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 */
+    onMount?: (bloc: InstanceType<TBloc>) => void;
+    /** Callback invoked when bloc instance unmounts */
+    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)
+ * - [1] State container instance (bloc) for calling actions
+ * - [2] Ref object for accessing component ref (advanced use cases)
+ *
+ * @template TBloc - The state container type
+ */
+export type UseBlocReturn<TBloc extends StateContainerConstructor, S = ExtractState<TBloc>> = [S, InstanceReadonlyState<TBloc>, RefObject<ComponentRef>];
+/**
+ * Internal ref structure for component-bloc binding
+ * @internal
+ */
+export type ComponentRef = {
+    /** Cached bloc instance ID for this component */
+    __blocInstanceId?: string;
+};

package/dist/useBloc.d.ts

@@ -0,0 +1,35 @@
+import { type ExtractState, type StateContainerConstructor } from '@blac/adapter';
+import type { UseBlocOptions, UseBlocReturn } from './types';
+/**
+ * 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
+ *
+ * @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]
+ *
+ * @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'
+ * });
+ * ```
+ */
+export declare function useBloc<T extends StateContainerConstructor = StateContainerConstructor>(BlocClass: T, options?: UseBlocOptions<T>): UseBlocReturn<T, ExtractState<T>>;

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

@@ -0,0 +1,18 @@
+/**
+ * Instance key generation utilities for React integration
+ */
+import type { ComponentRef } from '../types';
+/**
+ * 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
+ */
+export declare function generateInstanceKey(componentRef: ComponentRef, isIsolated: boolean, providedId?: string | number): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/react",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "repository": {
@@ -28,11 +28,7 @@
     }
   },
   "files": [
-    "dist/index.js",
-    "dist/index.cjs",
-    "dist/index.d.ts",
-    "dist/index.d.cts",
-    "dist/*.map",
+    "dist",
     "README.md",
     "LICENSE"
   ],
@@ -47,7 +43,7 @@
     "bloc-pattern"
   ],
   "dependencies": {
-    "@blac/adapter": "2.0.4"
+    "@blac/adapter": "2.0.5"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
@@ -79,15 +75,13 @@
     "react-dom": "^19.1.1",
     "tsdown": "^0.15.7",
     "typescript": "^5.9.2",
+    "publint": "^0.3.12",
     "vitest": "3.2.4",
-    "@blac/core": "2.0.4"
+    "@blac/core": "2.0.5"
   },
   "scripts": {
     "dev": "tsdown --watch",
-    "build": "pnpm build:js && pnpm build:types && pnpm build:dts",
-    "build:js": "tsdown",
-    "build:types": "tsc -p tsconfig.build.json",
-    "build:dts": "api-extractor run --local && cp dist/index.d.ts dist/index.d.cts && rm -rf dist/.types",
+    "build": "tsdown && tsc -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
     "clean": "rm -rf dist",
     "format": "prettier --write \".\"",
     "lint": "eslint src --ext .ts,.tsx",
@@ -99,6 +93,7 @@
     "test:compiler": "vitest run --config vitest.config.compiler.ts",
     "test:watch:compiler": "vitest --watch --config vitest.config.compiler.ts",
     "test:both": "pnpm test && echo '\n\n=== Running tests WITH React Compiler ===\n' && pnpm test:compiler",
+    "verify": "publint",
     "typecheck": "tsc --noEmit",
     "deploy": "pnpm publish --access public"
   }