@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/core/components/ui/form/checkbox/checkbox.md

@@ -1,77 +1,125 @@
 # Checkbox
 
-## Size
+**`sonic-checkbox`** is a styled checkbox that writes its `value` into form data. Give it a `name` and a `formDataProvider` (on the field or an ancestor); checkboxes sharing a `name` build an array of the checked values. Label goes in the default slot or `label`, helper text in the `description` slot.
+
+## Basic example
+
 <sonic-code>
   <template>
-  <div class="grid gap-2">
-    <sonic-checkbox size="2xs">2xs checkbox</sonic-checkbox>
-    <sonic-checkbox size="xs">xs checkbox</sonic-checkbox>
-    <sonic-checkbox size="sm">sm checkbox</sonic-checkbox>
-    <sonic-checkbox>default checkbox</sonic-checkbox>
-    <sonic-checkbox size="lg">lg checkbox</sonic-checkbox>
-    <sonic-checkbox size="xl">xl checkbox</sonic-checkbox>
-    <sonic-checkbox size="2xl">2xl checkbox</sonic-checkbox>
-  </div>
+    <sonic-checkbox>
+      Notify me of gate changes
+      <span slot="description">One message per change, no spam.</span>
+    </sonic-checkbox>
   </template>
 </sonic-code>
 
-## Checked
+## Size
+
+With no `size`, the checkbox follows `md` (1rem).
+
 <sonic-code>
   <template>
-  <sonic-checkbox checked
-    >Already checked checkbox
-  </sonic-checkbox>
+    <div class="grid gap-2">
+      <sonic-checkbox size="2xs">2xs</sonic-checkbox>
+      <sonic-checkbox size="xs">xs</sonic-checkbox>
+      <sonic-checkbox size="sm">sm</sonic-checkbox>
+      <sonic-checkbox>Default</sonic-checkbox>
+      <sonic-checkbox size="lg">lg</sonic-checkbox>
+      <sonic-checkbox size="xl">xl</sonic-checkbox>
+      <sonic-checkbox size="2xl">2xl</sonic-checkbox>
+    </div>
   </template>
 </sonic-code>
 
-## Disabled
+## Checked and disabled
+
+`checked` sets the initial state. `disabled` blocks interaction and dims the control.
+
 <sonic-code>
   <template>
-  <sonic-checkbox disabled
-    >Disabled checkbox
-  </sonic-checkbox>
+    <div class="grid gap-2">
+      <sonic-checkbox checked>Checked</sonic-checkbox>
+      <sonic-checkbox disabled>Disabled</sonic-checkbox>
+      <sonic-checkbox disabled checked>Disabled and checked</sonic-checkbox>
+      <sonic-checkbox>I accept the <sonic-link href="#" class="underline">terms</sonic-link></sonic-checkbox>
+    </div>
   </template>
 </sonic-code>
 
-## Disabled and checked
+## Form binding
+
+Checkboxes with the same `name` under one `formDataProvider` store an array of the checked `value`s. Initial state is read from that data, so a value already present checks the matching box. See [Data flow](/docs/getting-started/dataFlow).
+
 <sonic-code>
   <template>
-  <sonic-checkbox disabled checked
-    >Disabled but already checked checkbox
-  </sonic-checkbox>
+    <div formDataProvider="checkbox-multiple-demo" class="grid gap-2">
+      <sonic-checkbox name="extras" value="baggage" checked>Extra baggage</sonic-checkbox>
+      <sonic-checkbox name="extras" value="meal">Meal</sonic-checkbox>
+      <sonic-checkbox name="extras" value="lounge">Lounge access</sonic-checkbox>
+      <div>Selected: <sonic-value dataProvider="checkbox-multiple-demo" key="extras"></sonic-value></div>
+    </div>
   </template>
 </sonic-code>
 
-## Checkbox with link
+## Single value
+
+`unique` stores a single value instead of an array: checking one box unchecks the others with the same `name`, and the checked box can be unchecked again (value `null`). `radio` does the same but cannot be unchecked by a click.
+
 <sonic-code>
   <template>
