@plannotator/ui 0.54.0 → 0.56.0

package/components/chat/index.ts

@@ -0,0 +1,72 @@
+/**
+ * A shared floating chat window: screen code only. The host owns the
+ * conversation, the transport and anything saved.
+ *
+ *   const store = new ChatWindowStore({ initialGeometry, onGeometryChange });
+ *   <div className="relative">
+ *     <ChatFrame store={store} label="Chat" header={...} onClose={...}>
+ *       {() => (
+ *         <>
+ *           <ChatTranscript messages={messages} status={status} agentName="Agent" />
+ *           <ChatComposer value={value} onChange={setValue} onSend={send} />
+ *         </>
+ *       )}
+ *     </ChatFrame>
+ *   </div>
+ *
+ * THEME TOKENS. The classes below are not in `theme.css`, so a host defines
+ * them in its own `@theme`. With none defined a class has no rule and the
+ * property falls through to its default.
+ *
+ *   --color-tertiary               text-tertiary, the ink a step behind muted
+ *   --color-surface-hover          bg-surface-hover, the quiet hover wash
+ *   --color-ring-soft              ring-ring-soft, the focus halo
+ *   --color-border-subtle          border-border-subtle, a blockquote's rule
+ *   --color-soft-quiet-fill        bg-soft-quiet-fill, Stop's resting fill
+ *   --color-soft-quiet-fill-hover  bg-soft-quiet-fill-hover, Stop's hover
+ *   --radius-dialog                rounded-dialog, the window's corner
+ *   --shadow-dialog                shadow-dialog, the window's shadow
+ *   --text-2xs                     text-2xs, the Stopped badge
+ *
+ * Everything else comes from `theme.css`: bg-card, bg-popover,
+ * text-popover-foreground, text-foreground, text-muted-foreground, bg-muted,
+ * text-primary, border-border, border-input, ring-ring.
+ */
+
+export {
+  CHAT_WINDOW_DEFAULT,
+  CHAT_WINDOW_FRAME_MARGIN,
+  CHAT_WINDOW_MIN,
+  ChatWindowStore,
+  type ChatWindowGeometry,
+  type ChatWindowStoreOptions,
+} from './chatWindowStore';
+export {
+  CHAT_LAUNCHER_SELECTOR,
+  ChatFrame,
+  ChatFrameLauncher,
+  useChatFrameFocusReturn,
+  useChatFrameKeys,
+  type ChatFrameLabels,
+  type ChatFrameProps,
+  type ChatFrameRootProps,
+  type ChatFrameState,
+} from './ChatFrame';
+export { CHAT_COMPOSER_FIELD_BOX, ChatComposer, type ChatComposerProps } from './ChatComposer';
+export {
+  ChatMarkdown,
+  ChatMessageView,
+  ChatPendingTurn,
+  ChatTranscript,
+  chatTurnHasOutput,
+  clipAtSentenceBoundary,
+  type ChatMessage,
+  type ChatMessagePart,
+  type ChatMessageRole,
+  type ChatPartContext,
+  type ChatStatus,
+  type ChatTextPart,
+  type ChatTranscriptProps,
+} from './ChatTranscript';
+export { chatMarkdownHtml, personMarkdownHtml } from './chatMarkdown';
+export { FOCUS_RING, floatingDialogChrome } from './chatRecipes';

package/components/diagram/DiagramCanvas.tsx

