@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

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

@@ -1,290 +1,150 @@
 # Date
 
-## No attribute
+**`sonic-date`** formats a date or a date range with `Intl.DateTimeFormat`. Pass a Unix timestamp in seconds (`date`) or a parsable string (`date_string`), add `end_date` for a range, and tune each part (`weekday` · `month` · `hour` …) with attributes. With no date and no `now`, it renders nothing.
 
-**Nothing** is displayed.
+## Basic example
 
-<sonic-code>
-  <template>
-    <sonic-date></sonic-date>
-  </template>
-</sonic-code>
-
-## Now
-
-Displays the **current date**.
+`date` is in **seconds**, not milliseconds. `date_string` accepts anything `new Date()` parses: prefer ISO 8601 with an explicit offset. `now` shows the current date.
 
 <sonic-code>
   <template>
-    <sonic-date now></sonic-date>
-  </template>
-</sonic-code>
-
-
-## Date  
-
-Displays a date from a **timestamp**.
-
-<sonic-code>
-  <template>
-    <sonic-date date= "1640265629"></sonic-date>
-  </template>
-</sonic-code>
-
-## Date_string  
-
-Displays a date from a **string**.
-
-<sonic-code>
-  <template>
-    <sonic-date date_string="July 20, 69 20:17:40 GMT+00:00"></sonic-date>
-  </template>
-</sonic-code>
-
-## Start_date / end_date  
-
-Displays a period of time **from start_date to end_date**.  
-When by itself **start_date** will act as **date**  
-if a **start_date is not specified** it will be set by the **current date**.  
-if the **end_date is anterior** to start date date it will be **used as the start_date**. 
-
-<sonic-code>
-  <template>
-    <!-- from start_date to end_date -->
-    <sonic-date start_date="1640265629" end_date= "1640365629"></sonic-date>
-    <br>
-    <!-- start_date is not specified -->
-    <sonic-date end_date= "2640365629"></sonic-date>
-    <br>
-    <!-- end_date is anterior -->
-    <sonic-date end_date= "640365629"></sonic-date>
-  </template>
-</sonic-code>
-
-
-## Start_date_string / end_date_string
-
-<sonic-code>
-  <template>
-    <!-- from start_date to end_date -->
-    <sonic-date date_string="July 20, 90 20:17:40 GMT+00:00" end_date_string= "June 20, 94 20:17:40 GMT+00:00"></sonic-date>
-    <br>
-    <!-- start_date is not specified -->
-    <sonic-date end_date_string= "May 20, 34 20:17:40 GMT+00:00"></sonic-date>
-    <br>
-    <!-- end_date is anterior -->
-    <sonic-date end_date_string= "April 20, 06 20:17:40 GMT+00:00"></sonic-date>
-  </template>
-</sonic-code>
-
-## Wording_billet_periode_validite
-
-<sonic-code>
-  <template>
-    <sonic-date wording_billet_periode_validite= "À partir du %s jusqu'au %s" start_date="1640265629" end_date= "1640365629"></sonic-date>
+    <div class="grid gap-2">
+      <div>Departure: <sonic-date date="1781514000" language="en"></sonic-date></div>
+      <div>Arrival: <sonic-date date_string="2026-06-15T12:45:00Z" language="en"></sonic-date></div>
+      <div>Now: <sonic-date now language="en"></sonic-date></div>
+    </div>
   </template>
 </sonic-code>
 
+## Date range
 
-## Weekday
-
-<sonic-code>
-  <template>
-    <b>narrow : </b>
-    <sonic-date weekday="narrow" now></sonic-date>
-    <br>
-    <b>short (default) : </b>
-    <sonic-date weekday="short" now></sonic-date>
-    <br>
-    <b>long : </b>
-    <sonic-date weekday="long" now></sonic-date>
-    <br>
-    <b>hidden : </b>
-    <sonic-date weekday="hidden" now></sonic-date>
-  </template>
-</sonic-code>
+Set `start_date` and `end_date` (or their `_string` variants). On two different days, only the dates are shown, with the "from … to …" wording. On the same day, the hours are kept. `hide_hours` drops them anyway.
 
-## Day
+Without a start, the range starts now. If the end is before the start, the two are swapped.
 
 <sonic-code>
   <template>
