docs: improve layout

packages/docs/src/components/ComponentSubNav.tsx

@@ -0,0 +1,116 @@
+import React, { forwardRef, HTMLAttributes, useMemo, useRef } from 'react'
+import { Link } from 'gatsby'
+import { CContainer, CNav, CNavItem, CNavLink } from '@coreui/react'
+import useStickyObserver from '../hooks/useStickyObserver' // Adjust the path as needed
+
+type Fields = {
+  slug: string
+}
+
+type Node = {
+  id: string
+  fields: Fields
+}
+
+export interface Item {
+  node: Node
+}
+
+export interface ComponentSubNavProps extends HTMLAttributes<HTMLDivElement> {
+  nodes: Item[]
+}
+
+const findShortestSlug = (items: Item[]): string | undefined => {
+  if (items.length === 0) {
+    return undefined
+  }
+
+  let shortestSlug = items[0].node.fields.slug
+
+  for (const item of items) {
+    const currentSlug = item.node.fields.slug
+    if (currentSlug.length < shortestSlug.length) {
+      shortestSlug = currentSlug
+    }
+  }
+
+  return shortestSlug
+}
+
+const ComponentSubNav = forwardRef<HTMLDivElement, ComponentSubNavProps>(
+  ({ nodes, ...rest }, ref) => {
+    const parentPathname = findShortestSlug(nodes)
+    const hasNavAccessibility = useMemo(
+      () => nodes.some((edge) => edge.node.fields.slug.includes('accessibility')),
+      [nodes],
+    )
+    const hasNavAPI = useMemo(
+      () => nodes.some((edge) => edge.node.fields.slug.includes('api')),
+      [nodes],
+    )
+    const hasNavStyling = useMemo(
+      () => nodes.some((edge) => edge.node.fields.slug.includes('styling')),
+      [nodes],
+    )
+
+    // Ref for the sentinel element
+    const sentinelRef = useRef<HTMLDivElement>(null)
+
+    // Use the custom hook to track sticky state
+    const isSticky = useStickyObserver(sentinelRef)
+
+    return (
+      <>
+        <div ref={sentinelRef} style={{ height: '1px' }} />
+        <div
+          className={`component-sub-nav-wrapper bg-body position-sticky z-3 ${isSticky ? 'sticky shadow-sm' : ''}`}
+          ref={ref}
+          {...rest}
+        >
+          <CContainer lg className="px-3 px-sm-4">
+            <CNav
+              className="docs-nav component-sub-nav"
+              variant="underline-border"
+              role={undefined}
+            >
+              <CNavItem>
+                <CNavLink as={Link} to={parentPathname} activeClassName="active">
+                  Features
+                </CNavLink>
+              </CNavItem>
+              {hasNavAPI && (
+                <CNavItem>
+                  <CNavLink as={Link} to={`${parentPathname}api/`} activeClassName="active">
+                    API
+                  </CNavLink>
+                </CNavItem>
+              )}
+              {hasNavStyling && (
+                <CNavItem>
+                  <CNavLink as={Link} to={`${parentPathname}styling/`} activeClassName="active">
+                    Styling
+                  </CNavLink>
+                </CNavItem>
+              )}
+              {hasNavAccessibility && (
+                <CNavItem>
+                  <CNavLink
+                    as={Link}
+                    to={`${parentPathname}accessibility/`}
+                    activeClassName="active"
+                  >
+                    Accessibility
+                  </CNavLink>
+                </CNavItem>
+              )}
+            </CNav>
+          </CContainer>
+        </div>
+      </>
+    )
+  },
+)
+
+ComponentSubNav.displayName = 'ComponentSubNav'
+
+export default ComponentSubNav

packages/docs/src/components/ExampleSnippet.tsx

@@ -122,7 +122,7 @@ const ExampleSnippet: FC<ExampleSnippetProps> = ({
         )}
       </div>
       <div className="highlight-toolbar border-top">
