Merge pull request #2915 from squidfunk/feature/scrollable-content-tabs

Prototype: scrollable content tabs

material/base.html

@@ -39,7 +39,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.8b42a75e.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.55b1b295.min.css' | url }}">
       {% if config.theme.palette %}
         {% set palette = config.theme.palette %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.3f5d1f46.min.css' | url }}">
@@ -225,7 +225,7 @@
       </script>
     {% endblock %}
     {% block scripts %}
-      <script src="{{ 'assets/javascripts/bundle.5e5cfff9.min.js' | url }}"></script>
+      <script src="{{ 'assets/javascripts/bundle.2248a2bd.min.js' | url }}"></script>
       {% for path in config["extra_javascript"] %}
         <script src="{{ path | url }}"></script>
       {% endfor %}

requirements.txt

@@ -22,5 +22,5 @@
 mkdocs>=1.2.2
 Pygments>=2.4
 markdown>=3.2
-pymdown-extensions>=7.0
+pymdown-extensions>=8.2
 mkdocs-material-extensions>=1.0

src/assets/javascripts/components/content/_/index.ts

@@ -28,6 +28,7 @@ import { Component } from "../../_"
 import { CodeBlock, mountCodeBlock } from "../code"
 import { Details, mountDetails } from "../details"
 import { DataTable, mountDataTable } from "../table"
+import { ContentTabs, mountContentTabs } from "../tabs"
 
 /* ----------------------------------------------------------------------------
  * Types
@@ -37,6 +38,7 @@ import { DataTable, mountDataTable } from "../table"
  * Content
  */
 export type Content =
+  | ContentTabs
   | CodeBlock
   | DataTable
   | Details
@@ -84,6 +86,10 @@ export function mountContent(
 
     /* Details */
     ...getElements("details", el)
-      .map(child => mountDetails(child, { target$, print$ }))
+      .map(child => mountDetails(child, { target$, print$ })),
+
+    /* Content tabs */
+    ...getElements("[data-tabs]", el)
+      .map(child => mountContentTabs(child))
   )
 }

src/assets/javascripts/components/content/index.ts

@@ -24,3 +24,4 @@ export * from "./_"
 export * from "./code"
 export * from "./details"
 export * from "./table"
+export * from "./tabs"

src/assets/javascripts/components/content/tabs/index.ts

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2016-2021 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import { NEVER, Observable, Subject, fromEvent, merge } from "rxjs"
+import { finalize, map, mapTo, tap } from "rxjs/operators"
+
+import { getElementOrThrow, getElements } from "~/browser"
+
+import { Component } from "../../_"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Content tabs
+ */
+export interface ContentTabs {
+  active: HTMLLabelElement             /* Active tab label */
+}
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Watch content tabs
+ *
+ * @param el - Content tabs element
+ *
+ * @returns Content tabs observable
+ */
+export function watchContentTabs(
+  el: HTMLElement
+): Observable<ContentTabs> {
+  if (!el.classList.contains(".tabbed-alternate"))
+    return NEVER
+  else
+    return merge(...getElements(":scope > input", el)
+      .map(input => fromEvent(input, "change").pipe(mapTo(input.id)))
+    )
+      .pipe(
+        map(id => ({
+          active: getElementOrThrow<HTMLLabelElement>(`label[for=${id}]`)
+        }))
+      )
+}
+
+/**
+ * Mount content tabs
+ *
+ * @param el - Content tabs element
+ *
+ * @returns Content tabs component observable
+ */
+export function mountContentTabs(
+  el: HTMLElement
+): Observable<Component<ContentTabs>> {
+  const internal$ = new Subject<ContentTabs>()
+  internal$.subscribe(({ active }) => {
+    active.scrollIntoView({ behavior: "smooth",  block: "nearest" })
+  })
+
+  /* Create and return component */
+  return watchContentTabs(el)
+    .pipe(
+      tap(state => internal$.next(state)),
+      finalize(() => internal$.complete()),
+      map(state => ({ ref: el, ...state }))
+    )
+}

src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss

@@ -21,13 +21,13 @@
 ////
 
 // ----------------------------------------------------------------------------
-// Rules
+// Rules: legacy implementation (deprecated, removed in v8)
 // ----------------------------------------------------------------------------
 
 // Scoped in typesetted content to match specificity of regular content
 .md-typeset {
 
-  // Tabbed block content
+  // Tabbed content
   .tabbed-content {
     display: none;
     order: 99;
@@ -60,7 +60,7 @@
     }
   }
 
-  // Tabbed block container
+  // Tabbed container
   .tabbed-set {
     position: relative;
     display: flex;
@@ -121,3 +121,181 @@
     }
   }
 }
