Source: dist/extras/offline-notification/offline-notification.js

/**
 * Extra - Offline Notification
 *
 * Renders a small notification bar at the very top of <body> when the browser
 * reports no network connection. It lets users know they are viewing a cached,
 * offline copy of the site and that some features may be unavailable until a
 * connection is restored.
 *
 * This complements the service worker's offline cache: the service worker
 * serves previously fetched content while the connection is down, and this
 * notification keeps users informed of the offline state.
 *
 * **Initialization**
 *
 * To load this plugin, add it to the `extras` block of your
 * [config.php](https://markdownmaster.com/docs/site-configuration.html) or
 * theme [settings.php](https://markdownmaster.com/docs/theme-development.html):
 *
 * ```php
 * 'extras' => [
 *     // ...
 *
 *     'offline-notification' => [],
 *
 *     // ...
 * ],
 * ```
 *
 * @module Extras/OfflineNotification
 * @license The MIT License (MIT)
 * @copyright (c) 2026 eVAL Agency
 * @author Charlie Powell
 * @see https://markdownmaster.com/docs/extras/offline-notification.html
 * @since 6.0.0
 */

/**
 * The notification element currently in the document body, or null.
 *
 * @type {HTMLElement|null}
 */
let notificationElement = null;

/**
 * Reference to the CMS instance.
 *
 * `window.CMS` is set when the CMS core boots (see `src/app/main.js`).
 * The guard below also covers the edge case where this script runs before
 * the core is ready.
 *
 * @type {Object|null}
 */
const cms = window.CMS;

/**
 * Used to track if a connection was lost and subsequently reconnected.
 *
 * @type {boolean}
 */
let wasOffline = false;

/**
 * Time the script started so we can ignore sub-2-second flickers during page load/reload.
 * @type {DOMHighResTimeStamp}
 */
const PAGE_LOAD_TIME = performance.now();

/**
 * Safely fetch a single extra option.
 *
 * @param {string} name  Plugin name
 * @param {string} key   Option key
 * @param {*} defaultValue
 * @returns {*}
 */
function extraOption(name, key, defaultValue) {
	if (!cms || !cms.config) {
		return defaultValue;
	}
	return cms.config.extra(name, key, defaultValue);
}

/**
 * Options resolved for this plugin.
 *
 * @type {Object}
 */
const options = {
	// Auto-load the bundled default stylesheet.
	styles: extraOption('offline-notification', 'styles', true),

	// Body message explaining the offline state.
	message: extraOption('offline-notification', 'message',
		'Connection to the server was lost. You are viewing an offline ' +
		'version of this site and some features may be unavailable until you ' +
		'reconnect.'
	),

	// Show the leading warning glyph.
	showIcon: extraOption('offline-notification', 'showIcon', true),

	// Auto reload on reconnection
	autoReload: extraOption('offline-notification', 'autoReload', true),
};

/**
 * Adds the plugin's default stylesheet to the document head if enabled and
 * not already present.
 *
 * @function
 */
function loadStyles() {
	// Nothing to do if the core is not (yet) available.
	if (!cms || !cms.config) {
		return;
	}

	// Skip if the theme (or a user) has already loaded a stylesheet for this
	// plugin, so we don't double-load it.
	if (document.querySelector('link[href*="offline-notification.css"]')) {
		return;
	}

	let style = document.createElement('link');
	style.rel = 'stylesheet';
	style.href = cms.config.webpath + 'extras/offline-notification/offline-notification.css';
	document.head.appendChild(style);
}

/**
 * Builds and inserts the notification element as the first child of <body>.
 *
 * @function
 */
function showNotification() {
	// A single notification element is sufficient; skip if already present.
	if (notificationElement) {
		return;
	}

	let body = document.body;
	if (!body) {
		// No body yet (e.g. extremely early load); retry shortly.
		setTimeout(showNotification, 16);
		return;
	}

	let notification = document.createElement('div');
	notification.className = 'offline-notification';
	notification.setAttribute('role', 'alert');
	notification.setAttribute('aria-live', 'assertive');

	if (options.showIcon) {
		let icon = document.createElement('span');
		icon.className = 'offline-notification__icon';
		icon.setAttribute('aria-hidden', 'true');
		icon.textContent = '\u26a0';
		notification.appendChild(icon);
	}

	let message = document.createElement('p');
	message.className = 'offline-notification__message';
	message.textContent = options.message;
	notification.appendChild(message);

	body.prepend(notification);
	notificationElement = notification;
}

/**
 * Removes the notification element from the document body.
 *
 * @function
 */
function hideNotification() {
	if (!notificationElement) {
		return;
	}

	notificationElement.remove();
	notificationElement = null;
}

/**
 * Syncs the notification visibility with the current network state.
 *
 * @function
 */
function updateNotification() {
	if (window.navigator.onLine) {
		hideNotification();
		if (options.autoReload && wasOffline) {
			window.location.reload();
		}
	} else {
		showNotification();
		if (performance.now() - PAGE_LOAD_TIME > 5000) {
			// Only mark that it was offline if it occurred after the initial page load.
			wasOffline = true;
		}
	}
}

/**
 * Bootstrap: register styles, react to connectivity changes, and sync with the
 * browser's current state.
 *
 * @function
 */
{
	if (options.styles) {
		loadStyles();
	}

	window.addEventListener('online', updateNotification);
	window.addEventListener('offline', updateNotification);

	// Reflect the state at the moment the plugin loads.
	updateNotification();
}