@unhingged/vizu-core 0.1.15 → 0.1.17

package/dist/internal.d.ts

@@ -0,0 +1,446 @@
+/**
+ * Single rung of the ancestor chain: the element's tag and its
+ * `nth-of-type` index inside its parent (1-indexed). Captured root-near
+ * → closer-to-target so the matcher can shift-search through wrapper
+ * additions.
+ */
+interface AncestorStep {
+    tag: string;
+    nthOfType: number;
+}
+interface ElementFingerprint {
+    selector: string;
+    parentSelector: string;
+    tagName: string;
+    textSnippet: string;
+    siblingIndex: number;
+    attributes: {
+        id?: string;
+        classList?: string[];
+        role?: string;
+        ariaLabel?: string;
+        dataKey?: string;
+    };
+    /**
+     * 3-step ancestor chain. Added in algorithm v2 (Phase 11.4.2). Order:
+     * immediate parent first, then grandparent, then great-grandparent.
+     * Legacy fingerprints written before this field lack it; the matcher
+     * falls back to the parent+sibling-index+tag heuristic for those.
+     */
+    ancestorChain?: {
+        steps: AncestorStep[];
+    };
+    /**
+     * Algorithm version that produced this fingerprint. Absent (or `1`) on
+     * legacy captures; new captures stamp `2` (Phase 11.4 hardened matcher
+     * — class-signature rung, multi-ancestor chain, Levenshtein text scan).
+     * The matcher routes on the presence of {@link ancestorChain} today, so
+     * this field is informational; it gives us a stable handle to migrate
+     * data when v3 ships without re-introspecting fingerprint shape.
+     */
+    algorithmVersion?: 1 | 2;
+}
+interface VizuUser {
+    id?: string;
+    name: string;
+    avatarUrl?: string;
+    email?: string;
+    /** Free-form host-defined extras (team, role, etc.) preserved on each comment. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Slim shape for the mention picker. The host can @-mention any of
+ * these in a comment body. Returned by `Vizu.searchMentionable()` and
+ * cached by the popover dropdown. Name + avatar is all the UI needs;
+ * email/role intentionally omitted to keep the cross-origin surface
+ * minimal.
+ */
+interface MentionableUser {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+}
+/** Current schema version. Bump + add a migration when the shape changes. */
+declare const SCHEMA_VERSION: 2;
+type SchemaVersion = typeof SCHEMA_VERSION;
+/**
+ * Triage state. Cloud workspaces use this for filtering;
+ * the local sidebar treats `resolved` / `wontfix` as "dim".
+ */
+type CommentStatus = 'open' | 'resolved' | 'wontfix';
+/**
+ * Outcome of resolving a comment's fingerprint against the current DOM.
+ *
+ *   - `exact`    : `data-vizu-key` or `id` matched. We trust this 100%.
+ *   - `likely`   : The full CSS selector path matched. Probably the right
+ *                  element but not guaranteed if the page has dynamic
+ *                  duplicates.
+ *   - `drifted`  : Only the structural fallback (parent + sibling-index)
+ *                  or the page-wide text snippet matched. The page has
+ *                  changed since the comment was written. Render with a
+ *                  visible warning so visitors don't act on a stale match.
+ *   - `orphaned` : Nothing matched. The element is gone. Comment is shown
+ *                  in a separate sidebar section.
+ *
+ * Returned by `findByFingerprint`; emitted via the `anchor:resolved` event.
+ */
+type MatchConfidence = 'exact' | 'likely' | 'drifted' | 'orphaned';
+/**
+ * Embedded reply in a comment thread. Threading UI ships in v1.1 — the
+ * shape is stamped in v2 so writes are already future-correct.
+ */
+interface Reply {
+    id: string;
+    text: string;
+    createdAt: number;
+    author?: VizuUser;
+    /** Identity provider's user id (Clerk, etc.) when known. */
+    authorId?: string;
+    /** Clerk user ids mentioned in this reply. */
+    mentions?: string[];
+}
+/**
+ * File attachment metadata. Storage backend (Vercel Blob, S3, …) is
+ * decided by the host / cloud adapter; the comment only carries the
+ * resolved URL.
+ */
+interface Attachment {
+    id: string;
+    url: string;
+    mimeType: string;
+    sizeBytes: number;
+    uploadedAt: number;
+    /** Original filename the user uploaded. */
+    filename?: string;
+}
+interface VizuComment {
+    id: string;
+    /** Schema version. Set to {@link SCHEMA_VERSION} on every new write. */
+    schemaVersion: SchemaVersion;
+    /**
+     * One or more elements this comment is anchored to. Length 1 = single-anchor
+     * (the common case); >1 = "grouped" comment that applies to multiple
+     * elements together (e.g., "align these three CTAs to the same baseline").
+     *
+     * Always has length ≥ 1. Legacy v1 comments (with a singular `fingerprint`
+     * field) are auto-migrated to `[fingerprint]` on load — see `migrateComment`.
+     */
+    fingerprints: ElementFingerprint[];
+    /** @deprecated v1 only — kept on the type so older payloads parse cleanly; migrated at load time. */
+    fingerprint?: ElementFingerprint;
+    text: string;
+    createdAt: number;
+    pageVersion?: string;
+    /** @deprecated use `pageUrl` — kept for backwards-compat read of v1 payloads. */
+    url?: string;
+    /** Page URL where the comment was anchored. Cloud reads filter on this. */
+    pageUrl?: string;
+    /** Captured from `Vizu.setUser` / `options.user` at the moment the comment was created. */
+    author?: VizuUser;
+    /** Identity provider's user id (Clerk, etc.) when known. Cloud writes set this from the session. */
+    authorId?: string;
+    /**
+     * Element references the user inserted via `#` mentions. Keyed by short refId.
+     * The comment text contains tokens like `[#label](vizu-ref:refId)` that resolve
+     * to these fingerprints; clicking a rendered reference jumps to the element.
+     */
+    references?: Record<string, ElementFingerprint>;
+    /** Triage state. Defaults to `'open'` on new comments. */
+    status: CommentStatus;
+    /** Threaded replies. UI ships in v1.1; the array is always present. */
+    replies: Reply[];
+    /** File attachments. UI ships in v1.2; the array is always present. */
+    attachments: Attachment[];
+    /** Clerk user ids mentioned in this comment. */
+    mentions: string[];
+    /**
+     * Timestamp (ms) of the last self-healing re-fingerprint pass. Set by
+     * the Vizu class when a `drifted` resolution lands on an existing
+     * element and the fingerprint is rewritten in place. Reads as null
+     * for comments that have never drifted. Surface in the dashboard if
+     * you want to flag "auto-healed" rows; ignore otherwise.
+     */
+    fingerprintsRefreshedAt?: number | null;
+}
+/** Context handed to every action's onClick. Has the data and the side-effect helpers. */
+interface ActionContext {
+    comments: VizuComment[];
+    pageHtml: string;
+    pageUrl?: string;
+    pageVersion?: string;
+    user?: VizuUser;
+    timestamp: number;
+    /** Quick copy-to-clipboard helper. */
+    copyToClipboard: (text: string) => void;
+    /** Briefly show a toast above the pill. */
+    toast: (message: string) => void;
+}
+interface VizuAction {
+    id: string;
+    label: string;
+    /** Tooltip / aria-label */
+    title?: string;
+    variant?: 'primary' | 'default' | 'ghost';
+    /** Placement in the pill. Defaults to 'main'. */
+    position?: 'main';
+    onClick: (ctx: ActionContext) => void | Promise<void>;
+    /** Only render the action when this returns true. */
+    visibleWhen?: (ctx: {
+        commentsCount: number;
+    }) => boolean;
+}
+
+interface PillCallbacks {
+    onToggleSidebar: () => void;
+    onDisable: () => void;
+    onAction: (id: string) => void;
+    onToggleMultiSelect: () => void;
+    onCommitSelection: () => void;
+    onClearSelection: () => void;
+}
+declare class Pill {
+    private el;
+    private root;
+    private callbacks;
+    private sidebarOpen;
+    private actions;
+    private commentsCount;
+    private user;
+    private multiSelectMode;
+    private selectionCount;
+    constructor(root: HTMLElement, callbacks: PillCallbacks);
+    setActions(actions: VizuAction[]): void;
+    setComments(comments: VizuComment[]): void;
+    setUser(user: VizuUser | null): void;
+    setSidebarOpen(open: boolean): void;
+    setMultiSelectState(mode: boolean, selectionCount: number): void;
+    show(): void;
+    hide(): void;
+    private render;
+    private handleClick;
+    toast(message: string): void;
+    destroy(): void;
+}
+
+interface PopoverCallbacks {
+    /**
+     * Save a comment with one or more anchored fingerprints and the parsed
+     * reference map. Refs are inline tokens in `text` and resolved via `references`.
+     */
+    onAdd: (text: string, fingerprints: ElementFingerprint[], references?: Record<string, ElementFingerprint>, mentions?: string[], attachments?: Attachment[]) => void;
+    onDelete: (id: string) => void;
+    onAddReply: (commentId: string, text: string) => void;
+    onDeleteReply: (commentId: string, replyId: string) => void;
+    /** Upload a file via the active storage adapter; returns the resolved Attachment. */
+    onUploadAttachment: (file: File) => Promise<Attachment>;
+    /** True iff the active storage adapter supports uploads (popover hides the UI otherwise). */
+    canUploadAttachments: () => boolean;
+    onClose: () => void;
+    onStartReferencePick: (onPicked: (fp: ElementFingerprint) => void, onCancel: () => void) => void;
+    onJumpToReference: (commentId: string, refId: string) => void;
+    onAnchorsChanged: (fingerprints: ElementFingerprint[]) => void;
+    /**
+     * Fetch the workspace's mentionable users for the @ picker dropdown.
+     * Called every time the user opens the picker — keeps the list fresh
+     * if members were added/removed in another tab. Returns [] for hosts
+     * that don't support mentions (local/memory storage adapters).
+     */
+    onMentionSearch?: () => Promise<MentionableUser[]>;
+}
+declare class Popover {
+    private el;
+    private root;
+    private callbacks;
+    private currentUser;
+    /** All elements this in-progress comment is anchored to. First one positions the popover. */
+    private anchorTargets;
+    private anchorFingerprints;
+    /** Refs the user inserted via # picker during this session, keyed by refId. */
+    private pendingRefs;
+    /** Attachments uploaded during this session, persisted into `comment.attachments` on save. */
+    private pendingAttachments;
+    /** Open mention picker element, if any. Held so the next openMentionPicker / close calls can tear it down. */
+    private mentionPicker;
+    /** Dismiss handlers wired to document for the open picker; cleared in closeMentionPicker. */
+    private mentionPickerDismiss;
+    /** All mentionable users fetched for the open picker — pre-filter list. */
+    private mentionPickerUsers;
+    /** Currently visible subset of `mentionPickerUsers` after the user's filter. */
+    private mentionPickerFiltered;
+    /** Highlighted index in `mentionPickerFiltered`. Up/Down arrows mutate this. */
+    private mentionPickerSelected;
+    /**
+     * 'manual' = opened from the @ mention button (separate search input).
+     * 'editor' = opened by typing `@` in the editor; filter is derived
+     * from the text after `@` in the editor itself, no search input.
+     */
+    private mentionPickerMode;
+    /**
+     * In editor mode: a Range covering `@<query>` in the editor's text.
+     * Used to replace that span with the mention chip on commit, and to
+     * recompute the bounding rect when re-positioning after typing.
+     */
+    private mentionPickerEditorRange;
+    constructor(root: HTMLElement, callbacks: PopoverCallbacks);
+    setUser(user: VizuUser | null): void;
+    /**
+     * Open the popover anchored to one OR more elements. The popover positions
+     * itself relative to `targets[0]` but commits with every fingerprint in `fingerprints`.
+     */
+    open(targets: Element[], fingerprints: ElementFingerprint[], existingComments: VizuComment[]): void;
+    /** Refresh the rendered comment list (called by host when comments change). */
+    update(existingComments: VizuComment[]): void;
+    /** Add another anchor to the in-progress comment (Shift+Click flow). */
+    addAnchor(fp: ElementFingerprint, target: Element | null): boolean;
+    /** Remove an anchor by fingerprint key. Never removes the last anchor. */
+    removeAnchor(key: string): boolean;
+    private updateHeader;
+    /** Recompute viewport position; called by host on scroll/resize. */
+    reposition(): void;
+    close(): void;
+    isOpen(): boolean;
+    getAnchors(): ElementFingerprint[];
+    getAnchorTargets(): Element[];
+    private render;
+    private renderAnchorList;
+    private handleEditorKey;
+    /**
+     * Fires after every keystroke in the editor (post-insertion). Looks
+     * for an `@<query>` pattern adjacent to the caret. If found, opens
+     * (or refreshes) the mention picker in editor mode. If the trigger
+     * disappears (user typed a space, backspaced over @, etc.), closes
+     * the picker.
+     */
+    private handleEditorInput;
+    /**
+     * Walk back from the caret looking for the most recent `@` that
+     * starts a mention trigger — must be at start-of-text-node or
+     * preceded by whitespace, and there must be no whitespace between
+     * `@` and the caret. Returns the Range covering `@<query>` plus
+     * the bare query string.
+     */
+    private detectMentionTrigger;
+    private handleEditorPaste;
+    private handleDragOver;
+    private handleDragLeave;
+    private handleDrop;
+    private handleFileChange;
+    private uploadAndAppend;
+    private renderAttachmentList;
+    private saveRange;
+    private restoreRange;
+    private insertChip;
+    private moveCursorToEnd;
+    /** Walk the editor and produce the markdown-ish string with ref tokens. */
+    private serializeEditor;
+    private handleClick;
+    /**
+     * Manual-mode picker: opens from the @ mention button. Renders a
+     * search input above the list; the user types into the input to
+     * filter, arrows + Enter to pick. The selection inserts a mention
+     * chip at the editor's current caret (no `@<query>` replacement —
+     * the user didn't type one).
+     */
+    private openMentionPicker;
+    /**
+     * Editor-mode picker: opens because the user typed `@` in the
+     * editor. No search input — the editor IS the search; the query is
+     * the text after `@`. On commit, replaces the `@<query>` range with
+     * the chip.
+     */
+    private openOrUpdateEditorMentionPicker;
+    /**
+     * Build the picker DOM scaffold and attach it to the popover. Does
+     * NOT fetch users or render the body — caller's responsibility.
+     * Search input is hidden in editor mode where the user already has
+     * a perfectly good text-entry surface (the editor itself).
+     */
+    private createMentionPickerShell;
+    /** Fetch the mentionable list. Swallows errors → []. */
+    private fetchMentionables;
+    /**
+     * Re-filter the cached users by `query`, render the list, reset
+     * selected to 0. Called on every search input change and on every
+     * editor input event while in editor mode.
+     */
+    private renderMentionPickerBody;
+    private moveMentionPickerSelection;
+    private refreshMentionPickerHighlight;
+    private commitMentionPickerSelection;
+    /**
+     * Swap a Range covering `@<query>` for a mention chip + trailing
+     * space, then place the caret after the space so the user can keep
+     * typing. Used only in editor-trigger mode.
+     */
+    private replaceRangeWithMentionChip;
+    /** Wires Esc + outside-click handlers to close the open picker. */
+    private wireMentionPickerDismiss;
+    private closeMentionPicker;
+    /** Position the picker below the given anchor (the @ mention button). */
+    private positionMentionPickerByElement;
+    /** Position the picker below the `@<query>` text range in the editor. */
+    private positionMentionPickerByRange;
+    /**
+     * Insert a mention chip for the given user into the editor at the
+     * current caret position. Accepts any user-like shape with a required
+     * `id` + `name` — covers both the current VizuUser (for self-mention)
+     * and MentionableUser (from the workspace member picker).
+     */
+    private insertMentionChip;
+    private save;
+    private position;
+    destroy(): void;
+}
+
+declare class Highlighter {
+    private overlay;
+    private root;
+    private current;
+    private extraIgnore;
+    private onClick;
+    private active;
+    private paused;
+    constructor(root: HTMLElement, extraIgnore: string[], onClick: (el: Element, mouseEvent: MouseEvent) => void);
+    private setCurrent;
+    start(): void;
+    stop(): void;
+    private shouldIgnore;
+    private handleMove;
+    private handleClick;
+    setPaused(paused: boolean): void;
+    isPaused(): boolean;
+    private handleScroll;
+    private updateOverlay;
+    destroy(): void;
+}
+
+interface SidebarCallbacks {
+    onJumpTo: (fp: ElementFingerprint) => void;
+    onJumpToReference: (commentId: string, refId: string) => void;
+    onDelete: (id: string) => void;
+    onUpdateStatus: (id: string, status: CommentStatus) => void;
+    onClose: () => void;
+}
+declare class Sidebar {
+    private el;
+    private root;
+    private callbacks;
+    private open;
+    private filter;
+    private lastComments;
+    private lastConfidence;
+    constructor(root: HTMLElement, callbacks: SidebarCallbacks);
+    toggle(comments: VizuComment[], confidence?: Map<string, MatchConfidence>): void;
+    show(comments: VizuComment[], confidence?: Map<string, MatchConfidence>): void;
+    update(comments: VizuComment[], confidence?: Map<string, MatchConfidence>): void;
+    close(): void;
+    isOpen(): boolean;
+    private render;
+    private headerHtml;
+    private handleClick;
+    destroy(): void;
+}
+
+declare function injectStyles(): void;
+
+export { Highlighter, Pill, type PillCallbacks, Popover, type PopoverCallbacks, Sidebar, injectStyles };