@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/review-editor/review-editor-selection-geometry.ts

@@ -0,0 +1,31 @@
+export type SelectionAnchorPosition = {
+  x: number;
+  y: number;
+  /** Height of the selection rect in CSS pixels. */
+  height: number;
+};
+
+type SelectionRangeGeometry = Pick<Range, 'getBoundingClientRect' | 'getClientRects'>;
+
+export function getSelectionAnchorRect(range: SelectionRangeGeometry): DOMRect | null {
+  const rect =
+    Array.from(range.getClientRects()).find((clientRect) => {
+      return clientRect.width > 0 && clientRect.height > 0;
+    }) ?? range.getBoundingClientRect();
+
+  if (rect.width === 0 && rect.height === 0) return null;
+  return rect;
+}
+
+export function getSelectionAnchorPosition(
+  range: SelectionRangeGeometry,
+): SelectionAnchorPosition | null {
+  const rect = getSelectionAnchorRect(range);
+  if (!rect) return null;
+
+  return {
+    x: rect.left + rect.width / 2,
+    y: rect.top,
+    height: rect.height,
+  };
+}

package/src/components/review-editor/review-editor-selection-types.ts

@@ -0,0 +1,68 @@
+/**
+ * Public types for the selection popover manager, in a plain `.ts` file so the
+ * standard TypeScript compiler (not Svelte's `compileModule`) emits them.
+ */
+import type { ThreadCreateEvent } from '@lostgradient/cinder/commentary/comments';
+import type { EditorView } from '@milkdown/kit/prose/view';
+import type {
+  PopoverPosition,
+  ReviewMode,
+  ReviewEditorViewType as ViewType,
+} from './review-editor.types.ts';
+
+/**
+ * Options for creating the selection popover manager.
+ */
+export type SelectionPopoverOptions = {
+  /** Get the component ID */
+  getId: () => string;
+  /** Get the main editor area element (for scoping selection checks) */
+  getMainRef: () => HTMLElement | null;
+  /** Get the editor view */
+  getEditorView: () => EditorView | undefined;
+  /** Get the current mode */
+  getMode: () => ReviewMode;
+  /** Get the current view type */
+  getActiveView: () => ViewType;
+  /** Get the current user ID */
+  getCurrentUserId: () => string | undefined;
+  /** Check if thread popover is currently open */
+  isThreadPopoverOpen: () => boolean;
+  /** Announce message to screen readers */
+  announce: (message: string, priority?: 'polite' | 'assertive') => void;
+  /** Event callback for thread creation */
+  onthreadcreate?: (event: ThreadCreateEvent) => void;
+};
+
+/**
+ * Selection popover manager interface.
+ */
+export type SelectionPopover = {
+  /** Position for the selection popover (viewport-relative) */
+  readonly position: PopoverPosition | null;
+  /** Captured selection range for thread creation */
+  readonly capturedSelection: { from: number; to: number } | null;
+  /** Whether the popover is in expanded form state */
+  readonly expanded: boolean;
+  /** Whether the selection popover should be visible */
+  readonly visible: boolean;
+
+  /** Handle the comment submission from the selection popover */
+  handleComment(body: string): void;
+  /** Handle expanding the popover to show the form */
+  handleExpand(): void;
+  /** Handle canceling the expanded state */
+  handleCancel(): void;
+  /** Close the selection popover completely */
+  close(): void;
+  /** Clear all selection popover state */
+  clear(): void;
+
+  /** Start listening to browser selection changes */
+  startListening(): void;
+  /** Stop listening to browser selection changes */
+  stopListening(): void;
+
+  /** Destroy the manager and clean up resources */
+  destroy(): void;
+};

package/src/components/review-editor/review-editor-selection.svelte.ts

