@brillout/docpress 0.1.14 → 0.1.17

package/src/navigation/Navigation.client.ts

@@ -0,0 +1,19 @@
+import { initNavigationFullscreen } from './navigation-fullscreen/initNavigationFullscreen'
+
+activateNavigationMask()
+activateMenuToggle()
+initNavigationFullscreen()
+
+function activateMenuToggle() {
+  const menuToggle = document.getElementById('menu-toggle')!
+  menuToggle.onclick = toggleNavigation
+}
+
+function activateNavigationMask() {
+  const navigationMask = document.getElementById('navigation-mask')!
+  navigationMask.onclick = toggleNavigation
+}
+
+function toggleNavigation() {
+  document.body.classList.toggle('show-menu')
+}

package/src/navigation/Navigation.css

@@ -0,0 +1,12 @@
+@import './Navigation-layout.css';
+@import './Navigation-items.css';
+@import './Navigation-highlight.css';
+
+#navigation-container {
+  --background-color: #f0f0f0;
+  padding-bottom: 70px;
+}
+
+html.navigation-fullscreen #detached-note {
+  display: none;
+}

package/src/navigation/Navigation.tsx

@@ -0,0 +1,228 @@
+export { Navigation }
+export { NavigationMask }
+
+import React from 'react'
+import { NavigationHeader } from './NavigationHeader'
+import { Heading } from '../headings'
+import { assert, Emoji } from '../utils/server'
+import './Navigation.css'
+import { NavigationFullscreenClose } from './navigation-fullscreen/NavigationFullscreenButton'
+
+function Navigation({
+  pageContext
+}: {
+  pageContext: {
+    headingsWithSubHeadings: Heading[]
+    urlPathname: string
+    isDetachedPage: boolean
+  }
+}) {
+  const { isDetachedPage } = pageContext
+  return (
+    <>
+      <div id="navigation-container">
+        <NavigationHeader />
+        {isDetachedPage && <DetachedPageNote />}
+        <NavigationContent pageContext={pageContext} />
+        {/* <ScrollOverlay /> */}
+        <NavigationFullscreenClose />
+      </div>
+    </>
+  )
+}
+
+function NavigationMask() {
+  return <div id="navigation-mask" />
+}
+
+function NavigationContent({
+  pageContext
+}: {
+  pageContext: {
+    headingsWithSubHeadings: Heading[]
+    urlPathname: string
+    isDetachedPage: boolean
+  }
+}) {
+  const headings = getHeadingsWithComputedProps(pageContext)
+  const headingsGrouped = groupHeadings(headings)
+  return (
+    <div id="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
+    titleInNav: string | JSX.Element
+    computed: {
+      isActive: boolean
+      isActiveFirst: boolean
+      isActiveLast: boolean
+      isChildOfListHeading: boolean
+      isFirstOfItsKind: boolean
+      isLastOfItsKind: boolean
+    }
+  }
+}) {
+  assert([1, 2, 3, 4].includes(heading.level), heading)
+  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.isChildOfListHeading && 'nav-item-parent-is-list-heading',
+        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[] })[] = []
+  headings.forEach((heading) => {
+    if (heading.level === 1) {
+      headingsGrouped.push({ ...heading, headings: [] })
+    } else {
+      headingsGrouped[headingsGrouped.length - 1].headings.push(heading)
+    }
+  })
+  return headingsGrouped
+}
+
+function getHeadingsWithComputedProps(pageContext: {
+  headingsWithSubHeadings: Heading[]
+  urlPathname: string
+  isDetachedPage: boolean
+}) {
+  const { headingsWithSubHeadings, urlPathname } = pageContext
+  return headingsWithSubHeadings.map((heading, i) => {
+    assert([1, 2, 3, 4].includes(heading.level), heading)
+
+    const headingPrevious = headingsWithSubHeadings[i - 1]
+    const headingNext = headingsWithSubHeadings[i + 1]
+
+    let isActiveFirst = false
+    let isActiveLast = false
+    let isActive = false
+    if (heading.url === urlPathname) {
+      assert(heading.level === 2, { urlPathname })
+      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
+    const isChildOfListHeading = !!heading.parentHeadings[0]?.isListTitle
+
+    return {
+      ...heading,
+      computed: {
+        isActive,
+        isActiveFirst,
+        isActiveLast,
+        isFirstOfItsKind,
+        isLastOfItsKind,
+        isChildOfListHeading
+      }
+    }
+  })
+}
+
+function ScrollOverlay() {
+  // const width = '1px'
+  // const color = '#aaa'
+  return (
+    <div
+      id="scroll-overlay"
+      style={{
+        pointerEvents: 'none',
+        position: 'absolute',
+        left: '0',
+        width: '100%',
+        /*
+        background: `linear-gradient(to right, ${color} ${width}, transparent ${width}) 0 0,
+    linear-gradient(to right, ${color} ${width}, transparent ${width}) 0 100%,
+    linear-gradient(to left, ${color} ${width}, transparent ${width}) 100% 0,
+    linear-gradient(to left, ${color} ${width}, transparent ${width}) 100% 100%,
+    linear-gradient(to bottom, ${color} ${width}, transparent ${width}) 0 0,
+    linear-gradient(to bottom, ${color} ${width}, transparent ${width}) 100% 0,
+    linear-gradient(to top, ${color} ${width}, transparent ${width}) 0 100%,
+    linear-gradient(to top, ${color} ${width}, transparent ${width}) 100% 100%`,
+        //*/
+        //borderRight: `5px solid ${color}`,
+        borderRight: `3px solid #666`,
+        //border: `1px solid ${color}`,
+        boxSizing: 'border-box',
+        // backgroundColor: 'rgba(0,0,0,0.03)',
+        backgroundRepeat: 'no-repeat',
+
+        backgroundSize: '10px 10px'
+      }}
+    />
+  )
+}
+
+function DetachedPageNote() {
+  return (
+    <div
+      id="detached-note"
+      style={{
+        backgroundColor: 'var(--background-color)',
+        textAlign: 'left',
+        marginLeft: 10,
+        marginRight: 10,
+        marginTop: 30,
+        marginBottom: -8,
+        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 menu below.
+      </span>
+    </div>
+  )
+}

package/src/navigation/NavigationHeader.tsx

@@ -0,0 +1,97 @@
+import React from 'react'
+import iconGithub from '../icons/github.svg'
+import iconTwitter from '../icons/twitter.svg'
+import iconDiscord from '../icons/discord.svg'
+import iconChangelog from '../icons/changelog.svg'
+import { usePageContext } from '../renderer/usePageContext'
+
+export { NavigationHeader }
+
+function NavigationHeader() {
+  const pageContext = usePageContext()
+  return (
+    <div
+      id="navigation-header"
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        marginBottom: -5
+      }}
+    >
+      <a
+        id="navigation-header-logo"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          color: 'inherit',
+          justifyContent: 'left',
+          textDecoration: 'none',
+          paddingTop: 12,
+          paddingBottom: 7
+        }}
+        href="/"
+      >
+        {pageContext.config.navHeader}
+      </a>
+      <Links />
+    </div>
+  )
+}
+
+function Links() {
+  const pageContext = usePageContext()
+  const { projectInfo } = pageContext.config
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        paddingTop: 0,
+        justifyContent: 'left'
+      }}
+    >
+      <SocialLink className="decolorize-4" icon={iconGithub} href={projectInfo.githubRepository} />
+      <SocialLink className="decolorize-6" icon={iconDiscord} href={projectInfo.discordInvite} />
+      <SocialLink className="decolorize-7" icon={iconTwitter} href={projectInfo.twitterProfile} />
+      <div id="docsearch-desktop" />
+      <ChangelogButton />
+    </div>
+  )
+}
+
+function ChangelogButton() {
+  const pageContext = usePageContext()
+  const { projectInfo } = pageContext.config
+  return (
+    <a
+      href={`${projectInfo.githubRepository}/blob/main/CHANGELOG.md`}
+      className="button colorize-on-hover"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        padding: '1px 7px',
+        marginLeft: 2,
+        fontSize: '0.97em',
+        color: 'inherit'
+      }}
+    >
+      <span className="decolorize-7">v{projectInfo.projectVersion}</span>
+      <img className="decolorize-6" src={iconChangelog} height={16} style={{ marginLeft: 5 }} />
+    </a>
+  )
+}
+
+function SocialLink({ className, icon, href }: { className: string; icon: string; href: string }) {
+  return (
+    <>
+      <a
+        className={'colorize-on-hover ' + className}
+        href={href}
+        style={{ padding: 3, display: 'inline-block', lineHeight: 0 }}
+      >
+        <img src={icon} height="20" style={{}} />
+      </a>
+    </>
+  )
+}

