@barefootjs/shared 0.18.4 → 0.18.5

package/dist/html-entities.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HTML character-reference decoding and escaping for STATIC template
+ * content.
+ *
+ * JSX decodes character references at parse time: `<span>Fish &amp;
+ * Chips</span>` means the TEXT `Fish & Chips`, and `&copy;` means `©`
+ * (Babel/esbuild/TypeScript's JSX emit all decode). Phase 1
+ * (`jsx-to-ir`) applies `decodeEntities` once so `IRText.value` and
+ * static attribute values carry the DECODED text — the semantics —
+ * and every adapter re-escapes for its own emission context
+ * (`escapeHtml` for HTML template output; the Hono adapter
+ * re-encodes for JSX source). An adapter that emitted the raw entity
+ * text passed `&copy;` through as bytes while the reference decoded it
+ * (the `html-entity-text` divergence), and one that skipped
+ * re-escaping emitted a parse-corrupting `<`.
+ *
+ * The named table is the curated set below, not the full HTML5 list
+ * (~2,200 names): an unknown name (`&foo;`) is left as raw text, so
+ * BOTH the reference adapter and the template adapters receive the
+ * same undecoded string from the IR and stay byte-identical — the
+ * degradation is consistent, exactly how a browser treats an unknown
+ * reference. Numeric references (`&#169;` / `&#xA9;`) decode fully.
+ */
+/**
+ * Decode HTML character references in JSX literal text / static
+ * attribute values: numeric decimal (`&#169;`), numeric hex
+ * (`&#xA9;`), and the curated named set above. Anything unrecognized
+ * (unknown name, malformed numeric, bare `&`) is left verbatim.
+ */
+export declare function decodeEntities(text: string): string;
+/**
+ * Escape decoded static text for direct HTML emission: `&` `<` `>`
+ * `"` to their named forms. Used for BOTH text nodes and double-quoted
+ * attribute values — one set, no context-dependent under-escaping.
+ *
+ * `'` is deliberately NOT escaped: the reference (Hono JSX) escapes it
+ * as `&#39;`, but raw `'` is valid everywhere outside single-quoted
+ * attributes (which no adapter emits), and the conformance harness's
+ * `normalizeHTML` canonicalises the raw and entity forms to one
+ * spelling on both sides — so leaving apostrophes raw keeps every
+ * existing template byte-stable instead of rewriting all prose text.
+ */
+export declare function escapeHtml(text: string): string;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { BF_SCOPE, BF_SLOT, BF_HOST, BF_AT, BF_ROOT, BF_PROPS, BF_COND, BF_ITEM, BF_PORTAL_OWNER, BF_PORTAL_ID, BF_PORTAL_PLACEHOLDER, BF_PARENT_OWNED_PREFIX, BF_SCOPE_COMMENT_PREFIX, BF_LOOP_START, BF_LOOP_END, BF_LOOP_ITEM, loopItemMarker, loopStartMarker, loopEndMarker, BF_KEY, BF_KEY_PREFIX, BF_PLACEHOLDER, BF_ASYNC, BF_ASYNC_RESOLVE, BF_REGION, BF_PARENT_SCOPE_PLACEHOLDER, BF_SEAM_HYDRATE, BF_SEAM_HYDRATE_WITHIN, BF_SEAM_DISPOSE_WITHIN, BF_SEAM_PUSH_SEARCH, BF_SEAM_NAV_SEARCH, } from './markers.ts';
 export { classifyDOMProp, toHTMLAttrName, toHTMLAttrNameRuntime, isBooleanAttr, isEventProp, BOOLEAN_ATTRS, } from './dom-prop.ts';
 export type { DOMPropKind, DOMPropClassification } from './dom-prop.ts';
+export { decodeEntities, escapeHtml } from './html-entities.ts';
 export type { ProfilerEvent, ProfilerEventType, ProfilerSubscriberKind, } from './profiler-events.ts';

package/dist/index.js

@@ -264,6 +264,76 @@ function toHTMLAttrNameRuntime(key) {
 function isBooleanAttr(name) {
   return BOOLEAN_ATTRS.has(name.toLowerCase());
 }
+// src/html-entities.ts
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  copy: "©",
+  reg: "®",
+  trade: "™",
+  deg: "°",
+  plusmn: "±",
+  times: "×",
+  divide: "÷",
+  middot: "·",
+  bull: "•",
+  hellip: "…",
+  ndash: "–",
+  mdash: "—",
+  lsquo: "‘",
+  rsquo: "’",
+  ldquo: "“",
+  rdquo: "”",
+  laquo: "«",
+  raquo: "»",
+  sect: "§",
+  para: "¶",
+  dagger: "†",
+  Dagger: "‡",
+  euro: "€",
+  pound: "£",
+  yen: "¥",
+  cent: "¢",
+  sup1: "¹",
+  sup2: "²",
+  sup3: "³",
+  frac12: "½",
+  frac14: "¼",
+  frac34: "¾",
+  larr: "←",
+  uarr: "↑",
+  rarr: "→",
+  darr: "↓",
+  harr: "↔",
+  minus: "−",
+  infin: "∞",
+  ne: "≠",
+  le: "≤",
+  ge: "≥"
+};
+function decodeEntities(text) {
+  return text.replace(/&(#[xX]?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, body) => {
+    if (body[0] === "#") {
+      const isHex = body[1] === "x" || body[1] === "X";
+      const digits = body.slice(isHex ? 2 : 1);
+      if (!isHex && !/^[0-9]+$/.test(digits))
+        return match;
+      const code = parseInt(digits, isHex ? 16 : 10);
+      if (!Number.isFinite(code) || code > 1114111 || code >= 55296 && code <= 57343) {
+        return match;
+      }
+      return String.fromCodePoint(code);
+    }
+    return NAMED_ENTITIES[body] ?? match;
+  });
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 export {
   toHTMLAttrNameRuntime,
   toHTMLAttrName,
@@ -272,6 +342,8 @@ export {
   loopEndMarker,
   isEventProp,
   isBooleanAttr,
+  escapeHtml,
+  decodeEntities,
   classifyDOMProp,
   BOOLEAN_ATTRS,
   BF_SLOT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/shared",
-  "version": "0.18.4",
+  "version": "0.18.5",
   "description": "Shared constants for BarefootJS compiler and runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/html-entities.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'bun:test'
+import { decodeEntities, escapeHtml } from '../html-entities'
+
+describe('decodeEntities', () => {
+  test('escaping-set names decode', () => {
+    expect(decodeEntities('Fish & Chips')).toBe('Fish & Chips')
+    expect(decodeEntities('a &lt; b &gt; c')).toBe('a < b > c')
+    expect(decodeEntities('&quot;x&quot; &apos;y&apos;')).toBe(`"x" 'y'`)
+  })
+
+  test('common typographic names decode', () => {
+    expect(decodeEntities('&copy; 2026')).toBe('© 2026')
+    expect(decodeEntities('1&nbsp;000')).toBe('1 000')
+    expect(decodeEntities('A&hellip;')).toBe('A…')
+    expect(decodeEntities('&euro;5 / &pound;4 / &yen;3')).toBe('€5 / £4 / ¥3')
+  })
+
+  test('numeric decimal and hex references decode', () => {
+    expect(decodeEntities('&#169;')).toBe('©')
+    expect(decodeEntities('&#xA9;')).toBe('©')
+    expect(decodeEntities('&#x1F600;')).toBe('😀')
+  })
+
+  test('unknown / malformed references stay verbatim', () => {
+    expect(decodeEntities('&unknownname;')).toBe('&unknownname;')
+    expect(decodeEntities('a & b')).toBe('a & b')
+    expect(decodeEntities('&amp')).toBe('&amp')
+    // Lone surrogate / out-of-range code points are refused, not
+    // replaced with garbage.
+    expect(decodeEntities('&#xD800;')).toBe('&#xD800;')
+    expect(decodeEntities('&#x110000;')).toBe('&#x110000;')
+  })
+
+  test('double-escaped input decodes exactly one level', () => {
+    expect(decodeEntities('&amp;copy;')).toBe('&copy;')
+  })
+})
+
+describe('escapeHtml', () => {
+  test('escapes & < > " and leaves the rest', () => {
+    expect(escapeHtml('Fish & Chips')).toBe('Fish &amp; Chips')
+    expect(escapeHtml('a < b > c')).toBe('a &lt; b &gt; c')
+    expect(escapeHtml('say "hi"')).toBe('say &quot;hi&quot;')
+    expect(escapeHtml("it's © fine")).toBe("it's © fine")
+  })
+
+  test('decode → escape round-trips the entity text', () => {
+    expect(escapeHtml(decodeEntities('Fish &amp; Chips'))).toBe('Fish &amp; Chips')
+    expect(escapeHtml(decodeEntities('a &lt; b'))).toBe('a &lt; b')
+    // Named references outside the escape set stay decoded — the
+    // literal character is the canonical emission (`©`, not `&copy;`).
+    expect(escapeHtml(decodeEntities('&copy; 2026'))).toBe('© 2026')
+  })
+})

package/src/html-entities.ts

@@ -0,0 +1,123 @@
+/**
+ * HTML character-reference decoding and escaping for STATIC template
+ * content.
+ *
+ * JSX decodes character references at parse time: `<span>Fish &amp;
+ * Chips</span>` means the TEXT `Fish & Chips`, and `&copy;` means `©`
+ * (Babel/esbuild/TypeScript's JSX emit all decode). Phase 1
+ * (`jsx-to-ir`) applies `decodeEntities` once so `IRText.value` and
+ * static attribute values carry the DECODED text — the semantics —
+ * and every adapter re-escapes for its own emission context
+ * (`escapeHtml` for HTML template output; the Hono adapter
+ * re-encodes for JSX source). An adapter that emitted the raw entity
+ * text passed `&copy;` through as bytes while the reference decoded it
+ * (the `html-entity-text` divergence), and one that skipped
+ * re-escaping emitted a parse-corrupting `<`.
+ *
+ * The named table is the curated set below, not the full HTML5 list
+ * (~2,200 names): an unknown name (`&foo;`) is left as raw text, so
+ * BOTH the reference adapter and the template adapters receive the
+ * same undecoded string from the IR and stay byte-identical — the
+ * degradation is consistent, exactly how a browser treats an unknown
+ * reference. Numeric references (`&#169;` / `&#xA9;`) decode fully.
+ */
+
+/**
+ * Named character references JSX authors actually write in literal
+ * text. `amp`/`lt`/`gt`/`quot`/`apos` are the escaping set itself;
+ * the rest are the common typographic/symbol names.
+ */
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  copy: '©',
+  reg: '®',
+  trade: '™',
+  deg: '°',
+  plusmn: '±',
+  times: '×',
+  divide: '÷',
+  middot: '·',
+  bull: '•',
+  hellip: '…',
+  ndash: '–',
+  mdash: '—',
+  lsquo: '‘',
+  rsquo: '’',
+  ldquo: '“',
+  rdquo: '”',
+  laquo: '«',
+  raquo: '»',
+  sect: '§',
+  para: '¶',
+  dagger: '†',
+  Dagger: '‡',
+  euro: '€',
+  pound: '£',
+  yen: '¥',
+  cent: '¢',
+  sup1: '¹',
+  sup2: '²',
+  sup3: '³',
+  frac12: '½',
+  frac14: '¼',
+  frac34: '¾',
+  larr: '←',
+  uarr: '↑',
+  rarr: '→',
+  darr: '↓',
+  harr: '↔',
+  minus: '−',
+  infin: '∞',
+  ne: '≠',
+  le: '≤',
+  ge: '≥',
+}
+
+/**
+ * Decode HTML character references in JSX literal text / static
+ * attribute values: numeric decimal (`&#169;`), numeric hex
+ * (`&#xA9;`), and the curated named set above. Anything unrecognized
+ * (unknown name, malformed numeric, bare `&`) is left verbatim.
+ */
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#[xX]?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (match, body: string) => {
+    if (body[0] === '#') {
+      const isHex = body[1] === 'x' || body[1] === 'X'
+      const digits = body.slice(isHex ? 2 : 1)
+      if (!isHex && !/^[0-9]+$/.test(digits)) return match
+      const code = parseInt(digits, isHex ? 16 : 10)
+      // Reject out-of-range / lone-surrogate code points rather than
+      // producing replacement garbage — leave the reference raw.
+      if (!Number.isFinite(code) || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) {
+        return match
+      }
+      return String.fromCodePoint(code)
+    }
+    return NAMED_ENTITIES[body] ?? match
+  })
+}
+
+/**
+ * Escape decoded static text for direct HTML emission: `&` `<` `>`
+ * `"` to their named forms. Used for BOTH text nodes and double-quoted
+ * attribute values — one set, no context-dependent under-escaping.
+ *
+ * `'` is deliberately NOT escaped: the reference (Hono JSX) escapes it
+ * as `&#39;`, but raw `'` is valid everywhere outside single-quoted
+ * attributes (which no adapter emits), and the conformance harness's
+ * `normalizeHTML` canonicalises the raw and entity forms to one
+ * spelling on both sides — so leaving apostrophes raw keeps every
+ * existing template byte-stable instead of rewriting all prose text.
+ */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/index.ts

@@ -41,6 +41,7 @@ export {
   BOOLEAN_ATTRS,
 } from './dom-prop.ts'
 export type { DOMPropKind, DOMPropClassification } from './dom-prop.ts'
+export { decodeEntities, escapeHtml } from './html-entities.ts'
 
 export type {
   ProfilerEvent,