@segnavia/html 0.26.0 → 0.28.0

package/dist/motifs.js

@@ -0,0 +1,245 @@
+import { elements, parse, sanitize, serialize } from "./sanitize.js";
+import { bindingNames, bindingRoot, fill, hasBindings } from "./bindings.js";
+import { isTag } from "domhandler";
+import { LIBRARY_MOTIF_PREFIX, MOTIF_ATTRIBUTE, PRINTED_PAGE_CONTEXT, chooseMotifVersion, motifFieldAttribute, resolveDirection } from "@segnavia/format";
+//#region src/motifs.ts
+const MOTIF_DEPTH_LIMIT = 8;
+var MotifRefusedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MotifRefusedError";
+	}
+};
+function placementName(element) {
+	return `motif placement ${Object.entries(element.attribs).filter(([name]) => name === MOTIF_ATTRIBUTE || name.startsWith(`${MOTIF_ATTRIBUTE}-`)).sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => `${name}=${JSON.stringify(value)}`).join(", ") || `${MOTIF_ATTRIBUTE}=""`}`;
+}
+function refusal(element, problem, remedy) {
+	return `${placementName(element)} could not establish ${problem}; ${remedy} to clear this refusal.`;
+}
+function motifElements(html) {
+	return elements(parse(html).children).filter((element) => Object.hasOwn(element.attribs, MOTIF_ATTRIBUTE));
+}
+function libraryMotifPlacementRefusal(html) {
+	const placed = motifElements(html).find((element) => (element.attribs[MOTIF_ATTRIBUTE] ?? "").startsWith(LIBRARY_MOTIF_PREFIX));
+	return placed ? refusal(placed, `a host motif key because "${LIBRARY_MOTIF_PREFIX}" is reserved for library motifs`, "rename the motif key") : void 0;
+}
+function hasMotifPlacement(html) {
+	return motifElements(html).length > 0;
+}
+function renderMotifPlacements(html, replacement) {
+	const document = parse(html);
+	const visit = (nodes) => {
+		for (const node of [...nodes]) {
+			if (!isTag(node)) continue;
+			if (Object.hasOwn(node.attribs, MOTIF_ATTRIBUTE)) {
+				const rendered = replacement(node.attribs[MOTIF_ATTRIBUTE] ?? "");
+				if (rendered === void 0) {
+					const index = nodes.indexOf(node);
+					if (index >= 0) nodes.splice(index, 1);
+					continue;
+				}
+				delete node.attribs[MOTIF_ATTRIBUTE];
+				replaceChildren(node, rendered);
+			}
+			visit(node.children);
+		}
+	};
+	visit(document.children);
+	return serialize(document);
+}
+function refuse(state, element, problem, remedy) {
+	const message = refusal(element, problem, remedy);
+	if (!state.validateOnly) throw new MotifRefusedError(message);
+	state.refusals.push(message);
+	return false;
+}
+function placementValues(element, motif, inheritedLang, state) {
+	const known = new Set(motif.fields.map((field) => motifFieldAttribute(field.key).toLowerCase()));
+	known.add(motifFieldAttribute("lang").toLowerCase());
+	const unknown = Object.keys(element.attribs).filter((name) => name.startsWith(`${MOTIF_ATTRIBUTE}-`) && !known.has(name));
+	if (unknown.length > 0) {
+		refuse(state, element, `fields for ${unknown.join(", ")}`, "remove the unknown field attributes");
+		return;
+	}
+	const values = {};
+	for (const field of motif.fields) {
+		const value = element.attribs[motifFieldAttribute(field.key).toLowerCase()] ?? field.default;
+		if (value === void 0) {
+			if (field.required) {
+				refuse(state, element, `a value for required field "${field.key}"`, `set ${motifFieldAttribute(field.key)}`);
+				return;
+			}
+			continue;
+		}
+		if (field.choices && !field.choices.includes(value)) {
+			refuse(state, element, `an allowed value for field "${field.key}"`, `set ${motifFieldAttribute(field.key)} to one of ${field.choices.join(", ")}`);
+			return;
+		}
+		values[field.key] = value;
+	}
+	const lang = element.attribs[motifFieldAttribute("lang")] ?? inheritedLang;
+	if (lang !== void 0) values.lang = lang;
+	return values;
+}
+function replaceChildren(element, html) {
+	const children = parse(html).children;
+	for (const child of children) child.parent = element;
+	element.children = children;
+}
+function needsHostData(html, options) {
+	const deferred = new Set(options.deferPaths ?? []);
+	const names = new Set(Object.values(bindingNames(options.prefix)));
+	return elements(parse(html).children).some((held) => Object.entries(held.attribs).some(([name, path]) => names.has(name) && !deferred.has(bindingRoot(path))));
+}
+async function fillVersion(html, placement, element, state) {
+	const data = await state.options.source.data?.(placement, { signal: state.options.signal });
+	state.options.signal.throwIfAborted();
+	if (data && new Set(state.options.deferPaths ?? []).has(PRINTED_PAGE_CONTEXT) && Object.hasOwn(data, PRINTED_PAGE_CONTEXT)) {
+		refuse(state, element, `the reserved ${PRINTED_PAGE_CONTEXT} context because host data contains that key`, `remove ${PRINTED_PAGE_CONTEXT} from MotifSource.data`);
+		return;
+	}
+	const filled = fill(html, {
+		prefix: state.options.prefix,
+		data: data ?? {},
+		linkOrigins: state.options.linkOrigins,
+		dataFonts: state.options.dataFonts,
+		registerHrefOrigins: true,
+		deferPaths: state.options.deferPaths
+	});
+	for (const path of filled.unavailable) state.unavailable.add(path);
+	return filled.html;
+}
+async function motifFor(element, state) {
+	const key = element.attribs[MOTIF_ATTRIBUTE] ?? "";
+	if (!key) {
+		refuse(state, element, "a motif key", `set ${MOTIF_ATTRIBUTE} to a known motif key`);
+		return;
+	}
+	if (key.startsWith(LIBRARY_MOTIF_PREFIX)) {
+		refuse(state, element, `a host motif key because "${LIBRARY_MOTIF_PREFIX}" is reserved for library motifs`, "rename the motif key");
+		return;
+	}
+	const revision = state.options.pins && Object.hasOwn(state.options.pins, key) ? state.options.pins[key] : void 0;
+	const cacheKey = JSON.stringify([key, revision]);
+	let request = state.motifCache.get(cacheKey);
+	if (!request) {
+		request = state.options.source.motif(key, {
+			...revision === void 0 ? {} : { revision },
+			signal: state.options.signal
+		});
+		state.motifCache.set(cacheKey, request);
+	}
+	const motif = await request;
+	state.options.signal.throwIfAborted();
+	if (!motif) {
+		refuse(state, element, `motif "${key}"${revision ? ` at revision "${revision}"` : ""}`, "make that motif available from the source");
+		return;
+	}
+	if (motif.key.startsWith(LIBRARY_MOTIF_PREFIX)) {
+		refuse(state, element, `a host MotifSource result key because "${LIBRARY_MOTIF_PREFIX}" is reserved for library motifs`, "rename the motif key");
+		return;
+	}
+	return motif;
+}
+async function expandPlacement(element, inheritedLang, stack, state) {
+	state.options.signal.throwIfAborted();
+	state.placements += 1;
+	if (state.placements > 256) {
+		refuse(state, element, `at most 256 expanded motif placements`, "reduce the number of motif placements");
+		return;
+	}
+	const motif = await motifFor(element, state);
+	if (!motif) return;
+	if (stack.includes(motif.key)) {
+		refuse(state, element, `an acyclic motif path because "${motif.key}" occurs in ${[...stack, motif.key].join(" -> ")}`, "remove the motif cycle");
+		return;
+	}
+	if (stack.length >= 8) {
+		refuse(state, element, `a nesting depth within 8`, "reduce the motif nesting depth");
+		return;
+	}
+	const values = placementValues(element, motif, inheritedLang, state);
+	if (!values) return;
+	const choice = chooseMotifVersion(motif, values);
+	if (!choice.ok) {
+		refuse(state, element, `a unique matching version: ${choice.reason}`, "add or revise a matching motif version or its placement values");
+		return;
+	}
+	const bound = hasBindings(choice.version.html, state.options.prefix);
+	if (bound && state.options.scripts !== "refuse") {
+		refuse(state, element, "a data-free motif version for a scripted page", "remove its bindings or refuse page scripts");
+		return;
+	}
+	if (needsHostData(choice.version.html, state.options) && !state.options.source.data) {
+		refuse(state, element, "data for the motif version bindings", "provide MotifSource.data or remove the bindings");
+		return;
+	}
+	const lang = choice.version.lang;
+	const fields = Object.fromEntries(Object.entries(values).filter(([key]) => key !== "lang"));
+	const placement = {
+		key: motif.key,
+		revision: motif.revision,
+		lang,
+		fields
+	};
+	let versionHtml = sanitize(choice.version.html, {
+		linkOrigins: state.options.linkOrigins,
+		dataFonts: state.options.dataFonts
+	});
+	if (bound && !state.validateOnly) {
+		const filled = await fillVersion(versionHtml, placement, element, state);
+		if (filled === void 0) return;
+		versionHtml = filled;
+	}
+	element.attribs.lang = lang;
+	element.attribs.dir = choice.version.dir ?? resolveDirection(void 0, lang, versionHtml);
+	replaceChildren(element, versionHtml);
+	if (!state.validateOnly) {
+		state.placed.push({
+			...placement,
+			version: choice.index
+		});
+		for (const font of motif.fonts) state.fonts.set(JSON.stringify(font), font);
+	}
+	await expandNodes(element.children, lang, [...stack, motif.key], state);
+}
+async function expandNodes(nodes, inheritedLang, stack, state) {
+	for (const node of [...nodes]) {
+		state.options.signal.throwIfAborted();
+		if (!isTag(node)) continue;
+		if (Object.hasOwn(node.attribs, MOTIF_ATTRIBUTE)) await expandPlacement(node, inheritedLang, stack, state);
+		else await expandNodes(node.children, inheritedLang, stack, state);
+	}
+}
+async function run(html, options, validateOnly) {
+	const document = parse(html);
+	const state = {
+		options,
+		validateOnly,
+		refusals: [],
+		placed: [],
+		fonts: /* @__PURE__ */ new Map(),
+		unavailable: /* @__PURE__ */ new Set(),
+		motifCache: /* @__PURE__ */ new Map(),
+		placements: 0
+	};
+	await expandNodes(document.children, options.lang, [], state);
+	return {
+		document,
+		state
+	};
+}
+async function expandMotifs(html, options) {
+	const { document, state } = await run(html, options, false);
+	return {
+		html: serialize(document),
+		placed: state.placed,
+		fonts: [...state.fonts.values()],
+		unavailable: [...state.unavailable]
+	};
+}
+async function motifPlacementRefusals(html, options) {
+	return (await run(html, options, true)).state.refusals;
+}
+//#endregion
+export { MOTIF_DEPTH_LIMIT, MotifRefusedError, expandMotifs, hasMotifPlacement, libraryMotifPlacementRefusal, motifPlacementRefusals, renderMotifPlacements };

