web-comments 0.0.1 → 0.1.0

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@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 {};