feat(playground-ui): add CodeBlock component (mastra-ai#16202)

damien-schneider · web-flow · commit cd1788736524 · 2026-05-05T12:41:47.000+02:00
## Summary - New `CodeBlock` ds component with optional `select` or `tabs` switcher in the header, file-name caption, optional shiki syntax highlighting (via existing `highlight()` helper — no new deps), and a Notion-style copy button that hides on desktop until hover and stays visible on touch devices via `pointer-fine:` / `(hover: hover)` media queries. - Refactored the Mastra version dialog (`mastra-version-footer.tsx`) to use `CodeBlock` for the update command and replaced the full-width "Copy current versions" button with an icon-only `CopyButton` on the status row. <img width="947" height="756" alt="CleanShot 2026-05-05 at 11 52 48" src="https://github.com/user-attachments/assets/276d6fa4-1d27-4011-aba2-d9ff5c2807b3" /> ## Test plan - [ ] Open Storybook and review `Composite/CodeBlock` stories — `Default`, `WithSelect`, `WithTabs`, `TabsWithCode`, `WithFileName`, `Highlighted`, `LongCommand` - [ ] Verify select changes the displayed code and tabs variant switches between provider snippets - [ ] On desktop, copy button is hidden until hover; on touch (or mobile dev tools emulation), it stays visible - [ ] In the playground dialog, switching package manager updates the command and the icon copy button next to the status copies all installed versions  ## ELI5 - What's this PR about? Adds a reusable code display component that can show different snippets (via dropdown or tabs), highlight code, and let you quickly copy the code; the Mastra packages dialog now uses this component so the UI is simpler and consistent. --- ## Changes ### New `CodeBlock` component - Renders code with an optional variant selector (dropdown or tabs) to switch snippets (e.g., package managers or provider examples). - Optional filename caption. - Optional syntax highlighting via the existing highlight() helper (no new deps). Tokens are reset to null before each re-highlight and highlight() rejections are caught so the plain-text fallback remains visible and no unhandled promise rejections occur. - Notion-style copy button: hidden on desktop until hover and remains visible on touch devices using pointer-fine / (hover: hover) media-query behavior. - Supports configurable copy message/tooltip and controlled/uncontrolled value handling for the selector. ### Storybook - Added stories demonstrating variants and behaviors: Default, WithSelect, LongCommand, WithFileName, WithTabs, TabsWithCode, Highlighted. ### Refactor: Mastra version dialog - Replaced the dialog’s previous select + <pre> command block + copy button with the new `CodeBlock` for the update command (package-manager switching now drives CodeBlock via value/onValueChange). - Replaced the full-width “Copy current versions” control with an icon-only `CopyButton` on the status row. - Introduced PACKAGE_MANAGERS const, PackageManager union type, and isPackageManager guard for safer package-manager handling. - Consolidated UI and clipboard handling into `CodeBlock`, simplifying the footer component. ### Exports & package surface - Re-exported `CodeBlock` from packages/playground-ui/src/index.ts and added component index.ts. - New exported types: `CodeBlockSelector`, `CodeBlockOption`, `CodeBlockProps`. ### Changesets / Versioning - Minor bump for `@mastra/playground-ui` documenting the new component. - Patch update for `mastra` recording the Mastra version dialog refactor. ### Notes for reviewers - Verify select/tabs switching updates displayed code in Storybook. - Confirm copy button visibility behavior (hidden until hover on desktop; visible on touch). - In the playground dialog, confirm switching package manager updates the command and that the copy icon copies the expected text.
diff --git a/.changeset/every-buses-shave.md b/.changeset/every-buses-shave.md
@@ -0,0 +1,5 @@
+---
+'@mastra/playground-ui': minor
+---
+
+Added CodeBlock component with select/tabs switcher, optional shiki syntax highlighting, and Notion-style hover-only copy button (always visible on touch devices via media query).
diff --git a/.changeset/plenty-pens-call.md b/.changeset/plenty-pens-call.md
@@ -0,0 +1,5 @@
+---
+'mastra': patch
+---
+
+Refactored the Mastra version dialog to use the new CodeBlock component and simplified the package versions copy button to an icon-only button with tooltip.
diff --git a/packages/playground-ui/src/ds/components/CodeBlock/code-block.stories.tsx b/packages/playground-ui/src/ds/components/CodeBlock/code-block.stories.tsx
@@ -0,0 +1,143 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { TooltipProvider } from '../Tooltip';
+import { CodeBlock } from './code-block';
+
+const meta: Meta<typeof CodeBlock> = {
+  title: 'Composite/CodeBlock',
+  component: CodeBlock,
+  decorators: [
+    Story => (
+      <TooltipProvider>
+        <div className="w-full p-4">
+          <Story />
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CodeBlock>;
+
+const packageManagers = [
+  { label: 'pnpm', value: 'pnpm' },
+  { label: 'npm', value: 'npm' },
+  { label: 'yarn', value: 'yarn' },
+  { label: 'bun', value: 'bun' },
+];
+
+const commands: Record<string, string> = {
+  pnpm: 'pnpm add @mastra/core@latest @mastra/memory@latest mastra@latest',
+  npm: 'npm install @mastra/core@latest @mastra/memory@latest mastra@latest',
+  yarn: 'yarn add @mastra/core@latest @mastra/memory@latest mastra@latest',
+  bun: 'bun add @mastra/core@latest @mastra/memory@latest mastra@latest',
+};
+
+export const Default: Story = {
+  render: () => <CodeBlock code="pnpm dlx mastra@latest init" />,
+};
+
+export const WithSelect: Story = {
+  render: () => {
+    const [pm, setPm] = useState('pnpm');
+    return (
+      <CodeBlock
+        code={commands[pm]}
+        options={packageManagers}
+        value={pm}
+        onValueChange={setPm}
+        copyMessage="Copied update command!"
+      />
+    );
+  },
+};
+
+export const LongCommand: Story = {
+  render: () => {
+    const [pm, setPm] = useState('pnpm');
+    const long = `${pm} add @mastra/auth-workos@latest @mastra/client-js@latest @mastra/core@latest @mastra/duckdb@latest @mastra/editor@latest @mastra/libsql@latest @mastra/mcp@latest @mastra/memory@latest @mastra/observability@latest @mastra/slack@latest mastra@latest`;
+    return <CodeBlock code={long} options={packageManagers} value={pm} onValueChange={setPm} />;
+  },
+};
+
+export const WithFileName: Story = {
+  render: () => (
+    <CodeBlock
+      fileName="src/mastra/agents/index.ts"
+      lang="typescript"
+      code={`import { Agent } from '@mastra/core/agent';\nimport { openai } from '@ai-sdk/openai';\n\nexport const agent = new Agent({\n  name: 'assistant',\n  model: openai('gpt-4o-mini'),\n});`}
+    />
+  ),
+};
+
+export const WithTabs: Story = {
+  render: () => {
+    const [pm, setPm] = useState('pnpm');
+    return (
+      <CodeBlock
+        code={commands[pm]}
+        options={packageManagers}
+        value={pm}
+        onValueChange={setPm}
+        selector="tabs"
+        copyMessage="Copied update command!"
+      />
+    );
+  },
+};
+
+export const TabsWithCode: Story = {
+  render: () => {
+    const [provider, setProvider] = useState('anthropic');
+    const snippets: Record<string, string> = {
+      anthropic: `import { anthropic } from '@ai-sdk/anthropic';\n\nconst model = anthropic('claude-sonnet-4-5');`,
+      openai: `import { openai } from '@ai-sdk/openai';\n\nconst model = openai('gpt-4o-mini');`,
+      langchain: `import { ChatOpenAI } from '@langchain/openai';\n\nconst model = new ChatOpenAI({ model: 'gpt-4o-mini' });`,
+      mastra: `import { Agent } from '@mastra/core/agent';\n\nexport const agent = new Agent({ name: 'assistant', model });`,
+    };
+    return (
+      <CodeBlock
+        code={snippets[provider]}
+        lang="typescript"
+        selector="tabs"
+        options={[
+          { label: 'Anthropic', value: 'anthropic' },
+          { label: 'OpenAI', value: 'openai' },
+          { label: 'LangChain', value: 'langchain' },
+          { label: 'Mastra', value: 'mastra' },
+        ]}
+        value={provider}
+        onValueChange={setProvider}
+      />
+    );
+  },
+};
+
+export const Highlighted: Story = {
+  render: () => {
+    const [provider, setProvider] = useState('openai');
+    const snippets: Record<string, string> = {
+      openai: `import { openai } from '@ai-sdk/openai';\n\nconst model = openai('gpt-4o-mini');`,
+      anthropic: `import { anthropic } from '@ai-sdk/anthropic';\n\nconst model = anthropic('claude-sonnet-4-5');`,
+      mastra: `import { Agent } from '@mastra/core/agent';\n\nexport const agent = new Agent({ name: 'assistant', model });`,
+    };
+    return (
+      <CodeBlock
+        code={snippets[provider]}
+        lang="typescript"
+        options={[
+          { label: 'OpenAI', value: 'openai' },
+          { label: 'Anthropic', value: 'anthropic' },
+          { label: 'Mastra', value: 'mastra' },
+        ]}
+        value={provider}
+        onValueChange={setProvider}
+      />
+    );
+  },
+};
diff --git a/packages/playground-ui/src/ds/components/CodeBlock/code-block.tsx b/packages/playground-ui/src/ds/components/CodeBlock/code-block.tsx
@@ -0,0 +1,161 @@
+import * as React from 'react';
+import type { ThemedToken } from 'shiki';
+
+import { highlight } from '../CodeEditor';
+import { CopyButton } from '../CopyButton';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../Select';
+import { Tab, TabList, Tabs } from '../Tabs';
+import { transitions } from '@/ds/primitives/transitions';
+import { cn } from '@/lib/utils';
+
+export type CodeBlockSelector = 'select' | 'tabs';
+
+export interface CodeBlockOption {
+  label: string;
+  value: string;
+}
+
+export interface CodeBlockProps {
+  code: string;
+  options?: CodeBlockOption[];
+  value?: string;
+  onValueChange?: (value: string) => void;
+  selector?: CodeBlockSelector;
+  fileName?: string;
+  lang?: string;
+  copyMessage?: string;
+  copyTooltip?: string;
+  className?: string;
+}
+
+export function CodeBlock({
+  code,
+  options,
+  value,
+  onValueChange,
+  selector = 'select',
+  fileName,
+  lang,
+  copyMessage,
+  copyTooltip,
+  className,
+}: CodeBlockProps) {
+  const hasOptions = options && options.length > 0;
+  const useTabs = hasOptions && selector === 'tabs';
+  const useSelect = hasOptions && selector === 'select';
+  const activeValue = value ?? options?.[0]?.value;
+
+  return (
+    <figure
+      className={cn(
+        'group relative flex w-full flex-col overflow-hidden rounded-2xl border border-border2/40 bg-surface2',
+        className,
+      )}
+    >
+      {useTabs && options && (
+        <Tabs defaultTab={options[0].value} value={activeValue} onValueChange={onValueChange ?? (() => {})}>
+          <TabList>
+            {options.map(opt => (
+              <Tab key={opt.value} value={opt.value}>
+                {opt.label}
+              </Tab>
+            ))}
+          </TabList>
+        </Tabs>
+      )}
+
+      {useSelect && options && (
+        <div className="flex items-center border-b border-border2/40 px-2 py-1.5">
+          <Select value={activeValue} onValueChange={onValueChange}>
+            <SelectTrigger size="sm" variant="ghost">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {options.map(opt => (
+                <SelectItem key={opt.value} value={opt.value}>
+                  {opt.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+      )}
+
+      {!hasOptions && fileName && (
+        <div className="flex items-center border-b border-border2/40 px-4 py-2">
+          <figcaption className="font-mono text-ui-sm text-neutral4">{fileName}</figcaption>
+        </div>
+      )}
+
+      <div className="relative">
+        <HighlightedCode code={code} lang={lang} />
+        <CopyButton
+          content={code}
+          copyMessage={copyMessage}
+          tooltip={copyTooltip}
+          size="sm"
+          className={cn(
+            'absolute top-2 right-2 opacity-100 pointer-fine:opacity-0 group-hover:opacity-100 group-focus-within:opacity-100',
+            transitions.opacity,
+          )}
+        />
+      </div>
+    </figure>
+  );
+}
+
+interface HighlightedCodeProps {
+  code: string;
+  lang?: string;
+}
+
+function HighlightedCode({ code, lang }: HighlightedCodeProps) {
+  const [tokens, setTokens] = React.useState<ThemedToken[][] | null>(null);
+
+  React.useEffect(() => {
+    if (!lang) {
+      setTokens(null);
+      return;
+    }
+    setTokens(null);
+    let cancelled = false;
+    void highlight(code, lang)
+      .then(result => {
+        if (!cancelled && result) setTokens(result);
+      })
+      .catch(() => {
+        // Highlighting failed — plain-text fallback remains visible.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [code, lang]);
+
+  const preClass = 'px-4 py-3 font-mono text-ui-sm text-neutral5 whitespace-pre-wrap break-all';
+
+  if (!lang || !tokens) {
+    return <pre className={preClass}>{code}</pre>;
+  }
+
+  return (
+    <pre className={preClass}>
+      <code>
+        {tokens.map((line, lineIndex) => (
+          <React.Fragment key={lineIndex}>
+            <span>
+              {line.map((token, tokenIndex) => (
+                <span
+                  key={tokenIndex}
+                  className="text-shiki-light bg-shiki-light-bg dark:text-shiki-dark dark:bg-shiki-dark-bg"
+                >
+                  {token.content}
+                </span>
+              ))}
+            </span>
+            {lineIndex !== tokens.length - 1 && '\n'}
+          </React.Fragment>
+        ))}
+      </code>
+    </pre>
+  );
+}
diff --git a/packages/playground-ui/src/ds/components/CodeBlock/index.ts b/packages/playground-ui/src/ds/components/CodeBlock/index.ts
@@ -0,0 +1 @@
+export * from './code-block';
diff --git a/packages/playground-ui/src/index.ts b/packages/playground-ui/src/index.ts
@@ -25,6 +25,7 @@ export * from './ds/components/Checkbox';
 export * from './ds/components/Collapsible';
 export * from './ds/components/Combobox';
 export * from './ds/components/Command';
+export * from './ds/components/CodeBlock';
 export * from './ds/components/CopyButton';
 export * from './ds/components/DashboardCard';
 export * from './ds/components/Dialog';
diff --git a/packages/playground/src/domains/configuration/components/mastra-version-footer.tsx b/packages/playground/src/domains/configuration/components/mastra-version-footer.tsx

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@mastra/playground-ui': minor
 +---
++
 +Added CodeBlock component with select/tabs switcher, optional shiki syntax highlighting, and Notion-style hover-only copy button (always visible on touch devices via media query).