@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

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

@@ -1,10 +1,10 @@
 # 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.
+**`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`.
 
 ## Basic example
 
-With no attributes, actions align to the start of the row.
+With no attributes, actions align to the **start** of the row (typical for left-to-right forms).
 
 <sonic-code>
   <template>
@@ -13,7 +13,7 @@ With no attributes, actions align to the start of the row.
         <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="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>
@@ -21,9 +21,9 @@ With no attributes, actions align to the start of the row.
   </template>
 </sonic-code>
 
-## Justify
+## Justify content
 
-`justify` is the CSS `justify-content` of the row (default `flex-start`). Use `flex-end` for dialog-style footers or `center` for toolbars.
+**`justify`** maps to CSS **`justify-content`**. Use **`flex-end`** for dialog-style footers or **`center`** for balanced toolbars.
 
 <sonic-code>
   <template>
@@ -40,9 +40,9 @@ With no attributes, actions align to the start of the row.
   </template>
 </sonic-code>
 
-## Direction
+## Flex direction
 
-`direction` is the CSS `flex-direction` (default `row`). `row-reverse` swaps the visual order but keeps the DOM and focus order.
+**`direction`** maps to **`flex-direction`**. **`row-reverse`** swaps visual order while keeping DOM order (focus order unchanged).
 
 <sonic-code>
   <template>
@@ -61,7 +61,7 @@ With no attributes, actions align to the start of the row.
 
 ## Mixed controls
 
-Any content can be slotted, such as a vertical `sonic-divider`. The default `alignItems` (`center`) keeps items of different heights aligned.
+Combine **`sonic-button`** with **`sonic-divider vertical`** or other slotted content. Default **`alignItems`** `center` keeps unlike heights aligned on the cross axis.
 
 <sonic-code>
   <template>
@@ -72,12 +72,12 @@ Any content can be slotted, such as a vertical `sonic-divider`. The default `ali
         <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
+            Left seats
           </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
+            Right seats
           </sonic-button>
         </sonic-form-actions>
       </sonic-form-layout>
@@ -89,10 +89,12 @@ Any content can be slotted, such as a vertical `sonic-divider`. The default `ali
 
 | 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 |
+| `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`**.
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Footer controls |
+| *(default)* | Footer actions (**`sonic-button`** and related controls) |

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

@@ -1,9 +1,11 @@
 # 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.
+**`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.
 
 ## 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>
@@ -33,15 +35,15 @@
           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-textarea label="Message" rows="5"></sonic-textarea>
+        <sonic-switch>Enable optional feature</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-button type="success">Submit</sonic-button>
         </sonic-form-actions>
       </sonic-form-layout>
     </form>
@@ -50,18 +52,24 @@
 
 ## 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.
+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.
 
 <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>
+    <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>
       <sonic-form-layout>
-        <sonic-divider align="left">Wide host</sonic-divider>
+      <sonic-divider align="left">Wide host (two columns for inputs)</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>
@@ -69,9 +77,11 @@ The column count depends on the host width, not the viewport: two columns above
   </template>
 </sonic-code>
 
-## Full-width children
+## 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.
 
-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.
+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.
 
 <sonic-code>
   <template>
@@ -87,14 +97,14 @@ Any child that is not a short field spans the full row: `sonic-textarea` · `son
 
 ## 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.
+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.
 
 <sonic-code>
   <template>
     <sonic-form-layout>
-      <sonic-input label="From" name="from" placeholder="CDG"></sonic-input>
+      <sonic-input label="City" name="city"></sonic-input>
       <div class="form-item-container">
-        <sonic-input label="To" name="to" placeholder="JFK"></sonic-input>
+        <sonic-input label="Postal code" name="postal_code"></sonic-input>
       </div>
     </sonic-form-layout>
   </template>
@@ -102,8 +112,8 @@ Add the class `form-item-container` to a wrapper element to keep it in the two-c
 
 ## API reference
 
-No attributes.
+No public attributes — layout follows slotted children and host width.
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Fields and blocks in visual order; short fields and `form-item-container` share rows, everything else spans the full width |
+| *(default)* | Form fields and blocks in visual order; column vs full-width rules apply per slotted tag or **`form-item-container`** class |

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

@@ -1,142 +1,142 @@
 # Input
 
