@segnavia/html 0.20.0 → 0.22.0

package/dist/bindings.d.ts

@@ -6,6 +6,7 @@ export interface FillOptions extends Pick<SanitizeOptions, 'linkOrigins'> {
   prefix: string;
   data: Record<string, unknown>;
   unavailable?: Iterable<string>;
+  preserveUnavailable?: boolean;
 }
 export interface Filled {
   html: string;

package/dist/bindings.js

@@ -96,6 +96,7 @@ function fill(html, options) {
 		const path = take(element, names.value);
 		if (path === void 0) return;
 		const value = resolve(path, stack);
+		if (value === void 0 && options.preserveUnavailable) return;
 		element.children = [];
 		if (typeof value === "string" || typeof value === "number" && Number.isFinite(value)) {
 			const text = new Text(String(value));
@@ -106,10 +107,12 @@ function fill(html, options) {
 		} else if (value !== void 0) unavailable.add(path);
 	};
 	const applyUrls = (element, stack) => {
+		const preserves = (value) => value === void 0 && options.preserveUnavailable;
 		for (const attribute of ["href", "src"]) {
 			const path = take(element, names[attribute]);
 			if (path === void 0) continue;
 			const value = resolve(path, stack);
+			if (preserves(value)) continue;
 			if (typeof value === "string" && (attribute === "href" ? safeHref(value, origins) : /^data:image\//i.test(value))) element.attribs[attribute] = value;
 			else {
 				delete element.attribs[attribute];

package/dist/index.d.ts

@@ -2,9 +2,10 @@ import { REFUSED_ELEMENTS, SanitizeOptions, findActiveContent, sanitize } from "
 import { BINDINGS, FillOptions, Filled, bindingNames, fill, hasBindings } from "./bindings.js";
 import { BookDocument, BookDocumentOptions, BookHeading, BookPrintPart, BookSectionInfo, bookPrintPart } from "./book/types.js";
 import { bookDocument } from "./book/book-document.js";
+import { MAX_SLOT_DECLARATIONS, PreparedSlots, SlotFillRefusedError, hasSlotWork, prepareSlotCollection, prepareSlots, slotFillRefusal } from "./slots.js";
 //#region src/index.d.ts
 export type HtmlKind = 'plain' | 'live-data' | 'scripted' | 'refused';
 export declare function classify(html: string, prefix: string): HtmlKind;
 export declare function searchText(html: string): string;
 //#endregion
-export { BINDINGS, type BookDocument, type BookDocumentOptions, type BookHeading, type BookPrintPart, type BookSectionInfo, type FillOptions, type Filled, REFUSED_ELEMENTS, type SanitizeOptions, bindingNames, bookDocument, bookPrintPart, fill, findActiveContent, hasBindings, sanitize };
+export { BINDINGS, type BookDocument, type BookDocumentOptions, type BookHeading, type BookPrintPart, type BookSectionInfo, type FillOptions, type Filled, MAX_SLOT_DECLARATIONS, type PreparedSlots, REFUSED_ELEMENTS, type SanitizeOptions, SlotFillRefusedError, bindingNames, bookDocument, bookPrintPart, fill, findActiveContent, hasBindings, hasSlotWork, prepareSlotCollection, prepareSlots, sanitize, slotFillRefusal };

package/dist/index.js

@@ -2,6 +2,7 @@ import { REFUSED_ELEMENTS, elements, findActiveContent, parse, sanitize } from "
 import { BINDINGS, bindingNames, fill, hasBindings } from "./bindings.js";
 import { bookPrintPart } from "./book/types.js";
 import { bookDocument } from "./book/book-document.js";
+import { MAX_SLOT_DECLARATIONS, SlotFillRefusedError, hasSlotWork, prepareSlotCollection, prepareSlots, slotFillRefusal } from "./slots.js";
 //#region src/index.ts
 function classify(html, prefix) {
 	const scripted = elements(parse(html).children).some((element) => element.name.toLowerCase() === "script");
@@ -14,4 +15,4 @@ function searchText(html) {
 	return html.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
 }
 //#endregion
-export { BINDINGS, REFUSED_ELEMENTS, bindingNames, bookDocument, bookPrintPart, classify, fill, findActiveContent, hasBindings, sanitize, searchText };
+export { BINDINGS, MAX_SLOT_DECLARATIONS, REFUSED_ELEMENTS, SlotFillRefusedError, bindingNames, bookDocument, bookPrintPart, classify, fill, findActiveContent, hasBindings, hasSlotWork, prepareSlotCollection, prepareSlots, sanitize, searchText, slotFillRefusal };

package/dist/sanitize.js

@@ -48,7 +48,9 @@ const DATA_IMAGE = /^data:image\/(?:png|jpeg|gif|webp|svg\+xml)(?:[;,])/i;
 function parse(html) {
 	return parseDocument(html, {
 		lowerCaseAttributeNames: true,
-		recognizeSelfClosing: true
+		recognizeSelfClosing: true,
+		withStartIndices: true,
+		withEndIndices: true
 	});
 }
 function serialize(node) {

package/dist/slots.d.ts

@@ -0,0 +1,19 @@
+import { Scripts, SlotDeclaration, SlotReport, SlotsOptions } from "@segnavia/format";
+//#region src/slots.d.ts
+export declare const MAX_SLOT_DECLARATIONS = 200;
+export interface PreparedSlots {
+  report: SlotReport;
+  apply(html: string): string;
+}
+export declare class SlotFillRefusedError extends Error {
+  constructor(scripts: Exclude<Scripts, 'refuse'>);
+}
+/** Whether an item needs slot preparation for declarations, filling, asset resolution or reporting. */
+export declare function hasSlotWork(declarations: readonly SlotDeclaration[] | undefined, options: SlotsOptions | undefined): boolean;
+/** Refuses exposing filled values to an item's own scripts. */
+export declare function slotFillRefusal(scripts: Scripts, declarations: readonly SlotDeclaration[] | undefined, options: SlotsOptions | undefined): SlotFillRefusedError | undefined;
+/** Prepares and applies the slots declared by one item. */
+export declare function prepareSlots(declarations: readonly SlotDeclaration[] | undefined, options?: SlotsOptions, signal?: AbortSignal): Promise<PreparedSlots>;
+/** Prepares one shared fill for a collection, merging each item's declarations exactly once. */
+export declare function prepareSlotCollection(groups: ReadonlyArray<readonly SlotDeclaration[] | undefined>, options?: SlotsOptions, signal?: AbortSignal): Promise<PreparedSlots>;
+//#endregion

package/dist/slots.js

@@ -0,0 +1,237 @@
+import { elements, parse, serialize } from "./sanitize.js";
+import { bindingNames, hasBindings } from "./bindings.js";
+import { Text, isTag } from "domhandler";
+import { SlotsInput, mergeSlotDeclarations } from "@segnavia/format";
+//#region src/slots.ts
+const MAX_SLOT_DECLARATIONS = 200;
+const ASSET_RESOLUTION_CONCURRENCY = 4;
+var SlotFillRefusedError = class extends Error {
+	constructor(scripts) {
+		super(`A fill was not applied because this item runs its own scripts (scripts: '${scripts}'), which could read the filled values. Set the item's scripts to 'refuse', or show it without a fill.`);
+		this.name = "SlotFillRefusedError";
+	}
+};
+/** Whether an item needs slot preparation for declarations, filling, asset resolution or reporting. */
+function hasSlotWork(declarations, options) {
+	return Boolean(declarations?.length || options?.declarations?.length || options?.fill || options?.resolveAsset || options?.report);
+}
+/** Refuses exposing filled values to an item's own scripts. */
+function slotFillRefusal(scripts, declarations, options) {
+	const fillsValues = options?.fill && (declarations?.length || options.declarations?.length);
+	return scripts !== "refuse" && fillsValues ? new SlotFillRefusedError(scripts) : void 0;
+}
+const UNENCODED_TEXT_ELEMENTS = /* @__PURE__ */ new Set([
+	"style",
+	"script",
+	"xmp",
+	"iframe",
+	"noembed",
+	"noframes",
+	"plaintext",
+	"noscript",
+	"textarea",
+	"title"
+]);
+function refusesValueBinding(tag) {
+	return UNENCODED_TEXT_ELEMENTS.has(tag);
+}
+function assertDeclarationLimit(declarations, subject) {
+	if (declarations.length > 200) throw new RangeError(`${subject} declares ${declarations.length} slots; the limit is 200.`);
+}
+function parsedHostDeclarations(options) {
+	const declarations = options.declarations === void 0 ? [] : SlotsInput.parse(options.declarations);
+	assertDeclarationLimit(declarations, "The host");
+	return declarations;
+}
+function mergedDeclarations(groups, options) {
+	groups.forEach((group, index) => {
+		assertDeclarationLimit(group, groups.length === 1 ? "The item" : `Item ${index + 1}`);
+	});
+	return mergeSlotDeclarations(parsedHostDeclarations(options), ...groups);
+}
+function applyText(element, name, data) {
+	const path = element.attribs[name];
+	if (path === void 0) return;
+	delete element.attribs[name];
+	const value = data[path];
+	if (value === void 0) return;
+	const text = new Text(value);
+	text.parent = element;
+	element.children = [text];
+	if (element.attribs.dir === void 0) element.attribs.dir = "auto";
+}
+function invalidBinding(element, names, report) {
+	const tag = element.name.toLowerCase();
+	const value = element.attribs[names.value];
+	if (value !== void 0 && report.slots[value] !== void 0 && refusesValueBinding(tag)) {
+		report.slots[value] = "invalid";
+		return `Slot "${value}" uses a value binding on <${tag}>, whose raw-text content cannot be filled safely.`;
+	}
+	const src = element.attribs[names.src];
+	if (src !== void 0 && report.slots[src] !== void 0 && tag !== "img") {
+		report.slots[src] = "invalid";
+		return `Slot "${src}" uses a src binding on <${tag}>; src bindings are allowed only on <img>.`;
+	}
+	const href = element.attribs[names.href];
+	if (href !== void 0 && report.slots[href] !== void 0 && tag !== "a" && tag !== "area") {
+		report.slots[href] = "invalid";
+		return `Slot "${href}" uses an href binding on <${tag}>; href bindings are allowed only on <a> and <area>.`;
+	}
+}
+function applyUrl(element, attribute, name, resolved) {
+	const path = element.attribs[name];
+	if (path === void 0) return;
+	delete element.attribs[name];
+	const value = resolved.data[path];
+	if (typeof value !== "string") return;
+	if (attribute === "src") {
+		if (/^data:image\//i.test(value)) element.attribs.src = value;
+		return;
+	}
+	try {
+		if (resolved.linkOrigins.has(new URL(value).origin)) element.attribs.href = value;
+	} catch {}
+}
+function applyElement(element, names, resolved) {
+	applyText(element, names.value, resolved.data);
+	applyUrl(element, "href", names.href, resolved);
+	applyUrl(element, "src", names.src, resolved);
+	for (const child of element.children) if (isTag(child)) applyElement(child, names, resolved);
+}
+function bindingRefusal(roots, names, resolved) {
+	const reasons = [];
+	const visit = (element) => {
+		const reason = invalidBinding(element, names, resolved.report);
+		if (reason) reasons.push(reason);
+		for (const child of element.children) if (isTag(child)) visit(child);
+	};
+	for (const root of roots) visit(root);
+	if (reasons.length === 0) return void 0;
+	resolved.reportState?.(resolved.report);
+	return new RangeError(reasons.join(" "));
+}
+function validString(type, value) {
+	if (type === "email") return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+	if (type === "link") try {
+		return new URL(value).protocol === "https:";
+	} catch {
+		return false;
+	}
+	if (type === "image") return /^data:image\//i.test(value);
+	return true;
+}
+function assetResolver(options, signal) {
+	const cached = /* @__PURE__ */ new Map();
+	const waiting = [];
+	let running = 0;
+	const acquire = () => {
+		if (running < ASSET_RESOLUTION_CONCURRENCY) {
+			running++;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => waiting.push(resolve));
+	};
+	const release = () => {
+		const next = waiting.shift();
+		if (next) next();
+		else running--;
+	};
+	return (ref) => {
+		const held = cached.get(ref);
+		if (held) return held;
+		const resolution = (async () => {
+			if (!options.resolveAsset) return void 0;
+			await acquire();
+			try {
+				return await options.resolveAsset(ref, { signal });
+			} catch {
+				return;
+			} finally {
+				release();
+			}
+		})();
+		cached.set(ref, resolution);
+		return resolution;
+	};
+}
+async function valueFor(slot, value, resolveAsset) {
+	if (value === void 0) {
+		if (slot.placeholder === void 0) return { state: "unavailable" };
+		return validString(slot.type, slot.placeholder) ? {
+			value: slot.placeholder,
+			state: "placeholder"
+		} : { state: "invalid" };
+	}
+	if (typeof value === "string") return validString(slot.type, value) ? {
+		value,
+		state: "filled"
+	} : { state: "invalid" };
+	if (slot.type !== "image" || !value || typeof value.asset !== "string") return { state: "invalid" };
+	const resolved = await resolveAsset(value.asset);
+	if (resolved === void 0) return { state: "unavailable" };
+	return /^data:image\//i.test(resolved) ? {
+		value: resolved,
+		state: "filled"
+	} : { state: "invalid" };
+}
+async function resolveSlots(declarations, options, signal) {
+	const data = {};
+	const states = {};
+	const linkOrigins = /* @__PURE__ */ new Set();
+	const resolveAsset = assetResolver(options, signal);
+	await Promise.all(declarations.map(async (slot) => {
+		const resolved = await valueFor(slot, options.fill?.values[slot.key], resolveAsset);
+		states[slot.key] = resolved.state;
+		if (resolved.value !== void 0) {
+			data[slot.key] = resolved.value;
+			if (slot.type === "link" && resolved.state === "filled") linkOrigins.add(new URL(resolved.value).origin);
+		}
+	}));
+	signal.throwIfAborted();
+	const report = {
+		fill: options.fill?.id ?? null,
+		slots: states
+	};
+	options.report?.(report);
+	return {
+		data,
+		report,
+		linkOrigins,
+		reportState: options.report
+	};
+}
+function applySlots(html, resolved) {
+	if (Object.keys(resolved.report.slots).length === 0 || !hasBindings(html, "slot")) return html;
+	const names = bindingNames("slot");
+	const document = parse(html);
+	const bound = elements(document.children).filter((element) => Object.values(names).some((name) => element.attribs[name] !== void 0));
+	const roots = bound.filter((element) => {
+		for (let parent = element.parent; parent; parent = parent.parent) if (isTag(parent) && bound.includes(parent)) return false;
+		return true;
+	});
+	const refusal = bindingRefusal(roots, names, resolved);
+	if (refusal) throw refusal;
+	for (const root of roots) applyElement(root, names, resolved);
+	return roots.map((root) => ({
+		start: root.startIndex,
+		end: root.endIndex,
+		html: serialize(root)
+	})).filter((part) => part.start !== null && part.end !== null).sort((a, b) => b.start - a.start).reduce((output, part) => `${output.slice(0, part.start)}${part.html}${output.slice(part.end + 1)}`, html);
+}
+async function prepared(declarations, options, signal) {
+	const resolved = await resolveSlots(declarations, options, signal);
+	return {
+		report: resolved.report,
+		apply: (html) => applySlots(html, resolved)
+	};
+}
+/** Prepares and applies the slots declared by one item. */
+async function prepareSlots(declarations, options = {}, signal = new AbortController().signal) {
+	return prepared(mergedDeclarations([declarations ?? []], options), options, signal);
+}
+/** Prepares one shared fill for a collection, merging each item's declarations exactly once. */
+async function prepareSlotCollection(groups, options = {}, signal = new AbortController().signal) {
+	return prepared(mergedDeclarations(groups.map((group) => group ?? []), options), options, signal);
+}
+//#endregion
+export { MAX_SLOT_DECLARATIONS, SlotFillRefusedError, hasSlotWork, prepareSlotCollection, prepareSlots, slotFillRefusal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segnavia/html",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@segnavia/format": "0.20.0",
+    "@segnavia/format": "0.22.0",
     "htmlparser2": "^10.0.0",
     "domhandler": "^5.0.3",
     "dom-serializer": "^2.0.0"