package/dist/printed-pages.d.ts

@@ -0,0 +1,42 @@
+import { BookSectionParents as BookSectionParents$1, NumberSystem, PrintedPageRole, PrintedPageRules } from "@segnavia/format";
+//#region src/printed-pages.d.ts
+export type PrintedPageSide = 'left' | 'right';
+export interface PrintedPagePlan {
+  index: number;
+  role: PrintedPageRole;
+  parent: string;
+  side: PrintedPageSide;
+  number: string;
+  total: string;
+}
+export type BookPrintedPageRole = 'recto' | 'verso' | 'opener' | 'blank' | 'fixed';
+export interface BookPageFacts {
+  blank: boolean;
+  sectionOpening: boolean;
+  folio?: string;
+  runningHead?: string;
+  role?: BookPrintedPageRole | 'body';
+  parents?: BookSectionParents$1;
+}
+export interface BookPrintedPagePlan extends Omit<BookPageFacts, 'blank' | 'sectionOpening'> {
+  index: number;
+  role: BookPrintedPageRole;
+  parent: string;
+  side: PrintedPageSide;
+}
+export declare function printedPageAt(rules: PrintedPageRules, index: number, count: number, direction: 'ltr' | 'rtl'): Pick<PrintedPagePlan, 'role' | 'parent' | 'side'>;
+export declare function planPrintedPages(rules: PrintedPageRules, count: number, direction: 'ltr' | 'rtl', numbering?: NumberSystem): PrintedPagePlan[];
+export declare function selectBookParent(fact: BookPageFacts, index: number, count: number, direction: 'ltr' | 'rtl', names?: {
+  readonly recto: "segnavia:recto";
+  readonly verso: "segnavia:verso";
+  readonly opener: "segnavia:opener";
+  readonly blank: "segnavia:blank";
+}): Pick<BookPrintedPagePlan, 'role' | 'parent' | 'side'>;
+export declare function planBookPages(facts: BookPageFacts[], direction: 'ltr' | 'rtl', names?: {
+  readonly recto: "segnavia:recto";
+  readonly verso: "segnavia:verso";
+  readonly opener: "segnavia:opener";
+  readonly blank: "segnavia:blank";
+}): BookPrintedPagePlan[];
+//#endregion
+export type { BookSectionParents$1 as BookSectionParents };

