@slotted/react 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/docs/data-grid.json

@@ -98,6 +98,7 @@
         "skeletonRows": 8,
         "filterDebounce": 300,
         "loadMoreThreshold": 20,
+        "loadMoreTrigger": "scroll",
         "pageSizes": [
           25,
           50,
@@ -496,7 +497,7 @@
           "type": "GridColumn<Row>[]",
           "defaultValue": "—",
           "appliesTo": "DataGrid",
-          "description": "The column model: id, label, description, kind, accessor, format, compare, width, minWidth, maxWidth, flex, priority, sortable, filterable, searchable, editable, resizable, reorderable, hideable, rowHeader, options, aggregate, validate, parse — and help, a node for the column’s help popover."
+          "description": "The column model: id, label, description, kind, accessor, format, compare, width, minWidth, maxWidth, flex, priority, sortable, filterable, searchable, editable, resizable, reorderable, hideable, rowHeader, pinned (end by default for kind actions), options, aggregate, validate, parse — and help, a node for the column’s help popover."
         },
         {
           "name": "description",
@@ -552,14 +553,14 @@
           "type": "boolean",
           "defaultValue": "—",
           "appliesTo": "DataGrid",
-          "description": "Whether a page past this one exists when the total is unknown; the footer offers Load more."
+          "description": "Whether a page past this one exists when the total is unknown; loadMoreTrigger decides what asks for it."
         },
         {
           "name": "loading",
-          "type": "boolean",
+          "type": "boolean | 'initial' | 'refresh'",
           "defaultValue": "false",
           "appliesTo": "DataGrid",
-          "description": "Skeleton rows with no rows to keep; aria-busy and a dimmed body over rows already shown."
+          "description": "Skeleton rows with no answer to keep; aria-busy over an answer already drawn — rows, which dim, or the empty state, which stays. true is initial until the grid has drawn an answer, and refresh after; rows emptied while a load starts wait in the skeleton."
         },
         {
           "name": "error",
@@ -904,6 +905,20 @@
           "appliesTo": "DataGrid",
           "description": "Asked for the next page when hasMore is true."
         },
