@plannotator/ui 0.41.2 → 0.43.0

package/types.ts

@@ -1,6 +1,16 @@
 import type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+import type { DiagramRenderKind } from '@plannotator/core/annotatable';
 
 export type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+export type { DiagramRenderKind } from '@plannotator/core/annotatable';
+
+/**
+ * How a document's body is rendered. `markdown` and `html` are the original
+ * pair; the two diagram kinds are whole-file diagram sources (.mmd/.mermaid,
+ * .dot/.gv) that render as ONE diagram through the same engine a ```mermaid
+ * fence uses — see diagramDocumentBlocks in utils/parser.
+ */
+export type DocumentRenderAs = 'markdown' | 'html' | DiagramRenderKind;
 
 export enum AnnotationType {
   DELETION = 'DELETION',
@@ -192,6 +202,16 @@ export interface Block {
   order: number; // Sorting order
   startLine: number; // 1-based line number in source
   sourceLineCount?: number; // Number of source lines consumed when it differs from content lines
+  /**
+   * Line offset a diagram comment's `sourceLine` is measured from, when it
+   * differs from `startLine`. A ```mermaid fence in a document has its opening
+   * line ABOVE the diagram's first line, so `startLine` is the right offset
+   * there and this stays unset. A whole-file diagram source (.mmd/.dot) has no
+   * fence: its first line IS document line 1, so it sets 0 here while
+   * `startLine` keeps naming the block's own first line for the export's
+   * `(lines a–b)` label.
+   */
+  diagramSourceLineOffset?: number;
 }
 
 export interface DiffResult {
@@ -430,3 +450,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/parser.ts

@@ -541,6 +541,39 @@ export const resolveReferenceLinks = (markdown: string): string => {
     .join('\n');
 };
 
+/**
+ * The block list for a whole-file diagram source (`plannotator annotate
+ * flow.mmd`): ONE code block carrying the file's raw text, which `Viewer`
+ * hands to the same `DiagramBlock` a ```mermaid fence in a plan produces.
+ * Everything downstream — diagram comments, the annotations rail, the export's
+ * `Diagram node <label> (<id>), line <n>` location line, drafts, restore — is
+ * the fence path unchanged.
+ *
+ * `diagramSourceLineOffset: 0` is the load-bearing part. `DiagramBlock` passes
+ * it as the viewer's `sourceLineOffset` and the codec adds it to the 1-based
+ * line WITHIN the diagram source; for a fence that offset is the fence's own
+ * opening line, which sits one line above the diagram's first line. A diagram
+ * FILE has no fence, so its first line is document line 1 and the offset is 0
+ * — the 1 a synthesized ```mermaid wrapper would produce puts every exported
+ * diagram line one too high. `startLine`/`sourceLineCount` still describe the
+ * block itself, so the export's `(lines a–b)` label names the file's real
+ * span.
+ */
+export const diagramDocumentBlocks = (text: string, kind: 'mermaid' | 'graphviz'): Block[] => [
+  {
+    id: 'block-0',
+    type: 'code',
+    content: text,
+    // `dot` is what isGraphvizLanguage reads for the Graphviz engine.
+    language: kind === 'graphviz' ? 'dot' : 'mermaid',
+    order: 1,
+    startLine: 1,
+    // A trailing newline ends the last line, it does not start another.
+    sourceLineCount: text === '' ? 0 : text.replace(/\n$/, '').split('\n').length,
+    diagramSourceLineOffset: 0,
+  },
+];
+
 /**
  * A simplified markdown parser that splits content into linear blocks.
  * For a production app, we would use a robust AST walker (remark),

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 };
+}

package/utils/sharing.ts

@@ -8,7 +8,8 @@
  * Inspired by textarea.my's approach.
  */
 
-import { AnnotationType, type Annotation, type ImageAttachment } from '../types';
+import { AnnotationType, type Annotation, type DocumentRenderAs, type ImageAttachment } from '../types';
+import { isDiagramRenderKind } from '@plannotator/core/annotatable';
 import { compress, decompress } from '@plannotator/core/compress';
 import { encrypt, decrypt } from '@plannotator/core/crypto';
 
@@ -31,6 +32,32 @@ export interface SharePayload {
   r?: 'html';  // render mode flag (omitted = markdown)
 }
 
+/**
+ * The markdown a document ships as in a share payload's `p`.
+ *
+ * A whole-file diagram source (.mmd/.dot) has no fence of its own — the
+ * annotate session renders it as one diagram because the SERVER said so in
+ * `renderAs`, and a share link carries no server. So it travels as the fenced
+ * form, which the portal's ordinary markdown parse turns back into the same
+ * diagram block. This is deliberately smaller than adding a render-mode flag
+ * (`r: 'html'`'s sibling): the portal needs no change at all.
+ *
+ * Diagram comments themselves still degrade to text comments in a share link,
+ * exactly as they do today — `diagramAnchor` is dropped like `htmlAnchor`
+ * (see sharing.multiTarget.test.ts).
+ */
+export function shareableDocumentMarkdown(
+  markdown: string,
+  renderAs: DocumentRenderAs | undefined,
+): string {
+  if (!isDiagramRenderKind(renderAs) || markdown === '') return markdown;
+  const language = renderAs === 'graphviz' ? 'dot' : 'mermaid';
+  // A diagram source can itself contain a ``` run only in a comment/label;
+  // a four-backtick fence keeps such a body intact.
+  const fence = markdown.includes('```') ? '````' : '```';
+  return `${fence}${language}\n${markdown.replace(/\n+$/, '')}\n${fence}`;
+}
+
 /**
  * Convert ShareableImage[] to ImageAttachment[] (handles old plain-string format)
  */