@supersoniks/concorde 4.9.5 → 4.9.7

package/src/core/components/functional/queue/queue.ts

@@ -74,6 +74,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     this.requestId = 0;
     this.isFirstRequest = true;
     this.nextHadEvent = false;
+    this.teardownScrollGuard();
     this.publisher.set({});
     super.disconnectedCallback();
     return;
@@ -105,7 +106,8 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
         HTML.getAncestorAttributeValue(this.parentElement, "dataProvider") ||
         "";
     }
-    this.storeScrollPosition();
+    this.captureScrollPosition();
+    this.ensureScrollGuard();
     super.connectedCallback();
     this.publisher.set({});
     this.key = this.getAttribute("key");
@@ -161,6 +163,9 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     const searchHash = searchParams.toString();
     if (searchHash == this.searchHash && !this.isFirstRequest) return;
     this.searchHash = searchHash;
+    // Nouvelle recherche : ne pas restaurer l'ancienne position de scroll
+    this.storedScrollX = 0;
+    this.storedScrollY = 0;
 
     /**
      * on reset les données avant de lancer la requète
@@ -187,35 +192,233 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     this.isFirstRequest = false;
   };
 
-  storeScrollPosition() {
+  /**
+   * Conteneur scrollé (élément ou window) — Safari / iOS only.
+   * Stock = dernière position user (touch/wheel/pointer + settle inertie).
+   * Restore = updated (enfants Lit) + MutationObserver (subscribers / modal).
+   */
+  scrollRoot: HTMLElement | Window | null = null;
+  storedScrollY = 0;
+  storedScrollX = 0;
+  private static readonly SCROLL_SETTLE_MS = 150;
+  private userScrollEngaged = false;
+  private restoringScroll = false;
+  private scrollGuardActive = false;
+  private scrollSettleTimer?: ReturnType<typeof setTimeout>;
+  private mutationObserver: MutationObserver | null = null;
+  private boundScrollTarget: EventTarget | null = null;
+  private restoreGeneration = 0;
+
+  resolveScrollRoot(): HTMLElement | Window {
+    const ancestor = HTML.getScrollingAncestor(this);
+    if (
+      !ancestor ||
+      ancestor === document.documentElement ||
+      ancestor === document.body
+    ) {
+      return window;
+    }
+    return ancestor as HTMLElement;
+  }
+
+  /** Lit la position courante — ne pas appeler sur un scroll “fantôme” Safari. */
+  captureScrollPosition() {
+    if (!this.isSafari()) {
+      return;
+    }
+    const root = this.resolveScrollRoot();
+    this.scrollRoot = root;
+    if (root === window) {
+      this.storedScrollX = window.scrollX;
+      this.storedScrollY = window.scrollY;
+    } else {
+      const el = root as HTMLElement;
+      this.storedScrollX = el.scrollLeft;
+      this.storedScrollY = el.scrollTop;
+    }
+  }
+
+  restoreScrollPosition() {
     if (!this.isSafari()) {
       return;
     }
-    this.storedScrollX = window.scrollX;
-    this.storedScrollY = window.scrollY;
+    const root = this.scrollRoot ?? this.resolveScrollRoot();
+    const x = this.storedScrollX;
+    const y = this.storedScrollY;
+    this.restoringScroll = true;
+    try {
+      if (root === window) {
+        if (
+          Math.abs(x - window.scrollX) > 10 ||
+          Math.abs(y - window.scrollY) > 10
+        ) {
+          window.scrollTo(x, y);
+        }
+      } else {
+        const el = root as HTMLElement;
+        if (
+          Math.abs(x - el.scrollLeft) > 10 ||
+          Math.abs(y - el.scrollTop) > 10
+        ) {
+          el.scrollLeft = x;
+          el.scrollTop = y;
+        }
+      }
+    } finally {
+      requestAnimationFrame(() => {
+        this.restoringScroll = false;
+      });
+    }
   }
 
   isSafari() {
     return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
   }
 
