@supersoniks/concorde 4.9.7 → 4.9.91

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

@@ -4744,6 +4744,51 @@
       }
     }
   },
+  {
+    "search": "The decorator returned by get(...) can be kept as a typed handle. Its refetch(component) action targets only the connected component instance and works even before the first ApiResult exists:\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "local-refetch-handle": {
+            "count": 1,
+            "title": "Local refetch handle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The inline form remains unchanged:\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "local-refetch-handle": {
+            "count": 1,
+            "title": "Local refetch handle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "For a refetch triggered from another component, keep using triggerKey and invalidate().\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "local-refetch-handle": {
+            "count": 1,
+            "title": "Local refetch handle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:\n",
     "files": {
@@ -4759,6 +4804,51 @@
       }
     }
   },
+  {
+    "search": "Same pattern as @post: a publisher acts as a signal, independent of the response payload.\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "manual-refetch-triggerkey": {
+            "count": 1,
+            "title": "Manual refetch (`triggerKey`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Prefer triggerKey over mutating the API configuration publisher when you only want to reload the same URL — no need to touch serviceURL, tokens, etc.\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "manual-refetch-triggerkey": {
+            "count": 1,
+            "title": "Manual refetch (`triggerKey`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "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")).\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "manual-refetch-triggerkey": {
+            "count": 1,
+            "title": "Manual refetch (`triggerKey`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Same demo service as sonic-queue (/docs-mock-api/geo/). Publisher setup lives in decorators-demo-geo.ts and decorators-demo-subscribe-publish-get-demos.ts.\n",
     "files": {
@@ -4775,7 +4865,22 @@
     }
   },
   {
-    "search": "Dynamic config and endpoint path (demo-api-get-configuration-key in doc sources):\n",
+    "search": "@get with triggerKey — refresh button + X-Fetched-At timestamp in the UI:\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Dynamic config and endpoint path. Manual refetch is triggered from a separate component (same triggerKey publisher):\n",
     "files": {
       "docs/_decorators/get.md": {
         "title": "@get",
@@ -5884,6 +5989,36 @@
       }
     }
   },
+  {
+    "search": "The decorator returned by post(...) can be kept as a typed handle. Its send(component) action re-runs the POST with the current body publisher:\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "local-send-handle": {
+            "count": 1,
+            "title": "Local send handle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "send() is an explicit write operation. It is intentionally distinct from GET invalidation because replaying a POST, PUT, or PATCH can have side effects.\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "local-send-handle": {
+            "count": 1,
+            "title": "Local send handle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Mock service: POST /docs-mock-api/api/register (same route as sonic-submit demos). Publisher setup lives in decorators-demo-post.ts.\n",
     "files": {
@@ -6874,6 +7009,21 @@
       }
     }
   },
