@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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

@@ -1,12 +1,14 @@
 # Toast
 
-Toasts show short-lived feedback in a fixed stack at the bottom right of the page. Call **`SonicToast.add()`** (also `window.SonicToast`); the **`sonic-toast`** host is created on first use. Use **`label`** for a heading and **`preserve`** when the user must read or act before the toast goes away.
+Toasts surface **short-lived feedback** in a fixed stack (bottom-right in the main window). Queue messages with **`SonicToast.add()`** on the global **`SonicToast`** class—the host **`sonic-toast`** is created automatically. Prefer **`label`** for a heading; use **`preserve`** or interactive **`text`** when the user must read or act before dismiss.
 
 ## Basic example
 
+Click the button to show a toast.
+
 <sonic-code>
   <template>
-    <sonic-button onclick="SonicToast.add({ text: 'Flight CN 001 is now boarding' })">
+    <sonic-button onclick="SonicToast.add({ text: 'Simple notification' })">
       Show toast
     </sonic-button>
   </template>
@@ -14,37 +16,54 @@ Toasts show short-lived feedback in a fixed stack at the bottom right of the pag
 
 ## Status
 
-**`status`** sets the color, the icon and the live-region role. With no `status`, the toast is neutral.
+**`status`** drives color, icon, and live-region behavior. Omit **`status`** or pass an empty string for a neutral toast.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="SonicToast.add({ text: 'Default message' })">Default</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">Success</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">Error</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">Warning</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">Info</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Default message', status: '' })">
+        Default
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">
+        Success
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">
+        Error
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">
+        Warning
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">
+        Info
+      </sonic-button>
     </div>
   </template>
 </sonic-code>
 
 ## Label
 
-**`label`** adds a bold heading above **`text`**. `title` is a deprecated alias.
+Set **`label`** for a bold title above **`text`**. **`title`** still works but is deprecated—use **`label`** in new code.
 
 <sonic-code>
   <template>
-    <sonic-button
-      onclick="SonicToast.add({ label: 'Gate change', text: 'Flight CN 001 now departs from gate B12.', status: 'warning' })"
-    >
-      Toast with label
-    </sonic-button>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button
+        onclick="SonicToast.add({ label: 'Success', text: 'Your request was processed.', status: 'success' })"
+      >
+        Toast with label
+      </sonic-button>
+      <sonic-button
+        onclick="SonicToast.add({ label: 'Error', text: 'Processing failed. Try again.', status: 'error' })"
+      >
+        Error with label
+      </sonic-button>
+    </div>
   </template>
 </sonic-code>
 
 ## HTML in text
 
-**`text`** and **`label`** accept HTML strings. A link or form control in **`text`** turns on **`preserve`** automatically.
+**`text`** (and **`label`**) can include HTML strings. Links and controls in **`text`** automatically enable **`preserve`** so the toast does not auto-hide while the user interacts.
 
 <sonic-code>
   <template>
@@ -58,12 +77,12 @@ Toasts show short-lived feedback in a fixed stack at the bottom right of the pag
 
 ## Preserve
 
-Toasts hide after 6 seconds; the timer pauses on hover and focus. **`preserve`** keeps the toast until the user closes it.
+Without **`preserve`**, toasts auto-hide after about six seconds (timer pauses on hover or focus). Set **`preserve`** to keep the toast until the user closes it.
 
 <sonic-code>
   <template>
     <sonic-button
-      onclick="SonicToast.add({ text: 'Turbulence ahead: please fasten your seat belt', status: 'info', preserve: true })"
+      onclick="SonicToast.add({ text: 'This toast stays until you dismiss it', status: 'info', preserve: true })"
     >
       Persistent toast
     </sonic-button>
@@ -72,12 +91,12 @@ Toasts hide after 6 seconds; the timer pauses on hover and focus. **`preserve`**
 
 ## Dismiss forever
 
-With **`dismissForever`** and a stable **`id`**, closing the toast is stored in `localStorage` and later `add()` calls with that `id` are ignored. A toast identical to one already shown (ignoring `id`) is never added twice.
+With **`dismissForever`** and a stable **`id`**, closing the toast stores dismissal in **`localStorage`**—**`SonicToast.add`** skips it on later visits. Duplicate payloads (same fields, ignoring **`id`**) are not queued twice.
 
 <sonic-code>
   <template>
     <sonic-button
