ferrovue 0.4.0 → 0.6.0

package/dist/children.js

@@ -1,17 +1,18 @@
 import { isSSRSafeAttrName, propsToAttrMap } from "@vue/shared";
-import { camelize, declares, fail, GenError, rustStr, sameTy, snake, takesAttrs } from "./model.js";
+import { camelize, declares, fail, nothing, rustStr, sameTy, snake, takesAttrs } from "./model.js";
 import { ctx } from "./context.js";
 import { markHome } from "./typescript.js";
-import { expr, fieldVal } from "./expr.js";
+import { expr, fieldVal, holdsNothing } from "./expr.js";
 import { asF64 } from "./numbers.js";
 import { atom, bare } from "./parens.js";
 import { Emitter } from "./emitter.js";
 import { attrOf, dollarAttrs, IGNORED_PROPS, isAttrs, mergedParts } from "./attrs.js";
 import { passedKey } from "./fallthrough.js";
-import { claim, paramsOf, slotFieldsOf } from "./plugin.js";
+import { claim, paramsOf, slotContextOf, slotFieldsOf } from "./plugin.js";
 import { statements } from "./template.js";
 import { slotContent, slotFieldBorrows, staticallyFilled } from "./slots.js";
-export function renderChild(s, e, n) {
+import { slotAsVnodes } from "./dynamic.js";
+export function renderChild(s, e, n, twin) {
     const [target, rawProps, slots, , slotScopeId] = n.arguments;
     let local = null;
     if (target.type === "MemberExpression" && target.object.name === "$setup") {
@@ -19,9 +20,10 @@ export function renderChild(s, e, n) {
     }
     const isSelf = target.type === "Identifier" && target.name === s.selfAlias.name;
     const childName = isSelf ? s.comp.name : local ? s.children.get(local) : undefined;
-    const child = childName ? s.components.get(childName) : undefined;
+    const child = twin?.comp ?? (childName ? s.components.get(childName) : undefined);
     if (!child)
-        fail(s.comp, "a child component must be an imported island", n);
+        fail(s.comp, "FV0501", `a child component must be imported from a \`.vue\` file among the components compiled, in ${ctx.componentsDir.replace(/\/$/, "")}`, n);
+    const later = !twin && local !== null && s.loadedLater.has(local);
     for (const p of ctx.plugins)
         p.child?.(s, child, n);
     const parts = !rawProps || rawProps.type === "NullLiteral" ? [] : mergedParts(rawProps);
@@ -33,30 +35,33 @@ export function renderChild(s, e, n) {
     if (parts.some(passed)) {
         for (const name of s.comp.attrNames) {
             if (declares(child, name)) {
-                fail(s.comp, `\`${name}\`, an attribute ${s.comp.name} may be passed, would reach ${child.name} as its prop \`${camelize(name)}\`, which an attribute has no type for`, n);
+                fail(s.comp, "FV0502", `\`${name}\`, an attribute ${s.comp.name} may be passed, would reach ${child.name} as its prop \`${camelize(name)}\`, which an attribute has no type for`, n);
             }
         }
     }
     const ids = claim((p) => p.childIds?.(s, child, passesAttrs, !!slotScopeId, n)) ?? null;
     if (objects.length === 1 && objects[0].type !== "ObjectExpression") {
+        if (twin)
+            fail(s.comp, "FV1501", `the props of ${child.name}, a Rust twin, are attributes or an object literal`, objects[0]);
         const v = expr(s, objects[0]);
         const own = child.name === s.comp.name && v.ty.k === "struct" && v.ty.name === "Props";
         if (own || (v.ty.k === "child" && v.ty.name === child.name)) {
-            callChild(s, e, child, v.code, slots, childAttrsArg(s, child, parts, merges, null, ids));
+            callChild(s, e, child, v.code, slots, childAttrsArg(s, child, parts, merges, null, ids, n), later);
             return;
         }
-        fail(s.comp, `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, n);
+        fail(s.comp, "FV0503", `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, n);
     }
     for (const p of objects) {
         if (p.type !== "ObjectExpression")
-            fail(s.comp, `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, p);
+            fail(s.comp, "FV0503", `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, p);
     }
     const given = new Map();
-    const fallthrough = new Set();
+    const fallthrough = new Map();
+    const loaded = !merges && local !== null && s.loadedLater.has(local);
     for (const obj of objects) {
         for (const p of obj.properties) {
             if (p.type !== "ObjectProperty" || p.computed)
-                fail(s.comp, "child props hold plain keys", p);
+                fail(s.comp, "FV0504", "child props hold plain keys", p);
             const key = p.key.type === "Identifier" ? p.key.name : String(p.key.value);
             if (!passedKey(child, key))
                 continue;
@@ -66,29 +71,63 @@ export function renderChild(s, e, n) {
                 continue;
             }
             if (array(key))
-                fail(s.comp, `an attribute named \`${key}\`, which JavaScript would put before the others`, p);
+                fail(s.comp, "FV0505", `an attribute named \`${key}\`, which JavaScript would put before the others`, p);
             const name = propsToAttrMap[key] ?? key.toLowerCase();
             if (key !== "class" && key !== "style" && !isSSRSafeAttrName(name))
-                fail(s.comp, `unsafe attribute name \`${name}\``, p);
-            fallthrough.add(p);
+                fail(s.comp, "FV0404", `unsafe attribute name \`${name}\``, p);
+            fallthrough.set(p, loaded && key === "class" ? loadedClass(s, p.value) : p.value);
         }
     }
+    if (twin) {
+        const inits = child.props.fields.map((f) => twin.init(s, f, given.get(f.js), n));
+        twin.call(s, e, inits, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n));
+        return;
+    }
     const inits = child.props.fields.map((f) => {
         const node = given.get(f.js);
         if (!node) {
             if (f.ty.k !== "opt")
-                fail(s.comp, `${child.name} requires \`${f.js}\``, n);
+                fail(s.comp, "FV0506", `${child.name} requires \`${f.js}\``, n);
+            if (f.ty.none !== undefined)
+                fail(s.comp, "FV0507", `${child.name} requires \`${f.js}\`, which is \`T | null\`: Vue would hand it \`undefined\`; pass \`null\` for none`, n);
             return `${f.rust}: None`;
         }
         const v = expr(s, node);
         return fieldInit(f.rust, ownInto(s.comp, { ...v, ty: markHome(v.ty, s.comp.name) }, markHome(f.ty, child.name), node));
     });
-    callChild(s, e, child, `&super::${child.module}::Props { ${inits.join(", ")} }`, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids));
+    callChild(s, e, child, `&super::${child.module}::Props { ${inits.join(", ")} }`, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n), later);
 }
 export function array(key) {
     return /^(0|[1-9]\d*)$/.test(key) && Number(key) < 2 ** 32 - 1;
 }
