@yaebal/rich 0.0.1 → 0.0.2

package/src/template.test.ts

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { heading, list, paragraph } from "./blocks.js";
+import { RichDocument } from "./document.js";
+import { bold } from "./inline.js";
+import { RichError } from "./node.js";
+import { document, html, md } from "./template.js";
+
+test("tagged form escapes interpolated text per dialect and keeps the literal skeleton raw", () => {
+	const user = "<script>alert(1)</script>";
+
+	assert.equal(html`<p>${user}</p>`.content, "<p>&lt;script&gt;alert(1)&lt;/script&gt;</p>");
+	assert.equal(md`# ${"a*b"}`.content, "# a\\*b");
+});
+
+test("the same builder node renders into whichever dialect the template asks for", () => {
+	const status = bold("ok");
+
+	assert.equal(html`state: ${status}`.content, "state: <b>ok</b>");
+	assert.equal(md`state: ${status}`.content, "state: **ok**");
+});
+
+test("tagged form dedents the literal skeleton but not interpolated values", () => {
+	const doc = md`
+		# title
+
+		${"  indented value"}
+	`;
+
+	assert.equal(doc.content, "# title\n\n  indented value");
+});
+
+test("array and falsy interpolations — arrays concatenate, null/undefined/false vanish", () => {
+	const cond = false as boolean;
+
+	assert.equal(html`${["a", bold("b")]}${cond && "no"}${null}`.content, "a<b>b</b>");
+});
+
+test("a RichDocument interpolates raw when the dialect matches, throws RichError when it doesn't", () => {
+	const inner = md`**pre-rendered**`;
+
+	assert.equal(md`${inner}!`.content, "**pre-rendered**!");
+	assert.throws(() => html`${inner}`, RichError);
+});
+
+test("plain-function form passes a pre-formatted string through untouched", () => {
+	assert.equal(html("<p>as-is</p>").content, "<p>as-is</p>");
+	assert.equal(md("# as-is").content, "# as-is");
+});
+
+test("block-array form joins blocks — blank lines in markdown, adjacent tags in html", () => {
+	const blocks = [heading(1, "t"), paragraph("p"), list(["a"])];
+
+	assert.equal(html(blocks).content, "<h1>t</h1><p>p</p><ul><li>a</li></ul>");
+	assert.equal(md(blocks).content, "# t\n\np\n\n- a");
+});
+
+test("templates return a RichDocument that serializes to the right InputRichMessage shape", () => {
+	assert.deepEqual(html`x`.toInputRichMessage(), { html: "x" });
+	assert.deepEqual(md`x`.toInputRichMessage(), { markdown: "x" });
+});
+
+test("RichDocument fluent flags land in the payload, and toJSON() mirrors toInputRichMessage()", () => {
+	const doc = html`x`.rtl().noEntityDetection();
+
+	assert.deepEqual(doc.toInputRichMessage(), {
+		html: "x",
+		is_rtl: true,
+		skip_entity_detection: true,
+	});
+	assert.deepEqual(JSON.parse(JSON.stringify({ rich_message: doc })), {
+		rich_message: { html: "x", is_rtl: true, skip_entity_detection: true },
+	});
+});
+
+test("RichDocument flags are settable to false explicitly", () => {
+	assert.deepEqual(html`x`.rtl(false).toInputRichMessage(), { html: "x", is_rtl: false });
+});
+
+test("document() assembles blocks with options — html by default, markdown on request", () => {
+	assert.deepEqual(document([paragraph("hi")]).toInputRichMessage(), { html: "<p>hi</p>" });
+	assert.deepEqual(
+		document([paragraph("hi")], { dialect: "markdown", rtl: true }).toInputRichMessage(),
+		{
+			markdown: "hi",
+			is_rtl: true,
+		},
+	);
+	assert.deepEqual(document(paragraph("hi"), { skipEntityDetection: true }).toInputRichMessage(), {
+		html: "<p>hi</p>",
+		skip_entity_detection: true,
+	});
+});
+
+test("document() result is a RichDocument, so the fluent setters chain onto it", () => {
+	const doc = document([paragraph("hi")]);
+
+	assert.ok(doc instanceof RichDocument);
+	assert.deepEqual(doc.rtl().toInputRichMessage(), { html: "<p>hi</p>", is_rtl: true });
+});

package/src/template.ts

