react-luna-form 0.0.83 → 0.0.85

package/docs/structure/layout.md

@@ -0,0 +1,189 @@
+# Layout
+
+Inside a section, fields stack one per row. Everything else — fields side by
+side, a label beside its control — is opt in, and this page is where those keys
+live.
+
+## Columns (`type: "column"`)
+
+A `column` is a grid that holds fields. It is declared among the fields of a
+section (or of a [list](../fields/list.md) row) and takes a `fields` array of
+its own:
+
+```json
+{
+  "type": "column",
+  "advanced": { "cols": 2 },
+  "fields": [
+    { "name": "first_name", "type": "input/text", "label": "First name" },
+    { "name": "last_name", "type": "input/text", "label": "Last name" }
+  ]
+}
+```
+
+A column has no `name` and holds no value. It groups its fields visually and
+nothing more: they keep the names they declare, and the submitted object is the
+same one you would get without it.
+
+| Key             | Type                   | Does                                       |
+| --------------- | ---------------------- | ------------------------------------------ |
+| `type`          | `"column"`             | required, exactly this string              |
+| `fields`        | `Array<Field \| List>` | what the grid holds                        |
+| `advanced.cols` | `1 \| 2 \| 3`          | how many columns the grid has, default `2` |
+| `description`   | `string \| object`     | help text under the grid                   |
+| `order`         | `number`               | position among the section's other entries |
+
+### `cols`, and the values that are not
+
+`cols` accepts `1`, `2` and `3`. **Anything else falls back to `2`** —
+`"cols": 4`, `"cols": 0`, a string, or the key left out entirely all produce the
+same two-column grid, with no error and no warning. A four-column layout is not
+something to reach for by writing `4`; it does not exist.
+
+The grid is one column below the `md` breakpoint and `cols` columns from there
+up, so a column layout stacks on a phone whatever it says.
+
+### A field's own `cols` is a span
+
+Inside a column, a field's `advanced.cols` says how many of the grid's columns
+that field takes:
+
+```json
+{
+  "type": "column",
+  "advanced": { "cols": 3 },
+  "fields": [
+    {
+      "name": "card_number",
+      "type": "input/text",
+      "label": "Card number",
+      "advanced": { "cols": 2 }
+    },
+    { "name": "cvc", "type": "input/text", "label": "CVC" }
+  ]
+}
+```
+
+The card number takes two of the three columns and the CVC takes the third.
+Spans of `1`, `2` and `3` are honoured and anything else is ignored, leaving the
+field at one cell — unlike the container's `cols`, an out-of-range span does not
+fall back to a default.
+
+The same key means different things in the two places, which is worth reading
+twice: on a `column` it is **how many columns the grid has**, on a field inside
+it, **how many of them the field covers**.
+
+A field's span outside a column does nothing at all. The class is emitted, the
+parent is not a grid, and the field goes on filling the width.
+
+### Description
+
+A column's `description` renders **under** the grid, not above it, and unlike a
+[section's description](sections.md#title-and-description-are-translated-not-interpolated)
+it goes through interpolation: `{context.*}`, `{env.*}` and
+[format filters](../interpolation/format-filters.md) all resolve. It also takes
+the `{ title, message, collapsed }` object form that a field description takes.
+
+### What a column can hold
+
+Fields and [lists](../fields/list.md). A column inside a list row is supported
+and keeps its grid; the fields inside it are named by the row's path like any
+other leaf.
+
+A column has no visibility of its own: `hidden` on a column is not read. Hide
+the fields it holds instead — and note that when every field in a column is
+hidden, the column counts as hidden for the
+[section's visibility](sections.md#order-and-what-disappears), while the grid
+element itself stays in the layout.
+
+### Labels truncate inside a grid
+
+A label that is longer than its cell is truncated to one line inside a column,
+where the same label wraps outside one. This keeps the inputs of a row aligned
+with each other instead of one sinking below its neighbour. Write the short
+version in the `label` and put the rest in the `description`.
+
+## Ordering fields and columns
+
+Every entry in a `fields` array — a field, a column, a list — sorts by `order`
+before rendering. Entries carrying one sort ascending; entries without one hold
+their relative position and follow the rest. Because a column sorts as a single
+entry, `order` interleaves whole columns with the plain fields around them, not
+the fields inside them.
+
+## Orientation (`advanced.horizontal`)
+
+By default a field renders its label above its control. `advanced.horizontal`
+puts them side by side from the `md` breakpoint up:
+
+```json
+{
+  "name": "timeout",
+  "type": "input/number",
+  "label": "Timeout",
+  "advanced": { "horizontal": true }
+}
+```
+
+A form that wants every field that way sets it once as
+`style.horizontal` in [`defineConfig`](../setup.md#style-alert-env). A field
+that declares nothing inherits it; one that declares `false` opts out of it.
+
+Two consequences:
+
+- **`radio` and `checkbox` are always horizontal**, whatever the key or the
+  form-wide style says. Their control belongs beside its label, so neither is
+  read for them.
+- **The description moves.** A vertical field renders its description after the
+  control; a horizontal one renders it under the label, in the label's own
+  column.
+
+The rendered field carries `data-orientation="horizontal"` or `"vertical"`,
+which is the attribute to key CSS on rather than the class names.
+
+## `advanced.reverse` (checkbox only)
+
+A `checkbox` renders its box first and its label after it. `reverse: false`
+swaps them:
+
+```json
+{
+  "name": "accepted",
+  "type": "checkbox",
+  "label": "I accept the terms",
+  "advanced": { "reverse": false }
+}
+```
+
+The default is the reversed order, so this key exists to turn it **off**, and
+`"reverse": true` changes nothing. It is read only for `checkbox`; on a `radio`,
+an `input/*` or anything else it is ignored.
+
+## Spacing
+
+Spacing between fields is a property of the section that holds them, not of the
+field: see [`advanced.compact`](sections.md#advancedcompact).
+
+## Styling hooks
+
+Every structural element carries a `data-slot`, so a design system can restyle
+the scaffolding without patching the library. The components you register in
+[`defineConfig`](../setup.md#inputs-required) are yours already; these are the
+parts around them.
+
+| `data-slot`         | Wraps                                                   |
+| ------------------- | ------------------------------------------------------- |
+| `field-set`         | one section, the rendered `<fieldset>`                  |
+| `field-set-content` | the body of a collapsible section                       |
+| `field-group`       | the stack of entries inside a section                   |
+| `field-separator`   | the rule drawn by `advanced.separator`                  |
+| `column`            | the grid of a `column`                                  |
+| `field`             | one field, with `data-orientation` on it                |
+| `field-label`       | the `<label>`                                           |
+| `field-content`     | the label and, when horizontal, the description with it |
+| `field-control`     | the form's own control area — where `children` renders  |
+| `list-item-card`    | one row of a [list](../fields/list.md)                  |
+
+A field also carries `data-invalid` while it holds an error and `data-readonly`
+while it is disabled, both readable from the descendants with
+`group-data-[...]`.

package/docs/structure/sections.md

@@ -0,0 +1,187 @@
+# Sections
+
+`sections` is the top level of a form. Every other page describes what goes
+inside one; this page describes the section itself.
+
+A section is a **visual grouping and nothing else**. It draws a legend, sets the
+spacing around its fields and can collapse them out of the way, but it does not
+scope names: every field in the form shares one flat namespace, whichever
+section it was declared in. Two fields called `email` in two different sections
+are one field with two renderings, and
+[`buildFormSchema`](../validation/overview.md#headless-validation) produces one
+key for them.
+
+## The shape
+
+| Key                    | Type               | Does                                          |
+| ---------------------- | ------------------ | --------------------------------------------- |
+| `fields`               | `Fields`           | what the section renders                      |
+| `title`                | `string`           | the legend                                    |
+| `description`          | `string`           | help text under the legend                    |
+| `id`                   | `string \| number` | the `id` attribute of the rendered `fieldset` |
+| `order`                | `number`           | position among the other sections             |
+| `advanced.compact`     | `boolean`          | tighter spacing between this section's fields |
+| `advanced.collapsible` | `boolean`          | render the section closed, behind a toggle    |
+| `advanced.separator`   | `boolean`          | draw a rule after the section                 |
+
+```json
+{
+  "sections": [
+    {
+      "id": "payment",
+      "title": "Payment Method",
+      "description": "All transactions are secure and encrypted",
+      "advanced": { "separator": true },
+      "fields": [{ "name": "name", "type": "input/text", "label": "Name" }]
+    }
+  ]
+}
+```
+
+## A section with no title and no description draws nothing
+
+There is no empty legend and no wrapper to style around it: the section's fields
+join the flow of the form as if they had been declared without one. This is the
+form to reach for when you want the grouping only for `compact` spacing or for
+`order`.
+
+Declaring `advanced.collapsible` on such a section does nothing either — with no
+title there is nothing to click, so the fields render open.
+
+## Title and description are translated, not interpolated
+
+Both are resolved against the [`translations`](../fields/list.md#localization)
+dictionary and both render `[text](url)` markdown links. Neither is passed
+through interpolation: a `{context.name}` in a section title stays on screen as
+the literal text `{context.name}`.
+
+This is the one place the rule differs. A field's `label` and `description`
+_are_ interpolated, and so is a [column's description](layout.md#description).
+If a section heading has to carry a value, put the value in a field description
+or in a column instead.
+
+## `advanced.compact`
+
+Spacing between the fields of this section, tight instead of loose. It is
+declared per section:
+
+```json
+{
+  "title": "Connection",
+  "advanced": { "compact": true },
+  "fields": [{ "name": "host", "type": "input/text" }]
+}
+```
+
+A section that declares nothing inherits `style.compact` from
+[`defineConfig`](../setup.md#style-alert-env), so the form-wide default holds
+and a section only has to speak up to differ from it — including to opt out,
+with `"compact": false` under a compact form.
+
+## `advanced.separator`
+
+Draws a horizontal rule **after** the section, between it and whatever follows.
+On the last section it draws a trailing rule, which is rarely what you want.
+
+## `advanced.collapsible`
+
+Renders the section closed, with its title as the toggle:
+
+```json
+{
+  "title": "Advanced options",
+  "advanced": { "collapsible": true },
+  "fields": [{ "name": "timeout", "type": "input/number" }]
+}
+```
+
+Three 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.
+- **The fields inside stay mounted.** Collapsing hides them; it does not unmount
+  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.
+- **The description moves inside.** It renders with the fields rather than under
+  the title, so it is not visible while the section is closed.
+
+A collapsible section also renders no step number, whatever `advanced.step` says.
+
+## `advanced.step` numbers the sections
+
+Declared on the **form**, not on a section, it puts a numbered badge beside each
+section's legend, counting the sections in the order they render:
+
+```tsx
+<Form advanced={{ step: true }} sections={sections} config={config} />
+```
+
+It is a numbering, not a wizard: every section is on screen at once, and the
+library ships nothing that shows them one at a time. The badge appears only on
+sections that draw a legend — a section with no title and no description has
+nowhere to put it, and a collapsible one does not take it.
+
+## `order`, and what disappears
+
+`sections` renders in array order unless a section declares `order`. Sections
+carrying one sort ascending; sections without one keep their relative order and
+follow the rest. The same rule applies to the entries inside a section, so a
+field and a column can be interleaved by `order` — see
+[layout.md](layout.md#ordering-fields-and-columns).
+
+Two kinds of section never render at all:
+
+- **One with no fields.** `"fields": []` is dropped before rendering, legend
+  included.
+- **One whose fields are all hidden.** Hidden by `hidden: true` in the JSON or
+  by a [`state` action](../events/change.md#2-state-action-stateevent) at run
+  time, it makes no difference: when nothing inside a section is visible the
+  section goes with it, and it comes back when one of them is shown again. A
+  column counts as hidden when every field in it is.
+
+A section has **no visibility flag of its own**. Writing `"hidden": true` on a
+section is accepted and ignored; hide its fields instead, or leave the section
+out of the array.
+
+## `id`
+
+Lands on the rendered `<fieldset>` as its `id` attribute, for an anchor link or
+a test selector. It is not a name and nothing resolves against it: fields are
+addressed by their own `name` from anywhere in the form.
+
+## Complete example
+
+```json
+{
+  "advanced": { "step": true },
+  "sections": [
+    {
+      "id": "contact",
+      "title": "Contact",
+      "description": "How we reach you about this order",
+      "advanced": { "separator": true },
+      "fields": [
+        { "name": "email", "type": "input/email", "label": "Email" },
+        { "name": "phone", "type": "input/tel", "label": "Phone" }
+      ]
+    },
+    {
+      "title": "Delivery",
+      "advanced": { "compact": true },
+      "fields": [
+        { "name": "street", "type": "input/text", "label": "Street" },
+        { "name": "city", "type": "input/text", "label": "City" }
+      ]
+    },
+    {
+      "title": "Advanced options",
+      "advanced": { "collapsible": true },
+      "order": 99,
+      "fields": [
+        { "name": "notes", "type": "textarea", "label": "Delivery notes" }
+      ]
+    }
+  ]
+}
+```

package/docs/validation/overview.md

@@ -251,7 +251,7 @@ 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` sources.
+- **`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.
 - **`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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-luna-form",
-  "version": "0.0.83",
+  "version": "0.0.85",
   "description": "A React library for building forms based on JSON",
   "main": "./dist/client/cjs/index.js",
   "module": "./dist/client/esm/index.js",
@@ -31,11 +31,11 @@
   },
   "devDependencies": {
     "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.4",
+    "@types/react-dom": "19.2.5",
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.1.1",
-    "eslint-plugin-react-refresh": "0.5.4",
-    "@luna-form/core": "0.0.83"
+    "eslint-plugin-react-refresh": "0.5.5",
+    "@luna-form/core": "0.0.85"
   },
   "license": "Apache-2.0",
   "repository": {