@lostgradient/cinder 0.6.0 → 0.8.0

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

@@ -0,0 +1,435 @@
+/**
+ * Thread management for ReviewEditor (DEP-422).
+ *
+ * Handles:
+ * - Thread/comment CRUD operations
+ * - Thread popover state (open/close/position)
+ * - Active thread tracking
+ * - Sidebar thread selection
+ *
+ * Uses the factory pattern with lazy getters for dependency injection.
+ *
+ * **Note:** This module is experimental and provides an alternative implementation
+ * to the inline thread management in `review-editor.svelte`. It is exported for
+ * testing and potential future refactoring, but the component does not currently
+ * delegate to this factory. Behavior fixes should be made in both locations until
+ * the component is refactored to use this module.
+ *
+ * @module
+ * @experimental
+ */
+import { buildAnchorFromSelection } from '@lostgradient/cinder/commentary/anchoring';
+import { createDocumentAnchor, extractMentions, generateId, } from '@lostgradient/cinder/commentary/comments';
+import { devWarn } from '../../utilities/dev-warn.ts';
+/** Delay for scroll-then-position pattern (matches smooth scroll duration) */
+const POSITION_DELAY_MS = 350;
+/**
+ * Create a thread manager.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createThreadManager } from './review-editor-threads.svelte';
+ *
+ *   const threadManager = createThreadManager({
+ *     getThreads: () => threads,
+ *     getEditorView: () => editorRef?.getView(),
+ *     getMode: () => mode,
+ *     getCurrentUserId: () => currentUserId,
+ *     getScrollBehavior,
+ *     announce,
+ *     onthreadcreate,
+ *     onthreaddelete,
+ *     oncommentcreate,
+ *     oncommentupdate,
+ *     oncommentdelete,
+ *   });
+ * </script>
+ * ```
+ */
+export function createThreadManager(options) {
+    const { getThreads, getEditorView, getMode, getCurrentUserId, getScrollBehavior, announce, onthreadcreate, onthreaddelete, oncommentcreate, oncommentupdate, oncommentdelete, onBeforePopoverOpen, } = options;
+    // Internal state
+    let popoverThreadId = $state(null);
+    let popoverPosition = $state(null);
+    let activeThreadId = $state(null);
+    // Timer handle for panel selection scroll-then-position delay
+    let selectTimeoutId = null;
+    // Get the popover thread
+    const popoverThread = $derived.by(() => {
+        if (!popoverThreadId)
+            return null;
+        return getThreads().find((t) => t.id === popoverThreadId) ?? null;
+    });
+    // Clear popover if thread is deleted
+    $effect(() => {
+        if (popoverThreadId && !popoverThread) {
+            popoverThreadId = null;
+            popoverPosition = null;
+        }
+    });
+    // Clear internal active thread if it no longer exists
+    $effect(() => {
+        if (activeThreadId && !getThreads().some((t) => t.id === activeThreadId)) {
+            activeThreadId = null;
+        }
+    });
+    // Deep linking: open popover when activeThreadId is set externally
+    $effect(() => {
+        let positionTimeoutId = null;
+        if (activeThreadId && popoverThreadId !== activeThreadId) {
+            const threads = getThreads();
+            const thread = threads.find((t) => t.id === activeThreadId);
+            if (thread) {
+                const threadIdToOpen = activeThreadId;
+                // First, scroll the anchor into view
+                scrollAnchorIntoView(threadIdToOpen);
+                // After scrolling, calculate position and open the popover
+                positionTimeoutId = setTimeout(() => {
+                    const currentThread = getThreads().find((t) => t.id === threadIdToOpen);
+                    if (!currentThread)
+                        return;
+                    const pos = calculateViewportPosition(currentThread.anchor.from);
+                    if (pos) {
+                        popoverPosition = { x: pos.x + 16, y: pos.y };
+                        popoverThreadId = threadIdToOpen;
+                    }
+                }, POSITION_DELAY_MS);
+            }
+        }
+        return () => {
+            if (positionTimeoutId !== null) {
+                clearTimeout(positionTimeoutId);
+            }
+        };
+    });
+    /**
+     * Calculate position for fixed-position popovers near an anchor.
+     */
+    function calculateViewportPosition(from) {
+        const view = getEditorView();
+        if (!view)
+            return null;
+        try {
+            const coords = view.coordsAtPos(from);
+            if (coords) {
+                return {
+                    x: Math.max(16, coords.left),
+                    y: coords.top + 24,
+                };
+            }
+        }
+        catch {
+            // Position may be invalid
+        }
+        return null;
+    }
+    /**
+     * Scroll the editor to bring an anchor position into view.
+     */
+    function scrollAnchorIntoView(threadId) {
+        const editorDom = getEditorView()?.dom;
+        const anchorElement = editorDom?.querySelector(`[data-thread-id="${threadId}"]`);
+        if (anchorElement) {
+            anchorElement.scrollIntoView({ behavior: getScrollBehavior(), block: 'center' });
+        }
+    }
+    /**
+     * Scroll to a specific thread's anchor position.
+     */
+    function scrollToThread(threadId) {
+        const thread = getThreads().find((t) => t.id === threadId);
+        if (!thread)
+            return;
+        const view = getEditorView();
+        if (view && thread.anchor.from !== undefined) {
+            const coords = view.coordsAtPos(thread.anchor.from);
+            if (coords) {
+                view.dom.scrollTo({
+                    top: coords.top - 100,
+                    behavior: getScrollBehavior(),
+                });
+            }
+        }
+    }
+    /**
+     * Open the popover for a thread.
+     */
+    function openPopover(threadId, position) {
+        popoverThreadId = threadId;
+        popoverPosition = position;
+        activeThreadId = threadId;
+    }
+    /**
+     * Close the popover.
+     */
+    function closePopover() {
+        if (selectTimeoutId !== null) {
+            clearTimeout(selectTimeoutId);
+            selectTimeoutId = null;
+        }
+        popoverThreadId = null;
+        popoverPosition = null;
+        activeThreadId = null;
+    }
+    /**
+     * Handle click on an anchor decoration.
+     */
+    function handleAnchorClick(threadId, event) {
+        if (selectTimeoutId !== null) {
+            clearTimeout(selectTimeoutId);
+            selectTimeoutId = null;
+        }
+        // Clear selection popover before opening thread popover
+        // (prevents stale selection popover from reappearing after thread popover closes)
+        onBeforePopoverOpen?.();
+        activeThreadId = threadId;
+        const thread = getThreads().find((t) => t.id === threadId);
+        if (thread) {
+            popoverPosition = { x: event.clientX + 16, y: event.clientY };
+            popoverThreadId = threadId;
+        }
+    }
+    /**
+     * Handle thread selection from the comment sidebar.
+     */
+    function handleSidebarThreadSelect(threadId) {
+        const thread = getThreads().find((t) => t.id === threadId);
+        if (!thread)
+            return;
+        // Clear selection popover before opening thread popover
+        onBeforePopoverOpen?.();
+        activeThreadId = threadId;
+        scrollToThread(threadId);
+        selectTimeoutId = setTimeout(() => {
+            selectTimeoutId = null;
+            const view = getEditorView();
+            if (view && thread.anchor.from !== undefined) {
+                const coords = view.coordsAtPos(thread.anchor.from);
+                if (coords) {
+                    popoverPosition = { x: coords.left + 16, y: coords.top };
+                    popoverThreadId = threadId;
+                }
+            }
+        }, POSITION_DELAY_MS);
+    }
+    // Thread CRUD
+    function createThread(body, authorId, selection) {
+        if (!selection || selection.from === selection.to) {
+            devWarn('Cannot create thread: no text selected');
+            return null;
+        }
+        if (getMode() === 'readonly') {
+            devWarn('Cannot create thread: editor is readonly');
+            return null;
+        }
+        const view = getEditorView();
+        if (!view) {
+            devWarn('Cannot create thread: editor view not available');
+            return null;
+        }
+        const { from, to } = selection;
+        const anchor = buildAnchorFromSelection(view, from, to);
+        const mentions = extractMentions(body);
+        const requestId = generateId();
+        const event = {
+            requestId,
+            anchor,
+            body,
+            authorId,
+            mentions: mentions.length > 0 ? mentions : undefined,
+        };
+        onthreadcreate?.(event);
+        announce('Comment added');
+        return requestId;
+    }
+    function createDocumentThread(body, authorId) {
+        if (getMode() === 'readonly') {
+            devWarn('Cannot create thread: editor is readonly');
+            return null;
+        }
+        const anchor = createDocumentAnchor();
+        const mentions = extractMentions(body);
+        const requestId = generateId();
+        const event = {
+            requestId,
+            anchor,
+            body,
+            authorId,
+            mentions: mentions.length > 0 ? mentions : undefined,
+        };
+        onthreadcreate?.(event);
+        announce('Document comment added');
+        return requestId;
+    }
+    function createBlockThread(body, authorId) {
+        if (getMode() === 'readonly') {
+            devWarn('Cannot create block thread: editor is readonly');
+            return null;
+        }
+        const view = getEditorView();
+        if (!view) {
+            devWarn('Cannot create block thread: editor view not available');
+            return null;
+        }
+        const { from } = view.state.selection;
+        const resolvedPos = view.state.doc.resolve(from);
+        for (let depth = resolvedPos.depth; depth > 0; depth--) {
+            const node = resolvedPos.node(depth);
+            if (!node.isBlock)
+                continue;
+            const blockFrom = resolvedPos.start(depth);
+            const blockTo = resolvedPos.end(depth);
+            const anchor = buildAnchorFromSelection(view, blockFrom, blockTo);
+            const mentions = extractMentions(body);
+            const requestId = generateId();
+            onthreadcreate?.({
+                requestId,
+                anchor,
+                body,
+                authorId,
+                mentions: mentions.length > 0 ? mentions : undefined,
+            });
+            return requestId;
+        }
+        devWarn('Cannot create block thread: cursor not inside a block');
+        return null;
+    }
+    function deleteThread(threadId) {
+        if (getMode() === 'readonly')
+            return;
+        const thread = getThreads().find((t) => t.id === threadId);
+        if (!thread)
+            return;
+        onthreaddelete?.({ threadId });
+    }
+    function clearAllThreads() {
+        if (getMode() === 'readonly')
+            return;
+        const threads = getThreads();
+        if (threads.length === 0)
+            return;
+        for (const thread of threads) {
+            onthreaddelete?.({ threadId: thread.id });
+        }
+        popoverThreadId = null;
+        popoverPosition = null;
+        activeThreadId = null;
+        announce('All comments cleared');
+    }
+    // Comment CRUD
+    function createComment(threadId, body, authorId) {
+        if (getMode() === 'readonly')
+            return null;
+        const thread = getThreads().find((t) => t.id === threadId);
+        if (!thread)
+            return null;
+        const mentions = extractMentions(body);
+        const requestId = generateId();
+        oncommentcreate?.({
+            requestId,
+            threadId,
+            body,
+            authorId,
+            mentions: mentions.length > 0 ? mentions : undefined,
+        });
+        announce('Comment added');
+        return requestId;
+    }
+    function updateComment(threadId, commentId, body) {
+        if (getMode() === 'readonly')
+            return;
+        const thread = getThreads().find((t) => t.id === threadId);
+        const comment = thread?.comments.find((c) => c.id === commentId);
+        if (!comment || comment.deletedAt)
+            return;
+        const mentions = extractMentions(body);
+        oncommentupdate?.({
+            threadId,
+            commentId,
+            body,
+            mentions: mentions.length > 0 ? mentions : undefined,
+        });
+    }
+    function deleteComment(threadId, commentId, soft = true) {
+        if (getMode() === 'readonly')
+            return;
+        const thread = getThreads().find((t) => t.id === threadId);
+        const comment = thread?.comments.find((c) => c.id === commentId);
+        if (!comment || (soft && comment.deletedAt))
+            return;
+        oncommentdelete?.({ threadId, commentId, soft });
+        announce('Comment deleted');
+    }
+    // Popover handlers
+    function handlePopoverClose() {
+        closePopover();
+    }
+    function handlePopoverDelete(threadId) {
+        const currentUserId = getCurrentUserId();
+        if (currentUserId) {
+            deleteThread(threadId);
+            closePopover();
+        }
+    }
+    function handlePopoverCommentCreate(threadId, body) {
+        const currentUserId = getCurrentUserId();
+        if (currentUserId) {
+            createComment(threadId, body, currentUserId);
+        }
+    }
+    function handlePopoverCommentUpdate(threadId, commentId, body) {
+        updateComment(threadId, commentId, body);
+    }
+    function handlePopoverCommentDelete(threadId, commentId) {
+        deleteComment(threadId, commentId);
+    }
+    function destroy() {
+        if (selectTimeoutId !== null) {
+            clearTimeout(selectTimeoutId);
+            selectTimeoutId = null;
+        }
+    }
+    return {
+        // Popover state
+        get popoverThreadId() {
+            return popoverThreadId;
+        },
+        get popoverPosition() {
+            return popoverPosition;
+        },
+        get popoverThread() {
+            return popoverThread;
+        },
+        get activeThreadId() {
+            return activeThreadId;
+        },
+        // Popover actions
+        openPopover,
+        closePopover,
+        handleAnchorClick,
+        handleSidebarThreadSelect,
+        // Thread CRUD
+        createThread,
+        createDocumentThread,
+        createBlockThread,
+        deleteThread,
+        clearAllThreads,
+        // Comment CRUD
+        createComment,
+        updateComment,
+        deleteComment,
+        // Popover handlers
+        handlePopoverClose,
+        handlePopoverDelete,
+        handlePopoverCommentCreate,
+        handlePopoverCommentUpdate,
+        handlePopoverCommentDelete,
+        // Utilities
+        scrollAnchorIntoView,
+        scrollToThread,
+        calculateViewportPosition,
+        // Cleanup
+        destroy,
+    };
+}

