Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): seed Grid/Stack family Properties previews with playground defaults (#5912)

Ojas Mutrejaa13883d2e645
diff --git a/.changeset/grid-stack-properties-preview.md b/.changeset/grid-stack-properties-preview.md
new file mode 100644
index 0000000000..9adad8a4b7
--- /dev/null
+++ b/.changeset/grid-stack-properties-preview.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Grid, Stack, HStack, VStack, GridSpan, and StackItem: seed example content via playground defaults (and, for the two sub-components, a real parent wrapper) so the docsite properties-tab preview renders a working component instead of an empty stage. (#5892, #5893, #5894, #5898, #5899, #5900)
+
+@HelloOjasMutreja
diff --git a/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts b/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
index 920b200f92..fa3d5ea748 100644
--- a/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
+++ b/apps/docsite/src/__tests__/component-detail-resolve-elements.test.ts
@@ -2,10 +2,16 @@
import {isValidElement, type ReactElement} from 'react';
import {describe, expect, it, vi} from 'vitest';
-import {resolveValue} from '../components/component-detail/resolveElements';
+import {
+ getComponent,
+ resolveValue,
+} from '../components/component-detail/resolveElements';
vi.mock('@astryxdesign/core', () => ({
Badge: () => null,
+ Card: () => null,
+ Grid: () => null,
+ HStack: () => null,
Icon: () => null,
SideNavItem: () => null,
Text: () => null,
@@ -58,4 +64,16 @@ describe('component detail element resolution', () => {
expect(isValidElement(resolved.status.message)).toBe(true);
expect(resolved.status.message.props.children).toBe('Bad date');
});
+
+ it.each([
+ ['GridSpan', 'Grid', {columns: 3, gap: 2}],
+ ['StackItem', 'HStack', {gap: 2, width: 300}],
+ ])(
+ "resolves %s's playground.wrapper (%s) to a real component and its props (#5893, #5899)",
+ (_subComponent, wrapperName, wrapperProps) => {
+ const WrapperComponent = getComponent(wrapperName);
+ expect(WrapperComponent).not.toBeNull();
+ expect(resolveValue(wrapperProps)).toEqual(wrapperProps);
+ },
+ );
});
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
index 16f397a718..a9222f2ab7 100644
--- a/apps/docsite/src/__tests__/component-preview-state.test.ts
+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts
@@ -165,6 +165,61 @@ describe('component detail preview state', () => {
expect(getMissingRequiredProps(knobs, state)).toEqual([]);
});
+ it('seeds Grid children from playground defaults so the preview is not empty (#5892)', () => {
+ const knobs = pickPrimaryProps('Grid', [
+ prop({name: 'columns', type: 'number | {minWidth: number}'}),
+ prop({name: 'gap', type: '0 | 0.5 | 1 | 1.5 | 2'}),
+ prop({name: 'children', type: 'ReactNode'}),
+ ]);
+
+ const state = buildInitialState(knobs, {
+ defaults: {
+ columns: 3,
+ gap: 2,
+ children: [
+ {__element: 'Card', props: {padding: 4}, children: 'Item 1'},
+ {__element: 'Card', props: {padding: 4}, children: 'Item 2'},
+ {__element: 'Card', props: {padding: 4}, children: 'Item 3'},
+ ],
+ },
+ });
+
+ expect(state.columns).toBe(3);
+ expect(Array.isArray(state.children)).toBe(true);
+ expect((state.children as unknown[]).length).toBe(3);
+ expect(getMissingRequiredProps(knobs, state)).toEqual([]);
+ });
+
+ it.each([
+ ['Stack', {direction: 'horizontal'}],
+ ['HStack', {}],
+ ['VStack', {}],
+ ])(
+ 'seeds %s children from playground defaults so the preview is not empty (#5894, #5898, #5900)',
+ (name, extraDefaults) => {
+ const knobs = pickPrimaryProps(name, [
+ prop({name: 'gap', type: '0 | 0.5 | 1 | 1.5 | 2'}),
+ prop({name: 'children', type: 'ReactNode'}),
+ ]);
+
+ const state = buildInitialState(knobs, {
+ defaults: {
+ gap: 2,
+ ...extraDefaults,
+ children: [
+ {__element: 'Card', props: {padding: 3}, children: 'Item 1'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 2'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 3'},
+ ],
+ },
+ });
+
+ expect(Array.isArray(state.children)).toBe(true);
+ expect((state.children as unknown[]).length).toBe(3);
+ expect(getMissingRequiredProps(knobs, state)).toEqual([]);
+ },
+ );
+
it("satisfies Icon's required, non-generatable icon prop via playground defaults", () => {
const knobs = pickPrimaryProps('Icon', [
prop({
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 76482505fa..e680719c89 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -323,6 +323,62 @@ describe('componentRegistry', () => {
});
});
+ it('Grid declares playground children so the preview is not empty (#5892)', () => {
+ const core = components['@astryxdesign/core'];
+ const grid = core.find(c => c.name === 'Grid');
+ expect(grid).toBeDefined();
+ expect(grid!.playground?.defaults).toMatchObject({
+ columns: 3,
+ gap: 2,
+ children: expect.arrayContaining([
+ expect.objectContaining({__element: 'Card'}),
+ ]),
+ });
+ });
+
+ it('GridSpan declares a playground wrapper for realistic preview geometry (#5893)', () => {
+ const core = components['@astryxdesign/core'];
+ const gridSpan = core.find(c => c.name === 'GridSpan');
+ expect(gridSpan).toBeDefined();
+ expect(gridSpan!.playground?.wrapper).toMatchObject({
+ component: 'Grid',
+ props: {columns: 3, gap: 2},
+ });
+ expect(gridSpan!.playground?.defaults).toMatchObject({
+ columns: 2,
+ children: expect.any(String),
+ });
+ });
+
+ it.each(['Stack', 'HStack', 'VStack'])(
+ '%s declares playground children so the preview is not empty (#5894, #5898, #5900)',
+ name => {
+ const core = components['@astryxdesign/core'];
+ const entry = core.find(c => c.name === name);
+ expect(entry).toBeDefined();
+ expect(entry!.playground?.defaults).toMatchObject({
+ gap: 2,
+ children: expect.arrayContaining([
+ expect.objectContaining({__element: 'Card'}),
+ ]),
+ });
+ },
+ );
+
+ it('StackItem declares a playground wrapper for realistic preview geometry (#5899)', () => {
+ const core = components['@astryxdesign/core'];
+ const stackItem = core.find(c => c.name === 'StackItem');
+ expect(stackItem).toBeDefined();
+ expect(stackItem!.playground?.wrapper).toMatchObject({
+ component: 'HStack',
+ props: {gap: 2, width: 300},
+ });
+ expect(stackItem!.playground?.defaults).toMatchObject({
+ size: 'fill',
+ children: expect.objectContaining({__element: 'Card'}),
+ });
+ });
+
it('Lightbox declares an overlay playground with a closed initial state (#3657)', () => {
const core = components['@astryxdesign/core'];
const lightbox = core.find(c => c.name === 'Lightbox');
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index 39d7183dea..b9800950b8 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -43,6 +43,17 @@ export const docs = {
{className: 'astryx-grid-span'},
],
},
+ playground: {
+ defaults: {
+ columns: 3,
+ gap: 2,
+ children: [
+ {__element: 'Card', props: {padding: 4}, children: 'Item 1'},
+ {__element: 'Card', props: {padding: 4}, children: 'Item 2'},
+ {__element: 'Card', props: {padding: 4}, children: 'Item 3'},
+ ],
+ },
+ },
description: 'Grid container with fixed or responsive columns.',
props: [
{
diff --git a/packages/core/src/Grid/GridSpan.doc.mjs b/packages/core/src/Grid/GridSpan.doc.mjs
index 3a97a33e12..e0c8518768 100644
--- a/packages/core/src/Grid/GridSpan.doc.mjs
+++ b/packages/core/src/Grid/GridSpan.doc.mjs
@@ -8,6 +8,13 @@ export const docs = {
displayName: 'Grid Span',
isHiddenFromOverview: true,
description: 'Grid item that spans multiple columns or rows.',
+ playground: {
+ wrapper: {component: 'Grid', props: {columns: 3, gap: 2}},
+ defaults: {
+ columns: 2,
+ children: 'Spans 2 columns',
+ },
+ },
props: [
{
name: 'columns',
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index a15db3b097..49c08a5bcc 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -39,6 +39,17 @@ export const docs = {
displayName: 'Stack',
description:
'Unified stack layout component with a direction prop. Use direction="horizontal" for left-to-right flow or direction="vertical" (default) for top-to-bottom. For convenience, HStack and VStack are pre-configured wrappers.',
+ playground: {
+ defaults: {
+ direction: 'horizontal',
+ gap: 2,
+ children: [
+ {__element: 'Card', props: {padding: 3}, children: 'Item 1'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 2'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 3'},
+ ],
+ },
+ },
props: [
{
name: 'direction',
@@ -174,6 +185,16 @@ export const docs = {
displayName: 'H Stack',
description:
'Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.',
+ playground: {
+ defaults: {
+ gap: 2,
+ children: [
+ {__element: 'Card', props: {padding: 3}, children: 'Item 1'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 2'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 3'},
+ ],
+ },
+ },
props: [
{
name: 'gap',
@@ -301,6 +322,16 @@ export const docs = {
displayName: 'V Stack',
description:
'Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.',
+ playground: {
+ defaults: {
+ gap: 2,
+ children: [
+ {__element: 'Card', props: {padding: 3}, children: 'Item 1'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 2'},
+ {__element: 'Card', props: {padding: 3}, children: 'Item 3'},
+ ],
+ },
+ },
props: [
{
name: 'gap',
@@ -423,6 +454,13 @@ export const docs = {
displayName: 'Stack Item',
description:
'Stack item for controlling individual item behavior within a stack. Supports polymorphic rendering.',
+ playground: {
+ wrapper: {component: 'HStack', props: {gap: 2, width: 300}},
+ defaults: {
+ size: 'fill',
+ children: {__element: 'Card', props: {padding: 3}, children: 'Fills the row'},
+ },
+ },
props: [
{
name: 'size',