@brillout/docpress 0.5.39 → 0.5.40-commit-51be4fa

package/markdownHeadingsVitePlugin.ts

@@ -0,0 +1,150 @@
+export { markdownHeadingsVitePlugin }
+export type { MarkdownHeading }
+
+import { assert } from './utils/assert.js'
+import { determineSectionUrlHash } from './utils/determineSectionUrlHash.js'
+import os from 'os'
+
+type MarkdownHeading = {
+  title: string
+  headingId: string | null
+  headingLevel: number
+  titleAddendum?: string
+}
+
+function markdownHeadingsVitePlugin() {
+  return {
+    name: 'mdx-headings',
+    enforce: 'pre',
+    transform: async (code: string, id: string) => {
+      if (!id.endsWith('+Page.mdx')) {
+        return
+      }
+      const codeNew = transform(code)
+      return codeNew
+    }
+  }
+}
+
+function transform(code: string) {
+  const headings: MarkdownHeading[] = []
+  let isCodeBlock = false
+  let codeNew = code
+    .split('\n')
+    .map((line) => {
+      // Skip code blocks, e.g.
+      // ~~~md
+      // # Markdown Example
+      // Bla
+      // ~~~
+      if (line.startsWith('~~~') || line.startsWith('```')) {
+        isCodeBlock = !isCodeBlock
+        return line
+      }
+      if (isCodeBlock) {
+        return line
+      }
+
+      if (line.startsWith('#')) {
+        const { headingId, headingLevel, title, headingHtml } = parseMarkdownHeading(line)
+        headings.push({ headingId, headingLevel, title })
+        return headingHtml
+      }
+
+      return line
+    })
+    .join('\n')
+  const headingsExportCode = `export const headings = [${headings
+    .map((heading) => JSON.stringify(heading))
+    .join(', ')}];`
+  codeNew += `\n\n${headingsExportCode}\n`
+  return codeNew
+}
+
+function parseMarkdownHeading(line: string): MarkdownHeading & { headingHtml: string } {
+  const [lineBegin, ...lineWords] = line.split(' ')
+  assert(lineBegin.split('#').join('') === '', { line, lineWords })
+  const headingLevel = lineBegin.length
+
+  const titleMdx = lineWords.join(' ')
+  assert(!titleMdx.startsWith(' '), { line, lineWords })
+  assert(titleMdx, { line, lineWords })
+
+  const headingMdx = {
+    title: titleMdx,
+    anchor: titleMdx
+  }
+  {
+    // Support custom anchor like: `## title{#custom-anchor}`
+    const customAnchor = /(?<={#).*(?=})/g.exec(titleMdx)?.[0]
+    if (customAnchor) {
+      headingMdx.anchor = customAnchor
+      headingMdx.title = titleMdx.replace(/{#.*}/g, '')
+    }
+  }
+  const headingId = determineSectionUrlHash(headingMdx.anchor)
+  const title = headingMdx.title
+
+  const titleParsed = parseTitle(title)
+  assert(headingId === null || headingId.length > 0)
+  const headingAttrId = headingId === null ? '' : ` id="${headingId}"`
+  const headingHtml = `<h${headingLevel}${headingAttrId}>${titleParsed}</h${headingLevel}>`
+
+  const heading = { headingLevel, title, headingId, headingHtml }
+  return heading
+}
+
+function parseTitle(titleMarkdown: string): string {
+  type Part = { nodeType: 'text' | 'code'; content: string }
+  const parts: Part[] = []
+  let current: Part | undefined
+  titleMarkdown.split('').forEach((letter) => {
+    if (letter === '`') {
+      if (current?.nodeType === 'code') {
+        // </code>
+        parts.push(current)
+        current = undefined
+      } else {
+        // <code>
+        if (current) {
+          parts.push(current)
+        }
+        current = { nodeType: 'code', content: '' }
+      }
+    } else {
+      if (!current) {
+        current = { nodeType: 'text', content: '' }
+      }
+      current.content += letter
+    }
+  })
+  if (current) {
+    parts.push(current)
+  }
+
+  const titleHtml = parts
+    .map((part) => {
+      if (part.nodeType === 'code') {
+        return `<code>${serializeText(part.content)}</code>`
+      } else {
+        assert(part.nodeType === 'text', { parts })
+        return serializeText(part.content)
+      }
+    })
+    .join('')
+
+  return titleHtml
+
+  function serializeText(text: string) {
+    let textEscaped = text.split("'").join("\\'")
+    // https://github.com/brillout/docpress/pull/2
+    if (isWindows()) {
+      textEscaped = textEscaped.replace(/\r/, '')
+    }
+    return `{'${textEscaped}'}`
+  }
+}
+
+function isWindows() {
+  return os.platform() === 'win32'
+}

package/navigation/Navigation-highlight.css

@@ -0,0 +1,41 @@
+/*
+.nav-item {
+  border-top: 1px solid transparent;
+}
+.nav-item.is-active {
+  border-color: #eaeaea;
+}
+.nav-item[is-active] {
+  background-color: attr(is-active)
+}
+*/
+
+/*
+#navigation-container:not(:hover) ::-webkit-scrollbar {
+  display: none;
+}
+#navigation-container ::-webkit-scrollbar-thumb {
+  opacity: 0;
+}
+#navigation-container ::-webkit-scrollbar-track {
+  opacity: 0;
+}
+*/
+
+/*
+.nav-tree:not(.expanded) > .nav-tree {
+  edisplay: none;
+  background:red;
+}
+  */
+/*
+.nav-tree.expanded,
+.nav-tree.expanded > .nav-tree {
+  display: inherit;
+}
+.nav-tree.expanded,
+.nav-tree.expanded > .nav-tree {
+  display: inherit;
+  background:red;
+}
+*/

package/navigation/Navigation-items.css

@@ -0,0 +1,119 @@
+.nav-item {
+  display: block;
+  white-space: nowrap;
+  overflow-x: hidden;
+  --padding-left-global: 9px;
+  --padding-left-additional: 0px;
+}
+.nav-item code {
+  font-size: 0.9em;
+}
+.nav-item-h1 + .nav-item-h4 {
+  margin-top: -2px;
+}
+.nav-item-h4 {
+  margin-top: 14px;
+  margin-bottom: -1px;
+  color: #999;
+  font-size: 12px;
+  font-weight: 400;
+  letter-spacing: 0.15ch;
+  padding-left: var(--padding-left-global);
+  padding-right: 4px;
+  text-decoration: none;
+}
+.nav-column:first-of-type > .nav-h1-group:first-of-type > .nav-item-h1:first-of-type {
+  margin-top: 20px;
+}
+.nav-item-h1 {
+  margin-top: 30px;
+  font-size: 15.4px;
+  text-transform: uppercase;
+  font-weight: 600;
+  letter-spacing: 0.15ch;
+  color: var(--color-text);
+  padding: 12px 0;
+  padding-left: calc(var(--padding-left-global) - 2px);
+  padding-right: 4px;
+  text-decoration: none;
+}
+.nav-item-h2 {
+  text-decoration: none;
+  font-size: 14.4px;
+  font-weight: 400;
+  letter-spacing: 0.15ch;
+  color: var(--color-text);
+  padding-left: var(--padding-left-global);
+  padding-right: 0;
+  --padding: 4px;
+  padding-top: var(--padding);
+  padding-bottom: var(--padding);
+}
+.nav-item-h3 {
+  font-size: 12px;
+  font-weight: 400;
+  letter-spacing: 0.15ch;
+  color: var(--color-text);
+  text-decoration: none;
+  --padding: 5px;
+
+  background-color: #f9f9f9;
+  padding: var(--padding) 0;
+  padding-left: calc(var(--padding-left-global) + var(--padding-left-additional));
+}
+html.navigation-fullscreen .nav-item-h3 {
+  border-right: 4px solid #eee;
+}
+.nav-item-h3.nav-item-first-of-its-kind {
+  padding-top: calc(var(--padding) * 1.6);
+}
+.nav-item-h3.nav-item-last-of-its-kind {
+  padding-bottom: calc(var(--padding) * 2);
+}
+.nav-item-h2,
+.nav-item-h3 {
+  position: relative;
+}
+/*
+.nav-item-h2.is-active .nav-item-text{
+  background-color: var(--background-color);
+}
+*/
+.nav-item-h2.is-active {
+  background-color: var(--background-color);
+}
+.nav-item-h3.is-active:before {
+  display: block;
+  content: '';
+  position: absolute;
+  width: 4px;
+  left: 0;
+  top: 0;
+  height: 100%;
+  background-color: var(--background-color);
+  z-index: 10;
+}
+.nav-item-h3.is-active-last:after {
+  display: block;
+  content: '';
+  position: absolute;
+  height: 4px;
+  left: 0;
+  bottom: 0;
+  width: 100%;
+  background-color: var(--background-color);
+  z-index: 10;
+  border-bottom-left-radius: 5px;
+}
+html.navigation-fullscreen .nav-item {
+  --expend-border-radius: 5px;
+}
+.nav-item.is-active-first {
+  border-top-left-radius: 5px;
+  border-top-right-radius: var(--expend-border-radius);
+}
+.nav-item.is-active-last,
+.nav-item.is-active-last:before {
+  border-bottom-left-radius: 5px;
+  border-bottom-right-radius: var(--expend-border-radius);
+}

package/navigation/Navigation-layout.css

@@ -0,0 +1,127 @@
+:root {
+  --mobile-header-height: 60px;
+  --navigation-min-width: 300px;
+  --navigation-max-width: 350px;
+}
+#navigation-wrapper {
+  min-width: var(--navigation-min-width);
+}
+.doc-page #navigation-wrapper {
+  max-width: var(--navigation-max-width);
+}
+.landing-page #navigation-wrapper {
+  /* prettier-ignore */
+  max-width: min(var(--navigation-max-width), max(var(--navigation-min-width), calc(var(--navigation-min-width) + 100% - 1240px)));
+}
+#navigation-container {
+  /* `position: fixed` doesn't inherit the parent's width */
+  position: sticky;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  border-right: 1px solid #eee;
+  --background-color: #f0f0f0;
+  padding-bottom: 70px;
+}
+.navigation-content {
+  margin-top: 20px;
+}
+#navigation-content-detached {
+  margin-top: 25px;
+}
+
+#navigation-mask {
+  position: fixed;
+  width: 100%;
+  height: 100vh;
+  top: 0;
+  left: 0;
+  z-index: 2;
+}
+/* `1140px` is the breaking point that preserves the width of code blocks. */
+/* BEFORE EDITING THIS: also change the `1139px` value below */
+@media screen and (min-width: 1140px) {
+  #mobile-header {
+    display: none !important;
+  }
+  #navigation-container {
+    height: 100vh;
+    top: 0;
+  }
+  #navigation-mask {
+    display: none;
+  }
+}
+#navigation-container {
+  transition: transform 0.25s ease;
+  background: white;
+  z-index: 3;
+}
+#page-wrapper {
+  margin-left: calc(-1 * var(--navigation-fullscreen-button-width));
+}
+@media screen and (max-width: 1139px) {
+  #navigation-header-logo {
+    display: none !important;
+  }
+  #navigation-wrapper {
+    min-width: 0px !important;
+    max-width: 0px !important;
+  }
+  #navigation-fullscreen-button {
+    display: none;
+  }
+  #page-wrapper {
+    margin-left: 0 !important;
+  }
+  #navigation-container {
+    --width: min(100%, 350px);
+    width: var(--width);
+    left: 0;
+    height: calc(100vh - var(--mobile-header-height));
+    top: var(--mobile-header-height);
+    padding-top: 20px;
+    /* `position: sticky` doesn't seem to work on mobile */
+    position: fixed;
+  }
+  body:not(.show-menu) #navigation-container {
+    transform: translateX(calc(-1 * var(--width)));
+  }
+  body:not(.show-menu) #navigation-mask {
+    display: none;
+  }
+  #mobile-header {
+    display: inherit;
+  }
+  .doc-page h2 {
+    --padding-top: calc(var(--mobile-header-height) + 12px) !important;
+  }
+}
+
+html.navigation-fullscreen #navigation-container {
+  width: 100%;
+  height: 100vh;
+  position: fixed;
+  top: 0;
+  left: 0;
+  background-color: white;
+}
+html.navigation-fullscreen #navigation-header,
+html.navigation-fullscreen #navigation-content-detached,
+html.navigation-fullscreen #detached-note {
+  display: none !important;
+}
+html.navigation-fullscreen .navigation-content {
+  display: flex;
+  margin: auto; /* A `max-width` is set by src/navigation/navigation-fullscreen/initNavigationFullscreen.ts */
+}
+html.navigation-fullscreen .navigation-content > .nav-column {
+  flex-grow: 1;
+  max-width: 350px;
+}
+html.navigation-fullscreen .nav-column > .nav-h1-group:first-child > .nav-item-h1:first-child {
+  margin-top: 0px;
+}
+html.navigation-fullscreen {
+  /* disable scroll of main view */
+  overflow: hidden !important;
+}

