diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..a9e4773b7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# 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. + +### Commit message style + +- 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: + +``` +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. 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 `./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`. +- 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 +``` 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/ 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. 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/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")); }; } })(); 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"); + }); + }); }); 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 d439ac896..3a9ecd7c7 100644 --- a/src/pat/inject/documentation.md +++ b/src/pat/inject/documentation.md @@ -376,16 +376,45 @@ 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`. + +### 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 0e75b6873..f8aa63599 100644 --- a/src/pat/inject/inject.js +++ b/src/pat/inject/inject.js @@ -39,8 +39,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 = { @@ -227,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) { @@ -246,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 = {}) { @@ -350,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; @@ -472,7 +477,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")) { @@ -581,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 @@ -604,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") { @@ -620,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(); } @@ -633,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) { @@ -713,19 +727,41 @@ 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 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, 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; + return Promise.resolve(false); } if (!this.askForConfirmation(cfgs)) { - return; + return Promise.resolve(false); } if ($el.data("pat-inject-triggered")) { // Prevent double triggers; - return; + return Promise.resolve(false); } $el.data("pat-inject-triggered", true); @@ -741,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. @@ -758,7 +818,19 @@ const inject = { ); } }); - $el.on("pat-ajax-error.pat-inject", this._onInjectError.bind(this, $el, cfgs)); + $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") ); @@ -788,6 +860,7 @@ const inject = { }, }); } + 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 9850a8821..82a8acc50 100644 --- a/src/pat/inject/inject.test.js +++ b/src/pat/inject/inject.test.js @@ -752,6 +752,91 @@ describe("pat-inject", function () { spy_ajax.mockRestore(); }); + + describe("8.7 - execute returns a Promise", function () { + let spy_ajax; + let el; + + beforeEach(function () { + spy_ajax = jest.spyOn($, "ajax").mockImplementation(() => deferred); + document.body.innerHTML = ` + link +
+ `; + el = document.querySelector(".pat-inject"); + }); + + afterEach(function () { + 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); + + const injection = pattern.execute(pattern.extractConfig($(el)), $(el)); + expect(injection).toBeInstanceOf(Promise); + + answer('
repl
'); + expect(await injection).toBe(true); + expect(document.querySelector("#someid").textContent).toBe("repl"); + expect(finished).toHaveBeenCalledTimes(1); + }); + + it("8.7.2 - rejects with an error after a failed request", async function () { + const finished = jest.fn(); + el.addEventListener("pat-inject-finished", finished); + + const injection = pattern.execute(pattern.extractConfig($(el)), $(el)); + const jqxhr = { status: 404, statusText: "Not Found", responseText: "" }; + deferred.reject(jqxhr, "error", "Not Found"); + + 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); + + // pat-inject's own error handling was done. + expect(document.body.hasAttribute("data-error-message")).toBe(true); + document.body.removeAttribute("data-error-message"); + }); + + 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"); + }); + }); }); describe("9 - DOM tests", function () { 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. +
+ + diff --git a/src/pat/reload/reload.js b/src/pat/reload/reload.js new file mode 100644 index 000000000..65e3e466a --- /dev/null +++ b/src/pat/reload/reload.js @@ -0,0 +1,178 @@ +/** + * 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.reloading = false; + 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. + */ + async reload() { + if (!this.el.isConnected) { + this.destroy(); + return; + } + + 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 + // body - which is pat-inject's default. + cfg.target = cfg.target || "self"; + } + + 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; + await this.reload(); + } + } + + 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); + } + 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..1261585a8 --- /dev/null +++ b/src/pat/reload/reload.test.js @@ -0,0 +1,252 @@ +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 - 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"); + + history.pushState(null, "", "/page-1"); + await utils.timeout(1); + history.pushState(null, "", "/page-2"); + await utils.timeout(1); + 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`, + ]); + + 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-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 - 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; + }); + + 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 () => { + 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(); + }); +}); 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";