react-panel-layout 0.6.0 → 0.7.0

package/src/modules/dialog/useDialog.ts

@@ -0,0 +1,214 @@
+/**
+ * @file useDialog hook for imperative alert/confirm/prompt dialogs
+ */
+import * as React from "react";
+import type {
+  AlertOptions,
+  ConfirmOptions,
+  PromptOptions,
+  DialogQueueItem,
+  UseDialogReturn,
+  UseDialogProps,
+} from "./types";
+import { AlertDialog } from "./AlertDialog";
+
+type DialogState = {
+  queue: DialogQueueItem[];
+  current: DialogQueueItem | null;
+};
+
+const normalizeAlertOptions = (options: AlertOptions | string): AlertOptions => {
+  if (typeof options === "string") {
+    return { message: options };
+  }
+  return options;
+};
+
+const normalizeConfirmOptions = (options: ConfirmOptions | string): ConfirmOptions => {
+  if (typeof options === "string") {
+    return { message: options };
+  }
+  return options;
+};
+
+const normalizePromptOptions = (options: PromptOptions | string): PromptOptions => {
+  if (typeof options === "string") {
+    return { message: options };
+  }
+  return options;
+};
+
+/**
+ * Hook for imperative alert/confirm/prompt dialogs.
+ *
+ * Returns functions to show dialogs and an Outlet component that must be rendered.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { alert, confirm, prompt, Outlet } = useDialog();
+ *
+ *   const handleClick = async () => {
+ *     await alert("Hello!");
+ *
+ *     const confirmed = await confirm({
+ *       message: "Are you sure?",
+ *       confirmLabel: "Yes",
+ *       cancelLabel: "No",
+ *     });
+ *
+ *     if (confirmed) {
+ *       const name = await prompt({
+ *         message: "Enter your name:",
+ *         defaultValue: "Anonymous",
+ *       });
+ *       console.log("Name:", name);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleClick}>Show dialogs</button>
+ *       <Outlet />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export const useDialog = (props?: UseDialogProps): UseDialogReturn => {
+  const DialogComponent = props?.alertDialogComponent ?? AlertDialog;
+  const [state, setState] = React.useState<DialogState>({
+    queue: [],
+    current: null,
+  });
+
+  // Process queue when current dialog is closed
+  const processQueue = React.useCallback(() => {
+    setState((prev) => {
+      if (prev.queue.length === 0) {
+        return { ...prev, current: null };
+      }
+      const [next, ...rest] = prev.queue;
+      return { queue: rest, current: next };
+    });
+  }, []);
+
+  // Add to queue or show immediately if no current dialog
+  const enqueue = React.useCallback((item: DialogQueueItem) => {
+    setState((prev) => {
+      if (prev.current === null) {
+        return { ...prev, current: item };
+      }
+      return { ...prev, queue: [...prev.queue, item] };
+    });
+  }, []);
+
+  const alert = React.useCallback(
+    (options: AlertOptions | string): Promise<void> => {
+      return new Promise<void>((resolve) => {
+        const normalized = normalizeAlertOptions(options);
+        enqueue({
+          type: "alert",
+          options: normalized,
+          resolve,
+        });
+      });
+    },
+    [enqueue],
+  );
+
+  const confirm = React.useCallback(
+    (options: ConfirmOptions | string): Promise<boolean> => {
+      return new Promise<boolean>((resolve) => {
+        const normalized = normalizeConfirmOptions(options);
+        enqueue({
+          type: "confirm",
+          options: normalized,
+          resolve,
+        });
+      });
+    },
+    [enqueue],
+  );
+
+  const prompt = React.useCallback(
+    (options: PromptOptions | string): Promise<string | null> => {
+      return new Promise<string | null>((resolve) => {
+        const normalized = normalizePromptOptions(options);
+        enqueue({
+          type: "prompt",
+          options: normalized,
+          resolve,
+        });
+      });
+    },
+    [enqueue],
+  );
+
+  const handleConfirm = React.useCallback(
+    (value?: string) => {
+      const current = state.current;
+      if (!current) {
+        return;
+      }
+
+      if (current.type === "alert") {
+        current.resolve();
+      } else if (current.type === "confirm") {
+        current.resolve(true);
+      } else if (current.type === "prompt") {
+        current.resolve(value ?? "");
+      }
+
+      processQueue();
+    },
+    [state.current, processQueue],
+  );
+
+  const handleCancel = React.useCallback(() => {
+    const current = state.current;
+    if (!current) {
+      return;
+    }
+
+    if (current.type === "alert") {
+      current.resolve();
+    } else if (current.type === "confirm") {
+      current.resolve(false);
+    } else if (current.type === "prompt") {
+      current.resolve(null);
+    }
+
+    processQueue();
+  }, [state.current, processQueue]);
+
+  const Outlet: React.FC = React.useCallback(() => {
+    const current = state.current;
+    if (!current) {
+      return null;
+    }
+
+    const { type, options } = current;
+
+    return React.createElement(DialogComponent, {
+      type,
+      visible: true,
+      title: options.title,
+      message: options.message,
+      confirmLabel: type === "alert" ? (options as AlertOptions).okLabel : (options as ConfirmOptions).confirmLabel,
+      cancelLabel: (options as ConfirmOptions).cancelLabel,
+      placeholder: (options as PromptOptions).placeholder,
+      defaultValue: (options as PromptOptions).defaultValue,
+      inputType: (options as PromptOptions).inputType,
+      onConfirm: handleConfirm,
+      onCancel: handleCancel,
+    });
+  }, [state.current, handleConfirm, handleCancel, DialogComponent]);
+
+  return {
+    alert,
+    confirm,
+    prompt,
+    Outlet,
+  };
+};

package/src/modules/dialog/useDialogContainer.spec.ts

@@ -0,0 +1,339 @@
+/**
+ * @file Tests for useDialogContainer hook
+ */
+import * as React from "react";
+import { renderHook, act } from "@testing-library/react";
+import { useDialogContainer } from "./useDialogContainer";
+
+type CallTracker = {
+  calls: ReadonlyArray<ReadonlyArray<unknown>>;
+  fn: (...args: ReadonlyArray<unknown>) => void;
+};
+
+const createCallTracker = (): CallTracker => {
+  const calls: Array<ReadonlyArray<unknown>> = [];
+  const fn = (...args: ReadonlyArray<unknown>): void => {
+    calls.push(args);
+  };
+  return { calls, fn };
+};
+
+/**
+ * Create a mock view for test events.
+ */
+function createMockView(): React.MouseEvent<HTMLDialogElement>["view"] {
+  // eslint-disable-next-line custom/no-as-outside-guard -- test helper for view casting
+  return window as unknown as React.MouseEvent<HTMLDialogElement>["view"];
+}
+
+/**
+ * Mock SyntheticEvent with call tracking.
+ */
+type MockSyntheticEvent = React.SyntheticEvent & {
+  preventDefault: (() => void) & { calls: number };
+};
+
+/**
+ * Creates a mock React.SyntheticEvent with preventDefault tracking.
+ */
+function createMockSyntheticEvent(): MockSyntheticEvent {
+  const noop = (): void => {};
+  const noopBool = (): boolean => false;
+  const element = document.createElement("div");
+
+  const preventDefaultFn = (): void => {
+    preventDefaultFn.calls += 1;
+  };
+  preventDefaultFn.calls = 0;
+
+  return {
+    preventDefault: preventDefaultFn,
+    target: element,
+    currentTarget: element,
+    nativeEvent: new Event("test"),
+    bubbles: true,
+    cancelable: true,
+    defaultPrevented: false,
+    eventPhase: 0,
+    isTrusted: true,
+    isDefaultPrevented: noopBool,
+    stopPropagation: noop,
+    isPropagationStopped: noopBool,
+    persist: noop,
+    timeStamp: Date.now(),
+    type: "test",
+  };
+}
+
+/**
+ * Creates a mock React.MouseEvent for dialog interactions.
+ */
+function createMockMouseEvent(
+  target: HTMLElement,
+  currentTarget: HTMLDialogElement,
+): React.MouseEvent<HTMLDialogElement> {
+  const noop = (): void => {};
+  const noopBool = (): boolean => false;
+  const nativeEvent = new MouseEvent("click");
+
+  return {
+    target,
+    currentTarget,
+    nativeEvent,
+    bubbles: true,
+    cancelable: true,
+    defaultPrevented: false,
+    eventPhase: 0,
+    isTrusted: true,
+    preventDefault: noop,
+    isDefaultPrevented: noopBool,
+    stopPropagation: noop,
+    isPropagationStopped: noopBool,
+    persist: noop,
+    timeStamp: Date.now(),
+    type: "click",
+    // MouseEvent properties
+    altKey: false,
+    button: 0,
+    buttons: 1,
+    clientX: 0,
+    clientY: 0,
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    getModifierState: noopBool,
+    movementX: 0,
+    movementY: 0,
+    pageX: 0,
+    pageY: 0,
+    relatedTarget: null,
+    screenX: 0,
+    screenY: 0,
+    // UIEvent properties
+    detail: 0,
+    view: createMockView(),
+  };
+}
+
+describe("useDialogContainer", () => {
+  const dialogState = {
+    dialog: document.createElement("dialog") as HTMLDialogElement,
+    showModal: createCallTracker(),
+    close: createCallTracker(),
+  };
+
+  beforeEach(() => {
+    // Create mock dialog element
+    dialogState.dialog = document.createElement("dialog");
+    dialogState.showModal = createCallTracker();
+    dialogState.close = createCallTracker();
+    dialogState.dialog.showModal = () => {
+      dialogState.showModal.fn();
+    };
+    dialogState.dialog.close = () => {
+      dialogState.close.fn();
+    };
+    Object.defineProperty(dialogState.dialog, "open", {
+      value: false,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    document.body.style.overflow = "";
+    document.body.style.paddingRight = "";
+  });
+
+  it("should return dialogRef and dialogProps", () => {
+    const onClose = createCallTracker();
+    const { result } = renderHook(() =>
+      useDialogContainer({
+        visible: false,
+        onClose: onClose.fn,
+      }),
+    );
+
+    expect(result.current.dialogRef).toBeDefined();
+    expect(result.current.dialogProps).toBeDefined();
+    expect(result.current.dialogProps.onCancel).toBeInstanceOf(Function);
+    expect(result.current.dialogProps.onClick).toBeInstanceOf(Function);
+  });
+
+  it("should call showModal when visible becomes true", () => {
+    const onClose = createCallTracker();
+    const { result, rerender } = renderHook(
+      ({ visible }) =>
+        useDialogContainer({
+          visible,
+          onClose: onClose.fn,
+        }),
+      { initialProps: { visible: false } },
+    );
+
+    // Assign mock dialog to ref
+    act(() => {
+      (result.current.dialogRef as React.MutableRefObject<HTMLDialogElement | null>).current = dialogState.dialog;
+    });
+
+    // Make visible
+    rerender({ visible: true });
+
+    expect(dialogState.showModal.calls).toHaveLength(1);
+  });
+
+  it("should call close when visible becomes false", () => {
+    const onClose = createCallTracker();
+    const { result, rerender } = renderHook(
+      ({ visible }) =>
+        useDialogContainer({
+          visible,
+          onClose: onClose.fn,
+        }),
+      { initialProps: { visible: true } },
+    );
+
+    // Assign mock dialog to ref and set as open
+    act(() => {
+      (result.current.dialogRef as React.MutableRefObject<HTMLDialogElement | null>).current = dialogState.dialog;
+      Object.defineProperty(dialogState.dialog, "open", { value: true, configurable: true });
+    });
+
+    // Make invisible
+    rerender({ visible: false });
+
+    expect(dialogState.close.calls).toHaveLength(1);
+  });
+
+  it("should prevent default on cancel event and call onClose when closeOnEscape is true", () => {
+    const onClose = createCallTracker();
+    const { result } = renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        closeOnEscape: true,
+      }),
+    );
+
+    const mockEvent = createMockSyntheticEvent();
+
+    act(() => {
+      result.current.dialogProps.onCancel(mockEvent);
+    });
+
+    expect(mockEvent.preventDefault.calls).toBeGreaterThan(0);
+    expect(onClose.calls).toHaveLength(1);
+  });
+
+  it("should prevent default on cancel event but NOT call onClose when closeOnEscape is false", () => {
+    const onClose = createCallTracker();
+    const { result } = renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        closeOnEscape: false,
+      }),
+    );
+
+    const mockEvent = createMockSyntheticEvent();
+
+    act(() => {
+      result.current.dialogProps.onCancel(mockEvent);
+    });
+
+    expect(mockEvent.preventDefault.calls).toBeGreaterThan(0);
+    expect(onClose.calls).toHaveLength(0);
+  });
+
+  it("should call onClose on backdrop click when dismissible is true", () => {
+    const onClose = createCallTracker();
+    const { result } = renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        dismissible: true,
+      }),
+    );
+
+    // Simulate click on dialog element itself (backdrop area)
+    const mockEvent = createMockMouseEvent(dialogState.dialog, dialogState.dialog);
+
+    act(() => {
+      result.current.dialogProps.onClick(mockEvent);
+    });
+
+    expect(onClose.calls).toHaveLength(1);
+  });
+
+  it("should NOT call onClose on backdrop click when dismissible is false", () => {
+    const onClose = createCallTracker();
+    const { result } = renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        dismissible: false,
+      }),
+    );
+
+    const mockEvent = createMockMouseEvent(dialogState.dialog, dialogState.dialog);
+
+    act(() => {
+      result.current.dialogProps.onClick(mockEvent);
+    });
+
+    expect(onClose.calls).toHaveLength(0);
+  });
+
+  it("should NOT call onClose when click is on content (not backdrop)", () => {
+    const onClose = createCallTracker();
+    const { result } = renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        dismissible: true,
+      }),
+    );
+
+    const contentElement = document.createElement("div");
+
+    // Click on content inside dialog
+    const mockEvent = createMockMouseEvent(contentElement, dialogState.dialog);
+
+    act(() => {
+      result.current.dialogProps.onClick(mockEvent);
+    });
+
+    expect(onClose.calls).toHaveLength(0);
+  });
+
+  it("should set body overflow to hidden when visible and preventBodyScroll is true", () => {
+    const onClose = createCallTracker();
+    const { unmount } = renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        preventBodyScroll: true,
+      }),
+    );
+
+    expect(document.body.style.overflow).toBe("hidden");
+
+    unmount();
+
+    // Should restore
+    expect(document.body.style.overflow).toBe("");
+  });
+
+  it("should NOT set body overflow when preventBodyScroll is false", () => {
+    const onClose = createCallTracker();
+    renderHook(() =>
+      useDialogContainer({
+        visible: true,
+        onClose: onClose.fn,
+        preventBodyScroll: false,
+      }),
+    );
+
+    expect(document.body.style.overflow).toBe("");
+  });
+});

