@typed/template 0.13.0 → 1.0.0-beta.0

package/src/HtmlChunk.ts

@@ -1,407 +1,365 @@
+import type * as Template from "./Template.js";
+import * as Array from "effect/Array";
+import { constVoid } from "effect/Function";
+import * as Order from "effect/Order";
+import * as Predicate from "effect/Predicate";
+import { renderToEscapedString, renderToString } from "./internal/encoding.js";
+import { TEMPLATE_END_COMMENT, TEMPLATE_START_COMMENT } from "./internal/meta.js";
+
 /**
+ * Represents a piece of a pre-compiled HTML template.
+ *
+ * Chunks allow the renderer to stream static parts of the HTML immediately
+ * while waiting for dynamic parts to be resolved.
+ *
+ * @example
+ * ```ts
+ * import type { HtmlChunk } from "@typed/template/HtmlChunk"
+ * import { templateToHtmlChunks } from "@typed/template/HtmlChunk"
+ * import { parse } from "@typed/template/Parser"
+ *
+ * const template = parse`<div>Hello ${"world"}</div>`
+ * const chunks = templateToHtmlChunks(template)
+ *
+ * // chunks will contain:
+ * // - HtmlTextChunk with text "<div>Hello "
+ * // - HtmlPartChunk for the dynamic part
+ * // - HtmlTextChunk with text "</div>"
+ * ```
+ *
  * @since 1.0.0
+ * @category models
  */
-import { keyToPartType } from "./internal/utils.js"
-import { isNullOrUndefined } from "./internal/v2/helpers.js"
-import type {
-  Attribute,
-  ElementNode,
-  Node,
-  PartNode,
-  SelfClosingElementNode,
-  SparseAttrNode,
-  SparseClassNameNode,
-  Template,
-  Text,
-  TextOnlyElement
-} from "./Template.js"
+export type HtmlChunk = HtmlTextChunk | HtmlPartChunk | HtmlSparsePartChunk;
 
 /**
+ * A static text chunk.
+ *
  * @since 1.0.0
+ * @category models
  */
-export type HtmlChunk = TextChunk | PartChunk | SparsePartChunk
+export interface HtmlTextChunk {
+  readonly _tag: "text";
+  readonly text: string;
+}
 
 /**
+ * A chunk representing a dynamic part (interpolation).
+ *
  * @since 1.0.0
+ * @category models
  */
