react-luna-form 0.0.87 → 0.0.88

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). 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"`
@@ -73,6 +73,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 +250,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, a number out of range, a day before the first or after the last.
+- **`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.

package/docs/fields/list.md

@@ -156,7 +156,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
 

package/docs/fields/specialized-selectors.md

@@ -21,10 +21,18 @@ An optional month nobody picked is not submitted at all, and a required one asks
 
 ### 2. Year Selector (`select/year`)
 
-Renders a dropdown with a range of years.
+Renders a dropdown with the years from `advanced.length.min` to `advanced.length.max`, both included, written as whole numbers:
 
-- **Default behavior**: Shows the current year plus the next 5 years.
-- **Customization**: Use `advanced.length.min` and `advanced.length.max` to define the start and end years relative to the current year.
+```json
+{
+  "name": "graduation_year",
+  "type": "select/year",
+  "label": "Graduation Year",
+  "advanced": { "length": { "min": 1980, "max": 2030 } }
+}
+```
+
+The form keeps no clock, so which year it is now is the host's to say, the way it says [which day is today](input.md#the-first-and-the-last-day) to a date. Pass the years in [`context`](../structure/definition.md#what-the-host-knows-context) and point the bounds at them:
 
 ```json
 {
@@ -33,14 +41,30 @@ Renders a dropdown with a range of years.
   "label": "Expiration Year",
   "advanced": {
     "length": {
-      "min": 0,
-      "max": 10
+      "min": { "$ref": "#/context/years.current" },
+      "max": { "$ref": "#/context/years.inTen" }
     }
   }
 }
 ```
 
-An optional year nobody picked is not submitted at all, and a required one asks for a value, the way an [`input/number`](input.md#empty-and-required-numbers) does.
+```ts
+// In the application, counted where the business is, not where the server runs.
+const year = Number(
+  new Intl.DateTimeFormat('en', {
+    timeZone: 'America/Bogota',
+    year: 'numeric',
+  }).format(new Date())
+)
+
+const context = { years: { current: year, inTen: year + 10 } }
+```
+
+At 03:00 UTC on 1 January the year is already the next one in UTC and still the old one in Bogota, so the host decides where it is counted. The server renders and validates with the years it is given, the same ones the browser gets.
+
+A year select needs both bounds. Without one, or with one that is no whole number, such as `"2026"` written as text or a `$ref` the context does not hold, it offers no year, and a development build names it in the console. A minimum after the maximum is named the same way.
+
+The schema checks the same bounds, so a year outside them, from a host value or a submit made by hand, is held back with `validation.length.min` or `validation.length.max` as the message, or a default such as `Too small: expected number to be >=2026`. A field that offers no year takes none: any year is held back with `This year is not available`. An optional year nobody picked is not submitted at all, and a required one asks for a value, the way an [`input/number`](input.md#empty-and-required-numbers) does.
 
 ### 3. Day Selector (`select/day`)
 
@@ -56,17 +80,32 @@ Renders a dropdown with days 1 through 31.
 
 ### 4. Timezone Selector (`select/timezone`)
 
-Provides a comprehensive list of global timezones.
+Provides every time zone the runtime knows, from `Intl.supportedValuesOf('timeZone')`, grouped by region. A field submits the zone's IANA name, such as `America/Bogota`.
 
 ```json
 {
-  "name": "user_timezone",
+  "name": "meeting_zone",
   "type": "select/timezone",
-  "label": "Your Timezone",
-  "defaultValue": "America/New_York"
+  "label": "Time zone",
+  "advanced": { "suggested": { "$ref": "#/context/user.timeZone" } }
+}
+```
+
+```tsx
+// Worked out once per request, on the server.
+const context = {
+  now: new Date().toISOString(),
+  user: { timeZone: session.timeZone },
 }
