@supersoniks/concorde 5.1.0 → 5.1.2

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

@@ -1,97 +1,215 @@
 # Card
 
+Cards **group related content** on a padded surface with radius, theme **`type`** colors, and elevation. Default **`shadow`** is `lg`. Compose **`sonic-card-header`** / **`sonic-card-main`** / **`sonic-card-footer`**, or place any markup in the default slot.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-card class="max-w-sm">
+      <p class="m-0">CN 001 · CDG → JFK · On time.</p>
+    </sonic-card>
+  </template>
+</sonic-code>
+
 ## Type
+
+Default **`type`** is `base`. **`default`** and **`light`** share the same surface tokens.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-3">
+      <sonic-card type="base" class="min-w-[8rem]">Base</sonic-card>
+      <sonic-card type="light" class="min-w-[8rem]">Light</sonic-card>
+      <sonic-card type="default" class="min-w-[8rem]">Default</sonic-card>
+      <sonic-card type="primary" class="min-w-[8rem]">Primary</sonic-card>
+      <sonic-card type="info" class="min-w-[8rem]">Info</sonic-card>
+      <sonic-card type="success" class="min-w-[8rem]">Success</sonic-card>
+      <sonic-card type="warning" class="min-w-[8rem]">Warning</sonic-card>
+      <sonic-card type="danger" class="min-w-[8rem]">Danger</sonic-card>
+      <sonic-card type="neutral" class="min-w-[8rem]">Neutral</sonic-card>
+      <sonic-card type="invert" class="min-w-[8rem]">Invert</sonic-card>
+    </div>
+  </template>
+</sonic-code>
+
+## Shadow
+
+Set **`shadow`** to control elevation. Default is `lg`.
+
 <sonic-code>
   <template>
-  <div class="grid grid-cols-3 gap-3">
-    <sonic-card type="base">Base</sonic-card>
-    <sonic-card type="light">Light</sonic-card>
-    <sonic-card type="primary">Primary</sonic-card>
-    <sonic-card type="warning">Warning</sonic-card>
-    <sonic-card type="danger">Danger</sonic-card>
-    <sonic-card type="success">Success</sonic-card>
-    <sonic-card type="info">Info</sonic-card>
-    <sonic-card type="neutral">Neutral</sonic-card>
-    <sonic-card type="invert">Invert</sonic-card>
-  </div>
+    <div class="grid gap-4 sm:grid-cols-2 max-w-2xl">
+      <sonic-card shadow="none" class="min-h-[5rem] flex items-center justify-center">None</sonic-card>
+      <sonic-card shadow="sm" class="min-h-[5rem] flex items-center justify-center">Small</sonic-card>
+      <sonic-card shadow="md" class="min-h-[5rem] flex items-center justify-center">Medium</sonic-card>
+      <sonic-card shadow="lg" class="min-h-[5rem] flex items-center justify-center">Large</sonic-card>
+    </div>
   </template>
 </sonic-code>
 
 ## Header
+
+Quick titles with **`label`** and **`description`**, or full control through the default slot. **`slot="suffix"`** aligns badges or actions on the right; suffix content does not shrink when the title wraps.
+
+`label` and `description` accept HTML (rendered as markup). Prefer plain text when possible; use **`sonic-card-header-description`** or the default slot for structured content.
+
 <sonic-code>
   <template>
-  <div class="grid grid-cols-1 gap-3">
-    <sonic-card >
-      <sonic-card-header label="Header simple, titre géré via l'attribut : label" description="Description via l'attribut : description">
-      </sonic-card-header>
-    </sonic-card>
-    <sonic-card type="neutral">
-      <sonic-card-header label="Header composé">
-        <sonic-card-header-description>Description rendu via le composant : "sonic-card-header-description"</sonic-card-header-description>
-        <div  slot="suffix" class="flex">
-          Suffix
-        </div>
-      </sonic-card-header>
-    </sonic-card>
-    <sonic-card type="invert">
-      <sonic-card-header>
-        <div>Header custom</div>
-        <div class="text-lg text-danger">Tout le contenu excepté l'icône ✈ passe par le slot du header</div>
-        <span slot="suffix" >✈</span>
-      </sonic-card-header>
-    </sonic-card>
-  </div>
+    <div class="grid gap-4 max-w-xl">
+      <sonic-card>
+        <sonic-card-header
+          label="Account settings"
+          description="Manage your profile and preferences."
+        ></sonic-card-header>
+        <p class="m-0 text-sm opacity-80">Body content goes in the card slot or in <code>sonic-card-main</code>.</p>
+      </sonic-card>
+
+      <sonic-card type="neutral">
+        <sonic-card-header label="Notifications">
+          <sonic-card-header-description>
+            Choose what we email you about.
+          </sonic-card-header-description>
+          <sonic-badge slot="suffix" type="warning" size="xs">3 new</sonic-badge>
+        </sonic-card-header>
+      </sonic-card>
+
+      <sonic-card>
+        <sonic-card-header label="Team workspace" description="Shared with 12 members">
+          <sonic-button
+            slot="suffix"
+            shape="circle"
+            variant="outline"
+            size="sm"
+            type="default"
+            icon
+            data-aria-label="Workspace settings"
+          >
+            <sonic-icon library="iconoir" name="settings"></sonic-icon>
+          </sonic-button>
+        </sonic-card-header>
+      </sonic-card>
+
+      <sonic-card type="primary">
+        <sonic-card-header>
+          <div>Custom header</div>
+          <sonic-card-header-description>
+            Use the header slot when attributes are not enough.
+          </sonic-card-header-description>
+          <sonic-button slot="suffix" shape="circle" variant="ghost" size="sm" type="primary" icon>
+            <sonic-icon library="iconoir" name="nav-arrow-right"></sonic-icon>
+          </sonic-button>
+        </sonic-card-header>
+      </sonic-card>
+    </div>
   </template>
 </sonic-code>
 
 ## Main
