@supersoniks/concorde 5.0.3 → 5.0.5

package/docs/crawl/core/components/ui/alert/alert.html

@@ -4,8 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Alert — Concorde</title>
-  <meta name="description" content="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).">
-  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/alert/alert, alert, Alert, UI component, sonic-alert, web component, label, text, status, default, info, success, warning">
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/alert/alert, alert, Alert, UI component, sonic-alert, web component, label, text, announce, status, default, role, aria-live">
   <meta name="concorde-doc-id" content="core/components/ui/alert/alert">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html">
 </head>
@@ -15,10 +15,10 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Alert</strong>. 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). <span>Doc ID: <code>core/components/ui/alert/alert</code>. Keywords: Concorde, supersoniks, core/components/ui/alert/alert, alert, Alert, UI component, sonic-alert, web component, label, text, status, default, info, success, warning. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html">https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Alert</strong>. 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 <span>Doc ID: <code>core/components/ui/alert/alert</code>. Keywords: Concorde, supersoniks, core/components/ui/alert/alert, alert, Alert, UI component, sonic-alert, web component, label, text, announce, status, default, role, aria-live. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html">https://concorde.supersoniks.org/crawl/core/components/ui/alert/alert.html</a>.</span></p>
       <h1 id="alert">Alert</h1>
-<p>Inline message in the page: title (<code>label</code>), body (<code>text</code> or default slot), icon from <code>status</code>. For HTML or actions, use the slot instead of <code>label</code> / <code>text</code> (plain text only).</p>
-<p>Use <strong><code>status</code></strong>: <code>default</code>, <code>info</code>, <code>success</code>, <code>warning</code>, <code>error</code>.</p>
+<p>Alerts <strong>surface important feedback</strong> inline—errors, confirmations, or contextual help. Use <strong><code>label</code></strong> / <strong><code>text</code></strong> for simple copy, or the <strong>default slot</strong> for rich content (links, buttons). Set <strong><code>announce</code></strong> when the message appears after an action so screen readers pick it up.</p>
+<h2 id="basic-example">Basic example</h2>
 <pre><code>&lt;sonic-alert status=&quot;error&quot; label=&quot;Email error&quot; text=&quot;This address is already in use&quot; background&gt;&lt;/sonic-alert&gt;
 </code></pre>
 <h2 id="status">Status</h2>
@@ -133,6 +133,77 @@
       This address is already in use.
     &lt;/sonic-alert&gt;
 </code></pre>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>status</code></td>
+<td><code>default</code> · <code>info</code> · <code>success</code> · <code>warning</code> · <code>error</code></td>
+<td>Color and default icon</td>
+</tr>
+<tr>
+<td><code>label</code></td>
+<td>string</td>
+<td>Title (plain text)</td>
+</tr>
+<tr>
+<td><code>text</code></td>
+<td>string</td>
+<td>Short body (plain text), rendered before the slot</td>
+</tr>
+<tr>
+<td><code>size</code></td>
+<td><code>2xs</code> … <code>2xl</code></td>
+<td>Corner radius and typography</td>
+</tr>
+<tr>
+<td><code>background</code></td>
+<td>boolean</td>
+<td>Tinted background (<code>color-mix</code> on status color)</td>
+</tr>
+<tr>
+<td><code>dismissible</code></td>
+<td>boolean</td>
+<td>Close control; removes the element from the DOM</td>
+</tr>
+<tr>
+<td><code>dismissForever</code></td>
+<td>boolean</td>
+<td>Persists dismissal in <code>localStorage</code>; requires <strong><code>id</code></strong></td>
+</tr>
+<tr>
+<td><code>noIcon</code></td>
+<td>boolean</td>
+<td>Hides the icon (including custom <code>icon</code> slot content)</td>
+</tr>
+<tr>
+<td><code>announce</code></td>
+<td>boolean</td>
+<td><code>role=&quot;alert&quot;</code> / <code>aria-live</code> for dynamically injected content</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Slot</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><em>(default)</em></td>
+<td>Message body (HTML, actions); rendered after <code>text</code></td>
+</tr>
+<tr>
+<td><code>icon</code></td>
+<td>Replaces the default <code>sonic-icon</code></td>
+</tr>
+</tbody></table>
 
     </article>
   </main>

package/docs/crawl/core/components/ui/alert-messages/alert-messages.html

