@typed/template 0.14.0 → 1.0.0-beta.1

package/src/Template.ts

@@ -1,46 +1,79 @@
-/**
- * @since 1.0.0
- */
-import type { Chunk, NonEmptyChunk } from "effect/Chunk"
-import { type Inspectable, NodeInspectSymbol } from "effect/Inspectable"
-
-/**
- * @since 1.0.0
+import { type Inspectable, NodeInspectSymbol } from "effect/Inspectable";
+
+/**
+ * Represents a parsed HTML template.
+ *
+ * A `Template` instance contains the static structure of an HTML template (nodes)
+ * and metadata about dynamic parts (interpolation points).
+ *
+ * @example
+ * ```ts
+ * import { parse } from "@typed/template/Parser"
+ * import * as Template from "@typed/template/Template"
+ *
+ * // Parse a template string
+ * const template = parse`<div>Hello ${"world"}</div>`
+ *
+ * // Access template structure
+ * console.log(template.nodes) // Array of parsed nodes
+ * console.log(template.parts) // Array of dynamic parts
+ * console.log(template.hash) // Unique hash for caching
+ * ```
+ *
+ * @since 1.0.0
+ * @category models
  */
 export class Template implements Inspectable {
-  readonly _tag = "template"
+  readonly _tag = "template";
+
+  /**
+   * The root nodes of the template.
+   */
+  readonly nodes: ReadonlyArray<Node>;
+
+  /**
+   * A unique hash representing the template content. Used for caching and hydration.
+   */
+  readonly hash: string;
+
+  /**
+   * A list of dynamic parts in the template.
+   * Each part is associated with a path (array of indices) to locate the corresponding
+   * node in the DOM tree.
+   */
+  readonly parts: ReadonlyArray<readonly [part: PartNode | SparsePartNode, path: Array<number>]>;
 
   constructor(
-    readonly nodes: ReadonlyArray<Node>,
-    readonly hash: string,
-    // Parts are a array of Parts to the respective path from the root node to access it prior to rendering
-    /// any nodes/elements into the template.
-    readonly parts: ReadonlyArray<
-      readonly [part: PartNode | SparsePartNode, path: Chunk<number> | NonEmptyChunk<number>]
-    >
-  ) {}
+    nodes: ReadonlyArray<Node>,
+    hash: string,
+    parts: ReadonlyArray<readonly [part: PartNode | SparsePartNode, path: Array<number>]>,
+  ) {
+    this.nodes = nodes;
+    this.hash = hash;
+    this.parts = parts;
+  }
 
   toJSON() {
     return {
       _tag: "template",
       nodes: this.nodes,
       hash: this.hash,
-      parts: this.parts.map(([part, path]) => [part, path.toJSON()])
-    }
+      parts: this.parts,
+    };
   }
 
   [NodeInspectSymbol]() {
-    return this.toJSON()
+    return this.toJSON();
   }
 }
 
 /**
- * @since 1.0.0
+ * Represents a node that can be a parent of other nodes in the template AST.
  */
-export type ParentNode = ElementNode | SelfClosingElementNode | TextOnlyElement
+export type ParentNode = ElementNode | SelfClosingElementNode | TextOnlyElement;
 
 /**
- * @since 1.0.0
+ * Represents any node in the template AST.
  */
 export type Node =
   | ElementNode
@@ -49,10 +82,10 @@ export type Node =
   | TextNode
   | NodePart
   | Comment
-  | DocType
+  | DocType;
 
 /**
- * @since 1.0.0
+ * Represents a dynamic part of the template that will be updated at runtime.
  */
 export type PartNode =
   | AttrPartNode
@@ -65,70 +98,93 @@ export type PartNode =
   | PropertiesPartNode
   | RefPartNode
   | TextPartNode
-  | CommentPartNode
+  | CommentPartNode;
 
 /**
- * @since 1.0.0
+ * Represents a "sparse" part, which is a text or attribute value composed of
+ * mix of static text and dynamic parts (e.g. `id="prefix-${id}"`).
  */
