Feature : Components Documentation for "rest props"

bin/api-docs/gen-components-docs/index.mjs

@@ -116,6 +116,7 @@ await Promise.all(
 		const docs = generateMarkdownDocs( {
 			typeDocs,
 			subcomponentTypeDocs,
+			additionalProps: manifest.additionalProps,
 		} );
 		const outputFile = path.resolve(
 			path.dirname( manifestPath ),

bin/api-docs/gen-components-docs/markdown/index.mjs

@@ -21,15 +21,19 @@ function normalizeTrailingNewline( str ) {
 	return str.replace( /\n*$/, '\n' );
 }
 
-export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
+export function generateMarkdownDocs( {
+	typeDocs,
+	subcomponentTypeDocs,
+	additionalProps,
+} ) {
 	const mainDocsJson = [
 		{ h1: typeDocs.displayName },
 		'<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->',
 		{
 			p: `<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-${ typeDocs.displayName.toLowerCase() }--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>`,
 		},
 		normalizeTrailingNewline( typeDocs.description ),
-		...generateMarkdownPropsJson( typeDocs.props ),
+		...generateMarkdownPropsJson( typeDocs.props, {}, additionalProps ),
 	];
 
 	const subcomponentDocsJson = subcomponentTypeDocs?.length

bin/api-docs/gen-components-docs/markdown/props.mjs

@@ -18,7 +18,11 @@ function renderPropType( type ) {
 	}
 }
 
-export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
+export function generateMarkdownPropsJson(
+	props,
+	{ headingLevel = 2 } = {},
+	additionalProps = false
+) {
 	const sortedKeys = Object.keys( props ).sort( ( [ a ], [ b ] ) =>
 		a.localeCompare( b )
 	);
@@ -46,5 +50,12 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 		} )
 		.filter( Boolean );
 
+	if ( additionalProps ) {
+		propsJson.push( [
+			{ [ `h${ headingLevel + 1 }` ]: `\`Additional props\`` },
+			`All other props will be passed directly to the underlying \`${ additionalProps }\` element.`,
+		] );
+	}
+
 	return [ { [ `h${ headingLevel }` ]: 'Props' }, ...propsJson ];
 }

packages/components/schemas/docs-manifest.json

@@ -32,6 +32,11 @@
 				},
 				"required": [ "displayName", "filePath" ]
 			}
+		},
+		"additionalProps": {
+			"type": "string",
+			"default": false,
+			"description": "The wrapper associated with the component which accepts additional props."
 		}
 	},
 	"required": [ "displayName", "filePath" ]

packages/components/src/badge/README.md

@@ -20,3 +20,7 @@ Badge variant.
  - Type: `"default" | "info" | "success" | "warning" | "error"`
  - Required: No
  - Default: `default`
+
+### `Additional props`
+
+All other props will be passed directly to the underlying `span` element.

packages/components/src/badge/docs-manifest.json

@@ -1,5 +1,6 @@
 {
 	"$schema": "../../schemas/docs-manifest.json",
 	"displayName": "Badge",
-	"filePath": "./index.tsx"
+	"filePath": "./index.tsx",
+	"additionalProps": "span"
 }

packages/components/src/badge/stories/index.story.tsx

@@ -13,6 +13,14 @@ const meta = {
 	title: 'Components/Containers/Badge',
 	id: 'components-badge',
 	tags: [ 'status-private' ],
+	argTypes: {
+		// @ts-expect-error
+		'': {
+			control: false,
+			table: { category: 'Other' },
+			description: 'This component also accepts props of `span`',
+		},
+	},
 } satisfies Meta< typeof Badge >;
 
 export default meta;