merge template changes

Author: Jacob Logan

mdx-components.tsx

@@ -22,6 +22,7 @@ import { InternalLinkButton } from './src/components/InternalLinkButton';
 import { Grid, View } from '@aws-amplify/ui-react';
 import { Columns } from './src/components/Columns';
 import { Video } from './src/components/Video';
+import { ReferencePage } from './src/components/ApiDocs';
 
 const ResponsiveImage = (props) => (
   <ExportedImage style={{ height: 'auto' }} {...props} />
@@ -71,6 +72,7 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
     Columns,
     Video,
     View,
+    ReferencePage,
     ...components
   };
 }

src/components/ApiDocs/ApiComment.tsx

@@ -0,0 +1,36 @@
+import { Fragment } from 'react';
+import { View } from '@aws-amplify/ui-react';
+import { parseMarkdownLinks } from '@/utils/parseMdxLinks';
+
+interface ApiCommentProps {
+  apiComment?: any[];
+  codeBlock?: boolean | undefined;
+}
+
+export const ApiComment = ({ apiComment, codeBlock }: ApiCommentProps) => {
+  if (!apiComment) return null;
+  const firstItem = apiComment[0];
+  if (!firstItem?.text?.replaceAll('-', '')?.trim()) {
+    apiComment.shift();
+  }
+  const commentList = apiComment.map((snippet, idx) => {
+    if (snippet.kind === 'code') {
+      return <code key={idx}>{snippet.text.replaceAll('`', '')}</code>;
+    } else {
+      const text = snippet.text;
+      if (idx === 0 && codeBlock) {
+        const words = text.split(' ');
+        return (
+          <Fragment key={`snippet-${idx}`}>
+            <code>{words[0]}</code>
+            {words.slice(1).join(' ')}
+          </Fragment>
+        );
+      } else {
+        return parseMarkdownLinks(text);
+      }
+    }
+  });
+
+  return <View>{commentList}</View>;
+};

src/components/ApiDocs/ApiModalProvider.tsx

@@ -0,0 +1,56 @@
+import { useState, createContext } from 'react';
+import { LinkDataType } from './display/TypeLink';
+import { ApiModal } from './display/ApiModal';
+
+export const TypeContext = createContext({
+  setModalData: (data) => data,
+  modalOpen: () => {},
+  addBreadCrumb: (data) => data,
+  setBC: (data) => data
+});
+
+export const ApiModalProvider = ({ children }) => {
+  const [modalData, setModalData] = useState({});
+  const [showModal, setShowModal] = useState(false);
+  const [breadCrumbs, setBreadCrumbs] = useState<LinkDataType[]>([]);
+
+  const modalOpen = () => {
+    setShowModal(true);
+  };
+  const closeModal = () => {
+    setShowModal(false);
+  };
+
+  const addBreadCrumb = (bc) => {
+    breadCrumbs.push(bc);
+    setBreadCrumbs(breadCrumbs);
+  };
+
+  const setBC = (bc) => {
+    setBreadCrumbs(bc);
+  };
+
+  const clearBC = () => {
+    setBreadCrumbs([]);
+  };
+
+  const value = {
+    setModalData,
+    modalOpen,
+    addBreadCrumb,
+    setBC
+  };
+
+  return (
+    <TypeContext.Provider value={value}>
+      <ApiModal
+        data={modalData}
+        showModal={showModal}
+        close={closeModal}
+        breadCrumbs={breadCrumbs}
+        clearBC={clearBC}
+      />
+      {children}
+    </TypeContext.Provider>
+  );
+};

src/components/ApiDocs/FunctionReference.tsx

@@ -0,0 +1,12 @@
+import { View } from '@aws-amplify/ui-react';
+import { FunctionSignature } from './FunctionSignature';
+
+export const FunctionReference = ({ func }) => {
+  return (
+    <View>
+      {func.signatures.map((sig, index) => (
+        <FunctionSignature sig={sig} key={`signature-${index}`} />
+      ))}
+    </View>
+  );
+};

src/components/ApiDocs/FunctionReturn.tsx

@@ -0,0 +1,34 @@
+import { View } from '@aws-amplify/ui-react';
+import { MDXHeading } from '../MDXComponents';
+import { Promise } from './display/Promise';
+import { ApiComment } from './ApiComment';
+import references from '@/directory/apiReferences.json';
+
+export const FunctionReturn = ({ functionReturn, sigName }) => {
+  const name = functionReturn.name;
+  let display, description;
+  if (name === 'Promise') {
+    const returnType = references[functionReturn.typeArguments[0].target];
+    display = <Promise typeObject={functionReturn} />;
+    if (returnType?.comment?.summary) {
+      description = <ApiComment apiComment={returnType.comment.summary} />;
+    }
+  } else {
+    const returnType = references[functionReturn.target];
+    display = name;
+    if (returnType?.comment?.summary) {
+      description = <ApiComment apiComment={returnType.comment.summary} />;
+    }
+  }
+  return (
+    <View>
+      <MDXHeading level={3} id={`${sigName}-Returns`}>
+        Returns
+      </MDXHeading>
+
+      {display}
+
+      {description}
+    </View>
+  );
+};

