chore: Add feat/jsdoc-require-returns-type eslint rule

.eslintrc.cjs

@@ -71,6 +71,7 @@ module.exports = {
 
 		// Turn of JSdoc types and use TypeScript types instead.
 		'jsdoc/no-types': [ 'off' ],
+		'jsdoc/require-returns': [ 'warn' ],
 
 		// Restrict the use of empty functions.
 		'no-empty-function': 'error',
@@ -133,6 +134,7 @@ module.exports = {
 			rules: {
 				'dot-notation': 'off',
 				'@typescript-eslint/dot-notation': 'error',
+				'@typescript-eslint/explicit-function-return-type': 'error',
 			},
 			parserOptions: {
 				project: true,

packages/blocks/src/block-manager/index.tsx

@@ -14,7 +14,9 @@ export default class BlockManager {
 	 * Update block definitions to be used while rendering blocks.
 	 * @param blockDefinitions - rendering implementaion for blocks.
 	 */
-	public static addBlockDefinitions( blockDefinitions: BlockDefinitions ) {
+	public static addBlockDefinitions(
+		blockDefinitions: BlockDefinitions
+	): void {
 		BlockManager.blockDefinitions = {
 			...BlockManager.blockDefinitions,
 			...blockDefinitions,
@@ -24,7 +26,8 @@ export default class BlockManager {
 	/**
 	 * Function to convert a flat list of blocks to a tree depending on `clientId` and `parentClientId`
 	 * @param blockList - A flat list of blocks.
-	 * @return A tree of blocks.
+	 *
+	 * @return {Array<BlockTreeNode>} A tree of blocks.
 	 */
 	public static flatListToHierarchical(
 		blockList?: BlockData[] | null
@@ -72,7 +75,8 @@ export default class BlockManager {
 	/**
 	 * Pre processes a flat list of blocks for rendering.
 	 * @param blockList - A flat list of blocks.
-	 * @return A tree of blocks with render functions.
+	 *
+	 * @return {Array<BlockTreeNode>} A tree of blocks with render functions.
 	 */
 	public static parseBlockForRendering(
 		blockList?: BlockData[] | null

packages/blocks/src/blocks/core-audio.tsx

@@ -12,7 +12,7 @@ import type { CoreAudio as CoreAudioType, CoreAudioProps } from '@snapwp/types';
  * @param props.attributes - Block attributes.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element|null} The rendered block.
  */
 const CoreAudio: CoreAudioType = ( {
 	attributes,

packages/blocks/src/blocks/core-button.tsx

@@ -13,7 +13,7 @@ import type {
  * @param props - The props for the block component.
  * @param props.attributes - Block attributes.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreButton: CoreButtonType = ( { attributes }: CoreButtonProps ) => {
 	const {

packages/blocks/src/blocks/core-buttons.tsx

@@ -11,7 +11,7 @@ import type {
  * @param props.attributes - Block attributes.
  * @param props.children - The block's children.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreButtons: CoreButtonsType = ( {
 	attributes,

packages/blocks/src/blocks/core-code.tsx

@@ -8,7 +8,7 @@ import type { CoreCode as CoreCodeType, CoreCodeProps } from '@snapwp/types';
  * @param props - The props for the block component.
  * @param props.attributes - Block attributes.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreCode: CoreCodeType = ( { attributes }: CoreCodeProps ) => {
 	const { style, cssClassName, content } = attributes || {};

packages/blocks/src/blocks/core-column.tsx

@@ -11,7 +11,7 @@ import type {
  * @param props.attributes - Block attributes.
  * @param props.children - The block's children.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreColumn: CoreColumnType = ( {
 	attributes,

packages/blocks/src/blocks/core-columns.tsx

@@ -11,7 +11,7 @@ import type {
  * @param props.attributes - Block attributes.
  * @param props.children - The block's children.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreColumns: CoreColumnsType = ( {
 	attributes,

packages/blocks/src/blocks/core-cover.tsx

@@ -23,7 +23,7 @@ const DEFAULT_FOCAL_POINT = { x: 0.5, y: 0.5 };
  *
  * @param focalPoint - The focal point coordinates object containing x and y values.
  *
- * @return CSS position string or undefined if no focal point
+ * @return {string} CSS position string or undefined if no focal point
  */
 const mediaPosition = ( focalPoint?: FocalPoint | null ): string => {
 	if ( ! focalPoint ) {
@@ -42,7 +42,8 @@ const mediaPosition = ( focalPoint?: FocalPoint | null ): string => {
  * @param root0.renderedHtml - Pre-rendered HTML string for class extraction
  * @param root0.connectedMediaItem - The connected media item object
  * @param root0.mediaDetails - The media details object
- * @return The rendered cover block or null if using featured image
+ *
+ * @return {React.JSX.Element} The rendered cover block or null if using featured image
  */
 const CoreCover: CoreCoverType = ( {
 	attributes,

packages/blocks/src/blocks/core-details.tsx

@@ -16,7 +16,7 @@ import type {
  * @param props.children - The block's children.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreDetails: CoreDetailsType = ( {
 	attributes,

packages/blocks/src/blocks/core-file.tsx

@@ -16,7 +16,7 @@ const FALLBACK_ARIA_LABEL = 'PDF embed';
  * @param props.attributes - Block attributes.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element|null} The rendered block.
  */
 const CoreFile: CoreFileType = ( {
 	attributes,

packages/blocks/src/blocks/core-freeform.tsx

@@ -10,7 +10,7 @@ import type {
  * @param props - The props for the block component.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element|null} The rendered block.
  */
 const CoreFreeform: CoreFreeformType = ( {
 	renderedHtml,

packages/blocks/src/blocks/core-gallery.tsx

@@ -16,7 +16,7 @@ import type {
  * @param props.children - The block's children.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreGallery: CoreGalleryType = ( {
 	attributes,

packages/blocks/src/blocks/core-group.tsx

@@ -19,9 +19,14 @@ import type {
  * @param props.style - Inline styles.
  * @param props.children - The content to render inside the element.
  *
- * @return The rendered HTML element or the children if no tag name is provided.
+ * @return {React.JSX.Element} The rendered HTML element or the children if no tag name is provided.
  */
-const Tag = ( { name, className, style, children }: TagProps ) => {
+const Tag = ( {
+	name,
+	className,
+	style,
+	children,
+}: TagProps ): React.JSX.Element => {
 	if ( ! name ) {
 		return <>{ children }</>;
 	}
@@ -37,7 +42,7 @@ const Tag = ( { name, className, style, children }: TagProps ) => {
  * @param props.children - The block's children.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreGroup: CoreGroupType = ( {
 	attributes,

packages/blocks/src/blocks/core-heading.tsx

@@ -12,7 +12,7 @@ import type {
  * @param props - The props for the block component.
  * @param props.attributes - Block attributes.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreHeading: CoreHeadingType = ( { attributes }: CoreHeadingProps ) => {
 	const { style, cssClassName, content, level } = attributes || {};

packages/blocks/src/blocks/core-html.tsx

@@ -7,7 +7,7 @@ import type { CoreHtml as CoreHtmlType, CoreHtmlProps } from '@snapwp/types';
  * @param props - The props for the block component.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element|null} The rendered block.
  */
 const CoreHtml: CoreHtmlType = ( { renderedHtml }: CoreHtmlProps ) => {
 	// @todo use attributes.content instead of renderedHtml once it's available

packages/blocks/src/blocks/core-image.tsx

@@ -28,7 +28,7 @@ import type {
  * @param [props.rel] - The rel for the link.
  * @param [props.lightbox] - The lightbox attribute.
  *
- * @return The rendered figure element.
+ * @return {React.JSX.Element} The rendered figure element.
  */
 const Figure = ( {
 	children,
@@ -39,7 +39,7 @@ const Figure = ( {
 	linkTarget,
 	rel,
 	lightbox,
-}: FigureProps ) => {
+}: FigureProps ): React.JSX.Element => {
 	let props: ComponentProps< 'figure' > = {};
 
 	if ( isLightboxEnabled( lightbox ) ) {
@@ -77,7 +77,8 @@ const Figure = ( {
  * @param [props.connectedMediaItem] - The connected media item.
  * @param [props.mediaDetails] - The media details.
  * @param [props.renderedHtml] - The rendered HTML.
- * @return The rendered core image block or null if no URL is provided.
+ *
+ * @return {React.JSX.Element|null} The rendered core image block or null if no URL is provided.
  */
 const CoreImage: CoreImageType = ( {
 	attributes,
@@ -170,7 +171,7 @@ const CoreImage: CoreImageType = ( {
  * @param [connectedMediaItem] The connected media item.
  * @param [mediaDetails] The media details.
  *
- * @return The props for the image component.
+ * @return {Object} The props for the image component.
  */
 const getImageProps = (
 	attributes?: CoreImageAttributes,
@@ -244,10 +245,10 @@ const getImageProps = (
  *
  * @param lightbox - The lightbox attribute.
  *
- * @return Whether the lightbox is enabled.
+ * @return {boolean} Whether the lightbox is enabled.
  */
 //@ts-ignore -- Stubbed until lightbox support is fixed.
-const isLightboxEnabled = ( lightbox?: string | null ) => {
+const isLightboxEnabled = ( lightbox?: string | null ): boolean => {
 	// if ( ! lightbox ) {
 	// 	return false;
 	// }
@@ -265,12 +266,12 @@ const isLightboxEnabled = ( lightbox?: string | null ) => {
  * @param element - The element to extract attributes for.
  * @param renderedHtml - The rendered HTML.
  *
- * @return The extracted interactivity attributes.
+ * @return {Object} The extracted interactivity attributes.
  */
 const extractInteractivityAttributesForElement = (
 	element: string,
 	renderedHtml?: string | null
-) => {
+): Record< string, string > => {
 	if ( ! renderedHtml ) {
 		return {};
 	}
@@ -305,12 +306,12 @@ const extractInteractivityAttributesForElement = (
  * @param element - The element to extract attributes for.
  * @param renderedHtml - The rendered HTML.
  *
- * @return The extracted ARIA attributes.
+ * @return {Object} The extracted ARIA attributes.
  */
 const extractAriaAttributesForElement = (
 	element: string,
 	renderedHtml?: string | null
-) => {
+): Record< string, string > => {
 	if ( ! renderedHtml ) {
 		return {};
 	}

packages/blocks/src/blocks/core-list-item.tsx

@@ -17,7 +17,7 @@ import type {
  * @param props.children - The block's children.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreListItem: CoreListItemType = ( {
 	attributes,

packages/blocks/src/blocks/core-list.tsx

@@ -8,7 +8,7 @@ import type { CoreList as CoreListType, CoreListProps } from '@snapwp/types';
  * @param props.attributes - Block attributes.
  * @param props.children - The block's children.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreList: CoreListType = ( { attributes, children }: CoreListProps ) => {
 	const { cssClassName, ordered, reversed, start, style, type } =

packages/blocks/src/blocks/core-media-text.tsx

@@ -28,9 +28,13 @@ const DEFAULT_MEDIA_SIZE_SLUG = 'full';
  * @param focalPoint - The focal point of the image.
  * @param focalPoint.x - The x-coordinate of the focal point (0 to 1).
  * @param focalPoint.y - The y-coordinate of the focal point (0 to 1).
- * @return CSS styles for the image fill.
+ *
+ * @return {Object} CSS styles for the image fill.
  */
-function imageFillStyles( url?: string, focalPoint?: FocalPoint ) {
+function imageFillStyles(
+	url?: string,
+	focalPoint?: FocalPoint
+): { objectPosition: string } | { objectPosition?: undefined } {
 	return url
 		? {
 				objectPosition: focalPoint
@@ -51,7 +55,8 @@ function imageFillStyles( url?: string, focalPoint?: FocalPoint ) {
  * @param props.renderedHtml - Raw HTML string from WordPress
  * @param props.connectedMediaItem - Connected media item
  * @param props.mediaDetails - Media details
- * @return Rendered component or null if no content
+ *
+ * @return {React.JSX.Element} Rendered component or null if no content
  */
 const CoreMediaText: CoreMediaTextType = ( {
 	attributes = {},

packages/blocks/src/blocks/core-paragraph.tsx

@@ -11,7 +11,7 @@ import type {
  * @param props - The props for the block component.
  * @param props.attributes - Block attributes.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreParagraph: CoreParagraphType = ( {
 	attributes,

packages/blocks/src/blocks/core-pattern.tsx

@@ -9,7 +9,7 @@ import type {
  * @param props - The props for the block component.
  * @param props.children - The block's children.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CorePattern: CorePatternType = ( { children }: CorePatternProps ) => {
 	// Patterns contain only children, so we just return them.

packages/blocks/src/blocks/core-post-content.tsx

@@ -11,7 +11,7 @@ import type {
  * @param props.children - The block's children.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CorePostContent: CorePostContentType = ( {
 	renderedHtml,

packages/blocks/src/blocks/core-preformatted.tsx

@@ -16,7 +16,7 @@ import type {
  * @param props.attributes - Block attributes.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CorePreformatted: CorePreformattedType = ( {
 	attributes,

packages/blocks/src/blocks/core-pullquote.tsx

@@ -16,7 +16,7 @@ import type {
  * @param props.attributes - Block attributes.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CorePullquote: CorePullquoteType = ( {
 	attributes,

packages/blocks/src/blocks/core-quote.tsx

@@ -9,7 +9,7 @@ import type { CoreQuote as CoreQuoteType, CoreQuoteProps } from '@snapwp/types';
  * @param props.attributes - Block attributes.
  * @param props.children - The block's children.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreQuote: CoreQuoteType = ( {
 	attributes,

packages/blocks/src/blocks/core-separator.tsx

@@ -10,7 +10,7 @@ import type {
  * @param props - The props for the block component.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreSeparator: CoreSeparatorType = ( {
 	renderedHtml,

packages/blocks/src/blocks/core-spacer.tsx

@@ -16,7 +16,7 @@ import type {
  * @param props.attributes - Block attributes.
  * @param props.renderedHtml - The block's rendered HTML.
  *
- * @return The rendered block.
+ * @return {React.JSX.Element} The rendered block.
  */
 const CoreSpacer: CoreSpacerType = ( {
 	attributes,