@@ -0,0 +1,292 @@
+/**
+ * Selection popover management for ReviewEditor (DEP-422).
+ *
+ * Handles:
+ * - Selection popover lifecycle and positioning
+ * - Browser selection change detection
+ * - Captured selection for thread creation
+ * - RAF timing for coordinate calculation
+ *
+ * State machine:
+ * HIDDEN → (selectionchange + non-collapsed) → PREVIEW → (click icon) → EXPANDED → (submit/cancel) → HIDDEN
+ *
+ * **Note:** This module is experimental and provides an alternative implementation
+ * to the inline selection popover logic in `review-editor.svelte`. It is exported for
+ * testing and potential future refactoring, but the component does not currently
+ * delegate to this factory.
+ *
+ * @module
+ * @experimental
+ */
+import { buildAnchorFromSelection } from '@lostgradient/cinder/commentary/anchoring';
+import { extractMentions, generateId } from '@lostgradient/cinder/commentary/comments';
+import { devWarn } from '../../utilities/dev-warn.ts';
+import { getSelectionAnchorPosition } from './review-editor-selection-geometry.ts';
+/** Debounce delay for selection position calculation (ms) */
+const SELECTION_DEBOUNCE_MS = 20;
+/**
+ * Create a selection popover manager.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createSelectionPopover } from './review-editor-selection.svelte';
+ *
+ *   const selectionPopover = createSelectionPopover({
+ *     getId: () => id,
+ *     getMainRef: () => mainRef,
+ *     getEditorView: () => editorRef?.getView(),
+ *     getMode: () => mode,
+ *     getActiveView: () => activeView,
+ *     getCurrentUserId: () => currentUserId,
+ *     isThreadPopoverOpen: () => threadManager.popoverThreadId !== null,
+ *     announce,
+ *     onthreadcreate,
+ *   });
+ *
+ *   // Start listening when component mounts
+ *   $effect(() => {
+ *     selectionPopover.startListening();
+ *     return () => selectionPopover.destroy();
+ *   });
+ * </script>
+ * ```
+ */
+export function createSelectionPopover(options) {
+    const { getId, getMainRef, getEditorView, getMode, getActiveView, getCurrentUserId, isThreadPopoverOpen, announce, onthreadcreate, } = options;
+    // Internal state
+    let position = $state(null);
+    let capturedSelection = $state(null);
+    let expanded = $state(false);
+    // Timer for debounced selection position calculation
+    let selectionTimeoutId = null;
+    // Whether currently listening to selection changes
+    let isListening = false;
+    // Version token for async safety
+    let computeVersion = 0;
+    /**
+     * Whether the selection popover should be visible.
+     */
+    const visible = $derived.by(() => {
+        return (getActiveView() === 'editor' &&
+            getMode() === 'edit' &&
+            getCurrentUserId() !== undefined &&
+            (position !== null || expanded) &&
+            !isThreadPopoverOpen());
+    });
+    /**
+     * Clear any pending timeouts.
+     */
+    function clearTimeouts() {
+        if (selectionTimeoutId !== null) {
+            clearTimeout(selectionTimeoutId);
+            selectionTimeoutId = null;
+        }
+    }
+    /**
+     * Clear all selection popover state.
+     */
+    function clear() {
+        clearTimeouts();
+        position = null;
+        capturedSelection = null;
+        expanded = false;
+        computeVersion++;
+    }
+    /**
+     * Close the selection popover.
+     */
+    function close() {
+        clear();
+    }
+    /**
+     * Handle expanding the popover to show the form.
+     */
+    function handleExpand() {
+        expanded = true;
+    }
+    /**
+     * Handle canceling the expanded state.
+     */
+    function handleCancel() {
+        expanded = false;
+        // Keep position and captured selection so user can re-expand if they want
+    }
+    /**
+     * Handle the comment submission from the selection popover.
+     */
+    function handleComment(body) {
+        // Helper to clear state and announce failure
+        function failWithMessage(message) {
+            devWarn(message);
+            clear();
+            announce('Could not add comment. Please try selecting text again.', 'assertive');
+        }
+        const currentUserId = getCurrentUserId();
+        if (!currentUserId) {
+            failWithMessage('Cannot create comment: no currentUserId set');
+            return;
+        }
+        if (!capturedSelection) {
+            failWithMessage('Cannot create comment: no captured selection');
+            return;
+        }
+        if (getMode() === 'readonly') {
+            failWithMessage('Cannot create thread: editor is readonly');
+            return;
+        }
+        const view = getEditorView();
+        if (!view) {
+            failWithMessage('Cannot create thread: editor view not available');
+            return;
+        }
+        const { from, to } = capturedSelection;
+        // Validate positions are still within document bounds
+        const docSize = view.state.doc.content.size;
+        if (from < 0 || to > docSize || from > to) {
+            failWithMessage('Cannot create thread: captured selection is out of bounds');
+            return;
+        }
+        // Build anchor using shared helper
+        const anchor = buildAnchorFromSelection(view, from, to);
+        const requestId = generateId();
+        const mentions = extractMentions(body);
+        // Fire the create event
+        const event = {
+            requestId,
+            anchor,
+            body,
+            authorId: currentUserId,
+            mentions: mentions.length > 0 ? mentions : undefined,
+        };
+        onthreadcreate?.(event);
+        // Clear state
+        clear();
+        announce('Comment added');
+    }
+    /**
+     * Handle browser selection change event.
+     */
+    function handleBrowserSelectionChange() {
+        // Clear any pending calculation
+        clearTimeouts();
+        // Only process in edit mode
+        if (getMode() !== 'edit') {
+            position = null;
+            capturedSelection = null;
+            return;
+        }
+        // Don't clear the popover if focus is within it
+        const selectionPopoverElement = document.getElementById(`${getId()}-selection-popover`);
+        if (selectionPopoverElement?.contains(document.activeElement)) {
+            return;
+        }
+        // Don't clear if expanded (user is composing a comment)
+        if (expanded) {
+            return;
+        }
+        const browserSelection = window.getSelection();
+        // If selection is collapsed, hide popover immediately
+        if (!browserSelection || browserSelection.isCollapsed) {
+            position = null;
+            capturedSelection = null;
+            expanded = false;
+            return;
+        }
+        // Check if selection is within the main editor area
+        const mainRef = getMainRef();
+        const anchorNode = browserSelection.anchorNode;
+        if (!mainRef || !anchorNode || !mainRef.contains(anchorNode)) {
+            position = null;
+            capturedSelection = null;
+            expanded = false;
+            return;
+        }
+        // Capture version for async safety
+        const version = ++computeVersion;
+        // Debounce position calculation
+        selectionTimeoutId = setTimeout(() => {
+            selectionTimeoutId = null;
+            // Check if this computation is stale
+            if (computeVersion !== version)
+                return;
+            // Re-check selection after debounce
+            const sel = window.getSelection();
+            if (!sel || sel.isCollapsed) {
+                position = null;
+                capturedSelection = null;
+                return;
+            }
+            // Get the selection range and compute position from the browser's DOM
+            const range = sel.getRangeAt(0);
+            const anchorPosition = getSelectionAnchorPosition(range);
+            if (anchorPosition) {
+                // Capture the ProseMirror selection range for thread creation
+                const view = getEditorView();
+                if (view) {
+                    const { from, to } = view.state.selection;
+                    if (from !== to) {
+                        capturedSelection = { from, to };
+                        position = anchorPosition;
+                    }
+                }
+            }
+        }, SELECTION_DEBOUNCE_MS);
+    }
+    /**
+     * Start listening to browser selection changes.
+     */
+    function startListening() {
+        if (isListening || typeof document === 'undefined')
+            return;
+        document.addEventListener('selectionchange', handleBrowserSelectionChange);
+        isListening = true;
+    }
+    /**
+     * Stop listening to browser selection changes.
+     */
+    function stopListening() {
+        if (!isListening || typeof document === 'undefined')
+            return;
+        document.removeEventListener('selectionchange', handleBrowserSelectionChange);
+        isListening = false;
+    }
+    /**
+     * Destroy the manager and clean up resources.
+     */
+    function destroy() {
+        stopListening();
+        clearTimeouts();
+    }
+    // Clear selection popover state when mode changes to readonly
+    $effect(() => {
+        if (getMode() === 'readonly') {
+            clear();
+        }
+    });
+    return {
+        // State
+        get position() {
+            return position;
+        },
+        get capturedSelection() {
+            return capturedSelection;
+        },
+        get expanded() {
+            return expanded;
+        },
+        get visible() {
+            return visible;
+        },
+        // Actions
+        handleComment,
+        handleExpand,
+        handleCancel,
+        close,
+        clear,
+        // Lifecycle
+        startListening,
+        stopListening,
+        destroy,
+    };
+}

