@j13b/react-state 0.1.0

package/src/__tests__/exports.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import {
+  useSignalValue,
+  useSignalValueEffect,
+  useUpdate,
+  useRunnerStatus,
+  useRunnerStatusEffect,
+  useRunnerError,
+  useRunnerErrorEffect,
+  useRunnerProgress,
+  useRunnerProgressEffect,
+  useRunnerFeedback,
+  useRunnerFeedbackEffect,
+} from '../index.js';
+
+describe('@j13b/react-state exports', () => {
+  it.each([
+    ['useSignalValue', useSignalValue],
+    ['useSignalValueEffect', useSignalValueEffect],
+    ['useUpdate', useUpdate],
+    ['useRunnerStatus', useRunnerStatus],
+    ['useRunnerStatusEffect', useRunnerStatusEffect],
+    ['useRunnerError', useRunnerError],
+    ['useRunnerErrorEffect', useRunnerErrorEffect],
+    ['useRunnerProgress', useRunnerProgress],
+    ['useRunnerProgressEffect', useRunnerProgressEffect],
+    ['useRunnerFeedback', useRunnerFeedback],
+    ['useRunnerFeedbackEffect', useRunnerFeedbackEffect],
+  ])('exports %s as a function', (_name, hook) => {
+    expect(typeof hook).toBe('function');
+  });
+});

package/src/__tests__/hooks.test.tsx

