ferrovue 0.5.0 → 0.6.0

package/dist/conformance.js

@@ -0,0 +1,276 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { renderToString } from "vue/server-renderer";
+import { generate, loadConfig } from "./compiler.js";
+import { unifiedDiff } from "./diff.js";
+import { allPages, fileRoutes, pagesFolder, routeEntries } from "./file-routes.js";
+import { fixtureApp, peer, readFixture } from "./fixture.js";
+import { headRendered, settled } from "./settle.js";
+import { attachSsrRender } from "./ssr.js";
+export const TELEPORTS = "<!--fv-teleports-->";
+export const HEAD = "<!--fv-head-->";
+/** The head a recorded render wrote after its body, if it wrote one. */
+export function recordedHead(html) {
+    const at = html.indexOf(HEAD);
+    return at < 0 ? null : JSON.parse(html.slice(at + HEAD.length));
+}
+/** Render a fixture's app as the conformance suite records it: Vue's HTML, then what was teleported
+ * and what `useHead` asked for, each after its marker. */
+export async function renderFixture(app) {
+    const ssr = {};
+    const main = await renderToString(app, ssr);
+    const teleported = Object.entries(ssr.teleports ?? {});
+    const html = teleported.length ? `${main}${TELEPORTS}${JSON.stringify(Object.fromEntries(teleported))}` : main;
+    const head = app.config.globalProperties.$unhead?.render();
+    return head && Object.values(head).some(Boolean) ? `${html}${HEAD}${JSON.stringify(head)}` : html;
+}
+/** Put a recorded render's head into the document, as a page would write it: its tags in `<head>`,
+ * and its attributes on `<html>` and `<body>`. */
+export function placeHead(head, doc = document) {
+    doc.head.innerHTML = head?.headTags ?? "";
+    const attrs = (el, written) => {
+        for (const name of el.getAttributeNames())
+            el.removeAttribute(name);
+        const t = doc.createElement("template");
+        t.innerHTML = `<div${written}></div>`;
+        const parsed = t.content.firstElementChild;
+        for (const name of parsed.getAttributeNames())
+            el.setAttribute(name, parsed.getAttribute(name));
+    };
+    attrs(doc.documentElement, head?.htmlAttrs ?? "");
+    attrs(doc.body, head?.bodyAttrs ?? "");
+}
+/** A recorded render as a page body to hydrate: the main HTML in `<div id="root">`, what was
+ * teleported in each target, and the tags the head puts at the start and end of `<body>`. */
+export function hydrationBody(html) {
+    const head = recordedHead(html);
+    const [main, teleported] = html.split(HEAD)[0].split(TELEPORTS);
+    const targets = Object.entries(JSON.parse(teleported ?? "{}"));
+    const intoBody = targets
+        .filter(([t]) => t === "body")
+        .map(([, content]) => content)
+        .join("");
+    const elsewhere = targets
+        .filter(([t]) => t !== "body")
+        .map(([t, content]) => `<div id="${t.replace(/^#/, "")}">${content}</div>`)
+        .join("");
+    return `${head?.bodyTagsOpen ?? ""}${intoBody}<div id="root">${main}</div>${elsewhere}${head?.bodyTags ?? ""}`;
+}
+/** Where two renders first differ, with the text around it in each. */
+export function firstDifference(recorded, rendered) {
+    let at = 0;
+    while (at < recorded.length && at < rendered.length && recorded[at] === rendered[at])
+        at++;
+    const lines = recorded.slice(0, at).split("\n");
+    const around = (text) => JSON.stringify(text.slice(Math.max(0, at - 40), at + 40));
+    return `first difference at character ${at} (line ${lines.length}, column ${lines.at(-1).length + 1}):\n  recorded: ${around(recorded)}\n  rendered: ${around(rendered)}`;
+}
+function componentsByName(given, pages) {
+    const nameOf = (key) => {
+        const path = key.replaceAll("\\", "/");
+        return pages.find((p) => path.endsWith(`/${p.within}`))?.name ?? basename(key, ".vue");
+    };
+    return new Map(Object.entries(given).map(([key, value]) => [
+        nameOf(key),
+        value.default ?? value,
+    ]));
+}
+/** The routes and the router and vue-i18n options a project's fixtures render with, from its configuration. */
+export function fixtureOptions(root, config) {
+    const router = config.router ?? (config.routes ? { routes: config.routes } : null);
+    const pages = pagesFolder(config);
+    const routes = pages !== null
+        ? routeEntries(fileRoutes(root, pages))
+        : typeof router?.routes === "string"
+            ? JSON.parse(readFileSync(join(root, router.routes), "utf8"))
+            : null;
+    const options = {};
+    if (router?.base !== undefined)
+        options.base = router.base;
+    if (router?.linkActiveClass !== undefined)
+        options.linkActiveClass = router.linkActiveClass;
+    if (router?.linkExactActiveClass !== undefined)
+        options.linkExactActiveClass = router.linkExactActiveClass;
+    if (config.i18n) {
+        const dir = join(root, config.i18n.messages);
+        options.i18n = {
+            messages: Object.fromEntries(readdirSync(dir)
+                .filter((f) => f.endsWith(".json"))
+                .map((f) => [basename(f, ".json"), JSON.parse(readFileSync(join(dir, f), "utf8"))])),
+            locale: config.i18n.locale ?? "en",
+            ...(config.i18n.fallbackLocale !== undefined ? { fallbackLocale: config.i18n.fallbackLocale } : {}),
+        };
+    }
+    return { routes, options };
+}
+function casesIn(fixtures) {
+    if (!existsSync(fixtures))
+        return [];
+    return readdirSync(fixtures, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .toSorted((a, b) => a.name.localeCompare(b.name))
+        .flatMap((d) => readdirSync(join(fixtures, d.name))
+        .filter((f) => f.endsWith(".json"))
+        .toSorted()
+        .map((f) => ({ component: d.name, name: f, base: join(fixtures, d.name, basename(f, ".json")) })));
+}
+function recordedHtml(c) {
+    try {
+        return readFileSync(`${c.base}.html`, "utf8");
+    }
+    catch {
+        throw new Error(`${c.component}/${c.name} has no recorded HTML: record it from Vue with FERROVUE_FIXTURES_WRITE=1`);
+    }
+}
+function coverageProblems(fixtures, components, cases, files, given) {
+    const problems = [];
+    if (!existsSync(fixtures))
+        problems.push(`there is no fixtures directory at ${fixtures}`);
+    if (!files.length)
+        problems.push(`there are no components in ${components}`);
+    const withFixtures = new Set(cases.map((c) => c.component));
+    for (const name of files) {
+        if (!withFixtures.has(name))
+            problems.push(`${name} has no fixtures: add ${name}/<case>.json under ${fixtures}`);
+        if (!given.has(name))
+            problems.push(`${name} is not in \`components\``);
+    }
+    for (const name of withFixtures)
+        if (!files.includes(name))
+            problems.push(`the fixtures in ${name}/ name no component`);
+    for (const name of given.keys())
+        if (!files.includes(name))
+            problems.push(`\`components\` has ${name}, which is not a .vue file the configuration compiles`);
+    return problems;
+}
+function driftProblems(root, config) {
+    const out = join(root, config.out);
+    const files = generate(root, config);
+    const problems = [];
+    for (const [file, text] of files) {
+        const path = join(out, file);
+        if (!existsSync(path))
+            problems.push(`${file} is missing`);
+        else {
+            const committed = readFileSync(path, "utf8");
+            if (committed !== text)
+                problems.push(unifiedDiff(relative(root, path), committed, text).trimEnd());
+        }
+    }
+    const stale = existsSync(out) ? readdirSync(out).filter((f) => f.endsWith(".rs") && !files.has(f)) : [];
+    for (const file of stale.toSorted())
+        problems.push(`${file} is no longer generated`);
+    return problems;
+}
+async function hydrateFixture(app, html) {
+    if (typeof document === "undefined")
+        throw new Error("hydrating a fixture needs a DOM: run the suite with `environment: \"happy-dom\"` (or jsdom)");
+    placeHead(recordedHead(html));
+    document.body.innerHTML = hydrationBody(html);
+    const root = document.getElementById("root");
+    const first = root.firstChild;
+    const problems = [];
+    const { warn, error } = console;
+    console.warn = (...args) => void problems.push(`console.warn: ${args.map(String).join(" ")}`);
+    console.error = (...args) => void problems.push(`console.error: ${args.map(String).join(" ")}`);
+    app.config.warnHandler = (message) => void problems.push(`warning: ${message}`);
+    try {
+        app.mount(root);
+        await settled(app);
+        await headRendered();
+    }
+    finally {
+        console.warn = warn;
+        console.error = error;
+    }
+    if (root.firstChild !== first)
+        problems.push("Vue replaced the server's first node");
+    app.unmount();
+    await headRendered();
+    document.body.innerHTML = "";
+    placeHead(null);
+    return problems;
+}
+/** Register the conformance suite with the given `describe` and `it`. */
+export function registerConformance(api, options) {
+    const configFile = resolve(options.config);
+    const root = dirname(configFile);
+    const config = loadConfig(root, configFile);
+    const fixtures = resolve(root, options.fixtures ?? "fixtures");
+    const record = options.record ?? process.env.FERROVUE_FIXTURES_WRITE === "1";
+    const dir = join(root, config.components);
+    const pagesDir = pagesFolder(config)?.replace(/\/+$/, "") ?? null;
+    const pages = pagesDir === null
+        ? []
+        : allPages(fileRoutes(root, pagesDir)).map((p) => ({ name: p.component, file: join(root, p.file), within: `${basename(pagesDir)}/${p.file.slice(pagesDir.length + 1)}` }));
+    const sources = new Map([
+        ...(existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".vue")) : []).map((f) => [basename(f, ".vue"), join(dir, f)]),
+        ...pages.map((p) => [p.name, p.file]),
+    ]);
+    const files = [...sources.keys()].toSorted();
+    const given = componentsByName(options.components, pages);
+    for (const [name, component] of given) {
+        const source = sources.get(name);
+        if (source)
+            attachSsrRender(source, name, component);
+    }
+    const cases = casesIn(fixtures);
+    const { routes, options: configured } = fixtureOptions(root, config);
+    const appOptions = { ...configured, pinia: options.pinia, vueRouter: options.vueRouter, vueI18n: options.vueI18n };
+    const app = async (c, hydrate = false) => {
+        const component = given.get(c.component);
+        if (!component)
+            throw new Error(`the fixtures in ${c.component}/ name no component in \`components\``);
+        const json = JSON.parse(readFileSync(`${c.base}.json`, "utf8"));
+        return fixtureApp(component, readFixture(json), routes, { ...appOptions, hydrate });
+    };
+    api.describe("conformance", () => {
+        api.it("has fixtures for every component, and a component for every fixture", () => {
+            const problems = coverageProblems(fixtures, dir, cases, files, given);
+            if (problems.length)
+                throw new Error(`the fixtures do not cover the components:\n${problems.join("\n")}`);
+        });
+        api.it("has generated Rust that is what the generator writes now", () => {
+            const problems = driftProblems(root, config);
+            if (problems.length) {
+                throw new Error(`the generated Rust in ${config.out} is not what ferrovue writes now: run \`ferrovue\` and commit the result\n${problems.join("\n")}`);
+            }
+        });
+        api.describe("Vue renders each fixture to its recorded HTML", () => {
+            for (const c of cases) {
+                api.it(`${c.component}/${c.name}`, async () => {
+                    const html = await renderFixture(await app(c));
+                    if (record) {
+                        writeFileSync(`${c.base}.html`, html);
+                        return;
+                    }
+                    const want = recordedHtml(c);
+                    if (html !== want) {
+                        const message = `${c.component}/${c.name}: Vue renders this fixture differently from its recorded HTML, ${firstDifference(want, html)}`;
+                        throw Object.assign(new Error(message), { actual: html, expected: want, showDiff: true });
+                    }
+                });
+            }
+        });
+        if (record)
+            return;
+        api.describe("the recorded HTML hydrates without a mismatch", () => {
+            for (const c of cases) {
+                api.it(`${c.component}/${c.name}`, async () => {
+                    const problems = await hydrateFixture(await app(c, true), recordedHtml(c));
+                    if (problems.length)
+                        throw new Error(`${c.component}/${c.name} did not hydrate exactly:\n${problems.join("\n")}`);
+                });
+            }
+        });
+    });
+}
+/** Register vitest tests holding a project's components to Vue, as ferrovue's own suite does:
+ * every component has fixtures and every fixture a component, the generated Rust is what the
+ * generator writes now, Vue renders each fixture to its recorded `.html` (or records it, with
+ * `FERROVUE_FIXTURES_WRITE=1`), and each recorded `.html` hydrates with no warning and the server's
+ * nodes kept. Await it at the top of a test file run in a DOM environment such as happy-dom. */
+export async function conformanceSuite(options) {
+    const vitest = await peer("vitest", "`conformanceSuite` registers vitest tests", () => import("vitest"));
+    registerConformance(vitest, options);
+}

