Modernize and fix website build tooling deps and utilize JS type checking (#3348)

* Modernize and fix website build tooling deps and utilize JS type checking

* Upgrade to the latest Node.js

.github/workflows/website.yml

@@ -26,6 +26,14 @@ jobs:
       - name: 📥 Clone and checkout repository
         uses: actions/checkout@v3
 
+      # We can remove this step once `ubuntu-latest` has Node.js 22 or newer for its native TypeScript support. See:
+      # https://github.com/actions/runner-images?tab=readme-ov-file#available-images
+      # https://nodejs.org/en/learn/typescript/run-natively
+      - name: 📦 Install the latest Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "latest"
+
       - name: 🕸 Install Zola
         uses: taiki-e/install-action@v2
         with:
@@ -77,7 +85,8 @@ jobs:
           MODE: prod
         run: |
           cd website
-          npm run install-fonts
+          npm ci
+          npm run lint
           zola --config config.toml build --minify
 
       - name: 📤 Publish to Cloudflare Pages

website/.build-scripts/generate-editor-structure.ts

@@ -1,21 +1,12 @@
-const fs = require("fs");
+/* eslint-disable no-console */
-const path = require("path");
 
-/**
+import fs from "fs";
- * Escapes characters that have special meaning in HTML.
+import path from "path";
- * @param {string} text The text to escape.
- * @returns {string} The escaped text.
- */
-function escapeHtml(text) {
-	return text.replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
 
-/**
+type Entry = { level: number; text: string; link: string | undefined };
- * Parses a single line of the input text.
+
- * @param {string} line The line to parse.
+/// Parses a single line of the input text.
- * @returns {{ level: number, text: string, link: string | undefined }}
+function parseLine(line: string) {
- */
-function parseLine(line) {
 	const linkRegex = /`([^`]+)`$/;
 	const linkMatch = line.match(linkRegex);
 	let link = undefined;
@@ -25,7 +16,10 @@ function parseLine(line) {
 		link = `https://github.com/GraphiteEditor/Graphite/blob/master/${filePath}`;
 	}
 
-	const textContent = line.replace(/^[\s│├└─]*/, "").replace(linkRegex, "").trim();
+	const textContent = line
+		.replace(/^[\s│├└─]*/, "")
+		.replace(linkRegex, "")
+		.trim();
 	const indentation = line.indexOf(textContent);
 	// Each level of indentation is 4 characters.
 	const level = Math.floor(indentation / 4);
@@ -33,14 +27,8 @@ function parseLine(line) {
 	return { level, text: textContent, link };
 }
 
