@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/context-menu-trigger/context-menu-trigger.svelte

@@ -17,7 +17,6 @@
 
 <script lang="ts">
   import type { ContextMenuTriggerProps } from './context-menu-trigger.types.ts';
-  import { onDestroy } from 'svelte';
   import { classNames } from '../../utilities/class-names.ts';
   import { getDropdownRegisterTrigger } from '../dropdown/dropdown.context.ts';
   import { getContextMenuContext } from '../context-menu/context-menu.context.ts';
@@ -51,12 +50,14 @@
     currentTarget: EventTarget & HTMLDivElement;
   };
 
-  $effect(() => {
-    registerTrigger(triggerElement);
+  function attachTrigger(node: HTMLDivElement) {
+    registerTrigger(node);
     return () => registerTrigger(null);
-  });
+  }
 
-  onDestroy(clearLongPress);
+  $effect(() => {
+    return () => clearLongPress();
+  });
 
   function clearLongPress() {
     clearTimeout(longPressTimer);
@@ -142,7 +143,8 @@
     event.preventDefault();
     const target = event.target instanceof HTMLElement ? event.target : triggerElement;
     const rect = target?.getBoundingClientRect() ?? triggerElement?.getBoundingClientRect();
-    context.openAt(rect?.left ?? 0, rect?.bottom ?? 0);
+    const x = context.direction === 'rtl' ? rect?.right : rect?.left;
+    context.openAt(x ?? 0, rect?.bottom ?? 0);
     callTriggerHandler(onkeydown, event);
   }
 
@@ -164,6 +166,7 @@
 
 <div
   bind:this={triggerElement}
+  {@attach attachTrigger}
   class={classNames('cinder-context-menu-trigger', className)}
   aria-haspopup="menu"
   oncontextmenu={handleContextmenu}

package/src/components/copy-button/copy-button.svelte

@@ -17,7 +17,6 @@
 
 <script lang="ts">
   import type { CopyButtonProps } from './copy-button.types.ts';
-  import { onDestroy } from 'svelte';
 
   import Check from 'lucide-svelte/icons/check';
   import Copy from 'lucide-svelte/icons/copy';
@@ -62,8 +61,10 @@
     }, confirmDuration);
   }
 
