@brillout/docpress 0.15.10 → 0.15.11-commit-e615832

package/Layout.tsx

@@ -15,6 +15,7 @@ import { ExternalLinks } from './ExternalLinks'
 import { coseMenuModalOnMouseLeave, openMenuModal, toggleMenuModal } from './MenuModal/toggleMenuModal'
 import { MenuModal } from './MenuModal'
 import { autoScrollNav_SSR } from './autoScrollNav'
+import { initializeJsToggle_SSR } from './code-blocks/hooks/useSelectCodeLang'
 import { SearchLink } from './docsearch/SearchLink'
 import { navigate } from 'vike/client/router'
 import { css } from './utils/css'
@@ -78,6 +79,8 @@ function Layout({ children }: { children: React.ReactNode }) {
         <NavHead />
         {content}
       </div>
+      {/* Early toggling, to avoid layout jumps */}
+      <script dangerouslySetInnerHTML={{ __html: initializeJsToggle_SSR }}></script>
     </div>
   )
 }

package/autoScrollNav.ts

@@ -1,7 +1,7 @@
 export { autoScrollNav }
-export const autoScrollNav_SSR = `autoScrollNav();${autoScrollNav.toString()}`
+export { autoScrollNav_SSR }
 
-// - We cannot use TypeScript syntax because of autoScrollNav_SSR
+// - WARNING: We cannot use TypeScript here because we serialize the function.
 // - We have to save & restore `document.documentElement.scrollTop` because scrollIntoView() scrolls the main view. (I don't know why).
 //   - Failed alternatives:
 //     - scrollIntoViewIfNeeded() (https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoViewIfNeeded) would work (it doesn't scroll the main view) but Firefox doesn't support it.
@@ -17,7 +17,7 @@ export const autoScrollNav_SSR = `autoScrollNav();${autoScrollNav.toString()}`
 //       // ...
 //       document.documentElement.style.overflow = overflowOriginal
 //       ```
-
+const autoScrollNav_SSR = `autoScrollNav();${autoScrollNav.toString()}`
 function autoScrollNav() {
   const nav = document.querySelector('#nav-left .navigation-content')
   if (!nav) return

package/code-blocks/components/CodeSnippets.css

@@ -0,0 +1,74 @@
+.code-snippets {
+  position: relative;
+
+  &:hover {
+    .copy-button,
+    .code-lang-toggle {
+      opacity: 1;
+    }
+  }
+
+  /* Language toggle styles */
+  .code-lang-toggle {
+    position: absolute !important;
+    top: 10px;
+    right: 42px;
+    z-index: 3;
+
+    /* Checkbox appearance reset */
+    appearance: none;
+    -webkit-appearance: none;
+    -moz-appearance: none;
+
+    margin: 0;
+    padding: 0 4px;
+    height: 25px;
+    width: 59px;
+    display: flex;
+    background-color: #f7f7f7;
+    opacity: 0;
+    transition: opacity 0.5s ease-in-out, background-color 0.4s ease-in-out;
+
+    &:not(:hover) {
+      background-color: #eee;
+    }
+
+    /* Toggle Labels */
+    &::before,
+    &::after {
+      width: 24px;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+    }
+
+    &::before {
+      content: 'JS';
+    }
+
+    &::after {
+      content: 'TS';
+      border-left: none;
+      opacity: 0.3;
+    }
+
+    &:checked {
+      &::before {
+        opacity: 0.3;
+      }
+
+      &::after {
+        opacity: 1;
+      }
+    }
+  }
+
+  /* Code block visibility based on toggle */
+  &:has(.code-lang-toggle:checked) figure:first-of-type {
+    display: none;
+  }
+
+  &:has(.code-lang-toggle:not(:checked)) figure:last-of-type {
+    display: none;
+  }
+}

package/code-blocks/components/CodeSnippets.tsx

@@ -0,0 +1,51 @@
+// Public
+export { TypescriptOnly }
+
+// Internal
+export { CodeSnippets }
+
+import React, { useEffect, useRef } from 'react'
+import { useSelectCodeLang } from '../hooks/useSelectCodeLang'
+import './CodeSnippets.css'
+
+/** Only show if TypeScript is selected */
+function TypescriptOnly({ children }: { children: React.ReactNode }) {
+  const [codeLangSelected] = useSelectCodeLang()
+  return <div style={{ display: codeLangSelected === 'ts' ? 'block' : 'none' }}>{children}</div>
+}
+
+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])
+
+  return (
+    <div className="code-snippets">
+      <input
+        type="checkbox"
+        name="code-lang-toggle"
+        className="code-lang-toggle raised"
+        style={{ display: hideToggle ? 'none' : undefined }}
+        checked={codeLangSelected === 'ts'}
+        onChange={onChange}
+        title="Toggle language"
+      />
+      {children}
+    </div>
+  )
+  function onChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const element = e.target
+    prevPositionRef.current = { top: element.getBoundingClientRect().top, el: element }
+    selectCodeLang(element.checked ? 'ts' : 'js')
+  }
+}

