ferrovue 0.6.0 → 0.7.0

package/README.md

@@ -38,8 +38,8 @@ cargo add ferrovue serde --features serde/derive
 cargo add --dev serde_json    # the generated conformance helper uses it under cfg(test)
 ```
 
-ferrovue supports the latest stable Rust, currently **1.99**. Generated code uses let-chains, so the
-crate that includes it needs **edition 2024**.
+ferrovue needs Rust **1.89** or later (CI tests that and the latest stable). Generated code uses
+let-chains, so the crate that includes it needs **edition 2024**.
 
 ### 2. Configure
 
@@ -47,15 +47,22 @@ crate that includes it needs **edition 2024**.
 
 ```json
 {
+  "$schema": "https://cdn.jsdelivr.net/npm/ferrovue@0.7.0/schema.json",
   "components": "client/components",
   "out": "src/generated"
 }
 ```
 
+`$schema` points an editor at the configuration's JSON Schema, published with each version of the
+npm package, so VS Code and other JSON editors complete the keys, describe them on hover and flag a
+misspelt one. Name the version of `ferrovue` you use; `ferrovue init` writes it. ferrovue does not
+read `$schema`. Offline, the copy in the installed package works as well:
+`"$schema": "./node_modules/ferrovue/schema.json"`.
+
 | Key | Required | Meaning |
 |---|---|---|
 | `components` | yes | Directory of `.vue` files to compile |
-| `out` | yes | Directory the Rust modules are written to. **Everything in it is replaced.** |
+| `out` | yes | Directory the Rust modules are written to. **Every module ferrovue wrote there is replaced**, and one no component produces any more is removed; a `.rs` file without ferrovue's `// @generated` header is left alone, and `--check` reports it |
 | `routes` | no | JSON file listing the app's routes: each a vue-router path, or `{ "path", "name", "children" }`. Or `{ "pages": "client/pages" }`: a folder of pages, whose file names give the routes as vue-router's file-based routing reads them (`index.vue`, `[id].vue`, `[[id]].vue`, `[...path].vue`, `(group)` folders, a `name.vue` beside `name/` as its layout), each page compiled as a component. Needed for `<RouterLink>`, `<RouterView>` and `useRoute()` |
 | `router` | no | Instead of `routes`: `{ routes, base?, linkActiveClass?, linkExactActiveClass? }`, matching `createWebHistory(base)` and `createRouter`'s options |
 | `stores` | no | Directory of Pinia option stores whose state components may read |
