@liquiddom/react 0.2.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @liquiddom/react
+
+## 0.2.0-rc.0
+
+### Minor Changes
+
+Initial public release. React 18+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom).
+
+**Exports:**
+- `<LiquidProvider config?>` — owns a `LiquidDOMInstance` via React Context
+- `useLiquid()` — read the instance (returns `null` before init / outside provider)
+- `useLiquidRef<T>(opts?)` — callback ref that auto-observes/unobserves
+- `<LiquidElement as? liquidType? ...rest>` — drop-in tag wrapping `useLiquidRef`
+
+**Behavior:**
+- Strict-mode safe (idempotent observe — React 18 double-mount in dev does not double-register)
+- SSR-safe (provider effect gated on `typeof window`)
+- `liquiddom` is a peer dependency (single WASM instance shared across the app)
+
+### Peer dependencies
+
+- `liquiddom@^0.2.0-rc.0`
+- `react@^18.0.0 || ^19.0.0`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dennis Schmock
+
+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,96 @@
+# @liquiddom/react
+
+React 18+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom) — WASM-driven soft-body physics on real DOM elements.
+
+## Install
+
+```bash
+npm install liquiddom @liquiddom/react react react-dom
+```
+
+`liquiddom` is a peer dependency so a single WASM instance is shared across your app.
+
+## Quickstart
+
+```tsx
+import { LiquidProvider, LiquidElement } from "@liquiddom/react";
+
+export default function App() {
+  return (
+    <LiquidProvider config={{ capacity: 16, theme: { fusionRadius: 50 } }}>
+      <LiquidElement as="button">Click me</LiquidElement>
+      <LiquidElement as="a" href="#">Also liquid</LiquidElement>
+    </LiquidProvider>
+  );
+}
+```
+
+## Three usage patterns
+
+### 1. `<LiquidElement>` — drop-in tag
+
+Easiest. Wraps `useLiquidRef` and observes on mount.
+
+```tsx
+<LiquidElement as="button" liquidType={4 /* Shake */}>
+  Shaky
+</LiquidElement>
+```
+
+### 2. `useLiquidRef` — ref on your own element
+
+When you need full control over the element (custom components, third-party libs).
+
+```tsx
+import { useLiquidRef } from "@liquiddom/react";
+
+function Card() {
+  const ref = useLiquidRef<HTMLDivElement>({ liquidType: 3 /* Dragged */ });
+  return <div ref={ref} className="my-card">Drag me</div>;
+}
+```
+
+### 3. `useLiquid` — imperative access
+
+For one-off actions like `impulse()`, `tween()`, `spawnDroplet()`.
+
+```tsx
+import { useLiquid, useLiquidRef } from "@liquiddom/react";
+
+function Button() {
+  const liquid = useLiquid();
+  const ref = useLiquidRef<HTMLButtonElement>();
+
+  return (
+    <button
+      ref={ref}
+      onClick={() => liquid?.impulse(ref.current!, { magnitude: 20 })}
+    >
+      Splash me
+    </button>
+  );
+}
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `<LiquidProvider config?>` | Owns a `LiquidDOMInstance` via React Context. `config` is captured once on mount — re-renders don't re-create the instance. |
+| `useLiquid()` | Returns the active instance, or `null` before init / outside a provider. |
+| `useLiquidRef<T>(opts?)` | Callback ref that auto-observes on mount, unobserves on unmount. `opts.liquidType` captured at first attach. |
+| `<LiquidElement as? liquidType? ...rest>` | Convenience tag — internally uses `useLiquidRef`. Forwards all other props to the underlying element. |
+
+## Notes
+
+- **Strict-mode safe** — `useLiquidRef` observes idempotently, so React 18's double-mount in dev doesn't double-register.
+- **SSR-safe** — the provider effect is gated on `typeof window`, so server rendering is a no-op.
+- **Single instance per provider** — nested providers each spin up their own WASM instance. For most apps, one provider at the root is correct.
+
+## Full options + imperative API
+
+All options and methods exposed via `config` and `useLiquid()` come straight from [`liquiddom`'s core API](https://www.npmjs.com/package/liquiddom).
+
+## License
+
+[MIT](./LICENSE) © Dennis Schmock

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @liquiddom/react — React 18+ bindings.
+ */
+import { type ReactNode, type RefCallback, type HTMLAttributes } from "react";
+import { type LiquidDOMInstance, type LiquidOptions } from "liquiddom";
+/** Context value: the live instance, or null before init / after destroy. */
+export declare const LiquidContext: import("react").Context<LiquidDOMInstance | null>;
+/** Provider props. `config` is read ONCE on mount; subsequent changes are ignored. */
+export interface LiquidProviderProps {
+    config?: LiquidOptions;
+    children: ReactNode;
+}
+export declare function LiquidProvider({ config, children }: LiquidProviderProps): JSX.Element;
+/** Read the live instance from context. Null before init / outside a provider. */
+export declare function useLiquid(): LiquidDOMInstance | null;
+export interface UseLiquidRefOptions {
+    liquidType?: number;
+}
+/**
+ * Callback ref that auto-observes the attached element. Safe to use before
+ * the provider's instance is ready — observation deferred via state-trigger
+ * pattern (effect re-runs when `instance` becomes available).
+ *
+ * Strict-mode safe: cleanup unobserves, remount re-observes; `observe` is
+ * idempotent (W14 invariant).
+ *
+ * Closure-capture: the effect cleanup captures `el` and `instance` at the
+ * time the effect ran. A later `setEl(null)` does NOT change which element
+ * the captured cleanup unobserves.
+ */
+export declare function useLiquidRef<T extends HTMLElement>(opts?: UseLiquidRefOptions): RefCallback<T>;
+export interface LiquidElementProps {
+    as?: keyof JSX.IntrinsicElements;
+    liquidType?: number;
+    children?: ReactNode;
+}
+/**
+ * Convenience component: renders the chosen tag (default `div`) and auto-
+ * observes it via `useLiquidRef`. All HTML attributes are forwarded via spread.
+ *
+ * Polymorphic typing is intentionally loose for v1 — props are typed as
+ * `HTMLAttributes<HTMLElement>` so most common attributes typecheck across
+ * tags. Tag-specific attributes (`type` on input, `disabled` on button) may
+ * require a cast. Full polymorphic typing deferred to a follow-up ward.
+ */
+export declare function LiquidElement(props: LiquidElementProps & HTMLAttributes<HTMLElement>): JSX.Element;

package/dist/index.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @liquiddom/react — React 18+ bindings.
+ */
+import { createContext, useContext, useEffect, useRef, useState, } from "react";
+import { LiquidDOM, } from "liquiddom";
+/** Context value: the live instance, or null before init / after destroy. */
+export const LiquidContext = createContext(null);
+export function LiquidProvider({ config, children }) {
+    const [instance, setInstance] = useState(null);
+    const configRef = useRef(config);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return; // SSR guard — never runs server-side
+        let cancelled = false;
+        let created = null;
+        LiquidDOM.create(configRef.current)
+            .then((inst) => {
+            if (cancelled) {
+                // Provider unmounted (or strict-mode cleanup) before create resolved.
+                inst.destroy();
+                return;
+            }
+            created = inst;
+            setInstance(inst);
+        })
+            .catch((err) => {
+            console.error("[liquiddom/react] LiquidProvider failed to create instance:", err);
+        });
+        return () => {
+            cancelled = true;
+            if (created)
+                created.destroy();
+            // No setInstance(null) on unmount — context is going away regardless,
+            // and post-unmount state updates generate noise in test output.
+        };
+    }, []); // empty deps — config captured by ref, ignored after mount
+    return _jsx(LiquidContext.Provider, { value: instance, children: children });
+}
+/** Read the live instance from context. Null before init / outside a provider. */
+export function useLiquid() {
+    return useContext(LiquidContext);
+}
+/**
+ * Callback ref that auto-observes the attached element. Safe to use before
+ * the provider's instance is ready — observation deferred via state-trigger
+ * pattern (effect re-runs when `instance` becomes available).
+ *
+ * Strict-mode safe: cleanup unobserves, remount re-observes; `observe` is
+ * idempotent (W14 invariant).
+ *
+ * Closure-capture: the effect cleanup captures `el` and `instance` at the
+ * time the effect ran. A later `setEl(null)` does NOT change which element
+ * the captured cleanup unobserves.
+ */
+export function useLiquidRef(opts) {
+    const instance = useLiquid();
+    const [el, setEl] = useState(null);
+    const liquidType = opts?.liquidType;
+    useEffect(() => {
+        if (!el || !instance)
+            return;
+        instance.observe(el, liquidType);
+        return () => {
+            instance.unobserve(el);
+        };
+    }, [el, instance, liquidType]);
+    return setEl;
+}
+/**
+ * Convenience component: renders the chosen tag (default `div`) and auto-
+ * observes it via `useLiquidRef`. All HTML attributes are forwarded via spread.
+ *
+ * Polymorphic typing is intentionally loose for v1 — props are typed as
+ * `HTMLAttributes<HTMLElement>` so most common attributes typecheck across
+ * tags. Tag-specific attributes (`type` on input, `disabled` on button) may
+ * require a cast. Full polymorphic typing deferred to a follow-up ward.
+ */
+export function LiquidElement(props) {
+    const { as, liquidType, children, ...rest } = props;
+    const ref = useLiquidRef({ liquidType });
+    const Tag = (as ?? "div");
+    return (_jsx(Tag, { ref: ref, ...rest, children: children }));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@liquiddom/react",
+  "version": "0.2.0-rc.0",
+  "description": "React bindings for liquiddom",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "liquiddom": "^0.2.0-rc.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "author": "Dennis Schmock",
+  "license": "MIT",
+  "homepage": "https://github.com/boringreliability/liquiddom/tree/master/packages/react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boringreliability/liquiddom.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/boringreliability/liquiddom/issues"
+  },
+  "keywords": [
+    "liquiddom",
+    "react",
+    "wasm",
+    "physics",
+    "animation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}