-function childAttrsArg(s, child, parts, merges, fallthrough, ids) {
+/** A string `:class` given to a component `defineAsyncComponent` loads, in props no `mergeProps`
+ * normalised: Vue's wrapper hands on the class once as written and once trimmed, so a class with
+ * whitespace around it is written twice. */
+const lengthOf = (n) => ({ type: "MemberExpression", object: n, property: { type: "Identifier", name: "length" }, computed: false });
+function holdsClassLiteral(n) {
+    if (n.type === "ObjectExpression" || n.type === "ArrayExpression")
+        return true;
+    if (n.type === "ConditionalExpression")
+        return holdsClassLiteral(n.consequent) || holdsClassLiteral(n.alternate);
+    if (n.type === "LogicalExpression")
+        return holdsClassLiteral(n.left) || holdsClassLiteral(n.right);
+    return false;
+}
+function loadedClass(s, value) {
+    if (value.type === "ConditionalExpression" && (holdsClassLiteral(value.consequent) || holdsClassLiteral(value.alternate))) {
+        return { ...value, consequent: loadedClass(s, value.consequent), alternate: loadedClass(s, value.alternate) };
+    }
+    if (holdsClassLiteral(value) || expr(s, value).ty.k !== "str")
+        return value;
+    const trimmed = { type: "CallExpression", callee: { type: "MemberExpression", object: value, property: { type: "Identifier", name: "trim" }, computed: false }, arguments: [] };
+    return {
+        type: "ConditionalExpression",
+        test: { type: "BinaryExpression", operator: "===", left: lengthOf(trimmed), right: lengthOf(value) },
+        consequent: value,
+        alternate: { type: "ArrayExpression", elements: [trimmed, value] },
+    };
+}
+function childAttrsArg(s, child, parts, merges, fallthrough, ids, n) {
     const sources = [];
     for (const p of parts) {
         if (s.fallthrough !== null && ((isAttrs(p) && s.comp.inheritAttrs) || dollarAttrs(s, p))) {
@@ -97,7 +136,7 @@ function childAttrsArg(s, child, parts, merges, fallthrough, ids) {
         else if (p.type === "ObjectExpression" && fallthrough !== null) {
             const entries = p.properties.filter((q) => fallthrough.has(q)).map((q) => {
                 const key = q.key.type === "Identifier" ? q.key.name : String(q.key.value);
-                return `(${rustStr(key)}, ${attrOf(s, key, q.value, "vnode")})`;
+                return `(${rustStr(key)}, ${attrOf(s, key, fallthrough.get(q), "vnode")})`;
             });
             if (entries.length)
                 sources.push(`&[${entries.join(", ")}]`);
@@ -105,7 +144,7 @@ function childAttrsArg(s, child, parts, merges, fallthrough, ids) {
     }
     if (!takesAttrs(child)) {
         if (sources.length)
-            throw new GenError(`${s.comp.file}: ${child.name} is passed attributes it does not take`);
+            fail(s.comp, "FV0508", `${child.name} is passed attributes it does not take`, n);
         return ids;
     }
     if (!sources.length)
@@ -120,34 +159,48 @@ export function fieldInit(name, value) {
 export function takesSlots(c) {
     return c.slotNames.length > 0 || slotFieldsOf(c).length > 0;
 }
-export function extraParams(c) {
-    return (takesSlots(c) ? ", fv_slots: Slots<'_>" : "") + paramsOf(c).map((p) => `, ${p.name}: ${p.ty}`).join("");
+export function extraParams(c, unread = () => false) {
+    return (takesSlots(c) ? ", fv_slots: Slots<'_>" : "") + paramsOf(c).map((p) => `, ${unread(p.name) ? "_" : ""}${p.name}: ${p.ty}`).join("");
+}
+export function callChild(s, e, child, propsCode, slots, attrs, later = false) {
+    const m = `super::${child.module}`;
+    const scoped = child.inherits || takesAttrs(child);
+    const trailing = paramsOf(child).map((p) => `, ${p.name}`).join("") + (scoped ? `, ${attrs ?? (takesAttrs(child) ? "&fv::Attrs::NONE" : '""')}` : "");
+    const render = scoped ? "render_scoped" : "render";
+    const around = later ? ctx.plugins.flatMap((p) => p.loadedLater?.(child) ?? []) : [];
+    if (around.length) {
+        e.open("");
+        for (const line of around)
+            e.stmt(line);
+    }
+    callWith(s, e, child, m, `${m}::${render}(out, ${propsCode}`, `${m}::Slots`, trailing, slots);
+    if (around.length)
+        e.close();
 }
-export function callChild(s, e, child, propsCode, slots, attrs) {
+export function callWith(s, e, child, m, head, slotsTy, trailing, slots, vnode = false) {
     const given = new Map();
     if (slots && slots.type !== "NullLiteral") {
         if (slots.type !== "ObjectExpression")
-            fail(s.comp, "slots must be an object literal", slots);
+            fail(s.comp, "FV0901", "slots must be an object literal", slots);
         for (const p of slots.properties) {
             const key = p.key?.type === "Identifier" ? p.key.name : p.key?.value;
             if (key === "_")
                 continue;
             if (p.type !== "ObjectProperty" || p.computed)
-                fail(s.comp, "slots hold plain keys", p);
+                fail(s.comp, "FV0902", "slots hold plain keys", p);
             if (!child.slotNames.includes(key))
-                fail(s.comp, `${child.name} has no slot \`${key}\``, p);
+                fail(s.comp, "FV0903", `${child.name} has no slot \`${key}\``, p);
             given.set(key, p.value);
         }
     }
-    const m = `super::${child.module}`;
-    const scoped = child.inherits || takesAttrs(child);
-    const trailing = paramsOf(child).map((p) => `, ${p.name}`).join("") + (scoped ? `, ${attrs ?? (takesAttrs(child) ? "&fv::Attrs::NONE" : '""')}` : "");
-    const render = scoped ? "render_scoped" : "render";
     if (!takesSlots(child)) {
-        e.stmt(`${m}::${render}(out, ${propsCode}${trailing});`);
+        e.stmt(`${head}${trailing});`);
         return;
     }
-    e.open(`${m}::${render}(out, ${propsCode}, ${m}::Slots`);
+    e.open(`${head}, ${slotsTy}`);
+    const context = slotContextOf(child);
+    const contextParams = context.map((p) => `, ${p.name}: ${p.ty}`).join("");
+    const opaque = vnode ? child.name : s.opaque;
     for (const name of child.slotNames) {
         const field = snake(name);
         const value = given.get(name);
@@ -156,6 +209,7 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
             continue;
         }
         const { body, param } = slotContent(s, value);
+        const asVnodes = vnode || s.vnode || slotAsVnodes(child, name);
         const shape = child.slotShapes.get(name);
         const takesNone = param?.type === "Identifier" && param.name === "_";
         const sid = child.passesSlotIds ? `fv_sid${++ctx.narrowCount}` : null;
@@ -182,7 +236,7 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
             if (param?.type === "ObjectPattern") {
                 for (const p of param.properties) {
                     if (p.type !== "ObjectProperty" || p.computed || p.value.type !== "Identifier") {
-                        fail(s.comp, "slot props are destructured into plain names, without defaults", p);
+                        fail(s.comp, "FV0904", "slot props are destructured into plain names, without defaults", p);
                     }
                     locals.set(p.value.name, fieldVal(s.comp, sp, ty, p.key.name ?? p.key.value, p));
                 }
@@ -191,20 +245,31 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
                 locals.set(param.name, { code: sp, ty });
             }
             else if (!takesNone)
-                fail(s.comp, "slot props are a name or an object pattern", param);
+                fail(s.comp, "FV0905", "slot props are a name or an object pattern", param);
             const life = shape.fields.some((f) => slotFieldBorrows(f.ty)) ? "<'_>" : "";
-            e.open(`${field}: Some(&|out: &mut String, ${sp}: &${m}::${shape.name}${life}${sidParam}| -> bool`);
+            e.open(`${field}: Some(&|out: &mut String, ${sp}: &${m}::${shape.name}${life}${sidParam}${contextParams}| -> bool`);
             const opened = e.lines.length - 1;
-            content({ ...s, locals, sid });
+            content({ ...s, locals, sid, vnode: asVnodes, opaque });
             unread(opened, sp);
             unread(opened, sid);
+            for (const p of context)
+                unread(opened, p.name);
             e.close("),");
             continue;
         }
         if (!takesNone)
-            fail(s.comp, `\`<slot${name === "default" ? "" : ` name="${name}"`}>\` in ${child.name} passes no props`, param);
-        const inner = { ...s, sid };
-        if (sid !== null) {
+            fail(s.comp, "FV0906", `\`<slot${name === "default" ? "" : ` name="${name}"`}>\` in ${child.name} passes no props`, param);
+        const inner = { ...s, sid, vnode: asVnodes, opaque };
+        if (context.length) {
+            e.open(`${field}: Some(&|out: &mut String${sidParam}${contextParams}| -> bool`);
+            const opened = e.lines.length - 1;
+            content(inner);
+            unread(opened, sid);
+            for (const p of context)
+                unread(opened, p.name);
+            e.close("),");
+        }
+        else if (sid !== null) {
             e.open(`${field}: Some(fv::Slot::slotted(&|out: &mut String${sidParam}| -> bool`);
             const opened = e.lines.length - 1;
             content(inner);
@@ -227,14 +292,15 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
     e.close(`${trailing});`);
 }
 export function ownInto(comp, v, want, node) {
+    holdsNothing(comp, v, want, node, "the prop");
+    if (want.k === "opt" && nothing(v.ty))
+        return "None";
     if (want.k === "str") {
         if (v.ty.k !== "str")
-            fail(comp, "a string prop needs a string", node);
+            fail(comp, "FV0509", "a string prop needs a string", node);
         return `std::borrow::Cow::Borrowed(${bare(v.code)})`;
     }
     if (want.k === "opt" && want.of.k === "str") {
-        if (v.ty.k === "undef")
-            return "None";
         if (v.ty.k === "str")
             return `Some(std::borrow::Cow::Borrowed(${bare(v.code)}))`;
         if (v.ty.k === "opt" && v.ty.of.k === "str")
@@ -257,7 +323,7 @@ export function ownInto(comp, v, want, node) {
     if (want.k === "opt" && objecty(want.of) && sameTy(v.ty, want.of))
         return `Some(${atom(v.code)}.to_owned())`;
     if (objecty(want) && v.ty.k === want.k && JSON.stringify(v.ty).includes('"struct"')) {
-        fail(comp, `a ${JSON.stringify(v.ty)} where the child takes a ${JSON.stringify(want)}: two components share a type only when both import it from one \`.ts\` file`, node);
+        fail(comp, "FV0510", `a ${JSON.stringify(v.ty)} where the child takes a ${JSON.stringify(want)}: two components share a type only when both import it from one \`.ts\` file`, node);
     }
     if (want.k === "list" && v.ty.k === "list" && v.ty.of.k === "undef")
         return "Vec::new()";
@@ -269,5 +335,5 @@ export function ownInto(comp, v, want, node) {
         if (want.of.k === "int" || want.of.k === "float" || want.of.k === "bool")
             return `${atom(v.code)}.to_vec()`;
     }
-    return fail(comp, `a ${JSON.stringify(v.ty)} into a ${JSON.stringify(want)} prop`, node);
+    return fail(comp, "FV0511", `a ${JSON.stringify(v.ty)} into a ${JSON.stringify(want)} prop`, node);
 }

package/dist/classes.d.ts

@@ -7,6 +7,10 @@ export type ClassItem = {
 };
 export declare function classItems(s: Scope, n: N): ClassItem[];
 export declare function renderClass(s: Scope, e: Emitter, n: N, after?: boolean): void;
+/** The class list of an element in content Vue renders from virtual nodes, in the order Vue's
+ * client compiler merges a static `class` written before `:class`: the static names first, at the
+ * place of the static `class`. */
+export declare function vnodeClass(s: Scope, n: N): N;
 export declare function classPresent(s: Scope, n: N): string;
 export declare function maybeEqual(s: Scope, n: N): boolean;
 export declare function literalClass(n: N): string | null;

package/dist/classes.js

@@ -1,5 +1,5 @@
 import { escapeHtml } from "@vue/shared";
-import { fail, rustStr, STR } from "./model.js";
+import { directiveOwner, fail, nothing, rustStr, STR } from "./model.js";
 import { expr } from "./expr.js";
 import { cond, known, truthy } from "./narrowing.js";
 import { meet } from "./strings.js";
@@ -25,10 +25,10 @@ export function classItems(s, n) {
                 const keys = [];
                 const entries = n.properties.map((p) => {
                     if (p.type !== "ObjectProperty")
-                        fail(s.comp, "a class object holds `name: condition` pairs", p);
+                        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, "a computed class name is a string", p.key);
+                        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);
@@ -38,18 +38,18 @@ export function classItems(s, n) {
             }
             return n.properties.flatMap((p) => {
                 if (p.type !== "ObjectProperty")
-                    fail(s.comp, "a class object holds `name: condition` pairs", p);
+                    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, `class name \`${key}\` has spaces around it`, p);
+                        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, "a computed class name is a string", p.key);
+                        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);
@@ -77,9 +77,9 @@ export function classItems(s, n) {
         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")
+    if (nothing(v.ty))
         return [];
-    return fail(s.comp, "a class is a string, an array, or an object of conditions", n);
+    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")
@@ -102,6 +102,28 @@ export function renderClass(s, e, n, after = false) {
         e.stmt(`fv::class_into(out, ${wrote}, &[${rest.join(", ")}]);`);
     }
 }
+const UNWRITTEN = new Set(["on", "if", "else-if", "else", "for", "slot", "once", "memo", "cloak", "pre"]);
+/** The class list of an element in content Vue renders from virtual nodes, in the order Vue's
+ * client compiler merges a static `class` written before `:class`: the static names first, at the
+ * place of the static `class`. */
+export function vnodeClass(s, n) {
+    const last = n.type === "ArrayExpression" ? n.elements.at(-1) : null;
+    if (n.fvMerged || last?.type !== "StringLiteral" || n.elements.length < 2)
+        return n;
+    const el = directiveOwner(s.comp, n.elements[0]);
+    if (!el)
+        return n;
+    const own = el.props.findIndex((p) => p.type === 6 && p.name === "class");
+    const bound = el.props.findIndex((p) => p.type === 7 && p.name === "bind" && p.arg?.content === "class");
+    if (own < 0 || bound < own)
+        return n;
+    const between = el.props.slice(own + 1, bound).find((p) => p.type === 6 || !UNWRITTEN.has(p.name));
+    if (between) {
+        const at = { type: "VueTemplate", loc: { start: { line: between.loc.start.line, column: between.loc.start.column - 1 } }, __fv: "source" };
+        fail(s.comp, "FV1013", "in content Vue renders from virtual nodes, a `class` written before `:class` is written where the `class` stands, and Vue's server compiler moves it to where `:class` stands; write the two next to each other, or `:class` first", at);
+    }
+    return { ...n, elements: [last, ...n.elements.slice(0, -1)] };
+}
 export function classPresent(s, n) {
     if (n.fvMerged)
         return n.elements.reduce((acc, el) => logical(acc, "||", classPresent(s, el)), "false");
@@ -123,7 +145,7 @@ export function classPresent(s, n) {
             break;
     }
     const v = expr(s, n);
-    if (v.ty.k === "undef")
+    if (nothing(v.ty))
         return "false";
     if (v.ty.k === "opt")
         return `${atom(v.code)}.is_some()`;
@@ -170,7 +192,7 @@ export function classAttr(s, n, side) {
             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"))
+    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, "a class is a string, an array, or an object of conditions", n);
+    return fail(s.comp, "FV1004", "a class is a string, an array, or an object of conditions", n);
 }

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 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]
 
@@ -14,16 +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
 `;
+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);
@@ -77,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 {
@@ -104,6 +116,8 @@ 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}`);
 }
@@ -137,7 +151,7 @@ function watchProject(configPath) {
             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);
@@ -155,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);
         }
@@ -169,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 {
@@ -15,10 +15,11 @@ export interface MountOptions {
     /** Where to look for islands: the whole document by default. */
     root?: ParentNode;
     /** Told about an island left as the server rendered it, because its component is not among
-     * those given or its props are malformed. Warns on the console by default. */
+     * those given, did not load or its props are malformed, and about one hydrated at once because
+     * its `data-hydrate` is not one this version knows. 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
@@ -28,13 +29,50 @@ export type IslandComponent = Component | (() => Promise<Component | {
 }>);
 /** The islands mounted. */
 export interface Islands {
-    /** One app per island, in document order. */
+    /** One app per island hydrated so far: those hydrated at once in document order, then each
+     * island with a `data-hydrate` as it hydrates. */
     apps: App[];
-    /** Unmount every island, as a page leaving would. */
+    /** Unmount every island and stop waiting to hydrate the others, as a page leaving would. */
     unmount(): void;
 }
 /** 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. 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. */
+ * of them at once, and the islands mount in document order once every one has loaded. An island
+ * with a `data-hydrate` (`Html::hydrate`) waits instead: once it is visible (or within a root margin
+ * of the viewport), the browser is idle,
+ * it is interacted with or a media query matches, its component is loaded and it hydrates. */
 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>;