@yoltra/react 0.1.0

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

@@ -0,0 +1,248 @@
+import { DeepReadonly, Dotted, Emit, Event, EventMapBase, EventPhase, PathValue, StoreInstance, WithGlob } from '@yoltra/core';
+/**
+ * Re-export of {@link PathValue} from `@yoltra/core`.
+ *
+ * Resolves the TypeScript type at a dotted path `P` within object type `T`.
+ * See the core definition for full documentation.
+ *
+ * @public
+ */
+export type { PathValue };
+/**
+ * Accepts either a single value or a readonly array of that value.
+ * Useful for APIs that take one-or-many keys.
+ *
+ * @example
+ * ```ts
+ * function takeIds(ids: OneOrMany<string>) { /* ... *\/ }
+ * takeIds('a');
+ * takeIds(['a','b'] as const);
+ * ```
+ *
+ * @public
+ */
+export type OneOrMany<T> = T | readonly T[];
+/**
+ * Returns the current {@link StoreInstance} from {@link StoreContext}.
+ * Throws if used outside of a `<StoreProvider>`.
+ *
+ * @typeParam EM - Event map type.
+ * @typeParam R  - Reducer name union.
+ * @typeParam S  - State record keyed by `R`.
+ *
+ * @example
+ * ```tsx
+ * const store = useStore<MyEM, 'counter' | 'todos', AppState>();
+ * const state = store.getState();
+ * ```
+ *
+ * @public
+ */
+export declare function useStore<EM extends EventMapBase, R extends string, S extends Record<R, any>>(): StoreInstance<R, S, EM>;
+/**
+ * Returns the store's `emit` function (stable reference).
+ *
+ * @typeParam EM - Event map type.
+ *
+ * @example
+ * ```tsx
+ * const emit = useEmit<MyEM>();
+ * await emit('ui', 'toggle', true);
+ * ```
+ *
+ * @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;
+/**
+ * Selects a derived value from the store using an external-store subscription.
+ * Re-renders when the selected value changes per `isEqual`.
+ *
+ * @typeParam S - State type returned by `getState()`.
+ * @typeParam T - Selected value type.
+ * @param selector - `(state) => value` derived from the current state.
+ * @param isEqual  - Optional equality comparator (defaults to `Object.is`).
+ *
+ * @example
+ * ```tsx
+ * const total = useSelector((s: AppState) => s.todos.items.length);
+ * ```
+ *
+ * @public
+ */
+export declare function useSelector<S extends Record<any, any>, T>(selector: (state: DeepReadonly<S>) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * Fine-grained **single-path** selector for a reducer's state.
+ *
+ * Re-renders only when the specified `reducer.property` (dotted path) actually changes.
+ * For most applications, prefer using the typed version from {@link createHooks}
+ * which infers all type parameters automatically.
+ *
+ * **Supports**
+ * - Exact root prop: `{ reducer: "todo", property: "data" }`
+ * - Exact deep path: `{ reducer: "todo", property: "data.123.title" }`
+ * - Wildcards (pattern): `{ reducer: "todo", property: "data.*" }` or `"data.**"`
+ *
+ * **Overloads**
+ * - Exact path (no `*`): returns the precise `PathValue` when `map` is omitted
+ * - Exact path + `map`: returns `T` from `map(value)`
+ * - Glob path (with `*`/`**`): requires `map` and returns `T` from `map(state)`
+ *
+ * @example Via createHooks (recommended)
+ * ```tsx
+ * const { useAtomicProp } = createHooks(AppStoreContext);
+ *
+ * function TodoTitle({ index }: { index: number }) {
+ *   // Types are inferred — no explicit generics needed
+ *   const title = useAtomicProp({
+ *     reducer: 'todos',
+ *     property: `items.${index}.title`,
+ *   });
+ *   return <span>{title}</span>;
+ * }
+ * ```
+ *
+ * @example Standalone with explicit generics
+ * ```tsx
+ * const title = useAtomicProp<'todos', AppState, 'todos', 'items.0.title'>(
+ *   { reducer: 'todos', property: 'items.0.title' }
+ * );
+ * ```
+ *
+ * @example Map over exact path
+ * ```tsx
+ * const len = useAtomicProp(
+ *   { reducer: 'todos', property: 'items' },
+ *   items => items.length
+ * );
+ * ```
+ *
+ * @example Glob pattern over state
+ * ```tsx
+ * const titles = useAtomicProp(
+ *   { reducer: 'todos', property: 'items.**' },
+ *   state => state.items.map(x => x.title),
+ *   shallowEqual
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function useAtomicProp<R extends string, S extends Record<R, any>, R1 extends R, P extends Dotted<S[R1]>>(spec: {
+    reducer: R1;
+    property: P;
+}): PathValue<S[R1], P>;
+export declare function useAtomicProp<R extends string, S extends Record<R, any>, R1 extends R, P extends Dotted<S[R1]>, T>(spec: {
+    reducer: R1;
+    property: P;
+}, map: (value: PathValue<S[R1], P>) => T, isEqual?: (a: T, b: T) => boolean): T;
+export declare function useAtomicProp<R extends string, S extends Record<R, any>, R1 extends R, P extends WithGlob<Dotted<S[R1]>>, T>(spec: {
+    reducer: R1;
+    property: P;
+}, map: (value: any) => T, isEqual?: (a: T, b: T) => boolean): T;
+export declare function useAtomicProp<R extends string, S extends Record<R, any>>(spec: {
+    reducer: R;
+    property: string;
+}): unknown;
+export declare function useAtomicProp<R extends string, S extends Record<R, any>, T>(spec: {
+    reducer: R;
+    property: string;
+}, map: (value: any) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * **Multi-path** fine-grained selector.
+ *
+ * Subscribes to several `reducer.property` paths (supports deep & wildcard)
+ * and recomputes `selector(state)` when any of them change.
+ *
+ * @typeParam R - Slice name union.
+ * @typeParam S - State record keyed by `R`.
+ * @typeParam T - Derived value type.
+ *
+ * @param specs    - Array of `{ reducer, property }`, where `property` can be a string or array of strings. Supports `*`/`**`.
+ * @param selector - `(state) => T` function run against the full state.
+ * @param isEqual  - Equality comparator for the derived value (defaults to `Object.is`).
+ *
+ * @example
+ * ```tsx
+ * const total = useAtomicProps<'todos' | 'filter', AppState, number>(
+ *   [
+ *     { reducer: 'todos',  property: 'items.**' },
+ *     { reducer: 'filter', property: 'q' }
+ *   ],
+ *   (s) => s.todos.items.filter(x => x.title.includes(s.filter.q)).length
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function useAtomicProps<R extends string, S extends Record<R, any>, T>(specs: Array<{
+    reducer: R;
+    property: OneOrMany<WithGlob<Dotted<S[R]>>>;
+}>, selector: (state: DeepReadonly<S>) => T, isEqual?: (a: T, b: T) => boolean): T;
+export declare function useAtomicProps<R extends string, S extends Record<R, any>, T>(specs: Array<{
+    reducer: R;
+    property: OneOrMany<string>;
+}>, selector: (state: DeepReadonly<S>) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * Subscribe to store events from a React component.
+ *
+ * This hook enables reactive UI patterns by allowing components to respond
+ * to specific events without selecting state. Useful for:
+ * - Showing notifications on certain events
+ * - Triggering animations
+ * - Logging/analytics
+ * - Responding to rejected (uncommitted) events
+ *
+ * **Phases:**
+ * - `'committed'` (default): Events that passed middleware and reached reducers
+ * - `'uncommitted'`: Events rejected by middleware
+ * - `'all'`: Both committed and uncommitted events (handler receives phase parameter)
+ *
+ * @typeParam EM - Event map type.
+ * @typeParam C - Channel key within `EM`.
+ * @typeParam T - Event type key within channel `C`.
+ *
+ * @param channel - Event channel to subscribe to.
+ * @param type - Event type to subscribe to.
+ * @param handler - Handler called when the event fires. Receives `(event, getState, emit, phase)`.
+ * @param phase - Event phase to subscribe to (default: `'committed'`).
+ *
+ * @example Committed events (default)
+ * ```tsx
+ * useEvent('ui', 'save', (event, getState, emit, phase) => {
+ *   showToast('Saved successfully!');
+ * });
+ * ```
+ *
+ * @example Rejected events
+ * ```tsx
+ * useEvent('ui', 'delete', (event, getState, emit, phase) => {
+ *   showToast('Delete was blocked by middleware');
+ * }, 'uncommitted');
+ * ```
+ *
+ * @example All events
+ * ```tsx
+ * useEvent('ui', 'action', (event, getState, emit, phase) => {
+ *   console.log('Action:', phase); // 'committed' or 'uncommitted'
+ * }, 'all');
+ * ```
+ *
+ * @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: "committed" | "uncommitted") => void | Promise<void>, phase?: EventPhase): void;

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

@@ -0,0 +1,178 @@
+import { Dotted, WithGlob } from '@yoltra/core';
+/**
+ * Default Suspense cache instance shared by all `useSuspense*` hooks.
+ *
+ * Use {@link invalidateAtomicProp}, {@link invalidateAtomicPropsByReducer},
+ * or {@link clearSuspenseCache} to manage the cache from outside hooks.
+ *
+ * @public
+ */
+export declare const suspenseCache: SuspenseCache;
+/**
+ * Options for {@link useSuspenseAtomicProp}.
+ *
+ * @typeParam T - The resolved value type after loading.
+ * @typeParam S - Store state record.
+ *
+ * @example
+ * ```ts
+ * const options: SuspenseAtomicPropOptions<User, AppState> = {
+ *   load: async (userId) => fetchUser(userId),
+ *   staleTime: 30_000, // cache for 30 seconds
+ *   key: 'user-detail',
+ * };
+ * ```
+ *
+ * @public
+ */
+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). */
+    staleTime?: number;
+    /** Optional extra key to differentiate cache entries for the same path. */
+    key?: string;
+}
+/**
+ * Suspense-compatible version of `useAtomicProp` that throws a promise while loading.
+ *
+ * Subscribes to a single dotted path and calls `options.load` to produce the
+ * resolved value. While the promise is pending, React Suspense catches it and
+ * renders the nearest `<Suspense>` fallback.
+ *
+ * @typeParam R - Reducer name union.
+ * @typeParam S - State record keyed by `R`.
+ * @typeParam P - Dotted path within `S[R]`.
+ * @typeParam T - Resolved value type.
+ *
+ * @param storeSpec - `{ reducer, property }` identifying the path to subscribe to.
+ * @param options - Loading options (see {@link SuspenseAtomicPropOptions}).
+ * @returns The resolved value of type `T`.
+ *
+ * @throws A `Promise` while loading (caught by React Suspense).
+ * @throws If called outside a `<StoreProvider>`.
+ *
+ * @example
+ * ```tsx
+ * function UserName({ userId }: { userId: string }) {
+ *   const name = useSuspenseAtomicProp(
+ *     { reducer: 'users', property: `byId.${userId}.name` },
+ *     { load: async (name) => name ?? (await fetchUser(userId)).name },
+ *   );
+ *   return <span>{name}</span>;
+ * }
+ *
+ * // Wrap with Suspense
+ * <Suspense fallback={<Spinner />}>
+ *   <UserName userId="123" />
+ * </Suspense>
+ * ```
+ *
+ * @public
+ */
+export declare function useSuspenseAtomicProp<R extends string, S extends Record<R, any>, P extends Dotted<S[R]>, T>(storeSpec: {
+    reducer: R;
+    property: P;
+}, options: SuspenseAtomicPropOptions<T, S>): T;
+export declare function useSuspenseAtomicProp<R extends string, S extends Record<R, any>, T>(storeSpec: {
+    reducer: R;
+    property: string;
+}, options: SuspenseAtomicPropOptions<T, S>): T;
+/**
+ * Options for {@link useSuspenseAtomicProps}.
+ *
+ * @typeParam T - The resolved value type after loading.
+ * @typeParam S - Store state record.
+ *
+ * @public
+ */
+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). */
+    staleTime?: number;
+    /** Optional extra key to differentiate cache entries. */
+    key?: string;
+}
+/**
+ * Suspense-compatible version of `useAtomicProps` that throws a promise while loading.
+ *
+ * Subscribes to multiple dotted paths and calls `options.load` with the full state
+ * to produce the resolved value. While the promise is pending, React Suspense
+ * renders the nearest `<Suspense>` fallback.
+ *
+ * @typeParam R - Reducer name union.
+ * @typeParam S - State record keyed by `R`.
+ * @typeParam T - Resolved value type.
+ *
+ * @param specs - Array of `{ reducer, property }` paths to subscribe to.
+ * @param options - Loading options (see {@link SuspenseAtomicPropsOptions}).
+ * @returns The resolved value of type `T`.
+ *
+ * @throws A `Promise` while loading (caught by React Suspense).
+ * @throws If called outside a `<StoreProvider>`.
+ *
+ * @example
+ * ```tsx
+ * function Dashboard() {
+ *   const stats = useSuspenseAtomicProps(
+ *     [
+ *       { reducer: 'orders', property: 'items.**' },
+ *       { reducer: 'users', property: 'active' },
+ *     ],
+ *     { load: async (state) => computeDashboardStats(state) },
+ *   );
+ *   return <StatsGrid data={stats} />;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useSuspenseAtomicProps<R extends string, S extends Record<R, any>, T>(specs: Array<{
+    reducer: R;
+    property: Dotted<S[R]> | WithGlob<Dotted<S[R]>> | ReadonlyArray<WithGlob<Dotted<S[R]>>>;
+}>, options: SuspenseAtomicPropsOptions<T, S>): T;
+export declare function useSuspenseAtomicProps<R extends string, S extends Record<R, any>, T>(specs: Array<{
+    reducer: R;
+    property: string | readonly string[];
+}>, options: SuspenseAtomicPropsOptions<T, S>): T;
+/**
+ * Invalidates the Suspense cache entry for a specific `reducer.property` path.
+ *
+ * @param reducer - Reducer (slice) name.
+ * @param property - Dotted property path.
+ * @param extraKey - Optional extra key if the hook was created with `options.key`.
+ *
+ * @example
+ * ```ts
+ * invalidateAtomicProp('users', 'byId.123.name');
+ * ```
+ *
+ * @public
+ */
+export declare function invalidateAtomicProp(reducer: string, property: string, extraKey?: string): void;
+/**
+ * Invalidates all Suspense cache entries for a given reducer (slice).
+ *
+ * @param reducer - Reducer (slice) name whose cache entries should be cleared.
+ *
+ * @example
+ * ```ts
+ * invalidateAtomicPropsByReducer('users');
+ * ```
+ *
+ * @public
+ */
+export declare function invalidateAtomicPropsByReducer(reducer: string): void;
+/**
+ * Clears the entire Suspense cache, forcing all `useSuspense*` hooks to re-load.
+ *
+ * @example
+ * ```ts
+ * // After a logout, clear all cached data
+ * clearSuspenseCache();
+ * ```
+ *
+ * @public
+ */
+export declare function clearSuspenseCache(): void;

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 } from './hooks/createHooks';
+export type { OneOrMany, PathValue } from './hooks/hooks';
+export type { SuspenseAtomicPropOptions, SuspenseAtomicPropsOptions } from './hooks/suspense';

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

