@plannotator/ui 0.22.0

package/hooks/usePinpoint.ts

@@ -0,0 +1,182 @@
+import { useEffect, useState, useCallback, type RefObject } from 'react';
+import type Highlighter from '@plannotator/web-highlighter';
+import type { InputMethod } from '../types';
+import { resolvePinpointTarget, type PinpointTarget } from '../utils/blockTargeting';
+
+export interface UsePinpointOptions {
+  containerRef: RefObject<HTMLElement | null>;
+  highlighterRef: RefObject<Highlighter | null>;
+  inputMethod: InputMethod;
+  /** Disable when toolbar/popover/diff is active */
+  enabled: boolean;
+  /** Handle code block clicks (needs special annotation path) */
+  onCodeBlockClick: (blockId: string, element: HTMLElement) => void;
+}
+
+export interface UsePinpointReturn {
+  hoverTarget: { element: HTMLElement; label: string } | null;
+}
+
+export function usePinpoint({
+  containerRef,
+  highlighterRef,
+  inputMethod,
+  enabled,
+  onCodeBlockClick,
+}: UsePinpointOptions): UsePinpointReturn {
+  const [hoverTarget, setHoverTarget] = useState<{ element: HTMLElement; label: string } | null>(null);
+
+  const isActive = inputMethod === 'pinpoint' && enabled;
+
+  // Clear hover when deactivated
+  useEffect(() => {
+    if (!isActive) {
+      setHoverTarget((prev) => {
+        if (prev) prev.element.removeAttribute('data-pinpoint-hover');
+        return null;
+      });
+    }
+  }, [isActive]);
+
+  // Mousemove / touchstart — resolve target and update hover state
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!isActive || !container) return;
+
+    let prevElement: HTMLElement | null = null;
+
+    const updateHover = (clientX: number, clientY: number, target: HTMLElement) => {
+      const resolved = resolvePinpointTarget(target, container, { clientX, clientY });
+
+      if (resolved) {
+        if (resolved.element !== prevElement) {
+          prevElement?.removeAttribute('data-pinpoint-hover');
+          resolved.element.setAttribute('data-pinpoint-hover', '');
+          prevElement = resolved.element;
+          setHoverTarget({ element: resolved.element, label: resolved.label });
+        }
+      } else {
+        if (prevElement) {
+          prevElement.removeAttribute('data-pinpoint-hover');
+          prevElement = null;
+          setHoverTarget(null);
+        }
+      }
+    };
+
+    const handleMouseMove = (e: MouseEvent) => {
+      updateHover(e.clientX, e.clientY, e.target as HTMLElement);
+    };
+
+    const handleTouchStart = (e: TouchEvent) => {
+      if (e.touches.length !== 1) return;
+      const touch = e.touches[0];
+      const target = document.elementFromPoint(touch.clientX, touch.clientY) as HTMLElement;
+      if (target) updateHover(touch.clientX, touch.clientY, target);
+    };
+
+    const handleMouseLeave = () => {
+      prevElement?.removeAttribute('data-pinpoint-hover');
+      prevElement = null;
+      setHoverTarget(null);
+    };
+
+    container.addEventListener('mousemove', handleMouseMove);
+    container.addEventListener('mouseleave', handleMouseLeave);
+    container.addEventListener('touchstart', handleTouchStart, { passive: true });
+
+    return () => {
+      prevElement?.removeAttribute('data-pinpoint-hover');
+      container.removeEventListener('mousemove', handleMouseMove);
+      container.removeEventListener('mouseleave', handleMouseLeave);
+      container.removeEventListener('touchstart', handleTouchStart);
+    };
+  }, [isActive, containerRef]);
+
+  // Click — create Range and trigger web-highlighter
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!isActive || !container) return;
+
+    const handleClick = (e: MouseEvent) => {
+      // Read highlighter at click time, not effect setup time.
+      // On remount (e.g. after exiting plan diff), the highlighter init effect
+      // may not have run yet when this effect sets up, but it will be ready by
+      // the time the user clicks.
+      const highlighter = highlighterRef.current;
+      if (!highlighter) return;
+
+      const target = e.target as HTMLElement;
+      const resolved = resolvePinpointTarget(target, container, { clientX: e.clientX, clientY: e.clientY });
+      if (!resolved) return;
+
+      // Prevent link navigation in pinpoint mode
+      const link = (target.closest('a') as HTMLAnchorElement | null);
+      if (link && container.contains(link)) {
+        e.preventDefault();
+      }
+
+      // Clear hover state
+      resolved.element.removeAttribute('data-pinpoint-hover');
+      setHoverTarget(null);
+
+      if (resolved.isCodeBlock) {
+        // Route to existing code block annotation path
+        const codeBlockContainer = container.querySelector(`[data-block-id="${resolved.blockId}"]`) as HTMLElement;
+        if (codeBlockContainer) {
+          onCodeBlockClick(resolved.blockId, codeBlockContainer);
+        }
+        return;
+      }
+
+      // Create a text-level Range spanning the target element's content.
+      // web-highlighter needs ranges anchored to text nodes, not elements.
+      const range = createTextRange(resolved.element);
+      if (!range) return;
+
+      // Set browser selection so web-highlighter's mouseup handler picks it up
+      const sel = window.getSelection();
+      sel?.removeAllRanges();
+      sel?.addRange(range);
+
+      // Drive web-highlighter programmatically — fires CREATE event
+      highlighter.fromRange(range);
+
+      // Clean up browser selection
+      window.getSelection()?.removeAllRanges();
+    };
+
+    // Use capture phase so we get the click before links navigate
+    container.addEventListener('click', handleClick, true);
+
+    return () => {
+      container.removeEventListener('click', handleClick, true);
+    };
+  }, [isActive, containerRef, highlighterRef, onCodeBlockClick]);
+
+  return { hoverTarget };
+}
+
+/**
+ * Create a Range anchored to text nodes (not elements).
+ * web-highlighter's painter expects text-node-level ranges.
+ */
+function createTextRange(element: HTMLElement): Range | null {
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, null);
+
+  let firstNode: Text | null = null;
+  let lastNode: Text | null = null;
+
+  let node: Text | null;
+  while ((node = walker.nextNode() as Text | null)) {
+    if (!firstNode) firstNode = node;
+    lastNode = node;
+  }
+
+  if (!firstNode || !lastNode) return null;
+
+  const range = document.createRange();
+  range.setStart(firstNode, 0);
+  range.setEnd(lastNode, lastNode.length);
+  return range;
+}

