ferrovue 0.2.0 → 0.4.0

package/dist/classes.js

@@ -0,0 +1,176 @@
+import { escapeHtml } from "@vue/shared";
+import { fail, rustStr, STR } from "./model.js";
+import { expr } from "./expr.js";
+import { cond, known, truthy } from "./narrowing.js";
+import { meet } from "./strings.js";
+import { atom, bare, condition, logical, not, strArg } from "./parens.js";
+import { Emitter } from "./emitter.js";
+import { valueAttr } from "./attrs.js";
+export function classItems(s, n) {
+    switch (n.type) {
+        case "StringLiteral": {
+            const t = n.value.trim();
+            return t ? [{ lit: t }] : [];
+        }
+        case "ArrayExpression":
+            return n.elements.flatMap((el) => (el ? classItems(s, el) : []));
+        case "ObjectExpression":
+            const literalNames = n.properties
+                .filter((p) => p.type === "ObjectProperty" && !p.computed)
+                .map((p) => (p.key.type === "Identifier" ? p.key.name : String(p.key.value)));
+            const arrayIndex = (k) => /^(0|[1-9]\d*)$/.test(k) && Number(k) < 2 ** 32 - 1;
+            if (n.properties.some((p) => p.type === "ObjectProperty" && p.computed) ||
+                literalNames.some(arrayIndex) ||
+                new Set(literalNames).size !== literalNames.length) {
+                const keys = [];
+                const entries = n.properties.map((p) => {
+                    if (p.type !== "ObjectProperty")
+                        fail(s.comp, "a class object holds `name: condition` pairs", p);
+                    const key = p.computed ? expr(s, p.key) : { code: rustStr(p.key.type === "Identifier" ? p.key.name : String(p.key.value)), ty: STR };
+                    if (key.ty.k !== "str")
+                        fail(s.comp, "a computed class name is a string", p.key);
+                    for (const other of keys)
+                        meet(s.comp, other, key, "a class object's names", p.key, "equal");
+                    keys.push(key);
+                    return `(${bare(cond(s, p.value))}, ${bare(key.code)})`;
+                });
+                return [{ code: `&*fv::class_object(&[${entries.join(", ")}])` }];
+            }
+            return n.properties.flatMap((p) => {
+                if (p.type !== "ObjectProperty")
+                    fail(s.comp, "a class object holds `name: condition` pairs", p);
+                let name;
+                if (!p.computed) {
+                    const key = p.key.type === "Identifier" ? p.key.name : String(p.key.value);
+                    if (key !== key.trim() || !key)
+                        fail(s.comp, `class name \`${key}\` has spaces around it`, p);
+                    name = { lit: key };
+                }
+                else {
+                    const k = expr(s, p.key);
+                    if (k.ty.k !== "str")
+                        fail(s.comp, "a computed class name is a string", p.key);
+                    name = { code: `fv::js_trim(${strArg(k.code)})` };
+                }
+                const v = expr(s, p.value);
+                const on = known(v);
+                if (on !== undefined)
+                    return on ? [name] : [];
+                const text = "lit" in name ? rustStr(name.lit) : name.code;
+                return [{ code: `if ${condition(truthy(v))} { ${bare(text)} } else { "" }` }];
+            });
+        case "LogicalExpression":
+            if (n.operator === "&&") {
+                return conditional(cond(s, n.left), classItems(s, n.right));
+            }
+            break;
+        case "ConditionalExpression":
+            if (n.consequent.type === "NullLiteral" || n.alternate.type === "NullLiteral") {
+                const branch = n.consequent.type === "NullLiteral" ? n.alternate : n.consequent;
+                const test = cond(s, n.test);
+                return conditional(n.consequent.type === "NullLiteral" ? not(test) : test, classItems(s, branch));
+            }
+            break;
+    }
+    const v = expr(s, n);
+    if (v.ty.k === "str")
+        return [{ code: v.code }];
+    if (v.ty.k === "opt" && v.ty.of.k === "str")
+        return [{ code: `${atom(v.code)}.unwrap_or("")` }];
+    if (v.ty.k === "undef")
+        return [];
+    return fail(s.comp, "a class is a string, an array, or an object of conditions", n);
+}
+function conditional(test, items) {
+    if (test === "true" || test === "false")
+        return test === "true" ? items : [];
+    return items.map((it) => ({ code: `if ${condition(test)} { ${"lit" in it ? rustStr(it.lit) : bare(it.code)} } else { "" }` }));
+}
+export function renderClass(s, e, n, after = false) {
+    const items = classItems(s, n);
+    let wrote = after;
+    let i = 0;
+    for (; i < items.length; i++) {
+        const it = items[i];
+        if (!("lit" in it))
+            break;
+        e.lit((wrote ? " " : "") + escapeHtml(it.lit));
+        wrote = true;
+    }
+    if (i < items.length) {
+        const rest = items.slice(i).map((it) => ("lit" in it ? rustStr(it.lit) : it.code));
+        e.stmt(`fv::class_into(out, ${wrote}, &[${rest.join(", ")}]);`);
+    }
+}
+export function classPresent(s, n) {
+    if (n.fvMerged)
+        return n.elements.reduce((acc, el) => logical(acc, "||", classPresent(s, el)), "false");
+    switch (n.type) {
+        case "StringLiteral":
+        case "NullLiteral":
+        case "ArrayExpression":
+        case "ObjectExpression":
+            return "true";
+        case "LogicalExpression":
+            if (n.operator === "&&")
+                return logical(not(cond(s, n.left)), "||", classPresent(s, n.right));
+            break;
+        case "ConditionalExpression":
+            if (n.consequent.type === "NullLiteral")
+                return logical(cond(s, n.test), "||", classPresent(s, n.alternate));
+            if (n.alternate.type === "NullLiteral")
+                return logical(not(cond(s, n.test)), "||", classPresent(s, n.consequent));
+            break;
+    }
+    const v = expr(s, n);
+    if (v.ty.k === "undef")
+        return "false";
+    if (v.ty.k === "opt")
+        return `${atom(v.code)}.is_some()`;
+    return "true";
+}
+export function maybeEqual(s, n) {
+    if (n.type === "StringLiteral")
+        return true;
+    if (n.fvMerged || ["ArrayExpression", "ObjectExpression", "NullLiteral", "LogicalExpression", "ConditionalExpression"].includes(n.type))
+        return false;
+    const v = expr(s, n);
+    return v.ty.k === "str" || (v.ty.k === "opt" && v.ty.of.k === "str");
+}
+export function literalClass(n) {
+    if (n.type === "StringLiteral")
+        return n.value.trim();
+    if (!n.fvMerged)
+        return null;
+    const parts = n.elements.map(literalClass);
+    return parts.includes(null) ? null : parts.filter(Boolean).join(" ");
+}
+export function classAttr(s, n, side) {
+    switch (n.type) {
+        case "StringLiteral":
+            return `fv::Attr::str(${rustStr(n.value)})`;
+        case "NullLiteral":
+            return 'fv::Attr::str("")';
+        case "ArrayExpression":
+        case "ObjectExpression": {
+            const items = classItems(s, n);
+            const names = items.every((it) => "lit" in it)
+                ? rustStr(items.map((it) => ("lit" in it ? it.lit : "")).join(" "))
+                : `fv::class_names(&[${items.map((it) => ("lit" in it ? rustStr(it.lit) : it.code)).join(", ")}])`;
+            const literal = names.startsWith('"');
+            if (side === "vnode")
+                return literal ? `fv::Attr::str(${names})` : `fv::Attr::from(${names})`;
+            return `fv::Attr::Names(${literal ? `std::borrow::Cow::Borrowed(${names})` : `${names}.into()`})`;
+        }
+        case "LogicalExpression":
+            if (n.operator === "&&")
+                return `if ${condition(cond(s, n.left))} { ${classAttr(s, n.right, side)} } else { fv::Attr::str("") }`;
+            break;
+        case "ConditionalExpression":
+            return `if ${condition(cond(s, n.test))} { ${classAttr(s, n.consequent, side)} } else { ${classAttr(s, n.alternate, side)} }`;
+    }
+    const v = expr(s, n);
+    if (v.ty.k === "str" || v.ty.k === "undef" || (v.ty.k === "opt" && v.ty.of.k === "str"))
+        return valueAttr(s, v, n);
+    return fail(s.comp, "a class is a string, an array, or an object of conditions", n);
+}