@@ -0,0 +1,242 @@
+import { describe, expect, it, vi } from 'vitest';
+import { act, render, screen } from '@testing-library/react';
+import { IBroadcast, Runner, Signal, Status } from '@j13b/state';
+import {
+  useRunnerStatus,
+  useSignalValue,
+  useSignalValueEffect,
+} from '../index.js';
+
+describe('useSignalValue', () => {
+  function makeProbe() {
+    const renders = { count: 0 };
+
+    function Probe({ broadcast }: { broadcast: IBroadcast<string> }) {
+      renders.count++;
+      const value = useSignalValue(broadcast);
+      return <div data-testid="value">{value}</div>;
+    }
+
+    return { Probe, renders };
+  }
+
+  it('re-renders with the new value on set and unsubscribes on unmount', () => {
+    const signal = new Signal('a');
+    const { Probe, renders } = makeProbe();
+
+    const { unmount } = render(<Probe broadcast={signal.broadcast} />);
+    expect(screen.getByTestId('value').textContent).toBe('a');
+
+    act(() => {
+      signal.set('b');
+    });
+    expect(screen.getByTestId('value').textContent).toBe('b');
+
+    unmount();
+    expect(signal.subscriptions.length).toBe(0);
+
+    const rendersAfterUnmount = renders.count;
+    expect(() => {
+      act(() => {
+        signal.set('c');
+      });
+    }).not.toThrow();
+    expect(renders.count).toBe(rendersAfterUnmount);
+  });
+
+  it('re-renders even when the same value is set again (version snapshot contract)', () => {
+    const signal = new Signal('same');
+    const { Probe, renders } = makeProbe();
+
+    render(<Probe broadcast={signal.broadcast} />);
+    const rendersBefore = renders.count;
+
+    act(() => {
+      signal.set('same');
+    });
+
+    expect(renders.count).toBeGreaterThan(rendersBefore);
+    expect(screen.getByTestId('value').textContent).toBe('same');
+  });
+
+  it('coalesces a synchronous burst of emissions into a single render of the latest value', () => {
+    const signal = new Signal(0);
+    const renders = { count: 0 };
+
+    function NumberProbe() {
+      renders.count++;
+      const value = useSignalValue(signal.broadcast);
+      return <div data-testid="number">{value}</div>;
+    }
+
+    render(<NumberProbe />);
+    const rendersBefore = renders.count;
+
+    act(() => {
+      signal.set(1);
+      signal.set(2);
+      signal.set(3);
+    });
+
+    expect(screen.getByTestId('number').textContent).toBe('3');
+    expect(renders.count).toBe(rendersBefore + 1);
+  });
+
+  it('subscribes to a swapped broadcast and ignores the old one', () => {
+    const first = new Signal('first');
+    const second = new Signal('second');
+    const { Probe, renders } = makeProbe();
+
+    const { rerender } = render(<Probe broadcast={first.broadcast} />);
+    expect(screen.getByTestId('value').textContent).toBe('first');
+
+    rerender(<Probe broadcast={second.broadcast} />);
+    expect(screen.getByTestId('value').textContent).toBe('second');
+    expect(first.subscriptions.length).toBe(0);
+
+    const rendersAfterSwap = renders.count;
+    act(() => {
+      first.set('stale');
+    });
+    expect(renders.count).toBe(rendersAfterSwap);
+    expect(screen.getByTestId('value').textContent).toBe('second');
+
+    act(() => {
+      second.set('updated');
+    });
+    expect(screen.getByTestId('value').textContent).toBe('updated');
+  });
+
+  it('keeps multiple components reading one signal consistent', () => {
+    const signal = new Signal(0);
+
+    function Reader({ testId }: { testId: string }) {
+      const value = useSignalValue(signal.broadcast);
+      return <div data-testid={testId}>{value}</div>;
+    }
+
+    render(
+      <div>
+        <Reader testId="one" />
+        <Reader testId="two" />
+      </div>
+    );
+
+    act(() => {
+      signal.set(42);
+    });
+
+    expect(screen.getByTestId('one').textContent).toBe('42');
+    expect(screen.getByTestId('two').textContent).toBe('42');
+  });
+});
+
+describe('useSignalValueEffect', () => {
+  function Probe({
+    broadcast,
+    onValue,
+  }: {
+    broadcast: IBroadcast<string>;
+    onValue: (value: string) => void;
+  }) {
+    useSignalValueEffect(onValue, broadcast);
+    return null;
+  }
+
+  it('fires once on mount with the current value and once per set', () => {
+    const signal = new Signal('initial');
+    const onValue = vi.fn();
+
+    render(<Probe broadcast={signal.broadcast} onValue={onValue} />);
+    expect(onValue.mock.calls).toEqual([['initial']]);
+
+    act(() => {
+      signal.set('next');
+    });
+    expect(onValue.mock.calls).toEqual([['initial'], ['next']]);
+
+    act(() => {
+      signal.set('next');
+    });
+    expect(onValue.mock.calls).toEqual([['initial'], ['next'], ['next']]);
+  });
+
+  it('fires exactly once per emission across a broadcast swap (no double-fire)', () => {
+    const first = new Signal('first');
+    const second = new Signal('second');
+    const onValue = vi.fn();
+
+    const { rerender } = render(
+      <Probe broadcast={first.broadcast} onValue={onValue} />
+    );
+    expect(onValue.mock.calls).toEqual([['first']]);
+
+    rerender(<Probe broadcast={second.broadcast} onValue={onValue} />);
+    expect(onValue.mock.calls).toEqual([['first'], ['second']]);
+
+    act(() => {
+      second.set('second-updated');
+    });
+    expect(onValue.mock.calls).toEqual([
+      ['first'],
+      ['second'],
+      ['second-updated'],
+    ]);
+
+    act(() => {
+      first.set('stale');
+    });
+    expect(onValue).toHaveBeenCalledTimes(3);
+  });
+
+  it('uses the latest callback prop without re-firing on callback change', () => {
+    const signal = new Signal('value');
+    const firstCallback = vi.fn();
+    const secondCallback = vi.fn();
+
+    const { rerender } = render(
+      <Probe broadcast={signal.broadcast} onValue={firstCallback} />
+    );
+    expect(firstCallback).toHaveBeenCalledTimes(1);
+
+    rerender(<Probe broadcast={signal.broadcast} onValue={secondCallback} />);
+    expect(secondCallback).not.toHaveBeenCalled();
+
+    act(() => {
+      signal.set('changed');
+    });
+    expect(firstCallback).toHaveBeenCalledTimes(1);
+    expect(secondCallback.mock.calls).toEqual([['changed']]);
+  });
+});
+
+describe('useRunnerStatus', () => {
+  it('transitions INITIAL -> PENDING -> SUCCESS through an execute()', async () => {
+    const runner = new Runner<string>('initial');
+
+    function Probe() {
+      const status = useRunnerStatus(runner.broadcast);
+      return <div data-testid="status">{status}</div>;
+    }
+
+    render(<Probe />);
+    expect(screen.getByTestId('status').textContent).toBe(Status.INITIAL);
+
+    let resolveAction!: (value: string) => void;
+    const actionResult = new Promise<string>(resolve => {
+      resolveAction = resolve;
+    });
+
+    let execution!: Promise<string>;
+    act(() => {
+      execution = runner.execute(() => actionResult);
+    });
+    expect(screen.getByTestId('status').textContent).toBe(Status.PENDING);
+
+    await act(async () => {
+      resolveAction('done');
+      await execution;
+    });
+    expect(screen.getByTestId('status').textContent).toBe(Status.SUCCESS);
+  });
+});