package/src/components/review-editor/review-editor-state.svelte.ts

@@ -0,0 +1,117 @@
+/**
+ * Core state management for ReviewEditor (DEP-422).
+ *
+ * Provides reactive state for:
+ * - Diff statistics (added/removed/modified line counts)
+ * - Comment count
+ * - Summary content
+ * - View type management
+ *
+ * Uses the factory pattern with lazy getters for dependency injection,
+ * matching the established pattern in change-tracker.svelte.ts.
+ *
+ * @module
+ */
+import { generateMarkdownSummary } from '@lostgradient/cinder/commentary/export';
+import { computeLineDiff, getDiffStats } from '@lostgradient/cinder/markdown/diff/line-diff';
+import { normalize } from '@lostgradient/cinder/markdown/pipeline';
+/**
+ * Create a review editor state manager.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createReviewEditorState } from './review-editor-state.svelte';
+ *
+ *   const state = createReviewEditorState({
+ *     getOriginal: () => original,
+ *     getValue: () => value,
+ *     getThreads: () => threads,
+ *   });
+ *
+ *   // Access reactive values
+ *   const diffStats = $derived(state.diffStats);
+ *   const hasChanges = $derived(state.hasContentChanges);
+ * </script>
+ * ```
+ */
+export function createReviewEditorState(options) {
+    const { getOriginal, getValue, getThreads } = options;
+    // Internal state
+    let activeView = $state('editor');
+    let diffViewMode = $state('unified');
+    // Computed diff statistics
+    const diffStats = $derived.by(() => {
+        const original = getOriginal();
+        if (!original) {
+            return { added: 0, removed: 0, modified: 0 };
+        }
+        // Normalize both inputs to avoid false positives from formatting differences
+        const normalizedOriginal = normalize(original);
+        const normalizedCurrent = normalize(getValue());
+        const lineDiffs = computeLineDiff(normalizedOriginal, normalizedCurrent);
+        return getDiffStats(lineDiffs);
+    });
+    // Whether there are any content changes
+    const hasContentChanges = $derived(diffStats.added > 0 || diffStats.removed > 0 || diffStats.modified > 0);
+    // Total comment count (excluding soft-deleted comments)
+    const commentCount = $derived.by(() => {
+        const threads = getThreads();
+        return threads.reduce((count, thread) => {
+            return count + thread.comments.filter((c) => !c.deletedAt).length;
+        }, 0);
+    });
+    // Summary content for the Summary view (without heading)
+    const summaryContent = $derived.by(() => {
+        const threads = getThreads();
+        const state = {
+            schemaVersion: 4,
+            content: getValue(),
+            original: getOriginal() || undefined,
+            threads: threads.map((t) => ({
+                ...t,
+                anchor: {
+                    quote: t.anchor.quote,
+                    prefix: t.anchor.prefix,
+                    suffix: t.anchor.suffix,
+                    status: t.anchor.status,
+                    blockId: t.anchor.blockId,
+                    originalPosition: t.anchor.originalPosition,
+                    originalQuote: t.anchor.originalQuote,
+                    lastKnownOffset: t.anchor.lastKnownOffset,
+                },
+            })),
+            // Static timestamp for state construction - not meant to be reactive
+            updatedAt: '',
+        };
+        const result = generateMarkdownSummary(state);
+        // Strip the "# Review Summary\n" heading from the beginning
+        return result.markdown.replace(/^# Review Summary\n+/, '');
+    });
+    return {
+        get activeView() {
+            return activeView;
+        },
+        setActiveView(view) {
+            activeView = view;
+        },
+        get diffViewMode() {
+            return diffViewMode;
+        },
+        setDiffViewMode(mode) {
+            diffViewMode = mode;
+        },
+        get diffStats() {
+            return diffStats;
+        },
+        get hasContentChanges() {
+            return hasContentChanges;
+        },
+        get commentCount() {
+            return commentCount;
+        },
+        get summaryContent() {
+            return summaryContent;
+        },
+    };
+}