package/src/components/review-editor/review-editor.schema.ts

@@ -0,0 +1,88 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier for accessibility (required).',
+    },
+    original: {
+      type: 'string',
+      description: 'Original/baseline content for diff comparison.',
+    },
+    value: {
+      type: 'string',
+      description: 'Current markdown content (two-way bindable).',
+    },
+    mode: {
+      enum: ['edit', 'readonly'],
+      description: 'Editor mode.',
+    },
+    currentUserId: {
+      type: 'string',
+      description: 'Current user ID for permissions.',
+    },
+    placeholder: {
+      type: 'string',
+      description: 'Placeholder text when empty.',
+    },
+    name: {
+      type: 'string',
+      description: 'Form field name prefix for hidden inputs (enables form participation).',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional CSS classes.',
+    },
+    snapshotMode: {
+      type: 'boolean',
+      description:
+        'Snapshot mode for visual regression testing.\n\nWhen `true`:\n- Applies `caret-color: transparent` and `user-select: none` to the editor\n  root via a `data-snapshot-mode` attribute, producing a stable visual\n  state (no blinking cursor, no selection highlights).\n- Blurs any focused element inside the component on mount so the initial\n  screenshot does not capture a focused ring or active caret.\n- The inner MarkdownEditor instance also receives `snapshotMode={true}`.\n\nThis is a purely visual / CSS concern. It does NOT affect editability,\nProseMirror state, or any prop controlled by `readonly` / `mode`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['id'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'onchange',
+        reason: 'function-or-snippet',
+        description: 'Called when content changes.',
+      },
+      {
+        name: 'oncommentcreate',
+        reason: 'function-or-snippet',
+        description: 'Called when a comment is created in an existing thread.',
+      },
+      {
+        name: 'oncommentdelete',
+        reason: 'function-or-snippet',
+        description: 'Called when a comment is deleted.',
+      },
+      {
+        name: 'oncommentupdate',
+        reason: 'function-or-snippet',
+        description: 'Called when a comment is updated.',
+      },
+      {
+        name: 'onthreadcreate',
+        reason: 'function-or-snippet',
+        description: 'Called when user initiates thread creation.',
+      },
+      {
+        name: 'onthreaddelete',
+        reason: 'function-or-snippet',
+        description: 'Called when a thread is deleted.',
+      },
+      {
+        name: 'threads',
+        reason: 'unknown-shape',
+        description: 'Comment threads (two-way bindable).',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

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

@@ -0,0 +1,18 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import ReviewEditorImplementation from './review-editor-impl.svelte';
+let { class: customClassName, original = $bindable(''), value = $bindable(''), threads = $bindable([]), ...rest } = $props();
+const mergedClassName = $derived(classNames(customClassName));
+</script>
+
+<ReviewEditorImplementation
+  class={mergedClassName}
+  bind:original
+  bind:value
+  bind:threads
+  {...rest}
+/>

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

@@ -0,0 +1,92 @@
+/**
+ * Shared types for ReviewEditor modules (DEP-422).
+ *
+ * @module
+ */
+
+import type {
+  CommentCreateEvent,
+  CommentDeleteEvent,
+  CommentUpdateEvent,
+  Thread,
+  ThreadCreateEvent,
+  ThreadDeleteEvent,
+} from '@lostgradient/cinder/commentary/comments';
+
+/** Review editor mode: edit allows full editing, readonly is view-only. */
+export type ReviewMode = 'edit' | 'readonly';
+
+/** Available review document views. */
+export type ReviewEditorViewType = 'editor' | 'diff' | 'summary';
+
+/** Available diff rendering modes in the review editor. */
+export type ReviewEditorDiffViewMode = 'unified' | 'final' | 'original';
+
+/** FormData structure returned by getFormData(). */
+export type ReviewFormData = {
+  /** Original/baseline content. */
+  original: string;
+  /** Current edited content. */
+  current: string;
+  /** Serialized comment threads as JSON. */
+  comments: string;
+  /** Unified diff between original and current. */
+  diff: string;
+  /** LLM-optimized summary markdown. */
+  summary: string;
+};
+
+export type ReviewEditorProps = {
+  /** Unique identifier for accessibility (required). */
+  id: string;
+  /** Original/baseline content for diff comparison. */
+  original?: string;
+  /** Current markdown content (two-way bindable). */
+  value?: string;
+  /** Comment threads (two-way bindable). */
+  threads?: Thread[];
+  /** Editor mode. */
+  mode?: ReviewMode;
+  /** Current user ID for permissions. */
+  currentUserId?: string | undefined;
+  /** Placeholder text when empty. */
+  placeholder?: string;
+  /** Form field name prefix for hidden inputs (enables form participation). */
+  name?: string;
+  /** Additional CSS classes. */
+  class?: string;
+  /** Called when content changes. */
+  onchange?: (value: string) => void;
+  /** Called when user initiates thread creation. */
+  onthreadcreate?: (event: ThreadCreateEvent) => void;
+  /** Called when a thread is deleted. */
+  onthreaddelete?: (event: ThreadDeleteEvent) => void;
+  /** Called when a comment is created in an existing thread. */
+  oncommentcreate?: (event: CommentCreateEvent) => void;
+  /** Called when a comment is updated. */
+  oncommentupdate?: (event: CommentUpdateEvent) => void;
+  /** Called when a comment is deleted. */
+  oncommentdelete?: (event: CommentDeleteEvent) => void;
+
+  /**
+   * Snapshot mode for visual regression testing.
+   *
+   * When `true`:
+   * - Applies `caret-color: transparent` and `user-select: none` to the editor
+   *   root via a `data-snapshot-mode` attribute, producing a stable visual
+   *   state (no blinking cursor, no selection highlights).
+   * - Blurs any focused element inside the component on mount so the initial
+   *   screenshot does not capture a focused ring or active caret.
+   * - The inner MarkdownEditor instance also receives `snapshotMode={true}`.
+   *
+   * This is a purely visual / CSS concern. It does NOT affect editability,
+   * ProseMirror state, or any prop controlled by `readonly` / `mode`.
+   */
+  snapshotMode?: boolean;
+};
+
+/** Position for fixed-position popovers (viewport-relative coordinates) */
+export interface PopoverPosition {
+  x: number;
+  y: number;
+}

package/src/components/review-editor/review-editor.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;