@peckadesign/pd-naja 1.0.0

package/.editorconfig

@@ -0,0 +1,14 @@
+# editorconfig.org
+root = true
+
+[*]
+indent_style = tab
+tab_width = unset
+indent_size = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.eslintrc.js

@@ -0,0 +1,12 @@
+require('@rushstack/eslint-patch/modern-module-resolution')
+
+module.exports = {
+	root: true,
+	extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended', 'prettier'],
+	rules: {
+		'@typescript-eslint/ban-ts-comment': 'off',
+		'@typescript-eslint/no-explicit-any': 'off',
+		'prettier/prettier': 1
+	},
+	ignorePatterns: ['*.js']
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: ESLint
+    env:
+      CI: true
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v3
+
+      - name: Setup Node 📦
+        uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+          cache: npm
+
+      - name: Install dependencies 👨🏻‍💻
+        run: npm ci
+
+      - name: Lint ✨
+        run: npm run lint
+
+      - name: Build 🔨
+        run: npm run build

package/.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v3
+
+      - name: Setup Node 📦
+        uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+          cache: npm
+
+      - name: Install dependencies 👨🏻‍💻
+        run: npm ci
+
+      - name: Build 🔨
+        run: npm run build
+
+      - name: Download artifacts 🧩
+        uses: actions/upload-artifact@v3
+        with:
+          name: dist-files
+          path: dist/
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v3
+
+      - name: Download artifacts 🧩
+        uses: actions/download-artifact@v3
+        with:
+          name: dist-files
+          path: dist/
+
+      - name: Create release draft 🕊️
+        uses: softprops/action-gh-release@v1
+        with:
+          draft: true
+          files: |
+            dist/PdModal.js
+            dist/PdModal.js.map
+            dist/PdModal.min.js
+            dist/PdModal.min.js.map
+
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v3
+
+      - name: Download artifacts 🧩
+        uses: actions/download-artifact@v3
+        with:
+          name: dist-files
+          path: dist/
+
+      - name: Setup Node 📦
+        uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish release 🕊️
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+	"singleQuote": true,
+	"semi": false,
+	"trailingComma": "none",
+	"printWidth": 120
+}

package/README.md

