@supersoniks/concorde 5.0.4 → 5.0.5

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="Messages &lt;sonic-badge slot=&quot;suffix&quot; type=&quot;danger&quot; size=&quot;xs&quot;&gt;5&lt;/sonic-badge&gt;">
-  <meta name="keywords" content="Concorde, supersoniks, core/components/ui/badge/badge, badge, Badge, UI component, sonic-badge, web component">
+  <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,103 +15,181 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde UI component — Badge</strong>. Messages &lt;sonic-badge slot=&quot;suffix&quot; type=&quot;danger&quot; size=&quot;xs&quot;&gt;5&lt;/sonic-badge&gt; <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. 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>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>
-<pre><code>&lt;sonic-badge&gt;Default&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;primary&quot;&gt;Primary&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;neutral&quot;&gt;Neutral&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;warning&quot;&gt;Warning&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;info&quot;&gt;Info&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;success&quot;&gt;Success&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;danger&quot;&gt;Danger&lt;/sonic-badge&gt;
-  &lt;sonic-badge type=&quot;contrast&quot;&gt;Contrast&lt;/sonic-badge&gt;
+<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;
+      &lt;sonic-badge&gt;Default&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;primary&quot;&gt;Primary&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;neutral&quot;&gt;Neutral&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;warning&quot;&gt;Warning&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;info&quot;&gt;Info&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;success&quot;&gt;Success&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot;&gt;Danger&lt;/sonic-badge&gt;
+    &lt;/div&gt;
 </code></pre>
-<h2 id="outline">Outline</h2>
+<h2 id="variant">Variant</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;
-    &lt;sonic-badge variant=&quot;outline&quot; type=&quot;neutral&quot;&gt;Neutral&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;outline&quot; type=&quot;warning&quot;&gt;Warning&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;outline&quot; type=&quot;info&quot;&gt;Info&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;outline&quot; type=&quot;success&quot;&gt;Success&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;outline&quot; type=&quot;danger&quot;&gt;Danger&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;outline&quot; type=&quot;contrast&quot;&gt;Contrast&lt;/sonic-badge&gt;
-  &lt;/div&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;
+      &lt;sonic-badge variant=&quot;outline&quot; type=&quot;neutral&quot;&gt;Neutral&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;outline&quot; type=&quot;warning&quot;&gt;Warning&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;outline&quot; type=&quot;info&quot;&gt;Info&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;outline&quot; type=&quot;success&quot;&gt;Success&lt;/sonic-badge&gt;
+      &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;
-    &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;neutral&quot;&gt;Neutral&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;warning&quot;&gt;Warning&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;info&quot;&gt;Info&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;success&quot;&gt;Success&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;danger&quot;&gt;Danger&lt;/sonic-badge&gt;
-    &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;contrast&quot;&gt;Contrast&lt;/sonic-badge&gt;
-  &lt;/div&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;
+      &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;neutral&quot;&gt;Neutral&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;warning&quot;&gt;Warning&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;info&quot;&gt;Info&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;success&quot;&gt;Success&lt;/sonic-badge&gt;
+      &lt;sonic-badge variant=&quot;ghost&quot; type=&quot;danger&quot;&gt;Danger&lt;/sonic-badge&gt;
+    &lt;/div&gt;
 </code></pre>
 <h2 id="size">Size</h2>
