From ad0613d30981b477d0a97efcb1dc83ac7caf4f30 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Fri, 6 Nov 2026 21:15:29 +0100 Subject: [PATCH 01/22] feat(pat-inject): Add new trigger autoload-navigate which becomes active on navigate events. --- src/pat/inject/inject.js | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 0e75b6873..35c9ed803 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -24,6 +24,7 @@ parser.addArgument("source"); parser.addArgument("trigger", "default", [ "default", "autoload", + "autoload-navigate", "autoload-visible", "idle", ]); @@ -39,8 +40,9 @@ parser.addArgument("history", "none", ["none", "record"]); parser.addArgument("push-marker"); parser.addArgument("scroll"); -// Note: this should not be here but the parser would bail on unknown -// parameters and expand/collapsible need to pass the url to us. +// URL takes precedence over `href` or `action`. +// Use it only, if a semantically richer item like `` or `
` does not +// make sense. parser.addArgument("url"); const inject = { @@ -57,6 +59,8 @@ const inject = { // pat-validation's event handlers are initialized first. await utils.timeout(1); + this.uuid = create_uuid(); + const el = utils.jqToNode($el); const cfgs = this.extractConfig($el, opts); @@ -138,8 +142,7 @@ const inject = { this.onTrigger({ currentTarget: el }); } else { // generate UUID - const uuid = create_uuid(); - el.setAttribute("data-pat-inject-uuid", uuid); + el.setAttribute("data-pat-inject-uuid", this.uuid); // function to trigger the autoload and mark as triggered const delayed_trigger = (uuid_) => { @@ -158,7 +161,7 @@ const inject = { return true; }; window.setTimeout( - delayed_trigger.bind(null, uuid), + delayed_trigger.bind(null, this.uuid), cfgs[0].delay ); } @@ -166,6 +169,9 @@ const inject = { case "autoload-visible": this._initAutoloadVisible($el, cfgs); break; + case "autoload-navigate": + this._initAutoloadNavigate($el, cfgs); + break; case "idle": this._initIdleTrigger($el, cfgs[0].delay); break; @@ -472,7 +478,9 @@ const inject = { const method = cfg.sourceMod === "content" ? "innerHTML" : "outerHTML"; // There might be multiple sources, so we need to loop over them. // Access them with "innerHTML" or "outerHTML" depending on the sourceMod. - const sources_string = [...$sources].map(source => source[method]).join("\n"); + const sources_string = [...$sources] + .map((source) => source[method]) + .join("\n"); wrapper.innerHTML = sources_string; for (const img of wrapper.content.querySelectorAll("img")) { @@ -1049,6 +1057,17 @@ const inject = { observer.observe(el); }, + _initAutoloadNavigate($el, cfgs) { + const el = utils.jqToNode($el); + + events.add_event_listener( + window.navigation, + "navigate", + `pat-inject-autoload-navigate--${this.uuid}`, + this.onTrigger({ currentTarget: el }) + ); + }, + _initIdleTrigger($el, delay) { // TODO: handle item removed from DOM const timeout = parseInt(delay, 10); From 93d371987ce7701cabe9d4ce596d75bd3b8006c7 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:13:42 +0100 Subject: [PATCH 02/22] feat(core polyfills): Fire navigatesuccess in the Navigation API polyfill. The basic Navigation API polyfill now also fires a `navigatesuccess` event after `pushState` and `replaceState`, in addition to `navigate`. Note: Unlike the native implementation, the polyfill fires `navigate` after the URL has changed. Listening to `navigatesuccess` gives consistent timing for native and polyfilled implementations. Ref: ADR 0003 Assisted-by: Claude Opus 5.5 --- src/core/polyfills.js | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/core/polyfills.js b/src/core/polyfills.js index 3209cf7ae..f3d3b114b 100644 --- a/src/core/polyfills.js +++ b/src/core/polyfills.js @@ -41,7 +41,10 @@ // Navigation polyfill for Firefox and Safari, as of 2024-01-04 // NOTE: this is a very basic polyfill, it only supports firing a `navigate` -// event on location change and even that without interception support, etc. +// and `navigatesuccess` event on pushState/replaceState and even that without +// interception support, etc. +// Note: Unlike the native implementation, `navigate` is fired after the URL +// has changed. !(function () { if (window.navigation == undefined) { @@ -69,6 +72,7 @@ window.history.pushState = function () { pushState.apply(window.history, arguments); window.navigation.dispatchEvent(create_event(arguments)); + window.navigation.dispatchEvent(new Event("navigatesuccess")); }; // Same with replaceState @@ -76,6 +80,7 @@ window.history.replaceState = function () { replaceState.apply(window.history, arguments); window.navigation.dispatchEvent(create_event(arguments)); + window.navigation.dispatchEvent(new Event("navigatesuccess")); }; } })(); From b7e94c736657e07376359ffbd6171aae64b07fe3 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:14:37 +0100 Subject: [PATCH 03/22] fix(pat-inject): Do not store the UUID on the shared pattern object. pat-inject is a non-class based pattern - the registry calls `init` on the same plain object for every element. Storing the UUID on `this` meant every element initialization overwrote it. Create the UUID locally where it is needed instead: for the delayed autoload trigger and the autoload-navigate listener id. Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 35c9ed803..d5034c8fe 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -59,8 +59,6 @@ const inject = { // pat-validation's event handlers are initialized first. await utils.timeout(1); - this.uuid = create_uuid(); - const el = utils.jqToNode($el); const cfgs = this.extractConfig($el, opts); @@ -142,7 +140,8 @@ const inject = { this.onTrigger({ currentTarget: el }); } else { // generate UUID - el.setAttribute("data-pat-inject-uuid", this.uuid); + const uuid = create_uuid(); + el.setAttribute("data-pat-inject-uuid", uuid); // function to trigger the autoload and mark as triggered const delayed_trigger = (uuid_) => { @@ -161,7 +160,7 @@ const inject = { return true; }; window.setTimeout( - delayed_trigger.bind(null, this.uuid), + delayed_trigger.bind(null, uuid), cfgs[0].delay ); } @@ -1059,11 +1058,12 @@ const inject = { _initAutoloadNavigate($el, cfgs) { const el = utils.jqToNode($el); + const uuid = create_uuid(); events.add_event_listener( window.navigation, "navigate", - `pat-inject-autoload-navigate--${this.uuid}`, + `pat-inject-autoload-navigate--${uuid}`, this.onTrigger({ currentTarget: el }) ); }, From e5ab3f767d7b57c525f323b9be4cb39123d38c38 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:14:38 +0100 Subject: [PATCH 04/22] fix(pat-inject): Register the autoload-navigate handler instead of calling it. The autoload-navigate trigger called `onTrigger` immediately during initialization and passed its return value (undefined) as the event listener. Pass a callback instead. The navigate event is deliberately not passed to `onTrigger`, which would call `preventDefault` on it and cancel the navigation. Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index d5034c8fe..132964507 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -1064,7 +1064,7 @@ const inject = { window.navigation, "navigate", `pat-inject-autoload-navigate--${uuid}`, - this.onTrigger({ currentTarget: el }) + () => this.onTrigger({ currentTarget: el }) ); }, From 5cf29cf594cf10c11de0d62b693d592159da8810 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:14:39 +0100 Subject: [PATCH 05/22] feat(pat-inject): Trigger autoload-navigate on navigatesuccess for URL changes only. Listen to `navigatesuccess` instead of `navigate`. `navigate` is fired before the navigation is committed - the URL is not yet updated and the navigation might still be cancelled or unload the page. Only re-trigger when the URL without the hash has changed. This ignores anchor jumps and the same-URL `replaceState` calls which pat-inject uses to mark history entries ("pageload", "anchor"). Do not initialize if the Navigation API is not available. Ref: ADR 0003 Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 35 ++++++++++++++++---- src/pat/inject/inject.test.js | 60 +++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 6 deletions(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 132964507..4de95869a 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -1057,15 +1057,38 @@ const inject = { }, _initAutoloadNavigate($el, cfgs) { + /* Re-trigger the injection after each successful same-document + * navigation which changed the URL. + * + * We listen to `navigatesuccess` instead of `navigate`, as the latter + * is fired before the navigation is committed - the URL is not yet + * updated and the navigation might still be cancelled or unload the + * page. + */ const el = utils.jqToNode($el); + + if (!window.navigation) { + log.warn("Navigation API not available. Not initializing.", el); + return; + } + const uuid = create_uuid(); + const event_id = `pat-inject--autoload-navigate--${uuid}`; - events.add_event_listener( - window.navigation, - "navigate", - `pat-inject-autoload-navigate--${uuid}`, - () => this.onTrigger({ currentTarget: el }) - ); + // Only re-trigger on actual URL changes, ignoring hash changes and + // replaceState calls on the same URL, like the "pageload" and + // "anchor" history state markers set by pat-inject. + const strip_hash = (url) => url.split("#")[0]; + let last_url = strip_hash(window.location.href); + + events.add_event_listener(window.navigation, "navigatesuccess", event_id, () => { + const current_url = strip_hash(window.location.href); + if (current_url === last_url) { + return; + } + last_url = current_url; + this.onTrigger({ currentTarget: el }); + }); }, _initIdleTrigger($el, delay) { diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 9850a8821..0d5389c7a 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -4,6 +4,7 @@ import events from "../../core/events"; import registry from "../../core/registry"; import utils from "../../core/utils"; import { jest } from "@jest/globals"; +import "../../core/polyfills"; // window.navigation for jsdom const mockFetch = (text = "") => @@ -2475,6 +2476,65 @@ describe("pat-inject", function () { }); }); + describe("11b - Test trigger: autoload-navigate", function () { + let spy_trigger; + let initial_url; + + beforeEach(() => { + initial_url = window.location.href; + spy_trigger = jest.spyOn(pattern, "onTrigger").mockImplementation(() => {}); + }); + + afterEach(() => { + spy_trigger.mockRestore(); + events.remove_event_listener( + window.navigation, + "pat-inject--autoload-navigate--*" + ); + history.replaceState(null, "", initial_url); + document.body.innerHTML = ""; + }); + + const setup = async (config = "") => { + document.body.innerHTML = ` + toolbar + `; + const el = document.querySelector(".pat-inject"); + pattern.init($(el)); + await utils.timeout(1); + return el; + }; + + it("11b.1 - does not trigger on initialization", async () => { + await setup(); + expect(spy_trigger).not.toHaveBeenCalled(); + }); + + it("11b.2 - triggers on URL changes", async () => { + const el = await setup(); + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + expect(spy_trigger).toHaveBeenCalledTimes(1); + expect(spy_trigger.mock.calls[0][0].currentTarget).toBe(el); + + history.pushState(null, "", "/page-2"); + await utils.timeout(1); + expect(spy_trigger).toHaveBeenCalledTimes(2); + }); + + it("11b.3 - ignores hash changes and same-URL replaceState", async () => { + await setup(); + + history.pushState(null, "", "#anchor"); + history.replaceState("anchor", "", window.location.href); + await utils.timeout(1); + expect(spy_trigger).not.toHaveBeenCalled(); + }); + }); + describe("12 - caching", () => { afterEach(function () { document.body.innerHTML = ""; From 4c9af90347da8a2af77d64af5632e210af698aaf Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:14:40 +0100 Subject: [PATCH 06/22] feat(pat-inject): Do not allow autoload-navigate together with history: record. Recording history pushes a new history entry, which fires a navigation event which would re-trigger the injection again - an infinite loop. Log an error and do not initialize the trigger in that case. Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 11 +++++++++++ src/pat/inject/inject.test.js | 8 ++++++++ 2 files changed, 19 insertions(+) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 4de95869a..b055c688f 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -1067,6 +1067,17 @@ const inject = { */ const el = utils.jqToNode($el); + if (cfgs.some((cfg) => cfg.history === "record")) { + // Recording history would push a new history entry, which in turn + // would fire a navigation event and re-trigger this injection + // over and over again. + log.error( + "`trigger: autoload-navigate` cannot be combined with `history: record`. Not initializing.", + el + ); + return; + } + if (!window.navigation) { log.warn("Navigation API not available. Not initializing.", el); return; diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 0d5389c7a..3f9c868fd 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -2533,6 +2533,14 @@ describe("pat-inject", function () { await utils.timeout(1); expect(spy_trigger).not.toHaveBeenCalled(); }); + + it("11b.7 - is not initialized together with history: record", async () => { + await setup("history: record"); + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + expect(spy_trigger).not.toHaveBeenCalled(); + }); }); describe("12 - caching", () => { From 666e161f89f5e8a93c1386c3ba7d77d8cfa6afa8 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:14:41 +0100 Subject: [PATCH 07/22] fix(pat-inject): Clean up the autoload-navigate listener for removed elements. When the element was removed from the DOM - e.g. replaced by an injection - remove the navigation event listener instead of triggering an injection on a detached element. Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 11 ++++++++++- src/pat/inject/inject.test.js | 13 +++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index b055c688f..9c8b1804d 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -1092,13 +1092,22 @@ const inject = { const strip_hash = (url) => url.split("#")[0]; let last_url = strip_hash(window.location.href); + const trigger = () => { + if (!el.isConnected) { + // The element was removed from the DOM, e.g. replaced by an + // injection. Clean up. + events.remove_event_listener(window.navigation, event_id); + return; + } + this.onTrigger({ currentTarget: el }); + }; events.add_event_listener(window.navigation, "navigatesuccess", event_id, () => { const current_url = strip_hash(window.location.href); if (current_url === last_url) { return; } last_url = current_url; - this.onTrigger({ currentTarget: el }); + trigger(); }); }, diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 3f9c868fd..70e9b5914 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -2534,6 +2534,19 @@ describe("pat-inject", function () { expect(spy_trigger).not.toHaveBeenCalled(); }); + it("11b.5 - unregisters when the element is removed", async () => { + const el = await setup(); + el.remove(); + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + expect(spy_trigger).not.toHaveBeenCalled(); + + history.pushState(null, "", "/page-2"); + await utils.timeout(1); + expect(spy_trigger).not.toHaveBeenCalled(); + }); + it("11b.7 - is not initialized together with history: record", async () => { await setup("history: record"); From b65d89d3d0af4fdf27bac71746a5350c3a9a4379 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Sun, 8 Nov 2026 14:14:42 +0100 Subject: [PATCH 08/22] feat(pat-inject): Debounce autoload-navigate and re-trigger after running injections. Rapid successive navigations are debounced using the `delay` option (default: 0). pat-inject drops triggers while an injection is in progress. For autoload-navigate this would leave the content in the state of an outdated URL. Instead, remember a pending trigger and run it once after the running injection has finished. Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 24 +++++++++++++++++++++++- src/pat/inject/inject.test.js | 28 ++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 9c8b1804d..ff760128c 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -1092,6 +1092,7 @@ const inject = { const strip_hash = (url) => url.split("#")[0]; let last_url = strip_hash(window.location.href); + let pending = false; const trigger = () => { if (!el.isConnected) { // The element was removed from the DOM, e.g. replaced by an @@ -1099,15 +1100,36 @@ const inject = { events.remove_event_listener(window.navigation, event_id); return; } + if ($el.data("pat-inject-triggered")) { + // An injection is in progress. Re-trigger after it is done, + // so that the latest navigation state is reflected. + if (!pending) { + pending = true; + $el.one( + "pat-ajax-success.pat-inject-navigate pat-ajax-error.pat-inject-navigate", + async () => { + // Wait for the inject's own handlers to finish. + await utils.timeout(1); + pending = false; + trigger(); + } + ); + } + return; + } this.onTrigger({ currentTarget: el }); }; + // Debounce, to not fire one request per navigation on rapid + // successive navigations. + const debounced_trigger = utils.debounce(trigger, cfgs[0].delay || 0); + events.add_event_listener(window.navigation, "navigatesuccess", event_id, () => { const current_url = strip_hash(window.location.href); if (current_url === last_url) { return; } last_url = current_url; - trigger(); + debounced_trigger(); }); }, diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 70e9b5914..68adb6b96 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -2534,6 +2534,18 @@ describe("pat-inject", function () { expect(spy_trigger).not.toHaveBeenCalled(); }); + it("11b.4 - debounces rapid navigations with delay", async () => { + await setup("delay: 20ms"); + + history.pushState(null, "", "/page-1"); + history.pushState(null, "", "/page-2"); + history.pushState(null, "", "/page-3"); + await utils.timeout(1); + expect(spy_trigger).not.toHaveBeenCalled(); + await utils.timeout(30); + expect(spy_trigger).toHaveBeenCalledTimes(1); + }); + it("11b.5 - unregisters when the element is removed", async () => { const el = await setup(); el.remove(); @@ -2547,6 +2559,22 @@ describe("pat-inject", function () { expect(spy_trigger).not.toHaveBeenCalled(); }); + it("11b.6 - re-triggers once after an in-progress injection", async () => { + const el = await setup(); + $(el).data("pat-inject-triggered", true); // Injection in progress. + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + history.pushState(null, "", "/page-2"); + await utils.timeout(1); + expect(spy_trigger).not.toHaveBeenCalled(); + + $(el).removeData("pat-inject-triggered"); + $(el).trigger("pat-ajax-success"); + await utils.timeout(2); + expect(spy_trigger).toHaveBeenCalledTimes(1); + }); + it("11b.7 - is not initialized together with history: record", async () => { await setup("history: record"); From 7d61328cd200c3b0ef59025b173c49efe34a82be Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 02:56:13 +0100 Subject: [PATCH 09/22] maint(pat-inject): Remove the autoload-navigate trigger again. Reloading content on navigation or other events will be implemented in a dedicated pattern `pat-reload`, which uses pat-inject for the injection. Doing it in pat-inject would have required changing pat-inject's general contract - resolving the `url` relative to the current location and allowing other elements than `` and `` - for one use case, while the "when and which URL to reload" logic is not about injection. The polyfill's `navigatesuccess` event is kept. Ref: ADR 0001 Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 81 ------------------------- src/pat/inject/inject.test.js | 109 ---------------------------------- 2 files changed, 190 deletions(-) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index ff760128c..838d8e98b 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -24,7 +24,6 @@ parser.addArgument("source"); parser.addArgument("trigger", "default", [ "default", "autoload", - "autoload-navigate", "autoload-visible", "idle", ]); @@ -168,9 +167,6 @@ const inject = { case "autoload-visible": this._initAutoloadVisible($el, cfgs); break; - case "autoload-navigate": - this._initAutoloadNavigate($el, cfgs); - break; case "idle": this._initIdleTrigger($el, cfgs[0].delay); break; @@ -1056,83 +1052,6 @@ const inject = { observer.observe(el); }, - _initAutoloadNavigate($el, cfgs) { - /* Re-trigger the injection after each successful same-document - * navigation which changed the URL. - * - * We listen to `navigatesuccess` instead of `navigate`, as the latter - * is fired before the navigation is committed - the URL is not yet - * updated and the navigation might still be cancelled or unload the - * page. - */ - const el = utils.jqToNode($el); - - if (cfgs.some((cfg) => cfg.history === "record")) { - // Recording history would push a new history entry, which in turn - // would fire a navigation event and re-trigger this injection - // over and over again. - log.error( - "`trigger: autoload-navigate` cannot be combined with `history: record`. Not initializing.", - el - ); - return; - } - - if (!window.navigation) { - log.warn("Navigation API not available. Not initializing.", el); - return; - } - - const uuid = create_uuid(); - const event_id = `pat-inject--autoload-navigate--${uuid}`; - - // Only re-trigger on actual URL changes, ignoring hash changes and - // replaceState calls on the same URL, like the "pageload" and - // "anchor" history state markers set by pat-inject. - const strip_hash = (url) => url.split("#")[0]; - let last_url = strip_hash(window.location.href); - - let pending = false; - const trigger = () => { - if (!el.isConnected) { - // The element was removed from the DOM, e.g. replaced by an - // injection. Clean up. - events.remove_event_listener(window.navigation, event_id); - return; - } - if ($el.data("pat-inject-triggered")) { - // An injection is in progress. Re-trigger after it is done, - // so that the latest navigation state is reflected. - if (!pending) { - pending = true; - $el.one( - "pat-ajax-success.pat-inject-navigate pat-ajax-error.pat-inject-navigate", - async () => { - // Wait for the inject's own handlers to finish. - await utils.timeout(1); - pending = false; - trigger(); - } - ); - } - return; - } - this.onTrigger({ currentTarget: el }); - }; - // Debounce, to not fire one request per navigation on rapid - // successive navigations. - const debounced_trigger = utils.debounce(trigger, cfgs[0].delay || 0); - - events.add_event_listener(window.navigation, "navigatesuccess", event_id, () => { - const current_url = strip_hash(window.location.href); - if (current_url === last_url) { - return; - } - last_url = current_url; - debounced_trigger(); - }); - }, - _initIdleTrigger($el, delay) { // TODO: handle item removed from DOM const timeout = parseInt(delay, 10); diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 68adb6b96..9850a8821 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -4,7 +4,6 @@ import events from "../../core/events"; import registry from "../../core/registry"; import utils from "../../core/utils"; import { jest } from "@jest/globals"; -import "../../core/polyfills"; // window.navigation for jsdom const mockFetch = (text = "") => @@ -2476,114 +2475,6 @@ describe("pat-inject", function () { }); }); - describe("11b - Test trigger: autoload-navigate", function () { - let spy_trigger; - let initial_url; - - beforeEach(() => { - initial_url = window.location.href; - spy_trigger = jest.spyOn(pattern, "onTrigger").mockImplementation(() => {}); - }); - - afterEach(() => { - spy_trigger.mockRestore(); - events.remove_event_listener( - window.navigation, - "pat-inject--autoload-navigate--*" - ); - history.replaceState(null, "", initial_url); - document.body.innerHTML = ""; - }); - - const setup = async (config = "") => { - document.body.innerHTML = ` - toolbar - `; - const el = document.querySelector(".pat-inject"); - pattern.init($(el)); - await utils.timeout(1); - return el; - }; - - it("11b.1 - does not trigger on initialization", async () => { - await setup(); - expect(spy_trigger).not.toHaveBeenCalled(); - }); - - it("11b.2 - triggers on URL changes", async () => { - const el = await setup(); - - history.pushState(null, "", "/page-1"); - await utils.timeout(1); - expect(spy_trigger).toHaveBeenCalledTimes(1); - expect(spy_trigger.mock.calls[0][0].currentTarget).toBe(el); - - history.pushState(null, "", "/page-2"); - await utils.timeout(1); - expect(spy_trigger).toHaveBeenCalledTimes(2); - }); - - it("11b.3 - ignores hash changes and same-URL replaceState", async () => { - await setup(); - - history.pushState(null, "", "#anchor"); - history.replaceState("anchor", "", window.location.href); - await utils.timeout(1); - expect(spy_trigger).not.toHaveBeenCalled(); - }); - - it("11b.4 - debounces rapid navigations with delay", async () => { - await setup("delay: 20ms"); - - history.pushState(null, "", "/page-1"); - history.pushState(null, "", "/page-2"); - history.pushState(null, "", "/page-3"); - await utils.timeout(1); - expect(spy_trigger).not.toHaveBeenCalled(); - await utils.timeout(30); - expect(spy_trigger).toHaveBeenCalledTimes(1); - }); - - it("11b.5 - unregisters when the element is removed", async () => { - const el = await setup(); - el.remove(); - - history.pushState(null, "", "/page-1"); - await utils.timeout(1); - expect(spy_trigger).not.toHaveBeenCalled(); - - history.pushState(null, "", "/page-2"); - await utils.timeout(1); - expect(spy_trigger).not.toHaveBeenCalled(); - }); - - it("11b.6 - re-triggers once after an in-progress injection", async () => { - const el = await setup(); - $(el).data("pat-inject-triggered", true); // Injection in progress. - - history.pushState(null, "", "/page-1"); - await utils.timeout(1); - history.pushState(null, "", "/page-2"); - await utils.timeout(1); - expect(spy_trigger).not.toHaveBeenCalled(); - - $(el).removeData("pat-inject-triggered"); - $(el).trigger("pat-ajax-success"); - await utils.timeout(2); - expect(spy_trigger).toHaveBeenCalledTimes(1); - }); - - it("11b.7 - is not initialized together with history: record", async () => { - await setup("history: record"); - - history.pushState(null, "", "/page-1"); - await utils.timeout(1); - expect(spy_trigger).not.toHaveBeenCalled(); - }); - }); - describe("12 - caching", () => { afterEach(function () { document.body.innerHTML = ""; From 4db0d07869db1b6881dd1486379ef42d2e99f09f Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 02:58:57 +0100 Subject: [PATCH 10/22] feat(pat-reload): Add pat-reload to reload content on events. pat-reload reloads the content of an element when an event is fired - by default `navigatesuccess`, after same-document navigations which changed the URL. This is useful for toolbars, breadcrumbs or sidebars which depend on the current location. pat-reload defines when and from which URL to reload. The injection itself is delegated to pat-inject and can be configured via `data-pat-inject` on the same element. By default, the content is injected into the element itself. Options: - `url`: Required. Relative URLs are appended to the current URL (without query string and hash), absolute URLs are used as-is. - `trigger-event`: Default `navigatesuccess`. Navigation API events are listened to on `window.navigation`, all others on `document`. - `delay`: Debounce time for successive events. Hash changes and same-URL replaceState calls do not trigger a reload. Events during a running reload trigger one more reload afterwards. Listeners are removed when the element was removed from the DOM. The base URL for relative URLs is the current location for now. A configurable base URL - e.g. for Plone default pages - will follow. Ref: ADR 0001 Ref: ADR 0002 Ref: ADR 0003 Assisted-by: Claude Opus 5.5 --- src/pat/reload/reload.js | 177 ++++++++++++++++++++++++++++ src/pat/reload/reload.test.js | 210 ++++++++++++++++++++++++++++++++++ 2 files changed, 387 insertions(+) create mode 100644 src/pat/reload/reload.js create mode 100644 src/pat/reload/reload.test.js diff --git a/src/pat/reload/reload.js b/src/pat/reload/reload.js new file mode 100644 index 000000000..bb4ba7191 --- /dev/null +++ b/src/pat/reload/reload.js @@ -0,0 +1,177 @@ +/** + * pat-reload - Reload the content of an element on an event. + * + * The "when" and "from which URL" is defined by pat-reload, the "what" and + * "where" is delegated to pat-inject. + */ +import $ from "jquery"; +import { BasePattern } from "../../core/basepattern"; +import events from "../../core/events"; +import inject from "../inject/inject"; +import logging from "../../core/logging"; +import Parser from "../../core/parser"; +import registry from "../../core/registry"; +import utils from "../../core/utils"; + +const log = logging.getLogger("pat-reload"); + +export const parser = new Parser("reload"); +// URL to reload from. Relative URLs are resolved against the base URL. +parser.addArgument("url", null); +// Event which triggers the reload. +parser.addArgument("trigger-event", "navigatesuccess"); +// Debounce time for successive events. +parser.addArgument("delay", 0); + +// Events which are dispatched on `window.navigation`. +const NAVIGATION_EVENTS = [ + "navigate", + "navigatesuccess", + "navigateerror", + "currententrychange", +]; + +/** + * Strip query string and hash from an URL. + * + * @param {String} url - The URL. + * @returns {String} - The URL without query string and hash. + */ +const strip_url = (url) => url.split(/[?#]/)[0]; + +class Pattern extends BasePattern { + static name = "reload"; + static trigger = ".pat-reload"; + static parser = parser; + + parser_group_options = false; + + async init() { + if (!this.options.url) { + log.error("No `url` defined. Not initializing.", this.el); + return; + } + + this.is_navigation_event = NAVIGATION_EVENTS.includes( + this.options["trigger-event"] + ); + this.event_source = this.is_navigation_event ? window.navigation : document; + if (!this.event_source) { + log.warn("Navigation API not available. Not initializing.", this.el); + return; + } + + try { + this.delay = utils.parseTime(this.options.delay) || 0; + } catch { + log.warn("Invalid delay value: ", this.options.delay); + this.delay = 0; + } + + this.event_id = `pat-reload--${this.uuid}`; + this.last_url = strip_url(window.location.href); + this.pending = false; + + const debounced_reload = utils.debounce(() => this.reload(), this.delay); + events.add_event_listener( + this.event_source, + this.options["trigger-event"], + this.event_id, + () => { + if (!this.el.isConnected) { + // The element was removed from the DOM. Clean up. + this.destroy(); + return; + } + if (this.is_navigation_event) { + // Only reload on actual URL changes. Ignore hash changes + // and same-URL `replaceState` calls. + const current_url = strip_url(window.location.href); + if (current_url === this.last_url) { + return; + } + this.last_url = current_url; + } + debounced_reload(); + } + ); + } + + /** + * Get the base URL against which relative URLs are resolved. + * + * TODO: Allow configuring the base URL (e.g. via a CSS selector for + * `[data-base-url]` or `link[rel=canonical]`). Note: those are not + * updated on same-document navigation, while `window.location` is. + * + * @returns {String} - The base URL, ending with a slash. + */ + get_base_url() { + return strip_url(window.location.href).replace(/\/?$/, "/"); + } + + /** + * Get the URL to reload from. + * + * Absolute URLs (with scheme, starting with `//` or `/`) are used as-is. + * Relative URLs are appended to the base URL. + * + * @returns {String} - The reload URL. + */ + get_url() { + return new URL(this.options.url, this.get_base_url()).href; + } + + /** + * Reload the content via pat-inject. + */ + reload() { + if (!this.el.isConnected) { + this.destroy(); + return; + } + + const $el = $(this.el); + if ($el.data("pat-inject-triggered")) { + // An injection is in progress, which would drop this reload. + // Re-trigger after it is done, so that the latest state is + // reflected. + if (!this.pending) { + this.pending = true; + $el.one( + "pat-ajax-success.pat-reload pat-ajax-error.pat-reload", + async () => { + // Wait for pat-inject's own handlers to finish. + await utils.timeout(1); + this.pending = false; + this.reload(); + } + ); + } + return; + } + + const cfgs = inject.extractConfig($el, { url: this.get_url() }); + for (const cfg of cfgs) { + // Inject into the element itself by default instead of into the + // body - which is pat-inject's default. + cfg.target = cfg.target || "self"; + } + log.debug("Reloading from", cfgs[0].url); + inject.execute(cfgs, $el); + } + + destroy() { + if (this.event_source && this.event_id) { + // Guard: Without element and id, `remove_event_listener` would + // remove all registered event listeners. + events.remove_event_listener(this.event_source, this.event_id); + } + $(this.el).off(".pat-reload"); + super.destroy(); + } +} + +registry.register(Pattern); +export default Pattern; +export { Pattern }; diff --git a/src/pat/reload/reload.test.js b/src/pat/reload/reload.test.js new file mode 100644 index 000000000..aa28c1f6c --- /dev/null +++ b/src/pat/reload/reload.test.js @@ -0,0 +1,210 @@ +import $ from "jquery"; +import events from "../../core/events"; +import inject from "../inject/inject"; +import Pattern from "./reload"; +import utils from "../../core/utils"; +import { jest } from "@jest/globals"; + +describe("pat-reload", () => { + let initial_url; + let spy_ajax; + let ajax_urls; + + beforeEach(() => { + initial_url = window.location.href; + ajax_urls = []; + spy_ajax = jest.spyOn($, "ajax").mockImplementation((args) => { + ajax_urls.push(args.url); + const deferred = $.Deferred(); + const html = `
reloaded ${ajax_urls.length}
`; + deferred.resolve(html, "ok", { responseText: html }); + return deferred; + }); + }); + + afterEach(() => { + spy_ajax.mockRestore(); + events.remove_event_listener(undefined, "pat-reload--*"); + history.replaceState(null, "", initial_url); + document.body.innerHTML = ""; + }); + + const setup = async (reload_config, inject_config = "") => { + history.replaceState(null, "", "/folder/page"); + document.body.innerHTML = ` +
initial
+ `; + const el = document.querySelector(".pat-reload"); + const instance = new Pattern(el); + await events.await_pattern_init(instance); + return { el, instance }; + }; + + describe("1 - Initialization", () => { + it("1.1 - does not reload on initialization", async () => { + await setup("url: @@render-toolbar#toolbar"); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + }); + + it("1.2 - does not initialize without url", async () => { + const { instance } = await setup(""); + expect(instance.event_id).toBeUndefined(); + + history.pushState(null, "", "/folder/other"); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + }); + + it("1.3 - destroy does not remove other event listeners", async () => { + const cb = jest.fn(); + events.add_event_listener(document, "test", "pat-reload-test", cb); + + const { instance } = await setup(""); + instance.destroy(); + + document.dispatchEvent(new Event("test")); + expect(cb).toHaveBeenCalled(); + events.remove_event_listener(document, "pat-reload-test"); + }); + }); + + describe("2 - Reload on navigation", () => { + it("2.1 - reloads into itself on URL changes", async () => { + const { el } = await setup("url: @@render-toolbar#toolbar"); + + history.pushState(null, "", "/folder/other"); + await utils.timeout(1); + + expect(ajax_urls).toEqual([ + `${window.location.origin}/folder/other/@@render-toolbar`, + ]); + expect(el.textContent).toBe("reloaded 1"); + + history.pushState(null, "", "/another/page?x=1#y"); + await utils.timeout(1); + + expect(ajax_urls[1]).toBe( + `${window.location.origin}/another/page/@@render-toolbar` + ); + expect(el.textContent).toBe("reloaded 2"); + }); + + it("2.2 - ignores hash changes and same-URL replaceState", async () => { + await setup("url: @@render-toolbar#toolbar"); + + history.pushState(null, "", "#anchor"); + history.replaceState("anchor", "", window.location.href); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + }); + + it("2.3 - uses absolute URLs as-is", async () => { + await setup("url: /@@render-toolbar#toolbar"); + + history.pushState(null, "", "/folder/other"); + await utils.timeout(1); + expect(ajax_urls).toEqual([`${window.location.origin}/@@render-toolbar`]); + }); + + it("2.4 - uses the pat-inject configuration", async () => { + document.body.innerHTML = `
other
`; + const { el } = await setup( + "url: @@render-toolbar", + "source: #toolbar; target: #other" + ); + // setup replaces the body - re-add the target. + el.insertAdjacentHTML("afterend", `
other
`); + + history.pushState(null, "", "/folder/other"); + await utils.timeout(1); + + expect(el.textContent).toBe("initial"); + expect(document.querySelector("#other").textContent).toBe("reloaded 1"); + }); + + it("2.5 - debounces rapid navigations with delay", async () => { + await setup("url: @@render-toolbar#toolbar; delay: 20ms"); + + history.pushState(null, "", "/page-1"); + history.pushState(null, "", "/page-2"); + history.pushState(null, "", "/page-3"); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + + await utils.timeout(30); + expect(ajax_urls).toEqual([ + `${window.location.origin}/page-3/@@render-toolbar`, + ]); + }); + + it("2.6 - re-triggers once after an in-progress injection", async () => { + const { el } = await setup("url: @@render-toolbar#toolbar"); + $(el).data("pat-inject-triggered", true); // Injection in progress. + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + history.pushState(null, "", "/page-2"); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + + $(el).removeData("pat-inject-triggered"); + $(el).trigger("pat-ajax-success"); + await utils.timeout(5); + expect(ajax_urls).toEqual([ + `${window.location.origin}/page-2/@@render-toolbar`, + ]); + }); + + it("2.7 - unregisters when the element is removed", async () => { + const { el, instance } = await setup("url: @@render-toolbar#toolbar"); + const spy_destroy = jest.spyOn(instance, "destroy"); + el.remove(); + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + expect(spy_destroy).toHaveBeenCalledTimes(1); + + history.pushState(null, "", "/page-2"); + await utils.timeout(1); + expect(spy_destroy).toHaveBeenCalledTimes(1); + }); + }); + + describe("3 - Reload on custom events", () => { + it("3.1 - reloads on any event bubbling up to the document", async () => { + const { el } = await setup( + "url: @@render-toolbar#toolbar; trigger-event: my-reload" + ); + + // A navigation does not trigger the reload. + history.pushState(null, "", "/folder/other"); + await utils.timeout(1); + expect(spy_ajax).not.toHaveBeenCalled(); + + document.body.dispatchEvent(new Event("my-reload", { bubbles: true })); + await utils.timeout(1); + expect(el.textContent).toBe("reloaded 1"); + + // Custom events also reload without URL changes. + document.dispatchEvent(new Event("my-reload")); + await utils.timeout(1); + expect(el.textContent).toBe("reloaded 2"); + }); + }); + + it("4 - uses pat-inject for the injection", async () => { + const spy_execute = jest.spyOn(inject, "execute"); + await setup("url: @@render-toolbar#toolbar"); + + history.pushState(null, "", "/folder/other"); + await utils.timeout(1); + expect(spy_execute).toHaveBeenCalledTimes(1); + spy_execute.mockRestore(); + }); +}); From 25a4734abb933d769e8e9e123612ab113bc07d02 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 02:58:57 +0100 Subject: [PATCH 11/22] feat(pat-reload): Add documentation and demo. Ref: ADR 0001 Ref: ADR 0002 Assisted-by: Claude Opus 5.5 --- index.html | 6 ++ src/pat/reload/documentation.md | 94 ++++++++++++++++++++++++++++++ src/pat/reload/index.html | 50 ++++++++++++++++ src/pat/reload/reload-content.html | 13 +++++ 4 files changed, 163 insertions(+) create mode 100644 src/pat/reload/documentation.md create mode 100644 src/pat/reload/index.html create mode 100644 src/pat/reload/reload-content.html diff --git a/index.html b/index.html index 80ece4eeb..af739ae7c 100644 --- a/index.html +++ b/index.html @@ -71,6 +71,12 @@

Behavioural

title="Push" >Pushβ + Reloadβ
diff --git a/src/pat/reload/documentation.md b/src/pat/reload/documentation.md new file mode 100644 index 000000000..97a4eef0e --- /dev/null +++ b/src/pat/reload/documentation.md @@ -0,0 +1,94 @@ +## Description + +Reload the content of an element when an event is fired - by default, when +the browser navigated to another URL without a full page load. + +This is useful for parts of a page which depend on the current location but +are not part of the content which changes, like toolbars, breadcrumbs or +sidebars. + +## Documentation + +`pat-reload` defines _when_ and _from which URL_ to reload. The actual +injection - _what_ is fetched and _where_ it goes - is done by `pat-inject`, +configured via a `data-pat-inject` attribute on the same element. + +### Reload on navigation + +
+ … +
+ +After each same-document navigation, which changed the URL (e.g. via +`history.pushState`), the element's content is replaced with the content of +the `#toolbar` element from `/@@render-toolbar`. + +Hash changes and `replaceState` calls which do not change the URL do not +trigger a reload. + +### URL resolution + +- Relative URLs are appended to the current URL (without query string and + hash): `@@render-toolbar` on `/folder/page?a=1` reloads from + `/folder/page/@@render-toolbar`. +- Absolute URLs - starting with a scheme like `https:`, with `//` or with `/` + \- are used as-is. + +Note: This is different from relative URLs in links, where `@@view` on +`/folder/page` resolves to `/folder/@@view`. + +Like in `pat-inject`, a selector can be appended to the URL after a `#`. + +### Injection configuration + +By default, the content is injected into the element itself. Use +`data-pat-inject` for other targets, sources or multiple injections: + +
+ … +
+ +Do not add the `pat-inject` class to the element. `pat-reload` uses only +`pat-inject`'s configuration and injection logic. + +### Reload on other events + +
+ … +
+ +Navigation API events (`navigate`, `navigatesuccess`, `navigateerror`, +`currententrychange`) are listened to on `window.navigation`, all other events +on `document`. So any event which bubbles up to the document can be used. For +non-navigation events the reload happens on every event, regardless of URL +changes. + +Note: Events which are triggered via jQuery's `.trigger()` cannot be listened +to with native event listeners. + +### Rapid successive events + +Use `delay` to debounce rapid successive events. Only one reload is done after +no event was fired for the given time. + +If an event is fired while a reload is still in progress, one more reload is +done after the running one has finished. + +### Option reference + +| Property | Default value | Description | Type | +| --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------ | +| `url` | | Required. The URL to reload from. Relative URLs are appended to the current URL. A `#selector` defines the injection source. | String | +| `trigger-event` | `navigatesuccess` | The event which triggers a reload. | String | +| `delay` | `0` | Debounce time in milliseconds, or with unit (`ms`, `s`, `m`), between successive events. | String | diff --git a/src/pat/reload/index.html b/src/pat/reload/index.html new file mode 100644 index 000000000..d6f89319a --- /dev/null +++ b/src/pat/reload/index.html @@ -0,0 +1,50 @@ + + + + pat-reload demo + + + + + +