+
+<Form sections={sections} context={context} config={config} />
 ```
 
+- **`advanced.suggested`** is the zone offered first, alone in a "Suggested" group. The host knows it, from a profile, a cookie or a header, so it usually arrives through [`context`](../structure/definition.md#what-the-host-knows-context), and the server and the browser suggest the same one. Without it there is no "Suggested" group. A zone written another way is suggested, and submitted, by the name the runtime gives it, so it is listed once: `america/bogota` as `America/Bogota`, `US/Eastern` as `America/New_York`. A value that is no zone suggests nothing, an offset such as `+05:00` included, and a development build names it in the console.
+- **[`context.now`](../interpolation/overview.md#the-instant-relative-dates-use)**, an ISO date, time and offset, is the instant the zones are labelled for. A zone's offset depends on it, `Madrid - Central European (UTC+01:00)` in January and `(UTC+02:00)` in July, and so does its name, which some zones have changed over the years. Without it each zone is labelled by its city alone, `Madrid`.
+
+The list is the runtime's own, so two engines can list different zones: Node and Chromium list `Asia/Calcutta` and leave out `UTC`, which can still be suggested.
+
 ---
 
 ## Utility Selectors
@@ -123,7 +162,7 @@ Renders chips for the 12 months of the year.
 
 The option labels of these selectors are produced by the framework, not written in the schema, so most of them are resolved through the form's `lang` rather than against the `translations` dictionary the way an inline [array source](select.md#translating-options) is.
 
-- `select/month`, `select/day`, `chips/day` and `chips/month` take their names from the form's `lang`, resolved through `Intl`. Without `lang` they fall back to the runtime locale, and a malformed tag (`es_MX`, `español`) falls back too rather than failing.
+- `select/month`, `select/day`, `chips/day` and `chips/month` take their names from the form's `lang`, resolved through `Intl`. Without `lang`, with a malformed tag (`es_MX`, `español`), or with one the runtime has no language for (`sp`), they are in English, whatever language the machine rendering them speaks.
 - `select/year` renders plain numbers.
 - `select/timezone` renders its region groups and zone names in English.
 - `select/active` is the exception: `Yes` and `No` are authored copy rather than locale data, so they **are** resolved against the dictionary, using their English text as the key — the same way the built-in `(Optional)` suffix is. The library ships the Spanish for both, so `lang: "es"` alone is enough; see [built-in translations](list.md#built-in-translations).
@@ -139,7 +178,7 @@ The option labels of these selectors are produced by the framework, not written
 }
 ```
 
-The dropdown lists `enero` through `diciembre`, while the submitted value stays the month number. Setting `lang` also keeps the server and client renders on the same locale; without it each side resolves its own default, which can differ.
+The dropdown lists `enero` through `diciembre`, while the submitted value stays the month number. The server and the client render the same names, with `lang` or without it.
 
 `select/active` instead reads its two labels from the dictionary, and the library already ships the Spanish for them:
 

package/docs/forms/submit.md

@@ -28,18 +28,16 @@ On submit, in this order:
 
 1. **The form data becomes an object.** A name that appears more than once
    arrives as an array; everything else as a single value.
-2. **Date fields are normalized.** A date input holds its value in the display
-   format the field declares, and it is converted back to a native date before
-   validation, so the schema and your action see one shape whatever
+2. **It is validated** against the schema built from the fields that are
+   currently mounted. A date is read in either shape the form accepts and comes
+   out of the schema as `yyyy-MM-dd`, so your action sees one shape whatever
    `advanced.format` says.
-3. **It is validated** against the schema built from the fields that are
-   currently mounted.
-4. **Dotted names are un-flattened.** `basicAuth.username` becomes
+3. **Dotted names are un-flattened.** `basicAuth.username` becomes
    `{ basicAuth: { username } }`, and a numeric segment becomes an array index,
    so `rules.0.value` rebuilds the list — with the gaps of removed rows closed
    up.
-5. **Your `action` is awaited** with that object and the schema.
-6. **`onSuccess` is called** with what the action returned, and the form clears
+4. **Your `action` is awaited** with that object and the schema.
+5. **`onSuccess` is called** with what the action returned, and the form clears
    itself.
 
 ## Only mounted fields are validated

package/docs/index.md

@@ -22,7 +22,8 @@ between the client and server `Form`.
 | Declaring a text, number, date or password field                             | [fields/input.md](fields/input.md)                                 |
 | Declaring a `select`, `radio` or `chips` field, or filling one from a source | [fields/select.md](fields/select.md)                               |
 | Declaring a repeatable group of fields                                       | [fields/list.md](fields/list.md)                                   |
-| Looking for a date range, a color or another ready-made picker               | [fields/specialized-selectors.md](fields/specialized-selectors.md) |
+| Picking a range of days, bounding a date or blocking days                    | [fields/input.md](fields/input.md#a-range-of-days)                 |
+| Picking a day of the month, a month, a year, weekdays or a time zone         | [fields/specialized-selectors.md](fields/specialized-selectors.md) |
 | Implementing a field type this library does not ship                         | [fields/custom-inputs.md](fields/custom-inputs.md)                 |
 | Filling a `select` from an API                                               | [fields/data-source.md](fields/data-source.md)                     |
 | Making a field required, or validating against another field                 | [validation/overview.md](validation/overview.md)                   |