package/code-blocks/components/Pre.css

@@ -0,0 +1,51 @@
+pre > code {
+  /*
+  background-color: #f4f4f4;
+  0.043137255 = 1 - (#f4 / #ff)
+  */
+  background: rgba(0, 0, 0, 0.043137255);
+  font-size: 1em;
+}
+
+/* Copy button */
+pre {
+  &:has(.copy-button) {
+    position: relative;
+  }
+
+  &:hover {
+    .copy-button {
+      opacity: 1;
+    }
+  }
+
+  .copy-button {
+    position: absolute !important;
+    top: 10px;
+    right: 10px;
+    z-index: 3;
+    margin: 0;
+    height: 25px;
+    width: 30px;
+    background-color: #f7f7f7;
+    opacity: 0;
+    transition: opacity 0.5s ease-in-out, background-color 0.4s ease-in-out;
+
+    &:not(:hover) {
+      background-color: #eee;
+    }
+
+    & svg {
+      width: 100%;
+      height: 100%;
+      fill: none;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+  }
+}
+
+/* Workaround for shiki regression */
+pre > code:not([data-language]) {
+  padding: 16px !important;
+}

package/code-blocks/components/Pre.tsx

@@ -0,0 +1,70 @@
+export { Pre }
+
+import React, { ComponentPropsWithoutRef, useState } from 'react'
+import './Pre.css'
+
+function Pre({ children, ...props }: ComponentPropsWithoutRef<'pre'> & { 'hide-menu'?: string }) {
+  return (
+    <pre {...props}>
+      {!props['hide-menu'] && <CopyButton />}
+      {children}
+    </pre>
+  )
+}
+
+function CopyButton() {
+  const [isSuccess, setIsSuccess] = useState(null as null | boolean)
+  const onCopy = (success: boolean) => {
+    setIsSuccess(success)
+    setTimeout(() => {
+      setIsSuccess(null)
+    }, 900)
+  }
+  const tooltip = isSuccess === null ? 'Copy to clipboard' : isSuccess ? 'Copied' : 'Failed'
+  const icon =
+    isSuccess === null ? (
+      // Copy icon
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke="black" strokeWidth="2">
+        <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+        <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+      </svg>
+    ) : isSuccess ? (
+      // Green checkmark
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" stroke="#28a745" strokeWidth="3">
+        <polyline points="20 6 9 17 4 12" />
+      </svg>
+    ) : (
+      '❌'
+    )
+  return (
+    <button
+      className="copy-button raised"
+      aria-label={tooltip}
+      data-label-position="top"
+      type="button"
+      onClick={onClick}
+    >
+      {icon}
+    </button>
+  )
+  async function onClick(e: React.MouseEvent<HTMLButtonElement>) {
+    let success: boolean
+    const preEl = e.currentTarget.parentElement!
+    let text = preEl.textContent || ''
+    text = removeTrailingWhitespaces(text)
+    try {
+      await navigator.clipboard.writeText(text)
+      success = true
+    } catch (error) {
+      console.error(error)
+      success = false
+    }
+    onCopy(success)
+  }
+}
+function removeTrailingWhitespaces(text: string) {
+  return text
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .join('\n')
+}

package/code-blocks/hooks/useMDXComponents.tsx

@@ -0,0 +1,13 @@
+export { useMDXComponents }
+
+import React from 'react'
+import type { UseMdxComponents } from '@mdx-js/mdx'
+import { Pre } from '../components/Pre.js'
+import { CodeSnippets } from '../components/CodeSnippets.js'
+
+const useMDXComponents: UseMdxComponents = () => {
+  return {
+    CodeSnippets,
+    pre: (props) => <Pre {...props} />,
+  }
+}

package/code-blocks/hooks/useSelectCodeLang.ts

@@ -0,0 +1,74 @@
+export { useSelectCodeLang }
+export { initializeJsToggle_SSR }
+
+import { useState, useEffect, useCallback } from 'react'
+import { assertWarning } from '../../utils/assert'
+
+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
+}
+
+// WARNING: We cannot use the variables storageKey nor codeLangDefaultClient here: closures
+// don't work because we serialize the function.
+// WARNING: We cannot use TypeScript here, for the same reason.
+const initializeJsToggle_SSR = `initializeJsToggle();${initializeJsToggle.toString()};`
+function initializeJsToggle() {
+  const codeLangSelected = localStorage.getItem('docpress:code-lang') ?? 'js'
+  if (codeLangSelected === 'js') {
+    const inputs = document.querySelectorAll('.code-lang-toggle')
+    // @ts-ignore
+    for (const input of inputs) input.checked = false
+  }
+}
+
+declare global {
+  interface WindowEventMap {
+    'code-lang-storage': CustomEvent
+  }
+}

