chore: Add jsdoc/require-param-type eslint rule

.changeset/wet-geckos-check.md

@@ -0,0 +1,9 @@
+---
+"@snapwp/e2e-tests": patch
+"@snapwp/blocks": patch
+"@snapwp/query": patch
+"@snapwp/core": patch
+"@snapwp/next": patch
+---
+
+lint: Enforced parameter type in function documentation by adding the `jsdoc/require-param-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-param-type': [ 'error' ],
 		'jsdoc/require-returns': [ 'warn' ],
 
 		// Restrict the use of empty functions.

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

@@ -12,7 +12,8 @@ export default class BlockManager {
 
 	/**
 	 * Update block definitions to be used while rendering blocks.
-	 * @param blockDefinitions - rendering implementaion for blocks.
+	 *
+	 * @param {BlockDefinitions} blockDefinitions Rendering implementation for blocks.
 	 */
 	public static addBlockDefinitions(
 		blockDefinitions: BlockDefinitions
@@ -24,8 +25,9 @@ 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.
+	 * Function to convert a flat list of blocks to a tree depending on `clientId` and `parentClientId`.
+	 *
+	 * @param {Array<BlockData>} blockList A flat list of blocks.
 	 *
 	 * @return A tree of blocks.
 	 */
@@ -49,7 +51,8 @@ export default class BlockManager {
 	/**
 	 * Mutates the passed the node by adding a render function to a node of block tree.
 	 * if a node uses default renderer(which uses renderedHtml) prunes its children which does not need to be rendered.
-	 * @param node - A flat list of blocks.
+	 *
+	 * @param {BlockTreeNode} node A flat list of blocks.
 	 */
 	public static attachRendererToTreeNode = ( node: BlockTreeNode ): void => {
 		const customBlockDefinition =
@@ -78,7 +81,8 @@ export default class BlockManager {
 
 	/**
 	 * Pre processes a flat list of blocks for rendering.
-	 * @param blockList - A flat list of blocks.
+	 *
+	 * @param {Array<BlockData>} blockList A flat list of blocks.
 	 *
 	 * @return A tree of blocks with render functions.
 	 */

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

@@ -9,9 +9,9 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/audio block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                         props              The props for the block component.
+ * @param {CoreAudioProps['attributes']}   props.attributes   Block attributes.
+ * @param {CoreAudioProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -9,8 +9,8 @@ import type { ButtonHTMLAttributes, ReactNode } from 'react';
 /**
  * Renders the core/button block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
+ * @param {Object}                        props            The props for the block component.
+ * @param {CoreButtonProps['attributes']} props.attributes Block attributes.
  *
  * @return The rendered block.
  */

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

@@ -8,9 +8,9 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/buttons block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                         props            The props for the block component.
+ * @param {CoreButtonsProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                      props.children   The block's children.
  *
  * @return The rendered block.
  */

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

@@ -6,8 +6,8 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/code block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
+ * @param {Object}                      props            The props for the block component.
+ * @param {CoreCodeProps['attributes']} props.attributes Block attributes.
  *
  * @return The rendered block.
  */

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

@@ -8,9 +8,9 @@ import type { CSSProperties, ReactNode } from 'react';
 /**
  * Renders the core/column block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                        props            The props for the block component.
+ * @param {CoreColumnProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                     props.children   The block's children.
  *
  * @return The rendered block.
  */

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

@@ -8,9 +8,9 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/columns block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                         props            The props for the block component.
+ * @param {CoreColumnsProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                      props.children   The block's children.
  *
  * @return The rendered block.
  */

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

@@ -21,7 +21,7 @@ const DEFAULT_FOCAL_POINT = { x: 0.5, y: 0.5 };
  *
  * @see https://github.com/WordPress/gutenberg/blob/887243c1cb2b3280934fbff05d4af8e46a3feddc/packages/block-library/src/cover/shared.js#L27
  *
- * @param focalPoint - The focal point coordinates object containing x and y values.
+ * @param {FocalPoint} focalPoint The focal point coordinates object containing x and y values.
  *
  * @return CSS position string or undefined if no focal point
  */
@@ -38,12 +38,13 @@ const mediaPosition = (
 
 /**
  * Renders the core/cover block.
- * @param root0 - The component props object
- * @param root0.attributes - Block attributes including styling and media settings
- * @param root0.children - Child elements to render inside the cover
- * @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
+ *
+ * @param {Object}                               props                    The component props object
+ * @param {CoreCoverProps['attributes']}         props.attributes         Block attributes including styling and media settings
+ * @param {ReactNode}                            props.children           Child elements to render inside the cover
+ * @param {CoreCoverProps['renderedHtml']}       props.renderedHtml       Pre-rendered HTML string for class extraction
+ * @param {CoreCoverProps['connectedMediaItem']} props.connectedMediaItem The connected media item object
+ * @param {CoreCoverProps['mediaDetails']}       props.mediaDetails       The media details object
  *
  * @return The rendered cover block or null if using featured image
  */

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

@@ -12,10 +12,10 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/details block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                           props              The props for the block component.
+ * @param {CoreDetailsProps['attributes']}   props.attributes   Block attributes.
+ * @param {ReactNode}                        props.children     The block's children.
+ * @param {CoreDetailsProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -13,9 +13,9 @@ const FALLBACK_ARIA_LABEL = 'PDF embed';
 /**
  * Renders the core/file block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                        props              The props for the block component.
+ * @param {CoreFileProps['attributes']}   props.attributes   Block attributes.
+ * @param {CoreFileProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -8,8 +8,8 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/freeform block.
  *
- * @param props - The props for the block component.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                            props              The props for the block component.
+ * @param {CoreFreeformProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -12,10 +12,10 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/gallery block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                           props              The props for the block component.
+ * @param {CoreGalleryProps['attributes']}   props.attributes   Block attributes.
+ * @param {ReactNode}                        props.children     The block's children.
+ * @param {CoreGalleryProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -14,11 +14,11 @@ import type { CoreGroup as CoreGroupType, CoreGroupProps } from '@snapwp/types';
 /**
  * Renders an HTML element with the specified tag name.
  *
- * @param props - The props for the block component.
- * @param props.name - The tag name of the HTML element.
- * @param props.className - Class names.
- * @param props.style - Inline styles.
- * @param props.children - The content to render inside the element.
+ * @param {Object}                props           The props for the block component.
+ * @param {TagProps['name']}      props.name      The tag name of the HTML element.
+ * @param {TagProps['className']} props.className Class names.
+ * @param {TagProps['style']}     props.style     Inline styles.
+ * @param {ReactNode}             props.children  The content to render inside the element.
  *
  * @return The rendered HTML element or the children if no tag name is provided.
  */
@@ -42,10 +42,10 @@ const Tag = ( {
 /**
  * Renders the core/group block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                         props              The props for the block component.
+ * @param {CoreGroupProps['attributes']}   props.attributes   Block attributes.
+ * @param {ReactNode}                      props.children     The block's children.
+ * @param {CoreGroupProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -9,8 +9,8 @@ import type {
 /**
  * Renders the core/heading block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
+ * @param {Object}                         props            The props for the block component.
+ * @param {CoreHeadingProps['attributes']} props.attributes Block attributes.
  *
  * @return The rendered block.
  */

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

@@ -5,8 +5,8 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/html block.
  *
- * @param props - The props for the block component.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                        props              The props for the block component.
+ * @param {CoreHtmlProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -18,15 +18,15 @@ import type {
 /**
  * Renders a figure element with optional link and caption.
  *
- * @param props - The properties for the figure element.
- * @param [props.children] - The children of the figure element.
- * @param [props.classNames] - The class names for the figure element.
- * @param [props.renderedHtml] - The rendered HTML.
- * @param [props.href] - The href for the link.
- * @param [props.linkClass] - The class for the link.
- * @param [props.linkTarget] - The target for the link.
- * @param [props.rel] - The rel for the link.
- * @param [props.lightbox] - The lightbox attribute.
+ * @param {Object}                      props              The properties for the figure element.
+ * @param {ReactNode}                   props.children     The children of the figure element.
+ * @param {FigureProps['classNames']}   props.classNames   The class names for the figure element.
+ * @param {FigureProps['renderedHtml']} props.renderedHtml The rendered HTML.
+ * @param {FigureProps['href']}         props.href         The href for the link.
+ * @param {FigureProps['linkClass']}    props.linkClass    The class for the link.
+ * @param {FigureProps['linkTarget']}   props.linkTarget   The target for the link.
+ * @param {FigureProps['rel']}          props.rel          The rel for the link.
+ * @param {FigureProps['lightbox']}     props.lightbox     The lightbox attribute.
  *
  * @return The rendered figure element.
  */
@@ -72,11 +72,11 @@ const Figure = ( {
  *
  * @todo Expose context and state to frontend for lightbox functionality.
  *
- * @param props - The properties for the core image block.
- * @param [props.attributes] - The attributes for the image.
- * @param [props.connectedMediaItem] - The connected media item.
- * @param [props.mediaDetails] - The media details.
- * @param [props.renderedHtml] - The rendered HTML.
+ * @param {Object}                               props                    The properties for the core image block.
+ * @param {CoreImageProps['attributes']}         props.attributes         The attributes for the image.
+ * @param {CoreImageProps['connectedMediaItem']} props.connectedMediaItem The connected media item.
+ * @param {CoreImageProps['mediaDetails']}       props.mediaDetails       The media details.
+ * @param {CoreImageProps['renderedHtml']}       props.renderedHtml       The rendered HTML.
  *
  * @return The rendered core image block or null if no URL is provided.
  */
@@ -167,9 +167,9 @@ const CoreImage: CoreImageType = ( {
 /**
  * Returns the props for the image component.
  *
- * @param [attributes] The attributes for the image.
- * @param [connectedMediaItem] The connected media item.
- * @param [mediaDetails] The media details.
+ * @param {CoreImageAttributes}         attributes         The attributes for the image.
+ * @param {CoreImageConnectedMediaItem} connectedMediaItem The connected media item.
+ * @param {CoreImageMediaDetails}       mediaDetails       The media details.
  *
  * @return The props for the image component.
  */
@@ -243,7 +243,7 @@ const getImageProps = (
 /**
  * Is Lightbox enabled for the image.
  *
- * @param lightbox - The lightbox attribute.
+ * @param {string} lightbox The lightbox attribute.
  *
  * @return Whether the lightbox is enabled.
  */
@@ -263,8 +263,8 @@ const isLightboxEnabled = ( lightbox?: string | null ): boolean => {
 /**
  * Extracts interactivity attributes from the rendered HTML for a given element.
  *
- * @param element - The element to extract attributes for.
- * @param renderedHtml - The rendered HTML.
+ * @param {string} element      The element to extract attributes for.
+ * @param {string} renderedHtml The rendered HTML.
  *
  * @return The extracted interactivity attributes.
  */
@@ -303,8 +303,8 @@ const extractInteractivityAttributesForElement = (
 /**
  * Extracts ARIA attributes from the rendered HTML for a given element.
  *
- * @param element - The element to extract attributes for.
- * @param renderedHtml - The rendered HTML.
+ * @param {string} element      The element to extract attributes for.
+ * @param {string} renderedHtml The rendered HTML.
  *
  * @return The extracted ARIA attributes.
  */

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

@@ -13,10 +13,10 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/list-item block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                             props              The props for the block component.
+ * @param {CoreListItemProps['attributes']}    props.attributes   Block attributes.
+ * @param {ReactNode}                          props.children     The block's children.
+ * @param {CoreListItemProps['renderedHtml']}  props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

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

@@ -5,9 +5,9 @@ import type { CSSProperties, ReactNode } from 'react';
 /**
  * Renders the core/list block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                      props            The props for the block component.
+ * @param {CoreListProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                   props.children   The block's children.
  *
  * @return The rendered block.
  */