@toclocoinc/lattice-grid 1.101.2 → 1.101.4

package/docs/api/form.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Form API Reference — Lattice Grid 1.101.2</title>
+<title>Form API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an
@@ -391,6 +391,7 @@
         <a class="rail__sub-link" href="#form-live-example">Values, a committed edit, a veto and density, executed</a>
         <a class="rail__sub-link" href="#form-spacing-example">Spacing and label gap, executed</a>
         <a class="rail__sub-link" href="#form-width-example">Percentage widths in a cols row, executed</a>
+        <a class="rail__sub-link" href="#form-cols-breakpoint-example">Cols breakpoint and full-width buttons, executed</a>
         <a class="rail__sub-link" href="#form-disabled-readonly-example">Disabled and read-only, executed</a>
         <a class="rail__sub-link" href="#form-label-options-example">Label position, width and hidden labels, executed</a>
         <a class="rail__sub-link" href="#form-chrome-example">Help tooltips, read-only locks, field addons and panels, executed</a>
@@ -400,6 +401,7 @@
         <a class="rail__sub-link" href="#form-bind-live-example">Binding, dirty tracking, save, revert and conflict, executed</a>
         <a class="rail__sub-link" href="#form-router-bind-live-example">Router-bound forms and a form group, executed</a>
         <a class="rail__sub-link" href="#form-wizard-live-example">A custom control, declarative rules and a wizard, executed</a>
+        <a class="rail__sub-link" href="#form-step-validation-example">Step validation, the validateSteps opt-out and the refused move, executed</a>
         <a class="rail__sub-link" href="#form-validation-example">Required, a regex, a function, modes and the validated event, executed</a>
         <a class="rail__sub-link" href="#form-enhance-live-example">A server form enhanced in place, with the htmx adapter, executed</a>
         <a class="rail__sub-link" href="#form-controls-example">Choice, toggle and date controls, executed</a>
@@ -493,7 +495,7 @@ form.getValue();                         <span class="cmt">// { name: 'Grace', a
 form.on('beforeChange', (e) =&gt; { if (e.name === 'age' &amp;&amp; e.value &gt; 120) e.preventDefault(); });
 form.setDensity('comfortable');          <span class="cmt">// control heights follow the grid's row height</span>
 form.destroy();</code></pre>
-    <p><strong>Rows, columns and blocks.</strong> A form is a tree of <code>rows</code> and <code>cols</code>, each nesting the other to any depth, plus <code>items</code> to lay controls side by side. A <code>rows</code> block stacks its children vertically and stretches them to its width; a <code>cols</code> block lays its children side by side, sharing the width equally by default (<code>flex: 1 1 0</code>, <code>min-width: 0</code> &mdash; a child&rsquo;s own <code>width</code>, <code>flex</code> or <code>css</code> still wins, and a percentage <code>width</code> is a share of the row&rsquo;s width <em>after</em> its gaps, so three <code>33.3%</code> items sit on one line) and stacking them into one column once the container drops below <code>config.colsBreakpoint</code> (default 480px, via a container query). A <code>container</code> is the default block shape (a flex box along its axis); a <code>fieldset</code> is a native <code>&lt;fieldset&gt;</code>/<code>&lt;legend&gt;</code> with its children in a body below; a <code>spacer</code> is flexible space and a <code>separator</code> a rule &mdash; or, given a <code>label</code> (a literal such as <code>'or'</code>, or a key resolved through <code>config.messages</code>), a muted label centred between two rules (&ldquo;&mdash;&mdash; or &mdash;&mdash;&rdquo;), the label also its accessible name &mdash; both plain blocks. A <code>text</code> item renders a read-only display carrying its value &mdash; a label/value pair, not an editable control &mdash; and the basic controls are <code>input</code> (subtype <code>text</code>, <code>email</code>, <code>password</code> or <code>url</code>), <code>number</code> (<code>step</code>/<code>min</code>/<code>max</code>), <code>textarea</code>, <code>checkbox</code>, <code>button</code>, <code>rating</code> (a row of icons, whole or half steps, click or arrow), <code>stage</code> (a pipeline of chevron steps), <code>chips</code> (a row of pill buttons for one or several options) and <code>combo</code> (a searchable combobox, described below).</p>
+    <p><strong>Rows, columns and blocks.</strong> A form is a tree of <code>rows</code> and <code>cols</code>, each nesting the other to any depth, plus <code>items</code> to lay controls side by side. A <code>rows</code> block stacks its children vertically and stretches them to its width; a <code>cols</code> block lays its children side by side, sharing the width equally by default (<code>flex: 1 1 0</code>, <code>min-width: 0</code> &mdash; a child&rsquo;s own <code>width</code>, <code>flex</code> or <code>css</code> still wins, and a percentage <code>width</code> is a share of the row&rsquo;s width <em>after</em> its gaps, so three <code>33.3%</code> items sit on one line) and stacking them into one column once the container drops below <code>config.colsBreakpoint</code> (default 480px, via a container query &mdash; <code>0</code> or <code>false</code> turns stacking off, so the row never stacks at any width). A <code>container</code> is the default block shape (a flex box along its axis); a <code>fieldset</code> is a native <code>&lt;fieldset&gt;</code>/<code>&lt;legend&gt;</code> with its children in a body below; a <code>spacer</code> is flexible space and a <code>separator</code> a rule &mdash; or, given a <code>label</code> (a literal such as <code>'or'</code>, or a key resolved through <code>config.messages</code>), a muted label centred between two rules (&ldquo;&mdash;&mdash; or &mdash;&mdash;&rdquo;), the label also its accessible name &mdash; both plain blocks. A <code>text</code> item renders a read-only display carrying its value &mdash; a label/value pair, not an editable control &mdash; and the basic controls are <code>input</code> (subtype <code>text</code>, <code>email</code>, <code>password</code> or <code>url</code>), <code>number</code> (<code>step</code>/<code>min</code>/<code>max</code>), <code>textarea</code>, <code>checkbox</code>, <code>button</code>, <code>rating</code> (a row of icons, whole or half steps, click or arrow), <code>stage</code> (a pipeline of chevron steps), <code>chips</code> (a row of pill buttons for one or several options) and <code>combo</code> (a searchable combobox, described below).</p>
     <p><strong>One item, one handle.</strong> Every item is a wrapper holding an optional <code>&lt;label&gt;</code> (associated to its control by <code>for</code>/<code>id</code>), the control, and an optional help line. Per item: <code>name</code>, <code>label</code>, <code>labelPosition</code> (<code>top</code>/<code>left</code>), <code>labelWidth</code>, <code>width</code>, <code>placeholder</code>, <code>helpMessage</code>, <code>hidden</code>, <code>disabled</code>, <code>readOnly</code> and <code>value</code>. <code>getItem(name)</code> returns the handle &mdash; <code>{ el, name, getValue, setValue, show, hide, enable, disable, focus, blur, isVisible }</code> &mdash; or <code>undefined</code> for an unknown name, and <code>forEach(fn)</code> hands every handle to <code>fn</code> in document order. <code>setValue(values)</code> writes values silently by name (unknown keys are ignored), <code>getValue()</code> snapshots every named value-holding item as <code>{ name: value }</code> (a button holds no value and is not included), and <code>clear()</code> resets each user-editable item to its empty value &mdash; <code>''</code> for text, <code>null</code> for a number, a stage or a single <code>chips</code>, <code>[]</code> for a multi <code>chips</code>, <code>false</code> for a checkbox, <code>0</code> for a rating &mdash; without firing an event.</p>
     <p><strong>Events.</strong> A field fires <code>input</code> as the user types (the value is live, not yet committed) and <code>change</code> once the edit commits; a checkbox fires <code>change</code> on toggle; a button fires <code>click</code>. Every interactive item fires <code>focus</code> and <code>blur</code>, and an <code>otp</code> fires <code>complete</code> once every box is filled. A <code>change</code> is gated by a cancellable <code>beforeChange</code> &mdash; a handler calls <code>event.preventDefault(reason?)</code> or returns <code>false</code> (or a Promise of either) to refuse the commit, which then reverts the control to its last committed value &mdash; and the emitted events are subscribed with <code>form.on(name, fn)</code> (or <code>'*'</code> for every past-tense event) and detached with <code>form.off(name, fn)</code>.</p>
     <p><strong>Validation.</strong> An item declares <code>required</code> (an empty value fails), a <code>validation</code> rule &mdash; a built-in name (<code>email</code>, <code>number</code>, <code>integer</code>, <code>url</code>), a whole-value RegExp, or a function <code>(value, item) =&gt; boolean | string | void</code> that returns <code>true</code>/<code>undefined</code> for pass, <code>false</code> for a fail, or a string that <em>is</em> the failure message &mdash; and the message options <code>errorMessage</code>, <code>successMessage</code> and <code>preMessage</code>. <code>form.validate()</code> checks every rule-bearing item and returns <code>true</code>/<code>false</code>, marking each invalid item with <code>aria-invalid</code> and an associated message (and each pass with its <code>successMessage</code>); <code>item.validate()</code> checks one item. A <code>validationMode</code> of <code>change</code> re-checks an item once its edit commits, <code>blur</code> re-checks it as it loses focus, and <code>submit</code> (the default) checks it only on <code>validate()</code>. The default rule messages live in the module's catalogue &mdash; overridable through <code>config.messages</code> &mdash; and a <code>validated</code> event reports every failure as <code>{ name, rule, message }</code>. The control registry exposes a per-control <code>validate(el, item, value)</code> hook that later controls (file, combo, custom) plug into.</p>
