@unofficialbox/box-open-elements-react 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle @ Unofficial Box
+
+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,72 @@
+# @unofficialbox/box-open-elements-react
+
+Optional React wrappers for [`box-open-elements`](../..) Web Components.
+
+The core package stays framework-agnostic. This adapter is a thin layer that:
+
+1. imports the automatically registered custom element
+2. syncs React props onto element **properties** (not fragile attribute stringification)
+3. forwards refs and DOM events
+
+See [`docs/integration/react.md`](../../docs/integration/react.md) for the React
+boundary and the [framework adapter tracker](../../docs/integration/framework-adapters.md)
+for cross-framework milestones.
+
+## Install
+
+```bash
+npm install @unofficialbox/box-open-elements @unofficialbox/box-open-elements-react react react-dom
+```
+
+```ts
+import { Button, Dialog, Select, TextField } from "@unofficialbox/box-open-elements-react";
+import {
+  applyDesignTokens,
+  registerBoxDefaultDesignSystem,
+} from "@unofficialbox/box-open-elements/foundations/tokens";
+
+registerBoxDefaultDesignSystem({ setActive: true });
+applyDesignTokens(document.documentElement, "box-default");
+
+export function SaveAction() {
+  return (
+    <>
+      <TextField label="Project" value="Apollo" />
+      <Select
+        label="Status"
+        value="draft"
+        options={[{ label: "Draft", value: "draft" }]}
+      />
+      <Button label="Save" tone="primary" onClick={() => console.log("saved")} />
+    </>
+  );
+}
+```
+
+The release-candidate surface also includes a controlled `Dialog` wrapper and
+`useExplorerSelectionController`, which subscribes React to the existing
+headless selection controller without duplicating its state.
+
+## Status
+
+**Release candidate** — `Button`, `TextField`, `Select`, and `Dialog` prove native and
+composed events, value and structured property synchronization, latest callback
+routing, forwarded refs, controlled overlay focus behavior, and server-safe host
+rendering. `useExplorerSelectionController` proves headless controller
+composition. Package exports, version contracts, the Next.js hydration fixture,
+and CI validation are release-ready. Supported status follows the first public
+npm publication and a clean registry-install verification. React releases in
+lockstep with the Angular, Vue, and Svelte adapters under `adapters-vX.Y.Z`.
+
+## Supported versions
+
+| Dependency | Contract |
+| --- | --- |
+| React / React DOM | `^19.0.0` |
+| `@unofficialbox/box-open-elements` | `^0.5.0` |
+| Node.js for SSR | `>=20.9.0` |
+| Next.js validation host | `16.2.12` |
+
+The package ships ESM JavaScript and declarations from `dist/`. The Next.js
+fixture in `examples/frameworks/react-ssr` proves server prerendering, browser
+upgrade, hydration, events, controller subscriptions, and overlay focus.

package/dist/button.d.ts

@@ -0,0 +1,30 @@
+import type { MouseEventHandler } from "react";
+import { Button as ButtonElement } from "@unofficialbox/box-open-elements/button";
+import { type WebComponentProps } from "./create-web-component.js";
+export type ButtonProps = WebComponentProps & {
+    /** Button label text (maps to the `label` property / attribute). */
+    label?: string;
+    /** Visual tone: `primary` (default), `neutral`, `danger`. */
+    tone?: string;
+    /** Control size: `small`, `medium` (default), `large`. */
+    size?: string;
+    disabled?: boolean;
+    onClick?: MouseEventHandler<ButtonElement>;
+};
+/**
+ * React wrapper for `<box-button>`. Registers the custom element on first render
+ * and syncs props as element properties for the supported React 19 contract.
+ */
+export declare const Button: import("react").ForwardRefExoticComponent<{
+    className?: string;
+    style?: import("react").CSSProperties;
+} & Omit<import("react").HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel"> & {
+    /** Button label text (maps to the `label` property / attribute). */
+    label?: string;
+    /** Visual tone: `primary` (default), `neutral`, `danger`. */
+    tone?: string;
+    /** Control size: `small`, `medium` (default), `large`. */
+    size?: string;
+    disabled?: boolean;
+    onClick?: MouseEventHandler<ButtonElement>;
+} & import("react").RefAttributes<ButtonElement>>;

