Skip to content

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.ts
index 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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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.ts
index 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