Merge branch 'WordPress:trunk' into trunk

Author: karthick-murugan

LICENSE.md

@@ -1,6 +1,6 @@
 ## Gutenberg
 
-    Copyright 2016-2024 by the contributors
+    Copyright 2016-2025 by the contributors
 
 **License for Contributions (on and after April 15, 2021)**
 

bin/api-docs/gen-components-docs/get-tags-from-storybook.mjs

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import fs from 'node:fs/promises';
+import babel from '@babel/core';
+
+/**
+ * Returns `meta.tags` from a Storybook file.
+ *
+ * @param {string} filePath
+ * @return {Promise<string[]>} Array of tags.
+ */
+export async function getTagsFromStorybook( filePath ) {
+	const fileContent = await fs.readFile( filePath, 'utf8' );
+	const parsedFile = babel.parse( fileContent, {
+		filename: filePath,
+	} );
+
+	const meta = parsedFile.program.body.find(
+		( node ) =>
+			node.type === 'VariableDeclaration' &&
+			node.declarations[ 0 ].id.name === 'meta'
+	);
+
+	return (
+		meta.declarations[ 0 ].init.properties
+			.find( ( node ) => node.key.name === 'tags' )
+			?.value.elements.map( ( node ) => node.value ) ?? []
+	);
+}

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

@@ -11,6 +11,7 @@ import path from 'path';
  */
 import { generateMarkdownDocs } from './markdown/index.mjs';
 import { getDescriptionsForSubcomponents } from './get-subcomponent-descriptions.mjs';
+import { getTagsFromStorybook } from './get-tags-from-storybook.mjs';
 
 const MANIFEST_GLOB = 'packages/components/src/**/docs-manifest.json';
 
@@ -113,9 +114,17 @@ await Promise.all(
 			} ) ?? []
 		);
 
+		const tags = await getTagsFromStorybook(
+			path.resolve(
+				path.dirname( manifestPath ),
+				'stories/index.story.tsx'
+			)
+		);
+
 		const docs = generateMarkdownDocs( {
 			typeDocs,
 			subcomponentTypeDocs,
+			tags,
 		} );
 		const outputFile = path.resolve(
 			path.dirname( manifestPath ),

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

@@ -9,26 +9,32 @@ import json2md from 'json2md';
 import { generateMarkdownPropsJson } from './props.mjs';
 
 /**
- * If the string is contentful, ensure that it ends with a single newline.
- * Otherwise normalize to `undefined`.
+ * Converter for strings that are already formatted as Markdown.
  *
- * @param {string} [str]
+ * @param {string} [input]
+ * @return {string} The trimmed input if it is contentful, otherwise an empty string.
  */
-function normalizeTrailingNewline( str ) {
-	if ( ! str?.trim() ) {
-		return undefined;
-	}
-	return str.replace( /\n*$/, '\n' );
-}
+json2md.converters.md = ( input ) => {
+	return input?.trim() || '';
+};
 
-export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
+export function generateMarkdownDocs( {
+	typeDocs,
+	subcomponentTypeDocs,
+	tags,
+} ) {
 	const mainDocsJson = [
 		{ h1: typeDocs.displayName },
 		'<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->',
+		tags.includes( 'status-private' ) && [
+			{
+				p: '🔒 This component is locked as a [private API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-private-apis/). We do not yet recommend using this outside of the Gutenberg project.',
+			},
+		],
 		{
 			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 ),
+		{ md: typeDocs.description },
 		...generateMarkdownPropsJson( typeDocs.props ),
 	];
 
@@ -39,7 +45,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 					{
 						h3: subcomponentTypeDoc.displayName,
 					},
-					normalizeTrailingNewline( subcomponentTypeDoc.description ),
+					{ md: subcomponentTypeDoc.description },
 					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
 						headingLevel: 4,
 					} ),
@@ -49,5 +55,5 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 
 	return json2md(
 		[ ...mainDocsJson, ...subcomponentDocsJson ].filter( Boolean )
-	);
+	).replace( /\n+$/gm, '\n' ); // clean unnecessary consecutive newlines
 }

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