package/hooks/usePlanDiff.ts

@@ -0,0 +1,176 @@
+/**
+ * Plan Diff Hook
+ *
+ * Manages plan diff state: version fetching, diff computation, and version browsing.
+ * Consumes the version history API endpoints.
+ */
+
+import { useState, useMemo, useCallback, useEffect } from "react";
+import {
+  computePlanDiff,
+  type PlanDiffBlock,
+  type PlanDiffStats,
+} from "../utils/planDiffEngine";
+
+export interface VersionInfo {
+  version: number;
+  totalVersions: number;
+  project: string;
+}
+
+export interface VersionEntry {
+  version: number;
+  timestamp: string;
+}
+
+export interface UsePlanDiffReturn {
+  /** The version we're comparing against */
+  diffBaseVersion: number | null;
+  /** Content of the base version */
+  diffBasePlan: string | null;
+  /** Computed diff blocks (null if no base plan to diff against) */
+  diffBlocks: PlanDiffBlock[] | null;
+  /** Computed diff stats (null if no diff) */
+  diffStats: PlanDiffStats | null;
+  /** Whether a previous version exists to diff against */
+  hasPreviousVersion: boolean;
+  /** Change the base version to diff against */
+  selectBaseVersion: (version: number) => Promise<void>;
+  /** All versions of the current plan */
+  versions: VersionEntry[];
+  /** Whether version list is loading */
+  isLoadingVersions: boolean;
+  /** Whether a version selection fetch is in progress */
+  isSelectingVersion: boolean;
+  /** Which version is currently being fetched (null if none) */
+  fetchingVersion: number | null;
+  /** Fetch the version list for the sidebar */
+  fetchVersions: () => Promise<void>;
+}
+
+export interface PlanDiffFetchers {
+  /** Fetch a specific version's plan content. Default → GET /api/plan/version?v=N */
+  fetchVersion?: (version: number) => Promise<{ plan: string; version: number }>;
+  /** Fetch the version list. Default → GET /api/plan/versions */
+  fetchVersions?: () => Promise<{
+    project: string;
+    slug: string;
+    versions: VersionEntry[];
+  }>;
+}
+
+const defaultFetchVersion = async (
+  version: number
+): Promise<{ plan: string; version: number }> => {
+  const res = await fetch(`/api/plan/version?v=${version}`);
+  if (!res.ok) {
+    throw new Error(`Failed to load version ${version}.`);
+  }
+  return (await res.json()) as { plan: string; version: number };
+};
+
+const defaultFetchVersions = async (): Promise<{
+  project: string;
+  slug: string;
+  versions: VersionEntry[];
+}> => {
+  const res = await fetch("/api/plan/versions");
+  if (!res.ok) {
+    throw new Error("Failed to load versions.");
+  }
+  return (await res.json()) as {
+    project: string;
+    slug: string;
+    versions: VersionEntry[];
+  };
+};
+
+export function usePlanDiff(
+  currentPlan: string,
+  initialPreviousPlan: string | null,
+  versionInfo: VersionInfo | null,
+  fetchers?: PlanDiffFetchers
+): UsePlanDiffReturn {
+  const fetchVersionImpl = fetchers?.fetchVersion ?? defaultFetchVersion;
+  const fetchVersionsImpl = fetchers?.fetchVersions ?? defaultFetchVersions;
+  const [diffBasePlan, setDiffBasePlan] = useState<string | null>(
+    initialPreviousPlan
+  );
+  const [diffBaseVersion, setDiffBaseVersion] = useState<number | null>(
+    versionInfo && versionInfo.version > 1 ? versionInfo.version - 1 : null
+  );
+  const [versions, setVersions] = useState<VersionEntry[]>([]);
+  const [isLoadingVersions, setIsLoadingVersions] = useState(false);
+  const [isSelectingVersion, setIsSelectingVersion] = useState(false);
+  const [fetchingVersion, setFetchingVersion] = useState<number | null>(null);
+
+  // Sync diffBasePlan when initialPreviousPlan arrives after mount (API response)
+  useEffect(() => {
+    if (initialPreviousPlan && !diffBasePlan) {
+      setDiffBasePlan(initialPreviousPlan);
+    }
+  }, [initialPreviousPlan]);
+
+  // Sync diffBaseVersion when versionInfo arrives after mount
+  useEffect(() => {
+    if (versionInfo && versionInfo.version > 1 && diffBaseVersion === null) {
+      setDiffBaseVersion(versionInfo.version - 1);
+    }
+  }, [versionInfo]);
+
+  const hasPreviousVersion =
+    versionInfo !== null && versionInfo.totalVersions > 1 && diffBasePlan !== null;
+
+  // Compute diff whenever currentPlan or diffBasePlan changes
+  const diffResult = useMemo(() => {
+    if (!diffBasePlan) return null;
+    return computePlanDiff(diffBasePlan, currentPlan);
+  }, [currentPlan, diffBasePlan]);
+
+  const diffBlocks = diffResult?.blocks ?? null;
+  const diffStats = diffResult?.stats ?? null;
+
+  const selectBaseVersion = useCallback(
+    async (version: number) => {
+      setIsSelectingVersion(true);
+      setFetchingVersion(version);
+      try {
+        const data = await fetchVersionImpl(version);
+        setDiffBasePlan(data.plan);
+        setDiffBaseVersion(version);
+      } catch {
+        alert(`Failed to load version ${version}.`);
+      } finally {
+        setIsSelectingVersion(false);
+        setFetchingVersion(null);
+      }
+    },
+    [fetchVersionImpl]
+  );
+
+  const fetchVersions = useCallback(async () => {
+    setIsLoadingVersions(true);
+    try {
+      const data = await fetchVersionsImpl();
+      setVersions(data.versions);
+    } catch {
+      // Failed to fetch versions
+    } finally {
+      setIsLoadingVersions(false);
+    }
+  }, [fetchVersionsImpl]);
+
+  return {
+    diffBaseVersion,
+    diffBasePlan,
+    diffBlocks,
+    diffStats,
+    hasPreviousVersion,
+    selectBaseVersion,
+    versions,
+    isLoadingVersions,
+    isSelectingVersion,
+    fetchingVersion,
+    fetchVersions,
+  };
+}

