@supersoniks/concorde 4.9.6 → 4.9.9

package/src/core/utils/SafariScrollGuard.ts

@@ -0,0 +1,429 @@
+/**
+ * Garde Safari / WebKit : empêche les resets fantômes de scroll.
+ *
+ * - stock = dernière position user (intent + settle inertie)
+ * - jump brutal vers ~0 → JAMAIS capturé (même mid-gesture), restore
+ * - collapse Lit / slot light-DOM : observe aussi le host + sticky restore multi-frames
+ * - nested : intent uniquement sur le scroller le plus proche (composedPath)
+ */
+
+export type ScrollRoot = HTMLElement | Window;
+
+const SCROLL_SETTLE_MS = 150;
+const RESTORE_EPS = 10;
+/** Jump vers le haut considéré fantôme (pas une remontée progressive trackpad). */
+const JUMP_EPS = 200;
+/** Combien de frames on re-applique le stock après un fantôme / mutation. */
+const STICKY_RESTORE_FRAMES = 16;
+
+type RootState = {
+  x: number;
+  y: number;
+  restoring: boolean;
+  watching: boolean;
+  userEngaged: boolean;
+  settleTimer?: ReturnType<typeof setTimeout>;
+  raf: number;
+  stickyFrames: number;
+  resizeObserver?: ResizeObserver;
+  mutationObserver?: MutationObserver;
+};
+
+const states = new WeakMap<object, RootState>();
+let installed = false;
+
+export function isSafariScrollEngine(): boolean {
+  if (typeof navigator === "undefined") return false;
+  return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+}
+
+function read(root: ScrollRoot): { x: number; y: number } {
+  if (root === window) {
+    return { x: window.scrollX, y: window.scrollY };
+  }
+  const el = root as HTMLElement;
+  return { x: el.scrollLeft, y: el.scrollTop };
+}
+
+function write(root: ScrollRoot, x: number, y: number): void {
+  if (root === window) {
+    window.scrollTo(x, y);
+    return;
+  }
+  const el = root as HTMLElement;
+  // scrollTo coupe mieux l’inertie iOS que le setter seul
+  if (typeof el.scrollTo === "function") {
+    el.scrollTo(x, y);
+  } else {
+    el.scrollLeft = x;
+    el.scrollTop = y;
+  }
+}
+
+function maxScrollY(root: ScrollRoot): number {
+  if (root === window) {
+    const doc = document.documentElement;
+    return Math.max(0, doc.scrollHeight - window.innerHeight);
+  }
+  const el = root as HTMLElement;
+  return Math.max(0, el.scrollHeight - el.clientHeight);
+}
+
+function getState(root: ScrollRoot): RootState {
+  let s = states.get(root);
+  if (!s) {
+    const pos = read(root);
+    s = {
+      x: pos.x,
+      y: pos.y,
+      restoring: false,
+      watching: false,
+      userEngaged: false,
+      raf: 0,
+      stickyFrames: 0,
+    };
+    states.set(root, s);
+  }
+  return s;
+}
+
+function markUserEngaged(root: ScrollRoot): void {
+  getState(root).userEngaged = true;
+}
+
+function armScrollSettle(root: ScrollRoot): void {
+  const s = getState(root);
+  clearTimeout(s.settleTimer);
+  s.settleTimer = setTimeout(() => {
+    s.userEngaged = false;
+    s.settleTimer = undefined;
+  }, SCROLL_SETTLE_MS);
+}
+
+/**
+ * Saut brutal vers le haut (pas seulement ~0) : Safari clampe souvent à une
+ * valeur intermédiaire (ex. 1716→225). Un `cap` sans `rst` = on avait accepté
+ * ce drop comme scroll user.
+ */
+function looksLikePhantomDrop(currentY: number, storedY: number): boolean {
+  return storedY - currentY >= JUMP_EPS;
+}
+
+/**
+ * Mémorise la position courante — refuse tout gros drop d’un coup.
+ */
+export function captureScrollRoot(root: ScrollRoot): void {
+  if (!isSafariScrollEngine()) return;
+  const s = getState(root);
+  if (s.restoring) return;
+  const pos = read(root);
+  if (looksLikePhantomDrop(pos.y, s.y)) {
+    stickyRestore(root);
+    return;
+  }
+  s.x = pos.x;
+  s.y = pos.y;
+}
+
+/**
+ * Ré-applique le stock. Ne pollue jamais le stock avec le scroll courant.
+ *
+ * Important : on peut clamper la *cible d’écriture* à maxScroll (le navigateur
+ * le ferait de toute façon), mais on ne doit JAMAIS abaisser `s.y` pour autant —
+ * pendant un re-render Lit maxScroll plonge souvent un instant (ex. 215→75) puis
+ * revient ; baisser le stock là, c’est perdre la position pour de bon.
+ */
+export function restoreScrollRoot(root: ScrollRoot): void {
+  if (!isSafariScrollEngine()) return;
+  const s = getState(root);
+  const maxY = maxScrollY(root);
+  const targetX = s.x;
+  // maxY===0 : collapse total transitoire → tenter quand même s.y (no-op clamp)
+  const targetY = maxY > 0 ? Math.min(s.y, maxY) : s.y;
+
+  const { x, y } = read(root);
+  if (
+    Math.abs(targetX - x) <= RESTORE_EPS &&
+    Math.abs(targetY - y) <= RESTORE_EPS
+  ) {
+    return;
+  }
+
+  s.restoring = true;
+  try {
+    write(root, targetX, targetY);
+  } finally {
+    requestAnimationFrame(() => {
+      s.restoring = false;
+    });
+  }
+}
+
+/** @deprecated alias */
+export function syncScrollRoot(root: ScrollRoot): void {
+  restoreScrollRoot(root);
+}
+
+export function resetScrollRoot(
+  root: ScrollRoot,
+  position: { x?: number; y?: number } | "current" = { x: 0, y: 0 },
+): void {
+  if (!isSafariScrollEngine()) return;
+  const s = getState(root);
+  if (position === "current") {
+    const pos = read(root);
+    s.x = pos.x;
+    s.y = pos.y;
+    return;
+  }
+  s.x = position.x ?? 0;
+  s.y = position.y ?? 0;
+}
+
+function stickyRestore(root: ScrollRoot): void {
+  const s = getState(root);
+  s.stickyFrames = STICKY_RESTORE_FRAMES;
+  if (s.raf) return;
+  const tick = () => {
+    s.raf = 0;
+    restoreScrollRoot(root);
+    if (s.stickyFrames > 0) {
+      s.stickyFrames--;
+      s.raf = requestAnimationFrame(tick);
+    }
+  };
+  s.raf = requestAnimationFrame(tick);
+}
+
+function scheduleRestore(root: ScrollRoot): void {
+  stickyRestore(root);
+}
+
+/**
+ * Branche écoute intent + scroll + resize (+ mutations).
+ * Idempotent.
+ */
+export function watchScrollRoot(root: ScrollRoot): void {
+  if (!isSafariScrollEngine()) return;
+  const s = getState(root);
+  if (s.watching) return;
+  s.watching = true;
+
+  const target: EventTarget = root === window ? window : root;
+
+  const onScroll = () => {
+    if (s.restoring) return;
+    const { y } = read(root);
+
+    // Gros drop d’un coup (y compris vers une valeur intermédiaire) → restore
+    if (looksLikePhantomDrop(y, s.y)) {
+      stickyRestore(root);
+      return;
+    }
+
+    if (s.userEngaged) {
+      captureScrollRoot(root);
+      armScrollSettle(root);
+      return;
+    }
+
+    // Pas d’intent taggé : adopter la position courante (pas un gros drop).
+    captureScrollRoot(root);
+  };
+
+  const isGestureForThisRoot = (e: Event) =>
+    nearestScrollRootFromEvent(e) === root;
+
+  const onUserIntent = (e: Event) => {
+    if (!isGestureForThisRoot(e)) return;
+    // Snapshot immédiat avant mutation DOM déclenchée par le clic.
+    captureScrollRoot(root);
+    markUserEngaged(root);
+  };
+
+  const onUserIntentEnd = (e: Event) => {
+    if (!isGestureForThisRoot(e)) return;
+    armScrollSettle(root);
+  };
+
+  const onWheel = (e: Event) => {
+    if (!isGestureForThisRoot(e)) return;
+    captureScrollRoot(root);
+    markUserEngaged(root);
+    armScrollSettle(root);
+  };
+
+  target.addEventListener("scroll", onScroll, { passive: true });
+  target.addEventListener("touchstart", onUserIntent, { passive: true });
+  target.addEventListener("touchend", onUserIntentEnd, { passive: true });
+  target.addEventListener("touchcancel", onUserIntentEnd, { passive: true });
+  target.addEventListener("wheel", onWheel, { passive: true });
+  target.addEventListener("pointerdown", onUserIntent, { passive: true });
+  target.addEventListener("pointerup", onUserIntentEnd, { passive: true });
+  target.addEventListener("pointercancel", onUserIntentEnd, { passive: true });
+
+  const pos = read(root);
+  s.x = pos.x;
+  s.y = pos.y;
+
+  if (root === window) {
+    const ro = new ResizeObserver(() => scheduleRestore(window));
+    ro.observe(document.documentElement);
+    s.resizeObserver = ro;
+    return;
+  }
+
+  const el = root as HTMLElement;
+  const ro = new ResizeObserver(() => scheduleRestore(el));
+  ro.observe(el);
+  for (const child of Array.from(el.children)) {
+    ro.observe(child);
+  }
+  s.resizeObserver = ro;
+
+  const onDomChange = () => scheduleRestore(el);
+  const mo = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      if (mutation.type !== "childList") continue;
+      for (const node of Array.from(mutation.addedNodes)) {
+        if (node instanceof Element) ro.observe(node);
+      }
+    }
+    onDomChange();
+  });
+  // Shadow children
+  mo.observe(el, { childList: true, subtree: true, characterData: true });
+  // Light DOM du host (contenu <slot>) — sinon on rate suppressions / updates
+  const rootNode = el.getRootNode();
+  if (rootNode instanceof ShadowRoot && rootNode.host) {
+    mo.observe(rootNode.host, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+  }
+  s.mutationObserver = mo;
+}
+
+function nearestScrollRootFromEvent(e: Event): ScrollRoot {
+  for (const node of e.composedPath()) {
+    if (node === window || node === document) continue;
+    if (node instanceof HTMLElement && isScrollContainer(node)) {
+      return node;
+    }
+  }
+  return window;
+}
+
+function isScrollContainer(el: Element): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  if (el === document.documentElement || el === document.body) return false;
+  const oy = getComputedStyle(el).overflowY;
+  return oy === "auto" || oy === "scroll" || oy === "overlay";
+}
+
+function discoverFromEvent(e: Event): void {
+  for (const node of e.composedPath()) {
+    if (node === window || node === document) continue;
+    if (node instanceof HTMLElement && isScrollContainer(node)) {
+      watchScrollRoot(node);
+    }
+  }
+
+  const engageRoot = nearestScrollRootFromEvent(e);
+  watchScrollRoot(engageRoot);
+
+  if (e.type === "wheel") {
+    captureScrollRoot(engageRoot);
+    markUserEngaged(engageRoot);
+    armScrollSettle(engageRoot);
+  } else if (e.type === "touchstart" || e.type === "pointerdown") {
+    captureScrollRoot(engageRoot);
+    markUserEngaged(engageRoot);
+  }
+}
+
+function watchScrollContainersInTree(root: ParentNode): void {
+  if (root instanceof Element && root.classList?.contains("custom-scroll")) {
+    watchScrollRoot(root as HTMLElement);
+  }
+  root.querySelectorAll?.(".custom-scroll").forEach((el) => {
+    if (el instanceof HTMLElement) watchScrollRoot(el);
+  });
+}
+
+function observeShadowRoot(shadow: ShadowRoot): void {
+  watchScrollContainersInTree(shadow);
+  const mo = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of Array.from(mutation.addedNodes)) {
+        if (node instanceof Element) watchScrollContainersInTree(node);
+      }
+    }
+  });
+  mo.observe(shadow, { childList: true, subtree: true });
+}
+
+function walkExistingShadows(node: ParentNode): void {
+  node.querySelectorAll?.("*").forEach((el) => {
+    if (el.shadowRoot) {
+      observeShadowRoot(el.shadowRoot);
+      walkExistingShadows(el.shadowRoot);
+    }
+  });
+}
+
+function patchAttachShadow(): void {
+  const proto = Element.prototype as Element & {
+    __safariScrollGuardPatched?: boolean;
+  };
+  if (proto.__safariScrollGuardPatched) return;
+  proto.__safariScrollGuardPatched = true;
+  const nativeAttachShadow = proto.attachShadow;
+  proto.attachShadow = function attachShadowPatched(
+    this: Element,
+    init: ShadowRootInit,
+  ): ShadowRoot {
+    const shadow = nativeAttachShadow.call(this, init);
+    observeShadowRoot(shadow);
+    return shadow;
+  };
+}
+
+export function installSafariScrollGuard(): void {
+  if (typeof window === "undefined" || installed) return;
+  installed = true;
+
+  if (!isSafariScrollEngine()) return;
+
+  watchScrollRoot(window);
+  patchAttachShadow();
+
+  const opts: AddEventListenerOptions = { capture: true, passive: true };
+  window.addEventListener("wheel", discoverFromEvent, opts);
+  window.addEventListener("touchstart", discoverFromEvent, opts);
+  window.addEventListener("pointerdown", discoverFromEvent, opts);
+
+  const scan = () => {
+    watchScrollContainersInTree(document);
+    walkExistingShadows(document);
+  };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", scan, { once: true });
+  } else {
+    scan();
+  }
+
+  const mo = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of Array.from(mutation.addedNodes)) {
+        if (!(node instanceof Element)) continue;
+        watchScrollContainersInTree(node);
+        if (node.shadowRoot) observeShadowRoot(node.shadowRoot);
+        walkExistingShadows(node);
+      }
+    }
+  });
+  mo.observe(document.documentElement, { childList: true, subtree: true });
+}

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

