@veams/status-quo 1.7.0 → 1.8.1

package/dist/react/hooks/state-factory.js

@@ -1,13 +1,35 @@
+/**
+ * Utility hook for creating and subscribing to a state handler within a component.
+ * Combines creation and subscription logic in a single call.
+ */
 import { useStateHandler } from './state-handler.js';
 import { useStateSubscription } from './state-subscription.js';
+/**
+ * Default identity selector returns the whole state.
+ */
 const identitySelector = (state) => state;
-export function useStateFactory(stateFactoryFunction, selectorOrParams = [], isEqualOrParams = Object.is, params = []) {
+export function useStateFactory(
+// Implementation of the overloaded useStateFactory hook.
+stateFactoryFunction, 
+// Mixed argument: can be a selector or params array.
+selectorOrParams = [], 
+// Mixed argument: can be an equality function or params array.
+isEqualOrParams = Object.is, 
+// Optional params array.
+params = []) {
+    // Determine whether a selector was provided.
     const hasSelector = typeof selectorOrParams === 'function';
+    // Fallback to identity selector if none is provided.
     const selector = (hasSelector ? selectorOrParams : identitySelector);
+    // Determine whether a custom equality function was provided.
     const hasCustomEquality = hasSelector && typeof isEqualOrParams === 'function';
+    // Fallback to default equality check (Object.is).
     const isEqual = (hasCustomEquality ? isEqualOrParams : Object.is);
+    // Resolve the parameters for the state handler factory.
     const stateFactoryParams = (hasSelector ? (hasCustomEquality ? params : isEqualOrParams) : selectorOrParams);
+    // Create and persist the state handler instance using its factory and parameters.
     const stateHandler = useStateHandler(stateFactoryFunction, stateFactoryParams);
+    // Subscribe to the state handler and return the selected state and actions.
     return useStateSubscription(stateHandler, selector, isEqual);
 }
 //# sourceMappingURL=state-factory.js.map

package/dist/react/hooks/state-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-factory.js","sourceRoot":"","sources":["../../../src/react/hooks/state-factory.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAO/D,MAAM,gBAAgB,GAAG,CAAS,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC;AAiBzD,MAAM,UAAU,eAAe,CAC7B,oBAAoE,EACpE,mBAA8C,EAAkB,EAChE,kBAAuC,MAAM,CAAC,EAAqB,EACnE,SAAY,EAAkB;IAE9B,MAAM,WAAW,GAAG,OAAO,gBAAgB,KAAK,UAAU,CAAC;IAC3D,MAAM,QAAQ,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAA0B,CAAC;IAC9F,MAAM,iBAAiB,GAAG,WAAW,IAAI,OAAO,eAAe,KAAK,UAAU,CAAC;IAC/E,MAAM,OAAO,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClE,MAAM,kBAAkB,GAAG,CACzB,WAAW,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAC3E,CAAC;IACP,MAAM,YAAY,GAAG,eAAe,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;IAE/E,OAAO,oBAAoB,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"state-factory.js","sourceRoot":"","sources":["../../../src/react/hooks/state-factory.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAU/D;;GAEG;AACH,MAAM,gBAAgB,GAAG,CAAS,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC;AA8BzD,MAAM,UAAU,eAAe;AAC7B,yDAAyD;AACzD,oBAAoE;AACpE,qDAAqD;AACrD,mBAA8C,EAAkB;AAChE,+DAA+D;AAC/D,kBAAuC,MAAM,CAAC,EAAqB;AACnE,yBAAyB;AACzB,SAAY,EAAkB;IAE9B,6CAA6C;IAC7C,MAAM,WAAW,GAAG,OAAO,gBAAgB,KAAK,UAAU,CAAC;IAC3D,qDAAqD;IACrD,MAAM,QAAQ,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAA0B,CAAC;IAC9F,6DAA6D;IAC7D,MAAM,iBAAiB,GAAG,WAAW,IAAI,OAAO,eAAe,KAAK,UAAU,CAAC;IAC/E,kDAAkD;IAClD,MAAM,OAAO,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClE,wDAAwD;IACxD,MAAM,kBAAkB,GAAG,CACzB,WAAW,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAC3E,CAAC;IACP,kFAAkF;IAClF,MAAM,YAAY,GAAG,eAAe,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;IAE/E,4EAA4E;IAC5E,OAAO,oBAAoB,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}

package/dist/react/hooks/state-handler.d.ts

@@ -1,2 +1,6 @@
 import type { StateSubscriptionHandler } from '../../types/types.js';
+/**
+ * Returns a stable state handler instance based on a factory function.
+ * Uses a ref to ensure the factory function is only executed during initial render.
+ */
 export declare function useStateHandler<V, A, P extends unknown[]>(stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>, params?: P): StateSubscriptionHandler<V, A>;

package/dist/react/hooks/state-handler.js

@@ -1,9 +1,26 @@
+/**
+ * Utility hook for managing the lifecycle of a state handler instance.
+ * Ensures the instance is created once and persisted across component re-renders.
+ */
 import { useRef } from 'react';
-export function useStateHandler(stateFactoryFunction, params = []) {
+/**
+ * Returns a stable state handler instance based on a factory function.
+ * Uses a ref to ensure the factory function is only executed during initial render.
+ */
+export function useStateHandler(
+// Function to create a new state handler instance.
+stateFactoryFunction, 
+// Parameters to pass to the factory function.
+params = []) {
+    // Use a ref to store the state handler instance.
+    // This prevents the state handler from being recreated on every re-render.
     const stateHandlerRef = useRef(null);
+    // If the ref is currently null, we create the instance for the first time.
     if (!stateHandlerRef.current) {
+        // Invoke the factory function with the provided parameters.
         stateHandlerRef.current = stateFactoryFunction(...params);
     }
+    // Return the stable state handler instance.
     return stateHandlerRef.current;
 }
 //# sourceMappingURL=state-handler.js.map

package/dist/react/hooks/state-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-handler.js","sourceRoot":"","sources":["../../../src/react/hooks/state-handler.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAI/B,MAAM,UAAU,eAAe,CAC7B,oBAAoE,EACpE,SAAY,EAAkB;IAE9B,MAAM,eAAe,GAAG,MAAM,CAAwC,IAAI,CAAC,CAAC;IAE5E,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;QAC7B,eAAe,CAAC,OAAO,GAAG,oBAAoB,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,eAAe,CAAC,OAAO,CAAC;AACjC,CAAC"}
+{"version":3,"file":"state-handler.js","sourceRoot":"","sources":["../../../src/react/hooks/state-handler.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAI/B;;;GAGG;AACH,MAAM,UAAU,eAAe;AAC7B,mDAAmD;AACnD,oBAAoE;AACpE,8CAA8C;AAC9C,SAAY,EAAkB;IAE9B,iDAAiD;IACjD,2EAA2E;IAC3E,MAAM,eAAe,GAAG,MAAM,CAAwC,IAAI,CAAC,CAAC;IAE5E,2EAA2E;IAC3E,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;QAC7B,4DAA4D;QAC5D,eAAe,CAAC,OAAO,GAAG,oBAAoB,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5D,CAAC;IAED,4CAA4C;IAC5C,OAAO,eAAe,CAAC,OAAO,CAAC;AACjC,CAAC"}

package/dist/react/hooks/state-provider.d.ts

@@ -1,14 +1,23 @@
+/**
+ * Utility hook for providing a state handler through React Context.
+ * Allows components deep in the component tree to access a common state handler instance.
+ */
 import React from 'react';
-import type { PropsWithChildren } from 'react';
 import type { StateSubscriptionHandler } from '../../types/types.js';
-type StateSelector<State, SelectedState> = (state: State) => SelectedState;
-type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
-export type StateProviderProps<V, A> = PropsWithChildren<{
+/**
+ * Interface for the state provider component props.
+ */
+interface StateProviderProps<V, A> {
+    children: React.ReactNode;
     instance: StateSubscriptionHandler<V, A>;
-}>;
-export declare function useProvidedStateHandler<V, A>(): StateSubscriptionHandler<V, A>;
+}
+/**
+ * Provides a state handler instance to its descendant components using React Context.
+ */
 export declare function StateProvider<V, A>({ children, instance }: StateProviderProps<V, A>): React.JSX.Element;
-export declare function useProvidedStateActions<V, A>(): A;
-export declare function useProvidedStateSubscription<V, A>(): [V, A];
-export declare function useProvidedStateSubscription<V, A, Sel>(selector: StateSelector<V, Sel>, isEqual?: EqualityFn<Sel>): [Sel, A];
+/**
+ * Custom hook to access the state handler provided by the StateProvider.
+ * Throws an error if the hook is used outside of a StateProvider.
+ */
+export declare function useProvidedStateHandler<V, A>(): StateSubscriptionHandler<V, A>;
 export {};

package/dist/react/hooks/state-provider.js

@@ -1,24 +1,32 @@
+/**
+ * Utility hook for providing a state handler through React Context.
+ * Allows components deep in the component tree to access a common state handler instance.
+ */
 import React, { createContext, useContext } from 'react';
-import { useStateActions } from './state-actions.js';
-import { useStateSubscription } from './state-subscription.js';
-const StateProviderContext = createContext(null);
-const identitySelector = (state) => state;
+/**
+ * Creates a React Context for storing and providing the state handler instance.
+ * Initialized with null as there is no default state handler.
+ */
+const StateContext = createContext(null);
+/**
+ * Provides a state handler instance to its descendant components using React Context.
+ */
+export function StateProvider({ children, instance }) {
+    // Use a context provider to share the state handler instance.
+    return (React.createElement(StateContext.Provider, { value: instance }, children));
+}
+/**
+ * Custom hook to access the state handler provided by the StateProvider.
+ * Throws an error if the hook is used outside of a StateProvider.
+ */
 export function useProvidedStateHandler() {
-    const stateHandler = useContext(StateProviderContext);
+    // Retrieve the state handler from the nearest context provider.
+    const stateHandler = useContext(StateContext);
+    // If no state handler is found, it means the hook is being used incorrectly.
     if (!stateHandler) {
-        throw new Error('No StateProvider instance found in the current React tree.');
+        throw new Error('useProvidedStateHandler must be used within a StateProvider');
     }
+    // Cast and return the state handler instance.
     return stateHandler;
 }
-export function StateProvider({ children, instance }) {
-    return (React.createElement(StateProviderContext.Provider, { value: instance }, children));
-}
-export function useProvidedStateActions() {
-    const stateHandler = useProvidedStateHandler();
-    return useStateActions(stateHandler);
-}
-export function useProvidedStateSubscription(selector = identitySelector, isEqual = Object.is) {
-    const stateHandler = useProvidedStateHandler();
-    return useStateSubscription(stateHandler, selector, isEqual);
-}
 //# sourceMappingURL=state-provider.js.map

package/dist/react/hooks/state-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-provider.js","sourceRoot":"","sources":["../../../src/react/hooks/state-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAS/D,MAAM,oBAAoB,GAAG,aAAa,CAA4B,IAAI,CAAC,CAAC;AAC5E,MAAM,gBAAgB,GAAG,CAAS,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC;AAMzD,MAAM,UAAU,uBAAuB;IACrC,MAAM,YAAY,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IAEtD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,YAA8C,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,aAAa,CAAO,EAAE,QAAQ,EAAE,QAAQ,EAA4B;IAClF,OAAO,CACL,oBAAC,oBAAoB,CAAC,QAAQ,IAAC,KAAK,EAAE,QAA8B,IACjE,QAAQ,CACqB,CACjC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,MAAM,YAAY,GAAG,uBAAuB,EAAQ,CAAC;IAErD,OAAO,eAAe,CAAC,YAAY,CAAC,CAAC;AACvC,CAAC;AAOD,MAAM,UAAU,4BAA4B,CAC1C,WAAkC,gBAAyC,EAC3E,UAA2B,MAAM,CAAC,EAAE;IAEpC,MAAM,YAAY,GAAG,uBAAuB,EAAQ,CAAC;IAErD,OAAO,oBAAoB,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"state-provider.js","sourceRoot":"","sources":["../../../src/react/hooks/state-provider.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAczD;;;GAGG;AACH,MAAM,YAAY,GAAG,aAAa,CAAoD,IAAI,CAAC,CAAC;AAE5F;;GAEG;AACH,MAAM,UAAU,aAAa,CAAO,EAAE,QAAQ,EAAE,QAAQ,EAA4B;IAClF,8DAA8D;IAC9D,OAAO,CACL,oBAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,QAAsD,IACjF,QAAQ,CACa,CACzB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,gEAAgE;IAChE,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IAE9C,6EAA6E;IAC7E,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IAED,8CAA8C;IAC9C,OAAO,YAA8C,CAAC;AACxD,CAAC"}

package/dist/react/hooks/state-singleton.d.ts

@@ -1,6 +1,12 @@
 import type { StateSingleton } from '../../store/state-singleton.js';
+/**
+ * Type signatures for selector and equality functions.
+ */
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
-export declare function useStateSingleton<V, A>(stateSingleton: StateSingleton<V, A>): [V, A];
-export declare function useStateSingleton<V, A, Sel>(stateSingleton: StateSingleton<V, A>, selector: StateSelector<V, Sel>, isEqual?: EqualityFn<Sel>): [Sel, A];
+/**
+ * Singleton hook to subscribe to a state singleton.
+ */
+export declare function useStateSingleton<V, A>(singleton: StateSingleton<V, A>): [V, A];
+export declare function useStateSingleton<V, A, Sel>(singleton: StateSingleton<V, A>, selector: StateSelector<V, Sel>, isEqual?: EqualityFn<Sel>): [Sel, A];
 export {};

package/dist/react/hooks/state-singleton.js

@@ -1,7 +1,25 @@
+/**
+ * Utility hook for subscribing to a state singleton within a component.
+ */
 import { useStateSubscription } from './state-subscription.js';
+/**
+ * Default identity selector returns the whole state.
+ */
 const identitySelector = (state) => state;
-export function useStateSingleton(stateSingleton, selector = identitySelector, isEqual = Object.is) {
-    const [state, actions] = useStateSubscription(stateSingleton, selector, isEqual);
-    return [state, actions];
+export function useStateSingleton(
+// Implementation of the overloaded useStateSingleton hook.
+singleton, 
+// Mixed argument: can be a selector or equality function.
+selectorOrIsEqual = identitySelector, 
+// Mixed argument: can be an equality function or undefined.
+isEqual = Object.is) {
+    // Determine whether a selector was provided as the first optional argument.
+    const hasSelector = typeof selectorOrIsEqual === 'function' && selectorOrIsEqual.length === 1;
+    // Fallback to identity selector if none is provided.
+    const selector = (hasSelector ? selectorOrIsEqual : identitySelector);
+    // Resolve the equality function to use.
+    const equalityFn = (hasSelector ? isEqual : selectorOrIsEqual);
+    // Subscribe to the singleton state handler and return the selected state and actions.
+    return useStateSubscription(singleton, selector, equalityFn);
 }
 //# sourceMappingURL=state-singleton.js.map

package/dist/react/hooks/state-singleton.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-singleton.js","sourceRoot":"","sources":["../../../src/react/hooks/state-singleton.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAO/D,MAAM,gBAAgB,GAAG,CAAS,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC;AAQzD,MAAM,UAAU,iBAAiB,CAC/B,cAAoC,EACpC,WAAkC,gBAAyC,EAC3E,UAA2B,MAAM,CAAC,EAAE;IAEpC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,oBAAoB,CAAC,cAAc,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEjF,OAAO,CAAC,KAAK,EAAE,OAAO,CAAa,CAAC;AACtC,CAAC"}
+{"version":3,"file":"state-singleton.js","sourceRoot":"","sources":["../../../src/react/hooks/state-singleton.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAU/D;;GAEG;AACH,MAAM,gBAAgB,GAAG,CAAS,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC;AAiBzD,MAAM,UAAU,iBAAiB;AAC/B,2DAA2D;AAC3D,SAA+B;AAC/B,0DAA0D;AAC1D,oBAA6D,gBAG5D;AACD,4DAA4D;AAC5D,UAA2B,MAAM,CAAC,EAAqB;IAEvD,4EAA4E;IAC5E,MAAM,WAAW,GAAG,OAAO,iBAAiB,KAAK,UAAU,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,CAAC;IAC9F,qDAAqD;IACrD,MAAM,QAAQ,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,gBAAgB,CAA0B,CAAC;IAC/F,wCAAwC;IACxC,MAAM,UAAU,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAoB,CAAC;IAElF,sFAAsF;IACtF,OAAO,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC/D,CAAC"}

package/dist/react/hooks/state-subscription-selector.d.ts

@@ -1,3 +1,7 @@
 import type { StateSubscriptionHandler } from '../../types/types.js';
 import type { EqualityFn, Selector } from '../../utils/selector-cache.js';
+/**
+ * Custom hook to select and subscribe to a specific piece of state from a handler.
+ * Efficiently manages subscriptions and selector results.
+ */
 export declare function useStateSubscriptionSelector<V, A, Sel>(stateSubscriptionHandler: StateSubscriptionHandler<V, A>, selector: Selector<V, Sel>, isEqual?: EqualityFn<Sel>, destroyOnCleanup?: boolean): Sel;

package/dist/react/hooks/state-subscription-selector.js

@@ -1,11 +1,23 @@
+/**
+ * Utility hook for subscribing to a state handler and selecting a specific value from the state.
+ * Uses useSyncExternalStore to ensure consistent state reads and avoid unnecessary re-renders.
+ */
 import { useCallback, useRef, useSyncExternalStore } from 'react';
 import { createSelectorCache, selectWithCache } from '../../utils/selector-cache.js';
+// Global map to track deferred destruction status for each state handler instance.
 const deferredDestroyMap = new WeakMap();
+/**
+ * Returns the deferred destruction status for a given state handler instance.
+ * Initializes the status if it does not already exist.
+ */
 function getDeferredDestroyState(stateSubscriptionHandler) {
+    // Retrieve the existing status from the map.
     const existingState = deferredDestroyMap.get(stateSubscriptionHandler);
+    // If status already exists, return it.
     if (existingState) {
         return existingState;
     }
+    // Create and store a new status for the handler.
     const nextState = {
         refCount: 0,
         timeoutId: null,
@@ -13,102 +25,146 @@ function getDeferredDestroyState(stateSubscriptionHandler) {
     deferredDestroyMap.set(stateSubscriptionHandler, nextState);
     return nextState;
 }
-export function useStateSubscriptionSelector(stateSubscriptionHandler, selector, isEqual = Object.is, destroyOnCleanup = true) {
+/**
+ * Custom hook to select and subscribe to a specific piece of state from a handler.
+ * Efficiently manages subscriptions and selector results.
+ */
+export function useStateSubscriptionSelector(
+// The state handler instance to subscribe to.
+stateSubscriptionHandler, 
+// Selector function to derive a value from the state.
+selector, 
+// Equality function to compare selected values for changes.
+isEqual = Object.is, 
+// Whether to automatically destroy the handler instance on component unmount.
+destroyOnCleanup = true) {
+    // Cache for the selector results to ensure referential stability.
     const selectorCacheRef = useRef(null);
-    // Tracks store notifications so getSnapshot can reuse the same selected value
-    // within one store version. This keeps useSyncExternalStore reads referentially stable.
+    // Tracks store notifications so getSnapshot can reuse the same selected value within one store version.
     const snapshotVersionRef = useRef(0);
     // Client-side cache for selected snapshots per source snapshot/version pair.
     const snapshotCacheRef = useRef(null);
     // Separate cache for the server snapshot function used by SSR/hydration paths.
     const serverSnapshotCacheRef = useRef(null);
+    // Initialize the selector cache if it doesn't already exist.
     if (!selectorCacheRef.current) {
         selectorCacheRef.current = createSelectorCache();
     }
     const selectorCache = selectorCacheRef.current;
+    // Subscription function to be used by useSyncExternalStore.
     const subscribe = useCallback((listener) => {
+        // Access the deferred destruction status for this handler.
         const sharedStateSubscriptionHandler = stateSubscriptionHandler;
         const deferredDestroyState = getDeferredDestroyState(sharedStateSubscriptionHandler);
+        // Increment the consumer reference count.
         deferredDestroyState.refCount += 1;
+        // If a pending destruction timeout is scheduled, cancel it.
         if (deferredDestroyState.timeoutId) {
             clearTimeout(deferredDestroyState.timeoutId);
             deferredDestroyState.timeoutId = null;
         }
+        // Subscribe to the state handler.
         const unsubscribe = stateSubscriptionHandler.subscribe(() => {
-            // Invalidate the selected snapshot cache before notifying React.
-            // Any next getSnapshot call should recompute from the new store state.
+            // Invalidate the selected snapshot cache before notifying React of a change.
             snapshotVersionRef.current += 1;
             snapshotCacheRef.current = null;
+            // Notify React to re-trigger a getSnapshot call.
             listener();
         });
+        // Return an unsubscribe function to be called by React.
         return () => {
+            // Execute the handler's unsubscribe method.
             unsubscribe();
+            // If automatic cleanup is disabled, stop here.
             if (!destroyOnCleanup) {
                 return;
             }
+            // Retrieve the current destruction status.
             const activeDeferredDestroyState = deferredDestroyMap.get(sharedStateSubscriptionHandler);
+            // If no status is found, stop here.
             if (!activeDeferredDestroyState) {
                 return;
             }
+            // Decrement the consumer reference count.
             activeDeferredDestroyState.refCount -= 1;
+            // If there are still active consumers, do not destroy the handler.
             if (activeDeferredDestroyState.refCount > 0) {
                 return;
             }
+            // Reset the reference count to zero.
             activeDeferredDestroyState.refCount = 0;
+            // Schedule deferred destruction to allow for potential immediate re-subscriptions.
             activeDeferredDestroyState.timeoutId = setTimeout(() => {
+                // Check if the handler still has no consumers after the timeout.
                 const pendingDeferredDestroyState = deferredDestroyMap.get(sharedStateSubscriptionHandler);
+                // If consumers have reappeared, do not destroy the handler.
                 if (!pendingDeferredDestroyState || pendingDeferredDestroyState.refCount > 0) {
                     return;
                 }
+                // Clear the pending timeout and destroy the state handler.
                 pendingDeferredDestroyState.timeoutId = null;
                 stateSubscriptionHandler.destroy();
+                // Remove the status from the global map.
                 deferredDestroyMap.delete(sharedStateSubscriptionHandler);
             }, 0);
         };
     }, [destroyOnCleanup, stateSubscriptionHandler]);
+    // Helper to execute selection using the cache.
     const selectSnapshot = useCallback((snapshot) => {
         return selectWithCache(selectorCache, snapshot, selector, isEqual).value;
     }, [isEqual, selector, selectorCache]);
+    // Reference to track changes in selection strategy.
     const selectorCacheControlRef = useRef(selectSnapshot);
+    // If the selector or equality function changes, clear all caches.
     if (selectorCacheControlRef.current !== selectSnapshot) {
-        // Selector/equality changes define a new selection strategy, so clear all caches.
         selectorCacheControlRef.current = selectSnapshot;
         snapshotVersionRef.current = 0;
         snapshotCacheRef.current = null;
         serverSnapshotCacheRef.current = null;
     }
+    // Snapshot retrieval function to be used by useSyncExternalStore.
     const getSnapshot = useCallback(() => {
+        // Retrieve the current source state from the handler.
         const sourceSnapshot = stateSubscriptionHandler.getSnapshot();
+        // Access the current version and cached value.
         const version = snapshotVersionRef.current;
         const cachedSnapshot = snapshotCacheRef.current;
+        // If the cached selection is still valid for this version and source state, return it.
         if (cachedSnapshot &&
             cachedSnapshot.version === version &&
             Object.is(cachedSnapshot.sourceSnapshot, sourceSnapshot)) {
-            // Same source snapshot in the same store version: return the exact same selected reference.
             return cachedSnapshot.selectedSnapshot;
         }
+        // Compute a new selection and update the cache.
         const selectedSnapshot = selectSnapshot(sourceSnapshot);
         snapshotCacheRef.current = {
             selectedSnapshot,
             sourceSnapshot,
             version,
         };
+        // Return the new selection.
         return selectedSnapshot;
     }, [selectSnapshot, stateSubscriptionHandler]);
+    // Server snapshot retrieval function to be used for SSR/hydration.
     const getServerSnapshot = useCallback(() => {
+        // Retrieve the initial source state from the handler.
         const sourceSnapshot = stateSubscriptionHandler.getInitialState();
+        // Access the current cached server snapshot.
         const cachedSnapshot = serverSnapshotCacheRef.current;
+        // If the cached server selection is still valid for the initial state, return it.
         if (cachedSnapshot && Object.is(cachedSnapshot.sourceSnapshot, sourceSnapshot)) {
-            // Keep server snapshot reads stable for hydration by reusing cached selection.
             return cachedSnapshot.selectedSnapshot;
         }
+        // Compute a new server selection and update its cache.
         const selectedSnapshot = selectSnapshot(sourceSnapshot);
         serverSnapshotCacheRef.current = {
             selectedSnapshot,
             sourceSnapshot,
         };
+        // Return the initial selection result.
         return selectedSnapshot;
     }, [selectSnapshot, stateSubscriptionHandler]);
+    // Use the useSyncExternalStore hook to integrate the state with React's rendering lifecycle.
     return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 //# sourceMappingURL=state-subscription-selector.js.map

package/dist/react/hooks/state-subscription-selector.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-subscription-selector.js","sourceRoot":"","sources":["../../../src/react/hooks/state-subscription-selector.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"state-subscription-selector.js","sourceRoot":"","sources":["../../../src/react/hooks/state-subscription-selector.tsx"],"names":[],"mappings":"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"}

package/dist/react/hooks/state-subscription.d.ts

@@ -1,9 +1,21 @@
 import type { StateSingleton } from '../../store/state-singleton.js';
 import type { StateSubscriptionHandler } from '../../types/types.js';
+/**
+ * Type signatures for selector and equality functions.
+ */
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
+/**
+ * Custom hook to subscribe to a state handler or singleton and receive its state and actions.
+ * Correctly manages shared instances and reference counting.
+ */
 export declare function useStateSubscription<V, A>(source: StateSubscriptionHandler<V, A>): [V, A];
 export declare function useStateSubscription<V, A, Sel>(source: StateSubscriptionHandler<V, A>, selector: StateSelector<V, Sel>, isEqual?: EqualityFn<Sel>): [Sel, A];
 export declare function useStateSubscription<V, A>(source: StateSingleton<V, A>): [V, A];
 export declare function useStateSubscription<V, A, Sel>(source: StateSingleton<V, A>, selector: StateSelector<V, Sel>, isEqual?: EqualityFn<Sel>): [Sel, A];
+/**
+ * Custom hook to subscribe to the state handler provided by the nearest StateProvider.
+ */
+export declare function useProvidedStateSubscription<V, A>(): [V, A];
+export declare function useProvidedStateSubscription<V, A, Sel>(selector: StateSelector<V, Sel>, isEqual?: EqualityFn<Sel>): [Sel, A];
 export {};

package/dist/react/hooks/state-subscription.js

@@ -1,53 +1,101 @@
+/**
+ * Utility hook for subscribing to a state handler or a state singleton.
+ * Manages the lifecycle and reference counting for shared state handler instances.
+ */
 import { useEffect, useMemo } from 'react';
 import { useStateActions } from './state-actions.js';
 import { useStateSubscriptionSelector } from './state-subscription-selector.js';
+import { useProvidedStateHandler } from './state-provider.js';
+/**
+ * Global map to track reference counts for singleton state handler instances.
+ * Used to determine when it's safe to destroy a shared singleton.
+ */
 const singletonReferences = new WeakMap();
+/**
+ * Default identity selector returns the whole state.
+ */
 const identitySelector = (state) => state;
+/**
+ * Type guard function to check if a source is a StateSingleton.
+ */
 function isStateSingleton(source) {
+    // Check for the presence of the getInstance method.
     return 'getInstance' in source;
 }
-export function useStateSubscription(source, selector = identitySelector, isEqual = Object.is) {
+export function useStateSubscription(
+// Implementation of the overloaded useStateSubscription hook.
+source, 
+// Selector function to derive a specific value from the state.
+selector = identitySelector, 
+// Optional equality function to compare selected values for changes.
+isEqual = Object.is) {
+    // Determine if the source is a singleton instance or a direct state handler.
     const singletonSource = isStateSingleton(source) ? source : null;
+    // Resolve the final state subscription handler instance to use.
     const stateSubscriptionHandler = useMemo(() => {
+        // If it's a singleton, access its managed instance.
         if (singletonSource) {
             return singletonSource.getInstance();
         }
+        // Otherwise, return the source handler instance directly.
         return source;
     }, [singletonSource, source]);
+    // Use an effect to manage the lifecycle and reference count of singleton instances.
     useEffect(() => {
+        // If the source is not a singleton, no lifecycle management is needed here.
         if (!singletonSource) {
             return undefined;
         }
+        // Cast the source to access management properties and retrieve the current reference.
         const singleton = singletonSource;
         const sharedStateHandler = stateSubscriptionHandler;
         const singletonReference = singletonReferences.get(singleton);
+        // Update the reference count for the singleton instance.
         if (!singletonReference || singletonReference.stateHandler !== sharedStateHandler) {
+            // Initialize the count if it doesn't already exist or has changed.
             singletonReferences.set(singleton, { count: 1, stateHandler: sharedStateHandler });
         }
         else {
+            // Increment the consumer count.
             singletonReference.count += 1;
         }
+        // Return an effect cleanup function to decrement the count when the component unmounts.
         return () => {
+            // Access the active reference for the singleton.
             const activeReference = singletonReferences.get(singleton);
+            // If no active reference is found, do nothing.
             if (!activeReference || activeReference.stateHandler !== sharedStateHandler) {
                 return;
             }
+            // Decrement the consumer count.
             activeReference.count -= 1;
+            // If there are still active consumers, do not destroy the instance.
             if (activeReference.count <= 0) {
+                // Remove the reference from the map when the count reaches zero.
                 singletonReferences.delete(singleton);
+                // Only proceed with destruction if destroyOnNoConsumers is explicitly enabled.
                 if (singleton.destroyOnNoConsumers !== true) {
                     return;
                 }
+                // Use the singleton's internal destroy method if available.
                 if (singleton.destroyInstance) {
                     singleton.destroyInstance();
                     return;
                 }
+                // Otherwise, invoke the handler's destroy method directly.
                 stateSubscriptionHandler.destroy();
             }
         };
     }, [singletonSource, stateSubscriptionHandler]);
+    // Select and subscribe to the state value using the useStateSubscriptionSelector hook.
     const state = useStateSubscriptionSelector(stateSubscriptionHandler, selector, isEqual, !singletonSource);
+    // Retrieve the set of actions from the state handler.
     const actions = useStateActions(stateSubscriptionHandler);
+    // Return the selected state and its actions as a tuple.
     return [state, actions];
 }
+export function useProvidedStateSubscription(selector = identitySelector, isEqual = Object.is) {
+    const stateHandler = useProvidedStateHandler();
+    return useStateSubscription(stateHandler, selector, isEqual);
+}
 //# sourceMappingURL=state-subscription.js.map

package/dist/react/hooks/state-subscription.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-subscription.js","sourceRoot":"","sources":["../../../src/react/hooks/state-subscription.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AAahF,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAGpC,CAAC;AAEJ,MAAM,gBAAgB,GAAG,CAAS,KAAY,EAAE,EAAE,CAAC,KAAK,CAAC;AAEzD,SAAS,gBAAgB,CACvB,MAA6D;IAE7D,OAAO,aAAa,IAAI,MAAM,CAAC;AACjC,CAAC;AAcD,MAAM,UAAU,oBAAoB,CAClC,MAA6D,EAC7D,WAAkC,gBAAyC,EAC3E,UAA2B,MAAM,CAAC,EAAE;IAEpC,MAAM,eAAe,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,MAAM,wBAAwB,GAAG,OAAO,CAAiC,GAAG,EAAE;QAC5E,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,eAAe,CAAC,WAAW,EAAE,CAAC;QACvC,CAAC;QAED,OAAO,MAAwC,CAAC;IAClD,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,SAAS,GAAG,eAAmC,CAAC;QACtD,MAAM,kBAAkB,GAAG,wBAA8C,CAAC;QAC1E,MAAM,kBAAkB,GAAG,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE9D,IAAI,CAAC,kBAAkB,IAAI,kBAAkB,CAAC,YAAY,KAAK,kBAAkB,EAAE,CAAC;YAClF,mBAAmB,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACrF,CAAC;aAAM,CAAC;YACN,kBAAkB,CAAC,KAAK,IAAI,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,GAAG,EAAE;YACV,MAAM,eAAe,GAAG,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAE3D,IAAI,CAAC,eAAe,IAAI,eAAe,CAAC,YAAY,KAAK,kBAAkB,EAAE,CAAC;gBAC5E,OAAO;YACT,CAAC;YAED,eAAe,CAAC,KAAK,IAAI,CAAC,CAAC;YAE3B,IAAI,eAAe,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC/B,mBAAmB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACtC,IAAI,SAAS,CAAC,oBAAoB,KAAK,IAAI,EAAE,CAAC;oBAC5C,OAAO;gBACT,CAAC;gBAED,IAAI,SAAS,CAAC,eAAe,EAAE,CAAC;oBAC9B,SAAS,CAAC,eAAe,EAAE,CAAC;oBAC5B,OAAO;gBACT,CAAC;gBAED,wBAAwB,CAAC,OAAO,EAAE,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAG,4BAA4B,CACxC,wBAAwB,EACxB,QAAQ,EACR,OAAO,EACP,CAAC,eAAe,CACjB,CAAC;IACF,MAAM,OAAO,GAAG,eAAe,CAAC,wBAAwB,CAAC,CAAC;IAE1D,OAAO,CAAC,KAAK,EAAE,OAAO,CAAa,CAAC;AACtC,CAAC"}
+{"version":3,"file":"state-subscription.js","sourceRoot":"","sources":["../../../src/react/hooks/state-subscription.tsx"],"names":[],"mappings":"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"}

package/dist/react/index.d.ts

@@ -1 +1,4 @@
-export * from './hooks/index.js';
+/**
+ * Export core React hooks and components for Status Quo.
+ */
+export { StateProvider, useProvidedStateActions, useProvidedStateHandler, useProvidedStateSubscription, useStateActions, useStateFactory, useStateHandler, useStateSingleton, useStateSubscription, } from './hooks/index.js';

package/dist/react/index.js

@@ -1,2 +1,6 @@
-export * from './hooks/index.js';
+/**
+ * Export core React hooks and components for Status Quo.
+ */
+// Export hooks and components to manage state and actions.
+export { StateProvider, useProvidedStateActions, useProvidedStateHandler, useProvidedStateSubscription, useStateActions, useStateFactory, useStateHandler, useStateSingleton, useStateSubscription, } from './hooks/index.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,2DAA2D;AAC3D,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,EAC5B,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/store/__tests__/native-state-handler.spec.d.ts

@@ -0,0 +1 @@
+export {};