@firsthandjs/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+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,137 @@
+# @firsthandjs/react
+
+React components inside Firsthand — for MUI, and for every other library that
+exists only as React components.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/11-react-interop.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/react.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+
+```
+npm install @firsthandjs/react react react-dom
+```
+
+0.66 kB gzip. React and react-dom are peer dependencies: an application that
+never imports this package does not install them.
+
+```tsx
+import Button from '@mui/material/Button';
+import { fromReact } from '@firsthandjs/react';
+
+const MuiButton = fromReact(Button);
+
+<MuiButton variant="contained" onClick={save}>
+  Save
+</MuiButton>;
+```
+
+That works. [`integrations/interop`](../../integrations/interop) builds it and
+drives it in Chromium: MUI's `Button`, `Chip` and `Slider`, a React event
+calling back into a Firsthand signal, and a Firsthand signal updating a React prop.
+
+## React components as elements
+
+```tsx
+import '@firsthandjs/react/auto'; // once, at startup
+import Button from '@mui/material/Button';
+
+<Button variant="contained" onClick={save}>
+  Save
+</Button>;
+```
+
+Same bridge, same cost, one import instead of one wrapper per component. Use
+`fromReact` where you need Firsthand children — a direct element types `children`
+as React's `ReactNode` — or the bridge's `host` and `class` props.
+
+## One provider for every root
+
+Each bridge mounts its own React root, so React context does not flow between
+them: a `ThemeProvider` rendered through one bridge cannot reach a button
+rendered through another.
+
+```tsx
+import { createElement } from 'react';
+import { ThemeProvider } from '@mui/material/styles';
+import { setReactWrapper } from '@firsthandjs/react';
+
+setReactWrapper((node) => createElement(ThemeProvider, { theme: muiTheme(theme.value) }, node));
+```
+
+Reading a signal in the wrapper makes one theme switch re-render every bridged
+component, and nothing else.
+
+## What it costs
+
+React and react-dom are **about 45 kB gzip**, eight times this framework's
+entire runtime. Everything below a bridge is React's: its reconciler, its
+re-renders, its synthetic events. The bridge is fine-grained on the Firsthand side
+only — one effect re-renders the React root when a prop it reads changes, and
+the subtree below then behaves exactly as it does in a React application.
+
+So this is an escape hatch, and the size of the thing you are escaping to
+should decide whether to use it:
+
+| You want                                                                  | Use                                                                                                                                               |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A button, a card, a layout                                                | Plain elements, or [`@firsthandjs/styled`](../styled)                                                                                             |
+| A design system                                                           | A **web-component** one: Shoelace, Material Web, Fluent, Vaadin, Carbon. They are custom elements, so Firsthand uses them with nothing in between |
+| A date picker, a data grid, a rich text editor that only exists for React | This package                                                                                                                                      |
+
+The middle row is the one people miss. A web-component library needs no bridge,
+no adapter and no React — see the interop integration, which uses Shoelace with
+nothing but an import.
+
+## How it behaves
+
+**Call `fromReact` once, at module level.** Each _instance_ mounts its own
+React root, so creating the bridge inside a component would create a root per
+render of the surrounding page.
+
+**Props are forwarded, except two.** `class` goes on the host element, `host`
+chooses the host tag (a `span` by default, so inline layout survives).
+Everything else reaches the React component untouched — including functions, so
+callbacks work in both directions.
+
+**Children stay Firsthand's.** React cannot render DOM nodes, and a Firsthand dynamic
+child is a deferred part rather than a node, so the bridge gives Firsthand its own
+element inside the React tree and fills it through the ordinary `insert`.
+Reactive children update without React hearing about it:
+
+```tsx
+<MuiCard>
+  <p>{count.value}</p> {/* updates as a text write, not a React render */}
+</MuiCard>
+```
+
+**Disposal unmounts the root**, in a microtask — React refuses to unmount a
+root while it is rendering, and a Firsthand disposal can happen inside an effect a
+React event started.
+
+## `ReactHost`
+
+For a component chosen at runtime:
+
+```tsx
+<ReactHost component={whichever} props={{ variant: 'contained' }} host="div" />
+```
+
+It mounts a root per instance either way, so prefer `fromReact` where the
+component is known.
+
+## Two copies of React
+
+If you link this package from a monorepo rather than installing it, your
+bundler may resolve its `react` import and your application's to two different
+copies, and React's hooks dispatcher will be `null`:
+
+```
+TypeError: Cannot read properties of null (reading 'useContext')
+```
+
+```ts
+// vite.config.ts
+resolve: {
+  dedupe: ['react', 'react-dom'];
+}
+```
+
+An installed package has one copy and needs none of this.

package/dist/auto.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentType } from 'react';
+declare global {
+    namespace JSX {
+        interface ForeignElementTypes {
+            react: ComponentType<any>;
+        }
+    }
+}
+//# sourceMappingURL=auto.d.ts.map

package/dist/auto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAO3C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,GAAG,CAAC;QACZ,UAAU,mBAAmB;YAE3B,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;SAC3B;KACF;CACF"}

package/dist/auto.js

@@ -0,0 +1 @@
+import{b as e}from"./chunk-OSGUVKQH.js";import{setComponentAdapter as n}from"@firsthandjs/dom";n(o=>e(o));