-  <sonic-checkbox>Checkbox with <sonic-link href="#" class="underline text-info">link</sonic-link>
+    <div formDataProvider="checkbox-unique-demo" class="grid gap-2">
+      <sonic-checkbox unique name="cabin" value="economy">Economy</sonic-checkbox>
+      <sonic-checkbox unique name="cabin" value="business">Business</sonic-checkbox>
+      <div>Cabin: <sonic-value dataProvider="checkbox-unique-demo" key="cabin"></sonic-value></div>
+    </div>
   </template>
 </sonic-code>
 
-## Check all checkbox
+## Check all and indeterminate
+
+A checkbox with `checksAll` and the same `name` toggles every sibling value. It shows the indeterminate icon when only some are checked; its own `value` is never stored. With `unsetOnDisconnect`, a checkbox removes its value from the data when it leaves the DOM. `showAsIndeterminate` forces the indeterminate icon on any checkbox.
+
 <sonic-code>
-  <template>    
-      <div formDataProvider="checkbox-check-all-demo">
-      <sonic-checkbox  name='someSharedName' value="all" checksAll>All</sonic-checkbox>
-      <sonic-divider></sonic-divider>
-      <div class="grid gap-2">
-      <sonic-checkbox name="someSharedName" value="foo">Foo</sonic-checkbox>
-      <sonic-checkbox name="someSharedName" value="bar">Bar</sonic-checkbox>
+  <template>
+    <div formDataProvider="checkbox-check-all-demo" class="grid gap-2">
+      <sonic-checkbox name="alerts" value="all" checksAll>All alerts</sonic-checkbox>
+      <sonic-checkbox name="alerts" value="boarding">Boarding</sonic-checkbox>
+      <sonic-checkbox name="alerts" value="gate">Gate change</sonic-checkbox>
+      <div id="checkbox-removable" class="flex gap-2 items-center">
+        <sonic-checkbox name="alerts" value="delay" unsetOnDisconnect>Delay</sonic-checkbox>
+        <sonic-button size="xs" variant="ghost" onclick="document.getElementById('checkbox-removable').remove()">Remove</sonic-button>
       </div>
-      <sonic-divider></sonic-divider>
-      <div>
-        <span>Enabling unsetOnDisconect ensures that outdated or irrelevant values are not retained in the form state once their associated inputs are no longer rendered.</span>
-        <div id="prunable-checkbox" class="flex gap-2 items-center">
-        <sonic-checkbox name="someSharedName" value="baz">Baz</sonic-checkbox>
-        <sonic-button variant="ghost" shape="circle" unique name="toggleCheckboxExistance" onclick="document.getElementById('prunable-checkbox').remove();" value="true"><sonic-icon library="fontAwesome" prefix="solid" name="trash"></sonic-icon></sonic-button>
-        </div>
+      <div>Selected: <sonic-value dataProvider="checkbox-check-all-demo" key="alerts"></sonic-value></div>
     </div>
   </template>
 </sonic-code>
 
-## Example of use — blacklist + queue
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `name` | string | Key in the form data (dot notation supported) |
+| `value` | string | Value stored when checked |
+| `formDataProvider` | string | Form data id; inherited from the closest ancestor when omitted |
+| `checked` | boolean | Initial checked state |
+| `unique` | boolean | Stores a single value; can be unchecked |
+| `radio` | boolean | Stores a single value; cannot be unchecked by a click |
+| `checksAll` | boolean | Toggles every checkbox with the same `name` |
+| `unsetOnDisconnect` | boolean | Removes the value from the data when the element is removed |
+| `showAsIndeterminate` | boolean | Forces the indeterminate icon |
+| `label` | string (HTML) | Label, rendered before the default slot |
+| `description` | string (HTML) | Helper text, rendered in the `description` slot |
+| `size` | `2xs` … `2xl` · `inherit` (default `md`) | Font size and box size |
+| `disabled` | boolean | Blocks interaction |
+| `required` | boolean | Native validation on form submit |
+| `autofocus` | boolean | Focuses the input on load |
+| `iconName` | string (default `check`) | Icon shown when checked |
+| `indeterminateIconName` | string (default `minus-small`) | Icon shown when indeterminate |
+| `data-aria-label` · `data-aria-labelledby` | string | Forwarded to the inner input as `aria-label` / `aria-labelledby` |
 
