react-luna-form 0.0.87 → 0.0.88

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

@@ -141,7 +141,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 +165,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.88",
   "description": "A React library for building forms based on JSON",
   "main": "./dist/client/cjs/index.js",
   "module": "./dist/client/esm/index.js",
@@ -29,7 +29,7 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@luna-form/core": "0.0.87",
+    "@luna-form/core": "0.0.88",
     "@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;
-};