-**`sonic-input`** wraps a native `<input>` with a label, a description, prefix and suffix slots and Concorde sizes. Native attributes (`type`, `placeholder`, `pattern`, `min`, `max`, …) are passed through. Bind the value to a store with **`formDataProvider`** and **`name`**, set on the field or on an ancestor.
-
-## Basic example
+<sonic-button type="info" size="sm" target="_blank" href="https://www.w3schools.com/tags/tag_input.asp#midcontentadcontainer">
+  <sonic-icon library="iconoir" name="open-new-window" slot="prefix" ></sonic-icon>
+  Native attributes list
+</sonic-button>
 
+## Label
 <sonic-code>
   <template>
-    <sonic-input label="Name" placeholder="Ada Lindqvist" description="As it appears on your passport."></sonic-input>
+  <sonic-input label="Label"></sonic-input>
   </template>
 </sonic-code>
 
-## Type
+## Placeholder
+<sonic-code>
+  <template>
+  <sonic-input placeholder="placeholder"></sonic-input>
+  </template>
+</sonic-code>
 
-With no `type`, the input is `text`. Text-like types (`email`, `password`, `date`, `number`, `color`, `search`, …) are supported; `radio`, `checkbox` and `range` have dedicated components. `password` adds a visibility toggle.
+## Value
+<sonic-code>
+  <template>
+  <sonic-input value="value"></sonic-input>
+  </template>
+</sonic-code>
 
+## Required
 <sonic-code>
   <template>
-    <div class="grid gap-3">
-      <sonic-input type="text" label="Text"></sonic-input>
-      <sonic-input type="email" label="Email" placeholder="ada@example.com"></sonic-input>
-      <sonic-input type="password" label="Password"></sonic-input>
-      <sonic-input type="date" label="Date"></sonic-input>
-      <sonic-input type="number" label="Number"></sonic-input>
-      <sonic-input type="color" label="Color" value="#ffcc00"></sonic-input>
-    </div>
+  <sonic-input required  type="email" placeholder="you@email.com" label="Feedback on blur"></sonic-input>
   </template>
 </sonic-code>
 
-## Size and status
+## Description
+<sonic-code>
+  <template>
+  <sonic-input description="Description goes here" ></sonic-input>
+  </template>
+</sonic-code>
 
-With no `size`, the input uses the base scale. `status` colors the field; it defaults to `default`.
+## Type
+<sonic-button size="2xs" type="info" target="_blank" href="https://www.w3schools.com/html/html_form_input_types.asp">Liste des types</sonic-button>
 
 <sonic-code>
   <template>
-    <div class="grid gap-3">
-      <sonic-input size="2xs" value="2xs"></sonic-input>
-      <sonic-input size="xs" value="xs"></sonic-input>
-      <sonic-input size="sm" value="sm"></sonic-input>
-      <sonic-input value="default"></sonic-input>
-      <sonic-input size="lg" value="lg"></sonic-input>
-      <sonic-input size="xl" value="xl"></sonic-input>
-      <sonic-input size="2xl" value="2xl"></sonic-input>
-      <sonic-input status="success" value="success"></sonic-input>
-      <sonic-input status="error" value="error"></sonic-input>
-      <sonic-input status="warning" value="warning"></sonic-input>
-      <sonic-input status="info" value="info"></sonic-input>
-    </div>
+  <div class="grid gap-3">
+    <sonic-input type="text" label="Text">Text</sonic-input>
+    <sonic-input type="email" label="Email" placeholder="plop@kiki.com"></sonic-input>
+    <sonic-input type="password" label="Password"></sonic-input>
+    <sonic-input type="date" label="Date"></sonic-input>
+    <sonic-input type="number" label="Number"></sonic-input>
+    <sonic-input type="color" label="Color" value="#ffff00"></sonic-input>
+  </div>
   </template>
 </sonic-code>
 
-## Validation
+## Size
+<sonic-code>
+  <template>
+  <div class="grid gap-3">
+    <sonic-input size="2xs" value="2xs"></sonic-input>
+    <sonic-input size="xs" value="xs"></sonic-input>
+    <sonic-input size="sm" value="sm"></sonic-input>
+    <sonic-input size="md" value="md"></sonic-input>
+    <sonic-input value="default"></sonic-input>
+    <sonic-input size="lg" value="lg"></sonic-input>
+    <sonic-input size="xl" value="xl"></sonic-input>
+    <sonic-input size="2xl" value="2xl"></sonic-input>
+  </div>
+  </template>
+</sonic-code>
 
