@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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

@@ -1,112 +1,87 @@
 # States
 
-**`sonic-states`** renders the child `<template>` whose `data-value` matches a value of its data provider. Use it to switch views on a status or a selection; point `data-path` at the value, or set `state` directly.
-
-## Basic example
-
-Each `data-value` is a RegExp tested against the value. All matching templates render; a template with `data-value=""` renders while the value is empty.
+ ### sonic-states displays different states depending on the value of a sub-property of its dataProvider (data-path attribute in dot notation):
+ * It loops over its child templates and tests if the regexp contained in the *data-value* attribute matches the value of the property
+ * If so, the content of the corresponding template is displayed as a state.
+ * If the attribute dataProviderExpression is provided the content is surrounded by a div:
+ * The "dataProvider" attribute of this div is the result of calling the replace function on the property value with the regexp and dataproviderExpression as parameters.
+ * The subscribers/fetch... of the template will refer to this dataProvider
+ * You can also use url-pattern expressions for the route parameters, see the examples
+ *
+ **Examples**
+ * With ma.property= 2 :
+ * RegExp data-value = (\d+) and dataproviderExpression = /user/$1 the dataProvider attribute will be "/user/2"
+ * url-pattern data-value = :id and dataproviderExpression = /user/:id the dataProvider attribute will be "/user/2
+
+## Basic
 
 <sonic-code>
   <template>
-    <div class="flex flex-wrap gap-2" formDataProvider="states-flight-status">
-      <sonic-button radio name="status" value="boarding" size="xs">Boarding</sonic-button>
-      <sonic-button radio name="status" value="delayed" size="xs">Delayed</sonic-button>
-      <sonic-button radio name="status" value="landed" size="xs">Landed</sonic-button>
+    <div class="flex gap-2 items-center" formDataProvider="states-basic-example">
+      <sonic-button radio name="selection" value="#home" checked size="xs">Home</sonic-button>
+      <sonic-button radio name="selection" value="#about" size="xs">About</sonic-button>
+      <sonic-button radio name="selection" value="#work" size="xs">Work</sonic-button>
+      <sonic-button radio name="selection" value="#contact" size="xs">Contact</sonic-button>
     </div>
-    <div class="my-4 rounded border p-4 text-center text-2xl text-neutral-700">
-      <sonic-states dataProvider="states-flight-status" data-path="status">
-        <template data-value="">Select a status</template>
-        <template data-value="^boarding$">CN 001 is boarding at gate B12</template>
-        <template data-value="^delayed$">CN 001 is delayed by 45 minutes</template>
-        <template data-value="^landed$">CN 001 has landed at JFK</template>
-      </sonic-states>
+    <div class="text-center text-neutral-700 border rounded text-4xl  my-6 p-3 ">
+    <sonic-states dataProvider="states-basic-example" data-path="selection">
+      <template data-value="#home">Home</template>
+      <template data-value="#about">About</template>
+      <template data-value="#work">Work</template>
+      <template data-value="#contact">Contact</template>
+    </sonic-states>
     </div>
   </template>
 </sonic-code>
 
-Templates without `data-value` are ignored, and nothing renders when no template matches.
+## Regexp
 
-## Captured values
-
-Add `dataProviderExpression` to wrap the template content in an element whose `dataProvider` is built from the value: `$1` · `$2`… for RegExp groups. Children such as [sonic-fetch](/core/components/functional/fetch) then read that provider.
+When using **capturing groups ()** the stored values are accessible via the **dataProviderExpression**  
+**e.g.**, data-value="#couleur_<b class="text-danger">(\d+)</b>" => dataProviderExpression="api/unknown/<b class="text-danger">$1</b>"
 
 <sonic-code>
   <template>
-    <div serviceURL="/docs-mock-api">
-      <div class="flex flex-wrap gap-2" formDataProvider="states-flight-pick">
-        <sonic-button radio name="flight" value="flight_001" size="xs">CN 001</sonic-button>
-        <sonic-button radio name="flight" value="flight_102" size="xs">CN 102</sonic-button>
-        <sonic-button radio name="flight" value="flight_305" size="xs">CN 305</sonic-button>
-      </div>
-      <sonic-states dataProvider="states-flight-pick" data-path="flight">
-        <template data-value="flight_(\d+)" dataProviderExpression="flights?q=$1">
-          <sonic-fetch key="flights.0"></sonic-fetch>
-          <p class="my-4">
-            <sonic-value key="code"></sonic-value> to
-            <sonic-value key="city"></sonic-value>:
-            <sonic-value key="status"></sonic-value>
-          </p>
+    <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">
+            <span data-bind ::inner-html="ucFirst|$name"></span>
+          </sonic-button>
+        </template>
+      </sonic-list>
+      <sonic-states dataProvider="states-regexp-example" data-path="selection">
+        <template data-value="#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-states>
     </div>
   </template>
 </sonic-code>
 
