@apimatic/cli 1.4.0 → 2.0.0-beta.1

package/portal-template/src/components/example-layout.tsx

@@ -0,0 +1,99 @@
+import { createContext, useContext, useMemo, useState, type ReactNode } from 'react';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@fumadocs/api-docs/components/select';
+import { useOperationContext, useRenderContext } from 'fumadocs-openapi/ui';
+import { CodeSample } from '@/lib/code-samples';
+import { Parameter, requestExamples, type RequestExample } from '@/lib/request-examples';
+
+interface ExampleSelection {
+  operation: unknown;
+  examples: RequestExample[];
+  selected: RequestExample;
+  select: (id: string) => void;
+}
+
+interface LayoutSlots {
+  selector: ReactNode;
+  usageTabs: ReactNode;
+  responseTabs: ReactNode;
+}
+
+const SelectionContext = createContext<ExampleSelection | undefined>(undefined);
+
+export function useExampleSelection(): ExampleSelection {
+  const selection = useContext(SelectionContext);
+  if (selection === undefined) throw new Error('useExampleSelection needs an ExampleLayout above it');
+  return selection;
+}
+
+// Fumadocs' own selector lists request body examples only, and ignores an id outside that list.
+export function renderExampleLayout(slots: Readonly<LayoutSlots>): ReactNode {
+  return <ExampleLayout selector={slots.selector} usageTabs={slots.usageTabs} responseTabs={slots.responseTabs} />;
+}
+
+// Fumadocs passes a null selector for an operation with `x-exclusiveCodeSample`.
+function ExampleLayout({ selector, usageTabs, responseTabs }: Readonly<LayoutSlots>) {
+  const { schema } = useRenderContext();
+  const { route, examples: bodyExamples, example: defaultId, setExample } = useOperationContext();
+  const pathItem = schema.resolve(schema.dereferenced.paths?.[route]);
+  const operation = pathItem?.[bodyExamples[0].data.method];
+  // Only SDK samples follow a parameter's example ids; fumadocs' cURL and playground ignore them.
+  const examples = useMemo(
+    () =>
+      CodeSample.listIn(operation).length === 0
+        ? bodyExamples
+        : requestExamples(bodyExamples, Parameter.listIn(operation, pathItem, schema.resolve)),
+    [bodyExamples, operation, pathItem, schema]
+  );
+  const [selectedId, setSelectedId] = useState(defaultId);
+
+  const selection = useMemo<ExampleSelection>(
+    () => ({
+      operation,
+      examples,
+      selected: examples.find((example) => example.id === selectedId) ?? examples[0],
+      select: (id) => {
+        setSelectedId(id);
+        setExample(id);
+      }
+    }),
+    [operation, examples, selectedId, setExample]
+  );
+  return (
+    <SelectionContext.Provider value={selection}>
+      <div className="prose-no-margin">
+        {selector === null ? null : <ExampleSelector />}
+        {usageTabs}
+        {responseTabs}
+      </div>
+    </SelectionContext.Provider>
+  );
+}
+
+function ExampleSelector() {
+  const { examples, selected, select } = useExampleSelection();
+  if (examples.length === 1) return null;
+
+  const items = examples.map((example) => ({
+    value: example.id,
+    label: (
+      <div>
+        <p className="font-medium text-sm">{example.name}</p>
+        <p className="text-fd-muted-foreground">{example.description}</p>
+      </div>
+    )
+  }));
+  return (
+    <Select items={items} value={selected.id} onValueChange={(id) => id !== null && select(id)}>
+      <SelectTrigger className="not-prose mb-2">
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {items.map((item) => (
+          <SelectItem key={item.value} value={item.value}>
+            {item.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}

package/portal-template/src/components/logos.tsx

@@ -0,0 +1,127 @@
+import { useId, type ReactNode } from 'react';
+
+interface LogoProps {
+  className?: string;
+}
+
+// The languages' own coloured marks, from Devicon 2.17.0 (MIT). Python's drop shadow is left out.
+function CSharpLogo({ className }: Readonly<LogoProps>) {
+  return (
+    <svg viewBox="0 0 128 128" className={className} aria-hidden="true">
+      <path
+        fill="#9B4F96"
+        d="M115.4 30.7L67.1 2.9c-.8-.5-1.9-.7-3.1-.7-1.2 0-2.3.3-3.1.7l-48 27.9c-1.7 1-2.9 3.5-2.9 5.4v55.7c0 1.1.2 2.4 1 3.5l106.8-62c-.6-1.2-1.5-2.1-2.4-2.7z"
+      />
+      <path
+        fill="#68217A"
+        d="M10.7 95.3c.5.8 1.2 1.5 1.9 1.9l48.2 27.9c.8.5 1.9.7 3.1.7 1.2 0 2.3-.3 3.1-.7l48-27.9c1.7-1 2.9-3.5 2.9-5.4V36.1c0-.9-.1-1.9-.6-2.8l-106.6 62z"
+      />
+      <path
+        fill="#fff"
+        d="M85.3 76.1C81.1 83.5 73.1 88.5 64 88.5c-13.5 0-24.5-11-24.5-24.5s11-24.5 24.5-24.5c9.1 0 17.1 5 21.3 12.5l13-7.5c-6.8-11.9-19.6-20-34.3-20-21.8 0-39.5 17.7-39.5 39.5s17.7 39.5 39.5 39.5c14.6 0 27.4-8 34.2-19.8l-12.9-7.6zM97 66.2l.9-4.3h-4.2v-4.7h5.1L100 51h4.9l-1.2 6.1h3.8l1.2-6.1h4.8l-1.2 6.1h2.4v4.7h-3.3l-.9 4.3h4.2v4.7h-5.1l-1.2 6h-4.9l1.2-6h-3.8l-1.2 6h-4.8l1.2-6h-2.4v-4.7H97zm4.8 0h3.8l.9-4.3h-3.8l-.9 4.3z"
+      />
+    </svg>
+  );
+}
+
+function PythonLogo({ className }: Readonly<LogoProps>) {
+  // Unique per logo, so two on one page do not share, or lose, a gradient.
+  const id = useId();
+  return (
+    <svg viewBox="0 0 128 128" className={className} aria-hidden="true">
+      <linearGradient
+        id={`${id}a`}
+        gradientUnits="userSpaceOnUse"
+        x1="70.252"
+        y1="1237.476"
+        x2="170.659"
+        y2="1151.089"
+        gradientTransform="matrix(.563 0 0 -.568 -29.215 707.817)"
+      >
+        <stop offset="0" stopColor="#5A9FD4" />
+        <stop offset="1" stopColor="#306998" />
+      </linearGradient>
+      <linearGradient
+        id={`${id}b`}
+        gradientUnits="userSpaceOnUse"
+        x1="209.474"
+        y1="1098.811"
+        x2="173.62"
+        y2="1149.537"
+        gradientTransform="matrix(.563 0 0 -.568 -29.215 707.817)"
+      >
+        <stop offset="0" stopColor="#FFD43B" />
+        <stop offset="1" stopColor="#FFE873" />
+      </linearGradient>
+      <path
+        fill={`url(#${id}a)`}
+        transform="translate(0 10.26)"
+        d="M63.391 1.988c-4.222.02-8.252.379-11.8 1.007-10.45 1.846-12.346 5.71-12.346 12.837v9.411h24.693v3.137H29.977c-7.176 0-13.46 4.313-15.426 12.521-2.268 9.405-2.368 15.275 0 25.096 1.755 7.311 5.947 12.519 13.124 12.519h8.491V67.234c0-8.151 7.051-15.34 15.426-15.34h24.665c6.866 0 12.346-5.654 12.346-12.548V15.833c0-6.693-5.646-11.72-12.346-12.837-4.244-.706-8.645-1.027-12.866-1.008zM50.037 9.557c2.55 0 4.634 2.117 4.634 4.721 0 2.593-2.083 4.69-4.634 4.69-2.56 0-4.633-2.097-4.633-4.69-.001-2.604 2.073-4.721 4.633-4.721z"
+      />
+      <path
+        fill={`url(#${id}b)`}
+        transform="translate(0 10.26)"
+        d="M91.682 28.38v10.966c0 8.5-7.208 15.655-15.426 15.655H51.591c-6.756 0-12.346 5.783-12.346 12.549v23.515c0 6.691 5.818 10.628 12.346 12.547 7.816 2.297 15.312 2.713 24.665 0 6.216-1.801 12.346-5.423 12.346-12.547v-9.412H63.938v-3.138h37.012c7.176 0 9.852-5.005 12.348-12.519 2.578-7.735 2.467-15.174 0-25.096-1.774-7.145-5.161-12.521-12.348-12.521h-9.268zM77.809 87.927c2.561 0 4.634 2.097 4.634 4.692 0 2.602-2.074 4.719-4.634 4.719-2.55 0-4.633-2.117-4.633-4.719 0-2.595 2.083-4.692 4.633-4.692z"
+      />
+    </svg>
+  );
+}
+
+function TypeScriptLogo({ className }: Readonly<LogoProps>) {
+  return (
+    <svg viewBox="0 0 128 128" className={className} aria-hidden="true">
+      <path fill="#fff" d="M22.67 47h99.67v73.67H22.67z" />
+      <path
+        fill="#007acc"
+        d="M1.5 63.91v62.5h125v-125H1.5zm100.73-5a15.56 15.56 0 017.82 4.5 20.58 20.58 0 013 4c0 .16-5.4 3.81-8.69 5.85-.12.08-.6-.44-1.13-1.23a7.09 7.09 0 00-5.87-3.53c-3.79-.26-6.23 1.73-6.21 5a4.58 4.58 0 00.54 2.34c.83 1.73 2.38 2.76 7.24 4.86 8.95 3.85 12.78 6.39 15.16 10 2.66 4 3.25 10.46 1.45 15.24-2 5.2-6.9 8.73-13.83 9.9a38.32 38.32 0 01-9.52-.1 23 23 0 01-12.72-6.63c-1.15-1.27-3.39-4.58-3.25-4.82a9.34 9.34 0 011.15-.73L82 101l3.59-2.08.75 1.11a16.78 16.78 0 004.74 4.54c4 2.1 9.46 1.81 12.16-.62a5.43 5.43 0 00.69-6.92c-1-1.39-3-2.56-8.59-5-6.45-2.78-9.23-4.5-11.77-7.24a16.48 16.48 0 01-3.43-6.25 25 25 0 01-.22-8c1.33-6.23 6-10.58 12.82-11.87a31.66 31.66 0 019.49.26zm-29.34 5.24v5.12H56.66v46.23H45.15V69.26H28.88v-5a49.19 49.19 0 01.12-5.17C29.08 59 39 59 51 59h21.83z"
+      />
+    </svg>
+  );
+}
+
+// One-colour marks from Simple Icons 16.32.0 (CC0), drawn in the text colour so they follow the theme.
+function ClaudeLogo({ className }: Readonly<LogoProps>) {
+  return (
+    <svg viewBox="0 0 24 24" className={className} fill="currentColor" aria-hidden="true">
+      <path d="m4.7144 15.9555 4.7174-2.6471.079-.2307-.079-.1275h-.2307l-.7893-.0486-2.6956-.0729-2.3375-.0971-2.2646-.1214-.5707-.1215-.5343-.7042.0546-.3522.4797-.3218.686.0608 1.5179.1032 2.2767.1578 1.6514.0972 2.4468.255h.3886l.0546-.1579-.1336-.0971-.1032-.0972L6.973 9.8356l-2.55-1.6879-1.3356-.9714-.7225-.4918-.3643-.4614-.1578-1.0078.6557-.7225.8803.0607.2246.0607.8925.686 1.9064 1.4754 2.4893 1.8336.3643.3035.1457-.1032.0182-.0728-.164-.2733-1.3539-2.4467-1.445-2.4893-.6435-1.032-.17-.6194c-.0607-.255-.1032-.4674-.1032-.7285L6.287.1335 6.6997 0l.9957.1336.419.3642.6192 1.4147 1.0018 2.2282 1.5543 3.0296.4553.8985.2429.8318.091.255h.1579v-.1457l.1275-1.706.2368-2.0947.2307-2.6957.0789-.7589.3764-.9107.7468-.4918.5828.2793.4797.686-.0668.4433-.2853 1.8517-.5586 2.9021-.3643 1.9429h.2125l.2429-.2429.9835-1.3053 1.6514-2.0643.7286-.8196.85-.9046.5464-.4311h1.0321l.759 1.1293-.34 1.1657-1.0625 1.3478-.8804 1.1414-1.2628 1.7-.7893 1.36.0729.1093.1882-.0183 2.8535-.607 1.5421-.2794 1.8396-.3157.8318.3886.091.3946-.3278.8075-1.967.4857-2.3072.4614-3.4364.8136-.0425.0304.0486.0607 1.5482.1457.6618.0364h1.621l3.0175.2247.7892.522.4736.6376-.079.4857-1.2142.6193-1.6393-.3886-3.825-.9107-1.3113-.3279h-.1822v.1093l1.0929 1.0686 2.0035 1.8092 2.5075 2.3314.1275.5768-.3218.4554-.34-.0486-2.2039-1.6575-.85-.7468-1.9246-1.621h-.1275v.17l.4432.6496 2.3436 3.5214.1214 1.0807-.17.3521-.6071.2125-.6679-.1214-1.3721-1.9246L14.38 17.959l-1.1414-1.9428-.1397.079-.674 7.2552-.3156.3703-.7286.2793-.6071-.4614-.3218-.7468.3218-1.4753.3886-1.9246.3157-1.53.2853-1.9004.17-.6314-.0121-.0425-.1397.0182-1.4328 1.9672-2.1796 2.9446-1.7243 1.8456-.4128.164-.7164-.3704.0667-.6618.4008-.5889 2.386-3.0357 1.4389-1.882.929-1.0868-.0062-.1579h-.0546l-6.3385 4.1164-1.1293.1457-.4857-.4554.0608-.7467.2307-.2429 1.9064-1.3114Z" />
+    </svg>
+  );
+}
+
+function CursorLogo({ className }: Readonly<LogoProps>) {
+  return (
+    <svg viewBox="0 0 24 24" className={className} fill="currentColor" aria-hidden="true">
+      <path d="M11.503.131 1.891 5.678a.84.84 0 0 0-.42.726v11.188c0 .3.162.575.42.724l9.609 5.55a1 1 0 0 0 .998 0l9.61-5.55a.84.84 0 0 0 .42-.724V6.404a.84.84 0 0 0-.42-.726L12.497.131a1.01 1.01 0 0 0-.996 0M2.657 6.338h18.55c.263 0 .43.287.297.515L12.23 22.918c-.062.107-.229.064-.229-.06V12.335a.59.59 0 0 0-.295-.51l-9.11-5.257c-.109-.063-.064-.23.061-.23" />
+    </svg>
+  );
+}
+
+function GitHubCopilotLogo({ className }: Readonly<LogoProps>) {
+  return (
+    <svg viewBox="0 0 24 24" className={className} fill="currentColor" aria-hidden="true">
+      <path d="M23.922 16.997C23.061 18.492 18.063 22.02 12 22.02 5.937 22.02.939 18.492.078 16.997A.641.641 0 0 1 0 16.741v-2.869a.883.883 0 0 1 .053-.22c.372-.935 1.347-2.292 2.605-2.656.167-.429.414-1.055.644-1.517a10.098 10.098 0 0 1-.052-1.086c0-1.331.282-2.499 1.132-3.368.397-.406.89-.717 1.474-.952C7.255 2.937 9.248 1.98 11.978 1.98c2.731 0 4.767.957 6.166 2.093.584.235 1.077.546 1.474.952.85.869 1.132 2.037 1.132 3.368 0 .368-.014.733-.052 1.086.23.462.477 1.088.644 1.517 1.258.364 2.233 1.721 2.605 2.656a.841.841 0 0 1 .053.22v2.869a.641.641 0 0 1-.078.256Zm-11.75-5.992h-.344a4.359 4.359 0 0 1-.355.508c-.77.947-1.918 1.492-3.508 1.492-1.725 0-2.989-.359-3.782-1.259a2.137 2.137 0 0 1-.085-.104L4 11.746v6.585c1.435.779 4.514 2.179 8 2.179 3.486 0 6.565-1.4 8-2.179v-6.585l-.098-.104s-.033.045-.085.104c-.793.9-2.057 1.259-3.782 1.259-1.59 0-2.738-.545-3.508-1.492a4.359 4.359 0 0 1-.355-.508Zm2.328 3.25c.549 0 1 .451 1 1v2c0 .549-.451 1-1 1-.549 0-1-.451-1-1v-2c0-.549.451-1 1-1Zm-5 0c.549 0 1 .451 1 1v2c0 .549-.451 1-1 1-.549 0-1-.451-1-1v-2c0-.549.451-1 1-1Zm3.313-6.185c.136 1.057.403 1.913.878 2.497.442.544 1.134.938 2.344.938 1.573 0 2.292-.337 2.657-.751.384-.435.558-1.15.558-2.361 0-1.14-.243-1.847-.705-2.319-.477-.488-1.319-.862-2.824-1.025-1.487-.161-2.192.138-2.533.529-.269.307-.437.808-.438 1.578v.021c0 .265.021.562.063.893Zm-1.626 0c.042-.331.063-.628.063-.894v-.02c-.001-.77-.169-1.271-.438-1.578-.341-.391-1.046-.69-2.533-.529-1.505.163-2.347.537-2.824 1.025-.462.472-.705 1.179-.705 2.319 0 1.211.175 1.926.558 2.361.365.414 1.084.751 2.657.751 1.21 0 1.902-.394 2.344-.938.475-.584.742-1.44.878-2.497Z" />
+    </svg>
+  );
+}
+
+const LANGUAGE_LOGOS: Record<string, (props: Readonly<LogoProps>) => ReactNode> = {
+  csharp: CSharpLogo,
+  python: PythonLogo,
+  typescript: TypeScriptLogo
+};
+
+export const PLATFORMS = [
+  { name: 'Claude Code', Logo: ClaudeLogo },
+  { name: 'Cursor', Logo: CursorLogo },
+  { name: 'GitHub Copilot', Logo: GitHubCopilotLogo }
+];
+
+/** Nothing for a language without a mark, so a language added before its logo still renders. */
+export function LanguageLogo({ language, className }: Readonly<LogoProps & { language: string }>) {
+  const Logo = LANGUAGE_LOGOS[language];
+  return Logo === undefined ? null : <Logo className={className} />;
+}
+
+export function LogoTile({ children }: Readonly<{ children: ReactNode }>) {
+  return <span className="flex size-9 shrink-0 items-center justify-center rounded-lg bg-fd-muted">{children}</span>;
+}

package/portal-template/src/components/mdx.tsx

@@ -0,0 +1,28 @@
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { PluginInstall } from './plugin-install';
+import { PluginLanguage, PluginLanguages, PluginPlatforms } from './plugin-support';
+import { SdkActions } from './sdk-actions';
+import { SdkCard, SdkCards } from './sdk-cards';
+
+type MDXComponents = Record<string, unknown>;
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    // What the generated SDK and context plugin pages are made of.
+    SdkCards,
+    SdkCard,
+    SdkActions,
+    PluginInstall,
+    PluginLanguages,
+    PluginLanguage,
+    PluginPlatforms,
+    ...components
+  };
+}
+
+export const useMDXComponents = getMDXComponents;
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}

package/portal-template/src/components/not-found.tsx

@@ -0,0 +1,11 @@
+import { baseOptions } from '@/lib/layout.shared';
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found';
+
+export function NotFound() {
+  return (
+    <HomeLayout {...baseOptions()}>
+      <DefaultNotFound />
+    </HomeLayout>
+  );
+}

package/portal-template/src/components/plugin-install.tsx

@@ -0,0 +1,22 @@
+import { useSyncExternalStore } from 'react';
+import { asMarkdown } from 'fumadocs-core/server';
+import { CommandBlock } from './command-block';
+import { installCommand } from '@/lib/install-command';
+import { portal } from '@/lib/portal';
+
+// The origin never changes while the page is open, so there is nothing to subscribe to.
+const noSubscribe = () => () => {};
+
+/** The prerender cannot know where the portal is hosted, so the browser swaps in its own origin. */
+export function PluginInstall({ path }: Readonly<{ path: string }>) {
+  // Ahead of the hook, which only React may call; either branch is taken in every render of one environment.
+  if (asMarkdown()) {
+    return <CommandBlock command={installCommand(path, portal.siteUrl)} />;
+  }
+  const origin = useSyncExternalStore(
+    noSubscribe,
+    () => window.location.origin,
+    () => portal.siteUrl
+  );
+  return <CommandBlock command={installCommand(path, origin)} />;
+}

package/portal-template/src/components/plugin-support.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+import { asMarkdown } from 'fumadocs-core/server';
+import { LanguageLogo, LogoTile, PLATFORMS } from './logos';
+
+const CARD = 'flex items-center gap-3 rounded-xl border bg-fd-card p-3 font-medium text-fd-card-foreground';
+
+// By the width the page gives the list, not the screen's, up to three to a row.
+function CardGrid({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <div className="not-prose @container my-4">
+      <ul className="grid grid-cols-1 gap-3 @md:grid-cols-2 @2xl:grid-cols-3">{children}</ul>
+    </div>
+  );
+}
+
+export function PluginLanguages({ children }: Readonly<{ children?: ReactNode }>) {
+  if (asMarkdown()) {
+    return children;
+  }
+  return <CardGrid>{children}</CardGrid>;
+}
+
+export function PluginLanguage({ language, name }: Readonly<{ language: string; name: string }>) {
+  if (asMarkdown()) {
+    return `- ${name}`;
+  }
+  return (
+    <li className={CARD}>
+      <LogoTile>
+        <LanguageLogo language={language} className="size-5" />
+      </LogoTile>
+      {name}
+    </li>
+  );
+}
+
+export function PluginPlatforms() {
+  if (asMarkdown()) {
+    return PLATFORMS.map(({ name }) => `- ${name}`).join('\n');
+  }
+  return (
+    <CardGrid>
+      {PLATFORMS.map(({ name, Logo }) => (
+        <li key={name} className={CARD}>
+          <LogoTile>
+            <Logo className="size-5" />
+          </LogoTile>
+          {name}
+        </li>
+      ))}
+    </CardGrid>
+  );
+}

package/portal-template/src/components/sdk-actions.tsx

@@ -0,0 +1,79 @@
+import type { ReactNode } from 'react';
+import { asMarkdown } from 'fumadocs-core/server';
+import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import { Code, Download, Package } from 'lucide-react';
+
+export interface SdkActionsProps {
+  download: string;
+  /** Empty when no source repository is recorded. */
+  source: string;
+  /** Empty until a release is recorded. */
+  packageUrl: string;
+  registry: string;
+}
+
+export const LINK =
+  'inline-flex items-center gap-1.5 rounded-sm text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring';
+
+export const QUIET_LINK = `${LINK} text-fd-muted-foreground hover:text-fd-foreground`;
+
+/** Download, View source and View package: each shown only when there is something behind it. */
+export function SdkActions({ download, source, packageUrl, registry }: Readonly<SdkActionsProps>) {
+  // The page's Markdown twin, which the page actions and llms-full.txt hand to an AI assistant.
+  if (asMarkdown()) {
+    const links = [
+      `[Download SDK](${download})`,
+      source ? `[View source](${source})` : null,
+      packageUrl ? `[View on ${registry}](${packageUrl})` : null
+    ];
+    return links.filter((link) => link !== null).join(' · ');
+  }
+  // With a package to install from, the download is one way in among others; without one, it is the way in.
+  const leads = packageUrl === '';
+  return (
+    <div className="not-prose flex flex-wrap items-center gap-x-5 gap-y-2">
+      <DownloadLink
+        href={download}
+        className={leads ? buttonVariants({ color: 'primary', className: 'gap-1.5' }) : QUIET_LINK}
+      >
+        <Download className="size-4" />
+        Download SDK
+      </DownloadLink>
+      {source ? (
+        <ExternalLink href={source} className={QUIET_LINK}>
+          <Code className="size-4" />
+          View source
+        </ExternalLink>
+      ) : null}
+      {packageUrl ? (
+        <ExternalLink href={packageUrl} className={QUIET_LINK}>
+          <Package className="size-4" />
+          View on {registry}
+        </ExternalLink>
+      ) : null}
+    </div>
+  );
+}
+
+interface LinkProps {
+  href: string;
+  className: string;
+  children: ReactNode;
+}
+
+/** A plain link, not a route: the zip is a file the site serves beside its pages. */
+export function DownloadLink({ href, className, children }: Readonly<LinkProps>) {
+  return (
+    <a href={href} download className={className}>
+      {children}
+    </a>
+  );
+}
+
+export function ExternalLink({ href, className, children }: Readonly<LinkProps>) {
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer" className={className}>
+      {children}
+    </a>
+  );
+}

package/portal-template/src/components/sdk-cards.tsx

@@ -0,0 +1,100 @@
+import type { ReactNode } from 'react';
+import Link from 'fumadocs-core/link';
+import { asMarkdown } from 'fumadocs-core/server';
+import { ArrowDownToLine, ArrowRight, ExternalLink as ExternalLinkIcon } from 'lucide-react';
+import { CommandBlock } from './command-block';
+import { LanguageLogo, LogoTile } from './logos';
+import { DownloadLink, ExternalLink, LINK, QUIET_LINK, SdkActions, type SdkActionsProps } from './sdk-actions';
+
+interface SdkCardProps extends SdkActionsProps {
+  language: string;
+  name: string;
+  /** The language's own page. */
+  page: string;
+  /** Empty until a release is recorded. */
+  install: string;
+}
+
+// The height and look of the compact install command, whose place it takes.
+const DOWNLOAD_SLOT =
+  'flex items-center gap-2 rounded-lg border bg-fd-secondary px-4 py-1.5 text-sm font-medium text-fd-secondary-foreground transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring';
+
+// By the width the page gives the cards, not the screen's, so each keeps room for its install command.
+export function SdkCards({ children }: Readonly<{ children?: ReactNode }>) {
+  if (asMarkdown()) {
+    return children;
+  }
+  return (
+    <div className="not-prose @container my-6">
+      <div className="grid grid-cols-1 gap-4 @2xl:grid-cols-2 @4xl:grid-cols-3">{children}</div>
+    </div>
+  );
+}
+
+/** The card's language, for a screen reader's list of links, where every card's would otherwise read the same. */
+function LinkContext({ name }: Readonly<{ name: string }>) {
+  return <span className="sr-only">, {name}</span>;
+}
+
+// Not a Fumadocs `Card`, which is one link as a whole: the links inside would be links in a link.
+export function SdkCard({ language, name, page, install, ...actions }: Readonly<SdkCardProps>) {
+  if (asMarkdown()) {
+    const command = install ? `\`${install}\` · ` : '';
+    return [`- [${name}](${page}): ${command}`, <SdkActions key="actions" {...actions} />];
+  }
+  const { download, source, packageUrl, registry } = actions;
+  return (
+    <article className="flex flex-col rounded-xl border bg-fd-card text-fd-card-foreground">
+      <div className="flex flex-1 flex-col gap-4 p-4">
+        <div className="flex items-center gap-3">
+          <LogoTile>
+            <LanguageLogo language={language} className="size-5" />
+          </LogoTile>
+          <h2 className="text-base font-semibold">{name}</h2>
+        </div>
+        {/* The way in: the install command once a package is published, the download until then. */}
+        {install ? (
+          <CommandBlock command={install} compact />
+        ) : (
+          <DownloadLink href={download} className={DOWNLOAD_SLOT}>
+            <ArrowDownToLine className="size-4" />
+            Download SDK
+            <LinkContext name={name} />
+          </DownloadLink>
+        )}
+        <div className="mt-auto flex flex-wrap items-center gap-x-5 gap-y-2">
+          {install ? (
+            <DownloadLink href={download} className={`${QUIET_LINK} font-medium`}>
+              Download SDK
+              <LinkContext name={name} />
+              <ArrowDownToLine className="size-4" />
+            </DownloadLink>
+          ) : null}
+          <Link href={page} className={`${LINK} font-medium hover:text-fd-primary`}>
+            Overview
+            <LinkContext name={name} />
+            <ArrowRight className="size-4" />
+          </Link>
+        </div>
+      </div>
+      {packageUrl || source ? (
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-1 border-t px-4 py-2.5">
+          {packageUrl ? (
+            <ExternalLink href={packageUrl} className={QUIET_LINK}>
+              {registry}
+              <LinkContext name={name} />
+              <ExternalLinkIcon className="size-3.5" />
+            </ExternalLink>
+          ) : null}
+          {source ? (
+            <ExternalLink href={source} className={QUIET_LINK}>
+              Source
+              <LinkContext name={name} />
+              <ExternalLinkIcon className="size-3.5" />
+            </ExternalLink>
+          ) : null}
+        </div>
+      ) : null}
+    </article>
+  );
+}

package/portal-template/src/components/search.tsx

@@ -0,0 +1,41 @@
+'use client';
+import {
+  SearchDialog,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+  type SharedProps
+} from 'fumadocs-ui/components/dialog/search';
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import { staticClient } from 'fumadocs-core/search/client/orama-static';
+import { useI18n } from 'fumadocs-ui/contexts/i18n';
+
+export default function DefaultSearchDialog(props: SharedProps) {
+  const { locale } = useI18n();
+  const { search, setSearch, query } = useDocsSearch({
+    // Served with an extension so hosts and CDNs give it a JSON content type; without one
+    // it went out as application/octet-stream, which some of them attach or refuse.
+    client: staticClient({
+      from: '/api/search.json',
+      locale
+    })
+  });
+
+  return (
+    <SearchDialog search={search} onSearchChange={setSearch} isLoading={query.isLoading} {...props}>
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
+      </SearchDialogContent>
+    </SearchDialog>
+  );
+}

package/portal-template/src/components/usage-tabs.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import { CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger } from 'fumadocs-ui/components/codeblock';
+import { useOperationContext, useRenderContext, useServerContext } from 'fumadocs-openapi/ui';
+import { pathnameFromRequest } from 'fumadocs-openapi/requests/generators';
+import { curl } from 'fumadocs-openapi/requests/generators/curl';
+import { joinURL, resolveServerUrl } from '@fumadocs/api-docs/utils/url';
+import { CodeSample } from '@/lib/code-samples';
+import { CodeBlock } from './code-block';
+import { useExampleSelection } from './example-layout';
+
+interface UsageTab {
+  id: string;
+  label: string;
+  body: ReactNode;
+}
+
+// The registry Fumadocs passes in adds the operation's `x-codeSamples`, which cannot follow the example selector.
+export function renderUsageTabs(): ReactNode {
+  return <UsageTabs />;
+}
+
+function UsageTabs() {
+  const tabs: UsageTab[] = [
+    { id: 'curl', label: curl.label ?? curl.lang, body: <CurlCode /> },
+    ...CodeSample.listIn(useExampleSelection().operation).map((sample) => ({
+      id: sample.lang,
+      label: sample.label,
+      body: <SampleCode sample={sample} />
+    }))
+  ];
+
+  return (
+    <CodeBlockTabs groupId="fumadocs_openapi_requests" defaultValue={tabs[0].id}>
+      <CodeBlockTabsList>
+        {tabs.map((tab) => (
+          <CodeBlockTabsTrigger key={tab.id} value={tab.id}>
+            {tab.label}
+          </CodeBlockTabsTrigger>
+        ))}
+      </CodeBlockTabsList>
+      {tabs.map((tab) => (
+        <CodeBlockTab key={tab.id} value={tab.id}>
+          {tab.body}
+        </CodeBlockTab>
+      ))}
+    </CodeBlockTabs>
+  );
+}
+
+function SampleCode({ sample }: Readonly<{ sample: CodeSample }>) {
+  const { examples, selected } = useExampleSelection();
+  const source = sample.sourceFor(selected.id, examples.length);
+
+  if (source === undefined) {
+    return <p className="px-4 py-3 text-sm text-fd-muted-foreground">No {sample.label} sample for this example.</p>;
+  }
+  return <CodeBlock lang={sample.lang} code={source} />;
+}
+
+function CurlCode() {
+  const { mediaAdapters } = useRenderContext();
+  const { route } = useOperationContext();
+  const request = useSelectedRequest();
+  const serverUrl = useServerUrl();
+
+  if (request === undefined) return null;
+  const url = joinURL(serverUrl, pathnameFromRequest(route, request));
+  return <CodeBlock lang={curl.lang} code={curl.generate({ ...request, url }, { mediaAdapters, custom: null })} />;
+}
+
+// Fumadocs reports the playground's edits to the selected example through its listeners.
+function useSelectedRequest() {
+  const { examples, example, addListener, removeListener } = useOperationContext();
+  const [request, setRequest] = useState(() => examples.find((item) => item.id === example)?.encoded);
+
+  useEffect(() => {
+    const listener = (_: unknown, encoded: typeof request) => setRequest(encoded);
+    addListener(listener);
+    return () => removeListener(listener);
+  }, [addListener, removeListener]);
+  return request;
+}
+
+function useServerUrl(): string {
+  const { server } = useServerContext();
+  const [origin, setOrigin] = useState<string>();
+
+  useEffect(() => setOrigin(window.location.origin), []);
+  return server && origin
+    ? new URL(resolveServerUrl(server.url, server.variables), origin).href
+    : 'https://example.com';
+}