package/src/hooks/use_runner_error.ts

@@ -0,0 +1,29 @@
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValue } from './use_signal_value.js';
+
+/**
+ * A React hook that subscribes to the error state of a runner.
+ *
+ * @template T - The type of value that the runner manages
+ * @param {IRunnerBroadcast<T>} task - The runner broadcast interface to subscribe to
+ * @returns {Error | null} The current error state of the runner, or null if there is no error
+ *
+ * @example
+ * ```tsx
+ * const error = useRunnerError(saveRunner.broadcast);
+ * if (error) {
+ *   return <ErrorMessage error={error} />;
+ * }
+ * ```
+ *
+ * @remarks
+ * This hook is useful for:
+ * - Displaying error messages in the UI
+ * - Conditionally rendering error states
+ * - Triggering error handling logic
+ *
+ * The hook will automatically unsubscribe when the component unmounts.
+ */
+export function useRunnerError(task: IRunnerBroadcast<any>) {
+  return useSignalValue(task.stateBroadcast).error;
+}

package/src/hooks/use_runner_error_effect.ts

@@ -0,0 +1,37 @@
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValueEffect } from './use_signal_value_effect.js';
+
+/**
+ * A React hook that executes a callback whenever the error state of a Runner changes.
+ * This hook is useful for handling side effects that need to respond to error states
+ * in async operations managed by a Runner.
+ *
+ * @template T - The type of value managed by the Runner
+ * @param callback - A function that will be called with the current error state
+ * @param task - The Runner instance to monitor for error changes
+ * @returns void
+ *
+ * @example
+ * ```tsx
+ * useRunnerErrorEffect((error) => {
+ *   if (error) {
+ *     // Handle the error, e.g., show a notification
+ *     showErrorNotification(error.message);
+ *   }
+ * }, myRunner);
+ * ```
+ *
+ * @remarks
+ * - The callback will be called immediately with the current error state
+ * - The callback will be called whenever the error state changes
+ * - The hook automatically handles cleanup on component unmount
+ * - This hook is built on top of useSignalValueEffect for efficient state tracking
+ */
+export function useRunnerErrorEffect(
+  callback: (error: Error | null) => void,
+  task: IRunnerBroadcast<any>
+) {
+  return useSignalValueEffect(state => {
+    callback(state.error);
+  }, task.stateBroadcast);
+}

package/src/hooks/use_runner_feedback.ts

