@proto-labs-inc/rig 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proto Labs Inc.
+
+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,5 @@
+# @proto-labs-inc/rig
+
+The rig for React prototypes: `<ProtoRig manifest={…}>` at the root, and
+`usePreviewState` / `useVariant` wherever a view reads its state or variant.
+All logic lives in `@proto-labs-inc/rig-core`; this package is the React idiom.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @proto-labs-inc/rig — the React adapter over @proto-labs-inc/rig-core. All rig logic
+ * (URL-state sync, the bridge, comment mode) lives in the core; this file
+ * is only the React idiom: a provider component + hooks.
+ */
+import { type ReactNode } from "react";
+import { type Manifest } from "@proto-labs-inc/wire";
+export declare function ProtoRig({ manifest, children, }: {
+    manifest: Manifest;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The prototype's preview state, addressable as ?state=<id>. */
+export declare function usePreviewState(defaultId: string, validIds?: readonly string[]): readonly [string, (v: string) => void];
+/** A component's design variant, addressable as ?v.<component>=<id>. */
+export declare function useVariant(component: string, defaultVariant: string, validIds?: readonly string[]): readonly [string, (v: string) => void];

package/dist/index.js

@@ -0,0 +1,132 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @proto-labs-inc/rig — the React adapter over @proto-labs-inc/rig-core. All rig logic
+ * (URL-state sync, the bridge, comment mode) lives in the core; this file
+ * is only the React idiom: a provider component + hooks.
+ */
+import { createContext, useCallback, useContext, useEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { postToFrame, RigStore, wireRig, STATE_PARAM, variantParam, } from "@proto-labs-inc/rig-core";
+import { isFrameToRig } from "@proto-labs-inc/wire";
+const RigContext = createContext(null);
+const PROTO_BLUE = "#0088FF";
+function TargetHighlight({ focus, onDismiss, }) {
+    const [rect, setRect] = useState(null);
+    useEffect(() => {
+        let didScroll = false;
+        const update = () => {
+            const target = document.querySelector(`[data-proto-id="${CSS.escape(focus.id)}"]`);
+            if (!target) {
+                setRect(null);
+                postToFrame({
+                    type: "target-measured",
+                    targetId: focus.id,
+                    anchor: null,
+                });
+                return;
+            }
+            if (!didScroll) {
+                target.scrollIntoView({
+                    behavior: "smooth",
+                    block: "center",
+                    inline: "nearest",
+                });
+                didScroll = true;
+            }
+            const nextRect = target.getBoundingClientRect();
+            setRect(nextRect);
+            postToFrame({
+                type: "target-measured",
+                targetId: focus.id,
+                anchor: {
+                    x: nextRect.left,
+                    y: nextRect.top,
+                    width: nextRect.width,
+                    height: nextRect.height,
+                },
+            });
+        };
+        update();
+        const retry = window.setInterval(update, 50);
+        const stopRetry = window.setTimeout(() => window.clearInterval(retry), 400);
+        window.addEventListener("scroll", update, true);
+        window.addEventListener("resize", update);
+        // Dismiss before the prototype handles the interaction. A pointer-down can
+        // replace the focused target before a click is dispatched, which removes
+        // the visual highlight without giving the Frame a chance to clear its
+        // associated selection.
+        document.addEventListener("pointerdown", onDismiss, true);
+        return () => {
+            window.clearInterval(retry);
+            window.clearTimeout(stopRetry);
+            window.removeEventListener("scroll", update, true);
+            window.removeEventListener("resize", update);
+            document.removeEventListener("pointerdown", onDismiss, true);
+        };
+    }, [focus, onDismiss]);
+    if (!rect)
+        return null;
+    return (_jsx("div", { "aria-hidden": "true", "data-proto-target-highlight": true, style: {
+            position: "fixed",
+            zIndex: 2147483647,
+            pointerEvents: "none",
+            top: rect.top,
+            left: rect.left,
+            width: rect.width,
+            height: rect.height,
+            border: `2px solid color-mix(in srgb, ${PROTO_BLUE} 55%, transparent)`,
+            borderRadius: 9,
+            background: `color-mix(in srgb, ${PROTO_BLUE} 6%, transparent)`,
+            opacity: 1,
+        } }));
+}
+export function ProtoRig({ manifest, children, }) {
+    // One store per mount; survives re-renders, resets on full reload (correct:
+    // a reload re-hydrates from the URL, which is the source of truth).
+    const storeRef = useRef(null);
+    if (storeRef.current === null)
+        storeRef.current = new RigStore(manifest);
+    const store = storeRef.current;
+    const [targetFocus, setTargetFocus] = useState(null);
+    useEffect(() => {
+        const onMessage = (e) => {
+            if (!isFrameToRig(e.data) || e.data.type !== "focus-target")
+                return;
+            if (e.data.id === null) {
+                setTargetFocus(null);
+                return;
+            }
+            setTargetFocus((current) => ({
+                id: e.data.id,
+                token: (current?.token ?? 0) + 1,
+            }));
+        };
+        window.addEventListener("message", onMessage);
+        const dispose = wireRig(store, manifest);
+        return () => {
+            window.removeEventListener("message", onMessage);
+            dispose();
+        };
+    }, [store, manifest]);
+    return (_jsxs(RigContext.Provider, { value: store, children: [children, targetFocus ? (_jsx(TargetHighlight, { focus: targetFocus, onDismiss: () => {
+                    setTargetFocus((current) => current?.token === targetFocus.token ? null : current);
+                    postToFrame({ type: "target-focus-dismissed" });
+                } })) : null] }));
+}
+function useRigValue(key, fallback, valid) {
+    const store = useContext(RigContext);
+    if (!store)
+        throw new Error("useRig* hooks require a <ProtoRig> ancestor");
+    const raw = useSyncExternalStore(store.subscribe, () => store.get(key) ?? fallback, () => fallback);
+    const value = valid && !valid.includes(raw) ? fallback : raw;
+    const set = useCallback((v) => store.set(key, v), [store, key]);
+    return [value, set];
+}
+/** The prototype's preview state, addressable as ?state=<id>. */
+export function usePreviewState(defaultId, validIds) {
+    return useRigValue(STATE_PARAM, defaultId, validIds);
+}
+/** A component's design variant, addressable as ?v.<component>=<id>. */
+export function useVariant(component, defaultVariant, validIds) {
+    return useRigValue(variantParam(component), defaultVariant, validIds);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@proto-labs-inc/rig",
+  "version": "0.1.0",
+  "description": "Proto's rig for React prototypes: a provider and hooks over @proto-labs-inc/rig-core.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proto-labs-inc/proto.git",
+    "directory": "packages/rig"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@proto-labs-inc/wire": "^0.1.0",
+    "@proto-labs-inc/rig-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2",
+    "react": "19.3.0",
+    "@types/react": "^19.2.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}