@blac/react 2.0.20 → 2.0.21

package/dist/index.js

@@ -1,5 +1,5 @@
-import { createContext, useContext, useEffect, useId, useLayoutEffect, useMemo, useReducer, useRef } from "react";
-import { DEP_BRAND, getRegistry, resolveInstanceKey } from "@blac/core";
+import { createContext, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { APPLY_DEPS, DEP_BRAND, REMOVE_DEPS_OWNER, WITH_TRACKED_STATE, getRegistry, resolveInstanceKey } from "@blac/core";
 import { ALL_PATHS, ProxyCache, emptyPathSet, pathSetEquals, trackRender, untracked } from "@dirtytalk/structural";
 import { jsx } from "react/jsx-runtime";
 //#region src/BlocProvider.tsx
@@ -29,6 +29,7 @@ const ProvidedArgsContext = createContext(/* @__PURE__ */ new Map());
 *   <CartWidget />
 * </BlocProvider>
 * ```
+* @public
 */
 function BlocProvider({ bloc, args, children }) {
 	const parentMap = useContext(ProvidedArgsContext);
@@ -39,7 +40,7 @@ function BlocProvider({ bloc, args, children }) {
 	}, [
 		parentMap,
 		bloc,
-		args
+		resolveInstanceKey(bloc, args)
 	]);
 	return /* @__PURE__ */ jsx(ProvidedArgsContext.Provider, {
 		value: mergedMap,
@@ -51,36 +52,60 @@ function BlocProvider({ bloc, args, children }) {
 * bloc class, or `undefined` when called outside a matching provider.
 *
 * Used by `useBloc` to inherit provider args when no own `args` are given.
+* @public
 */
 function useProvidedArgs(BlocClass) {
 	return useContext(ProvidedArgsContext).get(BlocClass);
 }
 //#endregion
+//#region src/RegistryProvider.tsx
+/**
+* Internal context value: a registry to use in place of the module-global
+* default (`getRegistry()`), or `null` when no provider is present.
+*/
+const RegistryContext = createContext(null);
+/**
+* Scopes descendant `useBloc` calls to a specific registry instead of the
+* module-global default.
+*
+* Useful for test isolation, SSR isolation, and micro-frontends that must
+* not share bloc instances with the host page.
+*
+* @example
+* ```tsx
+* <RegistryProvider registry={new StateContainerRegistry()}>
+*   <App />
+* </RegistryProvider>
+* ```
+* @public
+*/
+function RegistryProvider({ registry, children }) {
+	return /* @__PURE__ */ jsx(RegistryContext.Provider, {
+		value: registry,
+		children
+	});
+}
+//#endregion
 //#region src/buildTrackedProxy.ts
+function supportsTrackedState(value) {
+	return typeof value[WITH_TRACKED_STATE] === "function";
+}
 /**
-* Build a per-consumer proxy pair for a bloc instance.
+* Build a per-consumer proxy for a bloc instance.
 *
-* Returns two proxies:
-* - `proxy` — the stable outer proxy returned to the consumer. Getter
-*   properties are invoked with `thisProxy` as `this` so that `this.state`
-*   reads inside getters are redirected to the current render's tracking
-*   proxy. Non-getter properties fall through to the live instance.
-* - `thisProxy` — the inner `this`-proxy used as the receiver for getter
-*   calls. Intercepts `state` to return `trackedStateRef.current` when a
-*   tracking context is active; otherwise falls through to the live value.
-*   When `onDepHandle` is supplied, a read off `this` whose value carries the
-*   `DEP_BRAND` symbol (i.e. a `depend()` handle) is routed through
-*   `onDepHandle`, which returns a per-consumer wrapper whose `.track()` opts
-*   the consumer into cross-bloc reactivity. Core stays decoupled — detection
-*   is purely by the `DEP_BRAND` symbol.
+* Getters run with `this` bound to the **real instance**, not a proxy, so ES
+* `#private` fields and methods work in user blocs. Path recording is done by
+* `[WITH_TRACKED_STATE]`, which makes the instance's own `state` getter report
+* the render's tracking proxy for the duration of the call; nested getter
+* chains stay tracked because the override is still set.
 *
-* Both allocations happen exactly once per bloc acquisition (inside `useMemo`)
-* so the proxies are stable across renders.
+* One allocation per bloc acquisition (inside `useMemo`), so the proxy is
+* stable across renders.
 *
-* @param onDepHandle - Optional callback invoked when a getter reads a branded
-*   dep handle off `this`. Receives the original handle and returns the value
-*   to expose in its place (the session-bound wrapper). The callback is
-*   responsible for caching wrappers per handle to avoid re-allocation.
+* @param onDepHandle - Optional callback invoked when a read returns a branded
+*   dep handle. Receives the original handle and returns the value to expose in
+*   its place (the session-bound wrapper). The callback is responsible for
+*   caching wrappers per handle to avoid re-allocation.
 */
 function buildTrackedProxy(instance, trackedStateRef, onDepHandle) {
 	const getterDescs = /* @__PURE__ */ new Map();
@@ -93,20 +118,29 @@ function buildTrackedProxy(instance, trackedStateRef, onDepHandle) {
 		}
 		proto = Object.getPrototypeOf(proto);
 	}
-	const thisProxy = new Proxy(instance, { get(t, k, r) {
-		if (k === "state") return trackedStateRef.current ?? Reflect.get(t, k, r);
-		const value = Reflect.get(t, k, r);
+	const boundMethods = /* @__PURE__ */ new Map();
+	const wrapDepHandle = (value) => {
 		if (onDepHandle !== void 0 && (typeof value === "function" || typeof value === "object") && value !== null && value[DEP_BRAND] !== void 0) return onDepHandle(value);
 		return value;
-	} });
-	return {
-		proxy: new Proxy(instance, { get(target, key, receiver) {
-			const desc = getterDescs.get(key);
-			if (desc?.get) return desc.get.call(thisProxy);
-			return Reflect.get(target, key, receiver);
-		} }),
-		thisProxy
 	};
+	return { proxy: new Proxy(instance, { get(target, key) {
+		const getter = getterDescs.get(key)?.get;
+		if (getter) {
+			const tracked = trackedStateRef.current;
+			const read = () => getter.call(target);
+			return wrapDepHandle(tracked == null || !supportsTrackedState(target) ? read() : target[WITH_TRACKED_STATE](tracked, read, onDepHandle));
+		}
+		const value = Reflect.get(target, key, target);
+		if (typeof value === "function") {
+			let bound = boundMethods.get(key);
+			if (bound === void 0) {
+				bound = value.bind(target);
+				boundMethods.set(key, bound);
+			}
+			return wrapDepHandle(bound);
+		}
+		return wrapDepHandle(value);
+	} }) };
 }
 //#endregion
 //#region src/useBloc.ts
@@ -122,7 +156,7 @@ const depRefId = (consumerId) => `useBloc@${consumerId}:dep`;
 * - **Auto-tracking** (default): the returned state value is a proxy that
 *   records read paths during render. The component re-renders when any
 *   recorded path changes. Backed by `@dirtytalk/structural`'s
-*   {@link trackRender} + the container's path-scoped `DirtyChannel`.
+*   `trackRender` + the container's path-scoped `DirtyChannel`.
 * - **Manual select**: pass `options.select` to opt out of auto-tracking.
 *   The hook re-renders only when the returned array's elements change
 *   (per-index `Object.is`).
@@ -142,7 +176,7 @@ const depRefId = (consumerId) => `useBloc@${consumerId}:dep`;
 * const [state, bloc] = useBloc(MyBloc, { args: { _id: id } });
 * ```
 *
-* @template T - The state container constructor type (inferred from BlocClass)
+* @typeParam T - The state container constructor type (inferred from BlocClass)
 * @param BlocClass - The state container class to connect to
 * @param options - Configuration options
 * @returns Tuple of `[state, bloc, ref]`
@@ -163,13 +197,13 @@ const depRefId = (consumerId) => `useBloc@${consumerId}:dep`;
 * ```ts
 * const [state, bloc] = useBloc(UserBloc, { args: { userId: 'alice' } });
 * ```
+* @public
 */
 function useBloc(BlocClass, options) {
-	const componentRef = useRef({});
+	const registry = useContext(RegistryContext) ?? getRegistry();
 	const consumerIdRef = useRef(null);
 	if (consumerIdRef.current === null) consumerIdRef.current = `useBloc-${nextConsumerId++}`;
 	const consumerId = consumerIdRef.current;
-	useId();
 	const selectRef = useRef(options?.select);
 	selectRef.current = options?.select;
 	const onMountRef = useRef(options?.onMount);
@@ -200,27 +234,30 @@ function useBloc(BlocClass, options) {
 		key: providerArgs === void 0 ? void 0 : JSON.stringify(providerArgs)
 	};
 	const providerArgsKey = providerArgsKeyRef.current.key;
+	const resolveEffectiveArgs = () => ownArgsRef.current !== void 0 ? ownArgsRef.current : providerArgsRef.current;
 	const trackedStateRef = useRef(null);
-	const sessionRef = useRef(/* @__PURE__ */ new Map());
-	const depSubsRef = useRef(/* @__PURE__ */ new Map());
-	const depWrapperCacheRef = useRef(/* @__PURE__ */ new Map());
 	const proxyCacheRef = useRef(new ProxyCache());
-	const lastReconcileRef = useRef(null);
-	const [rebindNonce, bumpRebind] = useReducer((x) => x + 1, 0);
+	const depWrapperCacheRef = useRef(/* @__PURE__ */ new Map());
+	const rebindNonceRef = useRef(0);
+	const rebindNonce = rebindNonceRef.current;
+	const consumerRef = useRef(null);
+	consumerRef.current ??= createConsumer();
+	const consumer = consumerRef.current;
 	const ownedBlocRef = useRef(null);
 	const { bloc, instanceKey, trackedBloc } = useMemo(() => {
-		const effectiveArgs = ownArgsRef.current !== void 0 ? ownArgsRef.current : providerArgsRef.current;
+		const effectiveArgs = resolveEffectiveArgs();
 		const resolvedKey = resolveInstanceKey(BlocClass, effectiveArgs);
-		const instance = getRegistry().acquire(BlocClass, resolvedKey, {
+		const instance = registry.acquire(BlocClass, resolvedKey, {
 			canCreate: true,
 			countRef: false,
-			args: effectiveArgs
+			args: effectiveArgs,
+			sweepIfUnowned: true
 		});
 		const onDepHandle = (handle) => {
 			const cache = depWrapperCacheRef.current;
 			const cached = cache.get(handle);
 			if (cached !== void 0) return cached;
-			const wrapper = makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, onDepHandle);
+			const wrapper = makeDepWrapper(handle, consumerId, registry, trackedStateRef, consumer, onDepHandle);
 			cache.set(handle, wrapper);
 			return wrapper;
 		};
@@ -234,58 +271,50 @@ function useBloc(BlocClass, options) {
 		BlocClass,
 		ownArgsKey,
 		providerArgsKey,
-		rebindNonce
+		rebindNonce,
+		registry
 	]);
-	const [, force] = useReducer((x) => x + 1, 0);
-	const pathRef = useRef(emptyPathSet());
-	const expandedInterestRef = useRef(emptyPathSet());
-	const lastSelectionRef = useRef(null);
-	const renderStateRef = useRef(void 0);
-	const prevBlocRef = useRef(null);
-	useEffect(() => {
-		const channel = bloc.channel;
-		if (selectRef.current !== void 0) {
-			const unsub = channel.subscribe(() => ALL_PATHS, () => {
+	consumer.container = bloc;
+	useSyncExternalStore(useMemo(() => (onStoreChange) => {
+		consumer.notify = onStoreChange;
+		const container = consumer.container;
+		const unsubscribe = container.channel.subscribe(() => consumer.interest, () => {
+			if (consumer.isSelectMode) {
 				const select = selectRef.current;
-				if (!select) {
-					force();
-					return;
-				}
-				const next = select(bloc.state, bloc);
-				const prev = lastSelectionRef.current;
-				if (prev !== null && shallowArrayEqual(prev, next)) return;
-				lastSelectionRef.current = next;
-				force();
-			});
-			const select = selectRef.current;
-			if (select) {
-				const next = select(bloc.state, bloc);
-				const prev = lastSelectionRef.current;
-				if (prev === null || !shallowArrayEqual(prev, next)) {
-					lastSelectionRef.current = next;
-					force();
+				if (select) {
+					const next = select(container.state, container);
+					const prev = consumer.selection;
+					if (prev !== null && shallowArrayEqual(prev, next)) return;
+					consumer.selection = next;
 				}
 			}
-			return unsub;
-		}
-		const unsub = channel.subscribe(() => expandedInterestRef.current, () => force());
-		bloc.registerConsumerPaths(consumerId, pathRef.current);
-		if (bloc.state !== renderStateRef.current) force();
+			consumer.bump();
+		});
+		container.registerConsumerPaths(consumerId, consumer.paths);
 		return () => {
-			unsub();
-			bloc.unregisterConsumer(consumerId);
+			consumer.notify = noop;
+			unsubscribe();
+			container.unregisterConsumer(consumerId);
 		};
-	}, [bloc, consumerId]);
+	}, [
+		BlocClass,
+		instanceKey,
+		consumerId,
+		rebindNonce
+	]), consumer.getSnapshot, consumer.getServerSnapshot);
 	useLayoutEffect(() => {
-		const registry = getRegistry();
 		const live = registry.acquire(BlocClass, instanceKey, {
 			canCreate: true,
 			countRef: true,
-			refId: primaryRefId(consumerId)
+			refId: primaryRefId(consumerId),
+			args: resolveEffectiveArgs()
 		});
 		ownedBlocRef.current = live;
 		onMountRef.current?.(live);
-		if (live !== bloc) bumpRebind();
+		if (live !== bloc) {
+			rebindNonceRef.current++;
+			consumer.bump();
+		}
 		return () => {
 			onUnmountRef.current?.(ownedBlocRef.current ?? bloc);
 			registry.release(BlocClass, instanceKey, false, primaryRefId(consumerId));
@@ -293,26 +322,26 @@ function useBloc(BlocClass, options) {
 	}, [
 		BlocClass,
 		instanceKey,
-		consumerId
+		consumerId,
+		registry
 	]);
-	const rawState = bloc.state;
-	renderStateRef.current = rawState;
-	if (prevBlocRef.current !== bloc) {
-		prevBlocRef.current = bloc;
-		lastSelectionRef.current = null;
-	}
+	const container = consumer.container;
+	const rawState = container.state;
+	const select = selectRef.current;
+	consumer.isSelectMode = select !== void 0;
 	let state;
-	if (selectRef.current !== void 0) {
+	if (select !== void 0) {
 		state = rawState;
-		if (lastSelectionRef.current === null) lastSelectionRef.current = selectRef.current(rawState, bloc);
+		if (consumer.selection === null) consumer.selection = select(rawState, bloc);
+		consumer.interest = ALL_PATHS;
 	} else {
-		const tracked = trackRender(rawState, bloc.interner, proxyCacheRef.current);
+		const tracked = trackRender(rawState, container.interner, proxyCacheRef.current);
 		state = tracked.value;
 		trackedStateRef.current = tracked.value;
-		pathRef.current = tracked.paths;
-		const session = sessionRef.current;
+		consumer.paths = tracked.paths;
+		const session = consumer.session;
 		session.clear();
-		session.set(bloc, {
+		session.set(container, {
 			kind: "primary",
 			paths: tracked.paths
 		});
@@ -320,15 +349,15 @@ function useBloc(BlocClass, options) {
 	}
 	useLayoutEffect(() => {
 		trackedStateRef.current = null;
-		if (selectRef.current !== void 0) {
-			lastReconcileRef.current = null;
+		if (consumer.isSelectMode) {
+			consumer.lastReconcile = null;
 			return;
 		}
-		const container = bloc;
-		const paths = pathRef.current;
-		const session = sessionRef.current;
-		const last = lastReconcileRef.current;
-		if (last !== null && last.primaryContainer === container && pathSetEquals(last.primaryPaths, paths)) {
+		const primary = consumer.container;
+		const paths = consumer.paths;
+		const session = consumer.session;
+		const last = consumer.lastReconcile;
+		if (last !== null && last.primaryContainer === primary && pathSetEquals(last.primaryPaths, paths)) {
 			let unchanged = last.deps.size === session.size - 1;
 			if (unchanged) for (const [depContainer, entry] of session) {
 				if (entry.kind === "primary") continue;
@@ -340,13 +369,13 @@ function useBloc(BlocClass, options) {
 			}
 			if (unchanged) return;
 		}
-		container.registerConsumerPaths(consumerId, paths);
-		expandedInterestRef.current = expandWithAncestors(paths, container.interner);
-		const subs = depSubsRef.current;
+		primary.registerConsumerPaths(consumerId, paths);
+		consumer.interest = expandWithAncestors(paths, primary.interner);
+		const subs = consumer.depSubs;
 		for (const [depContainer, sub] of subs) if (!session.has(depContainer)) {
 			sub.unsubscribe();
 			depContainer.unregisterConsumer(consumerId);
-			getRegistry().release(sub.Type, sub.key, false, sub.refId);
+			registry.release(sub.Type, sub.key, false, sub.refId);
 			subs.delete(depContainer);
 		}
 		for (const [depContainer, entry] of session) {
@@ -358,14 +387,14 @@ function useBloc(BlocClass, options) {
 				existing.interestRef.current = interest;
 				continue;
 			}
-			getRegistry().acquire(entry.Type, entry.key, {
+			registry.acquire(entry.Type, entry.key, {
 				canCreate: true,
 				countRef: true,
 				refId: entry.refId,
 				args: entry.args
 			});
 			const interestRef = { current: interest };
-			const unsubscribe = depContainer.channel.subscribe(() => interestRef.current, () => force());
+			const unsubscribe = depContainer.channel.subscribe(() => interestRef.current, () => consumer.bump());
 			subs.set(depContainer, {
 				unsubscribe,
 				interestRef,
@@ -385,28 +414,46 @@ function useBloc(BlocClass, options) {
 				args: entry.args
 			});
 		}
-		lastReconcileRef.current = {
-			primaryContainer: container,
+		consumer.lastReconcile = {
+			primaryContainer: primary,
 			primaryPaths: paths,
 			deps: depsSignature
 		};
 	});
 	useEffect(() => {
-		const subs = depSubsRef.current;
+		const subs = consumer.depSubs;
 		return () => {
 			for (const [depContainer, sub] of subs) {
 				sub.unsubscribe();
 				depContainer.unregisterConsumer(consumerId);
-				getRegistry().release(sub.Type, sub.key, false, sub.refId);
+				registry.release(sub.Type, sub.key, false, sub.refId);
 			}
 			subs.clear();
 		};
-	}, [consumerId]);
-	return [
-		state,
-		trackedBloc,
-		componentRef
-	];
+	}, [consumerId, registry]);
+	return [state, trackedBloc];
+}
+const noop = () => {};
+function createConsumer() {
+	const consumer = {
+		container: null,
+		version: 0,
+		notify: noop,
+		bump: () => {
+			consumer.version++;
+			consumer.notify();
+		},
+		getSnapshot: () => consumer.version,
+		getServerSnapshot: () => consumer.version,
+		interest: emptyPathSet(),
+		paths: emptyPathSet(),
+		isSelectMode: false,
+		selection: null,
+		session: /* @__PURE__ */ new Map(),
+		depSubs: /* @__PURE__ */ new Map(),
+		lastReconcile: null
+	};
+	return consumer;
 }
 /**
 * Build the per-consumer wrapper that replaces a branded dep handle inside a
@@ -430,10 +477,9 @@ function useBloc(BlocClass, options) {
 * the dep already has a non-primary session entry this render, reuse its proxy
 * + union its paths instead of re-acquiring.
 */
-function makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, onDepHandle) {
+function makeDepWrapper(handle, consumerId, registry, trackedStateRef, consumer, onDepHandle) {
 	const brand = handle[DEP_BRAND];
 	const refId = depRefId(consumerId);
-	const registry = getRegistry();
 	const perDep = /* @__PURE__ */ new Map();
 	const proxyCache = new ProxyCache();
 	const resolve = (options) => {
@@ -450,7 +496,7 @@ function makeDepWrapper(handle, consumerId, trackedStateRef, sessionRef, onDepHa
 		track: (options) => {
 			const { dep, key, args } = resolve(options);
 			if (trackedStateRef.current == null) return [dep.state, dep];
-			const session = sessionRef.current;
+			const session = consumer.session;
 			const existing = session.get(dep);
 			const tracked = trackRender(dep.state, dep.interner, proxyCache);
 			let cache = perDep.get(dep);
@@ -533,19 +579,39 @@ function expandWithAncestors(paths, interner) {
 	}
 	return expanded;
 }
-let globalConfig = {};
+//#endregion
+//#region src/useBlocDeps.ts
 /**
-* Configure global defaults for `@blac/react` hooks.
+* Feed live values from the component into a bloc's `deps` lane.
+*
+* Each calling component is one owner: its slice is shallow-merged into the
+* bloc's merged `deps` view, and withdrawn when the component unmounts. The
+* bloc observes changes through `onDepsChanged`.
+*
+* ```tsx
+* const [state, bloc] = useBloc(CanvasCubit);
+* useBlocDeps(bloc, { canvas, onTick });
+* ```
 *
-* @param config - Partial configuration to merge with current globals
+* Use this for values a bloc must *read* but should not own — DOM handles,
+* callbacks, values from other hooks. Pass identity-stable values (`useMemo` /
+* `useCallback`) as you would to any hook; a new function identity each render
+* counts as a change.
 */
-function configureBlacReact(config) {
-	globalConfig = {
-		...globalConfig,
-		...config
-	};
+function useBlocDeps(bloc, slice) {
+	const ownerId = useId();
+	const latest = useRef(slice);
+	latest.current = slice;
+	useEffect(() => {
+		bloc[APPLY_DEPS](ownerId, latest.current);
+	});
+	useEffect(() => {
+		return () => {
+			bloc[REMOVE_DEPS_OWNER](ownerId);
+		};
+	}, [bloc, ownerId]);
 }
 //#endregion
-export { BlocProvider, configureBlacReact, untracked, useBloc, useProvidedArgs };
+export { BlocProvider, RegistryProvider, untracked, useBloc, useBlocDeps, useProvidedArgs };
 
 //# sourceMappingURL=index.js.map