@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/data-table/data-table.svelte

@@ -16,6 +16,8 @@
 </script>
 
 <script lang="ts" generics="Row extends DataTableRow">
+  import { tick } from 'svelte';
+
   import TableBody from '../table-body/table-body.svelte';
   import TableCell from '../table-cell/table-cell.svelte';
   import TableHeaderCell from '../table-header-cell/table-header-cell.svelte';
@@ -24,6 +26,13 @@
   import TableRoot from '../table/table.svelte';
 
   import { classNames } from '../../utilities/class-names.ts';
+  import {
+    getFixedVirtualWindow,
+    parsePixelLength,
+    resolveVirtualItemHeight,
+    resolveVirtualOverscan,
+  } from '../../utilities/fixed-virtual-window.ts';
+  import { useResizeObserver } from '../../utilities/use-resize-observer.svelte.ts';
   import type { DataTableColumn, DataTableProps, DataTableRow } from './data-table.types.ts';
 
   let {
@@ -34,9 +43,26 @@
     stickyHeader = false,
     density = 'comfortable',
     scrollable = false,
+    virtualized = false,
+    rowHeight = 44,
+    overscan = 5,
+    height = '24rem',
+    stickToBottom = false,
+    onscroll: onScroll,
     class: className,
+    ...rest
   }: DataTableProps<Row> = $props();
 
