Merge pull request #59 from omnifed/58-docs-general-updates

58 docs general updates

docs/app/components/Admonition.tsx

@@ -1,45 +1,167 @@
-import { css } from '@/styled-system/css'
+import { css, cx } from '@/styled-system/css'
 import { hstack } from '@/styled-system/patterns'
-import { Information } from '@cerberus-design/icons'
-import type { PropsWithChildren } from 'react'
+import {
+  DataEnrichmentAdd,
+  Information,
+  Light,
+  WarningHex,
+} from '@cerberus-design/icons'
+import type { Sentiment } from '@cerberus-design/panda-preset'
+import type { PropsWithChildren, ReactNode } from 'react'
 
 // TODO: Replace with React version when available
 
 interface AdmonitionProps {
-  heading: string
   description: string
+  heading: string
+  icon: ReactNode
+  palette: Sentiment
+}
+
+function getPaletteStyles(palette: Sentiment) {
+  switch (palette) {
+    case 'success':
+      return css({
+        bgColor: 'success.surface.initial',
+        color: 'success.border.initial',
+      })
+
+    case 'warning':
+      return css({
+        bgColor: 'warning.surface.initial',
+        color: 'warning.border.initial',
+      })
+
+    case 'danger':
+      return css({
+        bgColor: 'danger.surface.initial',
+        color: 'danger.border.initial',
+      })
+
+    case 'info':
+    default:
+      return css({
+        bgColor: 'info.surface.initial',
+        color: 'info.border.initial',
+      })
+  }
+}
+
+function getPaletteTextStyles(palette: Sentiment) {
+  switch (palette) {
+    case 'success':
+      return css({
+        color: 'success.text.initial !important',
+      })
+
+    case 'warning':
+      return css({
+        color: 'warning.text.initial !important',
+      })
+
+    case 'danger':
+      return css({
+        color: 'danger.text.initial !important',
+        _darkMode: {
+          color: 'danger.text.inverse !important',
+        },
+      })
+
+    case 'info':
+    default:
+      return css({
+        color: 'info.text.initial !important',
+      })
+  }
 }
 
 export function Admonition(props: PropsWithChildren<AdmonitionProps>) {
+  const paletteStyles = getPaletteStyles(props.palette)
+  const textStyles = getPaletteTextStyles(props.palette)
+
   return (
     <div
-      className={css({
-        bgColor: 'info.surface.initial',
-        color: 'info.text.100',
-        mb: '6',
-        mt: '4',
-        p: '4',
-        rounded: 'xl',
-      })}
+      className={cx(
+        paletteStyles,
+        css({
+          mb: '6',
+          mt: '4',
+          pb: '4',
+          pxi: '6',
+          pt: '6',
+          rounded: '2xl',
+        }),
+      )}
     >
       <div
         className={hstack({
-          color: 'info.text.initial !important',
+          color: 'inherit !important',
           pb: '2',
         })}
       >
-        <Information aria-hidden size="1.25rem" />
+        {props.icon}
         <p
-          className={css({
-            color: 'info.text.initial !important',
-            pb: 'initial !important',
-            textStyle: 'h5 !important',
-          })}
+          className={cx(
+            textStyles,
+            css({
+              pb: 'initial !important',
+              paddingInlineStart: '2',
+              textStyle: 'h5 !important',
+            }),
+          )}
         >
           {props.heading}
         </p>
       </div>
-      <p>{props.description}</p>
+      <p
+        className={cx(
+          textStyles,
+          css({
+            paddingInlineStart: '10',
+            pt: '2',
+            textWrap: 'pretty',
+          }),
+        )}
+      >
+        {props.description}
+      </p>
     </div>
   )
 }
