@usemote/react 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Heavenson
+
+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

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @usemote/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React binding for [Mote](https://mote.hearvie.dev). **627 B** brotlied.
+
+```bash
+pnpm add @usemote/core @usemote/react
+```
+
+```tsx
+import { FloatingField } from '@usemote/react';
+
+<section style={{ position: 'relative', overflow: 'hidden' }}>
+  <FloatingField mode="bob" set="geo" count={12} avoid="center" depth />
+  <h1 style={{ position: 'relative' }}>Your headline</h1>
+</section>
+```
+
+**The field is a layer.** It fills its nearest positioned ancestor, so that
+parent needs `position: relative`, and content above it needs
+`position: relative` too — otherwise the shapes cover it.
+
+## SSR
+
+Works in Next.js app router and anywhere else. The server renders frame 0, the
+client renders the identical markup, so there is no hydration mismatch and no
+flash of an empty section.
+
+If you pass an inline `packs`, `shapes` or `theme` literal, it is compared by
+content rather than identity, so it will not rebuild the field each render. A
+custom `mode` preset object should be memoised.
+
+## Inspiration
+
+Architecturally modelled on **[Navii](https://github.com/uxderrick/navii)** by
+**[Derrick Tsorme](https://github.com/uxderrick)** — a deterministic avatar
+engine, and the reason this project exists. No code is shared; the debt is
+architectural, and it is a large one. If you need avatars, use Navii.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+var core = require('@usemote/core');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/FloatingField.tsx
+var BASE_STYLE = {
+  position: "absolute",
+  inset: 0,
+  overflow: "hidden",
+  pointerEvents: "none"
+};
+function FloatingField({
+  className,
+  style,
+  ssrWidth = 1200,
+  ssrHeight = 600,
+  ...options
+}) {
+  const ref = react.useRef(null);
+  const handle = react.useRef(null);
+  const poolKey = react.useMemo(
+    () => JSON.stringify([
+      options.packs?.map((p) => `${p.id}@${p.version}`) ?? null,
+      options.shapes ?? null,
+      Array.isArray(options.theme) ? options.theme : options.theme ?? null
+    ]),
+    [options.packs, options.shapes, options.theme]
+  );
+  const modeIsObject = typeof options.mode === "object";
+  react.useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    handle.current = core.createField(el, options);
+    return () => {
+      handle.current?.destroy();
+      handle.current = null;
+    };
+  }, [
+    poolKey,
+    options.seed,
+    options.count,
+    options.size,
+    options.set,
+    options.depth,
+    options.direction,
+    modeIsObject ? "custom" : options.mode
+  ]);
+  react.useEffect(() => {
+    const live = {};
+    if (options.speed !== void 0) live.speed = options.speed;
+    if (options.interactive !== void 0) live.interactive = options.interactive;
+    if (options.avoid !== void 0) live.avoid = options.avoid;
+    if (options.paused !== void 0) live.paused = options.paused;
+    handle.current?.update(live);
+  }, [options.speed, options.interactive, options.avoid, options.paused]);
+  const ssrHTML = react.useMemo(
+    () => core.renderFieldHTML({ ...options, width: ssrWidth, height: ssrHeight }),
+    [poolKey, options.seed, options.count, options.size, options.set, options.depth, ssrWidth, ssrHeight]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      ref,
+      className,
+      "aria-hidden": "true",
+      style: { ...BASE_STYLE, ...style },
+      dangerouslySetInnerHTML: { __html: ssrHTML }
+    }
+  );
+}
+
+exports.FloatingField = FloatingField;

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import { FieldOptions } from '@usemote/core';
+import { CSSProperties, ReactElement } from 'react';
+
+/**
+ * <FloatingField /> — a thin React wrapper around `createField`.
+ *
+ * Deliberately thin: all logic lives in @usemote/core so there is one
+ * implementation to maintain and test across every framework wrapper.
+ *
+ * SSR works by rendering core's frame-0 markup via `dangerouslySetInnerHTML`.
+ * Because layout is a pure function of (seed, options), the server and client
+ * agree exactly, so there is no hydration mismatch and no first-paint flash of
+ * an empty section. On mount the field adopts that existing markup rather than
+ * throwing it away.
+ */
+
+interface FloatingFieldProps extends FieldOptions {
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Size used for the server-rendered frame. Only affects the pre-hydration
+     * paint; the client re-measures its real box on mount.
+     */
+    ssrWidth?: number;
+    ssrHeight?: number;
+}
+declare function FloatingField({ className, style, ssrWidth, ssrHeight, ...options }: FloatingFieldProps): ReactElement;
+
+export { FloatingField, type FloatingFieldProps };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { FieldOptions } from '@usemote/core';
+import { CSSProperties, ReactElement } from 'react';
+
+/**
+ * <FloatingField /> — a thin React wrapper around `createField`.
+ *
+ * Deliberately thin: all logic lives in @usemote/core so there is one
+ * implementation to maintain and test across every framework wrapper.
+ *
+ * SSR works by rendering core's frame-0 markup via `dangerouslySetInnerHTML`.
+ * Because layout is a pure function of (seed, options), the server and client
+ * agree exactly, so there is no hydration mismatch and no first-paint flash of
+ * an empty section. On mount the field adopts that existing markup rather than
+ * throwing it away.
+ */
+
+interface FloatingFieldProps extends FieldOptions {
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Size used for the server-rendered frame. Only affects the pre-hydration
+     * paint; the client re-measures its real box on mount.
+     */
+    ssrWidth?: number;
+    ssrHeight?: number;
+}
+declare function FloatingField({ className, style, ssrWidth, ssrHeight, ...options }: FloatingFieldProps): ReactElement;
+
+export { FloatingField, type FloatingFieldProps };

