@magic-spells/dialog-panel 0.3.0 → 1.0.0

package/dist/dialog-panel.js

@@ -5,496 +5,367 @@
 })(this, (function (exports) { 'use strict';
 
 	/**
-	 * Retrieves all focusable elements within a given container.
+	 * DialogPanel - A lightweight web component wrapper for native <dialog> elements
+	 * with state-driven animations.
 	 *
-	 * @param {HTMLElement} container - The container element to search for focusable elements.
-	 * @returns {HTMLElement[]} An array of focusable elements found within the container.
+	 * @extends HTMLElement
+	 *
+	 * @property {string} state - Current state: 'hidden' | 'showing' | 'shown' | 'hiding'
+	 * @property {HTMLDialogElement} dialog - Reference to inner <dialog> element
+	 * @property {boolean} isOpen - True if state is 'showing' or 'shown'
+	 * @property {HTMLElement|null} triggerElement - Element that triggered current action
+	 *
+	 * @fires beforeShow - Fired before showing starts (cancelable)
+	 * @fires shown - Fired after show animation completes
+	 * @fires beforeHide - Fired before hiding starts (cancelable)
+	 * @fires hidden - Fired after hide animation completes
 	 */
-	const getFocusableElements = (container) => {
-		const focusableSelectors =
-			'summary, a[href], button:not(:disabled), [tabindex]:not([tabindex^="-"]):not(focus-trap-start):not(focus-trap-end), [draggable], area, input:not([type=hidden]):not(:disabled), select:not(:disabled), textarea:not(:disabled), object, iframe';
-		return Array.from(container.querySelectorAll(focusableSelectors));
-	};
-
-	class FocusTrap extends HTMLElement {
-		/** @type {boolean} Indicates whether the styles have been injected into the DOM. */
-		static styleInjected = false;
-
-		constructor() {
-			super();
-			this.trapStart = null;
-			this.trapEnd = null;
-
-			// Inject styles only once, when the first FocusTrap instance is created.
-			if (!FocusTrap.styleInjected) {
-				this.injectStyles();
-				FocusTrap.styleInjected = true;
-			}
-		}
+	class DialogPanel extends HTMLElement {
+		// Private fields
+		#state = 'hidden';
+		#triggerElement = null;
+		#dialog = null;
+		#result = null;
+
+		// Event handler references for cleanup
+		#handlers = {
+			click: null,
+			dialogClick: null,
+			cancel: null,
+		};
 
-		/**
-		 * Injects necessary styles for the focus trap into the document's head.
-		 * This ensures that focus-trap-start and focus-trap-end elements are hidden.
-		 */
-		injectStyles() {
-			const style = document.createElement('style');
-			style.textContent = `
-      focus-trap-start,
-      focus-trap-end {
-        position: absolute;
-        width: 1px;
-        height: 1px;
-        margin: -1px;
-        padding: 0;
-        border: 0;
-        clip: rect(0, 0, 0, 0);
-        overflow: hidden;
-        white-space: nowrap;
-      }
-    `;
-			document.head.appendChild(style);
-		}
+		// Animation cleanup references
+		#pendingRAF = null;
+		#pendingTimeout = null;
+
+		// Fallback timeout for transitionend (in ms)
+		static TRANSITION_FALLBACK_TIMEOUT = 500;
 
-		/**
-		 * Called when the element is connected to the DOM.
-		 * Sets up the focus trap and adds the keydown event listener.
-		 */
 		connectedCallback() {
-			this.setupTrap();
-			this.addEventListener('keydown', this.handleKeyDown);
-		}
+			const _ = this;
 
-		/**
-		 * Called when the element is disconnected from the DOM.
-		 * Removes the keydown event listener.
-		 */
-		disconnectedCallback() {
-			this.removeEventListener('keydown', this.handleKeyDown);
-		}
+			// Find inner dialog element
+			_.#dialog = _.querySelector('dialog');
 
-		/**
-		 * Sets up the focus trap by adding trap start and trap end elements.
-		 * Focuses the trap start element to initiate the focus trap.
-		 */
-		setupTrap() {
-			// check to see it there are any focusable children
-			const focusableElements = getFocusableElements(this);
-			// exit if there aren't any
-			if (focusableElements.length === 0) return;
-
-			// create trap start and end elements
-			this.trapStart = document.createElement('focus-trap-start');
-			this.trapEnd = document.createElement('focus-trap-end');
-
-			// add to DOM
-			this.prepend(this.trapStart);
-			this.append(this.trapEnd);
-		}
+			if (!_.#dialog) {
+				console.warn(
+					'DialogPanel: No <dialog> element found inside <dialog-panel>'
+				);
+				return;
+			}
 
-		/**
-		 * Handles the keydown event. If the Escape key is pressed, the focus trap is exited.
-		 *
-		 * @param {KeyboardEvent} e - The keyboard event object.
-		 */
-		handleKeyDown = (e) => {
-			if (e.key === 'Escape') {
-				e.preventDefault();
-				this.exitTrap();
+			// Auto-create dialog-backdrop if not present
+			if (!_.querySelector('dialog-backdrop')) {
+				const backdrop = document.createElement('dialog-backdrop');
+				_.insertBefore(backdrop, _.firstChild);
 			}
-		};
 
-		/**
-		 * Exits the focus trap by hiding the current container and shifting focus
-		 * back to the trigger element that opened the trap.
-		 */
-		exitTrap() {
-			const container = this.closest('[aria-hidden="false"]');
-			if (!container) return;
+			// Set initial state attribute
+			_.#setState('hidden');
 
-			container.setAttribute('aria-hidden', 'true');
+			// Bind event handlers
+			_.#bindEvents();
+		}
 
-			const trigger = document.querySelector(
-				`[aria-expanded="true"][aria-controls="${container.id}"]`
-			);
-			if (trigger) {
-				trigger.setAttribute('aria-expanded', 'false');
-				trigger.focus();
+		disconnectedCallback() {
+			const _ = this;
+
+			// Cancel pending animations
+			if (_.#pendingRAF) {
+				cancelAnimationFrame(_.#pendingRAF);
+				_.#pendingRAF = null;
+			}
+			if (_.#pendingTimeout) {
+				clearTimeout(_.#pendingTimeout);
+				_.#pendingTimeout = null;
 			}
-		}
-	}
 
-	class FocusTrapStart extends HTMLElement {
-		/**
-		 * Called when the element is connected to the DOM.
-		 * Sets the tabindex and adds the focus event listener.
-		 */
-		connectedCallback() {
-			this.setAttribute('tabindex', '0');
-			this.addEventListener('focus', this.handleFocus);
+			// Clean up event listeners
+			if (_.#handlers.click) {
+				_.removeEventListener('click', _.#handlers.click);
+			}
+			if (_.#dialog) {
+				if (_.#handlers.dialogClick) {
+					_.#dialog.removeEventListener(
+						'click',
+						_.#handlers.dialogClick
+					);
+				}
+				if (_.#handlers.cancel) {
+					_.#dialog.removeEventListener('cancel', _.#handlers.cancel);
+				}
+			}
 		}
 
 		/**
-		 * Called when the element is disconnected from the DOM.
-		 * Removes the focus event listener.
+		 * Bind event listeners for close buttons, backdrop, and escape key
+		 * @private
 		 */
-		disconnectedCallback() {
-			this.removeEventListener('focus', this.handleFocus);
+		#bindEvents() {
+			const _ = this;
+
+			// Handle close buttons with data-action-hide-dialog
+			_.#handlers.click = (e) => {
+				const trigger = e.target.closest('[data-action-hide-dialog]');
+				if (trigger) {
+					e.stopPropagation();
+					_.hide(trigger);
+				}
+			};
+			_.addEventListener('click', _.#handlers.click);
+
+			// Handle backdrop click - detect clicks outside dialog bounds
+			// This works because clicks on ::backdrop still fire on the dialog element
+			_.#handlers.dialogClick = (e) => {
+				const rect = _.#dialog.getBoundingClientRect();
+				const clickedOutside =
+					e.clientX < rect.left ||
+					e.clientX > rect.right ||
+					e.clientY < rect.top ||
+					e.clientY > rect.bottom;
+				if (clickedOutside) {
+					e.stopPropagation();
+					_.hide();
+				}
+			};
+			_.#dialog.addEventListener('click', _.#handlers.dialogClick);
+
+			// Handle escape key - intercept native cancel and animate close
+			_.#handlers.cancel = (e) => {
+				e.preventDefault();
+				e.stopPropagation();
+				_.hide();
+			};
+			_.#dialog.addEventListener('cancel', _.#handlers.cancel);
 		}
 
 		/**
-		 * Handles the focus event. If focus moves backwards from the first focusable element,
-		 * it is cycled to the last focusable element, and vice versa.
-		 *
-		 * @param {FocusEvent} e - The focus event object.
+		 * Show the dialog with animation
+		 * @param {HTMLElement} [triggerEl=null] - The element that triggered the show
+		 * @returns {boolean} False if show was prevented via beforeShow event
 		 */
-		handleFocus = (e) => {
-			const trap = this.closest('focus-trap');
-			const focusableElements = getFocusableElements(trap);
+		show(triggerEl = null) {
+			const _ = this;
 
-			if (focusableElements.length === 0) return;
+			// Check if already showing/shown
+			if (_.#state === 'showing' || _.#state === 'shown') return true;
 
-			const firstElement = focusableElements[0];
-			const lastElement =
-				focusableElements[focusableElements.length - 1];
+			// If currently hiding, ignore (let hide complete first)
+			if (_.#state === 'hiding') return false;
 
-			if (e.relatedTarget === firstElement) {
-				lastElement.focus();
-			} else {
-				firstElement.focus();
-			}
-		};
-	}
+			// Store trigger element for focus return later
+			_.#triggerElement = triggerEl || null;
 
-	class FocusTrapEnd extends HTMLElement {
-		/**
-		 * Called when the element is connected to the DOM.
-		 * Sets the tabindex and adds the focus event listener.
-		 */
-		connectedCallback() {
-			this.setAttribute('tabindex', '0');
-			this.addEventListener('focus', this.handleFocus);
-		}
+			// Fire beforeShow (cancelable)
+			if (!_.#emit('beforeShow', { cancelable: true })) return false;
 
-		/**
-		 * Called when the element is disconnected from the DOM.
-		 * Removes the focus event listener.
-		 */
-		disconnectedCallback() {
-			this.removeEventListener('focus', this.handleFocus);
-		}
+			// Set state to 'showing' and open native dialog
+			_.#setState('showing');
+			_.#dialog.showModal();
 
-		/**
-		 * Handles the focus event. When the trap end is focused, focus is shifted back to the trap start.
-		 */
-		handleFocus = () => {
-			const trap = this.closest('focus-trap');
-			const trapStart = trap.querySelector('focus-trap-start');
-			trapStart.focus();
-		};
-	}
+			// Double RAF ensures browser has painted the 'showing' state
+			// before we transition to 'shown'
+			_.#pendingRAF = requestAnimationFrame(() => {
+				_.#pendingRAF = requestAnimationFrame(() => {
+					_.#pendingRAF = null;
+					_.#setState('shown');
 
-	if (!customElements.get('focus-trap')) {
-		customElements.define('focus-trap', FocusTrap);
-	}
-	if (!customElements.get('focus-trap-start')) {
-		customElements.define('focus-trap-start', FocusTrapStart);
-	}
-	if (!customElements.get('focus-trap-end')) {
-		customElements.define('focus-trap-end', FocusTrapEnd);
-	}
-
-	/**
-	 * Custom element that creates an accessible modal dialog panel with focus management
-	 * @extends HTMLElement
-	 */
-	class DialogPanel extends HTMLElement {
-		#handleTransitionEnd;
+					// Wait for transition to complete before firing 'shown' event
+					_.#waitForTransition(() => {
+						_.#emit('shown');
+					});
+				});
+			});
 
-		/**
-		 * Clean up event listeners when component is removed from DOM
-		 */
-		disconnectedCallback() {
-			const _ = this;
-			if (_.contentPanel) {
-				_.contentPanel.removeEventListener(
-					'transitionend',
-					_.#handleTransitionEnd
-				);
-			}
+			return true;
 		}
+
 		/**
-		 * Initializes the dialog panel, sets up focus trap and overlay
+		 * Hide the dialog with animation
+		 * @param {HTMLElement} [triggerEl=null] - The element that triggered the hide
+		 * @returns {boolean} False if hide was prevented via beforeHide event
 		 */
-		constructor() {
-			super();
+		hide(triggerEl = null) {
 			const _ = this;
-			_.id = _.getAttribute('id');
-			_.setAttribute('role', 'dialog');
-			_.setAttribute('aria-modal', 'true');
-			_.setAttribute('aria-hidden', 'true');
-
-			_.contentPanel = _.querySelector('dialog-content');
-			_.triggerEl = null;
-
-			// Create a handler for transition end events
-			_.#handleTransitionEnd = (e) => {
-				if (
-					e.propertyName === 'opacity' &&
-					_.getAttribute('aria-hidden') === 'true'
-				) {
-					_.contentPanel.classList.add('hidden');
-
-					// Dispatch afterHide event - dialog has completed its transition
-					_.dispatchEvent(
-						new CustomEvent('afterHide', {
-							bubbles: true,
-							detail: { triggerElement: _.triggerEl },
-						})
-					);
-				}
-			};
 
-			// Set up focus-trap inside dialog-content
-			// Check if focus-trap already exists
-			_.focusTrap = _.contentPanel.querySelector('focus-trap');
-			if (!_.focusTrap) {
-				_.focusTrap = document.createElement('focus-trap');
+			// Check if already hiding/hidden
+			if (_.#state === 'hiding' || _.#state === 'hidden') return true;
 
-				// Move all existing dialog-content children into focus-trap
-				const existingContent = Array.from(_.contentPanel.childNodes);
-				existingContent.forEach((child) =>
-					_.focusTrap.appendChild(child)
-				);
+			// If currently showing, ignore (let show complete first)
+			if (_.#state === 'showing') return false;
 
-				// Insert focus-trap inside dialog-content
-				_.contentPanel.appendChild(_.focusTrap);
-			}
+			// Capture result from trigger element
+			_.#result = triggerEl?.dataset?.result ?? null;
 
-			// Ensure we have labelledby and describedby references
-			if (!_.getAttribute('aria-labelledby')) {
-				const heading = _.querySelector('h1, h2, h3');
-				if (heading && !heading.id) {
-					heading.id = `${_.id}-title`;
-				}
-				if (heading?.id) {
-					_.setAttribute('aria-labelledby', heading.id);
-				}
+			// Fire beforeHide (cancelable)
+			if (
+				!_.#emit('beforeHide', {
+					cancelable: true,
+					result: _.#result,
+					triggerElement: triggerEl,
+				})
+			) {
+				return false;
 			}
 
-			// Add modal overlay
-			_.prepend(document.createElement('dialog-overlay'));
-			_.#bindUI();
-			_.#bindKeyboard();
+			// Set state to 'hiding' - this triggers CSS exit animation
+			_.#setState('hiding');
+
+			// Wait for transition to complete
+			_.#waitForTransition(() => {
+				_.#dialog.close();
+				_.#setState('hidden');
+				_.#emit('hidden', {
+					result: _.#result,
+					triggerElement: triggerEl,
+				});
+
+				// Return focus to trigger element
+				if (_.#triggerElement) _.#triggerElement.focus();
+
+				// Clean up
+				_.#triggerElement = null;
+				_.#result = null;
+			});
+
+			return true;
 		}
 
 		/**
-		 * Binds click events for showing and hiding the dialog
+		 * Wait for CSS transition to complete with fallback timeout
+		 * @param {Function} callback - Called when transition completes
 		 * @private
 		 */
-		#bindUI() {
+		#waitForTransition(callback) {
 			const _ = this;
-
-			// Handle trigger buttons
-			document.addEventListener('click', (e) => {
-				const trigger = e.target.closest(`[aria-controls="${_.id}"]`);
-				if (!trigger) return;
-
-				if (trigger.getAttribute('data-prevent-default') === 'true') {
-					e.preventDefault();
+			let called = false;
+
+			const done = () => {
+				if (called) return;
+				called = true;
+				_.#dialog.removeEventListener('transitionend', onTransitionEnd);
+				if (_.#pendingTimeout) {
+					clearTimeout(_.#pendingTimeout);
+					_.#pendingTimeout = null;
 				}
+				callback();
+			};
 
-				_.show(trigger);
-			});
+			const onTransitionEnd = (e) => {
+				if (e.target === _.#dialog) done();
+			};
 
-			// Handle close buttons
-			_.addEventListener('click', (e) => {
-				if (!e.target.closest('[data-action-hide-dialog]')) return;
-				_.hide();
-			});
+			_.#dialog.addEventListener('transitionend', onTransitionEnd);
 
-			// Add transition end listener
-			_.contentPanel.addEventListener(
-				'transitionend',
-				_.#handleTransitionEnd
+			_.#pendingTimeout = setTimeout(
+				done,
+				DialogPanel.TRANSITION_FALLBACK_TIMEOUT
 			);
 		}
 
 		/**
-		 * Binds keyboard events for accessibility
+		 * Set the component state
+		 * @param {string} newState - The new state
 		 * @private
 		 */
-		#bindKeyboard() {
-			this.addEventListener('keydown', (e) => {
-				if (e.key === 'Escape') {
-					this.hide();
-				}
-			});
+		#setState(newState) {
+			this.#state = newState;
+			this.setAttribute('state', newState);
 		}
 
 		/**
-		 * Shows the dialog and traps focus within it
-		 * @param {HTMLElement} [triggerEl=null] - The element that triggered the dialog
-		 * @fires DialogPanel#beforeShow - Fired before the dialog starts to show
-		 * @fires DialogPanel#show - Fired when the dialog has been shown
-		 * @returns {boolean} False if the show was prevented by a beforeShow event handler
+		 * Emit a custom event
+		 * @param {string} name - Event name
+		 * @param {Object} options - Event options
+		 * @returns {boolean} False if event was cancelled
+		 * @private
 		 */
-		show(triggerEl = null) {
+		#emit(name, options = {}) {
 			const _ = this;
-			_.triggerEl = triggerEl || false;
+			const { cancelable = false, ...detail } = options;
 
-			// Dispatch beforeShow event - allows preventing the dialog from opening
-			const beforeShowEvent = new CustomEvent('beforeShow', {
+			const event = new CustomEvent(name, {
 				bubbles: true,
-				cancelable: true,
-				detail: { triggerElement: _.triggerEl },
+				composed: true,
+				cancelable,
+				detail: {
+					triggerElement: _.#triggerElement,
+					result: _.#result,
+					state: _.#state,
+					...detail,
+				},
 			});
 
-			const showAllowed = _.dispatchEvent(beforeShowEvent);
-
-			// If event was canceled (preventDefault was called), don't show the dialog
-			if (!showAllowed) return false;
+			return _.dispatchEvent(event);
+		}
 
-			// Add open attribute for CSS :has() selector
-			_.setAttribute('open', '');
+		// Read-only properties
+		get state() {
+			return this.#state;
+		}
+		get dialog() {
+			return this.#dialog;
+		}
+		get isOpen() {
+			return this.#state === 'showing' || this.#state === 'shown';
+		}
+		get triggerElement() {
+			return this.#triggerElement;
+		}
+	}
 
-			// Remove the hidden class first to ensure content is rendered
-			_.contentPanel.classList.remove('hidden');
+	/**
+	 * DialogBackdrop - A custom backdrop element that animates with the dialog-panel state.
+	 * Use this instead of native ::backdrop for consistent cross-browser animations.
+	 *
+	 * @extends HTMLElement
+	 */
+	class DialogBackdrop extends HTMLElement {
+		#panel = null;
+		#handlers = {
+			click: null,
+		};
 
-			// Give the browser a moment to process before starting animation
-			requestAnimationFrame(() => {
-				// Update ARIA states
-				_.setAttribute('aria-hidden', 'false');
+		connectedCallback() {
+			const _ = this;
 
-				// set trigger element to expanded: true
-				if (_.triggerEl) {
-					_.triggerEl.setAttribute('aria-expanded', 'true');
-				}
+			// Find parent dialog-panel
+			_.#panel = _.closest('dialog-panel');
 
-				// Focus management
-				const firstFocusable = _.querySelector(
-					'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+			if (!_.#panel) {
+				console.warn(
+					'DialogBackdrop: Must be inside a <dialog-panel> element'
 				);
-				if (firstFocusable) {
-					requestAnimationFrame(() => {
-						firstFocusable.focus();
-					});
-				}
+				return;
+			}
 
-				// Dispatch show event - dialog is now visible
-				_.dispatchEvent(
-					new CustomEvent('show', {
-						bubbles: true,
-						detail: { triggerElement: _.triggerEl },
-					})
-				);
-			});
+			// Handle click to close
+			_.#handlers.click = () => {
+				_.#panel.hide();
+			};
+			_.addEventListener('click', _.#handlers.click);
 		}
 
-		/**
-		 * Hides the dialog and restores focus
-		 * @fires DialogPanel#beforeHide - Fired before the dialog starts to hide
-		 * @fires DialogPanel#hide - Fired when the dialog has started hiding (transition begins)
-		 * @fires DialogPanel#afterHide - Fired when the dialog has completed its hide transition
-		 * @returns {boolean} False if the hide was prevented by a beforeHide event handler
-		 */
-		hide() {
+		disconnectedCallback() {
 			const _ = this;
-
-			// Dispatch beforeHide event - allows preventing the dialog from closing
-			const beforeHideEvent = new CustomEvent('beforeHide', {
-				bubbles: true,
-				cancelable: true,
-				detail: { triggerElement: _.triggerEl },
-			});
-
-			const hideAllowed = _.dispatchEvent(beforeHideEvent);
-
-			// If event was canceled (preventDefault was called), don't hide the dialog
-			if (!hideAllowed) return false;
-
-			// ensure focus is moved out of the dialog
-			const activeElement = document.activeElement;
-			if (activeElement && _.contains(activeElement)) {
-				// Blur the currently focused element if it's inside the dialog
-				activeElement.blur();
+			if (_.#handlers.click) {
+				_.removeEventListener('click', _.#handlers.click);
 			}
-
-			// Update ARIA states and restore focus
-			if (_.triggerEl) {
-				// remove focus from modal panel first
-				_.triggerEl.focus();
-				// mark trigger as no longer expanded
-				_.triggerEl.setAttribute('aria-expanded', 'false');
-			} else {
-				// Move focus to body to ensure it's not trapped
-				document.body.focus();
-			}
-
-			// Set aria-hidden to start transition
-			// The transitionend event handler will add display:none when complete
-			_.setAttribute('aria-hidden', 'true');
-			// Remove open attribute for CSS :has() selector
-
-			_.removeAttribute('open');
-
-			// Dispatch hide event - dialog is now starting to hide
-			_.dispatchEvent(
-				new CustomEvent('hide', {
-					bubbles: true,
-					detail: { triggerElement: _.triggerEl },
-				})
-			);
-
-			return true;
 		}
 	}
 
-	/**
-	 * Custom element that creates a clickable overlay for the dialog
-	 * @extends HTMLElement
-	 */
-	class DialogOverlay extends HTMLElement {
-		constructor() {
-			super();
-			this.setAttribute('tabindex', '-1');
-			this.dialogPanel = this.closest('dialog-panel');
-			this.#bindUI();
-		}
-
-		#bindUI() {
-			this.addEventListener('click', () => {
-				this.dialogPanel.hide();
-			});
-		}
+	// Register the custom elements
+	// Note: dialog-backdrop must be defined BEFORE dialog-panel,
+	// because dialog-panel's connectedCallback may create dialog-backdrop elements
+	if (!customElements.get('dialog-backdrop')) {
+		customElements.define('dialog-backdrop', DialogBackdrop);
 	}
-
-	/**
-	 * Custom element that wraps the content of the dialog
-	 * @extends HTMLElement
-	 */
-	class DialogContent extends HTMLElement {
-		constructor() {
-			super();
-			this.setAttribute('role', 'document');
-		}
-	}
-
 	if (!customElements.get('dialog-panel')) {
 		customElements.define('dialog-panel', DialogPanel);
 	}
-	if (!customElements.get('dialog-overlay')) {
-		customElements.define('dialog-overlay', DialogOverlay);
-	}
-	if (!customElements.get('dialog-content')) {
-		customElements.define('dialog-content', DialogContent);
-	}
 
-	exports.DialogContent = DialogContent;
-	exports.DialogOverlay = DialogOverlay;
+	exports.DialogBackdrop = DialogBackdrop;
 	exports.DialogPanel = DialogPanel;
-	exports.default = DialogPanel;
-
-	Object.defineProperty(exports, '__esModule', { value: true });
 
 }));
 //# sourceMappingURL=dialog-panel.js.map