-    <b>numeric : </b>
-    <sonic-date day="numeric" date_string="July 01, 69"></sonic-date>
-    <br>
-    <b>2-digit (default) : </b>
-    <sonic-date day="2-digit" date_string="July 01, 69"></sonic-date>
+    <div class="grid gap-2">
+      <sonic-date start_date_string="2026-06-15T09:00:00Z" end_date_string="2026-06-22T18:00:00Z" language="en" wording_billet_periode_validite="From %s to %s"></sonic-date>
+      <sonic-date start_date_string="2026-06-15T09:00:00Z" end_date_string="2026-06-15T12:45:00Z" language="en"></sonic-date>
+      <sonic-date start_date_string="2026-06-15T09:00:00Z" end_date_string="2026-06-15T12:45:00Z" language="en" hide_hours></sonic-date>
+    </div>
   </template>
 </sonic-code>
 
-## Month
+## Range wording
 
-<sonic-code>
-  <template>
-    <b>numeric : </b>
-    <sonic-date month="numeric" now></sonic-date>
-    <br>
-    <b>2-digit : </b>
-    <sonic-date month="2-digit" now></sonic-date>
-    <br>
-    <b>narrow : </b>
-    <sonic-date month="narrow" now></sonic-date>
-    <br>
-    <b>short (default) : </b>
-    <sonic-date month="short" now></sonic-date>
-    <br>
-    <b>long : </b>
-    <sonic-date month="long" now></sonic-date>
-  </template>
-</sonic-code>
-
-## Year
+`wording_billet_periode_validite` holds the range wording, with one `%s` per date. It defaults to the French `Du %s au %s`, whatever the language: **set it for every non-French page**.
 
 <sonic-code>
   <template>
-    <b>numeric (default) : </b>
-    <sonic-date year="numeric" now></sonic-date>
-    <br>
-    <b>2-digit : </b>
-    <sonic-date year="2-digit" now></sonic-date>
+    <sonic-date start_date_string="2026-06-15" end_date_string="2026-06-22" language="en" wording_billet_periode_validite="Valid from %s until %s"></sonic-date>
   </template>
 </sonic-code>
 
-## Hour
-
-<sonic-code>
-  <template>
-    <b>numeric : </b>
-    <sonic-date hour="numeric" date_string= "June 20, 04 02:06:02 GMT+00:00"></sonic-date>
-    <br>
-    <b>2-digit (default) : </b>
-    <sonic-date hour="2-digit" date_string= "June 20, 04 02:06:02 GMT+00:00"></sonic-date>
-    <br>
-    <b>hidden : </b>
-    <sonic-date hour="hidden" date_string= "June 20, 04 02:06:02 GMT+00:00"></sonic-date>
-  </template>
-</sonic-code>
+## Format options
 
-## Minute
+Defaults: `weekday="short"` · `day="2-digit"` · `month="short"` · `year="numeric"` · `hour="2-digit"` · `minute="2-digit"`, 24-hour clock, no era. `hidden` removes a part.
 
 <sonic-code>
   <template>
-    <b>numeric : </b>
-    <sonic-date minute="numeric" date_string= "June 20, 04 02:06:02 GMT+00:00"></sonic-date>
-    <br>
-    <b>2-digit (default) : </b>
-    <sonic-date minute="2-digit" date_string= "June 20, 04 02:06:02 GMT+00:00"></sonic-date>
-    <br>
-    <b>hidden : </b>
-    <sonic-date minute="hidden" date_string= "June 20, 04 02:06:02 GMT+00:00"></sonic-date>
+    <div class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 text-sm">
+      <code>default</code><sonic-date date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>weekday="long"</code><sonic-date weekday="long" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>weekday="narrow"</code><sonic-date weekday="narrow" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>weekday="hidden"</code><sonic-date weekday="hidden" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>day="numeric"</code><sonic-date day="numeric" date_string="2026-06-05T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>month="long"</code><sonic-date month="long" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>month="narrow"</code><sonic-date month="narrow" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>month="numeric"</code><sonic-date month="numeric" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>month="2-digit"</code><sonic-date month="2-digit" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>year="2-digit"</code><sonic-date year="2-digit" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>hour="numeric"</code><sonic-date hour="numeric" date_string="2026-06-15T07:05:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>hour12</code><sonic-date hour12 date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>hour="hidden" minute="hidden"</code><sonic-date hour="hidden" minute="hidden" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+      <code>era="short"</code><sonic-date era="short" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
+    </div>
   </template>
 </sonic-code>
 
