diff --git a/.gitignore b/.gitignore deleted file mode 100644 index cab85ca..0000000 --- a/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -/node_modules -/coverage -*.log -.DS_Store diff --git a/.npmignore b/.npmignore deleted file mode 100644 index 4c9adda..0000000 --- a/.npmignore +++ /dev/null @@ -1,4 +0,0 @@ -./docs -./scripts -./tests -./incoming \ No newline at end of file diff --git a/LICENSE b/LICENSE deleted file mode 100644 index b0e20f5..0000000 --- a/LICENSE +++ /dev/null @@ -1,9 +0,0 @@ -Copyright (c) All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md deleted file mode 100644 index dc27f0f..0000000 --- a/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# osr-package-template - -Package basics \ No newline at end of file diff --git a/package.json b/package.json deleted file mode 100644 index e67de54..0000000 --- a/package.json +++ /dev/null @@ -1,45 +0,0 @@ -{ - "name": "@plastichub/template", - "description": "", - "version": "0.3.1", - "main": "main.js", - "typings": "index.d.ts", - "publishConfig": { - "access": "public" - }, - "bin": { - "osr-bin": "main.js" - }, - "dependencies": { - "@types/node": "^14.17.5", - "@types/yargs": "^17.0.2", - "chalk": "^2.4.1", - "convert-units": "^2.3.4", - "env-var": "^7.0.1", - "typescript": "^4.3.5", - "yargs": "^14.2.3", - "yargs-parser": "^15.0.3" - }, - "scripts": { - "test": "tsc; mocha --full-trace mocha \"spec/**/*.spec.js\"", - "test-with-coverage": "istanbul cover node_modules/.bin/_mocha -- 'spec/**/*.spec.js'", - "lint": "tslint --project=./tsconfig.json", - "build": "tsc -p .", - "dev": "tsc -p . --declaration -w", - "typings": "tsc --declaration", - "docs": "npx typedoc src/index.ts", - "dev-test-watch": "mocha-typescript-watch" - }, - "homepage": "https://git.osr-plastic.org/plastichub/lib-content", - "repository": { - "type": "git", - "url": "https://git.osr-plastic.org/plastichub/lib-content.git" - }, - "engines": { - "node": ">= 14.0.0" - }, - "license": "BSD-3-Clause", - "keywords": [ - "typescript" - ] -} diff --git a/packages/imagetools/.eslintrc.js b/packages/imagetools/.eslintrc.js new file mode 100644 index 0000000..404d101 --- /dev/null +++ b/packages/imagetools/.eslintrc.js @@ -0,0 +1,17 @@ +module.exports = { + root: true, + env: { + node: true, + browser: true, + es2020: true, + }, + parserOptions: { + ecmaVersion: 2022, + sourceType: "module", + }, + plugins: ["unicorn"], + extends: ["eslint:recommended"], + rules: { + "unicorn/prefer-node-protocol": "error", + }, +}; diff --git a/packages/imagetools/.github/workflows/ci.yml b/packages/imagetools/.github/workflows/ci.yml new file mode 100644 index 0000000..8037912 --- /dev/null +++ b/packages/imagetools/.github/workflows/ci.yml @@ -0,0 +1,65 @@ +name: CI +on: + pull_request: + push: + branches: + - main +jobs: + lint: + env: + ASTRO_TELEMETRY_DISABLED: true + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup PNPM + uses: pnpm/action-setup@v2.2.1 + + - name: Setup node + uses: actions/setup-node@v3 + with: + node-version: 16 + cache: "pnpm" + + - name: Install dependencies + run: pnpm install + + - name: Prettier + run: pnpm run format:check + + - name: ESLint + run: pnpm run lint + + test: + name: "Test: ${{ matrix.os }} (node@${{ matrix.node_version }})" + env: + ASTRO_TELEMETRY_DISABLED: true + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + node_version: [14, 16] + include: + - os: windows-latest + node_version: 16 + - os: macos-latest + node_version: 16 + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup PNPM + uses: pnpm/action-setup@v2.2.1 + + - name: Setup node@${{ matrix.node_version }} + uses: actions/setup-node@v3 + with: + node-version: ${{ matrix.node_version }} + cache: "pnpm" + - name: Install dependencies + run: pnpm install + + - name: Test + run: pnpm --filter astro-imagetools run test diff --git a/packages/imagetools/.gitignore b/packages/imagetools/.gitignore new file mode 100644 index 0000000..7ce5e2f --- /dev/null +++ b/packages/imagetools/.gitignore @@ -0,0 +1,20 @@ +# dependencies +node_modules/ + +# build output +dist/ + +# logs +*.log + +# npm +package-lock.json + +# macOS-specific files +.DS_Store + +# env +*.env + +# astro-imagetools +packages/astro-imagetools/astroViteConfigs.js diff --git a/packages/imagetools/.npmignore b/packages/imagetools/.npmignore new file mode 100644 index 0000000..4f257ea --- /dev/null +++ b/packages/imagetools/.npmignore @@ -0,0 +1,4 @@ +*.test.ts +test-fixtures +astroViteConfigs.js +vitest.config.ts diff --git a/packages/imagetools/.npmrc b/packages/imagetools/.npmrc new file mode 100644 index 0000000..0cc653b --- /dev/null +++ b/packages/imagetools/.npmrc @@ -0,0 +1,2 @@ +## force pnpm to hoist +shamefully-hoist = true \ No newline at end of file diff --git a/packages/imagetools/.prettierignore b/packages/imagetools/.prettierignore new file mode 100644 index 0000000..2a056f3 --- /dev/null +++ b/packages/imagetools/.prettierignore @@ -0,0 +1,2 @@ +pnpm-lock.yaml +demo/dist diff --git a/packages/imagetools/.prettierrc b/packages/imagetools/.prettierrc new file mode 100644 index 0000000..8008794 --- /dev/null +++ b/packages/imagetools/.prettierrc @@ -0,0 +1,9 @@ +{ + "overrides": [ + { + "files": "**/*.astro", + "options": { "parser": "astro" } + } + ], + "plugins": ["prettier-plugin-astro"] +} diff --git a/packages/imagetools/LICENSE b/packages/imagetools/LICENSE new file mode 100644 index 0000000..a4be0c4 --- /dev/null +++ b/packages/imagetools/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2022 Rafid Muhymin Wafi + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/imagetools/README.md b/packages/imagetools/README.md new file mode 100644 index 0000000..eda0dbe --- /dev/null +++ b/packages/imagetools/README.md @@ -0,0 +1,39 @@ +# **Astro ImageTools** + +**Astro ImageTools** is a collection of tools for optimizing images, background images, and generating responsive images for the **Astro JS** framework. + +## Features + +Below is a short list of features that **Astro ImageTools** offers. For more information, please see component-specific or API-specific documentation. + +- ✅ **Regular Image Optimization** (`` and ``) +- ✅ **Background Image Optimization** +- ✅ **Responsive Images** +- ✅ **Simple and intuitive Art Direction API** +- ✅ **Lazy Loading** +- ✅ **Programmatic APIs** +- ✅ **Asynchronous Decoding** +- ✅ **Unique Breakpoints Calculation** +- ✅ **Preloading for urgent images** +- ✅ **SVG Tracing and Posterization** +- ✅ **100% Scoped CSS** +- ✅ **Four kind of Layouts: `constrained`, `fixed`, `fullWidth` & `fill`** +- ✅ **Three kind of Placeholder Images: `blurred`, `dominantColor` & `tracedSVG`** +- ✅ **Long list of supported Image Formats** +- ✅ **Long List of supported Configuration Options** +- ✅ **Supports Remote Images and Data URIs too** +- ✅ **Support for _`sharp`less_ Environments** +- ✅ **Both Memory-based and FS-based Caching for better Performance** +- ✅ **Respects to _Semantics of HTML_ as much as possible** + +## Getting Started + +To get started with **Astro ImageTools**, first check out the [Installation](https://astro-imagetools-docs.vercel.app/en/installation) documentation for instructions on how to install the `astro-imagetools` package. + +If you are looking for the available components and APIs, please check out the [Components and APIs](https://astro-imagetools-docs.vercel.app/en/components-and-apis) documentation. + +If you want to view live examples of the components, APIs, layouts, and placeholder images, check out the [Astro ImageTools Demo](https://astro-imagetools-demo.vercel.app/) website. + +If you want to report any issues or have found a missing feature, please report it on [GitHub](https://github.com/RafidMuhymin/astro-imagetools/)! + +Good luck out there, Astronaut. 🧑‍🚀 diff --git a/packages/imagetools/api/importImage.d.ts b/packages/imagetools/api/importImage.d.ts new file mode 100644 index 0000000..bb0bb97 --- /dev/null +++ b/packages/imagetools/api/importImage.d.ts @@ -0,0 +1 @@ +export default function importImage(url: string): Promise; diff --git a/packages/imagetools/api/importImage.js b/packages/imagetools/api/importImage.js new file mode 100644 index 0000000..b22ca0b --- /dev/null +++ b/packages/imagetools/api/importImage.js @@ -0,0 +1,23 @@ +import load from "../plugin/hooks/load.js"; +import { getSrcPath } from "./utils/getSrcPath.js"; +import getResolvedSrc from "./utils/getResolvedSrc.js"; + +export default async function importImage(path) { + try { + const { search, protocol, pathname } = new URL(path); + + const { src: id, base } = await getResolvedSrc( + protocol === "data:" ? protocol + pathname : path + ); + + const src = (await load(id + search, base)).slice(16, -1); + + return src; + } catch (error) { + const id = await getSrcPath(path); + + const src = (await load(id)).slice(16, -1); + + return src; + } +} diff --git a/packages/imagetools/api/index.js b/packages/imagetools/api/index.js new file mode 100644 index 0000000..062d6ad --- /dev/null +++ b/packages/imagetools/api/index.js @@ -0,0 +1,6 @@ +export { default as renderImg } from "./renderImg.js"; +export { default as renderPicture } from "./renderPicture.js"; +export { default as renderBackgroundImage } from "./renderBackgroundImage.js"; +export { default as renderBackgroundPicture } from "./renderBackgroundPicture.js"; +export { default as importImage } from "./importImage.js"; +export { getImageDetails, loadImage } from "./utils/imagetools.js" \ No newline at end of file diff --git a/packages/imagetools/api/renderBackgroundImage.d.ts b/packages/imagetools/api/renderBackgroundImage.d.ts new file mode 100644 index 0000000..e7e601b --- /dev/null +++ b/packages/imagetools/api/renderBackgroundImage.d.ts @@ -0,0 +1,8 @@ +import type { + BackgroundImageConfigOptions, + BackgroundImageHTMLData, +} from "../types"; + +export default function renderBackgroundImage( + config: BackgroundImageConfigOptions +): Promise; diff --git a/packages/imagetools/api/renderBackgroundImage.js b/packages/imagetools/api/renderBackgroundImage.js new file mode 100644 index 0000000..f56b308 --- /dev/null +++ b/packages/imagetools/api/renderBackgroundImage.js @@ -0,0 +1,159 @@ +// @ts-check +import crypto from "node:crypto"; +import getImage from "./utils/getImage.js"; +import getLinkElement from "./utils/getLinkElement.js"; +import getStyleElement from "./utils/getStyleElement.js"; +import getFilteredProps from "./utils/getFilteredProps.js"; +import getContainerElement from "./utils/getContainerElement.js"; + +export default async function renderBackgroundImage(props) { + const type = "BackgroundImage"; + + const { filteredProps, transformConfigs } = getFilteredProps(type, props); + + const { + src, + tag, + content, + preload, + attributes, + placeholder, + breakpoints, + backgroundSize, + backgroundPosition, + format, + fallbackFormat, + includeSourceFormat, + formatOptions, + artDirectives, + } = filteredProps; + + const { + link: linkAttributes = {}, + style: styleAttributes = {}, + container: containerAttributes = {}, + } = attributes; + + const sizes = ""; + + const { uuid, images } = await getImage({ + src, + type, + sizes, + format, + breakpoints, + placeholder, + artDirectives, + fallbackFormat, + includeSourceFormat, + formatOptions, + transformConfigs, + }); + + const className = `astro-imagetools-background-image-${uuid}`; + + const { imagesizes } = images[images.length - 1]; + + const link = getLinkElement({ images, preload, imagesizes, linkAttributes }); + + const backgroundImageStylesArray = images.map(({ media, sources }) => { + const uuid = crypto.randomBytes(4).toString("hex").toUpperCase(); + + const fallbackUrlCustomVariable = `--astro-imagetools-background-image-fallback-url${uuid}`; + + const newSources = {}; + + sources.forEach(({ src, format, srcset }) => { + const sources = srcset + .split(", ") + .map((source) => [ + source.slice(0, source.lastIndexOf(" ")), + source.slice(source.lastIndexOf(" ") + 1, -1), + ]); + + sources.forEach(([path, width]) => { + if (!newSources[width]) { + newSources[width] = []; + } + + newSources[width].push({ src, format, path }); + }); + }); + + const widths = Object.keys(newSources) + .map((width) => parseInt(width)) + .reverse(); + + const maxWidth = Math.max(...widths); + + const styles = widths + .map((width) => { + const sources = newSources[width]; + + const styles = sources + .map( + ({ format, path }, i) => + ` + ${i !== sources.length - 1 ? `.${format} ` : ""}.${className} { + background-repeat: no-repeat; + background-image: url(${path}), + var(${fallbackUrlCustomVariable}); + background-size: ${backgroundSize}; + background-position: ${backgroundPosition}; + } + ` + ) + .reverse() + .join(""); + + return width === maxWidth + ? styles + : ` + @media screen and (max-width: ${width}px) { + ${styles} + } + `; + }) + .join(""); + + return { + fallbackUrlCustomVariable, + styles: media + ? ` + @media ${media} { + ${styles} + } + ` + : styles, + }; + }); + + const containerStyles = ` + .${className} { + position: relative; + ${images + .map(({ fallback }, i) => { + const fallbackUrlCustomVariable = + backgroundImageStylesArray[i].fallbackUrlCustomVariable; + + return `${fallbackUrlCustomVariable}: url("${encodeURI(fallback)}");`; + }) + .join("\n")} + } + `; + + const backgroundStyles = + backgroundImageStylesArray.map(({ styles }) => styles).join("\n") + + containerStyles; + + const style = getStyleElement({ styleAttributes, backgroundStyles }); + + const htmlElement = getContainerElement({ + tag, + content, + className, + containerAttributes, + }); + + return { link, style, htmlElement }; +} diff --git a/packages/imagetools/api/renderBackgroundPicture.d.ts b/packages/imagetools/api/renderBackgroundPicture.d.ts new file mode 100644 index 0000000..a566421 --- /dev/null +++ b/packages/imagetools/api/renderBackgroundPicture.d.ts @@ -0,0 +1,8 @@ +import type { + BackgroundPictureConfigOptions, + BackgroundPictureHTMLData, +} from "../types"; + +export default function renderBackgroundPicture( + config: BackgroundPictureConfigOptions +): Promise; diff --git a/packages/imagetools/api/renderBackgroundPicture.js b/packages/imagetools/api/renderBackgroundPicture.js new file mode 100644 index 0000000..1eea4e1 --- /dev/null +++ b/packages/imagetools/api/renderBackgroundPicture.js @@ -0,0 +1,127 @@ +// @ts-check +import getImage from "./utils/getImage.js"; +import getImgElement from "./utils/getImgElement.js"; +import getLinkElement from "./utils/getLinkElement.js"; +import getStyleElement from "./utils/getStyleElement.js"; +import getLayoutStyles from "./utils/getLayoutStyles.js"; +import getFilteredProps from "./utils/getFilteredProps.js"; +import getPictureElement from "./utils/getPictureElement.js"; +import getBackgroundStyles from "./utils/getBackgroundStyles.js"; +import getContainerElement from "./utils/getContainerElement.js"; + +export default async function renderBackgroundPicture(props) { + const type = "BackgroundPicture"; + + const { filteredProps, transformConfigs } = getFilteredProps(type, props); + + const { + src, + tag, + content, + sizes, + preload, + loading, + decoding, + attributes, + placeholder, + breakpoints, + objectFit, + objectPosition, + format, + fallbackFormat, + includeSourceFormat, + formatOptions, + fadeInTransition, + artDirectives, + } = filteredProps; + + const { + img: imgAttributes = {}, + link: linkAttributes = {}, + style: styleAttributes = {}, + picture: pictureAttributes = {}, + container: containerAttributes = {}, + } = attributes; + + const { uuid, images } = await getImage({ + src, + type, + sizes, + format, + breakpoints, + placeholder, + artDirectives, + fallbackFormat, + includeSourceFormat, + formatOptions, + transformConfigs, + }); + + const className = `astro-imagetools-picture-${uuid}`, + containerClassName = `astro-imagetools-background-picture-${uuid}`; + + const { imagesizes } = images[images.length - 1]; + + const backgroundStyles = getBackgroundStyles( + images, + className, + objectFit, + objectPosition, + fadeInTransition, + { isBackgroundPicture: true, containerClassName } + ); + + const style = getStyleElement({ styleAttributes, backgroundStyles }); + + const link = getLinkElement({ images, preload, imagesizes, linkAttributes }); + + const layoutStyles = getLayoutStyles({ isBackgroundImage: true }); + + // Background Images shouldn't convey important information + const alt = ""; + + const sources = images.flatMap(({ media, sources, sizes, imagesizes }) => + sources.map(({ format, src, srcset }) => + src + ? getImgElement({ + src, + alt, + sizes, + style, + srcset, + loading, + decoding, + imagesizes, + fadeInTransition, + layoutStyles, + imgAttributes, + }) + : `` + ) + ); + + const picture = getPictureElement({ + sources, + className, + layoutStyles, + pictureAttributes, + isBackgroundPicture: true, + }); + + const htmlElement = getContainerElement({ + tag, + content: picture + content, + containerAttributes, + isBackgroundPicture: true, + containerClassName, + }); + + return { link, style, htmlElement }; +} diff --git a/packages/imagetools/api/renderImg.d.ts b/packages/imagetools/api/renderImg.d.ts new file mode 100644 index 0000000..abbc304 --- /dev/null +++ b/packages/imagetools/api/renderImg.d.ts @@ -0,0 +1,5 @@ +import type { ImgConfigOptions, ImgHTMLData } from "../types"; + +export default function renderImg( + config: ImgConfigOptions +): Promise; diff --git a/packages/imagetools/api/renderImg.js b/packages/imagetools/api/renderImg.js new file mode 100644 index 0000000..3bc2bf3 --- /dev/null +++ b/packages/imagetools/api/renderImg.js @@ -0,0 +1,93 @@ +// @ts-check +import getImage from "./utils/getImage.js"; +import getImgElement from "./utils/getImgElement.js"; +import getLinkElement from "./utils/getLinkElement.js"; +import getStyleElement from "./utils/getStyleElement.js"; +import getLayoutStyles from "./utils/getLayoutStyles.js"; +import getFilteredProps from "./utils/getFilteredProps.js"; +import getBackgroundStyles from "./utils/getBackgroundStyles.js"; + +export default async function renderImg(props) { + const type = "Img"; + + const { filteredProps, transformConfigs } = getFilteredProps(type, props); + + const { + src, + alt, + sizes, + preload, + loading, + decoding, + attributes, + layout, + breakpoints, + placeholder, + objectFit, + objectPosition, + format, + formatOptions, + } = filteredProps; + + const artDirectives = [], + fallbackFormat = format, + fadeInTransition = false, + includeSourceFormat = false; + + const { + img: imgAttributes = {}, + link: linkAttributes = {}, + style: styleAttributes = {}, + } = attributes; + + const { uuid, images } = await getImage({ + src, + type, + sizes, + format, + breakpoints, + placeholder, + artDirectives, + fallbackFormat, + includeSourceFormat, + formatOptions, + transformConfigs, + }); + + const className = `astro-imagetools-img-${uuid}`; + + const { imagesizes } = images[images.length - 1]; + const backgroundStyles = getBackgroundStyles( + images, + className, + objectFit, + objectPosition, + fadeInTransition, + { isImg: true } + ); + const style = getStyleElement({ styleAttributes, backgroundStyles }) + const link = getLinkElement({ images, preload, imagesizes, linkAttributes }) + const layoutStyles = getLayoutStyles({ layout }) + + const sources = images.flatMap(({ sources, sizes, imagesizes }) => + sources.map(({ src, srcset }) => + getImgElement({ + src, + alt, + sizes, + style, + srcset, + loading, + decoding, + imagesizes, + fadeInTransition, + layoutStyles, + imgAttributes, + imgClassName: className, + }) + ) + ) + + const [img] = sources + return { link, style, img } +} diff --git a/packages/imagetools/api/renderPicture.d.ts b/packages/imagetools/api/renderPicture.d.ts new file mode 100644 index 0000000..54ccfe5 --- /dev/null +++ b/packages/imagetools/api/renderPicture.d.ts @@ -0,0 +1,5 @@ +import type { PictureConfigOptions, PictureHTMLData } from "../types"; + +export default function renderPicture( + config: PictureConfigOptions +): Promise; diff --git a/packages/imagetools/api/renderPicture.js b/packages/imagetools/api/renderPicture.js new file mode 100644 index 0000000..8a98d1c --- /dev/null +++ b/packages/imagetools/api/renderPicture.js @@ -0,0 +1,111 @@ +// @ts-check +import getImage from "./utils/getImage.js"; +import getImgElement from "./utils/getImgElement.js"; +import getLinkElement from "./utils/getLinkElement.js"; +import getStyleElement from "./utils/getStyleElement.js"; +import getLayoutStyles from "./utils/getLayoutStyles.js"; +import getFilteredProps from "./utils/getFilteredProps.js"; +import getPictureElement from "./utils/getPictureElement.js"; +import getBackgroundStyles from "./utils/getBackgroundStyles.js"; + +export default async function renderPicture(props) { + const type = "Picture"; + + const { filteredProps, transformConfigs } = getFilteredProps(type, props); + + const { + src, + alt, + sizes, + preload, + loading, + decoding, + attributes, + layout, + placeholder, + breakpoints, + objectFit, + objectPosition, + format, + fallbackFormat, + includeSourceFormat, + formatOptions, + fadeInTransition, + artDirectives, + } = filteredProps; + + const { + img: imgAttributes = {}, + link: linkAttributes = {}, + style: styleAttributes = {}, + picture: pictureAttributes = {}, + } = attributes; + + const { uuid, images } = await getImage({ + src, + type, + sizes, + format, + breakpoints, + placeholder, + fallbackFormat, + includeSourceFormat, + formatOptions, + artDirectives, + transformConfigs, + }); + + const className = `astro-imagetools-picture-${uuid}`; + + const { imagesizes } = images[images.length - 1]; + + const backgroundStyles = getBackgroundStyles( + images, + className, + objectFit, + objectPosition, + fadeInTransition + ); + + const style = getStyleElement({ styleAttributes, backgroundStyles }); + + const link = getLinkElement({ images, preload, imagesizes, linkAttributes }); + + const layoutStyles = getLayoutStyles({ layout }); + + const sources = images.flatMap(({ media, sources, sizes, imagesizes }) => + sources.map(({ format, src, srcset }) => + src + ? getImgElement({ + src, + alt, + sizes, + style, + srcset, + loading, + decoding, + imagesizes, + fadeInTransition, + layoutStyles, + imgAttributes, + }) + : `` + ) + ); + + const picture = getPictureElement({ + sources, + className, + layoutStyles, + pictureAttributes, + }); + + return { link, style, picture }; +} diff --git a/packages/imagetools/api/utils/codecs.js b/packages/imagetools/api/utils/codecs.js new file mode 100644 index 0000000..8f72571 --- /dev/null +++ b/packages/imagetools/api/utils/codecs.js @@ -0,0 +1,38 @@ +// @ts-check +import fs from "node:fs"; +import { extname } from "node:path"; +import * as codecs from "@astropub/codecs"; + +export async function getImageDetails(path, width, height, aspect) { + const extension = extname(path).slice(1); + + const imageFormat = extension === "jpeg" ? "jpg" : extension; + + const buffer = fs.readFileSync(path); + const decodedImage = await codecs.jpg.decode(buffer); + + if (aspect && !width && !height) { + if (!width && !height) { + ({ width } = decodedImage); + } + + if (width) { + height = width / aspect; + } + + if (height) { + width = height * aspect; + } + } + + const image = await decodedImage.resize({ width, height }); + + const { width: imageWidth, height: imageHeight } = image; + + return { + image, + imageWidth, + imageHeight, + imageFormat, + }; +} diff --git a/packages/imagetools/api/utils/getArtDirectedImages.js b/packages/imagetools/api/utils/getArtDirectedImages.js new file mode 100644 index 0000000..1f7c073 --- /dev/null +++ b/packages/imagetools/api/utils/getArtDirectedImages.js @@ -0,0 +1,137 @@ +// @ts-check +import getSrcset from "./getSrcset.js"; +import getConfigOptions from "./getConfigOptions.js"; +import getFallbackImage from "./getFallbackImage.js"; +import getProcessedImage from "./getProcessedImage.js"; + +export default async function getArtDirectedImages( + artDirectives = [], + placeholder, + format, + imagesizes, + breakpoints, + fallbackFormat, + includeSourceFormat, + formatOptions, + rest +) { + const images = await Promise.all( + artDirectives.map( + async ({ + src, + media, + sizes: directiveImagesizes, + placeholder: directivePlaceholder, + breakpoints: directiveBreakpoints, + objectFit, + objectPosition, + backgroundSize, + backgroundPosition, + format: directiveFormat, + fallbackFormat: directiveFallbackFormat, + includeSourceFormat: directiveIncludeSourceFormat, + formatOptions: directiveFormatOptions = {}, + ...configOptions + }) => { + const { + path, + base, + rest: rest2, + image, + imageWidth, + imageHeight, + imageFormat, + } = await getProcessedImage(src, configOptions); + + rest2.aspect = `${imageWidth / imageHeight}`; + + const calculatedConfigs = getConfigOptions( + imageWidth, + directiveImagesizes || imagesizes, + directiveBreakpoints || breakpoints, + directiveFormat || format, + imageFormat, + directiveFallbackFormat || fallbackFormat, + directiveIncludeSourceFormat || includeSourceFormat + ); + + const { formats, requiredBreakpoints } = calculatedConfigs; + + imagesizes = calculatedConfigs.imagesizes; + + const maxWidth = requiredBreakpoints[requiredBreakpoints.length - 1]; + + const sources = await Promise.all( + formats.map(async (format) => { + const srcset = await getSrcset( + path, + base, + requiredBreakpoints, + format, + { + ...rest, + ...rest2, + ...formatOptions[format], + ...directiveFormatOptions[format], + } + ); + + return { + format, + srcset, + }; + }) + ); + + const sizes = { + width: maxWidth, + height: Math.round(maxWidth / rest2.aspect), + }; + + const object = { + fit: objectFit, + position: objectPosition, + }; + + const background = { + size: backgroundSize, + position: backgroundPosition, + }; + + const fallback = await getFallbackImage( + path, + directivePlaceholder || placeholder, + image, + imageFormat, + { ...formatOptions, ...directiveFormatOptions }, + { ...rest, ...rest2 } + ); + + const returnValue = { + media, + sources, + sizes, + fallback, + imagesizes, + }; + + const isBackgroundImage = !!backgroundSize || !!backgroundPosition; + + isBackgroundImage + ? (returnValue.background = background) + : (returnValue.object = object); + + return { + media, + sources, + sizes, + object, + fallback, + imagesizes, + }; + } + ) + ); + + return images; +} diff --git a/packages/imagetools/api/utils/getAttributesString.js b/packages/imagetools/api/utils/getAttributesString.js new file mode 100644 index 0000000..e9bd1c1 --- /dev/null +++ b/packages/imagetools/api/utils/getAttributesString.js @@ -0,0 +1,27 @@ +// @ts-check + +import printWarning from "../../utils/printWarning.js"; + +export default function getAttributesString({ + attributes, + element = "", + excludeArray = [], +}) { + const attributesString = Object.keys(attributes) + .filter((key) => { + if (excludeArray.includes(key)) { + printWarning({ + key, + element, + }); + + return false; + } + + return true; + }) + .map((key) => `${key}="${attributes[key]}"`) + .join(" "); + + return attributesString; +} diff --git a/packages/imagetools/api/utils/getBackgroundStyles.js b/packages/imagetools/api/utils/getBackgroundStyles.js new file mode 100644 index 0000000..111233c --- /dev/null +++ b/packages/imagetools/api/utils/getBackgroundStyles.js @@ -0,0 +1,97 @@ +// @ts-check + +export default function getBackgroundStyles( + images, + className, + objectFit, + objectPosition, + fadeInTransition, + { isImg = false, isBackgroundPicture = false, containerClassName = "" } = {} +) { + const sourcesWithFallback = images.filter(({ fallback }) => fallback); + + if (sourcesWithFallback.length === 0) return ""; + + const staticStyles = !fadeInTransition + ? "" + : ` + ${ + isBackgroundPicture + ? ` + .${containerClassName} * { + z-index: 1; + position: relative; + } + ` + : "" + } + + .${className} { + --opacity: 1; + --z-index: 0; + } + + ${ + !isBackgroundPicture + ? ` + .${className} img { + z-index: 1; + position: relative; + } + ` + : "" + } + + .${className}::after { + inset: 0; + content: ""; + left: 0; + width: 100%; + height: 100%; + position: absolute; + pointer-events: none; + transition: opacity ${ + typeof fadeInTransition !== "object" + ? "1s" + : (() => { + const { + delay = "0s", + duration = "1s", + timingFunction = "ease", + } = fadeInTransition; + + return `${duration} ${timingFunction} ${delay}`; + })() + }; + opacity: var(--opacity); + z-index: var(--z-index); + } + `; + + const dynamicStyles = images + .map(({ media, fallback, object }) => { + const elementSelector = className + (!isImg ? " img" : ""), + backgroundElementSelector = + className + (fadeInTransition ? "::after" : ""); + + const style = ` + .${elementSelector} { + object-fit: ${object?.fit || objectFit}; + object-position: ${object?.position || objectPosition}; + } + + .${backgroundElementSelector} { + background-size: ${object?.fit || objectFit}; + background-image: url("${encodeURI(fallback)}"); + background-position: ${object?.position || objectPosition}; + } + `; + + return media ? `@media ${media} { ${style} }` : style; + }) + .reverse(); + + const backgroundStyles = [staticStyles, ...dynamicStyles].join(""); + + return backgroundStyles; +} diff --git a/packages/imagetools/api/utils/getBreakpoints.js b/packages/imagetools/api/utils/getBreakpoints.js new file mode 100644 index 0000000..02a098e --- /dev/null +++ b/packages/imagetools/api/utils/getBreakpoints.js @@ -0,0 +1,77 @@ +// @ts-check +import printWarning from "../../utils/printWarning.js"; + +export default function getBreakpoints(breakpoints, imageWidth) { + if (Array.isArray(breakpoints)) { + return breakpoints.sort((a, b) => a - b); + } + + const { count, minWidth = 320 } = breakpoints || {}; + + const maxWidth = (() => { + if (breakpoints?.maxWidth) return breakpoints.maxWidth; + + if (imageWidth > 3840) { + printWarning({ + message: + "The width of the source image is greater than 3840px. The generated breakpoints will be capped at 3840px. If you need breakpoints larger than this, please pass the maxWidth option to the breakpoints property.", + }); + + return 3840; + } + + return imageWidth; + })(); + + const breakPoints = []; + + const diff = maxWidth - minWidth; + + const n = + count || + (maxWidth <= 400 + ? 1 + : maxWidth <= 640 + ? 2 + : maxWidth <= 800 + ? 3 + : maxWidth <= 1024 + ? 4 + : maxWidth <= 1280 + ? 5 + : maxWidth <= 1440 + ? 6 + : maxWidth <= 1920 + ? 7 + : maxWidth <= 2560 + ? 8 + : maxWidth <= 2880 + ? 9 + : maxWidth <= 3840 + ? 10 + : 11); + + let currentWidth = minWidth; + + n > 1 && breakPoints.push(currentWidth); + + let steps = 0; + + for (let i = 1; i < n; i++) { + steps += i; + } + + const pixelsPerStep = diff / steps; + + for (let i = 1; i < n - 1; i++) { + const next = pixelsPerStep * (n - i) + currentWidth; + + breakPoints.push(Math.round(next)); + + currentWidth = next; + } + + breakPoints.push(maxWidth); + + return [...new Set(breakPoints)]; +} diff --git a/packages/imagetools/api/utils/getConfigOptions.js b/packages/imagetools/api/utils/getConfigOptions.js new file mode 100644 index 0000000..3b3797d --- /dev/null +++ b/packages/imagetools/api/utils/getConfigOptions.js @@ -0,0 +1,34 @@ +// @ts-check +import getBreakpoints from "./getBreakpoints.js"; + +export default function getConfigOptions( + imageWidth, + imagesizes, + breakpoints, + format, + imageFormat, + fallbackFormat, + includeSourceFormat +) { + const formats = [ + ...new Set( + [format, includeSourceFormat && imageFormat] + .flat() + .filter((f) => f && f !== fallbackFormat) + ), + fallbackFormat, + ]; + + const requiredBreakpoints = getBreakpoints(breakpoints, imageWidth); + + imagesizes = + typeof imagesizes === "string" + ? imagesizes + : imagesizes(requiredBreakpoints); + + return { + formats, + imagesizes, + requiredBreakpoints, + }; +} diff --git a/packages/imagetools/api/utils/getContainerElement.js b/packages/imagetools/api/utils/getContainerElement.js new file mode 100644 index 0000000..9c5b710 --- /dev/null +++ b/packages/imagetools/api/utils/getContainerElement.js @@ -0,0 +1,48 @@ +// @ts-check +import getAttributesString from "./getAttributesString.js"; + +export default function getContainerElement({ + tag, + content, + className = "", + containerAttributes, + isBackgroundPicture = false, + containerClassName = "", +}) { + const { + class: customClasses = "", + style: customInlineStyles = "", + ...restContainerAttributes + } = containerAttributes; + + const attributesString = getAttributesString({ + attributes: restContainerAttributes, + }); + + const classAttribute = [ + isBackgroundPicture + ? "astro-imagetools-background-picture" + : "astro-imagetools-background-image", + isBackgroundPicture ? containerClassName : className, + customClasses, + ] + .join(" ") + .trim(); + + const styleAttribute = [ + isBackgroundPicture ? "position: relative;" : "", + customInlineStyles + (customInlineStyles.endsWith(";") ? "" : ";"), + ] + .join(" ") + .trim(); + + const containerElement = `<${tag} + ${attributesString} + class="${classAttribute}" + style="${styleAttribute}" + > + ${content} + `; + + return containerElement; +} diff --git a/packages/imagetools/api/utils/getFallbackImage.js b/packages/imagetools/api/utils/getFallbackImage.js new file mode 100644 index 0000000..b085286 --- /dev/null +++ b/packages/imagetools/api/utils/getFallbackImage.js @@ -0,0 +1,58 @@ +// @ts-check + +import util from "node:util"; +import potrace from "potrace"; +import getSrcset from "./getSrcset.js"; +import { sharp } from "../../utils/runtimeChecks.js"; + +export default async function getFallbackImage( + src, + placeholder, + image, + format, + formatOptions, + rest +) { + const base = null; + + switch (placeholder) { + case "blurred": { + const dataUri = await getSrcset(src, base, [20], format, { + inline: true, + ...rest, + ...formatOptions[format], + }); + + return dataUri; + } + case "tracedSVG": { + const { function: fn, options } = formatOptions.tracedSVG; + + const traceSVG = util.promisify(potrace[fn]); + + const imageBuffer = sharp + ? await image.toBuffer() + : Buffer.from( + (await image.encode(`image/${format === "jpg" ? "jpeg" : format}`)) + .data + ); + + const tracedSVG = await traceSVG(imageBuffer, options); + + return `data:image/svg+xml;utf8,${tracedSVG}`; + } + case "dominantColor": { + if (sharp) { + var { r, g, b } = (await image.stats()).dominant; + } else { + [r, g, b] = image.color; + } + + const svg = ``; + + return `data:image/svg+xml;utf8,${svg}`; + } + default: + return null; + } +} diff --git a/packages/imagetools/api/utils/getFilteredProps.js b/packages/imagetools/api/utils/getFilteredProps.js new file mode 100644 index 0000000..9c791ba --- /dev/null +++ b/packages/imagetools/api/utils/getFilteredProps.js @@ -0,0 +1,138 @@ +// @ts-check +import filterConfigs from "../../utils/filterConfigs.js"; +import { + supportedConfigs, + GlobalConfigOptions, +} from "../../utils/runtimeChecks.js"; + +const GlobalOnlyProperties = ["cacheDir", "assetFileNames"]; + +const NonGlobalSupportedConfigs = supportedConfigs.filter( + (key) => !GlobalOnlyProperties.includes(key) +); + +const NonProperties = { + Img: [ + "tag", + "content", + "backgroundSize", + "backgroundPosition", + "fallbackFormat", + "includeSourceFormat", + "fadeInTransition", + "artDirectives", + ], + Picture: ["tag", "content", "backgroundSize", "backgroundPosition"], + BackgroundImage: [ + "alt", + "loading", + "decoding", + "layout", + "objectFit", + "objectPosition", + "fadeInTransition", + ], + BackgroundPicture: ["alt", "backgroundSize", "backgroundPosition"], +}; + +const ImgProperties = NonGlobalSupportedConfigs.filter( + (key) => !NonProperties.Img.includes(key) + ), + PictureProperties = NonGlobalSupportedConfigs.filter( + (key) => !NonProperties.Picture.includes(key) + ), + BackgroundImageProperties = NonGlobalSupportedConfigs.filter( + (key) => !NonProperties.BackgroundImage.includes(key) + ), + BackgroundPictureProperties = NonGlobalSupportedConfigs.filter( + (key) => !NonProperties.BackgroundPicture.includes(key) + ); + +const SupportedProperties = { + Img: ImgProperties, + Picture: PictureProperties, + BackgroundImage: BackgroundImageProperties, + BackgroundPicture: BackgroundPictureProperties, +}; + +export default function getFilteredProps(type, props) { + const filteredGlobalConfigs = filterConfigs( + "Global", + GlobalConfigOptions, + SupportedProperties[type], + { warn: false } + ); + + const { search, searchParams } = new URL(props.src, "file://"); + + props.src = props.src.replace(search, ""); + + const paramOptions = Object.fromEntries(searchParams); + + const filteredLocalProps = filterConfigs( + type, + { + ...paramOptions, + ...props, + }, + SupportedProperties[type] + ); + + const resolvedProps = { + ...filteredGlobalConfigs, + ...filteredLocalProps, + }; + + const { + src, + alt, + tag = "section", + content = "", + sizes = function (breakpoints) { + const maxWidth = breakpoints[breakpoints.length - 1]; + return `(min-width: ${maxWidth}px) ${maxWidth}px, 100vw`; + }, + preload, + loading = preload ? "eager" : "lazy", + decoding = "async", + attributes = {}, + layout = "constrained", + placeholder = "blurred", + breakpoints, + objectFit = "cover", + objectPosition = "50% 50%", + backgroundSize = "cover", + backgroundPosition = "50% 50%", + format = type === "Img" ? undefined : ["avif", "webp"], + fallbackFormat, + includeSourceFormat = true, + formatOptions = { + tracedSVG: { + function: "trace", + }, + }, + fadeInTransition = true, + artDirectives, + ...transformConfigs + } = resolvedProps; + + // prettier-ignore + const allProps = { + src, alt, tag, content, sizes, preload, loading, decoding, attributes, layout, placeholder, + breakpoints, objectFit, objectPosition, backgroundSize, backgroundPosition, format, + fallbackFormat, includeSourceFormat, formatOptions, fadeInTransition, artDirectives, + ...transformConfigs, + }; + + const filteredProps = filterConfigs( + type, + allProps, + SupportedProperties[type], + { warn: false } + ); + + return { + filteredProps, + transformConfigs, + }; +} diff --git a/packages/imagetools/api/utils/getFilteredProps.test.ts b/packages/imagetools/api/utils/getFilteredProps.test.ts new file mode 100644 index 0000000..7b8f20c --- /dev/null +++ b/packages/imagetools/api/utils/getFilteredProps.test.ts @@ -0,0 +1,49 @@ +import { describe, expect, it } from "vitest"; +import getFilteredProps from "./getFilteredProps"; + +describe("getFilteredProps", () => { + it("should should merge in default props", () => { + const result = getFilteredProps("Img", { src: "/img.jpeg", alt: "alt" }); + expect(result).toEqual({ + filteredProps: { + alt: "alt", + attributes: {}, + breakpoints: undefined, + decoding: "async", + format: undefined, + formatOptions: { + tracedSVG: { + function: "trace", + }, + }, + layout: "constrained", + loading: "lazy", + objectFit: "cover", + objectPosition: "50% 50%", + placeholder: "blurred", + preload: undefined, + sizes: expect.any(Function), + src: "/img.jpeg", + }, + transformConfigs: {}, + }); + }); + + it("should accept empty string for `alt` prop on Img", () => { + const result = getFilteredProps("Img", { src: "/img.jpeg", alt: "" }); + expect(result).toMatchObject({ + filteredProps: { + alt: "", + }, + }); + }); + + it("should accept empty string for `alt` prop on Picture", () => { + const result = getFilteredProps("Picture", { src: "/img.jpeg", alt: "" }); + expect(result).toMatchObject({ + filteredProps: { + alt: "", + }, + }); + }); +}); diff --git a/packages/imagetools/api/utils/getImage.js b/packages/imagetools/api/utils/getImage.js new file mode 100644 index 0000000..594918e --- /dev/null +++ b/packages/imagetools/api/utils/getImage.js @@ -0,0 +1,107 @@ +// @ts-check +import crypto from "node:crypto"; +import objectHash from "object-hash"; +import getImageSources from "./getImageSources.js"; +import getProcessedImage from "./getProcessedImage.js"; +import getArtDirectedImages from "./getArtDirectedImages.js"; +import pMap from "p-map"; + +const imagesData = new Map(); + +const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); + +export default async function ({ + src, + type, + sizes: imagesizes, + format, + breakpoints, + placeholder, + fallbackFormat, + includeSourceFormat, + formatOptions, + artDirectives, + transformConfigs, +}) { + try { + const args = Array.from(arguments); + const hash = objectHash(args); + if (imagesData.has(hash)) { + return imagesData.get(hash); + } + + const start = performance.now(); + + const { path, base, rest, image, imageWidth, imageHeight, imageFormat } = + await getProcessedImage(src, transformConfigs); + + await delay(250); + src = path; + + rest.aspect = `${imageWidth / imageHeight}`; + if (!fallbackFormat) { + fallbackFormat = imageFormat; + } + + // Fetch both image sources and art-directed images + const [mainImage, artDirectedImages] = await pMap( + [ + async () => + await getImageSources( + src, + base, + image, + format, + imageWidth, + imagesizes, + breakpoints, + placeholder, + imageFormat, + formatOptions, + fallbackFormat, + includeSourceFormat, + rest + ), + async () => { + await delay(250); + return await getArtDirectedImages( + artDirectives, + placeholder, + format, + imagesizes, + breakpoints, + fallbackFormat, + includeSourceFormat, + formatOptions, + rest + ); + }, + ], + async (task) => await task(), + { concurrency: 1 } + ); + + // Ensure artDirectedImages is an array + const images = Array.isArray(artDirectedImages) ? [...artDirectedImages, mainImage] : [mainImage]; + + const uuid = crypto.randomBytes(4).toString("hex").toUpperCase(); + + const returnObject = { + uuid, + images, + }; + + imagesData.set(hash, returnObject); + + const end = performance.now(); + + console.log( + `Responsive Image sets generated for ${type} at ${args[0].src} in ${end - start}ms` + ); + + return returnObject; + } catch (error) { + console.error("Error processing images:", error); + throw error; + } +} diff --git a/packages/imagetools/api/utils/getImageSources.js b/packages/imagetools/api/utils/getImageSources.js new file mode 100644 index 0000000..d0dca00 --- /dev/null +++ b/packages/imagetools/api/utils/getImageSources.js @@ -0,0 +1,91 @@ +// @ts-check +import getSrcset from "./getSrcset.js"; +import getConfigOptions from "./getConfigOptions.js"; +import getFallbackImage from "./getFallbackImage.js"; +import pMap from "p-map"; + +function delay(ms) { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +export default async function getImageSources( + src, + base, + image, + format, + imageWidth, + imagesizes, + breakpoints, + placeholder, + imageFormat, + formatOptions, + fallbackFormat, + includeSourceFormat, + rest +) { + try { + const calculatedConfigs = getConfigOptions( + imageWidth, + imagesizes, + breakpoints, + format, + imageFormat, + fallbackFormat, + includeSourceFormat + ); + + const { formats, requiredBreakpoints } = calculatedConfigs; + imagesizes = calculatedConfigs.imagesizes; + const maxWidth = requiredBreakpoints[requiredBreakpoints.length - 1]; + const sliceLength = -(maxWidth.toString().length + 2); + + const sources = await pMap( + formats, + async (format) => { + try { + await delay(250); + const srcset = await getSrcset(src, base, requiredBreakpoints, format, { + ...rest, + ...formatOptions[format], + }); + + const srcsets = srcset.split(", "); + const srcObject = + format === fallbackFormat + ? { src: srcsets[srcsets.length - 1].slice(0, sliceLength) } + : {}; + + return { + ...srcObject, + format, + srcset, + }; + } catch (error) { + console.error(`Error processing format ${format}:`, error); + return null; + } + }, + { concurrency: 1 } + ); + + const filteredSources = sources.filter(Boolean); + + const sizes = { + width: maxWidth, + height: Math.round(maxWidth / rest.aspect), + }; + + const fallback = await getFallbackImage( + src, + placeholder, + image, + fallbackFormat, + formatOptions, + rest + ) + return { sources: filteredSources, sizes, fallback, imagesizes }; + } catch (error) { + console.error("Error in getImageSources:", error); + return { sources: [], sizes: {}, fallback: null, imagesizes: null }; + } +} diff --git a/packages/imagetools/api/utils/getImgElement.js b/packages/imagetools/api/utils/getImgElement.js new file mode 100644 index 0000000..fea4109 --- /dev/null +++ b/packages/imagetools/api/utils/getImgElement.js @@ -0,0 +1,80 @@ +// @ts-check + +import getAttributesString from "./getAttributesString.js"; + +export default function getImgElement({ + src, + alt, + sizes, + style, + srcset, + loading, + decoding, + imagesizes, + fadeInTransition, + layoutStyles, + imgAttributes, + imgClassName = "", +}) { + const { + class: customClasses = "", + style: customInlineStyles = "", + onload: customOnload = "", + ...restImgAttributes + } = imgAttributes; + + const attributesString = getAttributesString({ + attributes: restImgAttributes, + element: "img", + excludeArray: [ + "src", + "alt", + "srcset", + "sizes", + "width", + "height", + "loading", + "decoding", + ], + }); + + const classAttribute = ["astro-imagetools-img", imgClassName, customClasses] + .join(" ") + .trim(); + + const styleAttribute = [ + "display: inline-block; overflow: hidden; vertical-align: middle;", + customInlineStyles + (customInlineStyles.endsWith(";") ? "" : ";"), + layoutStyles, + ] + .join(" ") + .trim(); + + const onloadAttribute = [ + !imgClassName && style + ? fadeInTransition + ? `parentElement.style.setProperty('--z-index', 1); parentElement.style.setProperty('--opacity', 0);` + : `parentElement.style.backgroundImage = 'unset';` + : "", + customOnload, + ] + .join(" ") + .trim(); + + const imgElement = `==`; + + return imgElement; +} diff --git a/packages/imagetools/api/utils/getLayoutStyles.js b/packages/imagetools/api/utils/getLayoutStyles.js new file mode 100644 index 0000000..efa6d96 --- /dev/null +++ b/packages/imagetools/api/utils/getLayoutStyles.js @@ -0,0 +1,16 @@ +// @ts-check + +export default function getLayoutStyles({ + layout = null, + isBackgroundImage = false, +}) { + return isBackgroundImage + ? "width: 100%; height: 100%;" + : layout === "fill" + ? `width: 100%; height: 100%;` + : layout === "fullWidth" + ? `width: 100%; height: auto;` + : layout === "fixed" + ? "" + : "max-width: 100%; height: auto;"; +} diff --git a/packages/imagetools/api/utils/getLinkElement.js b/packages/imagetools/api/utils/getLinkElement.js new file mode 100644 index 0000000..2fcfb7a --- /dev/null +++ b/packages/imagetools/api/utils/getLinkElement.js @@ -0,0 +1,34 @@ +// @ts-check +import getAttributesString from "./getAttributesString.js"; + +export default function getLinkElement({ + images = [], + preload = "", + imagesizes = "", + linkAttributes, +}) { + const imagesrcset = + preload && + images[images.length - 1]?.sources.find( + ({ format: fmt }) => fmt === preload + )?.srcset; + + const attributesString = getAttributesString({ + element: "link", + attributes: linkAttributes, + excludeArray: ["as", "rel", "imagesizes", "imagesrcset"], + }); + + const linkElement = + preload && images.length + ? `` + : ""; + + return linkElement; +} diff --git a/packages/imagetools/api/utils/getLinkElement.test.ts b/packages/imagetools/api/utils/getLinkElement.test.ts new file mode 100644 index 0000000..83d435a --- /dev/null +++ b/packages/imagetools/api/utils/getLinkElement.test.ts @@ -0,0 +1,14 @@ +import { describe, expect, it } from "vitest"; +import getLinkElement from "./getLinkElement"; + +describe("getLinkElement", () => { + it("returns an empty string if preload is not set", () => { + const result = getLinkElement({ linkAttributes: {} }); + expect(result).toBe(""); + }); + + it("returns an empty string if no images are provided", () => { + const result = getLinkElement({ linkAttributes: {}, preload: "webp" }); + expect(result).toBe(""); + }); +}); diff --git a/packages/imagetools/api/utils/getPictureElement.js b/packages/imagetools/api/utils/getPictureElement.js new file mode 100644 index 0000000..b0d62c3 --- /dev/null +++ b/packages/imagetools/api/utils/getPictureElement.js @@ -0,0 +1,43 @@ +// @ts-check +import getAttributesString from "./getAttributesString.js"; + +export default function getPictureElement({ + sources, + className, + layoutStyles, + pictureAttributes, + isBackgroundPicture = false, +}) { + const { + class: customClasses = "", + style: customInlineStyles = "", + ...restPictureAttributes + } = pictureAttributes; + + const attributesString = getAttributesString({ + attributes: restPictureAttributes, + }); + + const classAttribute = ["astro-imagetools-picture", className, customClasses] + .join(" ") + .trim(); + + const styleAttribute = [ + isBackgroundPicture + ? `position: absolute; z-index: 0; width: 100%; height: 100%; display: inline-block;` + : `position: relative; display: inline-block;`, + customInlineStyles + (customInlineStyles.endsWith(";") ? "" : ";"), + layoutStyles, + ] + .join(" ") + .trim(); + + const pictureElement = `${sources.join("\n")} + `; + + return pictureElement; +} diff --git a/packages/imagetools/api/utils/getProcessedImage.js b/packages/imagetools/api/utils/getProcessedImage.js new file mode 100644 index 0000000..98eae1d --- /dev/null +++ b/packages/imagetools/api/utils/getProcessedImage.js @@ -0,0 +1,63 @@ +// @ts-check +import { fileURLToPath } from "node:url"; +import { extname, relative, resolve } from "node:path"; + +import { getSrcPath } from "./getSrcPath.js"; +import getResolvedSrc from "./getResolvedSrc.js"; +import { cwd, sharp } from "../../utils/runtimeChecks.js"; +import throwErrorIfUnsupported from "./throwErrorIfUnsupported.js"; + +const { getImageDetails } = await (sharp + ? import("./imagetools.js") + : import("./codecs.js")); + +export default async function getProcessedImage(src, transformConfigs) { + throwErrorIfUnsupported(src, extname(src).slice(1)); + + let base; + + if (src.match("(http://|https://|data:image/).*")) { + ({ src, base } = await getResolvedSrc(src)); + } else { + const { + default: { isSsrBuild }, + } = await import("../../astroViteConfigs.js"); + + if (isSsrBuild) { + const filename = fileURLToPath(import.meta.url); + + const assetPath = resolve(filename, "../../client") + src; + + src = "/" + relative(cwd, assetPath); + } + } + + const { + w, + h, + ar, + width = w, + height = h, + aspect = ar, + ...rest + } = transformConfigs; + + const path = src.replace(/\\/g, `/`); + + const { image, imageWidth, imageHeight, imageFormat } = await getImageDetails( + await getSrcPath(src), + width, + height, + aspect + ); + + return { + path, + base, + rest, + image, + imageWidth, + imageHeight, + imageFormat, + }; +} diff --git a/packages/imagetools/api/utils/getResolvedSrc.js b/packages/imagetools/api/utils/getResolvedSrc.js new file mode 100644 index 0000000..696f0bc --- /dev/null +++ b/packages/imagetools/api/utils/getResolvedSrc.js @@ -0,0 +1,50 @@ +// @ts-check +import fs from "node:fs"; +import crypto from "node:crypto"; +import { join, parse, relative } from "node:path"; +import throwErrorIfUnsupported from "./throwErrorIfUnsupported.js"; +import { + cwd, + fsCachePath, + supportedImageTypes, +} from "../../utils/runtimeChecks.js"; + +const { fileTypeFromBuffer } = await import("file-type"); + +export default async function getResolvedSrc(src) { + const token = crypto.createHash("md5").update(src).digest("hex"); + + let filepath = fsCachePath + token; + + const fileExists = (() => { + for (const type of supportedImageTypes) { + const fileExists = fs.existsSync(filepath + `.${type}`); + + if (fileExists) { + filepath += `.${type}`; + + return true; + } + } + })(); + + if (!fileExists) { + const buffer = Buffer.from(await (await fetch(src)).arrayBuffer()); + + const { ext } = (await fileTypeFromBuffer(buffer)) || {}; + + throwErrorIfUnsupported(src, ext); + + filepath += `.${ext}`; + + fs.writeFileSync(filepath, buffer); + } + + const base = /^https?:/.test(src) + ? parse(new URL(src).pathname).name + : undefined; + + src = join("/", relative(cwd, filepath)); + + return { src, base }; +} diff --git a/packages/imagetools/api/utils/getSrcPath.js b/packages/imagetools/api/utils/getSrcPath.js new file mode 100644 index 0000000..3a7a7da --- /dev/null +++ b/packages/imagetools/api/utils/getSrcPath.js @@ -0,0 +1,32 @@ +import fs from "node:fs"; +import path from "node:path"; + +// To strip off params when checking for file on disk. +const paramPattern = /\?.*/; + +/** + * getSrcPath allows the use of `src` attributes relative to either the public folder or project root. + * + * It first checks to see if the src is a file relative to the project root. + * If the file isn't found, it will look in the public folder. + * Finally, if it still can't be found, the original input will be returned. + */ +export async function getSrcPath(src) { + const { default: astroViteConfigs } = await import( + "../../astroViteConfigs.js" + ); + + // If this is already resolved to a file, return it. + if (fs.existsSync(src.replace(paramPattern, ""))) return src; + + const rootPath = path.join(astroViteConfigs.rootDir, src); + const rootTest = rootPath.replace(paramPattern, ""); + if (fs.existsSync(rootTest)) return rootPath; + + const publicPath = path.join(astroViteConfigs.publicDir, src); + const publicTest = publicPath.replace(paramPattern, ""); + if (fs.existsSync(publicTest)) return publicPath; + + // Fallback + return src; +} diff --git a/packages/imagetools/api/utils/getSrcPath.test.ts b/packages/imagetools/api/utils/getSrcPath.test.ts new file mode 100644 index 0000000..bb267dd --- /dev/null +++ b/packages/imagetools/api/utils/getSrcPath.test.ts @@ -0,0 +1,67 @@ +import path from "node:path"; +import { describe, expect, it, afterAll, vi } from "vitest"; +import { getSrcPath } from "./getSrcPath"; + +vi.mock("../../astroViteConfigs.js", () => { + return { + default: { + rootDir: buildPath(), + // Custom publicDir + publicDir: buildPath("out"), + }, + }; +}); + +/** + * Build an absolute path to the target in the fixture directory + */ +function buildPath(target = "") { + return path.resolve(__dirname, "../../test-fixtures/getSrcPath", target); +} + +describe("getLinkElement", () => { + afterAll(() => { + vi.unmock("../../astroViteConfigs.js"); + }); + + it("finds a file in the root of the project", async () => { + const result = await getSrcPath("root.jpeg"); + expect(result).toBe(buildPath("root.jpeg")); + }); + + it("finds a file in the public folder", async () => { + const result = await getSrcPath("out.jpeg"); + expect(result).toBe(buildPath("out/out.jpeg")); + }); + + it("returns an absolute path unchanged, if it exists", async () => { + const result = await getSrcPath(buildPath("out/out.jpeg")); + expect(result).toBe(buildPath("out/out.jpeg")); + }); + + it("handles query parameters", async () => { + const result = await getSrcPath("root.jpeg?w=200"); + expect(result).toBe(buildPath("root.jpeg?w=200")); + }); + + it("handles query parameters for public-resolved files", async () => { + const result = await getSrcPath("out.jpeg?w=200"); + expect(result).toBe(buildPath("out/out.jpeg?w=200")); + }); + + it("returns the original input if the file is not found", async () => { + const result = await getSrcPath( + "https://cdn.nedis.com/images/products_high_res/TVRC2080BK_P30.JPG" + ); + expect(result).toBe( + "https://cdn.nedis.com/images/products_high_res/TVRC2080BK_P30.JPG" + ); + }); + + it("finds relative paths correctly", async () => { + const outResult = await getSrcPath("./out/out.jpeg"); + const rootResult = await getSrcPath("./root.jpeg"); + expect(outResult).toBe(buildPath("out/out.jpeg")); + expect(rootResult).toBe(buildPath("root.jpeg")); + }); +}); diff --git a/packages/imagetools/api/utils/getSrcset.js b/packages/imagetools/api/utils/getSrcset.js new file mode 100644 index 0000000..cbd2990 --- /dev/null +++ b/packages/imagetools/api/utils/getSrcset.js @@ -0,0 +1,39 @@ +// @ts-check +import { getSrcPath } from "./getSrcPath.js"; + +export default async function getSrcset( + src, + base, + breakpoints, + format, + options +) { + options = { + format, + w: breakpoints, + ...options, + }; + + const keys = Object.keys(options); + + const params = keys.length + ? keys + .map((key) => + Array.isArray(options[key]) + ? `&${key}=${options[key].join(";")}` + : `&${key}=${options[key]}` + ) + .join("") + : ""; + + const id = `${src}?${params.slice(1)}`; + + const fullPath = await getSrcPath(id); + + const { default: load } = await import("../../plugin/hooks/load.js"); + + // @ts-ignore + const srcset = (await load(fullPath, base)).slice(16, -1); + + return srcset; +} diff --git a/packages/imagetools/api/utils/getStyleElement.js b/packages/imagetools/api/utils/getStyleElement.js new file mode 100644 index 0000000..30ad4d7 --- /dev/null +++ b/packages/imagetools/api/utils/getStyleElement.js @@ -0,0 +1,15 @@ +// @ts-check +import getAttributesString from "./getAttributesString.js"; + +export default function getStyleElement({ + styleAttributes, + backgroundStyles = "", +}) { + const attributesString = getAttributesString({ + attributes: styleAttributes, + }); + + const styleElement = ``; + + return styleElement; +} diff --git a/packages/imagetools/api/utils/imagetools.js b/packages/imagetools/api/utils/imagetools.js new file mode 100644 index 0000000..530abd1 --- /dev/null +++ b/packages/imagetools/api/utils/imagetools.js @@ -0,0 +1,40 @@ +// @ts-check +import { + builtins, + loadImage, + applyTransforms, + generateTransforms, +} from "imagetools-core"; +export { + loadImage +} from "imagetools-core"; +export async function getImageDetails(path, width, height, aspect) { + const loadedImage = loadImage(path); + + if (aspect && !width && !height) { + if (!width && !height) { + ({ width } = await loadedImage.metadata()); + } + + if (width) { + height = width / aspect; + } + + if (height) { + width = height * aspect; + } + } + + const { image, metadata } = await applyTransforms( + generateTransforms({ width, height }, builtins).transforms, + loadedImage + ); + + const { + width: imageWidth, + height: imageHeight, + format: imageFormat, + } = metadata; + + return { image, imageWidth, imageHeight, imageFormat }; +} diff --git a/packages/imagetools/api/utils/throwErrorIfUnsupported.js b/packages/imagetools/api/utils/throwErrorIfUnsupported.js new file mode 100644 index 0000000..581ca16 --- /dev/null +++ b/packages/imagetools/api/utils/throwErrorIfUnsupported.js @@ -0,0 +1,14 @@ +// @ts-check +import { supportedImageTypes } from "../../utils/runtimeChecks.js"; + +export default function throwErrorIfUnsupported(src, ext) { + if (!ext && typeof ext !== "string") { + throw new Error(`Failed to load ${src}; Invalid image format`); + } + + if (ext && !supportedImageTypes.includes(ext.toLowerCase())) { + throw new Error( + `Failed to load ${src}; Invalid image format ${ext} or the format is not supported by astro-imagetools` + ); + } +} diff --git a/packages/imagetools/astroViteConfigs.js b/packages/imagetools/astroViteConfigs.js new file mode 100644 index 0000000..8b2d327 --- /dev/null +++ b/packages/imagetools/astroViteConfigs.js @@ -0,0 +1,12 @@ +export default { + "environment": "dev", + "isSsrBuild": false, + "projectBase": "", + "publicDir": "C:\\Users\\zx\\Desktop\\polymech\\site2\\public\\", + "rootDir": "C:\\Users\\zx\\Desktop\\polymech\\site2\\", + "mode": "dev", + "outDir": "dist", + "assetsDir": "/_astro", + "sourcemap": false, + "assetFileNames": "/_astro/[name]@[width].[hash][extname]" +} \ No newline at end of file diff --git a/packages/imagetools/components/BackgroundImage.astro b/packages/imagetools/components/BackgroundImage.astro new file mode 100644 index 0000000..47d2b44 --- /dev/null +++ b/packages/imagetools/components/BackgroundImage.astro @@ -0,0 +1,46 @@ +--- +import renderBackgroundImage from "../api/renderBackgroundImage.js"; +import type { BackgroundImageConfigOptions } from "../types.d"; + +const content = await Astro.slots.render("default"); + +declare interface Props + extends Pick< + BackgroundImageConfigOptions, + Exclude + > {} + +const { link, style, htmlElement } = await renderBackgroundImage({ + content, + ...(Astro.props as Props), +}); +--- + + + + diff --git a/packages/imagetools/components/BackgroundPicture.astro b/packages/imagetools/components/BackgroundPicture.astro new file mode 100644 index 0000000..a53bab8 --- /dev/null +++ b/packages/imagetools/components/BackgroundPicture.astro @@ -0,0 +1,19 @@ +--- +import renderBackgroundPicture from "../api/renderBackgroundPicture.js"; +import { BackgroundPictureConfigOptions } from "../types.d"; + +declare interface Props + extends Pick< + BackgroundPictureConfigOptions, + Exclude + > {} + +const content = await Astro.slots.render("default"); + +const { link, style, htmlElement } = await renderBackgroundPicture({ + content, + ...(Astro.props as Props), +}); +--- + + diff --git a/packages/imagetools/components/Image.astro b/packages/imagetools/components/Image.astro new file mode 100644 index 0000000..d2d547a --- /dev/null +++ b/packages/imagetools/components/Image.astro @@ -0,0 +1,10 @@ +--- +import renderImage from "../api/renderImage.js"; +import type { PictureConfigOptions as ImageConfigOptions } from "../types.d"; + +const { link, style, image } = await renderImage( + Astro.props as ImageConfigOptions +); +--- + + diff --git a/packages/imagetools/components/ImageSupportDetection.astro b/packages/imagetools/components/ImageSupportDetection.astro new file mode 100644 index 0000000..9e62ae7 --- /dev/null +++ b/packages/imagetools/components/ImageSupportDetection.astro @@ -0,0 +1,4 @@ + + diff --git a/packages/imagetools/components/Img.astro b/packages/imagetools/components/Img.astro new file mode 100644 index 0000000..36c03ab --- /dev/null +++ b/packages/imagetools/components/Img.astro @@ -0,0 +1,10 @@ +--- +import renderImg from "../api/renderImg.js"; +import type { ImgConfigOptions } from "../types.d"; + +declare interface Props extends ImgConfigOptions {} + +const { link, style, img } = await renderImg(Astro.props as Props); +--- + + diff --git a/packages/imagetools/components/Picture.astro b/packages/imagetools/components/Picture.astro new file mode 100644 index 0000000..737bd77 --- /dev/null +++ b/packages/imagetools/components/Picture.astro @@ -0,0 +1,10 @@ +--- +import renderPicture from "../api/renderPicture.js"; +import type { PictureConfigOptions } from "../types.d"; + +declare interface Props extends PictureConfigOptions {} + +const { link, style, picture } = await renderPicture(Astro.props as Props); +--- + + diff --git a/packages/imagetools/components/index.js b/packages/imagetools/components/index.js new file mode 100644 index 0000000..a6c6389 --- /dev/null +++ b/packages/imagetools/components/index.js @@ -0,0 +1,5 @@ +export { default as Img } from "./Img.astro"; +export { default as Picture } from "./Picture.astro"; +export { default as BackgroundImage } from "./BackgroundImage.astro"; +export { default as BackgroundPicture } from "./BackgroundPicture.astro"; +export { default as ImageSupportDetection } from "./ImageSupportDetection.astro"; diff --git a/packages/imagetools/config.d.ts b/packages/imagetools/config.d.ts new file mode 100644 index 0000000..8569ca9 --- /dev/null +++ b/packages/imagetools/config.d.ts @@ -0,0 +1,3 @@ +import type { GlobalConfigOptions } from "./types"; + +export function defineConfig(config: GlobalConfigOptions): GlobalConfigOptions; diff --git a/packages/imagetools/config.mjs b/packages/imagetools/config.mjs new file mode 100644 index 0000000..64a4c49 --- /dev/null +++ b/packages/imagetools/config.mjs @@ -0,0 +1,3 @@ +export function defineConfig(config) { + return config; +} diff --git a/packages/imagetools/demo/.npmrc b/packages/imagetools/demo/.npmrc new file mode 100644 index 0000000..0cc653b --- /dev/null +++ b/packages/imagetools/demo/.npmrc @@ -0,0 +1,2 @@ +## force pnpm to hoist +shamefully-hoist = true \ No newline at end of file diff --git a/packages/imagetools/demo/.stackblitzrc b/packages/imagetools/demo/.stackblitzrc new file mode 100644 index 0000000..0dfa8f1 --- /dev/null +++ b/packages/imagetools/demo/.stackblitzrc @@ -0,0 +1,6 @@ +{ + "startCommand": "npm start", + "env": { + "ENABLE_CJS_IMPORTS": true + } +} diff --git a/packages/imagetools/demo/README.md b/packages/imagetools/demo/README.md new file mode 100644 index 0000000..777dd8e --- /dev/null +++ b/packages/imagetools/demo/README.md @@ -0,0 +1,5 @@ +# Astro ImageTools Live Examples + +This repository contains source code for the [**Astro ImageTools Demo**](https://astro-imagetools-demo.vercel.app) website. + +The demo displays live examples of the components and APIs provided by the [**Astro ImageTools**](https://npmjs.com/package/astro-imagetools) library and the **Layouts** and **Placeholders** supported by the library. diff --git a/packages/imagetools/demo/astro-imagetools.config.mjs b/packages/imagetools/demo/astro-imagetools.config.mjs new file mode 100644 index 0000000..b48b079 --- /dev/null +++ b/packages/imagetools/demo/astro-imagetools.config.mjs @@ -0,0 +1,3 @@ +import { defineConfig } from "astro-imagetools/config"; + +export default defineConfig({}); diff --git a/packages/imagetools/demo/astro.config.mjs b/packages/imagetools/demo/astro.config.mjs new file mode 100644 index 0000000..c46819e --- /dev/null +++ b/packages/imagetools/demo/astro.config.mjs @@ -0,0 +1,23 @@ +import { defineConfig } from "astro/config"; +import { astroImageTools } from "astro-imagetools"; + +// https://astro.build/config +export default defineConfig({ + vite: { + plugins: [ + { + name: "import.meta.url-transformer", + transform: (code, id) => { + if (id.endsWith(".astro")) + return code.replace(/import.meta.url/g, `"${id}"`); + }, + }, + ], + }, + + experimental: { + integrations: true, + }, + + integrations: [astroImageTools], +}); diff --git a/packages/imagetools/demo/package.json b/packages/imagetools/demo/package.json new file mode 100644 index 0000000..2a25773 --- /dev/null +++ b/packages/imagetools/demo/package.json @@ -0,0 +1,23 @@ +{ + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview" + }, + "dependencies": { + "astro-spa": "^1.3.9", + "react": "^18.2.0", + "react-dom": "^18.2.0" + }, + "devDependencies": { + "@astrojs/lit": "^1.1.2", + "@astrojs/preact": "^2.0.2", + "@astrojs/react": "^2.0.2", + "@astrojs/solid-js": "^2.0.2", + "@astrojs/svelte": "^2.0.1", + "@astrojs/vue": "^2.0.1", + "astro": "^2.0.6", + "astro-imagetools": "workspace:^0.9.0" + } +} diff --git a/packages/imagetools/demo/public/favicon.ico b/packages/imagetools/demo/public/favicon.ico new file mode 100644 index 0000000..578ad45 Binary files /dev/null and b/packages/imagetools/demo/public/favicon.ico differ diff --git a/packages/imagetools/demo/public/images/public.jpeg b/packages/imagetools/demo/public/images/public.jpeg new file mode 100644 index 0000000..d5b648a Binary files /dev/null and b/packages/imagetools/demo/public/images/public.jpeg differ diff --git a/packages/imagetools/demo/sandbox.config.json b/packages/imagetools/demo/sandbox.config.json new file mode 100644 index 0000000..b12019e --- /dev/null +++ b/packages/imagetools/demo/sandbox.config.json @@ -0,0 +1,11 @@ +{ + "infiniteLoopProtection": true, + "hardReloadOnChange": false, + "view": "browser", + "template": "node", + "container": { + "port": 3000, + "startScript": "start", + "node": "16" + } +} diff --git a/packages/imagetools/demo/src/env.d.ts b/packages/imagetools/demo/src/env.d.ts new file mode 100644 index 0000000..f964fe0 --- /dev/null +++ b/packages/imagetools/demo/src/env.d.ts @@ -0,0 +1 @@ +/// diff --git a/packages/imagetools/demo/src/images/elva-480w-close-portrait.jpg b/packages/imagetools/demo/src/images/elva-480w-close-portrait.jpg new file mode 100644 index 0000000..0ea3a05 Binary files /dev/null and b/packages/imagetools/demo/src/images/elva-480w-close-portrait.jpg differ diff --git a/packages/imagetools/demo/src/images/elva-800w.jpg b/packages/imagetools/demo/src/images/elva-800w.jpg new file mode 100644 index 0000000..d2f052e Binary files /dev/null and b/packages/imagetools/demo/src/images/elva-800w.jpg differ diff --git a/packages/imagetools/demo/src/layouts/LayoutsLayout.astro b/packages/imagetools/demo/src/layouts/LayoutsLayout.astro new file mode 100644 index 0000000..c2d0000 --- /dev/null +++ b/packages/imagetools/demo/src/layouts/LayoutsLayout.astro @@ -0,0 +1,15 @@ +--- +import { Picture } from "astro-imagetools/components"; +import MainLayout from "./MainLayout.astro"; + +const { layout, importMetaUrl } = Astro.props; +--- + + +