package/dist/printed-pages.js

@@ -0,0 +1,97 @@
+import { BOOK_PARENT_NAMES, formatNumber } from "@segnavia/format";
+//#region src/printed-pages.ts
+function printedPageAt(rules, index, count, direction) {
+	const recto = index % 2 === 1;
+	const side = recto === (direction === "ltr") ? "right" : "left";
+	let role = "every";
+	let parent = rules.every;
+	if (recto && rules.recto) {
+		role = "recto";
+		parent = rules.recto;
+	} else if (!recto && rules.verso) {
+		role = "verso";
+		parent = rules.verso;
+	}
+	if (index === count && rules.last) {
+		role = "last";
+		parent = rules.last;
+	}
+	if (index === 1 && rules.first) {
+		role = "first";
+		parent = rules.first;
+	}
+	return {
+		role,
+		parent,
+		side
+	};
+}
+function planPrintedPages(rules, count, direction, numbering = "arabic") {
+	if (!Number.isSafeInteger(count) || count < 1) throw new RangeError("A printed-page plan needs a positive safe page count.");
+	const total = formatNumber(count, numbering);
+	return Array.from({ length: count }, (_, offset) => {
+		const index = offset + 1;
+		return {
+			index,
+			...printedPageAt(rules, index, count, direction),
+			number: formatNumber(index, numbering),
+			total
+		};
+	});
+}
+function selectBookParent(fact, index, count, direction, names = BOOK_PARENT_NAMES) {
+	const physical = printedPageAt({
+		every: names.recto,
+		recto: names.recto,
+		verso: names.verso
+	}, index, count, direction);
+	const named = fact.parents;
+	if (fact.blank) return {
+		role: "blank",
+		parent: named?.blank ?? names.blank,
+		side: physical.side
+	};
+	if (fact.role === "fixed") return {
+		role: "fixed",
+		parent: named?.fixed ?? names.blank,
+		side: physical.side
+	};
+	if (fact.sectionOpening && fact.role !== "body") return {
+		role: "opener",
+		parent: named?.opener ?? names.opener,
+		side: physical.side
+	};
+	if (physical.role === "verso") return {
+		role: "verso",
+		parent: named?.verso ?? names.verso,
+		side: physical.side
+	};
+	return {
+		role: "recto",
+		parent: named?.recto ?? names.recto,
+		side: physical.side
+	};
+}
+function planBookPages(facts, direction, names = BOOK_PARENT_NAMES) {
+	return facts.map((fact, offset) => {
+		const index = offset + 1;
+		const selected = selectBookParent(fact, index, facts.length, direction, names);
+		if (selected.role === "blank") return {
+			index,
+			...selected
+		};
+		if (selected.role === "opener") return {
+			index,
+			...selected,
+			...fact.folio === void 0 ? {} : { folio: fact.folio }
+		};
+		return {
+			index,
+			...selected,
+			...fact.folio === void 0 ? {} : { folio: fact.folio },
+			...fact.runningHead === void 0 ? {} : { runningHead: fact.runningHead }
+		};
+	});
+}
+//#endregion
+export { planBookPages, planPrintedPages, printedPageAt, selectBookParent };

package/dist/sanitize-css.d.ts

@@ -0,0 +1,6 @@
+//#region src/sanitize-css.d.ts
+export interface CssSanitizeResult {
+  css: string;
+  removed: string[];
+}
+//#endregion