@unofficialbox/box-open-elements-react 0.7.0 → 0.9.0

package/README.md

@@ -6,7 +6,21 @@ 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
+3. forwards refs, and binds event callbacks directly to the element
+
+Callbacks an adapter **declares** receive the **native** DOM event, not a React
+`SyntheticEvent`. They are registered with `addEventListener` on the custom
+element so the listener travels with it: React delegates from its root
+container, so a node relocated out of that container silently stops receiving
+delegated handlers. `Button` declares its own `onClick`, typed as
+`(event: MouseEvent) => void`, for exactly that reason.
+
+Props an adapter does not declare — including React's `onClick` on `Select`,
+`TextField` and `Dialog` — are forwarded as ordinary host props and stay
+delegated. That is fine unless something moves the node out of the React root,
+and it is React's delegation model rather than these components': a plain
+`<div onClick>` in a relocated subtree behaves the same. (`box-drawer` used to
+relocate its subtree and no longer does — it uses the top layer.)
 
 See [`docs/integration/react.md`](../../docs/integration/react.md) for the React
 boundary and the [framework adapter tracker](../../docs/integration/framework-adapters.md)
@@ -43,27 +57,27 @@ export function SaveAction() {
 }
 ```
 
-The release-candidate surface also includes a controlled `Dialog` wrapper and
+The supported 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** as of `0.7.0` — `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. The two conditions this section used to defer on are met:
+the first public npm publication happened at `0.7.0`, and a clean registry install
+resolves the package and loads its exports. React releases in lockstep with the
+Angular, Vue, and Svelte adapters under `adapters-vX.Y.Z`, at the core's version.
 
 ## Supported versions
 
 | Dependency | Contract |
 | --- | --- |
 | React / React DOM | `^19.0.0` |
-| `@unofficialbox/box-open-elements` | `^0.5.0` |
+| `@unofficialbox/box-open-elements` | `^0.9.0` |
 | Node.js for SSR | `>=20.9.0` |
 | Next.js validation host | `16.2.12` |
 

package/dist/button.d.ts

