@blac/react 2.0.0-rc.1 → 2.0.0-rc.4

package/dist/index.d.cts

@@ -0,0 +1,368 @@
+import { RefObject } from "react";
+
+//#region ../blac/src/core/StateContainerRegistry.d.ts
+
+/**
+ * Registry for managing StateContainer instances
+ */
+declare class StateContainerRegistry {
+  private readonly instances;
+  private readonly types;
+  /**
+   * Register a type with isolation mode
+   */
+  register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+  /**
+   * Get or create a StateContainer instance
+   * For isolated: always creates new
+   * For shared: singleton per key
+   */
+  getOrCreate<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, key?: string, ...args: any[]): T;
+  /**
+   * Release a reference to an instance
+   * Disposes when ref count reaches zero (unless static keepAlive is true)
+   */
+  release<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, key?: string, forceDispose?: boolean): void;
+  /**
+   * Get all instances of a type (shared only, isolated aren't tracked)
+   */
+  getAll<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): T[];
+  /**
+   * Clear all instances of a type
+   */
+  clear<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+  /**
+   * Clear all instances from all types (for testing)
+   */
+  clearAll(): void;
+  /**
+   * Get registry statistics (for debugging)
+   */
+  getStats(): {
+    registeredTypes: number;
+    totalInstances: number;
+    typeBreakdown: Record<string, number>;
+  };
+  /**
+   * Get reference count for an instance
+   */
+  getRefCount<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, key?: string): number;
+  /**
+   * Check if an instance exists
+   */
+  hasInstance<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, key?: string): boolean;
+}
+//#endregion
+//#region ../blac/src/core/StateContainer.d.ts
+/**
+ * Configuration options for StateContainer
+ */
+interface StateContainerConfig {
+  /** Container name for debugging */
+  name?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom instance identifier */
+  instanceId?: string;
+}
+/**
+ * Listener function for state changes
+ */
+type StateListener<S$1> = (state: S$1) => void;
+/**
+ * Base abstract class for all state containers
+ */
+declare abstract class StateContainer<S$1> {
+  private static _registry;
+  /**
+   * Set a custom registry (mainly for testing)
+   */
+  static setRegistry(registry: StateContainerRegistry): void;
+  /**
+   * Register a type as isolated or shared
+   */
+  static register<T extends StateContainer<any>>(this: new (...args: any[]) => T, isolated?: boolean): void;
+  /**
+   * Get or create an instance
+   * @param key - Optional instance key for shared instances
+   * @param args - Constructor arguments
+   */
+  static getOrCreate<T extends StateContainer<any>>(this: new (...args: any[]) => T, key?: string, ...args: any[]): T;
+  /**
+   * Release a reference to an instance
+   * @param key - Optional instance key
+   * @param forceDispose - Force dispose regardless of ref count or keepAlive
+   */
+  static release<T extends StateContainer<any>>(this: new (...args: any[]) => T, key?: string, forceDispose?: boolean): void;
+  /**
+   * Get all instances of this type
+   */
+  static getAll<T extends StateContainer<any>>(this: new (...args: any[]) => T): T[];
+  /**
+   * Clear all instances of this type
+   */
+  static clear<T extends StateContainer<any>>(this: new (...args: any[]) => T): void;
+  /**
+   * Clear all instances from all types (for testing)
+   */
+  static clearAllInstances(): void;
+  /**
+   * Get registry statistics (for debugging)
+   */
+  static getStats(): {
+    registeredTypes: number;
+    totalInstances: number;
+    typeBreakdown: Record<string, number>;
+  };
+  /**
+   * Get reference count for an instance
+   * @param key - Optional instance key
+   */
+  static getRefCount<T extends StateContainer<any>>(this: new (...args: any[]) => T, key?: string): number;
+  /**
+   * Check if an instance exists
+   * @param key - Optional instance key
+   */
+  static hasInstance<T extends StateContainer<any>>(this: new (...args: any[]) => T, key?: string): boolean;
+  private _state;
+  private readonly listeners;
+  private _disposed;
+  private readonly config;
+  readonly name: string;
+  readonly debug: boolean;
+  readonly instanceId: string;
+  /**
+   * Create a new StateContainer
+   */
+  constructor(initialState: S$1, config?: StateContainerConfig);
+  /**
+   * Get the current state
+   */
+  get state(): S$1;
+  /**
+   * Check if disposed
+   */
+  get isDisposed(): boolean;
+  /**
+   * Subscribe to state changes
+   * @returns Unsubscribe function
+   */
+  subscribe(listener: StateListener<S$1>): () => void;
+  /**
+   * Dispose the container
+   */
+  dispose(): void;
+  /**
+   * Emit a new state (with change detection)
+   */
+  protected emit(newState: S$1): void;
+  /**
+   * Update state using a function
+   */
+  protected update(updater: (current: S$1) => S$1): void;
+  /**
+   * Optional disposal hook for subclasses
+   */
+  protected onDispose?(): void;
+  /**
+   * Optional state change hook for subclasses
+   */
+  protected onStateChange?(newState: S$1, previousState: S$1): void;
+}
+//#endregion
+//#region ../blac/src/types/branded.d.ts
+/**
+ * Branded types for type-safe IDs
+ * These types ensure that IDs can't be accidentally mixed up
+ */
+/**
+ * Helper type for cases where any object type is acceptable
+ * Used sparingly only where type cannot be more specific
+ * eslint-disable-next-line @typescript-eslint/no-explicit-any
+ */
+type AnyObject = any;
+//#endregion
+//#region ../blac/src/types/utilities.d.ts
+/**
+ * Extract state type from StateContainer
+ *
+ * @example
+ * ```ts
+ * class CounterBloc extends Cubit<number> { ... }
+ * type State = ExtractState<CounterBloc>; // number
+ * ```
+ */
+type ExtractState<T$1> = T$1 extends StateContainer<infer S> ? S : never;
+/**
+ * Bloc constructor type - represents a class constructor for StateContainer subclasses
+ * Includes static methods from StateContainer for instance management
+ *
+ * Note: Uses `any` for state type to support variance - the actual Bloc instance
+ * will have the correct specific types inferred at usage sites.
+ *
+ * @example
+ * ```ts
+ * function createBloc<TBloc extends StateContainer<any>>(
+ *   BlocClass: BlocConstructor<TBloc>
+ * ): TBloc {
+ *   return BlocClass.getOrCreate();
+ * }
+ * ```
+ */
+type BlocConstructor<TBloc extends StateContainer<any>> = (new (...args: any[]) => TBloc) & {
+  getOrCreate?(instanceKey?: string, ...args: any[]): TBloc;
+  release?(instanceKey?: string): void;
+  isolated?: boolean;
+  keepAlive?: boolean;
+};
+//#endregion
+//#region src/types.d.ts
+/**
+ * Configuration options for the useBloc hook
+ *
+ * @template TBloc - The StateContainer type
+ *
+ * @example
+ * ```tsx
+ * const [state, bloc] = useBloc(CounterBloc, {
+ *   staticProps: { initialCount: 0 },
+ *   dependencies: (state) => [state.count],
+ *   onMount: (bloc) => console.log('Mounted'),
+ * });
+ * ```
+ */
+interface UseBlocOptions<TBloc extends StateContainer<AnyObject>> {
+  /**
+   * Static props to pass to the Bloc constructor
+   * Type should match the constructor's first parameter
+   */
+  staticProps?: AnyObject;
+  /**
+   * Custom instance ID for shared blocs
+   * - For isolated blocs, each useBloc call gets its own instance
+   * - For shared blocs, the same instanceId will share the same bloc instance
+   */
+  instanceId?: string;
+  /**
+   * Manual dependency tracking function
+   * - When provided, automatic proxy tracking is disabled
+   * - Component only re-renders when the returned values change (shallow equality)
+   *
+   * @param state - Current state of the bloc
+   * @param bloc - The bloc instance
+   * @returns Array of values to track
+   */
+  dependencies?: (state: ExtractState<TBloc>, bloc: TBloc) => unknown[];
+  /**
+   * Control automatic dependency tracking (default: true)
+   * - true: Automatically track accessed properties via Proxy
+   * - false: Disable tracking, all state changes trigger re-render
+   * - Ignored when `dependencies` option is provided
+   *
+   * @default true
+   */
+  autoTrack?: boolean;
+  /**
+   * Callback invoked when the component mounts
+   *
+   * @param bloc - The bloc instance
+   */
+  onMount?: (bloc: TBloc) => void;
+  /**
+   * Callback invoked when the component unmounts
+   *
+   * @param bloc - The bloc instance
+   */
+  onUnmount?: (bloc: TBloc) => void;
+}
+/**
+ * Return type of the useBloc hook
+ *
+ * @template TBloc - The StateContainer type
+ *
+ * @returns A tuple containing:
+ * - [0]: The current state (may be a Proxy for tracking)
+ * - [1]: The bloc instance with methods
+ * - [2]: Component ref (internal use only)
+ */
+type UseBlocReturn<TBloc extends StateContainer<AnyObject>> = [ExtractState<TBloc>, TBloc, RefObject<ComponentRef>];
+/**
+ * @internal
+ * Component reference object for internal tracking
+ * Used to persist instance IDs across React Strict Mode remounts
+ */
+type ComponentRef = {
+  __blocInstanceId?: string;
+  __bridge?: any;
+};
+//#endregion
+//#region src/useBloc.d.ts
+/**
+ * Lifecycle: INITIAL MOUNT
+ * 1. useMemo runs once - creates bloc, subscribeFn, getSnapshotFn
+ * 2. useSyncExternalStore calls getSnapshotFn (1st time) - lazy creates tracker, starts tracking, returns proxy
+ * 3. Component renders - proxy tracks property accesses
+ * 4. useSyncExternalStore calls getSnapshotFn (2nd time) - captures tracked paths, starts new tracking, returns proxy
+ * 5. useSyncExternalStore calls subscribeFn - sets up state change listener
+ *
+ * Lifecycle: STATE CHANGE
+ * 1. Bloc state changes
+ * 2. subscribeFn callback checks hasChanges() - only re-renders if tracked paths changed
+ * 3. If re-render: getSnapshotFn captures previous paths, starts tracking, returns proxy
+ *
+ * Lifecycle: RE-RENDER (parent re-render)
+ * 1. useMemo returns cached values (same bloc, subscribeFn, getSnapshotFn)
+ * 2. useSyncExternalStore calls getSnapshotFn - captures paths, starts tracking, returns proxy
+ */
+declare function useBloc<TBloc extends StateContainer<AnyObject>>(BlocClass: BlocConstructor<TBloc>, options?: UseBlocOptions<TBloc>): UseBlocReturn<TBloc>;
+//#endregion
+//#region src/useBlocActions.d.ts
+/**
+ * Configuration options for the useBlocActions hook
+ *
+ * @template TBloc - The StateContainer type
+ */
+interface UseBlocActionsOptions<TBloc extends StateContainer<AnyObject>> {
+  /**
+   * Static props to pass to the Bloc constructor
+   * Type should match the constructor's first parameter
+   */
+  staticProps?: AnyObject;
+  /**
+   * Custom instance ID for shared blocs
+   * - For isolated blocs, each useBlocActions call gets its own instance
+   * - For shared blocs, the same instanceId will share the same bloc instance
+   */
+  instanceId?: string;
+  /**
+   * Callback invoked when the component mounts
+   *
+   * @param bloc - The bloc instance
+   */
+  onMount?: (bloc: TBloc) => void;
+  /**
+   * Callback invoked when the component unmounts
+   *
+   * @param bloc - The bloc instance
+   */
+  onUnmount?: (bloc: TBloc) => void;
+}
+/**
+ * React hook for accessing bloc instance without state subscription.
+ * Use this when you only need to call bloc methods/actions without reading state.
+ *
+ * Benefits over useBloc:
+ * - No state subscription overhead
+ * - No proxy tracking
+ * - Component never re-renders due to bloc state changes
+ * - Lighter weight for action-only components
+ *
+ * @template TBloc - The StateContainer type
+ * @param BlocClass - The bloc class constructor
+ * @param options - Optional configuration
+ * @returns The bloc instance
+ */
+declare function useBlocActions<TBloc extends StateContainer<AnyObject>>(BlocClass: BlocConstructor<TBloc>, options?: UseBlocActionsOptions<TBloc>): TBloc;
+//#endregion
+export { type UseBlocActionsOptions, type UseBlocOptions, type UseBlocReturn, useBloc, useBlocActions };
+//# sourceMappingURL=index.d.cts.map