-  onDestroy(() => {
-    if (resetTimer) clearTimeout(resetTimer);
+  $effect(() => {
+    return () => {
+      if (resetTimer) clearTimeout(resetTimer);
+    };
   });
 </script>
 

package/src/components/data-grid/README.md

@@ -33,7 +33,7 @@ ARIA data grid foundation for spreadsheet-like datasets with stable row identity
 ### Avoid When
 
 - You only need a semantic read-only table — use DataTable or the Table family instead.
-- You need sorting, virtualization, resize handles, drag-to-reorder controls, or editing today.
+- You need resize handles, drag-to-reorder controls, or editing today.
 
 ## Props
 
@@ -55,8 +55,8 @@ ARIA data grid foundation for spreadsheet-like datasets with stable row identity
 | `columns`                | `(opaque)`                                     | yes      | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                               |
 | `getRowAriaLabel`        | `(opaque)`                                     | no       | —       | Optional accessible row label for screen-reader row summaries. Not expressible in JSON Schema; see the component types for the signature.             |
 | `getRowId`               | `(opaque)`                                     | yes      | —       | Stable row identity used for ARIA ids and row-scoped state. Not expressible in JSON Schema; see the component types for the signature.                |
-| `onSelectionModelChange` | `(opaque)`                                     | no       | —       | Called when row selection changes through cell interaction. Not expressible in JSON Schema; see the component types for the signature.                |
-| `onSortModelChange`      | `(opaque)`                                     | no       | —       | Called after the user changes sort order and DataGrid updates `sortModel`. Not expressible in JSON Schema; see the component types for the signature. |
+| `onselectionmodelchange` | `(opaque)`                                     | no       | —       | Called when row selection changes through cell interaction. Not expressible in JSON Schema; see the component types for the signature.                |
+| `onsortmodelchange`      | `(opaque)`                                     | no       | —       | Called after the user changes sort order and DataGrid updates `sortModel`. Not expressible in JSON Schema; see the component types for the signature. |
 | `rowClass`               | `(opaque)`                                     | no       | —       | Additional class names for body rows. Not expressible in JSON Schema; see the component types for the signature.                                      |
 | `rows`                   | `(opaque)`                                     | yes      | —       | A generically typed prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                              |
 | `sortModel`              | `(opaque)`                                     | no       | —       | Controls the row sort order used to render rows. Not expressible in JSON Schema; see the component types for the signature.                           |

package/src/components/data-grid/_internal/column-model.svelte.ts

@@ -13,6 +13,7 @@ export const DEFAULT_DATA_GRID_COLUMN_MIN_WIDTH = 60;
 
 export type DataGridValueColumn<TRow> = {
   key: string;
+  rowHeader?: boolean;
   sortable?: boolean;
   sortComparator?: DataGridSortComparator<TRow>;
   getValue?: (row: TRow) => unknown;
@@ -148,6 +149,7 @@ function resolveColumn<TRow>(
   };
   if (column.cell !== undefined) resolvedColumn.cell = column.cell;
   if (column.maxWidth !== undefined) resolvedColumn.maxWidth = column.maxWidth;
+  if (column.rowHeader !== undefined) resolvedColumn.rowHeader = column.rowHeader;
   if (column.sortable !== undefined) resolvedColumn.sortable = column.sortable;
   if (column.sortComparator !== undefined) resolvedColumn.sortComparator = column.sortComparator;
   if (column.getValue !== undefined) resolvedColumn.getValue = column.getValue;

package/src/components/data-grid/data-grid.css

@@ -9,6 +9,7 @@
     inline-size: 100%;
     max-inline-size: 100%;
     overflow: auto;
+    scrollbar-gutter: stable;
     border: 1px solid var(--cinder-border);
     border-radius: var(--cinder-radius-md);
     background: var(--cinder-surface);
@@ -18,11 +19,25 @@
     -webkit-overflow-scrolling: touch;
   }
 
+  .cinder-data-grid[data-cinder-virtualized-columns='true'] {
+    --_cinder-data-grid-overflow-shadow:
+      inset 1rem 0 1rem -1rem color-mix(in srgb, var(--cinder-text) 28%, transparent),
+      inset -1rem 0 1rem -1rem color-mix(in srgb, var(--cinder-text) 28%, transparent);
+  }
+
   .cinder-data-grid:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-data-grid:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(-1 * var(--cinder-ring-width));
+      box-shadow: none;
+    }
+  }
+
   .cinder-data-grid__header-row,
   .cinder-data-grid__row {
     display: grid;
@@ -33,6 +48,7 @@
 
   .cinder-data-grid__header-row {
     background: var(--cinder-surface-inset);
+    box-shadow: var(--_cinder-data-grid-overflow-shadow, none);
   }
 
   .cinder-data-grid[data-cinder-sticky-header] .cinder-data-grid__header-row {
@@ -43,6 +59,7 @@
 
   .cinder-data-grid__row {
     background: var(--cinder-surface);
+    box-shadow: var(--_cinder-data-grid-overflow-shadow, none);
     transition: background var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
@@ -117,6 +134,14 @@
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-data-grid__sort-button:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 2px;
+      box-shadow: none;
+    }
+  }
+
   .cinder-data-grid__header-content {
     min-inline-size: 0;
     overflow: hidden;

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

@@ -84,9 +84,9 @@
     columnPinning,
     selectionMode = 'none',
     selectionModel = $bindable<DataGridSelectionModel | undefined>(undefined),
-    onSelectionModelChange,
+    onselectionmodelchange,
     sortModel = $bindable([]),
-    onSortModelChange,
+    onsortmodelchange,
     rowClass,
     getRowAriaLabel,
     class: className,
@@ -586,7 +586,7 @@
 
     const nextSortModel = getNextDataGridSortModel(activeSortModel, column.key, event.shiftKey);
     sortModel = nextSortModel;
-    onSortModelChange?.(nextSortModel);
+    onsortmodelchange?.(nextSortModel);
   }
 
   function getCellCoordinate(
@@ -644,7 +644,7 @@
 
   function setSelectionModel(nextSelectionModel: DataGridSelectionModel): void {
     selectionModel = nextSelectionModel;
-    onSelectionModelChange?.(nextSelectionModel);
+    onselectionmodelchange?.(nextSelectionModel);
   }
 
   function updateRowSelection(rowId: string, event: MouseEvent | KeyboardEvent): void {
@@ -981,7 +981,7 @@
         aria-rowindex={rowIndex + 2}
         aria-label={getResolvedRowAriaLabel(row, rowIndex)}
         aria-selected={selectedRowIds.has(rowId) ? 'true' : undefined}
-        data-cinder-selected={selectedRowIds.has(rowId) ? 'true' : undefined}
+        data-cinder-selected={selectedRowIds.has(rowId) ? '' : undefined}
         data-cinder-virtual-index={rowIndex}
         style={getRowStyle(renderedRow)}
       >
@@ -994,13 +994,13 @@
           <div
             id={cellId}
             class="cinder-data-grid__cell"
-            role="gridcell"
+            role={column.rowHeader ? 'rowheader' : 'gridcell'}
             aria-colindex={column.colIndex}
             aria-selected={isSelectedCell ? 'true' : undefined}
             tabindex="-1"
             data-cinder-pin={column.pin}
             data-cinder-active={activeCellId === cellId ? 'true' : undefined}
-            data-cinder-selected={isSelectedCell ? 'true' : undefined}
+            data-cinder-selected={isSelectedCell ? '' : undefined}
             data-cinder-anchor={isAnchorCell ? 'true' : undefined}
             data-cinder-row-id={rowId}
             data-cinder-row-dom-id={rowDomId}

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

@@ -43,6 +43,12 @@ type DataGridBaseColumnDef<TRow> = {
   maxWidth?: number;
   /** Pin this column to the left or right edge of the horizontal scroller. */
   pin?: DataGridColumnPin;
+  /**
+   * Render body cells in this column as row headers (`role="rowheader"`).
+   * Use this for the column that uniquely identifies each row, such as the
+   * value returned by `getRowId`.
+   */
+  rowHeader?: boolean;
   /** Enables header-click sorting for this column. */
   sortable?: boolean;
 };
@@ -104,11 +110,11 @@ export type DataGridProps<TRow = Record<string, unknown>> = Omit<
   /** Controlled row-selection ids, keyed by `getRowId`. */
   selectionModel?: DataGridSelectionModel | undefined;
   /** Called when row selection changes through cell interaction. */
-  onSelectionModelChange?: (selectionModel: DataGridSelectionModel) => void;
+  onselectionmodelchange?: (selectionModel: DataGridSelectionModel) => void;
   /** Controls the row sort order used to render rows. */
   sortModel?: DataGridSortModel;
   /** Called after the user changes sort order and DataGrid updates `sortModel`. */
-  onSortModelChange?: (sortModel: DataGridSortModel) => void;
+  onsortmodelchange?: (sortModel: DataGridSortModel) => void;
   /** Additional class names merged onto the root grid. */
   class?: string;
   /** Additional class names for body rows. */

package/src/components/data-list/README.md

@@ -24,7 +24,7 @@ for tabular rows and columns use [`Table`](../table/README.md).
   ];
 </script>
 
-<DataList items={members} density="condensed">
+<DataList items={members} key={(member) => member.id} density="condensed">
   {#snippet children(member)}
     <StackedListItem>
       {#snippet title()}{member.name}{/snippet}
@@ -45,14 +45,14 @@ set its own `density` prop. The `empty` snippet renders inside a component-owned
 
 <!-- generated:props:start -->
 
-| Prop       | Type                             | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ---------- | -------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`                         | no       | —       | Additional class merged onto the `.cinder-data-list` root element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `density`  | `"comfortable"` \| `"condensed"` | no       | —       | List-level density inherited by StackedListItem rows that do not set their own `density` prop. Omit to let each row use its own default. A per-row `density` always overrides this list-level value. Note: when passing a variable that may be `undefined`, spread conditionally because `exactOptionalPropertyTypes` is enabled: `{...(density ? { density } : {})}`                                                                                                                                                                                                            |
-| `children` | `(opaque)`                       | yes      | —       | Row renderer. MUST render an `<li>` (the list root is a `<ul role="list">`). StackedListItem is the recommended row — it renders an `<li>` with leading/title/description/meta/trailing slots. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                        |
-| `empty`    | `(opaque)`                       | no       | —       | Rendered when `items` is empty. The component automatically wraps the snippet output in `<li class="cinder-data-list-empty">`. **Do NOT wrap in an `<li>` yourself** — the component provides the `<li>` wrapper automatically. Pass only inner content (e.g. a `<p>`, a `<div>`, or plain text). Contrast with `children`, which must render an `<li>`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                              |
-| `items`    | `(opaque)`                       | yes      | —       | The records to render. Each is passed to `children`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `key`      | `(opaque)`                       | no       | —       | Key extractor for efficient DOM updates. Svelte uses this to identify each row when the list is reordered, filtered, or updated — without it, rows are matched by index and the wrong row instances may receive updated props. Strongly recommended for any list that can change after initial render: `svelte <DataList {items} key={(m) => m.id}> ` Omit only for truly static, never-reordered lists (e.g. a fixed reference list). When omitted, Svelte falls back to index-based reconciliation. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop       | Type                             | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------- | -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                         | no       | —       | Additional class merged onto the `.cinder-data-list` root element.                                                                                                                                                                                                                                                                                                                                                                  |
+| `density`  | `"comfortable"` \| `"condensed"` | no       | —       | List-level density inherited by StackedListItem rows that do not set their own `density` prop. Omit to let each row use its own default. A per-row `density` always overrides this list-level value. Note: when passing a variable that may be `undefined`, spread conditionally because `exactOptionalPropertyTypes` is enabled: `{...(density ? { density } : {})}`                                                               |
+| `children` | `(opaque)`                       | yes      | —       | Row renderer. MUST render an `<li>` (the list root is a `<ul role="list">`). StackedListItem is the recommended row — it renders an `<li>` with leading/title/description/meta/trailing slots. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                           |
+| `empty`    | `(opaque)`                       | no       | —       | Rendered when `items` is empty. The component automatically wraps the snippet output in `<li class="cinder-data-list-empty">`. **Do NOT wrap in an `<li>` yourself** — the component provides the `<li>` wrapper automatically. Pass only inner content (e.g. a `<p>`, a `<div>`, or plain text). Contrast with `children`, which must render an `<li>`. Not expressible in JSON Schema; see the component types for the signature. |
+| `items`    | `(opaque)`                       | yes      | —       | The records to render. Each is passed to `children`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                     |
+| `key`      | `(opaque)`                       | yes      | —       | Key extractor for stable DOM reconciliation. Svelte uses this to identify each row when the list is reordered, filtered, or updated. Without a key, rows are matched by index and the wrong row instances may receive updated props, causing O(n) churn and incorrect rendering. `svelte <DataList {items} key={(m) => m.id}> ` Not expressible in JSON Schema; see the component types for the signature.                          |
 
 <!-- generated:props:end -->
 

package/src/components/data-list/data-list.examples.json

@@ -13,7 +13,7 @@
       "id": "empty",
       "title": "Empty state fallback",
       "description": "When items is empty, the empty snippet renders inside a component-owned `<li class=\"cinder-data-list-empty\">` — centered, muted padding, no inline styles required.",
-      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n\n  const members: { id: string; name: string }[] = [];\n</script>\n\n<DataList items={members}>\n  {#snippet children(member)}\n    <StackedListItem>\n      {#snippet title()}{member.name}{/snippet}\n    </StackedListItem>\n  {/snippet}\n  {#snippet empty()}\n    No team members yet.\n  {/snippet}\n</DataList>\n"
+      "code": "<script lang=\"ts\">\n  import { DataList } from '@lostgradient/cinder/data-list';\n  import { StackedListItem } from '@lostgradient/cinder/stacked-list-item';\n\n  const members: { id: string; name: string }[] = [];\n</script>\n\n<DataList items={members} key={(m) => m.id}>\n  {#snippet children(member)}\n    <StackedListItem>\n      {#snippet title()}{member.name}{/snippet}\n    </StackedListItem>\n  {/snippet}\n  {#snippet empty()}\n    No team members yet.\n  {/snippet}\n</DataList>\n"
     }
   ]
 }

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

@@ -49,15 +49,9 @@
 -->
 <ul {...rest} class={classNames('cinder-data-list', className)} role="list">
   {#if items.length > 0}
-    {#if key}
-      {#each items as entry (key(entry))}
-        {@render children(entry)}
-      {/each}
-    {:else}
-      {#each items as entry}
-        {@render children(entry)}
-      {/each}
-    {/if}
+    {#each items as entry (key(entry))}
+      {@render children(entry)}
+    {/each}
   {:else if empty}
     <li class="cinder-data-list-empty">
       {@render empty()}

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

@@ -13,20 +13,16 @@ export type DataListProps<T> = Omit<
   /** The records to render. Each is passed to `children`. */
   items: T[];
   /**
-   * Key extractor for efficient DOM updates. Svelte uses this to identify each
-   * row when the list is reordered, filtered, or updated — without it, rows are
-   * matched by index and the wrong row instances may receive updated props.
-   *
-   * Strongly recommended for any list that can change after initial render:
+   * Key extractor for stable DOM reconciliation. Svelte uses this to identify
+   * each row when the list is reordered, filtered, or updated. Without a key,
+   * rows are matched by index and the wrong row instances may receive updated
+   * props, causing O(n) churn and incorrect rendering.
    *
    * ```svelte
    * <DataList {items} key={(m) => m.id}>
    * ```
-   *
-   * Omit only for truly static, never-reordered lists (e.g. a fixed reference
-   * list). When omitted, Svelte falls back to index-based reconciliation.
    */
-  key?: (item: T) => string | number;
+  key: (item: T) => string | number;
   /**
    * List-level density inherited by StackedListItem rows that do not set their
    * own `density` prop. Omit to let each row use its own default. A per-row

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

@@ -42,12 +42,25 @@
     block-size: var(--_cinder-data-table-row-height, 44px);
   }
 
+  .cinder-data-table tbody .cinder-table__row:focus-within {
+    background: var(--cinder-surface-hover);
+  }
+
   .cinder-data-table[data-cinder-virtualized]
     .cinder-table__row[data-cinder-virtual-row]:focus-visible {
     outline: var(--cinder-ring-width) solid transparent;
     box-shadow: var(--_cinder-focus-ring-shadow);
   }
 
+  @media (forced-colors: active) {
+    .cinder-data-table[data-cinder-virtualized]
+      .cinder-table__row[data-cinder-virtual-row]:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(-1 * var(--cinder-ring-width));
+      box-shadow: none;
+    }
+  }
+
   .cinder-data-table__virtual-spacer-cell {
     padding: 0;
     border: 0;

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

@@ -32,6 +32,7 @@
     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 {
@@ -115,12 +116,20 @@
   $effect(() => {
     const element = wrapperElement;
     if (!element || !shouldVirtualizeRows) return;
-
     syncScrollMetrics(element);
-    if (typeof ResizeObserver === 'undefined') return;
+  });
+
+  // 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));
-    observer.observe(element);
     const caption = element.querySelector('caption');
     if (caption) observer.observe(caption);
     const header = element.querySelector('thead');
@@ -382,6 +391,7 @@
 <div
   {...rest}
   bind:this={wrapperElement}
+  {@attach observeWrapperResize}
   class={classNames(
     'cinder-data-table',
     scrollable || shouldVirtualizeRows ? 'cinder-table-scroll' : undefined,

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

@@ -4,9 +4,9 @@ Controlled start/end date range picker with preset shortcuts and validation feed
 
 ## Overview
 
-`DateRangeField` renders two native date 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, or data fetching.
+`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.
 
-**v1 ships date-only.** Dates are expressed as ISO-8601 date strings (`YYYY-MM-DD`). Date-time support (hours, minutes, seconds, timezone) is a planned follow-up — it doubles the surface area with timezone complexity and time-picker UI. See the open GitHub issue for tracking demand.
+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
 
@@ -96,6 +96,7 @@ value        DateRangeValue       no        Current range. Bindable. Both fields
 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.
@@ -109,8 +110,8 @@ onchange     (value) => void      no        Called when the range changes via pr
 
 ```ts
 type DateRangeValue = {
-  start: string | undefined; // ISO-8601 date: YYYY-MM-DD
-  end: string | undefined; // ISO-8601 date: YYYY-MM-DD
+  start: string | undefined; // ISO-8601 local date or datetime string
+  end: string | undefined; // ISO-8601 local date or datetime string
 };
 
 type DateRangeDatePreset = {
@@ -134,8 +135,8 @@ The component implements accessible form labelling throughout:
 - `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.
 
-## v1 scope limits
+## Scope limits
 
-Date-time support (hours/minutes/seconds/timezone) is out of scope for v1. The added complexity of timezone handling and a time-picker UI warrants a separate design iteration. The `DateRangeValue` type uses ISO-8601 date strings (`YYYY-MM-DD`) only.
-
-If your use case requires sub-day precision, please add a comment on the GitHub issue to register demand for date-time mode.
+- 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.