@fpkit/acss 0.5.12 → 0.6.0

package/src/components/dialog/dialog.test.tsx

@@ -0,0 +1,450 @@
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Dialog } from "./dialog";
+import { DialogModal } from "./dialog-modal";
+
+describe("Dialog", () => {
+  describe("Controlled Component Behavior", () => {
+    it("renders dialog when isOpen is true", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={true} onOpenChange={onOpenChange} dialogTitle="Test Dialog">
+          Dialog content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      expect(dialog).toBeInTheDocument();
+      expect(screen.getByText("Test Dialog")).toBeInTheDocument();
+      expect(screen.getByText("Dialog content")).toBeInTheDocument();
+    });
+
+    it("does not render dialog when isOpen is false", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={false} onOpenChange={onOpenChange} dialogTitle="Test Dialog">
+          Dialog content
+        </Dialog>
+      );
+
+      const dialog = screen.queryByRole("dialog");
+      // Dialog element exists in DOM but should not have 'open' attribute
+      if (dialog) {
+        expect(dialog).not.toHaveAttribute("open");
+      }
+    });
+
+    it("calls onOpenChange with false when close button is clicked", async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+
+      render(
+        <Dialog isOpen={true} onOpenChange={onOpenChange} dialogTitle="Test Dialog">
+          Dialog content
+        </Dialog>
+      );
+
+      const closeButton = screen.getByRole("button", { name: /close dialog/i });
+      await user.click(closeButton);
+
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it("calls deprecated onClose callback for backward compatibility", async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      const onClose = vi.fn();
+
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          onClose={onClose}
+          dialogTitle="Test Dialog"
+        >
+          Dialog content
+        </Dialog>
+      );
+
+      const closeButton = screen.getByRole("button", { name: /close dialog/i });
+      await user.click(closeButton);
+
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onClose).toHaveBeenCalled();
+    });
+  });
+
+  describe("Modal vs Non-Modal Behavior", () => {
+    it("renders as modal dialog by default (role='dialog')", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={true} onOpenChange={onOpenChange} dialogTitle="Modal Dialog">
+          Content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      expect(dialog).toBeInTheDocument();
+      expect(dialog).toHaveAttribute("aria-modal", "true");
+    });
+
+    it("renders as alert dialog when isAlertDialog is true", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Alert Dialog"
+          isAlertDialog={true}
+        >
+          Alert content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("alertdialog");
+      expect(dialog).toBeInTheDocument();
+      // Alert dialogs (inline) should not have aria-modal
+      expect(dialog).not.toHaveAttribute("aria-modal", "true");
+    });
+  });
+
+  describe("Accessibility (ARIA Attributes)", () => {
+    it("links dialog to title with aria-labelledby", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={true} onOpenChange={onOpenChange} dialogTitle="Accessible Dialog">
+          Content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      const title = screen.getByText("Accessible Dialog");
+
+      expect(dialog).toHaveAttribute("aria-labelledby");
+      expect(title).toHaveAttribute("id");
+
+      const labelledBy = dialog.getAttribute("aria-labelledby");
+      const titleId = title.getAttribute("id");
+      expect(labelledBy).toBe(titleId);
+    });
+
+    it("links dialog to content with aria-describedby", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={true} onOpenChange={onOpenChange} dialogTitle="Test Dialog">
+          Dialog description
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      const content = screen.getByText("Dialog description").closest("section");
+
+      expect(dialog).toHaveAttribute("aria-describedby");
+      expect(content).toHaveAttribute("id");
+
+      const describedBy = dialog.getAttribute("aria-describedby");
+      const contentId = content?.getAttribute("id");
+      expect(describedBy).toBe(contentId);
+    });
+
+    it("applies custom aria-label when provided", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Dialog"
+          dialogLabel="Custom accessible label"
+        >
+          Content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      expect(dialog).toHaveAttribute("aria-label", "Custom accessible label");
+    });
+
+    it("close button has accessible label", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog isOpen={true} onOpenChange={onOpenChange} dialogTitle="Test">
+          Content
+        </Dialog>
+      );
+
+      const closeButton = screen.getByRole("button", { name: /close dialog/i });
+      expect(closeButton).toHaveAttribute("aria-label", "Close dialog");
+    });
+  });
+
+  describe("Dialog Footer", () => {
+    it("shows footer with cancel and confirm buttons by default", () => {
+      const onOpenChange = vi.fn();
+      const onConfirm = vi.fn();
+
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Confirm Action"
+          onConfirm={onConfirm}
+        >
+          Content
+        </Dialog>
+      );
+
+      expect(screen.getByRole("button", { name: /cancel/i })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: /confirm/i })).toBeInTheDocument();
+    });
+
+    it("hides footer when hideFooter is true", () => {
+      const onOpenChange = vi.fn();
+
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="No Footer"
+          hideFooter={true}
+        >
+          Content
+        </Dialog>
+      );
+
+      expect(screen.queryByRole("button", { name: /cancel/i })).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: /confirm/i })).not.toBeInTheDocument();
+    });
+
+    it("calls onConfirm when confirm button is clicked", async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      const onConfirm = vi.fn();
+
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Test"
+          onConfirm={onConfirm}
+        >
+          Content
+        </Dialog>
+      );
+
+      const confirmButton = screen.getByRole("button", { name: /confirm/i });
+      await user.click(confirmButton);
+
+      expect(onConfirm).toHaveBeenCalled();
+    });
+
+    it("uses custom button labels when provided", () => {
+      const onOpenChange = vi.fn();
+      const onConfirm = vi.fn();
+
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Delete Item"
+          onConfirm={onConfirm}
+          confirmLabel="Delete"
+          cancelLabel="Keep"
+        >
+          Are you sure?
+        </Dialog>
+      );
+
+      expect(screen.getByRole("button", { name: /delete/i })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: /keep/i })).toBeInTheDocument();
+    });
+  });
+
+  describe("Custom Styling", () => {
+    it("applies custom className", () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Styled Dialog"
+          className="custom-class"
+        >
+          Content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      expect(dialog).toHaveClass("custom-class");
+    });
+
+    it("applies custom inline styles", () => {
+      const onOpenChange = vi.fn();
+      const customStyles = { maxWidth: "600px" };
+
+      render(
+        <Dialog
+          isOpen={true}
+          onOpenChange={onOpenChange}
+          dialogTitle="Custom Styled"
+          styles={customStyles}
+        >
+          Content
+        </Dialog>
+      );
+
+      const dialog = screen.getByRole("dialog");
+      expect(dialog).toHaveStyle({ maxWidth: "600px" });
+    });
+  });
+});
+
+describe("DialogModal", () => {
+  describe("Uncontrolled State Management", () => {
+    it("renders trigger button with custom label", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open My Dialog">
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open my dialog/i });
+      expect(triggerButton).toBeInTheDocument();
+    });
+
+    it("opens dialog when trigger button is clicked", async () => {
+      const user = userEvent.setup();
+
+      render(
+        <DialogModal dialogTitle="Test Dialog" btnLabel="Open">
+          Dialog content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open/i });
+      await user.click(triggerButton);
+
+      await waitFor(() => {
+        expect(screen.getByRole("dialog")).toBeInTheDocument();
+        expect(screen.getByText("Dialog content")).toBeInTheDocument();
+      });
+    });
+
+    it("closes dialog when close button is clicked", async () => {
+      const user = userEvent.setup();
+
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open">
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open/i });
+      await user.click(triggerButton);
+
+      const closeButton = screen.getByRole("button", { name: /close dialog/i });
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        const dialog = screen.queryByRole("dialog");
+        // Dialog should not have 'open' attribute when closed
+        if (dialog) {
+          expect(dialog).not.toHaveAttribute("open");
+        }
+      });
+    });
+
+    it("calls onClose callback when dialog is closed", async () => {
+      const user = userEvent.setup();
+      const onClose = vi.fn();
+
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open" onClose={onClose}>
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open/i });
+      await user.click(triggerButton);
+
+      const closeButton = screen.getByRole("button", { name: /close dialog/i });
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(onClose).toHaveBeenCalled();
+      });
+    });
+
+    it("calls btnOnClick before opening dialog", async () => {
+      const user = userEvent.setup();
+      const btnOnClick = vi.fn();
+
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open" btnOnClick={btnOnClick}>
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open/i });
+      await user.click(triggerButton);
+
+      expect(btnOnClick).toHaveBeenCalled();
+    });
+  });
+
+  describe("Focus Restoration", () => {
+    it("restores focus to trigger button after dialog closes", async () => {
+      const user = userEvent.setup();
+
+      render(
+        <DialogModal dialogTitle="Focus Test" btnLabel="Open Dialog">
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open dialog/i });
+      await user.click(triggerButton);
+
+      const closeButton = screen.getByRole("button", { name: /close dialog/i });
+      await user.click(closeButton);
+
+      // Wait for focus restoration (has 100ms delay in DialogModal)
+      await waitFor(
+        () => {
+          // Focus restoration happens after dialog closes
+          expect(triggerButton).toHaveFocus();
+        },
+        { timeout: 300, interval: 50 }
+      );
+    });
+  });
+
+  describe("Button Props", () => {
+    it("applies custom button size", () => {
+      render(
+        <DialogModal dialogTitle="Test" btnLabel="Open" btnSize="lg">
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByRole("button", { name: /open/i });
+      expect(triggerButton).toHaveAttribute("data-btn", "lg");
+    });
+
+    it("forwards additional button props", () => {
+      render(
+        <DialogModal
+          dialogTitle="Test"
+          btnLabel="Open"
+          btnProps={{ "data-testid": "custom-trigger", disabled: false }}
+        >
+          Content
+        </DialogModal>
+      );
+
+      const triggerButton = screen.getByTestId("custom-trigger");
+      expect(triggerButton).toBeInTheDocument();
+      expect(triggerButton).not.toBeDisabled();
+    });
+  });
+});

