@blac/react 2.0.0 → 2.0.1

package/src/externalBlocStore.ts

@@ -1,93 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { BlocBase, BlocConstructor, BlocHookDependencyArrayFn, BlocState } from '@blac/core';
-
-/**
- * Interface defining an external store that can be used to subscribe to and access bloc state.
- * This interface follows the React external store pattern for state management.
- * 
- * @template B - The type of the Bloc instance
- * @template S - The type of the Bloc state
- */
-export interface ExternalStore<
-  B extends InstanceType<BlocConstructor<any>>
-> {
-  /**
-   * Subscribes to changes in the store and returns an unsubscribe function.
-   * @param onStoreChange - Callback function that will be called whenever the store changes
-   * @returns A function that can be called to unsubscribe from store changes
-   */
-  subscribe: (onStoreChange: (state: BlocState<B>) => void) => () => void;
-
-  /**
-   * Gets the current snapshot of the store state.
-   * @returns The current state of the store
-   */
-  getSnapshot: () => BlocState<B>;
-
-  /**
-   * Gets the server snapshot of the store state.
-   * This is optional and defaults to the same value as getSnapshot.
-   * @returns The server state of the store
-   */
-  getServerSnapshot?: () => BlocState<B>;
-}
-
-/**
- * Creates an external store that wraps a Bloc instance, providing a React-compatible interface
- * for subscribing to and accessing bloc state.
- * 
- * @template B - The type of the Bloc instance
- * @template S - The type of the Bloc state
- * @param bloc - The Bloc instance to wrap
- * @param dependencyArray - Function that returns an array of dependencies for the subscription
- * @param rid - Unique identifier for the subscription
- * @returns An ExternalStore instance that provides methods to subscribe to and access bloc state
- */
-const externalBlocStore = <
-  B extends InstanceType<BlocConstructor<any>>
->(
-  resolvedBloc: B,
-  dependencyArray: BlocHookDependencyArrayFn<BlocState<B>>,
-  rid: string,
-): ExternalStore<B> => {
-  // TODO: Revisit this type assertion. Ideally, 'resolvedBloc' should conform to a type
-  // that guarantees '_observer' and 'state' properties without needing 'as unknown as ...'.
-  // This might require adjustments in the core @blac/core types.
-  const asBlocBase = resolvedBloc as unknown as BlocBase<BlocState<B>>;
-  return {
-    subscribe: (listener: (state: BlocState<B>) => void) => {
-      // Subscribe to the bloc's observer with the provided listener function
-      // This will trigger the callback whenever the bloc's state changes
-      const unSub = asBlocBase._observer.subscribe({
-        fn: () => {
-          try {
-            listener(asBlocBase.state);
-          } catch (e) {
-            // Log any errors that occur during the listener callback
-            // This ensures errors in listeners don't break the entire application
-            console.error({
-              e,
-              resolvedBloc,
-              dependencyArray,
-            });
-          }
-        },
-        // Pass the dependency array to control when the subscription is updated
-        dependencyArray,
-        // Use the provided id to identify this subscription
-        id: rid,
-      });
-
-      // Return an unsubscribe function that can be called to clean up the subscription
-      return () => {
-        unSub();
-      };
-    },
-    // Return an immutable snapshot of the current bloc state
-    getSnapshot: (): BlocState<B> => asBlocBase.state,
-    // Server snapshot mirrors the client snapshot in this implementation
-    getServerSnapshot: (): BlocState<B> => asBlocBase.state,
-  };
-};
-
-export default externalBlocStore;

package/src/index.ts

@@ -1,4 +0,0 @@
-import externalBlocStore from './externalBlocStore';
-import useBloc from './useBloc';
-
-export { externalBlocStore, useBloc };

package/src/useBloc.tsx