-Checked **`blacklistFlags`** values are sent to the mock API (`?blacklistFlags=racist,sexist,…`), which excludes jokes whose **`flags`** match (see `filterDocsJokes` in `src/docs/mock-api/fixtures.ts`).
+| Slot | Description |
+|------|-------------|
+| *(default)* | Label content (text, links) |
+| `description` | Helper text under the label |
 
-<docs-lit-demo for="docs-joke-blacklist-demo"></docs-lit-demo>
+Fires a `change` event on each click.

package/src/core/components/ui/form/fieldset/fieldset.md

@@ -1,13 +1,13 @@
 # Fieldset
 
-**`sonic-fieldset`** groups related form controls with a bordered container and an accessible **`<fieldset>`** semantics layer. Put fields in the **default slot**; add a title with **`sonic-legend`** or the shorthand **`label`** / **`description`** / **`iconName`** attributes. Default **`variant`** is `default`. Pair the body with **`sonic-form-layout`** for responsive columns.
+**`sonic-fieldset`** groups related form controls in a bordered container rendered as a native `<fieldset>`. Put fields in the default slot and title the group with a slotted `sonic-legend` or with the `label` and `description` shorthand. Pair the body with `sonic-form-layout` for responsive columns.
 
 ## Basic example
 
 <sonic-code>
   <template>
     <sonic-fieldset>
-      <sonic-legend label="Contact details"></sonic-legend>
+      <sonic-legend label="Passenger contact"></sonic-legend>
       <sonic-form-layout>
         <sonic-input autocomplete="email" label="Email" name="email" type="email"></sonic-input>
         <sonic-input autocomplete="tel" label="Phone" name="phone" type="tel"></sonic-input>
@@ -18,7 +18,7 @@
 
 ## Variant
 
-**`ghost`** and **`shadow`** use a transparent border; **`shadow`** also applies **`--sc-shadow-lg`**.
+With no `variant`, the fieldset is `default` (bordered). `ghost` and `shadow` hide the border; `shadow` adds `--sc-shadow-lg`.
 
 <sonic-code>
   <template>
@@ -39,9 +39,9 @@
   </template>
 </sonic-code>
 
-## Tight layout
+## Tight
 
-Set **`tight`** to remove horizontal padding and side borders (flat strip inside a parent).
+`tight` removes horizontal padding, side borders and rounding, for a flat strip inside a parent.
 
 <sonic-code>
   <template>
