@brillout/docpress 0.16.5 → 0.16.7-commit-fc2ed19

package/Layout.tsx

@@ -27,6 +27,7 @@ import {
 } from './MenuModal/toggleMenuModal'
 import { MenuModal } from './MenuModal'
 import { autoScrollNav_SSR } from './autoScrollNav'
+import { initializeChoiceGroup_SSR } from './code-blocks/hooks/useSelectedChoice'
 import { initializeJsToggle_SSR } from './code-blocks/hooks/useSelectCodeLang'
 import { SearchLink } from './docsearch/SearchLink'
 import { navigate } from 'vike/client/router'
@@ -100,7 +101,7 @@ function Layout({ children }: { children: React.ReactNode }) {
         {content}
       </div>
       {/* Early toggling, to avoid layout jumps */}
-      <script dangerouslySetInnerHTML={{ __html: initializeJsToggle_SSR }}></script>
+      <script dangerouslySetInnerHTML={{ __html: `${initializeChoiceGroup_SSR}\n${initializeJsToggle_SSR}` }}></script>
       <Style>{getStyleLayout()}</Style>
     </div>
   )
@@ -589,7 +590,10 @@ function NavHeadLogo({ isNavLeft }: { isNavLeft?: true }) {
               paddingLeft: 'var(--main-view-padding)',
               paddingRight: 'var(--padding-side)',
             }
-          : {}),
+          : {
+              paddingLeft: 15,
+              marginLeft: -10,
+            }),
       }}
       href="/"
       onContextMenu={!navLogo ? undefined : onContextMenu}

package/code-blocks/components/ChoiceGroup.css

@@ -0,0 +1,48 @@
+.choice-group {
+  position: relative;
+
+  &:hover {
+    .select-choice,
+    .copy-button,
+    .code-lang-toggle {
+      opacity: 1;
+    }
+  }
+
+  --select-width: 100px;
+  --select-top-position: 10px;
+  --select-right-position: 42px;
+  --has-toggle: calc(var(--select-right-position) + 61px);
+
+  .select-choice {
+    position: absolute;
+    z-index: 3;
+    height: 25px;
+    top: var(--select-top-position);
+    right: var(--select-right-position);
+    width: var(--select-width);
+
+    opacity: 0;
+    transition: opacity 0.5s ease-in-out, background-color 0.4s ease-in-out;
+
+    &.has-toggle {
+      --select-right-position: var(--has-toggle);
+    }
+
+    &:has(+ .choice .choice-group) {
+      right: calc(var(--select-width) + var(--select-right-position) + 2px);
+    }
+  }
+
+  .hidden {
+    display: none !important;
+  }
+
+  select:has(option:nth-of-type(1):not(:checked)) ~ .choice:nth-of-type(1),
+  select:has(option:nth-of-type(2):not(:checked)) ~ .choice:nth-of-type(2),
+  select:has(option:nth-of-type(3):not(:checked)) ~ .choice:nth-of-type(3),
+  select:has(option:nth-of-type(4):not(:checked)) ~ .choice:nth-of-type(4),
+  select:has(option:nth-of-type(5):not(:checked)) ~ .choice:nth-of-type(5) {
+    display: none;
+  }
+}

package/code-blocks/components/ChoiceGroup.tsx