+  private markUserScrollEngaged = () => {
+    this.userScrollEngaged = true;
+  };
+
+  private armScrollSettle = () => {
+    clearTimeout(this.scrollSettleTimer);
+    this.scrollSettleTimer = setTimeout(() => {
+      this.userScrollEngaged = false;
+      this.scrollSettleTimer = undefined;
+    }, Queue.SCROLL_SETTLE_MS);
+  };
+
+  private onScrollRootScroll = () => {
+    if (!this.isSafari() || this.restoringScroll || !this.userScrollEngaged) {
+      return;
+    }
+    this.captureScrollPosition();
+    // iOS : l’inertie continue après touchend → prolonger l’engagement
+    this.armScrollSettle();
+  };
+
+  private onUserScrollIntent = () => {
+    if (!this.isSafari()) return;
+    this.markUserScrollEngaged();
+  };
+
+  private onUserScrollIntentEnd = () => {
+    if (!this.isSafari()) return;
+    this.armScrollSettle();
+  };
+
+  private onWheelIntent = () => {
+    if (!this.isSafari()) return;
+    this.markUserScrollEngaged();
+    this.armScrollSettle();
+  };
+
+  ensureScrollGuard() {
+    if (!this.isSafari() || !this.isConnected) {
+      return;
+    }
+    const root = this.resolveScrollRoot();
+    const target: EventTarget = root === window ? window : root;
+    if (this.scrollGuardActive && this.boundScrollTarget === target) {
+      this.scrollRoot = root;
+      return;
+    }
+    this.teardownScrollGuard();
+    this.scrollRoot = root;
+    this.boundScrollTarget = target;
+    this.scrollGuardActive = true;
+
+    target.addEventListener("scroll", this.onScrollRootScroll, {
+      passive: true,
+    });
+    // Intent user : touch (iOS), wheel, pointer (scrollbar desktop Safari)
+    target.addEventListener("touchstart", this.onUserScrollIntent, {
+      passive: true,
+    });
+    target.addEventListener("touchend", this.onUserScrollIntentEnd, {
+      passive: true,
+    });
+    target.addEventListener("touchcancel", this.onUserScrollIntentEnd, {
+      passive: true,
+    });
+    target.addEventListener("wheel", this.onWheelIntent, { passive: true });
+    target.addEventListener("pointerdown", this.onUserScrollIntent, {
+      passive: true,
+    });
+    target.addEventListener("pointerup", this.onUserScrollIntentEnd, {
+      passive: true,
+    });
+    target.addEventListener("pointercancel", this.onUserScrollIntentEnd, {
+      passive: true,
+    });
+
+    this.mutationObserver = new MutationObserver(() => {
+      this.scheduleRestoreAfterChildren();
+    });
+    this.mutationObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+  }
+
+  teardownScrollGuard() {
+    this.restoreGeneration++;
+    clearTimeout(this.scrollSettleTimer);
+    this.scrollSettleTimer = undefined;
+    this.userScrollEngaged = false;
+    this.restoringScroll = false;
+    if (this.boundScrollTarget) {
+      const target = this.boundScrollTarget;
+      target.removeEventListener("scroll", this.onScrollRootScroll);
+      target.removeEventListener("touchstart", this.onUserScrollIntent);
+      target.removeEventListener("touchend", this.onUserScrollIntentEnd);
+      target.removeEventListener("touchcancel", this.onUserScrollIntentEnd);
+      target.removeEventListener("wheel", this.onWheelIntent);
+      target.removeEventListener("pointerdown", this.onUserScrollIntent);
+      target.removeEventListener("pointerup", this.onUserScrollIntentEnd);
+      target.removeEventListener("pointercancel", this.onUserScrollIntentEnd);
+      this.boundScrollTarget = null;
+    }
+    this.mutationObserver?.disconnect();
+    this.mutationObserver = null;
+    this.scrollGuardActive = false;
+    this.scrollRoot = null;
+  }
+
+  /**
+   * Attend la fin des updates Lit de la queue + sonic-list, puis 2 rAF (layout Safari).
+   * Ne pas await updateComplete *dans* updated (deadlock) — on sort du cycle via void async.
+   */
+  scheduleRestoreAfterChildren() {
+    if (!this.isSafari() || !this.isConnected) {
+      return;
+    }
+    const generation = ++this.restoreGeneration;
+    void (async () => {
+      await this.updateComplete;
+      if (generation !== this.restoreGeneration || !this.isConnected) return;
+
+      const lists = Array.from(
+        this.querySelectorAll<LitElement>("sonic-list")
+      );
+      if (lists.length) {
+        await Promise.all(lists.map((list) => list.updateComplete));
+      }
+      if (generation !== this.restoreGeneration || !this.isConnected) return;
+
+      await new Promise<void>((r) => requestAnimationFrame(() => r()));
+      await new Promise<void>((r) => requestAnimationFrame(() => r()));
+      if (generation !== this.restoreGeneration || !this.isConnected) return;
+
+      this.restoreScrollPosition();
+    })();
+  }
+
   protected updated(_changedProperties: PropertyValues): void {
     if (this.isSafari()) {
-      if (
-        Math.abs(this.storedScrollX - window.scrollX) > 10 ||
-        Math.abs(this.storedScrollY - window.scrollY) > 10
-      ) {
-        window.scrollTo(this.storedScrollX, this.storedScrollY);
-      }
-      //Hack pour éviter que le scroll ne retourne en haut si safari
-      window.requestAnimationFrame(() => {
-        if (
-          Math.abs(this.storedScrollX - window.scrollX) > 10 ||
-          Math.abs(this.storedScrollY - window.scrollY) > 10
-        ) {
-          window.scrollTo(this.storedScrollX, this.storedScrollY);
-        }
-      });
+      this.ensureScrollGuard();
+      this.restoreScrollPosition();
+      this.scheduleRestoreAfterChildren();
     }
 
     super.updated(_changedProperties);
@@ -326,11 +529,12 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     this.lastRequestTime = new Date().getTime();
   }
 
