@plannotator/ui 0.24.0 → 0.26.0

package/README.md

@@ -30,6 +30,21 @@ configurePlannotatorUI({
 
 Anything you don't pass keeps Plannotator's default. A few component-specific overrides (e.g. an "open in editor" diff action) are passed as props where you render that component.
 
+### Resize-handle seams (`ResizeHandle` / `useResizablePanel`)
+
+The sidebar/panel resize handle exposes seams for hosts that want different edge interactions (e.g. no hover reveal, click-to-collapse). All default to today's behavior — pass nothing and it's unchanged.
+
+- **Suppress / restyle the hover reveal.** The inner visible track carries a `[data-resize-track]` attribute (same host-CSS pattern as the collapse button's `[data-collapse]`), and `ResizeHandle` takes a `trackClassName` prop. To kill the pop-in from host CSS:
+  ```css
+  [data-resize-track] { background: none !important; }
+  ```
+- **Click-to-collapse anywhere on the handle.** The handle can't tell a click from a drag-start on its own — the hook owns the pointer state machine. Pass `onClick` to `useResizablePanel`; it fires on pointer-up only when the pointer never traveled past `clickThreshold` (default 4px), so a genuine click on the full-width handle can collapse the panel while drags still resize:
+  ```ts
+  const resize = useResizablePanel({ storageKey, side: "left", onSnapClose: collapse, onClick: collapse });
+  ```
+
+Building your own tooltip and removing the built-in double-click reset are host-side concerns (override `onDoubleClick` where you render the handle).
+
 ## Consuming it (e.g. from Workspaces)
 
 ```bash

package/components/ResizeHandle.tsx

@@ -1,8 +1,22 @@
 import React from 'react';
+import { createPortal } from 'react-dom';
 import type { ResizeHandleProps as BaseProps } from '../hooks/useResizablePanel';
 
 interface Props extends BaseProps {
   className?: string;
+  /**
+   * Extra classes for the inner visible track (the 4px bar that reveals on
+   * hover). `className` only reaches the outer wrapper, so this is the seam for
+   * restyling or suppressing the hover affordance. The track also carries a
+   * `[data-resize-track]` attribute (same pattern as `[data-collapse]`) so a
+   * host can target it from plain CSS — e.g. to kill the hover reveal:
+   * `[data-resize-track] { background: none !important; }`.
+   */
+  trackClassName?: string;
+  /** Suppress the hover color-change on the track entirely (no pop-in). */
+  hideHoverTrack?: boolean;
+  /** Cursor-following hint shown while hovering the handle (hidden mid-drag). */
+  tooltip?: React.ReactNode;
   /** When provided, renders a hover-reveal collapse button centered on the
    *  handle (prototype's gutter affordance). Chevron direction follows `side`:
    *  a left sidebar collapses leftward, a right sidebar rightward. */
@@ -34,53 +48,78 @@ export const ResizeHandle: React.FC<Props> = ({
   onDoubleClick,
   style,
   className,
+  trackClassName,
+  hideHoverTrack,
+  tooltip,
   side,
   onCollapse,
-}) => (
-  <div
-    className={`relative w-0 cursor-col-resize flex-shrink-0 group${className ? ` ${className}` : ''}`}
-  >
-    {/* Visible track — 4px wide, centered on the zero-width layout box,
-        invisible until hover/drag. */}
-    <div className={`absolute inset-y-0 -left-0.5 -right-0.5 transition-colors ${
-      isDragging ? 'bg-transparent' : 'group-hover:bg-border'
-    }`} />
-    {/* Wider grab/touch zone — must never have zero width (see `side` docs).
-        Pointer events + setPointerCapture live here; touch-action:none (from
-        style) stops touch drags from scroll-hijacking. */}
+}) => {
+  const [tip, setTip] = React.useState<{ x: number; y: number } | null>(null);
+  const showTip = tooltip != null && tip != null && !isDragging;
+
+  return (
     <div
-      className={`absolute inset-y-0 ${
-        side === 'left' ? '-right-2 -left-1' :
-        side === 'right' ? '-right-3 left-0' :
-        '-inset-x-2'
-      }`}
-      style={style}
-      onPointerDown={onPointerDown}
-      onDoubleClick={onDoubleClick}
-    />
-    {/* Hover-reveal collapse button, centered on the handle. stopPropagation on
-        pointerdown so clicking it never starts a drag. Hidden mid-drag. */}
-    {onCollapse && !isDragging && (
-      <button
-        type="button"
-        onPointerDown={(e) => e.stopPropagation()}
-        onClick={(e) => {
-          e.stopPropagation();
-          onCollapse();
-        }}
-        title="Collapse sidebar"
-        aria-label="Collapse sidebar"
-        data-collapse={side}
-        className="absolute top-1/2 left-1/2 z-20 flex h-6 w-4 -translate-x-1/2 -translate-y-1/2 items-center justify-center before:absolute before:-inset-2 before:content-[''] rounded-sm bg-surface-1 text-muted-foreground/60 opacity-0 ring-1 ring-border/40 transition-opacity hover:text-foreground group-hover:opacity-100 group-hover/sidebar:opacity-100"
-      >
-        <svg className="size-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            d={side === 'right' ? 'M9 5l7 7-7 7' : 'M15 19l-7-7 7-7'}
-          />
-        </svg>
-      </button>
-    )}
-  </div>
-);
+      className={`relative w-0 cursor-col-resize flex-shrink-0 group${className ? ` ${className}` : ''}`}
+    >
+      {/* Visible track — 4px wide, centered on the zero-width layout box,
+          invisible until hover/drag. `data-resize-track` + `trackClassName` are
+          host seams for restyling/suppressing the hover reveal. */}
+      <div
+        data-resize-track={side ?? ''}
+        className={`absolute inset-y-0 -left-0.5 -right-0.5 transition-colors ${
+          isDragging || hideHoverTrack ? 'bg-transparent' : 'group-hover:bg-border'
+        }${trackClassName ? ` ${trackClassName}` : ''}`}
+      />
+      {/* Wider grab/touch zone — must never have zero width (see `side` docs).
+          Pointer events + setPointerCapture live here; touch-action:none (from
+          style) stops touch drags from scroll-hijacking. */}
+      <div
+        className={`absolute inset-y-0 ${
+          side === 'left' ? '-right-2 -left-1' :
+          side === 'right' ? '-right-3 left-0' :
+          '-inset-x-2'
+        }`}
+        style={style}
+        onPointerDown={onPointerDown}
+        onDoubleClick={onDoubleClick}
+        onPointerMove={tooltip != null && !isDragging ? (e) => setTip({ x: e.clientX, y: e.clientY }) : undefined}
+        onPointerLeave={tooltip != null ? () => setTip(null) : undefined}
+      />
+      {/* Cursor-following hint. pointer-events-none so it never blocks the drag;
+          portaled to body so the zero-width parent doesn't clip it. */}
+      {showTip && typeof document !== 'undefined' && createPortal(
+        <div
+          style={{ position: 'fixed', left: tip.x + 14, top: tip.y + 16, zIndex: 100 }}
+          className="pointer-events-none whitespace-nowrap rounded-md bg-surface-1 px-2 py-1 text-xs text-foreground shadow-md ring-1 ring-border/60"
+        >
+          {tooltip}
+        </div>,
+        document.body,
+      )}
+      {/* Hover-reveal collapse button, centered on the handle. stopPropagation on
+          pointerdown so clicking it never starts a drag. Hidden mid-drag. */}
+      {onCollapse && !isDragging && (
+        <button
+          type="button"
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={(e) => {
+            e.stopPropagation();
+            onCollapse();
+          }}
+          title="Collapse sidebar"
+          aria-label="Collapse sidebar"
+          data-collapse={side}
+          className="absolute top-1/2 left-1/2 z-20 flex h-6 w-4 -translate-x-1/2 -translate-y-1/2 items-center justify-center before:absolute before:-inset-2 before:content-[''] rounded-sm bg-surface-1 text-muted-foreground/60 opacity-0 ring-1 ring-border/40 transition-opacity hover:text-foreground group-hover:opacity-100 group-hover/sidebar:opacity-100"
+        >
+          <svg className="size-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d={side === 'right' ? 'M9 5l7 7-7 7' : 'M15 19l-7-7 7-7'}
+            />
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+};

package/components/html-viewer/HtmlViewer.tsx

@@ -17,39 +17,16 @@ import { CommentPopover, type CommentAskAIHandler } from "../CommentPopover";
 import { FloatingQuickLabelPicker } from "../FloatingQuickLabelPicker";
 import type { ViewerHandle } from "../Viewer";
 import { useHtmlAnnotation } from "./useHtmlAnnotation";
-import { ANNOTATION_HIGHLIGHT_CSS, BRIDGE_SCRIPT } from "./bridge-script";
+import {
+  THEME_TOKENS,
+  buildSrcdocInjection,
+  buildThemeTokenPayload,
+  hasHostThemeOptIn,
+  injectIntoHead,
+} from "./srcdoc";
 
 const PREFIX = "plannotator-bridge-";
 
-const THEME_TOKENS = [
-  "--background",
-  "--foreground",
-  "--card",
-  "--card-foreground",
-  "--primary",
-  "--primary-foreground",
-  "--secondary",
-  "--secondary-foreground",
-  "--muted",
-  "--muted-foreground",
-  "--accent",
-  "--accent-foreground",
-  "--destructive",
-  "--destructive-foreground",
-  "--success",
-  "--success-foreground",
-  "--warning",
-  "--warning-foreground",
-  "--border",
-  "--input",
-  "--ring",
-  "--code-bg",
-  "--focus-highlight",
-  "--font-sans",
-  "--font-mono",
-  "--radius",
-] as const;
-
 function readThemeTokens(): Record<string, string> {
   const style = getComputedStyle(document.documentElement);
   const tokens: Record<string, string> = {};
@@ -124,26 +101,19 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       contextText: string;
     } | null>(null);
 
-    const srcdoc = useMemo(() => {
-      const tokens = readThemeTokens();
-      let themeCSS = ":root {\n";
-      for (const [key, val] of Object.entries(tokens)) {
-        themeCSS += `  ${key}: ${val};\n`;
-      }
-      themeCSS += "}\n";
-      if (isLightTheme()) themeCSS += ":root { color-scheme: light; }\n:root.light, :root { }\n";
+    // Host theming is opt-in per document (Plannotator-generated artifacts tag
+    // themselves); arbitrary HTML renders untouched, like a standalone tab.
+    const hostTheme = useMemo(() => hasHostThemeOptIn(rawHtml), [rawHtml]);
 
-      // Version-diff highlights: htmlDiff wraps changed text in <ins>/<del>.
-      const diffCSS =
-        "ins{background:#e6ffec;color:#0a7d33;text-decoration:none;border-radius:2px;box-shadow:0 0 0 1px #abf2bc inset}" +
-        "del{background:#ffebe9;color:#b31d28;text-decoration:line-through;border-radius:2px;box-shadow:0 0 0 1px #ffc1bc inset}";
-      const injection = `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style><script>${BRIDGE_SCRIPT}</script>`;
-      const headClose = rawHtml.indexOf("</head>");
-      if (headClose !== -1) {
-        return rawHtml.slice(0, headClose) + injection + rawHtml.slice(headClose);
-      }
-      return injection + rawHtml;
-    }, [rawHtml]);
+    const srcdoc = useMemo(() => {
+      const injection = buildSrcdocInjection({
+        tokens: readThemeTokens(),
+        isLight: isLightTheme(),
+        hostTheme,
+        diffActive: !!diffActive,
+      });
+      return injectIntoHead(rawHtml, injection);
+    }, [rawHtml, hostTheme, diffActive]);
 
     const handleResize = useCallback((height: number) => {
       setIframeHeight(height);
@@ -189,9 +159,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     useEffect(() => {
       if (!iframeReady) return;
       function sendTheme() {
-        const tokens = readThemeTokens();
         iframeRef.current?.contentWindow?.postMessage(
-          { type: `${PREFIX}theme`, tokens, isLight: isLightTheme() },
+          {
+            type: `${PREFIX}theme`,
+            tokens: buildThemeTokenPayload(readThemeTokens(), hostTheme),
+            isLight: isLightTheme(),
+            hostTheme,
+          },
           "*",
         );
       }
@@ -202,7 +176,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         attributeFilter: ["class", "style"],
       });
       return () => observer.disconnect();
-    }, [iframeReady]);
+    }, [iframeReady, hostTheme]);
 
     useImperativeHandle(ref, () => ({
       removeHighlight: hook.removeHighlight,

package/components/html-viewer/bridge-script.ts

@@ -9,6 +9,11 @@
  * No external dependencies.
  */
 
+/**
+ * Reads only viewer-namespaced \`--pn-*\` variables (with fallbacks): arbitrary
+ * documents may define bare token names like \`--accent\` for themselves, and the
+ * viewer must never depend on — or collide with — the author's namespace.
+ */
 export const ANNOTATION_HIGHLIGHT_CSS = `
 .annotation-highlight {
   border-radius: 2px;
@@ -17,33 +22,33 @@ export const ANNOTATION_HIGHLIGHT_CSS = `
   cursor: pointer;
 }
 .annotation-highlight.deletion {
-  background: oklch(from var(--destructive, #c0392b) l c h / 0.35);
+  background: oklch(from var(--pn-destructive, #c0392b) l c h / 0.35);
   text-decoration: line-through;
-  text-decoration-color: var(--destructive, #c0392b);
+  text-decoration-color: var(--pn-destructive, #c0392b);
   text-decoration-thickness: 2px;
 }
 .annotation-highlight.comment {
   background: oklch(0.70 0.18 60 / 0.3);
-  border-bottom: 2px solid var(--accent, #d97757);
+  border-bottom: 2px solid var(--pn-accent, #d97757);
 }
 .annotation-highlight.focused {
-  background: oklch(from var(--focus-highlight, #4493f8) l c h / 0.45) !important;
-  box-shadow: 0 0 8px oklch(from var(--focus-highlight, #4493f8) l c h / 0.4);
-  border-bottom: 2px solid var(--focus-highlight, #4493f8);
+  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.45) !important;
+  box-shadow: 0 0 8px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.4);
+  border-bottom: 2px solid var(--pn-focus-highlight, #4493f8);
   filter: none;
 }
 .annotation-highlight:hover {
   filter: brightness(1.2);
 }
 .plannotator-pinpoint-hover {
-  outline: 2px solid var(--focus-highlight, #4493f8) !important;
+  outline: 2px solid var(--pn-focus-highlight, #4493f8) !important;
   outline-offset: 1px;
   cursor: crosshair !important;
 }
 /* SVG nodes can't take a CSS outline — stroke their shapes instead. */
 .plannotator-pinpoint-hover rect, .plannotator-pinpoint-hover path,
 .plannotator-pinpoint-hover circle, .plannotator-pinpoint-hover ellipse, .plannotator-pinpoint-hover polygon {
-  stroke: var(--focus-highlight, #4493f8) !important; stroke-width: 2.5px !important;
+  stroke: var(--pn-focus-highlight, #4493f8) !important; stroke-width: 2.5px !important;
 }
 `;
 
@@ -51,15 +56,23 @@ export const BRIDGE_SCRIPT = `(function() {
   var PREFIX = 'plannotator-bridge-';
 
   // --- Theme ---
+  // The author owns this document. Unless it opted in to host theming
+  // (hostTheme), only viewer-namespaced --pn-* properties may be written to its
+  // root, and its class list is never touched.
   window.addEventListener('message', function(e) {
     if (!e.data || e.data.type !== PREFIX + 'theme') return;
     var root = document.documentElement;
-    var tokens = e.data.tokens;
+    var tokens = e.data.tokens || {};
+    var hostTheme = !!e.data.hostTheme;
     for (var key in tokens) {
-      if (tokens.hasOwnProperty(key)) root.style.setProperty(key, tokens[key]);
+      if (!tokens.hasOwnProperty(key)) continue;
+      if (!hostTheme && key.indexOf('--pn-') !== 0) continue;
+      root.style.setProperty(key, tokens[key]);
+    }
+    if (hostTheme) {
+      root.classList.remove('light');
+      if (e.data.isLight) root.classList.add('light');
     }
-    root.classList.remove('light');
-    if (e.data.isLight) root.classList.add('light');
   });
 
   // --- Resize ---
@@ -244,7 +257,7 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!pinpointLabelEl) {
       pinpointLabelEl = document.createElement('div');
       pinpointLabelEl.setAttribute('data-plannotator-pinpoint-label', '');
-      pinpointLabelEl.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:none;font:600 11px/1.3 system-ui,-apple-system,sans-serif;padding:2px 7px;border-radius:5px;background:var(--focus-highlight,#4493f8);color:#fff;white-space:nowrap;box-shadow:0 1px 5px rgba(0,0,0,.35);';
+      pinpointLabelEl.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:none;font:600 11px/1.3 system-ui,-apple-system,sans-serif;padding:2px 7px;border-radius:5px;background:var(--pn-focus-highlight,#4493f8);color:#fff;white-space:nowrap;box-shadow:0 1px 5px rgba(0,0,0,.35);';
       document.body.appendChild(pinpointLabelEl);
     }
     return pinpointLabelEl;

package/components/html-viewer/srcdoc.ts

@@ -0,0 +1,130 @@
+/**
+ * Srcdoc injection builder for the HTML viewer.
+ *
+ * Product rule: arbitrary HTML must render exactly as it would in a plain
+ * browser tab. The viewer never writes into the document's namespace — no bare
+ * CSS custom properties, no classes on the author's root, no `color-scheme`,
+ * no styling of author elements. Host theme tokens are pushed under the
+ * viewer-owned `--pn-*` prefix, which the annotation CSS reads.
+ *
+ * Documents that WANT to follow the host theme (e.g. Plannotator-generated
+ * artifacts) opt in with `<meta name="plannotator-theme" content="host">`,
+ * which re-enables the bare-token push, the `light` class on their root, and
+ * `color-scheme` sync — for that document only.
+ *
+ * Pure string logic (no DOM) so the rendering-neutrality contract is unit-testable.
+ */
+import { ANNOTATION_HIGHLIGHT_CSS, BRIDGE_SCRIPT } from "./bridge-script";
+
+export const THEME_TOKENS = [
+  "--background",
+  "--foreground",
+  "--card",
+  "--card-foreground",
+  "--primary",
+  "--primary-foreground",
+  "--secondary",
+  "--secondary-foreground",
+  "--muted",
+  "--muted-foreground",
+  "--accent",
+  "--accent-foreground",
+  "--destructive",
+  "--destructive-foreground",
+  "--success",
+  "--success-foreground",
+  "--warning",
+  "--warning-foreground",
+  "--border",
+  "--input",
+  "--ring",
+  "--code-bg",
+  "--focus-highlight",
+  "--font-sans",
+  "--font-mono",
+  "--radius",
+] as const;
+
+/** Viewer-owned namespace for properties injected into the document. */
+export const PN_TOKEN_PREFIX = "--pn-";
+
+/**
+ * Version-diff highlights. htmlDiff tags the <ins>/<del> it generates with
+ * this class so author-written <ins>/<del> markup is never restyled.
+ */
+export const DIFF_HIGHLIGHT_CSS =
+  "ins.plannotator-diff{background:#e6ffec;color:#0a7d33;text-decoration:none;border-radius:2px;box-shadow:0 0 0 1px #abf2bc inset}" +
+  "del.plannotator-diff{background:#ffebe9;color:#b31d28;text-decoration:line-through;border-radius:2px;box-shadow:0 0 0 1px #ffc1bc inset}";
+
+/**
+ * True when the document opts in to following the host theme via
+ * `<meta name="plannotator-theme" content="host">` (attribute order/quoting agnostic).
+ */
+export function hasHostThemeOptIn(rawHtml: string): boolean {
+  const metas = rawHtml.match(/<meta\b[^>]*>/gi);
+  if (!metas) return false;
+  return metas.some(
+    (tag) =>
+      /\bname\s*=\s*["']?plannotator-theme["']?/i.test(tag) &&
+      /\bcontent\s*=\s*["']?host["']?/i.test(tag),
+  );
+}
+
+/**
+ * Build the theme properties to write into the document. Bare host token names
+ * (`--muted`, `--background`, …) collide with author variables, so they are
+ * remapped to `--pn-*`; the originals ride along only for host-theme documents.
+ */
+export function buildThemeTokenPayload(
+  tokens: Record<string, string>,
+  hostTheme: boolean,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const [key, val] of Object.entries(tokens)) {
+    payload[PN_TOKEN_PREFIX + key.slice(2)] = val;
+    if (hostTheme) payload[key] = val;
+  }
+  return payload;
+}
+
+export interface SrcdocInjectionOptions {
+  /** Host theme tokens, keyed by bare name (as read from the host root). */
+  tokens: Record<string, string>;
+  /** Whether the host is currently in its light theme. */
+  isLight: boolean;
+  /** Document opted in to host theming (see {@link hasHostThemeOptIn}). */
+  hostTheme: boolean;
+  /** The version-diff view is showing (rawHtml is htmlDiff output). */
+  diffActive: boolean;
+}
+
+/** The `<style>` + `<script>` block spliced into the document's head. */
+export function buildSrcdocInjection({
+  tokens,
+  isLight,
+  hostTheme,
+  diffActive,
+}: SrcdocInjectionOptions): string {
+  const payload = buildThemeTokenPayload(tokens, hostTheme);
+  let themeCSS = ":root {\n";
+  for (const [key, val] of Object.entries(payload)) {
+    themeCSS += `  ${key}: ${val};\n`;
+  }
+  themeCSS += "}\n";
+  // Host-theme documents mirror the host's light/dark; arbitrary documents keep
+  // their own color-scheme resolution (document + OS), like a standalone tab.
+  if (hostTheme) {
+    themeCSS += `:root { color-scheme: ${isLight ? "light" : "dark"}; }\n`;
+  }
+  const diffCSS = diffActive ? DIFF_HIGHLIGHT_CSS : "";
+  return `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style><script>${BRIDGE_SCRIPT}</script>`;
+}
+
+/** Splice the injection just before `</head>`, or prepend when there is none. */
+export function injectIntoHead(rawHtml: string, injection: string): string {
+  const headClose = rawHtml.indexOf("</head>");
+  if (headClose !== -1) {
+    return rawHtml.slice(0, headClose) + injection + rawHtml.slice(headClose);
+  }
+  return injection + rawHtml;
+}