@@ -0,0 +1,115 @@
+import { RichDocument } from "./document.js";
+import type { Dialect } from "./node.js";
+import { type Insertable, render } from "./render.js";
+
+// strip the common leading indentation shared by the literal skeleton, then trim blank edges.
+function dedent(skeleton: string): string {
+	const rawLines = skeleton.split("\n");
+	let min = Number.POSITIVE_INFINITY;
+
+	for (const line of rawLines) {
+		if (line.trim() === "") continue;
+		const indent = /^[ \t]*/.exec(line)?.[0].length ?? 0;
+		min = Math.min(min, indent);
+	}
+
+	if (!Number.isFinite(min)) min = 0;
+
+	return rawLines
+		.map((line) => line.slice(min))
+		.join("\n")
+		.replace(/^\n+/, "")
+		.trimEnd();
+}
+
+export interface RichTemplate {
+	/** plain-function form: passed through as-is, no escaping/dedent (already-formatted content). */
+	(source: string): RichDocument;
+	/** block-array form: each entry rendered; blocks blank-line-joined in markdown. */
+	(blocks: readonly Insertable[]): RichDocument;
+	/** tagged-template form: dedented, `${}` interpolation escaped/rendered per-item. */
+	(strings: TemplateStringsArray, ...subs: Insertable[]): RichDocument;
+}
+
+// top-level blocks need a blank line between them in markdown; in html the tags
+// carry the structure and separators are just cosmetic whitespace.
+function joinBlocks(blocks: readonly Insertable[], dialect: Dialect): string {
+	const separator = dialect === "markdown" ? "\n\n" : "";
+	return blocks.map((block) => render(block, dialect)).join(separator);
+}
+
+function makeTemplate(dialect: Dialect): RichTemplate {
+	return ((
+		first: string | TemplateStringsArray | readonly Insertable[],
+		...subs: Insertable[]
+	): RichDocument => {
+		if (typeof first === "string") return new RichDocument(dialect, first);
+
+		// a plain array (no `.raw` template marker) composes top-level blocks.
+		if (!("raw" in first)) {
+			return new RichDocument(dialect, joinBlocks(first as readonly Insertable[], dialect));
+		}
+
+		// dedent the literal skeleton only (\x00 marks interpolation seams so values aren't dedented).
+		const seam = String.fromCharCode(0);
+		const dedented = dedent((first as TemplateStringsArray).join(seam)).split(seam);
+
+		let out = "";
+		for (let i = 0; i < dedented.length; i++) {
+			out += dedented[i] ?? "";
+			if (i < subs.length) out += render(subs[i] as Insertable, dialect);
+		}
+
+		return new RichDocument(dialect, out);
+	}) as RichTemplate;
+}
+
+/**
+ * the html authoring entry point — a tagged template whose interpolations are
+ * auto-escaped (never re-parsed as markup); builder nodes render themselves,
+ * a nested `RichDocument` is spliced in raw (dialect-checked). also accepts a
+ * block array (`html([heading(1, t), table(rows)])`) or a plain pre-formatted
+ * string. returns a `RichDocument` — pass it straight to `sendRichMessage`.
+ */
+export const html: RichTemplate = makeTemplate("html");
+
+/**
+ * the markdown authoring entry point — same three forms as `html`, emitting
+ * `InputRichMessage.markdown` instead. the *same* builders work under both tags:
+ * every `RichNode` renders itself into whichever dialect the template asks for.
+ *
+ * @example
+ * md`
+ *   # ${title}
+ *
+ *   ${bold("status:")} ${status}
+ * `
+ */
+export const md: RichTemplate = makeTemplate("markdown");
+
+export interface DocumentOptions {
+	/** target dialect. defaults to `"html"` (the fully documented one). */
+	dialect?: Dialect;
+	/** `InputRichMessage.is_rtl` — show the message right-to-left. */
+	rtl?: boolean;
+	/** `InputRichMessage.skip_entity_detection` — see `RichDocument.noEntityDetection`. */
+	skipEntityDetection?: boolean;
+}
+
+/**
+ * assemble top-level blocks into a `RichDocument` in one call — the options-object
+ * counterpart of `html([...])`/`md([...])` + the fluent flag setters.
+ */
+export function document(
+	blocks: readonly Insertable[] | Insertable,
+	options: DocumentOptions = {},
+): RichDocument {
+	const dialect = options.dialect ?? "html";
+	const entries: readonly Insertable[] = Array.isArray(blocks) ? blocks : [blocks];
+	const doc = new RichDocument(dialect, joinBlocks(entries, dialect));
+
+	if (options.rtl !== undefined) doc.rtl(options.rtl);
+	if (options.skipEntityDetection !== undefined) doc.noEntityDetection(options.skipEntityDetection);
+
+	return doc;
+}

package/lib/message.d.ts

@@ -1,26 +0,0 @@
-import type { InputRichMessage } from "@yaebal/types";
-import type { Insertable } from "./inline.js";
-export interface DocumentOptions {
-    /** `InputRichMessage.is_rtl` — show the message right-to-left. */
-    rtl?: boolean;
-    /**
-     * `InputRichMessage.skip_entity_detection` — turn off auto-detection of urls,
-     * emails, `@mentions`, `#hashtags`, `$cashtags`, `/bot_commands`, and phone
-     * numbers in plain text.
-     */
-    skipEntityDetection?: boolean;
-}
-/**
- * assemble top-level blocks (from blocks.ts) into an `InputRichMessage.html`
- * payload. pass the result straight to `sendRichMessage`/`sendRichMessageDraft`
- * or a `RichMessageDraft`.
- */
-export declare function document(blocks: Insertable[], options?: DocumentOptions): InputRichMessage;
-/**
- * a raw markdown payload — telegram parses `InputRichMessage.markdown` the same
- * way as `html`, but the extended block syntax (tables, `tg-thinking`, …) is not
- * documented in markdown form, so unlike `document()` this has no builder: pass a
- * literal string.
- */
-export declare function markdown(source: string, options?: DocumentOptions): InputRichMessage;
-//# sourceMappingURL=message.d.ts.map

