@supersoniks/concorde 5.1.1 → 5.1.3

package/src/core/components/functional/states/states.demo.ts

@@ -14,43 +14,42 @@ export class SonicStatesDemo extends LitElement {
 
   constructor() {
     super();
-    // Initialisation du dataProvider
     dp<StatesDemoProvider>("states-demo-provider").set({});
   }
 
   @state()
   private states = {
-    pending: () => html`
+    boarding: () => html`
       <div class="p-4 border border-gray-200 rounded-md">
-        <h1 class="text-xl font-medium mb-2">En attente</h1>
-        <p class="text-gray-600">Veuillez patienter...</p>
+        <h1 class="text-xl font-medium mb-2">Boarding</h1>
+        <p class="text-gray-600">Please proceed to gate B12.</p>
       </div>
     `,
 
-    "user/:id/:status": ({
-      id,
+    "flights/:code/:status": ({
+      code,
       status,
     }: {
-      id: string;
+      code: string;
       status: string;
     }) => html`
       <div class="p-4 border border-gray-200 rounded-md">
-        <h1 class="text-xl font-medium mb-2">Utilisateur ${id}</h1>
-        <p class="text-gray-600">Statut: ${status}</p>
+        <h1 class="text-xl font-medium mb-2">Flight ${code}</h1>
+        <p class="text-gray-600">Status: ${status}</p>
       </div>
     `,
 
-    "error_(\\d+)": ([code]: [string]) => html`
+    "delayed_(\\d+)": ([minutes]: [string]) => html`
       <div class="p-4 border border-red-200 bg-red-50 rounded-md">
-        <h1 class="text-xl font-medium text-red-800 mb-2">Erreur ${code}</h1>
-        <p class="text-red-600">Une erreur s'est produite</p>
+        <h1 class="text-xl font-medium text-red-800 mb-2">Delayed</h1>
+        <p class="text-red-600">New departure in ${minutes} minutes</p>
       </div>
     `,
 
     fallback: () => html`
       <div class="p-4 border border-gray-200 rounded-md">
-        <h1 class="text-xl font-medium mb-2">État Inconnu</h1>
-        <p class="text-gray-600">L'état demandé n'existe pas</p>
+        <h1 class="text-xl font-medium mb-2">Unknown status</h1>
+        <p class="text-gray-600">No state matches this value</p>
       </div>
     `,
   };
@@ -58,20 +57,20 @@ export class SonicStatesDemo extends LitElement {
   render() {
     return html`
       <div class="p-4">
-        <h2 class="text-2xl font-medium mb-6">Démo des états</h2>
+        <h2 class="text-2xl font-medium mb-6">States demo</h2>
 
         <div class="flex gap-4 mb-6" formDataProvider="states-demo-provider">
-          <sonic-button radio name="status" checked value="pending">
-            En attente
+          <sonic-button radio name="status" checked value="boarding">
+            Boarding
           </sonic-button>
-          <sonic-button radio name="status" value="user/123/active">
-            Utilisateur Actif
+          <sonic-button radio name="status" value="flights/CN001/landed">
+            CN 001 landed
           </sonic-button>
-          <sonic-button radio name="status" value="error_404">
-            Erreur 404
+          <sonic-button radio name="status" value="delayed_45">
+            Delayed 45 min
           </sonic-button>
           <sonic-button radio name="status" value="invalid">
-            État Invalide
+            Unknown
           </sonic-button>
         </div>
 

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

@@ -1,87 +1,112 @@
 # 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-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-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 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>
-    <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 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>
   </template>
 </sonic-code>
 
-## Regexp
+Templates without `data-value` are ignored, and nothing renders when no template matches.
 
-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>"
+## 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.
 
 <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>
+    <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>
         </template>
       </sonic-states>
     </div>
   </template>
 </sonic-code>
 
-## Url-pattern
+With [url-pattern](https://www.npmjs.com/package/url-pattern) syntax, name the segments instead: `data-value="flight/:code"` and `dataProviderExpression="flights?q=:code"`.
 
-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>"
+## 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.
 
 <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 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>
+    <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>
+</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 |

package/src/core/components/functional/states/states.ts

@@ -126,7 +126,7 @@ export class SonicStates extends Subscriber(TemplatesContainer(LitElement)) {
     let state = this.state;
     if (
       (!Array.isArray(state) && Objects.isObject(state)) ||
-      state === undefined
+      state == null
     ) {
       state = "";
     }

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

@@ -1,114 +1,106 @@
 # 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"`).
+**`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`.
 
-## Overview
+## Basic example
 
-**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`.
+`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.
 
 <docs-lit-demo for="docs-submit-demo"></docs-lit-demo>
 
-## Native HTML form
-
-With **`native`**, Concorde does **not** call `fetch`. After form validation it:
+## Result key
 
-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).
+When the API wraps its payload (`{ data: { id, token } }`), set `submitResultKey` to a dot path so `submitResultDataProvider` receives only that part.
 
-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
+<docs-lit-demo for="docs-submit-result-key-demo"></docs-lit-demo>
 
-Sends fields as **`multipart/form-data`** instead of `application/json` (response is still parsed as JSON).
+## Reset after submit
 
-<docs-lit-demo for="docs-submit-formdata-demo"></docs-lit-demo>
+`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`.
 
-## submit-result-key
+<docs-lit-demo for="docs-submit-clear-demo"></docs-lit-demo>
 
-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.
+## Submit event
 
-<docs-lit-demo for="docs-submit-result-key-demo"></docs-lit-demo>
+After each request, `sonic-submit` dispatches a bubbling `submit` event whose `detail` is the result, the same value written to `submitResultDataProvider`.
 
-Mock endpoint: `POST /docs-mock-api/api/register/nested`.
+<docs-lit-demo for="docs-submit-event-demo"></docs-lit-demo>
 
-## clearedDataOnSuccess
+## Endpoint override
 
-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.
+`endPoint` on `sonic-submit` replaces the ancestor `dataProvider` as the request path, for this element only.
 
-<docs-lit-demo for="docs-submit-clear-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-endpoint-demo"></docs-lit-demo>
 
-## Custom `submit` event
+## HTTP method
 
-Listen for the bubbling **`submit`** event; **`event.detail`** is the same result written to **submitResultDataProvider** (if configured).
+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.
 
-<docs-lit-demo for="docs-submit-event-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-get-demo"></docs-lit-demo>
 
-## endPoint vs dataProvider
+## Multipart body
 
-Ancestor **`dataProvider`** is the default path; **`endPoint`** on **sonic-submit** overrides it for that button only.
+`sendAsFormData` sends the fields as `multipart/form-data` instead of JSON. The response is still parsed as JSON.
 
-<docs-lit-demo for="docs-submit-endpoint-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-formdata-demo"></docs-lit-demo>
 
-## method="get"
+## Native form
 
-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.
+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.
 
-<docs-lit-demo for="docs-submit-get-demo"></docs-lit-demo>
+<docs-lit-demo for="docs-submit-native-demo"></docs-lit-demo>
 
-## dot notation (formDataProvider shape)
+## Nested fields
 
-You can use dot notation in **`name`** on form controls; the publisher stores nested objects:
+A dot in a field `name` stores a nested object in the form publisher, and the body is sent with the same shape.
 
 <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>
+    <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>
       </div>
     </sonic-scope>
   </template>
 </sonic-code>
 
-Stored shape:
-
 <sonic-code language="typescript">
   <template>
-  {
-    email: { value: "eve.holt@reqres.in" },
-    details: { password: { value: "pistol" } }
-  }
+{ passenger: { name: "Ada Lindqvist", seat: "2A" } }
   </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.
+## 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 |

package/src/core/components/functional/translation/translation.md

@@ -0,0 +1,38 @@
+# Translation
+
+**`sonic-t`** renders a translated label in plain HTML. It is the markup counterpart of the [t()](/docs/directives/t) directive and shares its endpoint, batching and cache.
+
+## Basic example
+
+Set `serviceURL` and `wordingProvider` on an ancestor, then give each `sonic-t` a `key`. Labels requested together are fetched in one call.
+
+<sonic-code>
+  <template>
+    <div serviceURL="/docs-mock-api" wordingProvider="wording/labels?lang=fr">
+      <p><sonic-t key="flight.boarding"></sonic-t></p>
+    </div>
+  </template>
+</sonic-code>
+
+## HTML labels
+
+The label is escaped by default. Add `unsafeHTML` for labels that contain trusted markup.
+
+<sonic-code>
+  <template>
+    <div serviceURL="/docs-mock-api" wordingProvider="wording/labels?lang=fr">
+      <p><sonic-t key="flight.gate" unsafeHTML></sonic-t></p>
+    </div>
+  </template>
+</sonic-code>
+
+Endpoint format, reloading on `<html lang>` change and `wordingVersionProvider` are described on the [t()](/docs/directives/t) page.
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `key` | string | Label key. Renders nothing while empty |
+| `unsafeHTML` | boolean | Renders the label as HTML instead of text |
+
+No slots.

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

@@ -1,35 +1,47 @@
 # Value
 
-Simply shows a value from a data provider.
-You can target sub data value using dot syntax.
-The value reacts to changes.
+**`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.
 
-* 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 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>
+    <p>Cabin: <sonic-value dataProvider="value-checkin" key="cabin"></sonic-value></p>
   </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
+
+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.
+
 <sonic-code>
   <template>
-  <sonic-value dataProvider="value-example-2" key="my.complex.0.data"></sonic-value> 
+    <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>
   </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 |