package/src/modules/dialog/useDialogContainer.ts

@@ -0,0 +1,150 @@
+/**
+ * @file Hook for managing dialog element lifecycle
+ */
+import * as React from "react";
+import { useEffectEvent } from "../../hooks/useEffectEvent";
+import { useIsomorphicLayoutEffect } from "../../hooks/useIsomorphicLayoutEffect";
+
+export type UseDialogContainerOptions = {
+  /** Whether the dialog is visible */
+  visible: boolean;
+  /** Callback when dialog should close */
+  onClose: () => void;
+  /** Whether clicking backdrop closes the dialog (default: true) */
+  dismissible?: boolean;
+  /** Whether pressing Escape closes the dialog (default: true) */
+  closeOnEscape?: boolean;
+  /** Whether to return focus to previous element on close (default: true) */
+  returnFocus?: boolean;
+  /** Whether to prevent body scroll when open (default: true) */
+  preventBodyScroll?: boolean;
+};
+
+export type UseDialogContainerReturn = {
+  /** Ref to attach to the dialog element */
+  dialogRef: React.RefObject<HTMLDialogElement | null>;
+  /** Props to spread onto the dialog element */
+  dialogProps: {
+    onCancel: (event: React.SyntheticEvent) => void;
+    onClick: (event: React.MouseEvent<HTMLDialogElement>) => void;
+  };
+};
+
+const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+
+/**
+ * Hook for managing native dialog element lifecycle
+ *
+ * @example
+ * ```tsx
+ * function MyDialog({ visible, onClose }) {
+ *   const { dialogRef, dialogProps } = useDialogContainer({
+ *     visible,
+ *     onClose,
+ *   });
+ *
+ *   return (
+ *     <dialog ref={dialogRef} {...dialogProps}>
+ *       <div>Dialog content</div>
+ *     </dialog>
+ *   );
+ * }
+ * ```
+ */
+export const useDialogContainer = (options: UseDialogContainerOptions): UseDialogContainerReturn => {
+  const {
+    visible,
+    onClose,
+    dismissible = true,
+    closeOnEscape = true,
+    returnFocus = true,
+    preventBodyScroll = true,
+  } = options;
+
+  const dialogRef = React.useRef<HTMLDialogElement | null>(null);
+  const previousActiveElementRef = React.useRef<Element | null>(null);
+
+  const handleClose = useEffectEvent(onClose);
+
+  // Open/close dialog based on visibility
+  useIsomorphicLayoutEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog || !isBrowser) {
+      return;
+    }
+
+    if (visible) {
+      // Store currently focused element before opening
+      if (returnFocus) {
+        previousActiveElementRef.current = document.activeElement;
+      }
+
+      // Open as modal (this puts it in the top layer, above all other content)
+      if (!dialog.open) {
+        dialog.showModal();
+      }
+    } else if (dialog.open) {
+      dialog.close();
+
+      // Return focus to previously focused element
+      if (returnFocus && previousActiveElementRef.current instanceof HTMLElement) {
+        previousActiveElementRef.current.focus();
+        previousActiveElementRef.current = null;
+      }
+    }
+  }, [visible, returnFocus]);
+
+  // Prevent body scroll when dialog is open
+  React.useEffect(() => {
+    if (!isBrowser || !preventBodyScroll || !visible) {
+      return;
+    }
+
+    const originalOverflow = document.body.style.overflow;
+    const originalPaddingRight = document.body.style.paddingRight;
+
+    // Calculate scrollbar width to prevent layout shift
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+
+    document.body.style.overflow = "hidden";
+    if (scrollbarWidth > 0) {
+      document.body.style.paddingRight = `${scrollbarWidth}px`;
+    }
+
+    return () => {
+      document.body.style.overflow = originalOverflow;
+      document.body.style.paddingRight = originalPaddingRight;
+    };
+  }, [visible, preventBodyScroll]);
+
+  // Handle cancel event (Escape key)
+  const handleCancel = React.useCallback(
+    (event: React.SyntheticEvent) => {
+      event.preventDefault();
+      if (closeOnEscape) {
+        handleClose();
+      }
+    },
+    [closeOnEscape, handleClose],
+  );
+
+  // Handle click on dialog (for backdrop click detection)
+  const handleClick = React.useCallback(
+    (event: React.MouseEvent<HTMLDialogElement>) => {
+      // Check if click was on the dialog backdrop (::backdrop pseudo-element area)
+      // The dialog element itself is the backdrop; clicking on it directly means backdrop click
+      if (dismissible && event.target === event.currentTarget) {
+        handleClose();
+      }
+    },
+    [dismissible, handleClose],
+  );
+
+  return {
+    dialogRef,
+    dialogProps: {
+      onCancel: handleCancel,
+      onClick: handleClick,
+    },
+  };
+};