| ... | ... | @@ -0,0 +1,300 @@ |
| 1 | // Clover's Rendering Engine is the backbone of her website generator. It
|
| 2 | // converts objects and components (functions returning 'Node') into HTML. The
|
| 3 | // engine is simple and self-contained, with integrations for JSX and Marko
|
| 4 | // (which can interop with each-other) are provided next to this file.
|
| 5 | //
|
| 6 | // Add-ons to the rendering engine can provide opaque data, And retrieve it
|
| 7 | // within component calls with 'getAddonData'. For example, 'sitegen' uses this
|
| 8 | // to track needed client scripts without introducing patches to the engine.
|
| 9 |
|
| 10 | type AddonData = Record<string | symbol, unknown>;
|
| 11 | export function ssrSync(node: Node): Result;
|
| 12 | export function ssrSync<A extends AddonData>(
|
| 13 | node: Node,
|
| 14 | addon: AddonData,
|
| 15 | ): Result<A>;
|
| 16 | export function ssrSync(node: Node, addon: AddonData = {}) {
|
| 17 | const r = initRender(false, addon);
|
| 18 | const resolved = resolveNode(r, node);
|
| 19 | return { text: renderNode(resolved), addon };
|
| 20 | }
|
| 21 | export function ssrAsync(node: Node): Promise<Result>;
|
| 22 | export function ssrAsync<A extends AddonData>(
|
| 23 | node: Node,
|
| 24 | addon: AddonData,
|
| 25 | ): Promise<Result<A>>;
|
| 26 | export function ssrAsync(node: Node, addon: AddonData = {}) {
|
| 27 | const r = initRender(true, addon);
|
| 28 | const resolved = resolveNode(r, node);
|
| 29 | if (r.async === 0) {
|
| 30 | return Promise.resolve({ text: renderNode(resolved), addon });
|
| 31 | }
|
| 32 | const { resolve, reject, promise } = Promise.withResolvers<Result>();
|
| 33 | r.asyncDone = () => {
|
| 34 | const rejections = r.rejections;
|
| 35 | if (!rejections) return resolve({ text: renderNode(resolved), addon });
|
| 36 | if (rejections.length === 1) return reject(rejections[0]);
|
| 37 | return reject(new AggregateError(rejections));
|
| 38 | };
|
| 39 | return promise;
|
| 40 | }
|
| 41 |
|
| 42 | /** Inline HTML into a render without escaping it */
|
| 43 | export function html(rawText: string) {
|
| 44 | return [kDirectHtml, rawText];
|
| 45 | }
|
| 46 |
|
| 47 | interface Result<A extends AddonData = AddonData> {
|
| 48 | text: string;
|
| 49 | addon: A;
|
| 50 | }
|
| 51 |
|
| 52 | export interface Render {
|
| 53 | /**
|
| 54 | * Set to '-1' if rendering synchronously
|
| 55 | * Number of async promises the render is waiting on.
|
| 56 | */
|
| 57 | async: number | -1;
|
| 58 | asyncDone: null | (() => void);
|
| 59 | /** When components reject, those are logged here */
|
| 60 | rejections: unknown[] | null;
|
| 61 | /** Add-ons to the rendering engine store state here */
|
| 62 | addon: AddonData;
|
| 63 | }
|
| 64 |
|
| 65 | export const kElement = Symbol("Element");
|
| 66 | export const kDirectHtml = Symbol("DirectHtml");
|
| 67 |
|
| 68 | /** Node represents a webpage that can be 'rendered' into HTML. */
|
| 69 | export type Node =
|
| 70 | | number
|
| 71 | | string // Escape HTML
|
| 72 | | Node[] // Concat
|
| 73 | | Element // Render
|
| 74 | | DirectHtml // Insert
|
| 75 | | Promise<Node> // Await
|
| 76 | // Ignore
|
| 77 | | undefined
|
| 78 | | null
|
| 79 | | boolean;
|
| 80 | export type Element = [
|
| 81 | tag: typeof kElement,
|
| 82 | type: string | Component,
|
| 83 | props: Record<string, unknown>,
|
| 84 | ];
|
| 85 | export type DirectHtml = [tag: typeof kDirectHtml, html: string];
|
| 86 | /**
|
| 87 | * Components must return a value; 'undefined' is prohibited here
|
| 88 | * to avoid functions that are missing a return statement.
|
| 89 | */
|
| 90 | export type Component = (
|
| 91 | props: Record<string, unknown>,
|
| 92 | ) => Exclude<Node, undefined>;
|
| 93 |
|
| 94 | /**
|
| 95 | * Resolution narrows the type 'Node' into 'ResolvedNode'. Async trees are
|
| 96 | * marked in the 'Render'. This operation performs everything besides the final
|
| 97 | * string concatenation. This function is agnostic across async/sync modes.
|
| 98 | */
|
| 99 | export function resolveNode(r: Render, node: unknown): ResolvedNode {
|
| 100 | if (!node && node !== 0) return ""; // falsy, non numeric
|
| 101 | if (typeof node !== "object") {
|
| 102 | if (node === true) return ""; // booleans are ignored
|
| 103 | if (typeof node === "string") return escapeHTML(node);
|
| 104 | if (typeof node === "number") return String(node); // no escaping ever
|
| 105 | throw new Error(`Cannot render ${inspect(node)} to HTML`);
|
| 106 | }
|
| 107 | if (node instanceof Promise) {
|
| 108 | if (r.async === -1) {
|
| 109 | throw new Error(`Asynchronous rendering is not supported here.`);
|
| 110 | }
|
| 111 | const placeholder: InsertionPoint = [null];
|
| 112 | r.async += 1;
|
| 113 | node
|
| 114 | .then((result) => void (placeholder[0] = resolveNode(r, result)))
|
| 115 | // Intentionally catching errors in `resolveNode`
|
| 116 | .catch((e) => (r.rejections ??= []).push(e))
|
| 117 | .finally(() => {
|
| 118 | if (--r.async == 0) {
|
| 119 | if (r.asyncDone == null) throw new Error("r.asyncDone == null");
|
| 120 | r.asyncDone();
|
| 121 | r.asyncDone = null;
|
| 122 | }
|
| 123 | });
|
| 124 | // This lie is checked with an assertion in `renderNode`
|
| 125 | return placeholder as [ResolvedNode];
|
| 126 | }
|
| 127 | if (!Array.isArray(node)) {
|
| 128 | throw new Error(`Invalid node type: ${inspect(node)}`);
|
| 129 | }
|
| 130 | const type = node[0];
|
| 131 | if (type === kElement) {
|
| 132 | const { 1: tag, 2: props } = node;
|
| 133 | if (typeof tag === "function") {
|
| 134 | currentRender = r;
|
| 135 | const result = tag(props);
|
| 136 | currentRender = null;
|
| 137 | return resolveNode(r, result);
|
| 138 | }
|
| 139 | if (typeof tag !== "string") throw new Error("Unexpected " + typeof type);
|
| 140 | const children = props?.children;
|
| 141 | if (children) return [kElement, tag, props, resolveNode(r, children)];
|
| 142 | return node;
|
| 143 | }
|
| 144 | if (type === kDirectHtml) return node[1];
|
| 145 | return node.map((elem) => resolveNode(r, elem));
|
| 146 | }
|
| 147 |
|
| 148 | export type ResolvedNode =
|
| 149 | | ResolvedNode[] // Concat
|
| 150 | | ResolvedElement // Render
|
| 151 | | string; // Direct HTML
|
| 152 | export type ResolvedElement = [
|
| 153 | tag: typeof kElement,
|
| 154 | type: string,
|
| 155 | props: Record<string, unknown>,
|
| 156 | children: ResolvedNode,
|
| 157 | ];
|
| 158 | /**
|
| 159 | * Async rendering is done by creating an array of one item,
|
| 160 | * which is already a valid 'Node', but the element is written
|
| 161 | * once the data is available. The 'Render' contains a count
|
| 162 | * of how many async jobs are left.
|
| 163 | */
|
| 164 | export type InsertionPoint = [null | ResolvedNode];
|
| 165 |
|
| 166 | /**
|
| 167 | * Convert 'ResolvedNode' into HTML text. This operation happens after all
|
| 168 | * async work is settled. The HTML is emitted as concisely as possible.
|
| 169 | */
|
| 170 | export function renderNode(node: ResolvedNode): string {
|
| 171 | if (typeof node === "string") return node;
|
| 172 | ASSERT(node, "Unresolved Render Node");
|
| 173 | const type = node[0];
|
| 174 | if (type === kElement) {
|
| 175 | return renderElement(node as ResolvedElement);
|
| 176 | }
|
| 177 | node = node as ResolvedNode[]; // TS cannot infer.
|
| 178 | let out = type ? renderNode(type) : "";
|
| 179 | let len = node.length;
|
| 180 | for (let i = 1; i < len; i++) {
|
| 181 | const elem = node[i];
|
| 182 | if (elem) out += renderNode(elem);
|
| 183 | }
|
| 184 | return out;
|
| 185 | }
|
| 186 | function renderElement(element: ResolvedElement) {
|
| 187 | const { 1: tag, 2: props, 3: children } = element;
|
| 188 | let out = "<" + tag;
|
| 189 | let needSpace = true;
|
| 190 | for (const prop in props) {
|
| 191 | const value = props[prop];
|
| 192 | if (!value || typeof value === "function") continue;
|
| 193 | let attr;
|
| 194 | switch (prop) {
|
| 195 | default:
|
| 196 | attr = `${prop}=${quoteIfNeeded(escapeHTML(String(value)))}`;
|
| 197 | break;
|
| 198 | case "className":
|
| 199 | // Legacy React Compat
|
| 200 | case "class":
|
| 201 | attr = `class=${quoteIfNeeded(escapeHTML(clsx(value)))}`;
|
| 202 | break;
|
| 203 | case "htmlFor":
|
| 204 | throw new Error("Do not use the `htmlFor` attribute. Use `for`");
|
| 205 | // Do not process these
|
| 206 | case "children":
|
| 207 | case "ref":
|
| 208 | case "dangerouslySetInnerHTML":
|
| 209 | case "key":
|
| 210 | continue;
|
| 211 | }
|
| 212 | if (needSpace) out += " ", needSpace = !attr.endsWith('"');
|
| 213 | out += attr;
|
| 214 | }
|
| 215 | out += ">";
|
| 216 | if (children) out += renderNode(children);
|
| 217 | if (
|
| 218 | tag !== "br" && tag !== "img" && tag !== "input" && tag !== "meta" &&
|
| 219 | tag !== "link" && tag !== "hr"
|
| 220 | ) {
|
| 221 | out += `</${tag}>`;
|
| 222 | }
|
| 223 | return out;
|
| 224 | }
|
| 225 | export function renderStyleAttribute(style: Record<string, string>) {
|
| 226 | let out = ``;
|
| 227 | for (const styleName in style) {
|
| 228 | if (out) out += ";";
|
| 229 | out += `${styleName.replace(/[A-Z]/g, "-$&").toLowerCase()}:${
|
| 230 | escapeHTML(String(style[styleName]))
|
| 231 | }`;
|
| 232 | }
|
| 233 | return "style=" + quoteIfNeeded(out);
|
| 234 | }
|
| 235 | export function quoteIfNeeded(text) {
|
| 236 | if (text.includes(" ")) return '"' + text + '"';
|
| 237 | return text;
|
| 238 | }
|
| 239 |
|
| 240 | // -- utility functions --
|
| 241 |
|
| 242 | export function initRender(allowAsync: boolean, addon: AddonData): Render {
|
| 243 | return {
|
| 244 | async: allowAsync ? 0 : -1,
|
| 245 | rejections: null,
|
| 246 | asyncDone: null,
|
| 247 | addon,
|
| 248 | };
|
| 249 | }
|
| 250 |
|
| 251 | let currentRender: Render | null = null;
|
| 252 | export function getCurrentRender() {
|
| 253 | if (!currentRender) throw new Error("No Render Active");
|
| 254 | return currentRender;
|
| 255 | }
|
| 256 | export function setCurrentRender(r?: Render | null) {
|
| 257 | currentRender = r ?? null;
|
| 258 | }
|
| 259 | export function getUserData<T>(namespace: PropertyKey, def: () => T): T {
|
| 260 | return (getCurrentRender().addon[namespace] ??= def()) as T;
|
| 261 | }
|
| 262 |
|
| 263 | export function inspect(object: unknown) {
|
| 264 | try {
|
| 265 | return require("node:util").inspect(object);
|
| 266 | } catch {
|
| 267 | return typeof object;
|
| 268 | }
|
| 269 | }
|
| 270 |
|
| 271 | export type ClsxInput = string | Record<string, boolean | null> | ClsxInput[];
|
| 272 | export function clsx(mix: ClsxInput) {
|
| 273 | var k, y, str;
|
| 274 | if (typeof mix === "string") {
|
| 275 | return mix;
|
| 276 | } else if (typeof mix === "object") {
|
| 277 | str = "";
|
| 278 | if (Array.isArray(mix)) {
|
| 279 | for (k = 0; k < mix.length; k++) {
|
| 280 | if (mix[k] && (y = clsx(mix[k]))) {
|
| 281 | str && (str += " ");
|
| 282 | str += y;
|
| 283 | }
|
| 284 | }
|
| 285 | } else {
|
| 286 | for (k in mix) {
|
| 287 | if (mix[k]) {
|
| 288 | str && (str += " ");
|
| 289 | str += k;
|
| 290 | }
|
| 291 | }
|
| 292 | }
|
| 293 | }
|
| 294 | return str;
|
| 295 | }
|
| 296 |
|
| 297 | export const escapeHTML = (unsafeText: string) =>
|
| 298 | String(unsafeText)
|
| 299 | .replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">")
|
| 300 | .replace(/"/g, """).replace(/'/g, "'").replace(/`/g, "`");
|
clover caruso <git@paperclover.net> 2025-06-07 16:17:52-07:00