+  {
+    "search": "Everything after <!-- concorde-ai --> 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": {

package/docs/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"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersoniks/concorde",
-  "version": "4.9.7",
+  "version": "4.9.91",
   "license": "MIT",
   "type": "module",
   "main": "",
@@ -13,7 +13,7 @@
     "postbuild-docs": "node scripts/post-build-docs.js",
     "prepublishOnly": "node scripts/pre-publish.mjs",
     "test": "vitest --reporter verbose --watch",
-    "test:ci": "vitest run --reporter verbose",
+    "test:ci": "vitest run --reporter verbose && node --test scripts/ai-init.test.mjs",
     "ai-init": "node scripts/ai-init.mjs"
   },
   "exports": {
@@ -1062,6 +1062,10 @@
       "types": "./dist/types/core/utils/PublisherProxy.d.ts",
       "default": "./dist/js/core/utils/PublisherProxy.js"
     },
+    "./utils/SafariScrollGuard": {
+      "types": "./dist/types/core/utils/SafariScrollGuard.d.ts",
+      "default": "./dist/js/core/utils/SafariScrollGuard.js"
+    },
     "./utils/Utils": {
       "types": "./dist/types/core/utils/Utils.d.ts",
       "default": "./dist/js/core/utils/Utils.js"

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

@@ -5,6 +5,13 @@ import { map } from "lit/directives/map.js";
 import DataProvider, { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
 import "@supersoniks/concorde/core/components/functional/list/list";
 import { HTML } from "@supersoniks/concorde/utils";
+import {
+  isSafariScrollEngine,
+  resetScrollRoot,
+  restoreScrollRoot,
+  watchScrollRoot,
+  type ScrollRoot,
+} from "@supersoniks/concorde/core/utils/SafariScrollGuard";
 import { ListItems } from "@supersoniks/concorde/core/components/functional/list/list";
 
 type QueueItem = {
@@ -74,7 +81,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     this.requestId = 0;
     this.isFirstRequest = true;
     this.nextHadEvent = false;
-    this.teardownScrollGuard();
+    this.teardownScrollSync();
     this.publisher.set({});
     super.disconnectedCallback();
     return;
@@ -106,8 +113,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
         HTML.getAncestorAttributeValue(this.parentElement, "dataProvider") ||
         "";
     }
-    this.captureScrollPosition();
-    this.ensureScrollGuard();
+    this.ensureScrollSync();
     super.connectedCallback();
     this.publisher.set({});
     this.key = this.getAttribute("key");
@@ -164,8 +170,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     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;
+    resetScrollRoot(this.resolveScrollRoot(), { x: 0, y: 0 });
 
     /**
      * on reset les données avant de lancer la requète
@@ -193,23 +198,15 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
   };
 
   /**
-   * 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).
+   * Conteneur scrollé — Safari : stock/restore via SafariScrollGuard
+   * (capture intent user globale). Ici : sync root + restore après Lit.
    */
-  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>;
+  scrollRoot: ScrollRoot | null = null;
+  private scrollSyncActive = false;
   private mutationObserver: MutationObserver | null = null;
-  private boundScrollTarget: EventTarget | null = null;
   private restoreGeneration = 0;
 
-  resolveScrollRoot(): HTMLElement | Window {
+  resolveScrollRoot(): ScrollRoot {
     const ancestor = HTML.getScrollingAncestor(this);
     if (
       !ancestor ||
@@ -221,136 +218,21 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     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;
-    }
-    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);
+    return isSafariScrollEngine();
   }
 
-  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) {
+  ensureScrollSync() {
+    if (!isSafariScrollEngine() || !this.isConnected) {
       return;
     }
     const root = this.resolveScrollRoot();
-    const target: EventTarget = root === window ? window : root;
-    if (this.scrollGuardActive && this.boundScrollTarget === target) {
-      this.scrollRoot = root;
+    this.scrollRoot = root;
+    watchScrollRoot(root);
+    if (this.scrollSyncActive) {
       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.scrollSyncActive = true;
     this.mutationObserver = new MutationObserver(() => {
       this.scheduleRestoreAfterChildren();
     });
@@ -361,27 +243,11 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     });
   }
 
-  teardownScrollGuard() {
+  teardownScrollSync() {
     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.scrollSyncActive = false;
     this.scrollRoot = null;
   }
 
@@ -390,7 +256,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
    * Ne pas await updateComplete *dans* updated (deadlock) — on sort du cycle via void async.
    */
   scheduleRestoreAfterChildren() {
-    if (!this.isSafari() || !this.isConnected) {
+    if (!isSafariScrollEngine() || !this.isConnected) {
       return;
     }
     const generation = ++this.restoreGeneration;
@@ -410,14 +276,17 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
       await new Promise<void>((r) => requestAnimationFrame(() => r()));
       if (generation !== this.restoreGeneration || !this.isConnected) return;
 
-      this.restoreScrollPosition();
+      const root = this.scrollRoot ?? this.resolveScrollRoot();
+      watchScrollRoot(root);
+      restoreScrollRoot(root);
     })();
   }
 
   protected updated(_changedProperties: PropertyValues): void {
-    if (this.isSafari()) {
-      this.ensureScrollGuard();
-      this.restoreScrollPosition();
+    if (isSafariScrollEngine()) {
+      this.ensureScrollSync();
+      const root = this.scrollRoot ?? this.resolveScrollRoot();
+      restoreScrollRoot(root);
       this.scheduleRestoreAfterChildren();
     }
 
@@ -533,7 +402,7 @@ export default class Queue extends Subscriber(LitElement, {} as QueueProps) {
     // Ne pas écraser le stock avec un jump Safari : uniquement sync du root / guard.
     if (this.isSafari()) {
       this.scrollRoot = this.resolveScrollRoot();
-      this.ensureScrollGuard();
+      this.ensureScrollSync();
     }
     if (!Array.isArray(this.props)) {
       return nothing;

package/src/core/components/ui/_css/scroll.ts

@@ -1,4 +1,7 @@
 import { css } from "lit";
+import { installSafariScrollGuard } from "@supersoniks/concorde/core/utils/SafariScrollGuard";
+
+installSafariScrollGuard();
 
 export const customScroll = css`
   .custom-scroll {

package/src/core/decorators/api.post.spec.ts

@@ -5,7 +5,7 @@ import API, {
   type ApiResult,
 } from "@supersoniks/concorde/core/utils/api";
 import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
-import { patch, post, put } from "./api";
+import { patch, post, put, send } from "./api";
 
 async function flushSendFrames() {
   await new Promise<void>((resolve) => {
@@ -68,6 +68,84 @@ describe("post", () => {
     expect(el.payload?.result).toEqual({ ok: true });
   });
 
+  it("expose un send local avec le body courant", async () => {
+    const bodyPubId = "postSpecLocalSend";
+    const pub = PublisherManager.get(bodyPubId);
+    pub.set({ value: "first" });
+    const bodyKey = new DataProviderKey<{ value: string }>(bodyPubId);
+    const syncEp = new Endpoint<{ ok: boolean }>("items/local-send");
+    const localPost = post(syncEp, bodyKey);
+    const tag = "test-api-post-local-send";
+
+    class C extends HTMLElement {
+      @localPost
+      payload: ApiResult<{ ok: boolean }> | null = null;
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const wrap = document.createElement("div");
+    wrap.setAttribute("serviceURL", "https://api.example.test");
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    wrap.appendChild(el);
+    document.body.appendChild(wrap);
+
+    await flushSendFrames();
+    vi.mocked(API.prototype.postDetailed).mockClear();
+
+    pub.set({ value: "second" });
+    localPost.send(el);
+    await flushSendFrames();
+
+    expect(API.prototype.postDetailed).toHaveBeenCalledTimes(1);
+    expect(API.prototype.postDetailed).toHaveBeenCalledWith(
+      "items/local-send",
+      { value: "second" },
+    );
+  });
+
+  it("peut décorer une méthode avec send après sa résolution", async () => {
+    const bodyPubId = "postSpecMethodSend";
+    const pub = PublisherManager.get(bodyPubId);
+    pub.set({ value: "first" });
+    const bodyKey = new DataProviderKey<{ value: string }>(bodyPubId);
+    const syncEp = new Endpoint<{ ok: boolean }>("items/method-send");
+    const localPost = post(syncEp, bodyKey);
+    const tag = "test-api-post-method-send";
+
+    class C extends HTMLElement {
+      @localPost
+      payload: ApiResult<{ ok: boolean }> | null = null;
+
+      @send(localPost)
+      async save() {
+        await Promise.resolve();
+        pub.set({ value: "after" });
+      }
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const wrap = document.createElement("div");
+    wrap.setAttribute("serviceURL", "https://api.example.test");
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    wrap.appendChild(el);
+    document.body.appendChild(wrap);
+
+    await flushSendFrames();
+    vi.mocked(API.prototype.postDetailed).mockClear();
+
+    await el.save();
+    await flushSendFrames();
+
+    expect(API.prototype.postDetailed).toHaveBeenCalledWith(
+      "items/method-send",
+      { value: "after" },
+    );
+  });
+
   it("endpoint dynamique et relance quand le body publisher mute", async () => {
     const bodyPubId = "postSpecBody2";
     const pub = PublisherManager.get(bodyPubId);