@the-link/react 0.1.0 → 0.2.0

package/README.md

@@ -1,4 +1,68 @@
-# React
+# The Link React
 
-React bindings for The Link.
+React bindings for Core tunnels and synchronized properties. The package keeps
+the underlying Link objects authoritative and uses React only to subscribe and
+render their current values.
 
+## Install
+
+```sh
+npm install @the-link/react @the-link/core react
+```
+
+## Tunnel events
+
+`ReactTunnel.useFactory()` keeps one wrapper for a tunnel reference. Its hooks
+subscribe with React lifecycle cleanup.
+
+```tsx
+import { ReactTunnel } from "@the-link/react"
+import type { Tunnel } from "@the-link/core"
+
+export function Status({ tunnel }: { tunnel: Tunnel }) {
+    const events = ReactTunnel.useFactory(tunnel)
+    const status = events.useFirstState("status:changed", "idle")
+
+    return <span>{status}</span>
+}
+```
+
+Use `useState(event, initialTuple)` when every event value is needed, or
+`useSubscribe(event, handler)` for an effect-style subscription. As with React
+hooks generally, call these methods unconditionally while rendering a component.
+
+## Properties
+
+`useProperty()` reads a Core `Property` through `useSyncExternalStore`. The
+property remains the source of truth; React does not maintain a second copy.
+
+```tsx
+import { useProperty } from "@the-link/react"
+import type { Property } from "@the-link/core"
+
+export function Theme({ property }: { property: Property<string> }) {
+    const theme = useProperty(property)
+
+    return <span>{theme}</span>
+}
+```
+
+## Entry points
+
+| Import | Contract |
+| --- | --- |
+| `@the-link/react` | `ReactTunnel` and `useProperty()` |
+
+React and `@the-link/core` are peer dependencies, so the application owns their
+instances.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run verify
+```
+
+## License
+
+MIT

package/dist/property-hook.d.ts

@@ -1,4 +1,4 @@
-import Property from "@the-link/core/property";
+import { Property } from "@the-link/core";
 /**
  * React hook for reading a Property value reactively.
  *
@@ -18,4 +18,4 @@ import Property from "@the-link/core/property";
  * }
  * ```
  */
-export default function useProperty<Value>(property: Property<Value>): Value;
+export declare function useProperty<Value>(property: Property<Value>): Value;

package/dist/property-hook.js

@@ -18,7 +18,7 @@ import { useCallback, useSyncExternalStore } from "react";
  * }
  * ```
  */
-export default function useProperty(property) {
+export 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

@@ -1,4 +1,4 @@
-import Tunnel, { Subscriber } from "@the-link/core/tunnel";
+import { Tunnel, type Subscriber } from "@the-link/core";
 /**
  * React hook helper for a Tunnel instance.
  *
@@ -16,7 +16,7 @@ import Tunnel, { Subscriber } from "@the-link/core/tunnel";
  * }
  * ```
  */
-export default class ReactTunnel {
+export declare class ReactTunnel {
     /**
      * Tunnel instance used by the React hook helpers.
      */

package/dist/react-tunnel.js

@@ -16,7 +16,7 @@ import { useCallback, useEffect, useMemo, useState } from "react";
  * }
  * ```
  */
-export default class ReactTunnel {
+export class ReactTunnel {
     /**
      * Tunnel instance used by the React hook helpers.
      */

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+export { ReactTunnel } from "./react-tunnel.js";
+export { useProperty } from "./property-hook.js";

package/dist/react.js

@@ -0,0 +1,2 @@
+export { ReactTunnel } from "./react-tunnel.js";
+export { useProperty } from "./property-hook.js";

package/package.json

@@ -1,19 +1,15 @@
 {
   "name": "@the-link/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React bindings for The Link.",
   "type": "module",
   "sideEffects": false,
-  "main": "dist/react-tunnel.js",
-  "types": "dist/react-tunnel.d.ts",
+  "main": "dist/react.js",
+  "types": "dist/react.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"
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
     }
   },
   "files": ["dist", "LICENSE", "README.md"],
@@ -38,11 +34,11 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@the-link/core": "^0.1.0",
+    "@the-link/core": "^0.2.0",
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@the-link/core": "^0.1.0",
+    "@the-link/core": "^0.2.0",
     "@types/react": "^19.2.18",
     "react": "^19.2.8",
     "typescript": "^6.0.3"