@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -0,0 +1,150 @@
+# Date
+
+**`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.
+
+## Basic example
+
+`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>
+    <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
+
+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.
+
+Without a start, the range starts now. If the end is before the start, the two are swapped.
+
+<sonic-code>
+  <template>
+    <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>
+
+## Range wording
+
+`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>
+    <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>
+
+## Format options
+
+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>
+    <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
+
+With no `language`, the component follows `<html lang>` and updates when it changes. Pass a BCP 47 tag to force one.
+
+<sonic-code>
+  <template>
+    <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
+
+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>
+    <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>
+
+## Custom parts
+
+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-sm rounded-lg overflow-hidden">
+      <sonic-date
+        designMode
+        noShadowDom
+        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="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 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/docs/src/core/components/functional/fetch/fetch.md

@@ -0,0 +1,108 @@
+# Fetch
+
+**`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="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>
+
+## 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="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>
+
+## Key
+
+`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" 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>
+
+## Loader and skeleton
+
+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 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>
+
+## Text responses
+
+When the response type starts with `text/`, the provider holds `{ text: "…" }`.
+
+<sonic-code>
+  <template>
+    <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";
+
+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/docs/src/core/components/functional/if/if.md

@@ -0,0 +1,34 @@
+# If
+
+**`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>
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `condition` | boolean (default `false`) | Renders the default slot when true |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Content rendered while `condition` is true |

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