package/dist/context.d.ts

@@ -38,15 +38,17 @@ export interface Config {
     twins?: Record<string, TwinSpec>;
     /** The Rust type a `TrustedHtml` prop is, which must implement `ferrovue::TrustedHtml`, e.g.
      * `crate::sanitize::SafeHtml`. A type that borrows names the props' lifetime, `'a`:
-     * `crate::render::Trusted<'a>`. Without it, a component cannot use `v-html` at all. */
+     * `crate::render::Trusted<'a>`. `ferrovue::InlineHtml` makes every `TrustedHtml` prop inline HTML.
+     * Without it, only an `InlineHtml` prop may reach `v-html`. */
     trustedHtml?: string;
     /** A JSON file listing the app's routes as vue-router paths (`/users/:id`), which `<RouterLink>`
-     * resolves against. Without it, a component cannot use `<RouterLink>`. */
-    routes?: string;
-    /** The router, in full: its routes file, the history's base, and the class names
-     * `createRouter` gives active links. `routes` alone is shorthand for `{ routes }`. */
+     * resolves against, or `{ pages }`: a folder of pages whose file names give the routes, as
+     * vue-router's file-based routing reads them. Without it, a component cannot use `<RouterLink>`. */
+    routes?: RoutesSource;
+    /** The router, in full: its routes, the history's base, and the class names `createRouter`
+     * gives active links. `routes` alone is shorthand for `{ routes }`. */
     router?: {
-        routes: string;
+        routes: RoutesSource;
         base?: string;
         linkActiveClass?: string;
         linkExactActiveClass?: string;
@@ -77,10 +79,16 @@ export interface Config {
     builders?: boolean;
 }
 export type ScopeIdMode = "filepath" | "filepath-source";
+/** Where the routes come from: a JSON file of routes, or a folder of pages. */
+export type RoutesSource = string | {
+    pages: string;
+};
 export declare const CONFIG_FILE = "ferrovue.config.json";
 /** Read the project's configuration. */
 export declare function loadConfig(root: string, configPath?: string): Config;
 export declare function tyOfName(name: TypeName): Ty;
+/** The Rust type of an `InlineHtml` prop, and of a `TrustedHtml` one when `trustedHtml` names it. */
+export declare const INLINE_HTML = "ferrovue::InlineHtml";
 /** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
 export declare const TYPES_MODULE = "ferrovue/types";
 export declare const ctx: {
@@ -110,4 +118,5 @@ export declare const ctx: {
     components: Map<string, Component>;
     narrowCount: number;
     componentsDir: string;
+    vnodeTag: string | null;
 };

package/dist/context.js

@@ -54,6 +54,8 @@ export function tyOfName(name) {
             throw new GenError("FV1107", `unknown helper type \`${String(name)}\``);
     }
 }
+/** The Rust type of an `InlineHtml` prop, and of a `TrustedHtml` one when `trustedHtml` names it. */
+export const INLINE_HTML = "ferrovue::InlineHtml";
 /** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
 export const TYPES_MODULE = "ferrovue/types";
 export const ctx = {
@@ -74,4 +76,5 @@ export const ctx = {
     components: new Map(),
     narrowCount: 0,
     componentsDir: "",
+    vnodeTag: null,
 };

package/dist/dynamic.d.ts

@@ -0,0 +1,18 @@
+import { type Component, type N, type Scope } from "./model.ts";
+import { Emitter } from "./emitter.ts";
+/** Whether the content a parent gives `slot` of `child` is rendered as virtual nodes, as it is
+ * inside an element a `<component :is>` chooses. */
+export declare function slotAsVnodes(child: Component, slot: string): boolean;
+/** Whether a statement of a compiled template renders a `<component :is>`. */
+export declare function isDynamicComponent(st: N): boolean;
+/** Render `_ssrRenderVNode` of a `<component :is>`, or return false for a statement that is not one. */
+export declare function dynamicComponent(s: Scope, e: Emitter, st: N): boolean;
+/** Resolve every `<component :is>` of the components before any is generated: the slots whose
+ * content renders as virtual nodes, and the compiled templates as the analyses read them, with
+ * each `<component :is>` written out as its choices. */
+export declare function prepareDynamic(read: {
+    comp: Component;
+    ast: N[];
+    ssr: string;
+    scope: Scope;
+}[]): string[];