docs(CAlert): allow defining custom class names and overriding existing ones

Author: mrholek

packages/coreui-react/src/components/alert/CAlert.tsx

@@ -8,42 +8,120 @@ import { CCloseButton } from '../close-button/CCloseButton'
 import { useForkedRef } from '../../hooks'
 import { colorPropType } from '../../props'
 import type { Colors } from '../../types'
+import { mergeClassNames } from '../../utils'
 
 export interface CAlertProps extends HTMLAttributes<HTMLDivElement> {
   /**
-   * A string of all className you want applied to the component.
+   * Apply a CSS fade transition to the alert.
+   *
+   * @since 5.5.0
+   *
+   * @example
+   * <CAlert animation={false} color="success">No animation alert</CAlert>
+   */
+  animation?: boolean
+
+  /**
+   * A string of additional CSS class names to apply to the alert component.
+   *
+   * @example
+   * <CAlert className="my-custom-class" color="danger">Custom Class Alert</CAlert>
    */
   className?: string
+
   /**
    * Sets the color context of the component to one of CoreUI’s themed colors.
    *
    * @type 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'dark' | 'light' | string
+   *
+   * @example
+   * <CAlert color="warning">Warning Alert</CAlert>
    */
   color: Colors
+
   /**
-   * Optionally add a close button to alert and allow it to self dismiss.
+   * Custom class names to override or extend the default CSS classes used within the `CAlert` component.
+   * Each key corresponds to a specific part of the Alert component, allowing for granular styling control.
+   *
+   * @since v5.5.0
+   *
+   * @example
+   * const customClasses = {
+   *   ALERT: 'my-custom-alert',
+   *   ALERT_DISMISSIBLE: 'my-custom-dismissible',
+   * }
+   *
+   * <CAlert customClassNames={customClasses} />
+   */
+  customClassNames?: Partial<typeof ALERT_CLASS_NAMES>
+
+  /**
+   * Optionally add a close button to the alert and allow it to self-dismiss.
+   *
+   * @example
+   * <CAlert dismissible color="success">
+   *   Dismissible Alert
+   * </CAlert>
    */
   dismissible?: boolean
+
   /**
-   * Callback fired when the component requests to be closed.
+   * Callback fired when the alert requests to be closed. This occurs when the close button is clicked.
+   *
+   * @example
+   * const handleClose = () => {
+   *   console.log('Alert closed')
+   * }
+   *
+   * <CAlert dismissible color="danger" onClose={handleClose}>
+   *   Dismissible Alert with Callback
+   * </CAlert>
    */
   onClose?: () => void
+
   /**
-   * Set the alert variant to a solid.
+   * Set the alert variant to a solid background. This changes the alert's appearance to have a solid color.
+   *
+   * @example
+   * <CAlert variant="solid" color="primary">
+   *   Solid Variant Alert
+   * </CAlert>
    */
   variant?: 'solid' | string
+
   /**
-   * Toggle the visibility of component.
+   * Toggle the visibility of the alert component. When set to `false`, the alert will be hidden.
+   *
+   * @example
+   * const [visible, setVisible] = useState(true)
+   *
+   * <CAlert visible={visible} onClose={() => setVisible(false)} color="info">
+   *   Toggleable Alert
+   * </CAlert>
    */
   visible?: boolean
 }
 
