@liquiddom/vue 0.2.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @liquiddom/vue
+
+## 0.2.0-rc.0
+
+### Minor Changes
+
+Initial public release. Vue 3.4+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom).
+
+**Exports:**
+- `<LiquidProvider :config>` — owns a `LiquidDOMInstance` via provide/inject
+- `LiquidPlugin` — alternative install via `app.use(LiquidPlugin, config?)`
+- `useLiquid()` — returns `Ref<LiquidDOMInstance | null>` (reactive)
+- `useLiquidRef<T>(opts?)` — template ref that auto-observes/unobserves
+- `<LiquidElement :as :liquid-type ...attrs>` — drop-in tag wrapping `useLiquidRef`
+
+**Behavior:**
+- SSR-safe (provider effect gated on `typeof window`)
+- Pure TypeScript with `h()` render functions — no `.vue` SFC dependency in the published package
+- `liquidType` is captured once on first attach (not reactive)
+- `liquiddom` is a peer dependency (single WASM instance shared across the app)
+
+### Peer dependencies
+
+- `liquiddom@^0.2.0-rc.0`
+- `vue@^3.4.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,115 @@
+# @liquiddom/vue
+
+Vue 3.4+ bindings for [`liquiddom`](https://www.npmjs.com/package/liquiddom) — WASM-driven soft-body physics on real DOM elements.
+
+## Install
+
+```bash
+npm install liquiddom @liquiddom/vue vue
+```
+
+`liquiddom` is a peer dependency so a single WASM instance is shared across your app.
+
+## Quickstart
+
+```vue
+<script setup lang="ts">
+import { LiquidProvider, LiquidElement } from "@liquiddom/vue";
+</script>
+
+<template>
+  <LiquidProvider :config="{ capacity: 16, theme: { fusionRadius: 50 } }">
+    <LiquidElement as="button">Click me</LiquidElement>
+    <LiquidElement as="a" href="#">Also liquid</LiquidElement>
+  </LiquidProvider>
+</template>
+```
+
+## Three usage patterns
+
+### 1. `<LiquidElement>` — drop-in tag
+
+Easiest. Wraps `useLiquidRef` and observes on mount.
+
+```vue
+<LiquidElement as="button" :liquid-type="4 /* Shake */">
+  Shaky
+</LiquidElement>
+```
+
+### 2. `useLiquidRef` — template ref on your own element
+
+When you need full control over the element.
+
+```vue
+<script setup lang="ts">
+import { useLiquidRef } from "@liquiddom/vue";
+
+const cardRef = useLiquidRef<HTMLDivElement>({ liquidType: 3 /* Dragged */ });
+</script>
+
+<template>
+  <div ref="cardRef" class="my-card">Drag me</div>
+</template>
+```
+
+### 3. `useLiquid` — imperative access
+
+For one-off actions like `impulse()`, `tween()`, `spawnDroplet()`.
+
+```vue
+<script setup lang="ts">
+import { useLiquid, useLiquidRef } from "@liquiddom/vue";
+
+const liquid = useLiquid();
+const buttonRef = useLiquidRef<HTMLButtonElement>();
+
+function splash() {
+  if (liquid.value && buttonRef.value) {
+    liquid.value.impulse(buttonRef.value, { magnitude: 20 });
+  }
+}
+</script>
+
+<template>
+  <button ref="buttonRef" @click="splash">Splash me</button>
+</template>
+```
+
+## Plugin install (alternative to `<LiquidProvider>`)
+
+```ts
+import { createApp } from "vue";
+import { LiquidPlugin } from "@liquiddom/vue";
+import App from "./App.vue";
+
+createApp(App)
+  .use(LiquidPlugin, { capacity: 16 })
+  .mount("#app");
+```
+
+The plugin attaches the instance app-wide; `useLiquid()` works without a surrounding `<LiquidProvider>`. The plugin monkey-patches `app.unmount` for cleanup.
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `<LiquidProvider :config>` | Owns a `LiquidDOMInstance` via provide/inject. `config` captured once on mount. |
+| `LiquidPlugin` | Alternative install via `app.use(LiquidPlugin, config?)`. |
+| `useLiquid()` | Returns `Ref<LiquidDOMInstance \| null>`. Reactive — updates when async create resolves. |
+| `useLiquidRef<T>(opts?)` | Template ref that auto-observes / unobserves across lifecycle. Internal watch uses `flush: "post"` so the element is mounted before observe fires. |
+| `<LiquidElement :as :liquid-type ...attrs>` | Convenience tag. Uses `inheritAttrs: false` + manual spread so class/style/events/data-* forward correctly. |
+
+## Notes
+
+- **SSR-safe** — provider effect gated on `typeof window`; `useLiquidRef`'s watch doesn't fire on the server.
+- **No `.vue` SFC dependency in the package** — adapter is pure TypeScript using `h()` render functions, so it can be consumed without `vite-plugin-vue` configured for `node_modules`.
+- **`liquidType` is captured at first attach** — `:liquid-type="reactive"` looks reactive but is read once. Change requires re-mount.
+
+## 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,56 @@
+/**
+ * @liquiddom/vue — Vue 3.4+ bindings.
+ */
+import { type InjectionKey, type Plugin, type PropType, type Ref } from "vue";
+import { type LiquidDOMInstance, type LiquidOptions } from "liquiddom";
+/** Injection key used by both `<LiquidProvider>` and `LiquidPlugin`. */
+export declare const LiquidKey: InjectionKey<Ref<LiquidDOMInstance | null>>;
+export declare const LiquidProvider: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    config: {
+        type: PropType<LiquidOptions>;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    config: {
+        type: PropType<LiquidOptions>;
+    };
+}>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export declare const LiquidPlugin: Plugin<[LiquidOptions?]>;
+/** Read the live instance from injection. Null ref outside a provider/plugin. */
+export declare function useLiquid(): Ref<LiquidDOMInstance | null>;
+export interface UseLiquidRefOptions {
+    liquidType?: number;
+}
+/**
+ * Template-ref composable: auto-observes when both element and instance are ready.
+ *
+ * `flush: "post"` is required so the watch fires AFTER Vue's DOM commit — observing
+ * earlier would miss the mounted node. `liquidType` is captured once at setup;
+ * changes to a `:liquidType="..."` binding after mount are NOT reactive (v1 limitation).
+ */
+export declare function useLiquidRef<T extends HTMLElement = HTMLElement>(opts?: UseLiquidRefOptions): Ref<T | null>;
+export declare const LiquidElement: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+    liquidType: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    as: {
+        type: StringConstructor;
+        default: string;
+    };
+    liquidType: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    as: string;
+    liquidType: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/index.js

@@ -0,0 +1,112 @@
+/**
+ * @liquiddom/vue — Vue 3.4+ bindings.
+ */
+import { defineComponent, h, inject, onBeforeUnmount, onMounted, provide, ref, watch, } from "vue";
+import { LiquidDOM } from "liquiddom";
+/** Injection key used by both `<LiquidProvider>` and `LiquidPlugin`. */
+export const LiquidKey = Symbol("LiquidDOM");
+export const LiquidProvider = defineComponent({
+    name: "LiquidProvider",
+    props: { config: { type: Object } },
+    setup(props, { slots }) {
+        const instance = ref(null);
+        provide(LiquidKey, instance);
+        let cancelled = false;
+        onMounted(async () => {
+            if (typeof window === "undefined")
+                return;
+            try {
+                const inst = await LiquidDOM.create(props.config);
+                if (cancelled) {
+                    // Race path: unmount fired before create resolved — instance.value
+                    // was never assigned, so this branch owns the destroy.
+                    inst.destroy();
+                    return;
+                }
+                instance.value = inst;
+            }
+            catch (err) {
+                console.error("[liquiddom/vue] LiquidProvider failed to create instance:", err);
+            }
+        });
+        onBeforeUnmount(() => {
+            cancelled = true;
+            instance.value?.destroy();
+            instance.value = null;
+        });
+        return () => slots.default?.();
+    },
+});
+export const LiquidPlugin = {
+    install(app, config) {
+        const instance = ref(null);
+        app.provide(LiquidKey, instance);
+        if (typeof window === "undefined")
+            return;
+        let unmounted = false;
+        LiquidDOM.create(config)
+            .then((inst) => {
+            if (unmounted) {
+                // Race path: app.unmount() fired before create() resolved.
+                // The unmount wrapper below could not destroy because instance.value was still null,
+                // so this branch owns the destroy. Do NOT delete without restoring the symmetric guard.
+                inst.destroy();
+                return;
+            }
+            instance.value = inst;
+        })
+            .catch((err) => {
+            console.error("[liquiddom/vue] LiquidPlugin failed to create instance:", err);
+        });
+        const origUnmount = app.unmount.bind(app);
+        app.unmount = () => {
+            unmounted = true;
+            // Race-symmetric destroy: handles "app.unmount() AFTER create() resolved".
+            // The "BEFORE create() resolved" path is handled in the .then() above. Both
+            // branches are required for full cleanup coverage.
+            instance.value?.destroy();
+            instance.value = null;
+            origUnmount();
+        };
+    },
+};
+/** Read the live instance from injection. Null ref outside a provider/plugin. */
+export function useLiquid() {
+    return inject(LiquidKey, () => ref(null), true);
+}
+/**
+ * Template-ref composable: auto-observes when both element and instance are ready.
+ *
+ * `flush: "post"` is required so the watch fires AFTER Vue's DOM commit — observing
+ * earlier would miss the mounted node. `liquidType` is captured once at setup;
+ * changes to a `:liquidType="..."` binding after mount are NOT reactive (v1 limitation).
+ */
+export function useLiquidRef(opts) {
+    const instance = useLiquid();
+    // Vue's generic Ref<T> erases to Ref<UnwrapRef<T> | null> through `ref()`,
+    // which doesn't structurally match the function signature `Ref<T | null>`.
+    // Casting at the type-construction site keeps the public API contract clean.
+    const elRef = ref(null);
+    const liquidType = opts?.liquidType;
+    watch([elRef, instance], ([el, inst], _prev, onCleanup) => {
+        if (!el || !inst)
+            return;
+        inst.observe(el, liquidType);
+        onCleanup(() => {
+            inst.unobserve(el);
+        });
+    }, { flush: "post" });
+    return elRef;
+}
+export const LiquidElement = defineComponent({
+    name: "LiquidElement",
+    inheritAttrs: false,
+    props: {
+        as: { type: String, default: "div" },
+        liquidType: { type: Number, default: undefined },
+    },
+    setup(props, { slots, attrs }) {
+        const elRef = useLiquidRef({ liquidType: props.liquidType });
+        return () => h(props.as, { ...attrs, ref: elRef }, slots.default?.());
+    },
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@liquiddom/vue",
+  "version": "0.2.0-rc.0",
+  "description": "Vue 3 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",
+    "vue": "^3.4.0"
+  },
+  "author": "Dennis Schmock",
+  "license": "MIT",
+  "homepage": "https://github.com/boringreliability/liquiddom/tree/master/packages/vue#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boringreliability/liquiddom.git",
+    "directory": "packages/vue"
+  },
+  "bugs": {
+    "url": "https://github.com/boringreliability/liquiddom/issues"
+  },
+  "keywords": [
+    "liquiddom",
+    "vue",
+    "vue3",
+    "wasm",
+    "physics",
+    "animation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}