package/lib/message.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,WAAW,eAAe;IAC/B,kEAAkE;IAClE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,OAAO,GAAE,eAAoB,GAAG,gBAAgB,CAQ9F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,gBAAgB,CAQxF"}

package/lib/message.js

@@ -1,31 +0,0 @@
-import { toHtml } from "./inline.js";
-/**
- * assemble top-level blocks (from blocks.ts) into an `InputRichMessage.html`
- * payload. pass the result straight to `sendRichMessage`/`sendRichMessageDraft`
- * or a `RichMessageDraft`.
- */
-export function document(blocks, options = {}) {
-    return {
-        html: blocks.map(toHtml).join(""),
-        ...(options.rtl !== undefined ? { is_rtl: options.rtl } : {}),
-        ...(options.skipEntityDetection !== undefined
-            ? { skip_entity_detection: options.skipEntityDetection }
-            : {}),
-    };
-}
-/**
- * a raw markdown payload — telegram parses `InputRichMessage.markdown` the same
- * way as `html`, but the extended block syntax (tables, `tg-thinking`, …) is not
- * documented in markdown form, so unlike `document()` this has no builder: pass a
- * literal string.
- */
-export function markdown(source, options = {}) {
-    return {
-        markdown: source,
-        ...(options.rtl !== undefined ? { is_rtl: options.rtl } : {}),
-        ...(options.skipEntityDetection !== undefined
-            ? { skip_entity_detection: options.skipEntityDetection }
-            : {}),
-    };
-}
-//# sourceMappingURL=message.js.map

package/lib/message.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"message.js","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAarC;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAoB,EAAE,UAA2B,EAAE;IAC3E,OAAO;QACN,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,OAAO,CAAC,mBAAmB,KAAK,SAAS;YAC5C,CAAC,CAAC,EAAE,qBAAqB,EAAE,OAAO,CAAC,mBAAmB,EAAE;YACxD,CAAC,CAAC,EAAE,CAAC;KACN,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,UAA2B,EAAE;IACrE,OAAO;QACN,QAAQ,EAAE,MAAM;QAChB,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,OAAO,CAAC,mBAAmB,KAAK,SAAS;YAC5C,CAAC,CAAC,EAAE,qBAAqB,EAAE,OAAO,CAAC,mBAAmB,EAAE;YACxD,CAAC,CAAC,EAAE,CAAC;KACN,CAAC;AACH,CAAC"}

package/src/message.ts

@@ -1,45 +0,0 @@
-import type { InputRichMessage } from "@yaebal/types";
-import type { Insertable } from "./inline.js";
-import { toHtml } from "./inline.js";
-
-export interface DocumentOptions {
-	/** `InputRichMessage.is_rtl` — show the message right-to-left. */
-	rtl?: boolean;
-	/**
-	 * `InputRichMessage.skip_entity_detection` — turn off auto-detection of urls,
-	 * emails, `@mentions`, `#hashtags`, `$cashtags`, `/bot_commands`, and phone
-	 * numbers in plain text.
-	 */
-	skipEntityDetection?: boolean;
-}
-
-/**
- * assemble top-level blocks (from blocks.ts) into an `InputRichMessage.html`
- * payload. pass the result straight to `sendRichMessage`/`sendRichMessageDraft`
- * or a `RichMessageDraft`.
- */
-export function document(blocks: Insertable[], options: DocumentOptions = {}): InputRichMessage {
-	return {
-		html: blocks.map(toHtml).join(""),
-		...(options.rtl !== undefined ? { is_rtl: options.rtl } : {}),
-		...(options.skipEntityDetection !== undefined
-			? { skip_entity_detection: options.skipEntityDetection }
-			: {}),
-	};
-}
-
-/**
- * a raw markdown payload — telegram parses `InputRichMessage.markdown` the same
- * way as `html`, but the extended block syntax (tables, `tg-thinking`, …) is not
- * documented in markdown form, so unlike `document()` this has no builder: pass a
- * literal string.
- */
-export function markdown(source: string, options: DocumentOptions = {}): InputRichMessage {
-	return {
-		markdown: source,
-		...(options.rtl !== undefined ? { is_rtl: options.rtl } : {}),
-		...(options.skipEntityDetection !== undefined
-			? { skip_entity_detection: options.skipEntityDetection }
-			: {}),
-	};
-}