@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/sortable-list/sortable-list.schema.ts

@@ -0,0 +1,71 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    label: {
+      type: 'string',
+      description: 'Accessible name for the list (applied as aria-label on the list root).',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class merged onto the `.cinder-sortable-list` root element.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'announcements',
+        reason: 'unknown-shape',
+        description: 'Optional overrides for announcement strings.',
+      },
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Row content snippet. Receives the item and a per-row context.',
+      },
+      {
+        name: 'formatHandleLabel',
+        reason: 'function-or-snippet',
+        description:
+          'Optional formatter for the drag handle\'s accessible name. Default: "Reorder {itemLabel}".',
+      },
+      {
+        name: 'getItemLabel',
+        reason: 'function-or-snippet',
+        required: true,
+        description:
+          'Returns an accessible label for each item (e.g., "Buy milk").\nThe second argument is the item\'s original index in the `items` array\n(not its current visual position during a drag).\nUsed in handle aria-label and announcements.',
+      },
+      {
+        name: 'getKey',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Returns a stable key for each item. Must not change across reorders.',
+      },
+      {
+        name: 'handle',
+        reason: 'function-or-snippet',
+        description:
+          'Optional snippet rendered inside the drag-handle button. Receives { pressed, label }.',
+      },
+      {
+        name: 'items',
+        reason: 'generic-type-parameter',
+        required: true,
+        description: 'The list of items to render.',
+      },
+      {
+        name: 'onreorder',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Fires with the full reordered array and change metadata on drop.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/sortable-list/sortable-list.svelte

@@ -0,0 +1,113 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts" generics="Item">
+import { untrack } from 'svelte';
+import { classNames } from '../../utilities/class-names.ts';
+import { SortableController, setSortableContext, reorder, } from '../../utilities/sortable-controller.svelte.ts';
+import { useAnnouncer } from '../../utilities/use-announcer.svelte.ts';
+import SortableItem from '../_sortable-item.svelte';
+let { items, getKey, getItemLabel, formatHandleLabel = (label) => `Reorder ${label}`, handle, onreorder, announcements, children: renderRow, label, class: className, } = $props();
+const announcer = useAnnouncer({ clearDelay: 5000 });
+const controller = new SortableController(untrack(() => ({
+    announce: (msg) => announcer.announce(msg),
+    ...(announcements !== undefined ? { announcements } : {}),
+})));
+const instructionsId = $props.id();
+// Derived visual order — pure read of controller state, no side effects.
+const visualItems = $derived.by(() => {
+    if (controller.phase !== 'lifted' || controller.liftedKey === null)
+        return items;
+    const from = items.findIndex((it) => getKey(it) === controller.liftedKey);
+    if (from < 0)
+        return items;
+    return reorder(items, from, controller.liftedTo);
+});
+// Stable key → original-index map, rebuilt only when `items` (or `getKey`)
+// changes. The each block consults this in O(1) instead of `items.indexOf`,
+// which was O(n) per row and O(n²) per drag frame (the each block re-renders
+// on every pointer-move step while lifted).
+const originalIndexByKey = $derived.by(() => {
+    const lookup = new Map();
+    items.forEach((item, index) => lookup.set(getKey(item), index));
+    return lookup;
+});
+// Reconcile lifted key when items changes externally during a lift.
+// Reading each key forces deep tracking so in-place array mutations are caught.
+$effect(() => {
+    items.forEach((it) => getKey(it));
+    controller.reconcileLiftedKey(items, getKey);
+});
+// Command bag passed to each SortableItem via context.
+setSortableContext({
+    get controller() {
+        return controller;
+    },
+    commitDrop(_itemKey, itemLabel) {
+        const result = controller.drop(items, itemLabel);
+        if (result) {
+            onreorder(result.nextItems, result.change);
+        }
+    },
+    cancel(itemLabel) {
+        controller.cancel(itemLabel);
+    },
+    lift(key, fromIndex, itemLabel, total) {
+        controller.lift(key, fromIndex, itemLabel, total);
+    },
+    move(toIndex, itemLabel, total) {
+        controller.move(toIndex, itemLabel, total);
+    },
+});
+// Window-level Escape handler: cancels the lift regardless of which element has focus.
+// This covers the case where focus moved off the handle during a lift (pointer drag,
+// programmatic focus change, etc.). The item-level Escape handler also calls cancel
+// when the handle is focused, but the controller guard (phase !== 'lifted') makes
+// double-cancel safe.
+function handleWindowKeydown(event) {
+    if (controller.phase === 'lifted' && event.key === 'Escape') {
+        event.preventDefault();
+        controller.cancel();
+    }
+}
+</script>
+
+<svelte:window onkeydown={handleWindowKeydown} />
+
+<ul class={classNames('cinder-sortable-list', className)} role="list" aria-label={label}>
+  <!--
+    Instructions live inside the <ul> as a visually hidden <li> so the element is
+    present in the DOM before any handle buttons that reference it via aria-describedby.
+    role="presentation" removes the implicit listitem role so this element does not
+    count toward the list's item count. cinder-sr-only visually hides it with the
+    clip pattern (not display:none), so browsers resolve its id for aria-describedby.
+  -->
+  <li role="presentation" id={instructionsId} class="cinder-sr-only">
+    Press Space to lift, then arrow keys to move, Space to drop, Escape to cancel.
+  </li>
+
+  {#each visualItems as rowItem, visualIndex (getKey(rowItem))}
+    {@const originalIndex = originalIndexByKey.get(getKey(rowItem)) ?? -1}
+    {@const rowItemLabel = getItemLabel(rowItem, originalIndex >= 0 ? originalIndex : visualIndex)}
+    <SortableItem
+      item={rowItem}
+      itemKey={getKey(rowItem)}
+      index={visualIndex}
+      itemLabel={rowItemLabel}
+      {formatHandleLabel}
+      {...handle !== undefined ? { handle } : {}}
+      {instructionsId}
+      total={visualItems.length}
+    >
+      {#snippet children(ctx)}
+        {@render renderRow(rowItem, ctx)}
+      {/snippet}
+    </SortableItem>
+  {/each}
+</ul>
+
+<!-- Live region — role="alert" (implicit assertive) avoids role/aria-live conflict -->
+<div role="alert" aria-atomic="true" class="cinder-sr-only">
+  {announcer.message}
+</div>

package/src/components/sortable-list/sortable-list.types.ts

@@ -0,0 +1,41 @@
+import type { Snippet } from 'svelte';
+export type {
+  SortableAnnouncements,
+  SortableItemContext,
+  SortableReorderChange,
+} from '../../utilities/sortable-controller.types.ts';
+/** Props for the SortableList component. */
+export type SortableListProps<Item> = {
+  /** The list of items to render. */
+  items: Item[];
+  /** Returns a stable key for each item. Must not change across reorders. */
+  getKey: (item: Item) => string | number;
+  /**
+   * Returns an accessible label for each item (e.g., "Buy milk").
+   * The second argument is the item's original index in the `items` array
+   * (not its current visual position during a drag).
+   * Used in handle aria-label and announcements.
+   */
+  getItemLabel: (item: Item, originalIndex: number) => string;
+  /** Optional formatter for the drag handle's accessible name. Default: "Reorder {itemLabel}". */
+  formatHandleLabel?: (itemLabel: string) => string;
+  /** Optional snippet rendered inside the drag-handle button. Receives { pressed, label }. */
+  handle?: Snippet<[{ pressed: boolean; label: string }]>;
+  /** Fires with the full reordered array and change metadata on drop. */
+  onreorder: (
+    nextItems: Item[],
+    change: import('../../utilities/sortable-controller.types.ts').SortableReorderChange,
+  ) => void;
+  /** Optional overrides for announcement strings. */
+  announcements?: Partial<
+    import('../../utilities/sortable-controller.types.ts').SortableAnnouncements
+  >;
+  /** Row content snippet. Receives the item and a per-row context. */
+  children: Snippet<
+    [Item, import('../../utilities/sortable-controller.types.ts').SortableItemContext]
+  >;
+  /** Accessible name for the list (applied as aria-label on the list root). */
+  label?: string;
+  /** Additional class merged onto the `.cinder-sortable-list` root element. */
+  class?: string;
+};

package/src/components/sortable-list/sortable-list.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/source-diff-viewer/index.ts

@@ -0,0 +1,18 @@
+import './source-diff-viewer.css';
+import SourceDiffViewer from './source-diff-viewer.svelte';
+
+export default SourceDiffViewer;
+export type {
+  SourceDiffFile,
+  SourceDiffHunk,
+  SourceDiffLine,
+  SourceDiffLineKind,
+  SourceDiffParseResult,
+  SourceDiffViewerProps,
+} from './source-diff-viewer.types.ts';
+export {
+  getSourceDiffFileLabel,
+  getSourceDiffLineLabel,
+  parseUnifiedPatch,
+} from './source-diff-viewer.utilities.ts';
+export { SourceDiffViewer };

package/src/components/source-diff-viewer/source-diff-viewer.schema.ts

@@ -0,0 +1,40 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    patch: {
+      type: 'string',
+      description: 'Unified patch text to parse and render.',
+    },
+    ariaLabel: {
+      type: 'string',
+      description: 'Accessible label for the diff region.',
+    },
+    maxLines: {
+      type: 'integer',
+      description: 'Maximum number of diff rows to render before truncating.',
+      minimum: 0,
+      default: 1000,
+    },
+    lineNumbers: {
+      type: 'boolean',
+      description: 'Whether old and new line-number gutters are rendered.',
+      default: true,
+    },
+    emptyMessage: {
+      type: 'string',
+      description: 'Message shown when the patch is empty or contains no diffable rows.',
+      default: 'No patch lines to display.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional CSS classes merged with `.cinder-source-diff-viewer`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['patch'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/source-diff-viewer/source-diff-viewer.svelte

@@ -0,0 +1,88 @@
+<script lang="ts" module>
+export { getSourceDiffFileLabel, getSourceDiffLineLabel, parseUnifiedPatch, } from './source-diff-viewer.utilities.ts';
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { getSourceDiffFileLabel, getSourceDiffLineLabel, parseUnifiedPatch, } from './source-diff-viewer.utilities.ts';
+let { patch, ariaLabel, 'aria-label': nativeAriaLabel, 'aria-labelledby': nativeAriaLabelledBy, maxLines = 1000, lineNumbers = true, emptyMessage = 'No patch lines to display.', class: className, ...rest } = $props();
+const parsedPatch = $derived(parseUnifiedPatch(patch, { maxLines }));
+const hasPatchContent = $derived(parsedPatch.files.length > 0 || parsedPatch.totalLineCount > 0);
+const normalizedAriaLabelledBy = $derived(normalizeAriaLabel(nativeAriaLabelledBy));
+const normalizedAriaLabel = $derived(normalizedAriaLabelledBy
+    ? undefined
+    : (normalizeAriaLabel(ariaLabel) ?? normalizeAriaLabel(nativeAriaLabel) ?? 'Source diff'));
+function getSourceDiffLineText(line) {
+    if (line.kind === 'metadata')
+        return line.metadataPrefix ? `${line.metadataPrefix} ${line.content}` : line.content;
+    const prefix = line.kind === 'addition' ? '+' : line.kind === 'removal' ? '-' : ' ';
+    return `${prefix}${line.content}`;
+}
+function normalizeAriaLabel(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+</script>
+
+<div
+  {...rest}
+  class={classNames('cinder-source-diff-viewer', className)}
+  role="region"
+  aria-label={normalizedAriaLabel}
+  aria-labelledby={normalizedAriaLabelledBy}
+>
+  {#if !hasPatchContent}
+    <p class="cinder-source-diff-viewer__empty">{emptyMessage}</p>
+  {:else}
+    {#if parsedPatch.truncated}
+      <div class="cinder-source-diff-viewer__notice" role="status">
+        Showing first {parsedPatch.renderedLineCount} of {parsedPatch.totalLineCount} diff lines.
+      </div>
+    {/if}
+
+    {#each parsedPatch.files as file, fileIndex (`${fileIndex}:${file.header ?? `${file.oldPath ?? ''}:${file.newPath ?? ''}`}`)}
+      {@const fileLabel = getSourceDiffFileLabel(file)}
+      <section class="cinder-source-diff-viewer__file" aria-label={fileLabel}>
+        <header class="cinder-source-diff-viewer__file-header">
+          <span class="cinder-source-diff-viewer__file-path">{fileLabel}</span>
+        </header>
+
+        {#if file.metadata.length > 0}
+          <div class="cinder-source-diff-viewer__metadata" role="group" aria-label="File metadata">
+            {#each file.metadata as metadataLine, metadataIndex (`${metadataIndex}:${metadataLine}`)}
+              <code>{metadataLine}</code>
+            {/each}
+          </div>
+        {/if}
+
+        {#each file.hunks as hunk, hunkIndex (`${hunkIndex}:${hunk.header}`)}
+          {#if hunk.lines.length > 0}
+            <div class="cinder-source-diff-viewer__hunk">
+              <div class="cinder-source-diff-viewer__hunk-header">{hunk.header}</div>
+              <section
+                class="cinder-source-diff-viewer__lines"
+                aria-label={`${fileLabel} ${hunk.header} lines`}
+              >
+                {#each hunk.lines as line, lineIndex (`${lineIndex}:${line.kind}:${line.oldLineNumber ?? ''}:${line.newLineNumber ?? ''}`)}
+                  <div class="cinder-source-diff-viewer__line" data-cinder-line-kind={line.kind}>
+                    {#if lineNumbers}
+                      <span class="cinder-source-diff-viewer__line-number" aria-hidden="true">
+                        {line.oldLineNumber ?? ''}
+                      </span>
+                      <span class="cinder-source-diff-viewer__line-number" aria-hidden="true">
+                        {line.newLineNumber ?? ''}
+                      </span>
+                    {/if}
+                    <span class="cinder-sr-only">{getSourceDiffLineLabel(line)}</span>
+                    <code class="cinder-source-diff-viewer__line-code" aria-hidden="true">
+                      {getSourceDiffLineText(line)}
+                    </code>
+                  </div>
+                {/each}
+              </section>
+            </div>
+          {/if}
+        {/each}
+      </section>
+    {/each}
+  {/if}
+</div>

package/src/components/source-diff-viewer/source-diff-viewer.types.ts

@@ -0,0 +1,50 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type SourceDiffLineKind = 'addition' | 'removal' | 'context' | 'metadata';
+
+export type SourceDiffLine = {
+  kind: SourceDiffLineKind;
+  content: string;
+  oldLineNumber: number | null;
+  newLineNumber: number | null;
+  metadataPrefix?: '\\';
+};
+
+export type SourceDiffHunk = {
+  header: string;
+  oldStart: number | null;
+  oldCount: number | null;
+  newStart: number | null;
+  newCount: number | null;
+  lines: SourceDiffLine[];
+};
+
+export type SourceDiffFile = {
+  oldPath: string | null;
+  newPath: string | null;
+  header: string | null;
+  metadata: string[];
+  hunks: SourceDiffHunk[];
+};
+
+export type SourceDiffParseResult = {
+  files: SourceDiffFile[];
+  totalLineCount: number;
+  renderedLineCount: number;
+  truncated: boolean;
+};
+
+export type SourceDiffViewerProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Unified patch text to parse and render. */
+  patch: string;
+  /** Accessible label for the diff region. */
+  ariaLabel?: string;
+  /** Maximum number of diff rows to render before truncating. */
+  maxLines?: number;
+  /** Whether old and new line-number gutters are rendered. */
+  lineNumbers?: boolean;
+  /** Message shown when the patch is empty or contains no diffable rows. */
+  emptyMessage?: string;
+  /** Additional CSS classes merged with `.cinder-source-diff-viewer`. */
+  class?: string;
+};