@lostgradient/cinder 0.1.0

package/src/utilities/dev-warn.ts

@@ -0,0 +1,30 @@
+import { DEV } from 'esm-env';
+
+/**
+ * Emit a development-only `console.warn`.
+ *
+ * Component contract-misuse warnings (a missing required prop, an id that does
+ * not match the wrapping FormField, a duplicate key, …) are diagnostics for the
+ * developer building the app — never for the end user. Routing them through
+ * `devWarn` instead of a bare `console.warn` means:
+ *
+ * - **They are stripped from production bundles.** `DEV` from `esm-env` resolves
+ *   to a literal `false` under a production build, so a bundler dead-code-
+ *   eliminates the whole call. End users never see internal naming, and the
+ *   warning string is not shipped.
+ * - **One named, greppable seam.** Every diagnostic flows through one helper, so
+ *   the policy ("warnings are dev-only") is enforceable with a single lint rule
+ *   that bans bare `console.warn` in component source.
+ *
+ * Prefer calling this from a plain guard at the point of misuse rather than from
+ * a `$effect` whose only purpose is to warn — a reactive effect kept alive solely
+ * to log re-subscribes on every state change for no runtime benefit.
+ *
+ * @param message The warning message. Conventionally prefixed with the component
+ *   tag, e.g. `[cinder/Select] …`.
+ * @param args Additional values forwarded to `console.warn` (objects, ids, …).
+ */
+export function devWarn(message: string, ...args: unknown[]): void {
+  if (!DEV) return;
+  console.warn(message, ...args);
+}

package/src/utilities/document-order.ts

@@ -0,0 +1,25 @@
+/**
+ * Sort a list of items by DOM document order, using `compareDocumentPosition`
+ * on each item's `node`. Stable. Returns a new array — does not mutate input.
+ *
+ * Why: `{@attach}` fires after the node is mounted, so registration order
+ * usually equals DOM order. But conditional `{#if}` blocks that re-mount
+ * middle items can desync the registration list from visual order. Sorting
+ * on read keeps keyboard navigation aligned with the rendered tree.
+ *
+ * Edge case: if a node is temporarily disconnected from the document,
+ * `compareDocumentPosition` returns a platform-specific disconnected mask
+ * (`DOCUMENT_POSITION_DISCONNECTED | DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC`).
+ * The sort remains stable but order is undefined for disconnected nodes. In
+ * practice this is unreachable during normal teardown — unregister runs
+ * synchronously inside the attachment cleanup, before the node is removed.
+ */
+export function inDocumentOrder<T extends { node: Node }>(items: readonly T[]): T[] {
+  return items.toSorted((a, b) => {
+    if (a.node === b.node) return 0;
+    const position = a.node.compareDocumentPosition(b.node);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+    if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+    return 0;
+  });
+}

package/src/utilities/focus.ts

@@ -0,0 +1,42 @@
+/// <reference lib="dom" />
+
+/**
+ * Shared focus-restore helper used by overlay components (Modal, Sheet,
+ * Popover) when returning focus on close. The candidate list is kept local
+ * to each component — this helper enforces a uniform per-candidate safety
+ * check and refuses to fall back to `document.body`.
+ *
+ * The check matches Popover's pre-existing strictness: the target must be
+ * non-null, currently connected to the active document, and owned by that
+ * document. When the candidate fails the check the helper no-ops and returns
+ * `false` so callers can try the next candidate.
+ */
+
+/**
+ * Attempt to focus `target`. Returns `true` when focus was moved, `false`
+ * when the target failed the connection/ownership check or was null. Never
+ * falls back to `document.body`.
+ *
+ * Usage (typical candidate iteration):
+ *
+ * ```ts
+ * const candidates = [triggerRef, capturedFocus];
+ * for (const candidate of candidates) {
+ *   if (restoreFocusTo(candidate)) break;
+ * }
+ * ```
+ */
+export function restoreFocusTo(target: HTMLElement | null): boolean {
+  if (!target) return false;
+  if (typeof document === 'undefined') return false;
+  if (!target.isConnected) return false;
+  if (target.ownerDocument !== document) return false;
+  try {
+    target.focus();
+  } catch {
+    // happy-dom + jsdom can throw on focus() for exotic elements; treat as
+    // a failed candidate so the caller can fall through to the next one.
+    return false;
+  }
+  return true;
+}