package/src/navigation/navigation-fullscreen/NavigationFullscreenButton.css

@@ -0,0 +1,32 @@
+:root {
+  --navigation-fullscreen-button-width: 20px;
+}
+#navigation-fullscreen-button {
+  width: var(--navigation-fullscreen-button-width);
+  position: relative;
+  z-index: 2;
+}
+#navigation-wrapper:hover + #navigation-fullscreen-button > div > div,
+#navigation-fullscreen-button:hover > div > div {
+  left: 0px;
+}
+#navigation-fullscreen-button > div > div {
+  transition: all 0.3s ease-in-out;
+  left: -20px;
+  position: absolute;
+  height: 100%;
+  width: 100%;
+  background-color: #eee !important;
+  background: url('./chevron.svg');
+  background-repeat: no-repeat;
+  background-position: center center;
+}
+
+html:not(.navigation-fullscreen) #navigation-fullscreen-close {
+  display: none;
+}
+
+html.navigation-fullscreen #page-content {
+  /* Make `Ctrl-F` browser search only crawl the navigation menu */
+  visibility: hidden;
+}

package/src/navigation/navigation-fullscreen/NavigationFullscreenButton.tsx

@@ -0,0 +1,44 @@
+export { NavigationFullscreenButton }
+export { NavigationFullscreenClose }
+
+import React from 'react'
+import './NavigationFullscreenButton.css'
+import closeIcon from './close.svg'
+
+function NavigationFullscreenButton() {
+  return (
+    <>
+      <a id="navigation-fullscreen-button">
+        <div
+          style={{
+            position: 'fixed',
+            cursor: 'pointer',
+            height: '100vh',
+            width: 20,
+            overflow: 'hidden'
+          }}
+        >
+          <div></div>
+        </div>
+        <div
+          style={{ position: 'fixed', height: '100vh', width: 20 }}
+          aria-label="Press <Esc>"
+          data-balloon-pos="right"
+        ></div>
+      </a>
+    </>
+  )
+}
+
+function NavigationFullscreenClose() {
+  return (
+    <a
+      id="navigation-fullscreen-close"
+      style={{ position: 'fixed', top: 11, right: 15, zIndex: 10 }}
+      aria-label="Press <Esc>"
+      data-balloon-pos="left"
+    >
+      <img src={closeIcon} height={50} width={50} style={{ display: 'block' }} />
+    </a>
+  )
+}