-      onclick="SonicToast.add({ id: 'welcome-toast', label: 'Welcome', text: 'Close me and I will not come back after a reload.', status: 'info', dismissForever: true })"
+      onclick="SonicToast.add({ id: 'unique-toast-id', text: 'Dismiss forever hides this across reloads', status: 'info', dismissForever: true })"
     >
       Dismiss forever
     </sonic-button>
@@ -86,62 +105,112 @@ With **`dismissForever`** and a stable **`id`**, closing the toast is stored in
 
 ## Ghost
 
-**`ghost`** renders a semi-transparent, non-interactive toast, for example for a background task.
+**`ghost`** renders a semi-transparent, non-interactive toast—useful for loading or background states. **`SonicToast.removeAll`** leaves ghost toasts in place.
 
 <sonic-code>
   <template>
     <sonic-button
-      onclick="SonicToast.add({ text: 'Syncing in the background', status: 'info', ghost: true })"
+      onclick="SonicToast.add({ text: 'Ghost toast (non-interactive)', status: 'info', ghost: true })"
     >
       Ghost toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## Removing toasts
+## Dismissal
+
+Use static helpers to clear the stack from app logic (for example after navigation).
 
-Static helpers clear the stack from script, for example after navigation. **`removeAll()`** keeps ghost toasts; **`removeTemporaryItems()`** keeps preserved ones.
+### Remove all
+
+Removes every toast except **`ghost`** items.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="SonicToast.add({ text: 'Temporary success', status: 'success' })">Add success</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Temporary error', status: 'error' })">Add error</sonic-button>
-      <sonic-button onclick="SonicToast.add({ text: 'Persistent info', status: 'info', preserve: true })">Add persistent</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 1', status: 'info' })">Add toast 1</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 2', status: 'success' })">Add toast 2</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 3', status: 'warning' })">Add toast 3</sonic-button>
+      <sonic-button onclick="SonicToast.removeAll()">Remove all</sonic-button>
     </div>
-    <div class="flex flex-wrap gap-2 mt-3">
-      <sonic-button variant="outline" onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
-      <sonic-button variant="outline" onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
-      <sonic-button variant="outline" onclick="SonicToast.removeAll()">Remove all</sonic-button>
+  </template>
+</sonic-code>
+
+### Remove by status
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Success toast', status: 'success' })">Success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Error toast', status: 'error' })">Error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Warning toast', status: 'warning' })">Warning</sonic-button>
+      <sonic-button onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
+      <sonic-button onclick="SonicToast.removeItemsByStatus('error')">Remove error</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+### Remove temporary items
+
+Removes toasts that are not **`preserve`**.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary toast', status: 'info' })">Temporary</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Persistent toast', status: 'success', preserve: true })">
+        Persistent
+      </sonic-button>
+      <sonic-button onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
     </div>
   </template>
 </sonic-code>
 
-Inside an iframe, toasts are forwarded to the parent window's stack when the parent also loads Concorde.
+## Combined options
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({
+      id: 'welcome-toast',
+      label: 'Welcome',
+      text: 'Welcome to the platform. Explore the docs to get started.',
+      status: 'success',
+      dismissForever: true
+    })"
+    >
+      Full example
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+Each toast uses **`role="alert"`** for **`error`** and **`role="status"`** otherwise (with **`aria-live="polite"`** when applicable). Status icons are decorative (**`aria-hidden`**). The close control has an i18n **`aria-label`**. When there is no **`label`**, a truncated string **`aria-label`** may be derived from plain **`text`**.
 
 ## API reference
 
-Options of **`SonicToast.add(options)`**:
+Options passed to **`SonicToast.add(conf)`**:
 
 | Option | Values | Description |
 |----------|---------|-------------|
