foundry-vtt-react 0.1.0 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Sandberg
+
+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,26 +1,49 @@
 # Foundry VTT React
 
-This package provides extensions of various Foundry VTT classes to support React applications development within Foundry.
+This package provides extensions of various Foundry VTT classes to support building React applications inside Foundry VTT.
+
+It is a **library**, consumed by module developers — not a Foundry module itself.
+
+This is a bit experimental, but enables a modern JS workflow and if you know and enjoy React workflows with HMR/fast-refresh, this should have you flying in no time!
+
+**Disclaimers:**
+- ⚠️ Only tested against Foundry V13 at this point, v14 compatability testing coming soon (wanna try it out for me?)
+- ℹ️ Would love input if you're a Vite pro -- I have a suspicion devSetup could be a plugin, haven't had time to look into it.
 
 ## Installation
 
-Currently supported FoundryVTT classes:
+```bash
+npm install foundry-vtt-react
+# or: pnpm add foundry-vtt-react
+```
+
+`react` and `react-dom` (v19) are peer dependencies — install them in your module if you haven't already:
+
+```bash
+npm install react react-dom
+```
+
+## Supported Foundry classes
+
+- `ReactApplicationV2` — a base `ApplicationV2` that renders a React component instead of a Handlebars template.
+- `ReactActorSheetV2` — an `ActorSheetV2` that renders with React, letting your component react to document changes through the native sheet lifecycle.
 
-- `ReactApplicationV2`: A base application class for creating React-based applications in Foundry VTT.
-- `ReactActorSheetV2`: An actor sheet class that uses React for rendering the UI, allowing the React app to listen for changes to the document using the native ActoSheetV2 lifecycle events.
+Both are produced by the same `ReactApplicationMixin`, so they share the options and lifecycle described below.
 
 ## Usage
 
-There are two important pieces to developing React applications in Foundry.
+There are two pieces to developing React applications in Foundry:
 
