@blac/react 2.0.22 → 2.1.1

package/dist/BlocProvider.d.cts

@@ -18,14 +18,11 @@ export interface BlocProviderProps<T extends StateContainerConstructor> {
 }
 /**
  * Provides args to descendant `useBloc` calls for a specific bloc class via
- * React context.
- *
- * Descendants calling `useBloc(Bloc)` without their own `args` resolve to the
- * args supplied here. Own `args` on the `useBloc` call always win.
+ * React context. Own `args` on the `useBloc` call always win.
  *
  * Multiple `BlocProvider` wrappers for different bloc classes compose: each
- * provider merges its entry into the inherited map, so nested providers for
- * different blocs do not interfere.
+ * merges its entry into the inherited map, so nested providers for different
+ * blocs do not interfere.
  *
  * @example
  * ```tsx

package/dist/BlocProvider.d.ts

@@ -18,14 +18,11 @@ export interface BlocProviderProps<T extends StateContainerConstructor> {
 }
 /**
  * Provides args to descendant `useBloc` calls for a specific bloc class via
- * React context.
- *
- * Descendants calling `useBloc(Bloc)` without their own `args` resolve to the
- * args supplied here. Own `args` on the `useBloc` call always win.
+ * React context. Own `args` on the `useBloc` call always win.
  *
  * Multiple `BlocProvider` wrappers for different bloc classes compose: each
- * provider merges its entry into the inherited map, so nested providers for
- * different blocs do not interfere.
+ * merges its entry into the inherited map, so nested providers for different
+ * blocs do not interfere.
  *
  * @example
  * ```tsx

package/dist/RegistryProvider-BjSXfLeK.js

@@ -0,0 +1,40 @@
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+import { getRegistry } from "@blac/core";
+//#region src/RegistryProvider.tsx
+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
+	});
+}
+/**
+* The registry `useBloc` uses here: the nearest {@link RegistryProvider}'s,
+* else `getRegistry()`. The plain `@blac/core` helpers (`acquire`, `ensure`,
+* `watch`, …) can't read React context and always use `getRegistry()`; call
+* this registry's methods directly to stay inside a provider's scope.
+* @public
+*/
+function useRegistry() {
+	return useContext(RegistryContext) ?? getRegistry();
+}
+//#endregion
+export { useRegistry as n, RegistryProvider as t };
+
+//# sourceMappingURL=RegistryProvider-BjSXfLeK.js.map

package/dist/RegistryProvider-BjSXfLeK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RegistryProvider-BjSXfLeK.js","names":[],"sources":["../src/RegistryProvider.tsx"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\nimport { getRegistry, type StateContainerRegistry } from '@blac/core';\n\nconst RegistryContext = createContext<StateContainerRegistry | null>(null);\n\n/**\n * Props for {@link RegistryProvider}.\n * @public\n */\nexport interface RegistryProviderProps {\n  registry: StateContainerRegistry;\n  children: ReactNode;\n}\n\n/**\n * Scopes descendant `useBloc` calls to a specific registry instead of the\n * module-global default.\n *\n * Useful for test isolation, SSR isolation, and micro-frontends that must\n * not share bloc instances with the host page.\n *\n * @example\n * ```tsx\n * <RegistryProvider registry={new StateContainerRegistry()}>\n *   <App />\n * </RegistryProvider>\n * ```\n * @public\n */\nexport function RegistryProvider({\n  registry,\n  children,\n}: RegistryProviderProps): ReactElement {\n  return (\n    <RegistryContext.Provider value={registry}>\n      {children}\n    </RegistryContext.Provider>\n  );\n}\n\n/**\n * The registry `useBloc` uses here: the nearest {@link RegistryProvider}'s,\n * else `getRegistry()`. The plain `@blac/core` helpers (`acquire`, `ensure`,\n * `watch`, …) can't read React context and always use `getRegistry()`; call\n * this registry's methods directly to stay inside a provider's scope.\n * @public\n */\nexport function useRegistry(): StateContainerRegistry {\n  return useContext(RegistryContext) ?? getRegistry();\n}\n"],"mappings":";;;;AAQA,MAAM,kBAAkB,cAA6C,IAAI;;;;;;;;;;;;;;;;AA0BzE,SAAgB,iBAAiB,EAC/B,UACA,YACsC;CACtC,OACE,oBAAC,gBAAgB,UAAjB;EAA0B,OAAO;EAC9B;CACuB,CAAA;AAE9B;;;;;;;;AASA,SAAgB,cAAsC;CACpD,OAAO,WAAW,eAAe,KAAK,YAAY;AACpD"}

package/dist/RegistryProvider-F2qb_prD.cjs

