@supersoniks/concorde 5.0.2 → 5.0.3

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

@@ -0,0 +1,87 @@
+# States
+
+ ### 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 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="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>
+
+## Regexp
+
+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">
+      <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>
+
+## Url-pattern
+
+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 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>
+  </template>
+</sonic-code>

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

@@ -0,0 +1,114 @@
+# Submit
+
+> **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) |
+
+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>
+
+## 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>
+
+## submit-result-key
+
+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>
+  <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>
+  {
+    email: { value: "eve.holt@reqres.in" },
+    details: { password: { value: "pistol" } }
+  }
+  </template>
+</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/functional/subscriber/subscriber.md

@@ -0,0 +1,91 @@
+# Subscriber
+
+La mixin Subscriber permet lier un composant à un publisher.
+La liaison à un publisher se fait via l'attribut *dataProvider* du composant qui représente ce que l'on obtient en appellant PublisherManager.get(dataProvider).
+
+Les propriétés du composant sont automatiquement remplies avec les propriétés du même nom dans les données du publisher.
+
+Le composant est automatiquement mis à jour lorsque les données du publisher sont mises à jour.
+
+## DataProvider
+
+**Id** of the dataProvider that the component will **subscribe** to
+
+<sonic-code>
+  <template>
+    <sonic-subscriber dataProvider="id_that_the_subsriber_will_subscribe_to" debug>
+      <sonic-button> custom dataProvider id</sonic-button>
+    </sonic-subscriber>
+    <sonic-subscriber debug>
+      <sonic-button> default id : pageHTML</sonic-button>
+    </sonic-subscriber>
+  </template>
+</sonic-code>
+
+## Props
+
+Data object (json) that will be passed to the dataProvider
+
+<sonic-code>
+  <template>
+    <sonic-subscriber props='{"data":"Hello world"}' debug>
+      <sonic-button> Hover to see the data</sonic-button>
+    </sonic-subscriber>
+  </template>
+</sonic-code>
+
+
+## Debug
+
+**Helper**, display the data held by the dataProvider in a floating div
+
+<sonic-code>
+  <template>
+    <sonic-subscriber debug>
+      <sonic-button> see the dataProvider'data </sonic-button>
+    </sonic-subscriber>
+  </template>
+</sonic-code>
+
+
+## NoAutofill
+
+<sonic-alert status="info">Docs coming soon</sonic-alert>
+
+## PropertyMap
+
+<sonic-alert status="info">Docs coming soon</sonic-alert>
+
+Permet de mapper un nom de propriété de donnée source vers une propriété du subscriber à la volée
+
+## BindPublisher
+
+<sonic-alert status="info">Docs coming soon</sonic-alert>
+
+On peut utiliser cette fonction pour lier un publisher spécifique au composant si besoin.
+
+## instanceCounter
+
+<sonic-alert status="info">Docs coming soon</sonic-alert>
+
+## Publisher
+
+<sonic-alert status="info">Docs coming soon</sonic-alert>
+
+## Args
+
+<sonic-alert status="info">Docs coming soon</sonic-alert>
+ 
+## NoShadowDom
+
+Par défaut on crée un shadow dom mais on peut demander à ne pas en avoir via cette propriété et un attribut associé.  
+Cela se fait à l'initialisation uniquement et n'est pas modifiable lors de la vie du composant.
+
+
+## Other attributes gathered from subscriber.stories.ts
+
+styles ??  
+title ??  
+_props ??  
+onAssign ??  
+defferedDebug ??

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

@@ -0,0 +1,35 @@
+# Value
+
+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-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>
+  </template>
+</sonic-code>
+* Then you can see live value of the preference using this code :
+<sonic-code>
+  <template>
+  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>
+

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