package/dist/index.js

@@ -0,0 +1,72 @@
+import { createField, renderFieldHTML } from '@usemote/core';
+import { useRef, useMemo, useEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/FloatingField.tsx
+var BASE_STYLE = {
+  position: "absolute",
+  inset: 0,
+  overflow: "hidden",
+  pointerEvents: "none"
+};
+function FloatingField({
+  className,
+  style,
+  ssrWidth = 1200,
+  ssrHeight = 600,
+  ...options
+}) {
+  const ref = useRef(null);
+  const handle = useRef(null);
+  const poolKey = useMemo(
+    () => JSON.stringify([
+      options.packs?.map((p) => `${p.id}@${p.version}`) ?? null,
+      options.shapes ?? null,
+      Array.isArray(options.theme) ? options.theme : options.theme ?? null
+    ]),
+    [options.packs, options.shapes, options.theme]
+  );
+  const modeIsObject = typeof options.mode === "object";
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    handle.current = createField(el, options);
+    return () => {
+      handle.current?.destroy();
+      handle.current = null;
+    };
+  }, [
+    poolKey,
+    options.seed,
+    options.count,
+    options.size,
+    options.set,
+    options.depth,
+    options.direction,
+    modeIsObject ? "custom" : options.mode
+  ]);
+  useEffect(() => {
+    const live = {};
+    if (options.speed !== void 0) live.speed = options.speed;
+    if (options.interactive !== void 0) live.interactive = options.interactive;
+    if (options.avoid !== void 0) live.avoid = options.avoid;
+    if (options.paused !== void 0) live.paused = options.paused;
+    handle.current?.update(live);
+  }, [options.speed, options.interactive, options.avoid, options.paused]);
+  const ssrHTML = useMemo(
+    () => renderFieldHTML({ ...options, width: ssrWidth, height: ssrHeight }),
+    [poolKey, options.seed, options.count, options.size, options.set, options.depth, ssrWidth, ssrHeight]
+  );
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      className,
+      "aria-hidden": "true",
+      style: { ...BASE_STYLE, ...style },
+      dangerouslySetInnerHTML: { __html: ssrHTML }
+    }
+  );
+}
+
+export { FloatingField };

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@usemote/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "React component for Mote — deterministic floating-shape background fields.",
+  "license": "MIT",
+  "author": {
+    "name": "George Heavenson",
+    "url": "https://hearvie.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oti-adjei/mote.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://mote.hearvie.dev",
+  "bugs": "https://github.com/oti-adjei/mote/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "3 kB"
+    }
+  ],
+  "peerDependencies": {
+    "@usemote/core": "^0.1.1",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@usemote/core": "0.1.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@testing-library/react": "^16.3.0",
+    "happy-dom": "^20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "size": "size-limit"
+  }
 }