package/code-blocks/rehypeMetaToProps.ts

@@ -0,0 +1,69 @@
+export { rehypeMetaToProps, parseMetaString }
+
+import { visit } from 'unist-util-visit'
+import type { ElementData, Root } from 'hast'
+
+/**
+ * Rehype plugin to extract metadata from `<code>` blocks in markdown
+ * and attach them as props to the parent `<pre>` element.
+ *
+ * This allows using those props inside a custom `<Pre>` component.
+ *
+ * Example:
+ * ~~~mdx
+ * ```js foo="bar" hide_copy='true'
+ * export function add(a, b) {
+ *   return a + b
+ * }
+ * ```
+ * ~~~
+ * These props are then added to the `<pre>` element
+ */
+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)
+        parent.properties ??= {}
+        parent.properties = { ...parent.properties, ...props }
+      }
+    })
+  }
+}
+
+/**
+ * Minimal parser for a metadata string into key-value pairs.
+ *
+ * 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.
+ *
+ * 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.
+ */
+function parseMetaString(metaString: ElementData['meta']): Record<string, string> {
+  if (!metaString) return {}
+
+  const props: Record<string, string> = {}
+
+  const keyValuePairRE = /([a-zA-Z_-]+)(?:=([^"'\s]+))?(?=\s|$)/g
+  for (const match of metaString.matchAll(keyValuePairRE)) {
+    let [_, key, value] = match
+    props[kebabCase(key)] = value || 'true'
+  }
+
+  return props
+}
+
+// Simple function to convert a camelCase or PascalCase string to kebab-case.
+function kebabCase(str: string) {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace('_', '-')
+    .toLowerCase()
+}

package/code-blocks/remarkDetype.ts

@@ -0,0 +1,192 @@
+export { remarkDetype }
+
+import type { Root, Parent, Code } from 'mdast'
+import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx'
+import type { VFile } from '@mdx-js/mdx/internal-create-format-aware-processors'
+import { visit } from 'unist-util-visit'
+import { assertUsage } from '../utils/assert.js'
+import { parseMetaString } from './rehypeMetaToProps.js'
+import pc from '@brillout/picocolors'
+import module from 'node:module'
+// Cannot use `import { transform } from 'detype'` as it results in errors,
+// and the package has no default export. Using `module.createRequire` instead.
+const { transform: detype } = module.createRequire(import.meta.url)('detype') as typeof import('detype')
+
+const prettierOptions: NonNullable<Parameters<typeof detype>[2]>['prettierOptions'] = {
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'none',
+}
+
+type CodeNode = {
+  codeBlock: Code
+  index: number
+  parent: Parent
+}
+
+function remarkDetype() {
+  return async function transformer(tree: Root, file: VFile) {
+    const code_nodes: CodeNode[] = []
+
+    visit(tree, 'code', (node, index, parent) => {
+      if (!parent || typeof index === 'undefined') return
+      // Skip if `node.lang` is not ts, tsx, vue, or yaml
+      if (!['ts', 'tsx', 'vue', 'yaml'].includes(node.lang || '')) return
+
+      // Skip if 'ts-only' meta is present
+      if (node.meta?.includes('ts-only')) return
+
+      // Collect this node for post-processing
+      code_nodes.push({ codeBlock: node, index, parent })
+    })
+
+    for (const node of code_nodes.reverse()) {
+      if (node.codeBlock.lang === 'yaml') {
+        transformYaml(node)
+      } else {
+        await transformTsToJs(node, file)
+      }
+    }
+  }
+}
+
+function transformYaml(node: CodeNode) {
+  const { codeBlock, index, parent } = node
+  const codeBlockContentJs = replaceFileNameSuffixes(codeBlock.value)
+
+  // Skip wrapping if the YAML code block hasn't changed
+  if (codeBlockContentJs === codeBlock.value) return
+
+  const { position, ...rest } = codeBlock
+
+  // Create a new code node for the JS version based on the modified YAML
+  const yamlJsCode: Code = {
+    ...rest,
+    value: codeBlockContentJs,
+  }
+
+  // Wrap both the original YAML and `yamlJsCode` with <CodeSnippets>
+  const yamlContainer: MdxJsxFlowElement = {
+    type: 'mdxJsxFlowElement',
+    name: 'CodeSnippets',
+    children: [yamlJsCode, codeBlock],
+    attributes: [
+      {
+        name: 'hideToggle',
+        type: 'mdxJsxAttribute',
+      },
+    ],
+  }
+  parent.children.splice(index, 1, yamlContainer)
+}
+
+async function transformTsToJs(node: CodeNode, file: VFile) {
+  const { codeBlock, index, parent } = node
+  const maxWidth = Number(parseMetaString(codeBlock.meta)['max-width'])
+  let codeBlockReplacedJs = replaceFileNameSuffixes(codeBlock.value)
+  let codeBlockContentJs = ''
+
+  // Remove TypeScript from the TS/TSX/Vue code node
+  try {
+    codeBlockContentJs = await detype(codeBlockReplacedJs, `some-dummy-filename.${codeBlock.lang}`, {
+      customizeBabelConfig(config) {
+        // Add `onlyRemoveTypeImports: true` to the internal `@babel/preset-typescript` config
+        // https://github.com/cyco130/detype/blob/46ec867e9efd31d31a312a215ca169bd6bff4726/src/transform.ts#L206
+        assertUsage(config.presets && config.presets.length === 1, 'Unexpected Babel config presets')
+        config.presets = [[config.presets[0], { onlyRemoveTypeImports: true }]]
+      },
+      removeTsComments: true,
+      prettierOptions: {
+        ...prettierOptions,
+        printWidth: maxWidth ? maxWidth : 99,
+      },
+    })
+  } catch (error) {
+    // Log errors and return original content instead of throwing
+    console.error(pc.red((error as SyntaxError).message))
+    console.error(
+      [
+        `Failed to transform the code block in: ${pc.bold(pc.blue(file.path))}.`,
+        "This likely happened due to invalid TypeScript syntax (see detype's error message above). You can either:",
+        '- Fix the code block syntax',
+        '- Set the code block language to js instead of ts',
+        '- Use custom meta or comments https://github.com/brillout/docpress#detype',
+      ].join('\n') + '\n',
+    )
+    return
+  }
+
+  // Clean up both JS and TS code contents: correct diff comments (for js only) and apply custom magic comment replacements
+  codeBlockContentJs = cleanUpCode(codeBlockContentJs.trimEnd(), true)
+  codeBlock.value = cleanUpCode(codeBlock.value)
+
+  // No wrapping needed if JS and TS code are still identical
+  if (codeBlockContentJs === codeBlock.value) return
+
+  const { position, lang, ...rest } = codeBlock
+  const attributes: MdxJsxFlowElement['attributes'] = []
+
+  const jsCode: Code = {
+    ...rest,
+    // The jsCode lang should be js|jsx|vue
+    lang: lang!.replace('t', 'j'),
+    value: codeBlockContentJs,
+  }
+
+  // Add `hideToggle` attribute (prop) to `CodeSnippets` if the only change was replacing `.ts` with `.js`
+  if (codeBlockReplacedJs === codeBlockContentJs) {
+    attributes.push({
+      name: 'hideToggle',
+      type: 'mdxJsxAttribute',
+    })
+  }
+
+  // Wrap both the original `codeBlock` and `jsCode` with <CodeSnippets>
+  const container: MdxJsxFlowElement = {
+    type: 'mdxJsxFlowElement',
+    name: 'CodeSnippets',
+    children: [jsCode, codeBlock],
+    attributes,
+  }
+  parent.children.splice(index, 1, container)
+}
+
+// Replace all '.ts' extensions with '.js'
+function replaceFileNameSuffixes(codeBlockValue: string) {
+  return codeBlockValue.replaceAll('.ts', '.js')
+}
+
+function cleanUpCode(code: string, isJsCode: boolean = false) {
+  if (isJsCode) {
+    code = correctCodeDiffComments(code)
+  }
+  return processMagicComments(code)
+}
+function processMagicComments(code: string) {
+  // @detype-replace DummyLayout Layout
+  const renameCommentRE = /^\/\/\s@detype-replace\s([^ ]+) ([^ ]+)\n/gm
+  const matches = Array.from(code.matchAll(renameCommentRE))
+
+  if (matches.length) {
+    for (let i = matches.length - 1; i >= 0; i--) {
+      const match = matches[i]
+      const [fullMatch, renameFrom, renameTo] = match
+      code = code.split(fullMatch).join('').replaceAll(renameFrom, renameTo)
+    }
+  }
+  code = code.replaceAll('// @detype-uncomment ', '')
+
+  return code
+}
+/**
+ * Correct code diff comments that detype() unexpectedly reformatted (using Prettier and Babel internally)
+ * after removing TypeScript.
+ * See https://github.com/brillout/docpress/pull/47#issuecomment-3263953899
+ * @param code Transformed Javascript code.
+ * @returns The corrected code.
+ */
+function correctCodeDiffComments(code: string) {
+  // Expected to match the code diff comments: `// [!code ++]` and `// [!code --]` started with newline and optional spaces
+  const codeDiffRE = /\n\s*\/\/\s\[!code.+\]/g
+  return code.replaceAll(codeDiffRE, (codeDiff) => codeDiff.trimStart())
+}

package/code-blocks/shikiTransformerAutoLinks.ts

@@ -0,0 +1,61 @@
+export { shikiTransformerAutoLinks }
+
+import type { ShikiTransformer } from 'shiki'
+
+const linkRE = /https:\/\/[^\s]*[^.,\s"'`]/g
+
+/**
+ * A Shiki transformer that converts plain HTTPS URLs in code blocks into clickable `<a>` links.
+ *
+ * Inspired by `@jcayzac/shiki-transformer-autolinks`, but tailored for a narrower use case.
+ */
+function shikiTransformerAutoLinks(): ShikiTransformer {
+  return {
+    name: 'docpress-shiki-autolinks',
+    span(span) {
+      if (span.children.length !== 1) return
+      let child = span.children[0]
+      if (child.type !== 'text') return
+
+      const links: { href: string; index: number }[] = []
+      const matches = Array.from(child.value.matchAll(linkRE))
+
+      // Filter out URLs that contain `${...}`. e.g. `https://star-wars.brillout.com/api/films/${id}.json`.
+      const filtered = matches.filter(([href]) => !href.includes('${'))
+      if (filtered.length === 0) return
+
+      for (const match of filtered) {
+        const [href] = match
+        links.unshift({ href, index: match.index })
+      }
+
+      const newChildren: typeof span.children = []
+      for (const { href, index } of links) {
+        const postIndex = index + href.length
+        const postValue = child.value.slice(postIndex)
+
+        if (postValue.length > 0) {
+          newChildren.unshift({ type: 'text', value: postValue })
+        }
+
+        newChildren.unshift({
+          type: 'element',
+          tagName: 'a',
+          properties: { href },
+          children: [{ type: 'text', value: href }],
+        })
+
+        child = {
+          type: 'text',
+          value: child.value.slice(0, index),
+        }
+      }
+
+      if (child.value.length > 0) {
+        newChildren.unshift(child)
+      }
+
+      span.children = newChildren
+    },
+  }
+}