@fpkit/acss 0.5.12 → 0.5.13

package/src/components/alert/alert.tsx

@@ -1,12 +1,18 @@
 import React from "react";
-import UI from "#components/ui";
-import Icon from "#components/icons/icon";
 import { IconProps } from "#components/icons/types";
-import DismissButton from "./elements/dismiss-button";
+import { AlertView } from "./views";
 
-// First, define a type for the valid severity values
+// ============================================================================
+// TYPES & CONFIGURATION
+// ============================================================================
+
+/**
+ * Valid severity levels for alerts.
+ * Each severity has associated colors, icons, and ARIA attributes.
+ */
 type Severity = "default" | "info" | "success" | "warning" | "error";
 
+
 /**
  * Props for the Alert component.
  */
@@ -39,34 +45,158 @@ export type AlertProps = {
   onDismiss?: () => void;
 
   /**
-   * Size of the icon in pixels.
-   * @default 32
+   * Size of the severity icon in pixels.
+   * Allows customization of icon size for different contexts.
+   * @default 24
+   * @example
+   * ```tsx
+   * <Alert iconSize={32} severity="error">Larger icon</Alert>
+   * <Alert iconSize={16} severity="info">Smaller icon</Alert>
+   * ```
    */
   iconSize?: number;
 
   /**
-   * Whether to hide the icon.
+   * Whether to hide the severity icon.
+   * When true, only text content is displayed.
+   * @default false
    */
   hideIcon?: boolean;
 
   /**
    * Additional props to pass to the Icon component.
+   * Allows fine-grained control over icon appearance.
+   * @example
+   * ```tsx
+   * <Alert iconProps={{ className: 'custom-icon', 'aria-label': 'Custom' }}>
+   *   Alert with custom icon props
+   * </Alert>
+   * ```
    */
   iconProps?: IconProps;
-} & React.ComponentProps<typeof UI>;
+
+  /**
+   * Duration in milliseconds before the alert automatically dismisses.
+   * Set to 0 or undefined to disable auto-dismiss.
+   * @default undefined
+   * @example
+   * ```tsx
+   * <Alert autoHideDuration={5000}>Success message</Alert>
+   * ```
+   */
+  autoHideDuration?: number;
+
+  /**
+   * Whether to pause auto-dismiss when the alert is hovered or focused.
+   * Complies with WCAG 2.2.1 (Timing Adjustable).
+   * @default true
+   */
+  pauseOnHover?: boolean;
+
+  /**
+   * Semantic heading level for the title (2-6).
+   * When undefined, uses <strong> element instead of heading.
+   * Use this to maintain proper heading hierarchy on the page.
+   * @default undefined
+   * @example
+   * ```tsx
+   * <Alert titleLevel={2} title="Section Alert">...</Alert>
+   * <Alert titleLevel={3} title="Subsection Alert">...</Alert>
+   * ```
+   */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+
+  /**
+   * Custom action buttons to display in the alert.
+   * @example
+   * ```tsx
+   * <Alert actions={<><Button>Undo</Button><Button>Dismiss</Button></>}>
+   *   File deleted
+   * </Alert>
+   * ```
+   */
+  actions?: React.ReactNode;
+
+  /**
+   * Whether to automatically focus the alert when it becomes visible.
+   * Useful for critical alerts that require immediate attention.
+   * @default false
+   */
+  autoFocus?: boolean;
+
+  /**
+   * Visual variant of the alert.
+   * - outlined: Border with lighter background (default)
+   * - filled: Solid colored background
+   * - soft: No border, subtle background
+   * @default "outlined"
+   */
+  variant?: "outlined" | "filled" | "soft";
+
+  /**
+   * Content rendering mode for alert children.
+   * Determines how the children content is wrapped in the alert message area.
+   * - "text": Wraps children in a paragraph tag (default, for simple text content)
+   * - "node": Renders children directly without wrapper (for complex layouts, lists, or custom components)
+   * @default "text"
+   * @example Simple text content (uses default "text" mode)
+   * ```tsx
+   * <Alert severity="info">
+   *   This is a simple text message that will be wrapped in a paragraph.
+   * </Alert>
+   * ```
+   * @example Complex content with list
+   * ```tsx
+   * <Alert severity="warning" contentType="node">
+   *   <p>Please review the following items:</p>
+   *   <ul>
+   *     <li>Check your email settings</li>
+   *     <li>Update your password</li>
+   *     <li>Enable two-factor authentication</li>
+   *   </ul>
+   * </Alert>
+   * ```
+   * @example Custom component layout
+   * ```tsx
+   * <Alert severity="success" contentType="node">
+   *   <div className="custom-layout">
+   *     <p>Operation completed successfully!</p>
+   *     <div className="stats">
+   *       <span>Items processed: 150</span>
+   *       <span>Time elapsed: 2.5s</span>
+   *     </div>
+   *   </div>
+   * </Alert>
+   * ```
+   */
+  contentType?: "text" | "node";
+} & Omit<React.HTMLAttributes<HTMLDivElement>, 'title' | 'children'>;
 
 /**
- * Alert is a customizable component for displaying status messages with different severity levels.
+ * Alert is a fully accessible component for displaying status messages with different severity levels.
  * It supports multiple severity types (default, info, success, warning, error) and can include
  * optional titles and dismissal functionality.
  *
  * Features:
  * - Multiple severity levels with matching visual indicators
- * - Optional title and dismissible states
+ * - Three variants: outlined (default), filled, and soft
+ * - Auto-dismiss with configurable duration and pause on hover/focus
+ * - Optional title with configurable heading levels (h2-h6) for proper document structure
+ * - Action buttons support for interactive alerts
  * - Accessible by default with appropriate ARIA attributes
- * - Customizable icons through iconProps
+ * - Screen reader announcements for severity levels
+ * - Keyboard support (ESC to dismiss)
+ * - WCAG 2.1 Level AA compliant
+ *
+ * Accessibility Features:
+ * - Visually hidden severity text for screen readers (WCAG 1.1.1, 1.4.1)
+ * - Configurable heading levels to maintain document hierarchy (WCAG 1.3.1)
+ * - Visible focus indicators for keyboard navigation (WCAG 2.4.7)
+ * - Adequate color contrast for all variants (WCAG 1.4.3)
+ * - 44×44px minimum touch target size for dismiss button (WCAG 2.5.5)
+ * - Pause auto-dismiss on hover/focus (WCAG 2.2.1)
  *
- * @example
+ * @example Basic Usage
  * ```tsx
  * <Alert
  *   open={true}
@@ -79,9 +209,150 @@ export type AlertProps = {
  * </Alert>
  * ```
  *
+ * @example With Heading Level (for proper document structure)
+ * ```tsx
+ * <Alert
+ *   open={true}
+ *   severity="error"
+ *   title="Error Title"
+ *   titleLevel={2}
+ *   dismissible={true}
+ * >
+ *   Error message
+ * </Alert>
+ * ```
+ *
+ * @example Auto-dismiss with Pause on Hover
+ * ```tsx
+ * <Alert
+ *   open={true}
+ *   severity="success"
+ *   autoHideDuration={5000}
+ *   pauseOnHover={true}
+ * >
+ *   This will auto-dismiss in 5 seconds, but pauses when hovered
+ * </Alert>
+ * ```
+ *
  * @see {@link AlertProps} for available configuration options
  */
 
