@brillout/docpress 0.1.14 → 0.1.17

package/src/markdownHeadingsVitePlugin.ts

@@ -0,0 +1,128 @@
+import { assert, determineSectionUrlHash } from '../src/utils/server'
+
+export { markdownHeadingsVitePlugin }
+export type { MarkdownHeading }
+
+type MarkdownHeading = {
+  title: string
+  id: string
+  headingLevel: number
+  titleAddendum?: string
+}
+
+function markdownHeadingsVitePlugin() {
+  return {
+    name: 'mdx-headings',
+    enforce: 'pre',
+    transform: async (code: string, id: string) => {
+      if (!id.includes('.page.') || !id.endsWith('.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 { id, headingLevel, title, headingHtml } = parseMarkdownHeading(line)
+        headings.push({ id, headingLevel, title })
+        return headingHtml
+      }
+      if (line.startsWith('<h')) {
+        assert(false, { line })
+      }
+
+      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 id = determineSectionUrlHash(titleMdx)
+  const title = titleMdx
+
+  const headingHtml = `<h${headingLevel} id="${id}">${parseTitle(title)}</h${headingLevel}>`
+
+  const heading = { headingLevel, title, id, 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) {
+    const textEscaped = text.split("'").join("\\'")
+    return `{'${textEscaped}'}`
+  }
+}

package/src/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/src/navigation/Navigation-items.css

@@ -0,0 +1,122 @@
+.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);
+}
+.nav-item-h3.nav-item-parent-is-list-heading {
+  --padding-left-additional: 21px;
+}

package/src/navigation/Navigation-layout.css

@@ -0,0 +1,118 @@
+:root {
+  --mobile-header-height: 60px;
+  --navigation-min-height: 300px;
+  --navigation-max-height: 350px;
+}
+#navigation-wrapper {
+  min-width: var(--navigation-min-height);
+}
+.doc-page #navigation-wrapper {
+  max-width: var(--navigation-max-height);
+}
+.landing-page #navigation-wrapper {
+  /* prettier-ignore */
+  max-width: min(var(--navigation-max-height), max(var(--navigation-min-height), calc(var(--navigation-min-height) + 100vw - 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;
+}
+#navigation-mask {
+  position: fixed;
+  width: 100vw;
+  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,
+  #docsearch {
+    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(100vw, 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: 100vw;
+  height: 100vh;
+  overflow-y: scroll;
+  position: fixed;
+  top: 0;
+  left: 0;
+  background-color: white;
+}
+html.navigation-fullscreen #navigation-header {
+  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/src/navigation/Navigation.client.old.ts

@@ -0,0 +1,303 @@
+// @ts-nocheck
+
+import { headings as headingsCrawled } from './Docs.mdx'
+import { assert, isBrowser } from './utils/client'
+import { Heading } from './types'
+const headings: Heading[] = [
+  {
+    level: 2,
+    title: 'Overview',
+    isDocumentBegin: true
+  },
+  ...headingsCrawled
+]
+assert_headings()
+
+export { updateSidePanelScroll }
+
+if (isBrowser()) {
+  setTimeout(updateSidePanelScroll, 0)
+  window.addEventListener('scroll', updateSidePanelScroll, { passive: true })
+  window.addEventListener('resize', updateSidePanelScroll, { passive: true })
+}
+
+function updateSidePanelScroll() {
+  const headingSectionsVisibility = getHeadingSectionsVisbility(headings)
+  setActiveHeadings(headingSectionsVisibility)
+  renderNavScrollBar(headingSectionsVisibility)
+}
+
+function setActiveHeadings(headingSectionsVisibility: HeadingSectionVisibility[]) {
+  /*
+  const viewportPercentageHighest = Math.max(
+    ...headingSectionsVisibility.map(({ viewportPercentage }) => viewportPercentage)
+  )
+  */
+  const visibleHeadings = getVisibleHeadings(headingSectionsVisibility)
+  // console.log('v', visibleHeadings);
+  headingSectionsVisibility.forEach((heading) => {
+    const navItem = findNavLink(heading)
+    const isVisibile = visibleHeadings.find((visibleHeading) => {
+      if ('isDocumentBegin' in heading || 'isDocumentBegin' in visibleHeading) {
+        return 'isDocumentBegin' in heading && 'isDocumentBegin' in visibleHeading
+      } else {
+        return heading.id === visibleHeading.id
+      }
+    })
+    navItem.style.display = isVisibile ? 'inherit' : 'none'
+    /*
+    if (viewportPercentageHighest === heading.viewportPercentage) {
+      const navItem = findNavLink(heading)
+      updateNavTreeExpendedState(navItem)
+    }
+    */
+  })
+  headingSectionsVisibility.forEach((heading) => {
+    const navItem = findNavLink(heading)
+    setNavItemBackgroundColor(navItem, heading.viewportPercentage)
+  })
+}
+
+function updateNavTreeExpendedState(navItem: HTMLElement) {
+  const navItemHref = navItem.getAttribute('href')
+  assert(typeof navItemHref === 'string')
+  const selector = `a[href="${navItemHref}"]`
+  //console.log(11, selector, 2)
+  assert(document.querySelector(selector))
+  document.querySelectorAll('.nav-tree').forEach((navTree) => {
+    const isExpended = !!navTree.querySelector(selector)
+    //console.log(navTree.href, isExpended)
+    navTree.classList[isExpended ? 'add' : 'remove']('expanded')
+  })
+}
+
+function setNavItemBackgroundColor(navItem: HTMLElement, viewportPercentage: number) {
+  if (viewportPercentage) {
+    assert(viewportPercentage >= 0 && viewportPercentage <= 1)
+    const backgroundColor = `rgba(0, 0, 0, ${viewportPercentage / 20})`
+    navItem.style.backgroundColor = backgroundColor
+  } else {
+    navItem.style.backgroundColor = 'transparent'
+  }
+}
+
+function findNavLink(heading: Heading): HTMLElement {
+  const href = getHref(heading)
+  const navigationEl = getNavigationEl()
+  const navLinks: HTMLElement[] = Array.from(navigationEl.querySelectorAll(`a[href="${href}"]`))
+  assert(navLinks.length === 1)
+  return navLinks[0]
+}
+
+let _navigationEl: HTMLElement
+function getNavigationEl(): HTMLElement {
+  _navigationEl = _navigationEl || document.getElementById('navigation-content')
+  assert(_navigationEl)
+  return _navigationEl
+}
+
+function renderNavScrollBar(headingSectionsVisibility: HeadingSectionVisibility[]) {
+  const { headingVisibleFirst, headingVisibleLast } = getBoundaryHeading(headingSectionsVisibility)
+  assertBoundaryPosition(headingVisibleFirst.boundaryPosition)
+  assertBoundaryPosition(headingVisibleLast.boundaryPosition)
+
+  const navigationEl = getNavigationEl()
+  const getLinkNavPosition = (el: HTMLElement): number => {
+    let offsetY = el.offsetTop
+    const parentEl = el.offsetParent as HTMLElement
+    if (parentEl !== navigationEl) {
+      offsetY += getLinkNavPosition(parentEl)
+    }
+    return offsetY
+  }
+  const getOverlayPosition = ({
+    heading,
+    boundaryPosition
+  }: {
+    heading: Heading
+    boundaryPosition: number
+  }): number => {
+    const navLink = findNavLink(heading)
+    const navLinkPos = getLinkNavPosition(navLink)
+    const scrollOverlayBoundaryPos = navLinkPos + navLink.clientHeight * boundaryPosition
+    return scrollOverlayBoundaryPos
+  }
+  const overlayBegin = getOverlayPosition(headingVisibleFirst)
+  const overlayEnd = getOverlayPosition(headingVisibleLast)
+  const overlayHeight = Math.max(1, overlayEnd - overlayBegin)
+  const scrollOverlayEl = document.getElementById('scroll-overlay')!
+  scrollOverlayEl.style.top = overlayBegin + 'px'
+  scrollOverlayEl.style.height = overlayHeight + 'px'
+}
+
+function getHeadingPosition(heading: Heading): number {
+  if ('isDocumentBegin' in heading) return 0
+  const { id } = heading
+  assert(id)
+  const el = document.getElementById(id)
+  assert(el)
+
+  // `el.getBoundingClientRect()` returns position relative to viewport begin
+  // - https://stackoverflow.com/questions/5598743/finding-elements-position-relative-to-the-document
+  const headingPositionRelative = el.getBoundingClientRect().top
+
+  const scrollPosition = getScrollPosition()
+
+  // We add the viewport begin position
+  const headingPosition = headingPositionRelative + scrollPosition
+
+  return headingPosition
+}
+function getDocumentHeight(): number {
+  return document.body.clientHeight
+}
+function getViewportHeight(): number {
+  return window.innerHeight
+}
+function getScrollPosition(): number {
+  return window.scrollY
+}
+
+type HeadingVisible = { heading: Heading; boundaryPosition: number; viewportPercentage: number }
+function getVisibleHeadings(headingSectionsVisibility: HeadingSectionVisibility[]): HeadingSectionVisibility[] {
+  const headings_withVisibileNavItem: Heading[] = filterHeadingsWithVisibileNavItem(headingSectionsVisibility)
+  const headingSectionsWithVisibleNavItemVisibility = getHeadingSectionsVisbility(headings_withVisibileNavItem)
+  return headingSectionsWithVisibleNavItemVisibility
+}
+function getBoundaryHeading(headingSectionsVisibility: HeadingSectionVisibility[]): {
+  headingVisibleFirst: HeadingVisible
+  headingVisibleLast: HeadingVisible
+} {
+  const headingSectionsWithVisibleNavItemVisibility = getVisibleHeadings(headingSectionsVisibility)
+  const h: HeadingSectionVisibility[] = headingSectionsWithVisibleNavItemVisibility
+  const hFirst = h.find(({ screenBeginPosition }) => screenBeginPosition !== null)
+  const hLast = h.find(({ screenEndPosition }) => screenEndPosition !== null)
+  assert(hFirst)
+  assert(hLast)
+  assert(hFirst.screenBeginPosition !== null)
+  assert(hLast.screenEndPosition !== null)
+  const headingVisibleFirst = {
+    heading: hFirst,
+    boundaryPosition: hFirst.screenBeginPosition,
+    viewportPercentage: hFirst.viewportPercentage
+  }
+  const headingVisibleLast = {
+    heading: hLast,
+    boundaryPosition: hLast.screenEndPosition,
+    viewportPercentage: hLast.viewportPercentage
+  }
+  return { headingVisibleFirst, headingVisibleLast }
+}
+
+function filterHeadingsWithVisibileNavItem(headingSectionsVisibility: HeadingSectionVisibility[]): Heading[] {
+  const hs = headingSectionsVisibility
+  const viewportPercentageHighest = Math.max(...hs.map(({ viewportPercentage }) => viewportPercentage))
+  const mainHeading = hs.find((heading) => {
+    return heading.viewportPercentage === viewportPercentageHighest
+  })
+  assert(mainHeading)
+  const ancestors = getAncestors(mainHeading, hs)
+  const headings_withVisibileNavItem = hs.filter((heading) => {
+    const p = getParent(heading, hs)
+    return p === null || ancestors.includes(p)
+  })
+  return headings_withVisibileNavItem
+}
+
+function getParent(heading: Heading, headings: Heading[]): Heading | null {
+  return getAncestors(heading, headings)[0] || null
+}
+
+function getAncestors(heading: Heading, headings: Heading[]): Heading[] {
+  const headingIndex = headings.indexOf(heading)
+  assert(headingIndex >= 0)
+  const ancestors: Heading[] = []
+  let currentLevel = heading.level - 1
+  for (let i = headingIndex - 1; i >= 0; i--) {
+    const h = headings[i]
+    if (h.level === currentLevel) {
+      ancestors.push(h)
+      currentLevel--
+    }
+  }
+  assert(currentLevel === 1)
+  return ancestors
+}
+
+type HeadingSectionVisibility = Heading & {
+  viewportPercentage: number
+  screenBeginPosition: null | number
+  screenEndPosition: null | number
+}
+function getHeadingSectionsVisbility(headings: Heading[]): HeadingSectionVisibility[] {
+  const screenBeginPositionAbsolute = getScrollPosition()
+  const screenEndPositionAbsolute = screenBeginPositionAbsolute + getViewportHeight()
+
+  const headingSections: (HeadingSectionVisibility & { beginPosition: number; endPosition: number })[] = []
+  headings.forEach((heading, i) => {
+    const beginPosition = getHeadingPosition(heading)
+
+    const headingNext = headings[i + 1]
+    const endPosition = !headingNext ? getDocumentHeight() : getHeadingPosition(headingNext)
+
+    const sectionHeight = endPosition - beginPosition
+    assert(sectionHeight > 0)
+
+    let screenBeginPosition = null
+    if (beginPosition <= screenBeginPositionAbsolute && screenBeginPositionAbsolute <= endPosition) {
+      screenBeginPosition = (screenBeginPositionAbsolute - beginPosition) / sectionHeight
+      assert(0 <= screenBeginPosition && screenBeginPosition <= 1)
+    }
+
+    let screenEndPosition = null
+    if (beginPosition <= screenEndPositionAbsolute && screenEndPositionAbsolute <= endPosition) {
+      screenEndPosition = (screenEndPositionAbsolute - beginPosition) / sectionHeight
+      assert(0 <= screenEndPosition && screenEndPosition <= 1)
+    }
+
+    assert(beginPosition <= endPosition)
+    const getViewportPosition = (position: number) => {
+      const viewportPosition = Math.min(Math.max(position, screenBeginPositionAbsolute), screenEndPositionAbsolute)
+      assert(screenBeginPositionAbsolute <= viewportPosition && viewportPosition <= screenEndPositionAbsolute)
+      return viewportPosition
+    }
+    const viewportPositionBegin = getViewportPosition(beginPosition)
+    const viewportPositionEnd = getViewportPosition(endPosition)
+    const viewportPercentage = (viewportPositionEnd - viewportPositionBegin) / getViewportHeight()
+
+    headingSections.push({
+      ...heading,
+      viewportPercentage,
+      screenBeginPosition,
+      screenEndPosition,
+      beginPosition,
+      endPosition
+    })
+  })
+
+  const viewportPercentageTotal = sum(headingSections.map(({ viewportPercentage }) => viewportPercentage))
+  const debugInfo = JSON.stringify({ headingSections, screenBeginPositionAbsolute, screenEndPositionAbsolute }, null, 2)
+  assert(viewportPercentageTotal <= 1 + 0.00001, debugInfo)
+  // assert(1 - 0.00001 <= viewportPercentageTotal && viewportPercentageTotal <= 1 + 0.00001, debugInfo)
+  assert(headingSections.filter(({ screenBeginPosition }) => screenBeginPosition !== null).length === 1, debugInfo)
+  assert(headingSections.filter(({ screenEndPosition }) => screenEndPosition !== null).length === 1, debugInfo)
+
+  return headingSections
+}
+
+function assertBoundaryPosition(boundaryPosition: number) {
+  assert(0 <= boundaryPosition && boundaryPosition <= 1)
+}
+
+function sum(numbers: number[]): number {
+  return numbers.reduce((a, b) => a + b, 0)
+}
+
+function assert_headings() {
+  const hrefs: string[] = []
+  headings.forEach((heading) => {
+    const href = getHref(heading)
+    assert(!hrefs.includes(href), href)
+    hrefs.push(href)
+  })
+}