@magic-spells/dialog-panel 0.2.3 → 1.0.0

package/dist/dialog-panel.esm.js

@@ -1,307 +1,362 @@
-import '@magic-spells/focus-trap';
-
 /**
- * Custom element that creates an accessible modal dialog panel with focus management
+ * DialogPanel - A lightweight web component wrapper for native <dialog> elements
+ * with state-driven animations.
+ *
  * @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
  */
 class DialogPanel extends HTMLElement {
-	#handleTransitionEnd;
-	#scrollPosition = 0;
-
-	/**
-	 * Clean up event listeners when component is removed from DOM
-	 */
-	disconnectedCallback() {
+	// Private fields
+	#state = 'hidden';
+	#triggerElement = null;
+	#dialog = null;
+	#result = null;
+
+	// Event handler references for cleanup
+	#handlers = {
+		click: null,
+		dialogClick: null,
+		cancel: null,
+	};
+
+	// Animation cleanup references
+	#pendingRAF = null;
+	#pendingTimeout = null;
+
+	// Fallback timeout for transitionend (in ms)
+	static TRANSITION_FALLBACK_TIMEOUT = 500;
+
+	connectedCallback() {
 		const _ = this;
-		if (_.contentPanel) {
-			_.contentPanel.removeEventListener(
-				'transitionend',
-				_.#handleTransitionEnd
+
+		// Find inner dialog element
+		_.#dialog = _.querySelector('dialog');
+
+		if (!_.#dialog) {
+			console.warn(
+				'DialogPanel: No <dialog> element found inside <dialog-panel>'
 			);
+			return;
 		}
 
-		// Ensure body scroll is restored if component is removed while open
-		document.body.classList.remove('overflow-hidden');
-		this.#restoreScroll();
+		// Auto-create dialog-backdrop if not present
+		if (!_.querySelector('dialog-backdrop')) {
+			const backdrop = document.createElement('dialog-backdrop');
+			_.insertBefore(backdrop, _.firstChild);
+		}
+
+		// Set initial state attribute
+		_.#setState('hidden');
+
+		// Bind event handlers
+		_.#bindEvents();
 	}
 
-	/**
-	 * Saves current scroll position and locks body scrolling
-	 * @private
-	 */
-	#lockScroll() {
+	disconnectedCallback() {
 		const _ = this;
-		// Save current scroll position
-		_.#scrollPosition = window.pageYOffset;
 
-		// Apply fixed position to body
-		document.body.classList.add('overflow-hidden');
-		document.body.style.top = `-${_.#scrollPosition}px`;
+		// Cancel pending animations
+		if (_.#pendingRAF) {
+			cancelAnimationFrame(_.#pendingRAF);
+			_.#pendingRAF = null;
+		}
+		if (_.#pendingTimeout) {
+			clearTimeout(_.#pendingTimeout);
+			_.#pendingTimeout = null;
+		}
+
+		// 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);
+			}
+		}
 	}
 
 	/**
-	 * Restores scroll position when dialog is closed
+	 * Bind event listeners for close buttons, backdrop, and escape key
 	 * @private
 	 */
-	#restoreScroll() {
+	#bindEvents() {
 		const _ = this;
-		// Remove fixed positioning
-		document.body.classList.remove('overflow-hidden');
-		document.body.style.removeProperty('top');
 
-		// Restore scroll position
-		window.scrollTo(0, _.#scrollPosition);
-	}
-	/**
-	 * Initializes the dialog panel, sets up focus trap and overlay
-	 */
-	constructor() {
-		super();
-		const _ = this;
-		_.id = _.getAttribute('id');
-		_.setAttribute('role', 'dialog');
-		_.setAttribute('aria-modal', 'true');
-		_.setAttribute('aria-hidden', 'true');
-
-		_.contentPanel = _.querySelector('dialog-content');
-		_.focusTrap = document.createElement('focus-trap');
-		_.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 },
-					})
-				);
+		// 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);
 			}
 		};
-
-		// 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);
+		_.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();
 			}
-		}
-
-		_.contentPanel.parentNode.insertBefore(
-			_.focusTrap,
-			_.contentPanel
-		);
-		_.focusTrap.appendChild(_.contentPanel);
-
-		_.focusTrap.setupTrap();
+		};
+		_.#dialog.addEventListener('click', _.#handlers.dialogClick);
 
-		// Add modal overlay
-		_.prepend(document.createElement('dialog-overlay'));
-		_.#bindUI();
-		_.#bindKeyboard();
+		// Handle escape key - intercept native cancel and animate close
+		_.#handlers.cancel = (e) => {
+			e.preventDefault();
+			e.stopPropagation();
+			_.hide();
+		};
+		_.#dialog.addEventListener('cancel', _.#handlers.cancel);
 	}
 
 	/**
-	 * Binds click events for showing and hiding the dialog
-	 * @private
+	 * 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
 	 */
