@segnavia/html 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modstudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bindings.d.ts

@@ -0,0 +1,17 @@
+import { SanitizeOptions } from "./sanitize.js";
+//#region src/bindings.d.ts
+export declare const BINDINGS: readonly ["value", "href", "src", "each", "when", "present", "width"];
+export declare function bindingNames(prefix: string): Record<(typeof BINDINGS)[number], string>;
+export interface FillOptions extends Pick<SanitizeOptions, 'linkOrigins'> {
+  prefix: string;
+  data: Record<string, unknown>;
+  unavailable?: Iterable<string>;
+}
+export interface Filled {
+  html: string;
+  unavailable: string[];
+  values: string[];
+}
+export declare function hasBindings(html: string, prefix: string): boolean;
+export declare function fill(html: string, options: FillOptions): Filled;
+//#endregion

package/dist/bindings.js

@@ -0,0 +1,155 @@
+import { elements, parse, sanitize, serialize } from "./sanitize.js";
+import { Text, cloneNode, isTag } from "domhandler";
+//#region src/bindings.ts
+const BINDINGS = [
+	"value",
+	"href",
+	"src",
+	"each",
+	"when",
+	"present",
+	"width"
+];
+function bindingNames(prefix) {
+	return Object.fromEntries(BINDINGS.map((binding) => [binding, `data-${prefix}-${binding}`]));
+}
+function atPath(value, path) {
+	if (!path) return value;
+	const parts = path.split(".");
+	let held = value;
+	let start = 0;
+	if (held && typeof held === "object" && !Array.isArray(held)) for (let length = parts.length; length > 0; length -= 1) {
+		const prefix = parts.slice(0, length).join(".");
+		if (Object.hasOwn(held, prefix)) {
+			held = Reflect.get(held, prefix);
+			start = length;
+			break;
+		}
+	}
+	return parts.slice(start).reduce((current, part) => {
+		if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+		return Object.hasOwn(current, part) ? Reflect.get(current, part) : void 0;
+	}, held);
+}
+function contextAt(stack, path) {
+	let depth = 0;
+	let rest = path;
+	while (rest.startsWith("../")) {
+		depth += 1;
+		rest = rest.slice(3);
+	}
+	return {
+		context: stack[Math.max(0, stack.length - 1 - depth)],
+		rest
+	};
+}
+function isPresent(value) {
+	if (value === void 0 || value === null || value === false) return false;
+	if (typeof value === "number") return value !== 0 && Number.isFinite(value);
+	if (typeof value === "string" || Array.isArray(value)) return value.length > 0;
+	return true;
+}
+function safeHref(value, origins) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" && origins.has(url.origin);
+	} catch {
+		return false;
+	}
+}
+function hasBindings(html, prefix) {
+	const names = new Set(Object.values(bindingNames(prefix)));
+	return elements(parse(html).children).some((element) => Object.keys(element.attribs).some((name) => names.has(name)));
+}
+function fill(html, options) {
+	const names = bindingNames(options.prefix);
+	const origins = new Set([...options.linkOrigins ?? []].map((origin) => new URL(origin).origin));
+	const unavailable = new Set(options.unavailable ?? []);
+	const values = [];
+	const document = parse(sanitize(html, { linkOrigins: options.linkOrigins }));
+	const resolve = (path, stack) => {
+		const { context, rest } = contextAt(stack, path);
+		const value = atPath(context, rest);
+		if (value === void 0) unavailable.add(path);
+		return value;
+	};
+	const take = (element, name) => {
+		const value = element.attribs[name];
+		delete element.attribs[name];
+		return value;
+	};
+	const applies = (element, stack) => {
+		const context = stack[stack.length - 1];
+		const when = take(element, names.when);
+		if (when !== void 0 && (!context || typeof context !== "object" || Reflect.get(context, "state") !== when)) return false;
+		const present = take(element, names.present);
+		return present === void 0 || isPresent(resolve(present, stack));
+	};
+	const applyWidth = (element, stack) => {
+		const width = take(element, names.width);
+		if (width === void 0) return;
+		const value = resolve(width, stack);
+		if (typeof value === "number" && Number.isFinite(value)) element.attribs.style = `width: ${Math.min(100, Math.max(0, value))}%`;
+		else unavailable.add(width);
+	};
+	const applyValue = (element, stack) => {
+		const path = take(element, names.value);
+		if (path === void 0) return;
+		const value = resolve(path, stack);
+		element.children = [];
+		if (typeof value === "string" || typeof value === "number" && Number.isFinite(value)) {
+			const text = new Text(String(value));
+			text.parent = element;
+			element.children = [text];
+			if (element.attribs.dir === void 0) element.attribs.dir = "auto";
+			values.push(String(value));
+		} else if (value !== void 0) unavailable.add(path);
+	};
+	const applyUrls = (element, stack) => {
+		for (const attribute of ["href", "src"]) {
+			const path = take(element, names[attribute]);
+			if (path === void 0) continue;
+			const value = resolve(path, stack);
+			if (typeof value === "string" && (attribute === "href" ? safeHref(value, origins) : /^data:image\//i.test(value))) element.attribs[attribute] = value;
+			else {
+				delete element.attribs[attribute];
+				if (value !== void 0) unavailable.add(path);
+			}
+		}
+	};
+	const fillElement = (element, stack) => {
+		const each = take(element, names.each);
+		if (each !== void 0) {
+			const list = resolve(each, stack);
+			if (Array.isArray(list)) return list.flatMap((item) => fillElement(cloneNode(element, true), [...stack, item]));
+			unavailable.add(each);
+			return [];
+		}
+		if (!applies(element, stack)) return [];
+		applyWidth(element, stack);
+		applyValue(element, stack);
+		applyUrls(element, stack);
+		element.children = element.children.flatMap((child) => {
+			if (!isTag(child)) return [child];
+			return fillElement(child, stack).map((filled) => {
+				filled.parent = element;
+				return filled;
+			});
+		});
+		return [element];
+	};
+	document.children = document.children.flatMap((node) => {
+		if (!isTag(node)) return [node];
+		return fillElement(node, [options.data]).map((filled) => {
+			filled.parent = document;
+			return filled;
+		});
+	});
+	return {
+		html: serialize(document),
+		unavailable: [...unavailable],
+		values
+	};
+}
+//#endregion
+export { BINDINGS, bindingNames, fill, hasBindings };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { REFUSED_ELEMENTS, SanitizeOptions, findActiveContent, sanitize } from "./sanitize.js";
+import { BINDINGS, FillOptions, Filled, bindingNames, fill, hasBindings } from "./bindings.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 FillOptions, type Filled, REFUSED_ELEMENTS, type SanitizeOptions, bindingNames, fill, findActiveContent, hasBindings, sanitize };

package/dist/index.js

@@ -0,0 +1,15 @@
+import { REFUSED_ELEMENTS, elements, findActiveContent, parse, sanitize } from "./sanitize.js";
+import { BINDINGS, bindingNames, fill, hasBindings } from "./bindings.js";
+//#region src/index.ts
+function classify(html, prefix) {
+	const scripted = elements(parse(html).children).some((element) => element.name.toLowerCase() === "script");
+	const bound = hasBindings(html, prefix);
+	if (scripted && bound) return "refused";
+	if (scripted) return "scripted";
+	return bound ? "live-data" : "plain";
+}
+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, classify, fill, findActiveContent, hasBindings, sanitize, searchText };

package/dist/sanitize.d.ts

@@ -0,0 +1,11 @@
+import "domhandler";
+//#region src/sanitize.d.ts
+export declare const REFUSED_ELEMENTS: Set<string>;
+export interface SanitizeOptions {
+  linkOrigins?: Iterable<string>;
+  keepScripts?: boolean;
+  refuseElements?: Iterable<string>;
+}
+export declare function findActiveContent(html: string, options?: SanitizeOptions): string[];
+export declare function sanitize(html: string, options?: SanitizeOptions): string;
+//#endregion

package/dist/sanitize.js

@@ -0,0 +1,152 @@
+import { isTag } from "domhandler";
+import render from "dom-serializer";
+import { parseDocument } from "htmlparser2";
+//#region src/sanitize.ts
+const REFUSED_ELEMENTS = /* @__PURE__ */ new Set([
+	"script",
+	"iframe",
+	"frame",
+	"frameset",
+	"object",
+	"embed",
+	"applet",
+	"base",
+	"portal",
+	"link",
+	"form",
+	"input",
+	"button",
+	"select",
+	"textarea"
+]);
+const REFUSED_SVG_ELEMENTS = /* @__PURE__ */ new Set([
+	"script",
+	"animate",
+	"set",
+	"animatetransform",
+	"animatemotion",
+	"foreignobject"
+]);
+const REFUSED_ATTRIBUTES = /* @__PURE__ */ new Set([
+	"srcdoc",
+	"formaction",
+	"action"
+]);
+const URL_ATTRIBUTES = /* @__PURE__ */ new Set([
+	"href",
+	"xlink:href",
+	"src",
+	"srcset",
+	"poster",
+	"background",
+	"data",
+	"cite",
+	"longdesc",
+	"ping"
+]);
+const DATA_IMAGE = /^data:image\/(?:png|jpeg|gif|webp|svg\+xml)(?:[;,])/i;
+function parse(html) {
+	return parseDocument(html, {
+		lowerCaseAttributeNames: true,
+		recognizeSelfClosing: true
+	});
+}
+function serialize(node) {
+	return render(node, { encodeEntities: "utf8" });
+}
+function elements(nodes) {
+	const found = [];
+	const walk = (list) => {
+		for (const node of list) {
+			if (!isTag(node)) continue;
+			found.push(node);
+			walk(node.children);
+		}
+	};
+	walk(nodes);
+	return found;
+}
+function insideSvg(element) {
+	for (let parent = element.parent; parent; parent = parent.parent) if (isTag(parent) && parent.name.toLowerCase() === "svg") return true;
+	return false;
+}
+function normalizeUrl(value) {
+	return [...value].filter((c) => c.charCodeAt(0) > 32 && c.charCodeAt(0) !== 127).join("").toLowerCase();
+}
+function origins(values) {
+	const set = /* @__PURE__ */ new Set();
+	for (const value of values ?? []) try {
+		const url = new URL(value);
+		if (url.protocol === "https:") set.add(url.origin.toLowerCase());
+	} catch {}
+	return set;
+}
+function safeUrl(attribute, value, allowed) {
+	const url = normalizeUrl(value);
+	if (attribute === "href" || attribute === "xlink:href") {
+		if (url.startsWith("#")) return true;
+		try {
+			const parsed = new URL(url);
+			return parsed.protocol === "https:" && allowed.has(parsed.origin);
+		} catch {
+			return false;
+		}
+	}
+	if (attribute === "srcset") return /^data:image\/(?:png|jpeg|gif|webp|svg\+xml)(?:;[^,]*)?,[^,]*$/i.test(url);
+	if (attribute === "src" || attribute === "poster") return DATA_IMAGE.test(url);
+	return false;
+}
+function safeStyle(value) {
+	const matches = [...value.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi)];
+	if ((value.match(/url\(/gi)?.length ?? 0) !== matches.length) return false;
+	return matches.every((match) => normalizeUrl(match[2] ?? "").startsWith("data:image/"));
+}
+function refusedStyleElement(element) {
+	if (element.name.toLowerCase() !== "style") return false;
+	const text = element.children.map((child) => "data" in child ? child.data : "").join("");
+	return /@import/i.test(text) || !safeStyle(text);
+}
+function refusedElement(element, refused, keepScripts) {
+	const name = element.name.toLowerCase();
+	if (name === "script") return !keepScripts;
+	if (refusedStyleElement(element)) return true;
+	if (refused.has(name)) return true;
+	if (insideSvg(element) && REFUSED_SVG_ELEMENTS.has(name)) return true;
+	return name === "meta" && Object.keys(element.attribs).some((attribute) => attribute.toLowerCase() === "http-equiv");
+}
+function refusedAttribute(name, value, allowed, keepScripts) {
+	const attribute = name.toLowerCase();
+	if (attribute.startsWith("on")) return !keepScripts;
+	return REFUSED_ATTRIBUTES.has(attribute) || URL_ATTRIBUTES.has(attribute) && !safeUrl(attribute, value, allowed) || attribute === "style" && !safeStyle(value);
+}
+function refusedSet(options) {
+	return new Set([...REFUSED_ELEMENTS, ...options.refuseElements ?? []].map((name) => name.toLowerCase()));
+}
+function findActiveContent(html, options = {}) {
+	const allowed = origins(options.linkOrigins);
+	const refused = refusedSet(options);
+	const keepScripts = options.keepScripts ?? false;
+	const found = [];
+	for (const element of elements(parse(html).children)) {
+		if (refusedElement(element, refused, keepScripts)) found.push(`<${element.name}>`);
+		for (const [name, value] of Object.entries(element.attribs)) if (refusedAttribute(name, value, allowed, keepScripts)) found.push(`${element.name}[${name}]`);
+	}
+	return found;
+}
+function sanitize(html, options = {}) {
+	const allowed = origins(options.linkOrigins);
+	const refused = refusedSet(options);
+	const keepScripts = options.keepScripts ?? false;
+	const document = parse(html);
+	const prune = (nodes) => nodes.filter((node) => {
+		if (!isTag(node)) return true;
+		if (refusedElement(node, refused, keepScripts)) return false;
+		for (const [name, value] of Object.entries(node.attribs)) if (refusedAttribute(name, value, allowed, keepScripts)) delete node.attribs[name];
+		node.children = prune(node.children);
+		return true;
+	});
+	document.children = prune(document.children);
+	return serialize(document);
+}
+//#endregion
+export { REFUSED_ELEMENTS, elements, findActiveContent, parse, sanitize, serialize };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@segnavia/html",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modstudio/segnavia.git",
+    "directory": "packages/html"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "@segnavia/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "htmlparser2": "^10.0.0",
+    "domhandler": "^5.0.3",
+    "dom-serializer": "^2.0.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.