-`required`, `pattern`, `minlength` and the native type rules are checked by the browser. Feedback styles apply once the field is `touched` (after blur).
+## List
+<sonic-alert status="error" label="Non fonctionnel" class="mb-4"></sonic-alert>
 
 <sonic-code>
   <template>
-    <sonic-input required type="email" label="Email" placeholder="ada@example.com"></sonic-input>
+  <sonic-input list="browsers"></sonic-input>
+  <datalist id="browsers">
+    <option value="Internet Explorer">
+    <option value="Firefox">
+    <option value="Google Chrome">
+    <option value="Opera">
+    <option value="Safari">
+  </datalist>
   </template>
 </sonic-code>
 
-## Prefix and suffix
-
-Slotted content sits outside the field by default. Set `inlineContent` to draw it inside; clicking it then focuses the input unless `disableInlineContentFocus` is set.
+## Prefix & suffix
 
 <sonic-code>
   <template>
-    <div class="grid grid-cols-2 gap-3">
-      <sonic-input type="search" label="Search" placeholder="Search flights">
-        <sonic-icon library="iconoir" name="search" slot="prefix"></sonic-icon>
-      </sonic-input>
-      <sonic-input inlineContent type="number" label="Checked bags" placeholder="0">
-        <sonic-badge slot="suffix" type="danger" size="sm">4 max</sonic-badge>
-      </sonic-input>
-    </div>
+  <div class="grid grid-cols-2 gap-3">
+    <sonic-input type="search" label="Search" placeholder="Search plane">
+      <sonic-icon library="iconoir" name="search" slot="prefix"></sonic-icon>
+    </sonic-input>
+    <sonic-input type="number" label="Amount" placeholder="0">
+      <sonic-icon library="iconoir" name="euro" slot="suffix"></sonic-icon>
+    </sonic-input>
+  </div>
   </template>
 </sonic-code>
 
-## Form data
-
-Fields sharing the same `formDataProvider` and `name` stay in sync. The attribute is looked up on ancestors, so set it once on a wrapper.
+## InlineContent
 
 <sonic-code>
   <template>
-    <div formDataProvider="inputDemoForm" class="grid grid-cols-2 gap-3">
-      <sonic-input name="city" label="City" value="Lisbon"></sonic-input>
-      <sonic-input name="city" label="Same field"></sonic-input>
-    </div>
+  <div class="grid grid-cols-2 gap-3">
+    <sonic-input inlineContent type="search" label="Search icon in input" placeholder="Search plane">
+      <sonic-icon library="iconoir" name="search" slot="prefix"></sonic-icon>
+    </sonic-input>
+    <sonic-input inlineContent type="number" label="Number of seats" placeholder="0">
+      <div slot="suffix" class="flex gap-2 items-center">
+        <sonic-badge type="danger" size="sm">4 max</sonic-badge>
+        <sonic-icon library="iconoir" name="euro" ></sonic-icon>
+      </div>
+    </sonic-input>
+  </div>
   </template>
 </sonic-code>
 
-`sameValueAs` sets `pattern` to the value of another field in the same store, for confirmation fields.
+
+
+## Example of use — search + queue
+
+Filter with **`formDataProvider`** + **`name="contains"`** (mock API: substring on joke text). Caption and rows via Lit (`@subscribe`, `.items` on `sonic-queue`):
+
+<docs-lit-demo for="docs-joke-search-demo"></docs-lit-demo>
+
 
 <sonic-code>
   <template>
-    <div formDataProvider="inputDemoPassword" class="grid grid-cols-2 gap-3">
-      <sonic-input type="password" name="password" label="Password"></sonic-input>
-      <sonic-input type="password" name="confirm" sameValueAs="password" label="Confirm password"></sonic-input>
-    </div>
+    <sonic-input type="search"  placeholder="Search plane" class="inline-block">
+    </sonic-input>
+    <sonic-button type="danger" label="Amount" placeholder="0">azdazd
+    </sonic-button>
   </template>
 </sonic-code>
 
