Merge pull request #16 from swup/next

Update for swup 4

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+<!-- ## [Unreleased] -->
+
+## [4.0.0] - 2023-07-26
+
+- Update for swup 4 compatibility
+
+## [3.0.0] - 2023-03-10
+
+- Switch to microbundle
+- Export native ESM module
+
+## [2.1.0] - 2022-08-21
+
+- Set `aria-busy` on html element during transitions
+
+## [2.0.0] - 2021-03-15
+
+- Fix bundle name
+
+## [1.0.0] - 2020-08-10
+
+- Initial release
+
+[Unreleased]: https://github.com/swup/a11y-plugin/compare/4.0.0...HEAD
+
+[4.0.0]: https://github.com/swup/a11y-plugin/releases/tag/4.0.0
+[3.0.0]: https://github.com/swup/a11y-plugin/releases/tag/3.0.0
+[2.1.0]: https://github.com/swup/a11y-plugin/releases/tag/2.1.0
+[2.0.0]: https://github.com/swup/a11y-plugin/releases/tag/2.0.0
+[1.0.0]: https://github.com/swup/a11y-plugin/releases/tag/1.0.0

readme.md → README.md

@@ -1,37 +1,29 @@
 # Swup A11y Plugin
 
-**by [daun](https://github.com/daun)**
+A [swup](https://swup.js.org) plugin for enhanced accessibility.
 
-Enhance the accessibility of your [swup](https://github.com/swup/swup)-powered
-sites.
-
-Loading new content via AJAX is great UX for most users, but comes with serious
-shortcomings for screen reader users. We can improve the experience for
-everybody if we:
+Loading new content via AJAX is a great experience for most users, but comes with serious
+shortcomings for screen reader users. This plugin will improve that:
 
 - **Announce page visits** to screenreaders by reading the new page title
 - **Focus the main content area** after swapping out the content
 
-That's exactly what this plugin does.
-
 ## Installation
 
-This plugin can be installed with npm
+Install the plugin from npm and import it into your bundle.
 
 ```bash
 npm install @swup/a11y-plugin
 ```
 
-and included with import
-
-```shell
+```js
 import SwupA11yPlugin from '@swup/a11y-plugin';
 ```
 
-or included from the dist folder
+Or include the minified production file from a CDN:
 
 ```html
-<script src="./dist/SwupA11yPlugin.js"></script>
+<script src="https://unpkg.com/@swup/a11y-plugin@4"></script>
 ```
 
 ## Usage
@@ -60,6 +52,12 @@ See the options below for customizing what elements to look for.
 </main>
 ```
 
+If you want the announcement to be different from the text content, use `aria-label`:
+
+```html
+<h1 aria-label="Homepage">Project Title</h1> <!-- will announce 'Homepage' -->
+```
+
 ## Styling
 
 Browsers will display a visible outline around the main content area when it
@@ -95,8 +93,7 @@ This area will receive focus after a new page was loaded.
 
 The selector for finding headings **inside the main content area**.
 
-The first heading's content will be read to screen readers after a new page was
-loaded.
+The first heading's content will be read to screen readers after a new page was loaded.
 
 ### announcementTemplate
 

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@swup/a11y-plugin",
   "amdName": "SwupA11yPlugin",
-  "version": "3.0.0",
-  "description": "Enhanced accessibility for swup-powered sites",
+  "version": "4.0.0",
+  "description": "A swup plugin for enhanced accessibility",
   "type": "module",
   "source": "src/index.js",
   "main": "./dist/index.cjs",
@@ -17,7 +17,7 @@
     "dev": "swup-plugin dev",
     "lint": "swup-plugin lint",
     "format": "swup-plugin format",
-    "prepublish": "npm run build"
+    "prepublishOnly": "npm run build"
   },
   "author": {
     "name": "Philipp Daun",
@@ -42,12 +42,12 @@
     "url": "https://github.com/swup/a11y-plugin.git"
   },
   "dependencies": {
-    "@swup/plugin": "^2.0.0",
+    "@swup/plugin": "^3.0.0",
     "focus-options-polyfill": "^1.5.0",
     "on-demand-live-region": "^0.1.3"
   },
   "peerDependencies": {
-    "swup": "^3.0.0"
+    "swup": "^4.0.0"
   },
   "browserslist": [
     "extends @swup/browserslist-config"

src/index.js

@@ -6,46 +6,47 @@ import 'focus-options-polyfill';
 export default class SwupA11yPlugin extends Plugin {
 	name = 'SwupA11yPlugin';
 
+	requires = { swup: '>=4' };
+
+	defaults = {
+		contentSelector: 'main',
+		headingSelector: 'h1, h2, [role=heading]',
+		announcementTemplate: 'Navigated to: {title}',
+		urlTemplate: 'New page at {url}'
+	};
+
 	constructor(options = {}) {
 		super();
 
-		this.options = {
-			contentSelector: 'main',
-			headingSelector: 'h1, h2, [role=heading]',
-			announcementTemplate: 'Navigated to: {title}',
-			urlTemplate: 'New page at {url}',
-			...options
-		};
+		this.options = { ...this.defaults, ...options };
 
 		this.liveRegion = new OnDemandLiveRegion();
 	}
 
 	mount() {
-		this.swup.on('contentReplaced', this.announceVisit);
-		this.swup.on('transitionStart', this.onTransitionStart);
-		this.swup.on('transitionEnd', this.onTransitionEnd);
+		this.on('visit:start', this.markAsBusy);
+		this.on('visit:end', this.unmarkAsBusy);
+		this.on('content:replace', this.announceVisit);
+	}
+
+	markAsBusy() {
+		document.documentElement.setAttribute('aria-busy', 'true');
 	}
 
-	unmount() {
-		this.swup.off('contentReplaced', this.announceVisit);
-		this.swup.off('transitionStart', this.onTransitionStart);
-		this.swup.off('transitionEnd', this.onTransitionEnd);
+	unmarkAsBusy() {
+		document.documentElement.removeAttribute('aria-busy');
 	}
 
-	announceVisit = () => {
+	announceVisit() {
 		requestAnimationFrame(() => {
 			this.announcePageName();
 			this.focusPageContent();
-		});
-	};
+		})
+	}
 
-	announcePageName = () => {
-		const {
-			contentSelector,
-			headingSelector,
-			urlTemplate,
-			announcementTemplate
-		} = this.options;
+	announcePageName() {
+		const { contentSelector, headingSelector, urlTemplate, announcementTemplate } =
+			this.options;
 
 		// Default: announce new /path/of/page.html
 		let pageName = urlTemplate.replace('{url}', window.location.pathname);
@@ -67,21 +68,13 @@ export default class SwupA11yPlugin extends Plugin {
 
 		const announcement = announcementTemplate.replace('{title}', pageName.trim());
 		this.liveRegion.say(announcement);
-	};
+	}
 
-	focusPageContent = () => {
+	focusPageContent() {
 		const content = document.querySelector(this.options.contentSelector);
 		if (content) {
 			content.setAttribute('tabindex', '-1');
 			content.focus({ preventScroll: true });
 		}
-	};
-
-	onTransitionStart = () => {
-		document.documentElement.setAttribute('aria-busy', 'true');
-	};
-
-	onTransitionEnd = () => {
-		document.documentElement.removeAttribute('aria-busy');
-	};
+	}
 }