@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/review-editor/focus-navigation.ts

@@ -0,0 +1,220 @@
+/**
+ * F6 Landmark Navigation Utility
+ *
+ * Implements the F6 keyboard navigation pattern for cycling focus between
+ * landmark regions. This is a Windows accessibility pattern that has been
+ * widely adopted by web applications for navigating between major UI sections.
+ *
+ * The F6 key cycles forward through regions, and Shift+F6 cycles backward.
+ *
+ * @example
+ * ```ts
+ * const regions: FocusRegion[] = [
+ *   { id: 'editor', selector: '.editor-content', label: 'Editor' },
+ *   { id: 'sidebar', selector: '.comment-sidebar', label: 'Comments' },
+ *   { id: 'popover', selector: '.thread-popover', label: 'Thread' },
+ * ];
+ *
+ * const navigator = createFocusRegionNavigator(regions);
+ *
+ * function handleKeyDown(event: KeyboardEvent) {
+ *   if (event.key === 'F6') {
+ *     event.preventDefault();
+ *     const container = event.currentTarget as HTMLElement;
+ *     const current = navigator.getCurrentRegion(container);
+ *     const next = navigator.getNextRegion(current, event.shiftKey);
+ *     navigator.focusRegion(container, next);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Defines a focusable region for F6 navigation.
+ */
+export interface FocusRegion {
+  /** Unique identifier for the region */
+  id: string;
+  /** CSS selector to find the region element within a container */
+  selector: string;
+  /** Human-readable label for the region (used for announcements) */
+  label: string;
+}
+
+/**
+ * Options for creating a focus region navigator.
+ */
+export interface FocusRegionNavigatorOptions {
+  /**
+   * Callback to determine if a region should be included in the navigation cycle.
+   * Use this to conditionally exclude regions (e.g., exclude 'popover' when closed).
+   *
+   * @param region - The region to check
+   * @returns true if the region should be navigable, false to skip it
+   */
+  isRegionActive?: (region: FocusRegion) => boolean;
+
+  /**
+   * Custom focus handler for specific regions.
+   * Use this when a region requires special focus logic (e.g., focusing a ProseMirror editor).
+   *
+   * @param region - The region being focused
+   * @param container - The scoping container element
+   * @returns true if focus was handled, false to use default behavior
+   */
+  customFocusHandler?: (region: FocusRegion, container: HTMLElement) => boolean;
+}
+
+/**
+ * Navigator interface returned by createFocusRegionNavigator.
+ */
+export interface FocusRegionNavigator {
+  /**
+   * Get the currently focused region based on document.activeElement.
+   *
+   * @param container - The container element to scope the check within.
+   *   This supports multiple navigator instances on the same page.
+   * @returns The current region, or null if focus is outside all regions
+   */
+  getCurrentRegion(container: HTMLElement): FocusRegion | null;
+
+  /**
+   * Get the next region in the navigation cycle.
+   *
+   * @param current - The current region (or null if none focused)
+   * @param reverse - If true, navigate backward (Shift+F6)
+   * @returns The next region to focus
+   */
+  getNextRegion(current: FocusRegion | null, reverse?: boolean): FocusRegion;
+
+  /**
+   * Focus the first focusable element within a region.
+   *
+   * @param container - The container element to scope the query within
+   * @param region - The region to focus
+   */
+  focusRegion(container: HTMLElement, region: FocusRegion): void;
+
+  /**
+   * Get all currently active regions (respecting isRegionActive filter).
+   *
+   * @returns Array of active regions
+   */
+  getActiveRegions(): FocusRegion[];
+}
+
+/**
+ * Standard focusable element selector.
+ * Matches interactive elements that can receive keyboard focus.
+ */
+const FOCUSABLE_SELECTOR =
+  'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Create a focus region navigator for F6 landmark navigation.
+ *
+ * @param regions - Array of focus regions in navigation order
+ * @param options - Optional configuration
+ * @returns Navigator with methods for region navigation
+ */
+export function createFocusRegionNavigator(
+  regions: FocusRegion[],
+  options: FocusRegionNavigatorOptions = {},
+): FocusRegionNavigator {
+  const { isRegionActive, customFocusHandler } = options;
+
+  /**
+   * Get the list of currently active regions.
+   */
+  function getActiveRegions(): FocusRegion[] {
+    if (!isRegionActive) {
+      return regions;
+    }
+    return regions.filter(isRegionActive);
+  }
+
+  function getFallbackRegion(): FocusRegion {
+    const firstRegion = regions[0];
+    if (!firstRegion) {
+      throw new Error('createFocusRegionNavigator requires at least one focus region.');
+    }
+    return firstRegion;
+  }
+
+  /**
+   * Get the current region based on document.activeElement.
+   */
+  function getCurrentRegion(container: HTMLElement): FocusRegion | null {
+    const active = document.activeElement;
+    if (!active || !container.contains(active)) {
+      return null;
+    }
+
+    // Check each region to see if it contains the active element
+    for (const region of regions) {
+      const element = container.querySelector(region.selector);
+      if (element?.contains(active)) {
+        return region;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get the next region in the cycle.
+   */
+  function getNextRegion(current: FocusRegion | null, reverse = false): FocusRegion {
+    const activeRegions = getActiveRegions();
+
+    // If no regions active, return the first defined region
+    if (activeRegions.length === 0) {
+      return getFallbackRegion();
+    }
+
+    // If no current region, return the first active region
+    if (!current) {
+      return activeRegions[0] ?? getFallbackRegion();
+    }
+
+    // Find current region's index in the active list
+    const currentIndex = activeRegions.findIndex((r) => r.id === current.id);
+
+    // If current region is not in active list (e.g., just became inactive),
+    // return the first active region
+    if (currentIndex === -1) {
+      return activeRegions[0] ?? getFallbackRegion();
+    }
+
+    // Calculate next index with wrap-around
+    const nextIndex = reverse
+      ? (currentIndex - 1 + activeRegions.length) % activeRegions.length
+      : (currentIndex + 1) % activeRegions.length;
+
+    return activeRegions[nextIndex] ?? getFallbackRegion();
+  }
+
+  /**
+   * Focus the first focusable element within a region.
+   */
+  function focusRegion(container: HTMLElement, region: FocusRegion): void {
+    // Try custom handler first
+    if (customFocusHandler?.(region, container)) {
+      return;
+    }
+
+    // Default behavior: find the region element and focus first focusable child
+    const element = container.querySelector(region.selector);
+    if (element instanceof HTMLElement) {
+      const focusable = element.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
+      (focusable ?? element).focus();
+    }
+  }
+
+  return {
+    getCurrentRegion,
+    getNextRegion,
+    focusRegion,
+    getActiveRegions,
+  };
+}

package/src/components/review-editor/front-matter-fields.svelte

@@ -0,0 +1,159 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { parseFrontMatter, validateFrontMatter } from '@lostgradient/cinder/markdown/pipeline';
+import Checkbox from '../checkbox/checkbox.svelte';
+import Input from '../input/input.svelte';
+import Textarea from '../textarea/textarea.svelte';
+import { parseYamlFieldValue, serializeYamlFieldValue } from './review-editor-front-matter.ts';
+let { id, data, raw, readonly = false, onchange } = $props();
+const entries = $derived(Object.entries(data ?? {}));
+const hasParsedFields = $derived(data !== null && entries.length > 0);
+const shouldShowRawYaml = $derived(!hasParsedFields && raw !== null);
+let rawDraft = $state(untrack(() => raw) ?? '');
+let rawError = $state();
+let lastRaw = $state(null);
+let complexDrafts = $state({});
+let complexErrors = $state({});
+let lastComplexKeys = $state('');
+$effect(() => {
+    if (raw !== lastRaw) {
+        rawDraft = raw ?? '';
+        rawError = validateFrontMatter(rawDraft).error;
+        lastRaw = raw;
+    }
+});
+$effect(() => {
+    const complexEntries = entries.filter(([, value]) => isComplexValue(value));
+    const key = complexEntries
+        .map(([name, value]) => `${name}:${serializeYamlFieldValue(value)}`)
+        .join('|');
+    if (key === lastComplexKeys)
+        return;
+    const nextDrafts = {};
+    for (const [name, value] of complexEntries) {
+        nextDrafts[name] = serializeYamlFieldValue(value);
+    }
+    complexDrafts = nextDrafts;
+    complexErrors = {};
+    lastComplexKeys = key;
+});
+function patchField(name, value) {
+    if (readonly)
+        return;
+    onchange({ ...(data ?? {}), [name]: value });
+}
+function handleNumberInput(name, rawValue) {
+    if (rawValue.trim() === '') {
+        patchField(name, null);
+        return;
+    }
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed))
+        return;
+    patchField(name, parsed);
+}
+function handleComplexInput(name, rawValue) {
+    complexDrafts = { ...complexDrafts, [name]: rawValue };
+    const parsed = parseYamlFieldValue(rawValue);
+    if (!parsed.valid) {
+        complexErrors = { ...complexErrors, [name]: parsed.error };
+        return;
+    }
+    const nextErrors = { ...complexErrors };
+    delete nextErrors[name];
+    complexErrors = nextErrors;
+    patchField(name, parsed.value);
+}
+function handleRawInput(rawValue) {
+    rawDraft = rawValue;
+    const validation = validateFrontMatter(rawValue);
+    rawError = validation.error;
+    if (!validation.valid || readonly)
+        return;
+    const parsed = parseFrontMatter(`---\n${rawValue}\n---\n`);
+    onchange(parsed.data);
+}
+function fieldId(name) {
+    return `${id}-${name.replace(/[^a-zA-Z0-9_-]/g, '-')}`;
+}
+function isComplexValue(value) {
+    return typeof value === 'object' && value !== null;
+}
+</script>
+
+<section class="review-editor-front-matter" aria-labelledby={`${id}-heading`}>
+  <div class="review-editor-front-matter__header">
+    <h3 id={`${id}-heading`} class="review-editor-front-matter__title">Front matter</h3>
+  </div>
+
+  <div class="review-editor-front-matter__body">
+    {#if hasParsedFields}
+      {#each entries as [name, fieldValue] (name)}
+        <div class="review-editor-front-matter__field">
+          {#if typeof fieldValue === 'boolean'}
+            <Checkbox
+              id={fieldId(name)}
+              label={name}
+              checked={fieldValue}
+              disabled={readonly}
+              onchange={(event) => patchField(name, event.currentTarget.checked)}
+            />
+          {:else if typeof fieldValue === 'number'}
+            <Input
+              id={fieldId(name)}
+              label={name}
+              value={String(fieldValue)}
+              disabled={readonly}
+              oninput={(event) => handleNumberInput(name, event.currentTarget.value)}
+            />
+          {:else if typeof fieldValue === 'string'}
+            <Input
+              id={fieldId(name)}
+              label={name}
+              value={fieldValue}
+              disabled={readonly}
+              oninput={(event) => patchField(name, event.currentTarget.value)}
+            />
+          {:else if isComplexValue(fieldValue)}
+            <Textarea
+              id={fieldId(name)}
+              label={name}
+              value={complexDrafts[name] ?? serializeYamlFieldValue(fieldValue)}
+              error={complexErrors[name] ?? ''}
+              disabled={readonly}
+              rows={Math.max(
+                3,
+                (complexDrafts[name] ?? serializeYamlFieldValue(fieldValue)).split('\n').length,
+              )}
+              oninput={(event) => handleComplexInput(name, event.currentTarget.value)}
+            />
+          {:else}
+            <Input
+              id={fieldId(name)}
+              label={name}
+              value={fieldValue === null ? 'null' : String(fieldValue)}
+              disabled={readonly}
+              oninput={(event) => patchField(name, event.currentTarget.value)}
+            />
+          {/if}
+        </div>
+      {/each}
+    {:else if shouldShowRawYaml}
+      <Textarea
+        id={`${id}-raw`}
+        label="YAML"
+        value={rawDraft}
+        error={rawError ?? ''}
+        disabled={readonly}
+        rows={Math.max(3, rawDraft.split('\n').length)}
+        oninput={(event) => handleRawInput(event.currentTarget.value)}
+      />
+    {:else}
+      <p class="review-editor-front-matter__empty">No front matter fields.</p>
+    {/if}
+  </div>
+</section>

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

@@ -0,0 +1,59 @@
+import './review-editor.css';
+import ReviewEditor from './review-editor.svelte';
+
+export default ReviewEditor;
+export type {
+  CommentAnchor,
+  PersistedThread,
+  ReviewState,
+  Thread,
+} from '@lostgradient/cinder/commentary/comments';
+export { ReviewEditor };
+
+// DEP-422: Shared types
+export type {
+  PopoverPosition,
+  ReviewEditorDiffViewMode,
+  ReviewEditorProps,
+  ReviewEditorViewType,
+  ReviewFormData,
+  ReviewMode,
+} from './review-editor.types.ts';
+
+// DEP-422: Extracted runes modules for state management (experimental)
+export { createReviewEditorState } from './review-editor-state.svelte';
+export type {
+  DiffStats,
+  ReviewEditorState,
+  ReviewEditorStateOptions,
+} from './review-editor-state.svelte';
+
+export { createThreadManager } from './review-editor-threads.svelte';
+export type { ThreadManager, ThreadManagerOptions } from './review-editor-threads.svelte';
+
+export type { SelectionPopover, SelectionPopoverOptions } from './review-editor-selection-types.ts';
+export { createSelectionPopover } from './review-editor-selection.svelte';
+
+export { createAnchorManager, toPersistedThreads } from './review-editor-anchors.svelte';
+export type { AnchorManager, AnchorManagerOptions } from './review-editor-anchors.svelte';
+
+// DEP-422: Pure export utilities
+export {
+  buildFormData,
+  buildFormDataFromValues,
+  exportCommentsMarkdown,
+  exportMarkdownSummary,
+  exportUnifiedDiff,
+  getSummaryContentWithoutHeading,
+} from './review-editor-exports';
+export type { ReviewFormData as ExportedReviewFormData } from './review-editor-exports';
+
+// DEP-48: Export actions for clipboard export
+export { default as ExportActions } from './export-actions.svelte';
+
+// Thread UI components (for standalone use)
+export { default as ThreadPopover } from './thread-popover.svelte';
+
+export { default as CommentList } from './comment-list.svelte';
+
+export { default as CommentComposer } from './comment-composer.svelte';

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

@@ -0,0 +1,109 @@
+<script lang="ts" module>
+/**
+ * LiveRegion component for screen reader announcements (DEP-47).
+ *
+ * This component provides accessible announcements for the ReviewEditor.
+ * It uses an ARIA live region to communicate state changes to screen readers.
+ *
+ * Verbosity level: Standard (actions + navigation)
+ * - Comment CRUD operations
+ * - Thread state changes (resolved/reopened)
+ * - Suggestion accept/reject
+ * - Focus region changes
+ * - Popover open/close
+ */
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { class: className } = $props();
+// Current message to announce
+let message = $state('');
+let priority = $state('polite');
+let clearTimeoutId = null;
+/**
+ * Version counter for invalidating stale async callbacks.
+ *
+ * Each announce() call increments this counter. Microtasks and timeouts
+ * capture the version at schedule time and check it before updating state.
+ * This prevents orphaned callbacks from clearing messages prematurely when
+ * announce() is called multiple times in rapid succession.
+ */
+let announceVersion = 0;
+/**
+ * Track component destruction to prevent state updates after unmount.
+ *
+ * All async operations (queueMicrotask, setTimeout) check this flag before
+ * updating state. The $effect cleanup also clears pending timeouts as a
+ * belt-and-suspenders approach.
+ */
+let isDestroyed = false;
+// Cleanup on component destruction: clear pending timeout and set flag
+$effect(() => {
+    return () => {
+        isDestroyed = true;
+        if (clearTimeoutId) {
+            clearTimeout(clearTimeoutId);
+            clearTimeoutId = null;
+        }
+    };
+});
+/**
+ * Announce a message to screen readers.
+ *
+ * @param text - The message to announce
+ * @param announcePriority - 'polite' (default) waits for current speech to finish,
+ *                          'assertive' interrupts immediately
+ */
+export function announce(text, announcePriority = 'polite') {
+    // Prevent announcements after component destruction
+    if (isDestroyed)
+        return;
+    // Increment version to invalidate any pending microtasks/timeouts from previous calls
+    const version = ++announceVersion;
+    // Clear any pending timeout
+    if (clearTimeoutId) {
+        clearTimeout(clearTimeoutId);
+        clearTimeoutId = null;
+    }
+    // Force re-announcement by clearing first (needed for repeated messages)
+    message = '';
+    priority = announcePriority;
+    // Use microtask to ensure DOM updates between clear and set
+    queueMicrotask(() => {
+        // Guard against destruction or superseded calls during microtask
+        if (isDestroyed || announceVersion !== version)
+            return;
+        message = text;
+        // Clear after announcement (1s is enough for most screen readers)
+        clearTimeoutId = setTimeout(() => {
+            // Guard against destruction or superseded calls during timeout
+            if (isDestroyed || announceVersion !== version)
+                return;
+            message = '';
+            clearTimeoutId = null;
+        }, 1000);
+    });
+}
+</script>
+
+<!--
+  Using two regions: one for polite, one for assertive.
+  This ensures the correct aria-live value is always used.
+  The visually hidden class ensures screen readers can access it.
+-->
+{#if priority === 'polite'}
+  <div role="status" aria-live="polite" aria-atomic="true" class={classNames('sr-only', className)}>
+    {message}
+  </div>
+{:else}
+  <div
+    role="alert"
+    aria-live="assertive"
+    aria-atomic="true"
+    class={classNames('sr-only', className)}
+  >
+    {message}
+  </div>
+{/if}