@yoltra/react 0.6.0 → 0.8.0

package/dist/types/createYoltra.d.ts

@@ -1,4 +1,4 @@
-import { DeepReadonly, EffectSpec, EMFromReducersStrict, EventMapBase, EventUnion, MiddlewareFunction, ReducersMapAny, StateFromReducers, StoreInstance } from '@yoltra/core';
+import { DeepReadonly, EffectSpec, EMAddOf, EMFromReducersStrict, EventMapBase, EventUnion, Merge, MiddlewareFunction, MiddlewareInput, ReducersMapAny, ReducerSpec, SatisfiesSlices, StateFromReducers, StateOfSpec, StoreInstance, WidenNames, WidenState } from '@yoltra/core';
 import { default as React, ReactNode } from 'react';
 import { YoltraHooks } from './hooks/createHooks.js';
 /**
@@ -12,7 +12,7 @@ import { YoltraHooks } from './hooks/createHooks.js';
  *
  * @public
  */
-export interface Yoltra<R extends string, S extends Record<R, any>, EM extends EventMapBase> extends YoltraHooks<R, S, EM> {
+export interface Yoltra<R extends string, S extends Record<R, any>, EM extends EventMapBase> extends YoltraHooks<R, S, EM>, YoltraDecoration<R, S, EM> {
     /** The store created by this call; the hooks default to it (no Provider needed). */
     store: StoreInstance<R, S, EM>;
     /** Raw context carrying the store — usually you only need `StoreProvider`. */
@@ -23,6 +23,44 @@ export interface Yoltra<R extends string, S extends Record<R, any>, EM extends E
         children: ReactNode;
     }>;
 }
+/**
+ * The chainable decoration surface on a {@link Yoltra}.
+ *
+ * @remarks
+ * `Yoltra` extends this, so every hook set is chainable.
+ *
+ * Every method returns a **new hook set bound to the same context object**, re-typed. The
+ * context is never recreated, so a `StoreProvider` from any view in the chain serves the
+ * hooks of every other, and the Suspense cache is shared - it keys on store identity through
+ * a `WeakMap`, and the widened store is the same object.
+ *
+ * Call these at **module scope, once, before first render**. `createHooks` allocates fresh
+ * function objects per call, so decorating inside a component would hand React a different
+ * hook set on every render.
+ *
+ * @public
+ */
+export interface YoltraDecoration<R extends string, S extends Record<R, any>, EM extends EventMapBase> {
+    /** Mounts a slice and returns a widened `Yoltra`: the same store, a new hook set. */
+    withSlice<N extends string, Spec extends ReducerSpec<any, any>>(name: N, spec: Spec, options?: {
+        owner?: string;
+    }): DecoratableYoltra<WidenNames<R, N>, SatisfiesSlices<WidenState<S, N, StateOfSpec<Spec>>, WidenNames<R, N>>, Merge<EM, EMAddOf<Spec>>>;
+    /**
+     * Registers middleware and returns a `Yoltra` widened by whatever event map it declares.
+     *
+     * Only the spec form can widen; a bare `MiddlewareFunction` contributes nothing, because
+     * its event parameter is `EventUnion<EM>` and TypeScript cannot infer `EM` back out of it.
+     */
+    withMiddleware<M extends MiddlewareInput<any, any>>(mw: M): DecoratableYoltra<R, S, Merge<EM, EMAddOf<M>>>;
+    /** Registers an effect and returns a `Yoltra` widened by whatever event map it declares. */
+    withEffect<Spec extends EffectSpec<any, any>>(spec: Spec): DecoratableYoltra<R, S, Merge<EM, EMAddOf<Spec>>>;
+}
+/**
+ * A {@link Yoltra} carrying the chainable decoration surface.
+ *
+ * @public
+ */
+export type DecoratableYoltra<R extends string, S extends Record<R, any>, EM extends EventMapBase> = Yoltra<R, S, EM>;
 /**
  * One-call setup: create a store and its fully-typed React hooks together.
  *
@@ -41,7 +79,7 @@ export interface Yoltra<R extends string, S extends Record<R, any>, EM extends E
  * **The Suspense hooks are part of this set.** Take `useSuspenseAtomicProp` and
  * `useSuspenseAtomicProps` from here, not from the `@yoltra/react` barrel: the
  * barrel's copies read the *package-level* context, which this function never
- * fills, so they would throw `useStore must be used inside <StoreProvider>` at
+ * fills, so they would throw `[yoltra] No store in context` at
  * runtime with nothing in the types to warn you — the two are identical in
  * shape. The ones returned here are bound to this store's own context and need
  * no provider, like the rest of the set.
@@ -94,3 +132,26 @@ export declare function createYoltra<RM extends ReducersMapAny>(cfg: {
     };
     onEffectError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>) => void;
 }): Yoltra<keyof RM & string, StateFromReducers<RM>, EMFromReducersStrict<RM>>;
+/**
+ * {@link YoltraDecoration.withSlice} as a free function.
+ *
+ * @remarks
+ * For a library handed a `Yoltra` it did not create. Identical to the method.
+ *
+ * @public
+ */
+export declare function withSlice<R extends string, S extends Record<R, any>, EM extends EventMapBase, N extends string, Spec extends ReducerSpec<any, any>>(yoltra: Yoltra<R, S, EM>, name: N, spec: Spec, options?: {
+    owner?: string;
+}): DecoratableYoltra<WidenNames<R, N>, SatisfiesSlices<WidenState<S, N, StateOfSpec<Spec>>, WidenNames<R, N>>, Merge<EM, EMAddOf<Spec>>>;
+/**
+ * {@link YoltraDecoration.withMiddleware} as a free function.
+ *
+ * @public
+ */
+export declare function withMiddleware<R extends string, S extends Record<R, any>, EM extends EventMapBase, M extends MiddlewareInput<any, any>>(yoltra: Yoltra<R, S, EM>, mw: M): DecoratableYoltra<R, S, Merge<EM, EMAddOf<M>>>;
+/**
+ * {@link YoltraDecoration.withEffect} as a free function.
+ *
+ * @public
+ */
+export declare function withEffect<R extends string, S extends Record<R, any>, EM extends EventMapBase, Spec extends EffectSpec<any, any>>(yoltra: Yoltra<R, S, EM>, spec: Spec): DecoratableYoltra<R, S, Merge<EM, EMAddOf<Spec>>>;

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

