ferrovue 0.3.0 → 0.5.0

package/dist/classes.js

@@ -0,0 +1,176 @@
+import { escapeHtml } from "@vue/shared";
+import { fail, nothing, 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, "FV1001", "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, "FV1002", "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, "FV1001", "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, "FV1003", `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, "FV1002", "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 (nothing(v.ty))
+        return [];
+    return fail(s.comp, "FV1004", "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 (nothing(v.ty))
+        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" || nothing(v.ty) || (v.ty.k === "opt" && v.ty.of.k === "str"))
+        return valueAttr(s, v, n);
+    return fail(s.comp, "FV1004", "a class is a string, an array, or an object of conditions", n);
+}

package/dist/cli.js

@@ -1,19 +1,9 @@
 #!/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 --check --diff   show a unified diff of differences
- *   ferrovue --watch          write them, then again whenever a component, store, type file, the routes
- *                             or the configuration changes, until interrupted
- *   ferrovue init             scaffold a starter ferrovue.config.json and components directory
- *   ferrovue -c, --config     path to configuration file (default: ferrovue.config.json)
- *   ferrovue -v, --version    print the version and exit
- *   ferrovue -h, --help       print this help and exit */
 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 { CONFIG_FILE, generate, loadConfig, VERSION, write } from "./compiler.js";
 import { unifiedDiff } from "./diff.js";
+import { diagnose, formatRefusal, isRefusal } from "./diagnostics.js";
 const root = process.cwd();
 const HELP = `Usage: ferrovue [command] [options]
 
@@ -25,17 +15,23 @@ Commands:
 Options:
       --check              check that generated files match committed files without writing
   -d, --diff               show unified diff of changes when checking (use with --check)
+      --format <format>    how to write errors and results: human (default) or json
       --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
 `;
-/** A refused construct, or a broken configuration: the message alone, which names the file. */
+let json = false;
+function emit(result) {
+    console.log(JSON.stringify({ diagnostics: [], ...result }));
+}
 function report(e) {
-    if (e instanceof GenError || e instanceof SyntaxError)
-        console.error(`error: ${e.message}`);
-    else
+    if (!isRefusal(e))
         throw e;
+    if (json)
+        emit({ diagnostics: [diagnose(e)] });
+    else
+        console.error(formatRefusal(e));
 }
 function initProject(targetRoot, configPath) {
     const configFile = configPath ? resolve(targetRoot, configPath) : join(targetRoot, CONFIG_FILE);
@@ -79,7 +75,6 @@ function check(config, showDiff = false) {
         have = readdirSync(dir).filter((f) => f.endsWith(".rs"));
     }
     catch {
-        // An absent directory is simply stale.
     }
     const stale = [...want.keys()].filter((name) => {
         try {
@@ -90,6 +85,10 @@ function check(config, showDiff = false) {
         }
     });
     const extra = have.filter((name) => !want.has(name));
+    if (json) {
+        emit({ out: config.out, stale: stale.map((name) => `${config.out}/${name}`), notGenerated: extra.map((name) => `${config.out}/${name}`) });
+        return stale.length || extra.length ? 1 : 0;
+    }
     if (stale.length || extra.length) {
         const committed = (name) => {
             try {
@@ -117,11 +116,11 @@ function check(config, showDiff = false) {
 }
 function once(config) {
     const { files, changed, removed } = write(root, config);
+    if (json)
+        return emit({ out: config.out, files, changed, removed });
     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(configPath) {
     const run = () => {
         try {
@@ -138,7 +137,6 @@ function watchProject(configPath) {
             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") ||
@@ -149,12 +147,11 @@ function watchProject(configPath) {
     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);
     });
-    console.log("watching for changes (Ctrl-C to stop)");
+    (json ? console.error : console.log)("watching for changes (Ctrl-C to stop)");
 }
 try {
     const rawArgs = process.argv.slice(2);
@@ -172,6 +169,14 @@ try {
         else if (arg.startsWith("--config=")) {
             configPath = arg.slice("--config=".length);
         }
+        else if (arg === "--format" || arg.startsWith("--format=")) {
+            const format = arg === "--format" ? rawArgs[++i] : arg.slice("--format=".length);
+            if (format !== "human" && format !== "json") {
+                console.error(`error: '--format' is 'human' or 'json'`);
+                process.exit(1);
+            }
+            json = format === "json";
+        }
         else {
             args.push(arg);
         }
@@ -186,6 +191,10 @@ try {
         console.error("error: '--diff' requires '--check'");
         process.exit(1);
     }
+    if ((args.includes("--diff") || args.includes("-d")) && json) {
+        console.error("error: '--diff' writes text, and does not combine with '--format json'");
+        process.exit(1);
+    }
     if (args.includes("--version") || args.includes("-v")) {
         console.log(VERSION);
     }

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { type App, type Component, type Plugin } from "vue";
 import type { Pinia } from "pinia";
 import type { Router } from "vue-router";
-/** Give Pinia the state the server rendered with — what `ferrovue::state_script_into` wrote — before
+/** 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 declare function hydrateState(pinia: Pinia, id?: string, doc?: Document): void;
 export interface MountOptions {
@@ -18,7 +18,7 @@ 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
+/** 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
@@ -38,3 +38,36 @@ export interface 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>;
+/** Content only the browser renders. The server writes the `#fallback` slot, or nothing; the
+ * browser hydrates that fallback, then swaps in the default slot once mounted. ferrovue does not
+ * compile the default slot, so anything may go there: a component library's components, code that
+ * reads `window`. The swap happens only where Vue runs on the page, as in an island. */
+export declare const ClientOnly: Component;
+/** One component the server rendered into a slot of a page's layout, as `ferrovue::Part` records
+ * it: its name (`c`) and the props it was rendered from (`p`). */
+export interface PagePart {
+    c: string;
+    p: Record<string, unknown>;
+}
+/** What `ferrovue::PageRecord` writes: the layout's props, and each slot's parts in order. */
+export interface PageRecord {
+    props: Record<string, unknown>;
+    slots: Record<string, PagePart[]>;
+}
+export interface PageOptions extends Pick<MountOptions, "pinia" | "router" | "plugins"> {
+    /** The element holding the layout's root, or a selector for it: `#app` by default. */
+    container?: Element | string;
+    /** The `id` of the record's script, as given to `PageRecord::script_into`: `__fv_page` by default. */
+    record?: string;
+    /** The document to read the page from. */
+    doc?: Document;
+}
+/** The app of a page: its root renders `layout` with the record's props, and each slot as the
+ * components the record names, in order, as a plain array, which hydrates the markup the server
+ * wrote with no fragment of its own. `components` must hold every component the record names. */
+export declare function createPageApp(layout: Component, record: PageRecord, components: Record<string, Component>, options?: PageOptions): App;
+/** Hydrate a page `ferrovue::Page` rendered: read its record, load the components it names (and
+ * no others), wait for the router, and mount the layout on the container. Rejects, leaving the page
+ * as the server rendered it, when the container or the record is missing or a component is not
+ * given or does not load. */
+export declare function mountPage(layout: IslandComponent, components: Record<string, IslandComponent>, options?: PageOptions): Promise<App>;

package/dist/client.js

@@ -1,18 +1,9 @@
-/* What the browser does with a page ferrovue rendered. */
-import { createSSRApp } from "vue";
-/** A JSON string, skipped whole as it may hold the same letters, or a bare number JSON has no word
- * for, which the server writes as JavaScript does where `serde_json` alone would write `null`. */
+import { createSSRApp, createTextVNode, defineComponent, h, onMounted, ref } from "vue";
 const BARE = /"(?:[^"\\]|\\.)*"|-?Infinity|NaN/g;
 const NON_FINITE = { NaN: Number.NaN, Infinity: Number.POSITIVE_INFINITY, "-Infinity": Number.NEGATIVE_INFINITY };
-/** `JSON.parse`, reading back the bare `NaN`, `Infinity` and `-Infinity` that an island's props and
- * the state script hold for a number that is not finite, so the client renders what the server did.
- * Throws as `JSON.parse` does on anything else that is not JSON. */
 function parseJson(text) {
-    // Plain JSON: almost everything the server writes, and all it wrote before it wrote these.
     if (!/NaN|Infinity/.test(text))
         return JSON.parse(text);
-    // Each token becomes a string that starts with more NULs in a row than any string in the text
-    // holds (JSON has one way to write a NUL, `\u0000`), so no other value can be mistaken for one.
     let escaped = "\\u0000";
     while (text.includes(escaped))
         escaped += "\\u0000";
@@ -20,7 +11,7 @@ function parseJson(text) {
     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
+/** 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;
@@ -35,7 +26,6 @@ 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));
     const elements = Array.from(root.querySelectorAll("[data-island]"));
-    // Each component the page names, loaded once however many islands it has.
     const loading = new Map();
     for (const el of elements) {
         const name = el.dataset.island ?? "";
@@ -84,8 +74,32 @@ export async function mountIslands(components, options = {}) {
         },
     };
 }
-/** The component itself, or what its loader resolves to: a module's default export, or the
- * component. A loader that rejects gives its error, which leaves only its own islands unhydrated. */
+/** Content only the browser renders. The server writes the `#fallback` slot, or nothing; the
+ * browser hydrates that fallback, then swaps in the default slot once mounted. ferrovue does not
+ * compile the default slot, so anything may go there: a component library's components, code that
+ * reads `window`. The swap happens only where Vue runs on the page, as in an island. */
+export const ClientOnly = Object.assign(defineComponent({
+    name: "ClientOnly",
+    inheritAttrs: false,
+    setup(_, { slots }) {
+        const mounted = ref(false);
+        onMounted(() => {
+            mounted.value = true;
+        });
+        return () => (mounted.value ? slots.default?.() : slots.fallback?.());
+    },
+}), {
+    ssrRender(ctx, push, parent) {
+        const fallback = ctx.$slots.fallback;
+        if (!fallback) {
+            push("<!---->");
+            return;
+        }
+        push("<!--[-->");
+        fallback({}, push, parent, "");
+        push("<!--]-->");
+    },
+});
 async function load(component) {
     if (typeof component !== "function" || "props" in component || "displayName" in component || "__vccOpts" in component)
         return component;
@@ -97,3 +111,52 @@ async function load(component) {
         return e instanceof Error ? e : new Error(String(e));
     }
 }
+/** The app of a page: its root renders `layout` with the record's props, and each slot as the
+ * components the record names, in order, as a plain array, which hydrates the markup the server
+ * wrote with no fragment of its own. `components` must hold every component the record names. */
+export function createPageApp(layout, record, components, options = {}) {
+    const slots = Object.fromEntries(Object.entries(record.slots).map(([name, parts]) => [
+        name,
+        () => (parts.length ? parts.map((part) => h(components[part.c], part.p)) : [createTextVNode("")]),
+    ]));
+    const app = createSSRApp({ name: "FerrovuePage", render: () => h(layout, record.props, slots) });
+    if (options.pinia)
+        app.use(options.pinia);
+    if (options.router)
+        app.use(options.router);
+    for (const plugin of options.plugins ?? [])
+        app.use(plugin);
+    return app;
+}
+/** Hydrate a page `ferrovue::Page` rendered: read its record, load the components it names (and
+ * no others), wait for the router, and mount the layout on the container. Rejects, leaving the page
+ * as the server rendered it, when the container or the record is missing or a component is not
+ * given or does not load. */
+export async function mountPage(layout, components, options = {}) {
+    const doc = options.doc ?? document;
+    const selector = options.container ?? "#app";
+    const container = typeof selector === "string" ? doc.querySelector(selector) : selector;
+    if (!container)
+        throw new Error(`[ferrovue] the page has no ${selector} to mount on`);
+    const id = options.record ?? "__fv_page";
+    const text = doc.getElementById(id)?.textContent;
+    if (!text)
+        throw new Error(`[ferrovue] the page has no record: no <script id="${id}">`);
+    const record = parseJson(text);
+    const names = new Set(Object.values(record.slots).flatMap((parts) => parts.map((part) => part.c)));
+    const loading = [...names].map(async (name) => {
+        if (!Object.hasOwn(components, name))
+            throw new Error(`[ferrovue] no component called ${JSON.stringify(name)} was given to mountPage`);
+        return [name, await loadOrThrow(name, components[name])];
+    });
+    const [root, parts] = await Promise.all([loadOrThrow("the layout", layout), Promise.all(loading), options.router?.isReady()]);
+    const app = createPageApp(root, record, Object.fromEntries(parts), options);
+    app.mount(container);
+    return app;
+}
+async function loadOrThrow(name, component) {
+    const result = await load(component);
+    if (result instanceof Error)
+        throw new Error(`[ferrovue] ${name} did not load: ${result.message}`, { cause: result });
+    return result;
+}

package/dist/compiler.d.ts

@@ -18,6 +18,6 @@ export interface Written {
  * so a Rust build that watches them rebuilds no more than it must, and removing what no component
  * produces any more. */
 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 { CONFIG_FILE, loadConfig, TYPES_MODULE, type Config, type HelperSpec, type TwinSpec, type TypeName } from "./context.ts";
 export { GenError } from "./model.ts";
 export declare const VERSION: string;