@supersoniks/concorde 5.1.0 → 5.1.2

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

@@ -0,0 +1,97 @@
+# Theme
+
+**`sonic-theme`** is the root element of a Concorde UI: it holds the `--sc-*` design tokens, optionally applies a built-in palette, and is where popovers, modals and toasts are mounted. Import `@supersoniks/concorde/theme` once at the app entry and wrap your app in it. Token names and brand overrides are covered in [Theming](/docs/getting-started/theming).
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-theme color font class="block bg-base p-6 rounded-lg">
+      <sonic-button type="primary">Save changes</sonic-button>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Theme mode
+
+With no `theme` (or `theme="custom"`), only the core tokens and your own `--sc-*` overrides apply. `light` and `dark` apply the built-in palettes; `auto` switches between them with `prefers-color-scheme`.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4 md:grid-cols-2">
+      <sonic-theme theme="light" color font class="block bg-base p-4 rounded-md border border-neutral-200">
+        <p class="text-sm mb-3 opacity-80">theme="light"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+      <sonic-theme theme="dark" color font class="block bg-base p-4 rounded-md">
+        <p class="text-sm mb-3 opacity-80">theme="dark"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+    </div>
+  </template>
+</sonic-code>
+
+## Text color and font
+
+`color` sets the host text color to `--sc-base-content`. `font` applies the base font family, weight and style tokens. Both are off by default. To paint the background, add the Tailwind classes `block` and `bg-base` on the host.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-6 rounded-lg">
+      <p>Body copy inherits the base content color and font from the theme.</p>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Pop container
+
+Overlays such as `sonic-modal` are appended to the last connected `sonic-theme`, or to `document.body` when there is none. `Theme.getPopContainer()` returns that element.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-4 rounded-lg">
+      <sonic-button onclick="document.getElementById('themePopModal').show()">
+        Open modal
+      </sonic-button>
+      <sonic-modal id="themePopModal">
+        <sonic-modal-title>Mounted on theme</sonic-modal-title>
+        <sonic-modal-content>
+          This dialog is appended under the nearest sonic-theme pop container.
+        </sonic-modal-content>
+        <sonic-modal-actions>
+          <sonic-button hideModal>Close</sonic-button>
+        </sonic-modal-actions>
+      </sonic-modal>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Embedded iframes
+
+On connect, the theme posts its resolved `--sc-*` values and linked Google Fonts / Adobe Fonts stylesheets to every iframe on the page (message type `SonicTheme`). An iframe can ask for them again:
+
+<sonic-code language="javascript">
+  <template>
+window.parent.postMessage({ type: "GetSonicTheme" }, "*");
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `theme` | `custom` (default) · `light` · `dark` · `auto` | Built-in palette; `custom` applies core tokens and your overrides only |
+| `color` | boolean | Host text color uses `--sc-base-content` |
+| `font` | boolean | Host uses the base font family, weight and style tokens |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Application content |

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

@@ -1,166 +1,147 @@
 # Toast
 
-## Utilisation de base
+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.
+
+## Basic example
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Message de notification simple' })">
-      Afficher un toast
+    <sonic-button onclick="SonicToast.add({ text: 'Flight CN 001 is now boarding' })">
+      Show toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## Statut
+## Status
 
-Les statuts disponibles sont : `success`, `error`, `warning`, `info` ou vide (par défaut).
+**`status`** sets the color, the icon and the live-region role. With no `status`, the toast is neutral.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Message par défaut', status: '' })">
-        Default
-      </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Opération réussie !', status: 'success' })">
-        Success
-      </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Une erreur est survenue', status: 'error' })">
-        Error
-      </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Attention à ce point', status: 'warning' })">
-        Warning
-      </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Information importante', status: 'info' })">
-        Info
-      </sonic-button>
+      <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>
     </div>
   </template>
 </sonic-code>
 
-## Avec titre
-
-<sonic-code>
-  <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ title: 'Succès', text: 'Votre demande a été traitée avec succès.', status: 'success' })">
-        Toast avec titre
-      </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ title: 'Test', text: 'Une erreur est survenue lors du traitement.', status: 'error' })">
-        Toast d'erreur avec titre
-      </sonic-button>
-    </div>
-  </template>
-</sonic-code>
+## Label
 
-## Avec contenu HTML
-
-Le contenu du toast peut contenir du HTML.
+**`label`** adds a bold heading above **`text`**. `title` is a deprecated alias.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Message avec <strong>HTML</strong> et un <a href=&quot;#&quot;>lien cliquable</a>', status: 'info' })">
-      Toast avec HTML
+    <sonic-button
+      onclick="SonicToast.add({ label: 'Gate change', text: 'Flight CN 001 now departs from gate B12.', status: 'warning' })"
+    >
+      Toast with label
     </sonic-button>
   </template>
 </sonic-code>
 
+## HTML in text
 