-        <CNav className="px-3" variant="underline-border">
+        <CNav as="div" className="px-3" variant="underline-border" role={undefined}>
           {showJSTab && (
             <CNavLink as="button" active={language === 'js'} onClick={() => setLanguage('js')}>
               JavaScript

packages/docs/src/components/Footer.tsx

@@ -7,30 +7,21 @@ import pkg from './../../package.json'
 
 const Footer: FC = () => {
   return (
-    <CFooter className="docs-footer p-3 p-md-5 mt-5 text-center text-sm-start">
-      <CContainer>
-        <ul className="docs-footer-links ps-0 mb-3">
-          <li className="d-inline-block">
-            <a href="https://github.com/coreui">GitHub</a>
-          </li>
-          <li className="d-inline-block ms-3">
-            <a href="https://twitter.com/core_ui">Twitter</a>
-          </li>
-          <li className="d-inline-block ms-3 ps-3 border-start border-2">
-            <a href="https://coreui.io/">CoreUI (Vanilla)</a>
-          </li>
-          <li className="d-inline-block ms-3">
-            <a href="https://coreui.io/angular/">CoreUI for Angular</a>
-          </li>
-          <li className="d-inline-block ms-3">
-            <a href="https://coreui.io/vue/">CoreUI for Vue.js</a>
-          </li>
-        </ul>
+    <CFooter className="docs-footer py-md-5 mt-5 text-center text-sm-start">
+      <CContainer lg className="px-4">
+        <div className="docs-footer-links mb-3 d-flex flex-column flex-sm-row gap-3">
+          <a href="https://github.com/coreui">GitHub</a>
+          <a href="https://twitter.com/core_ui">Twitter</a>
+          <span className="border-start border-start-2 d-none d-sm-flex"></span>
+          <a href="https://coreui.io/bootstrap/">CoreUI (Vanilla)</a>
+          <a href="https://coreui.io/angular/">CoreUI for Angular</a>
+          <a href="https://coreui.io/vue/">CoreUI for Vue.js</a>
+        </div>
         <p className="mb-0">CoreUI for React is Open Source UI Components Library for React.js.</p>
         <p className="mb-0">
           Currently v{pkg.version}. CoreUI code licensed{' '}
           <a
-            href="https://github.com/coreui/coreui/blob/main/LICENSE"
+            href="https://github.com/coreui/coreui-react/blob/main/LICENSE"
             target="_blank"
             rel="noreferrer"
           >

packages/docs/src/components/Header.tsx

@@ -1,4 +1,4 @@
-import React, { FC } from 'react'
+import React, { forwardRef } from 'react'
 import { DocSearch } from '@docsearch/react'
 
 import CIcon from '@coreui/icons-react'
@@ -28,13 +28,13 @@ import {
 } from '@coreui/react/src'
 import { AppContext } from './../AppContext'
 
-const Header: FC = () => {
+const Header = forwardRef<HTMLDivElement>(({}, ref) => {
   const { colorMode, setColorMode } = useColorModes('coreui-react-docs-theme')
   return (
     <>
       <AppContext.Consumer>
         {(context) => (
-          <CHeader className="mb-5" position="sticky">
+          <CHeader className="mb-5" position="sticky" ref={ref}>
             <CHeaderToggler
               className="ms-md-3"
               aria-label="Close"
@@ -49,8 +49,7 @@ const Header: FC = () => {
               indexName="coreui-react"
               apiKey="6e3f7692d2589d042bb40426b75df1b7"
             />
-            {/* <div className="docs-search" id="docsearch"></div> */}
-            <CHeaderNav className="ms-auto">
+            <CHeaderNav className="ms-auto" role={undefined}>
               <CNavItem
                 href="https://github.com/coreui/coreui-react/"
                 aria-label="Visit our GitHub"
@@ -70,9 +69,8 @@ const Header: FC = () => {
                 <div className="vr d-none d-lg-flex h-100 mx-lg-2 text-body text-opacity-75"></div>
                 <hr className="d-lg-none my-2 text-white-50" />
               </li>
-              <CDropdown placement="bottom-end">
+              <CDropdown placement="bottom-end" variant="nav-item">
                 <CDropdownToggle
-                  className="nav-link"
                   color="link"
                   caret={false}
                   aria-label="Light/Dark mode switch"
@@ -148,7 +146,7 @@ const Header: FC = () => {
       </AppContext.Consumer>
     </>
   )
-}
+})
 
 Header.displayName = 'Header'
 

packages/docs/src/components/Sidebar.tsx

@@ -1,4 +1,5 @@
 import React, { FC } from 'react'
+import { Link } from 'gatsby'
 
 import {
   CDropdown,
@@ -27,7 +28,12 @@ const Sidebar: FC = () => {
             context.setSidebarVisible && context.setSidebarVisible(value)
           }
         >
-          <CSidebarBrand className="justify-content-start ps-3">
+          <CSidebarBrand
+            as={Link}
+            className="justify-content-start ps-3"
+            to="/"
+            aria-label="Go to CoreUI for React.js documentation"
+          >
             <svg
               xmlns="http://www.w3.org/2000/svg"
               viewBox="0 0 615 134"

packages/docs/src/components/Toc.tsx

@@ -1,4 +1,4 @@
-import React, { FC, useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 import { CCollapse, CNav } from '@coreui/react/src/index'
 
 export type TocItem = {
@@ -32,12 +32,16 @@ const toc = (items: TocItem[]) => {
   )
 }
 
-const Toc: FC<TocProps> = ({ items }) => {
+const Toc = forwardRef<HTMLDivElement, TocProps>(({ items, ...rest }, ref) => {
   const [visible, setVisible] = useState(false)
   return (
-    <div className="docs-toc mt-4 mb-5 my-md-0 ps-xl-5 mb-lg-5 text-body-secondary">
+    <div
+      className="docs-toc mt-4 mb-5 my-lg-0 ps-xl-5 mb-lg-5 text-body-secondary"
+      ref={ref}
+      {...rest}
+    >
       <button
-        className="btn btn-link p-md-0 mb-2 mb-md-0 text-decoration-none docs-toc-toggle d-md-none"
+        className="btn btn-link p-lg-0 mb-2 mb-lg-0 text-decoration-none docs-toc-toggle d-lg-none"
         type="button"
         aria-expanded={visible ? true : false}
         aria-controls="tocContents"
@@ -46,7 +50,7 @@ const Toc: FC<TocProps> = ({ items }) => {
         On this page
         <svg
           xmlns="http://www.w3.org/2000/svg"
-          className="icon d-md-none ms-2"
+          className="icon d-lg-none ms-2"
           aria-hidden="true"
           viewBox="0 0 512 512"
         >
@@ -57,14 +61,16 @@ const Toc: FC<TocProps> = ({ items }) => {
           />
         </svg>
       </button>
-      <strong className="d-none d-md-block h6 mb-2 pb-2 border-bottom">On this page</strong>
+      <strong className="d-none d-lg-block h6 mb-2 pb-2 border-bottom">On this page</strong>
       <CCollapse className="docs-toc-collapse" id="tocContents" visible={visible}>
         <CNav as="nav">
           <ul>{toc(items)}</ul>
         </CNav>
       </CCollapse>
     </div>
   )
-}
+})
+
+Toc.displayName = 'Toc'
 
 export default Toc

packages/docs/src/components/index.ts

@@ -3,6 +3,7 @@ import Banner from './Banner'
 import Callout from './Callout'
 import CodeBlock from './CodeBlock'
 import ClassNamesDocs from './ClassNamesDocs'
+import ComponentSubNav from './ComponentSubNav'
 import Example from './Example'
 import ExampleSnippet from './ExampleSnippet'
 import Footer from './Footer'
@@ -20,6 +21,7 @@ export {
   Callout,
   CodeBlock,
   ClassNamesDocs,
+  ComponentSubNav,
   Example,
   ExampleSnippet,
   Footer,

packages/docs/src/hooks/useStickyObserver.ts

@@ -0,0 +1,36 @@
+import { useEffect, useState, RefObject } from 'react'
+
+const useStickyObserver = (
+  sentinelRef: RefObject<HTMLElement>,
+  options?: IntersectionObserverInit,
+): boolean => {
+  const [isSticky, setIsSticky] = useState(false)
+
+  useEffect(() => {
+    const sentinel = sentinelRef.current
+    if (!sentinel) return
+
+    const observerOptions = options || {
+      root: null,
+      rootMargin: '0px',
+      threshold: 0,
+    }
+
+    const observerCallback: IntersectionObserverCallback = (entries) => {
+      entries.forEach((entry) => {
+        setIsSticky(!entry.isIntersecting)
+      })
+    }
+
+    const observer = new IntersectionObserver(observerCallback, observerOptions)
+    observer.observe(sentinel)
+
+    return () => {
+      observer.unobserve(sentinel)
+    }
+  }, [sentinelRef, options])
+
+  return isSticky
+}
+
+export default useStickyObserver

packages/docs/src/styles/_component-sub-nav.scss

@@ -0,0 +1,36 @@
+.component-sub-nav-wrapper {
+  @include transition(box-shadow 0.2s linear);
+  &:before {
+    position: absolute;
+    z-index: -1;
+    content: '';
+    right: 0;
+    bottom: 0;
+    left: 0;
+    height: 2px;
+    width: 90%;
+    max-width: 1140px;
+    margin: 0 auto;
+    background: var(--cui-border-color);
+    @include transition(max-width .2s ease-in-out, width .2s ease-in-out);
+  }
+
+  .component-sub-nav {
+    .nav-link {
+      @include transition(padding .2s linear);
+    }
+  }
+
+  &.sticky {
+    &::before {
+      width: 100%;
+      max-width: 100%;
+    }
+
+    .component-sub-nav {
+      .nav-link {
+        --cui-nav-underline-border-link-padding-y: .75rem;
+      }
+    }
+  }
+}

packages/docs/src/styles/_footer.scss

@@ -7,13 +7,12 @@
   @include font-size(.875rem);
 
   a {
-    color: var(--#{$prefix}tertiary-color);
-    text-decoration: none;
+    color: var(--#{$prefix}secondary-color);
+    // text-decoration: none;
 
     &:hover,
     &:focus {
       color: var(--cui-link-hover-color);
-      text-decoration: underline;
     }
   }
 }