src/components/ApiDocs/FunctionSignature.tsx

@@ -0,0 +1,44 @@
+import { View } from '@aws-amplify/ui-react';
+import { MDXHeading } from '../MDXComponents';
+import { ApiComment } from './ApiComment';
+import { Parameters } from './Parameters';
+import { Throws } from './Throws';
+import { FunctionReturn } from './FunctionReturn';
+import references from '@/directory/apiReferences.json';
+
+export const FunctionSignature = ({ sig }) => {
+  const sigObject = references[sig];
+  const description = sigObject?.comment?.summary;
+  const parameters = sigObject?.parameters;
+  const throws = sigObject?.comment?.blockTags?.filter(
+    (tagObject) => tagObject['tag'] === '@throws'
+  );
+  const returns = sigObject?.type;
+  return (
+    <View>
+      <MDXHeading level={2} id={`${sigObject.name}-${sigObject.id}`}>
+        {sigObject.name}
+      </MDXHeading>
+
+      {description && <ApiComment apiComment={description} />}
+
+      {parameters && (
+        <Parameters
+          parameters={parameters}
+          sigName={`${sigObject.name}-${sigObject.id}`}
+        />
+      )}
+
+      {throws && throws.length > 0 && (
+        <Throws throws={throws} sigName={`${sigObject.name}-${sigObject.id}`} />
+      )}
+
+      {returns && (
+        <FunctionReturn
+          functionReturn={returns}
+          sigName={`${sigObject.name}-${sigObject.id}`}
+        />
+      )}
+    </View>
+  );
+};

src/components/ApiDocs/Parameters.tsx

@@ -0,0 +1,46 @@
+import { View } from '@aws-amplify/ui-react';
+import { MDXHeading, MDXTable } from '../MDXComponents';
+import { ApiComment } from './ApiComment';
+import { ParameterType } from './display';
+import references from '@/directory/apiReferences.json';
+
+export const Parameters = ({ parameters, sigName }) => {
+  const paramObjects = parameters.map((id) => references[id]);
+  return (
+    <View>
+      <MDXHeading level={3} id={`${sigName}-Parameters`}>
+        Parameters
+      </MDXHeading>
+      <MDXTable>
+        <thead>
+          <tr>
+            <th>Option</th>
+            <th>Required</th>
+            <th>Type</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {paramObjects.map((option) => {
+            return (
+              <tr key={option.id}>
+                <td>
+                  <code>{option.name}</code>
+                </td>
+                <td>{option?.flags?.isOptional ? 'false' : 'true'}</td>
+                <td>
+                  <ParameterType typeData={option.type} />
+                </td>
+                <td>
+                  {option?.comment?.summary && (
+                    <ApiComment apiComment={option.comment.summary} />
+                  )}
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </MDXTable>
+    </View>
+  );
+};

src/components/ApiDocs/ReferencePage.tsx

@@ -0,0 +1,23 @@
+import { Fragment } from 'react';
+
+import { FunctionReference } from './FunctionReference';
+import { Divider, View } from '@aws-amplify/ui-react';
+import { API_CATEGORIES, API_SUB_CATEGORIES } from '@/data/api-categories.mjs';
+import references from '@/directory/apiReferences.json';
+
+export const ReferencePage = ({ category }) => {
+  category = API_CATEGORIES[category] || API_SUB_CATEGORIES[category];
+  const cat = references['categories'].find(
+    (catObject) => catObject.name === category
+  );
+  return (
+    <View className={'reference-page'}>
+      {cat?.children?.map((child, idx) => (
+        <Fragment key={`reference-${idx}`}>
+          {idx !== 0 && <Divider marginTop={'medium'} />}
+          <FunctionReference func={child} />
+        </Fragment>
+      ))}
+    </View>
+  );
+};

src/components/ApiDocs/Throws.tsx

@@ -0,0 +1,21 @@
+import { View } from '@aws-amplify/ui-react';
+import { MDXHeading } from '../MDXComponents';
+import { ApiComment } from './ApiComment';
+
+export const Throws = ({ throws, sigName }) => {
+  return (
+    <View>
+      <MDXHeading level={3} id={`${sigName}-Throws`}>
+        Throws
+      </MDXHeading>
+
+      <ul>
+        {throws.map((error, i) => (
+          <li key={i}>
+            <ApiComment apiComment={error.content} codeBlock={true} />{' '}
+          </li>
+        ))}
+      </ul>
+    </View>
+  );
+};