@supersoniks/concorde 5.0.3 → 5.0.5

package/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/src/core/decorators/subscriber/ancestorAttribute.spec.ts

@@ -236,4 +236,30 @@ describe("ancestorAttribute", () => {
 
     expect(el.dataProvider).toBe("scope-a");
   });
+
+  it("suit un wrapper plus proche après reparent (sans opt-in)", async () => {
+    const tag = "test-ancestor-attr-dynamic-reparent";
+    class C extends HTMLElement {
+      @ancestorAttribute("dataProvider", { dynamic: true })
+      dataProvider: string | null = null;
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const outer = document.createElement("div");
+    outer.setAttribute("dataProvider", "from-outer");
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    outer.appendChild(el);
+    document.body.appendChild(outer);
+    expect(el.dataProvider).toBe("from-outer");
+
+    const closer = document.createElement("div");
+    closer.setAttribute("dataProvider", "from-closer");
+    closer.appendChild(el);
+    outer.appendChild(closer);
+    await flushFrames();
+
+    expect(el.dataProvider).toBe("from-closer");
+  });
 });

package/src/core/decorators/subscriber/ancestorAttribute.ts

@@ -5,10 +5,9 @@ import { ConnectedComponent, setSubscribable } from "./common";
 
 export type AncestorAttributeOptions = {
   /**
-   * Si true, le composant reste synchronisé avec les attributs ancêtres via
-   * `AncestorAttributeObserver` (mutations + reparenting). Requis pour que
-   * `@bind` / `@subscribe` avec `${dataProvider}` se re-lient quand le scope change.
-   * Défaut : false (lecture unique au connect, rétrocompat).
+   * Si true, reste synchronisé quand un attribut ancêtre change **et** au
+   * reparenting (sans flag séparé). MO attributs partagés ; childList seulement
+   * sur le parent direct (ignoré pour les siblings). Défaut : false.
    */
   dynamic?: boolean;
 };

package/src/core/utils/AncestorAttributeObserver.ts

