├── .editorconfig
├── .github
    └── workflows
    │   ├── e2e-tests.yml
    │   ├── npm-publish.yml
    │   ├── redeploy-docs.yml
    │   ├── unit-tests.yml
    │   └── version-update.yml
├── .gitignore
├── .husky
    └── pre-commit
├── .lintstagedrc.js
├── CHANGELOG.md
├── LICENSE
├── README.md
├── package-lock.json
├── package.json
├── src
    ├── SwupFragmentPlugin.ts
    ├── inc
    │   ├── Logger.ts
    │   ├── ParsedRule.ts
    │   ├── defs.ts
    │   ├── env.ts
    │   ├── functions.ts
    │   └── handlers.ts
    └── index.ts
├── tests
    ├── config
    │   ├── playwright.config.ts
    │   ├── playwright.setup.ts
    │   ├── playwright.teardown.ts
    │   ├── serve.json
    │   ├── vitest.config.ts
    │   └── vitest.setup.ts
    ├── fixtures
    │   ├── assets
    │   │   ├── script.js
    │   │   ├── style.css
    │   │   └── transitions.css
    │   ├── detail
    │   │   └── index.html
    │   ├── index.html
    │   └── list
    │   │   ├── filter
    │   │       ├── green
    │   │       │   └── index.html
    │   │       └── red
    │   │       │   └── index.html
    │   │   └── index.html
    ├── playwright
    │   ├── fragment-plugin.spec.ts
    │   └── inc
    │   │   └── commands.ts
    ├── prepare.js
    └── vitest
    │   ├── ParsedRule.test.ts
    │   ├── adjustVisitScroll.test.ts
    │   ├── cloneRules.test.ts
    │   ├── dedupe.test.ts
    │   ├── exports.test.ts
    │   ├── getFragmentVisit.test.ts
    │   ├── getFragmentVisitContainers.test.ts
    │   ├── getRoute.test.ts
    │   ├── handlePageView.test.ts
    │   ├── inc
    │       └── helpers.ts
    │   ├── modifyRules.test.ts
    │   ├── normalizeUrl.test.ts
    │   ├── queryFragmentElement.test.ts
    │   ├── shouldSkipAnimation.test.ts
    │   └── toggleFragmentVisitClass.test.ts
└── tsconfig.json


/.editorconfig:
--------------------------------------------------------------------------------
 1 | root = true
 2 | 
 3 | [*]
 4 | charset = utf-8
 5 | end_of_line = lf
 6 | trim_trailing_whitespace = true
 7 | insert_final_newline = true
 8 | max_line_length = 100
 9 | 
10 | [*.{js,mjs,ts}]
11 | indent_style = tab
12 | indent_size = 4
13 | 
14 | [*.{json,md,yaml,yml}]
15 | indent_style = space
16 | indent_size = 2
17 | 
18 | [*.md]
19 | trim_trailing_whitespace = false
20 | 


--------------------------------------------------------------------------------
/.github/workflows/e2e-tests.yml:
--------------------------------------------------------------------------------
 1 | name: E2E tests
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: [main, next]
 6 |   pull_request:
 7 |   workflow_dispatch:
 8 | 
 9 | jobs:
10 |   run-tests:
11 |     name: E2E tests
12 |     runs-on: ubuntu-latest
13 |     timeout-minutes: 5
14 | 
15 |     steps:
16 |       - name: Check out repo
17 |         uses: actions/checkout@v3
18 | 
19 |       - name: Set up node
20 |         uses: actions/setup-node@v3
21 |         with:
22 |           node-version: 18
23 | 
24 |       - run: npm ci
25 |       - run: npm run build
26 |       - run: npx playwright install --with-deps
27 | 
28 |       - name: Run tests
29 |         run: npx playwright test --config ./tests/config/playwright.config.ts
30 | 
31 |       - uses: daun/playwright-report-summary@v2
32 |         with:
33 |           report-file: playwright-results.json
34 | 


--------------------------------------------------------------------------------
/.github/workflows/npm-publish.yml:
--------------------------------------------------------------------------------
 1 | # This workflow publishes a package to NPM
 2 | 
 3 | name: Publish package
 4 | 
 5 | on:
 6 |   release:
 7 |     types: [published]
 8 | 
 9 | jobs:
10 |   publish-npm:
11 |     runs-on: ubuntu-latest
12 |     steps:
13 |       - uses: actions/checkout@v3
14 |       - uses: actions/setup-node@v3
15 |         with:
16 |           node-version: 16
17 |           registry-url: https://registry.npmjs.org
18 |       - run: npm ci
19 |       - run: npm publish --access public
20 |         env:
21 |           NODE_AUTH_TOKEN: ${{secrets.npm_token}}
22 | 


--------------------------------------------------------------------------------
/.github/workflows/redeploy-docs.yml:
--------------------------------------------------------------------------------
 1 | name: Redeploy Docs
 2 | on:
 3 |   push:
 4 |     branches: [main]
 5 | 
 6 | jobs:
 7 |   redeploy-docs:
 8 |     uses: swup/.github/.github/workflows/redeploy-docs.yml@main
 9 |     secrets: inherit
10 | 


--------------------------------------------------------------------------------
/.github/workflows/unit-tests.yml:
--------------------------------------------------------------------------------
 1 | name: Unit tests
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: [main, next]
 6 |   pull_request:
 7 |   workflow_dispatch:
 8 | 
 9 | jobs:
10 |   run-tests:
11 |     name: Run unit tests
12 |     runs-on: ubuntu-latest
13 |     timeout-minutes: 5
14 | 
15 |     steps:
16 |       - name: Check out repo
17 |         uses: actions/checkout@v3
18 | 
19 |       - name: Set up node
20 |         uses: actions/setup-node@v3
21 |         with:
22 |           node-version: 18
23 | 
24 |       - run: npm ci
25 |       - run: npm run build
26 | 
27 |       - name: Run tests
28 |         run: npm run test:unit
29 | 


--------------------------------------------------------------------------------
/.github/workflows/version-update.yml:
--------------------------------------------------------------------------------
 1 | # This workflow bumps the package.json version and creates a PR
 2 | 
 3 | name: Update package version
 4 | 
 5 | on:
 6 |   workflow_dispatch:
 7 |     inputs:
 8 |       segment:
 9 |         description: 'Semver segment to update'
10 |         required: true
11 |         default: 'patch'
12 |         type: choice
13 |         options:
14 |         - minor
15 |         - patch
16 | 
17 | jobs:
18 |   update-version:
19 |     name: Update package version
20 |     runs-on: ubuntu-latest
21 |     steps:
22 |       - uses: actions/checkout@v2
23 |       - uses: actions/setup-node@v2
24 |         with:
25 |           node-version: 16
26 |       - run: echo "Updating ${{ inputs.segment }} version"
27 |       - name: Update version
28 |         run: npm --no-git-tag-version version ${{ inputs.segment }}
29 |       - uses: peter-evans/create-pull-request@v4
30 |         with:
31 |           base: main
32 |           branch: 'version/automated'
33 |           title: 'Update package version (automated)'
34 |           commit-message: 'Update package version'
35 |           body: 'Automated update to ${{ inputs.segment }} version'
36 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | .DS_Store
 2 | *.DS_Store
 3 | node_modules
 4 | Thumbs.db
 5 | .idea
 6 | dist
 7 | *.tgz
 8 | src/packages
 9 | 
10 | # Testing tools and outputs
11 | /tests/reports/
12 | /tests/results/
13 | /tests/fixtures/dist/
14 | /playwright/.cache/
15 | /playwright-report/
16 | /coverage
17 | .nyc_output
18 | report.json
19 | 


--------------------------------------------------------------------------------
/.husky/pre-commit:
--------------------------------------------------------------------------------
1 | npx lint-staged
2 | 