-## Persistance
-
-Par défaut, les toasts disparaissent automatiquement. Avec `preserve: true`, le toast reste affiché jusqu'à ce qu'il soit fermé manuellement.
+**`text`** and **`label`** accept HTML strings. A link or form control in **`text`** turns on **`preserve`** automatically.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Ce toast ne disparaîtra pas automatiquement', status: 'info', preserve: true })">
-      Toast persistant
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Message with <strong>HTML</strong> and an <a href=&quot;#&quot;>action link</a>', status: 'info' })"
+    >
+      Toast with HTML
     </sonic-button>
   </template>
 </sonic-code>
 
-## Masquer définitivement
+## Preserve
 
-Avec `dismissForever: true` et un `id`, le toast peut être masqué définitivement. Une fois fermé, il ne réapparaîtra plus même après rechargement de la page.
+Toasts hide after 6 seconds; the timer pauses on hover and focus. **`preserve`** keeps the toast until the user closes it.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ id: 'unique-toast-id', text: 'Ce toast peut être masqué définitivement', status: 'info', dismissForever: true })">
-      Toast avec dismiss forever
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Turbulence ahead: please fasten your seat belt', status: 'info', preserve: true })"
+    >
+      Persistent toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## Fantôme
+## Dismiss forever
 
-Avec `ghost: true`, le toast devient semi-transparent et non-interactif.
+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.
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ text: 'Toast fantôme (semi-transparent)', status: 'info', ghost: true })">
-      Toast ghost
+    <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 })"
+    >
+      Dismiss forever
     </sonic-button>
   </template>
 </sonic-code>
 
+## Ghost
 
-## Méthodes de suppression
-
-### Tout supprimer
-
-Supprime tous les toasts sauf ceux marqués comme `ghost`.
+**`ghost`** renders a semi-transparent, non-interactive toast, for example for a background task.
 
 <sonic-code>
   <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast 1', status: 'info' })">Ajouter toast 1</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast 2', status: 'success' })">Ajouter toast 2</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast 3', status: 'warning' })">Ajouter toast 3</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeAll()">Supprimer tous</sonic-button>
-    </div>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Syncing in the background', status: 'info', ghost: true })"
+    >
+      Ghost toast
+    </sonic-button>
   </template>
 </sonic-code>
 
-### Supprimer par statut
+## Removing toasts
 
-Supprime tous les toasts d'un statut spécifique.
+Static helpers clear the stack from script, for example after navigation. **`removeAll()`** keeps ghost toasts; **`removeTemporaryItems()`** keeps preserved ones.
 
 <sonic-code>
   <template>
     <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast success', status: 'success' })">Success</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast error', status: 'error' })">Error</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast warning', status: 'warning' })">Warning</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeItemsByStatus('success')">Supprimer success</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeItemsByStatus('error')">Supprimer error</sonic-button>
+      <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>
     </div>
-  </template>
-</sonic-code>
-
-### Supprimer les éléments temporaires
-
-Supprime tous les toasts qui ne sont pas marqués comme `preserve`.
-
-<sonic-code>
-  <template>
-    <div class="flex flex-wrap gap-2">
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast temporaire', status: 'info' })">Temporaire</sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Toast persistant', status: 'success', preserve: true })">Persistant</sonic-button>
-      <sonic-button onclick="window.SonicToast.removeTemporaryItems()">Supprimer temporaires</sonic-button>
+    <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>
     </div>
   </template>
 </sonic-code>
 
-## Exemple complet
-
-<sonic-code>
-  <template>
-    <sonic-button onclick="window.SonicToast.add({ 
-      id: 'welcome-toast',
-      title: 'Bienvenue',
-      text: 'Bienvenue sur notre plateforme ! Vous pouvez commencer à explorer les fonctionnalités.',
-      status: 'success',
-      dismissForever: true
-    })">
-      Toast complet
-    </sonic-button>
-  </template>
-</sonic-code>
-
+Inside an iframe, toasts are forwarded to the parent window's stack when the parent also loads Concorde.
+
+## API reference
+
+Options of **`SonicToast.add(options)`**:
+
+| 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 |
+
+| 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` |
+
+`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.

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

@@ -1,82 +1,89 @@
 # 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`.
+
+## Basic example
+
 <sonic-code>
   <template>
-    <sonic-tooltip label="Tada : Text appears">hover me</sonic-tooltip>
+    <sonic-tooltip label="Cruising at Mach 2.04">
+      <sonic-button variant="outline">Hover me</sonic-button>
+    </sonic-tooltip>
   </template>
 </sonic-code>
 
 ## Placement
 
