web-comments 0.0.1 → 1.0.0

package/dist/types/store/r2.d.ts

@@ -0,0 +1,20 @@
+import type { AssetStore } from "../server/store";
+/** The slice of a Workers R2 binding this uses. */
+export interface R2BucketLike {
+    put(key: string, value: ArrayBuffer, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+    }): Promise<unknown>;
+    get(key: string): Promise<{
+        body: ReadableStream;
+        httpMetadata?: {
+            contentType?: string;
+        };
+    } | null>;
+    delete(key: string): Promise<void>;
+}
+/** Screenshots in a Cloudflare R2 bucket, through its Workers binding: `assets: (env) => r2Assets(env.SCREENSHOTS)`. */
+export declare function r2Assets(bucket: R2BucketLike, options?: {
+    prefix?: string;
+}): AssetStore;

package/dist/types/store/s3.d.ts

@@ -0,0 +1,21 @@
+import type { AssetStore } from "../server/store";
+export interface S3AssetsOptions {
+    /**
+     * The S3 API endpoint, without the bucket: "https://s3.us-east-1.amazonaws.com",
+     * "https://<account>.r2.cloudflarestorage.com", a MinIO URL, ...
+     */
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Default "auto", which R2 expects; AWS needs the bucket's region. */
+    region?: string;
+    /** Put every key under this prefix, e.g. "web-comments/". */
+    prefix?: string;
+}
+/**
+ * Screenshots in any S3-compatible bucket (AWS S3, R2's S3 API, MinIO, ...),
+ * signed with SigV4 over fetch, so it runs on Workers, Node and Bun alike.
+ * Path-style addressing: {endpoint}/{bucket}/{key}.
+ */
+export declare function s3Assets(options: S3AssetsOptions): AssetStore;

package/dist/types/widget/anchor.d.ts

@@ -0,0 +1,9 @@
+import type { Anchor } from "../shared/types";
+export declare function textOf(element: Element): string;
+/** The page element under a point, looking past the widget's own layer. */
+export declare function elementAt(x: number, y: number, host: Element): Element | null;
+/** Describes where a click landed so the comment can find its element again later. */
+export declare function createAnchor(element: Element, clientX: number, clientY: number): Anchor;
+/** Finds an anchor's element on the page as it is now, or null when it's gone. */
+export declare function resolveAnchor(anchor: Anchor): Element | null;
+export declare function selectorFor(element: Element): string;

package/dist/types/widget/api.d.ts