pat-reload demo

+ +

Reload on navigation

+

+ Click the buttons to change the URL via history.pushState. The + box below reloads from reload-content.html#content after each + URL change. +

+ + + +
+ Not yet reloaded. +
+ +

Reload on a custom event

+ + +
+ Not yet reloaded. +
+ + diff --git a/src/pat/reload/reload-content.html b/src/pat/reload/reload-content.html new file mode 100644 index 000000000..0a32c00cc --- /dev/null +++ b/src/pat/reload/reload-content.html @@ -0,0 +1,13 @@ + + + + pat-reload demo content + + + +
+ Reloaded. + See the network panel of your browser's developer tools for the requests. +
+ + From b8f03956975d6881aeabbd1c72934356a5187ed0 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 02:58:57 +0100 Subject: [PATCH 12/22] feat(pat-reload): Add pat-reload to the Patternslib bundle. Ref: ADR 0001 Assisted-by: Claude Opus 5.5 --- src/patterns.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/patterns.js b/src/patterns.js index aafde2c1a..e86b28d46 100644 --- a/src/patterns.js +++ b/src/patterns.js @@ -44,6 +44,7 @@ import "./pat/modal/modal"; import "./pat/navigation/navigation"; import "./pat/notification/notification"; import "./pat/push/push"; +import "./pat/reload/reload"; import "./pat/scroll-box/scroll-box"; import "./pat/scroll/scroll"; import "./pat/scroll-marker/scroll-marker"; From b681b82431429212228ebfcf12ff8cfb6b33cd62 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 03:17:27 +0100 Subject: [PATCH 13/22] feat(pat-inject): Native API for injection state: execute return value and pat-inject-finished event. - `execute` now returns `true` if the injection was started and `false` otherwise - for invalid configurations, denied confirmations or when an injection is already in progress. Previously it returned `undefined`. - A native `pat-inject-finished` event is dispatched on the pat-inject element after the injection has finished - successfully or not. Until now the injection state was only available via jQuery: the `pat-inject-triggered` jQuery data and the `pat-ajax-success` and `pat-ajax-error` events, which are triggered via jQuery and cannot be listened to with native event listeners. Ref: ADR 0004 Assisted-by: Claude Opus 5.5 --- src/pat/inject/documentation.md | 23 +++++++------- src/pat/inject/inject.js | 25 +++++++++++---- src/pat/inject/inject.test.js | 56 +++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 17 deletions(-) diff --git a/src/pat/inject/documentation.md b/src/pat/inject/documentation.md index d439ac896..c4ea6ed1c 100644 --- a/src/pat/inject/documentation.md +++ b/src/pat/inject/documentation.md @@ -376,16 +376,17 @@ You can customise the behaviour of injection through options in the `data-pat-in pat-inject fires several JavaScript events which bubble up the DOM tree: -| Event name | Type | Triggered on | Bubbles | Description | -| ---------------------------------- | ---------- | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `patterns-inject-triggered` | jQuery | pat-inject-element | true | Triggered, right after injection has been triggered. This can be on click, on submit, automatically and so on. | -| `pat-ajax-success` | jQuery | pat-inject element | true | Triggered after successful ajax call but before the response is injected into the document | -| `patterns-injected` | jQuery | parent of injected content | true | Triggered after successful injection | -| `pat-inject-success` | JavaScript | pat-inject element | true | Triggered after successful injection, right after `patterns-injected` but on the pat-inject element and not on the injected content itself. | -| `patterns-injected-scanned` | jQuery | injected content | true | Triggered after injected content was scanned by Pattern registry for new patterns. | -| `patterns-injected-delayed` | JavaScript | injected content | true | Triggered 10ms after `patterns-injected-scanned` | -| `pat-inject-content-loaded` | jQuery | images within injected content | true | Triggered on images within the injected content when those images are loaded. | -| `pat-inject-missingSource` | jQuery | trigger which caused the injection | true | Triggered when no to-be-injected source could be found. | -| `pat-inject-missingTarget` | jQuery | trigger which caused the injection | true | Triggered when no target could be found. | +| Event name | Type | Triggered on | Bubbles | Description | +| --------------------------- | ---------- | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `patterns-inject-triggered` | jQuery | pat-inject-element | true | Triggered, right after injection has been triggered. This can be on click, on submit, automatically and so on. | +| `pat-ajax-success` | jQuery | pat-inject element | true | Triggered after successful ajax call but before the response is injected into the document | +| `patterns-injected` | jQuery | parent of injected content | true | Triggered after successful injection | +| `pat-inject-success` | JavaScript | pat-inject element | true | Triggered after successful injection, right after `patterns-injected` but on the pat-inject element and not on the injected content itself. | +| `pat-inject-finished` | JavaScript | pat-inject element | true | Triggered after the injection has finished - successfully or not. Also after errors, unlike `pat-inject-success`. | +| `patterns-injected-scanned` | jQuery | injected content | true | Triggered after injected content was scanned by Pattern registry for new patterns. | +| `patterns-injected-delayed` | JavaScript | injected content | true | Triggered 10ms after `patterns-injected-scanned` | +| `pat-inject-content-loaded` | jQuery | images within injected content | true | Triggered on images within the injected content when those images are loaded. | +| `pat-inject-missingSource` | jQuery | trigger which caused the injection | true | Triggered when no to-be-injected source could be found. | +| `pat-inject-missingTarget` | jQuery | trigger which caused the injection | true | Triggered when no target could be found. | Please note: `jQuery.trigger` events can be catched with jQuery only while JavaScript `dispatchEvent` events can be catched with bare JavaScript `addEventListener` and `jQuery.on`. diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 838d8e98b..7b3d25251 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -716,19 +716,26 @@ const inject = { * * Either by making an ajax request or by spoofing an ajax * request when the content is readily available in the current page. + * + * Returns `true` if the injection was started, `false` otherwise - + * e.g. if the configuration is invalid, the confirmation was denied + * or an injection is already in progress. + * + * When the injection has finished - successfully or not - a native + * `pat-inject-finished` event is dispatched on the element. */ const el = utils.jqToNode($el); // get a kinda deep copy, we scribble on it cfgs = cfgs.map((cfg) => $.extend({}, cfg)); if (!this.verifyConfig(cfgs)) { - return; + return false; } if (!this.askForConfirmation(cfgs)) { - return; + return false; } if ($el.data("pat-inject-triggered")) { // Prevent double triggers; - return; + return false; } $el.data("pat-inject-triggered", true); @@ -762,9 +769,14 @@ const inject = { } }); $el.on("pat-ajax-error.pat-inject", this._onInjectError.bind(this, $el, cfgs)); - $el.on("pat-ajax-success.pat-inject pat-ajax-error.pat-inject", () => - $el.removeData("pat-inject-triggered") - ); + $el.on("pat-ajax-success.pat-inject pat-ajax-error.pat-inject", async () => { + $el.removeData("pat-inject-triggered"); + // Wait for the success and error handlers to finish. + await utils.timeout(1); + el.dispatchEvent( + new Event("pat-inject-finished", { bubbles: true, cancelable: false }) + ); + }); // Prevent closing the panel while injection is in progress. let do_close_panel = false; @@ -791,6 +803,7 @@ const inject = { }, }); } + return true; }, _inject(trigger, source_nodes, target, cfg) { diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 9850a8821..eaaacfee9 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -752,6 +752,62 @@ describe("pat-inject", function () { spy_ajax.mockRestore(); }); + + it("8.7 - dispatches a native pat-inject-finished event after a successful injection", async function () { + const spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); + document.body.innerHTML = ` + link +
+ `; + const el = document.querySelector(".pat-inject"); + const callback = jest.fn(); + el.addEventListener("pat-inject-finished", callback); + + const started = pattern.execute(pattern.extractConfig($(el)), $(el)); + expect(started).toBe(true); + expect(callback).not.toHaveBeenCalled(); + + answer('
repl
'); + await utils.timeout(2); + expect(callback).toHaveBeenCalledTimes(1); + expect(document.querySelector("#someid").textContent).toBe("repl"); + + spy_ajax.mockRestore(); + }); + + it("8.8 - dispatches a native pat-inject-finished event after a failed injection", async function () { + const spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); + document.body.innerHTML = ` + link +
+ `; + const el = document.querySelector(".pat-inject"); + const callback = jest.fn(); + el.addEventListener("pat-inject-finished", callback); + + pattern.execute(pattern.extractConfig($(el)), $(el)); + deferred.reject({ status: 500, statusText: "error" }, "error", "error"); + await utils.timeout(2); + expect(callback).toHaveBeenCalledTimes(1); + + spy_ajax.mockRestore(); + }); + + it("8.9 - execute returns false if the injection was not started", async function () { + const spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); + document.body.innerHTML = ` + link +
+ `; + const el = document.querySelector(".pat-inject"); + + // Started. + expect(pattern.execute(pattern.extractConfig($(el)), $(el))).toBe(true); + // Already in progress. + expect(pattern.execute(pattern.extractConfig($(el)), $(el))).toBe(false); + + spy_ajax.mockRestore(); + }); }); describe("9 - DOM tests", function () { From d353334d438a1e3aecaa0f3afc414f7fc3343f02 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 03:17:29 +0100 Subject: [PATCH 14/22] fix(pat-inject): Do not inject if a non-id target cannot be created. Only missing `#id` targets can be created. For other missing targets, `createTarget` returned `null` but `ensureTarget` still reported success. `execute` then failed with a TypeError when adding the loading class to the non-existing target. Now the configuration is reported as invalid and the injection is not started. Assisted-by: Claude Opus 5.5 --- src/pat/inject/inject.js | 4 ++++ src/pat/inject/inject.test.js | 10 ++++++++++ 2 files changed, 14 insertions(+) diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index 7b3d25251..de3a29b1a 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -351,6 +351,10 @@ const inject = { return false; } cfg.$target = this.createTarget(cfg.target); + if (!cfg.$target) { + // The target could not be created. + return false; + } cfg.$created_target = cfg.$target; } return true; diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index eaaacfee9..8c62f8fc3 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -798,6 +798,7 @@ describe("pat-inject", function () { document.body.innerHTML = ` link
+ link `; const el = document.querySelector(".pat-inject"); @@ -806,6 +807,15 @@ describe("pat-inject", function () { // Already in progress. expect(pattern.execute(pattern.extractConfig($(el)), $(el))).toBe(false); + // Invalid configuration - non-id target cannot be created. + const invalid = document.querySelector(".invalid"); + expect( + pattern.execute( + pattern.extractConfig($(invalid), { target: ".nonexisting" }), + $(invalid) + ) + ).toBe(false); + spy_ajax.mockRestore(); }); }); From 490f1e144e579deef26b29fb460d519e0ee44926 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 03:17:29 +0100 Subject: [PATCH 15/22] maint(pat-reload): Use native APIs instead of jQuery for the reload state. Track running reloads with the return value of pat-inject's `execute` and the native `pat-inject-finished` event, registered via `events.add_event_listener`, instead of reading the `pat-inject-triggered` jQuery data and listening to the jQuery-triggered `pat-ajax-success` and `pat-ajax-error` events. `pat-inject-finished` events bubbling up from injections within the element are ignored. jQuery is only used for calling pat-inject's API, which expects jQuery objects. Ref: ADR 0004 Assisted-by: Claude Opus 5.5 --- src/pat/reload/reload.js | 52 ++++++++++++++++++++++------------- src/pat/reload/reload.test.js | 49 ++++++++++++++++++++++++++++----- 2 files changed, 75 insertions(+), 26 deletions(-) diff --git a/src/pat/reload/reload.js b/src/pat/reload/reload.js index bb4ba7191..8f0389179 100644 --- a/src/pat/reload/reload.js +++ b/src/pat/reload/reload.js @@ -70,8 +70,16 @@ class Pattern extends BasePattern { this.event_id = `pat-reload--${this.uuid}`; this.last_url = strip_url(window.location.href); + this.reloading = false; this.pending = false; + events.add_event_listener( + this.el, + "pat-inject-finished", + this.event_id, + this.on_inject_finished.bind(this) + ); + const debounced_reload = utils.debounce(() => this.reload(), this.delay); events.add_event_listener( this.event_source, @@ -131,26 +139,15 @@ class Pattern extends BasePattern { return; } - const $el = $(this.el); - if ($el.data("pat-inject-triggered")) { - // An injection is in progress, which would drop this reload. - // Re-trigger after it is done, so that the latest state is - // reflected. - if (!this.pending) { - this.pending = true; - $el.one( - "pat-ajax-success.pat-reload pat-ajax-error.pat-reload", - async () => { - // Wait for pat-inject's own handlers to finish. - await utils.timeout(1); - this.pending = false; - this.reload(); - } - ); - } + if (this.reloading) { + // A reload is in progress. Reload once more after it has + // finished, so that the latest state is reflected. + this.pending = true; return; } + // Note: pat-inject's API expects jQuery objects. + const $el = $(this.el); const cfgs = inject.extractConfig($el, { url: this.get_url() }); for (const cfg of cfgs) { // Inject into the element itself by default instead of into the @@ -158,7 +155,24 @@ class Pattern extends BasePattern { cfg.target = cfg.target || "self"; } log.debug("Reloading from", cfgs[0].url); - inject.execute(cfgs, $el); + this.reloading = inject.execute(cfgs, $el) === true; + } + + /** + * Handle the end of an injection started by this pattern. + * + * @param {Event} event - The `pat-inject-finished` event. + */ + on_inject_finished(event) { + if (event.target !== this.el) { + // Ignore bubbling events from injections within this element. + return; + } + this.reloading = false; + if (this.pending) { + this.pending = false; + this.reload(); + } } destroy() { @@ -166,8 +180,8 @@ class Pattern extends BasePattern { // Guard: Without element and id, `remove_event_listener` would // remove all registered event listeners. events.remove_event_listener(this.event_source, this.event_id); + events.remove_event_listener(this.el, this.event_id); } - $(this.el).off(".pat-reload"); super.destroy(); } } diff --git a/src/pat/reload/reload.test.js b/src/pat/reload/reload.test.js index aa28c1f6c..49bdf9903 100644 --- a/src/pat/reload/reload.test.js +++ b/src/pat/reload/reload.test.js @@ -142,25 +142,60 @@ describe("pat-reload", () => { ]); }); - it("2.6 - re-triggers once after an in-progress injection", async () => { + it("2.6 - reloads once more after a running reload", async () => { + // Hold back the responses until resolved manually. + const deferreds = []; + spy_ajax.mockImplementation((args) => { + ajax_urls.push(args.url); + const deferred = $.Deferred(); + deferreds.push(deferred); + return deferred; + }); + const respond = (html) => + deferreds.at(-1).resolve(html, "ok", { responseText: html }); + const { el } = await setup("url: @@render-toolbar#toolbar"); - $(el).data("pat-inject-triggered", true); // Injection in progress. history.pushState(null, "", "/page-1"); await utils.timeout(1); history.pushState(null, "", "/page-2"); await utils.timeout(1); - expect(spy_ajax).not.toHaveBeenCalled(); + history.pushState(null, "", "/page-3"); + await utils.timeout(1); + // Only the first reload is running. + expect(ajax_urls).toEqual([ + `${window.location.origin}/page-1/@@render-toolbar`, + ]); - $(el).removeData("pat-inject-triggered"); - $(el).trigger("pat-ajax-success"); + respond(`
page 1
`); await utils.timeout(5); + expect(el.textContent).toBe("page 1"); + // Exactly one more reload for the latest URL. expect(ajax_urls).toEqual([ - `${window.location.origin}/page-2/@@render-toolbar`, + `${window.location.origin}/page-1/@@render-toolbar`, + `${window.location.origin}/page-3/@@render-toolbar`, ]); + + respond(`
page 3
`); + await utils.timeout(5); + expect(el.textContent).toBe("page 3"); + expect(ajax_urls.length).toBe(2); + }); + + it("2.7 - ignores finished events from injections within the element", async () => { + const { el, instance } = await setup("url: @@render-toolbar#toolbar"); + instance.reloading = true; + instance.pending = true; + + el.innerHTML = ``; + el.firstElementChild.dispatchEvent( + new Event("pat-inject-finished", { bubbles: true }) + ); + expect(instance.reloading).toBe(true); + expect(spy_ajax).not.toHaveBeenCalled(); }); - it("2.7 - unregisters when the element is removed", async () => { + it("2.8 - unregisters when the element is removed", async () => { const { el, instance } = await setup("url: @@render-toolbar#toolbar"); const spy_destroy = jest.spyOn(instance, "destroy"); el.remove(); From c55e935f8b64d89c7b7f89950a0708f64ca704f5 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 03:33:07 +0100 Subject: [PATCH 16/22] breaking(pat-inject): Return a Promise from execute, which settles when the injection has finished. This allows to use async/await with pat-inject: try { const injected = await inject.execute(cfgs, $el); } catch (error) { log.warn("Could not load.", error); } The Promise: - resolves to `true` if the content was injected, - resolves to `false` if the injection was not started - invalid configuration, denied confirmation or an injection already in progress - or if there was nothing to inject, - rejects with an Error if the request failed with a network error or an HTTP error status. The error's `cause` is the jqXHR object. pat-inject's own error handling is done before. The `pat-inject-finished` event is dispatched right before the Promise settles. The Promise also waits for injections with a `process-delay`. This replaces the boolean return value from the previous commit. Note: Code which calls `execute` without handling the rejection now gets unhandled Promise rejections for failed requests. The internal callers in pat-inject, pat-collapsible and pat-expandable-tree catch them, as the error is already handled by pat-inject. Ref: ADR 0004 Assisted-by: Claude Opus 5.5 --- src/pat/collapsible/collapsible.js | 3 +- src/pat/expandable-tree/expandable-tree.js | 6 +- src/pat/inject/documentation.md | 28 +++++ src/pat/inject/inject.js | 93 +++++++++++---- src/pat/inject/inject.test.js | 127 ++++++++++++--------- 5 files changed, 181 insertions(+), 76 deletions(-) diff --git a/src/pat/collapsible/collapsible.js b/src/pat/collapsible/collapsible.js index 32a160564..7f016d3fe 100644 --- a/src/pat/collapsible/collapsible.js +++ b/src/pat/collapsible/collapsible.js @@ -164,7 +164,8 @@ class Pattern extends BasePattern { dataType: "html", }, ]; - inject.execute(opts, $el); + // Errors are already handled by pat-inject. + inject.execute(opts, $el).catch((error) => log.debug(error)); } // jQuery method to force loading of content. diff --git a/src/pat/expandable-tree/expandable-tree.js b/src/pat/expandable-tree/expandable-tree.js index 37c0daffd..365cc5a7b 100644 --- a/src/pat/expandable-tree/expandable-tree.js +++ b/src/pat/expandable-tree/expandable-tree.js @@ -1,8 +1,11 @@ import $ from "jquery"; import inject from "../inject/inject"; +import logging from "../../core/logging"; import Parser from "../../core/parser"; import registry from "../../core/registry"; +const log = logging.getLogger("pat.expandable-tree"); + export const parser = new Parser("expandable"); parser.addArgument("load-content"); @@ -55,7 +58,8 @@ var _ = { dataType: "html", }, ]; - inject.execute(opts, $el); + // Errors are already handled by pat-inject. + inject.execute(opts, $el).catch((error) => log.debug(error)); }); }, }; diff --git a/src/pat/inject/documentation.md b/src/pat/inject/documentation.md index c4ea6ed1c..3a9ecd7c7 100644 --- a/src/pat/inject/documentation.md +++ b/src/pat/inject/documentation.md @@ -390,3 +390,31 @@ pat-inject fires several JavaScript events which bubble up the DOM tree: | `pat-inject-missingTarget` | jQuery | trigger which caused the injection | true | Triggered when no target could be found. | Please note: `jQuery.trigger` events can be catched with jQuery only while JavaScript `dispatchEvent` events can be catched with bare JavaScript `addEventListener` and `jQuery.on`. + +### JavaScript API + +Injections can be started programmatically with `inject.execute(cfgs, $el)`. +It returns a Promise which settles when the injection has finished: + +- It resolves to `true` if the content was injected. +- It resolves to `false` if the injection was not started - e.g. if the + configuration is invalid, the confirmation was denied or an injection is + already in progress on the element - or if there was nothing to inject. +- It rejects with an `Error` if the request failed, e.g. with a network error + or an HTTP error status. The error's `cause` is the jqXHR object. + pat-inject's own error handling - like showing an error page - is done + before. + +```javascript +import inject from "@patternslib/patternslib/src/pat/inject/inject"; + +const cfgs = inject.extractConfig($el, { url: "/some/url#content" }); +try { + const injected = await inject.execute(cfgs, $el); +} catch (error) { + log.warn("Could not load.", error); +} +``` + +Note: Always handle the rejection, e.g. with `try`/`catch` or `.catch()`. +Otherwise failed requests result in unhandled Promise rejections. diff --git a/src/pat/inject/inject.js b/src/pat/inject/inject.js index de3a29b1a..f8aa63599 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -228,7 +228,7 @@ const inject = { } $el.trigger("patterns-inject-triggered"); - this.execute(cfgs, $el); + this.execute(cfgs, $el).catch((error) => log.debug(error)); }, submitSubform($sub) { @@ -247,7 +247,7 @@ const inject = { } catch (e) { log.error("patterns-inject-triggered", e); } - this.execute(cfgs, $el); + this.execute(cfgs, $el).catch((error) => log.debug(error)); }, extractConfig($el, options = {}) { @@ -588,7 +588,7 @@ const inject = { let data = ev?.jqxhr?.responseText; if (!data) { log.warn("No response content, aborting", ev); - return; + return false; } if (cfgs[0].source === "none") { // Special case, we want to call something, but we don't want to inject anything @@ -611,6 +611,7 @@ const inject = { $title = sources$[sources$.length - 1]; } + const delayed_injections = []; for (const [idx1, cfg] of cfgs.entries()) { const perform_inject = () => { if (cfg.target !== "none") { @@ -627,7 +628,9 @@ const inject = { } }; if (cfg.processDelay) { - setTimeout(() => perform_inject(), cfg.processDelay); + delayed_injections.push( + utils.timeout(cfg.processDelay).then(() => perform_inject()) + ); } else { perform_inject(); } @@ -640,6 +643,10 @@ const inject = { } $el.off("pat-ajax-success.pat-inject"); $el.off("pat-ajax-error.pat-inject"); + + // Wait for injections with a process delay. + await Promise.all(delayed_injections); + return true; }, async _onInjectError($el, cfgs, event) { @@ -721,25 +728,40 @@ const inject = { * Either by making an ajax request or by spoofing an ajax * request when the content is readily available in the current page. * - * Returns `true` if the injection was started, `false` otherwise - - * e.g. if the configuration is invalid, the confirmation was denied - * or an injection is already in progress. + * Returns a Promise which settles when the injection has finished: + * + * - Resolves to `true` if the content was injected. + * - Resolves to `false` if the injection was not started - e.g. if + * the configuration is invalid, the confirmation was denied or an + * injection is already in progress - or if there was nothing to + * inject. + * - Rejects with an error if the request failed, e.g. with a network + * error or an HTTP error status. The error's `cause` is the jqXHR + * object. pat-inject's own error handling is done before. * * When the injection has finished - successfully or not - a native - * `pat-inject-finished` event is dispatched on the element. + * `pat-inject-finished` event is dispatched on the element, right + * before the Promise settles. + * + * Usage: + * try { + * const injected = await inject.execute(cfgs, $el); + * } catch (error) { + * log.warn("Could not load.", error); + * } */ const el = utils.jqToNode($el); // get a kinda deep copy, we scribble on it cfgs = cfgs.map((cfg) => $.extend({}, cfg)); if (!this.verifyConfig(cfgs)) { - return false; + return Promise.resolve(false); } if (!this.askForConfirmation(cfgs)) { - return false; + return Promise.resolve(false); } if ($el.data("pat-inject-triggered")) { // Prevent double triggers; - return false; + return Promise.resolve(false); } $el.data("pat-inject-triggered", true); @@ -755,8 +777,32 @@ const inject = { } } + // Settle the returned Promise after the injection has finished. + let resolve_injection, reject_injection; + const injection = new Promise((resolve, reject) => { + resolve_injection = resolve; + reject_injection = reject; + }); + const finish = async (handler) => { + let result; + let error; + try { + result = await handler; + } catch (e) { + error = e; + } + el.dispatchEvent( + new Event("pat-inject-finished", { bubbles: true, cancelable: false }) + ); + if (error) { + reject_injection(error); + } else { + resolve_injection(result); + } + }; + $el.on("pat-ajax-success.pat-inject", async (e) => { - this._onInjectSuccess($el, cfgs, e); + finish(this._onInjectSuccess($el, cfgs, e)); // Wait for the next tick to ensure that the close-panel listener // is called before this one, even for non-async local injects. @@ -772,15 +818,22 @@ const inject = { ); } }); - $el.on("pat-ajax-error.pat-inject", this._onInjectError.bind(this, $el, cfgs)); - $el.on("pat-ajax-success.pat-inject pat-ajax-error.pat-inject", async () => { - $el.removeData("pat-inject-triggered"); - // Wait for the success and error handlers to finish. - await utils.timeout(1); - el.dispatchEvent( - new Event("pat-inject-finished", { bubbles: true, cancelable: false }) + $el.on("pat-ajax-error.pat-inject", (e) => { + finish( + this._onInjectError($el, cfgs, e).then(() => { + const status = e.jqxhr?.status; + throw new Error( + `Injection from ${cfgs[0].url} failed with status ${status} ${ + e.jqxhr?.statusText || "" + }`.trim(), + { cause: e.jqxhr } + ); + }) ); }); + $el.on("pat-ajax-success.pat-inject pat-ajax-error.pat-inject", () => + $el.removeData("pat-inject-triggered") + ); // Prevent closing the panel while injection is in progress. let do_close_panel = false; @@ -807,7 +860,7 @@ const inject = { }, }); } - return true; + return injection; }, _inject(trigger, source_nodes, target, cfg) { diff --git a/src/pat/inject/inject.test.js b/src/pat/inject/inject.test.js index 8c62f8fc3..82a8acc50 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -753,70 +753,89 @@ describe("pat-inject", function () { spy_ajax.mockRestore(); }); - it("8.7 - dispatches a native pat-inject-finished event after a successful injection", async function () { - const spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); - document.body.innerHTML = ` - link -
- `; - const el = document.querySelector(".pat-inject"); - const callback = jest.fn(); - el.addEventListener("pat-inject-finished", callback); + describe("8.7 - execute returns a Promise", function () { + let spy_ajax; + let el; - const started = pattern.execute(pattern.extractConfig($(el)), $(el)); - expect(started).toBe(true); - expect(callback).not.toHaveBeenCalled(); + beforeEach(function () { + spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); + document.body.innerHTML = ` + link +
+ `; + el = document.querySelector(".pat-inject"); + }); - answer('
repl
'); - await utils.timeout(2); - expect(callback).toHaveBeenCalledTimes(1); - expect(document.querySelector("#someid").textContent).toBe("repl"); + afterEach(function () { + spy_ajax.mockRestore(); + }); - spy_ajax.mockRestore(); - }); + it("8.7.1 - resolves to true after a successful injection", async function () { + const finished = jest.fn(); + el.addEventListener("pat-inject-finished", finished); - it("8.8 - dispatches a native pat-inject-finished event after a failed injection", async function () { - const spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); - document.body.innerHTML = ` - link -
- `; - const el = document.querySelector(".pat-inject"); - const callback = jest.fn(); - el.addEventListener("pat-inject-finished", callback); + const injection = pattern.execute(pattern.extractConfig($(el)), $(el)); + expect(injection).toBeInstanceOf(Promise); - pattern.execute(pattern.extractConfig($(el)), $(el)); - deferred.reject({ status: 500, statusText: "error" }, "error", "error"); - await utils.timeout(2); - expect(callback).toHaveBeenCalledTimes(1); + answer('
repl
'); + expect(await injection).toBe(true); + expect(document.querySelector("#someid").textContent).toBe("repl"); + expect(finished).toHaveBeenCalledTimes(1); + }); - spy_ajax.mockRestore(); - }); + it("8.7.2 - rejects with an error after a failed request", async function () { + const finished = jest.fn(); + el.addEventListener("pat-inject-finished", finished); - it("8.9 - execute returns false if the injection was not started", async function () { - const spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); - document.body.innerHTML = ` - link -
- link - `; - const el = document.querySelector(".pat-inject"); + const injection = pattern.execute(pattern.extractConfig($(el)), $(el)); + const jqxhr = { status: 404, statusText: "Not Found", responseText: "" }; + deferred.reject(jqxhr, "error", "Not Found"); - // Started. - expect(pattern.execute(pattern.extractConfig($(el)), $(el))).toBe(true); - // Already in progress. - expect(pattern.execute(pattern.extractConfig($(el)), $(el))).toBe(false); + let error; + try { + await injection; + } catch (e) { + error = e; + } + expect(error).toBeInstanceOf(Error); + expect(error.message).toBe( + "Injection from test.html failed with status 404 Not Found" + ); + expect(error.cause).toBe(jqxhr); + expect(finished).toHaveBeenCalledTimes(1); - // Invalid configuration - non-id target cannot be created. - const invalid = document.querySelector(".invalid"); - expect( - pattern.execute( - pattern.extractConfig($(invalid), { target: ".nonexisting" }), - $(invalid) - ) - ).toBe(false); + // pat-inject's own error handling was done. + expect(document.body.hasAttribute("data-error-message")).toBe(true); + document.body.removeAttribute("data-error-message"); + }); - spy_ajax.mockRestore(); + it("8.7.3 - resolves to false if the injection was not started", async function () { + // Started. + const injection = pattern.execute(pattern.extractConfig($(el)), $(el)); + // Already in progress. + expect(await pattern.execute(pattern.extractConfig($(el)), $(el))).toBe( + false + ); + + answer('
repl
'); + expect(await injection).toBe(true); + }); + + it("8.7.4 - resolves to false if there is nothing to inject", async function () { + const injection = pattern.execute(pattern.extractConfig($(el)), $(el)); + answer(""); + expect(await injection).toBe(false); + }); + + it("8.7.5 - resolves after delayed injections", async function () { + const cfgs = pattern.extractConfig($(el)); + cfgs[0].processDelay = 20; + const injection = pattern.execute(cfgs, $(el)); + + answer('
repl
'); + expect(await injection).toBe(true); + expect(document.querySelector("#someid").textContent).toBe("repl"); + }); }); }); From 385afad523b71e36eefddc57e5e6411930358de9 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 03:33:08 +0100 Subject: [PATCH 17/22] maint(pat-reload): Use async/await with pat-inject's execute. Await the Promise returned by `inject.execute` instead of listening to the `pat-inject-finished` event. This removes the event listener and the filtering of events bubbling up from injections within the element. Failed reloads are logged as warnings and do not block further reloads. Ref: ADR 0004 Assisted-by: Claude Opus 5.5 --- src/pat/reload/reload.js | 31 +++++++++---------------------- src/pat/reload/reload.test.js | 27 +++++++++++++++++---------- 2 files changed, 26 insertions(+), 32 deletions(-) diff --git a/src/pat/reload/reload.js b/src/pat/reload/reload.js index 8f0389179..65e3e466a 100644 --- a/src/pat/reload/reload.js +++ b/src/pat/reload/reload.js @@ -73,13 +73,6 @@ class Pattern extends BasePattern { this.reloading = false; this.pending = false; - events.add_event_listener( - this.el, - "pat-inject-finished", - this.event_id, - this.on_inject_finished.bind(this) - ); - const debounced_reload = utils.debounce(() => this.reload(), this.delay); events.add_event_listener( this.event_source, @@ -133,7 +126,7 @@ class Pattern extends BasePattern { /** * Reload the content via pat-inject. */ - reload() { + async reload() { if (!this.el.isConnected) { this.destroy(); return; @@ -154,24 +147,19 @@ class Pattern extends BasePattern { // body - which is pat-inject's default. cfg.target = cfg.target || "self"; } - log.debug("Reloading from", cfgs[0].url); - this.reloading = inject.execute(cfgs, $el) === true; - } - /** - * Handle the end of an injection started by this pattern. - * - * @param {Event} event - The `pat-inject-finished` event. - */ - on_inject_finished(event) { - if (event.target !== this.el) { - // Ignore bubbling events from injections within this element. - return; + log.debug("Reloading from", cfgs[0].url); + this.reloading = true; + try { + await inject.execute(cfgs, $el); + } catch (error) { + log.warn("Could not reload.", error); } this.reloading = false; + if (this.pending) { this.pending = false; - this.reload(); + await this.reload(); } } @@ -180,7 +168,6 @@ class Pattern extends BasePattern { // Guard: Without element and id, `remove_event_listener` would // remove all registered event listeners. events.remove_event_listener(this.event_source, this.event_id); - events.remove_event_listener(this.el, this.event_id); } super.destroy(); } diff --git a/src/pat/reload/reload.test.js b/src/pat/reload/reload.test.js index 49bdf9903..1261585a8 100644 --- a/src/pat/reload/reload.test.js +++ b/src/pat/reload/reload.test.js @@ -182,17 +182,24 @@ describe("pat-reload", () => { expect(ajax_urls.length).toBe(2); }); - it("2.7 - ignores finished events from injections within the element", async () => { - const { el, instance } = await setup("url: @@render-toolbar#toolbar"); - instance.reloading = true; - instance.pending = true; + it("2.7 - continues reloading after a failed reload", async () => { + const { el } = await setup("url: @@render-toolbar#toolbar"); + spy_ajax.mockImplementationOnce((args) => { + ajax_urls.push(args.url); + const deferred = $.Deferred(); + deferred.reject({ status: 500, statusText: "Error" }, "error", "Error"); + return deferred; + }); - el.innerHTML = ``; - el.firstElementChild.dispatchEvent( - new Event("pat-inject-finished", { bubbles: true }) - ); - expect(instance.reloading).toBe(true); - expect(spy_ajax).not.toHaveBeenCalled(); + history.pushState(null, "", "/page-1"); + await utils.timeout(5); + expect(el.textContent).toBe("initial"); + document.body.removeAttribute("data-error-message"); + + history.pushState(null, "", "/page-2"); + await utils.timeout(5); + expect(ajax_urls.length).toBe(2); + expect(el.textContent).toBe("reloaded 2"); }); it("2.8 - unregisters when the element is removed", async () => { From 2852d1c6fba3bfe716df8d5586927750697c121c Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 03:41:54 +0100 Subject: [PATCH 18/22] fix(pat-ajax): Track the latest request per element instead of per URL. pat-ajax only handles the result of the latest request, e.g. when a search form is submitted multiple times in a row. The requests were counted per URL globally though. When two different elements requested the same URL at the same time, the first element never received a `pat-ajax-success` event. For pat-inject this meant, that the first element stayed in the "injection in progress" state forever and could not inject again, and the Promise returned by `inject.execute` never settled. Now the requests are counted per element. The latest request of an element still wins - also when the same element requests different URLs, so that an outdated response cannot overwrite a newer one. Ref: ADR 0005 Assisted-by: Claude Opus 5.5 --- src/pat/ajax/ajax.js | 33 +++++++++++---------- src/pat/ajax/ajax.test.js | 60 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 17 deletions(-) diff --git a/src/pat/ajax/ajax.js b/src/pat/ajax/ajax.js index 44852f258..6fca19288 100644 --- a/src/pat/ajax/ajax.js +++ b/src/pat/ajax/ajax.js @@ -26,14 +26,10 @@ parser.addArgument("url", function ($el) { }); parser.addArgument("browser-cache", "no-cache", ["cache", "no-cache"]); // Cache ajax requests -const xhrCount = {}; -xhrCount.get = function (a) { - return this[a] !== undefined ? this[a] : 0; -}; -xhrCount.inc = function (a) { - this[a] = this.get(a) + 1; - return this.get(a); -}; +// Sequence number of the latest request per element. +// Used to only handle the result of the latest request of an element, e.g. +// when a search form is submitted multiple times in a row. +const request_sequence = new WeakMap(); const _ = { name: "ajax", @@ -91,18 +87,21 @@ const _ = { jqxhr: jqxhr, }); }; - const seqNumber = xhrCount.inc(cfg.url); + const el = $el[0]; + const seq_number = (request_sequence.get(el) || 0) + 1; + request_sequence.set(el, seq_number); const onSuccess = function (data, status, jqxhr) { log.debug("success: jqxhr:", jqxhr); - if (seqNumber === xhrCount.get(cfg.url)) { - // if this url is requested multiple time, only return the last result - $el.trigger({ - type: "pat-ajax-success", - jqxhr: {"url": cfg.url, ...jqxhr}, - }); - } else { - // ignore + if (seq_number !== request_sequence.get(el)) { + // This element has made a newer request in the meantime. + // Only handle the result of the latest request. + log.debug("Ignoring outdated response for", cfg.url); + return; } + $el.trigger({ + type: "pat-ajax-success", + jqxhr: { url: cfg.url, ...jqxhr }, + }); }; const temp = $el.data("pat-ajax.clicked-data"); const clickedData = temp ? $.param(temp) : ""; diff --git a/src/pat/ajax/ajax.test.js b/src/pat/ajax/ajax.test.js index e4206cee5..b1b2775bf 100644 --- a/src/pat/ajax/ajax.test.js +++ b/src/pat/ajax/ajax.test.js @@ -221,4 +221,64 @@ describe("pat-ajax", function () { spy_ajax.mockRestore(); }); }); + + describe("concurrent requests", function () { + let deferreds; + + beforeEach(function () { + deferreds = []; + jest.spyOn($, "ajax").mockImplementation(() => { + const deferred = $.Deferred(); + deferreds.push(deferred); + return deferred; + }); + }); + + afterEach(function () { + document.body.innerHTML = ""; + jest.restoreAllMocks(); + }); + + const respond = (deferred, html) => + deferred.resolve(html, "success", { responseText: html }); + + it("handles requests of different elements to the same URL", function () { + document.body.innerHTML = ` + 1 + 2 + `; + const $a1 = $(".a1"); + const $a2 = $(".a2"); + const success1 = jest.fn(); + const success2 = jest.fn(); + $a1.on("pat-ajax-success", success1); + $a2.on("pat-ajax-success", success2); + + pattern.request($a1); + pattern.request($a2); + respond(deferreds[0], "response 1"); + respond(deferreds[1], "response 2"); + + expect(success1).toHaveBeenCalledTimes(1); + expect(success1.mock.calls[0][0].jqxhr.responseText).toBe("response 1"); + expect(success2).toHaveBeenCalledTimes(1); + expect(success2.mock.calls[0][0].jqxhr.responseText).toBe("response 2"); + }); + + it("only handles the latest response of the same element", function () { + document.body.innerHTML = `1`; + const $a1 = $(".a1"); + const success = jest.fn(); + $a1.on("pat-ajax-success", success); + + pattern.request($a1); + pattern.request($a1); + // The newer request finishes first, the outdated one later. + respond(deferreds[1], "newer"); + respond(deferreds[0], "outdated"); + + expect(success).toHaveBeenCalledTimes(1); + expect(success.mock.calls[0][0].jqxhr.responseText).toBe("newer"); + }); + }); }); From cda00c7b1fde7ffa1325ff70457ef34344cc911e Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 04:03:55 +0100 Subject: [PATCH 19/22] maint: Add an AGENTS.md file for AI agent instructions. --- AGENTS.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..cc2f76684 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,100 @@ +# Patternslib AGENTS.md instructions + +## Relevant Paths + +- First search all the relevant paths, then - if needed - the individual `node_modules` directories. + +- "@patternslib/patternslib" at `./` is the main Patternslib directory +- "@patternslib/dev" at `../REPOS-pat/dev/` is for base configuration files, e.g. Webpack, prettier, eslint and release-it. +- External Patterns which use this Patternslib infrastructure can be found at: `../REPOS-pat/` +- Plone's "@plone/mockup" repository - the base Plone ClassicUI JavaScript library which uses "@patternslib/patternslib" can be found at: `../../../../plone/patternslib/mockup/` + +## Dev environment tips + +- "@plone/mockup" uses "pnpm" +- "@patternslib/patternslib" and most others use "yarn" (We think of switching to "pnpm") +- All we still Webpack based projects (We think of switching to "rspack" or "vite") +- All use "Jest" as testing framework (We think of switching to "vitest" or "rstest") +- We make heavy use of Module Federation to share libraries between individual Patternslib addons and not to load dependencies twice. +- We use "release-it" for releasing packages on npm. + +### Build output goes into its own "Compiled." commit + +Build output is everything under `./dist/`. + +- Source commits contain no build output. +- After the last source commit of a batch, before pushing, rebuild with + `make all` and commit all build output in one commit with the message + `Compiled.`. If you know exactly which output a change affects, you may + run only its target, but the + result still goes into that single `Compiled.` commit. If the build + changes nothing, there is no `Compiled.` commit. +- On a merge or rebase conflict in build output, do not resolve it by hand. + While the rebase runs, take either side and continue. Once it is done, + rebuild with `make all` at the tip and commit the result as `Compiled.`. + +### Commit message style + +- We use "conventionalchangelog" changelog generation when releasing. The format is `category(subtitle): commit message`, where category is one of `breaking`, `feat`, `maint` or `tech`. Subtitle should define the Pattern or module we were working on, e.g. "pat-inject". The commit message title is a concise summary of what was done. A more elaborate body can be given. + Example: + +``` +feat(pat-inject):‌ Sanitize HTML using DOMPurify + +We're now using DOMPurify to sanitize the HTML response instead of the previous custom regex based sanitization method. This improves the libraries security. +``` + +- If a source commit implements a decision documented in an ADR, reference that ADR in the commit message as (same rule as in AGENTS.md): + +``` +ORIGINAL COMMIT MESSAGE + +Ref: ADR NNNN +``` + +- If a commit was done with significant help from someone else, append this to the commit message: + +``` +ORIGINAL COMMIT MESSAGE + +Co-Authored-By: NAME +``` + +- If a commit was done with significant help from an AI, append this to the commit message: + +``` +ORIGINAL COMMIT MESSAGE + +Assisted-by: NAME +``` + +Don't use `Co-Authored-By` for AI contributions, as for Plone and other projects we need a contributor agreement for commits and an AI cannot sign it. + +- Use these rules in order as they are defined here - first ADR, then scrum, then co-authored, then assisted references. + +- These rules do not apply to build-output commits as defined above. Their commit message must be `Compiled.` + +## Architecture Decision Records + +Record significant decisions made during agentic sessions as Architecture +Decision Records (ADRs) in `./docs/adr/`. + +- Write an ADR when a session makes a non-trivial design, architecture or + styling decision, or a change whose reasoning is not obvious from the + code. Q&A, reviews and trivial fixes need none. If unsure, ask. +- Start with a draft ADR, so that it can be referenced from source commits. +- One ADR per decision, not per session. Write it when the decision is + implemented, before committing. +- File name: `NNNN-short-kebab-title.md`, numbered consecutively. +- Sections: title, `Status: (YYYY-MM-DD)`, + Context, Decision, Consequences. See `0001-*.md` as an example. +- Unpushed ADRs may be rewritten freely. Once pushed, an accepted ADR is + only changed for typos and clarifications; to revise the decision, write + a new ADR and mark the old one `Superseded by NNNN`. +- If a source commit implements a decision documented in an ADR, reference that ADR in the commit message as: + +``` +ORIGINAL COMMIT MESSAGE + +Ref: ADR NNNN +``` From a18c49a71486b2f25893a54b011ea0068bb912e3 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 04:06:49 +0100 Subject: [PATCH 20/22] maint(adr): Add ADRs for pat-reload, navigation handling, pat-inject's Promise API and pat-ajax request tracking. - ADR 0001: Reload content on events with pat-reload instead of a pat-inject trigger. - ADR 0002: pat-reload URL resolution relative to the current location. - ADR 0003: React to navigations on navigatesuccess, not navigate. - ADR 0004: pat-inject's execute returns a Promise. - ADR 0005: pat-ajax handles the latest request per element. Assisted-by: Claude Opus 5.5 --- ...at-reload-instead-of-pat-inject-trigger.md | 70 ++++++++++++++++++ docs/adr/0002-pat-reload-url-resolution.md | 60 ++++++++++++++++ ...-navigatesuccess-for-navigation-changes.md | 45 ++++++++++++ ...04-pat-inject-execute-returns-a-promise.md | 71 +++++++++++++++++++ ...005-pat-ajax-latest-request-per-element.md | 37 ++++++++++ 5 files changed, 283 insertions(+) create mode 100644 docs/adr/0001-pat-reload-instead-of-pat-inject-trigger.md create mode 100644 docs/adr/0002-pat-reload-url-resolution.md create mode 100644 docs/adr/0003-use-navigatesuccess-for-navigation-changes.md create mode 100644 docs/adr/0004-pat-inject-execute-returns-a-promise.md create mode 100644 docs/adr/0005-pat-ajax-latest-request-per-element.md diff --git a/docs/adr/0001-pat-reload-instead-of-pat-inject-trigger.md b/docs/adr/0001-pat-reload-instead-of-pat-inject-trigger.md new file mode 100644 index 000000000..bf8728abb --- /dev/null +++ b/docs/adr/0001-pat-reload-instead-of-pat-inject-trigger.md @@ -0,0 +1,70 @@ +# 0001 - Reload content on events with pat-reload instead of a pat-inject trigger + +Status: Accepted (2026-11-09) + +## Context + +A toolbar - a plain `
`, not an `` or `` - needs to be reloaded +whenever the browser navigates to another URL without a full page load (via +`history.pushState`, e.g. in Plone's folder contents). + +The first approach was a new pat-inject trigger `autoload-navigate`, as +pat-inject is already good at fetching and injecting content. While +implementing and reviewing it, it turned out that it required: + +- changing pat-inject's general contract for this one trigger: + - resolving `url` relative to the current location (appending to it) + instead of like a normal link, + - allowing elements other than `` and ``, if they have a `url`, +- about 70 lines of navigation handling: excluding `history: record` + (which would cause an infinite loop, as recording history fires a + navigation event again), filtering URL changes, cleaning up listeners of + removed elements, debouncing and re-triggering after a running + injection. + +None of that is about injection. It is about _when_ and _from which URL_ to +reload. pat-inject is already the most complex pattern in Patternslib. + +Mockup's `pat-toolbar` shows the same split: it listens to an +application-specific event and builds the URL from application knowledge, +but implements fetching and replacing itself with `$.ajax` - duplicating +what pat-inject does better (source/target selection, error handling, +loading classes, injection events, scanning for new patterns). + +## Decision + +- Remove the `autoload-navigate` trigger from pat-inject again. +- Add a generic pattern `pat-reload`, configured via `data-pat-reload`: + - `url` (required): the URL to reload from. See ADR 0002. + - `trigger-event` (default `navigatesuccess`): the event which triggers + a reload. See ADR 0003. + - `delay` (default `0`): debounce time for successive events. +- pat-reload decides _when_ and _from which URL_ to reload. _What_ is + fetched and _where_ it goes is delegated to pat-inject via its JavaScript + API (`inject.extractConfig` and `inject.execute`) and configured with + `data-pat-inject` on the same element. The element must not have the + `pat-inject` class. +- Unlike pat-inject, which injects into `body` by default, pat-reload + injects into the element itself if no target is configured. +- Events which arrive while a reload is running lead to exactly one more + reload after it has finished, so that the latest state is shown. +- When the element was removed from the DOM, the event listener is removed. +- The names `url` and `trigger-event` were chosen over `reload-view` (Zope + jargon, and the `reload-` prefix is redundant within `data-pat-reload`) + and `event-trigger` (Patternslib already uses `trigger` and + `trigger-element`). + +## Consequences + +- pat-inject's contract stays unchanged. +- pat-reload can be used for anything which needs to be reloaded on a + configurable event - toolbars, breadcrumbs, sidebars, portlets. +- pat-reload depends on pat-inject's JavaScript API, which expects jQuery + objects. To interact with it without jQuery events and data, pat-inject + got a native Promise based API. See ADR 0004. +- pat-push already does "reload this element on an event", but only for + push messages and with its own `fetch` and `innerHTML`. It could be built + upon pat-reload later. +- Events triggered via jQuery's `.trigger()` - like pat-structure's + `structure-url-changed` - cannot be used as `trigger-event`, as native + event listeners don't receive them. diff --git a/docs/adr/0002-pat-reload-url-resolution.md b/docs/adr/0002-pat-reload-url-resolution.md new file mode 100644 index 000000000..49b208c96 --- /dev/null +++ b/docs/adr/0002-pat-reload-url-resolution.md @@ -0,0 +1,60 @@ +# 0002 - pat-reload URL resolution relative to the current location + +Status: Accepted (2026-11-09) + +## Context + +pat-reload (ADR 0001) needs a URL which depends on the current location, e.g. +`/@@render-toolbar` in Plone. + +A fixed URL is wrong after a navigation. Standard relative URL resolution +does not work either: `@@render-toolbar` resolved against `/folder/page` +results in `/folder/@@render-toolbar` - the wrong context. + +When the `navigate` event fires, the new URL is not yet committed. After +`navigatesuccess`, `window.location` is up to date (ADR 0003). + +Hints in the DOM about the actual context - ``, +`link[rel=canonical]`, Plone's `data-base-url` on `` - are not updated +on same-document navigations. After `pushState`, they still describe the +initially loaded page. + +## Decision + +- Relative URLs are appended to the current location: the current URL + without query string and hash, with a trailing slash ensured. So + `@@render-toolbar` on `/folder/page?a=1#x` reloads from + `/folder/page/@@render-toolbar`. +- Absolute URLs - with a scheme like `https:`, starting with `//` or with + `/` - are used as-is. +- Resolution is done with the standard `new URL(url, base)`, which already + distinguishes relative and absolute URLs. No custom check, e.g. "starts + with `http` or `/`", which would miss other schemes and `//`. +- Like in pat-inject, a `#selector` appended to the URL defines the + injection source. +- The base URL is computed in a single method, `get_base_url`, so that it + can be made configurable later. + +## Consequences + +- Relative URLs in pat-reload behave differently from relative URLs in + links. This is documented. +- Plone default pages are not handled yet: there, the actual context is a + content item within the path shown in the URL bar. A configurable base + URL is to be designed separately. Considerations so far: + - An option like `base-url-selector` with a CSS selector, e.g. + `[data-base-url], link[rel=canonical]`. Other standard sources are + `` (reflected in `document.baseURI`); `og:url` is for + social media and not suitable. + - `querySelector` with a selector list returns the first match in + document order, not in the order of the list. Fallbacks would have + to be tried one by one - and selectors can contain commas themselves. + - The URL is stored in different attributes (`href` vs. + `data-base-url`), so the attribute to read needs a rule. + - The DOM hints are stale after same-document navigations. For + navigation events, the new location or the event itself (e.g. + pat-structure's `path`) are the only up-to-date sources - unless the + navigating code updates the hints. +- Changing pat-inject's `url` handling the same way was rejected. It would + have changed the result for every existing relative `url` and `href` + (ADR 0001). diff --git a/docs/adr/0003-use-navigatesuccess-for-navigation-changes.md b/docs/adr/0003-use-navigatesuccess-for-navigation-changes.md new file mode 100644 index 000000000..e4b903b6b --- /dev/null +++ b/docs/adr/0003-use-navigatesuccess-for-navigation-changes.md @@ -0,0 +1,45 @@ +# 0003 - React to navigations on navigatesuccess, not navigate + +Status: Accepted (2026-11-09) + +## Context + +The Navigation API's `navigate` event fires _before_ a navigation is +committed: + +- `window.location` still has the old URL. +- The navigation might still be cancelled. +- It also fires for navigations which unload the page (link clicks to other + pages, form submissions, reloads). Starting a request there is wasted. +- Passing the event on to code which calls `preventDefault()` - like + pat-inject's `onTrigger` - cancels the navigation. + +Patternslib's basic Navigation API polyfill (`src/core/polyfills.js`) for +browsers without the API only fired `navigate`, and - unlike the native +implementation - only _after_ `pushState` and `replaceState` changed the URL. +Native and polyfilled timing differed. + +pat-inject also calls `replaceState` without changing the URL to mark +history entries: `"pageload"` at module load and `"anchor"` on hash +navigations. These fire navigation events too. + +## Decision + +- Code reacting to navigations listens to `navigatesuccess`. Then the + navigation is committed and `window.location` is up to date. +- The polyfill also fires `navigatesuccess` after `pushState` and + `replaceState`. So `navigatesuccess` has the same timing natively and + polyfilled. +- Navigation-triggered reloads only happen if the URL without the hash has + changed. This ignores hash changes and same-URL `replaceState` calls. + +## Consequences + +- pat-reload uses `navigatesuccess` by default (ADR 0001). +- `navigatesuccess` carries no destination; the new URL is read from + `window.location`. +- Back/forward navigations after pat-inject `history: record` injections + trigger a full page reload by pat-inject's `popstate` handler anyway. A + navigation-triggered request might still be started right before that. +- The Navigation API is supported in all major browsers by now. Whether the + polyfill is still needed should be re-evaluated. diff --git a/docs/adr/0004-pat-inject-execute-returns-a-promise.md b/docs/adr/0004-pat-inject-execute-returns-a-promise.md new file mode 100644 index 000000000..bad7021e9 --- /dev/null +++ b/docs/adr/0004-pat-inject-execute-returns-a-promise.md @@ -0,0 +1,71 @@ +# 0004 - pat-inject's execute returns a Promise + +Status: Accepted (2026-11-09) + +## Context + +Code which starts injections via pat-inject's JavaScript API - like +pat-reload (ADR 0001) - needs to know when an injection has finished and +whether it succeeded, e.g. to reload once more after a running injection. + +The injection state was only available via jQuery: + +- pat-ajax triggers `pat-ajax-success` and `pat-ajax-error` with jQuery's + `.trigger()`. Native event listeners - including + `events.add_event_listener` - don't receive jQuery-triggered custom + events. +- The "injection in progress" flag is stored as jQuery data + (`pat-inject-triggered`). + +`execute` started the request and returned `undefined`. Errors were handled +by pat-inject itself (error pages, error message), with no way for the +calling code to react. + +A first step returned a boolean "started" from `execute` and added a native +`pat-inject-finished` event. Listening to an event after calling a method +needs filtering of events bubbling up from nested injections and still does +not allow `async`/`await`. `events.await_event` does not filter by target and +never settles if the event never comes. + +## Decision + +`inject.execute(cfgs, $el)` returns a Promise which settles when the +injection has finished: + +- It resolves to `true` if the content was injected. +- It resolves to `false` if the injection was not started - invalid + configuration, denied confirmation or an injection already in progress - + or if there was nothing to inject. +- It rejects with an `Error` if the request failed with a network error or + an HTTP error status. The error's `cause` is the jqXHR object. + pat-inject's own error handling is done before. +- It also waits for injections with a `process-delay`. + +Additionally, a native `pat-inject-finished` event is dispatched on the +element right before the Promise settles, for code which did not call +`execute` itself. + +Usage: + +```javascript +try { + const injected = await inject.execute(cfgs, $el); +} catch (error) { + log.warn("Could not load.", error); +} +``` + +## Consequences + +- This is a breaking change: code which calls `execute` and ignores the + return value now gets unhandled Promise rejections ("Uncaught (in + promise)") for failed requests. The internal callers in pat-inject, + pat-collapsible and pat-expandable-tree catch them. No callers were found + in Mockup or the add-ons in `REPOS-pat`. +- pat-reload uses `async`/`await` with `try`/`catch` and does not need any + jQuery events or data. It still needs jQuery objects to call pat-inject's + API. +- The Promise only settles if pat-ajax reports the result of the request. + pat-ajax silently dropped results of concurrent requests to the same URL + from different elements, which would leave the Promise unsettled forever. + This was fixed, see ADR 0005. diff --git a/docs/adr/0005-pat-ajax-latest-request-per-element.md b/docs/adr/0005-pat-ajax-latest-request-per-element.md new file mode 100644 index 000000000..d54f2d34c --- /dev/null +++ b/docs/adr/0005-pat-ajax-latest-request-per-element.md @@ -0,0 +1,37 @@ +# 0005 - pat-ajax handles the latest request per element + +Status: Accepted (2026-11-09) + +## Context + +Since 2016, pat-ajax only handles the result of the latest request: "if this +url is requested multiple time, only return the last result". The intention +is that, e.g. for a search form submitted multiple times in a row, an +outdated response does not overwrite a newer one. + +The requests were counted per URL, globally for the whole page. When two +different elements requested the same URL at the same time, the first +element never received a `pat-ajax-success` event: + +- pat-inject's "injection in progress" state of that element was never + reset, so it could never inject again. +- The Promise returned by `inject.execute` (ADR 0004) never settled, so + e.g. pat-reload (ADR 0001) would stop reloading. + +## Decision + +- Requests are counted per element, using a `WeakMap`. +- The latest request of an element wins - regardless of its URL. Counting + per element _and_ URL was rejected, as then an outdated response of the + same element requesting different URLs (e.g. different `formaction` + buttons) could still overwrite a newer one. + +## Consequences + +- Different elements requesting the same URL at the same time each get + their response. +- The original behavior for repeated requests of the same element is kept. +- Errors are still not filtered: a failed outdated request still triggers + `pat-ajax-error` while a newer request is running. Through pat-inject + this cannot happen, as an element cannot have two injections running at + the same time. It only affects bare `.pat-ajax` elements. From 9e8c04ecd21737d1d1d7a9aa4972a6a36f0e8b25 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 04:17:40 +0100 Subject: [PATCH 21/22] fixup: maint: Fix Agents.md problems. --- AGENTS.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cc2f76684..a9e4773b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,24 +18,9 @@ - We make heavy use of Module Federation to share libraries between individual Patternslib addons and not to load dependencies twice. - We use "release-it" for releasing packages on npm. -### Build output goes into its own "Compiled." commit - -Build output is everything under `./dist/`. - -- Source commits contain no build output. -- After the last source commit of a batch, before pushing, rebuild with - `make all` and commit all build output in one commit with the message - `Compiled.`. If you know exactly which output a change affects, you may - run only its target, but the - result still goes into that single `Compiled.` commit. If the build - changes nothing, there is no `Compiled.` commit. -- On a merge or rebase conflict in build output, do not resolve it by hand. - While the rebase runs, take either side and continue. Once it is done, - rebuild with `make all` at the tip and commit the result as `Compiled.`. - ### Commit message style -- We use "conventionalchangelog" changelog generation when releasing. The format is `category(subtitle): commit message`, where category is one of `breaking`, `feat`, `maint` or `tech`. Subtitle should define the Pattern or module we were working on, e.g. "pat-inject". The commit message title is a concise summary of what was done. A more elaborate body can be given. +- We use "conventionalchangelog" changelog generation when releasing. The format is `category(subtitle): commit message`, where category is one of `breaking`, `feat`, `fix`, `maint` or `tech`. Subtitle should define the Pattern or module we were working on, e.g. "pat-inject". The commit message title is a concise summary of what was done. A more elaborate body can be given. Example: ``` @@ -84,10 +69,10 @@ Decision Records (ADRs) in `./docs/adr/`. code. Q&A, reviews and trivial fixes need none. If unsure, ask. - Start with a draft ADR, so that it can be referenced from source commits. - One ADR per decision, not per session. Write it when the decision is - implemented, before committing. + implemented, before committing. This is not a strict rule. - File name: `NNNN-short-kebab-title.md`, numbered consecutively. - Sections: title, `Status: (YYYY-MM-DD)`, - Context, Decision, Consequences. See `0001-*.md` as an example. + Context, Decision, Consequences. See `./docs/adr/0004-pat-inject-execute-returns-a-promise.md` as an example. - Unpushed ADRs may be rewritten freely. Once pushed, an accepted ADR is only changed for typos and clarifications; to revise the decision, write a new ADR and mark the old one `Superseded by NNNN`. From 4f231db09e8d43fb85ff3085f56c85eabf8a39a2 Mon Sep 17 00:00:00 2001 From: Johannes Raggam Date: Mon, 9 Nov 2026 18:04:38 +0100 Subject: [PATCH 22/22] maint: Add docs/adr for documenting architectural decision records (ADR). --- docs/adr/0000-README.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/adr/0000-README.md diff --git a/docs/adr/0000-README.md b/docs/adr/0000-README.md new file mode 100644 index 000000000..f9301cba1 --- /dev/null +++ b/docs/adr/0000-README.md @@ -0,0 +1,9 @@ +# Architecture Decision Records + +This directory contains Architecture Decision Records from agentic sessions. + +## References + +- https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html +- https://martinfowler.com/bliki/ArchitectureDecisionRecord.html +- https://adr.github.io/