-## Language  
+## Language
 
-<sonic-button href="https://www.w3schools.com/tags/ref_language_codes.asp" target="_blank" type="info" size="sm">ISO 639-1 Language Codes</sonic-button>
+With no `language`, the component follows `<html lang>` and updates when it changes. Pass a BCP 47 tag to force one.
 
 <sonic-code>
   <template>
-    <b>fr : </b>
-    <sonic-date language="fr" now></sonic-date>
-    <br>
-    <b>en : </b>
-    <sonic-date language="en" now></sonic-date>
-    <br>
-    <b>zh : </b>
-    <sonic-date language="zh" now></sonic-date>
-    <br>
-    <b>ja : </b>
-    <sonic-date language="ja" now></sonic-date>
+    <div class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 text-sm">
+      <code>en</code><sonic-date language="en" date_string="2026-06-15T09:00:00Z"></sonic-date>
+      <code>fr</code><sonic-date language="fr" date_string="2026-06-15T09:00:00Z"></sonic-date>
+      <code>ja</code><sonic-date language="ja" date_string="2026-06-15T09:00:00Z"></sonic-date>
+    </div>
   </template>
 </sonic-code>
 
-## Time_zone
-
-For the list of supported timeZones, run <b class="text-info">Intl.supportedValuesOf('timeZone')</b> in the console
-
-<sonic-code>
-  <template>
-    <b>Europe/London : </b>
-    <sonic-date time_zone="Europe/London" now></sonic-date>
-    <br>
-    <b>Europe/Paris : </b>
-    <sonic-date time_zone="Europe/Paris" now></sonic-date>
-    <br>
-    <b>America/Tijuana : </b>
-    <sonic-date time_zone="America/Tijuana" now></sonic-date>
-  </template>
-</sonic-code>
+## Time zone
 
-## Era  
+With no `time_zone`, dates use the browser time zone. Pass an IANA name (`Intl.supportedValuesOf("timeZone")` lists them) to show local airport time.
 
 <sonic-code>
   <template>
-    <b>narrow : </b>
-    <sonic-date era="narrow" now></sonic-date>
-    <br>
-    <b>short : </b>
-    <sonic-date era="short" now></sonic-date>
-    <br>
-    <b>long : </b>
-    <sonic-date era="long" now></sonic-date>
+    <div class="grid gap-2">
+      <div>CN 001 departs CDG at <sonic-date date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" weekday="hidden" language="en"></sonic-date> (Paris)</div>
+      <div>and lands at JFK at <sonic-date date_string="2026-06-15T12:45:00Z" time_zone="America/New_York" weekday="hidden" language="en"></sonic-date> (New York)</div>
+    </div>
   </template>
 </sonic-code>
 
-## .renderIf  
-
-<sonic-alert status="error" background>Deprecated</sonic-alert>
-
-<sonic-code>
-  <template>
-    <b>True statement : </b>
-    <sonic-date data-bind ::render-if="|10>2" now></sonic-date>
-    <br>
-    <b>False statement : </b>
-    <sonic-date data-bind ::render-if="|10<2" now></sonic-date>
-  </template>
-</sonic-code>
+## Custom parts
 
-## DesignMode  
+A child `<template data-value="<part>">` wraps a part in your own markup: `weekday` · `day` · `month` · `year` · `hour` · `minute` · `literal`, plus `from` and `to` in ranges. An empty element receives the part value; a non-empty one replaces it. `designMode` drops the leading "from" word and the commas, for stacked layouts. Add `noShadowDom` so page styles reach the parts.
 
 <sonic-code>
   <template>
-    <div class="relative max-w-lg rounded-lg overflow-hidden">
-      <div class="absolute top-0 h-1/2 w-full bg-gradient-to-b from-[rgba(0,0,10,.2)] z-10 "></div>
+    <div class="relative max-w-sm rounded-lg overflow-hidden">
       <sonic-date
         designMode
         noShadowDom