@@ -0,0 +1 @@
+export {};

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

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

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@yoltra/react",
+  "version": "0.1.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:watch": "vitest --coverage",
+    "prepublishOnly": "node ../../common/scripts/copy-license.cjs",
+    "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"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Manu Ramirez <@pixerael>",
+    "email": "manu@yoltra.dev"
+  },
+  "maintainers": [],
+  "homepage": "https://yoltra.dev",
+  "keywords": [
+    "state",
+    "store",
+    "react",
+    "redux-alternative",
+    "yoltra"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yoltra/yoltra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yoltra/yoltra/issues"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "private": false,
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "peerDependencies": {
+    "@yoltra/core": "^0.1.0",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "@yoltra/core": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@yoltra/core": "workspace:^0.1.0",
+    "@eslint/js": "^9.30.1",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.2",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "16.3.0",
+    "@types/react-dom": "^19.1.6",
+    "@types/react": "^19.1.8",
+    "@types/node": "^24.0.12",
+    "@vitejs/plugin-react-swc": "^3.10.2",
+    "@vitejs/plugin-react": "^5.0.0",
+    "@vitest/coverage-v8": "3.2.4",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "vite-plugin-banner": "0.8.1",
+    "eslint": "^9.30.1",
+    "globals": "^16.3.0",
+    "jsdom": "^24.0.0",
+    "react-dom": "19.1.1",
+    "react": "19.1.1",
+    "rollup": "^4.16.0",
+    "typescript-eslint": "^8.35.1",
+    "typescript": "5.9.3",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "4.9.0",
+    "typedoc-plugin-localization": "3.0.6",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^4.3.2",
+    "vite": "^7.1.11",
+    "vitest": "3.2.4"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "react-native": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}