@supersoniks/concorde 5.1.0 → 5.1.2

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

@@ -1,6 +1,11 @@
 # Button
 
+**`sonic-button`** is the clickable control of the library: a plain button, a link when `href` is set, or a form toggle when it has a `name` and `value`. It shares `type` / `variant` / `size` with **`sonic-badge`**, and exposes `prefix` / `suffix` slots for icons.
+
 ## Type
+
+With no `type`, the button is `default`. Use `custom` with `--sc-btn-custom-color` and `--sc-btn-custom-bg` for a one-off color.
+
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
@@ -16,167 +21,196 @@
   </template>
 </sonic-code>
 
-## Outline
+## Variant
+
+With no `variant`, the button is filled. The `outline` / `ghost` / `link` variants take their color from `type`. `unstyled` removes all styling so you can apply your own classes.
+
 <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>
+      <sonic-button type="primary">Default</sonic-button>
+      <sonic-button type="primary" variant="outline">Outline</sonic-button>
+      <sonic-button type="primary" variant="ghost">Ghost</sonic-button>
+      <sonic-button type="primary" variant="link">Link</sonic-button>
+      <sonic-button variant="unstyled">Unstyled</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
+
+With no `size`, the button is `md`.
+
 <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>
+    <div class="flex flex-wrap items-center gap-2">
+      <sonic-button size="2xs">2xs</sonic-button>
+      <sonic-button size="xs">xs</sonic-button>
+      <sonic-button size="sm">sm</sonic-button>
+      <sonic-button>md</sonic-button>
+      <sonic-button size="lg">lg</sonic-button>
+      <sonic-button size="xl">xl</sonic-button>
+      <sonic-button size="2xl">2xl</sonic-button>
+    </div>
   </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
+`circle` and `square` make a fixed-size icon button. `block` stretches to the full width of the parent.
+
 <sonic-code>
   <template>
-    <sonic-button loading></sonic-button>
-    <sonic-button loading>Loading button</sonic-button>
+    <div class="flex flex-wrap items-center gap-2 mb-2">
+      <sonic-button shape="circle" type="primary"><sonic-icon library="iconoir" name="plus"></sonic-icon></sonic-button>
+      <sonic-button shape="square" type="primary"><sonic-icon library="iconoir" name="plus"></sonic-icon></sonic-button>
+    </div>
+    <sonic-button shape="block" type="primary">Block</sonic-button>
   </template>
 </sonic-code>
 
-## Swap
+## Prefix and suffix slots
+
 <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>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button type="primary" variant="outline">
+        <sonic-icon library="iconoir" slot="prefix" name="arrow-left"></sonic-icon>
+        Previous flight
+      </sonic-button>
+      <sonic-button type="primary">
+        Next flight
+        <sonic-icon library="iconoir" slot="suffix" name="arrow-right"></sonic-icon>
+      </sonic-button>
+    </div>
   </template>
 </sonic-code>
 
-## Reset
+## Loading
+
+`loading` replaces the content with a spinner and blocks clicks. The button keeps the width of its content.
+
 <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 class="flex flex-wrap gap-2">
+      <sonic-button loading></sonic-button>
+      <sonic-button loading>Loading button</sonic-button>
+      <sonic-button loading type="primary">
+        <sonic-icon library="iconoir" slot="prefix" name="check"></sonic-icon>
+        Checking in
+      </sonic-button>
     </div>
-      <sonic-button reset="button-reset-demo">Reset formDataProvider by name</sonic-button>
   </template>
 </sonic-code>
 
+## Link
+
+With `href`, the button renders as a link. For a relative `href`, the button gets `active` when the current URL matches, according to `autoActive` (default `partial`). Add `pushState` to navigate without reloading the page.
 
-## 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>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button href="https://example.com" target="_blank" type="primary">External link</sonic-button>
+      <sonic-button href="/core/components/ui/button" variant="ghost">Current page</sonic-button>
+    </div>
   </template>
 </sonic-code>
 
-## Button with icon
+## Toggle and radio
+
+A button with `name` and `value` writes to its `formDataProvider` and toggles `active` when clicked. Add `radio` for a single choice in a group, or `unique` to also allow deselecting. Children marked `swap="on"` / `swap="off"` show only in the active / inactive state.
+
 <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>
+    <div class="flex flex-wrap items-center gap-4">
+      <sonic-button formDataProvider="button-toggle-demo" name="visible" value="yes" type="primary" shape="circle" variant="outline">
+        <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-group formDataProvider="button-radio-demo">
+        <sonic-button radio minWidth="7rem" name="plan" value="free">Free</sonic-button>
+        <sonic-button radio minWidth="7rem" name="plan" value="pro">Pro</sonic-button>
+        <sonic-button radio minWidth="7rem" name="plan" value="team">Team</sonic-button>
+      </sonic-group>
+    </div>
   </template>
 </sonic-code>
 
+## Reset
+
+`reset` clears the button's own `formDataProvider`. Give it a value to clear another one by name.
 
-## 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>
+    <div formDataProvider="button-reset-demo" class="mb-2">
+      <sonic-checkbox name="agree" value="yes">Extra baggage</sonic-checkbox>
+      <sonic-button reset>Reset this form</sonic-button>
+    </div>
+    <sonic-button reset="button-reset-demo">Reset by name</sonic-button>
   </template>
 </sonic-code>
 