@@ -0,0 +1,31 @@
+/**
+ * @module hooks/use_runner_feedback
+ *
+ * This module provides a hook for accessing the feedback message from a Runner's state.
+ * It is useful for displaying status messages to users during async operations.
+ */
+
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValue } from './use_signal_value.js';
+
+/**
+ * Hook that provides access to the feedback message from a Runner's state.
+ *
+ * @template T - The type of the Runner's value
+ * @param {IRunnerBroadcast<T>} task - The Runner broadcast interface to subscribe to
+ * @returns {string | undefined} The current feedback message, or undefined if no feedback is set
+ *
+ * @example
+ * ```tsx
+ * const feedback = useRunnerFeedback(saveRunner.broadcast);
+ * return <div>{feedback}</div>;
+ * ```
+ *
+ * @remarks
+ * This hook is useful for displaying status messages to users during async operations.
+ * The feedback message is typically set using the Runner's setFeedback method.
+ * The component will automatically re-render when the feedback message changes.
+ */
+export function useRunnerFeedback(task: IRunnerBroadcast<any>) {
+  return useSignalValue(task.stateBroadcast).feedback;
+}

package/src/hooks/use_runner_feedback_effect.ts

@@ -0,0 +1,40 @@
+/**
+ * @module hooks/use_runner_feedback_effect
+ *
+ * This module provides a React hook for handling feedback messages from a Runner.
+ * It allows components to react to changes in the feedback state of async operations.
+ */
+
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValueEffect } from './use_signal_value_effect.js';
+
+/**
+ * A React hook that executes a callback whenever the feedback message of a Runner changes.
+ *
+ * This hook is useful for displaying operation feedback to users, such as loading messages,
+ * progress updates, or error notifications. It automatically handles cleanup when the
+ * component unmounts.
+ *
+ * @example
+ * ```tsx
+ * useRunnerFeedbackEffect(
+ *   (feedback) => {
+ *     // Update UI with feedback message
+ *     setMessage(feedback);
+ *   },
+ *   myRunner.broadcast
+ * );
+ * ```
+ *
+ * @param callback - A function that will be called with the new feedback message whenever it changes
+ * @param task - The Runner's broadcast interface to subscribe to
+ * @returns void
+ */
+export function useRunnerFeedbackEffect(
+  callback: (feedback: string) => void,
+  task: IRunnerBroadcast<any>
+) {
+  return useSignalValueEffect(state => {
+    callback(state.feedback);
+  }, task.stateBroadcast);
+}

package/src/hooks/use_runner_progress.ts

@@ -0,0 +1,25 @@
+/**
+ * A React hook that subscribes to the progress state of a Runner.
+ *
+ * @template T - The type of the Runner's value
+ * @param {IRunnerBroadcast<T>} task - The Runner broadcast interface to subscribe to
+ * @returns {number} A number between 0 and 1 representing the current progress of the task
+ *
+ * @example
+ * ```tsx
+ * const progress = useRunnerProgress(saveRunner.broadcast);
+ * // progress will be a number between 0 and 1
+ * // 0 = not started, 1 = complete
+ * ```
+ *
+ * @remarks
+ * This hook is useful for tracking the progress of long-running operations
+ * such as file uploads, data processing, or any task that can report progress.
+ * The component will automatically re-render when the progress value changes.
+ */
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValue } from './use_signal_value.js';
+
+export function useRunnerProgress(task: IRunnerBroadcast<any>) {
+  return useSignalValue(task.stateBroadcast).progress;
+}

package/src/hooks/use_runner_progress_effect.ts

