satteri-figure 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# satteri-figure
+
+[Satteri](https://satteri.bruits.org) plugin to transform an image with alt text to a figure with caption. A port of [`@microflash/rehype-figure`](https://github.com/naiyerasif/rehype-figure) to Satteri's [HAST plugin API](https://satteri.bruits.org/docs/plugin-api/).
+
+> [!IMPORTANT]
+> Converting an image with alt text to a figure with caption is an [escape hatch](https://en.wiktionary.org/wiki/escape_hatch). Alt text, title, and captions have [different intended purposes](https://www.stylemanual.gov.au/content-types/images/alt-text-captions-and-titles-images), and you should eventually enhance your content to adopt them.
+
+## What's this?
+
+This package is a [Satteri](https://satteri.bruits.org) plugin that takes an image node with alt text (e.g., `![Alt text](path-to-image.jpg)`) and converts it to a [figure](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) element with caption.
+
+```html
+<figure>
+  <img src="path-to-image.jpg" alt="Alt text" />
+  <figcaption>Alt text</figcaption>
+</figure>
+```
+
+## Install
+
+```sh
+npm install satteri-figure
+yarn add satteri-figure
+pnpm add satteri-figure
+```
+
+## Use
+
+Say we have the following module `example.js`:
+
+```js
+import { markdownToHtml } from "satteri";
+import satteriFigure from "satteri-figure";
+
+const { html } = markdownToHtml("![Alt text](path-to-image.jpg)", {
+  hastPlugins: [satteriFigure()],
+});
+
+console.log(html);
+```
+
+Running that with `node example.js` yields:
+
+```html
+<figure><img src="path-to-image.jpg" alt="Alt text"><figcaption>Alt text</figcaption></figure>
+```
+
+## API
+
+The default export is `satteriFigure`, a function returning a HAST plugin definition to pass to `hastPlugins`.
+
+The following options are available. All of them are optional.
+
+- `className`: class (or list of classes) for the wrapped `figure` element
+
+By default, no classes are added to the `figure` element.
+
+## Development
+
+- Run `pnpm test` to run tests
+
+## License
+
+[MIT](../../LICENSE)

package/index.js

@@ -0,0 +1,149 @@
+import { defineHastPlugin } from "satteri";
+
+// HTML inter-element whitespace.
+// See <https://infra.spec.whatwg.org/#ascii-whitespace>.
+const whitespaceRe = /^[ \t\n\f\r]*$/;
+
+/**
+ * @typedef {object} SatteriFigureOptions
+ * @property {string | string[]} [className]
+ *   Class(es) for the wrapping `figure` element. No classes are added
+ *   by default.
+ */
+
+/**
+ * Satteri plugin to transform an image with alt text to a figure with
+ * caption.
+ *
+ * Port of [`@microflash/rehype-figure`](https://github.com/naiyerasif/rehype-figure)
+ * to a Satteri HAST plugin.
+ *
+ * @param {SatteriFigureOptions} [options]
+ *   Optional settings.
+ * @returns
+ *   HAST plugin definition; pass the result to `hastPlugins`.
+ */
+export default function satteriFigure(options = {}) {
+	return defineHastPlugin({
+		name: "satteri-figure",
+		element: [
+			{
+				// Phase 1: unwrap the images inside an images-only paragraph,
+				// wrapping each image with alt text in a figure on the way up.
+				filter: ["p"],
+				visit(node, ctx) {
+					if (!hasOnlyImages(node)) {
+						return;
+					}
+
+					const parent = ctx.parent(node);
+
+					ctx.replaceNode(
+						node,
+						node.children
+							.filter(
+								(child) => child.type === "element" && child.tagName === "img"
+							)
+							.map((image) =>
+								isImageWithAlt(image) &&
+								!isImageWithCaption(parent) &&
+								!isImageLink(parent)
+									? createFigure(image, options)
+									: image
+							)
+					);
+				},
+			},
+			{
+				// Phase 2: wrap every other image with alt text in a figure.
+				filter: ["img"],
+				visit(node, ctx) {
+					if (!isImageWithAlt(node)) {
+						return;
+					}
+
+					const parent = ctx.parent(node);
+
+					if (
+						isImageWithCaption(parent) ||
+						isImageLink(parent) ||
+						// Handled by the paragraph visitor above.
+						(parent?.tagName === "p" && hasOnlyImages(parent))
+					) {
+						return;
+					}
+
+					ctx.replaceNode(node, createFigure(node, options));
+				},
+			},
+		],
+	});
+}
+
+function hasOnlyImages(node) {
+	return (
+		node?.type === "element" &&
+		node.children.every(
+			(child) =>
+				(child.type === "element" && child.tagName === "img") ||
+				(child.type === "text" && whitespaceRe.test(child.value))
+		)
+	);
+}
+
+function isImageWithAlt(node) {
+	return (
+		node?.type === "element" &&
+		node.tagName === "img" &&
+		Boolean(node.properties?.alt) &&
+		Boolean(node.properties?.src)
+	);
+}
+
+function isImageWithCaption(node) {
+	return (
+		node?.type === "element" &&
+		node.tagName === "figure" &&
+		node.children.some(
+			(child) => child.type === "element" && child.tagName === "figcaption"
+		)
+	);
+}
+
+function isImageLink(node) {
+	return node?.type === "element" && node.tagName === "a";
+}
+
+function createFigure(image, options) {
+	const classes = toClasses(options.className);
+
+	return {
+		type: "element",
+		tagName: "figure",
+		properties: classes.length > 0 ? { className: classes } : {},
+		children: [
+			{
+				type: "element",
+				tagName: "img",
+				properties: { ...image.properties },
+				children: [],
+			},
+			{
+				type: "element",
+				tagName: "figcaption",
+				properties: {},
+				children: [{ type: "text", value: String(image.properties.alt) }],
+			},
+		],
+	};
+}
+
+function toClasses(className) {
+	if (!className) {
+		return [];
+	}
+
+	return (Array.isArray(className) ? className : [className])
+		.flatMap((value) => String(value).split(/\s+/))
+		.filter(Boolean);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "satteri-figure",
+  "description": "A Satteri plugin to convert images into figures with captions.",
+  "version": "0.0.1",
+  "license": "MIT",
+  "author": "Abhigyan Trips <contact@abhi.now>",
+  "repository": "https://github.com/abhigyantrips/satteri-plugins",
+  "keywords": [
+    "satteri",
+    "figure",
+    "figcaption",
+    "plugin",
+    "image",
+    "caption"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "devDependencies": {
+    "satteri": "^0.10.5"
+  },
+  "peerDependencies": {
+    "satteri": "^0.10.5"
+  },
+  "scripts": {
+    "test": "node --test ./test/plugin.test.js"
+  }
+}