diff --git a/.changeset/wet-geckos-check.md b/.changeset/wet-geckos-check.md new file mode 100644 index 00000000..89c27bc8 --- /dev/null +++ b/.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 +--- + +chore: Enforce `jsdoc/require-param-type` ESLint rule in repository ruleset. diff --git a/.eslintrc.cjs b/.eslintrc.cjs index 9565719c..2939836b 100644 --- a/.eslintrc.cjs +++ b/.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. diff --git a/packages/blocks/src/block-manager/index.tsx b/packages/blocks/src/block-manager/index.tsx index c73fff0c..0da8fb17 100644 --- a/packages/blocks/src/block-manager/index.tsx +++ b/packages/blocks/src/block-manager/index.tsx @@ -13,7 +13,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 @@ -25,8 +26,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} blockList A flat list of blocks. * * @return A tree of blocks. */ @@ -50,7 +52,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 = @@ -79,7 +82,8 @@ export default class BlockManager { /** * Pre processes a flat list of blocks for rendering. - * @param blockList - A flat list of blocks. + * + * @param {Array} blockList A flat list of blocks. * * @return A tree of blocks with render functions. */ diff --git a/packages/blocks/src/blocks/core-audio.tsx b/packages/blocks/src/blocks/core-audio.tsx index b4c22f7f..67c3b405 100644 --- a/packages/blocks/src/blocks/core-audio.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-button.tsx b/packages/blocks/src/blocks/core-button.tsx index aad3ea4a..2ca50e4e 100644 --- a/packages/blocks/src/blocks/core-button.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-buttons.tsx b/packages/blocks/src/blocks/core-buttons.tsx index 34d004dd..1e3be2d4 100644 --- a/packages/blocks/src/blocks/core-buttons.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-code.tsx b/packages/blocks/src/blocks/core-code.tsx index 17b168d4..8f2c39b4 100644 --- a/packages/blocks/src/blocks/core-code.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-column.tsx b/packages/blocks/src/blocks/core-column.tsx index b8b9a66f..095cfb71 100644 --- a/packages/blocks/src/blocks/core-column.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-columns.tsx b/packages/blocks/src/blocks/core-columns.tsx index e27ec0f8..553152b4 100644 --- a/packages/blocks/src/blocks/core-columns.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-cover.tsx b/packages/blocks/src/blocks/core-cover.tsx index be3f8733..4db66daf 100644 --- a/packages/blocks/src/blocks/core-cover.tsx +++ b/packages/blocks/src/blocks/core-cover.tsx @@ -22,7 +22,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 */ @@ -39,12 +39,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 */ diff --git a/packages/blocks/src/blocks/core-details.tsx b/packages/blocks/src/blocks/core-details.tsx index e9be0611..62d263a1 100644 --- a/packages/blocks/src/blocks/core-details.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-file.tsx b/packages/blocks/src/blocks/core-file.tsx index 86ff630c..19288557 100644 --- a/packages/blocks/src/blocks/core-file.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-freeform.tsx b/packages/blocks/src/blocks/core-freeform.tsx index 72ff3aef..117379d1 100644 --- a/packages/blocks/src/blocks/core-freeform.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-gallery.tsx b/packages/blocks/src/blocks/core-gallery.tsx index b886e7cc..765a35a2 100644 --- a/packages/blocks/src/blocks/core-gallery.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-group.tsx b/packages/blocks/src/blocks/core-group.tsx index 75cb5e08..e1080c1a 100644 --- a/packages/blocks/src/blocks/core-group.tsx +++ b/packages/blocks/src/blocks/core-group.tsx @@ -15,11 +15,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. */ @@ -43,10 +43,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. */ diff --git a/packages/blocks/src/blocks/core-heading.tsx b/packages/blocks/src/blocks/core-heading.tsx index 197d71f3..04275e64 100644 --- a/packages/blocks/src/blocks/core-heading.tsx +++ b/packages/blocks/src/blocks/core-heading.tsx @@ -9,8 +9,8 @@ import type { JSX, ReactNode } from 'react'; /** * 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. */ diff --git a/packages/blocks/src/blocks/core-html.tsx b/packages/blocks/src/blocks/core-html.tsx index b2751612..43606df3 100644 --- a/packages/blocks/src/blocks/core-html.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-image.tsx b/packages/blocks/src/blocks/core-image.tsx index 6c911782..3f7dc5ef 100644 --- a/packages/blocks/src/blocks/core-image.tsx +++ b/packages/blocks/src/blocks/core-image.tsx @@ -19,15 +19,15 @@ import type { ComponentProps, CSSProperties, ReactNode } from 'react'; /** * 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. */ @@ -73,11 +73,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. */ @@ -168,9 +168,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. */ @@ -244,7 +244,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. */ @@ -264,8 +264,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. */ @@ -304,8 +304,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. */ diff --git a/packages/blocks/src/blocks/core-list-item.tsx b/packages/blocks/src/blocks/core-list-item.tsx index 7d562f6c..2857f112 100644 --- a/packages/blocks/src/blocks/core-list-item.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-list.tsx b/packages/blocks/src/blocks/core-list.tsx index 0fd5ce25..55aa646c 100644 --- a/packages/blocks/src/blocks/core-list.tsx +++ b/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. */ diff --git a/packages/blocks/src/blocks/core-media-text.tsx b/packages/blocks/src/blocks/core-media-text.tsx index bf378a72..87d553c7 100644 --- a/packages/blocks/src/blocks/core-media-text.tsx +++ b/packages/blocks/src/blocks/core-media-text.tsx @@ -24,10 +24,10 @@ const DEFAULT_MEDIA_SIZE_SLUG = 'full'; /** * Generates CSS styles for image fill based on the provided URL and focal point. * - * @param url - The URL of the image. - * @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). + * @param {string} url The URL of the image. + * @param {FocalPoint} focalPoint The focal point of the image. + * @param {FocalPoint['x']} focalPoint.x The x-coordinate of the focal point (0 to 1). + * @param {FocalPoint['y']} focalPoint.y The y-coordinate of the focal point (0 to 1). * * @return CSS styles for the image fill. */ @@ -49,12 +49,12 @@ function imageFillStyles( /** * Renders a WordPress Media & Text block with support for images, videos, and linked media * - * @param props - Component props - * @param props.attributes - Block configuration attributes - * @param props.children - Child components to render - * @param props.renderedHtml - Raw HTML string from WordPress - * @param props.connectedMediaItem - Connected media item - * @param props.mediaDetails - Media details + * @param {Object} props Component props + * @param {CoreMediaTextProps['attributes']} props.attributes Block configuration attributes + * @param {ReactNode} props.children Child components to render + * @param {CoreMediaTextProps['renderedHtml']} props.renderedHtml Raw HTML string from WordPress + * @param {CoreMediaTextProps['connectedMediaItem']} props.connectedMediaItem Connected media item + * @param {CoreMediaTextProps['mediaDetails']} props.mediaDetails Media details * * @return Rendered component or null if no content */ diff --git a/packages/blocks/src/blocks/core-paragraph.tsx b/packages/blocks/src/blocks/core-paragraph.tsx index 9d9ed778..4a5915b3 100644 --- a/packages/blocks/src/blocks/core-paragraph.tsx +++ b/packages/blocks/src/blocks/core-paragraph.tsx @@ -9,8 +9,8 @@ import type { ReactNode } from 'react'; /** * Renders the core/paragraph block. * - * @param props - The props for the block component. - * @param props.attributes - Block attributes. + * @param {Object} props The props for the block component. + * @param {CoreParagraphProps['attributes']} props.attributes Block attributes. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-pattern.tsx b/packages/blocks/src/blocks/core-pattern.tsx index 1c040826..1c8650b1 100644 --- a/packages/blocks/src/blocks/core-pattern.tsx +++ b/packages/blocks/src/blocks/core-pattern.tsx @@ -7,8 +7,8 @@ import type { ReactNode } from 'react'; /** * Renders the core/pattern block. * - * @param props - The props for the block component. - * @param props.children - The block's children. + * @param {Object} props The props for the block component. + * @param {ReactNode} props.children The block's children. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-post-content.tsx b/packages/blocks/src/blocks/core-post-content.tsx index bf36c805..0f0f59e6 100644 --- a/packages/blocks/src/blocks/core-post-content.tsx +++ b/packages/blocks/src/blocks/core-post-content.tsx @@ -8,9 +8,9 @@ import type { ReactNode } from 'react'; /** * Renders the core/post-content block. * - * @param props - The props for the block component. - * @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 {ReactNode} props.children The block's children. + * @param {CorePostContentProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-preformatted.tsx b/packages/blocks/src/blocks/core-preformatted.tsx index 1ad71f80..87b854c9 100644 --- a/packages/blocks/src/blocks/core-preformatted.tsx +++ b/packages/blocks/src/blocks/core-preformatted.tsx @@ -13,9 +13,9 @@ import type { ReactNode } from 'react'; /** * Renders the core/preformatted 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 {CorePreformattedProps['attributes']} props.attributes Block attributes. + * @param {CorePreformattedProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-pullquote.tsx b/packages/blocks/src/blocks/core-pullquote.tsx index 4985c902..d8f47e72 100644 --- a/packages/blocks/src/blocks/core-pullquote.tsx +++ b/packages/blocks/src/blocks/core-pullquote.tsx @@ -13,9 +13,9 @@ import type { ReactNode } from 'react'; /** * Renders the core/pullquote 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 {CorePullquoteProps['attributes']} props.attributes Block attributes. + * @param {CorePullquoteProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-quote.tsx b/packages/blocks/src/blocks/core-quote.tsx index a669e549..a029c2ca 100644 --- a/packages/blocks/src/blocks/core-quote.tsx +++ b/packages/blocks/src/blocks/core-quote.tsx @@ -6,9 +6,9 @@ import type { ReactNode } from 'react'; /** * Renders the core/quote 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 {CoreQuoteProps['attributes']} props.attributes Block attributes. + * @param {ReactNode} props.children The block's children. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-separator.tsx b/packages/blocks/src/blocks/core-separator.tsx index 25e7497d..1ea3a25a 100644 --- a/packages/blocks/src/blocks/core-separator.tsx +++ b/packages/blocks/src/blocks/core-separator.tsx @@ -8,8 +8,8 @@ import type { ReactNode } from 'react'; /** * Renders the core/separator 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 {CoreSeparatorProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-spacer.tsx b/packages/blocks/src/blocks/core-spacer.tsx index 06e3cd75..83727047 100644 --- a/packages/blocks/src/blocks/core-spacer.tsx +++ b/packages/blocks/src/blocks/core-spacer.tsx @@ -13,9 +13,9 @@ import type { ReactNode } from 'react'; /** * Renders the core/spacer 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 {CoreSpacerProps['attributes']} props.attributes Block attributes. + * @param {CoreSpacerProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-template-part.tsx b/packages/blocks/src/blocks/core-template-part.tsx index 12284aa5..42cf2c53 100644 --- a/packages/blocks/src/blocks/core-template-part.tsx +++ b/packages/blocks/src/blocks/core-template-part.tsx @@ -8,10 +8,10 @@ import type { JSX, ReactNode } from 'react'; /** * Renders the core/template-part 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 {CoreTemplatePartProps['attributes']} props.attributes Block attributes. + * @param {ReactNode} props.children The block's children. + * @param {CoreTemplatePartProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-verse.tsx b/packages/blocks/src/blocks/core-verse.tsx index 50decfbe..13750869 100644 --- a/packages/blocks/src/blocks/core-verse.tsx +++ b/packages/blocks/src/blocks/core-verse.tsx @@ -10,9 +10,9 @@ import type { ReactNode } from 'react'; /** * Renders the core/verse 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 {CoreVerseProps['attributes']} props.attributes Block attributes. + * @param {CoreVerseProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/core-video.tsx b/packages/blocks/src/blocks/core-video.tsx index 2e12ab9c..418c349b 100644 --- a/packages/blocks/src/blocks/core-video.tsx +++ b/packages/blocks/src/blocks/core-video.tsx @@ -14,8 +14,8 @@ import type { ReactNode } from 'react'; /** * Renders a list of `` elements for a video. * - * @param props - The props for the component. - * @param props.tracks - An array of track objects containing `src`, `kind`, `srclang`, and `label`. + * @param {Object} props The props for the component. + * @param {Array} props.tracks An array of track objects containing `src`, `kind`, `srclang`, and `label`. * * @return A list of `` elements or `null` if no tracks are provided. */ @@ -45,9 +45,9 @@ const Tracks = ( { /** * Renders the core/video 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 {CoreVideoProps['attributes']} props.attributes Block attributes. + * @param {CoreVideoProps['renderedHtml']} props.renderedHtml The block's rendered HTML. * * @return The rendered block. */ diff --git a/packages/blocks/src/blocks/default.tsx b/packages/blocks/src/blocks/default.tsx index ae8b59ce..84dfde63 100644 --- a/packages/blocks/src/blocks/default.tsx +++ b/packages/blocks/src/blocks/default.tsx @@ -4,8 +4,8 @@ import type { ReactNode } from 'react'; /** * Renders the default block. - * @param props - The props for the component. - * @param props.renderedHtml - The rendered HTML. + * @param {Object} props The props for the component. + * @param {DefaultProps['renderedHtml']} props.renderedHtml The rendered HTML. * * @return The rendered default block. */ diff --git a/packages/blocks/src/editor-blocks-renderer/index.tsx b/packages/blocks/src/editor-blocks-renderer/index.tsx index 9137e5b8..626f6aff 100644 --- a/packages/blocks/src/editor-blocks-renderer/index.tsx +++ b/packages/blocks/src/editor-blocks-renderer/index.tsx @@ -11,11 +11,12 @@ type EditorBlocksRendererProps = { /** * A react component to render editor blocks. - * @param props - Props. - * @param props.editorBlocks - A list of blocks to be rendered. - * @param props.blockDefinitions - Blocks rendering functions. * - * @return The rendered template. + * @param {Object} props Props. + * @param {EditorBlocksRendererProps['editorBlocks']} props.editorBlocks A list of blocks to be rendered. + * @param {EditorBlocksRendererProps['blockDefinitions']} props.blockDefinitions Blocks rendering functions. + * + * @return The rendered template */ export default function EditorBlocksRenderer( { editorBlocks, diff --git a/packages/blocks/src/utils/flat-list-to-hierarchical.ts b/packages/blocks/src/utils/flat-list-to-hierarchical.ts index 6a77c1f2..e0ecf656 100644 --- a/packages/blocks/src/utils/flat-list-to-hierarchical.ts +++ b/packages/blocks/src/utils/flat-list-to-hierarchical.ts @@ -9,13 +9,13 @@ type Data = Record< string | number, unknown >; /** * Converts a flat list to hierarchical. * - * @param data The data items as an array. - * @param options The data item property keys. - * @param options.idKey The key for the unique identifier. - * @param options.parentKey The key for the parent identifier. - * @param options.childrenKey The key for the children. + * @param {Array} data The data items as an array. + * @param {Options} options The data item property keys. + * @param {Options['idKey']} options.idKey The key for the unique identifier. + * @param {Options['parentKey']} options.parentKey The key for the parent identifier. + * @param {Options['childrenKey']} options.childrenKey The key for the children. * - * @return Data Array. + * @return Data Array */ export default function flatListToHierarchical( data: Data[] = [], diff --git a/packages/core/src/config/snapwp-config-manager.ts b/packages/core/src/config/snapwp-config-manager.ts index 2910d3bb..1dddd5b4 100644 --- a/packages/core/src/config/snapwp-config-manager.ts +++ b/packages/core/src/config/snapwp-config-manager.ts @@ -136,7 +136,8 @@ class SnapWPConfigManager { /** * Validate the URL. * - * @param value The value to validate. + * @param {string} value The value to validate. + * * @throws {Error} If the value is invalid. */ validate: ( value ) => { @@ -155,7 +156,8 @@ class SnapWPConfigManager { /** * Validate the URL. * - * @param value The value to validate. + * @param {string} value The value to validate. + * * @throws {Error} If the value is invalid. */ validate: ( value ) => { @@ -170,7 +172,7 @@ class SnapWPConfigManager { /** * Validate the URL. * - * @param value The value to validate. + * @param {string} value The value to validate. * @throws {Error} If the value is invalid. */ validate: ( value ) => { @@ -185,7 +187,7 @@ class SnapWPConfigManager { /** * Validate the REST URL prefix. * - * @param value The value to validate. + * @param {string} value The value to validate. * * @throws {Error} If the value is invalid. */ @@ -203,7 +205,7 @@ class SnapWPConfigManager { /** * Validate the uploads directory. * - * @param value The value to validate. + * @param {string} value The value to validate. * * @throws {Error} If the value is invalid. */ @@ -220,7 +222,7 @@ class SnapWPConfigManager { /** * Normalizes the configuration. * - * @param cfg The configuration to normalize. + * @param {Partial} cfg The configuration to normalize. * * @return The normalized configuration. */ @@ -274,7 +276,7 @@ class SnapWPConfigManager { * 2. Config file. * 3. Default values. * - * @param cfg The configuration object. + * @param {Partial} cfg The configuration object. */ static setConfig( cfg?: Partial< SnapWPConfig > ): void { if ( SnapWPConfigManager.configsSet ) { @@ -304,8 +306,8 @@ class SnapWPConfigManager { /** * Validate and resolve the configuration. * - * @param config The configuration to validate. - * @param schema The schema to validate the configuration against. + * @param {Partial} config The configuration to validate. + * @param {ConfigSchema} schema The schema to validate the configuration against. * * @return The resolved configuration. * @@ -322,7 +324,7 @@ class SnapWPConfigManager { /** * Validate a property. * - * @param key The property key. + * @param {keyof Type} key The property key. * * @throws {Error} If the property is invalid. */ diff --git a/packages/core/src/errors/index.ts b/packages/core/src/errors/index.ts index 924efc4f..5afada1e 100644 --- a/packages/core/src/errors/index.ts +++ b/packages/core/src/errors/index.ts @@ -5,7 +5,7 @@ class TemplateParseError extends Error { /** * Constructor. * - * @param message The error message. + * @param {string} message The error message. */ constructor( message: string ) { super( message ); @@ -20,7 +20,7 @@ class GlobalStylesParseError extends Error { /** * Constructor. * - * @param message - The error message. + * @param {string} message The error message. */ constructor( message: string ) { super( message ); diff --git a/packages/core/src/logger/index.ts b/packages/core/src/logger/index.ts index 4cb268e2..7e67ec5c 100644 --- a/packages/core/src/logger/index.ts +++ b/packages/core/src/logger/index.ts @@ -3,19 +3,13 @@ * * @internal */ -export enum LOGTYPE { - DEBUG, - INFO, - WARN, - ERROR, - LOG, -} +export type LOGTYPE = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'LOG'; /** * Logs a message to the console. * - * @param type - The type of log message. - * @param args - The arguments to log. + * @param {LOGTYPE} type The type of log message. + * @param {Array} args The arguments to log. */ const log = ( type: LOGTYPE, ...args: unknown[] ): void => { if ( @@ -30,19 +24,19 @@ const log = ( type: LOGTYPE, ...args: unknown[] ): void => { const prefix = 'SnapWP:'; /* eslint-disable no-console -- Allow the use of console for loggers. */ switch ( type ) { - case LOGTYPE.DEBUG: + case 'DEBUG': console.debug( prefix, ...args ); break; - case LOGTYPE.INFO: + case 'INFO': console.info( prefix, ...args ); break; - case LOGTYPE.WARN: + case 'WARN': console.warn( prefix, ...args ); break; - case LOGTYPE.ERROR: + case 'ERROR': console.error( prefix, ...args ); break; - case LOGTYPE.LOG: + case 'LOG': console.log( prefix, ...args ); break; } @@ -56,59 +50,57 @@ class Logger { /** * Logs a debug message in the console in dev mode * - * @param args - The arguments to log. + * @param {Array} args The arguments to log. * * @example Logger.debug("This is a debug message.") * * @return void */ - static debug = ( ...args: unknown[] ): void => - log( LOGTYPE.DEBUG, ...args ); + static debug = ( ...args: unknown[] ): void => log( 'DEBUG', ...args ); /** * Logs an info message in the console in dev mode * - * @param args - The arguments to log. + * @param {Array} args The arguments to log. * * @example Logger.info("This is an info message.") * * @return void */ - static info = ( ...args: unknown[] ): void => log( LOGTYPE.INFO, ...args ); + static info = ( ...args: unknown[] ): void => log( 'INFO', ...args ); /** * Logs a warning in the console in dev mode * - * @param args - The arguments to log. + * @param {Array} args The arguments to log. * * @example Logger.warn("You should do/change something.") * * @return void */ - static warn = ( ...args: unknown[] ): void => log( LOGTYPE.WARN, ...args ); + static warn = ( ...args: unknown[] ): void => log( 'WARN', ...args ); /** * Logs an error in the console in dev mode * - * @param args - The arguments to log. + * @param {Array} args The arguments to log. * * @example Logger.error("An error occurred.") * * @return void */ - static error = ( ...args: unknown[] ): void => - log( LOGTYPE.ERROR, ...args ); + static error = ( ...args: unknown[] ): void => log( 'ERROR', ...args ); /** * Logs a message in the console in dev mode * - * @param args - The arguments to log. + * @param {Array} args The arguments to log. * * @example Logger.log("This is a message.") * * @return void */ - static log = ( ...args: unknown[] ): void => log( LOGTYPE.LOG, ...args ); + static log = ( ...args: unknown[] ): void => log( 'LOG', ...args ); } export { Logger }; diff --git a/packages/core/src/utils/generate-graphql-url.ts b/packages/core/src/utils/generate-graphql-url.ts index 8e18aa59..240ea361 100644 --- a/packages/core/src/utils/generate-graphql-url.ts +++ b/packages/core/src/utils/generate-graphql-url.ts @@ -3,8 +3,8 @@ import { Logger } from '@/logger'; /** * Generates the complete GraphQL URL based on env vars. * - * @param homeUrl The home URL. - * @param graphqlEndpoint The GraphQL endpoint. + * @param {string} homeUrl The home URL. + * @param {string} graphqlEndpoint The GraphQL endpoint. * * @return The complete GraphQL URL. */ diff --git a/packages/core/src/utils/parse-external-remote-patterns.ts b/packages/core/src/utils/parse-external-remote-patterns.ts index ab73daca..cbe720a6 100644 --- a/packages/core/src/utils/parse-external-remote-patterns.ts +++ b/packages/core/src/utils/parse-external-remote-patterns.ts @@ -1,6 +1,7 @@ /** * Parses given string into remote patterns. - * @param str URLs for external image sources in a comma seperated fashion. + * + * @param {string} str URLs for external image sources in a comma seperated fashion. * * @return an array of remote patterns to be used in next.config.js * diff --git a/packages/core/src/utils/styles/cn.ts b/packages/core/src/utils/styles/cn.ts index b200a915..61f7e3f0 100644 --- a/packages/core/src/utils/styles/cn.ts +++ b/packages/core/src/utils/styles/cn.ts @@ -3,7 +3,7 @@ import { clsx, type ClassValue } from 'clsx'; /** * Combines class names. * - * @param inputs - Class names or objects to combine. + * @param {Array} inputs Class names or objects to combine. * * @return Joined class names. * diff --git a/packages/core/src/utils/styles/find-element-and-get-class-names.ts b/packages/core/src/utils/styles/find-element-and-get-class-names.ts index 6cf889ce..37205cda 100644 --- a/packages/core/src/utils/styles/find-element-and-get-class-names.ts +++ b/packages/core/src/utils/styles/find-element-and-get-class-names.ts @@ -4,8 +4,8 @@ import getClassNamesFromString from './get-class-names-from-string'; /** * Extracts the class names from the specified HTML element within the rendered HTML string. * - * @param renderedHtml - The rendered HTML string. - * @param elementSelector - The element selector (class, id, or tag name) If selector is not provided then it will select the first element and will return it's classNames. + * @param {string|null|undefined} renderedHtml The rendered HTML string. + * @param {string|undefined} elementSelector The element selector (class, id, or tag name) If selector is not provided then it will select the first element and will return it's classNames. * * @return The extracted class names from the first occurrence of the specified element or an empty string if the element is not found. */ diff --git a/packages/core/src/utils/styles/get-class-names-from-string.ts b/packages/core/src/utils/styles/get-class-names-from-string.ts index c0534f7e..5263998c 100644 --- a/packages/core/src/utils/styles/get-class-names-from-string.ts +++ b/packages/core/src/utils/styles/get-class-names-from-string.ts @@ -1,7 +1,7 @@ /** * Extracts class names from the `class` attribute in an HTML string. * - * @param html - The HTML string to parse. + * @param {string} html The HTML string to parse. * * @return An array of class names. */ diff --git a/packages/core/src/utils/styles/get-color-class-name.ts b/packages/core/src/utils/styles/get-color-class-name.ts index d7adbba5..3fc1477d 100644 --- a/packages/core/src/utils/styles/get-color-class-name.ts +++ b/packages/core/src/utils/styles/get-color-class-name.ts @@ -1,8 +1,8 @@ /** * Generates a CSS class name for a given color context and color slug. * - * @param colorContextName - The context name for the color (e.g., 'background', 'text'). - * @param colorSlug - The slug for the color (e.g., 'primary', 'secondary'). + * @param {string} colorContextName The context name for the color (e.g., 'background', 'text'). + * @param {string} colorSlug The slug for the color (e.g., 'primary', 'secondary'). * * @return The generated CSS class name or undefined if parameters are missing. */ diff --git a/packages/core/src/utils/styles/get-image-size-from-attributes.ts b/packages/core/src/utils/styles/get-image-size-from-attributes.ts index 35928cbd..d2aa4798 100644 --- a/packages/core/src/utils/styles/get-image-size-from-attributes.ts +++ b/packages/core/src/utils/styles/get-image-size-from-attributes.ts @@ -30,7 +30,7 @@ const imageSizeToHeight: { /** * Retrieves the width and height based on image attributes. * - * @param attributes - Image size attributes including sizeSlug, width, and height. + * @param {ImageSizeAttributes} attributes Image size attributes including sizeSlug, width, and height. * * @return An object containing the width and height in pixels. * diff --git a/packages/core/src/utils/styles/get-px-for-size-attribute.ts b/packages/core/src/utils/styles/get-px-for-size-attribute.ts index 9ee6ae85..dc181247 100644 --- a/packages/core/src/utils/styles/get-px-for-size-attribute.ts +++ b/packages/core/src/utils/styles/get-px-for-size-attribute.ts @@ -1,7 +1,7 @@ /** * Converts a size attribute to pixels. * - * @param sizeAttribute - The size attribute string (e.g., "10em", "50%"). + * @param {string} sizeAttribute The size attribute string (e.g., "10em", "50%"). * * @return The size in pixels. * diff --git a/packages/core/src/utils/styles/get-spacing-preset-css-var.ts b/packages/core/src/utils/styles/get-spacing-preset-css-var.ts index f0c4a254..6d97c25a 100644 --- a/packages/core/src/utils/styles/get-spacing-preset-css-var.ts +++ b/packages/core/src/utils/styles/get-spacing-preset-css-var.ts @@ -3,7 +3,7 @@ * * @see https://github.com/WordPress/gutenberg/blob/da50610ac45e2cd18b59424d260bb3d693535061/packages/block-editor/src/components/spacing-sizes-control/utils.js#L128 * - * @param value Value to convert. + * @param {string|null|undefined} value Value to convert. * * @return CSS var string for given spacing preset value. */ diff --git a/packages/core/src/utils/styles/get-style-object-from-string.ts b/packages/core/src/utils/styles/get-style-object-from-string.ts index ee84cae3..85ff213d 100644 --- a/packages/core/src/utils/styles/get-style-object-from-string.ts +++ b/packages/core/src/utils/styles/get-style-object-from-string.ts @@ -4,9 +4,9 @@ import type { CSSProperties } from 'react'; /** * Formats a string to camel case. * - * @param str - The input string. + * @param {string} str The input string. * - * @return The camelcased string. + * @return The camelcase string. * * @internal */ @@ -31,7 +31,7 @@ function formatStringToCamelCase( str: string ): string { /** * Converts a CSS string to an object. * - * @param str - The CSS string. + * @param {string} str The CSS string. * * @return The style object. */ @@ -56,7 +56,7 @@ function cssToReactStyle( str: string ): CSSProperties { /** * Converts a CSS string or object to a React style object. * - * @param css - The CSS string. + * @param {Object|string} css The CSS string. * * @return The style object. */ diff --git a/packages/core/src/utils/styles/get-styles-from-attributes.ts b/packages/core/src/utils/styles/get-styles-from-attributes.ts index 4d86ddc0..c355525d 100644 --- a/packages/core/src/utils/styles/get-styles-from-attributes.ts +++ b/packages/core/src/utils/styles/get-styles-from-attributes.ts @@ -10,8 +10,8 @@ interface AttributesWithStyle { /** * Extracts and compiles styles from attributes. * - * @param attributes - Object containing a style string. - * @param attributes.style - The style string to compile. + * @param {Object} attributes - Object containing a style string. + * @param {AttributesWithStyle['style']} attributes.style - The style string to compile. * * @return Compiled styles as an object or an empty object if no styles exist. */ diff --git a/packages/core/src/utils/url/transformers.ts b/packages/core/src/utils/url/transformers.ts index b7e3b0de..f8e916f7 100644 --- a/packages/core/src/utils/url/transformers.ts +++ b/packages/core/src/utils/url/transformers.ts @@ -4,7 +4,7 @@ import { isInternalUrl, isWPSiteUrl } from './validators'; /** * Convert a URL to an internal URL. * - * @param url The URL to convert. + * @param {string} url The URL to convert. * * @return The internal URL. */ @@ -32,7 +32,7 @@ export const toFrontendUri = ( url: string ): string => { /** * Remove trailing slash from the URL. * - * @param url The URL to modify. + * @param {string} url The URL to modify. * * @return The modified URL. * @@ -45,7 +45,7 @@ export function removeTrailingSlash( url: string ): string { /** * Add trailing slash to the URL. * - * @param url The URL to modify. + * @param {string} url The URL to modify. * * @return The modified URL. * @@ -58,7 +58,7 @@ export function addTrailingSlash( url: string ): string { /** * Remove leading slash from the URL. * - * @param url The URL to modify. + * @param {string} url The URL to modify. * * @return The modified URL. * @@ -71,7 +71,7 @@ export function removeLeadingSlash( url: string ): string { /** * Add leading slash to the URL. * - * @param url The URL to modify. + * @param {string} url The URL to modify. * * @return The modified URL. * diff --git a/packages/core/src/utils/url/validators.ts b/packages/core/src/utils/url/validators.ts index fec57444..6901471a 100644 --- a/packages/core/src/utils/url/validators.ts +++ b/packages/core/src/utils/url/validators.ts @@ -3,8 +3,8 @@ import { getConfig } from '@/config'; /** * Check if a URL is the home URL. * - * @param url The URL to check. - * @param ignoreProtocol - Ignore HTTP protocol when comparing URLs. + * @param {string} url The URL to check. + * @param {boolean} ignoreProtocol - Ignore HTTP protocol when comparing URLs. * * @return Whether the URL is the home URL. */ @@ -30,7 +30,7 @@ export const isWPHomeUrl = ( /** * Check if a URL is the site URL. * - * @param url The URL to check. + * @param {string} url The URL to check. * @param {boolean} ignoreProtocol - Whether to ignore the HTTP protocol when comparing URLs. * * @return Whether the URL is the site URL. @@ -62,8 +62,8 @@ export const isWPSiteUrl = ( /** * Check if a URL is internal (Site URL or Home Url). * - * @param url The URL to check. - * @param ignoreProtocol - Ignore HTTP protocol when comparing URLs. + * @param {string} url The URL to check. + * @param {boolean} ignoreProtocol - Ignore HTTP protocol when comparing URLs. * * @return Whether the URL is internal. */ @@ -79,7 +79,7 @@ export const isInternalUrl = ( }; /** - * @param str A string to be validated as a Url. + * @param {string} str A string to be validated as a Url. * @return flag signifying validity. * * @internal diff --git a/packages/e2e-tests/src/utils/wait-for-server.ts b/packages/e2e-tests/src/utils/wait-for-server.ts index 012dc177..890ab67b 100644 --- a/packages/e2e-tests/src/utils/wait-for-server.ts +++ b/packages/e2e-tests/src/utils/wait-for-server.ts @@ -1,9 +1,10 @@ /** * Waits for a server to respond within a given number of attempts. * - * @param url - The server URL to check. - * @param timeout - Max wait time per attempt in ms. - * @param retries - Number of retry attempts (default: 5). + * @param {string} url The server URL to check. + * @param {number} timeout Max wait time per attempt in ms. + * @param {number} retries Number of retry attempts (default: 5). + * * @throws If the server doesn't respond after all retries. */ export default async function waitForServer( diff --git a/packages/next/src/components/default-error.tsx b/packages/next/src/components/default-error.tsx index 27ae33d9..4c57fe2a 100644 --- a/packages/next/src/components/default-error.tsx +++ b/packages/next/src/components/default-error.tsx @@ -8,9 +8,9 @@ import type { ReactNode } from 'react'; * This component is exported directly from `package.json` to prevent conflicts with other components when importing it from the Next.js package. * This resolves the issue of `You're importing a component that needs "next/headers". That only works in a Server Component which is not supported in the pages/ directory` * - * @param root0 - The props. - * @param root0.error - The error. - * @param root0.reset - The reset function. + * @param {Object} props The props. + * @param {Error} props.error The error. + * @param {Function} props.reset The reset function. * * @return The default error component. */ diff --git a/packages/next/src/components/font.tsx b/packages/next/src/components/font.tsx index b0319046..99875c46 100644 --- a/packages/next/src/components/font.tsx +++ b/packages/next/src/components/font.tsx @@ -3,8 +3,8 @@ import type { ReactNode } from 'react'; /** * A wrapper for loading fonts dynamically using next/font. * - * @param props - Props for the Font component. - * @param props.renderedFontFaces - Font face data as a string. + * @param {Object} props Props for the Font component. + * @param {string} props.renderedFontFaces Font face data as a string. * * @return A style tag with the rendered font faces. * diff --git a/packages/next/src/components/image.tsx b/packages/next/src/components/image.tsx index a3ec0483..eff0877a 100644 --- a/packages/next/src/components/image.tsx +++ b/packages/next/src/components/image.tsx @@ -38,15 +38,15 @@ interface ImageInterface { * Note: The next/image component applies style { color: transparent; } to an image when it loads successfully, ensuring the alt text is hidden. If the image fails to load, this style isn’t applied, making the alt text visible instead. * @see https://github.com/vercel/next.js/blob/v15.1.3/packages/next/src/shared/lib/get-img-props.ts#L625 * - * @param props - Props for the component. - * @param props.alt - Alt text for the image. - * @param props.image - Media item containing image details. - * @param props.width - Width of the image. - * @param props.height - Height of the image. - * @param props.className - CSS class names. - * @param props.priority - If true, loads the image with higher priority. - * @param props.fill - If true, fills the container. - * @param props.src - Source URL for the image. + * @param {Object} props Props for the component. + * @param {ImageInterface['alt']} props.alt Alt text for the image. + * @param {ImageInterface['image']} props.image Media item containing image details. + * @param {ImageInterface['width']} props.width Width of the image. + * @param {ImageInterface['height']} props.height Height of the image. + * @param {ImageInterface['className']} props.className CSS class names. + * @param {ImageInterface['priority']} props.priority If true, loads the image with higher priority. + * @param {ImageInterface['fill']} props.fill If true, fills the container. + * @param {ImageInterface['src']} props.src Source URL for the image. * * @return The rendered image. */ diff --git a/packages/next/src/components/link.tsx b/packages/next/src/components/link.tsx index 401a11f1..516e1b5e 100644 --- a/packages/next/src/components/link.tsx +++ b/packages/next/src/components/link.tsx @@ -19,11 +19,11 @@ interface LinkInterface { /** * Link component to handle internal and external links. * - * @param props - Props for the component. - * @param props.href - Link's href attribute. - * @param props.style - CSS style object. - * @param props.className - CSS class name. - * @param props.children - Block's Children. + * @param {Object} props Props for the component. + * @param {LinkInterface['href']} props.href Link's href attribute. + * @param {LinkInterface['style']} props.style CSS style object. + * @param {LinkInterface['className']} props.className CSS class name. + * @param {ReactNode} props.children Block's Children. * * @return The rendered link. */ diff --git a/packages/next/src/components/script-module.tsx b/packages/next/src/components/script-module.tsx index 9b4aa83e..a03eeddd 100644 --- a/packages/next/src/components/script-module.tsx +++ b/packages/next/src/components/script-module.tsx @@ -28,11 +28,11 @@ interface ScriptModuleInterface { * A reusable wrapper for Next.js Script component to handle script modules and their dependencies. * Uses Next.js script loading strategies to optimize loading behavior. * - * @param props - Props for the Script Module component - * @param props.handle - The unique identifier for the script module - * @param props.src - The source URL for the script module - * @param props.extraData - Additional data required by the script module - * @param props.dependencies - Dependencies required by the script module + * @param {Object} props Props for the Script Module component. + * @param {ScriptModuleInterface['handle']} props.handle The unique identifier for the script module. + * @param {ScriptModuleInterface['src']} props.src The source URL for the script module. + * @param {ScriptModuleInterface['extraData']} props.extraData Additional data required by the script module. + * @param {ScriptModuleInterface['dependencies']} props.dependencies Dependencies required by the script module. * * @return The rendered script module elements */ diff --git a/packages/next/src/components/script.tsx b/packages/next/src/components/script.tsx index 72d3e79b..072a124b 100644 --- a/packages/next/src/components/script.tsx +++ b/packages/next/src/components/script.tsx @@ -14,14 +14,14 @@ interface ScriptInterface { /** * A reusable wrapper for Next.js Script component. * - * @param props - Props for the Script component. - * @param props.after - Scripts to be executed after the main script. - * @param props.before - Scripts to be executed before the main script. - * @param props.extraData - Additional data to be included in the script. - * @param props.handle - The handle for the script. - * @param props.loadingStrategy - The loading strategy for the script (async or defer). - * @param props.groupLocation - The location where the script should be loaded. - * @param props.src - The source URL for the script. + * @param {Object} props Props for the Script component. + * @param {ScriptInterface['after']} props.after Scripts to be executed after the main script. + * @param {ScriptInterface['before']} props.before Scripts to be executed before the main script. + * @param {ScriptInterface['extraData']} props.extraData Additional data to be included in the script. + * @param {ScriptInterface['handle']} props.handle The handle for the script. + * @param {ScriptInterface['loadingStrategy']} props.loadingStrategy The loading strategy for the script (async or defer). + * @param {ScriptInterface['location']} props.groupLocation The location where the script should be loaded. + * @param {ScriptInterface['src']} props.src The source URL for the script. * * @return The rendered script element. */ diff --git a/packages/next/src/config/get-snap-wp-webpack-plugins.ts b/packages/next/src/config/get-snap-wp-webpack-plugins.ts index a578dd6c..75c97438 100644 --- a/packages/next/src/config/get-snap-wp-webpack-plugins.ts +++ b/packages/next/src/config/get-snap-wp-webpack-plugins.ts @@ -5,7 +5,7 @@ import { /** * Generates webpack plugin array required for SnapWP packges to work. - * @param snapWPConfigPath -- Path to snapwp config file + * @param {string} snapWPConfigPath -- Path to snapwp config file * @return Webpack config */ // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Using `any` type as the parameter type is `any` in Next.js. diff --git a/packages/next/src/config/snapwp-remote-patterns.ts b/packages/next/src/config/snapwp-remote-patterns.ts index cd1d7f1a..ba37d297 100644 --- a/packages/next/src/config/snapwp-remote-patterns.ts +++ b/packages/next/src/config/snapwp-remote-patterns.ts @@ -2,7 +2,7 @@ import type { RemotePattern } from 'next/dist/shared/lib/image-config'; /** * Creates base remote patterns - * @param homeUrl -- WordPress Home Url + * @param {URL} homeUrl -- WordPress Home Url * @return Remote pattern array */ export const generateRemotePatterns = ( homeUrl: URL ): RemotePattern[] => { diff --git a/packages/next/src/config/with-snap-wp.ts b/packages/next/src/config/with-snap-wp.ts index f229590c..ac95120e 100644 --- a/packages/next/src/config/with-snap-wp.ts +++ b/packages/next/src/config/with-snap-wp.ts @@ -10,7 +10,7 @@ import type { WebpackConfigContext } from 'next/dist/server/config-shared'; /** * Extends the Next.js configuration with SnapWP configuration. * - * @param nextConfig The Next.js configuration object. + * @param {NextConfig} nextConfig The Next.js configuration object. * * @return The extended configuration object. */ diff --git a/packages/next/src/middleware/cors.ts b/packages/next/src/middleware/cors.ts index 8dd33380..3027fd7e 100644 --- a/packages/next/src/middleware/cors.ts +++ b/packages/next/src/middleware/cors.ts @@ -16,7 +16,7 @@ import type { MiddlewareFactory } from './utils'; * eg: http://localhost:3000/proxy/assets/api.js will get resouce at https://examplewp/assets/api.js * assuming env vars NEXT_PUBLIC_FRONTEND_URL had its value set to http://localhost:3000 and NEXT_PUBLIC_WP_HOME_URL to https://examplewp.com * - * @param next - Next middleware + * @param {NextMiddleware} next Next middleware. * * @return The response object with modified headers. */ diff --git a/packages/next/src/middleware/current-path.ts b/packages/next/src/middleware/current-path.ts index 49f37b6a..9acc0732 100644 --- a/packages/next/src/middleware/current-path.ts +++ b/packages/next/src/middleware/current-path.ts @@ -7,7 +7,7 @@ import type { NextFetchEvent, NextMiddleware, NextRequest } from 'next/server'; * This middleware adds a custom header 'x-current-path' to the response, * which contains the current pathname of the request. * - * @param next - Next middleware + * @param {NextMiddleware} next Next middleware. * * @return The response object with modified headers */ diff --git a/packages/next/src/middleware/proxies.ts b/packages/next/src/middleware/proxies.ts index f46462cf..e665ef4f 100644 --- a/packages/next/src/middleware/proxies.ts +++ b/packages/next/src/middleware/proxies.ts @@ -14,7 +14,7 @@ import type { MiddlewareFactory } from './utils'; * * This middleware adds custom proxies. * - * @param next - Next middleware + * @param {NextMiddleware} next Next middleware. * * @return Custom redirection or NextMiddleware. */ diff --git a/packages/next/src/middleware/utils.ts b/packages/next/src/middleware/utils.ts index 8fa7e06d..8b7d7431 100644 --- a/packages/next/src/middleware/utils.ts +++ b/packages/next/src/middleware/utils.ts @@ -12,10 +12,10 @@ export type MiddlewareFactory = ( * Stacks middlewares. * Ref: https://reacthustle.com/blog/how-to-chain-multiple-middleware-functions-in-nextjs * - * @param functions Array containing Middleware. - * @param index Index of current middleware. - * @param stackDefaultMiddlewares Weather to add load default middlewares with custom ones. - * Pass false to skip loading default middlewares. + * @param {Array} functions Array containing Middleware. + * @param {number} index Index of current middleware. + * @param {boolean} stackDefaultMiddlewares Weather to add load default middlewares with custom ones. + * Pass false to skip loading default middlewares. * * @return NextJS Middleware. */ @@ -43,7 +43,7 @@ export function appMiddlewares( /** * Stacks default middlewares with the custom middlewares passed by user. * - * @param middlewares Array containing user defined Middlewares. + * @param {Array} middlewares Array containing user defined Middlewares. * * @return Array combining default middlewares and custom middlewares. */ diff --git a/packages/next/src/react-parser/index.tsx b/packages/next/src/react-parser/index.tsx index 77bf0643..3b955ab2 100644 --- a/packages/next/src/react-parser/index.tsx +++ b/packages/next/src/react-parser/index.tsx @@ -8,8 +8,8 @@ import type { ReactNode } from 'react'; /** * Parses HTML string into React components. * - * @param props - The props for the parser. - * @param props.html - The HTML string to parse and render. + * @param {Object} props The props for the parser. + * @param {string} props.html The HTML string to parse and render. * * @return The rendered React components. */ diff --git a/packages/next/src/react-parser/options.tsx b/packages/next/src/react-parser/options.tsx index 92a59774..d44ed82d 100644 --- a/packages/next/src/react-parser/options.tsx +++ b/packages/next/src/react-parser/options.tsx @@ -15,7 +15,7 @@ export const defaultOptions: HTMLReactParserOptions = { /** * Replaces anchor tags with Next.js Link components. * - * @param domNode - The DOM node being processed. + * @param {DOMNode} domNode The DOM node being processed. * * @return A React element if the node is an anchor tag, otherwise undefined. */ diff --git a/packages/next/src/root-layout/global-head.tsx b/packages/next/src/root-layout/global-head.tsx index ef93550e..6ca021a3 100644 --- a/packages/next/src/root-layout/global-head.tsx +++ b/packages/next/src/root-layout/global-head.tsx @@ -7,10 +7,10 @@ import type { ReactNode } from 'react'; * Renders the head section with custom styles, block styles, global stylesheet, * rendered font faces for the global context. * - * @param props - The props for the component. - * @param props.customCss - Custom CSS to be included. - * @param props.globalStylesheet - Global stylesheet for the page. - * @param props.renderedFontFaces - Font faces rendered locally. + * @param {Object} props The props for the component. + * @param {string|null} props.customCss Custom CSS to be included. + * @param {string|null} props.globalStylesheet Global stylesheet for the page. + * @param {string|null} props.renderedFontFaces Font faces rendered locally. * * @return A head element containing the provided styles and links. */ diff --git a/packages/next/src/root-layout/icons-metadata.ts b/packages/next/src/root-layout/icons-metadata.ts index 62b82f29..b6bf8979 100644 --- a/packages/next/src/root-layout/icons-metadata.ts +++ b/packages/next/src/root-layout/icons-metadata.ts @@ -112,8 +112,8 @@ export const getIcons = async (): Promise< IconMetaData > => { /** * Filter icons by multiple size formats. * - * @param icons - List of all available icons. - * @param sizes - Array of sizes in "WxH" format (e.g., "32x32"). + * @param {Array} icons - List of all available icons. + * @param {Array} sizes - Array of sizes in "WxH" format (e.g., "32x32"). * @return Filtered list of icons. */ export const filterIconsBySize = ( @@ -127,8 +127,8 @@ export const filterIconsBySize = ( /** * Find a single icon matching the specified size. * - * @param icons - List of icons. - * @param size - Size in "WxH" format (e.g., "270x270"). + * @param {Array} icons - List of icons. + * @param {Array} size - Size in "WxH" format (e.g., "270x270"). * @return The first matching icon or undefined. */ export const findIconBySize = ( @@ -140,7 +140,7 @@ export const findIconBySize = ( /** * Format icons into the required metadata structure. * - * @param icons - List of icons. + * @param {Array} icons - List of icons. * * @return Formatted list of icons. */ diff --git a/packages/next/src/root-layout/index.tsx b/packages/next/src/root-layout/index.tsx index 408553a1..c9890d26 100644 --- a/packages/next/src/root-layout/index.tsx +++ b/packages/next/src/root-layout/index.tsx @@ -11,9 +11,10 @@ export type RootLayoutProps = { /** * The RootLayout to be used in a NextJS app. - * @param props - The props for the renderer. - * @param props.getGlobalStyles - A async callback to get global styles. - * @param props.children - Child components. + * + * @param {Object} props The props for the renderer. + * @param {RootLayoutProps['getGlobalStyles']} props.getGlobalStyles A async callback to get global styles. + * @param {ReactNode} props.children Child components. * * @return The rendered template. */ diff --git a/packages/next/src/template-renderer/index.tsx b/packages/next/src/template-renderer/index.tsx index 80e2ff75..e8c98233 100644 --- a/packages/next/src/template-renderer/index.tsx +++ b/packages/next/src/template-renderer/index.tsx @@ -16,9 +16,9 @@ export type TemplateRendererProps = { * Renders a full HTML document including the head, body, and scripts. * Combines custom styles, block content, and scripts into a complete page. * - * @param props - The props for the component.. - * @param props.getTemplateData - A async callback to get template styles and content. - * @param props.children - The block content to render. + * @param {Object} props The props for the component. + * @param {TemplateRendererProps['getTemplateData']} props.getTemplateData A async callback to get template styles and content. + * @param {TemplateRendererProps['children']} props.children The block content to render. * * @return A complete HTML document structure. */ diff --git a/packages/next/src/template-renderer/template-head.tsx b/packages/next/src/template-renderer/template-head.tsx index 1201fc3d..f80e8ebe 100644 --- a/packages/next/src/template-renderer/template-head.tsx +++ b/packages/next/src/template-renderer/template-head.tsx @@ -9,8 +9,8 @@ export interface TemplateHeadProps { /** * Renders the head section with additional stylesheets for a template. * - * @param props - The props for the component. - * @param props.stylesheets - An array of additional stylesheets and inline styles. + * @param {Object} props The props for the component. + * @param {TemplateHeadProps['stylesheets']} props.stylesheets An array of additional stylesheets and inline styles. * * @return A head element containing the provided styles and links. */ diff --git a/packages/next/src/template-renderer/template-scripts.tsx b/packages/next/src/template-renderer/template-scripts.tsx index ee67aa01..fe889018 100644 --- a/packages/next/src/template-renderer/template-scripts.tsx +++ b/packages/next/src/template-renderer/template-scripts.tsx @@ -10,8 +10,8 @@ import type { PropsWithChildren, ReactNode } from 'react'; /** * Renders a list of script elements from a given array of script data. * - * @param props - The props for the component. - * @param props.scripts - Array of script objects to be rendered. + * @param {Object} props The props for the component. + * @param {Array} props.scripts Array of script objects to be rendered. * * @return A collection of `