Skip to content

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.tsx
index 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 (
<div
style={{
- 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']}>
<HStack
gap={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,
+ });
}}
/>
)}