@plannotator/ui 0.43.1 → 0.43.2

package/HANDOFF.md

@@ -956,6 +956,8 @@ that state out of `Viewer`, exactly as with `AnnotationToolstrip`'s
 
 ### 3. `CommentPopover` `mentionSource` — an `@` mention source for the composer
 
+> **0.43.2 additions (opt-in, byte-identical when absent):** `MentionSource.heading?: string | null` draws one non-selectable heading row (`data-mention-heading`, e.g. "People in this workspace") above the list; `MentionPerson.avatar?: { url?, initials?, tint? }` draws an avatar (`data-mention-avatar="image" | "initials"`) before the label — an `<img>` when `url` is set, else `initials` (defaulting to the label's first letter) on a disc tinted with `tint` (any CSS color; absent means the muted surface). Neither the grammar, the keyboard state machine, `onMentionsChange`, `onPickBlocked` nor `Annotation.mentions` changes.
+
 ```ts
 import type { MentionPerson, MentionSource } from "@plannotator/ui/types";
 // (also @plannotator/ui/utils/mentions)
@@ -971,6 +973,7 @@ interface MentionPerson {
 interface MentionSource {
   readonly people: readonly MentionPerson[];
   readonly emptyNotice?: string | null;                     // honest-empty row
+  readonly heading?: string | null;                         // 0.43.2: heading row above the list, absent → none
   readonly onMentionsChange?: (ids: readonly string[]) => void;
   readonly onPickBlocked?: (person: MentionPerson) => void;
 }

package/README.md

@@ -245,7 +245,9 @@ in 0.42.0 (proven by diffing the mounted `outerHTML` against the base commit).
 - **`AnnotationToolbar` `quickLabels`** (default `true`): `false` hides the Zap
   picker and makes the Alt+digit label shortcuts inert on that toolbar. The
   one-click 👍 is unaffected, and mode state is still yours to clamp.
-- **`CommentPopover` `mentionSource`**: `{ people, emptyNotice?,
+- **`CommentPopover` `mentionSource`** (0.43.2 adds `heading?` above the list
+  and an optional `avatar?: { url?, initials?, tint? }` per person, drawn before
+  the label; both absent → the 0.43.1 rows): `{ people, emptyNotice?,
   onMentionsChange?, onPickBlocked? }` over `MentionPerson`
   (`{ id, kind, label, detail, canOpen }`). Typing `@` at a word boundary opens
   a portaled picker measured from the textarea; picking inserts the readable

package/components/CommentPopover.tsx

@@ -694,6 +694,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
                 id={mentionListboxId}
                 people={mentionAc.menu.items}
                 emptyNotice={mentionAc.menu.emptyNotice}
+                heading={mentionAc.menu.heading}
                 active={mentionAc.menu.activeIndex}
                 anchor={mentionAc.menu.anchor}
                 onPick={(person) => {
@@ -858,6 +859,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
             id={mentionListboxId}
             people={mentionAc.menu.items}
             emptyNotice={mentionAc.menu.emptyNotice}
+            heading={mentionAc.menu.heading}
             active={mentionAc.menu.activeIndex}
             anchor={mentionAc.menu.anchor}
             onPick={(person) => {

package/components/MentionPicker.tsx

@@ -34,10 +34,45 @@ export function mentionAnchorOf(element: HTMLElement | null): MentionAnchor | nu
   return { top: rect.top, bottom: rect.bottom, left: rect.left, width: rect.width };
 }
 
+/** The optional avatar column: an image, else initials on a tinted disc. */
+function MentionAvatar({
+  avatar,
+  label,
+}: {
+  readonly avatar: NonNullable<MentionPerson['avatar']>;
+  readonly label: string;
+}) {
+  if (avatar.url) {
+    return (
+      <img
+        data-mention-avatar="image"
+        src={avatar.url}
+        alt=""
+        aria-hidden="true"
+        className="h-4 w-4 shrink-0 rounded-full object-cover"
+      />
+    );
+  }
+  const initials = (avatar.initials ?? label.trim().charAt(0)).slice(0, 2).toUpperCase();
+  return (
+    <span
+      data-mention-avatar="initials"
+      aria-hidden="true"
+      style={avatar.tint ? { backgroundColor: avatar.tint } : undefined}
+      className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full text-[8px] font-semibold leading-none ${
+        avatar.tint ? 'text-white' : 'bg-muted text-foreground/80'
+      }`}
+    >
+      {initials}
+    </span>
+  );
+}
+
 export function MentionPicker({
   id,
   people,
   emptyNotice,
+  heading,
   active,
   anchor,
   onPick,
@@ -48,6 +83,8 @@ export function MentionPicker({
   readonly people: readonly MentionPerson[];
   /** Shown as one non-selectable row when `people` is empty. */
   readonly emptyNotice?: string | null;
+  /** Optional heading above the list. Absent → nothing rendered. */
+  readonly heading?: string | null;
   /** Index of the arrow-focused row, or null for "nothing preselected". */
   readonly active: number | null;
   readonly anchor: MentionAnchor | null;
@@ -70,6 +107,11 @@ export function MentionPicker({
       style={{ position: 'fixed', left: anchor.left, width: anchor.width, ...style }}
       className="z-[120] max-h-48 overflow-y-auto rounded-md border border-border bg-popover p-1 shadow-xl"
     >
+      {heading && (
+        <p data-mention-heading className="px-2 pb-1 pt-0.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+          {heading}
+        </p>
+      )}
       {people.length === 0 ? (
         <p data-mention-empty className="px-2 py-1 text-[11px] text-muted-foreground">
           {emptyNotice}
@@ -94,6 +136,7 @@ export function MentionPicker({
               active === index ? 'bg-muted text-foreground' : 'text-foreground/85 hover:bg-muted/60'
             }`}
           >
+            {person.avatar && <MentionAvatar avatar={person.avatar} label={person.label} />}
             <span className="min-w-0 flex-1 truncate">{person.label}</span>
             {person.detail && (
               // The NAME is what the person reads; the detail gives way first.

package/hooks/useMentionAutocomplete.ts

@@ -15,6 +15,7 @@ export interface MentionMenuState {
   items: readonly MentionPerson[];
   /** Shown as one non-selectable row when `items` is empty. */
   emptyNotice: string | null;
+  heading: 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. */
@@ -112,6 +113,7 @@ export function useMentionAutocomplete(options: {
   );
 
   const emptyNotice = source?.emptyNotice ?? null;
+  const heading = source?.heading ?? null;
   const open =
     trigger !== null
     && trigger.from !== dismissedStart
@@ -236,7 +238,7 @@ export function useMentionAutocomplete(options: {
 
   return {
     menu: open && trigger
-      ? { items, emptyNotice, activeIndex: boundedActive, anchor, query: trigger.query }
+      ? { items, emptyNotice, heading, activeIndex: boundedActive, anchor, query: trigger.query }
       : null,
     onKeyDown,
     onSelect: readCaret,

package/package.json

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