-With [url-pattern](https://www.npmjs.com/package/url-pattern) syntax, name the segments instead: `data-value="flight/:code"` and `dataProviderExpression="flights?q=:code"`.
+## Url-pattern
 
-## Inverted matching
-
-With `inverted`, the value is the RegExp and each `data-value` is the tested text. Use it to show several templates at once.
+Same as RegExp but using <a href="https://www.npmjs.com/package/url-pattern" target="_blank">url patterns</a>  
+**e.g.**, data-value="#couleur_<b class="text-danger">:id</b>" => dataProviderExpression="api/unknown/<b class="text-danger">:id</b>"
 
 <sonic-code>
   <template>
-    <div class="flex flex-wrap gap-2" formDataProvider="states-board-filter">
-      <sonic-button radio name="filter" value=".*" size="xs">All</sonic-button>
-      <sonic-button radio name="filter" value="delayed|cancelled" size="xs">Disrupted</sonic-button>
-      <sonic-button radio name="filter" value="on-time" size="xs">On time</sonic-button>
+    <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">
+            <span data-bind ::inner-html="ucFirst|$name"></span>
+          </sonic-button>
+        </template>
+      </sonic-list>
+      <sonic-states dataProvider="states-regexp-example" data-path="selection">
+        <template data-value="#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-states>
     </div>
-    <sonic-states inverted dataProvider="states-board-filter" data-path="filter" class="my-4 flex flex-col gap-1">
-      <template data-value="on-time"><p>CN 014 · LHR · on time</p></template>
-      <template data-value="delayed"><p>CN 102 · GIG · delayed</p></template>
-      <template data-value="cancelled"><p>CN 305 · IAD · cancelled</p></template>
-    </sonic-states>
   </template>
-</sonic-code>
-
-While the value is empty, every template renders.
-
-## Render functions
-
-From Lit, pass a `.states` map instead of templates: keys are RegExp or url-pattern expressions, values are render functions. RegExp groups arrive as an array, url-pattern segments as an object, and `fallback` renders when no key matches.
-
-<sonic-code language="typescript">
-  <template>
-private states = {
-  boarding: () => html`&lt;p&gt;Boarding at gate B12&lt;/p&gt;`,
-  "delayed_(\\d+)": ([minutes]) => html`&lt;p&gt;Delayed by ${minutes} min&lt;/p&gt;`,
-  "flights/:code/:status": ({ code, status }) => html`&lt;p&gt;${code}: ${status}&lt;/p&gt;`,
-  fallback: () => html`&lt;p&gt;Unknown status&lt;/p&gt;`,
-};
-
-html`&lt;sonic-states dataProvider="flight" data-path="status" .states=${this.states}&gt;&lt;/sonic-states&gt;`;
-  </template>
-</sonic-code>
-
-## API reference
-
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `dataProvider` | string | Provider holding the value. Inherited from the closest ancestor when omitted |
-| `data-path` | string | Dot path of the value in the provider |
-| `state` | string | Value to match when `data-path` is not set |
-| `inverted` | boolean (default `false`) | Uses the value as the RegExp and each `data-value` as the tested text |
-| `states` | object (property) | Render functions keyed by expression, plus `fallback`. Templates are used only when nothing in the map renders |
-
-| Template attribute | Description |
-|--------------------|-------------|
-| `data-value` | RegExp or url-pattern matched against the value. `""` matches an empty value |
-| `dataProviderExpression` | Builds the `dataProvider` of a wrapper around the template content from `$1`… or `:name` |
-
-| Slot | Description |
-|------|-------------|
-| *(default)* | `<template data-value>` children |
+</sonic-code>

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

@@ -1,106 +1,114 @@
 # Submit
 
-**`sonic-submit`** sends the form publisher named by `formDataProvider` to a REST endpoint and writes the response to `submitResultDataProvider`. The request is configured like [Fetch](/core/components/functional/fetch): `serviceURL` on an ancestor, path from the ancestor `dataProvider` or from `endPoint`. Form fields such as `sonic-input` fill the publisher through their `name`.
+> **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"`).
 
-## Basic example
+## Overview
 
-`onClick` sends on a click inside the element, `onEnterKey` on Enter in a focused field inside it. The method defaults to `post` and the body to JSON. Fields are validated first; while the request runs, the content is faded and not clickable.
+**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) |
+
+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.
+
+## Form and result handling
+
+POST to mock `api/register`; result publisher `submit-example-result`.
 
 <docs-lit-demo for="docs-submit-demo"></docs-lit-demo>
 