@@ -0,0 +1,90 @@
+# pd-naja
+
+1. [Quick start](#quick-start)
+2. [Utilities](#utilities)
+3. [Extensions](#extensions)
+   1. [AjaxModalExtension](#ajaxmodalextension)
+   2. [SpinnerExtension](#spinnerextension)
+
+## Quick start
+```
+$ npm install naja @peckadesign/pd-naja
+```
+
+```typescript
+import naja from 'naja'
+import { ExtensionName } from '@peckadesign/pd-naja'
+
+naja.registerExtension(new ExtensionName())
+```
+
+```typescript
+import { controlManager } from '@peckadesign/pd-naja'
+import SomeControl from '@/js/Controls/SomeControl' // `SomeControl` must implement `Control` interface
+import SomeAnotherControl from '@/js/Controls/SomeControl'
+
+// This control is only initialized on page load
+controlManager.addControlOnLoad(SomeControl)
+
+// This control will also get initialized after Naja requests
+controlManager.addControlOnLive(SomeControl)
+
+```
+
+## Utilities
+This package provides easy ways to add JS components reactive to Naja ajax events.
+
+`Control` is meant to be used for standalone components, that might be dependent on ajax. It should be used together with `ControlManager`. Class implementing the `Control` interface **should export its instance**. Then the intended lifecycle of class is as follows:
+
+1. `constructor` is called immediately and is also called only once. This is the ideal place for e.g. adding common event handlers to the `body`, or modifying necessary DOM properties on elements not affected by ajax.
+
+2. The instantiated class is then added to ControlManager either by `addControlOnLoad` or `addControlOnLive`. This ensures, that on `DOMContentLoaded` the `initialize` function of class is called. This method should implement initialization of the control dependent on fully loaded DOM. The `context` argument is equal to `document` in this call.
+
+3. In case of `addControlOnLive` used, the `initialize` method is also called for each success ajax request. The `context` argument is equal to modified nette snippet.
+
+
+## Extensions
+
+### `AjaxModalExtension`
+This extension allows you to implement modal window with browser history using Naja. Extension itself is agnostic of used modal, you can use any modal plugin you want as long as you provide simple adapter implementing `AjaxModal` interface. Class implementing `AjaxModal` is only parameter recieved by constructor.
+
+```typescript
+import naja from 'naja'
+import { AjaxModalExtension } from '@peckadesign/pd-naja'
+import { modal } from '@/js/App/PdModal' // modal must implement AjaxModal interface 
+
+naja.registerExtension(
+	new AjaxModalExtension(modal)
+)
+```
+
+#### Interface `AjaxModal`
+| Property                                                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                            |
+|-----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `element: Element`                                                                                                                            | Most outer element of the modal window.                                                                                                                                                                                                                                                                                                                |
+| `reservedSnippetIds: string[]`                                                                                                                | List of snippet id's, that are neccessary for modal to work, e.g. `snippet--modal`.                                                                                                                                                                                                                                                                    |
+| `show(opener: Element \| undefined, options: any, event: BeforeEvent \| PopStateEvent): void`                                                 | Method that is called for opening the modal. `opener` is the element causing the opening, event is the associated event.                                                                                                                                                                                                                               |
+| `hide(event: SuccessEvent \| PopStateEvent): void`                                                                                            | Method that is called for closing the modal either as a result of `closeModal` property in ajax response or as a result of navigating using browser history.                                                                                                                                                                                           |                                            
+| `isShown(): boolean`                                                                                                                          | Should return wheter the modal is opened or not.                                                                                                                                                                                                                                                                                                       |
+| `onShow: (callback: EventListener) => void`<br/>`onHide: (callback: EventListener) => void`<br/>`onHidden: (callback: EventListener) => void` | The extension needs to attach some handlers when show, hide or hidden happens. These functions should provide a way to add listeners to such events.                                                                                                                                                                                                   |
+| `dispatchLoad?: (options: any, event: SuccessEvent \| PopStateEvent) => void`                                                                 | If you provide this method, extension will call it whenever the content is changed (loaded).                                                                                                                                                                                                                                                           |
+| `getOptions(opener: Element): any`                                                                                                            | If you need to change some modal settings based on opener element, you can do that in this function. Return value of this function is stored in `localStorage` (or wherever is Naja configured to store states) and also in `HistoryState`. Bear in mind that this introduces some limitations of what can be returned (e.g. no `Element` is allowed). | 
+| `setOptions(options: any): void`                                                                                                              | Counterpart of `getOptions` method, you can use this method to restore modal settings based on `options`.                                                                                                                                                                                                                                              |
+
+### `SpinnerExtension`
+
+This extension allows you to add configurable loading indicator to ajax request. Constructor recieves following 4 parameters:
+
+| Parameter                                                                | Description                                                                                                                                                             |
+|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `spinner: ((props?: any) => Element) \| Element`                         | Mandatory parameter. It should either be function return the spinner element, or directly element.                                                                      |
+| `getSpinnerProps: ((initator: Element) => any) \| undefined = undefined` | If you provide `spinner` as a function, you might also provide function to get settings from ajax initiator. Returned value is passed as a `props` to `spinner()` call. |
+| `ajaxSpinnerWrapSelector = '.ajax-wrap'`  | See below.                                                                                                                                                              |
+|`ajaxSpinnerPlaceholderSelector = '.ajax-spinner'`| See below                                                                                                                                                               |
+
+The logic for spinner placeholder is as follows:
+1. Extension can be turned off by using `data-naja-spinner="off"`.
+2. If there is `data-naja-spinner` with different value, this value is used as a selector for element into which the spinner element is appended.
+3. If there is no `data-naja-spinner`, closest `ajaxSpinnerWrapSelector` is being searched for and:
+   1. If there is `ajaxSpinnerPlaceholderSelector` inside, this element is used for placing spinner element.
+   2. If not, the spinner element is appended into `ajaxSpinnerWrapSelector` itself.

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@peckadesign/pd-naja",
+	"title": "PD Naja utils & extensions",
+	"version": "1.0.0",
+	"private": false,
+	"description": "Utilities and extensions created for use with Naja library.",
+	"module": "dist/PdNaja.esm.js",
+	"types": "dist/index.esm.d.ts",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/peckadesign/pd-naja.git"
+	},
+	"keywords": [
+		"naja",
+		"extension",
+		"ajax",
+		"typescript",
+		"vanilla",
+		"javascript"
+	],
+	"author": {
+		"name": "PeckaDesign, s.r.o",
+		"email": "support@peckadesign.cz"
+	},
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/peckadesign/pd-naja/issues"
+	},
+	"homepage": "https://github.com/peckadesign/pd-naja#readme",
+	"dependencies": {
+		"naja": "^2.5.0"
+	},
+	"scripts": {
+		"build": "NODE_ENV=production rollup -c --bundleConfigAsCjs",
+		"lint": "NODE_ENV=development eslint src --ext .ts --max-warnings=0"
+	},
+	"devDependencies": {
+		"@rollup/plugin-babel": "^6.0.3",
+		"@rollup/plugin-commonjs": "^24.1.0",
+		"@rollup/plugin-node-resolve": "^15.0.2",
+		"@rollup/plugin-typescript": "^11.1.0",
+		"@rushstack/eslint-patch": "^1.2.0",
+		"eslint": "^8.40.0",
+		"eslint-config-prettier": "^8.8.0",
+		"eslint-config-typescript": "^3.0.0",
+		"eslint-plugin-prettier": "^4.2.1",
+		"prettier": "^2.8.8",
+		"rollup": "^3.21.6",
+		"typescript": "^5.0.4"
+	}
+}

package/rollup.config.js

@@ -0,0 +1,61 @@
+import babel from '@rollup/plugin-babel';
+import commonjs from '@rollup/plugin-commonjs';
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from '@rollup/plugin-typescript';
+import path from 'path';
+
+import pkg from './package.json';
+const output = {
+	banner: `/**\n * ${pkg.title} - ${pkg.description} \n * ${pkg.homepage}\n *\n * @author ${pkg.author.name} <${pkg.author.email}>\n * @license ${pkg.license}\n *\n * @version ${pkg.version}\n */\n`,
+	sourcemap: true,
+};
+
+const babelPlugin = babel({
+	exclude: /node_modules/,
+	include: 'src/**',
+	babelHelpers: 'runtime',
+});
+
+export default [
+	{
+		// ESM build for modern tools like webpack
+		input: 'src/index.esm.ts',
+		output: {
+			...output,
+			file: pkg.module,
+			format: 'esm',
+		},
+		external: [
+			/@babel\/runtime/,
+			...Object.keys(pkg.dependencies || {}),
+			...Object.keys(pkg.peerDependencies || {}),
+		],
+		plugins: [
+			resolve(),
+			commonjs(),
+			typescript(),
+			babelPlugin,
+		],
+	},
+	{
+		// type declaration files for ESM build
+		input: 'src/index.esm.ts',
+		output: {
+			...output,
+			dir: path.dirname(pkg.module),
+			format: 'esm',
+		},
+		external: [
+			/@babel\/runtime/,
+			...Object.keys(pkg.dependencies || {}),
+			...Object.keys(pkg.peerDependencies || {}),
+		],
+		plugins: [
+			typescript({
+				declaration: true,
+				declarationDir: path.dirname(pkg.module),
+				emitDeclarationOnly: true,
+			}),
+		],
+	},
+];

package/src/extensions/AjaxModalExtension.ts

@@ -0,0 +1,375 @@
+import { Naja, BeforeEvent, CompleteEvent, StartEvent, SuccessEvent, Options, Extension } from 'naja/dist/Naja'
+import { BuildStateEvent, HistoryState } from 'naja/dist/core/HistoryHandler'
+import { InteractionEvent } from 'naja/dist/core/UIHandler'
+import { FetchEvent } from 'naja/dist/core/SnippetCache'
+
+declare module 'naja/dist/Naja' {
+	interface Options {
+		pdModal?: boolean
+		modalOpener?: Element
+		modalOptions?: any
+	}
+
+	interface Payload {
+		closeModal?: boolean
+	}
+}
+
+type CallbackFn = (callback: EventListener) => void
+
+export interface AjaxModal {
+	// main element of the modal
+	element: Element
+
+	// id's of snippets, that are necessary for modal function
+	reservedSnippetIds: string[]
+
+	show(opener: Element | undefined, options: any, event: BeforeEvent | PopStateEvent): void
+	hide(event: SuccessEvent | PopStateEvent): void
+	isShown(): boolean
+
+	onShow: CallbackFn
+	onHide: CallbackFn
+	onHidden: CallbackFn
+
+	dispatchLoad?: (options: any, event: SuccessEvent | PopStateEvent) => void
+
+	getOptions(opener: Element): any
+	setOptions(options: any): void
+}
+
+interface HistoryStateWrapper extends Record<string, any> {
+	location: string
+	state: HistoryState
+	title: string
+}
+
+type HistoryDirection = 'forwards' | 'backwards'
+
+export class AjaxModalExtension implements Extension {
+	private readonly modal: AjaxModal
+	private readonly uniqueExtKey: string = 'modal'
+
+	private popstateFlag = false
+	private hidePopstateFlag = false
+
+	private historyEnabled = false // (dis)allows `pushState` after hiding the modal when going back in history (popstate), we don't want to push new state into history same is true also when the history is disabled for request altogether
+	private historyDirection: HistoryDirection = 'backwards'
+
+	private modalOptions: any = {}
+
+	private original: HistoryStateWrapper[] = [] // stack of states under the modal after hiding the modal with `forwards` history mode, we need to push the previous state
+	private lastState: HistoryStateWrapper | null = null
+	private initialState: HistoryState | Record<string, never>
+
+	private readonly abortControllers: Map<string, AbortController> = new Map()
+
+	public constructor(modal: AjaxModal) {
+		// Extension popstate has to be executed before naja popstate, so we can correctly detect if the pdModal is
+		// opened. Therefore, we bind the callback before the extension initialization itself.
+		window.addEventListener('popstate', this.popstateHandler.bind(this))
+
+		this.modal = modal
+		this.initialState = history.state || {}
+	}
+
+	public initialize(naja: Naja): void {
+		naja.uiHandler.addEventListener('interaction', this.checkExtensionEnabled.bind(this))
+
+		naja.historyHandler.addEventListener('buildState', this.buildState.bind(this))
+
+		naja.snippetCache.addEventListener('fetch', this.onSnippetFetch.bind(this))
+
+		naja.addEventListener('before', this.before.bind(this))
+		naja.addEventListener('start', this.abortPreviousRequest.bind(this))
+		naja.addEventListener('success', this.success.bind(this))
+		naja.addEventListener('complete', this.clearRequest.bind(this))
+
+		this.modal.onShow(this.showHandler.bind(this))
+		this.modal.onHide(() => {
+			this.removeModalSnippetsIds()
+			this.abortControllers.get('modal')?.abort()
+		})
+		this.modal.onHidden(this.hiddenHandler.bind(this))
+	}
+
+	private isRequestWithHistory = (options: Options): boolean => {
+		return options.history !== false
+	}
+
+	private isPdModalState = (state: HistoryState | Record<string, never>): boolean => {
+		return 'pdModal' in state && state.pdModal?.isShown
+	}
+
+	private restoreExtensionPropertiesFromState = (state: HistoryState): void => {
+		this.historyEnabled = true // Called from popstateHandler means the history is enabled
+		this.historyDirection = state.pdModal.historyDirection
+		this.modalOptions = state.pdModal.options
+	}
+
+	private checkExtensionEnabled(event: InteractionEvent): void {
+		const { element, options } = event.detail
+
+		options.pdModal =
+			this.modal.isShown() ||
+			element.hasAttribute('data-naja-modal') ||
+			(element as HTMLInputElement).form?.hasAttribute('data-naja-modal')
+
+		// If the extension is enabled and modal is not opened, we detect and store history mode. History mode cannot
+		// change when traversing ajax link inside modal.
+		if (!options.pdModal) {
+			return
+		}
+
+		// `modalOptions` will be stored in state, therefore no `Element` is allowed. These options are also forwarded
+		// to other Naja event handlers via `options`. We also store the element separately to be used there as well.
+		this.modalOptions = this.modal.getOptions(element)
+
+		options.modalOptions = this.modalOptions
+		options.modalOpener = element
+
+		// History direction can only be set before opening the modal, then it stays the same until modal is hidden.
+		if (!this.modal.isShown()) {
+			this.historyDirection = element.getAttribute('data-naja-modal-history') === 'forwards' ? 'forwards' : 'backwards'
+		}
+	}
+
+	private onSnippetFetch(event: FetchEvent): void {
+		event.detail.options.pdModal = 'pdModal' in event.detail.state
+	}
+
+	private removeModalSnippetsIds(): void {
+		// When closing the modal, we don't want to update any snippets inside it, when other requests finishes. This
+		// will ensure, that snippets that might be also outside modal (e.g. flash messages) will be redrawn outside the
+		// modal. Therefore, we remove the id attributes, so no snippet is found.
+		//
+		// Some snippets are necessary for modal function
+		this.modal.element.querySelectorAll('[id^="snippet-"]').forEach((snippet) => {
+			if (!this.modal.reservedSnippetIds.includes(snippet.id)) {
+				snippet.removeAttribute('id')
+			}
+		})
+	}
+
+	private abortPreviousRequest(event: StartEvent): void {
+		const { abortController, options } = event.detail
+		if (options.pdModal) {
+			this.abortControllers.get(this.uniqueExtKey)?.abort()
+			this.abortControllers.set(this.uniqueExtKey, abortController)
+		}
+	}
+
+	private clearRequest(event: CompleteEvent): void {
+		const { request } = event.detail
+		if (!request.signal.aborted) {
+			this.abortControllers.delete(this.uniqueExtKey)
+		}
+	}
+
+	private buildState(event: BuildStateEvent): void {
+		const { options, state } = event.detail
+
+		// Every time naja builds the state, we extend it with `pdModal` object containing information about modal being
+		// opened and what history mode is in use. When options.forceRedirect is set, modal might be open but the new
+		// state will be redirected outside it.
+		const isShown: boolean = this.modal.isShown() && !options.forceRedirect
+		state.pdModal = {
+			isShown,
+			historyDirection: isShown ? this.historyDirection : null,
+			options: isShown ? this.modalOptions : null
+		}
+
+		// If the state is build, the history is enabled. This information is needed inside modal callback where the
+		// options are not available, so we store this internally in extension.
+		this.historyEnabled = true
+	}
+
+	private before(event: BeforeEvent) {
+		const { options, request } = event.detail
+		if (!options.pdModal) {
+			return
+		}
+
+		this.modal.show(options.modalOpener, options.modalOptions, event)
+
+		request.headers.append('Pd-Modal-Opened', String(Number(this.modal.isShown())))
+	}
+
+	private success(event: SuccessEvent) {
+		const { options, payload } = event.detail
+
+		this.popstateFlag = false
+		this.lastState = {
+			location: location.href,
+			state: history.state,
+			title: document.title
+		}
+
+		if (!options.pdModal) {
+			return
+		}
+
+		const requestHistory = this.isRequestWithHistory(options)
+
+		// If the history is disabled for current request, we will disable it for all ajax links / forms in modal as well.
+		if (!requestHistory && event.target) {
+			const ajaxified = this.modal.element.querySelectorAll<HTMLElement>((event.target as Naja).uiHandler?.selector)
+
+			ajaxified.forEach((element: HTMLElement) => {
+				element.setAttribute('data-naja-history', 'off')
+			})
+		}
+
+		if (payload.closeModal) {
+			this.modal.hide(event)
+		} else {
+			this.modal.setOptions(this.modalOptions)
+
+			if (this.modal.dispatchLoad) {
+				this.modal.dispatchLoad(this.modalOptions, event)
+			}
+		}
+	}
+
+	private showHandler() {
+		this.modal.setOptions(this.modalOptions)
+
+		// If the modal history mode is `forwards`, we store the state under the modal, so we can push it as a new state
+		// after hiding the modal.
+		if (this.historyDirection === 'forwards') {
+			if (this.popstateFlag && this.lastState) {
+				this.original.push(this.lastState)
+			} else {
+				const state: HistoryStateWrapper = {
+					location: location.href,
+					state: history.state,
+					title: document.title
+				}
+				this.original.push(state)
+			}
+		}
+	}
+
+	private hiddenHandler() {
+		// This method is called after modal has been hidden. It either pushes a new state into history (mode `forwards`)
+		// or calls `history.back()` to start go-back procedure.
+		//
+		// New state is pushed only if we are able to retrieve the state under the modal (which should have been stored
+		// previously) and the modal is not being closed using forward / back buttons in browser.
+		if (!this.historyEnabled) {
+			return
+		}
+
+		if (this.historyDirection === 'backwards') {
+			// We don't know how many states we need to return. We go one by one, see popstate handler. This go-back
+			// procedure is detected using `hidePopstateFlag`.
+			this.hidePopstateFlag = true
+			this.cleanData()
+			window.history.back()
+		} else if (this.historyDirection === 'forwards') {
+			const state = this.original.pop()
+			this.original = []
+
+			if (state) {
+				// When closing the modal using forward / back buttons in browser, the current state is the same as the
+				// one stored in `this.original`. If that's the case, we don't push anything as it would duplicate the
+				// state in history.
+				if (history.state === undefined || history.state.href !== state.location) {
+					history.pushState(state.state, state.title, state.location)
+					document.title = state.title
+
+					this.popstateFlag = false
+					this.lastState = {
+						location: state.location,
+						state: state.state,
+						title: state.title
+					}
+				}
+			}
+
+			this.cleanData()
+		}
+	}
+
+	private popstateHandler(event: PopStateEvent): void {
+		const state: HistoryState = event.state || this.initialState
+
+		if (typeof state === 'undefined' || !this.modal) {
+			return
+		}
+
+		const isCurrentStatePdModal = this.isPdModalState(state)
+		this.popstateFlag = true
+
+		// We don't know how many states we go back. So we go one by one until the new state is not modal state
+		// (`isPdModalState` is `false`).
+		if (this.hidePopstateFlag) {
+			// We don't want the naja popstate callback to be executed (or any other popstate handler).
+			event.stopImmediatePropagation()
+
+			if (isCurrentStatePdModal) {
+				window.history.back()
+
+				return
+			} else {
+				// Todo check if this is really necessary. When used with nette.ajax / history.nette.ajax, this was necessary in some cases, where the title hasn't been restored correctly.
+				if (state.title) {
+					document.title = state.title
+				}
+			}
+
+			this.hidePopstateFlag = false
+		}
+
+		// We check if the state has pdModal object present on popstate. If so (and the pdModal.isShown is true), we proceed
+		// to open the modal. Content of the modal is restored by naja itself (either from cache or by new request).
+		//
+		// If the initial state is also detected as pdModal state, we returned to some pdModal state using reload. In that
+		// case, we don't want to open the modal, because we might be missing some snippets. Effectively this means that the
+		// modal will never be opened by forward / back button if there has been some other site loaded outside the modal
+		// (e.g. some non-ajax link leading from modal).
+		if (isCurrentStatePdModal && !this.isPdModalState(this.initialState)) {
+			this.restoreExtensionPropertiesFromState(state)
+
+			this.modal.show(undefined, state.pdModal.options, event)
+
+			// If there is some snippet cache, we might restore modal options. If not, options will be restored based on
+			// options after the ajax request. Same applies to dispatching load event - if cache is on, we dispatch the
+			// event immediately, otherwise it will be dispatched after ajax request.
+			if (state.snippets?.storage !== 'off') {
+				this.modal.setOptions(state.pdModal.options)
+
+				if (this.modal.dispatchLoad) {
+					this.modal.dispatchLoad(this.modalOptions, event)
+				}
+			}
+		} else {
+			this.historyEnabled = false // Hiding modal using forward / back button, we disable the history to prevent state duplication
+
+			// Reload the page if the initial state has been inside modal. This prevents snippets loss e.g. during layout changes.
+			if (this.isPdModalState(this.initialState)) {
+				window.location.reload()
+			}
+
+			// Non-modal state and non-modal initial state, we just hide the current modal.
+			this.modal.hide(event)
+
+			// We don't want the naja popstate callback to be executed (or any other popstate handler).
+			event.stopImmediatePropagation()
+		}
+
+		// Keep track of current state. When `backwards` history mode is used, we eventually push this state into
+		// `this.original`.
+		this.lastState = {
+			location: location.href,
+			state: state,
+			title: document.title
+		}
+	}
+
+	private cleanData(): void {
+		this.historyEnabled = false
+		this.historyDirection = 'backwards'
+		this.modalOptions = null
+	}
+}

package/src/extensions/SpinnerExtension.ts

@@ -0,0 +1,132 @@
+import { CompleteEvent, Extension, Naja, StartEvent } from 'naja/dist/Naja'
+import { InteractionEvent } from 'naja/dist/core/UIHandler'
+
+/**
+ * @author Radek Šerý
+ *
+ * Spinner - loading indicator:
+ * 1. Extension can be turned off by using `data-naja-spinner="off"`.
+ * 2. If there is `data-naja-spinner` with different value, this value is used as a selector for element into which the spinner element is appended.
+ * 3. If there is no `data-naja-spinner`, closest `ajaxSpinnerWrapSelector` is being searched for and:
+ *    i.  If there is `ajaxSpinnerPlaceholderSelector` inside, this element is used for placing spinner element.
+ *    ii. If not, the spinner element is appended into `ajaxSpinnerWrapSelector` itself.
+ */
+
+declare module 'naja/dist/Naja' {
+	interface Options {
+		spinnerInitiator?: Element
+	}
+}
+
+type spinnerType = ((props?: any) => Element) | Element
+type spinnerPropsFn = ((initiator: Element) => any) | undefined
+
+export class SpinnerExtension implements Extension {
+	public readonly spinner: spinnerType
+	public readonly getSpinnerProps?: spinnerPropsFn
+
+	public readonly ajaxSpinnerWrapSelector: string
+	public readonly ajaxSpinnerPlaceholderSelector: string
+
+	public constructor(
+		spinner: spinnerType,
+		getSpinnerProps: spinnerPropsFn = undefined,
+		ajaxSpinnerWrapSelector = '.ajax-wrap',
+		ajaxSpinnerPlaceholderSelector = '.ajax-spinner'
+	) {
+		this.spinner = spinner
+		this.getSpinnerProps = getSpinnerProps
+
+		this.ajaxSpinnerWrapSelector = ajaxSpinnerWrapSelector
+		this.ajaxSpinnerPlaceholderSelector = ajaxSpinnerPlaceholderSelector
+	}
+
+	public initialize(naja: Naja): void {
+		naja.uiHandler.addEventListener('interaction', this.getSpinnerInitiator.bind(this))
+
+		naja.addEventListener('start', this.showSpinners.bind(this))
+		naja.addEventListener('complete', this.hideSpinners.bind(this))
+	}
+
+	private getSpinnerInitiator(event: InteractionEvent): void {
+		event.detail.options.spinnerInitiator = event.detail.element
+	}
+
+	private showSpinners(event: StartEvent): void {
+		const { options } = event.detail
+
+		if (!options.spinnerInitiator) {
+			return
+		}
+
+		const spinnerInitiator = options.spinnerInitiator
+		const placeholders = this.getPlaceholders(spinnerInitiator)
+
+		if (placeholders.length === 0) {
+			return
+		} else {
+			options.spinnerQueue = options.spinnerQueue || []
+
+			placeholders.forEach((placeholder) => {
+				let spinner: Element
+
+				if (typeof this.spinner === 'function') {
+					spinner = this.getSpinnerProps ? this.spinner(this.getSpinnerProps(spinnerInitiator)) : this.spinner()
+				} else {
+					spinner = this.spinner
+				}
+
+				placeholder.appendChild(spinner)
+				options.spinnerQueue.push(spinner)
+
+				spinner.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 100 })
+			})
+		}
+	}
+
+	private hideSpinners(event: CompleteEvent): void {
+		const { options } = event.detail
+
+		if (options.forceRedirect) {
+			return
+		}
+
+		options.spinnerQueue?.forEach((spinner: Element) => {
+			const animation = spinner.animate({ opacity: 0 }, { duration: 100 })
+			animation.finished.then(() => spinner.remove())
+		})
+	}
+
+	private getPlaceholders(element: Element): Element[] {
+		if (!element) {
+			return []
+		}
+
+		const spinner = element.getAttribute('data-naja-spinner') || null
+		let placeholders: Element[] = []
+
+		if (spinner === 'off') {
+			return []
+		}
+
+		placeholders = this.getPlaceholdersByQuerySelector(spinner)
+
+		return placeholders.length ? placeholders : this.getPlaceholdersByDOM(element)
+	}
+
+	private getPlaceholdersByQuerySelector(selector: string | null): Element[] {
+		return selector ? Array.from(document.querySelectorAll(selector)) : []
+	}
+
+	private getPlaceholdersByDOM(element: Element): Element[] {
+		const wrap = element.closest(this.ajaxSpinnerWrapSelector)
+
+		if (wrap === null) {
+			return []
+		}
+
+		const placeholders = wrap.querySelectorAll(this.ajaxSpinnerPlaceholderSelector)
+
+		return placeholders.length ? Array.from(placeholders) : [wrap]
+	}
+}

