@ganeshdole/brainbox-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+O'Saasy License
+
+Copyright © 2026, Ganesh Dole.
+
+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:
+
+1. The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including
+any modified or derivative versions) to directly compete with the
+original Licensor by offering it to third parties as a hosted, managed,
+or Software-as-a-Service (SaaS) product or cloud service where the
+primary value of the service is the functionality of the Software itself.
+
+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,3 +1,69 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @ganeshdole/brainbox-react
+
+React bindings for `@ganeshdole/brainbox-core`: a provider that owns one instance, and
+hooks that read it. The `react-redux` to core's `redux`. No UI lives here;
+for Brainbox's own widget see `@ganeshdole/brainbox-widget`.
+
+## Install
+
+Inside this monorepo the package is consumed from source. `react` (19+) is a
+peer dependency, so a host ends up with one copy.
+
+```json
+{ "dependencies": { "@ganeshdole/brainbox-react": "workspace:*" } }
+```
+
+Outside it, from npm:
+
+```sh
+npm install @ganeshdole/brainbox-react @ganeshdole/brainbox-core
+```
+
+`pnpm build` emits `dist/` (JS plus `.d.ts`); the published package's
+`exports` point at it (`publishConfig`).
+
+## Use
+
+```tsx
+import { BrainboxProvider, useBrainbox, useDraft } from "@ganeshdole/brainbox-react";
+import { brainboxTransport } from "@ganeshdole/brainbox-core";
+
+// Keep the transport stable: a new one means a new instance.
+const transport = brainboxTransport({ endpoint, projectKey });
+
+export function Root() {
+  return (
+    <BrainboxProvider transport={transport} identity={{ id: user.id, email: user.email }}>
+      <App />
+    </BrainboxProvider>
+  );
+}
+```
+
+Your own UI on top of the engine:
+
+```tsx
+function FeedbackPanel() {
+  const brainbox = useBrainbox();           // null on the server and the first render
+  const panel = useRef<HTMLDivElement>(null);
+  const draft = useMemo(() => brainbox?.draft({ exclude: panel.current ?? undefined }), [brainbox]);
+  if (!draft) return null;
+  return <Panel ref={panel} draft={draft} />;
+}
+
+function Panel({ draft }: { draft: Draft }) {
+  const state = useDraft(draft);            // re-renders on every change
+  return state.screenshotPending ? <Spinner /> : <img src={state.screenshotUrl ?? ""} />;
+}
+```
+
+## How the provider behaves
+
+- The instance is created in an effect and destroyed in the cleanup. That
+  keeps a server render side-effect free and leaves exactly one instance
+  under StrictMode's mount-unmount-mount. The cost is one render in which
+  `useBrainbox()` is `null`.
+- `identity` changes call `identify()` on the live instance. `onSubmitted`
+  may change freely. Only a new `transport` rebuilds the instance.
+- `<BrainboxProvider brainbox={instance}>` provides an instance you created
+  and own. Shells outside React (the script-tag bundle) use this.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { BrainboxProvider, useBrainbox, type BrainboxProviderProps } from "./provider.tsx";
+export { useDraft } from "./use-draft.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+// @ganeshdole/brainbox-react - React bindings for @ganeshdole/brainbox-core.
+export { BrainboxProvider, useBrainbox } from "./provider.js";
+export { useDraft } from "./use-draft.js";