{layout} Layout Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/layouts/MainLayout.astro b/packages/imagetools/demo/src/layouts/MainLayout.astro new file mode 100644 index 0000000..3012534 --- /dev/null +++ b/packages/imagetools/demo/src/layouts/MainLayout.astro @@ -0,0 +1,57 @@ +--- +import { Spa } from "astro-spa"; +import "../styles/index.css"; + +const { importMetaUrl } = Astro.props as { importMetaUrl: string }; + +const path = + Astro.props.content?.path || + importMetaUrl?.slice(importMetaUrl.indexOf("/pages/") + 7); + +const GitHubURL = `https://github.com/RafidMuhymin/astro-imagetools/tree/main/demo/src/pages/${path}`; +--- + + + + + + + + + + +
+ + + + + + + + + +
+ + + + diff --git a/packages/imagetools/demo/src/layouts/PlaceholderLayout.astro b/packages/imagetools/demo/src/layouts/PlaceholderLayout.astro new file mode 100644 index 0000000..809c2f4 --- /dev/null +++ b/packages/imagetools/demo/src/layouts/PlaceholderLayout.astro @@ -0,0 +1,18 @@ +--- +import { Picture } from "astro-imagetools/components"; +import MainLayout from "./MainLayout.astro"; + +const { placeholder, importMetaUrl } = Astro.props; +--- + + +