@@ -350,19 +350,14 @@
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load": {
+          "lazy-load--offset-and-limit": {
             "count": 1,
-            "title": "Lazy load",
+            "title": "Lazy load — `$offset` and `$limit`",
             "type": "paragraph"
           },
-          "manual-next-signal--supplement": {
+          "simple-batch-no-lazy-scroll": {
             "count": 1,
-            "title": "Manual next (signal) — supplement",
-            "type": "paragraph"
-          },
-          "simple-batch-no-pagination": {
-            "count": 1,
-            "title": "Simple batch (no pagination)",
+            "title": "Simple batch (no lazy scroll)",
             "type": "paragraph"
           }
         }
@@ -825,14 +820,14 @@
     }
   },
   {
-    "search": "In Lit apps, use defineQueue + .config on <sonic-queue> — typed Endpoint, DataProviderKey, enums. See src/docs/example/docs-queue-demos.ts.\n",
+    "search": "When the expression contains $offset and $limit, the queue:\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "queue": {
+          "lazy-load--offset-and-limit": {
             "count": 1,
-            "title": "",
+            "title": "Lazy load — `$offset` and `$limit`",
             "type": "paragraph"
           }
         }
@@ -840,14 +835,14 @@
     }
   },
   {
-    "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",
+    "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",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "queue": {
+          "lazy-load--offset-and-limit": {
             "count": 1,
-            "title": "",
+            "title": "Lazy load — `$offset` and `$limit`",
             "type": "paragraph"
           }
         }
@@ -855,14 +850,14 @@
     }
   },
   {
-    "search": "Layout (class, id, …) stays on <sonic-queue> — not inside .config.\n",
+    "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",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "queue": {
+          "lazy-load--offset-and-limit": {
             "count": 1,
-            "title": "",
+            "title": "Lazy load — `$offset` and `$limit`",
             "type": "paragraph"
           }
         }
@@ -870,14 +865,14 @@
     }
   },
   {
-    "search": "When pagination is enabled (default QueueLoadStrategy.Lazy), the queue:\n",
+    "search": "Try scrolling after load — batches of 4 users. Search e.g. George, Bluth, or zzz for empty results.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load": {
+          "lazy-load--offset-and-limit": {
             "count": 1,
-            "title": "Lazy load",
+            "title": "Lazy load — `$offset` and `$limit`",
             "type": "paragraph"
           }
         }
@@ -885,14 +880,14 @@
     }
   },
   {
-    "search": "Mock: GET /docs-mock-api/api/users?offset=…&limit=… (paginateUsers in src/docs/mock-api/router.ts).\n",
+    "search": "Without $offset in the expression, the queue behaves like a single list (one batch), e.g. geo communes below.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "lazy-load": {
+          "expression-example": {
             "count": 1,
-            "title": "Lazy load",
+            "title": "Expression example",
             "type": "paragraph"
           }
         }