-<pre><code>&lt;sonic-badge size=&quot;2xs&quot;&gt;2Xs badge&lt;/sonic-badge&gt;
-  &lt;sonic-badge size=&quot;xs&quot;&gt;Xs badge&lt;/sonic-badge&gt;
-  &lt;sonic-badge size=&quot;sm&quot;&gt;Sm badge&lt;/sonic-badge&gt;
-  &lt;sonic-badge&gt;Md badge&lt;/sonic-badge&gt;
-  &lt;sonic-badge size=&quot;lg&quot;&gt;Lg badge&lt;/sonic-badge&gt;
-  &lt;sonic-badge size=&quot;xl&quot;&gt;Xl badge&lt;/sonic-badge&gt;
-  &lt;sonic-badge size=&quot;2xl&quot;&gt;2Xl badge&lt;/sonic-badge&gt;
+<p>Default size is <code>md</code> (omit the <code>size</code> attribute). Typography and padding follow <code>sonic-button</code>.</p>
+<pre><code>&lt;div class=&quot;flex flex-wrap items-center gap-2&quot;&gt;
+      &lt;sonic-badge size=&quot;2xs&quot;&gt;2Xs&lt;/sonic-badge&gt;
+      &lt;sonic-badge size=&quot;xs&quot;&gt;Xs&lt;/sonic-badge&gt;
+      &lt;sonic-badge size=&quot;sm&quot;&gt;Sm&lt;/sonic-badge&gt;
+      &lt;sonic-badge&gt;Md&lt;/sonic-badge&gt;
+      &lt;sonic-badge size=&quot;lg&quot;&gt;Lg&lt;/sonic-badge&gt;
+      &lt;sonic-badge size=&quot;xl&quot;&gt;Xl&lt;/sonic-badge&gt;
+      &lt;sonic-badge size=&quot;2xl&quot;&gt;2Xl&lt;/sonic-badge&gt;
+    &lt;/div&gt;
+</code></pre>
+<h2 id="prefix-and-suffix-slots">Prefix and suffix slots</h2>
+<p>Icons or short text before / after the main label.</p>
+<pre><code>&lt;sonic-badge type=&quot;info&quot; size=&quot;sm&quot;&gt;
+      &lt;sonic-icon slot=&quot;prefix&quot; name=&quot;info-empty&quot; library=&quot;iconoir&quot;&gt;&lt;/sonic-icon&gt;
+      Info
+    &lt;/sonic-badge&gt;
+    &lt;sonic-badge type=&quot;success&quot;&gt;
+      Verified
+      &lt;sonic-icon slot=&quot;suffix&quot; name=&quot;check&quot; library=&quot;iconoir&quot;&gt;&lt;/sonic-icon&gt;
+    &lt;/sonic-badge&gt;
 </code></pre>
 <h2 id="empty-badges">Empty badges</h2>
+<p>Badge with no text (visual dot). <code>min-width</code> / <code>min-height</code> keep a readable shape.</p>
 <pre><code>&lt;div class=&quot;flex items-center flex-wrap gap-3&quot;&gt;
-    &lt;sonic-badge type=&quot;danger&quot; size=&quot;2xs&quot;&gt;&lt;/sonic-badge&gt;
-    &lt;sonic-badge type=&quot;danger&quot; size=&quot;xs&quot;&gt;&lt;/sonic-badge&gt;
-    &lt;sonic-badge type=&quot;danger&quot; size=&quot;sm&quot;&gt;&lt;/sonic-badge&gt;
-    &lt;sonic-badge type=&quot;danger&quot;&gt;&lt;/sonic-badge&gt;
-    &lt;sonic-badge type=&quot;danger&quot; size=&quot;lg&quot;&gt;&lt;/sonic-badge&gt;
-    &lt;sonic-badge type=&quot;danger&quot; size=&quot;xl&quot;&gt;&lt;/sonic-badge&gt;
-    &lt;sonic-badge type=&quot;danger&quot; size=&quot;2xl&quot;&gt;&lt;/sonic-badge&gt;
-  &lt;/div&gt;
+      &lt;sonic-badge type=&quot;danger&quot; size=&quot;2xs&quot;&gt;&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot; size=&quot;xs&quot;&gt;&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot; size=&quot;sm&quot;&gt;&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot;&gt;&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot; size=&quot;lg&quot;&gt;&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot; size=&quot;xl&quot;&gt;&lt;/sonic-badge&gt;
+      &lt;sonic-badge type=&quot;danger&quot; size=&quot;2xl&quot;&gt;&lt;/sonic-badge&gt;
+    &lt;/div&gt;
 </code></pre>
 <h2 id="ellipsis">Ellipsis</h2>
