An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): give provider/utility pages a static props table, not a playground (#2733) (#3878)
Jiun Shin1887ee2ed02e
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.tsindex 0ca7c5be9a..12ee0cb900 100644--- a/apps/docsite/src/__tests__/component-preview-state.test.ts+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts@@ -5,6 +5,7 @@ import {buildInitialState,buildRuntimePreviewState,getMissingRequiredProps,+ hasInteractivePlayground,isOverlayPreviewClosed,pickPrimaryProps,} from '../components/component-detail/interactiveState';@@ -491,3 +492,60 @@ describe('component detail preview state', () => {expect(isOverlayPreviewClosed(undefined, {})).toBe(false);});});++// ── Simplified layout for provider/utility pages (#2733) ───────────────────+// Utility entries like LinkProvider are non-visual providers: auto-generated+// playground knobs render an empty stage with an unsatisfiable required+// `component` prop. They must get the hook-style static layout instead,+// while Utility docs that curate a playground (Theme) keep the interactive+// Properties tab.+describe('hasInteractivePlayground', () => {+ it('gives regular components an interactive playground', () => {+ expect(+ hasInteractivePlayground({+ category: 'Action',+ params: null,+ playground: null,+ }),+ ).toBe(true);+ expect(+ hasInteractivePlayground({+ category: null,+ params: null,+ playground: null,+ }),+ ).toBe(true);+ });++ it('never gives hooks a playground', () => {+ expect(+ hasInteractivePlayground({+ category: 'Utility',+ params: [{name: 'query', type: 'string', description: ''}],+ playground: null,+ }),+ ).toBe(false);+ });++ it('gives playground-less Utility entries the static layout', () => {+ // LinkProvider, LayerProvider, VisuallyHidden shape+ expect(+ hasInteractivePlayground({+ category: 'Utility',+ params: null,+ playground: null,+ }),+ ).toBe(false);+ });++ it('keeps the playground for Utility docs that curate one', () => {+ // Theme, MediaTheme, SyntaxTheme shape+ expect(+ hasInteractivePlayground({+ category: 'Utility',+ params: null,+ playground: {defaults: {mode: 'light'}},+ }),+ ).toBe(true);+ });+});diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 7246b5b825..47cb3afb26 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -980,3 +980,33 @@ describe('ToggleButtonGroup vertical example', () => {expect(vertical!.source).toContain('type="multiple"');});});++// ── LinkProvider utility page (#2733) ──────────────────────────────────────+// LinkProvider is a non-visual provider: its page renders the hook-style+// static layout (props table on the main page, no interactive playground).+// That layout keys off `category: 'Utility'` with no curated playground, and+// still needs props and an example block to have content to show.+describe('LinkProvider utility page', () => {+ const linkProvider = components['@astryxdesign/core'].find(+ c => c.name === 'LinkProvider',+ );++ it('is a Utility entry without a curated playground', () => {+ expect(linkProvider).toBeDefined();+ expect(linkProvider!.category).toBe('Utility');+ expect(linkProvider!.params).toBeNull();+ expect(linkProvider!.playground).toBeNull();+ });++ it('documents props for the static props table', () => {+ const propNames = linkProvider!.props.map(p => p.name);+ expect(propNames).toContain('component');+ expect(propNames).toContain('children');+ });++ it('registers an example block demonstrating a custom link component', () => {+ const examples = exampleRegistry['LinkProvider'] ?? [];+ expect(examples.length).toBeGreaterThanOrEqual(1);+ expect(examples[0].source).toContain('<LinkProvider component=');+ });+});diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsxindex e25ab6a23d..b7f6bc15f5 100644--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx@@ -23,7 +23,9 @@ import {InteractivePreviewStage,useInteractiveState,} from './InteractivePreview';+import {hasInteractivePlayground} from './interactiveState';import {PlaygroundPropsTable} from './PlaygroundPropsTable';+import {PropsTable} from './PropsTable';import type {ComponentEntry} from '../../generated/componentRegistry';import type {BlockEntry} from '../../generated/blockRegistry';import {showcaseRegistry} from '../../generated/showcaseRegistry';@@ -112,6 +114,10 @@ function OverviewContent({<HookSignature params={comp.params} returns={comp.returns} />)}+ {!isHook && !hasInteractivePlayground(comp) && comp.props.length > 0 && (+ <PropsTable props={comp.props} heading="Props" />+ )}+{(exampleRegistry[comp.name] || []).length > 0 && (<><VStack gap={4}>@@ -143,9 +149,8 @@ function ComponentDetailInner({const router = useRouter();const pathname = usePathname();- const isHook = comp.params != null;const hasShowcase = comp.name in showcaseRegistry;- const hasPlayground = !isHook;+ const hasPlayground = hasInteractivePlayground(comp);const tab = searchParams.get('tab') ?? 'overview';const setTab = (value: string) => {diff --git a/apps/docsite/src/components/component-detail/PropsTable.tsx b/apps/docsite/src/components/component-detail/PropsTable.tsxnew file mode 100644index 0000000000..cd13b5a3e5--- /dev/null+++ b/apps/docsite/src/components/component-detail/PropsTable.tsx@@ -0,0 +1,89 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Heading, Text} from '@astryxdesign/core/Text';+import {VStack, HStack} from '@astryxdesign/core/Layout';+import {Section} from '@astryxdesign/core/Section';+import {Table, pixel} from '@astryxdesign/core/Table';+import {Badge} from '@astryxdesign/core/Badge';+import type {PropDoc} from '../../generated/componentRegistry';+import {MarkdownText} from '../MarkdownText';++function formatType(type: string, defaultValue?: string): string {+ if (defaultValue != null) {+ return `${type} (default: ${defaultValue})`;+ }+ return type;+}++interface PropsTableProps {+ props: PropDoc[];+ heading?: string;+}++export function PropsTable({props, heading}: PropsTableProps) {+ if (props.length === 0) {+ return null;+ }++ const required = props.filter(p => p.required);+ const optional = props.filter(p => !p.required);+ const sorted = [...required, ...optional];++ const data = sorted.map(prop => ({+ name: prop.name as unknown,+ required: prop.required as unknown,+ type: formatType(prop.type, prop.default) as unknown,+ description: (prop.description ?? '') as unknown,+ })) as Record<string, unknown>[];++ return (+ <Section>+ <VStack gap={2}>+ {heading && <Heading level={3}>{heading}</Heading>}+ <Table+ data={data}+ columns={[+ {+ key: 'name',+ header: 'Prop',+ width: pixel(180),+ renderCell: (item: Record<string, unknown>) => (+ <HStack gap={1} vAlign="center">+ <Text type="code" weight="bold">+ {item.name as string}+ </Text>+ {item.required === true && (+ <Badge label="required" variant="info" />+ )}+ </HStack>+ ),+ },+ {+ key: 'type',+ header: 'Type',+ width: pixel(240),+ renderCell: (item: Record<string, unknown>) => (+ <Text type="code" color="secondary">+ {item.type as string}+ </Text>+ ),+ },+ {+ key: 'description',+ header: 'Description',+ renderCell: (item: Record<string, unknown>) => (+ <MarkdownText type="body">+ {item.description as string}+ </MarkdownText>+ ),+ },+ ]}+ density="spacious"+ dividers="rows"+ />+ </VStack>+ </Section>+ );+}diff --git a/apps/docsite/src/components/component-detail/interactiveState.ts b/apps/docsite/src/components/component-detail/interactiveState.tsindex 0053bcf585..28edcea501 100644--- a/apps/docsite/src/components/component-detail/interactiveState.ts+++ b/apps/docsite/src/components/component-detail/interactiveState.ts@@ -17,6 +17,7 @@ import {} from './parsePropType';import {resolveValue} from './resolveElements';import type {+ ComponentEntry,PropDoc,PlaygroundConfig,} from '../../generated/componentRegistry';@@ -198,6 +199,24 @@ export function buildInitialState(return state;}+/**+ * Whether a component detail page renders the interactive Properties+ * playground. Hooks document params/returns through HookSignature instead.+ * Utility entries (providers and context, e.g. LinkProvider, LayerProvider,+ * VisuallyHidden) are non-visual, so auto-generated knobs render an empty or+ * meaningless stage; they get the hook-style static layout with a plain props+ * table unless their doc curates a playground (e.g. Theme, which previews+ * themed content). See #2733.+ */+export function hasInteractivePlayground(+ comp: Pick<ComponentEntry, 'category' | 'params' | 'playground'>,+): boolean {+ if (comp.params != null) {+ return false;+ }+ return comp.category !== 'Utility' || comp.playground != null;+}+/*** True when an overlay-mode component (`playground.overlay`) is closed in the* current preview state. The component renders nothing inline while closed