feat: clickable chapter title (#1744)

* feat: clickable chapter title * chore: fix active link color * chore: add rule to support backwards compatibility * chore: fix pagination section * chore: remove console.log * chore: updated smoke test navigation.yaml * chore: add documentation overview page * chore: add api-smoke-test overview pages * chore: changeset
commercetools · Jul 13, 2023 · 561a159 · 561a159
1 parent 81f0bc6
commit 561a159
Show file tree

Hide file tree

Showing 23 changed files with 321 additions and 12 deletions.
diff --git a/.changeset/quiet-suns-report.md b/.changeset/quiet-suns-report.md
@@ -0,0 +1,10 @@
+---
+'@commercetools-website/self-learning-smoke-test': minor
+'@commercetools-website/api-docs-smoke-test': minor
+'@commercetools-docs/gatsby-theme-docs': minor
+'@commercetools-website/docs-smoke-test': minor
+'@commercetools-website/documentation': minor
+'@commercetools-website/site-template': minor
+---
+
+Enable support for clickable chapter titles in websites. This is NOT a breaking change as we keep supporting non clickable chapters.
diff --git a/packages/gatsby-theme-docs/gatsby-node.mjs b/packages/gatsby-theme-docs/gatsby-node.mjs
@@ -162,6 +162,7 @@ export const createSchemaCustomization = ({ actions, schema }) => {
     type NavigationYaml implements Node @dontInfer {
       id: ID!
       chapterTitle: String! @proxy(from: "chapter-title")
+      path: String
       beta: Boolean
       pagination: Boolean
       pages: [NavigationPage!]
@@ -471,6 +472,7 @@ async function createContentPages(
       allNavigationYaml {
         nodes {
           chapterTitle
+          path
           pages {
             title
             path

diff --git a/packages/gatsby-theme-docs/src/components/content-pagination.js b/packages/gatsby-theme-docs/src/components/content-pagination.js
@@ -104,25 +104,76 @@ PaginationLink.propTypes = {
   direction: PropTypes.oneOf(['left', 'right']).isRequired,
 };
 
+// TODO: cleanup. After docs websites migrate to clickable chapter, this function
+// can be simplified/removed or refactored since is currently supporting both clickable
+// and non-clickable configs
+const isChapterPathOrPageMatchingSlug = (node, slug) => {
+  if (node.path && isMatching(slug, node.path)) {
+    return true;
+  }
+  return node.pages.some((page) => isMatching(slug, page.path));
+};
+
+// TODO: cleanup. After docs websites migrate to clickable chapter, this function
+// can be simplified/removed or refactored since is currently supporting both clickable
+// and non-clickable configs
+const findActivePageIndex = (node, slug) => {
+  let indexOffset = 0;
+  if (node.path) {
+    indexOffset = 1;
+  }
+  if (node.path && isMatching(slug, node.path)) {
+    return 0;
+  }
+  const index = node.pages.findIndex(
+    (page) => page.path && isMatching(slug, page.path)
+  );
+  if (index >= 0) {
+    return index + indexOffset;
+  }
+  return index;
+};
+
+// TODO: cleanup. After docs websites migrate to clickable chapter, this function
+// can be simplified/removed or refactored since is currently supporting both clickable
+// and non-clickable configs
+const getPreviousPageLink = (node, currentIndex) => {
+  if (node.path) {
+    if (currentIndex === 1) {
+      // return the chapter
+      return { path: node.path, title: node.chapterTitle };
+    } else {
+      return node.pages[currentIndex - 2];
+    }
+  }
+  return node.pages[currentIndex - 1];
+};
+
+// TODO: cleanup. After docs websites migrate to clickable chapter, this function
+// can be simplified/removed or refactored since is currently supporting both clickable
+// and non-clickable configs
+const getNextPageLink = (node, currentIndex) => {
+  const indexOffset = node.path ? 1 : 0;
+  return node.pages[currentIndex - indexOffset + 1];
+};
+
 export const PurePagination = (props) => {
   const activeChapter = props.data.allNavigationYaml.nodes.find((node) => {
     const isPaginationEnabledForChapter =
       typeof node.pagination === 'boolean' ? node.pagination : true;
     if (!isPaginationEnabledForChapter) return false;
     if (!node.pages) return false;
-    return node.pages.some((page) => isMatching(props.slug, page.path));
+    return isChapterPathOrPageMatchingSlug(node, props.slug);
   });
 
   if (!activeChapter) {
     return <Container />;
   }
 
-  const currentPageLinkIndex = activeChapter.pages.findIndex((page) =>
-    isMatching(props.slug, page.path)
-  );
+  const currentPageLinkIndex = findActivePageIndex(activeChapter, props.slug);
   const hasPagination = currentPageLinkIndex > -1;
-  const previousPage = activeChapter.pages[currentPageLinkIndex - 1];
-  const nextPage = activeChapter.pages[currentPageLinkIndex + 1];
+  const previousPage = getPreviousPageLink(activeChapter, currentPageLinkIndex);
+  const nextPage = getNextPageLink(activeChapter, currentPageLinkIndex);
 
   return (
     <Container aria-label="Next / Previous in Chapter Navigation">
@@ -176,6 +227,7 @@ const Pagination = (props) => {
       allNavigationYaml {
         nodes {
           chapterTitle
+          path
           pagination
           pages {
             title

diff --git a/packages/gatsby-theme-docs/src/layouts/internals/sidebar.js b/packages/gatsby-theme-docs/src/layouts/internals/sidebar.js
@@ -83,6 +83,16 @@ const LinkTitle = styled.div`
   overflow-x: hidden;
   width: 100%;
 `;
+const LinkChapterTitle = styled.div`
+  font-size: ${designSystem.typography.fontSizes.body};
+  text-overflow: ellipsis;
+  overflow-x: hidden;
+  width: 100%;
+  color: ${designSystem.colors.light.textPrimary};
+  :hover {
+    color: ${designSystem.colors.light.linkNavigation};
+  }
+`;
 const LinkSubtitle = styled.div`
   font-size: ${designSystem.typography.fontSizes.small};
   text-overflow: ellipsis;
@@ -96,8 +106,16 @@ const LinkItem = styled.div`
   align-items: flex-end;
   vertical-align: middle;
 `;
+
+// TODO: cleanup. After docs websites migrate to clickable chapter, this component
+// can be simplified/removed or refactored since is currently supporting both clickable
+// and non-clickable configs
 const LinkItemWithIcon = styled.div`
-  padding: 0 0 0 ${designSystem.dimensions.spacings.m};
+  ${(props) =>
+    !props.clickable &&
+    `
+    padding: 0 0 0 ${designSystem.dimensions.spacings.m};
+  `}
   display: flex;
   flex-direction: row;
   vertical-align: middle;
@@ -278,10 +296,42 @@ const SidebarChapter = (props) => {
     [elemId]
   );
 
+  // TODO: cleanup. After docs websites migrate to clickable chapter, this component
+  // can be simplified/removed or refactored since is currently supporting both clickable
+  // and non-clickable configs
   return (
     <div role="sidebar-chapter" id={elemId}>
       <SpacingsStack data-testid={`sidebar-chapter-${courseId}`} scale="s">
-        {courseId ? (
+        {props.chapter.path ? (
+          <SidebarLinkWrapper
+            data-testid={`sidebar-chapter-title-item-${courseId}`}
+            key={`${props.index}-${props.chapter.path}`}
+            to={props.chapter.path}
+            onClick={props.onLinkClick}
+            location={props.location}
+            nextScrollPosition={props.nextScrollPosition}
+            getChapterDOMElement={getChapterDOMElement}
+            customActiveStyles={css`
+              div:first-child {
+                color: ${designSystem.colors.light.linkNavigation} !important;
+              }
+              div:first-child > div {
+                color: ${designSystem.colors.light.linkNavigation} !important;
+              }
+            `}
+          >
+            {courseId ? (
+              <LinkItemWithIcon clickable={true}>
+                <SidebarCourseStatus courseId={courseId} />
+                <LinkChapterTitle>
+                  {props.chapter.chapterTitle}
+                </LinkChapterTitle>
+              </LinkItemWithIcon>
+            ) : (
+              <LinkChapterTitle>{props.chapter.chapterTitle}</LinkChapterTitle>
+            )}
+          </SidebarLinkWrapper>
+        ) : courseId ? (
           <LinkItemWithIcon>
             <SidebarCourseStatus courseId={courseId} />
             <LinkTitle>{props.chapter.chapterTitle}</LinkTitle>
@@ -333,6 +383,7 @@ SidebarChapter.propTypes = {
   index: PropTypes.number.isRequired,
   chapter: PropTypes.shape({
     chapterTitle: PropTypes.string.isRequired,
+    path: PropTypes.string,
     beta: PropTypes.bool,
     pages: PropTypes.arrayOf(
       PropTypes.shape({
@@ -358,6 +409,7 @@ const SidebarNavigationLinks = (props) => {
       allNavigationYaml {
         nodes {
           chapterTitle
+          path
           pages {
             title
             path

diff --git a/websites/api-docs-smoke-test/src/content/docs-replications/overview.mdx b/websites/api-docs-smoke-test/src/content/docs-replications/overview.mdx
@@ -0,0 +1,9 @@
+---
+title: Docs Replications
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [Long Page with Many Types](/docs-replications/long-page)
diff --git a/websites/api-docs-smoke-test/src/content/e2e-tests/overview.mdx b/websites/api-docs-smoke-test/src/content/e2e-tests/overview.mdx
@@ -0,0 +1,10 @@
+---
+title: E2E Tests
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [Soft Linking First Page](/e2e-tests/soft-linking-first-page)
+- [Soft Linking Second Page](/e2e-tests/soft-linking-second-page)
diff --git a/websites/api-docs-smoke-test/src/content/endpoints/overview.mdx b/websites/api-docs-smoke-test/src/content/endpoints/overview.mdx
@@ -0,0 +1,10 @@
+---
+title: Endpoints
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [Methods](/endpoints/methods)
+- [All Endpoints of Resource](/endpoints/endpoints-for-resource)
diff --git a/websites/api-docs-smoke-test/src/content/layouts/overview.mdx b/websites/api-docs-smoke-test/src/content/layouts/overview.mdx
@@ -0,0 +1,12 @@
+---
+title: Layouts
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [API Type Large Desktop](/layouts/type-large-desktop)
+- [API Type Regular Desktop](/layouts/type-regular-desktop)
+- [API Endpoint Large Desktop](/layouts/endpoint-large-desktop)
+- [API Endpoint Regular Desktop](/layouts/endpoint-regular-desktop)
diff --git a/websites/api-docs-smoke-test/src/content/types/overview.mdx b/websites/api-docs-smoke-test/src/content/types/overview.mdx
@@ -0,0 +1,12 @@
+---
+title: Types
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [General](/types/general)
+- [Scalars](/types/scalars)
+- [Examples](/types/examples)
+- [Enums, Constants & Unions](/types/enums-constants-unions)
diff --git a/websites/api-docs-smoke-test/src/data/navigation.yaml b/websites/api-docs-smoke-test/src/data/navigation.yaml
@@ -1,4 +1,5 @@
 - chapter-title: Layouts
+  path: /layouts/overview
   pages:
     - title: API Type Large Desktop
       path: /layouts/type-large-desktop
@@ -9,6 +10,7 @@
     - title: API Endpoint Regular Desktop
       path: /layouts/endpoint-regular-desktop
 - chapter-title: Types
+  path: /types/overview
   pages:
     - title: General
       path: /types/general
@@ -19,18 +21,21 @@
     - title: Enums, Constants & Unions
       path: /types/enums-constants-unions
 - chapter-title: Endpoints
+  path: /endpoints/overview
   pages:
     - title: Methods
       path: /endpoints/methods
     - title: All Endpoints of Resource
       path: /endpoints/endpoints-for-resource
 - chapter-title: E2E Tests
+  path: /e2e-tests/overview
   pages:
     - title: Soft Linking First Page
       path: /e2e-tests/soft-linking-first-page
     - title: Soft Linking Second Page
       path: /e2e-tests/soft-linking-second-page
 - chapter-title: Docs Replications
+  path: /docs-replications/overview
   pages:
     - title: Long Page with Many Types
       path: /docs-replications/long-page
diff --git a/websites/docs-smoke-test/src/content/components/overview.mdx b/websites/docs-smoke-test/src/content/components/overview.mdx
@@ -0,0 +1,17 @@
+---
+title: Components
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [Code blocks](/components/code-blocks)
+- [Code Examples](/components/code-examples)
+- [Content notifications](/components/content-notifications)
+- [Images](/components/images)
+- [Cards](/components/cards)
+- [RSS Feeds](/components/rss-feeds)
+- [Child section navigation](/components/child-section-navigation)
+- [Mermaid Diagrams](/components/mermaid-diagram)
+- [Video Player](/components/video-player)
diff --git a/websites/docs-smoke-test/src/content/empty-pages/overview-1.mdx b/websites/docs-smoke-test/src/content/empty-pages/overview-1.mdx
@@ -0,0 +1,10 @@
+---
+title: Empty pages
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [PageWithLongNameThatOverflowsBecauseItsOneWord](/empty-pages/empty-page-three)
+- [BetaPageWithLongNameThatOverflowsBecauseItsOneWord](/empty-pages/empty-page-four)
diff --git a/websites/docs-smoke-test/src/content/empty-pages/overview.mdx b/websites/docs-smoke-test/src/content/empty-pages/overview.mdx
@@ -0,0 +1,10 @@
+---
+title: Empty pages
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [Page with some very long title too much for our innocent API to handle](/empty-pages/empty-page-one)
+- [Beta Page with some very long title too much for our innocent API to handle](/empty-pages/empty-page-two)
diff --git a/websites/docs-smoke-test/src/content/views/overview.mdx b/websites/docs-smoke-test/src/content/views/overview.mdx
@@ -0,0 +1,18 @@
+---
+title: Views
+showTimeToRead: false
+timeToRead: false
+---
+
+# Contents of this chapter
+
+- [Markdown](/views/markdown)
+- [Empty](/views/empty)
+- [Beta with long page title to see how the index nav behaves](/views/beta)
+- [Nested headings](/views/nested-headings)
+- [Two-level nav](/views/two-level-index-nav)
+- [Links](/views/links)
+- [Code blocks](/views/code-blocks)
+- [Code examples](/views/code-examples)
+- [Custom Anchor](/views/custom-anchor)
+- [Wide Layout](/views/wide)
diff --git a/websites/docs-smoke-test/src/data/navigation.yaml b/websites/docs-smoke-test/src/data/navigation.yaml
@@ -1,4 +1,5 @@
 - chapter-title: Views
+  path: /views/overview
   pages:
     - title: Markdown
       path: /views/markdown
@@ -21,6 +22,7 @@
     - title: Wide Layout
       path: /views/wide
 - chapter-title: Components
+  path: /components/overview
   beta: true
   pages:
     - title: Code blocks
@@ -42,13 +44,15 @@
     - title: Video Player
       path: /components/video-player
 - chapter-title: Chapter 9999 With a Longer Multi-Word Name that Wraps
+  path: /empty-pages/overview
   pages:
     - title: Page with some very long title too much for our innocent API to handle
       path: /empty-pages/empty-page-one
     - title: Beta Page with some very long title too much for our innocent API to handle
       path: /empty-pages/empty-page-two
       beta: true
 - chapter-title: ChapterWithLongNameThatOverflowsBecauseItsOneWord
+  path: /empty-pages/overview-1
   pages:
     - title: PageWithLongNameThatOverflowsBecauseItsOneWord
       path: /empty-pages/empty-page-three