@@ -0,0 +1,177 @@
+# Alert
+
+Inline message in the page: title (`label`), body (`text` or default slot), icon from `status`. For HTML or actions, use the slot instead of `label` / `text` (plain text only).
+
+Use **`status`**: `default`, `info`, `success`, `warning`, `error`.
+
+<sonic-code>
+  <template>
+    <sonic-alert status="error" label="Email error" text="This address is already in use" background></sonic-alert>
+  </template>
+</sonic-code>
+
+## Status
+
+Color and icon follow `status`. With no `status`, behavior is `default`.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-alert label="Default">This address is already in use.</sonic-alert>
+      <sonic-alert status="success" label="Success">This address is already in use.</sonic-alert>
+      <sonic-alert status="error" label="Error">This address is already in use.</sonic-alert>
+      <sonic-alert status="warning" label="Warning">This address is already in use.</sonic-alert>
+      <sonic-alert status="info" label="Info">This address is already in use.</sonic-alert>
+    </div>
+  </template>
+</sonic-code>
+
+## Accessibility (`announce`)
+
+By default, an alert already in the DOM is **not** announced (no `role` / `aria-live`). Set **`announce`** when the message appears **after** user action (API response, validation, etc.): screen readers get `role="alert"` for `error`, otherwise `role="status"` and `aria-live="polite"`.
+
+`sonic-alert-messages` sets `announce` on every rendered alert.
+
+<sonic-code>
+  <template>
+    <sonic-alert announce status="success" label="Saved" text="Your changes were saved."></sonic-alert>
+  </template>
+</sonic-code>
+
+## Content and icon
+
+`label` and `text` accept plain text only. The default slot is rendered after `text`. Use the **`icon`** slot to replace the default `sonic-icon`. **`noIcon`** hides the icon.
+
+<sonic-code>
+  <template>
+    <sonic-alert status="info" noIcon label="No icon" text="Informational message."></sonic-alert>
+  </template>
+</sonic-code>
+
+## Custom icon slot
+
+Project any markup into **`slot="icon"`** (emoji, image, custom component). Keep it decorative with `aria-hidden="true"` when the message text already conveys meaning.
+
+<sonic-code>
+  <template>
+    <sonic-alert status="success" label="Achievement unlocked" background>
+      <span slot="icon" aria-hidden="true" class="text-lg leading-none">🎉</span>
+      You unlocked a new badge.
+    </sonic-alert>
+  </template>
+</sonic-code>
+
+## Sizes
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-alert status="error" label="Email error" size="2xs">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="xs">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="sm">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="lg">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="xl">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+      <sonic-alert status="error" label="Email error" size="2xl">
+        This address is already in use. Lorem ipsum dolor sit amet.
+      </sonic-alert>
+    </div>
+  </template>
+</sonic-code>
+
+## Alert with link
+
+Rich content in the slot (buttons, links).
+
+<sonic-code>
+  <template>
+    <sonic-alert status="info" label="New messages !">
+      You have 2 unread messages<br />
+      <div class="flex gap-2 mt-1">
+        <sonic-button variant="outline" type="info" size="xs">See messages</sonic-button>
+        <sonic-button variant="ghost" type="info" size="xs">Dismiss</sonic-button>
+      </div>
+    </sonic-alert>
+  </template>
+</sonic-code>
+
+## Background
+
+Tinted background from the `status` color (`color-mix` on `currentColor`).
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4">
+      <sonic-alert background label="Lorem ipsum dolor">This address is already in use.</sonic-alert>
+      <sonic-alert status="success" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+      <sonic-alert status="error" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+      <sonic-alert status="warning" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+      <sonic-alert status="info" background label="Lorem ipsum dolor">
+        This address is already in use.
+      </sonic-alert>
+    </div>
+  </template>
+</sonic-code>
+
+## Dismissible
+
+`dismissible` removes the alert from the DOM when the close control is clicked (i18n aria label). **`dismissible`** and **`background`** are independent: without `background`, close sits at the end of the row; with `background`, top-right.
+
+<sonic-code>
+  <template>
+    <sonic-alert status="info" class="mb-3" dismissible label="This address is already in use.">
+    </sonic-alert>
+    <sonic-alert class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="success" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="error" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="warning" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+    <sonic-alert status="info" class="mb-3" dismissible background label="Lorem ipsum dolor">
+      This address is already in use.
+    </sonic-alert>
+  </template>
+</sonic-code>
+
+## Dismiss forever
+
+With **`dismissForever`**, dismissal is stored in `localStorage` (key `sonic-alert-dismissed`). A stable **`id`** on the element is **required**; without `id`, a warning is logged and nothing is persisted.
+
+<sonic-code>
+  <template>
+    <sonic-alert
+      class="mb-3"
+      dismissible
+      background
+      dismissForever
+      label="Lorem ipsum dolor"
+      id="addressUniqueId"
+    >
+      This address is already in use.
+    </sonic-alert>
+  </template>
+</sonic-code>