@the-link/react 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Zohayr SLILEH
+
+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,4 @@
+# React
+
+React bindings for The Link.
+

package/dist/property-hook.d.ts

@@ -0,0 +1,21 @@
+import Property from "@the-link/core/property";
+/**
+ * React hook for reading a Property value reactively.
+ *
+ * The Property remains the source of truth. React reads its current snapshot
+ * and subscribes only for invalidation, so there is no mirrored state that can
+ * fall out of step between rendering and effect setup.
+ *
+ * @param property Property instance to synchronize with React state
+ * @returns Current property value, updated when the property publishes `change`
+ *
+ * @example
+ * ```typescript
+ * function ThemeLabel({ theme }: { theme: Property<string> }) {
+ *     const value = useProperty(theme)
+ *
+ *     return <span>{value}</span>
+ * }
+ * ```
+ */
+export default function useProperty<Value>(property: Property<Value>): Value;

package/dist/property-hook.js

@@ -0,0 +1,25 @@
+import { useCallback, useSyncExternalStore } from "react";
+/**
+ * React hook for reading a Property value reactively.
+ *
+ * The Property remains the source of truth. React reads its current snapshot
+ * and subscribes only for invalidation, so there is no mirrored state that can
+ * fall out of step between rendering and effect setup.
+ *
+ * @param property Property instance to synchronize with React state
+ * @returns Current property value, updated when the property publishes `change`
+ *
+ * @example
+ * ```typescript
+ * function ThemeLabel({ theme }: { theme: Property<string> }) {
+ *     const value = useProperty(theme)
+ *
+ *     return <span>{value}</span>
+ * }
+ * ```
+ */
+export default function useProperty(property) {
+    const subscribe = useCallback((changed) => property.tunnel.subscribe("change", changed), [property]);
+    const snapshot = useCallback(() => property.value, [property]);
+    return useSyncExternalStore(subscribe, snapshot, snapshot);
+}

package/dist/react-tunnel.d.ts

@@ -0,0 +1,60 @@
+import Tunnel, { Subscriber } from "@the-link/core/tunnel";
+/**
+ * React hook helper for a Tunnel instance.
+ *
+ * Provides React-friendly subscription and state helpers around Tunnel events.
+ * Subscriptions are registered in effects and cleaned up automatically, while
+ * event payloads can be mirrored into React state for rendering.
+ *
+ * @example
+ * ```typescript
+ * function StatusView({ tunnel }: { tunnel: Tunnel }) {
+ *     const reactTunnel = ReactTunnel.useFactory(tunnel)
+ *     const status = reactTunnel.useFirstState("status:update", "idle")
+ *
+ *     return <span>{status}</span>
+ * }
+ * ```
+ */
+export default class ReactTunnel {
+    /**
+     * Tunnel instance used by the React hook helpers.
+     */
+    readonly tunnel: Tunnel;
+    /**
+     * Initialize a ReactTunnel wrapper around a Tunnel.
+     *
+     * @param tunnel Tunnel instance to integrate with React components
+     */
+    constructor(tunnel: Tunnel);
+    /**
+     * Create a memoized ReactTunnel instance for a Tunnel.
+     *
+     * @param tunnel Tunnel instance to wrap
+     * @returns Stable ReactTunnel wrapper while the Tunnel reference is unchanged
+     */
+    static useFactory(tunnel: Tunnel): ReactTunnel;
+    /**
+     * Subscribe to a Tunnel event with React lifecycle cleanup.
+     *
+     * @param event Event identifier to subscribe to
+     * @param subscriber Handler invoked when the event is published
+     */
+    useSubscribe(event: string, subscriber: Subscriber): void;
+    /**
+     * Mirror a Tunnel event's payload values into React state.
+     *
+     * @param event Event identifier used for state updates
+     * @param defaultResults Initial state values before the event is published
+     * @returns Latest event payload values
+     */
+    useState<Results extends unknown[]>(event: string, defaultResults: Results): Results;
+    /**
+     * Mirror the first value of a Tunnel event payload into React state.
+     *
+     * @param event Event identifier used for state updates
+     * @param defaultResult Initial value before the event is published
+     * @returns Latest first event payload value
+     */
+    useFirstState<Result>(event: string, defaultResult: Result): Result;
+}

