@primer/doctocat-nextjs 0.5.2-rc.77cd6c6 → 0.5.2

package/CHANGELOG.md

@@ -4,7 +4,19 @@
 
 ### Patch Changes
 
-- [#38](https://github.com/primer/doctocat-nextjs/pull/38) [`e950c9a`](https://github.com/primer/doctocat-nextjs/commit/e950c9af9ad410025437510113172e207e2e30a2) Thanks [@danielguillan](https://github.com/danielguillan)! - Updated Primer Brand library to v0.54.0
+- [#41](https://github.com/primer/doctocat-nextjs/pull/41) [`e1ffb3a`](https://github.com/primer/doctocat-nextjs/commit/e1ffb3a630c51316a19e25869f731b4ef3660d2b) Thanks [@danielguillan](https://github.com/danielguillan)! - - Updated sidebar styles.
+
+  - Added active header link as sidebar heading.
+  - Made active header the root item of breadcrumbs, if available.
+  - Made sidebar group headlines link to the index page.
+
+- [#39](https://github.com/primer/doctocat-nextjs/pull/39) [`9090a35`](https://github.com/primer/doctocat-nextjs/commit/9090a3516de8657321ff2217e944cca6466ec9a0) Thanks [@danielguillan](https://github.com/danielguillan)! - Updated index pages to use a grid of Cards with thumbnails.
+
+  Use `thumbnail` and `thumbnail_darkMode` to set custom thumbnail URLs for light and dark color modes respectively.
+
+- [#38](https://github.com/primer/doctocat-nextjs/pull/38) [`e950c9a`](https://github.com/primer/doctocat-nextjs/commit/e950c9af9ad410025437510113172e207e2e30a2) Thanks [@danielguillan](https://github.com/danielguillan)! - Updated Primer Brand library to `v0.54.0`
+
+- [#42](https://github.com/primer/doctocat-nextjs/pull/42) [`c9c2d16`](https://github.com/primer/doctocat-nextjs/commit/c9c2d16aa12ad56c71ec5ddbc008a028a378d81d) Thanks [@rezrah](https://github.com/rezrah)! - Added placeholder images to the Index page cards, where `thumbnail` and `thumbnail_darkMode` aren't provided through the frontmatter
 
 ## 0.5.1
 

package/components/layout/index-cards/IndexCards.module.css

@@ -1,12 +1,5 @@
-.heading a {
-  color: var(--brand-InlineLink-color-rest);
-  text-decoration: none;
-}
-
-.heading a:hover {
-  text-decoration: underline;
-}
-
-.heading a:active {
-  color: var(--brand-InlineLink-color-pressed);
+.IndexCards {
+  --brand-Grid-spacing-column-gap: var(--base-size-24);
+  --brand-Grid-spacing-row: var(--base-size-24);
+  padding-inline: 0;
 }

package/components/layout/index-cards/IndexCards.tsx

@@ -1,16 +1,48 @@
-import React from 'react'
-import {Heading, Stack, Text} from '@primer/react-brand'
+import React, {useCallback, useRef} from 'react'
+import {Card, Grid} from '@primer/react-brand'
+import {DocsItem} from '../../../types'
+import {useColorMode} from '../../context/color-modes/useColorMode'
+import type {StaticImageData} from 'next/image'
+import placeholderDarkOneThumb from './images/dark-1.png'
+import placeholderDarkTwoThumb from './images/dark-2.png'
+import placeholderDarkThreeThumb from './images/dark-3.png'
+import placeholderDarkFourThumb from './images/dark-4.png'
+import placeholderDarkFiveThumb from './images/dark-5.png'
+import placeholderDarkSixThumb from './images/dark-6.png'
+import placeholderLightOneThumb from './images/light-1.png'
+import placeholderLightTwoThumb from './images/light-2.png'
+import placeholderLightThreeThumb from './images/light-3.png'
+import placeholderLightFourThumb from './images/light-4.png'
+import placeholderLightFiveThumb from './images/light-5.png'
+import placeholderLightSixThumb from './images/light-6.png'
 
-import Link from 'next/link'
 import styles from './IndexCards.module.css'
-import {DocsItem} from '../../../types'
 
 type IndexCardsProps = {
   route: string
   folderData: DocsItem[]
 }
 
+const darkModePlaceholderThumbs = [
+  placeholderDarkOneThumb,
+  placeholderDarkTwoThumb,
+  placeholderDarkThreeThumb,
+  placeholderDarkFourThumb,
+  placeholderDarkFiveThumb,
+  placeholderDarkSixThumb,
+] as unknown as StaticImageData[]
+
+const lightModePlaceholderThumbs = [
+  placeholderLightOneThumb,
+  placeholderLightTwoThumb,
+  placeholderLightThreeThumb,
+  placeholderLightFourThumb,
+  placeholderLightFiveThumb,
+  placeholderLightSixThumb,
+] as unknown as StaticImageData[]
+
 export function IndexCards({route, folderData}: IndexCardsProps) {
+  const lastPlaceholderIndexRef = useRef<number>(-1)
   // We don't want to show children of these pages. E.g. tabbed pages
   const onlyDirectChildren = folderData.filter(item => {
     // Normalize paths regardless of trailing slash enablement
@@ -27,23 +59,45 @@ export function IndexCards({route, folderData}: IndexCardsProps) {
   })
 
   const filteredData = onlyDirectChildren.filter(item => item.type === 'doc')
+
+  const {colorMode} = useColorMode()
+
+  // This is a better approach to straight randomisation, as it ensures that no adjacent placeholder images will be the same.
+  const getNextPlaceholderIndex = useCallback((placeholderArray: StaticImageData[]): StaticImageData => {
+    if (placeholderArray.length <= 1) {
+      return placeholderArray[0]
+    }
+
+    const numImagesByIndex = placeholderArray.map((_, index) => index)
+
+    const filteredIndexes = numImagesByIndex.filter(index => index !== lastPlaceholderIndexRef.current)
+
+    const nextIndex = filteredIndexes[Math.floor(Math.random() * filteredIndexes.length)]
+
+    lastPlaceholderIndexRef.current = nextIndex
+    return placeholderArray[nextIndex]
+  }, [])
+
   return (
-    <Stack direction="vertical" padding="none" gap="spacious">
+    <Grid className={styles.IndexCards}>
       {filteredData.map((item: DocsItem) => {
         if (item.type !== 'doc' || !item.frontMatter) return null
 
+        const thumbnailUrl =
+          colorMode === 'dark'
+            ? item.frontMatter.thumbnail_darkMode || getNextPlaceholderIndex(darkModePlaceholderThumbs).src
+            : item.frontMatter.thumbnail || getNextPlaceholderIndex(lightModePlaceholderThumbs).src
+
         return (
-          <Stack direction="vertical" padding="none" gap="condensed" key={item.frontMatter.title}>
-            <Heading as="h2" size="6" className={styles.heading}>
-              <Link href={item.route} legacyBehavior passHref>
-                {item.frontMatter.title}
-              </Link>
-            </Heading>
-
-            {item.frontMatter.description && <Text as="p">{item.frontMatter.description}</Text>}
-          </Stack>
+          <Grid.Column span={{xsmall: 12, small: 12, medium: 12, large: 6, xlarge: 4}} key={item.frontMatter.title}>
+            <Card href={item.route} hasBorder>
+              <Card.Image src={thumbnailUrl} alt="" aspectRatio="4:3" />
+              <Card.Heading>{item.frontMatter.title}</Card.Heading>
+              {item.frontMatter.description && <Card.Description>{item.frontMatter.description}</Card.Description>}
+            </Card>
+          </Grid.Column>
         )
       })}
-    </Stack>
+    </Grid>
   )
 }

package/components/layout/root-layout/Theme.tsx

@@ -28,6 +28,8 @@ import '@primer/react-brand/lib/css/main.css'
 import {normalizePages} from 'nextra/normalize-pages'
 import {usePathname} from 'next/navigation'
 
+import {useConfig} from '../../context/useConfig'
+
 import {Header} from '../header/Header'
 import {IndexCards} from '../index-cards/IndexCards'
 import {useColorMode} from '../../context/color-modes/useColorMode'
@@ -75,6 +77,9 @@ export function Theme({pageMap, children}: ThemeProps) {
 
   // eslint-disable-next-line i18n-text/no-en
   const siteTitle = process.env.NEXT_PUBLIC_SITE_TITLE || 'Example Site'
+  const {headerLinks} = useConfig()
+  const activeHeaderLink = headerLinks.find(link => link.isActive)
+
   const isHomePage = route === '/'
 
   const activeFile = isHomePage
@@ -133,7 +138,7 @@ export function Theme({pageMap, children}: ThemeProps) {
                           <>
                             {activePath.length && (
                               <Breadcrumbs>
-                                {siteTitle && (
+                                {(activeHeaderLink || siteTitle) && (
                                   <Breadcrumbs.Item
                                     as={NextLink}
                                     href="/"
@@ -141,7 +146,7 @@ export function Theme({pageMap, children}: ThemeProps) {
                                       color: 'var(--brand-InlineLink-color-rest)',
                                     }}
                                   >
-                                    {siteTitle}
+                                    {activeHeaderLink ? activeHeaderLink.title : siteTitle}
                                   </Breadcrumbs.Item>
                                 )}
                                 {activePath.map((item, index) => {

package/components/layout/sidebar/Sidebar.module.css

@@ -1,3 +1,13 @@
+.Sidebar__title {
+  display: block;
+  padding: var(--base-size-24) var(--base-size-16) 0;
+}
+
+.NavList {
+  font-family: var(--brand-fontStack-sansSerif);
+  font-size: inherit;
+}
+
 @media (min-width: 768px) {
   .Sidebar {
     padding-inline-start: var(--base-size-8);
@@ -5,18 +15,21 @@
 }
 
 .NavList h3 {
-  font-weight: normal;
-  text-transform: uppercase;
+  color: var(--brand-color-text-default);
+  font-size: var(--brand-text-size-100);
 }
 
-.NavList [data-component='ActionList.Divider'] {
-  display: none; /* TODO: Find workaround to hide this in component */
+.NavList__Container li a,
+.NavList__Container li button {
+  font-size: var(--brand-text-size-200);
+  padding-block: 0.5em;
 }
 
-.NavList h3 {
-  text-transform: initial;
-  color: var(--brand-color-text-default);
-  font-weight: var(--brand-text-subhead-weight-medium);
-  font-size: var(--brand-text-subhead-size-medium);
-  line-height: var(--brand-text-subhead-lineHeight-medium);
+.NavList .NavListItem {
+  margin-top: var(--base-size-4);
+}
+
+.NavList .NavListItem,
+.NavList .NavListItem a {
+  font-size: inherit;
 }

package/components/layout/sidebar/Sidebar.tsx

@@ -1,6 +1,7 @@
 import React, {useMemo} from 'react'
 import NextLink from 'next/link'
 import {NavList} from '@primer/react'
+import {Text} from '@primer/react-brand'
 import type {Folder, MdxFile, PageMapItem} from 'nextra'
 
 import styles from './Sidebar.module.css'
@@ -20,7 +21,8 @@ type SidebarProps = {
 
 export function Sidebar({pageMap}: SidebarProps) {
   const pathname = usePathname()
-  const {sidebarLinks} = useConfig()
+  const {headerLinks, sidebarLinks} = useConfig()
+  const activeHeaderLink = headerLinks.find(link => link.isActive)
 
   /**
    * Sorts the incoming data so that folders with a menu-position frontmatter value
@@ -46,6 +48,12 @@ export function Sidebar({pageMap}: SidebarProps) {
 
   return (
     <div className={styles.Sidebar}>
+      {activeHeaderLink && (
+        <Text size="400" weight="semibold" className={styles.Sidebar__title}>
+          {activeHeaderLink.title}
+        </Text>
+      )}
+
       <NavList className={styles.NavList} aria-label="Menu links">
         {reorderedPageMap.map(item => {
           if (item.hasOwnProperty('data')) return null
@@ -70,6 +78,9 @@ export function Sidebar({pageMap}: SidebarProps) {
 
           return (
             <NavList.Group title={subNavName} key={item.name} sx={{mb: 24}}>
+              <NavList.GroupHeading as="h3">
+                <NextLink href={item.route}>{subNavName}</NextLink>
+              </NavList.GroupHeading>
               {item.children
                 .sort((a, b) => ((a as MdxFile).name === 'index' ? -1 : (b as MdxFile).name === 'index' ? 1 : 0)) // puts index page first
                 // only show index page if it has show-tabs
@@ -85,6 +96,7 @@ export function Sidebar({pageMap}: SidebarProps) {
                         key={name}
                         href={route}
                         aria-current={route === cleanPathname ? 'page' : undefined}
+                        className={styles.NavListItem}
                       >
                         {(child as MdxFile).frontMatter?.title || name}
                       </NavList.Item>
@@ -110,6 +122,7 @@ export function Sidebar({pageMap}: SidebarProps) {
                         href={landingPageItem.route}
                         sx={{textTransform: 'capitalize'}}
                         aria-current={isCurrentOrChild ? 'page' : undefined}
+                        className={styles.NavListItem}
                       >
                         {landingPageItem.frontMatter?.title || item.name}
                       </NavList.Item>
@@ -129,6 +142,7 @@ export function Sidebar({pageMap}: SidebarProps) {
                   href={link.href}
                   {...(link.isExternal && {target: '_blank', rel: 'noopener noreferrer'})}
                   aria-current={link.isActive ? 'page' : undefined}
+                  className={styles.NavListItem}
                 >
                   {link.title}
                   {link.isExternal && (

package/global.types.d.ts

@@ -0,0 +1,5 @@
+declare module '*.png' {
+  const content: string
+
+  export default content
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.5.2-rc.77cd6c6",
+  "version": "0.5.2",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",

package/types.ts

@@ -38,4 +38,6 @@ export type FrontMatter = {
   timestamp?: number
   title?: string
   [key: string]: unknown
+  thumbnail?: string
+  thumbnail_darkMode?: string
 }