Skip to content

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

TypeScript

fix(cli): extractBrief for multi-component READMEs (#267) (#268)

Cindy Zhanga27434276543
diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjs
index f93b3accc4..86c1cc0fc7 100644
--- a/packages/cli/src/commands/component.mjs
+++ b/packages/cli/src/commands/component.mjs
@@ -21,6 +21,7 @@ const DIR_TO_CATEGORY = {
Center: 'Layout',
Grid: 'Layout',
Layout: 'Layout',
+ Stack: 'Layout',
// Display
Avatar: 'Display',
Badge: 'Display',
@@ -427,17 +428,48 @@ export function extractBrief(content, componentName) {
}
// 2. Extract props from the Props table
+ // Supports two README layouts:
+ // a) Single-component: `## Props` section with a table
+ // b) Multi-component: `### XDSComponentName` subsection with a table
const props = [];
let inPropsTable = false;
let headerParsed = false;
+ let inComponentSection = false;
+
+ // For multi-component READMEs, find the section for this specific component
+ const componentSectionRe = new RegExp(
+ `^###\\s+${displayName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`
+ );
for (const line of lines) {
+ // Detect `## Props` (single-component layout)
if (/^#{2,3}\s+Props/.test(line)) {
inPropsTable = true;
headerParsed = false;
continue;
}
- if (inPropsTable && /^#{2,3}\s+/.test(line) && !/Props/.test(line)) {
+
+ // Detect `### XDSComponentName` (multi-component layout)
+ if (componentSectionRe.test(line)) {
+ inComponentSection = true;
+ continue;
+ }
+
+ // Exit component section when hitting another ### heading
+ if (inComponentSection && /^###\s+/.test(line) && !componentSectionRe.test(line)) {
+ inComponentSection = false;
+ if (inPropsTable) inPropsTable = false;
+ continue;
+ }
+
+ // Within a component section, a pipe-delimited table is a props table
+ if (inComponentSection && !inPropsTable && /^\|\s*`?Prop/.test(line)) {
+ inPropsTable = true;
+ headerParsed = false;
+ // Don't continue — let the header row logic below handle it
+ }
+
+ if (inPropsTable && /^#{2,3}\s+/.test(line) && !/Props/.test(line) && !inComponentSection) {
inPropsTable = false;
continue;
}
@@ -449,7 +481,7 @@ export function extractBrief(content, componentName) {
continue;
}
// Skip the header row itself
- if (!headerParsed && /^\|\s*Prop/.test(line)) continue;
+ if (!headerParsed && /^\|\s*`?Prop/.test(line)) continue;
// Parse prop row: | `name` | `type` | `default` | description |
const cells = line
@@ -491,30 +523,47 @@ export function extractBrief(content, componentName) {
}
// 4. Extract first code example
+ // For multi-component READMEs, prefer examples from the component's section
let example = '';
+ let fallbackExample = '';
let inCode = false;
+ let inCompSection = false;
+
for (const line of lines) {
+ // Track whether we're in this component's subsection
+ if (componentSectionRe.test(line)) {
+ inCompSection = true;
+ continue;
+ }
+ if (inCompSection && /^###\s+/.test(line) && !componentSectionRe.test(line)) {
+ inCompSection = false;
+ }
+
if (line.startsWith('```tsx') || line.startsWith('```jsx')) {
inCode = true;
continue;
}
if (inCode && line.startsWith('```')) {
- break;
+ inCode = false;
+ continue;
}
if (inCode) {
const trimmed = line.trim();
// Take the first substantial JSX line
if (trimmed.startsWith('<XDS') || trimmed.startsWith('<')) {
- // Collect multi-line JSX
- example = trimmed;
- if (!trimmed.includes('/>') && !trimmed.includes('</')) {
- // Multi-line — just take the opening tag
+ if (inCompSection && !example) {
+ // Prefer example from this component's section
example = trimmed;
+ } else if (!fallbackExample) {
+ // Fallback: first example from anywhere in the README
+ fallbackExample = trimmed;
}
- break;
+ if (example) break; // Found one in the right section, done
}
}
}
+ // Use component-section example if found, otherwise fallback
+ if (!example) example = fallbackExample;
// 5. Build output
const output = [];
diff --git a/packages/core/src/Stack/README.md b/packages/core/src/Stack/README.md
index 13c7656bdd..fc49bcc2fd 100644
--- a/packages/core/src/Stack/README.md
+++ b/packages/core/src/Stack/README.md
@@ -51,13 +51,13 @@ Horizontal stack for arranging items left-to-right. Supports polymorphic renderi
</XDSHStack>
```
-| Prop | Type | Default | Description |
-| ---------- | ------------------------------------------- | ----------- | --------------------------- |
-| `gap` | `SpacingScale` | — | Spacing token between items |
-| `vAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Vertical alignment |
-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
-| `element` | `ElementType` | `'div'` | HTML element to render |
-| `children` | `ReactNode` | — | Stack content |
+| Prop | Type | Default | Description |
+| ---------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------ |
+| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |
+| `vAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Vertical alignment |
+| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
+| `element` | `ElementType` | `'div'` | HTML element to render |
+| `children` | `ReactNode` | — | Stack content |
### XDSVStack
@@ -83,13 +83,13 @@ Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering
</XDSVStack>
```
-| Prop | Type | Default | Description |
-| ---------- | ------------------------------------------- | ----------- | --------------------------- |
-| `gap` | `SpacingScale` | — | Spacing token between items |
-| `hAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Horizontal alignment |
-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
-| `element` | `ElementType` | `'div'` | HTML element to render |
-| `children` | `ReactNode` | — | Stack content |
+| Prop | Type | Default | Description |
+| ---------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------ |
+| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |
+| `hAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Horizontal alignment |
+| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
+| `element` | `ElementType` | `'div'` | HTML element to render |
+| `children` | `ReactNode` | — | Stack content |
### XDSStackItem
@@ -140,12 +140,12 @@ import * as stylex from '@stylexjs/stylex';
</div>;
```
-| Option | Type | Default | Description |
-| ------------ | ------------------------------------------- | ---------- | --------------------------- |
-| `direction` | `'horizontal' \| 'vertical'` | Required | Stack direction |
-| `gap` | `SpacingScale` | — | Spacing token between items |
-| `crossAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Cross-axis alignment |
-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
+| Option | Type | Default | Description |
+| ------------ | ------------------------------------------- | ---------- | ------------------------------------------------------------------------ |
+| `direction` | `'horizontal' \| 'vertical'` | Required | Stack direction |
+| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |
+| `crossAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Cross-axis alignment |
+| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
### stackItem