@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

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

@@ -0,0 +1,183 @@
+# Button
+
+## Type
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button>Default</sonic-button>
+      <sonic-button type="primary">Primary</sonic-button>
+      <sonic-button type="neutral">Neutral</sonic-button>
+      <sonic-button type="warning">Warning</sonic-button>
+      <sonic-button type="info">Info</sonic-button>
+      <sonic-button type="success">Success</sonic-button>
+      <sonic-button type="danger">Danger</sonic-button>
+      <sonic-button type="custom" style="--sc-btn-custom-color: #fde68a; --sc-btn-custom-bg: #5b21b6">Custom</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Outline
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button variant="outline">Default</sonic-button>
+      <sonic-button variant="outline" type="primary">Primary</sonic-button>
+      <sonic-button variant="outline" type="neutral">Neutral</sonic-button>
+      <sonic-button variant="outline" type="warning">Warning</sonic-button>
+      <sonic-button variant="outline" type="info">Info</sonic-button>
+      <sonic-button variant="outline" type="success">Success</sonic-button>
+      <sonic-button variant="outline" type="danger">Danger</sonic-button>
+      <sonic-button variant="outline" type="custom" style="--sc-btn-custom-bg: #5b21b6">Custom</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Variant
+<sonic-code>
+  <template>
+    <sonic-button variant="default">Default</sonic-button>
+    <sonic-button variant="outline">Outline</sonic-button>
+    <sonic-button variant="ghost">Ghost</sonic-button>
+    <sonic-button variant="link">Link</sonic-button>
+    <sonic-button variant="unstyled">Unstyled</sonic-button>
+  </template>
+</sonic-code>
+
+## Size
+<sonic-code>
+  <template>
+    <sonic-button size="2xs">2Xs button</sonic-button>
+    <sonic-button size="xs">Xs button</sonic-button>
+    <sonic-button size="sm">Sm button</sonic-button>
+    <sonic-button size="md">Md button</sonic-button>
+    <sonic-button>Default button</sonic-button>
+    <sonic-button size="lg">Lg button</sonic-button>
+    <sonic-button size="xl">Xl button</sonic-button>
+    <sonic-button size="2xl">2Xl button</sonic-button>
+  </template>
+</sonic-code>
+
+## Shape
+<sonic-code>
+  <template>
+    <sonic-button shape="circle"> 😂 </sonic-button>
+    <sonic-button shape="square"> 🚀 </sonic-button>
+  </template>
+</sonic-code>
+
+## Loading
+The length of the button depends on the size of its content
+<sonic-code>
+  <template>
+    <sonic-button loading></sonic-button>
+    <sonic-button loading>Loading button</sonic-button>
+    <sonic-button loading><span slot="prefix">🚀</span>Loading with prefix<span slot="suffix">😂</span></sonic-button>
+  </template>
+</sonic-code>
+
+## Swap
+<sonic-code>
+  <template>
+    <sonic-button formDataProvider="button_swap_example" name="youpi" value="youpla" type="primary" shape="circle" variant="outline" class="mr-4">
+      <sonic-icon library="iconoir" swap="on" name="eye-empty"></sonic-icon>
+      <sonic-icon library="iconoir" swap="off" name="eye-off"></sonic-icon>
+    </sonic-button>
+    <sonic-button formDataProvider="button_swap_example" name="youpi" value="youpla" type="primary" variant="outline">
+      <sonic-icon library="iconoir" swap="on" slot="prefix" name="eye-empty"></sonic-icon>
+      <sonic-icon library="iconoir" swap="off" slot="prefix" name="eye-off"></sonic-icon>
+      Révélez
+      <span swap="off">...</span>
+      <span swap="on">moi !</span>
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Reset
+<sonic-code>
+  <template>
+    <div formDataProvider="button-reset-demo" class="mb-2">
+      <sonic-checkbox name="aChexbox" value="AValueToSet">Set A value</sonic-checkbox><br>
+      <sonic-button reset>Reset current formDataProvider</sonic-button>
+    </div>
+      <sonic-button reset="button-reset-demo">Reset formDataProvider by name</sonic-button>
+  </template>
+</sonic-code>
+
+
+## GoBack
+<sonic-code>
+  <template>
+    <sonic-button goBack type="primary" variant="outline"  class="mr-4">
+      <sonic-icon library="iconoir" slot="prefix" name="arrow-left"></sonic-icon>
+      Retour classique
+    </sonic-button>
+    <sonic-button goBack="http://la-billetterie.net" type="primary" variant="outline"  class="mr-4">
+      <sonic-icon library="iconoir" slot="prefix" name="arrow-left"></sonic-icon>
+      Retour url prédéfinie
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Button with icon
+<sonic-code>
+  <template>
+    <sonic-button goBack type="primary" variant="outline"  class="mr-4">
+      <sonic-icon library="iconoir" slot="prefix" name="arrow-right" ></sonic-icon>
+      Button with icon
+    </sonic-button>
+  </template>
+</sonic-code>
+
+
+## Button group
+<sonic-code>
+  <template>
+    <sonic-group label="Code promo" class="mr-4">
+      <sonic-input placeholder="Entrez votre code ici..."></sonic-input>
+      <sonic-button type="primary" shape="square">
+        <sonic-icon library="iconoir" library="iconoir" name="gift"></sonic-icon>
+      </sonic-button>
+    </sonic-group>
+    <sonic-divider size="lg"></sonic-divider>
+    <div class="text-lg mb-2">Choose a subscription</div>
+    <sonic-group formDataProvider="subscriptionData">
+      <sonic-button radio minWidth="10rem" name="subscription" value="standard" type="default"
+        >😎 Standard</sonic-button
+      >
+      <sonic-button radio minWidth="10rem" name="subscription" value="premium" type="default">⭐ Premium</sonic-button>
+      <sonic-button radio minWidth="10rem" name="subscription" value="diamond" type="default">💎 Diamond</sonic-button>
+    </sonic-group>
+  </template>
+</sonic-code>
+
+
+## Aria-label
+<sonic-code>
+  <template>
+      <sonic-button data-aria-label="Custom aria label" type="primary" >
+        Button with aria label
+      </sonic-button>
+       <sonic-button data-aria-label="Custom aria label" href="https://google.fr" type="primary" >
+        Button link with aria label
+      </sonic-button>
+  </template>
+</sonic-code>
+
+
+## Custom styles & active states with tailwind
+<sonic-code>
+  <template>
+    <div formDataProvider="subscriptionData2">
+      <sonic-button
+        class="bg-neutral-100 transition-all text-center text-lg text-neutral-400 rounded-md min-w-[8rem] [&[active]]:text-danger-content [&[active]]:min-w-[13rem] [&[active]]:bg-danger [&[active]]:font-black [&[active]]:rounded-full"
+        variant="unstyled"
+        checkable unique 
+        name="subscription"
+        value="premium"
+        type="default">
+          <span swap="off" class="inline-block py-2 px-3" >subscribe</span>
+          <span swap="on" class="inline-block py-2 px-3" >⭐ Premium</span>
+      </sonic-button>
+    </div>
+  </template>
+</sonic-code>

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

