react-luna-form 0.0.87 → 0.0.89

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)                   |

package/docs/interpolation/format-filters.md

@@ -25,21 +25,21 @@ Filters work in any string passed through Luna Form's interpolation engine, incl
 
 Multiple filters can be chained; the output of the previous filter becomes the input of the next.
 
-## Locale resolution
+## Language
 
-Locale-aware filters read the locale from `config.env.locale`. If not set, filters fall back to the runtime default (typically the browser's locale).
+Filters format in the form's `lang`, the tag that also picks its translations
+and names its months:
 
-It applies wherever a filter is written — a label, a description, a `value` payload — so one setting keeps them consistent. See [Interpolation](overview.md#the-locale-filters-use).
-
-```ts
-const config = {
-  env: {
-    locale: 'es-ES',
-  },
-  // ...
-}
+```tsx
+<Form sections={sections} config={config} lang="es-ES" />
 ```
 
+It applies wherever a filter is written — a label, a description, a `value` or
+`source` payload — so one setting keeps them consistent. Without `lang`, or with
+one that is no language tag or names no language the runtime has, filters write
+English, on every machine. See
+[Interpolation](overview.md#the-language-filters-use).
+
 ## Fallback rules
 
 - **Unknown filter name**: the entire placeholder is preserved literally (`{value | foo}` stays as `{value | foo}`).
@@ -57,8 +57,8 @@ Formats a number as currency.
   - `CODE` (string, default `"USD"`) — ISO 4217 currency code.
 - **Backend**: `Intl.NumberFormat(locale, { style: 'currency', currency: CODE })`.
 - **Examples**:
-  - `1234.56` with `currency:USD` and `locale: en-US` → `$1,234.56`.
-  - `1234.56` with `currency:EUR` and `locale: es-ES` → `1234,56 €`.
+  - `1234.56` with `currency:USD` and `lang: en-US` → `$1,234.56`.
+  - `1234.56` with `currency:EUR` and `lang: es-ES` → `1234,56 €`.
 
 ### `percent`
 
@@ -67,7 +67,7 @@ Formats a fractional number as a percentage.
 - **Syntax**: `{value | percent}`
 - **Backend**: `Intl.NumberFormat(locale, { style: 'percent' })`.
 - **Examples**:
-  - `0.25` with `locale: en-US` → `25%`.
+  - `0.25` with `lang: en-US` → `25%`.
 - **Note**: input is interpreted as a fraction (`1` is `100%`).
 
 ### `number`
@@ -77,8 +77,8 @@ Formats a number with locale-aware thousands separators.
 - **Syntax**: `{value | number}`
 - **Backend**: `Intl.NumberFormat(locale)`.
 - **Examples**:
-  - `1234567` with `locale: en-US` → `1,234,567`.
-  - `1234567` with `locale: es-ES` → `1.234.567`.
+  - `1234567` with `lang: en-US` → `1,234,567`.
+  - `1234567` with `lang: es-ES` → `1.234.567`.
 
 ### `date`
 
@@ -87,11 +87,13 @@ Formats a date or ISO string with a named style.
 - **Syntax**: `{value | date:STYLE}`
 - **Args**:
   - `STYLE` (string, default `"short"`) — one of `short`, `medium`, `long`, `full`, `relative`. Any other value is passed directly to `date-fns`'s `format` as a pattern.
-- **Backend**: `date-fns` (`format`, `formatDistanceToNow` for `relative`).
+- **Backend**: `Intl.DateTimeFormat` with `dateStyle` for the named styles, `Intl.RelativeTimeFormat` for `relative`, and `date-fns`'s `format` for a pattern.
 - **Accepts**: `Date`, ISO string, or numeric timestamp (ms).
+- **`relative`** is measured from [`context.now`](overview.md#the-instant-relative-dates-use), the instant the host passes, never from the clock of the machine that renders it. Without it the date is shown in the `medium` style.
 - **Examples**:
-  - `"2026-05-10"` with `date:long` and `locale: en-US` → `May 10, 2026`.
-  - A future date with `date:relative` and `locale: en-US` → `in 7 days`.
+  - `"2026-05-10"` with `date:long` and `lang: en-US` → `May 10, 2026`.
+  - `"2026-05-10"` with `date:long` and `lang: es-ES` → `10 de mayo de 2026`.
+  - `"2026-10-12T12:00:00Z"` with `date:relative`, `context.now` at `"2026-10-05T12:00:00Z"` and `lang: en-US` → `in 7 days`; with no `context.now` → `Oct 12, 2026`.
 
 ### `duration`
 
@@ -100,10 +102,10 @@ Produces a localized human-readable duration in years, months, days, hours, minu
 - **Syntax**: `{value | duration}` or `{value | duration:UNIT}`
 - **Args**:
   - `UNIT` (string, default `"ms"`) — input unit when the value is a number. One of `ms`, `s`, `min`, `h`, `d`.
-- **Backend**: `date-fns` (`formatDistanceToNow`, `formatDuration`, `intervalToDuration`).
+- **Backend**: `Intl.RelativeTimeFormat` for a date, and `date-fns` (`formatDuration`, `intervalToDuration`) for a number.
 - **Behavior depends on input type**:
   - **Number** (or numeric string): treated as a duration in `UNIT` units, converted to milliseconds, then formatted as a breakdown (`"1 day 2 hours"`).
-  - **`Date` or non-numeric ISO string**: distance between the date and "now" with a suffix (`"3 months ago"`, `"in 2 days"`).
+  - **`Date` or non-numeric ISO string**: distance between the date and [`context.now`](overview.md#the-instant-relative-dates-use) with a suffix (`"3 months ago"`, `"in 2 days"`). Without `context.now` the date is shown in the `medium` style.
 - **Multipliers to milliseconds**:
 
   | Unit  | Multiplier |
@@ -118,15 +120,12 @@ Produces a localized human-readable duration in years, months, days, hours, minu
   - `{age | duration:s}` with `3600` → `1 hour`.
   - `{wait | duration:min}` with `90` → `1 hour 30 minutes`.
   - `{ms | duration}` with `93_600_000` → `1 day 2 hours`.
-  - `{createdAt | duration}` with an ISO date in the past → `3 months ago`.
-
-## Supported locales
+  - `{createdAt | duration}` with `"2026-07-07T12:00:00Z"` and `context.now` at `"2026-10-05T12:00:00Z"` → `3 months ago`.
 
-Out of the box, the following locales map to a `date-fns/locale` bundle for `date` (relative and pattern styles) and `duration`:
+## Supported languages
 
-- `en`, `en-US` → `enUS`
-- `es`, `es-ES`, `es-MX` → `es`
+The named date styles, `relative`, `currency`, `percent` and `number` are written by `Intl`, in any well-formed BCP 47 tag the runtime supports. In English the named styles read as they always did: `10/2/26`, `Oct 2, 2026`, `October 2, 2026`, `Friday, October 2, 2026`.
 
-Other locale codes match by language prefix (e.g. `es-AR` → `es`). If no match is found, `enUS` is used as fallback.
+`relative` writes the distance in the largest unit that holds it once rounded: seconds, minutes, hours, days up to a month, months up to a year, and then years. `in 40 seconds`, `in 3 hours`, `in 1 month`; 59 minutes and 40 seconds is `1 hour ago`, and no distance at all is `now` (`ahora` in Spanish).
 
-`Intl`-backed filters (`currency`, `percent`, `number`) accept any well-formed BCP 47 locale tag supported by the runtime.
+A date pattern (`date:dd/MM/yyyy`) and a `duration` of a number are written by `date-fns`, which the library ships in English and Spanish. A tag matches by its base language (`es-AR` writes Spanish), and any other language gets English names and units.

package/docs/interpolation/overview.md

@@ -33,13 +33,18 @@ about interpolation is one being read as the other.
 dot notation for anything nested:
 
 ```tsx
-<Form
-  sections={sections}
-  config={config}
-  context={{ user: { firstName: 'Jane' }, plan: 'pro' }}
-/>
+const context = { user: { firstName: 'Jane' }, plan: 'pro' }
+
+export function Page() {
+  return <Form sections={sections} config={config} context={context} />
+}
 ```
 
+Keep `context` the same object while nothing in it changes, as here, or with
+`useMemo` when it comes from state: every field renders again when it is a new
+one. See
+[What the host knows](../structure/definition.md#what-the-host-knows-context).
+
 ```json
 {
   "name": "greeting",
@@ -148,19 +153,44 @@ until somebody fills it.
 - **Spaces are trimmed.** `{ value }` and `{value}` are the same placeholder, as
   are `{total|currency:USD}` and `{total | currency:USD}`.
 
-## The locale filters use
+## The language filters use
+
+Filters format in the form's language, its `lang`: the same tag that picks its
+[translations](../fields/list.md#built-in-translations) and names its months.
+
+```tsx
+<Form sections={sections} config={config} lang="es-CO" />
+```
+
+It reaches every filter the form runs: a label, a description and the payload
+of a `value` or `source` action format the same value the same way. Without
+`lang`, with one that is no language tag (`es_MX`), or with one the runtime has
+no language for (`sp`), the form speaks English, on the server and in the
+browser alike, whatever language their machines speak. Its translations follow
+the same tag, so a form never writes in two languages.
+`config.env.locale` is not read; a development build names one left in the
+config.
 
-Locale-aware filters read `config.env.locale`:
+## The instant relative dates use
 
-```ts
-defineConfig({ inputs: [...], env: { locale: 'es-ES', currency: 'EUR' } })
+The form keeps no clock. A [`date:relative`](format-filters.md#date) or a [`duration`](format-filters.md#duration) of a date is measured from `context.now`, an ISO date, time and offset the host passes, such as `2026-10-05T19:30:00-05:00` or what `toISOString()` gives:
+
+```tsx
+// Worked out once per request, on the server.
+const context = { now: new Date().toISOString(), renewal: plan.renewsAt }
+
+<Form sections={sections} context={context} config={config} />
+```
+
+```json
+{ "label": "Renews {context.renewal | date:relative}" }
 ```
 
-It reaches every filter the form renders — a label and a description format the
-same value the same way. With no `locale` set, filters fall back to the locale of
-whatever is running the code: the browser in the client form, the process in the
-server one, which are not always the same machine. Set it once in `env` and both
-renders agree.
+With `now` at `2026-10-05T12:00:00Z` and the renewal at `2026-10-10T12:00:00Z`, the label reads `Renews in 5 days` on the server and in the browser alike, whatever their clocks say. Without `context.now`, or with one that is no ISO instant, the date is shown in the `medium` style: `Renews Oct 10, 2026`.
+
+The offset is what makes it an instant. Without one, `2026-10-05T12:00:00` or `2026-10-05` would be read in the zone of the machine that renders it, so the form takes it for no instant. So is a `Date` or a timestamp: a development build names each once for the `context` that carries it. The date being measured is read the way the [`date`](format-filters.md#date) filter reads any date, so give it with its offset too: a day alone is midnight where the code runs, and the distance to it changes with the machine.
+
+`now` is the one key of `context` the form reads on its own, wherever the text it formats can read `context`: a label and a description. A [`value` or `source` payload](#event-payloads) resolves against the selected option and nothing else, so a relative date written there shows the date. A [`select/timezone`](../fields/specialized-selectors.md#4-timezone-selector-selecttimezone) labels its zones for the same instant.
 
 ## An unresolved placeholder cancels a request
 

package/docs/setup.md

@@ -16,7 +16,7 @@ dependency, so your application resolves one copy of React, Zod and the rest.
 | Peer                 | Version   | Used for                                    |
 | -------------------- | --------- | ------------------------------------------- |
 | `react`, `react-dom` | `^19.0.0` | rendering, and `useActionState` on submit   |
-| `zod`                | `^4.0.0`  | the schema derived from `sections`          |
+| `zod`                | `^4.0.6`  | the schema derived from `sections`          |
 | `jotai`              | `^2.0.0`  | the value, error and source stores          |
 | `swr`                | `^2.0.0`  | fetching a field's remote `source`          |
 | `date-fns`           | `^4.0.0`  | date and time formatting, `duration` filter |
@@ -29,6 +29,10 @@ them in for you; anywhere else, install them alongside the library. A missing
 peer surfaces as a module resolution error at import time, not as a form that
 renders badly.
 
+Zod has to be 4.0.6 or later. An earlier 4.0 reports a value that an optional
+text or email field holds back as `Invalid input`, instead of with the field's
+own message.
+
 ## Styling
 
 The components render Tailwind utility classes and **the build ships no CSS**.
@@ -141,7 +145,8 @@ Check the console when a remote source comes back empty — see
 - `alert` is the component that renders the error summary, when `showError`
   is on.
 - `env` is a flat record of values available to interpolation, in labels and in
-  descriptions. Its `locale` key is also what those two read to format values.
+  descriptions. It holds the application's values: the language is the form's
+  `lang`, and a development build names an `env.locale` nothing reads.
 
 ## Warnings
 
@@ -164,21 +169,21 @@ production build does not. Where nothing defines it at all, they are shown.
 The client form. It owns its own state, so it is the one to use for anything
 interactive.
 
-| Prop            | Purpose                                                                                                         |
-| --------------- | --------------------------------------------------------------------------------------------------------------- |
-| `sections`      | the field descriptors — the form itself                                                                         |
-| `config`        | the result of `defineConfig`                                                                                    |
-| `value`         | the current values                                                                                              |
-| `action`        | server action invoked on submit, receives the form data and the schema — see [forms/submit.md](forms/submit.md) |
-| `onSuccess`     | called with the parsed data after `action` succeeds                                                             |
-| `onValueChange` | called with `{ name, value }` on every change                                                                   |
-| `readOnly`      | renders every field disabled                                                                                    |
-| `translations`  | per-locale strings for labels, options and messages                                                             |
-| `lang`          | the locale to resolve `translations` against                                                                    |
-| `context`       | arbitrary values available to interpolation                                                                     |
-| `definition`    | the JSON that [`$ref`](structure/definition.md) entries resolve against                                         |
-| `advanced.step` | numbers the [sections](structure/sections.md#advancedstep-numbers-the-sections)                                 |
-| `children`      | the form's control area — see [forms/submit.md](forms/submit.md#nothing-submits-without-a-control)              |
+| Prop            | Purpose                                                                                                                 |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `sections`      | the field descriptors — the form itself                                                                                 |
+| `config`        | the result of `defineConfig`                                                                                            |
+| `value`         | the current values                                                                                                      |
+| `action`        | server action invoked on submit, receives the form data and the schema — see [forms/submit.md](forms/submit.md)         |
+| `onSuccess`     | called with the parsed data after `action` succeeds                                                                     |
+| `onValueChange` | called with `{ name, value }` on every change                                                                           |
+| `readOnly`      | renders every field disabled                                                                                            |
+| `translations`  | per-language strings for labels, options and messages                                                                   |
+| `lang`          | the form's language: its translations, its month and day names, its filters and the dates it shows; English without one |
+| `context`       | arbitrary values available to interpolation, and to a `$ref` under `#/context/`                                         |
+| `definition`    | the JSON that [`$ref`](structure/definition.md) entries resolve against                                                 |
+| `advanced.step` | numbers the [sections](structure/sections.md#advancedstep-numbers-the-sections)                                         |
+| `children`      | the form's control area — see [forms/submit.md](forms/submit.md#nothing-submits-without-a-control)                      |
 
 ### `Form` from `react-luna-form/server`
 

package/docs/structure/definition.md

@@ -67,6 +67,42 @@ section:
 References inside a definition are resolved too, so one entry can be built out
 of others.
 
+## What the host knows: `#/context/`
+
+A definition is JSON the form reuses. What the host only knows when it renders,
+such as the options a user may pick or the nights already booked, is passed as
+the form's `context` prop instead and read with the same syntax, under
+`#/context/`:
+
+```json
+{
+  "name": "room",
+  "type": "select",
+  "source": { "$ref": "#/context/rooms" }
+}
+```
+
+```tsx
+const context = useMemo(() => ({ rooms }), [rooms])
+
+<Form sections={sections} context={context} config={config} />
+```
+
+Both roots resolve the same way and follow the rules below. A path with no root
+reads the definition, as it always has, and an entry of the definition can
+point into `#/context/`.
+
+One key of `context` is read by the form on its own: `now`, the instant
+[relative dates](../interpolation/overview.md#the-instant-relative-dates-use)
+are measured from and a time zone select labels its zones for. The form keeps
+no clock, so without it there is no "now".
+
+Keep `context` the same object while nothing in it changes, and hand over a new
+one when something does. Every field renders again when `context` is a new
+object, since a label or a description may interpolate it, and a field whose
+JSON reads `#/context/` is resolved again as well. A value changed in place, in
+the same object, is not something the form can notice.
+
 ## The rules
 
 - **Resolution happens once, before anything else.** The tree is resolved first,
@@ -76,24 +112,27 @@ of others.
   stays as the literal `{ "$ref": ... }` object. What that looks like on screen
   depends on where it was — a field whose `source` is still a reference renders
   with no options at all, which is the usual way a typo in the path is noticed.
-- **An empty or missing `definition` resolves nothing.** `definition={{}}` is
-  treated as absent, and every `$ref` in the form is left as written.
+  A path that holds nothing is unresolved too: a key that is missing, and one
+  the host left `undefined` or `null`.
+- **An empty or missing root resolves nothing under it.** `definition={{}}` is
+  treated as absent, and so is `context={{}}`: every `$ref` into a root that is
+  absent is left as written.
 - **A cycle stops instead of hanging.** Two entries pointing at each other
   resolve until the loop closes and leave the reference that would repeat
   unresolved.
 
 ## Pass it everywhere the sections go
 
-`definition` is a prop of both the client and the server `Form`, and the third
-argument of the headless builder:
+`definition` and `context` are props of both the client and the server `Form`,
+and the third and fourth arguments of the headless builder:
 
 ```ts
 import { buildFormSchema } from 'react-luna-form/schema'
 
-const schema = buildFormSchema(sections, translations, definition)
+const schema = buildFormSchema(sections, translations, definition, context)
 ```
 
-A schema built without the definition sees `$ref` objects where the form sees
+A schema built without them sees `$ref` objects where the form sees
 fields — the rendered form and the validated shape drift apart, which is the one
 thing [the schema being derived from the same descriptors](../validation/overview.md#headless-validation)
 is meant to prevent.

package/docs/validation/overview.md

@@ -17,7 +17,10 @@ This page documents every key of the `validation` object plus the shared operato
 
 - **`required`** _(string)_: Message shown when a field marked `required: true` is empty.
 - **`email`** _(string)_: Message for an invalid email format (`input/email`).
-- **`length`** _({ min?: string, max?: string })_: Messages when the value's length breaches `advanced.length`.
+- **`date`** _(string)_: Message when an `input/date` holds text that is no day. See [Input](../fields/input.md#what-a-date-holds).
+- **`length`** _({ min?: string, max?: string })_: Messages when the value breaches `advanced.length`: its length, a number's range, or a date's first and last day. See [Input](../fields/input.md#the-first-and-the-last-day).
+- **`reserved`** _(string)_: Message when an `input/date` holds a day its `advanced.reserved` lists. See [Input](../fields/input.md#days-nobody-can-pick).
+- **`range`** _(string)_: Message when an `input/date` range has an end missing, or its last day before its first. See [Input](../fields/input.md#a-range-of-days).
 - **`step`** _(string)_: Message when an `input/number` is off its step: a decimal on a whole number, or a value off `advanced.step`. See [Input](../fields/input.md).
 - **`custom`** _(CustomValidation | CustomValidation[])_: Cross-field comparison. See [Custom (cross-field)](#custom-cross-field).
 - **`requiredWhen`** _(WhenRule | WhenRule[])_: Conditionally required. See [requiredWhen](#requiredwhen).
@@ -260,20 +263,20 @@ if (!result.success) {
 }
 ```
 
-- **`buildFormSchema(sections, translations?, definition?)`** — walks the form tree (sections → columns → lists → fields) and returns a Zod schema. Lists become arrays of objects, so nested `requiredWhen`/`rules` resolve in **item scope**. `translations` maps messages to localized strings; `definition` resolves [`$ref` entries](../structure/definition.md), and has to be the same one the form renders with.
+- **`buildFormSchema(sections, translations?, definition?, context?)`** — walks the form tree (sections → columns → lists → fields) and returns a Zod schema. Lists become arrays of objects, so nested `requiredWhen`/`rules` resolve in **item scope**. `translations` maps messages to localized strings; `definition` and `context` resolve [`$ref` entries](../structure/definition.md), and have to be the same ones the form renders with. A date comes out of it as `yyyy-MM-dd`, as it does from the form's submit.
 - **`collectIssues(error)`** — flattens a `ZodError` into `{ path, message }` entries with **dotted paths** (e.g. `rules.0.value`), including nested list issues.
 
 ### What each path validates
 
-| Rule                                          | Rendered `<Form>` submit | `buildFormSchema` (headless) |
-| --------------------------------------------- | ------------------------ | ---------------------------- |
-| `required`, `email`, `length`, `step` (field) | ✅                       | ✅                           |
-| `custom`                                      | ✅                       | ✅                           |
-| `requiredWhen` (top-level)                    | ✅                       | ✅                           |
-| `pattern`                                     | ✅                       | ✅                           |
-| `rules` (top-level)                           | ✅                       | ✅                           |
-| `requiredWhen` **inside a list** (item scope) | —                        | ✅                           |
-| List `length`                                 | —                        | ✅                           |
+| Rule                                                                       | Rendered `<Form>` submit | `buildFormSchema` (headless) |
+| -------------------------------------------------------------------------- | ------------------------ | ---------------------------- |
+| `required`, `email`, `length`, `step`, `date`, `reserved`, `range` (field) | ✅                       | ✅                           |
+| `custom`                                                                   | ✅                       | ✅                           |
+| `requiredWhen` (top-level)                                                 | ✅                       | ✅                           |
+| `pattern`                                                                  | ✅                       | ✅                           |
+| `rules` (top-level)                                                        | ✅                       | ✅                           |
+| `requiredWhen` **inside a list** (item scope)                              | —                        | ✅                           |
+| List `length`                                                              | —                        | ✅                           |
 
 The headless builder is the superset: item-scoped conditions and list length require the nested tree it produces.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-luna-form",
-  "version": "0.0.87",
+  "version": "0.0.89",
   "description": "A React library for building forms based on JSON",
   "main": "./dist/client/cjs/index.js",
   "module": "./dist/client/esm/index.js",
@@ -26,10 +26,10 @@
     "react-dom": "^19.0.0",
     "swr": "^2.0.0",
     "tailwind-merge": "^3.7.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.6"
   },
   "devDependencies": {
-    "@luna-form/core": "0.0.87",
+    "@luna-form/core": "0.0.89",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "eslint-plugin-react": "7.37.5",

package/dist/types/luna-react/src/client/hook/use-format.d.ts

@@ -1,5 +0,0 @@
-import { type Field } from '../../../../luna-core/index';
-export declare function useFormat(field: Field): {
-    dateFormat: import('../../../../luna-core/index').DateFormat | null;
-    timeFormat: import('../../../../luna-core/index').TimeFormat | null;
-};