package/src/utilities/format-bytes.ts

@@ -0,0 +1,16 @@
+/**
+ * Format bytes to a human-readable size string.
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted string (e.g., "1.5 KB", "2.3 MB", "512 B")
+ *
+ * @example
+ * formatBytes(512) // "512 B"
+ * formatBytes(1536) // "1.5 KB"
+ * formatBytes(2621440) // "2.5 MB"
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/utilities/format-date.ts

@@ -0,0 +1,62 @@
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+const WEEK = 604_800_000;
+const MONTH = 2_592_000_000;
+
+function toDate(input: number | string | Date): Date {
+  if (input instanceof Date) return input;
+  if (typeof input === 'number') return new Date(input);
+  return new Date(input);
+}
+
+/**
+ * Format a date with explicit locale and time-zone control.
+ *
+ * Defaults to `en-US` and UTC so call sites stay deterministic across machines and CI shards.
+ * Pass an `Intl.DateTimeFormatOptions` object to override the time zone or formatting.
+ */
+export function formatDate(
+  date: Date | string | number,
+  locale: string = 'en-US',
+  options: Intl.DateTimeFormatOptions = {},
+): string {
+  const d = date instanceof Date ? date : new Date(date);
+  return new Intl.DateTimeFormat(locale, { timeZone: 'UTC', ...options }).format(d);
+}
+
+/** Format a date relative to now (e.g., "5m ago", "2h ago", "3d ago"). */
+export function formatRelativeTime(input: number | string | Date): string {
+  const date = toDate(input);
+  const now = Date.now();
+  const elapsed = now - date.getTime();
+
+  if (elapsed < MINUTE) return 'just now';
+  if (elapsed < HOUR) return `${Math.floor(elapsed / MINUTE)}m ago`;
+  if (elapsed < DAY) return `${Math.floor(elapsed / HOUR)}h ago`;
+  if (elapsed < WEEK) return `${Math.floor(elapsed / DAY)}d ago`;
+  if (elapsed < MONTH) return `${Math.floor(elapsed / WEEK)}w ago`;
+
+  return new Intl.DateTimeFormat('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    timeZone: 'UTC',
+  }).format(date);
+}
+
+/** Format a timestamp for display. Returns "-" for null/undefined. */
+export function formatTimestamp(input: number | string | Date | null | undefined): string {
+  if (input === null || input === undefined) return '-';
+
+  const date = toDate(input);
+
+  return new Intl.DateTimeFormat('en-US', {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+    timeZone: 'UTC',
+  }).format(date);
+}

package/src/utilities/format-duration.ts

@@ -0,0 +1,52 @@
+/** Format a duration in milliseconds to a human-readable string (e.g., "45s", "3m 12s", "2h 15m"). */
+export function formatDuration(milliseconds: number | null): string;
+export function formatDuration(
+  start: Date | string | number | null,
+  end: Date | string | number | null,
+): string;
+export function formatDuration(
+  startOrMilliseconds: number | Date | string | null,
+  end?: Date | string | number | null,
+): string {
+  let milliseconds: number;
+
+  if (end !== undefined) {
+    if (startOrMilliseconds === null || end === null) return '-';
+
+    const startTime =
+      typeof startOrMilliseconds === 'number'
+        ? startOrMilliseconds
+        : new Date(startOrMilliseconds).getTime();
+    const endTime = typeof end === 'number' ? end : new Date(end).getTime();
+    milliseconds = endTime - startTime;
+  } else {
+    if (startOrMilliseconds === null) return '-';
+    milliseconds = typeof startOrMilliseconds === 'number' ? startOrMilliseconds : 0;
+  }
+
+  if (milliseconds < 0) return '-';
+
+  const seconds = Math.floor(milliseconds / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) {
+    const remainingHours = hours % 24;
+    return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
+  }
+
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60;
+    return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+  }
+
+  if (minutes > 0) {
+    const remainingSeconds = seconds % 60;
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+  }
+
+  if (seconds > 0) return `${seconds}s`;
+
+  return `${milliseconds}ms`;
+}

package/src/utilities/format-number.ts

