Skip to content

Code-first video & image, rendered natively on WebGPU.

8.7 KB
Raw Blame
import type { Signal, TextSpan, TextSpanMark } from "@framefields/core";

export type { TextSpan, TextSpanMark };

export type TextSpanItem =
	| string
	| number
	| boolean
	| Signal<unknown>
	| TextSpan
	| (string | TextSpan)[]
	| null
	| undefined;

/**
 * Tagged template literal for authoring rich, multi-style text runs.
 *
 * Interpolates strings, numbers, reactive signals, and typed span modifiers
 * directly into a structured TextSpan[] array with zero runtime parsing.
 *
 * @example
 * rich`Scale ${bold("10x", { fill: "#6366f1" })} faster with ${mark("120 FPS", { bg: "#10b98133" })}`
 */
export function rich(
	strings: TemplateStringsArray,
	...values: TextSpanItem[]
): TextSpan[] {
	const spans: TextSpan[] = [];

	for (let i = 0; i < strings.length; i++) {
		const str = strings[i];
		if (str) {
			spans.push({ text: str });
		}

		if (i < values.length) {
			const val = values[i];
			if (val === null || val === undefined) {
				continue;
			}

			if (Array.isArray(val)) {
				for (const item of val) {
					if (typeof item === "string") {
						if (item) spans.push({ text: item });
					} else if (item && typeof item === "object" && "text" in item) {
						spans.push(item as TextSpan);
					}
				}
			} else if (typeof val === "object" && "text" in val) {
				spans.push(val as TextSpan);
			} else if (
				typeof val === "object" &&
				"get" in val &&
				typeof (val as { get: unknown }).get === "function"
			) {
				spans.push({ text: val as Signal<string> });
			} else {
				spans.push({ text: String(val) });
			}
		}
	}

	return spans;
}

export function span(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return { text, ...options };
}

export function bold(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return { text, fontWeight: options.fontWeight ?? 700, ...options };
}

export function italic(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return { text, fontStyle: "italic", ...options };
}

export function accent(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return { text, fill: options.fill ?? "#6366f1", ...options };
}

export function color(
	text: string | Signal<string>,
	fill: string | Signal<string>,
	options: Omit<TextSpan, "text" | "fill"> = {},
): TextSpan {
	return { text, fill, ...options };
}

export function size(
	text: string | Signal<string>,
	fontSize: number | Signal<number>,
	options: Omit<TextSpan, "text" | "fontSize"> = {},
): TextSpan {
	return { text, fontSize, ...options };
}

export interface MarkOptions extends Omit<TextSpan, "text" | "mark" | "fill"> {
	bg?: string | Signal<string>;
	fill?: string | Signal<string>;
	radius?: number;
	paddingX?: number;
	paddingY?: number;
}

export function mark(
	text: string | Signal<string>,
	options: MarkOptions = {},
): TextSpan {
	const { bg, fill, radius, paddingX, paddingY, ...rest } = options;
	return {
		text,
		fill,
		mark: {
			background: bg ?? "#6366f133",
			borderRadius: radius ?? 4,
			paddingX: paddingX ?? 6,
			paddingY: paddingY ?? 2,
		},
		...rest,
	};
}

export function sup(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return {
		text,
		baselineShift: options.baselineShift ?? -8,
		...options,
	};
}

export function sub(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return {
		text,
		baselineShift: options.baselineShift ?? 6,
		...options,
	};
}

export function code(
	text: string | Signal<string>,
	options: Omit<TextSpan, "text"> = {},
): TextSpan {
	return {
		text,
		fontFamily: options.fontFamily ?? "JetBrains Mono",
		mark: options.mark ?? {
			background: "#ffffff18",
			borderRadius: 4,
			paddingX: 6,
			paddingY: 2,
		},
		...options,
	};
}

/**
 * Normalizes string, TextSpan[], or array of mixed strings/spans into plain text and spans.
 */
export function normalizeTextSpans(
	input: string | TextSpan[] | (string | TextSpan)[],
): { text: string; spans?: TextSpan[] } {
	if (typeof input === "string") {
		return { text: input };
	}

	if (!Array.isArray(input)) {
		return { text: String(input) };
	}

	const spans: TextSpan[] = [];
	let plainText = "";

	for (const item of input) {
		if (typeof item === "string") {
			if (item) {
				spans.push({ text: item });
				plainText += item;
			}
		} else if (item && typeof item === "object" && "text" in item) {
			const s = item as TextSpan;
			spans.push(s);
			const piece =
				typeof s.text === "string"
					? s.text
					: s.text &&
							typeof s.text === "object" &&
							"get" in s.text &&
							typeof (s.text as { get: () => unknown }).get === "function"
						? String((s.text as { get: () => unknown }).get())
						: String(s.text ?? "");
			plainText += piece;
		}
	}

	return {
		text: plainText,
		spans: spans.length > 0 ? spans : undefined,
	};
}