@@ -503,10 +505,10 @@ form.destroy();</code></pre>
     <p><strong>Data binding.</strong> <code>config.bind</code> binds the form to a record instead of a static config. <code>bind: { grid, rowKey }</code> binds a grid row: when no layout is declared, one item per column is generated from the grid's own columns &mdash; their titles, types and editors &mdash; so a boolean column becomes a <code>checkbox</code> and a number column a <code>number</code>; the form follows the grid's density by default; <code>save()</code> writes the dirty items once through the grid's edit path (permissions, read-only, parse, validation and the beforeEdit gate honoured); and <code>revert()</code> restores the bound values. External edits to the row update a clean item in place and leave a dirty one alone, flagging it with <code>isConflicted()</code>. <code>bind: { router, route, key, onSave? }</code> follows a data-router record with the same update-unless-dirty rule: the form reads the record eagerly through <code>router.get(route, key)</code> &mdash; so a form created <em>after</em> the ingest still fills at once, whatever the order &mdash; then subscribes to the route's keyed diffs, and <code>destroy()</code> unsubscribes. <code>save()</code> writes the dirty items back through <code>router.apply</code>, then calls <code>bind.onSave(changes, record)</code> when the host gave one (may be async; a rejection reverts the router record and leaves the form dirty). A form <strong>group</strong> takes the same <code>bind</code> once: every member fills with its own fields off the record, and <code>group.save()</code> writes <em>one</em> router update with all the members' dirty fields, calling <code>onSave</code> once. A plain object of values initialises the form and is written back by <code>save()</code>. <code>isDirty(name?)</code> reports an unsaved user edit on one item or the whole form, and editing is the only thing that marks an item dirty &mdash; <code>setValue()</code>, <code>revert()</code> and bound-record updates are silent. The binding is duck-typed against the grid's public API, so the module still imports no grid and no core source.</p>
     <p><strong>Custom controls.</strong> <code>registerControl(type, definition)</code> makes a control type a first-class item: the definition's <code>create(el, item, api)</code> builds the control's DOM into <code>el</code>, <code>getValue(el)</code>/<code>setValue(el, value)</code> round-trip the value through <code>getValue()</code>/<code>setValue()</code>, and an optional <code>validate(value, item, el)</code> refuses a bad commit (return <code>true</code> to accept, <code>false</code> or a message to refuse, a Promise is awaited). The registered control gets the same wrapper, label, item API, events and density as a built-in, its <code>api.onChange()</code>/<code>api.onInput()</code> commit and report through the same path a native edit takes, and a later registration for the same type replaces the earlier one.</p>
     <p><strong>Declarative rules.</strong> An item's <code>visibleWhen</code>, <code>readOnlyWhen</code> or <code>requiredWhen</code> is a rule re-evaluated on every committed change: a constant, a function of the whole <code>{ name: value }</code> snapshot, or a condition on one named item's value with <code>equals</code>, <code>in</code>, <code>empty</code> or <code>fn</code>. A <code>visibleWhen</code> that is false hides the item, a <code>readOnlyWhen</code> that is true makes its control read-only, and a <code>requiredWhen</code> that is true marks it required &mdash; its commit path then refuses an empty value. A rule composes on the item's own <code>hidden</code>/<code>readOnly</code> baseline, so it never fights the item API's <code>hide()</code>/<code>show()</code>/<code>enable()</code>/<code>disable()</code>.</p>
-    <p><strong>Wizards.</strong> A <code>steps</code> array turns the form into a wizard: each <code>{ id, label, rows }</code> step is one body, only the active one visible, under a step indicator whose <code>stepOrientation</code> is <code>horizontal</code> (default) or <code>vertical</code>. <code>form.next()</code> validates the current step's items before advancing, <code>form.back()</code> goes back without validating, and <code>form.goToStep(index)</code> moves to a step validating the ones passed over on the way forward; the indicator marks each step pending, active, complete or in error, and never disagrees with the form. On the last step <code>next()</code> reads "Finish" and validates in place.</p>
+    <p><strong>Wizards.</strong> A <code>steps</code> array turns the form into a wizard: each <code>{ id, label, rows }</code> step is one body, only the active one visible, under a step indicator whose <code>stepOrientation</code> is <code>horizontal</code> (default) or <code>vertical</code>. <code>form.next()</code>, <code>form.goToStep(index)</code> to a later step, and a click on a later indicator step all validate the current step's items first &mdash; exactly as <code>form.validate()</code> does, so a refused move shows the same errors, fires the <code>validated</code> event and moves focus to the first invalid item, resolving <code>false</code> and staying put. <code>form.back()</code>, <code>goToStep(index)</code> to an earlier step and an earlier indicator step go back without validating; the indicator marks each step pending, active, complete or in error, and never disagrees with the form. On the last step <code>next()</code> reads "Finish" and validates in place, resolving <code>false</code> while it is invalid. Set <code>validateSteps: false</code> to opt out &mdash; the integrator then runs <code>validate()</code> itself, and forward navigation is unchecked.</p>
     <p><strong>Files and rich text.</strong> A <code>file</code> item is an uploader field: drop, paste or pick, with <code>accept</code> (extensions or MIME patterns), <code>maxSize</code> and <code>maxFiles</code> enforced at admission, and a host <code>upload(file, { onProgress, signal })</code> callback that does the actual upload. The file list shows per-file progress and status with retry and remove, and the value is the accepted file entries &mdash; a rejected file stays visible with a message but never enters the value. A <code>richtext</code> item is a sanitised HTML editor: toolbar presets (<code>basic</code>/<code>html</code>/<code>rich</code> or an item-name array) over bold, italic, underline, strikethrough, colour, case, paragraph styles, lists, alignment, links, images, source view and undo/redo, with keyboard shortcuts and paste cleanup. Its whitelist sanitiser is the security boundary, shared with the grid's rich-text editor as one implementation: scripts, event handlers, <code>srcdoc</code>, <code>id</code>/<code>name</code> clobbering and <code>javascript:</code>/<code>vbscript:</code>/<code>data:</code> URLs never survive pasting, dropping or <code>setValue</code>, and every <code>_blank</code> link carries <code>rel="noopener noreferrer"</code>. Both honour density, theme tokens, <code>readOnly</code>/<code>disabled</code> and the item API, and clear to <code>[]</code> (file) or <code>''</code> (richtext). The same rich-text editor is available as a grid pop-up editor for long text with <code>edit: { editor: 'richtext' }</code>.</p>
     <p><strong>Passwords and one-time codes.</strong> A <code>password</code> <code>input</code> carries a reveal button inside the field: an eye that toggles the input between the native <code>password</code> and <code>text</code> types, keyboard-operable like any button, carrying <code>aria-pressed</code> and a name from the catalogue (&ldquo;Show password&rdquo;/&ldquo;Hide password&rdquo;). It returns to hidden when focus leaves the field and when the form validates or submits, and <code>reveal: false</code> renders a bare password input with no button &mdash; the value, events and validation are unchanged. An <code>otp</code> item is a one-time-code entry of single-character boxes: <code>length</code> (default 6) sets how many, <code>mode</code> (<code>numeric</code> default or <code>alphanumeric</code>) drives each box&rsquo;s <code>inputmode</code>/<code>pattern</code> and the characters it admits, the first box advertises <code>autocomplete="one-time-code"</code>, and <code>mask</code> hides each glyph behind the password disc. Typing advances, Backspace steps back and clears, the arrow keys move, and pasting fills every box (spaces and dashes stripped). <code>getValue()</code> returns the joined string, <code>setValue()</code> fills the boxes, and a <code>complete</code> event fires once every box is filled. Screen readers hear one labelled group, each box announced as &ldquo;Digit <em>n</em> of <em>length</em>&rdquo;.</p>