package/dist/button.js

@@ -0,0 +1,24 @@
+import { Button as ButtonElement } from "@unofficialbox/box-open-elements/button";
+import { createWebComponent } from "./create-web-component.js";
+ButtonElement.register();
+/**
+ * React wrapper for `<box-button>`. Registers the custom element on first render
+ * and syncs props as element properties for the supported React 19 contract.
+ */
+export const Button = createWebComponent({
+    tagName: "box-button",
+    displayName: "Button",
+    propertyNames: ["label", "tone", "size", "disabled"],
+    sync: (element, props) => {
+        if (props.label !== undefined) {
+            element.label = props.label;
+        }
+        if (props.tone !== undefined) {
+            element.tone = props.tone;
+        }
+        if (props.size !== undefined) {
+            element.size = props.size;
+        }
+        element.disabled = Boolean(props.disabled);
+    },
+});

package/dist/create-web-component.d.ts

@@ -0,0 +1,24 @@
+import { type CSSProperties, type HTMLAttributes } from "react";
+export type WebComponentProps = {
+    className?: string;
+    style?: CSSProperties;
+} & Omit<HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel">;
+type CreateWebComponentOptions<E extends HTMLElement, P extends WebComponentProps> = {
+    tagName: string;
+    /** Sync React props onto the custom element instance (prefer properties over attributes). */
+    sync: (element: E, props: P) => void;
+    /** Props assigned by `sync`; omit them from React's host-attribute spread. */
+    propertyNames?: ReadonlyArray<keyof P & string>;
+    /** Map React callback props to composed custom-element event names. */
+    events?: ReadonlyArray<{
+        propName: keyof P & string;
+        eventName: string;
+    }>;
+    displayName: string;
+};
+/**
+ * Thin React adapter factory for a box-open-elements custom element.
+ * Defines the element once, syncs props via properties, and forwards refs/events.
+ */
+export declare const createWebComponent: <E extends HTMLElement, P extends WebComponentProps>(options: CreateWebComponentOptions<E, P>) => import("react").ForwardRefExoticComponent<import("react").PropsWithoutRef<P> & import("react").RefAttributes<E>>;
+export {};

package/dist/create-web-component.js

@@ -0,0 +1,70 @@
+import { createElement, forwardRef, useCallback, useLayoutEffect, useRef, } from "react";
+const assignRef = (ref, value) => {
+    if (typeof ref === "function") {
+        ref(value);
+        return;
+    }
+    if (ref) {
+        ref.current = value;
+    }
+};
+/**
+ * Thin React adapter factory for a box-open-elements custom element.
+ * Defines the element once, syncs props via properties, and forwards refs/events.
+ */
+export const createWebComponent = (options) => {
+    const Component = forwardRef(function WebComponent(props, forwardedRef) {
+        const localRef = useRef(null);
+        const latestPropsRef = useRef(props);
+        const setRefs = useCallback(node => {
+            localRef.current = node;
+            assignRef(forwardedRef, node);
+        }, [forwardedRef]);
+        useLayoutEffect(() => {
+            latestPropsRef.current = props;
+            const element = localRef.current;
+            if (!element) {
+                return;
+            }
+            options.sync(element, props);
+        });
+        useLayoutEffect(() => {
+            const element = localRef.current;
+            if (!element || !options.events) {
+                return;
+            }
+            const subscriptions = options.events.map(binding => {
+                const listener = (event) => {
+                    const handler = latestPropsRef.current[binding.propName];
+                    if (typeof handler === "function") {
+                        handler(event);
+                    }
+                };
+                element.addEventListener(binding.eventName, listener);
+                return { eventName: binding.eventName, listener };
+            });
+            return () => {
+                for (const { eventName, listener } of subscriptions) {
+                    element.removeEventListener(eventName, listener);
+                }
+            };
+        }, []);
+        const { className, style, ...rest } = props;
+        const hostProps = { ...rest };
+        for (const propertyName of options.propertyNames ?? []) {
+            delete hostProps[propertyName];
+        }
+        for (const { propName } of options.events ?? []) {
+            delete hostProps[propName];
+        }
+        return createElement(options.tagName, {
+            ...hostProps,
+            ref: setRefs,
+            className,
+            style,
+            suppressHydrationWarning: true,
+        });
+    });
+    Component.displayName = options.displayName;
+    return Component;
+};

