ferrovue 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/README.md +201 -50
  2. package/dist/attrs.d.ts +2 -1
  3. package/dist/attrs.js +7 -4
  4. package/dist/children.d.ts +2 -2
  5. package/dist/children.js +66 -13
  6. package/dist/classes.d.ts +4 -0
  7. package/dist/classes.js +23 -1
  8. package/dist/client.d.ts +9 -4
  9. package/dist/client.js +106 -17
  10. package/dist/compiler.d.ts +1 -1
  11. package/dist/compiler.js +38 -10
  12. package/dist/component.d.ts +1 -1
  13. package/dist/component.js +2 -3
  14. package/dist/conformance.d.ts +64 -0
  15. package/dist/conformance.js +276 -0
  16. package/dist/context.d.ts +15 -6
  17. package/dist/context.js +3 -0
  18. package/dist/dynamic.d.ts +18 -0
  19. package/dist/dynamic.js +576 -0
  20. package/dist/errors.d.ts +168 -1
  21. package/dist/errors.js +96 -1
  22. package/dist/file-routes.d.ts +33 -0
  23. package/dist/file-routes.js +224 -0
  24. package/dist/fixture.d.ts +16 -0
  25. package/dist/fixture.js +22 -7
  26. package/dist/index.d.ts +1 -1
  27. package/dist/link-router.d.ts +1 -1
  28. package/dist/link-router.js +1 -0
  29. package/dist/lists.d.ts +4 -0
  30. package/dist/lists.js +2 -2
  31. package/dist/loops.js +4 -4
  32. package/dist/model.d.ts +11 -0
  33. package/dist/model.js +44 -1
  34. package/dist/numbers.js +3 -2
  35. package/dist/page-routes.d.ts +9 -0
  36. package/dist/page-routes.js +10 -0
  37. package/dist/plugin.d.ts +13 -1
  38. package/dist/plugin.js +3 -0
  39. package/dist/plugins/client-only.js +3 -0
  40. package/dist/plugins/head.d.ts +15 -0
  41. package/dist/plugins/head.js +385 -0
  42. package/dist/plugins/index.js +3 -1
  43. package/dist/plugins/provide.d.ts +44 -0
  44. package/dist/plugins/provide.js +528 -0
  45. package/dist/plugins/router-link.js +7 -3
  46. package/dist/plugins/router.d.ts +4 -1
  47. package/dist/plugins/router.js +56 -10
  48. package/dist/plugins/stores.js +19 -9
  49. package/dist/routes.d.ts +5 -2
  50. package/dist/routes.js +8 -2
  51. package/dist/rust.js +46 -18
  52. package/dist/script.js +19 -3
  53. package/dist/settle.d.ts +2 -0
  54. package/dist/settle.js +5 -0
  55. package/dist/slots.js +18 -4
  56. package/dist/ssr.d.ts +3 -0
  57. package/dist/ssr.js +29 -0
  58. package/dist/strings.d.ts +3 -0
  59. package/dist/strings.js +16 -2
  60. package/dist/template.js +92 -11
  61. package/dist/testing.d.ts +2 -3
  62. package/dist/testing.js +2 -29
  63. package/dist/types.d.ts +5 -0
  64. package/dist/typescript.js +7 -3
  65. package/dist/vhtml.d.ts +4 -0
  66. package/dist/vhtml.js +63 -0
  67. package/dist/vite.d.ts +7 -1
  68. package/dist/vite.js +65 -5
  69. package/package.json +15 -1
package/dist/errors.d.ts CHANGED
@@ -35,6 +35,10 @@ export declare const ERRORS: {
35
35
  readonly title: "Unexpected construct in Vue's compiled template";
36
36
  readonly detail: "The compiler met output of Vue's server compiler that it has no translation for. Please report it with the component that caused it.";
37
37
  };
38
+ readonly FV0007: {
39
+ readonly title: "Component file name that gives no Rust module of its own";
40
+ readonly detail: "Each component is written to a Rust module named after its file in snake case (`UserCard.vue` is `user_card.rs`). A file name that is not letters, digits and `_` starting with a letter, two names with the same snake case (`FooBar.vue` and `Foo_bar.vue`), `Mod.vue`, and a name a module ferrovue writes for the project already has (`Types.vue`, `Stores.vue`) are refused.";
41
+ };
38
42
  readonly FV0101: {
39
43
  readonly title: "`inheritAttrs` that is not `true` or `false`";
40
44
  };
@@ -250,7 +254,24 @@ export declare const ERRORS: {
250
254
  readonly title: "Attribute name chosen at run time";
251
255
  };
252
256
  readonly FV0418: {
253
- readonly title: "`<component :is>`";
257
+ readonly title: "`<component :is>` over a value that is not a closed set";
258
+ readonly detail: "`<component :is>` compiles to a `match` over its choices, so each one must be known when compiling: an imported component, an HTML element's name, a `computed` or `?:` choosing among them, a prop typed as a union of string literals, or an object of imported components read by such a prop. A `string`, a `Component` or a value from elsewhere could be anything.";
259
+ };
260
+ readonly FV0419: {
261
+ readonly title: "`<component :is>` naming something other than an HTML element";
262
+ };
263
+ readonly FV0420: {
264
+ readonly title: "`<component :is>` over a prop that may be absent";
265
+ };
266
+ readonly FV0421: {
267
+ readonly title: "`<component :is>` reading a key its object does not have";
268
+ };
269
+ readonly FV0422: {
270
+ readonly title: "`v-html` or `v-text` on `<component :is>`";
271
+ };
272
+ readonly FV0423: {
273
+ readonly title: "`v-show`, or `v-model` on `<select>`, in content rendered from virtual nodes";
274
+ readonly detail: "Inside an element `<component :is>` chooses, in the slot content such an element renders, and inside a `<RouterLink>`, Vue's server renders from virtual nodes, where `v-show` writes no `style` while it shows and `v-model` on a `<select>` marks no option `selected`. Bind `:style` or `:selected` yourself.";
254
275
  };
