From cdda093bd78e1336a3c599cea17ebb682debb1d0 Mon Sep 17 00:00:00 2001
From: Heather <hbuchel@gmail.com>
Date: Tue, 10 Sep 2024 12:35:51 -0400
Subject: [PATCH 1/2] update Modal styling/ add Breadcrumbs

---
 src/components/ApiDocs/display/ApiModal.tsx   | 140 ++++++++++--------
 .../ApiDocs/display/ApiModalBreadcrumbs.tsx   |  55 +++++++
 src/components/ApiDocs/display/TypeLink.tsx   |   2 +-
 src/styles/reference.scss                     | 120 ++++++++++-----
 4 files changed, 216 insertions(+), 101 deletions(-)
 create mode 100644 src/components/ApiDocs/display/ApiModalBreadcrumbs.tsx

diff --git a/src/components/ApiDocs/display/ApiModal.tsx b/src/components/ApiDocs/display/ApiModal.tsx
index 3cbf90c0a58..c311cd51793 100644
--- a/src/components/ApiDocs/display/ApiModal.tsx
+++ b/src/components/ApiDocs/display/ApiModal.tsx
@@ -1,19 +1,27 @@
-import {
-  View,
-  Flex,
-  Heading,
-  Card,
-  Divider,
-  Button
-} from '@aws-amplify/ui-react';
+import { Badge, View, Flex, Grid, Card, Button } from '@aws-amplify/ui-react';
+
+import { ApiModalBreadcrumbs } from './ApiModalBreadcrumbs';
 import { IconX } from '../../Icons';
 import { ParameterType } from './ParameterType';
 import { ApiComment } from '../ApiComment';
-import { TypeLink } from './TypeLink';
+import { LinkDataType, TypeLinkInterface } from './TypeLink';
 import references from '@/directory/apiReferences.json';
 