package/dist/cli.js

@@ -1,22 +1,65 @@
 #!/usr/bin/env node
-/* `ferrovue` — compile the project's components, run from its root.
- *
- *   ferrovue          write the Rust modules to the configured output directory
- *   ferrovue --check  write nothing; exit 1 if the committed modules are not what would be written
- *   ferrovue --watch  write them, then again whenever a component, store, type file, the routes
- *                     or the configuration changes, until interrupted */
-import { readFileSync, readdirSync, watch } from "node:fs";
-import { join, relative, sep } from "node:path";
-import { GenError, generate, loadConfig, write } from "./compiler.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, watch, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { CONFIG_FILE, GenError, generate, loadConfig, VERSION, write } from "./compiler.js";
+import { unifiedDiff } from "./diff.js";
 const root = process.cwd();
-/** A refused construct, or a broken configuration: the message alone, which names the file. */
+const HELP = `Usage: ferrovue [command] [options]
+
+Compile Vue components to Rust render functions, run from the project root.
+
+Commands:
+  init                     scaffold starter ferrovue.config.json and components
+
+Options:
+      --check              check that generated files match committed files without writing
+  -d, --diff               show unified diff of changes when checking (use with --check)
+      --watch              watch components, stores, routes and config for changes and regenerate
+  -c, --config <path>      path to configuration file (default: ferrovue.config.json)
+  -v, --version            print the version and exit
+  -h, --help               print this help and exit
+`;
 function report(e) {
     if (e instanceof GenError || e instanceof SyntaxError)
         console.error(`error: ${e.message}`);
     else
         throw e;
 }
