@lostgradient/cinder 0.4.0 → 0.4.1

package/src/index.ts

@@ -237,6 +237,7 @@ export type {
   DataTableColumn,
   DataTableProps,
   DataTableRow,
+  DataTableSelectionMode,
 } from './components/data-table/index.ts';
 
 export { default as DateRangeField } from './components/date-range-field/index.ts';
@@ -683,7 +684,7 @@ export type {
   SortableAnnouncements,
   SortableItemContext,
   SortableReorderChange,
-} from './utilities/sortable-controller.svelte.ts';
+} from './utilities/sortable-controller.types.ts';
 
 export { default as Skeleton } from './components/skeleton/index.ts';
 export type { SkeletonProps } from './components/skeleton/index.ts';
@@ -823,7 +824,7 @@ export type {
 } from './components/transfer-list/index.ts';
 
 export { useAnnouncer } from './utilities/use-announcer.svelte.ts';
-export type { Announcer, AnnouncerOptions } from './utilities/use-announcer.svelte.ts';
+export type { Announcer, AnnouncerOptions } from './utilities/use-announcer.types.ts';
 
 export { useHistory } from './utilities/use-history.svelte.ts';
 export type {
@@ -832,12 +833,12 @@ export type {
   UseHistoryEntry,
   UseHistoryEntryMetadata,
   UseHistoryOptions,
-} from './utilities/use-history.svelte.ts';
+} from './utilities/use-history.types.ts';
 
 export { useIntersection } from './utilities/use-intersection.svelte.ts';
 export { useMutationObserver } from './utilities/use-mutation-observer.svelte.ts';
 export { useReducedMotion } from './utilities/use-reduced-motion.svelte.ts';
-export type { UseReducedMotion } from './utilities/use-reduced-motion.svelte.ts';
+export type { UseReducedMotion } from './utilities/use-reduced-motion.types.ts';
 export { useResizeObserver } from './utilities/use-resize-observer.svelte.ts';
 
 export { useToast } from './utilities/use-toast.ts';

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

@@ -14,27 +14,7 @@ import {
   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;
-}
+import type { ChangeTracker, ChangeTrackerOptions } from './change-tracker.types.ts';
 
 /**
  * Fast non-cryptographic hash for change detection.

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

@@ -0,0 +1,21 @@
+export type ChangeTrackerOptions = {
+  /** Debounce delay for semantic comparison (ms). Default: 300 */
+  debounceMs?: number;
+  /** Whether to include front matter in comparison. Default: false */
+  includeFrontMatter?: boolean;
+};
+
+export type 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;
+};

package/src/utilities/document-order.ts

@@ -14,12 +14,17 @@
  * practice this is unreachable during normal teardown — unregister runs
  * synchronously inside the attachment cleanup, before the node is removed.
  */
