@plannotator/ui 0.42.0 → 0.43.1

package/components/html-viewer/HtmlViewer.tsx

@@ -6,6 +6,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
 import { useVimDocumentFocus } from "../../hooks/useVimDocumentFocus";
@@ -24,6 +25,8 @@ import {
   type VimHudCommand,
 } from "../../utils/vimHud";
 import { AnnotationToolbar } from "../AnnotationToolbar";
+import type { SelectionAction } from "../../utils/selectionActions";
+import type { MentionSource } from "../../utils/mentions";
 import { AttachmentsButton } from "../AttachmentsButton";
 import {
   CommentPopover,
@@ -265,6 +268,18 @@ export interface HtmlViewerProps {
    *  to the bridge so the in-page toggle stops at the same number. Default
    *  16 (the package cap); absent leaves every message unchanged. */
   maxAdditionalTargets?: number;
+  /** Opt-in host capability, passed straight through to the selection
+   *  toolbar: the host's own commands for the current selection, rendered as
+   *  one wand button that opens the package's dropdown. Absent → unchanged. */
+  selectionActions?: SelectionAction[];
+  /** Opt-in host capability: the glyph on the `selectionActions` button.
+   *  Absent → the package's own wand. */
+  selectionActionsIcon?: ReactNode;
+  /** Opt-in host capability, forwarded to BOTH comment composers this viewer
+   *  mounts (the pinpoint/selection composer and the global one): the `@`
+   *  mention source for the composer's picker. The picked ids ride onto the
+   *  created annotation as `Annotation.mentions`. Absent → unchanged. */
+  mentionSource?: MentionSource;
   /** scrollIntoView behavior when a selected annotation is scrolled into
    *  view inside the page. Default 'smooth'; pass 'auto' to carry the
    *  parent's reduced-motion preference across the iframe boundary. */
@@ -352,6 +367,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       readOnly = false,
       onUnanchoredChange,
       maxAdditionalTargets,
+      selectionActions,
+      selectionActionsIcon,
+      mentionSource,
       scrollBehavior,
       title = "HTML Plan Viewer",
       bridgeScriptUrl,
@@ -989,7 +1007,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     }));
 
     const handleGlobalCommentSubmit = useCallback(
-      (text: string, images?: ImageAttachment[]) => {
+      (text: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
         if (readOnly) return;
         onAddAnnotation({
           id: `global-${Date.now()}`,
@@ -1002,6 +1020,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
           author: getIdentity(),
           createdA: Date.now(),
           images,
+          ...(mentions && mentions.length > 0 ? { mentions } : {}),
         });
         setGlobalCommentPopover(null);
       },
@@ -1202,6 +1221,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               // wrapper filters by id as defense in depth, so no present or
               // future toolbar path can emit an arbitrary label here.
               commentOnly
+              selectionActions={selectionActions}
+              selectionActionsIcon={selectionActionsIcon}
               onQuickLabel={(label) => {
                 if (label.id === THUMBS_UP_LABEL.id) hook.handleQuickLabel(label);
               }}
@@ -1222,6 +1243,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               isGlobal={false}
               draftKey={`html:${hook.commentPopover.draftKey}`}
               onSubmit={hook.handleCommentSubmit}
+              mentionSource={mentionSource}
               // Pinpoint clicks open this composer directly, so it carries
               // the surface's one-click "Looks good" (the global composer
               // does not: a document-wide thumbs-up is not a thing).
@@ -1253,6 +1275,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               isGlobal={true}
               onSubmit={handleGlobalCommentSubmit}
               onClose={() => setGlobalCommentPopover(null)}
+              mentionSource={mentionSource}
               skillReferences
               onAskAI={onAskAI}
               askAIContext={{ kind: "general", label: "Document" }}

package/components/html-viewer/useHtmlAnnotation.ts

@@ -911,7 +911,7 @@ export function useHtmlAnnotation({
   );
 
   const handleCommentSubmit = useCallback(
-    (comment: string, images?: ImageAttachment[]) => {
+    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
       if (!enabledRef.current) return;
       // Prefer the text captured when the popover opened — it can't be clobbered by
       // a later selection change or clear while the user is composing the comment.
@@ -944,6 +944,9 @@ export function useHtmlAnnotation({
         author: getIdentity(),
         createdA: Date.now(),
         images,
+        // Host capability: present only when a mentionSource was supplied AND
+        // a token survived, so a comment without one is unchanged.
+        ...(mentions && mentions.length > 0 ? { mentions } : {}),
         htmlAnchor: pendingAnchorRef.current ?? undefined,
         elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,

package/hooks/useAnnotationHighlighter.ts

@@ -631,7 +631,13 @@ export interface UseAnnotationHighlighterReturn {
   handleQuickLabel: (label: QuickLabel) => void;
   handleToolbarClose: () => void;
   handleRequestComment: (initialChar?: string) => void;
-  handleCommentSubmit: (text: string, images?: ImageAttachment[]) => void;
+  /** The composer's submit. `mentions` arrives only from a `CommentPopover`
+   *  the host gave a `mentionSource`; the ids ride onto the new annotation. */
+  handleCommentSubmit: (
+    text: string,
+    images?: ImageAttachment[],
+    mentions?: readonly string[],
+  ) => void;
   handleCommentClose: () => void;
   handleFloatingQuickLabel: (label: QuickLabel) => void;
   handleQuickLabelPickerDismiss: () => void;
@@ -870,6 +876,7 @@ export function useAnnotationHighlighter({
     images?: ImageAttachment[],
     isQuickLabel?: boolean,
     quickLabelTip?: string,
+    mentions?: readonly string[],
   ) => {
     const doms = highlighter.getDoms(source.id);
     let blockId = '';
@@ -904,6 +911,9 @@ export function useAnnotationHighlighter({
       startMeta: source.startMeta,
       endMeta: source.endMeta,
       images,
+      // Host capability: present only when a mentionSource was supplied AND a
+      // token survived, so an annotation created without one is unchanged.
+      ...(mentions && mentions.length > 0 ? { mentions } : {}),
       ...(mathTargets.length > 0 ? {
         mathTargets: mathTargets.map(target => ({
           blockId: target.blockId,
@@ -933,6 +943,7 @@ export function useAnnotationHighlighter({
     images?: ImageAttachment[],
     isQuickLabel?: boolean,
     quickLabelTip?: string,
+    mentions?: readonly string[],
   ) => {
     const id = annotationId();
     applyMathAnnotationClass(source.element, id, type, source.displayMode);
@@ -951,6 +962,7 @@ export function useAnnotationHighlighter({
       createdA: Date.now(),
       author: getIdentity(),
       images,
+      ...(mentions && mentions.length > 0 ? { mentions } : {}),
       ...(isQuickLabel ? { isQuickLabel: true } : {}),
       ...(quickLabelTip ? { quickLabelTip } : {}),
     };
@@ -1695,7 +1707,11 @@ export function useAnnotationHighlighter({
     setToolbarState(null);
   };
 
-  const handleCommentSubmit = (text: string, images?: ImageAttachment[]) => {
+  const handleCommentSubmit = (
+    text: string,
+    images?: ImageAttachment[],
+    mentions?: readonly string[],
+  ) => {
     if (!commentPopover) return;
     if (isMathAnnotationSource(commentPopover.source)) {
       createAnnotationFromMathSource(
@@ -1703,6 +1719,9 @@ export function useAnnotationHighlighter({
         AnnotationType.COMMENT,
         text,
         images,
+        undefined,
+        undefined,
+        mentions,
       );
       clearPendingSelection();
       window.getSelection()?.removeAllRanges();
@@ -1712,7 +1731,7 @@ export function useAnnotationHighlighter({
     if (commentPopover.source && highlighterRef.current) {
       createAnnotationFromSource(
         highlighterRef.current, commentPopover.source,
-        AnnotationType.COMMENT, text, images
+        AnnotationType.COMMENT, text, images, undefined, undefined, mentions
       );
       clearPendingSelection();
       window.getSelection()?.removeAllRanges();

package/hooks/useMentionAutocomplete.ts

@@ -0,0 +1,246 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type React from 'react';
+import {
+  applyMentionPick,
+  mentionMatches,
+  mentionTrigger,
+  survivingMentions,
+  type MentionPerson,
+  type MentionSource,
+  type MentionTrigger,
+} from '../utils/mentions';
+import { mentionAnchorOf, type MentionAnchor } from '../components/MentionPicker';
+
+export interface MentionMenuState {
+  items: readonly MentionPerson[];
+  /** Shown as one non-selectable row when `items` is empty. */
+  emptyNotice: string | null;
+  /** Explicitly activated row, or null — the menu opens with NOTHING active. */
+  activeIndex: number | null;
+  /** Measured textarea rect the portaled picker is placed from. */
+  anchor: MentionAnchor | null;
+  query: string;
+}
+
+export interface UseMentionAutocompleteResult {
+  /** Open menu state, or null. Render MentionPicker from this. */
+  menu: MentionMenuState | null;
+  /** Call in the textarea's onKeyDown; true means the event was consumed. */
+  onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => boolean;
+  /** Call from the textarea's onSelect and onChange (every caret move + input). */
+  onSelect: () => void;
+  /** Insert the given menu item at the active trigger. */
+  select: (index: number) => void;
+  /** The ids whose readable token still survives in the text. */
+  mentionIds: readonly string[];
+}
+
+/**
+ * `@` mention autocomplete for a comment textarea, driven entirely by a
+ * host-supplied `MentionSource`. With no source every path here is inert:
+ * no listener is registered, no menu state is ever open, `mentionIds` stays
+ * the same frozen empty array, and the composer renders and behaves exactly
+ * as it did before the prop existed.
+ *
+ * NO-PRESELECTION INVARIANT (shared with `useSkillReferenceAutocomplete`):
+ * the menu opens with no row active, and while no row is active Enter and
+ * Tab behave exactly as if the menu were not open — a body that ends
+ * "ping @" plus Enter is still a newline. A row becomes active only through
+ * explicit keyboard navigation (ArrowDown from none lands on the FIRST row,
+ * ArrowUp from none on the LAST) or a pointer click, which inserts directly.
+ *
+ * DELIBERATE DIFFERENCE from the `/` and `$` skill trigger: the arrows engage
+ * this menu even on a BARE trigger (`@` with no query typed). `$` and `/` are
+ * ordinary prose characters, so their menu must yield the arrows back to
+ * caret navigation; `@` at a word boundary is an unambiguous tag gesture, and
+ * typing `@` then ArrowDown is how the host's own reply box already behaves.
+ * Escape closes the menu whenever it is visible, for the same reason.
+ */
+const NO_IDS: readonly string[] = Object.freeze([]);
+const NO_PEOPLE: readonly MentionPerson[] = Object.freeze([]);
+
+export function useMentionAutocomplete(options: {
+  text: string;
+  setText: (text: string) => void;
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+  source?: MentionSource;
+}): UseMentionAutocompleteResult {
+  const { text, setText, textareaRef, source } = options;
+  const enabled = !!source;
+  const [caret, setCaret] = useState<number | null>(null);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [tagged, setTagged] = useState<readonly MentionPerson[]>(NO_PEOPLE);
+  const [anchor, setAnchor] = useState<MentionAnchor | null>(null);
+  // Escape dismisses the menu for the trigger it was open on; the same trigger
+  // does not reopen until the caret leaves it.
+  const [dismissedStart, setDismissedStart] = useState<number | null>(null);
+
+  const trigger: MentionTrigger | null = useMemo(() => {
+    if (!enabled || caret === null) return null;
+    return mentionTrigger(text, caret);
+  }, [enabled, text, caret]);
+
+  // A token the author deleted stops being a tag, so the body and the
+  // reported ids never disagree about who was named.
+  const survivors = useMemo(() => survivingMentions(text, tagged), [text, tagged]);
+  useEffect(() => {
+    if (survivors.length !== tagged.length) setTagged(survivors);
+  }, [survivors, tagged]);
+
+  const taggedIds = useMemo(() => new Set(survivors.map((p) => p.id)), [survivors]);
+  const mentionIds = useMemo(
+    () => (enabled ? survivors.map((p) => p.id) : NO_IDS),
+    [enabled, survivors],
+  );
+
+  const onMentionsChange = source?.onMentionsChange;
+  const mentionsKey = mentionIds.join('\u0000');
+  const lastReported = useRef<string | null>(null);
+  useEffect(() => {
+    if (!onMentionsChange) return;
+    if (lastReported.current === mentionsKey) return;
+    lastReported.current = mentionsKey;
+    onMentionsChange(mentionIds);
+    // mentionIds is keyed by mentionsKey; re-running on identity alone would
+    // report the same ids on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mentionsKey, onMentionsChange]);
+
+  const items = useMemo(
+    () => (source && trigger ? mentionMatches(source.people, trigger, taggedIds) : []),
+    [source, trigger, taggedIds],
+  );
+
+  const emptyNotice = source?.emptyNotice ?? null;
+  const open =
+    trigger !== null
+    && trigger.from !== dismissedStart
+    && (items.length > 0 || !!emptyNotice);
+
+  // A new trigger start clears the dismissal memory.
+  const triggerStart = trigger?.from ?? null;
+  const lastTriggerStart = useRef<number | null>(null);
+  useEffect(() => {
+    if (triggerStart !== lastTriggerStart.current) {
+      lastTriggerStart.current = triggerStart;
+      setDismissedStart(null);
+    }
+  }, [triggerStart]);
+
+  // Any trigger change — a new one, or more typing re-filtering the same one —
+  // disarms the active row, so an activation always refers to the exact list
+  // the user was looking at.
+  const triggerQuery = trigger?.query ?? null;
+  useEffect(() => {
+    setActiveIndex(null);
+  }, [triggerStart, triggerQuery]);
+
+  // Measure the composer while the menu is open (and follow scroll/resize).
+  useEffect(() => {
+    if (!open) {
+      setAnchor(null);
+      return;
+    }
+    const measure = () => setAnchor(mentionAnchorOf(textareaRef.current));
+    measure();
+    window.addEventListener('scroll', measure, true);
+    window.addEventListener('resize', measure);
+    return () => {
+      window.removeEventListener('scroll', measure, true);
+      window.removeEventListener('resize', measure);
+    };
+  }, [open, textareaRef, triggerStart, triggerQuery]);
+
+  const boundedActive =
+    activeIndex !== null && activeIndex >= 0 && activeIndex < items.length ? activeIndex : null;
+
+  const readCaret = useCallback(() => {
+    if (!enabled) return;
+    const el = textareaRef.current;
+    setCaret(el ? el.selectionStart : null);
+  }, [enabled, textareaRef]);
+
+  const select = useCallback(
+    (index: number) => {
+      const el = textareaRef.current;
+      if (!source || !trigger) return;
+      const person = items[index];
+      if (!person) return;
+      if (person.canOpen === false && source.onPickBlocked) {
+        // Nothing is inserted: the host owns the no-access affordance.
+        source.onPickBlocked(person);
+        setActiveIndex(null);
+        setDismissedStart(trigger.from);
+        return;
+      }
+      const result = applyMentionPick(text, trigger, person);
+      setText(result.text);
+      setCaret(result.caret);
+      setTagged((prev) => (prev.some((p) => p.id === person.id) ? prev : [...prev, person]));
+      setActiveIndex(null);
+      // Close deterministically: the DOM caret only moves in the timer below,
+      // and React's select plugin can re-read the STALE caret before then,
+      // transiently reopening the menu on the just-replaced query.
+      setDismissedStart(trigger.from);
+      setTimeout(() => {
+        if (!el || !el.isConnected) return;
+        el.focus();
+        el.setSelectionRange(result.caret, result.caret);
+      }, 0);
+    },
+    [items, setText, source, text, textareaRef, trigger],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>): boolean => {
+      if (!open || !trigger) return false;
+      // Never consume keys mid-composition: for Pinyin, Telex and friends the
+      // composition buffer is ASCII, so Enter can mean "commit this candidate".
+      if (e.nativeEvent.isComposing) return false;
+      if (e.metaKey || e.ctrlKey || e.altKey) return false;
+      switch (e.key) {
+        case 'ArrowDown':
+        case 'ArrowUp':
+          if (items.length === 0) return false; // the empty-notice row is not navigable
+          e.preventDefault();
+          if (e.key === 'ArrowDown') {
+            setActiveIndex(boundedActive === null ? 0 : (boundedActive + 1) % items.length);
+          } else {
+            setActiveIndex(
+              boundedActive === null
+                ? items.length - 1
+                : (boundedActive - 1 + items.length) % items.length,
+            );
+          }
+          return true;
+        case 'Enter':
+        case 'Tab':
+          // NO row active means these keys were NOT aimed at the menu: Enter
+          // stays a newline, Tab still leaves the field.
+          if (boundedActive === null) return false;
+          e.preventDefault();
+          select(boundedActive);
+          return true;
+        case 'Escape':
+          e.preventDefault();
+          e.stopPropagation();
+          setActiveIndex(null);
+          setDismissedStart(trigger.from);
+          return true;
+        default:
+          return false;
+      }
+    },
+    [boundedActive, items.length, open, select, trigger],
+  );
+
+  return {
+    menu: open && trigger
+      ? { items, emptyNotice, activeIndex: boundedActive, anchor, query: trigger.query }
+      : null,
+    onKeyDown,
+    onSelect: readCaret,
+    select,
+    mentionIds,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.42.0",
+  "version": "0.43.1",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",