-	#bindUI() {
+	show(triggerEl = null) {
 		const _ = this;
 
-		// Handle trigger buttons
-		document.addEventListener('click', (e) => {
-			const trigger = e.target.closest(`[aria-controls="${_.id}"]`);
-			if (!trigger) return;
+		// Check if already showing/shown
+		if (_.#state === 'showing' || _.#state === 'shown') return true;
 
-			if (trigger.getAttribute('data-prevent-default') === 'true') {
-				e.preventDefault();
-			}
+		// If currently hiding, ignore (let hide complete first)
+		if (_.#state === 'hiding') return false;
 
-			_.show(trigger);
-		});
+		// Store trigger element for focus return later
+		_.#triggerElement = triggerEl || null;
 
-		// Handle close buttons
-		_.addEventListener('click', (e) => {
-			if (!e.target.closest('[data-action="hide-dialog"]')) return;
-			_.hide();
-		});
+		// Fire beforeShow (cancelable)
+		if (!_.#emit('beforeShow', { cancelable: true })) return false;
 
-		// Add transition end listener
-		_.contentPanel.addEventListener(
-			'transitionend',
-			_.#handleTransitionEnd
-		);
-	}
+		// Set state to 'showing' and open native dialog
+		_.#setState('showing');
+		_.#dialog.showModal();
 
-	/**
-	 * Binds keyboard events for accessibility
-	 * @private
-	 */
-	#bindKeyboard() {
-		this.addEventListener('keydown', (e) => {
-			if (e.key === 'Escape') {
-				this.hide();
-			}
+		// Double RAF ensures browser has painted the 'showing' state
+		// before we transition to 'shown'
+		_.#pendingRAF = requestAnimationFrame(() => {
+			_.#pendingRAF = requestAnimationFrame(() => {
+				_.#pendingRAF = null;
+				_.#setState('shown');
+
+				// Wait for transition to complete before firing 'shown' event
+				_.#waitForTransition(() => {
+					_.#emit('shown');
+				});
+			});
 		});
+
+		return true;
 	}
 
 	/**
-	 * 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
+	 * 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
 	 */