@@ -0,0 +1,51 @@
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+let _blac_core = require("@blac/core");
+//#region src/RegistryProvider.tsx
+const RegistryContext = (0, react.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__ */ (0, react_jsx_runtime.jsx)(RegistryContext.Provider, {
+		value: registry,
+		children
+	});
+}
+/**
+* The registry `useBloc` uses here: the nearest {@link RegistryProvider}'s,
+* else `getRegistry()`. The plain `@blac/core` helpers (`acquire`, `ensure`,
+* `watch`, …) can't read React context and always use `getRegistry()`; call
+* this registry's methods directly to stay inside a provider's scope.
+* @public
+*/
+function useRegistry() {
+	return (0, react.useContext)(RegistryContext) ?? (0, _blac_core.getRegistry)();
+}
+//#endregion
+Object.defineProperty(exports, "RegistryProvider", {
+	enumerable: true,
+	get: function() {
+		return RegistryProvider;
+	}
+});
+Object.defineProperty(exports, "useRegistry", {
+	enumerable: true,
+	get: function() {
+		return useRegistry;
+	}
+});
+
+//# sourceMappingURL=RegistryProvider-F2qb_prD.cjs.map

package/dist/RegistryProvider-F2qb_prD.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"RegistryProvider-F2qb_prD.cjs","names":[],"sources":["../src/RegistryProvider.tsx"],"sourcesContent":["import {\n  createContext,\n  useContext,\n  type ReactElement,\n  type ReactNode,\n} from 'react';\nimport { getRegistry, type StateContainerRegistry } from '@blac/core';\n\nconst RegistryContext = createContext<StateContainerRegistry | null>(null);\n\n/**\n * Props for {@link RegistryProvider}.\n * @public\n */\nexport interface RegistryProviderProps {\n  registry: StateContainerRegistry;\n  children: ReactNode;\n}\n\n/**\n * Scopes descendant `useBloc` calls to a specific registry instead of the\n * module-global default.\n *\n * Useful for test isolation, SSR isolation, and micro-frontends that must\n * not share bloc instances with the host page.\n *\n * @example\n * ```tsx\n * <RegistryProvider registry={new StateContainerRegistry()}>\n *   <App />\n * </RegistryProvider>\n * ```\n * @public\n */\nexport function RegistryProvider({\n  registry,\n  children,\n}: RegistryProviderProps): ReactElement {\n  return (\n    <RegistryContext.Provider value={registry}>\n      {children}\n    </RegistryContext.Provider>\n  );\n}\n\n/**\n * The registry `useBloc` uses here: the nearest {@link RegistryProvider}'s,\n * else `getRegistry()`. The plain `@blac/core` helpers (`acquire`, `ensure`,\n * `watch`, …) can't read React context and always use `getRegistry()`; call\n * this registry's methods directly to stay inside a provider's scope.\n * @public\n */\nexport function useRegistry(): StateContainerRegistry {\n  return useContext(RegistryContext) ?? getRegistry();\n}\n"],"mappings":";;;;AAQA,MAAM,mBAAA,GAAA,MAAA,eAA+D,IAAI;;;;;;;;;;;;;;;;AA0BzE,SAAgB,iBAAiB,EAC/B,UACA,YACsC;CACtC,OACE,iBAAA,GAAA,kBAAA,KAAC,gBAAgB,UAAjB;EAA0B,OAAO;EAC9B;CACuB,CAAA;AAE9B;;;;;;;;AASA,SAAgB,cAAsC;CACpD,QAAA,GAAA,MAAA,YAAkB,eAAe,MAAA,GAAA,WAAA,aAAiB;AACpD"}

package/dist/RegistryProvider.d.cts

@@ -1,10 +1,5 @@
 import { type ReactElement, type ReactNode } from 'react';
-import type { StateContainerRegistry } from '@blac/core';
-/**
- * Internal context value: a registry to use in place of the module-global
- * default (`getRegistry()`), or `null` when no provider is present.
- */
-export declare const RegistryContext: import("react").Context<StateContainerRegistry | null>;
+import { type StateContainerRegistry } from '@blac/core';
 /**
  * Props for {@link RegistryProvider}.
  * @public
@@ -29,3 +24,11 @@ export interface RegistryProviderProps {
  * @public
  */
 export declare function RegistryProvider({ registry, children, }: RegistryProviderProps): ReactElement;
+/**
+ * The registry `useBloc` uses here: the nearest {@link RegistryProvider}'s,
+ * else `getRegistry()`. The plain `@blac/core` helpers (`acquire`, `ensure`,
+ * `watch`, …) can't read React context and always use `getRegistry()`; call
+ * this registry's methods directly to stay inside a provider's scope.
+ * @public
+ */
+export declare function useRegistry(): StateContainerRegistry;

package/dist/RegistryProvider.d.ts

@@ -1,10 +1,5 @@
 import { type ReactElement, type ReactNode } from 'react';