package/src/navigation/navigation-fullscreen/initNavigationFullscreen.ts

@@ -0,0 +1,115 @@
+export { initNavigationFullscreen }
+
+import { assert } from '../../utils/client'
+
+let scrollPositionBeforeToggle: number = 0
+
+function initNavigationFullscreen() {
+  updateColumnWidth()
+  window.addEventListener('resize', updateColumnWidth, { passive: true })
+  document.getElementById('navigation-fullscreen-button')!.onclick = toggleNavExpend
+  document.getElementById('navigation-fullscreen-close')!.onclick = toggleNavExpend
+  document.addEventListener(
+    // We don't use keydown to not interfere with user pressing `<Esc>` for closing the browser's `<Ctrl-F>` search diablog, see https://stackoverflow.com/questions/66595035/how-to-detect-escape-key-if-search-bar-of-browser-is-open
+    'keydown',
+    (ev) => {
+      if (ev.key === 'Escape') toggleNavExpend()
+    },
+    false
+  )
+}
+
+function toggleNavExpend() {
+  const navContainer = document.getElementById('navigation-container')!
+  const scrollPos = navContainer.scrollTop
+  document.documentElement.classList.toggle('navigation-fullscreen')
+  if (scrollPositionBeforeToggle !== undefined) {
+    navContainer.scrollTop = scrollPositionBeforeToggle
+  }
+  scrollPositionBeforeToggle = scrollPos
+}
+
+function updateColumnWidth() {
+  const navMinWidth = 299
+  const navH1Groups = Array.from(document.querySelectorAll('.nav-h1-group'))
+  const numberOfColumnsMax = navH1Groups.length
+
+  const widthAvailable = getViewportWidth()
+  const numberOfColumns = Math.max(1, Math.min(numberOfColumnsMax, Math.floor(widthAvailable / navMinWidth)))
+
+  let columns = navH1Groups.map((navH1Group) => {
+    const column = [
+      {
+        element: navH1Group,
+        elementHeight: navH1Group.children.length
+      }
+    ]
+    return column
+  })
+
+  mergeColumns(columns, numberOfColumns)
+
+  const navContent = document.getElementById('navigation-content')!
+
+  Array.from(navContent.children).forEach((child) => {
+    assert(child.className === 'nav-column')
+  })
+  navContent.innerHTML = ''
+
+  columns.forEach((column) => {
+    const columnEl = document.createElement('div')
+    columnEl.className = 'nav-column'
+    column.forEach(({ element }) => {
+      columnEl.appendChild(element)
+    })
+    navContent.appendChild(columnEl)
+  })
+
+  const navItemMaxWidth = 350
+  navContent.style.maxWidth = `${numberOfColumns * navItemMaxWidth}px`
+}
+function getViewportWidth(): number {
+  // `window.innerWidth` inlcudes scrollbar width: https://developer.mozilla.org/en-US/docs/Web/API/Window/innerWidth#usage_notes
+  return document.documentElement.clientWidth
+}
+
+function mergeColumns<T>(columns: { element: T; elementHeight: number }[][], maxNumberOfColumns: number) {
+  assert(columns.length > 0)
+  assert(maxNumberOfColumns > 0)
+  if (columns.length <= maxNumberOfColumns) {
+    return columns
+  }
+
+  let mergeCandidate = {
+    i: -1,
+    mergeHeight: Infinity
+  }
+  for (let i = 0; i <= columns.length - 2; i++) {
+    const column1 = columns[i + 0]
+    const column2 = columns[i + 1]
+    const column1Height = sum(column1.map((c) => c.elementHeight))
+    const column2Height = sum(column2.map((c) => c.elementHeight))
+    const mergeHeight = column1Height + column2Height
+    if (mergeCandidate.mergeHeight > mergeHeight) {
+      mergeCandidate = {
+        i,
+        mergeHeight
+      }
+    }
+  }
+
+  {
+    const { i } = mergeCandidate
+    assert(-1 < i && i < columns.length - 1, { i, columnsLength: columns.length, maxNumberOfColumns })
+    columns[i] = [...columns[i], ...columns[i + 1]]
+    columns.splice(i + 1, 1)
+  }
+
+  mergeColumns(columns, maxNumberOfColumns)
+}
+
+function sum(arr: number[]): number {
+  let total = 0
+  arr.forEach((n) => (total += n))
+  return total
+}