package/src/components/dialog/dialog.tsx

@@ -1,58 +1,59 @@
-import React, { useRef, useEffect, CSSProperties } from "react";
+import React, { useRef, useEffect, useCallback, useId } from "react";
 import UI from "#components/ui";
 import DialogHeader from "#components/dialog/views/dialog-header";
 import DialogFooter from "#components/dialog/views/dialog-footer";
 import { useDialogClickHandler } from "#hooks/useDialogClickHandler.js";
+import type { DialogProps } from "./dialog.types";
 
 /**
- * Defines the props for the Dialog component.
+ * A controlled dialog component that supports both modal and non-modal (inline alert) modes.
  *
- * @property {boolean} [showDialog] - Determines whether the dialog should be shown.
- * @property {boolean} [isAlertDialog] - Determines whether the dialog should be displayed as an alert dialog.
- * @property {() => void} [onClose] - A callback function to be called when the dialog is closed.
- * @property {string} dialogTitle - The title of the dialog.
- * @property {string} [dialogLabel] - An optional label for the dialog.
- * @property {React.ReactNode} children - The content to be displayed inside the dialog.
- * @property {() => void | Promise<void>} [onConfirm] - A callback function to be called when the user confirms the dialog.
- * @property {string} [confirmLabel] - The label for the confirm button.
- * @property {string} [cancelLabel] - The label for the cancel button.
- * @property {string} [className] - An optional CSS class name to be applied to the dialog.
- * @property {CSSProperties} [styles] - Optional inline styles to be applied to the dialog.
- */
-type DialogModalProps = React.ComponentProps<typeof UI> &
-  React.ComponentProps<"dialog"> & {
-    dialogTitle: string;
-    dialogLabel?: string;
-    children: React.ReactNode;
-    showDialog?: boolean;
-    isAlertDialog?: boolean;
-    onClose?: () => void;
-    onConfirm?: () => void | Promise<void>;
-    confirmLabel?: string;
-    cancelLabel?: string;
-    className?: string;
-    hideFooter?: boolean;
-    styles?: CSSProperties;
-  };
-
-/**
- * Renders a dialog modal component with customizable content and behavior.
+ * **Modal Dialog** (default): Uses native `<dialog>` element with `.showModal()` which provides:
+ * - Automatic focus trap (Tab cycles within dialog)
+ * - Escape key closes dialog (native behavior)
+ * - Backdrop overlay with click-to-close
+ * - Inert background (page content becomes non-interactive)
+ *
+ * **Inline Alert Dialog** (`isAlertDialog={true}`): Uses `.show()` for non-modal inline alerts:
+ * - No focus trap (page remains interactive)
+ * - No escape key behavior
+ * - Positioned inline in page flow
+ * - User must explicitly close with button
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Controlled usage
+ * const [open, setOpen] = useState(false);
+ * <Dialog
+ *   isOpen={open}
+ *   onOpenChange={setOpen}
+ *   dialogTitle="Confirm Delete"
+ * >
+ *   Are you sure you want to delete this item?
+ * </Dialog>
+ * ```
  *
- * @param showDialog - Determines whether the dialog should be shown.
- * @param isAlertDialog - Determines whether the dialog should be displayed as an alert dialog.
- * @param onClose - A callback function to be called when the dialog is closed.
- * @param dialogTitle - The title of the dialog.
- * @param dialogLabel - An optional label for the dialog.
- * @param children - The content to be displayed inside the dialog.
- * @param onConfirm - A callback function to be called when the user confirms the dialog.
- * @param confirmLabel - The label for the confirm button.
- * @param cancelLabel - The label for the cancel button.
- * @param className - An optional CSS class name to be applied to the dialog.
- * @param styles - Optional inline styles to be applied to the dialog.
+ * @param {DialogProps} props - Component props
+ * @param {boolean} props.isOpen - Controls whether the dialog is currently open
+ * @param {(open: boolean) => void} props.onOpenChange - Callback fired when dialog open state changes
+ * @param {string} props.dialogTitle - The title displayed in the dialog header
+ * @param {boolean} [props.isAlertDialog=false] - If true, renders as non-modal inline alert
+ * @param {() => void} [props.onClose] - Deprecated: Use onOpenChange. Called when dialog closes.
+ * @param {ReactNode} props.children - Content to display inside the dialog body
+ * @param {() => void | Promise<void>} [props.onConfirm] - Callback fired when confirm button is clicked
+ * @param {string} [props.confirmLabel="Confirm"] - Text label for confirm button
+ * @param {string} [props.cancelLabel="Cancel"] - Text label for cancel button
+ * @param {boolean} [props.hideFooter=false] - If true, hides the footer with action buttons
+ * @param {string} [props.className] - Additional CSS classes to apply
+ * @param {string} [props.dialogLabel] - Optional aria-label for the dialog
+ * @param {CSSProperties} [props.styles] - Inline styles to apply to dialog element
+ * @returns {JSX.Element} A controlled dialog component
  */