-export type SparsePartNode = SparseAttrNode | SparseClassNameNode | SparseCommentNode
+export type SparsePartNode =
+  | SparseAttrNode
+  | SparseClassNameNode
+  | SparseCommentNode
+  | SparseTextNode;
 
 /**
- * @since 1.0.0
+ * Represents an HTML element with children.
  */
 export class ElementNode {
-  readonly _tag = "element"
-  constructor(
-    readonly tagName: string,
-    readonly attributes: Array<Attribute>,
-    readonly children: Array<Node>
-  ) {}
+  readonly _tag = "element";
+  readonly tagName: string;
+  readonly attributes: Array<Attribute>;
+  readonly children: Array<Node>;
+  constructor(tagName: string, attributes: Array<Attribute>, children: Array<Node>) {
+    this.tagName = tagName;
+    this.attributes = attributes;
+    this.children = children;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a dynamic insertion point within the node structure (e.g. `<div>${content}</div>`).
  */
 export class NodePart {
-  readonly _tag = "node"
-  constructor(readonly index: number) {}
+  readonly _tag = "node";
+  /**
+   * The index of the value in the interpolation array.
+   */
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a self-closing HTML element (e.g. `<br />`, `<img />`).
  */
 export class SelfClosingElementNode {
-  readonly _tag = "self-closing-element"
-  constructor(
-    readonly tagName: string,
-    readonly attributes: Array<Attribute>
-  ) {}
+  readonly _tag = "self-closing-element";
+  readonly tagName: string;
+  readonly attributes: Array<Attribute>;
+  constructor(tagName: string, attributes: Array<Attribute>) {
+    this.tagName = tagName;
+    this.attributes = attributes;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents an element that contains only text (e.g. `<script>`, `<style>`).
  */
 export class TextOnlyElement {
-  readonly _tag = "text-only-element"
-  constructor(
-    readonly tagName: string,
-    readonly attributes: Array<Attribute>,
-    readonly children: Array<Text>
-  ) {}
+  readonly _tag = "text-only-element";
+
+  readonly tagName: string;
+  readonly attributes: Array<Attribute>;
+  readonly textContent: Text | null;
+  constructor(tagName: string, attributes: Array<Attribute>, textContent: Text | null) {
+    this.tagName = tagName;
+    this.attributes = attributes;
+    this.textContent = textContent;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a DOCTYPE declaration.
  */
 export class DocType {
-  readonly _tag = "doctype"
-  constructor(
-    readonly name: string,
-    readonly publicType?: string,
-    readonly systemId?: string
-  ) {}
+  readonly _tag = "doctype";
+  readonly name: string;
+  readonly publicId: string | undefined;
+  readonly systemId: string | undefined;
+  constructor(name: string, publicType?: string, systemId?: string) {
+    this.name = name;
+    this.publicId = publicType;
+    this.systemId = systemId;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents an attribute on an element.
  */
 export type Attribute =
   | AttributeNode
@@ -136,192 +192,237 @@ export type Attribute =
   | SparseAttrNode
   | BooleanNode
   | BooleanPartNode
-  | ClassNameNode
+  | ClassNamePartNode
   | SparseClassNameNode
   | DataPartNode
   | EventPartNode
   | PropertyPartNode
   | PropertiesPartNode
-  | RefPartNode
+  | RefPartNode;
 
 /**
- * @since 1.0.0
+ * Represents a static attribute (e.g. `class="foo"`).
  */
 export class AttributeNode {
-  readonly _tag = "attribute" as const
-  constructor(
-    readonly name: string,
-    readonly value: string
-  ) {}
+  readonly _tag = "attribute" as const;
+  readonly name: string;
+  readonly value: string;
+  constructor(name: string, value: string) {
+    this.name = name;
+    this.value = value;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a dynamic attribute (e.g. `src="${url}"`).
  */
 export class AttrPartNode {
-  readonly _tag = "attr" as const
-  constructor(
-    readonly name: string,
-    readonly index: number
-  ) {}
+  readonly _tag = "attr" as const;
+  readonly name: string;
+  readonly index: number;
+  constructor(name: string, index: number) {
+    this.name = name;
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a sparse attribute (e.g. `class="foo ${bar}"`).
  */
 export class SparseAttrNode {
-  readonly _tag = "sparse-attr" as const
-  constructor(
-    readonly name: string,
-    readonly nodes: Array<AttrPartNode | TextNode>
-  ) {}
+  readonly _tag = "sparse-attr" as const;
+  readonly name: string;
+  readonly nodes: Array<AttrPartNode | TextNode>;
+  constructor(name: string, nodes: Array<AttrPartNode | TextNode>) {
+    this.name = name;
+    this.nodes = nodes;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a boolean attribute (e.g. `disabled`).
  */
 export class BooleanNode {
-  readonly _tag = "boolean" as const
-  constructor(readonly name: string) {}
+  readonly _tag = "boolean" as const;
+  readonly name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a dynamic boolean attribute (e.g. `?disabled="${isDisabled}"`).
  */
 export class BooleanPartNode {
-  readonly _tag = "boolean-part" as const
-  constructor(
-    readonly name: string,
-    readonly index: number
-  ) {}
+  readonly _tag = "boolean-part" as const;
+  readonly name: string;
+  readonly index: number;
+  constructor(name: string, index: number) {
+    this.name = name;
+    this.index = index;
+  }
 }
-
 /**
- * @since 1.0.0
- */
-export type ClassNameNode = TextNode | ClassNamePartNode
-
-/**
- * @since 1.0.0
+ * Represents a dynamic class name part (e.g. `class="${classes}"`).
  */
 export class ClassNamePartNode {
-  readonly _tag = "className-part" as const
-  constructor(readonly index: number) {}
+  readonly _tag = "className-part" as const;
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a sparse class name (e.g. `class="foo ${bar}"`).
  */
 export class SparseClassNameNode {
-  readonly _tag = "sparse-class-name" as const
+  readonly _tag = "sparse-class-name" as const;
 
-  constructor(readonly nodes: Array<ClassNameNode>) {}
+  readonly nodes: Array<ClassNamePartNode | TextNode>;
+  constructor(nodes: Array<ClassNamePartNode | TextNode>) {
+    this.nodes = nodes;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a data attribute part (e.g. `data-foo="${value}"`).
  */
 export class DataPartNode {
-  readonly _tag = "data" as const
+  readonly _tag = "data" as const;
 
-  constructor(readonly index: number) {}
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents an event listener part (e.g. `@click="${handler}"`).
  */
 export class EventPartNode {
-  readonly _tag = "event" as const
-
-  constructor(
-    readonly name: string,
-    readonly index: number
-  ) {}
+  readonly _tag = "event" as const;
+  readonly name: string;
+  readonly index: number;
+  constructor(name: string, index: number) {
+    this.name = name;
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a property assignment (e.g. `.value="${value}"`).
  */
 export class PropertyPartNode {
-  readonly _tag = "property" as const
-
-  constructor(
-    readonly name: string,
-    readonly index: number
-  ) {}
+  readonly _tag = "property" as const;
+  readonly name: string;
+  readonly index: number;
+  constructor(name: string, index: number) {
+    this.name = name;
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a spread of properties (e.g. `${...props}`).
  */
 export class PropertiesPartNode {
-  readonly _tag = "properties" as const
-
-  constructor(
-    readonly index: number
-  ) {}
+  readonly _tag = "properties" as const;
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a reference capture (e.g. `ref="${ref}"`).
  */
 export class RefPartNode {
-  readonly _tag = "ref" as const
+  readonly _tag = "ref" as const;
 
-  constructor(readonly index: number) {}
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents text content.
  */
-export type Text = TextNode | TextPartNode
+export type Text = TextNode | TextPartNode | SparseTextNode;
 
 /**
- * @since 1.0.0
+ * Represents a static text node.
  */
 export class TextNode {
-  readonly _tag = "text" as const
+  readonly _tag = "text" as const;
 
-  constructor(readonly value: string) {}
+  readonly value: string;
+  constructor(value: string) {
+    this.value = value;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a dynamic text part (e.g. `${text}`).
  */
 export class TextPartNode {
-  readonly _tag = "text-part" as const
+  readonly _tag = "text-part" as const;
 
-  constructor(readonly index: number) {}
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents sparse text content (e.g. `Hello ${name}!`).
  */
-export type Comment = CommentNode | CommentPartNode | SparseCommentNode
+export class SparseTextNode {
+  readonly _tag = "sparse-text" as const;
+  readonly nodes: Array<TextNode | TextPartNode>;
+  constructor(nodes: Array<TextNode | TextPartNode>) {
+    this.nodes = nodes;
+  }
+}
 
 /**
- * @since 1.0.0
+ * Represents a comment node.
+ */
+export type Comment = CommentNode | CommentPartNode | SparseCommentNode;
+
+/**
+ * Represents a static comment.
  */
 export class CommentNode {
-  readonly _tag = "comment" as const
+  readonly _tag = "comment" as const;
 
-  constructor(readonly value: string) {}
+  readonly value: string;
+  constructor(value: string) {
+    this.value = value;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a dynamic comment part.
  */
 export class CommentPartNode {
-  readonly _tag = "comment-part" as const
+  readonly _tag = "comment-part" as const;
 
-  constructor(readonly index: number) {}
+  readonly index: number;
+  constructor(index: number) {
+    this.index = index;
+  }
 }
 
 /**
- * @since 1.0.0
+ * Represents a sparse comment.
  */
 export class SparseCommentNode {
-  readonly _tag = "sparse-comment" as const
+  readonly _tag = "sparse-comment" as const;
 
-  constructor(readonly nodes: Array<TextNode | CommentPartNode>) {}
+  readonly nodes: Array<TextNode | CommentPartNode>;
+  constructor(nodes: Array<TextNode | CommentPartNode>) {
+    this.nodes = nodes;
+  }
 }