-| `text` | string · Lit template | Body, required; HTML strings allowed |
-| `label` | string · Lit template | Heading above `text` |
-| `title` | string · Lit template | Deprecated alias of `label` |
-| `status` | `success` · `error` · `warning` · `info` (default neutral) | Color and icon; `error` gets `role="alert"`, others `role="status"` |
-| `id` | string · number (default timestamp) | Identifier for `removeItemById` and `dismissForever` |
-| `preserve` | boolean | No auto-hide; forced when `text` contains a link or control |
-| `ghost` | boolean | Semi-transparent and non-interactive; kept by `removeAll` |
-| `dismissForever` | boolean | Remember the dismissal in `localStorage`; needs a stable `id` |
-| `styleSheet` | `CSSResult` · `CSSStyleSheet` · array | Extra styles adopted by the toast |
-| `useSlot` | boolean | Legacy: render `text` in the light DOM |
+| `text` | string · Lit template | Main body; HTML strings are supported |
+| `label` | string · Lit template | Optional heading above **`text`** |
+| `title` | string · Lit template | Deprecated alias for **`label`** |
+| `status` | `success` · `error` · `warning` · `info` · `` (empty) | Semantic styling and live region behavior |
+| `id` | string · number | Stable id for deduplication and **`dismissForever`** (defaults to timestamp) |
+| `preserve` | boolean | Skip auto-hide; forced when **`text`** contains interactive markup |
+| `ghost` | boolean | Semi-transparent and non-interactive; kept by **`removeAll`** |
+| `dismissForever` | boolean | Persist dismissal in **`localStorage`** when closed (requires stable **`id`**) |
+| `styleSheet` | modal style input | Extra adopted styles on the toast item shadow root |
+| `useSlot` | boolean | Legacy: project **`text`** into the light DOM slot |
 
 | Method | Description |
 |--------|-------------|
-| `SonicToast.add(options)` | Show a toast; returns the stored config, or `null` when skipped |
-| `SonicToast.removeAll()` | Remove every toast except ghosts |
-| `SonicToast.removeItemsByStatus(status)` | Remove toasts with this `status` |
-| `SonicToast.removeItemById(id)` | Remove one toast |
-| `SonicToast.removeTemporaryItems()` | Remove toasts without `preserve` |
+| `SonicToast.add(conf)` | Append a toast; returns the config or **`null`** if skipped (dismissed forever or duplicate) |
+| `SonicToast.removeAll()` | Remove all non-**`ghost`** toasts |
+| `SonicToast.removeItemsByStatus(status)` | Remove toasts matching **`status`** |
+| `SonicToast.removeItemById(id)` | Remove a single toast by **`id`** |
+| `SonicToast.removeTemporaryItems()` | Remove toasts without **`preserve`** |
 
-`sonic-toast` and `sonic-toast-item` are created by `add()`; do not write them in markup. `sonic-toast-message-subscriber` shows a toast for each `{ type: "public", content, status }` entry of its `messages` property.
+**`sonic-toast`** is mounted automatically; **`sonic-toast-item`** is internal. In iframes, toasts can delegate to the parent window via **`postMessage`**.

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

@@ -1,12 +1,12 @@
 # Tooltip
 
-**`sonic-tooltip`** shows a short `label` in a bubble when the trigger in the default slot is hovered or receives focus. With no `placement`, the bubble sits on `top`, centered. An empty `label` hides the bubble, like `disabled`.
+Tooltip shows a short **`label`** on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default **`placement`** is **`top`** (center-aligned). An empty **`label`** hides the bubble the same way as **`disabled`**.
 
 ## Basic example
 
 <sonic-code>
   <template>
-    <sonic-tooltip label="Cruising at Mach 2.04">
+    <sonic-tooltip label="Additional context on hover">
       <sonic-button variant="outline">Hover me</sonic-button>
     </sonic-tooltip>
   </template>
@@ -14,34 +14,67 @@
 
 ## Placement
 
-`top` · `bottom` · `left` · `right` set the side. Add `-start` or `-end` to align the bubble with an edge of the trigger instead of its center. The bubble is repositioned while open to stay in the viewport.
+Use **`top`** · **`bottom`** · **`left`** · **`right`** for the main axis. Add **`-start`** or **`-end`** to align the bubble along the anchor edge.
 
 <sonic-code>
   <template>
