@citewidget/vue 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,72 @@
-# Temporary Holding Version
+# @citewidget/vue
 
-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 Vue 3 and Nuxt: visitors ask questions and get answers from your
+documents, with links to the pages they came from.
+
+```sh
+npm install @citewidget/vue
+```
+
+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
+
+```vue
+<script setup lang="ts">
+import { CiteWidget } from "@citewidget/vue";
+</script>
+
+<template>
+  <RouterView />
+  <CiteWidget workspace-key="pk_..." primary-color="#0F766E" />
+</template>
+```
+
+`<CiteWidget>` renders nothing where you place it: when mounted it adds the chat as a fixed
+overlay at the end of `<body>`. Put it once in your root component or layout.
+
+### Nuxt
+
+The component only mounts the widget in `onMounted`, so server rendering outputs nothing and
+never touches the browser. Use it in `app.vue` or a layout as above; wrapping it in
+`<ClientOnly>` is optional.
+
+## Your own button
+
+```vue
+<script setup lang="ts">
+import { useCiteWidget } from "@citewidget/vue";
+const widget = useCiteWidget();
+</script>
+
+<template>
+  <button type="button" @click="widget.open">Ask about this product</button>
+</template>
+```
+
+`useCiteWidget()` returns `open`, `close`, `toggle` and `newChat` for the mounted `<CiteWidget>`
+(the newest one if there are several). Combine it with `:show-launcher="false"` to hide the
+round button. Calling them while no widget is mounted logs a warning and does nothing.
+
+## Props and events
+
+Every option of `createCiteWidget` from
+[`@citewidget/widget`](https://www.npmjs.com/package/@citewidget/widget) is a prop (kebab-case in
+templates): `workspace-key` (required), `api-url`, `server-url`, `load-dashboard-settings`,
+`title`, `greeting`, `bot-name`, `primary-color`, `surface-color`, `color-scheme`, `position`,
+`show-launcher`, `launcher-label`, `launcher-icon`, `launcher-icon-url`, `soft-refusal`,
+`goodbye`, `suggestions`, `handoff`, `handoff-reply-time`, `lead-capture`,
+`chat-duration-minutes`, `nonce`. See that package for types, limits and defaults.
+
+Events `open`, `close` and `handoff` are emitted with no payload: nothing a visitor typed reaches
+your code.
+
+- Settings combine as: built-in defaults < your CiteWidget dashboard < props. A boolean prop you
+  don't set stays unset (not `false`), and clearing a prop hands it back to the dashboard.
+- Changing props updates the widget; it is rebuilt only when something visible changed.
+- A missing or invalid `workspace-key` 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,99 @@
+import { type PropType } from "vue";
+import { type CiteWidgetColorScheme, type CiteWidgetLauncherIcon, type CiteWidgetPosition } from "@citewidget/widget";
+/**
+ * The CiteWidget chat for Vue 3 / Nuxt. Renders nothing in place: the widget is a fixed overlay
+ * appended to <body> in onMounted, so server rendering (Nuxt SSR) never touches the browser.
+ * Emits open, close and handoff with no payload.
+ */
+export declare const CiteWidget: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    workspaceKey: {
+        type: StringConstructor;
+        required: true;
+    };
+    apiUrl: StringConstructor;
+    serverUrl: StringConstructor;
+    loadDashboardSettings: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    title: StringConstructor;
+    greeting: StringConstructor;
+    botName: StringConstructor;
+    primaryColor: StringConstructor;
+    surfaceColor: StringConstructor;
+    colorScheme: PropType<CiteWidgetColorScheme>;
+    position: PropType<CiteWidgetPosition>;
+    showLauncher: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    launcherLabel: StringConstructor;
+    launcherIcon: PropType<CiteWidgetLauncherIcon>;
+    launcherIconUrl: StringConstructor;
+    softRefusal: StringConstructor;
+    goodbye: StringConstructor;
+    suggestions: PropType<readonly string[]>;
+    handoff: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    handoffReplyTime: StringConstructor;
+    leadCapture: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    chatDurationMinutes: NumberConstructor;
+    nonce: StringConstructor;
+}>, () => null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    open: () => true;
+    close: () => true;
+    handoff: () => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    workspaceKey: {
+        type: StringConstructor;
+        required: true;
+    };
+    apiUrl: StringConstructor;
+    serverUrl: StringConstructor;
+    loadDashboardSettings: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    title: StringConstructor;
+    greeting: StringConstructor;
+    botName: StringConstructor;
+    primaryColor: StringConstructor;
+    surfaceColor: StringConstructor;
+    colorScheme: PropType<CiteWidgetColorScheme>;
+    position: PropType<CiteWidgetPosition>;
+    showLauncher: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    launcherLabel: StringConstructor;
+    launcherIcon: PropType<CiteWidgetLauncherIcon>;
+    launcherIconUrl: StringConstructor;
+    softRefusal: StringConstructor;
+    goodbye: StringConstructor;
+    suggestions: PropType<readonly string[]>;
+    handoff: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    handoffReplyTime: StringConstructor;
+    leadCapture: {
+        readonly type: BooleanConstructor;
+        readonly default: undefined;
+    };
+    chatDurationMinutes: NumberConstructor;
+    nonce: StringConstructor;
+}>> & Readonly<{
+    onClose?: (() => any) | undefined;
+    onHandoff?: (() => any) | undefined;
+    onOpen?: (() => any) | undefined;
+}>, {
+    loadDashboardSettings: boolean;
+    showLauncher: boolean;
+    handoff: boolean;
+    leadCapture: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @citewidget/vue: the CiteWidget chat for Vue 3 and Nuxt. Safe in server rendering: the widget
+ * mounts in onMounted only.
+ */
+export { CiteWidget } from "./CiteWidget";
+export { useCiteWidget, type CiteWidgetControls } from "./useCiteWidget";
+export type { CiteWidgetColorScheme, CiteWidgetLauncherIcon, CiteWidgetOptions, CiteWidgetPosition, } from "@citewidget/widget";

package/dist/index.js

@@ -0,0 +1,108 @@
+// src/CiteWidget.ts
+import { defineComponent, onBeforeUnmount, onMounted, watch } from "vue";
+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 optionalBoolean = { type: Boolean, default: void 0 }, CiteWidget = defineComponent({
+  name: "CiteWidget",
+  props: {
+    workspaceKey: { type: String, required: !0 },
+    apiUrl: String,
+    serverUrl: String,
+    loadDashboardSettings: optionalBoolean,
+    title: String,
+    greeting: String,
+    botName: String,
+    primaryColor: String,
+    surfaceColor: String,
+    colorScheme: String,
+    position: String,
+    showLauncher: optionalBoolean,
+    launcherLabel: String,
+    launcherIcon: String,
+    launcherIconUrl: String,
+    softRefusal: String,
+    goodbye: String,
+    suggestions: Array,
+    handoff: optionalBoolean,
+    handoffReplyTime: String,
+    leadCapture: optionalBoolean,
+    chatDurationMinutes: Number,
+    nonce: String
+  },
+  emits: {
+    open: () => !0,
+    close: () => !0,
+    handoff: () => !0
+  },
+  setup(props, { emit }) {
+    let widget = null, unregister = () => {
+    }, options = () => ({ ...props }), start = () => {
+      try {
+        widget = createCiteWidget({
+          ...options(),
+          onOpen: () => emit("open"),
+          onClose: () => emit("close"),
+          onHandoff: () => emit("handoff")
+        });
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        return;
+      }
+      unregister = registerWidget(widget);
+    };
+    return onMounted(start), watch(
+      options,
+      (next) => {
+        if (!widget) {
+          start();
+          return;
+        }
+        try {
+          widget.update(next);
+        } catch (error) {
+          console.error(error instanceof Error ? error.message : error);
+        }
+      },
+      { deep: !0 }
+    ), onBeforeUnmount(() => {
+      unregister(), widget?.destroy(), widget = null;
+    }), () => 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 app without provide/inject. Written only in onMounted / onBeforeUnmount
+ * (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>; plain functions, safe to bind to @click. */
+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 button with
+ * :show-launcher="false" on the widget). With several mounted, the newest one wins.
+ */
+export declare function useCiteWidget(): CiteWidgetControls;

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@citewidget/vue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CiteWidget chat for Vue 3 and Nuxt: <CiteWidget workspace-key=\"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",
+    "vue",
+    "nuxt",
+    "chat-widget"
+  ],
+  "homepage": "https://citewidget.com",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@citewidget/widget": "0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}