@supersoniks/concorde 5.1.1 → 5.1.3

package/docs/src/core/components/ui/divider/divider.md

@@ -0,0 +1,126 @@
+# Divider
+
+**`sonic-divider`** draws a horizontal or vertical rule with optional **centered label** copy. Use it to separate sections in forms, cards, and **`sonic-menu`**. Set **`label`** for simple HTML captions or use the **default slot** for richer markup; default **`align`** is **`center`** and default **`lineStyle`** is **`solid`**.
+
+## Basic example
+
+A bare divider is a full-width line with vertical margin. Omit **`size`** to use the host default spacing (`0.5rem` block margin).
+
+<sonic-code>
+  <template>
+    <sonic-divider></sonic-divider>
+  </template>
+</sonic-code>
+
+## Label and align
+
+**`label`** renders inside the line (as HTML). **`align`** controls which side(s) of the line remain visible: **`left`** drops the leading segment, **`right`** drops the trailing segment, **`center`** keeps both.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-divider label="Default centered label"></sonic-divider>
+      <sonic-divider label="Left" align="left"></sonic-divider>
+      <sonic-divider label="Center" align="center"></sonic-divider>
+      <sonic-divider label="Right" align="right"></sonic-divider>
+    </div>
+  </template>
+</sonic-code>
+
+## Size
+
+**`size`** adjusts block margin and label font size. Values follow the shared Concorde scale (`2xs` … `2xl`).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-divider size="2xs" label="2xs"></sonic-divider>
+      <sonic-divider size="xs" label="xs"></sonic-divider>
+      <sonic-divider size="sm" label="sm"></sonic-divider>
+      <sonic-divider size="md" label="md"></sonic-divider>
+      <sonic-divider size="lg" label="lg"></sonic-divider>
+      <sonic-divider size="xl" label="xl"></sonic-divider>
+      <sonic-divider size="2xl" label="2xl"></sonic-divider>
+    </div>
+  </template>
+</sonic-code>
+
+## Line style
+
+**`lineStyle`** sets the stroke of the rule (`solid` · `dashed` · `dotted`). In HTML use the reflected attribute **`linestyle`** (case-insensitive).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-divider label="Solid"></sonic-divider>
+      <sonic-divider label="Dashed" lineStyle="dashed"></sonic-divider>
+      <sonic-divider label="Dotted" lineStyle="dotted"></sonic-divider>
+    </div>
+  </template>
+</sonic-code>
+
+## Vertical and margin
+
+Set **`vertical`** for a column rule (for example between toolbar actions). **`noMargin`** removes host margin when a parent layout already provides spacing.
+
+<sonic-code>
+  <template>
+    <div class="flex items-stretch gap-2" style="min-height: 3rem;">
+      <span class="flex items-center px-2">Before</span>
+      <sonic-divider vertical noMargin></sonic-divider>
+      <span class="flex items-center px-2">After</span>
+    </div>
+  </template>
+</sonic-code>
+
+## Default slot
+
+Slotted content replaces or augments **`label`**. Useful for badges, icons, or mixed markup in menus.
+
+<sonic-code>
+  <template>
+    <sonic-divider>
+      <span class="mr-2">Departures</span>
+      <sonic-badge type="danger">+25</sonic-badge>
+    </sonic-divider>
+  </template>
+</sonic-code>
+
+## Inside typed cards
+
+On **`sonic-card`** with semantic **`type`** (`primary` · `warning` · `danger` · `info` · `success`), the rule uses the card’s text color at reduced opacity so it stays visible on tinted surfaces. **`label`** and slotted captions use the same foreground color as surrounding copy.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4 max-w-xl">
+      <sonic-card type="danger">
+        <div>CN 001 is cancelled.</div>
+        <sonic-divider label="Affected passengers"></sonic-divider>
+        <ul class="m-0 pl-5 text-sm">
+          <li>Ada Lindqvist</li>
+          <li>Captain Leo Marchand</li>
+        </ul>
+      </sonic-card>
+      <sonic-card type="info">
+        <div>Aircraft maintenance is scheduled for tonight.</div>
+        <sonic-divider></sonic-divider>
+        <div class="opacity-60">Expected downtime: about 15 minutes.</div>
+      </sonic-card>
+    </div>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `label` | string (HTML) | Caption centered on the rule; combined with default-slot content when both are set |
+| `align` | `left` · `center` · `right` (default `center`) | Hides the leading or trailing line segment for left/right alignment |
+| `size` | `2xs` … `2xl` · `inherit` | Vertical margin and label `font-size`; omit for host defaults |
+| `lineStyle` | `solid` · `dashed` · `dotted` (default `solid`) | Stroke style of the rule (HTML attribute `linestyle`) |
+| `vertical` | boolean | Renders a vertical rule; swap block/inline margins |
+| `noMargin` | boolean | Sets host margin to `0` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Label markup when **`label`** is insufficient or empty |

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

