@localnerve/web-component-build 3.3.0 → 3.4.0-rc.2

package/index.js

@@ -6,4 +6,5 @@
  * Copyright (c) 2023 - 2025 Alex Grant (@localnerve), LocalNerve LLC
  * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
  */
-export {build, build as default} from './lib/index.js';
+export { build, build as default } from './lib/index.js';
+export * as browser from './lib/browser/index.js';

package/lib/browser/index.js

@@ -0,0 +1,9 @@
+/**
+ * Browser api helper exports
+ * Exports code that would be duplicated across web components interfacing with browser apis.
+ *
+ * Copyright (c) 2023 - 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+
+export { escapeHtml, getTrustedPolicy, trustedHtml } from './trusted-types.js';

package/lib/browser/trusted-types.js

@@ -0,0 +1,75 @@
+/**
+ * Trusted Types runtime helpers for web components.
+ * 
+ * Lets a component be authored so it works both with and without Trusted
+ * Types enforcement (CSP `require-trusted-types-for 'script'`):
+ * 
+ *   - static, author-controlled markup (shadow DOM templates, static snippets)
+ *     is registered once through the component's own named policy and handed
+ *     to sinks as a trusted value;
+ *   - dynamic, user-influenced values are escaped with escapeHtml() before
+ *     being composed into markup;
+ *   - in browsers without Trusted Types (or when CSP is not enforced) every
+ *     helper degrades to a plain-string passthrough, so components keep
+ *     working unchanged.
+ * 
+ * The component MUST list its policy name in the site's CSP `trusted-types`
+ * directive, e.g. `trusted-types default my-component;`. A build step can
+ * compute that allowlist from the sources (see @localnerve/trusted-types-rules).
+ * 
+ * Copyright (c) 2023 - 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+
+// per-module policy cache: a name may only be created once without the CSP
+// 'allow-duplicates' keyword, so repeated calls must reuse the instance
+const policies = new Map();
+
+/**
+ * Escape a value for safe interpolation into HTML markup (text or attribute).
+ * 
+ * @param {Any} input - The value to escape
+ * @returns {String} The escaped string. null/undefined yield ''.
+ */
+export function escapeHtml (input) {
+  if (input === null || typeof input === 'undefined') return '';
+  return String(input)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Get (creating once) a named Trusted Type policy.
+ * 
+ * @param {String} name - The policy name. Must be allowlisted in the CSP trusted-types directive when enforcement is active.
+ * @param {Object} [hooks] - Policy hooks. Defaults to pass-through createHTML/createScriptURL, appropriate for author-controlled content that has already been escaped where needed.
+ * @returns {TrustedTypePolicy|null} The policy, or null when Trusted Types is unavailable (passthrough mode).
+ */
+export function getTrustedPolicy (name, hooks = {
+  createHTML: input => String(input),
+  createScriptURL: input => String(input)
+}) {
+  if (!(typeof window !== 'undefined' && 'trustedTypes' in window)) {
+    return null;
+  }
+  if (!policies.has(name)) {
+    policies.set(name, trustedTypes.createPolicy(name, hooks));
+  }
+  return policies.get(name);
+}
+
+/**
+ * Convert author-controlled (or pre-escaped) markup into a value that is safe
+ * to pass to an HTML injection sink under Trusted Types enforcement.
+ * 
+ * @param {String} policyName - The named policy to use (must be CSP allowlisted).
+ * @param {String} html - Author-controlled or already-escaped markup.
+ * @returns {TrustedHTML|String} A trusted value when enforced, otherwise the input string unchanged (passthrough for dev builds / browsers without Trusted Types).
+ */
+export function trustedHtml (policyName, html) {
+  const policy = getTrustedPolicy(policyName);
+  return policy ? policy.createHTML(html) : html;
+}

package/lib/build.js

@@ -8,8 +8,8 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
 import CleanCss from 'clean-css';
-import {minify as _minifyHtml} from 'html-minifier-terser';
-import {minify as _minifyJs} from 'terser';
+import { minify as _minifyHtml } from 'html-minifier-terser';
+import { minify as _minifyJs } from 'terser';
 
 export const defaultHtmlMinifyOptions = {
   minifyJS: true,

package/lib/index.js

@@ -8,7 +8,7 @@
  */
 import * as fs from 'node:fs/promises';
 import * as cheerio from 'cheerio';
-import {createBuild, defaultHtmlMinifyOptions} from './build.js';
+import { createBuild, defaultHtmlMinifyOptions } from './build.js';
 
 /**
  * Build entry point.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localnerve/web-component-build",
-  "version": "3.3.0",
+  "version": "3.4.0-rc.2",
   "description": "A library to help build web components",
   "main": "index.js",
   "type": "module",
@@ -11,7 +11,7 @@
   "scripts": {
     "lint": "eslint .",
     "pretest": "node -e \"const fs=require('fs');fs.rmSync('./coverage',{recursive:true,force:true});fs.mkdirSync('./coverage',{recursive:true})\"",
-    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-coverage-exclude=\"__tests__/**\" ./__tests__/*.js"
+    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-coverage-exclude=\"__tests__/**\" ./__tests__/*.spec.js"
   },
   "files": [
     "lib"
@@ -33,11 +33,13 @@
     "email": "alex@localnerve.com",
     "url": "https://www.localnerve.com"
   },
-  "maintainers": [{
-    "name": "Alex Grant",
-    "email": "alex@localnerve.com",
-    "url": "https://www.localnerve.com"
-  }],
+  "maintainers": [
+    {
+      "name": "Alex Grant",
+      "email": "alex@localnerve.com",
+      "url": "https://www.localnerve.com"
+    }
+  ],
   "license": "BSD-3-Clause",
   "bugs": {
     "url": "https://github.com/localnerve/web-component-build/issues"
@@ -47,13 +49,14 @@
     "cheerio": "^1.2.0",
     "clean-css": "^5.3.3",
     "html-minifier-terser": "^7.2.0",
-    "terser": "^5.51.0"
+    "terser": "^5.51.2"
   },
   "devDependencies": {
-    "eslint": "^10.9.1",
     "@eslint/js": "^10.0.1",
+    "eslint": "^10.9.1",
     "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.11.0",
+    "globals": "^17.12.0",
+    "jsdom": "^30.0.1",
     "tempy": "^3.2.0"
   },
   "overrides": {