Merge pull request moodle#122 from andrewnicols/fixComponentFileSum

[repo] Address some syntax issues with the ComponentFileSummary
gbarat87 · May 11, 2022 · b3fe504 · b3fe504
2 parents 97d2966 + 88c2120
commit b3fe504
Show file tree

Hide file tree

Showing 4 changed files with 133 additions and 69 deletions.
diff --git a/docs/_utils.tsx b/docs/_utils.tsx
@@ -14,11 +14,13 @@
  * You should have received a copy of the GNU General Public License
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
-import React from 'react';
-import { ComponentFileSummary as ComponentFileSummaryGeneric } from '@site/src/components';
-import { getExample } from '@site/src/moodleBridge';
+import React, { type ReactNode } from 'react';
+import ComponentFileSummaryGeneric, {
+    type ComponentFileSummaryProps,
+} from '@site/src/components/ComponentFileSummary';
+import { MDXProvider } from '@mdx-js/react';
 
-import type { Props } from '@site/src/moodleBridge';
+import { getExample } from '@site/src/moodleBridge';
 
 export {
     getExample,
@@ -29,12 +31,32 @@ export {
  * @param {Props} props
  * @return {Props}
  */
-export const fillDefaultProps = (props: Props): Props => ({
-    fileType: 'php',
+export const fillDefaultProps = (props: ComponentFileSummaryProps): ComponentFileSummaryProps => ({
+    filetype: 'php',
     examplePurpose: props.summary,
     ...props,
 });
 
+const normaliseDescription = (Value: ReactNode | string): null | JSX.Element => {
+    if (typeof Value === 'boolean' || !Value) {
+        return null;
+    }
+
+    if (typeof Value === 'string' || React.isValidElement(Value)) {
+        return (
+            <MDXProvider>
+                {Value}
+            </MDXProvider>
+        );
+    }
+
+    return (
+        <MDXProvider>
+            <Value />
+        </MDXProvider>
+    );
+};
+
 /**
  * Get the preferred description given a standard properties value which contains an optional description,
  * and/or extraDescription, and a DefaultDescription object.
@@ -46,24 +68,42 @@ export const fillDefaultProps = (props: Props): Props => ({
 export const getDescription = ({
     description = null,
     extraDescription = null,
-}: Props, DefaultDescription?: string | boolean): ReactFragment => {
+    children = null,
+}: ComponentFileSummaryProps, defaultDescription?: ReactNode | string): null | ReactNode | JSX.Element => {
+    if (children) {
+        const Description = normaliseDescription(children);
+        return (
+            <MDXProvider>
+                {Description}
+            </MDXProvider>
+        );
+    }
+
     if (description) {
-        return description;
+        const Description = normaliseDescription(description);
+        return (
+            <MDXProvider>
+                {Description}
+            </MDXProvider>
+        );
     }
 
-    if (description === false) {
-        return null;
+    const Description = normaliseDescription(defaultDescription);
+    const ExtraDescription = normaliseDescription(extraDescription);
+
+    if (Description) {
+        return (
+            <MDXProvider>
+                {Description}
+                {ExtraDescription}
+            </MDXProvider>
+        );
     }
 
-    return (
-        <>
-            <DefaultDescription />
-            {extraDescription}
-        </>
-    );
+    return null;
 };
 
-export const ComponentFileSummary = (initialProps: Props): ReactFragment => {
+export const ComponentFileSummary = (initialProps: ComponentFileSummaryProps): JSX.Element => {
     const props = fillDefaultProps({
         examplePurpose: initialProps?.summary ?? null,
         ...initialProps,

diff --git a/docs/apis/_files/version-php.tsx b/docs/apis/_files/version-php.tsx
@@ -14,9 +14,9 @@
  * You should have received a copy of the GNU General Public License
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
+import { type ComponentFileSummaryProps } from '@site/src/components/ComponentFileSummary';
 import React from 'react';
 import { ComponentFileSummary } from '../../_utils';
-import type { Props } from '../../_utils';
 import DefaultDescription from './version-php.mdx';
 
 const defaultExample = `defined('MOODLE_INTERNAL') || die();
@@ -35,15 +35,17 @@ $plugin->dependencies = [
 ];
 `;
 
-export default (initialProps: Props): ComponentFileSummary => (
-    <ComponentFileSummary
-        required
-        filepath="/version.php"
-        filetype="php"
-        summary="Version metadata"
-        examplePurpose="Version metadata"
-        defaultDescription={DefaultDescription}
-        defaultExample={defaultExample}
-        {...initialProps}
-    />
-);
+export default function VersionPHP(props: ComponentFileSummaryProps): JSX.Element {
+    return (
+        <ComponentFileSummary
+            required
+            filepath="/version.php"
+            filetype="php"
+            summary="Version metadata"
+            examplePurpose="Version metadata"
+            defaultDescription={DefaultDescription}
+            defaultExample={defaultExample}
+            {...props}
+        />
+    );
+}
diff --git a/src/components/ComponentFileSummary.js → src/components/ComponentFileSummary.tsx b/src/components/ComponentFileSummary.js → src/components/ComponentFileSummary.tsx
@@ -15,34 +15,32 @@
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-import * as React from 'react';
+/* eslint-disable react/no-unused-prop-types */
+import React, { type ReactNode } from 'react';
 import Chip from '@mui/material/Chip';
 import Tooltip from '@mui/material/Tooltip';
 import Grid from '@mui/material/Grid';
 import Details from '@theme/Details';
+import { MDXProvider } from '@mdx-js/react';
 
-const getBadge = (title, description, colour = 'info') => {
-    const chip = (
-        <Grid item key={title}>
-            <Tooltip title={description}>
-                <Chip
-                    label={title}
-                    color={colour}
-                />
-            </Tooltip>
-        </Grid>
-    );
-
-    return chip;
-};
+const getBadge = (title, description, colour = 'info'): JSX.Element => (
+    <Grid item key={title}>
+        <Tooltip title={description}>
+            <Chip
+                label={title}
+                color={colour}
+            />
+        </Tooltip>
+    </Grid>
+);
 
 function getBadges({
     required = false,
     legacy = false,
     deprecated = false,
     refreshedDuringUpgrade = false,
     refreshedDuringPurge = false,
-}) {
+}): Array<typeof Grid> {
     const badges = [];
     if (refreshedDuringUpgrade) {
         // This file is re-read during an upgrade and configuration will be re-applied.
@@ -111,7 +109,28 @@ function getExamples(props) {
     return null;
 }
 
-export default function ComponentFileSummary(props) {
+export interface ComponentFileSummaryProps {
+    description?: string | ReactNode,
+    defaultDescription?: string | ReactNode,
+    defaultExample?: string | ReactNode,
+    example?: string | ReactNode | JSX.Element,
+    exampleFilepath?: string,
+    examplePurpose?: string,
+    extraDescription?: string,
+    filepath?: string,
+    filetype?: string,
+    modulename?: string,
+    pluginname?: string,
+    plugintype?: string,
+    showFileHeader?: boolean,
+    showLicense?: boolean,
+    summary?: string,
+    children?: React.ReactNode,
+    required?: boolean,
+    legacy?: boolean,
+}
+
+export default function ComponentFileSummary(props: ComponentFileSummaryProps): JSX.Element {
     const {
         filepath,
         summary,
@@ -131,26 +150,28 @@ export default function ComponentFileSummary(props) {
     })();
 
     return (
-        <Grid container spacing={2}>
-            <Grid item xs={6}>
-                <h4>
-                    {summary}
-                </h4>
-            </Grid>
-            <Grid item xs={6}>
-                <Grid container spacing={2} justifyContent="flex-end">
-                    {badges}
+        <MDXProvider>
+            <Grid container spacing={2}>
+                <Grid item xs={6}>
+                    <h4>
+                        {summary}
+                    </h4>
                 </Grid>
+                <Grid item xs={6}>
+                    <Grid container spacing={2} justifyContent="flex-end">
+                        {badges}
+                    </Grid>
+                </Grid>
+                <Grid item xs={12}>
+                    <h5>
+                        File path:
+                        {' '}
+                        {filepath}
+                    </h5>
+                </Grid>
+                {description}
+                {getExamples(props)}
             </Grid>
-            <Grid item xs={12}>
-                <h5>
-                    File path:
-                    {' '}
-                    {filepath}
-                </h5>
-            </Grid>
-            {description}
-            {getExamples(props)}
-        </Grid>
+        </MDXProvider>
     );
 }
diff --git a/src/moodleBridge.tsx b/src/moodleBridge.tsx
@@ -15,7 +15,7 @@
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-import React from 'react';
+import React, { type ReactNode } from 'react';
 import CodeBlock from '@theme/CodeBlock';
 import DefaultComponentData from '@site/data/master/components.json';
 
@@ -25,7 +25,7 @@ export interface ComponentList {
 }
 
 export interface Props {
-    description?: string,
+    description?: string | ReactNode,
     example?: string,
     exampleFilepath?: string,
     examplePurpose?: string,
@@ -37,6 +37,7 @@ export interface Props {
     plugintype?: string,
     showFileHeader?: boolean,
     showLicense?: boolean,
+    summary?: string,
 }
 
 /**
@@ -264,7 +265,7 @@ const getLanguage = ({
 export const fileExampleGetter = (ComponentData: ComponentList) => (
     initialProps: Props,
     defaultExample: string,
-): typeof CodeBlock => {
+): JSX.Element => {
     const props = {
         plugintype: 'plugintype',
         showLicense: true,