package/dist/react-tunnel.js

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+/**
+ * React hook helper for a Tunnel instance.
+ *
+ * Provides React-friendly subscription and state helpers around Tunnel events.
+ * Subscriptions are registered in effects and cleaned up automatically, while
+ * event payloads can be mirrored into React state for rendering.
+ *
+ * @example
+ * ```typescript
+ * function StatusView({ tunnel }: { tunnel: Tunnel }) {
+ *     const reactTunnel = ReactTunnel.useFactory(tunnel)
+ *     const status = reactTunnel.useFirstState("status:update", "idle")
+ *
+ *     return <span>{status}</span>
+ * }
+ * ```
+ */
+export default class ReactTunnel {
+    /**
+     * Tunnel instance used by the React hook helpers.
+     */
+    tunnel;
+    /**
+     * Initialize a ReactTunnel wrapper around a Tunnel.
+     *
+     * @param tunnel Tunnel instance to integrate with React components
+     */
+    constructor(tunnel) {
+        // Store the tunnel used by all helper hooks.
+        this.tunnel = tunnel;
+    }
+    /**
+     * Create a memoized ReactTunnel instance for a Tunnel.
+     *
+     * @param tunnel Tunnel instance to wrap
+     * @returns Stable ReactTunnel wrapper while the Tunnel reference is unchanged
+     */
+    static useFactory(tunnel) {
+        return useMemo(() => new ReactTunnel(tunnel), [tunnel]);
+    }
+    /**
+     * Subscribe to a Tunnel event with React lifecycle cleanup.
+     *
+     * @param event Event identifier to subscribe to
+     * @param subscriber Handler invoked when the event is published
+     */
+    useSubscribe(event, subscriber) {
+        useEffect(() => {
+            // Register on mount or when the event/subscriber pair changes.
+            this.tunnel.subscribe(event, subscriber);
+            // Remove the exact subscriber when React cleans up the effect.
+            return () => this.tunnel.unsubscribe(event, subscriber);
+        }, [event, subscriber]);
+    }
+    /**
+     * Mirror a Tunnel event's payload values into React state.
+     *
+     * @param event Event identifier used for state updates
+     * @param defaultResults Initial state values before the event is published
+     * @returns Latest event payload values
+     */
+    useState(event, defaultResults) {
+        const [results, setResults] = useState(defaultResults);
+        // Store each event publication payload as the next React state value.
+        const subscriber = useCallback((...results) => setResults(results), []);
+        this.useSubscribe(event, subscriber);
+        return results;
+    }
+    /**
+     * Mirror the first value of a Tunnel event payload into React state.
+     *
+     * @param event Event identifier used for state updates
+     * @param defaultResult Initial value before the event is published
+     * @returns Latest first event payload value
+     */
+    useFirstState(event, defaultResult) {
+        return this.useState(event, [defaultResult])[0];
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@the-link/react",
+  "version": "0.1.0",
+  "description": "React bindings for The Link.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/react-tunnel.js",
+  "types": "dist/react-tunnel.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/react-tunnel.d.ts",
+      "default": "./dist/react-tunnel.js"
+    },
+    "./property": {
+      "types": "./dist/property-hook.d.ts",
+      "default": "./dist/property-hook.js"
+    }
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-l-ink/react.git"
+  },
+  "homepage": "https://the-l.ink",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "check": "tsc --noEmit",
+    "build": "node --run clean && tsc",
+    "verify:package": "npm pack --dry-run --ignore-scripts",
+    "verify": "node --run check && node --run build && node --run verify:package",
+    "prepack": "node --run build"
+  },
+  "peerDependencies": {
+    "@the-link/core": "^0.1.0",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@the-link/core": "^0.1.0",
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
+    "typescript": "^6.0.3"
+  }
+}