@@ -0,0 +1,61 @@
+# Jsonata
+
+**`sonic-jsonata`** reads one data provider, evaluates a [JSONata](https://jsonata.org) expression on it and writes the result to another data provider. Use it for read-only aggregates such as groups, rankings and totals; use [Mix](/core/components/functional/mix) to compose data in both directions, and [`derive`](/docs/getting-started/dataFlow) for several inputs or a TypeScript function.
+
+## Group and sort
+
+`inputProvider` is available as `$input` and the result is written to `outputProvider`. Each field of the optional `formDataProvider` store becomes a variable (`$direction` here): changing it recomputes the output without fetching again.
+
+<docs-lit-demo for="docs-jsonata-space-cats-demo"></docs-lit-demo>
+
+JSONata returns a single object instead of an array when only one item matches. Wrap the expression in `$append([], …)` when a list renders the output.
+
+## Totals
+
+A `( … )` block declares local variables and returns an object; read its fields with `sonic-value`. Change the reserve to recompute the block fuel.
+
+<docs-lit-demo for="docs-jsonata-table-totals-demo"></docs-lit-demo>
+
+## States
+
+The evaluation state is published on `{outputProvider}/_state_` as `{ status, error }`, with `status` among `loading` · `ready` · `empty` · `error`. Display it with [States](/core/components/functional/states).
+
+<sonic-code>
+  <template>
+    <div serviceURL="/docs-mock-api">
+      <sonic-fetch dataProvider="jsonataStateFlights" endPoint="flights" key="flights"></sonic-fetch>
+      <sonic-jsonata
+        inputProvider="jsonataStateFlights"
+        outputProvider="jsonataLanded"
+        expression='{"landed": $count($input[status="landed"])}'
+      ></sonic-jsonata>
+      <sonic-states dataProvider="jsonataLanded/_state_" data-path="status">
+        <template data-value="loading">Counting flights…</template>
+        <template data-value="ready">Landed flights: <sonic-value dataProvider="jsonataLanded" key="landed"></sonic-value></template>
+        <template data-value="error">Expression error</template>
+      </sonic-states>
+    </div>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `inputProvider` | string | Source data provider, bound to `$input`. Required |
+| `outputProvider` | string | Data provider that receives the result. Required |
+| `expression` | JSONata string (max 8,000 characters) | Expression to evaluate. Required |
+| `formDataProvider` | string | Store whose fields become variables (`$name`) |
+| `outputSchema` | object | Light check of the result: `type` and `required` only; a mismatch sets the `error` state |
+
+| Helper | Description |
+|--------|-------------|
+| `$ucFirst(value)` | Upper-cases the first letter |
+| `$currency(value, locale?, currency?)` | Formats a price (default `fr-FR` and `EUR`) |
+| `$percent(value, locale?, digits?)` | Formats a ratio as a percentage (default `fr-FR` and `0` digits) |
+| `$date(value, locale?, optionsJson?)` | Formats a date (default `fr-FR`, medium style) |
+| `$toChart(items, labelKey, valueKey, datasetLabel?)` | Converts rows to `{ labels, datasets }` for a chart |
+
+Expressions have no access to the DOM or the network.
+
+No slots.

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

@@ -0,0 +1,125 @@
+# List
+
+**`sonic-list`** renders one row per entry of its `props` array, either set directly or loaded with `fetch`. In TypeScript, prefer the `.items` row renderer (with `.separator` · `.noItems` · `.skeleton`); `<template>` children are for plain HTML hosts without Lit. Each row gets its own data provider at `<dataProvider>/list-item/<index>`.
+
+## Basic example
+
+Add `fetch` to load `props` from `serviceURL` + `endPoint` (or `dataProvider` when `endPoint` is empty). `key` picks the array inside the response. Without `fetch`, the list only renders the `props` it receives.
+
+<sonic-code>
+  <template>
+    <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=arrivals" key="flights" class="grid gap-1">
+      <template>
+        <div class="text-sm" data-bind ::inner-html="<b>$time</b> $code from $city ($airport)"></div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+This example uses HTML templates; from Lit, use the [row renderer](#row-renderer) instead. Fetch attributes (`lazyload` · `refetchEveryMs` · headers · authentication) are shared with [Fetch](/core/components/functional/fetch).
+
+## Row renderer
+
+From a Lit component, set `.items` to a function `(item, metadata) => TemplateResult`. Functions only pass as properties, so always use the `.` binding: the same applies to `.separator` · `.noItems` · `.skeleton`. `metadata` holds `key` · `even` · `odd` · `firstChild` · `lastChild` · `onlyChild`.
+
+<docs-lit-demo for="docs-list-alternate-demo"></docs-lit-demo>
+
+## Row variants
+
+In HTML, `templateKey` (default `template`) names the row field that selects a `<template data-value="…">`. Rows without a match cycle through the `<template>` children that have no `data-value`. From Lit, branch inside the `items` callback instead.
+
+<sonic-code>
+  <template>
+    <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=departures" key="flights" templateKey="status" class="grid gap-1">
+      <template>
+        <div class="text-sm" data-bind ::inner-html="$code to $city"></div>
+      </template>
+      <template data-value="delayed">
+        <div class="text-sm text-warning" data-bind ::inner-html="$code to $city: delayed"></div>
+      </template>
+      <template data-value="cancelled">
+        <div class="text-sm text-danger line-through" data-bind ::inner-html="$code to $city"></div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+## Separator and empty list
+
+`.separator` renders between rows (not after the last one). `.noItems` renders when the array is empty. In HTML, use `<template data-value="separator">` and `<template data-value="no-item">`.
+
+<docs-lit-demo for="docs-list-separator-demo"></docs-lit-demo>
+
+## Limit and offset
+
+`limit` caps the number of rendered rows and `offset` skips the first ones, without changing the data. With no `limit`, every row is rendered.
+
+<sonic-code>
+  <template>
+    <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=departures" key="flights" limit="3" class="grid gap-1">
+      <template>
+        <div class="text-sm" data-bind ::inner-html="<b>$time</b> $code to $city"></div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+## Objects and `extractValues`
+
+When the data is an object, the list wraps it in a one-row array. Add `extractValues` to render one row per property instead, as `{ key, value }`.
+
+<docs-lit-demo for="docs-list-extract-values-demo"></docs-lit-demo>
+
+## Loading state
+
+With no `loader`, nothing is shown while fetching. Set `loader` (`fixed`) or `loader="inline"` to show a [Loader](/core/components/ui/loader), or provide `.skeleton` / `<template skeleton>` to render placeholder rows; a skeleton replaces the loader. Call `invalidate()` on the list publisher to fetch again.
+
+<sonic-code>
+  <template>
+    <sonic-list fetch loader="inline" serviceURL="/docs-mock-api" dataProvider="flights?direction=arrivals&status=landed" key="flights" class="grid gap-1">
+      <template>
+        <div class="text-sm" data-bind ::inner-html="$code from $city: landed"></div>
+      </template>
+    </sonic-list>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProvider` | string | Publisher of the list. Also the endpoint when `endPoint` is empty. Inherited from ancestors |
+| `fetch` | boolean | Loads `props` from the API. Without it, the list never fetches |
+| `serviceURL` · `endPoint` · `key` | string | Request configuration, see [Fetch](/core/components/functional/fetch) |
+| `templateKey` | string (default `template`) | Row field that selects a `<template data-value>` |
+| `extractValues` | boolean | Renders an object as one `{ key, value }` row per property |
+| `limit` | number (default unlimited) | Maximum number of rendered rows |
+| `offset` | number (default `0`) | Index of the first rendered row |
+| `loader` | `fixed` (when empty) · `inline` | Loader shown while fetching. None by default |
+| `debug` | boolean | Shows each row's data on hover |
+
+Properties (TypeScript / Lit, preferred):
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `props` | array · object | Rows to render |
+| `items` | `(item, metadata) => TemplateResult` | Row renderer |
+| `separator` | `() => TemplateResult` | Rendered between rows |
+| `noItems` | `() => TemplateResult` | Rendered when there are no rows |
+| `skeleton` | `() => TemplateResult` | Rendered while fetching |
+| `itemPropertyMap` | object | `propertyMap` passed to each row subscriber |
+
+Templates (plain HTML hosts):
+
+| Template | Description |
+|----------|-------------|
+| `<template>` | Row markup; several are used in turn |
+| `<template data-value="…">` | Row variant selected by `templateKey` |
+| `<template data-value="separator">` | Between rows |
+| `<template data-value="no-item">` | Empty list |
+| `<template skeleton>` | While fetching |
+
+| Event | Description |
+|-------|-------------|
+| `loading` | A fetch starts |
+| `load` | Data is loaded and assigned to `props` |

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

@@ -0,0 +1,46 @@
+# Mix
+
+**`sonic-mix`** builds a new data provider from parts of other ones. Each key of `composition` maps to a source data provider id, with an optional dot path to a sub-value. The mixed provider is named by the `dataProvider` attribute and stays in sync with its sources in both directions.
+
+## Basic example
+
+Two sources hold the flight and its gate. The mix exposes the whole flight under `flight` and only the gate number under `gate`; children read them like any other data provider.
+
+<sonic-code>
+  <template>
+    <sonic-subscriber dataProvider="docs-mix-flight" props='{"code":"CN 001","route":"CDG → JFK"}'></sonic-subscriber>
+    <sonic-subscriber dataProvider="docs-mix-gate" props='{"gate":"B12","terminal":"2E"}'></sonic-subscriber>
+    <sonic-mix dataProvider="docs-mix-board" composition='{"flight":"docs-mix-flight","gate":"docs-mix-gate.gate"}'>
+      <p>
+        <sonic-value key="flight.code"></sonic-value> ·
+        <sonic-value key="flight.route"></sonic-value> ·
+        gate <sonic-value key="gate"></sonic-value>
+      </p>
+    </sonic-mix>
+  </template>
+</sonic-code>
+
+## Two-way sync
+
+Writing to a source updates the mix, and writing to the mix updates the source. The button changes `docs-mix-gate`; the field writes to `docs-mix-board.gate`.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap items-end gap-4">
+      <sonic-button size="sm" onclick="SonicPublisherManager.get('docs-mix-gate').gate = 'C34'">Gate change to C34</sonic-button>
+      <sonic-input label="Gate (mixed provider)" formDataProvider="docs-mix-board" name="gate"></sonic-input>
+    </div>
+    <p class="mt-2">Source gate: <sonic-value dataProvider="docs-mix-gate" key="gate"></sonic-value></p>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProvider` | string | Id of the mixed data provider. Its content is reset when the composition changes |
+| `composition` | object (JSON) | Keys of the mixed provider mapped to `"providerId"` or `"providerId.path.to.value"` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Content that reads the mixed provider |

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

@@ -0,0 +1,51 @@
+# Queue
+
+**`sonic-queue`** loads a paginated API in batches and renders each batch as an internal [List](/core/components/functional/list). Choose it over `sonic-list` for long or endless lists; the key attributes are `dataProviderExpression` · `limit` · `dataFilterProvider`.
+
+## Lazy load
+
+`dataProviderExpression` is the request path: `$offset` and `$limit` are replaced for each batch. The first batch starts at `offset` (default `0`) with `limit` rows (default `5`, at most `15`). The next batch loads when the end of the list scrolls into view, and the queue stops at the first empty batch. Put the queue in a box with a fixed height and `overflow-y-auto`, then scroll inside it.
+
+<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
+
+Rows come from the `.items` callback, as on [List](/core/components/functional/list); `.noItems` and `.skeleton` work the same way. Without `$offset` in the expression, the queue sends one request and behaves like a list. Set `noLazyload` to load every batch in a row without waiting for the scroll.
+
+## Filters
+
+`dataFilterProvider` names a form store (`formDataProvider`). Each non-empty field is added to the query string; when a field changes, the queue drops the loaded batches and reloads from the first offset, after a `filterTimeoutMs` debounce (default `400`). Search a city, an airport or a flight number.
+
+<docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>
+
+To keep some form fields out of the request, list their names in `filteredFields`, separated by spaces.
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProviderExpression` | string (default: closest ancestor `dataProvider`) | Request path; `$offset` and `$limit` are replaced for each batch |
+| `serviceURL` | string | API base URL; inherited from the closest ancestor |
+| `key` | string | Response property that holds the rows |
+| `limit` | number (default `5`, max `15`) | Rows per batch |
+| `offset` | number (default `0`) | Offset of the first batch |
+| `idKey` | string (default `id`) | Row property used as identity |
+| `dataFilterProvider` | string | Form store whose fields are added to the query; inherited from the closest ancestor |
+| `filteredFields` | space-separated names | Form fields not sent to the API |
+| `filterTimeoutMs` | number (default `400`) | Debounce before reloading after a filter change |
+| `noLazyload` | boolean | Loads all batches without waiting for the scroll |
+| `lazyBoundsRatio` | number (default `1`) | Lazy-load margin, as a multiple of the viewport size |
+| `loader` | `inline` · `fixed` (default `inline`) | Loader shown while a batch loads |
+| `cache` | `RequestCache` (default `default`) | Fetch cache mode |
+| `invalidateOnPageShow` | boolean | Reloads batches when the page is restored from the back/forward cache |
+| `localStorage` | `disabled` · `enabled` (default `disabled`) | Forwarded to each batch list |
+| `debug` | boolean | Shows a live inspector of each batch list's data |
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `items` | `ListItems` | Row renderer |
+| `noItems` | `ListItems` | Rendered when the first batch is empty |
+| `skeleton` | `ListItems` | Rendered while a batch loads |
+| `itemPropertyMap` | object | Forwarded to each batch list |
+
+The queue publisher exposes `resultCount`, the number of rows loaded so far.
+
+No slots. `<template>` children are used as row templates for hosts without Lit; see [HTML integration](/docs/misc/html-integration).