@supersoniks/concorde 5.0.3 → 5.0.5

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

@@ -1,166 +1,216 @@
 # Toast
 
-## Utilisation de base
+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="window.SonicToast.add({ text: 'Message de notification simple' })">
-      Afficher un toast
+    <sonic-button onclick="SonicToast.add({ text: 'Simple notification' })">
+      Show toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## Statut
+## Status
 
-Les statuts disponibles sont : `success`, `error`, `warning`, `info` ou vide (par défaut).
+**`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="window.SonicToast.add({ text: 'Message par défaut', status: '' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Default message', status: '' })">
         Default
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Opération réussie !', status: 'success' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">
         Success
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Une erreur est survenue', status: 'error' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">
         Error
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Attention à ce point', status: 'warning' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">
         Warning
       </sonic-button>
-      <sonic-button onclick="window.SonicToast.add({ text: 'Information importante', status: 'info' })">
+      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">
         Info
       </sonic-button>
     </div>
   </template>
 </sonic-code>
 
-## Avec titre
+## Label
+
+Set **`label`** for a bold title above **`text`**. **`title`** still works but is deprecated—use **`label`** in new code.
 
 <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
+        onclick="SonicToast.add({ label: 'Success', text: 'Your request was processed.', status: 'success' })"
+      >
+        Toast with label
       </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
+        onclick="SonicToast.add({ label: 'Error', text: 'Processing failed. Try again.', status: 'error' })"
+      >
+        Error with label
       </sonic-button>
     </div>
   </template>
 </sonic-code>
 
-## Avec contenu HTML
+## HTML in text
 
-Le contenu du toast peut contenir du HTML.
+**`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>
-    <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({ 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>
 
+## Preserve
 
-## Persistance
-
-Par défaut, les toasts disparaissent automatiquement. Avec `preserve: true`, le toast reste affiché jusqu'à ce qu'il soit fermé manuellement.
+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="window.SonicToast.add({ text: 'Ce toast ne disparaîtra pas automatiquement', status: 'info', preserve: true })">
-      Toast persistant
+    <sonic-button
+      onclick="SonicToast.add({ text: 'This toast stays until you dismiss it', status: 'info', preserve: true })"
+    >
+      Persistent toast
     </sonic-button>
   </template>
 </sonic-code>
 
-## Masquer définitivement
+## Dismiss forever
 
-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.
+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="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({ id: 'unique-toast-id', text: 'Dismiss forever hides this across reloads', status: 'info', dismissForever: true })"
+    >
+      Dismiss forever
     </sonic-button>
   </template>
 </sonic-code>
 
-## Fantôme
+## Ghost
 
-Avec `ghost: true`, le toast devient semi-transparent et non-interactif.
+**`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="window.SonicToast.add({ text: 'Toast fantôme (semi-transparent)', status: 'info', ghost: true })">
-      Toast ghost
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Ghost toast (non-interactive)', status: 'info', ghost: true })"
+    >
+      Ghost toast
     </sonic-button>
   </template>
 </sonic-code>
 
+## Dismissal
 
-## Méthodes de suppression
+Use static helpers to clear the stack from app logic (for example after navigation).
 
-### Tout supprimer
+### Remove all
 
-Supprime tous les toasts sauf ceux marqués comme `ghost`.
+Removes every toast except **`ghost`** items.
 
 <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>
+      <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>
   </template>
 </sonic-code>
 
-### Supprimer par statut
-
-Supprime tous les toasts d'un statut spécifique.
+### Remove by status
 
 <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: '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>
 
-### Supprimer les éléments temporaires
+### Remove temporary items
 
-Supprime tous les toasts qui ne sont pas marqués comme `preserve`.
+Removes toasts that are not **`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>
+      <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>
 
-## Exemple complet
+## Combined options
 
 <sonic-code>
   <template>
-    <sonic-button onclick="window.SonicToast.add({ 
+    <sonic-button
+      onclick="SonicToast.add({
       id: 'welcome-toast',
-      title: 'Bienvenue',
-      text: 'Bienvenue sur notre plateforme ! Vous pouvez commencer à explorer les fonctionnalités.',
+      label: 'Welcome',
+      text: 'Welcome to the platform. Explore the docs to get started.',
       status: 'success',
       dismissForever: true
-    })">
-      Toast complet
+    })"
+    >
+      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 passed to **`SonicToast.add(conf)`**:
+
+| Option | Values | Description |
+|----------|---------|-------------|
+| `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(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`** 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,71 +1,97 @@
 # Tooltip
 
+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="Tada : Text appears">hover me</sonic-tooltip>
+    <sonic-tooltip label="Additional context on hover">
+      <sonic-button variant="outline">Hover me</sonic-button>
+    </sonic-tooltip>
   </template>
 </sonic-code>
 
 ## Placement
 
-By default, tooltip is centered next to its content
+Use **`top`** · **`bottom`** · **`left`** · **`right`** for the main axis. Add **`-start`** or **`-end`** to align the bubble along the anchor edge.
 
 <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-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>
 
-## More placement
+### Aligned placements
+
 <sonic-code>
   <template>
     <div class="flex gap-3 flex-wrap">
-      <sonic-tooltip placement="top-start" label="My tooltip">
+      <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="My 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="My 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="My 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="My 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="My 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="My 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="My 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="First line&#10;Second line">
+      <sonic-button variant="outline">Multiline label</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
 
 ## Focusable
 
+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>
-    <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>
@@ -74,9 +100,25 @@ By default, tooltip is centered next to its content
 
 <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>
 
+## 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 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 (hover target) |

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

@@ -69,8 +69,9 @@ This decorator is particularly useful for:
 - By default (`dynamic: false`), the value is read once at connect time and is not updated afterward
 - With `{ dynamic: true }`, the property stays in sync when:
   - an ancestor **changes** the attribute value
-  - a **closer** ancestor **gains** the attribute (that value wins)
-  - the **nearest** ancestor **loses** the attribute (falls back to the next one up, or `null`)
+  - a **closer** ancestor **gains** / **loses** the attribute (fallback / `null`)
+  - the component is **reparented** (no extra opt-in) — parent `childList` only reacts if *this* node moves
+- Observers are **shared** (one per ancestor attribute / one per parent) so large lists of `sonic-icon` stay cheap on Firefox.
 - When `dynamic` is enabled, updates also propagate to `@subscribe` / `@bind` paths that depend on the decorated property (e.g. `${dataProvider}`)
 
 ### Dynamic mode

package/docs/src/docs/_getting-started/start.md

@@ -3,7 +3,7 @@
 ## What is Concorde?
 
 Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of web components for shared apps and websites.  
-Build UIs without tying components to a specific host stack, while keeping visual consistency through a small set of CSS variables.
+Build UIs without tying components to a specific host stack, while keeping visual consistency through the smallest set of CSS variables needed to define a theme.
 
 ## Why and use case