@@ -0,0 +1,85 @@
+export { ChoiceGroup }
+
+import React, { useEffect, useRef, useState } from 'react'
+import { usePageContext } from '../../renderer/usePageContext'
+import { useSelectedChoice } from '../hooks/useSelectedChoice'
+import { useRestoreScroll } from '../hooks/useRestoreScroll'
+import { assertUsage } from '../../utils/assert'
+import { cls } from '../../utils/cls'
+import type { PageContext } from 'vike/types'
+import './ChoiceGroup.css'
+
+function ChoiceGroup({ children, choices }: { children: React.ReactNode; choices: string[] }) {
+  const pageContext = usePageContext()
+  const group = findGroup(pageContext, choices)
+  const [selectedChoice, setSelectedChoice] = useSelectedChoice(group.name, group.default)
+  const [hasJsToggle, setHasJsToggle] = useState(false)
+  const choiceGroupRef = useRef<HTMLDivElement>(null)
+  const prevPositionRef = useRestoreScroll([selectedChoice])
+  const isHidden = choices.length === 1 || !choices.includes(selectedChoice)
+
+  useEffect(() => {
+    if (!choiceGroupRef.current) return
+    const selectedChoiceEl = choiceGroupRef.current.querySelector<HTMLDivElement>(`div[id="${selectedChoice}"]`)
+    setHasJsToggle(!!selectedChoiceEl?.classList.contains('has-toggle'))
+  }, [selectedChoice])
+
+  return (
+    <div ref={choiceGroupRef} data-group-name={group.name} className="choice-group">
+      <select
+        name={`${group.name}-choices`}
+        value={selectedChoice}
+        onChange={onChange}
+        className={cls(['select-choice', hasJsToggle && 'has-toggle', isHidden && 'hidden'])}
+      >
+        {group.choices.map((choice, i) => (
+          <option key={i} value={choice} disabled={!choices.includes(choice)}>
+            {choice}
+          </option>
+        ))}
+      </select>
+      {children}
+    </div>
+  )
+
+  function onChange(e: React.ChangeEvent<HTMLSelectElement>) {
+    const el = e.target
+    prevPositionRef.current = { top: el.getBoundingClientRect().top, el }
+    setSelectedChoice(el.value)
+  }
+}
+
+function findGroup(pageContext: PageContext, choices: string[]) {
+  const { choices: choicesGroup } = pageContext.globalContext.config.docpress
+  assertUsage(choicesGroup, `+docpress.choices is not defined.`)
+
+  const groupName = Object.keys(choicesGroup).find((key) => {
+    // get only the values that exist in both choices and choicesGroup[key].choices
+    const relevantChoices = choicesGroup[key].choices.filter((choice) => choices.includes(choice))
+    // if nothing exists, skip this key
+    if (relevantChoices.length === 0) return false
+
+    // check order
+    let i = 0
+    for (const choice of choices) {
+      if (choice === relevantChoices[i]) i++
+    }
+    assertUsage(
+      i === relevantChoices.length,
+      `Choices exist for key "${key}" but NOT in order. Expected order: [${relevantChoices}], got: [${choices}]`,
+    )
+
+    return true
+  })
+  assertUsage(groupName, `the group name for [${choices}] was not found.`)
+
+  const mergedChoices = [...new Set([...choices, ...choicesGroup[groupName].choices])]
+
+  const group = {
+    name: groupName,
+    ...choicesGroup[groupName],
+    choices: mergedChoices,
+  }
+
+  return group
+}

package/code-blocks/components/CodeSnippets.tsx

@@ -4,8 +4,9 @@ export { TypescriptOnly }
 // Internal
 export { CodeSnippets }
 
-import React, { useEffect, useRef } from 'react'
+import React from 'react'
 import { useSelectCodeLang } from '../hooks/useSelectCodeLang'
+import { useRestoreScroll } from '../hooks/useRestoreScroll'
 import './CodeSnippets.css'
 
 /** Only show if TypeScript is selected */
