@brillout/docpress 0.16.33 → 0.16.35

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), [])
@@ -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/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,7 @@ 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 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 +59,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 || hide, lvl }),
+  )
 
   const choiceGroupNode: MdxJsxFlowElement = {
     type: 'mdxJsxFlowElement',
@@ -142,7 +88,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 +111,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/utils/generateChoiceGroupCode.js

@@ -14,16 +14,7 @@ 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 { choiceGroup, mergedChoiceNodes } = resolveChoiceGroupNodes(choiceNodes);
     const attributes = [];
     const children = [];
     for (const choiceNode of mergedChoiceNodes) {
@@ -54,53 +45,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 || hide, lvl }));
     const choiceGroupNode = {
         type: 'mdxJsxFlowElement',
         name: 'ChoiceGroup',
@@ -117,7 +66,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 +86,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",
   "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",