docs: update type declarations and improve documentation across multiple files

Author: johannschopplich

docs/api/auto-sizes.md

@@ -8,16 +8,7 @@ To lazy load images, refer to the [`lazyLoad`](/api/lazy-load) method.
 
 ## Type Declarations
 
-```ts
-function autoSizes<T extends HTMLImageElement | HTMLSourceElement>(
-  /**
-   * A CSS selector, a DOM element, a list of DOM elements, or an array of DOM elements to calculate the `sizes` attribute for.
-   *
-   * @default 'img[data-sizes="auto"], source[data-sizes="auto"]'
-   */
-  selectorsOrElements?: string | T | NodeListOf<T> | T[]
-): void
-```
+<<< @/../packages/core/src/lazyLoad.ts#autoSizes{ts}
 
 ## Example
 

docs/api/blurhash-create-png-data-uri.md

@@ -15,29 +15,9 @@ The function uses the `fast-blurhash` library for decoding and generates a compa
 
 ## Type Declarations
 
-```ts
-interface BlurHashOptions {
-  /**
-   * Aspect ratio (width / height) of the BlurHash image to be decoded.
-   *
-   * @default 1 (square aspect ratio)
-   */
-  ratio?: number
-
-  /**
-   * The size of the longer edge (width or height) of the BlurHash image to be
-   * decoded, depending on the aspect ratio.
-   *
-   * @default 32
-   */
-  size?: number
-}
-
-function createPngDataUri(
-  hash: string,
-  options?: BlurhashOptions
-): string
-```
+<<< @/../packages/core/src/blurhash.ts#BlurHashOptions{ts}
+
+<<< @/../packages/core/src/blurhash.ts#createPngDataUri{ts}
 
 ## Example
 

docs/api/create-placeholder-from-hash.md

@@ -4,20 +4,7 @@ Generates a PNG data URI placeholder from a BlurHash or ThumbHash string. This f
 
 ## Type Declarations
 
-```ts
-function createPlaceholderFromHash(options?: {
-  /** If present, hash and ratio are extracted from element's data attributes */
-  image?: HTMLImageElement
-  /** Hash string to decode */
-  hash?: string
-  /** Type of hash algorithm */
-  hashType?: 'blurhash' | 'thumbhash'
-  /** Size of longer edge for BlurHash decoding (ignored for ThumbHash) */
-  size?: number
-  /** Aspect ratio (width/height) for BlurHash */
-  ratio?: number
-}): string | undefined
-```
+<<< @/../packages/core/src/lazyLoad.ts#createPlaceholderFromHash{ts}
 
 ## Parameters
 

docs/api/lazy-load.md

@@ -36,65 +36,6 @@ cleanup()
 
 ## Type Declarations
 
-```ts
-interface UnLazyLoadOptions {
-  /**
-   * Whether to generate a blurry placeholder from a [BlurHash](https://blurha.sh)
-   * or [ThumbHash](https://github.com/evanw/thumbhash) string. The placeholder
-   * image will be inlined as a data URI in the `src` attribute.
-   *
-   * @remarks
-   * If this option is set to `true`, the `data-blurhash` or `data-thumbhash`
-   * attributes will be used for the hash string. If you pass a single element
-   * as the `selectorsOrElements` argument, you can also pass a string to this
-   * option to override the hash string.
-   */
-  hash?: string | boolean
-
-  /**
-   * Specify the hash type to use for generating the blurry placeholder.
-   *
-   * @remarks
-   * This option is ignored if the `hash` option is set to a boolean value.
-   * In these cases, the `data-blurhash` or `data-thumbhash` attributes will
-   * be used to determine the hash type.
-   *
-   * @default 'blurhash'
-   */
-  hashType?: 'blurhash' | 'thumbhash'
-
-  /**
-   * The size of the longer edge (width or height) of the BlurHash image to be
-   * decoded, depending on the aspect ratio.
-   *
-   * @remarks
-   * This option is ignored if the `hashType` option is set to `thumbhash`.
-   *
-   * @default 32
-   */
-  placeholderSize?: number
-
-  /**
-   * Whether to update the `sizes` attribute on resize events with the current image width.
-   *
-   * @default false
-   */
-  updateSizesOnResize?: boolean
+<<< @/../packages/core/src/types.ts#UnLazyLoadOptions{ts}
 
-  /**
-   * A callback function to run when an image is loaded.
-   */
-  onImageLoad?: (image: HTMLImageElement) => void
-}
-
-function lazyLoad<T extends HTMLImageElement>(
-  /**
-   * A CSS selector, a DOM element, a list of DOM elements, or an array of DOM elements to lazy-load.
-   *
-   * @default 'img[loading="lazy"]'
-   */
-  selectorsOrElements?: string | T | NodeListOf<T> | T[],
-
-  options?: UnLazyLoadOptions
-): () => void
-```
+<<< @/../packages/core/src/lazyLoad.ts#lazyLoad{ts}