-## Filtering a list
-
-The input writes `q` to the store used as `dataFilterProvider` by a `sonic-queue`; `inputDelayMs` debounces the requests while typing. Search a city, an airport or a flight number.
-
-<docs-lit-demo for="docs-flight-search-demo"></docs-lit-demo>
-
-## API reference
-
-| Attribute | Values | Description |
-|----------|---------|-------------|
-| `type` | `text` · `email` · `password` · `number` · `date` · `search` · `color` · … (default `text`) | Native input type |
-| `size` | `2xs` … `2xl` (default: base scale) | Typography and padding |
-| `status` | `default` · `success` · `error` · `warning` · `info` | Field color |
-| `label` | string (HTML) | Label; or use the `label` slot |
-| `description` | string (HTML) | Help text under the field; or use the `description` slot |
-| `name` | string | Key in the form store (dot notation allowed) |
-| `value` | string | Initial value |
-| `formDataProvider` | string | Store id; inherited from the closest ancestor |
-| `placeholder` | string | Native placeholder |
-| `required` · `disabled` · `readonly` · `autofocus` | boolean | Native flags |
-| `pattern` · `min` · `max` · `step` · `minlength` · `maxlength` | native | Native constraints |
-| `inputmode` · `autocomplete` · `list` · `src` · `tabindex` | native | Passed to the inner `<input>` |
-| `data-aria-label` · `data-aria-labelledby` | string | Forwarded as `aria-label` and `aria-labelledby` |
-| `inlineContent` | boolean | Renders prefix and suffix inside the field (forced for `password`) |
-| `disableInlineContentFocus` | boolean | Clicking inline content does not focus the input |
-| `showPasswordToggle` | boolean | Visibility toggle (forced for `password`) |
-| `sameValueAs` | string | Name of a field whose value becomes this field's `pattern` |
-| `inputDelayMs` | number | Debounces value updates while typing |
-| `autoActive` | boolean | Sets `active` whenever the value is not empty |
-| `active` | boolean | Reflected state for styling |
-| `unsetOnDisconnect` | boolean | Clears the store value when the element is removed |
-| `forceAutoFill` | boolean | Lets properties override `type` / `label` / `description` / `name` attributes |
-
-| Slot | Description |
-|------|-------------|
-| `label` | Rich label content |
-| `description` | Rich help text |
-| `prefix` | Content before the input |
-| `suffix` | Content after the input |
-| `list` | Extra content after the description |
+<!-- <sonic-input type="password" inlineContent size="2xl"><span slot="suffix">PLOP</span></sonic-input> -->

package/docs/src/core/components/ui/form/input-autocomplete/input-autocomplete.md