-export const ApiModal = ({ data, showModal, close, breadCrumbs, clearBC }) => {
-  let name = data.name;
+interface ApiModalInterface {
+  data: any;
+  showModal?: boolean;
+  close: () => void;
+  breadCrumbs: LinkDataType[];
+  clearBC: () => void;
+}
+
+export const ApiModal = ({
+  data,
+  showModal = false,
+  close,
+  breadCrumbs,
+  clearBC
+}: ApiModalInterface) => {
   if (data.type === 'reference') {
     data = references[data.target];
   }
@@ -24,6 +32,7 @@ export const ApiModal = ({ data, showModal, close, breadCrumbs, clearBC }) => {
     close();
   };
 
+  let name = data.name;
   let typeParameters = data.typeArguments;
   if (data?.typeObject?.type == 'alias' && data.typeObject.typeParameters) {
     typeParameters = data.typeObject.typeParameters;
@@ -40,6 +49,7 @@ export const ApiModal = ({ data, showModal, close, breadCrumbs, clearBC }) => {
   if (params && params.length) {
     name += `<${params.join(',')}>`;
   }
+
   const typeData = data.typeObject || data.value;
   // look for objects or interfaces to render additional data
   const displayProperties = {};
@@ -66,60 +76,64 @@ export const ApiModal = ({ data, showModal, close, breadCrumbs, clearBC }) => {
   }
   recursivelyParseType(typeData, displayProperties);
 
+  const breadcrumbItems = breadCrumbs.length
+    ? breadCrumbs.reduce((acc, breadcrumb, index) => {
+        const bcArray = breadCrumbs.slice(0, index + 1);
+        acc.push({ linkData: breadcrumb, breadCrumbs: bcArray });
+        return acc;
+      }, [] as TypeLinkInterface[])
+    : [];
+
   return (
-    <View display={showModal ? 'flex' : 'none'} className="api-modal-container">
-      <View>
-        <Card
-          className="api-modal"
-          borderRadius="medium"
-          variation="outlined"
-          textAlign="center"
-          position="relative"
-        >
-          <View padding="xs" fontSize="large">
-            <Flex className={'bread-crumbs'}>
-              {breadCrumbs.length &&
-                breadCrumbs.reduce((acc, bc, idx) => {
-                  const bcArray = breadCrumbs.slice(0, idx + 1);
-                  const next = <TypeLink linkData={bc} breadCrumbs={bcArray} />;
-                  if (idx > 0) {
-                    acc.push(' > ');
-                  }
-                  acc.push(next);
-                  return acc;
-                }, [])}
-            </Flex>
-            <Button
-              onClick={closeModal}
-              size="small"
-              variation="link"
-              className={'close-button'}
-            >
-              <IconX />
-            </Button>
-            <Flex justifyContent="space-between">
-              <Heading padding="large" level={2}>
-                {name}
-              </Heading>
-            </Flex>
-            <Divider padding="xs" />
-            <Flex justifyContent={'center'}>
-              <View as={'code'} fontSize="large" className={'parameter'}>
-                <ParameterType typeData={data.type || data} />
-              </View>
-            </Flex>
-            <View className={'description-wrapper'}>
-              <View className={'description'}>
-                {description && (
-                  <>
-                    <ApiComment apiComment={description} />
-                  </>
-                )}
-              </View>
+    <View
+      aria-label={`${name} API Reference`}
+      className={`api-modal-container${showModal ? ' api-modal-container--open' : ''}`}
+    >
+      <Card as="dialog" className="api-modal" aria-modal="true">
+        <Flex className="api-model__header">
+          <ApiModalBreadcrumbs items={breadcrumbItems} />
+          <Button
+            onClick={closeModal}
+            size="small"
+            variation="link"
+            className="api-modal__close"
+          >
+            <IconX />
+          </Button>
+        </Flex>
+
+        <Grid as="dl" className="api-modal__content">
+          <dt>Name:</dt>
+          <Flex as="dd" className="api-modal__content__name">
+            <Badge size="small">
+              {data.type?.type ? data.type.type : 'interface'}{' '}
+            </Badge>
+            <span className="api-modal__api-name">{name}</span>
+          </Flex>
+          <dt>Value:</dt>
+          {/** This dd is not scrollable if the value is only a reference, because
+           * then it is a single link to an item (avoids having to tab again). It is
+           * scrollable for others because the code might overflow the container on smaller
+           * viewports.
+           */}
+          <dd
+            className="api-modal__api-value"
+            tabIndex={data.type?.type === 'reference' ? -1 : 0}
+          >
+            <View as="code" className="parameter">
+              <ParameterType typeData={data.type || data} />
             </View>
-          </View>
-        </Card>
-      </View>
+          </dd>
+          {description ? (
+            <>
+              <dt>Description:</dt>
+              <dd>
+                <ApiComment apiComment={description} />
+              </dd>
+            </>
+          ) : null}
+        </Grid>
+      </Card>
     </View>
   );
 };
diff --git a/src/components/ApiDocs/display/ApiModalBreadcrumbs.tsx b/src/components/ApiDocs/display/ApiModalBreadcrumbs.tsx
new file mode 100644
index 00000000000..5ea1ef744a0
--- /dev/null
+++ b/src/components/ApiDocs/display/ApiModalBreadcrumbs.tsx
@@ -0,0 +1,55 @@
+import { useEffect, useRef, Fragment } from 'react';
+import { Text, Flex } from '@aws-amplify/ui-react';
+
+import { TypeLink, TypeLinkInterface } from './TypeLink';
+
+interface ApiModalBreadcrumbs {
+  items?: TypeLinkInterface[];
+}
+
+export const ApiModalBreadcrumbs = ({ items }: ApiModalBreadcrumbs) => {
+  const navRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (navRef.current) {
+      navRef.current.scrollLeft = navRef.current.scrollWidth;
+    }
+  }, [items]);
+
+  return (
+    <Flex
+      as="nav"
+      ref={navRef}
+      aria-label="API Type breadcrumbs"
+      className="api-modal__breadcrumbs"
+      tabIndex={0}
+    >
+      {items
+        ? items.map((item, index) => {
+            return (
+              <Fragment key={`api-breadcrumb-${index}`}>
+                {index !== 0 ? (
+                  <div
+                    className="api-modal__breadcrumbs__separator"
+                    aria-hidden="true"
+                  >
+                    /
+                  </div>
+                ) : null}{' '}
+                {index === items.length - 1 ? (
+                  <Text as="span" className="api-modal__breadcrumbs__current">
+                    {item.linkData.name}
+                  </Text>
+                ) : (
+                  <TypeLink
+                    linkData={item.linkData}
+                    breadCrumbs={item.breadCrumbs}
+                  />
+                )}
+              </Fragment>
+            );
+          })
+        : null}
+    </Flex>
+  );
+};
diff --git a/src/components/ApiDocs/display/TypeLink.tsx b/src/components/ApiDocs/display/TypeLink.tsx
index 86de4a83a78..cf01e9e77b2 100644
--- a/src/components/ApiDocs/display/TypeLink.tsx
+++ b/src/components/ApiDocs/display/TypeLink.tsx
@@ -11,7 +11,7 @@ export interface LinkDataType {
 
 export interface TypeLinkInterface {
   linkData: LinkDataType;
-  breadCrumbs?: [];
+  breadCrumbs?: LinkDataType[];
 }
 
 export const TypeLink = ({ linkData, breadCrumbs }: TypeLinkInterface) => {
diff --git a/src/styles/reference.scss b/src/styles/reference.scss
index 76720f2edaf..6aa85dbe862 100644
--- a/src/styles/reference.scss
+++ b/src/styles/reference.scss
@@ -11,66 +11,112 @@
 }
 
 .api-modal-container {
+  display: none;
   position: fixed;
   top: 0;
   left: 0;
   width: 100vw;
   height: 100vh;
   background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
   align-items: center;
   justify-content: center;
   z-index: 99999;
+  &--open {
+    display: flex;
+  }
+}
 
-  .api-modal {
-    padding: 60px;
-    border-radius: 10px;
-    box-shadow: 0px 0px 10px #cccccc;
-    width: 80vw;
-    height: 80vh;
-    overflow: auto;
-    display: block;
-    color: var(--amplify-colors-font-primary);
+.api-modal {
+  width: 800px;
+  max-width: 90vw;
+  max-height: 90vh;
+  border-radius: var(--amplify-radii-medium);
+}
 
-    .close-button {
-      position: absolute;
-      top: 0;
-      right: 0;
-      padding: var(--amplify-space-small);
-    }
+.api-model__header {
+  align-items: flex-start;
+}
 
-    h2,
-    h3 {
-      text-align: center;
-      width: 100%;
-    }
+.api-modal__breadcrumbs {
+  flex: 1 0 0;
+  padding-bottom: var(--amplify-space-medium);
+  margin-bottom: var(--amplify-space-xs);
+  overflow: scroll;
+  align-items: baseline;
+  gap: 2px;
+}
 
-    .amplify-divider {
-      margin-bottom: var(--amplify-space-large);
-    }
+.api-modal__breadcrumbs__current {
+  font-weight: bold;
+}
 
-    .parameter {
-      min-width: 60%;
-      margin: var(--amplify-space-xs);
-      text-align: left;
-    }
+.api-modal__content {
+  gap: var(--amplify-space-xxs);
+  grid-template-columns: 1fr;
+  grid-template-rows: auto;
+  align-items: baseline;
+  dt {
+    color: var(--amplify-colors-font-secondary);
+    /** Visually hide labels on small viewports */
+    // position: absolute;
+    // width: 1px;
+    // height: 1px;
+    // padding: 0;
+    // margin: -1px;
+    // fill: transparent;
+    // overflow: hidden;
+    // clip: rect(0, 0, 0, 0);
+    // white-space: nowrap;
+    // border-width: 0;
+  }
+  dd {
+    padding-inline-start: var(--amplify-space-small);
+  }
+  &__name {
+    text-align: start;
+    color: var(--amplify-colors-neutral-90);
+    font-weight: bold;
+    align-items: baseline;
+  }
+}
 
-    .object-type {
-      margin-left: var(--amplify-space-large);
-    }
+.api-modal__api-name {
+  word-break: break-word;
+  flex: 1 0 0;
+}
 
-    .bread-crumbs {
-      margin-bottom: var(--amplify-space-xs);
-    }
+.api-modal__api-value {
+  overflow: scroll;
+
+  &:focus-visible {
+    outline: 2px solid var(--amplify-colors-border-focus);
+    outline-offset: 2px;
+  }
+}
 
-    .description {
-      margin-top: var(--amplify-space-xl);
+@media (min-width: 600px) {
+  .api-modal__content {
+    grid-template-columns: auto 1fr;
+    gap: var(--amplify-space-small);
+    dt {
+      position: relative;
+      white-space: normal;
+      width: auto;
+      height: auto;
+      margin: 0;
+      clip: none;
+      text-align: end;
     }
   }
 }
 
+.object-type {
+  margin-inline-start: var(--amplify-space-medium);
+}
+
 .type-link {
   cursor: pointer;
+  margin: 4px;
   border: none;
   padding: 0;
   background: none;

From d11d4953a69e23f0c27988723bb874c4f8c6c2be Mon Sep 17 00:00:00 2001
From: Heather <hbuchel@gmail.com>
Date: Tue, 10 Sep 2024 12:51:02 -0400
Subject: [PATCH 2/2] remove commented out code

---
 src/styles/reference.scss | 17 -----------------
 1 file changed, 17 deletions(-)

diff --git a/src/styles/reference.scss b/src/styles/reference.scss
index 6aa85dbe862..3fe95441783 100644
--- a/src/styles/reference.scss
+++ b/src/styles/reference.scss
@@ -57,17 +57,6 @@
   align-items: baseline;
   dt {
     color: var(--amplify-colors-font-secondary);
-    /** Visually hide labels on small viewports */
-    // position: absolute;
-    // width: 1px;
-    // height: 1px;
-    // padding: 0;
-    // margin: -1px;
-    // fill: transparent;
-    // overflow: hidden;
-    // clip: rect(0, 0, 0, 0);
-    // white-space: nowrap;
-    // border-width: 0;
   }
   dd {
     padding-inline-start: var(--amplify-space-small);
@@ -99,12 +88,6 @@
     grid-template-columns: auto 1fr;
     gap: var(--amplify-space-small);
     dt {
-      position: relative;
-      white-space: normal;
-      width: auto;
-      height: auto;
-      margin: 0;
-      clip: none;
       text-align: end;
     }
   }