-    <div class="flex flex-wrap gap-3">
-      <sonic-tooltip placement="top" label="top"><sonic-button minWidth="9rem">top</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="top-start" label="top-start"><sonic-button minWidth="9rem">top-start</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="top-end" label="top-end"><sonic-button minWidth="9rem">top-end</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="bottom" label="bottom"><sonic-button minWidth="9rem">bottom</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="bottom-start" label="bottom-start"><sonic-button minWidth="9rem">bottom-start</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="bottom-end" label="bottom-end"><sonic-button minWidth="9rem">bottom-end</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="left" label="left"><sonic-button minWidth="9rem">left</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="left-start" label="left-start"><sonic-button minWidth="9rem">left-start</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="left-end" label="left-end"><sonic-button minWidth="9rem">left-end</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="right" label="right"><sonic-button minWidth="9rem">right</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="right-start" label="right-start"><sonic-button minWidth="9rem">right-start</sonic-button></sonic-tooltip>
-      <sonic-tooltip placement="right-end" label="right-end"><sonic-button minWidth="9rem">right-end</sonic-button></sonic-tooltip>
+    <div class="flex flex-wrap gap-2">
+      <sonic-tooltip placement="top" label="Top">
+        <sonic-button>Top</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom" label="Bottom">
+        <sonic-button>Bottom</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right" label="Right">
+        <sonic-button>Right</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left" label="Left">
+        <sonic-button>Left</sonic-button>
+      </sonic-tooltip>
     </div>
   </template>
 </sonic-code>
 
-## Multiline label
+### Aligned placements
 
-Line breaks in `label` (a real newline or `&#10;`) are kept. Each line is trimmed and the bubble wraps at `18rem`.
+<sonic-code>
+  <template>
+    <div class="flex gap-3 flex-wrap">
+      <sonic-tooltip placement="top-start" label="Top start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="top-end" label="Top end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top end</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom-start" label="Bottom start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom-end" label="Bottom end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom end</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right-start" label="Right start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right-end" label="Right end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right end</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left-start" label="Left start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left-end" label="Left end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left end</sonic-button>
+      </sonic-tooltip>
+    </div>
+  </template>
+</sonic-code>
+
+## Label formatting
+
+**`label`** supports line breaks (`\n` in markup or multiline text). Lines are trimmed; **`&nbsp;`** is normalized to spaces. **`white-space: pre-line`** preserves breaks in the bubble (max width **18rem**).
 
 <sonic-code>
   <template>
-    <sonic-tooltip label="Gate B12&#10;Boarding at 08:15">
+    <sonic-tooltip label="First line&#10;Second line">
       <sonic-button variant="outline">Multiline label</sonic-button>
     </sonic-tooltip>
   </template>
@@ -49,7 +82,7 @@ Line breaks in `label` (a real newline or `&#10;`) are kept. Each line is trimme
 
 ## Focusable
 
-Set `focusable` when the trigger is not focusable itself (text, icon): the host gets `tabindex="0"` so keyboard users can open the tooltip. The bubble uses `popover="hint"`; without Popover API support, the label falls back to a native `title` on one line.
+On non-interactive triggers, set **`focusable`** so the host gets **`tabindex="0"`** and the tooltip opens on keyboard focus as well as hover.
 
 <sonic-code>
   <template>
@@ -65,8 +98,6 @@ Set `focusable` when the trigger is not focusable itself (text, icon): the host
 
 ## Disabled
 
-`disabled` never shows the bubble and sets `tabindex="-1"` on the host.
-
 <sonic-code>
   <template>
     <sonic-tooltip disabled label="Not shown">
@@ -75,15 +106,19 @@ Set `focusable` when the trigger is not focusable itself (text, icon): the host
   </template>
 </sonic-code>
 
+## Accessibility
+
+The bubble uses **`popover="hint"`** (non-modal, no pointer capture). Prefer **`focusable`** when the slotted content is not already focusable. When the Popover API is unavailable, the host falls back to the native **`title`** attribute with a single-line label. Opacity transitions respect **`prefers-reduced-motion`**.
+
 ## API reference
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `label` | string | Tooltip text; empty or whitespace-only hides the bubble |
-| `placement` | `top` (default) · `bottom` · `left` · `right`, each with optional `-start` · `-end` | Side and alignment relative to the trigger |
-| `disabled` | boolean | Never show the bubble; sets `tabindex="-1"` on the host |
-| `focusable` | boolean | Sets `tabindex="0"` on the host so the tooltip opens on keyboard focus |
+| `label` | string | Tooltip copy; whitespace-only values suppress the bubble |
+| `placement` | `top` (default) · `bottom` · `left` · `right` · `top-start` · `top-end` · `bottom-start` · `bottom-end` · `left-start` · `left-end` · `right-start` · `right-end` | Position relative to the trigger; repositions while open |
+| `disabled` | boolean | Suppress show/hide; sets **`tabindex="-1"`** on the host |
+| `focusable` | boolean | Add **`tabindex="0"`** on the host for keyboard access |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | Trigger content |
+| *(default)* | Trigger content (hover target) |