package/dist/dialog.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import { Dialog as DialogElement } from "@unofficialbox/box-open-elements/dialog";
+import { type WebComponentProps } from "./create-web-component.js";
+import type { CustomEventHandler } from "./events.js";
+export type DialogSize = "small" | "medium" | "large" | "fullscreen";
+export type DialogProps = WebComponentProps & {
+    children?: ReactNode;
+    open?: boolean;
+    heading?: string;
+    description?: string;
+    confirmLabel?: string;
+    size?: DialogSize;
+    onOpenChanged?: CustomEventHandler<DialogElement, {
+        open: boolean;
+    }>;
+    onConfirm?: CustomEventHandler<DialogElement, null>;
+    onCancel?: CustomEventHandler<DialogElement, null>;
+};
+/** React wrapper for the controlled `<box-dialog>` overlay. */
+export declare const Dialog: import("react").ForwardRefExoticComponent<{
+    className?: string;
+    style?: import("react").CSSProperties;
+} & Omit<import("react").HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel"> & {
+    children?: ReactNode;
+    open?: boolean;
+    heading?: string;
+    description?: string;
+    confirmLabel?: string;
+    size?: DialogSize;
+    onOpenChanged?: CustomEventHandler<DialogElement, {
+        open: boolean;
+    }>;
+    onConfirm?: CustomEventHandler<DialogElement, null>;
+    onCancel?: CustomEventHandler<DialogElement, null>;
+} & import("react").RefAttributes<DialogElement>>;

package/dist/dialog.js

@@ -0,0 +1,31 @@
+import { Dialog as DialogElement } from "@unofficialbox/box-open-elements/dialog";
+import { createWebComponent } from "./create-web-component.js";
+DialogElement.register();
+/** React wrapper for the controlled `<box-dialog>` overlay. */
+export const Dialog = createWebComponent({
+    tagName: "box-dialog",
+    displayName: "Dialog",
+    propertyNames: ["open", "heading", "description", "confirmLabel", "size"],
+    events: [
+        { propName: "onOpenChanged", eventName: "open-changed" },
+        { propName: "onConfirm", eventName: "confirm" },
+        { propName: "onCancel", eventName: "cancel" },
+    ],
+    sync: (element, props) => {
+        if (props.heading !== undefined) {
+            element.heading = props.heading;
+        }
+        if (props.description !== undefined) {
+            element.description = props.description;
+        }
+        if (props.confirmLabel !== undefined) {
+            element.confirmLabel = props.confirmLabel;
+        }
+        if (props.size !== undefined) {
+            element.size = props.size;
+        }
+        if (props.open !== undefined) {
+            element.open = props.open;
+        }
+    },
+});

package/dist/events.d.ts

@@ -0,0 +1,6 @@
+export type CustomEventHandler<E extends HTMLElement, Detail> = (event: CustomEvent<Detail> & {
+    currentTarget: E;
+}) => void;
+export type ValueChangedDetail = {
+    value: string;
+};

package/dist/events.js

@@ -0,0 +1 @@
+export {};

package/dist/explorer-selection.d.ts