@@ -247,6 +247,13 @@ export function DiagramCanvas({
       pressRef.current = null;
       return;
     }
+    // A second finger makes it a pinch: neither finger is a tap on a part or
+    // a pan any more, so the press ends here.
+    if (event.pointerType === 'touch' && !event.isPrimary) {
+      if (pressRef.current?.panning) setPanning(false);
+      pressRef.current = null;
+      return;
+    }
     pressRef.current = {
       id: event.pointerId,
       x: event.clientX,

package/components/diagram/DiagramComposer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState, type KeyboardEvent } from 'react';
 import { diagramTargetName, diagramTargetText } from '@plannotator/core/diagram-anchor';
 import { cn } from '../../lib/utils';
 import type { ScreenRect } from '../../utils/diagram-projection';
@@ -30,6 +30,7 @@ export function DiagramComposer({
   draft,
   anchorRect,
   hostWidth,
+  hostHeight = 0,
   sourceDirty,
   submitting,
   error,
@@ -41,6 +42,8 @@ export function DiagramComposer({
   draft: DiagramComposerDraft;
   anchorRect: ScreenRect;
   hostWidth: number;
+  /** The canvas's height, to keep the composer inside it. */
+  hostHeight?: number;
   sourceDirty: boolean;
   submitting: boolean;
   /** The last submit's failure, shown under the textarea. */
@@ -73,6 +76,14 @@ export function DiagramComposer({
   const canWrite = disabledReason === undefined && !unsavedPart;
   const rightFits = anchorRect.left + anchorRect.width + 12 + COMPOSER_WIDTH_PX <= hostWidth;
   const left = rightFits ? anchorRect.left + anchorRect.width + 12 : Math.max(0, anchorRect.left - COMPOSER_WIDTH_PX - 12);
+  // The canvas clips what overflows it: a part near the bottom of a short
+  // canvas (an inline diagram on a phone) lifts the composer until it all shows.
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const [height, setHeight] = useState(0);
+  useLayoutEffect(() => {
+    setHeight(rootRef.current?.offsetHeight ?? 0);
+  });
+  const top = Math.max(0, hostHeight > 0 && height > 0 ? Math.min(anchorRect.top, hostHeight - height) : anchorRect.top);
 
   const canAskAI = onAskAI !== undefined && !asking && !submitting && text.trim() !== '';
   const askAI = async () => {
@@ -113,11 +124,12 @@ export function DiagramComposer({
 
   return (
     <div
+      ref={rootRef}
       data-diagram-composer=""
       role="dialog"
       aria-label={`Comment on ${diagramTargetText(target)}`}
-      className="pointer-events-auto absolute z-10 flex w-72 flex-col gap-1.5 rounded-md border border-border bg-card p-2 shadow-lg"
-      style={{ left, top: Math.max(0, anchorRect.top) }}
+      className="pointer-events-auto absolute z-10 flex w-72 max-w-full flex-col gap-1.5 rounded-md border border-border bg-card p-2 shadow-lg"
+      style={{ left, top }}
       onPointerDown={(event) => event.stopPropagation()}
       onPointerUp={(event) => event.stopPropagation()}
       onKeyDown={(event) => {

package/components/diagram/DiagramViewer.tsx

@@ -265,6 +265,7 @@ export function DiagramViewer({
               draft={commentsState.composer}
               anchorRect={anchorRect}
               hostWidth={handle.hostRef.current?.getBoundingClientRect().width ?? 0}
+              hostHeight={handle.hostRef.current?.getBoundingClientRect().height ?? 0}
               sourceDirty={sourceDirty}
               submitting={commentsState.submitting}
               error={commentsState.submitError}

package/components/docBadgesWidth.ts

@@ -0,0 +1,29 @@
+/** A box's viewport edges, as `getBoundingClientRect()` reports them. */
+export interface BoxEdges {
+  readonly left: number;
+  readonly right: number;
+  readonly top: number;
+  readonly bottom: number;
+}
+
+/** Space kept between the badge cluster and the action cluster. */
+const ACTIONS_GAP = 8;
+
+/**
+ * The widest the legacy (absolutely positioned) badge cluster may grow before
+ * it runs under the document's action cluster, so a long file name truncates
+ * where the buttons start rather than at a fixed width.
+ *
+ * When no actions share the row (there are none, they have not been measured
+ * yet, or the phone layout drops them below the badges), the cluster stops
+ * inside the card instead, keeping the same inset on the right as on the left,
+ * so the name truncates and the open-in button stays on screen. Null leaves
+ * it unbounded while the card has no measured width (hidden, not laid out).
+ */
+export function legacyBadgesMaxWidth(badges: BoxEdges, actions: BoxEdges | null, card: BoxEdges): number | null {
+  const inCard = card.right > card.left ? Math.max(0, card.right - badges.left - (badges.left - card.left)) : null;
+  if (!actions || actions.right <= actions.left) return inCard;
+  const sharesRow = actions.top < badges.bottom && actions.bottom > badges.top;
+  if (!sharesRow) return inCard;
+  return Math.max(0, actions.left - badges.left - ACTIONS_GAP);
+}

package/components/html-viewer/HtmlViewer.tsx

@@ -148,6 +148,20 @@ const MAX_VIM_COPY_TEXT_LENGTH = 2 * 1024 * 1024;
  */
 export const HTML_VIEWER_SANDBOX = "allow-scripts allow-modals";
 
+/**
+ * The srcdoc frame's `sandbox` attribute: the `sandbox` prop's value as given,
+ * plus `allow-popups` when `hostNavigates` needs it and the value lacks it.
+ * Anything that is not a string (`undefined`, and also `null` from a host's
+ * unset config, which a destructuring default does not catch) becomes
+ * `HTML_VIEWER_SANDBOX`, so the frame always carries a sandbox: React would
+ * drop a `null` attribute and run the page unsandboxed.
+ */
+function srcdocSandbox(sandbox: unknown, hostNavigates: boolean): string {
+  const value = typeof sandbox === "string" ? sandbox : HTML_VIEWER_SANDBOX;
+  if (!hostNavigates || value.split(/\s+/).includes("allow-popups")) return value;
+  return value.trim() ? `${value} allow-popups` : "allow-popups";
+}
+
 /** Default wait for the bridge's `ready` on the `bridgeScriptUrl` path. */
 export const DEFAULT_BRIDGE_READY_TIMEOUT_MS = 5000;
 
@@ -373,6 +387,26 @@ export interface HtmlViewerProps {
    * still pins. Absent → unchanged.
    */
   hostNavigates?: boolean;
+  /**
+   * The srcdoc frame's whole `sandbox` attribute value, for a host whose
+   * documents must not open dialogs: `"allow-scripts"` keeps a shared page's
+   * `alert`, `confirm` and `prompt` from drawing over the host's origin. Used
+   * as given, except that `hostNavigates` still adds `allow-popups`, which it
+   * needs. Never add `allow-same-origin` beside `allow-scripts`: the page
+   * could then remove its own sandbox. Live-app (`src`) mode has no sandbox
+   * and ignores this. Absent, or any non-string such as `null` →
+   * `HTML_VIEWER_SANDBOX` (`"allow-scripts allow-modals"`), unchanged.
+   *
+   * `""` (or only spaces) is kept as given: the strictest frame, with no
+   * scripts, so the annotation bridge never starts and the page cannot be
+   * annotated. It never falls back to the wider default.
+   *
+   * Read when the frame loads a document: browsers apply a changed `sandbox`
+   * only on the frame's next navigation (a new `rawHtml`, for example). To
+   * apply a new value to the document already shown, remount the viewer (for
+   * example, key it on the value).
+   */
+  sandbox?: string;
 }
 
 /**
@@ -429,6 +463,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       bridgeErrorDisplay = "banner",
       onHostDraft,
       hostNavigates = false,
+      sandbox = HTML_VIEWER_SANDBOX,
     },
     ref,
   ) => {
@@ -1295,7 +1330,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 same-origin XHR) and no srcdoc. Srcdoc mode is unchanged. */}
             <iframe
               ref={iframeRef}
-              {...(src ? { src } : { srcDoc: srcdoc, sandbox: HTML_VIEWER_SANDBOX + (hostNavigates ? " allow-popups" : "") })}
+              {...(src ? { src } : { srcDoc: srcdoc, sandbox: srcdocSandbox(sandbox, hostNavigates) })}
               style={{
                 width: "100%",
                 height: fullViewport ? "100%" : `${iframeHeight}px`,

package/components/imageZoom.ts

@@ -32,6 +32,16 @@ export interface ZoomInset {
   readonly y: number;
 }
 
+/**
+ * Rows of a stage that things float over: Fit and the pan's limits work in the
+ * stage between them, while a zoomed image still slides under them and every
+ * row of the stage still takes the fingers.
+ */
+export interface ZoomClear {
+  readonly top: number;
+  readonly bottom: number;
+}
+
 /** 800%: an image pixel is then 8 screen pixels, enough to read any screenshot. */
 export const LIGHTBOX_ZOOM_MAX = 8;
 /** Wheel zoom: factor = exp(-deltaY * sensitivity), with deltaY capped so a
@@ -147,6 +157,17 @@ export function atFit(view: ZoomViewport, limits: ZoomLimits | number): boolean
   return Math.abs(view.scale - fit) < 1e-3;
 }
 
+/**
+ * Whether the part of an image on screen (`visibleBox`, its own pixels) can
+ * still pan sideways: `1` shows more of its right (the finger moving left),
+ * `-1` more of its left. A swipe that way pans first, and steps once the
+ * image is at its edge (approval "inbox-image-swipe").
+ */
+export function canPanToward(box: Pick<NaturalBox, 'x' | 'w'> | null, naturalWidth: number, dir: 1 | -1): boolean {
+  if (!box || !(naturalWidth > 0)) return false;
+  return dir > 0 ? box.x + box.w < naturalWidth - 1 : box.x > 1;
+}
+
 /** The share of a stage that leaves `padding` CSS pixels on every side (at least a tenth). */
 export function paddingInset(stage: ZoomSize, padding: number): ZoomInset {
   if (!valid(stage) || padding <= 0) return FULL;

package/components/inbox-thread/FileName.tsx

@@ -0,0 +1,118 @@
+import { useEffect } from 'react';
+import { sliceText } from '@plannotator/core/inbox-questions';
+import { Tip } from './Tip';
+
+/**
+ * A file name that is cut in the middle when it runs short, never at its
+ * end: the end is what tells two files apart (the date, the version, the
+ * extension), so "SPIKE-claude-code-mobile-annotations-20261012.md" reads
+ * "SPIKE-claude-…-20261012.md" in a tile, not "SPIKE-claude-code-mob…".
+ * The same two-part pattern code review's file rows use: the start shrinks
+ * with an ellipsis, the end keeps its width. The full name is the hover
+ * text, and the direction follows the name (`dir="auto"`), so an Arabic name
+ * reads right to left and is cut at its own end.
+ *
+ * `wrap` draws the whole name, broken where it must, for places with room
+ * (the download card). A cut name gets its whole name in a tooltip (Tip)
+ * only while it is cut.
+ */
+export function FileName({ name, className, wrap = false }: { name: string; className?: string; wrap?: boolean }) {
+  useEffect(keepNamesWholeOnCopy, []);
+  const [head, tail] = splitFileName(name);
+  const cls = `ib-fname${wrap ? ' ib-fname-wrap' : ''}${className ? ` ${className}` : ''}`;
+  if (wrap) {
+    return (
+      <span className={cls} dir="auto">
+        <span className="ib-fname-h">{name}</span>
+      </span>
+    );
+  }
+  if (!tail) {
+    return (
+      <Tip content={name} cut>
+        <span className={cls} dir="auto">
+          <span className="ib-fname-h">{name}</span>
+        </span>
+      </Tip>
+    );
+  }
+  // The two parts are flex items, which a screen reader would read apart
+  // ("refund -policy.pdf"): they are hidden from it, and it hears the whole
+  // name from `data-name` (inbox.css draws it as a visually hidden ::after).
+  // The text content stays the name.
+  return (
+    <Tip content={name} cut>
+      <span className={cls} dir="auto" data-name={name}>
+        <span className="ib-fname-h" aria-hidden="true">
+          {head}
+        </span>
+        <span className="ib-fname-t" aria-hidden="true">
+          {tail}
+        </span>
+      </span>
+    </Tip>
+  );
+}
+
+let copyListeners = 0;
+
+/**
+ * The two parts of a cut name are flex items, so a selection's text puts a
+ * line break between them: a copy that takes in a cut name gets the name
+ * whole instead. Installed once while any FileName is on the page.
+ */
+function keepNamesWholeOnCopy(): () => void {
+  if (copyListeners++ === 0) document.addEventListener('copy', onCopy);
+  return () => {
+    if (--copyListeners === 0) document.removeEventListener('copy', onCopy);
+  };
+}
+
+function onCopy(event: ClipboardEvent): void {
+  const selection = document.getSelection();
+  if (!selection || selection.isCollapsed || !event.clipboardData) return;
+  const text = selection.toString();
+  let whole = text;
+  for (const el of document.querySelectorAll<HTMLElement>('.ib-fname[data-name]')) {
+    if (!selection.containsNode(el, true)) continue;
+    const head = el.querySelector('.ib-fname-h')?.textContent ?? '';
+    const tail = el.querySelector('.ib-fname-t')?.textContent ?? '';
+    if (!head || !tail) continue;
+    // A selection across the cut holds the head's last character, the break, then the tail's first, however
+    // much of either part it took.
+    whole = whole.split(`${head.slice(-1)}\n${tail.slice(0, 1)}`).join(`${head.slice(-1)}${tail.slice(0, 1)}`);
+  }
+  if (whole === text) return;
+  event.clipboardData.setData('text/plain', whole);
+  event.preventDefault();
+}
+
+/** Names this short are never cut in the middle: there is nothing to keep apart. */
+const SHORT = 16;
+/** The most of the stem kept with the extension. */
+const TAIL_STEM = 12;
+
+/**
+ * The name split where a middle cut goes: `[start, end]`, the end being the
+ * extension and the last part of the stem (after its last `-`, `_`, `.` or
+ * space when that part is short, else its last few characters), never
+ * splitting a character. `end` is empty for a short name.
+ */
+export function splitFileName(name: string): [string, string] {
+  if (name.length <= SHORT) return [name, ''];
+  const dot = name.lastIndexOf('.');
+  // An extension: a dot that is not the first character, 1 to 8 letters or digits after it.
+  const ext = dot > 0 && /^\.[\p{L}\p{N}]{1,8}$/u.test(name.slice(dot)) ? name.slice(dot) : '';
+  const stem = ext ? name.slice(0, -ext.length) : name;
+  const sep = Math.max(stem.lastIndexOf('-'), stem.lastIndexOf('_'), stem.lastIndexOf(' '), stem.lastIndexOf('.'));
+  let keep: string;
+  if (sep > 0 && stem.length - sep <= TAIL_STEM + 1) keep = stem.slice(sep);
+  else {
+    // The last few characters, never half of one: cut the stem's start whole, keep what is left.
+    const start = sliceText(stem, Math.max(0, stem.length - 6));
+    keep = stem.slice(start.length);
+  }
+  const tail = `${keep}${ext}`;
+  const head = name.slice(0, name.length - tail.length);
+  return head ? [head, tail] : [name, ''];
+}

package/components/inbox-thread/GuideCard.tsx

@@ -0,0 +1,39 @@
+/**
+ * A guided review at the foot of the message that carries it (the record's
+ * 4.1): like any attachment, with its sections, files and line counts, and
+ * Open, which takes the window with Plannotator's guide viewer.
+ */
+
+import type { InboxGuideRef } from '@plannotator/core/inbox-types';
+import { formatCount, plural } from '@plannotator/core/inbox-format';
+import { Icon } from './icons';
+import { Tip } from './Tip';
+
+export function GuideCard({ guide, onOpen }: { guide: InboxGuideRef; onOpen: () => void }) {
+  return (
+    <>
+      <div className="ib-attach-h">
+        <Icon name="clip" size={13} />1 attachment
+      </div>
+      <div className="ib-atts">
+        <button type="button" className="ib-att-t ib-guide" onClick={onOpen} data-guide-card="">
+          <span className="ib-fi">
+            <Icon name="book" size={18} />
+          </span>
+          <span className="ib-att-text">
+            <Tip content={`Guided review: ${guide.title}`} cut>
+              <span className="ib-nm">
+                Guided review: <bdi>{guide.title}</bdi>
+              </span>
+            </Tip>
+            <span className="ib-kd">
+              {plural(guide.sections, 'section')}, {plural(guide.files, 'file')}, <span className="ib-add">+{formatCount(guide.additions)}</span>{' '}
+              <span className="ib-del">-{formatCount(guide.deletions)}</span>
+            </span>
+          </span>
+          <span className="ib-open">Open</span>
+        </button>
+      </div>
+    </>
+  );
+}

package/components/inbox-thread/ReaskNote.tsx

@@ -0,0 +1,25 @@
+import type { InboxMessageWire } from '@plannotator/core/inbox-types';
+import { Icon } from './icons';
+import { reaskNoteSentence } from './reask';
+
+/**
+ * The person's Re-ask note as it reads in the thread (approval "inbox-reask"):
+ * one line, and what the agent was sent behind a disclosure.
+ */
+export function ReaskNote({ message, agent, picks }: { message: InboxMessageWire; agent: string; picks: number }) {
+  const asked = message.reask?.length ?? 0;
+  // Action items it asked about (ids `<message id>/a-…`): the line names them.
+  const actions = (message.reask ?? []).filter((id) => /\/a-[0-9a-f]/.test(id)).length;
+  return (
+    <div className="ib-reask" data-reask-note="">
+      <p className="ib-reask-l">
+        <Icon name="refresh" size={15} />
+        <span>{reaskNoteSentence(agent, asked, picks, actions)}</span>
+      </p>
+      <details className="ib-reask-d">
+        <summary>What {agent} was sent</summary>
+        <pre>{message.body}</pre>
+      </details>
+    </div>
+  );
+}

package/components/inbox-thread/SkillsLine.tsx

@@ -0,0 +1,40 @@
+/**
+ * The quiet skills line under a person's message (approval
+ * "inbox-skills-line", option B, 2026-10-29): the box icon, then the names of
+ * the skills the reply used as a comma list. Nothing to open: no label, no
+ * size, no Show. The block the window pasted at the end of the message is
+ * split off by Thread.tsx's MessageBody; the agent's text is shown whole.
+ * The line sits in the message body, above the Delivered line, so it is in
+ * the same place whatever the state (sent, queued, answered). A long list
+ * wraps between names, never inside one.
+ */
+import type { InboxSkillsSplit } from '@plannotator/core/skill-reference-block';
+
+export function SkillsLine({ split }: { split: InboxSkillsSplit }) {
+  const names = split.skills.map((s) => s.name).join(', ');
+  return (
+    <div className="ib-skills" data-skills-line="" title={`Skills you referenced: ${names}`}>
+      <SkillCube />
+      <span className="ib-sr">Skills: </span>
+      <span className="ib-skills-n">
+        {split.skills.map((s, i) => (
+          <span key={s.name}>
+            <span className="ib-skill-nm" data-skill-name="">{s.name}</span>
+            {i < split.skills.length - 1 ? ', ' : ''}
+          </span>
+        ))}
+      </span>
+    </div>
+  );
+}
+
+/** The cube Plannotator's skill picker shows beside each skill. */
+function SkillCube() {
+  return (
+    <svg className="ib-skills-i" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.7} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
+      <path d="M3.29 7 12 12l8.71-5" />
+      <path d="M12 22V12" />
+    </svg>
+  );
+}

package/components/inbox-thread/Tip.tsx

@@ -0,0 +1,105 @@
+import { useCallback, useState, type ReactElement, type ReactNode } from 'react';
+import { Tooltip, TOOLTIP_DELAY_MS } from '../Tooltip';
+import { isTextCut as isTextCutIn, noHover } from '../../utils/textCut';
+import { tooltipContainerOf } from '../HostTitle';
+
+/**
+ * ui's cut check (a whole pixel, or the text's Range wider than its box). A
+ * FileName (`.ib-fname`) counts as cut when its first part (`.ib-fname-h`) is.
+ */
+export function isTextCut(el: Element | null | undefined): boolean {
+  return isTextCutIn(el, el?.classList.contains('ib-fname') ? '.ib-fname-h' : undefined);
+}
+
+/** How long the pointer rests before a tooltip opens (the list chips' timing). */
+export const TIP_DELAY_MS = TOOLTIP_DELAY_MS;
+
+/**
+ * The Inbox's hover text: ui's Tooltip (the component the list's chips use),
+ * never the browser's native `title`, which waits about a second and cannot
+ * be styled. The host's TooltipProvider sets the timing (the Inbox has one,
+ * in its App.tsx): 150 ms to open, the next one at once within 400 ms.
+ *
+ * `cut`: open only while the trigger's text is actually cut (an ellipsis, a
+ * clamp), so a name that fits gets no tooltip repeating it. Without `cut` it
+ * always opens. `when` decides each time instead, for anything else (a mark
+ * whose label is hidden).
+ *
+ * The trigger keeps its own accessible name (an `aria-label`, or its text):
+ * the tooltip adds nothing a screen reader needs, and a trigger that is not
+ * focusable stays out of the tab order. Nothing opens on a touch screen
+ * (`hover: none`): a hover there is a first tap. The popup is portaled into
+ * the open native `<dialog>` the trigger sits in (so the top layer does not
+ * cover it), else into the window's root (`data-pn-tooltip-root`), so the
+ * Soft switches' tokens reach it. Escape closes an open tooltip and still reaches the window
+ * (`escapePassesThrough`), so Escape closes a thread whatever holds focus.
+ */
+export function Tip({
+  content,
+  children,
+  cut = false,
+  when,
+  side = 'top',
+  align,
+  wide = true,
+  open,
+}: {
+  content: ReactNode;
+  children: ReactElement;
+  cut?: boolean;
+  when?: (trigger: Element) => boolean;
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  align?: 'start' | 'center' | 'end';
+  wide?: boolean;
+  /**
+   * Shown whatever the pointer does while true (the list rows' badges, while
+   * their row has keyboard focus). Unset: hover decides, as for every tip.
+   */
+  open?: boolean;
+}) {
+  const [container, setContainer] = useState<HTMLElement | null>(null);
+  const shouldOpen = useCallback(
+    (trigger: Element) => {
+      if (content === null || content === undefined || content === '') return false;
+      if (noHover()) return false;
+      if (cut && !isTextCut(trigger)) return false;
+      if (when && !when(trigger)) return false;
+      setContainer(tooltipContainerOf(trigger));
+      return true;
+    },
+    [content, cut, when],
+  );
+  // A disabled control gets no pointer events (and React drops mouse events on
+  // it), so its tooltip hangs on a wrapper the pointer reaches instead
+  // (inbox.css: `.ib-tipwrap > :disabled` lets the pointer through). Any
+  // control that can be disabled gets the wrapper, disabled or not, so the
+  // control is never remounted (and never loses focus) when it changes.
+  const canDisable = 'disabled' in (children.props as object);
+  const trigger = canDisable ? (
+    <span className="ib-tipwrap" data-tip-wrap="">
+      {children}
+    </span>
+  ) : (
+    children
+  );
+  return (
+    <Tooltip
+      content={content}
+      side={side}
+      align={align}
+      wide={wide}
+      delayDuration={TIP_DELAY_MS}
+      shouldOpen={shouldOpen}
+      // Opened without a hover, shouldOpen never named the trigger's root: the window's.
+      container={container ?? (open ? windowTooltipRoot() : null)}
+      escapePassesThrough
+      forceOpen={open}
+    >
+      {trigger}
+    </Tooltip>
+  );
+}
+
+function windowTooltipRoot(): HTMLElement | null {
+  return typeof document === 'undefined' ? null : document.querySelector<HTMLElement>('[data-pn-tooltip-root]');
+}