@blac/react 2.0.0-rc.5 → 2.0.0-rc.8

package/dist/index.d.ts

@@ -1,453 +1,12 @@
-import { RefObject } from "react";
-
-//#region ../blac/src/types/events.d.ts
-
 /**
- * Base event interface for type-safe event system
- */
-/**
- * Base event interface
- * Used by Vertex for event-driven state management
- */
-interface BaseEvent {
-  readonly type: string;
-  readonly timestamp: number;
-  readonly source?: string;
-}
-//#endregion
-//#region ../blac/src/core/Vertex.d.ts
-
-/**
- * Event handler signature (synchronous only)
- */
-type EventHandler<E$1 extends BaseEvent, S$1> = (event: E$1, emit: (state: S$1) => void) => void;
-/**
- * Type-safe event constructor
- */
-type EventConstructor<T$1 extends BaseEvent = BaseEvent> = new (...args: never[]) => T$1;
-/**
- * Vertex is an event-driven state container (Bloc pattern)
- *
- * Includes its own simple event system since events are only needed
- * for the Vertex pattern, not for the base StateContainer.
- */
-declare abstract class Vertex<S$1, E$1 extends BaseEvent = BaseEvent> extends StateContainer<S$1> {
-  private eventHandlers;
-  private isProcessing;
-  private eventQueue;
-  /**
-   * Create a new Vertex
-   * @param initialState Initial state value
-   * @param config Configuration options
-   */
-  constructor(initialState: S$1, config?: StateContainerConfig);
-  /**
-   * Register an event handler
-   * Arrow function to maintain correct 'this' binding
-   */
-  protected on: <T extends E$1>(EventClass: EventConstructor<T>, handler: EventHandler<T, S$1>) => void;
-  /**
-   * Add an event to be processed
-   * Arrow function to maintain correct 'this' binding in React
-   */
-  add: (event: E$1) => void;
-  /**
-   * Process an event (synchronously)
-   */
-  private processEvent;
-  /**
-   * Handle a single event (synchronously)
-   */
-  private handleEvent;
-  /**
-   * Hook for handling event processing errors
-   */
-  protected onEventError(event: E$1, error: Error): void;
-}
-//#endregion
-//#region ../blac/src/core/StateContainerRegistry.d.ts
-/**
- * Lifecycle events that can be observed
- */
-type LifecycleEvent = 'created' | 'stateChanged' | 'eventAdded' | 'disposed';
-/**
- * Listener function types for each lifecycle event
- */
-type LifecycleListener<E$1 extends LifecycleEvent> = E$1 extends 'created' ? (container: StateContainer<any>) => void : E$1 extends 'stateChanged' ? (container: StateContainer<any>, previousState: any, currentState: any) => void : E$1 extends 'eventAdded' ? (container: Vertex<any, any>, event: any) => void : E$1 extends 'disposed' ? (container: StateContainer<any>) => void : never;
-/**
- * Registry for managing StateContainer instances
- */
-declare class StateContainerRegistry {
-  private readonly instances;
-  private readonly types;
-  private readonly listeners;
-  /**
-   * 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;
-  /**
-   * Subscribe to lifecycle events
-   * @param event - The lifecycle event to listen for
-   * @param listener - The listener function to call when the event occurs
-   * @returns Unsubscribe function
-   */
-  on<E extends LifecycleEvent>(event: E, listener: LifecycleListener<E>): () => void;
-  /**
-   * Emit lifecycle event to all listeners
-   * @internal - Called by StateContainer/Vertex lifecycle methods
-   */
-  emit(event: LifecycleEvent, ...args: any[]): void;
-}
-//#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> {
-  protected static _registry: StateContainerRegistry;
-  /**
-   * 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
+ * React Integration
  *
- * @template TBloc - The StateContainer type
- * @param BlocClass - The bloc class constructor
- * @param options - Optional configuration
- * @returns The bloc instance
+ * Clean integration between React and StateContainer architecture.
+ * Constructor-based API with automatic type inference.
+ * Supports concurrent (useSyncExternalStore) mode for optimal performance.
  */
-declare function useBlocActions<TBloc extends StateContainer<AnyObject>>(BlocClass: BlocConstructor<TBloc>, options?: UseBlocActionsOptions<TBloc>): TBloc;
-//#endregion
-export { type UseBlocActionsOptions, type UseBlocOptions, type UseBlocReturn, useBloc, useBlocActions };
+export { useBloc } from './useBloc';
+export { useBlocActions } from './useBlocActions';
+export type { UseBlocOptions, UseBlocReturn } from './types';
+export type { UseBlocActionsOptions } from './useBlocActions';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC"}