-<pre><code>&lt;div class=&quot;grid grid-cols-3 gap-4&quot; &gt;
-        &lt;sonic-badge ellipsis size=&quot;sm&quot; variant=&quot;outline&quot;  &gt;
-        &lt;sonic-icon slot=&quot;prefix&quot; name=&quot;info-empty&quot; library=&quot;iconoir&quot;&gt;&lt;/sonic-icon&gt; Lorem ipsum dolor sit consectetur adipiscing elit. Lorem ipsum dolor sit consectetur adipiscing elit.&lt;/sonic-badge&gt;
-        &lt;sonic-badge ellipsis size=&quot;sm&quot; &gt; &lt;sonic-icon slot=&quot;prefix&quot; name=&quot;info-empty&quot; library=&quot;iconoir&quot;&gt;&lt;/sonic-icon&gt; Lorem ipsum dolor sit consectetur adipiscing elit. Lorem ipsum dolor sit consectetur adipiscing elit.&lt;/sonic-badge&gt;
+<p>With <code>ellipsis</code>, long labels truncate. The parent must constrain width (<code>max-width</code>, grid, etc.).</p>
+<pre><code>&lt;div class=&quot;grid grid-cols-2 gap-4 max-w-xl&quot;&gt;
+      &lt;sonic-badge ellipsis size=&quot;sm&quot; variant=&quot;outline&quot;&gt;
+        &lt;sonic-icon slot=&quot;prefix&quot; name=&quot;info-empty&quot; library=&quot;iconoir&quot;&gt;&lt;/sonic-icon&gt;
+        Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod.
+      &lt;/sonic-badge&gt;
+      &lt;sonic-badge ellipsis size=&quot;sm&quot;&gt;
+        &lt;sonic-icon slot=&quot;prefix&quot; name=&quot;info-empty&quot; library=&quot;iconoir&quot;&gt;&lt;/sonic-icon&gt;
+        Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod.
+      &lt;/sonic-badge&gt;
     &lt;/div&gt;
 </code></pre>
 <h2 id="badge-in-button">Badge in button</h2>
+<p>Count inside a button (<code>slot=&quot;suffix&quot;</code>) or a badge absolutely positioned on a button / icon.</p>
 <pre><code>&lt;div class=&quot;flex flex-wrap gap-4 items-center&quot;&gt;
-    &lt;sonic-button type=&quot;default&quot;&gt;
-      Messages &lt;sonic-badge slot=&quot;suffix&quot; type=&quot;danger&quot; size=&quot;xs&quot;&gt;5&lt;/sonic-badge&gt;
-    &lt;/sonic-button&gt;
-    &lt;div class=&quot;relative inline-block&quot;&gt;
-      &lt;sonic-button type=&quot;success&quot; class=&quot;relative&quot;&gt; Mon compte &lt;/sonic-button&gt;
-      &lt;sonic-badge type=&quot;danger&quot; size=&quot;xs&quot; class=&quot;absolute right-1 top-0 pe-none transform -translate-y-1/2&quot;
-        &gt;12&lt;/sonic-badge
-      &gt;
-    &lt;/div&gt;
-    &lt;div class=&quot;relative inline-block&quot;&gt;
-      &lt;sonic-button type=&quot;neutral&quot; shape=&quot;circle&quot; variant=&quot;outline&quot;
-        &gt;&lt;sonic-icon library=&quot;iconoir&quot; name=&quot;user&quot;&gt;&lt;/sonic-icon&gt;
-      &lt;/sonic-button&gt;
-      &lt;sonic-badge
-        type=&quot;danger&quot;
-        size=&quot;xs&quot;
-        class=&quot;absolute right-1 bottom-1 pe-none transform translate-y-1/2 translate-x-1/2&quot;
-        &gt;33&lt;/sonic-badge
-      &gt;
-    &lt;/div&gt;
-    &lt;div class=&quot;relative inline-block&quot;&gt;
-      &lt;sonic-button type=&quot;neutral&quot; shape=&quot;circle&quot; variant=&quot;outline&quot;
-        &gt;&lt;sonic-icon library=&quot;iconoir&quot; name=&quot;user&quot;&gt;&lt;/sonic-icon&gt;
+      &lt;sonic-button type=&quot;default&quot;&gt;
+        Messages &lt;sonic-badge slot=&quot;suffix&quot; type=&quot;danger&quot; size=&quot;xs&quot;&gt;5&lt;/sonic-badge&gt;
       &lt;/sonic-button&gt;
