@supersoniks/concorde 4.9.7 → 4.9.91

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/decorators.ts

@@ -19,6 +19,8 @@ export const get = api.get;
 export const post = api.post;
 export const put = api.put;
 export const patch = api.patch;
+export const refetch = api.refetch;
+export const send = api.send;
 export {
   DataProviderKey,
   type DataProviderKeyHost,
@@ -27,6 +29,9 @@ export { Endpoint };
 export type { ApiResult, ApiGetResult } from "./core/utils/api";
 export type {
   ApiSendOptions,
+  ApiSendDecoratorHandle,
+  ApiMethodActionOptions,
+  GetDecoratorHandle,
   GetOptions,
   PostOptions,
   PutOptions,
@@ -57,4 +62,6 @@ window["concorde-decorator-subscriber"] = {
   post: api.post,
   put: api.put,
   patch: api.patch,
+  refetch: api.refetch,
+  send: api.send,
 };

package/src/docs/_decorators/get.md

@@ -1,123 +1,124 @@
 # @get
 
-Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response` (or `null` for `dataProvider(...)` resolution without HTTP), and typed `result`.
+`@get` loads data and stores the result in an optional `ApiResult<T>` property.
+The property is `undefined` until a result is available.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument. Import `get` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+- `payload.result`: typed data;
+- `payload.response`: the HTTP response;
+- `payload.request`: the request that was sent.
 
-## Configuration
+## Minimal usage
 
-- **Default:** `HTML.getApiConfiguration(host)` (ancestor `serviceURL`, etc.).
-- **Second argument:** `DataProviderKey<APIConfiguration>` — config is read from the publisher at the resolved path; internal mutations trigger another GET. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
+```typescript
+const usersEndpoint = new Endpoint<User[]>("users");
 
-## Dynamic path
+@get(usersEndpoint)
+@state()
+payload?: ApiResult<User[]>;
+```
 
-`${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+The first argument is always an
+[`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint). API configuration is read
+from the HTML scope (`serviceURL`, token, etc.), so the component is usually
+placed below an element that provides this configuration.
 
-## Options (`GetOptions`)
+## Refetching a GET
 
-Pass as the **second** argument (scoped config) or **third** (with a configuration key). Same shape as send decorators where applicable:
+### From the component
 
-| Option | Description |
-|--------|-------------|
-| `skipEmptyPlaceholder` | Treat `""` as not ready (see [Dynamic path](#docs/_misc/dynamic-path.md/dynamic-path)). |
-| `refetchEveryMs` | Automatic polling interval (ms). `0` or omitted = no polling. |
-| `triggerKey` | `DataProviderKey` — `PublisherManager.get(...).invalidate()` on that publisher re-runs the GET. |
+Keep the decorator in a constant to access `refetch(component)`. Refetch only
+targets the instance passed as the argument, even before it has received a
+result.
 
-### Manual refetch (`triggerKey`)
+```typescript
+const usersGet = get(new Endpoint<User[]>("users"));
 
-Same pattern as [@post](#docs/_decorators/post.md/post): a publisher acts as a **signal**, independent of the response payload.
+@usersGet
+@state()
+payload?: ApiResult<User[]>;
+
+refresh() {
+  usersGet.refetch(this);
+}
+```
+
+### From a method decorator
+
+The refetch can decorate a local method. The default is `after`; if the
+method returns a Promise, the GET waits for its resolution.
 
 ```typescript
-import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { dp } from "@supersoniks/concorde/core/utils/PublisherProxy";
-
-const geoCommunesEndpoint = new Endpoint<GeoCommuneRow[]>(
-  "communes?limit=5&fields=nom,code",
-);
-const geoCommunesRefreshKey = new DataProviderKey<void>(
-  "docsDemoGeoCommunesRefresh",
-);
-
-@get(geoCommunesEndpoint, apiConfigurationKey, {
-  triggerKey: geoCommunesRefreshKey,
-})
-@state()
-payload: ApiResult<GeoCommuneRow[]> | null = null;
+import { refetch } from "@supersoniks/concorde/decorators";
+
+@refetch(usersGet)
+async reload() {
+  this.userId = "42";
+}
+```
 
-// Same component or anywhere else:
-dp(geoCommunesRefreshKey).invalidate();
+Use `{ when: "before" }` when the GET must be scheduled before the method:
+
+```typescript
+@refetch(usersGet, { when: "before" })
+reloadBefore() {
+  // The refetch is scheduled before this method runs.
+}
 ```
 
-Prefer `triggerKey` over mutating the API configuration publisher when you only want to **reload the same URL** — no need to touch `serviceURL`, tokens, etc.
+The method decorator adds an explicit trigger; changes to dynamic endpoint
+properties and configuration publishers keep their existing automatic behavior.
+
+## Options (`GetOptions`)
+
+Options are the second argument, or the third argument when an API
+configuration key is provided.
+
+- `skipEmptyPlaceholder`: blocks the GET when `${prop}` is `""`.
+- `refetchEveryMs`: automatically runs the GET again after this interval
+  (milliseconds). Omit the option, or use `0`, to disable polling.
 
-The docs mock adds an **`X-Fetched-At`** response header on `/docs-mock-api/geo/communes` so live demos can show when the last fetch happened (`response.headers.get("X-Fetched-At")`).
+With a configuration key, use:
+
+```typescript
+@get(usersEndpoint, apiConfigurationKey)
+```
 
 ## When the GET runs again
 
-- A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
-- `set` on the active configuration publisher (`onInternalMutation`).
-- `triggerKey` publisher `invalidate()`.
-- `refetchEveryMs` polling (after each successful fetch).
+- when the component connects and configuration is available;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- after each response when `refetchEveryMs` is set.
+
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Minimal example
-
-Same demo service as [`sonic-queue`](../../core/components/functional/queue/queue.demo.ts) (`/docs-mock-api/geo/`). Publisher setup lives in `decorators-demo-geo.ts` and `decorators-demo-subscribe-publish-get-demos.ts`.
-
-<sonic-code language="typescript">
-  <template>
-@get(new Endpoint<User>("users/${userId}"))
-@state()
-payload: ApiResult<User> | null = null;
-  </template>
-</sonic-code>
-
-## Live demos
-
-`@get` with **`triggerKey`** — refresh button + `X-Fetched-At` timestamp in the UI:
+## Demos
 
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-get"></docs-demo-sources>
     <demo-api-get></demo-api-get>
-  </template>
-</sonic-code>
-
-Dynamic config and endpoint path. Manual refetch is triggered **from a separate component** (same `triggerKey` publisher):
-
-<sonic-code>
-  <template>
     <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
     <demo-api-get-configuration-key></demo-api-get-configuration-key>
-    <demo-api-get-refresh-remote></demo-api-get-refresh-remote>
-  </template>
-</sonic-code>
-
-Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#docs/_decorators/publish.md/publish) and [@subscribe](#docs/_decorators/subscribe.md/subscribe)) — wrap under an ancestor with `serviceURL="/docs-mock-api/geo/"`:
-
-<sonic-code>
-  <template>
-<div serviceURL="/docs-mock-api/geo/">
-  <docs-demo-sources for="demo-api-get-publish-subscribe"></docs-demo-sources>
-  <demo-api-get-publish-subscribe></demo-api-get-publish-subscribe>
-</div>
   </template>
 </sonic-code>
 
-Stale responses are ignored if the path or generation changed before the request finished.
+See [@post](#docs/_decorators/post.md/post),
+[@put](#docs/_decorators/put.md/put), and
+[@patch](#docs/_decorators/patch.md/patch) for write operations.
 
-## See also
+## Advanced
 
-- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)
-- [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — send decorators (same path rules)
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.