package/hooks/usePrintMode.ts

@@ -0,0 +1,27 @@
+import { useEffect } from 'react';
+
+/**
+ * Manages print mode by toggling 'plannotator-print' class on <html>.
+ * Includes visibilitychange fallback for Firefox, which may not fire
+ * afterprint when print preview is closed without printing.
+ */
+export function usePrintMode() {
+  useEffect(() => {
+    const onBeforePrint = () => document.documentElement.classList.add('plannotator-print');
+    const onAfterPrint = () => document.documentElement.classList.remove('plannotator-print');
+    const onVisibilityChange = () => {
+      if (!document.hidden && document.documentElement.classList.contains('plannotator-print')) {
+        document.documentElement.classList.remove('plannotator-print');
+      }
+    };
+    window.addEventListener('beforeprint', onBeforePrint);
+    window.addEventListener('afterprint', onAfterPrint);
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => {
+      window.removeEventListener('beforeprint', onBeforePrint);
+      window.removeEventListener('afterprint', onAfterPrint);
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      document.documentElement.classList.remove('plannotator-print');
+    };
+  }, []);
+}

package/hooks/useResizablePanel.ts

@@ -0,0 +1,173 @@
+import { useState, useRef, useCallback } from 'react';
+import { storage } from '../utils/storage';
+
+interface UseResizablePanelOptions {
+  storageKey: string;
+  defaultWidth?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  side?: 'left' | 'right' | 'top' | 'bottom';
+  /** Drag axis: 'x' resizes width (default), 'y' resizes height (uses clientY). */
+  axis?: 'x' | 'y';
+  /**
+   * When provided, dragging the panel narrower than `snapCloseRatio * minWidth`
+   * snaps it shut (calls this) instead of clamping at minWidth.
+   */
+  onSnapClose?: () => void;
+  snapCloseRatio?: number;
+  /**
+   * Imperative live-apply. When provided, the drag drives the width through this
+   * callback ONCE PER FRAME and does NOT call setState — so the host component
+   * never re-renders mid-drag (buttery on heavy hosts). React state is committed
+   * once on release. When omitted, the width is driven through React state
+   * (still rAF-coalesced).
+   */
+  apply?: (width: number) => void;
+}
+
+export interface ResizeHandleProps {
+  isDragging: boolean;
+  onPointerDown: (e: React.PointerEvent) => void;
+  onDoubleClick: () => void;
+  /** touch-action: none so touch drags don't scroll-hijack. */
+  style: React.CSSProperties;
+}
+
+export function useResizablePanel({
+  storageKey,
+  defaultWidth = 288,
+  minWidth = 200,
+  maxWidth = 600,
+  side = 'right',
+  axis = 'x',
+  onSnapClose,
+  snapCloseRatio = 0.6,
+  apply,
+}: UseResizablePanelOptions) {
+  const [width, setWidth] = useState(() => {
+    const saved = storage.getItem(storageKey);
+    if (saved) {
+      const n = Number(saved);
+      if (!Number.isNaN(n) && n >= minWidth && n <= maxWidth) return n;
+    }
+    return defaultWidth;
+  });
+
+  const [isDragging, setIsDragging] = useState(false);
+
+  // Live/committed width. Drag math reads/writes this without re-rendering.
+  const widthRef = useRef(width);
+  const startXRef = useRef(0);
+  const startWidthRef = useRef(0);
+  const draggingRef = useRef(false);
+  const snappedRef = useRef(false);
+  const latestXRef = useRef(0);
+  const rafRef = useRef<number | null>(null);
+
+  // Latest callbacks via refs so the rAF loop always sees fresh values.
+  const applyRef = useRef(apply);
+  applyRef.current = apply;
+  const onSnapCloseRef = useRef(onSnapClose);
+  onSnapCloseRef.current = onSnapClose;
+
+  // rAF tick: compute the width from the most recent pointer position and apply
+  // it. At most one DOM/state write per frame regardless of pointer-event rate.
+  const flush = useCallback(() => {
+    rafRef.current = null;
+    if (!draggingRef.current) return;
+    const delta =
+      side === 'right' || side === 'bottom'
+        ? startXRef.current - latestXRef.current
+        : latestXRef.current - startXRef.current;
+    const raw = startWidthRef.current + delta;
+
+    // Drag-to-snap-shut.
+    if (onSnapCloseRef.current && raw < minWidth * snapCloseRatio) {
+      snappedRef.current = true;
+      draggingRef.current = false;
+      widthRef.current = startWidthRef.current;
+      applyRef.current?.(startWidthRef.current);
+      storage.setItem(storageKey, String(startWidthRef.current));
+      setWidth(startWidthRef.current);
+      setIsDragging(false);
+      onSnapCloseRef.current();
+      return;
+    }
+
+    const w = Math.min(maxWidth, Math.max(minWidth, raw));
+    widthRef.current = w;
+    if (applyRef.current) applyRef.current(w);
+    else setWidth(w);
+  }, [side, minWidth, maxWidth, snapCloseRatio, storageKey]);
+
+  const onPointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      // Only primary button / touch / pen.
+      if (e.button !== 0) return;
+      e.preventDefault();
+      const pos = axis === 'y' ? e.clientY : e.clientX;
+      startXRef.current = pos;
+      startWidthRef.current = widthRef.current;
+      latestXRef.current = pos;
+      snappedRef.current = false;
+      draggingRef.current = true;
+      setIsDragging(true);
+
+      // Native window listeners — fire for EVERY pointer move anywhere on screen,
+      // including past the window edge and faster than the cursor. This is the
+      // reliable path (React's synthetic onPointerMove on the tiny handle drops
+      // moves once the pointer leaves it).
+      const onMove = (ev: PointerEvent) => {
+        if (!draggingRef.current) return;
+        latestXRef.current = axis === 'y' ? ev.clientY : ev.clientX;
+        if (rafRef.current == null) rafRef.current = requestAnimationFrame(flush);
+      };
+      const cleanup = () => {
+        window.removeEventListener('pointermove', onMove);
+        window.removeEventListener('pointerup', onUp);
+        window.removeEventListener('pointercancel', onUp);
+      };
+      function onUp() {
+        const wasSnapped = snappedRef.current;
+        draggingRef.current = false;
+        snappedRef.current = false;
+        if (rafRef.current != null) {
+          cancelAnimationFrame(rafRef.current);
+          rafRef.current = null;
+        }
+        setIsDragging(false);
+        if (!wasSnapped) {
+          // Commit the live width to React state + persist.
+          setWidth(widthRef.current);
+          storage.setItem(storageKey, String(widthRef.current));
+        }
+        cleanup();
+      }
+
+      window.addEventListener('pointermove', onMove);
+      window.addEventListener('pointerup', onUp);
+      window.addEventListener('pointercancel', onUp);
+    },
+    [flush, storageKey, axis],
+  );
+
+  const resetWidth = useCallback(() => {
+    widthRef.current = defaultWidth;
+    applyRef.current?.(defaultWidth);
+    setWidth(defaultWidth);
+    storage.setItem(storageKey, String(defaultWidth));
+  }, [defaultWidth, storageKey]);
+
+  return {
+    width,
+    /** Alias for `width` — reads clearer when axis is 'y' (it's a height). */
+    size: width,
+    isDragging,
+    handleProps: {
+      isDragging,
+      onPointerDown,
+      onDoubleClick: resetWidth,
+      style: { touchAction: 'none' },
+    } as ResizeHandleProps,
+  };
+}

