@magic-spells/dialog-panel 0.2.3 → 1.0.0

package/src/dialog-panel.js

@@ -1,308 +1,363 @@
-import './index.scss';
-import '@magic-spells/focus-trap';
+import './dialog-panel.css';
 
 /**
- * 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;
+		}
+
+		// Auto-create dialog-backdrop if not present
+		if (!_.querySelector('dialog-backdrop')) {
+			const backdrop = document.createElement('dialog-backdrop');
+			_.insertBefore(backdrop, _.firstChild);
 		}
 
-		// Ensure body scroll is restored if component is removed while open
-		document.body.classList.remove('overflow-hidden');
-		this.#restoreScroll();
+		// 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`;
+		_.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();
 			}
-			if (heading?.id) {
-				_.setAttribute('aria-labelledby', heading.id);
-			}
-		}
-
-		_.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 { DialogPanel, DialogOverlay, DialogContent };
-export default DialogPanel;
+export { DialogPanel, DialogBackdrop };

package/dist/dialog-panel.scss

@@ -1,2 +0,0 @@
-@forward 'scss/variables';
-@forward 'scss/dialog-panel';

package/dist/scss/dialog-panel.scss

@@ -1,73 +0,0 @@
-// Import variables using the modern @use rule
-@use 'variables' as vars;
-
-dialog-panel {
-	/* Make it take no space and be invisible in the document flow */
-	display: contents;
-
-	&[aria-hidden='false'] {
-		dialog-overlay,
-		dialog-content {
-			pointer-events: auto;
-			opacity: 1;
-			transform: scale(1);
-			filter: blur(0px);
-		}
-	}
-}
-
-/* Overlay background */
-dialog-overlay {
-	position: fixed;
-	top: 0;
-	left: 0;
-	width: 100vw;
-	height: 100vh;
-	opacity: 0;
-	pointer-events: none;
-	z-index: var(--dp-overlay-z-index, 1000);
-	transition: var(--dp-overlay-transition, all 300ms ease-out);
-	background-color: var(
-		--dp-overlay-background,
-		rgba(20, 23, 26, 0.4)
-	);
-	backdrop-filter: var(
-		--dp-overlay-backdrop-filter,
-		blur(2px) saturate(120%)
-	);
-}
-
-dialog-content {
-	position: fixed;
-	top: 50%;
-	left: 50%;
-	transform: translate(-50%, -50%) scale(0.95);
-	max-width: 90vw;
-	max-height: 85vh;
-	display: var(--dp-content-display, block);
-	opacity: 0;
-	background: var(--dp-content-background, white);
-	pointer-events: none;
-	z-index: var(--dp-content-z-index, 1001);
-	box-shadow: var(
-		--dp-content-shadow,
-		0 10px 25px rgba(0, 0, 0, 0.15)
-	);
-	border-radius: var(--dp-content-border-radius, 8px);
-	overflow: auto;
-	transition:
-		opacity var(--dp-transition-duration, 300ms)
-			var(--dp-transition-timing, ease-out),
-		transform var(--dp-transition-duration, 300ms)
-			var(--dp-transition-timing, ease-out);
-
-	/* When shown, reset transform to center */
-	dialog-panel[aria-hidden='false'] & {
-		transform: translate(-50%, -50%) scale(1);
-	}
-
-	/* When explicitly hidden, remove from layout */
-	&.hidden {
-		display: none;
-	}
-}