-    <p><strong>Buttons and button rows.</strong> A <code>button</code> item is an acting control, not a value: it takes an <code>icon</code> (a name from the grid&rsquo;s icon set, an image URL or data: URI, or an element) with <code>iconPosition</code> (<code>start</code> default / <code>end</code>), sitting a density-scaled gap (about 0.5em) from the text and vertically centred with it, a <code>variant</code> (<code>primary</code>, <code>secondary</code> default, <code>tonal</code>, <code>outline</code>, <code>text</code> or <code>danger</code> &mdash; theme-token colours, light and dark), <code>fullWidth</code> to span the form, a <code>size</code> (<code>sm</code>/<code>md</code>/<code>lg</code>), a <code>textTransform</code> (<code>none</code> default / <code>uppercase</code>) and a <code>buttonType</code> (<code>button</code>, <code>submit</code> or <code>reset</code>). A <code>submit</code> button runs <code>form.validate()</code> first and only then fires a <code>submit</code> event on the form&rsquo;s element with the values in <code>event.detail.values</code> when valid; a <code>reset</code> button calls <code>form.clear()</code>. <code>loading: true</code> (or <code>item.setLoading(bool)</code>) swaps the icon for a spinner, keeps the width, sets <code>aria-busy</code> and makes the button ignore clicks; a <code>href</code> turns it into a link styled as a button. An icon with no label is icon-only: it requires <code>ariaLabel</code> and renders square. A <code>{ type: 'buttons', align, items }</code> row lays a group of buttons out along the width with <code>align</code> <code>start</code> (default), <code>end</code>, <code>center</code>, <code>stretch</code> or <code>space-between</code>, and each child takes the same options as a <code>button</code> item.</p>
+    <p><strong>Buttons and button rows.</strong> A <code>button</code> item is an acting control, not a value: it takes an <code>icon</code> (a name from the grid&rsquo;s icon set, an image URL or data: URI, or an element) with <code>iconPosition</code> (<code>start</code> default / <code>end</code>), sitting a density-scaled gap (about 0.5em) from the text and vertically centred with it, a <code>variant</code> (<code>primary</code>, <code>secondary</code> default, <code>tonal</code>, <code>outline</code>, <code>text</code> or <code>danger</code> &mdash; theme-token colours, light and dark), <code>fullWidth</code> to span the form (inside a <code>cols</code> row it fills its own column, so two full-width buttons keep sharing the row), a <code>size</code> (<code>sm</code>/<code>md</code>/<code>lg</code>), a <code>textTransform</code> (<code>none</code> default / <code>uppercase</code>) and a <code>buttonType</code> (<code>button</code>, <code>submit</code> or <code>reset</code>). A <code>submit</code> button runs <code>form.validate()</code> first and only then fires a <code>submit</code> event on the form&rsquo;s element with the values in <code>event.detail.values</code> when valid; a <code>reset</code> button calls <code>form.clear()</code>. <code>loading: true</code> (or <code>item.setLoading(bool)</code>) swaps the icon for a spinner, keeps the width, sets <code>aria-busy</code> and makes the button ignore clicks; a <code>href</code> turns it into a link styled as a button. An icon with no label is icon-only: it requires <code>ariaLabel</code> and renders square. A <code>{ type: 'buttons', align, items }</code> row lays a group of buttons out along the width with <code>align</code> <code>start</code> (default), <code>end</code>, <code>center</code>, <code>stretch</code> or <code>space-between</code>, and each child takes the same options as a <code>button</code> item.</p>
     <p><strong>A button is an action item, and its states are named tokens.</strong> Because a button acts rather than holds a value, the view draws no field <code>&lt;label&gt;</code>, required asterisk, help line or hint line for it &mdash; its <code>label</code> is its own text, shown once &mdash; and in a <code>labelPosition: 'left'</code> form it lines up with the fields&rsquo; input column (unless <code>fullWidth</code> spans the row). Every variant defines the same state matrix in light and dark, each state&rsquo;s colours read from an overridable <code>--lattice-button-&lt;variant&gt;-&lt;state&gt;</code> token: <strong>rest</strong>; <strong>hover</strong> (one step toward the foreground &mdash; a shade in light, a tint in dark); <strong>active</strong> (a deeper step); <strong>focus-visible</strong> (a 2px accent ring with a 2px offset, never removed); <strong>disabled</strong> (muted text, border and fill with text at or above 3:1 against its fill, <code>cursor: not-allowed</code>, no hover or pressed change, <code>aria-disabled</code>, and still in the tab order only when <code>focusableWhenDisabled: true</code> keeps it focusable instead of natively disabled); <strong>loading</strong> (the spinner from <code>loading</code>); and <strong>toggled</strong> (a distinct pressed look). <code>toggle: true</code> makes the button two-state: it flips <code>aria-pressed</code> and fires <code>change</code> with the new boolean (starting pressed when <code>value</code> is <code>true</code>). The swatches below show each variant&rsquo;s fill per state, light and dark.</p>
     <div class="table-wrap">
       <table>