+
+interface AdmonitionTypeProps {
+  description: string
+}
+
+export function NoteAdmonition(props: AdmonitionTypeProps) {
+  return (
+    <Admonition
+      heading="Note"
+      description={props.description}
+      icon={<Information aria-hidden size="1.5rem" />}
+      palette="info"
+    />
+  )
+}
+
+export function WhenToUseAdmonition(props: AdmonitionTypeProps) {
+  return (
+    <Admonition
+      heading="When to use"
+      description={props.description}
+      icon={<DataEnrichmentAdd aria-hidden size="1.5rem" />}
+      palette="success"
+    />
+  )
+}
+
+export function WhenNotToUseAdmonition(props: AdmonitionTypeProps) {
+  return (
+    <Admonition
+      heading="When not to use"
+      description={props.description}
+      icon={<WarningHex aria-hidden size="1.5rem" />}
+      palette="danger"
+    />
+  )
+}

docs/app/components/Nav.tsx

@@ -52,7 +52,7 @@ export function Nav() {
             pxi: '2',
             textStyle: 'body-xl',
             _active: {
-              color: 'blue',
+              color: 'neutral.text.initial',
             },
           })}
         >
@@ -81,10 +81,6 @@ export function Nav() {
             borderColor: 'neutral.border.initial',
             gap: '0',
             w: 'full',
-            md: {
-              border: 'none',
-              w: 'auto',
-            },
             '& li:nth-child(2)': {
               borderColor: 'neutral.border.initial',
               borderLeft: '1px solid',
@@ -93,6 +89,10 @@ export function Nav() {
                 border: 'none',
               },
             },
+            md: {
+              border: 'none',
+              w: 'auto',
+            },
           })}
         >
           {navData.map((item) => (
@@ -105,7 +105,7 @@ export function Nav() {
               key={item.id}
             >
               <Link
-                aria-current={pathname === item.href ? 'page' : undefined}
+                aria-current={pathname.includes(item.href) ? 'page' : undefined}
                 className={css({
                   display: 'inline-block',
                   p: '4',

docs/app/components/OnThisPage.tsx

@@ -0,0 +1,102 @@
+'use client'
+
+import { css } from '@/styled-system/css'
+import { vstack } from '@/styled-system/patterns'
+import Link from 'next/link'
+import { useLayoutEffect, useRef, useState } from 'react'
+
+interface OverrideHeading {
+  href: string
+}
+
+interface NodeOverride {
+  href: {
+    nodeValue: string
+  }
+}
+
+interface HeadingLink {
+  id: string
+  label: string
+  path: string
+}
+
+export default function OnThisPage() {
+  const hasRendered = useRef<boolean>(false)
+  const [links, setLinks] = useState<HeadingLink[]>([])
+
+  useLayoutEffect(() => {
+    if (hasRendered.current) return
+    const nodeList = document.querySelectorAll('a.heading')
+
+    for (let i = 0; i < nodeList.length; i++) {
+      const heading = nodeList[i]
+      const overrideHeading = heading as unknown as OverrideHeading
+      const attributes = heading.attributes as unknown as NodeOverride
+      setLinks((prevLinks) => [
+        ...prevLinks,
+        {
+          id: attributes.href.nodeValue ?? '#',
+          label: heading.textContent ?? '',
+          path: overrideHeading.href,
+        },
+      ])
+    }
+
+    hasRendered.current = true
+  }, [])
+
+  return (
+    <div
+      className={css({
+        borderLeft: '1px solid',
+        borderColor: 'neutral.border.initial',
+        paddingInlineStart: '6',
+      })}
+    >
+      <p
+        className={css({
+          color: 'neutral.text.100',
+          textStyle: 'h6',
+          mb: '4',
+        })}
+      >
+        On this page
+      </p>
+      <ul
+        aria-label="Page sections"
+        className={vstack({
+          alignItems: 'flex-start',
+          gap: '1',
+        })}
+      >
+        {links.map((link) => (
+          <li key={link.id}>
+            <Link
+              aria-current={
+                window.location.hash === link.id ? 'page' : undefined
+              }
+              href={link.id}
+              className={css({
+                display: 'block',
+                textStyle: 'body-xs',
+                textWrap: 'pretty',
+                '&:hover': {
+                  textDecorationColor: 'action.navigation.hover',
+                  textDecoration: 'underline',
+                },
+                _currentPage: {
+                  color: 'action.navigation.visited',
+                  textDecorationColor: 'action.navigation.hover',
+                  textDecoration: 'underline',
+                },
+              })}
+            >
+              {link.label}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}