A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!
TypeScript agent-skillsaidsh-pluginhacktoberfestjavascriptmcp-serverreactresume-builderself-hostedtypescript
import type { PageSize } from "../forme/primitives";
import type { HostElement, HostNode } from "../forme/reconciler";
import type { Style, StyleProp } from "../forme/style-types";
import { toSafeLink } from "@reactive-resume/utils/link";
import { escapeHtml } from "@reactive-resume/utils/string";
import { HOST } from "../forme/primitives";
import { COLOR_KEYS, flattenStyle, LENGTH_KEYS, toColor, toFormeStyle, toPoints } from "../forme/style";
import { DEFAULT_PAGE, pageDimensions } from "../forme/to-forme";
import { HEADING_NODE_PROP, RESUME_NODE_PROP } from "../page-map";
/**
* Host tree → HTML and CSS, the web page's counterpart of `to-forme.tsx`. Templates draw with react-pdf-style
* primitives; here every `View` becomes a flex column box as in Yoga, text becomes block or inline elements, and the
* page becomes a sheet that narrows with the screen. Styles go through the same vocabulary the PDF accepts, so a
* template looks the same in both, and nothing a resume supplies can reach the stylesheet unchecked.
*/
export type HtmlOutput = {
/** The page sheets, ready to place inside a `.rr` container. */
html: string;
/** Rules for the classes `html` uses, scoped to `.rr`. */
css: string;
};
export type ToHtmlOptions = {
/** Resolves a picture's source to the URL a browser loads; return `undefined` to leave the picture out. */
imageUrl?: ((source: string) => string | undefined) | undefined;
};
type Context = {
fontSize: number;
pageWidth: number;
pageHeight: number;
inText: boolean;
/** Inside the header region's own box: its rows fold too. */
inHeader?: boolean;
imageUrl: (source: string) => string | undefined;
classes: Map<string, string>;
};
const kebab = (property: string) => property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
const round = (value: number) => Math.round(value * 1000) / 1000;
const length = (value: number | string) => (typeof value === "number" ? `${round(value)}pt` : value);
const PERCENT = /^-?\d*\.?\d+%$/;
const SAFE_COLOR = /^(?:#[0-9a-f]{3,8}|rgba?\([\d.\s,]+\))$/i;
/** A colour as CSS, or `undefined`: only the hex and rgb forms `toColor` writes, checked character by character. */
function cssColor(value: unknown) {
const color = toColor(value);
return color && SAFE_COLOR.test(color) ? color : undefined;
}
// Shorthands Forme expands itself; CSS has no `paddingHorizontal`.
const EXPANDED: Record<string, readonly string[]> = {
paddingHorizontal: ["paddingLeft", "paddingRight"],
paddingVertical: ["paddingTop", "paddingBottom"],
marginHorizontal: ["marginLeft", "marginRight"],
marginVertical: ["marginTop", "marginBottom"],
};
const BORDER_STYLES = new Set(["solid", "dashed", "dotted"]);
const OBJECT_FITS = new Set(["contain", "cover", "fill", "none", "scale-down"]);
const BORDER_SHORTHANDS = new Set(["border", "borderTop", "borderRight", "borderBottom", "borderLeft"]);
// What Forme reads that a browser does without: widow and orphan control, line breaking, transforms (rotation is
// already left out of the PDF), and `lang`, which the document sets.
const FORME_ONLY = new Set(["minWidowLines", "minOrphanLines", "lineBreaking", "transform", "transformOrigin", "lang"]);
/** `"1 solid #ccc"` → `1pt solid #ccc`, keeping only widths, solid styles and colours. */
function borderShorthand(value: unknown, context: { fontSize: number }): string | undefined {
if (typeof value === "number") return `${length(value)} solid`;
if (typeof value !== "string") return undefined;
const parts: string[] = [];
for (const token of value.trim().split(/\s+(?![^(]*\))/)) {
const points = toPoints(token, context);
if (typeof points === "number" && Number.isFinite(points)) parts.push(length(points));
else if (BORDER_STYLES.has(token)) parts.push("solid");
else {
const color = cssColor(token);
if (color) parts.push(color);
}
}
if (parts.length === 0) return undefined;
// A border is drawn solid in the PDF whatever style it names; CSS draws nothing without one.
if (!parts.includes("solid")) parts.push("solid");
return parts.join(" ");
}
/** One value `toFormeStyle` produced, as CSS; `undefined` when CSS can't take it. */
function cssValue(key: string, value: unknown, fontSize: number): string | undefined {
if (BORDER_SHORTHANDS.has(key)) return borderShorthand(value, { fontSize });
if (FORME_ONLY.has(key)) return undefined;
if (typeof value === "number") {
if (!Number.isFinite(value)) return undefined;
return key === "fontSize" || LENGTH_KEYS.has(key) ? length(value) : String(round(value));
}
if (typeof value !== "string") return undefined;
if (key === "fontFamily")
return value
.split(",")
.map((family) => `"${family.trim().replace(/["\\<>{};]/g, "")}"`)
.join(", ");
if (COLOR_KEYS.has(key)) return SAFE_COLOR.test(value) ? value : undefined;
if (LENGTH_KEYS.has(key)) {
if (value === "auto") return value;
// Percentages and shorthands with several values ("4 8") stay strings in Forme; every part must be a length.
const parts = value
.split(" ")
.map((part) => (PERCENT.test(part) ? part : part && Number.isFinite(Number(part)) ? length(Number(part)) : ""));
return parts.every(Boolean) ? parts.join(" ") : undefined;
}
if (key === "objectFit") return OBJECT_FITS.has(value) ? value : undefined;
if (key === "textOverflow") return value === "ellipsis" ? value : undefined;
// The rest are keywords `toFormeStyle` checked against what the PDF reads.
return /^[a-z-]+$/.test(value) ? value : undefined;
}
/**
* One flattened style as CSS declarations, through `toFormeStyle`: what the PDF draws, the web page draws; what it
* drops (rotation, grid templates, unknown keys), the web page drops too.
*/
function toCssDeclarations(input: Style, context: Context) {
const source = input as Record<string, unknown>;
const { style, hidden } = toFormeStyle(input, context);
const converted = style as Record<string, unknown>;
const fontSize = typeof converted.fontSize === "number" ? converted.fontSize : context.fontSize;
const declarations: [string, string][] = [];
for (const key of Object.keys(source)) {
const raw = source[key];
// A browser draws percentage corners itself; Forme resolves them against the box's size, or drops them.
const percentCorner =
LENGTH_KEYS.has(key) && key.endsWith("Radius") && typeof raw === "string" && PERCENT.test(raw.trim());
const css = percentCorner ? raw.trim() : cssValue(key, converted[key], fontSize);
if (css === undefined) continue;
// Templates already mirror geometry; direction must reach text without flipping browser flex axes again.
if (key === "direction") {
declarations.push(["--rr-text-direction", css]);
continue;
}
for (const target of EXPANDED[key] ?? [key]) declarations.push([kebab(target), css]);
}
return { declarations, fontSize, hidden };
}
function className(declarations: [string, string][], context: Context): string | undefined {
if (declarations.length === 0) return undefined;
const body = declarations.map(([property, value]) => `${property}:${value}`).join(";");
let name = context.classes.get(body);
if (!name) {
name = `c${context.classes.size}`;
context.classes.set(body, name);
}
return name;
}
/**
* A text box laid out as a row places its runs by `justify-content`, not `text-align`, and its direction orders them:
* a left-to-right sentence on a right-to-left page would sit at the far left, away from its bullet. Its alignment
* becomes the row's, read in the box's own direction.
*/
function alignFlexText(declarations: [string, string][]) {
const value = (property: string) => declarations.findLast(([name]) => name === property)?.[1];
if (value("display") !== "flex" || value("justify-content") !== undefined) return;
if (!["row", "row-reverse", undefined].includes(value("flex-direction"))) return;
const align = value("text-align");
if (align !== "left" && align !== "right" && align !== "center") return;
const rtl = value("--rr-text-direction") === "rtl";
const reversed = value("flex-direction") === "row-reverse";
// Right in a left-to-right row is its end; a right-to-left or reversed row flips that once each.
const flips = [align === "right", rtl, reversed].filter(Boolean).length;
const end = flips % 2 === 1;
declarations.push(["justify-content", align === "center" ? "center" : end ? "flex-end" : "flex-start"]);
}
const isText = (node: HostNode) => "text" in node || node.type === HOST.text || node.type === HOST.link;
const isEmptyText = (node: HostNode): boolean =>
"text" in node
? node.text.length === 0
: (node.type === HOST.text || node.type === HOST.link) && node.children.every(isEmptyText);
/** A text's runs without the line breaks that end it; a browser would draw an empty line for each. */
function withoutTrailingBreaks(nodes: HostNode[]): HostNode[] {
const last = nodes.at(-1);
if (!last) return nodes;
if ("text" in last) {
const text = last.text.replace(/\n+$/, "");
if (text === last.text) return nodes;
return text ? [...nodes.slice(0, -1), { ...last, text }] : withoutTrailingBreaks(nodes.slice(0, -1));
}
if (last.type !== HOST.text && last.type !== HOST.link) return nodes;
const children = withoutTrailingBreaks(last.children);
if (children === last.children) return nodes;
if (children.length === 0) return withoutTrailingBreaks(nodes.slice(0, -1));
return [...nodes.slice(0, -1), { ...last, children }];
}
const nodeKey = (element: HostElement): string | undefined => {
const key = element.props[RESUME_NODE_PROP];
return typeof key === "string" && key.length > 0 ? key : undefined;
};
const REGIONS = new Set(["main", "sidebar", "header"]);
/** Which part of the layout a box holds, as `SemanticRegionView` and `SemanticHeaderView` mark it. */
const regionOf = (element: HostElement) => {
const region = element.props["data-region"];
return typeof region === "string" && REGIONS.has(region) ? region : undefined;
};
/** The element a semantic node is best written as: the name is the page's heading, section titles its subheadings. */
function semanticTag(element: HostElement, block: boolean): { tag: string; attributes: string } | undefined {
const heading = element.props[HEADING_NODE_PROP];
const key = (typeof heading === "string" ? heading : nodeKey(element)) ?? "";
if (key.endsWith("/header/name")) return block ? { tag: "h1", attributes: "" } : undefined;
if (key.endsWith("/section-heading"))
return block && element.children.every(isText)
? { tag: "h2", attributes: "" }
: { tag: "div", attributes: ' role="heading" aria-level="2"' };
if (/\/section-[^/]+$/.test(key) && !key.endsWith("/section-items")) return { tag: "section", attributes: "" };
return undefined;
}
const attributes = (classes: (string | undefined)[], extra = "") => {
const list = classes.filter(Boolean).join(" ");
return `${list ? ` class="${list}"` : ""}${extra}`;
};
/** The regions a box holds, itself included. */
const regionsCache = new WeakMap<HostElement, ReadonlySet<string>>();
function regionsIn(element: HostElement): ReadonlySet<string> {
let regions = regionsCache.get(element);
if (!regions) {
const found = new Set<string>();
const own = regionOf(element);
if (own) found.add(own);
for (const child of element.children)
if (!("text" in child)) for (const region of regionsIn(child)) found.add(region);
regions = found;
regionsCache.set(element, regions);
}
return regions;
}
/** Whether a box holds a picture or a section: what makes a header row worth stacking on a phone. */
function holdsBlocks(element: HostElement): boolean {
return element.children.some(
(child) =>
!("text" in child) &&
(child.type === HOST.image || /\/section-[^/]+$/.test(nodeKey(child) ?? "") || holdsBlocks(child)),
);
}
type Part = "main" | "sidebar" | "header-sidebar";
/**
* Where a box's children sit when the columns fold: the box that splits the main column from the sidebar gets its
* children marked, so a phone stacks them header, main, sidebar, however deep each template nests its columns.
*/
function splitParts(element: HostElement): Map<HostNode, Part> | undefined {
const parts = new Map<HostNode, Part>();
for (const child of element.children) {
if ("text" in child) continue;
const regions = regionsIn(child);
if (regions.has("main")) parts.set(child, "main");
else if (regions.has("sidebar")) parts.set(child, regions.has("header") ? "header-sidebar" : "sidebar");
}
const values = [...parts.values()];
return values.includes("main") && values.some((part) => part !== "main") ? parts : undefined;
}
function convertSplitChildren(children: HostNode[], parts: Map<HostNode, Part> | undefined, context: Context) {
return children
.map((child) => {
const html = convertNode(child, context);
const part = parts?.get(child);
// The part rides on the child's opening tag.
return part ? html.replace(/^<([a-z0-9]+)/, `<$1 data-part="${part}"`) : html;
})
.join("");
}
function styleOf(element: HostElement, context: Context) {
const flat = flattenStyle(element.props.style as StyleProp);
return { ...toCssDeclarations(flat, context), flat: flat as Record<string, unknown> };
}
function convertNode(node: HostNode, parent: Context): string {
if ("text" in node) return escapeHtml(node.text).replaceAll("\n", "<br>");
const { props } = node;
switch (node.type) {
case HOST.view: {
const { declarations, fontSize, hidden, flat } = styleOf(node, parent);
if (hidden) return "";
const context = { ...parent, fontSize };
const region = regionOf(node);
const split = splitParts(node);
const semantic = semanticTag(node, false);
const tag = semantic?.tag ?? "div";
// A row in the header that holds the picture or a section (picture beside the name and summary), or a section
// laid out as a row (a label gutter beside the entries), is too narrow on a phone: it stacks there instead.
// Small rows, such as an icon beside a contact detail, stay rows.
const direction = flat.flexDirection;
const isRow = direction === "row" || direction === "row-reverse";
const inHeader = region === "header" || parent.inHeader === true;
const fold = isRow && !split && (tag === "section" || (inHeader && holdsBlocks(node)));
// A box that paints its own band (Pikachu's coloured header) spans a folded row instead of hugging its text.
const fill =
typeof flat.backgroundColor === "string" &&
!/^(transparent|none|rgba\([^)]*,\s*0\))$/i.test(flat.backgroundColor);
const extra = [
semantic?.attributes ?? "",
region ? ` data-region="${region}"` : "",
split ? " data-split" : "",
fold ? " data-fold" : "",
fill ? " data-fill" : "",
props.fixed === true ? " data-fixed" : "",
].join("");
const inner = { ...context, inHeader };
return `<${tag}${attributes(["v", className(declarations, context)], extra)}>${convertSplitChildren(node.children, split, inner)}</${tag}>`;
}
case HOST.text:
case HOST.link: {
const { declarations, fontSize, hidden } = styleOf(node, parent);
if (hidden) return "";
alignFlexText(declarations);
const context = { ...parent, fontSize };
const href =
node.type === HOST.link && typeof props.src === "string" ? (toSafeLink(props.src) ?? undefined) : undefined;
const external = href && /^https?:/i.test(href) ? ' rel="noopener ugc" target="_blank"' : "";
const link = href ? ` href="${escapeHtml(href)}"${external}` : "";
const own = className(declarations, context);
if (parent.inText) {
const tag = href ? "a" : "span";
return `<${tag}${attributes([own], link)}>${node.children.map((child) => convertNode(child, context)).join("")}</${tag}>`;
}
if (node.children.every(isEmptyText)) return `<div${attributes(["t", own])}></div>`;
// Text around views (a whole entry in a link) becomes a box: inline runs between the views share a line box.
const hasBlockChild = node.children.some((child) => !isText(child));
if (hasBlockChild) {
const parts: string[] = [];
let inline: HostNode[] = [];
const flush = () => {
const runs = withoutTrailingBreaks(inline);
if (runs.length > 0)
parts.push(
`<div class="t">${runs.map((child) => convertNode(child, { ...context, inText: true })).join("")}</div>`,
);
inline = [];
};
for (const child of node.children) {
if (isText(child)) inline.push(child);
else {
flush();
parts.push(convertNode(child, context));
}
}
flush();
const tag = href ? "a" : "div";
return `<${tag}${attributes(["v", own], link)}>${parts.join("")}</${tag}>`;
}
const semantic = semanticTag(node, true);
const tag = href ? "a" : (semantic?.tag ?? "div");
const inner = withoutTrailingBreaks(node.children)
.map((child) => convertNode(child, { ...context, inText: true }))
.join("");
return `<${tag}${attributes(["t", own], link || (semantic?.attributes ?? ""))}>${inner}</${tag}>`;
}
case HOST.image: {
const source = typeof props.src === "string" ? props.src.trim() : "";
const url = source ? parent.imageUrl(source) : undefined;
if (!url) return "";
const { declarations, hidden } = styleOf(node, parent);
if (hidden) return "";
return `<img${attributes(["i", className(declarations, parent)], ` src="${escapeHtml(url)}" alt="" loading="lazy" decoding="async"`)}>`;
}
case HOST.svg: {
const { declarations, hidden } = styleOf(node, parent);
if (hidden) return "";
const size = (value: unknown, fallback: number) => {
const points = toPoints(value, parent);
return typeof points === "number" ? points : fallback;
};
const width = size(props.width, 12);
const height = size(props.height, width);
const opacity: [string, string][] =
typeof props.opacity === "number" && Number.isFinite(props.opacity) ? [["opacity", String(props.opacity)]] : [];
const viewBox = typeof props.viewBox === "string" ? ` viewBox="${escapeHtml(props.viewBox)}"` : "";
const own = className(
[...declarations, ["width", length(width)], ["height", length(height)], ...opacity],
parent,
);
// The drawing is one of the app's own icons (`forme/icons.tsx`), never resume content.
return `<svg${attributes(["s", own], `${viewBox} aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"`)}>${String(props.content ?? "")}</svg>`;
}
default:
return "";
}
}
/** The colour of a page's sidebar band, drawn behind the sidebar when it folds under the main column on phones. */
function bandColor(page: HostElement): string | undefined {
for (const child of page.children) {
if ("text" in child || child.type !== HOST.view || child.props.fixed !== true) continue;
const style = flattenStyle(child.props.style as StyleProp) as Record<string, unknown>;
if (style.position !== "absolute" || typeof style.width !== "string" || !style.width.endsWith("%")) continue;
const color = cssColor(style.backgroundColor);
if (color) return color;
}
return undefined;
}
/**
* The base rules every web page uses: Yoga's box model, the sheet, and how the layout folds on narrow screens. A folded
* part never grows but may still shrink: a header that sits in a row (Pikachu's) narrows to the phone, so its contact
* line wraps instead of running off the screen.
*/
const BASE_CSS = `
.rr,.rr *{box-sizing:border-box;margin:0;padding:0;border:0 solid}
.rr .v{display:flex;flex-direction:column;direction:ltr;position:relative;min-width:0;align-content:flex-start}
.rr .t{display:block;min-width:0;overflow-wrap:break-word}
.rr .t,.rr .t span,.rr .t a{direction:var(--rr-text-direction,ltr)}
.rr a{color:inherit;text-decoration:none}
.rr h1,.rr h2{font:inherit}
.rr .s,.rr .i{flex-shrink:0;display:block}
.rr .rr-page{position:relative;width:100%;margin:0 auto;background:#fff;overflow:hidden}
@media (max-width:640px){
.rr .rr-page{min-height:0!important;padding:24px 20px!important}
.rr [data-split]{flex-direction:column!important;row-gap:20px!important}
.rr [data-split]>*,.rr [data-region]{width:auto!important;max-width:none!important;flex:0 1 auto!important}
.rr [data-part=main]{order:1}
.rr [data-part=sidebar]{order:2}
.rr [data-part=header-sidebar]{display:contents!important}
.rr [data-part=header-sidebar]>*{order:2}
.rr [data-part=header-sidebar]>[data-region=header]{order:0}
.rr [data-region=sidebar]{background-color:var(--rr-band,transparent)}
.rr [data-fold]{flex-direction:column!important;align-items:flex-start!important;row-gap:8px}
.rr:dir(rtl) [data-fold]{align-items:flex-end!important}
.rr [data-fold]>*{width:auto!important;max-width:100%!important;flex:none!important}
.rr [data-fold]>[data-fill]{align-self:stretch!important}
.rr [data-region][data-fill]{flex-grow:1!important}
.rr [data-fixed]{display:none!important}
}
`;
/** Converts a host tree rendered from a `ResumeDocument` to the web page's markup. */
export function toHtml(tree: HostNode[], options: ToHtmlOptions = {}): HtmlOutput {
const root = tree.find((node): node is HostElement => !("text" in node) && node.type === HOST.document);
if (!root) throw new Error("The resume didn't render a <Document>.");
const context: Context = {
fontSize: 12,
pageWidth: DEFAULT_PAGE.width,
pageHeight: DEFAULT_PAGE.height,
inText: false,
imageUrl: options.imageUrl ?? ((source) => (/^(https?:|data:image\/)/i.test(source) ? source : undefined)),
classes: new Map(),
};
const pages = root.children
.filter((child): child is HostElement => !("text" in child) && child.type === HOST.page)
.map((page) => {
// `toWebLayout` asks for A4 or Letter; a free-form page would take A4's height as its minimum.
const dimensions = pageDimensions(page.props.size as PageSize | undefined, DEFAULT_PAGE.height);
const pageContext = { ...context, pageWidth: dimensions.width, pageHeight: dimensions.height };
const { declarations, fontSize } = styleOf(page, pageContext);
const band = bandColor(page);
const sheet = className(
[
...declarations.filter(([property]) => property !== "width" && property !== "height"),
["max-width", length(dimensions.width)],
["min-height", length(dimensions.height)],
...(band ? ([["--rr-band", band]] as [string, string][]) : []),
],
pageContext,
);
const split = splitParts(page);
const children = convertSplitChildren(page.children, split, { ...pageContext, fontSize });
return `<div${attributes(["rr-page", "v", sheet], split ? " data-split" : "")}>${children}</div>`;
});
const rules = [...context.classes].map(([body, name]) => `.rr .${name}{${body}}`).join("\n");
return { html: pages.join(""), css: `${BASE_CSS}${rules}\n` };
}