package/dist/chunk-OSGUVKQH.js

@@ -0,0 +1 @@
+import{bind as R,onCleanup as g,signal as h}from"@firsthandjs/core";import{component as m}from"@firsthandjs/dom";import{insert as T}from"@firsthandjs/dom/internal";import{createElement as s}from"react";import{createRoot as w}from"react-dom/client";var u=h(null);function x(e){u.value=e}function M({slot:e}){return s("span",{ref:t=>{t!==null&&e.parentNode!==t&&t.appendChild(e)}})}function N(e,t={}){let f=n=>{let y=n.host??t.host??"span",l=document.createElement(y),c=w(l),a="children"in n?document.createElement("span"):null;return a!==null&&T(a,()=>n.children),R(()=>{let o={};for(let r of Object.keys(n))r==="class"||r==="host"||r==="children"||(o[r]=n[r]);typeof n.class=="string"&&(l.className=n.class),a!==null&&(o.children=s(M,{slot:a}));let d=s(e,o),p=u.value;c?.render(p===null?d:p(d))}),g(()=>{let o=c;c=null,queueMicrotask(()=>{o?.unmount()})}),l},i=e.displayName??(e.name===""?"Anonymous":e.name);return m(f,void 0,`firsthand/react:${i}`,`React(${i})`)}var C=m(e=>N(e.component,{...e.host===void 0?{}:{host:e.host}})({...e.props}),void 0,"firsthand/react:ReactHost","ReactHost");export{x as a,N as b,C as c};

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { type Component, type View } from '@firsthandjs/dom';
+import { type ComponentType, type ReactNode } from 'react';
+/** Wraps what every bridged root renders — a provider tower, usually. */
+export type ReactWrapper = (node: ReactNode) => ReactNode;
+/**
+ * Wraps every bridged React root in the same React elements.
+ *
+ * Each bridge mounts its **own** React root, so React context does not flow
+ * from one to another: a `<ThemeProvider>` written as one bridged component
+ * cannot reach a `<Button>` written as another, because they are different
+ * trees. Providers therefore have to be per root, which is what this does.
+ *
+ * ```tsx
+ * import { createElement } from 'react';
+ * import { ThemeProvider } from '@mui/material/styles';
+ *
+ * setReactWrapper((node) => createElement(ThemeProvider, { theme: muiTheme(theme.value) }, node));
+ * ```
+ *
+ * Reading a signal inside the wrapper — `theme.value` above — is an ordinary
+ * reactive read, so swapping the theme re-renders every bridged component and
+ * nothing else. `null` removes it again.
+ */
+export declare function setReactWrapper(next: ReactWrapper | null): void;
+/**
+ * Props a bridged component takes.
+ *
+ * The React component's own, except `children`: what you write inside a
+ * bridged component in TSX is Firsthand's, not React's — DOM that Firsthand keeps
+ * owning inside the React tree — so the type says `View` rather than
+ * `ReactNode`.
+ */
+export type BridgeProps<P> = Omit<P, 'children'> & {
+    readonly children?: View;
+    /** Put on the element React renders into, not passed to the component. */
+    readonly class?: string;
+    /** The element to mount into. `span` by default, so inline layout survives. */
+    readonly host?: keyof HTMLElementTagNameMap;
+};
+/**
+ * Turns a React component into a Firsthand one.
+ *
+ * Call it once, at module level, next to the import — a bridge created inside
+ * a component would mount a new React root per instance.
+ */
+export declare function fromReact<P extends object>(Component_: ComponentType<P>, options?: {
+    host?: keyof HTMLElementTagNameMap;
+}): Component<BridgeProps<P>>;
+/**
+ * The same thing without declaring a component first.
+ *
+ * ```tsx
+ * <ReactHost component={Button} props={{ variant: 'contained' }} />
+ * ```
+ *
+ * Useful when the component is chosen at runtime. It mounts a root per
+ * instance either way, so prefer `fromReact` where you can.
+ */
+export declare const ReactHost: Component<{
+    readonly component: ComponentType<never>;
+    readonly props?: Record<string, unknown>;
+    readonly host?: keyof HTMLElementTagNameMap;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAa,KAAK,SAAS,EAAE,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG1E,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,SAAS,CAAC;AAQ1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAE/D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,qBAAqB,CAAC;CAC7C,CAAC;AAqBF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EACxC,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,qBAAqB,CAAA;CAAO,GACnD,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA2D3B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS;wBACA,aAAa,CAAC,KAAK,CAAC;qBACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;oBACxB,MAAM,qBAAqB;EAW5C,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+import{a,b,c}from"./chunk-OSGUVKQH.js";export{c as ReactHost,b as fromReact,a as setReactWrapper};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@firsthandjs/react",
+  "version": "0.1.0",
+  "description": "Render React components inside Firsthand, for component libraries like MUI.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./dist/auto.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./auto": {
+      "types": "./dist/auto.d.ts",
+      "default": "./dist/auto.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/core": "0.1.0",
+    "@firsthandjs/dom": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "react",
+    "interop",
+    "mui",
+    "adapter"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-dom": {
+      "optional": false
+    }
+  }
+}