@supersoniks/concorde 4.6.0 → 4.7.3

package/docs/src/core/components/functional/queue/queue.md

@@ -1,87 +1,72 @@
 # Queue
 
-**sonic-queue** loads content in batches based on the expression provided in the dataProviderExpression attribute.
-
-* Each batch is loaded by a [List component](#core/components/functional/list/list.md/list) whose dataProvider is created from the dataProviderExpression attribute.
-* Upon initialization, it looks at the dataFilterProvider attribute, which provides the address of a publisher.
-If this attribute is found, Queue listens to the provided publisher and resets itself whenever the content of the publisher is modified.
-The values provided in this publisher are added as parameters to each request.
-* The key property can be used to target a specific property in the API response as fetch does.
- 
-List extends the mixin [Subscriber](#docs/_core-concept/subscriber.md/subscriber)
-
-
-<sonic-code>
-  <template>
-    <sonic-queue
-        class="grid grid-cols-3 gap-3"
-        dataProviderExpression="communes?limit=$limit"
-        limit="30"
-        serviceURL="https://geo.api.gouv.fr/"
-        debug
-      >
-      <template>
-        <div data-bind ::inner-html="$nom" class="bg-neutral-100 p-2">
-          queue
-        </div>
-      </template>
-    </sonic-queue>
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <sonic-queue
-      lazyload
-      dataProviderExpression="api/users?page=$offset&per_page=$limit"
-      offset="2"
-      limit="5"
-      dataFilterProvider="filter"
-      targetRequestDuration="500"
-      serviceURL="https://reqres.in"
-      key="data"
-      debug
-    >
-        <template>
-          <div class="flex px-4 py-3 items-center gap-4">
-            <sonic-image data-bind ::src="$avatar" rounded="full" ratio="1/1" class="w-20 block"></sonic-image>
-            <div>
-              <div class="text-bold text-2xl mb-2">
-                <span data-bind ::inner-html="$first_name"></span>
-                <span data-bind ::inner-html="$last_name"></span>
-              </div>
-              <sonic-button data-bind ::href="mailto|$email" size="xs" variant="outline"> Contact </sonic-button>
-            </div>
-          </div>
-          <div class="border-0 border-t-2 border-t-neutral-200 w-full border-solid"></div>
-        </template>
-    </sonic-queue>
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <sonic-list
-      lazyload
-      fetch
-      dataProvider="api/users?page=2&per_page=5"
-      serviceURL="https://reqres.in"
-      key="data"
-      debug
-    >
-      <template>
-        <div class="flex px-4 py-3 items-center gap-4">
-          <sonic-image data-bind ::src="$avatar" rounded="full" ratio="1/1" class="w-20 block"></sonic-image>
-          <div>
-            <div class="text-bold text-2xl mb-2">
-              <span data-bind ::inner-html="$first_name"></span>
-              <span data-bind ::inner-html="$last_name"></span>
-            </div>
-            <sonic-button data-bind ::href="mailto|$email" size="xs" variant="outline"> Contact </sonic-button>
-          </div>
-        </div>
-        <div class="border-0 border-t-2 border-t-neutral-200 w-full border-solid"></div>
-      </template>
-    </sonic-list>
-  </template>
-</sonic-code>
+> **Try offline:** `serviceURL="/docs-mock-api"` — see [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api). Row rendering: [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) (`.items` property binding).
+
+**sonic-queue** loads data in **batches**. Each batch is an internal [List](#core/components/functional/list/list.md/list) with its own `dataProvider` (`…/list-item/0`, `…/1`, …).
+
+| Mechanism | Role |
+|-----------|------|
+| **`dataProviderExpression`** | API path template; `$offset` and `$limit` are replaced per batch |
+| **`lazyload`** | Load the next batch when the user scrolls near the end |
+| **`dataFilterProvider`** | Publisher id of a form (`formDataProvider`); field values are merged into the request query string |
+| **`filteredFields`** | Optional list of form field names to **exclude** from the query (space-separated) — omit when every field should be sent |
+| **`.items`**, **`.noItems`**, **`.separator`**, **`.skeleton`** | Lit callbacks forwarded to each batch list (use the **dot** — functions are properties, not attributes) |
+
+## Lazy load — `$offset` and `$limit`
+
+When the expression contains **`$offset`** and **`$limit`**, the queue:
+
+1. Fetches the first batch with `offset=0` (or the initial `offset` attribute) and `per_page=$limit`.
+2. On scroll, appends a batch with `offset` increased by the previous batch size.
+3. Stops when a batch returns fewer rows than `limit` (or none).
+
+The doc mock implements this on `GET /docs-mock-api/api/users?offset=…&per_page=…` (`paginateUsers` in `src/docs/mock-api/router.ts`).
+
+<docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>
+
+Wrap the queue in a **fixed height** with **`overflow-y-auto`** so lazy load triggers when scrolling inside the box (same layout as the [TS starter](https://github.com/supersoniks/create-concorde-ts-starter) `demo-queue-templates`).
+
+Try scrolling after load — batches of 4 users. Search e.g. `George`, `Bluth`, or `zzz` for empty results.
+
+### Expression example
+
+```typescript
+html`<sonic-queue
+  lazyload
+  serviceURL="/docs-mock-api"
+  dataProviderExpression="api/users?offset=$offset&limit=$limit"
+  key="data"
+  limit="4"
+  class="grid max-h-96 overflow-y-auto"
+  .items=${this.renderUser}
+></sonic-queue>`;
+```
+
+Without **`$offset`** in the expression, the queue behaves like a single list (one batch), e.g. geo communes below.
+
+## Filter — `dataFilterProvider` + `q`
+
+One search field (`name="q"`) on `formDataProvider="filter"`. The queue listens via **`dataFilterProvider="filter"`** and, on change:
+
+1. Resets loaded batches.
+2. Appends each non-empty form field to the query (here only **`q`** — no `filteredFields` needed).
+3. Fetches again from offset `0`.
+
+Use **`filteredFields`** only when the form has extra fields that must **not** be sent to the API (e.g. `filteredFields="rememberMe internalId"`).
+
+The mock API filters before pagination — same haystack logic as the starter (`filterDocsUsers` in `src/docs/mock-api/fixtures.ts`, used by `paginateUsers` in `router.ts` / Service Worker):
+
+```typescript
+const haystack = `${first_name} ${last_name} ${email}`.toLowerCase();
+return haystack.includes(q);
+```
+
+## Simple batch (no lazy scroll)
+
+Geo communes: expression uses **`$limit` only** (no `$offset`) — one request, one batch.
+
+<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
+
+## HTML `<template>` children
+
+Optional for hosts without Lit — see [HTML integration](#docs/_misc/html-integration.md/html-integration).

package/docs/src/core/components/functional/router/router.md

@@ -1,94 +1,77 @@
 # Router
 
-The router observes the document.location changes and updates its view as follows
+**sonic-router** watches `document.location` (pathname + hash) and renders the matching view.
 
-## Data-route / Basic
+From a **Lit** parent, pass a **`.routes`** map (property binding — same rule as [`.items` on list](#core/components/functional/list/list.md/list)): keys are path patterns, values are render functions. Use **`fallback`** when nothing matches.
 
-When the data-route attribute of a template matches the current url, the content of this template is rendered
+Legacy HTML **`<template data-route="…">`** remains for hosts without Lit — [HTML integration](#docs/_misc/html-integration.md/html-integration).
 
-<sonic-code>
-  <template>
-    <div class="flex gap-2 items-center">
-      <sonic-button href="#core/components/functional/router/router.md/router#home" size="xs">Home</sonic-button>
-      <sonic-button href="#core/components/functional/router/router.md/router#about" size="xs">About</sonic-button>
-      <sonic-button href="#core/components/functional/router/router.md/router#work" size="xs">Work</sonic-button>
-      <sonic-button href="#core/components/functional/router/router.md/router#contact" size="xs">Contact</sonic-button>
-    </div>
-    <sonic-router>
-      <template data-route="#home">
-        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">Home</div>
-      </template>
-      <template data-route="#about">
-        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">About</div>
-      </template>
-      <template data-route="#work">
-        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">Work</div>
-      </template>
-      <template data-route="#contact">
-        <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">Contact</div>
-      </template>
-    </sonic-router>
-  </template>
-</sonic-code>
+## Static routes (no parameters)
 
-## Data-route / Regexp
+Route keys are matched against `pathname + hash`. A simple hash route `#home` matches when the location contains that segment.
 
-You can use any RegExp in the data-route attribute of your templates to match the current location and to extract variables from it using capturing groups.
-A dataProvider attribute is generated using the dataProviderExpression where $1, $2... are replaced with this variables.
+On the **doc site**, the page URL is already a hash (`#…/router.md/router`). Demos append a **second** hash for in-page routes (`#…/router#home`), use **`href` + `autoActive="strict"`** on `sonic-button` for the active state, and `history.replaceState` on click so markdown is not reloaded (`setDocsDemoSubHash` in `src/docs/docs-location.ts`).
 
-**e.g.**, data-route="#couleur_<b class="text-danger">(\d+)</b>" => dataProviderExpression="api/unknown/<b class="text-danger">$1</b>"
+<docs-lit-demo for="docs-router-basic-demo"></docs-lit-demo>
 
-The rendered content of the matching template is scoped with this  **dataProvider**.
-You can make creative usage on this feature to generate dynamic content based on services.
+```typescript
+@state()
+private routes = {
+  "#home": () => html`<div>Home</div>`,
+  "#about": () => html`<div>About</div>`,
+  fallback: () => html`<div>Not found</div>`,
+};
 
-<sonic-code>
-  <template>
-    <sonic-list fetch dataProvider="api/unknown" key="data" class="flex gap-2 items-center" >
-      <template>
-        <sonic-button radio size="xs" data-bind ::href="#core/components/functional/router/router.md/router#couleur_$id">
-          <span data-bind ::inner-html="ucFirst|$name"></span>
-        </sonic-button>
-      </template>
-    </sonic-list>
-    <sonic-router>
-      <template data-route="#couleur_(\d+)" dataProviderExpression="api/unknown/$1">
-        <sonic-fetch>
-          <input type="color" disabled data-bind ::value="$data.color" class=" w-full h-10 my-3" />
-        </sonic-fetch>
-      </template>
-    </sonic-router>
-  </template>
-</sonic-code>
+html`
+  <sonic-button href="#home">Home</sonic-button>
+  <sonic-router .routes=${this.routes}></sonic-router>
+`;
+```
 
-## Data-route / Url-pattern
+| Key | When it runs |
+|-----|----------------|
+| `"#home"`, `"#about"`, … | `RegExp` or [url-pattern](https://www.npmjs.com/package/url-pattern) test succeeds on current location |
+| **`fallback`** | No other route matched (not an attribute — a key on the same object) |
 
-Same as RegExp but using <a href="https://www.npmjs.com/package/url-pattern" target="_blank">url patterns</a>  
-**e.g.**, data-route="#couleur_<b class="text-danger">:id</b>" => dataProviderExpression="api/unknown/<b class="text-danger">:id</b>"
+## Routes with parameters
 
-<sonic-code>
-  <template>
-    <sonic-list fetch dataProvider="api/unknown" key="data" class="flex gap-2 items-center" >
-      <template>
-        <sonic-button radio size="xs" data-bind ::href="#core/components/functional/router/router.md/router#couleur_$id">
-          <span data-bind ::inner-html="ucFirst|$name"></span>
-        </sonic-button>
-      </template>
-    </sonic-list>
-    <sonic-router>
-      <template data-route="/*#couleur_:id" dataProviderExpression="api/unknown/:id">
-        <sonic-fetch>
-          <input type="color" disabled data-bind ::value="$data.color" class=" w-full h-10 my-3" />
-        </sonic-fetch>
-      </template>
-    </sonic-router>
-  </template>
-</sonic-code>
+Two styles (see `router.demo.ts` and `docs-router-params-demo`):
+
+### Url-pattern (`:name`)
+
+Key uses **`:param`** segments. The render function receives an **object** `{ param: string }`.
+
+<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
+
+```typescript
+"#couleur/:id": ({ id }) => html`<p>Colour id: ${id}</p>`,
+```
 
-## Redirect
+### RegExp (capturing groups)
 
-Redirect allows to redirect to a url when a data is provided.
-Here Redirect waits that a data is available in the property *theData* of the dataProvider *stupid-data-set-id*
-We are then redirected to the url *#data-is-set* which does nothing in itself.
+Key is a **RegExp** string with `(\d+)` / `(\w+)` groups. The render function receives an **array** of captured strings (in order).
+
+```typescript
+"#products/(\\d+)/(\\w+)": ([productId, slug]) =>
+  html`<p>Product ${productId}, slug ${slug}</p>`,
+```
+
+With parameters you usually render data directly in Lit (`${id}`). The old **`<template data-route>` + `dataProviderExpression`** pattern scoped a `dataProvider` for `data-bind` / fetch children — prefer **`@subscribe`** or explicit props when using `.routes`.
+
+## `.routes` binding
+
+Always use **`.routes=${…}`** in Lit templates: route handlers are functions and must be set as **properties**, not HTML attributes.
+
+## Optional attributes
+
+| Attribute | Role |
+|-----------|------|
+| **`basePath`** | Prefix for pattern matching (default allows optional leading segments) |
+| **`fallBackRoute`** | If set and no template/route matches, navigates to this URL (redirect). Distinct from **`routes.fallback`** which only renders content |
+
+## `sonic-redirect`
+
+Separate component: redirect when data appears on a publisher (login steps, wizards). Not part of the `.routes` map.
 
 <sonic-code>
   <template>
@@ -101,29 +84,11 @@ We are then redirected to the url *#data-is-set* which does nothing in itself.
         Delete the data and do a history.back()
       </sonic-button>
     </div>
-    
   </template>
 </sonic-code>
 
-Example of use : use with a router and a submit to manage the steps of login/logout, display of user info.
-
-## Fallback
-
-The fallback route is rendered when no other route matches the current location.
-
-<sonic-code>
-  <sonic-router>
-    <template data-route="#home">
-      <div>Home</div>
-    </template>
-    <template data-route="#fallback">
-      <div>Fallback</div>
-    </template>
-  </sonic-router>
-</sonic-code>
-
-## Programmatic routes
-
-
+Example: combine with **`.routes`** and **submit** for login / logout / profile steps.
 
+## Package demo
 
+`sonic-router-demo` (`router.demo.ts`) — home, user profile (`#user/:id/:slug`), products RegExp, **fallback** 404.

package/docs/src/core/components/functional/states/states.md

@@ -41,7 +41,7 @@ When using **capturing groups ()** the stored values are accessible via the **da
 
 <sonic-code>
   <template>
-    <div  serviceURL="https://reqres.in">
+    <div  serviceURL="/docs-mock-api">
       <sonic-list formDataProvider="states-regexp-example" fetch dataProvider="api/unknown" key="data" class="flex gap-2 items-center" >
         <template>
           <sonic-button radio size="xs" name="selection" data-bind ::value="#couleur_$id">
@@ -67,7 +67,7 @@ Same as RegExp but using <a href="https://www.npmjs.com/package/url-pattern" tar
 
 <sonic-code>
   <template>
-    <div serviceURL="https://reqres.in">
+    <div serviceURL="/docs-mock-api">
       <sonic-list formDataProvider="states-regexp-example" fetch dataProvider="api/unknown" key="data" class="flex gap-2 items-center" >
         <template>
           <sonic-button radio size="xs" name="selection" data-bind ::value="#couleur_$id">

package/docs/src/core/components/functional/submit/submit.md

@@ -1,58 +1,90 @@
 # Submit
 
-## The submit element is used to send data to a rest service
- * The api is set up like a [fetcher](#core/components/functional/fetch/fetch.md/fetch).
- * The *formDataProvider* attribute points to the adress where the data is held by a publisher.
- * This attribute is also used by form elements such as *sonic-input*, or *sonic-select*, which fill this publisher with their *value* attribute according to their *name* attribute
- * The *method* attribute allows you to choose the sending method: *put/delete/post*, *post* being the default method.
- * If the *onClick* attribute is present, the data is sent when the content is clicked on
- * If the *onEnterKey* attribute is present, data is sent when the enter key of an element contained in the *sonic-submit* with focus is pressed
- * During sending, *sonic-submit* elements with the same *dataProvider* attribute have the *disabled="disabled "* property, which has the effect of disabling their content
- * The *clearedDataOnSuccess* attribute can be used to clear the data from the corresponding dataProvider when the call to the api has provided a result.
-
-## Form example
-<sonic-code>
-  <template>
-  <sonic-scope
-        serviceURL="https://reqres.in" dataProvider="api/register"
-        formDataProvider="submit-example" submitResultDataProvider="submit-example-result"
-        method="post"
-        class="max-w-lg block"
-      >
-        <sonic-submit onEnterKey>
-          <div class="grid grid-cols-2 gap-4 mb-4 ">
-            <sonic-input required name="email" type="email" value="eve.holt@reqres.in"></sonic-input>
-            <sonic-input required type="password" name="password" value="pistol"></sonic-input>
-          </div>
-        </sonic-submit>
-        <sonic-submit onClick>
-          <sonic-button type="success" class="w-full">Submit</sonic-button>
-        </sonic-submit>
-    </sonic-scope>
-  </template>
-</sonic-code>
+> **Live demos:** `<docs-lit-demo>` + `src/docs/example/docs-submit-demos.ts`. Use [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) (`serviceURL="/docs-mock-api"`).
 
+## Overview
 
+**sonic-submit** sends the **formDataProvider** publisher to a REST endpoint (same configuration model as [fetch](#core/components/functional/fetch/fetch.md/fetch): `serviceURL` on an ancestor, path via `dataProvider` or `endPoint`).
 
+| Trigger | Attribute |
+|---------|-----------|
+| Click inside the slot | `onClick` |
+| Enter in a focused field inside the slot | `onEnterKey` |
 
+| Data / API | Attribute / property | Notes |
+|------------|----------------------|--------|
+| Form fields | `formDataProvider` on ancestor | Filled by `sonic-input`, `sonic-select`, etc. via `name` |
+| Result after call | `submitResultDataProvider` on ancestor | Whole result object (after optional `submit-result-key`) |
+| Slice of JSON result | `submit-result-key` on **sonic-submit** | Dot path, e.g. `data` when the API returns `{ data: { … } }` |
+| HTTP verb | `method` on **sonic-submit** | `post` (default), `put`, `patch`, `delete`, `get` — not inherited from `sonic-scope` |
+| Path override | `endPoint` on **sonic-submit** | Wins over ancestor `dataProvider` |
+| JSON vs multipart | `sendAsFormData` on **sonic-submit** | `FormData` body, still expects JSON response |
+| Reset publishers | `clearedDataOnSuccess` on ancestor | Space-separated `DataProviderKey.path` values; runs when a **result object** is returned (including error payloads with `messages`) |
+| Browser form POST | `native` on **sonic-submit** | See [Native HTML form](#native-html-form) |
+| Result event | — | Bubbles `submit` `CustomEvent` with `detail` = result |
+| Credential Management API | `usernameKey`, `passwordKey` on **sonic-submit** | After a **successful** HTTP response, stores login if those keys exist in the payload (defaults: `username`, `password`) |
+| ALTCHA / captcha | `needsCaptchaValidation` on form/header publisher | Defers send until token is set — see [Captcha](#core/components/ui/captcha/captcha.md/captcha) |
 
-## Result handling example
+While a REST submit runs, the slot is wrapped with `data-disabled` (faded, no pointer events). With **`native`**, validation and loader still run, then the browser performs a normal form submission.
 
-Result will show when something has been submit because the **dataprovider** used in this example is the same as the **submitResultDataProvider** used in the previous form.
-<sonic-code>
-  <template>
-      <div dataProvider="submit-example-result">
-        <div>Id : <span data-bind ::inner-html="$id"></span></div>
-        <div>Token : <span data-bind ::inner-html="$token"></span></div>
-        <div data-bind ::inner-html="$error"></div>
-      </div>
-  </template>
-</sonic-code>
+## Form and result handling
+
+POST to mock `api/register`; result publisher `submit-example-result`.
+
+<docs-lit-demo for="docs-submit-demo"></docs-lit-demo>
+
+## Native HTML form
+
+With **`native`**, Concorde does **not** call `fetch`. After form validation it:
+
+1. Copies **formDataProvider** values into matching `<input>` / `<select>` / `<textarea>` inside the closest **`<form>`** (creates hidden inputs if needed).
+2. Programmatically clicks a hidden native `type="submit"` control (`name` / `value` on **sonic-submit** if you need them).
+
+Use a real `<form action="…" method="post">` ancestor. For SPAs, a named **`target`** (e.g. iframe) avoids leaving the doc page.
+
+<docs-lit-demo for="docs-submit-native-demo"></docs-lit-demo>
+
+## sendAsFormData
+
+Sends fields as **`multipart/form-data`** instead of `application/json` (response is still parsed as JSON).
 
+<docs-lit-demo for="docs-submit-formdata-demo"></docs-lit-demo>
 
-## dot notation
+## submit-result-key
 
-You can write the folowing code where the name attribute is written in dot notation.
+When the API wraps the payload (e.g. `{ data: { id, token } }`), set **`submit-result-key="data"`** on **sonic-submit** so **submitResultDataProvider** receives only the inner object.
+
+<docs-lit-demo for="docs-submit-result-key-demo"></docs-lit-demo>
+
+Mock endpoint: `POST /docs-mock-api/api/register/nested`.
+
+## clearedDataOnSuccess
+
+Lists one or more publisher ids (space-separated). After the API returns a result object, each is set to `{}` — useful to reset the form publisher.
+
+<docs-lit-demo for="docs-submit-clear-demo"></docs-lit-demo>
+
+## Custom `submit` event
+
+Listen for the bubbling **`submit`** event; **`event.detail`** is the same result written to **submitResultDataProvider** (if configured).
+
+<docs-lit-demo for="docs-submit-event-demo"></docs-lit-demo>
+
+## endPoint vs dataProvider
+
+Ancestor **`dataProvider`** is the default path; **`endPoint`** on **sonic-submit** overrides it for that button only.
+
+<docs-lit-demo for="docs-submit-endpoint-demo"></docs-lit-demo>
+
+## method="get"
+
+Appends publisher fields as a query string on the endpoint, then performs a GET. The mock route `api/register/echo` returns the query for inspection.
+
+<docs-lit-demo for="docs-submit-get-demo"></docs-lit-demo>
+
+## dot notation (formDataProvider shape)
+
+You can use dot notation in **`name`** on form controls; the publisher stores nested objects:
 
 <sonic-code>
   <template>
@@ -65,19 +97,18 @@ You can write the folowing code where the name attribute is written in dot notat
   </template>
 </sonic-code>
 
-The data will be stored in the following format:
+Stored shape:
 
- <sonic-code language="typescript">
+<sonic-code language="typescript">
   <template>
   {
-    email: {
-      value: "eve.holt@reqres.in",
-    },
-    details: {
-      password: {
-        value: "pistol",
-      },
-    },
+    email: { value: "eve.holt@reqres.in" },
+    details: { password: { value: "pistol" } }
   }
   </template>
-</sonic-code>
+</sonic-code>
+
+## Related
+
+- [Captcha](#core/components/ui/captcha/captcha.md/captcha) — submit waits for `captchaToken` when validation is required.
+- [HTML integration](#docs/_misc/html-integration.md/html-integration) — legacy `data-bind` result blocks; prefer **submitResultDataProvider** + `@subscribe` in Lit demos.

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

@@ -3,7 +3,7 @@
 <sonic-code>
   <template>
   <sonic-captcha formDataProvider="captchaTestDataProvider" key="6Leq5V0iAAAAAB-41DlWN335jDlcIuXmhNtdd00t">
-    <sonic-submit serviceURL="https://reqres.in" endPoint="api/unknown" onclick>
+    <sonic-submit serviceURL="/docs-mock-api" endPoint="api/unknown" onclick>
       <sonic-button  class="mt-4">Submit with captcha</sonic-button>
     </sonic-submit>
   </sonic-captcha>
@@ -21,4 +21,4 @@
   </sonic-captcha>
   </template>
 </sonic-code>
-                
+                

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

@@ -51,7 +51,7 @@
     <sonic-card-main >
       <h3>Main area</h3>
       <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-      <iframe width="560" height="315" src="https://www.youtube.com/embed/IZTOtyksyPs" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+      <iframe width="560" height="315" src="https://www.youtube.com/embed/aqz-KE-bpKQ" title="Big Buck Bunny (Blender Foundation)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
     </sonic-card-main>
   </sonic-card>
   </template>

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

@@ -70,35 +70,8 @@
   </template>
 </sonic-code>
 
-## Example of use
-<sonic-code>
-  <template>
-    <sonic-subscriber dataProvider="jokeFilter" class="text-xl my-4 block font-bold">
-      Remove following jokes :
-      <sonic-value key="blacklistFlags" class="block text-sm"></sonic-value>
-    </sonic-subscriber>
-    <div formDataProvider="jokeFilter" class="grid grid-cols-2 lg:grid-cols-3 gap-x-6 gap-y-2 mt-2 mb-3">
-      <sonic-checkbox name="blacklistFlags"  value="nsfw">nsfw</sonic-checkbox>
-      <sonic-checkbox name="blacklistFlags"  value="religious">religious</sonic-checkbox>
-      <sonic-checkbox name="blacklistFlags"  value="political">political</sonic-checkbox>
-      <sonic-checkbox name="blacklistFlags"  value="racist" checked disabled>racist</sonic-checkbox>
-      <sonic-checkbox name="blacklistFlags"  value="sexist" checked disabled>sexist</sonic-checkbox>
-      <sonic-checkbox name="blacklistFlags"  value="explicit">explicit</sonic-checkbox>
-    </div>
-    <sonic-queue
-      lazyload
-      dataProviderExpression="joke/Any?amount=10&lang=en"
-      dataFilterProvider="jokeFilter"
-      serviceURL="https://v2.jokeapi.dev"
-      key="jokes"
-    >
-      <template>
-        <div class="border-0 border-b-[1px] border-b-neutral-300  py-3 leading-tight">
-          <sonic-value key="joke"></sonic-value>
-          <sonic-value key="setup" class="font-bold"></sonic-value><br>
-          <sonic-value key="delivery"></sonic-value>
-        </div>
-      </template>
-    </sonic-queue>
-  </template>
-</sonic-code>
+## Example of use — blacklist + queue
+
+Checked **`blacklistFlags`** values are sent to the mock API (`?blacklistFlags=racist,sexist,…`), which excludes jokes whose **`flags`** match (see `filterDocsJokes` in `src/docs/mock-api/fixtures.ts`).
+
+<docs-lit-demo for="docs-joke-blacklist-demo"></docs-lit-demo>