255
276
  readonly FV0501: {
256
277
  readonly title: "Child component that is not among the compiled components";
@@ -541,6 +562,13 @@ export declare const ERRORS: {
541
562
  readonly FV0918: {
542
563
  readonly title: "Slot scope id given to content that takes none";
543
564
  };
565
+ readonly FV0919: {
566
+ readonly title: "`<slot>` with fallback content inside an element `<component :is>` chooses";
567
+ readonly detail: "Inside an element that `<component :is>` chooses, Vue renders a slot's content as virtual nodes and decides whether to show the fallback by rules of their own. Give the fallback from the parent instead.";
568
+ };
569
+ readonly FV0920: {
570
+ readonly title: "`<slot>` rendered both inside and outside an element `<component :is>` chooses";
571
+ };
544
572
  readonly FV1001: {
545
573
  readonly title: "Computed or spread key in a class object";
546
574
  };
@@ -577,6 +605,10 @@ export declare const ERRORS: {
577
605
  readonly FV1012: {
578
606
  readonly title: "Scope ids handed to a component whose render does not take them";
579
607
  };
608
+ readonly FV1013: {
609
+ readonly title: "`class` written apart from a later `:class` in content rendered from virtual nodes";
610
+ readonly detail: "Inside an element `<component :is>` chooses, in the slot content such an element renders, and inside a `<RouterLink>`, Vue's server renders from virtual nodes, where a static `class` written before `:class` keeps its place and its names come first. ferrovue writes them so when nothing stands between the two; with attributes between them, write the two next to each other, or `:class` first.";
611
+ };
580
612
  readonly FV1101: {
581
613
  readonly title: "Helper called with the wrong number of arguments";
582
614
  };
@@ -724,6 +756,32 @@ export declare const ERRORS: {
724
756
  readonly FV1237: {
725
757
  readonly title: "`<RouterView>` in a child component";
726
758
  };
759
+ readonly FV1238: {
760
+ readonly title: "`routes` that is neither a routes file nor `{ pages }`";
761
+ };
762
+ readonly FV1239: {
763
+ readonly title: "Pages folder that cannot be read";
764
+ };
765
+ readonly FV1240: {
766
+ readonly title: "Page file name the router cannot match";
767
+ readonly detail: "Each part of a page's path is plain text (letters, digits, `-` and `_`) or one whole parameter: `[id]`, `[[id]]` (optional) or `[...path]` (a catch-all, last). A parameter beside text in one part (`prefix-[id].vue`), a repeatable parameter (`[id]+`), an optional catch-all (`[[...path]]`), a parameter parser (`[id=int]`) and a character code (`[x+2E]`) are not matched on the server.";
768
+ };
769
+ readonly FV1241: {
770
+ readonly title: "Named view in a page file name";
771
+ };
772
+ readonly FV1242: {
773
+ readonly title: "`definePage()` in a page";
774
+ readonly detail: "`definePage()` changes a page's route (its name, path, alias, meta or params) at build time. ferrovue builds the server's routes from the files' paths alone, so the two would disagree.";
775
+ };
776
+ readonly FV1243: {
777
+ readonly title: "`<route>` block in a page";
778
+ };
779
+ readonly FV1244: {
780
+ readonly title: "`_parent.vue` with no pages to hold";
781
+ };
782
+ readonly FV1245: {
783
+ readonly title: "Page whose component name is taken or not a Rust name";
784
+ };
727
785
  readonly FV1301: {
728
786
  readonly title: "Type declared by two stores";
729
787
  };
@@ -860,6 +918,115 @@ export declare const ERRORS: {
860
918
  readonly FV1510: {
861
919
  readonly title: "Twin for a component ferrovue compiles";
862
920
  };
921
+ readonly FV1511: {
922
+ readonly title: "`<ClientOnly>` with a `#fallback` in content rendered from virtual nodes";
923
+ readonly detail: "Inside an element `<component :is>` chooses, inside a `<RouterLink>` or a twin's slot, and in the slot content they render, Vue's server renders from virtual nodes, and `<ClientOnly>` writes an empty fragment there instead of its fallback, which the client then renders and reports as a mismatch. Leave out the `#fallback`, or move the `<ClientOnly>` outside that content.";
924
+ };
925
+ readonly FV1512: {
926
+ readonly title: "`v-html` on an element whose content the browser rebuilds";
927
+ readonly detail: "The browser's HTML parser moves markup written in a `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>` or `<colgroup>` out of the table, drops the tags written in a `<select>` or `<optgroup>`, and ends SVG or MathML at an HTML tag, so the page holds other nodes than the server wrote and hydration mismatches. Put `v-html` on a `<td>`, `<th>` or `<caption>`, write the options in the template, or use an HTML element inside a `<foreignObject>` or an `<mtext>`. See [`escaping`](crate::guide::escaping).";
928
+ };
929
+ readonly FV1513: {
930
+ readonly title: "`v-html` in a `<p>` of HTML that may hold blocks";
931
+ readonly detail: "A block tag in the HTML (`<p>`, `<ul>`, `<div>`) ends the `<p>` it is written in where the browser reads it. Type the prop `InlineHtml` from `ferrovue/types`, which is `ferrovue::InlineHtml` on the server and keeps only inline tags, or put the HTML in a `<div>`. Slot content placed into a child's `<p>` is not seen at compile time. See [`escaping`](crate::guide::escaping).";
932
+ };
933
+ readonly FV1601: {
934
+ readonly title: "Injection key that is not a string literal or a symbol exported from a `.ts` file";
935
+ };
936
+ readonly FV1602: {
937
+ readonly title: "Injection key symbol without an `InjectionKey<T>` type";
938
+ };
939
+ readonly FV1603: {
940
+ readonly title: "`provide` or `inject` with unsupported arguments";
941
+ };
942
+ readonly FV1604: {
943
+ readonly title: "`inject` that is not bound to a name at the top of `<script setup>`";
944
+ };
945
+ readonly FV1605: {
946
+ readonly title: "`inject(key)!`, asserting a provider";
947
+ };
948
+ readonly FV1606: {
949
+ readonly title: "`inject` of a string key with neither a default nor a type argument";
950
+ };
951
+ readonly FV1607: {
952
+ readonly title: "Function default without the factory flag";
953
+ };
954
+ readonly FV1608: {
955
+ readonly title: "Values of different types provided under one key";
956
+ };
957
+ readonly FV1609: {
958
+ readonly title: "Provided value that may be `null` or `undefined`";
959
+ };
960
+ readonly FV1610: {
961
+ readonly title: "Provided value of a form the context does not hold";
962
+ };
963
+ readonly FV1611: {
964
+ readonly title: "Object provided or given as a default under a key without an interface type";
965
+ };
966
+ readonly FV1612: {
967
+ readonly title: "Provided or default object whose fields do not match its interface";
968
+ };
969
+ readonly FV1613: {
970
+ readonly title: "Ref and plain value under one key";
971
+ };
972
+ readonly FV1614: {
973
+ readonly title: "Key provided twice by one component";
974
+ };
975
+ readonly FV1615: {
976
+ readonly title: "Two keys that give the context one field name";
977
+ };
978
+ readonly FV1616: {
979
+ readonly title: "`provide` in a component that holds `<RouterView>`";
980
+ readonly detail: "The page `<RouterView>` shows is rendered from Rust and handed in as a slot, so it cannot see what the component provides. Provide the value above the router (in Rust, through the `Provides` the page is rendered with) or below it.";
981
+ };
982
+ readonly FV1617: {
983
+ readonly title: "String-keyed `inject` inside a Rust twin's slot";
984
+ readonly detail: "Content in a twin's slot is a child of the library component the twin stands for, which may provide the same string key on the client. Use an `InjectionKey` symbol, which only the project provides.";
985
+ };
986
+ readonly FV1618: {
987
+ readonly title: "Setup that assigns to an injected value";
988
+ };
989
+ readonly FV1619: {
990
+ readonly title: "Function and value provided under one key";
991
+ };
992
+ readonly FV1620: {
993
+ readonly title: "`provide` or `inject` called inside an expression";
994
+ };
995
+ readonly FV1701: {
996
+ readonly title: "Options given to `useHead`";
997
+ };
998
+ readonly FV1702: {
999
+ readonly title: "Head input that is not an object literal";
1000
+ };
1001
+ readonly FV1703: {
1002
+ readonly title: "Head key ferrovue does not translate";
1003
+ };
1004
+ readonly FV1704: {
1005
+ readonly title: "Spread, computed key, hole or method in a head input";
1006
+ };
1007
+ readonly FV1705: {
1008
+ readonly title: "Function in a head input";
1009
+ readonly detail: "unhead calls a function given as a value on the server only when it takes no arguments, as a getter (`title: () => props.title`), which ferrovue evaluates. A `titleTemplate` function and an event handler (`onload`) run with arguments or on the client.";
1010
+ };
1011
+ readonly FV1706: {
1012
+ readonly title: "Head value of a type the head does not take";
1013
+ };
1014
+ readonly FV1707: {
1015
+ readonly title: "`tagPosition`, `tagPriority` or `tagDuplicateStrategy` that is not a literal it accepts";
1016
+ };
1017
+ readonly FV1708: {
1018
+ readonly title: "`useHeadSafe`";
1019
+ };
1020
+ readonly FV1709: {
1021
+ readonly title: "`useSeoMeta` key or value ferrovue does not translate";
1022
+ };
1023
+ readonly FV1710: {
1024
+ readonly title: "`class` or `style` in the head that may be `null`";
1025
+ readonly detail: "unhead's server renderer throws on a `class` or `style` of `null`. Write `?? undefined`, which leaves the attribute out.";
1026
+ };
1027
+ readonly FV1711: {
1028
+ readonly title: "`innerHTML` or `textContent` on a head tag that has no content";
1029
+ };
863
1030
  };
864
1031
  /** A stable error code, as `FV0604`. */
865
1032
  export type Code = keyof typeof ERRORS;
package/dist/errors.js CHANGED
@@ -16,6 +16,8 @@ export const AREAS = {
16
16
  "13": { name: "Pinia stores", guide: "pinia" },
17
17
  "14": { name: "vue-i18n", guide: "i18n" },
18
18
  "15": { name: "Raw HTML, client-only content, teleports and Rust twins", guide: "errors_and_limits" },
19
+ "16": { name: "Provide and inject", guide: "provide_inject" },
20
+ "17": { name: "Page head", guide: "head" },
19
21
  };
20
22
  /** Every code the compiler raises. A code is never reused: one the compiler stops raising is marked
21
23
  * `retired` and stays listed. `pnpm errors:generate` writes the guide's index from this list. */
@@ -32,6 +34,10 @@ export const ERRORS = {
32
34
  title: "Unexpected construct in Vue's compiled template",
33
35
  detail: "The compiler met output of Vue's server compiler that it has no translation for. Please report it with the component that caused it.",
34
36
  },
37
+ FV0007: {
38
+ title: "Component file name that gives no Rust module of its own",
39
+ detail: "Each component is written to a Rust module named after its file in snake case (`UserCard.vue` is `user_card.rs`). A file name that is not letters, digits and `_` starting with a letter, two names with the same snake case (`FooBar.vue` and `Foo_bar.vue`), `Mod.vue`, and a name a module ferrovue writes for the project already has (`Types.vue`, `Stores.vue`) are refused.",
40
+ },
35
41
  FV0101: { title: "`inheritAttrs` that is not `true` or `false`" },
36
42
  FV0102: { title: "`watch` with `immediate`" },
37
43
  FV0103: { title: "Effect that runs once on the server" },
@@ -114,7 +120,18 @@ export const ERRORS = {
114
120
  FV0415: { title: "Value read from `$attrs`" },
115
121
  FV0416: { title: "Root `<Transition>` or `<KeepAlive>` around `v-if` that is given attributes" },
116
122
  FV0417: { title: "Attribute name chosen at run time" },
117
- FV0418: { title: "`<component :is>`" },
123
+ FV0418: {
124
+ title: "`<component :is>` over a value that is not a closed set",
125
+ detail: "`<component :is>` compiles to a `match` over its choices, so each one must be known when compiling: an imported component, an HTML element's name, a `computed` or `?:` choosing among them, a prop typed as a union of string literals, or an object of imported components read by such a prop. A `string`, a `Component` or a value from elsewhere could be anything.",
126
+ },
127
+ FV0419: { title: "`<component :is>` naming something other than an HTML element" },
128
+ FV0420: { title: "`<component :is>` over a prop that may be absent" },
129
+ FV0421: { title: "`<component :is>` reading a key its object does not have" },
130
+ FV0422: { title: "`v-html` or `v-text` on `<component :is>`" },
131
+ FV0423: {
132
+ title: "`v-show`, or `v-model` on `<select>`, in content rendered from virtual nodes",
133
+ detail: "Inside an element `<component :is>` chooses, in the slot content such an element renders, and inside a `<RouterLink>`, Vue's server renders from virtual nodes, where `v-show` writes no `style` while it shows and `v-model` on a `<select>` marks no option `selected`. Bind `:style` or `:selected` yourself.",
134
+ },
118
135
  FV0501: { title: "Child component that is not among the compiled components" },
119
136
  FV0502: { title: "Fallthrough attribute that would reach a child's prop" },
120
137
  FV0503: { title: "Child props that are not an object literal" },
@@ -214,6 +231,11 @@ export const ERRORS = {
214
231
  FV0916: { title: "Outlets of one slot that pass different props" },
215
232
  FV0917: { title: "Interface named as a slot's props type" },
216
233
  FV0918: { title: "Slot scope id given to content that takes none" },
234
+ FV0919: {
235
+ title: "`<slot>` with fallback content inside an element `<component :is>` chooses",
236
+ detail: "Inside an element that `<component :is>` chooses, Vue renders a slot's content as virtual nodes and decides whether to show the fallback by rules of their own. Give the fallback from the parent instead.",
237
+ },
238
+ FV0920: { title: "`<slot>` rendered both inside and outside an element `<component :is>` chooses" },
217
239
  FV1001: { title: "Computed or spread key in a class object" },
218
240
  FV1002: { title: "Computed class name that is not a string" },
219
241
  FV1003: { title: "Class name with spaces around it" },
@@ -226,6 +248,10 @@ export const ERRORS = {
226
248
  FV1010: { title: "Style array mixing a string with objects" },
227
249
  FV1011: { title: "Style property whose place depends on a condition" },
228
250
  FV1012: { title: "Scope ids handed to a component whose render does not take them" },
251
+ FV1013: {
252
+ title: "`class` written apart from a later `:class` in content rendered from virtual nodes",
253
+ detail: "Inside an element `<component :is>` chooses, in the slot content such an element renders, and inside a `<RouterLink>`, Vue's server renders from virtual nodes, where a static `class` written before `:class` keeps its place and its names come first. ferrovue writes them so when nothing stands between the two; with attributes between them, write the two next to each other, or `:class` first.",
254
+ },
229
255
  FV1101: { title: "Helper called with the wrong number of arguments" },
230
256
  FV1102: { title: "Configuration file not found" },
231
257
  FV1103: { title: "Configuration file that is not valid JSON" },
@@ -275,6 +301,20 @@ export const ERRORS = {
275
301
  FV1235: { title: "`??` after a query value with a fallback that is not a string" },
276
302
  FV1236: { title: "`<RouterView>` in a component with `<style scoped>`" },
277
303
  FV1237: { title: "`<RouterView>` in a child component" },
304
+ FV1238: { title: "`routes` that is neither a routes file nor `{ pages }`" },
305
+ FV1239: { title: "Pages folder that cannot be read" },
306
+ FV1240: {
307
+ title: "Page file name the router cannot match",
308
+ detail: "Each part of a page's path is plain text (letters, digits, `-` and `_`) or one whole parameter: `[id]`, `[[id]]` (optional) or `[...path]` (a catch-all, last). A parameter beside text in one part (`prefix-[id].vue`), a repeatable parameter (`[id]+`), an optional catch-all (`[[...path]]`), a parameter parser (`[id=int]`) and a character code (`[x+2E]`) are not matched on the server.",
309
+ },
310
+ FV1241: { title: "Named view in a page file name" },
311
+ FV1242: {
312
+ title: "`definePage()` in a page",
313
+ detail: "`definePage()` changes a page's route (its name, path, alias, meta or params) at build time. ferrovue builds the server's routes from the files' paths alone, so the two would disagree.",
314
+ },
315
+ FV1243: { title: "`<route>` block in a page" },
316
+ FV1244: { title: "`_parent.vue` with no pages to hold" },
317
+ FV1245: { title: "Page whose component name is taken or not a Rust name" },
278
318
  FV1301: { title: "Type declared by two stores" },
279
319
  FV1302: { title: "Store id that is not a string literal" },
280
320
  FV1303: { title: "Store of an unsupported shape" },
@@ -323,6 +363,61 @@ export const ERRORS = {
323
363
  FV1508: { title: "`<Teleport>` target that is not a string" },
324
364
  FV1509: { title: "Twin prop of a type with no Rust type" },
325
365
  FV1510: { title: "Twin for a component ferrovue compiles" },
366
+ FV1511: {
367
+ title: "`<ClientOnly>` with a `#fallback` in content rendered from virtual nodes",
368
+ detail: "Inside an element `<component :is>` chooses, inside a `<RouterLink>` or a twin's slot, and in the slot content they render, Vue's server renders from virtual nodes, and `<ClientOnly>` writes an empty fragment there instead of its fallback, which the client then renders and reports as a mismatch. Leave out the `#fallback`, or move the `<ClientOnly>` outside that content.",
369
+ },
370
+ FV1512: {
371
+ title: "`v-html` on an element whose content the browser rebuilds",
372
+ detail: "The browser's HTML parser moves markup written in a `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>` or `<colgroup>` out of the table, drops the tags written in a `<select>` or `<optgroup>`, and ends SVG or MathML at an HTML tag, so the page holds other nodes than the server wrote and hydration mismatches. Put `v-html` on a `<td>`, `<th>` or `<caption>`, write the options in the template, or use an HTML element inside a `<foreignObject>` or an `<mtext>`. See [`escaping`](crate::guide::escaping).",
373
+ },
374
+ FV1513: {
375
+ title: "`v-html` in a `<p>` of HTML that may hold blocks",
376
+ detail: "A block tag in the HTML (`<p>`, `<ul>`, `<div>`) ends the `<p>` it is written in where the browser reads it. Type the prop `InlineHtml` from `ferrovue/types`, which is `ferrovue::InlineHtml` on the server and keeps only inline tags, or put the HTML in a `<div>`. Slot content placed into a child's `<p>` is not seen at compile time. See [`escaping`](crate::guide::escaping).",
377
+ },
378
+ FV1601: { title: "Injection key that is not a string literal or a symbol exported from a `.ts` file" },
379
+ FV1602: { title: "Injection key symbol without an `InjectionKey<T>` type" },
380
+ FV1603: { title: "`provide` or `inject` with unsupported arguments" },
381
+ FV1604: { title: "`inject` that is not bound to a name at the top of `<script setup>`" },
382
+ FV1605: { title: "`inject(key)!`, asserting a provider" },
383
+ FV1606: { title: "`inject` of a string key with neither a default nor a type argument" },
384
+ FV1607: { title: "Function default without the factory flag" },
385
+ FV1608: { title: "Values of different types provided under one key" },
386
+ FV1609: { title: "Provided value that may be `null` or `undefined`" },
387
+ FV1610: { title: "Provided value of a form the context does not hold" },
388
+ FV1611: { title: "Object provided or given as a default under a key without an interface type" },
389
+ FV1612: { title: "Provided or default object whose fields do not match its interface" },
390
+ FV1613: { title: "Ref and plain value under one key" },
391
+ FV1614: { title: "Key provided twice by one component" },
392
+ FV1615: { title: "Two keys that give the context one field name" },
393
+ FV1616: {
394
+ title: "`provide` in a component that holds `<RouterView>`",
395
+ detail: "The page `<RouterView>` shows is rendered from Rust and handed in as a slot, so it cannot see what the component provides. Provide the value above the router (in Rust, through the `Provides` the page is rendered with) or below it.",
396
+ },
397
+ FV1617: {
398
+ title: "String-keyed `inject` inside a Rust twin's slot",
399
+ detail: "Content in a twin's slot is a child of the library component the twin stands for, which may provide the same string key on the client. Use an `InjectionKey` symbol, which only the project provides.",
400
+ },
401
+ FV1618: { title: "Setup that assigns to an injected value" },
402
+ FV1619: { title: "Function and value provided under one key" },
403
+ FV1620: { title: "`provide` or `inject` called inside an expression" },
404
+ FV1701: { title: "Options given to `useHead`" },
405
+ FV1702: { title: "Head input that is not an object literal" },
406
+ FV1703: { title: "Head key ferrovue does not translate" },
407
+ FV1704: { title: "Spread, computed key, hole or method in a head input" },
408
+ FV1705: {
409
+ title: "Function in a head input",
410
+ detail: "unhead calls a function given as a value on the server only when it takes no arguments, as a getter (`title: () => props.title`), which ferrovue evaluates. A `titleTemplate` function and an event handler (`onload`) run with arguments or on the client.",
411
+ },
412
+ FV1706: { title: "Head value of a type the head does not take" },
413
+ FV1707: { title: "`tagPosition`, `tagPriority` or `tagDuplicateStrategy` that is not a literal it accepts" },
414
+ FV1708: { title: "`useHeadSafe`" },
415
+ FV1709: { title: "`useSeoMeta` key or value ferrovue does not translate" },
416
+ FV1710: {
417
+ title: "`class` or `style` in the head that may be `null`",
418
+ detail: "unhead's server renderer throws on a `class` or `style` of `null`. Write `?? undefined`, which leaves the attribute out.",
419
+ },
420
+ FV1711: { title: "`innerHTML` or `textContent` on a head tag that has no content" },
326
421
  };
327
422
  /** Where a code is documented. */
328
423
  export function docsUrl(code) {
@@ -0,0 +1,33 @@
1
+ import type { RouteEntry } from "./routes.ts";
2
+ /** A route as vue-router's file-based routing builds it from a folder of pages. */
3
+ export interface FileRoute {
4
+ /** The path, relative to the parent's unless it starts with `/`. */
5
+ path: string;
6
+ /** The route's name, absent on a folder and on a `_parent.vue`. */
7
+ name?: string;
8
+ /** The page's `.vue` file, relative to the project root; absent on a folder, which only groups
9
+ * the routes in it. */
10
+ file?: string;
11
+ /** The page's component name, from its file's path: `books/[id].vue` is `BooksId`. */
12
+ component?: string;
13
+ /** The routes nested in it. */
14
+ children?: FileRoute[];
15
+ }
16
+ /** The name ferrovue gives a page's component: the PascalCase of its path in the pages folder. */
17
+ export declare function pageComponentName(rel: string): string;
18
+ /** The routes vue-router's file-based routing builds from the `.vue` files in `pages`, a folder
19
+ * relative to `root`: `index.vue`, `[id].vue`, `[[id]].vue`, `[...path].vue`, `(group)` folders,
20
+ * and a `name.vue` beside a `name/` folder as the layout of the routes in it. */
21
+ export declare function fileRoutes(root: string, pages: string): FileRoute[];
22
+ /** The pages folder `ferrovue.config.json` names, as `routes: { "pages": "…" }`, at the top or in
23
+ * `router`; `null` when the routes come from a file or there are none. */
24
+ export declare function pagesFolder(config: {
25
+ routes?: unknown;
26
+ router?: {
27
+ routes?: unknown;
28
+ };
29
+ }): string | null;
30
+ /** Every page in the routes, layouts and nested pages included. */
31
+ export declare function allPages(routes: FileRoute[]): FileRoute[];
32
+ /** The routes as a routes file lists them, a folder marked as showing no view. */
33
+ export declare function routeEntries(routes: FileRoute[]): RouteEntry[];
@@ -0,0 +1,224 @@
1
+ import { readdirSync, readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { parse as parseSfc } from "@vue/compiler-sfc";
4
+ import { failIn, GenError } from "./model.js";
5
+ const STATIC = /^[A-Za-z0-9_-]+$/;
6
+ const PARAM = /^:\w+(?:\?|\(\.\*\))?$/;
7
+ function node(raw, segment, parent) {
8
+ return { raw, segment, parent, children: new Map(), file: null, unnamed: false };
9
+ }
10
+ function pageFiles(root, dir, under = "") {
11
+ let entries;
12
+ try {
13
+ entries = readdirSync(join(root, dir, under), { withFileTypes: true });
14
+ }
15
+ catch {
16
+ throw new GenError("FV1239", `cannot read the pages folder \`${dir}\``, { file: dir });
17
+ }
18
+ return entries
19
+ .filter((e) => !e.name.startsWith("."))
20
+ .flatMap((e) => {
21
+ const rel = under ? `${under}/${e.name}` : e.name;
22
+ if (e.isDirectory())
23
+ return pageFiles(root, dir, rel);
24
+ return e.isFile() && e.name.endsWith(".vue") ? [rel] : [];
25
+ })
26
+ .toSorted();
27
+ }
28
+ function fileSegment(segment, file) {
29
+ let buffer = "";
30
+ let state = 0;
31
+ let path = "";
32
+ let param = { name: "", optional: false, splat: false, repeatable: false };
33
+ const unsupported = (why) => failIn(file, "FV1240", `\`${segment}\` in the file's path: ${why}`);
34
+ const consume = () => {
35
+ if (state === 0)
36
+ path += buffer;
37
+ else if (state === 4) {
38
+ if (param.repeatable)
39
+ unsupported("a repeatable parameter (`+`) is not supported");
40
+ if (param.optional && param.splat)
41
+ unsupported("an optional catch-all (`[[...name]]`) is not supported");
42
+ path += `:${buffer}${param.splat ? "(.*)" : ""}${param.optional ? "?" : ""}`;
43
+ param = { name: "", optional: false, splat: false, repeatable: false };
44
+ }
45
+ buffer = "";
46
+ };
47
+ for (let pos = 0; pos < segment.length; pos++) {
48
+ const c = segment[pos];
49
+ if (state === 0) {
50
+ if (c === "[") {
51
+ if (buffer)
52
+ consume();
53
+ state = 1;
54
+ }
55
+ else
56
+ buffer += c === "." ? "/" : c;
57
+ }
58
+ else if (state === 1) {
59
+ if (c === "[")
60
+ param.optional = true;
61
+ else if (c === ".") {
62
+ param.splat = true;
63
+ pos += 2;
64
+ }
65
+ else
66
+ buffer += c;
67
+ state = 2;
68
+ }
69
+ else if (state === 2) {
70
+ if (c === "]") {
71
+ if (param.optional)
72
+ pos++;
73
+ state = 4;
74
+ }
75
+ else if (c === ".") {
76
+ param.splat = true;
77
+ pos += 2;
78
+ }
79
+ else if (c === "=")
80
+ unsupported("a parameter parser (`[name=parser]`) is not supported");
81
+ else if (c === "+" && buffer === "x" && !param.splat && !param.optional)
82
+ unsupported("a character code (`[x+2E]`) is not supported");
83
+ else
84
+ buffer += c;
85
+ }
86
+ else {
87
+ if (c === "+")
88
+ param.repeatable = true;
89
+ else
90
+ pos--;
91
+ consume();
92
+ state = 0;
93
+ }
94
+ }
95
+ if (state !== 0 && state !== 4)
96
+ unsupported("a `[` is never closed");
97
+ if (buffer)
98
+ consume();
99
+ const pieces = path.split("/");
100
+ pieces.forEach((piece, i) => {
101
+ if (!STATIC.test(piece) && !PARAM.test(piece)) {
102
+ unsupported("each part of a route's path is letters, digits, `-` and `_`, or one whole parameter (`[id]`, `[[id]]`, `[...path]`)");
103
+ }
104
+ if (piece.endsWith("(.*)") && i < pieces.length - 1)
105
+ unsupported("a catch-all (`[...name]`) is the last part of a path");
106
+ });
107
+ return path;
108
+ }
109
+ function segmentOf(raw, file) {
110
+ if (raw === "" || raw === "index")
111
+ return "";
112
+ if (/^\([^()]*\)$/.test(raw))
113
+ return "";
114
+ return fileSegment(raw, file);
115
+ }
116
+ function insert(at, parts, file, isRoot) {
117
+ const [head, ...tail] = parts;
118
+ const view = head.indexOf("@");
119
+ if (view > 0)
120
+ failIn(file, "FV1241", "a named view (`name@view.vue`) is not supported: `<RouterView>` on the server shows the default view");
121
+ if (head === "_parent" && !tail.length) {
122
+ if (isRoot)
123
+ failIn(file, "FV1244", "`_parent.vue` in the pages folder itself is not supported: put the layout in a folder beside the pages it holds");
124
+ at.file = file;
125
+ at.unnamed = true;
126
+ return;
127
+ }
128
+ let child = at.children.get(head);
129
+ if (!child) {
130
+ child = node(head, segmentOf(head, file), at);
131
+ at.children.set(head, child);
132
+ }
133
+ if (tail.length)
134
+ insert(child, tail, file, false);
135
+ else
136
+ child.file = file;
137
+ }
138
+ function routePath(n) {
139
+ return (n.parent?.parent === null ? "/" : "") + n.segment;
140
+ }
141
+ function routeName(n) {
142
+ return n.parent ? `${routeName(n.parent)}/${n.raw === "index" ? "" : n.raw}` : "";
143
+ }
144
+ function sorted(n) {
145
+ return [...n.children.values()].toSorted((a, b) => routePath(a).localeCompare(routePath(b), "en") || a.raw.localeCompare(b.raw, "en"));
146
+ }
147
+ /** The name ferrovue gives a page's component: the PascalCase of its path in the pages folder. */
148
+ export function pageComponentName(rel) {
149
+ return rel
150
+ .replace(/\.vue$/, "")
151
+ .split(/[^A-Za-z0-9]+/)
152
+ .filter(Boolean)
153
+ .map((w) => w[0].toUpperCase() + w.slice(1))
154
+ .join("");
155
+ }
156
+ function checkSource(root, file) {
157
+ const source = readFileSync(join(root, file), "utf8");
158
+ const { descriptor } = parseSfc(source, { filename: file });
159
+ const block = descriptor.customBlocks.find((b) => b.type === "route");
160
+ if (block) {
161
+ const { line, column } = block.loc.start;
162
+ throw new GenError("FV1243", `${file}:${line}:${column}: a \`<route>\` block changes the route vue-router builds from the page, which ferrovue builds from the file's path alone`, { file, line, column }, "a `<route>` block changes the route vue-router builds from the page, which ferrovue builds from the file's path alone");
163
+ }
164
+ for (const script of [descriptor.script, descriptor.scriptSetup]) {
165
+ const found = script ? /\bdefinePage\s*\(/.exec(script.content) : null;
166
+ if (!script || !found)
167
+ continue;
168
+ const offset = script.loc.start.offset + found.index;
169
+ const before = source.slice(0, offset);
170
+ const line = before.split("\n").length;
171
+ const column = offset - before.lastIndexOf("\n");
172
+ const what = "`definePage()` changes the route vue-router builds from the page, which ferrovue builds from the file's path alone";
173
+ throw new GenError("FV1242", `${file}:${line}:${column}: ${what}`, { file, line, column }, what);
174
+ }
175
+ }
176
+ /** The routes vue-router's file-based routing builds from the `.vue` files in `pages`, a folder
177
+ * relative to `root`: `index.vue`, `[id].vue`, `[[id]].vue`, `[...path].vue`, `(group)` folders,
178
+ * and a `name.vue` beside a `name/` folder as the layout of the routes in it. */
179
+ export function fileRoutes(root, pages) {
180
+ const dir = pages.replace(/\/+$/, "");
181
+ const tree = node("", "", null);
182
+ for (const rel of pageFiles(root, dir)) {
183
+ const file = `${dir}/${rel}`;
184
+ checkSource(root, file);
185
+ insert(tree, rel.slice(0, -".vue".length).split("/"), file, true);
186
+ }
187
+ const record = (n) => {
188
+ if (n.file && n.unnamed && !n.children.size)
189
+ failIn(n.file, "FV1244", "`_parent.vue` is the layout of the pages beside it, and this folder has none");
190
+ if (n.segment.endsWith("(.*)") && n.children.size)
191
+ failIn(n.file ?? `${dir}/${routeName(n).slice(1)}`, "FV1240", "a catch-all (`[...name]`) is the last part of a path: it cannot hold other pages");
192
+ const r = { path: routePath(n) };
193
+ if (n.file && !n.unnamed)
194
+ r.name = routeName(n);
195
+ if (n.file) {
196
+ r.file = n.file;
197
+ r.component = pageComponentName(n.file.slice(dir.length + 1));
198
+ }
199
+ if (n.children.size)
200
+ r.children = sorted(n).map(record);
201
+ return r;
202
+ };
203
+ return sorted(tree).map(record);
204
+ }
205
+ /** The pages folder `ferrovue.config.json` names, as `routes: { "pages": "…" }`, at the top or in
206
+ * `router`; `null` when the routes come from a file or there are none. */
207
+ export function pagesFolder(config) {
208
+ const routes = config.router?.routes ?? config.routes;
209
+ const pages = typeof routes === "object" && routes !== null ? routes.pages : undefined;
210
+ return typeof pages === "string" ? pages : null;
211
+ }
212
+ /** Every page in the routes, layouts and nested pages included. */
213
+ export function allPages(routes) {
214
+ return routes.flatMap((r) => [...(r.file ? [r] : []), ...allPages(r.children ?? [])]);
215
+ }
216
+ /** The routes as a routes file lists them, a folder marked as showing no view. */
217
+ export function routeEntries(routes) {
218
+ return routes.map((r) => ({
219
+ path: r.path,
220
+ ...(r.name !== undefined ? { name: r.name } : {}),
221
+ ...(r.file ? {} : { view: false }),
222
+ ...(r.children ? { children: routeEntries(r.children) } : {}),
223
+ }));
224
+ }
package/dist/fixture.d.ts CHANGED
@@ -12,6 +12,7 @@ export interface Fixture {
12
12
  }
13
13
  /** A fixture's JSON, split into the props and the rest. */
14
14
  export declare function readFixture(json: Record<string, unknown>): Fixture;
15
+ export declare function peer<T>(name: string, needs: string, load: () => Promise<T>): Promise<T>;
15
16
  /** The router options ferrovue reproduces, as the project's configuration gives them. */
16
17
  export interface RouterOptions {
17
18
  base?: string;
@@ -27,6 +28,21 @@ export interface RouterOptions {
27
28
  /** Render on the client from scratch with `createApp`: the scope
28
29
  * ids a fresh client render writes, which the server's must equal for scoped styles to apply. */
29
30
  client?: boolean;
31
+ /** The app hydrates a page the DOM already holds: the head `@unhead/vue` gives it, when the
32
+ * project has it, is its client head, which takes over the tags in the document's head. Otherwise
33
+ * it is the server head `createHead({ disableDefaults: true })`, whose tags the conformance suite
34
+ * writes after the render. */
35
+ hydrate?: boolean;
36
+ /** The application's own `pinia` module, used in place of the one `ferrovue/testing` would
37
+ * import: under vitest the application's stores use the module Vite loads, which must be the
38
+ * one that installs the fixture's state. */
39
+ pinia?: typeof import("pinia");
40
+ /** The application's own `vue-router` module, used in place of the one `ferrovue/testing`
41
+ * would import. */
42
+ vueRouter?: typeof import("vue-router");
43
+ /** The application's own `vue-i18n` module, used in place of the one `ferrovue/testing` would
44
+ * import. */
45
+ vueI18n?: typeof import("vue-i18n");
30
46
  }
31
47
  /** An app rendering one fixture of `component`: with a router over `routes` when there are any. */
32
48
  export declare function fixtureApp(component: Component, fixture: Fixture, routes: RouteEntry[] | null, options?: RouterOptions): Promise<App>;