-        start_date= "1640265629"
-        end_date= "1640365629"
-        language= "fr"
-        wording_billet_periode_validite= "Du %s au %s"
-        year= "numeric"
-        month= "short"
-        weekday= "short"
-        hour= "2-digit"
-        minute= "2-digit"
-        class="py-4 drop-shadow-lg text-contrast-content p-4 inline-block text-center absolute left-0 z-20 text-sm"
+        start_date_string="2026-06-15"
+        end_date_string="2026-06-22"
+        language="en"
+        wording_billet_periode_validite="From %s to %s"
+        class="absolute top-0 left-0 z-10 p-4 text-center text-sm text-white drop-shadow-lg"
       >
-        <template data-value="weekday">
-          <span class="hidden"></span>
-        </template>
-        <template data-value="day">
-          <span class="text-4xl block uppercase leading-none font-bold"></span>
-        </template>
-        <template data-value="month">
-          <span class="text-xl block uppercase leading-tight font-bold"></span>
-        </template>
-        <template data-value="year">
-          <span class="text-lg  mb-1 font-bold  block uppercase leading-tight "></span>
-        </template>
-        <template data-value="to">
-          <span class="font-medium block my-1 text-3xl leading-none">↓</span>
-        </template>
+        <template data-value="weekday"><span class="hidden"></span></template>
+        <template data-value="day"><span class="block text-4xl font-bold leading-none"></span></template>
+        <template data-value="month"><span class="block text-xl font-bold uppercase leading-tight"></span></template>
+        <template data-value="year"><span class="block text-lg font-bold leading-tight"></span></template>
+        <template data-value="to"><span class="block my-1 text-3xl leading-none">↓</span></template>
       </sonic-date>
-      <sonic-image 
-      ratio="1/1" src="https://picsum.photos/id/237/700/700">
-      </sonic-image>
+      <sonic-image src="/img/concorde/plane_03.jpg" alt="Concorde specifications board" ratio="1/1" cover></sonic-image>
     </div>
   </template>
 </sonic-code>
 
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `date` | number | Unix timestamp in seconds |
+| `date_string` | string | Date parsed with `new Date()`. Overrides `date` |
+| `start_date` / `start_date_string` | number / string | Range start. Overrides `date` |
+| `end_date` / `end_date_string` | number / string | Range end. Swapped with the start when earlier |
+| `now` | boolean | Uses the current date when no start is set |
+| `hide_hours` | boolean | Hides hours and minutes in a same-day range |
+| `weekday` | `narrow` · `short` · `long` · `hidden` (default `short`) | Weekday format |
+| `day` | `numeric` · `2-digit` (default `2-digit`) | Day format |
+| `month` | `numeric` · `2-digit` · `narrow` · `short` · `long` (default `short`) | Month format |
+| `year` | `numeric` · `2-digit` (default `numeric`) | Year format |
+| `hour` | `numeric` · `2-digit` · `hidden` (default `2-digit`) | Hour format |
+| `minute` | `numeric` · `2-digit` · `hidden` (default `2-digit`) | Minute format |
+| `hour12` | boolean | 12-hour clock. Default is 24-hour |
+| `era` | `narrow` · `short` · `long` | Shows the era. Hidden by default |
+| `language` | BCP 47 tag | Locale. Defaults to `<html lang>` |
+| `time_zone` | IANA name | Time zone. Defaults to the browser one |
+| `wording_billet_periode_validite` | string with two `%s` (default `Du %s au %s`) | Wording of a multi-day range |
+| `designMode` | boolean | Removes the "from" word and commas |
+| `noShadowDom` | boolean | Renders in light DOM so page styles apply to the parts |
+| `templates` | `HTMLTemplateElement[]` (property) | Part templates, instead of child `<template>` elements |
+| `renderIf` | boolean | Deprecated: wrap the date in [sonic-if](/core/components/functional/if) instead |
+
+No slots. Child `<template data-value>` elements customise the parts.

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

