@yoltra/react 0.3.0 → 0.5.0

package/dist/types/entity/useEntity.d.ts

@@ -0,0 +1,32 @@
+import { EntityAdapter, EntityId } from '@yoltra/core';
+/**
+ * Subscribes to a collection's order.
+ *
+ * @remarks
+ * This is the subscription a list container wants, and the only one that should wake when the
+ * collection is reordered. Rows use {@link useEntity} or {@link useEntityField} and stay
+ * asleep through a sort.
+ *
+ * @public
+ */
+export declare function useEntityIds<T, Id extends EntityId, R extends string>(reducer: R, adapter: EntityAdapter<T, Id>): readonly Id[];
+/**
+ * Subscribes to one entity.
+ *
+ * @returns The entity, or `undefined` once it has been removed — a row that outlives its data
+ * for one render is normal, and returning `undefined` is what lets it render nothing rather
+ * than throw.
+ *
+ * @public
+ */
+export declare function useEntity<T, Id extends EntityId, R extends string>(reducer: R, adapter: EntityAdapter<T, Id>, id: Id): T | undefined;
+/**
+ * Subscribes to one field of one entity.
+ *
+ * @remarks
+ * The narrowest subscription available, and the reason the shape is worth adopting: editing a
+ * title wakes the components reading that title and nothing else.
+ *
+ * @public
+ */
+export declare function useEntityField<T, Id extends EntityId, R extends string, K extends keyof T & string>(reducer: R, adapter: EntityAdapter<T, Id>, id: Id, field: K): T[K] | undefined;

package/dist/types/hooks/createHooks.d.ts

@@ -1,4 +1,5 @@
 import { DeepReadonly, Dotted, Emit, Event, EventMapBase, EventPhase, PathValue, StoreInstance, WithGlob } from '@yoltra/core';
+import { UseSuspenseAtomicProp, UseSuspenseAtomicProps } from './suspense.js';
 import * as React from "react";
 /**
  * Call signature for the typed `useAtomicProp` hook returned by {@link createHooks}.
@@ -137,6 +138,10 @@ export interface YoltraHooks<R extends string, S extends Record<R, any>, EM exte
     useAtomicProps: UseAtomicProps<R, S>;
     /** Runs a handler for a specific `(channel, type)` event. */
     useEvent: UseEvent<EM, S>;
+    /** Suspense-loading variant of `useAtomicProp`, bound to the same context. */
+    useSuspenseAtomicProp: UseSuspenseAtomicProp<R, S>;
+    /** Suspense-loading variant of `useAtomicProps`, bound to the same context. */
+    useSuspenseAtomicProps: UseSuspenseAtomicProps<R, S>;
     /** Shallow object equality using `Object.is` per-key. */
     shallowEqual: <T extends Record<string, unknown>>(a: T, b: T) => boolean;
 }
@@ -153,7 +158,8 @@ export interface YoltraHooks<R extends string, S extends Record<R, any>, EM exte
  *
  * @param StoreContext - A React context carrying a `StoreInstance<R, S, EM>`.
  * @returns An object with typed hooks: `useStore`, `useEmit`, `useSelector`,
- *   `useAtomicProp`, `useAtomicProps`, `useEvent`, and `shallowEqual`.
+ *   `useAtomicProp`, `useAtomicProps`, `useEvent`, `useSuspenseAtomicProp`,
+ *   `useSuspenseAtomicProps`, and `shallowEqual`.
  *
  * @throws If any returned hook is called outside a `<StoreProvider>`.
  *

package/dist/types/hooks/hooks.d.ts

@@ -53,7 +53,7 @@ export declare function useStore<EM extends EventMapBase, R extends string, S ex
  * @public
  */
 export declare function useEmit<EM extends EventMapBase>(): Emit<EM>;
