@yoltra/react 0.1.0 → 0.2.0

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

@@ -53,22 +53,7 @@ export declare function useStore<EM extends EventMapBase, R extends string, S ex
  * @public
  */
 export declare function useEmit<EM extends EventMapBase>(): Emit<EM>;
-/**
- * Shallow object equality using `Object.is` per-key.
- *
- * Useful as the `isEqual` argument for `useAtomicProp` and `useAtomicProps`
- * when the derived value is a plain object. Also available from the object
- * returned by {@link createHooks}.
- *
- * @example
- * ```ts
- * shallowEqual({ a: 1 }, { a: 1 }); // true
- * shallowEqual({ a: 1 }, { a: 2 }); // false
- * ```
- *
- * @public
- */
-export declare function shallowEqual<T extends Record<string, any>>(a: T, b: T): boolean;
+export { shallowEqual } from '../utils/shallowEqual';
 /**
  * Selects a derived value from the store using an external-store subscription.
  * Re-renders when the selected value changes per `isEqual`.

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

@@ -28,7 +28,12 @@ export declare const suspenseCache: SuspenseCache;
 export interface SuspenseAtomicPropOptions<T, S> {
     /** Async loader that receives the value at the path and the full slice. */
     load: (valueAtPath: any, slice: S[keyof S]) => Promise<T> | T;
-    /** Time in ms before the cached value is considered stale (default: 0). */
+    /**
+     * Extra wall-clock TTL (ms) for a resolved value. `0` (the default) or omitted
+     * means the cached value is served until the subscribed path changes or you
+     * invalidate it explicitly; a positive value additionally expires it after that
+     * many ms. Cached errors ignore this and are re-thrown until invalidated.
+     */
     staleTime?: number;
     /** Optional extra key to differentiate cache entries for the same path. */
     key?: string;
@@ -40,6 +45,12 @@ export interface SuspenseAtomicPropOptions<T, S> {
  * resolved value. While the promise is pending, React Suspense catches it and
  * renders the nearest `<Suspense>` fallback.
  *
+ * @remarks
+ * **Client-only loading.** During server rendering this hook does not suspend
+ * (throwing a promise would crash `renderToString`): `getServerSnapshot` returns
+ * the current value at the path **without** invoking `options.load`. Perform the
+ * actual load on the client.
+ *
  * @typeParam R - Reducer name union.
  * @typeParam S - State record keyed by `R`.
  * @typeParam P - Dotted path within `S[R]`.
@@ -89,7 +100,12 @@ export declare function useSuspenseAtomicProp<R extends string, S extends Record
 export interface SuspenseAtomicPropsOptions<T, S> {
     /** Async loader that receives the full store state. */
     load: (state: S) => Promise<T> | T;
-    /** Time in ms before the cached value is considered stale (default: 0). */
+    /**
+     * Extra wall-clock TTL (ms) for a resolved value. `0` (the default) or omitted
+     * means the cached value is served until the subscribed path changes or you
+     * invalidate it explicitly; a positive value additionally expires it after that
+     * many ms. Cached errors ignore this and are re-thrown until invalidated.
+     */
     staleTime?: number;
     /** Optional extra key to differentiate cache entries. */
     key?: string;
@@ -101,6 +117,12 @@ export interface SuspenseAtomicPropsOptions<T, S> {
  * to produce the resolved value. While the promise is pending, React Suspense
  * renders the nearest `<Suspense>` fallback.
  *
+ * @remarks
+ * **Client-only loading.** During server rendering this hook does not suspend
+ * (throwing a promise would crash `renderToString`): `getServerSnapshot` uses a
+ * synchronous `options.load` result if one is available, otherwise `undefined`.
+ * Perform the actual load on the client.
+ *
  * @typeParam R - Reducer name union.
  * @typeParam S - State record keyed by `R`.
  * @typeParam T - Resolved value type.

package/dist/types/index.d.ts

@@ -6,6 +6,8 @@ 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 } 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';

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

@@ -0,0 +1,19 @@
+/**
+ * @module @yoltra/react
+ */
+/**
+ * Shallow object equality using `Object.is` per-key.
+ *
+ * Useful as the `isEqual` argument for `useAtomicProp` and `useAtomicProps`
+ * when the derived value is a plain object. Also available from the object
+ * returned by {@link createHooks} and {@link createYoltra}.
+ *
+ * @example
+ * ```ts
+ * shallowEqual({ a: 1 }, { a: 1 }); // true
+ * shallowEqual({ a: 1 }, { a: 2 }); // false
+ * ```
+ *
+ * @public
+ */
+export declare function shallowEqual<T extends Record<string, unknown>>(a: T, b: T): boolean;

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

@@ -0,0 +1,4 @@
+/**
+ * @module @yoltra/react
+ */
+export {};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@yoltra/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React bindings for Yoltra",
   "scripts": {
     "build": "tsc -p tsconfig.build.json && vite build",
     "lint": "node ../../tools/repo-tools/bin/repo-eslint.cjs --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "node ../../tools/repo-tools/bin/repo-eslint.cjs --fix",
-    "test": "pnpm vitest --coverage --watch=false",
+    "test": "vitest --coverage --watch=false",
     "test:watch": "vitest --coverage",
     "prepublishOnly": "node ../../common/scripts/copy-license.cjs",
     "docs": "rushx docs:js && rushx docs:md",
@@ -51,7 +51,7 @@
     "node": ">=18.18"
   },
   "peerDependencies": {
-    "@yoltra/core": "^0.1.0",
+    "@yoltra/core": "^0.2.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
@@ -64,7 +64,7 @@
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@yoltra/core": "workspace:^0.1.0",
+    "@yoltra/core": "workspace:*",
     "@eslint/js": "^9.30.1",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-node-resolve": "^15.2.3",