@@ -0,0 +1,8 @@
+import { ExplorerSelectionController, type ExplorerSelectionState } from "@unofficialbox/box-open-elements/patterns/content-explorer/selection";
+export { ExplorerSelectionController };
+export type { ExplorerSelectionState };
+/**
+ * Subscribes React to the framework-neutral explorer selection controller.
+ * Selection behavior remains owned entirely by the controller.
+ */
+export declare const useExplorerSelectionController: (controller: ExplorerSelectionController) => Readonly<ExplorerSelectionState>;

package/dist/explorer-selection.js

@@ -0,0 +1,17 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { ExplorerSelectionController, } from "@unofficialbox/box-open-elements/patterns/content-explorer/selection";
+// Re-exported so a React host can construct the controller through this
+// package and hand it straight to the hook. Classes with private fields are
+// nominally typed, so a host that imports the class from a differently
+// resolved copy of the core package gets an incompatible identity — one
+// import path sidesteps that whole class of version-skew errors.
+export { ExplorerSelectionController };
+/**
+ * Subscribes React to the framework-neutral explorer selection controller.
+ * Selection behavior remains owned entirely by the controller.
+ */
+export const useExplorerSelectionController = (controller) => {
+    const subscribe = useCallback((onStoreChange) => controller.subscribe("selectionChanged", () => onStoreChange()), [controller]);
+    const getSnapshot = useCallback(() => controller.getState(), [controller]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@unofficialbox/box-open-elements-react` — optional React wrappers for box-open-elements
+ * Web Components. Core stays framework-agnostic; this package is an adapter
+ * layer only.
+ */
+export { createWebComponent, type WebComponentProps } from "./create-web-component.js";
+export type { CustomEventHandler, ValueChangedDetail } from "./events.js";
+export { Button, type ButtonProps } from "./button.js";
+export { Dialog, type DialogProps, type DialogSize } from "./dialog.js";
+export { ExplorerSelectionController, useExplorerSelectionController, type ExplorerSelectionState, } from "./explorer-selection.js";
+export { Select, type SelectOption, type SelectProps } from "./select.js";
+export { TextField, type TextFieldProps } from "./text-field.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@unofficialbox/box-open-elements-react` — optional React wrappers for box-open-elements
+ * Web Components. Core stays framework-agnostic; this package is an adapter
+ * layer only.
+ */
+export { createWebComponent } from "./create-web-component.js";
+export { Button } from "./button.js";
+export { Dialog } from "./dialog.js";
+export { ExplorerSelectionController, useExplorerSelectionController, } from "./explorer-selection.js";
+export { Select } from "./select.js";
+export { TextField } from "./text-field.js";

package/dist/select.d.ts

@@ -0,0 +1,31 @@
+import { Select as SelectElement } from "@unofficialbox/box-open-elements/select";
+import { type WebComponentProps } from "./create-web-component.js";
+import type { CustomEventHandler, ValueChangedDetail } from "./events.js";
+export type SelectOption = {
+    label: string;
+    value: string;
+};
+export type SelectProps = WebComponentProps & {
+    label?: string;
+    value?: string;
+    options?: SelectOption[];
+    disabled?: boolean;
+    name?: string;
+    invalid?: boolean;
+    errorMessage?: string;
+    onValueChanged?: CustomEventHandler<SelectElement, ValueChangedDetail>;
+};
+/** React wrapper for `<box-select>`, including its structured `options` property. */
+export declare const Select: import("react").ForwardRefExoticComponent<{
+    className?: string;
+    style?: import("react").CSSProperties;
+} & Omit<import("react").HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel"> & {
+    label?: string;
+    value?: string;
+    options?: SelectOption[];
+    disabled?: boolean;
+    name?: string;
+    invalid?: boolean;
+    errorMessage?: string;
+    onValueChanged?: CustomEventHandler<SelectElement, ValueChangedDetail>;
+} & import("react").RefAttributes<SelectElement>>;

package/dist/select.js

@@ -0,0 +1,37 @@
+import { Select as SelectElement } from "@unofficialbox/box-open-elements/select";
+import { createWebComponent } from "./create-web-component.js";
+SelectElement.register();
+/** React wrapper for `<box-select>`, including its structured `options` property. */
+export const Select = createWebComponent({
+    tagName: "box-select",
+    displayName: "Select",
+    propertyNames: [
+        "label",
+        "value",
+        "options",
+        "disabled",
+        "name",
+        "invalid",
+        "errorMessage",
+    ],
+    events: [{ propName: "onValueChanged", eventName: "value-changed" }],
+    sync: (element, props) => {
+        if (props.label !== undefined) {
+            element.label = props.label;
+        }
+        if (props.value !== undefined) {
+            element.value = props.value;
+        }
+        if (props.options !== undefined) {
+            element.options = props.options;
+        }
+        if (props.name !== undefined) {
+            element.name = props.name;
+        }
+        if (props.errorMessage !== undefined) {
+            element.errorMessage = props.errorMessage;
+        }
+        element.disabled = Boolean(props.disabled);
+        element.invalid = Boolean(props.invalid);
+    },
+});

package/dist/text-field.d.ts

@@ -0,0 +1,27 @@
+import { TextField as TextFieldElement } from "@unofficialbox/box-open-elements/text-field";
+import { type WebComponentProps } from "./create-web-component.js";
+import type { CustomEventHandler, ValueChangedDetail } from "./events.js";
+export type TextFieldProps = WebComponentProps & {
+    label?: string;
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    name?: string;
+    invalid?: boolean;
+    errorMessage?: string;
+    onValueChanged?: CustomEventHandler<TextFieldElement, ValueChangedDetail>;
+};
+/** React wrapper for the value-bearing `<box-text-field>` form control. */
+export declare const TextField: import("react").ForwardRefExoticComponent<{
+    className?: string;
+    style?: import("react").CSSProperties;
+} & Omit<import("react").HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel"> & {
+    label?: string;
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    name?: string;
+    invalid?: boolean;
+    errorMessage?: string;
+    onValueChanged?: CustomEventHandler<TextFieldElement, ValueChangedDetail>;
+} & import("react").RefAttributes<TextFieldElement>>;