+
+// ----------------------------------------------------------------------------
+// Placeholders: improve colocation for better compression
+// ----------------------------------------------------------------------------
+
+// Tab label placeholder
+%tabbed-label {
+
+  // [screen]: Show active state
+  @media screen {
+    color: var(--md-accent-fg-color);
+    border-color: var(--md-accent-fg-color);
+  }
+}
+
+// Tab label on keyboard focus placeholder
+%tabbed-label-focus-visible {
+  background-color: var(--md-accent-fg-color--transparent);
+}
+
+// Tab content placeholder
+%tabbed-content {
+  display: block;
+}
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Scoped in typesetted content to match specificity of regular content
+.md-typeset { // stylelint-disable-line
+
+  // Tabbed labels
+  .tabbed-labels {
+    display: flex;
+    max-width: 100vw;
+    overflow: auto;
+    box-shadow: 0 px2rem(-1px) var(--md-default-fg-color--lightest) inset;
+    scroll-snap-type: x proximity;
+    -ms-overflow-style: none;          // IE, Edge
+    scrollbar-width: none;             // Firefox
+
+    // [print]: Move one layer up for ordering
+    @media print {
+      display: contents;
+    }
+
+    // Webkit scrollbar
+    &::-webkit-scrollbar {
+      display: none;                   // Chrome, Safari
+    }
+
+    // Tab label
+    > label {
+      z-index: 1;
+      width: auto;
+      padding: px2em(12px, 12.8px) 1.25em px2em(10px, 12.8px);
+      color: var(--md-default-fg-color--light);
+      font-weight: 700;
+      font-size: px2rem(12.8px);
+      white-space: nowrap;
+      border-bottom: px2rem(2px) solid transparent;
+      scroll-snap-align: start;
+      border-top-left-radius: px2rem(2px);
+      border-top-right-radius: px2rem(2px);
+      cursor: pointer;
+      transition:
+        background-color 250ms,
+        color            250ms;
+
+      // [print]: Intersperse labels with containers
+      @media print {
+
+        // Ensure correct order of labels
+        @for $i from 1 through 10 {
+          &:nth-child(#{$i}) {
+            order: $i;
+          }
+        }
+      }
+
+      // Tab label on hover
+      &:hover {
+        color: var(--md-accent-fg-color);
+      }
+    }
+  }
+
+  // [mobile -]: Align with body copy
+  @include break-to-device(mobile) {
+
+    // Top-level tabbed labels
+    > .tabbed-alternate .tabbed-labels {
+      margin: 0 px2rem(-16px);
+      padding: 0 px2rem(16px);
+      scroll-padding: 0 px2rem(16px);
+    }
+  }
+
+  // Tabbed container
+  .tabbed-alternate {
+    flex-direction: column;
+
+    // Tabbed content
+    .tabbed-content {
+      display: initial;
+      order: initial;
+      width: 100%;
+      box-shadow: initial;
+
+      // [print]: Move one layer up for ordering
+      @media print {
+        display: contents;
+      }
+    }
+
+    // Tabbed block
+    .tabbed-block {
+      display: none;
+
+      // [print]: Intersperse labels with containers
+      @media print {
+        display: block;
+
+        // Ensure correct order of containers
+        @for $i from 1 through 10 {
+          &:nth-child(#{$i}) {
+            order: $i;
+          }
+        }
+      }
+
+      // Code block is the only child of a tab - remove margin and mirror
+      // previous (now deprecated) SuperFences code block grouping behavior
+      > pre:only-child,
+      > .highlight:only-child pre,
+      > .highlighttable:only-child {
+        margin: 0;
+
+        // Omit rounded borders
+        > code {
+          border-top-left-radius: 0;
+          border-top-right-radius: 0;
+        }
+      }
+
+      // Adjust spacing for nested tabbed container
+      > .tabbed-set {
+        margin: 0;
+      }
+    }
+
+    // Tab label states
+    @for $i from 10 through 1 {
+      input:nth-child(#{$i}) {
+
+        // Tab is active
+        &:checked {
+
+          // Tab label
+          ~ .tabbed-labels > :nth-child(#{$i}) {
+            @extend %tabbed-label;
+          }
+
+          // Tab content
+          ~ .tabbed-content > :nth-child(#{$i}) {
+            @extend %tabbed-content;
+          }
+        }
+
+        // Tab label on keyboard focus
+        &.focus-visible ~ .tabbed-labels > :nth-child(#{$i}) {
+          @extend %tabbed-label-focus-visible;
+        }
+      }
+    }
+  }
+}