astro-lqip 1.2.1 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-<a href="https://github.com/felixicaza/astro-lqip/">
+<a href="https://astro-lqip.web.app/">
   <img src="./assets/logo.png" alt="Astro LQIP Logo" width="200" height="200" />
 </a>
 
@@ -7,7 +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)
 
-Native extended Astro component for generating low quality image placeholders (LQIP).
+Native extended Astro components for generating low quality image placeholders (LQIP).
 
 ## ⬇️ Installation
 
@@ -31,27 +31,39 @@ yarn add astro-lqip
 
 ## 🚀 Usage
 
-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).
+In your current Astro project, just replace the import of the native Astro `<Image>` or `<Picture>` components with the ones provided by [astro-lqip](https://astro-lqip.web.app/).
+
+### Image
+
+```diff
+- import { Image } from 'astro:assets';
++ import { Image } from 'astro-lqip/components';
+```
+
+### Picture
 
 ```diff
 - import { Picture } from 'astro:assets';
-+import { Picture } from 'astro-lqip/components';
++ import { Picture } from 'astro-lqip/components';
 ```
 
 Example:
 
 ```astro
 ---
-import { Picture } from 'astro-lqip/components'
+import { Image, Picture } from 'astro-lqip/components'
+
 import image from './path/to/image.png'
+import otherImage from './path/to/other-image.png'
 ---
 
-<Picture src={image} alt="Cover Image" width={220} height={220} />
+<Image src={image} alt="Cover Image" width={220} height={220} />
+<Picture src={otherImage} alt="Other cover Image" width={220} height={220} />
 ```
 
 ## ⚙️ 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:
+Both `<Image>` and `<Picture>` components support all the props of the [native Astro components](https://docs.astro.build/en/reference/modules/astro-assets/), 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)
@@ -67,24 +79,31 @@ Example:
 
 ```astro
 ---
-import { Picture } from 'astro-lqip/components'
+import { Image, Picture } from 'astro-lqip/components'
+
 import image from './path/to/image.png'
+import otherImage from './path/to/other-image.png'
 ---
 
-<Picture src={image} alt="Cover Image" width={220} height={220} lqip="css" lqipSize={7} />
+<Image src={image} alt="Cover Image" width={220} height={220} lqip="svg" lqipSize={10} />
+<Picture src={otherImage} alt="Other cover Image" width={220} height={220} lqip="css" lqipSize={7} />
 ```
 
+> [!TIP]
+> For the `<Image>` component, a `parentAttributes` prop similar to `pictureAttributes` has been added.
+
 ## 📝 ToDo
 
-- [ ] Add support for Image component.
+- [x] Add support for Image component.
 - [x] Add support for more lqip techniques.
 - [ ] Test for remote images.
 - [ ] Optimize current CSS usage.
 - [x] Improve docs page.
+- [ ] Test support for SSR mode.
 
 ## 💡 Knowledge
 
-Since this integration is built on top of Astro's native `<Picture>` component, you can refer to the [Astro documentation](https://docs.astro.build/en/guides/images/#picture-) for more information on how to use it.
+Since this integration is built on top of Astro native `<Image>` and `<Picture>` components, you can refer to the [Astro documentation](https://docs.astro.build/en/guides/images/) for more information on how to use it.
 
 ## 🤝 Contributing
 If you wish to contribute to this project, you can do so by reading the [contribution guide](https://github.com/felixicaza/astro-lqip/blob/main/CONTRIBUTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-lqip",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Native extended Astro component for generating low quality image placeholders (LQIP).",
   "keywords": [
     "astro",
@@ -36,21 +36,21 @@
     "plaiceholder": "3.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.30.0",
-    "@typescript-eslint/parser": "8.35.0",
-    "astro": "5.10.1",
-    "bumpp": "10.2.0",
-    "eslint": "9.30.0",
+    "@eslint/js": "9.33.0",
+    "@typescript-eslint/parser": "8.39.1",
+    "astro": "5.12.9",
+    "bumpp": "10.2.3",
+    "eslint": "9.33.0",
     "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.53.0",
     "eslint-plugin-yml": "1.18.0",
-    "globals": "16.2.0",
-    "jiti": "2.4.2",
+    "globals": "16.3.0",
+    "jiti": "2.5.1",
     "nano-staged": "0.8.0",
-    "neostandard": "0.12.1",
-    "simple-git-hooks": "2.13.0"
+    "neostandard": "0.12.2",
+    "simple-git-hooks": "2.13.1"
   },
   "peerDependencies": {
     "astro": ">=3.3.0"

package/src/components/Image.astro

@@ -0,0 +1,95 @@
+---
+import type { LocalImageProps, RemoteImageProps } from 'astro:assets'
+import type { Props as LqipProps } from '../types'
+import type { HTMLAttributes } from 'astro/types'
+
+import { PREFIX } from '../constants'
+
+import { resolveImageMetadata } from '../utils/resolveImageMetadata'
+import { renderSVGNode } from '../utils/renderSVGNode'
+import { getLqipStyle } from '../utils/getLqipStyle'
+import { getLqip } from '../utils/getLqip'
+
+import { Image as ImageComponent } from 'astro:assets'
+
+type Props = (LocalImageProps | RemoteImageProps) & LqipProps & {
+  parentAttributes?: HTMLAttributes<'div'>
+}
+
+const { class: className, lqip = 'base64', lqipSize = 4, parentAttributes = {}, ...props } = Astro.props as Props
+
+const isDevelopment = import.meta.env.MODE === 'development'
+
+const imageMetadata = await resolveImageMetadata(props.src)
+const lqipImage = await getLqip(imageMetadata, isDevelopment, lqip, lqipSize)
+
+let svgHTML = ''
+
+if (lqip === 'svg' && Array.isArray(lqipImage)) {
+  svgHTML = renderSVGNode(lqipImage as [string, Record<string, any>, any[]])
+}
+
+const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
+
+const forbiddenVars = ['--lqip-background', '--z-index', '--opacity']
+const styleProps = parentAttributes.style ?? {}
+
+for (const key of Object.keys(styleProps)) {
+  if (forbiddenVars.includes(key)) {
+    console.warn(
+      `${PREFIX} The CSS variable “${key}” should not be passed in \`parentAttributes.style\` because it can override the functionality of LQIP.`
+    )
+  }
+}
+
+const combinedStyle = {
+  ...styleProps,
+  ...lqipStyle
+}
+
+const combinedParentAttributes = {
+  ...parentAttributes,
+  style: combinedStyle
+}
+---
+
+<style is:inline>
+  div[data-astro-lqip] {
+    --opacity: 1;
+    --z-index: 0;
+
+    position: relative;
+    display: inline-block;
+    width: fit-content;
+    height: fit-content;
+  }
+
+  div[data-astro-lqip]::after {
+    content: "";
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    pointer-events: none;
+    transition: opacity 1s;
+    opacity: var(--opacity);
+    z-index: var(--z-index);
+    background: var(--lqip-background);
+    background-size: cover;
+    background-position: 50% 50%;
+  }
+
+  div[data-astro-lqip] img {
+    z-index: 1;
+    position: relative;
+    overflow: hidden;
+  }
+</style>
+
+<div class={className} data-astro-lqip {...combinedParentAttributes}>
+  <ImageComponent
+    {...props}
+    class={className}
+    onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"
+  />
+</div>

package/src/components/Picture.astro

@@ -1,5 +1,8 @@
 ---
-import type { Props } from '../types'
+import type { Props as AstroPictureProps } from 'astro/components/Picture.astro'
+import type { Props as LqipProps } from '../types'
+
+import { PREFIX } from '../constants'
 
 import { resolveImageMetadata } from '../utils/resolveImageMetadata'
 import { renderSVGNode } from '../utils/renderSVGNode'
@@ -8,7 +11,9 @@ import { getLqip } from '../utils/getLqip'
 
 import { Picture as PictureComponent } from 'astro:assets'
 
-const { class: className, lqip = 'base64', lqipSize = 4, ...props } = Astro.props as Props
+type Props = AstroPictureProps & LqipProps
+
+const { class: className, lqip = 'base64', lqipSize = 4, pictureAttributes = {}, ...props } = Astro.props as Props
 
 const isDevelopment = import.meta.env.MODE === 'development'
 
@@ -22,10 +27,31 @@ if (lqip === 'svg' && Array.isArray(lqipImage)) {
 }
 
 const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
+
+const forbiddenVars = ['--lqip-background', '--z-index', '--opacity']
+const styleProps = pictureAttributes.style ?? {}
+
+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.`
+    )
+  }
+}
+
+const combinedStyle = {
+  ...styleProps,
+  ...lqipStyle
+}
+
+const combinedPictureAttributes = {
+  ...pictureAttributes,
+  style: combinedStyle
+}
 ---
 
 <style is:inline>
-  picture {
+  picture[data-astro-lqip] {
     --opacity: 1;
     --z-index: 0;
 
@@ -33,7 +59,7 @@ const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
     display: inline-block;
   }
 
-  picture::after {
+  picture[data-astro-lqip]::after {
     content: "";
     inset: 0;
     width: 100%;
@@ -48,7 +74,7 @@ const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
     background-position: 50% 50%;
   }
 
-  picture img {
+  picture[data-astro-lqip] img {
     z-index: 1;
     position: relative;
     overflow: hidden;
@@ -58,6 +84,6 @@ const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
 <PictureComponent
   {...props}
   class={className}
-  pictureAttributes={{ style: lqipStyle }}
+  pictureAttributes={{ 'data-astro-lqip': '', ...combinedPictureAttributes }}
   onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"
 />

package/src/index.ts

@@ -1 +1,2 @@
 export { default as Picture } from './components/Picture.astro'
+export { default as Image } from './components/Image.astro'

package/src/types/props.type.ts

@@ -1,8 +1,6 @@
-import type { Props as PictureProps } from 'astro/components/Picture.astro'
-
 import type { LqipType } from './lqip.type'
 
-export type Props = PictureProps & {
+export type Props = {
   /**
    * LQIP type.
    * This can be 'color', 'css', 'svg' or 'base64'.