package/dist/provider.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import { type Brainbox, type Identity, type SubmitResult, type Transport } from "@ganeshdole/brainbox-core";
+interface OwnedProps {
+    /** Where finished reports go. Keep it stable (module-level or `useMemo`):
+     *  a new transport means a new instance. */
+    transport: Transport;
+    /** Who is filing. Changing it calls `identify()` on the live instance. */
+    identity?: Identity;
+    /** Called after every successful submit. May change between renders. */
+    onSubmitted?: (result: SubmitResult) => void;
+    brainbox?: never;
+}
+interface GivenProps {
+    /** An instance the caller created and will `destroy()` itself. For shells
+     *  outside React, like the script-tag bundle, that need the instance before
+     *  anything renders. */
+    brainbox: Brainbox;
+    transport?: never;
+    identity?: never;
+    onSubmitted?: never;
+}
+export type BrainboxProviderProps = (OwnedProps | GivenProps) & {
+    children?: ReactNode;
+};
+/**
+ * Makes one `Brainbox` available to the tree below it.
+ *
+ * Given `transport`, it owns the instance: created in an effect, not during
+ * render, because creating it patches `console.error`, which must not happen
+ * on the server and must happen exactly once under StrictMode's
+ * mount-unmount-mount. The cost is one render where `useBrainbox()` is still
+ * `null`. Given `brainbox`, it only provides it.
+ */
+export declare function BrainboxProvider(props: BrainboxProviderProps): import("react").JSX.Element;
+/** The nearest provider's instance. `null` during the first render and on the
+ *  server, before the provider's effect has created it. */
+export declare function useBrainbox(): Brainbox | null;
+export {};

package/dist/provider.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { createBrainbox, } from "@ganeshdole/brainbox-core";
+const BrainboxContext = createContext(null);
+/**
+ * Makes one `Brainbox` available to the tree below it.
+ *
+ * Given `transport`, it owns the instance: created in an effect, not during
+ * render, because creating it patches `console.error`, which must not happen
+ * on the server and must happen exactly once under StrictMode's
+ * mount-unmount-mount. The cost is one render where `useBrainbox()` is still
+ * `null`. Given `brainbox`, it only provides it.
+ */
+export function BrainboxProvider(props) {
+    if (props.brainbox) {
+        return (_jsx(BrainboxContext.Provider, { value: props.brainbox, children: props.children }));
+    }
+    return _jsx(OwnedProvider, { ...props });
+}
+function OwnedProvider({ transport, identity, onSubmitted, children, }) {
+    const [brainbox, setBrainbox] = useState(null);
+    // Read through refs so a new callback or identity does not rebuild the instance.
+    const onSubmittedRef = useRef(onSubmitted);
+    useEffect(() => {
+        onSubmittedRef.current = onSubmitted;
+    }, [onSubmitted]);
+    const identityRef = useRef(identity);
+    useEffect(() => {
+        identityRef.current = identity;
+    }, [identity]);
+    useEffect(() => {
+        const options = {
+            transport,
+            identity: identityRef.current,
+            onSubmitted: (result) => onSubmittedRef.current?.(result),
+        };
+        const instance = createBrainbox(options);
+        setBrainbox(instance);
+        return () => {
+            instance.destroy();
+            setBrainbox(null);
+        };
+    }, [transport]);
+    useEffect(() => {
+        if (brainbox && identity)
+            brainbox.identify(identity);
+    }, [brainbox, identity]);
+    return _jsx(BrainboxContext.Provider, { value: brainbox, children: children });
+}
+/** The nearest provider's instance. `null` during the first render and on the
+ *  server, before the provider's effect has created it. */
+export function useBrainbox() {
+    return useContext(BrainboxContext);
+}

package/dist/use-draft.d.ts

@@ -0,0 +1,3 @@
+import type { Draft, DraftState } from "@ganeshdole/brainbox-core";
+/** A draft's state, re-rendering the component whenever it changes. */
+export declare function useDraft(draft: Draft): DraftState;

package/dist/use-draft.js

@@ -0,0 +1,5 @@
+import { useSyncExternalStore } from "react";
+/** A draft's state, re-rendering the component whenever it changes. */
+export function useDraft(draft) {
+    return useSyncExternalStore(draft.subscribe, draft.getState, draft.getState);
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@ganeshdole/brainbox-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React bindings for @ganeshdole/brainbox-core: a provider that owns one Brainbox instance and hooks that read it. No UI.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://www.brainbox.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ganeshdole/brainbox.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ganeshdole/brainbox-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^10.4.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.6.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.1",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }