react-luna-form 0.0.87 → 0.0.89

package/dist/types/luna-react/src/component/slot/slot.d.ts

@@ -4,12 +4,11 @@ export declare const Slot: (props: Readonly<{
     context?: Record<string, unknown>;
     disabled?: boolean;
     fields?: import('../../../../luna-core/index').Fields;
-    lang?: string;
     onValueChange?: (input: {
         name: string;
         value: unknown;
     }) => void;
     style?: import('../../../../luna-core/index').Style;
-    translations?: Record<string, string>;
+    localization?: import('../../../../luna-core/index').Localization;
     value?: import('../../../../luna-core/index').Nullable<Record<string, unknown>>;
 }>) => import("react").JSX.Element;

package/dist/types/luna-react/src/config/index.d.ts

@@ -1,5 +1,6 @@
 import { type Environment, type Protocol } from '../../../luna-core/index';
 import type { AlertProps, Config, InputConfig } from '../type';
+export { readDateProps, type DateProps } from '../../../luna-core/index';
 export declare function defineConfig<T extends React.ElementType>(options: Readonly<{
     alert?: React.ComponentType<AlertProps>;
     env?: Environment;

package/dist/types/luna-react/src/server/component/input.d.ts

@@ -1,4 +1,4 @@
-import { type AriaAttributes, type CommonProps, type DataAttributes, type Field } from '../../../../luna-core/index';
+import { type AriaAttributes, type CommonProps, type DataAttributes, type Field, type Localization } from '../../../../luna-core/index';
 import type { Config } from '../../type';
 export declare function Input(props: Readonly<{
     ariaAttributes?: AriaAttributes;
@@ -8,6 +8,6 @@ export declare function Input(props: Readonly<{
     dataAttributes?: DataAttributes;
     field: Field;
     horizontal?: boolean;
-    translations?: Record<string, string>;
+    localization?: Localization;
     value?: Record<string, unknown>;
 }>): import("react").ReactNode;

package/dist/types/luna-react/src/server/component/slot.d.ts

@@ -4,12 +4,11 @@ export declare const Slot: (props: Readonly<{
     context?: Record<string, unknown>;
     disabled?: boolean;
     fields?: import('../../../../luna-core/index').Fields;
-    lang?: string;
     onValueChange?: (input: {
         name: string;
         value: unknown;
     }) => void;
     style?: import('../../../../luna-core/index').Style;
-    translations?: Record<string, string>;
+    localization?: import('../../../../luna-core/index').Localization;
     value?: import('../../../../luna-core/index').Nullable<Record<string, unknown>>;
 }>) => import("react").JSX.Element;

package/dist/types/luna-react/src/type.d.ts

@@ -1,4 +1,4 @@
-import type { AriaAttributes, BaseConfig, CommonProps, DataAttributes, Field, Fields, FormStateError } from '../../luna-core/index';
+import type { AriaAttributes, BaseConfig, CommonProps, DataAttributes, Field, Fields, FormStateError, Localization } from '../../luna-core/index';
 export type Slot = (props: {
     disabled?: boolean;
     fields?: Fields;
@@ -12,6 +12,7 @@ export type Children = (props: {
     dataAttributes?: DataAttributes;
     field: Field;
     horizontal?: boolean;
+    localization?: Localization;
     readOnly?: boolean;
 }) => React.ReactNode;
 export type InputConfig<T extends React.ElementType> = {

package/docs/events/change.md

@@ -189,7 +189,7 @@ The `state` action modifies the interactive state or visibility of other fields
 - `action` (string): Must be set to `"state"`.
 - `target` (string | array of strings): The field name, or an array of field names, that the state modifications should be applied to.
 - `state` (object): An object containing the new state to apply. Properties are independent of field names — the form may safely contain a field whose `name` is `"description"`, `"disabled"` or `"hidden"`; `target` identifies the field, the keys inside `state` configure it.
-  - `disabled` (boolean, optional): Whether the field should be disabled.
+  - `disabled` (boolean, optional): Whether the field should be disabled. While the condition holds it takes the place of the field's own `disabled`, in either direction: `false` enables a field declared `"disabled": true`. Once the condition stops holding, the field's own `disabled` applies again.
   - `hidden` (boolean, optional): Whether the field should be hidden from view. **Note:** When a field becomes hidden (`hidden: true`), its current value is automatically cleared from the form state to ensure no non-applicable data is submitted. See [What clearing a hidden target means](#what-clearing-a-hidden-target-means).
   - `description` (string | object, optional): A new description to render for the target field. Supports interpolation, format filters, and **Markdown** (specifically links). e.g. `"Check our [terms](https://example.com) for details."`.
 - `when` (string | array of strings | [Condition object](#the-condition-object), optional): A condition that specifies when this state should be applied.
@@ -409,6 +409,9 @@ Two details:
   `source`, the initial run is held until the data has loaded, so an action
   keyed on the selected entity sees the entity rather than a bare value. Text
   and date fields run as soon as the value is valid.
+- **A date range carries its pair.** A [range](../fields/input.md#a-range-of-days)
+  runs its events with `[from, to]`, at mount and on a click alike: `{value}` is
+  that pair.
 - **A `chips` field carries its array, not an entity.** No single option answers
   to a value that can hold several, so a `chips` change carries the array
   itself, at mount and on a click alike: `{value}` is that array, and there is

package/docs/fields/custom-inputs.md

@@ -44,16 +44,19 @@ Props are applied in this order:
 
 ```tsx
 <Component
-  {...commonProps} // id, name, placeholder, disabled, required
-  {...ariaAttributes} // aria-invalid, aria-errormessage
-  {...dataAttributes} // data-invalid, data-readonly
-  {...extraProps} // whatever the field family adds
+  {...dataAttributes} // advanced.data, as data-* attributes
+  {...commonProps} // id, name, placeholder, disabled, required, and what the field family adds
+  {...ariaAttributes} // advanced.aria, and aria-invalid, aria-errormessage
   {...inputProps} // the prepared value or defaultValue
   onBlur={onBlur}
   onChange={onChange}
 />
 ```
 
+`advanced.data` comes first, so an attribute the form writes for its own rules,
+such as the `data-format` of a date, keeps the form's value whatever
+`advanced.data` declares under the same name.
+
 `onChange` and `onBlur` are applied **last**, after every spread. A component
 that forwards its props unchanged gets them for free. A component that declares
 its own handlers must call the ones it received, or the form never learns the
@@ -63,6 +66,8 @@ field declares.
 A `readonly` field arrives `disabled` and without a `name`. Its value is still
 submitted, but by the form, in hidden inputs of its own: nothing your component
 renders for it is sent, so it is sent once, whatever your component renders.
+While a field is disabled or read-only, a change your component sends is not
+applied, so a part of it left enabled cannot change the value.
 
 ## Forwarding `id` is what gives the field its name
 
@@ -122,6 +127,147 @@ The same registered component is used by both render paths. If your custom
 input needs browser APIs, state or effects, mark it `'use client'` as you would
 any other component — the library does not do it for you.
 
+## Date components
+
+A component registered for `input/date` gets the field's day and its rules as
+plain props, and only renders. The form reads what it emits, checks every rule
+itself, on submit and on the server, and submits the value. Any calendar can
+render the field, and a native `<input type="date">` needs nothing at all.
+
+### What it receives
+
+| Prop            | Example                                        | What it is                                                                                                                           |
+| --------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`         | `"2026-10-02"`, `["2026-10-01", "2026-10-05"]` | The day as `yyyy-MM-dd`, from the client `Form`. A [range](input.md#a-range-of-days) is `[from, to]`, `''` for an end not picked yet |
+| `defaultValue`  | the same                                       | The same, from the server `Form`                                                                                                     |
+| `data-format`   | `"dd/MM/yyyy"`                                 | How to show the day, in date-fns tokens                                                                                              |
+| `data-mode`     | `"range"`                                      | Only on a range                                                                                                                      |
+| `min`, `max`    | `"2026-10-01"`                                 | [The first and the last day](input.md#the-first-and-the-last-day), both included                                                     |
+| `data-reserved` | `"2026-12-24,2026-12-25"`                      | [Days nobody can pick](input.md#days-nobody-can-pick)                                                                                |
+| `lang`          | `"es-CO"`                                      | The form's language, to name months and days in. Absent when the form has none                                                       |
+| `name`          | `"stay"`                                       | Absent, in the client `Form`, on a range and on a read-only field: the form submits those itself                                     |
+
+Read the props with `readDateProps` instead of by attribute name, so the
+component keeps working whatever the form puts on them next:
+
+```ts
+import { readDateProps } from 'react-luna-form/config'
+
+const { format, lang, mode, min, max, reserved } = readDateProps(props)
+```
+
+`lang` is the form's language as a canonical tag, and `'en'` when it has
+none. `mode` is `'single'` or `'range'`. `min` and `max` come back only when they are
+days, so a component can test them for `undefined` and nothing else. `reserved`
+is always a list, empty when nothing is reserved, sorted and with each day once.
+It is the same array for as long as the days are, so a component can memoize on
+it.
+
+### What it emits
+
+- One day: `onChange({ target: { value } })` with `yyyy-MM-dd` for a day the
+  user picked, or with the text as the user typed it. The form reads text in
+  the field's format, and keeps anything else as typed so that validation can
+  say what is wrong with it.
+- A range: `onChange({ target: { value: [from, to] } })`, with `''` for an end
+  not picked yet, or `''` once nothing is picked.
+- `onBlur` when the user leaves the component: that is when the form validates
+  the field.
+
+A calendar should offer no day outside `min` and `max` nor any in `reserved`,
+and a read-only or disabled field nothing to pick from. The form holds a wrong
+day back anyway, and ignores the change a locked field's component sends, but a
+person should not be able to pick it.
+
+### A calendar, in a few lines
+
+One day picked in react-day-picker, which is what shadcn's `Calendar` renders:
+
+```tsx
+'use client'
+
+import { format as formatDay, isValid, parse } from 'date-fns'
+import { DayPicker } from 'react-day-picker'
+import { readDateProps } from 'react-luna-form/config'
+
+// A day, read in local time: see the first mistake below.
+function toDay(iso?: string) {
+  const day = iso ? parse(iso, 'yyyy-MM-dd', new Date()) : undefined
+  return day && isValid(day) ? day : undefined
+}
+
+function toIso(day?: Date) {
+  return day ? formatDay(day, 'yyyy-MM-dd') : ''
+}
+
+export function CalendarDate(
+  props: Readonly<{
+    'data-format'?: string
+    'data-reserved'?: string
+    defaultValue?: string
+    max?: string
+    min?: string
+    onChange?: (event: { target: { value: string } }) => void
+    value?: string
+  }>
+) {
+  const { min, max, reserved } = readDateProps(props)
+  const booked = new Set(reserved)
+  const first = toDay(min)
+  const last = toDay(max)
+
+  return (
+    <DayPicker
+      mode="single"
+      selected={toDay(props.value ?? props.defaultValue)}
+      onSelect={(day) => props.onChange?.({ target: { value: toIso(day) } })}
+      disabled={[
+        ...(first ? [{ before: first }] : []),
+        ...(last ? [{ after: last }] : []),
+        (day: Date) => booked.has(toIso(day)),
+      ]}
+      startMonth={first}
+      endMonth={last}
+    />
+  )
+}
+```
+
+A range is the same with `mode="range"`, `selected={{ from, to }}` and
+`onSelect={(range) => ...}` emitting `[toIso(range.from), toIso(range.to)]`.
+
+### Mapping to common libraries
+
+| luna-form gives     | react-day-picker (shadcn `Calendar`)                           | MUI X                                                               | `<input type="date">`                        |
+| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------- |
+| `value`, one day    | `selected={toDay(value)}`                                      | `value={dayjs(value)}`                                              | `value` as it is                             |
+| `value`, a range    | `mode="range"`, `selected={{ from, to }}`                      | `DateRangePicker` (Pro) with `[dayjs(from), dayjs(to)]`             | none: two date fields and a `custom` rule    |
+| `onChange`          | from `onSelect`, with `format(day, 'yyyy-MM-dd')`              | from `onChange`, with `day.format('YYYY-MM-DD')`                    | native                                       |
+| `min`, `max`        | `disabled={[{ before }, { after }]}`, `startMonth`, `endMonth` | `minDate`, `maxDate`                                                | native                                       |
+| `data-reserved`     | `disabled` with a function that looks the day up in a set      | `shouldDisableDate={(day) => booked.has(day.format('YYYY-MM-DD'))}` | not shown; the form checks it all the same   |
+| `data-mode="range"` | `excludeDisabled`, `numberOfMonths={2}`                        | `DateRangePicker`                                                   | not supported                                |
+| `data-format`       | the text box: `format(day, dataFormat)`                        | `format`, in dayjs tokens                                           | ignored: the browser shows the user's locale |
+| `lang`              | `locale` from `react-day-picker/locale`, also for `format`     | `adapterLocale` on `LocalizationProvider`                           | ignored, the same way                        |
+
+### Mistakes that are easy to make
+
+1. **`new Date("2026-10-02")` is midnight UTC**, which is the day before
+   anywhere west of Greenwich: a calendar fed that marks the wrong day. Read a
+   `yyyy-MM-dd` day in local time, with `parse(iso, 'yyyy-MM-dd', new Date())`
+   or `new Date(year, month - 1, day)`.
+2. **In range mode, react-day-picker's `min` and `max` are numbers:** how many
+   days the range must or may span, not its first and last day. Spread the
+   form's props onto `<Calendar>` and a date lands where a count is expected:
+   hand it only what the component works out.
+3. **`startMonth` and `endMonth` only limit navigation.** The days outside the
+   bounds are disabled with `disabled`.
+4. **MUI takes dayjs tokens, `advanced.format` is in date-fns tokens:**
+   `dd/MM/yyyy` is `DD/MM/YYYY` there. Translate the format rather than pass it
+   through.
+5. **Disabling a day in the calendar validates nothing.** A typed date, a value
+   from the host and a payload posted to the server never pass through the
+   calendar; the form checks them, so the component does not have to.
+
 ## Checklist
 
 Before shipping a custom input:
@@ -130,3 +276,6 @@ Before shipping a custom input:
 - The `id` it receives reaches the focusable element
 - It forwards or calls the `onChange` and `onBlur` it receives
 - If it is a select variant, it does not rely on `''` to clear
+- If it renders `input/date`, it reads and emits `yyyy-MM-dd`, or `[from, to]`
+  for a range, offers no day outside `min` and `max` nor any in `reserved`, and
+  nothing to pick while it is disabled

package/docs/fields/data-source.md

@@ -66,9 +66,11 @@ Four ways to end up with an empty field and no request:
 - **The URL is blocked** by [`fetcher.remotePatterns`](../setup.md#fetcherremotepatterns).
   This one is logged; the others are silent. Relative URLs are internal and
   always allowed.
-- **The field is disabled.** Nothing is fetched, and a disabled `select` whose
-  value is an object renders that object as its only option — so a saved
-  selection is still readable on a form that cannot be edited.
+- **The field is disabled.** Nothing is fetched, and a disabled `select` with a
+  remote source whose value is an object renders that object as its only
+  option — so a saved selection is still readable on a form that cannot be
+  edited. Inline options need no request and stay, so a disabled `select` with
+  an array source still shows the option it holds.
 
 Requests are keyed by the source itself, so two fields declaring the same one
 share a single request and its cache entry.

package/docs/fields/input.md

@@ -29,7 +29,7 @@ Luna Form's input fields inherit the standard logical properties available to al
 - **`placeholder`** _(string, optional)_: The temporary placeholder text shown when the input is empty.
 - **`required`** _(boolean, optional)_: If `true`, standard browser/HTML5 validation makes the field mandatory.
 - **`disabled`** _(boolean, optional)_: If `true`, the field is non-interactive and blocked from events, and its value is not submitted.
-- **`readonly`** _(boolean, optional)_: If `true`, the field's value is locked and cannot be modified by the user, but it is still submitted. The control renders disabled, the one lock every input component understands, and the form sends the value itself. A field that is both `readonly` and `disabled` is not submitted.
+- **`readonly`** _(boolean, optional)_: If `true`, the field's value is locked and cannot be modified by the user, but it is still submitted. The control renders disabled, the one lock every input component understands, and the form sends the value itself; a change the control sends anyway is not applied. A field that is both `readonly` and `disabled` is not submitted.
 - **`hidden`** _(boolean, optional)_: If `true`, the field is hidden from the user interface.
 - **`order`** _(number, optional)_: A numeric order determining the field's position relative to adjacent fields.
 
@@ -54,7 +54,7 @@ The `advanced` property dictates finer HTML details, interactive structures, and
 
 These basic field types support extra manipulation properties inside the `advanced` block:
 
-- **`length`** _({ min?: number, max?: number })_: Applies HTML structural limits (`minlength` / `maxlength`, or `min` / `max` depending on the input type).
+- **`length`** _({ min?: number, max?: number })_: Applies HTML structural limits (`minlength` / `maxlength`, or `min` / `max` depending on the input type). Each bound is a number, or a `$ref` the host resolves to one; see [A bound that is no number](#a-bound-that-is-no-number). On an `input/date` the bounds are days instead; see [The first and the last day](#the-first-and-the-last-day).
 - **`step`** _(number)_ (`input/number` only): A number is whole unless it declares a step, which is the browser's own default of 1. The step is rendered on the input, so its arrows move by it, and validation accepts only values on it, counted from `length.min` when there is one, as the browser does: `0.01` for a price, `0.5` for halves, `0.001` for three decimals. A step has to be a number above 0. The browser ignores 0 and below, and so does the form; text such as `"any"` is no step either, and it is never rendered. Either way the number stays whole.
 - **`transform`** _(string | string[])_: Safely intercepts user inputs and manipulates content dynamically. Options include:
   - `"lowercase"`
@@ -66,6 +66,22 @@ These basic field types support extra manipulation properties inside the `advanc
 
 A required `input/number` accepts `0` and negative numbers: required means a value is present, not that it is at least 1. An optional one left empty is not submitted at all, rather than submitted as `0`, and its `length` bounds only apply to a value that is there. `select/year` and `select/month` read an empty selection the same way.
 
+### Empty and required text
+
+A text left empty is no value for its `length` bounds to check, as the browser's `minlength` does not apply to an empty value either. An optional field left empty, or holding only spaces, passes as `""`, whatever its `length.min`. A required one left empty asks for a value with `validation.required`, not with `validation.length.min`, and its bounds only apply once there is text. This holds for `input/text`, `input/tel`, `input/password`, a [`textarea`](#textarea), and a type the form does not know, which it checks as text.
+
+### A bound that is no number
+
+On the types above, on a [`textarea`](#textarea), and on a type the form does not know, which it checks as text, a `length` bound is a number. A day such as `"2026-10-05"` is not one, nor is text that reads as one, such as `"3"`, nor a `$ref` the context does not hold or holds as `undefined`. Such a bound is a rule the form cannot read, so the field takes no value: anything in it is held back with `This value cannot be checked`, whatever else the field would have checked, such as the address of an `input/email` or the `step` of a number. An optional field left empty still passes, and a required one still asks for a value.
+
+That is deliberate, as it is for [a date](#the-first-and-the-last-day): a server that validates with `buildFormSchema` and forgets its `context` would otherwise let through what the bound was there to keep out, with nothing in production to say so. The input is not handed such a bound, and a development build names it in the console, in the browser and on the server alike, once for each field:
+
+```text
+[Luna Form] when: advanced.length.min is "2026-10-05", which is no number, so the field takes no value
+```
+
+A minimum above the maximum, which no value passes, is named the same way.
+
 ### Temporal Options (`input/date`, `input/time`)
 
 Date and time inputs omit transformations and instead expose a `format` property directly under `advanced` for displaying values properly:
@@ -73,6 +89,175 @@ Date and time inputs omit transformations and instead expose a `format` property
 - **Date format** _(used with `input/date`)_: `"yyyy-MM-dd"`, `"MM/dd/yyyy"`, `"dd/MM/yyyy"`, or `"MMMM d, yyyy"`.
 - **Time format** _(used with `input/time`)_: `"HH:mm"`, `"HH:mm:ss"`, `"hh:mm a"`, or `"hh:mm:ss a"`.
 
+### What a date holds
+
+An `input/date` holds a day as `yyyy-MM-dd`, whatever its `format`, or two of them in [a range](#a-range-of-days). That is the value the form hands its component, reports through `onValueChange`, submits, and validates on the server with `buildFormSchema`. With [submit validation off](../forms/submit.md#turning-submit-validation-off), the action gets the raw `FormData` instead, where a single day is whatever its control holds; a range and a read-only field still carry `yyyy-MM-dd`, in the hidden inputs the form adds. `format` only says how the field shows the day, and reaches the component as its `data-format` prop (see [Date components](custom-inputs.md#date-components)).
+
+- A value the host passes in, or a `defaultValue`, is read in either shape: `yyyy-MM-dd`, or the field's `format`. A host that keeps what the form submitted can pass it straight back.
+- A `format` with month or day names reads them in English or in Spanish, the languages the form writes them in, so `octubre 2, 2026`, which a form in Spanish shows, reads back as `2026-10-02`.
+- Text that is no day, typed in another format, with a year short of four digits, or naming a day that does not exist such as February 30, is kept as typed and holds the submit back with `validation.date`.
+- An optional date left empty is not submitted at all, the way an empty number is not.
+- In a description, `{value}` is the `yyyy-MM-dd` text. To show it another way, use a filter such as `{value | date:long}`.
+- Everything that compares a date sees `yyyy-MM-dd` too: a `when`, a `custom` or `rules` validation, a change event. Write the dates they compare against that way, as in `"value": "2026-10-01"`.
+
+### The first and the last day
+
+`advanced.length` bounds an `input/date` the way it bounds a number: `min` is the first day a person may pick and `max` the last, both included, written as `yyyy-MM-dd` whatever the field's `format`. `validation.length.min` and `.max` are the messages for a day outside them; without one, the message names the bound the way the field shows a day.
+
+```json
+{
+  "name": "check_in",
+  "type": "input/date",
+  "advanced": {
+    "format": "dd/MM/yyyy",
+    "length": { "min": "2026-10-05", "max": "2026-10-20" }
+  },
+  "validation": { "length": { "min": "We open on October 5" } }
+}
+```
+
+The component gets the bounds as `min` and `max`, which a native `<input type="date">` uses as they are and a calendar reads back with `readDateProps` (see [Date components](custom-inputs.md#date-components)). The form checks them itself, so a day typed, passed in by the host or posted to the server outside them holds the submit back whatever the component allowed.
+
+The form keeps no clock, so which day is today is the host's to say. Pass it in [`context`](../structure/definition.md#what-the-host-knows-context) and point the bound at it:
+
+```json
+"advanced": { "length": { "min": { "$ref": "#/context/today" } } }
+```
+
+```tsx
+const context = useMemo(() => ({ today }), [today])
+
+<Form sections={sections} context={context} config={config} />
+```
+
+The host decides the day and the time zone it is counted in, and a server that validates with `buildFormSchema(sections, translations, definition, context)` gets the same answer as the browser. Keep `context` the same object until the day changes: every field renders again when it is a new one (see [What the host knows](../structure/definition.md#what-the-host-knows-context)).
+
+A bound that is no `yyyy-MM-dd` day, such as `"05/10/2026"`, or a `$ref` the context does not hold or holds as `undefined`, is a rule the form cannot read, so the field takes no day: every day is held back with `This date cannot be checked`, and an optional field left empty still passes. That is deliberate. A server that validates with `buildFormSchema` and forgets its `context` would otherwise let every day through, with nothing in production to say so. The component is not handed such a bound, and a development build names it in the console wherever the form reads the bounds, in the browser and on the server alike: once for each field, and again whenever a new `context` resolves them anew. A minimum later than the maximum, which no day passes, is named the same way.
+
+### Days nobody can pick
+
+`advanced.reserved` lists days nobody may pick, as `yyyy-MM-dd`: a night already booked, a holiday. `validation.reserved` is the message for one of them; without it, the message is `This date is not available`. The bounds are checked first, so a reserved day outside them gets the bound's message.
+
+```json
+{
+  "name": "night",
+  "type": "input/date",
+  "advanced": { "reserved": ["2026-12-24", "2026-12-25"] },
+  "validation": { "reserved": "That night is taken" }
+}
+```
+
+What is booked is usually the host's to know, so the list usually comes through [`context`](../structure/definition.md#what-the-host-knows-context):
+
+```json
+"advanced": { "reserved": { "$ref": "#/context/booked" } }
+```
+
+The component gets the days as `data-reserved`, sorted, once each and joined by commas, and reads them back as a list with `readDateProps` (see [Date components](custom-inputs.md#date-components)). The form checks them itself, and a server that validates with `buildFormSchema(sections, translations, definition, context)` checks the list it is given at that moment. That holds back a submit made with an old list on screen; two submits for the same day at the same moment are told apart only by the application, when it saves.
+
+An entry that is no `yyyy-MM-dd` day, or a list that is not one, such as a `$ref` the context does not hold, is a rule the form cannot read too: the field takes no day, with `This date cannot be checked`, rather than let a booked night through. A development build names both, the way it names a bound.
+
+### A range of days
+
+`advanced.mode: "range"` makes an `input/date` hold two days, the first and the last, as `[from, to]`, both `yyyy-MM-dd`. That pair is what the component gets, what the host is told and what the action receives. A range of one day has the same day at both ends.
+
+```json
+{
+  "name": "stay",
+  "type": "input/date",
+  "advanced": { "mode": "range", "reserved": { "$ref": "#/context/booked" } },
+  "validation": { "range": "Pick the first and the last night" }
+}
+```
+
+```js
+{
+  stay: ['2026-11-02', '2026-11-06']
+}
+```
+
+- Each end answers to the rules of a single day: the bounds, the reserved days, and `validation.date` for one that is no day. The days between the ends belong to the range too, so a reserved one anywhere inside holds it back.
+- An end missing, or a last day before the first, holds the submit back with `validation.range`; without it, the message is `Invalid date range`.
+- Nothing picked is no range: an optional one is not submitted, and a required one asks with `validation.required`.
+- The form submits the two days itself, in two hidden inputs, so the component's control has no `name` and nothing it renders is sent. A host passes a range the way it gets one back, as `[from, to]`.
+- A native `<input type="date">` holds one day. A range needs a component that picks two (see [Date components](custom-inputs.md#date-components)), or two date fields compared with a `custom` validation and `gte`.
+- In a description, `{value}` stays as written: it takes one value, and a range is two.
+- A range is a list of two days. `exists`, `empty`, `truthy` and `contains` read it the way they read any list, but the operators that order (`gt`, `gte`, `lt`, `lte`), and `eq` or `in` against a single day, never hold on it, so a `custom` rule that orders a range holds every submit back. Compare single dates instead.
+
+### A booking, end to end
+
+A stay that starts today at the earliest, within a year, and on no night already booked. The form declares the rules; the host knows the facts, and hands them over in `context`:
+
+```json
+{
+  "name": "stay",
+  "type": "input/date",
+  "label": "Stay",
+  "required": true,
+  "advanced": {
+    "format": "dd/MM/yyyy",
+    "mode": "range",
+    "length": {
+      "min": { "$ref": "#/context/dates.today" },
+      "max": { "$ref": "#/context/dates.inOneYear" }
+    },
+    "reserved": { "$ref": "#/context/booked" }
+  },
+  "validation": {
+    "required": "Pick your stay",
+    "range": "Pick the first and the last night",
+    "length": {
+      "min": "A stay cannot start in the past",
+      "max": "We take bookings a year ahead"
+    },
+    "reserved": "A night in it is taken"
+  }
+}
+```
+
+Which day is today depends on where it is counted, so the host counts it where the business does, not where the server runs:
+
+```ts
+// In the application, not in the form.
+import { addYears, format, parse } from 'date-fns'
+
+// 'en-CA' writes a day as yyyy-MM-dd.
+const day = new Intl.DateTimeFormat('en-CA', {
+  timeZone: 'America/Bogota',
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+})
+
+export function formDates(now: Date) {
+  const today = day.format(now)
+  const next = addYears(parse(today, 'yyyy-MM-dd', new Date()), 1)
+  return { today, inOneYear: format(next, 'yyyy-MM-dd') }
+}
+```
+
+The page works the context out once per request, so it is the same object for as long as the form is on screen, and the server validates the submit with a context worked out when it arrives:
+
+```tsx
+const context = {
+  dates: formDates(new Date()),
+  booked: await bookedNights(roomId),
+}
+
+<Form sections={sections} context={context} config={config} action={book} />
+```
+
+```ts
+// In the action: the same rules, against the nights booked by now.
+const schema = buildFormSchema(sections, translations, definition, {
+  dates: formDates(new Date()),
+  booked: await bookedNights(roomId),
+})
+const result = schema.safeParse(form) // { stay: ['2026-11-02', '2026-11-06'] }
+```
+
+That holds back a stay chosen from a list that was old by the time it was sent. Two submits for the same night at the same moment are told apart only by the application, when it saves: the form is the first line, not the guarantee.
+
 ---
 
 ## Validation (`validation` object)
@@ -81,7 +266,10 @@ The `validation` object resolves form errors overriding generic defaults, mappin
 
 - **`required`** _(string)_: Specifies the error message exposed when the element is marked exactly as `required: true` and the field is empty.
 - **`email`** _(string)_: Error message specifically asserting an invalid email format.
-- **`length`** _({ min?: string, max?: string })_: Specific string messages shown when input lengths are breached.
+- **`date`** _(string)_: `input/date` only. The message shown when the field holds text that is no day. Without it, the message is `Invalid date`.
+- **`length`** _({ min?: string, max?: string })_: Specific string messages shown when a value breaches `advanced.length`: a text too short or too long, the address of an `input/email` included, a number out of range, a day before the first or after the last. An address that is no address and is out of its bounds shows both messages, the `email` one first. An optional `input/email` left empty still passes.
+- **`reserved`** _(string)_: `input/date` only. The message shown for a day its `advanced.reserved` lists. Without it, the message is `This date is not available`.
+- **`range`** _(string)_: `input/date` ranges only. The message shown for a range with an end missing, or whose last day comes before its first. Without it, the message is `Invalid date range`.
 - **`step`** _(string)_: The message shown when an `input/number` is off its step: a decimal on a number that declares no step, or a value off the `advanced.step` it declares. The form's dictionary translates it, as it does every other message.
 - **`custom`** _(CustomValidation | CustomValidation[])_: Powerful conditional-based logic blocks. An array specifying:
   - `field`: Optional target reference string.
@@ -153,7 +341,10 @@ Everything else in `advanced` is ignored for this type.
 ```
 
 `length.min` and `length.max` are emitted as the `minLength` and `maxLength`
-attributes on the rendered element.
+attributes on the rendered element, and validation checks the same bounds on
+text that is there: see [Empty and required text](#empty-and-required-text). A
+bound that is no number is neither: see
+[A bound that is no number](#a-bound-that-is-no-number).
 
 Like the `input/*` family, a declared `change` event on a `textarea` is
 debounced: it fires 300 ms after the last keystroke, not on every one.

package/docs/fields/list.md

@@ -25,6 +25,7 @@ The `advanced` property customizes structural interaction rules and layout rende
   A custom label has to be translated by the form; the built-in `Add item` default is already translated by the library — see [Localization](#localization).
 - **`length`** _({ min?: number, max?: number })_: Configures restrictions on how many items can be generated. Enforces boundary conditions where minimum instances ensure permanent default items and maximum instances automatically disable insertion toggles. The matching error messages are declared under the list's `validation.length` — see the [Validation reference](../validation/overview.md#list-length).
   Both bounds apply to the rows a list opens with, not only to the ones added by hand: an initial `value` shorter than `min` leaves the remainder standing and empty, and one longer than `max` stops at `max`. A [`value` event](../events/change.md#targeting-a-list) assigning rows is clamped the same way.
+  Each bound is a number, or a `$ref` the host resolves to one. A bound that is not, such as a `$ref` the context does not hold, is a rule the form cannot read: the list is held back with `This list cannot be checked`, an empty one included, since a list has no `required` of its own and `length.min` is how it asks for rows. Meanwhile it shows its rows as if that bound were not declared, a `min` of one or no `max` at all, and a development build names the bound in the console, as it does [for a field](input.md#a-bound-that-is-no-number).
 - **`collapsed`** _(boolean)_: When enabled, list items default to a visually collapsed representation upon mounting or adding.
   Collapsing only hides a row: its fields keep their values, still validate and are still submitted, and a submit that fails on one of them opens the row so the error can be seen.
 - **`keepValue`** _(boolean)_: If `true`, hiding the list leaves the values behind instead of taking them. A list holds nothing under its own name, so declaring it here is a statement about the rows: it covers every value they hold. See [Keeping a value through a hide](../events/change.md#keeping-a-value-through-a-hide).
@@ -156,7 +157,7 @@ The built-ins are layered _under_ the form's own block, so declaring a key still
 }
 ```
 
-Regional tags resolve to their base language, so `es-MX` and `es-419` both get the Spanish defaults. A form's own entries keep matching on the exact tag, unchanged.
+Regional tags fall back to their base language: `es-MX` and `es-419` get the Spanish defaults and the form's own `es` block, and a block for the exact tag, where the form has one, wins key by key. One `lang` carries the region the form's money and dates are written for without repeating its translations. A tag that is no tag, such as `es_MX`, is English everywhere, its dictionary included.
 
 ### Accessible name templates