+  let wrapperElement: HTMLElement | undefined = $state();
+  let scrollOffset = $state(0);
+  let measuredViewportHeight = $state(0);
+  let captionHeight = $state(0);
+  let headerHeight = $state(0);
+  let activeRowIndex = $state(0);
+  let previousRowCount = 0;
+  let hasObservedRowCount = false;
+  let shouldStickAfterAppend = false;
+
   /**
    * The key of the row-header column. Explicitly set via `column.rowHeader === true`,
    * or falls back to the first column's key. Used to render `<th scope="row">` on
@@ -45,6 +71,36 @@
   const rowHeaderKey = $derived(
     (columns.find((column) => column.rowHeader === true) ?? columns[0])?.key,
   );
+  const shouldVirtualizeRows = $derived(virtualized);
+  const resolvedRowHeight = $derived(resolveVirtualItemHeight(rowHeight, 44));
+  const resolvedOverscan = $derived(resolveVirtualOverscan(overscan));
+  const viewportHeight = $derived(
+    measuredViewportHeight || estimateViewportHeight(height, resolvedRowHeight),
+  );
+  const virtualWindow = $derived(
+    getFixedVirtualWindow({
+      itemCount: rows.length,
+      itemHeight: resolvedRowHeight,
+      scrollOffset,
+      viewportHeight,
+      overscan: resolvedOverscan,
+    }),
+  );
+  const virtualRows = $derived(
+    shouldVirtualizeRows
+      ? virtualWindow.items.flatMap((virtualItem) => {
+          const row = rows[virtualItem.index];
+          return row === undefined ? [] : [{ ...virtualItem, row }];
+        })
+      : rows.map((row, index) => ({
+          row,
+          index,
+          key: index,
+          start: index * resolvedRowHeight,
+          size: resolvedRowHeight,
+        })),
+  );
+  const tabbableRowIndex = $derived(getTabbableRowIndex());
 
   /**
    * Map a DataTableColumn's `align` value to the value accepted by TableHeaderCell
@@ -56,10 +112,218 @@
     if (align === 'center') return 'center';
     return undefined;
   }
+
+  $effect(() => {
+    const element = wrapperElement;
+    if (!element || !shouldVirtualizeRows) return;
+    syncScrollMetrics(element);
+  });
+
+  // Observe wrapper, caption, and header for size changes when virtualized.
+  // The wrapper uses an attachment (see template); caption and header are inner
+  // elements that can only be reached via querySelector after mount.
+  const observeWrapperResize = useResizeObserver(() => {
+    if (wrapperElement && shouldVirtualizeRows) syncScrollMetrics(wrapperElement);
+  });
+
+  $effect(() => {
+    const element = wrapperElement;
+    if (!element || !shouldVirtualizeRows || typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(() => syncScrollMetrics(element));
+    const caption = element.querySelector('caption');
+    if (caption) observer.observe(caption);
+    const header = element.querySelector('thead');
+    if (header) observer.observe(header);
+    return () => observer.disconnect();
+  });
+
+  $effect.pre(() => {
+    const rowCount = rows.length;
+    const element = wrapperElement;
+
+    if (!hasObservedRowCount) {
+      previousRowCount = rowCount;
+      hasObservedRowCount = true;
+      shouldStickAfterAppend = false;
+      return;
+    }
+
+    shouldStickAfterAppend =
+      shouldVirtualizeRows &&
+      stickToBottom &&
+      element !== undefined &&
+      rowCount > previousRowCount &&
+      isAtBottom(
+        element,
+        previousRowCount * resolvedRowHeight,
+        viewportHeight,
+        getTableChromeHeight(captionHeight, headerHeight),
+      );
+
+    previousRowCount = rowCount;
+  });
+
+  $effect(() => {
+    const rowCount = rows.length;
+    const element = wrapperElement;
+    if (!shouldVirtualizeRows || !stickToBottom || !shouldStickAfterAppend || !element) return;
+
+    void tick().then(() => {
+      element.scrollTop = maxScrollTop(
+        rowCount * resolvedRowHeight,
+        viewportHeight,
+        getTableChromeHeight(captionHeight, headerHeight),
+      );
+      syncScrollMetrics(element);
+      shouldStickAfterAppend = false;
+    });
+  });
+
+  function estimateViewportHeight(value: string | undefined, fallbackRowHeight: number): number {
+    return parsePixelLength(value) ?? fallbackRowHeight * 10;
+  }
+
+  function getCaptionHeight(element: HTMLElement): number {
+    const captionElement = element.querySelector<HTMLElement>('caption');
+    if (!captionElement) return 0;
+    const rect = captionElement.getBoundingClientRect();
+    return rect.height || captionElement.offsetHeight || 0;
+  }
+
+  function getHeaderHeight(element: HTMLElement): number {
+    const header = element.querySelector<HTMLElement>('thead');
+    if (!header) return 0;
+    const rect = header.getBoundingClientRect();
+    return rect.height || header.offsetHeight || 0;
+  }
+
+  function syncScrollMetrics(element: HTMLElement): void {
+    const rect = element.getBoundingClientRect();
+    const nextCaptionHeight = getCaptionHeight(element);
+    const nextHeaderHeight = getHeaderHeight(element);
+    measuredViewportHeight =
+      rect.height || element.clientHeight || parsePixelLength(height) || resolvedRowHeight * 10;
+    captionHeight = nextCaptionHeight;
+    headerHeight = nextHeaderHeight;
+    scrollOffset = Math.max(
+      0,
+      element.scrollTop - getBodyScrollOrigin(nextCaptionHeight, nextHeaderHeight),
+    );
+  }
+
+  function handleWrapperScroll(
+    event: UIEvent & { currentTarget: EventTarget & HTMLDivElement },
+  ): void {
+    if (typeof onScroll === 'function') onScroll(event);
+    if (!shouldVirtualizeRows) return;
+    syncScrollMetrics(event.currentTarget as HTMLElement);
+  }
+
+  function maxScrollTop(totalBodyHeight: number, visibleHeight: number, chromeBlockSize: number) {
+    return Math.max(0, chromeBlockSize + totalBodyHeight - visibleHeight);
+  }
+
+  function getTableChromeHeight(captionBlockSize: number, headerBlockSize: number): number {
+    return captionBlockSize + headerBlockSize;
+  }
+
+  function getBodyScrollOrigin(captionBlockSize: number, headerBlockSize: number): number {
+    return stickyHeader
+      ? captionBlockSize
+      : getTableChromeHeight(captionBlockSize, headerBlockSize);
+  }
+
+  function getTabbableRowIndex(): number {
+    if (!shouldVirtualizeRows) return activeRowIndex;
+    if (virtualRows.some((virtualRow) => virtualRow.index === activeRowIndex)) {
+      return activeRowIndex;
+    }
+    return virtualRows[0]?.index ?? activeRowIndex;
+  }
+
+  function isAtBottom(
+    element: HTMLElement,
+    totalBodyHeight: number,
+    visibleHeight: number,
+    chromeBlockSize: number,
+  ): boolean {
+    return element.scrollTop >= maxScrollTop(totalBodyHeight, visibleHeight, chromeBlockSize) - 1;
+  }
+
+  function clampRowIndex(index: number): number {
+    return Math.min(Math.max(0, index), Math.max(0, rows.length - 1));
+  }
+
+  function scrollToRow(index: number): void {
+    const element = wrapperElement;
+    if (!element) return;
+
+    const rowScrollTop =
+      index === 0
+        ? 0
+        : getBodyScrollOrigin(captionHeight, headerHeight) + index * resolvedRowHeight;
+
+    element.scrollTop = Math.min(
+      maxScrollTop(
+        rows.length * resolvedRowHeight,
+        viewportHeight,
+        getTableChromeHeight(captionHeight, headerHeight),
+      ),
+      rowScrollTop,
+    );
+    syncScrollMetrics(element);
+  }
+
+  function focusRow(index: number): void {
+    const nextIndex = clampRowIndex(index);
+    activeRowIndex = nextIndex;
+    scrollToRow(nextIndex);
+
+    void tick().then(() => {
+      const row = wrapperElement?.querySelector<HTMLElement>(
+        `[data-cinder-data-table-row-index="${nextIndex}"]`,
+      );
+      row?.focus({ preventScroll: true });
+    });
+  }
+
+  function handleRowFocus(index: number): void {
+    activeRowIndex = clampRowIndex(index);
+  }
+
+  function handleRowKeydown(event: KeyboardEvent, index: number): void {
+    if (!shouldVirtualizeRows) return;
+
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      focusRow(index + 1);
+      return;
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      focusRow(index - 1);
+      return;
+    }
+    if (event.key === 'Home') {
+      event.preventDefault();
+      focusRow(0);
+      return;
+    }
+    if (event.key === 'End') {
+      event.preventDefault();
+      focusRow(rows.length - 1);
+    }
+  }
 </script>
 
 {#snippet table()}
-  <TableRoot {...caption !== undefined ? { caption } : {}} {stickyHeader} {density} bind:sort>
+  <TableRoot
+    {...caption !== undefined ? { caption } : {}}
+    {...shouldVirtualizeRows ? { 'aria-rowcount': rows.length + 1 } : {}}
+    {stickyHeader}
+    {density}
+    bind:sort
+  >
     <TableHeader>
       <TableRow>
         {#each columns as column (column.key)}
@@ -79,28 +343,66 @@
            unique, so keying by them would corrupt row identity when two rows
            share a value. DataTable does not reorder rows itself, so the index
            is a stable identity for the consumer-owned ordering. -->
-      {#each rows as row, rowIndex (rowIndex)}
-        <TableRow>
+      {#if shouldVirtualizeRows && virtualWindow.leadingSize > 0}
+        <tr class="cinder-data-table__virtual-spacer" aria-hidden="true">
+          <td
+            class="cinder-data-table__virtual-spacer-cell"
+            colspan={columns.length}
+            style:height={`${virtualWindow.leadingSize}px`}
+          ></td>
+        </tr>
+      {/if}
+      {#each virtualRows as virtualRow (virtualRow.key)}
+        <TableRow
+          {...shouldVirtualizeRows
+            ? {
+                'aria-rowindex': virtualRow.index + 2,
+                tabindex: tabbableRowIndex === virtualRow.index ? 0 : -1,
+                'data-cinder-virtual-row': 'true',
+                'data-cinder-data-table-row-index': virtualRow.index,
+                onfocus: () => handleRowFocus(virtualRow.index),
+                onkeydown: (event: KeyboardEvent) => handleRowKeydown(event, virtualRow.index),
+              }
+            : {}}
+        >
           {#each columns as column (column.key)}
             <TableCell
               as={column.key === rowHeaderKey ? 'th' : 'td'}
               align={mapAlign(column.align) ?? 'left'}
             >
-              {row[column.key]}
+              {virtualRow.row[column.key]}
             </TableCell>
           {/each}
         </TableRow>
       {/each}
+      {#if shouldVirtualizeRows && virtualWindow.trailingSize > 0}
+        <tr class="cinder-data-table__virtual-spacer" aria-hidden="true">
+          <td
+            class="cinder-data-table__virtual-spacer-cell"
+            colspan={columns.length}
+            style:height={`${virtualWindow.trailingSize}px`}
+          ></td>
+        </tr>
+      {/if}
     </TableBody>
   </TableRoot>
 {/snippet}
 
-{#if scrollable}
-  <div class={classNames('cinder-data-table', 'cinder-table-scroll', className)}>
-    {@render table()}
-  </div>
-{:else}
-  <div class={classNames('cinder-data-table', className)}>
-    {@render table()}
-  </div>
-{/if}
+<div
+  {...rest}
+  bind:this={wrapperElement}
+  {@attach observeWrapperResize}
+  class={classNames(
+    'cinder-data-table',
+    scrollable || shouldVirtualizeRows ? 'cinder-table-scroll' : undefined,
+    className,
+  )}
+  data-cinder-virtualized={shouldVirtualizeRows ? 'true' : undefined}
+  style:--cinder-data-table-height={shouldVirtualizeRows ? height : undefined}
+  style:--_cinder-data-table-row-height={shouldVirtualizeRows
+    ? `${resolvedRowHeight}px`
+    : undefined}
+  onscroll={handleWrapperScroll}
+>
+  {@render table()}
+</div>

package/src/components/data-table/data-table.types.ts

@@ -1,3 +1,5 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
 import type { TableDensity, TableSort } from '../table/table.types.ts';
 
 /**
@@ -52,7 +54,10 @@ export type DataTableColumn<Row extends DataTableRow = DataTableRow> = {
  *
  * @template Row - The row record type. Defaults to `DataTableRow`.
  */
