@unhingged/vizu-core 0.1.12 → 0.1.14

package/dist/index.d.cts

@@ -677,6 +677,13 @@ declare class Vizu {
     off<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
     setUser(user: VizuUser | null): void;
     getUser(): VizuUser | null;
+    /**
+     * Fetch the list of users who can be @-mentioned on the current
+     * workspace. Used by the popover's mention dropdown; hosts can also
+     * call this directly to build their own picker. Returns [] for
+     * non-cloud adapters (no workspace, no member list to fetch from).
+     */
+    searchMentionable(): Promise<MentionableUser[]>;
     /**
      * Whether the full Vizu UI (pill, highlighter, markers, popover) can
      * be mounted right now. Cloud-mode workspaces hold off until the

package/dist/index.d.ts

@@ -677,6 +677,13 @@ declare class Vizu {
     off<E extends VizuEventName>(event: E, handler: VizuEventHandler<E>): void;
     setUser(user: VizuUser | null): void;
     getUser(): VizuUser | null;
+    /**
+     * Fetch the list of users who can be @-mentioned on the current
+     * workspace. Used by the popover's mention dropdown; hosts can also
+     * call this directly to build their own picker. Returns [] for
+     * non-cloud adapters (no workspace, no member list to fetch from).
+     */
+    searchMentionable(): Promise<MentionableUser[]>;
     /**
      * Whether the full Vizu UI (pill, highlighter, markers, popover) can
      * be mounted right now. Cloud-mode workspaces hold off until the

package/dist/index.js

@@ -1235,8 +1235,54 @@ var Popover = class {
     this.pendingRefs = {};
     /** Attachments uploaded during this session, persisted into `comment.attachments` on save. */
     this.pendingAttachments = [];
+    /** Open mention picker element, if any. Held so the next openMentionPicker / close calls can tear it down. */
+    this.mentionPicker = null;
+    /** Dismiss handlers wired to document for the open picker; cleared in closeMentionPicker. */
+    this.mentionPickerDismiss = null;
+    /** All mentionable users fetched for the open picker — pre-filter list. */
+    this.mentionPickerUsers = [];
+    /** Currently visible subset of `mentionPickerUsers` after the user's filter. */
+    this.mentionPickerFiltered = [];
+    /** Highlighted index in `mentionPickerFiltered`. Up/Down arrows mutate this. */
+    this.mentionPickerSelected = 0;
+    /**
+     * '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.
+     */
+    this.mentionPickerMode = "manual";
+    /**
+     * 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.
+     */
+    this.mentionPickerEditorRange = null;
     this.handleEditorKey = (e) => {
       const editor = e.currentTarget;
+      if (this.mentionPicker && this.mentionPickerMode === "editor") {
+        if (e.key === "ArrowDown") {
+          e.preventDefault();
+          this.moveMentionPickerSelection(1);
+          return;
+        }
+        if (e.key === "ArrowUp") {
+          e.preventDefault();
+          this.moveMentionPickerSelection(-1);
+          return;
+        }
+        if (e.key === "Enter" || e.key === "Tab") {
+          if (this.mentionPickerFiltered.length > 0) {
+            e.preventDefault();
+            this.commitMentionPickerSelection();
+            return;
+          }
+        }
+        if (e.key === "Escape") {
+          e.preventDefault();
+          this.closeMentionPicker();
+          return;
+        }
+      }
       if (e.key === "#") {
         e.preventDefault();
         const savedRange = this.saveRange();
@@ -1259,6 +1305,21 @@ var Popover = class {
         this.callbacks.onClose();
       }
     };
+    /**
+     * 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.
+     */
+    this.handleEditorInput = () => {
+      const trigger = this.detectMentionTrigger();
+      if (trigger) {
+        void this.openOrUpdateEditorMentionPicker(trigger.range, trigger.query);
+      } else if (this.mentionPicker && this.mentionPickerMode === "editor") {
+        this.closeMentionPicker();
+      }
+    };
     this.handleEditorPaste = (e) => {
       if (this.callbacks.canUploadAttachments()) {
         const items = e.clipboardData?.items ?? null;
@@ -1341,7 +1402,7 @@ var Popover = class {
       else if (action === "save") this.save();
       else if (action === "mention") {
         e.preventDefault();
-        this.insertMentionChip(this.currentUser);
+        this.openMentionPicker(target);
       } else if (action === "upload") {
         e.preventDefault();
         const input = this.el.querySelector('[data-vz="file-input"]');
@@ -1450,6 +1511,7 @@ var Popover = class {
     this.position();
   }
   close() {
+    this.closeMentionPicker();
     this.el.style.display = "none";
     this.anchorTargets = [];
     this.anchorFingerprints = [];
@@ -1507,7 +1569,7 @@ var Popover = class {
       <div class="vz-popover-actions">
         <button class="vz-btn vz-btn-ghost" data-vz="close">Close</button>
         ${this.callbacks.canUploadAttachments() ? `<button class="vz-btn vz-btn-ghost vz-btn-upload" data-vz="upload" title="Attach an image">+ image</button>` : ""}
-        ${this.currentUser ? `<button class="vz-btn vz-btn-ghost vz-btn-mention" data-vz="mention" title="Mention ${escapeHtml(this.currentUser.name)}">@ mention</button>` : ""}
+        ${this.currentUser ? `<button class="vz-btn vz-btn-ghost vz-btn-mention" data-vz="mention" title="Mention a teammate">@ mention</button>` : ""}
         <button class="vz-btn vz-btn-primary" data-vz="save">Save</button>
       </div>
       <input type="file" class="vz-file-input" data-vz="file-input" accept="image/png,image/jpeg,image/webp,image/gif,image/svg+xml" hidden />
@@ -1518,6 +1580,7 @@ var Popover = class {
     const editor = this.el.querySelector(".vz-textarea");
     editor.focus();
     editor.addEventListener("keydown", this.handleEditorKey);
+    editor.addEventListener("input", this.handleEditorInput);
     editor.addEventListener("paste", this.handleEditorPaste);
     const wrap = this.el.querySelector(".vz-editor-wrap");
     if (wrap && this.callbacks.canUploadAttachments()) {
@@ -1547,6 +1610,37 @@ var Popover = class {
       <div class="vz-anchor-list">${chips}</div>
     `;
   }
+  /**
+   * 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.
+   */
+  detectMentionTrigger() {
+    const sel = window.getSelection();
+    if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return null;
+    const caret = sel.getRangeAt(0);
+    const node = caret.startContainer;
+    if (node.nodeType !== Node.TEXT_NODE) return null;
+    const text = node.textContent ?? "";
+    const offset = caret.startOffset;
+    for (let i = offset - 1; i >= 0; i--) {
+      const ch = text[i];
+      if (ch === "@") {
+        const prev = i > 0 ? text[i - 1] : "";
+        if (prev !== "" && !/\s/.test(prev)) return null;
+        const query = text.slice(i + 1, offset);
+        if (/\s/.test(query)) return null;
+        const range = document.createRange();
+        range.setStart(node, i);
+        range.setEnd(node, offset);
+        return { range, query };
+      }
+      if (/\s/.test(ch)) return null;
+    }
+    return null;
+  }
   async uploadAndAppend(file) {
     if (!this.callbacks.canUploadAttachments()) return;
     const placeholderId = "upload-" + Math.random().toString(36).slice(2, 9);
@@ -1676,11 +1770,254 @@ var Popover = class {
     for (const child of editor.childNodes) walk(child);
     return parts.join("").trim();
   }
+  /**
+   * 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).
+   */
+  async openMentionPicker(anchor) {
+    this.closeMentionPicker();
+    if (!this.callbacks.onMentionSearch) return;
+    this.mentionPickerMode = "manual";
+    this.mentionPickerEditorRange = null;
+    const picker = this.createMentionPickerShell();
+    this.positionMentionPickerByElement(picker, anchor);
+    const users = await this.fetchMentionables();
+    if (this.mentionPicker !== picker) return;
+    this.mentionPickerUsers = users;
+    this.renderMentionPickerBody("");
+    this.positionMentionPickerByElement(picker, anchor);
+    const input = picker.querySelector(".vz-mention-search");
+    input?.focus();
+    this.wireMentionPickerDismiss();
+  }
+  /**
+   * 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.
+   */
+  async openOrUpdateEditorMentionPicker(range, query) {
+    this.mentionPickerEditorRange = range;
+    if (!this.mentionPicker || this.mentionPickerMode !== "editor") {
+      this.closeMentionPicker();
+      this.mentionPickerMode = "editor";
+      const picker = this.createMentionPickerShell({ showSearch: false });
+      this.positionMentionPickerByRange(picker, range);
+      const users = await this.fetchMentionables();
+      if (this.mentionPicker !== picker) return;
+      this.mentionPickerUsers = users;
+      this.renderMentionPickerBody(query);
+      this.positionMentionPickerByRange(picker, range);
+      this.wireMentionPickerDismiss();
+      return;
+    }
+    this.renderMentionPickerBody(query);
+    this.positionMentionPickerByRange(this.mentionPicker, range);
+  }
+  /**
+   * 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).
+   */
+  createMentionPickerShell({ showSearch = true } = {}) {
+    const picker = document.createElement("div");
+    picker.className = "vz-mention-picker";
+    picker.setAttribute("data-vz-ignore", "");
+    picker.innerHTML = `
+      ${showSearch ? `<input class="vz-mention-search" type="text" placeholder="Search teammates\u2026" autocomplete="off" spellcheck="false" />` : ""}
+      <div class="vz-mention-list" data-vz="mention-list">
+        <div class="vz-mention-loading">Loading\u2026</div>
+      </div>
+    `;
+    this.el.appendChild(picker);
+    this.mentionPicker = picker;
+    this.mentionPickerFiltered = [];
+    this.mentionPickerSelected = 0;
+    picker.addEventListener("mousemove", (e) => {
+      const btn = e.target?.closest(".vz-mention-item");
+      if (!btn) return;
+      const idx = Number(btn.getAttribute("data-mention-index") ?? -1);
+      if (idx >= 0 && idx !== this.mentionPickerSelected) {
+        this.mentionPickerSelected = idx;
+        this.refreshMentionPickerHighlight();
+      }
+    });
+    picker.addEventListener("click", (e) => {
+      const btn = e.target?.closest(".vz-mention-item");
+      if (!btn) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const idx = Number(btn.getAttribute("data-mention-index") ?? -1);
+      if (idx >= 0) {
+        this.mentionPickerSelected = idx;
+        this.commitMentionPickerSelection();
+      }
+    });
+    if (showSearch) {
+      const input = picker.querySelector(".vz-mention-search");
+      input?.addEventListener("input", () => this.renderMentionPickerBody(input.value));
+      input?.addEventListener("keydown", (e) => {
+        if (e.key === "ArrowDown") {
+          e.preventDefault();
+          this.moveMentionPickerSelection(1);
+        } else if (e.key === "ArrowUp") {
+          e.preventDefault();
+          this.moveMentionPickerSelection(-1);
+        } else if (e.key === "Enter" || e.key === "Tab") {
+          if (this.mentionPickerFiltered.length > 0) {
+            e.preventDefault();
+            this.commitMentionPickerSelection();
+          }
+        } else if (e.key === "Escape") {
+          e.preventDefault();
+          this.closeMentionPicker();
+        }
+      });
+    }
+    return picker;
+  }
+  /** Fetch the mentionable list. Swallows errors → []. */
+  async fetchMentionables() {
+    if (!this.callbacks.onMentionSearch) return [];
+    try {
+      return await this.callbacks.onMentionSearch();
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * 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.
+   */
+  renderMentionPickerBody(query) {
+    const picker = this.mentionPicker;
+    if (!picker) return;
+    const list = picker.querySelector('[data-vz="mention-list"]');
+    if (!list) return;
+    const q = query.toLowerCase().trim();
+    this.mentionPickerFiltered = q ? this.mentionPickerUsers.filter((u) => u.name.toLowerCase().includes(q)) : this.mentionPickerUsers.slice();
+    this.mentionPickerSelected = 0;
+    if (this.mentionPickerFiltered.length === 0) {
+      list.innerHTML = `<div class="vz-mention-empty">${this.mentionPickerUsers.length === 0 ? "No teammates to mention yet." : "No teammates match."}</div>`;
+      return;
+    }
+    list.innerHTML = this.mentionPickerFiltered.map((u, i) => {
+      const avatar = u.avatarUrl ? `<img class="vz-mention-avatar" src="${escapeHtml(u.avatarUrl)}" alt="" />` : `<span class="vz-mention-avatar vz-mention-avatar-initials">${escapeHtml(initials(u.name) || "?")}</span>`;
+      return `<button class="vz-mention-item${i === 0 ? " is-selected" : ""}" type="button" data-mention-index="${i}">${avatar}<span class="vz-mention-item-name">${escapeHtml(u.name)}</span></button>`;
+    }).join("");
+  }
+  moveMentionPickerSelection(delta) {
+    if (this.mentionPickerFiltered.length === 0) return;
+    const n = this.mentionPickerFiltered.length;
+    this.mentionPickerSelected = (this.mentionPickerSelected + delta + n) % n;
+    this.refreshMentionPickerHighlight();
+  }
+  refreshMentionPickerHighlight() {
+    const picker = this.mentionPicker;
+    if (!picker) return;
+    const items = picker.querySelectorAll(".vz-mention-item");
+    items.forEach((el, i) => el.classList.toggle("is-selected", i === this.mentionPickerSelected));
+    items[this.mentionPickerSelected]?.scrollIntoView({ block: "nearest" });
+  }
+  commitMentionPickerSelection() {
+    const user = this.mentionPickerFiltered[this.mentionPickerSelected];
+    if (!user) return;
+    if (this.mentionPickerMode === "editor" && this.mentionPickerEditorRange) {
+      this.replaceRangeWithMentionChip(this.mentionPickerEditorRange, user);
+    } else {
+      this.insertMentionChip(user);
+    }
+    this.closeMentionPicker();
+  }
+  /**
+   * 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.
+   */
+  replaceRangeWithMentionChip(range, user) {
+    const editor = this.el.querySelector(".vz-textarea");
+    if (!editor) return;
+    const chip = document.createElement("span");
+    chip.className = "vz-chip vz-chip-mention";
+    chip.contentEditable = "false";
+    chip.setAttribute("data-mention-id", user.id);
+    chip.textContent = "@" + user.name;
+    range.deleteContents();
+    range.insertNode(chip);
+    const space = document.createTextNode(" ");
+    chip.after(space);
+    const sel = window.getSelection();
+    if (sel) {
+      const after = document.createRange();
+      after.setStartAfter(space);
+      after.collapse(true);
+      sel.removeAllRanges();
+      sel.addRange(after);
+    }
+    editor.focus();
+  }
+  /** Wires Esc + outside-click handlers to close the open picker. */
+  wireMentionPickerDismiss() {
+    if (this.mentionPickerDismiss) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        this.closeMentionPicker();
+      }
+    };
+    const onOutside = (e) => {
+      if (!this.mentionPicker) return;
+      if (this.mentionPicker.contains(e.target)) return;
+      if (this.mentionPickerMode === "editor") {
+        const editor = this.el.querySelector(".vz-textarea");
+        if (editor && editor.contains(e.target)) return;
+      }
+      this.closeMentionPicker();
+    };
+    document.addEventListener("keydown", onKey, true);
+    document.addEventListener("mousedown", onOutside, true);
+    this.mentionPickerDismiss = () => {
+      document.removeEventListener("keydown", onKey, true);
+      document.removeEventListener("mousedown", onOutside, true);
+    };
+  }
+  closeMentionPicker() {
+    if (this.mentionPickerDismiss) {
+      this.mentionPickerDismiss();
+      this.mentionPickerDismiss = null;
+    }
+    if (this.mentionPicker) {
+      this.mentionPicker.remove();
+      this.mentionPicker = null;
+    }
+    this.mentionPickerFiltered = [];
+    this.mentionPickerSelected = 0;
+    this.mentionPickerEditorRange = null;
+  }
+  /** Position the picker below the given anchor (the @ mention button). */
+  positionMentionPickerByElement(picker, anchor) {
+    const popRect = this.el.getBoundingClientRect();
+    const btnRect = anchor.getBoundingClientRect();
+    picker.style.left = `${btnRect.left - popRect.left}px`;
+    picker.style.top = `${btnRect.bottom - popRect.top + 4}px`;
+  }
+  /** Position the picker below the `@<query>` text range in the editor. */
+  positionMentionPickerByRange(picker, range) {
+    const popRect = this.el.getBoundingClientRect();
+    const rect = range.getBoundingClientRect();
+    picker.style.left = `${rect.left - popRect.left}px`;
+    picker.style.top = `${rect.bottom - popRect.top + 4}px`;
+  }
   /**
    * Insert a mention chip for the given user into the editor at the
-   * current caret position. Owner-only ACL in v1: the only callable
-   * "mentionable" user is the current Vizu user (= workspace owner).
-   * Future versions can expand this with an autocomplete dropdown.
+   * 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).
    */
   insertMentionChip(user) {
     if (!user || !user.id) return;
@@ -1757,6 +2094,7 @@ var Popover = class {
     this.el.style.left = left + "px";
   }
   destroy() {
+    this.closeMentionPicker();
     this.el.removeEventListener("click", this.handleClick);
     this.el.remove();
   }
@@ -2535,6 +2873,91 @@ var STYLES = `
 }
 .vz-btn-primary:hover { background: color-mix(in srgb, var(--vz-accent) 88%, white); }
 
+/* Mention picker \u2014 floating dropdown anchored under the @ mention button */
+.vz-mention-picker {
+  position: absolute;
+  z-index: 10;
+  min-width: 200px;
+  max-width: 280px;
+  max-height: 240px;
+  overflow-y: auto;
+  padding: 4px;
+  background: var(--vz-bg-popover, #1c1c1c);
+  border: 1px solid var(--vz-border, rgba(255,255,255,0.08));
+  border-radius: 8px;
+  box-shadow: 0 12px 28px rgba(0,0,0,0.4), 0 2px 6px rgba(0,0,0,0.3);
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.vz-mention-search {
+  width: 100%;
+  padding: 7px 9px;
+  margin-bottom: 4px;
+  background: rgba(255,255,255,0.04);
+  border: 1px solid var(--vz-border, rgba(255,255,255,0.08));
+  border-radius: 6px;
+  color: #fafafa;
+  font-size: 13px;
+  outline: none;
+  box-sizing: border-box;
+}
+.vz-mention-search:focus { border-color: var(--vz-accent, #ff8b6e); }
+.vz-mention-search::placeholder { color: var(--vz-text-muted); }
+.vz-mention-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-height: 0;
+}
+.vz-mention-loading,
+.vz-mention-empty {
+  padding: 10px 12px;
+  font-size: 12px;
+  color: var(--vz-text-muted);
+  text-align: center;
+}
+.vz-mention-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 10px;
+  border-radius: 6px;
+  background: transparent;
+  border: none;
+  color: #fafafa;
+  font-size: 13px;
+  text-align: left;
+  cursor: pointer;
+  transition: background 80ms;
+}
+.vz-mention-item.is-selected,
+.vz-mention-item:focus-visible {
+  background: var(--vz-bg-hover, rgba(255,255,255,0.08));
+  outline: none;
+}
+.vz-mention-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px; height: 22px;
+  border-radius: 50%;
+  font-size: 10px; font-weight: 600;
+  color: var(--vz-marker-fg, #0a0a0a);
+  background: var(--vz-accent, #ff8b6e);
+  flex-shrink: 0;
+  overflow: hidden;
+}
+.vz-mention-avatar img {
+  width: 100%; height: 100%; object-fit: cover;
+}
+.vz-mention-item-name {
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
 /* Sidebar */
 .vz-sidebar {
   position: fixed;
@@ -3302,6 +3725,18 @@ var Vizu = class {
   getUser() {
     return this.user;
   }
+  /**
+   * Fetch the list of users who can be @-mentioned on the current
+   * workspace. Used by the popover's mention dropdown; hosts can also
+   * call this directly to build their own picker. Returns [] for
+   * non-cloud adapters (no workspace, no member list to fetch from).
+   */
+  async searchMentionable() {
+    if (this.storage instanceof CloudStorageAdapter) {
+      return this.storage.searchMentionable();
+    }
+    return [];
+  }
   /**
    * Whether the full Vizu UI (pill, highlighter, markers, popover) can
    * be mounted right now. Cloud-mode workspaces hold off until the
@@ -3657,7 +4092,8 @@ var Vizu = class {
       onClose: () => this.closePopover(),
       onStartReferencePick: (onPicked, onCancel) => this.startPicking(onPicked, onCancel),
       onJumpToReference: (commentId, refId2) => this.jumpToReference(commentId, refId2),
-      onAnchorsChanged: (fps) => this.syncActiveAnchorOutlines(fps)
+      onAnchorsChanged: (fps) => this.syncActiveAnchorOutlines(fps),
+      onMentionSearch: () => this.searchMentionable()
     });
     this.popover.setUser(this.user);
     this.sidebar = new Sidebar(this.root, {