docs: update documentation for image loading features and placeholder generation

Author: johannschopplich

docs/advanced/aspect-ratio.md

@@ -1,11 +1,12 @@
 # Aspect Ratio for Blurry Placeholders
 
-In certain cases, the blurry placeholder might not have the full image width and height. To ensure that the layout does not change when the full-quality image loads and to maintain a consistent user experience, you can add the `aspect-ratio` CSS property to the `style` attribute to your images.
+When using blurry placeholders without explicit `width` and `height` attributes, the browser doesn't know the image dimensions until it loads, causing Cumulative Layout Shift (CLS). Setting the `aspect-ratio` CSS property reserves the correct space before the full-quality image loads.
 
-By setting the aspect ratio for your blurry placeholders, you can:
+This technique is especially important for:
 
-- Prevent layout shifts as the full-quality image loads.
-- Ensure that the image container maintains its dimensions even before the full-quality image is loaded.
+- Preventing CLS and improving Core Web Vitals scores
+- Maintaining consistent layouts during image loading
+- Supporting responsive images where dimensions vary by viewport
 
 ## Usage
 

docs/advanced/build-flags.md

@@ -1,8 +1,8 @@
 # Build Flags
 
-This guide will focus on build flags to enable bundlers like [Rollup](https://rollupjs.org) to tree-shake features that are not used in your project.
+unlazy uses build-time flags to enable tree-shaking of unused features, reducing bundle size. Bundlers replace these flags at build time, allowing dead code elimination for features your project doesn't use.
 
-Most bundlers provide a `define` option to set build flags:
+Common bundlers support the `define` option for setting build flags:
 
 - [Vite](https://vitejs.dev/config/shared-options.html#define)
 - [@rollup/plugin-replace](https://www.npmjs.com/package/@rollup/plugin-replace)
@@ -26,16 +26,17 @@ export default defineConfig({
 
 ## Disable Hash Decoding <Badge type="info" text="^0.10.0" />
 
-unlazy ships with the [BlurHash](/placeholders/blurhash) and [ThumbHash](/placeholders/thumbhash) decoding algorithms to decode the hash values into images.
+unlazy includes [BlurHash](/placeholders/blurhash) and [ThumbHash](/placeholders/thumbhash) decoding algorithms (from `fast-blurhash` and `thumbhash` packages). If your project doesn't use hash-based placeholders, you can exclude these dependencies entirely:
 
-In case your project does not use these placeholders, you can disable the hash decoding algorithms to reduce the bundle size. Use the following build flags to tree-shake the hash decoding algorithms:
+- `__UNLAZY_HASH_DECODING__`: Set to `false` to tree-shake hash decoding code. Default is `true`.
 
-- `__UNLAZY_HASH_DECODING__`: This flag is set to `true` by default.
+When disabled, the bundler removes:
+- BlurHash and ThumbHash decoding libraries
+- Hash-related code paths in `lazyLoad()`
+- Associated dependencies from the final bundle
 
 ::: warning
-This will only tree-shake the BlurHash and ThumbHash decoding algorithms when using the [`lazyLoad`](/api/lazy-load) method.
-
-If you use either `unlazy/blurhash` or `unlazy/thumbhash` sub-path imports directly, the decoding algorithms will still be bundled.
+This flag only affects the main entry point. If you directly import `unlazy/blurhash` or `unlazy/thumbhash`, those modules will still be bundled regardless of this flag.
 :::
 
 ## Disable Client Logging <Badge type="info" text="^0.10.2" />

docs/api/auto-sizes.md

@@ -1,6 +1,8 @@
 # `autoSizes`
 
-The `autoSizes` function calculates the sizes attribute for a CSS selector, a DOM element, a list of DOM elements, or an array of DOM elements if the `data-sizes` attribute is set to `auto`.
+The `autoSizes` function calculates and sets the `sizes` attribute based on the current display width of image or source elements when `data-sizes="auto"` is present.
+
+The calculation uses the element's rendered width (`element.offsetWidth`) to determine the appropriate value for the `sizes` attribute, enabling browsers to select the optimal image from a `srcset`.
 
 To lazy load images, refer to the [`lazyLoad`](/api/lazy-load) method.
 

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

@@ -1,13 +1,18 @@
 # `createPngDataUri`
 
-Especially when using a server-side rendering framework like [Nuxt](https://nuxt.com), you might want to generate the placeholder images for the `src` attribute during SSR. This can be done with the `createPngDataUri` function:
+Creates a PNG data URI from a BlurHash string for server-side rendering. This function decodes the BlurHash into RGBA pixel data and encodes it as a base64 PNG data URI.
 
 ```ts
 import { createPngDataUri } from 'unlazy/blurhash'
 
-const pngDataUri = createPngDataUri(blurhash)
+const pngDataUri = createPngDataUri(blurhash, {
+  ratio: 16 / 9,
+  size: 32
+})
 ```
 
+The function uses the `fast-blurhash` library for decoding and generates a compact PNG representation suitable for inlining in HTML.
+
 ## Type Declarations
 
 ```ts

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

@@ -0,0 +1,73 @@
+# `createPlaceholderFromHash`
+
+Generates a PNG data URI placeholder from a BlurHash or ThumbHash string. This function is used internally by [`lazyLoad`](/api/lazy-load) but can also be called directly for custom implementations.
+
+## 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
+```
+
+## Parameters
+
+The function accepts an options object with the following properties:
+
+- `image`: If provided, the function extracts the hash from `data-blurhash` or `data-thumbhash` attributes and calculates the aspect ratio from the element's dimensions
+- `hash`: The hash string to decode. If both `image` and `hash` are provided, `hash` takes precedence
+- `hashType`: Specifies whether the hash is a `blurhash` or `thumbhash`. Default is `blurhash`. If `image` is provided, the type is determined from the presence of `data-blurhash` or `data-thumbhash` attributes
+- `size`: The size of the longer edge for BlurHash decoding. Default is `32`. This parameter is ignored for ThumbHash
+- `ratio`: The aspect ratio (width divided by height) for BlurHash. If `image` is provided, this is calculated automatically from the element's dimensions
+
+## Return Value
+
+Returns a PNG data URI string if the hash is successfully decoded, or `undefined` if:
+- No hash is provided
+- The hash decoding fails
+- The required decoding library is not available
+
+## Examples
+
+Using with a hash string:
+
+```ts
+import { createPlaceholderFromHash } from 'unlazy'
+
+const placeholder = createPlaceholderFromHash({
+  hash: 'LKO2:N%2Tw=w]~RBVZRi};RPxuwH',
+  hashType: 'blurhash',
+  size: 32,
+  ratio: 16 / 9
+})
+```
+
+Using with an image element:
+
+```ts
+import { createPlaceholderFromHash } from 'unlazy'
+
+const img = document.querySelector('img')
+const placeholder = createPlaceholderFromHash({
+  image: img
+})
+
+if (placeholder) {
+  img.src = placeholder
+}
+```
+
+::: tip
+For server-side rendering, use the specialized functions instead:
+- [`createPngDataUri`](/api/blurhash-create-png-data-uri) from `unlazy/blurhash`
+- [`createPngDataUri`](/api/thumbhash-create-png-data-uri) from `unlazy/thumbhash`
+:::

docs/api/index.md

@@ -2,9 +2,10 @@
 
 unlazy provides a number of methods to help you with lazy loading images. The following methods are available:
 
-- [`lazyLoad`](/api/lazy-load) – Lazy load images
+- [`lazyLoad`](/api/lazy-load) – Lazy load images with automatic placeholder generation
 - [`autoSizes`](/api/auto-sizes) – Automatically calculate the `sizes` attribute
-- [`loadImage`](/api/load-image) – Manually load an image
+- [`loadImage`](/api/load-image) – Manually load an image before it enters the viewport
+- [`createPlaceholderFromHash`](/api/create-placeholder-from-hash) – Generate PNG data URI from BlurHash or ThumbHash
 
 ## Server-Side Rendering
 

docs/api/lazy-load.md

@@ -15,12 +15,24 @@ The `lazyLoad` function takes a CSS selector, a DOM element, a list of DOM eleme
 
 ## Options
 
-Options can be passed to the function to customize its behavior. These options include:
+Options can be passed to the function to customize its behavior:
 
-- `hash`: Whether to use a hash for generating a blurry placeholder. Default is `true`.
-- `hashType`: The type of hash to use for generating a blurry placeholder. Possible values are `blurhash` and `thumbhash`. Default is `blurhash`.
-- `placeholderSize`: The size of the placeholder. Applies only to BlurHash strings. Default is `32`.
-- `onImageLoad`: A callback function that will be executed when the image is loaded.
+- `hash`: Whether to use a hash for generating a blurry placeholder. Can be a boolean or a string. Default is `true`. If `thumbhash` is provided, it takes precedence over `blurhash`.
+- `hashType`: The type of hash to use. Possible values are `blurhash` and `thumbhash`. Default is `blurhash`.
+- `placeholderSize`: The size of the longer edge for BlurHash decoding. Default is `32`. Ignored for ThumbHash.
+- `updateSizesOnResize`: Whether to update the `sizes` attribute on window resize events using a debounced ResizeObserver. Default is `false`.
+- `onImageLoad`: A callback function invoked when an image loads successfully.
+
+## Return Value
+
+The function returns a cleanup function that removes all event listeners and ResizeObservers created by `lazyLoad`. Call this function when images are no longer needed to prevent memory leaks:
+
+```ts
+const cleanup = lazyLoad()
+
+// Later, when cleaning up
+cleanup()
+```
 
 ## Type Declarations
 

docs/api/load-image.md

@@ -1,6 +1,14 @@
 # `loadImage`
 
-The `loadImage` function takes an `HTMLImageElement` and an optional callback function to execute when the image is loaded. It updates the `src`, `srcset`, and `sizes` attributes of the image and its parent picture element's sources, if applicable.
+The `loadImage` function programmatically loads an image by updating its attributes from data attributes. It handles both standalone `<img>` elements and images within `<picture>` elements.
+
+The function performs the following operations:
+
+1. If the image is inside a `<picture>` element, updates all `<source>` elements by converting their `data-srcset` and `data-sizes` attributes to standard attributes
+2. Preloads the image in a temporary element to ensure proper loading
+3. Calculates the `sizes` attribute if `data-sizes="auto"` is set
+4. Swaps `data-src` and `data-srcset` to their standard counterparts
+5. Invokes the optional callback when loading completes
 
 ## Type Declarations
 

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

@@ -1,13 +1,15 @@
 # `createPngDataUri`
 
-Especially when using a server-side rendering framework like [Nuxt](https://nuxt.com), you might want to generate the placeholder images for the `src` attribute during SSR. This can be done with the `createPngDataUri` function:
+Creates a PNG data URI from a ThumbHash string for server-side rendering. This function decodes the base64-encoded ThumbHash into RGBA pixel data and encodes it as a base64 PNG data URI.
 
 ```ts
 import { createPngDataUri } from 'unlazy/thumbhash'
 
 const pngDataUri = createPngDataUri(thumbhash)
 ```
 
+The function handles base64-url encoding by converting `-` to `+` and `_` to `/` before decoding. It uses the `thumbhash` library for decoding, which automatically determines the aspect ratio from the hash itself.
+
 ## Type Declarations
 
 ```ts

docs/guide/index.md

@@ -10,9 +10,17 @@ Although the `loading="lazy"` attribute is supported in all major browsers, it i
 
 ## How It Works
 
-unlazy processes all images with a `loading="lazy"` attribute, calculates the sizes attribute if necessary, and checks if the image has a blurry placeholder (given that either a `data-src` or `data-srcset` attribute is present).
+unlazy enhances the native `loading="lazy"` attribute by processing images and managing their lifecycle:
 
-unlazy intends to offer a good balance between performance and user experience and works well for specific use cases where blurry placeholders are the preferred method for image loading.
+1. **Data Attribute Processing**: Uses `data-src`, `data-srcset`, and `data-sizes` attributes which are swapped to standard attributes when images load. This prevents browsers from eagerly loading images before they enter the viewport.
+
+2. **Placeholder Generation**: Decodes [BlurHash](/placeholders/blurhash) or [ThumbHash](/placeholders/thumbhash) strings (via `data-blurhash` or `data-thumbhash` attributes) into PNG data URIs for placeholders.
+
+3. **Chrome Workaround**: Generates unique indexed SVG placeholders to prevent Chrome's aggressive image loading behavior that can trigger load events prematurely.
+
+4. **Automatic Sizes Calculation**: Calculates the `sizes` attribute based on the image's display width when `data-sizes="auto"` is set.
+
+unlazy leverages native browser APIs rather than replacing them, offering a good balance between performance and user experience for image-heavy applications.
 
 ## SEO