package/src/parseEmojis.ts

@@ -0,0 +1,33 @@
+export { parseEmojis }
+
+import twemoji from 'twemoji'
+
+const emojiList = {
+  // https://emojipedia.org/no-entry/
+  ':no_entry:': 0x26d4,
+  // https://emojipedia.org/warning/
+  ':warning:': 0x26a0,
+  // https://emojipedia.org/trophy/
+  ':trophy:': 0x1f3c6
+  /*
+  // https://emojipedia.org/red-heart/
+  ':heart:': 0x2764,
+  */
+}
+
+function parseEmojis(html: string) {
+  Object.entries(emojiList).forEach(([shortcode, codepoint]) => {
+    if (!html.includes(shortcode)) {
+      return
+    }
+    const emojiStr = twemoji.convert.fromCodePoint(codepoint as any)
+    let emojiImg: any = twemoji.parse(emojiStr, {
+      folder: 'svg',
+      ext: '.svg'
+    })
+    const style = 'height: 1.275em; width: 1.275em; vertical-align: -20%'
+    emojiImg = emojiImg.replace('<img class="emoji" ', `<img style="${style}" `)
+    html = html.split(shortcode).join(emojiImg)
+  })
+  return html
+}

package/src/renderer/_default.page.client.ts

@@ -0,0 +1,4 @@
+import '../css/index.css'
+import '../autoScrollNav'
+import '../installSectionUrlHashs'
+import '../navigation/Navigation.client'

