trigger scrolling when toc item is outside the viewport (#3394)

* trigger scrolling when toc item is outside the viewport

* fixes to make it looks even better

* fixes

---------

Co-authored-by: Dimitri POSTOLOV <[email protected]>

Author: 87xie

.changeset/neat-onions-unite.md

@@ -0,0 +1,5 @@
+---
+'nextra-theme-docs': patch
+---
+
+trigger scrolling when the TOC item is outside the viewport

docs/pages/docs/docs-theme/theme-configuration.mdx

@@ -637,10 +637,11 @@ Options to configure the language dropdown for
 
 <Table>
 
-|                     |          |                                                        |
-| ------------------- | -------- | ------------------------------------------------------ |
-| i18n[number].locale | `string` | Locale from `i18n.locales` field in `next.config` file |
-| i18n[number].name   | `string` | Locale name in dropdown                                |
+|                        |                  |                                                        |
+| ---------------------- | ---------------- | ------------------------------------------------------ |
+| i18n[number].locale    | `string`         | Locale from `i18n.locales` field in `next.config` file |
+| i18n[number].name      | `string`         | Locale name in dropdown                                |
+| i18n[number].direction | `'ltl' \| 'rtl'` | Locale writing direction. Default: `ltr`               |
 
 </Table>
 

packages/nextra-theme-docs/css/styles.css

@@ -136,7 +136,6 @@ body {
 
 body,
 .nextra-nav-container-blur,
-.nextra-toc-footer,
 .nextra-sidebar-footer {
   @apply _bg-[rgb(var(--nextra-bg))];
 }

packages/nextra-theme-docs/src/components/back-to-top.tsx

@@ -35,6 +35,7 @@ export function BackToTop({
       className={({ disabled }) =>
         cn(
           '_flex _items-center _gap-1.5',
+          '_whitespace-nowrap', // Safari
           disabled ? '_opacity-0' : '_opacity-100',
           className
         )

packages/nextra-theme-docs/src/components/toc.tsx

@@ -48,25 +48,38 @@ export function TOC({ toc, filePath }: TOCProps): ReactElement {
         behavior: 'smooth',
         block: 'center',
         inline: 'center',
-        scrollMode: 'always',
-        boundary: tocRef.current!.parentElement
+        scrollMode: 'if-needed',
+        boundary: tocRef.current
       })
     }
   }, [activeSlug])
 
   return (
     <div
       className={cn(
-        'nextra-scrollbar _sticky _top-16 _overflow-y-auto _px-4 _pt-6 _text-sm [hyphens:auto]',
-        '_max-h-[calc(100vh-var(--nextra-navbar-height)-env(safe-area-inset-bottom))]'
+        hasHeadings && '_grid _grid-rows-[min-content_1fr_min-content]', // 1fr: toc headings, min-content: title/footer
+        '_sticky _top-[--nextra-navbar-height] _pt-6 _text-sm',
+        '_max-h-[calc(100vh-var(--nextra-navbar-height))]'
       )}
     >
       {hasHeadings && (
         <>
-          <p className="_mb-4 _font-semibold _tracking-tight">
+          <p
+            className={cn(
+              '_mx-4', // use margin instead padding to not have shadow on scrollbar
+              '_font-semibold _tracking-tight',
+              '_pb-2 _shadow-[0_12px_16px_rgb(var(--nextra-bg))] contrast-more:_shadow-none _z-[1]'
+            )}
+          >
             {renderComponent(themeConfig.toc.title)}
           </p>
-          <ul ref={tocRef}>
+          <ul
+            ref={tocRef}
+            className={cn(
+              '_px-4 nextra-scrollbar _overscroll-y-contain _overflow-y-auto _hyphens-auto',
+              '_py-1.5' // for title/footer shadow
+            )}
+          >
             {toc.map(({ id, value, depth }) => (
               <li className="_my-2 _scroll-my-6 _scroll-py-6" key={id}>
                 <a
@@ -75,10 +88,10 @@ export function TOC({ toc, filePath }: TOCProps): ReactElement {
                     'nextra-focus',
                     {
                       2: '_font-semibold',
-                      3: 'ltr:_ml-4 rtl:_mr-4',
-                      4: 'ltr:_ml-8 rtl:_mr-8',
-                      5: 'ltr:_ml-12 rtl:_mr-12',
-                      6: 'ltr:_ml-16 rtl:_mr-16'
+                      3: '_ms-4',
+                      4: '_ms-8',
+                      5: '_ms-12',
+                      6: '_ms-16'
                     }[depth],
                     '_block _transition-colors _subpixel-antialiased',
                     activeAnchor[id]?.isActive
@@ -98,9 +111,9 @@ export function TOC({ toc, filePath }: TOCProps): ReactElement {
       {hasMetaInfo && (
         <div
           className={cn(
-            hasHeadings && 'nextra-toc-footer _mt-8 _pt-8',
-            '_sticky _bottom-0 _flex _flex-col _items-start _gap-2 _pb-8',
-            '_-mx-1 _px-1' // to hide focused toc links
+            hasHeadings && 'nextra-toc-footer _pt-4',
+            '_flex _flex-col _items-start _gap-2 _pb-4',
+            '_mx-4' // for border top width
           )}
         >
           {themeConfig.feedback.content ? (

packages/nextra/styles/scrollbar.css

@@ -1,27 +1,24 @@
 .nextra-scrollbar {
   scrollbar-width: thin; /* Firefox */
-  scrollbar-color: oklch(55.55% 0 0 / 40%) transparent; /* Firefox */
-
+  scrollbar-color: rgba(115, 115, 115, 0.4) transparent; /* Firefox */
   scrollbar-gutter: stable;
+
   &::-webkit-scrollbar {
     @apply _size-3;
   }
+
   &::-webkit-scrollbar-track {
     @apply _bg-transparent;
   }
+
   &::-webkit-scrollbar-thumb {
     @apply _rounded-[10px];
-  }
-  &:hover::-webkit-scrollbar-thumb {
-    border: 3px solid transparent;
-    background-color: var(--tw-shadow-color);
-    background-clip: content-box;
-    @apply _shadow-neutral-500/20 hover:_shadow-neutral-500/40;
-  }
 
-  @media (max-width: 767px) {
-    .nextra-container & {
-      scrollbar-gutter: auto;
+    &:hover {
+      border: 3px solid transparent;
+      background-color: var(--tw-shadow-color);
+      background-clip: content-box;
+      @apply _shadow-neutral-500/20 hover:_shadow-neutral-500/40;
     }
   }
 }