Skip to content

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

TypeScript

docs(cli): fix Card example titles and add playground defaults (#3225)

Cindy Zhang882d2b1dbf92
diff --git a/.changeset/card-example-titles-and-playground-defaults.md b/.changeset/card-example-titles-and-playground-defaults.md
new file mode 100644
index 0000000000..666d8ec9fa
--- /dev/null
+++ b/.changeset/card-example-titles-and-playground-defaults.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[docs] Rename the ClickableCard and SelectableCard examples to follow the "Component — Variant" title convention (`Clickable Card — Nested Button`, `Selectable Card — Multi-select`), and add playground defaults to both card docs so their docsite previews show realistic card content (#2877)
+
+@cixzhang
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index dde0b3b491..04024aa7d8 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -337,8 +337,7 @@ describe('componentRegistry', () => {
// rather than by a name prefix.
const hooks = core.filter(
c =>
- /^use[A-Z]/.test(c.name) &&
- (exampleRegistry[c.name]?.length ?? 0) > 0,
+ /^use[A-Z]/.test(c.name) && (exampleRegistry[c.name]?.length ?? 0) > 0,
);
expect(hooks.length).toBeGreaterThan(15);
expect(hooks.map(h => h.name)).toContain('useTheme');
@@ -666,7 +665,9 @@ describe('themeRegistry', () => {
});
it('has no entries for non-theme packages', () => {
- const nonTheme = packages.filter(p => !p.name.startsWith('@astryxdesign/theme-'));
+ const nonTheme = packages.filter(
+ p => !p.name.startsWith('@astryxdesign/theme-'),
+ );
for (const pkg of nonTheme) {
expect(registrySource).not.toContain(`'${pkg.name}':`);
}
@@ -809,3 +810,68 @@ describe('exampleRegistry', () => {
expect(longest).toBeGreaterThan(200);
});
});
+
+// ── Block example title convention (Component — Variant) ─────────────────
+// Example block `displayName`s should read like "Component — Variant" using an
+// em-dash separator, not leak PascalCase/export-name wording. The Card example
+// titles previously rendered as "Clickable Card With Nested Button" and
+// "Selectable Card Multi".
+describe('block example title convention', () => {
+ const blocksDir = fileURLToPath(
+ new URL('../../../../packages/cli/templates/blocks', import.meta.url),
+ );
+
+ function displayNameOf(relPath: string): string | null {
+ const content = fs.readFileSync(`${blocksDir}/${relPath}`, 'utf-8');
+ const m = content.match(/displayName:\s*['"]([^'"]+)['"]/);
+ return m ? m[1] : null;
+ }
+
+ it('Card example titles use the em-dash variant convention', () => {
+ expect(
+ displayNameOf('components/Card/ClickableCardWithNestedButton.doc.mjs'),
+ ).toBe('Clickable Card — Nested Button');
+ expect(displayNameOf('components/Card/SelectableCardMulti.doc.mjs')).toBe(
+ 'Selectable Card — Multi-select',
+ );
+ });
+});
+
+// ── Playground defaults for Card components (BB-006 / #2008) ──────────────
+// ClickableCard and SelectableCard playgrounds rendered empty because their
+// docs carried no `playground.defaults`. Defaults must flow into the generated
+// registry so previews demonstrate realistic card layouts.
+describe('Card playground defaults', () => {
+ function coreComponent(name: string) {
+ return Object.values(components)
+ .flat()
+ .find(c => c.name === name);
+ }
+
+ it('ClickableCard has playground defaults with label, href, and body content', () => {
+ const entry = coreComponent('ClickableCard');
+ expect(entry).toBeDefined();
+ const defaults = entry!.playground?.defaults as
+ | Record<string, unknown>
+ | undefined;
+ expect(defaults).toBeDefined();
+ expect(typeof defaults!.label).toBe('string');
+ expect(defaults!.href).toBeDefined();
+ // children is a resolved element descriptor, not empty.
+ expect(defaults!.children).toBeTruthy();
+ expect(typeof defaults!.children).toBe('object');
+ });
+
+ it('SelectableCard has playground defaults with label, selection state, and body content', () => {
+ const entry = coreComponent('SelectableCard');
+ expect(entry).toBeDefined();
+ const defaults = entry!.playground?.defaults as
+ | Record<string, unknown>
+ | undefined;
+ expect(defaults).toBeDefined();
+ expect(typeof defaults!.label).toBe('string');
+ expect(typeof defaults!.isSelected).toBe('boolean');
+ expect(defaults!.children).toBeTruthy();
+ expect(typeof defaults!.children).toBe('object');
+ });
+});
diff --git a/packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.doc.mjs b/packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.doc.mjs
index d8e47e0fa0..9a116b7927 100644
--- a/packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.doc.mjs
+++ b/packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.doc.mjs
@@ -5,7 +5,7 @@ export const doc = {
type: 'block',
exampleFor: 'ClickableCard',
name: 'ClickableCardWithNestedButton',
- displayName: 'Clickable Card With Nested Button',
+ displayName: 'Clickable Card — Nested Button',
description:
'A product card that navigates on click but has an independent "Add to cart" button inside.',
isReady: true,
diff --git a/packages/cli/templates/blocks/components/Card/SelectableCardMulti.doc.mjs b/packages/cli/templates/blocks/components/Card/SelectableCardMulti.doc.mjs
index 5a3a240f22..ad53cfce9c 100644
--- a/packages/cli/templates/blocks/components/Card/SelectableCardMulti.doc.mjs
+++ b/packages/cli/templates/blocks/components/Card/SelectableCardMulti.doc.mjs
@@ -5,7 +5,7 @@ export const doc = {
type: 'block',
exampleFor: 'SelectableCard',
name: 'SelectableCardMulti',
- displayName: 'Selectable Card Multi',
+ displayName: 'Selectable Card — Multi-select',
description:
'Multi-select tag picker using color variant selectable cards with color-matched selection borders.',
isReady: true,
diff --git a/packages/core/src/ClickableCard/ClickableCard.doc.mjs b/packages/core/src/ClickableCard/ClickableCard.doc.mjs
index 519a44f29a..9bdde0dc09 100644
--- a/packages/core/src/ClickableCard/ClickableCard.doc.mjs
+++ b/packages/core/src/ClickableCard/ClickableCard.doc.mjs
@@ -37,6 +37,21 @@ export const docs = {
container: true,
targets: [{className: 'astryx-clickable-card', visualProps: ['variant']}],
},
+ playground: {
+ defaults: {
+ label: 'View product details',
+ href: '#',
+ padding: 4,
+ children: {
+ __element: 'XDSVStack',
+ props: {gap: 1},
+ children: [
+ {__element: 'XDSHeading', props: {level: 3}, children: 'Wireless Headphones'},
+ {__element: 'XDSText', props: {type: 'body'}, children: 'Noise-cancelling over-ear headphones with 30-hour battery life.'},
+ ],
+ },
+ },
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/SelectableCard/SelectableCard.doc.mjs b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
index 66a86eb6af..aaef567ce9 100644
--- a/packages/core/src/SelectableCard/SelectableCard.doc.mjs
+++ b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
@@ -36,6 +36,21 @@ export const docs = {
container: true,
targets: [{className: 'astryx-selectable-card', visualProps: ['selected']}],
},
+ playground: {
+ defaults: {
+ label: 'Pro plan',
+ isSelected: true,
+ padding: 4,
+ children: {
+ __element: 'XDSVStack',
+ props: {gap: 1},
+ children: [
+ {__element: 'XDSHeading', props: {level: 3}, children: 'Pro plan'},
+ {__element: 'XDSText', props: {type: 'body'}, children: '$29/month — unlimited projects and priority support.'},
+ ],
+ },
+ },
+ },
};
/** @type {import('../docs-types').TranslationDoc} */