@@ -900,37 +895,7 @@
     }
   },
   {
-    "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": {
-          "lazy-load": {
-            "count": 1,
-            "title": "Lazy load",
-            "type": "paragraph"
-          }
-        }
-      }
-    }
-  },
-  {
-    "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",
+    "search": "One search field (name="q") on formDataProvider="filter". The queue listens via dataFilterProvider="filter" and, on change:\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
@@ -945,7 +910,7 @@
     }
   },
   {
-    "search": "Use filteredFields in the config only when the form has fields that must not be sent to the API.\n",
+    "search": "Use filteredFields only when the form has extra fields that must not be sent to the API (e.g. filteredFields="rememberMe internalId").\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
@@ -960,7 +925,7 @@
     }
   },
   {
-    "search": "The users demo above wires docsQueueUsersFilterKey + sonic-input name="q". Mock filter: filterDocsUsers in src/docs/mock-api/fixtures.ts.\n",
+    "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",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
@@ -975,14 +940,14 @@
     }
   },
   {
-    "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",
+    "search": "Geo communes: expression uses $limit only (no $offset) — one request, one batch.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "manual-next-signal--supplement": {
+          "simple-batch-no-lazy-scroll": {
             "count": 1,
-            "title": "Manual next (signal) — supplement",
+            "title": "Simple batch (no lazy scroll)",
             "type": "paragraph"
           }
         }
@@ -990,44 +955,14 @@
     }
   },
   {
-    "search": "state exposes QueuePublisherState on the queue dataProvider: meta (e.g. total), loadedCount, hasMore. Wire sonic-button invalidate to the same next key.\n",
+    "search": "Optional for hosts without Lit — see HTML integration.\n",
     "files": {
       "core/components/functional/queue/queue.md": {
         "title": "Queue",
         "hashes": {
-          "manual-next-signal--supplement": {
+          "html-template-children": {
             "count": 1,
-            "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)",
+            "title": "HTML `<template>` children",
             "type": "paragraph"
           }
         }
@@ -2334,21 +2269,6 @@
       }
     }
   },
-  {
-    "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": {

package/src/tsconfig.json

@@ -789,6 +789,9 @@
       "./utils/PublisherProxy": [
         "/sites/concorde/src/core/utils/PublisherProxy.ts"
       ],
+      "./utils/SafariScrollGuard": [
+        "/sites/concorde/src/core/utils/SafariScrollGuard.ts"
+      ],
       "./utils/Utils": [
         "/sites/concorde/src/core/utils/Utils.ts"
       ],