@@ -66,6 +73,8 @@ crate that includes it needs **edition 2024**.
 | `clientDirectives` | no | Custom directives with no server output (no `getSSRProps`), by name without `v-`: `["focus"]` |
 | `scopeId` | no | How a `<style scoped>` id is hashed, as `@vitejs/plugin-vue` hashes it: `"filepath-source"` (the default, the plugin's in a production build) or `"filepath"`. See [Scoped styles](#scoped-styles) |
 | `viteRoot` | no | Vite's root, relative to this file's directory, from which a component's path is hashed (default `.`) |
+| `isProduction` | no | Whether `@vitejs/plugin-vue` compiles for production, as Vite's `isProduction`: `true` (the default) for `vite build`, `false` for the dev server. It names the variables `v-bind()` in `<style>` sets. See [Scoped styles](#scoped-styles) |
+| `cssModules` | no | `{ generateScopedName, hashPrefix?, context? }`, as Vite's `css.modules` names CSS module classes: needed for `<style module>`. `context` is the directory Vite runs in (default `viteRoot`). See [Scoped styles](#scoped-styles) |
 | `builders` | no | `false` leaves out each props struct's and shared type's `new()` and setters, for an app that builds its props as struct literals (default `true`) |
 
 ### 3. Write a component
@@ -92,11 +101,28 @@ pnpm ferrovue --check --format json  # errors as JSON, for an editor or CI annot
 pnpm ferrovue --watch   # regenerates when components or configs change
 ```
 
+`-c, --config <path>` reads another configuration file. `--watch` regenerates on a change to what a
+run reads (the configuration, the components, stores, locale messages, pages or routes file, and
+the `.ts` files components import types from), not on any other file of the project. A Vite project
+can use the plugin instead, which does the same in its dev server and before a build:
+
+```ts
+// vite.config.ts
+import ferrovue from "ferrovue/vite";
+
+export default { plugins: [ferrovue({ config: "config/ferrovue.json" })] };
+```
+
+`root` is the project root the configuration's paths are relative to (Vite's working directory by
+default), and `config` the configuration file in it, as `--config` takes it (`ferrovue.config.json`
+by default).
+
 Every error carries a stable code, as `error[FV0602]: components/Card.vue:4:17: …`, documented in
 the crate's [`error_codes`](https://docs.rs/ferrovue/latest/ferrovue/guide/error_codes/index.html)
 guide. `--format json` writes the same errors as JSON with the exit status unchanged, and a VS Code
 problem matcher for `tasks.json` puts them in the Problems panel: both are in the
 [quick start](https://docs.rs/ferrovue/latest/ferrovue/guide/quick_start/index.html#editor-and-ci-diagnostics).
+In the editor, the `ferrovue/volar` plugin shows them as you type (step 5).
 
 ```rust
 #[rustfmt::skip]
@@ -129,7 +155,7 @@ 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.6", default-features = false }`.
+`ferrovue-router` nor `ferrovue-i18n`: `ferrovue = { version = "0.7", default-features = false }`.
 
 With the `maud` feature, `ferrovue::Html` implements `maud::Render`, so `(greeting::html(&props))` can go
 straight into a `maud::html!` page.
@@ -160,6 +186,23 @@ With the `dioxus` feature, a component goes into a Dioxus 0.7 page (`dioxus-ssr`
 hydrates inside it. See `examples/dioxus` and the crate guide's
 [Dioxus page](https://github.com/Kinsmir/ferrovue/blob/main/crates/ferrovue/docs/guide/dioxus.md).
 
+### 5. Diagnostics in your editor
+
+`ferrovue/volar` is a plugin for Vue's language tools, which the Vue (Official) extension for VS Code
+and Vue support in other editors run. It compiles the project as you type and underlines what
+ferrovue refuses in the open component, with the error's code linked to its documentation. Name it
+in the `tsconfig.json` that includes your components, then run **Vue: Restart Vue and TS servers**:
+
+```json
+{
+  "include": ["components/**/*.vue", "components/**/*.ts"],
+  "vueCompilerOptions": { "plugins": ["ferrovue/volar"] }
+}
+```
+
+The [quick start](https://docs.rs/ferrovue/latest/ferrovue/guide/quick_start/index.html#diagnostics-in-your-editor)
+has the details; `examples/fullstack/tsconfig.json` enables it.
+
 ## What a component may use
 
 ferrovue compiles `<script setup lang="ts">` components, and components with no script at all
@@ -177,13 +220,15 @@ ferrovue compiles `<script setup lang="ts">` components, and components with no
 | Text | `{{ }}` of strings, integers and booleans; `+`, `-`, `*`, `/`, `%`, with integers and fractions as JavaScript computes them; `<`, `>`, `<=`, `>=` (between numbers, or between strings by UTF-16 code unit), `===`, `!==`; unary `-`, `!`; `??`, `\|\|`, `&&`, `?:`; template literals; optional chaining `a?.b`; `.length`; `String()`, `.toString()`, `.toFixed()`, `Math.max`/`min`/`abs`/`round`/`floor`/`ceil`/`trunc`; `Number()`, `parseInt()` (no radix, 10 or 16), `parseFloat()`; `JSON.stringify()` of strings, numbers, booleans and lists of those; array literals |
 | Strings | `.trim()`, `.trimStart()`, `.trimEnd()`, `.toUpperCase()`, `.toLowerCase()`, `.includes()`, `.startsWith()`, `.endsWith()`, `.indexOf()`, `.lastIndexOf()`, `.slice()`, `.substring()`, `.at()`, `.charAt()`, `.split()`, `.replace()` and `.replaceAll()` with string patterns (`$&`, `` $` ``, `$'`, `$$` read as JavaScript reads them), `.padStart()`, `.padEnd()`, `.repeat()`; indices and lengths count UTF-16 code units, as JavaScript's do (see [Strings](#strings)) |
 | Conditions | `v-if` / `v-else-if` / `v-else`, `?:`, `&&` and `||`, with optional and nullable values narrowed as TypeScript narrows them: `v-if="user"`, `user !== undefined`, `user !== null`, `user != null`, and `!user`, `user === undefined` or `user === null` for the `v-else` |
-| Lists | `v-for` over arrays (of strings, numbers, objects or child props), array literals and number ranges (`n in 5`); with an index; with destructured items (`{ id, name } in rows`); nested; on `<template>`. `.includes()` (a number looked for in a list of numbers whether either is a `number` or a `Float`, as JavaScript compares them), `.join()`, and `.filter()`, `.map()`, `.some()`, `.every()`, `.find()`, `.findIndex()` with an arrow function of the item (a name, or destructured) and its index, whose body is an expression, narrowing inside as outside; `.slice()`; chained and nested; a computed list read by `v-for`, `.join()`, `.length`, `.includes()`, kept by `computed`, or handed to a child |
+| Lists | `v-for` over arrays (of strings, numbers, objects or child props), array literals and number ranges (`n in 5`); with an index; with destructured items (`{ id, name } in rows`); nested; on `<template>`. `.includes()` (a number looked for in a list of numbers whether either is a `number` or a `Float`, as JavaScript compares them), `.join()`, and `.filter()`, `.map()`, `.some()`, `.every()`, `.find()`, `.findIndex()` with an arrow function of the item (a name, or destructured) and its index, whose body is an expression, narrowing inside as outside, or with `Boolean`; `.filter(Boolean)` of a list or an array literal whose items may be `null` or `undefined`, which keeps the ones present and truthy as a list of the values (`[name, title, city].filter(Boolean).join(" · ")`); `Boolean(x)`; `.slice()`; chained and nested; a computed list read by `v-for`, `.join()`, `.length`, `.includes()`, kept by `computed`, or handed to a child |
 | Dictionaries | `v-for="(value, key, index) in r"` over a `Record<string, T>`, and `([key, value], index) in Object.entries(r)`, in JavaScript's order: keys that are array indices first, in numeric order, then the others as the props give them; `Object.keys(r)`, `Object.values(r)`, `Object.entries(r).length`; handed to a child |
 | Attributes | static and bound attributes, boolean attributes, `:hidden`, `data-*` and `aria-*`, `v-bind` objects |
 | `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; props named in `kebab-case` or `camelCase`; `defineAsyncComponent(() => import("./X.vue"))` (or `{ loader: … }`), rendered as the component it loads, which Vue's server renderer waits for |
+| `v-bind()` in `<style>` | variables bound to props, setup values, `computed`s and constants, quoted expressions included (`v-bind('size + "px"')`), in a scoped or global `<style>`: written into the root's `style` after its own and what a parent passes, on each root of a fragment, and handed to a root that is a component, as Vue's server writes them; `undefined` and `null` as `initial`, an empty string as a space; named as plugin-vue names them for production or development (`isProduction`) |
+| CSS modules | `<style module>` and `<style module="name">`, read as `$style.x`, `name.x`, `$style['x-y']` and through `useCssModule()`, each class a constant in the generated code, when `cssModules` mirrors Vite's `css.modules.generateScopedName`: computed as postcss-modules computes it in Vite (`[local]`, `[name]`, `[hash:base64:5]`, `[path]` and the rest), composed classes, `@value`s and keyframes included |
+| Components | imported child components, `v-bind` of a child's own `Props`, listeners in any form (`@x`, `v-on="obj"`, `@[name]`), which the server skips, `v-model` on a child's `defineModel`, recursion; props named in `kebab-case` or `camelCase`; `defineAsyncComponent(() => import("./X.vue"))` (or `{ loader: … }`), rendered as the component it loads, which Vue's server renderer waits for |
 | `<component :is>` | over a closed set of choices, compiled to a `match`: an imported component (`:is="Card"`), an HTML element's name (`is="h2"`), a `computed` or `?:` choosing among them, a prop typed as a union of string literals (`as: "h1" \| "h2"`), and an object of imported components (or element names) declared in setup or imported from a `.ts` file, read by such a prop (`ICONS[name]`); props, fallthrough attributes, slots and scope ids reach each choice as they reach a static child; also inside `<KeepAlive>` and `<Transition>`. See the crate's [`generated_code`](https://docs.rs/ferrovue/latest/ferrovue/guide/generated_code/index.html#component-is) guide |
 | Escape hatches | `<ClientOnly>` from `ferrovue/client`, whose default slot the server never renders, so anything may go in it; components listed in `twins`, rendered by Rust functions of yours. See [Escape hatches](#escape-hatches) |
 | 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 |
@@ -198,7 +243,9 @@ ferrovue compiles `<script setup lang="ts">` components, and components with no
 
 Refused at compile time, each with an error that names the construct:
 
-- `<style module>`, and `v-bind()` in CSS
+- `<style module>` without `cssModules` in the configuration; a CSS module in another file, one a
+  preprocessor compiles, or one that imports from another file; `v-bind()` in `<style>` of a value
+  that is not a string or a number
 - `<RouterView>` in a component with `<style scoped>`, which would give the page that component's
   id; and, since vue-router renders a link from virtual nodes, a `<slot>` inside a `<RouterLink>`
   that takes scope ids, or an element inside one in slot content given a `:slotted()` id
@@ -233,8 +280,9 @@ Refused at compile time, each with an error that names the construct:
   starting position or a split's limit (`.includes(x, 3)`, `.split(",", 2)`), `.toLocaleUpperCase()`
   and `.toLocaleLowerCase()` (the server's locale is not the browser's), `parseInt` with another radix
   or of a number, `.repeat()` by a negative literal
-- array methods given anything but an arrow function whose body is an expression (`.filter(Boolean)`,
-  `x => { return … }`), `.map()` to optional values, a computed list as a slot prop
+- array methods given anything but `Boolean` or an arrow function whose body is an expression
+  (`.map(String)`, `x => { return … }`), `.map()` to optional values, methods other than
+  `.filter(Boolean)` over a list of optional values, a computed list as a slot prop
 - a dictionary's field read by name (`r.key`, `r[key]`), which may be absent although TypeScript says
   it is not; `Object.entries()` anywhere but as a `v-for`'s source; dictionaries of optional values
 - two strings that may each hold half of a surrogate pair compared, searched or joined (see
@@ -310,6 +358,15 @@ Set `viteRoot` when Vite's root is not the directory holding `ferrovue.config.js
 plugin (`ferrovue/vite`) compares the two when a component has scoped styles: a build in which they
 differ fails, and the dev server warns.
 
+`v-bind()` in `<style>` sets CSS variables on the component's root, which Vue's server writes into
+its `style` and ferrovue writes there too. Their names follow the same id, and whether plugin-vue
+compiles for production (`vite build`) or development (the dev server): set `isProduction` to match,
+`true` by default. CSS modules (`<style module>`) take their class names from Vite's
+`css.modules.generateScopedName`: set it to a pattern, and `cssModules` in `ferrovue.config.json` to
+the same, and ferrovue computes each class as postcss-modules does in Vite. The Vite plugin compares
+both, and fails a build in which they differ. See the crate's
+[`scoped_styles`](https://docs.rs/ferrovue/latest/ferrovue/guide/scoped_styles/index.html) guide.
+
 The default is the plugin's production behaviour because the production build is the one readers
 get: with every option left alone, its styles apply. But plugin-vue hashes the path alone in its dev
 server, so with the default a page rendered during development carries other ids than the dev
@@ -565,6 +622,24 @@ The record repeats the text of every prop, so a page hydrated this way is larger
 islands; the guide's `islands_and_hydration` page compares the two, and `examples/fullstack` serves
 a page of each kind.
 
+An application that goes to the next page without a reload shows it from the record in the fetched
+document, with the same app:
+
+```ts
+import { hydrateState, readPage, renderPage } from "ferrovue";
+
+const next = readPage(await (await fetch(href)).text()); // no DOMParser: works in a worker too
+const pinia = createPinia();
+hydrateState(pinia, { text: next.state });
+const router = linkRouter(routes, { navigate, location: href }); // at the next page's location
+current = await renderPage(() => import("./Picks.vue"), islands, next.record, { pinia, router, previous: current });
+```
+
+`renderPage` mounts the next page's app in place of the container before it unmounts `previous`, so
+a router both use stays started. `renderRecordedPage` from `ferrovue/testing` checks that a page
+rendered from its record on the client shows what the server wrote, and `conformanceSuite` checks
+the same of every fixture.
+
 ### Hydrating Pinia state
 
 ```rust
@@ -719,6 +794,15 @@ the fixtures from it. A weekly CI job re-records them from the newest patch each
 hydrates the committed HTML with it, so a patch that changes what Vue writes or hydrates is caught
 before it reaches you; a ferrovue patch follows when one does.
 
+### Deprecations
+
+Something ferrovue stops supporting is deprecated first, for at least one minor release, and
+removed in the next major release. A deprecated item of the crates carries `#[deprecated]`, so the
+Rust compiler warns where it is used. A deprecated configuration key warns with
+`warning[FV1117]` and a deprecated command-line option with `warning[FV1118]`, each naming what
+replaces it, and the JSON Schema marks the key deprecated for editors. Each release's CHANGELOG lists
+what it deprecates under "Deprecated".
+
 ## Repository layout
 
 ```text
@@ -741,10 +825,13 @@ crates/ferrovue-core/        escaping and JavaScript's numbers, which the other
 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)
+crates/ferrovue-contract/    unpublished: Rust using every item of the generated-code contract,
+                             and the version check's message (trybuild)
 packages/ferrovue/           the compiler (npm package)
-  src/index.ts               `ferrovue`: the browser API, `mountIslands`, `mountPage`, `hydrateState` and the types
+  src/index.ts               `ferrovue`: the browser API, `mountIslands`, `mountPage`, `readPage`, `renderPage`, `hydrateState` and the types
   src/compiler.ts            `ferrovue/compiler`: `generate`, `write`
   src/context.ts, model.ts   `ferrovue.config.json`, and the types and values the compiler passes around
+  src/schema.ts              the configuration's keys, types and defaults, from which `schema.json` is written
   src/component.ts, script.ts, typescript.ts, constants.ts
                              a `.vue` file read, <script setup>, TypeScript types, constants and enums
   src/template.ts, children.ts, slots.ts, loops.ts, vhtml.ts
@@ -760,11 +847,13 @@ packages/ferrovue/           the compiler (npm package)
   src/plugins/               vue-router, Pinia, vue-i18n, scoped styles, <Teleport>, shared types,
                              <ClientOnly>, Rust twins, provide and inject, the page head
   src/rust.ts, emitter.ts    the Rust source written out
-  src/cli.ts, vite.ts        the `ferrovue` command and the Vite plugin
+  src/cli.ts, args.ts, vite.ts
+                             the `ferrovue` command, its options, and the Vite plugin
   src/diff.ts                the diff `ferrovue --check --diff` prints for a stale file
   src/errors.ts, diagnostics.ts
                              every error code with its title, and errors as the CLI, JSON and Vite show them
-  src/client.ts              browser-side helpers: `mountIslands`, `mountPage`, `hydrateState`, `<ClientOnly>`
+  src/volar.ts, editor.ts    `ferrovue/volar`: errors in the editor, from a plugin for Vue's language tools
+  src/client.ts              browser-side helpers: `mountIslands`, `mountPage`, `readPage`, `renderPage`, `hydrateState`, `<ClientOnly>`
   src/islands.ts             `ferrovue/islands`, which the Vite plugin writes: every island, loaded lazily
   src/link-router.ts         `ferrovue/link-router`: `<RouterLink>` while the application navigates on its own
   src/routes.ts              a routes file as vue-router's route records
@@ -774,9 +863,12 @@ packages/ferrovue/           the compiler (npm package)
   src/fixture.ts, settle.ts  `fixtureApp` and `readFixture`, and waiting for async components to settle
   src/conformance.ts         `conformanceSuite`, which `ferrovue/testing` exports
   src/ssr.ts                 `attachSsrRender`, which `ferrovue/testing` exports
-  src/hydration.ts           `hydrateRecordedPage`, which `ferrovue/testing` exports
+  src/hydration.ts           `hydrateRecordedPage` and `renderRecordedPage`, which `ferrovue/testing` exports
+  src/client-render.ts       the DOM of a client render as it is compared with the server's markup
   src/types.ts               `ferrovue/types`: `TrustedHtml`, `InlineHtml`, `Float`
   test/                      compiler, CLI, router, vector, island, Vite and conformance tests
+  api/                       the package's API report, an `.api.md` per export and `cli.txt` (`pnpm api:report`)
+  schema.json                the JSON Schema of `ferrovue.config.json` (`pnpm schema:generate`)
   browser/                   conformance fixtures and recorded pages hydrated in real browsers (`pnpm test:browser`)
   bench/                     Vue renderToString benchmarks, the other half of Performance
   fuzz/                      the randomised differential tester (`pnpm fuzz`)
@@ -788,6 +880,7 @@ examples/dioxus/             a Dioxus page, rendered with dioxus-ssr, with an is
 scripts/ferrovue-in.ts       the `ferrovue` command run in a project of this repository (`pnpm conformance:check`, CI)
 scripts/inspect.ts           Vue's SSR code and render of a component beside the Rust ferrovue generates for it
 scripts/release.ts           the release version bump (see RELEASING.md)
+scripts/api-report.ts        the npm package's API report, written and checked (`pnpm api:report`, `pnpm api:check`)
 ```
 
 ## Development

package/dist/args.d.ts

@@ -0,0 +1,28 @@
+import { GenError } from "./model.ts";
+import type { Deprecation } from "./schema.ts";
+/** A command-line option: its names, short one first, the value it takes, and its line in `--help`. */
+export interface Flag {
+    names: readonly string[];
+    value?: string;
+    help: string;
+    deprecated?: Deprecation;
+}
+/** The commands `ferrovue` takes, with their lines in `--help`. */
+export declare const COMMANDS: Readonly<Record<string, string>>;
+/** The options `ferrovue` takes. */
+export declare const FLAGS: readonly Flag[];
+/** What the command line asks for: the command, and each option given by its long name, with its
+ * value or `true`. */
+export interface Args {
+    command: string | null;
+    options: Map<string, string | true>;
+    /** The name each option was given by, as an error about it quotes it. */
+    spelt: Map<string, string>;
+    warnings: GenError[];
+}
+/** `ferrovue --help`. */
+export declare function helpText(flags?: readonly Flag[], commands?: Readonly<Record<string, string>>): string;
+/** Read the command line, or say what is wrong with it. A deprecated option gives a warning. */
+export declare function parseArgs(argv: readonly string[], flags?: readonly Flag[], commands?: Readonly<Record<string, string>>): Args | {
+    error: string;
+};

package/dist/args.js

@@ -0,0 +1,69 @@
+import { GenError } from "./model.js";
+/** The commands `ferrovue` takes, with their lines in `--help`. */
+export const COMMANDS = {
+    init: "scaffold starter ferrovue.config.json and components",
+};
+/** The options `ferrovue` takes. */
+export const FLAGS = [
+    { names: ["--check"], help: "check that generated files match committed files without writing" },
+    { names: ["-d", "--diff"], help: "show unified diff of changes when checking (use with --check)" },
+    { names: ["--format"], value: "<format>", help: "how to write errors and results: human (default) or json" },
+    { names: ["--watch"], help: "watch components, stores, routes and config for changes and regenerate" },
+    { names: ["-c", "--config"], value: "<path>", help: "path to configuration file (default: ferrovue.config.json)" },
+    { names: ["-v", "--version"], help: "print the version and exit" },
+    { names: ["-h", "--help"], help: "print this help and exit" },
+];
+const longName = (flag) => flag.names.at(-1);
+/** `ferrovue --help`. */
+export function helpText(flags = FLAGS, commands = COMMANDS) {
+    const line = (left, help) => `  ${left.padEnd(23)}  ${help}`;
+    const option = (flag) => {
+        const [short, long] = flag.names.length > 1 ? [`${flag.names[0]}, `, longName(flag)] : ["    ", longName(flag)];
+        const help = flag.deprecated ? `${flag.help} (deprecated: use ${flag.deprecated.use})` : flag.help;
+        return line(`${short}${long}${flag.value ? ` ${flag.value}` : ""}`, help);
+    };
+    return `Usage: ferrovue [command] [options]
+
+Compile Vue components to Rust render functions, run from the project root.
+
+Commands:
+${Object.entries(commands).map(([name, help]) => line(name, help)).join("\n")}
+
+Options:
+${flags.map(option).join("\n")}`;
+}
+/** Read the command line, or say what is wrong with it. A deprecated option gives a warning. */
+export function parseArgs(argv, flags = FLAGS, commands = COMMANDS) {
+    const args = { command: null, options: new Map(), spelt: new Map(), warnings: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const eq = arg.startsWith("--") ? arg.indexOf("=") : -1;
+        const name = eq === -1 ? arg : arg.slice(0, eq);
+        const flag = flags.find((f) => f.names.includes(name));
+        if (!flag) {
+            if (arg in commands && args.command === null) {
+                args.command = arg;
+                continue;
+            }
+            return { error: `unknown option or command '${arg}'\n\nRun \`ferrovue --help\` for usage.` };
+        }
+        let value = true;
+        if (flag.value) {
+            if (eq !== -1)
+                value = arg.slice(eq + 1);
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("-"))
+                value = argv[++i];
+            else
+                return { error: `option '${name}' requires an argument` };
+        }
+        else if (eq !== -1) {
+            return { error: `option '${name}' takes no value` };
+        }
+        if (flag.deprecated) {
+            args.warnings.push(new GenError("FV1118", `'${name}' is deprecated since ${flag.deprecated.since}, and goes in the next major release: use ${flag.deprecated.use}`));
+        }
+        args.options.set(longName(flag), value);
+        args.spelt.set(longName(flag), name);
+    }
+    return args;
+}

package/dist/attrs.js

@@ -338,7 +338,10 @@ export function valueAttr(s, v, n) {
             const make = of === "str" ? "fv::Attr::str" : of === "int" ? "fv::Attr::Int" : of === "float" ? "fv::Attr::Float" : of === "bool" ? "fv::Attr::Bool" : null;
             if (make !== null)
                 return `${atom(v.code)}.map_or(fv::Attr::Undefined, ${make})`;
+            break;
         }
+        default:
+            break;
     }
     return fail(s.comp, "FV0412", "an attribute that may fall through is a string, a number or a boolean", n);
 }

package/dist/calls.js

@@ -2,7 +2,7 @@ import { BOOL, fail, FLOAT, INT, sameTy, STR } from "./model.js";
 import { ctx } from "./context.js";
 import { claim } from "./plugin.js";
 import { atom, bare, binary, condition, operand, receiver, strArg, UNARY } from "./parens.js";
-import { computedListMethod, items, listMethod, objectCall } from "./lists.js";
+import { computedListMethod, isBoolean, items, listMethod, objectCall, presentLiteral } from "./lists.js";
 import { lonely, loneOf, meet, stringMethod, stringsEqual } from "./strings.js";
 import { asF64, intFromF64, isNumber } from "./numbers.js";
 import { boolOf, truthy } from "./narrowing.js";
@@ -41,6 +41,8 @@ export function call(s, n) {
         const helper = s.helpers.get(callee.name);
         if (helper)
             return helperCall(s, helper, args, n);
+        if (isBoolean(s, callee) && args.length === 1)
+            return boolOf(truthy(expr(s, args[0])));
         if (callee.name === "String" && args.length === 1) {
             const a = expr(s, args[0]);
             if (a.ty.k === "str")
@@ -121,7 +123,8 @@ export function call(s, n) {
             }
             return fail(comp, "FV0704", `\`Math.${method}()\` is supported on numbers as \`max\`, \`min\`, \`abs\`, \`round\`, \`floor\`, \`ceil\` and \`trunc\``, n);
         }
-        const target = expr(s, callee.object);
+        const literal = method === "filter" && args.length === 1 && isBoolean(s, args[0]) && callee.object.type === "ArrayExpression";
+        const target = (literal ? presentLiteral(s, callee.object) : null) ?? expr(s, callee.object);
         if (target.ty.k === "str") {
             const lone = loneOf(target);
             switch (args.length === 0 ? method : "") {

package/dist/children.js

@@ -6,8 +6,8 @@ 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 { attrOf, dollarAttrs, isAttrs, mergedParts } from "./attrs.js";
+import { isListener, passedKey } from "./fallthrough.js";
 import { claim, paramsOf, slotContextOf, slotFieldsOf } from "./plugin.js";
 import { statements } from "./template.js";
 import { slotContent, slotFieldBorrows, staticallyFilled } from "./slots.js";
@@ -30,7 +30,17 @@ export function renderChild(s, e, n, twin) {
     const merges = parts.length > 0 && parts[0] !== rawProps;
     const passesAttrs = parts.some(isAttrs);
     const passed = (p) => s.fallthrough !== null && ((isAttrs(p) && s.comp.inheritAttrs) || dollarAttrs(s, p));
-    const marker = (p) => p.type === "ObjectExpression" && p.properties.length > 0 && p.properties.every((q) => q.type === "ObjectProperty" && IGNORED_PROPS.has(q.key.name ?? q.key.value));
+    const handlers = (p) => {
+        const dynamic = p.type === "ObjectProperty" && p.computed && isCall(p.key, "_toHandlerKey");
+        if (!isCall(p, "_toHandlers") && !dynamic)
+            return false;
+        const declared = child.props.fields.find((f) => isListener(f.js));
+        if (declared)
+            fail(s.comp, "FV0514", `a listener whose name is not known before rendering, given to ${child.name}, which declares \`${declared.js}\` as a prop`, p);
+        return true;
+    };
+    const silent = (p) => p.type === "ObjectProperty" && !p.computed && !passedKey(child, p.key.name ?? String(p.key.value));
+    const marker = (p) => handlers(p) || (p.type === "ObjectExpression" && p.properties.length > 0 && p.properties.every((q) => silent(q) || handlers(q)));
     const objects = parts.filter((p) => !isAttrs(p) && !dollarAttrs(s, p) && !marker(p));
     if (parts.some(passed)) {
         for (const name of s.comp.attrNames) {
@@ -60,6 +70,8 @@ export function renderChild(s, e, n, twin) {
     const loaded = !merges && local !== null && s.loadedLater.has(local);
     for (const obj of objects) {
         for (const p of obj.properties) {
+            if (handlers(p))
+                continue;
             if (p.type !== "ObjectProperty" || p.computed)
                 fail(s.comp, "FV0504", "child props hold plain keys", p);
             const key = p.key.type === "Identifier" ? p.key.name : String(p.key.value);
@@ -97,6 +109,9 @@ export function renderChild(s, e, n, twin) {
     });
     callChild(s, e, child, `&super::${child.module}::Props { ${inits.join(", ")} }`, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n), later);
 }
+function isCall(n, callee) {
+    return n?.type === "CallExpression" && n.callee.type === "Identifier" && n.callee.name === callee;
+}
 export function array(key) {
     return /^(0|[1-9]\d*)$/.test(key) && Number(key) < 2 ** 32 - 1;
 }