+const DOCUMENT_POSITION_PRECEDING = 0x02;
+const DOCUMENT_POSITION_FOLLOWING = 0x04;
+
 export function inDocumentOrder<T extends { node: Node }>(items: readonly T[]): T[] {
-  return items.toSorted((a, b) => {
+  const sortedItems = [...items];
+  sortedItems.sort((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;
+    if (position & DOCUMENT_POSITION_FOLLOWING) return -1;
+    if (position & DOCUMENT_POSITION_PRECEDING) return 1;
     return 0;
   });
+  return sortedItems;
 }

package/src/utilities/sortable-controller.svelte.ts

@@ -1,52 +1,10 @@
 import { createContext } from 'svelte';
 
-export type SortableAnnouncements = {
-  lifted: (itemLabel: string, position: number, total: number) => string;
-  moved: (itemLabel: string, position: number, total: number) => string;
-  dropped: (itemLabel: string, position: number, total: number) => string;
-  cancelled: (itemLabel: string) => string;
-};
-
-export type SortableReorderChange = {
-  itemKey: string | number;
-  /** Index of the lifted item in `items` immediately before the drop. */
-  fromIndex: number;
-  /** Index where the item is placed after the drop. */
-  toIndex: number;
-};
-
-export type SortableItemContext = {
-  /** True when this row is currently lifted. */
-  isLifted: boolean;
-  /** True when this row would receive the drop. */
-  isDropTarget: boolean;
-  /** The visual index this row currently occupies. */
-  visualIndex: number;
-  /** Total rows in the list. */
-  total: number;
-};
-
-/** Shape of the command bag passed through context from SortableList to SortableItem. */
-export type SortableContextValue = {
-  controller: SortableController<unknown>;
-  commitDrop: (itemKey: string | number, itemLabel: string) => void;
-  cancel: (itemLabel: string) => void;
-  lift: (key: string | number, fromIndex: number, itemLabel: string, total: number) => void;
-  move: (toIndex: number, itemLabel: string, total: number) => void;
-  getPointerTarget?: (input: {
-    activeKey: string | number;
-    pointerX: number;
-    pointerY: number;
-    itemLabel: string;
-  }) => { index: number; total: number } | null;
-  handleLiftedKeydown?: (input: {
-    event: KeyboardEvent;
-    itemKey: string | number;
-    itemLabel: string;
-    index: number;
-    total: number;
-  }) => boolean;
-};
+import type {
+  SortableAnnouncements,
+  SortableContextValue,
+  SortableReorderChange,
+} from './sortable-controller.types.ts';
 
 export const [getSortableContext, setSortableContext] = createContext<SortableContextValue>();
 

package/src/utilities/sortable-controller.types.ts

@@ -0,0 +1,49 @@
+import type { SortableController } from './sortable-controller.svelte.ts';
+
+export type SortableAnnouncements = {
+  lifted: (itemLabel: string, position: number, total: number) => string;
+  moved: (itemLabel: string, position: number, total: number) => string;
+  dropped: (itemLabel: string, position: number, total: number) => string;
+  cancelled: (itemLabel: string) => string;
+};
+
+export type SortableReorderChange = {
+  itemKey: string | number;
+  /** Index of the lifted item in `items` immediately before the drop. */
+  fromIndex: number;
+  /** Index where the item is placed after the drop. */
+  toIndex: number;
+};
+
+export type SortableItemContext = {
+  /** True when this row is currently lifted. */
+  isLifted: boolean;
+  /** True when this row would receive the drop. */
+  isDropTarget: boolean;
+  /** The visual index this row currently occupies. */
+  visualIndex: number;
+  /** Total rows in the list. */
+  total: number;
+};
+
+/** Shape of the command bag passed through context from SortableList to SortableItem. */
+export type SortableContextValue = {
+  controller: SortableController<unknown>;
+  commitDrop: (itemKey: string | number, itemLabel: string) => void;
+  cancel: (itemLabel: string) => void;
+  lift: (key: string | number, fromIndex: number, itemLabel: string, total: number) => void;
+  move: (toIndex: number, itemLabel: string, total: number) => void;
+  getPointerTarget?: (input: {
+    activeKey: string | number;
+    pointerX: number;
+    pointerY: number;
+    itemLabel: string;
+  }) => { index: number; total: number } | null;
+  handleLiftedKeydown?: (input: {
+    event: KeyboardEvent;
+    itemKey: string | number;
+    itemLabel: string;
+    index: number;
+    total: number;
+  }) => boolean;
+};

package/src/utilities/typeahead.ts

@@ -0,0 +1,63 @@
+export type TypeaheadCandidate<T> = {
+  value: T;
+  label: string;
+  disabled?: boolean | undefined;
+};
+
+export function isTypeaheadKey(event: KeyboardEvent): boolean {
+  return (
+    event.key.length === 1 &&
+    event.key !== ' ' &&
+    !event.ctrlKey &&
+    !event.metaKey &&
+    !event.altKey &&
+    !event.isComposing
+  );
+}
+
+export function findTypeaheadMatch<T>(
+  candidates: readonly TypeaheadCandidate<T>[],
+  prefix: string,
+  currentIndex: number,
+): T | undefined {
+  if (candidates.length === 0) return undefined;
+
+  const normalizedPrefix = prefix.toLocaleLowerCase();
+  const startIndex = currentIndex < 0 ? -1 : currentIndex;
+
+  for (let offset = 1; offset <= candidates.length; offset += 1) {
+    const index = (startIndex + offset) % candidates.length;
+    const candidate = candidates[index];
+    if (!candidate || candidate.disabled) continue;
+    if (candidate.label.toLocaleLowerCase().startsWith(normalizedPrefix)) {
+      return candidate.value;
+    }
+  }
+
+  return undefined;
+}
+
+export class TypeaheadBuffer {
+  #value = '';
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  push(character: string): string {
+    this.clearTimer();
+    this.#value += character.toLocaleLowerCase();
+    this.#timer = setTimeout(() => {
+      this.reset();
+    }, 500);
+    return this.#value;
+  }
+
+  reset(): void {
+    this.clearTimer();
+    this.#value = '';
+  }
+
+  clearTimer(): void {
+    if (this.#timer === null) return;
+    clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+}

package/src/utilities/use-announcer.svelte.ts

@@ -26,32 +26,7 @@
  * ```
  */
 
-export interface AnnouncerOptions {
-  /**
-   * Delay before clearing the message (ms).
-   * This should be long enough for screen readers to read the message.
-   * Default: 1000
-   */
-  clearDelay?: number;
-
-  /**
-   * Debounce delay before announcing (ms).
-   * Use when announcements may fire rapidly (e.g., typing indicators).
-   * Default: 0 (no debounce)
-   */
-  debounceMs?: number;
-}
-
-export interface Announcer {
-  /** The current message to display in the live region */
-  readonly message: string;
-  /** Announce a message to screen readers */
-  announce(text: string): void;
-  /** Clear any pending announcement and reset message */
-  clear(): void;
-  /** Cleanup resources - call via onDestroy() if needed before component unmount */
-  destroy(): void;
-}
+import type { Announcer, AnnouncerOptions } from './use-announcer.types.ts';
 
 /**
  * Create a screen reader announcer for use with ARIA live regions.

package/src/utilities/use-announcer.types.ts

@@ -0,0 +1,26 @@
+export type AnnouncerOptions = {
+  /**
+   * Delay before clearing the message (ms).
+   * This should be long enough for screen readers to read the message.
+   * Default: 1000
+   */
+  clearDelay?: number;
+
+  /**
+   * Debounce delay before announcing (ms).
+   * Use when announcements may fire rapidly (e.g., typing indicators).
+   * Default: 0 (no debounce)
+   */
+  debounceMs?: number;
+};
+
+export type Announcer = {
+  /** The current message to display in the live region */
+  readonly message: string;
+  /** Announce a message to screen readers */
+  announce(text: string): void;
+  /** Clear any pending announcement and reset message */
+  clear(): void;
+  /** Cleanup resources - call via onDestroy() if needed before component unmount */
+  destroy(): void;
+};

package/src/utilities/use-history.svelte.ts

@@ -14,62 +14,12 @@
  * and `equals` strategies.
  */
 
-export interface UseHistoryEntryMetadata {
-  /** Human-readable description of the action that produced this entry. */
-  label?: string | undefined;
-}
-
-export interface UseHistoryCommitOptions extends UseHistoryEntryMetadata {
-  /**
-   * Caller-provided tag. Two consecutive commits sharing the same key within
-   * `coalesceMs` replace the stack top instead of pushing. Pass `undefined`
-   * (or omit) for structural actions that should always push.
-   */
-  coalesceKey?: string | undefined;
-}
-
-export interface UseHistoryEntry<T> {
-  value: T;
-  label?: string | undefined;
-}
-
-export interface UseHistoryOptions<T> {
-  initial: T;
-  /** Maximum number of entries retained in the stack. Default: 100. */
-  maxDepth?: number | undefined;
-  /** Time window for coalescing rapid commits sharing a key. Default: 300ms. */
-  coalesceMs?: number | undefined;
-  /** Deep-clone strategy. Default: structuredClone. */
-  clone?: ((value: T) => T) | undefined;
-  /**
-   * Equality predicate used to skip no-op commits. Default: stable JSON
-   * serialise comparison (sorted keys). Reference identity is intentionally
-   * NOT used as a sufficient signal — callers may mutate-then-commit the
-   * same object reference and we should still push a new entry.
-   */
-  equals?: ((a: T, b: T) => boolean) | undefined;
-}
-
-export interface UseHistory<T> {
-  /** Current reactive value; may be ahead of the committed stack via {@link UseHistory.set}. */
-  readonly current: T;
-  /** Top of the committed stack — the entry undo would leave us at. */
-  readonly committedEntry: UseHistoryEntry<T>;
-  readonly canUndo: boolean;
-  readonly canRedo: boolean;
-  readonly size: number;
-  readonly index: number;
-  /** Replace `current` without touching the committed stack. */
-  set(next: T): void;
-  /** Push a new entry (subject to coalescing and equality). */
-  commit(next: T, options?: UseHistoryCommitOptions): void;
-  /** Move back one entry. Returns the entry we left, or null at the bottom. */
-  undo(): UseHistoryEntry<T> | null;
-  /** Move forward one entry. Returns the entry we moved to, or null at the top. */
-  redo(): UseHistoryEntry<T> | null;
-  /** Clear history and seed a new baseline. */
-  reset(value: T, label?: string): void;
-}
+import type {
+  UseHistory,
+  UseHistoryCommitOptions,
+  UseHistoryEntry,
+  UseHistoryOptions,
+} from './use-history.types.ts';
 
 function defaultClone<T>(value: T): T {
   // First unwrap any Svelte $state proxies via $state.snapshot, which yields

package/src/utilities/use-history.types.ts

@@ -0,0 +1,56 @@
+export type UseHistoryEntryMetadata = {
+  /** Human-readable description of the action that produced this entry. */
+  label?: string | undefined;
+};
+
+export type UseHistoryCommitOptions = UseHistoryEntryMetadata & {
+  /**
+   * Caller-provided tag. Two consecutive commits sharing the same key within
+   * `coalesceMs` replace the stack top instead of pushing. Pass `undefined`
+   * (or omit) for structural actions that should always push.
+   */
+  coalesceKey?: string | undefined;
+};
+
+export type UseHistoryEntry<T> = {
+  value: T;
+  label?: string | undefined;
+};
+
+export type UseHistoryOptions<T> = {
+  initial: T;
+  /** Maximum number of entries retained in the stack. Default: 100. */
+  maxDepth?: number | undefined;
+  /** Time window for coalescing rapid commits sharing a key. Default: 300ms. */
+  coalesceMs?: number | undefined;
+  /** Deep-clone strategy. Default: structuredClone. */
+  clone?: ((value: T) => T) | undefined;
+  /**
+   * Equality predicate used to skip no-op commits. Default: stable JSON
+   * serialise comparison (sorted keys). Reference identity is intentionally
+   * NOT used as a sufficient signal — callers may mutate-then-commit the
+   * same object reference and we should still push a new entry.
+   */
+  equals?: ((a: T, b: T) => boolean) | undefined;
+};
+
+export type UseHistory<T> = {
+  /** Current reactive value; may be ahead of the committed stack via {@link UseHistory.set}. */
+  readonly current: T;
+  /** Top of the committed stack — the entry undo would leave us at. */
+  readonly committedEntry: UseHistoryEntry<T>;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly size: number;
+  readonly index: number;
+  /** Replace `current` without touching the committed stack. */
+  set(next: T): void;
+  /** Push a new entry (subject to coalescing and equality). */
+  commit(next: T, options?: UseHistoryCommitOptions): void;
+  /** Move back one entry. Returns the entry we left, or null at the bottom. */
+  undo(): UseHistoryEntry<T> | null;
+  /** Move forward one entry. Returns the entry we moved to, or null at the top. */
+  redo(): UseHistoryEntry<T> | null;
+  /** Clear history and seed a new baseline. */
+  reset(value: T, label?: string): void;
+};

package/src/utilities/use-intersection.svelte.ts

@@ -1,17 +1,8 @@
-import type { Attachment } from 'svelte/attachments';
-
-export type IntersectionCallback = (entry: IntersectionObserverEntry) => void;
-
-export type UseIntersectionOptions = {
-  /** Static root element. If null/undefined, observes against the viewport. */
-  root?: Element | Document | null;
-  /** CSS margin string captured when the attachment mounts. Defaults to "0px". */
-  rootMargin?: string;
-  /** Threshold(s) captured when the attachment mounts. Defaults to 0. */
-  threshold?: number | number[];
-  /** Getter for whether observation is enabled. Defaults to `() => true`. */
-  enabled?: () => boolean;
-};
+import type {
+  IntersectionAttachment,
+  IntersectionCallback,
+  UseIntersectionOptions,
+} from './use-intersection.types.ts';
 
 /**
  * Creates an attachment that observes the element with IntersectionObserver.
@@ -23,7 +14,7 @@ export type UseIntersectionOptions = {
 export function useIntersection(
   onIntersect: IntersectionCallback,
   options: UseIntersectionOptions = {},
-): Attachment<HTMLElement> {
+): IntersectionAttachment {
   const { root = null, rootMargin = '0px', threshold = 0, enabled = () => true } = options;
 
   return (node: HTMLElement) => {

package/src/utilities/use-intersection.types.ts

@@ -0,0 +1,16 @@
+import type { Attachment } from 'svelte/attachments';
+
+export type IntersectionCallback = (entry: IntersectionObserverEntry) => void;
+
+export type UseIntersectionOptions = {
+  /** Static root element. If null/undefined, observes against the viewport. */
+  root?: Element | Document | null;
+  /** CSS margin string captured when the attachment mounts. Defaults to "0px". */
+  rootMargin?: string;
+  /** Threshold(s) captured when the attachment mounts. Defaults to 0. */
+  threshold?: number | number[];
+  /** Getter for whether observation is enabled. Defaults to `() => true`. */
+  enabled?: () => boolean;
+};
+
+export type IntersectionAttachment = Attachment<HTMLElement>;

package/src/utilities/use-mutation-observer.svelte.ts

@@ -1,25 +1,8 @@
-import type { Attachment } from 'svelte/attachments';
-
-export type MutationCallback = (mutations: MutationRecord[]) => void;
-
-export type UseMutationObserverOptions = {
-  /** Whether to observe child node additions and removals. */
-  childList?: boolean;
-  /** Whether to observe changes to the target's attributes. */
-  attributes?: boolean;
-  /** Whether to observe changes to the target's character data. */
-  characterData?: boolean;
-  /** Whether to extend observation to the entire subtree. */
-  subtree?: boolean;
-  /** Specific attribute names to observe. Only relevant when `attributes` is true. */
-  attributeFilter?: string[];
-  /** Whether to record the old attribute value before a change. */
-  attributeOldValue?: boolean;
-  /** Whether to record the old character data before a change. */
-  characterDataOldValue?: boolean;
-  /** Getter for whether observation is enabled. Defaults to `() => true`. */
-  enabled?: () => boolean;
-};
+import type {
+  MutationCallback,
+  MutationObserverAttachment,
+  UseMutationObserverOptions,
+} from './use-mutation-observer.types.ts';
 
 /**
  * Creates an attachment that observes the element with MutationObserver.
@@ -31,7 +14,7 @@ export type UseMutationObserverOptions = {
 export function useMutationObserver(
   onMutate: MutationCallback,
   options: UseMutationObserverOptions = {},
-): Attachment<HTMLElement> {
+): MutationObserverAttachment {
   const {
     childList,
     attributes,

package/src/utilities/use-mutation-observer.types.ts

@@ -0,0 +1,24 @@
+import type { Attachment } from 'svelte/attachments';
+
+export type MutationCallback = (mutations: MutationRecord[]) => void;
+
+export type UseMutationObserverOptions = {
+  /** Whether to observe child node additions and removals. */
+  childList?: boolean;
+  /** Whether to observe changes to the target's attributes. */
+  attributes?: boolean;
+  /** Whether to observe changes to the target's character data. */
+  characterData?: boolean;
+  /** Whether to extend observation to the entire subtree. */
+  subtree?: boolean;
+  /** Specific attribute names to observe. Only relevant when `attributes` is true. */
+  attributeFilter?: string[];
+  /** Whether to record the old attribute value before a change. */
+  attributeOldValue?: boolean;
+  /** Whether to record the old character data before a change. */
+  characterDataOldValue?: boolean;
+  /** Getter for whether observation is enabled. Defaults to `() => true`. */
+  enabled?: () => boolean;
+};
+
+export type MutationObserverAttachment = Attachment<HTMLElement>;

package/src/utilities/use-reduced-motion.svelte.ts

@@ -1,9 +1,6 @@
 import { MediaQuery } from 'svelte/reactivity';
 
-export type UseReducedMotion = {
-  /** Reactive boolean — `true` when the user prefers reduced motion. */
-  readonly current: boolean;
-};
+import type { UseReducedMotion } from './use-reduced-motion.types.ts';
 
 /**
  * Reactive `prefers-reduced-motion: reduce` watcher backed by Svelte's `MediaQuery`.

package/src/utilities/use-reduced-motion.types.ts

@@ -0,0 +1,4 @@
+export type UseReducedMotion = {
+  /** Reactive boolean — `true` when the user prefers reduced motion. */
+  readonly current: boolean;
+};

package/src/utilities/use-resize-observer.svelte.ts

@@ -1,13 +1,8 @@
-import type { Attachment } from 'svelte/attachments';
-
-export type ResizeCallback = (entries: ResizeObserverEntry[]) => void;
-
-export type UseResizeObserverOptions = {
-  /** Which box model to observe. Defaults to the ResizeObserver constructor default. */
-  box?: ResizeObserverBoxOptions;
-  /** Getter for whether observation is enabled. Defaults to `() => true`. */
-  enabled?: () => boolean;
-};
+import type {
+  ResizeCallback,
+  ResizeObserverAttachment,
+  UseResizeObserverOptions,
+} from './use-resize-observer.types.ts';
 
 /**
  * Creates an attachment that observes the element with ResizeObserver.
@@ -19,7 +14,7 @@ export type UseResizeObserverOptions = {
 export function useResizeObserver(
   onResize: ResizeCallback,
   options: UseResizeObserverOptions = {},
-): Attachment<HTMLElement> {
+): ResizeObserverAttachment {
   const { box, enabled = () => true } = options;
 
   return (node: HTMLElement) => {

package/src/utilities/use-resize-observer.types.ts

@@ -0,0 +1,12 @@
+import type { Attachment } from 'svelte/attachments';
+
+export type ResizeCallback = (entries: ResizeObserverEntry[]) => void;
+
+export type UseResizeObserverOptions = {
+  /** Which box model to observe. Defaults to the ResizeObserver constructor default. */
+  box?: ResizeObserverBoxOptions;
+  /** Getter for whether observation is enabled. Defaults to `() => true`. */
+  enabled?: () => boolean;
+};
+
+export type ResizeObserverAttachment = Attachment<HTMLElement>;