astro-lqip 1.1.0 → 1.2.2

package/README.md

@@ -1,5 +1,5 @@
 <a href="https://github.com/felixicaza/astro-lqip/">
-  <img src="./assets/cover.png" alt="Astro LQIP Cover" width="896" height="280" style="object-fit: cover" />
+  <img src="./assets/logo.png" alt="Astro LQIP Logo" width="200" height="200" />
 </a>
 
 # 🖼️ astro-lqip
@@ -7,9 +7,7 @@
 [![GitHub Release](https://img.shields.io/github/v/release/felixicaza/astro-lqip?logo=npm)](https://www.npmjs.com/package/astro-lqip)
 [![GitHub License](https://img.shields.io/github/license/felixicaza/astro-lqip)](https://github.com/felixicaza/astro-lqip/blob/main/LICENSE)
 
-A integration built over the native Astro component that generates low quality image placeholders (LQIP) for your images.
-
-[See Demo.](https://astro-lqip.web.app/)
+Native extended Astro component for generating low quality image placeholders (LQIP).
 
 ## ⬇️ Installation
 
@@ -33,29 +31,57 @@ yarn add astro-lqip
 
 ## 🚀 Usage
 
-In your current Astro project, just replace the native Astro `<Picture>` component import with the one provided by this package.
+In your current Astro project, just replace the import of the native Astro `<Picture />` component with the one provided by [astro-lqip](https://www.npmjs.com/package/astro-lqip).
+
+```diff
+- import { Picture } from 'astro:assets';
++ import { Picture } from 'astro-lqip/components';
+```
+
+Example:
 
 ```astro
 ---
-// import { Picture } from 'astro:assets';
-import { Picture } from 'astro-lqip/components';
+import { Picture } from 'astro-lqip/components'
+import image from './path/to/image.png'
+---
+
+<Picture src={image} alt="Cover Image" width={220} height={220} />
+```
 
-import image from './path/to/image.jpg';
+## ⚙️ Props
+
+This `<Picture />` component supports all the props of the [native Astro component](https://docs.astro.build/en/reference/modules/astro-assets/#picture-properties), but adds a couple of props for LQIP management:
+
+- `lqip`: The LQIP type to use. It can be one of the following:
+  - `base64`: Generates a Base64-encoded LQIP image. (default option)
+  - `color`: Generates a solid color placeholder. Not compatible with `lqipSize`.
+  - `css`: Generates a CSS-based LQIP image.
+  - `svg`: Generates an SVG-based LQIP image.
+- `lqipSize`: The size of the LQIP image, which can be any number from `4` to `64`. (default is 4)
+
+> [!WARNING]
+> A major size in the lqipSize prop can significantly impact the performance of your application.
+
+Example:
+
+```astro
+---
+import { Picture } from 'astro-lqip/components'
+import image from './path/to/image.png'
 ---
 
-<Picture
-  src={image}
-  alt="Description of the image"
-/>
+<Picture src={image} alt="Cover Image" width={220} height={220} lqip="css" lqipSize={7} />
 ```
 
 ## 📝 ToDo
 
 - [ ] Add support for Image component.
-- [ ] Add support for more lqip techniques.
+- [x] Add support for more lqip techniques.
 - [ ] Test for remote images.
 - [ ] Optimize current CSS usage.
-- [ ] Improve demo page.
+- [x] Improve docs page.
+- [ ] Test support for SSR mode.
 
 ## 💡 Knowledge
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-lqip",
-  "version": "1.1.0",
+  "version": "1.2.2",
   "description": "Native extended Astro component for generating low quality image placeholders (LQIP).",
   "keywords": [
     "astro",
@@ -36,20 +36,20 @@
     "plaiceholder": "3.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.30.0",
-    "@typescript-eslint/parser": "8.35.0",
-    "astro": "5.10.1",
+    "@eslint/js": "9.30.1",
+    "@typescript-eslint/parser": "8.36.0",
+    "astro": "5.11.0",
     "bumpp": "10.2.0",
-    "eslint": "9.30.0",
+    "eslint": "9.30.1",
     "eslint-plugin-astro": "1.3.1",
     "eslint-plugin-jsonc": "2.20.1",
     "eslint-plugin-jsx-a11y": "6.10.2",
-    "eslint-plugin-package-json": "0.42.0",
+    "eslint-plugin-package-json": "0.44.1",
     "eslint-plugin-yml": "1.18.0",
-    "globals": "16.2.0",
+    "globals": "16.3.0",
     "jiti": "2.4.2",
     "nano-staged": "0.8.0",
-    "neostandard": "0.12.1",
+    "neostandard": "0.12.2",
     "simple-git-hooks": "2.13.0"
   },
   "peerDependencies": {

package/src/components/Picture.astro

@@ -1,59 +1,49 @@
 ---
-import { join } from 'node:path'
-import { readFile } from 'node:fs/promises'
+import type { Props } from '../types'
 
-import { getPlaiceholder } from 'plaiceholder'
+import { PREFIX } from '../constants'
 
-import { Picture as PictureComponent } from 'astro:assets'
-import type { Props as PictureProps } from 'astro/components/Picture.astro'
+import { resolveImageMetadata } from '../utils/resolveImageMetadata'
+import { renderSVGNode } from '../utils/renderSVGNode'
+import { getLqipStyle } from '../utils/getLqipStyle'
+import { getLqip } from '../utils/getLqip'
 
-type Props = PictureProps
+import { Picture as PictureComponent } from 'astro:assets'
 
-const { class: className, ...props } = Astro.props as Props
+const { class: className, lqip = 'base64', lqipSize = 4, pictureAttributes = {}, ...props } = Astro.props as Props
 
-const PREFIX = '[astro-lqip]'
+const isDevelopment = import.meta.env.MODE === 'development'
 
 const imageMetadata = await resolveImageMetadata(props.src)
-const lqip = await getLqip(imageMetadata)
+const lqipImage = await getLqip(imageMetadata, isDevelopment, lqip, lqipSize)
 
-async function resolveImageMetadata(src: any) {
-  if (typeof src === 'string') return null
-  if ('then' in src && typeof src.then === 'function') return (await src).default
-  if ('src' in src) return src
-  return null
-}
+let svgHTML = ''
 
-async function tryGenerateLqip(filePath: string, errorPrefix: string, isDevelopment: boolean) {
-  try {
-    const buffer = await readFile(filePath)
-    const { base64 } = await getPlaiceholder(buffer)
-
-    if (isDevelopment) {
-      console.log(`${PREFIX} LQIP successfully generated!`)
-    } else {
-      console.log(`${PREFIX} LQIP successfully generated for:`, imageMetadata.src)
-    }
-    return base64
-  } catch (err) {
-    console.error(`${errorPrefix} Error generating LQIP in:`, filePath, '\n', err)
-    return undefined
-  }
+if (lqip === 'svg' && Array.isArray(lqipImage)) {
+  svgHTML = renderSVGNode(lqipImage as [string, Record<string, any>, any[]])
 }
 
-async function getLqip(imageMetadata: any) {
-  if (!imageMetadata?.src) return undefined
+const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
 
-  const isDevelopment = import.meta.env.MODE === 'development'
+const forbiddenVars = ['--lqip-background', '--z-index', '--opacity']
+const styleProps = pictureAttributes.style ?? {}
 
-  if (isDevelopment && imageMetadata.src.startsWith('/@fs/')) {
-    const filePath = imageMetadata.src.replace(/^\/@fs/, '').split('?')[0]
-    return await tryGenerateLqip(filePath, PREFIX, isDevelopment)
+for (const key of Object.keys(styleProps)) {
+  if (forbiddenVars.includes(key)) {
+    console.warn(
+      `${PREFIX} The CSS variable “${key}” should not be passed in \`pictureAttributes.style\` because it can override the functionality of LQIP.`
+    )
   }
+}
 
-  if (!isDevelopment && imageMetadata.src.startsWith('/_astro/')) {
-    const buildPath = join(process.cwd(), 'dist', imageMetadata.src)
-    return await tryGenerateLqip(buildPath, PREFIX, isDevelopment)
-  }
+const combinedStyle = {
+  ...styleProps,
+  ...lqipStyle
+}
+
+const combinedPictureAttributes = {
+  ...pictureAttributes,
+  style: combinedStyle
 }
 ---
 
@@ -91,6 +81,6 @@ async function getLqip(imageMetadata: any) {
 <PictureComponent
   {...props}
   class={className}
-  pictureAttributes={{ style: { '--lqip-background': `url('${lqip}')` } }}
+  pictureAttributes={{ ...combinedPictureAttributes }}
   onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"
 />

package/src/constants/index.ts

@@ -0,0 +1 @@
+export const PREFIX = '[astro-lqip]'

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './plaiceholder.type'
+export * from './lqip.type'
+export * from './props.type'

package/src/types/lqip.type.ts

@@ -0,0 +1 @@
+export type LqipType = 'color' | 'css' | 'base64' | 'svg'

package/src/types/plaiceholder.type.ts

@@ -0,0 +1,3 @@
+import type { GetPlaiceholderReturn } from 'plaiceholder'
+
+export type GetSVGReturn = GetPlaiceholderReturn['svg']

package/src/types/props.type.ts

@@ -0,0 +1,18 @@
+import type { Props as PictureProps } from 'astro/components/Picture.astro'
+
+import type { LqipType } from './lqip.type'
+
+export type Props = PictureProps & {
+  /**
+   * LQIP type.
+   * This can be 'color', 'css', 'svg' or 'base64'.
+   * The default value is 'base64'.
+   */
+  lqip?: LqipType
+  /**
+   * Size of the LQIP image in pixels.
+   * This value should be between 4 and 64.
+   * The default value is 4.
+   */
+  lqipSize?: number
+}

package/src/utils/generateLqip.ts

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises'
+
+import type { GetSVGReturn, LqipType } from '../types'
+
+import { PREFIX } from '../constants'
+
+import { getPlaiceholder } from 'plaiceholder'
+
+export async function generateLqip(filePath: string, isDevelopment: boolean, lqipType: LqipType, lqipSize: number) {
+  try {
+    const buffer = await readFile(filePath)
+    const plaiceholderResult = await getPlaiceholder(buffer, { size: lqipSize })
+    let lqipValue: string | GetSVGReturn | undefined
+
+    switch (lqipType) {
+      case 'color':
+        lqipValue = plaiceholderResult.color?.hex
+        break
+      case 'css':
+        lqipValue = typeof plaiceholderResult.css === 'object' && plaiceholderResult.css.backgroundImage
+          ? plaiceholderResult.css.backgroundImage
+          : String(plaiceholderResult.css)
+        break
+      case 'svg':
+        lqipValue = plaiceholderResult.svg
+        break
+      case 'base64':
+      default:
+        lqipValue = plaiceholderResult.base64
+        break
+    }
+
+    if (isDevelopment) {
+      console.log(`${PREFIX} LQIP (${lqipType}) successfully generated!`)
+    } else {
+      console.log(`${PREFIX} LQIP (${lqipType}) successfully generated for:`, filePath)
+    }
+
+    return lqipValue
+  } catch (err) {
+    console.error(`${PREFIX} Error generating LQIP (${lqipType}) in:`, filePath, '\n', err)
+    return undefined
+  }
+}

package/src/utils/getLqip.ts

@@ -0,0 +1,20 @@
+import { join } from 'node:path'
+
+import type { ImageMetadata } from 'astro'
+import type { LqipType } from '../types'
+
+import { generateLqip } from './generateLqip'
+
+export async function getLqip(imageMetadata: ImageMetadata, envMode: boolean, lqipType: LqipType, lqipSize: number) {
+  if (!imageMetadata?.src) return undefined
+
+  if (envMode && imageMetadata.src.startsWith('/@fs/')) {
+    const filePath = imageMetadata.src.replace(/^\/@fs/, '').split('?')[0]
+    return await generateLqip(filePath, envMode, lqipType, lqipSize)
+  }
+
+  if (!envMode && imageMetadata.src.startsWith('/_astro/')) {
+    const buildPath = join(process.cwd(), 'dist', imageMetadata.src)
+    return await generateLqip(buildPath, envMode, lqipType, lqipSize)
+  }
+}

package/src/utils/getLqipStyle.ts

@@ -0,0 +1,17 @@
+import type { GetSVGReturn, LqipType } from '../types'
+
+export function getLqipStyle(lqipType: LqipType, lqipImage: string | GetSVGReturn | undefined, svgHTML: string = '') {
+  if (!lqipImage) return {}
+
+  switch (lqipType) {
+    case 'css':
+      return { '--lqip-background': lqipImage }
+    case 'svg':
+      return { '--lqip-background': `url('data:image/svg+xml;utf8,${encodeURIComponent(svgHTML)}')` }
+    case 'color':
+      return { '--lqip-background': lqipImage }
+    case 'base64':
+    default:
+      return { '--lqip-background': `url('${lqipImage}')` }
+  }
+}

package/src/utils/renderSVGNode.ts

@@ -0,0 +1,22 @@
+function styleToString(style: Record<string, string>) {
+  return Object.entries(style)
+    .map(([key, val]) => `${key.replace(/([A-Z])/g, '-$1').toLowerCase()}:${val}`)
+    .join(';')
+}
+
+export function renderSVGNode([tag, attrs, children]: [string, Record<string, any>, any[]]): string {
+  let attrString = ''
+  for (const [k, v] of Object.entries(attrs || {})) {
+    if (k === 'style') {
+      attrString += ` style="${styleToString(v)}"`
+    } else {
+      attrString += ` ${k}="${v}"`
+    }
+  }
+
+  if (children && children.length > 0) {
+    return `<${tag}${attrString}>${children.map(renderSVGNode).join('')}</${tag}>`
+  } else {
+    return `<${tag}${attrString} />`
+  }
+}

package/src/utils/resolveImageMetadata.ts

@@ -0,0 +1,6 @@
+export async function resolveImageMetadata(src: any) {
+  if (typeof src === 'string') return null
+  if ('then' in src && typeof src.then === 'function') return (await src).default
+  if ('src' in src) return src
+  return null
+}