@citewidget/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CiteWidget
+
+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,3 +1,93 @@
-# Temporary Holding Version
+# @citewidget/react
 
-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.
+The CiteWidget chat for React and Next.js: visitors ask questions and get answers from your
+documents, with links to the pages they came from. React 18 or 19.
+
+```sh
+npm install @citewidget/react
+```
+
+This package is ES modules only (no CommonJS build): use `import`, not `require()`. Every current bundler and Node 22+ handle that; with an older CommonJS-only setup, load the script tag version instead.
+
+## Quick start
+
+```tsx
+import { CiteWidget } from "@citewidget/react";
+
+export function App() {
+  return (
+    <>
+      {/* your app */}
+      <CiteWidget workspaceKey="pk_..." primaryColor="#0F766E" />
+    </>
+  );
+}
+```
+
+`<CiteWidget>` renders nothing where you place it: after mounting it adds the chat as a fixed
+overlay at the end of `<body>`. Put it once, high in the tree (a layout), so it stays mounted
+across pages.
+
+### Next.js (App Router)
+
+The package is marked `"use client"`, so a server component such as `app/layout.tsx` can render
+it directly. Nothing touches `window` or `document` during server rendering.
+
+```tsx
+// app/layout.tsx
+import { CiteWidget } from "@citewidget/react";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <CiteWidget workspaceKey={process.env.NEXT_PUBLIC_CITEWIDGET_KEY!} />
+      </body>
+    </html>
+  );
+}
+```
+
+The workspace key is public (it starts with `pk_`), so a `NEXT_PUBLIC_` variable is fine.
+
+## Your own button
+
+```tsx
+"use client";
+import { useCiteWidget } from "@citewidget/react";
+
+export function AskButton() {
+  const widget = useCiteWidget();
+  return <button onClick={widget.open}>Ask about this product</button>;
+}
+```
+
+`useCiteWidget()` returns stable `open`, `close`, `toggle` and `newChat` functions for the
+mounted `<CiteWidget>` (the newest one if there are several). Combine it with
+`showLauncher={false}` to hide the round button. Calling them while no widget is mounted logs a
+warning and does nothing.
+
+## Props
+
+Every option of `createCiteWidget` from
+[`@citewidget/widget`](https://www.npmjs.com/package/@citewidget/widget) is a prop:
+`workspaceKey` (required), `apiUrl`, `serverUrl`, `loadDashboardSettings`, `title`, `greeting`,
+`botName`, `primaryColor`, `surfaceColor`, `colorScheme`, `position`, `showLauncher`,
+`launcherLabel`, `launcherIcon`, `launcherIconUrl`, `softRefusal`, `goodbye`, `suggestions`,
+`handoff`, `handoffReplyTime`, `leadCapture`, `chatDurationMinutes`, `nonce`, and the callbacks
+`onOpen`, `onClose`, `onHandoff` (called with no arguments). See that package for types, limits
+and defaults.
+
+- Settings combine as: built-in defaults < your CiteWidget dashboard < props. Removing a prop
+  hands that setting back to the dashboard.
+- Changing props updates the widget; it is rebuilt only when something visible changed (a new
+  array with the same questions, or a new callback function, changes nothing). Callbacks always
+  use your latest props.
+- Under React Strict Mode's double mount you still get exactly one widget.
+- A missing or invalid `workspaceKey` is logged with `console.error` and nothing is shown; other
+  invalid values are ignored with a console warning.
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).

package/dist/CiteWidget.d.ts

@@ -0,0 +1,8 @@
+import { type CiteWidgetOptions } from "@citewidget/widget";
+/** Every createCiteWidget() option as a prop; workspaceKey is required. */
+export type CiteWidgetProps = CiteWidgetOptions;
+/**
+ * The CiteWidget chat. Renders nothing in place: the widget is a fixed overlay appended to
+ * <body> after mount, so it is safe in server rendering and under Strict Mode.
+ */
+export declare function CiteWidget(props: CiteWidgetProps): null;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @citewidget/react: the CiteWidget chat for React and Next.js (App Router: the build keeps
+ * "use client"; nothing touches window or document during server rendering).
+ */
+export { CiteWidget, type CiteWidgetProps } from "./CiteWidget";
+export { useCiteWidget, type CiteWidgetControls } from "./useCiteWidget";
+export type { CiteWidgetColorScheme, CiteWidgetLauncherIcon, CiteWidgetOptions, CiteWidgetPosition, } from "@citewidget/widget";