docs/api/load-image.md

@@ -12,9 +12,4 @@ The function performs the following operations:
 
 ## Type Declarations
 
-```ts
-function loadImage(
-  image: HTMLImageElement,
-  onImageLoad?: (image: HTMLImageElement) => void
-): void
-```
+<<< @/../packages/core/src/lazyLoad.ts#loadImage{ts}

docs/integrations/nuxt.md

@@ -33,28 +33,7 @@ export default defineNuxtConfig({
 
 The `@unlazy/nuxt` module accepts the following options:
 
-```ts
-export interface ModuleOptions {
-  /**
-   * Whether to generate the blurry placeholder on the server-side if a BlurHash
-   * or ThumbHash is provided via the `blurhash`, respectively `thumbhash` prop.
-   *
-   * @default true
-   */
-  ssr?: boolean
-
-  /**
-   * The size of the longer edge (width or height) of the BlurHash image to be
-   * decoded, depending on the aspect ratio.
-   *
-   * @remarks
-   * This option is ignored if the a ThumbHash is used.
-   *
-   * @default 32
-   */
-  placeholderSize?: number
-}
-```
+<<< @/../packages/nuxt/src/module.ts#ModuleOptions{ts}
 
 Adapt the module options to your needs:
 

packages/core/src/blurhash.ts

@@ -2,6 +2,7 @@ import { decodeBlurHash } from 'fast-blurhash'
 import { DEFAULT_PLACEHOLDER_SIZE } from './constants'
 import { rgbaToDataUri } from './utils/dataUri'
 
+// #region BlurHashOptions
 export interface BlurHashOptions {
   /**
    * Aspect ratio (width / height) of the BlurHash image to be decoded.
@@ -18,20 +19,27 @@ export interface BlurHashOptions {
    */
   size?: number
 }
+// #endregion BlurHashOptions
 
+// #region createPngDataUri
+export function createPngDataUri(
+  hash: string,
+  options?: BlurHashOptions
+): string
+// #endregion createPngDataUri
 export function createPngDataUri(
   hash: string,
   {
     ratio = 1,
     size = DEFAULT_PLACEHOLDER_SIZE,
   }: BlurHashOptions = {},
-) {
+): string {
   const { width, height } = getAspectRatioDimensions(ratio, size)
   const rgba = decodeBlurHash(hash, width, height)
   return rgbaToDataUri(width, height, rgba)
 }
 
-function getAspectRatioDimensions(ratio: number, size: number) {
+function getAspectRatioDimensions(ratio: number, size: number): { width: number, height: number } {
   const isLandscapeOrSquare = ratio >= 1
 
   return {

packages/core/src/lazyLoad.ts

@@ -4,12 +4,18 @@ import { DEFAULT_PLACEHOLDER_SIZE } from './constants'
 import { createPngDataUri as createPngDataUriFromThumbHash } from './thumbhash'
 import { createIndexedImagePlaceholder, debounce, isCrawler, isLazyLoadingSupported, toElementArray } from './utils'
 
+// #region lazyLoad
 export function lazyLoad<T extends HTMLImageElement>(
   /**
    * A CSS selector, a DOM element, a list of DOM elements, or an array of DOM elements to lazy-load.
    *
    * @default 'img[loading="lazy"]'
    */
+  selectorsOrElements?: string | T | NodeListOf<T> | T[],
+  options?: UnLazyLoadOptions
+): () => void
+// #endregion lazyLoad
+export function lazyLoad<T extends HTMLImageElement>(
   selectorsOrElements: string | T | NodeListOf<T> | T[] = 'img[loading="lazy"]',
   {
     hash = true,
@@ -18,7 +24,7 @@ export function lazyLoad<T extends HTMLImageElement>(
     updateSizesOnResize = false,
     onImageLoad,
   }: UnLazyLoadOptions = {},
-) {
+): () => void {
   const cleanupHandlers = new Set<() => void>()
 
   for (const [index, image] of toElementArray<T>(selectorsOrElements).entries()) {
@@ -89,22 +95,33 @@ export function lazyLoad<T extends HTMLImageElement>(
   }
 }
 
+// #region autoSizes
 export function autoSizes<T extends HTMLImageElement | HTMLSourceElement>(
   /**
    * A CSS selector, a DOM element, a list of DOM elements, or an array of DOM elements to calculate the `sizes` attribute for.
    *
    * @default 'img[data-sizes="auto"], source[data-sizes="auto"]'
    */
+  selectorsOrElements?: string | T | NodeListOf<T> | T[]
+): void
+// #endregion autoSizes
+export function autoSizes<T extends HTMLImageElement | HTMLSourceElement>(
   selectorsOrElements: string | T | NodeListOf<T> | T[] = 'img[data-sizes="auto"], source[data-sizes="auto"]',
-) {
+): void {
   for (const image of toElementArray<T>(selectorsOrElements))
     updateSizesAttribute(image)
 }
 
+// #region loadImage
+export function loadImage(
+  image: HTMLImageElement,
+  onImageLoad?: (image: HTMLImageElement) => void
+): void
+// #endregion loadImage
 export function loadImage(
   image: HTMLImageElement,
   onImageLoad?: (image: HTMLImageElement) => void,
-) {
+): void {
   // Skip preloading its `data-src` or `data-srcset` to avoid unnecessary requests
   if (isDescendantOfPicture(image)) {
     updatePictureSources(image)
@@ -139,6 +156,18 @@ export function loadImage(
   }, { once: true })
 }
 
+// #region createPlaceholderFromHash
+export function createPlaceholderFromHash(options?: {
+  /** If present, the hash will be extracted from the image's `data-blurhash` or `data-thumbhash` attribute and ratio will be calculated from the image's actual dimensions. */
+  image?: HTMLImageElement
+  hash?: string
+  hashType?: 'blurhash' | 'thumbhash'
+  /** @default 32 */
+  size?: number
+  /** Will be calculated from the image's actual dimensions if image is provided and ratio is not. */
+  ratio?: number
+}): string | undefined
+// #endregion createPlaceholderFromHash
 export function createPlaceholderFromHash(
   {
     image,
@@ -156,7 +185,7 @@ export function createPlaceholderFromHash(
     /** Will be calculated from the image's actual dimensions if image is provided and ratio is not. */
     ratio?: number
   } = {},
-) {
+): string | undefined {
   if (image && !hash) {
     const { blurhash, thumbhash } = image.dataset
     hash = thumbhash || blurhash
@@ -195,7 +224,7 @@ function updateSizesAttribute(
     updateOnResize?: boolean
     processSourceElements?: boolean
   },
-) {
+): (() => void) | undefined {
   if (element.dataset.sizes !== 'auto')
     return
 
@@ -252,7 +281,7 @@ function updatePictureSources(image: HTMLImageElement) {
   }
 }
 
-function getOffsetWidth(element: HTMLElement | HTMLSourceElement) {
+function getOffsetWidth(element: HTMLElement | HTMLSourceElement): number | undefined {
   return element instanceof HTMLSourceElement
     ? element.parentElement?.getElementsByTagName('img')[0]?.offsetWidth
     : element.offsetWidth

packages/core/src/thumbhash.ts

@@ -1,20 +1,20 @@
 import { thumbHashToRGBA } from 'thumbhash'
 import { rgbaToDataUri } from './utils/dataUri'
 
-export function createPngDataUri(hash: string) {
+export function createPngDataUri(hash: string): string {
   const hashArray = base64ToUint8Array(hash)
   const { w, h, rgba } = thumbHashToRGBA(hashArray)
 
   return rgbaToDataUri(w, h, rgba)
 }
 
-function base64ToUint8Array(base64String: string) {
+function base64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer> {
   return Uint8Array.from(
     globalThis.atob(base64UrlToBase64(base64String)),
     x => x.charCodeAt(0),
   )
 }
 
-function base64UrlToBase64(base64Url: string) {
+function base64UrlToBase64(base64Url: string): string {
   return base64Url.replaceAll('-', '+').replaceAll('_', '/')
 }

packages/core/src/types.ts

@@ -1,3 +1,4 @@
+// #region UnLazyLoadOptions
 export interface UnLazyLoadOptions {
   /**
    * Whether to generate a blurry placeholder from a [BlurHash](https://blurha.sh)
@@ -47,3 +48,4 @@ export interface UnLazyLoadOptions {
    */
   onImageLoad?: (image: HTMLImageElement) => void
 }
+// #endregion UnLazyLoadOptions