feat(ui): implement deep linking in CodeTabs via URL hash (#9159)

* feat(ui): implement deep linking in CodeTabs via URL hash

* feat(site,ui): add HashContext and HashProvider for global URL state

* refactor(ui): isolate window hash logic from CodeTabs

* chore: improve code documentation for useHash hook

* feat(ui): use native DOM id for CodeTabs scrolling

* fix(site): dispatch global hashchange event on hash update

* refactor(ui-components): revert CodeTabs and use derived state in CodeTabsWithHash

* feat(rehype-shiki): route to  CodeTabsWithHash if groupId exists

---------

Co-authored-by: Claudio Wunder <cwunder@gnome.org>

Author: moshams272

apps/site/app/[locale]/layout.tsx

@@ -6,6 +6,7 @@ import { getLocale } from 'next-intl/server';
 
 import BaseLayout from '#site/layouts/Base';
 import { IBM_PLEX_MONO, OPEN_SANS } from '#site/next.fonts';
+import { HashProvider } from '#site/providers/hashProvider';
 import { ThemeProvider } from '#site/providers/themeProvider';
 
 import type { FC, PropsWithChildren } from 'react';
@@ -29,9 +30,11 @@ const RootLayout: FC<PropsWithChildren> = async ({ children }) => {
     >
       <body suppressHydrationWarning>
         <NextIntlClientProvider>
-          <ThemeProvider>
-            <BaseLayout>{children}</BaseLayout>
-          </ThemeProvider>
+          <HashProvider>
+            <ThemeProvider>
+              <BaseLayout>{children}</BaseLayout>
+            </ThemeProvider>
+          </HashProvider>
         </NextIntlClientProvider>
 
         <a

apps/site/hooks/useHash.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useSyncExternalStore, useCallback } from 'react';
+
+const subscribe = (callback: () => void) => {
+  window.addEventListener('hashchange', callback);
+  return () => window.removeEventListener('hashchange', callback);
+};
+
+const getSnapshot = () => window.location.hash.slice(1);
+const getServerSnapshot = () => '';
+
+const useHash = () => {
+  // Works in both client and server environments, provides the initial value for the store during server rendering and hydration, avoiding hydration mismatches
+  const hash = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  const setHash = useCallback((newHash: string) => {
+    window.history.replaceState(null, '', `#${newHash}`);
+    window.dispatchEvent(new Event('hashchange'));
+  }, []);
+
+  return [hash, setHash] as const;
+};
+
+export default useHash;

apps/site/mdx/components.mjs

@@ -4,6 +4,7 @@ import AlertBox from '@node-core/ui-components/Common/AlertBox';
 import BadgeGroup from '@node-core/ui-components/Common/BadgeGroup';
 import Blockquote from '@node-core/ui-components/Common/Blockquote';
 import MDXCodeTabs from '@node-core/ui-components/MDX/CodeTabs';
+import CodeTabsWithHash from '@node-core/ui-components/MDX/CodeTabs/CodeTabsWithHash';
 import {
   MDXTooltip,
   MDXTooltipContent,
@@ -58,6 +59,7 @@ export default {
   AlertBox,
   // Renders MDX CodeTabs
   CodeTabs: MDXCodeTabs,
+  CodeTabsWithHash,
   // Renders Tooltips
   MDXTooltip,
   MDXTooltipContent,

apps/site/providers/hashProvider.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { HashContext } from '@node-core/ui-components/contexts/HashContext';
+
+import useHash from '#site/hooks/useHash';
+
+import type { FC, PropsWithChildren } from 'react';
+
+export const HashProvider: FC<PropsWithChildren> = ({ children }) => {
+  const [hash, setHash] = useHash();
+
+  return <HashContext value={{ hash, setHash }}>{children}</HashContext>;
+};

packages/rehype-shiki/src/plugin.mjs

@@ -67,6 +67,7 @@ export default async function rehypeShikiji(options) {
       const codeTabsChildren = [];
 
       let defaultTab = '0';
+      let groupId;
       let currentIndex = index;
 
       while (isCodeBlock(parent?.children[currentIndex])) {
@@ -84,6 +85,11 @@ export default async function rehypeShikiji(options) {
         // Map the display names of each variant for the CodeTab
         displayNames.push(meta.displayName?.replaceAll('|', '') ?? '');
 
+        // Extract groupId if it exists
+        if (meta.groupId) {
+          groupId = meta.groupId;
+        }
+
         codeTabsChildren.push(parent?.children[currentIndex]);
 
         // If `active="true"` is provided in a CodeBox
@@ -102,12 +108,13 @@ export default async function rehypeShikiji(options) {
       if (codeTabsChildren.length >= 2) {
         const codeTabElement = {
           type: 'element',
-          tagName: 'CodeTabs',
+          tagName: groupId ? 'CodeTabsWithHash' : 'CodeTabs',
           children: codeTabsChildren,
           properties: {
             languages: languages.join('|'),
             displayNames: displayNames.join('|'),
             defaultTab,
+            groupId,
           },
         };
 

packages/ui-components/src/Common/CodeTabs/index.tsx

@@ -6,7 +6,7 @@ import styles from './index.module.css';
 
 type CodeTabsProps = Pick<
   ComponentProps<typeof Tabs>,
-  'tabs' | 'defaultValue' | 'children' | 'addons'
+  'tabs' | 'defaultValue' | 'value' | 'onValueChange' | 'children' | 'addons'
 >;
 
 const CodeTabs: FC<CodeTabsProps> = ({ ...props }) => (

packages/ui-components/src/Common/Tabs/index.tsx

@@ -7,6 +7,7 @@ import styles from './index.module.css';
 
 type Tab = {
   key: string;
+  id?: string;
   label: string;
   secondaryLabel?: string;
   value?: string;
@@ -34,6 +35,7 @@ const Tabs: FC<PropsWithChildren<TabsProps>> = ({
       {tabs.map(tab => (
         <TabsPrimitive.Trigger
           key={tab.key}
+          id={tab.id}
           value={tab.value ?? tab.key}
           className={classNames(styles.tabsTrigger, triggerClassName)}
         >

packages/ui-components/src/MDX/CodeTabs/CodeTabsWithHash.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+import { useCallback, useMemo } from 'react';
+
+import CodeTabs from '#ui/Common/CodeTabs';
+import { useHashContext } from '#ui/contexts/HashContext';
+
+import type { ComponentProps, FC } from 'react';
+
+import MDXCodeTabs from './index';
+
+type CodeTabsWithHashProps = ComponentProps<typeof MDXCodeTabs> & {
+  groupId: string;
+};
+
+const NAME_OVERRIDES: Record<string, string | undefined> = {
+  mjs: 'ESM',
+};
+
+const CodeTabsWithHash: FC<CodeTabsWithHashProps> = ({
+  languages: rawLanguages,
+  displayNames: rawDisplayNames,
+  children: codes,
+  defaultTab = '0',
+  groupId,
+  ...props
+}) => {
+  const { hash, setHash } = useHashContext();
+
+  const { tabs, languages } = useMemo(() => {
+    const occurrences: Record<string, number> = {};
+    const languages = rawLanguages.split('|');
+    const displayNames = rawDisplayNames?.split('|') ?? [];
+
+    const tabs = languages.map((language, index) => {
+      const base =
+        displayNames[index]?.trim() ||
+        NAME_OVERRIDES[language] ||
+        language.toUpperCase();
+
+      const count = occurrences[base] ?? 0;
+      occurrences[base] = count + 1;
+
+      const label = count > 0 ? `${base} (${count + 1})` : base;
+
+      return {
+        key: `${language}-${index}`,
+        label,
+        id: `${groupId}-${language}-${index}`.replace(/[^a-zA-Z0-9-_]/g, '-'),
+      };
+    });
+
+    return { tabs, languages };
+  }, [rawLanguages, rawDisplayNames, groupId]);
+
+  const activeTab =
+    tabs.find(t => t.id === hash)?.key ?? tabs[Number(defaultTab)].key;
+
+  const handleValueChange = useCallback(
+    (value: string) => {
+      const matched = tabs.find(t => t.key === value);
+      if (matched?.id) {
+        setHash(matched.id);
+      }
+    },
+    [tabs, setHash]
+  );
+
+  return (
+    <CodeTabs
+      tabs={tabs}
+      value={activeTab}
+      onValueChange={handleValueChange}
+      {...props}
+    >
+      {languages.map((_, index) => (
+        <TabsPrimitive.Content
+          forceMount
+          key={tabs[index].key}
+          value={tabs[index].key}
+        >
+          {codes[index]}
+        </TabsPrimitive.Content>
+      ))}
+    </CodeTabs>
+  );
+};
+export default CodeTabsWithHash;

…kages/ui-components/src/MDX/CodeTabs.tsx …ui-components/src/MDX/CodeTabs/index.tsxpackages/ui-components/src/MDX/CodeTabs.tsx renamed to packages/ui-components/src/MDX/CodeTabs/index.tsx packages/ui-components/src/MDX/CodeTabs.tsx renamed to packages/ui-components/src/MDX/CodeTabs/index.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import { createContext, use } from 'react';
+
+type HashContextType = {
+  hash: string;
+  setHash: (newHash: string) => void;
+};
+
+export const HashContext = createContext<HashContextType>({
+  hash: '',
+  setHash: () => {},
+});
+
+export const useHashContext = () => use(HashContext);