package/src/index.esm.ts

@@ -0,0 +1,6 @@
+import ControlManager from './utils/ControlManager'
+
+export { AjaxModalExtension } from './extensions/AjaxModalExtension'
+export { SpinnerExtension } from './extensions/SpinnerExtension'
+
+export const controlManager = new ControlManager()

package/src/utils/Control.ts

@@ -0,0 +1,18 @@
+// `Control` is meant to be used for standalone components, that might be dependent on ajax. It should be used together
+// with ControlManager. Class implementing the `Control` interface should export its instance. Then the intended
+// lifecycle of class is as follows:
+//
+// 1. `constructor` is called immediately and is also called only once. This is the ideal place for e.g. adding common
+//    event handlers to the `body`, or modifying necessary DOM properties on elements not affected by ajax.
+
+// 2. The instantiated class is then added to ControlManager either by `addControlOnLoad` or `addControlOnLive`. This
+//    ensures, that on `DOMContentLoaded` the `initialize` function of class is called. This method should implement
+//    initialization of the control dependent on fully loaded DOM. The `context` argument is equal to `document` in this
+//    call.
+//
+// 3. In case of `addControlOnLive` used, the `initialize` method is also called for each success ajax request. The
+//    `context` argument is equal to modified nette snippet.
+//
+export default interface Control {
+	initialize(context: Element | Document): void
+}