@@ -0,0 +1,29 @@
+# Input-autocomplete
+
+Champ formulaire + suggestions via [queue](#core/components/functional/queue/queue.md/queue). Valeur via `formDataProvider` + `name` ; la recherche filtre la queue (store interne).
+
+Rendu des lignes : propriété **`.items`** (callback Lit) — voir les démos ci-dessous. Mock : `serviceURL="/docs-mock-api/geo/"`.
+
+## Simple
+
+`name` = paramètre de recherche = valeur formulaire.
+
+<docs-lit-demo for="docs-input-autocomplete-basic-demo"></docs-lit-demo>
+
+## Valeur ≠ paramètre de recherche
+
+Recherche sur `nom`, valeur formulaire = `code`. Préremplissage via `value`.
+
+<docs-lit-demo for="docs-input-autocomplete-code-demo"></docs-lit-demo>
+
+## Mode select
+
+À la fermeture du pop, seule une valeur de la liste (ou vide) est conservée.
+
+<docs-lit-demo for="docs-input-autocomplete-select-demo"></docs-lit-demo>
+
+## Navigation clavier
+
+`data-keyboard-nav` sur le champ et les items (flèches haut / bas).
+
+<docs-lit-demo for="docs-input-autocomplete-keyboard-demo"></docs-lit-demo>

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

@@ -1,78 +1,57 @@
 # Radio
 
-**`sonic-radio`** is a round [Checkbox](/core/components/ui/form/checkbox) in radio mode: radios sharing a `name` under one **`formDataProvider`** store a single value, and a checked radio cannot be unchecked by a click. Label goes in the default slot or `label`, helper text in the `description` slot.
-
-## Basic example
-
+## Size
 <sonic-code>
   <template>
-    <div formDataProvider="radio-basic-demo" class="grid gap-2">
-      <sonic-radio name="seat" value="window" checked>Window</sonic-radio>
-      <sonic-radio name="seat" value="aisle">Aisle</sonic-radio>
-      <div>Seat: <sonic-value dataProvider="radio-basic-demo" key="seat"></sonic-value></div>
+    <div class="grid gap-2" formDataProvider="radioSizeExemple">
+      <sonic-radio name="size" value="2xs" size="2xs">2xs radio</sonic-radio>
+      <sonic-radio name="size" value="xs" size="xs">xs radio</sonic-radio>
+      <sonic-radio name="size" value="sm" size="sm">sm radio</sonic-radio>
+      <sonic-radio name="size" value="default" >default radio</sonic-radio>
+      <sonic-radio name="size" value="lg" size="lg">lg radio</sonic-radio>
+      <sonic-radio name="size" value="xl" size="xl">xl radio</sonic-radio>
+      <sonic-radio name="size" value="2xl" size="2xl">2xl radio</sonic-radio>
     </div>
   </template>
 </sonic-code>
 
-## Size
-
-With no `size`, the radio follows `md` (1rem).
-
+## Checked
 <sonic-code>
   <template>
-    <div class="grid gap-2" formDataProvider="radio-size-demo">
-      <sonic-radio name="size" value="2xs" size="2xs">2xs</sonic-radio>
-      <sonic-radio name="size" value="xs" size="xs">xs</sonic-radio>
-      <sonic-radio name="size" value="sm" size="sm">sm</sonic-radio>
-      <sonic-radio name="size" value="md">Default</sonic-radio>
-      <sonic-radio name="size" value="lg" size="lg">lg</sonic-radio>
-      <sonic-radio name="size" value="xl" size="xl">xl</sonic-radio>
-      <sonic-radio name="size" value="2xl" size="2xl">2xl</sonic-radio>
-    </div>
+  <sonic-radio checked
+    >Already checked radio
+  </sonic-radio>
   </template>
 </sonic-code>
 
-## Checked and disabled
-
-`checked` sets the initial state. `disabled` blocks interaction and dims the control.
-
+## Disabled
 <sonic-code>
   <template>
-    <div class="grid gap-2">
-      <sonic-radio name="state-checked" value="a" checked>Checked</sonic-radio>
-      <sonic-radio name="state-disabled" value="b" disabled>Disabled</sonic-radio>
-      <sonic-radio name="state-both" value="c" disabled checked>Disabled and checked</sonic-radio>
-      <sonic-radio name="state-link" value="d">I accept the <sonic-link href="#" class="underline">terms</sonic-link></sonic-radio>
-    </div>
+  <sonic-radio disabled
+    >Disabled radio
+  </sonic-radio>
   </template>
 </sonic-code>
 
-## Filtering a list
-
-The radio group writes one `status` value to the store used as `dataFilterProvider` by a `sonic-queue`. See [Checkbox](/core/components/ui/form/checkbox) for the multi-value version.
+## Disabled and checked
+<sonic-code>
+  <template>
+  <sonic-radio disabled checked
+    >Disabled but already checked radio
+  </sonic-radio>
+  </template>
+</sonic-code>
 
-<docs-lit-demo for="docs-flight-status-radio-demo"></docs-lit-demo>
+## radio with link
+<sonic-code>
+  <template>
+  <sonic-radio name="link" value="link">radio with <sonic-link href="#" class="underline text-info">link</sonic-link>
+  </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 |
-| `unsetOnDisconnect` | boolean | Removes the value from the data when the element is removed |
-| `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 control size |
-| `disabled` | boolean | Blocks interaction |
-| `required` | boolean | Native validation on form submit |
-| `autofocus` | boolean | Focuses the input on load |
-| `data-aria-label` · `data-aria-labelledby` | string | Forwarded to the inner input as `aria-label` / `aria-labelledby` |
+## Example of use — blacklist + queue
 
-| Slot | Description |
-|------|-------------|
-| *(default)* | Label content (text, links) |
-| `description` | Helper text under the label |
+Same mock filter as [Checkbox](#core/components/ui/form/checkbox/checkbox.md/checkbox) (`blacklistFlags` query param). Radio sends **one** flag at a time.
 
-Fires a `change` event on each click.
+<docs-lit-demo for="docs-joke-blacklist-radio-demo"></docs-lit-demo>