+## Go back
+
+`goBack` navigates back in history. When there is no previous page on the same origin, it goes to the attribute value, or to the site root if empty.
 
-## 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>
+    <sonic-button goBack="/" variant="outline">
+      <sonic-icon library="iconoir" slot="prefix" name="arrow-left"></sonic-icon>
+      Back
+    </sonic-button>
   </template>
 </sonic-code>
 
+## Accessibility
+
+Icon-only buttons need a label. Use `data-aria-label`, which is forwarded to the inner `button` (and link).
 
-## 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>
+    <sonic-button shape="circle" data-aria-label="Close">
+      <sonic-icon library="iconoir" name="cancel"></sonic-icon>
+    </sonic-button>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `type` | `default` (default) · `primary` · `neutral` · `warning` · `info` · `success` · `danger` · `custom` | Color; `custom` reads `--sc-btn-custom-color` and `--sc-btn-custom-bg` |
+| `variant` | `default` (default) · `outline` · `ghost` · `link` · `unstyled` | Visual style |
+| `size` | `2xs` … `2xl` (default `md`) · `inherit` | Typography and padding |
+| `shape` | `default` (default) · `circle` · `square` · `block` | Icon button or full width |
+| `icon` | boolean | Enlarges a lone icon |
+| `loading` | boolean | Shows a spinner and blocks clicks |
+| `disabled` | boolean | Dims the button and blocks clicks |
+| `active` | boolean | Active state, set automatically for links and toggles |
+| `align` | `left` · `center` · `right` | Text alignment |
+| `direction` | flex direction (default `row`) | Layout of slots |
+| `alignItems` | flex `align-items` (default `center`) | Cross-axis alignment of slots |
+| `justify` | flex `justify-content` (default `center`) | Main-axis alignment of slots |
+| `minWidth` | CSS length (default `0`) | Minimum width of the button |
+| `href` | URL | Renders the button as a link |
+| `target` | `_self` · `_blank` · `_parent` · `_top` | Link target |
+| `download` | string | Link `download` attribute |
+| `pushState` | boolean | Navigates with `history.pushState` |
+| `autoActive` | `partial` (default) · `strict` · `strict-path-only` · `disabled` | URL matching for `active` |
+| `goBack` | URL or empty | Goes back in history, with a fallback URL |
+| `reset` | empty or provider name | Clears the current or named form data provider |
+| `name` / `value` | string | Form field written to the data provider |
+| `formDataProvider` | string | Data provider to write to (default: nearest ancestor) |
+| `radio` | boolean | Single choice among buttons with the same `name` |
+| `unique` | boolean | Like `radio`, but can be deselected |
+| `autoRepeat` | boolean | Repeats the click while the pointer is held |
+| `data-aria-label` | string | `aria-label` of the inner button |
+| `data-aria-labelledby` | string | `aria-labelledby` of the inner button |
+| `data-aria-controls` | string | `aria-controls` of the inner button |
+| `data-aria-expanded` | boolean | `aria-expanded` of the inner button |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Label |
+| `prefix` | Icon or text before the label |
+| `suffix` | Icon or text after the label |

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

@@ -1,12 +1,56 @@
 # Captcha
 
+**`sonic-captcha`** embeds an [ALTCHA](https://altcha.org) proof-of-work widget and makes the nearest form wait for it. Place it inside a form scope and put **`sonic-submit`** in its default slot: the widget renders above the slot content, and the submit sends only once a token is available.
+
+## Basic example
+
+The widget loads only on **HTTPS**. On plain HTTP the component renders nothing and the form is not blocked.
+
 <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-scope
+      serviceURL="/docs-mock-api"
+      formDataProvider="captcha-docs-form"
+      submitResultDataProvider="captcha-docs-result"
+    >
+      <sonic-captcha>
+        <sonic-input class="mb-3 block" name="email" type="email" label="Email" value="demo@example.com"></sonic-input>
+        <sonic-submit endPoint="api/register" onClick>
+          <sonic-button type="primary">Join the crew</sonic-button>
+        </sonic-submit>
+      </sonic-captcha>
+    </sonic-scope>
+  </template>
+</sonic-code>
+
+## Form integration
+
+The component writes to the publisher named by the closest `headersDataProvider`, or else `formDataProvider`, on itself or an ancestor. On connect it sets `needsCaptchaValidation` to `true`. When **`sonic-submit`** sees that flag, it requests a token, the captcha copies the solved ALTCHA payload into `captchaToken` and its key into `captchaKey`, and the request is sent. `needsCaptchaValidation` is stripped from the payload. On disconnect both fields are reset.
+
+<sonic-code language="typescript">
+  <template>
+{
+  email: "demo@example.com",
+  captchaKey: "…",
+  captchaToken: "…"
+}
   </template>
 </sonic-code>
-                
+
+## Key and challenge endpoint
+
+With no `key`, the component generates an encrypted key on connect. The widget fetches its challenge from the `chalengeUrl` property (a JavaScript property, not an attribute) with `key` and `maxNumber` (default `50000`) as query parameters. Point it at your own ALTCHA server and verify `captchaToken` there.
+
+Labels follow the page language: French when `<html lang>` starts with `fr`, English otherwise.
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `key` | string (default generated) | Key sent to the challenge endpoint and copied to `captchaKey` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Form fields and actions, rendered below the widget |
+
+No events.