Add changes to switcher, tabs, and codeblock from universal gateway restructure (#1337)

I decided to take the tabs and code blocks updates in #1224 and merge
them separately into main so we can have them.

This PR:

- Replaces the docusaurus `Tabs` component with mantle tabs, which means
the entire docs site no longer uses the old docusaurus style tabs
anymore. ([Preview
here](https://ngrok-docs-git-shaquil-doc-266-copy-over-tabs-554909-ngrok-dev.vercel.app/docs/traffic-policy/actions/add-headers/#example-traffic-policy-document))


https://github.com/user-attachments/assets/1fb66470-24e2-4df7-92d1-bc1cd3a29ee1

- Adds the language tab to singular code block components ([Preview
here](https://ngrok-docs-git-shaquil-doc-266-copy-over-tabs-554909-ngrok-dev.vercel.app/docs/agent/ssh-reverse-tunnel-agent/#custom-domain))
<img width="731" alt="image"
src="https://github.com/user-attachments/assets/20c95908-a192-4a2b-8b45-374d7b51a252"
/>


- Adds the book icon with links to the SDK docs ([Preview
here](https://ngrok-docs-git-shaquil-doc-266-copy-over-tabs-554909-ngrok-dev.vercel.app/docs/agent/agent-tls-termination#step-4--start-your-upstream-server))


https://github.com/user-attachments/assets/57cf3b6b-550d-4d56-a7cd-36dd0fb353dc


## This PR also

Prevents the ConfigExample component from showing the Agent Config
variant by default. Now it only shows the Traffic Policy version by
default

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: S3Prototype

advanced-contribution-guides/README.md

@@ -0,0 +1 @@
+These guides exist to walk you through using some of the interactive components in the docs, such as `<LangSwitcher>`, `<Tabs>`, and more.

advanced-contribution-guides/codeblocks/CODEBLOCKS.md

@@ -0,0 +1,143 @@
+Table of Contents
+
+- [Creating code blocks](#creating-code-blocks)
+  - [Valid properties](#valid-properties)
+    - [`tabName`](#-tabname-)
+    - [`title`](#-title-)
+      - [`titleLink`](#-titlelink-)
+    - [`mode`](#-mode-)
+    - [`disableCopy`](#-disablecopy-)
+    - [`collapsible`](#-collapsible-)
+      - [`collapseLineNumber`](#-collapselinenumber-)
+  - [`indentation`](#-indentation-)
+
+This guide is for internal ngrok teammates who want to use the codeblock and LangSwitcher components to render code snippets in the docs.
+
+# Creating code blocks
+
+A standard codeblock will look like this:
+
+````txt
+```bash title="file-title"
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+Result:
+![An example codeblock](./img/default.png)
+
+## Valid properties
+
+The code block can take the following meta properties, which you use by adding them to the same line where you specify the language.
+
+### `tabName`
+
+Use `tabName` to rename the language tab shown in the code block component.
+
+Example:
+
+````txt
+```bash tabName="Example"
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+Result:
+![Screenshot of a language tab after tabName has been applied](./img/tabNameResult.png)
+
+### `title`
+
+Use `title` to add a file name to a code block component.
+
+Example:
+
+````txt
+```bash title="Example file"
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+Result:
+![An example codeblock with a title prop](./img/titleResult.png)
+
+#### `titleLink`
+
+After defining a `title`, use `titleLink` wrap a link around the file name of a codeblock.
+
+Example:
+
+````txt
+```bash title="Example file" titleLink=https://ngrok.com/pricing
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+![An example codeblock with title and titleLink props](./img/titleLinkResult.png)
+
+### `mode`
+
+Define which file icon appears next to the `title` of a codeblock.
+
+Example:
+
+````txt
+```bash title="Example file" mode=traffic-policy
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+![An example codeblock with title and titleLink props](./img/modeResult.png)
+
+### `disableCopy`
+
+Boolean. Decide if the "copy code" button will appear in the codeblock
+
+Example:
+
+````txt
+```bash disableCopy=true
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+![An example codeblock using the disableCopy prop](./img/disableCopyResult.png)
+
+### `collapsible`
+
+Default `false`. Decide if a codeblock will start off collapsed, truncating what's shown. The user can then expand the codeblock to see the rest.
+
+Example:
+
+````txt
+```bash collapsible
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+#### `collapseLineNumber`
+
+Choose which line number codeblock will be collapsed at.
+
+Example:
+
+````txt
+```bash title="Example file" collapsible collapseLine=20
+openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key
+```
+````
+
+## `indentation`
+
+Default `undefined`. Choose whether the code block should be indented with `tabs` or `spaces`.
+
+In general, don't use this property unless you have a specific reason. The codeblock automatically chooses the appropriate indentation based on the language.
+
+Example:
+
+````txt
+```js indendation=spaces
+function example(){
+	return console.log("example");
+}
+```
+````

advanced-contribution-guides/codeblocks/img/default.png

@@ -0,0 +1,88 @@
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import {
+	CodeBlock,
+	CodeBlockBody,
+	CodeBlockCode,
+	CodeBlockCopyButton,
+	CodeBlockExpanderButton,
+	CodeBlockHeader,
+	CodeBlockIcon,
+	CodeBlockTitle,
+	fmtCode,
+} from "@ngrok/mantle/code-block";
+import clsx from "clsx";
+import type { ReactNode } from "react";
+import { SdkButton } from "../LangSwitcher/SdkButton";
+import type { LanguageInfo } from "../LangSwitcher/data";
+
+type CodeBlockWithInfoProps = {
+	content: string | undefined;
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	language: any;
+	collapseLineNumber: number;
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	meta: any;
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	className?: any;
+	headerContent: ReactNode;
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	codeBlockProps?: any;
+	info?: LanguageInfo | undefined;
+};
+
+export function CodeBlockWithInfo({
+	content,
+	language,
+	collapseLineNumber,
+	meta,
+	className,
+	headerContent,
+	info,
+	codeBlockProps,
+}: CodeBlockWithInfoProps) {
+	const collapsible = !meta
+		? false
+		: meta.collapsible &&
+			content &&
+			content.split("\n").length > collapseLineNumber;
+
+	return (
+		<div className="flex flex-col">
+			<CodeBlock className={className} {...codeBlockProps}>
+				<CodeBlockHeader className={clsx("flex w-[100%]  justify-start p-2")}>
+					{headerContent}
+					{info && <SdkButton className="ml-auto mr-0.5" data={info} />}
+				</CodeBlockHeader>
+				<CodeBlockBody>
+					{meta?.title && (
+						<div className="mx-2 mt-3.5 flex w-[100%] items-end justify-start gap-1">
+							<>
+								{meta?.mode ? (
+									<CodeBlockIcon preset={meta.mode} />
+								) : (
+									<CodeBlockIcon preset="file" />
+								)}
+								<CodeBlockTitle>
+									{meta?.titleLink ? (
+										<a href={useBaseUrl(meta.titleLink)}>
+											<strong>{meta.title}</strong>
+										</a>
+									) : (
+										<strong>{meta?.title}</strong>
+									)}
+								</CodeBlockTitle>
+							</>
+						</div>
+					)}
+					{!meta?.disableCopy && <CodeBlockCopyButton />}
+					<CodeBlockCode
+						indentation={meta?.indentation}
+						language={language}
+						value={fmtCode`${content}`}
+					/>
+					{collapsible && <CodeBlockExpanderButton />}
+				</CodeBlockBody>
+			</CodeBlock>
+		</div>
+	);
+}

advanced-contribution-guides/codeblocks/img/disableCopyResult.png

@@ -1,4 +1,5 @@
-import { Tabs, TabsContent, TabsList, TabsTrigger } from "@ngrok/mantle/tabs";
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
 import type { ReactNode } from "react";
 import YAML, { type ToStringOptions } from "yaml";
 import { LangSwitcher } from "./LangSwitcher";
@@ -69,14 +70,14 @@ export type ConfigExampleProps = {
 	jsonMetastring?: string;
 	title?: string;
 	icon?: ReactNode;
-	hideAgentConfig?: boolean;
-	hideTrafficPolicy?: boolean;
+	showAgentConfig?: boolean;
+	showTrafficPolicy?: boolean;
 };
 
 export default function ConfigExample({
 	// Show the agent config by default
-	hideAgentConfig = false,
-	hideTrafficPolicy = false,
+	showAgentConfig = false,
+	showTrafficPolicy = true,
 	...props
 }: ConfigExampleProps) {
 	const yamlOptions = {
@@ -103,29 +104,35 @@ export default function ConfigExample({
 		agentConfig.yamlConfig,
 		agentConfig.jsonConfig,
 	);
-	if (hideAgentConfig && hideTrafficPolicy)
+
+	// if both false, throw error;
+	if (!showTrafficPolicy && !showAgentConfig) {
 		throw new Error(
-			"At least one of hideAgentConfig or hideTrafficPolicy must be false",
+			"ConfigExample error: One of showTrafficPolicy or showAgentConfig must be true",
 		);
+	}
+
+	// if only one is true, no need for <Tabs></Tabs>
+	if (!showAgentConfig) {
+		return policySnippet;
+	}
+	if (!showTrafficPolicy) {
+		return agentConfigSnippet;
+	}
+
 	return (
-		<Tabs
-			orientation="horizontal"
-			defaultValue={hideTrafficPolicy ? "agent-config" : "traffic-policy"}
-		>
-			<TabsList>
-				{hideTrafficPolicy ? null : (
-					<TabsTrigger value="traffic-policy">Traffic Policy</TabsTrigger>
-				)}
-				{hideAgentConfig ? null : (
-					<TabsTrigger value="agent-config">Agent Config</TabsTrigger>
-				)}
-			</TabsList>
-			{hideTrafficPolicy ? null : (
-				<TabsContent value="traffic-policy">{policySnippet}</TabsContent>
-			)}
-			{hideAgentConfig ? null : (
-				<TabsContent value="agent-config">{agentConfigSnippet}</TabsContent>
-			)}
+		<Tabs groupId="config-example" queryString="config-example">
+			{showTrafficPolicy ? (
+				<TabItem value="traffic-policy" label="Traffic Policy" default>
+					{policySnippet}
+				</TabItem>
+			) : null}
+
+			{showAgentConfig ? (
+				<TabItem value="agent-config" label="Agent Config">
+					{agentConfigSnippet}
+				</TabItem>
+			) : null}
 		</Tabs>
 	);
 }

advanced-contribution-guides/codeblocks/img/tabNameResult.png

@@ -0,0 +1,30 @@
+import { useContext } from "react";
+import type { LangSwitcherContextType } from "./LangSwitcherContext";
+import LangSwitcherContext from "./LangSwitcherContext";
+
+/**
+ * Renders its children only if the specified language matches the
+ * currently selected language for the LangSwithcher component.
+ * This is useful for conditionally rendering content based on the
+ * selected language.
+ */
+export function ContentSwitcher({
+	children,
+	languages,
+}: {
+	children: React.ReactNode;
+	languages: string[];
+	className?: string;
+}) {
+	const { selectedLanguage } =
+		useContext<LangSwitcherContextType>(LangSwitcherContext);
+	if (!languages?.length)
+		throw new Error("Must specify a language for the ContentSwitcher");
+
+	for (const lang of languages) {
+		if (lang === selectedLanguage) {
+			return <div className="mt-[1rem]">{children}</div>;
+		}
+	}
+	return null;
+}

advanced-contribution-guides/codeblocks/img/titleLinkResult.png

@@ -2,14 +2,16 @@ import type { SupportedLanguage } from "@ngrok/mantle/code-block";
 import { createContext } from "react";
 
 export type LangSwitcherContextType = {
-	tabLanguage: string | SupportedLanguage | null;
+	selectedLanguage: string | SupportedLanguage | null;
 	defaultLanguage: string | null;
-	updateTab: null | ((newLang: string | SupportedLanguage) => void);
+	updateSelectedLanguage:
+		| null
+		| ((newLang: string | SupportedLanguage | undefined) => void);
 };
 
 const LangSwitcherContext = createContext<LangSwitcherContextType>({
-	tabLanguage: "",
-	updateTab: null,
+	selectedLanguage: null,
+	updateSelectedLanguage: null,
 	defaultLanguage: null,
 });
 

advanced-contribution-guides/codeblocks/img/titleResult.png

@@ -0,0 +1,26 @@
+import { Button } from "@ngrok/mantle/button";
+
+export function LangTab({
+	tabText,
+	disabled = false,
+	className,
+	onClick,
+}: {
+	tabText: string;
+	className?: string;
+	disabled?: boolean;
+	onClick?: () => void;
+}) {
+	return (
+		<Button
+			disabled={disabled}
+			onClick={onClick}
+			type="button"
+			priority="neutral"
+			appearance="ghost"
+			className={className}
+		>
+			{tabText}
+		</Button>
+	);
+}