@@ -0,0 +1,13 @@
+/**
+ * Format a number with explicit locale and `Intl.NumberFormat` options.
+ *
+ * Defaults to `en-US` so call sites stay deterministic across machines and CI shards.
+ * Pass an options object to control fraction digits, grouping, currency, etc.
+ */
+export function formatNumber(
+  value: number,
+  locale: string = 'en-US',
+  options?: Intl.NumberFormatOptions,
+): string {
+  return new Intl.NumberFormat(locale, options).format(value);
+}

package/src/utilities/highlighter.ts

@@ -0,0 +1,36 @@
+/**
+ * The `Highlighter` contract for `<CodeBlock>`.
+ *
+ * `<CodeBlock>` highlights automatically when a `language` is set by
+ * lazy-loading the bundled `@lostgradient/cinder/highlighters/shiki` adapter on the
+ * client. Consumers who want a different highlighter (a non-default theme, a
+ * non-Shiki engine, a pre-configured `shikiHighlighter()` instance) implement
+ * this type and pass the function to `<CodeBlock highlighter={...} />`.
+ *
+ * This file holds the canonical type so plain `.ts` consumers and `.svelte`
+ * components can both `import type` it without going through a component
+ * module path. Keep it free of component/value imports so it never forms an
+ * import cycle.
+ */
+
+/**
+ * Signature of a syntax highlighter callback. Receives the raw `code` and
+ * `lang` and returns an HTML string (sync or async) that replaces
+ * `<CodeBlock>`'s default `<pre><code>` markup — including the
+ * `cinder-code-block__pre` / `__code` classes — so the highlighter is also
+ * responsible for matching any structural CSS the consumer relies on (Shiki's
+ * own `<pre class="shiki ...">` output covers most cases).
+ *
+ * @security The returned string is rendered VERBATIM via `{@html}` inside
+ * `<CodeBlock>`. It is a trusted-HTML boundary: the highlighter MUST escape
+ * every byte of caller- or user-provided `code` before returning markup, or
+ * it opens an HTML-injection / XSS hole. The narrow safety claim cinder makes
+ * is only this: the bundled `@lostgradient/cinder/highlighters/shiki` adapter WITH DEFAULT
+ * OPTIONS escapes its input (Shiki's `codeToHtml` escapes, and the adapter's
+ * plaintext fallback HTML-escapes). Any custom `highlighter`, and any Shiki
+ * usage with custom transformers / decorations / raw-HTML options, is a
+ * caller-owned trust boundary that cinder does not and cannot vouch for. When
+ * highlighting is undesirable, prefer `highlight={false}` — that path escapes
+ * the code via Svelte text interpolation and never touches `{@html}`.
+ */
+export type Highlighter = (code: string, lang: string) => string | Promise<string>;

package/src/utilities/id-factory.ts