{placeholder} Placeholder Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/pages/api/renderBackgroundImage.astro b/packages/imagetools/demo/src/pages/api/renderBackgroundImage.astro new file mode 100644 index 0000000..93cf23c --- /dev/null +++ b/packages/imagetools/demo/src/pages/api/renderBackgroundImage.astro @@ -0,0 +1,48 @@ +--- +import { ImageSupportDetection } from "astro-imagetools/components"; +import { renderBackgroundImage } from "astro-imagetools/api"; +import MainLayout from "../../layouts/MainLayout.astro"; + +const { link, style, htmlElement } = await renderBackgroundImage({ + src: "https://picsum.photos/1024/768/", + content: `

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eveniet, nisi! + Commodi, dolor hic omnis debitis natus eaque nisi magni corrupti earum + aliquam at quidem dolorum? +

+ +

+ Eos facere amet nesciunt! Vero, culpa eaque quasi ullam atque alias + repudiandae facere placeat ipsam recusandae quam minus nemo officia + reiciendis dicta quaerat maiores omnis. +

+ +

+ Pariatur doloribus, facilis enim accusamus velit, amet ducimus dolorum + unde numquam doloremque eveniet eum et error, quod quas fugit commodi + suscipit sequi. At, deleniti nihil. +

+ +

+ Laborum voluptate maxime dicta alias minus nam, doloribus accusantium + veritatis perferendis, expedita eaque. Deleniti deserunt, iure dolorum + itaque fugiat assumenda ullam amet asperiores soluta ipsam! +

+ +

+ Veniam qui ad, illo fuga autem voluptatibus iusto cum reprehenderit error. + Nemo nisi laborum blanditiis, accusamus dolores harum labore perspiciatis. + Nesciunt, repellat mollitia. Rem, labore? +

`, +}); +--- + + + + +