@@ -16,18 +17,7 @@ function TypescriptOnly({ children }: { children: React.ReactNode }) {
 
 function CodeSnippets({ children, hideToggle = false }: { children: React.ReactNode; hideToggle: boolean }) {
   const [codeLangSelected, selectCodeLang] = useSelectCodeLang()
-  const prevPositionRef = useRef<null | { top: number; el: Element }>(null)
-
-  // Restores the scroll position of the toggle element after toggling languages.
-  useEffect(() => {
-    if (!prevPositionRef.current) return
-    const { top, el } = prevPositionRef.current
-    const delta = el.getBoundingClientRect().top - top
-    if (delta !== 0) {
-      window.scrollBy(0, delta)
-    }
-    prevPositionRef.current = null
-  }, [codeLangSelected])
+  const prevPositionRef = useRestoreScroll([codeLangSelected])
 
   return (
     <div className="code-snippets">

package/code-blocks/components/Pre.tsx

@@ -1,11 +1,35 @@
 export { Pre }
 
-import React, { ComponentPropsWithoutRef, useState } from 'react'
+import React, { useState } from 'react'
+import { cls } from '../../utils/cls'
 import './Pre.css'
 
-function Pre({ children, ...props }: ComponentPropsWithoutRef<'pre'> & { 'hide-menu'?: string }) {
+// Styling defined in src/css/code/diff.css
+const classRemoved = [
+  //
+  'diff-entire-file',
+  'diff-entire-file-removed',
+].join(' ')
+const classAdded = [
+  //
+  'diff-entire-file',
+  'diff-entire-file-added',
+].join(' ')
+
+type AdditionalProps = {
+  'hide-menu'?: string
+  'file-added'?: string
+  'file-removed'?: string
+}
+
+function Pre({ children, ...props }: React.ComponentPropsWithoutRef<'pre'> & AdditionalProps) {
+  const { className, ...rest } = props
+
   return (
-    <pre {...props}>
+    <pre
+      className={cls([className, props['file-added'] && classAdded, props['file-removed'] && classRemoved])}
+      {...rest}
+    >
       {!props['hide-menu'] && <CopyButton />}
       {children}
     </pre>

package/code-blocks/hooks/useLocalStorage.ts

@@ -0,0 +1,39 @@
+export { useLocalStorage }
+
+import { useCallback, useSyncExternalStore } from 'react'
+
+/**
+ * A simple, generic `useLocalStorage` hook with SSR and cross-tab support.
+ *
+ * @param storageKey The key used in localStorage.
+ * @param clientValue Default value for the client.
+ * @param ssrValue Optional fallback for server-side rendering.
+ * @returns A tuple `[value, setValue]`.
+ */
+function useLocalStorage(storageKey: string, clientValue: string, ssrValue?: string) {
+  const subscribe = useCallback(
+    (callback: () => void) => {
+      const listener = (e: StorageEvent) => {
+        if (e.key === storageKey) callback()
+      }
+      window.addEventListener('storage', listener)
+      return () => window.removeEventListener('storage', listener)
+    },
+    [storageKey],
+  )
+
+  const getSnapshot = useCallback(() => {
+    const storedValue = localStorage.getItem(storageKey)
+    return storedValue || clientValue
+  }, [storageKey, clientValue])
+
+  const setValue = (value: string) => {
+    localStorage.setItem(storageKey, value)
+    // Manually dispatch a storage event to force update in the current tab
+    window.dispatchEvent(new StorageEvent('storage', { key: storageKey }))
+  }
+
+  const value = useSyncExternalStore(subscribe, getSnapshot, () => ssrValue || clientValue)
+
+  return [value, setValue] as const
+}

package/code-blocks/hooks/useMDXComponents.tsx

@@ -4,9 +4,11 @@ import React from 'react'
 import type { UseMdxComponents } from '@mdx-js/mdx'
 import { Pre } from '../components/Pre.js'
 import { CodeSnippets } from '../components/CodeSnippets.js'
+import { ChoiceGroup } from '../components/ChoiceGroup.js'
 
 const useMDXComponents: UseMdxComponents = () => {
   return {
+    ChoiceGroup,
     CodeSnippets,
     pre: (props) => <Pre {...props} />,
   }

package/code-blocks/hooks/useRestoreScroll.ts

@@ -0,0 +1,31 @@
+export { useRestoreScroll }
+
+import React, { useEffect, useRef } from 'react'
+
+type ScrollPosition = { top: number; el: Element }
+
+/**
+ * useRestoreScroll
+ *
+ * Keeps the page from jumping when content changes,
+ * preserving the user’s scroll position.
+ *
+ * @param deps Dependencies that trigger scroll restoration
+ * @returns Ref holding the tracked element and its previous top position
+ */
+function useRestoreScroll(deps: React.DependencyList) {
+  const prevPositionRef = useRef<ScrollPosition | null>(null)
+
+  useEffect(() => {
+    if (!prevPositionRef.current) return
+
+    const { top, el } = prevPositionRef.current
+    const delta = el.getBoundingClientRect().top - top
+
+    if (delta !== 0) window.scrollBy(0, delta)
+
+    prevPositionRef.current = null
+  }, deps)
+
+  return prevPositionRef
+}

package/code-blocks/hooks/useSelectCodeLang.ts

@@ -1,57 +1,14 @@
 export { useSelectCodeLang }
 export { initializeJsToggle_SSR }
 
-import { useState, useEffect, useCallback } from 'react'
-import { assertWarning } from '../../utils/assert'
+import { useLocalStorage } from './useLocalStorage'
 
 const storageKey = 'docpress:code-lang'
 const codeLangDefaultSsr = 'ts'
 const codeLangDefaultClient = 'js'
 
 function useSelectCodeLang() {
-  const [codeLangSelected, setCodeLangSelected] = useState(codeLangDefaultSsr)
-  const updateState = () => {
-    setCodeLangSelected(getCodeLangStorage())
-  }
-  const updateStateOnStorageEvent = (event: StorageEvent) => {
-    if (event.key === storageKey) updateState()
-  }
-
-  const getCodeLangStorage = () => {
-    try {
-      return window.localStorage.getItem(storageKey) ?? codeLangDefaultClient
-    } catch (error) {
-      console.error(error)
-      assertWarning(false, 'Error reading from localStorage')
-      return codeLangDefaultClient
-    }
-  }
-
-  const selectCodeLang = useCallback((value: string) => {
-    try {
-      window.localStorage.setItem(storageKey, value)
-      setCodeLangSelected(value)
-      window.dispatchEvent(new CustomEvent('code-lang-storage'))
-    } catch (error) {
-      console.error(error)
-      assertWarning(false, 'Error setting localStorage')
-    }
-  }, [])
-
-  useEffect(() => {
-    // Initial load from localStorage
-    updateState()
-    // Update code lang in current tab
-    window.addEventListener('code-lang-storage', updateState)
-    // Update code lang if changed in another tab
-    window.addEventListener('storage', updateStateOnStorageEvent)
-    return () => {
-      window.removeEventListener('code-lang-storage', updateState)
-      window.removeEventListener('storage', updateStateOnStorageEvent)
-    }
-  }, [])
-
-  return [codeLangSelected, selectCodeLang] as const
+  return useLocalStorage(storageKey, codeLangDefaultClient, codeLangDefaultSsr)
 }
 
 // WARNING: We cannot use the variables storageKey nor codeLangDefaultClient here: closures
@@ -66,9 +23,3 @@ function initializeJsToggle() {
     for (const input of inputs) input.checked = false
   }
 }
-
-declare global {
-  interface WindowEventMap {
-    'code-lang-storage': CustomEvent
-  }
-}

package/code-blocks/hooks/useSelectedChoice.ts

@@ -0,0 +1,34 @@
+export { useSelectedChoice }
+export { initializeChoiceGroup_SSR }
+
+import { useState } from 'react'
+import { useLocalStorage } from './useLocalStorage'
+
+const keyPrefix = 'docpress'
+
+/**
+ * Tracks the selected choice.
+ * Uses `useLocalStorage` if `persistId` is provided, otherwise regular state.
+ *
+ * @param persistId Optional ID to persist selection.
+ * @param defaultValue Default choice value.
+ * @returns `[selectedChoice, setSelectedChoice]`.
+ */
+function useSelectedChoice(persistId: string | null, defaultValue: string) {
+  if (!persistId) return useState(defaultValue)
+
+  return useLocalStorage(`${keyPrefix}:${persistId}`, defaultValue)
+}
+
+// WARNING: We cannot use the keyPrefix variable here: closures don't work because we serialize the function.
+const initializeChoiceGroup_SSR = `initializeChoiceGroup();${initializeChoiceGroup.toString()};`
+function initializeChoiceGroup() {
+  const groupsElements = document.querySelectorAll<HTMLDivElement>('[data-group-name]')
+  for (const groupEl of groupsElements) {
+    const groupName = groupEl.getAttribute('data-group-name')!
+    const selectedChoice = localStorage.getItem(`docpress:${groupName}`)
+    if (!selectedChoice) continue
+    const selectEl = groupEl.querySelector<HTMLSelectElement>(`.select-choice`)
+    if (selectEl) selectEl.value = selectedChoice
+  }
+}

package/code-blocks/rehypeMetaToProps.ts

@@ -23,41 +23,47 @@ function rehypeMetaToProps() {
   return (tree: Root) => {
     visit(tree, 'element', (node, _index, parent) => {
       if (node.tagName === 'code' && parent?.type === 'element' && parent.tagName === 'pre') {
-        const props = parseMetaString(node.data?.meta)
+        const meta = parseMetaString(node.data?.meta)
         parent.properties ??= {}
-        parent.properties = { ...parent.properties, ...props }
+        parent.properties = { ...parent.properties, ...meta.props }
       }
     })
   }
 }
 
 /**
- * Minimal parser for a metadata string into key-value pairs.
+ * Simple parser for a metadata string into key-value pairs and a remaining unparsed string.
  *
- * Supports simple patterns: key or key="value".
+ * Supports simple patterns: key or key=value.
  *
- * Keys must contain only letters, dashes, or underscores (no digits).
- * Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys must contain only letters, dashes, or underscores (no digits).
+ * - Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys and values are stored in `props`.
+ * - If `propNames` is provided, only keys included in that list are extracted.
+ * - Unextracted tokens remain in `rest`.
  *
- * Example:
- *   parseMetaString('foo fooBar="value"')
- *   => { foo: 'true', foo_bar: 'value' }
- *
- * @param metaString - The input metadata string.
- * @returns A plain object of parsed key-value pairs.
+ * @param meta - The input metadata string.
+ * @param propNames - Optional whitelist of property names to extract.
+ * @returns An object containing:
+ *   - `props`: a map of extracted properties
+ *   - `rest`: the remaining metadata string after extraction
  */
-function parseMetaString(metaString: ElementData['meta']): Record<string, string> {
-  if (!metaString) return {}
+function parseMetaString<Name extends string = string>(meta: ElementData['meta'], propNames?: Name[]): PropsType<Name> {
+  if (!meta) return { props: {}, rest: '' }
 
-  const props: Record<string, string> = {}
+  let str = meta
 
-  const keyValuePairRE = /([a-zA-Z_-]+)(?:=([^"'\s]+))?(?=\s|$)/g
-  for (const match of metaString.matchAll(keyValuePairRE)) {
-    let [_, key, value] = match
-    props[kebabCase(key)] = value || 'true'
-  }
+  const keyValuePairRE = /(?<name>[a-zA-Z_-]+)(?:=([^"'\s]+))?/g
+  const props: PropsType['props'] = {}
+
+  str = str.replaceAll(keyValuePairRE, (match, name, value) => {
+    if (propNames && !propNames.includes(name)) return match
 
-  return props
+    props[kebabCase(name)] = value || 'true'
+    return ''
+  })
+
+  return { props, rest: str.trim() }
 }
 
 // Simple function to convert a camelCase or PascalCase string to kebab-case.
@@ -67,3 +73,8 @@ function kebabCase(str: string) {
     .replace('_', '-')
     .toLowerCase()
 }
+
+interface PropsType<Name extends string = string> {
+  props: Partial<Record<Name, string>>
+  rest: string
+}

package/code-blocks/remarkChoiceGroup.ts

@@ -0,0 +1,112 @@
+export { remarkChoiceGroup }
+
+import type { Code, Root } from 'mdast'
+import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx'
+import type { ContainerDirective } from 'mdast-util-directive'
+import { visit } from 'unist-util-visit'
+import { parseMetaString } from './rehypeMetaToProps.js'
+import { generateChoiceGroup } from './utils/generateChoiceGroup.js'
+
+type Node = Code | MdxJsxFlowElement | ContainerDirective
+
+function remarkChoiceGroup() {
+  return function (tree: Root) {
+    visit(tree, (node) => {
+      if (node.type === 'code') {
+        if (!node.meta) return
+        const meta = parseMetaString(node.meta, ['choice'])
+        const { choice } = meta.props
+        node.meta = meta.rest
+
+        if (choice) node.data ??= { choice }
+      }
+      if (node.type === 'containerDirective' && node.name === 'Choice') {
+        if (!node.attributes) return
+        const { id: choice } = node.attributes
+        if (choice) {
+          node.data ??= { choice }
+          node.attributes = {}
+        }
+      }
+    })
+
+    const replaced = new WeakSet()
+    visit(tree, (node) => {
+      if (!('children' in node) || replaced.has(node)) return 'skip'
+      if (node.type === 'mdxJsxFlowElement') return 'skip'
+
+      let start = -1
+      let end = 0
+
+      const process = () => {
+        if (start === -1 || start === end) return
+        const nodes = node.children.slice(start, end) as Node[]
+        const groupedNodes = groupByNodeType(nodes)
+        const replacements: MdxJsxFlowElement[] = []
+
+        for (const groupedNode of groupedNodes) {
+          const replacement = generateChoiceGroup(groupedNode)
+
+          replacements.push(replacement)
+          replaced.add(replacement)
+        }
+
+        node.children.splice(start, end - start, ...replacements)
+
+        end = start
+        start = -1
+      }
+
+      for (; end < node.children.length; end++) {
+        const child = node.children[end]
+
+        if (!['code', 'mdxJsxFlowElement', 'containerDirective'].includes(child.type)) {
+          process()
+          continue
+        }
+
+        if (!child.data?.choice) {
+          process()
+          continue
+        }
+
+        if (start === -1) start = end
+      }
+
+      process()
+    })
+  }
+}
+
+type NodeGroup = {
+  value: string
+  children: Node[]
+}
+
+function groupByNodeType(nodes: Node[]) {
+  const groupedNodes = new Set<NodeGroup[]>()
+  const filters = [...new Set(nodes.flat().map((node) => (node.type === 'code' ? node.lang! : node.name)))]
+
+  filters.map((filter) => {
+    const nodesByChoice = new Map<string, Node[]>()
+    nodes
+      .filter((node) => (node.type === 'code' ? node.lang! : node.name) === filter)
+      .map((node) => {
+        const choice = node.data!.choice!
+        const nodes = nodesByChoice.get(choice) ?? []
+        nodes.push(node)
+        node.data = {}
+        nodesByChoice.set(choice, nodes)
+      })
+
+    groupedNodes.add([...nodesByChoice].map(([name, nodes]) => ({ value: name, children: nodes })))
+  })
+
+  return [...groupedNodes]
+}
+
+declare module 'mdast' {
+  export interface Data {
+    choice?: string
+  }
+}

package/code-blocks/remarkDetype.ts

@@ -82,7 +82,11 @@ function transformYaml(node: CodeNode) {
 
 async function transformTsToJs(node: CodeNode, file: VFile) {
   const { codeBlock, index, parent } = node
-  const maxWidth = Number(parseMetaString(codeBlock.meta)['max-width'])
+  const meta = parseMetaString(codeBlock.meta, ['max-width', 'choice'])
+  const maxWidth = Number(meta.props['max-width'])
+  const { choice } = meta.props
+  codeBlock.meta = meta.rest
+
   let codeBlockReplacedJs = replaceFileNameSuffixes(codeBlock.value)
   let codeBlockContentJs = ''
 
@@ -136,8 +140,8 @@ async function transformTsToJs(node: CodeNode, file: VFile) {
   // Add `hideToggle` attribute (prop) to `CodeSnippets` if the only change was replacing `.ts` with `.js`
   if (codeBlockReplacedJs === codeBlockContentJs) {
     attributes.push({
-      name: 'hideToggle',
       type: 'mdxJsxAttribute',
+      name: 'hideToggle',
     })
   }
 
@@ -148,6 +152,9 @@ async function transformTsToJs(node: CodeNode, file: VFile) {
     children: [jsCode, codeBlock],
     attributes,
   }
+
+  if (choice) container.data ??= { choice }
+
   parent.children.splice(index, 1, container)
 }
 
@@ -164,7 +171,7 @@ function cleanUpCode(code: string, isJsCode: boolean = false) {
 }
 function processMagicComments(code: string) {
   // @detype-replace DummyLayout Layout
-  const renameCommentRE = /^\/\/\s@detype-replace\s([^ ]+) ([^ ]+)\n/gm
+  const renameCommentRE = /^\s*\/\/\s@detype-replace\s([^ ]+) ([^ ]+)\n/gm
   const matches = Array.from(code.matchAll(renameCommentRE))
 
   if (matches.length) {