package/docs/{docs/getting-started → src/docs/_core-concept}/dataFlow.md

@@ -1,6 +1,6 @@
 # Data flow
 
-Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a **DataProvider** store.
+Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a **DataProvider** store (legacy **Publisher** API: [Legacy: Sharing data](#docs/_getting-started/pubsub.md/pubsub)).
 
 ## Quick map
 
@@ -16,8 +16,8 @@ Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, d
 | HTTP POST (body from store) | `@post` + `Endpoint` + body `DataProviderKey` |
 | HTTP PUT / PATCH (body from store) | `@put` / `@patch` — same model as `@post` |
 | Forms | `formDataProvider` + `name` on fields (no Subscriber on form elements) |
-| Derived / aggregate (JSONata) | `derive()` or `sonic-jsonata` — [Jsonata](/core/components/functional/jsonata) |
-| Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](/docs/misc/docs-mock-api) |
+| Derived / aggregate (JSONata) | `derive()` or `sonic-jsonata` — [Jsonata](#core/components/functional/jsonata/jsonata.md/jsonata) |
+| Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) |
 
 Skill: `concorde-get-set-dp` in the package `ai/` folder.
 
@@ -36,15 +36,15 @@ get(cartKey);
   </template>
 </sonic-code>
 
-Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path).
+Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
-[DataProviderKey](/docs/misc/dataProviderKey)
+[DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey)
 
 ## Decorators
 
 | Decorator | Role |
 |-----------|------|