@@ -109,7 +109,17 @@ export type UseAtomicProps<R extends string, S extends Record<R, any>> = {
  *
  * @public
  */
-export type UseEvent<EM extends EventMapBase, S> = <C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (event: Event<EM, C, T>, getState: () => DeepReadonly<S>, emit: Emit<EM>, phase: NotifiedPhase) => void | Promise<void>, phase?: EventPhase) => void;
+export type UseEvent<EM extends EventMapBase, S> = <C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (event: Event<EM, C, T>, getState: () => DeepReadonly<S>, emit: Emit<EM>, phase: NotifiedPhase) => void | Promise<void>, phase?: EventPhase, options?: {
+    /**
+     * Also run this handler while devtools is replaying, which it does not by default.
+     *
+     * @remarks
+     * Opt in only for a handler that derives view state purely from the event stream. A
+     * handler that publishes, writes or notifies must stay out: scrubbing a timeline is a
+     * debugging operation and should not reach a peer, a socket or an analytics endpoint.
+     */
+    duringReplay?: boolean;
+}) => void;
 /**
  * The bundle of fully-typed hooks returned by {@link createHooks} (and, with the
  * store and provider added, by {@link createYoltra}).

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

@@ -243,4 +243,14 @@ export declare function useAtomicProps<R extends string, S extends Record<R, any
  *
  * @public
  */
-export declare function useEvent<EM extends EventMapBase, C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (event: Event<EM, C, T>, getState: () => DeepReadonly<any>, emit: Emit<EM>, phase: NotifiedPhase) => void | Promise<void>, phase?: EventPhase): void;
+export declare function useEvent<EM extends EventMapBase, C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (event: Event<EM, C, T>, getState: () => DeepReadonly<any>, emit: Emit<EM>, phase: NotifiedPhase) => void | Promise<void>, phase?: EventPhase, options?: {
+    /**
+     * Also run this handler while devtools is replaying, which it does not by default.
+     *
+     * @remarks
+     * Opt in only for a handler that derives view state purely from the event stream. A
+     * handler that publishes, writes or notifies must stay out: scrubbing a timeline is a
+     * debugging operation and should not reach a peer, a socket or an analytics endpoint.
+     */
+    duringReplay?: boolean;
+}): void;

package/dist/types/index.d.ts

@@ -9,8 +9,8 @@ export type { 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 { createYoltra, withEffect, withMiddleware, withSlice } from './createYoltra.js';
+export type { DecoratableYoltra, Yoltra, YoltraDecoration } 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoltra/react",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "React bindings for Yoltra",
   "license": "MIT",
   "author": {
@@ -18,7 +18,8 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/yoltra/yoltra.git"
+    "url": "https://github.com/yoltra/yoltra.git",
+    "directory": "packages/react"
   },
   "bugs": {
     "url": "https://github.com/yoltra/yoltra/issues"
@@ -37,10 +38,10 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18.18"
+    "node": ">=18"
   },
   "peerDependencies": {
-    "@yoltra/core": "^0.6.0",
+    "@yoltra/core": "^0.8.0",
     "react": "^18 || ^19"
   },
   "peerDependenciesMeta": {
@@ -83,7 +84,7 @@
     "vite-tsconfig-paths": "^4.3.2",
     "vite": "^7.3.6",
     "vitest": "3.2.7",
-    "@yoltra/core": "0.6.0"
+    "@yoltra/core": "0.8.0"
   },
   "exports": {
     ".": {
@@ -117,7 +118,8 @@
     "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",
+    "size": "node ../../tools/repo-tools/bin/size-check.cjs --check-readme",
+    "size:write": "node ../../tools/repo-tools/bin/size-check.cjs --write-readme",
     "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"