package/dist/index.js

@@ -0,0 +1,73 @@
+"use client";
+
+// src/CiteWidget.ts
+import { useEffect, useRef } from "react";
+import { createCiteWidget } from "@citewidget/widget";
+
+// src/registry.ts
+var mounted = [];
+function registerWidget(widget) {
+  return mounted = [...mounted, widget], () => {
+    mounted = mounted.filter((entry) => entry !== widget);
+  };
+}
+function currentWidget() {
+  return mounted[mounted.length - 1] ?? null;
+}
+
+// src/CiteWidget.ts
+var CALLBACKS = /* @__PURE__ */ new Set(["onOpen", "onClose", "onHandoff"]);
+function dataOptions(props) {
+  return Object.fromEntries(Object.entries(props).filter(([key]) => !CALLBACKS.has(key)));
+}
+function patchFrom(next, previous) {
+  return { ...Object.fromEntries(Object.keys(previous).map((key) => [key, void 0])), ...next };
+}
+function CiteWidget(props) {
+  let latest = useRef(props), widget = useRef(null), unregister = useRef(() => {
+  }), sent = useRef({ workspaceKey: props.workspaceKey }), sentKey = useRef(""), optionsKey = JSON.stringify(dataOptions(props));
+  return useEffect(() => {
+    latest.current = props;
+  }), useEffect(
+    () => () => {
+      unregister.current(), widget.current?.destroy(), widget.current = null, sentKey.current = "";
+    },
+    []
+  ), useEffect(() => {
+    if (optionsKey === sentKey.current) return;
+    let next = dataOptions(latest.current);
+    try {
+      widget.current ? widget.current.update(patchFrom(next, sent.current)) : (widget.current = createCiteWidget({
+        ...next,
+        onOpen: () => latest.current.onOpen?.(),
+        onClose: () => latest.current.onClose?.(),
+        onHandoff: () => latest.current.onHandoff?.()
+      }), unregister.current = registerWidget(widget.current)), sent.current = next, sentKey.current = optionsKey;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : error);
+    }
+  }, [optionsKey]), null;
+}
+
+// src/useCiteWidget.ts
+function call(method) {
+  let widget = currentWidget();
+  if (widget) {
+    widget[method]();
+    return;
+  }
+  console.warn(`[CiteWidget] ${method}() was called, but no <CiteWidget> is mounted.`);
+}
+var controls = Object.freeze({
+  open: () => call("open"),
+  close: () => call("close"),
+  toggle: () => call("toggle"),
+  newChat: () => call("newChat")
+});
+function useCiteWidget() {
+  return controls;
+}
+export {
+  CiteWidget,
+  useCiteWidget
+};

package/dist/registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The widgets <CiteWidget> has mounted, newest last, so useCiteWidget() can reach the current one
+ * from anywhere in the tree without a provider. Written only from effects (browser), so server
+ * rendering never sees or shares it.
+ */
+import type { CiteWidgetController } from "@citewidget/widget";
+/** Adds a widget; the returned function removes it again. */
+export declare function registerWidget(widget: CiteWidgetController): () => void;
+/** The most recently mounted widget, or null. */
+export declare function currentWidget(): CiteWidgetController | null;

package/dist/useCiteWidget.d.ts

@@ -0,0 +1,13 @@
+/** Controls for the mounted <CiteWidget>; stable across renders, safe to pass to onClick. */
+export interface CiteWidgetControls {
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Clears the conversation. */
+    newChat(): void;
+}
+/**
+ * Opens, closes or resets the mounted <CiteWidget> from your own UI (for example a "Ask about
+ * this product" button with showLauncher={false}). With several mounted, the newest one wins.
+ */
+export declare function useCiteWidget(): CiteWidgetControls;

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@citewidget/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CiteWidget chat for React and Next.js: <CiteWidget workspaceKey=\"pk_...\" /> and useCiteWidget().",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "citewidget",
+    "react",
+    "nextjs",
+    "chat-widget"
+  ],
+  "homepage": "https://citewidget.com",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@citewidget/widget": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}