Astro ImageTools {"renderBackgroundImage"} API Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/pages/api/renderBackgroundPicture.astro b/packages/imagetools/demo/src/pages/api/renderBackgroundPicture.astro new file mode 100644 index 0000000..1324eb3 --- /dev/null +++ b/packages/imagetools/demo/src/pages/api/renderBackgroundPicture.astro @@ -0,0 +1,45 @@ +--- +import { renderBackgroundPicture } from "astro-imagetools/api"; +import MainLayout from "../../layouts/MainLayout.astro"; + +const { link, style, htmlElement } = await renderBackgroundPicture({ + src: "https://picsum.photos/1024/768/", + content: `

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eveniet, nisi! + Commodi, dolor hic omnis debitis natus eaque nisi magni corrupti earum + aliquam at quidem dolorum? +

+ +

+ Eos facere amet nesciunt! Vero, culpa eaque quasi ullam atque alias + repudiandae facere placeat ipsam recusandae quam minus nemo officia + reiciendis dicta quaerat maiores omnis. +

+ +

+ Pariatur doloribus, facilis enim accusamus velit, amet ducimus dolorum + unde numquam doloremque eveniet eum et error, quod quas fugit commodi + suscipit sequi. At, deleniti nihil. +

+ +

+ Laborum voluptate maxime dicta alias minus nam, doloribus accusantium + veritatis perferendis, expedita eaque. Deleniti deserunt, iure dolorum + itaque fugiat assumenda ullam amet asperiores soluta ipsam! +

+ +

+ Veniam qui ad, illo fuga autem voluptatibus iusto cum reprehenderit error. + Nemo nisi laborum blanditiis, accusamus dolores harum labore perspiciatis. + Nesciunt, repellat mollitia. Rem, labore? +

`, +}); +--- + + +

Astro ImageTools {"renderBackgroundPicture"} API Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/pages/api/renderImg.astro b/packages/imagetools/demo/src/pages/api/renderImg.astro new file mode 100644 index 0000000..313f18d --- /dev/null +++ b/packages/imagetools/demo/src/pages/api/renderImg.astro @@ -0,0 +1,17 @@ +--- +import { renderImg } from "astro-imagetools/api"; +import MainLayout from "../../layouts/MainLayout.astro"; + +const { link, style, img } = await renderImg({ + src: "https://picsum.photos/1024/768/", + alt: "A random image", +}); +--- + + +

Astro ImageTools {"renderImg"} API Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/pages/api/renderPicture.astro b/packages/imagetools/demo/src/pages/api/renderPicture.astro new file mode 100644 index 0000000..fe8abdf --- /dev/null +++ b/packages/imagetools/demo/src/pages/api/renderPicture.astro @@ -0,0 +1,17 @@ +--- +import { renderPicture } from "astro-imagetools/api"; +import MainLayout from "../../layouts/MainLayout.astro"; + +const { link, style, picture } = await renderPicture({ + src: "https://picsum.photos/1024/768/", + alt: "A random image", +}); +--- + + +

Astro ImageTools {"renderPicture"} API Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/pages/components/BackgroundImage.astro b/packages/imagetools/demo/src/pages/components/BackgroundImage.astro new file mode 100644 index 0000000..aef8bdf --- /dev/null +++ b/packages/imagetools/demo/src/pages/components/BackgroundImage.astro @@ -0,0 +1,45 @@ +--- +import { + BackgroundImage, + ImageSupportDetection, +} from "astro-imagetools/components"; +import MainLayout from "../../layouts/MainLayout.astro"; +--- + + + + +

+ Astro ImageTools {""} Component Example +

+ +
+ + +

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eveniet, nisi! + Commodi, dolor hic omnis debitis natus eaque nisi magni corrupti earum + aliquam at quidem dolorum? +

+

+ Eos facere amet nesciunt! Vero, culpa eaque quasi ullam atque alias + repudiandae facere placeat ipsam recusandae quam minus nemo officia + reiciendis dicta quaerat maiores omnis. +

+

+ Pariatur doloribus, facilis enim accusamus velit, amet ducimus dolorum + unde numquam doloremque eveniet eum et error, quod quas fugit commodi + suscipit sequi. At, deleniti nihil. +

+

+ Laborum voluptate maxime dicta alias minus nam, doloribus accusantium + veritatis perferendis, expedita eaque. Deleniti deserunt, iure dolorum + itaque fugiat assumenda ullam amet asperiores soluta ipsam! +

+

+ Veniam qui ad, illo fuga autem voluptatibus iusto cum reprehenderit error. + Nemo nisi laborum blanditiis, accusamus dolores harum labore perspiciatis. + Nesciunt, repellat mollitia. Rem, labore? +

+ + diff --git a/packages/imagetools/demo/src/pages/components/BackgroundPicture.astro b/packages/imagetools/demo/src/pages/components/BackgroundPicture.astro new file mode 100644 index 0000000..871d97c --- /dev/null +++ b/packages/imagetools/demo/src/pages/components/BackgroundPicture.astro @@ -0,0 +1,40 @@ +--- +import { BackgroundPicture } from "astro-imagetools/components"; +import MainLayout from "../../layouts/MainLayout.astro"; +--- + + +

+ Astro ImageTools {""} Component Example +

+ +
+ + +

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eveniet, nisi! + Commodi, dolor hic omnis debitis natus eaque nisi magni corrupti earum + aliquam at quidem dolorum? +

+

+ Eos facere amet nesciunt! Vero, culpa eaque quasi ullam atque alias + repudiandae facere placeat ipsam recusandae quam minus nemo officia + reiciendis dicta quaerat maiores omnis. +

+

+ Pariatur doloribus, facilis enim accusamus velit, amet ducimus dolorum + unde numquam doloremque eveniet eum et error, quod quas fugit commodi + suscipit sequi. At, deleniti nihil. +

+

+ Laborum voluptate maxime dicta alias minus nam, doloribus accusantium + veritatis perferendis, expedita eaque. Deleniti deserunt, iure dolorum + itaque fugiat assumenda ullam amet asperiores soluta ipsam! +

+

+ Veniam qui ad, illo fuga autem voluptatibus iusto cum reprehenderit error. + Nemo nisi laborum blanditiis, accusamus dolores harum labore perspiciatis. + Nesciunt, repellat mollitia. Rem, labore? +

+ + diff --git a/packages/imagetools/demo/src/pages/components/Img.astro b/packages/imagetools/demo/src/pages/components/Img.astro new file mode 100644 index 0000000..3f6eb9b --- /dev/null +++ b/packages/imagetools/demo/src/pages/components/Img.astro @@ -0,0 +1,12 @@ +--- +import { Img } from "astro-imagetools/components"; +import MainLayout from "../../layouts/MainLayout.astro"; +--- + + +

Astro ImageTools {""} Component Example

+ +
+ + A random image + diff --git a/packages/imagetools/demo/src/pages/components/Picture.astro b/packages/imagetools/demo/src/pages/components/Picture.astro new file mode 100644 index 0000000..b617e39 --- /dev/null +++ b/packages/imagetools/demo/src/pages/components/Picture.astro @@ -0,0 +1,12 @@ +--- +import { Picture } from "astro-imagetools/components"; +import MainLayout from "../../layouts/MainLayout.astro"; +--- + + +

Astro ImageTools {""} Component Example