@@ -3,13 +3,14 @@ import HTML, { SearchableDomElement } from "./HTML";
 /**
  * Observateur pour `@ancestorAttribute({ dynamic: true })`.
  *
- * Un MutationObserver sur `document` ne voit pas les mutations dans les shadow
- * roots (Lit par défaut). Chaque abonnement observe donc directement les nœuds
- * de sa chaîne d'ancêtres (composant → parent → … → host shadow), comme
- * `watchScopedConfiguration` dans `api.ts`.
+ * ## Perf (FF / listes denses d'icônes)
+ * Ancien modèle : 1 MO/abonnement avec `childList` sur **toute** la chaîne +
+ * `reconnect()` à chaque mutation → O(n²) quand une list insert des siblings.
  *
- * Après un `childList` (wrapper plus proche, reparenting), la chaîne est
- * recalculée pour écouter les nouveaux ancêtres.
+ * Modèle actuel :
+ * 1. **MO attributs partagés** — 1 observer par `(ancêtre, attributeName)`.
+ * 2. **Reparent** — 1 MO `childList` partagé sur le parent direct ; on ne
+ *    réagit que si *notre* nœud est dans added/removed (insert sibling → no-op).
  */
 
 type SyncOptions = {
@@ -22,7 +23,18 @@ type Subscription = {
   attributeName: string;
   propertyKey: string;
   syncOptions: SyncOptions;
-  disconnectObservers: (() => void) | null;
+  watchedAncestors: Element[];
+  parentForReparent: Element | null;
+};
+
+type AttrSlot = {
+  observer: MutationObserver;
+  subscriptions: Set<Subscription>;
+};
+
+type ParentSlot = {
+  observer: MutationObserver;
+  byComponent: Map<Element, Set<Subscription>>;
 };
 
 /** Chaîne composant → ancêtres, en traversant les shadow roots. */
@@ -40,58 +52,17 @@ function walkAncestorElements(node: Node): Element[] {
   return elements;
 }
 
-/**
- * Observe attributs + enfants directs de chaque ancêtre.
- * Retourne une fonction de nettoyage (disconnect).
- */
-function attachAncestorChainObservers(
-  subscription: Subscription,
-  onMutation: () => void,
-): () => void {
-  const observers: MutationObserver[] = [];
-  let disconnected = false;
-  const attributeFilter = HTML.scopeAttributeNames(subscription.attributeName);
-
-  const reconnect = () => {
-    for (const observer of observers) {
-      observer.disconnect();
-    }
-    observers.length = 0;
-    if (disconnected) return;
-
-    for (const element of walkAncestorElements(subscription.component)) {
-      const observer = new MutationObserver((records) => {
-        if (disconnected) return;
-        if (records.some((record) => record.type === "childList")) {
-          reconnect();
-        }
-        onMutation();
-      });
-      observer.observe(element, {
-        attributes: true,
-        attributeFilter,
-        childList: true,
-        subtree: false,
-      });
-      observers.push(observer);
-    }
-  };
-
-  reconnect();
-
-  return () => {
-    disconnected = true;
-    for (const observer of observers) {
-      observer.disconnect();
-    }
-    observers.length = 0;
-  };
+function directParentElement(component: HTMLElement): Element | null {
+  const parent =
+    component.parentNode ||
+    ((component.getRootNode() as ShadowRoot)?.host ?? null);
+  return parent instanceof Element ? parent : null;
 }
 
 /**
  * Point unique de synchronisation DOM → propriété du composant.
  * N'assigne que si la valeur change (`Object.is`) pour limiter les re-renders Lit
- * et éviter de reboucler inutilement `observeDynamicProperty` (@bind / @subscribe).
+ * et éviter de reboucler inutilement `observeDynamicProperty` (@bind / `@subscribe`).
  */
 export function syncAncestorAttributeValue(
   component: object,
@@ -115,8 +86,11 @@ export default class AncestorAttributeObserver {
   private static pendingRefresh = new Set<Subscription>();
   private static animationFrameId: number | null = null;
 
+  private static attrSlots = new WeakMap<Element, Map<string, AttrSlot>>();
+  private static parentSlots = new WeakMap<Element, ParentSlot>();
+
   /**
-   * Enregistre un composant en mode `{ dynamic: true }`.
+   * Enregistre un composant en mode `{ dynamic: true }` (attributs + reparent).
    * Le `unsubscribe` retourné doit être appelé au `disconnectedCallback`.
    */
   static subscribe(
@@ -130,32 +104,172 @@ export default class AncestorAttributeObserver {
       attributeName,
       propertyKey,
       syncOptions,
-      disconnectObservers: null,
+      watchedAncestors: [],
+      parentForReparent: null,
     };
 
-    subscription.disconnectObservers = attachAncestorChainObservers(
-      subscription,
-      () => {
-        if (!AncestorAttributeObserver.subscriptions.has(subscription)) return;
-        AncestorAttributeObserver.pendingRefresh.add(subscription);
-        AncestorAttributeObserver.scheduleRefresh();
-      },
-    );
-
     AncestorAttributeObserver.subscriptions.add(subscription);
+    AncestorAttributeObserver.bindSubscription(subscription);
 
     return () => {
       AncestorAttributeObserver.unsubscribe(subscription);
     };
   }
 
-  /** Coupe les observateurs et retire l'abonnement (pas de fuite après disconnect). */
+  private static bindSubscription(subscription: Subscription): void {
+    AncestorAttributeObserver.unbindWatchers(subscription);
+
+    const ancestors = walkAncestorElements(subscription.component);
+    subscription.watchedAncestors = ancestors;
+
+    for (const ancestor of ancestors) {
+      AncestorAttributeObserver.addAttrSlot(
+        ancestor,
+        subscription.attributeName,
+        subscription,
+      );
+    }
+
+    const parent = directParentElement(subscription.component);
+    subscription.parentForReparent = parent;
+    if (parent) {
+      AncestorAttributeObserver.addParentSlot(parent, subscription);
+    }
+
+    AncestorAttributeObserver.pendingRefresh.add(subscription);
+    AncestorAttributeObserver.scheduleRefresh();
+  }
+
+  private static unbindWatchers(subscription: Subscription): void {
+    for (const ancestor of subscription.watchedAncestors) {
+      AncestorAttributeObserver.removeAttrSlot(
+        ancestor,
+        subscription.attributeName,
+        subscription,
+      );
+    }
+    subscription.watchedAncestors = [];
+
+    if (subscription.parentForReparent) {
+      AncestorAttributeObserver.removeParentSlot(
+        subscription.parentForReparent,
+        subscription,
+      );
+      subscription.parentForReparent = null;
+    }
+  }
+
+  private static addAttrSlot(
+    element: Element,
+    attributeName: string,
+    subscription: Subscription,
+  ): void {
+    let byAttr = AncestorAttributeObserver.attrSlots.get(element);
+    if (!byAttr) {
+      byAttr = new Map();
+      AncestorAttributeObserver.attrSlots.set(element, byAttr);
+    }
+
+    let slot = byAttr.get(attributeName);
+    if (!slot) {
+      const attributeFilter = HTML.scopeAttributeNames(attributeName);
+      const subscriptions = new Set<Subscription>();
+      const observer = new MutationObserver(() => {
+        for (const sub of subscriptions) {
+          if (!AncestorAttributeObserver.subscriptions.has(sub)) continue;
+          AncestorAttributeObserver.pendingRefresh.add(sub);
+        }
+        AncestorAttributeObserver.scheduleRefresh();
+      });
+      observer.observe(element, {
+        attributes: true,
+        attributeFilter,
+      });
+      slot = { observer, subscriptions };
+      byAttr.set(attributeName, slot);
+    }
+
+    slot.subscriptions.add(subscription);
+  }
+
+  private static removeAttrSlot(
+    element: Element,
+    attributeName: string,
+    subscription: Subscription,
+  ): void {
+    const byAttr = AncestorAttributeObserver.attrSlots.get(element);
+    if (!byAttr) return;
+    const slot = byAttr.get(attributeName);
+    if (!slot) return;
+
+    slot.subscriptions.delete(subscription);
+    if (slot.subscriptions.size > 0) return;
+
+    slot.observer.disconnect();
+    byAttr.delete(attributeName);
+  }
+
+  private static addParentSlot(
+    parent: Element,
+    subscription: Subscription,
+  ): void {
+    let slot = AncestorAttributeObserver.parentSlots.get(parent);
+    if (!slot) {
+      const byComponent = new Map<Element, Set<Subscription>>();
+      const observer = new MutationObserver((records) => {
+        const touched = new Set<Element>();
+        for (const record of records) {
+          record.removedNodes.forEach((n) => {
+            if (n instanceof Element) touched.add(n);
+          });
+          record.addedNodes.forEach((n) => {
+            if (n instanceof Element) touched.add(n);
+          });
+        }
+        for (const el of touched) {
+          const subs = byComponent.get(el);
+          if (!subs) continue;
+          for (const sub of [...subs]) {
+            if (!AncestorAttributeObserver.subscriptions.has(sub)) continue;
+            AncestorAttributeObserver.bindSubscription(sub);
+          }
+        }
+      });
+      observer.observe(parent, { childList: true });
+      slot = { observer, byComponent };
+      AncestorAttributeObserver.parentSlots.set(parent, slot);
+    }
+
+    let set = slot.byComponent.get(subscription.component);
+    if (!set) {
+      set = new Set();
+      slot.byComponent.set(subscription.component, set);
+    }
+    set.add(subscription);
+  }
+
+  private static removeParentSlot(
+    parent: Element,
+    subscription: Subscription,
+  ): void {
+    const slot = AncestorAttributeObserver.parentSlots.get(parent);
+    if (!slot) return;
+
+    const set = slot.byComponent.get(subscription.component);
+    if (set) {
+      set.delete(subscription);
+      if (set.size === 0) slot.byComponent.delete(subscription.component);
+    }
+
+    if (slot.byComponent.size > 0) return;
+    slot.observer.disconnect();
+    AncestorAttributeObserver.parentSlots.delete(parent);
+  }
+
   private static unsubscribe(subscription: Subscription): void {
     if (!AncestorAttributeObserver.subscriptions.has(subscription)) return;
 
-    subscription.disconnectObservers?.();
-    subscription.disconnectObservers = null;
-
+    AncestorAttributeObserver.unbindWatchers(subscription);
     AncestorAttributeObserver.subscriptions.delete(subscription);
     AncestorAttributeObserver.pendingRefresh.delete(subscription);
 
@@ -187,7 +301,6 @@ export default class AncestorAttributeObserver {
 
     for (const subscription of subscriptions) {
       if (!AncestorAttributeObserver.subscriptions.has(subscription)) continue;
-      if (!subscription.component.isConnected) continue;
       syncAncestorAttributeValue(
         subscription.component,
         subscription.attributeName,

package/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/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