@nativewindow/react 0.1.1 → 1.0.1

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.d.ts

@@ -17,8 +17,8 @@ import { EventMap, SendArgs, SchemaMap, InferSchemaMap, TypedChannel, Validation
  *
  * const { ChannelProvider, useChannel, useChannelEvent, useSend } =
  *   createChannelHooks({
- *     counter: z.number(),
- *     title: z.string(),
+ *     host: { title: z.string() },
+ *     client: { counter: z.number() },
  *   });
  *
  * function App() {
@@ -45,14 +45,21 @@ export type { ChannelClientOptions } from '../ipc/client.ts';
  *
  * @example
  * ```tsx
- * <ChannelProvider schemas={schemas}>
+ * <ChannelProvider schemas={{ host: hostSchemas, client: clientSchemas }}>
  *   <App />
  * </ChannelProvider>
  * ```
  */
-export interface ChannelProviderProps<S extends SchemaMap> {
-    /** Schemas for each event. Provides both TypeScript types and runtime validation. */
-    schemas: S;
+export interface ChannelProviderProps<H extends SchemaMap, C extends SchemaMap> {
+    /**
+     * Directional schemas for the channel.
+     * - `host`: events the host sends to the client (validated on receive).
+     * - `client`: events the client sends to the host (type-checked on send).
+     */
+    schemas: {
+        host: H;
+        client: C;
+    };
     /**
      * Called when an incoming payload fails schema validation.
      * If not provided, failed payloads are silently dropped.
@@ -74,8 +81,8 @@ export interface ChannelProviderProps<S extends SchemaMap> {
  * import { ChannelProvider } from "@nativewindow/react";
  *
  * const schemas = {
- *   counter: z.number(),
- *   title: z.string(),
+ *   host: { title: z.string() },
+ *   client: { counter: z.number() },
  * };
  *
  * function Root() {
@@ -87,67 +94,76 @@ export interface ChannelProviderProps<S extends SchemaMap> {
  * }
  * ```
  */
-export declare function ChannelProvider<S extends SchemaMap>(props: ChannelProviderProps<S>): ReactNode;
+export declare function ChannelProvider<H extends SchemaMap, C extends SchemaMap>(props: ChannelProviderProps<H, C>): ReactNode;
 /**
  * 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 Events = { counter: number; title: string };
+ * type ClientEvents = { counter: number };
+ * type HostEvents = { title: string };
  *
  * function StatusBar() {
- *   const channel = useChannel<Events>();
+ *   const channel = useChannel<ClientEvents, HostEvents>();
  *   channel.send("counter", 1);
  * }
  * ```
  */
-export declare function useChannel<T extends EventMap = EventMap>(): TypedChannel<T>;
+export declare function useChannel<Send extends EventMap = EventMap, Receive extends EventMap = EventMap>(): TypedChannel<Send, Receive>;
 /**
- * Subscribe to a specific IPC event type with automatic cleanup.
+ * 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 Events = { title: string };
+ * type HostEvents = { title: string };
  *
  * function TitleDisplay() {
- *   useChannelEvent<Events, "title">("title", (title) => {
+ *   useChannelEvent<HostEvents, "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;
+export declare function useChannelEvent<Receive extends EventMap = EventMap, K extends keyof Receive & string = keyof Receive & string>(type: K, handler: (payload: Receive[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).
  *
+ * @typeParam Send - The event map for outgoing (sendable) events.
+ *
  * @example
  * ```tsx
  * import { useSend } from "@nativewindow/react";
  *
- * type Events = { counter: number; title: string };
+ * type ClientEvents = { counter: number };
  *
  * function Counter() {
- *   const send = useSend<Events>();
+ *   const send = useSend<ClientEvents>();
  *   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;
+export declare function useSend<Send extends EventMap = EventMap>(): <K extends keyof Send & string>(...args: SendArgs<Send, K>) => void;
 /**
  * Options for {@link createChannelHooks}.
  *
@@ -169,11 +185,15 @@ export interface ChannelHooksOptions {
  * 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.
+ * All hooks are bound to the same internal context and typed with
+ * separate Send/Receive maps, so event names and payload types are
+ * inferred automatically without requiring generic type parameters
+ * at the call site.
+ *
+ * @typeParam Send - Events the client sends to the host.
+ * @typeParam Receive - Events the client receives from the host.
  */
-export interface TypedChannelHooks<T extends EventMap> {
+export interface TypedChannelHooks<Send extends EventMap, Receive extends EventMap> {
     /**
      * Context provider that creates the channel client once.
      * Wrap your React app with this at the root.
@@ -182,11 +202,11 @@ export interface TypedChannelHooks<T extends EventMap> {
         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;
+    useChannel: () => TypedChannel<Send, Receive>;
+    /** Subscribe to a typed incoming (host) event with automatic cleanup. */
+    useChannelEvent: <K extends keyof Receive & string>(type: K, handler: (payload: Receive[K]) => void) => void;
+    /** Returns a stable typed `send` function for outgoing (client) events. */
+    useSend: () => <K extends keyof Send & string>(...args: SendArgs<Send, K>) => void;
 }
 /**
  * Create a set of pre-typed React hooks for the IPC channel.
@@ -200,16 +220,16 @@ export interface TypedChannelHooks<T extends EventMap> {
  * import { z } from "zod";
  * import { createChannelHooks } from "@nativewindow/react";
  *
- * // Types are inferred: { counter: number; title: string }
+ * // Types are inferred from directional schemas
  * const { ChannelProvider, useChannel, useChannelEvent, useSend } =
  *   createChannelHooks({
- *     counter: z.number(),
- *     title: z.string(),
+ *     host: { title: z.string() },
+ *     client: { counter: z.number() },
  *   });
  *
  * function App() {
- *   const send = useSend();                        // fully typed
- *   useChannelEvent("title", (t) => {              // t: string
+ *   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>;
@@ -224,4 +244,7 @@ export interface TypedChannelHooks<T extends EventMap> {
  * }
  * ```
  */
-export declare function createChannelHooks<S extends SchemaMap>(schemas: S, options?: ChannelHooksOptions): TypedChannelHooks<InferSchemaMap<S>>;
+export declare function createChannelHooks<H extends SchemaMap, C extends SchemaMap>(schemas: {
+    host: H;
+    client: C;
+}, options?: ChannelHooksOptions): TypedChannelHooks<InferSchemaMap<C>, InferSchemaMap<H>>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nativewindow/react",
-  "version": "0.1.1",
-  "description": "React bindings for native-window IPC (alpha)",
+  "version": "1.0.1",
+  "description": "React bindings for native-window IPC (beta)",
   "homepage": "https://nativewindow.fcannizzaro.com",
   "bugs": {
     "url": "https://github.com/nativewindow/webview/issues"