fix(react): update composition pattern

packages/react/src/components/Accordion/Accordion.tsx

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023, WSO2 LLC. (https://www.wso2.com).
+ * Copyright (c) 2023, WSO2 LLC. (https://www.wso2.com). All Rights Reserved.
  *
  * WSO2 LLC. licenses this file to you under the Apache License,
  * Version 2.0 (the "License"); you may not use this file except
@@ -18,20 +18,54 @@
 
 import MuiAccordion, {AccordionProps as MuiAccordionProps} from '@mui/material/Accordion';
 import clsx from 'clsx';
-import {FC, ReactElement} from 'react';
+import {forwardRef} from 'react';
+import type {ElementType, ForwardRefExoticComponent, MutableRefObject, ReactElement} from 'react';
 import type {WithWrapperProps} from '../../models/component';
 import composeComponentDisplayName from '../../utils/compose-component-display-name';
 import './accordion.scss';
 
-export type AccordionProps = MuiAccordionProps;
+export type AccordionProps<C extends ElementType = ElementType> = {
+  /**
+   * The component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C;
+} & Omit<MuiAccordionProps, 'component'>;
 
 const COMPONENT_NAME: string = 'Accordion';
 
-const Accordion: FC<AccordionProps> & WithWrapperProps = ({className, ...rest}: AccordionProps): ReactElement => {
-  const classes: string = clsx('oxygen-accordion', className);
+/**
+ * The Accordion component lets users show and hide sections of related content on a page.
+ *
+ * Demos:
+ *
+ * - [Accordion (Oxygen UI)] (https://wso2.github.io/oxygen-ui/react/?path=/docs/surfaces-accordion)
+ * - [Accordion (MUI)](https://mui.com/material-ui/react-accordion/)
+ *
+ * API:
+ *
+ * - [Accordion API](https://mui.com/material-ui/api/accordion/)
+ * - inherits [Paper API](https://mui.com/material-ui/api/paper/)
+ *
+ * @remarks
+ * - ✔️ Props of the [Paper](https://mui.com/material-ui/api/paper/) component are also available.
+ * - ✅ `component` prop is supported.
+ * - ✅ The `ref` is forwarded to the root element.
+ *
+ * @template C - The type of the component.
+ * @param props - The props for the Accordion component.
+ * @param ref - The ref to be forwarded to the MuiAccordion component.
+ * @returns The rendered Accordion component.
+ */
+const Accordion: ForwardRefExoticComponent<AccordionProps> & WithWrapperProps = forwardRef(
+  <C extends ElementType = ElementType>(
+    {className, ...rest}: AccordionProps<C>,
+    ref: MutableRefObject<HTMLDivElement>,
+  ): ReactElement => {
+    const classes: string = clsx('oxygen-accordion', className);
 
-  return <MuiAccordion className={classes} {...rest} />;
-};
+    return <MuiAccordion ref={ref} className={classes} {...rest} />;
+  },
+) as ForwardRefExoticComponent<AccordionProps> & WithWrapperProps;
 
 Accordion.displayName = composeComponentDisplayName(COMPONENT_NAME);
 Accordion.muiName = COMPONENT_NAME;

packages/react/src/components/Accordion/index.ts

@@ -17,4 +17,4 @@
  */
 
 export {default} from './Accordion';
-export type {AccordionProps} from './Accordion';
+export * from './Accordion';

packages/react/src/components/AccordionDetails/AccordionDetails.tsx

@@ -16,21 +16,44 @@
  * under the License.
  */
 
-import MuiAccordionDetails, {AccordionDetailsProps as MuiAccordionDetailsProps} from '@mui/material/AccordionDetails';
+import MuiAccordionDetails from '@mui/material/AccordionDetails';
+import type {AccordionDetailsProps as MuiAccordionDetailsProps} from '@mui/material/AccordionDetails';
 import clsx from 'clsx';
-import {forwardRef, ForwardRefExoticComponent, ReactElement, MutableRefObject} from 'react';
+import {forwardRef} from 'react';
+import type {ForwardRefExoticComponent, ReactElement, MutableRefObject} from 'react';
 import type {WithWrapperProps} from '../../models/component';
 import composeComponentDisplayName from '../../utils/compose-component-display-name';
 
 export type AccordionDetailsProps = MuiAccordionDetailsProps;
 
 const COMPONENT_NAME: string = 'AccordionDetails';
 
+/**
+ * The Accordion Details component is the wrapper for the Accordion content.
+ *
+ * Demos:
+ *
+ * - [Accordion (Oxygen UI)] (https://wso2.github.io/oxygen-ui/react/?path=/docs/surfaces-accordion)
+ * - [Accordion (MUI)](https://mui.com/material-ui/react-accordion/)
+ *
+ * API:
+ *
+ * - [AccordionDetails API](https://mui.com/material-ui/api/accordion-details/)
+ *
+ * @remarks
+ * - ✔️ Props of the native component are also available.
+ * - ❌ `component` prop is not supported.
+ * - ✅ The `ref` is forwarded to the root element.
+ *
+ * @param props - The props for the AccordionDetails component.
+ * @param ref - The ref to be forwarded to the MuiAccordionDetails component.
+ * @returns The rendered AccordionDetails component.
+ */
 const AccordionDetails: ForwardRefExoticComponent<AccordionDetailsProps> & WithWrapperProps = forwardRef(
   ({className, ...rest}: AccordionDetailsProps, ref: MutableRefObject<HTMLDivElement>): ReactElement => {
     const classes: string = clsx('oxygen-accordion-details', className);
 
-    return <MuiAccordionDetails className={classes} {...rest} ref={ref} />;
+    return <MuiAccordionDetails ref={ref} className={classes} {...rest} />;
   },
 ) as ForwardRefExoticComponent<AccordionDetailsProps> & WithWrapperProps;
 

packages/react/src/components/AccordionDetails/index.ts

@@ -17,4 +17,4 @@
  */
 
 export {default} from './AccordionDetails';
-export type {AccordionDetailsProps} from './AccordionDetails';
+export * from './AccordionDetails';

packages/react/src/components/AccordionSummary/AccordionSummary.tsx

@@ -16,21 +16,61 @@
  * under the License.
  */
 
-import MuiAccordionSummary, {AccordionSummaryProps as MuiAccordionSummaryProps} from '@mui/material/AccordionSummary';
+import MuiAccordionSummary from '@mui/material/AccordionSummary';
+import type {
+  AccordionSummaryProps as MuiAccordionSummaryProps,
+  AccordionSummaryTypeMap,
+} from '@mui/material/AccordionSummary';
 import clsx from 'clsx';
-import {forwardRef, ForwardRefExoticComponent, ReactElement, MutableRefObject} from 'react';
+import {forwardRef} from 'react';
+import type {ForwardRefExoticComponent, ReactElement, MutableRefObject, ElementType} from 'react';
 import type {WithWrapperProps} from '../../models/component';
 import composeComponentDisplayName from '../../utils/compose-component-display-name';
 
-export type AccordionSummaryProps = MuiAccordionSummaryProps;
+export type AccordionSummaryProps<
+  C extends ElementType = ElementType,
+  D extends ElementType = AccordionSummaryTypeMap['defaultComponent'],
+  P = {},
+> = {
+  /**
+   * The component used for the root node. Either a string to use a HTML element or a component.
+   */
+  component?: C;
+} & Omit<MuiAccordionSummaryProps<D, P>, 'component'>;
 
 const COMPONENT_NAME: string = 'AccordionSummary';
 
+/**
+ * The Accordion Summary component is the wrapper for the Accordion header, which expands or collapses the content when clicked.
+ *
+ * Demos:
+ *
+ * - [Accordion (Oxygen UI)] (https://wso2.github.io/oxygen-ui/react/?path=/docs/surfaces-accordion)
+ * - [Accordion (MUI)](https://mui.com/material-ui/react-accordion/)
+ *
+ * API:
+ *
+ * - [AccordionSummary API](https://mui.com/material-ui/api/accordion-summary/)
+ * - inherits [ButtonBase API](https://mui.com/material-ui/api/button-base/)
+ *
+ * @remarks
+ * - ✔️ Props of the [ButtonBase](https://mui.com/material-ui/api/button-base/) component are also available.
+ * - ✅ `component` prop is supported.
+ * - ✅ The `ref` is forwarded to the root element.
+ *
+ * @template C - The type of the component.
+ * @param props - The props for the AccordionSummary component.
+ * @param ref - The ref to be forwarded to the MuiAccordionSummary component.
+ * @returns The rendered AccordionSummary component.
+ */
 const AccordionSummary: ForwardRefExoticComponent<AccordionSummaryProps> & WithWrapperProps = forwardRef(
-  ({className, ...rest}: AccordionSummaryProps, ref: MutableRefObject<HTMLDivElement>): ReactElement => {
+  <C extends ElementType = ElementType>(
+    {className, ...rest}: AccordionSummaryProps<C>,
+    ref: MutableRefObject<HTMLDivElement>,
+  ): ReactElement => {
     const classes: string = clsx('oxygen-accordion-summary', className);
 
-    return <MuiAccordionSummary className={classes} {...rest} ref={ref} />;
+    return <MuiAccordionSummary ref={ref} className={classes} {...rest} />;
   },
 ) as ForwardRefExoticComponent<AccordionSummaryProps> & WithWrapperProps;
 

packages/react/src/components/AccordionSummary/index.ts

@@ -17,4 +17,6 @@
  */
 
 export {default} from './AccordionSummary';
-export type {AccordionSummaryProps} from './AccordionSummary';
+export * from './AccordionSummary';
+
+export type {AccordionSummaryTypeMap} from '@mui/material/AccordionSummary';

packages/react/src/components/AccountOverview/AccountOverview.tsx

@@ -17,19 +17,27 @@
  */
 
 import clsx from 'clsx';
-import {FC, ReactElement, ReactNode} from 'react';
+import {forwardRef} from 'react';
+import type {ElementType, ForwardRefExoticComponent, MutableRefObject, ReactElement, ReactNode} from 'react';
 import type {WithWrapperProps} from '../../models/component';
 import composeComponentDisplayName from '../../utils/compose-component-display-name';
 import Box from '../Box';
-import Card, {CardProps} from '../Card';
-import CardHeader, {CardHeaderProps} from '../CardHeader';
-import Carousel, {CarouselStep} from '../Carousel';
+import Card from '../Card';
+import type {CardProps, CardTypeMap} from '../Card';
+import CardHeader from '../CardHeader';
+import type {CardHeaderProps} from '../CardHeader';
+import Carousel from '../Carousel';
+import type {CarouselStep} from '../Carousel';
 import CircularProgressAvatar from '../CircularProgressAvatar';
 import Divider from '../Divider';
-import {UserTemplate} from '../UserDropdownMenu';
+import type {UserTemplate} from '../UserDropdownMenu';
 import './account-overview.scss';
 
-export interface AccountOverviewProps extends Omit<CardProps, 'title'> {
+export type AccountOverviewProps<
+  C extends ElementType = ElementType,
+  D extends ElementType = CardTypeMap['defaultComponent'],
+  P = {},
+> = Omit<CardProps<C, D, P>, 'title'> & {
   /**
    * Account completion steps.
    */
@@ -60,49 +68,77 @@ export interface AccountOverviewProps extends Omit<CardProps, 'title'> {
    * Logged user information.
    */
   user: UserTemplate;
-}
+};
 
 export type AccountCompletionSteps = CarouselStep;
 
 const COMPONENT_NAME: string = 'AccountOverview';
 
-const AccountOverview: FC<AccountOverviewProps> & WithWrapperProps = ({
-  className,
-  title,
-  subheader,
-  accountCompletionStepsTitle,
-  accountCompletionSteps,
-  accountProgress,
-  user,
-  cardHeaderProps,
-  ...rest
-}: AccountOverviewProps): ReactElement => {
-  const classes: string = clsx('oxygen-account-overview', className);
+/**
+ * The Account Overview component lets you display the progress of the user's account.
+ * It includes the user's profile picture, name, email, account progress and account completion steps.
+ *
+ * Demos:
+ *
+ * - [Account Overview (Oxygen UI)] (https://wso2.github.io/oxygen-ui/react/?path=/docs/patterns-account-overview)
+ *
+ * API:
+ *
+ * - inherits [Card API](https://mui.com/material-ui/api/card/)
+ *
+ * @remarks
+ * - ✨ This is a custom component that is not available in the Material-UI library.
+ * - ✔️ Props of the [Paper](https://mui.com/material-ui/api/card/) component are also available.
+ * - ✅ `component` prop is supported.
+ * - ✅ The `ref` is forwarded to the root element.
+ *
+ * @template C - The type of the component.
+ * @param props - The props for the AccountOverview component.
+ * @param ref - The ref to be forwarded to the Card component.
+ * @returns The rendered AccountOverview component.
+ */
+const AccountOverview: ForwardRefExoticComponent<AccountOverviewProps> & WithWrapperProps = forwardRef(
+  <C extends ElementType = ElementType>(
+    {
+      className,
+      title,
+      subheader,
+      accountCompletionStepsTitle,
+      accountCompletionSteps,
+      accountProgress,
+      user,
+      cardHeaderProps,
+      ...rest
+    }: AccountOverviewProps<C>,
+    ref: MutableRefObject<HTMLDivElement>,
+  ): ReactElement => {
+    const classes: string = clsx('oxygen-account-overview', className);
 
-  return (
-    <Card className={classes} elevation={0} variant="outlined" {...rest}>
-      <CardHeader
-        avatar={
-          <CircularProgressAvatar
-            color={accountProgress < 100 ? 'warning' : 'success'}
-            progress={accountProgress}
-            avatarOptions={{alt: "User's avatar", src: user?.image}}
-            badgeOptions={{badgeContent: `${accountProgress}%`, color: accountProgress < 100 ? 'warning' : 'success'}}
-          />
-        }
-        title={title}
-        subheader={subheader}
-        {...cardHeaderProps}
-      />
-      {accountCompletionSteps && (
-        <Box className="oxygen-account-completion-steps-box">
-          <Divider />
-          <Carousel title={accountCompletionStepsTitle} steps={accountCompletionSteps} />
-        </Box>
-      )}
-    </Card>
-  );
-};
+    return (
+      <Card ref={ref} className={classes} elevation={0} variant="outlined" {...rest}>
+        <CardHeader
+          avatar={
+            <CircularProgressAvatar
+              color={accountProgress < 100 ? 'warning' : 'success'}
+              progress={accountProgress}
+              avatarOptions={{alt: "User's avatar", src: user?.image}}
+              badgeOptions={{badgeContent: `${accountProgress}%`, color: accountProgress < 100 ? 'warning' : 'success'}}
+            />
+          }
+          title={title}
+          subheader={subheader}
+          {...cardHeaderProps}
+        />
+        {accountCompletionSteps && (
+          <Box className="oxygen-account-completion-steps-box">
+            <Divider />
+            <Carousel title={accountCompletionStepsTitle} steps={accountCompletionSteps} />
+          </Box>
+        )}
+      </Card>
+    );
+  },
+) as ForwardRefExoticComponent<AccountOverviewProps> & WithWrapperProps;
 
 AccountOverview.displayName = composeComponentDisplayName(COMPONENT_NAME);
 AccountOverview.muiName = COMPONENT_NAME;

packages/react/src/components/AccountOverview/index.ts

@@ -17,4 +17,4 @@
  */
 
 export {default} from './AccountOverview';
-export type {AccountOverviewProps} from './AccountOverview';
+export * from './AccountOverview';