package/src/utils/ControlManager.ts

@@ -0,0 +1,42 @@
+import naja from 'naja'
+import { AfterUpdateEvent } from 'naja/dist/core/SnippetHandler'
+import Control from './Control'
+
+let instance: ControlManager | null = null
+
+export default class ControlManager {
+	private onLoadControl: Control[] = []
+	private onLiveControl: Control[] = []
+
+	public constructor() {
+		if (instance === null) {
+			// eslint-disable-next-line @typescript-eslint/no-this-alias
+			instance = this
+			naja.snippetHandler.addEventListener('afterUpdate', this.onSnippetUpdate.bind(this))
+		}
+		return instance
+	}
+
+	public onLoad(): void {
+		this.initialize(this.onLoadControl)
+		this.initialize(this.onLiveControl)
+	}
+
+	private onSnippetUpdate(event: AfterUpdateEvent): void {
+		this.initialize(this.onLiveControl, event.detail.snippet)
+	}
+
+	private initialize(controls: Control[], snippet?: Element | Document): void {
+		controls.forEach((control) => {
+			control.initialize(snippet || document)
+		})
+	}
+
+	public addControlOnLoad(control: Control): void {
+		this.onLoadControl.push(control)
+	}
+
+	public addControlOnLive(control: Control): void {
+		this.onLiveControl.push(control)
+	}
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"compilerOptions": {
+		"target": "ES2021",
+		"module": "ES2015",
+		"moduleResolution": "node",
+		"esModuleInterop": true,
+
+		"strict": true,
+		"alwaysStrict": true,
+
+		"rootDir": "src/",
+		"sourceMap": true,
+
+		"noEmitOnError": true,
+		"jsx": "react"
+	},
+	"exclude": [
+		"node_modules"
+	]
+}