From bd2fcd725c6e287990997b5c1b9046e0ed5c0e66 Mon Sep 17 00:00:00 2001
From: Rasmus Viloma <rasmus.viloma@intentface.com>
Date: Sun, 11 Oct 2026 23:52:49 +0300
Subject: [PATCH] feat(docs): code block tabs with a sliding indicator

---
 components/docs/code-block.tsx              |  4 +-
 components/docs/code-files.tsx              | 35 +++++---
 components/docs/code-frame.tsx              | 93 ++++++++++++++-------
 components/docs/installation-block-tabs.tsx | 41 ---------
 components/docs/installation-block.tsx      | 13 +--
 5 files changed, 97 insertions(+), 89 deletions(-)
 delete mode 100644 components/docs/installation-block-tabs.tsx

diff --git a/components/docs/code-block.tsx b/components/docs/code-block.tsx
index ebeaea7..00c197e 100644
--- a/components/docs/code-block.tsx
+++ b/components/docs/code-block.tsx
@@ -2,7 +2,7 @@ import { highlight } from "fumadocs-core/highlight";
 import type { ReactNode } from "react";
 import { codeTheme } from "@/lib/docs/code-theme";
 import { cn } from "@/lib/utils";
-import { CodeFrame, CodeTab } from "./code-frame";
+import { CodeFrame, CodeTitle } from "./code-frame";
 
 type CodeBlockProps = {
   code: string;
@@ -34,7 +34,7 @@ export const highlightCode = (code: string, lang = "tsx") =>
 
 export const CodeBlock = async ({ code, lang = "tsx", title, className }: CodeBlockProps) => (
   <CodeFrame
-    tabs={<CodeTab active={Boolean(title)}>{title ?? lang}</CodeTab>}
+    tabs={<CodeTitle active={Boolean(title)}>{title ?? lang}</CodeTitle>}
     code={code}
     className={className}
   >
diff --git a/components/docs/code-files.tsx b/components/docs/code-files.tsx
index e73c2f2..f8fa374 100644
--- a/components/docs/code-files.tsx
+++ b/components/docs/code-files.tsx
@@ -1,8 +1,9 @@
 "use client";
 
+import { Tabs } from "@base-ui/react/tabs";
 import type { ReactNode } from "react";
 import { useState } from "react";
-import { CodeFrame, CodeTab } from "./code-frame";
+import { CodeFrame, CodePanel, CodeTab, CodeTabList } from "./code-frame";
 
 export type CodeFileEntry = {
   name: string;
@@ -18,16 +19,26 @@ export const CodeFiles = ({ files, className }: { files: CodeFileEntry[]; classN
   const current = files.find((file) => file.name === name) ?? files[0];
 
   return (
-    <CodeFrame
-      className={className}
-      code={current.source}
-      tabs={files.map((file) => (
-        <CodeTab key={file.name} active={file.name === name} onClick={() => setName(file.name)}>
-          {file.name}
-        </CodeTab>
-      ))}
-    >
-      {current.code}
-    </CodeFrame>
+    <Tabs.Root value={name} onValueChange={setName}>
+      <CodeFrame
+        className={className}
+        code={current.source}
+        tabs={
+          <CodeTabList>
+            {files.map((file) => (
+              <CodeTab key={file.name} value={file.name}>
+                {file.name}
+              </CodeTab>
+            ))}
+          </CodeTabList>
+        }
+      >
+        {files.map((file) => (
+          <CodePanel key={file.name} value={file.name}>
+            {file.code}
+          </CodePanel>
+        ))}
+      </CodeFrame>
+    </Tabs.Root>
   );
 };
diff --git a/components/docs/code-frame.tsx b/components/docs/code-frame.tsx
index fbd12f2..f87329a 100644
--- a/components/docs/code-frame.tsx
+++ b/components/docs/code-frame.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import { Tabs } from "@base-ui/react/tabs";
 import { Check, Copy } from "@keyline-icons/react";
 import type { ReactNode } from "react";
 import { useCopy } from "@/hooks/use-copy";
@@ -9,6 +10,8 @@ import { cn } from "@/lib/utils";
  * The dark code chrome shared by every block in the docs: a header of file (or
  * package-manager) tabs with a copy button, over an inset code panel. Dark in
  * both themes, tinted by the theme's seeds (see --code-bg in globals.css).
+ * A tabbed frame sits inside a `Tabs.Root`, with a `CodeTabList` as its
+ * `tabs` and a `CodePanel` per tab as its children.
  */
 export const CodeFrame = ({
   tabs,
@@ -25,12 +28,12 @@ export const CodeFrame = ({
   <div
     data-code-block=""
     className={cn(
-      "not-prose flex flex-col rounded-xl bg-code-bg px-[5px] pb-[5px] shadow-code",
+      "not-prose flex flex-col rounded-xl bg-code-bg px-1.5 pb-1.5 shadow-code",
       className,
     )}
   >
-    <div className="flex h-10 shrink-0 items-center justify-between gap-2 pr-0.5 pl-[11px]">
-      <div className="flex h-full min-w-0 items-center gap-4 overflow-x-auto">{tabs}</div>
+    <div className="flex h-10 shrink-0 items-center justify-between gap-2">
+      <div className="flex h-full min-w-0 items-center overflow-x-auto">{tabs}</div>
       <CodeCopyButton code={code} />
     </div>
     <div className="overflow-hidden rounded-md bg-code-panel shadow-[inset_0_0_0_1px_rgb(255_255_255/0.07)]">
@@ -39,36 +42,70 @@ export const CodeFrame = ({
   </div>
 );
 
-/** A header tab. Without `onClick` it is a plain label (a single file's name). */
-export const CodeTab = ({
+/** The header's tab strip. The indicator slides to the active tab's label. */
+export const CodeTabList = ({ children }: { children: ReactNode }) => (
+  <Tabs.List className="relative flex h-full items-center">
+    {children}
+    <Tabs.Indicator
+      renderBeforeHydration
+      className={cn(
+        "absolute bottom-0 left-0 h-0.5 rounded-t-full bg-white/92",
+        // Inset 8px into the label on each side.
+        "w-[calc(var(--active-tab-width)-32px)] translate-x-[calc(var(--active-tab-left)+16px)]",
+        "transition-[translate,width] duration-200 ease-out motion-reduce:transition-none",
+      )}
+    />
+  </Tabs.List>
+);
+
+/** A header tab, inside a `CodeTabList`. */
+export const CodeTab = ({ value, children }: { value: string; children: ReactNode }) => (
+  <Tabs.Tab
+    value={value}
+    className={cn(
+      tabLabel,
+      "isolate cursor-pointer text-white/50 outline-none hover:text-white/80 data-active:text-white/92",
+      // A centred rounded square behind the label on hover or keyboard focus.
+      "before:absolute before:inset-x-0 before:inset-y-1.5 before:-z-10 before:rounded-md before:transition-colors",
+      "not-data-active:hover:before:bg-white/8 focus-visible:before:bg-white/8",
+    )}
+  >
+    {children}
+  </Tabs.Tab>
+);
+
+/** One tab's code, as a child of a tabbed `CodeFrame`. */
+export const CodePanel = ({ value, children }: { value: string; children: ReactNode }) => (
+  <Tabs.Panel
+    value={value}
+    className="rounded-md focus-visible:outline-2 focus-visible:outline-white/60 focus-visible:-outline-offset-2"
+  >
+    {children}
+  </Tabs.Panel>
+);
+
+/** A plain header label in place of tabs: a single file's name, or dimmed, its language. */
+export const CodeTitle = ({
   active = true,
-  onClick,
   children,
 }: {
   active?: boolean;
-  onClick?: () => void;
   children: ReactNode;
-}) => {
-  const className = cn(
-    "flex h-full shrink-0 items-center font-medium font-mono text-xs transition-colors",
-    active
-      ? "text-white/92 shadow-[inset_0_-1px_0_rgb(255_255_255/0.92)]"
-      : "text-white/50 hover:text-white/80",
-  );
+}) => (
+  <span
+    className={cn(
+      tabLabel,
+      active
+        ? "text-white/92 after:absolute after:inset-x-4 after:bottom-0 after:h-0.5 after:rounded-t-full after:bg-white/92"
+        : "text-white/50",
+    )}
+  >
+    {children}
+  </span>
+);
 
-  return onClick ? (
-    <button
-      type="button"
-      onClick={onClick}
-      aria-pressed={active}
-      className={cn(className, "cursor-pointer outline-none focus-visible:text-white")}
-    >
-      {children}
-    </button>
-  ) : (
-    <span className={className}>{children}</span>
-  );
-};
+const tabLabel =
+  "relative flex h-full shrink-0 items-center px-2 font-medium font-mono text-xs transition-colors";
 
 const CodeCopyButton = ({ code }: { code: string }) => {
   const { copy, copied } = useCopy();
@@ -79,7 +116,7 @@ const CodeCopyButton = ({ code }: { code: string }) => {
       type="button"
       onClick={() => copy(code)}
       aria-label={isCopied ? "Copied" : "Copy code"}
-      className="grid size-7 shrink-0 cursor-pointer place-items-center rounded-full text-white/56 transition-colors hover:bg-white/8 hover:text-white focus-visible:outline-2 focus-visible:outline-white/60"
+      className="grid size-7 shrink-0 cursor-pointer place-items-center rounded-md text-white/56 transition-colors hover:bg-white/8 hover:text-white focus-visible:outline-2 focus-visible:outline-white/60"
     >
       {isCopied ? <Check className="size-[15px]" /> : <Copy className="size-[15px]" />}
     </button>
diff --git a/components/docs/installation-block-tabs.tsx b/components/docs/installation-block-tabs.tsx
deleted file mode 100644
index 1749318..0000000
--- a/components/docs/installation-block-tabs.tsx
+++ /dev/null
@@ -1,41 +0,0 @@
-"use client";
-
-import type { ReactNode } from "react";
-import { useState } from "react";
-import { CodeFrame, CodeTab } from "./code-frame";
-
-export type InstallationEntry = {
-  manager: string;
-  command: string;
-  /** Pre-highlighted command, rendered on the server. */
-  code: ReactNode;
-};
-
-type InstallationBlockTabsProps = {
-  entries: InstallationEntry[];
-};
-
-// Client shell for the package-manager tabs. The server highlights every
-// command up front; this only picks which one shows.
-export const InstallationBlockTabs = ({ entries }: InstallationBlockTabsProps) => {
-  const [manager, setManager] = useState(entries[0].manager);
-  const current = entries.find((entry) => entry.manager === manager) ?? entries[0];
-
-  return (
-    <CodeFrame
-      className="my-6"
-      code={current.command}
-      tabs={entries.map((entry) => (
-        <CodeTab
-          key={entry.manager}
-          active={entry.manager === manager}
-          onClick={() => setManager(entry.manager)}
-        >
-          {entry.manager}
-        </CodeTab>
-      ))}
-    >
-      {current.code}
-    </CodeFrame>
-  );
-};
diff --git a/components/docs/installation-block.tsx b/components/docs/installation-block.tsx
index bde9734..03ae3f7 100644
--- a/components/docs/installation-block.tsx
+++ b/components/docs/installation-block.tsx
@@ -1,20 +1,21 @@
 import { PACKAGE_MANAGERS } from "@/lib/docs/package-managers";
 import { highlightCode } from "./code-block";
-import { InstallationBlockTabs } from "./installation-block-tabs";
+import { CodeFiles } from "./code-files";
 
 type InstallationBlockProps = {
   packageName: string;
 };
 
 // Server component: highlights one install command per package manager and
-// hands them all to the client shell, which shows the selected one.
+// shows them as tabs, one per manager.
 export const InstallationBlock = async ({ packageName }: InstallationBlockProps) => (
-  <InstallationBlockTabs
-    entries={
+  <CodeFiles
+    className="my-6"
+    files={
       await Promise.all(
         PACKAGE_MANAGERS.map(async ({ manager, install }) => {
-          const command = `${install} ${packageName}`;
-          return { manager, command, code: await highlightCode(command, "bash") };
+          const source = `${install} ${packageName}`;
+          return { name: manager, source, code: await highlightCode(source, "bash") };
         }),
       )
     }