@@ -1,7 +1,7 @@
-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 & {
+import type { NativeEventHandler } from "./events.js";
+export type ButtonProps = Omit<WebComponentProps, "onClick"> & {
     /** Button label text (maps to the `label` property / attribute). */
     label?: string;
     /** Visual tone: `primary` (default), `neutral`, `danger`. */
@@ -9,16 +9,26 @@ export type ButtonProps = WebComponentProps & {
     /** Control size: `small`, `medium` (default), `large`. */
     size?: string;
     disabled?: boolean;
-    onClick?: MouseEventHandler<ButtonElement>;
+    /**
+     * Click callback, bound directly to the element.
+     *
+     * Receives a **native** `MouseEvent`, not a React `SyntheticEvent`. See
+     * `NativeEventHandler` for why the binding is direct.
+     */
+    onClick?: NativeEventHandler<ButtonElement, MouseEvent>;
 };
 /**
  * React wrapper for `<box-button>`. Registers the custom element on first render
  * and syncs props as element properties for the supported React 19 contract.
+ *
+ * `click` is bound through the factory's `events` map rather than left to
+ * React's `onClick`. React delegates from its root container, so a button that
+ * has been relocated out of it — every button inside a `box-drawer`, which
+ * portals to `document.body` on open — never sees a delegated event and the
+ * callback silently does nothing. A listener on the element travels with it.
+ * The other adapters already bind this way; Button was the one that didn't.
  */
-export declare const Button: import("react").ForwardRefExoticComponent<{
-    className?: string;
-    style?: import("react").CSSProperties;
-} & Omit<import("react").HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel"> & {
+export declare const Button: import("react").ForwardRefExoticComponent<Omit<WebComponentProps, "onClick"> & {
     /** Button label text (maps to the `label` property / attribute). */
     label?: string;
     /** Visual tone: `primary` (default), `neutral`, `danger`. */
@@ -26,5 +36,11 @@ export declare const Button: import("react").ForwardRefExoticComponent<{
     /** Control size: `small`, `medium` (default), `large`. */
     size?: string;
     disabled?: boolean;
-    onClick?: MouseEventHandler<ButtonElement>;
+    /**
+     * Click callback, bound directly to the element.
+     *
+     * Receives a **native** `MouseEvent`, not a React `SyntheticEvent`. See
+     * `NativeEventHandler` for why the binding is direct.
+     */
+    onClick?: NativeEventHandler<ButtonElement, MouseEvent>;
 } & import("react").RefAttributes<ButtonElement>>;

package/dist/button.js

@@ -4,11 +4,19 @@ 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.
+ *
+ * `click` is bound through the factory's `events` map rather than left to
+ * React's `onClick`. React delegates from its root container, so a button that
+ * has been relocated out of it — every button inside a `box-drawer`, which
+ * portals to `document.body` on open — never sees a delegated event and the
+ * callback silently does nothing. A listener on the element travels with it.
+ * The other adapters already bind this way; Button was the one that didn't.
  */
 export const Button = createWebComponent({
     tagName: "box-button",
     displayName: "Button",
     propertyNames: ["label", "tone", "size", "disabled"],
+    events: [{ propName: "onClick", eventName: "click" }],
     sync: (element, props) => {
         if (props.label !== undefined) {
             element.label = props.label;

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

@@ -1,9 +1,45 @@
 import { type CSSProperties, type HTMLAttributes } from "react";
+/**
+ * Host props an adapter accepts.
+ *
+ * `onCancel` is omitted because `Dialog` redeclares it with a native-event
+ * signature, and an intersection of two function types is an overload that no
+ * single handler satisfies.
+ *
+ * React's `onClick` stays. It is delegated from the React root container, which
+ * means it does **not** fire for an element that has relocated outside that
+ * container — every host inside an open `box-drawer`, which portals its subtree
+ * to `document.body`. That is a real trap, but it is React's trap and it catches
+ * a plain `<div onClick>` in a drawer just the same; removing the prop from
+ * three adapters would not fix the class of bug, only make those three behave
+ * unlike every other element in the tree while breaking handlers that work
+ * perfectly well outside overlays. An adapter that needs a click callback to
+ * survive relocation declares its own and binds through `events` below, as
+ * `Button` does.
+ */
 export type WebComponentProps = {
     className?: string;
     style?: CSSProperties;
 } & Omit<HTMLAttributes<HTMLElement>, "className" | "style" | "children" | "onCancel">;
-type CreateWebComponentOptions<E extends HTMLElement, P extends WebComponentProps> = {
+/**
+ * What the factory itself requires of an adapter's props.
+ *
+ * Deliberately narrower than `WebComponentProps`: the factory reads `className`
+ * and `style` and spreads the rest, so those two are the whole requirement.
+ * Constraining to the full host-prop type instead would forbid an adapter from
+ * *narrowing* a host prop — `Button` redeclaring `onClick` as a native-event
+ * handler is not assignable to React's `MouseEventHandler` (parameters are
+ * contravariant, and a `SyntheticEvent` is not a `MouseEvent`), so the whole
+ * prop would have to come off the base type for every adapter to keep one
+ * adapter's narrowing legal. Each adapter still builds its props from
+ * `WebComponentProps`; the constraint just stops one adapter's choice from
+ * dictating the shared type.
+ */
+type AdapterHostProps = {
+    className?: string;
+    style?: CSSProperties;
+};
+type CreateWebComponentOptions<E extends HTMLElement, P extends AdapterHostProps> = {
     tagName: string;
     /** Sync React props onto the custom element instance (prefer properties over attributes). */
     sync: (element: E, props: P) => void;
@@ -20,5 +56,5 @@ type CreateWebComponentOptions<E extends HTMLElement, P extends WebComponentProp
  * 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 declare const createWebComponent: <E extends HTMLElement, P extends AdapterHostProps>(options: CreateWebComponentOptions<E, P>) => import("react").ForwardRefExoticComponent<import("react").PropsWithoutRef<P> & import("react").RefAttributes<E>>;
 export {};

package/dist/events.d.ts

@@ -4,3 +4,19 @@ export type CustomEventHandler<E extends HTMLElement, Detail> = (event: CustomEv
 export type ValueChangedDetail = {
     value: string;
 };
+/**
+ * A callback bound with `addEventListener`, receiving the **native** event.
+ *
+ * Not a React `SyntheticEvent`. Adapter callbacks are registered directly on
+ * the custom element rather than routed through React's delegation, so what
+ * arrives is the real DOM event — `event.nativeEvent` does not exist on it, and
+ * `stopPropagation` acts on the real tree.
+ *
+ * That indirection is not a style choice. React delegates from the root
+ * container, and an element that relocates itself outside that container —
+ * `box-drawer` portals to `document.body` when it opens — stops receiving
+ * delegated events entirely. A listener on the element itself travels with it.
+ */
+export type NativeEventHandler<E extends HTMLElement, Ev extends Event = Event> = (event: Ev & {
+    currentTarget: E;
+}) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements-react",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -37,7 +37,7 @@
     "node": ">=20.9.0"
   },
   "peerDependencies": {
-    "@unofficialbox/box-open-elements": "^0.7.0",
+    "@unofficialbox/box-open-elements": "^0.9.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },