@lostgradient/cinder 0.5.0 → 0.6.0

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

@@ -1,220 +0,0 @@
-/**
- * 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

@@ -1,176 +0,0 @@
-<script lang="ts" module>
-  export type FrontMatterFieldsProps = {
-    id: string;
-    data: Record<string, unknown> | null;
-    raw: string | null;
-    readonly?: boolean;
-    onchange: (data: Record<string, unknown> | null) => void;
-  };
-</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 }: FrontMatterFieldsProps = $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<string | undefined>();
-  let lastRaw = $state<string | null>(null);
-  let complexDrafts = $state<Record<string, string>>({});
-  let complexErrors = $state<Record<string, string | undefined>>({});
-  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: Record<string, string> = {};
-    for (const [name, value] of complexEntries) {
-      nextDrafts[name] = serializeYamlFieldValue(value);
-    }
-    complexDrafts = nextDrafts;
-    complexErrors = {};
-    lastComplexKeys = key;
-  });
-
-  function patchField(name: string, value: unknown): void {
-    if (readonly) return;
-    onchange({ ...(data ?? {}), [name]: value });
-  }
-
-  function handleNumberInput(name: string, rawValue: string): void {
-    if (rawValue.trim() === '') {
-      patchField(name, null);
-      return;
-    }
-
-    const parsed = Number(rawValue);
-    if (!Number.isFinite(parsed)) return;
-    patchField(name, parsed);
-  }
-
-  function handleComplexInput(name: string, rawValue: string): void {
-    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: string): void {
-    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: string): string {
-    return `${id}-${name.replace(/[^a-zA-Z0-9_-]/g, '-')}`;
-  }
-
-  function isComplexValue(value: unknown): boolean {
-    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

@@ -1,59 +0,0 @@
-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

@@ -1,125 +0,0 @@
-<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 type AnnouncementPriority = 'polite' | 'assertive';
-
-  export type LiveRegionProps = {
-    /** Optional CSS class */
-    class?: string;
-  };
-</script>
-
-<script lang="ts">
-  import { classNames } from '../../utilities/class-names.ts';
-
-  let { class: className }: LiveRegionProps = $props();
-
-  // Current message to announce
-  let message = $state('');
-  let priority = $state<AnnouncementPriority>('polite');
-  let clearTimeoutId: ReturnType<typeof setTimeout> | null = 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: string, announcePriority: AnnouncementPriority = 'polite'): void {
-    // 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}