-  storedScrollY = 0;
-  storedScrollX = 0;
-
   render() {
-    this.storeScrollPosition();
+    // Ne pas écraser le stock avec un jump Safari : uniquement sync du root / guard.
+    if (this.isSafari()) {
+      this.scrollRoot = this.resolveScrollRoot();
+      this.ensureScrollGuard();
+    }
     if (!Array.isArray(this.props)) {
       return nothing;
     }

package/src/core/utils/HTML.ts

@@ -24,6 +24,20 @@ class HTML {
       }, {});
   }
 
+  /**
+   * Ancêtre suivant dans l'arbre composé : slot de projection, sinon parentNode / shadow host.
+   * Nécessaire pour trouver un scroller/clipper dans le shadow d'un ancêtre (ex. #modal.custom-scroll).
+   */
+  static nextComposedAncestor(
+    node: SearchableDomElement,
+  ): SearchableDomElement | null {
+    if (node instanceof Element && node.assignedSlot) {
+      return node.assignedSlot;
+    }
+    const parent = node.parentNode || (node as ShadowRoot).host;
+    return (parent as SearchableDomElement) || null;
+  }
+
   static everyAncestors(
     node: SearchableDomElement,
     callback: (node: SearchableDomElement) => /*continue ?*/ boolean
@@ -36,29 +50,50 @@ class HTML {
     }
   }
 