@@ -0,0 +1,43 @@
+import type { Anchor, Identity, Thread, ThreadContext, ThreadStatus } from "../shared/types";
+import type { Shots } from "./capture";
+export interface ApiOptions {
+    endpoint: string;
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    credentials: RequestCredentials;
+}
+/** The API answered that nobody is signed in (or the gate in front of it did). */
+export declare class SignedOut extends Error {
+    readonly loginUrl?: string | undefined;
+    constructor(loginUrl?: string | undefined);
+}
+/** Signed in, but not allowed to use comments here. */
+export declare class Forbidden extends Error {
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function createApi(options: ApiOptions): {
+    /** A path the API returned (a screenshot), as a URL the browser can load: it's relative to the API's host. */
+    resolve: (path: string) => string;
+    me: () => Promise<Identity>;
+    threads: (page: string) => Promise<Thread[]>;
+    thread: (threadId: string) => Promise<Thread>;
+    /** Opens a thread, sending its screenshots along in the same request when there are any. */
+    createThread: (input: {
+        page: string;
+        url: string;
+        anchor: Anchor;
+        context?: ThreadContext;
+        body: string;
+    }, shots?: Shots) => Promise<Thread>;
+    reply: (threadId: string, body: string) => Promise<Thread>;
+    /** Moves a thread's pin to a new spot on the page. Only its author may. */
+    moveThread: (threadId: string, anchor: Anchor) => Promise<Thread>;
+    setStatus: (threadId: string, status: ThreadStatus) => Promise<Thread>;
+    deleteComment: (commentId: string) => Promise<{
+        deleted: "comment" | "thread";
+        threadId: string;
+    }>;
+};
+export type Api = ReturnType<typeof createApi>;

package/dist/types/widget/app.d.ts

@@ -0,0 +1,29 @@
+import { type Api } from "./api";
+import { type Tracker } from "./tracker";
+export interface Settings {
+    page: () => string;
+    shortcut: string | false;
+    pollInterval: number;
+    linkParam: string;
+    /** "push" moves the page over to make room for the toolbar; "overlay" draws it on top. */
+    dock: "push" | "overlay";
+}
+/** What mountComments hands back, wired up once the app is running. */
+export interface Controls {
+    open?: (threadId: string) => void;
+    setPlacing?: (placing: boolean) => void;
+}
+interface RootProps {
+    api: Api;
+    host: HTMLElement;
+    tracker: Tracker;
+    settings: Settings;
+    controls: Controls;
+    colorScheme: "light" | "dark" | undefined;
+    zIndex: number;
+}
+/** Spectrum's Provider, with overlays (menus, tooltips, dialogs) kept inside the shadow root. */
+export declare function Root({ colorScheme, zIndex, ...props }: RootProps): import("react").JSX.Element;
+type AppProps = Omit<RootProps, "colorScheme" | "zIndex">;
+export declare function App({ api, host, tracker, settings, controls }: AppProps): import("react").JSX.Element | null;
+export {};

package/dist/types/widget/capture.d.ts

@@ -0,0 +1,33 @@
+import type { ScreenshotKind, ThreadContext } from "../shared/types";
+export interface Shot {
+    blob: Blob;
+    width: number;
+    height: number;
+}
+export type Shots = Partial<Record<ScreenshotKind, Shot>>;
+/** What the commenter is looking at: the element and the page around it. */
+export declare function contextOf(element: Element): ThreadContext;
+/**
+ * Two screenshots from one render of the viewport, drawn from the DOM and
+ * leaving the widget out: the viewport as it was, and the element in its
+ * surroundings with an outline round it. None comes back when the page can't
+ * be drawn (a render that times out); a comment never waits on them for long.
+ */
+export declare function capture(element: Element, host: Element): Promise<Shots>;
+/** The part of the viewport to show for an element: it, a margin, at least a minimum size, inside the viewport. */
+export declare function cropAround(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Waits for screenshots, but never longer than `ms`: a comment goes out without them rather than late. */
+export declare function within(shots: Promise<Shots>, ms: number): Promise<Shots>;

package/dist/types/widget/format.d.ts

@@ -0,0 +1,15 @@
+export declare function colorFor(id: string): string;
+/** An image for Spectrum's Avatar: the person's picture, or their initials on a color. */
+export declare function avatarSrc(person: {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+}): string;
+/** "Ada Lovelace" → "AL", "林黛玉" → "林" */
+export declare function initials(name: string): string;
+export declare function timeAgo(iso: string, now: number): string;
+/** Splits text into plain strings and links (with where each starts), for rendering without innerHTML. */
+export declare function linkify(text: string): Array<string | {
+    href: string;
+    start: number;
+}>;

package/dist/types/widget/index.d.ts

@@ -0,0 +1,41 @@
+import { type Settings } from "./app";
+export type * from "../shared/types";
+export interface MountOptions {
+    /** Where the comments API is mounted. Default "/__comments". */
+    endpoint?: string;
+    /**
+     * Which page a comment belongs to. Default: the path. Return a route
+     * pattern (e.g. "/:org/settings") to share comments across ids.
+     */
+    page?: () => string;
+    /** Extra request headers, e.g. a bearer token the host app holds. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Default "include", so cookie-based gates such as Cloudflare Access work cross-origin too. */
+    credentials?: RequestCredentials;
+    /**
+     * The toolbar is docked on the right. "push" (default) moves the page over
+     * to make room for it; "overlay" draws it on top of the page.
+     */
+    dock?: Settings["dock"];
+    /** Key that toggles comment mode. Default "c"; false turns it off. */
+    shortcut?: string | false;
+    theme?: "auto" | "light" | "dark";
+    /** Default: just under the largest z-index. */
+    zIndex?: number;
+    /** How often to look for new comments, in ms. Default 15000. */
+    pollInterval?: number;
+    /** Query parameter that links to a thread. Default "comment". */
+    linkParam?: string;
+}
+export interface CommentsHandle {
+    /** Opens a thread on this page by id. */
+    open(threadId: string): void;
+    /** Turns comment mode on or off. */
+    setCommentMode(on: boolean): void;
+    unmount(): void;
+}
+/**
+ * Puts the comments toolbar on the page for people the API accepts; everyone
+ * else sees nothing. Call unmount() to take it off again.
+ */
+export declare function mountComments(options?: MountOptions): CommentsHandle;

package/dist/types/widget/styles.d.ts

@@ -0,0 +1,6 @@
+/** Everything that styles the widget, injected into its shadow root. */
+export declare const SHADOW_CSS: string;
+/** @font-face and @property rules, which only work in the document. */
+export declare const DOCUMENT_CSS: string;
+/** The widget's own base rules, and keyframes its styles refer to by name. */
+export declare const BASE_CSS = "\nimg { -webkit-user-drag: none; user-select: none; }\n/* The toolbar wears construction stripes in the accent colour: a tool for the people building the page, not part of it. */\n.wc-rail {\n  background-image: repeating-linear-gradient(\n    45deg,\n    light-dark(rgb(59 99 251 / 0.05), rgb(93 137 255 / 0.06)) 0 10px,\n    light-dark(rgb(59 99 251 / 0.11), rgb(93 137 255 / 0.12)) 10px 20px\n  );\n}\n@keyframes wc-pop-in {\n  from { opacity: 0; transform: scale(0.5); animation-timing-function: cubic-bezier(0, 0, 0.4, 1); }\n  60% { opacity: 1; transform: scale(1.12); animation-timing-function: cubic-bezier(0.45, 0, 0.4, 1); }\n  to { opacity: 1; transform: scale(1); }\n}\n@keyframes wc-grow-in {\n  from { opacity: 0; transform: scale(0.96); }\n  to { opacity: 1; transform: scale(1); }\n}\n";

package/dist/types/widget/thread.d.ts

@@ -0,0 +1,32 @@
+import type { Author, Identity, Thread } from "../shared/types";
+import type { Api } from "./api";
+export declare function PersonAvatar({ person, size, }: {
+    person: Pick<Author, "id" | "name" | "avatarUrl">;
+    size?: 20 | 24 | 28 | 32;
+}): import("react").JSX.Element;
+interface ComposerProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    onSubmit: () => Promise<void>;
+    /** Escape calls this: drops a draft, or closes the thread. */
+    onCancel?: () => void;
+    autoFocus?: boolean;
+    /** Floats on its own over the page (a new comment) rather than inside a card. */
+    floating?: boolean;
+}
+export declare function Composer(props: ComposerProps): import("react").JSX.Element;
+interface ThreadViewProps {
+    thread: Thread;
+    me: Identity;
+    api: Api;
+    now: number;
+    linkFor: (thread: Thread) => string;
+    onChange: (thread: Thread) => void;
+    onDeleted: (threadId: string) => void;
+    onClose?: () => void;
+    /** Shown inside the panel rather than as a card by its pin. */
+    inline?: boolean;
+}
+export declare function ThreadView(props: ThreadViewProps): import("react").JSX.Element;
+export {};

package/dist/types/widget/tracker.d.ts

@@ -0,0 +1,68 @@
+import type { Anchor } from "../shared/types";
+export interface Box {
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    /** The element a comment is on, for cards that sit under it. */
+    rect?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+type Place = (node: HTMLElement, box: Box) => void;
+interface Item {
+    node: HTMLElement;
+    box: () => Box | null;
+    place: Place;
+}
+/**
+ * Moves pins and cards with their elements every frame, through the
+ * `translate` property so a hover `scale` grows the pin in place instead of
+ * scaling its offset from the corner of the viewport. Positions are written
+ * straight to the DOM so scrolling never re-renders the widget.
+ */
+export declare class Tracker {
+    private items;
+    private ticks;
+    private frame;
+    set(key: string, item: Item): void;
+    delete(key: string): void;
+    /** Runs a callback on every frame, for cheap checks such as "did the page change?". */
+    onTick(callback: () => void): () => void;
+    start(): void;
+    stop(): void;
+    private place;
+}
+export declare const placePin: Place;
+export declare const placeOutline: Place;
+/**
+ * Places a card under the element its comment is on, left edges aligned, or
+ * above it when there's no room below. An element too tall for either gets
+ * the card beside the pin. Everything stays left of `rightEdge()` (the docked
+ * toolbar, and the panel when it's open). The transform origin follows the
+ * pin, so an entering card grows out of it.
+ */
+export declare function placeCardNear(rightEdge: () => number): Place;
+/** Remembers which element each thread is on, looking again when the page replaces it. */
+export declare class AnchorCache {
+    private entries;
+    element(id: string, anchor: Anchor): Element | null;
+    /** Where a thread's pin goes right now, or null when its element is gone or hidden. */
+    point(id: string, anchor: Anchor): Box | null;
+    /** The pin's point plus its element's box, for the thread's card. */
+    card(id: string, anchor: Anchor): Box | null;
+    /** The box of a thread's element, for an outline around it. */
+    outline(id: string, anchor: Anchor): Box | null;
+    /** Looks for a thread's element afresh, e.g. after it was moved. */
+    forget(id: string): void;
+    clear(): void;
+}
+export declare function pointOn(element: Element, anchor: Pick<Anchor, "x" | "y">): Box | null;
+/** An element's box, for an outline drawn around it. */
+export declare function outlineOf(element: Element | null | undefined): Box | null;
+/** Where a comment's card goes: the pin's point, plus the element's box to sit under. */
+export declare function cardBoxOf(element: Element | null | undefined, anchor: Pick<Anchor, "x" | "y">): Box | null;
+export {};