@dropby/react 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,220 @@
+# `@dropby/react`
+
+DropBy for React: a provider, hooks for support chat, ideas, pending asks and
+feature flags, and optional unstyled components. It supports React 18 and 19;
+`react-dom` is needed only when your app renders through it.
+
+## Installation
+
+```bash
+pnpm add @dropby/react @dropby/browser
+```
+
+`@dropby/browser` holds the options and data types used below, 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 hooks
+
+With `options`, `DropByProvider` creates the DropBy instance, starts it once
+mounted, and destroys it when unmounted. 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).
+
+```tsx
+import type { DropByOptions } from "@dropby/browser";
+import { DropByProvider, useChatThreads } from "@dropby/react";
+import { useEffect } from "react";
+
+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();
+  },
+};
+
+export function Inbox() {
+  const { data, actions } = useChatThreads();
+
+  useEffect(() => {
+    void actions.listThreads({ filter: "unread" });
+  }, [actions]);
+
+  return <p>{data.items.length} unread threads</p>;
+}
+
+export function App() {
+  return (
+    <DropByProvider options={options}>
+      <Inbox />
+    </DropByProvider>
+  );
+}
+```
+
+- `useChatThreads`, `useChatThread(id)`, `useChatUnread`, `useIdeas` and
+  `usePendingAsks` return `data` and `actions`. `actions` keeps its identity
+  across renders. All but `useChatUnread` take a selector, such as
+  `useChatThreads((state) => state.unread)`, to re-render only when that part
+  changes.
+- `useDropBy()` returns the instance. `useDropByState()` returns its live
+  `bootstrap`, `capabilities` and `connection` states.
+- An instance passed as `<DropByProvider dropby={…}>` stays yours to start and
+  destroy.
+- 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`.
+
+### Next.js App Router
+
+The package's modules are client modules (`"use client"`), so server components
+can import them. `DropByProvider` takes an `auth` function, which cannot cross
+from a server component, so create it in a client component of your own:
+
+<!-- snippet file=dropby-provider.tsx -->
+
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import type { DropByOptions } from "@dropby/browser";
+import { DropByProvider } from "@dropby/react";
+
+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();
+  },
+};
+
+export function DropByClientProvider({
+  identity,
+  children,
+}: {
+  identity: { userId: string; accountId: string | null };
+  children: ReactNode;
+}) {
+  // Another user or account gets a new instance.
+  return (
+    <DropByProvider key={`${identity.userId}:${identity.accountId ?? ""}`} options={options}>
+      {children}
+    </DropByProvider>
+  );
+}
+```
+
+Then render it where signed-in pages begin, for example in `app/layout.tsx`. On
+the server the hooks return their initial idle state; the instance starts in
+the browser.
+
+<!-- snippet: declare function signedIn(): Promise<{ userId: string; accountId: string | null } | null>; -->
+
+```tsx
+import type { ReactNode } from "react";
+import { DropByClientProvider } from "./dropby-provider";
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const identity = await signedIn(); // from your own auth
+  return (
+    <html lang="en">
+      <body>
+        {identity ? (
+          <DropByClientProvider identity={identity}>{children}</DropByClientProvider>
+        ) : (
+          children
+        )}
+      </body>
+    </html>
+  );
+}
+```
+
+## Feature flags
+
+`useFeatureFlag(name)` returns one flag's value, and re-renders only when that
+value changes. `useFeatureConfig()` returns them all. `<Feature>` renders its
+children when a flag is on (truthy, or equal to `equals`), and `fallback`
+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).
+
+```tsx
+import { useFeatureFlag } from "@dropby/react";
+import { Feature } from "@dropby/react/components";
+
+export function ExportButton() {
+  const format = useFeatureFlag("export_format");
+  return <button type="button">export as {format === "csv" ? "csv" : "pdf"}</button>;
+}
+
+export function Toolbar() {
+  return (
+    <Feature name="new_exports" fallback={<span>exports are coming soon</span>}>
+      <ExportButton />
+    </Feature>
+  );
+}
+```
+
+## Components and styling
+
+Optional components live in `@dropby/react/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
+render function as `children` when you want your own markup with its state.
+
+`ChatThread` and `Idea` share their names with data types in
+`@dropby/browser`; import one under another name
+(`import type { Idea as IdeaData }`) when you need both.
+
+The 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 render-function 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 `onSelect={(threadId) => ...}`;
+  `selectedId` marks the open one with `aria-current`.
+- Failed loads, sends and downloads show as `role="alert"` messages in plain
+  words. A render function'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:
+
+```tsx
+import { ChatComposer } from "@dropby/react/components";
+import { useChatAttachments } from "@dropby/react/components/chat-attachments";
+
+function Composer({ threadId }: { threadId: `thr_${string}` }) {
+  const attachments = useChatAttachments();
+  return <ChatComposer threadId={threadId} attachments={attachments} />;
+}
+```
+
+The hook returns `drafts`, `add`, `remove`, `clear`, `references`, `pending`,
+`notice` and `accept`. `ChatComposer` waits for uploads in progress and sends
+only the ready ones. Unmounting the component releases the hook'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-uP-PsyQf.js

@@ -0,0 +1,21 @@
+"use client";
+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/use-dropby-BW4iKpiA.js

@@ -0,0 +1,54 @@
+"use client";
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { initialSnapshots } from "@dropby/browser";
+const DropByContext = createContext(null);
+function useStoreWithSelector(store, serverSnapshot, selector, isEqual) {
+	const subscribe = useMemo(() => (listener) => store.subscribe(listener), [store]);
+	const committed = useRef(null);
+	const [getSelection, getServerSelection] = useMemo(() => {
+		let last = null;
+		const select = (snapshot) => {
+			if (last && Object.is(last.snapshot, snapshot)) return last.selection;
+			const next = selector(snapshot);
+			const previous = last ? { value: last.selection } : committed.current;
+			const selection = previous && isEqual?.(previous.value, next) ? previous.value : next;
+			last = {
+				snapshot,
+				selection
+			};
+			return selection;
+		};
+		return [() => select(store.getSnapshot()), () => select(serverSnapshot)];
+	}, [
+		store,
+		serverSnapshot,
+		selector,
+		isEqual
+	]);
+	const value = useSyncExternalStore(subscribe, getSelection, getServerSelection);
+	useEffect(() => {
+		committed.current = { value };
+	}, [value]);
+	return value;
+}
+const idleBootstrap = initialSnapshots.bootstrap;
+const idleCapabilities = initialSnapshots.capabilities;
+const idleConnection = initialSnapshots.connection;
+const idleChat = initialSnapshots.chat;
+const idleIdeas = initialSnapshots.ideas;
+const idleAsks = initialSnapshots.asks;
+const identity = (value) => value;
+function useDropBy() {
+	const core = useContext(DropByContext);
+	if (core === null) throw new Error("useDropBy and DropBy hooks must be used within a <DropByProvider>.");
+	return core;
+}
+function useDropByState() {
+	const core = useDropBy();
+	return {
+		connection: useStoreWithSelector(core.connection, idleConnection, identity),
+		capabilities: useStoreWithSelector(core.capabilities, idleCapabilities, identity),
+		bootstrap: useStoreWithSelector(core.bootstrap, idleBootstrap, identity)
+	};
+}
+export { idleChat as a, DropByContext as c, idleBootstrap as i, useDropByState as n, idleIdeas as o, idleAsks as r, useStoreWithSelector as s, useDropBy as t };

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

@@ -0,0 +1,78 @@
+"use client";
+import { a as idleChat, i as idleBootstrap, o as idleIdeas, r as idleAsks, s as useStoreWithSelector, t as useDropBy } from "./use-dropby-BW4iKpiA.js";
+import { useEffect, useMemo } from "react";
+const selectThreads = (state) => state.threads;
+function useChatThreads(selector, isEqual) {
+	const core = useDropBy();
+	const select = selector ?? selectThreads;
+	const equal = selector ? isEqual : void 0;
+	return {
+		data: useStoreWithSelector(core.chat, idleChat, select, equal),
+		actions: core.chat
+	};
+}
+function useChatThread(id, selector, isEqual) {
+	const chat = useDropBy().chat;
+	useEffect(() => chat.observeThread(id), [chat, id]);
+	const select = useMemo(() => selector ?? ((state) => state.threadsById[id]), [selector, id]);
+	const data = useStoreWithSelector(chat, idleChat, select, selector ? isEqual : void 0);
+	const selectOlder = useMemo(() => (state) => state.olderMessagesById[id], [id]);
+	const olderMessages = useStoreWithSelector(chat, idleChat, selectOlder);
+	const selectLatest = useMemo(() => (state) => state.latestMessagesById[id], [id]);
+	const latestMessages = useStoreWithSelector(chat, idleChat, selectLatest);
+	return {
+		data,
+		actions: useMemo(() => ({
+			open: () => chat.openThread(id),
+			markSeen: (request) => chat.markThreadSeen(id, request),
+			loadOlderMessages: () => chat.loadOlderMessages(id),
+			loadLatestMessages: () => chat.loadLatestMessages(id),
+			sendMessage: (input, options) => chat.sendMessage(id, input, options),
+			getAttachmentDownload: (attachmentId) => chat.getAttachmentDownload(attachmentId)
+		}), [chat, id]),
+		olderMessages,
+		latestMessages
+	};
+}
+const selectUnread = (state) => state.unread;
+function useChatUnread() {
+	const core = useDropBy();
+	return {
+		data: useStoreWithSelector(core.chat, idleChat, selectUnread),
+		actions: core.chat
+	};
+}
+const selectIdeas = (state) => state.ideas;
+function useIdeas(selector, isEqual) {
+	const core = useDropBy();
+	const select = selector ?? selectIdeas;
+	const equal = selector ? isEqual : void 0;
+	return {
+		data: useStoreWithSelector(core.ideas, idleIdeas, select, equal),
+		actions: core.ideas
+	};
+}
+const selectPending = (state) => state.pending;
+function usePendingAsks(selector, isEqual) {
+	const core = useDropBy();
+	const select = selector ?? selectPending;
+	const equal = selector ? isEqual : void 0;
+	return {
+		data: useStoreWithSelector(core.asks, idleAsks, select, equal),
+		actions: core.asks
+	};
+}
+const EMPTY_CONFIG = Object.freeze({});
+function selectConfig(state) {
+	return state.data?.config ?? EMPTY_CONFIG;
+}
+function useFeatureConfig() {
+	const core = useDropBy();
+	return useStoreWithSelector(core.bootstrap, idleBootstrap, selectConfig);
+}
+function useFeatureFlag(key) {
+	const core = useDropBy();
+	const selector = useMemo(() => (state) => state.data?.config?.[key], [key]);
+	return useStoreWithSelector(core.bootstrap, idleBootstrap, selector);
+}
+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. Unmounting releases the previews; 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,88 @@
+"use client";
+import { t as useDropBy } from "../../chunks/use-dropby-BW4iKpiA.js";
+import { r as uuid, t as chatAttachmentContentTypes } from "../../chunks/chat-attachments-uP-PsyQf.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createChatAttachment } from "@dropby/browser/attachments";
+const accept = chatAttachmentContentTypes.join(",");
+function useChatAttachments() {
+	const core = useDropBy();
+	const entries = useRef(/* @__PURE__ */ new Map());
+	const unsubscribes = useRef(/* @__PURE__ */ new Map());
+	const [drafts, setDrafts] = useState([]);
+	const [notice, setNotice] = useState(null);
+	const snapshot = useCallback(() => {
+		const next = [];
+		for (const entry of entries.current.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
+			});
+		}
+		setDrafts(next);
+	}, []);
+	const add = useCallback((files) => {
+		const incoming = Array.from(files);
+		if (incoming.length === 0) return;
+		const availableSlots = 4 - entries.current.size;
+		if (availableSlots <= 0) {
+			setNotice(`you can attach up to 4 files.`);
+			return;
+		}
+		const selected = incoming.slice(0, availableSlots);
+		setNotice(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.current.set(localId, {
+				localId,
+				upload,
+				previewUrl
+			});
+			unsubscribes.current.set(localId, upload.subscribe(snapshot));
+			upload.result.catch(() => void 0);
+		}
+		snapshot();
+	}, [core, snapshot]);
+	const remove = useCallback((localId) => {
+		const entry = entries.current.get(localId);
+		if (entry?.previewUrl) URL.revokeObjectURL(entry.previewUrl);
+		unsubscribes.current.get(localId)?.();
+		unsubscribes.current.delete(localId);
+		entries.current.delete(localId);
+		setNotice(null);
+		snapshot();
+	}, [snapshot]);
+	const clear = useCallback(() => {
+		for (const localId of [...entries.current.keys()]) remove(localId);
+	}, [remove]);
+	useEffect(() => {
+		const subs = unsubscribes.current;
+		const live = entries.current;
+		return () => {
+			for (const unsubscribe of subs.values()) unsubscribe();
+			for (const entry of live.values()) if (entry.previewUrl) URL.revokeObjectURL(entry.previewUrl);
+			subs.clear();
+			live.clear();
+		};
+	}, []);
+	return {
+		drafts,
+		add,
+		remove,
+		clear,
+		references: useCallback(() => drafts.flatMap((draft) => draft.status === "ready" && draft.attachmentId ? [{ attachmentId: draft.attachmentId }] : []), [drafts]),
+		pending: useMemo(() => drafts.some((draft) => draft.status === "checking" || draft.status === "uploading"), [drafts]),
+		notice,
+		accept
+	};
+}
+export { useChatAttachments };