-export { shallowEqual } from '../utils/shallowEqual';
+export { shallowEqual } from '../utils/shallowEqual.js';
 /**
  * Selects a derived value from the store using an external-store subscription.
  * Re-renders when the selected value changes per `isEqual`.
@@ -173,6 +173,19 @@ export declare function useAtomicProp<R extends string, S extends Record<R, any>
  * );
  * ```
  *
+ * @remarks
+ * The selector receives **only the paths declared in `specs`**, not the whole store. Reading
+ * anything else yields `undefined` in production and throws in development, naming the path.
+ *
+ * That is deliberate, and it replaced a real bug: the two arguments used to be independent, so
+ * a component could subscribe to one path and read another. It compiled, it ran, and it worked
+ * for as long as the two happened to change together — this repository shipped exactly that in
+ * its own example, where a list subscribed to `todo.filter` while reading `todo.data` and
+ * re-rendered only because adding a todo also rewrote `filter.categories`.
+ *
+ * Correct code is unaffected. Code that read more than it declared was already wrong, and now
+ * says so on the first render rather than on the first day the coincidence breaks.
+ *
  * @public
  */
 export declare function useAtomicProps<R extends string, S extends Record<R, any>, T>(specs: Array<{

package/dist/types/hooks/suspense.d.ts

@@ -35,6 +35,19 @@ export interface SuspenseAtomicPropOptions<T, S> {
      * many ms. Cached errors ignore this and are re-thrown until invalidated.
      */
     staleTime?: number;
+    /**
+     * How long a **failed** load is remembered, in milliseconds.
+     *
+     * @remarks
+     * `0` or omitted — the default — delivers the error to the nearest boundary and then forgets
+     * it, so resetting that boundary retries the load. Held errors made a retry button unable to
+     * retry, which turned a transient failure into a permanent one.
+     *
+     * A positive value puts a floor between attempts, for a loader that fails fast and would
+     * otherwise be re-attempted on every reset. `null` holds the failure until something calls
+     * `invalidate`, which is the old behaviour and is now something you ask for.
+     */
+    errorTtlMs?: number | null;
     /** Optional extra key to differentiate cache entries for the same path. */
     key?: string;
 }
@@ -107,6 +120,19 @@ export interface SuspenseAtomicPropsOptions<T, S> {
      * many ms. Cached errors ignore this and are re-thrown until invalidated.
      */
     staleTime?: number;
+    /**
+     * How long a **failed** load is remembered, in milliseconds.
+     *
+     * @remarks
+     * `0` or omitted — the default — delivers the error to the nearest boundary and then forgets
+     * it, so resetting that boundary retries the load. Held errors made a retry button unable to
+     * retry, which turned a transient failure into a permanent one.
+     *
+     * A positive value puts a floor between attempts, for a loader that fails fast and would
+     * otherwise be re-attempted on every reset. `null` holds the failure until something calls
+     * `invalidate`, which is the old behaviour and is now something you ask for.
+     */
+    errorTtlMs?: number | null;
     /** Optional extra key to differentiate cache entries. */
     key?: string;
 }
@@ -198,3 +224,43 @@ export declare function invalidateAtomicPropsByReducer(reducer: string): void;
  * @public
  */
 export declare function clearSuspenseCache(): void;
+/**
+ * Call signature for the typed `useSuspenseAtomicProp` returned by `createHooks`.
+ *
+ * Identical in behaviour to the package-level {@link useSuspenseAtomicProp}; the reducer union
+ * and state shape are fixed by the store the hooks were created for, so neither has to be
+ * supplied at the call site.
+ *
+ * @typeParam R - Reducer name union.
+ * @typeParam S - State record keyed by `R`.
+ *
+ * @public
+ */
+export type UseSuspenseAtomicProp<R extends string, S extends Record<R, any>> = {
+    <R1 extends R, P extends Dotted<S[R1]>, T>(storeSpec: {
+        reducer: R1;
+        property: P;
+    }, options: SuspenseAtomicPropOptions<T, S>): T;
+    <R1 extends R, T>(storeSpec: {
+        reducer: R1;
+        property: string;
+    }, options: SuspenseAtomicPropOptions<T, S>): T;
+};
+/**
+ * Call signature for the typed `useSuspenseAtomicProps` returned by `createHooks`.
+ *
+ * @typeParam R - Reducer name union.
+ * @typeParam S - State record keyed by `R`.
+ *
+ * @public
+ */
+export type UseSuspenseAtomicProps<R extends string, S extends Record<R, any>> = {
+    <R1 extends R, T>(specs: Array<{
+        reducer: R1;
+        property: WithGlob<Dotted<S[R1]>> | ReadonlyArray<WithGlob<Dotted<S[R1]>>>;
+    }>, options: SuspenseAtomicPropsOptions<T, S>): T;
+    <R1 extends R, T>(specs: Array<{
+        reducer: R1;
+        property: string | readonly string[];
+    }>, options: SuspenseAtomicPropsOptions<T, S>): T;
+};

package/dist/types/index.d.ts

@@ -1,13 +1,15 @@
 /**
  * @module @yoltra/react
  */
-export { StoreContext } from './context/StoreContext';
-export { StoreProvider } from './context/StoreProvider';
-export { shallowEqual, useAtomicProp, useAtomicProps, useEmit, useEvent, useSelector, useStore, } from './hooks/hooks';
-export { clearSuspenseCache, invalidateAtomicProp, invalidateAtomicPropsByReducer, suspenseCache, useSuspenseAtomicProp, useSuspenseAtomicProps, } from './hooks/suspense';
-export { createHooks } from './hooks/createHooks';
-export type { UseAtomicProp, UseAtomicProps, UseEvent, YoltraHooks } from './hooks/createHooks';
-export { createYoltra } from './createYoltra';
-export type { Yoltra } from './createYoltra';
-export type { OneOrMany, PathValue } from './hooks/hooks';
-export type { SuspenseAtomicPropOptions, SuspenseAtomicPropsOptions } from './hooks/suspense';
+export { StoreContext } from './context/StoreContext.js';
+export { StoreProvider } from './context/StoreProvider.js';
+export { shallowEqual, useEmit, useEvent, useSelector, useStore } from './hooks/hooks.js';
+export { clearSuspenseCache, invalidateAtomicProp, invalidateAtomicPropsByReducer, suspenseCache, } from './hooks/suspense.js';
+export { createHooks } from './hooks/createHooks.js';
+export type { UseAtomicProp, UseAtomicProps, UseEvent, YoltraHooks } from './hooks/createHooks.js';
+export type { UseSuspenseAtomicProp, UseSuspenseAtomicProps } from './hooks/suspense.js';
+export { createYoltra } from './createYoltra.js';
+export type { Yoltra } from './createYoltra.js';
+export type { OneOrMany, PathValue } from './hooks/hooks.js';
+export type { SuspenseAtomicPropOptions, SuspenseAtomicPropsOptions } from './hooks/suspense.js';
+export { useEntity, useEntityField, useEntityIds } from './entity/useEntity.js';

package/dist/types/utils/declaredProjection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Building the slice of state a component actually declared.
+ *
+ * @remarks
+ * `useAtomicProps` used to take two independent arguments: a list of paths that wake the
+ * component, and a selector handed the *entire* state. Nothing tied them together, so
+ * declaring one path and reading another compiled, ran, and worked — until the day the two
+ * stopped changing together. This repository shipped that bug in its own example: a list
+ * subscribed to `todo.filter` while reading `todo.data`, and re-rendered only because adding a
+ * todo happened to rewrite `filter.categories` too.
+ *
+ * The fix is not to detect the mismatch but to remove the opportunity. The selector is handed
+ * a projection containing the declared paths and nothing else, so reading undeclared state is
+ * no longer a mistake that can be made silently — it reads `undefined` immediately, on the
+ * first render, instead of a correct value that goes stale later.
+ *
+ * In development it does better than `undefined`: the projection is wrapped in a guard that
+ * throws and names the path, because a `TypeError` three frames downstream is a poor way to
+ * learn you forgot a subscription.
+ *
+ * @module @yoltra/react
+ */
+/** A declared subscription, already normalized. */
+export interface DeclaredPath {
+    readonly reducer: string;
+    /** Dotted path within the reducer's slice. `""` means the whole slice. */
+    readonly property: string;
+}
+/**
+ * Builds the projection of `state` that `declared` covers.
+ *
+ * @remarks
+ * Leaves are copied by reference, so nothing is cloned and identity-based memoization
+ * downstream keeps working. Only the containers needed to reach a declared leaf are rebuilt.
+ *
+ * A declared path that does not exist in state is still written, as `undefined`. That keeps
+ * "declared but absent" distinguishable from "never declared", which is what lets the
+ * development guard tell a missing subscription from a missing value.
+ */
+export declare function projectDeclared(state: unknown, declared: readonly DeclaredPath[]): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoltra/react",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "React bindings for Yoltra",
   "license": "MIT",
   "author": {
@@ -40,9 +40,8 @@
     "node": ">=18.18"
   },
   "peerDependencies": {
-    "@yoltra/core": "^0.3.0",
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
+    "@yoltra/core": "^0.5.0",
+    "react": "^18 || ^19"
   },
   "peerDependenciesMeta": {
     "@yoltra/core": {
@@ -84,7 +83,7 @@
     "vite-tsconfig-paths": "^4.3.2",
     "vite": "^7.1.11",
     "vitest": "3.2.4",
-    "@yoltra/core": "0.3.0"
+    "@yoltra/core": "0.5.0"
   },
   "exports": {
     ".": {
@@ -96,14 +95,31 @@
     },
     "./package.json": "./package.json"
   },
+  "sizeLimit": [
+    {
+      "name": "barrel",
+      "limitKb": 6.5,
+      "external": [
+        "react",
+        "@yoltra/core",
+        "tslib"
+      ]
+    }
+  ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && vite build",
+    "build": "tsc -p tsconfig.build.json && vite build && node ../../tools/repo-tools/bin/dts-extensions.mjs dist/types",
     "lint": "node ../../tools/repo-tools/bin/repo-eslint.cjs --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.vitest.json --noEmit",
     "lint:fix": "node ../../tools/repo-tools/bin/repo-eslint.cjs --fix",
     "test": "vitest --coverage --watch=false",
     "test:watch": "vitest --coverage",
-    "docs": "rushx docs:js && rushx docs:md",
-    "docs:md": "pnpm typedoc --options ./typedoc.react.json",
-    "docs:js": "pnpm typedoc --options ./typedoc.react.json --json ./.typedoc/react-en.json"
+    "docs": "rushx docs:js && rushx docs:md && rushx docs:stamp",
+    "docs:stamp": "node ../../tools/repo-tools/bin/docs-stamp.mjs docs",
+    "docs:md": "typedoc --options ./typedoc.react.json",
+    "docs:js": "typedoc --options ./typedoc.react.json --json ./.typedoc/react-en.json",
+    "size": "node ../../tools/repo-tools/bin/size-check.cjs",
+    "bench": "vitest bench --run",
+    "bench:check": "node ../../tools/repo-tools/bin/bench-check.cjs",
+    "bench:record": "node ../../tools/repo-tools/bin/bench-check.cjs --record"
   }
 }