-	show(triggerEl = null) {
+	hide(triggerEl = null) {
 		const _ = this;
-		_.triggerEl = triggerEl || false;
 
-		// Dispatch beforeShow event - allows preventing the dialog from opening
-		const beforeShowEvent = new CustomEvent('beforeShow', {
-			bubbles: true,
-			cancelable: true,
-			detail: { triggerElement: _.triggerEl },
-		});
+		// Check if already hiding/hidden
+		if (_.#state === 'hiding' || _.#state === 'hidden') return true;
 
-		const showAllowed = _.dispatchEvent(beforeShowEvent);
+		// If currently showing, ignore (let show complete first)
+		if (_.#state === 'showing') return false;
 
-		// If event was canceled (preventDefault was called), don't show the dialog
-		if (!showAllowed) return false;
+		// Capture result from trigger element
+		_.#result = triggerEl?.dataset?.result ?? null;
 
-		// Remove the hidden class first to ensure content is rendered
-		_.contentPanel.classList.remove('hidden');
+		// Fire beforeHide (cancelable)
+		if (
+			!_.#emit('beforeHide', {
+				cancelable: true,
+				result: _.#result,
+				triggerElement: triggerEl,
+			})
+		) {
+			return false;
+		}
 
-		// Give the browser a moment to process before starting animation
-		requestAnimationFrame(() => {
-			// Update ARIA states
-			_.setAttribute('aria-hidden', 'false');
-			if (_.triggerEl) {
-				_.triggerEl.setAttribute('aria-expanded', 'true');
-			}
+		// Set state to 'hiding' - this triggers CSS exit animation
+		_.#setState('hiding');
 
-			// Lock body scrolling and save scroll position
-			_.#lockScroll();
+		// Wait for transition to complete
+		_.#waitForTransition(() => {
+			_.#dialog.close();
+			_.#setState('hidden');
+			_.#emit('hidden', {
+				result: _.#result,
+				triggerElement: triggerEl,
+			});
 
-			// Focus management
-			const firstFocusable = _.querySelector(
-				'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-			);
-			if (firstFocusable) {
-				requestAnimationFrame(() => {
-					firstFocusable.focus();
-				});
-			}
+			// Return focus to trigger element
+			if (_.#triggerElement) _.#triggerElement.focus();
 
-			// Dispatch show event - dialog is now visible
-			_.dispatchEvent(
-				new CustomEvent('show', {
-					bubbles: true,
-					detail: { triggerElement: _.triggerEl },
-				})
-			);
+			// Clean up
+			_.#triggerElement = null;
+			_.#result = null;
 		});
 
 		return true;
 	}
 
 	/**
-	 * 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
+	 * Wait for CSS transition to complete with fallback timeout
+	 * @param {Function} callback - Called when transition completes
+	 * @private
 	 */
-	hide() {
+	#waitForTransition(callback) {
 		const _ = this;
+		let called = false;
+
+		const done = () => {
+			if (called) return;
+			called = true;
+			_.#dialog.removeEventListener('transitionend', onTransitionEnd);
+			if (_.#pendingTimeout) {
+				clearTimeout(_.#pendingTimeout);
+				_.#pendingTimeout = null;
+			}
+			callback();
+		};
 
-		// Dispatch beforeHide event - allows preventing the dialog from closing
-		const beforeHideEvent = new CustomEvent('beforeHide', {
-			bubbles: true,
-			cancelable: true,
-			detail: { triggerElement: _.triggerEl },
-		});
+		const onTransitionEnd = (e) => {
+			if (e.target === _.#dialog) done();
+		};
 
-		const hideAllowed = _.dispatchEvent(beforeHideEvent);
+		_.#dialog.addEventListener('transitionend', onTransitionEnd);
 
-		// If event was canceled (preventDefault was called), don't hide the dialog
-		if (!hideAllowed) return false;
+		_.#pendingTimeout = setTimeout(
+			done,
+			DialogPanel.TRANSITION_FALLBACK_TIMEOUT
+		);
+	}
 
-		// Restore body scroll and scroll position
-		_.#restoreScroll();
+	/**
+	 * Set the component state
+	 * @param {string} newState - The new state
+	 * @private
+	 */
+	#setState(newState) {
+		this.#state = newState;
+		this.setAttribute('state', newState);
+	}
 
-		// Update ARIA states
-		if (_.triggerEl) {
-			// remove focus from modal panel first
-			_.triggerEl.focus();
-			// mark trigger as no longer expanded
-			_.triggerEl.setAttribute('aria-expanded', 'false');
-		}
+	/**
+	 * Emit a custom event
+	 * @param {string} name - Event name
+	 * @param {Object} options - Event options
+	 * @returns {boolean} False if event was cancelled
+	 * @private
+	 */
+	#emit(name, options = {}) {
+		const _ = this;
+		const { cancelable = false, ...detail } = options;
 
-		// Set aria-hidden to start transition
-		// The transitionend event handler will add display:none when complete
-		_.setAttribute('aria-hidden', 'true');
+		const event = new CustomEvent(name, {
+			bubbles: true,
+			composed: true,
+			cancelable,
+			detail: {
+				triggerElement: _.#triggerElement,
+				result: _.#result,
+				state: _.#state,
+				...detail,
+			},
+		});
 
-		// Dispatch hide event - dialog is now starting to hide
-		_.dispatchEvent(
-			new CustomEvent('hide', {
-				bubbles: true,
-				detail: { triggerElement: _.triggerEl },
-			})
-		);
+		return _.dispatchEvent(event);
+	}
 
-		return true;
+	// 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;
 	}
 }
 
 /**
- * Custom element that creates a clickable overlay for the dialog
+ * 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 DialogOverlay extends HTMLElement {
-	constructor() {
-		super();
-		this.setAttribute('tabindex', '-1'); // Changed to -1 as it shouldn't be focusable
-		this.setAttribute('aria-hidden', 'true');
-		this.dialogPanel = this.closest('dialog-panel');
-		this.#bindUI();
-	}
+class DialogBackdrop extends HTMLElement {
+	#panel = null;
+	#handlers = {
+		click: null,
+	};
 
-	#bindUI() {
-		this.addEventListener('click', () => {
-			this.dialogPanel.hide();
-		});
+	connectedCallback() {
+		const _ = this;
+
+		// Find parent dialog-panel
+		_.#panel = _.closest('dialog-panel');
+
+		if (!_.#panel) {
+			console.warn(
+				'DialogBackdrop: Must be inside a <dialog-panel> element'
+			);
+			return;
+		}
+
+		// Handle click to close
+		_.#handlers.click = () => {
+			_.#panel.hide();
+		};
+		_.addEventListener('click', _.#handlers.click);
 	}
-}
 
-/**
- * Custom element that wraps the content of the dialog
- * @extends HTMLElement
- */
-class DialogContent extends HTMLElement {
-	constructor() {
-		super();
-		this.setAttribute('role', 'document'); // Optional: helps with document structure
+	disconnectedCallback() {
+		const _ = this;
+		if (_.#handlers.click) {
+			_.removeEventListener('click', _.#handlers.click);
+		}
 	}
 }
 
+// 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);
+}
 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);
-}
 
-export { DialogContent, DialogOverlay, DialogPanel, DialogPanel as default };
+export { DialogBackdrop, DialogPanel };
 //# sourceMappingURL=dialog-panel.esm.js.map