@dropby/vue 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simpllyf Software
+
+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,188 @@
+# `@dropby/vue`
+
+DropBy for Vue 3: a provider, composables for support chat, ideas, pending asks
+and feature flags, and optional unstyled components. It supports Vue 3.4 and
+later 3.x releases.
+
+## Installation
+
+```bash
+pnpm add @dropby/vue @dropby/browser
+```
+
+`@dropby/browser` holds the options and data types, and its README explains
+sessions, context and flags in full. Keep the two packages on the same version;
+every release publishes them together.
+
+## Provider and composables
+
+With `options`, `DropByProvider` creates the DropBy instance, starts it once
+mounted, and destroys it with its scope. Your `auth` callback calls your own
+backend, which knows who is signed in and creates the session; see
+[`@dropby/server`](https://www.npmjs.com/package/@dropby/server).
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from "vue";
+import type { DropByOptions } from "@dropby/browser";
+import { DropByProvider } from "@dropby/vue";
+import Inbox from "./Inbox.vue";
+
+const options: DropByOptions = {
+  publicKey: "YOUR_PUBLIC_KEY",
+  auth: async ({ refresh }) => {
+    const response = await fetch("/api/dropby/session", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ refresh }),
+    });
+    if (!response.ok) throw new Error("could not create a DropBy session");
+    return response.json();
+  },
+};
+
+const mounted = ref(false);
+onMounted(() => {
+  mounted.value = true;
+});
+</script>
+
+<template>
+  <DropByProvider v-if="mounted" :options="options">
+    <Inbox />
+  </DropByProvider>
+</template>
+```
+
+`Inbox.vue` lists the unread conversations. `useChatThread(id)` and
+`useFeatureFlag(name)` also take a ref or a getter, and follow it when it
+changes.
+
+<!-- snippet file=Inbox.vue -->
+
+```vue
+<script setup lang="ts">
+import { onMounted } from "vue";
+import { useChatThreads } from "@dropby/vue";
+
+const { data, actions } = useChatThreads();
+onMounted(() => void actions.listThreads({ filter: "unread" }));
+</script>
+
+<template>
+  <p>{{ data.items.length }} unread threads</p>
+</template>
+```
+
+- `useChatThreads`, `useChatThread(id)`, `useChatUnread`, `useIdeas` and
+  `usePendingAsks` return `data` as a read-only ref and a stable `actions`
+  object.
+- `useDropBy()` returns the instance. `useDropByState()` returns its live
+  `bootstrap`, `capabilities` and `connection` refs.
+- An instance passed as the provider's `dropby` prop stays yours to start and
+  destroy.
+- The `v-if` above mounts DropBy only in the browser. Never share an instance
+  across server requests.
+- The provider reads `options` once. When a user logs out, or another user or
+  account signs in, mount a new provider (give it a `:key` of the user's and
+  account's ids) so the old instance is destroyed.
+- Use the full `pk_live_...` or `pk_test_...` value from the dashboard's API
+  keys page for `YOUR_PUBLIC_KEY`.
+
+## Feature flags
+
+`useFeatureFlag(name)` returns one flag's value as a ref, and `useFeatureConfig()`
+all of them. `<Feature>` renders its default slot when a flag is on (truthy, or
+equal to `equals`), and its `fallback` slot otherwise. Before the instance
+starts, and for a flag that does not exist, the value is `undefined`. How flags
+are resolved, and when they change, is in the
+[`@dropby/browser` README](https://www.npmjs.com/package/@dropby/browser#context-and-feature-flags).
+
+```vue
+<script setup lang="ts">
+import { useFeatureFlag } from "@dropby/vue";
+import { Feature } from "@dropby/vue/components";
+
+const format = useFeatureFlag("export_format");
+</script>
+
+<template>
+  <Feature name="new_exports">
+    <button type="button">export as {{ format === "csv" ? "csv" : "pdf" }}</button>
+    <template #fallback><span>exports are coming soon</span></template>
+  </Feature>
+</template>
+```
+
+## Components and styling
+
+Optional components live in `@dropby/vue/components`: `ChatThread`,
+`ChatThreadList`, `ChatComposer`, `IdeaList`, `Idea`, `IdeaVoteButton`, `Ask`,
+`AskForm`, `PendingAsks` and `Feature`. They render plain, accessible HTML with
+state attributes such as `data-status`, `data-unread` and `data-busy`, so your
+own CSS styles them; they load no theme. Each, except `Feature`, also takes a
+default scoped slot when you want your own markup with its state, and the slot
+props are typed:
+
+```vue
+<script setup lang="ts">
+import { ChatThreadList } from "@dropby/vue/components";
+
+const emit = defineEmits<{ open: [threadId: `thr_${string}`] }>();
+</script>
+
+<template>
+  <ChatThreadList v-slot="{ threads }">
+    <button
+      v-for="thread in threads.items"
+      :key="thread.threadId"
+      type="button"
+      @click="emit('open', thread.threadId)"
+    >
+      {{ thread.lastMessagePreview }}
+    </button>
+    <p v-if="threads.status === 'error'">couldn't load your conversations.</p>
+  </ChatThreadList>
+</template>
+```
+
+The default chat components behave like the hosted widget:
+
+- `ChatThread` marks a reply seen once its end is on screen (the page visible,
+  the viewer allowed). Pass `:acknowledge="false"` to do that yourself with
+  `actions.markSeen`. A slot body is never observed.
+- `ChatThread` follows new messages inside its own scroll container: to the
+  newest when it opens, when the reader sends, and when a message arrives while
+  they are at the end. It scrolls only its own scroll container (itself or the
+  nearest ancestor with `overflow-y: auto`), never the document.
+- `ChatThreadList` rows become buttons with `@select="(threadId) => ..."`;
+  `selected-id` marks the open one with `aria-current`.
+- Failed loads, sends and downloads show as `role="alert"` messages in plain
+  words. A slot's state carries the `DropByError` behind a failed load or send.
+- `ChatComposer` keeps a failed message in the box. Sending it again unchanged
+  cannot post it twice.
+
+## Optional attachments
+
+Import `useChatAttachments` only when the composer needs uploads, so other
+pages never load the upload code:
+
+```vue
+<script setup lang="ts">
+import { ChatComposer } from "@dropby/vue/components";
+import { useChatAttachments } from "@dropby/vue/components/chat-attachments";
+
+defineProps<{ threadId: `thr_${string}` }>();
+const attachments = useChatAttachments();
+</script>
+
+<template>
+  <ChatComposer :thread-id="threadId" :attachments="attachments" />
+</template>
+```
+
+The composable returns `drafts`, `add`, `remove`, `clear`, `references`,
+`pending`, `notice` and `accept`. `ChatComposer` waits for uploads in progress
+and sends only the ready ones. Disposing the component's scope releases the
+composable's previews and subscriptions; destroying the instance cancels its
+uploads.

package/dist/chunks/chat-attachment-types-BG8VFQj5.d.ts

@@ -0,0 +1,56 @@
+import { ChatAttachmentContentType, ChatAttachmentKind, DropById } from "@dropby/browser";
+/** A file picked for the next message: its upload's state, and a preview for images. */
+interface ChatAttachmentDraft {
+  /** This draft's own id, stable from the moment it is picked; pass it to `remove`. */
+  localId: string;
+  /** The file's name, trimmed, or `attachment` when it has none. */
+  fileName: string;
+  /** The type the file was accepted as; null until it is checked. */
+  contentType: ChatAttachmentContentType | null;
+  /** The file's size in bytes. */
+  byteSize: number;
+  /** Whether it shows as an image or a file; null until it is checked. */
+  kind: ChatAttachmentKind | null;
+  /** A local URL to preview an image; null for other files. */
+  previewUrl: string | null;
+  /** Where the upload is: checking the file, uploading, ready to send, or failed. */
+  status: "checking" | "uploading" | "ready" | "error";
+  /** The attachment's id once it is ready to send; null before. */
+  attachmentId: DropById<"att_"> | null;
+  /** Why the upload failed, such as `too_large`; null unless `status` is `error`. */
+  error: {
+    code: string;
+    message: string;
+  } | null;
+}
+/**
+ * Attachments for a composer, from `useChatAttachments`: the files picked, and
+ * how to add, remove and send them. Pass it to `ChatComposer` as `attachments`.
+ */
+interface ChatAttachmentsToolkit {
+  /** The files picked, in order. */
+  drafts: ChatAttachmentDraft[];
+  /**
+   * Starts uploading files, up to four per message; files past that are left out
+   * and `notice` says so.
+   */
+  add: (files: FileList | File[]) => void;
+  /** Drops one file from the message. */
+  remove: (localId: string) => void;
+  /** Drops every file. */
+  clear: () => void;
+  /** The ready uploads, to send with a message. */
+  references: () => Array<{
+    attachmentId: DropById<"att_">;
+  }>;
+  /** Whether a file is still being checked or uploaded. */
+  pending: boolean;
+  /**
+   * Why files were left out of the last `add`; null otherwise. Cleared by the next
+   * `add` that takes every file, or by any `remove` or `clear`.
+   */
+  notice: string | null;
+  /** The content types a file input should accept. */
+  accept: string;
+}
+export { ChatAttachmentsToolkit as n, ChatAttachmentDraft as t };

package/dist/chunks/chat-attachments-BeJa4tEd.js

@@ -0,0 +1,20 @@
+function uuid() {
+	const bytes = globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
+	const time = Date.now();
+	for (let index = 0; index < 6; index++) bytes[index] = Math.floor(time / 2 ** (8 * (5 - index))) % 256;
+	bytes[6] = bytes[6] & 15 | 112;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+const chatAttachmentContentTypes = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif",
+	"application/pdf",
+	"text/plain",
+	"text/csv"
+];
+const chatAttachmentMaxByteSize = 10485760;
+export { chatAttachmentMaxByteSize as n, uuid as r, chatAttachmentContentTypes as t };

package/dist/chunks/public-component-A2rcQYAZ.d.ts

@@ -0,0 +1,10 @@
+import { AllowedComponentProps, ComponentCustomProps, VNodeProps } from "vue";
+/**
+ * The type of each component in this package: the props it accepts and the slots
+ * it renders, which is what a template or `h()` checks.
+ */
+type PublicComponent<Props, Slots = object> = new () => {
+  $props: AllowedComponentProps & ComponentCustomProps & VNodeProps & Props;
+  $slots: Slots;
+};
+export { PublicComponent as t };

package/dist/chunks/use-drop-by-4B6MMMx1.js

@@ -0,0 +1,33 @@
+import { computed, inject, onMounted, onScopeDispose, shallowRef } from "vue";
+const dropByKey = Symbol("dropby-core");
+function useStore(store, selector, isEqual = Object.is) {
+	const snapshot = shallowRef(store.getSnapshot());
+	let unsubscribe;
+	onMounted(() => {
+		const sync = () => {
+			snapshot.value = store.getSnapshot();
+		};
+		sync();
+		unsubscribe = store.subscribe(sync);
+	});
+	onScopeDispose(() => unsubscribe?.());
+	return computed((previous) => {
+		const next = selector(snapshot.value);
+		return previous !== void 0 && isEqual(previous, next) ? previous : next;
+	});
+}
+const identity = (value) => value;
+function useDropBy() {
+	const dropby = inject(dropByKey, null);
+	if (dropby === null) throw new Error("DropBy composables must be used within a <DropByProvider>.");
+	return dropby;
+}
+function useDropByState() {
+	const core = useDropBy();
+	return {
+		connection: useStore(core.connection, identity),
+		capabilities: useStore(core.capabilities, identity),
+		bootstrap: useStore(core.bootstrap, identity)
+	};
+}
+export { dropByKey as i, useDropByState as n, useStore as r, useDropBy as t };

package/dist/chunks/use-feature-BQHA7pdn.js

@@ -0,0 +1,68 @@
+import { r as useStore, t as useDropBy } from "./use-drop-by-4B6MMMx1.js";
+import { onMounted, onScopeDispose, toValue, watch } from "vue";
+function useChatThreads() {
+	const core = useDropBy();
+	return {
+		data: useStore(core.chat, (state) => state.threads),
+		actions: core.chat
+	};
+}
+function useChatThread(id) {
+	const chat = useDropBy().chat;
+	let release;
+	onMounted(() => {
+		watch(() => toValue(id), (current) => {
+			release?.();
+			release = chat.observeThread(current);
+		}, { immediate: true });
+	});
+	onScopeDispose(() => release?.());
+	return {
+		data: useStore(chat, (state) => state.threadsById[toValue(id)]),
+		actions: {
+			open: () => chat.openThread(toValue(id)),
+			markSeen: (request) => chat.markThreadSeen(toValue(id), request),
+			loadOlderMessages: () => chat.loadOlderMessages(toValue(id)),
+			loadLatestMessages: () => chat.loadLatestMessages(toValue(id)),
+			sendMessage: (input, options) => chat.sendMessage(toValue(id), input, options),
+			getAttachmentDownload: (attachmentId) => chat.getAttachmentDownload(attachmentId)
+		},
+		olderMessages: useStore(chat, (state) => state.olderMessagesById[toValue(id)]),
+		latestMessages: useStore(chat, (state) => state.latestMessagesById[toValue(id)])
+	};
+}
+function useChatUnread() {
+	const core = useDropBy();
+	return {
+		data: useStore(core.chat, (state) => state.unread),
+		actions: core.chat
+	};
+}
+function useIdeas(selector, isEqual) {
+	const core = useDropBy();
+	if (selector) return {
+		data: useStore(core.ideas, selector, isEqual),
+		actions: core.ideas
+	};
+	return {
+		data: useStore(core.ideas, (state) => state.ideas),
+		actions: core.ideas
+	};
+}
+function usePendingAsks() {
+	const core = useDropBy();
+	return {
+		data: useStore(core.asks, (state) => state.pending),
+		actions: core.asks
+	};
+}
+const EMPTY_CONFIG = Object.freeze({});
+function useFeatureConfig() {
+	const core = useDropBy();
+	return useStore(core.bootstrap, (state) => state.data?.config ?? EMPTY_CONFIG);
+}
+function useFeatureFlag(key) {
+	const core = useDropBy();
+	return useStore(core.bootstrap, (state) => state.data?.config?.[toValue(key)]);
+}
+export { useChatThread as a, useIdeas as i, useFeatureFlag as n, useChatThreads as o, usePendingAsks as r, useChatUnread as s, useFeatureConfig as t };

package/dist/components/chat-attachments/index.d.ts

@@ -0,0 +1,9 @@
+import { n as ChatAttachmentsToolkit, t as ChatAttachmentDraft } from "../../chunks/chat-attachment-types-BG8VFQj5.js";
+/**
+ * Attachments for a `ChatComposer`: add files, see each upload and its preview,
+ * remove one, and hand the ready ones to the next message. Up to four files per
+ * message. The toolkit is reactive; unmounting the component releases the previews,
+ * and destroying the instance cancels the uploads.
+ */
+export declare function useChatAttachments(): ChatAttachmentsToolkit;
+export type { ChatAttachmentDraft, ChatAttachmentsToolkit };

package/dist/components/chat-attachments/index.js

@@ -0,0 +1,87 @@
+import { t as useDropBy } from "../../chunks/use-drop-by-4B6MMMx1.js";
+import { r as uuid, t as chatAttachmentContentTypes } from "../../chunks/chat-attachments-BeJa4tEd.js";
+import { computed, onScopeDispose, reactive, ref, shallowRef } from "vue";
+import { createChatAttachment } from "@dropby/browser/attachments";
+const accept = chatAttachmentContentTypes.join(",");
+function useChatAttachments() {
+	const core = useDropBy();
+	const entries = /* @__PURE__ */ new Map();
+	const unsubscribes = /* @__PURE__ */ new Map();
+	const drafts = shallowRef([]);
+	const notice = ref(null);
+	function snapshot() {
+		const next = [];
+		for (const entry of entries.values()) {
+			const state = entry.upload.getSnapshot();
+			next.push({
+				localId: entry.localId,
+				fileName: state.fileName,
+				contentType: state.contentType,
+				byteSize: state.byteSize,
+				kind: state.kind,
+				previewUrl: entry.previewUrl,
+				status: state.status,
+				attachmentId: state.attachmentId,
+				error: state.error
+			});
+		}
+		drafts.value = next;
+	}
+	function add(files) {
+		const incoming = Array.from(files);
+		if (incoming.length === 0) return;
+		const availableSlots = 4 - entries.size;
+		if (availableSlots <= 0) {
+			notice.value = `you can attach up to 4 files.`;
+			return;
+		}
+		const selected = incoming.slice(0, availableSlots);
+		notice.value = selected.length < incoming.length ? `only 4 attachments can be sent at once.` : null;
+		for (const file of selected) {
+			const localId = uuid();
+			const upload = createChatAttachment(core, file);
+			const previewUrl = file.type.startsWith("image/") ? URL.createObjectURL(file) : null;
+			entries.set(localId, {
+				localId,
+				upload,
+				previewUrl
+			});
+			unsubscribes.set(localId, upload.subscribe(snapshot));
+			upload.result.catch(() => void 0);
+		}
+		snapshot();
+	}
+	function remove(localId) {
+		const entry = entries.get(localId);
+		if (entry?.previewUrl) URL.revokeObjectURL(entry.previewUrl);
+		unsubscribes.get(localId)?.();
+		unsubscribes.delete(localId);
+		entries.delete(localId);
+		notice.value = null;
+		snapshot();
+	}
+	function clear() {
+		for (const localId of [...entries.keys()]) remove(localId);
+	}
+	function references() {
+		return drafts.value.flatMap((draft) => draft.status === "ready" && draft.attachmentId ? [{ attachmentId: draft.attachmentId }] : []);
+	}
+	const pending = computed(() => drafts.value.some((draft) => draft.status === "checking" || draft.status === "uploading"));
+	onScopeDispose(() => {
+		for (const unsubscribe of unsubscribes.values()) unsubscribe();
+		for (const entry of entries.values()) if (entry.previewUrl) URL.revokeObjectURL(entry.previewUrl);
+		unsubscribes.clear();
+		entries.clear();
+	});
+	return reactive({
+		drafts,
+		add,
+		remove,
+		clear,
+		references,
+		pending,
+		notice,
+		accept
+	});
+}
+export { useChatAttachments };