+export const ALERT_CLASS_NAMES = {
+  /**
+   * Base class for the alert container.
+   */
+  ALERT: 'alert',
+
+  /**
+   * Applied when the `dismissible` prop is enabled.
+   */
+  ALERT_DISMISSIBLE: 'alert-dismissible',
+}
+
 export const CAlert = forwardRef<HTMLDivElement, CAlertProps>(
   (
     {
       children,
+      animation = true,
       className,
       color = 'primary',
+      customClassNames,
       dismissible,
       variant,
       visible = true,
@@ -60,6 +138,11 @@ export const CAlert = forwardRef<HTMLDivElement, CAlertProps>(
       setVisible(visible)
     }, [visible])
 
+    const mergedClassNames = mergeClassNames<typeof ALERT_CLASS_NAMES>(
+      ALERT_CLASS_NAMES,
+      customClassNames,
+    )
+
     return (
       <Transition
         in={_visible}
@@ -72,10 +155,11 @@ export const CAlert = forwardRef<HTMLDivElement, CAlertProps>(
         {(state) => (
           <div
             className={classNames(
-              'alert',
+              mergedClassNames.ALERT,
               variant === 'solid' ? `bg-${color} text-white` : `alert-${color}`,
               {
-                'alert-dismissible fade': dismissible,
+                [mergedClassNames.ALERT_DISMISSIBLE]: dismissible,
+                fade: animation,
                 show: state === 'entered',
               },
               className,
@@ -94,9 +178,11 @@ export const CAlert = forwardRef<HTMLDivElement, CAlertProps>(
 )
 
 CAlert.propTypes = {
+  animation: PropTypes.bool,
   children: PropTypes.node,
   className: PropTypes.string,
   color: colorPropType.isRequired,
+  customClassNames: PropTypes.object,
   dismissible: PropTypes.bool,
   onClose: PropTypes.func,
   variant: PropTypes.string,

packages/coreui-react/src/components/alert/CAlertHeading.tsx

@@ -3,23 +3,74 @@ import PropTypes from 'prop-types'
 import classNames from 'classnames'
 
 import { PolymorphicRefForwardingComponent } from '../../helpers'
+import { mergeClassNames } from '../../utils'
 
 export interface CAlertHeadingProps extends HTMLAttributes<HTMLHeadingElement> {
   /**
-   * Component used for the root node. Either a string to use a HTML element or a component.
+   * The component used for the root node. It can be a string representing a HTML element or a React component.
+   *
+   * @default 'h4'
+   *
+   * @example
+   * // Using default 'h4' element
+   * <CAlertHeading>Alert Heading</CAlertHeading>
+   *
+   * // Using a custom component
+   * const CustomHeading = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>((props, ref) => (
+   *   <div ref={ref} {...props} />
+   * ))
+   *
+   * <CAlertHeading as={CustomHeading}>Custom Alert Heading</CAlertHeading>
    */
   as?: ElementType
+
   /**
-   * A string of all className you want applied to the base component.
+   * A string of additional CSS class names to apply to the React Alert Heading component.
+   *
+   * @example
+   * <CAlertHeading className="my-custom-class">Custom Class Alert Heading</CAlertHeading>
    */
   className?: string
+
+  /**
+   * Custom class names to override or extend the default CSS classes used within the `CAlertHeading` component.
+   * Each key corresponds to a specific part of the React Alert Heading component, allowing for granular styling control.
+   *
+   * @since v5.0.0
+   *
+   * @example
+   * const customClasses = {
+   *   ALERT_HEADING: 'my-custom-alert-heading',
+   * }
+   *
+   * <CAlertHeading customClassNames={customClasses}>
+   *   Custom Styled Alert Heading
+   * </CAlertHeading>
+   */
+  customClassNames?: Partial<typeof ALERT_HEADING_CLASS_NAMES>
+}
+
+export const ALERT_HEADING_CLASS_NAMES = {
+  /**
+   * Base class for the React Alert Heading container.
+   */
+  ALERT_HEADING: 'alert-heading',
 }
 
 export const CAlertHeading: PolymorphicRefForwardingComponent<'h4', CAlertHeadingProps> =
   forwardRef<HTMLHeadingElement, CAlertHeadingProps>(
-    ({ children, as: Component = 'h4', className, ...rest }, ref) => {
+    ({ children, as: Component = 'h4', className, customClassNames, ...rest }, ref) => {
+      const mergedClassNames = mergeClassNames<typeof ALERT_HEADING_CLASS_NAMES>(
+        ALERT_HEADING_CLASS_NAMES,
+        customClassNames,
+      )
+
       return (
-        <Component className={classNames('alert-heading', className)} {...rest} ref={ref}>
+        <Component
+          className={classNames(mergedClassNames.ALERT_HEADING, className)}
+          {...rest}
+          ref={ref}
+        >
           {children}
         </Component>
       )
@@ -30,6 +81,7 @@ CAlertHeading.propTypes = {
   as: PropTypes.elementType,
   children: PropTypes.node,
   className: PropTypes.string,
+  customClassNames: PropTypes.object,
 }
 
 CAlertHeading.displayName = 'CAlertHeading'

packages/coreui-react/src/components/alert/CAlertLink.tsx

@@ -3,18 +3,51 @@ import PropTypes from 'prop-types'
 import classNames from 'classnames'
 
 import { CLink } from '../link/CLink'
+import { mergeClassNames } from '../../utils'
 
 export interface CAlertLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
   /**
-   * A string of all className you want applied to the base component.
+   * A string of additional CSS class names to apply to the alert link component.
+   *
+   * @example
+   * <CAlertLink className="my-custom-link">Custom Styled Link</CAlertLink>
    */
   className?: string
+
+  /**
+   * Custom class names to override or extend the default CSS classes used within the `CAlertLink` component.
+   * Each key corresponds to a specific part of the React Alert Link component, allowing for granular styling control.
+   *
+   * @since v5.0.0
+   *
+   * @example
+   * const customClasses = {
+   *   ALERT_LINK: 'my-custom-alert-link',
+   * }
+   *
+   * <CAlertLink customClassNames={customClasses} href="#">
+   *   Custom Class Alert Link
+   * </CAlertLink>
+   */
+  customClassNames?: Partial<typeof ALERT_LINK_CLASS_NAMES>
+}
+
+export const ALERT_LINK_CLASS_NAMES = {
+  /**
+   * Base class for the React alert link.
+   */
+  ALERT_LINK: 'alert-link',
 }
 
 export const CAlertLink = forwardRef<HTMLAnchorElement, CAlertLinkProps>(
-  ({ children, className, ...rest }, ref) => {
+  ({ children, className, customClassNames, ...rest }, ref) => {
+    const mergedClassNames = mergeClassNames<typeof ALERT_LINK_CLASS_NAMES>(
+      ALERT_LINK_CLASS_NAMES,
+      customClassNames,
+    )
+
     return (
-      <CLink className={classNames('alert-link', className)} {...rest} ref={ref}>
+      <CLink className={classNames(mergedClassNames.ALERT_LINK, className)} {...rest} ref={ref}>
         {children}
       </CLink>
     )
@@ -24,6 +57,7 @@ export const CAlertLink = forwardRef<HTMLAnchorElement, CAlertLinkProps>(
 CAlertLink.propTypes = {
   children: PropTypes.node,
   className: PropTypes.string,
+  customClassNames: PropTypes.object,
 }
 
 CAlertLink.displayName = 'CAlertLink'