@lostgradient/cinder 0.1.0

package/src/utilities/attachments.ts

@@ -0,0 +1,195 @@
+import type { Attachment } from 'svelte/attachments';
+import { lockBodyScroll } from '../_internal/overlay.ts';
+
+/**
+ * Creates a body scroll lock attachment that participates in the shared
+ * counted lock from `_internal/overlay.ts`. Nested overlays each call this;
+ * the page scroll is only restored when the last attachment is torn down.
+ *
+ * Use this instead of a raw `overflow: hidden` assignment so that a Modal
+ * opened inside a Sheet (or any combination of locking overlays) cannot
+ * prematurely restore page scroll when only one of them closes.
+ *
+ * @example
+ * ```svelte
+ * <div {@attach createBodyScrollLock()}>Modal content</div>
+ * ```
+ */
+export function createBodyScrollLock(): Attachment<HTMLElement> {
+  return () => {
+    const release = lockBodyScroll();
+    return release;
+  };
+}
+
+/** Pointer/click events the outside-dismiss listener can key off. */
+export type ClickOutsideEventType = 'click' | 'pointerdown' | 'mousedown';
+
+export type ClickOutsideOptions = {
+  /** Callback when an outside interaction occurs */
+  handler: () => void;
+  /** Whether the attachment is enabled — accepts a getter to stay reactive (default: true) */
+  enabled?: boolean | (() => boolean);
+  /**
+   * Which document event triggers the outside check (default: `'click'`). Overlays that must
+   * dismiss before a focus/selection change commits use `'pointerdown'` (or `'mousedown'`),
+   * which fire ahead of `'click'`.
+   */
+  eventType?: ClickOutsideEventType;
+  /**
+   * Whether to listen in the capture phase (default: `true`). Capture sees the event before
+   * inner stopPropagation can swallow it — the right default for a document-level dismisser.
+   */
+  capture?: boolean;
+  /**
+   * Additional elements that count as "inside" — a target within any of these (or the attach
+   * node) does NOT trigger the handler. Each entry is a getter so a trigger/anchor that mounts
+   * or swaps after the attachment is created still resolves freshly on each event. Returning
+   * `null` skips that ref.
+   */
+  ignoreRefs?: Array<() => Element | null>;
+};
+
+/**
+ * Creates an outside-interaction attachment that calls a handler when a `click`, `pointerdown`,
+ * or `mousedown` lands outside the attached element (and outside any `ignoreRefs`). This is the
+ * single canonical mechanism for overlay light-dismiss — dropdowns, menus, popovers — so each
+ * overlay does not hand-roll its own `document` listener and inside/trigger exclusion (see
+ * `OVERLAY-POLICY.md` § Outside-click).
+ *
+ * @example
+ * ```svelte
+ * <div {@attach createClickOutside({ handler: () => isOpen = false, enabled: () => isOpen })}>
+ *   Dropdown content
+ * </div>
+ * ```
+ *
+ * @example With a separate trigger that must not count as outside, dismissing on pointerdown:
+ * ```svelte
+ * <div {@attach createClickOutside({
+ *   handler: close,
+ *   enabled: () => open,
+ *   eventType: 'pointerdown',
+ *   ignoreRefs: [() => triggerElement],
+ * })}>...</div>
+ * ```
+ */
+export function createClickOutside(options: ClickOutsideOptions): Attachment<HTMLElement> {
+  const { handler, enabled = true, eventType = 'click', capture = true, ignoreRefs } = options;
+
+  return (node: HTMLElement) => {
+    // All three event types (click, pointerdown, mousedown) produce MouseEvent or its
+    // subtype PointerEvent — typing as MouseEvent is accurate and preserves mouse properties
+    // should the handler or future callers need them.
+    function handleEvent(event: MouseEvent) {
+      const isEnabled = typeof enabled === 'function' ? enabled() : enabled;
+      if (!isEnabled) return;
+      const target = event.target;
+      // A non-Node (or null) target is treated as outside the node.
+      if (!(target instanceof Node)) {
+        handler();
+        return;
+      }
+      if (node.contains(target)) return;
+      if (ignoreRefs) {
+        for (const ref of ignoreRefs) {
+          const element = ref();
+          if (element && element.contains(target)) return;
+        }
+      }
+      handler();
+    }
+
+    document.addEventListener(eventType, handleEvent, capture);
+
+    return () => {
+      document.removeEventListener(eventType, handleEvent, capture);
+    };
+  };
+}
+
+/**
+ * Marks scroll containers that have more content below the visible area.
+ * Intended for overlay bodies that show a bottom mask fade while scrollable.
+ */
+export function overflowFade(): Attachment<HTMLElement> {
+  return (node) => {
+    if (typeof ResizeObserver === 'undefined') {
+      node.removeAttribute('data-cinder-overflows');
+      return;
+    }
+
+    const update = () => {
+      const overflows = node.scrollHeight - node.clientHeight > 1;
+      const atBottom = node.scrollTop + node.clientHeight >= node.scrollHeight - 1;
+      node.toggleAttribute('data-cinder-overflows', overflows && !atBottom);
+    };
+
+    const requestFrame =
+      typeof requestAnimationFrame === 'function'
+        ? requestAnimationFrame
+        : (callback: FrameRequestCallback) => window.setTimeout(() => callback(performance.now()));
+    const cancelFrame =
+      typeof cancelAnimationFrame === 'function'
+        ? cancelAnimationFrame
+        : (handle: number) => window.clearTimeout(handle);
+
+    let frame = 0;
+    const scheduleUpdate = () => {
+      if (frame) return;
+      frame = requestFrame(() => {
+        frame = 0;
+        update();
+      });
+    };
+
+    const resizeObserver = new ResizeObserver(scheduleUpdate);
+    const observedElements = new Set<Element>();
+    const observeElement = (element: Element) => {
+      if (observedElements.has(element)) return;
+      resizeObserver.observe(element);
+      observedElements.add(element);
+    };
+    const syncObservedElements = () => {
+      const currentElements = new Set<Element>([node, ...node.querySelectorAll('*')]);
+      for (const element of observedElements) {
+        if (!currentElements.has(element)) {
+          resizeObserver.unobserve(element);
+          observedElements.delete(element);
+        }
+      }
+      for (const element of currentElements) {
+        observeElement(element);
+      }
+    };
+
+    syncObservedElements();
+
+    const mutationObserver =
+      typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver(() => {
+            syncObservedElements();
+            scheduleUpdate();
+          });
+
+    mutationObserver?.observe(node, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ['hidden', 'class', 'style', 'aria-hidden'],
+    });
+
+    node.addEventListener('scroll', scheduleUpdate, { passive: true });
+    update();
+
+    return () => {
+      if (frame) cancelFrame(frame);
+      resizeObserver.disconnect();
+      observedElements.clear();
+      mutationObserver?.disconnect();
+      node.removeEventListener('scroll', scheduleUpdate);
+    };
+  };
+}