-export type DataTableProps<Row extends DataTableRow = DataTableRow> = {
+export type DataTableProps<Row extends DataTableRow = DataTableRow> = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class'
+> & {
   /** Column descriptors defining the headers and cell rendering for each column. */
   columns: DataTableColumn<Row>[];
   /** Row data. Each entry is read via `column.key` for each column. */
@@ -80,6 +85,35 @@ export type DataTableProps<Row extends DataTableRow = DataTableRow> = {
    * enables horizontal overflow scrolling on small viewports.
    */
   scrollable?: boolean;
+  /**
+   * When true, renders only the visible `<tbody>` row window plus spacer rows.
+   * Requires a fixed row height. This is intended for large, append-only tables
+   * such as live logs or event streams.
+   */
+  virtualized?: boolean;
+  /**
+   * Fixed body row height in pixels for virtualized mode.
+   * This must match the actual rendered body row height, including density
+   * padding and any wrapping introduced by the table content.
+   * Defaults to 44.
+   */
+  rowHeight?: number;
+  /**
+   * Extra body rows rendered before and after the visible virtualized window.
+   * Defaults to 5.
+   */
+  overscan?: number;
+  /**
+   * CSS block-size for the virtualized native scroll container.
+   * Defaults to `"24rem"` when `virtualized` is true.
+   */
+  height?: string;
+  /**
+   * When true in virtualized mode, appending rows while scrolled to the bottom
+   * keeps the newest row pinned in view. Appending while scrolled up does not
+   * change the viewport.
+   */
+  stickToBottom?: boolean;
   /**
    * Additional class names merged onto DataTable's root wrapper element (the
    * `<div class="cinder-data-table">` that contains the table). To style the

package/src/components/date-range-field/README.md

@@ -0,0 +1,142 @@
+# DateRangeField
+
+Controlled start/end date range picker with preset shortcuts and validation feedback, designed for time-window filtering on dashboards, event streams, and audit logs.
+
+## Overview
+
+`DateRangeField` renders two native date or date-time inputs (start and end) along with a row of preset shortcut buttons (Today, Yesterday & today, Last 7 days by default). It is fully controlled: the consumer owns the `value` and responds to `onchange` callbacks. It does not own routing, query-string synchronization, timezone conversion, or data fetching.
+
+Values are ISO-8601 local strings. `granularity="day"` emits `YYYY-MM-DD`; `granularity="hour"`, `"minute"`, and `"second"` use native `datetime-local` inputs and emit values truncated to the selected precision.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { DateRangeField } from '@lostgradient/cinder/date-range-field';
+  import type { DateRangeValue } from '@lostgradient/cinder/date-range-field';
+
+  let range: DateRangeValue = $state({ start: undefined, end: undefined });
+</script>
+
+<DateRangeField
+  id="event-time-filter"
+  label="Time window"
+  bind:value={range}
+  onchange={(next) => {
+    range = next;
+  }}
+/>
+```
+
+### With custom presets
+
+```svelte
+<script lang="ts">
+  import { DateRangeField } from '@lostgradient/cinder/date-range-field';
+  import type { DateRangeDatePreset, DateRangeValue } from '@lostgradient/cinder/date-range-field';
+
+  let range: DateRangeValue = $state({ start: undefined, end: undefined });
+
+  function formatLocalDate(date: Date): string {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+  }
+
+  const presets: DateRangeDatePreset[] = [
+    {
+      id: 'today',
+      label: 'Today',
+      resolve: () => {
+        const today = formatLocalDate(new Date());
+        return { start: today, end: today };
+      },
+    },
+    {
+      id: 'this-month',
+      label: 'This month',
+      resolve: () => {
+        const now = new Date();
+        const start = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-01`;
+        const end = formatLocalDate(now);
+        return { start, end };
+      },
+    },
+  ];
+</script>
+
+<DateRangeField id="billing-filter" label="Billing period" {presets} bind:value={range} />
+```
+
+### With validation error
+
+```svelte
+<script lang="ts">
+  import { DateRangeField } from '@lostgradient/cinder/date-range-field';
+  import type { DateRangeValue } from '@lostgradient/cinder/date-range-field';
+
+  let range: DateRangeValue = $state({ start: undefined, end: undefined });
+
+  let error = $derived(
+    range.start && range.end && range.start > range.end
+      ? 'Start date must be on or before the end date.'
+      : undefined,
+  );
+</script>
+
+<DateRangeField id="validated-filter" label="Date range" bind:value={range} {error} />
+```
+
+## Props
+
+```
+id           string               no        Unique identifier for label and ARIA wiring. Generated via `$props.id()` when omitted.
+value        DateRangeValue       no        Current range. Bindable. Both fields start undefined.
+label        string               no        Visible legend rendered above the inputs.
+startLabel   string               no        Label for the start input. Default: "Start date".
+endLabel     string               no        Label for the end input. Default: "End date".
+granularity  DateRangeGranularity no        Precision for native inputs: day, hour, minute, or second. Default: day.
+presets      DateRangeDatePreset[]  no      Custom preset buttons. Defaults to today, yesterday-today, last-7d.
+hidePresets  boolean              no        When true, hides the preset row. Default: false.
+description  string               no        Helper text below the field, wired via aria-describedby.
+error        string               no        Validation error. Sets aria-invalid="true" on inputs.
+disabled     boolean              no        Disables all inputs and preset buttons. Default: false.
+class        string               no        Additional CSS classes on the root element.
+onchange     (value) => void      no        Called when the range changes via preset or manual input.
+```
+
+## Types
+
+```ts
+type DateRangeValue = {
+  start: string | undefined; // ISO-8601 local date or datetime string
+  end: string | undefined; // ISO-8601 local date or datetime string
+};
+
+type DateRangeDatePreset = {
+  id: string;
+  label: string;
+  resolve: () => DateRangeValue;
+};
+```
+
+## Accessibility
+
+The component implements accessible form labelling throughout:
+
+- Each date input is associated with a `<label>` via `for`/`id`.
+- The optional legend (`label` prop) is a `<p>` associated with the group visually.
+- The preset button row carries `role="group"` with `aria-label="Date range presets"`.
+- Each preset button carries `aria-pressed` to communicate current selection state to assistive technology.
+- The error region uses `aria-live="polite"` and is always in the DOM so screen readers reliably pick up the live region before text is injected.
+- When `error` is set, both inputs carry `aria-invalid="true"`.
+- The root carries `role="group"` and `aria-labelledby` pointing to the legend element when a `label` prop is provided, associating the label with the start/end input group.
+- `description` and `error` elements are wired into each input via `aria-describedby`, so a screen reader user tabbing to an input hears the description and any active error.
+- Forced-colors (Windows High Contrast) mode: inputs and preset buttons receive a solid `outline` instead of `box-shadow` focus rings, which are ignored in that mode.
+
+## Scope limits
+
+- Timezone conversion is caller-owned. Native `datetime-local` values are local wall-clock strings without timezone offsets.
+- The browser owns the date and date-time picker UI. Keyboard behavior inside those native pickers is browser-controlled.
+- No range constraint enforcement. The component sets `min`/`max` on the inputs to hint the browser's picker (end min = start, start max = end), but does not block the user from entering out-of-order values programmatically. Validation is the consumer's responsibility via the `error` prop.