ferrovue 0.3.0 → 0.4.0

package/dist/rust.js

@@ -1,17 +1,17 @@
-/* The Rust source written for each component, and the modules beside them. */
 import { parse as parseJs } from "@babel/parser";
 import { basename } from "node:path";
-import { fail, GenError, rustStr, snake, tagAst, takesAttrs } from "./model.js";
-import { allRoutes, ctx } from "./context.js";
+import { blankComponent, fail, GenError, rustStr, snake, tagAst, takesAttrs } from "./model.js";
+import { ctx } from "./context.js";
 import { lookupStruct } from "./typescript.js";
 import { childOf } from "./expr.js";
 import { Emitter } from "./emitter.js";
-import { extraParams, fieldInit, slotFieldBorrows, slotFieldTy, slotTypeName, statements, takesSlots } from "./template.js";
-import { storeHome } from "./stores.js";
+import { statements } from "./template.js";
+import { slotFieldBorrows, slotFieldTy, slotTypeName } from "./slots.js";
+import { extraParams, fieldInit, takesSlots } from "./children.js";
+import { paramsOf, renderParams, slotFieldsOf } from "./plugin.js";
 import { scopeFor } from "./script.js";
 export function needsLifetime(ty, comp, seen = new Set()) {
     switch (ty.k) {
-        // A record's keys are strings.
         case "str":
         case "record":
             return true;
@@ -19,7 +19,6 @@ export function needsLifetime(ty, comp, seen = new Set()) {
         case "list":
             return needsLifetime(ty.of, comp, seen);
         case "struct": {
-            // A struct that holds itself borrows only if something else in it does.
             if (seen.has(ty.name))
                 return false;
             const { st, owner } = lookupStruct(comp, ty);
@@ -30,7 +29,6 @@ export function needsLifetime(ty, comp, seen = new Set()) {
             const child = childOf(ty.name);
             return structLifetime(child.props, child);
         }
-        // A configured type that borrows says so by naming the props' lifetime: `Trusted<'a>`.
         case "html":
             return ctx.trustedHtml?.includes("'a") ?? false;
         default:
@@ -72,8 +70,6 @@ export function rustTy(ty, comp) {
             throw new GenError("no Rust type for `undefined`");
     }
 }
-/** A constructor parameter for a field of type \`ty\`, and how its argument becomes the field's
- * value: strings from anything that turns into a \`Cow\`, lists of them from any iterator. */
 function param(ty, comp, arg) {
     if (ty.k === "str")
         return { ty: "impl Into<Cow<'a, str>>", value: `${arg}.into()` };
@@ -82,12 +78,10 @@ function param(ty, comp, arg) {
     }
     return { ty: rustTy(ty, comp), value: arg };
 }
-/** \`new\` with every required field, and a chainable setter for each optional one, so building
- * props from Rust takes neither \`Cow\` nor \`None\`. */
 function builderSource(st, comp, life) {
     const required = st.fields.filter((f) => f.ty.k !== "opt");
     const optional = st.fields.filter((f) => f.ty.k === "opt");
-    const arg = (f) => f.rust.replace(/^r#/, "");
+    const arg = (f) => f.rust;
     const params = required.map((f) => `${arg(f)}: ${param(f.ty, comp, arg(f)).ty}`).join(", ");
     const inits = st.fields
         .map((f) => (f.ty.k === "opt" ? `${f.rust}: None` : fieldInit(f.rust, param(f.ty, comp, arg(f)).value)))
@@ -105,7 +99,6 @@ function builderSource(st, comp, life) {
     })
         .join("\n");
     const usesA = /'a/.test(params + setters);
-    // A struct without strings has no lifetime for its constructor to name.
     const impl = life ? "impl<'a>" : usesA ? "impl<'a>" : "impl";
     return `${impl} ${st.name}${life} {
     /// ${st.name} with ${required.length ? "its required fields" : "nothing set"}${optional.length ? ", every optional one absent" : ""}.
@@ -126,9 +119,8 @@ export function structSource(st, comp, doc) {
         return `${attrs}\n    pub ${f.rust}: ${rustTy(f.ty, comp)},`;
     })
         .join("\n");
-    /* `Deserialize` only for the conformance suite. Props go out as JSON and never come back in, and a
-     * `Deserialize` in production would be a way to make a `TrustedHtml` value out of any string. */
-    return `${doc}#[derive(Debug, Clone, serde::Serialize)]
+    const derives = st.fields.some((f) => f.ty.k !== "opt") ? "Debug, Clone" : "Debug, Clone, Default";
+    return `${doc}#[derive(${derives}, serde::Serialize)]
 #[cfg_attr(test, derive(serde::Deserialize))]
 pub struct ${st.name}${life} {
 ${fields}
@@ -142,7 +134,6 @@ export function header(source, edit = "the `.vue` file") {
 // \`ferrovue\`.
 `;
 }
-/** Rust expressions summing the lengths of the strings a value of type `ty` at `place` holds. */
 export function textLen(comp, place, ty, seen = new Set()) {
     switch (ty.k) {
         case "str":
@@ -160,7 +151,6 @@ export function textLen(comp, place, ty, seen = new Set()) {
             }
             return [];
         case "struct": {
-            // A recursive structure is counted to its first level: the reservation is an estimate.
             if (seen.has(ty.name))
                 return [];
             const { st, owner } = lookupStruct(comp, ty);
@@ -179,18 +169,12 @@ export function textLen(comp, place, ty, seen = new Set()) {
             return [];
     }
 }
-/** `render`, and for a component a parent may hand scope ids or pass attributes to,
- * `render_scoped`, which takes them last, as `ssrRenderAttrs` writes them onto its root; `render`
- * hands it none. */
 function renderSource(comp, life, args, e) {
     const doc = "/// Write the component's server render into `out`.\n";
-    // Props or ids the render never reads, as when a component only passes its slot on.
     const props = e.reads("props", 0) ? "props" : "_props";
     if (!comp.inherits && !takesAttrs(comp))
         return `${doc}pub fn render(out: &mut String, ${props}: &Props${life}${extraParams(comp)}) {\n${e.lines.join("\n")}\n}`;
-    // A root that is a fragment, or a `<Teleport>`, takes no ids.
     const attrs = e.reads("fv_attrs", 0) ? "fv_attrs" : "_fv_attrs";
-    // A component a parent may pass attributes takes them with the ids, as one `fv::Attrs`.
     const [none, ty, what] = takesAttrs(comp)
         ? ["&fv::Attrs::NONE", "&fv::Attrs<'_>", "the attributes a parent passes beyond the props, and the scope ids it hands the root"]
         : ['""', "&str", "the scope ids a parent hands the root: ` data-v-…` each"];
@@ -204,10 +188,8 @@ pub fn render_scoped(out: &mut String, ${props}: &Props${life}${extraParams(comp
 ${e.lines.join("\n")}
 }`;
 }
-/** Whether the component gets an `island()`: it renders from its props alone, which `data-props` is
- * all the client gets to mount it with. */
 export function isIsland(comp) {
-    return !takesSlots(comp) && !comp.usesRoute && !comp.usesStores && !comp.usesI18n && !comp.usesTeleports;
+    return !takesSlots(comp) && comp.takes.size === 0;
 }
 export function componentSource(comp, ast, ssr, components) {
     if (takesAttrs(comp) && comp.inheritAttrs && comp.attrsDropped) {
@@ -223,18 +205,12 @@ export function componentSource(comp, ast, ssr, components) {
     for (const l of lets)
         e.stmt(l);
     statements(scope, e, fn.body.body);
-    // A setup value the render never reads is not computed. Checked from the last up, since one may
-    // read another declared before it.
     for (let i = lets.length - 1; i >= 0; i--) {
         const name = /^let (\w+)/.exec(lets[i])[1];
         if (!e.reads(name, i + 1))
             e.lines.splice(i, 1);
     }
     e.flush();
-    /* The literal markup, a loop's once per item, what the helpers can write, and every string the
-     * props hold. Literals in untaken branches overcount and escaping or a string used twice
-     * undercounts, so it is an estimate — close enough that the buffer is sized once, where
-     * reserving the literals alone leaves it to grow again at the first long label. */
     const text = textLen(comp, "props", { k: "struct", name: "Props" });
     const fixed = e.literalBytes + scope.helperBytes.n;
     const reserve = [...(fixed || !(e.perItem.length + text.length) ? [String(fixed)] : []), ...e.perItem, ...text];
@@ -242,16 +218,12 @@ export function componentSource(comp, ast, ssr, components) {
     const life = structLifetime(comp.props, comp) ? "<'_>" : "";
     const gen = life ? "<'p, 'a>" : "<'p>";
     const named = life ? "<'a>" : "";
-    // What holds its props borrows only what they borrow.
     const owned = life ? "<'a>" : "";
     const ownedLife = life ? "'a" : "'static";
-    // An `interface Props` that `defineProps` takes is the props struct itself, written once below.
     const structs = [...comp.structs.values()]
         .filter((st) => st.name !== "Props" && !st.slot)
         .map((st) => structSource(st, comp, `/// \`${st.name}\` in \`${basename(comp.file)}\`.\n`))
         .join("\n");
-    // `Cow` is imported only where a field is one: a lifetime that comes from another component's props
-    // alone borrows through that type, not through a `Cow` written here.
     const usesCow = /Cow</.test(structs + structSource(comp.props, comp, ""));
     const plain = isIsland(comp);
     const slotFields = [
@@ -260,7 +232,7 @@ export function componentSource(comp, ast, ssr, components) {
             const type = comp.slotShapes.has(n) ? `&'s ${slotTypeName(n, "Slot")}<'s>` : "fv::Slot<'s>";
             return `    /// ${outlet}\n    pub ${snake(n)}: Option<${type}>,`;
         }),
-        ...(comp.routerView ? ["    /// The page `<RouterView>` shows.\n    pub router_view: fv::Slot<'s>,"] : []),
+        ...slotFieldsOf(comp).map((f) => `    /// ${f.doc}\n    pub ${f.rust}: fv::Slot<'s>,`),
     ];
     const slotTypes = [...comp.slotShapes.entries()]
         .map(([n, shape]) => {
@@ -281,19 +253,15 @@ pub type ${slotTypeName(n, "Slot")}<'s> = dyn ${borrows ? "for<'v> " : ""}Fn(&mu
         .join("");
     const slotsStruct = takesSlots(comp)
         ? `${slotTypes}/// What a parent puts in the slots \`${basename(comp.file)}\` renders.
-#[derive(Clone, Copy${comp.routerView ? "" : ", Default"})]
+#[derive(Clone, Copy${slotFieldsOf(comp).length ? "" : ", Default"})]
 pub struct Slots<'s> {
 ${slotFields.join("\n")}
 }
 
 `
         : "";
-    const args = (takesSlots(comp) ? ", fv_slots" : "") + (comp.usesRoute ? ", fv_route" : "") + (comp.usesStores ? ", fv_stores" : "") + (comp.usesI18n ? ", fv_i18n" : "") + (comp.usesTeleports ? ", fv_teleports" : "");
-    const params = (takesSlots(comp) ? ", fv_slots: Slots<'p>" : "") +
-        (comp.usesRoute ? ", fv_route: &'p fv::Route<'p>" : "") +
-        (comp.usesStores ? ", fv_stores: &'p super::stores::Stores<'p>" : "") +
-        (comp.usesI18n ? ", fv_i18n: &'p fv::I18n" : "") +
-        (comp.usesTeleports ? ", fv_teleports: &'p fv::Teleports" : "");
+    const args = (takesSlots(comp) ? ", fv_slots" : "") + paramsOf(comp).map((p) => `, ${p.name}`).join("");
+    const params = (takesSlots(comp) ? ", fv_slots: Slots<'p>" : "") + paramsOf(comp).map((p) => `, ${p.name}: ${p.pageTy}`).join("");
     const wrappers = plain
         ? `/// The component's markup, for a maud page that shows it without hydrating it.
 pub fn html${gen}(props: &'p Props${named}) -> fv::Html<'p, Props${named}> {
@@ -331,20 +299,22 @@ ${slotsStruct}${renderSource(comp, life, args, e)}
 
 ${wrappers}`;
 }
-export function modSource(comps) {
+function readsFixture(c) {
+    return takesSlots(c) || paramsOf(c).some((p) => p.test.fixture);
+}
+export function modSource(comps, modules) {
     const arms = comps
         .map((c) => {
         const lines = [`let props: ${c.module}::Props = serde_json::from_str(json).map_err(|e| e.to_string())?;`];
         let args = "";
-        if (takesSlots(c) || c.usesRoute || c.usesStores || c.usesI18n)
+        if (readsFixture(c))
             lines.push("let fixture: Fixture = serde_json::from_str(json).map_err(|e| e.to_string())?;");
         if (takesSlots(c)) {
-            const names = [...c.slotNames, ...(c.routerView ? ["routerView"] : [])];
+            const names = [...c.slotNames, ...slotFieldsOf(c).map((f) => f.js)];
             for (const n of names) {
                 const local = `s_${snake(n).replace(/^r#/, "")}`;
                 const shape = c.slotShapes.get(n);
                 if (shape) {
-                    // A fixture's content for a scoped slot is static: it is given the props and ignores them.
                     const life = shape.fields.some((f) => slotFieldBorrows(f.ty)) ? "<'_>" : "";
                     lines.push(`let ${local} = |out: &mut String, _: &${c.module}::${shape.name}${life}${c.passesSlotIds ? ", _: &str" : ""}| -> bool { out.push_str(fixture.slot(${rustStr(n)}).unwrap_or_default()); true };`);
                 }
@@ -356,34 +326,23 @@ export function modSource(comps) {
                 const value = c.slotShapes.has(n) ? `&${local} as &${c.module}::${slotTypeName(n, "Slot")}` : `ferrovue::Slot::new(&${local})`;
                 return `${snake(n)}: fixture.slot(${rustStr(n)}).map(|_| ${value})`;
             });
-            if (c.routerView)
-                fields.push("router_view: ferrovue::Slot::new(&s_router_view)");
+            for (const f of slotFieldsOf(c))
+                fields.push(`${f.rust}: ferrovue::Slot::new(&s_${snake(f.js).replace(/^r#/, "")})`);
             args += `, ${c.module}::Slots { ${fields.join(", ")} }`;
         }
-        if (c.usesRoute) {
-            lines.push("let router = route_table::router();", "let route = router.at(&fixture.route);");
-            args += ", &route";
-        }
-        if (c.usesStores) {
-            lines.push("let state: stores::Stores = serde_json::from_value(fixture.stores.clone()).map_err(|e| e.to_string())?;");
-            args += ", &state";
-        }
-        if (c.usesI18n) {
-            lines.push("let i18n = i18n::i18n(fixture.locale.as_deref().unwrap_or(i18n::LOCALE));");
-            args += ", &i18n";
-        }
-        if (c.usesTeleports) {
-            lines.push("let teleports = ferrovue::Teleports::new();");
-            args += ", &teleports";
+        for (const p of paramsOf(c)) {
+            lines.push(...p.test.lines);
+            args += `, ${p.test.arg}`;
         }
         lines.push(`${c.module}::render(&mut out, &props${args});`);
-        // What was teleported follows the render, as the conformance suite records Vue's.
-        if (c.usesTeleports)
-            lines.push("teleports_into(&mut out, teleports);");
+        for (const p of paramsOf(c))
+            lines.push(...(p.test.after ?? []));
         return `        ${rustStr(c.name)} => {\n${lines.map((l) => "            " + l).join("\n")}\n        }`;
     })
         .join("\n");
-    const fixture = comps.some((c) => takesSlots(c) || c.usesRoute || c.usesStores || c.usesI18n)
+    const fields = renderParams().flatMap((p) => (p.fixtureField === undefined ? [] : [p.fixtureField]));
+    const defaults = renderParams().flatMap((p) => (p.fixtureDefault === undefined ? [] : [p.fixtureDefault]));
+    const fixture = comps.some(readsFixture)
         ? `
 /// What a fixture holds besides the props: each slot's content, and the location it renders at.
 #[cfg(test)]
@@ -391,25 +350,12 @@ export function modSource(comps) {
 struct Fixture {
     #[serde(rename = "$slots", default)]
     slots: std::collections::HashMap<String, String>,
-    #[serde(rename = "$route", default = "Fixture::root")]
-    route: String,
-    #[serde(rename = "$stores", default = "Fixture::no_stores")]
-    stores: serde_json::Value,
-    #[serde(rename = "$locale", default)]
-    locale: Option<String>,
+${fields.join("\n")}
 }
 
 #[cfg(test)]
 impl Fixture {
-    fn root() -> String {
-        "/".to_owned()
-    }
-
-    fn no_stores() -> serde_json::Value {
-        serde_json::Value::Object(Default::default())
-    }
-
-    fn slot(&self, name: &str) -> Option<&str> {
+${defaults.map((d) => `${d}\n\n`).join("")}    fn slot(&self, name: &str) -> Option<&str> {
         self.slots.get(name).map(String::as_str)
     }
 }
@@ -424,25 +370,12 @@ impl Fixture {
 // it needs.
 #![allow(dead_code)]
 
-${comps.map((c) => `pub mod ${c.module};`).join("\n")}${ctx.routes ? "\npub mod route_table;" : ""}${ctx.stores.size ? "\npub mod stores;" : ""}${ctx.typeStructs.size ? "\npub mod types;" : ""}${ctx.i18n ? "\npub mod i18n;" : ""}
+${comps.map((c) => `pub mod ${c.module};`).join("\n")}${modules.map((m) => `\npub mod ${m.replace(/\.rs$/, "")};`).join("")}
 ${fixture}
-${comps.some((c) => c.usesTeleports) ? `/// What was teleported, after a marker, as the conformance suite writes Vue's: \`{"target":"…"}\`.
-#[cfg(test)]
-fn teleports_into(out: &mut String, teleports: ferrovue::Teleports) {
-    let targets = teleports.into_targets();
-    if targets.is_empty() {
-        return;
-    }
-    let pairs: Vec<String> = targets
-        .iter()
-        .map(|(t, html)| format!("{}:{}", serde_json::to_string(t).unwrap(), serde_json::to_string(html).unwrap()))
-        .collect();
-    out.push_str("<!--fv-teleports-->{");
-    out.push_str(&pairs.join(","));
-    out.push('}');
-}
-
-` : ""}/// Render one component from its props as JSON, for the conformance suite.
+${renderParams()
+        .filter((p) => p.testSupport !== undefined && comps.some((c) => c.takes.has(p.name)))
+        .map((p) => `${p.testSupport}\n\n`)
+        .join("")}/// Render one component from its props as JSON, for the conformance suite.
 #[cfg(test)]
 pub fn render_json(component: &str, json: &str) -> Result<String, String> {
     let mut out = String::new();
@@ -454,28 +387,8 @@ ${arms}
 }
 `;
 }
-export function storesSource(dir) {
-    const home = storeHome(dir);
-    // Test-only `Default` lets a fixture name only the stores it reads; the rest are never looked at.
-    const testDerive = (src) => src.replace("#[cfg_attr(test, derive(serde::Deserialize))]", "#[cfg_attr(test, derive(Default, serde::Deserialize))]\n#[cfg_attr(test, serde(default))]");
-    const structs = [...ctx.storeStructs.values()]
-        .map((st) => testDerive(structSource(st, home, `/// \`${st.name}\` in \`${ctx.storeFiles.get(st.name)}\`.\n`)))
-        .join("\n");
-    const all = {
-        name: "Stores",
-        fields: [...ctx.stores.values()].map((st) => ({ js: st.id, rust: st.field, ty: { k: "struct", name: st.state, store: true } })),
-    };
-    const top = testDerive(structSource(all, home, "/// Every store's state, keyed by id as `pinia.state.value` is: what the page sends the client.\n"));
-    return `${header(dir, "the store files")}
-//! The Pinia stores' state, which components read while they render on the server.
-
-${/Cow</.test(structs) ? "use std::borrow::Cow;\n\n" : ""}${structs}
-${top}`;
-}
 export function typesSource() {
-    const home = storeHome("types");
-    home.structs = ctx.typeStructs;
-    home.module = "types";
+    const home = blankComponent("types", "types", "types", ctx.typeStructs);
     const files = [...new Set(ctx.typeFiles.values())].toSorted();
     const structs = [...ctx.typeStructs.values()]
         .map((st) => structSource(st, home, `/// \`${st.name}\` in \`${ctx.typeFiles.get(st.name)}\`.\n`))
@@ -486,38 +399,3 @@ export function typesSource() {
 
 ${/Cow</.test(structs) ? "use std::borrow::Cow;\n\n" : ""}${structs}`;
 }
-/** Route definitions as \`ferrovue::RouteDef\` literals, children nested. */
-function routeDefs(routes, depth) {
-    const pad = "    ".repeat(depth);
-    return routes
-        .map((r) => {
-        const name = r.name === undefined ? "None" : `Some(${rustStr(r.name)})`;
-        const children = r.children?.length ? `&[\n${routeDefs(r.children, depth + 1)}\n${pad}]` : "&[]";
-        return `${pad}ferrovue::RouteDef { path: ${rustStr(r.path)}, name: ${name}, children: ${children} },`;
-    })
-        .join("\n");
-}
-export function routesSource(routes, file) {
-    return `${header(file, "the routes file")}
-//! The app's routes: what \`<RouterLink>\` resolves against and \`useRoute()\` reads.
-
-/// Each route: its vue-router path, its name if it has one, and the routes nested in it.
-pub const ROUTES: &[ferrovue::RouteDef<'static>] = &[
-${routeDefs(routes, 1)}
-];
-
-/// Every route's full path, nested ones included.
-pub const PATHS: &[&str] = &[
-${allRoutes(routes).map((r) => `    ${rustStr(r.fullPath)},`).join("\n")}
-];
-
-/// The history's base, which every link's \`href\` starts with.
-pub const BASE: &str = ${rustStr(ctx.routerBase)};
-
-/// The router these routes make: build it once, and resolve each request's location with
-/// [\`ferrovue::Router::at\`].
-pub fn router() -> ferrovue::Router {
-    ferrovue::Router::tree(ROUTES).with_base(BASE)
-}
-`;
-}

package/dist/script.d.ts

@@ -1,14 +1,8 @@
 import { type Component, type N, type Scope } from "./model.ts";
-/** Lifecycle hooks, which never run on the server: setup may register them freely. */
 export declare const CLIENT_HOOKS: Set<string>;
-/** Compiler macros and calls with no effect on the server's render. */
 export declare const INERT_CALLS: Set<string>;
-/** A statement in setup that is a call on its own: allowed only when it cannot change the render. */
 export declare function setupStatement(comp: Component, st: N): void;
-/** What a setup binding's value is computed from: `ref(x)` and `shallowRef(x)` hold `x`,
- * `computed(() => x)` is `x`, and a plain `const y = x` is `x`. */
 export declare function setupSource(init: N): N | null;
-/** The names a destructuring pattern binds. */
 export declare function patternNames(p: N): string[];
 export declare function scopeFor(comp: Component, ast: N[], components: Map<string, Component>): {
     scope: Scope;