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

.changeset/polite-turkeys-check.md

@@ -0,0 +1,10 @@
+---
+"@snapwp/e2e-tests": patch
+"@snapwp/blocks": patch
+"@snapwp/query": patch
+"@snapwp/types": patch
+"@snapwp/core": patch
+"@snapwp/next": patch
+---
+
+chore: Add and enforce explicit return types on method signatures.

.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,6 +26,7 @@ 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.
 	 */
 	public static flatListToHierarchical(
@@ -76,6 +79,7 @@ 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.
 	 */
 	public static parseBlockForRendering(

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

@@ -4,6 +4,7 @@ import {
 	getStylesFromAttributes,
 } from '@snapwp/core';
 import type { CoreAudio as CoreAudioType, CoreAudioProps } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/audio block.
@@ -17,7 +18,7 @@ import type { CoreAudio as CoreAudioType, CoreAudioProps } from '@snapwp/types';
 const CoreAudio: CoreAudioType = ( {
 	attributes,
 	renderedHtml,
-}: CoreAudioProps ) => {
+}: CoreAudioProps ): ReactNode => {
 	const { autoplay, caption, loop, preload, src, style } = attributes || {};
 
 	if ( ! src ) {

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

@@ -4,7 +4,7 @@ import type {
 	CoreButton as CoreButtonType,
 	CoreButtonProps,
 } from '@snapwp/types';
-import type { ButtonHTMLAttributes } from 'react';
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
 /**
  * Renders the core/button block.
@@ -14,7 +14,9 @@ import type { ButtonHTMLAttributes } from 'react';
  *
  * @return The rendered block.
  */
-const CoreButton: CoreButtonType = ( { attributes }: CoreButtonProps ) => {
+const CoreButton: CoreButtonType = ( {
+	attributes,
+}: CoreButtonProps ): ReactNode => {
 	const {
 		buttonType,
 		cssClassName,

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

@@ -3,6 +3,7 @@ import type {
 	CoreButtons as CoreButtonsType,
 	CoreButtonsProps,
 } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/buttons block.
@@ -16,7 +17,7 @@ import type {
 const CoreButtons: CoreButtonsType = ( {
 	attributes,
 	children,
-}: CoreButtonsProps ) => {
+}: CoreButtonsProps ): ReactNode => {
 	const { cssClassName, style } = attributes || {};
 	const classNames = cn( cssClassName );
 

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

@@ -1,6 +1,7 @@
 import { getStylesFromAttributes } from '@snapwp/core';
 import { Parse } from '@snapwp/next';
 import type { CoreCode as CoreCodeType, CoreCodeProps } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/code block.
@@ -10,7 +11,7 @@ import type { CoreCode as CoreCodeType, CoreCodeProps } from '@snapwp/types';
  *
  * @return The rendered block.
  */
-const CoreCode: CoreCodeType = ( { attributes }: CoreCodeProps ) => {
+const CoreCode: CoreCodeType = ( { attributes }: CoreCodeProps ): ReactNode => {
 	const { style, cssClassName, content } = attributes || {};
 
 	const styleObject = getStylesFromAttributes( { style } );

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

@@ -3,7 +3,7 @@ import type {
 	CoreColumn as CoreColumnType,
 	CoreColumnProps,
 } from '@snapwp/types';
-import type { CSSProperties } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
 /**
  * Renders the core/column block.
@@ -17,7 +17,7 @@ import type { CSSProperties } from 'react';
 const CoreColumn: CoreColumnType = ( {
 	attributes,
 	children,
-}: CoreColumnProps ) => {
+}: CoreColumnProps ): ReactNode => {
 	const { cssClassName, style, width } = attributes || {};
 
 	const classNames = cn( cssClassName );

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

@@ -3,6 +3,7 @@ import type {
 	CoreColumns as CoreColumnsType,
 	CoreColumnsProps,
 } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/columns block.
@@ -16,7 +17,7 @@ import type {
 const CoreColumns: CoreColumnsType = ( {
 	attributes,
 	children,
-}: CoreColumnsProps ) => {
+}: CoreColumnsProps ): ReactNode => {
 	const { cssClassName, style } = attributes || {};
 
 	const styleObject = getStylesFromAttributes( { style } );

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

@@ -1,4 +1,4 @@
-import type { ComponentProps } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 import {
 	getStylesFromAttributes,
 	findElementAndGetClassNames,
@@ -44,6 +44,7 @@ const mediaPosition = (
  * @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
  */
 const CoreCover: CoreCoverType = ( {
@@ -52,7 +53,7 @@ const CoreCover: CoreCoverType = ( {
 	mediaDetails,
 	children,
 	renderedHtml,
-}: CoreCoverProps ) => {
+}: CoreCoverProps ): ReactNode => {
 	// Rest of the component implementation remains unchanged
 	const {
 		alt,

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

@@ -7,6 +7,7 @@ import type {
 	CoreDetails as CoreDetailsType,
 	CoreDetailsProps,
 } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/details block.
@@ -22,7 +23,7 @@ const CoreDetails: CoreDetailsType = ( {
 	attributes,
 	children,
 	renderedHtml,
-}: CoreDetailsProps ) => {
+}: CoreDetailsProps ): ReactNode => {
 	const { style, showContent, summary } = attributes ?? {};
 	const styleObject = getStylesFromAttributes( { style } );
 

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

@@ -5,6 +5,7 @@ import {
 } from '@snapwp/core';
 import { Link, Parse } from '@snapwp/next';
 import type { CoreFile as CoreFileType, CoreFileProps } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 const FALLBACK_DOWNLOAD_BUTTON_TEXT = 'Download';
 const FALLBACK_ARIA_LABEL = 'PDF embed';
@@ -21,7 +22,7 @@ const FALLBACK_ARIA_LABEL = 'PDF embed';
 const CoreFile: CoreFileType = ( {
 	attributes,
 	renderedHtml,
-}: CoreFileProps ) => {
+}: CoreFileProps ): ReactNode => {
 	const {
 		displayPreview,
 		downloadButtonText,

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

@@ -3,6 +3,7 @@ import type {
 	CoreFreeform as CoreFreeformType,
 	CoreFreeformProps,
 } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/freeform block.
@@ -14,7 +15,7 @@ import type {
  */
 const CoreFreeform: CoreFreeformType = ( {
 	renderedHtml,
-}: CoreFreeformProps ) => {
+}: CoreFreeformProps ): ReactNode => {
 	// @todo `attribues.content` is not populated in GraphQL. Using `renderedHtml` for now.
 	if ( ! renderedHtml ) {
 		return null;

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

@@ -7,6 +7,7 @@ import type {
 	CoreGallery as CoreGalleryType,
 	CoreGalleryProps,
 } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/gallery block.
@@ -22,7 +23,7 @@ const CoreGallery: CoreGalleryType = ( {
 	attributes,
 	children,
 	renderedHtml,
-}: CoreGalleryProps ) => {
+}: CoreGalleryProps ): ReactNode => {
 	const { caption, style } = attributes || {};
 
 	const styleObject = getStylesFromAttributes( { style } );

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

@@ -2,6 +2,7 @@ import {
 	createElement,
 	type CSSProperties,
 	type PropsWithChildren,
+	type ReactNode,
 } from 'react';
 import {
 	cn,
@@ -30,7 +31,7 @@ const Tag = ( {
 	name?: string;
 	className: string;
 	style?: CSSProperties;
-} > ) => {
+} > ): ReactNode => {
 	if ( ! name ) {
 		return <>{ children }</>;
 	}
@@ -52,7 +53,7 @@ const CoreGroup: CoreGroupType = ( {
 	attributes,
 	renderedHtml,
 	children,
-}: CoreGroupProps ) => {
+}: CoreGroupProps ): ReactNode => {
 	const { style, tagName } = attributes ?? {};
 
 	const styleObject = getStylesFromAttributes( { style } );

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

@@ -1,4 +1,4 @@
-import type { JSX } from 'react';
+import type { JSX, ReactNode } from 'react';
 import { getStylesFromAttributes } from '@snapwp/core';
 import { Parse } from '@snapwp/next';
 import type {
@@ -14,7 +14,9 @@ import type {
  *
  * @return The rendered block.
  */
-const CoreHeading: CoreHeadingType = ( { attributes }: CoreHeadingProps ) => {
+const CoreHeading: CoreHeadingType = ( {
+	attributes,
+}: CoreHeadingProps ): ReactNode => {
 	const { style, cssClassName, content, level } = attributes || {};
 
 	const styleObject = getStylesFromAttributes( { style } );

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

@@ -1,5 +1,6 @@
 import { Parse } from '@snapwp/next';
 import type { CoreHtml as CoreHtmlType, CoreHtmlProps } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/html block.
@@ -9,7 +10,9 @@ import type { CoreHtml as CoreHtmlType, CoreHtmlProps } from '@snapwp/types';
  *
  * @return The rendered block.
  */
-const CoreHtml: CoreHtmlType = ( { renderedHtml }: CoreHtmlProps ) => {
+const CoreHtml: CoreHtmlType = ( {
+	renderedHtml,
+}: CoreHtmlProps ): ReactNode => {
 	// @todo use attributes.content instead of renderedHtml once it's available
 	if ( ! renderedHtml ) {
 		return null;

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

@@ -1,5 +1,5 @@
 import { decode } from 'html-entities';
-import type { ComponentProps, CSSProperties } from 'react';
+import type { ComponentProps, CSSProperties, ReactNode } from 'react';
 import {
 	cn,
 	getClassNamesFromString,
@@ -39,7 +39,7 @@ const Figure = ( {
 	linkTarget,
 	rel,
 	lightbox,
-}: FigureProps ) => {
+}: FigureProps ): ReactNode => {
 	let props: ComponentProps< 'figure' > = {};
 
 	if ( isLightboxEnabled( lightbox ) ) {
@@ -77,14 +77,15 @@ 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.
  */
 const CoreImage: CoreImageType = ( {
 	attributes,
 	connectedMediaItem,
 	mediaDetails,
 	renderedHtml,
-}: CoreImageProps ) => {
+}: CoreImageProps ): ReactNode => {
 	// @todo: fetchPriority is missing
 	const { caption, url, lightbox } = attributes || {};
 
@@ -247,7 +248,7 @@ const getImageProps = (
  * @return 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;
 	// }
@@ -270,7 +271,7 @@ const isLightboxEnabled = ( lightbox?: string | null ) => {
 const extractInteractivityAttributesForElement = (
 	element: string,
 	renderedHtml?: string | null | undefined
-) => {
+): Record< string, string > => {
 	if ( ! renderedHtml ) {
 		return {};
 	}
@@ -310,7 +311,7 @@ const extractInteractivityAttributesForElement = (
 const extractAriaAttributesForElement = (
 	element: string,
 	renderedHtml?: string | null
-) => {
+): Record< string, string > => {
 	if ( ! renderedHtml ) {
 		return {};
 	}

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

@@ -8,6 +8,7 @@ import type {
 	CoreListItem as CoreListItemType,
 	CoreListItemProps,
 } from '@snapwp/types';
+import type { ReactNode } from 'react';
 
 /**
  * Renders the core/list-item block.
@@ -23,7 +24,7 @@ const CoreListItem: CoreListItemType = ( {
 	attributes,
 	renderedHtml,
 	children,
-}: CoreListItemProps ) => {
+}: CoreListItemProps ): ReactNode => {
 	const { content, style } = attributes || {};
 
 	const styleObject = getStylesFromAttributes( { style } );