@nativewindow/react 1.0.0 → 1.0.2

package/README.md

@@ -2,8 +2,8 @@
 
 [![npm](https://img.shields.io/npm/v/@nativewindow/react)](https://www.npmjs.com/package/@nativewindow/react)
 
-> [!WARNING]
-> This project is in **alpha**. APIs may change without notice.
+> [!NOTE]
+> This project is in **beta**. APIs may change without notice.
 
 React hooks for [native-window-ipc](https://github.com/nativewindow/webview/tree/main/packages/ipc). Provides type-safe React bindings for the webview side of the IPC channel.
 
@@ -32,10 +32,12 @@ import { z } from "zod";
 import { createChannelHooks } from "@nativewindow/react";
 
 export const { ChannelProvider, useChannel, useChannelEvent, useSend } = createChannelHooks({
-  schemas: {
-    counter: z.number(),
+  host: {
     "update-title": z.string(),
   },
+  client: {
+    counter: z.number(),
+  },
 });
 ```
 
@@ -64,11 +66,12 @@ function Counter() {
   const [count, setCount] = useState(0);
   const send = useSend();
 
-  // Subscribe to events with automatic cleanup
-  useChannelEvent("counter", (n) => {
-    setCount(n);
+  // Subscribe to host events with automatic cleanup
+  useChannelEvent("update-title", (title) => {
+    document.title = title;
   });
 
+  // Send client events to the host
   return <button onClick={() => send("counter", count + 1)}>Count: {count}</button>;
 }
 ```

package/dist/index.js

@@ -1,99 +1,211 @@
-import { createContext, useRef, createElement, useContext, useEffect, useCallback } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useRef } from "react";
 import { createChannelClient } from "@nativewindow/ipc/client";
-const ChannelContext = createContext(null);
+//#region index.ts
+/** @internal React context holding the channel instance. */
+var ChannelContext = createContext(null);
+/**
+* Provides a typed IPC channel to the React tree.
+*
+* Creates the channel client exactly once (on initial mount) via
+* `createChannelClient` from `@nativewindow/ipc/client`.
+* The channel instance is stable for the lifetime of the provider.
+*
+* @example
+* ```tsx
+* import { z } from "zod";
+* import { ChannelProvider } from "@nativewindow/react";
+*
+* const schemas = {
+*   host: { title: z.string() },
+*   client: { counter: z.number() },
+* };
+*
+* function Root() {
+*   return (
+*     <ChannelProvider schemas={schemas}>
+*       <App />
+*     </ChannelProvider>
+*   );
+* }
+* ```
+*/
 function ChannelProvider(props) {
-  const { schemas, onValidationError, children } = props;
-  const channelRef = useRef(null);
-  if (channelRef.current === null) {
-    channelRef.current = createChannelClient({ schemas, onValidationError });
-  }
-  return createElement(ChannelContext.Provider, { value: channelRef.current }, children);
+	const { schemas, onValidationError, children } = props;
+	const channelRef = useRef(null);
+	if (channelRef.current === null) channelRef.current = createChannelClient({
+		schemas,
+		onValidationError
+	});
+	return createElement(ChannelContext.Provider, { value: channelRef.current }, children);
 }
+/**
+* Access the typed IPC channel from context.
+*
+* Must be called inside a {@link ChannelProvider}. Throws if the
+* provider is missing.
+*
+* @typeParam Send - Events this side can send (client events).
+* @typeParam Receive - Events this side can receive (host events).
+*
+* @example
+* ```tsx
+* import { useChannel } from "@nativewindow/react";
+*
+* type ClientEvents = { counter: number };
+* type HostEvents = { title: string };
+*
+* function StatusBar() {
+*   const channel = useChannel<ClientEvents, HostEvents>();
+*   channel.send("counter", 1);
+* }
+* ```
+*/
 function useChannel() {
-  const channel = useContext(ChannelContext);
-  if (channel === null) {
-    throw new Error("useChannel() must be used inside a <ChannelProvider>.");
-  }
-  return channel;
+	const channel = useContext(ChannelContext);
+	if (channel === null) throw new Error("useChannel() must be used inside a <ChannelProvider>.");
+	return channel;
 }
+/**
+* Subscribe to a specific incoming IPC event type with automatic cleanup.
+*
+* The handler is stored in a ref to avoid re-subscribing when the
+* handler function identity changes between renders. The subscription
+* itself only re-runs when `type` changes.
+*
+* @typeParam Receive - The event map for incoming (receivable) events.
+* @typeParam K - The specific event key to subscribe to.
+*
+* @example
+* ```tsx
+* import { useChannelEvent } from "@nativewindow/react";
+*
+* type HostEvents = { title: string };
+*
+* function TitleDisplay() {
+*   useChannelEvent<HostEvents, "title">("title", (title) => {
+*     document.title = title;
+*   });
+*   return null;
+* }
+* ```
+*/
 function useChannelEvent(type, handler) {
-  const channel = useChannel();
-  const handlerRef = useRef(handler);
-  handlerRef.current = handler;
-  useEffect(() => {
-    const stableHandler = (payload) => {
-      handlerRef.current(payload);
-    };
-    channel.on(type, stableHandler);
-    return () => {
-      channel.off(type, stableHandler);
-    };
-  }, [channel, type]);
+	const channel = useChannel();
+	const handlerRef = useRef(handler);
+	handlerRef.current = handler;
+	useEffect(() => {
+		const stableHandler = (payload) => {
+			handlerRef.current(payload);
+		};
+		channel.on(type, stableHandler);
+		return () => {
+			channel.off(type, stableHandler);
+		};
+	}, [channel, type]);
 }
+/**
+* Returns a stable `send` function from the channel.
+*
+* A convenience wrapper around `useChannel().send`. The returned
+* function has a stable identity (does not change between renders).
+*
+* @typeParam Send - The event map for outgoing (sendable) events.
+*
+* @example
+* ```tsx
+* import { useSend } from "@nativewindow/react";
+*
+* type ClientEvents = { counter: number };
+*
+* function Counter() {
+*   const send = useSend<ClientEvents>();
+*   return <button onClick={() => send("counter", 1)}>Increment</button>;
+* }
+* ```
+*/
 function useSend() {
-  const channel = useChannel();
-  return useCallback(
-    (...args) => {
-      channel.send(...args);
-    },
-    [channel]
-  );
+	const channel = useChannel();
+	return useCallback((...args) => {
+		channel.send(...args);
+	}, [channel]);
 }
+/**
+* Create a set of pre-typed React hooks for the IPC channel.
+*
+* Types are inferred from the `schemas` argument — no need to pass
+* generic type parameters to individual hooks. Each call creates its
+* own React context, so multiple independent channels are supported.
+*
+* @example
+* ```tsx
+* import { z } from "zod";
+* import { createChannelHooks } from "@nativewindow/react";
+*
+* // Types are inferred from directional schemas
+* const { ChannelProvider, useChannel, useChannelEvent, useSend } =
+*   createChannelHooks({
+*     host: { title: z.string() },
+*     client: { counter: z.number() },
+*   });
+*
+* function App() {
+*   const send = useSend();                        // fully typed (client events)
+*   useChannelEvent("title", (t) => {              // t: string (host events)
+*     document.title = t;
+*   });
+*   return <button onClick={() => send("counter", 1)}>+1</button>;
+* }
+*
+* function Root() {
+*   return (
+*     <ChannelProvider>
+*       <App />
+*     </ChannelProvider>
+*   );
+* }
+* ```
+*/
 function createChannelHooks(schemas, options) {
-  const HooksContext = createContext(null);
-  function HooksProvider(props) {
-    const channelRef = useRef(null);
-    if (channelRef.current === null) {
-      channelRef.current = createChannelClient({
-        schemas,
-        onValidationError: options?.onValidationError
-      });
-    }
-    return createElement(HooksContext.Provider, { value: channelRef.current }, props.children);
-  }
-  function hooks_useChannel() {
-    const channel = useContext(HooksContext);
-    if (channel === null) {
-      throw new Error(
-        "useChannel() must be used inside the <ChannelProvider> returned by createChannelHooks()."
-      );
-    }
-    return channel;
-  }
-  function hooks_useChannelEvent(type, handler) {
-    const channel = hooks_useChannel();
-    const handlerRef = useRef(handler);
-    handlerRef.current = handler;
-    useEffect(() => {
-      const stableHandler = (payload) => {
-        handlerRef.current(payload);
-      };
-      channel.on(type, stableHandler);
-      return () => {
-        channel.off(type, stableHandler);
-      };
-    }, [channel, type]);
-  }
-  function hooks_useSend() {
-    const channel = hooks_useChannel();
-    return useCallback(
-      (...args) => {
-        channel.send(...args);
-      },
-      [channel]
-    );
-  }
-  return {
-    ChannelProvider: HooksProvider,
-    useChannel: hooks_useChannel,
-    useChannelEvent: hooks_useChannelEvent,
-    useSend: hooks_useSend
-  };
+	const HooksContext = createContext(null);
+	function HooksProvider(props) {
+		const channelRef = useRef(null);
+		if (channelRef.current === null) channelRef.current = createChannelClient({
+			schemas,
+			onValidationError: options?.onValidationError
+		});
+		return createElement(HooksContext.Provider, { value: channelRef.current }, props.children);
+	}
+	function hooks_useChannel() {
+		const channel = useContext(HooksContext);
+		if (channel === null) throw new Error("useChannel() must be used inside the <ChannelProvider> returned by createChannelHooks().");
+		return channel;
+	}
+	function hooks_useChannelEvent(type, handler) {
+		const channel = hooks_useChannel();
+		const handlerRef = useRef(handler);
+		handlerRef.current = handler;
+		useEffect(() => {
+			const stableHandler = (payload) => {
+				handlerRef.current(payload);
+			};
+			channel.on(type, stableHandler);
+			return () => {
+				channel.off(type, stableHandler);
+			};
+		}, [channel, type]);
+	}
+	function hooks_useSend() {
+		const channel = hooks_useChannel();
+		return useCallback((...args) => {
+			channel.send(...args);
+		}, [channel]);
+	}
+	return {
+		ChannelProvider: HooksProvider,
+		useChannel: hooks_useChannel,
+		useChannelEvent: hooks_useChannelEvent,
+		useSend: hooks_useSend
+	};
 }
-export {
-  ChannelProvider,
-  createChannelHooks,
-  useChannel,
-  useChannelEvent,
-  useSend
-};
+//#endregion
+export { ChannelProvider, createChannelHooks, useChannel, useChannelEvent, useSend };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nativewindow/react",
-  "version": "1.0.0",
-  "description": "React bindings for native-window IPC (alpha)",
+  "version": "1.0.2",
+  "description": "React bindings for native-window IPC (beta)",
   "homepage": "https://nativewindow.fcannizzaro.com",
   "bugs": {
     "url": "https://github.com/nativewindow/webview/issues"
@@ -43,17 +43,17 @@
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.0",
-    "jsdom": "^28.1.0",
+    "jsdom": "^29.0.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
-    "vite": "^7.3.1",
+    "vite": "^8.0.3",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.2",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@nativewindow/ipc": "workspace:*",
     "react": "^18.0.0 || ^19.0.0",
-    "typescript": "^5"
+    "typescript": "^6.0.2"
   }
 }