@@ -0,0 +1,117 @@
+/**
+ * Deterministic ID factory utilities.
+ *
+ * Provides counters and seed-based hashing so component IDs are stable across
+ * re-renders and snapshot runs — avoiding the visual churn that
+ * `crypto.randomUUID()` and `Math.random()` cause in screenshot regression tests.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A factory that vends deterministic, incrementing IDs for a given prefix. */
+export type IdFactory = {
+  /** Returns the next ID in the sequence: `${prefix}-${counter}`. */
+  next: () => string;
+  /** Resets the internal counter to 0 so the next call to `next()` returns `${prefix}-1`. */
+  reset: () => void;
+};
+
+// ---------------------------------------------------------------------------
+// createIdFactory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates an independent ID factory for the given prefix.
+ *
+ * Each factory maintains its own counter, so two factories with the same
+ * prefix produce independent sequences and do not interfere with each other.
+ *
+ * @param prefix - String prepended to every generated ID (default `''`).
+ * @returns An `IdFactory` with `next()` and `reset()` methods.
+ *
+ * @example
+ * ```ts
+ * const factory = createIdFactory('tooltip');
+ * factory.next(); // 'tooltip-1'
+ * factory.next(); // 'tooltip-2'
+ * factory.reset();
+ * factory.next(); // 'tooltip-1'
+ * ```
+ */
+export function createIdFactory(prefix = ''): IdFactory {
+  let counter = 0;
+
+  return {
+    next(): string {
+      return `${prefix}-${++counter}`;
+    },
+    reset(): void {
+      counter = 0;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// defaultIdFactory
+// ---------------------------------------------------------------------------
+
+/**
+ * A module-level singleton factory useful when callers do not need an
+ * isolated counter. Uses the `'cinder'` prefix.
+ *
+ * @example
+ * ```ts
+ * defaultIdFactory.next(); // 'cinder-1'
+ * defaultIdFactory.next(); // 'cinder-2'
+ * ```
+ */
+export const defaultIdFactory: IdFactory = createIdFactory('cinder');
+
+// ---------------------------------------------------------------------------
+// useStableId
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a deterministic ID derived from `seed`.
+ *
+ * When a seed is provided the ID is derived from the first 8 hex characters of
+ * the SHA-1 digest of that seed, prefixed with `'id-'`. The same seed always
+ * produces the same ID, making it safe for snapshot/regression test runs that
+ * capture DOM output.
+ *
+ * When no seed is provided the call falls back to `defaultIdFactory.next()`,
+ * which returns a sequentially incrementing ID.
+ *
+ * @param seed - An optional string whose content uniquely identifies the element
+ *   (e.g. `file.name + file.size + file.lastModified`).
+ * @returns A stable string ID.
+ *
+ * @example
+ * ```ts
+ * useStableId('report.pdf12345678901234'); // 'id-a3f2c1b0'  (deterministic)
+ * useStableId();                            // 'cinder-1'   (fallback counter)
+ * ```
+ */
+/**
+ * A browser-safe djb2 hash that converts a string to an 8-character lowercase
+ * hex string. Not cryptographic — used only for deterministic ID derivation.
+ */
+function djb2Hex(value: string): string {
+  let hash = 5381;
+  for (let index = 0; index < value.length; index++) {
+    // djb2: hash * 33 XOR charCode. The `| 0` coerces to a 32-bit int on each
+    // iteration so the value stays in the signed-32-bit range across all runtimes.
+    hash = ((hash << 5) + hash + value.charCodeAt(index)) | 0;
+  }
+  // Convert to unsigned 32-bit then to 8-char hex.
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+export function useStableId(seed?: string): string {
+  if (seed === undefined) {
+    return defaultIdFactory.next();
+  }
+  return `id-${djb2Hex(seed)}`;
+}

package/src/utilities/json-highlight.ts

@@ -0,0 +1,193 @@
+/**
+ * Hand-rolled JSON tokenizer for inline syntax highlighting.
+ *
+ * Parses the input first with `JSON.parse` to confirm it is well-formed JSON;
+ * non-JSON input falls through to plain (escaped) text. When parsing succeeds,
+ * walks the original source string with a small state machine and wraps each
+ * token in a `<span class="cinder-json-token cinder-json-token-{kind}">`.
+ *
+ * **HTML-safety invariant.** Every byte of the input is HTML-escaped before
+ * being placed in the output. Token spans are constructed from a fixed set of
+ * class names plus escaped text. The output is therefore safe to render via
+ * Svelte's `{@html}`. Future maintainers must keep the escape step — do not
+ * route raw input into the output.
+ *
+ * Returns a `<code class="cinder-json">…</code>` snippet only. The caller wraps
+ * it in `<pre>` so headed and headerless code blocks share container styling.
+ */
+
+const KEYWORD_NULL = 'null';
+const KEYWORD_TRUE = 'true';
+const KEYWORD_FALSE = 'false';
+
+// Only escape characters that are syntactically meaningful in HTML *text*
+// content. The double-quote needs escaping only inside attribute values, and
+// every quote in our output sits inside text nodes — escaping it would change
+// what users see when copying the rendered string.
+function escapeHtml(text: string): string {
+  return text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+
+function span(kind: string, raw: string): string {
+  return `<span class="cinder-json-token cinder-json-token-${kind}">${escapeHtml(raw)}</span>`;
+}
+
+function plainCode(raw: string): string {
+  return `<code class="cinder-json">${escapeHtml(raw)}</code>`;
+}
+
+/**
+ * Read a JSON string token starting at `source[index]` (which is `"`).
+ * Returns the literal source slice including the surrounding quotes.
+ */
+function readStringLiteral(source: string, startIndex: number): string {
+  let index = startIndex + 1;
+  while (index < source.length) {
+    const character = source[index];
+    if (character === '\\') {
+      index += 2;
+      continue;
+    }
+    if (character === '"') {
+      return source.slice(startIndex, index + 1);
+    }
+    index += 1;
+  }
+  // JSON.parse already validated input, so this branch is unreachable for
+  // well-formed JSON. Return the rest of the source as a defensive fallback.
+  return source.slice(startIndex);
+}
+
+/**
+ * Read a JSON number token starting at `source[startIndex]`. Numbers consist of
+ * an optional minus, integer digits, an optional fractional part, and an
+ * optional exponent.
+ */
+function readNumberLiteral(source: string, startIndex: number): string {
+  const numberPattern = /-?(?:\d+)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+  numberPattern.lastIndex = startIndex;
+  const match = numberPattern.exec(source);
+  return match?.[0] ?? source[startIndex] ?? '';
+}
+
+/**
+ * Tokenize a well-formed JSON source string into highlighted markup.
+ * Caller has already verified `JSON.parse(source)` succeeds.
+ *
+ * `openerStack` tracks the currently-open container kinds left-to-right.
+ * After a comma, the top of the stack tells us whether we're inside an
+ * object (next string is a key) or an array (next string is a value).
+ * Avoids the previous O(n²) backward scan and naturally handles strings
+ * with escaped quotes — no scan that could misread `\"` as a real boundary.
+ */
+function tokenize(source: string): string {
+  let output = '';
+  let index = 0;
+  let pendingKey = false; // tracks whether the next string is an object key
+  const openerStack: Array<'{' | '['> = [];
+
+  while (index < source.length) {
+    const character = source[index];
+
+    if (character === undefined) break;
+
+    if (character === ' ' || character === '\t' || character === '\n' || character === '\r') {
+      output += escapeHtml(character);
+      index += 1;
+      continue;
+    }
+
+    if (character === '{') {
+      output += span('punctuation', '{');
+      openerStack.push('{');
+      pendingKey = true;
+      index += 1;
+      continue;
+    }
+
+    if (character === '[') {
+      output += span('punctuation', '[');
+      openerStack.push('[');
+      pendingKey = false;
+      index += 1;
+      continue;
+    }
+
+    if (character === '}' || character === ']') {
+      output += span('punctuation', character);
+      openerStack.pop();
+      index += 1;
+      continue;
+    }
+
+    if (character === ',') {
+      output += span('punctuation', ',');
+      pendingKey = openerStack[openerStack.length - 1] === '{';
+      index += 1;
+      continue;
+    }
+
+    if (character === ':') {
+      output += span('punctuation', ':');
+      pendingKey = false; // values follow the colon
+      index += 1;
+      continue;
+    }
+
+    if (character === '"') {
+      const literal = readStringLiteral(source, index);
+      output += span(pendingKey ? 'key' : 'string', literal);
+      index += literal.length;
+      // After a key string, the next non-whitespace must be `:` and then a value.
+      // After a value string, the next non-whitespace is `,` or a closing bracket.
+      // pendingKey will be reset by `:` (to false) and by `,` (recomputed).
+      continue;
+    }
+
+    if (character === '-' || (character >= '0' && character <= '9')) {
+      const literal = readNumberLiteral(source, index);
+      output += span('number', literal);
+      index += literal.length;
+      continue;
+    }
+
+    if (source.startsWith(KEYWORD_TRUE, index)) {
+      output += span('boolean', KEYWORD_TRUE);
+      index += KEYWORD_TRUE.length;
+      continue;
+    }
+
+    if (source.startsWith(KEYWORD_FALSE, index)) {
+      output += span('boolean', KEYWORD_FALSE);
+      index += KEYWORD_FALSE.length;
+      continue;
+    }
+
+    if (source.startsWith(KEYWORD_NULL, index)) {
+      output += span('null', KEYWORD_NULL);
+      index += KEYWORD_NULL.length;
+      continue;
+    }
+
+    // Defensive: well-formed JSON has no other tokens. Emit the character
+    // escaped so we never mis-render unexpected input.
+    output += escapeHtml(character);
+    index += 1;
+  }
+
+  return `<code class="cinder-json">${output}</code>`;
+}
+
+/**
+ * Highlight a JSON value as syntax-colored HTML. Non-JSON input is returned as
+ * a plain `<code>` with the input HTML-escaped, so the caller can wrap either
+ * result in the same `<pre>` for visual parity.
+ */
+export function highlightJson(value: string): string {
+  try {
+    JSON.parse(value);
+  } catch {
+    return plainCode(value);
+  }
+  return tokenize(value);
+}