+ +
+ + + diff --git a/packages/imagetools/demo/src/pages/index.md b/packages/imagetools/demo/src/pages/index.md new file mode 100644 index 0000000..66d5df0 --- /dev/null +++ b/packages/imagetools/demo/src/pages/index.md @@ -0,0 +1,78 @@ +--- +path: index.md +layout: ../layouts/MainLayout.astro +--- + +# Image Optimization in Astro with Astro ImageTools + +This page demonstrates the usage of the [astro-imagetools](https://www.npmjs.com/package/astro-imagetools) library with live examples. + +
+ +## Components + +- [`` Component](/components/Img) +- [`` Component](/components/Picture) +- [`` Component](/components/BackgroundImage) +- [`` Component](/components/BackgroundPicture) + +## APIs + +- [`renderImg` API](/api/renderImg) +- [`renderPicture` API](/api/renderPicture) +- [`renderBackgroundImage` API](/api/renderBackgroundImage) +- [`renderBackgroundPicture` API](/api/renderBackgroundPicture) + +## Layout + +The `layout` property tells the image to respond differently depending on the device size or the container size. + +Select a layout below and try resizing the window or rotating your device to see how the image reacts. + +- [Constrained Layout](/layout/constrained) +- [Fixed Layout](/layout/fixed) +- [Full Width Layout](/layout/fullWidth) +- [Fill Layout](/layout/fill) + +
+ +## Placeholder + +The `placeholder` property tells the image what to show while loading. + +- [Blurred Placeholder](/placeholder/blurred) +- [Dominant Color Placeholder](/placeholder/dominantColor) +- [Traced SVG Placeholder](/placeholder/tracedSVG) +- [No Placeholder](/placeholder/none) + +
+ +## Internal Image + +The following is an example of a reference to an internal image in the `src` directory (`../images/elva-800w.jpg`). + +![A father holding his beloved daughter in his arms](../images/elva-800w.jpg) + +
+ +## External Image + +The following is an example of a reference to an external image (`https://picsum.photos/1024/768`). + +![A random image](https://picsum.photos/1024/768) + +
+ +## Image in /public + +This image is in the public directory (`/images/public.jpeg`). + +![A random image](/images/public.jpeg) + +
+ +## Learn More + +You can optionally configure many more things! + +Checkout the [Astro ImageTools](https://astro-imagetools-docs.vercel.app/) documentation to learn more. diff --git a/packages/imagetools/demo/src/pages/layout/constrained.astro b/packages/imagetools/demo/src/pages/layout/constrained.astro new file mode 100644 index 0000000..669994d --- /dev/null +++ b/packages/imagetools/demo/src/pages/layout/constrained.astro @@ -0,0 +1,5 @@ +--- +import LayoutsLayout from "../../layouts/LayoutsLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/layout/fill.astro b/packages/imagetools/demo/src/pages/layout/fill.astro new file mode 100644 index 0000000..01d5e0f --- /dev/null +++ b/packages/imagetools/demo/src/pages/layout/fill.astro @@ -0,0 +1,5 @@ +--- +import LayoutsLayout from "../../layouts/LayoutsLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/layout/fixed.astro b/packages/imagetools/demo/src/pages/layout/fixed.astro new file mode 100644 index 0000000..65e626c --- /dev/null +++ b/packages/imagetools/demo/src/pages/layout/fixed.astro @@ -0,0 +1,5 @@ +--- +import LayoutsLayout from "../../layouts/LayoutsLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/layout/fullWidth.astro b/packages/imagetools/demo/src/pages/layout/fullWidth.astro new file mode 100644 index 0000000..b822c52 --- /dev/null +++ b/packages/imagetools/demo/src/pages/layout/fullWidth.astro @@ -0,0 +1,5 @@ +--- +import LayoutsLayout from "../../layouts/LayoutsLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/placeholder/blurred.astro b/packages/imagetools/demo/src/pages/placeholder/blurred.astro new file mode 100644 index 0000000..1fee26c --- /dev/null +++ b/packages/imagetools/demo/src/pages/placeholder/blurred.astro @@ -0,0 +1,5 @@ +--- +import PlaceholderLayout from "../../layouts/PlaceholderLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/placeholder/dominantColor.astro b/packages/imagetools/demo/src/pages/placeholder/dominantColor.astro new file mode 100644 index 0000000..5a9b6c9 --- /dev/null +++ b/packages/imagetools/demo/src/pages/placeholder/dominantColor.astro @@ -0,0 +1,5 @@ +--- +import PlaceholderLayout from "../../layouts/PlaceholderLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/placeholder/none.astro b/packages/imagetools/demo/src/pages/placeholder/none.astro new file mode 100644 index 0000000..293dc79 --- /dev/null +++ b/packages/imagetools/demo/src/pages/placeholder/none.astro @@ -0,0 +1,5 @@ +--- +import PlaceholderLayout from "../../layouts/PlaceholderLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/pages/placeholder/tracedSVG.astro b/packages/imagetools/demo/src/pages/placeholder/tracedSVG.astro new file mode 100644 index 0000000..9e3393a --- /dev/null +++ b/packages/imagetools/demo/src/pages/placeholder/tracedSVG.astro @@ -0,0 +1,5 @@ +--- +import PlaceholderLayout from "../../layouts/PlaceholderLayout.astro"; +--- + + diff --git a/packages/imagetools/demo/src/styles/index.css b/packages/imagetools/demo/src/styles/index.css new file mode 100644 index 0000000..518e741 --- /dev/null +++ b/packages/imagetools/demo/src/styles/index.css @@ -0,0 +1,19 @@ +main { + padding: 1.5rem; + background-color: black; + color: white; +} + +code::before { + content: "`"; +} + +code::after { + content: "`"; +} + +.view-source { + position: fixed; + top: 0; + right: 0; +} diff --git a/packages/imagetools/docs/.npmrc b/packages/imagetools/docs/.npmrc new file mode 100644 index 0000000..ef83021 --- /dev/null +++ b/packages/imagetools/docs/.npmrc @@ -0,0 +1,2 @@ +# Expose Astro dependencies for `pnpm` users +shamefully-hoist=true diff --git a/packages/imagetools/docs/.stackblitzrc b/packages/imagetools/docs/.stackblitzrc new file mode 100644 index 0000000..43798ec --- /dev/null +++ b/packages/imagetools/docs/.stackblitzrc @@ -0,0 +1,6 @@ +{ + "startCommand": "npm start", + "env": { + "ENABLE_CJS_IMPORTS": true + } +} \ No newline at end of file diff --git a/packages/imagetools/docs/README.md b/packages/imagetools/docs/README.md new file mode 100644 index 0000000..984e496 --- /dev/null +++ b/packages/imagetools/docs/README.md @@ -0,0 +1,97 @@ +# Astro ImageTools Docs Astro logo + +To all who come to this happy place: welcome. + +This is the repo for [https://astro-imagetools-docs.vercel.app/](https://astro-imagetools-docs.vercel.app/). +This repo contains all the source code to build the docs site. + +## We are Astro + +Astro is a site builder for the web platform. +We want everyone to be successful building sites, and that means helping everyone understand how Astro works. + +## You are Awesome + +You can also help make the docs awesome. +Your feedback is welcome. +Your writing, editing, translating, designing, and developing skills are welcome. +You being a part of our community is welcome. + +## Chat with Us + +You can learn more about Astro, get support, and meet other devs in [our Discord community](https://astro.build/chat). + +## Raise an Issue + +Is something missing? +Is something wrong? +Could something be better? +Issues are a quick way for you to offer us feedback about the docs. + +Before you share, please [see if your issue has already been reported](https://github.com/RafidMuhymin/astro-imagetools/issues). + +## Edit a Page + +Every page on [https://astro-imagetools-docs.vercel.app/](https://astro-imagetools-docs.vercel.app/) has an **Edit this page** button in the sidebar. +You can click that button to edit the source code for that page in **GitHub**. + +After you make your changes, click **Commit changes**. +This will automatically create a [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) of the docs in your GitHub account with the changes. + +Once your edits are ready in GitHub, follow the prompts to **create a pull request** and submit your changes for review. + +## Develop + +To begin developing locally, checkout this project from your machine. + +```shell +git clone git@github.com:RafidMuhymin/astro-imagetools.git +``` + +You can install and run the project locally using [pnpm](https://pnpm.io/). Head to [the pnpm installation guide](https://pnpm.io/installation) to get that set up. Then, run the following from your terminal: + +```shell +pnpm install + +pnpm dev +``` + +If you’re copying these instructions, remember to [configure this project as a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork). + +```shell +git remote add upstream git@github.com:RafidMuhymin/astro-imagetools.git +``` + +At any point, create a branch for your contribution. +We are not strict about branch names. + +```shell +git checkout -b add/klingon-language +``` + +That’s it. +As you [open a pull request](https://github.com/withastro/astro/compare), please include a clear title and description. + +```markdown +# Add Klingon language to Getting Started page + +This adds the Klingon language and also updates the sidebar and language selection components. +``` + +Thank you for helping make the docs awesome. +And please, [come chat with us](https://astro.build/chat) if you have any questions. + +## Deploy + +Every pull request generates a preview using **Vercel** for anyone to see. + +Use the **Deploy Preview** of your pull request to review and share your changes. + +The docs site will be automatically updated whenever pull requests are merged. + +## Next Steps + +- [Read the docs](https://astro-imagetools-docs.vercel.app/) +- [Fork the project](https://github.com/RafidMuhymin/astro-imagetools/fork) +- [Raise an issue](https://github.com/RafidMuhymin/astro-imagetools/issues/new) +- [Discuss the docs](https://discord.gg/cZDZU3hJHc) diff --git a/packages/imagetools/docs/astro.config.mjs b/packages/imagetools/docs/astro.config.mjs new file mode 100644 index 0000000..1cb4233 --- /dev/null +++ b/packages/imagetools/docs/astro.config.mjs @@ -0,0 +1,25 @@ +import mdx from "@astrojs/mdx"; +import react from "@astrojs/react"; +import preact from "@astrojs/preact"; +import { defineConfig } from "astro/config"; +import AutoImport from "unplugin-auto-import/vite"; + +// https://astro.build/config +export default defineConfig({ + site: "https://astro-imagetools-docs.vercel.app/", + integrations: [preact(), react(), mdx()], + vite: { + plugins: [ + AutoImport({ + include: [/\.astro$/, /\.mdx$/], + imports: [ + { + "@astrojs/markdown-component": [["default", "Markdown"]], + "/src/components/CodeExample.astro": [["default", "CodeExample"]], + }, + ], + dts: "./auto-imports.d.ts", + }), + ], + }, +}); diff --git a/packages/imagetools/docs/auto-imports.d.ts b/packages/imagetools/docs/auto-imports.d.ts new file mode 100644 index 0000000..4ca0671 --- /dev/null +++ b/packages/imagetools/docs/auto-imports.d.ts @@ -0,0 +1,7 @@ +// Generated by 'unplugin-auto-import' +export {}; + +declare global { + const CodeExample: typeof import("../../../src/components/CodeExample.astro")["default"]; + const Markdown: typeof import("@astrojs/markdown-component")["default"]; +} diff --git a/packages/imagetools/docs/package.json b/packages/imagetools/docs/package.json new file mode 100644 index 0000000..44f0b83 --- /dev/null +++ b/packages/imagetools/docs/package.json @@ -0,0 +1,28 @@ +{ + "name": "@example/docs", + "version": "0.0.1", + "private": true, + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview" + }, + "dependencies": { + "@algolia/client-search": "^4.14.3", + "@astrojs/markdown-component": "^1.0.2", + "@astrojs/mdx": "^0.14.0", + "@docsearch/css": "^3.3.2", + "@docsearch/react": "^3.3.2", + "@types/react": "^18.0.26", + "preact": "^10.11.3", + "react": "^18.2.0", + "react-dom": "^18.2.0", + "unplugin-auto-import": "^0.9.5" + }, + "devDependencies": { + "@astrojs/preact": "^0.2.0", + "@astrojs/react": "^0.2.1", + "astro": "^1.9.2" + } +} diff --git a/packages/imagetools/docs/public/default-og-image.png b/packages/imagetools/docs/public/default-og-image.png new file mode 100644 index 0000000..9790320 Binary files /dev/null and b/packages/imagetools/docs/public/default-og-image.png differ diff --git a/packages/imagetools/docs/public/favicon.ico b/packages/imagetools/docs/public/favicon.ico new file mode 100644 index 0000000..578ad45 Binary files /dev/null and b/packages/imagetools/docs/public/favicon.ico differ diff --git a/packages/imagetools/docs/public/make-scrollable-code-focusable.js b/packages/imagetools/docs/public/make-scrollable-code-focusable.js new file mode 100644 index 0000000..6fbf1ee --- /dev/null +++ b/packages/imagetools/docs/public/make-scrollable-code-focusable.js @@ -0,0 +1,3 @@ +Array.from(document.getElementsByTagName("pre")).forEach((element) => { + element.setAttribute("tabindex", "0"); +}); diff --git a/packages/imagetools/docs/sandbox.config.json b/packages/imagetools/docs/sandbox.config.json new file mode 100644 index 0000000..9178af7 --- /dev/null +++ b/packages/imagetools/docs/sandbox.config.json @@ -0,0 +1,11 @@ +{ + "infiniteLoopProtection": true, + "hardReloadOnChange": false, + "view": "browser", + "template": "node", + "container": { + "port": 3000, + "startScript": "start", + "node": "14" + } +} diff --git a/packages/imagetools/docs/src/components/CodeExample.astro b/packages/imagetools/docs/src/components/CodeExample.astro new file mode 100644 index 0000000..92ae1f5 --- /dev/null +++ b/packages/imagetools/docs/src/components/CodeExample.astro @@ -0,0 +1,83 @@ +--- +import { Code } from "astro/components"; + +const { values, global, api, component } = Astro.props; + +const isJS = component ? false : true; + +const isGlobal = global; + +const comment = (text) => (isJS ? `// ${text}` : ``) + "\n"; + +function formatValue(value) { + let formattedValue = ["number", "boolean", "function"].includes(typeof value) + ? `${value}` + : Array.isArray(value) + ? `${value[0]}` + : typeof value === "string" && + (value.startsWith("{") || value.startsWith("[")) + ? value + : `"${value}"`; + + if (typeof value === "function") { + formattedValue = formattedValue.replaceAll(/\n\s+/g, "\n "); + + formattedValue = formattedValue.replace(/\n\s+\}$/, "\n }"); + } + + if (component) { + (formattedValue.startsWith("{") || + formattedValue.startsWith("[") || + ["number", "boolean", "function"].includes(typeof value) || + Array.isArray(value)) && + (formattedValue = `{${formattedValue}}`); + } + + return formattedValue; +} + +function code(props, { api, component }) { + const builtProps = Object.keys(props) + .filter((key) => + isGlobal + ? ["src", "alt", "tag", "content", "artDirectives"].includes(key) + ? false + : true + : true + ) + .map((key) => + key === "comment" + ? `/* ${props[key]} */` + : key + (isJS ? ": " : "=") + `${formatValue(props[key])}` + ) + .join(`${isJS ? "," : ""}\n `); + + return ( + `${ + isJS + ? isGlobal + ? `export default defineConfig({` + : `const renderedHTML = await ${api}({` + : `<${component}` + } + ${builtProps}${isJS ? "," : ""} +${isJS ? `});` : `/>`}` + "\n" + ); +} + +const codeBlock = values + .map((value) => + value === "" + ? "\n" + : typeof value === "string" + ? comment(value) + : Array.isArray(value) + ? isJS + ? value.filter((value) => value !== "---").join("\n") + "\n" + : value.join("\n") + "\n" + : code(value, { api, component }) + ) + .join(""); +--- + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions.astro b/packages/imagetools/docs/src/components/ConfigOptions.astro new file mode 100644 index 0000000..bc7ed80 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions.astro @@ -0,0 +1,107 @@ +--- +import Src from "@config/src.astro"; +import Alt from "@config/alt.astro"; +import Tag from "@config/tag.astro"; +import Content from "@config/content.astro"; +import Sizes from "@config/sizes.astro"; +import Preload from "@config/preload.astro"; +import Loading from "@config/loading.astro"; +import Decoding from "@config/decoding.astro"; +import Attributes from "@config/attributes.astro"; +import Layout from "@config/layout.astro"; +import Placeholder from "@config/placeholder.astro"; +import BreakPoints from "@config/breakpoints.astro"; +import ObjectFit from "@config/objectFit.astro"; +import ObjectPosition from "@config/objectPosition.astro"; +import BackgroundSize from "@config/backgroundSize.astro"; +import BackgroundPosition from "@config/backgroundPosition.astro"; +import Format from "@config/format.astro"; +import FallbackFormat from "@config/fallbackFormat.astro"; +import IncludeSourceFormat from "@config/includeSourceFormat.astro"; +import FormatOptions from "@config/formatOptions.astro"; +import FadeInTransition from "@config/fadeInTransition.astro"; +import ArtDirectives from "@config/artDirectives.astro"; +import CacheDir from "@config/cacheDir.astro"; +import AssetFileNames from "@config/assetFileNames.astro"; +import Flip from "@config/flip.astro"; +import Flop from "@config/flop.astro"; +import Invert from "@config/invert.astro"; +import Flatten from "@config/flatten.astro"; +import Normalize from "@config/normalize.astro"; +import Grayscale from "@config/grayscale.astro"; +import Hue from "@config/hue.astro"; +import Saturation from "@config/saturation.astro"; +import Brightness from "@config/brightness.astro"; +import Width from "@config/width.astro"; +import Height from "@config/height.astro"; +import Aspect from "@config/aspect.astro"; +import Background from "@config/background.astro"; +import Tint from "@config/tint.astro"; +import Blur from "@config/blur.astro"; +import Median from "@config/median.astro"; +import Rotate from "@config/rotate.astro"; +import Quality from "@config/quality.astro"; +import Fit from "@config/fit.astro"; +import Kernel from "@config/kernel.astro"; +import Position from "@config/position.astro"; + +const { props } = Astro; + +const isGlobal = props.global; + +const { api, component } = props; + +const isBackground = + component?.startsWith("Background") || api?.startsWith("renderBackground"); + +const isBackgroundImage = + component === "BackgroundImage" || api === "renderBackgroundImage"; + +const isNotImg = component !== "Img" && api !== "renderImg"; +--- + +{!isGlobal && } +{!isGlobal && !isBackground && } +{!isGlobal && isBackground && } +{!isGlobal && api && isBackground && } +{!isBackgroundImage && } + +{!isBackgroundImage && } +{!isBackgroundImage && } + +{!isBackground && } + + +{!isBackgroundImage && } +{!isBackgroundImage && } +{isBackgroundImage && } +{isBackgroundImage && } + +{isNotImg && } +{isNotImg && } + +{isNotImg && !isBackgroundImage && } +{!isGlobal && isNotImg && } +{isGlobal && } +{isGlobal && } + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/alt.astro b/packages/imagetools/docs/src/components/ConfigOptions/alt.astro new file mode 100644 index 0000000..a3db1d0 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/alt.astro @@ -0,0 +1,22 @@ + + + ### `alt` + + **Type:** `string` + + **Default:** `undefined` + + The alternative text to display if the image fails to load. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/artDirectives.astro b/packages/imagetools/docs/src/components/ConfigOptions/artDirectives.astro new file mode 100644 index 0000000..98dcb75 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/artDirectives.astro @@ -0,0 +1,115 @@ +--- +const { api, component } = Astro.props; + +const dynamicText = component + ? `${"`"}<${component} />${"`"} component` + : `${"`"}render${api}${"`"} API`; + +const isPicture = + Astro.props.component === "Picture" || Astro.props.api === "renderPicture"; + +const isBackgroundImage = + Astro.props.component === "BackgroundImage" || + Astro.props.api === "renderBackgroundImage"; +--- + + + + ### `artDirectives` + + **Type:** `ArtDirective[]` + + + +{isPicture ? ( + + *An `ArtDirective` object can take all the props supported by the{" "} + {} except `alt`, `preload`, `loading`, + `decoding`, `attributes`, `layout`, and `fadeInTransition`. The only + addition is `media`. Only the [`src`](#src) and [`media`](#media) properties + are required.* + +) : isBackgroundImage ? ( + + *An `ArtDirective` object can take all the props supported by the{" "} + {} except `attributes`. The only addition + is `media`. Only the [`src`](#src) and [`media`](#media) properties are + required.* + +) : ( + + *An `ArtDirective` object can take all the props supported by the{" "} + {} except `preload`, `loading`, + `decoding`, `attributes`, and `fadeInTransition`. The only addition is + `media`. Only the [`src`](#src) and [`media`](#media) properties are + required.* + +)} + + + **Default:** `undefined` + + The list of art directions to be applied to the generated picture. + + **Code Example:** + + + + + + + #### `media` + + **Type:** `string` + + **Default:** `undefined` + + The CSS media query to use to define the art direction. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/aspect.astro b/packages/imagetools/docs/src/components/ConfigOptions/aspect.astro new file mode 100644 index 0000000..53a54a8 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/aspect.astro @@ -0,0 +1,23 @@ + + + ### `aspect` | `ar` + + **Type:** `number` + + **Default:** _The aspect ratio of the source image_ + + Resizes the image to be the specified aspect ratio. If `height` and `width` are both provided, this will be ignored. If `height` is provided, the `height` will be scaled accordingly. If `width` is provided, the height will be scaled accordingly. If neither height nor width are provided, the image will be cropped to the given `aspect` ratio. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/assetFileNames.astro b/packages/imagetools/docs/src/components/ConfigOptions/assetFileNames.astro new file mode 100644 index 0000000..60a4211 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/assetFileNames.astro @@ -0,0 +1,26 @@ + + ### `assetFileNames` + + **Type:** `string` + + **Default:** `_astro/[name]@[width].[hash][extname]` + + The file name pattern for the image assets generated. This config can be used as an alternative to `vite.build.rollupOptions.output.assetFileNames` so that the pattern only applies to assets generated by `astro-imagetools`. Patterns support the following placeholders: + + - `[name]` - the name of the asset (basename of the source file unless the source was a data URI, in which case it's the hash of the data) + - `[width]` - the width descriptor of the image asset + - `[hash]` - the hash of the asset path. A specific length can be specified by appending a colon and the desired length, e.g. `[hash:8]` + - `[ext]` - the extension of the asset (without the leading `.`) + - `[extname]` - the extension of the asset (with the leading `.`) + + > **Note:** Currently, the hash is generated from the asset path, not the asset content. This means that if you change the asset content, the hash will not change. It will be fixed in a future release. + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/attributes.astro b/packages/imagetools/docs/src/components/ConfigOptions/attributes.astro new file mode 100644 index 0000000..570a9f7 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/attributes.astro @@ -0,0 +1,116 @@ +--- +const isImg = + Astro.props.component === "Img" || Astro.props.api === "renderImg"; + +const isPicture = + Astro.props.component === "Picture" || Astro.props.api === "renderPicture"; + +const isBackgroundImage = + Astro.props.component === "BackgroundImage" || + Astro.props.api === "renderBackgroundImage"; +--- + + + ### `attributes` + + **Type:** + + + +{isImg ? ( + + ```ts + declare interface Attributes { + style?: Record; + link?: Omit, "as" | "rel" | "imagesizes" | "imagesrcset">; + img?: Omit< + Record, + | "src" + | "alt" + | "srcset" + | "sizes" + | "width" + | "height" + | "loading" + | "decoding" + >; + } + ``` + +) : isPicture ? ( + + ```ts + declare interface Attributes { + picture?: Record; + style?: Record; + link?: Omit, "as" | "rel" | "imagesizes" | "imagesrcset">; + img?: Omit< + Record, + | "src" + | "alt" + | "srcset" + | "sizes" + | "width" + | "height" + | "loading" + | "decoding" + >; + } + ``` + +) : isBackgroundImage ? ( + + ```ts + declare interface Attributes { + container?: Record; + style?: Record; + link?: Omit, "as" | "rel" | "imagesizes" | "imagesrcset">; + } + ``` + +) : ( + + ```ts + declare interface Attributes { + container?: Record; + picture?: Record; + style?: Record; + link?: Omit, "as" | "rel" | "imagesizes" | "imagesrcset">; + img?: Omit< + Record, + | "src" + | "alt" + | "srcset" + | "sizes" + | "width" + | "height" + | "loading" + | "decoding" + >; + } + ``` + +)} + + + **Default:** `{}` + + The HTML attributes to add to the generate elements. If the `class`, `style`, and `onload` attributes are present, the values passed via this config will be merged. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/background.astro b/packages/imagetools/docs/src/components/ConfigOptions/background.astro new file mode 100644 index 0000000..1f25259 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/background.astro @@ -0,0 +1,52 @@ + + + ### `background` + + **Type:** `string` + + **Default:** `undefined` + + This instructs various props (e.g. [`rotate`](#rotate)) to use the specified color when filling empty spots in the image. + + > **Note:** This prop does nothing on it's own, it has to be used in conjunction with another prop. + + **Code example:** + + The below example demonstrates all the posible cases when the `background` prop is used. + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/backgroundPosition.astro b/packages/imagetools/docs/src/components/ConfigOptions/backgroundPosition.astro new file mode 100644 index 0000000..6e29581 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/backgroundPosition.astro @@ -0,0 +1,22 @@ + + + ### `backgroundPosition` + + **Type:** `string` + + **Default:** `50% 50%` + + The value of the `background-position` CSS property of the generated background image sets. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/backgroundSize.astro b/packages/imagetools/docs/src/components/ConfigOptions/backgroundSize.astro new file mode 100644 index 0000000..98e5bb5 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/backgroundSize.astro @@ -0,0 +1,22 @@ + + + ### `backgroundSize` + + **Type:** `"fill" | "contain" | "cover" | "none" | "scale-down"` + + **Default:** `cover` + + The value of the `background-size` CSS property of the generated background image sets. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/blur.astro b/packages/imagetools/docs/src/components/ConfigOptions/blur.astro new file mode 100644 index 0000000..9627c6f --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/blur.astro @@ -0,0 +1,39 @@ + + + ### `blur` + + **Type:** `string` + + **Default:** `undefined` + + Blurs the image. If the value is `true`, it performs a _fast blur_. When a `number` between `0.3` and `1000` is provided, it performs a more accurate _gaussian blur_. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/breakpoints.astro b/packages/imagetools/docs/src/components/ConfigOptions/breakpoints.astro new file mode 100644 index 0000000..dc04a1a --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/breakpoints.astro @@ -0,0 +1,44 @@ + + + ### `breakpoints` + + **Type:** `number[] | { count?: number; minWidth?: number; maxWidth?: number }` + + **Default:** `undefined` + + An array of widths in pixels to generate image sets for. If not provided, the breakpoints + will be calculated automatically. + + If an object is passed then the breakpoints will be calculated automatically based + on the values of the `count`, + `minWidth`, and `maxWidth` properties. The `count` property is to specify the number + of breakpoints to generate. The `minWidth` and `maxWidth` properties are to specify + the widths to generate in the range between their values. + + When an object is passed or the `breakpoints` prop is not provided, the breakpoints + are calculated using a simple formula/algorithm. Instead of explaining the complete + algorithm here, I am linking to the [code](https://github.com/RafidMuhymin/astro-imagetools/blob/main/packages/astro-imagetools/utils/getBreakpoints.js). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/brightness.astro b/packages/imagetools/docs/src/components/ConfigOptions/brightness.astro new file mode 100644 index 0000000..ea856a0 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/brightness.astro @@ -0,0 +1,23 @@ + + + ### `brightness` + + **Type:** `number` + + **Default:** `undefined` + + Adjusts the images `brightness` with the given brightness multiplier. Commonly used together with [`hue`](#hue) and [`saturation`](#saturation). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/cacheDir.astro b/packages/imagetools/docs/src/components/ConfigOptions/cacheDir.astro new file mode 100644 index 0000000..13b94c7 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/cacheDir.astro @@ -0,0 +1,21 @@ + + + ### `cacheDir` + + **Type:** `string` + + **Default:** `./node_modules/.cache/astro-imagetools` (most of the time) + + Where the cached images will be saved to. If not passed the default cache directory will be located using the [`find-cache-dir`](https://www.npmjs.com/package/find-cache-dir) library. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/content.astro b/packages/imagetools/docs/src/components/ConfigOptions/content.astro new file mode 100644 index 0000000..20d9129 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/content.astro @@ -0,0 +1,22 @@ + + + ### `content` + + **Type:** `string` + + **Default:** `undefined` + + The content of the html element to apply the generated background image sets to. + + **Code Example:** + + + r.text())`], + }, + ]} +/> diff --git a/packages/imagetools/docs/src/components/ConfigOptions/decoding.astro b/packages/imagetools/docs/src/components/ConfigOptions/decoding.astro new file mode 100644 index 0000000..a1c5515 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/decoding.astro @@ -0,0 +1,24 @@ + + + ### `decoding` + + **Type:** `"async" | "sync" | "auto" | null` + + **Default:** `"async"` + + The value of the `decoding` attribute of the generated `` element. If `null` + is provided, the `decoding` attribute will be omitted. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/fadeInTransition.astro b/packages/imagetools/docs/src/components/ConfigOptions/fadeInTransition.astro new file mode 100644 index 0000000..55c8daa --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/fadeInTransition.astro @@ -0,0 +1,45 @@ + + + ### `fadeInTransition` + + **Type:** `boolean | { delay?: string; duration?: string; timingFunction?: string; }` + + **Default:** `true | { delay: "0s"; duration?: "1s"; timingFunction: "ease"; }` + + Whether or not to fade in the image when it is loaded. If an object is passed with the `delay`, `duration`, and `timingFunction` properties, the values will be used as values for the [`transition-delay`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-delay), [`transition-duration`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-duration), and [`transition-timing-function`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function) CSS properties, respectively. + + > **Note:** This prop is only available when the `placeholder` prop of at least one source is not `"none"`. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/fallbackFormat.astro b/packages/imagetools/docs/src/components/ConfigOptions/fallbackFormat.astro new file mode 100644 index 0000000..5419eec --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/fallbackFormat.astro @@ -0,0 +1,24 @@ + + + ### `fallbackFormat` + + **Type:** `format` + + **Default:** _The format of the source image_ + + The format the browser will fallback to if the other formats are not supported. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/fit.astro b/packages/imagetools/docs/src/components/ConfigOptions/fit.astro new file mode 100644 index 0000000..0dc2078 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/fit.astro @@ -0,0 +1,27 @@ + + + ### `fit` + + **Type:** `"cover" | "contain" | "fill" | "inside" | "outside"` + + **Default:** `undefined` + + When both `width` and `height` are provided, this directive can be used to specify the method by which the image should fit. + + > **Note:** The empty parts are filled with the color specified in the [`background`](#background) prop. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/flatten.astro b/packages/imagetools/docs/src/components/ConfigOptions/flatten.astro new file mode 100644 index 0000000..96df725 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/flatten.astro @@ -0,0 +1,23 @@ + + + ### `flatten` + + **Type:** `boolean` + + **Default:** `undefined` + + Whether to remove the alpha channel of the image or not, reducing filesize. Transparent pixels will be merged with the color set by [`background`](#background). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/flip.astro b/packages/imagetools/docs/src/components/ConfigOptions/flip.astro new file mode 100644 index 0000000..ffea04e --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/flip.astro @@ -0,0 +1,23 @@ + + + ### `flip` + + **Type:** `boolean` + + **Default:** `undefined` + + Flip the image about the vertical axis. This step is always performed **after** any rotation. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/flop.astro b/packages/imagetools/docs/src/components/ConfigOptions/flop.astro new file mode 100644 index 0000000..16bb49e --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/flop.astro @@ -0,0 +1,23 @@ + + + ### `flop` + + **Type:** `boolean` + + **Default:** `undefined` + + Flop the image about the vertical axis. This step is always performed **after** any rotation. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/format.astro b/packages/imagetools/docs/src/components/ConfigOptions/format.astro new file mode 100644 index 0000000..4427eb2 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/format.astro @@ -0,0 +1,44 @@ +--- +const isImg = + Astro.props.component === "Img" || Astro.props.api === "renderImg"; +--- + + + ### `format` + + + +{isImg ? ( + + **Type:** `"heic" | "heif" | "avif" | "jpg" | "jpeg" | "png" | "tiff" | + "webp" | "gif"` **Default:** _The format of the source image_ The format to + generate image sets for. + +) : ( + + **Type:** `format | format[] | [] | null` **`format`:** `"heic" | "heif" | + "avif" | "jpg" | "jpeg" | "png" | "tiff" | "webp" | "gif"` **Default:** + `["avif", "webp"]` The image format or formats to generate image sets for. + If `format` is set to `null` or `[]`, no _additional_ image set will be + generated. > **Note:** Passing `[]` or `null` does not necessarily mean that + no image sets will be generated. Image sets will still be generated for the + source format if `includeSourceFormat` is set to `true` (which is the + default value) and for the format specified in the `fallbackFormat` prop + (the default value is the source format). + +)} + + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/formatOptions.astro b/packages/imagetools/docs/src/components/ConfigOptions/formatOptions.astro new file mode 100644 index 0000000..22fa0e5 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/formatOptions.astro @@ -0,0 +1,274 @@ +--- +const { api, component } = Astro.props; + +const isImg = api === "renderImg" || component === "Img"; + +const dynamicText = component + ? `${"`"}<${component} />${"`"} component` + : `${"`"}render${api}${"`"} API`; + +declare interface ConfigOptions { + src: string; + alt: string; + placeholder: string; + format: string | string[]; + fallbackFormat?: string; + includeSourceFormat?: boolean; + formatOptions: string; +} + +const configOptions = { + src: "https://picsum.photos/1024/768", + alt: "A random image", + placeholder: "tracedSVG", +} as ConfigOptions; + +configOptions.format = isImg ? "webp" : [`["webp", "jpg"]`]; +isImg || (configOptions.fallbackFormat = "png"); +isImg || (configOptions.includeSourceFormat = false); +configOptions.formatOptions = isImg + ? `{ + webp: quality: 50, + }` + : `{ + jpg: { + quality: 80, + }, + png: { + quality: 80, + }, + webp: { + quality: 50, + }, + tracedSVG: { + options: { + background: "#fff", + color: "#000", + turnPolicy: "black", + turdSize: 1, + alphaMax: 1, + optCurve: true, + threshold: 100, + blackOnWhite: false, + }, + }, + }`; +--- + + + + ### `formatOptions` + +

