react-luna-form 0.0.92 → 0.0.94

package/docs/fields/custom-inputs.md

@@ -46,7 +46,7 @@ Props are applied in this order:
 <Component
   {...dataAttributes} // advanced.data, as data-* attributes
   {...commonProps} // id, name, placeholder, disabled, required, and what the field family adds
-  {...ariaAttributes} // advanced.aria, and aria-invalid, aria-errormessage
+  {...ariaAttributes} // advanced.aria, aria-labelledby, aria-invalid, aria-errormessage
   {...inputProps} // the prepared value or defaultValue
   onBlur={onBlur}
   onChange={onChange}
@@ -98,6 +98,34 @@ function PeoplePicker({ id, ...props }: React.ComponentProps<'input'>) {
 The same applies when you build on a component library: whatever primitive
 renders the focusable element is where the `id` belongs.
 
+## A group of controls takes its name from `aria-labelledby`
+
+A `<label for>` names only an element a label can name: an `input`, a `select`,
+a `textarea`, a `button`. A component drawn as several controls, such as a row
+of chips, has no one element the label belongs to, and putting the `id` on one
+of its buttons would rename that button after the field.
+
+So a field that renders a label also hands its component `aria-labelledby`,
+pointing at that label, whose `id` is the field's `name` followed by `-label`.
+Put it, with the `id`, on the element that holds the controls, and give that
+element a role that can carry a name:
+
+```tsx
+function Chips({ id, 'aria-labelledby': labelledBy, ...props }: ChipsProps) {
+  return (
+    <div aria-labelledby={labelledBy} id={id} role="group">
+      {/* one button per option */}
+    </div>
+  )
+}
+```
+
+A component that forwards its props to a single input gets it for free, and the
+input is named exactly as its `for` already named it. A field without a `label`
+or a `name` renders no label, and gets no `aria-labelledby`. An `aria.label` or
+`aria.labelledby` in `advanced` is the author's name for the field, and the form
+then sends that instead.
+
 ## Clearing a value on a select-family type
 
 If you register a custom input under a `select` variant, be aware that an
@@ -274,6 +302,8 @@ Before shipping a custom input:
 
 - Its `type` string matches `defineCustomInput` exactly, character for character
 - The `id` it receives reaches the focusable element
+- If it renders several controls, the `aria-labelledby` it receives reaches
+  the element that holds them, which has a role such as `group`
 - It forwards or calls the `onChange` and `onBlur` it receives
 - If it is a select variant, it does not rely on `''` to clear
 - If it renders `input/date`, it reads and emits `yyyy-MM-dd`, or `[from, to]`

package/docs/fields/list.md

@@ -20,6 +20,7 @@ The `advanced` property customizes structural interaction rules and layout rende
 
 - **`title`** _(string)_: Names one item of the collection. The header of the second row then reads `Contact 2` and its controls announce `Collapse Contact 2` and `Remove Contact 2`.
   It falls back to the list's `label`, and then to its `name`, so a list called `contacts` with neither captions its rows `contacts 1`. A [`preview.label`](#collapsed-previews-preview-object) replaces the caption where it resolves; this stays the fallback for the rows where it does not.
+  A row with a `preview.label` is also named after it, so its controls announce `Collapse Ana (Contact 2)` and `Remove Ana (Contact item 2)`: the name holds the text the row shows, and two rows in different lists that share a title stay apart. The name follows the label as the user edits it. A row whose label comes out empty shows the caption instead, and its name repeats it: `Collapse Contact 2 (Contact 2)`.
   Like `action`, it is copy the form declares, so it is translated through the dictionary — see [Localization](#localization).
 - **`action`** _(string)_: A custom label applied strictly to the generic "Add item" button rendering at the end of the collection (e.g. `"Add email address"`).
   A custom label has to be translated by the form; the built-in `Add item` default is already translated by the library — see [Localization](#localization).
@@ -116,6 +117,7 @@ Every piece of copy a list renders goes through the `translations` dictionary, k
 
 - `Add item`, the add-button label when no `action` is declared.
 - `Expand {label} {index}`, `Collapse {label} {index}` and `Remove {label} item {index}`, the accessible names of the item controls.
+- `Expand {name} ({label} {index})`, `Collapse {name} ({label} {index})` and `Remove {name} ({label} item {index})`, the same names for a row that has a [`preview.label`](#collapsed-previews-preview-object); `{name}` is the text that label shows.
 
 ```json
 {
@@ -176,6 +178,8 @@ The accessible names are single keys carrying `{label}` and `{index}` placeholde
 
 Left untranslated, the template fills in to the same English text it replaced.
 
+`{name}` may sit anywhere in a translation, the same as the other placeholders. A translation of a `{name}` key that leaves `{name}` out is not used: the row is named with the matching key without it, `Expand {label} {index}` and so on, translated as that key is.
+
 ---
 
 ## Complete Example Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-luna-form",
-  "version": "0.0.92",
+  "version": "0.0.94",
   "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.92",
+    "@luna-form/core": "0.0.94",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "eslint-plugin-react": "7.37.5",