ferrovue 0.2.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
 
@@ -82,8 +82,11 @@ defineProps<{ name: string; unread: number; note?: string }>();
 ### 4. Generate and render
 
 ```sh
+npx ferrovue init       # a starter ferrovue.config.json and components/Hello.vue
 npx ferrovue            # writes src/generated/{greeting.rs, mod.rs}
 npx ferrovue --check    # in CI: exits 1 if the committed modules are stale
+npx ferrovue --check --diff   # …and shows what differs, as `diff -u` does
+npx ferrovue --watch    # regenerates when components or configs change
 ```
 
 ```rust
@@ -115,9 +118,28 @@ 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.
 
+With the `axum` feature, `Html` is an `IntoResponse`, and with `actix-web` a `Responder`: a handler
+responds with the component, as `text/html; charset=utf-8`. `into_html(props)` and
+`into_island(props)` take the props by value, so a handler that builds them returns the page:
+
+```rust
+async fn hello(Path(name): Path<String>) -> impl IntoResponse {
+    greeting::into_html(greeting::Props::new(name, 0))
+}
+```
+
+With the `dioxus` feature, a component goes into a Dioxus 0.7 page (`dioxus-ssr` or fullstack):
+`{greeting::island(&props)}` in `rsx!` is the island element itself, with exactly the markup Vue
+hydrates inside it. See `examples/dioxus` and the crate guide's
+[Dioxus page](crates/ferrovue/docs/guide/dioxus.md).
+
 ## What a component may use
 
 ferrovue compiles `<script setup lang="ts">` components. Props are declared by type, with
@@ -138,11 +160,12 @@ ferrovue compiles `<script setup lang="ts">` components. Props are declared by t
 | `class` | strings, arrays, objects (`{ active: on }`, computed keys), `cond && "x"`, `cond ? "x" : null`, merged with a static `class` |
 | `style` | objects (camelCase or kebab-case keys, `--custom` properties), arrays of objects, strings, merged with a static `style`, and `v-show`; later values override earlier ones as in Vue. A global `<style>` block is allowed |
 | Scoped styles | `<style scoped>`: the id on every element, on child components' roots (a root that is itself a component, fragments, recursion and `inheritAttrs: false` as Vue renders them) and, from a component with `:slotted()` rules, on the slot content it is given, forwarded slots included; inside `<Transition>`, `<KeepAlive>`, `<Teleport>` and `v-if`; on `<RouterLink>` and what it holds, as vue-router renders them |
-| Components | imported child components, `v-bind` of a child's own `Props`, `v-model` on a child's `defineModel`, recursion |
+| Components | imported child components, `v-bind` of a child's own `Props`, `v-model` on a child's `defineModel`, recursion; props named in `kebab-case` or `camelCase` |
+| Fallthrough attributes | what a parent passes a child beyond its props (static and bound attributes, `class`, `style`, `data-*`, `aria-*`, booleans, `undefined`): onto its single root, merged with the root's own class and style and replacing its other attributes where they stand, as Vue's `mergeProps` merges them; none for two roots; on through a root that is a component, or a `<RouterLink>`; with `inheritAttrs: false`, onto the elements or components that bind `v-bind="$attrs"` or a `useAttrs()` binding, before or after their own; beside scope ids. Listeners are dropped, as Vue's server drops them. See the crate's [`generated_code`](https://docs.rs/ferrovue/latest/ferrovue/guide/generated_code/index.html#fallthrough-attributes) guide |
 | Slots | default and named slots, fallbacks, `$slots.name` tests, scoped slots (`<slot :item="x">` and `#item="{ item }"` or `v-slot="props"`), whose props a parent can hand to its own children |
 | Forms | `v-model` on text inputs, checkboxes, radios, `<select>` and `<textarea>` (renders the initial state) |
 | Built-ins | `<Transition>`, `<TransitionGroup>`, `<KeepAlive>`, `<Suspense>` (synchronous content), `<Teleport>` (to any target, nested, disabled: see below), `v-text`, `v-once`, `v-pre`, `v-memo`, custom directives listed in `clientDirectives` |
