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

package/README.md

@@ -11,6 +11,7 @@ The parts are processed and written to an output directory, then exposed to a ca
 
   * [Why This Exists](#why-this-exists)
   * [Processing Possibilities](#processing-map)
+  * [Trusted Types Helpers](#trusted-types-helpers)
   * [Usage](#usage)
   * [API](#api)
   * [Options](#options-object-optional)
@@ -42,6 +43,40 @@ The following is a table of _some_ of the possible input, processing, and output
 
 > By default, html minification minifies any css found therein.
 
+## Trusted Types Helpers
+
+In addition to `build`, this package exports a small set of browser runtime helpers so that web components can be authored to work **with** and **without** [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types) enforcement (CSP `require-trusted-types-for 'script'`).
+
+```
+export { escapeHtml, getTrustedPolicy, trustedHtml }
+```
+
+The idea: a component registers **its own named policy** for the static, author-controlled markup it injects into sinks (`innerHTML`, etc.), escapes any user-influenced values before composing them, and falls back to plain-string passthrough in browsers (or builds) that do not enforce Trusted Types. Import these helpers directly into your component source — they are small, dependency-free, and get tree-shaken/inlined into the final bundle at build time (a consuming component does **not** need a runtime dependency on this package).
+
+### escapeHtml(input)
+Applies the industry-standard 6-character escape — `& < > " ' \`` → `&amp; &lt; &gt; &quot; &#x27; &#x60;` — for safe interpolation into HTML markup. Escaping quotes and the backtick (not just `&lt;/&gt;`) is what makes the result safe to reuse inside an **attribute value**, not only element content (matches `he.escape`). `null`/`undefined` yield `''`. Use it for any user-influenced value before composing it into markup.
+```js
+import { escapeHtml } from '@localnerve/web-component-build';
+const html = `<li>${escapeHtml(key)}: ${escapeHtml(value)}</li>`;
+// safe to interpolate into text OR a quoted attribute value
+```
+
+### getTrustedPolicy(name, hooks)
+Gets (creating once) a named Trusted Type policy. A name may only be created once without the CSP `allow-duplicates` keyword, so repeated calls reuse the instance. Returns `null` when Trusted Types is unavailable (passthrough mode). The default hooks are pass-through `createHTML`/`createScriptURL`, appropriate for author-controlled content that has already been escaped where needed.
+```js
+import { getTrustedPolicy } from '@localnerve/web-component-build';
+const policy = getTrustedPolicy('my-component'); // null if TT unavailable
+```
+
+### trustedHtml(policyName, html)
+Converts author-controlled (or pre-escaped) markup into a value safe to pass to an HTML injection sink under Trusted Types enforcement. Returns a `TrustedHTML` when enforced, otherwise the input string unchanged (passthrough for dev builds / browsers without Trusted Types).
+```js
+import { trustedHtml } from '@localnerve/web-component-build';
+shadowRoot.innerHTML = trustedHtml('my-component', '<div>…static template…</div>');
+```
+
+> The policy name must be allowlisted in the site's CSP `trusted-types` directive, e.g. `trusted-types default my-component;`. A build step can compute that allowlist from your sources — see [`@localnerve/trusted-types-rules`](https://github.com/localnerve/trusted-types-rules#readme). See [editable-object](https://github.com/localnerve/editable-object#trusted-types) for a complete, real-world example of a component built on these helpers.
+
 ## Usage
 
 ```javascript

package/index.js

@@ -7,4 +7,4 @@
  * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
  */
 export { build, build as default } from './lib/index.js';
-export * as browser from './lib/browser/index.js';
+export { escapeHtml, getTrustedPolicy, trustedHtml } from './lib/browser/index.js';

package/lib/browser/trusted-types.js

@@ -27,7 +27,12 @@ const policies = new Map();
 
 /**
  * Escape a value for safe interpolation into HTML markup (text or attribute).
- * 
+ *
+ * Applies the industry-standard escape of all six characters that can break
+ * out of a text or attribute context: & < > " ' and backtick. Escaping quotes
+ * and the backtick (not just &lt;/&gt;) is what makes the result safe to reuse
+ * inside an attribute value, not only element content.
+ *
  * @param {Any} input - The value to escape
  * @returns {String} The escaped string. null/undefined yield ''.
  */
@@ -38,7 +43,8 @@ export function escapeHtml (input) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
+    .replace(/'/g, '&#x27;')
+    .replace(/`/g, '&#x60;');
 }
 
 /**

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "@localnerve/web-component-build",
-  "version": "3.4.0-rc.2",
+  "version": "3.4.0-rc.4",
   "description": "A library to help build web components",
   "main": "index.js",
   "type": "module",
   "exports": {
-    "import": "./index.js",
-    "default": "./index.js"
+    ".": {
+      "browser": "./lib/browser/index.js",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./browser": {
+      "import": "./lib/browser/index.js",
+      "default": "./lib/browser/index.js"
+    }
   },
+  "browser": "./lib/browser/index.js",
   "scripts": {
     "lint": "eslint .",
     "pretest": "node -e \"const fs=require('fs');fs.rmSync('./coverage',{recursive:true,force:true});fs.mkdirSync('./coverage',{recursive:true})\"",