-function check(config) {
+function initProject(targetRoot, configPath) {
+    const configFile = configPath ? resolve(targetRoot, configPath) : join(targetRoot, CONFIG_FILE);
+    if (existsSync(configFile)) {
+        console.error(`error: configuration file already exists: ${relative(targetRoot, configFile) || CONFIG_FILE}`);
+        return 1;
+    }
+    const defaultComponents = "components";
+    const defaultOut = "src/generated";
+    mkdirSync(dirname(configFile), { recursive: true });
+    const config = {
+        components: defaultComponents,
+        out: defaultOut,
+    };
+    writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+    console.log(`created ${relative(targetRoot, configFile) || CONFIG_FILE}`);
+    const compDir = join(targetRoot, defaultComponents);
+    mkdirSync(compDir, { recursive: true });
+    const helloVue = join(compDir, "Hello.vue");
+    if (!existsSync(helloVue)) {
+        writeFileSync(helloVue, `<script setup lang="ts">
+defineProps<{ name: string }>();
+</script>
+
+<template>
+  <p>Hello, {{ name }}!</p>
+</template>
+`);
+        console.log(`created ${join(defaultComponents, "Hello.vue")}`);
+    }
+    const outDir = join(targetRoot, defaultOut);
+    mkdirSync(outDir, { recursive: true });
+    console.log("\nNext steps:\n  1. Run `ferrovue` to generate Rust render functions into src/generated\n  2. In your Rust crate, declare `mod generated;` to use them");
+    return 0;
+}
+function check(config, showDiff = false) {
     const want = generate(root, config);
     const dir = join(root, config.out);
     let have = [];
@@ -24,7 +67,6 @@ function check(config) {
         have = readdirSync(dir).filter((f) => f.endsWith(".rs"));
     }
     catch {
-        // An absent directory is simply stale.
     }
     const stale = [...want.keys()].filter((name) => {
         try {
@@ -36,10 +78,24 @@ function check(config) {
     });
     const extra = have.filter((name) => !want.has(name));
     if (stale.length || extra.length) {
-        for (const name of stale)
+        const committed = (name) => {
+            try {
+                return readFileSync(join(dir, name), "utf8");
+            }
+            catch {
+                return "";
+            }
+        };
+        for (const name of stale) {
             console.error(`stale: ${config.out}/${name}`);
-        for (const name of extra)
+            if (showDiff)
+                console.error(unifiedDiff(`${config.out}/${name}`, committed(name), want.get(name)));
+        }
+        for (const name of extra) {
             console.error(`not generated: ${config.out}/${name}`);
+            if (showDiff)
+                console.error(unifiedDiff(`${config.out}/${name}`, committed(name), ""));
+        }
         console.error("run `ferrovue` to regenerate");
         return 1;
     }
@@ -51,12 +107,10 @@ function once(config) {
     const what = changed.length || removed.length ? `${changed.length} changed, ${removed.length} removed` : "nothing changed";
     console.log(`${config.out}: ${files.length} files, ${what}`);
 }
-/** Regenerate on every change to what the components are compiled from, reporting errors and
- * carrying on. The output directory itself, dependencies and build output are ignored. */
-function watchProject() {
+function watchProject(configPath) {
     const run = () => {
         try {
-            once(loadConfig(root));
+            once(loadConfig(root, configPath));
         }
         catch (e) {
             report(e);
@@ -66,10 +120,9 @@ function watchProject() {
     const ignored = (file) => {
         let out = "";
         try {
-            out = loadConfig(root).out;
+            out = loadConfig(root, configPath).out;
         }
         catch {
-            // A broken configuration ignores nothing; the next run reports it.
         }
         const parts = file.split(sep);
         return (parts.some((p) => p === "node_modules" || p === "target" || p === ".git" || p === "dist") ||
@@ -80,7 +133,6 @@ function watchProject() {
     watch(root, { recursive: true }, (_event, name) => {
         if (!name || ignored(relative(root, join(root, name))))
             return;
-        // Editors write a file in several steps: one run once they are done.
         if (timer)
             clearTimeout(timer);
         timer = setTimeout(run, 50);
@@ -88,12 +140,54 @@ function watchProject() {
     console.log("watching for changes (Ctrl-C to stop)");
 }
 try {
-    if (process.argv.includes("--watch"))
-        watchProject();
-    else if (process.argv.includes("--check"))
-        process.exitCode = check(loadConfig(root));
-    else
-        once(loadConfig(root));
+    const rawArgs = process.argv.slice(2);
+    let configPath;
+    const args = [];
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === "-c" || arg === "--config") {
+            if (i + 1 >= rawArgs.length || rawArgs[i + 1].startsWith("-")) {
+                console.error(`error: option '${arg}' requires an argument`);
+                process.exit(1);
+            }
+            configPath = rawArgs[++i];
+        }
+        else if (arg.startsWith("--config=")) {
+            configPath = arg.slice("--config=".length);
+        }
+        else {
+            args.push(arg);
+        }
+    }
+    const known = new Set(["init", "--check", "--diff", "-d", "--watch", "-v", "--version", "-h", "--help"]);
+    const unknown = args.find((a) => !known.has(a));
+    if (unknown !== undefined) {
+        console.error(`error: unknown option or command '${unknown}'\n\nRun \`ferrovue --help\` for usage.`);
+        process.exit(1);
+    }
+    if ((args.includes("--diff") || args.includes("-d")) && !args.includes("--check")) {
+        console.error("error: '--diff' requires '--check'");
+        process.exit(1);
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(VERSION);
+    }
+    else if (args.includes("--help") || args.includes("-h")) {
+        console.log(HELP.trimEnd());
+    }
+    else if (args.includes("init")) {
+        process.exitCode = initProject(root, configPath);
+    }
+    else if (args.includes("--watch")) {
+        watchProject(configPath);
+    }
+    else if (args.includes("--check")) {
+        const showDiff = args.includes("--diff") || args.includes("-d");
+        process.exitCode = check(loadConfig(root, configPath), showDiff);
+    }
+    else {
+        once(loadConfig(root, configPath));
+    }
 }
 catch (e) {
     report(e);

package/dist/client.d.ts

@@ -18,6 +18,14 @@ export interface MountOptions {
      * those given or its props are malformed. Warns on the console by default. */
     onError?: (element: Element, problem: string) => void;
 }
+/** A component, or a function that loads one — `() => import("./Counter.vue")` — so that the code
+ * of an island not on the page is never fetched. A function is taken for a loader as vue-router
+ * takes one for a lazy route: unless it has `props` or `displayName`, which mark a functional
+ * component, or `__vccOpts`, a class component. `ferrovue/islands` maps the name of every island
+ * to a loader. */
+export type IslandComponent = Component | (() => Promise<Component | {
+    default: Component;
+}>);
 /** The islands mounted. */
 export interface Islands {
     /** One app per island, in document order. */
@@ -27,5 +35,6 @@ export interface Islands {
 }
 /** Hydrate every island on the page: each `<div data-island="Name" data-props="…">` that
  * `Html::island` wrote becomes an app of the component of that name, given the props the server
- * rendered it with, mounted where it is. */
-export declare function mountIslands(components: Record<string, Component>, options?: MountOptions): Promise<Islands>;
+ * rendered it with, mounted where it is. A loader is called only for an island the page holds, all
+ * of them at once, and the islands mount in document order once every one has loaded. */
+export declare function mountIslands(components: Record<string, IslandComponent>, options?: MountOptions): Promise<Islands>;

package/dist/client.js

@@ -1,31 +1,56 @@
-/* What the browser does with a page ferrovue rendered. */
 import { createSSRApp } from "vue";
+const BARE = /"(?:[^"\\]|\\.)*"|-?Infinity|NaN/g;
+const NON_FINITE = { NaN: Number.NaN, Infinity: Number.POSITIVE_INFINITY, "-Infinity": Number.NEGATIVE_INFINITY };
+function parseJson(text) {
+    if (!/NaN|Infinity/.test(text))
+        return JSON.parse(text);
+    let escaped = "\\u0000";
+    while (text.includes(escaped))
+        escaped += "\\u0000";
+    const tag = JSON.parse(`"${escaped}"`);
+    const quoted = text.replace(BARE, (match) => (match.startsWith('"') ? match : `"${escaped}${match}"`));
+    return JSON.parse(quoted, (_key, value) => (typeof value === "string" && value.startsWith(tag) ? NON_FINITE[value.slice(tag.length)] : value));
+}
 /** Give Pinia the state the server rendered with — what `ferrovue::state_script_into` wrote — before
  * the app mounts, so every store starts from it and the hydrated markup agrees with the server's. */
 export function hydrateState(pinia, id = "__pinia", doc = document) {
     const text = doc.getElementById(id)?.textContent;
     if (text)
-        pinia.state.value = JSON.parse(text);
+        pinia.state.value = parseJson(text);
 }
 /** Hydrate every island on the page: each `<div data-island="Name" data-props="…">` that
  * `Html::island` wrote becomes an app of the component of that name, given the props the server
- * rendered it with, mounted where it is. */
+ * rendered it with, mounted where it is. A loader is called only for an island the page holds, all
+ * of them at once, and the islands mount in document order once every one has loaded. */
 export async function mountIslands(components, options = {}) {
     const root = options.root ?? document;
     const report = options.onError ?? ((el, problem) => console.warn(`[ferrovue] island left unhydrated: ${problem}`, el));
-    if (options.router)
-        await options.router.isReady();
+    const elements = Array.from(root.querySelectorAll("[data-island]"));
+    const loading = new Map();
+    for (const el of elements) {
+        const name = el.dataset.island ?? "";
+        if (Object.hasOwn(components, name) && !loading.has(name))
+            loading.set(name, load(components[name]));
+    }
+    const [loaded] = await Promise.all([
+        Promise.all([...loading].map(async ([name, pending]) => [name, await pending])).then((pairs) => new Map(pairs)),
+        options.router?.isReady(),
+    ]);
     const apps = [];
-    for (const el of Array.from(root.querySelectorAll("[data-island]"))) {
+    for (const el of elements) {
         const name = el.dataset.island ?? "";
-        const component = components[name];
+        const component = loaded.get(name);
         if (!component) {
-            report(el, `no component called ${JSON.stringify(name)} was given`);
+            report(el, `no component called ${JSON.stringify(name)} was given (\`ferrovue/islands\` holds every component that has an \`island()\`)`);
+            continue;
+        }
+        if (component instanceof Error) {
+            report(el, `${name} did not load: ${component.message}`);
             continue;
         }
         let props;
         try {
-            props = JSON.parse(el.dataset.props ?? "{}");
+            props = parseJson(el.dataset.props ?? "{}");
         }
         catch {
             report(el, `the props of ${name} are not JSON`);
@@ -49,3 +74,14 @@ export async function mountIslands(components, options = {}) {
         },
     };
 }
+async function load(component) {
+    if (typeof component !== "function" || "props" in component || "displayName" in component || "__vccOpts" in component)
+        return component;
+    try {
+        const loaded = await component();
+        return typeof loaded === "object" && "default" in loaded ? loaded.default : loaded;
+    }
+    catch (e) {
+        return e instanceof Error ? e : new Error(String(e));
+    }
+}

package/dist/compiler.d.ts

@@ -10,6 +10,9 @@ export interface Written {
     changed: string[];
     /** The files removed, which the components no longer produce. */
     removed: string[];
+    /** Every component that has an `island()`, by the name `data-island` carries, with its `.vue`
+     * file relative to the root: what `ferrovue/islands` loads. */
+    islands: Record<string, string>;
 }
 /** Write what \`generate\` produces to the configured directory: only the files whose text changed,
  * so a Rust build that watches them rebuilds no more than it must, and removing what no component
@@ -17,3 +20,4 @@ export interface Written {
 export declare function write(root: string, config?: Config): Written;
 export { CONFIG_FILE, loadConfig, TYPES_MODULE, type Config, type HelperSpec, type TypeName } from "./context.ts";
 export { GenError } from "./model.ts";
+export declare const VERSION: string;