-| Vue Router | `<RouterLink>` (resolved by name or imported) with a string `to` or `{ name, params, query, hash }` / `{ path, query, hash }`, `active-class`, `exact-active-class`, `aria-current-value`, `replace`; vue-router's own encoding and active-link matching, nested routes included (a parent link is active on its children's pages, exact only on its own); a history base. `useRoute()` and `$route`: `path`, `fullPath`, `hash`, `name`, `params`, and `query` (a value written once, without `=`, or repeated, exactly as vue-router parses it). `<RouterView>`, at the top and in nested route components: each takes the page it shows as a slot |
+| Vue Router | `<RouterLink>` (resolved by name or imported) with a string `to` or `{ name, params, query, hash }` / `{ path, query, hash }`, `active-class`, `exact-active-class`, `aria-current-value`, `replace`; vue-router's own encoding and active-link matching, nested routes included (a parent link is active on its children's pages, exact only on its own); a history base. `useRoute()` and `$route`: `path`, `fullPath`, `hash`, `name`, `params`, and `query` (a value written once, without `=`, or repeated, exactly as vue-router parses it; `typeof route.query.q === "string"` narrows one to a single string). `<RouterView>`, at the top and in nested route components: each takes the page it shows as a slot |
 | Pinia | option stores with a typed `state`, and setup stores (`defineStore(id, () => { … })`) whose returned refs are typed by `ref<T>()` or their initial literal; read through `useX()` or `storeToRefs`, in the template or in `computed`; getters that are an expression of the state, and a setup store's computeds, which may read each other |
 | vue-i18n | `$t` and `useI18n()`'s `t` and `locale`: named and list values, plurals by vue-i18n's rule, literals, linked messages with `upper`/`lower`/`capitalize`, nested and flat keys, fallback locales, a missing key shown as itself. Messages are parsed at build time by vue-i18n's own compiler |
 | `v-html` | only on a `TrustedHtml` prop (`import type { TrustedHtml } from "ferrovue/types"`) |