-## Result key
+## Native HTML form
 
-When the API wraps its payload (`{ data: { id, token } }`), set `submitResultKey` to a dot path so `submitResultDataProvider` receives only that part.
+With **`native`**, Concorde does **not** call `fetch`. After form validation it:
 
-<docs-lit-demo for="docs-submit-result-key-demo"></docs-lit-demo>
+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).
 
-## Reset after submit
+Use a real `<form action="…" method="post">` ancestor. For SPAs, a named **`target`** (e.g. iframe) avoids leaving the doc page.
 
-`clearedDataOnSuccess` on an ancestor lists publisher ids, separated by spaces, that are set to `{}` once the API returns a result. This includes error results with `messages`.
+<docs-lit-demo for="docs-submit-native-demo"></docs-lit-demo>
 
-<docs-lit-demo for="docs-submit-clear-demo"></docs-lit-demo>
+## sendAsFormData
 
-## Submit event
+Sends fields as **`multipart/form-data`** instead of `application/json` (response is still parsed as JSON).
 
-After each request, `sonic-submit` dispatches a bubbling `submit` event whose `detail` is the result, the same value written to `submitResultDataProvider`.
+<docs-lit-demo for="docs-submit-formdata-demo"></docs-lit-demo>
 
-<docs-lit-demo for="docs-submit-event-demo"></docs-lit-demo>
+## submit-result-key
 
-## Endpoint override
+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.
 
-`endPoint` on `sonic-submit` replaces the ancestor `dataProvider` as the request path, for this element only.
+<docs-lit-demo for="docs-submit-result-key-demo"></docs-lit-demo>
 
-<docs-lit-demo for="docs-submit-endpoint-demo"></docs-lit-demo>
+Mock endpoint: `POST /docs-mock-api/api/register/nested`.
 
-## HTTP method
+## clearedDataOnSuccess
 
-Set `method` to `put` · `patch` · `delete` · `get` (default `post`). It is read on `sonic-submit` only, never inherited. With `get`, the fields are appended to the endpoint as a query string.
+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-get-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-clear-demo"></docs-lit-demo>
 
-## Multipart body
+## Custom `submit` event
 
-`sendAsFormData` sends the fields as `multipart/form-data` instead of JSON. The response is still parsed as JSON.
+Listen for the bubbling **`submit`** event; **`event.detail`** is the same result written to **submitResultDataProvider** (if configured).
 
-<docs-lit-demo for="docs-submit-formdata-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-event-demo"></docs-lit-demo>
 
-## Native form
+## endPoint vs dataProvider
 
-With `native`, no request is made: after validation, the publisher values are copied into the matching controls of the closest `<form>` (hidden inputs are created when missing), then the browser submits the form. `name` and `value` on `sonic-submit` are sent as the submit button pair. Use a `target` iframe to stay on the page.
+Ancestor **`dataProvider`** is the default path; **`endPoint`** on **sonic-submit** overrides it for that button only.
 
-<docs-lit-demo for="docs-submit-native-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-endpoint-demo"></docs-lit-demo>
 
-## Nested fields
+## method="get"
 
-A dot in a field `name` stores a nested object in the form publisher, and the body is sent with the same shape.
+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>
-    <sonic-scope formDataProvider="submit-example-dot-notation">
-      <div class="grid grid-cols-2 gap-4">
-        <sonic-input label="Passenger" name="passenger.name" value="Ada Lindqvist"></sonic-input>
-        <sonic-input label="Seat" name="passenger.seat" value="2A"></sonic-input>
+  <sonic-scope formDataProvider="submit-example-dot-notation">
+     <div class="grid grid-cols-2 gap-4 mb-4 ">
+        <sonic-input required name="email.value" type="email" value="eve.holt@reqres.in"></sonic-input>
+        <sonic-input required type="password" name="details.password.value" value="pistol"></sonic-input>
       </div>
     </sonic-scope>
   </template>
 </sonic-code>
 
+Stored shape:
+
 <sonic-code language="typescript">
   <template>
-{ passenger: { name: "Ada Lindqvist", seat: "2A" } }
+  {
+    email: { value: "eve.holt@reqres.in" },
+    details: { password: { value: "pistol" } }
+  }
   </template>
 </sonic-code>
 
