fragtml 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Bret Comnes
+
+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/README.md

@@ -0,0 +1,387 @@
+# fragtml
+
+[![latest version](https://img.shields.io/npm/v/fragtml.svg)](https://www.npmjs.com/package/fragtml)
+[![Actions Status](https://github.com/bcomnes/fragtml/workflows/tests/badge.svg)](https://github.com/bcomnes/fragtml/actions)
+
+[![downloads](https://img.shields.io/npm/dm/fragtml.svg)](https://npmtrends.com/fragtml)
+![Types in JS](https://img.shields.io/badge/types_in_js-yes-brightgreen)
+[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-7fffff?style=flat&labelColor=ff80ff)](https://github.com/neostandard/neostandard)
+[![Socket Badge](https://socket.dev/api/badge/npm/package/fragtml)](https://socket.dev/npm/package/fragtml)
+
+A safe-by-default, string-generating HTML tagged template library with inline fragment support for server-rendered hypermedia apps.
+
+`fragtml` is inspired by `common-tags` HTML formatting behavior and by htmx-style [template fragments](https://htmx.org/essays/template-fragments/). It lets you keep a full template and its partial update fragments together in one JavaScript template function.
+
+## Install
+
+```sh
+npm install fragtml
+```
+
+## Basic usage
+
+```js
+import html, { render } from 'fragtml'
+
+const name = '<Bret>'
+const result = html`<p>Hello ${name}</p>`
+
+render(result)
+// '<p>Hello &lt;Bret&gt;</p>'
+```
+
+`html` returns an intermediate result object, not a primitive string. Use `render()` at route-handler boundaries:
+
+```js
+return render(html`<h1>${title}</h1>`)
+```
+
+The returned object also supports direct string coercion:
+
+```js
+const result = html`<p>${'Hello'}</p>`
+
+String(result)
+result.toString()
+`${result}`
+```
+
+## Safe interpolation
+
+Static template HTML is left as-is. Ordinary substitutions are escaped:
+
+```js
+render(html`<p>${'<script>alert(1)</script>'}</p>`)
+// '<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>'
+```
+
+The following non-printing values are omitted:
+
+- `null`
+- `undefined`
+- booleans
+- `NaN`
+
+```js
+render(html`<p>${null}${false}${Number.NaN}${0}</p>`)
+// '<p>0</p>'
+```
+
+## Trusted raw HTML
+
+Use `raw()` for trusted HTML that should not be escaped:
+
+```js
+import html, { raw, render } from 'fragtml'
+
+render(html`<p>${raw('<strong>trusted</strong>')}</p>`)
+// '<p><strong>trusted</strong></p>'
+```
+
+The tag also exposes the same helper as `.raw`:
+
+```js
+html.raw === raw
+
+render(html`<p>${html.raw('<em>trusted</em>')}</p>`)
+// '<p><em>trusted</em></p>'
+```
+
+Only pass trusted HTML to `raw()`. User input should be interpolated normally so it is escaped.
+
+There is no public `unsafeHtml` tag in v1. Prefer local, explicit trust boundaries with `raw()`.
+
+## Composition
+
+Nested `html` results are treated as trusted `fragtml` output, while their own substitutions remain escaped:
+
+```js
+const button = html`<button>${'<Archive>'}</button>`
+
+render(html`
+  <div hx-target="this">
+    ${button}
+  </div>
+`)
+// '<div hx-target="this">\n  <button>&lt;Archive&gt;</button>\n</div>'
+```
+
+Arrays are inlined with indentation-aware formatting:
+
+```js
+const items = ['one', 'two'].map((item) => html`<li>${item}</li>`)
+
+render(html`
+  <ul>
+    ${items}
+  </ul>
+`)
+// '<ul>\n  <li>one</li>\n  <li>two</li>\n</ul>'
+```
+
+String substitutions containing newlines are split and aligned to the surrounding indentation.
+
+## Boolean attributes
+
+Use `?name=${condition}` to toggle boolean attributes. When the value is truthy, `fragtml` renders the bare attribute. When the value is falsey, it omits the attribute.
+
+```js
+render(html`<button ?disabled=${loading}>Save</button>`)
+```
+
+When `loading` is truthy:
+
+```html
+<button disabled>Save</button>
+```
+
+When `loading` is falsey:
+
+```html
+<button>Save</button>
+```
+
+This syntax is useful for native HTML boolean attributes such as `disabled`, `checked`, `selected`, `readonly`, `required`, `multiple`, `autofocus`, `hidden`, and `open`.
+
+Only the unquoted form is supported:
+
+```js
+html`<button ?disabled=${loading}>Save</button>`
+```
+
+Quoted forms are intentionally unsupported in v1:
+
+```js
+html`<button ?disabled="${loading}">Save</button>`
+html`<button ?disabled='${loading}'>Save</button>`
+```
+
+## Bound tags
+
+`html(options)` returns a configured tag. This is useful for fragment rendering and for editor syntax highlighting, because many editors highlight tagged templates better when the tag is a simple identifier.
+
+```js
+import { createHtml, render } from 'fragtml'
+
+export function view ({ fragmentId }) {
+  const html = createHtml({ fragmentId })
+
+  return render(html`
+    <main>...</main>
+  `)
+}
+```
+
+`createHtml` is an alias of `html`:
+
+```js
+import html, { createHtml } from 'fragtml'
+
+createHtml === html
+```
+
+You can also use the short fragment-target form:
+
+```js
+const html = createHtml('archive-ui')
+```
+
+which is equivalent to:
+
+```js
+const html = createHtml({ fragmentId: 'archive-ui' })
+```
+
+## Fragments
+
+Fragments mark a named range inside a larger template. Rendering without `fragmentId` returns the whole template. Rendering with `fragmentId` returns only that fragment.
+
+This mirrors the htmx article’s idea:
+
+```txt
+#fragment archive-ui
+  ...
+#end
+```
+
+In `fragtml`, use boundary tokens:
+
+```js
+${html.fragment.start('archive-ui')}
+...
+${html.fragment.end}
+```
+
+### Example
+
+```js
+import { createHtml, render } from 'fragtml'
+
+export function contactDetail ({ contact, fragmentId }) {
+  const html = createHtml({ fragmentId })
+
+  return render(html`
+    <html>
+      <body>
+        <div hx-target="this">
+          ${html.fragment.start('archive-ui')}
+          ${contact.archived
+            ? html`<button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>`
+            : html`<button hx-delete="/contacts/${contact.id}">Archive</button>`}
+          ${html.fragment.end}
+        </div>
+
+        <h3>Contact</h3>
+        <p>${contact.email}</p>
+      </body>
+    </html>
+  `)
+}
+```
+
+Render the whole page:
+
+```js
+contactDetail({ contact })
+```
+
+Render only the archive button fragment:
+
+```js
+contactDetail({ contact, fragmentId: 'archive-ui' })
+```
+
+Fragment boundary tokens are not included in either output.
+
+### Fragment rules
+
+- Fragment IDs must be unique within a rendered template.
+- Missing fragments throw `FragmentNotFoundError`.
+- Duplicate fragment IDs throw `DuplicateFragmentError`.
+- `html.fragment.end` without a matching start throws `FragmentBoundaryError`.
+- An unclosed `html.fragment.start(id)` throws `FragmentBoundaryError`.
+
+## Nested fragments
+
+Nested fragments are supported with stack semantics. This is useful when a larger region can be re-rendered as a whole, but a smaller region inside it is also a valid htmx update target.
+
+```js
+import { createHtml, render } from 'fragtml'
+
+export function page ({ fragmentId }) {
+  const html = createHtml({ fragmentId })
+
+  return render(html`
+    ${html.fragment.start('outer')}
+    <section>
+      <h2>Outer</h2>
+
+      ${html.fragment.start('inner')}
+      <button>Inner update target</button>
+      ${html.fragment.end}
+    </section>
+    ${html.fragment.end}
+  `)
+}
+```
+
+Rendering `outer` includes the nested `inner` content:
+
+```js
+page({ fragmentId: 'outer' })
+// '<section>\n  <h2>Outer</h2>\n\n  <button>Inner update target</button>\n</section>'
+```
+
+Rendering `inner` returns only the inner fragment:
+
+```js
+page({ fragmentId: 'inner' })
+// '<button>Inner update target</button>'
+```
+
+Use nested fragments sparingly. Prefer flat fragments unless you actually need both a parent region and a child region as independently renderable update targets.
+
+## API
+
+### `html`
+
+Safe-by-default template tag.
+
+```js
+html`<p>${value}</p>`
+```
+
+Also acts as a factory for bound tags:
+
+```js
+const h = html({ fragmentId: 'name' })
+const h = html('name')
+```
+
+### `createHtml`
+
+Alias of `html`, intended for local tag naming:
+
+```js
+import { createHtml } from 'fragtml'
+
+const html = createHtml({ fragmentId })
+```
+
+### `render(value)`
+
+Converts a `fragtml` result to a primitive string.
+
+```js
+render(html`<p>${value}</p>`)
+```
+
+### `raw(value)` / `html.raw(value)`
+
+Marks trusted HTML so it is inserted without escaping.
+
+```js
+html`<p>${raw('<strong>trusted</strong>')}</p>`
+```
+
+### Boolean attributes
+
+Use unquoted `?name=${condition}` syntax to toggle a boolean attribute.
+
+```js
+html`<button ?disabled=${loading}>Save</button>`
+```
+
+### `html.fragment.start(id)`
+
+Starts a named fragment range.
+
+```js
+${html.fragment.start('archive-ui')}
+```
+
+### `html.fragment.end`
+
+Ends the most recently opened fragment range.
+
+```js
+${html.fragment.end}
+```
+
+### Error classes
+
+```js
+import {
+  DuplicateFragmentError,
+  FragmentBoundaryError,
+  FragmentNotFoundError
+} from 'fragtml'
+```
+
+## TypeScript
+
+`fragtml` is written in typed JavaScript and ships generated declaration files.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,8 @@
+export default html;
+import { html } from './lib/html.js';
+export const createHtml: import("./lib/create-tag.js").HtmlTag;
+import { raw } from './lib/raw.js';
+import { render } from './lib/render.js';
+export { html, raw, render };
+export { DuplicateFragmentError, FragmentBoundaryError, FragmentNotFoundError } from "./lib/render.js";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";qBAAqB,eAAe;AAIpC,+DAAuB;oBAHH,cAAc;uBACX,iBAAiB"}

package/index.js

@@ -0,0 +1,9 @@
+import { html } from './lib/html.js'
+import { raw } from './lib/raw.js'
+import { render } from './lib/render.js'
+
+const createHtml = html
+
+export default html
+export { createHtml, html, raw, render }
+export { DuplicateFragmentError, FragmentBoundaryError, FragmentNotFoundError } from './lib/render.js'

package/lib/create-tag.d.ts

@@ -0,0 +1,15 @@
+export const html: HtmlTag;
+export type RenderOptions = {
+    fragmentId?: string | undefined;
+};
+export type CompiledTemplate = {
+    strings: readonly string[];
+};
+export type HtmlTag = ((strings: TemplateStringsArray | readonly string[], ...substitutions: unknown[]) => HtmlResult) & ((options?: RenderOptions | string) => HtmlTag) & {
+    fragment: FragmentHelpers;
+    raw: (value: unknown) => RawHtml;
+};
+import { HtmlResult } from './html-result.js';
+import type { FragmentHelpers } from './fragment.js';
+import type { RawHtml } from './raw.js';
+//# sourceMappingURL=create-tag.d.ts.map

package/lib/create-tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tag.d.ts","sourceRoot":"","sources":["create-tag.js"],"names":[],"mappings":"AA+EA,mBADW,OAAO,CACoB;;iBArExB,MAAM,GAAG,SAAS;;;aAKlB,SAAS,MAAM,EAAE;;sBAmElB,CAAC,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE,OAAO,EAAE,KAAK,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,KAAK,OAAO,CAAC,GAAG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE;2BA9EtM,kBAAkB;qCAJR,eAAe;6BACvB,UAAU"}

package/lib/create-tag.js

@@ -0,0 +1,84 @@
+/** @import { FragmentHelpers } from './fragment.js' */
+/** @import { RawHtml } from './raw.js' */
+
+import { createFragmentHelpers } from './fragment.js'
+import { HtmlResult } from './html-result.js'
+import { raw } from './raw.js'
+import { renderResult } from './render.js'
+
+/**
+ * @typedef {object} RenderOptions
+ * @property {string | undefined} [fragmentId]
+ */
+
+/**
+ * @typedef {object} CompiledTemplate
+ * @property {readonly string[]} strings
+ */
+
+/** @type {WeakMap<TemplateStringsArray | readonly string[], CompiledTemplate>} */
+const templateCache = new WeakMap()
+const fragment = createFragmentHelpers()
+
+/**
+ * @param {TemplateStringsArray | readonly string[]} strings
+ * @returns {CompiledTemplate}
+ */
+function compileTemplate (strings) {
+  const cached = templateCache.get(strings)
+
+  if (cached) return cached
+
+  const compiled = { strings: Array.from(strings) }
+  templateCache.set(strings, compiled)
+  return compiled
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is TemplateStringsArray | readonly string[]}
+ */
+function isTemplateStrings (value) {
+  return Array.isArray(value)
+}
+
+/**
+ * @param {RenderOptions | string | undefined} options
+ * @returns {RenderOptions}
+ */
+function normalizeOptions (options) {
+  if (typeof options === 'string') return { fragmentId: options }
+  return options ? { ...options } : {}
+}
+
+/**
+ * @param {RenderOptions} options
+ * @returns {HtmlTag}
+ */
+function createBoundTag (options) {
+  // eslint-disable-next-line @stylistic/no-extra-parens
+  const tag = /** @type {HtmlTag} */ (function tag (strings, ...substitutions) {
+    if (!isTemplateStrings(strings)) {
+      return createBoundTag(normalizeOptions(/** @type {RenderOptions | string | undefined} */ strings))
+    }
+
+    return new HtmlResult(
+      compileTemplate(strings),
+      substitutions,
+      options,
+      renderResult
+    )
+  })
+
+  tag.fragment = fragment
+  tag.raw = raw
+
+  return tag
+}
+
+/** @type {HtmlTag} */
+export const html = createBoundTag({})
+
+/**
+ * @typedef {((strings: TemplateStringsArray | readonly string[], ...substitutions: unknown[]) => HtmlResult) & ((options?: RenderOptions | string) => HtmlTag) & { fragment: FragmentHelpers, raw: (value: unknown) => RawHtml }} HtmlTag
+ */

package/lib/escape-html.d.ts

@@ -0,0 +1,2 @@
+export function escapeHtml(value: unknown): string;
+//# sourceMappingURL=escape-html.d.ts.map

package/lib/escape-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-html.d.ts","sourceRoot":"","sources":["escape-html.js"],"names":[],"mappings":"AAQA,kCAHW,OAAO,GACL,MAAM,CAclB"}

package/lib/escape-html.js

@@ -0,0 +1,21 @@
+const htmlEscapes = /[&<>"'`]/g
+
+/**
+ * Escapes text for safe HTML interpolation.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml (value) {
+  return String(value).replace(htmlEscapes, (character) => {
+    switch (character) {
+      case '&': return '&amp;'
+      case '<': return '&lt;'
+      case '>': return '&gt;'
+      case '"': return '&quot;'
+      case "'": return '&#x27;'
+      case '`': return '&#x60;'
+      default: return character
+    }
+  })
+}

package/lib/fragment.d.ts

@@ -0,0 +1,20 @@
+export function createFragmentHelpers(): FragmentHelpers;
+export function isFragmentBoundary(value: unknown): value is FragmentBoundary;
+export const fragmentBoundarySymbol: unique symbol;
+export type FragmentStartBoundary = {
+    [fragmentBoundarySymbol]: true;
+    kind: "start";
+    id: string;
+};
+export type FragmentEndBoundary = {
+    [fragmentBoundarySymbol]: true;
+    kind: "end";
+};
+export type FragmentBoundary = FragmentStartBoundary | FragmentEndBoundary;
+export type FragmentHelpers = {
+    start: typeof start;
+    end: FragmentEndBoundary;
+};
+declare function start(id: string): FragmentStartBoundary;
+export {};
+//# sourceMappingURL=fragment.d.ts.map

package/lib/fragment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment.d.ts","sourceRoot":"","sources":["fragment.js"],"names":[],"mappings":"AAiCA,yCAFa,eAAe,CAI3B;AAMD,0CAHW,OAAO,GACL,KAAK,IAAI,gBAAgB,CAQrC;AAxCD,mDAAwE;oCAN3D;IAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;kCAC7D;IAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE;+BAC/C,qBAAqB,GAAG,mBAAmB;8BAC3C;IAAE,KAAK,EAAE,OAAO,KAAK,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE;AAc9D,2BAHW,MAAM,GACJ,qBAAqB,CAYjC"}

package/lib/fragment.js

@@ -0,0 +1,48 @@
+/**
+ * @typedef {{ [fragmentBoundarySymbol]: true, kind: 'start', id: string }} FragmentStartBoundary
+ * @typedef {{ [fragmentBoundarySymbol]: true, kind: 'end' }} FragmentEndBoundary
+ * @typedef {FragmentStartBoundary | FragmentEndBoundary} FragmentBoundary
+ * @typedef {{ start: typeof start, end: FragmentEndBoundary }} FragmentHelpers
+ */
+
+export const fragmentBoundarySymbol = Symbol('fragtml.fragmentBoundary')
+
+const end = Object.freeze(/** @type {FragmentEndBoundary} */ ({
+  [fragmentBoundarySymbol]: true,
+  kind: 'end'
+}))
+
+/**
+ * @param {string} id
+ * @returns {FragmentStartBoundary}
+ */
+function start (id) {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new TypeError('fragment.start(id) requires a non-empty string id')
+  }
+
+  return {
+    [fragmentBoundarySymbol]: true,
+    kind: 'start',
+    id
+  }
+}
+
+/**
+ * @returns {FragmentHelpers}
+ */
+export function createFragmentHelpers () {
+  return Object.freeze({ start, end })
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is FragmentBoundary}
+ */
+export function isFragmentBoundary (value) {
+  return !!(
+    value &&
+    typeof value === 'object' &&
+    /** @type {Record<symbol, unknown>} */(value)[fragmentBoundarySymbol] === true
+  )
+}

package/lib/html-result.d.ts

@@ -0,0 +1,16 @@
+export function isHtmlResult(value: unknown): value is HtmlResult;
+export const htmlResultSymbol: unique symbol;
+export class HtmlResult {
+    constructor(compiled: CompiledTemplate, substitutions: unknown[], options: RenderOptions, render: (result: HtmlResult) => string);
+    compiled: CompiledTemplate;
+    substitutions: unknown[];
+    options: RenderOptions;
+    render: (result: HtmlResult) => string;
+    toString(): string;
+    valueOf(): string;
+    [Symbol.toPrimitive](): string;
+    [htmlResultSymbol]: boolean;
+}
+import type { CompiledTemplate } from './create-tag.js';
+import type { RenderOptions } from './create-tag.js';
+//# sourceMappingURL=html-result.d.ts.map

package/lib/html-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-result.d.ts","sourceRoot":"","sources":["html-result.js"],"names":[],"mappings":"AAoCA,oCAHW,OAAO,GACL,KAAK,IAAI,UAAU,CAQ/B;AAxCD,6CAA4D;AAE5D;IAOE,sBALW,gBAAgB,iBAChB,OAAO,EAAE,WACT,aAAa,UACb,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,EAQxC;IAJC,2BAAwB;IACxB,yBAAkC;IAClC,uBAAsB;IACtB,iBAPkB,UAAU,KAAK,MAAM,CAOnB;IAGtB,mBAEC;IAED,kBAEC;IAED,+BAEC;IAjBC,4BAA6B;CAkBhC;sCA9BoD,iBAAiB;mCAAjB,iBAAiB"}

package/lib/html-result.js

@@ -0,0 +1,43 @@
+/** @import { CompiledTemplate, RenderOptions } from './create-tag.js' */
+
+export const htmlResultSymbol = Symbol('fragtml.htmlResult')
+
+export class HtmlResult {
+  /**
+   * @param {CompiledTemplate} compiled
+   * @param {unknown[]} substitutions
+   * @param {RenderOptions} options
+   * @param {(result: HtmlResult) => string} render
+   */
+  constructor (compiled, substitutions, options, render) {
+    this[htmlResultSymbol] = true
+    this.compiled = compiled
+    this.substitutions = substitutions
+    this.options = options
+    this.render = render
+  }
+
+  toString () {
+    return this.render(this)
+  }
+
+  valueOf () {
+    return this.render(this)
+  }
+
+  [Symbol.toPrimitive] () {
+    return this.render(this)
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is HtmlResult}
+ */
+export function isHtmlResult (value) {
+  return value instanceof HtmlResult || !!(
+    value &&
+    typeof value === 'object' &&
+    /** @type {Record<symbol, unknown>} */(value)[htmlResultSymbol] === true
+  )
+}

package/lib/html.d.ts

@@ -0,0 +1,2 @@
+export { html } from "./create-tag.js";
+//# sourceMappingURL=html.d.ts.map

package/lib/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["html.js"],"names":[],"mappings":""}

package/lib/html.js

@@ -0,0 +1 @@
+export { html } from './create-tag.js'

package/lib/inline-array.d.ts

@@ -0,0 +1,2 @@
+export function inlineArray(resultSoFar: string, parts: string[]): string;
+//# sourceMappingURL=inline-array.d.ts.map

package/lib/inline-array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-array.d.ts","sourceRoot":"","sources":["inline-array.js"],"names":[],"mappings":"AAOA,yCAJW,MAAM,SACN,MAAM,EAAE,GACN,MAAM,CAiBlB"}

package/lib/inline-array.js

@@ -0,0 +1,36 @@
+import { stripLastNewLine } from './utils.js'
+
+/**
+ * @param {string} resultSoFar
+ * @param {string[]} parts
+ * @returns {string}
+ */
+export function inlineArray (resultSoFar, parts) {
+  const indentation = resultSoFar.match(/(?:\n)([^\S\n]+)$/)
+
+  return parts.reduce((result, part, index) => {
+    const isFirstPart = index === 0
+    const strippedPart = stripLastNewLine(part)
+
+    return ''.concat(
+      result,
+      isFirstPart ? '' : indentation ? '\n' : ' ',
+      indentation
+        ? prefixLines(indentation[1] ?? '', strippedPart, isFirstPart)
+        : strippedPart
+    )
+  }, '')
+}
+
+/**
+ * @param {string} prefix
+ * @param {string} value
+ * @param {boolean} skipFirst
+ * @returns {string}
+ */
+function prefixLines (prefix, value, skipFirst) {
+  return value
+    .split('\n')
+    .map((line, index) => skipFirst && index === 0 ? line : `${prefix}${line}`)
+    .join('\n')
+}

package/lib/raw.d.ts

@@ -0,0 +1,12 @@
+export function raw(value: unknown): RawHtml;
+export function isRawHtml(value: unknown): value is RawHtml;
+export const rawHtmlSymbol: unique symbol;
+export class RawHtml {
+    constructor(value: unknown);
+    value: unknown;
+    toString(): string;
+    valueOf(): string;
+    [Symbol.toPrimitive](): string;
+    [rawHtmlSymbol]: boolean;
+}
+//# sourceMappingURL=raw.d.ts.map

package/lib/raw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["raw.js"],"names":[],"mappings":"AA8BA,2BAHW,OAAO,GACL,OAAO,CAInB;AAMD,iCAHW,OAAO,GACL,KAAK,IAAI,OAAO,CAQ5B;AA5CD,0CAAsD;AAEtD;IAIE,mBAFW,OAAO,EAKjB;IADC,eAAkB;IAGpB,mBAEC;IAED,kBAEC;IAED,+BAEC;IAdC,yBAA0B;CAe7B"}

package/lib/raw.js

@@ -0,0 +1,45 @@
+export const rawHtmlSymbol = Symbol('fragtml.rawHtml')
+
+export class RawHtml {
+  /**
+   * @param {unknown} value
+   */
+  constructor (value) {
+    this[rawHtmlSymbol] = true
+    this.value = value
+  }
+
+  toString () {
+    return String(this.value)
+  }
+
+  valueOf () {
+    return String(this.value)
+  }
+
+  [Symbol.toPrimitive] () {
+    return String(this.value)
+  }
+}
+
+/**
+ * Marks a value as trusted HTML so it is inserted without escaping.
+ *
+ * @param {unknown} value
+ * @returns {RawHtml}
+ */
+export function raw (value) {
+  return new RawHtml(value)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is RawHtml}
+ */
+export function isRawHtml (value) {
+  return value instanceof RawHtml || !!(
+    value &&
+    typeof value === 'object' &&
+    /** @type {Record<symbol, unknown>} */(value)[rawHtmlSymbol] === true
+  )
+}

package/lib/render.d.ts

@@ -0,0 +1,15 @@
+export function render(value: unknown): string;
+export function renderResult(result: HtmlResult): string;
+export class FragmentNotFoundError extends Error {
+    constructor(id: string);
+    fragmentId: string;
+}
+export class DuplicateFragmentError extends Error {
+    constructor(id: string);
+    fragmentId: string;
+}
+export class FragmentBoundaryError extends Error {
+    constructor(message: string);
+}
+import type { HtmlResult } from './html-result.js';
+//# sourceMappingURL=render.d.ts.map

package/lib/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["render.js"],"names":[],"mappings":"AAoJA,8BAHW,OAAO,GACL,MAAM,CAQlB;AAMD,qCAHW,UAAU,GACR,MAAM,CAMlB;AAxJD;IAIE,gBAFW,MAAM,EAMhB;IADC,mBAAoB;CAEvB;AAED;IAIE,gBAFW,MAAM,EAMhB;IADC,mBAAoB;CAEvB;AAED;IAIE,qBAFW,MAAM,EAKhB;CACF;gCA1C+B,kBAAkB"}

package/lib/render.js

@@ -0,0 +1,278 @@
+/** @import { HtmlResult } from './html-result.js' */
+
+import { escapeHtml } from './escape-html.js'
+import { isFragmentBoundary } from './fragment.js'
+import { isHtmlResult } from './html-result.js'
+import { inlineArray } from './inline-array.js'
+import { isRawHtml } from './raw.js'
+import { stripIndent } from './strip-indent.js'
+import { isNonPrintingValue } from './utils.js'
+
+const booleanAttributeSuffix = /(^|\s)\?([A-Za-z_:][A-Za-z0-9_:.-]*)=$/
+
+export class FragmentNotFoundError extends Error {
+  /**
+   * @param {string} id
+   */
+  constructor (id) {
+    super(`Fragment not found: ${id}`)
+    this.name = 'FragmentNotFoundError'
+    this.fragmentId = id
+  }
+}
+
+export class DuplicateFragmentError extends Error {
+  /**
+   * @param {string} id
+   */
+  constructor (id) {
+    super(`Duplicate fragment: ${id}`)
+    this.name = 'DuplicateFragmentError'
+    this.fragmentId = id
+  }
+}
+
+export class FragmentBoundaryError extends Error {
+  /**
+   * @param {string} message
+   */
+  constructor (message) {
+    super(message)
+    this.name = 'FragmentBoundaryError'
+  }
+}
+
+class RenderContext {
+  /**
+   * @param {string | undefined} fragmentId
+   */
+  constructor (fragmentId) {
+    this.fragmentId = fragmentId
+    this.full = ''
+    /** @type {{ id: string, content: string }[]} */
+    this.stack = []
+    /** @type {Map<string, string>} */
+    this.fragments = new Map()
+    /** @type {Set<string>} */
+    this.seen = new Set()
+  }
+
+  /**
+   * @param {string} value
+   */
+  append (value) {
+    this.full += value
+
+    for (const fragment of this.stack) {
+      fragment.content += value
+    }
+  }
+
+  trimTrailingLineWhitespace () {
+    this.full = trimTrailingLineWhitespace(this.full)
+
+    for (const fragment of this.stack) {
+      fragment.content = trimTrailingLineWhitespace(fragment.content)
+    }
+  }
+
+  /**
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  consumeBooleanAttribute (value) {
+    const match = this.full.match(booleanAttributeSuffix)
+
+    if (!match) return false
+
+    const prefix = match[1] ?? ''
+    const name = match[2] ?? ''
+    const replacement = value ? `${prefix}${name}` : ''
+
+    this.full = replaceBooleanAttributeSuffix(this.full, replacement)
+
+    for (const fragment of this.stack) {
+      fragment.content = replaceBooleanAttributeSuffix(fragment.content, replacement)
+    }
+
+    return true
+  }
+
+  /**
+   * @param {string} id
+   */
+  startFragment (id) {
+    if (this.seen.has(id)) {
+      throw new DuplicateFragmentError(id)
+    }
+
+    this.seen.add(id)
+    this.stack.push({ id, content: '' })
+  }
+
+  endFragment () {
+    const fragment = this.stack.pop()
+
+    if (!fragment) {
+      throw new FragmentBoundaryError('Unexpected fragment end with no open fragment')
+    }
+
+    this.fragments.set(fragment.id, fragment.content)
+  }
+
+  finish () {
+    if (this.stack.length > 0) {
+      const open = this.stack.at(-1)
+      throw new FragmentBoundaryError(`Unclosed fragment: ${open?.id}`)
+    }
+
+    if (this.fragmentId) {
+      const fragment = this.fragments.get(this.fragmentId)
+
+      if (fragment == null) {
+        throw new FragmentNotFoundError(this.fragmentId)
+      }
+
+      return stripIndent(fragment)
+    }
+
+    return stripIndent(this.full)
+  }
+}
+
+/**
+ * Converts a renderable value to a primitive string.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function render (value) {
+  if (isHtmlResult(value)) return renderResult(value)
+  if (isRawHtml(value)) return String(value)
+  if (Array.isArray(value)) return value.map(render).join('')
+  if (isNonPrintingValue(value)) return ''
+  return escapeHtml(value)
+}
+
+/**
+ * @param {HtmlResult} result
+ * @returns {string}
+ */
+export function renderResult (result) {
+  const context = new RenderContext(result.options.fragmentId)
+  renderResultInto(result, context)
+  return context.finish()
+}
+
+/**
+ * @param {HtmlResult} result
+ * @param {RenderContext} context
+ */
+function renderResultInto (result, context) {
+  const { strings } = result.compiled
+  const { substitutions } = result
+
+  context.append(strings[0] ?? '')
+
+  for (let index = 0; index < substitutions.length; index++) {
+    const substitution = substitutions[index]
+    const nextString = strings[index + 1] ?? ''
+
+    if (isFragmentBoundary(substitution)) {
+      context.trimTrailingLineWhitespace()
+      appendSubstitution(context, substitution)
+      context.append(stripLeadingBoundaryLineWhitespace(nextString))
+    } else {
+      appendSubstitution(context, substitution)
+      context.append(nextString)
+    }
+  }
+}
+
+/**
+ * @param {RenderContext} context
+ * @param {unknown} value
+ */
+function appendSubstitution (context, value) {
+  if (isFragmentBoundary(value)) {
+    if (value.kind === 'start') context.startFragment(value.id)
+    else context.endFragment()
+    return
+  }
+
+  if (context.consumeBooleanAttribute(value)) {
+    return
+  }
+
+  if (isHtmlResult(value)) {
+    renderResultInto(value, context)
+    return
+  }
+
+  context.append(renderSubstitution(value, context.full))
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} resultSoFar
+ * @returns {string}
+ */
+function renderSubstitution (value, resultSoFar) {
+  if (isNonPrintingValue(value)) return ''
+  if (isRawHtml(value)) return String(value)
+  if (isHtmlResult(value)) return renderNestedResult(value)
+
+  if (Array.isArray(value)) {
+    const parts = value
+      .filter((part) => !isNonPrintingValue(part))
+      .flatMap((part) => {
+        const rendered = renderSubstitution(part, resultSoFar)
+        return typeof part === 'string' && part.includes('\n')
+          ? rendered.split('\n')
+          : [rendered]
+      })
+
+    return inlineArray(resultSoFar, parts)
+  }
+
+  if (typeof value === 'string' && value.includes('\n')) {
+    return inlineArray(resultSoFar, value.split('\n').map(escapeHtml))
+  }
+
+  return escapeHtml(value)
+}
+
+/**
+ * @param {HtmlResult} result
+ * @returns {string}
+ */
+function renderNestedResult (result) {
+  const context = new RenderContext(undefined)
+  renderResultInto(result, context)
+  return context.finish()
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function trimTrailingLineWhitespace (value) {
+  return value.replace(/[ \t]*$/, '')
+}
+
+/**
+ * @param {string} value
+ * @param {string} replacement
+ * @returns {string}
+ */
+function replaceBooleanAttributeSuffix (value, replacement) {
+  return value.replace(booleanAttributeSuffix, replacement)
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function stripLeadingBoundaryLineWhitespace (value) {
+  return value.replace(/^\r?\n/, '')
+}

package/lib/strip-indent.d.ts

@@ -0,0 +1,2 @@
+export function stripIndent(value: string): string;
+//# sourceMappingURL=strip-indent.d.ts.map

package/lib/strip-indent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip-indent.d.ts","sourceRoot":"","sources":["strip-indent.js"],"names":[],"mappings":"AAMA,mCAHW,MAAM,GACJ,MAAM,CAqBlB"}

package/lib/strip-indent.js

@@ -0,0 +1,26 @@
+/**
+ * Smart trims and strips the shared indentation from a template result.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function stripIndent (value) {
+  const trimmed = value
+    .replace(/^[ \t]*\r?\n/, '')
+    .replace(/\r?\n[ \t]*$/, '')
+
+  const lines = trimmed.split(/\r?\n/)
+  let minIndent = Infinity
+
+  for (const line of lines) {
+    if (line.trim() === '') continue
+    const indent = line.match(/^[ \t]*/)?.[0].length ?? 0
+    minIndent = Math.min(minIndent, indent)
+  }
+
+  if (!Number.isFinite(minIndent) || minIndent === 0) return trimmed
+
+  return lines
+    .map((line) => line.trim() === '' ? '' : line.slice(minIndent))
+    .join('\n')
+}

package/lib/utils.d.ts

@@ -0,0 +1,3 @@
+export function isNonPrintingValue(value: unknown): boolean;
+export function stripLastNewLine(value: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/lib/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAIA,0CAHW,OAAO,GACL,OAAO,CAInB;AAMD,wCAHW,MAAM,GACJ,MAAM,CAIlB"}

package/lib/utils.js

@@ -0,0 +1,15 @@
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isNonPrintingValue (value) {
+  return value == null || typeof value === 'boolean' || (typeof value === 'number' && Number.isNaN(value))
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function stripLastNewLine (value) {
+  return value.replace(/\n$/, '')
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "fragtml",
+  "description": "WIP - nothing to see here",
+  "version": "0.0.1",
+  "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io)",
+  "bugs": {
+    "url": "https://github.com/bcomnes/fragtml/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@voxpelli/tsconfig": "^16.1.0",
+    "@types/node": "^25.0.0",
+    "neostandard": "^0.13.0",
+    "npm-run-all2": "^9.0.0",
+    "releasearoni": "^0.2.0",
+    "typescript": "~6.0.3"
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=10"
+  },
+  "homepage": "https://github.com/bcomnes/fragtml",
+  "keywords": [],
+  "license": "MIT",
+  "type": "module",
+  "module": "index.js",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.d.ts.map",
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bcomnes/fragtml.git"
+  },
+  "scripts": {
+    "prepublishOnly": "releasearoni",
+    "postpublish": "npm run clean",
+    "test": "run-s test:*",
+    "test:lint": "eslint",
+    "test:tsc": "tsc",
+    "test:node-test": "node --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info --test",
+    "version": "releasearoni version",
+    "build": "npm run clean && run-p build:*",
+    "build:declaration": "tsc -p declaration.tsconfig.json",
+    "clean": "run-p clean:*",
+    "clean:declarations-top": "rm -rf $(find . -maxdepth 1 -type f -name '*.d.ts*')",
+    "clean:declarations-lib": "rm -rf $(find lib -type f -name '*.d.ts*' ! -name '*-types.d.ts')"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/bcomnes"
+  }
+}