--------------------------------------------------------------------------------
/.lintstagedrc.js:
--------------------------------------------------------------------------------
1 | export default {
2 | 	'**/*.{js,ts,mjs,cjs,md,html}': ['prettier --write']
3 | };
4 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # Changelog
  2 | 
  3 | ## [1.1.2] - 2025-05-30
  4 | 
  5 | - Only move `<dialog>` elements with an `[open]` attribute to the top layer
  6 | 
  7 | ## [1.1.1] - 2024-06-01
  8 | 
  9 | - Optimize logic of persisting fragment elements
 10 | - Optimize API usage of `getFragmentVisit`
 11 | 
 12 | ## [1.1.0] - 2024-05-29
 13 | 
 14 | - Match rules conditionally: [`rule.if`](https://swup.js.org/plugins/fragment-plugin/#rule-if)
 15 | 
 16 | ## [1.0.2] - 2024-05-21
 17 | 
 18 | - always update the `href` of `a[data-swup-link-to-fragment]`, even if it's the current URL
 19 | 
 20 | ## [1.0.1] - 2024-03-26
 21 | 
 22 | - Compatibility with swup 4.6.0
 23 | 
 24 | ## [1.0.0] - 2024-01-28
 25 | 
 26 | - Version 1.0.0 🍾
 27 | 
 28 | ## [0.3.7] - 2023-11-14
 29 | 
 30 | - Add playwright tests
 31 | 
 32 | ## [0.3.6] - 2023-11-13
 33 | 
 34 | - Prevent `<dialog>` fragments from being closed if pressing the <kbd>Escape</kbd> key
 35 | 
 36 | ## [0.3.5] - 2023-11-11
 37 | 
 38 | - New [API methods](https://github.com/swup/fragment-plugin#api-methods):
 39 |   - `getFragmentVisit()`
 40 |   - `prependRule()`
 41 |   - `appendRule()`
 42 |   - `getRules()`
 43 |   - `setRules()`
 44 | - Add vitest tests for many functions
 45 | 
 46 | ## [0.3.4] - 2023-10-15
 47 | 
 48 | - Ignore fragment elements that are not children of swup's default `containers`
 49 | 
 50 | ## [0.3.3] - 2023-10-05
 51 | 
 52 | - Refactor exports
 53 | - Ensure all type definitions make it into `/dist`
 54 | - Fix return type of `swup.getFragmentVisit()`
 55 | 
 56 | ## [0.3.2] - 2023-09-26
 57 | 
 58 | - Use `@swup/cli` for bundling
 59 | 
 60 | ## [0.3.1] - 2023-09-25
 61 | 
 62 | - Ignore fragment rules where any of the `containers` doesn't return a match
 63 | 
 64 | ## [0.3.0] - 2023-09-07
 65 | 
 66 | - Make `visit.a11y.focus` adjustable
 67 | 
 68 | ## [0.2.6] - 2023-08-09
 69 | 
 70 | - Support for fragment visits to the current URL (handy for @swup/fragment-plugin)
 71 | 
 72 | ## [0.2.5] - 2023-08-04
 73 | 
 74 | - simplify `visit.fragmentVisit` #35
 75 | - new option `rule.scroll` #36
 76 | 
 77 | ## [0.2.4] - 2023-07-31
 78 | 
 79 | - Optimize exported types
 80 | 
 81 | ## [0.2.3] - 2023-07-28
 82 | 
 83 | - Sort the `"exports"` field in package.json in the recommended way
 84 | 
 85 | ## [0.2.2] - 2023-07-28
 86 | 
 87 | - use an `interface` for augmenting swup, so that multiple plugins can augment it
 88 | 
 89 | ## [0.2.1] - 2023-07-26
 90 | 
 91 | - Initial Release
 92 | 
 93 | [1.1.2]: https://github.com/swup/fragment-plugin/releases/tag/1.1.2
 94 | [1.1.1]: https://github.com/swup/fragment-plugin/releases/tag/1.1.1
 95 | [1.1.0]: https://github.com/swup/fragment-plugin/releases/tag/1.1.0
 96 | [1.0.2]: https://github.com/swup/fragment-plugin/releases/tag/1.0.2
 97 | [1.0.1]: https://github.com/swup/fragment-plugin/releases/tag/1.0.1
 98 | [1.0.0]: https://github.com/swup/fragment-plugin/releases/tag/1.0.0
 99 | [0.3.7]: https://github.com/swup/fragment-plugin/releases/tag/0.3.7
100 | [0.3.6]: https://github.com/swup/fragment-plugin/releases/tag/0.3.6
101 | [0.3.5]: https://github.com/swup/fragment-plugin/releases/tag/0.3.5
102 | [0.3.4]: https://github.com/swup/fragment-plugin/releases/tag/0.3.4
103 | [0.3.3]: https://github.com/swup/fragment-plugin/releases/tag/0.3.3
104 | [0.3.2]: https://github.com/swup/fragment-plugin/releases/tag/0.3.2
105 | [0.3.1]: https://github.com/swup/fragment-plugin/releases/tag/0.3.1
106 | [0.3.0]: https://github.com/swup/fragment-plugin/releases/tag/0.3.0
107 | [0.2.6]: https://github.com/swup/fragment-plugin/releases/tag/0.2.6
108 | [0.2.5]: https://github.com/swup/fragment-plugin/releases/tag/0.2.5
109 | [0.2.4]: https://github.com/swup/fragment-plugin/releases/tag/0.2.4
110 | [0.2.3]: https://github.com/swup/fragment-plugin/releases/tag/0.2.3
111 | [0.2.2]: https://github.com/swup/fragment-plugin/releases/tag/0.2.2
112 | [0.2.1]: https://github.com/swup/fragment-plugin/releases/tag/0.2.1
113 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2023 Rasso Hilber<mail@rassohilber.com>
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Swup Fragment Plugin
  2 | 
  3 | <div class="shields">
  4 | 
  5 | <!--[![npm version](https://img.shields.io/npm/v/@swup/fragment-plugin.svg)](https://www.npmjs.com/package/@swup/fragment-plugin) -->
  6 | 
  7 | [![Unit Tests](https://img.shields.io/github/actions/workflow/status/swup/fragment-plugin/unit-tests.yml?branch=main&label=vitest)](https://github.com/swup/fragment-plugin/actions/workflows/unit-tests.yml)
  8 | [![E2E Tests](https://img.shields.io/github/actions/workflow/status/swup/fragment-plugin/e2e-tests.yml?branch=main&label=playwright)](https://github.com/swup/fragment-plugin/actions/workflows/e2e-tests.yml)
  9 | [![License](https://img.shields.io/github/license/swup/fragment-plugin.svg)](https://github.com/swup/fragment-plugin/blob/main/LICENSE)
 10 | 
 11 | </div>
 12 | 
 13 | A [swup](https://swup.js.org) plugin for dynamically replacing containers based on rules 🧩
 14 | 
 15 | - Selectively replace containers instead of the main swup containers, based on custom rules
 16 | - Improve orientation by animating only the parts of the page that have actually changed
 17 | - Give your site the polish and snappiness of a single-page app
 18 | 
 19 | ## Use cases
 20 | 
 21 | All of the following scenarios require updating only a small content fragment instead of
 22 | performing a full page transition:
 23 | 
 24 | - a filter UI that live-updates its list of results on every interaction
 25 | - a detail overlay that shows on top of the currently open content
 26 | - a tab group that should update only itself when selecting one of the tabs
 27 | 
 28 | If you are looking for selectively replacing forms on submission, you should have a look at
 29 | [Forms Plugin](https://swup.js.org/plugins/forms-plugin/#inline-forms).
 30 | 
 31 | ## Demo
 32 | 
 33 | See the plugin in action in [this interactive demo](https://swup-fragment-plugin.netlify.app)
 34 | 
 35 | <div data-video data-screencast>
 36 | 
 37 | https://github.com/swup/fragment-plugin/assets/869813/ecaf15d7-ec72-43e8-898a-64f61330c6f5
 38 | 
 39 | </div>
 40 | 
 41 | ## Table of contents
 42 | 
 43 | - [Installation](#installation)
 44 | - [How it works](#how-it-works)
 45 | - [Example](#example)
 46 | - [Options](#options)
 47 | - [How rules are matched](#how-rules-are-matched)
 48 | - [How fragment containers are found](#how-fragment-containers-are-found)
 49 | - [Advanced use cases](#advanced-use-cases)
 50 | - [Skip animations using `<template>`](#skip-animations-using-template)
 51 | - [API Methods](#api-methods)
 52 | 
 53 | ## Installation
 54 | 
 55 | Install the plugin from npm and import it into your bundle.
 56 | 
 57 | ```bash
 58 | npm install @swup/fragment-plugin
 59 | ```
 60 | 
 61 | ```js
 62 | import SwupFragmentPlugin from '@swup/fragment-plugin';
 63 | ```
 64 | 
 65 | Or include the minified production file from a CDN:
 66 | 
 67 | ```html
 68 | <script src="https://unpkg.com/@swup/fragment-plugin@1"></script>
 69 | ```
 70 | 
 71 | ## How it works
 72 | 
 73 | When a visit is determined to be a fragment visit, the plugin will:
 74 | 
 75 | - **update only** the contents of the elements matching the rule's `containers`
 76 | - **not update** the default [containers](https://swup.js.org/options/#containers) replaced on all other visits
 77 | - **wait** for CSS transitions on those fragment elements using [scoped animations](https://swup.js.org/options/#animation-scope)
 78 | - **preserve** the current scroll position upon navigation
 79 | - add a `to-[name]` class to the elements if the current `rule` has a `name` key
 80 | - **ignore** elements that already match the current visit's URL
 81 | 
 82 | ## Example
 83 | 
 84 | ### Content filter: only update a list of results
 85 | 
 86 | Imagine a website with a `/users/` page that displays a list of users. Above the user list, there
 87 | is a filter UI to choose which users to display. Selecting a filter will trigger a visit
 88 | to the narrowed-down user list at `/users/filter/x/`. The only part that has changed is the
 89 | list of users, so that's what we'd like to replace and animate instead of the whole content
 90 | container.
 91 | 
 92 | ```html
 93 | <body>
 94 |   <header>Website</header>
 95 |   <main id="swup" class="transition-main" class="transition-main">
 96 |     <h1>Users</h1>
 97 |     <!-- A list of filters for the users: selecting one will update the list below -->
 98 |     <ul>
 99 |       <a href="/users/filter/1/">Filter 1</a>
100 |       <a href="/users/filter/2/">Filter 2</a>
101 |       <a href="/users/filter/3/">Filter 2</a>
102 |     </ul>
103 |     <!-- The list of users, filtered by the criteria above -->
104 |     <ul id="users">
105 |       <li><a href="/user/1/">User 1</a></li>
106 |       <li><a href="/user/2/">User 2</a></li>
107 |       <li><a href="/user/3/">User 3</a></li>
108 |     </ul>
109 |   </main>
110 | </body>
111 | ```
112 | 
113 | Using Fragment Plugin, we can update **only** the `#users` list when clicking one of the filters.
114 | The plugin expects an array of rules to recognize and handle fragment visits:
115 | 
116 | ```js
117 | const swup = new Swup({
118 |   plugins: [
119 |     new SwupFragmentPlugin({
120 |       rules: [
121 |         {
122 |           from: '/users/:filter?',
123 |           to: '/users/:filter?',
124 |           containers: ['#users']
125 |         }
126 |       ]
127 |     })
128 |   ]
129 | });
130 | ```
131 | 
132 | Now we can add custom animations for our fragment rule:
133 | 
134 | ```css
135 | /*
136 | * The default animation, for visits without matching fragment rules
137 | */
138 | html.is-changing .transition-main {
139 |   transition: opacity 250ms;
140 |   opacity: 1;
141 | }
142 | html.is-animating .transition-main {
143 |   opacity: 0;
144 | }
145 | 
146 | /*
147 | * The animation when filtering users
148 | */
149 | #users.is-changing {
150 |   transition: opacity 250ms;
151 | }
152 | #users.is-animating {
153 |   opacity: 0;
154 | }
155 | ```
156 | 
157 | ## Options
158 | 
159 | ```ts
160 | /** A path to match URLs against */
161 | type Path = string | RegExp | Array<string | RegExp>;
162 | 
163 | /** A fragment rule */
164 | export type Rule = {
165 |   from: Path;
166 |   to: Path;
167 |   containers: string[];
168 |   name?: string;
169 |   scroll?: boolean | string;
170 |   focus?: boolean | string;
171 |   if?: Predicate;
172 | };
173 | 
174 | /** The plugin options */
175 | export type Options = {
176 |   rules: Rule[];
177 |   debug?: boolean;
178 | };
179 | ```
180 | 
181 | ### `rules`
182 | 
183 | The rules that define whether a visit will be considered a fragment visit. Each rule consists of
184 | mandatory `from` and `to` URL paths, an array of selectors `containers`, as well as an optional
185 | `name` of this rule to allow scoped styling.
186 | 
187 | The rule's `from`/`to` paths are converted to a regular expression by [path-to-regexp](https://github.com/pillarjs/path-to-regexp) and matched against the current browser URL. If you want to create an either/or path, you can also provide an array of paths, for example:
188 | 
189 | ```js
190 | {
191 |   rules: [
192 |     {
193 |       from: ['/users', '/users/:filter?'],
194 |       to: ['/users', '/users/:filter?'],
195 |       containers: ['#user-list']
196 |     }
197 |   ];
198 | }
199 | ```
200 | 
201 | #### `rule.from`
202 | 
203 | Required, Type: `string | string[]` – The path(s) to match against the previous URL
204 | 
205 | #### `rule.to`
206 | 
207 | Required, Type: `string | string[]` – The path(s) to match against the next URL
208 | 
209 | #### `rule.containers`
210 | 
211 | Required, Type: `string[]` – Selectors of containers to be replaced if the visit matches.
212 | 
213 | **Notes**
214 | 
215 | - **only IDs and no nested selectors are allowed**. `#my-element` is valid, while
216 |   `.my-element` or `#wrap #child` both will throw an error.
217 | - if **any** of the selectors in `containers` doesn't return a match in the current document, the rule will be skipped.
218 | - Fragment elements **must either match a swup container or be a descendant of one of them**
219 | 
220 | #### `rule.name`
221 | 
222 | Optional, Type: `string` – A name for this rule to allow scoped styling, ideally in `kebab-case`
223 | 
224 | #### `rule.scroll`
225 | 
226 | Optional, Type: `boolean | string` – By default, scrolling will be disabled for fragment visits.
227 | Using this option, you can re-enable it for selected visits:
228 | 
229 | - `true` will scroll to the top
230 | - `'#my-element'` will scroll to the first element matching the selector
231 | 
232 | #### `rule.focus`
233 | 
234 | Optional, Type: `boolean | string` – If you have [Accessibility Plugin](https://github.com/swup/a11y-plugin/) installed, you can adjust which element to focus for the visit [as described here](https://github.com/swup/a11y-plugin/#visita11yfocus).
235 | 
236 | #### `rule.if`
237 | 
238 | Optional, Type: `(visit) => boolean` – A predicate function that allows for fine-grained control over the matching behavior of a rule. The function receives the current [visit](https://swup.js.org/visit/) as a parameter. If the function returns `false`, the related rule is being skipped for the current visit, even if it matches the current route.
239 | 
240 | ### `debug`
241 | 
242 | Optional, Type: `boolean`, Default `false`. Set to `true` for debug information in the console.
243 | 
244 | ```js
245 | {
246 |   debug: true;
247 | }
248 | ```
249 | 
250 | > [!IMPORTANT] to keep the bundle size small, UMD builds are stripped from all debug messages, so `debug` won't have an effect there.
251 | 
252 | ## How rules are matched
253 | 
254 | - The first matching rule in your `rules` array will be used for the current visit
255 | - If no rule matches the current visit, the default content containers defined in swup's options will be replaced
256 | 
257 | ## How fragment containers are found
258 | 
259 | - The `containers` of the matching rule **need to be shared between the current and the incoming document**
260 | - For each selector in the `containers` array, the **first** matching element in the DOM will be selected
261 | - If a visit isn't be considered a reload of the current page, fragment elements that already match the new URL will be ignored
262 | 
263 | ## Advanced use cases
264 | 
265 | Creating the rules for your fragment visits should be enough to enable dynamic updates on most
266 | sites. However, there are some advanced use cases that require adding certain attributes to the
267 | fragment elements themselves or to links on the page. These tend to be situations where **modal dialogs** are involved and swup doesn't know which page the modal was opened from.
268 | 
269 | ### Fragment URL
270 | 
271 | Use the `data-swup-fragment-url` attribute to uniquely identify fragment elements.
272 | 
273 | In scenarios where a modal is rendered on top of other content, leaving or closing the modal to
274 | the same URL it was opened from should ideally not update the content behind it as
275 | nothing has changed. Fragment plugin will normally do that by keeping track of URLs. However,
276 | when swup was initialized on a subpage with an already-visible modal, the plugin doesn't know which URL the content behind it corresponds to. Hence, we need to tell swup manually so it can persist content when closing the modal.
277 | 
278 | ```diff
279 | <!-- the modal -->
280 | <dialog open id="modal">
281 |   <main>
282 |     <h1>User 1</h1>
283 |     <p>Lorem ipsum dolor sit amet...</p>
284 |   </main>
285 | </dialog>
286 | <!-- the content behind the modal -->
287 | <main>
288 |   <section
289 |     id="list"
290 | +   data-swup-fragment-url="/users/"
291 |     >
292 |     <ul>
293 |       <li>User 1</li>
294 |       <li>User 2</li>
295 |       <li>User 3</li>
296 |     </ul>
297 |   </section>
298 | </main>
299 | ```
300 | 
301 | ### Link to another fragment
302 | 
303 | Use the `data-swup-link-to-fragment` attribute to automatically update links pointing to a fragment.
304 | 
305 | Consider again an overlay rendered on top of other content. To implement a close button for that
306 | overlay, we could ideally point a link at the URL of the content where the overlay is closed. The
307 | fragment plugin will then handle the animation and replacing of the overlay. However, knowing
308 | where to point that link requires knowing where the current overlay was opened from.
309 | 
310 | `data-swup-link-to-fragment` automates that by keeping the `href` attribute of a link in sync with the currently
311 | tracked URL of the fragment matching the selector provided by the attribute. The code below will make sure the close button will always point at the last known URL of the `#list` fragment to allow seamlessly closing the overlay:
312 | 
313 | ```diff
314 | <dialog open id="modal">
315 |   <main>
316 |     <!-- `href` will be synced to the fragment URL of #list at runtime: -->
317 | +   <a href="" data-swup-link-to-fragment="#list">Close</a>
318 |     <h1>User 1</h1>
319 |     <p>Lorem ipsum dolor sit amet...</p>
320 |   </main>
321 | </dialog>
322 | <main>
323 |   <section id="list"
324 |     data-swup-fragment-url="/users/">
325 |     <ul>
326 |       <li>User 1</li>
327 |       <li>User 2</li>
328 |       <li>User 3</li>
329 |     </ul>
330 |   </section>
331 | </main>
332 | ```
333 | 
334 | > [!TIP]
335 | > To keep your markup semantic and accessible, we recommend you **always provide a default value**
336 | > for the link's `href` attribute, even though it will be updated automatically at runtime:
337 | 
338 | ```diff
339 | <a
340 | + href="/users/"
341 |   data-swup-link-to-fragment="#list">Close</a>
342 | ```
343 | 
344 | ## Skip animations using `<template>`
345 | 
346 | If all elements of a visit are `<template>` elements, the `out`/`in`-animation will automatically be skipped. This can come in handy for modals:
347 | 
348 | ```js
349 | {
350 |   from: '/overview/',
351 |   to: '/detail/:id',
352 |   containers: ['#modal']
353 | },
354 | {
355 |   from: '/detail/:id',
356 |   to: '/overview/',
357 |   containers: ['#modal']
358 | }
359 | ```
360 | 
361 | ```html
362 | <!-- /overview/: provide a <template> as a placeholder for the modal -->
363 | <template id="modal"></template>
364 | <main>
365 |   <ul>
366 |     <!-- list of items that will open in the #modal -->
367 |   </ul>
368 | </main>
369 | ```
370 | 
371 | ```html
372 | <!-- /detail/1 -->
373 | <dialog open id="modal">
374 |   <main>
375 |     <h1>Detail 1</h1>
376 |   </main>
377 | </dialog>
378 | <main>
379 |   <ul>
380 |     <!-- list of items that will open in the #modal -->
381 |   </ul>
382 | </main>
383 | ```
384 | 
385 | > [!TIP]
386 | > Fragment Plugin will detect `<dialog open>`-fragment elements automatically on every page view and
387 | > move them to the [top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer)
388 | > automatically. This has the benefit of simplified accesssiblity handling and styling.
389 | 
390 | ## API methods
391 | 
392 | Fragment plugin provides a few API functions for advanced use cases. To be able to access those, you'll need to keep a reference to the plugin during instanciation:
393 | 
394 | ```js
395 | const fragmentPlugin = new SwupFragmentPlugin({ rules });
396 | const swup = new Swup({ plugins: [fragmentPlugin] });
397 | /** You can now call the plugin's public API, for example: */
398 | fragmentPlugin.getFragmentVisit(route);
399 | ```
400 | 
401 | ### `getFragmentVisit(route)`
402 | 
403 | Get information about the fragment visit for a given route. Returns either `FragmentVisit` or `undefined`.
404 | 
405 | ```js
406 | /**
407 |  * Get information about which containers will
408 |  * be replaced when hovering over links:
409 |  */
410 | document.querySelectorAll('a[href]').forEach((el) => {
411 |   el.addEventListener('mouseenter', () => {
412 |     const fragmentVisit = fragmentPlugin.getFragmentVisit({
413 |       from: window.location.href, // the current URL
414 |       to: el.href // the URL of the link
415 |     });
416 |     console.log(`will replace ${fragmentVisit?.containers || swup.options.containers}`);
417 |   });
418 | });
419 | ```
420 | 
421 | ### `prependRule(rule)`
422 | 
423 | Prepends a [rule](#type-signature-rule) to the array of rules.
424 | 
425 | ```js
426 | fragmentPlugin.prependRule({ from: '/foo/', to: '/bar/', containers: ['#foobar'] });
427 | ```
428 | 
429 | ### `appendRule(rule)`
430 | 
431 | Appends a [rule](#type-signature-rule) to the array of rules.
432 | 
433 | ```js
434 | fragmentPlugin.prependRule({ from: '/baz/', to: '/bat/', containers: ['#bazbat'] });
435 | ```
436 | 
437 | ### `getRules()`
438 | 
439 | Get a **clone** of all registered fragment rules
440 | 
441 | ```js
442 | console.log(fragmentPlugin.getRules());
443 | ```
444 | 
445 | ### `setRules(rules)`
446 | 
447 | Overwrite all fragment rules with the provided rules. This methods provides the lowest-level access to the rules. For example, you could use it to remove all rules with the name `foobar`:
448 | 
449 | ```js
450 | fragmentPlugin.setRules(fragmentPlugin.getRules().filter((rule) => rule.name !== 'foobar'));
451 | ```
452 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@swup/fragment-plugin",
 3 |   "amdName": "SwupFragmentPlugin",
 4 |   "version": "1.1.2",
 5 |   "description": "A swup plugin for dynamically replacing containers based on rules",
 6 |   "type": "module",
 7 |   "source": "src/index.ts",
 8 |   "main": "./dist/index.cjs",
 9 |   "module": "./dist/index.module.js",
10 |   "unpkg": "./dist/index.umd.js",
11 |   "types": "./dist/index.d.ts",
12 |   "exports": {
13 |     ".": {
14 |       "types": "./dist/index.d.ts",
15 |       "import": "./dist/index.modern.js",
16 |       "require": "./dist/index.cjs"
17 |     }
18 |   },
19 |   "author": {
20 |     "name": "Rasso Hilber",
21 |     "email": "mail@rassohilber.com",
22 |     "url": "https://rassohilber.com"
23 |   },
24 |   "contributors": [
25 |     {
26 |       "name": "Philipp Daun",
27 |       "email": "daun@daun.ltd",
28 |       "url": "https://philippdaun.net"
29 |     }
30 |   ],
31 |   "files": [
32 |     "dist",
33 |     "src"
34 |   ],
35 |   "scripts": {
36 |     "prepare": "husky",
37 |     "build": "swup package:build",
38 |     "dev": "swup package:dev",
39 |     "lint": "swup package:lint",
40 |     "format": "swup package:format",
41 |     "prepublishOnly": "npm run build",
42 |     "test": "npm run test:unit && npm run test:e2e",
43 |     "test:unit": "vitest run --config ./tests/config/vitest.config.ts",
44 |     "test:unit:watch": "vitest --config ./tests/config/vitest.config.ts",
45 |     "test:e2e": "npx playwright test --config ./tests/config/playwright.config.ts",
46 |     "test:e2e:dev": "npx playwright test --ui --config ./tests/config/playwright.config.ts",
47 |     "test:e2e:serve": "./tests/prepare.js && npx serve -n -S -L -p 8274 --config ./tests/config/serve.json"
48 |   },
49 |   "license": "MIT",
50 |   "repository": {
51 |     "type": "git",
52 |     "url": "https://github.com/swup/fragment-plugin.git"
53 |   },
54 |   "dependencies": {
55 |     "@swup/plugin": "^4.0.0"
56 |   },
57 |   "devDependencies": {
58 |     "@playwright/test": "^1.39.0",
59 |     "@swup/cli": "^5.0.2",
60 |     "@types/jsdom": "^21.1.4",
61 |     "husky": "^9.0.11",
62 |     "jsdom": "^22.1.0",
63 |     "lint-staged": "^15.2.2",
64 |     "serve": "^14.2.1",
65 |     "vitest": "^0.34.6"
66 |   },
67 |   "peerDependencies": {
68 |     "swup": "^4.6.0"
69 |   },
70 |   "browserslist": [
71 |     "extends @swup/browserslist-config"
72 |   ],
73 |   "prettier": "@swup/prettier-config"
74 | }
75 | 


--------------------------------------------------------------------------------
/src/SwupFragmentPlugin.ts:
--------------------------------------------------------------------------------
  1 | import PluginBase from '@swup/plugin';
  2 | import ParsedRule from './inc/ParsedRule.js';
  3 | import Logger from './inc/Logger.js';
  4 | import {
  5 | 	handlePageView,
  6 | 	cleanupFragmentElements,
  7 | 	getFirstMatchingRule,
  8 | 	getFragmentVisitContainers,
  9 | 	cloneRules
 10 | } from './inc/functions.js';
 11 | import type { Options, Rule, Route, FragmentVisit } from './inc/defs.js';
 12 | import * as handlers from './inc/handlers.js';
 13 | import { __DEV__ } from './inc/env.js';
 14 | import type { Visit } from 'swup';
 15 | 
 16 | type RequireKeys<T, K extends keyof T> = Partial<T> & Pick<T, K>;
 17 | type InitOptions = RequireKeys<Options, 'rules'>;
 18 | 
 19 | /**
 20 |  * The main plugin class
 21 |  */
 22 | export default class SwupFragmentPlugin extends PluginBase {
 23 | 	readonly name = 'SwupFragmentPlugin';
 24 | 	readonly requires = { swup: '>=4.6' };
 25 | 
 26 | 	protected _rawRules: Rule[] = [];
 27 | 	protected _parsedRules: ParsedRule[] = [];
 28 | 
 29 | 	get parsedRules() {
 30 | 		return this._parsedRules;
 31 | 	}
 32 | 
 33 | 	options: Options;
 34 | 
 35 | 	protected defaults: Options = {
 36 | 		rules: [],
 37 | 		debug: false
 38 | 	};
 39 | 
 40 | 	logger?: Logger;
 41 | 
 42 | 	/**
 43 | 	 * Plugin Constructor
 44 | 	 * The options are NOT optional and need to contain at least a `rules` property
 45 | 	 */
 46 | 	constructor(options: InitOptions) {
 47 | 		super();
 48 | 		this.options = { ...this.defaults, ...options };
 49 | 	}
 50 | 
 51 | 	/**
 52 | 	 * Runs when the plugin is being mounted
 53 | 	 */
 54 | 	mount() {
 55 | 		const swup = this.swup;
 56 | 
 57 | 		this.setRules(this.options.rules);
 58 | 		if (__DEV__) {
 59 | 			if (this.options.debug) this.logger = new Logger();
 60 | 		}
 61 | 
 62 | 		this.before('link:self', handlers.onLinkToSelf);
 63 | 		this.on('visit:start', handlers.onVisitStart);
 64 | 		this.before('animation:out:await', handlers.maybeSkipOutAnimation);
 65 | 		this.before('animation:in:await', handlers.maybeSkipInAnimation);
 66 | 		this.before('content:replace', handlers.beforeContentReplace);
 67 | 		this.on('content:replace', handlers.onContentReplace);
 68 | 		this.on('visit:end', handlers.onVisitEnd);
 69 | 
 70 | 		if (__DEV__) {
 71 | 			this.logger?.warnIf(
 72 | 				!swup.options.cache,
 73 | 				`fragment caching will only work with swup's cache being active`
 74 | 			);
 75 | 		}
 76 | 
 77 | 		handlePageView(this);
 78 | 	}
 79 | 
 80 | 	/**
 81 | 	 * Runs when the plugin is being unmounted
 82 | 	 */
 83 | 	unmount() {
 84 | 		super.unmount();
 85 | 		cleanupFragmentElements();
 86 | 	}
 87 | 
 88 | 	/**
 89 | 	 * Set completely new rules
 90 | 	 *
 91 | 	 * @access public
 92 | 	 */
 93 | 	setRules(rules: Rule[]) {
 94 | 		this._rawRules = cloneRules(rules);
 95 | 		this._parsedRules = rules.map((rule) => this.parseRule(rule));
 96 | 		if (__DEV__) this.logger?.log('Updated fragment rules', this.getRules());
 97 | 	}
 98 | 
 99 | 	/**
100 | 	 * Get a clone of the current rules
101 | 	 *
102 | 	 * @access public
103 | 	 */
104 | 	getRules() {
105 | 		return cloneRules(this._rawRules);
106 | 	}
107 | 
108 | 	/**
109 | 	 * Prepend a rule to the existing rules
110 | 	 *
111 | 	 * @access public
112 | 	 */
113 | 	prependRule(rule: Rule) {
114 | 		this.setRules([rule, ...this.getRules()]);
115 | 	}
116 | 
117 | 	/**
118 | 	 * Append a rule to the existing rules
119 | 	 *
120 | 	 * @access public
121 | 	 */
122 | 	appendRule(rule: Rule) {
123 | 		this.setRules([...this.getRules(), rule]);
124 | 	}
125 | 
126 | 	/**
127 | 	 * Parse a rule (for e.g. debugging)
128 | 	 *
129 | 	 * @access public
130 | 	 */
131 | 	parseRule(rule: Rule): ParsedRule {
132 | 		return new ParsedRule({
133 | 			...rule,
134 | 			logger: this.logger,
135 | 			swup: this.swup
136 | 		});
137 | 	}
138 | 
139 | 	/**
140 | 	 * Get the fragment visit object for a given route
141 | 	 *
142 | 	 * @access public
143 | 	 */
144 | 	getFragmentVisit(route: Route, visit?: Visit): FragmentVisit | undefined {
145 | 		const rule = getFirstMatchingRule(
146 | 			route,
147 | 			this.parsedRules,
148 | 			// @ts-expect-error createVisit is protected
149 | 			visit || this.swup.createVisit(route)
150 | 		);
151 | 
152 | 		// Bail early if no rule matched
153 | 		if (!rule) return;
154 | 
155 | 		// Get containers that should be replaced for this visit
156 | 		const containers = getFragmentVisitContainers(
157 | 			route,
158 | 			rule.containers,
159 | 			this.swup,
160 | 			this.logger
161 | 		);
162 | 
163 | 		/** Bail early if there are no fragment elements found for this visit */
164 | 		if (!containers.length) {
165 | 			return;
166 | 		}
167 | 
168 | 		// Pick properties from the current rule that should be projected into the fragmentVisit object
169 | 		const { name, scroll, focus } = rule;
170 | 
171 | 		const fragmentVisit: FragmentVisit = {
172 | 			containers,
173 | 			name,
174 | 			scroll,
175 | 			focus
176 | 		};
177 | 
178 | 		return fragmentVisit;
179 | 	}
180 | }
181 | 


--------------------------------------------------------------------------------
/src/inc/Logger.ts:
--------------------------------------------------------------------------------
 1 | import { __TEST__ } from './env.js';
 2 | /**
 3 |  * Wrap a string in an escape sequence
 4 |  * @see https://stackoverflow.com/a/68373080/586823
 5 |  */
 6 | const wrapInEscapeSequence = (s: string, open: number, close: number): string => {
 7 | 	if (s == null) return s;
 8 | 	return `\x1b[${open}m${String(s)}\x1b[${close}m`;
 9 | };
10 | 
11 | /**
12 |  * Color Codes:
13 |  * @see https://github.com/lzwme/console-log-colors/blob/56a41b352bf9ed327cc864f588b831d92ee6390e/src/index.js
14 |  */
15 | const bold = (s: string): string => wrapInEscapeSequence(s, 1, 22);
16 | const purple = (s: string): string => wrapInEscapeSequence(s, 94, 39);
17 | 
18 | const prepare = (s: string): string => {
19 | 	if (__TEST__) return s;
20 | 	return `🧩 ${bold(s)}`;
21 | };
22 | 
23 | export const highlight = (s: string): string => {
24 | 	if (__TEST__) return s;
25 | 	return purple(s);
26 | };
27 | 
28 | /**
29 |  * A slim wrapper around console statements
30 |  */
31 | export default class Logger {
32 | 	log(...args: any) {
33 | 		const msg = args.shift();
34 | 		console.log(prepare(msg), ...args);
35 | 	}
36 | 	warn(...args: any) {
37 | 		const msg = args.shift();
38 | 		console.warn(prepare(msg), ...args);
39 | 	}
40 | 	error(...args: any) {
41 | 		const msg = args.shift();
42 | 		console.error(prepare(msg), ...args);
43 | 	}
44 | 	logIf(condition: boolean, ...args: any) {
45 | 		if (condition) this.log(...args);
46 | 	}
47 | 	warnIf(condition: boolean, ...args: any) {
48 | 		if (condition) this.warn(...args);
49 | 	}
50 | 	errorIf(condition: boolean, ...args: any) {
51 | 		if (condition) this.error(...args);
52 | 	}
53 | }
54 | 


--------------------------------------------------------------------------------
/src/inc/ParsedRule.ts:
--------------------------------------------------------------------------------
  1 | import { matchPath, classify, Location } from 'swup';
  2 | import type { Swup, Path, Visit } from 'swup';
  3 | import type { Route, Rule, Predicate } from './defs.js';
  4 | import { dedupe, queryFragmentElement } from './functions.js';
  5 | import Logger, { highlight } from './Logger.js';
  6 | import { __DEV__ } from './env.js';
  7 | 
  8 | type Options = Rule & {
  9 | 	swup: Swup;
 10 | 	logger?: Logger;
 11 | };
 12 | 
 13 | /**
 14 |  * Represents a Rule
 15 |  */
 16 | export default class ParsedRule {
 17 | 	readonly matchesFrom: ReturnType<typeof matchPath>;
 18 | 	readonly matchesTo: ReturnType<typeof matchPath>;
 19 | 
 20 | 	swup: Swup;
 21 | 	from: Path;
 22 | 	to: Path;
 23 | 	containers: string[];
 24 | 	name?: string;
 25 | 	scroll: boolean | string = false;
 26 | 	focus?: boolean | string;
 27 | 	logger?: Logger;
 28 | 	if: Predicate = () => true;
 29 | 
 30 | 	constructor(options: Options) {
 31 | 		this.swup = options.swup;
 32 | 		this.logger = options.logger;
 33 | 		this.from = options.from || '';
 34 | 		this.to = options.to || '';
 35 | 
 36 | 		if (options.name) this.name = classify(options.name);
 37 | 		if (typeof options.scroll !== 'undefined') this.scroll = options.scroll;
 38 | 		if (typeof options.focus !== 'undefined') this.focus = options.focus;
 39 | 		if (typeof options.if === 'function') this.if = options.if;
 40 | 
 41 | 		this.containers = this.parseContainers(options.containers);
 42 | 
 43 | 		if (__DEV__) {
 44 | 			this.logger?.errorIf(!this.to, `Every fragment rule must contain a 'to' path`, this);
 45 | 			this.logger?.errorIf(!this.from, `Every fragment rule must contain a 'from' path`, this); // prettier-ignore
 46 | 		}
 47 | 
 48 | 		this.matchesFrom = matchPath(this.from);
 49 | 		this.matchesTo = matchPath(this.to);
 50 | 	}
 51 | 
 52 | 	/**
 53 | 	 * Parse provided fragment containers
 54 | 	 */
 55 | 	parseContainers(rawContainers: string[]): string[] {
 56 | 		if (!Array.isArray(rawContainers) || !rawContainers.length) {
 57 | 			// prettier-ignore
 58 | 			if (__DEV__) this.logger?.error(`Every fragment rule must contain an array of containers`, this.getDebugInfo());
 59 | 			return [];
 60 | 		}
 61 | 		// trim selectors
 62 | 		const containers = dedupe(rawContainers.map((selector) => selector.trim()));
 63 | 		return containers.filter((selector) => {
 64 | 			const result = this.validateSelector(selector);
 65 | 			this.logger?.errorIf(result instanceof Error, result);
 66 | 			return result === true;
 67 | 		});
 68 | 	}
 69 | 
 70 | 	/**
 71 | 	 * Validate a fragment selector
 72 | 	 *
 73 | 	 * - only IDs are allowed
 74 | 	 * - no nested selectors
 75 | 	 */
 76 | 	validateSelector(selector: string): true | Error {
 77 | 		if (!selector.startsWith('#')) {
 78 | 			return new Error(`fragment selectors must be IDs: ${selector}`);
 79 | 		}
 80 | 
 81 | 		if (selector.match(/\s|>/)) {
 82 | 			return new Error(`fragment selectors must not be nested: ${selector}`);
 83 | 		}
 84 | 		return true;
 85 | 	}
 86 | 
 87 | 	/**
 88 | 	 * Get debug info for logging
 89 | 	 */
 90 | 	getDebugInfo() {
 91 | 		const { from, to, containers } = this;
 92 | 		return {
 93 | 			from: String(from),
 94 | 			to: String(to),
 95 | 			containers: String(containers)
 96 | 		};
 97 | 	}
 98 | 
 99 | 	/**
100 | 	 * Checks if a given route matches this rule
101 | 	 */
102 | 	public matches(route: Route, visit: Visit): boolean {
103 | 		if (!this.if(visit)) {
104 | 			if (__DEV__) {
105 | 				this.logger?.log(`ignoring fragment rule due to custom rule.if:`, this);
106 | 			}
107 | 			return false;
108 | 		}
109 | 
110 | 		const { url: fromUrl } = Location.fromUrl(route.from);
111 | 		const { url: toUrl } = Location.fromUrl(route.to);
112 | 
113 | 		const matchesRoute = !!this.matchesFrom(fromUrl) && !!this.matchesTo(toUrl);
114 | 		if (!matchesRoute) return false;
115 | 
116 | 		for (const selector of this.containers) {
117 | 			const result = this.validateFragmentSelectorForMatch(selector);
118 | 			if (result instanceof Error) {
119 | 				if (__DEV__) this.logger?.error(result, this.getDebugInfo());
120 | 				return false;
121 | 			}
122 | 		}
123 | 
124 | 		return true;
125 | 	}
126 | 
127 | 	/**
128 | 	 * Validates a fragment element at runtime when this rule's route matches
129 | 	 */
130 | 	validateFragmentSelectorForMatch(selector: string): true | Error {
131 | 		if (!document.querySelector(selector)) {
132 | 			// prettier-ignore
133 | 			return new Error(`skipping rule since ${highlight(selector)} doesn't exist in the current document`);
134 | 		}
135 | 		if (!queryFragmentElement(selector, this.swup)) {
136 | 			// prettier-ignore
137 | 			return new Error(`skipping rule since ${highlight(selector)} is outside of swup's default containers`);
138 | 		}
139 | 		return true;
140 | 	}
141 | }
142 | 


--------------------------------------------------------------------------------
/src/inc/defs.ts:
--------------------------------------------------------------------------------
 1 | import type { Path, Visit } from 'swup';
 2 | 
 3 | /** Represents a route from one to another URL */
 4 | export type Route = {
 5 | 	from: string;
 6 | 	to: string;
 7 | };
 8 | 
 9 | /** The interface for an augmented Fragment Element */
10 | export interface FragmentElement extends HTMLElement {
11 | 	__swupFragment?: {
12 | 		url?: string;
13 | 		selector?: string;
14 | 		modalShown?: boolean;
15 | 	};
16 | }
17 | 
18 | export type Predicate = (visit: Visit) => boolean;
19 | 
20 | /** A fragment rule */
21 | export type Rule = {
22 | 	from: Path;
23 | 	to: Path;
24 | 	containers: string[];
25 | 	name?: string;
26 | 	scroll?: boolean | string;
27 | 	focus?: boolean | string;
28 | 	if?: Predicate;
29 | };
30 | 
31 | /** The plugin options */
32 | export type Options = {
33 | 	rules: Rule[];
34 | 	debug: boolean;
35 | };
36 | 
37 | /** A fragment visit object */
38 | export type FragmentVisit = {
39 | 	name?: string;
40 | 	containers: string[];
41 | 	scroll: boolean | string;
42 | 	focus?: boolean | string;
43 | };
44 | 


--------------------------------------------------------------------------------
/src/inc/env.ts:
--------------------------------------------------------------------------------
 1 | declare global {
 2 | 	const __DEV__: boolean;
 3 | 	const MICROBUNDLE_TARGET: string;
 4 | 	interface Window {
 5 | 		process?: any;
 6 | 	}
 7 | }
 8 | 
 9 | /**
10 |  * Make sure process.env is defined in the browser
11 |  */
12 | if (!window.process) window.process = {};
13 | if (!window.process.env) window.process.env = {};
14 | 
15 | /**
16 |  * Export the __DEV__ variable. This will become false in production builds from consumers
17 |  */
18 | export const __TEST__ = ['test'].includes(String(process.env.NODE_ENV));
19 | export const __DEV__ = ['development', 'test'].includes(String(process.env.NODE_ENV));
20 | 


--------------------------------------------------------------------------------
/src/inc/functions.ts:
--------------------------------------------------------------------------------
  1 | import Swup, { Location } from 'swup';
  2 | import type { Visit, VisitScroll } from 'swup';
  3 | import type { default as FragmentPlugin } from '../SwupFragmentPlugin.js';
  4 | import type { Route, Rule, FragmentVisit, FragmentElement } from './defs.js';
  5 | import type ParsedRule from './ParsedRule.js';
  6 | import Logger, { highlight } from './Logger.js';
  7 | 
  8 | import { __DEV__ } from './env.js';
  9 | 
 10 | /**
 11 |  * Handles a page view. Runs on `mount` as well as on every content:replace
 12 |  */
 13 | export const handlePageView = (fragmentPlugin: FragmentPlugin): void => {
 14 | 	prepareFragmentElements(fragmentPlugin);
 15 | 	handleLinksToFragments(fragmentPlugin);
 16 | 	showDialogs(fragmentPlugin);
 17 | };
 18 | 
 19 | /**
 20 |  * Run `showModal` for all `<dialog[data-swup-fragment][open]>` elements
 21 |  * This puts them on the top layer and makes them ignore css transforms on parent elements
 22 |  * @see https://developer.mozilla.org/en-US/docs/Glossary/Top_layer
 23 |  */
 24 | function showDialogs({ logger }: FragmentPlugin): void {
 25 | 	document
 26 | 		.querySelectorAll<HTMLDialogElement & FragmentElement>('dialog[data-swup-fragment][open]')
 27 | 		.forEach((el) => {
 28 | 			if (!el.__swupFragment) {
 29 | 				if (__DEV__) logger?.warn(`fragment properties missing on element:`, el);
 30 | 				return;
 31 | 			}
 32 | 			if (el.__swupFragment.modalShown) return;
 33 | 			el.__swupFragment.modalShown = true;
 34 | 			el.removeAttribute('open');
 35 | 			/** don't assume showModal exists – otherwise unit tests will fail */
 36 | 			el.showModal?.();
 37 | 			el.addEventListener('keydown', (e) => e.key === 'Escape' && e.preventDefault());
 38 | 		});
 39 | }
 40 | 
 41 | /**
 42 |  * Updates the `href` of links matching [data-swup-link-to-fragment="#my-fragment"]
 43 |  */
 44 | function handleLinksToFragments({ logger, swup }: FragmentPlugin): void {
 45 | 	const targetAttribute = 'data-swup-link-to-fragment';
 46 | 	const links = document.querySelectorAll<HTMLAnchorElement>(`a[${targetAttribute}]`);
 47 | 
 48 | 	links.forEach((el) => {
 49 | 		const selector = el.getAttribute(targetAttribute);
 50 | 		if (!selector) {
 51 | 			// prettier-ignore
 52 | 			if (__DEV__) logger?.warn(`[${targetAttribute}] needs to contain a valid fragment selector`);
 53 | 			return;
 54 | 		}
 55 | 
 56 | 		const fragment = queryFragmentElement(selector, swup);
 57 | 		if (!fragment) {
 58 | 			if (__DEV__) {
 59 | 				logger?.log(
 60 | 					// prettier-ignore
 61 | 					`ignoring ${highlight(`[${targetAttribute}="${selector}"]`)} as ${highlight(selector)} is missing`
 62 | 				);
 63 | 			}
 64 | 			return;
 65 | 		}
 66 | 
 67 | 		const fragmentUrl = fragment.__swupFragment?.url;
 68 | 		if (!fragmentUrl) {
 69 | 			if (__DEV__) logger?.warn(`no fragment infos found on ${selector}`);
 70 | 			return;
 71 | 		}
 72 | 
 73 | 		// Help finding suspicious fragment urls
 74 | 		if (isEqualUrl(fragmentUrl, swup.getCurrentUrl())) {
 75 | 			// prettier-ignore
 76 | 			if (__DEV__) logger?.warn(`The fragment URL of ${selector} is identical to the current URL. This could mean that [data-swup-fragment-url] needs to be provided by the server.`);
 77 | 		}
 78 | 
 79 | 		el.href = fragmentUrl;
 80 | 	});
 81 | }
 82 | 
 83 | /**
 84 |  * Adds attributes and properties to fragment elements
 85 |  */
 86 | function prepareFragmentElements({ parsedRules, swup, logger }: FragmentPlugin): void {
 87 | 	const currentUrl = swup.getCurrentUrl();
 88 | 
 89 | 	parsedRules
 90 | 		.filter((rule) => rule.matchesFrom(currentUrl) || rule.matchesTo(currentUrl))
 91 | 		.forEach((rule) => {
 92 | 			rule.containers.forEach((selector) => {
 93 | 				const el = queryFragmentElement(`${selector}:not([data-swup-fragment])`, swup);
 94 | 
 95 | 				// No element
 96 | 				if (!el) return;
 97 | 
 98 | 				// Parse a provided fragment URL
 99 | 				const providedFragmentUrl = el.getAttribute('data-swup-fragment-url');
100 | 				if (providedFragmentUrl) {
101 | 					if (__DEV__) {
102 | 						// prettier-ignore
103 | 						logger?.log(`fragment url ${highlight(providedFragmentUrl)} for ${highlight(selector)} provided by server`);
104 | 					}
105 | 				}
106 | 
107 | 				// Get the fragment URL
108 | 				const { url } = Location.fromUrl(providedFragmentUrl || currentUrl);
109 | 
110 | 				// Mark the element as a fragment
111 | 				el.setAttribute('data-swup-fragment', '');
112 | 
113 | 				// Augment the element with the necessary properties
114 | 				el.__swupFragment = { url, selector };
115 | 			});
116 | 		});
117 | }
118 | 
119 | /**
120 |  * Get all containers that should be replaced for a given visit's route.
121 |  * Ignores containers that already match the current URL, if the visit can't be considered a reload.
122 |  *
123 |  * A visit is being considered a reload, if one of these conditions apply:
124 |  * 	- `route.from` equal to `route.to`
125 |  *  - all containers match the current url and swup is set to navigate on `linkToSelf`
126 |  */
127 | export const getFragmentVisitContainers = (
128 | 	route: Route,
129 | 	selectors: string[],
130 | 	swup: Swup,
131 | 	logger?: Logger
132 | ): string[] => {
133 | 	let fragments: { selector: string; el: FragmentElement }[] = selectors
134 | 		.map((selector) => {
135 | 			const el = document.querySelector<FragmentElement>(selector);
136 | 
137 | 			if (!el) {
138 | 				if (__DEV__) logger?.log(`${highlight(selector)} missing in current document`);
139 | 				return false;
140 | 			}
141 | 
142 | 			const fragmentElement = queryFragmentElement(selector, swup);
143 | 
144 | 			if (!fragmentElement) {
145 | 				if (__DEV__) {
146 | 					// prettier-ignore
147 | 					logger?.error(`${highlight(selector)} is outside of swup's default containers`);
148 | 				}
149 | 				return false;
150 | 			}
151 | 
152 | 			return {
153 | 				selector,
154 | 				el
155 | 			};
156 | 		})
157 | 		.filter((record): record is { selector: string; el: FragmentElement } => !!record);
158 | 
159 | 	const isLinkToSelf = fragments.every((fragment) =>
160 | 		elementMatchesFragmentUrl(fragment.el, route.to)
161 | 	);
162 | 
163 | 	const isReload =
164 | 		isEqualUrl(route.from, route.to) ||
165 | 		(isLinkToSelf && swup.options.linkToSelf === 'navigate');
166 | 
167 | 	/**
168 | 	 * If this is NOT a reload, ignore fragments that already match `route.to`
169 | 	 */
170 | 	if (!isReload) {
171 | 		fragments = fragments.filter((fragment) => {
172 | 			if (elementMatchesFragmentUrl(fragment.el, route.to)) {
173 | 				if (__DEV__) {
174 | 					// prettier-ignore
175 | 					logger?.log(`ignoring fragment ${highlight(fragment.selector)} as it already matches the current URL`);
176 | 				}
177 | 				return false;
178 | 			}
179 | 			return true;
180 | 		});
181 | 	}
182 | 
183 | 	return fragments.map((fragment) => fragment.selector);
184 | };
185 | 
186 | /**
187 |  * Checks if an element's fragment url matches a given URL
188 |  */
189 | export const elementMatchesFragmentUrl = (el: FragmentElement, url: string): boolean => {
190 | 	const fragmentUrl = el.__swupFragment?.url;
191 | 	if (!fragmentUrl) return false;
192 | 	return isEqualUrl(fragmentUrl, url);
193 | };
194 | 
195 | /**
196 |  * Checks if two URLs should be considered equal:
197 |  *
198 |  * - ignores trailing slashes
199 |  * - ignores query string order
200 |  *
201 |  * Example: /test?foo=bar&baz=boo === /test/?baz=boo&foo=bar
202 |  */
203 | const isEqualUrl = (url1: string, url2: string) => {
204 | 	return normalizeUrl(url1) === normalizeUrl(url2);
205 | };
206 | 
207 | /**
208 |  * Normalize a URL
209 |  *
210 |  * - removes the trailing slash
211 |  * - sorts query params
212 |  */
213 | export const normalizeUrl = (url: string) => {
214 | 	if (!url.trim()) return url;
215 | 
216 | 	const removeTrailingSlash = (str: string) => str.replace(/\/+$/g, '');
217 | 
218 | 	const location = Location.fromUrl(url);
219 | 	location.searchParams.sort();
220 | 
221 | 	return removeTrailingSlash(location.pathname) + location.search;
222 | };
223 | 
224 | /**
225 |  * Removes all fragment traces from all fragment elements
226 |  */
227 | export const cleanupFragmentElements = () => {
228 | 	document.querySelectorAll<FragmentElement>('[data-swup-fragment]').forEach((el) => {
229 | 		el.removeAttribute('data-swup-fragment-url');
230 | 		delete el.__swupFragment;
231 | 	});
232 | };
233 | 
234 | /**
235 |  * Get the route from a given visit
236 |  */
237 | export const getRoute = (visit: Visit): Route | undefined => {
238 | 	const from = visit.from.url;
239 | 	const to = visit.to.url;
240 | 	if (!from || !to) return;
241 | 	return { from, to };
242 | };
243 | 
244 | /**
245 |  * Adds or removes a rule's name class from all current fragment elements
246 |  */
247 | export const toggleFragmentVisitClass = (
248 | 	fragmentVisit: FragmentVisit | undefined,
249 | 	toggle: boolean
250 | ): void => {
251 | 	if (!fragmentVisit?.name) return;
252 | 
253 | 	const { name, containers } = fragmentVisit;
254 | 
255 | 	containers.forEach((selector) => {
256 | 		document.querySelector(selector)?.classList.toggle(`to-${name}`, toggle);
257 | 	});
258 | };
259 | 
260 | /**
261 |  * Get the first matching rule for a given route
262 |  */
263 | export const getFirstMatchingRule = (
264 | 	route: Route,
265 | 	rules: ParsedRule[],
266 | 	visit: Visit
267 | ): ParsedRule | undefined => {
268 | 	return rules.find((rule) => rule.matches(route, visit));
269 | };
270 | 
271 | /**
272 |  * Makes sure unchanged fragment elements land in the cache of the current page
273 |  */
274 | export const cacheForeignFragmentElements = ({ swup, logger }: FragmentPlugin): void => {
275 | 	const currentUrl = swup.getCurrentUrl();
276 | 	const cache = swup.cache;
277 | 
278 | 	// Get the cache entry for the current URL
279 | 	const currentCache = cache.get(currentUrl);
280 | 	if (!currentCache) return;
281 | 	const currentCachedDocument = new DOMParser().parseFromString(currentCache.html, 'text/html');
282 | 
283 | 	// debug info
284 | 	const updatedFragments: FragmentElement[] = [];
285 | 
286 | 	/**
287 | 	 * We only want to handle fragment elements that
288 | 	 *  - are not templates
289 | 	 *  - don't fit the current URL
290 | 	 */
291 | 	const foreignFragmentElements = Array.from(
292 | 		document.querySelectorAll<FragmentElement>('[data-swup-fragment]')
293 | 	).filter((el) => {
294 | 		if (el.matches('template')) return false;
295 | 		if (elementMatchesFragmentUrl(el, currentUrl)) return false;
296 | 		return true;
297 | 	});
298 | 
299 | 	// Bail early if there are no foreign fragment elements
300 | 	if (!foreignFragmentElements.length) return;
301 | 
302 | 	if (!swup.options.cache) {
303 | 		if (__DEV__) logger?.warn(`can't cache foreign fragment elements without swup's cache`);
304 | 		return;
305 | 	}
306 | 
307 | 	foreignFragmentElements.forEach((el) => {
308 | 		// Don't cache the fragment if it contains fragment elements
309 | 		const containsFragments = el.querySelector('[data-swup-fragment]') != null;
310 | 		if (containsFragments) return;
311 | 
312 | 		const fragmentUrl = el.__swupFragment?.url;
313 | 		if (!fragmentUrl) {
314 | 			if (__DEV__) logger?.warn(`no fragment url found:`, el);
315 | 			return;
316 | 		}
317 | 
318 | 		const fragmentSelector = el.__swupFragment?.selector;
319 | 		if (!fragmentSelector) {
320 | 			if (__DEV__) logger?.warn(`no fragment selector found:`, el);
321 | 			return;
322 | 		}
323 | 
324 | 		// Get the cache entry for the fragment URL, bail early if it doesn't exist
325 | 		const fragmentCache = cache.get(fragmentUrl);
326 | 		if (!fragmentCache) return;
327 | 
328 | 		// Check if the fragment exists in the current cached document
329 | 		const currentFragment = currentCachedDocument.querySelector(fragmentSelector);
330 | 		if (!currentFragment) return;
331 | 
332 | 		// Get a fresh copy of the fragment from it's original cache
333 | 		const unchangedFragment = new DOMParser()
334 | 			.parseFromString(fragmentCache.html, 'text/html')
335 | 			.querySelector(fragmentSelector);
336 | 		if (!unchangedFragment) return;
337 | 
338 | 		// Make sure the dynamic fragment url makes it to the cache
339 | 		unchangedFragment.setAttribute('data-swup-fragment-url', fragmentUrl);
340 | 
341 | 		// Replace the current fragment with the unchanged fragment
342 | 		currentFragment.replaceWith(unchangedFragment);
343 | 
344 | 		// For debugging
345 | 		updatedFragments.push(el);
346 | 	});
347 | 
348 | 	if (!updatedFragments.length) return;
349 | 
350 | 	// Update the cache of the current page with the updated html
351 | 	cache.update(currentUrl, {
352 | 		fragmentHtml: currentCachedDocument.documentElement.outerHTML
353 | 	});
354 | 
355 | 	updatedFragments.forEach((el) => {
356 | 		const url = el.__swupFragment?.url || '';
357 | 		const selector = el.__swupFragment?.selector || '';
358 | 		// prettier-ignore
359 | 		if (__DEV__) logger?.log(`updated cache with ${highlight(selector)} from ${highlight(url)}`);
360 | 	});
361 | };
362 | 
363 | /**
364 |  * Skips the animation if all current containers are <template> elements
365 |  */
366 | export function shouldSkipAnimation(fragmentVisit?: FragmentVisit): boolean {
367 | 	if (!fragmentVisit) return false;
368 | 
369 | 	return fragmentVisit.containers.every((selector) => {
370 | 		return (
371 | 			document.querySelector<FragmentElement>(selector)?.tagName?.toLowerCase() === 'template'
372 | 		);
373 | 	});
374 | }
375 | 
376 | /**
377 |  * Remove duplicates from an array
378 |  */
379 | export function dedupe<T>(arr: Array<T>): Array<T> {
380 | 	return [...new Set<T>(arr)];
381 | }
382 | 
383 | /**
384 |  * Adjusts visit.scroll based on given fragment visit
385 |  */
386 | export function adjustVisitScroll(fragmentVisit: FragmentVisit, scroll: VisitScroll): VisitScroll {
387 | 	if (typeof fragmentVisit.scroll === 'boolean') {
388 | 		return { ...scroll, reset: fragmentVisit.scroll };
389 | 	}
390 | 	if (typeof fragmentVisit.scroll === 'string' && !scroll.target) {
391 | 		return { ...scroll, target: fragmentVisit.scroll };
392 | 	}
393 | 	return scroll;
394 | }
395 | 
396 | /**
397 |  * Queries a fragment element. Needs to be either:
398 |  *
399 |  * - one of swup's default containers
400 |  * - inside of one of swup's default containers
401 |  */
402 | export function queryFragmentElement(
403 | 	fragmentSelector: string,
404 | 	swup: Swup
405 | ): FragmentElement | undefined {
406 | 	for (const containerSelector of swup.options.containers) {
407 | 		const container = document.querySelector(containerSelector);
408 | 		if (container?.matches(fragmentSelector)) return container as FragmentElement;
409 | 
410 | 		const fragment = container?.querySelector<FragmentElement>(fragmentSelector);
411 | 		if (fragment) return fragment;
412 | 	}
413 | 	return;
414 | }
415 | 
416 | /**
417 |  * Clone fragment rules (replacement for `structuredClone`)
418 |  */
419 | export function cloneRules(rules: Rule[]): Rule[] {
420 | 	if (!Array.isArray(rules)) throw new Error(`cloneRules() expects an array of rules`);
421 | 
422 | 	return rules.map((rule) => ({
423 | 		...rule,
424 | 		from: Array.isArray(rule.from) ? [...rule.from] : rule.from,
425 | 		to: Array.isArray(rule.to) ? [...rule.to] : rule.to,
426 | 		containers: [...rule.containers]
427 | 	}));
428 | }
429 | 
430 | /**
431 |  * Create a visit object for tests
432 |  */
433 | export function stubVisit(options: { from?: string; to: string }) {
434 | 	const swup = new Swup();
435 | 	// @ts-expect-error swup.createVisit is protected
436 | 	return swup.createVisit(options);
437 | }
438 | 


--------------------------------------------------------------------------------
/src/inc/handlers.ts:
--------------------------------------------------------------------------------
  1 | import type { Handler } from 'swup';
  2 | import { highlight } from './Logger.js';
  3 | import type { default as FragmentPlugin } from '../SwupFragmentPlugin.js';
  4 | 
  5 | import {
  6 | 	handlePageView,
  7 | 	getRoute,
  8 | 	toggleFragmentVisitClass,
  9 | 	getFirstMatchingRule,
 10 | 	cacheForeignFragmentElements,
 11 | 	shouldSkipAnimation,
 12 | 	adjustVisitScroll
 13 | } from './functions.js';
 14 | 
 15 | import { __DEV__ } from './env.js';
 16 | 
 17 | /**
 18 |  * Do not scroll if clicking on a link to the same page
 19 |  * and the route matches a fragment rule
 20 |  */
 21 | export const onLinkToSelf: Handler<'link:self'> = function (this: FragmentPlugin, visit) {
 22 | 	const route = getRoute(visit);
 23 | 	if (!route) return;
 24 | 
 25 | 	const rule = getFirstMatchingRule(route, this.parsedRules, visit);
 26 | 
 27 | 	if (rule) visit.scroll.reset = false;
 28 | };
 29 | 
 30 | /**
 31 |  * Prepare fragment visits
 32 |  */
 33 | export const onVisitStart: Handler<'visit:start'> = async function (this: FragmentPlugin, visit) {
 34 | 	const route = getRoute(visit);
 35 | 	if (!route) return;
 36 | 
 37 | 	const fragmentVisit = this.getFragmentVisit(route, visit);
 38 | 
 39 | 	/**
 40 | 	 * Bail early if the current route doesn't match
 41 | 	 * a rule or wouldn't replace any fragment elements
 42 | 	 */
 43 | 	if (!fragmentVisit) return;
 44 | 
 45 | 	visit.fragmentVisit = fragmentVisit;
 46 | 
 47 | 	if (__DEV__) {
 48 | 		this.logger?.log(`fragment visit: ${highlight(visit.fragmentVisit.containers.join(', '))}`);
 49 | 	}
 50 | 
 51 | 	visit.scroll = adjustVisitScroll(fragmentVisit, visit.scroll);
 52 | 
 53 | 	// Fragment Plugin can't know if Accesssibilty Plugin is installed
 54 | 	// @ts-expect-error
 55 | 	const a11y = visit.a11y as { focus?: boolean | string };
 56 | 	if (typeof fragmentVisit.focus !== 'undefined') {
 57 | 		if (__DEV__) {
 58 | 			this.logger?.errorIf(
 59 | 				!a11y,
 60 | 				"Can't set visit.a11y.focus. Is @swup/a11y-plugin installed?"
 61 | 			);
 62 | 		}
 63 | 		if (a11y) a11y.focus = fragmentVisit.focus;
 64 | 	}
 65 | 
 66 | 	// Add the transition classes directly to the containers for this visit
 67 | 	visit.animation.scope = visit.fragmentVisit.containers;
 68 | 
 69 | 	// Overwrite the containers for this visit
 70 | 	visit.containers = visit.fragmentVisit.containers;
 71 | 
 72 | 	// Overwrite the animationSelector for this visit
 73 | 	visit.animation.selector = visit.fragmentVisit.containers.join(',');
 74 | 
 75 | 	toggleFragmentVisitClass(fragmentVisit, true);
 76 | };
 77 | 
 78 | /**
 79 |  * Skips the out-animation for <template> fragment elements
 80 |  */
 81 | export const maybeSkipOutAnimation: Handler<'animation:out:await'> = function (
 82 | 	this: FragmentPlugin,
 83 | 	visit,
 84 | 	args
 85 | ) {
 86 | 	if (visit.fragmentVisit && shouldSkipAnimation(visit.fragmentVisit)) {
 87 | 		if (__DEV__)
 88 | 			this.logger?.log(
 89 | 				`${highlight('out')}-animation skipped for ${highlight(
 90 | 					visit.fragmentVisit?.containers.toString()
 91 | 				)}`
 92 | 			);
 93 | 		args.skip = true;
 94 | 	}
 95 | };
 96 | 
 97 | /**
 98 |  * Skips the in-animation for <template> fragment elements
 99 |  */
100 | export const maybeSkipInAnimation: Handler<'animation:in:await'> = function (
101 | 	this: FragmentPlugin,
102 | 	visit,
103 | 	args
104 | ) {
105 | 	if (visit.fragmentVisit && shouldSkipAnimation(visit.fragmentVisit)) {
106 | 		if (__DEV__)
107 | 			this.logger?.log(
108 | 				`${highlight('in')}-animation skipped for ${highlight(
109 | 					visit.fragmentVisit?.containers.toString()
110 | 				)}`
111 | 			);
112 | 		args.skip = true;
113 | 	}
114 | };
115 | 
116 | /**
117 |  * Runs directly before replacing the content
118 |  */
119 | export const beforeContentReplace: Handler<'content:replace'> = function (
120 | 	this: FragmentPlugin,
121 | 	visit,
122 | 	args
123 | ) {
124 | 	/**
125 | 	 * Only use the fragment cache if navigating without a trigger (e.g. link click)
126 | 	 * (PopStateEvent, swup.navigate)
127 | 	 */
128 | 	if (visit.trigger.el || !visit.to.url) return;
129 | 
130 | 	const cache = this.swup.cache.get(visit.to.url);
131 | 	if (!cache || !cache.fragmentHtml) return;
132 | 
133 | 	visit.to.document = new DOMParser().parseFromString(cache.fragmentHtml, 'text/html');
134 | 	visit.to.html = cache.fragmentHtml;
135 | 
136 | 	if (__DEV__) this.logger?.log(`fragment cache used for ${highlight(visit.to.url!)}`);
137 | };
138 | 
139 | /**
140 |  * Runs after the content was replaced
141 |  */
142 | export const onContentReplace: Handler<'content:replace'> = function (this: FragmentPlugin, visit) {
143 | 	toggleFragmentVisitClass(visit.fragmentVisit, true);
144 | 	handlePageView(this);
145 | 	cacheForeignFragmentElements(this);
146 | };
147 | 
148 | /**
149 |  * Remove possible fragment rule names from fragment elements
150 |  */
151 | export const onVisitEnd: Handler<'visit:end'> = function (this: FragmentPlugin, visit) {
152 | 	toggleFragmentVisitClass(visit.fragmentVisit, false);
153 | };
154 | 


--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
 1 | import FragmentPlugin from './SwupFragmentPlugin.js';
 2 | export default FragmentPlugin;
 3 | import type { FragmentVisit } from './inc/defs.js';
 4 | export type { Options, Rule, FragmentElement, FragmentVisit } from './inc/defs.js';
 5 | 
 6 | declare module 'swup' {
 7 | 	export interface Swup {
 8 | 		getFragmentVisit?: FragmentPlugin['getFragmentVisit'];
 9 | 		getFragmentRules?: FragmentPlugin['getRules'];
10 | 		setFragmentRules?: FragmentPlugin['setRules'];
11 | 		prependFragmentRule?: FragmentPlugin['prependRule'];
12 | 		appendFragmentRule?: FragmentPlugin['appendRule'];
13 | 	}
14 | 	export interface Visit {
15 | 		fragmentVisit?: FragmentVisit;
16 | 	}
17 | 	export interface CacheData {
18 | 		fragmentHtml?: string;
19 | 	}
20 | }
21 | 


--------------------------------------------------------------------------------
/tests/config/playwright.config.ts:
--------------------------------------------------------------------------------
 1 | import { defineConfig, devices } from '@playwright/test';
 2 | 
 3 | import { fileURLToPath } from 'url';
 4 | import path from 'path';
 5 | 
 6 | const __filename = fileURLToPath(import.meta.url);
 7 | const __dirname = path.dirname(__filename);
 8 | 
 9 | const baseURL = 'http://localhost:8274';
10 | 
11 | /**
12 |  * See https://playwright.dev/docs/test-configuration.
13 |  */
14 | export default defineConfig({
15 | 	/* Run this file before starting the tests */
16 | 	globalSetup: path.resolve(__dirname, './playwright.setup.ts'),
17 | 	/* Run this file after all the tests have finished */
18 | 	// globalTeardown: path.resolve(__dirname, './playwright.teardown.ts'),
19 | 	/* Directory containing the test files */
20 | 	testDir: '../playwright',
21 | 	/* Folder for test artifacts: screenshots, videos, ... */
22 | 	outputDir: '../results',
23 | 	/* Timeout individual tests after 5 seconds */
24 | 	timeout: 10_000,
25 | 	/* Run tests in files in parallel */
26 | 	fullyParallel: true,
27 | 	/* Fail the build on CI if you accidentally left test.only in the source code. */
28 | 	forbidOnly: !!process.env.CI,
29 | 	/* Retry on CI only */
30 | 	retries: process.env.CI ? 1 : 0,
31 | 	/* Limit parallel workers on CI, use default locally. */
32 | 	workers: process.env.CI ? 1 : undefined,
33 | 	// Limit the number of failures on CI to save resources
34 | 	maxFailures: process.env.CI ? 10 : undefined,
35 | 	/* Reporter to use. See https://playwright.dev/docs/test-reporters */
36 | 	reporter: process.env.CI
37 | 		? [['dot'], ['github'], ['json', { outputFile: '../../playwright-results.json' }]]
38 | 		: [['list'], ['html', { outputFolder: '../reports/html', open: 'on-failure' }]],
39 | 
40 | 	expect: {
41 | 		/* Timeout async expect matchers after 3 seconds */
42 | 		timeout: 3_000
43 | 	},
44 | 
45 | 	/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
46 | 	use: {
47 | 		/* Base URL to use in actions like `await page.goto('/')`. */
48 | 		baseURL,
49 | 		/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
50 | 		trace: 'on-first-retry',
51 | 		/* Capture screenshot after each test failure. */
52 | 		screenshot: 'only-on-failure',
53 | 		/* Capture video if failed tests. */
54 | 		video: 'retain-on-failure'
55 | 	},
56 | 
57 | 	/* Configure projects for major browsers */
58 | 	projects: [
59 | 		{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
60 | 		{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
61 | 		{ name: 'webkit', use: { ...devices['Desktop Safari'] } }
62 | 	],
63 | 
64 | 	/* Run your local dev server before starting the tests */
65 | 	webServer: {
66 | 		url: baseURL,
67 | 		command: 'npm run test:e2e:serve',
68 | 		reuseExistingServer: !process.env.CI
69 | 	}
70 | });
71 | 


--------------------------------------------------------------------------------
/tests/config/playwright.setup.ts:
--------------------------------------------------------------------------------
1 | import { prepare } from '../prepare.js';
2 | 
3 | export default () => {
4 | 	prepare();
5 | };
6 | 


--------------------------------------------------------------------------------
/tests/config/playwright.teardown.ts:
--------------------------------------------------------------------------------
1 | import { rmSync } from 'node:fs';
2 | 
3 | export default () => {
4 | 	rmSync('./tests/fixtures/dist', { recursive: true });
5 | };
6 | 


--------------------------------------------------------------------------------
/tests/config/serve.json:
--------------------------------------------------------------------------------
1 | {
2 |   "public": "tests/fixtures",
3 |   "cleanUrls": true,
4 |   "redirects": [
5 |     { "source": "/redirect-2.html", "destination": "/redirect-3.html" }
6 |   ]
7 | }
8 | 


--------------------------------------------------------------------------------
/tests/config/vitest.config.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Vitest config file
 3 |  * @see https://vitest.dev/config/
 4 |  */
 5 | 
 6 | import path from 'path';
 7 | import { defineConfig } from 'vitest/config';
 8 | 
 9 | const __dirname = path.dirname(__filename);
10 | 
11 | export default defineConfig({
12 | 	test: {
13 | 		environment: 'jsdom',
14 | 		include: ['tests/vitest/**/*.test.ts'],
15 | 		setupFiles: [path.resolve(__dirname, './vitest.setup.ts')]
16 | 	}
17 | });
18 | 


--------------------------------------------------------------------------------
/tests/config/vitest.setup.ts:
--------------------------------------------------------------------------------
 1 | import { vi } from 'vitest';
 2 | 
 3 | /**
 4 |  * Allow spying on the console
 5 |  */
 6 | // vi.spyOn(console, 'log');
 7 | // vi.spyOn(console, 'warn');
 8 | // vi.spyOn(console, 'error');
 9 | 
10 | // Stub browser functions for vitest
11 | // console.log = vi.fn();
12 | // console.warn = vi.fn();
13 | // console.error = vi.fn();
14 | 


--------------------------------------------------------------------------------
/tests/fixtures/assets/script.js:
--------------------------------------------------------------------------------
 1 | const rules = [
 2 | 	{
 3 | 		from: ['/list/', '/list/filter/:filter'],
 4 | 		to: ['/list/', '/list/filter/:filter'],
 5 | 		containers: ['#list'],
 6 | 		name: 'update-list'
 7 | 	},
 8 | 	{
 9 | 		from: ['/list/', '/list/filter/:filter'],
10 | 		to: '/detail/',
11 | 		containers: ['#detail'],
12 | 		name: 'open-detail'
13 | 	},
14 | 	{
15 | 		from: '/detail/',
16 | 		to: ['/list/', '/list/filter/:filter'],
17 | 		containers: ['#detail', '#list'],
18 | 		name: 'close-detail'
19 | 	}
20 | ];
21 | 
22 | const fragmentPlugin = new SwupFragmentPlugin({ rules });
23 | 
24 | const swup = new Swup({ plugins: [fragmentPlugin] });
25 | window._fragmentPlugin = fragmentPlugin;
26 | window._swup = swup;
27 | 
28 | const uniqueId = (length = 16) => {
29 | 	return parseInt(
30 | 		Math.ceil(Math.random() * Date.now())
31 | 			.toPrecision(length)
32 | 			.toString()
33 | 			.replace('.', '')
34 | 	);
35 | };
36 | 
37 | const fragmentContainers = rules.reduce((acc, current) => [...acc, ...current.containers], []);
38 | const allContainers = [...new Set([...swup.options.containers, ...fragmentContainers])];
39 | 
40 | /**
41 |  * Add a unique id attribute to every provided selector.
42 |  * This will help to identify persisted elements more easily
43 |  */
44 | function addUniqueIds(selectors) {
45 | 	selectors.forEach((selector) => {
46 | 		document.querySelector(selector)?.setAttribute('data-uniqueid', uniqueId());
47 | 	});
48 | }
49 | 
50 | addUniqueIds(allContainers);
51 | swup.hooks.on('content:replace', ({ containers }) => addUniqueIds(containers));
52 | 
53 | swup.hooks.on('visit:start', () => document.documentElement.setAttribute('aria-busy', 'true'));
54 | swup.hooks.on('visit:end', () => document.documentElement.removeAttribute('aria-busy'));
55 | 


--------------------------------------------------------------------------------
/tests/fixtures/assets/style.css:
--------------------------------------------------------------------------------
  1 | @import url('./transitions.css');
  2 | 
  3 | *,
  4 | *:before,
  5 | *:after {
  6 | 	box-sizing: border-box;
  7 | }
  8 | 
  9 | :root {
 10 | 	--red: hsl(0, 74%, 67%);
 11 | 	--green: hsl(100, 68%, 58%);
 12 | 	--blue: oklch(59.12% 0.153 230.82);
 13 | }
 14 | body {
 15 | 	font-family: system-ui;
 16 | 	padding: 1rem;
 17 | 	max-width: 800px;
 18 | 	margin: 5% auto;
 19 | 	padding-bottom: 100vh;
 20 | }
 21 | 
 22 | h1,
 23 | h2,
 24 | ul {
 25 | 	margin-bottom: 1rem;
 26 | }
 27 | 
 28 | :focus-visible {
 29 | 	box-shadow: 0 0 0 3px gold;
 30 | 	outline: 0;
 31 | }
 32 | 
 33 | /*
 34 | * Lists
 35 | */
 36 | :where(ul[class]) {
 37 | 	list-style: none;
 38 | 	padding: 0;
 39 | }
 40 | :where(ul:not([class])) {
 41 | 	list-style-type: '> ';
 42 | 	padding-left: 1rem;
 43 | 	& li {
 44 | 		padding-block: 0.2em;
 45 | 	}
 46 | }
 47 | :where(a) {
 48 | 	color: var(--blue);
 49 | 	text-decoration: none;
 50 | }
 51 | 
 52 | /*
 53 | * List
 54 | */
 55 | .filters {
 56 | 	display: flex;
 57 | 	gap: 1rem;
 58 | }
 59 | .filters a,
 60 | a.button {
 61 | 	padding: 0.2em 0.5em;
 62 | 	border: 1px solid var(--blue);
 63 | 	border-radius: 0.5em;
 64 | 	&.is-active,
 65 | 	&:hover {
 66 | 		background: var(--blue);
 67 | 		color: white;
 68 | 	}
 69 | }
 70 | .list {
 71 | 	display: grid;
 72 | 	grid-template-columns: repeat(auto-fill, minmax(100px, 1fr));
 73 | 	gap: 1rem;
 74 | }
 75 | .list_item {
 76 | 	border-radius: 100%;
 77 | 	background: black;
 78 | }
 79 | .list_item--red {
 80 | 	background: var(--red);
 81 | }
 82 | .list_item--green {
 83 | 	background: var(--green);
 84 | }
 85 | .list_item_link {
 86 | 	display: flex;
 87 | 	color: white;
 88 | 	aspect-ratio: 1;
 89 | 	display: flex;
 90 | 	align-items: center;
 91 | 	justify-content: center;
 92 | 	border-radius: 100%;
 93 | 	text-decoration: none;
 94 | 	font-size: 2rem;
 95 | }
 96 | 
 97 | /*
 98 | * Modals
 99 | */
100 | .modal {
101 | 	max-width: 600px;
102 | 	padding: 1rem;
103 | }
104 | .modal_close {
105 | 	position: absolute;
106 | 	inset-block-start: 1rem;
107 | 	inset-inline-end: 1rem;
108 | }
109 | 


--------------------------------------------------------------------------------
/tests/fixtures/assets/transitions.css:
--------------------------------------------------------------------------------
 1 | /*
 2 | * Default
 3 | */
 4 | html.is-changing .transition-main {
 5 | 	transition:
 6 | 		opacity 250ms,
 7 | 		transform 250ms;
 8 | }
 9 | html.is-animating .transition-main {
10 | 	opacity: 0;
11 | 	transform: translateY(-30px);
12 | }
13 | html.is-leaving .transition-main {
14 | 	transform: translateY(30px);
15 | }
16 | /*
17 | * List
18 | */
19 | #list.is-changing {
20 | 	transition: opacity 300ms;
21 | }
22 | #list.is-animating {
23 | 	opacity: 0;
24 | }
25 | 
26 | /*
27 | * Modal
28 | */
29 | #detail.is-changing {
30 | 	transition:
31 | 		transform 300ms,
32 | 		opacity 300ms;
33 | }
34 | #detail.is-animating {
35 | 	opacity: 0;
36 | 	transform: scale(0.9);
37 | }
38 | 


--------------------------------------------------------------------------------
/tests/fixtures/detail/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 | 	<head>
 4 | 		<meta charset="utf-8" />
 5 | 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 6 | 		<title>Detail</title>
 7 | 		<link rel="stylesheet" href="/assets/style.css" />
 8 | 	</head>
 9 | 	<body>
10 | 		<main id="swup" class="transition-main">
11 | 
12 | 			<dialog open id="detail" class="modal">
13 | 				<main>
14 | 					<h1>Detail</h1>
15 | 					<a href="/list/" data-swup-link-to-fragment="#list" class="modal_close button">close</a>
16 | 					<p>
17 | 						Lorem, ipsum dolor sit amet consectetur adipisicing elit. Eveniet neque at
18 | 						et sapiente voluptate tempore odit earum quam. Illum quia labore quibusdam
19 | 						provident accusantium earum fugiat cumque quidem a, ex itaque laudantium at
20 | 						ad mollitia ab aut quisquam pariatur velit! Est ex iure dolores ducimus
21 | 						porro? Aliquam distinctio quas porro unde! Omnis, est quisquam. Omnis,
22 | 						facere repudiandae molestiae quod ratione cum eos soluta dolorum quidem,
23 | 						asperiores, adipisci officia.
24 | 					</p>
25 | 					<ul class="filters">
26 | 						<li><a href="/list/">All</a></li>
27 | 						<li><a href="/list/filter/green/">Green</a></li>
28 | 						<li><a href="/list/filter/red/">Red</a></li>
29 | 					</ul>
30 | 					<ul>
31 | 						<li><a href="/">Home</a></li>
32 | 					</ul>
33 | 				</main>
34 | 			</dialog>
35 | 
36 | 			<div id="list" data-swup-fragment-url="/list/">
37 | 				<h2>All Items</h2>
38 | 				<ul class="filters">
39 | 					<li><a href="/list/" class="is-active">All</a></li>
40 | 					<li><a href="/list/filter/green/">Green</a></li>
41 | 					<li><a href="/list/filter/red/">Red</a></li>
42 | 				</ul>
43 | 				<ul class="list">
44 | 					<li class="list_item list_item--red">
45 | 						<a class="list_item_link" href="/detail/">1</a>
46 | 					</li>
47 | 					<li class="list_item list_item--green">
48 | 						<a class="list_item_link" href="/detail/">2</a>
49 | 					</li>
50 | 					<li class="list_item list_item--red">
51 | 						<a class="list_item_link" href="/detail/">3</a>
52 | 					</li>
53 | 					<li class="list_item list_item--green">
54 | 						<a class="list_item_link" href="/detail/">4</a>
55 | 					</li>
56 | 				</ul>
57 | 			</div>
58 | 		</main>
59 | 		<script src="/dist/swup.umd.js"></script>
60 | 		<script src="/dist/fragment-plugin.umd.js"></script>
61 | 		<script src="/assets/script.js"></script>
62 | 	</body>
63 | </html>
64 | 


--------------------------------------------------------------------------------
/tests/fixtures/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 | 	<head>
 4 | 		<meta charset="utf-8" />
 5 | 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 6 | 		<title>Home</title>
 7 | 		<link rel="stylesheet" href="/assets/style.css" />
 8 | 	</head>
 9 | 	<body>
10 | 		<main id="swup" class="transition-main">
11 | 			<h1>Home</h1>
12 | 			<ul>
13 | 				<li><a href="/list/">Go to list: all items</a></li>
14 | 				<li><a href="/list/filter/red">Go to list: red items</a></li>
15 | 				<li><a href="/list/filter/red">Go to list: green items</a></li>
16 | 				<li><a href="/detail/">Go to detail</a></li>
17 | 			</ul>
18 | 		</main>
19 | 		<!-- <script type="importmap">
20 | 			{
21 | 				"imports": {
22 | 					"swup": "/dist/node_modules/swup/dist/Swup.modern.js",
23 | 					"delegate-it": "/dist/node_modules/delegate-it/index.js",
24 | 					"path-to-regexp": "/dist/node_modules/path-to-regexp/dist.es2015/index.js",
25 | 					"@swup/plugin": "/dist/node_modules/@swup/plugin/dist/index.modern.js",
26 | 					"@swup/fragment-plugin": "/dist/fragment-plugin/index.modern.js",
27 | 				}
28 | 			}
29 | 		</script>
30 | 		<script type="module" src="/assets/script.js"></script> -->
31 | 		<script src="/dist/swup.umd.js"></script>
32 | 		<script src="/dist/fragment-plugin.umd.js"></script>
33 | 		<script src="/assets/script.js"></script>
34 | 	</body>
35 | </html>
36 | 


--------------------------------------------------------------------------------
/tests/fixtures/list/filter/green/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 | 	<head>
 4 | 		<meta charset="utf-8" />
 5 | 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 6 | 		<title>List: Green Items</title>
 7 | 		<link rel="stylesheet" href="/assets/style.css" />
 8 | 	</head>
 9 | 	<body>
10 | 		<main id="swup" class="transition-main">
11 | 
12 | 			<h1>List</h1>
13 | 
14 | 			<template id="detail"></template>
15 | 
16 | 			<div id="list">
17 | 				<h2>Green Items</h2>
18 | 				<ul class="filters">
19 | 					<li><a href="/list/">All</a></li>
20 | 					<li><a href="/list/filter/green/" class="is-active">Green</a></li>
21 | 					<li><a href="/list/filter/red/">Red</a></li>
22 | 				</ul>
23 | 				<ul class="list">
24 | 					<li class="list_item list_item--green">
25 | 						<a class="list_item_link" href="/detail/">2</a>
26 | 					</li>
27 | 					<li class="list_item list_item--green">
28 | 						<a class="list_item_link" href="/detail/">4</a>
29 | 					</li>
30 | 				</ul>
31 | 			</div>
32 | 
33 | 			<ul>
34 | 				<li><a href="/">Home</a></li>
35 | 			</ul>
36 | 
37 | 		</main>
38 | 		<script src="/dist/swup.umd.js"></script>
39 | 		<script src="/dist/fragment-plugin.umd.js"></script>
40 | 		<script src="/assets/script.js"></script>
41 | 	</body>
42 | </html>
43 | 


--------------------------------------------------------------------------------
/tests/fixtures/list/filter/red/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 | 	<head>
 4 | 		<meta charset="utf-8" />
 5 | 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 6 | 		<title>List: Red Items</title>
 7 | 		<link rel="stylesheet" href="/assets/style.css" />
 8 | 	</head>
 9 | 	<body>
10 | 		<main id="swup" class="transition-main">
11 | 
12 | 			<h1>List</h1>
13 | 
14 | 			<template id="detail"></template>
15 | 
16 | 			<div id="list">
17 | 				<h2>Red Items</h2>
18 | 				<ul class="filters">
19 | 					<li><a href="/list/">All</a></li>
20 | 					<li><a href="/list/filter/green/">Green</a></li>
21 | 					<li><a href="/list/filter/red/" class="is-active">Red</a></li>
22 | 				</ul>
23 | 				<ul class="list">
24 | 					<li class="list_item list_item--red">
25 | 						<a class="list_item_link" href="/detail/">1</a>
26 | 					</li>
27 | 					<li class="list_item list_item--red">
28 | 						<a class="list_item_link" href="/detail/">3</a>
29 | 					</li>
30 | 				</ul>
31 | 			</div>
32 | 
33 | 			<ul>
34 | 				<li><a href="/">Home</a></li>
35 | 			</ul>
36 | 
37 | 		</main>
38 | 		<script src="/dist/swup.umd.js"></script>
39 | 		<script src="/dist/fragment-plugin.umd.js"></script>
40 | 		<script src="/assets/script.js"></script>
41 | 	</body>
42 | </html>
43 | 


--------------------------------------------------------------------------------
/tests/fixtures/list/index.html:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html lang="en">
 3 | 	<head>
 4 | 		<meta charset="utf-8" />
 5 | 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 6 | 		<title>List</title>
 7 | 		<link rel="stylesheet" href="/assets/style.css" />
 8 | 	</head>
 9 | 	<body>
10 | 		<main id="swup" class="transition-main">
11 | 
12 | 			<h1>List</h1>
13 | 
14 | 			<p id="intro">
15 | 				This paragraph should persist when clicking one of the filters.
16 | 			</p>
17 | 
18 | 			<template id="detail"></template>
19 | 
20 | 			<div id="list">
21 | 				<h2>All Items</h2>
22 | 				<ul class="filters">
23 | 					<li><a href="/list/" class="is-active">All</a></li>
24 | 					<li><a href="/list/filter/green/">Green</a></li>
25 | 					<li><a href="/list/filter/red/">Red</a></li>
26 | 				</ul>
27 | 				<ul class="list">
28 | 					<li class="list_item list_item--red">
29 | 						<a class="list_item_link" href="/detail/">1</a>
30 | 					</li>
31 | 					<li class="list_item list_item--green">
32 | 						<a class="list_item_link" href="/detail/">2</a>
33 | 					</li>
34 | 					<li class="list_item list_item--red">
35 | 						<a class="list_item_link" href="/detail/">3</a>
36 | 					</li>
37 | 					<li class="list_item list_item--green">
38 | 						<a class="list_item_link" href="/detail/">4</a>
39 | 					</li>
40 | 				</ul>
41 | 			</div>
42 | 
43 | 			<ul>
44 | 				<li><a href="/">Home</a></li>
45 | 			</ul>
46 | 
47 | 		</main>
48 | 		<script src="/dist/swup.umd.js"></script>
49 | 		<script src="/dist/fragment-plugin.umd.js"></script>
50 | 		<script src="/assets/script.js"></script>
51 | 	</body>
52 | </html>
53 | 


--------------------------------------------------------------------------------
/tests/playwright/fragment-plugin.spec.ts:
--------------------------------------------------------------------------------
 1 | import { test, expect } from '@playwright/test';
 2 | 
 3 | import {
 4 | 	clickOnLink,
 5 | 	waitForSwup,
 6 | 	navigateWithSwup,
 7 | 	scrollTo,
 8 | 	expectScrollPosition
 9 | } from './inc/commands.js';
10 | 
11 | test.describe('Fragment Plugin', () => {
12 | 	test.beforeEach(async ({ page }) => {
13 | 		await page.goto('/');
14 | 		await waitForSwup(page);
15 | 	});
16 | 
17 | 	test('should ignore visits without a matching rule', async ({ page }) => {
18 | 		const swupID = await page.locator('#swup').getAttribute('data-uniqueid');
19 | 
20 | 		await clickOnLink(page, '/list/');
21 | 
22 | 		/* #swup was replaced */
23 | 		await expect(page.locator('#swup')).not.toHaveAttribute('data-uniqueid', String(swupID));
24 | 	});
25 | 
26 | 	test('should replace fragments', async ({ page }) => {
27 | 		await navigateWithSwup(page, '/list/');
28 | 
29 | 		const swupID = await page.locator('#swup').getAttribute('data-uniqueid');
30 | 		const listID = await page.locator('#list').getAttribute('data-uniqueid');
31 | 
32 | 		await navigateWithSwup(page, '/list/filter/red/');
33 | 		await expect(page).toHaveURL('/list/filter/red/');
34 | 		await expect(page.locator('h2')).toHaveText('Red Items');
35 | 
36 | 		/* #swup was left alone */
37 | 		expect(await page.locator('#swup').getAttribute('data-uniqueid')).toBe(swupID);
38 | 		/* #list was replaced */
39 | 		expect(await page.locator('#list').getAttribute('data-uniqueid')).not.toBe(listID);
40 | 	});
41 | 
42 | 	test('should cache foreign fragments', async ({ page }) => {
43 | 		await page.goto('/list/');
44 | 
45 | 		await clickOnLink(page, '/list/filter/green/');
46 | 		await clickOnLink(page, '/detail/');
47 | 		await clickOnLink(page, '/');
48 | 		await page.goBack();
49 | 
50 | 		/* #list was updated in the cache of /detail/ */
51 | 		await expect(page.locator('#list h2')).toHaveText('Green Items');
52 | 	});
53 | 
54 | 	test('should move <dialog open> fragments to the top layer', async ({ page }) => {
55 | 		await page.goto('/list/');
56 | 
57 | 		await clickOnLink(page, '/detail/');
58 | 
59 | 		const dialog = page.locator('dialog[data-swup-fragment][open]');
60 | 
61 | 		await expect(dialog).toBeVisible();
62 | 
63 | 		expect(await dialog.evaluate((el) => el.matches(':modal'))).toBe(true);
64 | 	});
65 | 
66 | 	test('should not scroll', async ({ page }) => {
67 | 		await page.goto('/list/');
68 | 
69 | 		await scrollTo(page, 100);
70 | 
71 | 		await navigateWithSwup(page, '/list/filter/green/');
72 | 
73 | 		await expectScrollPosition(page, 100);
74 | 	});
75 | });
76 | 


--------------------------------------------------------------------------------
/tests/playwright/inc/commands.ts:
--------------------------------------------------------------------------------
 1 | import { expect, Page } from '@playwright/test';
 2 | 
 3 | declare global {
 4 | 	interface Window {
 5 | 		_swup: Swup;
 6 | 		data: any;
 7 | 	}
 8 | }
 9 | 
10 | import type Swup from 'swup';
11 | 
12 | export async function waitForSwup(page: Page) {
13 | 	await page.waitForSelector('html.swup-enabled');
14 | }
15 | 
16 | export function sleep(timeout = 0): Promise<void> {
17 | 	return new Promise((resolve) => setTimeout(() => resolve(undefined), timeout));
18 | }
19 | 
20 | export async function clickOnLink(page: Page, url: string, options?: Parameters<Page['click']>[1]) {
21 | 	await page.click(`a[href="${url}"]`, options);
22 | 	await expectToBeAt(page, url);
23 | }
24 | 
25 | export async function navigateWithSwup(
26 | 	page: Page,
27 | 	url: string,
28 | 	options?: Parameters<Swup['navigate']>[1]
29 | ) {
30 | 	await page.evaluate(({ url, options }) => window._swup.navigate(url, options), {
31 | 		url,
32 | 		options
33 | 	});
34 | 	await expectToBeAt(page, url);
35 | }
36 | 
37 | export async function scrollTo(page: Page, y: number) {
38 | 	await page.evaluate((y) => window.scrollTo(0, y), y);
39 | }
40 | 
41 | export async function expectScrollPosition(page: Page, expected: number) {
42 | 	const scrollY = await page.evaluate(() => window.scrollY);
43 | 	expect(scrollY).toBe(expected);
44 | }
45 | 
46 | export async function expectToBeAt(page: Page, url: string) {
47 | 	await page.waitForSelector('html:not([aria-busy=true])', { timeout: 5000 });
48 | 	await expect(page).toHaveURL(url);
49 | }
50 | 
51 | /**
52 |  * Trim slashes from a string
53 |  * @see https://stackoverflow.com/a/3840645/586823
54 |  */
55 | const trimSlashes = (str: string) => str.replace(/^\/|\/$/g, '');
56 | 
57 | /**
58 |  * Create a function to prefix a path
59 |  */
60 | export const prefixed = (prefix: string) => {
61 | 	return (path: string) => `/${trimSlashes(prefix)}/${trimSlashes(path)}`;
62 | };
63 | 


--------------------------------------------------------------------------------
/tests/prepare.js:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env node
 2 | 
 3 | // @ts-check
 4 | 
 5 | import { cpSync, rmSync } from 'node:fs';
 6 | const fixturesDir = './tests/fixtures';
 7 | 
 8 | export function prepare() {
 9 | 	rmSync('./tests/fixtures/dist/', { recursive: true, force: true });
10 | 	cpSync('./node_modules/swup/dist/Swup.umd.js', `${fixturesDir}/dist/swup.umd.js`);
11 | 	cpSync('./dist/index.umd.js', `${fixturesDir}/dist/fragment-plugin.umd.js`);
12 | }
13 | 
14 | prepare();
15 | 


--------------------------------------------------------------------------------
/tests/vitest/ParsedRule.test.ts:
--------------------------------------------------------------------------------
  1 | import { describe, expect, it, afterEach, vi } from 'vitest';
  2 | import ParsedRule from '../../src/inc/ParsedRule.js';
  3 | import Logger from '../../src/inc/Logger.js';
  4 | import { spyOnConsole, stubGlobalDocument } from './inc/helpers.js';
  5 | import Swup from 'swup';
  6 | import { stubVisit } from '../../src/inc/functions.js';
  7 | 
  8 | describe('ParsedRule', () => {
  9 | 	afterEach(() => {
 10 | 		vi.restoreAllMocks();
 11 | 	});
 12 | 	it('should have correct defaults', () => {
 13 | 		const rule = new ParsedRule({
 14 | 			from: '/users/',
 15 | 			to: '/user/:slug',
 16 | 			containers: [' #fragment-1'],
 17 | 			swup: new Swup()
 18 | 		});
 19 | 
 20 | 		// expect valid matchesFrom and matchesTo functions
 21 | 		expect(Boolean(rule.matchesFrom('/users/'))).toBe(true);
 22 | 		expect(Boolean(rule.matchesTo('/user/john'))).toBe(true);
 23 | 		expect(rule.matchesFrom('/')).toBe(false);
 24 | 		expect(rule.matchesTo('/')).toBe(false);
 25 | 
 26 | 		// expect sanitized selectors
 27 | 		expect(rule.containers).toEqual(['#fragment-1']);
 28 | 
 29 | 		expect(rule.scroll).toBe(false);
 30 | 		expect(rule.name).toBe(undefined);
 31 | 		expect(rule.focus).toBe(undefined);
 32 | 		expect(rule.logger).toBe(undefined);
 33 | 	});
 34 | 
 35 | 	it('should parse all provided options', () => {
 36 | 		const rule1 = new ParsedRule({
 37 | 			from: '(.*)',
 38 | 			to: '(.*)',
 39 | 			containers: ['#fragment-1'],
 40 | 			name: 'test',
 41 | 			scroll: '#top',
 42 | 			focus: 'main',
 43 | 			swup: new Swup()
 44 | 		});
 45 | 		expect(rule1.name).toEqual('test');
 46 | 		expect(rule1.scroll).toEqual('#top');
 47 | 		expect(rule1.focus).toEqual('main');
 48 | 
 49 | 		const rule2 = new ParsedRule({
 50 | 			from: '(.*)',
 51 | 			to: '(.*)',
 52 | 			containers: ['#fragment-1'],
 53 | 			scroll: true,
 54 | 			focus: false,
 55 | 			swup: new Swup()
 56 | 		});
 57 | 		expect(rule2.scroll).toEqual(true);
 58 | 		expect(rule2.focus).toEqual(false);
 59 | 	});
 60 | 
 61 | 	it('should log an error if containers is empty', () => {
 62 | 		const console = spyOnConsole();
 63 | 		new ParsedRule({
 64 | 			from: '(.*)',
 65 | 			to: '(.*)',
 66 | 			containers: [],
 67 | 			swup: new Swup(),
 68 | 			logger: new Logger()
 69 | 		});
 70 | 		expect(console.error).toBeCalledWith('Every fragment rule must contain an array of containers', expect.any(Object)); // prettier-ignore
 71 | 	});
 72 | 
 73 | 	it('should validate container selectors and log errors', () => {
 74 | 		const console = spyOnConsole();
 75 | 		const rule = new ParsedRule({
 76 | 			from: '(.*)',
 77 | 			to: '(.*)',
 78 | 			containers: ['.fragment-1', '#swup #fragment-2'],
 79 | 			swup: new Swup(),
 80 | 			logger: new Logger()
 81 | 		});
 82 | 		expect(console.error).toBeCalledTimes(2);
 83 | 		expect(rule.containers).toEqual([]);
 84 | 
 85 | 		expect(console.error).toBeCalledWith(new Error(`fragment selectors must be IDs: .fragment-1`)); // prettier-ignore
 86 | 		expect(console.error).toBeCalledWith(new Error(`fragment selectors must not be nested: #swup #fragment-2`)); // prettier-ignore
 87 | 	});
 88 | 
 89 | 	it('should correctly match a rule', () => {
 90 | 		stubGlobalDocument(
 91 | 			/*html*/ `<div id="swup" class="transition-main"><div id="fragment-1"></div></div>`
 92 | 		);
 93 | 		const rule = new ParsedRule({
 94 | 			from: '/users/',
 95 | 			to: '/user/:slug',
 96 | 			containers: ['#fragment-1'],
 97 | 			swup: new Swup(),
 98 | 			if: (visit) => true
 99 | 		});
100 | 		const visit = stubVisit({ to: '' });
101 | 		expect(rule.matches({ from: '/users/', to: '/user/jane' }, visit)).toBe(true);
102 | 		expect(rule.matches({ from: '/users/', to: '/users/' }, visit)).toBe(false);
103 | 		expect(rule.matches({ from: '/user/jane', to: '/users/' }, visit)).toBe(false);
104 | 		expect(rule.matches({ from: '/user/jane', to: '/user/john' }, visit)).toBe(false);
105 | 
106 | 		/** Respect rule.if */
107 | 		rule.if = (visit) => false;
108 | 		expect(rule.matches({ from: '/users/', to: '/user/jane' }, visit)).toBe(false);
109 | 	});
110 | 
111 | 	it('should validate selectors if matching a rule', () => {
112 | 		const console = spyOnConsole();
113 | 		const rule = new ParsedRule({
114 | 			from: '(.*)',
115 | 			to: '(.*)',
116 | 			containers: ['#fragment-1'],
117 | 			swup: new Swup(),
118 | 			logger: new Logger()
119 | 		});
120 | 		const visit = stubVisit({ to: '' });
121 | 
122 | 		/** fragment element missing */
123 | 		stubGlobalDocument(/*html*/ `<div id="swup" class="transition-main"></div>`);
124 | 		expect(rule.matches({ from: '/foo/', to: '/bar/' }, visit)).toBe(false);
125 | 		expect(console.error).toBeCalledWith(new Error('skipping rule since #fragment-1 doesn\'t exist in the current document'), expect.any(Object)) // prettier-ignore
126 | 
127 | 		/** fragment element outside of swup's default containers */
128 | 		stubGlobalDocument(
129 | 			/*html*/ `<div id="swup" class="transition-main"></div><div id="fragment-1"></div>`
130 | 		);
131 | 		expect(rule.matches({ from: '/foo/', to: '/bar/' }, visit)).toBe(false);
132 | 		expect(console.error).toBeCalledWith(new Error('skipping rule since #fragment-1 is outside of swup\'s default containers'), expect.any(Object)) // prettier-ignore
133 | 	});
134 | });
135 | 


--------------------------------------------------------------------------------
/tests/vitest/adjustVisitScroll.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { adjustVisitScroll, stubVisit } from '../../src/inc/functions.js';
 3 | import Swup from 'swup';
 4 | 
 5 | describe('adjustVisitScroll()', () => {
 6 | 	it('adjust visit.scroll', () => {
 7 | 		const { scroll } = stubVisit({ to: '' });
 8 | 
 9 | 		expect(adjustVisitScroll({ containers: [], scroll: true }, scroll)).toEqual({
10 | 			reset: true
11 | 		});
12 | 
13 | 		expect(adjustVisitScroll({ containers: [], scroll: false }, scroll)).toEqual({
14 | 			reset: false
15 | 		});
16 | 
17 | 		expect(adjustVisitScroll({ containers: [], scroll: '#top' }, scroll)).toEqual({
18 | 			reset: true,
19 | 			target: '#top'
20 | 		});
21 | 	});
22 | });
23 | 


--------------------------------------------------------------------------------
/tests/vitest/cloneRules.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { cloneRules } from '../../src/inc/functions.js';
 3 | 
 4 | describe('cloneRules()', () => {
 5 | 	it('should clone rules', () => {
 6 | 		const original = [
 7 | 			{ from: 'foo', to: 'bar', containers: ['#foobar'] },
 8 | 			{ from: ['/', 'baz'], to: ['/', 'bat'], containers: ['#bazbat'] }
 9 | 		];
10 | 		/** test equality with a reference */
11 | 		const reference = original;
12 | 		expect(original === reference).toEqual(true);
13 | 
14 | 		/** test shallow copy */
15 | 		const shallowCopy = { ...original };
16 | 		expect(original === shallowCopy).toEqual(false);
17 | 		expect(original[0].containers === shallowCopy[0].containers).toEqual(true);
18 | 		expect(original[1].from === shallowCopy[1].from).toEqual(true);
19 | 
20 | 		/** test deep clone */
21 | 		const clone = cloneRules(original);
22 | 		expect(original === clone).toEqual(false);
23 | 		expect(original[0].containers === clone[0].containers).toEqual(false);
24 | 		expect(original[1].from === clone[1].from).toEqual(false);
25 | 	});
26 | });
27 | 


--------------------------------------------------------------------------------
/tests/vitest/dedupe.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { dedupe } from '../../src/inc/functions.js';
 3 | 
 4 | describe('dedupe()', () => {
 5 | 	it('remove duplicates from an array', () => {
 6 | 		expect(dedupe([1, 1, 2, 2, 3])).toEqual([1, 2, 3]);
 7 | 		expect(dedupe(['foo', 'foo', 'bar'])).toEqual(['foo', 'bar']);
 8 | 	});
 9 | });
10 | 


--------------------------------------------------------------------------------
/tests/vitest/exports.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | 
 3 | import * as IndexTS from '../../src/index.js';
 4 | 
 5 | describe('Exports', () => {
 6 | 	it('UMD compatibility: index.ts should only have a default export', () => {
 7 | 		expect(Object.keys(IndexTS)).toEqual(['default']);
 8 | 	});
 9 | });
10 | 


--------------------------------------------------------------------------------
/tests/vitest/getFragmentVisit.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it, vi, afterEach, beforeEach } from 'vitest';
 2 | import { getMountedPluginInstance, stubGlobalDocument } from './inc/helpers.js';
 3 | 
 4 | const fragmentPlugin = getMountedPluginInstance({
 5 | 	rules: [
 6 | 		{
 7 | 			from: '/page-1/',
 8 | 			to: '/page-2/',
 9 | 			containers: ['#fragment-1']
10 | 		}
11 | 	]
12 | });
13 | 
14 | describe('getFragmentVisit()', () => {
15 | 	beforeEach(() => {
16 | 		stubGlobalDocument(
17 | 			/*html*/ `<div id="swup" class="transition-main"><div id="fragment-1"></div></div>`
18 | 		);
19 | 	});
20 | 	afterEach(() => {
21 | 		vi.restoreAllMocks();
22 | 	});
23 | 	it('should be callable as public API', () => {
24 | 		const fragmentVisit = fragmentPlugin.getFragmentVisit({ from: '/page-1/', to: '/page-2/' });
25 | 
26 | 		expect(fragmentVisit).toEqual({
27 | 			containers: ['#fragment-1'],
28 | 			name: undefined,
29 | 			scroll: false,
30 | 			focus: undefined
31 | 		});
32 | 	});
33 | 
34 | 	it('should return undefined if there is no matching rule', () => {
35 | 		const fragmentVisit = fragmentPlugin.getFragmentVisit({ from: '/foo/', to: '/bar/' });
36 | 
37 | 		expect(fragmentVisit).toBeUndefined();
38 | 	});
39 | });
40 | 


--------------------------------------------------------------------------------
/tests/vitest/getFragmentVisitContainers.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it, vi, afterEach, beforeEach } from 'vitest';
 2 | import { getMountedPluginInstance, stubGlobalDocument, spyOnConsole } from './inc/helpers.js';
 3 | import { getFragmentVisitContainers, handlePageView } from '../../src/inc/functions.js';
 4 | 
 5 | const fragmentPlugin = getMountedPluginInstance({
 6 | 	rules: [
 7 | 		{
 8 | 			from: '(.*)',
 9 | 			to: '(.*)',
10 | 			containers: ['#fragment-1', '#fragment-2', '#fragment-3']
11 | 		}
12 | 	]
13 | });
14 | 
15 | describe('getFragmentVisitContainers()', () => {
16 | 	beforeEach(() => {
17 | 		spyOnConsole();
18 | 		stubGlobalDocument(
19 | 			/*html*/ `
20 | 			<div id="swup" class="transition-main">
21 | 				<div id="fragment-1"></div>
22 | 				<div id="fragment-2"></div>
23 | 				<div id="fragment-3" data-swup-fragment-url="/page-2/"></div>
24 | 			</div>
25 | 			<div id="fragment-outside"></div>`,
26 | 			{ url: '/page-1/' }
27 | 		);
28 | 		handlePageView(fragmentPlugin);
29 | 	});
30 | 	afterEach(() => {
31 | 		vi.restoreAllMocks();
32 | 	});
33 | 
34 | 	it('should get the correct containers for a fragment visit', () => {
35 | 		const console = spyOnConsole();
36 | 
37 | 		const fragmentContainers = getFragmentVisitContainers(
38 | 			{ from: '/page-1/', to: '/page-2/' },
39 | 			['#fragment-1', '#fragment-2', '#fragment-3', '#fragment-outside', '#fragment-missing'],
40 | 			fragmentPlugin.swup,
41 | 			fragmentPlugin.logger
42 | 		);
43 | 
44 | 		expect(fragmentContainers).toEqual(['#fragment-1', '#fragment-2']);
45 | 		expect(console.log).toBeCalledWith(`ignoring fragment #fragment-3 as it already matches the current URL`); // prettier-ignore
46 | 		expect(console.log).toBeCalledWith(`#fragment-missing missing in current document`);
47 | 		expect(console.error).toBeCalledWith(`#fragment-outside is outside of swup's default containers`); // prettier-ignore
48 | 	});
49 | 
50 | 	it('should get the correct containers when navigating to the same URL', () => {
51 | 		// route.from is equal to route.to
52 | 		expect(
53 | 			getFragmentVisitContainers(
54 | 				{ from: '/page-1/', to: '/page-1/' },
55 | 				[
56 | 					'#fragment-1',
57 | 					'#fragment-2',
58 | 					'#fragment-3',
59 | 					'#fragment-outside',
60 | 					'#fragment-missing'
61 | 				],
62 | 				fragmentPlugin.swup,
63 | 				fragmentPlugin.logger
64 | 			)
65 | 		).toEqual(['#fragment-1', '#fragment-2', '#fragment-3']);
66 | 	});
67 | 
68 | 	it("should reload fragments if swup.options.linkToSelf equals 'navigate'", () => {
69 | 		fragmentPlugin.swup.options.linkToSelf = 'navigate';
70 | 		expect(
71 | 			getFragmentVisitContainers(
72 | 				{ from: '/page-1/', to: '/page-2/' },
73 | 				['#fragment-3'],
74 | 				fragmentPlugin.swup,
75 | 				fragmentPlugin.logger
76 | 			)
77 | 		).toEqual(['#fragment-3']);
78 | 	});
79 | 
80 | 	it("should ignore fragments if swup.options.linkToSelf equals 'scroll'", () => {
81 | 		fragmentPlugin.swup.options.linkToSelf = 'scroll';
82 | 		expect(
83 | 			getFragmentVisitContainers(
84 | 				{ from: '/page-1/', to: '/page-2/' },
85 | 				['#fragment-3'],
86 | 				fragmentPlugin.swup,
87 | 				fragmentPlugin.logger
88 | 			)
89 | 		).toEqual([]);
90 | 	});
91 | });
92 | 


--------------------------------------------------------------------------------
/tests/vitest/getRoute.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { getRoute, stubVisit } from '../../src/inc/functions.js';
 3 | import Swup from 'swup';
 4 | 
 5 | describe('getRoute()', () => {
 6 | 	it('should get the route from a visit', () => {
 7 | 		const route = { from: '/page-1/', to: '/page-2/' };
 8 | 		const visit = stubVisit(route);
 9 | 		expect(getRoute(visit)).toEqual(route);
10 | 	});
11 | 
12 | 	it('should return undefined for incomplete visits', () => {
13 | 		const withEmptyTo = stubVisit({ to: '' });
14 | 		expect(getRoute(withEmptyTo)).toEqual(undefined);
15 | 
16 | 		const withEmptyFrom = stubVisit({ from: '', to: '/page-2/' });
17 | 		expect(getRoute(withEmptyFrom)).toEqual(undefined);
18 | 	});
19 | });
20 | 


--------------------------------------------------------------------------------
/tests/vitest/handlePageView.test.ts:
--------------------------------------------------------------------------------
 1 | import { afterEach, describe, expect, it, vi } from 'vitest';
 2 | import { getMountedPluginInstance, spyOnConsole, stubGlobalDocument } from './inc/helpers.js';
 3 | import { handlePageView } from '../../src/inc/functions.js';
 4 | import type { FragmentElement } from '../../src/index.js';
 5 | 
 6 | const fragmentPlugin = getMountedPluginInstance({
 7 | 	rules: [
 8 | 		{
 9 | 			from: '(.*)',
10 | 			to: '(.*)',
11 | 			containers: ['#fragment-1', '#fragment-2']
12 | 		}
13 | 	]
14 | });
15 | 
16 | describe('handlePageView()', () => {
17 | 	afterEach(() => {
18 | 		vi.restoreAllMocks();
19 | 	});
20 | 	it('should prepare fragment elements', () => {
21 | 		const url = '/page/?foo=bar';
22 | 		stubGlobalDocument(
23 | 			/*html*/ `
24 | 			<div id="swup" class="transition-main">
25 | 				<div id="fragment-1"></div>
26 | 				<div id="fragment-2"></div>
27 | 			</div>`,
28 | 			{ url }
29 | 		);
30 | 		handlePageView(fragmentPlugin);
31 | 
32 | 		const [fragment1, fragment2] = document.querySelectorAll<FragmentElement>('[data-swup-fragment]'); // prettier-ignore
33 | 
34 | 		expect(fragment1?.__swupFragment).toEqual({ url, selector: '#fragment-1' });
35 | 		expect(fragment2?.__swupFragment).toEqual({ url, selector: '#fragment-2' });
36 | 	});
37 | 
38 | 	it('should handle user-provided data attributes', () => {
39 | 		const console = spyOnConsole();
40 | 		stubGlobalDocument(/*html*/ `
41 | 			<div id="swup" class="transition-main">
42 | 				<div id="fragment-1" data-swup-fragment-url="/fragment-url/"></div>
43 | 				<a data-swup-link-to-fragment="#fragment-1"></a>
44 | 			</div>`);
45 | 
46 | 		handlePageView(fragmentPlugin);
47 | 
48 | 		const link = document.querySelector<HTMLAnchorElement>(`a[data-swup-link-to-fragment]`)!;
49 | 
50 | 		expect(console.log).toBeCalledWith(`fragment url /fragment-url/ for #fragment-1 provided by server`); // prettier-ignore
51 | 		expect(link.pathname).toEqual('/fragment-url/');
52 | 	});
53 | 
54 | 	it('should handle <dialog> fragment elements', () => {
55 | 		stubGlobalDocument(
56 | 			/*html*/ `<div id="swup" class="transition-main"><dialog open id="fragment-1"></div></div>`
57 | 		);
58 | 		handlePageView(fragmentPlugin);
59 | 
60 | 		const dialog = document.querySelector<HTMLDialogElement & FragmentElement>('#fragment-1');
61 | 		expect(dialog?.__swupFragment?.modalShown).toEqual(true);
62 | 	});
63 | 
64 | 	it("should ignore fragments outside of swup's main containers", () => {
65 | 		stubGlobalDocument(
66 | 			/*html*/ `<div id="swup" class="transition-main"></div><div id="fragment-1"></div>`
67 | 		);
68 | 		handlePageView(fragmentPlugin);
69 | 
70 | 		const el = document.querySelector('#fragment-1');
71 | 		expect(el?.hasAttribute('data-swup-fragment')).toEqual(false);
72 | 	});
73 | });
74 | 


--------------------------------------------------------------------------------
/tests/vitest/inc/helpers.ts:
--------------------------------------------------------------------------------
 1 | import { vi } from 'vitest';
 2 | import Swup from 'swup';
 3 | import { JSDOM } from 'jsdom';
 4 | import SwupFragmentPlugin from '../../../src/index.js';
 5 | import type { Options } from '../../../src/inc/defs.js';
 6 | 
 7 | type DocumentOptions = {
 8 | 	url: string;
 9 | };
10 | 
11 | /**
12 |  * Wrap <body> HTML inside a html string
13 |  */
14 | export const wrapBodyTag = (body: string): string => /*html*/ `<!DOCTYPE html><body>${body}</body>`;
15 | 
16 | /**
17 |  * Stub the global document with
18 |  *
19 |  * - custom body HTML
20 |  * - a custom URL
21 |  *
22 |  * @see https://github.com/jsdom/jsdom#reconfiguring-the-jsdom-with-reconfiguresettings
23 |  */
24 | export const stubGlobalDocument = (body: string, options: Partial<DocumentOptions> = {}): void => {
25 | 	const baseURI = 'https://example.com';
26 | 	const defaults: DocumentOptions = {
27 | 		url: '/'
28 | 	};
29 | 	const settings: DocumentOptions = { ...defaults, ...options };
30 | 
31 | 	const dom = new JSDOM(wrapBodyTag(body));
32 | 	dom.reconfigure({ url: `${baseURI}${settings.url}` });
33 | 
34 | 	vi.stubGlobal('location', dom.window.location);
35 | 	vi.stubGlobal('document', dom.window.document);
36 | };
37 | 
38 | /**
39 |  * Get an instance of FragmentPlugin, in the state after mount()
40 |  */
41 | export const getMountedPluginInstance = (options: Partial<Options> = {}): SwupFragmentPlugin => {
42 | 	const defaults = {
43 | 		rules: [],
44 | 		debug: true
45 | 	};
46 | 	const fragmentPlugin = new SwupFragmentPlugin({ ...defaults, ...options });
47 | 	new Swup({ plugins: [fragmentPlugin] });
48 | 	return fragmentPlugin;
49 | };
50 | 
51 | /**
52 |  * Spies on and optionally mutes console calls
53 |  */
54 | export const spyOnConsole = (mute: boolean = true) => {
55 | 	const console = {
56 | 		log: vi.spyOn(global.console, 'log'),
57 | 		warn: vi.spyOn(global.console, 'warn'),
58 | 		error: vi.spyOn(global.console, 'error')
59 | 	};
60 | 	if (mute) {
61 | 		for (const method of Object.keys(console)) {
62 | 			console[method] = console[method].mockImplementation(() => undefined);
63 | 		}
64 | 	}
65 | 	return console;
66 | };
67 | 


--------------------------------------------------------------------------------
/tests/vitest/modifyRules.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 2 | import { getMountedPluginInstance, spyOnConsole } from './inc/helpers.js';
 3 | 
 4 | const defaultRule = {
 5 | 	from: '/page-1/',
 6 | 	to: '/page-2/',
 7 | 	containers: ['#default']
 8 | };
 9 | const fragmentPlugin = getMountedPluginInstance({
10 | 	rules: [defaultRule]
11 | });
12 | 
13 | describe('modify fragment rules', () => {
14 | 	beforeEach(() => {
15 | 		spyOnConsole();
16 | 		/** Reset the rules */
17 | 		fragmentPlugin.setRules([defaultRule]);
18 | 	});
19 | 	afterEach(() => {
20 | 		vi.restoreAllMocks();
21 | 	});
22 | 
23 | 	it('should return unparsed raw rules', () => {
24 | 		expect(fragmentPlugin.getRules()).toEqual([defaultRule]);
25 | 	});
26 | 
27 | 	it('should provide API methods on the swup instance', () => {
28 | 		expect(fragmentPlugin.getRules).toBeTypeOf('function');
29 | 		expect(fragmentPlugin.setRules).toBeTypeOf('function');
30 | 		expect(fragmentPlugin.prependRule).toBeTypeOf('function');
31 | 		expect(fragmentPlugin.appendRule).toBeTypeOf('function');
32 | 	});
33 | 
34 | 	it('should provide access to prependRule() and appendRule()', () => {
35 | 		const prependRule = {
36 | 			from: '/corge/',
37 | 			to: '/grault/',
38 | 			containers: ['#corgegrault']
39 | 		};
40 | 		const appendRule = {
41 | 			from: '/garply/',
42 | 			to: '/waldo/',
43 | 			containers: ['#garplywaldo']
44 | 		};
45 | 
46 | 		fragmentPlugin.prependRule(prependRule);
47 | 		fragmentPlugin.appendRule(appendRule);
48 | 
49 | 		expect(fragmentPlugin.getRules()).toEqual([prependRule, defaultRule, appendRule]);
50 | 	});
51 | 
52 | 	it('should provide access to getRules() and setRules()', () => {
53 | 		/** Add a rule using the plugin's API, *after* the existing rules */
54 | 		const appendRule = {
55 | 			from: '/foo/',
56 | 			to: '/bar/',
57 | 			containers: ['#foobar'],
58 | 			name: 'from-plugin'
59 | 		};
60 | 		fragmentPlugin.setRules([...fragmentPlugin.getRules(), appendRule]);
61 | 
62 | 		/** Add a rule using swup's API, *before* the existing rules */
63 | 		const prependRule = {
64 | 			from: '/baz/',
65 | 			to: '/bat/',
66 | 			containers: ['#bazbat'],
67 | 			name: 'from-swup'
68 | 		};
69 | 		fragmentPlugin.setRules([prependRule, ...fragmentPlugin.getRules()]);
70 | 
71 | 		expect(fragmentPlugin.getRules()).toEqual([prependRule, defaultRule, appendRule]);
72 | 	});
73 | 
74 | 	it('should remove rules', () => {
75 | 		fragmentPlugin.appendRule({
76 | 			from: '/foo/',
77 | 			to: '/bar/',
78 | 			containers: ['#foobar'],
79 | 			name: 'remove-me'
80 | 		});
81 | 		const rules = fragmentPlugin.getRules();
82 | 		fragmentPlugin.setRules(rules.filter((rule) => rule.name !== 'remove-me'));
83 | 		expect(fragmentPlugin.getRules()).toEqual([defaultRule]);
84 | 	});
85 | });
86 | 


--------------------------------------------------------------------------------
/tests/vitest/normalizeUrl.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { normalizeUrl } from '../../src/inc/functions.js';
 3 | 
 4 | describe('normalizeUrl()', () => {
 5 | 	it('should strip any amount of trailing slashes from the pathname', () => {
 6 | 		expect(normalizeUrl('/foo')).toEqual('/foo');
 7 | 		expect(normalizeUrl('/foo/')).toEqual('/foo');
 8 | 		expect(normalizeUrl('/foo/bar/')).toEqual('/foo/bar');
 9 | 		expect(normalizeUrl('/foo///')).toEqual('/foo');
10 | 		expect(normalizeUrl('/foo/?bar=baz')).toEqual('/foo?bar=baz');
11 | 	});
12 | 	it('should ignore empty URLs', () => {
13 | 		expect(normalizeUrl('')).toEqual('');
14 | 	});
15 | 	it('should sort the query string', () => {
16 | 		expect(normalizeUrl('/foo?b=b&a=a')).toEqual('/foo?a=a&b=b');
17 | 	});
18 | });
19 | 


--------------------------------------------------------------------------------
/tests/vitest/queryFragmentElement.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { stubGlobalDocument } from './inc/helpers.js';
 3 | import { queryFragmentElement } from '../../src/inc/functions.js';
 4 | import Swup from 'swup';
 5 | 
 6 | describe('queryFragmentElement()', () => {
 7 | 	it('should correctly query fragment elements', () => {
 8 | 		const swup = new Swup();
 9 | 		stubGlobalDocument(/*html*/ `
10 | 			<div id="swup" class="transition-main"><div id="fragment-1"></div></div>
11 | 			<div id="fragment-2"></div>
12 | 		`);
13 | 		expect(queryFragmentElement('#swup', swup)).toBeDefined();
14 | 		expect(queryFragmentElement('#fragment-1', swup)).toBeDefined();
15 | 		expect(queryFragmentElement('#missing', swup)).toBeUndefined();
16 | 		expect(queryFragmentElement('#fragment-2', swup)).toBeUndefined();
17 | 	});
18 | });
19 | 


--------------------------------------------------------------------------------
/tests/vitest/shouldSkipAnimation.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { shouldSkipAnimation } from '../../src/inc/functions.js';
 3 | import { stubGlobalDocument } from './inc/helpers.js';
 4 | 
 5 | describe('shouldSkipAnimation()', () => {
 6 | 	it('should skip the animation if all fragments are <template> elements', () => {
 7 | 		const fragmentVisit = {
 8 | 			containers: ['#fragment-1', '#fragment-2'],
 9 | 			scroll: false
10 | 		};
11 | 		/** all are <template> elements */
12 | 		stubGlobalDocument(/*html*/ `<div id="swup" class="transition-main">
13 | 			<template id="fragment-1"></template>
14 | 			<template id="fragment-2"></template>
15 | 		</div>`);
16 | 		expect(shouldSkipAnimation(fragmentVisit)).toBe(true);
17 | 
18 | 		/** some are not <template> elements */
19 | 		stubGlobalDocument(/*html*/ `<div id="swup" class="transition-main">
20 | 			<template id="fragment-1"></template>
21 | 			<div id="fragment-2"></div>
22 | 		</div>`);
23 | 		expect(shouldSkipAnimation(fragmentVisit)).toBe(false);
24 | 	});
25 | });
26 | 


--------------------------------------------------------------------------------
/tests/vitest/toggleFragmentVisitClass.test.ts:
--------------------------------------------------------------------------------
 1 | import { describe, expect, it } from 'vitest';
 2 | import { toggleFragmentVisitClass } from '../../src/inc/functions.js';
 3 | import { stubGlobalDocument } from './inc/helpers.js';
 4 | import { FragmentVisit } from '../../src/index.js';
 5 | 
 6 | describe('toggleFragmentVisitClass()', () => {
 7 | 	it("should toggle a fragment visit's name on the classList of all fragment elements", () => {
 8 | 		stubGlobalDocument(/*html*/ `
 9 | 			<div id="swup" class="transition-main">
10 | 				<div id="fragment-1"></div>
11 | 				<div id="fragment-2"></div>
12 | 			</div>`);
13 | 
14 | 		const fragmentVisit: FragmentVisit = {
15 | 			name: 'test',
16 | 			containers: ['#fragment-1', '#fragment-2'],
17 | 			scroll: false
18 | 		};
19 | 
20 | 		toggleFragmentVisitClass(fragmentVisit, true);
21 | 		expect(document.querySelector('#fragment-1')?.classList.contains(`to-test`)).toBe(true);
22 | 		expect(document.querySelector('#fragment-2')?.classList.contains(`to-test`)).toBe(true);
23 | 
24 | 		toggleFragmentVisitClass(fragmentVisit, false);
25 | 		expect(document.querySelector('#fragment-1')?.classList.contains(`to-test`)).toBe(false);
26 | 		expect(document.querySelector('#fragment-2')?.classList.contains(`to-test`)).toBe(false);
27 | 	});
28 | 
29 | 	it("should't add classes if the current fragment visit doesn't have a `name`", () => {
30 | 		stubGlobalDocument(/*html*/ `
31 | 			<div id="swup" class="transition-main">
32 | 				<div id="fragment-1"></div>
33 | 			</div>`);
34 | 
35 | 		const fragmentVisit: FragmentVisit = {
36 | 			containers: ['#fragment-1', '#fragment-2'],
37 | 			scroll: false
38 | 		};
39 | 
40 | 		toggleFragmentVisitClass(fragmentVisit, true);
41 | 		expect(document.querySelector('#fragment-1')?.classList.contains(`to-test`)).toBe(false);
42 | 	});
43 | });
44 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   /** @see https://www.totaltypescript.com/tsconfig-cheat-sheet#quickstart */
 3 |   "include": ["src"],
 4 |   "compilerOptions": {
 5 |     /* Base Options: */
 6 |     "esModuleInterop": true,
 7 |     "skipLibCheck": true,
 8 |     "target": "es2022",
 9 |     "verbatimModuleSyntax": true,
10 |     "allowJs": true,
11 |     "resolveJsonModule": true,
12 |     "moduleDetection": "force",
13 |     /* Strictness */
14 |     "strict": true,
15 |     /* If transpiling with TypeScript: */
16 |     "moduleResolution": "NodeNext",
17 |     "module": "NodeNext",
18 |     "rootDir": "src",
19 |     "outDir": "dist",
20 |     "sourceMap": true,
21 |     /* If your code runs in the DOM: */
22 |     "lib": ["es2022", "dom", "dom.iterable"],
23 |     /* If you're building for a library: */
24 |     "declaration": true,
25 |     /* If you're building for a library in a monorepo: */
26 |     "declarationMap": true
27 |   },
28 | }
29 | 


--------------------------------------------------------------------------------