-  static getScrollableAncestor(node: SearchableDomElement) {
-    //Based on overflow-y: auto, overflow-y: scroll, overflow-y: hidden
-    while (node) {
-      const htmlNode = node as HTMLElement;
-      if (htmlNode.nodeType === 1) {
-        const style = window.getComputedStyle(htmlNode);
-        if (
-          style?.overflowY === "auto" ||
-          style?.overflowY === "scroll" ||
-          style?.overflowY === "hidden" ||
-          style?.overflowX === "auto" ||
-          style?.overflowX === "scroll" ||
-          style?.overflowX === "hidden"
-        ) {
-          return node;
+  private static overflowMatches(
+    style: CSSStyleDeclaration,
+    values: readonly string[],
+  ): boolean {
+    return values.includes(style.overflowY) || values.includes(style.overflowX);
+  }
+
+  private static findAncestorByOverflow(
+    node: SearchableDomElement,
+    overflowValues: readonly string[],
+  ): SearchableDomElement | null {
+    let current: SearchableDomElement | null = node;
+    while (current) {
+      if (current instanceof Element && current.nodeType === 1) {
+        const style = window.getComputedStyle(current);
+        if (HTML.overflowMatches(style, overflowValues)) {
+          return current;
         }
       }
-      node = (node.parentNode ||
-        (node as ShadowRoot).host) as SearchableDomElement;
+      current = HTML.nextComposedAncestor(current);
     }
     return null;
   }
 
+  /**
+   * Ancêtre qui clippe (inclut overflow:hidden) — ex. clamp de sonic-pop.
+   * Reconnaît aussi overflow:overlay (.custom-scroll) et traverse les slots.
+   */
+  static getScrollableAncestor(node: SearchableDomElement) {
+    return HTML.findAncestorByOverflow(node, [
+      "auto",
+      "scroll",
+      "hidden",
+      "overlay",
+    ]);
+  }
+
+  /**
+   * Ancêtre réellement scrollable (pas overflow:hidden) — ex. restore scroll Safari de sonic-queue.
+   */
+  static getScrollingAncestor(node: SearchableDomElement) {
+    return HTML.findAncestorByOverflow(node, ["auto", "scroll", "overlay"]);
+  }
+
   /** Noms d'attribut DOM à tester (Lit reflect → minuscules, ex. serviceURL → serviceurl). */
   static scopeAttributeNames(attributeName: string): string[] {
     const lower = attributeName.toLowerCase();

package/src/docs/search/docs-search.json

@@ -350,14 +350,19 @@
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load--offset-and-limit": {
+          "lazy-load": {
             "count": 1,
-            "title": "Lazy load — `$offset` and `$limit`",
+            "title": "Lazy load",
             "type": "paragraph"
           },
-          "simple-batch-no-lazy-scroll": {
+          "manual-next-signal--supplement": {
             "count": 1,
-            "title": "Simple batch (no lazy scroll)",
+            "title": "Manual next (signal) — supplement",
+            "type": "paragraph"
+          },
+          "simple-batch-no-pagination": {
+            "count": 1,
+            "title": "Simple batch (no pagination)",
             "type": "paragraph"
           }
         }
@@ -820,14 +825,14 @@
     }
   },
   {
-    "search": "When the expression contains $offset and $limit, the queue:\n",
+    "search": "In Lit apps, use defineQueue + .config on <sonic-queue> — typed Endpoint, DataProviderKey, enums. See src/docs/example/docs-queue-demos.ts.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load--offset-and-limit": {
+          "queue": {
             "count": 1,
-            "title": "Lazy load — `$offset` and `$limit`",
+            "title": "",
             "type": "paragraph"
           }
         }
@@ -835,14 +840,29 @@
     }
   },
   {
-    "search": "The doc mock implements this on GET /docs-mock-api/api/users?offset=…&per_page=… (paginateUsers in src/docs/mock-api/router.ts).\n",
+    "search": "Required: endpoint + items. Add rowsAt when rows live in a nested property. Everything else has sensible defaults (strategy: Lazy, pageSize: 10, offset/limit query names).\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load--offset-and-limit": {
+          "queue": {
             "count": 1,
-            "title": "Lazy load — `$offset` and `$limit`",
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Layout (class, id, …) stays on <sonic-queue> — not inside .config.\n",
+    "files": {
+      "core/components/functional/queue/queue.md": {
+        "title": "Queue",
+        "hashes": {
+          "queue": {
+            "count": 1,
+            "title": "",
             "type": "paragraph"
           }
         }
@@ -850,14 +870,14 @@
     }
   },
   {
-    "search": "Wrap the queue in a fixed height with overflow-y-auto so lazy load triggers when scrolling inside the box (same layout as the TS starter demo-queue-templates).\n",
+    "search": "When pagination is enabled (default QueueLoadStrategy.Lazy), the queue:\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load--offset-and-limit": {
+          "lazy-load": {
             "count": 1,
-            "title": "Lazy load — `$offset` and `$limit`",
+            "title": "Lazy load",
             "type": "paragraph"
           }
         }
@@ -865,14 +885,14 @@
     }
   },
   {
-    "search": "Try scrolling after load — batches of 4 users. Search e.g. George, Bluth, or zzz for empty results.\n",
+    "search": "Mock: GET /docs-mock-api/api/users?offset=…&limit=… (paginateUsers in src/docs/mock-api/router.ts).\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load--offset-and-limit": {
+          "lazy-load": {
             "count": 1,
-            "title": "Lazy load — `$offset` and `$limit`",
+            "title": "Lazy load",
             "type": "paragraph"
           }
         }
@@ -880,14 +900,14 @@
     }
   },
   {
-    "search": "Without $offset in the expression, the queue behaves like a single list (one batch), e.g. geo communes below.\n",
+    "search": "Wrap the queue in a fixed height with overflow-y-auto so lazy load triggers when scrolling inside the box.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "expression-example": {
+          "lazy-load": {
             "count": 1,
-            "title": "Expression example",
+            "title": "Lazy load",
             "type": "paragraph"
           }
         }
@@ -895,7 +915,22 @@
     }
   },
   {
-    "search": "One search field (name="q") on formDataProvider="filter". The queue listens via dataFilterProvider="filter" and, on change:\n",
+    "search": "Without pagination offset ( $offset not generated), the queue behaves as a single batch — see geo communes below.\n",
+    "files": {
+      "core/components/functional/queue/queue.md": {
+        "title": "Queue",
+        "hashes": {
+          "lazy-load": {
+            "count": 1,
+            "title": "Lazy load",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Pass a filter DataProviderKey in defineQueue (same publisher as formDataProvider on the search form). On change, the queue:\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
@@ -910,7 +945,7 @@
     }
   },
   {
-    "search": "Use filteredFields only when the form has extra fields that must not be sent to the API (e.g. filteredFields="rememberMe internalId").\n",
+    "search": "Use filteredFields in the config only when the form has fields that must not be sent to the API.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
@@ -925,7 +960,7 @@
     }
   },
   {
-    "search": "The mock API filters before pagination — same haystack logic as the starter (filterDocsUsers in src/docs/mock-api/fixtures.ts, used by paginateUsers in router.ts / Service Worker):\n",
+    "search": "The users demo above wires docsQueueUsersFilterKey + sonic-input name="q". Mock filter: filterDocsUsers in src/docs/mock-api/fixtures.ts.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
@@ -940,14 +975,14 @@
     }
   },
   {
-    "search": "Geo communes: expression uses $limit only (no $offset) — one request, one batch.\n",
+    "search": "Default lazy scroll loads the next batch automatically. For a button that triggers the next batch via publishers — without touching the queue instance — use QueueLoadStrategy.Signal and a void next key (invalidate(), same idea as triggerKey on @get).\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "simple-batch-no-lazy-scroll": {
+          "manual-next-signal--supplement": {
             "count": 1,
-            "title": "Simple batch (no lazy scroll)",
+            "title": "Manual next (signal) — supplement",
             "type": "paragraph"
           }
         }
@@ -955,14 +990,44 @@
     }
   },
   {
-    "search": "Optional for hosts without Lit — see HTML integration.\n",
+    "search": "state exposes QueuePublisherState on the queue dataProvider: meta (e.g. total), loadedCount, hasMore. Wire sonic-button invalidate to the same next key.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "html-template-children": {
+          "manual-next-signal--supplement": {
             "count": 1,
-            "title": "HTML `<template>` children",
+            "title": "Manual next (signal) — supplement",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Elsewhere: dp(usersNextKey).invalidate().\n",
+    "files": {
+      "core/components/functional/queue/queue.md": {
+        "title": "Queue",
+        "hashes": {
+          "manual-next-signal--supplement": {
+            "count": 1,
+            "title": "Manual next (signal) — supplement",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Geo communes: one request, one batch ($limit only).\n",
+    "files": {
+      "core/components/functional/queue/queue.md": {
+        "title": "Queue",
+        "hashes": {
+          "simple-batch-no-pagination": {
+            "count": 1,
+            "title": "Simple batch (no pagination)",
             "type": "paragraph"
           }
         }
@@ -2269,6 +2334,21 @@
       }
     }
   },
+  {
+    "search": "Emit a publisher signal on click (same idea as triggerKey on @get, or dataNextProvider on sonic-queue). Value is the publisher path.\n",
+    "files": {
+      "core/components/ui/button/button.md": {
+        "title": "Button",
+        "hashes": {
+          "invalidate": {
+            "count": 1,
+            "title": "Invalidate",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Captcha",
     "files": {
@@ -6934,6 +7014,21 @@
       }
     }
   },
+  {
+    "search": "Everything after &lt;!-- concorde-ai --&gt; is replaced on each ai-init run (idempotent). Do not paste a full copy of the Concorde guide above the marker — put project-specific notes in AGENTS.concorde.md (overlay). If the preamble duplicates package AGENTS.md, ai-init slims or drops it and prints a warning. Legacy filenames AGENTS.overlay.md / AGENTS.starter.md are still accepted with a deprecation warning.\n",
+    "files": {
+      "docs/_getting-started/ai-agents.md": {
+        "title": "AI agents (skills & AGENTS.md)",
+        "hashes": {
+          "agentsmd-policy-non-invasive": {
+            "count": 1,
+            "title": "`AGENTS.md` policy (non-invasive)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Source files in the npm package: node_modules/@supersoniks/concorde/ai/ (see also ai/README.md in the Concorde repository).\n",
     "files": {