@@ -525,7 +527,8 @@ form.destroy();</code></pre>
       <table>
         <thead><tr><th>Member</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="sig">createForm(el, config?)</td><td class="desc">Create a form. <code>config</code> is <code>{ rows | cols, density, spacing, labelGap, labelPosition, labelWidth, requiredHint, colsBreakpoint, bind, css, messages, steps, stepOrientation }</code>; <code>rows</code> stacks the top-level blocks vertically, <code>cols</code> lays them left-to-right sharing the width equally (used when <code>rows</code> is absent), <code>spacing</code> is the vertical gap between items (a px number or a CSS length, defaulting to the density's gap) and <code>labelGap</code> the gap between an item's label and its field (defaulting to half the density's space), <code>labelPosition</code> (<code>top</code> default / <code>left</code> / <code>hidden</code>) and <code>labelWidth</code> are the defaults every item inherits (an item&rsquo;s own value wins), <code>requiredHint</code> is the placeholder marker a required field with no visible label shows (<code>true</code> appends <code>" *"</code>, a string resolves through the catalogue, <code>false</code> shows nothing), <code>colsBreakpoint</code> is the container width below which a <code>cols</code> container stacks into one column (default 480px), <code>bind</code> binds the form to a record (<code>{ grid, rowKey }</code>, <code>{ router, route, key, onSave? }</code> or a plain values object), <code>messages</code> supplies a <code>t(key, params)</code> catalogue for the separator's accessible label and the validation defaults, and a <code>steps</code> array turns the form into a wizard with a <code>horizontal</code> (default) or <code>vertical</code> <code>stepOrientation</code>. Returns <code>{ el, config, getItem, getValue, setValue, clear, validate, forEach, on, off, setDensity, setSpacing, setReadOnly, setDisabled, isDirty, isConflicted, save, revert, steps, activeStep, next, back, goToStep, destroy }</code>.</td></tr>
+          <tr><td class="sig">createForm(el, config?)</td><td class="desc">Create a form. <code>config</code> is <code>{ rows | cols, density, spacing, labelGap, labelPosition, labelWidth, requiredHint, colsBreakpoint, bind, css, messages, steps, stepOrientation }</code>; <code>rows</code> stacks the top-level blocks vertically, <code>cols</code> lays them left-to-right sharing the width equally (used when <code>rows</code> is absent), <code>spacing</code> is the vertical gap between items (a px number or a CSS length, defaulting to the density's gap) and <code>labelGap</code> the gap between an item's label and its field (defaulting to half the density's space), <code>labelPosition</code> (<code>top</code> default / <code>left</code> / <code>hidden</code>) and <code>labelWidth</code> are the defaults every item inherits (an item&rsquo;s own value wins), <code>requiredHint</code> is the placeholder marker a required field with no visible label shows (<code>true</code> appends <code>" *"</code>, a string resolves through the catalogue, <code>false</code> shows nothing), <code>colsBreakpoint</code> is the container width below which a <code>cols</code> container stacks into one column (default 480px; <code>0</code> or <code>false</code> never stacks), <code>bind</code> binds the form to a record (<code>{ grid, rowKey }</code>, <code>{ router, route, key, onSave? }</code> or a plain values object), <code>messages</code> supplies a <code>t(key, params)</code> catalogue for the separator's accessible label and the validation defaults, and a <code>steps</code> array turns the form into a wizard with a <code>horizontal</code> (default) or <code>vertical</code> <code>stepOrientation</code>. Returns <code>{ el, config, getItem, getValue, setValue, clear, validate, forEach, on, off, setDensity, setSpacing, setReadOnly, setDisabled, isDirty, isConflicted, save, revert, steps, activeStep, next, back, goToStep, destroy }</code>.</td></tr>
+          <tr><td class="sig">createForm(el, config?)</td><td class="desc">Create a form. <code>config</code> is <code>{ rows | cols, density, spacing, labelGap, labelPosition, labelWidth, requiredHint, colsBreakpoint, bind, css, messages, steps, stepOrientation, validateSteps }</code>; <code>rows</code> stacks the top-level blocks vertically, <code>cols</code> lays them left-to-right sharing the width equally (used when <code>rows</code> is absent), <code>spacing</code> is the vertical gap between items (a px number or a CSS length, defaulting to the density's gap) and <code>labelGap</code> the gap between an item's label and its field (defaulting to half the density's space), <code>labelPosition</code> (<code>top</code> default / <code>left</code> / <code>hidden</code>) and <code>labelWidth</code> are the defaults every item inherits (an item&rsquo;s own value wins), <code>requiredHint</code> is the placeholder marker a required field with no visible label shows (<code>true</code> appends <code>" *"</code>, a string resolves through the catalogue, <code>false</code> shows nothing), <code>colsBreakpoint</code> is the container width below which a <code>cols</code> container stacks into one column (default 480px), <code>bind</code> binds the form to a record (<code>{ grid, rowKey }</code>, <code>{ router, route, key, onSave? }</code> or a plain values object), <code>messages</code> supplies a <code>t(key, params)</code> catalogue for the separator's accessible label and the validation defaults, a <code>steps</code> array turns the form into a wizard with a <code>horizontal</code> (default) or <code>vertical</code> <code>stepOrientation</code>, and <code>validateSteps: false</code> opts out of validating the current step on a forward move (the integrator runs <code>validate()</code> itself). Returns <code>{ el, config, getItem, getValue, setValue, clear, validate, forEach, on, off, setDensity, setSpacing, setReadOnly, setDisabled, isDirty, isConflicted, save, revert, steps, activeStep, next, back, goToStep, destroy }</code>.</td></tr>
           <tr><td class="sig">registerControl(type, definition)</td><td class="desc">Register a custom control type as a first-class item. <code>definition</code> is <code>{ create(el, item, api), getValue(el), setValue(el, value), validate?(value, item, el), destroy?(el) }</code>; the control gets the same wrapper, label, item API, events and density as a built-in. A later registration for the same type replaces the earlier one.</td></tr>
           <tr><td class="sig">item</td><td class="desc">Each item: <code>type</code> (a built-in <code>input</code>/<code>number</code>/<code>textarea</code>/<code>checkbox</code>/<code>button</code>/<code>text</code>/<code>combo</code>/<code>rating</code>/<code>stage</code> or a registered custom type), <code>name</code>, <code>label</code>, <code>labelPosition</code> (<code>top</code>/<code>left</code>), <code>labelWidth</code>, <code>width</code>, <code>placeholder</code>, <code>helpMessage</code>, <code>hidden</code>, <code>disabled</code>, <code>readOnly</code>, <code>value</code>, <code>required</code>, <code>validation</code>, <code>errorMessage</code>, <code>successMessage</code>, <code>preMessage</code>, <code>validationMode</code>, <code>css</code>, and the rules <code>visibleWhen</code>, <code>readOnlyWhen</code>, <code>requiredWhen</code>. <code>input</code> takes <code>subtype</code> (a <code>password</code> subtype also <code>reveal</code>); <code>number</code> takes <code>step</code>/<code>min</code>/<code>max</code>. <code>rating</code> takes <code>max</code>, <code>allowHalf</code>, <code>allowClear</code>, <code>icon</code> or <code>icons</code> (<code>{ filled, empty }</code>), <code>labels</code>, <code>showValue</code> and <code>size</code> (<code>sm</code>/<code>md</code>/<code>lg</code>); <code>stage</code> takes <code>stages</code>, <code>current</code>, <code>completed</code>, <code>clickable</code> and <code>showIcons</code>; <code>chips</code> takes <code>options</code> (<code>{ value, label, icon?, disabled? }</code>), <code>multiple</code>, <code>allowEmpty</code>, <code>wrap</code> and <code>max</code>; <code>otp</code> takes <code>length</code>, <code>mode</code> (<code>numeric</code>/<code>alphanumeric</code>) and <code>mask</code>. <code>select</code>, <code>radiogroup</code> and <code>checkboxgroup</code> take <code>options</code>; a <code>radiogroup</code>/<code>checkboxgroup</code> also takes <code>orientation</code> (<code>vertical</code>/<code>horizontal</code>) or <code>columns</code> (an n-column grid read across then down). <code>button</code> takes <code>icon</code> (a name, URL/data: URI or element), <code>iconPosition</code> (<code>start</code>/<code>end</code>), <code>variant</code> (<code>primary</code>/<code>secondary</code>/<code>tonal</code>/<code>outline</code>/<code>text</code>/<code>danger</code>), <code>fullWidth</code>, <code>size</code> (<code>sm</code>/<code>md</code>/<code>lg</code>), <code>textTransform</code> (<code>none</code>/<code>uppercase</code>), <code>buttonType</code> (<code>button</code>/<code>submit</code>/<code>reset</code>), <code>loading</code>, <code>href</code>, <code>ariaLabel</code> (required for an icon-only button), <code>toggle</code> (a two-state button that flips <code>aria-pressed</code> and fires <code>change</code> with the new boolean) and <code>focusableWhenDisabled</code> (keep a disabled button focusable and in the tab order, reading <code>aria-disabled</code> instead of being natively disabled); a <code>{ type: 'buttons', align, items }</code> row lays buttons out by <code>align</code> (<code>start</code>/<code>end</code>/<code>center</code>/<code>stretch</code>/<code>space-between</code>), each child taking the same options.</td></tr>
           <tr><td class="sig">getItem(name)</td><td class="desc">The item handle <code>{ el, name, getValue, setValue, show, hide, enable, disable, focus, blur, isVisible, validate, setLoading }</code> &mdash; <code>el</code> is the item's wrapper element. <code>undefined</code> for an unknown name.</td></tr>
@@ -544,9 +547,9 @@ form.destroy();</code></pre>
           <tr><td class="sig">isConflicted(name?)</td><td class="desc">Whether an item (or the whole form) is in conflict: the user has an unsaved edit, and an external change to the bound record arrived for the same item, which the form therefore did not overwrite.</td></tr>
           <tr><td class="sig">save()</td><td class="desc">Save the dirty items. For a grid binding the writes go through the grid's own edit path in one call (permissions, read-only, parse, validation and the beforeEdit gate honoured); for a router binding they are applied back through <code>router.apply</code> and, when <code>bind.onSave</code> was given, handed to it (may be async &mdash; a rejection reverts the router record and keeps the items dirty); for a values binding they are written back into the bound object. Returns <code>true</code> when saved (or nothing to save), or a <code>Promise&lt;boolean&gt;</code> when the write is asynchronous. An unbound form returns <code>false</code>.</td></tr>
           <tr><td class="sig">revert()</td><td class="desc">Restore every dirty item to its bound/committed value and clear the dirty and conflict flags.</td></tr>
-          <tr><td class="sig">next()</td><td class="desc">Advance a wizard one step, validating the current step's items first. Resolves <code>true</code> when the wizard moved (or the final step validated), <code>false</code> when the current step is invalid or there is no next step. Not a wizard: resolves <code>false</code>.</td></tr>
+          <tr><td class="sig">next()</td><td class="desc">Advance a wizard one step, validating the current step's items first &mdash; as <code>form.validate()</code> does, so a refused move shows the same errors, fires <code>validated</code> and focuses the first invalid item. Resolves <code>true</code> when the wizard moved (or the final step validated), <code>false</code> while the current step is invalid or there is no next step; <code>validateSteps: false</code> skips the validation. Not a wizard: resolves <code>false</code>.</td></tr>
           <tr><td class="sig">back()</td><td class="desc">Go back one step &mdash; always allowed, never validated. Resolves <code>false</code> when already on the first step.</td></tr>
-          <tr><td class="sig">goToStep(index)</td><td class="desc">Move a wizard to a step by index. Forward moves validate the steps passed over (the first invalid one stops the move and is marked in error); backward moves are always allowed. Resolves <code>false</code> when an intermediate step is invalid or the index is out of range.</td></tr>
+          <tr><td class="sig">goToStep(index)</td><td class="desc">Move a wizard to a step by index. Forward moves validate the steps passed over (the first invalid one is focused, marked in error and stops the move); backward moves are always allowed, and <code>validateSteps: false</code> skips the forward validation. Resolves <code>false</code> when an intermediate step is invalid or the index is out of range.</td></tr>
           <tr><td class="sig">destroy()</td><td class="desc">Empty the element, remove only what the module added (class, density attribute, own inline style), and drop every item record, listener and handler. The host still owns the element.</td></tr>
         </tbody>
       </table>
@@ -682,6 +685,46 @@ form.destroy();
 form.destroy();
 <span class="kw">return</span> widths;</code></pre>
 
+    <h3 id="form-cols-breakpoint-example">Cols breakpoint and full-width buttons, executed</h3>
+    <p class="section-note"><code>colsBreakpoint: 0</code> (or <code>false</code>) turns stacking off so a <code>cols</code> row never stacks, and a <code>fullWidth</code> button fills its own column while the columns keep sharing the row &mdash; with the real-Chrome geometry asserted in <code>test/form-cols-breakpoint-2292-browser.test.js</code>.</p>
+    <pre data-run="js" data-expect="lat-cols-never|true|true|lat-cols-never|lat-cols-bp-200" data-covers="export:createForm config:FormConfig.cols config:FormConfig.colsBreakpoint config:FormItemConfig.fullWidth"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
+<span class="kw">const</span> { createForm } = <span class="kw">await</span> import('../packages/modules/form/index.js');
+
+<span class="kw">const</span> { root } = createTestDom();
+<span class="kw">const</span> form = createForm(root, {
+  colsBreakpoint: <span class="kw">false</span>,                   <span class="cmt">// false (or 0): never stack</span>
+  cols: [
+    { type: <span class="str">'button'</span>, name: <span class="str">'ok'</span>, label: <span class="str">'OK'</span>, fullWidth: <span class="kw">true</span> },
+    { type: <span class="str">'button'</span>, name: <span class="str">'cancel'</span>, label: <span class="str">'Cancel'</span>, fullWidth: <span class="kw">true</span> },
+  ],
+});
+<span class="kw">const</span> neverFalse = root.style.getPropertyValue('--lattice-cols-container');  <span class="cmt">// 'lat-cols-never'</span>
+<span class="kw">const</span> okFull = form.getItem('ok').el.querySelector('button').getAttribute('data-full');         <span class="cmt">// 'true'</span>
+<span class="kw">const</span> cancelFull = form.getItem('cancel').el.querySelector('button').getAttribute('data-full'); <span class="cmt">// 'true'</span>
+form.destroy();
+
+<span class="kw">const</span> zero = createForm(root, {
+  colsBreakpoint: 0,                          <span class="cmt">// 0 means never stack too</span>
+  cols: [
+    { type: <span class="str">'input'</span>, name: <span class="str">'a'</span>, label: <span class="str">'A'</span> },
+    { type: <span class="str">'input'</span>, name: <span class="str">'b'</span>, label: <span class="str">'B'</span> },
+  ],
+});
+<span class="kw">const</span> neverZero = root.style.getPropertyValue('--lattice-cols-container');   <span class="cmt">// 'lat-cols-never'</span>
+zero.destroy();
+
+<span class="kw">const</span> positive = createForm(root, {
+  colsBreakpoint: 200,                        <span class="cmt">// a positive number keeps the old behaviour</span>
+  cols: [
+    { type: <span class="str">'input'</span>, name: <span class="str">'c'</span>, label: <span class="str">'C'</span> },
+    { type: <span class="str">'input'</span>, name: <span class="str">'d'</span>, label: <span class="str">'D'</span> },
+  ],
+});
+<span class="kw">const</span> positiveBp = root.style.getPropertyValue('--lattice-cols-container');   <span class="cmt">// 'lat-cols-bp-200'</span>
+positive.destroy();
+
+<span class="kw">return</span> [neverFalse, okFull, cancelFull, neverZero, positiveBp].join('|');</code></pre>
+
     <h3 id="form-disabled-readonly-example">Disabled and read-only, executed</h3>
     <p class="section-note">The two states are one contract across every control, set per item or form-wide &mdash; with the real Chrome focus, cursor, token and value assertions over all 16 control types in <code>test/form-disabled-readonly-2198-browser.test.js</code>.</p>
     <pre data-run="js" data-expect="true|true|true|Ada|false|true|true|true|true|false" data-covers="export:createForm method:form.setReadOnly method:form.setDisabled config:FormItemConfig.disabled config:FormItemConfig.readOnly"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
@@ -896,7 +939,7 @@ form.destroy();
 return [variant, full, iconPosition, googleImg, caps, iconOnly, helpLabel, linkTag, blocked, submitted, submittedValues, cleared, busy, spinner, rowAlign, rowButtons, pinStart, pinAfter, toggleValue, ghostDisabled, ghostAriaDisabled].join('|');</code></pre>
 
     <h3 id="combo">The combo control</h3>
-    <p>The same module also ships <code>createCombo(el, config)</code>, the standalone form of the form's <code>type: 'combo'</code> item: a searchable combobox with dynamic server values, dependent lists, multi-select and multi-line options. It is a <code>load</code>-driven paging list &mdash; the search is debounced, a newer load aborts the older one, pages load on scroll and are cached, and <code>reload()</code> drops the cache &mdash; or a static <code>options</code> list when there is no server. Options are a bare value or <code>{ value, label, description, icon, avatar, color, dot, disabled }</code>; a <code>description</code> adds a second line, an <code>icon</code> is a glyph name from the grid's icon set drawn as the real SVG (or a DOM node) and an <code>avatar</code> is an image URL or initials, each drawn round on the left of the list rows, the multi-select chips and the single-select shown value, in a virtualised list of variable-height rows; <code>color</code> tints the initials avatar and the icon (an SVG takes it as its fill or stroke, an element as its colour), and <code>dot</code> draws a small filled circle in that colour instead of any icon or avatar, with no letter; a <code>disabled</code> option shows but refuses a click. A <code>multiple</code> combo keeps its value as an array in selection order and draws chips that wrap, cap at <code>maxHeight</code> and scroll, with a <code>+N</code> summary and a <code>selectAll</code> action over the loaded set. <code>chipPlacement</code> moves those chips out of the control &mdash; <code>'above'</code> or <code>'below'</code> puts them in their own wrapping row beside the field, so the input stays a single clean search line and the list still opens directly under it. <code>resolveLabels(values)</code> supplies labels for a preselected value outside the first page, <code>newOptions</code> turns the box into free entry (with a create row while typing), <code>optionTemplate</code> replaces the row renderer and <code>selectedTemplate</code> the chips and shown value &mdash; either may return a DOM node or an HTML string, which is sanitised before insertion &mdash; and a form item's <code>dependsOn</code> clears and reloads it when a named parent item changes.</p>
+    <p>The same module also ships <code>createCombo(el, config)</code>, the standalone form of the form's <code>type: 'combo'</code> item: a searchable combobox with dynamic server values, dependent lists, multi-select and multi-line options. It is a <code>load</code>-driven paging list &mdash; the search is debounced, a newer load aborts the older one, pages load on scroll and are cached, and <code>reload()</code> drops the cache &mdash; or a static <code>options</code> list when there is no server. Options are a bare value or <code>{ value, label, description, icon, avatar, color, dot, disabled }</code>; a <code>description</code> adds a second line, an <code>icon</code> is a glyph name from the grid's icon set drawn as the real SVG (or a DOM node) and an <code>avatar</code> is an image URL or initials, each drawn round on the left of the list rows, the multi-select chips and the single-select shown value, in a virtualised list of variable-height rows; <code>color</code> tints the initials avatar and the icon (an SVG takes it as its fill or stroke, an element as its colour), and <code>dot</code> draws a small filled circle in that colour instead of any icon or avatar, with no letter; a <code>disabled</code> option shows but refuses a click. A <code>multiple</code> combo keeps its value as an array in selection order and draws chips that wrap, cap at <code>maxHeight</code> and scroll, with a <code>+N</code> summary and a <code>selectAll</code> action over the loaded set. <code>chipPlacement</code> moves those chips out of the control &mdash; <code>'above'</code> or <code>'below'</code> puts them in their own wrapping row beside the field, so the input stays a single clean search line and the list still opens directly under it. <code>resolveLabels(values)</code> supplies labels for a preselected value outside the first page, <code>newOptions</code> turns the box into free entry (with a create row while typing), <code>optionTemplate</code> replaces the row renderer and <code>selectedTemplate</code> the chips and shown value &mdash; either may return a DOM node or an HTML string, which is sanitised before insertion &mdash; and a form item's <code>dependsOn</code> clears and reloads it when a named parent item changes. The list opens in the same shared top-level layer the select and the date picker use, positioned against the field so a clipping or fixed-height ancestor never cuts it off (BACKLOG-0002291).</p>
     <div class="table-wrap">
       <table>
         <thead><tr><th>Member</th><th>Description</th></tr></thead>
@@ -945,8 +988,9 @@ const sized = createCombo(sizedHost, {
   options: [{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }],
   optionTemplate: (opt) =&gt; 'T:' + opt.label,
 });
+const sizedPopup = sized.root.querySelector('.lat-combo__popup');   <span class="cmt">// captured before open: the popup moves into the shared layer host while open (BACKLOG-0002291)</span>
 sized.open();
-const renderedRow = Array.from(sized.root.querySelectorAll('.lat-combo__option')).find((r) =&gt; r.textContent === 'T:Alpha');
+const renderedRow = Array.from(sizedPopup.querySelectorAll('.lat-combo__option')).find((r) =&gt; r.textContent === 'T:Alpha');
 const rendered = renderedRow.textContent;         <span class="cmt">// 'T:Alpha' &mdash; the optionTemplate applied</span>
 
 // A static combo with a real 'user' SVG icon, an initials avatar and a
@@ -960,8 +1004,9 @@ const deco = createCombo(decoHost, {
   ],
   selectedTemplate: (opt) =&gt; 'S:' + opt.label,
 });
+const decoPopup = deco.root.querySelector('.lat-combo__popup');   <span class="cmt">// captured before open: the popup moves into the shared layer host while open (BACKLOG-0002291)</span>
 deco.open();
-const decoRows = Array.from(deco.root.querySelectorAll('.lat-combo__option'));
+const decoRows = Array.from(decoPopup.querySelectorAll('.lat-combo__option'));
 const hasIcon = decoRows.some((r) =&gt; r.querySelector('.lat-combo__icon') !== null);   <span class="cmt">// true &mdash; the 'user' SVG</span>
 const hasAvatar = decoRows.some((r) =&gt; r.querySelector('.lat-combo__avatar') !== null); <span class="cmt">// true &mdash; round initials</span>
 deco.setValue('u');
@@ -1331,6 +1376,53 @@ form.setValue({ rating: '5' });                   <span class="cmt">// re-evalua
 form.destroy();
 <span class="kw">return</span> [blocked, advanced, active, custom, noteHidden, reviewReadOnly, wentBack, jumped, finish, vertical].join('|');</code></pre>
 
+    <h3 id="form-step-validation-example">Step validation, the <code>validateSteps</code> opt-out and the refused move, executed</h3>
+    <p class="section-note">A forward move &mdash; <code>next()</code>, <code>goToStep()</code> to a later step, or a click on a later indicator
+    step &mdash; validates the current step's items exactly as <code>form.validate()</code> does: a <code>required</code> item
+    left empty refuses the move, resolves <code>false</code>, paints the same <code>aria-invalid</code> and message, fires
+    <code>validated</code> and focuses the first invalid item, while <code>back()</code> never validates. <code>validateSteps:
+    false</code> restores the unchecked navigation &mdash; with the real Chrome indicator-click assertions in
+    <code>test/form-steps-validate-2290-browser.test.js</code>.</p>
+    <pre data-run="js" data-expect="false|0|true|This field is required.|true|true|true|true|true" data-covers="export:createForm method:form.next method:form.back method:form.on config:FormConfig.steps config:FormConfig.validateSteps config:FormItemConfig.required"><code><span class="kw">const</span> { createTestDom } = <span class="kw">await</span> import('../packages/dom/src/renderer/testdom.js');
+<span class="kw">const</span> { createForm } = <span class="kw">await</span> import('../packages/modules/form/index.js');
+
+<span class="kw">const</span> { root } = createTestDom();
+<span class="kw">let</span> validated = 0;
+<span class="kw">const</span> form = createForm(root, {
+  steps: [
+    { id: 'a', label: 'A', rows: [
+      { type: 'input', name: 'x', label: 'X', required: true },
+      { type: 'input', name: 'y', label: 'Y' },
+    ] },
+    { id: 'b', label: 'B', rows: [ { type: 'checkbox', name: 'done', label: 'Done', required: true } ] },
+  ],
+});
+form.on('validated', () =&gt; { validated += 1; });
+
+<span class="kw">const</span> blocked = <span class="kw">await</span> form.next();             <span class="cmt">// false &mdash; x is required and empty</span>
+<span class="kw">const</span> stayed = form.activeStep;                  <span class="cmt">// 0 &mdash; the move was refused</span>
+<span class="kw">const</span> xInput = form.getItem('x').el.querySelector('input');
+<span class="kw">const</span> invalid = xInput.getAttribute('aria-invalid');              <span class="cmt">// 'true' &mdash; as validate() paints it</span>
+<span class="kw">const</span> message = form.getItem('x').el.querySelector('.lat-form__validation').textContent; <span class="cmt">// 'This field is required.'</span>
+<span class="kw">const</span> focused = root.ownerDocument.activeElement === xInput;      <span class="cmt">// focus lands on the first invalid item</span>
+<span class="kw">const</span> fired = validated &gt; 0;                     <span class="cmt">// the refused move emitted `validated`</span>
+
+form.getItem('x').setValue('Ada');                <span class="cmt">// fill the required item</span>
+<span class="kw">const</span> advanced = <span class="kw">await</span> form.next();            <span class="cmt">// true &mdash; step one now validates</span>
+<span class="kw">const</span> wentBack = <span class="kw">await</span> form.back();            <span class="cmt">// true &mdash; back never validates</span>
+form.destroy();
+
+<span class="kw">const</span> uncheckedForm = createForm(root, {
+  validateSteps: <span class="kw">false</span>,                        <span class="cmt">// the integrator runs validate() itself</span>
+  steps: [
+    { id: 'a', label: 'A', rows: [ { type: 'input', name: 'x', label: 'X', required: true } ] },
+    { id: 'b', label: 'B', rows: [] },
+  ],
+});
+<span class="kw">const</span> unchecked = <span class="kw">await</span> uncheckedForm.next();   <span class="cmt">// true &mdash; no validation on the way</span>
+uncheckedForm.destroy();
+<span class="kw">return</span> [blocked, stayed, invalid, message, focused, fired, advanced, wentBack, unchecked].join('|');</code></pre>
+
     <h3 id="form-validation-example">Required, a regex, a function, modes and the validated event, executed</h3>
     <p class="section-note">An empty required item fails <code>form.validate()</code> with its catalogue message (overridden here to French) and
     <code>aria-invalid</code>; a regex rule and a function rule each pass and fail through <code>item.validate()</code>; a
@@ -1431,7 +1523,11 @@ built[0].setValue({ email: 'changed@x.y' });          <span class="cmt">// a lat
 
     <h3 id="form-controls-example">Choice, toggle and date controls, executed</h3>
     <p class="section-note">A <code>select</code> renders its own trigger and drop-down listbox on the combo's listbox
-    (BACKLOG-0002168) and commits when an option is chosen &mdash; or keeps the native element with <code>native: true</code>;
+    (BACKLOG-0002168) and commits when an option is chosen &mdash; or keeps the native element with <code>native: true</code>.
+    The select's, the combo's and the date picker's popup all open in the same shared top-level layer, positioned
+    against the field and never clipped by an ancestor's <code>overflow: hidden</code> or fixed height (BACKLOG-0002291):
+    it flips above when there is no room below, follows the field on scroll and resize, and closes on an outside
+    pointer down, Escape, Tab out or the field scrolling out of view;
     a <code>radiogroup</code> and a <code>checkboxgroup</code> commit on their options' change &mdash; laid out vertically by
     default, on one wrapping row with <code>orientation: 'horizontal'</code> (the radiogroup carries a matching
     <code>aria-orientation</code> and ArrowLeft/ArrowRight move between radios), or in an n-column grid with
@@ -1443,7 +1539,9 @@ built[0].setValue({ email: 'changed@x.y' });          <span class="cmt">// a lat
     <code>icon</code>, a round <code>avatar</code>, a <code>color</code> that tints them, and a <code>dot</code>
     colour shorthand &mdash; and both the list rows and the
     shown value accept <code>optionTemplate</code>/<code>selectedTemplate</code> renderers (a DOM node or an
-    HTML string, sanitised before insertion).</p>
+    HTML string, sanitised before insertion). Values supplied in <code>options</code> keep their own type through
+    <code>getValue()</code> and the <code>change</code> payload &mdash; choosing <code>{ value: 1 }</code> commits the
+    number <code>1</code>, not the string <code>'1'</code> (BACKLOG-0002293).</p>
     <pre data-run="js" data-expect="m|green|tow|true|2026-06-15|2026-06-15T09:30|07:45|l|red|roof,tow|false|4|2026-06-01|2026-06-01|2026-07-04|23:59|true|l" data-covers="export:createForm method:form.getItem method:form.getValue method:form.setValue method:form.on method:form.destroy config:FormItemConfig.type config:FormItemConfig.options config:FormItemConfig.mode config:FormItemConfig.locale config:FormItemConfig.timeZone config:FormItemConfig.min config:FormItemConfig.max config:FormItemConfig.value config:FormItemConfig.native"><code>const { createTestDom, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
 const { createForm } = await import('../packages/modules/form/index.js');
 
@@ -1485,8 +1583,9 @@ boxes[0].dispatchEvent(new TestEvent('change', { bubbles: true }));
 const committed = [form.getValue().size, form.getValue().colour, form.getValue().extras.join(','), form.getValue().auto, changes].join('|');
 
 const dayItem = form.getItem('day');
+const dayPopup = dayItem.el.querySelector('.lat-form__datepicker-popup');   <span class="cmt">// captured before open: the popup moves into the shared layer host while open (BACKLOG-0002291)</span>
 dayItem.el.querySelector('.lat-form__datepicker-toggle').dispatchEvent(new TestEvent('click', { bubbles: true }));
-dayItem.el.querySelector('.lat-form__datepicker-day').dispatchEvent(new TestEvent('click', { bubbles: true }));
+dayPopup.querySelector('.lat-form__datepicker-day').dispatchEvent(new TestEvent('click', { bubbles: true }));
 const clicked = form.getValue().day;
 
 const dayInput = form.getItem('day').el.querySelector('input');
@@ -2479,11 +2578,12 @@ shell.destroy();
           <tr><td class="name">labelPosition</td><td class="type"><a href="types.html#type-FormLabelPosition">FormLabelPosition</a> <small class="literals">'top' | 'left' | 'hidden'</small></td><td class="desc">The default label position every item inherits: `top`, `left` or `hidden`. An item's own `labelPosition` wins. <small>(optional)</small></td></tr>
           <tr><td class="name">labelWidth</td><td class="type">number | string</td><td class="desc">The default label column width every item inherits when its label is `left`; an item's own `labelWidth` wins. <small>(optional)</small></td></tr>
           <tr><td class="name">requiredHint</td><td class="type">boolean | string</td><td class="desc">The default marker a required field with no visible label shows on its placeholder: `true` appends `" *"`, a string resolves through the message catalogue, `false` shows nothing. An item's own `requiredHint` wins. <small>(optional)</small></td></tr>
-          <tr><td class="name">colsBreakpoint</td><td class="type">number</td><td class="desc">The width, in pixels, below which a `cols` container stacks its children into one column. Default 480. <small>(optional)</small></td></tr>
+          <tr><td class="name">colsBreakpoint</td><td class="type">number | false</td><td class="desc">The width, in pixels, below which a `cols` container stacks its children into one column, or `false` (or `0`) to never stack. A positive number is used as-is. Default 480. <small>(optional)</small></td></tr>
           <tr><td class="name">bind</td><td class="type"><a href="types.html#type-FormBind">FormBind</a></td><td class="desc">Bind the form to a record. A grid row generates one item per column and saves through the grid's edit path; a routed record follows the route's keyed diffs; a plain object is initialised from and written back to. <small>(optional)</small></td></tr>
           <tr><td class="name">css</td><td class="type">Record&lt;string, string | number&gt; | string</td><td class="desc">Extra CSS on the form root. <small>(optional)</small></td></tr>
           <tr><td class="name">steps</td><td class="type"><a href="#type-FormStep">FormStep</a>[]</td><td class="desc">Wizard steps: one labelled group of rows shown at a time. <small>(optional)</small></td></tr>
           <tr><td class="name">stepOrientation</td><td class="type"><a href="types.html#type-FormStepOrientation">FormStepOrientation</a> <small class="literals">'horizontal' | 'vertical'</small></td><td class="desc">The step indicator's orientation: `horizontal` (default) or `vertical`. <small>(optional)</small></td></tr>
+          <tr><td class="name">validateSteps</td><td class="type">boolean</td><td class="desc">Whether a forward step move validates the current step first (`true`, the default). Set `false` to run `validate()` yourself and navigate unchecked. <small>(optional)</small></td></tr>
           <tr><td class="name">messages</td><td class="type">{ t(key: string, params?: object): string }</td><td class="desc">A `t(key, params)` catalogue for the separator's accessible label. <small>(optional)</small></td></tr>
         </tbody>
       </table>

package/docs/api/gantt.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Gantt API Reference — Lattice Grid 1.101.2</title>
+<title>Gantt API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/geometry.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Geometry API Reference — Lattice Grid 1.101.2</title>
+<title>Geometry API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/grid.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Grid API Reference — Lattice Grid 1.101.2</title>
+<title>Grid API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an
@@ -1912,7 +1912,7 @@ grid.destroy();
       <table>
         <thead><tr><th>Member</th><th>Returns</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.101.2'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
+          <tr><td class="sig">getVersion()</td><td class="type">string</td><td class="desc">The version this grid came from, e.g. <code>'1.101.4'</code>. Also on the module as <code>getVersion()</code>, for when you have no grid to hand.</td></tr>
           <tr><td class="sig">get(key)</td><td class="type">unknown</td><td class="desc">Read any configuration key.</td></tr>
           <tr><td class="sig">set(key, value)</td><td class="type">void</td><td class="desc">Write one key. Every key is live; nothing needs a rebuild.</td></tr>
           <tr><td class="sig">setAll(values)</td><td class="type">void</td><td class="desc">Write several in one pass. Emits one <code>config:changed</code> for the batch, not one per key.</td></tr>

package/docs/api/index.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>API Reference — Lattice Grid 1.101.2</title>
+<title>API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an
@@ -455,7 +455,7 @@
           <tr><td class="name"><a href="tabs.html">The tabbed grid</a></td><td class="desc"><code>createTabs</code>: a tab strip where each tab holds a grid, a board, a KPI strip or a Gantt, and the tablist keyboard model.</td><td class="type">1</td><td class="type">7</td><td class="type">57</td></tr>
           <tr><td class="name"><a href="layout.html">The dashboard layout</a></td><td class="desc"><code>createLayout</code>: windows a reader moves, resizes and closes, the arrangement saved as plain JSON, locking, and the cancellable gestures.</td><td class="type">1</td><td class="type">15</td><td class="type">133</td></tr>
           <tr><td class="name"><a href="shell.html">The shell module</a></td><td class="desc"><code>createShell</code>: cells nested as rows and columns to any depth, sized by flexbox so the DOM is complete and measured the moment the factory returns.</td><td class="type">1</td><td class="type">25</td><td class="type">153</td></tr>
-          <tr><td class="name"><a href="form.html">The form module</a></td><td class="desc"><code>createForm</code>: named items laid out in nested rows and columns, themed by the grid's own density tokens, so the DOM is complete and measured the moment the factory returns.</td><td class="type">1</td><td class="type">40</td><td class="type">379</td></tr>
+          <tr><td class="name"><a href="form.html">The form module</a></td><td class="desc"><code>createForm</code>: named items laid out in nested rows and columns, themed by the grid's own density tokens, so the DOM is complete and measured the moment the factory returns.</td><td class="type">1</td><td class="type">40</td><td class="type">380</td></tr>
           <tr><td class="name"><a href="dashboard.html">Dashboard composition</a></td><td class="desc"><code>createDashboard</code>: a dashboard described as a JSON spec &mdash; a layout, grid, chart, KPI, map and html panels, a source per panel, links between them &mdash; built into the wired page, handed back by <code>spec()</code>, and proposed by the AI.</td><td class="type">1</td><td class="type">15</td><td class="type">81</td></tr>
           <tr><td class="name"><a href="designer.html">The Designer</a></td><td class="desc"><code>createDesigner</code>: a dashboard designer whose state is the dashboard spec extended with pages, in edit and view mode, with JSON state in and out.</td><td class="type">1</td><td class="type">63</td><td class="type">406</td></tr>
           <tr><td class="name"><a href="ai.html">The AI narrative and insights layer</a></td><td class="desc">The narrative module: summaries, insights and risk text over what the grid already holds. The <code>grid.ai</code> intent layer is on the grid page.</td><td class="type">1</td><td class="type">17</td><td class="type">124</td></tr>

package/docs/api/kanban.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Kanban API Reference — Lattice Grid 1.101.2</title>
+<title>Kanban API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/kpi.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>KPI API Reference — Lattice Grid 1.101.2</title>
+<title>KPI API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/layout.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Layout API Reference — Lattice Grid 1.101.2</title>
+<title>Layout API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/leaflet.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Leaflet API Reference — Lattice Grid 1.101.2</title>
+<title>Leaflet API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/list.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>List API Reference — Lattice Grid 1.101.2</title>
+<title>List API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/mapview.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Map view API Reference — Lattice Grid 1.101.2</title>
+<title>Map view API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/mock-socket.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Mock socket API Reference — Lattice Grid 1.101.2</title>
+<title>Mock socket API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/presets.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Presets API Reference — Lattice Grid 1.101.2</title>
+<title>Presets API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/scheduler.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Scheduler API Reference — Lattice Grid 1.101.2</title>
+<title>Scheduler API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/shell.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Shell API Reference — Lattice Grid 1.101.2</title>
+<title>Shell API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/tabs.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Tabs API Reference — Lattice Grid 1.101.2</title>
+<title>Tabs API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an

package/docs/api/types.html

@@ -13,7 +13,7 @@
   Self-contained: no stylesheet, script or font is fetched, so this opens from disk, from
   a file share or from behind a firewall with nothing else present.
 -->
-<title>Types API Reference — Lattice Grid 1.101.2</title>
+<title>Types API Reference — Lattice Grid 1.101.4</title>
 <style>
   /* ---------------------------------------------------------------
      Palette lifted from the grid's own theme, so the reference reads as an