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.mdnew file mode 100644index 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)++@cixzhangdiff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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} */