-## API reference
-
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `onClick` | boolean | Sends on click inside the element |
-| `onEnterKey` | boolean | Sends on Enter in a focused field inside the element |
-| `method` | `post` · `put` · `patch` · `delete` · `get` (default `post`) | HTTP method. `get` sends the fields as a query string |
-| `endPoint` | string | Request path. Overrides the ancestor `dataProvider` |
-| `submitResultKey` | string | Dot path of the response part written to `submitResultDataProvider` |
-| `sendAsFormData` | boolean | Sends `multipart/form-data` instead of JSON |
-| `native` | boolean | Fills and submits the closest `<form>` instead of calling the API |
-| `name` · `value` | string | Submit button pair added to a native form submission |
-| `disabled` | boolean | Ignores triggers. Set while a request runs |
-| `usernameKey` · `passwordKey` | string (default `username` · `password`) | After a successful response, fields stored with the Credential Management API when both are present |
-
-| Ancestor attribute | Description |
-|--------------------|-------------|
-| `serviceURL` | API base URL |
-| `dataProvider` | Default request path |
-| `formDataProvider` | Publisher sent as the body. Required |
-| `submitResultDataProvider` | Publisher receiving the result |
-| `headersDataProvider` | Publisher sent as request headers |
-| `clearedDataOnSuccess` | Space-separated publisher ids reset to `{}` after a result |
-
-When the form or headers publisher has `needsCaptchaValidation`, the request waits for a [Captcha](/core/components/ui/captcha) token. A network failure produces a result with an error message in `messages`.
-
-| Event | Detail |
-|-------|--------|
-| `submit` | The result (after `submitResultKey`) |
-
-| Slot | Description |
-|------|-------------|
-| *(default)* | Fields and buttons that trigger the submission |
+## 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/functional/value/value.md

@@ -1,47 +1,35 @@
 # Value
 
-**`sonic-value`** prints one value from a data provider and updates when it changes. Set `dataProvider` (or inherit it from an ancestor) and point `key` at the field to show.
-
-## Basic example
-
-The form below writes `cabin` into the `value-checkin` provider; `sonic-value` reads it back.
+Simply shows a value from a data provider.
+You can target sub data value using dot syntax.
+The value reacts to changes.
 
+* Below is a form that helps you to set a value for the field "preference" in the data target with id "value-example"
 <sonic-code>
   <template>
-    <div formDataProvider="value-checkin" class="flex flex-wrap gap-4 mb-3">
-      <sonic-radio name="cabin" value="Economy" checked>Economy</sonic-radio>
-      <sonic-radio name="cabin" value="Business">Business</sonic-radio>
-      <sonic-radio name="cabin" value="First">First</sonic-radio>
+    <div formDataProvider="value-example">
+      which one do you prefer  ?
+      <sonic-radio name="preference" checked value="dogs"> Dogs</sonic-radio>
+      <sonic-radio name="preference" value="cats"> Cats</sonic-radio>
     </div>
-    <p>Cabin: <sonic-value dataProvider="value-checkin" key="cabin"></sonic-value></p>
   </template>
 </sonic-code>
-
-The value is rendered as HTML, not escaped: only display trusted data. When the value is an object or is missing, nothing is printed.
-
-## Nested key
-
-`key` accepts a dot path, array indexes included.
-
+* Then you can see live value of the preference using this code :
 <sonic-code>
   <template>
-    <sonic-subscriber dataProvider="value-passenger" props='{"passenger":{"name":"Ada Lindqvist","seats":[{"number":"2A"}]}}'></sonic-subscriber>
-    <p>
-      <sonic-value dataProvider="value-passenger" key="passenger.name"></sonic-value>
-      is seated in
-      <sonic-value dataProvider="value-passenger" key="passenger.seats.0.number"></sonic-value>
-    </p>
+  I prefer <sonic-value dataProvider="value-example" key="preference"></sonic-value> 
+  </template>
+</sonic-code>
+* If you have more complex data like this
+<sonic-code>
+  <template>
+    <sonic-subscriber dataProvider="value-example-2" props='{"my":{"complex":[{"data":"👋 Hi There"}]}}'></sonic-subscriber> 
+  </template>
+</sonic-code>
+* You can target it with the dot syntax
+<sonic-code>
+  <template>
+  <sonic-value dataProvider="value-example-2" key="my.complex.0.data"></sonic-value> 
   </template>
 </sonic-code>
 
-## API reference
-
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `dataProvider` | string | Provider to read. Inherited from the closest ancestor when omitted |
-| `key` | string (required) | Dot path of the value in the provider |
-
-| Slot | Description |
-|------|-------------|
-| *(default)* | Content rendered after the value |
-| `prefix` · `suffix` | Rendered around the default slot, after the value |