package/src/renderer/_default.page.server.tsx

@@ -0,0 +1,69 @@
+import ReactDOMServer from 'react-dom/server'
+import React from 'react'
+import { escapeInject, dangerouslySkipEscape } from 'vite-plugin-ssr'
+import { PageLayout } from '../PageLayout'
+import { resolvePageContext, PageContextOriginal } from '../config/resolvePageContext'
+import { getDocSearchJS, getDocSearchCSS } from '../algolia/DocSearch'
+import { parseEmojis } from '../parseEmojis'
+import { assert } from '../utils/server'
+
+export { render }
+
+async function render(pageContextOriginal: PageContextOriginal) {
+  const { Page } = pageContextOriginal
+  const pageContextResolved = resolvePageContext(pageContextOriginal)
+
+  const page = (
+    <PageLayout pageContext={pageContextResolved}>
+      <Page />
+    </PageLayout>
+  )
+
+  const descriptionTag = pageContextResolved.isLandingPage
+    ? dangerouslySkipEscape(`<meta name="description" content="${pageContextResolved.meta.tagline}" />`)
+    : ''
+
+  const docSearchJS = getDocSearchJS(pageContextResolved)
+  const docSearchCSS = getDocSearchCSS(pageContextResolved)
+
+  let pageHtml = ReactDOMServer.renderToString(page)
+  pageHtml = parseEmojis(pageHtml)
+
+  return escapeInject`<!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" href="${pageContextResolved.meta.faviconUrl}" />
+        <title>${pageContextResolved.meta.title}</title>
+        ${descriptionTag}
+        <meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" />
+        ${docSearchCSS}
+        ${getOpenGraphTags(pageContextOriginal.urlPathname, pageContextResolved.meta)}
+      </head>
+      <body>
+        <div id="page-view">${dangerouslySkipEscape(pageHtml)}</div>
+        ${docSearchJS}
+      </body>
+    </html>`
+}
+
+function getOpenGraphTags(
+  url: string,
+  meta: { title: string; tagline: string; websiteUrl: string; twitterHandle: string; bannerUrl?: string }
+) {
+  const { title, tagline, websiteUrl, twitterHandle, bannerUrl } = meta
+
+  assert(url.startsWith('/'))
+  if (url !== '/' || !bannerUrl) return ''
+
+  // See view-source:https://vitejs.dev/
+  return escapeInject`
+    <meta property="og:type" content="website">
+    <meta property="og:title" content="${title}">
+    <meta property="og:image" content="${bannerUrl}">
+    <meta property="og:url" content="${websiteUrl}">
+    <meta property="og:description" content="${tagline}">
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:site" content="${twitterHandle}">
+  `
+}

package/src/renderer/usePageContext.tsx

@@ -0,0 +1,25 @@
+// `usePageContext` allows us to access `pageContext` in any React component.
+// More infos: https://vite-plugin-ssr.com/pageContext-anywhere
+
+import React, { useContext } from 'react'
+import type { PageContextResolved } from '../config/resolvePageContext'
+
+export { PageContextProvider }
+export { usePageContext }
+
+const Context = React.createContext<PageContextResolved>(undefined as any)
+
+function PageContextProvider({
+  pageContext,
+  children
+}: {
+  pageContext: PageContextResolved
+  children: React.ReactNode
+}) {
+  return <Context.Provider value={pageContext}>{children}</Context.Provider>
+}
+
+function usePageContext(): PageContextResolved {
+  const pageContext = useContext(Context)
+  return pageContext
+}

package/src/types.ts

@@ -0,0 +1,2 @@
+export type { Config } from './config/Config'
+export type { HeadingDefinition, HeadingWithoutLink } from './headings'