-1. Creating your ReactApplicationV2 instance and passing in your React component.
-2. Configuring ViteJS development server to work with your local FoundryVTT instance.
+1. Creating a React-powered application instance and passing in your React component.
+2. Configuring a Vite dev server to work with your local Foundry instance (see [Development setup](#development-setup-with-vite)).
 
-### Creating a ReactApplicationV2 Instance
+### Creating a ReactApplicationV2 instance
 
-To create a new React-powered Foundry application, you can instantiate the `ReactApplicationV2` class and provide your React component along with any initial properties and window options.
+Instantiate `ReactApplicationV2` with your React component plus any initial props and window options:
+
+```jsx
+import { ReactApplicationV2 } from "foundry-vtt-react";
 
-```javascript
 // Basic component
 function MyReactComponent(props) {
   return <div>Hello, {props.data}!</div>;
@@ -36,4 +59,252 @@ const app = new ReactApplicationV2({
 app.render(true);
 ```
 
-![alt text](assets/image.png)
+A React component rendered inside a Foundry application window
+
+**Constructor options**
+
+
+| Option         | Type                  | Description                                                                              |
+| -------------- | --------------------- | ---------------------------------------------------------------------------------------- |
+| `reactApp`     | `React.ComponentType` | The component mounted into the application window.                                       |
+| `initialProps` | `object` (optional)   | Props passed to `reactApp` on mount. Also reachable via `_prepareContext` (see below).   |
+| ...options     | `ApplicationV2`       | Any standard `ApplicationV2` options (`window`, `position`, `classes`, `actions`, etc.). |
+
+
+### Building a React actor sheet
+
+Subclass `ReactActorSheetV2`, set `reactApp`, and register it as the sheet for your actor type. Override `_prepareContext` to choose exactly which props your component receives — this is also where you hand your component the `[ContextConnector](#reacting-to-foundry-updates-with-contextconnector)` so it can subscribe to live document updates:
+
+```jsx
+import { ReactActorSheetV2 } from "foundry-vtt-react";
+import MySheetApp from "./MySheetApp";
+
+class MyActorSheet extends ReactActorSheetV2 {
+  reactApp = MySheetApp;
+
+  static DEFAULT_OPTIONS = {
+    window: { title: "My Sheet", resizable: true },
+    position: { width: 625, height: 750 },
+    classes: ["my-sheet"],
+  };
+
+  async _prepareContext(options) {
+    const context = await super._prepareContext(options);
+    // Pick the props your React app receives:
+    context.initialProps = {
+      actor: context.document,
+      source: context.source,
+      contextConnector: this.contextConnector, // for live updates
+    };
+    return context;
+  }
+}
+```
+
+Register it like any other sheet, e.g.:
+
+```js
+foundry.documents.collections.Actors.registerSheet("my-module", MyActorSheet, {
+  types: ["character"],
+  makeDefault: true,
+});
+```
+
+### Reacting to Foundry updates with ContextConnector
+
+Every React application instance owns a `ContextConnector` at `this.contextConnector`. On **every** render, the mixin calls `contextConnector.publishContext(context)` with the prepared context (which, for a sheet, includes the updated `document`). Pass the connector into your component (via `initialProps`, as shown above) and subscribe to those updates so React re-renders when the Foundry document changes.
+
+`onUpdate(callback)` returns a **disposer** function, ideal for `useEffect` cleanup:
+
+```jsx
+import { useEffect, useState } from "react";
+
+function MySheetApp({ actor: initialActor, contextConnector }) {
+  const [actor, setActor] = useState(initialActor);
+
+  useEffect(() => {
+    // Re-render whenever Foundry re-renders the sheet
+    const off = contextConnector.onUpdate(({ document }) => {
+      setActor(document);
+    });
+    return off; // unsubscribe on unmount
+  }, [contextConnector]);
+
+  return <h1>{actor.name}</h1>;
+}
+```
+
+You can debounce noisy update streams with Foundry's helper:
+
+```jsx
+const handleUpdate = foundry.utils.debounce(({ document }) => {
+  setActor(document);
+}, 200);
+const off = contextConnector.onUpdate(handleUpdate);
+```
+
+`ContextConnector<T>` **API**
+
+
+| Method                    | Returns      | Description                                                         |
+| ------------------------- | ------------ | ------------------------------------------------------------------- |
+| `onUpdate(cb)`            | `() => void` | Subscribe to context updates. Returns a disposer that unsubscribes. |
+| `tearDown(cb)`            | `void`       | Unsubscribe a callback previously passed to `onUpdate`.             |
+| `on(event, cb)`           | `() => void` | Subscribe to a custom event. Returns a disposer.                    |
+| `off(event, cb)`          | `void`       | Unsubscribe a callback from a custom event.                         |
+| `publishContext(context)` | `void`       | Emit a context update. Called for you by the mixin on each render.  |
+
+
+> Use the returned disposer **or** `tearDown(cb)` to clean up — either removes the listener.
+
+## Development setup with Vite
+
+For a fast dev loop with React Fast Refresh (HMR) inside Foundry, you split your module into **two entry points** and let a Vite dev server serve them:
+
+- `src/main.ts` — your **real app** entry (registers hooks, sheets, etc.). This is what gets bundled for production.
+- `src/main.js` — a tiny **dev-only shim** that calls `devSetup`, which injects the React Refresh runtime and then loads `src/main.ts` over HMR.
+
+The trick that ties it together: your manifest's `esmodules` points at `dist/main.js`. In a production build that's the bundled app. In development, the Vite dev server is configured so that the same `/modules/<id>/dist/main.js` URL is served from `src/main.js` (the shim) — so **the manifest entry resolves to the dev shim while you develop, and to the real bundle once built.**
+
+### Directory structure
+
+```text
+my-module/
+├─ module.json          # manifest → esmodules: ["dist/main.js"]
+├─ package.json
+├─ vite.config.ts
+├─ src/
+│  ├─ main.js           # dev-only shim: calls devSetup() (served at dist/main.js in dev)
+│  ├─ main.ts           # real app entry: Hooks, registerSheet, … (build input)
+│  └─ MySheetApp.tsx    # your React component(s)
+└─ dist/                # build output (gitignored); created by `vite build`
+```
+
+### Steps
+
+**1. Manifest — point** `esmodules` **at the built path.**
+
+```jsonc
+// module.json
+{
+  "id": "my-module",
+  "esmodules": ["dist/main.js"],
+  "styles": ["dist/main.css"],
+  "compatibility": { "minimum": "13", "verified": "13" }
+}
+```
+
+**2. Real app entry (**`src/main.ts`**)** — your normal module bootstrap:
+
+```ts
+import MyActorSheet from "./MyActorSheet";
+
+foundry.helpers.Hooks.once("ready", () => {
+  foundry.documents.collections.Actors.registerSheet("my-module", MyActorSheet, {
+    types: ["character"],
+    makeDefault: true,
+  });
+});
+```
+
+**3. Dev-only shim (**`src/main.js`**)** — calls `devSetup` with your module id and the path to the real entry:
+
+```js
+import { id as APP_ID } from "../module.json";
+import { devSetup } from "foundry-vtt-react";
+
+// Loads @react-refresh + src/main.ts (served at dist/main.ts) with HMR.
+devSetup(APP_ID, "dist/main.ts");
+```
+
+**4. Vite config** — serve `src/` at the manifest's `dist` path and proxy everything else to Foundry:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+import { id as APP_ID } from "./module.json";
+
+export default defineConfig({
+  plugins: [react()],
+  root: "src/",
+  // Serve src/ under the path the manifest references, so
+  // /modules/<id>/dist/main.js resolves to src/main.js (the shim),
+  // and /modules/<id>/dist/main.ts resolves to src/main.ts (the app).
+  base: `/modules/${APP_ID}/dist`,
+  server: {
+    port: 30001,
+    proxy: {
+      // Everything that isn't your dev bundle goes to the Foundry server.
+      [`^(?!/modules/${APP_ID}/dist)`]: "http://localhost:30000/",
+      "/socket.io": { target: "ws://localhost:30000", ws: true },
+    },
+  },
+  build: {
+    outDir: path.resolve(__dirname, "dist"),
+    emptyOutDir: true,
+    rollupOptions: {
+      input: path.resolve(__dirname, "src/main.ts"), // build the real entry
+      output: { entryFileNames: "[name].js", assetFileNames: "[name].[ext]", format: "es" },
+    },
+  },
+});
+```
+
+**5. Scripts (**`package.json`**):**
+
+```jsonc
+{
+  "scripts": {
+    "dev": "vite",          // dev server with HMR
+    "build": "vite build"   // produces dist/main.js for production
+  }
+}
+```
+
+**6. Make the module visible to Foundry** — symlink (or copy) your module folder into your Foundry data `Data/modules/` directory so Foundry can read `module.json`.
+
+> If you run foundry in docker like me, you can simply mount your local module volume into the docker foundry's modules folder like:
+>
+> ```
+> foundry:
+>     image: felddy/foundryvtt:13
+>     hostname: localhost
+>     volumes:
+>       - /path/to/my-module:/data/Data/modules/my-module
+> ```
+
+**7. Run it.** Start Foundry (port `30000`), then `npm run dev` and open the Vite server (e.g. `http://localhost:30001`). Foundry loads your module; the manifest's `dist/main.js` is served from `src/main.js`, `devSetup` boots React Refresh, and edits to your components hot-reload.
+
+> For production, run `npm run build` and ship `dist/` — `dist/main.js` is now the bundled app, and `devSetup` is not involved.
+
+### `devSetup` reference
+
+```ts
+devSetup(appId: string, entrypoint: string): void
+```
+
+
+| Parameter    | Description                                                                                                            |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `appId`      | Your module's `id` (from `module.json`). Used to build the served paths and to namespace the injected `<script>` tags. |
+| `entrypoint` | Path to your real app entry, relative to the module root (e.g. `dist/main.ts`), as served by the Vite dev server.      |
+
+
+It injects (idempotently — safe to call more than once):
+
+- A `<script type="module">` preamble that wires up the React Refresh global hooks, loading `@react-refresh` from `/modules/<appId>/dist/@react-refresh`.
+- A `<script type="module" src="/modules/<appId>/<entrypoint>">` that loads your app.
+
+## Exports
+
+```js
+import {
+  ReactApplicationV2,
+  ReactActorSheetV2,
+  ContextConnector,
+  devSetup,
+} from "foundry-vtt-react";
+```
+

package/dist/index.d.mts

@@ -1,12 +1,27 @@
 export { devSetup } from './util/dev-setup.mjs';
 
+/**
+ * Event-based bridge for pushing Foundry context updates into React.
+ *
+ * A `ReactApplicationMixin` instance creates one connector and calls
+ * {@link ContextConnector.publishContext} on every render. React components
+ * subscribe with {@link ContextConnector.onUpdate} to re-render on changes.
+ */
 declare class ContextConnector<T> extends EventTarget {
+    #private;
     static UPDATE: string;
-    constructor();
     publishContext(context: T): void;
-    on(event: string, callback: (data: T) => void): void;
-    onUpdate(callback: (data: T) => void): void;
-    tearDown(fn: (data: T) => void): void;
+    /**
+     * Subscribe to an event. Returns a disposer that removes the listener,
+     * convenient for React `useEffect` cleanup.
+     */
+    on(event: string, callback: (data: T) => void): () => void;
+    /** Subscribe to context updates. Returns a disposer. */
+    onUpdate(callback: (data: T) => void): () => void;
+    /** Remove a listener previously added with {@link on}. */
+    off(event: string, callback: (data: T) => void): void;
+    /** Remove a context-update listener previously added with {@link onUpdate}. */
+    tearDown(callback: (data: T) => void): void;
 }
 
 declare const ReactApplicationV2_base: {

package/dist/index.mjs

@@ -5,22 +5,44 @@ import {
 // lib/context-connector.ts
 var ContextConnector = class _ContextConnector extends EventTarget {
   static UPDATE = "contextUpdate";
-  constructor() {
-    super();
-  }
+  /**
+   * Maps each subscriber callback to the wrapper actually registered with
+   * `addEventListener`, so `off`/`tearDown` can remove it by the original
+   * callback reference.
+   */
+  #wrappers = /* @__PURE__ */ new Map();
   publishContext(context) {
-    this.dispatchEvent(new CustomEvent("contextUpdate", { detail: context }));
+    this.dispatchEvent(
+      new CustomEvent(_ContextConnector.UPDATE, { detail: context })
+    );
   }
+  /**
+   * Subscribe to an event. Returns a disposer that removes the listener,
+   * convenient for React `useEffect` cleanup.
+   */
   on(event, callback) {
-    this.addEventListener(event, (e) => {
-      callback(e.detail);
-    });
+    if (!this.#wrappers.has(callback)) {
+      const wrapper = (e) => callback(e.detail);
+      this.#wrappers.set(callback, wrapper);
+      this.addEventListener(event, wrapper);
+    }
+    return () => this.off(event, callback);
   }
+  /** Subscribe to context updates. Returns a disposer. */
   onUpdate(callback) {
-    this.on(_ContextConnector.UPDATE, callback);
+    return this.on(_ContextConnector.UPDATE, callback);
+  }
+  /** Remove a listener previously added with {@link on}. */
+  off(event, callback) {
+    const wrapper = this.#wrappers.get(callback);
+    if (wrapper) {
+      this.removeEventListener(event, wrapper);
+      this.#wrappers.delete(callback);
+    }
   }
-  tearDown(fn) {
-    this.removeEventListener(_ContextConnector.UPDATE, fn);
+  /** Remove a context-update listener previously added with {@link onUpdate}. */
+  tearDown(callback) {
+    this.off(_ContextConnector.UPDATE, callback);
   }
 };
 

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../lib/context-connector.ts","../lib/util/mount-app.tsx","../lib/react-application-mixin.ts","../lib/react-application-v2.ts","../lib/react-actor-sheet-v2.ts"],"sourcesContent":["export class ContextConnector<T> extends EventTarget {\n  static UPDATE = \"contextUpdate\";\n\n  constructor() {\n    super();\n  }\n\n  publishContext(context: T) {\n    this.dispatchEvent(new CustomEvent(\"contextUpdate\", { detail: context }));\n  }\n\n  on(event: string, callback: (data: T) => void) {\n    this.addEventListener(event, (e: CustomEventInit<T>) => {\n      callback(e.detail!);\n    });\n  }\n\n  onUpdate(callback: (data: T) => void) {\n    this.on(ContextConnector.UPDATE, callback);\n  }\n\n  tearDown(fn: (data: T) => void) {\n    this.removeEventListener(ContextConnector.UPDATE, fn as EventListener);\n  }\n}\n","import { createRoot } from \"react-dom/client\";\n\nexport function mountApp({\n  App,\n  element,\n  initialProps = {},\n  innerSelector,\n}: {\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  App: React.ComponentType<any>;\n  element: Element;\n  initialProps?: {};\n  innerSelector: string;\n}) {\n  const root = createRoot(element);\n  root.render(\n    <div id={innerSelector}>\n      <App {...initialProps} />\n    </div>\n  );\n}\n","import { ContextConnector } from \"./context-connector\";\nimport { mountApp } from \"./util/mount-app\";\n\n/**\n * A mixin that integrates React components with Foundry VTT's Application class.\n * This mixin enables the use of React applications within Foundry VTT's application framework.\n *\n * @param superclass - The base class to extend, typically a Foundry VTT Application class\n * @returns A class that extends the superclass with React integration capabilities\n *\n * @remarks\n * This mixin provides the following features:\n * - Mounting React components within Foundry VTT applications\n * - Context management through ContextConnector\n * - Automatic cleanup and rendering lifecycle management\n * - Default window options for position and configuration\n *\n * @example\n * ```typescript\n * class MyReactApp extends ReactApplicationMixin(Application) {\n *   constructor(options) {\n *     super({\n *       reactApp: MyReactComponent,\n *       initialProps: { data: \"example\" },\n *       ...options\n *     });\n *   }\n * }\n * ```\n */\n\ntype ReactApplicationProps = {\n  reactApp: React.ComponentType<any>;\n  initialProps?: Record<string, any>;\n};\n\nfunction ReactApplicationMixin(Superclass: any) {\n  return class ReactApplication extends Superclass {\n    reactApp: React.ComponentType<any>;\n    uuid = foundry.utils.randomID(12);\n    rootId = `react-app-root-${this.uuid}`;\n    innerSelector = `react-application-inner-${this.rootId}`;\n    contextConnector: ContextConnector<any>;\n\n    static DEFAULT_OPTIONS = {\n      position: {\n        width: 400,\n        height: 300,\n      },\n      window: {\n        title: \"Hello React-powered Foundry applications\",\n        resizable: true,\n        minimizable: true,\n      },\n    };\n\n    initialProps = {};\n\n    constructor({ reactApp, initialProps, ...options }: ReactApplicationProps & any) {\n      super(options);\n      this.reactApp = reactApp;\n      this.contextConnector = new ContextConnector();\n      this.initialProps = initialProps || {};\n    }\n\n    get appIsRendered() {\n      return !!document.querySelector(`#${this.innerSelector}`);\n    }\n\n    async _onRender(context: any, options: any) {\n      await super._onRender(context, options);\n      const el = this.element.querySelectorAll(`#${this.rootId}`);\n\n      if (el && !this.appIsRendered) {\n        mountApp({\n          App: this.reactApp,\n          element: el[0],\n          initialProps: context.initialProps,\n          innerSelector: this.innerSelector,\n        });\n      }\n      this.contextConnector.publishContext(context);\n    }\n\n    _replaceHTML(result: HTMLElement, content: HTMLElement) {\n      if (!this.appIsRendered) {\n        content.appendChild(result);\n      }\n    }\n\n    async _prepareContext(options: any) {\n      const context = (await super._prepareContext(options)) as any;\n      context.initialProps = this.initialProps;\n      return context;\n    }\n\n    async _renderHTML() {\n      const tempEl = document.createElement(\"div\");\n      tempEl.id = this.rootId;\n      tempEl.innerHTML = `<span>Uh oh, something went wrong</span>`;\n      return tempEl;\n    }\n  };\n}\n\nexport default ReactApplicationMixin;\n","import ReactApplicationMixin from \"./react-application-mixin\";\n\n/**\n * A Foundry VTT Application class that integrates React components with the Foundry application framework.\n * Extends ApplicationV2 to provide seamless React app mounting and rendering capabilities.\n *\n * @class FoundryReactApplication\n * @extends foundry.applications.api.ApplicationV2\n *\n * @example\n * // Create a new React-powered Foundry application\n * const app = new FoundryReactApplication({\n *   reactApp: MyReactComponent,\n *   initialProps: { data: 'example' },\n *   window: { title: \"My React App\" },\n *   position: { width: 600, height: 400 }\n * });\n *\n * @property {React.Component} reactApp - The React component to be mounted\n * @property {string} template - Path to the Handlebars template for the application shell\n * @property {Object} initialProps - Initial properties passed to the React component\n * @property {string} rootId - ID added to the root element where the React app will be mounted\n */\nexport class ReactApplicationV2 extends ReactApplicationMixin(foundry.applications.api.ApplicationV2) {}\n","/**\n * A React-enabled version of Foundry VTT's ActorSheetV2 class.\n *\n * This class extends the core ActorSheetV2 functionality by applying the ReactApplicationMixin,\n * which enables React component rendering within the actor sheet application.\n *\n * @extends {foundry.applications.sheets.ActorSheetV2}\n * @mixes ReactApplicationMixin\n *\n * @example\n * ```typescript\n * class MyActorSheet extends ReactActorSheetV2 {\n *   // Your custom React-enabled actor sheet implementation\n * }\n * ```\n */\nimport ReactApplicationMixin from \"./react-application-mixin\";\n\nexport class ReactActorSheetV2 extends ReactApplicationMixin(foundry.applications.sheets.ActorSheetV2) {}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../lib/context-connector.ts","../lib/util/mount-app.tsx","../lib/react-application-mixin.ts","../lib/react-application-v2.ts","../lib/react-actor-sheet-v2.ts"],"sourcesContent":["/**\n * Event-based bridge for pushing Foundry context updates into React.\n *\n * A `ReactApplicationMixin` instance creates one connector and calls\n * {@link ContextConnector.publishContext} on every render. React components\n * subscribe with {@link ContextConnector.onUpdate} to re-render on changes.\n */\nexport class ContextConnector<T> extends EventTarget {\n  static UPDATE = \"contextUpdate\";\n\n  /**\n   * Maps each subscriber callback to the wrapper actually registered with\n   * `addEventListener`, so `off`/`tearDown` can remove it by the original\n   * callback reference.\n   */\n  #wrappers = new Map<(data: T) => void, EventListener>();\n\n  publishContext(context: T) {\n    this.dispatchEvent(\n      new CustomEvent(ContextConnector.UPDATE, { detail: context })\n    );\n  }\n\n  /**\n   * Subscribe to an event. Returns a disposer that removes the listener,\n   * convenient for React `useEffect` cleanup.\n   */\n  on(event: string, callback: (data: T) => void): () => void {\n    if (!this.#wrappers.has(callback)) {\n      const wrapper: EventListener = (e) =>\n        callback((e as CustomEvent<T>).detail);\n      this.#wrappers.set(callback, wrapper);\n      this.addEventListener(event, wrapper);\n    }\n    return () => this.off(event, callback);\n  }\n\n  /** Subscribe to context updates. Returns a disposer. */\n  onUpdate(callback: (data: T) => void): () => void {\n    return this.on(ContextConnector.UPDATE, callback);\n  }\n\n  /** Remove a listener previously added with {@link on}. */\n  off(event: string, callback: (data: T) => void) {\n    const wrapper = this.#wrappers.get(callback);\n    if (wrapper) {\n      this.removeEventListener(event, wrapper);\n      this.#wrappers.delete(callback);\n    }\n  }\n\n  /** Remove a context-update listener previously added with {@link onUpdate}. */\n  tearDown(callback: (data: T) => void) {\n    this.off(ContextConnector.UPDATE, callback);\n  }\n}\n","import { createRoot } from \"react-dom/client\";\n\nexport function mountApp({\n  App,\n  element,\n  initialProps = {},\n  innerSelector,\n}: {\n  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */\n  App: React.ComponentType<any>;\n  element: Element;\n  initialProps?: {};\n  innerSelector: string;\n}) {\n  const root = createRoot(element);\n  root.render(\n    <div id={innerSelector}>\n      <App {...initialProps} />\n    </div>\n  );\n}\n","import { ContextConnector } from \"./context-connector\";\nimport { mountApp } from \"./util/mount-app\";\n\n/**\n * A mixin that integrates React components with Foundry VTT's Application class.\n * This mixin enables the use of React applications within Foundry VTT's application framework.\n *\n * @param superclass - The base class to extend, typically a Foundry VTT Application class\n * @returns A class that extends the superclass with React integration capabilities\n *\n * @remarks\n * This mixin provides the following features:\n * - Mounting React components within Foundry VTT applications\n * - Context management through ContextConnector\n * - Automatic cleanup and rendering lifecycle management\n * - Default window options for position and configuration\n *\n * @example\n * ```typescript\n * class MyReactApp extends ReactApplicationMixin(Application) {\n *   constructor(options) {\n *     super({\n *       reactApp: MyReactComponent,\n *       initialProps: { data: \"example\" },\n *       ...options\n *     });\n *   }\n * }\n * ```\n */\n\ntype ReactApplicationProps = {\n  reactApp: React.ComponentType<any>;\n  initialProps?: Record<string, any>;\n};\n\nfunction ReactApplicationMixin(Superclass: any) {\n  return class ReactApplication extends Superclass {\n    reactApp: React.ComponentType<any>;\n    uuid = foundry.utils.randomID(12);\n    rootId = `react-app-root-${this.uuid}`;\n    innerSelector = `react-application-inner-${this.rootId}`;\n    contextConnector: ContextConnector<any>;\n\n    static DEFAULT_OPTIONS = {\n      position: {\n        width: 400,\n        height: 300,\n      },\n      window: {\n        title: \"Hello React-powered Foundry applications\",\n        resizable: true,\n        minimizable: true,\n      },\n    };\n\n    initialProps = {};\n\n    constructor({ reactApp, initialProps, ...options }: ReactApplicationProps & any) {\n      super(options);\n      this.reactApp = reactApp;\n      this.contextConnector = new ContextConnector();\n      this.initialProps = initialProps || {};\n    }\n\n    get appIsRendered() {\n      return !!document.querySelector(`#${this.innerSelector}`);\n    }\n\n    async _onRender(context: any, options: any) {\n      await super._onRender(context, options);\n      const el = this.element.querySelectorAll(`#${this.rootId}`);\n\n      if (el && !this.appIsRendered) {\n        mountApp({\n          App: this.reactApp,\n          element: el[0],\n          initialProps: context.initialProps,\n          innerSelector: this.innerSelector,\n        });\n      }\n      this.contextConnector.publishContext(context);\n    }\n\n    _replaceHTML(result: HTMLElement, content: HTMLElement) {\n      if (!this.appIsRendered) {\n        content.appendChild(result);\n      }\n    }\n\n    async _prepareContext(options: any) {\n      const context = (await super._prepareContext(options)) as any;\n      context.initialProps = this.initialProps;\n      return context;\n    }\n\n    async _renderHTML() {\n      const tempEl = document.createElement(\"div\");\n      tempEl.id = this.rootId;\n      tempEl.innerHTML = `<span>Uh oh, something went wrong</span>`;\n      return tempEl;\n    }\n  };\n}\n\nexport default ReactApplicationMixin;\n","import ReactApplicationMixin from \"./react-application-mixin\";\n\n/**\n * A Foundry VTT Application class that integrates React components with the Foundry application framework.\n * Extends ApplicationV2 to provide seamless React app mounting and rendering capabilities.\n *\n * @class FoundryReactApplication\n * @extends foundry.applications.api.ApplicationV2\n *\n * @example\n * // Create a new React-powered Foundry application\n * const app = new FoundryReactApplication({\n *   reactApp: MyReactComponent,\n *   initialProps: { data: 'example' },\n *   window: { title: \"My React App\" },\n *   position: { width: 600, height: 400 }\n * });\n *\n * @property {React.Component} reactApp - The React component to be mounted\n * @property {string} template - Path to the Handlebars template for the application shell\n * @property {Object} initialProps - Initial properties passed to the React component\n * @property {string} rootId - ID added to the root element where the React app will be mounted\n */\nexport class ReactApplicationV2 extends ReactApplicationMixin(foundry.applications.api.ApplicationV2) {}\n","/**\n * A React-enabled version of Foundry VTT's ActorSheetV2 class.\n *\n * This class extends the core ActorSheetV2 functionality by applying the ReactApplicationMixin,\n * which enables React component rendering within the actor sheet application.\n *\n * @extends {foundry.applications.sheets.ActorSheetV2}\n * @mixes ReactApplicationMixin\n *\n * @example\n * ```typescript\n * class MyActorSheet extends ReactActorSheetV2 {\n *   // Your custom React-enabled actor sheet implementation\n * }\n * ```\n */\nimport ReactApplicationMixin from \"./react-application-mixin\";\n\nexport class ReactActorSheetV2 extends ReactApplicationMixin(foundry.applications.sheets.ActorSheetV2) {}\n"],"mappings":";;;;;AAOO,IAAM,mBAAN,MAAM,0BAA4B,YAAY;AAAA,EACnD,OAAO,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOhB,YAAY,oBAAI,IAAsC;AAAA,EAEtD,eAAe,SAAY;AACzB,SAAK;AAAA,MACH,IAAI,YAAY,kBAAiB,QAAQ,EAAE,QAAQ,QAAQ,CAAC;AAAA,IAC9D;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,GAAG,OAAe,UAAyC;AACzD,QAAI,CAAC,KAAK,UAAU,IAAI,QAAQ,GAAG;AACjC,YAAM,UAAyB,CAAC,MAC9B,SAAU,EAAqB,MAAM;AACvC,WAAK,UAAU,IAAI,UAAU,OAAO;AACpC,WAAK,iBAAiB,OAAO,OAAO;AAAA,IACtC;AACA,WAAO,MAAM,KAAK,IAAI,OAAO,QAAQ;AAAA,EACvC;AAAA;AAAA,EAGA,SAAS,UAAyC;AAChD,WAAO,KAAK,GAAG,kBAAiB,QAAQ,QAAQ;AAAA,EAClD;AAAA;AAAA,EAGA,IAAI,OAAe,UAA6B;AAC9C,UAAM,UAAU,KAAK,UAAU,IAAI,QAAQ;AAC3C,QAAI,SAAS;AACX,WAAK,oBAAoB,OAAO,OAAO;AACvC,WAAK,UAAU,OAAO,QAAQ;AAAA,IAChC;AAAA,EACF;AAAA;AAAA,EAGA,SAAS,UAA6B;AACpC,SAAK,IAAI,kBAAiB,QAAQ,QAAQ;AAAA,EAC5C;AACF;;;ACvDA,SAAS,kBAAkB;AAiBrB;AAfC,SAAS,SAAS;AAAA,EACvB;AAAA,EACA;AAAA,EACA,eAAe,CAAC;AAAA,EAChB;AACF,GAMG;AACD,QAAM,OAAO,WAAW,OAAO;AAC/B,OAAK;AAAA,IACH,oBAAC,SAAI,IAAI,eACP,8BAAC,OAAK,GAAG,cAAc,GACzB;AAAA,EACF;AACF;;;ACgBA,SAAS,sBAAsB,YAAiB;AAC9C,SAAO,MAAM,yBAAyB,WAAW;AAAA,IAC/C;AAAA,IACA,OAAO,QAAQ,MAAM,SAAS,EAAE;AAAA,IAChC,SAAS,kBAAkB,KAAK,IAAI;AAAA,IACpC,gBAAgB,2BAA2B,KAAK,MAAM;AAAA,IACtD;AAAA,IAEA,OAAO,kBAAkB;AAAA,MACvB,UAAU;AAAA,QACR,OAAO;AAAA,QACP,QAAQ;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,QACN,OAAO;AAAA,QACP,WAAW;AAAA,QACX,aAAa;AAAA,MACf;AAAA,IACF;AAAA,IAEA,eAAe,CAAC;AAAA,IAEhB,YAAY,EAAE,UAAU,cAAc,GAAG,QAAQ,GAAgC;AAC/E,YAAM,OAAO;AACb,WAAK,WAAW;AAChB,WAAK,mBAAmB,IAAI,iBAAiB;AAC7C,WAAK,eAAe,gBAAgB,CAAC;AAAA,IACvC;AAAA,IAEA,IAAI,gBAAgB;AAClB,aAAO,CAAC,CAAC,SAAS,cAAc,IAAI,KAAK,aAAa,EAAE;AAAA,IAC1D;AAAA,IAEA,MAAM,UAAU,SAAc,SAAc;AAC1C,YAAM,MAAM,UAAU,SAAS,OAAO;AACtC,YAAM,KAAK,KAAK,QAAQ,iBAAiB,IAAI,KAAK,MAAM,EAAE;AAE1D,UAAI,MAAM,CAAC,KAAK,eAAe;AAC7B,iBAAS;AAAA,UACP,KAAK,KAAK;AAAA,UACV,SAAS,GAAG,CAAC;AAAA,UACb,cAAc,QAAQ;AAAA,UACtB,eAAe,KAAK;AAAA,QACtB,CAAC;AAAA,MACH;AACA,WAAK,iBAAiB,eAAe,OAAO;AAAA,IAC9C;AAAA,IAEA,aAAa,QAAqB,SAAsB;AACtD,UAAI,CAAC,KAAK,eAAe;AACvB,gBAAQ,YAAY,MAAM;AAAA,MAC5B;AAAA,IACF;AAAA,IAEA,MAAM,gBAAgB,SAAc;AAClC,YAAM,UAAW,MAAM,MAAM,gBAAgB,OAAO;AACpD,cAAQ,eAAe,KAAK;AAC5B,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,cAAc;AAClB,YAAM,SAAS,SAAS,cAAc,KAAK;AAC3C,aAAO,KAAK,KAAK;AACjB,aAAO,YAAY;AACnB,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEA,IAAO,kCAAQ;;;AClFR,IAAM,qBAAN,cAAiC,gCAAsB,QAAQ,aAAa,IAAI,aAAa,EAAE;AAAC;;;ACLhG,IAAM,oBAAN,cAAgC,gCAAsB,QAAQ,aAAa,OAAO,YAAY,EAAE;AAAC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foundry-vtt-react",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Extensions of various FoundryVTT classes to support React applications.",
   "packageManager": "pnpm@10.30.3",
   "main": "dist/index.mjs",
@@ -24,8 +24,16 @@
     "prepublishOnly": "pnpm build"
   },
   "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "author": "Tim Sandberg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tasandberg/foundry-vtt-react.git"
+  },
+  "homepage": "https://github.com/tasandberg/foundry-vtt-react#readme",
+  "bugs": {
+    "url": "https://github.com/tasandberg/foundry-vtt-react/issues"
+  },
   "devDependencies": {
     "fvtt-types": "^13",
     "tsup": "^8.5.1",