package/dist/text-field.js

@@ -0,0 +1,37 @@
+import { TextField as TextFieldElement } from "@unofficialbox/box-open-elements/text-field";
+import { createWebComponent } from "./create-web-component.js";
+TextFieldElement.register();
+/** React wrapper for the value-bearing `<box-text-field>` form control. */
+export const TextField = createWebComponent({
+    tagName: "box-text-field",
+    displayName: "TextField",
+    propertyNames: [
+        "label",
+        "value",
+        "placeholder",
+        "disabled",
+        "name",
+        "invalid",
+        "errorMessage",
+    ],
+    events: [{ propName: "onValueChanged", eventName: "value-changed" }],
+    sync: (element, props) => {
+        if (props.label !== undefined) {
+            element.label = props.label;
+        }
+        if (props.value !== undefined) {
+            element.value = props.value;
+        }
+        if (props.placeholder !== undefined) {
+            element.placeholder = props.placeholder;
+        }
+        if (props.name !== undefined) {
+            element.name = props.name;
+        }
+        if (props.errorMessage !== undefined) {
+            element.errorMessage = props.errorMessage;
+        }
+        element.disabled = Boolean(props.disabled);
+        element.invalid = Boolean(props.invalid);
+    },
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@unofficialbox/box-open-elements-react",
+  "version": "0.7.0",
+  "description": "Optional React wrappers for box-open-elements Web Components. Thin adapters — core stays framework-agnostic.",
+  "license": "MIT",
+  "homepage": "https://unofficialbox.github.io/box-open-elements",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unofficialbox/box-open-elements.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/unofficialbox/box-open-elements/issues"
+  },
+  "keywords": [
+    "react",
+    "web-components",
+    "design-system",
+    "box"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "peerDependencies": {
+    "@unofficialbox/box-open-elements": "^0.7.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}