@@ -0,0 +1,41 @@
+/**
+ * @module hooks/use_runner_progress_effect
+ *
+ * This module provides a React hook for tracking the progress of a Runner operation.
+ * It allows components to react to progress changes in long-running operations.
+ */
+
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValueEffect } from './use_signal_value_effect.js';
+
+/**
+ * Hook that executes a callback whenever the progress of a Runner operation changes.
+ *
+ * @template T - The type of the Runner's value
+ * @param callback - Function to be called when progress changes. Receives the current progress value (0-1)
+ * @param task - The Runner broadcast interface to track progress from
+ * @returns void
+ *
+ * @example
+ * ```tsx
+ * useRunnerProgressEffect(
+ *   (progress) => {
+ *     console.log(`Operation is ${progress * 100}% complete`);
+ *   },
+ *   myRunner.broadcast
+ * );
+ * ```
+ *
+ * @remarks
+ * - The callback will be called with a number between 0 and 1 representing progress
+ * - The effect is automatically cleaned up when the component unmounts
+ * - This hook is built on top of useSignalValueEffect for efficient state tracking
+ */
+export function useRunnerProgressEffect(
+  callback: (progress: number) => void,
+  task: IRunnerBroadcast<any>
+) {
+  return useSignalValueEffect(state => {
+    callback(state.progress);
+  }, task.stateBroadcast);
+}

package/src/hooks/use_runner_status.ts

@@ -0,0 +1,27 @@
+import { IRunnerBroadcast } from '@j13b/state';
+import { useSignalValue } from './use_signal_value.js';
+
+/**
+ * A hook that subscribes to a runner's status changes and returns the current status.
+ * The component will re-render whenever the runner's status changes.
+ *
+ * @template T - The type of the runner's value
+ * @param broadcast - The broadcast interface of the runner to subscribe to
+ * @returns The current status of the runner (INITIAL, PENDING, SUCCESS, ERROR)
+ *
+ * @example
+ * ```tsx
+ * const status = useRunnerStatus(runner.broadcast);
+ *
+ * return (
+ *   <div>
+ *     {status === 'PENDING' && <Spinner />}
+ *     {status === 'ERROR' && <ErrorMessage />}
+ *     {status === 'SUCCESS' && <SuccessMessage />}
+ *   </div>
+ * );
+ * ```
+ */
+export function useRunnerStatus(broadcast: IRunnerBroadcast<any>) {
+  return useSignalValue(broadcast.stateBroadcast).status;
+}

package/src/hooks/use_runner_status_effect.ts

@@ -0,0 +1,33 @@
+import { IRunnerBroadcast, Status } from '@j13b/state';
+import { useSignalValueEffect } from './use_signal_value_effect.js';
+
+/**
+ * A hook that runs an effect whenever a runner's status changes.
+ * This is useful for side effects that need to respond to runner status changes
+ * without causing a re-render.
+ *
+ * @template T - The type of the runner's value
+ * @param callback - The effect to run when the runner's status changes
+ * @param task - The broadcast interface of the runner to subscribe to
+ *
+ * @example
+ * ```tsx
+ * useRunnerStatusEffect(
+ *   status => {
+ *     if (status === 'ERROR') {
+ *       // Handle error state
+ *       showErrorToast();
+ *     }
+ *   },
+ *   runner.broadcast
+ * );
+ * ```
+ */
+export function useRunnerStatusEffect(
+  callback: (value: Status) => void,
+  task: IRunnerBroadcast<any>
+) {
+  return useSignalValueEffect(state => {
+    callback(state.status);
+  }, task.stateBroadcast);
+}

package/src/hooks/use_signal_value.ts