@@ -1,261 +0,0 @@
-/* eslint-disable @typescript-eslint/restrict-template-expressions */
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import {
-  Blac,
-  BlocBase,
-  BlocBaseAbstract,
-  BlocConstructor,
-  BlocHookDependencyArrayFn,
-  BlocState,
-  InferPropsFromGeneric,
-} from '@blac/core';
-import {
-  useEffect,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useSyncExternalStore,
-} from 'react';
-import externalBlocStore from './externalBlocStore';
-
-/**
- * Type definition for the return type of the useBloc hook
- * @template B - Bloc constructor type
- */
-type HookTypes<B extends BlocConstructor<BlocBase<any>>> = [
-  BlocState<InstanceType<B>>,
-  InstanceType<B>,
-];
-
-/**
- * Configuration options for the useBloc hook
- * @template B - Bloc generic type
- * @property {string} [id] - Optional identifier for the Bloc instance
- * @property {BlocHookDependencyArrayFn<B>} [dependencySelector] - Function to select dependencies for re-renders
- * @property {InferPropsFromGeneric<B>} [props] - Props to pass to the Bloc
- * @property {(bloc: B) => void} [onMount] - Callback function invoked when the Bloc is mounted
- */
-export interface BlocHookOptions<B extends BlocBase<any>> {
-  id?: string;
-  dependencySelector?: BlocHookDependencyArrayFn<BlocState<B>>;
-  props?: InferPropsFromGeneric<B>;
-  onMount?: (bloc: B) => void;
-}
-
-/**
- * Default dependency selector that wraps the entire state in an array
- * @template T - State type
- * @param {T} s - Current state
- * @returns {Array<Array<T>>} Dependency array containing the entire state
- */
-
-/**
- * React hook for integrating with Blac state management
- *
- * This hook connects a React component to a Bloc state container, providing
- * automatic re-rendering when relevant state changes, dependency tracking,
- * and proper lifecycle management.
- *
- * @template B - Bloc constructor type
- * @template O - BlocHookOptions type
- * @param {B} bloc - Bloc constructor class
- * @param {O} [options] - Configuration options for the hook
- * @returns {HookTypes<B>} Tuple containing [state, bloc instance]
- *
- * @example
- * const [state, counterBloc] = useBloc(CounterBloc);
- * // Access state
- * console.log(state.count);
- * // Call bloc methods
- * counterBloc.increment();
- */
-export default function useBloc<B extends BlocConstructor<BlocBase<any>>>(
-  bloc: B,
-  options?: BlocHookOptions<InstanceType<B>>,
-): HookTypes<B> {
-  const { dependencySelector, id: blocId, props } = options ?? {};
-  const rid = useMemo(() => {
-    return Math.random().toString(36);
-  }, []);
-
-  // Track used state keys
-  const usedKeys = useRef<Set<string>>(new Set());
-  const instanceKeys = useRef<Set<string>>(new Set());
-
-  // Track used class properties
-  const usedClassPropKeys = useRef<Set<string>>(new Set());
-  const instanceClassPropKeys = useRef<Set<string>>(new Set());
-
-  const renderInstance = {};
-
-  // Determine ID for isolated or shared blocs
-  const base = bloc as unknown as BlocBaseAbstract;
-  const isIsolated = base.isolated;
-  const effectiveBlocId = isIsolated ? rid : blocId;
-
-  // Use useRef to hold the bloc instance reference consistently across renders
-  const blocRef = useRef<InstanceType<B> | null>(null);
-
-  // Initialize or get the bloc instance ONCE using useMemo based on the effective ID
-  // This avoids re-running Blac.getBloc on every render.
-  useMemo(() => {
-    blocRef.current = Blac.getBloc(bloc, {
-      id: effectiveBlocId,
-      props,
-      instanceRef: rid, // Pass component ID for consumer tracking
-    });
-  }, [bloc, effectiveBlocId, rid]); // Dependencies ensure this runs only when bloc type or ID changes
-
-  const resolvedBloc = blocRef.current;
-
-  if (!resolvedBloc) {
-    // This should ideally not happen if Blac.getBloc works correctly
-    throw new Error(`useBloc: could not resolve bloc: ${bloc.name || bloc}`);
-  }
-
-  // Update props ONLY if this hook instance created the bloc (or is the designated main instance)
-  // We rely on Blac.getBloc to handle initial props correctly during creation.
-  // Subsequent calls should not overwrite props.
-  // Check if this instanceRef matches the one stored on the bloc when it was created/first retrieved.
-  if (
-    rid === resolvedBloc._instanceRef &&
-    options?.props &&
-    Blac.instance.findRegisteredBlocInstance(bloc, effectiveBlocId) ===
-      resolvedBloc
-  ) {
-    // Avoid double-setting props if Blac.getBloc already set them during creation
-    if (resolvedBloc.props !== options.props) {
-      resolvedBloc.props = options.props;
-    }
-  }
-
-  // Configure dependency tracking for re-renders
-  const dependencyArray: BlocHookDependencyArrayFn<BlocState<InstanceType<B>>> = (
-    newState,
-    oldState,
-  ): ReturnType<BlocHookDependencyArrayFn<BlocState<InstanceType<B>>>> => {
-    // Use custom dependency selector if provided
-    if (dependencySelector) {
-      return dependencySelector(newState, oldState);
-    }
-
-    // Fall back to bloc's default dependency selector if available
-    if (resolvedBloc.defaultDependencySelector) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-      return resolvedBloc.defaultDependencySelector(newState, oldState);
-    }
-
-    // For primitive states, use default selector
-    if (typeof newState !== 'object') {
-      // Default behavior for primitive states: re-render if the state itself changes.
-      return [[newState]];
-    }
-
-    // For object states, track which properties were actually used
-    const usedStateValues: string[] = [];
-    for (const key of usedKeys.current) {
-      if (key in newState) {
-        usedStateValues.push(newState[key as keyof typeof newState]);
-      }
-    }
-
-    // Track used class properties for dependency tracking, this enables rerenders when class getters change
-    const usedClassValues: unknown[] = [];
-    for (const key of usedClassPropKeys.current) {
-      if (key in resolvedBloc) {
-        try {
-          const value = resolvedBloc[key as keyof InstanceType<B>];
-          switch (typeof value) {
-            case 'function':
-              continue;
-            default:
-              usedClassValues.push(value);
-              continue;
-          }
-        } catch (error) {
-          Blac.instance.log('useBloc Error', error);
-        }
-      }
-    }
-
-    setTimeout(() => {
-      instanceKeys.current = new Set();
-      instanceClassPropKeys.current = new Set();
-    });
-    return [usedStateValues, usedClassValues];
-  };
-
-  // Set up external store subscription for state updates
-  const store = useMemo(
-    () => externalBlocStore(resolvedBloc, dependencyArray, rid),
-    [resolvedBloc, rid],
-  ); // dependencyArray removed as it changes frequently
-
-  // Subscribe to state changes using React's external store API
-  const state = useSyncExternalStore<BlocState<InstanceType<B>>>(
-    store.subscribe,
-    store.getSnapshot,
-    store.getServerSnapshot,
-  );
-
-  // Create a proxy for state to track property access
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-  const returnState: BlocState<InstanceType<B>> = useMemo(() => {
-    try {
-      if (typeof state === 'object') {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        return new Proxy(state as any, {
-          get(_, prop) {
-            instanceKeys.current.add(prop as string);
-            usedKeys.current.add(prop as string);
-            const value = state[prop as keyof typeof state];
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-            return value;
-          },
-        });
-      }
-    } catch (error) {
-      Blac.instance.log('useBloc Error', error);
-    }
-    return state;
-  }, [state]);
-
-  // Create a proxy for the bloc instance to track property access
-  const returnClass = useMemo(() => {
-    return new Proxy(resolvedBloc, {
-      get(_, prop) {
-        const value = resolvedBloc[prop as keyof InstanceType<B>];
-        // Track which class properties are accessed (excluding methods)
-        if (typeof value !== 'function') {
-          instanceClassPropKeys.current.add(prop as string);
-        }
-        return value;
-      },
-    });
-  }, [resolvedBloc]);
-
-  // Clean up tracked keys after each render
-  useLayoutEffect(() => {
-    // inherit the keys from the previous render
-    usedKeys.current = new Set(instanceKeys.current);
-    usedClassPropKeys.current = new Set(instanceClassPropKeys.current);
-  }, [renderInstance]);
-
-  // Set up bloc lifecycle management
-  useEffect(() => {
-    const currentBlocInstance = blocRef.current; // Capture instance for cleanup
-    if (!currentBlocInstance) return;
-
-    currentBlocInstance._addConsumer(rid);
-
-    // Call onMount callback if provided
-    options?.onMount?.(currentBlocInstance);
-
-    // Cleanup: remove this component as a consumer using the captured instance
-    return () => {
-      currentBlocInstance._removeConsumer(rid);
-    };
-  }, [bloc, rid]); // Do not add options.onMount to deps, it will cause a loop
-
-  return [returnState, returnClass];
-}