@@ -171,7 +194,18 @@ Refused at compile time, each with an error that names the construct:
 - two strings that may each hold half of a surrogate pair compared, searched or joined (see
   [Strings](#strings))
 - `null`
+- an attribute (`class` and `style` aside) bound to a value that may be neither a string, a number
+  nor a boolean: a list, an object, or a `route.query` value, which is an array when its key is
+  repeated. Vue's server renderer leaves the attribute out and hydration then sets it, silently;
+  join a list (`.join(",")`), or narrow a query value with `typeof route.query.q === "string"`
 - any method call without a Rust twin
+- a value read from `$attrs` or `useAttrs()` (`$attrs.title`), which has no type; an attribute a
+  component is passed that would reach a prop of the component (or `<RouterLink>`) its root passes it
+  on to; `$attrs` in a component that is the root of one that may be handed scope ids, where it would
+  hold them; an attribute named by a number, or bound to a `$route.query` value; a class merged by
+  `v-bind` with a string that may equal the class before it, which Vue would write once; attributes
+  passed to a component whose root is a `<Transition>` or `<KeepAlive>` around a `v-if`, which Vue's
+  server drops but its client keeps
 
 An object prop handed to a child component is cloned. Its strings are `Cow`s, so borrowed ones
 cost nothing to copy.
@@ -203,7 +237,8 @@ same in development and production, and do not change, nor change the generated
 component's source does.
 
 A component a parent may hand ids to has a `render_scoped(…, attrs)` beside `render`, which
-generated parents call. A component whose outlets pass a slot scope id (`:slotted()`) takes slot
+generated parents call (for one a parent also passes attributes to, `attrs` is an `fv::Attrs`
+holding them and the ids). A component whose outlets pass a slot scope id (`:slotted()`) takes slot
 content that is given it: `Slot::slotted` for a slot, a third `&str` parameter for a scoped slot's
 closure. `render`, and content from Rust, need none of it: markup written from Rust carries no ids.
 
@@ -217,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
@@ -286,6 +321,37 @@ let row = |out: &mut String, p: &data_list::RowSlotProps<'_>| {
 data_list::render(&mut page, &props, data_list::Slots { row: Some(&row), ..Default::default() });
 ```
 
+### Hydrating islands
+
+`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";
+import islands from "ferrovue/islands"; // written by `ferrovue()` from `ferrovue/vite`
+
+hydrateState(pinia);
+await mountIslands(islands, { pinia, router }); // one Pinia and one router for every island
+```
+
+The islands are exactly the components that have an `island()`: those that render from their props
+alone, as the compiler finds while it generates them. That is the only set the server can write
+`data-island` for, so it needs no folder convention or list to keep in step, and making a component
+an island is a matter of the server calling its `island()`. Each is keyed by its `NAME`, the file
+name without `.vue`, which is what `data-island` carries.
+
+Each entry is a lazy `import()`, so the bundler gives every island a chunk of its own and a page
+fetches the code of the islands it holds and no more. `mountIslands` takes such loaders and
+components alike, so a hand-written island can join them: `mountIslands({ ...islands, Chart })`.
+An island whose name is not among them is left as the server rendered it, with a warning naming it
+(`onError` to handle it otherwise), as is one whose component fails to load.
+
+An island's `<style>` goes into its chunk too, and Vite links it only once the island's script has
+loaded, after the server's markup is on screen. Link those stylesheets from the page up front: a
+server reading Vite's manifest takes the `css` of the entry's `dynamicImports` as well as its own
+(`examples/fullstack/src/assets.rs`).
+
 ### Hydrating Pinia state
 
 ```rust
@@ -293,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
 ```
 
@@ -301,7 +367,12 @@ hydrateState(pinia); // before app.mount(): every store starts from what the ser
 
 `ferrovue::hole()` is a slot whose content you write later. Render a layout with holes,
 `split_holes` the output, and stream the pieces with each hole's content between them, in whatever
-order the content is ready.
+order the content is ready. With the `axum` or `actix-web` feature, `ferrovue::HtmlStream` is that
+streamed response, from the render and a future for each hole's content:
+
+```rust
+let body = ferrovue::HtmlStream::new(page).hole(async move { reviews_of(&id).await });
+```
 
 ## Performance
 
@@ -361,21 +432,37 @@ 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`
+  src/islands.ts             `ferrovue/islands`, which the Vite plugin writes: every island, loaded lazily
   src/testing.ts             utilities for a project's own conformance suite
   src/types.ts               `ferrovue/types`: `TrustedHtml`, `Float`
   test/                      compiler, CLI, router, vector, island, Vite and conformance tests
@@ -384,6 +471,7 @@ packages/ferrovue/           the compiler (npm package)
   fuzz/                      the randomised differential tester (`pnpm fuzz`)
 examples/greeting/           the smallest setup: one component rendered from Rust
 examples/fullstack/          axum + Vite: islands, Pinia state, routes and streaming
+examples/dioxus/             a Dioxus page, rendered with dioxus-ssr, with an island in it
 scripts/release.ts           the release version bump (see RELEASING.md)
 ```
 

package/dist/attrs.d.ts

@@ -1,51 +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(e: Emitter, key: string, v: Val): 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 renderAttr(s: Scope, e: Emitter, key: string, v: Val, n: N): void;
 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;
-/** `ssrRenderAttrs(obj)`, key by key in the object's order, and the inherited scope ids where the
- * root's `_attrs` is merged in. */
+export declare function isAttrs(n: N): boolean;
+export declare function dollarAttrs(s: Scope, n: N): boolean;
+export declare function mergedParts(n: N): N[];
 export declare function renderAttrs(s: Scope, e: Emitter, n: N): void;
-/** `mergeProps(a, _attrs, b, …)` as one object literal, without `_attrs`: it holds only scope ids,
- * which the caller writes after the rest. Of the rest, `class` and `style` values are merged as an
- * array, and any other key keeps the place it first had with the last value given. */
 export declare function mergeProps(s: Scope, n: N): N;
-/** 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 attrEntries(s: Scope, obj: N, side: "vnode" | "own"): string[];
+export declare function attrOf(s: Scope, key: string, n: N, side: "vnode" | "own"): string;
+export declare function valueAttr(s: Scope, v: Val, n: N): string;