@nativewindow/react 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Saverio Cannizzaro
+
+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,104 @@
+# @nativewindow/react
+
+[![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.
+
+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.
+
+## Install
+
+```bash
+bun add @nativewindow/react
+# or
+deno add npm:@nativewindow/react
+```
+
+### Peer Dependencies
+
+- `react` ^18.0.0 || ^19.0.0
+- `@nativewindow/ipc`
+
+## Usage
+
+### Factory approach (recommended)
+
+Create pre-typed hooks from your schemas:
+
+```ts
+// channel.ts
+import { z } from "zod";
+import { createChannelHooks } from "@nativewindow/react";
+
+export const { ChannelProvider, useChannel, useChannelEvent, useSend } = createChannelHooks({
+  schemas: {
+    counter: z.number(),
+    "update-title": z.string(),
+  },
+});
+```
+
+### Provider setup
+
+Wrap your app with `ChannelProvider`:
+
+```tsx
+import { ChannelProvider } from "./channel";
+
+function App() {
+  return (
+    <ChannelProvider>
+      <Counter />
+    </ChannelProvider>
+  );
+}
+```
+
+### Hooks
+
+```tsx
+import { useChannelEvent, useSend } from "./channel";
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  const send = useSend();
+
+  // Subscribe to events with automatic cleanup
+  useChannelEvent("counter", (n) => {
+    setCount(n);
+  });
+
+  return <button onClick={() => send("counter", count + 1)}>Count: {count}</button>;
+}
+```
+
+## API
+
+### `createChannelHooks(options)`
+
+Factory that returns pre-typed `{ ChannelProvider, useChannel, useChannelEvent, useSend }`. Each call creates its own React context, supporting multiple independent channels.
+
+### `ChannelProvider`
+
+React component that creates a `createChannelClient` instance and provides it via context.
+
+### `useChannel()`
+
+Access the typed channel from context. Throws if used outside `ChannelProvider`.
+
+### `useChannelEvent(type, handler)`
+
+Subscribe to a specific IPC event type. Automatically cleans up on unmount. Handler is stored in a ref to avoid re-subscriptions on handler identity changes.
+
+### `useSend()`
+
+Returns a stable `send` function (memoized via `useCallback`).
+
+## Documentation
+
+Full documentation at [nativewindow.fcannizzaro.com](https://nativewindow.fcannizzaro.com)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+import { ReactNode } from 'react';
+import { EventMap, SendArgs, SchemaMap, InferSchemaMap, TypedChannel, ValidationErrorHandler } from '@nativewindow/ipc';
+/**
+ * React hooks for the native-window typed IPC channel (webview-side).
+ *
+ * Provides lifecycle wrappers around `createChannelClient` from
+ * `@nativewindow/ipc/client` for use inside a React app
+ * running in a native webview.
+ *
+ * The recommended approach is to use {@link createChannelHooks} to get
+ * a set of pre-typed hooks that infer event types from your schemas:
+ *
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { createChannelHooks } from "@nativewindow/react";
+ *
+ * const { ChannelProvider, useChannel, useChannelEvent, useSend } =
+ *   createChannelHooks({
+ *     counter: z.number(),
+ *     title: z.string(),
+ *   });
+ *
+ * function App() {
+ *   const send = useSend();
+ *   useChannelEvent("title", (t) => { document.title = t; });
+ *   return <button onClick={() => send("counter", 1)}>+1</button>;
+ * }
+ *
+ * function Root() {
+ *   return (
+ *     <ChannelProvider>
+ *       <App />
+ *     </ChannelProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { EventMap, SchemaLike, SchemaMap, InferSchemaMap, InferOutput, SendArgs, ValidationErrorHandler, TypedChannel, } from '@nativewindow/ipc';
+export type { ChannelClientOptions } from '../ipc/client.ts';
+/**
+ * Props for {@link ChannelProvider}.
+ *
+ * @example
+ * ```tsx
+ * <ChannelProvider schemas={schemas}>
+ *   <App />
+ * </ChannelProvider>
+ * ```
+ */
+export interface ChannelProviderProps<S extends SchemaMap> {
+    /** Schemas for each event. Provides both TypeScript types and runtime validation. */
+    schemas: S;
+    /**
+     * Called when an incoming payload fails schema validation.
+     * If not provided, failed payloads are silently dropped.
+     */
+    onValidationError?: ValidationErrorHandler;
+    /** React children. */
+    children: ReactNode;
+}
+/**
+ * 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 = {
+ *   counter: z.number(),
+ *   title: z.string(),
+ * };
+ *
+ * function Root() {
+ *   return (
+ *     <ChannelProvider schemas={schemas}>
+ *       <App />
+ *     </ChannelProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function ChannelProvider<S extends SchemaMap>(props: ChannelProviderProps<S>): ReactNode;
+/**
+ * Access the typed IPC channel from context.
+ *
+ * Must be called inside a {@link ChannelProvider}. Throws if the
+ * provider is missing.
+ *
+ * @example
+ * ```tsx
+ * import { useChannel } from "@nativewindow/react";
+ *
+ * type Events = { counter: number; title: string };
+ *
+ * function StatusBar() {
+ *   const channel = useChannel<Events>();
+ *   channel.send("counter", 1);
+ * }
+ * ```
+ */
+export declare function useChannel<T extends EventMap = EventMap>(): TypedChannel<T>;
+/**
+ * Subscribe to a specific 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.
+ *
+ * @example
+ * ```tsx
+ * import { useChannelEvent } from "@nativewindow/react";
+ *
+ * type Events = { title: string };
+ *
+ * function TitleDisplay() {
+ *   useChannelEvent<Events, "title">("title", (title) => {
+ *     document.title = title;
+ *   });
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useChannelEvent<T extends EventMap = EventMap, K extends keyof T & string = keyof T & string>(type: K, handler: (payload: T[K]) => void): void;
+/**
+ * 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).
+ *
+ * @example
+ * ```tsx
+ * import { useSend } from "@nativewindow/react";
+ *
+ * type Events = { counter: number; title: string };
+ *
+ * function Counter() {
+ *   const send = useSend<Events>();
+ *   return <button onClick={() => send("counter", 1)}>Increment</button>;
+ * }
+ * ```
+ */
+export declare function useSend<T extends EventMap = EventMap>(): <K extends keyof T & string>(...args: SendArgs<T, K>) => void;
+/**
+ * Options for {@link createChannelHooks}.
+ *
+ * @example
+ * ```tsx
+ * createChannelHooks(schemas, {
+ *   onValidationError: (type, payload) => console.warn(type, payload),
+ * });
+ * ```
+ */
+export interface ChannelHooksOptions {
+    /**
+     * Called when an incoming payload fails schema validation.
+     * If not provided, failed payloads are silently dropped.
+     */
+    onValidationError?: ValidationErrorHandler;
+}
+/**
+ * The set of pre-typed React hooks and provider returned by
+ * {@link createChannelHooks}.
+ *
+ * All hooks are bound to the same internal context and typed to `T`,
+ * so event names and payload types are inferred automatically without
+ * requiring generic type parameters at the call site.
+ */
+export interface TypedChannelHooks<T extends EventMap> {
+    /**
+     * Context provider that creates the channel client once.
+     * Wrap your React app with this at the root.
+     */
+    ChannelProvider: (props: {
+        children: ReactNode;
+    }) => ReactNode;
+    /** Access the typed channel from context. Throws if outside the provider. */
+    useChannel: () => TypedChannel<T>;
+    /** Subscribe to a typed event with automatic cleanup. */
+    useChannelEvent: <K extends keyof T & string>(type: K, handler: (payload: T[K]) => void) => void;
+    /** Returns a stable typed `send` function. */
+    useSend: () => <K extends keyof T & string>(...args: SendArgs<T, K>) => void;
+}
+/**
+ * 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: { counter: number; title: string }
+ * const { ChannelProvider, useChannel, useChannelEvent, useSend } =
+ *   createChannelHooks({
+ *     counter: z.number(),
+ *     title: z.string(),
+ *   });
+ *
+ * function App() {
+ *   const send = useSend();                        // fully typed
+ *   useChannelEvent("title", (t) => {              // t: string
+ *     document.title = t;
+ *   });
+ *   return <button onClick={() => send("counter", 1)}>+1</button>;
+ * }
+ *
+ * function Root() {
+ *   return (
+ *     <ChannelProvider>
+ *       <App />
+ *     </ChannelProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function createChannelHooks<S extends SchemaMap>(schemas: S, options?: ChannelHooksOptions): TypedChannelHooks<InferSchemaMap<S>>;

package/dist/index.js

@@ -0,0 +1,99 @@
+import { createContext, useRef, createElement, useContext, useEffect, useCallback } from "react";
+import { createChannelClient } from "@nativewindow/ipc/client";
+const ChannelContext = createContext(null);
+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);
+}
+function useChannel() {
+  const channel = useContext(ChannelContext);
+  if (channel === null) {
+    throw new Error("useChannel() must be used inside a <ChannelProvider>.");
+  }
+  return channel;
+}
+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]);
+}
+function useSend() {
+  const channel = useChannel();
+  return useCallback(
+    (...args) => {
+      channel.send(...args);
+    },
+    [channel]
+  );
+}
+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
+  };
+}
+export {
+  ChannelProvider,
+  createChannelHooks,
+  useChannel,
+  useChannelEvent,
+  useSend
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nativewindow/react",
+  "version": "0.1.1",
+  "description": "React bindings for native-window IPC (alpha)",
+  "homepage": "https://nativewindow.fcannizzaro.com",
+  "bugs": {
+    "url": "https://github.com/nativewindow/webview/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Francesco Saverio Cannizzaro (fcannizzaro)",
+    "url": "https://fcannizzaro.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nativewindow/webview/tree/main/packages/react"
+  },
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/fcannizzaro"
+    }
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.0",
+    "jsdom": "^28.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@nativewindow/ipc": "workspace:*",
+    "react": "^18.0.0 || ^19.0.0",
+    "typescript": "^5"
+  }
+}