@@ -2,6 +2,7 @@ import { html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { Endpoint } from "@supersoniks/concorde/utils";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+import type { Frozen } from "@supersoniks/concorde/utils/deepReadonly";
 import {
   get,
   publish,
@@ -19,6 +20,7 @@ const endpoint = new Endpoint<City[], { limit: number }>(
 /** Même path que l’endpoint ; type = charge utile `@get` pour `@publish`. */
 const dpKey = new DataProviderKey<ApiResult<City[]>>(endpoint.path);
 
+
 const tagName = "sonic-example"; // For Astro.build
 @customElement(tagName)
 export class SonicComponent extends LitElement {
@@ -31,7 +33,7 @@ export class SonicComponent extends LitElement {
 
   @state()
   @subscribe(dpKey.result)
-  geoCommunesResult?: City[];
+  geoCommunesResult?: Frozen<City[]>;
 
   render() {
     return html` <span part="api-get-demo">

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

@@ -1,125 +1,108 @@
 # Fetch
 
-> **New apps:** prefer [@get](#docs/_decorators/get.md/get) for a typed GET on a component, or [List](#core/components/functional/list/list.md/list) / [Queue](#core/components/functional/queue/queue.md/queue) with `fetch` for collections. Use [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) (`serviceURL="/docs-mock-api"`) to try examples offline.
-
-The **sonic-fetch** component requests and stores API data. It extends the Fetcher and [Subscriber](#docs/_core-concept/subscriber.md/subscriber) mixins.
-
-
-
-
-
-## Basic usage
-In order to work properly the <b>sonic-fetch</b> component needs at least the following attributes.  
-- **serviceURL** : A base service url. This attribute can be inherited from an ancestor.
-  *ex : /docs-mock-api*
-- **endPoint** : the specific location where requests for information are sent (see the api docs).  
-  *ex : api/users | api/users?page=2 | api/users/2*
-- **dataProvider *(Required)*** : An ID that is used as a reference to the object storing the data returned by the API.
-This attribute can be inherited from an ancestor.
+**`sonic-fetch`** sends a GET request to `serviceURL` + `endPoint` and publishes the response under `dataProvider`, so its children and any subscriber of that provider can render it. In a Lit component, prefer the [@get](/docs/decorators/get) decorator; for collections, use [List](/core/components/functional/list) or [Queue](/core/components/functional/queue).
 
+## Basic example
 
+`dataProvider` is required; `serviceURL` and `dataProvider` can be set on an ancestor. Children are hidden while the request is pending. With no `serviceURL`, requests go to the page origin.
 
 <sonic-code>
   <template>
-<sonic-fetch serviceURL="/docs-mock-api" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
-<sonic-button dataProvider="myDataObj" debug>Hover to see the data</sonic-button>
+    <sonic-fetch serviceURL="/docs-mock-api" endPoint="flights?direction=departures" dataProvider="docsFetchNextDeparture" key="flights.0">
+      <p data-bind ::inner-html="Next departure: <b>$code</b> to $city, gate $gate"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## DataProvider as an endPoint
-If no **endPoint** is specified it will be filled by the **dataProvider ID** instead  
+## Data provider as endpoint
+
+With no `endPoint`, the `dataProvider` value is used as the endpoint.
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="api/users?page=2" ></sonic-fetch>
-    <sonic-button dataProvider="api/users?page=2" debug>Hover to see the data</sonic-button>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=arrivals" key="flights.0">
+      <p data-bind ::inner-html="Next arrival: <b>$code</b> from $city at $time"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## HeadersDataProvider
-
-<sonic-alert status="error" background>Deprecated</sonic-alert>
-
 ## Key
-When the **key** attribute is present, only a sub-part of the data received is injected into the **dataProvider**.
-We can use the dot syntax to target what we want to keep.
 
-For example if the data is `{my:{data:{a:1,b:2}}}` and the key is `key="my.data"`, the data available in the **dataProvider** will be `{a:1 , b:2}`
+`key` keeps only part of the response, using a dot path: with `{ "flights": [ … ] }` and `key="flights.1"`, the provider holds the second flight. Add `preserveOtherKeys` to merge the target into the parent object instead of dropping its siblings. With no `key`, the whole response is published.
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="api/users/2" ></sonic-fetch>
-    <sonic-button dataProvider="api/users/2" debug>dataProvider object</sonic-button>
-    <!-- Get the user ID -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="id" endPoint="api/users/2" key="data.id"></sonic-fetch>
-    <sonic-button dataProvider="id" debug>data.id</sonic-button>
-    <!-- Get the user First name -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="first_name" endPoint="api/users/2" key="data.first_name"></sonic-fetch>
-    <sonic-button dataProvider="first_name" debug>data.first_name</sonic-button>
-    <!-- Get the user Last name -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="last_name" endPoint="api/users/2" key="data.last_name"></sonic-fetch>
-    <sonic-button dataProvider="last_name" debug>data.last_name</sonic-button>
-    <!-- Get the user email -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="email" endPoint="api/users/2" key="data.email"></sonic-fetch>
-    <sonic-button dataProvider="email" debug>data.email</sonic-button>
+    <sonic-fetch serviceURL="/docs-mock-api" endPoint="flights?direction=departures" dataProvider="docsFetchKey" key="flights.1">
+      <p data-bind ::inner-html="$code to $city ($airport), status $status"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## Text mode
+## Loader and skeleton
 
-if the mime type of the content returned by the service begins with **text/**, then the dataProvider has a key named "text" which contains the text returned by the service.
+With no `loader`, nothing is shown during the request. Set `loader` (`fixed` overlay) or `loader="inline"` to show a [Loader](/core/components/ui/loader), or add a `<template skeleton>` child rendered in place of the content while loading.
 
 <sonic-code>
   <template>
-    <sonic-fetch endPoint="README.md" dataProvider="fetchText"></sonic-fetch>
-    <sonic-button dataProvider="fetchText" debug>Hover to see the data</sonic-button>
+    <sonic-fetch loader="inline" serviceURL="/docs-mock-api" endPoint="flights?direction=arrivals" dataProvider="docsFetchLoader" key="flights.2">
+      <template skeleton>
+        <p class="text-neutral-400">Loading arrivals…</p>
+      </template>
+      <p data-bind ::inner-html="<b>$code</b> from $city: $status"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## NoLoader
+## Text responses
 
-The noLoader attribute disables display of the default loader
+When the response type starts with `text/`, the provider holds `{ text: "…" }`.
 
 <sonic-code>
   <template>
-    <sonic-fetch noLoader serviceURL="/docs-mock-api" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
-    <sonic-button dataProvider="myDataObj" debug>Basic fetch with noLoader attribute</sonic-button>
+    <sonic-fetch endPoint="robots.txt" dataProvider="docsFetchText">
+      <pre class="max-h-40 overflow-auto text-xs" data-bind ::inner-html="$text"></pre>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
+## Reloading
 
+`endPoint` is reactive: changing it fetches again. Call `invalidate()` on the publisher to reload the same endpoint, or set `refetchEveryMs` to poll. A request that fails with no data shows an error toast.
 
+<sonic-code language="typescript">
+  <template>
+import { PublisherManager } from "@supersoniks/concorde/utils";
 
-<!--
- ## Summary
- Extends mixins : Fetcher, [Subscriber](#core/components/functional/subscriber/subscriber.md/subscriber)
- 
- ### Configuration via les attributs
-
-| nom          | sur quelle balise | Description | Exemple de valeur | défaut / requis |
-|-----|-----|---|---|---|
-| serviceURL   |Fetcher ou un de ses parents | URL de base des services. | http://la-billetterie.net/api/v2 | domain du site |
-| endpoint   |Fetcher | point d'accès d'un service | user/2 | valeur de l'attribut dataProvider |
-| dataProvider  |Fetcher ou un de ses parents | Identifiant d'un publisher qui stock les données, voir [subscriber](#core/components/functional/subscriber/subscriber.md/subscriber). | billetterie/user/2 | *REQUIS* |
-| headersDataProvider  |Fetcher ou un de ses parents | Identifiant d'un publisher qui stock les données destinées à être envoyées en entêtes de la requetes | MyCoockieHEaders | null |
-| key  |Fetcher  | extrait une sous propriété de la donnée chargée avant de l'assignée à son publisher | ma.data | null |
-
- *Si la données est `{ma:{data:{a:1,b:2}}}` et `key="ma.data"`, la données disponible dans le composant sera `{a:1, b:2}`*
- 
- ### Intégration auto de basic auth (pour tester une api qui nécessite une authentification) 
-
- Fetch utilise le service pour générer le token et l'ajoute au header de l'appel qui récupère les données.
-
-| nom           | sur quelle balise | Description | Exemple de valeur | défaut / requis |
-|-----|-----|---|---|---|
-| userName      | Fetcher ou un de ses parents | Nom de l'utilisateur | DjuDju | null |
-| password      | Fetcher ou un de ses parents | mot de passe | pom_549 | null |
-| tokenProvider | Fetcher ou un de ses parents | point d'accès du service fournissant le token | auth | null |
-| token | Fetcher ou un de ses parents | A fournir à la place des autres attributs si on le possède | q<d34gb | null |
-
- ### Autres choses utiles
- L'attribut *noLoader* du composant permet de désactiver l'affichage du loader par défaut.
- On peut appeler la methode invalidate() sur le publisher associé au  composant pour declencher le rechargement des données.
- endPoint est une propriété réctive, par conséquent, sa modification, manuelle via template ou data binbding provoque la mise à jour du contenu.
--->
+PublisherManager.get("docsFetchNextDeparture").invalidate();
+  </template>
+</sonic-code>
 
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProvider` | string | **Required.** Publisher that receives the data. Also the endpoint when `endPoint` is empty. Inherited from ancestors |
+| `serviceURL` | URL (default page origin) | Base URL of the API. Inherited from ancestors |
+| `endPoint` | string | Path appended to `serviceURL`. Reactive |
+| `key` | dot path | Part of the response to publish |
+| `preserveOtherKeys` | boolean | With `key`, keeps the sibling properties of the target |
+| `loader` | `fixed` (when empty) · `inline` | Loader shown during the request. None by default |
+| `lazyload` | boolean | Fetches when the element nears the viewport |
+| `lazyBoundsRatio` | number (default `1`) | Viewport ratio used as margin by `lazyload` |
+| `refetchEveryMs` | number (default `0`) | Polling interval in milliseconds; `0` disables it |
+| `headersDataProvider` | string | Publisher whose data is sent as request headers. Inherited from ancestors |
+| `token` | string | Bearer token. Inherited from ancestors |
+| `userName` · `password` · `tokenProvider` | string | Basic auth used to get a token from `tokenProvider` when no `token` is set. Inherited from ancestors |
+| `credentials` | `omit` · `same-origin` · `include` | `fetch` credentials mode. Inherited from ancestors |
+| `cache` | `RequestCache` value | `fetch` cache mode |
+| `addHTTPResponse` | boolean | Adds the HTTP response as `_sonic_http_response_` on the data. Inherited from ancestors |
+| `localStorage` | `disabled` (default) · `enabled` | Persists the publisher in `localStorage` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Content, hidden while the request is pending |
+
+| Event | Description |
+|-------|-------------|
+| `loading` | The request starts |
+| `load` | The data is published |

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

@@ -1,9 +1,34 @@
-# if
+# If
 
-The **sonic-if** component shows its slot when **`.condition`** is true. In Lit, bind `.condition` from store-driven state (`@subscribe` on a `formDataProvider` field) — live preview and **TypeScript source are the same file** (`docs-lit-demo`):
+**`sonic-if`** renders its default slot only while `condition` is true. Use it to show or hide a block from reactive state; with no `condition`, the content is not rendered. The host uses `display: contents`, so it adds no box to the layout.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-if condition>
+      <sonic-badge type="success">CN 001 · Boarding</sonic-badge>
+    </sonic-if>
+    <sonic-if>
+      <sonic-badge type="danger">Never rendered</sonic-badge>
+    </sonic-if>
+  </template>
+</sonic-code>
+
+`condition` is a boolean attribute: **any value, even `condition="false"`, counts as true**. To toggle it, remove the attribute or bind the property.
+
+## Reactive condition
+
+In Lit, bind `.condition` to state read with `@subscribe`. Here a checkbox writes to a `formDataProvider` and the component re-renders from it.
 
 <docs-lit-demo for="docs-toggle-if-demo"></docs-lit-demo>
 
-Plain HTML without Lit: [HTML integration](#docs/_misc/html-integration.md/html-integration).
+## API reference
 
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `condition` | boolean (default `false`) | Renders the default slot when true |
 
+| Slot | Description |
+|------|-------------|
+| *(default)* | Content rendered while `condition` is true |