+// ============================================================================
+// CUSTOM HOOK (Behavior Management)
+// ============================================================================
+
+/**
+ * Custom hook that manages all Alert component behavior in one cohesive unit.
+ * Consolidates visibility, auto-dismiss, keyboard, and focus management.
+ *
+ * @param open - Whether the alert should be open
+ * @param onDismiss - Callback when alert is dismissed
+ * @param dismissible - Whether the alert can be dismissed
+ * @param autoHideDuration - Duration before auto-dismiss (ms)
+ * @param pauseOnHover - Whether to pause auto-dismiss on hover/focus
+ * @param autoFocus - Whether to auto-focus the alert
+ * @param alertRef - Ref to the alert DOM element
+ * @returns Object with visibility state, handlers, and event callbacks
+ */
+const useAlertBehavior = ({
+  open,
+  onDismiss,
+  dismissible,
+  autoHideDuration,
+  pauseOnHover,
+  autoFocus,
+  alertRef,
+}: {
+  open: boolean;
+  onDismiss?: () => void;
+  dismissible: boolean;
+  autoHideDuration?: number;
+  pauseOnHover: boolean;
+  autoFocus: boolean;
+  alertRef: React.RefObject<HTMLDivElement>;
+}) => {
+  const [isVisible, setIsVisible] = React.useState(open);
+  const [shouldRender, setShouldRender] = React.useState(open);
+  const [isPaused, setIsPaused] = React.useState(false);
+
+  // Dismiss handler with animation timing
+  const handleDismiss = React.useCallback((): void => {
+    setIsVisible(false);
+    // Wait for animation to complete before unmounting
+    setTimeout(() => {
+      setShouldRender(false);
+      onDismiss?.();
+    }, 300); // Match CSS transition duration
+  }, [onDismiss]);
+
+  // Visibility management - sync with open prop
+  React.useEffect(() => {
+    if (open) {
+      setShouldRender(true);
+      setIsVisible(true);
+    } else {
+      setIsVisible(false);
+    }
+  }, [open]);
+
+  // Auto-dismiss timer with pause support
+  React.useEffect(() => {
+    if (!autoHideDuration || !isVisible || isPaused) return;
+
+    const timer = setTimeout(() => {
+      handleDismiss();
+    }, autoHideDuration);
+
+    return () => clearTimeout(timer);
+  }, [autoHideDuration, isVisible, isPaused, handleDismiss]);
+
+  // ESC key support for dismissible alerts
+  React.useEffect(() => {
+    if (!dismissible || !isVisible) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        handleDismiss();
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [dismissible, isVisible, handleDismiss]);
+
+  // Auto-focus for critical alerts
+  React.useEffect(() => {
+    if (autoFocus && isVisible && alertRef.current) {
+      alertRef.current.focus();
+    }
+  }, [autoFocus, isVisible, alertRef]);
+
+  // Pause/resume handlers (memoized for stable references)
+  const pause = React.useCallback(() => {
+    if (pauseOnHover && autoHideDuration) {
+      setIsPaused(true);
+    }
+  }, [pauseOnHover, autoHideDuration]);
+
+  const resume = React.useCallback(() => {
+    if (pauseOnHover && autoHideDuration) {
+      setIsPaused(false);
+    }
+  }, [pauseOnHover, autoHideDuration]);
+
+  return {
+    isVisible,
+    shouldRender,
+    handleDismiss,
+    handleInteractionStart: pause,
+    handleInteractionEnd: resume,
+  };
+};
+
+// ============================================================================
+// MAIN COMPONENT
+// ============================================================================
+
 const Alert: React.FC<AlertProps> = ({
   open,
   severity = "default",
@@ -92,70 +363,64 @@ const Alert: React.FC<AlertProps> = ({
   iconSize,
   iconProps,
   hideIcon,
+  autoHideDuration,
+  pauseOnHover = true,
+  titleLevel = 3,
+  actions,
+  autoFocus = false,
+  variant = "outlined",
+  contentType = "text",
   ...props
 }) => {
-  const [isVisible, setIsVisible] = React.useState(open);
-
-  React.useEffect(() => {
-    setIsVisible(open);
-  }, [open]);
-
-  if (!isVisible) return null;
+  const alertRef = React.useRef<HTMLDivElement>(null);
 
-  const handleDismiss = (): void => {
-    setIsVisible(false);
-    onDismiss?.();
-  };
+  // Use consolidated behavior hook
+  const {
+    isVisible,
+    shouldRender,
+    handleDismiss,
+    handleInteractionStart,
+    handleInteractionEnd,
+  } = useAlertBehavior({
+    open,
+    onDismiss,
+    dismissible,
+    autoHideDuration,
+    pauseOnHover,
+    autoFocus,
+    alertRef,
+  });
 
-  /**
-   * Default props for the Icon component used in the Alert component.
-   * These props set the fill color to white and the size to 32 pixels.
-   */
-  const defaultIconProps: IconProps = {
-    size: iconSize || 32,
-  };
+  // Early return if component shouldn't render
+  if (!shouldRender) return null;
 
-  // Update the severityType object with the type
-  const severityType: Record<Severity, "polite" | "assertive"> = {
-    default: "polite",
-    info: "polite",
-    success: "polite",
-    warning: "polite",
-    error: "assertive",
-  } as const;
-
-  const mergedIconProps = { ...defaultIconProps, ...iconProps };
-
-  // Update the severityIcons object with the type
-  const severityIcons: Record<Severity, JSX.Element> = {
-    info: <Icon.InfoSolid {...mergedIconProps} />,
-    success: <Icon.SuccessSolid {...mergedIconProps} />,
-    warning: <Icon.WarnSolid {...mergedIconProps} />,
-    error: <Icon.AlertSolid {...mergedIconProps} />,
-    default: <Icon.AlertSquareSolid {...mergedIconProps} />,
+  // Merge icon props with defaults
+  const mergedIconProps: IconProps = {
+    size: iconSize || 16,
+    ...iconProps,
   };
 
   return (
-    <UI
-      as="div"
-      role="alert"
-      aria-live={severityType[severity]}
-      aria-atomic="true"
-      className={`alert alert-${severity}`}
-      data-alert={severity}
+    <AlertView
+      ref={alertRef}
+      severity={severity}
+      variant={variant}
+      isVisible={isVisible}
+      dismissible={dismissible}
+      onDismiss={handleDismiss}
+      onInteractionStart={handleInteractionStart}
+      onInteractionEnd={handleInteractionEnd}
+      autoFocus={autoFocus}
+      title={title}
+      titleLevel={titleLevel}
+      contentType={contentType}
+      actions={actions}
+      hideIcon={hideIcon}
+      iconProps={mergedIconProps}
       {...props}
     >
-      {!hideIcon && <UI aria-hidden="true">{severityIcons[severity]}</UI>}
-      <UI as="div" className="alert-message">
-        {title && (
-          <UI as="h3" className="alert-title">
-            {title}
-          </UI>
-        )}
-        <UI as="div">{children}</UI>
-      </UI>
-      {dismissible && <DismissButton onDismiss={handleDismiss} />}
-    </UI>
+      {children}
+    </AlertView>
   );
 };
 export default Alert;

package/src/components/alert/views/alert-actions.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+import UI from "#components/ui";
+
+/**
+ * Renders optional action buttons within the alert.
+ *
+ * @param actions - Action button elements to display
+ * @returns Actions container, or null if no actions provided
+ */
+export const AlertActions: React.FC<{ actions?: React.ReactNode }> = ({ actions }) => {
+  if (!actions) return null;
+  return <UI as="div" className="alert-actions">{actions}</UI>;
+};

package/src/components/alert/views/alert-content.tsx

@@ -0,0 +1,17 @@
+import React from "react";
+import UI from "#components/ui";
+
+/**
+ * Renders the alert message content.
+ * Supports both simple text (wrapped in <p>) and complex node structures.
+ *
+ * @param children - The content to render
+ * @param contentType - How to wrap the content ("text" or "node")
+ * @returns Wrapped content
+ */
+export const AlertContent: React.FC<{
+  children: React.ReactNode;
+  contentType: "text" | "node";
+}> = ({ children, contentType }) => {
+  return contentType === "node" ? <>{children}</> : <UI as="p">{children}</UI>;
+};

package/src/components/alert/views/alert-icon.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import UI from "#components/ui";
+import Icon from "#components/icons/icon";
+import { IconProps } from "#components/icons/types";
+
+/**
+ * Valid severity levels for alerts.
+ */
+type Severity = "default" | "info" | "success" | "warning" | "error";
+
+/**
+ * Pure function to get the appropriate icon for a severity level.
+ *
+ * @param severity - The alert severity level
+ * @param iconProps - Props to pass to the Icon component
+ * @returns The icon element for the severity
+ */
+const getSeverityIcon = (
+  severity: Severity,
+  iconProps: IconProps
+): JSX.Element => {
+  const severityIcons: Record<Severity, JSX.Element> = {
+    info: <Icon.InfoSolid {...iconProps} />,
+    success: <Icon.SuccessSolid {...iconProps} />,
+    warning: <Icon.WarnSolid {...iconProps} />,
+    error: <Icon.AlertSolid {...iconProps} />,
+    default: <Icon.AlertSquareSolid {...iconProps} />,
+  };
+  return severityIcons[severity];
+};
+
+/**
+ * Renders the severity icon with proper ARIA attributes.
+ * Icon is hidden from screen readers as the text provides context.
+ *
+ * @param severity - The alert severity level
+ * @param iconProps - Props to pass to the Icon component
+ * @param hideIcon - Whether to hide the icon
+ * @returns Icon element, or null if hidden
+ */
+export const AlertIcon: React.FC<{
+  severity: Severity;
+  iconProps: IconProps;
+  hideIcon?: boolean;
+}> = ({ severity, iconProps, hideIcon }) => {
+  if (hideIcon) return null;
+  const icon = getSeverityIcon(severity, iconProps);
+  return (
+    <UI aria-hidden="true" className="alert-icon">
+      {icon}
+    </UI>
+  );
+};

package/src/components/alert/views/alert-screen-reader-text.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+
+/**
+ * Valid severity levels for alerts.
+ */
+type Severity = "default" | "info" | "success" | "warning" | "error";
+
+/**
+ * Screen reader announcement text for each severity level.
+ */
+const SEVERITY_SCREEN_READER_TEXT: Record<Severity, string> = {
+  default: "",
+  info: "Information: ",
+  success: "Success: ",
+  warning: "Warning: ",
+  error: "Error: ",
+} as const;
+
+/**
+ * Renders visually hidden severity text for screen readers.
+ * Provides context about the alert type without visual clutter.
+ *
+ * @param severity - The alert severity level
+ * @returns Hidden text for screen readers, or null if no text needed
+ */
+export const AlertScreenReaderText: React.FC<{ severity: Severity }> = ({ severity }) => {
+  const text = SEVERITY_SCREEN_READER_TEXT[severity];
+  if (!text) return null;
+  return <span className="sr-only">{text}</span>;
+};

package/src/components/alert/views/alert-title.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import UI from "#components/ui";
+
+/**
+ * Renders the alert title with configurable heading level.
+ * Uses semantic heading (h2-h6) or strong element based on titleLevel prop.
+ *
+ * @param title - The title text to display
+ * @param titleLevel - Semantic heading level (2-6)
+ * @returns Title element, or null if no title provided
+ */
+export const AlertTitle: React.FC<{
+  title?: string;
+  titleLevel: 2 | 3 | 4 | 5 | 6;
+}> = ({ title, titleLevel }) => {
+  if (!title) return null;
+  const TitleElement = titleLevel ? (`h${titleLevel}` as const) : "strong";
+  return (
+    <UI as={TitleElement} className="alert-title">
+      {title}
+    </UI>
+  );
+};