-import type { StateContainerRegistry } from '@blac/core';
-/**
- * Internal context value: a registry to use in place of the module-global
- * default (`getRegistry()`), or `null` when no provider is present.
- */
-export declare const RegistryContext: import("react").Context<StateContainerRegistry | null>;
+import { type StateContainerRegistry } from '@blac/core';
 /**
  * Props for {@link RegistryProvider}.
  * @public
@@ -29,3 +24,11 @@ export interface RegistryProviderProps {
  * @public
  */
 export declare function RegistryProvider({ registry, children, }: RegistryProviderProps): ReactElement;
+/**
+ * The registry `useBloc` uses here: the nearest {@link RegistryProvider}'s,
+ * else `getRegistry()`. The plain `@blac/core` helpers (`acquire`, `ensure`,
+ * `watch`, …) can't read React context and always use `getRegistry()`; call
+ * this registry's methods directly to stay inside a provider's scope.
+ * @public
+ */
+export declare function useRegistry(): StateContainerRegistry;

package/dist/buildTrackedProxy.d.cts

@@ -1,19 +1,18 @@
 /**
  * Build a per-consumer proxy for a bloc instance.
  *
- * Getters run with `this` bound to the **real instance**, not a proxy, so ES
+ * Getters run with `this` bound to the real instance, not the 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.
+ * `[WITH_TRACKED_STATE]`, which makes the instance's own `state` getter
+ * report the render's tracking proxy for the call's duration; nested getter
+ * chains stay tracked because the override remains set.
  *
  * One allocation per bloc acquisition (inside `useMemo`), so the proxy is
  * stable across renders.
  *
- * @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.
+ * @param onDepHandle - Invoked when a read returns a branded dep handle;
+ *   returns the value (the session-bound wrapper) to expose in its place.
+ *   Must cache wrappers per handle to avoid re-allocation.
  */
 export declare function buildTrackedProxy<T extends object>(instance: T, trackedStateRef: {
     current: unknown;

package/dist/buildTrackedProxy.d.ts

@@ -1,19 +1,18 @@
 /**
  * Build a per-consumer proxy for a bloc instance.
  *
- * Getters run with `this` bound to the **real instance**, not a proxy, so ES
+ * Getters run with `this` bound to the real instance, not the 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.
+ * `[WITH_TRACKED_STATE]`, which makes the instance's own `state` getter
+ * report the render's tracking proxy for the call's duration; nested getter
+ * chains stay tracked because the override remains set.
  *
  * One allocation per bloc acquisition (inside `useMemo`), so the proxy is
  * stable across renders.
  *
- * @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.
+ * @param onDepHandle - Invoked when a read returns a branded dep handle;
+ *   returns the value (the session-bound wrapper) to expose in its place.
+ *   Must cache wrappers per handle to avoid re-allocation.
  */
 export declare function buildTrackedProxy<T extends object>(instance: T, trackedStateRef: {
     current: unknown;

package/dist/depSession.d.cts

@@ -0,0 +1,54 @@
+import type { StateContainer, StateContainerConstructor, StateContainerRegistry } from '@blac/core';
+import { DEP_BRAND } from '@blac/core/internal';
+import { type PathSet } from '@dirtytalk/structural';
+/**
+ * The containers one `useBloc` consumer reads during a render: its primary
+ * bloc plus every dep reached through `this.<handle>.track()`.
+ *
+ * The render records entries; the commit calls `reconcile`, which subscribes
+ * and takes a ref on new deps and drops the ones no longer read. `dispose`
+ * releases everything. Refs are only taken at commit, so an uncommitted render
+ * never leaks one.
+ */
+export declare class DepSession {
+    private readonly consumerId;
+    private readonly onChange;
+    private readonly entries;
+    private readonly subs;
+    private lastReconciled;
+    private readonly refId;
+    constructor(consumerId: string, onChange: () => void);
+    begin(primary: StateContainer, paths: PathSet): void;
+    record(dep: StateContainer, paths: PathSet, Type: StateContainerConstructor, key: string, args: unknown): void;
+    /** Forces the next `reconcile` to run in full. */
+    invalidate(): void;
+    isUnchanged(): boolean;
+    reconcile(registry: StateContainerRegistry): void;
+    dispose(): void;
+    private drop;
+}
+interface DepAccessOptionsLike {
+    args?: unknown;
+}
+/** Structural shape of a branded `depend()` handle as seen from React. */
+export interface DepHandleLike {
+    track(options?: DepAccessOptionsLike): [unknown, StateContainer];
+    untracked(options?: DepAccessOptionsLike): StateContainer;
+    readonly [DEP_BRAND]: {
+        Type: StateContainerConstructor;
+        defaultArgs?: unknown;
+    };
+}
+/**
+ * Wrap a dep handle read inside a tracked getter. During a render (`tracked`
+ * is set) `.track()` records the dep's read paths into `session` and returns
+ * a tracked proxy, so the dep's own getters track too. Outside a render it
+ * returns the live `[state, dep]`, like the core handle.
+ *
+ * Args resolve per call, so one handle can reach several instances; proxies
+ * are cached per resolved instance.
+ */
+export declare function makeDepWrapper(handle: DepHandleLike, registry: StateContainerRegistry, session: DepSession, tracked: {
+    current: unknown;
+}, onDepHandle: (handle: object) => unknown): DepHandleLike;
+export {};

package/dist/depSession.d.ts

@@ -0,0 +1,54 @@
+import type { StateContainer, StateContainerConstructor, StateContainerRegistry } from '@blac/core';
+import { DEP_BRAND } from '@blac/core/internal';
+import { type PathSet } from '@dirtytalk/structural';
+/**
+ * The containers one `useBloc` consumer reads during a render: its primary
+ * bloc plus every dep reached through `this.<handle>.track()`.
+ *
+ * The render records entries; the commit calls `reconcile`, which subscribes
+ * and takes a ref on new deps and drops the ones no longer read. `dispose`
+ * releases everything. Refs are only taken at commit, so an uncommitted render
+ * never leaks one.
+ */
+export declare class DepSession {
+    private readonly consumerId;
+    private readonly onChange;
+    private readonly entries;
+    private readonly subs;
+    private lastReconciled;
+    private readonly refId;
+    constructor(consumerId: string, onChange: () => void);
+    begin(primary: StateContainer, paths: PathSet): void;
+    record(dep: StateContainer, paths: PathSet, Type: StateContainerConstructor, key: string, args: unknown): void;
+    /** Forces the next `reconcile` to run in full. */
+    invalidate(): void;
+    isUnchanged(): boolean;
+    reconcile(registry: StateContainerRegistry): void;
+    dispose(): void;
+    private drop;
+}
+interface DepAccessOptionsLike {
+    args?: unknown;
+}
+/** Structural shape of a branded `depend()` handle as seen from React. */
+export interface DepHandleLike {
+    track(options?: DepAccessOptionsLike): [unknown, StateContainer];
+    untracked(options?: DepAccessOptionsLike): StateContainer;
+    readonly [DEP_BRAND]: {
+        Type: StateContainerConstructor;
+        defaultArgs?: unknown;
+    };
+}
+/**
+ * Wrap a dep handle read inside a tracked getter. During a render (`tracked`
+ * is set) `.track()` records the dep's read paths into `session` and returns
+ * a tracked proxy, so the dep's own getters track too. Outside a render it
+ * returns the live `[state, dep]`, like the core handle.
+ *
+ * Args resolve per call, so one handle can reach several instances; proxies
+ * are cached per resolved instance.
+ */
+export declare function makeDepWrapper(handle: DepHandleLike, registry: StateContainerRegistry, session: DepSession, tracked: {
+    current: unknown;
+}, onDepHandle: (handle: object) => unknown): DepHandleLike;
+export {};

package/dist/expandWithAncestors.d.cts

@@ -0,0 +1,14 @@
+import { type PathInterner, type PathSet } from '@dirtytalk/structural';
+/**
+ * Add an ancestor-watch id for every ancestor of every tracked leaf, so a
+ * `patch` that replaces a parent atomically (e.g. the array `items`) wakes a
+ * consumer that read a child (`items.length`).
+ *
+ * Ancestor-watch ids only match marks the source emits for atomic
+ * replacements, never a plain-object pulse-up: `{'user.email'}` does not wake
+ * when a sibling `user.name` changes. The `''` root is never added; a root
+ * change already marks `ALL_PATHS`.
+ *
+ * Returns `paths` itself when no leaf has an ancestor.
+ */
+export declare function expandWithAncestors(paths: PathSet, interner: PathInterner): PathSet;

package/dist/expandWithAncestors.d.ts

@@ -0,0 +1,14 @@
+import { type PathInterner, type PathSet } from '@dirtytalk/structural';
+/**
+ * Add an ancestor-watch id for every ancestor of every tracked leaf, so a
+ * `patch` that replaces a parent atomically (e.g. the array `items`) wakes a
+ * consumer that read a child (`items.length`).
+ *
+ * Ancestor-watch ids only match marks the source emits for atomic
+ * replacements, never a plain-object pulse-up: `{'user.email'}` does not wake
+ * when a sibling `user.name` changes. The `''` root is never added; a root
+ * change already marks `ALL_PATHS`.
+ *
+ * Returns `paths` itself when no leaf has an ancestor.
+ */
+export declare function expandWithAncestors(paths: PathSet, interner: PathInterner): PathSet;