Type

+ + _`formatOptions` is an object that takes config options for all the supported formats: `heic`, `heif`, `avif`, `jpg`, `jpeg`, `png`, `tiff`, `webp`, `gif`, and `tracedSVG`._ + + _The supported config options of all the formats except `tracedSVG` are: [`flip`](#flop), [`flop`](#flip), [`invert`](#invert), [`flatten`](#flatten), [`normalize`](#normalize), [`grayscale`](#grayscale), [`hue`](#hue), [`saturation`](#saturation), [`brightness`](#brightness), [`width`](#width), [`height`](#height), [`aspect`](#aspect), [`background`](#background), [`tint`](#tint), [`blur`](#blur), [`median`](#median), [`rotate`](#rotate), [`quality`](#quality), [`fit`](#fit), [`kernel`](#kernel), [`position`](#position)._ + + _The config options supported by the [`tracedSVG`](#tracedSVG) format are listed below._ + + **Default:** _The default values for the all the formats except `tracedSVG` are inherited from the direct configs of the {}. And for more information on the `tracedSVG` property, see the [`PotraceOptions`](#potraceoptions) interface._ + + The configuration options for the different formats. These configuration options will be respected when generating image sets for different formats. + + The `tracedSVG` config object is used only when the `placeholder` prop is set to `"tracedSVG"`. + + **Code example:** + + + + + + + #### `tracedSVG` + + All the properties of the `tracedSVG` property are the configuration options supported by the [`node-potrace`](https://npmjs.com/package/node-potrace) library. These options are used to generate traced SVGs when the `placeholder` prop is set to `"tracedSVG"`. All the properties defined below are optional. + + > **Note:** Most of the below _jargons_ are taken from the [`potrace`](https://npmjs.com/package/potrace) documentation. I have tried my best to simplify the config options and make the documentation as simple and clear as possible. + > + > If you want to go deeper into this, check the [Technical documentation](http://potrace.sourceforge.net/#technical) of the original C [`potrace`](http://potrace.sourceforge.net/) library. + > + > If you have a good knowledge on the `potrace` library and about bitmap tracing and posterizing, please consider contributing to update the documentation of this section. + + ##### `function` + + **Type:** `"trace" | "posterize"` + + **Default:** `"trace"` + + Which method of the `node-potrace` library to use. The `posterize` method is basically _tracing_ the image multiple times to produce a more accurate result. See this [example](https://www.npmjs.com/package/potrace#example-and-demo) for more information. + + ##### `options` + + ###### `turnPolicy` + + **Type:** `"black" | "white" | "left" | "right" | "minority" | "majority"` + + **Default:** `"minority"` + + How to resolve ambiguities in path decomposition. Refer to the [**potrace-algorithm**](http://potrace.sourceforge.net/potrace.pdf) documentaion (PDF, page 4) for more information. + + ###### `turdSize` + + **Type:** `number` + + **Default:** `2` + + Suppress speckles of up to this size. + + ###### `alphaMax` + + **Type:** `number` + + **Default:** `1` + + Corner threshold parameter. + + ###### `optCurve` + + **Type:** `boolean` + + **Default:** `true` + + Curve optimization. + + ###### `optTolerance` + + **Type:** `number` + + **Default:** `0.2` + + Curve optimization tolerance. + + ###### `threshold` + + **Type:** `number` + + **Default:** `-1` + + _When `function` is `"trace"` :_ + + Threshold below which color is considered black. Should be a number between 0 and 255 or `-1` in which case threshold will be selected automatically using [Algorithm For Multilevel Thresholding](http://www.iis.sinica.edu.tw/page/jise/2001/200109_01.pdf). + + _When `function` is `"posterize"` :_ + + Breaks image into foreground and background (and only foreground being broken into desired number of layers). Basically when provided it becomes a threshold for last (least opaque) layer and then `steps - 1` intermediate thresholds calculated. If **steps** is an array of thresholds and every value from the array is lower (or larger if **blackOnWhite** parameter set to `false`) than threshold - threshold will be added to the array, otherwise just ignored. + + ###### `blackOnWhite` + + **Type:** `boolean` + + **Default:** `true` + + Specifies colors by which side from threshold should be turned into vector shape. + + ###### `color` + + **Type:** `"auto" | string` + + **Default:** `"auto"` + + Fill color for the traced image. If `"auto"` is provided, the color will be black or white depending on the `blackOnWhite` property. + +
background
+ + **Type:** `"transparent" | string` + + **Default:** `"transparent"` + + Background color of the traced image. If `"transparent"` is provided, no background will be present. + + ###### `fill` + + **Type:** `"spread" | "dominant" | "median" | "mean"` + + Determines how fill color for each layer should be selected. + + - `dominant` - Most frequent color in range (used by default), + - `mean` - Arithmetic mean (average), + - `median` - Median color, + - `spread` - Ignores color information of the image and just spreads colors equally in range between 0 and `threshold` (or `threshold` and ..255 if `blackOnWhite` is set to `false`). + + > **Note:** This option is available only when `function` is `"posterize"`. + + ###### `ranges` + + **Type:** `"auto" | "equal"` + + How color stops for each layer should be selected. Ignored if `steps` is an array. Possible values are: + + - `auto` - Performs automatic thresholding (using [Algorithm For Multilevel Thresholding](http://www.iis.sinica.edu.tw/page/jise/2001/200109_01.pdf)). Preferable method for already posterized sources, but takes long time to calculate 5 or more thresholds (exponential time complexity) _(used by default)_ + - `equal` - Ignores color information of the image and breaks available color space into equal chunks + + > **Note:** This option is available only when `function` is `"posterize"`. + + ###### `steps` + + **Type:** `number | number[]` + + Specifies desired number of layers in resulting image. If a number provided - thresholds for each layer will be automatically calculated according to `ranges` property. If an array provided it expected to be an array with precomputed thresholds for each layer (in range between 0 and 255). + + > **Note:** This option is available only when `function` is `"posterize"`. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/grayscale.astro b/packages/imagetools/docs/src/components/ConfigOptions/grayscale.astro new file mode 100644 index 0000000..0583c8f --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/grayscale.astro @@ -0,0 +1,25 @@ + + + ### `grayscale` + + **Type:** `boolean` + + **Default:** `undefined` + + Converts the image to an 8-bit grayscale image. + + > **Note:** If `true` the image will be converted to the `b-w` colorspace, meaning the resulting image will only have one channel. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/height.astro b/packages/imagetools/docs/src/components/ConfigOptions/height.astro new file mode 100644 index 0000000..5bb39a0 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/height.astro @@ -0,0 +1,25 @@ + + + ### `height` | `h` + + **Type:** `number` + + **Default:** _The height of the source image_ + + Resizes the image to be the specified amount of pixels tall. If not given the `width` will be scaled accordingly. + + > **Note:** The specified `height` will be used to resize the source image when loading it. The final heights of the image will be based on the final calculated [`breakpoints`](#breakpoints). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/hue.astro b/packages/imagetools/docs/src/components/ConfigOptions/hue.astro new file mode 100644 index 0000000..3741ae5 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/hue.astro @@ -0,0 +1,23 @@ + + + ### `hue` + + **Type:** `number` + + **Default:** `undefined` + + Adjusts the images `hue` rotation by the given number of degrees. Commonly used together with [`saturation`](#saturation) and [`brightness`](#brightness). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/includeSourceFormat.astro b/packages/imagetools/docs/src/components/ConfigOptions/includeSourceFormat.astro new file mode 100644 index 0000000..484cbff --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/includeSourceFormat.astro @@ -0,0 +1,24 @@ + + + ### `includeSourceFormat` + + **Type:** `boolean` + + **Default:** `true` + + Whether to generate image set for the source format or not. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/invert.astro b/packages/imagetools/docs/src/components/ConfigOptions/invert.astro new file mode 100644 index 0000000..f23e86f --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/invert.astro @@ -0,0 +1,23 @@ + + + ### `invert` + + **Type:** `boolean` + + **Default:** `undefined` + + Produces a **negative** of the image. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/kernel.astro b/packages/imagetools/docs/src/components/ConfigOptions/kernel.astro new file mode 100644 index 0000000..d2d2d59 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/kernel.astro @@ -0,0 +1,23 @@ + + + ### `kernel` + + **Type:** `"nearest" | "cubic" | "mitchell" | "lanczos2" | "lanczos3"` + + **Default:** `undefined` + + The interpolation kernel to use when resizing the images. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/layout.astro b/packages/imagetools/docs/src/components/ConfigOptions/layout.astro new file mode 100644 index 0000000..7d79be7 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/layout.astro @@ -0,0 +1,40 @@ + + + ### `layout` + + **Type:** `"constrained" | "fixed" | "fullWidth" | "fill"` + + **Default:** `"constrained"` + + The layout mode to determine the resizing behavior of the image in the + browser. + + In `constrained` mode, the image will occupy full width of the container + with `max-width` set to 100% its width. The height of the image will be calculated + based on the aspect ratio of the image. The image will be scaled down to fit the + container but won't be enlarged. + + In `fixed` mode, the image will have a fixed width + and height. The `width` and `height` props will be used to set the width and height + of the image. The image won't be scaled down nor enlarged. + + In `fullWidth` mode, + the image will be scaled up or down to occupy the full width of the container. + The height of the image will be calculated based on the aspect ratio of the image. + + In `fill` mode, the image will be scaled up or down to fill the entire width and + height of the container. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/loading.astro b/packages/imagetools/docs/src/components/ConfigOptions/loading.astro new file mode 100644 index 0000000..ff3116f --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/loading.astro @@ -0,0 +1,24 @@ + + + ### `loading` + + **Type:** `"lazy" | "eager" | "auto" | null` + + **Default:** `preload ? "eager" : "lazy"` + + The value of the `loading` attribute of the generated `` element. If `null` + is provided, the `loading` attribute will be omitted. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/median.astro b/packages/imagetools/docs/src/components/ConfigOptions/median.astro new file mode 100644 index 0000000..b399412 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/median.astro @@ -0,0 +1,39 @@ + + + ### `median` + + **Type:** `number | boolean` + + **Default:** `undefined` + + Applies a median filter. This is commonly used to remove noise from images. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/normalize.astro b/packages/imagetools/docs/src/components/ConfigOptions/normalize.astro new file mode 100644 index 0000000..8ffd1eb --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/normalize.astro @@ -0,0 +1,23 @@ + + + ### `normalize` + + **Type:** `boolean` + + **Default:** `undefined` + + **Normalizes** the image by stretching its luminance to cover the full dynamic range. This Enhances the output image contrast. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/objectFit.astro b/packages/imagetools/docs/src/components/ConfigOptions/objectFit.astro new file mode 100644 index 0000000..2b645a2 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/objectFit.astro @@ -0,0 +1,23 @@ + + + ### `objectFit` + + **Type:** `"fill" | "contain" | "cover" | "none" | "scale-down"` + + **Default:** `cover` + + The value of the `object-fit` CSS property of the generated `` element. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/objectPosition.astro b/packages/imagetools/docs/src/components/ConfigOptions/objectPosition.astro new file mode 100644 index 0000000..3d55ca1 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/objectPosition.astro @@ -0,0 +1,23 @@ + + + ### `objectPosition` + + **Type:** `string` + + **Default:** `50% 50%` + + The value of the `object-position` CSS property of the generated `` element. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/placeholder.astro b/packages/imagetools/docs/src/components/ConfigOptions/placeholder.astro new file mode 100644 index 0000000..e4fb27d --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/placeholder.astro @@ -0,0 +1,35 @@ + + + ### `placeholder` + + **Type:** `"dominantColor" | "blurred" | "tracedSVG" | "none"` + + **Default:** `"blurred"` + + The placeholder to be displayed while the image is loading. + + If `placeholder` is set to `"dominantColor"`, the dominant color of the source + image will be used as the placeholder. + + If the value is set to `"blurred"`, a very low-resolution version of the + provided image will be enlarged and used as the placeholder. + + If the value is set to `"tracedSVG"`, a traced SVG of the image will be used + as the placeholder. If the value is set to `"none"`, no placeholder will be + displayed. + + > **Note:** If the value is set to `"tracedSVG"`, the placeholder can be customized to be a **Posterized SVG** too. See the [**formatOptions**](#formatOptions) prop for more details. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/position.astro b/packages/imagetools/docs/src/components/ConfigOptions/position.astro new file mode 100644 index 0000000..3fb4aa3 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/position.astro @@ -0,0 +1,28 @@ + + + ### `position` + + **Type:** `"top" | "right top" | "right" | "right bottom" | "bottom" | "left bottom" | "left" | "left top" | "north" | "northeast" | "east" | "southeast" | "south" | "southwest" | "west" | "northwest" | "center" | "centre" | "cover" | "entropy" | "attention"` + + **Default:** `undefined` + + When both `width` and `height` are provided **AND** `fit` is is set to `cover` or `contain`, this directive can be used to set the position of the image. + + > See `sharp`'s [resize options](https://sharp.pixelplumbing.com/api-resize#resize) for more information. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/preload.astro b/packages/imagetools/docs/src/components/ConfigOptions/preload.astro new file mode 100644 index 0000000..b48b33c --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/preload.astro @@ -0,0 +1,25 @@ + + + ### `preload` + + **Type:** `"heic" | "heif" | "avif" | "jpg" | "jpeg" | "png" | "tiff" | "webp" | "gif"` + + **Default:** `undefined` + + Which format of image set to preload. + + > **Note:** It's not reasonable to preload multiple formats of the same image. And due to the factors like file size and browser support, it's not possible to pick the best format automatically. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/quality.astro b/packages/imagetools/docs/src/components/ConfigOptions/quality.astro new file mode 100644 index 0000000..5107d8c --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/quality.astro @@ -0,0 +1,27 @@ + + + ### `quality` + + **Type:** `number` + + **Default:** `undefined` + + All formats (except `gif`) allow the quality to be adjusted by setting this directive. + + The argument must be a number between `0` and `100`. + + > See sharps [Output options](https://sharp.pixelplumbing.com/api-output) for default quality values. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/rotate.astro b/packages/imagetools/docs/src/components/ConfigOptions/rotate.astro new file mode 100644 index 0000000..e7c7d2e --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/rotate.astro @@ -0,0 +1,25 @@ + + + ### `rotate` + + **Type:** `number` + + **Default:** `undefined` + + Rotate the image by the specified number of degrees. + + > **Note:** The empty parts are filled with the color specified in the [`background`](#background) prop. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/saturation.astro b/packages/imagetools/docs/src/components/ConfigOptions/saturation.astro new file mode 100644 index 0000000..a9d5a23 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/saturation.astro @@ -0,0 +1,23 @@ + + + ### `saturation` + + **Type:** `number` + + **Default:** `undefined` + + Adjusts the images `saturation` with the given saturation multiplier. Commonly used together with [`hue`](#hue) and [`brightness`](#brightness). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/sizes.astro b/packages/imagetools/docs/src/components/ConfigOptions/sizes.astro new file mode 100644 index 0000000..281e477 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/sizes.astro @@ -0,0 +1,36 @@ + + + ### `sizes` + + **Type:** `string` or `(breakpoints: number[]) => string` + + **Default:** `` (breakpoints) => `(min-width: ${breakpoints[breakpopints.length - 1]}px) ${breakpoints[breakpopints.length - 1]}px, 100vw `` + + A string or function that returns a string suitable for the value of the `sizes` + attribute of the generated `` element. The final calculated breakpoints + are passed to the function as a parameter. + + **Code example:** + + + { + const maxWidth = breakpoints[breakpoints.length - 1]; + return `(min-width: ${maxWidth}px) ${maxWidth}px, 100vw`; + }, + }, + ]} +/> diff --git a/packages/imagetools/docs/src/components/ConfigOptions/src.astro b/packages/imagetools/docs/src/components/ConfigOptions/src.astro new file mode 100644 index 0000000..ca03553 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/src.astro @@ -0,0 +1,53 @@ + + + ### `src` + + **Type:** `string` + + **Default:** `undefined` + + The path to the source image. If local, the path must be relative to the project root. Remote URLs and Data URIs are also supported. + + **Code example:** + + + + + + #### SSR Usage + + In `SSR` mode, if you are using local images, you have to generate assets for them first and then you have to pass the path to the assets to the `src` property. + + + + + + > The `raw` query parameter has been used to tell the internal Vite plugin to emit the asset from the source image unchanged. + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/tag.astro b/packages/imagetools/docs/src/components/ConfigOptions/tag.astro new file mode 100644 index 0000000..34269f6 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/tag.astro @@ -0,0 +1,22 @@ + + + ### `tag` + + **Type:** `string` + + **Default:** `section` + + Which html tag to use for the html element to apply the generated background image sets to. + + **Code Example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/tint.astro b/packages/imagetools/docs/src/components/ConfigOptions/tint.astro new file mode 100644 index 0000000..0640a21 --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/tint.astro @@ -0,0 +1,23 @@ + + + ### `tint` + + **Type:** `string` + + **Default:** `undefined` + + Tints the image using the provided chroma while preserving the image luminance. If the image has an alpha channel it will be untouched. + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/ConfigOptions/width.astro b/packages/imagetools/docs/src/components/ConfigOptions/width.astro new file mode 100644 index 0000000..c9ba92f --- /dev/null +++ b/packages/imagetools/docs/src/components/ConfigOptions/width.astro @@ -0,0 +1,25 @@ + + + ### `width` | `w` + + **Type:** `number` + + **Default:** _The width of the source image_ + + Resizes the image to be the specified amount of pixels wide. If not given the `height` will be scaled accordingly. + + > **Note:** The specified `width` will be used to resize the source image when loading it. The final widths of the image will be based on the final calculated [`breakpoints`](#breakpoints). + + **Code example:** + + + diff --git a/packages/imagetools/docs/src/components/Footer/AvatarList.astro b/packages/imagetools/docs/src/components/Footer/AvatarList.astro new file mode 100644 index 0000000..1804608 --- /dev/null +++ b/packages/imagetools/docs/src/components/Footer/AvatarList.astro @@ -0,0 +1,176 @@ +--- +// fetch all commits for just this page's path +const path = "docs/" + Astro.props.path; +const url = `https://api.github.com/repos/withastro/astro/commits?path=${path}`; +const commitsURL = `https://github.com/withastro/astro/commits/main/${path}`; + +async function getCommits(url) { + try { + const token: string = import.meta.env.SNOWPACK_PUBLIC_GITHUB_TOKEN; + + if (!token) { + throw new Error( + 'Cannot find "SNOWPACK_PUBLIC_GITHUB_TOKEN" used for escaping rate-limiting.' + ); + } + + const auth = `Basic ${Buffer.from(token, "binary").toString("base64")}`; + + const res = await fetch(url, { + method: "GET", + headers: { + Authorization: auth, + "User-Agent": "astro-docs/1.0", + }, + }); + + const data = await res.json(); + + if (!res.ok) { + throw new Error( + `Request to fetch commits failed. Reason: ${res.statusText} + Message: ${data.message}` + ); + } + + return data; + } catch (e) { + console.warn(`[error] /src/components/AvatarList.astro + ${e?.message ?? e}`); + + return new Array(); + } +} + +function removeDups(arr) { + if (!arr) { + return new Array(); + } + + let map = new Map(); + + for (let item of arr) { + let author = item.author; + + // Deduplicate based on author.id + map.set(author.id, { login: author.login, id: author.id }); + } + + return Array.from(map.values()); +} + +const data = await getCommits(url); +const unique = removeDups(data); +const recentContributors = unique.slice(0, 3); // only show avatars for the 3 most recent contributors +const additionalContributors = unique.length - recentContributors.length; // list the rest of them as # of extra contributors +--- + + +
+
    + {recentContributors.map((item) => ( +
  • + + {`Contributor + +
    • + ))} +
+ + {additionalContributors > 0 && ( + + {`and ${additionalContributors} additional contributor${ + additionalContributors > 1 ? "s" : "" + }.`} + + )} + + {unique.length === 0 && Contributors} +
+ + diff --git a/packages/imagetools/docs/src/components/Footer/Footer.astro b/packages/imagetools/docs/src/components/Footer/Footer.astro new file mode 100644 index 0000000..21c56d8 --- /dev/null +++ b/packages/imagetools/docs/src/components/Footer/Footer.astro @@ -0,0 +1,16 @@ +--- +import AvatarList from "./AvatarList.astro"; +const { path } = Astro.props; +--- + +
+ +
+ + diff --git a/packages/imagetools/docs/src/components/HeadCommon.astro b/packages/imagetools/docs/src/components/HeadCommon.astro new file mode 100644 index 0000000..addcd1c --- /dev/null +++ b/packages/imagetools/docs/src/components/HeadCommon.astro @@ -0,0 +1,47 @@ +--- +import "../styles/theme.css"; +import "../styles/index.css"; +--- + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/imagetools/docs/src/components/HeadSEO.astro b/packages/imagetools/docs/src/components/HeadSEO.astro new file mode 100644 index 0000000..a31c4e7 --- /dev/null +++ b/packages/imagetools/docs/src/components/HeadSEO.astro @@ -0,0 +1,52 @@ +--- +import { SITE, OPEN_GRAPH } from "../config.ts"; + +export interface Props { + content: any; + site: any; + canonicalURL: URL | string; +} + +const { content = {}, canonicalURL } = Astro.props; +const formattedContentTitle = content.title + ? `${content.title} 🚀 ${SITE.title}` + : SITE.title; +const imageSrc = content?.image?.src ?? OPEN_GRAPH.image.src; +const canonicalImageSrc = new URL(imageSrc, Astro.site); +const imageAlt = content?.image?.alt ?? OPEN_GRAPH.image.alt; +--- + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/imagetools/docs/src/components/Header/AstroLogo.astro b/packages/imagetools/docs/src/components/Header/AstroLogo.astro new file mode 100644 index 0000000..14eb5bc --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/AstroLogo.astro @@ -0,0 +1,37 @@ +--- +const { size } = Astro.props; +--- + + diff --git a/packages/imagetools/docs/src/components/Header/Header.astro b/packages/imagetools/docs/src/components/Header/Header.astro new file mode 100644 index 0000000..653664f --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/Header.astro @@ -0,0 +1,144 @@ +--- +import { getLanguageFromURL, KNOWN_LANGUAGE_CODES } from "../../languages.ts"; +import * as CONFIG from "../../config.ts"; +import AstroLogo from "./AstroLogo.astro"; +import SkipToContent from "./SkipToContent.astro"; +import SidebarToggle from "./SidebarToggle.tsx"; +import LanguageSelect from "./LanguageSelect.tsx"; +import Search from "./Search.tsx"; + +const { currentPage } = Astro.props; +const lang = currentPage && getLanguageFromURL(currentPage); +--- + +
+ + + +
+ + diff --git a/packages/imagetools/docs/src/components/Header/LanguageSelect.css b/packages/imagetools/docs/src/components/Header/LanguageSelect.css new file mode 100644 index 0000000..8d73ace --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/LanguageSelect.css @@ -0,0 +1,50 @@ +.language-select { + flex-grow: 1; + width: 48px; + box-sizing: border-box; + margin: 0; + padding: 0.33em 0.5em; + overflow: visible; + font-weight: 500; + font-size: 1rem; + font-family: inherit; + line-height: inherit; + background-color: var(--theme-bg); + border-color: var(--theme-text-lighter); + color: var(--theme-text-light); + border-style: solid; + border-width: 1px; + border-radius: 0.25rem; + outline: 0; + cursor: pointer; + transition-timing-function: ease-out; + transition-duration: 0.2s; + transition-property: border-color, color; + -webkit-font-smoothing: antialiased; + padding-left: 30px; + padding-right: 1rem; +} + +.language-select-wrapper .language-select:hover, +.language-select-wrapper .language-select:focus { + color: var(--theme-text); + border-color: var(--theme-text-light); +} + +.language-select-wrapper { + color: var(--theme-text-light); + position: relative; +} + +.language-select-wrapper > svg { + position: absolute; + top: 7px; + left: 10px; + pointer-events: none; +} + +@media (min-width: 50em) { + .language-select { + width: 100%; + } +} diff --git a/packages/imagetools/docs/src/components/Header/LanguageSelect.tsx b/packages/imagetools/docs/src/components/Header/LanguageSelect.tsx new file mode 100644 index 0000000..6e9ce5c --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/LanguageSelect.tsx @@ -0,0 +1,50 @@ +import type { FunctionalComponent } from "preact"; +import { h } from "preact"; +import "./LanguageSelect.css"; +import { KNOWN_LANGUAGES, langPathRegex } from "../../languages"; + +const LanguageSelect: FunctionalComponent<{ lang: string }> = ({ lang }) => { + return ( +
+ + + +
+ ); +}; + +export default LanguageSelect; diff --git a/packages/imagetools/docs/src/components/Header/Search.css b/packages/imagetools/docs/src/components/Header/Search.css new file mode 100644 index 0000000..5d8a2e7 --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/Search.css @@ -0,0 +1,81 @@ +/** Style Algolia */ +:root { + --docsearch-primary-color: var(--theme-accent); + --docsearch-logo-color: var(--theme-text); +} + +.search-input { + flex-grow: 1; + box-sizing: border-box; + width: 100%; + margin: 0; + padding: 0.33em 0.5em; + overflow: visible; + font-weight: 500; + font-size: 1rem; + font-family: inherit; + line-height: inherit; + background-color: var(--theme-divider); + border-color: var(--theme-divider); + color: var(--theme-text-light); + border-style: solid; + border-width: 1px; + border-radius: 0.25rem; + outline: 0; + cursor: pointer; + transition-timing-function: ease-out; + transition-duration: 0.2s; + transition-property: border-color, color; + -webkit-font-smoothing: antialiased; +} + +.search-input:hover, +.search-input:focus { + color: var(--theme-text); + border-color: var(--theme-text-light); +} + +.search-input:hover::placeholder, +.search-input:focus::placeholder { + color: var(--theme-text-light); +} + +.search-input::placeholder { + color: var(--theme-text-light); +} + +.search-hint { + position: absolute; + top: 7px; + right: 19px; + padding: 3px 5px; + display: none; + display: none; + align-items: center; + justify-content: center; + letter-spacing: 0.125em; + font-size: 13px; + font-family: var(--font-mono); + pointer-events: none; + border-color: var(--theme-text-lighter); + color: var(--theme-text-light); + border-style: solid; + border-width: 1px; + border-radius: 0.25rem; + line-height: 14px; +} + +@media (min-width: 50em) { + .search-hint { + display: flex; + } +} + +/* ------------------------------------------------------------ *\ + DocSearch (Algolia) +\* ------------------------------------------------------------ */ + +.DocSearch-Modal .DocSearch-Hit a { + box-shadow: none; + border: 1px solid var(--theme-accent); +} diff --git a/packages/imagetools/docs/src/components/Header/Search.tsx b/packages/imagetools/docs/src/components/Header/Search.tsx new file mode 100644 index 0000000..5b1056d --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/Search.tsx @@ -0,0 +1,104 @@ +/* jsxImportSource: react */ +import { useState, useCallback, useRef } from "react"; +import * as CONFIG from "../../config"; +import "@docsearch/css/dist/style.css"; +import "./Search.css"; + +// @ts-ignore +import * as docSearchReact from "@docsearch/react"; +// @ts-ignore +import { createPortal } from "react-dom"; + +export default function Search() { + const DocSearchModal = + docSearchReact.DocSearchModal || docSearchReact.default.DocSearchModal; + + const useDocSearchKeyboardEvents = + docSearchReact.useDocSearchKeyboardEvents || + docSearchReact.default.useDocSearchKeyboardEvents; + + const [isOpen, setIsOpen] = useState(false); + const searchButtonRef = useRef(); + const [initialQuery, setInitialQuery] = useState(null); + + const onOpen = useCallback(() => { + setIsOpen(true); + }, [setIsOpen]); + + const onClose = useCallback(() => { + setIsOpen(false); + }, [setIsOpen]); + + const onInput = useCallback( + (e) => { + setIsOpen(true); + setInitialQuery(e.key); + }, + [setIsOpen, setInitialQuery] + ); + + useDocSearchKeyboardEvents({ + isOpen, + onOpen, + onClose, + onInput, + searchButtonRef, + }); + + return ( + <> + + + {isOpen && + createPortal( + { + return items.map((item) => { + // We transform the absolute URL into a relative URL to + // work better on localhost, preview URLS. + const a = document.createElement("a"); + a.href = item.url; + const hash = a.hash === "#overview" ? "" : a.hash; + return { + ...item, + url: `${a.pathname}${hash}`, + }; + }); + }} + />, + document.body + )} + + ); +} diff --git a/packages/imagetools/docs/src/components/Header/SidebarToggle.tsx b/packages/imagetools/docs/src/components/Header/SidebarToggle.tsx new file mode 100644 index 0000000..6ff4a6d --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/SidebarToggle.tsx @@ -0,0 +1,45 @@ +import type { FunctionalComponent } from "preact"; +import { h, Fragment } from "preact"; +import { useState, useEffect } from "preact/hooks"; + +const MenuToggle: FunctionalComponent = () => { + const [sidebarShown, setSidebarShown] = useState(false); + + useEffect(() => { + const body = document.getElementsByTagName("body")[0]; + if (sidebarShown) { + body.classList.add("mobile-sidebar-toggle"); + } else { + body.classList.remove("mobile-sidebar-toggle"); + } + }, [sidebarShown]); + + return ( + + ); +}; + +export default MenuToggle; diff --git a/packages/imagetools/docs/src/components/Header/SkipToContent.astro b/packages/imagetools/docs/src/components/Header/SkipToContent.astro new file mode 100644 index 0000000..b2b542f --- /dev/null +++ b/packages/imagetools/docs/src/components/Header/SkipToContent.astro @@ -0,0 +1,24 @@ + + + diff --git a/packages/imagetools/docs/src/components/LeftSidebar/LeftSidebar.astro b/packages/imagetools/docs/src/components/LeftSidebar/LeftSidebar.astro new file mode 100644 index 0000000..afa61a7 --- /dev/null +++ b/packages/imagetools/docs/src/components/LeftSidebar/LeftSidebar.astro @@ -0,0 +1,130 @@ +--- +import { getLanguageFromURL } from "../../languages.ts"; +import { SIDEBAR } from "../../config.ts"; + +const { currentPage } = Astro.props; +const currentPageMatch = currentPage.slice(1); +const langCode = getLanguageFromURL(currentPage); + +// SIDEBAR is a flat array. Group it by sections to properly render. +const sidebarSections = SIDEBAR[langCode].reduce((col, item, i) => { + // If the first item is not a section header, create a new container section. + if (i === 0) { + if (!item.header) { + const pesudoSection = { text: "" }; + col.push({ ...pesudoSection, children: [] }); + } + } + + if (item.header) { + col.push({ ...item, children: [] }); + } else { + col[col.length - 1].children.push(item); + } + + return col; +}, []); +--- + + + + + + diff --git a/packages/imagetools/docs/src/components/PageContent/PageContent.astro b/packages/imagetools/docs/src/components/PageContent/PageContent.astro new file mode 100644 index 0000000..d306afd --- /dev/null +++ b/packages/imagetools/docs/src/components/PageContent/PageContent.astro @@ -0,0 +1,49 @@ +--- +import MoreMenu from "../RightSidebar/MoreMenu.astro"; +import TableOfContents from "../RightSidebar/TableOfContents.tsx"; + +const { content, githubEditUrl } = Astro.props; +const title = content.title; +const headers = content.astro.headers; +--- + +
+
+

{title}

+ + + + +
+ + +
+ + diff --git a/packages/imagetools/docs/src/components/RightSidebar/MoreMenu.astro b/packages/imagetools/docs/src/components/RightSidebar/MoreMenu.astro new file mode 100644 index 0000000..54446ca --- /dev/null +++ b/packages/imagetools/docs/src/components/RightSidebar/MoreMenu.astro @@ -0,0 +1,74 @@ +--- +import ThemeToggleButton from "./ThemeToggleButton.tsx"; +import * as CONFIG from "../../config"; + +const { editHref } = Astro.props; +const showMoreSection = CONFIG.COMMUNITY_INVITE_URL || editHref; +--- + +{showMoreSection &&

More

} + + +
+ +
+ + diff --git a/packages/imagetools/docs/src/components/RightSidebar/RightSidebar.astro b/packages/imagetools/docs/src/components/RightSidebar/RightSidebar.astro new file mode 100644 index 0000000..fca7ca1 --- /dev/null +++ b/packages/imagetools/docs/src/components/RightSidebar/RightSidebar.astro @@ -0,0 +1,29 @@ +--- +import TableOfContents from "./TableOfContents.tsx"; +import MoreMenu from "./MoreMenu.astro"; + +const { content, githubEditUrl } = Astro.props; +const headers = content.astro.headers; +--- + + + + diff --git a/packages/imagetools/docs/src/components/RightSidebar/TableOfContents.tsx b/packages/imagetools/docs/src/components/RightSidebar/TableOfContents.tsx new file mode 100644 index 0000000..84de46f --- /dev/null +++ b/packages/imagetools/docs/src/components/RightSidebar/TableOfContents.tsx @@ -0,0 +1,51 @@ +import type { FunctionalComponent } from "preact"; +import { useState, useEffect } from "preact/hooks"; + +declare interface Header { + depth: number; + slug: string; + text: string; +} + +const TableOfContents: FunctionalComponent<{ headers: Header[] }> = ({ + headers = [], +}) => { + const [renderedHeaders, setRenderedHeaders] = useState(undefined); + + useEffect(() => { + const titles = document.querySelectorAll("article :is(h1, h2, h3, h4)"); + + const newRenderedHeaders = [...titles] + .map((title) => { + const depth = parseInt(title.tagName.substring(1)); + const slug = title.id; + const text = title.textContent; + return { depth, slug, text }; + }) + .filter(({ slug }) => slug !== ""); + + setRenderedHeaders(newRenderedHeaders); + }, []); + + return ( + <> +

On this page

+ +
    +
  • + Overview +
    • + + {(renderedHeaders || headers) + .filter(({ depth }) => depth > 1 && depth < 4) + .map(({ depth, slug, text }) => ( +
  • + {text} +
    • + ))} +
+ + ); +}; + +export default TableOfContents; diff --git a/packages/imagetools/docs/src/components/RightSidebar/ThemeToggleButton.css b/packages/imagetools/docs/src/components/RightSidebar/ThemeToggleButton.css new file mode 100644 index 0000000..9a41946 --- /dev/null +++ b/packages/imagetools/docs/src/components/RightSidebar/ThemeToggleButton.css @@ -0,0 +1,37 @@ +.theme-toggle { + display: inline-flex; + align-items: center; + gap: 0.25em; + padding: 0.33em 0.67em; + border-radius: 99em; + background-color: var(--theme-code-inline-bg); +} + +.theme-toggle > label:focus-within { + outline: 2px solid transparent; + box-shadow: 0 0 0 0.08em var(--theme-accent), 0 0 0 0.12em white; +} + +.theme-toggle > label { + color: var(--theme-code-inline-text); + position: relative; + display: flex; + align-items: center; + justify-content: center; + opacity: 0.5; +} + +.theme-toggle .checked { + color: var(--theme-accent); + opacity: 1; +} + +input[name="theme-toggle"] { + position: absolute; + opacity: 0; + top: 0; + right: 0; + bottom: 0; + left: 0; + z-index: -1; +} diff --git a/packages/imagetools/docs/src/components/RightSidebar/ThemeToggleButton.tsx b/packages/imagetools/docs/src/components/RightSidebar/ThemeToggleButton.tsx new file mode 100644 index 0000000..400c0e9 --- /dev/null +++ b/packages/imagetools/docs/src/components/RightSidebar/ThemeToggleButton.tsx @@ -0,0 +1,89 @@ +import type { FunctionalComponent } from "preact"; +import { h, Fragment } from "preact"; +import { useState, useEffect } from "preact/hooks"; +import "./ThemeToggleButton.css"; + +const themes = ["light", "dark"]; + +const icons = [ + + + , + + + + , +]; + +const ThemeToggle: FunctionalComponent = () => { + const [theme, setTheme] = useState(() => { + if (import.meta.env.SSR) { + return undefined; + } + + if (typeof localStorage !== "undefined" && localStorage.getItem("theme")) { + return localStorage.getItem("theme"); + } + + if (window.matchMedia("(prefers-color-scheme: dark)").matches) { + return "dark"; + } + + return "light"; + }); + + useEffect(() => { + const root = document.documentElement; + + if (theme === "light") { + root.classList.remove("theme-dark"); + } else { + root.classList.add("theme-dark"); + } + }, [theme]); + + return ( +
+ {themes.map((t, i) => { + const icon = icons[i]; + const checked = t === theme; + + return ( + + ); + })} +
+ ); +}; + +export default ThemeToggle; diff --git a/packages/imagetools/docs/src/config.ts b/packages/imagetools/docs/src/config.ts new file mode 100644 index 0000000..143eb2b --- /dev/null +++ b/packages/imagetools/docs/src/config.ts @@ -0,0 +1,62 @@ +export const SITE = { + title: "Astro ImageTools Documentation", + description: "Documentation for the Astro ImageTools project", + defaultLanguage: "en_US", +}; + +export const OPEN_GRAPH = { + image: { + src: "https://github.com/withastro/astro/blob/main/assets/social/banner.jpg?raw=true", + alt: + "astro logo on a starry expanse of space," + + " with a purple saturn-like planet floating in the right foreground", + }, + twitter: "astrodotbuild", +}; + +export const KNOWN_LANGUAGES = { + English: "en", +}; + +export const GITHUB_EDIT_URL = `https://github.com/RafidMuhymin/astro-imagetools/blob/main/docs/`; + +export const COMMUNITY_INVITE_URL = `https://astro.build/chat`; + +// See "Algolia" section of the README for more information. +export const ALGOLIA = { + appId: "SZQLV18K73", + indexName: "astro-imagetools", + apiKey: "5da19c05f194060063e0e73a50b21b8e", +}; + +export const SIDEBAR = { + en: [ + { text: "GETTING_STARTED", header: true }, + { text: "Introduction", link: "en/introduction" }, + { text: "Installation", link: "en/installation" }, + { text: "Usage", link: "en/usage" }, + + { text: "BASICS", header: true }, + { text: "Components and APIs", link: "en/components-and-apis" }, + { text: "SSR", link: "en/ssr" }, + { text: "Markdown Images", link: "en/markdown-images" }, + { text: "Global Config Options", link: "en/global-config-options" }, + + { text: "COMPONENTS", header: true }, + { text: "", link: "en/components/Img" }, + { text: "", link: "en/components/Picture" }, + { text: "", link: "en/components/BackgroundImage" }, + { text: "", link: "en/components/BackgroundPicture" }, + + { text: "API", header: true }, + { text: "renderImg", link: "en/api/renderImg" }, + { text: "renderPicture", link: "en/api/renderPicture" }, + { text: "renderBackgroundImage", link: "en/api/renderBackgroundImage" }, + { text: "renderBackgroundPicture", link: "en/api/renderBackgroundPicture" }, + { text: "importImage", link: "en/api/importImage" }, + + { text: "MISCELLANEOUS", header: true }, + { text: "Deprecations", link: "en/deprecations" }, + { text: "Acknowledgements", link: "en/acknowledgements" }, + ], +}; diff --git a/packages/imagetools/docs/src/languages.ts b/packages/imagetools/docs/src/languages.ts new file mode 100644 index 0000000..acfe7ae --- /dev/null +++ b/packages/imagetools/docs/src/languages.ts @@ -0,0 +1,10 @@ +import { KNOWN_LANGUAGES } from "./config"; + +export { KNOWN_LANGUAGES }; +export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES); +export const langPathRegex = /\/([a-z]{2}-?[A-Z]{0,2})\//; + +export function getLanguageFromURL(pathname: string) { + const langCodeMatch = pathname.match(langPathRegex); + return langCodeMatch ? langCodeMatch[1] : "en"; +} diff --git a/packages/imagetools/docs/src/layouts/MainLayout.astro b/packages/imagetools/docs/src/layouts/MainLayout.astro new file mode 100644 index 0000000..fe951d7 --- /dev/null +++ b/packages/imagetools/docs/src/layouts/MainLayout.astro @@ -0,0 +1,147 @@ +--- +import HeadCommon from "../components/HeadCommon.astro"; +import HeadSEO from "../components/HeadSEO.astro"; +import Header from "../components/Header/Header.astro"; +import PageContent from "../components/PageContent/PageContent.astro"; +import LeftSidebar from "../components/LeftSidebar/LeftSidebar.astro"; +import RightSidebar from "../components/RightSidebar/RightSidebar.astro"; +import * as CONFIG from "../config"; + +const { content = {} } = Astro.props; +const currentPage = new URL(Astro.request.url).pathname; +const currentFile = `src/pages${currentPage.replace(/\/$/, "")}.md`; +const githubEditUrl = + CONFIG.GITHUB_EDIT_URL && CONFIG.GITHUB_EDIT_URL + currentFile; +--- + + + + + + + + + + + +
+ +
+ + +
+ + + +
+ + +
+ + + + diff --git a/packages/imagetools/docs/src/pages/en/acknowledgements.md b/packages/imagetools/docs/src/pages/en/acknowledgements.md new file mode 100644 index 0000000..4d6991b --- /dev/null +++ b/packages/imagetools/docs/src/pages/en/acknowledgements.md @@ -0,0 +1,47 @@ +--- +title: Acknowledgements +description: Acknowledgements +layout: ../../layouts/MainLayout.astro +--- + + + +## The people for whom this project has become possible + +[Jonathan Neal](https://github.com/jonathantneal) for being extremely helpful and for the [`@astropub/codecs`](https://github.com/astro-community/codecs) library. + +[Jonas Kruckenberg](https://github.com/JonasKruckenberg) for the [`imagetools-core`](https://github.com/JonasKruckenberg/imagetools/tree/main/packages/core) and [`vite-imagetools`](https://github.com/JonasKruckenberg/imagetools/tree/main/packages/vite) libraries. + +[Lovell Fuller](https://github.com/lovell) for the awesome [`sharp`](https://sharp.pixelplumbing.com/) library. + +[Matt Mc](https://github.com/tooolbox) for the [`potrace`](https://github.com/tooolbox/node-potrace) library. + +[Zade Viggers](https://github.com/zadeviggers) for his code contributions. + +[Peter Singh](https://github.com/aFuzzyBear) for documentation support and suggestions. + +_...and many more people for their help and inspiration. And, thanks to the [Astro JS](https://astro.build/) community for their support and encouragement. And, thanks to the people behind the [Vite JS](https://vitejs.dev/) project too._ + +## The resouces that have helped me understand Responsive Images and Image Optimization + +[Responsive Images 101](https://cloudfour.com/thinks/responsive-images-101-definitions/) by [Cloud Four](https://cloudfour.com/). + +[Responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) by [MDN](https://developer.mozilla.org/en-US/). + +[A Guide to the Responsive Images Syntax in HTML](https://css-tricks.com/a-guide-to-the-responsive-images-syntax-in-html/) by [CSS-Tricks](https://css-tricks.com/). + +[Responsive Images](https://developers.google.com/web/fundamentals/design-and-ux/responsive/images) by [Google Developers](https://developers.google.com/web/). + +[Optimising for high-density displays](https://jakearchibald.com/2021/serving-sharp-images-to-high-density-screens/) by [Jake Archibald](https://jakearchibald.com/). + +[Responsive Images, The sizes Attribute, and Unexpected Image Sizes](https://medium.com/@MRWwebDesign/responsive-images-the-sizes-attribute-and-unexpected-image-sizes-882a2eadb6db) by [Mark Root-Wiley](https://github.com/mrwweb/). + +[Fluid Images: Art Direction](https://www.learnhowtoprogram.com/user-interfaces/responsive-design-development-environments/fluid-images-art-direction) by [Learn How To Program](https://www.learnhowtoprogram.com/). + +[Responsive images and art direction](https://web.dev/patterns/web-vitals-patterns/images/responsive-images/) by [Web.dev](https://web.dev/). + +_...and many more articles and resources that have helped me to understand Responsive Images and Image Optimization._ diff --git a/packages/imagetools/docs/src/pages/en/api/importImage.mdx b/packages/imagetools/docs/src/pages/en/api/importImage.mdx new file mode 100644 index 0000000..ddc0302 --- /dev/null +++ b/packages/imagetools/docs/src/pages/en/api/importImage.mdx @@ -0,0 +1,63 @@ +--- +title: importImage +description: The importImage API Documentation +layout: ../../../layouts/MainLayout.astro +--- + +The `importImage` API is a function which acts similar to the ESM `import()` function but for `astro-imagetools`. It returns a `Promise` which resolves to the `src/srcset` of the generated _asset_/_assets_. The provided path should follow the same format as the [`src`](/en/api/renderPicture/#src) attribute. + +## Why? + +- It supports dynamic paths +- It supports remote URLs (data URIs are also supported) + +**Note:** The `importImage` API doesn't support relative local paths. + +## Code Example + +```js +import React from "react"; +import { importImage } from "astro-imagetools/api"; + +const src = await importImage("https://picsum.photos/1024/768"); + +export default function ReactImage() { + return ; +} +``` + +You can pass configuration options via query parameters just like regular ESM imports. + +```js +import { importImage } from "astro-imagetools/api"; + +const src = await importImage( + "https://picsum.photos/1024/768?w=200&h=200&format=avif&q=80" +); +``` + +If you want the function to return a `srcset` instead of a `src`, pass multiple values to the `w` or `width` query parameter. + +```js +import { importImage } from "astro-imagetools/api"; + +const srcset = await importImage( + "https://picsum.photos/1024/768?w=200;400;800" +); +``` + +Dynamic paths are also supported. + +```astro +--- +import { importImage } from "astro-imagetools/api"; + +const { imagePath } = Astro.props; // imagePath = "/public/images/image.jpeg" + +const src = await importImage(imagePath); +--- +``` + +## Return Value + +**Type:** `Promise` diff --git a/packages/imagetools/docs/src/pages/en/api/renderBackgroundImage.mdx b/packages/imagetools/docs/src/pages/en/api/renderBackgroundImage.mdx new file mode 100644 index 0000000..c77dc3f --- /dev/null +++ b/packages/imagetools/docs/src/pages/en/api/renderBackgroundImage.mdx @@ -0,0 +1,59 @@ +--- +title: renderBackgroundImage +description: The renderPicture API Documentation +layout: ../../../layouts/MainLayout.astro +--- + +import ConfigOptions from "../../../components/ConfigOptions.astro"; + +The `renderBackgroundImage` API is a function for rendering an optimized and responsive **Background Images**. The CSS `background-image` property will be used to display the generated background images. + +Similar to the [``](/en/components/BackgroundImage) component, the `renderBackgroundImage` API lacks the **Lazy Loading**, **Asynchronous Decoding**, the `sizes` attribute, and the **onload fade-in transition** features. And it too depends on the [``](/en/components-and-apis#imagesupportdetection) component to work. + +## Code Example + +```astro +--- +import { renderBackgroundImage } from "astro-imagetools/api"; +import { ImageSupportDetection } from "astro-imagetools/components"; + +const content = await fetch(import.meta.env.CONTENT_URL).then((r) => r.text()); + +const { link, style, htmlElement } = await renderBackgroundImage({ + src: "https://picsum.photos/1024/768", + content, + artDirectives: [ + { + src: "https://picsum.photos/1024/768?image=1", + media: "(orientation: potrait)", + }, + ], +}); +--- + + + + + + + + + + +``` + +## Return Value + +**Type:** `{ link: string; style: string; htmlElement: string }` + +If the [`preload`](#preload) config option is set, then the `link` property will contain the `outerHTML` of the generated `` element to preload the image set of the asked format. Otherwise, `link` will be an empty string. + +If the [`placeholder`](#placeholder) config option is not set to `"none"`, then the `style` property will contain the `outerHTML` of the generated ` \ No newline at end of file diff --git a/packages/polymech/src/components/remote.astro b/packages/polymech/src/components/remote.astro new file mode 100644 index 0000000..8c66509 --- /dev/null +++ b/packages/polymech/src/components/remote.astro @@ -0,0 +1,11 @@ +--- +// Example: Fetch Markdown from a remote API +// and render it to HTML, at runtime. +// Using "marked" (https://github.com/markedjs/marked) +import { marked } from 'marked' +const {...rest} = Astro.props +const response = await fetch(rest.src || 'https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md') +const markdown = await response.text(); +const content = marked.parse(markdown); +--- +
\ No newline at end of file diff --git a/packages/polymech/tsconfig.json b/packages/polymech/tsconfig.json new file mode 100644 index 0000000..0827fb6 --- /dev/null +++ b/packages/polymech/tsconfig.json @@ -0,0 +1,26 @@ + { + "compilerOptions": { + "strictNullChecks": true, + // Enable top-level await, and other modern ESM features. + "target": "ESNext", + "allowJs": true, + "module": "NodeNext", + "moduleResolution": "nodenext", + "jsx": "react", + // Enable node-style module resolution, for things like npm package imports. + // Enable stricter transpilation for better output. + "isolatedModules": true, + // Astro will directly run your TypeScript code, no transpilation needed. + "outDir": "./dist", + "esModuleInterop": true, + "skipLibCheck": true, + "baseUrl": ".", + "lib": ["DOM", "ES2015"], + "declaration": true, + "paths": { + "@/*": ["src/*"], + "config/*": ["src/app/*"] + } + }, + "include": [".astro/types.d.ts", "**/*.ts", "**/*.tsx", "**/*.astro"], + } diff --git a/src/.gitignore b/src/.gitignore deleted file mode 100644 index e69de29..0000000