@brillout/docpress 0.16.33 → 0.16.35-commit-797f17e

package/Layout.tsx

@@ -27,7 +27,7 @@ import {
 } from './MenuModal/toggleMenuModal.js'
 import { MenuModal } from './MenuModal.js'
 import { autoScrollNav_SSR } from './autoScrollNav.js'
-import { initializeChoiceGroup_SSR } from './code-blocks/hooks/useSelectedChoice.js'
+import { initializeChoiceGroup_SSR } from './code-blocks/hooks/useCurrentSelection.js'
 import { SearchLink } from './docsearch/SearchLink.js'
 import { navigate } from 'vike/client/router'
 import { css } from './utils/css.js'

package/code-blocks/components/ChoiceGroup.css

@@ -1,13 +1,6 @@
 .choice-group {
   position: relative;
 
-  &:hover {
-    .choice-group__selects,
-    .copy-button {
-      opacity: 1;
-    }
-  }
-
   /* layout */
   --top-position: 10px;
   --border-color: hsl(0, 0%, 75%) hsl(0, 0%, 72%) hsl(0, 0%, 72%) hsl(0, 0%, 75%);
@@ -20,8 +13,6 @@
     z-index: 3;
     top: var(--top-position);
     right: 42px;
-    opacity: 0;
-    transition: opacity 0.5s ease-in-out;
   }
 
   .choice-select {
@@ -53,65 +44,10 @@
     align-items: center;
     flex-wrap: nowrap;
     background: #fff;
-    padding: 0 3px 0 5px;
+    padding: 0 6px;
     border-bottom: 1px solid rgba(0, 0, 0, 0.1);
     cursor: pointer;
     transition: background 120ms ease;
-
-    span {
-      flex: 1;
-    }
-
-    &::after {
-      width: 15px;
-      text-align: end;
-      --animation-width: 2px;
-      position: relative;
-      padding-right: var(--animation-width);
-      padding-left: var(--animation-width);
-      font-size: 1.13em;
-      color: #666;
-      left: 0;
-      transition: left 500ms ease, opacity 150ms ease-in-out;
-      opacity: 0;
-    }
-
-    .choice-select__list:hover &:hover::after {
-      opacity: 1;
-    }
-
-    &[aria-selected='true'] {
-      &::after {
-        content: '»' !important;
-        opacity: 1;
-      }
-
-      .choice-select__list:hover &:not(:hover)::after {
-        opacity: 0;
-      }
-
-      &:hover::after {
-        left: var(--animation-width);
-      }
-    }
-
-    &[aria-disabled='true'] {
-      &::after {
-        content: '⊘';
-        font-size: 1em;
-        left: 1px;
-      }
-    }
-
-    &:not([aria-selected='true']):not([aria-disabled='true']) {
-      &::after {
-        content: '«';
-      }
-
-      &:hover::after {
-        left: calc(-1 * var(--animation-width));
-      }
-    }
   }
 
   .choice-select[aria-expanded='false'] {
@@ -143,7 +79,7 @@
 
   .choice-select__option[aria-disabled='true'] {
     color: #999;
-    cursor: default;
+    cursor: not-allowed;
     opacity: 0.8;
   }
 

package/code-blocks/components/ChoiceGroup.tsx

@@ -1,7 +1,7 @@
 export { ChoiceGroup, CustomSelectsContainer }
 
 import React, { createContext, useContext, useEffect, useState } from 'react'
-import { useSelectedChoice } from '../hooks/useSelectedChoice.js'
+import { useCurrentSelection } from '../hooks/useCurrentSelection.js'
 import { useRestoreScroll } from '../hooks/useRestoreScroll.js'
 import { cls } from '../../utils/cls.js'
 import './ChoiceGroup.css'
@@ -93,8 +93,7 @@ type ChoiceGroupProps = {
 
 function ChoiceGroup({ children, choiceGroup, parentChoiceGroup }: ChoiceGroupProps) {
   const { name: groupName, choices, default: defaultChoice, lvl } = choiceGroup
-  // TODO/after-PR-merge rename useSelectedChoice useCurrentSelection
-  const [selectedChoice] = useSelectedChoice(groupName, defaultChoice)
+  const [selectedChoice] = useCurrentSelection(groupName, defaultChoice)
   const { choiceGroupAll, registerChoiceGroup } = useCustomSelectsContext()
 
   useEffect(() => registerChoiceGroup(choiceGroup, parentChoiceGroup), [])
@@ -110,7 +109,7 @@ function ChoiceGroup({ children, choiceGroup, parentChoiceGroup }: ChoiceGroupPr
         ))}
       </select>
       {children}
-      {lvl === 0 && (
+      {lvl === 0 && !choiceGroup.hidden && (
         <div className={`choice-group__selects`}>
           {choiceGroupAll
             .slice()
@@ -133,8 +132,8 @@ function CustomSelect({ choiceGroup }: { choiceGroup: ChoiceGroupWithParent }) {
     hidden,
     parentChoiceGroup,
   } = choiceGroup
-  const [selectedChoice, setSelectedChoice] = useSelectedChoice(groupName, defaultChoice)
-  const prevPositionRef = useRestoreScroll([selectedChoice])
+  const [selectedChoice, setSelectedChoice] = useCurrentSelection(groupName, defaultChoice)
+  const setPrevPosition = useRestoreScroll([selectedChoice])
   const [expanded, setExpanded] = useState(false)
   const selectedIndex = choices.indexOf(selectedChoice)
   const height = 25
@@ -153,7 +152,7 @@ function CustomSelect({ choiceGroup }: { choiceGroup: ChoiceGroupWithParent }) {
   }
   function isHidden() {
     if (parentChoiceGroup) {
-      const [parentSelectedChoice] = useSelectedChoice(parentChoiceGroup.name, parentChoiceGroup.default)
+      const [parentSelectedChoice] = useCurrentSelection(parentChoiceGroup.name, parentChoiceGroup.default)
       return !parentChoiceGroup.choices.includes(parentSelectedChoice)
     }
     return hidden
@@ -189,7 +188,7 @@ function CustomSelect({ choiceGroup }: { choiceGroup: ChoiceGroupWithParent }) {
             style={{ height }}
             onClick={handleOnClick}
           >
-            <span>{choice}</span>
+            {choice}
           </div>
         ))}
       </div>
@@ -198,7 +197,7 @@ function CustomSelect({ choiceGroup }: { choiceGroup: ChoiceGroupWithParent }) {
   function handleOnClick(e: React.MouseEvent<HTMLDivElement, MouseEvent>) {
     e.stopPropagation()
     const el = e.currentTarget
-    prevPositionRef.current = { top: el.getBoundingClientRect().top, el }
+    setPrevPosition(el)
     if (el.getAttribute('aria-selected') === 'true') {
       next()
     } else if (el.getAttribute('aria-disabled') === 'false') {

package/code-blocks/components/Pre.css

@@ -13,12 +13,6 @@ pre {
     position: relative;
   }
 
-  &:hover {
-    .copy-button {
-      opacity: 1;
-    }
-  }
-
   .copy-button {
     position: absolute !important;
     top: 10px;
@@ -28,8 +22,7 @@ pre {
     height: 25px;
     width: 30px;
     background-color: #f7f7f7;
-    opacity: 0;
-    transition: opacity 0.5s ease-in-out, background-color 0.4s ease-in-out;
+    transition: background-color 0.4s ease-in-out;
 
     &:not(:hover) {
       background-color: #eee;

package/code-blocks/components/Tabs.css

@@ -0,0 +1,53 @@
+.choice-tabs {
+  -webkit-tap-highlight-color: transparent;
+
+  /* tablist style logic */
+  select:has(option:nth-of-type(1):checked) ~ ul[role='tablist'] li:nth-of-type(1),
+  select:has(option:nth-of-type(2):checked) ~ ul[role='tablist'] li:nth-of-type(2),
+  select:has(option:nth-of-type(3):checked) ~ ul[role='tablist'] li:nth-of-type(3),
+  select:has(option:nth-of-type(4):checked) ~ ul[role='tablist'] li:nth-of-type(4),
+  select:has(option:nth-of-type(5):checked) ~ ul[role='tablist'] li:nth-of-type(5),
+  select:has(option:nth-of-type(6):checked) ~ ul[role='tablist'] li:nth-of-type(6),
+  select:has(option:nth-of-type(7):checked) ~ ul[role='tablist'] li:nth-of-type(7) {
+    border-bottom: 2px solid #aaa;
+    color: var(--color-text);
+  }
+}
+
+.choice-tabs__tab-list {
+  border-bottom: 1px solid #eaeaea;
+  margin: 0 0 10px;
+  padding: 0;
+}
+
+.choice-tabs__tab {
+  display: inline-block;
+  bottom: -1px;
+  position: relative;
+  list-style: none;
+  padding: 6px 12px;
+  cursor: pointer;
+  font-weight: 500;
+  /* lighten --color-text by 20% */
+  color: color-mix(in srgb, var(--color-text) 80%, white 20%);
+}
+
+@media screen and (max-width: 400px) {
+  .choice-tabs__tab {
+    padding: 6px 4px;
+    font-size: 0.87em;
+  }
+}
+
+.choice-tabs__tab:hover {
+  color: var(--color-text);
+}
+
+.choice-tabs__tab--disabled {
+  color: GrayText;
+  cursor: default;
+}
+
+.choice-tabs__tab:focus {
+  outline: none;
+}

package/code-blocks/components/Tabs.tsx

@@ -0,0 +1,91 @@
+export { Tabs }
+
+import React from 'react'
+import { useCurrentSelection } from '../hooks/useCurrentSelection.js'
+import { useRestoreScroll } from '../hooks/useRestoreScroll.js'
+import { usePageContext } from '../../renderer/usePageContext.js'
+import { assertUsage } from '../../utils/assert.js'
+import './Tabs.css'
+
+function Tabs({ choice }: { choice: string }) {
+  const groupName = choice
+  const pageContext = usePageContext()
+  const choicesAll = pageContext.config.docpress.choices
+  assertUsage(choicesAll && choicesAll[groupName], `${groupName} is unknown`)
+
+  const { choices, default: defaultChoice } = choicesAll[groupName]
+  const [selectedChoice, setSelectedChoice] = useCurrentSelection(groupName, defaultChoice)
+  const setPrevPosition = useRestoreScroll([selectedChoice])
+  const selectedIndex = choices.indexOf(selectedChoice)
+
+  return (
+    <div className="choice-tabs" data-choice-group={groupName}>
+      {/* Hidden select used to control tablist styling via CSS. */}
+      <select name={`choicesFor-${groupName}`} value={selectedChoice} hidden disabled>
+        {choices.map((choice, i) => (
+          <option key={i} value={choice}>
+            {choice}
+          </option>
+        ))}
+      </select>
+      <ul id={`choicesFor-${groupName}`} className="choice-tabs__tab-list" role="tablist">
+        {choices.map((choice, i) => (
+          <li
+            key={i}
+            id={choice}
+            className="choice-tabs__tab"
+            role="tab"
+            aria-selected={i === selectedIndex}
+            tabIndex={i === selectedIndex ? 0 : -1}
+            onClick={(e) => handleOnClick(e, i)}
+            onKeyDown={handleOnKeyDown}
+          >
+            {choice}
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+
+  function handleOnClick(e: React.MouseEvent<HTMLLIElement, MouseEvent>, index: number) {
+    const el = e.currentTarget
+    setPrevPosition(el)
+    setSelectedChoice(choices[index]!)
+  }
+
+  function handleOnKeyDown(e: React.KeyboardEvent<HTMLLIElement>) {
+    const el = e.currentTarget
+    let nextIndex = selectedIndex
+
+    switch (e.key) {
+      case 'ArrowRight':
+        nextIndex = (selectedIndex + 1) % choices.length
+        break
+      case 'ArrowLeft':
+        nextIndex = (selectedIndex - 1 + choices.length) % choices.length
+        break
+      case 'Home':
+        nextIndex = 0
+        break
+      case 'End':
+        nextIndex = choices.length - 1
+        break
+      default:
+        return
+    }
+
+    e.preventDefault()
+    setPrevPosition(el)
+    const nextChoice = choices[nextIndex]!
+    setSelectedChoice(nextChoice)
+    const tabEl = el.parentElement?.parentElement as HTMLDivElement
+
+    if (!isInViewport(tabEl)) tabEl.scrollIntoView({ block: 'start', behavior: 'smooth' })
+    el.focus()
+  }
+}
+
+function isInViewport(el: Element) {
+  const rect = el.getBoundingClientRect()
+  return rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth
+}

package/code-blocks/hooks/{useSelectedChoice.ts → useCurrentSelection.ts}

@@ -1,4 +1,4 @@
-export { useSelectedChoice }
+export { useCurrentSelection }
 export { initializeChoiceGroup_SSR }
 
 import { useLocalStorage } from './useLocalStorage.js'
@@ -12,7 +12,7 @@ const keyPrefix = 'docpress'
  * @param defaultValue Default choice value.
  * @returns `[selectedChoice, setSelectedChoice]`.
  */
-function useSelectedChoice(choiceGroupName: string, defaultValue: string) {
+function useCurrentSelection(choiceGroupName: string, defaultValue: string) {
   return useLocalStorage(`${keyPrefix}:choice:${choiceGroupName}`, defaultValue)
 }
 

package/code-blocks/hooks/useRestoreScroll.ts

@@ -11,7 +11,7 @@ type ScrollPosition = { top: number; el: Element }
  * preserving the user’s scroll position.
  *
  * @param deps Dependencies that trigger scroll restoration
- * @returns Ref holding the tracked element and its previous top position
+ * @returns Function to set the previous top position
  */
 function useRestoreScroll(deps: React.DependencyList) {
   const prevPositionRef = useRef<ScrollPosition | null>(null)
@@ -27,5 +27,9 @@ function useRestoreScroll(deps: React.DependencyList) {
     prevPositionRef.current = null
   }, deps)
 
-  return prevPositionRef
+  const setPrevPosition = (el: Element) => {
+    prevPositionRef.current = { top: el.getBoundingClientRect().top, el }
+  }
+
+  return setPrevPosition
 }

package/code-blocks/remarkChoiceGroup.ts

@@ -28,9 +28,8 @@ function remarkChoiceGroup() {
       }
     })
 
-    const replaced = new WeakSet()
     visit(tree, (node) => {
-      if (!('children' in node) || replaced.has(node)) return 'skip'
+      if (!('children' in node) || node.data?.customDataIsVisited) return 'skip'
 
       let start = -1
       let end = 0
@@ -43,9 +42,10 @@ function remarkChoiceGroup() {
 
         for (const choiceNodes of choiceNodesFiltered) {
           const replacement = generateChoiceGroupCode(choiceNodes, node)
+          replacement.data ??= {}
+          replacement.data.customDataIsVisited = true
           replacements.push(replacement)
         }
-        replaced.add(replacements)
 
         node.children.splice(start, end - start, ...replacements)
 
@@ -56,7 +56,7 @@ function remarkChoiceGroup() {
       for (; end < node.children.length; end++) {
         const child = node.children[end]!
 
-        if (!['code', 'mdxJsxFlowElement', 'containerDirective'].includes(child.type)) {
+        if (!['code', 'containerDirective'].includes(child.type)) {
           process()
           continue
         }
@@ -85,7 +85,6 @@ function filterChoices(nodes: ChoiceNode['children']) {
       .map((node) => {
         const choice = node.data!.customDataChoice!
         const nodes = nodesByChoice.get(choice) ?? []
-        node.data!.customDataChoice = undefined
         nodes.push(node)
         nodesByChoice.set(choice, nodes)
       })
@@ -99,6 +98,7 @@ function filterChoices(nodes: ChoiceNode['children']) {
 
 declare module 'mdast' {
   export interface Data {
+    customDataIsVisited?: boolean
     customDataChoice?: string
     customDataFilter?: string
     customDataParentChoiceGroup?: {

package/code-blocks/remarkDetype.ts

@@ -33,6 +33,9 @@ function remarkDetype() {
       // Skip if 'ts-only' meta is present
       if (node.meta?.includes('ts-only')) return
 
+      // Skip if 'customDataChoice' is 'TypeScript'
+      if (node.data?.customDataChoice === 'TypeScript') return
+
       // Collect this node for post-processing
       code_nodes.push({ codeBlock: node, index, parent })
     })
@@ -54,9 +57,6 @@ function transformYaml(node: CodeNode) {
   // Skip wrapping if the YAML code block hasn't changed
   if (codeBlockContentJs === codeBlock.value) return
 
-  const meta = parseMetaString(codeBlock.meta, ['choice'])
-  const { choice } = meta.props
-  codeBlock.meta = meta.rest
   const { position, ...rest } = codeBlock
 
   // Create a new code node for the JS version based on the modified YAML
@@ -71,21 +71,16 @@ function transformYaml(node: CodeNode) {
     { choiceValue: 'TypeScript', children: [codeBlock] },
   ]
   const replacement = generateChoiceGroupCode(choiceNodes, parent, true)
-  replacement.data ??= { customDataChoice: choice, customDataFilter: 'codeLang' }
 
   parent.children.splice(index, 1, replacement)
 }
 
 async function transformTsToJs(node: CodeNode, file: VFile) {
   const { codeBlock, index, parent } = node
-  const meta = parseMetaString(codeBlock.meta, ['max-width', 'choice'])
+  const meta = parseMetaString(codeBlock.meta, ['max-width'])
   const maxWidth = Number(meta.props['max-width'])
-  const { choice } = meta.props
   codeBlock.meta = meta.rest
 
-  codeBlock.data ??= { customDataChoice: choice, customDataFilter: 'codeLang' }
-  if (choice === 'TypeScript') return
-
   let codeBlockReplacedJs = replaceFileNameSuffixes(codeBlock.value)
   let codeBlockContentJs = ''
 
@@ -126,7 +121,7 @@ async function transformTsToJs(node: CodeNode, file: VFile) {
   // No wrapping needed if JS and TS code are still identical
   if (codeBlockContentJs === codeBlock.value) return
 
-  const { position, lang, data, ...rest } = codeBlock
+  const { position, lang, ...rest } = codeBlock
 
   const tsCode: Code = { ...rest, lang }
   const jsCode: Code = {
@@ -145,8 +140,6 @@ async function transformTsToJs(node: CodeNode, file: VFile) {
   const hide = codeBlockReplacedJs === codeBlockContentJs
   const replacement = generateChoiceGroupCode(choiceNodes, parent, hide)
 
-  replacement.data ??= { ...data }
-
   parent.children.splice(index, 1, replacement)
 }
 

package/code-blocks/remarkPkgManager.ts

@@ -4,7 +4,6 @@ import type { Code, Root } from 'mdast'
 import type { VFile } from '@mdx-js/mdx/internal-create-format-aware-processors'
 import { visit } from 'unist-util-visit'
 import convert_ from 'npm-to-yarn'
-import { parseMetaString } from './rehypeMetaToProps.js'
 import { generateChoiceGroupCode } from './utils/generateChoiceGroupCode.js'
 import { assertUsage } from '../utils/assert.js'
 import pc from '@brillout/picocolors'
@@ -25,15 +24,8 @@ function remarkPkgManager() {
         }. Replace it with the equivalent 'npm' command for the package manager toggle to work.`,
       )
       if (!node.value.includes('npm ') && !node.value.includes('npx ')) return
-      let choice: string | undefined = undefined
       const nodes = new Map<string, Code>()
 
-      if (node.meta) {
-        const meta = parseMetaString(node.meta, ['choice'])
-        choice = meta.props['choice']
-        node.meta = meta.rest
-      }
-
       node.value = node.value.replaceAll('npm i ', 'npm install ')
       nodes.set('npm', node)
 
@@ -49,7 +41,6 @@ function remarkPkgManager() {
       const choiceNodes = [...nodes].map(([name, node]) => ({ choiceValue: name, children: [node] }))
       const replacement = generateChoiceGroupCode(choiceNodes, parent)
 
-      replacement.data ??= { customDataChoice: choice, customDataFilter: replacement.type }
       parent.children.splice(index, 1, replacement)
     })
   }

package/code-blocks/utils/generateChoiceGroupCode.ts

@@ -1,7 +1,6 @@
 export { generateChoiceGroupCode }
 export type { ChoiceNode }
 
-import type { VikeConfig } from 'vike/types'
 import type { BlockContent, DefinitionContent, Parent } from 'mdast'
 import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx-jsx'
 import { getVikeConfig } from 'vike/plugin'
@@ -26,20 +25,12 @@ const CHOICES_BUILT_IN: Record<string, { choices: string[]; default: string }> =
 
 function generateChoiceGroupCode(choiceNodes: ChoiceNode[], parent: Parent, hide: boolean = false): MdxJsxFlowElement {
   let lvl: number = 0
+  const customHidden = choiceNodes.some((node) =>
+    node.children.some((node) => node.type === 'containerDirective' && node.children[0]!.type !== 'code'),
+  )
+  const hidden = hide || customHidden
 
-  const vikeConfig = getVikeConfig()
-  const choices = choiceNodes.map((choiceNode) => choiceNode.choiceValue)
-  const choiceGroup = findChoiceGroup(vikeConfig, choices)
-
-  const mergedChoiceNodes = choiceGroup.choices.map((choice) => {
-    const node = choiceNodes.find((n) => n.choiceValue === choice)
-
-    return {
-      choiceValue: choice,
-      children: node?.children ?? [],
-    }
-  })
-
+  const { choiceGroup, mergedChoiceNodes } = resolveChoiceGroupNodes(choiceNodes)
   const attributes: MdxJsxAttribute[] = []
   const children: MdxJsxFlowElement[] = []
 
@@ -73,55 +64,15 @@ function generateChoiceGroupCode(choiceNodes: ChoiceNode[], parent: Parent, hide
   if (parent.data?.customDataParentChoiceGroup) {
     const { lvl: parentLvl, ...parentChoiceGroup } = parent.data.customDataParentChoiceGroup
 
-    attributes.push({
-      type: 'mdxJsxAttribute',
-      name: 'parentChoiceGroup',
-      value: {
-        type: 'mdxJsxAttributeValueExpression',
-        value: '',
-        data: {
-          estree: {
-            type: 'Program',
-            sourceType: 'module',
-            comments: [],
-            body: [
-              // @ts-ignore: Missing properties in type definition
-              {
-                type: 'ExpressionStatement',
-                expression: valueToEstree(parentChoiceGroup),
-              },
-            ],
-          },
-        },
-      },
-    })
+    attributes.push(expressionToAttribute('parentChoiceGroup', parentChoiceGroup))
 
     lvl = parentLvl + 1
     parent.data.customDataParentChoiceGroup = undefined
   }
 
-  attributes.push({
-    type: 'mdxJsxAttribute',
-    name: 'choiceGroup',
-    value: {
-      type: 'mdxJsxAttributeValueExpression',
-      value: '',
-      data: {
-        estree: {
-          type: 'Program',
-          sourceType: 'module',
-          comments: [],
-          body: [
-            // @ts-ignore: Missing properties in type definition
-            {
-              type: 'ExpressionStatement',
-              expression: valueToEstree({ ...choiceGroup, hidden: choiceNodes.length === 1 || hide, lvl }),
-            },
-          ],
-        },
-      },
-    },
-  })
+  attributes.push(
+    expressionToAttribute('choiceGroup', { ...choiceGroup, hidden: choiceNodes.length === 1 || hidden, lvl }),
+  )
 
   const choiceGroupNode: MdxJsxFlowElement = {
     type: 'mdxJsxFlowElement',
@@ -142,7 +93,9 @@ function generateChoiceGroupCode(choiceNodes: ChoiceNode[], parent: Parent, hide
   return choiceGroupNode
 }
 
-function findChoiceGroup(vikeConfig: VikeConfig, choices: string[]) {
+function resolveChoiceGroupNodes(choiceNodes: ChoiceNode[]) {
+  const vikeConfig = getVikeConfig()
+  const choices = choiceNodes.map((choiceNode) => choiceNode.choiceValue)
   const { choices: choicesConfig } = vikeConfig.config.docpress
   const choicesAll = { ...CHOICES_BUILT_IN, ...choicesConfig }
 
@@ -163,5 +116,39 @@ function findChoiceGroup(vikeConfig: VikeConfig, choices: string[]) {
     disabled,
   }
 
-  return choiceGroup
+  const mergedChoiceNodes: ChoiceNode[] = choiceGroup.choices.map((choice) => {
+    const node = choiceNodes.find((node) => node.choiceValue === choice)
+
+    return {
+      choiceValue: choice,
+      children: node?.children ?? [],
+    }
+  })
+
+  return { choiceGroup, mergedChoiceNodes }
+}
+
+function expressionToAttribute(name: string, value: unknown): MdxJsxAttribute {
+  return {
+    type: 'mdxJsxAttribute',
+    name,
+    value: {
+      type: 'mdxJsxAttributeValueExpression',
+      value: '',
+      data: {
+        estree: {
+          type: 'Program',
+          sourceType: 'module',
+          comments: [],
+          body: [
+            // @ts-ignore: Missing properties in type definition
+            {
+              type: 'ExpressionStatement',
+              expression: valueToEstree(value),
+            },
+          ],
+        },
+      },
+    },
+  }
 }

package/components/index.ts

@@ -8,3 +8,4 @@ export * from './HorizontalLine.js'
 export * from './CodeBlockTransformer.js'
 export * from './Comment.js'
 export * from './FileRemoved.js'
+export * from '../code-blocks/components/Tabs.js'

package/dist/code-blocks/components/Tabs.d.ts

@@ -0,0 +1,6 @@
+export { Tabs };
+import React from 'react';
+import './Tabs.css';
+declare function Tabs({ choice }: {
+    choice: string;
+}): React.JSX.Element;

package/dist/code-blocks/components/Tabs.js

@@ -0,0 +1,57 @@
+export { Tabs };
+import React from 'react';
+import { useCurrentSelection } from '../hooks/useCurrentSelection.js';
+import { useRestoreScroll } from '../hooks/useRestoreScroll.js';
+import { usePageContext } from '../../renderer/usePageContext.js';
+import { assertUsage } from '../../utils/assert.js';
+import './Tabs.css';
+function Tabs({ choice }) {
+    const groupName = choice;
+    const pageContext = usePageContext();
+    const choicesAll = pageContext.config.docpress.choices;
+    assertUsage(choicesAll && choicesAll[groupName], `${groupName} is unknown`);
+    const { choices, default: defaultChoice } = choicesAll[groupName];
+    const [selectedChoice, setSelectedChoice] = useCurrentSelection(groupName, defaultChoice);
+    const setPrevPosition = useRestoreScroll([selectedChoice]);
+    const selectedIndex = choices.indexOf(selectedChoice);
+    return (React.createElement("div", { className: "choice-tabs", "data-choice-group": groupName },
+        React.createElement("select", { name: `choicesFor-${groupName}`, value: selectedChoice, hidden: true, disabled: true }, choices.map((choice, i) => (React.createElement("option", { key: i, value: choice }, choice)))),
+        React.createElement("ul", { id: `choicesFor-${groupName}`, className: "choice-tabs__tab-list", role: "tablist" }, choices.map((choice, i) => (React.createElement("li", { key: i, id: choice, className: "choice-tabs__tab", role: "tab", "aria-selected": i === selectedIndex, tabIndex: i === selectedIndex ? 0 : -1, onClick: (e) => handleOnClick(e, i), onKeyDown: handleOnKeyDown }, choice))))));
+    function handleOnClick(e, index) {
+        const el = e.currentTarget;
+        setPrevPosition(el);
+        setSelectedChoice(choices[index]);
+    }
+    function handleOnKeyDown(e) {
+        const el = e.currentTarget;
+        let nextIndex = selectedIndex;
+        switch (e.key) {
+            case 'ArrowRight':
+                nextIndex = (selectedIndex + 1) % choices.length;
+                break;
+            case 'ArrowLeft':
+                nextIndex = (selectedIndex - 1 + choices.length) % choices.length;
+                break;
+            case 'Home':
+                nextIndex = 0;
+                break;
+            case 'End':
+                nextIndex = choices.length - 1;
+                break;
+            default:
+                return;
+        }
+        e.preventDefault();
+        setPrevPosition(el);
+        const nextChoice = choices[nextIndex];
+        setSelectedChoice(nextChoice);
+        const tabEl = el.parentElement?.parentElement;
+        if (!isInViewport(tabEl))
+            tabEl.scrollIntoView({ block: 'start', behavior: 'smooth' });
+        el.focus();
+    }
+}
+function isInViewport(el) {
+    const rect = el.getBoundingClientRect();
+    return rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth;
+}

package/dist/code-blocks/hooks/useCurrentSelection.d.ts

@@ -0,0 +1,11 @@
+export { useCurrentSelection };
+export { initializeChoiceGroup_SSR };
+/**
+ * Stores and retrieves a selected choice from local storage.
+ *
+ * @param choiceGroupName Group name for the stored choice.
+ * @param defaultValue Default choice value.
+ * @returns `[selectedChoice, setSelectedChoice]`.
+ */
+declare function useCurrentSelection(choiceGroupName: string, defaultValue: string): readonly [string, (value: string) => void];
+declare const initializeChoiceGroup_SSR: string;

package/dist/code-blocks/hooks/useCurrentSelection.js

@@ -0,0 +1,34 @@
+export { useCurrentSelection };
+export { initializeChoiceGroup_SSR };
+import { useLocalStorage } from './useLocalStorage.js';
+const keyPrefix = 'docpress';
+/**
+ * Stores and retrieves a selected choice from local storage.
+ *
+ * @param choiceGroupName Group name for the stored choice.
+ * @param defaultValue Default choice value.
+ * @returns `[selectedChoice, setSelectedChoice]`.
+ */
+function useCurrentSelection(choiceGroupName, defaultValue) {
+    return useLocalStorage(`${keyPrefix}:choice:${choiceGroupName}`, defaultValue);
+}
+// WARNING: We cannot use `keyPrefix` here: closures don't work because we serialize the function.
+const initializeChoiceGroup_SSR = `initializeChoiceGroup();${initializeChoiceGroup.toString()};`;
+function initializeChoiceGroup() {
+    const groupsElements = document.querySelectorAll('[data-choice-group]');
+    for (const groupEl of groupsElements) {
+        const choiceGroupName = groupEl.getAttribute('data-choice-group');
+        const storageKey = `docpress:choice:${choiceGroupName}`;
+        const selectedChoice = localStorage.getItem(storageKey);
+        if (selectedChoice) {
+            const selectEl = groupEl.querySelector(`select[name="choicesFor-${choiceGroupName}"]`);
+            const selectedIndex = [...selectEl.options].findIndex((option) => option.value === selectedChoice);
+            if (selectedIndex === -1) {
+                localStorage.removeItem(storageKey);
+            }
+            else {
+                selectEl.value = selectedChoice;
+            }
+        }
+    }
+}

package/dist/code-blocks/hooks/useLocalStorage.d.ts

@@ -0,0 +1,10 @@
+export { useLocalStorage };
+/**
+ * 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]`.
+ */
+declare function useLocalStorage(storageKey: string, clientValue: string, ssrValue?: string): readonly [string, (value: string) => void];

package/dist/code-blocks/hooks/useLocalStorage.js

@@ -0,0 +1,31 @@
+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, clientValue, ssrValue) {
+    const subscribe = useCallback((callback) => {
+        const listener = (e) => {
+            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) => {
+        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];
+}

package/dist/code-blocks/hooks/useRestoreScroll.d.ts

@@ -0,0 +1,12 @@
+export { useRestoreScroll };
+import React from 'react';
+/**
+ * useRestoreScroll
+ *
+ * Keeps the page from jumping when content changes,
+ * preserving the user’s scroll position.
+ *
+ * @param deps Dependencies that trigger scroll restoration
+ * @returns Function to set the previous top position
+ */
+declare function useRestoreScroll(deps: React.DependencyList): (el: Element) => void;

package/dist/code-blocks/hooks/useRestoreScroll.js

@@ -0,0 +1,27 @@
+export { useRestoreScroll };
+import { useEffect, useRef } from 'react';
+/**
+ * useRestoreScroll
+ *
+ * Keeps the page from jumping when content changes,
+ * preserving the user’s scroll position.
+ *
+ * @param deps Dependencies that trigger scroll restoration
+ * @returns Function to set the previous top position
+ */
+function useRestoreScroll(deps) {
+    const prevPositionRef = useRef(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);
+    const setPrevPosition = (el) => {
+        prevPositionRef.current = { top: el.getBoundingClientRect().top, el };
+    };
+    return setPrevPosition;
+}

package/dist/code-blocks/remarkChoiceGroup.d.ts

@@ -3,6 +3,7 @@ import type { Root } from 'mdast';
 declare function remarkChoiceGroup(): (tree: Root) => void;
 declare module 'mdast' {
     interface Data {
+        customDataIsVisited?: boolean;
         customDataChoice?: string;
         customDataFilter?: string;
         customDataParentChoiceGroup?: {

package/dist/code-blocks/remarkChoiceGroup.js

@@ -24,9 +24,8 @@ function remarkChoiceGroup() {
                 }
             }
         });
-        const replaced = new WeakSet();
         visit(tree, (node) => {
-            if (!('children' in node) || replaced.has(node))
+            if (!('children' in node) || node.data?.customDataIsVisited)
                 return 'skip';
             let start = -1;
             let end = 0;
@@ -38,16 +37,17 @@ function remarkChoiceGroup() {
                 const replacements = [];
                 for (const choiceNodes of choiceNodesFiltered) {
                     const replacement = generateChoiceGroupCode(choiceNodes, node);
+                    replacement.data ?? (replacement.data = {});
+                    replacement.data.customDataIsVisited = true;
                     replacements.push(replacement);
                 }
-                replaced.add(replacements);
                 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)) {
+                if (!['code', 'containerDirective'].includes(child.type)) {
                     process();
                     continue;
                 }
@@ -72,7 +72,6 @@ function filterChoices(nodes) {
             .map((node) => {
             const choice = node.data.customDataChoice;
             const nodes = nodesByChoice.get(choice) ?? [];
-            node.data.customDataChoice = undefined;
             nodes.push(node);
             nodesByChoice.set(choice, nodes);
         });

package/dist/code-blocks/remarkDetype.js

@@ -22,6 +22,9 @@ function remarkDetype() {
             // Skip if 'ts-only' meta is present
             if (node.meta?.includes('ts-only'))
                 return;
+            // Skip if 'customDataChoice' is 'TypeScript'
+            if (node.data?.customDataChoice === 'TypeScript')
+                return;
             // Collect this node for post-processing
             code_nodes.push({ codeBlock: node, index, parent });
         });
@@ -41,9 +44,6 @@ function transformYaml(node) {
     // Skip wrapping if the YAML code block hasn't changed
     if (codeBlockContentJs === codeBlock.value)
         return;
-    const meta = parseMetaString(codeBlock.meta, ['choice']);
-    const { choice } = meta.props;
-    codeBlock.meta = meta.rest;
     const { position, ...rest } = codeBlock;
     // Create a new code node for the JS version based on the modified YAML
     const yamlJsCode = {
@@ -56,18 +56,13 @@ function transformYaml(node) {
         { choiceValue: 'TypeScript', children: [codeBlock] },
     ];
     const replacement = generateChoiceGroupCode(choiceNodes, parent, true);
-    replacement.data ?? (replacement.data = { customDataChoice: choice, customDataFilter: 'codeLang' });
     parent.children.splice(index, 1, replacement);
 }
 async function transformTsToJs(node, file) {
     const { codeBlock, index, parent } = node;
-    const meta = parseMetaString(codeBlock.meta, ['max-width', 'choice']);
+    const meta = parseMetaString(codeBlock.meta, ['max-width']);
     const maxWidth = Number(meta.props['max-width']);
-    const { choice } = meta.props;
     codeBlock.meta = meta.rest;
-    codeBlock.data ?? (codeBlock.data = { customDataChoice: choice, customDataFilter: 'codeLang' });
-    if (choice === 'TypeScript')
-        return;
     let codeBlockReplacedJs = replaceFileNameSuffixes(codeBlock.value);
     let codeBlockContentJs = '';
     // Remove TypeScript from the TS/TSX/Vue code node
@@ -104,7 +99,7 @@ async function transformTsToJs(node, file) {
     // No wrapping needed if JS and TS code are still identical
     if (codeBlockContentJs === codeBlock.value)
         return;
-    const { position, lang, data, ...rest } = codeBlock;
+    const { position, lang, ...rest } = codeBlock;
     const tsCode = { ...rest, lang };
     const jsCode = {
         ...rest,
@@ -120,7 +115,6 @@ async function transformTsToJs(node, file) {
     // Add `hide` prop to `<ChoiceGroup>` if the only change was replacing `.ts` with `.js`
     const hide = codeBlockReplacedJs === codeBlockContentJs;
     const replacement = generateChoiceGroupCode(choiceNodes, parent, hide);
-    replacement.data ?? (replacement.data = { ...data });
     parent.children.splice(index, 1, replacement);
 }
 // Replace all '.ts' extensions with '.js'

package/dist/code-blocks/remarkPkgManager.js

@@ -1,7 +1,6 @@
 export { remarkPkgManager };
 import { visit } from 'unist-util-visit';
 import convert_ from 'npm-to-yarn';
-import { parseMetaString } from './rehypeMetaToProps.js';
 import { generateChoiceGroupCode } from './utils/generateChoiceGroupCode.js';
 import { assertUsage } from '../utils/assert.js';
 import pc from '@brillout/picocolors';
@@ -18,13 +17,7 @@ function remarkPkgManager() {
             assertUsage(!node.value.includes('pnpm'), `Found a 'pnpm' command in the code block at: ${pc.bold(pc.blue(file.path))}, line ${node.position?.start.line}. Replace it with the equivalent 'npm' command for the package manager toggle to work.`);
             if (!node.value.includes('npm ') && !node.value.includes('npx '))
                 return;
-            let choice = undefined;
             const nodes = new Map();
-            if (node.meta) {
-                const meta = parseMetaString(node.meta, ['choice']);
-                choice = meta.props['choice'];
-                node.meta = meta.rest;
-            }
             node.value = node.value.replaceAll('npm i ', 'npm install ');
             nodes.set('npm', node);
             for (const pm of PKG_MANAGERS) {
@@ -37,7 +30,6 @@ function remarkPkgManager() {
             }
             const choiceNodes = [...nodes].map(([name, node]) => ({ choiceValue: name, children: [node] }));
             const replacement = generateChoiceGroupCode(choiceNodes, parent);
-            replacement.data ?? (replacement.data = { customDataChoice: choice, customDataFilter: replacement.type });
             parent.children.splice(index, 1, replacement);
         });
     };

package/dist/code-blocks/utils/generateChoiceGroupCode.js

@@ -14,16 +14,9 @@ const CHOICES_BUILT_IN = {
 };
 function generateChoiceGroupCode(choiceNodes, parent, hide = false) {
     let lvl = 0;
-    const vikeConfig = getVikeConfig();
-    const choices = choiceNodes.map((choiceNode) => choiceNode.choiceValue);
-    const choiceGroup = findChoiceGroup(vikeConfig, choices);
-    const mergedChoiceNodes = choiceGroup.choices.map((choice) => {
-        const node = choiceNodes.find((n) => n.choiceValue === choice);
-        return {
-            choiceValue: choice,
-            children: node?.children ?? [],
-        };
-    });
+    const customHidden = choiceNodes.some((node) => node.children.some((node) => node.type === 'containerDirective' && node.children[0].type !== 'code'));
+    const hidden = hide || customHidden;
+    const { choiceGroup, mergedChoiceNodes } = resolveChoiceGroupNodes(choiceNodes);
     const attributes = [];
     const children = [];
     for (const choiceNode of mergedChoiceNodes) {
@@ -54,53 +47,11 @@ function generateChoiceGroupCode(choiceNodes, parent, hide = false) {
     }
     if (parent.data?.customDataParentChoiceGroup) {
         const { lvl: parentLvl, ...parentChoiceGroup } = parent.data.customDataParentChoiceGroup;
-        attributes.push({
-            type: 'mdxJsxAttribute',
-            name: 'parentChoiceGroup',
-            value: {
-                type: 'mdxJsxAttributeValueExpression',
-                value: '',
-                data: {
-                    estree: {
-                        type: 'Program',
-                        sourceType: 'module',
-                        comments: [],
-                        body: [
-                            // @ts-ignore: Missing properties in type definition
-                            {
-                                type: 'ExpressionStatement',
-                                expression: valueToEstree(parentChoiceGroup),
-                            },
-                        ],
-                    },
-                },
-            },
-        });
+        attributes.push(expressionToAttribute('parentChoiceGroup', parentChoiceGroup));
         lvl = parentLvl + 1;
         parent.data.customDataParentChoiceGroup = undefined;
     }
-    attributes.push({
-        type: 'mdxJsxAttribute',
-        name: 'choiceGroup',
-        value: {
-            type: 'mdxJsxAttributeValueExpression',
-            value: '',
-            data: {
-                estree: {
-                    type: 'Program',
-                    sourceType: 'module',
-                    comments: [],
-                    body: [
-                        // @ts-ignore: Missing properties in type definition
-                        {
-                            type: 'ExpressionStatement',
-                            expression: valueToEstree({ ...choiceGroup, hidden: choiceNodes.length === 1 || hide, lvl }),
-                        },
-                    ],
-                },
-            },
-        },
-    });
+    attributes.push(expressionToAttribute('choiceGroup', { ...choiceGroup, hidden: choiceNodes.length === 1 || hidden, lvl }));
     const choiceGroupNode = {
         type: 'mdxJsxFlowElement',
         name: 'ChoiceGroup',
@@ -117,7 +68,9 @@ function generateChoiceGroupCode(choiceNodes, parent, hide = false) {
     }
     return choiceGroupNode;
 }
-function findChoiceGroup(vikeConfig, choices) {
+function resolveChoiceGroupNodes(choiceNodes) {
+    const vikeConfig = getVikeConfig();
+    const choices = choiceNodes.map((choiceNode) => choiceNode.choiceValue);
     const { choices: choicesConfig } = vikeConfig.config.docpress;
     const choicesAll = { ...CHOICES_BUILT_IN, ...choicesConfig };
     const groupName = Object.keys(choicesAll).find((key) => {
@@ -135,5 +88,36 @@ function findChoiceGroup(vikeConfig, choices) {
         ...choicesAll[groupName],
         disabled,
     };
-    return choiceGroup;
+    const mergedChoiceNodes = choiceGroup.choices.map((choice) => {
+        const node = choiceNodes.find((node) => node.choiceValue === choice);
+        return {
+            choiceValue: choice,
+            children: node?.children ?? [],
+        };
+    });
+    return { choiceGroup, mergedChoiceNodes };
+}
+function expressionToAttribute(name, value) {
+    return {
+        type: 'mdxJsxAttribute',
+        name,
+        value: {
+            type: 'mdxJsxAttributeValueExpression',
+            value: '',
+            data: {
+                estree: {
+                    type: 'Program',
+                    sourceType: 'module',
+                    comments: [],
+                    body: [
+                        // @ts-ignore: Missing properties in type definition
+                        {
+                            type: 'ExpressionStatement',
+                            expression: valueToEstree(value),
+                        },
+                    ],
+                },
+            },
+        },
+    };
 }

package/dist/components/index.d.ts

@@ -8,3 +8,4 @@ export * from './HorizontalLine.js';
 export * from './CodeBlockTransformer.js';
 export * from './Comment.js';
 export * from './FileRemoved.js';
+export * from '../code-blocks/components/Tabs.js';

package/dist/components/index.js

@@ -8,3 +8,4 @@ export * from './HorizontalLine.js';
 export * from './CodeBlockTransformer.js';
 export * from './Comment.js';
 export * from './FileRemoved.js';
+export * from '../code-blocks/components/Tabs.js';

package/icons/index.ts

@@ -1,14 +1,21 @@
 // Playground: https://www.figma.com/design/EFFQgT1aDH5exs2bABaIFJ/Icons?t=y0K2dHfJgpxMIl1e-0
-export { default as iconGear } from './gear.svg'
+export { default as iconBluesky } from './bluesky.svg'
 export { default as iconBooks } from './books.svg'
-export { default as iconSeedling } from './seedling.svg'
-export { default as iconMagnifyingGlass } from './magnifying-glass.svg'
-export { default as iconPencil } from './pencil.svg'
+export { default as iconChangelog } from './changelog.svg'
+export { default as iconCoin } from './coin.svg'
 export { default as iconCompass } from './compass.svg'
-export { default as iconScroll } from './scroll.svg'
+export { default as iconDiscord } from './discord.svg'
+export { default as iconEyes } from './eyes.svg'
+export { default as iconGear } from './gear.svg'
+export { default as iconGithub } from './github.svg'
 export { default as iconGlobe } from './globe.svg'
-export { default as iconPlug } from './plug.svg'
+export { default as iconLanguages } from './languages.svg'
+export { default as iconLinkedin } from './linkedin.svg'
 export { default as iconLoudspeaker } from './loudspeaker.svg'
+export { default as iconMagnifyingGlass } from './magnifying-glass.svg'
 export { default as iconMegaphone } from './megaphone.svg'
-export { default as iconCoin } from './coin.svg'
-export { default as iconEyes } from './eyes.svg'
+export { default as iconPencil } from './pencil.svg'
+export { default as iconPlug } from './plug.svg'
+export { default as iconScroll } from './scroll.svg'
+export { default as iconSeedling } from './seedling.svg'
+export { default as iconTwitter } from './twitter.svg'

package/index.ts

@@ -1,7 +1,16 @@
 /**********/
 /* PUBLIC */
 /**********/
-export { CodeBlockTransformer, Link, RepoLink, FileAdded, FileRemoved, ImportMeta, Emoji } from './components/index.js'
+export {
+  CodeBlockTransformer,
+  Link,
+  RepoLink,
+  FileAdded,
+  FileRemoved,
+  ImportMeta,
+  Emoji,
+  Tabs,
+} from './components/index.js'
 export { MenuToggle } from './Layout.js'
 export * from './components/Note.js'
 export * from './icons/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brillout/docpress",
-  "version": "0.16.33",
+  "version": "0.16.35-commit-797f17e",
   "type": "module",
   "dependencies": {
     "@brillout/picocolors": "^1.0.10",
@@ -54,12 +54,12 @@
   },
   "devDependencies": {
     "@brillout/release-me": "^0.4.8",
-    "@vitejs/plugin-react": "^6.0.1",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.0",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react": "^6.0.1",
     "mdast-util-directive": "^3.1.0",
     "mdast-util-mdx-jsx": "^3.2.0",
     "vike": "^0.4.255",