package/hooks/useScrollViewport.ts

@@ -0,0 +1,38 @@
+import { createContext, useContext, createElement, type ReactNode } from 'react';
+
+/**
+ * Provides the currently-active scroll viewport element to descendants.
+ *
+ * The element that actually scrolls is the host element rendered by
+ * <OverlayScrollArea> (native scroll) — not <main>. Any code that needs the
+ * scroll container (IntersectionObserver roots, scroll event listeners,
+ * scrollTo / getBoundingClientRect offsets) must consume this context instead
+ * of `document.querySelector('main')`.
+ *
+ * The value is `null` until the scroll element has mounted. Consumers should
+ * handle that transient state.
+ */
+export const ScrollViewportContext = createContext<HTMLElement | null>(null);
+
+/** Returns the active scroll viewport element, or `null` before it mounts. */
+export function useScrollViewport(): HTMLElement | null {
+  return useContext(ScrollViewportContext);
+}
+
+/**
+ * Render-transparent provider for the active scroll viewport element.
+ *
+ * The host mounts this around its layout and feeds it the MAIN content's scroll
+ * element, so descendants — including a sidebar Table-of-Contents rendered
+ * inside it — resolve to the main viewport (not the sidebar's own scroll area).
+ * Ships with the package so consumers work without app-shell wiring.
+ */
+export function ScrollViewportProvider({
+  viewport,
+  children,
+}: {
+  viewport: HTMLElement | null;
+  children: ReactNode;
+}) {
+  return createElement(ScrollViewportContext.Provider, { value: viewport }, children);
+}