ferrovue 0.4.0 → 0.5.0

package/dist/client.js

@@ -1,4 +1,4 @@
-import { createSSRApp } from "vue";
+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 };
 function parseJson(text) {
@@ -11,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;
@@ -74,6 +74,32 @@ export async function mountIslands(components, options = {}) {
         },
     };
 }
+/** 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;
@@ -85,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;

package/dist/compiler.js

@@ -1,7 +1,7 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { ctx, loadConfig, tyOfName } from "./context.js";
-import { readComponent } from "./component.js";
+import { importsOf, readComponent } from "./component.js";
 import { scopeFor } from "./script.js";
 import { attrsFlow } from "./fallthrough.js";
 import { componentSource, isIsland, modSource } from "./rust.js";
@@ -12,12 +12,15 @@ export function generate(root, config = loadConfig(root)) {
     ctx.componentsDir = config.components.replace(/\/?$/, "/");
     ctx.helperModule = config.helpers?.module ?? null;
     ctx.trustedHtml = config.trustedHtml ?? null;
+    ctx.builders = config.builders ?? true;
     ctx.clientDirectives = new Set(config.clientDirectives ?? []);
     ctx.rootDir = root;
     ctx.typeStructs = new Map();
     ctx.typeAliases = new Map();
     ctx.typeFiles = new Map();
     ctx.typeRead = new Set();
+    ctx.constDecls = new Map();
+    ctx.typeConsts = new Map();
     ctx.plugins = PLUGINS;
     ctx.runs = new Map();
     for (const p of PLUGINS)
@@ -33,7 +36,8 @@ export function generate(root, config = loadConfig(root)) {
         .filter((f) => f.endsWith(".vue"))
         .toSorted()
         .map((f) => join(dir, f));
-    const read = files.map((f) => readComponent(f, root));
+    const children = new Set(files.flatMap((f) => importsOf(readFileSync(f, "utf8")).filter((c) => c !== basename(f, ".vue"))));
+    const read = files.map((f) => readComponent(f, root, children.has(basename(f, ".vue"))));
     const components = new Map(read.map((r) => [r.comp.name, r.comp]));
     ctx.components = components;
     const scopes = read.map((r) => scopeFor(r.comp, r.ast, components).scope);

package/dist/component.d.ts

@@ -1,5 +1,7 @@
 import { type Component, type N } from "./model.ts";
-export declare function readComponent(file: string, root: string): {
+/** The `.vue` files a component imports, by name. */
+export declare function importsOf(source: string): string[];
+export declare function readComponent(file: string, root: string, isChild: boolean): {
     comp: Component;
     ast: N[];
     ssr: string;

package/dist/component.js

@@ -1,11 +1,13 @@
+import { parse as parseJs } from "@babel/parser";
 import { compileScript, compileTemplate, parse as parseSfc } from "@vue/compiler-sfc";
 import { readFileSync } from "node:fs";
 import { SourceMapConsumer } from "source-map-js";
 import { basename, relative } from "node:path";
-import { blankComponent, fail, opt, snake, tagAst } from "./model.js";
+import { absence, blankComponent, fail, GenError, opt, snake, sourceAt, tagAst } from "./model.js";
 import { ctx } from "./context.js";
-import { typesImports, declareTypes, defaultValue, definePropsType, readTypeFile, resolveImport, runtimeDefaults, structOf, tyOfTs } from "./typescript.js";
+import { typesImports, declareTypes, defaultValue, definePropsType, ONE_NOTHING, readTypeFile, resolveImport, runtimeDefaults, structOf, tyOfTs } from "./typescript.js";
 import { claim } from "./plugin.js";
+import { asyncChildren } from "./script.js";
 function vueErrorNode(err, within) {
     const loc = err.loc;
     if (!loc)
@@ -29,13 +31,90 @@ function inheritAttrs(comp, statements) {
             if (p.type !== "ObjectProperty" || p.computed || (p.key.name ?? p.key.value) !== "inheritAttrs")
                 continue;
             if (p.value.type !== "BooleanLiteral")
-                fail(comp, "`inheritAttrs` is `true` or `false`", p.value);
+                fail(comp, "FV0101", "`inheritAttrs` is `true` or `false`", p.value);
             found = p.value.value;
         }
     }
     return found;
 }