@@ -0,0 +1,71 @@
+# Captcha
+
+**`sonic-captcha`** embeds an **ALTCHA** widget and wires **`captchaToken`** / **`needsCaptchaValidation`** on the ancestor **`formDataProvider`** (or **`headersDataProvider`**). **`sonic-submit`** waits for a token before sending when validation is required. The widget loads only on **HTTPS**; on plain HTTP the host renders nothing.
+
+> Live widget calls the Supersoniks challenge service — not part of [docs mock API](#docs/_misc/docs-mock-api.md/docs-mock-api).
+
+## Basic example
+
+Wrap the form scope and place **`sonic-submit`** in the default slot so the challenge appears above the action.
+
+<sonic-code>
+  <template>
+    <sonic-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="captcha-docs-form"
+      submitResultDataProvider="captcha-docs-result"
+    >
+      <sonic-captcha formDataProvider="captcha-docs-form">
+        <sonic-input class="mb-3" name="email" type="email" label="Email" value="demo@example.com"></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Submit with captcha</sonic-button>
+        </sonic-submit>
+      </sonic-captcha>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Encrypted site key
+
+Optional **`key`** skips client-side key generation. When omitted, the component derives an encrypted key on connect (after **`generateEncryptedKey`**).
+
+<sonic-code>
+  <template>
+    <sonic-captcha formDataProvider="captcha-docs-form" key="6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t">
+      <sonic-button type="outline" disabled>Complete the challenge above to enable submit</sonic-button>
+    </sonic-captcha>
+  </template>
+</sonic-code>
+
+## Form publisher fields
+
+On connect (HTTPS only), **`needsCaptchaValidation`** is set to **`true`** and **`captchaToken`** is cleared. When the ALTCHA widget reaches **`verified`**, **`captchaToken`** is written on the form publisher and **`sonic-captcha-validate`** fires (`detail.valid` · **`detail.state`** · optional **`detail.token`** / **`detail.payload`**). **`sonic-submit`** still listens for **`request_token`** to refresh the token immediately before send.
+
+<sonic-code language="typescript">
+  <template>
+{
+  needsCaptchaValidation: true,
+  captchaKey: "…",
+  captchaToken: "…"
+}
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `formDataProvider` | publisher id | Same as ancestor form scope; reads/writes **`needsCaptchaValidation`** · **`captchaKey`** · **`captchaToken`** |
+| `key` | string | ALTCHA site key; auto-generated when empty |
+| `action` | string | Optional action name forwarded to the widget |
+| `zIndex` | number (default `9999`) | Stacking for the challenge overlay |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Form actions (typically **`sonic-submit`** and fields) rendered below the widget |
+
+| Event | Description |
+|-------|-------------|
+| `sonic-captcha-validate` | Fired when **`state`** is **`verified`** · **`error`** or **`expired`**; **`detail.valid`** is **`true`** only for **`verified`** |
+
+Related: [Submit](#core/components/functional/submit/submit.md/submit) — **`needsCaptchaValidation`** and deferred send.

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

@@ -0,0 +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">Related content on a raised surface.</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 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 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 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 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>
+      </sonic-card-footer>
+    </sonic-card>
+  </template>
+</sonic-code>
+
+## Full example
+
+Header, media, body, and footer together.
+
+<sonic-code>
+  <template>
+    <sonic-card class="max-w-md">
+      <sonic-card-header label="Featured route" description="San Francisco → New York">
+        <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="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+          alt="Airplane wing above the clouds"
+        ></sonic-image>
+        <p class="mb-0">
+          Nonstop flight with flexible dates. Prices shown include taxes and fees.
+        </p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <div class="flex items-center justify-between gap-3 flex-wrap">
+          <span class="text-sm font-semibold">From $249</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

@@ -0,0 +1,129 @@
+# 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 (HTML via the same pipeline as other form labels). **`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">Section title</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>This action cannot be undone.</div>
+        <sonic-divider label="Affected resources"></sonic-divider>
+        <ul class="m-0 pl-5 text-sm">
+          <li>Project files</li>
+          <li>Shared links</li>
+        </ul>
+      </sonic-card>
+      <sonic-card type="info">
+        <div>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` · `xs` · `sm` · `md` · `lg` · `xl` · `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 |
+
+The inner flex container exposes **`part="divider"`** for theme overrides.

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

@@ -0,0 +1,77 @@
+# Checkbox
+
+## Size
+<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>
+  </template>
+</sonic-code>
+
+## Checked
+<sonic-code>
+  <template>
+  <sonic-checkbox checked
+    >Already checked checkbox
+  </sonic-checkbox>
+  </template>
+</sonic-code>
+
+## Disabled
+<sonic-code>
+  <template>
+  <sonic-checkbox disabled
+    >Disabled checkbox
+  </sonic-checkbox>
+  </template>
+</sonic-code>
+
+## Disabled and checked
+<sonic-code>
+  <template>
+  <sonic-checkbox disabled checked
+    >Disabled but already checked checkbox
+  </sonic-checkbox>
+  </template>
+</sonic-code>
+
+## Checkbox with link
+<sonic-code>
+  <template>
+  <sonic-checkbox>Checkbox with <sonic-link href="#" class="underline text-info">link</sonic-link>
+  </template>
+</sonic-code>
+
+## Check all 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>
+      </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>
+  </template>
+</sonic-code>
+
+## Example of use — blacklist + queue
+
+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`).
+
+<docs-lit-demo for="docs-joke-blacklist-demo"></docs-lit-demo>