+        {
+          "name": "loadMoreTrigger",
+          "type": "'scroll' | 'button' | 'both'",
+          "defaultValue": "scroll",
+          "appliesTo": "DataGrid",
+          "description": "What asks for the next page: nearing the end, with a loading status in the footer; a Load more control; or both."
+        },
+        {
+          "name": "loadMoreFailed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "DataGrid",
+          "description": "The last page asked for failed: the automatic request stops and the footer offers Try again."
+        },
         {
           "name": "onRetry",
           "type": "() => void",
@@ -1086,7 +1101,7 @@
           "type": "component",
           "defaultValue": "—",
           "appliesTo": "Application",
-          "description": "Sets variant, striped, stickyHeader, stickyTo, selectionMode, editMode, filterRow, virtualize, rowHeight, columnOverflow, overscan, pageSizes, filterDebounce, loadMoreThreshold and skeletonRows once for a subtree. A grid that states one itself still wins. Its words and its locale come from the language in force (SlottedProvider)."
+          "description": "Sets variant, striped, stickyHeader, stickyTo, selectionMode, editMode, filterRow, virtualize, rowHeight, columnOverflow, overscan, pageSizes, filterDebounce, loadMoreThreshold, loadMoreTrigger and skeletonRows once for a subtree. A grid that states one itself still wins. Its words and its locale come from the language in force (SlottedProvider)."
         },
         {
           "name": "@slotted/core/grid",
@@ -1207,7 +1222,9 @@
     "--slotted-control-font-size-md",
     "--slotted-control-font-size-sm",
     "--slotted-control-gap-md",
+    "--slotted-control-height-lg",
     "--slotted-control-height-md",
+    "--slotted-control-height-sm",
     "--slotted-control-icon-size-md",
     "--slotted-control-inner-size-sm",
     "--slotted-control-invalid-edge-width",
@@ -1526,7 +1543,7 @@
     {
       "id": "load-more",
       "title": "Load more",
-      "note": "With an unknown total the footer states the range without one and offers Load more; when the grid windows its rows, onLoadMore is called on its own as the window nears the end.",
+      "note": "With an unknown total the footer states the range without one. onLoadMore is called on its own as the reader nears the end, and the footer says a page is loading; it offers a control only to retry a page that failed (loadMoreFailed). loadMoreTrigger=\"button\" asks only from a Load more control, \"both\" does the two.",
       "language": "tsx",
       "source": "<DataGrid\n  hasMore={hasMore}\n  onLoadMore={fetchMore}\n  query={{ ...emptyQuery(), page: { cursor, size: 50 } }}\n  rows={rows}\n/>;\n",
       "verdict": "excerpt"
@@ -1534,7 +1551,7 @@
     {
       "id": "empty-and-loading",
       "title": "Empty, no results, error, loading",
-      "note": "Three states a body can hold instead of rows, each a result-state: nothing at all; nothing after the filter, with Clear filters; and a failed load, with Try again. A first load draws skeleton rows; a refresh over rows already shown dims them and moves nothing.",
+      "note": "Three states a body can hold instead of rows, each a result-state: nothing at all; nothing after the filter, with Clear filters; and a failed load, with Try again. A first load draws skeleton rows; a refresh over rows already shown dims them and moves nothing. Zero rows is an answer too: once the grid has drawn the empty state, loading keeps it and draws no skeleton, and loading=\"initial\" asks for the skeleton anyway.",
       "language": "tsx",
       "source": "<DataGrid error={error} loading={loading} onRetry={reload} rows={rows} />;\n",
       "verdict": "excerpt"

package/dist/docs/data-grid.md

@@ -208,7 +208,7 @@ See [data-grid.props.md](./data-grid.props.md).
 
 ## Tokens
 
-`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-md`, `--slotted-control-height-md`, `--slotted-control-icon-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-data-grid-band-surface`, `--slotted-data-grid-block-size`, `--slotted-data-grid-border-color`, `--slotted-data-grid-border-color-strong`, `--slotted-data-grid-border-width`, `--slotted-data-grid-cell-padding-block`, `--slotted-data-grid-cell-padding-inline`, `--slotted-data-grid-changed-surface`, `--slotted-data-grid-color`, `--slotted-data-grid-color-muted`, `--slotted-data-grid-control-radius`, `--slotted-data-grid-cursor-color`, `--slotted-data-grid-filter-operator-size`, `--slotted-data-grid-filter-panel-size`, `--slotted-data-grid-filter-panel-size-date`, `--slotted-data-grid-filter-panel-size-datetime`, `--slotted-data-grid-font-family`, `--slotted-data-grid-font-size`, `--slotted-data-grid-gap`, `--slotted-data-grid-head-block-size`, `--slotted-data-grid-header-surface`, `--slotted-data-grid-header-surface-hover`, `--slotted-data-grid-icon-size`, `--slotted-data-grid-indent`, `--slotted-data-grid-pin-shadow-color`, `--slotted-data-grid-pin-shadow-size`, `--slotted-data-grid-radius`, `--slotted-data-grid-range-surface`, `--slotted-data-grid-row-block-size`, `--slotted-data-grid-row-color-selected`, `--slotted-data-grid-row-max-block-size`, `--slotted-data-grid-row-surface-hover`, `--slotted-data-grid-row-surface-selected`, `--slotted-data-grid-row-surface-selected-hover`, `--slotted-data-grid-row-surface-stripe`, `--slotted-data-grid-shadow`, `--slotted-data-grid-sticky-offset`, `--slotted-data-grid-sticky-offset-end`, `--slotted-data-grid-surface`, `--slotted-disabled-foreground`, `--slotted-duration-long`, `--slotted-duration-loop`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-ground`, `--slotted-line-height-md`, `--slotted-popover-gap`, `--slotted-popover-padding-block-sm`, `--slotted-popover-padding-inline-sm`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-scrim`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-sticky`
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-md`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-data-grid-band-surface`, `--slotted-data-grid-block-size`, `--slotted-data-grid-border-color`, `--slotted-data-grid-border-color-strong`, `--slotted-data-grid-border-width`, `--slotted-data-grid-cell-padding-block`, `--slotted-data-grid-cell-padding-inline`, `--slotted-data-grid-changed-surface`, `--slotted-data-grid-color`, `--slotted-data-grid-color-muted`, `--slotted-data-grid-control-radius`, `--slotted-data-grid-cursor-color`, `--slotted-data-grid-filter-operator-size`, `--slotted-data-grid-filter-panel-size`, `--slotted-data-grid-filter-panel-size-date`, `--slotted-data-grid-filter-panel-size-datetime`, `--slotted-data-grid-font-family`, `--slotted-data-grid-font-size`, `--slotted-data-grid-gap`, `--slotted-data-grid-head-block-size`, `--slotted-data-grid-header-surface`, `--slotted-data-grid-header-surface-hover`, `--slotted-data-grid-icon-size`, `--slotted-data-grid-indent`, `--slotted-data-grid-pin-shadow-color`, `--slotted-data-grid-pin-shadow-size`, `--slotted-data-grid-radius`, `--slotted-data-grid-range-surface`, `--slotted-data-grid-row-block-size`, `--slotted-data-grid-row-color-selected`, `--slotted-data-grid-row-max-block-size`, `--slotted-data-grid-row-surface-hover`, `--slotted-data-grid-row-surface-selected`, `--slotted-data-grid-row-surface-selected-hover`, `--slotted-data-grid-row-surface-stripe`, `--slotted-data-grid-shadow`, `--slotted-data-grid-sticky-offset`, `--slotted-data-grid-sticky-offset-end`, `--slotted-data-grid-surface`, `--slotted-disabled-foreground`, `--slotted-duration-long`, `--slotted-duration-loop`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-ground`, `--slotted-line-height-md`, `--slotted-popover-gap`, `--slotted-popover-padding-block-sm`, `--slotted-popover-padding-inline-sm`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-scrim`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-sticky`
 
 ## Examples
 

package/dist/docs/data-grid.props.md

@@ -9,7 +9,7 @@
 | --- | --- | --- | --- | --- |
 | `rows` | `readonly Row[]` | — | DataGrid | The records; the grid never mutates them. Left out when a dataSource answers for them. |
 | `rowKey` | `keyof Row \| (row) => string` | — | DataGrid | A field name or a function: the key every state model names a row by. |
-| `columns` | `GridColumn<Row>[]` | — | DataGrid | The column model: id, label, description, kind, accessor, format, compare, width, minWidth, maxWidth, flex, priority, sortable, filterable, searchable, editable, resizable, reorderable, hideable, rowHeader, options, aggregate, validate, parse — and help, a node for the column’s help popover. |
+| `columns` | `GridColumn<Row>[]` | — | DataGrid | The column model: id, label, description, kind, accessor, format, compare, width, minWidth, maxWidth, flex, priority, sortable, filterable, searchable, editable, resizable, reorderable, hideable, rowHeader, pinned (end by default for kind actions), options, aggregate, validate, parse — and help, a node for the column’s help popover. |
 | `description` | `string` | — | DataGridColumn | What the column is: the header’s accessible description, the caption atop its menu and the first line of its help popover. |
 | `help` | `ReactNode` | — | DataGridColumn | The column’s own help, under the description in the popover the column-help button opens. Its presence alone draws the button. |
 | `priority` | `number` | — | DataGridColumn | The lower, the longer the column stays when the frame is too narrow. A column without one leaves before every numbered one; the identity column and an actions column never leave. |
@@ -17,8 +17,8 @@
 | `columnGroups` | `GridColumnGroup[]` | — | DataGrid | Headings spanning columns, drawn as a row above the names. |
 | `mode` | `'client' \| 'server'` | inferred | DataGrid | client applies the query to rows; server draws rows as given. server when totalCount or hasMore is present. |
 | `totalCount` | `number` | — | DataGrid | The whole set’s size in server mode; aria-rowcount and the range read it. |
-| `hasMore` | `boolean` | — | DataGrid | Whether a page past this one exists when the total is unknown; the footer offers Load more. |
-| `loading` | `boolean` | false | DataGrid | Skeleton rows with no rows to keep; aria-busy and a dimmed body over rows already shown. |
+| `hasMore` | `boolean` | — | DataGrid | Whether a page past this one exists when the total is unknown; loadMoreTrigger decides what asks for it. |
+| `loading` | `boolean \| 'initial' \| 'refresh'` | false | DataGrid | Skeleton rows with no answer to keep; aria-busy over an answer already drawn — rows, which dim, or the empty state, which stays. true is initial until the grid has drawn an answer, and refresh after; rows emptied while a load starts wait in the skeleton. |
 | `error` | `string \| null` | — | DataGrid | The message of a failed load; draws the error state with Try again when onRetry is set. |
 | `disabledKeys` | `string[]` | — | DataGrid | Rows that are neither selectable nor editable, drawn with data-disabled. |
 | `query` | `GridQuery` | — | DataGrid | sort, filter, search, page and group in one object. Present puts the query in controlled mode. |
@@ -68,6 +68,8 @@
 | `highlightChanges` | `boolean \| number` | false | DataGrid | Marks a mounted cell whose value changed between two rows, for the stated milliseconds (true is 1200). |
 | `loadMoreThreshold` | `number` | 20 | DataGrid | Rows left below the window before onLoadMore is called. |
 | `onLoadMore` | `() => void` | — | DataGrid | Asked for the next page when hasMore is true. |
+| `loadMoreTrigger` | `'scroll' \| 'button' \| 'both'` | scroll | DataGrid | What asks for the next page: nearing the end, with a loading status in the footer; a Load more control; or both. |
+| `loadMoreFailed` | `boolean` | false | DataGrid | The last page asked for failed: the automatic request stops and the footer offers Try again. |
 | `onRetry` | `() => void` | — | DataGrid | The error state’s Try again. |
 | `skeletonRows` | `number` | 8 | DataGrid | Rows the first load draws. |
 | `pageSizes` | `number[]` | 25,50,100 | DataGrid | The sizes a page-size control in the footer offers, read through useDataGridDefaults. |
@@ -93,7 +95,7 @@
 | `align` | `'start' \| 'center' \| 'end'` | start | GridColumn | Where the value sits; a number column sits at the end unless told otherwise. |
 | `numeric` | `boolean` | false | GridColumn | Tabular figures and end alignment; true for kind number. |
 | `text` | `'wrap' \| 'truncate' \| 'nowrap'` | truncate | GridColumn | What a long value does. |
-| `DataGridDefaultsProvider` | `component` | — | Application | Sets variant, striped, stickyHeader, stickyTo, selectionMode, editMode, filterRow, virtualize, rowHeight, columnOverflow, overscan, pageSizes, filterDebounce, loadMoreThreshold and skeletonRows once for a subtree. A grid that states one itself still wins. Its words and its locale come from the language in force (SlottedProvider). |
+| `DataGridDefaultsProvider` | `component` | — | Application | Sets variant, striped, stickyHeader, stickyTo, selectionMode, editMode, filterRow, virtualize, rowHeight, columnOverflow, overscan, pageSizes, filterDebounce, loadMoreThreshold, loadMoreTrigger and skeletonRows once for a subtree. A grid that states one itself still wins. Its words and its locale come from the language in force (SlottedProvider). |
 | `@slotted/core/grid` | `module` | — | Application | applyQuery, emptyQuery, withSortPress, withColumnFilter, withSearch, withPageIndex, withGroup, toGridParams, fromGridParams, normalizeColumnState, serializeColumnState, parseColumnState: the engine the grid runs on, for a server mock, a URL and a saved view. |
 | `renderCell, renderEditor, renderHeader, renderDetail, renderGroup, renderEmpty, renderFilterOperand` | `render props` | — | DataGrid | Every surface a consumer replaces, per grid or per column through cellRenderers and editorRenderers. row, cell, head and body are fixed: the layout and the roles are theirs. |
 | `footer` | `ReactNode` | — | DataGrid | Pagination, a page-size select, a count: the consumer’s own controls in the bar the grid draws. |

package/dist/docs/data-list.json

@@ -568,7 +568,8 @@
     "--slotted-target-min",
     "--slotted-text",
     "--slotted-text-muted",
-    "--slotted-tone-accent-text"
+    "--slotted-tone-accent-text",
+    "--slotted-z-index-sticky"
   ],
   "examples": [
     {

package/dist/docs/data-list.md

@@ -125,7 +125,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-md`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-8`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-md`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-8`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-z-index-sticky`
 
 ## Examples
 

package/dist/docs/date-field.json

@@ -125,7 +125,7 @@
           "type": "PlainDate | null",
           "defaultValue": "—",
           "appliesTo": "DateField",
-          "description": "The date the control shows. Present means the consumer owns it: the control asks and waits rather than moving it."
+          "description": "The date the control shows. Present means the consumer owns it: the control asks and waits rather than moving it. PlainDate is exported by @slotted/core/date. parseISODate(text) returns a PlainDate or null, and toISODate(date) returns 'YYYY-MM-DD': value={parseISODate(iso)} onValueChange={(v) => setIso(v === null ? '' : toISODate(v))}."
         },
         {
           "name": "defaultValue",
@@ -134,6 +134,13 @@
           "appliesTo": "DateField",
           "description": "The date the control starts from when nobody else writes one. Read once; a later change to it is not new state."
         },
+        {
+          "name": "granularity",
+          "type": "'day' | 'month'",
+          "defaultValue": "day",
+          "appliesTo": "DateField",
+          "description": "What the control holds. month shows the month and the year segments in the locale’s order, takes the first day of the month as its value, and submits YYYY-MM through name."
+        },
         {
           "name": "min",
           "type": "PlainDate",
@@ -325,6 +332,7 @@
     "--slotted-border-subtle",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
+    "--slotted-control-focus-ring-offset",
     "--slotted-control-font-family",
     "--slotted-control-font-size-lg",
     "--slotted-control-font-size-md",

package/dist/docs/date-field.md

@@ -38,8 +38,9 @@ Excerpt — not a complete module
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `value` | `PlainDate \| null` | — | DateField | The date the control shows. Present means the consumer owns it: the control asks and waits rather than moving it. |
+| `value` | `PlainDate \| null` | — | DateField | The date the control shows. Present means the consumer owns it: the control asks and waits rather than moving it. PlainDate is exported by @slotted/core/date. parseISODate(text) returns a PlainDate or null, and toISODate(date) returns 'YYYY-MM-DD': value={parseISODate(iso)} onValueChange={(v) => setIso(v === null ? '' : toISODate(v))}. |
 | `defaultValue` | `PlainDate \| null` | — | DateField | The date the control starts from when nobody else writes one. Read once; a later change to it is not new state. |
+| `granularity` | `'day' \| 'month'` | day | DateField | What the control holds. month shows the month and the year segments in the locale’s order, takes the first day of the month as its value, and submits YYYY-MM through name. |
 | `min` | `PlainDate` | — | DateField | The earliest date the control accepts. Reported through each segment’s aria-valuemin, and a value below it makes the control invalid. |
 | `max` | `PlainDate` | — | DateField | The latest date the control accepts, on the same terms as min. |
 | `isDateUnavailable` | `(date: PlainDate) => boolean` | — | DateField | Refuses particular dates — a weekend, a holiday, a day already booked. A refused date makes the control invalid. |
@@ -89,7 +90,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-date-field-action-active-background`, `--slotted-date-field-action-color`, `--slotted-date-field-action-hover-background`, `--slotted-date-field-action-size`, `--slotted-date-field-adornment-color`, `--slotted-date-field-background`, `--slotted-date-field-border-color`, `--slotted-date-field-color`, `--slotted-date-field-disabled-background`, `--slotted-date-field-disabled-border-color`, `--slotted-date-field-disabled-color`, `--slotted-date-field-hover-border-color`, `--slotted-date-field-icon-size-min`, `--slotted-date-field-invalid-border-color`, `--slotted-date-field-invalid-edge-width`, `--slotted-date-field-invalid-focus-ring-color`, `--slotted-date-field-literal-color`, `--slotted-date-field-placeholder-color`, `--slotted-date-field-plain-hover-background`, `--slotted-date-field-radius`, `--slotted-date-field-readonly-background`, `--slotted-date-field-segment-focus-background`, `--slotted-date-field-segment-focus-color`, `--slotted-date-field-segment-min-inline-size`, `--slotted-date-field-segment-padding-inline`, `--slotted-date-field-segment-radius`, `--slotted-date-field-shadow`, `--slotted-date-field-subtle-background`, `--slotted-date-field-subtle-border-color`, `--slotted-date-field-subtle-hover-background`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-focus-ring-offset`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-date-field-action-active-background`, `--slotted-date-field-action-color`, `--slotted-date-field-action-hover-background`, `--slotted-date-field-action-size`, `--slotted-date-field-adornment-color`, `--slotted-date-field-background`, `--slotted-date-field-border-color`, `--slotted-date-field-color`, `--slotted-date-field-disabled-background`, `--slotted-date-field-disabled-border-color`, `--slotted-date-field-disabled-color`, `--slotted-date-field-hover-border-color`, `--slotted-date-field-icon-size-min`, `--slotted-date-field-invalid-border-color`, `--slotted-date-field-invalid-edge-width`, `--slotted-date-field-invalid-focus-ring-color`, `--slotted-date-field-literal-color`, `--slotted-date-field-placeholder-color`, `--slotted-date-field-plain-hover-background`, `--slotted-date-field-radius`, `--slotted-date-field-readonly-background`, `--slotted-date-field-segment-focus-background`, `--slotted-date-field-segment-focus-color`, `--slotted-date-field-segment-min-inline-size`, `--slotted-date-field-segment-padding-inline`, `--slotted-date-field-segment-radius`, `--slotted-date-field-shadow`, `--slotted-date-field-subtle-background`, `--slotted-date-field-subtle-border-color`, `--slotted-date-field-subtle-hover-background`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
 
 ## Examples
 

package/dist/docs/date-picker.examples.md

@@ -740,6 +740,35 @@ export default function DatePickerInvoiceDue() {
 }
 ```
 
+### iso-date.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { DatePicker } from '@slotted/react/date-picker';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { isPlainDate, parseISODate, toISODate } from '@slotted/core/date';
+
+export default function DatePickerIsoDate() {
+  /* The API carries the date as text; the picker holds a PlainDate. */
+  const [iso, setIso] = useState('2026-10-19');
+
+  return (
+    <Field>
+      <FieldLabel>Statement date</FieldLabel>
+      <DatePicker
+        onValueChange={(value) => setIso(isPlainDate(value) ? toISODate(value) : '')}
+        value={parseISODate(iso)}
+      />
+      <FieldDescription>
+        {iso === '' ? 'No date sent.' : `The API receives ${iso}.`}
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
 ### locale.tsx
 
 Example

package/dist/docs/date-picker.json

@@ -135,7 +135,7 @@
           "type": "PlainDate | DateRange | PlainDate[] | null",
           "defaultValue": "—",
           "appliesTo": "DatePicker",
-          "description": "The selected value, whose shape follows selectionMode. Setting it makes the value controlled."
+          "description": "The selected value, whose shape follows selectionMode. Setting it makes the value controlled. PlainDate is exported by @slotted/core/date. parseISODate(text) returns a PlainDate or null, toISODate(date) returns 'YYYY-MM-DD', and isPlainDate(value) narrows the CalendarValue onValueChange reports: value={parseISODate(iso)} onValueChange={(v) => setIso(isPlainDate(v) ? toISODate(v) : '')}."
         },
         {
           "name": "defaultValue",
@@ -179,6 +179,13 @@
           "appliesTo": "DatePicker",
           "description": "Returns true for a date the reader cannot choose. The calendar disables it, and a typed unavailable date marks the date picker invalid."
         },
+        {
+          "name": "granularity",
+          "type": "'day' | 'month'",
+          "defaultValue": "day",
+          "appliesTo": "DatePicker",
+          "description": "What a choice is. month opens the calendar on the months of a year and chooses a month cell; the field shows the month and the year segments; value, defaultValue, min and max are PlainYearMonth from @slotted/core/date ({ year, month }), onValueChange reports one, and name submits YYYY-MM. parseISOYearMonth and toISOYearMonth convert to and from that text. selectionMode, months, isDateUnavailable and the week props do not apply."
+        },
         {
           "name": "selectionMode",
           "type": "'single' | 'range' | 'multiple'",
@@ -627,6 +634,14 @@
       "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport {\n  Select,\n  SelectContent,\n  SelectItem,\n  SelectTrigger,\n  SelectValue,\n} from '@slotted/react/select';\nimport { Stack } from '@slotted/react/stack';\nimport {\n  addDays,\n  createDateFormat,\n  isPlainDate,\n  plainDate,\n  type PlainDate,\n} from '@slotted/core/date';\n\nconst TERMS = [\n  { value: 'receipt', label: 'Due on receipt', days: 0 },\n  { value: 'net-15', label: 'Net 15', days: 15 },\n  { value: 'net-30', label: 'Net 30', days: 30 },\n  { value: 'net-60', label: 'Net 60', days: 60 },\n];\nconst words = createDateFormat({ locale: 'en-US' });\n\nexport default function DatePickerInvoiceDue() {\n  const [issued, setIssued] = useState<PlainDate | null>(plainDate(2026, 9, 30));\n  const [terms, setTerms] = useState('net-30');\n  const days = TERMS.find((option) => option.value === terms)?.days ?? 0;\n  const due = issued === null ? null : addDays(issued, days);\n\n  return (\n    <Stack gap={5}>\n      <Field required>\n        <FieldLabel>Invoice date</FieldLabel>\n        <DatePicker\n          onValueChange={(value) => setIssued(isPlainDate(value) ? value : null)}\n          value={issued}\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Payment terms</FieldLabel>\n        <Select\n          items={TERMS}\n          onValueChange={(next) => {\n            if (typeof next === 'string') setTerms(next);\n          }}\n          value={terms}\n        >\n          <SelectTrigger>\n            <SelectValue />\n          </SelectTrigger>\n          <SelectContent>\n            {TERMS.map((option) => (\n              <SelectItem key={option.value} value={option.value}>\n                {option.label}\n              </SelectItem>\n            ))}\n          </SelectContent>\n        </Select>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Due date</FieldLabel>\n        <DatePicker value={due} />\n        <FieldDescription>\n          {due === null ? 'Set the invoice date first.' : `Payment is due ${words.describe(due)}.`}\n        </FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
       "verdict": "example"
     },
+    {
+      "id": "iso-date",
+      "title": "iso-date.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { isPlainDate, parseISODate, toISODate } from '@slotted/core/date';\n\nexport default function DatePickerIsoDate() {\n  /* The API carries the date as text; the picker holds a PlainDate. */\n  const [iso, setIso] = useState('2026-10-19');\n\n  return (\n    <Field>\n      <FieldLabel>Statement date</FieldLabel>\n      <DatePicker\n        onValueChange={(value) => setIso(isPlainDate(value) ? toISODate(value) : '')}\n        value={parseISODate(iso)}\n      />\n      <FieldDescription>\n        {iso === '' ? 'No date sent.' : `The API receives ${iso}.`}\n      </FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
     {
       "id": "locale",
       "title": "locale.tsx",

package/dist/docs/date-picker.md

@@ -44,13 +44,14 @@ export default function DatePickerBasic() {
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `value` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | DatePicker | The selected value, whose shape follows selectionMode. Setting it makes the value controlled. |
+| `value` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | DatePicker | The selected value, whose shape follows selectionMode. Setting it makes the value controlled. PlainDate is exported by @slotted/core/date. parseISODate(text) returns a PlainDate or null, toISODate(date) returns 'YYYY-MM-DD', and isPlainDate(value) narrows the CalendarValue onValueChange reports: value={parseISODate(iso)} onValueChange={(v) => setIso(isPlainDate(v) ? toISODate(v) : '')}. |
 | `defaultValue` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | DatePicker | The starting value of an uncontrolled date picker. Read once, on the first render. |
 | `open` | `boolean` | — | DatePicker | Whether the calendar is showing. Setting it makes the open state controlled. |
 | `defaultOpen` | `boolean` | false | DatePicker | Whether the calendar shows on the first render. Focus does not move into it. |
 | `min` | `PlainDate` | — | DatePicker | The earliest date the field and the calendar accept. Earlier days are disabled in the calendar, and an earlier typed date marks the date picker invalid. |
 | `max` | `PlainDate` | — | DatePicker | The latest date the field and the calendar accept. Later days are disabled in the calendar, and a later typed date marks the date picker invalid. |
 | `isDateUnavailable` | `(date: PlainDate) => boolean` | — | DatePicker | Returns true for a date the reader cannot choose. The calendar disables it, and a typed unavailable date marks the date picker invalid. |
+| `granularity` | `'day' \| 'month'` | day | DatePicker | What a choice is. month opens the calendar on the months of a year and chooses a month cell; the field shows the month and the year segments; value, defaultValue, min and max are PlainYearMonth from @slotted/core/date ({ year, month }), onValueChange reports one, and name submits YYYY-MM. parseISOYearMonth and toISOYearMonth convert to and from that text. selectionMode, months, isDateUnavailable and the week props do not apply. |
 | `selectionMode` | `'single' \| 'range' \| 'multiple'` | single | DatePicker | How many dates the calendar selects, and so the shape of the value. The field shows a single date only; for a start and an end, use DateRangePicker. |
 | `months` | `number` | 1 | DatePicker | How many months the calendar draws side by side. |
 | `defaultView` | `'day' \| 'month' \| 'year'` | day | DatePicker | The grid the calendar opens on. |

package/dist/docs/datetime-field.json

@@ -419,6 +419,7 @@
     "--slotted-border-subtle",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
+    "--slotted-control-focus-ring-offset",
     "--slotted-control-font-family",
     "--slotted-control-font-size-lg",
     "--slotted-control-font-size-md",

package/dist/docs/datetime-field.md

@@ -103,7 +103,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-datetime-field-action-active-background`, `--slotted-datetime-field-action-color`, `--slotted-datetime-field-action-hover-background`, `--slotted-datetime-field-action-size`, `--slotted-datetime-field-adornment-color`, `--slotted-datetime-field-background`, `--slotted-datetime-field-border-color`, `--slotted-datetime-field-color`, `--slotted-datetime-field-disabled-background`, `--slotted-datetime-field-disabled-border-color`, `--slotted-datetime-field-disabled-color`, `--slotted-datetime-field-half-gap`, `--slotted-datetime-field-hover-border-color`, `--slotted-datetime-field-icon-size-min`, `--slotted-datetime-field-incomplete-border-color`, `--slotted-datetime-field-invalid-border-color`, `--slotted-datetime-field-invalid-edge-width`, `--slotted-datetime-field-invalid-focus-ring-color`, `--slotted-datetime-field-literal-color`, `--slotted-datetime-field-padding-block`, `--slotted-datetime-field-period-min-inline-size`, `--slotted-datetime-field-placeholder-color`, `--slotted-datetime-field-plain-hover-background`, `--slotted-datetime-field-preview-color`, `--slotted-datetime-field-preview-day-color`, `--slotted-datetime-field-radius`, `--slotted-datetime-field-readonly-background`, `--slotted-datetime-field-relative-border-color`, `--slotted-datetime-field-segment-focus-background`, `--slotted-datetime-field-segment-focus-color`, `--slotted-datetime-field-segment-min-inline-size`, `--slotted-datetime-field-segment-padding-inline`, `--slotted-datetime-field-segment-radius`, `--slotted-datetime-field-shadow`, `--slotted-datetime-field-subtle-background`, `--slotted-datetime-field-subtle-border-color`, `--slotted-datetime-field-subtle-hover-background`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-semibold`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-warning-border`
+`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-focus-ring-offset`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-datetime-field-action-active-background`, `--slotted-datetime-field-action-color`, `--slotted-datetime-field-action-hover-background`, `--slotted-datetime-field-action-size`, `--slotted-datetime-field-adornment-color`, `--slotted-datetime-field-background`, `--slotted-datetime-field-border-color`, `--slotted-datetime-field-color`, `--slotted-datetime-field-disabled-background`, `--slotted-datetime-field-disabled-border-color`, `--slotted-datetime-field-disabled-color`, `--slotted-datetime-field-half-gap`, `--slotted-datetime-field-hover-border-color`, `--slotted-datetime-field-icon-size-min`, `--slotted-datetime-field-incomplete-border-color`, `--slotted-datetime-field-invalid-border-color`, `--slotted-datetime-field-invalid-edge-width`, `--slotted-datetime-field-invalid-focus-ring-color`, `--slotted-datetime-field-literal-color`, `--slotted-datetime-field-padding-block`, `--slotted-datetime-field-period-min-inline-size`, `--slotted-datetime-field-placeholder-color`, `--slotted-datetime-field-plain-hover-background`, `--slotted-datetime-field-preview-color`, `--slotted-datetime-field-preview-day-color`, `--slotted-datetime-field-radius`, `--slotted-datetime-field-readonly-background`, `--slotted-datetime-field-relative-border-color`, `--slotted-datetime-field-segment-focus-background`, `--slotted-datetime-field-segment-focus-color`, `--slotted-datetime-field-segment-min-inline-size`, `--slotted-datetime-field-segment-padding-inline`, `--slotted-datetime-field-segment-radius`, `--slotted-datetime-field-shadow`, `--slotted-datetime-field-subtle-background`, `--slotted-datetime-field-subtle-border-color`, `--slotted-datetime-field-subtle-hover-background`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-semibold`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-warning-border`
 
 ## Examples