package/navigation/Navigation.client.ts

@@ -0,0 +1,43 @@
+import { initNavigationFullscreen } from './navigation-fullscreen/initNavigationFullscreen'
+
+activateNavigationMask()
+activateMenuToggle()
+initNavigationFullscreen()
+autoHideNavigationOverlayOnLinkClick()
+navHeaderRightClickInterceptor()
+
+function activateMenuToggle() {
+  const menuToggle = document.getElementById('menu-toggle')!
+  menuToggle.onclick = navigationOverlayToggle
+}
+
+function activateNavigationMask() {
+  const navigationMask = document.getElementById('navigation-mask')!
+  navigationMask.onclick = navigationOverlayToggle
+}
+
+function autoHideNavigationOverlayOnLinkClick() {
+  document.addEventListener('click', (ev: any) => {
+    const el = ev.target
+    if (!el || !('classList' in el)) return
+    if (!el.classList.contains('nav-item')) return
+    navigationOverlayHide()
+  })
+}
+
+function navigationOverlayToggle() {
+  document.body.classList.toggle('show-menu')
+}
+function navigationOverlayHide() {
+  document.body.classList.remove('show-menu')
+}
+
+function navHeaderRightClickInterceptor() {
+  const navHeader = document.getElementById('navigation-header')!
+  if (!navHeader.classList.contains('press-kit')) return
+  if (window.location.pathname === '/press') return
+  navHeader.oncontextmenu = (ev) => {
+    ev.preventDefault()
+    window.location.href = '/press'
+  }
+}