@@ -3,9 +3,9 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Concorde — Concorde</title>
-  <meta name="description" content="Concorde documentation: Concorde">
-  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/alert-messages/alert-messages, alert-messages, UI component, sonic-alert-messages, web component">
+  <title>Alert messages — Concorde</title>
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/alert-messages/alert-messages, alert-messages, Alert messages, UI component, sonic-alert-messages, web component, sonic-alert, messages, submitResultDataProvider, type=&quot;public&quot;, announce, dataProvider, type">
   <meta name="concorde-doc-id" content="core/components/ui/alert-messages/alert-messages">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html">
 </head>
@@ -15,8 +15,116 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Concorde</strong>. Concorde documentation: Concorde <span>Doc ID: <code>core/components/ui/alert-messages/alert-messages</code>. Keywords: Concorde, supersoniks, core/components/ui/alert-messages/alert-messages, alert-messages, UI component, sonic-alert-messages, web component. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html">https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html</a>.</span></p>
-      
+      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Alert messages</strong>. 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 <span>Doc ID: <code>core/components/ui/alert-messages/alert-messages</code>. Keywords: Concorde, supersoniks, core/components/ui/alert-messages/alert-messages, alert-messages, Alert messages, UI component, sonic-alert-messages, web component, sonic-alert, messages, submitResultDataProvider, type=&quot;public&quot;, announce, dataProvider, type. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html">https://concorde.supersoniks.org/crawl/core/components/ui/alert-messages/alert-messages.html</a>.</span></p>
+      <h1 id="alert-messages">Alert messages</h1>
+<p><strong><code>sonic-alert-messages</code></strong> renders a vertical stack of <strong><code>sonic-alert</code></strong> items from a <strong><code>messages</code></strong> array on a linked <strong>data provider</strong> (typical pattern: <strong><code>submitResultDataProvider</code></strong> after a form submit). Only entries with <strong><code>type=&quot;public&quot;</code></strong> are shown. Each alert gets <strong><code>announce</code></strong> so screen readers pick up feedback after the request.</p>
+<h2 id="with-submit-result">With submit result</h2>
+<p>Bind <strong><code>dataProvider</code></strong> to the same publisher as <strong><code>submitResultDataProvider</code></strong>. API <strong><code>messages</code></strong> entries need <strong><code>type</code></strong>: <strong><code>public</code></strong>, plus <strong><code>content</code></strong> and optional <strong><code>status</code></strong> (<code>warning</code> · <code>success</code> · <code>error</code> · <code>info</code>).</p>
+<pre><code>&lt;sonic-scope
+      serviceURL=&quot;/docs-mock-api&quot;
+      formDataProvider=&quot;submit-example&quot;
+      submitResultDataProvider=&quot;submit-example-result&quot;
+    &gt;
+      &lt;sonic-alert-messages dataProvider=&quot;submit-example-result&quot; background class=&quot;mb-4&quot;&gt;&lt;/sonic-alert-messages&gt;
+      &lt;div class=&quot;grid gap-4 max-w-md&quot;&gt;
+        &lt;sonic-input name=&quot;email&quot; type=&quot;email&quot; label=&quot;Email&quot; value=&quot;&quot;&gt;&lt;/sonic-input&gt;
+        &lt;sonic-input name=&quot;password&quot; type=&quot;password&quot; label=&quot;Password&quot; value=&quot;&quot;&gt;&lt;/sonic-input&gt;
+        &lt;sonic-submit endPoint=&quot;api/register&quot; onClick&gt;
+          &lt;sonic-button type=&quot;primary&quot;&gt;Submit (empty fields → error messages)&lt;/sonic-button&gt;
+        &lt;/sonic-submit&gt;
+      &lt;/div&gt;
+    &lt;/sonic-scope&gt;
+</code></pre>
+<h2 id="shared-alert-props">Shared alert props</h2>
+<p><strong><code>size</code></strong> · <strong><code>background</code></strong> and <strong><code>noIcon</code></strong> apply to every rendered <strong><code>sonic-alert</code></strong> in the list.</p>
+<pre><code>&lt;sonic-button
+      size=&quot;sm&quot;
+      variant=&quot;outline&quot;
+      class=&quot;mb-3&quot;
+      onclick=&quot;SonicPublisherManager.get(&#39;submit-example-result&#39;).set({ messages: [{ type: &#39;public&#39;, content: &#39;Compact inline feedback without icons.&#39;, status: &#39;info&#39; }] })&quot;
+    &gt;
+      Load sample messages
+    &lt;/sonic-button&gt;
+    &lt;sonic-alert-messages
+      dataProvider=&quot;submit-example-result&quot;
+      size=&quot;sm&quot;
+      background
+      noIcon
+    &gt;&lt;/sonic-alert-messages&gt;
+</code></pre>
+<h2 id="message-shape">Message shape</h2>
+<p>Example JSON on the result publisher (or API response merged into it):</p>
+<pre><code class="language-typescript">{
+  &quot;messages&quot;: [
+    {
+      &quot;type&quot;: &quot;public&quot;,
+      &quot;content&quot;: &quot;The product has been added to your cart&quot;,
+      &quot;status&quot;: &quot;success&quot;
+    }
+  ]
+}
+</code></pre>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>dataProvider</code></td>
+<td>publisher id</td>
+<td>Source object; <strong><code>messages</code></strong> array is auto-filled via <strong>Subscriber</strong></td>
+</tr>
+<tr>
+<td><code>size</code></td>
+<td><code>2xs</code> … <code>2xl</code> (default <code>md</code>)</td>
+<td>Passed to each <strong><code>sonic-alert</code></strong></td>
+</tr>
+<tr>
+<td><code>background</code></td>
+<td>boolean</td>
+<td>Tinted background on each alert</td>
+</tr>
+<tr>
+<td><code>noIcon</code></td>
+<td>boolean</td>
+<td>Hides icons on each alert</td>
+</tr>
+<tr>
+<td><code>messages</code></td>
+<td><code>Message[]</code></td>
+<td>Usually set by the publisher; each item uses <strong><code>content</code></strong> as alert <strong><code>text</code></strong></td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Message field</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>type</code></td>
+<td><code>public</code></td>
+<td>Required for the message to render</td>
+</tr>
+<tr>
+<td><code>content</code></td>
+<td>string</td>
+<td>Alert body (<strong><code>text</code></strong> on <strong><code>sonic-alert</code></strong>)</td>
+</tr>
+<tr>
+<td><code>status</code></td>
+<td><code>warning</code> · <code>success</code> · <code>error</code> · <code>info</code></td>
+<td>Alert <strong><code>status</code></strong>; defaults to <strong><code>default</code></strong> when omitted</td>
+</tr>
+</tbody></table>
+<p>No slots — alerts are generated from <strong><code>messages</code></strong>.</p>
+
     </article>
   </main>
 </body>

package/docs/crawl/core/components/ui/badge/badge.html

@@ -4,8 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Badge — Concorde</title>
-  <meta name="description" content="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.">
-  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component, sonic-button, type, variant, size, --sc-primary, --sc-danger, default, base-100, neutral">
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component, sonic-button, type, variant, size, default, base-100, neutral, base-content, outline">
   <meta name="concorde-doc-id" content="core/components/ui/badge/badge">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html">
 </head>
@@ -15,10 +15,9 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Badge</strong>. 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. <span>Doc ID: <code>core/components/ui/badge/badge</code>. Keywords: Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component, sonic-button, type, variant, size, --sc-primary, --sc-danger, default, base-100, neutral. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html">https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Badge</strong>. 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 <span>Doc ID: <code>core/components/ui/badge/badge</code>. Keywords: Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component, sonic-button, type, variant, size, default, base-100, neutral, base-content, outline. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html">https://concorde.supersoniks.org/crawl/core/components/ui/badge/badge.html</a>.</span></p>
       <h1 id="badge">Badge</h1>
-<p>A <strong>non-interactive</strong> pill for labels, counts, or highlights (counter, status, category). The API mirrors <code>sonic-button</code> (<code>type</code>, <code>variant</code>, <code>size</code>) without focus or click states.</p>
-<p>Colors come from theme tokens (<code>--sc-primary</code>, <code>--sc-danger</code>, …) or the semantic <code>type</code> values below. </p>
+<p>Badges are <strong>compact, non-interactive</strong> labels for status, counts, or categories. They mirror <strong><code>sonic-button</code></strong> styling (<code>type</code>, <code>variant</code>, <code>size</code>) without focus rings or click handling—use a button when the control should be actionable.</p>
 <h2 id="type">Type</h2>
 <p><code>default</code> — subtle background (<code>base-100</code>). <code>neutral</code> — dark fill (<code>base-content</code>) with light text, useful on light backgrounds.</p>
 <pre><code>&lt;div class=&quot;flex flex-wrap gap-2&quot;&gt;
@@ -32,8 +31,8 @@
     &lt;/div&gt;
 </code></pre>
 <h2 id="variant">Variant</h2>
-<p><code>outline</code> — border and text in the <code>type</code> color. <code>ghost</code> — text only, no padding (except in forced-colors mode).</p>
-<h2 id="outline">Outline</h2>
+<p>Default <strong><code>variant</code></strong> is filled. <strong><code>outline</code></strong> — border and text in the <code>type</code> color. <strong><code>ghost</code></strong> — text only, no padding (except in forced-colors mode).</p>
+<h3 id="outline">Outline</h3>
 <pre><code>&lt;div class=&quot;flex items-center flex-wrap gap-3&quot;&gt;
       &lt;sonic-badge variant=&quot;outline&quot;&gt;Default&lt;/sonic-badge&gt;
       &lt;sonic-badge variant=&quot;outline&quot; type=&quot;primary&quot;&gt;Primary&lt;/sonic-badge&gt;
@@ -44,7 +43,7 @@
       &lt;sonic-badge variant=&quot;outline&quot; type=&quot;danger&quot;&gt;Danger&lt;/sonic-badge&gt;
     &lt;/div&gt;
 </code></pre>
-<h2 id="ghost">Ghost</h2>
+<h3 id="ghost">Ghost</h3>
 <pre><code>&lt;div class=&quot;flex items-center flex-wrap gap-3&quot;&gt;
       &lt;sonic-badge variant=&quot;ghost&quot;&gt;Default&lt;/sonic-badge&gt;
       &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;primary&quot;&gt;Primary&lt;/sonic-badge&gt;
@@ -141,6 +140,56 @@
       &lt;/div&gt;
     &lt;/div&gt;
 </code></pre>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>type</code></td>
+<td><code>default</code> (default) · <code>primary</code> · <code>neutral</code> · <code>warning</code> · <code>info</code> · <code>success</code> · <code>danger</code></td>
+<td>Semantic color (<code>--sc-*</code> tokens)</td>
+</tr>
+<tr>
+<td><code>variant</code></td>
+<td><code>default</code> (default) · <code>outline</code> · <code>ghost</code></td>
+<td>Filled, bordered, or text-only</td>
+</tr>
+<tr>
+<td><code>size</code></td>
+<td><code>2xs</code> … <code>2xl</code> (default <code>md</code>)</td>
+<td>Typography and padding (aligned with <strong><code>sonic-button</code></strong>)</td>
+</tr>
+<tr>
+<td><code>ellipsis</code></td>
+<td>boolean</td>
+<td>Single-line truncation; parent must constrain width</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Slot</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><em>(default)</em></td>
+<td>Main label</td>
+</tr>
+<tr>
+<td><code>prefix</code></td>
+<td>Icon or short text before the label</td>
+</tr>
+<tr>
+<td><code>suffix</code></td>
+<td>Icon or short text after the label</td>
+</tr>
+</tbody></table>
 
     </article>
   </main>

package/docs/crawl/core/components/ui/captcha/captcha.html

@@ -4,8 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Captcha — Concorde</title>
-  <meta name="description" content="Captcha: Submit with captcha">
-  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/captcha/captcha, captcha, Captcha, UI component, sonic-captcha, web component">
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/captcha/captcha, captcha, Captcha, UI component, sonic-captcha, web component, captchaToken, needsCaptchaValidation, formDataProvider, headersDataProvider, sonic-submit, key, generateEncryptedKey">
   <meta name="concorde-doc-id" content="core/components/ui/captcha/captcha">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html">
 </head>
@@ -15,14 +15,96 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Captcha</strong>. Captcha: Submit with captcha <span>Doc ID: <code>core/components/ui/captcha/captcha</code>. Keywords: Concorde, supersoniks, core/components/ui/captcha/captcha, captcha, Captcha, UI component, sonic-captcha, web component. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html">https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Captcha</strong>. 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 <span>Doc ID: <code>core/components/ui/captcha/captcha</code>. Keywords: Concorde, supersoniks, core/components/ui/captcha/captcha, captcha, Captcha, UI component, sonic-captcha, web component, captchaToken, needsCaptchaValidation, formDataProvider, headersDataProvider, sonic-submit, key, generateEncryptedKey. URL: <a href="https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html">https://concorde.supersoniks.org/crawl/core/components/ui/captcha/captcha.html</a>.</span></p>
       <h1 id="captcha">Captcha</h1>
-<pre><code>&lt;sonic-captcha formDataProvider=&quot;captchaTestDataProvider&quot; key=&quot;6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t&quot;&gt;
-    &lt;sonic-submit serviceURL=&quot;/docs-mock-api&quot; endPoint=&quot;api/unknown&quot; onclick&gt;
-      &lt;sonic-button  class=&quot;mt-4&quot;&gt;Submit with captcha&lt;/sonic-button&gt;
-    &lt;/sonic-submit&gt;
-  &lt;/sonic-captcha&gt;
+<p><strong><code>sonic-captcha</code></strong> embeds an <strong>ALTCHA</strong> widget and wires <strong><code>captchaToken</code></strong> / <strong><code>needsCaptchaValidation</code></strong> on the ancestor <strong><code>formDataProvider</code></strong> (or <strong><code>headersDataProvider</code></strong>). <strong><code>sonic-submit</code></strong> waits for a token before sending when validation is required. The widget loads only on <strong>HTTPS</strong>; on plain HTTP the host renders nothing.</p>
+<blockquote>
+<p>Live widget calls the Supersoniks challenge service — not part of <a href="../../../../docs/_misc/docs-mock-api.html#docs-mock-api">docs mock API</a>.</p>
+</blockquote>
+<h2 id="basic-example">Basic example</h2>
+<p>Wrap the form scope and place <strong><code>sonic-submit</code></strong> in the default slot so the challenge appears above the action.</p>
+<pre><code>&lt;sonic-scope
+      serviceURL=&quot;/docs-mock-api&quot;
+      formDataProvider=&quot;captcha-docs-form&quot;
+      submitResultDataProvider=&quot;captcha-docs-result&quot;
+    &gt;
+      &lt;sonic-captcha formDataProvider=&quot;captcha-docs-form&quot;&gt;
+        &lt;sonic-input class=&quot;mb-3&quot; name=&quot;email&quot; type=&quot;email&quot; label=&quot;Email&quot; value=&quot;demo@example.com&quot;&gt;&lt;/sonic-input&gt;
+        &lt;sonic-submit endPoint=&quot;api/register&quot; onClick&gt;
+          &lt;sonic-button type=&quot;primary&quot;&gt;Submit with captcha&lt;/sonic-button&gt;
+        &lt;/sonic-submit&gt;
+      &lt;/sonic-captcha&gt;
+    &lt;/sonic-scope&gt;
 </code></pre>
+<h2 id="encrypted-site-key">Encrypted site key</h2>
+<p>Optional <strong><code>key</code></strong> skips client-side key generation. When omitted, the component derives an encrypted key on connect (after <strong><code>generateEncryptedKey</code></strong>).</p>
+<pre><code>&lt;sonic-captcha formDataProvider=&quot;captcha-docs-form&quot; key=&quot;6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t&quot;&gt;
+      &lt;sonic-button type=&quot;outline&quot; disabled&gt;Complete the challenge above to enable submit&lt;/sonic-button&gt;
+    &lt;/sonic-captcha&gt;
+</code></pre>
+<h2 id="form-publisher-fields">Form publisher fields</h2>
+<p>On connect (HTTPS only), <strong><code>needsCaptchaValidation</code></strong> is set to <strong><code>true</code></strong> and <strong><code>captchaToken</code></strong> is cleared. When the ALTCHA widget reaches <strong><code>verified</code></strong>, <strong><code>captchaToken</code></strong> is written on the form publisher and <strong><code>sonic-captcha-validate</code></strong> fires (<code>detail.valid</code> · <strong><code>detail.state</code></strong> · optional <strong><code>detail.token</code></strong> / <strong><code>detail.payload</code></strong>). <strong><code>sonic-submit</code></strong> still listens for <strong><code>request_token</code></strong> to refresh the token immediately before send.</p>
+<pre><code class="language-typescript">{
+  needsCaptchaValidation: true,
+  captchaKey: &quot;…&quot;,
+  captchaToken: &quot;…&quot;
+}
+</code></pre>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>formDataProvider</code></td>
+<td>publisher id</td>
+<td>Same as ancestor form scope; reads/writes <strong><code>needsCaptchaValidation</code></strong> · <strong><code>captchaKey</code></strong> · <strong><code>captchaToken</code></strong></td>
+</tr>
+<tr>
+<td><code>key</code></td>
+<td>string</td>
+<td>ALTCHA site key; auto-generated when empty</td>
+</tr>
+<tr>
+<td><code>action</code></td>
+<td>string</td>
+<td>Optional action name forwarded to the widget</td>
+</tr>
+<tr>
+<td><code>zIndex</code></td>
+<td>number (default <code>9999</code>)</td>
+<td>Stacking for the challenge overlay</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Slot</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><em>(default)</em></td>
+<td>Form actions (typically <strong><code>sonic-submit</code></strong> and fields) rendered below the widget</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Event</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>sonic-captcha-validate</code></td>
+<td>Fired when <strong><code>state</code></strong> is <strong><code>verified</code></strong> · <strong><code>error</code></strong> or <strong><code>expired</code></strong>; <strong><code>detail.valid</code></strong> is <strong><code>true</code></strong> only for <strong><code>verified</code></strong></td>
+</tr>
+</tbody></table>
+<p>Related: <a href="../../functional/submit/submit.html#submit">Submit</a> — <strong><code>needsCaptchaValidation</code></strong> and deferred send.</p>
 
     </article>
   </main>