@brillout/docpress 0.6.21 → 0.7.1

package/navigation/NavigationHeader.tsx

@@ -4,12 +4,16 @@ import iconTwitter from '../icons/twitter.svg'
 import iconDiscord from '../icons/discord.svg'
 import iconChangelog from '../icons/changelog.svg'
 import iconLanguages from '../icons/languages.svg'
-import { usePageContext } from '../renderer/usePageContext'
+import { usePageContext, usePageContext2 } from '../renderer/usePageContext'
+import { DocSearch } from '@docsearch/react'
+import '@docsearch/css'
 
 export { NavigationHeader }
 
 function NavigationHeader() {
   const pageContext = usePageContext()
+  const pageContext2 = usePageContext2()
+  const { NavHeader } = pageContext2.config.NavHeader!
   return (
     <div
       id="navigation-header"
@@ -31,11 +35,11 @@ function NavigationHeader() {
           textDecoration: 'none',
           paddingTop: 12,
           paddingBottom: 7,
-          ...pageContext.config.navHeaderWrapperStyle,
+          ...pageContext2.config.NavHeader?.navHeaderWrapperStyle,
         }}
         href="/"
       >
-        {pageContext.config.navHeader}
+        <NavHeader />
       </a>
       <Links />
     </div>
@@ -53,6 +57,7 @@ function Links() {
       style={{ height: 21, position: 'relative', top: 0, left: 0 }}
     />
   )
+  const { algolia } = pageContext.meta
   return (
     <div
       style={{
@@ -67,7 +72,17 @@ function Links() {
         <LinkIcon className="decolorize-6" icon={iconDiscord} href={projectInfo.discordInvite} />
       )}
       <LinkIcon className="decolorize-7" icon={iconTwitter} href={projectInfo.twitterProfile} />
-      <div className="decolorize-6 colorize-on-hover" id="docsearch-desktop" />
+      {algolia && (
+        <div className="decolorize-6 colorize-on-hover">
+          <DocSearch
+            appId={algolia.appId}
+            indexName={algolia.indexName}
+            apiKey={algolia.apiKey}
+            transformItems={transformItems}
+            insights={true}
+          />
+        </div>
+      )}
       {iconI18n}
       <ChangelogButton />
     </div>
@@ -111,3 +126,17 @@ function LinkIcon({ className, icon, href, style }: { className: string; icon: s
     </>
   )
 }
+
+// Remove superfluous hash '#page-content' from URLs pointing to whole pages
+//  - https://github.com/algolia/docsearch/issues/1801
+//  - https://discourse.algolia.com/t/how-to-avoid-hash-in-search-result-url/6486
+//  - https://discourse.algolia.com/t/docsearchs-transformdata-function-cannot-remove-hashes-from-result-urls/8487
+type TransformItems = Parameters<typeof DocSearch>[0]['transformItems']
+const transformItems: TransformItems = (hits) => {
+  hits.map((hit) => {
+    if (hit.url.indexOf('#page-content') > 0) {
+      hit.url = hit.url.replace('#page-content', '')
+    }
+  })
+  return hits
+}

package/navigation/initMobileNavigation.ts

@@ -1,9 +1,9 @@
 export { initMobileNavigation }
+export { hideMobileNavigation }
 
 function initMobileNavigation() {
   activateMobileShowNavigationToggle()
   activateMobileNavigationMask()
-  autoHideNavigationOverlayOnLinkClick()
 }
 
 function activateMobileShowNavigationToggle() {
@@ -15,18 +15,9 @@ function activateMobileNavigationMask() {
   navigationMask.onclick = toggleNavigation
 }
 
-function autoHideNavigationOverlayOnLinkClick() {
-  document.addEventListener('click', (ev: any) => {
-    const el = ev.target
-    if (!el || !('classList' in el)) return
-    if (!el.classList.contains('nav-item')) return
-    hideNavigation()
-  })
-}
-
 function toggleNavigation() {
   document.body.classList.toggle('mobile-show-navigation')
 }
-function hideNavigation() {
+function hideMobileNavigation() {
   document.body.classList.remove('mobile-show-navigation')
 }

package/navigation/initPressKit.ts

@@ -1,5 +1,7 @@
 export { initPressKit }
 
+import { navigate } from 'vike/client/router'
+
 function initPressKit() {
   // Right click navigation header => show /press
   navigationHeaderRightClickInterceptor()
@@ -9,8 +11,9 @@ function navigationHeaderRightClickInterceptor() {
   const navHeader = document.getElementById('navigation-header')!
   if (!navHeader.classList.contains('press-kit')) return
   if (window.location.pathname === '/press') return
-  navHeader.oncontextmenu = (ev) => {
+  const navHeaderImg = document.querySelector('#navigation-header-logo img') as HTMLElement
+  navHeaderImg.oncontextmenu = (ev) => {
     ev.preventDefault()
-    window.location.href = '/press'
+    navigate('/press')
   }
 }

package/navigation/navigation-fullscreen/initNavigationFullscreen.ts

@@ -1,14 +1,12 @@
 export { initNavigationFullscreen }
+export { hideNavigationFullScreen }
 
 import { assert } from '../../utils/client'
-
 let scrollPositionBeforeToggle: number = 0
+initOnce()
 
-function initNavigationFullscreen() {
-  updateColumnWidth()
+function initOnce() {
   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',
@@ -19,6 +17,11 @@ function initNavigationFullscreen() {
     false,
   )
 }
+function initNavigationFullscreen() {
+  document.getElementById('navigation-fullscreen-button')!.onclick = toggleNavExpend
+  document.getElementById('navigation-fullscreen-close')!.onclick = toggleNavExpend
+  updateColumnWidth()
+}
 
 function toggleNavExpend() {
   const navContainer = document.getElementById('navigation-container')!
@@ -29,6 +32,10 @@ function toggleNavExpend() {
   }
   scrollPositionBeforeToggle = scrollPos
 }
+function hideNavigationFullScreen() {
+  if (!document.documentElement.classList.contains('navigation-fullscreen')) return
+  toggleNavExpend()
+}
 
 function updateColumnWidth() {
   const navMinWidth = 299

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@brillout/docpress",
-  "version": "0.6.21",
+  "version": "0.7.1",
   "type": "module",
   "scripts": {
-    "// Build vite.config.ts and +config.ts": "",
+    "======== Build": "",
+    "// Build vite.config.ts and +config.ts (other files don't need to be built as @brillout/docpress is noExternal)": "",
     "build": "rm -rf dist/ && tsc --project tsconfig.config.json",
-    "// Development": "",
+    "======== Develop": "",
     "dev": "tsc --watch --project tsconfig.config.json",
-    "// Check types while developing": "",
-    "types": "tsc --noEmit --watch",
-    "// Release": "",
+    "// Check types of all source files while developing": "",
+    "typecheck": "tsc --noEmit --watch",
+    "========= Release": "",
     "release": "release-me patch",
-    "release:commit": "release-me commit",
-    "release:breaking-change": "release-me minor"
+    "release:minor": "release-me minor",
+    "release:commit": "release-me commit"
   },
   "dependencies": {
     "@brillout/picocolors": "^1.0.10",
+    "@docsearch/css": "^3.6.1",
+    "@docsearch/react": "3.6.1",
     "@mdx-js/mdx": "3.0.1",
     "@mdx-js/react": "3.0.1",
     "@mdx-js/rollup": "3.0.1",
@@ -39,7 +42,8 @@
   },
   "exports": {
     "./renderer/onRenderHtml": "./renderer/onRenderHtml.tsx",
-    "./renderer/client": "./renderer/client.ts",
+    "./renderer/onRenderClient": "./renderer/onRenderClient.tsx",
+    "./renderer/onBeforeRender": "./renderer/onBeforeRender.ts",
     ".": "./index.ts",
     "./FeatureList/FeatureList": "./components/FeatureList/FeatureList.tsx",
     "./FeatureList/FeatureList.client": {
@@ -70,12 +74,14 @@
   },
   "devDependencies": {
     "@brillout/release-me": "^0.3.8",
-    "@types/node": "^15.12.1",
-    "@types/react": "^18.2.45",
-    "@types/react-dom": "^18.2.18",
-    "typescript": "^5.4.3",
-    "vike": "^0.4.195",
-    "vite": "^5.2.2"
+    "@types/node": "link:../demo/node_modules/@types/node/",
+    "@types/react": "link:../demo/node_modules/@types/react/",
+    "@types/react-dom": "link:../demo/node_modules/@types/react-dom/",
+    "react": "link:../demo/node_modules/react/",
+    "react-dom": "link:../demo/node_modules/react-dom/",
+    "typescript": "link:../demo/node_modules/typescript/",
+    "vike": "link:../demo/node_modules/vike/",
+    "vite": "link:../demo/node_modules/vite/"
   },
   "repository": "https://github.com/brillout/docpress",
   "license": "MIT",

package/parsePageSections.ts

@@ -44,7 +44,12 @@ function transform(code: string) {
         return line
       }
 
-      if (line.startsWith('#')) {
+      if (
+        line.startsWith('#')
+        /* TODO/eventually: implement.
+        || line.startsWith('<h2')
+        */
+      ) {
         const { pageSectionId, pageSectionLevel, pageSectionTitle, headingHtml } = parsePageSection(line)
         pageSections.push({ pageSectionId, pageSectionLevel, pageSectionTitle })
         return headingHtml

package/renderer/getPageElement.tsx

@@ -0,0 +1,16 @@
+export { getPageElement }
+
+import type { PageContext } from 'vike/types'
+import type { PageContextResolved } from '../config/resolvePageContext'
+import { PageLayout } from '../PageLayout'
+import React from 'react'
+
+function getPageElement(pageContext: PageContext, pageContextResolved: PageContextResolved) {
+  const { Page } = pageContext
+  const page = (
+    <PageLayout pageContext={pageContextResolved} pageContext2={pageContext}>
+      <Page />
+    </PageLayout>
+  )
+  return page
+}

package/renderer/onBeforeRender.ts

@@ -0,0 +1,12 @@
+export { onBeforeRender }
+
+import { resolvePageContext, type PageContextOriginal, type PageContextResolved } from '../config/resolvePageContext'
+
+function onBeforeRender(pageContextOriginal: PageContextOriginal) {
+  const pageContextResolved = resolvePageContext(pageContextOriginal)
+  return {
+    pageContext: {
+      pageContextResolved,
+    },
+  }
+}

package/renderer/onRenderClient.tsx

@@ -0,0 +1,90 @@
+export { onRenderClient }
+
+import React, { useEffect } from 'react'
+import type { PageContextClient } from 'vike/types'
+import ReactDOM from 'react-dom/client'
+import { PageContextResolved } from '../config/resolvePageContext'
+import { getPageElement } from './getPageElement'
+import {
+  hideNavigationFullScreen,
+  initNavigationFullscreen,
+} from '../navigation/navigation-fullscreen/initNavigationFullscreen'
+import { hideMobileNavigation, initMobileNavigation } from '../navigation/initMobileNavigation'
+import { initPressKit } from '../navigation/initPressKit'
+import '../css/index.css'
+import { autoScrollNav } from '../autoScrollNav'
+import { installSectionUrlHashs } from '../installSectionUrlHashs'
+import { addFeatureClickHandlers, addTwitterWidgets } from '../components/FeatureList/FeatureList.client'
+
+initOnLinkClick()
+
+let root: ReactDOM.Root
+function onRenderClient(pageContext: PageContextClient) {
+  // TODO: stop using any
+  const pageContextResolved: PageContextResolved = (pageContext as any).pageContextResolved
+  let page = getPageElement(pageContext, pageContextResolved)
+  page = <OnRenderDoneHook>{page}</OnRenderDoneHook>
+  const container = document.getElementById('page-view')!
+  if (pageContext.isHydration) {
+    root = ReactDOM.hydrateRoot(container, page)
+  } else {
+    if (!root) {
+      root = ReactDOM.createRoot(container)
+    }
+    root.render(page)
+  }
+
+  if (!pageContext.isHydration) {
+    applyHead(pageContext)
+  }
+}
+
+function applyHead(pageContext: PageContextClient) {
+  // TODO: stop using any
+  const pageContextResolved: PageContextResolved = (pageContext as any).pageContextResolved
+  document.title = pageContextResolved.documentTitle
+}
+
+function onRenderDone() {
+  autoScrollNav()
+  installSectionUrlHashs()
+  initNavigationFullscreen()
+  initMobileNavigation()
+  initPressKit()
+  addFeatureClickHandlers()
+  addTwitterWidgets()
+  setHydrationIsFinished()
+}
+
+function OnRenderDoneHook({ children }: { children: React.ReactNode }) {
+  useEffect(onRenderDone)
+  return children
+}
+
+function initOnLinkClick() {
+  document.addEventListener('click', (ev) => {
+    const linkTag = findLinkTag(ev.target as HTMLElement)
+    if (!linkTag) return
+    const url = linkTag.getAttribute('href')
+    if (!url) return
+    hideMobileNavigation()
+    hideNavigationFullScreen()
+  })
+}
+function findLinkTag(target: HTMLElement): null | HTMLElement {
+  while (target.tagName !== 'A') {
+    const { parentNode } = target
+    if (!parentNode) {
+      return null
+    }
+    target = parentNode as HTMLElement
+  }
+  return target
+}
+
+function setHydrationIsFinished() {
+  // Used by:
+  // - https://github.com/vikejs/vike/blob/9d67f3dd4bdfb38c835186b8147251e0e3b06657/docs/.testRun.ts#L22
+  // - https://github.com/brillout/telefunc/blob/57c942c15b7795cfda96b5106acc9e098aa509aa/docs/.testRun.ts#L26
+  ;(window as any).__docpress_hydrationFinished = true
+}

package/renderer/onRenderHtml.tsx

@@ -1,30 +1,24 @@
 export { onRenderHtml }
 
 import ReactDOMServer from 'react-dom/server'
-import React from 'react'
 import { escapeInject, dangerouslySkipEscape } from 'vike/server'
-import { PageLayout } from '../PageLayout'
-import { resolvePageContext, PageContextOriginal } from '../config/resolvePageContext'
-import { getDocSearchJS, getDocSearchCSS } from '../algolia/DocSearch'
 import { assert } from '../utils/server'
+import type { PageContextResolved } from '../config/resolvePageContext'
+import { getPageElement } from './getPageElement'
+import type { OnRenderHtmlAsync } from 'vike/types'
 
-async function onRenderHtml(pageContextOriginal: PageContextOriginal) {
-  const { Page } = pageContextOriginal
-  const pageContextResolved = resolvePageContext(pageContextOriginal)
+const onRenderHtml: OnRenderHtmlAsync = async (
+  pageContext,
+): // TODO: Why is Promise<Awaited<>> needed?
+Promise<Awaited<ReturnType<OnRenderHtmlAsync>>> => {
+  const pageContextResolved: PageContextResolved = (pageContext as any).pageContextResolved
 
-  const page = (
-    <PageLayout pageContext={pageContextResolved}>
-      <Page />
-    </PageLayout>
-  )
+  const page = getPageElement(pageContext, pageContextResolved)
 
   const descriptionTag = pageContextResolved.isLandingPage
     ? dangerouslySkipEscape(`<meta name="description" content="${pageContextResolved.meta.tagline}" />`)
     : ''
 
-  const docSearchJS = getDocSearchJS(pageContextResolved)
-  const docSearchCSS = getDocSearchCSS(pageContextResolved)
-
   const pageHtml = ReactDOMServer.renderToString(page)
 
   return escapeInject`<!DOCTYPE html>
@@ -35,16 +29,10 @@ async function onRenderHtml(pageContextOriginal: PageContextOriginal) {
         <title>${pageContextResolved.documentTitle}</title>
         ${descriptionTag}
         <meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" />
-        ${docSearchCSS}
-        ${getOpenGraphTags(
-          pageContextOriginal.urlPathname,
-          pageContextResolved.documentTitle,
-          pageContextResolved.meta,
-        )}
+        ${getOpenGraphTags(pageContext.urlPathname, pageContextResolved.documentTitle, pageContextResolved.meta)}
       </head>
       <body>
         <div id="page-view">${dangerouslySkipEscape(pageHtml)}</div>
-        ${docSearchJS}
       </body>
     </html>`
 }

package/renderer/usePageContext.tsx

@@ -3,6 +3,7 @@
 
 import React, { useContext } from 'react'
 import type { PageContextResolved } from '../config/resolvePageContext'
+import type { PageContext } from 'vike/types'
 
 export { PageContextProvider }
 export { usePageContext }
@@ -23,3 +24,22 @@ function usePageContext(): PageContextResolved {
   const pageContext = useContext(Context)
   return pageContext
 }
+
+export { PageContextProvider2 }
+// TODO/refactor: rename to usePageContext and remove old implementation
+export { usePageContext2 }
+
+const Context2 = React.createContext<PageContext>(undefined as any)
+function usePageContext2(): PageContext {
+  const pageContext = useContext(Context2)
+  return pageContext
+}
+function PageContextProvider2({
+  pageContext,
+  children,
+}: {
+  pageContext: PageContext
+  children: React.ReactNode
+}) {
+  return <Context2.Provider value={pageContext}>{children}</Context2.Provider>
+}

package/tsconfig.config.json

@@ -1,6 +1,6 @@
 {
   "extends": "./tsconfig.json",
-  "include": ["vite.config.ts", "+config.ts"],
+  "files": ["vite.config.ts", "+config.ts"],
   "compilerOptions": {
     "outDir": "./dist/"
   }

package/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "jsx": "react",
     "module": "ES2020",
-    "moduleResolution": "Node",
+    "moduleResolution": "Bundler",
     "lib": ["DOM", "DOM.Iterable", "ESNext"],
     "types": ["vite/client"],
     "esModuleInterop": true,

package/types/Config.ts

@@ -13,28 +13,14 @@ type Config = {
     twitterProfile: string
   }
   faviconUrl: string
-  algolia:
-    | null
-    | ({
-        PENDING_APPROVAL?: true
-      } & (
-        | {
-            appId?: undefined
-            apiKey?: undefined
-            indexName?: undefined
-          }
-        | {
-            appId: string
-            apiKey: string
-            indexName: string
-          }
-      ))
+  algolia: null | {
+    appId: string
+    apiKey: string
+    indexName: string
+  }
   headings: HeadingDefinition[]
   headingsDetached: HeadingDetachedDefinition[]
-  navHeaderMobile: React.ReactNode
-  navHeaderMobileWrapperStyle?: React.CSSProperties
-  navHeader: React.ReactNode
-  navHeaderWrapperStyle?: React.CSSProperties
+
   /** Sets `<meta name="description" content="${tagline}" />` */
   tagline: string
   websiteUrl: string

package/types/Heading.ts

@@ -8,9 +8,9 @@ import type { EmojiName } from '../utils/server'
 type HeadingResolved = {
   url?: null | string
   level: number
-  title: JSX.Element
-  titleInNav: JSX.Element
-  linkBreadcrumb: JSX.Element[]
+  title: string
+  titleInNav: string
+  linkBreadcrumb: string[]
   sectionTitles?: string[]
 } & Tmp
 
@@ -21,7 +21,7 @@ type HeadingDetachedResolved = Omit<HeadingResolved, 'level' | 'linkBreadcrumb'>
 
 type HeadingDetachedDefinition = {
   url: string
-  title: string | JSX.Element
+  title: string
   sectionTitles?: string[]
 }
 
@@ -37,7 +37,7 @@ type IsCategory = {
   titleInNav?: undefined
 }
 type HeadingDefinitionLevel =
-  | ({ level: 1; titleEmoji: EmojiName } & IsCategory)
+  | ({ level: 1 } & IsCategory)
   | ({ level: 4 } & IsCategory)
   | {
       level: 2

package/utils/assert.ts

@@ -2,6 +2,27 @@ export { assert }
 export { assertUsage }
 export { assertWarning }
 
+const devModeKey = '__docpress_dev_mode'
+
+if (isBrowser()) {
+  ;(window as any).toggleDevMode = toggleDevMode
+  console.log(
+    [
+      '[@brillout/docpress] DEV MODE',
+      isDevMode() ? 'enabled' : 'disabled',
+      !isLocalhost() && 'run window.toggleDevMode() to toggle DEV MODE',
+    ]
+      .filter(Boolean)
+      .join(' '),
+  )
+  if (isDevMode()) {
+    window.onerror = (err) => {
+      alert(err)
+      window.onerror = null
+    }
+  }
+}
+
 function assert(condition: unknown, debugInfo?: unknown): asserts condition {
   if (condition) {
     return
@@ -18,8 +39,8 @@ function assert(condition: unknown, debugInfo?: unknown): asserts condition {
     errMsg += ' Debug info: ' + String(debugInfo)
   }
   const err = new Error(errMsg)
-  if (isBrowserAndDev()) {
-    alert(err.stack)
+  if (isBrowser() && isDevMode()) {
+    window.alert(err.stack)
   }
   throw err
 }
@@ -29,14 +50,29 @@ function assertUsage(condition: unknown, msg: string): asserts condition {
     return
   }
   const err = new Error('[DocPress][Wrong Usage] ' + msg)
-  if (isBrowserAndDev()) {
-    alert(err.stack)
+  if (isBrowser() && isDevMode()) {
+    window.alert(err.stack)
   }
   throw err
 }
 
-function isBrowserAndDev() {
-  return typeof window !== 'undefined' && window?.location?.port !== ''
+function isBrowser() {
+  return typeof window !== 'undefined'
+}
+function isDevMode() {
+  return !!window.localStorage[devModeKey] || isLocalhost()
+}
+function isLocalhost() {
+  return window?.location?.port !== ''
+}
+function toggleDevMode() {
+  if (isLocalhost()) throw new Error('On localhost DEV MODE is always on.')
+  if (window.localStorage[devModeKey]) {
+    window.localStorage[devModeKey] = 'true'
+  } else {
+    delete window.localStorage[devModeKey]
+  }
+  console.log(`DEV MODE ${isDevMode() ? 'enabled' : 'disabled'}`)
 }
 
 function assertWarning(condition: unknown, msg: string): asserts condition {
@@ -45,7 +81,7 @@ function assertWarning(condition: unknown, msg: string): asserts condition {
   }
   msg = '[DocPress][Warning] ' + msg
   console.warn(msg)
-  if (isBrowserAndDev()) {
-    alert(msg)
+  if (isBrowser() && isDevMode()) {
+    window.alert(msg)
   }
 }

package/utils/jsxToTextContent.ts

@@ -3,7 +3,7 @@ import { assert } from './assert'
 export { jsxToTextContent }
 
 // https://stackoverflow.com/questions/34204975/react-is-there-something-similar-to-node-textcontent/60564620#60564620
-function jsxToTextContent(node: JSX.Element | string): string {
+function jsxToTextContent(node: JSX.Element): string {
   if (['string', 'number'].includes(typeof node)) return String(node)
   if (node instanceof Array) return node.map(jsxToTextContent).join('')
   if (typeof node === 'object' && node) return jsxToTextContent(node.props.children)

package/vite.config.ts

@@ -26,10 +26,12 @@ const config: UserConfig = {
       includeAssetsImportedByServer: true,
     }),
   ],
-  optimizeDeps: { include: ['@brillout/docpress', 'react-dom'] },
-  // @ts-ignore
+  optimizeDeps: {
+    include: ['react', 'react-dom', 'react-dom/client'],
+    exclude: ['@brillout/docpress'],
+  },
   ssr: {
-    noExternal: ['@brillout/docpress'],
+    noExternal: ['@brillout/docpress', '@docsearch/react'],
   },
   clearScreen: false,
 }