@@ -33,7 +33,6 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 
 			return [
 				{ [ `h${ headingLevel + 1 }` ]: `\`${ key }\`` },
-				prop.description,
 				{
 					ul: [
 						`Type: \`${ renderPropType( prop.type ) }\``,
@@ -42,6 +41,7 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 							`Default: \`${ prop.defaultValue.value }\``,
 					].filter( Boolean ),
 				},
+				{ md: prop.description },
 			];
 		} )
 		.filter( Boolean );

bin/tsconfig.json

@@ -16,6 +16,7 @@
 		"noEmit": true,
 		"outDir": ".cache"
 	},
+	"include": [],
 	"files": [
 		"./api-docs/update-api-docs.js",
 		"./plugin/config.js",

bin/validate-tsconfig.mjs

@@ -29,14 +29,33 @@ for ( const packageName of packagesWithTypes ) {
 		hasErrors = true;
 	}
 
-	const packageJson = JSON.parse(
-		readFileSync( `packages/${ packageName }/package.json`, 'utf8' )
-	);
-	const tsconfigJson = JSON.parse(
-		stripJsonComments(
-			readFileSync( `packages/${ packageName }/tsconfig.json`, 'utf8' )
-		)
-	);
+	let packageJson;
+	try {
+		packageJson = JSON.parse(
+			readFileSync( `packages/${ packageName }/package.json`, 'utf8' )
+		);
+	} catch ( e ) {
+		console.error(
+			`Error parsing package.json for package ${ packageName }`
+		);
+		throw e;
+	}
+	let tsconfigJson;
+	try {
+		tsconfigJson = JSON.parse(
+			stripJsonComments(
+				readFileSync(
+					`packages/${ packageName }/tsconfig.json`,
+					'utf8'
+				)
+			)
+		);
+	} catch ( e ) {
+		console.error(
+			`Error parsing tsconfig.json for package ${ packageName }`
+		);
+		throw e;
+	}
 	if ( packageJson.dependencies ) {
 		for ( const dependency of Object.keys( packageJson.dependencies ) ) {
 			if ( dependency.startsWith( '@wordpress/' ) ) {

docs/getting-started/faq.md

@@ -8,7 +8,7 @@ What follows is a set of questions that have come up from the last few years of
 
 “Gutenberg” is the name of the project to create a new editor experience for WordPress — contributors have been working on it since January 2017 and it’s one of the most significant changes to WordPress in years. It’s built on the idea of using “blocks” to write and design posts and pages. This will serve as the foundation for future improvements to WordPress, including blocks as a way not just to design posts and pages, but also entire sites. The overall goal is to simplify the first-time user experience of WordPress — for those who are writing, editing, publishing, and designing web pages. The editing experience is intended to give users a better visual representation of what their post or page will look like when they hit publish. Originally, this was the kickoff goal:
 
-> The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.
+> The editor will endeavor to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.
 
 Key takeaways include the following points:
 

docs/reference-guides/core-blocks.md

@@ -661,7 +661,7 @@ Contains the block elements used to render a post, like the title, date, feature
 -	**Name:** core/post-template
 -	**Category:** theme
 -	**Ancestor:** core/query
--	**Supports:** align (full, wide), color (background, gradients, link, text), interactivity (clientNavigation), layout, spacing (blockGap), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
+-	**Supports:** align (full, wide), color (background, gradients, link, text), interactivity (clientNavigation), layout, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
 
 ## Post Terms
 

jsconfig.json

@@ -247,6 +247,8 @@ function gutenberg_set_up_cross_origin_isolation() {
  * Uses an output buffer to add crossorigin="anonymous" where needed.
  *
  * @link https://web.dev/coop-coep/
+ *
+ * @global bool $is_safari
  */
 function gutenberg_start_cross_origin_isolation_output_buffer(): void {
 	global $is_safari;