visual-comments 0.0.0-stage → 0.1.0

package/dist/ui/text.d.ts

@@ -0,0 +1,3 @@
+import type { Comment } from '../shared/types.js';
+/** A comment's text for previews, or what it holds when it is only images. */
+export declare function commentText(comment: Comment): string;

package/dist/ui/text.js

@@ -0,0 +1,7 @@
+/** A comment's text for previews, or what it holds when it is only images. */
+export function commentText(comment) {
+    if (comment.body)
+        return comment.body;
+    const count = comment.images?.length ?? 0;
+    return count === 1 ? 'Image' : `${count} images`;
+}

package/dist/visual-comments.svelte.d.ts

@@ -0,0 +1,181 @@
+import { type Aim } from './core/aim.js';
+import { Api } from './core/api.js';
+import { type Rect, type Surface } from './core/surfaces.js';
+import { type CommentTarget } from './core/target.js';
+import { Threads } from './core/threads.svelte.js';
+import type { CommentImage, CommentThread } from './shared/types.js';
+export interface VisualCommentsOptions {
+    /** Where the site's server passes comment requests on to the comment server. Default `/_comments`. */
+    endpoint?: string;
+    /**
+     * The site's sign-in: the path of its routes, as in `@convex-works/sign-in`
+     * (default `/auth`), or functions that sign in and out.
+     */
+    auth?: string | {
+        signIn(): void;
+        signOut(): void;
+    };
+    /**
+     * The page threads belong to. Default: the address's origin and path, so
+     * the query and fragment do not matter. A fixed string makes every page share threads.
+     */
+    page?: string | ((url: URL) => string);
+    /** What to store about where a thread is placed, besides the viewport size and `data-vc-context`. */
+    context?: (surface: SurfaceInfo) => Record<string, string | number | undefined> | undefined;
+    /**
+     * Brings a thread's surface into view when it is opened from the list or a
+     * link, e.g. by zooming a canvas to it or navigating to it. Return true when
+     * handled; otherwise threads on other pages are opened by navigating to them.
+     */
+    show?: (thread: CommentThread) => boolean | void;
+    /** The address that opens a thread. Default: where it was placed, with `#vc=<id>`. */
+    link?: (thread: CommentThread) => string;
+    /** A surface's title and place in the list, for surfaces not on screen. */
+    describe?: (surface: string) => {
+        title?: string;
+        order?: number;
+    } | undefined;
+    /** A frame surface's document, when the default (any same-origin frame once loaded) is not right. */
+    documentOf?: (surface: Element, frame: HTMLIFrameElement) => Document | undefined;
+    /** The key that turns comment mode on and off. Default: `c`. */
+    shortcut?: string | false;
+    /** Show the floating toolbar. Default: unless the page has a `[data-vc-toggle]` button. */
+    toolbar?: boolean;
+}
+export interface SurfaceInfo {
+    id: string;
+    title: string;
+    element: Element | null;
+}
+export interface CommentFilters {
+    query: string;
+    sort: 'date' | 'place';
+    showResolved: boolean;
+    onlyMine: boolean;
+    /** Threads on every page, not only this one. */
+    allPages: boolean;
+}
+/** A new comment being written. */
+export interface Draft extends Aim {
+    text: string;
+    /** Narrower targets the pin was widened from, innermost first. */
+    inner?: CommentTarget[];
+    /** Images added so far, so a click elsewhere keeps them like text. */
+    images?: number;
+}
+interface Pointer {
+    x: number;
+    y: number;
+    alt: boolean;
+}
+/**
+ * Comments on a page: pins, the comment mode, the list of threads and the
+ * sign-in, drawn in a shadow root over the page. One per page.
+ */
+export declare class VisualComments {
+    readonly api: Api;
+    readonly store: Threads;
+    options: VisualCommentsOptions;
+    /** Comment mode: the list is shown, and clicking a surface starts a thread. Pins always show. */
+    active: boolean;
+    /** The thread whose conversation is open. */
+    openId: number | undefined;
+    draft: Draft | undefined;
+    filters: CommentFilters;
+    /** Measured on every change of the page. */
+    surfaces: Surface[];
+    /** Bumped whenever anything on the page may have moved. */
+    layout: number;
+    page: string;
+    /** Where the host asked for the list to go. */
+    panelRect: Rect | undefined;
+    hostToggles: boolean;
+    /** Where a click would start a thread, while it would. */
+    aim: Aim | undefined;
+    /** The pointer while it is over a surface in comment mode: the comment cursor is drawn there. */
+    cursor: {
+        x: number;
+        y: number;
+    } | undefined;
+    /** Opening a thread scrolls its element into view once it is found. */
+    revealing: number | undefined;
+    readonly doc: Document;
+    readonly host: HTMLElement;
+    private app?;
+    private slots;
+    private frames;
+    private cleanup;
+    private pointer?;
+    private pressed?;
+    private measuring;
+    private aiming;
+    private animating;
+    private cursorSheet;
+    private focusDraftHandler?;
+    private linked?;
+    constructor(options: VisualCommentsOptions, doc?: Document);
+    get viewer(): import("./index.js").Viewer | null;
+    get threads(): CommentThread[];
+    get unreadCount(): number;
+    get loading(): boolean;
+    get open(): CommentThread | undefined;
+    /** Threads shown as pins: on this page, unresolved unless resolved ones are shown or it is open. */
+    get pinned(): CommentThread[];
+    get showToolbar(): boolean;
+    surface(id: string): Surface | undefined;
+    /** A surface's title for the list, whether or not it is on screen. */
+    titleOf(thread: CommentThread): string;
+    orderOf(thread: CommentThread): number;
+    linkOf(thread: CommentThread): string;
+    imageUrl(image: CommentImage): string;
+    /** Whether an element belongs to the comment UI. */
+    readonly ours: (element: Element) => boolean;
+    /** Changes options after creation, e.g. when a host's view mounts and can show threads. */
+    configure(options: Partial<VisualCommentsOptions>): void;
+    toggle(on?: boolean): void;
+    openThread(id: number | undefined): void;
+    /** Opens a thread from the list or a link, bringing it into view. */
+    focus(thread: CommentThread): void;
+    /** The thread's element, once found, scrolled into view inside its document. */
+    revealElement(element: Element): void;
+    /** Leaves for the site's sign-in, and comes back to this address. */
+    signIn(): void;
+    signOut(): void;
+    /** Measures the page again, e.g. after the host moved surfaces in a way it cannot see. */
+    relayout(): void;
+    /** For hosts that are not built with Svelte: called after any change of state. */
+    subscribe(listener: (comments: VisualComments) => void): () => void;
+    destroy(): void;
+    /** Called by the UI so a click elsewhere can bring the unsent comment back to attention. */
+    onFocusDraft(handler: (() => void) | undefined): void;
+    private get draftHasContent();
+    private start;
+    /** Watches a frame's own document: its scrolling, its changes and its keys. */
+    private watchFrame;
+    private schedule;
+    private measure;
+    /** Puts the account button in every `[data-vc-account]` element of the host's own toolbar. */
+    private mountSlots;
+    private fromUs;
+    private surfaceAt;
+    /** The pointer moved, or left (undefined). Also called by the layers over frames. */
+    move(pointer: Pointer | undefined): void;
+    private onPointerMove;
+    /** Aims again, at most once per frame: the pointer moved, or the page moved under it. */
+    private updateAim;
+    /** Over a surface in comment mode the page's cursor is hidden; the comment cursor is drawn instead. */
+    private updateCursorStyle;
+    /** Pressing on a surface in comment mode does not reach the page, unless the host keeps its gestures there. */
+    private onPress;
+    private onRelease;
+    private onOtherClick;
+    private onClick;
+    /** A click on a surface in comment mode starts a thread. A click away from an open thread closes it first. */
+    place(surface: Surface, x: number, y: number, free: boolean): void;
+    /** A layer over a frame passes wheel turns to whatever scrolls under the pointer. */
+    wheel(surface: Surface, event: WheelEvent): void;
+    private onKey;
+}
+/** The page key: the address's origin and path, without a trailing slash. */
+export declare function pageOf(option: VisualCommentsOptions['page']): string;
+export {};