@@ -0,0 +1,125 @@
+# Checkbox
+
+**`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>
+    <sonic-checkbox>
+      Notify me of gate changes
+      <span slot="description">One message per change, no spam.</span>
+    </sonic-checkbox>
+  </template>
+</sonic-code>
+
+## Size
+
+With no `size`, the checkbox follows `md` (1rem).
+
+<sonic-code>
+  <template>
+    <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>
+
+## Checked and disabled
+
+`checked` sets the initial state. `disabled` blocks interaction and dims the control.
+
+<sonic-code>
+  <template>
+    <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>
+
+## 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>
+    <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>
+
+## 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>
+    <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 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" 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>
+      <div>Selected: <sonic-value dataProvider="checkbox-check-all-demo" key="alerts"></sonic-value></div>
+    </div>
+  </template>
+</sonic-code>
+
+## 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` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Label content (text, links) |
+| `description` | Helper text under the label |
+
+Fires a `change` event on each click.

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

@@ -0,0 +1,161 @@
+# Fieldset
+
+**`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="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>
+      </sonic-form-layout>
+    </sonic-fieldset>
+  </template>
+</sonic-code>
+
+## Variant
+
+With no `variant`, the fieldset is `default` (bordered). `ghost` and `shadow` hide the border; `shadow` adds `--sc-shadow-lg`.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-fieldset variant="default">
+        <sonic-legend label="Default"></sonic-legend>
+        <sonic-input label="Field" name="a"></sonic-input>
+      </sonic-fieldset>
+      <sonic-fieldset variant="ghost">
+        <sonic-legend label="Ghost"></sonic-legend>
+        <sonic-input label="Field" name="b"></sonic-input>
+      </sonic-fieldset>
+      <sonic-fieldset variant="shadow">
+        <sonic-legend label="Shadow"></sonic-legend>
+        <sonic-input label="Field" name="c"></sonic-input>
+      </sonic-fieldset>
+    </div>
+  </template>
+</sonic-code>
+
+## Tight
+
+`tight` removes horizontal padding, side borders and rounding, for a flat strip inside a parent.
+
+<sonic-code>
+  <template>
+    <sonic-fieldset tight variant="ghost">
+      <sonic-legend label="Tight fieldset"></sonic-legend>
+      <sonic-input label="Field" name="tight"></sonic-input>
+    </sonic-fieldset>
+  </template>
+</sonic-code>
+
+## Legend
+
+`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>
+    <div class="grid gap-4">
+      <sonic-fieldset>
+        <sonic-legend label="Attributes" description="Short description via attributes"></sonic-legend>
+        <sonic-input label="Field" name="attr"></sonic-input>
+      </sonic-fieldset>
+      <sonic-fieldset>
+        <sonic-legend iconLibrary="iconoir" iconName="pin-alt">
+          Custom title in the default slot
+          <sonic-legend-description>Description via sonic-legend-description</sonic-legend-description>
+        </sonic-legend>
+        <sonic-input label="Field" name="slot"></sonic-input>
+      </sonic-fieldset>
+    </div>
+  </template>
+</sonic-code>
+
+## Shorthand legend
+
+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="Crew profile"
+      description="Basic crew member fields"
+      iconLibrary="iconoir"
+      iconName="user"
+    >
+      <sonic-input label="Display name" name="display_name"></sonic-input>
+    </sonic-fieldset>
+  </template>
+</sonic-code>
+
+## Legend actions
+
+`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="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>
+          </sonic-button>
+          <sonic-menu slot="content" minWidth="12rem">
+            <sonic-menu-item>Legal notice</sonic-menu-item>
+            <sonic-menu-item>Terms of use</sonic-menu-item>
+          </sonic-menu>
+        </sonic-pop>
+      </sonic-legend>
+      <sonic-form-layout>
+        <sonic-input autocomplete="family-name" label="Last name" name="last_name"></sonic-input>
+        <sonic-input autocomplete="given-name" label="First name" name="first_name"></sonic-input>
+      </sonic-form-layout>
+    </sonic-fieldset>
+  </template>
+</sonic-code>
+
+<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
+
+### `sonic-fieldset`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `variant` | `default` · `ghost` · `shadow` (default `default`) | Border and shadow treatment |
+| `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)* | Optional `sonic-legend`, then the grouped fields |
+
+### `sonic-legend`
+
+| Attribute | Values | 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)* | Custom title and `sonic-legend-description` |
+| `suffix` | Trailing actions (menus, icon buttons) |
+
+### `sonic-legend-description`
+
+No attributes. The default slot holds the muted line under the legend title.

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

