@fpkit/acss 0.5.12 → 0.6.0

package/src/components/dialog/dialog.types.ts

@@ -0,0 +1,133 @@
+import { CSSProperties, ReactNode } from "react";
+
+/**
+ * Base properties shared by all dialog variants.
+ *
+ * @property {string} dialogTitle - The title displayed in the dialog header
+ * @property {string} [dialogLabel] - Optional accessible label for the dialog (aria-label)
+ * @property {ReactNode} children - Content to be displayed inside the dialog body
+ * @property {string} [className] - Additional CSS classes to apply to the dialog
+ * @property {CSSProperties} [styles] - Inline styles to apply to the dialog element
+ */
+export interface BaseDialogProps {
+  /** The title displayed in the dialog header */
+  dialogTitle: string;
+  /** Optional accessible label for the dialog (aria-label) */
+  dialogLabel?: string;
+  /** Content to be displayed inside the dialog body */
+  children: ReactNode;
+  /** Additional CSS classes to apply to the dialog */
+  className?: string;
+  /** Inline styles to apply to the dialog element */
+  styles?: CSSProperties;
+}
+
+/**
+ * Props for the controlled Dialog component.
+ * Use this when you want to manage dialog state externally.
+ *
+ * @extends BaseDialogProps
+ * @property {boolean} isOpen - Controls whether the dialog is currently open
+ * @property {(open: boolean) => void} onOpenChange - Callback fired when dialog open state should change
+ * @property {boolean} [isAlertDialog=false] - If true, renders as non-modal inline alert using dialog.show()
+ * @property {() => void} [onClose] - Deprecated: Use onOpenChange instead. Called when dialog closes.
+ * @property {() => void | Promise<void>} [onConfirm] - Callback fired when confirm button is clicked
+ * @property {string} [confirmLabel="Confirm"] - Text label for the confirm button
+ * @property {string} [cancelLabel="Cancel"] - Text label for the cancel button
+ * @property {boolean} [hideFooter=false] - If true, hides the dialog footer with action buttons
+ */
+export interface DialogProps extends BaseDialogProps {
+  /** Controls whether the dialog is currently open (controlled component) */
+  isOpen: boolean;
+  /** Callback fired when dialog open state should change */
+  onOpenChange: (open: boolean) => void;
+  /** If true, renders as non-modal inline alert using dialog.show() instead of dialog.showModal() */
+  isAlertDialog?: boolean;
+  /** @deprecated Use onOpenChange instead. Called when dialog closes. */
+  onClose?: () => void;
+  /** Callback fired when confirm button is clicked */
+  onConfirm?: () => void | Promise<void>;
+  /** Text label for the confirm button */
+  confirmLabel?: string;
+  /** Text label for the cancel button */
+  cancelLabel?: string;
+  /** If true, hides the dialog footer with action buttons */
+  hideFooter?: boolean;
+}
+
+/**
+ * Props for the DialogModal wrapper component.
+ * This component manages dialog state internally and provides a trigger button.
+ * Use this for simple cases where you don't need external state management.
+ *
+ * @extends BaseDialogProps
+ * @property {boolean} [isAlertDialog=false] - If true, renders as non-modal inline alert
+ * @property {() => void} [onClose] - Callback fired when dialog is closed
+ * @property {() => void | Promise<void>} [onConfirm] - Callback fired when confirm button is clicked
+ * @property {string} [confirmLabel="Confirm"] - Text label for the confirm button
+ * @property {string} [cancelLabel="Cancel"] - Text label for the cancel button
+ * @property {boolean} [hideFooter=false] - If true, hides the dialog footer
+ * @property {string} [btnLabel="Open Dialog"] - Text label for the trigger button
+ * @property {"sm" | "md" | "lg"} [btnSize="sm"] - Size variant for the trigger button
+ * @property {() => void} [btnOnClick] - Callback fired when trigger button is clicked (before opening)
+ */
+export interface DialogModalProps extends BaseDialogProps {
+  /** If true, renders as non-modal inline alert using dialog.show() */
+  isAlertDialog?: boolean;
+  /** Callback fired when dialog is closed */
+  onClose?: () => void;
+  /** Callback fired when confirm button is clicked */
+  onConfirm?: () => void | Promise<void>;
+  /** Text label for the confirm button */
+  confirmLabel?: string;
+  /** Text label for the cancel button */
+  cancelLabel?: string;
+  /** If true, hides the dialog footer with action buttons */
+  hideFooter?: boolean;
+  /** Text label for the trigger button that opens the dialog */
+  btnLabel?: string;
+  /** Size variant for the trigger button */
+  btnSize?: "sm" | "md" | "lg";
+  /** Callback fired when trigger button is clicked (before opening dialog) */
+  btnOnClick?: () => void;
+  /** Additional props to pass to the trigger button component */
+  btnProps?: Record<string, unknown>;
+}
+
+/**
+ * Props for the DialogHeader component.
+ *
+ * @property {string} dialogTitle - The title text to display in the header
+ * @property {() => void} onClick - Callback fired when the close button is clicked
+ * @property {string} [id] - Optional ID for aria-labelledby linking. Auto-generated if not provided.
+ * @property {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} [type="h3"] - Heading level for the title
+ */
+export interface DialogHeaderProps {
+  /** The title text to display in the header */
+  dialogTitle: string;
+  /** Callback fired when the close button is clicked */
+  onClick: () => void;
+  /** Optional ID for aria-labelledby linking. Auto-generated if not provided. */
+  id?: string;
+  /** Heading level for the title */
+  type?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+/**
+ * Props for the DialogFooter component.
+ *
+ * @property {() => void} onClose - Callback fired when cancel button is clicked
+ * @property {() => void | Promise<void>} [onConfirm] - Callback fired when confirm button is clicked
+ * @property {string} confirmLabel - Text label for the confirm button
+ * @property {string} cancelLabel - Text label for the cancel button
+ */
+export interface DialogFooterProps {
+  /** Callback fired when cancel button is clicked */
+  onClose: () => void;
+  /** Callback fired when confirm button is clicked */
+  onConfirm?: () => void | Promise<void>;
+  /** Text label for the confirm button */
+  confirmLabel: string;
+  /** Text label for the cancel button */
+  cancelLabel: string;
+}

package/src/components/dialog/views/dialog-footer.tsx

@@ -1,26 +1,67 @@
-import React from "react";
+import React, { useCallback } from "react";
 import UI from "#components/ui";
 import Button from "#components/buttons/button";
+import type { DialogFooterProps } from "../dialog.types";
 
-type DialogFooterProps = {
-  onClose: () => void;
-  onConfirm?: () => void | Promise<void>;
-  confirmLabel: string;
-  cancelLabel: string;
-};
-
+/**
+ * DialogFooter component renders action buttons for dialog confirmation/cancellation.
+ *
+ * This component provides a consistent footer layout with:
+ * - Cancel button (secondary style) - Always shown if cancelLabel provided
+ * - Confirm button (primary style) - Only shown if onConfirm callback provided
+ * - Proper semantic button types
+ * - Accessible button sizing and spacing
+ * - Memoized to prevent unnecessary re-renders
+ *
+ * @component
+ * @param {DialogFooterProps} props - Component props
+ * @param {() => void} props.onClose - Callback fired when cancel button is clicked
+ * @param {() => void | Promise<void>} [props.onConfirm] - Optional callback for confirm action. If omitted, confirm button is hidden.
+ * @param {string} props.confirmLabel - Text label for the confirm button
+ * @param {string} props.cancelLabel - Text label for the cancel button
+ * @returns {JSX.Element} A footer section with action buttons
+ *
+ * @example
+ * ```tsx
+ * // Simple close-only footer
+ * <DialogFooter
+ *   onClose={() => setOpen(false)}
+ *   cancelLabel="Close"
+ *   confirmLabel="OK"
+ * />
+ *
+ * // Confirmation dialog with both actions
+ * <DialogFooter
+ *   onClose={() => setOpen(false)}
+ *   onConfirm={async () => await deleteItem()}
+ *   confirmLabel="Delete"
+ *   cancelLabel="Cancel"
+ * />
+ * ```
+ */
 const DialogFooter: React.FC<DialogFooterProps> = ({
   onClose,
   onConfirm,
   confirmLabel,
   cancelLabel,
 }) => {
+  // Memoize handlers to prevent unnecessary re-renders
+  const handleCancel = useCallback(() => {
+    onClose();
+  }, [onClose]);
+
+  const handleConfirm = useCallback(() => {
+    if (onConfirm) {
+      onConfirm();
+    }
+  }, [onConfirm]);
+
   return (
     <UI as="section" className="dialog-footer">
       {cancelLabel && (
         <Button
           type="button"
-          onClick={onClose}
+          onClick={handleCancel}
           className="dialog-button button-secondary"
           data-btn="sm"
         >
@@ -31,7 +72,7 @@ const DialogFooter: React.FC<DialogFooterProps> = ({
       {onConfirm && (
         <Button
           type="button"
-          onClick={onConfirm}
+          onClick={handleConfirm}
           className="dialog-button button-primary"
           data-btn="sm"
         >
@@ -42,4 +83,6 @@ const DialogFooter: React.FC<DialogFooterProps> = ({
   );
 };
 
-export default DialogFooter;
+DialogFooter.displayName = "DialogFooter";
+
+export default React.memo(DialogFooter);

package/src/components/dialog/views/dialog-header.tsx

@@ -1,45 +1,50 @@
-import React from "react";
+import React, { useCallback } from "react";
 import UI from "#components/ui";
 import Heading from "#components/heading/heading";
 import Button from "#components/buttons/button";
 import Icon from "#components/icons/icon";
-
-export type DialogHeaderProps = {
-  dialogTitle: string;
-  onClick: () => void;
-} & React.ComponentProps<typeof Heading>;
+import type { DialogHeaderProps } from "../dialog.types";
 
 /**
  * DialogHeader component displays the header section of a dialog with a title and close button.
  *
+ * This component is optimized for accessibility with:
+ * - Unique ID for `aria-labelledby` linking to parent dialog
+ * - Semantic heading structure for screen readers
+ * - Clear close button with accessible label
+ * - Memoized to prevent unnecessary re-renders
+ *
  * @component
- * @param {Object} props - Component props
+ * @param {DialogHeaderProps} props - Component props
  * @param {string} props.dialogTitle - The title text to display in the dialog header
  * @param {() => void} props.onClick - Callback function triggered when close button is clicked
- * @param {string} [props.type='h3'] - Heading type/level to use for the title
+ * @param {string} [props.id] - Optional ID for aria-labelledby linking. Auto-generated if not provided.
+ * @param {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} [props.type="h3"] - Heading level for semantic structure
  * @returns {JSX.Element} A dialog header with title and close button
  *
  * @example
- * ```jsx
+ * ```tsx
  * <DialogHeader
+ *   id="dialog-title-1"
  *   dialogTitle="Confirm Action"
  *   onClick={() => setIsOpen(false)}
  *   type="h2"
  * />
  * ```
  */
-
-const DialogHeader = ({
+const DialogHeader: React.FC<DialogHeaderProps> = ({
   dialogTitle,
   onClick,
+  id,
   type = "h3",
-}: DialogHeaderProps): JSX.Element => {
-  const handleClose = () => {
+}) => {
+  const handleClose = useCallback(() => {
     onClick();
-  };
+  }, [onClick]);
+
   return (
     <UI as="div" classes="dialog-header">
-      <Heading type={type} className="dialog-title">
+      <Heading type={type} className="dialog-title" id={id}>
         {dialogTitle || "Dialog"}
       </Heading>
       <Button