@webappwiz/react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jared Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @webappwiz/react
+
+Wiring React to the rest of webappwiz, and nothing else. Anything that would
+work without React lives in `webappwiz/browser`, and this
+package stays small on purpose.
+
+## Owning a resource for a mount
+
+```ts
+import { useResource, useDisposerEffect } from "@webappwiz/react";
+
+const parser = useResource(() => new Parser(source));
+
+useDisposerEffect((disposer) => {
+	disposer.use(new WindowBackgroundObserver());
+}, []);
+```
+
+`useResource` builds a `Resource` during render and disposes it on unmount,
+or when the factory changes. Its factory must be render-pure: React can abandon
+a render before commit, and anything acquired there would never be disposed.
+Acquire timers, subscriptions and workers in `useDisposerEffect` instead, which
+runs after commit and disposes everything it registered on teardown.
+
+## Rendering something that raises events
+
+```ts
+import { useReactive } from "@webappwiz/react";
+
+const title = useReactive(player, (player) => player.title(), ["change"]);
+```
+
+`useReactive` reads a projection of an `Eventful` and re-renders when the named
+events change what it returns. The projection is compared shallowly, so an
+event that changes nothing the component reads does not re-render it.
+
+`useExternalStore` and `ReactiveExternalStore` are the layer underneath, for
+when a store is wanted directly.
+
+The source is captured on the first render, so pass a stable one: a controller
+or a singleton, not an object built during render. Remount with a `key` if it
+has to change.

package/external-store/external-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A source `useExternalStore` can subscribe to: the `useSyncExternalStore`
+ * contract, as an object so the three calls travel together.
+ *
+ * The methods must keep a stable identity across renders. Bind them in the
+ * constructor or write them as arrow properties; a `.bind()` at the call site
+ * makes React tear down and rebuild the subscription every render.
+ */
+export interface ExternalStore<Snapshot> {
+    subscribe(onStoreChange: () => void): () => void;
+    getSnapshot(): Snapshot;
+    getServerSnapshot(): Snapshot;
+}

package/external-store/reactive-external-store.d.ts

@@ -0,0 +1,20 @@
+import type { Eventful, EventMapOf } from "webappwiz/events";
+import type { ExternalStore } from "./external-store.js";
+/**
+ * Projects part of an `Eventful` source into a snapshot, recomputing it when
+ * any of the named events fire and notifying React only when the projection
+ * actually changed (compared shallowly).
+ *
+ * The methods are arrow properties so their identity survives being passed to
+ * `useSyncExternalStore` on every render.
+ */
+export declare class ReactiveExternalStore<Source extends Eventful<Record<string, unknown>>, State> implements ExternalStore<State> {
+    private source;
+    private select;
+    private events;
+    private state;
+    constructor(source: Source, select: (source: Source) => State, events: Array<string & keyof EventMapOf<Source>>);
+    subscribe: (onStoreChange: () => void) => (() => void);
+    getSnapshot: () => State;
+    getServerSnapshot: () => State;
+}

package/external-store/shallow-equal.d.ts

@@ -0,0 +1,2 @@
+/** Compares two values by their own enumerable keys, one level deep. */
+export declare function shallowEqual<T>(left: T, right: T): boolean;

package/index.d.ts

@@ -0,0 +1,6 @@
+export type { ExternalStore } from "./external-store/external-store.js";
+export { ReactiveExternalStore } from "./external-store/reactive-external-store.js";
+export { type AppendOnlyDisposer, type DisposerEffectCallback, useDisposerEffect, } from "./use-disposer-effect.js";
+export { useExternalStore } from "./use-external-store.js";
+export { useReactive } from "./use-reactive.js";
+export { useResource } from "./use-resource.js";

package/index.js

