From e6bd407e8801cb37b34ab6cc11feb23f88959366 Mon Sep 17 00:00:00 2001
From: Anthony Lio <lionnet.ant@gmail.com>
Date: Thu, 10 Sep 2026 10:54:21 +0300
Subject: [PATCH] fix(docs): collapsible details component (#50065)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## What kind of change does this PR introduce?

nitpick ui bug fix in docs of the collapsible details component +
commentary

## What is the current behavior?

1. data / response / notes collapsibles on reference pages grow taller
when you expand them + also get double padding: the panel pads the
content, and the code block pads itself again inside it

2. commentary that follows a snippet in the example column renders
unstyled, since that column has no prose context. it comes out larger
than the description column and inline code stays as plain text

## What is the new behavior?

├ adds `CodeBlock` a `compact` variant that get appropriate styling when
used within collapsible

| state | preview |
| -------|------|
| before | <video
src="https://github.com/user-attachments/assets/8b70e1c6-9e0e-4371-a2b2-eb4a3d580247"
/> |
| after | <video
src="https://github.com/user-attachments/assets/1e5cdd46-ce7d-4d2d-ac6a-6da680df37e5"
/> |

├ wraps example column in prose so trailing commentary matches the
description font size + inline code styling

| state | preview |
| -------|------|
| before | <img width="1142" height="404" alt="image"
src="https://github.com/user-attachments/assets/8d0f1ac0-087d-47f7-b35d-b8798d589fdb"
/> |
| after | <img width="1142" height="404" alt="image"
src="https://github.com/user-attachments/assets/b9ba4202-a8dd-407d-b535-f34d83f5b24b"
/> |

## Test
- visits `/docs/reference/javascript/using-filters-gt`
- visits `/docs/reference/server/middleware-withsupabaseadminclient`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Documentation code blocks can now be displayed in a compact format
without borders or extra spacing.
- Reference documentation supports customizing code block presentation.
- **Style**
- Improved formatting for example content, including prose wrapping,
spacing, and code block margins.
- Refined collapsible documentation sections with clearer spacing, hover
and focus states, and open/close animations.
- Code-only collapsible content now uses a more compact layout, while
text content receives consistent typography and padding.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/features/docs/Reference.mdx.tsx     |  7 ++-
 .../docs/features/docs/Reference.sections.tsx | 10 +++-
 apps/docs/features/docs/Reference.ui.tsx      | 54 ++++++++++++++-----
 apps/docs/features/ui/CodeBlock/CodeBlock.tsx |  9 ++--
 4 files changed, 60 insertions(+), 20 deletions(-)

diff --git a/apps/docs/features/docs/Reference.mdx.tsx b/apps/docs/features/docs/Reference.mdx.tsx
index 1e63f8adb3d..2f3f846c9f9 100644
--- a/apps/docs/features/docs/Reference.mdx.tsx
+++ b/apps/docs/features/docs/Reference.mdx.tsx
@@ -41,14 +41,17 @@ const getRefMarkdown = cache_fullProcess_withDevCacheBust(
 
 interface MDXRemoteRefsProps {
   source: string
+  codeBlockProps?: Partial<ComponentProps<typeof CodeBlock>>
 }
 
-function MDXRemoteRefs({ source }: MDXRemoteRefsProps) {
+function MDXRemoteRefs({ source, codeBlockProps }: MDXRemoteRefsProps) {
   const refComponents = {
     ...components,
     // Override the CodeBlock used for normal guides to skip type generation
     // because it is too resource-intensive
-    pre: (props: ComponentProps<typeof CodeBlock>) => <CodeBlock {...props} skipTypeGeneration />,
+    pre: (props: ComponentProps<typeof CodeBlock>) => (
+      <CodeBlock {...props} {...codeBlockProps} skipTypeGeneration />
+    ),
     RefSubLayout,
     CliGlobalFlagsHandler,
   }
diff --git a/apps/docs/features/docs/Reference.sections.tsx b/apps/docs/features/docs/Reference.sections.tsx
index cbced0f844c..a95baa199b0 100644
--- a/apps/docs/features/docs/Reference.sections.tsx
+++ b/apps/docs/features/docs/Reference.sections.tsx
@@ -548,7 +548,15 @@ async function FunctionSection({
               </TabsList>
               {examples.map((example) => (
                 <TabsContent key={example.id} value={example.id}>
-                  <MDXRemoteRefs source={example.code} />
+                  <div
+                    className={cn(
+                      'prose wrap-break-word max-w-none',
+                      '[&_.shiki]:!my-0 [&_.shiki:not(:last-child)]:!mb-4',
+                      '[&_p]:!whitespace-normal'
+                    )}
+                  >
+                    <MDXRemoteRefs source={example.code} />
+                  </div>
                   <div className="flex flex-col gap-2 mt-2">
                     {'data' in example && !!example.data?.sql && (
                       <CollapsibleDetails title="Data source" content={example.data.sql} />
diff --git a/apps/docs/features/docs/Reference.ui.tsx b/apps/docs/features/docs/Reference.ui.tsx
index 42c984a41e6..441976c8d35 100644
--- a/apps/docs/features/docs/Reference.ui.tsx
+++ b/apps/docs/features/docs/Reference.ui.tsx
@@ -12,6 +12,7 @@ import { ReferenceSectionWrapper } from '~/features/docs/Reference.ui.client'
 import { normalizeMarkdown } from '~/features/docs/Reference.utils'
 import { isEqual } from 'lodash-es'
 import { ChevronRight, XCircle } from 'lucide-react'
+import { fromMarkdown } from 'mdast-util-from-markdown'
 import type { HTMLAttributes, PropsWithChildren } from 'react'
 import ReactMarkdown from 'react-markdown'
 import { Badge, cn, Collapsible, CollapsibleContent, CollapsibleTrigger } from 'ui'
@@ -115,32 +116,57 @@ export function StickyHeader({ title, monoFont = false, className }: StickyHeade
 }
 
 export function CollapsibleDetails({ title, content }: { title: string; content: string }) {
+  const blocks = fromMarkdown(content).children
+  const isCodeOnly = blocks.length === 1 && blocks[0].type === 'code'
+
   return (
-    <Collapsible>
+    <Collapsible
+      className={cn(
+        'overflow-hidden',
+        'border border-default rounded-lg bg-surface-100',
+        'has-[:focus-visible]:outline-solid has-[:focus-visible]:outline-2',
+        'has-[:focus-visible]:outline-offset-[-2px] has-[:focus-visible]:outline-[var(--ring)]'
+      )}
+    >
       <CollapsibleTrigger
         className={cn(
-          'group',
-          'w-full h-8',
-          'border bg-surface-100 rounded-sm',
-          'px-5',
-          'flex items-center gap-3',
+          'group/trigger',
+          'w-full min-h-8',
+          'px-2 py-1.5',
+          'flex items-center gap-2',
           'text-xs text-foreground-light',
-          'data-open:bg-surface-200',
-          'data-open:rounded-b-none data-open:border-b-0',
-          'transition motion-reduce:duration-1 ease-out'
+          'cursor-pointer hover:bg-surface-200 hover:text-foreground',
+          'focus-visible:outline-none',
+          'transition-[background-color,color] duration-150 ease-out'
         )}
       >
-        <ChevronRight size={12} className="group-data-open:rotate-90 transition-transform" />
         {title}
+        <ChevronRight
+          size={12}
+          strokeWidth={2}
+          aria-hidden
+          className="ms-auto shrink-0 text-foreground-muted group-data-open/trigger:rotate-90 transition-transform duration-200 ease-out motion-reduce:transition-none"
+        />
       </CollapsibleTrigger>
       <CollapsibleContent
         className={cn(
-          'border border-default bg-surface-100 rounded-b',
-          'px-5 py-2',
-          'prose max-w-none text-sm'
+          'overflow-hidden',
+          'data-open:animate-collapsible-down data-closed:animate-collapsible-up',
+          'motion-reduce:animate-none'
         )}
       >
-        <MDXRemoteRefs source={content} />
+        <div
+          className={cn(
+            'border-t border-default',
+            'prose max-w-none text-sm',
+            !isCodeOnly && 'px-4 py-3 [&_:where(p,li)]:text-sm [&_:where(p,li)]:leading-6'
+          )}
+        >
+          <MDXRemoteRefs
+            source={content}
+            codeBlockProps={isCodeOnly ? { compact: true } : undefined}
+          />
+        </div>
       </CollapsibleContent>
     </Collapsible>
   )
diff --git a/apps/docs/features/ui/CodeBlock/CodeBlock.tsx b/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
index 4ecafb77f33..1d1c4d3268d 100644
--- a/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
+++ b/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
@@ -27,6 +27,7 @@ export async function CodeBlock({
   children,
   skipTypeGeneration,
   hideControls = false,
+  compact = false,
 }: PropsWithChildren<{
   className?: string
   lang?: string
@@ -34,6 +35,7 @@ export async function CodeBlock({
   contents?: string
   skipTypeGeneration?: boolean
   hideControls?: boolean
+  compact?: boolean
 }>) {
   let code = (contents || extractCode(children)).trim()
   const lang = tryToBundledLanguage(langSetting || '') || extractLang(children)
@@ -63,8 +65,8 @@ export async function CodeBlock({
         'relative',
         'not-prose',
         'w-full',
-        'border border-default rounded-lg',
-        'bg-200 shadow-codeblock',
+        compact ? 'border-0 my-0!' : 'border border-default rounded-lg shadow-codeblock',
+        'bg-200',
         'text-sm',
         className
       )}
@@ -72,7 +74,8 @@ export async function CodeBlock({
       <div
         className={cn(
           'code-scroll',
-          'w-full overflow-x-auto overscroll-x-none rounded-lg',
+          'w-full overflow-x-auto overscroll-x-none',
+          !compact && 'rounded-lg',
           'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring'
         )}
         role="group"