-By default, tooltip is centered next to its content
+`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.
 
 <sonic-code>
   <template>
-    <sonic-tooltip placement="top" label="Top text">
-      <sonic-button>Top</sonic-button>
-    </sonic-tooltip>
-    <sonic-tooltip placement="bottom" label="Bottom text">
-      <sonic-button>Bottom</sonic-button>
-    </sonic-tooltip>
-     <sonic-tooltip placement="right" label="Right text">
-      <sonic-button>Right</sonic-button>
-    </sonic-tooltip>
-    <sonic-tooltip placement="left" label="Left text">
-      <sonic-button>Left</sonic-button>
-    </sonic-tooltip>
+    <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>
   </template>
 </sonic-code>
 
-## More placement
+## Multiline label
+
+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="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="top-end" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top end</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="bottom-start" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="bottom-end" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom end</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="right-start" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="right-end" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right end</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="left-start" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left start</sonic-button>
-      </sonic-tooltip>
-      <sonic-tooltip placement="left-end" label="My tooltip">
-        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left end</sonic-button>
-      </sonic-tooltip>
-    </div>
+    <sonic-tooltip label="Gate B12&#10;Boarding at 08:15">
+      <sonic-button variant="outline">Multiline label</sonic-button>
+    </sonic-tooltip>
   </template>
 </sonic-code>
 
-
 ## 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.
+
 <sonic-code>
   <template>
-    <sonic-tooltip focusable label="The Concorde made its first transatlantic crossing on September 26, 1973">
-      <sonic-icon library="iconoir" name="chat-bubble-question"></sonic-icon> Focus or hover non interactive element 
+    <sonic-tooltip
+      focusable
+      label="The Concorde made its first transatlantic crossing on September 26, 1973"
+    >
+      <sonic-icon library="iconoir" name="chat-bubble-question"></sonic-icon>
+      Focus or hover this text
     </sonic-tooltip>
   </template>
 </sonic-code>
 
 ## Disabled
 
+`disabled` never shows the bubble and sets `tabindex="-1"` on the host.
+
 <sonic-code>
   <template>
-    <sonic-tooltip disabled label="Disabled text">
+    <sonic-tooltip disabled label="Not shown">
       <sonic-button>Tooltip disabled</sonic-button>
     </sonic-tooltip>
   </template>
 </sonic-code>
 
+## 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 |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Trigger content |

package/docs/src/docs/decorators/ancestor-attribute.md

@@ -0,0 +1,59 @@
+# @ancestorAttribute
+
+Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as `dataProvider` without passing it down by hand, typically to feed a dynamic key of [@subscribe](/docs/decorators/subscribe).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+## Read once at connect
+
+By default the value is read once, just before the component's `connectedCallback`, and never updated. The closest element with the attribute wins. If no ancestor has it, the property keeps its initial value.
+
+<sonic-code>
+  <template>
+<div dataProvider="flights.CN001" gate="B12">
+  <docs-demo-sources for="demo-ancestor-attribute"></docs-demo-sources>
+  <demo-ancestor-attribute></demo-ancestor-attribute>
+</div>
+  </template>
+</sonic-code>
+
+An attribute present without a value (`<div gate>`) resolves to `""`. A camelCase name also matches its lowercase form (`dataProvider` and `dataprovider`).
+
+## Follow DOM changes
+
+With `{ dynamic: true }`, the property stays in sync while the component is connected: when an ancestor changes the attribute, when a closer ancestor gains or loses it, and when the component is moved. When no ancestor has the attribute, the property becomes `null`. Add `@state()` so Lit re-renders on each assignment.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider", { dynamic: true })
+@state()
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+Change the parent or outer value, insert a closer wrapper, or remove an attribute: the child always shows the nearest one.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-ancestor-attribute-dynamic-section"></docs-demo-sources>
+    <demo-ancestor-attribute-dynamic-section></demo-ancestor-attribute-dynamic-section>
+  </template>
+</sonic-code>
+
+Keys of [@subscribe](/docs/decorators/subscribe) and [@bind](/docs/decorators/bind) that use the property as a placeholder (`"${dataProvider}"`) are re-resolved on each change.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `attributeName` | `string` | Attribute to look up on the host, then on its ancestors |
+| `options.dynamic` | `boolean` (default `false`) | Keep the property in sync with attribute changes and reparenting until disconnect; assigns `null` when no ancestor has the attribute |

package/docs/src/docs/decorators/auto-subscribe.md

@@ -0,0 +1,40 @@
+# @autoSubscribe
+
+Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer [@subscribe](/docs/decorators/subscribe) with a [`DataProviderKey`](/docs/misc/dataProviderKey): dependencies are explicit and typed.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+import { get } from "@supersoniks/concorde/utils";
+
+@autoSubscribe()
+updateDisplay() {
+  this.total = get(passengersKey) + get(crewKey);
+}
+  </template>
+</sonic-code>
+
+## Tracked reads
+
+The method runs once after `connectedCallback`. Every store value read during that run becomes a dependency; assigning any of them runs the method again. Write the result to a `@state()` property (or call `requestUpdate()`) so the component re-renders.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-auto-subscribe"></docs-demo-sources>
+    <demo-auto-subscribe></demo-auto-subscribe>
+  </template>
+</sonic-code>
+
+## Notes
+
+- Several assignments in the same task trigger a single re-run (batched with `queueMicrotask`).
+- Keep reads unconditional: a value read only behind a condition becomes a dependency the first time that branch runs.
+- Subscriptions are removed in `disconnectedCallback`.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| none | | `@autoSubscribe()` takes no argument; apply it to a method of a custom element |