/**
 * Upfront parser for external CMS or subtitle strings containing basic tags
 * (<b>, <i>, <span>, <color>, <mark>, <accent>, <code>, <sup>, <sub>).
 *
 * Compiles string markup into clean TextSpan[] before entering the composition pipeline.
 */
export function parseMarkup(markup: string): TextSpan[] {
	if (!markup || !markup.includes("<")) {
		return [{ text: markup }];
	}

	const spans: TextSpan[] = [];
	const tagRegex = /<(\/?[a-zA-Z0-9_-]+)([^>]*)>/g;
	let lastIndex = 0;

	interface StyleState {
		tag: string;
		style: Partial<TextSpan>;
	}
	const stack: StyleState[] = [];

	const getCurrentStyle = (): Partial<TextSpan> => {
		const merged: Partial<TextSpan> = {};
		for (const state of stack) {
			Object.assign(merged, state.style);
		}
		return merged;
	};

	for (;;) {
		const match = tagRegex.exec(markup);
		if (!match) {
			break;
		}
		const textBefore = markup.slice(lastIndex, match.index);
		if (textBefore) {
			spans.push({ text: textBefore, ...getCurrentStyle() });
		}
		lastIndex = match.index + match[0].length;

		const tagName = match[1].toLowerCase();
		const rawAttrs = match[2];

		if (tagName.startsWith("/")) {
			const closingTag = tagName.slice(1);
			for (let i = stack.length - 1; i >= 0; i--) {
				if (stack[i].tag === closingTag) {
					stack.splice(i, 1);
					break;
				}
			}
		} else {
			const attrs: Record<string, string> = {};
			const attrRegex = /([a-zA-Z0-9_-]+)=["']([^"']*)["']/g;
			for (;;) {
				const attrMatch = attrRegex.exec(rawAttrs);
				if (!attrMatch) {
					break;
				}
				attrs[attrMatch[1].toLowerCase()] = attrMatch[2];
			}

			const style: Partial<TextSpan> = {};

			if (tagName === "b" || tagName === "strong") {
				style.fontWeight = 700;
				if (attrs.color || attrs.fill) style.fill = attrs.color ?? attrs.fill;
			} else if (tagName === "i" || tagName === "em") {
				style.fontStyle = "italic";
				if (attrs.color || attrs.fill) style.fill = attrs.color ?? attrs.fill;
			} else if (tagName === "accent") {
				style.fill = "#6366f1";
			} else if (tagName === "color") {
				style.fill = attrs.value ?? attrs.hex ?? attrs.fill;
			} else if (tagName === "size") {
				const num = parseFloat(attrs.value ?? attrs.px ?? attrs.pt ?? "0");
				if (num > 0) style.fontSize = num;
			} else if (tagName === "mark") {
				style.mark = {
					background: attrs.bg ?? attrs.background ?? "#6366f133",
					borderRadius: attrs.radius ? parseFloat(attrs.radius) : 4,
					paddingX: attrs.paddingx ? parseFloat(attrs.paddingx) : 6,
					paddingY: attrs.paddingy ? parseFloat(attrs.paddingy) : 2,
				};
				if (attrs.color || attrs.fill) style.fill = attrs.color ?? attrs.fill;
			} else if (tagName === "sup") {
				style.baselineShift = -8;
			} else if (tagName === "sub") {
				style.baselineShift = 6;
			} else if (tagName === "code") {
				style.fontFamily = "JetBrains Mono";
				style.mark = {
					background: attrs.bg ?? "#ffffff18",
					borderRadius: 4,
					paddingX: 6,
					paddingY: 2,
				};
			} else if (tagName === "span") {
				if (attrs.color || attrs.fill) style.fill = attrs.color ?? attrs.fill;
				if (attrs.fontfamily) style.fontFamily = attrs.fontfamily;
				if (attrs.fontsize) style.fontSize = parseFloat(attrs.fontsize);
				if (attrs.fontweight) {
					const nw = parseInt(attrs.fontweight, 10);
					style.fontWeight = Number.isNaN(nw) ? attrs.fontweight : nw;
				}
				if (attrs.fontstyle === "italic" || attrs.fontstyle === "normal") {
					style.fontStyle = attrs.fontstyle;
				}
				if (attrs.letterspacing)
					style.letterSpacing = parseFloat(attrs.letterspacing);
				if (attrs.baselineshift)
					style.baselineShift = parseFloat(attrs.baselineshift);
				if (attrs.opacity) style.opacity = parseFloat(attrs.opacity);
			}

			stack.push({ tag: tagName, style });
		}
	}

	const remainingText = markup.slice(lastIndex);
	if (remainingText) {
		spans.push({ text: remainingText, ...getCurrentStyle() });
	}

	return spans;
}