fontaine 0.8.0 → 0.8.2

package/dist/metrics-ChAPPk2j.cjs

@@ -0,0 +1,425 @@
+let css_tree = require("css-tree");
+let magic_regexp = require("magic-regexp");
+let pathe = require("pathe");
+let ufo = require("ufo");
+let node_url = require("node:url");
+let _capsizecss_unpack = require("@capsizecss/unpack");
+let _capsizecss_unpack_fs = require("@capsizecss/unpack/fs");
+//#region src/css.ts
+function toPercentage(value, fractionDigits = 4) {
+	return `${+(value * 100).toFixed(fractionDigits)}%`;
+}
+function toCSS(properties, indent = 2) {
+	return Object.entries(properties).map(([key, value]) => `${" ".repeat(indent)}${key}: ${value};`).join("\n");
+}
+const QUOTES_RE = (0, magic_regexp.createRegExp)((0, magic_regexp.charIn)("\"'").at.lineStart().or((0, magic_regexp.charIn)("\"'").at.lineEnd()), ["g"]);
+const withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
+const QUERY_OR_FRAGMENT_RE = (0, magic_regexp.createRegExp)((0, magic_regexp.charIn)("?#").and((0, magic_regexp.oneOrMore)(magic_regexp.char).optionally()).at.lineEnd());
+/** Removes any `?query` or `#fragment` suffix, which is not part of the file a URL points to. */
+function withoutQueryOrFragment(source) {
+	return source.replace(QUERY_OR_FRAGMENT_RE, "");
+}
+/**
+* Whether a CSS URL may be resolved relative to the stylesheet that declared it, as opposed to
+* the document root (`/font.woff2`) or an external location (`https:`, `//`, `data:`).
+*
+* Bare package specifiers and the webpack `~` convention are indistinguishable from
+* stylesheet-relative paths here, so callers should fall back to their own resolver when
+* resolving against the stylesheet finds nothing.
+*/
+function isStylesheetRelative(source) {
+	return !(0, ufo.hasProtocol)(source, { acceptRelative: true }) && !(0, pathe.isAbsolute)(source);
+}
+const cssWideKeywords = /* @__PURE__ */ new Set([
+	"inherit",
+	"initial",
+	"revert",
+	"revert-layer",
+	"unset"
+]);
+const genericCSSFamilies = /* @__PURE__ */ new Set([
+	"serif",
+	"sans-serif",
+	"monospace",
+	"cursive",
+	"fantasy",
+	"system-ui",
+	"ui-serif",
+	"ui-sans-serif",
+	"ui-monospace",
+	"ui-rounded",
+	"emoji",
+	"math",
+	"fangsong"
+]);
+const genericFamilyLocals = {
+	"serif": [
+		"Times New Roman",
+		"Tinos",
+		"Liberation Serif",
+		"DejaVu Serif",
+		"Times"
+	],
+	"sans-serif": [
+		"Arial",
+		"Arimo",
+		"Liberation Sans",
+		"DejaVu Sans",
+		"Helvetica"
+	],
+	"monospace": [
+		"Courier New",
+		"Cousine",
+		"Liberation Mono",
+		"DejaVu Sans Mono",
+		"Menlo"
+	],
+	"system-ui": [
+		"Segoe UI",
+		"Roboto",
+		"Helvetica Neue",
+		"Cantarell",
+		"Ubuntu",
+		"Noto Sans"
+	],
+	"cursive": [
+		"Comic Sans MS",
+		"Apple Chancery",
+		"Segoe Script",
+		"URW Chancery L"
+	],
+	"fantasy": [
+		"Impact",
+		"Papyrus",
+		"Luminari"
+	]
+};
+genericFamilyLocals["ui-serif"] = genericFamilyLocals.serif;
+genericFamilyLocals["ui-sans-serif"] = genericFamilyLocals["sans-serif"];
+genericFamilyLocals["ui-monospace"] = genericFamilyLocals.monospace;
+genericFamilyLocals["ui-rounded"] = genericFamilyLocals["system-ui"];
+const fontProperties = /* @__PURE__ */ new Set([
+	"font-weight",
+	"font-style",
+	"font-stretch"
+]);
+/**
+* Extracts font family and source information from a CSS @font-face rule using css-tree.
+*
+* @param {string} css - The CSS containing @font-face rules
+* @returns Array<{ family?: string, source?: string }> - Array of objects with font family and source information
+*/
+function parseFontFace(css) {
+	const families = [];
+	const ast = typeof css === "string" ? (0, css_tree.parse)(css, { positions: true }) : css;
+	(0, css_tree.walk)(ast, {
+		visit: "Atrule",
+		enter(node) {
+			if (node.name !== "font-face") return;
+			let family;
+			const sources = [];
+			const properties = {};
+			if (node.block) (0, css_tree.walk)(node.block, {
+				visit: "Declaration",
+				enter(declaration) {
+					if (declaration.property === "font-family" && declaration.value.type === "Value") for (const child of declaration.value.children) {
+						if (child.type === "String") {
+							family = withoutQuotes(child.value);
+							break;
+						}
+						if (child.type === "Identifier" && !genericCSSFamilies.has(child.name)) {
+							family = child.name;
+							break;
+						}
+					}
+					if (fontProperties.has(declaration.property)) {
+						if (declaration.value.type === "Value") for (const child of declaration.value.children) {
+							const hasValue = !!properties[declaration.property];
+							properties[declaration.property] ||= "";
+							properties[declaration.property] += (hasValue ? " " : "") + (0, css_tree.generate)(child);
+						}
+					}
+					if (declaration.property === "src") (0, css_tree.walk)(declaration.value, {
+						visit: "Url",
+						enter(urlNode) {
+							const source = withoutQuotes(urlNode.value);
+							if (source) sources.push(source);
+						}
+					});
+				}
+			});
+			if (family) {
+				for (const source of sources) families.push({
+					index: node.loc.start.offset,
+					family,
+					source,
+					properties
+				});
+				if (!sources.length) families.push({
+					index: node.loc.start.offset,
+					family,
+					properties
+				});
+			}
+		}
+	});
+	return families;
+}
+/**
+* Generates a fallback name based on the first font family specified in the input string.
+* @param {string} name - The full font family string.
+* @returns {string} - The fallback font name.
+*/
+function generateFallbackName(name) {
+	return `${withoutQuotes(name.split(",").shift())} fallback`;
+}
+/**
+* Generates a CSS `@font-face' declaration for a font, taking fallback and resizing into account.
+* @param {FontFaceMetrics} metrics - The metrics of the preferred font. See {@link FontFaceMetrics}.
+* @param {FallbackOptions} fallback - The fallback options, including name, font and optional metrics. See {@link FallbackOptions}.
+* @returns {string} - The full `@font-face` CSS declaration.
+*/
+function generateFontFace(metrics, fallback) {
+	const { name: fallbackName, font: fallbackFontName, metrics: fallbackMetrics, ...properties } = fallback;
+	const preferredFontXAvgRatio = metrics.xWidthAvg / metrics.unitsPerEm;
+	const fallbackFontXAvgRatio = fallbackMetrics ? fallbackMetrics.xWidthAvg / fallbackMetrics.unitsPerEm : 1;
+	const sizeAdjust = fallbackMetrics && preferredFontXAvgRatio && fallbackFontXAvgRatio ? preferredFontXAvgRatio / fallbackFontXAvgRatio : 1;
+	const adjustedEmSquare = metrics.unitsPerEm * sizeAdjust;
+	const ascentOverride = metrics.ascent / adjustedEmSquare;
+	const descentOverride = Math.abs(metrics.descent) / adjustedEmSquare;
+	const lineGapOverride = metrics.lineGap / adjustedEmSquare;
+	return `@font-face {\n${toCSS({
+		"font-family": JSON.stringify(fallbackName),
+		"src": renderLocalSrc(fallbackFontName),
+		"size-adjust": toPercentage(sizeAdjust),
+		"ascent-override": toPercentage(ascentOverride),
+		"descent-override": toPercentage(descentOverride),
+		"line-gap-override": toPercentage(lineGapOverride),
+		...properties
+	})}\n}\n`;
+}
+function renderLocalSrc(font) {
+	return (genericFamilyLocals[withoutQuotes(font).toLowerCase()] || [font]).map((local) => `local(${JSON.stringify(local)})`).join(", ");
+}
+//#endregion
+//#region src/fallbacks.ts
+/**
+* Default fallback font stacks for each font category.
+* These are system fonts that work across different platforms.
+*/
+const DEFAULT_CATEGORY_FALLBACKS = {
+	"sans-serif": [
+		"BlinkMacSystemFont",
+		"Segoe UI",
+		"Helvetica Neue",
+		"Arial",
+		"Noto Sans"
+	],
+	"serif": [
+		"Times New Roman",
+		"Georgia",
+		"Noto Serif"
+	],
+	"monospace": [
+		"Courier New",
+		"Roboto Mono",
+		"Noto Sans Mono"
+	],
+	"display": [
+		"BlinkMacSystemFont",
+		"Segoe UI",
+		"Helvetica Neue",
+		"Arial",
+		"Noto Sans"
+	],
+	"handwriting": [
+		"BlinkMacSystemFont",
+		"Segoe UI",
+		"Helvetica Neue",
+		"Arial",
+		"Noto Sans"
+	]
+};
+/**
+* Resolves the appropriate fallback fonts for a given font family.
+*
+* Resolution order:
+* 1. If fallbacks is an array, use it as a global override
+* 2. If fallbacks is an object with the font family key, use that override
+* 3. If metrics contain a category, use the category-based fallbacks
+* 4. Default to sans-serif category fallbacks
+*
+* @param options - Configuration for fallback resolution
+* @returns Array of fallback font family names
+*/
+function resolveCategoryFallbacks(options) {
+	const { fontFamily, fallbacks, metrics, categoryFallbacks } = options;
+	const mergedCategoryFallbacks = { ...DEFAULT_CATEGORY_FALLBACKS };
+	if (categoryFallbacks) for (const category in categoryFallbacks) {
+		const categoryKey = category;
+		const categoryFallbacksList = categoryFallbacks[categoryKey];
+		if (categoryFallbacksList) mergedCategoryFallbacks[categoryKey] = categoryFallbacksList;
+	}
+	if (Array.isArray(fallbacks)) return fallbacks;
+	const familyFallback = fallbacks[fontFamily];
+	if (familyFallback) return familyFallback;
+	if (metrics?.category) {
+		const categoryFallback = mergedCategoryFallbacks[metrics.category];
+		if (categoryFallback) return categoryFallback;
+	}
+	return mergedCategoryFallbacks["sans-serif"];
+}
+//#endregion
+//#region src/metrics.ts
+const metricCache = {};
+function filterRequiredMetrics(font) {
+	return {
+		ascent: font.ascent,
+		descent: font.descent,
+		lineGap: font.lineGap,
+		unitsPerEm: font.unitsPerEm,
+		xWidthAvg: font.xWidthAvg,
+		category: font.category
+	};
+}
+/**
+* Retrieves the font metrics for a given font family from the metrics collection. Uses caching to avoid redundant calculations.
+* @param {string} family - The name of the font family for which metrics are requested.
+* @returns {Promise<FontFaceMetrics | null>} - A promise that resolves with the filtered font metrics or null if not found. See {@link FontFaceMetrics}.
+* @async
+*/
+async function getMetricsForFamily(family) {
+	family = withoutQuotes(family);
+	if (family in metricCache) return metricCache[family] ?? null;
+	try {
+		const name = fontFamilyToCamelCase(family);
+		const { entireMetricsCollection } = await import("#capsize-font-metrics");
+		const metrics = entireMetricsCollection[name];
+		/* v8 ignore next 4 */
+		if (!("descent" in metrics)) {
+			metricCache[family] = null;
+			return null;
+		}
+		const filteredMetrics = filterRequiredMetrics(metrics);
+		metricCache[family] = filteredMetrics;
+		return filteredMetrics;
+	} catch {
+		metricCache[family] = null;
+		return null;
+	}
+}
+const urlRequestCache = /* @__PURE__ */ new Map();
+/**
+* Reads font metrics from a specified source URL or file path. This function supports both local files and remote URLs.
+* It caches the results to optimise subsequent requests for the same source.
+* @param {URL | string} _source - The source URL or local file path from which to read the font metrics.
+* @returns {Promise<FontFaceMetrics | null>} - A promise that resolves to the filtered font metrics or null if the source cannot be processed.
+* @async
+*/
+async function readMetrics(_source) {
+	const source = typeof _source !== "string" && "href" in _source ? _source.href : _source;
+	if (source in metricCache) return metricCache[source] ?? null;
+	const { protocol } = (0, ufo.parseURL)(source);
+	if (!protocol) return null;
+	let metrics;
+	if (protocol === "file:") metrics = await (0, _capsizecss_unpack_fs.fromFile)((0, node_url.fileURLToPath)(source));
+	else if (urlRequestCache.has(source)) metrics = await urlRequestCache.get(source);
+	else {
+		const requestPromise = (0, _capsizecss_unpack.fromUrl)(source);
+		urlRequestCache.set(source, requestPromise);
+		metrics = await requestPromise;
+	}
+	const filteredMetrics = filterRequiredMetrics(metrics);
+	metricCache[source] = filteredMetrics;
+	return filteredMetrics;
+}
+/**
+* Reads font metrics for a `src` URL declared in a stylesheet.
+*
+* A scheme-less, non-rooted URL is resolved against the stylesheet first, then handed to
+* `resolvePath` if that yields no metrics: bare package specifiers and webpack's `~` prefix
+* look identical to stylesheet-relative paths, and only the caller's resolver can map them.
+*/
+async function readMetricsForSource(source, importer, resolvePath) {
+	if (importer && (0, pathe.isAbsolute)(importer) && isStylesheetRelative(source)) {
+		const metrics = await readMetrics(new URL(source, (0, node_url.pathToFileURL)(importer))).catch(() => null);
+		if (metrics) return metrics;
+	}
+	return readMetrics(resolvePath(source));
+}
+function fontFamilyToCamelCase(str) {
+	return str.split(/[\s|-]/).filter(Boolean).map((s, i) => `${s.charAt(0)[i > 0 ? "toUpperCase" : "toLowerCase"]()}${s.slice(1)}`).join("");
+}
+//#endregion
+Object.defineProperty(exports, "DEFAULT_CATEGORY_FALLBACKS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_CATEGORY_FALLBACKS;
+	}
+});
+Object.defineProperty(exports, "cssWideKeywords", {
+	enumerable: true,
+	get: function() {
+		return cssWideKeywords;
+	}
+});
+Object.defineProperty(exports, "generateFallbackName", {
+	enumerable: true,
+	get: function() {
+		return generateFallbackName;
+	}
+});
+Object.defineProperty(exports, "generateFontFace", {
+	enumerable: true,
+	get: function() {
+		return generateFontFace;
+	}
+});
+Object.defineProperty(exports, "genericCSSFamilies", {
+	enumerable: true,
+	get: function() {
+		return genericCSSFamilies;
+	}
+});
+Object.defineProperty(exports, "getMetricsForFamily", {
+	enumerable: true,
+	get: function() {
+		return getMetricsForFamily;
+	}
+});
+Object.defineProperty(exports, "parseFontFace", {
+	enumerable: true,
+	get: function() {
+		return parseFontFace;
+	}
+});
+Object.defineProperty(exports, "readMetrics", {
+	enumerable: true,
+	get: function() {
+		return readMetrics;
+	}
+});
+Object.defineProperty(exports, "readMetricsForSource", {
+	enumerable: true,
+	get: function() {
+		return readMetricsForSource;
+	}
+});
+Object.defineProperty(exports, "resolveCategoryFallbacks", {
+	enumerable: true,
+	get: function() {
+		return resolveCategoryFallbacks;
+	}
+});
+Object.defineProperty(exports, "withoutQueryOrFragment", {
+	enumerable: true,
+	get: function() {
+		return withoutQueryOrFragment;
+	}
+});
+Object.defineProperty(exports, "withoutQuotes", {
+	enumerable: true,
+	get: function() {
+		return withoutQuotes;
+	}
+});