ferrovue 0.3.0 → 0.4.0

package/README.md

@@ -26,7 +26,7 @@ The project has two halves:
 | | What it is | Published as |
 |---|---|---|
 | `packages/ferrovue` | The compiler and the `ferrovue` command (TypeScript, runs on Node) | npm: [`ferrovue`](https://www.npmjs.com/package/ferrovue) |
-| `crates/ferrovue` | The runtime the generated Rust calls: escaping, slots, islands, `<RouterLink>` matching | crates.io: [`ferrovue`](https://crates.io/crates/ferrovue) ([API docs](https://docs.rs/ferrovue)) |
+| `crates/ferrovue` | The runtime the generated Rust calls: escaping, slots, islands, `<RouterLink>` matching. The router, vue-i18n and the escaping and number primitives they share are crates of their own (`crates/ferrovue-router`, `ferrovue-i18n`, `ferrovue-core`), which `ferrovue` re-exports | crates.io: [`ferrovue`](https://crates.io/crates/ferrovue) ([API docs](https://docs.rs/ferrovue)) |
 
 ## Quick start
 
@@ -118,6 +118,10 @@ With `routes` configured, the generated `route_table::router()` builds the route
 each request's location with `router.at(path)` and pass the result to the components that take a
 route.
 
+The router and vue-i18n are features of the crate, `router` and `i18n`, both on by default. An
+application with neither routes nor translations can leave them out, and build neither
+`ferrovue-router` nor `ferrovue-i18n`: `ferrovue = { version = "0.4", default-features = false }`.
+
 With the `maud` feature, `ferrovue::Html` implements `maud::Render`, so `(greeting::html(&props))` can go
 straight into a `maud::html!` page.
 
@@ -248,7 +252,7 @@ gives the ids that other component inherits.
 String methods count as JavaScript counts: in UTF-16 code units, so `"🦀".length` is 2 and
 `"🦀 crab".slice(3)` is `"crab"`. Strings are ordered by code unit too, which puts every character
 from U+E000 to U+FFFF after one beyond U+FFFF. Each runtime routine is held to vectors recorded from
-JavaScript (`crates/ferrovue/tests/vectors/`).
+JavaScript (`crates/*/tests/vectors/`).
 
 A JavaScript string can hold half of a surrogate pair — `"🦀".slice(0, 1)`, `.charAt(1)`,
 `.split("")` — and a Rust string cannot. ferrovue writes U+FFFD in its place, which is exactly what
@@ -319,12 +323,12 @@ data_list::render(&mut page, &props, data_list::Slots { row: Some(&row), ..Defau
 
 ### Hydrating islands
 
-`mountIslands` from `ferrovue/client` hydrates every `data-island` element on the page with the
+`mountIslands` from `ferrovue` hydrates every `data-island` element on the page with the
 component of that name, from the props the server wrote. With the Vite plugin, `ferrovue/islands`
 gives it every island there is, so nothing has to be listed by hand:
 
 ```ts
-import { hydrateState, mountIslands } from "ferrovue/client";
+import { hydrateState, mountIslands } from "ferrovue";
 import islands from "ferrovue/islands"; // written by `ferrovue()` from `ferrovue/vite`
 
 hydrateState(pinia);
@@ -355,7 +359,7 @@ ferrovue::state_script_into(&mut page, "__pinia", &stores);   // a <script type=
 ```
 
 ```ts
-import { hydrateState } from "ferrovue/client";
+import { hydrateState } from "ferrovue";
 hydrateState(pinia); // before app.mount(): every store starts from what the server rendered
 ```
 
@@ -428,18 +432,33 @@ ferrovue version.
 ## Repository layout
 
 ```text
-crates/ferrovue/             the Rust runtime crate
-  src/                       runtime (escaping, JS numbers, router, i18n, teleports) + unit tests
+crates/ferrovue/             the Rust runtime crate, which generated code calls
+  src/                       a module per part (`Html`, slots, class and style, the state script,
+                             strings, teleports, fallthrough attributes), each module's unit tests
+                             beside it in <module>/tests.rs; lib.rs re-exports them all, and the
+                             three crates below
   tests/conformance/         components, fixtures, recorded HTML, generated Rust
-  tests/vectors/             vectors recorded from JavaScript, vue-router and vue-i18n
+  tests/vectors/             vectors recorded from JavaScript and Vue
   tests/properties.rs        property-based tests of the runtime
   benches/                   criterion benchmarks of generated renderers (see Performance)
+crates/ferrovue-core/        escaping and JavaScript's numbers, which the other crates share
+  tests/vectors/             vectors recorded from escapeHtml, String(n), Math and toFixed
+crates/ferrovue-router/      vue-router's matching and links (the `router` feature)
+  tests/vectors/             vectors recorded from vue-router
+crates/ferrovue-i18n/        vue-i18n's t() (the `i18n` feature)
 packages/ferrovue/           the compiler (npm package)
-  src/compiler.ts            the API: `generate`, `write`
-  src/script.ts, template.ts, expr.ts, attrs.ts
-                             <script setup>, the compiled template, expressions, class/style
-  src/router.ts, stores.ts, i18n.ts
-                             vue-router, Pinia and vue-i18n
+  src/index.ts               `ferrovue`: the browser API, `mountIslands`, `hydrateState` and the types
+  src/compiler.ts            `ferrovue/compiler`: `generate`, `write`
+  src/component.ts, script.ts, typescript.ts
+                             a `.vue` file read, <script setup>, TypeScript types
+  src/template.ts, children.ts, slots.ts, loops.ts
+                             the compiled template: statements, child components, slots, v-for
+  src/expr.ts, strings.ts, numbers.ts, narrowing.ts, calls.ts, lists.ts
+                             expressions: operators, strings, numbers, narrowing, calls, lists
+  src/attrs.ts, classes.ts, styles.ts, fallthrough.ts
+                             attributes, class and style, attributes a parent passes on
+  src/plugin.ts              the plugin interface (see CONTRIBUTING.md)
+  src/plugins/               vue-router, Pinia, vue-i18n, scoped styles, <Teleport>, shared types
   src/rust.ts, emitter.ts    the Rust source written out
   src/cli.ts, vite.ts        the `ferrovue` command and the Vite plugin
   src/client.ts              browser-side helpers: `mountIslands`, `hydrateState`

package/dist/attrs.d.ts

@@ -1,67 +1,17 @@
 import { type N, type Scope, type Val } from "./model.ts";
 import { Emitter } from "./emitter.ts";
-/** `toDisplayString`, escaped. */
+export declare function display(e: Emitter, v: Val): boolean;
 export declare function interpolate(e: Emitter, v: Val): void;
-/** The value half of `key="value"`, escaped. */
 export declare function attrValue(e: Emitter, v: Val): void;
-/** `ssrRenderAttr(key, value)`: absent for null/undefined, `key="value"` for anything else. */
 export declare function renderAttr(s: Scope, e: Emitter, key: string, v: Val, n: N): void;
-/** `ssrRenderDynamicAttr(key, value)`: as `renderAttr`, but a boolean attribute is present or
- * absent, and an empty string renders the name alone. */
 export declare function renderDynamicAttr(s: Scope, e: Emitter, key: string, v: Val, n: N): void;
-/** One item of a class list once it is flattened: literal text, known now, or a Rust `&str`
- * expression evaluated at run time — empty when the item contributes nothing. */
-export type ClassItem = {
-    lit: string;
-} | {
-    code: string;
-};
-/** `normalizeClass`'s view of a class binding, flattened: a string, an array of items, an object
- * of `name: condition`, `cond && "name"`, `cond ? "a" : null`. Every item is trimmed and the empty
- * ones dropped before they are joined with one space, which is what `class_into` does too, so an
- * object's keys become items of their own. */
-export declare function classItems(s: Scope, n: N): ClassItem[];
-/** `ssrRenderClass(value)`: normalised, then escaped. `after` says a class was already written. */
-export declare function renderClass(s: Scope, e: Emitter, n: N, after?: boolean): void;
 export declare const IGNORED_PROPS: Set<string>;
-/** `ssrGetDirectiveProps(_ctx, dir)`: a custom directive's server props, which are none for a
- * directive the configuration declares client-only. `false` when `n` is not such a call. */
 export declare function directiveProps(s: Scope, n: N): boolean;
-/** Whether `n` is the root's `_attrs`: what a parent passes, then the scope ids. */
 export declare function isAttrs(n: N): boolean;
-/** Whether `n` is `$attrs` — `_ctx.$attrs`, or a `useAttrs()` binding — which a component whose
- * root is another's would find holding scope ids as well. */
 export declare function dollarAttrs(s: Scope, n: N): boolean;
-/** The parts `_mergeProps(…)` merges, or the one object that is not merged. */
 export declare function mergedParts(n: N): N[];
-/** `ssrRenderAttrs(obj)`, key by key in the object's order, and the inherited scope ids where the
- * root's `_attrs` is merged in. When a parent may pass attributes, which only the run time knows,
- * `$attrs` and the root's `_attrs` are merged with the element's own by `fv::attrs_into` — but only
- * when some were passed: with none, the element is written as it is without. */
 export declare function renderAttrs(s: Scope, e: Emitter, n: N): void;
-/** `mergeProps(a, _attrs, b, …)` as one object literal, without `_attrs` and `$attrs`, which hold
- * what only the run time knows. Of the rest, `class` and `style` values are merged as an array —
- * unless a class equals the one so far, which Vue then keeps once — and any other key keeps the
- * place it first had with the last value given. */
 export declare function mergeProps(s: Scope, n: N): N;
-/** The attributes of an object literal as `fv::Attr` entries, `("name", value)`, for a merge at run
- * time: given to a child component (`vnode`), whose virtual node normalises a class array or object
- * to a string, or an element's own (`own`), which `mergeProps` keeps as an object. */
 export declare function attrEntries(s: Scope, obj: N, side: "vnode" | "own"): string[];
-/** One attribute's value as an `fv::Attr`. */
 export declare function attrOf(s: Scope, key: string, n: N, side: "vnode" | "own"): string;
-/** One object of a style binding, and the run-time condition under which it is part of it. */
-export interface StyleItem {
-    cond: string | null;
-    entries: {
-        key: string;
-        css: string;
-        value: N;
-    }[];
-}
-/** The objects a style binding merges, in order: an object literal, a static `style` the compiler
- * parsed, `v-show`'s `cond ? null : { display: "none" }`, and arrays of those. */
-export declare function styleItems(s: Scope, n: N, when: string | null): StyleItem[];
-/** `ssrRenderStyle(value)`: a string as it is, or the objects merged — each property where it first
- * appears, with the last value given — and written `name:value;`, all escaped. */
-export declare function renderStyle(s: Scope, e: Emitter, n: N): void;
+export declare function valueAttr(s: Scope, v: Val, n: N): string;