-/**
+/// Recursively builds the HTML list from the parsed nodes.
- * Recursively builds the HTML list from the parsed nodes.
+function buildHtmlList(nodes: Entry[], currentIndex: number, currentLevel: number) {
- * @param {Array} nodes The array of parsed node objects.
- * @param {number} currentIndex The current index in the nodes array.
- * @param {number} currentLevel The current indentation level.
- * @returns {{html: string, nextIndex: number}}
- */
-function buildHtmlList(nodes, currentIndex, currentLevel) {
 	if (currentIndex >= nodes.length) {
 		return { html: "", nextIndex: currentIndex };
 	}
@@ -76,7 +64,9 @@ function buildHtmlList(nodes, currentIndex, currentLevel) {
 
 		const partOfMessageFromNamingConvention = ["Message", "MessageHandler", "MessageContext"].some((suffix) => node.text.replace(/(.*)<.*>/g, "$1").endsWith(suffix));
 		const partOfMessageViolatesNamingConvention = node.link && !partOfMessageFromNamingConvention;
-		const violatesNamingConvention = partOfMessageViolatesNamingConvention ? "<span class=\"warn\">(violates naming convention — should end with 'Message', 'MessageHandler', or 'MessageContext')</span>" : "";
+		const violatesNamingConvention = partOfMessageViolatesNamingConvention
+			? "<span class=\"warn\">(violates naming convention — should end with 'Message', 'MessageHandler', or 'MessageContext')</span>"
+			: "";
 
 		if (hasDirectChildren) {
 			html += `<li><span class="tree-node"><span class="${role}">${escapedText}</span>${linkHtml}${violatesNamingConvention}</span>`;
@@ -96,12 +86,16 @@ function buildHtmlList(nodes, currentIndex, currentLevel) {
 	return { html, nextIndex: i };
 }
 
+function escapeHtml(text: string) {
+	return text.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 const inputFile = process.argv[2];
 const outputFile = process.argv[3];
 
 if (!inputFile || !outputFile) {
 	console.error("Error: Please provide the input text and output HTML file paths as arguments.");
-	console.log("Usage: node generate-editor-structure.js <input txt> <output html>");
+	console.log("Usage: node generate-editor-structure.ts <input txt> <output html>");
 	process.exit(1);
 }
 
@@ -112,7 +106,7 @@ if (!fs.existsSync(inputFile)) {
 
 try {
 	const fileContent = fs.readFileSync(inputFile, "utf-8");
-	const lines = fileContent.split(/\r?\n/).filter(line => line.trim() !== "" && !line.startsWith("// filepath:"));
+	const lines = fileContent.split(/\r?\n/).filter((line) => line.trim() !== "" && !line.startsWith("// filepath:"));
 	const parsedNodes = lines.map(parseLine);
 
 	const { html } = buildHtmlList(parsedNodes, 0, 0);

website/.build-scripts/install-fonts.ts

@@ -1,9 +1,11 @@
-const fs = require("fs");
+/* eslint-disable no-console */
-const https = require("https");
-const path = require("path");
 
-// Define basePath
+import fs from "fs";
-const basePath = path.resolve(__dirname);
+import https from "https";
+import path from "path";
+
+// Define basePath as the directory of the current script
+const basePath = import.meta.dirname;
 
 // Define files to copy as [source, destination] pairs
 // Files with the same destination will be concatenated
@@ -21,8 +23,8 @@ const DIRECTORIES_TO_COPY = [
 
 // Track processed destination files and CSS content
 const processedDestinations = new Set();
-const cssDestinations = new Set();
+const cssDestinations = new Set<string>();
-const allCopiedFiles = new Set();
+const allCopiedFiles = new Set<string>();
 
 // Process each file
 FILES_TO_COPY.forEach(([source, dest]) => {
@@ -68,8 +70,7 @@ FILES_TO_COPY.forEach(([source, dest]) => {
 	}
 });
 
-// Function to recursively copy a directory
+function copyDirectoryRecursive(source: string, destination: string) {
-function copyDirectoryRecursive(source, destination) {
 	// Ensure destination directory exists
 	if (!fs.existsSync(destination)) {
 		fs.mkdirSync(destination, { recursive: true });
@@ -130,7 +131,7 @@ cssDestinations.forEach((cssPath) => {
 });
 
 // Filter files that aren't referenced in CSS
-const unusedFiles = [];
+const unusedFiles: string[] = [];
 allCopiedFiles.forEach((filePath) => {
 	const fileName = path.basename(filePath);
 
@@ -185,10 +186,10 @@ https
 				fs.writeFileSync(textBalancerDest, data, "utf8");
 				console.log(`Downloaded and saved: ${textBalancerDest}`);
 			} catch (error) {
-				console.error(`Error saving text-balancer.js:`, error);
+				console.error("Error saving text-balancer.js:", error);
 			}
 		});
 	})
 	.on("error", (err) => {
-		console.error(`Error downloading text-balancer.js:`, err);
+		console.error("Error downloading text-balancer.js:", err);
 	});

website/.eslintrc.js

@@ -1,86 +0,0 @@
-module.exports = {
-	root: true,
-	env: {
-		browser: true,
-		node: true,
-		es2020: true,
-	},
-	parserOptions: {
-		ecmaVersion: 2020,
-	},
-	extends: [
-		"eslint:recommended",
-		"plugin:import/recommended",
-		"plugin:@typescript-eslint/recommended",
-		"plugin:import/typescript",
-		"prettier",
-	],
-	plugins: ["import", "@typescript-eslint", "prettier"],
-	settings: {
-		// https://github.com/import-js/eslint-plugin-import#resolvers
-		"import/resolver": {
-			// `node` must be listed first!
-			node: {},
-		},
-	},
-	ignorePatterns: [
-		// Ignore generated directories
-		"node_modules/",
-		"public/",
-
-		// Don't ignore JS and TS dotfiles in this folder
-		"!.*.js",
-		"!.*.ts",
-	],
-	rules: {
-		// Standard ESLint config
-		indent: "off",
-		quotes: ["error", "double"],
-		camelcase: ["error", { properties: "always" }],
-		"linebreak-style": ["error", "unix"],
-		"eol-last": ["error", "always"],
-		"max-len": ["error", { code: 200, tabWidth: 4, ignorePattern: `d="([\\s\\S]*?)"` }],
-		"prefer-destructuring": "off",
-		"no-console": "warn",
-		"no-debugger": "warn",
-		"no-param-reassign": ["error", { props: false }],
-		"no-bitwise": "off",
-		"no-shadow": "off",
-		"no-use-before-define": "off",
-		"no-restricted-imports": ["error", { patterns: [".*", "!@graphite/*"] }],
-
-		// Import plugin config (used to intelligently validate module import statements)
-		"import/prefer-default-export": "off",
-		"import/no-relative-packages": "error",
-		"import/order": [
-			"error",
-			{
-				alphabetize: {
-					order: "asc",
-					caseInsensitive: true,
-				},
-				warnOnUnassignedImports: true,
-				"newlines-between": "always-and-inside-groups",
-				pathGroups: [],
-			},
-		],
-
-		// Prettier plugin config (used to enforce HTML, CSS, and JS formatting styles as an ESLint plugin, where fixes are reported to ESLint to be applied when linting)
-		"prettier/prettier": [
-			"error",
-			{
-				tabWidth: 4,
-				tabs: true,
-				printWidth: 200,
-			},
-		],
-	},
-	overrides: [
-		{
-			files: ["*.js"],
-			rules: {
-				"@typescript-eslint/explicit-function-return-type": ["off"],
-			},
-		},
-	],
-};

website/eslint.config.js

@@ -0,0 +1,106 @@
+import js from "@eslint/js";
+import { defineConfig, globalIgnores } from "eslint/config";
+import * as pluginImport from "eslint-plugin-import";
+import pluginPrettier from "eslint-plugin-prettier";
+import globals from "globals";
+import ts from "typescript-eslint";
+
+export default defineConfig([
+	js.configs.recommended,
+	ts.configs.recommended,
+	pluginImport.flatConfigs.recommended,
+	pluginImport.flatConfigs.typescript,
+	globalIgnores([
+		// Ignore generated directories
+		"node_modules/",
+		"public/",
+		// Ignore vendored code
+		"static/*.js",
+		// Don't ignore JS and TS dotfiles in this folder
+		"!.*.js",
+		"!.*.ts",
+	]),
+	{
+		plugins: {
+			prettier: pluginPrettier,
+		},
+		settings: {
+			"import/parsers": { "@typescript-eslint/parser": [".ts", ".js"] },
+			"import/resolver": { typescript: true, node: true },
+		},
+		languageOptions: {
+			parserOptions: {
+				project: "./tsconfig.json",
+			},
+			globals: {
+				...globals.browser,
+				...globals.node,
+			},
+		},
+		rules: {
+			// Standard ESLint config (for ordinary JS syntax linting)
+			indent: "off",
+			quotes: ["error", "double", { allowTemplateLiterals: true }],
+			camelcase: ["error", { properties: "always" }],
+			curly: ["error", "multi-line"],
+			"linebreak-style": ["error", "unix"],
+			"eol-last": ["error", "always"],
+			"max-len": ["error", { code: 200, tabWidth: 4, ignorePattern: `d="([\\s\\S]*?)"` }],
+			"prefer-destructuring": "off",
+			"no-console": "warn",
+			"no-debugger": "warn",
+			"no-param-reassign": ["error", { props: false }],
+			"no-bitwise": "off",
+			"no-shadow": "off",
+			"no-use-before-define": "off",
+			"no-restricted-imports": ["error", { patterns: [".*"] }],
+
+			// TypeScript plugin config (for TS-specific linting)
+			"@typescript-eslint/indent": "off",
+			"@typescript-eslint/camelcase": "off",
+			"@typescript-eslint/no-use-before-define": "off",
+			"@typescript-eslint/no-unused-vars": [
+				"error",
+				{
+					args: "all",
+					argsIgnorePattern: "^_",
+					caughtErrors: "all",
+					caughtErrorsIgnorePattern: "^_",
+					destructuredArrayIgnorePattern: "^_",
+					varsIgnorePattern: "^_",
+					ignoreRestSiblings: true,
+				},
+			],
+			"@typescript-eslint/consistent-type-imports": "error",
+			"@typescript-eslint/consistent-type-definitions": ["error", "type"],
+			"@typescript-eslint/consistent-type-assertions": ["error", { assertionStyle: "as", objectLiteralTypeAssertions: "never" }],
+			"@typescript-eslint/consistent-indexed-object-style": ["error", "record"],
+			"@typescript-eslint/consistent-generic-constructors": ["error", "constructor"],
+			"@typescript-eslint/no-restricted-types": ["error", { types: { null: "Use `undefined` instead." } }],
+
+			// Import plugin config (for intelligently validating module import statements)
+			"import/no-unresolved": "error",
+			"import/prefer-default-export": "off",
+			"import/no-relative-packages": "error",
+			"import/no-named-as-default-member": "off",
+			"import/order": [
+				"error",
+				{
+					alphabetize: { order: "asc", caseInsensitive: true },
+					warnOnUnassignedImports: true,
+					"newlines-between": "always-and-inside-groups",
+				},
+			],
+
+			// Prettier plugin config (for validating and fixing formatting)
+			"prettier/prettier": [
+				"error",
+				{
+					tabWidth: 4,
+					tabs: true,
+					printWidth: 200,
+				},
+			],
+		},
+	},
+]);

website/package.json

@@ -9,23 +9,31 @@
 	"author": "Graphite Authors <contact@graphite.rs>",
 	"license": "Apache-2.0",
 	"homepage": "https://graphite.rs",
+	"type": "module",
 	"scripts": {
-		"install-fonts": "npm ci && node build-scripts/install-fonts.js",
+		"postinstall": "node .build-scripts/install-fonts.ts",
-		"generate-editor-structure": "node build-scripts/generate-editor-structure.js ../hierarchical_message_system_tree.txt ../hierarchical_message_system_tree.html"
+		"generate-editor-structure": "node .build-scripts/generate-editor-structure.ts ../hierarchical_message_system_tree.txt ../hierarchical_message_system_tree.html",
+		"lint": "eslint . && tsc --noEmit",
+		"lint-fix": "eslint . --fix && tsc --noEmit"
 	},
 	"devDependencies": {
-		"@typescript-eslint/eslint-plugin": "^8.7.0",
+		"@eslint/compat": "^1.4.1",
-		"@typescript-eslint/parser": "^8.7.0",
+		"@eslint/eslintrc": "^3.3.1",
-		"eslint": "^9.11.1",
+		"@eslint/js": "^9.39.1",
-		"eslint-config-prettier": "^9.1.0",
+		"@types/node": "^24.10.0",
-		"eslint-import-resolver-typescript": "^3.6.3",
+		"@typescript-eslint/eslint-plugin": "^8.46.3",
-		"eslint-plugin-import": "^2.30.0",
+		"@typescript-eslint/parser": "^8.46.3",
-		"eslint-plugin-prettier": "^5.2.1",
+		"eslint-config-prettier": "^10.1.8",
-		"prettier": "^3.3.3",
+		"eslint-import-resolver-typescript": "^4.4.4",
-		"sass": "1.78.0"
+		"eslint-plugin-import": "^2.32.0",
+		"eslint-plugin-prettier": "^5.5.4",
+		"eslint": "^9.39.1",
+		"prettier": "^3.6.2",
+		"sass": "1.93.3",
+		"typescript-eslint": "^8.46.3"
 	},
 	"dependencies": {
-		"@fontsource-variable/inter": "^5.2.5",
+		"@fontsource-variable/inter": "^5.2.8",
-		"@fontsource/bona-nova": "^5.2.5"
+		"@fontsource/bona-nova": "^5.2.8"
 	}
 }

website/static/js/book.js

@@ -18,7 +18,7 @@ function trackScrollHeadingInTOC() {
 
 		// If the next heading isn't fully visible, use the previous heading
 		if (heading && heading.getBoundingClientRect().bottom > window.innerHeight) {
-			prevHeading = firstVisible;
+			let prevHeading = firstVisible;
 			while (prevHeading && !prevHeading.tagName.match(/^H[1-6]$/)) {
 				if (!prevHeading.previousElementSibling) break;
 				prevHeading = prevHeading.previousElementSibling;
@@ -34,7 +34,7 @@ function trackScrollHeadingInTOC() {
 		}
 
 		// If there is no heading, use the first heading
-		if (!heading) heading = document.querySelector("article > h1");
+		if (!heading) heading = document.querySelector("article > h1") || undefined;
 
 		// Remove the existing active heading
 		const existingActive = document.querySelector("aside.contents li.active");
@@ -69,7 +69,7 @@ function listenForClickToOpenOrCloseTOC() {
 	// Close the chapter selection if the user clicks outside of it
 	document.querySelector("main")?.addEventListener("click", (e) => {
 		const chapters = document.querySelector("[data-chapters]");
-		if (chapters?.classList.contains("open") && !e.target.closest("[data-chapters]")) {
+		if (chapters?.classList.contains("open") && e.target instanceof HTMLElement && !e.target.closest("[data-chapters]")) {
 			chapters.classList.remove("open");
 		}
 	});

website/static/js/carousel.js

@@ -6,7 +6,22 @@ window.addEventListener("pointerup", () => dragEnd(false));
 window.addEventListener("scroll", () => dragEnd(true));
 window.addEventListener("pointermove", dragMove);
 
-const carousels = [];
+/**
+ * @typedef {{
+ *   carouselContainer: Element,
+ *   images: NodeListOf<Element>,
+ *   directionPrev: Element | null,
+ *   directionNext: Element | null,
+ *   dots: NodeListOf<Element>,
+ *   descriptions: NodeListOf<Element>,
+ *   dragLastClientX: number | undefined,
+ *   velocityDeltaWindow: Array<{ time: number, delta: number }>,
+ *   jostleNoLongerNeeded: boolean,
+ *   requestAnimationFrameActive: boolean
+ * }} Carousel
+ */
+
+const /** @type {Carousel[]} */ carousels = [];
 
 function initializeCarousel() {
 	const carouselContainers = document.querySelectorAll("[data-carousel]");
@@ -16,9 +31,11 @@ function initializeCarousel() {
 		const tornLeft = carouselContainer.querySelector("[data-carousel-slide-torn-left]");
 		const tornRight = carouselContainer.querySelector("[data-carousel-slide-torn-right]");
 		[tornLeft, tornRight].forEach((insertInsideElement) => {
+			if (!(insertInsideElement instanceof HTMLElement)) return;
 			slideImages.forEach((image) => {
 				const clonedImage = image.cloneNode(true);
-				if (clonedImage instanceof HTMLImageElement) clonedImage.alt = "";
+				if (!(clonedImage instanceof HTMLImageElement)) return;
+				clonedImage.alt = "";
 				insertInsideElement.insertAdjacentElement("beforeend", clonedImage);
 			});
 		});
@@ -48,28 +65,31 @@ function initializeCarousel() {
 		carousels.push(carousel);
 
 		images.forEach((image) => {
+			if (!(image instanceof HTMLElement)) return;
 			image.addEventListener("pointerdown", dragBegin);
 		});
-		directionPrev.addEventListener("click", () => slideDirection(carousel, "prev", true, false));
+		directionPrev?.addEventListener("click", () => slideDirection(carousel, "prev", true, false));
-		directionNext.addEventListener("click", () => slideDirection(carousel, "next", true, false));
+		directionNext?.addEventListener("click", () => slideDirection(carousel, "next", true, false));
 		Array.from(dots).forEach((dot) =>
 			dot.addEventListener("click", (event) => {
-				const index = Array.from(dots).indexOf(event.target);
+				const index = event.target instanceof Element ? Array.from(dots).indexOf(event.target) : -1;
 				slideTo(carousel, index, true);
-			})
+			}),
 		);
 
 		// Jostle hint is a feature to briefly shift the carousel by a bit as a hint to users that it can be interacted with
 		if (performJostleHint) {
 			window.addEventListener("load", () => {
-				new IntersectionObserver((entries) => {
+				if (!(directionPrev instanceof HTMLElement)) return;
+				new IntersectionObserver(
+					(entries) => {
 						entries.forEach((entry) => {
 							if (entry.intersectionRatio === 1 && currentTransform(carousel) === 0 && !carousel.jostleNoLongerNeeded) {
 								const JOSTLE_TIME = 1000;
 								const MAX_JOSTLE_DISTANCE = -10;
 
-							let startTime;
+								let /** @type {number} */ startTime;
-							const buildUp = (timeStep) => {
+								const buildUp = (/** @type {number} */ timeStep) => {
 									if (carousel.jostleNoLongerNeeded) {
 										carousel.carouselContainer.classList.remove("jostling");
 										return;
@@ -78,7 +98,7 @@ function initializeCarousel() {
 									if (!startTime) startTime = timeStep;
 									const elapsedTime = timeStep - startTime;
 
-								const easeOutCirc = (x) => Math.sqrt(1 - Math.pow(x - 1, 2));
+									const easeOutCirc = (/** @type {number} */ x) => Math.sqrt(1 - Math.pow(x - 1, 2));
 									const movementFactor = easeOutCirc(Math.min(1, elapsedTime / JOSTLE_TIME));
 
 									setCurrentTransform(carousel, movementFactor * MAX_JOSTLE_DISTANCE, "%", false, true);
@@ -91,17 +111,23 @@ function initializeCarousel() {
 										slideTo(carousel, 0, true);
 									}
 								};
-							carousel.carouselContainer.classList.add("jostling")
+								carousel.carouselContainer.classList.add("jostling");
 								requestAnimationFrame(buildUp);
-						};
+							}
 						});
-				}, { threshold: 1 })
+					},
-					.observe(directionPrev);
+					{ threshold: 1 },
+				).observe(directionPrev);
 			});
 		}
 	});
 }
 
+/**
+ * @param {Carousel} carousel
+ * @param {"prev" | "next"} direction
+ * @param {boolean} smooth
+ */
 function slideDirection(carousel, direction, smooth, clamped = false) {
 	const directionIndexOffset = { prev: -1, next: 1 }[direction];
 	const offsetDotIndex = currentClosestImageIndex(carousel) + directionIndexOffset;
@@ -113,9 +139,14 @@ function slideDirection(carousel, direction, smooth, clamped = false) {
 	else slideTo(carousel, nextDotIndex, smooth);
 }
 
+/**
+ * @param {Carousel} carousel
+ * @param {number} index
+ * @param {boolean} smooth
+ */
 function slideTo(carousel, index, smooth) {
 	const activeDot = carousel.carouselContainer.querySelector("[data-carousel-dot].active");
-	activeDot.classList.remove("active");
+	activeDot?.classList.remove("active");
 	carousel.dots[index].classList.add("active");
 
 	const activeDescription = carousel.carouselContainer.querySelector("[data-carousel-description].active");
@@ -137,6 +168,9 @@ function slideTo(carousel, index, smooth) {
 	setCurrentTransform(carousel, index * -100, "%", smooth);
 }
 
+/**
+ * @param {Carousel} carousel
+ */
 function currentTransform(carousel) {
 	const currentTransformMatrix = window.getComputedStyle(carousel.images[1]).transform;
 	// Grab the X value from the format that looks like either of: `matrix(1, 0, 0, 1, -1332.13, 0)` or `none`
@@ -145,6 +179,13 @@ function currentTransform(carousel) {
 	return xValue + carousel.images[1].getBoundingClientRect().width;
 }
 
+/**
+ * @param {Carousel} carousel
+ * @param {number} x
+ * @param {string} unit
+ * @param {boolean} smooth
+ * @param {boolean} doNotTerminateJostle
+ */
 function setCurrentTransform(carousel, x, unit, smooth, doNotTerminateJostle = false) {
 	const xInitial = currentTransform(carousel);
 	let xValue = x;
@@ -152,6 +193,7 @@ function setCurrentTransform(carousel, x, unit, smooth, doNotTerminateJostle = f
 	if (unit === "px") xValue = x - carousel.images[1].getBoundingClientRect().width;
 
 	Array.from(carousel.images).forEach((image) => {
+		if (!(image instanceof HTMLElement)) return;
 		image.style.transitionTimingFunction = smooth ? "ease-in-out" : "cubic-bezier(0, 0, 0.2, 1)";
 		image.style.transform = `translateX(${xValue}${unit})`;
 	});
@@ -159,33 +201,39 @@ function setCurrentTransform(carousel, x, unit, smooth, doNotTerminateJostle = f
 	// If the user caused the carousel to move, we can assume they know how to use it and don't need the jostle hint anymore
 	if (!doNotTerminateJostle && x - xInitial < 0.0001) carousel.jostleNoLongerNeeded = true;
 
-	const distance = unit === "%" ? x : x / carousel.images[1].getBoundingClientRect().width * 100;
+	const distance = unit === "%" ? x : (x / carousel.images[1].getBoundingClientRect().width) * 100;
 	const overSlidingLeft = distance > 0;
 	const overSlidingRight = distance < (carousel.dots.length - 1) * -100;
 
 	if ((overSlidingLeft || overSlidingRight) && !carousel.requestAnimationFrameActive) updateOverSlide(carousel);
 }
 
+/**
+ * @param {Carousel} carousel
+ */
 function updateOverSlide(carousel) {
 	const paddingLeft = parseInt(getComputedStyle(carousel.images[1]).paddingLeft);
 	const paddingRight = parseInt(getComputedStyle(carousel.images[carousel.images.length - 2]).paddingRight);
-	const slidLeftDistance = carousel.images[1].getBoundingClientRect().left + paddingLeft - carousel.images[1].parentElement.getBoundingClientRect().left;
+	const slidLeftDistance = carousel.images[1].getBoundingClientRect().left + paddingLeft - (carousel.images[1].parentElement?.getBoundingClientRect().left || 0);
-	const slidRightDistance = -(carousel.images[carousel.images.length - 2].getBoundingClientRect().right - paddingRight - carousel.images[1].parentElement.getBoundingClientRect().right);
+	const slidRightDistance = -(carousel.images[carousel.images.length - 2].getBoundingClientRect().right - paddingRight - (carousel.images[1].parentElement?.getBoundingClientRect().right || 0));
 	const imageWidth = carousel.images[1].getBoundingClientRect().width;
-	const overSlideFactor = Math.min(1, Math.max(0, (Math.max(slidLeftDistance, slidRightDistance) / imageWidth)));
+	const overSlideFactor = Math.min(1, Math.max(0, Math.max(slidLeftDistance, slidRightDistance) / imageWidth));
 
-	const images = carousel.images[0].closest("[data-carousel]").querySelectorAll("[data-carousel-image]:first-child, [data-carousel-image]:last-child");
+	const images = carousel.images[0].closest("[data-carousel]")?.querySelectorAll("[data-carousel-image]:first-child, [data-carousel-image]:last-child");
+	if (!images) return;
 
 	// Call again the next frame if we're still sliding past the edge
 	if (overSlideFactor > 0) {
 		images.forEach((image) => {
-			image.style.setProperty("--over-slide-factor", overSlideFactor);
+			if (!(image instanceof HTMLElement)) return;
+			image.style.setProperty("--over-slide-factor", `${overSlideFactor}`);
 		});
 
 		carousel.requestAnimationFrameActive = true;
 		requestAnimationFrame(() => updateOverSlide(carousel));
 	} else {
 		images.forEach((image) => {
+			if (!(image instanceof HTMLElement)) return;
 			image.style.removeProperty("--over-slide-factor");
 		});
 
@@ -193,6 +241,9 @@ function updateOverSlide(carousel) {
 	}
 }
 
+/**
+ * @param {Carousel} carousel
+ */
 function currentClosestImageIndex(carousel) {
 	const currentTransformX = -currentTransform(carousel);
 
@@ -200,12 +251,19 @@ function currentClosestImageIndex(carousel) {
 	return Math.round(currentTransformX / imageWidth);
 }
 
+/**
+ * @param {Carousel} carousel
+ */
 function currentActiveDotIndex(carousel) {
 	const activeDot = carousel.carouselContainer.querySelector("[data-carousel-dot].active");
-	return Array.from(carousel.dots).indexOf(activeDot);
+	return activeDot ? Array.from(carousel.dots).indexOf(activeDot) : -1;
 }
 
+/**
+ * @param {PointerEvent} event
+ */
 function dragBegin(event) {
+	if (!(event.target instanceof HTMLElement)) return;
 	const carouselContainer = event.target.closest("[data-carousel]");
 	const carousel = carousels.find((carousel) => carousel.carouselContainer === carouselContainer);
 	if (!carousel) return;
@@ -215,9 +273,12 @@ function dragBegin(event) {
 	carousel.dragLastClientX = event.clientX;
 
 	setCurrentTransform(carousel, currentTransform(carousel), "px", false);
-	carouselContainer.classList.add("dragging");
+	carouselContainer?.classList.add("dragging");
 }
 
+/**
+ * @param {boolean} dropWithoutVelocity
+ */
 function dragEnd(dropWithoutVelocity) {
 	const carousel = carousels.find((carousel) => carousel.dragLastClientX !== undefined);
 	if (!carousel) return;
@@ -254,7 +315,6 @@ function dragEnd(dropWithoutVelocity) {
 		// Negative velocity should go to the next image
 		else {
 			// Don't apply the velocity-based fling if we're already snapping to the next image
-			// eslint-disable-next-line no-lonely-if
 			if (closestImageIndex <= activeDotIndex) {
 				slideDirection(carousel, "next", false, true);
 				return;
@@ -267,7 +327,12 @@ function dragEnd(dropWithoutVelocity) {
 	slideTo(carousel, clamp(closestImageIndex, 0, carousel.dots.length - 1), true);
 }
 
+/**
+ * @param {PointerEvent} event
+ */
 function dragMove(event) {
+	if (!(event.target instanceof HTMLElement)) return;
+
 	const carouselContainer = event.target.closest("[data-carousel]");
 	const carousel = carousels.find((carousel) => carousel.carouselContainer === carouselContainer);
 	if (!carousel) return;
@@ -292,6 +357,11 @@ function dragMove(event) {
 	carousel.dragLastClientX = event.clientX;
 }
 
+/**
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ */
 function clamp(value, min, max) {
 	const m = Math; // This is a workaround for a bug in Zola's minifier
 	return m.min(m.max(value, min), max);

website/static/js/developer-guide-editor-structure.js

@@ -2,9 +2,9 @@ document.addEventListener("DOMContentLoaded", () => {
 	document.querySelectorAll(".tree-node").forEach((toggle) => {
 		toggle.addEventListener("click", (event) => {
 			// Prevent link click from also toggling parent
-			if (event.target.tagName === "A") return;
+			if (event.target instanceof HTMLElement && event.target.tagName === "A") return;
 
-			const nestedList = toggle.parentElement.querySelector(".nested");
+			const nestedList = toggle.parentElement?.querySelector(".nested");
 			if (nestedList) {
 				toggle.classList.toggle("expanded");
 				nestedList.classList.toggle("active");
@@ -13,5 +13,6 @@ document.addEventListener("DOMContentLoaded", () => {
 	});
 
 	// Expand the first level by default
-	document.querySelector(".structure-outline > ul > li > .tree-node")?.click();
+	const firstLevel = document.querySelector(".structure-outline > ul > li > .tree-node");
+	if (firstLevel instanceof HTMLElement) firstLevel.click();
 });

website/static/js/fundraising.js

@@ -6,9 +6,10 @@ function initializeFundraisingBar() {
 	let loaded = false;
 
 	const fundraising = document.querySelector("[data-fundraising]");
+	if (!fundraising) return;
 	const bar = fundraising.querySelector("[data-fundraising-bar]");
-	const dynamicPercent = fundraising.querySelector("[data-fundraising-percent] [data-dynamic]")
+	const dynamicPercent = fundraising.querySelector("[data-fundraising-percent] [data-dynamic]");
-	const dynamicGoal = fundraising.querySelector("[data-fundraising-goal] [data-dynamic]")
+	const dynamicGoal = fundraising.querySelector("[data-fundraising-goal] [data-dynamic]");
 	if (!(fundraising instanceof HTMLElement && bar instanceof HTMLElement && dynamicPercent instanceof HTMLElement && dynamicGoal instanceof HTMLElement)) return;
 
 	const setFundraisingGoal = async () => {
@@ -18,15 +19,17 @@ function initializeFundraisingBar() {
 
 		fundraising.classList.remove("loading");
 		bar.style.setProperty("--fundraising-percent", `${data.percentComplete}%`);
-		dynamicPercent.textContent = data.percentComplete;
+		dynamicPercent.textContent = `${data.percentComplete}`;
-		dynamicGoal.textContent = data.targetValue;
+		dynamicGoal.textContent = `${data.targetValue}`;
 
 		loaded = true;
 	};
-	new IntersectionObserver((entries) => {
+	new IntersectionObserver(
+		(entries) => {
 			entries.forEach((entry) => {
 				if (!loaded && entry.intersectionRatio > VISIBILITY_COVERAGE_FRACTION) setFundraisingGoal();
 			});
-	}, { threshold: VISIBILITY_COVERAGE_FRACTION })
+		},
-		.observe(fundraising);
+		{ threshold: VISIBILITY_COVERAGE_FRACTION },
+	).observe(fundraising);
 }

website/static/js/image-comparison.js

@@ -5,7 +5,9 @@ window.addEventListener("DOMContentLoaded", initializeImageComparison);
 
 function initializeImageComparison() {
 	Array.from(document.querySelectorAll("[data-image-comparison]")).forEach((element) => {
-		const moveHandler = (event) => {
+		if (!(element instanceof HTMLElement)) return;
+
+		const moveHandler = (/** @type {PointerEvent} **/ event) => {
 			const factor = (event.clientX - element.getBoundingClientRect().left) / element.getBoundingClientRect().width;
 			const capped = Math.max(0, Math.min(1, factor));
 
@@ -14,7 +16,7 @@ function initializeImageComparison() {
 			element.dataset.lastInteraction = "";
 		};
 
-		const leaveHandler = (event) => {
+		const leaveHandler = (/** @type {PointerEvent} **/ event) => {
 			moveHandler(event);
 
 			const randomCode = Math.random().toString().substring(2);
@@ -22,8 +24,8 @@ function initializeImageComparison() {
 
 			setTimeout(() => {
 				if (element.dataset.lastInteraction === randomCode) {
-					element.dataset.recenterStartTime = Date.now();
+					element.dataset.recenterStartTime = `${Date.now()}`;
-					element.dataset.recenterStartValue = parseFloat(element.style.getPropertyValue("--comparison-percent"));
+					element.dataset.recenterStartValue = `${parseFloat(element.style.getPropertyValue("--comparison-percent"))}`;
 
 					recenterAnimationStep();
 				}
@@ -33,21 +35,21 @@ function initializeImageComparison() {
 		const recenterAnimationStep = () => {
 			if (element.dataset.lastInteraction === "") return;
 
-			const completionFactor = (Date.now() - element.dataset.recenterStartTime) / (RECENTER_ANIMATION_DURATION * 1000);
+			const completionFactor = (Date.now() - Number(element.dataset.recenterStartTime)) / (RECENTER_ANIMATION_DURATION * 1000);
 			if (completionFactor > 1) {
 				element.dataset.lastInteraction = "";
 				return;
 			}
 
 			const factor = smootherstep(completionFactor);
-			const newLocation = lerp(element.dataset.recenterStartValue, 50, factor);
+			const newLocation = lerp(Number(element.dataset.recenterStartValue), 50, factor);
 			element.style.setProperty("--comparison-percent", `${newLocation}%`);
 
 			requestAnimationFrame(recenterAnimationStep);
 		};
 
-		const lerp = (a, b, t) => (1 - t) * a + t * b;
+		const lerp = (/** @type {number} **/ a, /** @type {number} **/ b, /** @type {number} **/ t) => (1 - t) * a + t * b;
-		const smootherstep = (x) => x * x * x * (x * (x * 6 - 15) + 10);
+		const smootherstep = (/** @type {number} **/ x) => x * x * x * (x * (x * 6 - 15) + 10);
 
 		element.addEventListener("pointermove", moveHandler);
 		element.addEventListener("pointerenter", moveHandler);

website/static/js/navbar.js

@@ -3,24 +3,26 @@ const RIPPLE_ANIMATION_MILLISECONDS = 100;
 const RIPPLE_WIDTH = 100;
 const HANDLE_STRETCH = 0.4;
 
-let navButtons;
+let /** @type {NodeList | undefined} **/ navButtons;
-let rippleSvg;
+let /** @type {Element | undefined} **/ rippleSvg;
-let ripplePath;
+let /** @type {Element | undefined} **/ ripplePath;
-let fullRippleHeight;
+let /** @type {number | undefined} **/ fullRippleHeight;
-let ripples;
+let /** @type {{ element: HTMLElement, goingUp: boolean, animationStartTime: number, animationEndTime: number }[]} **/ ripples;
-let activeRippleIndex;
+let /** @type {number} **/ activeRippleIndex;
 
 window.addEventListener("DOMContentLoaded", initializeRipples);
 
 function initializeRipples() {
 	window.addEventListener("resize", () => animate(true));
 
-	navButtons = document.querySelectorAll("header nav a");
+	navButtons = document.querySelectorAll("header nav a") || undefined;
-	rippleSvg = document.querySelector("header .ripple");
+	rippleSvg = document.querySelector("header .ripple") || undefined;
-	ripplePath = rippleSvg.querySelector("path");
+	ripplePath = rippleSvg?.querySelector("path") || undefined;
-	fullRippleHeight = Number.parseInt(window.getComputedStyle(rippleSvg).height, 10);
+	fullRippleHeight = rippleSvg ? Number.parseInt(window.getComputedStyle(rippleSvg).height, 10) || undefined : undefined;
 
-	ripples = Array.from(navButtons).map((button) => ({
+	ripples = Array.from(navButtons)
+		.filter((x) => x instanceof HTMLElement)
+		.map((button) => ({
 			element: button,
 			goingUp: false,
 			animationStartTime: 0,
@@ -29,6 +31,7 @@ function initializeRipples() {
 
 	activeRippleIndex = ripples.findIndex((ripple) => {
 		let link = ripple.element.getAttribute("href");
+		if (!link) return false;
 		if (!link.endsWith("/")) link += "/";
 		let location = window.location.pathname;
 		if (!location.endsWith("/")) location += "/";
@@ -41,7 +44,7 @@ function initializeRipples() {
 	});
 
 	ripples.forEach((ripple) => {
-		const updateTimings = (goingUp) => {
+		const updateTimings = (/** @type {boolean} **/ goingUp) => {
 			const start = ripple.animationStartTime;
 			const now = Date.now();
 			const stop = ripple.animationStartTime + RIPPLE_ANIMATION_MILLISECONDS;
@@ -61,13 +64,15 @@ function initializeRipples() {
 		ripple.element.addEventListener("pointerleave", () => updateTimings(false));
 	});
 
-	if (activeRippleIndex >= 0) ripples[activeRippleIndex] = {
+	if (activeRippleIndex >= 0) {
+		ripples[activeRippleIndex] = {
 			...ripples[activeRippleIndex],
 			goingUp: true,
 			// Set to non-zero, but very old times (1ms after epoch), so the math works out as if the animation has already completed
 			animationStartTime: 1,
 			animationEndTime: 1 + RIPPLE_ANIMATION_MILLISECONDS,
 		};
+	}
 
 	setRipples();
 }
@@ -83,9 +88,11 @@ function animate(forceRefresh = false) {
 }
 
 function setRipples() {
-	const lerp = (a, b, t) => a + (b - a) * t;
+	const lerp = (/** @type {number} **/ a, /** @type {number} **/ b, /** @type {number} **/ t) => a + (b - a) * t;
-	const ease = (x) => 1 - (1 - x) * (1 - x);
+	const ease = (/** @type {number} **/ x) => 1 - (1 - x) * (1 - x);
-	const clamp01 = (x) => Math.min(Math.max(x, 0), 1);
+	const clamp01 = (/** @type {number} **/ x) => Math.min(Math.max(x, 0), 1);
+
+	if (!rippleSvg || !ripplePath || !navButtons || !fullRippleHeight || !(navButtons[0] instanceof HTMLElement)) return;
 
 	const rippleSvgRect = rippleSvg.getBoundingClientRect();
 
@@ -112,7 +119,7 @@ function setRipples() {
 
 		const buttonRect = ripple.element.getBoundingClientRect();
 		const buttonCenter = buttonRect.width / 2;
-		const rippleCenter = RIPPLE_WIDTH / 2 * mediaQueryScaleFactor;
+		const rippleCenter = (RIPPLE_WIDTH / 2) * mediaQueryScaleFactor;
 		const rippleOffset = rippleCenter - buttonCenter;
 		const rippleStartX = buttonRect.left - rippleSvgRect.left - rippleOffset;
 		const handleRadius = rippleCenter * HANDLE_STRETCH;

website/static/js/text-justification.js

@@ -1,8 +1,12 @@
 window.addEventListener("DOMContentLoaded", () => {
 	document.querySelectorAll("section p").forEach((paragraph) => {
+		const /** @type {[Text, NodeList][]} */ mutationQueue = [];
+
 		// Recursively traverse the DOM tree and modify the text nodes
-		const recursivelyAddWbr = (node) => {
+		const recursivelyAddWbr = (/** @type {ChildNode} **/ node) => {
 			if (node.nodeType === Node.TEXT_NODE) {
+				if (!(node instanceof Text)) return;
+
 				const newNodes = node.textContent.split("/");
 				for (let i = 0; i < newNodes.length - 1; i++) {
 					newNodes[i] += "/";
@@ -18,11 +22,10 @@ window.addEventListener("DOMContentLoaded", () => {
 			}
 		};
 
-		// Perform the recursive traversal and replace the text nodes
+		// Perform the recursive traversal
-		const mutationQueue = [];
 		recursivelyAddWbr(paragraph);
-		mutationQueue.forEach(([node, newNodes]) => {
+
-			node.replaceWith(...newNodes);
+		// Replace the text nodes
-		});
+		mutationQueue.forEach(([node, newNodes]) => node.replaceWith(...newNodes));
 	});
 });

website/static/js/video-autoplay.js

@@ -7,16 +7,18 @@ window.addEventListener("DOMContentLoaded", () => {
 
 		let loaded = false;
 
-		new IntersectionObserver((entries) => {
+		new IntersectionObserver(
+			(entries) => {
 				entries.forEach((entry) => {
 					if (!loaded && entry.intersectionRatio > VISIBILITY_COVERAGE_FRACTION) {
 						player.removeAttribute("preload");
 						player.setAttribute("autoplay", "");
 
 						loaded = true;
-				};
+					}
 				});
-		}, { threshold: VISIBILITY_COVERAGE_FRACTION })
+			},
-		.observe(player);
+			{ threshold: VISIBILITY_COVERAGE_FRACTION },
+		).observe(player);
 	});
 });

website/static/js/youtube-embed.js

@@ -1,9 +1,24 @@
 window.addEventListener("DOMContentLoaded", () => {
 	document.querySelectorAll("[data-youtube-embed]").forEach((placeholder) => {
+		if (!(placeholder instanceof HTMLElement)) return;
 		placeholder.addEventListener("click", () => {
-			const videoId = placeholder.attributes["data-youtube-embed"].value;
+			const videoId = placeholder.getAttribute("data-youtube-embed") || "";
-			const timestamp = placeholder.attributes["data-youtube-timestamp"]?.value
+			const timestamp = placeholder.getAttribute("data-youtube-timestamp") || "";
-			placeholder.outerHTML = `<iframe width="1280" height="720" src="https://www.youtube.com/embed/${videoId}?${timestamp ? `start=${timestamp}&` : ""}autoplay=1" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>`;
+			placeholder.outerHTML = `
+				<iframe \\
+				width="1280" \\
+				height="720" \\
+				src="https://www.youtube.com/embed/${videoId}?${timestamp ? `start=${timestamp}&` : ""}autoplay=1" \\
+				frameborder="0" \\
+				allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" \\
+				allowfullscreen\\
+				>\\
+				</iframe>\\
+				`
+				.split("\n")
+				.map((line) => line.trim())
+				.join("")
+				.replaceAll(`\\`, "");
 		});
 	});
 });

website/templates/base.html

@@ -38,7 +38,7 @@
 	{%- set global_css = ["/base.css", "/fonts/common.css"] -%}
 	{%- set fonts_loaded = load_data(path = "static/fonts/common.css", format = "plain", required = false) -%}
 	{%- if not fonts_loaded -%}
-	{{ throw(message = "------------------------------------------------------------> FONTS ARE NOT INSTALLED! Before running Zola, execute `npm run install-fonts` from the `/website` directory.") }}
+	{{ throw(message = "------------------------------------------------------------> FONTS ARE NOT INSTALLED! Before running Zola, execute `npm install` from the `/website` directory.") }}
 	{%- endif -%}
 
 	{#- RETRIEVE FROM TEMPLATES AND PAGES: CSS AND JS TO LOAD EITHER AS A LINK OR INLINE -#}

website/tsconfig.json

@@ -0,0 +1,45 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "node",
+		"strict": true,
+		"allowJs": true,
+		"checkJs": true,
+		"noEmit": true,
+		"importHelpers": true,
+		"experimentalDecorators": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"verbatimModuleSyntax": true,
+		"sourceMap": true,
+		"types": ["node"],
+		"baseUrl": ".",
+		"paths": {
+			"/*": ["./*"]
+		},
+		"lib": ["ESNext", "DOM", "DOM.Iterable", "ScriptHost"]
+	},
+	"include": [
+		// TypeScript and JSDoc-typed JavaScript files
+		"**/*.ts",
+		"**/*.js",
+		// Also include build scripts, which aren't included above because of the dot-prefixed directory
+		".build-scripts/**/*.ts",
+		".build-scripts/**/*.js"
+	],
+	"exclude": [
+		// Ignore generated directories
+		"node_modules",
+		"public",
+		// Ignore vendored code
+		"static/*.js"
+	],
+	"ts-node": {
+		"compilerOptions": {
+			"useDefineForClassFields": false,
+			"noImplicitOverride": true
+		}
+	}
+}