An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): examples are framed once by their card and render inside a clean layout boundary (#9411)
Cindy Zhangd93eda1b472c
diff --git a/apps/docsite/src/components/component-detail/ExampleBlock.tsx b/apps/docsite/src/components/component-detail/ExampleBlock.tsxindex 4ec7d7cb98..23414ce48d 100644--- a/apps/docsite/src/components/component-detail/ExampleBlock.tsx+++ b/apps/docsite/src/components/component-detail/ExampleBlock.tsx@@ -9,7 +9,8 @@* @position Used by ComponentDetailClient's Examples section.*/-import {useEffect, useState, type ComponentType} from 'react';+import {useEffect, useState, type ComponentType, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';import {Card} from '@astryxdesign/core/Card';import {Section} from '@astryxdesign/core/Section';import {Center} from '@astryxdesign/core/Center';@@ -18,7 +19,13 @@ import {CodeExampleBlock} from '../CodeExampleBlock';import {TabList, Tab} from '@astryxdesign/core/TabList';import {Spinner} from '@astryxdesign/core/Spinner';import {Button} from '@astryxdesign/core/Button';-import {HStack, VStack} from '@astryxdesign/core/Layout';+import {+ HStack,+ LayoutAreaContext,+ LayoutDividerContext,+ overlayPaddingReset,+ VStack,+} from '@astryxdesign/core/Layout';import type {ExampleEntry} from '../../generated/exampleRegistry';import {ComponentPreviewTheme} from './ComponentPreviewTheme';import {ExampleAnchor} from './ExampleAnchor';@@ -32,6 +39,45 @@ import {} from '../../generated/shadcnRegistry';import {shadcnInstallCommand} from '../../lib/shadcnRegistry.mjs';+const styles = stylex.create({+ // With Core's `overlayPaddingReset` (container padding, Layout insets,+ // Section padding propagation), the layout values the docs card publishes+ // stop at the example, so it renders as it does at a page root: no Layout in+ // the example escapes the card's padding, or takes its insets, widths or+ // height cap. These are the values that reset leaves out. AppShell's own+ // layout-root reset (component:AppShell FR18) is not built yet; until it is,+ // this boundary is what keeps the AppShell examples whole.+ exampleRoot: {+ minWidth: 'fit-content',+ '--layout-content-width': 'initial',+ '--layout-alignment-width': 'initial',+ '--_layout-flush-block-start': 'initial',+ '--_layout-flush-block-end': 'initial',+ '--container-max-height': 'initial',+ },+});++/** Room for a focus ring inside the preview's scroll box, in px. */+const FOCUS_RING_ROOM = 5;++/**+ * The example's root: a clean layout boundary, with no padding of its own+ * (the Card's padding is the example's only frame). Nothing the docs page or+ * card passes down (container padding, Layout insets and widths, the Layout+ * area and divider defaults) reaches the example.+ */+function ExampleLayoutRoot({children}: {children: ReactNode}) {+ return (+ <LayoutAreaContext value={null}>+ <LayoutDividerContext value={null}>+ <div {...stylex.props(overlayPaddingReset.reset, styles.exampleRoot)}>+ {children}+ </div>+ </LayoutDividerContext>+ </LayoutAreaContext>+ );+}+function LivePreview({entry,componentName,@@ -75,7 +121,17 @@ function LivePreview({return (<divstyle={{- width: '100%',+ // A focus ring (2px at a 3px offset) on a control at the preview's+ // edge needs room inside this scroll box, or it loses that side. The+ // room comes out of the card's padding through an equal negative+ // margin, so the example still lines up with the title and no inset+ // is added around it. At the block end it stays inside, above the+ // tabs' divider.+ boxSizing: 'border-box',+ width: `calc(100% + ${2 * FOCUS_RING_ROOM}px)`,+ marginInline: -FOCUS_RING_ROOM,+ marginBlockStart: -FOCUS_RING_ROOM,+ padding: FOCUS_RING_ROOM,overflow: 'auto',minHeight: 200,display: 'flex',@@ -83,9 +139,9 @@ function LivePreview({justifyContent: 'center',}}{...previewNavigationProps}>- <div style={{minWidth: 'fit-content', padding: 'var(--spacing-4)'}}>+ <ExampleLayoutRoot><Component />- </div>+ </ExampleLayoutRoot></div>);}@@ -102,16 +158,22 @@ export function ExampleBlock({entry, componentName}: ExampleBlockProps) {<ExampleAnchor id={entry.anchorId}><ComponentPreviewTheme><Card padding={3}>- <Text type="body" weight="medium">- {entry.name}- </Text>-- <LivePreview entry={entry} componentName={componentName} />-+ {/* This stack's gap separates the title from the example, and the+ tabs' divider separates the example from the tabs; nothing pads+ the example itself. */}+ <VStack gap={3}>+ <Text type="body" weight="medium">+ {entry.name}+ </Text>+ <LivePreview entry={entry} componentName={componentName} />+ </VStack><Section variant="muted" padding={1} dividers={['top']}><HStackgap={1}- style={{justifyContent: 'space-between', alignItems: 'center'}}>+ style={{+ justifyContent: 'space-between',+ alignItems: 'center',+ }}><TabList value={tab} onChange={setTab} size="sm"><Tab value="description" label="Description" /><Tab value="code" label="Code" />@@ -129,7 +191,10 @@ export function ExampleBlock({entry, componentName}: ExampleBlockProps) {// for analytics; the href handles navigation natively.href={buildPlaygroundHref(entry.source)}onClick={() => {- trackOpenPlayground({page: 'components', item: entry.name});+ trackOpenPlayground({+ page: 'components',+ item: entry.name,+ });}}/>)}