@plannotator/ui 0.52.1 → 0.53.1

package/components/Settings.tsx

@@ -1,3 +1,4 @@
+import type { UpdateCheckSetting } from '../hooks/useUpdateCheckSetting';
 import React, { useState, useEffect, useMemo, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import type { AnnotateAgentTerminalSide } from '@plannotator/core/agent-terminal';
@@ -112,6 +113,10 @@ interface SettingsProps {
    *  `env` is PLANNOTATOR_AUTO_UPDATE when it overrides the config file.
    *  Hosts that omit it get no toggle. */
   autoUpdateSetting?: { env?: boolean };
+  /** Present when the server reports the update-notice switch (serverConfig.updateCheck,
+   *  useUpdateCheckSetting); `env` is PLANNOTATOR_UPDATE_CHECK when it overrides the
+   *  config file. Hosts that omit it get no row. */
+  updateCheckSetting?: UpdateCheckSetting;
   /** The `plannotator` agent tool switch, as the server reports it
    *  (parseAgentToolSetting of serverConfig: present only when the session's
    *  host registers the tool). Shown only together with onAgentToolChange;
@@ -1002,9 +1007,10 @@ const CommentsTab: React.FC = () => {
   );
 };
 
-export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', annotateParity = false, onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, autoUpdateSetting, agentToolSetting, onAgentToolChange, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
+export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', annotateParity = false, onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, autoUpdateSetting, updateCheckSetting, agentToolSetting, onAgentToolChange, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
   const webmcpTools = useWebMcpToolsEnabled();
   const autoUpdate = useConfigValue('autoUpdate');
+  const updateChecksOn = updateCheckSetting ? updateCheckSetting.on : true;
   const [showDialog, setShowDialog] = useState(false);
   const settingsWasOpenRef = useRef(false);
   const [themePreview, setThemePreview] = useState(false);
@@ -1441,20 +1447,42 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                       </div>
                     </div>
 
+                    {/* Update notices: on by default. Writes updateCheck to
+                        ~/.plannotator/config.json; off makes no request to GitHub. */}
+                    {updateCheckSetting && (
+                      <>
+                        <div className="border-t border-border" />
+                        <ToggleSwitch
+                          checked={updateChecksOn}
+                          onChange={(v) => updateCheckSetting.onChange(v)}
+                          disabled={updateCheckSetting.env !== undefined}
+                          label="Tell me when a new version is out"
+                          description={
+                            updateCheckSetting.env !== undefined
+                              ? 'Set by PLANNOTATOR_UPDATE_CHECK in your environment.'
+                              : 'This computer asks GitHub once a day, never your browser. Off makes no request at all.'
+                          }
+                        />
+                      </>
+                    )}
+
                     {/* Auto-update (#1634): opt-in, default off. Writes
-                        autoUpdate to ~/.plannotator/config.json. */}
+                        autoUpdate to ~/.plannotator/config.json. It needs
+                        update checks, so it is locked while they are off. */}
                     {autoUpdateSetting && (
                       <>
                         <div className="border-t border-border" />
                         <ToggleSwitch
-                          checked={autoUpdateSetting.env ?? autoUpdate}
+                          checked={(autoUpdateSetting.env ?? autoUpdate) && updateChecksOn}
                           onChange={(v) => configStore.set('autoUpdate', v)}
-                          disabled={autoUpdateSetting.env !== undefined}
+                          disabled={autoUpdateSetting.env !== undefined || !updateChecksOn}
                           label="Keep Plannotator up to date"
                           description={
                             autoUpdateSetting.env !== undefined
                               ? 'Set by PLANNOTATOR_AUTO_UPDATE in your environment.'
-                              : 'Installs new releases in the background, at most once a day, never while another review is open.'
+                              : !updateChecksOn
+                                ? 'Needs update checks (above).'
+                                : 'Installs new releases in the background, at most once a day, never while another review is open.'
                           }
                         />
                       </>

package/components/SkillReferenceMenu.tsx

@@ -15,6 +15,16 @@ interface SkillReferenceMenuProps {
   /** Explicitly activated row, or null — the menu opens with nothing active. */
   activeIndex: number | null;
   onSelect: (index: number) => void;
+  /**
+   * The box the menu must stay inside, in viewport coordinates, read at each
+   * measure. Default: the viewport. A host whose composer sits in a dialog
+   * with a footer passes the dialog's area above the footer.
+   */
+  boundary?: () => { top: number; bottom: number } | null;
+  /** Which side of the anchor the menu tries first. Default: above. */
+  prefer?: 'above' | 'below';
+  /** Upper bound on the list's height, in px. Default: 256. */
+  maxListHeight?: number;
 }
 
 /** Vertical gap between the composer wrapper and the menu (mb-1.5 / mt-1.5 = 6px). */
@@ -40,24 +50,29 @@ interface MenuPlacement {
  * When neither side fits the whole list, the side with more room wins and the
  * list is clamped to it, so the menu never extends past a viewport edge.
  */
-function computeMenuPlacement(
+export function computeMenuPlacement(
   anchorRect: Pick<DOMRect, 'top' | 'bottom'>,
   naturalListHeight: number,
   chromeHeight: number,
   viewportHeight: number,
+  options: { boundaryTop?: number; prefer?: 'above' | 'below'; maxListHeight?: number } = {},
 ): MenuPlacement {
-  const spaceAbove = anchorRect.top - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
+  const boundaryTop = options.boundaryTop ?? 0;
+  const cap = options.maxListHeight ?? MAX_LIST_HEIGHT;
+  const spaceAbove = anchorRect.top - boundaryTop - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
   const spaceBelow = viewportHeight - anchorRect.bottom - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
-  const needed = Math.min(naturalListHeight, MAX_LIST_HEIGHT);
+  const needed = Math.min(naturalListHeight, cap);
+  const [first, second] = options.prefer === 'below' ? (['below', 'above'] as const) : (['above', 'below'] as const);
+  const space = (side: MenuPlacement['direction']) => (side === 'above' ? spaceAbove : spaceBelow);
   const direction: MenuPlacement['direction'] =
-    needed <= spaceAbove ? 'above'
-    : needed <= spaceBelow ? 'below'
-    : spaceAbove >= spaceBelow ? 'above'
-    : 'below';
-  const available = direction === 'above' ? spaceAbove : spaceBelow;
+    needed <= space(first) ? first
+    : needed <= space(second) ? second
+    : space(first) >= space(second) ? first
+    : second;
+  const available = space(direction);
   return {
     direction,
-    maxListHeight: Math.max(0, Math.min(MAX_LIST_HEIGHT, Math.round(available))),
+    maxListHeight: Math.max(0, Math.min(cap, Math.round(available))),
   };
 }
 
@@ -85,13 +100,19 @@ export const SkillReferenceMenu: React.FC<SkillReferenceMenuProps> = ({
   items,
   activeIndex,
   onSelect,
+  boundary,
+  prefer,
+  maxListHeight,
 }) => {
   const menuRef = useRef<HTMLDivElement>(null);
   const listRef = useRef<HTMLDivElement>(null);
   const [placement, setPlacement] = useState<MenuPlacement>({
-    direction: 'above',
-    maxListHeight: MAX_LIST_HEIGHT,
+    direction: prefer ?? 'above',
+    maxListHeight: maxListHeight ?? MAX_LIST_HEIGHT,
   });
+  // The optional seams, read through a ref so `measure` stays stable for its listeners.
+  const optionsRef = useRef({ boundary, prefer, maxListHeight });
+  optionsRef.current = { boundary, prefer, maxListHeight };
 
   const measure = useCallback(() => {
     const menuEl = menuRef.current;
@@ -106,7 +127,13 @@ export const SkillReferenceMenu: React.FC<SkillReferenceMenuProps> = ({
     // jitter loop this component once shipped.
     const chrome = Math.max(0, menuEl.offsetHeight - listEl.offsetHeight);
     // scrollHeight reports full content height even while clamped.
-    const next = computeMenuPlacement(rect, listEl.scrollHeight, chrome, window.innerHeight);
+    const { boundary: readBoundary, prefer: side, maxListHeight: cap } = optionsRef.current;
+    const box = readBoundary?.() ?? null;
+    const next = computeMenuPlacement(rect, listEl.scrollHeight, chrome, box ? box.bottom : window.innerHeight, {
+      boundaryTop: box ? box.top : 0,
+      prefer: side,
+      maxListHeight: cap,
+    });
     setPlacement((prev) =>
       prev.direction === next.direction && prev.maxListHeight === next.maxListHeight
         ? prev
@@ -182,11 +209,12 @@ export const SkillReferenceMenu: React.FC<SkillReferenceMenuProps> = ({
             }`}
           >
             <SkillIcon />
-            <span className="shrink-0 font-semibold text-foreground">{item.name}</span>
-            <span className="min-w-0 flex-1 truncate text-muted-foreground">
+            {/* data-skill-item-part: a host's styling hook (the Inbox lays a row out in two lines on a phone). */}
+            <span data-skill-item-part="name" className="shrink-0 font-semibold text-foreground">{item.name}</span>
+            <span data-skill-item-part="description" className="min-w-0 flex-1 truncate text-muted-foreground">
               {item.description ?? ''}
             </span>
-            <span className="shrink-0 pl-3 text-xs text-muted-foreground/80">
+            <span data-skill-item-part="root" className="shrink-0 pl-3 text-xs text-muted-foreground/80">
               {ROOT_LABELS[item.root]}
             </span>
           </button>
@@ -215,6 +243,26 @@ const SkillIcon: React.FC = () => (
 
 interface HumanOnlySkillNoticeProps {
   skills: SkillCatalogEntry[];
+  /**
+   * What the instructions go with. Default: the host's (`setSkillInstructionsDestination`),
+   * else "your feedback". The Inbox says "your reply" or "your message".
+   */
+  destination?: string;
+}
+
+// Module-level seam (see packages/ui/CLAUDE.md): what every composer's
+// human-only line says the instructions go with, unless the composer says.
+// Plannotator's comments go with "your feedback"; the Inbox's comments on
+// attached files ride a reply.
+const DEFAULT_DESTINATION = 'your feedback';
+let defaultDestination = DEFAULT_DESTINATION;
+
+export function setSkillInstructionsDestination(destination: string): void {
+  defaultDestination = destination || DEFAULT_DESTINATION;
+}
+
+export function resetSkillInstructionsDestination(): void {
+  defaultDestination = DEFAULT_DESTINATION;
 }
 
 /**
@@ -227,8 +275,9 @@ interface HumanOnlySkillNoticeProps {
  * toggles), and assistive tech alike. It pairs with the dotted-underline
  * marker the composer overlay paints on human-only tokens.
  */
-export const HumanOnlySkillNotice: React.FC<HumanOnlySkillNoticeProps> = ({ skills }) => {
+export const HumanOnlySkillNotice: React.FC<HumanOnlySkillNoticeProps> = ({ skills, destination }) => {
   if (skills.length === 0) return null;
+  destination ??= defaultDestination;
   const names = skills.map((s) => s.name).join(', ');
   return (
     <details data-skill-human-only-notice="true" className="group mt-1 px-1">
@@ -240,12 +289,12 @@ export const HumanOnlySkillNotice: React.FC<HumanOnlySkillNoticeProps> = ({ skil
         {skills.length === 1 ? (
           <>
             <span className="font-mono">{names}</span> cannot be invoked by a model, so
-            its instructions will be included with your feedback.
+            its instructions will be included with {destination}.
           </>
         ) : (
           <>
             <span className="font-mono">{names}</span> cannot be invoked by a model, so
-            their instructions will be included with your feedback.
+            their instructions will be included with {destination}.
           </>
         )}
       </p>

package/components/Tooltip.tsx

@@ -44,6 +44,25 @@ interface TooltipProps {
    * that use it for short button labels.
    */
   wide?: boolean;
+  /**
+   * Asked each time the tooltip would open, with the trigger element; `false`
+   * keeps it closed this time (e.g. open only while the trigger's text is cut
+   * off). Unset: it always opens, as before.
+   */
+  shouldOpen?: (trigger: Element) => boolean;
+  /**
+   * Where the popup is portaled. Unset: the document body. A trigger inside a
+   * native modal `<dialog>` needs the dialog here, or the popup is drawn
+   * under the dialog's top layer.
+   */
+  container?: HTMLElement | null;
+  /**
+   * When true, Escape closes the tooltip without using the key up: it still
+   * reaches the page (not default-prevented, not stopped), so the page's own
+   * Escape (closing a pane) works while a tooltip is open. Unset: Base UI's
+   * default, where the Escape that closes a tooltip goes no further.
+   */
+  escapePassesThrough?: boolean;
 }
 
 export const Tooltip: React.FC<TooltipProps> = ({
@@ -54,15 +73,43 @@ export const Tooltip: React.FC<TooltipProps> = ({
   delayDuration,
   sideOffset = 8,
   wide = false,
+  shouldOpen,
+  container,
+  escapePassesThrough = false,
 }) => {
   const disableHoverablePopup = React.useContext(DisableHoverablePopupContext);
+  // Controlled only for escapePassesThrough: the Escape close is canceled (so Base UI neither prevents nor stops
+  // the key) and the tooltip is closed here instead.
+  const [controlledOpen, setControlledOpen] = React.useState(false);
+  const controlled = escapePassesThrough ? { open: controlledOpen } : {};
   return (
-    <BaseTooltip.Root disableHoverablePopup={disableHoverablePopup}>
+    <BaseTooltip.Root
+      disableHoverablePopup={disableHoverablePopup}
+      {...controlled}
+      onOpenChange={
+        shouldOpen || escapePassesThrough
+          ? (open, details) => {
+              if (open && shouldOpen && !(details.trigger && shouldOpen(details.trigger))) {
+                details.cancel();
+                return;
+              }
+              if (!escapePassesThrough) return;
+              if (!open && details.reason === 'escape-key') {
+                details.cancel();
+                details.allowPropagation();
+              }
+              setControlledOpen(open);
+            }
+          : undefined
+      }
+    >
       <BaseTooltip.Trigger render={children} delay={delayDuration} />
-      <BaseTooltip.Portal>
-        <BaseTooltip.Positioner side={side} align={align} sideOffset={sideOffset} className="isolate z-50">
+      <BaseTooltip.Portal container={container ?? undefined}>
+        {/* Above the annotation toolbar (z-[100]), so a tooltip that flips toward it is never tucked under it. */}
+        <BaseTooltip.Positioner side={side} align={align} sideOffset={sideOffset} className="isolate z-[110]">
           <BaseTooltip.Popup
-            className={`z-50 px-2 py-1 text-xs bg-popover text-popover-foreground border border-border rounded shadow-md origin-[var(--transform-origin)] transition-[opacity,scale] duration-150 ease-out data-[starting-style]:opacity-0 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[ending-style]:scale-95 ${
+            data-pn-tooltip=""
+            className={`z-[110] px-2 py-1 text-xs bg-popover text-popover-foreground border border-border rounded shadow-md origin-[var(--transform-origin)] transition-[opacity,scale] duration-150 ease-out data-[starting-style]:opacity-0 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[ending-style]:scale-95 ${
               wide
                 ? 'max-w-[min(260px,calc(100vw-1rem))] leading-snug whitespace-normal [overflow-wrap:anywhere]'
                 : 'whitespace-nowrap'