-export function readComponent(file, root) {
+function sourceDefault(ast, key) {
+    const named = (p) => (p.key?.name ?? p.key?.value) === key;
+    for (const st of ast) {
+        for (const d of st.type === "VariableDeclaration" ? st.declarations : []) {
+            if (d.id.type !== "ObjectPattern" || !definePropsType(d.init))
+                continue;
+            const p = d.id.properties.find((q) => q.type === "ObjectProperty" && named(q));
+            if (p?.value.type === "AssignmentPattern")
+                return p.value.right;
+        }
+        const call = st.type === "ExpressionStatement" ? st.expression : st.type === "VariableDeclaration" ? st.declarations[0]?.init : null;
+        if (call?.type !== "CallExpression" || call.callee.name !== "withDefaults" || call.arguments[1]?.type !== "ObjectExpression")
+            continue;
+        const p = call.arguments[1].properties.find((q) => q.type === "ObjectProperty" && named(q));
+        if (p)
+            return p.value;
+    }
+    return null;
+}
+function blockAt(source, block) {
+    return sourceAt(source, source.lastIndexOf(`<${block.type}`, block.loc.start.offset));
+}
+/** The `.vue` files a component imports, by name. */
+export function importsOf(source) {
+    return [...source.matchAll(/\bfrom\s*["'](?:[^"']*\/)?([^"'/]+)\.vue["']/g)].map((m) => m[1]);
+}
+function generics(comp, source, block) {
+    const text = block.attrs.generic;
+    if (typeof text !== "string")
+        return;
+    const open = source.lastIndexOf("<script", block.loc.start.offset);
+    const attr = source.slice(open, block.loc.start.offset).search(/\bgeneric\s*=\s*["']/);
+    const valueAt = open + attr + /^generic\s*=\s*["']/.exec(source.slice(open + attr))[0].length;
+    const at = sourceAt(source, valueAt).loc.start;
+    const prefix = "type T<";
+    let params;
+    try {
+        params = parseJs(`${prefix}${text}> = 0;`, { sourceType: "module", plugins: ["typescript"] }).program.body[0].typeParameters.params;
+    }
+    catch {
+        return fail(comp, "FV0301", "`generic` is a list of type parameters, as `T extends string`", sourceAt(source, valueAt));
+    }
+    const rebase = (n) => {
+        if (!n || typeof n !== "object")
+            return;
+        if (Array.isArray(n))
+            return n.forEach(rebase);
+        const start = n.loc?.start;
+        if (start && typeof n.type === "string") {
+            n.loc = { ...n.loc, start: start.line === 1 ? { line: at.line, column: at.column + start.column - prefix.length } : { line: at.line + start.line - 1, column: start.column } };
+        }
+        for (const [k, v] of Object.entries(n))
+            if (k !== "loc" && v && typeof v === "object")
+                rebase(v);
+    };
+    rebase(params);
+    tagAst(params, "source");
+    for (const p of params) {
+        const name = typeof p.name === "string" ? p.name : p.name.name;
+        if (!p.constraint)
+            fail(comp, "FV0302", `\`${name}\` in \`generic\` has no constraint: the server renders \`${name}\` as the type it extends, \`${name} extends string\``, p);
+        comp.aliases.set(name, p.constraint);
+    }
+}
+function scriptOf(comp, descriptor) {
+    try {
+        return compileScript(descriptor, { id: comp.name });
+    }
+    catch (e) {
+        if (!(e instanceof SyntaxError))
+            throw e;
+        const at = e.loc;
+        const block = descriptor.scriptSetup.loc.start;
+        const where = !at || descriptor.script ? {} : at.line === 1 ? { line: block.line, column: block.column + at.column } : { line: block.line + at.line - 1, column: at.column + 1 };
+        throw new GenError("FV0001", e.message, { file: comp.file, ...where }, e.message.split("\n")[0]);
+    }
+}
+export function readComponent(file, root, isChild) {
     const name = basename(file, ".vue");
     const source = readFileSync(file, "utf8");
     const { descriptor, errors } = parseSfc(source, { filename: file });
@@ -43,22 +122,26 @@ export function readComponent(file, root) {
     const comp = blankComponent(name, snake(name), rel);
     comp.source = source;
     if (errors.length)
-        fail(comp, String(errors[0]), vueErrorNode(errors[0]));
-    if (!descriptor.scriptSetup || !descriptor.template) {
-        fail(comp, "an island needs `<script setup lang=\"ts\">` and a `<template>`");
+        fail(comp, "FV0002", String(errors[0]), vueErrorNode(errors[0]));
+    if (descriptor.script && !descriptor.scriptSetup) {
+        const needs = isChild ? "a child component must have" : "an island needs";
+        fail(comp, "FV0003", `${needs} \`<script setup lang="ts">\`, or no script at all: a \`<script>\` without \`setup\` (the Options API, \`defineComponent\`) is not translated`, blockAt(source, descriptor.script));
     }
+    if (!descriptor.template)
+        fail(comp, "FV0004", "a component needs a `<template>`: a render function is not translated", sourceAt(source, 0));
     for (const st of descriptor.styles) {
         if (st.module)
-            fail(comp, "`<style module>` renames classes in the bundler; use a global or scoped `<style>`, or a stylesheet");
+            fail(comp, "FV1005", "`<style module>` renames classes in the bundler; use a global or scoped `<style>`, or a stylesheet", blockAt(source, st));
     }
+    const cssVar = descriptor.styles.find((st) => /\bv-bind\s*\(/.test(st.content));
     if (descriptor.cssVars.length)
-        fail(comp, "`v-bind()` in `<style>` sets variables the server does not render; bind `:style` instead");
+        fail(comp, "FV1006", "`v-bind()` in `<style>` sets variables the server does not render; bind `:style` instead", cssVar ? blockAt(source, cssVar) : undefined);
     for (const p of ctx.plugins)
         p.sfc?.(comp, descriptor, file, source);
-    const script = compileScript(descriptor, { id: name });
-    const ast = script.scriptSetupAst ?? [];
+    const script = descriptor.scriptSetup ? scriptOf(comp, descriptor) : null;
+    const ast = script?.scriptSetupAst ?? [];
     tagAst(ast, "source");
-    const plainAst = script.scriptAst ?? [];
+    const plainAst = script?.scriptAst ?? [];
     tagAst(plainAst, "source");
     for (const s of [...plainAst, ...ast]) {
         if (s.type !== "ImportDeclaration" || !s.source.value.endsWith(".vue"))
@@ -72,6 +155,8 @@ export function readComponent(file, root) {
             }
         }
     }
+    for (const loaded of asyncChildren(comp, ast).values())
+        comp.imports.add(loaded);
     typesImports(comp, [...plainAst, ...ast]);
     comp.inheritAttrs = inheritAttrs(comp, [...plainAst, ...ast]);
     for (const st of [...plainAst, ...ast]) {
@@ -102,6 +187,8 @@ export function readComponent(file, root) {
                 comp.aliases.set(sp.local.name, ctx.typeAliases.get(typeName));
         }
     }
+    if (descriptor.scriptSetup)
+        generics(comp, source, descriptor.scriptSetup);
     const decls = declareTypes(comp, [...plainAst, ...ast], comp.structs, comp.aliases);
     for (const d of decls)
         comp.structs.set(d.name, structOf(comp, d.name, d.members, comp.structs));
@@ -110,7 +197,7 @@ export function readComponent(file, root) {
         const call = s.type === "ExpressionStatement" ? s.expression : s.type === "VariableDeclaration" ? s.declarations[0]?.init : null;
         const inner = call?.type === "CallExpression" && call.callee.type === "Identifier" && call.callee.name === "withDefaults" ? call.arguments[0] : call;
         if (inner?.type === "CallExpression" && inner.callee.type === "Identifier" && inner.callee.name === "defineProps" && !inner.typeParameters) {
-            fail(comp, "props are declared with a type, `defineProps<{ ... }>()`: a runtime declaration has no Rust type", inner);
+            fail(comp, "FV0303", "props are declared with a type, `defineProps<{ ... }>()`: a runtime declaration has no Rust type", inner);
         }
         const found = definePropsType(call);
         if (found)
@@ -125,7 +212,7 @@ export function readComponent(file, root) {
         comp.props = { name: "Props", fields: comp.structs.get(propsTy.typeName.name).fields };
     }
     else {
-        fail(comp, "`defineProps` takes a type literal or an interface declared in the same block", propsTy);
+        fail(comp, "FV0304", "`defineProps` takes a type literal or an interface declared in the same block", propsTy);
     }
     for (const st of ast) {
         if (st.type !== "VariableDeclaration")
@@ -136,22 +223,29 @@ export function readComponent(file, root) {
                 continue;
             const t = call.typeParameters?.params?.[0];
             if (!t)
-                fail(comp, "`defineModel` needs its type: `defineModel<string>()`", call);
+                fail(comp, "FV0305", "`defineModel` needs its type: `defineModel<string>()`", call);
             const named = call.arguments[0]?.type === "StringLiteral" ? call.arguments[0].value : "modelValue";
             const options = call.arguments.find((a) => a.type === "ObjectExpression");
             const required = options?.properties.some((p) => p.type === "ObjectProperty" && (p.key.name ?? p.key.value) === "required" && p.value.type === "BooleanLiteral" && p.value.value);
             const base = tyOfTs(comp, t, comp.structs);
+            if (!required && absence(base) === "null")
+                fail(comp, "FV0306", `a \`defineModel\` of \`T | null\` that is not \`required\` may be absent, which is \`undefined\`, or \`null\`: ${ONE_NOTHING}`, call);
             comp.props.fields.push({ js: named, rust: snake(named), ty: required ? base : opt(base) });
             comp.models.set(d.id.name, named);
         }
     }
-    const defaults = runtimeDefaults(comp, script.content);
+    const defaults = runtimeDefaults(comp, script?.content ?? "");
     for (const f of comp.props.fields) {
         if (f.ty.k !== "opt")
             continue;
         const node = defaults.get(f.js);
+        if (f.ty.none !== undefined) {
+            if (node)
+                fail(comp, "FV0307", `a default for \`${f.js}\`, which is \`T | null\`: Vue gives it only when \`${f.js}\` is absent, which its Rust type, an \`Option\`, cannot be; fall back in the template with \`??\``, sourceDefault(ast, f.js) ?? node);
+            continue;
+        }
         if (node)
-            f.dflt = defaultValue(comp, f, node);
+            f.dflt = defaultValue(comp, f, node, sourceDefault(ast, f.js) ?? undefined);
         else if (f.ty.of.k === "bool")
             f.dflt = "false";
     }
@@ -161,7 +255,7 @@ export function readComponent(file, root) {
         ...(claim((p) => p.templateOptions?.(comp)) ?? { id: name, scoped: false, slotted: false }),
         ssr: true,
         ssrCssVars: [],
-        compilerOptions: { bindingMetadata: script.bindings, sourceMap: true },
+        compilerOptions: { ...(script ? { bindingMetadata: script.bindings } : {}), sourceMap: true },
     });
     const kids = (n) => n.children.filter((c) => c.type !== 3 && !(c.type === 2 && !c.content.trim()));
     const roots = descriptor.template.ast ? kids(descriptor.template.ast) : [];
@@ -172,12 +266,13 @@ export function readComponent(file, root) {
         if (!lone)
             comp.attrsDropped = { type: "VueTemplate", loc: { start: { line: wrapper.loc.start.line, column: wrapper.loc.start.column - 1 } }, __fv: "source" };
     }
+    comp.templateAst = descriptor.template.ast;
     const start = descriptor.template.loc.start;
     comp.templateStart = { line: start.line, column: start.column };
     if (compiled.map)
         comp.templateMap = new SourceMapConsumer(compiled.map);
     if (compiled.errors.length)
-        fail(comp, String(compiled.errors[0]), vueErrorNode(compiled.errors[0], comp.templateStart));
+        fail(comp, "FV0005", String(compiled.errors[0]), vueErrorNode(compiled.errors[0], comp.templateStart));
     for (const m of compiled.code.matchAll(/_ssrRenderSlot\(_ctx\.\$slots, "([^"]+)"/g)) {
         if (!comp.slotNames.includes(m[1]))
             comp.slotNames.push(m[1]);

package/dist/constants.d.ts

@@ -0,0 +1,42 @@
+import { type Component, type N, type Scope, type Val } from "./model.ts";
+export type Const = {
+    k: "scalar";
+    js: Scalar;
+} | {
+    k: "list";
+    items: Const[];
+    node: N;
+    home: Component;
+    path: string;
+    typed: string | null;
+} | {
+    k: "object";
+    fields: Map<string, Const>;
+    node: N;
+    home: Component;
+    name: string;
+};
+type Scalar = string | number | boolean | null;
+export interface Declared {
+    node: N;
+    home: Component;
+    exported: boolean;
+}
+/** Remember the constants and enums a file declares at its top level, to evaluate when one is used. */
+export declare function declareConsts(home: Component, body: N[]): Map<string, Declared>;
+/** What a declared constant or enum stands for, evaluated once. */
+export declare function constOfDecl(d: Declared): Const;
+/** The type an enum stands for: the union of its members' literal types. */
+export declare function enumType(home: Component, d: N): N;
+/** What a constant is as a value in Rust; an object has none, only its fields. */
+export declare function constVal(c: Const, at: {
+    comp: Component;
+    node: N;
+    what: string;
+}): Val;
+/** The constant an expression names: an imported or enum binding, or a field of one. */
+export declare function constOf(s: Scope, n: N): {
+    c: Const;
+    what: string;
+} | null;
+export {};