-export class TextChunk {
-  readonly _tag = "text"
-  constructor(readonly value: string) {}
+export interface HtmlPartChunk {
+  readonly _tag: "part";
+  readonly node: Template.PartNode;
+  /**
+   * Function to render the value of this part into a string.
+   */
+  readonly render: (value: unknown) => string;
 }
 
 /**
+ * A chunk representing a sparse part (mixed static/dynamic text).
+ *
  * @since 1.0.0
+ * @category models
  */
-export class PartChunk {
-  readonly _tag = "part"
-
-  constructor(
-    readonly node: PartNode,
-    readonly render: (value: unknown) => string
-  ) {}
+export interface HtmlSparsePartChunk {
+  readonly _tag: "sparse-part";
+  readonly node: Template.SparsePartNode;
+  /**
+   * Function to render the value of this part into a string.
+   */
+  readonly render: (value: unknown) => string;
 }
 
 /**
- * @since 1.0.0
+ * Helper class for constructing a list of `HtmlChunk`s.
+ * @internal
  */
-export class SparsePartChunk {
-  readonly _tag = "sparse-part"
+export class HtmlChunksBuilder {
+  private chunks: Array<HtmlChunk> = [];
+
+  text(text: string): HtmlChunksBuilder {
+    const lastIndex = this.chunks.length - 1;
+    const lastChunk = this.chunks[lastIndex];
+    if (lastChunk?._tag === "text") {
+      this.chunks[lastIndex] = { _tag: "text", text: lastChunk.text + text };
+    } else {
+      this.chunks.push({ _tag: "text", text });
+    }
+    return this;
+  }
+
+  part(node: Template.PartNode, render: (value: unknown) => string): HtmlChunksBuilder {
+    this.chunks.push({ _tag: "part", node, render });
+    return this;
+  }
+
+  sparsePart(node: Template.SparsePartNode, render: (value: unknown) => string): HtmlChunksBuilder {
+    this.chunks.push({ _tag: "sparse-part", node, render });
+    return this;
+  }
 
-  constructor(
-    readonly node: SparseAttrNode | SparseClassNameNode,
-    readonly render: (value: AttrValue) => string
-  ) {}
+  build(): ReadonlyArray<HtmlChunk> {
+    const chunks = this.chunks;
+    this.chunks = [];
+    return chunks;
+  }
 }
 
+// TODO: Add support for unsafe HTML content.
+
 /**
+ * Converts a parsed `Template` into a sequence of `HtmlChunk`s.
+ * This optimization pre-calculates the static HTML strings to minimize work at render time.
+ *
+ * @example
+ * ```ts
+ * import { templateToHtmlChunks } from "@typed/template/HtmlChunk"
+ * import { parse } from "@typed/template/Parser"
+ *
+ * const template = parse`<div class="container">Hello ${"world"}</div>`
+ * const chunks = templateToHtmlChunks(template)
+ *
+ * // chunks is an array of HtmlChunk objects
+ * // Static parts are pre-rendered as text chunks
+ * // Dynamic parts are represented as part chunks
+ * ```
+ *
  * @since 1.0.0
+ * @category utilities
  */
-export type AttrValue = string | null | undefined | ReadonlyArray<AttrValue>
-
-// TODO: Should we escape more things?
-// TODO: We should manually optimize the text fusion
+export function templateToHtmlChunks({ nodes }: Template.Template) {
+  const builder = new HtmlChunksBuilder();
+  for (const node of nodes) nodeToHtmlChunk(builder, node);
+  return builder.build();
+}
 
 /**
+ * Wraps the HTML chunks with comments containing the template hash.
+ * This is crucial for hydration to identify which template rendered a section of HTML.
+ *
+ * @example
+ * ```ts
+ * import { addTemplateHash, templateToHtmlChunks } from "@typed/template/HtmlChunk"
+ * import { parse } from "@typed/template/Parser"
+ *
+ * const template = parse`<div>Hello</div>`
+ * const chunks = templateToHtmlChunks(template)
+ * const chunksWithHash = addTemplateHash(chunks, template)
+ *
+ * // chunksWithHash will have template hash comments added
+ * // for hydration purposes
+ * ```
+ *
  * @since 1.0.0
+ * @category utilities
  */
-export function templateToHtmlChunks({ hash, nodes }: Template, isStatic: boolean) {
-  if (isStatic) {
-    return fuseTextChunks(nodes.flatMap((node) => nodeToHtmlChunk(node)))
-  }
-
-  const chunks = fuseTextChunks([
-    templateStart(hash),
-    ...nodes.flatMap((node) => nodeToHtmlChunk(node, hash)),
-    templateEnd(hash)
-  ])
-
-  return chunks
+export function addTemplateHash(
+  chunks: ReadonlyArray<HtmlChunk>,
+  { hash }: Template.Template,
+): ReadonlyArray<HtmlChunk> {
+  const start = TEMPLATE_START_COMMENT(hash);
+  const end = TEMPLATE_END_COMMENT(hash);
+  if (chunks.length === 0) return [{ _tag: "text", text: start + end }];
+  return appendTextChunk(prependTextChunk(chunks, start), end);
 }
 
-function templateStart(hash: string): HtmlChunk {
-  return new TextChunk(`<!--typed-${hash}-->`)
+function prependTextChunk(
+  chunks: ReadonlyArray<HtmlChunk>,
+  text: string,
+): ReadonlyArray<HtmlChunk> {
+  if (chunks.length === 0) return [{ _tag: "text", text }];
+  const firstChunk = chunks[0];
+  if (firstChunk._tag === "text")
+    return [{ _tag: "text", text: text + firstChunk.text }, ...chunks.slice(1)];
+  return [{ _tag: "text", text }, ...chunks];
 }
 
-function templateEnd(hash: string): HtmlChunk {
-  return new TextChunk(`<!--/typed-${hash}-->`)
-}
-
-function fuseTextChunks(chunks: Array<HtmlChunk>): ReadonlyArray<HtmlChunk> {
-  const output: Array<HtmlChunk> = []
-
-  for (let i = 0; i < chunks.length; i++) {
-    if (i > 0) {
-      const prevIndex = output.length - 1
-      const prev = output[prevIndex]
-      const curr = chunks[i]
-
-      if (prev._tag === "text" && curr._tag === "text") {
-        output[prevIndex] = new TextChunk(prev.value + curr.value)
-      } else {
-        output.push(curr)
-      }
-    } else {
-      output.push(chunks[i])
-    }
-  }
-
-  return output
+function appendTextChunk(chunks: ReadonlyArray<HtmlChunk>, text: string): ReadonlyArray<HtmlChunk> {
+  if (chunks.length === 0) return [{ _tag: "text", text }];
+  const lastChunk = chunks[chunks.length - 1];
+  if (lastChunk._tag === "text")
+    return [...chunks.slice(0, -1), { _tag: "text", text: lastChunk.text + text }];
+  return [...chunks, { _tag: "text", text }];
 }
 
 type NodeMap = {
-  readonly [K in Node["_tag"]]: (node: Extract<Node, { _tag: K }>, hash?: string) => Array<HtmlChunk>
-}
+  readonly [K in Template.Node["_tag"]]: (
+    builder: HtmlChunksBuilder,
+    node: Extract<Template.Node, { _tag: K }>,
+  ) => void;
+};
 
 const nodeMap: NodeMap = {
-  doctype: (node) => [new TextChunk(`<!DOCTYPE ${node.name}>`)],
+  doctype: (builder, node) => builder.text(`<!DOCTYPE ${node.name}>`),
   element: elementToHtmlChunks,
-  node: (node) => [new PartChunk(node, String)],
+  text: (builder, node) => builder.text(node.value),
+  node: (builder, part) => builder.part(part, (v) => renderToEscapedString(v, "")),
   "self-closing-element": selfClosingElementToHtmlChunks,
-  text: (node) => [textToHtmlChunks(node)],
   "text-only-element": textOnlyElementToHtmlChunks,
-  comment: (node) => [new TextChunk(`<!--${node.value}-->`)],
-  "comment-part": (node) => [
-    new PartChunk(node, (value) => `<!--${value}-->`)
-  ],
-  "sparse-comment": (node) => [
-    new TextChunk("<!--"),
-    ...node.nodes.map((node) => {
-      if (node._tag === "text") {
-        return textToHtmlChunks(node)
-      } else {
-        return new PartChunk(node, (value) => `${value}`)
-      }
-    }),
-    new TextChunk("-->")
-  ]
-}
+  comment: (builder, node) => builder.text(`<!--${node.value}-->`),
+  "comment-part": (builder, part) =>
+    builder.part(part, (v) => `<!--${renderToEscapedString(v, "")}-->`),
+  "sparse-comment": (builder, part) =>
+    builder.sparsePart(part, (v) => `<!--${renderToEscapedString(v, "")}-->`),
+};
 
-function nodeToHtmlChunk(node: Node, hash?: string): Array<HtmlChunk> {
-  return nodeMap[node._tag](node as any, hash)
+function selfClosingElementToHtmlChunks(
+  builder: HtmlChunksBuilder,
+  node: Template.SelfClosingElementNode,
+) {
+  builder.text(`<${node.tagName}`);
+  addAttributes(builder, node.attributes);
+  builder.text(`/>`);
 }
 
-function elementToHtmlChunks(
-  { attributes, children, tagName }: ElementNode
-): Array<HtmlChunk> {
-  if (attributes.length === 0) {
-    return [
-      new TextChunk(openTag(tagName) + ">"),
-      ...children.flatMap((c) => nodeToHtmlChunk(c)),
-      new TextChunk(closeTag(tagName))
-    ]
+function textOnlyElementToHtmlChunks(builder: HtmlChunksBuilder, node: Template.TextOnlyElement) {
+  builder.text(`<${node.tagName}`);
+  addAttributes(builder, node.attributes);
+  builder.text(">");
+  if (node.textContent !== null) {
+    textContentToHtml(builder, node.textContent);
   }
 
-  const chunks: Array<HtmlChunk> = [
-    new TextChunk(openTag(tagName)),
-    ...attributes.map((a) => attributeToHtmlChunk(a)),
-    new TextChunk(">"),
-    ...children.flatMap((c) => nodeToHtmlChunk(c)),
-    new TextChunk(closeTag(tagName))
-  ]
-
-  return chunks
+  builder.text(`</${node.tagName}>`);
 }
 
-function selfClosingElementToHtmlChunks(
-  { attributes, tagName }: SelfClosingElementNode
-): Array<HtmlChunk> {
-  if (attributes.length === 0) {
-    return [new TextChunk(openTag(tagName) + " />")]
+function textContentToHtml(builder: HtmlChunksBuilder, textContent: Template.Text) {
+  switch (textContent._tag) {
+    case "text":
+      return builder.text(textContent.value);
+    case "text-part":
+      return builder.part(textContent, (v) => renderToString(v, ""));
+    case "sparse-text":
+      return builder.sparsePart(textContent, (v) => renderToString(v, ""));
   }
+}
 
-  const chunks: Array<HtmlChunk> = [
-    new TextChunk(openTag(tagName)),
-    ...attributes.map((a) => attributeToHtmlChunk(a)),
-    new TextChunk(`/>`)
-  ]
-
-  return chunks
+function nodeToHtmlChunk(builder: HtmlChunksBuilder, node: Template.Node) {
+  const handler = nodeMap[node._tag];
+  handler(builder, node as never);
 }
 
-function textToHtmlChunks(text: Text): HtmlChunk {
-  return text._tag === "text" ? new TextChunk(text.value) : new PartChunk(text, String)
+function elementToHtmlChunks(
+  builder: HtmlChunksBuilder,
+  { attributes, children, tagName }: Template.ElementNode,
+) {
+  builder.text(`<${tagName}`);
+  addAttributes(builder, attributes);
+  builder.text(">");
+  for (const child of children) nodeToHtmlChunk(builder, child);
+  builder.text(`</${tagName}>`);
 }
 
-function textOnlyElementToHtmlChunks(
-  { attributes, children, tagName }: TextOnlyElement
-): Array<HtmlChunk> {
-  if (attributes.length === 0) {
-    return [
-      new TextChunk(openTag(tagName) + ">"),
-      ...children.map((c) => textToHtmlChunks(c)),
-      new TextChunk(closeTag(tagName))
-    ]
+function addAttributes(builder: HtmlChunksBuilder, attributes: ReadonlyArray<Template.Attribute>) {
+  if (attributes.length > 0) {
+    const lastIndex = attributes.length - 1;
+    for (const [index, attribute] of sortAttributes(attributes).entries()) {
+      attributeToHtmlChunk(builder, attribute, {
+        isFirst: index === 0,
+        isLast: index === lastIndex,
+      });
+    }
   }
-
-  const chunks: Array<HtmlChunk> = [
-    new TextChunk(openTag(tagName)),
-    ...attributes.map((a) => attributeToHtmlChunk(a)),
-    new TextChunk(">"),
-    ...children.map((c) => textToHtmlChunks(c)),
-    new TextChunk(closeTag(tagName))
-  ]
-
-  return chunks
 }
 
-type AttrMap = {
-  [K in Attribute["_tag"]]: (attr: Extract<Attribute, { readonly _tag: K }>) => HtmlChunk
+type Placement = {
+  readonly isFirst: boolean;
+  readonly isLast: boolean;
+};
+
+type AttributeMap = {
+  readonly [K in Template.Attribute["_tag"]]: (
+    builder: HtmlChunksBuilder,
+    attribute: Extract<Template.Attribute, { _tag: K }>,
+    placement: Placement,
+  ) => void;
+};
+
+function attributeToHtmlChunk(
+  builder: HtmlChunksBuilder,
+  attr: Template.Attribute,
+  placement: Placement,
+): void {
+  attributeMap[attr._tag](builder, attr as never, placement);
 }
 
-const attrMap: AttrMap = {
-  attribute: (attr) => new TextChunk(` ${attr.name}="${escape(attr.value)}"`),
-  attr: (attr) => new PartChunk(attr, (value) => (value == null ? `` : ` ${attr.name}="${escape(value)}"`)),
-  boolean: (attr) => new TextChunk(" " + attr.name),
-  "boolean-part": (attr) => new PartChunk(attr, (value) => (value ? ` ${attr.name}` : "")),
-  "className-part": (attr) => new PartChunk(attr, (value) => (value ? ` class="${escape(value)}"` : "")),
-  data: (attr) =>
-    new PartChunk(attr, (value) => value == null ? `` : datasetToString(value as Readonly<Record<string, string>>)),
-  event: () => new TextChunk(""),
-  property: (attr) => new PartChunk(attr, (value) => (value == null ? `` : ` ${attr.name}="${escape(value)}"`)),
-  properties: (attr) =>
-    new PartChunk(
-      attr,
-      (
-        value
-      ) => {
-        if (value == null) return ""
-
-        // Each call has only 1 key-value pair
-        const [k, v] = Object.entries(value)[0]
-
-        if (value == null) return ""
-
-        const [type, key] = keyToPartType(k)
-
-        switch (type) {
-          case "attr":
-          case "property":
-            return v == null ? "" : ` ${key}="${escape(v)}"`
-          case "boolean":
-            return v ? key : ""
-          case "class":
-            return ` class="${escape(v)}"`
-          case "data": {
-            const d = datasetToString(v)
-            return d.length === 0 ? "" : ` ${d}`
-          }
-          default:
-            return ""
-        }
-      }
+const attributeMap: AttributeMap = {
+  attribute: (builder, attribute, placement) =>
+    builder.text(addAttributeSpace(`${attribute.name}="${attribute.value}"`, placement)),
+  boolean: (builder, attribute, placement) =>
+    builder.text(addAttributeSpace(`${attribute.name}`, placement)),
+  attr: (builder, attribute, placement) =>
+    builder.part(attribute, (v) =>
+      addAttributeSpace(`${attribute.name}="${renderToEscapedString(v, "")}"`, placement),
+    ),
+  "sparse-attr": (builder, attribute, placement) =>
+    builder.sparsePart(attribute, (v) =>
+      addAttributeSpace(`${attribute.name}="${renderToEscapedString(v, "")}"`, placement),
+    ),
+  "boolean-part": (builder, attribute, placement) =>
+    builder.part(attribute, (v) => addAttributeSpace(v ? `${attribute.name}` : "", placement)),
+  "className-part": (builder, attribute, placement) =>
+    builder.part(attribute, (v) =>
+      addAttributeSpace(`class="${renderToEscapedString(v, " ")}"`, placement),
+    ),
+  "sparse-class-name": (builder, attribute, placement) =>
+    builder.sparsePart(attribute, (v) =>
+      addAttributeSpace(`class="${renderToEscapedString(v, "")}"`, placement),
+    ),
+  data: (builder, attribute) =>
+    builder.part(attribute, (v) => (Predicate.isObject(v) ? recordWithPrefix(`data-`, v) : "")),
+  property: (builder, attribute, placement) =>
+    builder.part(attribute, (v) =>
+      addAttributeSpace(`${attribute.name}="${renderToEscapedString(v, "")}"`, placement),
+    ),
+  properties: (builder, attribute, placement) =>
+    builder.part(attribute, (v) =>
+      addAttributeSpace(Predicate.isObject(v) ? recordWithPrefix(``, v) : "", placement),
     ),
-  ref: () => new TextChunk(""),
-  "sparse-attr": (attr) =>
-    new SparsePartChunk(attr, (values) => {
-      return values == null
-        ? ``
-        : ` ${attr.name}="${Array.isArray(values) ? escape(values.filter(isString).join("")) : escape(values)}"`
-    }),
-  "sparse-class-name": (attr) =>
-    new SparsePartChunk(attr, (values) => {
-      return values == null
-        ? ``
-        : ` class="${Array.isArray(values) ? escape(values.filter(isString).join("")) : escape(values)}"`
-    }),
-  text: (attr) => new TextChunk(attr.value)
-}
 
-function attributeToHtmlChunk(attr: Attribute): HtmlChunk {
-  return attrMap[attr._tag](attr as any)
-}
+  // Don't have HTML representations for these
+  ref: constVoid,
+  event: constVoid,
+};
 
-function isString(value: unknown): value is string {
-  return typeof value === "string"
+function addAttributeSpace(str: string, placement: Placement) {
+  if (str.length === 0) return str;
+  if (placement.isFirst) return " " + str + (placement.isLast ? "" : " ");
+  return str + (placement.isLast ? "" : " ");
 }
 
-function datasetToString(dataset: Readonly<Record<string, string | undefined>>) {
-  const s = Object.entries(dataset)
-    .map(([key, value]) => (value === undefined ? `data-${key}` : `data-${key}="${escape(value)}"`))
-    .join(" ")
+function recordWithPrefix(prefix: string, r: {}) {
+  const s = Object.entries(r)
+    .map(([key, value]) =>
+      value === undefined
+        ? `${prefix}${key}`
+        : `${prefix}${key}="${renderToEscapedString(value, "")}"`,
+    )
+    .join(" ");
 
-  return s.length === 0 ? "" : " " + s
+  return s.length === 0 ? "" : " " + s;
 }
 
-function openTag(tagName: string): string {
-  return `<${tagName}`
-}
+const AttributeOrder = Order.mapInput(
+  Order.Number,
+  // Order such that static attributes can be streamed out first
+  // and sparse attributes can be streamed out last
+  (attr: Template.Attribute) => (isStaticAttribute(attr) ? -1 : isSparseAttribute(attr) ? 1 : 0),
+);
 
-function closeTag(tagName: string): string {
-  return `</${tagName}>`
-}
+const sortAttributes = Array.sortBy(AttributeOrder);
 
-/**
- * @since 1.0.0
- */
-export function escape(s: unknown): string {
-  switch (typeof s) {
-    case "string":
-    case "number":
-    case "boolean":
-    case "bigint":
-      return escapeHtml(String(s))
-    case "object": {
-      if (isNullOrUndefined(s)) {
-        return ""
-      } else if (Array.isArray(s)) {
-        return s.map(escape).join("")
-      } else if (s instanceof Date) {
-        return escapeHtml(s.toISOString())
-      } else if (s instanceof RegExp) {
-        return escapeHtml(s.toString())
-      } else {
-        return escapeHtml(JSON.stringify(s))
-      }
-    }
-    default:
-      return escapeHtml(JSON.stringify(s))
-  }
-}
+const staticAttributes = new Set<Template.Attribute["_tag"]>(["attribute", "boolean"]);
 
-/**
- * @since 1.0.0
- */
-export function unescape(s: string) {
-  const unescaped = unescapeHtml(s)
-  const couldBeJson = unescaped[0] === "[" || unescaped === "{"
-  if (couldBeJson) {
-    try {
-      return JSON.parse(unescaped)
-    } catch {
-      return unescaped
-    }
-  } else {
-    return unescaped
-  }
+function isStaticAttribute(attr: Template.Attribute) {
+  return staticAttributes.has(attr._tag);
 }
 
-const unescapeHtmlRules = [
-  [/&quot;/g, "\""],
-  [/&#39;/g, "'"],
-  [/&#x3A;/g, ":"],
-  [/&lt;/g, "<"],
-  [/&gt;/g, ">"],
-  [/&amp;/g, "&"]
-] as const
-
-const matchHtmlRegExp = /["'&<>]/
-
-/**
- * @since 1.0.0
- */
-export function escapeHtml(str: string): string {
-  const match = matchHtmlRegExp.exec(str)
-
-  if (!match) {
-    return str
-  }
-
-  let escape
-  let html = ""
-  let index = 0
-  let lastIndex = 0
-
-  for (index = match.index; index < str.length; index++) {
-    switch (str.charCodeAt(index)) {
-      case 34: // "
-        escape = "&quot;"
-        break
-      case 38: // &
-        escape = "&amp;"
-        break
-      case 39: // '
-        escape = "&#39;"
-        break
-      case 60: // <
-        escape = "&lt;"
-        break
-      case 62: // >
-        escape = "&gt;"
-        break
-      default:
-        continue
-    }
-
-    if (lastIndex !== index) {
-      html += str.substring(lastIndex, index)
-    }
-
-    lastIndex = index + 1
-    html += escape
-  }
-
-  return lastIndex !== index
-    ? html + str.substring(lastIndex, index)
-    : html
-}
-
-/**
- * @since 1.0.0
- */
-export function unescapeHtml(html: string) {
-  for (const [from, to] of unescapeHtmlRules) {
-    html = html.replace(from, to)
-  }
+const sparseAttributes = new Set<Template.Attribute["_tag"]>(["sparse-attr", "sparse-class-name"]);
 
-  return html
+function isSparseAttribute(attr: Template.Attribute) {
+  return sparseAttributes.has(attr._tag);
 }