package/navigation/Navigation.css

@@ -0,0 +1,3 @@
+@import './Navigation-layout.css';
+@import './Navigation-items.css';
+@import './Navigation-highlight.css';

package/navigation/Navigation.tsx

@@ -0,0 +1,211 @@
+export { Navigation }
+export { NavigationMask }
+
+import React from 'react'
+import { NavigationHeader } from './NavigationHeader'
+import { Heading, HeadingDetached } from '../types/Heading'
+import { assert, Emoji, assertWarning, jsxToTextContent } from '../utils/server'
+import './Navigation.css'
+import { NavigationFullscreenClose } from './navigation-fullscreen/NavigationFullscreenButton'
+
+function Navigation({
+  pageContext
+}: {
+  pageContext: {
+    headingsProcessed: Heading[]
+    headingsOfDetachedPage: null | (Heading | HeadingDetached)[]
+    urlPathname: string
+  }
+}) {
+  const currentUrl = pageContext.urlPathname
+  return (
+    <>
+      <div id="navigation-container">
+        <NavigationHeader />
+        {pageContext.headingsOfDetachedPage && (
+          <>
+            {pageContext.headingsOfDetachedPage.length > 1 && (
+              <NavigationContent
+                id="navigation-content-detached"
+                headingsProcessed={pageContext.headingsOfDetachedPage}
+                currentUrl={currentUrl}
+              />
+            )}
+            <DetachedPageNote />
+          </>
+        )}
+        <NavigationContent
+          id="navigation-content-main"
+          headingsProcessed={pageContext.headingsProcessed}
+          currentUrl={currentUrl}
+        />
+        {/* <ScrollOverlay /> */}
+        <NavigationFullscreenClose />
+      </div>
+    </>
+  )
+}
+
+function NavigationMask() {
+  return <div id="navigation-mask" />
+}
+
+function NavigationContent(props: {
+  id: 'navigation-content-main' | 'navigation-content-detached'
+  headingsProcessed: (Heading | HeadingDetached)[]
+  currentUrl: string
+}) {
+  const headings = getHeadingsWithComputedProps(props.headingsProcessed, props.currentUrl)
+
+  const headingsGrouped = groupHeadings(headings)
+
+  return (
+    <div id={props.id} className="navigation-content">
+      <div className="nav-column" style={{ position: 'relative' }}>
+        {headingsGrouped.map((headingsH1, i) => (
+          <div className="nav-h1-group" key={i}>
+            <Heading heading={headingsH1} />
+            {headingsH1.headings.map((heading, j) => (
+              <Heading heading={heading} key={j} />
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function Heading({
+  heading
+}: {
+  heading: {
+    level: number
+    url?: string | null
+    title: string | JSX.Element
+    titleInNav: string | JSX.Element
+    computed: {
+      isActive: boolean
+      isActiveFirst: boolean
+      isActiveLast: boolean
+      isFirstOfItsKind: boolean
+      isLastOfItsKind: boolean
+    }
+  }
+}) {
+  assert([1, 2, 3, 4].includes(heading.level), heading)
+  if (heading.level === 1 || heading.level === 4) {
+    assert(heading.url === undefined)
+  } else {
+    const sectionTitle = jsxToTextContent(heading.title)
+    assertWarning(
+      heading.url,
+      `${jsxToTextContent(
+        heading.titleInNav
+      )} is missing a URL hash. Use \`<h2 id="url-hash">${sectionTitle}</h2>\` instead of \`## ${sectionTitle}\`.`
+    )
+  }
+  return (
+    <a
+      className={[
+        'nav-item',
+        'nav-item-h' + heading.level,
+        heading.computed.isActive && ' is-active',
+        heading.computed.isActiveFirst && ' is-active-first',
+        heading.computed.isActiveLast && ' is-active-last',
+        heading.computed.isFirstOfItsKind && 'nav-item-first-of-its-kind',
+        heading.computed.isLastOfItsKind && 'nav-item-last-of-its-kind'
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      href={heading.url ?? undefined}
+    >
+      {/* <span className="nav-item-text">{heading.titleInNav}</span> */}
+      {heading.titleInNav}
+    </a>
+  )
+}
+
+function groupHeadings<T extends { level: number }>(headings: T[]) {
+  const headingsGrouped: (T & { headings: T[] })[] = []
+  const headingLevelMin: number = Math.min(...headings.map((h) => h.level))
+  headings.forEach((heading) => {
+    if (heading.level === headingLevelMin) {
+      headingsGrouped.push({ ...heading, headings: [] })
+    } else {
+      headingsGrouped[headingsGrouped.length - 1].headings.push(heading)
+    }
+  })
+  return headingsGrouped
+}
+
+function getHeadingsWithComputedProps(headings: (Heading | HeadingDetached)[], currentUrl: string) {
+  return headings.map((heading, i) => {
+    assert([1, 2, 3, 4].includes(heading.level), heading)
+
+    const headingPrevious = headings[i - 1]
+    const headingNext = headings[i + 1]
+
+    let isActiveFirst = false
+    let isActiveLast = false
+    let isActive = false
+    if (heading.url === currentUrl) {
+      assert(heading.level === 2, { currentUrl })
+      isActive = true
+      isActiveFirst = true
+      if (headingNext?.level !== 3) {
+        isActiveLast = true
+      }
+    }
+    if (heading.level === 3) {
+      isActive = true
+      if (headingNext?.level !== 3) {
+        isActiveLast = true
+      }
+    }
+
+    const isFirstOfItsKind = heading.level !== headingPrevious?.level
+    const isLastOfItsKind = heading.level !== headingNext?.level
+
+    return {
+      ...heading,
+      computed: {
+        isActive,
+        isActiveFirst,
+        isActiveLast,
+        isFirstOfItsKind,
+        isLastOfItsKind
+      }
+    }
+  })
+}
+
+function DetachedPageNote() {
+  return (
+    <div
+      id="detached-note"
+      style={{
+        backgroundColor: 'var(--background-color)',
+        textAlign: 'left',
+        marginLeft: 10,
+        marginRight: 10,
+        marginTop: 25,
+        marginBottom: -5,
+        borderRadius: 5,
+        padding: 10
+      }}
+    >
+      <Emoji name="info" />{' '}
+      <b>
+        <em>Detached</em>
+      </b>
+      <span
+        style={{
+          opacity: 0.8
+        }}
+      >
+        {' '}
+        &mdash; this page isn't listed in the navigation below.
+      </span>
+    </div>
+  )
+}