An open source design system that's fully customizable and agent ready
TypeScript
fix(lint): enforce @example code fence format in docblocks (#485)
Cindy Zhangb19d07c6aee2
diff --git a/internal/eslint-plugin-xds/docblock-example-format.js b/internal/eslint-plugin-xds/docblock-example-format.jsnew file mode 100644index 0000000000..09800f4bfd--- /dev/null+++ b/internal/eslint-plugin-xds/docblock-example-format.js@@ -0,0 +1,92 @@+/**+ * @file docblock-example-format.js+ * @description ESLint rule enforcing @example blocks use fenced code.+ *+ * Valid:+ * @example+ * ```+ * <XDSButton label="Click" />+ * ```+ *+ * Invalid:+ * @example <XDSButton label="Click" />+ * @example+ * <XDSButton label="Click" />+ */++/**+ * Checks JSDoc comments for @example formatting violations.+ *+ * Pattern 1 (inline): @example followed by code on the same line+ * e.g. `@example getInitials('John') // 'J'`+ *+ * Pattern 2 (missing fence): @example on its own line, but the next+ * non-empty line is not a code fence (```)+ */+const docblockExampleFormatRule = {+ meta: {+ type: 'suggestion',+ docs: {+ description:+ 'Enforce @example blocks use ``` fenced code on a separate line',+ category: 'Stylistic Issues',+ recommended: true,+ },+ fixable: 'code',+ messages: {+ inlineExample:+ '@example must not have code on the same line. Put ``` on the next line, then the code.',+ missingFence:+ '@example must be followed by a ``` code fence on the next line.',+ },+ schema: [],+ },+ create(context) {+ const sourceCode = context.sourceCode ?? context.getSourceCode();++ return {+ Program() {+ const comments = sourceCode.getAllComments();++ for (const comment of comments) {+ if (comment.type !== 'Block') continue;++ const lines = comment.value.split('\n');++ for (let i = 0; i < lines.length; i++) {+ const line = lines[i];+ const trimmed = line.replace(/^\s*\*?\s*/, '');++ // Pattern 1: @example with code on the same line+ // e.g. "@example getInitials('John')" or '@example "mod+k"'+ if (/^@example\s+\S/.test(trimmed)) {+ context.report({+ node: comment,+ messageId: 'inlineExample',+ });+ continue;+ }++ // Pattern 2: @example alone, but next non-empty line isn't ```+ if (/^@example\s*$/.test(trimmed)) {+ // Look ahead for the next non-empty comment line+ for (let j = i + 1; j < lines.length; j++) {+ const nextTrimmed = lines[j].replace(/^\s*\*?\s*/, '');+ if (nextTrimmed === '') continue; // skip blank lines+ if (!nextTrimmed.startsWith('```')) {+ context.report({+ node: comment,+ messageId: 'missingFence',+ });+ }+ break; // only check the first non-empty line after @example+ }+ }+ }+ }+ },+ };+ },+};++export default docblockExampleFormatRule;diff --git a/internal/eslint-plugin-xds/docblock-example-format.test.mjs b/internal/eslint-plugin-xds/docblock-example-format.test.mjsnew file mode 100644index 0000000000..f64fa49f84--- /dev/null+++ b/internal/eslint-plugin-xds/docblock-example-format.test.mjs@@ -0,0 +1,173 @@+/**+ * @file docblock-example-format.test.mjs+ * Tests for the docblock-example-format ESLint rule.+ */++import {describe, it} from 'vitest';+import {RuleTester} from 'eslint';+import tseslint from 'typescript-eslint';+import docblockExampleFormatRule from './docblock-example-format.js';++const ruleTester = new RuleTester({+ languageOptions: {+ parser: tseslint.parser,+ parserOptions: {+ ecmaFeatures: {jsx: true},+ },+ },+});++describe('docblock-example-format', () => {+ruleTester.run('docblock-example-format', docblockExampleFormatRule, {+ valid: [+ // Pattern 1: @example on its own line, ``` on next line+ {+ code: `+/**+ * A button component.+ *+ * @example+ * \`\`\`+ * <Button label="Click" />+ * \`\`\`+ */+function Button() {}+ `,+ },+ // @example with ```tsx language tag+ {+ code: `+/**+ * @example+ * \`\`\`tsx+ * <Button label="Click" />+ * \`\`\`+ */+function Button() {}+ `,+ },+ // No @example at all — perfectly fine+ {+ code: `+/**+ * A simple helper function.+ */+function helper() {}+ `,+ },+ // @example with blank line before fence — still valid+ {+ code: `+/**+ * @example+ *+ * \`\`\`+ * <Button />+ * \`\`\`+ */+function Button() {}+ `,+ },+ // Multiple valid @example blocks+ {+ code: `+/**+ * @example+ * \`\`\`+ * <Button variant="primary" />+ * \`\`\`+ *+ * @example+ * \`\`\`+ * <Button variant="ghost" />+ * \`\`\`+ */+function Button() {}+ `,+ },+ ],++ invalid: [+ // Inline: @example with code on the same line+ {+ code: `+/**+ * @example getInitials('John Doe') // 'JD'+ */+function getInitials() {}+ `,+ errors: [{messageId: 'inlineExample'}],+ },+ // Inline: @example with JSX on same line+ {+ code: `+/**+ * @example <Button label="Click" />+ */+function Button() {}+ `,+ errors: [{messageId: 'inlineExample'}],+ },+ // Inline: @example with string on same line+ {+ code: `+/**+ * @example "mod+k", "mod+shift+p"+ */+function Shortcut() {}+ `,+ errors: [{messageId: 'inlineExample'}],+ },+ // Missing fence: @example then code without ```+ {+ code: `+/**+ * @example+ * <Button label="Click" />+ */+function Button() {}+ `,+ errors: [{messageId: 'missingFence'}],+ },+ // Missing fence: @example then comment without ```+ {+ code: `+/**+ * @example+ * // Default usage+ * <Button label="Click" />+ */+function Button() {}+ `,+ errors: [{messageId: 'missingFence'}],+ },+ // Mixed: one valid, one inline+ {+ code: `+/**+ * @example+ * \`\`\`+ * <Button />+ * \`\`\`+ *+ * @example dividers={['top']}+ */+function Section() {}+ `,+ errors: [{messageId: 'inlineExample'}],+ },+ // Prop-level docblock with inline example+ {+ code: `+interface Props {+ /**+ * @example dividers={['top', 'bottom']}+ */+ dividers?: string[];+}+ `,+ errors: [{messageId: 'inlineExample'}],+ },+ ],+});+});diff --git a/internal/eslint-plugin-xds/index.js b/internal/eslint-plugin-xds/index.jsindex 9ccdead8bc..ed9c3efc1f 100644--- a/internal/eslint-plugin-xds/index.js+++ b/internal/eslint-plugin-xds/index.js@@ -5,6 +5,7 @@* Rules:* - no-hardcoded-styles: Enforces usage of design tokens instead of hardcoded values in StyleX* - boolean-prop-naming: Enforces is/has prefix on boolean props in *Props interfaces+ * - docblock-example-format: Enforces @example blocks use ``` fenced code on a separate line** Philosophy: Strict for agents (CI), lenient for humans (local dev)* - "strict" config: All rules as errors - use in CI/agent environments@@ -12,6 +13,7 @@*/import booleanPropNamingRule from './boolean-prop-naming.js';+import docblockExampleFormatRule from './docblock-example-format.js';// =============================================================================// Rule: no-hardcoded-styles@@ -213,6 +215,7 @@ const plugin = {rules: {'no-hardcoded-styles': noHardcodedStylesRule,'boolean-prop-naming': booleanPropNamingRule,+ 'docblock-example-format': docblockExampleFormatRule,},configs: {},};@@ -225,6 +228,7 @@ plugin.configs.strict = {rules: {'@xds/no-hardcoded-styles': 'error','@xds/boolean-prop-naming': 'error',+ '@xds/docblock-example-format': 'error',},};@@ -236,6 +240,7 @@ plugin.configs.recommended = {rules: {'@xds/no-hardcoded-styles': 'warn','@xds/boolean-prop-naming': 'warn',+ '@xds/docblock-example-format': 'warn',},};diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsxindex 34f67b2099..09dd046df6 100644--- a/packages/core/src/Avatar/XDSAvatar.tsx+++ b/packages/core/src/Avatar/XDSAvatar.tsx@@ -220,8 +220,11 @@ export interface XDSAvatarProps extends Omit</*** Generates initials from a name string.* Takes the first letter of the first two words.- * @example getInitials('John Doe') // 'JD'- * @example getInitials('Alice') // 'A'+ * @example+ * ```+ * getInitials('John Doe') // 'JD'+ * getInitials('Alice') // 'A'+ * ```*/function getInitials(name: string): string {const words = name.trim().split(/\s+/);diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsxindex 5d6418d249..ffcc79ad4d 100644--- a/packages/core/src/Banner/XDSBanner.tsx+++ b/packages/core/src/Banner/XDSBanner.tsx@@ -92,7 +92,9 @@ export interface XDSBannerProps {* Typically an XDSButton with a secondary or ghost variant.** @example+ * ```* endContent={<XDSButton label="Retry" variant="ghost" onClick={handleRetry} />}+ * ```*/endContent?: ReactNode;/**diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsxindex 81136bc934..1c5fce5ee8 100644--- a/packages/core/src/Calendar/XDSCalendar.tsx+++ b/packages/core/src/Calendar/XDSCalendar.tsx@@ -183,7 +183,9 @@ export type XDSCalendarProps = XDSCalendarSingleProps | XDSCalendarRangeProps;* A calendar component for selecting dates or date ranges.** @example+ * ```* <XDSCalendar value={selectedDate} onChange={setSelectedDate} />+ * ```*/export const XDSCalendar = forwardRef<XDSCalendarHandle, XDSCalendarProps>((props, ref) => {diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsxindex 30cd9ad20f..a11e231192 100644--- a/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPaletteShortcut.tsx@@ -46,14 +46,14 @@ const styles = stylex.create({* Map of modifier key names to display symbols.*/const KEY_DISPLAY: Record<string, string> = {- mod: '\u2318', // ⌘- ctrl: '\u2303', // ⌃- alt: '\u2325', // ⌥- shift: '\u21E7', // ⇧- enter: '\u21B5', // ↵+ mod: '\u2318', // ⌘+ ctrl: '\u2303', // ⌃+ alt: '\u2325', // ⌥+ shift: '\u21E7', // ⇧+ enter: '\u21B5', // ↵backspace: '\u232B', // ⌫escape: 'Esc',- tab: '\u21E5', // ⇥+ tab: '\u21E5', // ⇥up: '\u2191',down: '\u2193',left: '\u2190',@@ -65,7 +65,10 @@ export interface XDSCommandPaletteShortcutProps {* Keyboard shortcut string. Use "+" to separate keys.* Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.*- * @example "mod+k", "mod+shift+p", "enter"+ * @example+ * ```+ * "mod+k", "mod+shift+p", "enter"+ * ```*/keys: string;}@@ -82,7 +85,7 @@ export interface XDSCommandPaletteShortcutProps {export function XDSCommandPaletteShortcut({keys,}: XDSCommandPaletteShortcutProps) {- const parts = keys.split('+').map((key) => key.trim().toLowerCase());+ const parts = keys.split('+').map(key => key.trim().toLowerCase());return (<span {...stylex.props(styles.wrapper)} aria-hidden="true">diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsxindex 5eff85da39..05f06b67d5 100644--- a/packages/core/src/Pagination/XDSPagination.tsx+++ b/packages/core/src/Pagination/XDSPagination.tsx@@ -233,9 +233,11 @@ const styles = stylex.create({* Returns an array of page numbers and '...' strings.** @example+ * ```* generatePageRange(5, 10, 1) → [1, '...', 4, 5, 6, '...', 10]* generatePageRange(1, 10, 1) → [1, 2, 3, '...', 10]* generatePageRange(1, 5, 1) → [1, 2, 3, 4, 5]+ * ```*/export function generatePageRange(currentPage: number,diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsxindex 20daf48cac..dc8cfec101 100644--- a/packages/core/src/Section/XDSSection.tsx+++ b/packages/core/src/Section/XDSSection.tsx@@ -167,7 +167,10 @@ export interface XDSSectionProps {/*** Which sides should have divider borders.* Use 'start'/'end' for horizontal (respects RTL).- * @example dividers={['top', 'bottom']}+ * @example+ * ```+ * dividers={['top', 'bottom']}+ * ```*/dividers?: Array<'top' | 'bottom' | 'start' | 'end'>;diff --git a/packages/core/src/Table/columnUtils.ts b/packages/core/src/Table/columnUtils.tsindex 8e7abbb4c5..bbc9845f0d 100644--- a/packages/core/src/Table/columnUtils.ts+++ b/packages/core/src/Table/columnUtils.ts@@ -21,7 +21,10 @@ import type {* Create a proportional column width (fr-like).* Columns share available space proportionally.*- * @example proportional(2) // twice as wide as proportional(1)+ * @example+ * ```+ * proportional(2) // twice as wide as proportional(1)+ * ```*/export function proportional(value: number = 1): ProportionalWidth {return {type: 'proportional', value};@@ -30,7 +33,10 @@ export function proportional(value: number = 1): ProportionalWidth {/*** Create a fixed pixel column width.*- * @example pixel(200) // exactly 200px wide+ * @example+ * ```+ * pixel(200) // exactly 200px wide+ * ```*/export function pixel(value: number): PixelWidth {return {type: 'pixel', value};diff --git a/packages/core/src/Text/XDSFontWrapper.tsx b/packages/core/src/Text/XDSFontWrapper.tsxindex 6890b622f2..d4cf469af7 100644--- a/packages/core/src/Text/XDSFontWrapper.tsx+++ b/packages/core/src/Text/XDSFontWrapper.tsx@@ -49,6 +49,7 @@ export interface XDSFontWrapperProps {* Uses the reset.css stylesheet which references theme CSS custom properties.** @example+ * ```* // Default variant (dense scale)* <XDSFontWrapper>* <h1>Page Title</h1>@@ -59,17 +60,16 @@ export interface XDSFontWrapperProps {* </ul>* </XDSFontWrapper>*- * @example* // Editorial variant (larger heading scale)* <XDSFontWrapper variant="editorial">* <h1>Article Title</h1>* <p>Body text for long-form content.</p>* </XDSFontWrapper>*- * @example* // For global usage, apply to body:* // import '@xds/core/typography.css';* // <body className="xds-typography">+ * ```*/export function XDSFontWrapper({variant = 'default',@@ -104,10 +104,12 @@ XDSFontWrapper.displayName = 'XDSFontWrapper';* Use this for applying styles to native HTML elements programmatically.** @example+ * ```* const { headingStyles, proseStyles } = useXDSFontWrapperStyles();** <h1 {...stylex.props(headingStyles?.h1)}>Title</h1>* <p {...stylex.props(proseStyles?.p)}>Paragraph</p>+ * ```*/export function useXDSFontWrapperStyles() {const themeContext = useTheme();diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsxindex 2736389f0a..431f53fc95 100644--- a/packages/core/src/Text/XDSHeading.tsx+++ b/packages/core/src/Text/XDSHeading.tsx@@ -74,8 +74,10 @@ export interface XDSHeadingProps {* @default Same as `level`** @example+ * ```* // Visually styled as h2, but semantically h3 in document outline* <XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>+ * ```*/accessibilityLevel?: XDSHeadingLevel;diff --git a/packages/core/src/utils/dateParser.ts b/packages/core/src/utils/dateParser.tsindex 442e932761..b8dfd371b3 100644--- a/packages/core/src/utils/dateParser.ts+++ b/packages/core/src/utils/dateParser.ts@@ -243,7 +243,9 @@ export function parseISO(iso: ISODateString): Date {* Uses locale-aware formatting with full month name.** @example+ * ```* formatDisplayDate("2026-01-25") // "January 25, 2026"+ * ```*/export function formatDisplayDate(iso: ISODateString): string {const date = parseISO(iso);