@@ -54,9 +54,7 @@ Set **`tight`** to remove horizontal padding and side borders (flat strip inside
 
 ## Legend
 
-Use **`sonic-legend`** for the group title. Set **`label`** and **`description`** for simple copy, or use the **default slot** for custom markup. Add secondary text with **`sonic-legend-description`**. Place actions in **`slot="suffix"`** on the legend.
-
-Attribute values on **`sonic-legend`** are rendered as HTML—use only trusted content.
+`sonic-legend` takes `label` and `description`, or custom markup in its default slot with `sonic-legend-description` for the secondary line. `iconName` adds a leading `sonic-icon`. **`label` and `description` are rendered as HTML**: pass trusted content only.
 
 <sonic-code>
   <template>
@@ -76,15 +74,15 @@ Attribute values on **`sonic-legend`** are rendered as HTML—use only trusted c
   </template>
 </sonic-code>
 
-## Shorthand legend on the fieldset
+## Shorthand legend
 
-When **`label`** is set on **`sonic-fieldset`**, the component renders **`sonic-legend`** for you. Pass **`description`** **`iconName`** **`iconLibrary`** and **`iconPrefix`** the same way. Do not combine shorthand **`label`** with a separate slotted **`sonic-legend`**—you will get two legends.
+When `label` is set on `sonic-fieldset`, it renders the `sonic-legend` itself and forwards `description` · `iconName` · `iconLibrary` · `iconPrefix`. Do not also slot a `sonic-legend`, or the group gets two titles.
 
 <sonic-code>
   <template>
     <sonic-fieldset
-      label="Account"
-      description="Basic profile fields"
+      label="Crew profile"
+      description="Basic crew member fields"
       iconLibrary="iconoir"
       iconName="user"
     >
@@ -95,12 +93,12 @@ When **`label`** is set on **`sonic-fieldset`**, the component renders **`sonic-
 
 ## Legend actions
 
-Use **`slot="suffix"`** on **`sonic-legend`** for menus or icon buttons aligned to the end of the legend row.
+`slot="suffix"` on `sonic-legend` aligns menus or icon buttons to the end of the title row.
 
 <sonic-code>
   <template>
     <sonic-fieldset>
-      <sonic-legend label="Personal information">
+      <sonic-legend label="Passenger details">
         <sonic-pop class="inline-block" slot="suffix">
           <sonic-button shape="circle" variant="ghost">
             <sonic-icon library="iconoir" size="lg" name="more-vert"></sonic-icon>
@@ -119,49 +117,7 @@ Use **`slot="suffix"`** on **`sonic-legend`** for menus or icon buttons aligned
   </template>
 </sonic-code>
 
-## Form association and disabled state
-
-### Associating a distant `form`
-
-Set **`form`** on **`sonic-fieldset`** to the **`id`** of a **`<form>`** elsewhere in the page (same as the native **`form`** attribute on **`<fieldset>`**). Named fields in the fieldset then belong to that form for submit and constraint validation—for example a toolbar **`form`** and a field group rendered lower on the layout.
-
-<sonic-code>
-  <template>
-    <div class="grid gap-4">
-      <form id="billing-form" class="flex flex-wrap items-center gap-2">
-        <sonic-button submit type="primary">Save billing</sonic-button>
-      </form>
-      <sonic-fieldset form="billing-form" label="Billing address">
-        <sonic-form-layout>
-          <sonic-input label="Street" name="street" autocomplete="street-address"></sonic-input>
-          <sonic-input label="Postal code" required name="postal_code" autocomplete="postal-code"></sonic-input>
-          <sonic-input label="City" name="city" autocomplete="address-level2"></sonic-input>
-        </sonic-form-layout>
-      </sonic-fieldset>
-    </div>
-  </template>
-</sonic-code>
-
-### Disabling a group
-
-Set **`disabled`** on **`sonic-fieldset`** to disable the inner **`<fieldset>`** and every control in the group (same as a native fieldset). Use it for read-only steps or sections gated by permissions.
-
-<sonic-code>
-  <template>
-    <div class="grid gap-4">
-      <sonic-fieldset label="Editable">
-        <sonic-input label="Display name" name="display_name"></sonic-input>
-      </sonic-fieldset>
-      <sonic-fieldset label="Locked" disabled>
-        <sonic-input label="Account ID" name="account_id" value="acct_42"></sonic-input>
-      </sonic-fieldset>
-    </div>
-  </template>
-</sonic-code>
-
-## Accessibility
-
-The inner **`<fieldset>`** carries grouping semantics. **`disabled`** is applied on that element so nested controls are disabled in the usual way. **`sonic-legend`** renders a native **`<legend>`** for the group label.
+<sonic-alert status="warning" label="Disabled state and form association" text="Both attributes are set on the inner native fieldset only. Slotted Concorde fields are not disabled or re-associated by them: set disabled on each field instead."></sonic-alert>
 
 ## API reference
 
@@ -170,36 +126,36 @@ The inner **`<fieldset>`** carries grouping semantics. **`disabled`** is applied
 | Attribute | Values | Description |
 |----------|---------|-------------|
 | `variant` | `default` · `ghost` · `shadow` (default `default`) | Border and shadow treatment |
-| `tight` | boolean | Removes horizontal padding and side borders |
-| `label` | string | Shorthand legend title; renders **`sonic-legend`** when set |
-| `description` | string | Shorthand legend description (HTML) |
-| `iconName` | string | Shorthand legend icon **`name`** |
-| `iconLibrary` | string | Shorthand legend icon **`library`** |
-| `iconPrefix` | string | Shorthand legend icon **`prefix`** |
-| `disabled` | boolean | Disables the native **`<fieldset>`** and its controls |
-| `form` | string | **`id`** of an associated **`form`** |
-| `dataProvider` | string | Subscriber key; can autofill properties that match publisher fields (e.g. **`label`**) |
+| `tight` | boolean | Removes horizontal padding, side borders and rounding |
+| `label` | string | Shorthand title; renders a `sonic-legend` when set |
+| `description` | string | Shorthand description (HTML) |
+| `iconName` | string | Shorthand legend icon `name` |
+| `iconLibrary` | string | Shorthand legend icon `library` |
+| `iconPrefix` | string | Shorthand legend icon `prefix` |
+| `disabled` | boolean | Sets `disabled` on the inner native `<fieldset>` |
+| `form` | string | Sets `form` on the inner native `<fieldset>` |
+| `dataProvider` | string | Publisher key; matching publisher fields (e.g. `label`) fill the properties |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Legend (optional) and field group content in visual order |
+| *(default)* | Optional `sonic-legend`, then the grouped fields |
 
 ### `sonic-legend`
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `label` | string | Title HTML when not using the default slot |
-| `description` | string | Description HTML (wrapped in **`sonic-legend-description`**) |
-| `iconName` | string | Leading **`sonic-icon`** **`name`** |
-| `iconLibrary` | string | Icon **`library`** |
-| `iconPrefix` | string | Icon **`prefix`** |
-| `forceAutoFill` | boolean | Allows Subscriber autofill to override attribute-backed **`label`** / **`description`** |
+| `label` | string | Title (HTML) |
+| `description` | string | Description (HTML), wrapped in `sonic-legend-description` |
+| `iconName` | string | Leading `sonic-icon` `name` |
+| `iconLibrary` | string | Icon `library` |
+| `iconPrefix` | string | Icon `prefix` |
+| `forceAutoFill` | boolean | Lets a `label` or `description` set as a property override the attribute value |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Legend title and description components |
+| *(default)* | Custom title and `sonic-legend-description` |
 | `suffix` | Trailing actions (menus, icon buttons) |
 
 ### `sonic-legend-description`
 
-Muted description line below the legend title. No attributes—project content through the **default slot**.
+No attributes. The default slot holds the muted line under the legend title.

package/src/core/components/ui/form/form-actions/form-actions.md

@@ -1,10 +1,10 @@
 # Form actions
 
-**`sonic-form-actions`** lays out submit / cancel and other **form footer controls** in a **wrapping flex row** with a small fixed gap. Place it inside **`sonic-form-layout`** (full-width row) or any block that should end with actions. Defaults: **`direction`** `row` · **`justify`** `flex-start` · **`alignItems`** `center`.
+**`sonic-form-actions`** lays out form footer controls (submit, cancel) in a wrapping flex row with a `0.3rem` gap. Place it inside `sonic-form-layout`, where it spans the full width, or at the end of any block. Use `justify` and `direction` to arrange the controls.
 
 ## Basic example
 
-With no attributes, actions align to the **start** of the row (typical for left-to-right forms).
+With no attributes, actions align to the start of the row.
 
 <sonic-code>
   <template>
@@ -13,7 +13,7 @@ With no attributes, actions align to the **start** of the row (typical for left-
         <sonic-input label="First name"></sonic-input>
         <sonic-input label="Last name"></sonic-input>
         <sonic-form-actions>
-          <sonic-button type="success"><sonic-icon name="check" library="iconoir"></sonic-icon> Submit</sonic-button>
+          <sonic-button type="success"><sonic-icon name="check" library="iconoir"></sonic-icon> Check in</sonic-button>
           <sonic-button type="danger" variant="ghost"><sonic-icon name="undo" library="iconoir"></sonic-icon> Cancel</sonic-button>
         </sonic-form-actions>
       </sonic-form-layout>
@@ -21,9 +21,9 @@ With no attributes, actions align to the **start** of the row (typical for left-
   </template>
 </sonic-code>
 
-## Justify content
+## Justify
 
-**`justify`** maps to CSS **`justify-content`**. Use **`flex-end`** for dialog-style footers or **`center`** for balanced toolbars.
+`justify` is the CSS `justify-content` of the row (default `flex-start`). Use `flex-end` for dialog-style footers or `center` for toolbars.
 
 <sonic-code>
   <template>
@@ -40,9 +40,9 @@ With no attributes, actions align to the **start** of the row (typical for left-
   </template>
 </sonic-code>
 
-## Flex direction
+## Direction
 
-**`direction`** maps to **`flex-direction`**. **`row-reverse`** swaps visual order while keeping DOM order (focus order unchanged).
+`direction` is the CSS `flex-direction` (default `row`). `row-reverse` swaps the visual order but keeps the DOM and focus order.
 
 <sonic-code>
   <template>
@@ -61,7 +61,7 @@ With no attributes, actions align to the **start** of the row (typical for left-
 
 ## Mixed controls
 
-Combine **`sonic-button`** with **`sonic-divider vertical`** or other slotted content. Default **`alignItems`** `center` keeps unlike heights aligned on the cross axis.
+Any content can be slotted, such as a vertical `sonic-divider`. The default `alignItems` (`center`) keeps items of different heights aligned.
 
 <sonic-code>
   <template>
@@ -72,12 +72,12 @@ Combine **`sonic-button`** with **`sonic-divider vertical`** or other slotted co
         <sonic-form-actions justify="center">
           <sonic-button type="info" minWidth="12rem">
             <sonic-icon name="nav-arrow-left" library="iconoir" slot="prefix"></sonic-icon>
-            Left seats
+            Previous step
           </sonic-button>
           <sonic-divider vertical></sonic-divider>
           <sonic-button type="info" minWidth="12rem">
             <sonic-icon name="nav-arrow-right" library="iconoir" slot="suffix"></sonic-icon>
-            Right seats
+            Next step
           </sonic-button>
         </sonic-form-actions>
       </sonic-form-layout>
@@ -89,12 +89,10 @@ Combine **`sonic-button`** with **`sonic-divider vertical`** or other slotted co
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `direction` | `row` (default) · `column` · `row-reverse` · `column-reverse` | Main-axis layout of slotted controls |
-| `justify` | CSS justify-content (default `flex-start`) | Distribution along the main axis |
-| `alignItems` | CSS align-items (default `center`) | Cross-axis alignment when items differ in height |
-
-The component exposes a single unnamed slot; there are no named slots. Slotted nodes use the host’s flex **`gap`** (`0.3rem`) and **`flex-wrap`**.
+| `direction` | `row` (default) · `column` · `row-reverse` · `column-reverse` | CSS `flex-direction` of the row |
+| `justify` | CSS `justify-content` value (default `flex-start`) | Distribution along the main axis |
+| `alignItems` | CSS `align-items` value (default `center`) | Cross-axis alignment |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Footer actions (**`sonic-button`** and related controls) |
+| *(default)* | Footer controls |

package/src/core/components/ui/form/form-layout/form-layout.md

@@ -1,11 +1,9 @@
 # Form layout
 
-**`sonic-form-layout`** arranges slotted form controls in a **responsive CSS grid** with consistent vertical spacing. Pair **`sonic-input`** · **`sonic-select`** and **`sonic-input-autocomplete`** fields side by side when the host is wider than **440px**; **textareas**, **toggles**, **dividers**, and **`sonic-form-actions`** span the full width. Wrap a **`form`** or **`sonic-fieldset`** body—no attributes are required.
+**`sonic-form-layout`** arranges slotted form controls in a responsive grid. Short fields (`sonic-input` · `sonic-select`) sit two per row when the host is wider than `440px`; every other child spans the full width. It has no attributes: wrap the body of a `form` or `sonic-fieldset` with it.
 
 ## Basic example
 
-Typical registration-style form: short fields flow in two columns on wide layouts; long or grouped blocks stay full width.
-
 <sonic-code>
   <template>
     <form>
@@ -35,15 +33,15 @@ Typical registration-style form: short fields flow in two columns on wide layout
           type="password"
         ></sonic-input>
         <sonic-divider></sonic-divider>
-        <sonic-textarea label="Message" rows="5"></sonic-textarea>
-        <sonic-switch>Enable optional feature</sonic-switch>
+        <sonic-textarea label="Special assistance" rows="5"></sonic-textarea>
+        <sonic-switch>Add priority boarding</sonic-switch>
         <sonic-checkbox>Subscribe to newsletter</sonic-checkbox>
         <sonic-checkbox>
           I accept the
           <sonic-link href="#" class="underline">terms and conditions</sonic-link>
         </sonic-checkbox>
         <sonic-form-actions>
-          <sonic-button type="success">Submit</sonic-button>
+          <sonic-button type="success">Confirm passenger</sonic-button>
         </sonic-form-actions>
       </sonic-form-layout>
     </form>
@@ -52,24 +50,18 @@ Typical registration-style form: short fields flow in two columns on wide layout
 
 ## Responsive columns
 
-When the host **`offsetWidth`** is **greater than 440px**, the grid uses **two equal columns** with slightly larger gap (**1.75rem**). Below that breakpoint, fields stack in a **single column** (**1.5rem** gap).
-
-If the slot contains **exactly one** direct **`sonic-input`**, **`sonic-select`**, or **`sonic-input-autocomplete`**, the layout stays **one column** even above the breakpoint so a lone field does not sit in half an empty row.
+The column count depends on the host width, not the viewport: two columns above `440px`, one below. When the layout holds exactly one short field, it stays single-column so the field does not sit in half an empty row.
 
 <sonic-code>
   <template>
-    <div class="grid gap-8 md:grid-cols-2 mb-6">
-      <div>
-        <sonic-form-layout style="max-width: 20rem">
-        <sonic-divider align="left">Narrow host (single column)</sonic-divider>
-          <sonic-input label="Email" name="email_narrow" type="email"></sonic-input>
-          <sonic-input label="Confirm email" name="email_confirm_narrow" type="email"></sonic-input>
-        </sonic-form-layout>
-      </div>
-    </div>
-    <div>
+    <div class="grid gap-8">
+      <sonic-form-layout style="max-width: 20rem">
+        <sonic-divider align="left">Narrow host</sonic-divider>
+        <sonic-input label="Email" name="email_narrow" type="email"></sonic-input>
+        <sonic-input label="Confirm email" name="email_confirm_narrow" type="email"></sonic-input>
+      </sonic-form-layout>
       <sonic-form-layout>
-      <sonic-divider align="left">Wide host (two columns for inputs)</sonic-divider>
+        <sonic-divider align="left">Wide host</sonic-divider>
         <sonic-input label="Email" name="email_wide" type="email"></sonic-input>
         <sonic-input label="Confirm email" name="email_confirm_wide" type="email"></sonic-input>
       </sonic-form-layout>
@@ -77,11 +69,9 @@ If the slot contains **exactly one** direct **`sonic-input`**, **`sonic-select`*
   </template>
 </sonic-code>
 
-## Full-width slotted blocks
-
-Everything except **`sonic-input`**, **`sonic-select`**, **`sonic-input-autocomplete`**, and slotted elements with class **`form-item-container`** is assigned **`grid-column: 1 / -1`**. Use this for **`sonic-textarea`**, **`sonic-checkbox`**, **`sonic-switch`**, **`sonic-form-actions`**, **`sonic-divider`**, and similar blocks.
+## Full-width children
 
-Slotted **`sonic-divider`** sets **`--sc-divider-my: 0`** so divider spacing matches the grid rhythm. Slotted **`sonic-submit`** uses **`display: contents`** so submit controls participate in the grid without an extra wrapper box.
+Any child that is not a short field spans the full row: `sonic-textarea` · `sonic-checkbox` · `sonic-switch` · `sonic-divider` · `sonic-form-actions` and plain elements. Slotted dividers lose their vertical margin to match the grid gap, and `sonic-submit` uses `display: contents` so its button joins the grid directly.
 
 <sonic-code>
   <template>
@@ -97,14 +87,14 @@ Slotted **`sonic-divider`** sets **`--sc-divider-my: 0`** so divider spacing mat
 
 ## Custom column wrapper
 
-Add class **`form-item-container`** on a slotted wrapper (for example a **`div`**) when a field is not a direct **`sonic-input`** / **`sonic-select`** / **`sonic-input-autocomplete`** but should still share the two-column flow with short inputs.
+Add the class `form-item-container` to a wrapper element to keep it in the two-column flow like a short field.
 
 <sonic-code>
   <template>
     <sonic-form-layout>
-      <sonic-input label="City" name="city"></sonic-input>
+      <sonic-input label="From" name="from" placeholder="CDG"></sonic-input>
       <div class="form-item-container">
-        <sonic-input label="Postal code" name="postal_code"></sonic-input>
+        <sonic-input label="To" name="to" placeholder="JFK"></sonic-input>
       </div>
     </sonic-form-layout>
   </template>
@@ -112,8 +102,8 @@ Add class **`form-item-container`** on a slotted wrapper (for example a **`div`*
 
 ## API reference
 
-No public attributes — layout follows slotted children and host width.
+No attributes.
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Form fields and blocks in visual order; column vs full-width rules apply per slotted tag or **`form-item-container`** class |
+| *(default)* | Fields and blocks in visual order; short fields and `form-item-container` share rows, everything else spans the full width |