@@ -0,0 +1,108 @@
+// external-store/reactive-external-store.ts
+import { Disposer } from "webappwiz/disposable";
+
+// external-store/shallow-equal.ts
+function shallowEqual(left, right) {
+  if (Object.is(left, right)) {
+    return true;
+  }
+  if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) {
+    return false;
+  }
+  const keysLeft = Object.keys(left);
+  const keysRight = Object.keys(right);
+  if (keysLeft.length !== keysRight.length) {
+    return false;
+  }
+  return keysLeft.every((key) => Object.hasOwn(right, key) && Object.is(left[key], right[key]));
+}
+
+// external-store/reactive-external-store.ts
+class ReactiveExternalStore {
+  source;
+  select;
+  events;
+  state;
+  constructor(source, select, events) {
+    this.source = source;
+    this.select = select;
+    this.events = events;
+    this.state = this.select(this.source);
+  }
+  subscribe = (onStoreChange) => {
+    const disposer = new Disposer;
+    const reconcile = () => {
+      const next = this.select(this.source);
+      if (!shallowEqual(this.state, next)) {
+        this.state = next;
+        onStoreChange();
+      }
+    };
+    for (const event of this.events) {
+      disposer.defer(this.source.events.on(event, reconcile));
+    }
+    reconcile();
+    return () => {
+      disposer.dispose();
+    };
+  };
+  getSnapshot = () => this.state;
+  getServerSnapshot = () => this.state;
+}
+// use-disposer-effect.ts
+import { useEffect } from "react";
+import { Disposer as Disposer2 } from "webappwiz/disposable";
+function useDisposerEffect(effect, deps) {
+  useEffect(() => {
+    const disposer = new Disposer2;
+    try {
+      effect(disposer);
+    } catch (error) {
+      disposer.dispose();
+      throw error;
+    }
+    return () => {
+      disposer.dispose();
+    };
+  }, deps);
+}
+// use-external-store.ts
+import { useSyncExternalStore } from "react";
+function useExternalStore(store) {
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+}
+// use-reactive.ts
+import { useRef, useState } from "react";
+function useReactive(source, select, events) {
+  const selectRef = useRef(select);
+  selectRef.current = select;
+  const [store] = useState(() => new ReactiveExternalStore(source, (source2) => selectRef.current(source2), events));
+  return useExternalStore(store);
+}
+// use-resource.ts
+import { useRef as useRef2, useState as useState2 } from "react";
+function useResource(factory) {
+  const [generation, setGeneration] = useState2(0);
+  const retiredRef = useRef2(new WeakSet);
+  const memo = useRef2(null);
+  if (memo.current === null || memo.current.factory !== factory || memo.current.generation !== generation || retiredRef.current.has(memo.current.instance)) {
+    memo.current = { factory, generation, instance: factory() };
+  }
+  const instance = memo.current.instance;
+  useDisposerEffect((disposer) => {
+    if (retiredRef.current.has(instance)) {
+      setGeneration((generation2) => generation2 + 1);
+      return;
+    }
+    disposer.use(instance);
+    disposer.defer(() => retiredRef.current.add(instance));
+  }, [instance]);
+  return instance;
+}
+export {
+  useResource,
+  useReactive,
+  useExternalStore,
+  useDisposerEffect,
+  ReactiveExternalStore
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@webappwiz/react",
+	"version": "0.0.1",
+	"description": "Wiring React to the rest of webappwiz: resources, reactive objects and external stores",
+	"license": "MIT",
+	"author": "Jared Johnson",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jaredjj3/webappwiz.git",
+		"directory": "packages/react"
+	},
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"webappwiz": "^0.0.1"
+	},
+	"peerDependencies": {
+		"react": "^19"
+	},
+	"main": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		}
+	}
+}

package/use-disposer-effect.d.ts

@@ -0,0 +1,10 @@
+import { type DependencyList } from "react";
+import { Disposer } from "webappwiz/disposable";
+/** A `Disposer` that can take on resources but cannot be disposed by the effect. */
+export type AppendOnlyDisposer = Pick<Disposer, "disposed" | "use" | "adopt" | "defer">;
+export type DisposerEffectCallback = (disposer: AppendOnlyDisposer) => void;
+/**
+ * Runs an effect that acquires resources, disposing everything it registered
+ * when the effect is torn down.
+ */
+export declare function useDisposerEffect(effect: DisposerEffectCallback, deps: DependencyList): void;

package/use-external-store.d.ts

@@ -0,0 +1,3 @@
+import type { ExternalStore } from "./external-store/external-store.js";
+/** Subscribes to an `ExternalStore` and returns its current snapshot. */
+export declare function useExternalStore<Snapshot>(store: ExternalStore<Snapshot>): Snapshot;

package/use-reactive.d.ts

@@ -0,0 +1,12 @@
+import type { Eventful, EventMapOf } from "webappwiz/events";
+/**
+ * Reads a projection of an `Eventful` source, re-rendering when any of the
+ * named events changes what `select` returns.
+ *
+ * The store is built once per mount. `select` is read through a ref, so an
+ * inline arrow that closes over fresh props still sees the latest values, but
+ * `source` and `events` are captured on the first render: pass a stable source
+ * (a controller or singleton, not a per-render object) and a fixed event list.
+ * Remount against a new source with a `key` if it ever needs to change.
+ */
+export declare function useReactive<Source extends Eventful<Record<string, unknown>>, State>(source: Source, select: (source: Source) => State, events: Array<string & keyof EventMapOf<Source>>): State;

package/use-resource.d.ts

@@ -0,0 +1,22 @@
+import type { Resource } from "webappwiz/disposable";
+/**
+ * Owns a disposable for the lifetime of a single mount. The factory builds the
+ * resource; it is disposed when the component unmounts or when the factory's
+ * identity changes (a constructor argument changed), at which point a fresh
+ * instance is built.
+ *
+ * Pass a factory, not a prebuilt instance: a factory is what lets the hook
+ * rebuild rather than hand back one it has already disposed. The instance is
+ * built during render, so a dependent resource built later in the same render
+ * reads the rebuilt one straight away.
+ *
+ * REQUIREMENT: the factory and the disposable's constructor must be
+ * render-pure. They may wire up in-memory state and pure helper objects, but
+ * must not acquire resources that need cleanup (timers, event or DOM
+ * subscriptions, workers, audio nodes, network, global mutation). Because
+ * construction happens at render, a render React abandons before commit (an
+ * interrupted concurrent render, a throw elsewhere in the tree) builds an
+ * instance whose disposing effect never runs, and anything acquired there
+ * leaks. Acquire such resources after commit, via `useDisposerEffect`.
+ */
+export declare function useResource<T extends Resource>(factory: () => T): T;