⚡ Spark: Dialog backdrop click and native event sync

.axioma/spark.md

@@ -25,3 +25,7 @@
 ## 2025-05-26 - [Shadowing standard props for ISO transforms]
 **Learning:** For components that wrap native HTML inputs, adding `iso*` variants of standard props (like `isoMin` for `min`) allows the component to handle standard data formats while gracefully falling back to native behavior when the specialized prop is absent.
 **Pattern:** Implement specialized props with an `iso` prefix and use a ternary in the render function to prioritize the transformed ISO value: `min={isoMin ? iso2LocalDateTime(isoMin) : min}`.
+
+## 2026-05-26 - [Syncing React State with Native Events]
+**Learning:** For components wrapping native elements with their own internal state (like `<dialog>`), synchronizing React state via native event listeners (like `onClose`) is critical. This ensures the component remains in sync when the state changes via browser shortcuts (ESC key) or other non-React means.
+**Pattern:** Use native event handlers on the underlying element to trigger React state updates, rather than relying solely on imperative method calls (like `dialog.close()`) to drive the `onClose` logic.

README.md

@@ -255,6 +255,7 @@ Accessible dialog/modal component built on top of the native `<dialog>` element.
 | `onClose`   | `() => void`                  | Triggered on close                         |
 | `opener`    | `ReactNode`                   | Element to trigger opening                 |
 | `children`  | `ReactNode`                   | Content inside the dialog                  |
+| `closeOnBackdropClick` | `boolean` (default: `false`) | Whether to close when clicking the backdrop |
 | `...dialogProps` | All native `<dialog>` props | Inherits all HTML dialog element attributes |
 
 ***

lib/components/Dialog/index.test.tsx

@@ -13,7 +13,10 @@ describe('Dialog', () => {
             this.setAttribute('open', '')
         })
         vi.spyOn(HTMLDialogElement.prototype, 'close').mockImplementation(function (this: HTMLDialogElement) {
-            this.removeAttribute('open')
+            if (this.hasAttribute('open')) {
+                this.removeAttribute('open')
+                this.dispatchEvent(new Event('close'))
+            }
         })
     })
 
@@ -70,7 +73,7 @@ describe('Dialog', () => {
         expect(onOpen).toHaveBeenCalled()
     })
 
-    it('should call onClose callback when closed', () => {
+    it('should call onClose callback when closed via prop change', () => {
         const onClose = vi.fn()
         const { rerender } = render(
             <Dialog isOpen={true} onClose={onClose}>
@@ -84,9 +87,57 @@ describe('Dialog', () => {
             </Dialog>
         )
 
+        // The component calls dialog.close() which triggers the onClose event handler
         expect(onClose).toHaveBeenCalled()
     })
 
+    it('should call onClose and update internal state when closed via native event', () => {
+        const onClose = vi.fn()
+        const { container } = render(
+            <Dialog isOpen={true} onClose={onClose}>
+                <p>Content</p>
+            </Dialog>
+        )
+
+        const dialog = container.querySelector('dialog')
+        // Dispatching native close event
+        fireEvent(dialog!, new Event('close'))
+
+        expect(onClose).toHaveBeenCalled()
+    })
+
+    it('should close on backdrop click when closeOnBackdropClick is true', () => {
+        // Mock getBoundingClientRect for the dialog
+        vi.spyOn(HTMLDialogElement.prototype, 'getBoundingClientRect').mockReturnValue({
+            top: 100,
+            bottom: 400,
+            left: 100,
+            right: 400,
+            width: 300,
+            height: 300,
+            x: 100,
+            y: 100,
+            toJSON: () => {}
+        })
+
+        const onClose = vi.fn()
+        const { container } = render(
+            <Dialog isOpen={true} closeOnBackdropClick={true} onClose={onClose}>
+                <p>Content</p>
+            </Dialog>
+        )
+
+        const dialog = container.querySelector('dialog')
+
+        // Click inside the dialog (should not close)
+        fireEvent.click(dialog!, { clientX: 200, clientY: 200 })
+        expect(HTMLDialogElement.prototype.close).not.toHaveBeenCalled()
+
+        // Click outside the dialog (backdrop)
+        fireEvent.click(dialog!, { clientX: 50, clientY: 50 })
+        expect(HTMLDialogElement.prototype.close).toHaveBeenCalled()
+    })
+
     it('should toggle dialog when opener is clicked', () => {
         render(
             <Dialog

lib/components/Dialog/index.tsx

@@ -36,6 +36,7 @@ export const Dialog = (props: DialogProps): JSX.Element => {
     const {
         isOpen = false,
         behavior = 'modal',
+        closeOnBackdropClick = false,
         opener,
         onOpen,
         onClose,
@@ -62,17 +63,41 @@ export const Dialog = (props: DialogProps): JSX.Element => {
         } else {
             if (dialogElement.open) {
                 dialogElement.close()
-                onClose?.()
             }
         }
-    }, [open, behavior, onOpen, onClose])
+    }, [open, behavior, onOpen])
+
+    const handleNativeClose = () => {
+        setOpen(false)
+        onClose?.()
+    }
+
+    const handleClick = (event: React.MouseEvent<HTMLDialogElement>) => {
+        if (!closeOnBackdropClick || behavior !== 'modal') return
+
+        const rect = event.currentTarget.getBoundingClientRect()
+        const isInDialog =
+            rect.top <= event.clientY &&
+            event.clientY <= rect.bottom &&
+            rect.left <= event.clientX &&
+            event.clientX <= rect.right
+
+        if (!isInDialog) {
+            dialog.current?.close()
+        }
+    }
 
     const handleToggle = () => setOpen((prev) => !prev)
 
     return (
         <>
             {opener && cloneElement(opener, { onClick: handleToggle })}
-            <dialog ref={dialog} {...restProps} />
+            <dialog
+                ref={dialog}
+                {...restProps}
+                onClose={handleNativeClose}
+                onClick={handleClick}
+            />
         </>
     )
 }
@@ -104,4 +129,11 @@ export interface DialogProps extends React.HTMLAttributes<HTMLDialogElement> {
      * The element that triggers the dialog to open or close.
      */
     opener?: ReactElement
+    /**
+     * Whether the dialog should close when clicking on the backdrop.
+     * Only applies when behavior is 'modal'.
+     *
+     * @default false
+     */
+    closeOnBackdropClick?: boolean
 }