@plannotator/ui 0.53.1 → 0.55.0

package/components/TableOfContents.tsx

@@ -22,6 +22,17 @@ interface TableOfContentsProps {
   linkedDocFilepath?: string | null;
   onLinkedDocBack?: () => void;
   backLabel?: string;
+  /**
+   * The element a click scrolls. Default: the `ScrollViewportProvider`
+   * context's viewport (plan review). A host that draws the list outside the
+   * document's scroll area (the Inbox's comments column) names it here.
+   */
+  scrollViewport?: HTMLElement | null;
+  /**
+   * The deepest heading level listed. Default 3 (plan review's list); the
+   * contents rail's surface (`DocumentContents`) lists 1 to 4, as the rail does.
+   */
+  maxLevel?: number;
 }
 
 // The prototype's TOC is a FLAT list — heading depth is conveyed by indentation
@@ -43,7 +54,7 @@ function flattenToc(items: TocItem[]): TocItem[] {
 // H1 flush + near-full strength, H2/H3 indented and dimmed to muted. Active row
 // is a soft neutral surface tint (not a loud primary fill).
 function itemClasses(level: number, isActive: boolean): string {
-  const indent = level <= 1 ? '' : level === 2 ? 'ml-3' : 'ml-6';
+  const indent = level <= 1 ? '' : level === 2 ? 'ml-3' : level === 3 ? 'ml-6' : 'ml-9';
   const tone = isActive
     ? 'bg-surface-1 text-foreground'
     : level <= 1
@@ -62,6 +73,8 @@ export function TableOfContents({
   linkedDocFilepath,
   onLinkedDocBack,
   backLabel,
+  scrollViewport: scrollViewportProp,
+  maxLevel = 3,
 }: TableOfContentsProps) {
   // Annotation count per section (kept — production feature).
   const annotationCounts = useMemo(
@@ -69,15 +82,16 @@ export function TableOfContents({
     [blocks, annotations]
   );
 
-  // Build the hierarchy (filters to heading levels ≤ 3 and attaches counts),
-  // then flatten to a plain list.
+  // Build the hierarchy (filters to heading levels ≤ maxLevel and attaches
+  // counts), then flatten to a plain list.
   const tocItems = useMemo(
-    () => flattenToc(buildTocHierarchy(blocks, annotationCounts)),
-    [blocks, annotationCounts]
+    () => flattenToc(buildTocHierarchy(blocks, annotationCounts, maxLevel)),
+    [blocks, annotationCounts, maxLevel]
   );
 
   // The real scroll element is the OverlayScrollArea viewport, not <main>.
-  const scrollViewport = useScrollViewport();
+  const contextViewport = useScrollViewport();
+  const scrollViewport = scrollViewportProp === undefined ? contextViewport : scrollViewportProp;
 
   // Smooth scroll-to-heading, accounting for the sticky header.
   const handleNavigate = useCallback(

package/components/TerminalToolsAnnouncementDialog.tsx

@@ -231,7 +231,7 @@ function DemoPlayer({ demo, reducedMotion }: DemoPlayerProps) {
           data-terminal-tools-playback={playing ? 'pause' : 'play'}
           className={
             playing
-              ? 'absolute bottom-3 left-3 grid size-9 place-items-center rounded-full border border-border/60 bg-background/70 text-foreground opacity-0 outline-none backdrop-blur-sm transition-opacity motion-reduce:transition-none group-hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-primary'
+              ? 'absolute bottom-3 left-3 grid size-9 place-items-center rounded-full border border-border/60 bg-background/70 text-foreground opacity-0 outline-none backdrop-blur-sm transition-opacity motion-reduce:transition-none group-hover:opacity-100 focus-visible:opacity-100 [@media(hover:none)]:opacity-100 focus-visible:ring-2 focus-visible:ring-primary'
               : 'absolute left-1/2 top-1/2 grid size-16 -translate-x-1/2 -translate-y-1/2 place-items-center rounded-full border border-border/60 bg-background/80 text-foreground shadow-lg outline-none backdrop-blur-sm transition-transform motion-reduce:transition-none hover:scale-105 focus-visible:ring-2 focus-visible:ring-primary'
           }
         >

package/components/ThemeProvider.tsx

@@ -18,6 +18,7 @@ import {
 } from '../utils/themeRegistry';
 import type { Mode } from './themeModes';
 import { usePrintMedia } from '../hooks/usePrintMedia';
+import { markRootPlatform } from '../utils/platform';
 
 // Kept here because published consumers already import Mode from ThemeProvider.
 export type { Mode } from './themeModes';
@@ -62,12 +63,22 @@ const ThemeProviderContext = createContext<ThemeProviderState>({
   manageFavicon: false,
 });
 
-/** Sync theme classes on <html> without stripping non-theme classes (e.g. transitions-ready). */
+/**
+ * Sync theme classes on <html> without stripping non-theme classes (e.g. transitions-ready).
+ *
+ * A page that sets an inline `color-scheme` on <html> before its scripts run
+ * (Plannotator's packed pages do, so the empty page does not paint white under
+ * a dark theme) hands it over here: from the first render it follows the mode
+ * on screen, so it never goes stale after a theme switch. A host page that sets
+ * none keeps none.
+ */
 function applyThemeClasses(themeId: string, resolvedMode: 'dark' | 'light'): void {
   const el = document.documentElement;
   const themeClass = `theme-${themeId}`;
   const wantLight = resolvedMode === 'light';
 
+  if (el.style.colorScheme && el.style.colorScheme !== resolvedMode) el.style.colorScheme = resolvedMode;
+
   if (el.classList.contains(themeClass) && el.classList.contains('light') === wantLight) return;
 
   for (const cls of Array.from(el.classList)) {
@@ -223,6 +234,8 @@ export function ThemeProvider({
   // without this the first frame has no valid --background/--foreground.
   if (typeof window !== 'undefined') {
     applyThemeClasses(colorTheme, resolvedMode);
+    // theme.css scopes the Linux-only font-feature rule to this class (#1961).
+    markRootPlatform();
   }
 
   // Keep class in sync after state changes

package/components/ThemeTab.tsx

@@ -1,7 +1,8 @@
-import React, { useEffect, useState } from 'react';
+import React from 'react';
 import { useTheme } from './ThemeProvider';
 import { THEME_MODES } from './themeModes';
-import { themesForHalf, type ThemeHalf } from '../utils/themeRegistry';
+import type { ThemeHalf, ThemeInfo } from '../utils/themeRegistry';
+import { useThemePaletteHalves } from '../hooks/useThemePaletteHalves';
 import { configStore } from '../config/configStore';
 import { useConfigValue } from '../config/useConfig';
 import { faviconDataUrl, type FaviconStyle } from '@plannotator/core/favicon';
@@ -56,27 +57,19 @@ const FaviconStyleControl: React.FC<{ selected: FaviconStyle }> = ({ selected })
   </div>
 );
 
-export const ThemeTab: React.FC<ThemeTabProps> = ({ onPreview, compact }) => {
-  const {
-    mode,
-    setMode,
-    lightTheme,
-    darkTheme,
-    setHalfTheme,
-    availableThemes,
-    preferredMode,
-    manageFavicon,
-  } = useTheme();
-  const faviconStyle = useConfigValue('faviconStyle');
+// The picker's state lives in hooks/useThemePaletteHalves; re-exported here so existing imports keep working.
+export { useThemePaletteHalves, type ThemePaletteHalves } from '../hooks/useThemePaletteHalves';
 
-  // Which half the grid assigns to. Follows the mode you are actually seeing,
-  // so opening Settings in dark mode edits the dark half first.
-  const [half, setHalf] = useState<ThemeHalf>(preferredMode);
-  useEffect(() => setHalf(preferredMode), [preferredMode]);
+/** The five colors a palette tile shows for one half, in ThemeTab's order. */
+export function paletteSwatchColors(theme: ThemeInfo, half: ThemeHalf): string[] {
+  const colors = theme.colors[half];
+  return [colors.primary, colors.secondary, colors.accent, colors.background, colors.foreground];
+}
 
-  const pair: Record<ThemeHalf, string> = { light: lightTheme, dark: darkTheme };
-  const themes = themesForHalf(availableThemes, half);
-  const nameOf = (id: string) => availableThemes.find(theme => theme.id === id)?.name ?? id;
+export const ThemeTab: React.FC<ThemeTabProps> = ({ onPreview, compact }) => {
+  const { mode, setMode, manageFavicon } = useTheme();
+  const faviconStyle = useConfigValue('faviconStyle');
+  const { half, setHalf, pair, themes, nameOf, choose } = useThemePaletteHalves();
 
   const summary = (
     <div className={`flex items-center gap-1.5 text-[11px] text-muted-foreground ${compact ? '' : 'flex-wrap'}`}>
@@ -190,11 +183,10 @@ export const ThemeTab: React.FC<ThemeTabProps> = ({ onPreview, compact }) => {
         <div className={`grid gap-2 overflow-y-auto pr-1 ${compact ? 'grid-cols-4' : 'grid-cols-3'}`}>
           {themes.map(theme => {
             const isSelected = pair[half] === theme.id;
-            const colors = theme.colors[half];
             return (
               <button
                 key={theme.id}
-                onClick={() => setHalfTheme(half, theme.id)}
+                onClick={() => choose(half, theme.id)}
                 className={`relative p-2 rounded-md border text-left transition-colors ${
                   isSelected
                     ? 'border-primary bg-primary/5'
@@ -209,7 +201,7 @@ export const ThemeTab: React.FC<ThemeTabProps> = ({ onPreview, compact }) => {
                 )}
                 {/* Color swatches */}
                 <div className="flex gap-1 mb-1.5">
-                  {[colors.primary, colors.secondary, colors.accent, colors.background, colors.foreground].map((color, i) => (
+                  {paletteSwatchColors(theme, half).map((color, i) => (
                     <div
                       key={i}
                       className="w-3 h-3 rounded-full border border-border/50"

package/components/Tooltip.tsx

@@ -1,6 +1,22 @@
 import React from 'react';
 import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip';
 
+/**
+ * One tooltip timing for every surface (owner's design-system ruling q4): open
+ * after 150 ms of rest, and open the next one at once for 400 ms after one
+ * closes. A host's own `TooltipProvider` props, or a trigger's
+ * `delayDuration`, still win.
+ */
+export const TOOLTIP_DELAY_MS = 150;
+export const TOOLTIP_SKIP_DELAY_MS = 400;
+
+interface TooltipProviderContextValue {
+  disableHoverablePopup: boolean;
+}
+
+/** Null outside a `TooltipProvider`: a lone Tooltip then sets its own 150 ms (Base UI's own default is 600). */
+const TooltipProviderContext = React.createContext<TooltipProviderContextValue | null>(null);
+
 /**
  * TooltipProvider keeps the Radix-era prop names (`delayDuration`,
  * `skipDelayDuration`, `disableHoverableContent`) as its public API and maps
@@ -9,8 +25,6 @@ import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip';
  * in Base UI (it moved to per-root `disableHoverablePopup`), so it is carried
  * via context and applied to every Tooltip root under the provider.
  */
-const DisableHoverablePopupContext = React.createContext(false);
-
 interface TooltipProviderProps {
   delayDuration?: number;
   skipDelayDuration?: number;
@@ -23,13 +37,15 @@ export const TooltipProvider: React.FC<TooltipProviderProps> = ({
   skipDelayDuration,
   disableHoverableContent = false,
   children,
-}) => (
-  <BaseTooltip.Provider delay={delayDuration} timeout={skipDelayDuration}>
-    <DisableHoverablePopupContext.Provider value={disableHoverableContent}>
-      {children}
-    </DisableHoverablePopupContext.Provider>
-  </BaseTooltip.Provider>
-);
+}) => {
+  // One object per setting, so tooltips behind a memo boundary don't re-render with the provider.
+  const value = React.useMemo(() => ({ disableHoverablePopup: disableHoverableContent }), [disableHoverableContent]);
+  return (
+    <BaseTooltip.Provider delay={delayDuration ?? TOOLTIP_DELAY_MS} timeout={skipDelayDuration ?? TOOLTIP_SKIP_DELAY_MS}>
+      <TooltipProviderContext.Provider value={value}>{children}</TooltipProviderContext.Provider>
+    </BaseTooltip.Provider>
+  );
+};
 
 interface TooltipProps {
   content: React.ReactNode;
@@ -63,6 +79,13 @@ interface TooltipProps {
    * default, where the Escape that closes a tooltip goes no further.
    */
   escapePassesThrough?: boolean;
+  /**
+   * When true, the tooltip is shown whatever the pointer does: a host shows
+   * it while the element that holds the trigger has keyboard focus (the
+   * Inbox's row badges). False or unset: hover and focus on the trigger decide,
+   * as before.
+   */
+  forceOpen?: boolean;
 }
 
 export const Tooltip: React.FC<TooltipProps> = ({
@@ -76,25 +99,30 @@ export const Tooltip: React.FC<TooltipProps> = ({
   shouldOpen,
   container,
   escapePassesThrough = false,
+  forceOpen,
 }) => {
-  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 provider = React.useContext(TooltipProviderContext);
+  const disableHoverablePopup = provider?.disableHoverablePopup ?? false;
+  // Under a provider, an unset delay takes the provider's; alone, the shared default.
+  const triggerDelay = delayDuration ?? (provider ? undefined : TOOLTIP_DELAY_MS);
+  // Controlled for escapePassesThrough (the Escape close is canceled, so Base UI neither prevents nor stops the
+  // key, and the tooltip is closed here instead) and for forceOpen (shown on top of what hover decides).
   const [controlledOpen, setControlledOpen] = React.useState(false);
-  const controlled = escapePassesThrough ? { open: controlledOpen } : {};
+  const controlledMode = escapePassesThrough || forceOpen !== undefined;
+  const controlled = controlledMode ? { open: controlledOpen || forceOpen === true } : {};
   return (
     <BaseTooltip.Root
       disableHoverablePopup={disableHoverablePopup}
       {...controlled}
       onOpenChange={
-        shouldOpen || escapePassesThrough
+        shouldOpen || controlledMode
           ? (open, details) => {
               if (open && shouldOpen && !(details.trigger && shouldOpen(details.trigger))) {
                 details.cancel();
                 return;
               }
-              if (!escapePassesThrough) return;
-              if (!open && details.reason === 'escape-key') {
+              if (!controlledMode) return;
+              if (escapePassesThrough && !open && details.reason === 'escape-key') {
                 details.cancel();
                 details.allowPropagation();
               }
@@ -103,13 +131,16 @@ export const Tooltip: React.FC<TooltipProps> = ({
           : undefined
       }
     >
-      <BaseTooltip.Trigger render={children} delay={delayDuration} />
+      <BaseTooltip.Trigger render={children} delay={triggerDelay} />
       <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]">
+          {/* A borderless float (owner's design-system ruling q4): the shadow (--float-shadow, theme.css) separates
+              it from the page. The 1px border stays, transparent, so forced colors (Windows High Contrast), which
+              drop shadows and paint borders in the system colour, still draw its edge. */}
           <BaseTooltip.Popup
             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 ${
+            className={`z-[110] px-2 py-1 text-xs bg-popover text-popover-foreground border border-transparent rounded shadow-[var(--float-shadow)] 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'