Merge branch 'master' of github.com:prismicio-community/eleventy-plug…

…in-prismic

CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.0.0-beta.0](https://github.com/prismicio-community/eleventy-plugin-prismic/compare/v0.2.1...v1.0.0-beta.0) (2022-02-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* enhance image shortcode with imgix capabilities
+* use object instead of array for attributes
+
+### Features
+
+* add new image helpers ([2070bde](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/2070bdea57739cbd9c6aefdc543ab0e9041d8af9))
+* enhance image shortcode with imgix capabilities ([c66401d](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/c66401d2bbdfc48666e9d6bfe586e2e175cfebbe))
+
+
+### Bug Fixes
+
+* don't append preview name on default resolved preview URL ([9f2b1ae](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/9f2b1aedf5c9116dbeb2898f04f0f392e8b58adf))
+* keep image tag accessible by defaulting alt value ([6ef0085](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/6ef0085bb8e175086eea2758ffc7495f762c95ac))
+
+
+### Refactor
+
+* use object instead of array for attributes ([b9890a2](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/b9890a2a6b4cdb082b7d05d2798ce2a6be8fe867))
+
+
+### Chore
+
+* **deps:** maintain dependencies ([e337167](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/e337167dd66777cbbfc102174a87e2abeb336b93))
+* update playground ([3ed483a](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/3ed483adedba586b8f262340f85d9c04dae05444))
+* update release script ([211bb94](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/211bb9490d239a6260375ee13a74c59ddd0fc979))
+
+
+### Documentation
+
+* update doc for 1.0.0 ([1682241](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/1682241e558fea4e2f4afa924b5935839e7fdc59))
+* update documentation title ([f274c49](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/f274c49c84a236a33a884272df72d2718122600d))
+* warn about the need for a link resolving strategy to be provided for previews ([5d3910f](https://github.com/prismicio-community/eleventy-plugin-prismic/commit/5d3910fc06d3aafd7ef8db7b939bff98bb96d469))
+
 ### [0.2.1](https://github.com/prismicio-community/eleventy-plugin-prismic/compare/v0.2.1-alpha.0...v0.2.1) (2022-01-10)
 
 

DOCUMENTATION.md

@@ -1,8 +1,9 @@
-# `eleventy-plugin-prismic@0.1.x` Documentation
+# `eleventy-plugin-prismic@1.x.x` Documentation
 
 - [🚀  Installation](#installation)
 - [🛠  Usage](#usage)
 - [📚  Configuration References](#configuration-references)
+- [🚢  Migrating From `0.2.x`](#migrating-from-02x)
 - [⛵  Migrating From `0.1.x`](#migrating-from-01x)
 - [🛶  Migrating From `0.0.x`](#migrating-from-00x)
 
@@ -383,7 +384,7 @@ Displays a link field or document as link with the right attributes and accessib
   Width class
 {% endlink %}
 
-{% link page, document.data.link, "class", "no-underline", "data-foo", "bar" %}
+{% link page, document.data.link, { class: "no-underline", "data-foo": "bar" %}
   With any attribute
 {% endlink %}
 ```
@@ -418,38 +419,68 @@ Renders to:
 
 #### `image`
 
-Displays an image field:
+Displays an image field, image manipulation can be performed through the `imgixParams` option using [Imgix URL parameters](https://docs.imgix.com/apis/rendering):
 
 ```njk
 {% image document.data.image %}
 
 {% image document.data.image, "block p-5" %}
 
-{% image document.data.image, "class", "block p-5", "width", "200px", "loading", "lazy" %}
+{% image document.data.image, { class: "block p-5", width: "200px", loading: "lazy" %}
+
+{% image document.data.image, { imgixParams: { sat: 100 } } %}
+
+{% image document.data.image, { widths: "defaults" } %}
+
+{% image document.data.imageWithResponsiveViews, { widths: "auto" } %}
+
+{% image document.data.image, { widths: [500, 1000, 1500] } %}
+
+{% image document.data.image, { pixelDensities: "defaults" } %}
+
+{% image document.data.image, { pixelDensities: [3, 4] } %}
+
+{% image document.data.image, { imgixParams: { sat: 100 }, widths: "auto", class: "block p-5", loading: "lazy" } %}
 ```
 
 Renders to:
 
 <!-- prettier-ignore-start -->
 ```html
-<img src="https://images.prismic.io/..." />
+<img alt="..." src="https://images.prismic.io/..." />
+
+<img alt="..." src="https://images.prismic.io/..." class="block p-5" />
+
+<img alt="..." src="https://images.prismic.io/..." class="block p-5" width="200px" loading="lazy" />
+
+<img alt="..." src="https://images.prismic.io/...&sat=100" />
 
-<img src="https://images.prismic.io/..." class="block p-5" />
+<img alt="..." src="https://images.prismic.io/..." srcset="https://images.prismic.io/...&width=640 640w, ..., https://images.prismic.io/...&width=3840 3840w" />
 
-<img src="https://images.prismic.io/..." class="block p-5" width="200px" loading="lazy" />
+<img alt="..." src="https://images.prismic.io/..." srcset="https://images.prismic.io/...&width=640 600w, ..., https://images.prismic.io/...&width=1200 1200w" />
+
+<img alt="..." src="https://images.prismic.io/..." srcset="https://images.prismic.io/...&dpr=1 1x, ..., https://images.prismic.io/...&dpr=3 3x" />
+
+<img alt="..." src="https://images.prismic.io/..." srcset="https://images.prismic.io/...&dpr=3 3x, ..., https://images.prismic.io/...&dpr=4 4x" />
+
+<img alt="..." src="https://images.prismic.io/...&sat=100" srcset="https://images.prismic.io/...&sat=100&width=640 640w, ..., https://images.prismic.io/...&sat=100&width=3840 3840w" class="block p-5" loading="lazy" />
 ```
 <!-- prettier-ignore-end -->
 
+> This shortcode is heavily inspired by `@prismicio/vue`'s image component. Its documentation can help you understand this shortcode more if needed: https://prismic.io/docs/technical-reference/prismicio-vue?version=v3#prismicimage
+
 #### `embed`
 
 Displays an embed field:
 
 ```njk
 {% embed document.data.embed %}
 
-{% embed document.data.embed, "blockquote", "block p-5" %}
+{% embed document.data.embed, "block p-5" %}
+
+{% embed document.data.embed, { wrapper: "blockquote" } %}
 
-{% embed document.data.embed, "blockquote", "class", "block p-5", "width", "200px" %}
+{% embed document.data.embed, { wrapper: "blockquote", class: "block p-5", width: "200px" } %}
 ```
 
 Renders to:
@@ -460,13 +491,17 @@ Renders to:
   <!-- Embed HTML snippet -->
 </div>
 
-<blockquote data-oembed="..." data-oembed-type="..." data-oembed-provider="..." class="block p-5">
+<div data-oembed="..." data-oembed-type="..." data-oembed-provider="..." class="block p-5">
+  <!-- Embed HTML snippet -->
+</div>
+
+<blockquote data-oembed="..." data-oembed-type="..." data-oembed-provider="...">
   <!-- Embed HTML snippet -->
 </blockquote>
 
-<div data-oembed="..." data-oembed-type="..." data-oembed-provider="..." class="block p-5" width="200px">
+<blockquote data-oembed="..." data-oembed-type="..." data-oembed-provider="..." class="block p-5" width="200px">
   <!-- Embed HTML snippet -->
-</div>
+</blockquote>
 ```
 <!-- prettier-ignore-end -->
 
@@ -486,7 +521,7 @@ Like Eleventy, this plugin makes use of the [debug](https://www.npmjs.com/packag
 # Installed globally
 DEBUG=Eleventy* eleventy
 # Installed locally
-DEBUG=Eleventy* npx @11ty/eleventy@canary # until 1.0.0 is released on latest
+DEBUG=Eleventy* npx @11ty/eleventy
 ```
 
 Or get just Prismic related logs:
@@ -495,7 +530,7 @@ Or get just Prismic related logs:
 # Installed globally
 DEBUG=Eleventy:Prismic* eleventy
 # Installed locally
-DEBUG=Eleventy:Prismic* npx @11ty/eleventy@canary # until 1.0.0 is released on latest
+DEBUG=Eleventy:Prismic* npx @11ty/eleventy
 ```
 
 ## Configuration References
@@ -539,6 +574,12 @@ type PrismicPluginOptions = {
 
 	// Value of the `rel` attribute on links with `target="_blank"` rendered by shortcodes, defaults to `noopener noreferrer`
 	linkBlankTargetRelAttribute?: string;
+
+	// Default widths to use when rendering an image with `{ widths: "defaults" }`, defaults to `@prismicio/helpers` defaults
+	imageWidthSrcSetDefaults?: number[];
+
+	// Default pixel densities to use when rendering an image with `{ pixelDensities: "defaults" }`, defaults to `@prismicio/helpers` defaults
+	imagePixelDensitySrcSetDefaults?: number[];
 };
 ```
 
@@ -554,9 +595,38 @@ type PrismicPluginOptions = {
 	shortcodesInjector: eleventyConfig.addShortcode,
 	shortcodesPairedInjector: eleventyConfig.addPairedShortcode,
 	linkBlankTargetRelAttribute: "noopener noreferrer",
+	imageWidthSrcSetDefaults: [640, 828, 1200, 2048, 3840], // From `@prismicio/helpers`
+	imagePixelDensitySrcSetDefaults: [1, 2, 3], // From `@prismicio/helpers`
 }
 ```
 
+## Migrating From `0.2.x`
+
+Version `1.x.x` changes the way classes and attributes are passed to shortcodes to support props.
+
+Applying just a class remains the same:
+
+```njk
+{% shortcodeName document.data.field, "block p-5" %}
+```
+
+Applying attributes now requires passing an object instead of a tuple:
+
+```diff
+- {% shortcodeName document.data.field, "class", "block p-5", "data-foo", "bar" %}
++ {% shortcodeName document.data.field, { class: "block p-5", "data-foo": "bar" } %}
+```
+
+The `embed` shortcode's optional `wrapper` is now passed through the attribute object:
+
+```diff
+- {% embed document.data.embed, "blockquote" %}
++ {% embed document.data.embed, { wrapper: "blockquote" } %}
+
+- {% embed document.data.embed, "blockquote", "block p-5" %}
++ {% embed document.data.embed, { wrapper: "blockquote", class: "block p-5" } %}
+```
+
 ## Migrating From `0.1.x`
 
 Version `0.2.x` now relies on Eleventy `1.0.0` or above, upgrade from Eleventy Beta or Canary to prevent any trouble:
@@ -565,7 +635,7 @@ Version `0.2.x` now relies on Eleventy `1.0.0` or above, upgrade from Eleventy B
 $ npm install @11ty/eleventy@^1.0.0
 ```
 
-I also recommend updating your `.eleventy.js` configuration file structure to export your `prismicPluginOptions` alongside your Eleventy config function. This helps to ensure setting up [previews](#previews-experimental) will be straightforward should you decide to set them up:
+It's also recommended to update your `.eleventy.js` configuration file structure to export your `prismicPluginOptions` alongside your Eleventy config function. This helps to ensure setting up [previews](#previews-experimental) will be straightforward should you decide to set them up:
 
 ```javascript
 const {
@@ -588,7 +658,7 @@ module.exports = config;
 
 ## Migrating From `0.0.x`
 
-Package exports have changed from `0.0.x` to `0.1.x`, `pluginPrismic` is not longer default exported:
+Version `0.1.x` changes package exports, `pluginPrismic` is no longer exported as `default`:
 
 ```diff
 -	const pluginPrismic = require("eleventy-plugin-prismic");

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eleventy-plugin-prismic",
-	"version": "0.2.1",
+	"version": "1.0.0-beta.0",
 	"description": "Eleventy plugin and shortcodes to fetch and present Prismic content",
 	"keywords": [
 		"eleventy",
@@ -44,8 +44,8 @@
 		"playground:dev": "cd playground && cross-env DEBUG=Eleventy:Prismic* eleventy --serve",
 		"prepare": "npm run build",
 		"release": "npm run build && npm run test && standard-version && git push --follow-tags && npm run build && npm publish",
-		"release:alpha": "npm run build && npm run test && standard-version --release-as patch --prerelease alpha && git push --follow-tags && npm run build && npm publish --tag alpha",
-		"release:alpha:dry": "standard-version --release-as patch --prerelease alpha --dry-run",
+		"release:beta": "npm run build && npm run test && standard-version --release-as major --prerelease beta && git push --follow-tags && npm run build && npm publish --tag beta",
+		"release:beta:dry": "standard-version --release-as major --prerelease beta --dry-run",
 		"release:dry": "standard-version --dry-run",
 		"test": "npm run lint && npm run unit",
 		"unit": "nyc --reporter=lcovonly --reporter=text --exclude-after-remap=false ava"

src/lib/attributesToHTML.ts

@@ -10,7 +10,15 @@ export const attributesToHTML = (
 ): string => {
 	const attributesArray = Object.entries(attributes)
 		// Keep attributes with a value of `0`
-		.filter(([_, value]) => !!value || typeof value === "number")
+		.filter(([key, value]) => {
+			switch (key) {
+				case "alt":
+					return value != null;
+
+				default:
+					return !!value || typeof value === "number";
+			}
+		})
 		.map(([key, value]) => `${key}="${value}"`);
 
 	return attributesArray.length ? ` ${attributesArray.join(" ")}` : "";

src/shortcodes.ts

@@ -226,7 +226,12 @@ export const image = (
 			}
 		})();
 
-		return `<img${attributesToHTML({ alt, src, srcset, ...attributes })} />`;
+		return `<img${attributesToHTML({
+			alt: alt ?? "",
+			src,
+			srcset,
+			...attributes,
+		})} />`;
 	};
 };
 

test/shortcodes-embed.test.ts

@@ -27,6 +27,13 @@ test("returns a valid embed tag", (t) => {
 	);
 });
 
+test("returns a valid embed tag with specified wrapper", (t) => {
+	t.is(
+		embed()(embedField, { wrapper: "blockquote" }),
+		`<blockquote data-oembed="foo" data-oembed-type="${OEmbedType.Link}" data-oembed-provider="bar">baz</blockquote>`,
+	);
+});
+
 test("returns a valid embed tag with class", (t) => {
 	t.is(
 		embed()(embedField, "foo"),

test/shortcodes-image.test.ts

@@ -17,6 +17,13 @@ test("returns a valid image tag", (t) => {
 	t.is(image()(imageField), '<img alt="foo" src="https://example.com/" />');
 });
 
+test("returns a valid image tag with an accessible default alt value", (t) => {
+	t.is(
+		image()({ ...imageField, alt: null }),
+		'<img alt="" src="https://example.com/" />',
+	);
+});
+
 test("returns a valid image tag with class", (t) => {
 	t.is(
 		image()(imageField, "foo"),
@@ -120,5 +127,5 @@ test("returns a valid image tag with width-based over pixel-density-based `srcse
 });
 
 test("returns a valid image tag from a partial image field", (t) => {
-	t.is(image()({}), "<img />");
+	t.is(image()({}), '<img alt="" />');
 });