@plannotator/ui 0.42.0 → 0.43.1

package/types.ts

@@ -83,6 +83,7 @@ export interface Annotation {
   author?: string; // Tater identity for collaborative sharing
   source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API
   images?: ImageAttachment[]; // Attached images with human-readable names
+  mentions?: readonly string[]; // opaque host ids named with `@` in the comment body, set ONLY when a host supplied a `mentionSource` to the composer and at least one token survived; the key is absent otherwise. Host data: the package never renders, exports, shares or archives it.
   isQuickLabel?: boolean; // true if created via quick label chip
   quickLabelTip?: string; // optional instruction tip from the label definition
   diffContext?: 'added' | 'removed' | 'modified'; // set when annotation created in plan diff view
@@ -450,3 +451,15 @@ export type {
   AgentCapability,
   AgentCapabilities,
 } from '@plannotator/core/agent-jobs';
+
+/** Host toolbar seams (opt-in; Plannotator supplies neither). */
+export type {
+  SelectionAction,
+  SelectionActionContext,
+} from './utils/selectionActions';
+
+export type {
+  MentionPerson,
+  MentionSource,
+  MentionTrigger,
+} from './utils/mentions';

package/utils/mentions.ts

@@ -0,0 +1,149 @@
+/**
+ * The `@` grammar for a PLAIN TEXTAREA comment composer, and the one place it
+ * is spelled in this package.
+ *
+ * These are the host's own rules, ported as pure functions so the package can
+ * own the typing behavior while the host owns the people: the trigger regex,
+ * the word-boundary guard that keeps `a@b.com` from opening a menu, the
+ * readable `@Label` insertion, and the surviving-token rule that keeps the
+ * body and the reported mention ids from ever disagreeing about who was named.
+ *
+ * Nothing here touches the DOM, fetches, or persists. A composer with no
+ * `mentionSource` never calls any of it.
+ */
+
+/** One pickable identity, supplied by the host. */
+export interface MentionPerson {
+  /** Opaque host id (a user id, a credential id). Reported back verbatim. */
+  readonly id: string;
+  readonly kind: 'user' | 'agent';
+  readonly label: string;
+  /** Right-aligned hint shown after the label (an email, "Agent"), or null. */
+  readonly detail: string | null;
+  /**
+   * Whether this person can open the document. Host data: rows render
+   * identically either way, and a `false` row is only special when the host
+   * supplied `onPickBlocked` (see `MentionSource`).
+   */
+  readonly canOpen: boolean;
+}
+
+/** The opt-in `@` mention source for `CommentPopover`'s composer. */
+export interface MentionSource {
+  /** The people this composer may offer. An empty list shows `emptyNotice`. */
+  readonly people: readonly MentionPerson[];
+  /**
+   * The honest-empty row's text when there is no one to offer, or null/absent
+   * to keep the menu closed instead.
+   */
+  readonly emptyNotice?: string | null;
+  /** Fires on every text change with the ids whose token still survives in the body. */
+  readonly onMentionsChange?: (ids: readonly string[]) => void;
+  /**
+   * A `canOpen: false` person was picked. When supplied, NOTHING is inserted
+   * and the host shows its own no-access affordance. When absent, such a
+   * person inserts like any other.
+   */
+  readonly onPickBlocked?: (person: MentionPerson) => void;
+}
+
+/**
+ * THE trigger: `@` plus a word-ish query, anchored at the caret. The
+ * word-boundary check that makes `a@b.com` safe is the caller's (below),
+ * because a textarea walks the string.
+ */
+export const MENTION_QUERY_RE = /@[\w .-]*$/;
+
+/**
+ * Sanitize a display label for the inserted token: byte shapes that would
+ * break a `[@…](…)` link grammar are replaced and whitespace collapsed, so a
+ * host that later rewrites the body into links reads back what it wrote.
+ */
+export function sanitizeMentionLabel(label: string): string {
+  return label
+    .replace(/[[\]|\n\r]/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim();
+}
+
+export interface MentionTrigger {
+  /** What was typed after the `@`, trimmed and lowercased for matching. */
+  readonly query: string;
+  /** Offset of the `@` itself, so a pick can swallow it. */
+  readonly from: number;
+  /** Offset just past the typed query (the caret). */
+  readonly to: number;
+}
+
+/**
+ * The trigger under the caret, or null. The word-boundary check is the whole
+ * email guard: the character before the `@` must be a line start or
+ * whitespace, so typing `a@b.com` never opens the picker.
+ */
+export function mentionTrigger(text: string, caret: number): MentionTrigger | null {
+  const before = text.slice(0, caret);
+  const match = MENTION_QUERY_RE.exec(before);
+  if (match === null) return null;
+  const from = match.index;
+  if (from > 0) {
+    const prior = before.charAt(from - 1);
+    if (!/\s/u.test(prior)) return null;
+  }
+  return { query: match[0].slice(1).trim().toLowerCase(), from, to: caret };
+}
+
+/**
+ * The people this trigger offers: users only (an agent is not taggable in a
+ * comment), never one already tagged in this draft, de-duplicated by id, and
+ * filtered on label or detail once a query character exists.
+ */
+export function mentionMatches(
+  people: readonly MentionPerson[],
+  trigger: MentionTrigger,
+  alreadyTagged: ReadonlySet<string>,
+): readonly MentionPerson[] {
+  const seen = new Set<string>();
+  return people.filter((person) => {
+    if (person.kind !== 'user') return false;
+    if (alreadyTagged.has(person.id) || seen.has(person.id)) return false;
+    seen.add(person.id);
+    if (trigger.query === '') return true;
+    return (
+      person.label.toLowerCase().includes(trigger.query) ||
+      (person.detail ?? '').toLowerCase().includes(trigger.query)
+    );
+  });
+}
+
+/** The readable token this person's name becomes in the body. */
+export function mentionToken(person: MentionPerson): string {
+  return `@${sanitizeMentionLabel(person.label)}`;
+}
+
+/**
+ * Picking: the typed `@query` is replaced by the readable token plus one
+ * space, and the caret lands after it.
+ */
+export function applyMentionPick(
+  text: string,
+  trigger: MentionTrigger,
+  person: MentionPerson,
+): { readonly text: string; readonly caret: number } {
+  const insert = `${mentionToken(person)} `;
+  return {
+    text: text.slice(0, trigger.from) + insert + text.slice(trigger.to),
+    caret: trigger.from + insert.length,
+  };
+}
+
+/**
+ * The people a draft still tags. A token the author deleted from the text
+ * stops being a tag: the body and the reported ids never disagree about who
+ * was named, which is what makes the readable `@Name` honest.
+ */
+export function survivingMentions(
+  text: string,
+  tagged: readonly MentionPerson[],
+): readonly MentionPerson[] {
+  return tagged.filter((person) => text.includes(mentionToken(person)));
+}

package/utils/selectionActions.ts

@@ -0,0 +1,64 @@
+/**
+ * Host selection actions — the opt-in seam that lets a host put its own
+ * commands on the selection toolbar beside (or instead of) the quick labels.
+ *
+ * The package renders the button and the dropdown and hands back the
+ * selection context; it creates NO annotation of its own. What an action does
+ * is entirely the host's business. Plannotator supplies none of these, so
+ * nothing here runs in Plannotator's apps.
+ */
+
+import type React from 'react';
+
+/** What the toolbar knows about the selection an action was invoked on. */
+export interface SelectionActionContext {
+  /** The selected text (the toolbar's copy text, else the element's text). */
+  text: string;
+  /** The enclosing `[data-block-id]`, or '' on surfaces that have none (raw HTML). */
+  blockId: string;
+  /** Offset of the selection within the block's text, 0 when unknown. */
+  startOffset: number;
+  /** `startOffset + text.length` — so on a block-less surface it is the
+   *  selection's length, not 0. */
+  endOffset: number;
+  /** The element the toolbar is anchored to. */
+  element: HTMLElement;
+}
+
+export interface SelectionAction {
+  id: string;
+  label: string;
+  /** Optional dimmed second line under the label. */
+  detail?: string;
+  /** Optional leading icon; a colored bar is drawn when absent. */
+  icon?: React.ReactNode;
+  onSelect: (ctx: SelectionActionContext) => void;
+}
+
+/**
+ * Build the context for an invoked action from what the toolbar has: its
+ * anchor element and the selected text. The block lookup and the offset
+ * arithmetic deliberately reproduce `createAnnotationFromSource`'s, so an
+ * action sees the same coordinates an annotation created from the same
+ * selection would carry.
+ *
+ * ONE deliberate deviation: when the selection is not found inside the block
+ * at all — a selection spanning two blocks, where the anchor sits in the
+ * first — `String.split` yields the whole block text and the annotation path
+ * would report `blockText.length`. A host gets 0 instead, since an offset
+ * past the end of the block is worse than an admitted "unknown".
+ */
+export function buildSelectionActionContext(
+  element: HTMLElement,
+  text: string,
+): SelectionActionContext {
+  const blockEl = element.closest<HTMLElement>('[data-block-id]');
+  const blockId = blockEl?.dataset.blockId ?? '';
+  let startOffset = 0;
+  if (blockEl && text) {
+    const blockText = blockEl.textContent || '';
+    const before = blockText.split(text)[0];
+    startOffset = before === blockText ? 0 : before?.length || 0;
+  }
+  return { text, blockId, startOffset, endOffset: startOffset + text.length, element };
+}