react-luna-form 0.0.85 → 0.0.87

package/docs/fields/input.md

@@ -28,10 +28,9 @@ Luna Form's input fields inherit the standard logical properties available to al
   - Or an object payload: `{ title: string, message: string, collapsed?: boolean }`.
 - **`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.
-- **`readonly`** _(boolean, optional)_: If `true`, the field's value is locked and cannot be modified by the user.
+- **`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.
 - **`hidden`** _(boolean, optional)_: If `true`, the field is hidden from the user interface.
-- **`keepValue`** _(boolean, optional)_: If `true`, hiding the field leaves its value behind instead of taking it. See [What clearing a hidden target means](../events/change.md#what-clearing-a-hidden-target-means).
 - **`order`** _(number, optional)_: A numeric order determining the field's position relative to adjacent fields.
 
 ---
@@ -48,6 +47,7 @@ The `advanced` property dictates finer HTML details, interactive structures, and
 - **`reverse`** _(boolean)_: `checkbox` only, and it exists to turn a default **off**. A checkbox renders its box first and its label after it; `reverse: false` swaps them, `true` changes nothing, and on any other field type the key is not read. See [Layout](../structure/layout.md#advancedreverse-checkbox-only).
 - **`aria`** _(object)_: Map of specific ARIA attributes for screen readers (e.g., `{ "aria-label": "Custom label" }`).
 - **`data`** _(object)_: Map of specific HTML data attributes (e.g., `{ "data-test-id": "my-field" }`).
+- **`keepValue`** _(boolean)_: If `true`, hiding the field leaves its value behind instead of taking it — the field is put away rather than dropped. See [Keeping a value through a hide](../events/change.md#keeping-a-value-through-a-hide).
 - **`transient`** _(boolean)_: If `true`, the field fires its change events and keeps nothing of its own — it is neither stored nor reported to the consumer. For a control whose whole job is to write to _another_ field. See [Transient controls](../events/change.md#transient-controls).
 
 ### Text & Numeric Options (`input/text`, `input/email`, `input/tel`, `input/password`, `input/number`)
@@ -55,12 +55,17 @@ 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).
+- **`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"`
   - `"uppercase"`
   - `"remove-space"`
   - `"remove-accent"`
 
+### Empty and required numbers
+
+A required `input/number` accepts `0` and negative numbers: required means a value is present, not that it is at least 1. An optional one left empty is not submitted at all, rather than submitted as `0`, and its `length` bounds only apply to a value that is there. `select/year` and `select/month` read an empty selection the same way.
+
 ### Temporal Options (`input/date`, `input/time`)
 
 Date and time inputs omit transformations and instead expose a `format` property directly under `advanced` for displaying values properly:
@@ -77,6 +82,7 @@ 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.
+- **`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.
   - `operator`: Logical evaluation operations (e.g., `eq`, `neq`, `gt`, `lt`).

package/docs/fields/list.md

@@ -26,6 +26,8 @@ The `advanced` property customizes structural interaction rules and layout rende
 - **`length`** _({ min?: number, max?: number })_: Configures restrictions on how many items can be generated. Enforces boundary conditions where minimum instances ensure permanent default items and maximum instances automatically disable insertion toggles. The matching error messages are declared under the list's `validation.length` — see the [Validation reference](../validation/overview.md#list-length).
   Both bounds apply to the rows a list opens with, not only to the ones added by hand: an initial `value` shorter than `min` leaves the remainder standing and empty, and one longer than `max` stops at `max`. A [`value` event](../events/change.md#targeting-a-list) assigning rows is clamped the same way.
 - **`collapsed`** _(boolean)_: When enabled, list items default to a visually collapsed representation upon mounting or adding.
+  Collapsing only hides a row: its fields keep their values, still validate and are still submitted, and a submit that fails on one of them opens the row so the error can be seen.
+- **`keepValue`** _(boolean)_: If `true`, hiding the list leaves the values behind instead of taking them. A list holds nothing under its own name, so declaring it here is a statement about the rows: it covers every value they hold. See [Keeping a value through a hide](../events/change.md#keeping-a-value-through-a-hide).
 
 ### Collapsed Previews (`preview` object)
 

package/docs/fields/specialized-selectors.md

@@ -17,6 +17,8 @@ Renders a dropdown with the 12 months of the year.
 }
 ```
 
+An optional month 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.
+
 ### 2. Year Selector (`select/year`)
 
 Renders a dropdown with a range of years.
@@ -38,6 +40,8 @@ Renders a dropdown with a range of years.
 }
 ```
 
+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`)
 
 Renders a dropdown with days 1 through 31.

package/docs/forms/submit.md

@@ -103,18 +103,24 @@ If the values have to survive, hold them outside the form: mirror
 people, which is that a key you stop sending is not the same as a key you send
 empty.
 
-A **failed** validation is the opposite: the submitted values are handed back to
-the form, so the user's typing is still on screen next to the errors.
+A **failed** submit is the opposite: nothing is cleared or reset, so what the
+user entered stays on screen next to the errors — typed text, ticked boxes and
+picked options alike. An error inside a collapsed
+[section](../structure/sections.md#advancedcollapsible) or list row is brought
+on screen too: the section or row holding it opens. The form does not take over
+`value` either. What you pass is still what the fields read, so you can change
+it, or put it back, while the errors are showing.
 
 ## Turning submit validation off
 
-`defineConfig({ validation: { submit: false, ... } })` skips the parse
-entirely. The action is called with the raw `FormData` and the schema, and
-nothing is checked, reported or cleared on the way — for a form whose action
-does its own parsing. With no action at all, submitting does nothing.
+`defineConfig({ validation: { submit: false } })` skips the parse entirely. The
+action is called with the raw `FormData` and the schema, and nothing is checked,
+reported or cleared on the way — for a form whose action does its own parsing.
+With no action at all, submitting does nothing.
 
-Remember that this object [replaces the defaults rather than merging](../setup.md#validation),
-so pass the keys you still want.
+The other three keys are untouched by that: this object
+[merges into the defaults](../setup.md#validation), so a form that stops
+validating on submit goes on validating as the user types.
 
 ## The error summary
 

package/docs/setup.md

@@ -13,15 +13,15 @@ pnpm add react-luna-form
 The package carries no dependencies of its own: everything it needs is a peer
 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`          |
-| `jotai`, `jotai-family` | `^2.0.0` / `^1.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 |
-| `fast-equals`           | `^6.0.0`            | change detection in the stores              |
-| `tailwind-merge`        | `^3.5.0`            | merging the classes the components render   |
+| Peer                 | Version   | Used for                                    |
+| -------------------- | --------- | ------------------------------------------- |
+| `react`, `react-dom` | `^19.0.0` | rendering, and `useActionState` on submit   |
+| `zod`                | `^4.0.0`  | 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 |
+| `fast-equals`        | `^6.0.0`  | change detection in the stores              |
+| `tailwind-merge`     | `^3.7.0`  | merging the classes the components render   |
 
 None of them is optional, and none is bundled. A package manager that installs
 peers automatically (npm 7+, or pnpm with `auto-install-peers=true`) brings
@@ -48,20 +48,26 @@ CSS.
 
 Every element also carries a `data-slot` attribute — `field`, `field-label`,
 `field-control`, `field-set`, `field-set-content`, `field-content`,
-`field-group`, `field-separator`, `column`, `list-item-card` — so a design
-system can restyle the structure without patching the library. The components
-you register yourself are yours to style; these slots cover the scaffolding
-around them.
+`field-group`, `field-separator`, `collapsible-content`, `column`,
+`list-item-card` — so a design system can restyle the structure without
+patching the library. The components you register yourself are yours to style;
+these slots cover the scaffolding around them.
 
 ## Entry points
 
 | Import                   | Contains                                                                                  |
 | ------------------------ | ----------------------------------------------------------------------------------------- |
 | `react-luna-form`        | `Form` (client), `withDeclaredFields`, and the `Sections`, `Source` and `ZodSchema` types |
-| `react-luna-form/server` | `Form` (server) and `Fallback`                                                            |
+| `react-luna-form/server` | `Form` (server) and `Fallback`, usable under the `react-server` condition                 |
 | `react-luna-form/config` | `defineConfig` and the `define*` registration helpers                                     |
 | `react-luna-form/schema` | `buildFormSchema` and `collectIssues`                                                     |
 
+The client bundle is published carrying a `'use client'` directive, so an App
+Router project imports `Form` straight from a Server Component and needs no
+wrapper module of its own to say it. The server bundle carries none and
+resolves under the `react-server` condition, which is what lets a Server
+Component render the form itself.
+
 ## Configuring
 
 `defineConfig` is called once, usually in a `luna.config.ts` at the root of the
@@ -99,10 +105,9 @@ When to validate and whether to summarise errors. All four default to `true`.
 validation: { blur: true, change: true, showError: true, submit: true }
 ```
 
-**This object replaces the defaults, it does not merge into them.** Passing
-`{ change: false }` also turns off `blur`, `submit` and `showError`, so the form
-stops validating on blur and loses its error summary with no indication why.
-Pass every key you still want.
+This object merges into the defaults, so pass only what you want to change.
+`{ change: false }` stops the form validating as the user types and leaves the
+other three alone.
 
 ### `fetcher.remotePatterns`
 
@@ -127,7 +132,8 @@ fetcher: {
 A blocked URL is not an error. The library logs
 `URL blocked by remotePatterns: <url>` and the field renders with no options at
 all, which on screen looks like an empty select rather than a rejected request.
-Check the console when a remote source comes back empty.
+Check the console when a remote source comes back empty — see
+[Warnings](#warnings) for when that line is written.
 
 ### `style`, `alert`, `env`
 
@@ -137,6 +143,20 @@ Check the console when a remote source comes back empty.
 - `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.
 
+## Warnings
+
+Some of what can go wrong is nobody's to fix but the author of the form, and
+the library says so on the console rather than on screen: a `pattern` that does
+not compile, a field name that reaches a prototype and is left out of the
+submit, the error an `action` threw, a remote `source` that failed or was
+blocked. Every one of those lines is prefixed `[Luna Form]`.
+
+They are written outside production and silent inside it, and which one you are
+in is your build's answer to give: the published bundle leaves
+`process.env.NODE_ENV` for your bundler to resolve instead of deciding while it
+is being packaged. A development build of your application shows them and a
+production build does not. Where nothing defines it at all, they are shown.
+
 ## Rendering
 
 ### `Form` from `react-luna-form`

package/docs/structure/sections.md

@@ -95,7 +95,7 @@ Renders the section closed, with its title as the toggle:
 }
 ```
 
-Three things to know before using it:
+Four things to know before using it:
 
 - **It always starts closed.** There is no key that opens it, and reopening the
   form does not remember that the user had expanded it.
@@ -103,6 +103,8 @@ Three things to know before using it:
   them. They keep their values, they still validate, and they are still
   submitted. That is the opposite of what a [`state` action](../events/change.md#what-clearing-a-hidden-target-means)
   does when it hides a field, which unmounts it and clears the value.
+- **A failed submit opens it.** When a field inside fails validation, the
+  section opens so the error can be seen, and it stays open.
 - **The description moves inside.** It renders with the fields rather than under
   the title, so it is not visible while the section is closed.
 

package/docs/validation/overview.md

@@ -18,6 +18,7 @@ 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`.
+- **`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).
 - **`pattern`** _(PatternRule)_: Regex/format check. See [pattern](#pattern).
@@ -110,6 +111,14 @@ Validates a string value against a regular expression.
 
 `pattern` never fires on an empty value — pair it with `required`/`requiredWhen` when the field is mandatory.
 
+A `regex` or `flags` that does not compile is a mistake in the definition, not in the value. The rule then holds back every value it checks with its `message`, as it does a value that does not match, and the form keeps working. The same goes for a `pattern` among [`rules`](#rules). Since the `message` is written for whoever fills the form in, the expression that failed to compile is named on the console instead — see [Warnings](../setup.md#warnings).
+
+A `regex` that compiles runs as written, on what the user types: in the browser when the form is submitted, and on the server when it validates with `buildFormSchema`. Nothing inspects it first, so it is part of the code the form ships with. Accept one only from someone you would let write that code.
+
+The shape to avoid is a pattern that can split the same text between its repetitions in more than one way, such as `^(a+)+$`, `^(\w+\s?)+$` or `^(a|a)+$`. On a value that almost matches, it backtracks exponentially, and about thirty characters can hold the page, or the server, for seconds. A repetition that opens with a separator the one before cannot close with is not ambiguous and runs in linear time, as in `^[a-z]+(-[a-z]+)*$` or `^\d+(,\d+)*$`.
+
+If definitions reach you from other people, check their patterns with a ReDoS analyzer before you accept them.
+
 ---
 
 ## `rules`
@@ -258,7 +267,7 @@ if (!result.success) {
 
 | Rule                                          | Rendered `<Form>` submit | `buildFormSchema` (headless) |
 | --------------------------------------------- | ------------------------ | ---------------------------- |
-| `required`, `email`, `length` (field)         | ✅                       | ✅                           |
+| `required`, `email`, `length`, `step` (field) | ✅                       | ✅                           |
 | `custom`                                      | ✅                       | ✅                           |
 | `requiredWhen` (top-level)                    | ✅                       | ✅                           |
 | `pattern`                                     | ✅                       | ✅                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-luna-form",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "description": "A React library for building forms based on JSON",
   "main": "./dist/client/cjs/index.js",
   "module": "./dist/client/esm/index.js",
@@ -22,20 +22,20 @@
     "date-fns": "^4.0.0",
     "fast-equals": "^6.0.0",
     "jotai": "^2.0.0",
-    "jotai-family": "^1.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "swr": "^2.0.0",
-    "tailwind-merge": "^3.5.0",
+    "tailwind-merge": "^3.7.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.5",
+    "@luna-form/core": "0.0.87",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.1.1",
-    "eslint-plugin-react-refresh": "0.5.5",
-    "@luna-form/core": "0.0.85"
+    "eslint-plugin-react-refresh": "0.5.7",
+    "jotai-family": "1.1.0"
   },
   "license": "Apache-2.0",
   "repository": {

package/dist/types/luna-react/src/client/component/field/field-with-state.d.ts

@@ -1,13 +0,0 @@
-export declare function withError<P extends {
-    errors?: Record<string, string[]>;
-    field: {
-        name: string;
-    };
-}>(Component: React.ComponentType<P>): (props: Readonly<P>) => import("react").JSX.Element | null;
-export declare function withState<P extends {
-    disabled?: boolean;
-    field: {
-        name: string;
-        hidden?: boolean;
-    };
-}>(Component: React.ComponentType<P>): (props: Readonly<P>) => import("react").JSX.Element | null;