+
+Optional wrapper for the primary content area (typography, media, forms).
+
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-main >
-      <h3>Main area</h3>
-      <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-      <iframe width="560" height="315" src="https://www.youtube.com/embed/aqz-KE-bpKQ" title="Big Buck Bunny (Blender Foundation)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-    </sonic-card-main>
-  </sonic-card>
+    <sonic-card class="max-w-xl">
+      <sonic-card-header label="Release notes" description="Version 2.4"></sonic-card-header>
+      <sonic-card-main>
+        <p class="mt-0">
+          Improved performance on large lists and fixed an issue with keyboard navigation in menus.
+        </p>
+        <sonic-divider></sonic-divider>
+        <p class="mb-0 text-sm opacity-80">See the changelog for details.</p>
+      </sonic-card-main>
+    </sonic-card>
   </template>
 </sonic-code>
 
 ## Footer
+
+Optional footer for actions, metadata, or secondary text.
+
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-footer >
-      <div >
-        <h4 class="mb-0">Footer area</h4>
-        <small>Debitis deleniti eligendi natus dolorem aufdh.</small>
-        <div>
-          🛫 ✈ ✈ ✈ ✈ ✈ 🛬
+    <sonic-card class="max-w-xl">
+      <sonic-card-header label="Confirm deletion"></sonic-card-header>
+      <sonic-card-main>
+        <p class="m-0">This project and all of its data will be removed permanently.</p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <sonic-divider></sonic-divider>
+        <div class="flex flex-wrap gap-2 justify-end">
+          <sonic-button variant="ghost" size="sm">Cancel</sonic-button>
+          <sonic-button type="danger" size="sm">Delete</sonic-button>
         </div>
-      </div>
-    </sonic-card-footer>
-  </sonic-card>
+      </sonic-card-footer>
+    </sonic-card>
   </template>
 </sonic-code>
 
+## Full example
+
+Header, media, body, and footer together.
 
-## Example of use
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-header label="Header" description="Header description">
-      <sonic-icon library="iconoir" name="nav-arrow-right" slot="suffix" ></sonic-icon>
-    </sonic-card-header>
-    <sonic-card-main >
-      <sonic-image rounded ratio="11/4" src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg">
-      </sonic-image>
-      <p><b>Main</b> - Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-    </sonic-card-main>
-    <sonic-card-footer>
-      <div>
-        <i>Footer</i> - Amet consectetur adipisicing
-      </div>
-    </sonic-card-footer>
-  </sonic-card>
+    <sonic-card class="max-w-md">
+      <sonic-card-header label="Featured route" description="CDG → JFK">
+        <sonic-icon slot="suffix" library="iconoir" name="airplane" aria-hidden="true"></sonic-icon>
+      </sonic-card-header>
+      <sonic-card-main>
+        <sonic-image
+          rounded
+          ratio="16/9"
+          src="img/concorde/plane_04.jpg"
+          alt="Concorde on the apron under a blue sky"
+        ></sonic-image>
+        <p class="mb-0">
+          Nonstop at Mach 2.04, with flexible dates.
+        </p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <div class="flex items-center justify-between gap-3 flex-wrap">
+          <span class="text-sm font-semibold">Cabin class: Business</span>
+          <sonic-button type="primary" size="sm">Book</sonic-button>
+        </div>
+      </sonic-card-footer>
+    </sonic-card>
   </template>
 </sonic-code>
+
+## API reference
+
+### `sonic-card`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `base` (default) · `light` · `invert` · `default` · `primary` · `warning` · `danger` · `success` · `info` · `neutral` | Semantic background and text (`default` and `light` share the same surface) |
+| `shadow` | `none` · `sm` · `md` · `lg` (default `lg`) | Elevation on the card surface |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Free-form content (header, main, footer, or direct markup) |
+
+### `sonic-card-header`
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `label` | HTML | Title (rendered as markup) |
+| `description` | HTML | Subtitle below the title |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Custom title / description when attributes are not enough |
+| `suffix` | Actions or badges aligned on the right (does not shrink) |
+
+### `sonic-card-header-description`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Subtitle text; styled below the title when slotted in **`sonic-card-header`** |
+
+### `sonic-card-main` · `sonic-card-footer`
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Primary content (`main`) or actions / metadata (`footer`) |

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

@@ -1,35 +1,126 @@
 # Divider
 
-## Default
+**`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>
+    <sonic-divider></sonic-divider>
   </template>
 </sonic-code>
 
-## Align
+## 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>
-  <sonic-divider label="Default centered label"></sonic-divider>
-  <sonic-divider label="Right" align="right"></sonic-divider>
-  <sonic-divider label="Center" align="center"></sonic-divider>
-  <sonic-divider label="Left" align="left"></sonic-divider>
+    <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>
-  <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>
+    <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>
 
-## Custom
+## Line style
+
+**`lineStyle`** sets the stroke of the rule (`solid` · `dashed` · `dotted`). In HTML use the reflected attribute **`linestyle`** (case-insensitive).
+
 <sonic-code>
   <template>
-  <sonic-divider><span class="mr-2">Lorem ipsum dolor sit amet</span><sonic-badge type="danger">+25</sonic-badge></sonic-divider>
+    <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

@@ -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.