-export const Dialog: React.FC<DialogModalProps> = ({
-  showDialog,
-  isAlertDialog,
+export const Dialog: React.FC<DialogProps> = ({
+  isOpen,
+  onOpenChange,
+  isAlertDialog = false,
   onClose,
   dialogTitle,
   dialogLabel,
@@ -61,24 +62,23 @@ export const Dialog: React.FC<DialogModalProps> = ({
   confirmLabel = "Confirm",
   cancelLabel = "Cancel",
   className = "",
-  hideFooter,
+  hideFooter = false,
   styles,
 }) => {
   const dialogRef = useRef<HTMLDialogElement>(null);
-  const [isOpen, setIsOpen] = React.useState(showDialog);
-
-  useEffect(() => {
-    setIsOpen(showDialog);
-  }, [showDialog]);
+  const titleId = useId();
 
+  // Handle native dialog open/close based on isOpen prop
   useEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog) return;
 
     if (isOpen) {
       if (isAlertDialog) {
+        // Non-modal inline alert - no focus trap, no backdrop
         dialog.show();
       } else {
+        // Modal dialog - native focus trap, escape key, backdrop
         dialog.showModal();
       }
     } else {
@@ -86,13 +86,18 @@ export const Dialog: React.FC<DialogModalProps> = ({
     }
   }, [isOpen, isAlertDialog]);
 
-  const handleClose = () => {
+  // Handle close event - notify parent via onOpenChange
+  const handleClose = useCallback(() => {
+    onOpenChange(false);
+    // Support deprecated onClose prop for backward compatibility
     if (onClose) onClose();
-    setIsOpen(false);
-  };
+  }, [onOpenChange, onClose]);
 
+  // Handle backdrop clicks (only for modal dialogs)
   const handleClickOutside = useDialogClickHandler(dialogRef, handleClose);
 
+  const contentId = useId();
+
   return (
     <UI
       as="dialog"
@@ -100,16 +105,19 @@ export const Dialog: React.FC<DialogModalProps> = ({
       ref={dialogRef}
       onClose={handleClose}
       onClick={handleClickOutside}
-      aria-modal={isOpen ? "true" : undefined}
-      className={`${"dialog-modal"} ${className}`}
+      aria-modal={isOpen && !isAlertDialog ? "true" : undefined}
+      aria-labelledby={titleId}
+      aria-describedby={contentId}
       aria-label={dialogLabel}
+      className={`dialog-modal ${className}`.trim()}
       style={styles}
     >
-      <DialogHeader dialogTitle={dialogTitle} onClick={handleClose} />
+      <DialogHeader dialogTitle={dialogTitle} onClick={handleClose} id={titleId} />
 
       <UI
         as="section"
-        className={`dialog-content ${className}`}
+        id={contentId}
+        className="dialog-content"
         onClick={(e: React.MouseEvent) => e.stopPropagation()}
       >
         {children}
@@ -125,4 +133,6 @@ export const Dialog: React.FC<DialogModalProps> = ({
     </UI>
   );
 };
+Dialog.displayName = "Dialog";
+
 export default React.memo(Dialog);