@supersoniks/concorde 4.9.4 → 4.9.6

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/_getting-started/ai-agents.md

@@ -29,7 +29,7 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 | `--skip-agents` | Never write `AGENTS.md` (skills / rules only) |
 | `--merge-agents` | Opt-in: keep the project preamble and append / refresh the Concorde block |
 | `--force-agents` | Opt-in: **replace** the whole `AGENTS.md` (destructive) |
-| `--overlay <dir>` | Extra rules/skills + optional `AGENTS.starter.md` for project-only agent notes |
+| `--overlay <dir>` | Extra rules/skills + optional `AGENTS.concorde.md` for project-only Concorde agent notes |
 | `--cursor-only` | Install only `.cursor/skills` and `.cursor/rules` |
 | `--jetbrains-only` | Install only `.aiassistant/rules/` |
 
@@ -46,10 +46,10 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 [optional project preamble — short, project-only]
 <!-- concorde-ai -->
 <package ai/AGENTS.md>
-[--- + overlay AGENTS.starter.md]
+[--- + overlay AGENTS.concorde.md]
 ```
 
-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.starter.md` (overlay). If the preamble duplicates package `AGENTS.md`, `ai-init` slims or drops it and prints a warning.
+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.
 
 ## What gets installed
 

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": {