perf(date-picker): defer flatpickr destroy to survive portal-driven DOM moves

When a portal moves a DOM element, the browser fires
`disconnectedCallback` followed by `connectedCallback` in the same
microtask. The immediate `destroy()` in `disconnectedCallback` killed
the flatpickr instance permanently, even though the element was about
to be reattached.

`DeferredDestroy` pushes the teardown into a `setTimeout(0)` so that
`connectedCallback` can cancel it if the element is reconnected.
`Picker` methods now guard against a nulled-out flatpickr instance.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jgroth

src/components/date-picker/flatpickr-adapter/deferred-destroy.spec.ts

@@ -0,0 +1,76 @@
+import { vi } from 'vitest';
+import { DeferredDestroy } from './deferred-destroy';
+
+let deferredDestroy: DeferredDestroy;
+
+beforeEach(() => {
+    vi.useFakeTimers();
+    deferredDestroy = new DeferredDestroy();
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+test('schedule does not call the callback synchronously', () => {
+    const callback = vi.fn();
+    deferredDestroy.schedule(callback);
+
+    expect(callback).not.toHaveBeenCalled();
+});
+
+test('schedule calls the callback after the microtask completes', () => {
+    const callback = vi.fn();
+    deferredDestroy.schedule(callback);
+    vi.runAllTimers();
+
+    expect(callback).toHaveBeenCalledTimes(1);
+});
+
+test('cancel prevents the callback from firing', () => {
+    const callback = vi.fn();
+    deferredDestroy.schedule(callback);
+    deferredDestroy.cancel();
+    vi.runAllTimers();
+
+    expect(callback).not.toHaveBeenCalled();
+});
+
+test('cancel is safe to call when nothing is scheduled', () => {
+    expect(() => deferredDestroy.cancel()).not.toThrow();
+});
+
+test('scheduling twice only fires the second callback', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    deferredDestroy.schedule(first);
+    deferredDestroy.schedule(second);
+    vi.runAllTimers();
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+});
+
+test('schedule works after a previous cancel', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    deferredDestroy.schedule(first);
+    deferredDestroy.cancel();
+    deferredDestroy.schedule(second);
+    vi.runAllTimers();
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+});
+
+test('schedule works after a previous callback has fired', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    deferredDestroy.schedule(first);
+    vi.runAllTimers();
+    deferredDestroy.schedule(second);
+    vi.runAllTimers();
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+});

src/components/date-picker/flatpickr-adapter/deferred-destroy.ts

@@ -0,0 +1,31 @@
+/**
+ * Defers a destroy callback so that portal-driven DOM moves
+ * (disconnect + reconnect in the same microtask) can cancel the
+ * destroy before it fires.
+ */
+export class DeferredDestroy {
+    private pendingDestroyTimer: ReturnType<typeof setTimeout> | null = null;
+
+    /**
+     * Schedule a deferred destroy callback. Any previously pending
+     * callback is cancelled first.
+     * @param callback
+     */
+    public schedule(callback: () => void): void {
+        this.cancel();
+        this.pendingDestroyTimer = setTimeout(() => {
+            this.pendingDestroyTimer = null;
+            callback();
+        }, 0);
+    }
+
+    /**
+     * Cancel the pending destroy callback, if any.
+     */
+    public cancel(): void {
+        if (this.pendingDestroyTimer !== null) {
+            clearTimeout(this.pendingDestroyTimer);
+            this.pendingDestroyTimer = null;
+        }
+    }
+}

src/components/date-picker/flatpickr-adapter/flatpickr-adapter.tsx

@@ -9,6 +9,7 @@ import { QuarterPicker } from '../pickers/quarter-picker';
 import { TimePicker } from '../pickers/time-picker';
 import { WeekPicker } from '../pickers/week-picker';
 import { YearPicker } from '../pickers/year-picker';
+import { DeferredDestroy } from './deferred-destroy';
 
 /**
  * This component is internal and only supposed to be used by
@@ -71,6 +72,7 @@ export class DatePickerCalendar {
 
     private picker: Picker;
     private flatPickrCreated: boolean = false;
+    private deferredDestroy = new DeferredDestroy();
 
     private container: HTMLElement;
 
@@ -173,9 +175,15 @@ export class DatePickerCalendar {
         this.flatPickrCreated = true;
     }
 
+    public connectedCallback() {
+        this.deferredDestroy.cancel();
+    }
+
     public disconnectedCallback() {
-        this.picker.destroy();
-        this.flatPickrCreated = false;
+        this.deferredDestroy.schedule(() => {
+            this.picker.destroy();
+            this.flatPickrCreated = false;
+        });
     }
 
     public render() {

src/components/date-picker/pickers/picker.ts

@@ -67,11 +67,11 @@ export abstract class Picker {
     }
 
     public setValue(value: Date) {
-        this.flatpickr.setDate(value, false);
+        this.flatpickr?.setDate(value, false);
     }
 
     public redraw() {
-        this.flatpickr.redraw();
+        this.flatpickr?.redraw();
     }
 
     public destroy() {
@@ -80,6 +80,7 @@ export abstract class Picker {
         }
 
         this.flatpickr.destroy();
+        this.flatpickr = null;
     }
 
     public abstract getConfig(
@@ -139,6 +140,6 @@ export abstract class Picker {
     }
 
     private handleOnClose() {
-        this.flatpickr.element.focus();
+        this.flatpickr?.element.focus();
     }
 }