package/src/utilities/change-tracker.svelte.ts

@@ -0,0 +1,207 @@
+/**
+ * Change tracker with lazy dirty flag and debounced verification (DEP-47).
+ *
+ * Uses three-tier detection:
+ * 1. Fast: Identical string check (O(1) for same reference, O(n) for comparison)
+ * 2. Lightweight: Length + hash check (O(n), no parsing)
+ * 3. Semantic: Full normalization (debounced, only when hash differs)
+ *
+ * This avoids per-keystroke normalize() calls which are expensive for large documents.
+ */
+
+import {
+  contentEquals,
+  contentEqualsWithFrontMatter,
+} from '@lostgradient/cinder/markdown/pipeline';
+
+export interface ChangeTrackerOptions {
+  /** Debounce delay for semantic comparison (ms). Default: 300 */
+  debounceMs?: number;
+  /** Whether to include front matter in comparison. Default: false */
+  includeFrontMatter?: boolean;
+}
+
+export interface ChangeTracker {
+  /** Whether content has changed from baseline (fast check + verified result) */
+  readonly hasChanges: boolean;
+  /** Whether semantic verification is still pending */
+  readonly isPending: boolean;
+  /** Set the baseline value (e.g., original document) */
+  setBaseline(value: string): void;
+  /** Set the current value (e.g., edited document) */
+  setCurrent(value: string): void;
+  /** Force immediate semantic verification (useful for save operations) */
+  verifyNow(): boolean;
+  /** Cleanup resources (call on component destroy) */
+  destroy(): void;
+}
+
+/**
+ * Fast non-cryptographic hash for change detection.
+ * Uses djb2 algorithm - fast and good distribution.
+ */
+function simpleHash(str: string): number {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * Create a change tracker for comparing baseline vs current content.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChangeTracker } from '../../utilities/change-tracker.svelte.ts';
+ *
+ *   const tracker = createChangeTracker({ debounceMs: 300 });
+ *
+ *   $effect(() => tracker.setBaseline(original));
+ *   $effect(() => tracker.setCurrent(value));
+ *
+ *   const hasChanges = $derived(tracker.hasChanges);
+ * </script>
+ * ```
+ */
+export function createChangeTracker(options: ChangeTrackerOptions = {}): ChangeTracker {
+  const { debounceMs = 300, includeFrontMatter = false } = options;
+
+  // Internal state
+  let baseline = $state('');
+  let current = $state('');
+  let baselineHash = $state<number>(0);
+  let currentHash = $state<number>(0);
+  let isPending = $state(false);
+  let semanticResult = $state<boolean | null>(null);
+  let verifyTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  // Fast dirty check (synchronous, cheap)
+  const isDirtyFast = $derived.by(() => {
+    // Identical reference or content
+    if (baseline === current) return false;
+    // Length mismatch is definitely dirty
+    if (baseline.length !== current.length) return true;
+    // Hash mismatch is likely dirty (verify async)
+    return currentHash !== baselineHash;
+  });
+
+  // Combined result: fast check OR pending verification result
+  const hasChanges = $derived.by(() => {
+    // Fast path: identical content
+    if (!isDirtyFast) return false;
+    // Use verified result if available
+    if (semanticResult !== null) return semanticResult;
+    // Assume dirty until verified (optimistic indicator)
+    return true;
+  });
+
+  /**
+   * Perform semantic verification using full normalization.
+   */
+  function doSemanticVerification(): void {
+    const equals = includeFrontMatter
+      ? contentEqualsWithFrontMatter(baseline, current)
+      : contentEquals(baseline, current);
+    semanticResult = !equals;
+    isPending = false;
+  }
+
+  /**
+   * Schedule debounced semantic verification.
+   *
+   * @param base - Baseline content to compare against
+   * @param curr - Current content to compare
+   * @param baseHash - Pre-computed hash of baseline
+   * @param currHash - Pre-computed hash of current
+   */
+  function scheduleVerification(
+    base: string,
+    curr: string,
+    baseHash: number,
+    currHash: number,
+  ): void {
+    // Clear pending verification
+    if (verifyTimeout) {
+      clearTimeout(verifyTimeout);
+      verifyTimeout = null;
+    }
+
+    // Reset semantic result when content changes
+    semanticResult = null;
+
+    // Skip if fast check says clean (identical strings)
+    if (base === curr) {
+      isPending = false;
+      return;
+    }
+
+    // Skip verification if hash matches (likely no semantic change)
+    if (baseHash === currHash && base.length === curr.length) {
+      // Hash collision possible but rare - verify anyway after short delay
+      isPending = true;
+      verifyTimeout = setTimeout(doSemanticVerification, debounceMs);
+      return;
+    }
+
+    // Schedule semantic verification
+    isPending = true;
+    verifyTimeout = setTimeout(doSemanticVerification, debounceMs);
+  }
+
+  // Watch for content changes and schedule verification.
+  // Dependencies are explicit via function arguments - Svelte tracks all four values
+  // because they're read to be passed as arguments.
+  $effect(() => {
+    scheduleVerification(baseline, current, baselineHash, currentHash);
+
+    return () => {
+      if (verifyTimeout) {
+        clearTimeout(verifyTimeout);
+        verifyTimeout = null;
+      }
+    };
+  });
+
+  return {
+    get hasChanges() {
+      return hasChanges;
+    },
+    get isPending() {
+      return isPending;
+    },
+    setBaseline(value: string) {
+      baseline = value;
+      baselineHash = simpleHash(value);
+      semanticResult = null;
+    },
+    setCurrent(value: string) {
+      current = value;
+      currentHash = simpleHash(value);
+      // Reset semantic result immediately to prevent stale values from being used
+      // before the $effect runs. Without this, hasChanges could briefly return
+      // the previous verification result when content changes.
+      semanticResult = null;
+    },
+    verifyNow(): boolean {
+      if (verifyTimeout) {
+        clearTimeout(verifyTimeout);
+        verifyTimeout = null;
+      }
+      if (baseline === current) {
+        isPending = false;
+        semanticResult = false;
+        return false;
+      }
+      doSemanticVerification();
+      return semanticResult ?? false;
+    },
+    destroy() {
+      if (verifyTimeout) {
+        clearTimeout(verifyTimeout);
+        verifyTimeout = null;
+      }
+    },
+  };
+}

package/src/utilities/class-names.ts

@@ -0,0 +1,9 @@
+/**
+ * Join truthy class-name strings, dropping falsy entries.
+ * Accepts any number of string | null | undefined | false inputs.
+ */
+export function classNames(...parts: Array<string | null | undefined | false>): string {
+  return parts
+    .filter((part): part is string => typeof part === 'string' && part.length > 0)
+    .join(' ');
+}

package/src/utilities/clipboard.ts

@@ -0,0 +1,51 @@
+/**
+ * Clipboard utility.
+ *
+ * Wraps `navigator.clipboard.writeText` with a defensive fallback that uses
+ * the deprecated-but-still-supported `document.execCommand('copy')` path.
+ * The fallback fires when:
+ *
+ * - `navigator.clipboard` is unavailable (older Safari, insecure contexts)
+ * - The native call rejects (permissions, focus issues)
+ *
+ * Returns a boolean: true if any path succeeded, false otherwise. Callers
+ * should reflect that to the user (e.g., flash an error icon on the button).
+ */
+
+/// <reference lib="dom" />
+
+/**
+ * Copy `text` to the clipboard. Prefers the modern Async Clipboard API and
+ * falls back to a contenteditable / `execCommand('copy')` shim for older
+ * browsers and edge cases.
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } catch {
+      // Fall through to the legacy path.
+    }
+  }
+  return legacyCopy(text);
+}
+
+function legacyCopy(text: string): boolean {
+  if (typeof document === 'undefined') return false;
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.setAttribute('readonly', '');
+  textarea.style.position = 'absolute';
+  textarea.style.left = '-9999px';
+  document.body.appendChild(textarea);
+  textarea.select();
+  let succeeded = false;
+  try {
+    succeeded = document.execCommand('copy');
+  } catch {
+    succeeded = false;
+  }
+  textarea.remove();
+  return succeeded;
+}

package/src/utilities/color-luminance.ts

@@ -0,0 +1,217 @@
+/**
+ * Color parsing and luminance utilities for swatch contrast computation.
+ *
+ * Supported input formats: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`,
+ * `rgb(r, g, b)`, `rgba(r, g, b, a)`, `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`.
+ * All other CSS color syntaxes are treated as opaque with best-effort `'white'` contrast.
+ */
+
+type RgbaComponents = { r: number; g: number; b: number; a: number };
+
+/** Parse a hex, rgb(a), or hsl(a) color string into RGBA components (0–255, alpha 0–1). */
+export function parseColor(input: string): RgbaComponents | null {
+  const trimmed = input.trim().toLowerCase();
+
+  // Hex formats
+  const hexMatch = trimmed.match(/^#([0-9a-f]{3,8})$/);
+  if (hexMatch) {
+    return parseHex(hexMatch[1]!);
+  }
+
+  // rgb / rgba
+  const rgbMatch = trimmed.match(/^rgba?\(\s*([^)]+)\)$/);
+  if (rgbMatch) {
+    return parseRgb(rgbMatch[1]!);
+  }
+
+  // hsl / hsla
+  const hslMatch = trimmed.match(/^hsla?\(\s*([^)]+)\)$/);
+  if (hslMatch) {
+    return parseHsl(hslMatch[1]!);
+  }
+
+  return null;
+}
+
+function parseHex(hex: string): RgbaComponents | null {
+  let r: number, g: number, b: number, a: number;
+
+  if (hex.length === 3) {
+    r = parseInt((hex[0] ?? '') + (hex[0] ?? ''), 16);
+    g = parseInt((hex[1] ?? '') + (hex[1] ?? ''), 16);
+    b = parseInt((hex[2] ?? '') + (hex[2] ?? ''), 16);
+    a = 1;
+  } else if (hex.length === 4) {
+    r = parseInt((hex[0] ?? '') + (hex[0] ?? ''), 16);
+    g = parseInt((hex[1] ?? '') + (hex[1] ?? ''), 16);
+    b = parseInt((hex[2] ?? '') + (hex[2] ?? ''), 16);
+    a = parseInt((hex[3] ?? '') + (hex[3] ?? ''), 16) / 255;
+  } else if (hex.length === 6) {
+    r = parseInt(hex.slice(0, 2), 16);
+    g = parseInt(hex.slice(2, 4), 16);
+    b = parseInt(hex.slice(4, 6), 16);
+    a = 1;
+  } else if (hex.length === 8) {
+    r = parseInt(hex.slice(0, 2), 16);
+    g = parseInt(hex.slice(2, 4), 16);
+    b = parseInt(hex.slice(4, 6), 16);
+    a = parseInt(hex.slice(6, 8), 16) / 255;
+  } else {
+    return null;
+  }
+
+  return { r, g, b, a };
+}
+
+function parseChannelValue(raw: string): number {
+  const trimmed = raw.trim();
+  // Reject slash-alpha syntax (e.g. "255 / 50%") — we only support comma-separated legacy syntax
+  if (trimmed.includes('/')) return NaN;
+  if (trimmed.endsWith('%')) {
+    return Math.max(0, Math.min(255, (parseFloat(trimmed) / 100) * 255));
+  }
+  return Math.max(0, Math.min(255, parseFloat(trimmed)));
+}
+
+function parseAlphaValue(raw: string): number {
+  const trimmed = raw.trim();
+  // Reject slash-alpha syntax
+  if (trimmed.includes('/')) return NaN;
+  if (trimmed.endsWith('%')) {
+    return Math.max(0, Math.min(1, parseFloat(trimmed) / 100));
+  }
+  return Math.max(0, Math.min(1, parseFloat(trimmed)));
+}
+
+function parseRgb(inner: string): RgbaComponents | null {
+  // Reject modern slash-alpha syntax (e.g. "rgb(255 0 0 / 50%)")
+  if (inner.includes('/')) return null;
+  const parts = inner.split(',').map((p) => p.trim());
+  if (parts.length < 3 || parts.length > 4) return null;
+
+  const p0 = parts[0] ?? '';
+  const p1 = parts[1] ?? '';
+  const p2 = parts[2] ?? '';
+  const r = parseChannelValue(p0);
+  const g = parseChannelValue(p1);
+  const b = parseChannelValue(p2);
+  const a = parts.length === 4 ? parseAlphaValue(parts[3] ?? '') : 1;
+
+  if ([r, g, b, a].some(isNaN)) return null;
+  return { r, g, b, a };
+}
+
+function hslToRgb(h: number, s: number, l: number): { r: number; g: number; b: number } {
+  // Wrap hue to [0, 360)
+  h = ((h % 360) + 360) % 360;
+  // Clamp s and l to [0, 1]
+  s = Math.max(0, Math.min(1, s));
+  l = Math.max(0, Math.min(1, l));
+
+  if (s === 0) {
+    const v = Math.round(l * 255);
+    return { r: v, g: v, b: v };
+  }
+
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+
+  let rp = 0,
+    gp = 0,
+    bp = 0;
+  if (h < 60) {
+    rp = c;
+    gp = x;
+    bp = 0;
+  } else if (h < 120) {
+    rp = x;
+    gp = c;
+    bp = 0;
+  } else if (h < 180) {
+    rp = 0;
+    gp = c;
+    bp = x;
+  } else if (h < 240) {
+    rp = 0;
+    gp = x;
+    bp = c;
+  } else if (h < 300) {
+    rp = x;
+    gp = 0;
+    bp = c;
+  } else {
+    rp = c;
+    gp = 0;
+    bp = x;
+  }
+
+  return {
+    r: Math.round((rp + m) * 255),
+    g: Math.round((gp + m) * 255),
+    b: Math.round((bp + m) * 255),
+  };
+}
+
+function parseHsl(inner: string): RgbaComponents | null {
+  // Reject modern slash-alpha syntax (e.g. "hsl(0 100% 50% / 50%)")
+  if (inner.includes('/')) return null;
+  const parts = inner.split(',').map((p) => p.trim());
+  if (parts.length < 3 || parts.length > 4) return null;
+
+  const p0 = parts[0] ?? '';
+  const p1 = parts[1] ?? '';
+  const p2 = parts[2] ?? '';
+  const h = parseFloat(p0); // unitless degrees
+  const sPct = p1.endsWith('%') ? parseFloat(p1) : NaN;
+  const lPct = p2.endsWith('%') ? parseFloat(p2) : NaN;
+  const a = parts.length === 4 ? parseAlphaValue(parts[3] ?? '') : 1;
+
+  if ([h, sPct, lPct, a].some(isNaN)) return null;
+
+  const { r, g, b } = hslToRgb(h, sPct / 100, lPct / 100);
+  return { r, g, b, a };
+}
+
+/**
+ * Return true when the color has a non-opaque alpha channel.
+ * Supports: `#rgba`, `#rrggbbaa`, `rgba(...)`, `hsla(...)`.
+ * Any unsupported format returns false (treated as opaque).
+ */
+export function hasAlpha(input: string): boolean {
+  const parsed = parseColor(input);
+  if (!parsed) return false;
+  return parsed.a < 1;
+}
+
+/** Linearize a single sRGB channel (0–255) per WCAG 2.x. */
+function linearize(channel: number): number {
+  const cs = channel / 255;
+  return cs <= 0.04045 ? cs / 12.92 : ((cs + 0.055) / 1.055) ** 2.4;
+}
+
+/**
+ * Compute WCAG 2.x relative luminance from an RGB triple (channels 0–255).
+ * https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+export function relativeLuminance({ r, g, b }: { r: number; g: number; b: number }): number {
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+/**
+ * Return `'black'` or `'white'` — whichever has higher WCAG contrast ratio against
+ * the given color. Falls back to `'white'` when the color cannot be parsed.
+ *
+ * Alpha is ignored: the indicator color is chosen against the swatch's intended
+ * solid color, not its composite with whatever surface sits behind it.
+ */
+export function pickContrastColor(input: string): 'black' | 'white' {
+  const parsed = parseColor(input);
+  if (!parsed) return 'white';
+
+  const L = relativeLuminance(parsed);
+  // WCAG contrast ratio against black (L2=0) and white (L2=1)
+  const contrastBlack = (L + 0.05) / 0.05;
+  const contrastWhite = 1.05 / (L + 0.05);
+  return contrastBlack >= contrastWhite ? 'black' : 'white';
+}