@@ -0,0 +1,61 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { IBroadcast } from '@j13b/state';
+
+/**
+ * A hook that subscribes to a signal's value changes and returns the current value.
+ * The component re-renders when the signal broadcasts. Notifications are batched
+ * by React: a burst of synchronous emissions (e.g. several `set()` calls in one
+ * event tick) renders once with the latest value — intermediate states are never
+ * painted.
+ *
+ * Built on React 18's `useSyncExternalStore`, which makes the hook:
+ * - Tear-free under concurrent rendering (React re-checks the snapshot after render).
+ * - SSR-safe: on the server the current value is rendered via the server snapshot
+ *   without subscribing (no `useLayoutEffect` warnings).
+ *
+ * The snapshot is the broadcast's monotonically increasing `version` rather than
+ * the value itself. This guarantees that no emission is silently ignored:
+ * `Signal.transform()` mutates the value in place and returns the SAME reference,
+ * so value/reference equality (`Object.is`) cannot detect the change — the version
+ * counter is what makes in-place transforms render. A consequence is that a
+ * `set()` of an identical value also triggers one render, since without a deep
+ * comparison it is indistinguishable from an in-place mutation.
+ *
+ * The subscription object returned by `broadcast.subscribe()` is strongly held by
+ * the unsubscribe closure for the lifetime of the subscription (the signal itself
+ * only holds it via WeakRef), and is unsubscribed when the component unmounts or
+ * the broadcast changes.
+ *
+ * @template TValue - The type of the signal's value
+ * @param broadcast - The broadcast interface of the signal to subscribe to
+ * @returns The current value of the signal
+ *
+ * @example
+ * ```tsx
+ * const value = useSignalValue(signal.broadcast);
+ *
+ * return <div>Current value: {value}</div>;
+ * ```
+ */
+export function useSignalValue<TValue>(broadcast: IBroadcast<TValue>) {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      // `subscription` must be strongly referenced: the signal only keeps a
+      // WeakRef to it, so this closure is what keeps the callback alive.
+      const subscription = broadcast.subscribe(onStoreChange);
+      return () => subscription.unsubscribe();
+    },
+    [broadcast]
+  );
+
+  // Version snapshot (deliberate): transform() mutates in place and returns the
+  // same reference, so Object.is on the value would miss changes. The version
+  // increments on every set(), so no emission is ignored (React coalesces a
+  // synchronous burst into a single render of the latest value). Do not
+  // snapshot the value.
+  const getSnapshot = useCallback(() => broadcast.version, [broadcast]);
+
+  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  return broadcast.get();
+}

package/src/hooks/use_signal_value_effect.ts

@@ -0,0 +1,68 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import type { IBroadcast } from '@j13b/state';
+
+// useLayoutEffect warns during server-side rendering; fall back to useEffect
+// there. Effects never run on the server either way, so behavior is identical.
+const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+/**
+ * A hook that runs an effect whenever a signal's value changes.
+ * This is useful for side effects that need to respond to signal value changes
+ * without causing a re-render.
+ *
+ * Contract:
+ * - The callback fires exactly once with the current value on mount, and again
+ *   once whenever the `broadcast` identity changes (with the new broadcast's
+ *   current value).
+ * - After that, it fires exactly once per emission — including emissions of an
+ *   identical value (every `set()` notifies subscribers). No double-fires.
+ * - The latest `callback` prop is always used; changing the callback does not
+ *   re-subscribe or re-fire.
+ * - The subscription object is strongly held for the component's lifetime (the
+ *   signal itself only holds it via WeakRef) and is cleaned up on unmount or
+ *   when the broadcast changes.
+ *
+ * @template T - The type of the signal's value
+ * @param callback - The effect to run when the signal's value changes
+ * @param broadcast - The broadcast interface of the signal to subscribe to
+ *
+ * @example
+ * ```tsx
+ * useSignalValueEffect(
+ *   value => {
+ *     // Do something with the new value
+ *     console.log('Value changed:', value);
+ *   },
+ *   signal.broadcast
+ * );
+ * ```
+ */
+export function useSignalValueEffect<T>(
+  callback: (value: T) => void,
+  broadcast: IBroadcast<T>
+) {
+  const callbackRef = useRef(callback);
+
+  // Declared before the subscription effect so the ref is up to date when the
+  // subscription effect (re-)runs in the same commit.
+  useIsomorphicLayoutEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useIsomorphicLayoutEffect(() => {
+    // `subscription` is strongly referenced by this effect's closure: the
+    // signal only keeps a WeakRef to it, so this is what keeps it alive.
+    const subscription = broadcast.subscribe(value => {
+      callbackRef.current(value);
+    });
+
+    // Fire exactly once with the current value on mount / broadcast change.
+    // Subsequent emissions arrive through the subscription above.
+    callbackRef.current(broadcast.get());
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [broadcast]);
+}