@supersoniks/concorde 5.0.3 → 5.0.5

package/docs/llms.txt

@@ -29,43 +29,36 @@ Full text: https://concorde.supersoniks.org/llms-full.txt
 - [Submit](https://concorde.supersoniks.org/crawl/core/components/functional/submit/submit.html) (core/components/functional/submit/submit): > Live demos: <docs-lit-demo> + src/docs/example/docs-submit-demos.ts. Use Local API demos (serviceURL="/docs-mock-api").
 - [Subscriber](https://concorde.supersoniks.org/crawl/core/components/functional/subscriber/subscriber.html) (core/components/functional/subscriber/subscriber): La mixin Subscriber permet lier un composant à un publisher.
 - [Value](https://concorde.supersoniks.org/crawl/core/components/functional/value/value.html) (core/components/functional/value/value): Simply shows a value from a data provider.
-- [Concorde](https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html) (core/components/ui/alert-messages/alert-messages): Concorde documentation: Concorde
-- [Alert](https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html) (core/components/ui/alert/alert): Inline message in the page: title (label), body (text or default slot), icon from status. For HTML or actions, use the slot instead of label / text (plain text only).
-- [Badge](https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html) (core/components/ui/badge/badge): A non-interactive pill for labels, counts, or highlights (counter, status, category). The API mirrors sonic-button (type, variant, size) without focus or click states.
+- [Alert messages](https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html) (core/components/ui/alert-messages/alert-messages): sonic-alert-messages renders a vertical stack of sonic-alert items from a messages array on a linked data provider (typical pattern: submitResultDataProvider after a form submit). Only entries with ty
+- [Alert](https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html) (core/components/ui/alert/alert): Alerts surface important feedback inline—errors, confirmations, or contextual help. Use label / text for simple copy, or the default slot for rich content (links, buttons). Set announce when the messa
+- [Badge](https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html) (core/components/ui/badge/badge): Badges are compact, non-interactive labels for status, counts, or categories. They mirror sonic-button styling (type, variant, size) without focus rings or click handling—use a button when the control
 - [Button](https://concorde.supersoniks.org/crawl/core/components/ui/button/button.html) (core/components/ui/button/button): The length of the button depends on the size of its content
-- [Captcha](https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html) (core/components/ui/captcha/captcha): Captcha: Submit with captcha
-- [Card](https://concorde.supersoniks.org/crawl/core/components/ui/card/card.html) (core/components/ui/card/card): A surface for grouped content: padding, radius, shadow, and semantic type colors via shared theme tokens. Compose sonic-card-header, sonic-card-main, and sonic-card-footer inside the card, or put any 
-- [Divider](https://concorde.supersoniks.org/crawl/core/components/ui/divider/divider.html) (core/components/ui/divider/divider): Default
-
-Align
-
-Size
-
-Custom
-
-  Lorem ipsum dolor sit amet  +25
+- [Captcha](https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html) (core/components/ui/captcha/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 vali
+- [Card](https://concorde.supersoniks.org/crawl/core/components/ui/card/card.html) (core/components/ui/card/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 marku
+- [Divider](https://concorde.supersoniks.org/crawl/core/components/ui/divider/divider.html) (core/components/ui/divider/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 
 - [Checkbox](https://concorde.supersoniks.org/crawl/core/components/ui/form/checkbox/checkbox.html) (core/components/ui/form/checkbox/checkbox): >Already checked checkbox
-- [Fieldset](https://concorde.supersoniks.org/crawl/core/components/ui/form/fieldset/fieldset.html) (core/components/ui/form/fieldset/fieldset): Default
-- [Form-actions](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-actions/form-actions.html) (core/components/ui/form/form-actions/form-actions): Left seats
-- [Form-layout](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-layout/form-layout.html) (core/components/ui/form/form-layout/form-layout): autocomplete="email"
+- [Fieldset](https://concorde.supersoniks.org/crawl/core/components/ui/form/fieldset/fieldset.html) (core/components/ui/form/fieldset/fieldset): sonic-fieldset groups related form controls with a bordered container and an accessible <fieldset> semantics layer. Put fields in the default slot; add a title with sonic-legend or the shorthand label
+- [Form actions](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-actions/form-actions.html) (core/components/ui/form/form-actions/form-actions): sonic-form-actions lays out submit / cancel and other form footer controls in a wrapping flex row with a small fixed gap. Place it inside sonic-form-layout (full-width row) or any block that should en
+- [Form layout](https://concorde.supersoniks.org/crawl/core/components/ui/form/form-layout/form-layout.html) (core/components/ui/form/form-layout/form-layout): sonic-form-layout arranges slotted form controls in a responsive CSS grid with consistent vertical spacing. Pair sonic-input · sonic-select and sonic-input-autocomplete fields side by side when the ho
 - [Input-autocomplete](https://concorde.supersoniks.org/crawl/core/components/ui/form/input-autocomplete/input-autocomplete.html) (core/components/ui/form/input-autocomplete/input-autocomplete): Champ formulaire + suggestions via queue. Valeur via formDataProvider + name ; la recherche filtre la queue (store interne).
 - [Input](https://concorde.supersoniks.org/crawl/core/components/ui/form/input/input.html) (core/components/ui/form/input/input): Native attributes list
 - [Radio](https://concorde.supersoniks.org/crawl/core/components/ui/form/radio/radio.html) (core/components/ui/form/radio/radio): >Already checked radio
 - [Select](https://concorde.supersoniks.org/crawl/core/components/ui/form/select/select.html) (core/components/ui/form/select/select): {"value":"dark", "wording":"dark (set by \"attribute\")", "selected" : "true"}, {"value":"auto", "wording":"auto"}
 - [Switch](https://concorde.supersoniks.org/crawl/core/components/ui/form/switch/switch.html) (core/components/ui/form/switch/switch): >Already checked switch
 - [Textarea](https://concorde.supersoniks.org/crawl/core/components/ui/form/textarea/textarea.html) (core/components/ui/form/textarea/textarea): Native attributes list
-- [Group](https://concorde.supersoniks.org/crawl/core/components/ui/group/group.html) (core/components/ui/group/group): Group: 😎 Standard ⭐ Premium 💎 Diamond
-- [Icon](https://concorde.supersoniks.org/crawl/core/components/ui/icon/icon.html) (core/components/ui/icon/icon): customIconDefaultPrefix="regular">
-- [Image](https://concorde.supersoniks.org/crawl/core/components/ui/image/image.html) (core/components/ui/image/image): Responsive <img> wrapper: aspect ratio, object-fit: cover, rounded corners, and optional fade-in on load. The host uses a light placeholder background (--sc-placeholder-bg) until the file is ready. De
-- [Link](https://concorde.supersoniks.org/crawl/core/components/ui/link/link.html) (core/components/ui/link/link): Link: Basic link with href attribute
-- [Loader](https://concorde.supersoniks.org/crawl/core/components/ui/loader/loader.html) (core/components/ui/loader/loader): import {Loader} from "@supersoniks/concorde/core/components/ui/loader/loader";
-- [Menu](https://concorde.supersoniks.org/crawl/core/components/ui/menu/menu.html) (core/components/ui/menu/menu): Row
-- [Concorde](https://concorde.supersoniks.org/crawl/core/components/ui/modal/modal.html) (core/components/ui/modal/modal): Concorde: Simple modal Lorem ipsum dolor sit amet +33 Donec sed vestibulum augue. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed eget quam eu mi luctus faucibus. Click don't close Confir
-- [Pop](https://concorde.supersoniks.org/crawl/core/components/ui/pop/pop.html) (core/components/ui/pop/pop): Default placement is bottom. Placement is written side-align, like sonic-tooltip: side is top, right, bottom or left, align is start, center or end. Without align, content is aligned on the start of t
-- [Progress bar](https://concorde.supersoniks.org/crawl/core/components/ui/progress/progress.html) (core/components/ui/progress/progress): Displays an indicator showing the completion progress of a task.
-- [Table](https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html) (core/components/ui/table/table): Values available : primary, info, success, warning, danger
-- [Toast](https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html) (core/components/ui/toast/toast): Afficher un toast
-- [Tooltip](https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html) (core/components/ui/tooltip/tooltip): By default, tooltip is centered next to its content
+- [Group](https://concorde.supersoniks.org/crawl/core/components/ui/group/group.html) (core/components/ui/group/group): sonic-group lays out slotted sonic-button · sonic-input and sonic-select controls in a single horizontal row with shared corner radius (first / middle / last items). Optional label and description fol
+- [Icon](https://concorde.supersoniks.org/crawl/core/components/ui/icon/icon.html) (core/components/ui/icon/icon): sonic-icon renders inline SVG icons from the bundled core set or from CDN libraries. Set name (and library / prefix when needed); scale with size. Icons inherit currentColor and are aria-hidden by def
+- [Image](https://concorde.supersoniks.org/crawl/core/components/ui/image/image.html) (core/components/ui/image/image): sonic-image wraps a responsive <img> with aspect ratio, object-fit: cover, optional rounded corners, and load transitions. The host shows a placeholder background (--sc-placeholder-bg) until the asset
+- [Link](https://concorde.supersoniks.org/crawl/core/components/ui/link/link.html) (core/components/ui/link/link): Links navigate with inherited typography: internal routes, anchors, or external URLs. The default slot is the anchor label. For in-app routing, pair href with pushstate; use autoActive to reflect the 
+- [Loader](https://concorde.supersoniks.org/crawl/core/components/ui/loader/loader.html) (core/components/ui/loader/loader): sonic-loader shows a loading animation in the page or as a viewport overlay. Default mode is fixed (centered overlay). Use inline inside lists and fetch placeholders. Pair noDelay when the spinner sho
+- [Menu](https://concorde.supersoniks.org/crawl/core/components/ui/menu/menu.html) (core/components/ui/menu/menu): sonic-menu lays out navigation or actions as a direction row or column of sonic-menu-item entries (ghost variant and block shape by default), optional sonic-divider separators, and overflow content in
+- [Modal](https://concorde.supersoniks.org/crawl/core/components/ui/modal/modal.html) (core/components/ui/modal/modal): sonic-modal presents focused content in a <dialog> overlay with backdrop, enter/exit animation, and a built-in close control. Compose sonic-modal-title / sonic-modal-subtitle / sonic-modal-content / s
+- [Pop](https://concorde.supersoniks.org/crawl/core/components/ui/pop/pop.html) (core/components/ui/pop/pop): sonic-pop anchors floating panels to a trigger: put the control in the default slot and the panel in slot="content" (menus, forms, custom markup). Click toggles open/closed unless manual is set; defau
+- [Progress](https://concorde.supersoniks.org/crawl/core/components/ui/progress/progress.html) (core/components/ui/progress/progress): Shows task completion on a value / max scale via a native <progress> bar. Omit value for an indeterminate loading animation. Put primary copy in the default slot and optional secondary text in remaini
+- [Table](https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html) (core/components/ui/table/table): sonic-table lays out tabular data with composable sonic-tr / sonic-th / sonic-td children. The root applies shared typography via size, scrolls horizontally when content overflows, and optionally caps
+- [Theme](https://concorde.supersoniks.org/crawl/core/components/ui/theme/theme.html) (core/components/ui/theme/theme): sonic-theme wraps a Concorde UI: it registers --sc-* design tokens and provides the default slot for your app. With no theme attribute (or theme="custom"), only shared primitives and your overrides ap
+- [Toast](https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html) (core/components/ui/toast/toast): Toasts surface short-lived feedback in a fixed stack (bottom-right in the main window). Queue messages with SonicToast.add() on the global SonicToast class—the host sonic-toast is created automaticall
+- [Tooltip](https://concorde.supersoniks.org/crawl/core/components/ui/tooltip/tooltip.html) (core/components/ui/tooltip/tooltip): Tooltip shows a short label on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default placement is top (center-aligned). A
 - [Data flow](https://concorde.supersoniks.org/crawl/docs/_core-concept/dataFlow.html) (docs/_core-concept/dataFlow): Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a DataProvider store (legacy Publisher API: Legacy: Sharing data).
 - [lit + tailwind + vite](https://concorde.supersoniks.org/crawl/docs/_core-concept/overview.html) (docs/_core-concept/overview): Some notes for an overview of Concorde's functioning
 - [Legacy: Subscriber mixin](https://concorde.supersoniks.org/crawl/docs/_core-concept/subscriber.html) (docs/_core-concept/subscriber): > New app components: My first component and Data flow — extend LitElement with decorators (@subscribe, @ancestorAttribute, …). This mixin remains in core components (sonic-list, sonic-fetch, …) and l
@@ -90,7 +83,7 @@ Custom
 - [Legacy: My first subscriber component](https://concorde.supersoniks.org/crawl/docs/_getting-started/my-first-subscriber.html) (docs/_getting-started/my-first-subscriber): > New projects: use My first component (@ancestorAttribute, @subscribe + DataProviderKey, .items on lists) and Data flow. This page documents the Subscriber mixin used by older apps and core component
 - [Legacy: Sharing data](https://concorde.supersoniks.org/crawl/docs/_getting-started/pubsub.html) (docs/_getting-started/pubsub): > New apps: Data flow (get / set / DataProviderKey, decorators). This page documents the historical Publisher proxy API (PublisherManager, publisher.set, onAssign, …).
 - [Introduction](https://concorde.supersoniks.org/crawl/docs/_getting-started/start.html) (docs/_getting-started/start): Based on lit.dev, Concorde is a collection of web components for shared apps and websites.
-- [Adding styles](https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html) (docs/_getting-started/theming): No style crosses the shadow root of a component, except for inheritable properties (which have the "inherit" property possible) and CSS variables.
+- [Customization](https://concorde.supersoniks.org/crawl/docs/_getting-started/theming.html) (docs/_getting-started/theming): Concorde components ship with default styles (fallback values in each component and in <sonic-theme>).
 - [API configuration](https://concorde.supersoniks.org/crawl/docs/_misc/api-configuration.html) (docs/_misc/api-configuration): APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, 
 - [DataProviderKey](https://concorde.supersoniks.org/crawl/docs/_misc/dataProviderKey.html) (docs/_misc/dataProviderKey): The DataProviderKey<T> utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via toString() or the
 - [Local API demos (offline)](https://concorde.supersoniks.org/crawl/docs/_misc/docs-mock-api.html) (docs/_misc/docs-mock-api): The Concorde doc site does not call fragile third-party APIs during yarn dev. A Service Worker and the Vite dev middleware serve /docs-mock-api/* on the same origin.

package/docs/sitemap.xml

@@ -132,6 +132,9 @@
   <url>
     <loc>https://concorde.supersoniks.org/crawl/core/components/ui/table/table.html</loc>
   </url>
+  <url>
+    <loc>https://concorde.supersoniks.org/crawl/core/components/ui/theme/theme.html</loc>
+  </url>
   <url>
     <loc>https://concorde.supersoniks.org/crawl/core/components/ui/toast/toast.html</loc>
   </url>

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

@@ -1,8 +1,8 @@
 # Alert
 
-Inline message in the page: title (`label`), body (`text` or default slot), icon from `status`. For HTML or actions, use the slot instead of `label` / `text` (plain text only).
+Alerts **surface important feedback** inline—errors, confirmations, or contextual help. Use **`label`** / **`text`** for simple copy, or the **default slot** for rich content (links, buttons). Set **`announce`** when the message appears after an action so screen readers pick it up.
 
-Use **`status`**: `default`, `info`, `success`, `warning`, `error`.
+## Basic example
 
 <sonic-code>
   <template>
@@ -175,3 +175,22 @@ With **`dismissForever`**, dismissal is stored in `localStorage` (key `sonic-ale
     </sonic-alert>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `status` | `default` · `info` · `success` · `warning` · `error` | Color and default icon |
+| `label` | string | Title (plain text) |
+| `text` | string | Short body (plain text), rendered before the slot |
+| `size` | `2xs` … `2xl` | Corner radius and typography |
+| `background` | boolean | Tinted background (`color-mix` on status color) |
+| `dismissible` | boolean | Close control; removes the element from the DOM |
+| `dismissForever` | boolean | Persists dismissal in `localStorage`; requires **`id`** |
+| `noIcon` | boolean | Hides the icon (including custom `icon` slot content) |
+| `announce` | boolean | `role="alert"` / `aria-live` for dynamically injected content |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Message body (HTML, actions); rendered after `text` |
+| `icon` | Replaces the default `sonic-icon` |

package/docs/src/core/components/ui/alert-messages/alert-messages.md

@@ -0,0 +1,85 @@
+# Alert messages
+
+**`sonic-alert-messages`** renders a vertical stack of **`sonic-alert`** items from a **`messages`** array on a linked **data provider** (typical pattern: **`submitResultDataProvider`** after a form submit). Only entries with **`type="public"`** are shown. Each alert gets **`announce`** so screen readers pick up feedback after the request.
+
+## With submit result
+
+Bind **`dataProvider`** to the same publisher as **`submitResultDataProvider`**. API **`messages`** entries need **`type`**: **`public`**, plus **`content`** and optional **`status`** (`warning` · `success` · `error` · `info`).
+
+<sonic-code>
+  <template>
+    <sonic-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="submit-example"
+      submitResultDataProvider="submit-example-result"
+    >
+      <sonic-alert-messages dataProvider="submit-example-result" background class="mb-4"></sonic-alert-messages>
+      <div class="grid gap-4 max-w-md">
+        <sonic-input name="email" type="email" label="Email" value=""></sonic-input>
+        <sonic-input name="password" type="password" label="Password" value=""></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Submit (empty fields → error messages)</sonic-button>
+        </sonic-submit>
+      </div>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Shared alert props
+
+**`size`** · **`background`** and **`noIcon`** apply to every rendered **`sonic-alert`** in the list.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      size="sm"
+      variant="outline"
+      class="mb-3"
+      onclick="SonicPublisherManager.get('submit-example-result').set({ messages: [{ type: 'public', content: 'Compact inline feedback without icons.', status: 'info' }] })"
+    >
+      Load sample messages
+    </sonic-button>
+    <sonic-alert-messages
+      dataProvider="submit-example-result"
+      size="sm"
+      background
+      noIcon
+    ></sonic-alert-messages>
+  </template>
+</sonic-code>
+
+## Message shape
+
+Example JSON on the result publisher (or API response merged into it):
+
+<sonic-code language="typescript">
+  <template>
+{
+  "messages": [
+    {
+      "type": "public",
+      "content": "The product has been added to your cart",
+      "status": "success"
+    }
+  ]
+}
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `dataProvider` | publisher id | Source object; **`messages`** array is auto-filled via **Subscriber** |
+| `size` | `2xs` … `2xl` (default `md`) | Passed to each **`sonic-alert`** |
+| `background` | boolean | Tinted background on each alert |
+| `noIcon` | boolean | Hides icons on each alert |
+| `messages` | `Message[]` | Usually set by the publisher; each item uses **`content`** as alert **`text`** |
+
+| Message field | Values | Description |
+|---------------|---------|-------------|
+| `type` | `public` | Required for the message to render |
+| `content` | string | Alert body (**`text`** on **`sonic-alert`**) |
+| `status` | `warning` · `success` · `error` · `info` | Alert **`status`**; defaults to **`default`** when omitted |
+
+No slots — alerts are generated from **`messages`**.

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

@@ -1,8 +1,6 @@
 # Badge
 
-A **non-interactive** pill for labels, counts, or highlights (counter, status, category). The API mirrors `sonic-button` (`type`, `variant`, `size`) without focus or click states.
-
-Colors come from theme tokens (`--sc-primary`, `--sc-danger`, …) or the semantic `type` values below. 
+Badges are **compact, non-interactive** labels for status, counts, or categories. They mirror **`sonic-button`** styling (`type`, `variant`, `size`) without focus rings or click handling—use a button when the control should be actionable.
 
 ## Type
 
@@ -24,9 +22,9 @@ Colors come from theme tokens (`--sc-primary`, `--sc-danger`, …) or the semant
 
 ## Variant
 
-`outline` — border and text in the `type` color. `ghost` — text only, no padding (except in forced-colors mode).
+Default **`variant`** is filled. **`outline`** — border and text in the `type` color. **`ghost`** — text only, no padding (except in forced-colors mode).
 
-## Outline
+### Outline
 
 <sonic-code>
   <template>
@@ -42,7 +40,7 @@ Colors come from theme tokens (`--sc-primary`, `--sc-danger`, …) or the semant
   </template>
 </sonic-code>
 
-## Ghost
+### Ghost
 
 <sonic-code>
   <template>
@@ -173,3 +171,18 @@ Count inside a button (`slot="suffix"`) or a badge absolutely positioned on a bu
     </div>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` (default) · `primary` · `neutral` · `warning` · `info` · `success` · `danger` | Semantic color (`--sc-*` tokens) |
+| `variant` | `default` (default) · `outline` · `ghost` | Filled, bordered, or text-only |
+| `size` | `2xs` … `2xl` (default `md`) | Typography and padding (aligned with **`sonic-button`**) |
+| `ellipsis` | boolean | Single-line truncation; parent must constrain width |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Main label |
+| `prefix` | Icon or short text before the label |
+| `suffix` | Icon or short text after the label |

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

@@ -1,12 +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="captchaTestDataProvider" key="6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t">
-    <sonic-submit serviceURL="/docs-mock-api" endPoint="api/unknown" onclick>
-      <sonic-button  class="mt-4">Submit with captcha</sonic-button>
-    </sonic-submit>
-  </sonic-captcha>
+    <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

@@ -1,16 +1,27 @@
 # Card
 
-A **surface** for grouped content: padding, radius, shadow, and semantic **`type`** colors via shared theme tokens. Compose **`sonic-card-header`**, **`sonic-card-main`**, and **`sonic-card-footer`** inside the card, or put any markup in the default slot.
+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.
 
-Default **`type`** is `base` (page background). Use `light` for a subtle gray panel, `invert` / `neutral` for high-contrast blocks, and `primary`, `info`, `success`, `warning`, or `danger` for tinted surfaces (divider tokens apply on colored types).
+## 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>
@@ -22,9 +33,26 @@ Default **`type`** is `base` (page background). Use `light` for a subtle gray pa
   </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`** attributes, 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.
+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>
@@ -42,7 +70,7 @@ Quick titles with **`label`** and **`description`** attributes, or full control
           <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-badge slot="suffix" type="warning" size="xs">3 new</sonic-badge>
         </sonic-card-header>
       </sonic-card>
 
@@ -77,8 +105,6 @@ Quick titles with **`label`** and **`description`** attributes, or full control
   </template>
 </sonic-code>
 
-`label` and `description` accept HTML (rendered as markup). Prefer plain text when possible; use the slot for structured content.
-
 ## Main
 
 Optional wrapper for the primary content area (typography, media, forms).
@@ -110,7 +136,7 @@ Optional footer for actions, metadata, or secondary text.
         <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>
+        <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>
@@ -128,14 +154,14 @@ Header, media, body, and footer together.
   <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"></sonic-icon>
+        <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://images.unsplash.com/photo-1436491865332-7a61a109cc05?w=800&q=80"
-          alt=""
+          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.
@@ -150,3 +176,40 @@ Header, media, body, and footer together.
     </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`) |