-      &lt;sonic-badge
-        type=&quot;danger&quot;
-        size=&quot;xs&quot;
-        class=&quot;absolute right-2 bottom-2 pe-none transform translate-y-1/2 translate-x-1/2&quot;
-      &gt;&lt;/sonic-badge&gt;
+      &lt;div class=&quot;relative inline-block&quot;&gt;
+        &lt;sonic-button type=&quot;success&quot; class=&quot;relative&quot;&gt;My account&lt;/sonic-button&gt;
+        &lt;sonic-badge
+          type=&quot;danger&quot;
+          size=&quot;xs&quot;
+          class=&quot;absolute right-1 top-0 pe-none transform -translate-y-1/2&quot;
+          &gt;12&lt;/sonic-badge
+        &gt;
+      &lt;/div&gt;
+      &lt;div class=&quot;relative inline-block&quot;&gt;
+        &lt;sonic-button type=&quot;neutral&quot; shape=&quot;circle&quot; variant=&quot;outline&quot;&gt;
+          &lt;sonic-icon library=&quot;iconoir&quot; name=&quot;user&quot;&gt;&lt;/sonic-icon&gt;
+        &lt;/sonic-button&gt;
+        &lt;sonic-badge
+          type=&quot;danger&quot;
+          size=&quot;xs&quot;
+          class=&quot;absolute right-1 bottom-1 pe-none transform translate-y-1/2 translate-x-1/2&quot;
+          &gt;33&lt;/sonic-badge
+        &gt;
+      &lt;/div&gt;
+      &lt;div class=&quot;relative inline-block&quot;&gt;
+        &lt;sonic-button type=&quot;neutral&quot; shape=&quot;circle&quot; variant=&quot;outline&quot;&gt;
+          &lt;sonic-icon library=&quot;iconoir&quot; name=&quot;user&quot;&gt;&lt;/sonic-icon&gt;
+        &lt;/sonic-button&gt;
+        &lt;sonic-badge
+          type=&quot;danger&quot;
+          size=&quot;xs&quot;
+          class=&quot;absolute right-2 bottom-2 pe-none transform translate-y-1/2 translate-x-1/2&quot;
+        &gt;&lt;/sonic-badge&gt;
+      &lt;/div&gt;
     &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/button/button.html

@@ -66,6 +66,7 @@
 <p>The length of the button depends on the size of its content</p>
 <pre><code>&lt;sonic-button loading&gt;&lt;/sonic-button&gt;
     &lt;sonic-button loading&gt;Loading button&lt;/sonic-button&gt;
+    &lt;sonic-button loading&gt;&lt;span slot=&quot;prefix&quot;&gt;🚀&lt;/span&gt;Loading with prefix&lt;span slot=&quot;suffix&quot;&gt;😂&lt;/span&gt;&lt;/sonic-button&gt;
 </code></pre>
 <h2 id="swap">Swap</h2>
 <pre><code>&lt;sonic-button formDataProvider=&quot;button_swap_example&quot; name=&quot;youpi&quot; value=&quot;youpla&quot; type=&quot;primary&quot; shape=&quot;circle&quot; variant=&quot;outline&quot; class=&quot;mr-4&quot;&gt;

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>