@@ -0,0 +1,98 @@
+# Form actions
+
+**`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.
+
+<sonic-code>
+  <template>
+    <form>
+      <sonic-form-layout>
+        <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> 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>
+    </form>
+  </template>
+</sonic-code>
+
+## Justify
+
+`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>
+    <form>
+      <sonic-form-layout>
+        <sonic-input label="First name"></sonic-input>
+        <sonic-input label="Last name"></sonic-input>
+        <sonic-form-actions justify="flex-end">
+          <sonic-button type="success"><sonic-icon name="check" library="iconoir"></sonic-icon> Submit</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>
+    </form>
+  </template>
+</sonic-code>
+
+## Direction
+
+`direction` is the CSS `flex-direction` (default `row`). `row-reverse` swaps the visual order but keeps the DOM and focus order.
+
+<sonic-code>
+  <template>
+    <form>
+      <sonic-form-layout>
+        <sonic-input label="First name"></sonic-input>
+        <sonic-input label="Last name"></sonic-input>
+        <sonic-form-actions direction="row-reverse">
+          <sonic-button type="success"><sonic-icon name="check" library="iconoir"></sonic-icon> Submit</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>
+    </form>
+  </template>
+</sonic-code>
+
+## Mixed controls
+
+Any content can be slotted, such as a vertical `sonic-divider`. The default `alignItems` (`center`) keeps items of different heights aligned.
+
+<sonic-code>
+  <template>
+    <form>
+      <sonic-form-layout>
+        <sonic-input label="First name"></sonic-input>
+        <sonic-input label="Last name"></sonic-input>
+        <sonic-form-actions justify="center">
+          <sonic-button type="info" minWidth="12rem">
+            <sonic-icon name="nav-arrow-left" library="iconoir" slot="prefix"></sonic-icon>
+            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>
+            Next step
+          </sonic-button>
+        </sonic-form-actions>
+      </sonic-form-layout>
+    </form>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `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 controls |

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

@@ -0,0 +1,109 @@
+# Form layout
+
+**`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
+
+<sonic-code>
+  <template>
+    <form>
+      <sonic-form-layout>
+        <sonic-input autocomplete="family-name" label="Last name" name="last_name"></sonic-input>
+        <sonic-input autocomplete="given-name" label="First name" name="first_name"></sonic-input>
+        <sonic-select autocomplete="sex" label="Gender" name="gender">
+          <option value="" selected="selected">— Select —</option>
+          <option value="prefer-not">Prefer not to say</option>
+          <option value="male">Male</option>
+          <option value="female">Female</option>
+        </sonic-select>
+        <sonic-input autocomplete="bday" label="Date of birth" name="birth_date" type="date"></sonic-input>
+        <sonic-divider></sonic-divider>
+        <sonic-input autocomplete="email" label="Email" name="email" type="email"></sonic-input>
+        <sonic-input
+          autocomplete="email"
+          label="Confirm email"
+          name="email_confirmation"
+          type="email"
+        ></sonic-input>
+        <sonic-input autocomplete="new-password" label="Password" name="password" type="password"></sonic-input>
+        <sonic-input
+          autocomplete="new-password"
+          label="Confirm password"
+          name="password_confirmation"
+          type="password"
+        ></sonic-input>
+        <sonic-divider></sonic-divider>
+        <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">Confirm passenger</sonic-button>
+        </sonic-form-actions>
+      </sonic-form-layout>
+    </form>
+  </template>
+</sonic-code>
+
+## Responsive columns
+
+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">
+      <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</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>
+    </div>
+  </template>
+</sonic-code>
+
+## Full-width children
+
+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>
+    <sonic-form-layout>
+      <sonic-input label="Subject" name="subject"></sonic-input>
+      <sonic-textarea label="Details" rows="4"></sonic-textarea>
+      <sonic-form-actions>
+        <sonic-button type="primary">Send</sonic-button>
+      </sonic-form-actions>
+    </sonic-form-layout>
+  </template>
+</sonic-code>
+
+## Custom column wrapper
+
+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="From" name="from" placeholder="CDG"></sonic-input>
+      <div class="form-item-container">
+        <sonic-input label="To" name="to" placeholder="JFK"></sonic-input>
+      </div>
+    </sonic-form-layout>
+  </template>
+</sonic-code>
+
+## API reference
+
+No attributes.
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Fields and blocks in visual order; short fields and `form-item-container` share rows, everything else spans the full width |