-| `@subscribe` | Read-only property from store — [data configuration](/docs/getting-started/my-first-component) (type + key + scope) |
+| `@subscribe` | Read-only property from store — [data configuration](#docs/_getting-started/my-first-component.md/my-first-component) (type + key + scope) |
 | `@publish` | Push property writes to store |
 | `@handle` | Method called on assignment |
 | `@ancestorAttribute` | Copy ancestor HTML attribute onto property |
@@ -52,15 +52,15 @@ Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.
 | `@post` | HTTP POST into `ApiResult&lt;T&gt;` (body from a publisher) |
 | `@put` / `@patch` | HTTP PUT / PATCH into `ApiResult&lt;T&gt;` |
 
-Walkthrough: [My first component](/docs/getting-started/my-first-component)
+Walkthrough: [My first component](#docs/_getting-started/my-first-component.md/my-first-component)
 
 ## HTTP and lists
 
-- [@get](/docs/decorators/get) — single GET on a component
-- [@post](/docs/decorators/post) — POST with body read from a `DataProviderKey`
-- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH (same options as `@post`)
-- [List](/core/components/functional/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
-- [Queue](/core/components/functional/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
+- [@get](#docs/_decorators/get.md/get) — single GET on a component
+- [@post](#docs/_decorators/post.md/post) — POST with body read from a `DataProviderKey`
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH (same options as `@post`)
+- [List](#core/components/functional/list/list.md/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
+- [Queue](#core/components/functional/queue/queue.md/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
 
 ## Starter kit
 
@@ -75,13 +75,14 @@ Interactive routes mirror these patterns (`/concepts/*`, `/demo/*`).
 Use when you need **client-side aggregations** (groupby, top N, chart shapes) from existing DataProviders — without inline app JS in SDUI.
 
 - Primitive: `derive({ inputs, compute, output, variables? })` from `@supersoniks/concorde/utils` (read-only output, debounce, generation, cycle detection, `{output}/_state_`).
-- SDUI adapter: [`sonic-jsonata`](/core/components/functional/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
-- vs [`sonic-mix`](/core/components/functional/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
+- SDUI adapter: [`sonic-jsonata`](#core/components/functional/jsonata/jsonata.md/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
+- vs [`sonic-mix`](#core/components/functional/mix/mix.md/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
 
 ## Legacy integration
 
 | Topic | Page |
 |-------|------|
-| `data-bind` HTML (plain HTML hosts) | [HTML integration](/docs/misc/html-integration) — doc demos use Lit in `src/docs/example/` |
-| `@onAssign` | [@onAssign](/docs/decorators/on-assign) (prefer `@handle`) |
-| `sonic-fetch` alone | [Fetch](/core/components/functional/fetch) |
+| `Subscriber` / `Fetcher` mixins on app code | [Legacy: Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber), [Legacy: My first subscriber](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber) |
+| `data-bind` HTML (plain HTML hosts) | [HTML integration](#docs/_misc/html-integration.md/html-integration) — doc demos use Lit in `src/docs/example/` |
+| `@onAssign` | [@onAssign](#docs/_decorators/on-assign.md/on-assign) (prefer `@handle`) |
+| `sonic-fetch` alone | [Fetch](#core/components/functional/fetch/fetch.md/fetch) |

package/docs/src/docs/_core-concept/overview.md

@@ -0,0 +1,57 @@
+# lit + tailwind + vite
+
+**Some notes for an overview of Concorde's functioning**
+
+## Standard Web components
+A web component is simply a **custom HTML element** created using web standards:
+
+**web component** = [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) + [shadowDom](https://developer.mozilla.org/fr/docs/Web/Web_Components/Using_shadow_DOM) + [HTML templates](https://developer.mozilla.org/fr/docs/Web/HTML/Element/template)
+
+## Lit Library
+
+Concorde components are written using the lightweight Lit library: https://lit.dev/.
+
+A good portion of the elements documented on the Lit website are standard JavaScript concepts (e.g., [mixins](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#mix-ins), [tagged template literals](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Template_literals#gabarits_%C3%A9tiquet%C3%A9s)).
+
+The **library simplifies the writing of web components** by automating certain tasks:
+
+- Creation of an **open mode shadow DOM** (the component is accessible from the outside via its shadow root property).
+- [Rendering function](https://lit.dev/docs/components/rendering/) based on [tagged template literals](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Template_literals#gabarits_%C3%A9tiquet%C3%A9s)
+- [Reactive properties](https://lit.dev/docs/components/properties/) that trigger rendering when modified.
+
+Our use of Lit rarely goes beyond this [hello world](https://lit.dev/playground/#sample=examples/hello-world)
+
+## Typescript Language
+
+We write the components in [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html), which is then compiled into JS.
+
+Static and inferred typing provides stronger validation of the program's functioning during compilation.
+However, we often use the "any" type due to time constraints.
+
+Lit uses TypeScript to simplify development through metadata:
+- Simplified declaration of `custom elements` via @customElement
+- Generation of `reactive properties` via @property.
+
+☢️**Warning**:
+- During development, we operate in interpreted mode, which is faster but allows errors that won't pass during the build.
+- It is important to **build a distribution before pushing the code** to ensure everything is fine.
+
+## Compatibility with Classic JS Libraries
+
+Compatibility issues may arise when using JS libraries, particularly regarding DOM traversal.
+This is because these libraries are blocked from traversing the DOM due to the presence of the shadow DOM.
+Here are some examples of things that may cause problems:
+
+- Latest FontAwesome in SVG mode, icons are not replaced
+- Libraries associated with jQuery
+- document.getElementById
+- ...
+
+## Topics to Explore for Further Learning
+
+
+[🧱 Creating components](#docs/_getting-started/create-a-component.md/create-a-component)
+
+[🎨 Adding styles](#docs/_getting-started/theming.md/theming)
+
+[🥨 Sharing data](#docs/_getting-started/pubsub.md/pubsub)

package/docs/src/docs/_core-concept/subscriber.md

@@ -0,0 +1,75 @@
+# Legacy: Subscriber mixin
+
+> **New app components:** [My first component](#docs/_getting-started/my-first-component.md/my-first-component) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — extend `LitElement` with decorators (`@subscribe`, `@ancestorAttribute`, …). This mixin remains in **core** components (`sonic-list`, `sonic-fetch`, …) and [legacy tutorials](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber).
+
+The Subscriber mixin was commonly extended by Concorde core components and older destination components. Pure UI components usually don't extend it, especially those outside of form components.
+
+## DataProvider Attribute: Automatic Filling of Subscriber Properties
+
+Upon being added to the DOM (connectedCallback), subscribers search for the first occurrence of the `dataProvider` attribute in their parent's HTML structure.
+
+The value of this attribute is the DataProvider path (see [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) and [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey); legacy API: [Sharing Data](#docs/_getting-started/pubsub.md/pubsub)).
+
+The subscriber then subscribes to the publisher as a data template to be filled.
+
+The reactive properties of the component reflect in real-time the properties with the same name in the publisher.
+
+This functionality is commonly used in the generic components [fetch](#core/components/functional/fetch/fetch.md/fetch), [queue](#core/components/functional/queue/queue.md/queue), and [list](#core/components/functional/list/list.md/list).
+
+If the subscriber is inside another subscriber, it can subscribe to a data of its parent using the attribute `subDataProvider = 'address.of.my.data'` instead of the parent's data. This allows for dynamic behavior.
+
+## Automated Translation
+
+In a similar manner, searching for ancestor attributes can be used to configure automatic translation for any property starting with "wording" and ending with a label identifier recognized by the wordingProvider API.
+
+Normally, this API is globally configured and not within the component. Therefore, remember to prefix translatable label identifiers present in the ticketing system, for example, with "wording".
+
+## Reactive Property `props`
+
+The value of this property can be provided as a JSON object or any other value. This value is then assigned to the associated publisher via the `dataProvider` attribute. As a result, the reactive properties of all subscribers associated with the same `dataProvider` are filled as mentioned above.
+
+## Disabling Automatic Filling of Reactive Properties
+
+It is possible to disable the automatic filling of reactive properties in a particular component. To do so, set the variable `noAutoFill = true` in the component's class. However, the reactive property `props` will still be updated.
+
+For example, `sonic-subscriber` and `sonic-fetch` have this attribute because they do not have reactive properties.
+
+**☢ CAUTION:** When creating an object of type Subscriber or Fetcher, make sure to use the mixins and not directly extend the concrete fetch component (`sonic-fetch`) and subscriber component (`sonic-subscriber`). This is because the `noAutofill = true` attribute is set in those components.
+
+**TIPS:** 
+If you disable automatic filling, you will likely make the rendering dynamic by writing expressions like `this.props.my.subproperty`. If `props` is updated, the rendering will be triggered. However, if `this.props.my.subproperty` is directly modified, the rendering will not be triggered. To achieve more reactivity, you can enable rendering when any subproperty is modified. Simply set the variable `renderOnPropsInternalChange = true` in the class that implements the corresponding mixin.
+
+## Data Binding
+
+Suppose that:
+
+- You have a subscriber subscribed to a publisher via its `dataProvider` attribute.
+- The published data has the following structure:
+
+<sonic-code language="javascript">
+  <template>
+    {"img": { "avatar": "my-avatar.jpg", "caption": "look at my smile" }, "email": "an.email@example.com" }
+  </template>
+</sonic-code>
+- We want to keep the display of an image and its `title` attribute up to date, as well as a "contact" button to email the person in the photo. The content of the subscriber could be as follows:
+
+In a **Lit** app, use the same data with [data configuration](#docs/_getting-started/my-first-component.md/my-first-component) (`@subscribe` + `DataProviderKey`) on a small row component — see `docs-user` in `src/docs/example/users.ts`.
+
+For **HTML-only** embedding (no Lit), attribute binding is described in [HTML integration](#docs/_misc/html-integration.md/html-integration) and in the Legacy [Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber) pages.
+
+This pattern also illustrates:
+
+- Binding to subproperties using dot syntax, as done for the `src` attribute of the `img` tag.
+- Using a simple expression to include the property within a string, as in creating a `mailto` link.
+- Using formatting functions, as in the `title` attribute of the `img` tag. You can find (and add) formatting functions in the `core/utils/Format.ts` file.
+- Writing for properties that are in camel case. Convert everything to lowercase and add hyphens. Note that `innerHTML` (or `outerHTML`) is a special case where no hyphens are added between each letter.
+
+**Note:** Data binding implies that updating the `img.src` data via the publisher will change the photo without any additional calls.
+
+**Special Variables:**
+- `_self_` targets the root of the data. This is useful, for example, when the data is a pure string.
+- `_parent_` targets the parent publisher of the current publisher, if any. For example, the subscribers of lists have the complete data of the list as their parent.
+- `_metadata_` is only used in the case of *sonic-list* at the moment. In a simple list, `_metadata_` see the (list)[] component for further details
+
+**Disabling this functionality:**
+You can disable data binding if it is not needed by calling `DataBinding.disable()`.