toiljs 0.0.15 → 0.0.19

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 (273) hide show
  1. package/.babelrc +13 -13
  2. package/.gitattributes +2 -2
  3. package/.github/ISSUE_TEMPLATE/bug_report.md +38 -38
  4. package/.github/ISSUE_TEMPLATE/bug_report.yml +90 -90
  5. package/.github/ISSUE_TEMPLATE/config.yml +8 -8
  6. package/.github/ISSUE_TEMPLATE/feature_request.md +20 -20
  7. package/.github/PULL_REQUEST_TEMPLATE.md +43 -43
  8. package/.github/changelog-config.json +45 -45
  9. package/.github/dependabot.yml +27 -27
  10. package/.github/workflows/ci.yml +191 -191
  11. package/.prettierrc.json +11 -11
  12. package/.vscode/settings.json +9 -9
  13. package/CHANGELOG.md +116 -5
  14. package/LICENSE +187 -187
  15. package/README.md +524 -315
  16. package/as-pect.asconfig.json +34 -34
  17. package/as-pect.config.js +65 -65
  18. package/assets/logo.svg +36 -36
  19. package/build/backend/.tsbuildinfo +1 -1
  20. package/build/backend/index.d.ts +1 -0
  21. package/build/backend/index.js +20 -1
  22. package/build/cli/.tsbuildinfo +1 -1
  23. package/build/cli/index.js +1320 -696
  24. package/build/client/.tsbuildinfo +1 -1
  25. package/build/client/dev/devtools.d.ts +6 -0
  26. package/build/client/dev/devtools.js +479 -0
  27. package/build/client/dev/error-overlay.d.ts +9 -0
  28. package/build/client/dev/error-overlay.js +19 -4
  29. package/build/client/errors.d.ts +1 -0
  30. package/build/client/errors.js +3 -0
  31. package/build/client/index.d.ts +2 -0
  32. package/build/client/index.js +2 -0
  33. package/build/client/navigation/prefetch.d.ts +1 -0
  34. package/build/client/navigation/prefetch.js +35 -0
  35. package/build/client/routing/Router.js +1 -1
  36. package/build/client/routing/hooks.js +6 -2
  37. package/build/client/routing/loader.d.ts +23 -0
  38. package/build/client/routing/loader.js +53 -7
  39. package/build/client/routing/mount.js +4 -3
  40. package/build/client/rpc.d.ts +1 -0
  41. package/build/client/rpc.js +37 -0
  42. package/build/compiler/.tsbuildinfo +1 -1
  43. package/build/compiler/config.d.ts +16 -0
  44. package/build/compiler/config.js +9 -0
  45. package/build/compiler/docs.js +78 -21
  46. package/build/compiler/generate.js +5 -4
  47. package/build/compiler/index.d.ts +3 -2
  48. package/build/compiler/index.js +2 -2
  49. package/build/compiler/plugin.js +228 -0
  50. package/build/compiler/prerender.d.ts +1 -0
  51. package/build/compiler/prerender.js +1 -1
  52. package/build/compiler/seo.d.ts +1 -1
  53. package/build/compiler/seo.js +20 -5
  54. package/build/compiler/ssg.js +39 -2
  55. package/build/compiler/vite.js +25 -0
  56. package/build/io/.tsbuildinfo +1 -1
  57. package/build/io/codec.d.ts +54 -0
  58. package/build/io/codec.js +143 -0
  59. package/build/io/index.d.ts +1 -2
  60. package/build/io/index.js +1 -2
  61. package/build/logger/.tsbuildinfo +1 -1
  62. package/build/shared/.tsbuildinfo +1 -1
  63. package/eslint.config.js +48 -48
  64. package/examples/basic/client/404.tsx +11 -11
  65. package/examples/basic/client/components/.gitkeep +1 -1
  66. package/examples/basic/client/global-error.tsx +13 -13
  67. package/examples/basic/client/layout.tsx +25 -25
  68. package/examples/basic/client/public/images/.gitkeep +1 -1
  69. package/examples/basic/client/public/images/logo.svg +36 -36
  70. package/examples/basic/client/public/robots.txt +2 -2
  71. package/examples/basic/client/routes/docs/[...slug].tsx +12 -12
  72. package/examples/basic/client/routes/features/error/error.tsx +16 -16
  73. package/examples/basic/client/routes/features/index.tsx +1 -1
  74. package/examples/basic/client/routes/features/template/b.tsx +14 -14
  75. package/examples/basic/client/routes/files/[[...slug]].tsx +21 -21
  76. package/examples/basic/client/routes/gallery/layout.tsx +13 -13
  77. package/examples/basic/client/routes/io.tsx +23 -24
  78. package/examples/basic/client/routes/loader-demo/loading.tsx +13 -13
  79. package/examples/basic/client/routes/rest.tsx +74 -0
  80. package/examples/basic/client/routes/rpc.tsx +43 -0
  81. package/examples/basic/client/routes/search.tsx +61 -61
  82. package/examples/basic/client/toil.tsx +5 -5
  83. package/package.json +167 -148
  84. package/presets/eslint.js +88 -88
  85. package/presets/no-uint8array-tostring.js +200 -200
  86. package/presets/prettier-plugin.js +51 -0
  87. package/presets/prettier.json +19 -18
  88. package/presets/tsconfig.json +37 -37
  89. package/server/runtime/README.md +97 -0
  90. package/server/runtime/abort/abort.ts +27 -0
  91. package/server/runtime/env/Server.ts +61 -0
  92. package/server/runtime/envelope.ts +191 -0
  93. package/server/runtime/exports/index.ts +52 -0
  94. package/server/runtime/handlers/ToilHandler.ts +34 -0
  95. package/server/runtime/index.ts +26 -0
  96. package/server/runtime/lang/Potential.ts +5 -0
  97. package/server/runtime/memory.ts +81 -0
  98. package/server/runtime/request.ts +55 -0
  99. package/server/runtime/response.ts +86 -0
  100. package/server/runtime/rest/Rest.ts +39 -0
  101. package/server/runtime/rest/RestHandler.ts +20 -0
  102. package/server/runtime/rest/RouteContext.ts +82 -0
  103. package/server/runtime/rest/match.ts +48 -0
  104. package/server/runtime/tsconfig.json +7 -0
  105. package/src/backend/index.ts +202 -160
  106. package/src/cli/create.ts +15 -5
  107. package/src/cli/diagnostics.ts +81 -0
  108. package/src/cli/doctor.ts +384 -7
  109. package/src/cli/index.ts +11 -2
  110. package/src/cli/proc.ts +50 -50
  111. package/src/cli/updates.ts +69 -69
  112. package/src/cli/validate.ts +31 -31
  113. package/src/client/channel/channel.ts +146 -146
  114. package/src/client/components/Form.tsx +65 -65
  115. package/src/client/components/Script.tsx +113 -113
  116. package/src/client/components/Slot.tsx +21 -21
  117. package/src/client/dev/devtools.tsx +1018 -0
  118. package/src/client/dev/error-overlay.tsx +30 -4
  119. package/src/client/errors.ts +11 -0
  120. package/src/client/head/head.ts +167 -167
  121. package/src/client/head/metadata.ts +112 -112
  122. package/src/client/index.ts +91 -89
  123. package/src/client/navigation/NavLink.tsx +86 -86
  124. package/src/client/navigation/navigation.ts +235 -235
  125. package/src/client/navigation/prefetch.ts +169 -130
  126. package/src/client/navigation/scroll.ts +53 -53
  127. package/src/client/routing/Router.tsx +8 -2
  128. package/src/client/routing/action.ts +122 -122
  129. package/src/client/routing/error-boundary.tsx +43 -43
  130. package/src/client/routing/hooks.ts +21 -6
  131. package/src/client/routing/loader.ts +325 -235
  132. package/src/client/routing/match.ts +47 -47
  133. package/src/client/routing/mount.tsx +54 -52
  134. package/src/client/routing/params-context.ts +10 -10
  135. package/src/client/routing/slot-context.ts +7 -7
  136. package/src/client/rpc.ts +64 -0
  137. package/src/client/search/search.ts +189 -189
  138. package/src/client/search/use-page-search.ts +73 -73
  139. package/src/client/types.ts +73 -73
  140. package/src/compiler/config.ts +221 -182
  141. package/src/compiler/docs.ts +285 -228
  142. package/src/compiler/generate.ts +395 -394
  143. package/src/compiler/index.ts +66 -57
  144. package/src/compiler/pages.ts +70 -70
  145. package/src/compiler/plugin.ts +258 -2
  146. package/src/compiler/prerender.ts +156 -156
  147. package/src/compiler/seo.ts +417 -390
  148. package/src/compiler/ssg.ts +171 -126
  149. package/src/compiler/vite.ts +34 -0
  150. package/src/io/FastMap.ts +151 -127
  151. package/src/io/FastSet.ts +15 -1
  152. package/src/io/codec.ts +217 -0
  153. package/src/io/index.ts +10 -11
  154. package/src/io/lengths.ts +14 -14
  155. package/src/io/types.ts +19 -18
  156. package/src/logger/index.ts +22 -22
  157. package/src/shared/index.ts +10 -10
  158. package/std/client/index.d.ts +15 -15
  159. package/std/client/package.json +3 -3
  160. package/test/assembly/example.spec.ts +17 -7
  161. package/test/channel.test.ts +21 -21
  162. package/test/doctor.test.ts +65 -0
  163. package/test/dom/Link.test.tsx +47 -47
  164. package/test/dom/NavLink.test.tsx +37 -37
  165. package/test/dom/error-overlay.test.tsx +44 -44
  166. package/test/dom/loader.test.tsx +121 -121
  167. package/test/dom/navigation.test.ts +59 -59
  168. package/test/dom/revalidate.test.tsx +38 -38
  169. package/test/dom/route-head.test.tsx +78 -78
  170. package/test/dom/router-loading.test.tsx +44 -44
  171. package/test/dom/scroll.test.ts +56 -56
  172. package/test/dom/use-metadata.test.tsx +58 -58
  173. package/test/errors.test.ts +21 -0
  174. package/test/io.test.ts +117 -93
  175. package/test/navlink.test.ts +28 -28
  176. package/test/placeholder.test.ts +9 -9
  177. package/test/prettier-plugin.test.ts +46 -0
  178. package/test/routes.test.ts +76 -76
  179. package/test/rpc.test.ts +50 -0
  180. package/test/seo.test.ts +175 -164
  181. package/test/slot-layouts.test.ts +69 -69
  182. package/test/ssg.test.ts +36 -36
  183. package/test/update.test.ts +44 -44
  184. package/test/validate.test.ts +42 -42
  185. package/tests/data-parity/generated-parity.ts +99 -0
  186. package/tests/data-parity/parity.ts +80 -0
  187. package/tests/data-parity/spec.ts +46 -0
  188. package/toil-routes.d.ts +7 -0
  189. package/tsconfig.backend.json +13 -13
  190. package/tsconfig.base.json +35 -35
  191. package/tsconfig.cli.json +13 -13
  192. package/tsconfig.client.json +14 -14
  193. package/tsconfig.compiler.json +13 -13
  194. package/tsconfig.io.json +12 -12
  195. package/tsconfig.json +22 -22
  196. package/tsconfig.logger.json +12 -12
  197. package/tsconfig.server.json +10 -10
  198. package/tsconfig.shared.json +12 -12
  199. package/vitest.config.ts +26 -26
  200. package/.idea/codeStyles/Project.xml +0 -54
  201. package/.idea/codeStyles/codeStyleConfig.xml +0 -5
  202. package/.idea/inspectionProfiles/Project_Default.xml +0 -6
  203. package/.idea/modules.xml +0 -8
  204. package/.idea/prettier.xml +0 -7
  205. package/.idea/toiljs.iml +0 -8
  206. package/.idea/vcs.xml +0 -6
  207. package/.toil/entry.tsx +0 -9
  208. package/.toil/index.html +0 -12
  209. package/.toil/routes.ts +0 -9
  210. package/build/cli/configure.d.ts +0 -16
  211. package/build/cli/configure.js +0 -272
  212. package/build/cli/create.d.ts +0 -16
  213. package/build/cli/create.js +0 -420
  214. package/build/cli/diagnostics.d.ts +0 -55
  215. package/build/cli/diagnostics.js +0 -333
  216. package/build/cli/doctor.d.ts +0 -6
  217. package/build/cli/doctor.js +0 -249
  218. package/build/cli/features.d.ts +0 -25
  219. package/build/cli/features.js +0 -107
  220. package/build/cli/index.d.ts +0 -2
  221. package/build/cli/proc.d.ts +0 -6
  222. package/build/cli/proc.js +0 -31
  223. package/build/cli/ui.d.ts +0 -9
  224. package/build/cli/ui.js +0 -75
  225. package/build/cli/update.d.ts +0 -7
  226. package/build/cli/update.js +0 -117
  227. package/build/cli/updates.d.ts +0 -10
  228. package/build/cli/updates.js +0 -45
  229. package/build/cli/validate.d.ts +0 -4
  230. package/build/cli/validate.js +0 -19
  231. package/build/client/Link.d.ts +0 -8
  232. package/build/client/Link.js +0 -44
  233. package/build/client/NavLink.d.ts +0 -14
  234. package/build/client/NavLink.js +0 -37
  235. package/build/client/Router.d.ts +0 -7
  236. package/build/client/Router.js +0 -55
  237. package/build/client/channel.d.ts +0 -23
  238. package/build/client/channel.js +0 -94
  239. package/build/client/error-boundary.d.ts +0 -16
  240. package/build/client/error-boundary.js +0 -19
  241. package/build/client/head.d.ts +0 -26
  242. package/build/client/head.js +0 -87
  243. package/build/client/hooks.d.ts +0 -17
  244. package/build/client/hooks.js +0 -48
  245. package/build/client/lazy.d.ts +0 -16
  246. package/build/client/lazy.js +0 -53
  247. package/build/client/match.d.ts +0 -2
  248. package/build/client/match.js +0 -32
  249. package/build/client/mount.d.ts +0 -2
  250. package/build/client/mount.js +0 -13
  251. package/build/client/navigation.d.ts +0 -13
  252. package/build/client/navigation.js +0 -97
  253. package/build/client/params-context.d.ts +0 -2
  254. package/build/client/params-context.js +0 -2
  255. package/build/client/prefetch.d.ts +0 -11
  256. package/build/client/prefetch.js +0 -100
  257. package/build/client/runtime.d.ts +0 -31
  258. package/build/client/runtime.js +0 -112
  259. package/build/client/scroll.d.ts +0 -8
  260. package/build/client/scroll.js +0 -36
  261. package/build/io/BinaryReader.d.ts +0 -44
  262. package/build/io/BinaryReader.js +0 -244
  263. package/build/io/BinaryWriter.d.ts +0 -44
  264. package/build/io/BinaryWriter.js +0 -297
  265. package/build/server/release.wasm +0 -0
  266. package/build/server/release.wat +0 -9
  267. package/src/io/BinaryReader.ts +0 -340
  268. package/src/io/BinaryWriter.ts +0 -385
  269. package/src/server/index.ts +0 -10
  270. package/src/server/main.ts +0 -13
  271. package/src/server/tsconfig.json +0 -4
  272. package/toil-env.d.ts +0 -16
  273. package/toilconfig.json +0 -30
package/src/client/dev/error-overlay.tsx CHANGED
@@ -7,21 +7,33 @@
7
7
  import { Component, type CSSProperties, type ErrorInfo, type ReactNode, useSyncExternalStore, } from 'react';
8
8
 
9
9
  /** A captured dev error. */
10
- interface DevError {
10
+ export interface DevError {
11
11
  readonly error: Error;
12
12
  readonly componentStack?: string;
13
13
  /** Where it came from, a render boundary, a window `error`, or an unhandled rejection. */
14
14
  readonly source: 'render' | 'window' | 'unhandledrejection';
15
+ /** Capture time (ms epoch). */
16
+ readonly time: number;
15
17
  }
16
18
 
17
19
  let current: DevError | null = null;
18
20
  const listeners = new Set<() => void>();
21
+ /**
22
+ * Bounded history of captured errors, for the dev toolbar's Errors tab. Reassigned to a new array
23
+ * on each change (never mutated in place) so `getErrorLog` is a stable useSyncExternalStore snapshot:
24
+ * the reference changes only when the log changes, so React re-renders on new errors but not in a loop.
25
+ */
26
+ let errorLog: readonly DevError[] = [];
27
+ const MAX_LOG = 50;
19
28
 
20
29
  function emit(): void {
21
30
  for (const listener of listeners) listener();
22
31
  }
23
32
  function setDevError(next: DevError | null): void {
24
33
  current = next;
34
+ if (next) {
35
+ errorLog = [...errorLog, next].slice(-MAX_LOG);
36
+ }
25
37
  emit();
26
38
  }
27
39
  function subscribe(listener: () => void): () => void {
@@ -31,6 +43,13 @@ function subscribe(listener: () => void): () => void {
31
43
  };
32
44
  }
33
45
 
46
+ /** The captured-error history (most recent last). Subscribe via {@link subscribeErrors}. */
47
+ export function getErrorLog(): readonly DevError[] {
48
+ return errorLog;
49
+ }
50
+ /** Subscribes to error captures (fires whenever a new error is recorded or dismissed). */
51
+ export const subscribeErrors = subscribe;
52
+
34
53
  /** True when running under Vite's dev server (replaced at build time; falsy in production). */
35
54
  export function isDevMode(): boolean {
36
55
  try {
@@ -46,12 +65,14 @@ export function initDevErrorOverlay(): void {
46
65
  if (windowBound || typeof window === 'undefined') return;
47
66
  windowBound = true;
48
67
  window.addEventListener('error', (event) => {
49
- if (event.error instanceof Error) setDevError({ error: event.error, source: 'window' });
68
+ if (event.error instanceof Error) {
69
+ setDevError({ error: event.error, source: 'window', time: Date.now() });
70
+ }
50
71
  });
51
72
  window.addEventListener('unhandledrejection', (event) => {
52
73
  const reason: unknown = event.reason;
53
74
  const error = reason instanceof Error ? reason : new Error(String(reason));
54
- setDevError({ error, source: 'unhandledrejection' });
75
+ setDevError({ error, source: 'unhandledrejection', time: Date.now() });
55
76
  });
56
77
  }
57
78
 
@@ -76,7 +97,12 @@ export class DevErrorBoundary extends Component<BoundaryProps, BoundaryState> {
76
97
  }
77
98
 
78
99
  public override componentDidCatch(error: Error, info: ErrorInfo): void {
79
- setDevError({ error, componentStack: info.componentStack ?? undefined, source: 'render' });
100
+ setDevError({
101
+ error,
102
+ componentStack: info.componentStack ?? undefined,
103
+ source: 'render',
104
+ time: Date.now(),
105
+ });
80
106
  }
81
107
 
82
108
  public override componentDidMount(): void {
package/src/client/errors.ts ADDED
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Extracts a human-readable message from an unknown thrown value. Handy in `catch`
3
+ * blocks where the caught value is typed `unknown`. Exposed as a global `parseError`
4
+ * (no import) alongside the other toiljs globals.
5
+ *
6
+ * @param err - the caught value (an `Error`, a string, or anything else).
7
+ * @returns the `Error.message` when `err` is an `Error`, otherwise `String(err)`.
8
+ */
9
+ export function parseError(err: unknown): string {
10
+ return err instanceof Error ? err.message : String(err);
11
+ }
package/src/client/head/head.ts CHANGED
@@ -1,167 +1,167 @@
1
- /**
2
- * Client-side document `<head>` management. `useHead` / `useTitle` / `<Head>` let any component
3
- * (layout or page) set the title and `<meta>` / `<link>` tags; entries compose across the tree
4
- * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
5
- * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
6
- */
7
- import { useEffect, useLayoutEffect } from 'react';
8
-
9
- /** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
10
- export interface MetaTag {
11
- readonly name?: string;
12
- readonly property?: string;
13
- readonly content: string;
14
- readonly [attr: string]: string | undefined;
15
- }
16
-
17
- /** A `<link>` tag (deduped by `rel` + `href`); extra attrs pass through. */
18
- export interface LinkTag {
19
- readonly rel: string;
20
- readonly href: string;
21
- readonly [attr: string]: string | undefined;
22
- }
23
-
24
- /** A head contribution from one component. */
25
- export interface HeadSpec {
26
- /** Document title. */
27
- readonly title?: string;
28
- /** Template applied to a child's title, `%s` = the title (e.g. `'%s · toiljs'`). */
29
- readonly titleTemplate?: string;
30
- readonly meta?: readonly MetaTag[];
31
- readonly link?: readonly LinkTag[];
32
- }
33
-
34
- /** The resolved head after merging all active specs. */
35
- export interface ResolvedHead {
36
- readonly title?: string;
37
- readonly meta: MetaTag[];
38
- readonly link: LinkTag[];
39
- }
40
-
41
- function metaKey(m: MetaTag): string {
42
- if (m.name !== undefined) return `name:${m.name}`;
43
- if (m.property !== undefined) return `property:${m.property}`;
44
- return `meta:${JSON.stringify(m)}`;
45
- }
46
-
47
- /**
48
- * Merges head specs in order: the last `title`/`titleTemplate` wins, `meta` dedupes by name/property
49
- * and `link` by rel+href (last wins). A `titleTemplate` formats the resolved title via `%s`.
50
- */
51
- export function mergeHead(specs: readonly HeadSpec[]): ResolvedHead {
52
- let title: string | undefined;
53
- let titleTemplate: string | undefined;
54
- const meta = new Map<string, MetaTag>();
55
- const link = new Map<string, LinkTag>();
56
- for (const spec of specs) {
57
- if (spec.title !== undefined) title = spec.title;
58
- if (spec.titleTemplate !== undefined) titleTemplate = spec.titleTemplate;
59
- for (const m of spec.meta ?? []) meta.set(metaKey(m), m);
60
- for (const l of spec.link ?? []) link.set(`${l.rel}:${l.href}`, l);
61
- }
62
- const resolvedTitle =
63
- title !== undefined && titleTemplate !== undefined
64
- ? titleTemplate.replace('%s', title)
65
- : title;
66
- return { title: resolvedTitle, meta: [...meta.values()], link: [...link.values()] };
67
- }
68
-
69
- const entries = new Map<number, HeadSpec>();
70
- let order: number[] = [];
71
- let seq = 0;
72
- let baseTitle: string | null = null;
73
- // The current route's resolved `metadata` export. Merged LAST (highest priority), so a route's
74
- // metadata wins over a layout's `useHead`/`<Head>` defaults (e.g. a site-wide title/titleTemplate) for
75
- // the keys it sets, while the layout still fills everything the route leaves unset. Set by the router
76
- // via `setRouteHead` on each navigation.
77
- let routeHead: HeadSpec | null = null;
78
-
79
- function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
80
- el.setAttribute('data-toil-head', '');
81
- for (const [key, value] of Object.entries(attrs)) {
82
- if (value !== undefined) el.setAttribute(key, value);
83
- }
84
- }
85
-
86
- /** Reconciles `document.head` with the merged active specs. */
87
- function apply(): void {
88
- if (typeof document === 'undefined') return;
89
- if (baseTitle === null) baseTitle = document.title;
90
-
91
- const specs = [...order.map((id) => entries.get(id)), routeHead];
92
- const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
93
-
94
- document.title = resolved.title ?? baseTitle;
95
-
96
- for (const stale of document.head.querySelectorAll('[data-toil-head]')) stale.remove();
97
- for (const m of resolved.meta) {
98
- const el = document.createElement('meta');
99
- setAttrs(el, m);
100
- document.head.appendChild(el);
101
- }
102
- for (const l of resolved.link) {
103
- const el = document.createElement('link');
104
- setAttrs(el, l);
105
- document.head.appendChild(el);
106
- }
107
- }
108
-
109
- function addHead(spec: HeadSpec): number {
110
- const id = ++seq;
111
- entries.set(id, spec);
112
- order.push(id);
113
- apply();
114
- return id;
115
- }
116
-
117
- function removeHead(id: number): void {
118
- entries.delete(id);
119
- order = order.filter((x) => x !== id);
120
- apply();
121
- }
122
-
123
- /**
124
- * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
125
- * Reverts on unmount. Compose freely, a root layout can set defaults a page overrides.
126
- */
127
- export function useHead(spec: HeadSpec): void {
128
- const json = JSON.stringify(spec);
129
- useEffect(() => {
130
- const id = addHead(JSON.parse(json) as HeadSpec);
131
- return () => {
132
- removeHead(id);
133
- };
134
- }, [json]);
135
- }
136
-
137
- /** Sets `document.title` for the calling component's lifetime. */
138
- export function useTitle(title: string): void {
139
- useHead({ title });
140
- }
141
-
142
- /** Declarative form of {@link useHead}: `<Head title="…" meta={[…]} />`. Renders nothing. */
143
- export function Head(props: HeadSpec): null {
144
- useHead(props);
145
- return null;
146
- }
147
-
148
- /** Sets the current route's baseline head (lowest priority). Pass `null` to clear it. */
149
- export function setRouteHead(spec: HeadSpec | null): void {
150
- routeHead = spec;
151
- apply();
152
- }
153
-
154
- /**
155
- * Applies a route's resolved `metadata` as the baseline head for the calling route's lifetime, and
156
- * clears it on unmount. Used internally by the router; a layout-effect so the title updates before
157
- * paint (no flicker).
158
- */
159
- export function useRouteHead(spec: HeadSpec | undefined): void {
160
- const json = spec ? JSON.stringify(spec) : '';
161
- useLayoutEffect(() => {
162
- setRouteHead(json ? (JSON.parse(json) as HeadSpec) : null);
163
- return () => {
164
- setRouteHead(null);
165
- };
166
- }, [json]);
167
- }
1
+ /**
2
+ * Client-side document `<head>` management. `useHead` / `useTitle` / `<Head>` let any component
3
+ * (layout or page) set the title and `<meta>` / `<link>` tags; entries compose across the tree
4
+ * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
5
+ * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
6
+ */
7
+ import { useEffect, useLayoutEffect } from 'react';
8
+
9
+ /** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
10
+ export interface MetaTag {
11
+ readonly name?: string;
12
+ readonly property?: string;
13
+ readonly content: string;
14
+ readonly [attr: string]: string | undefined;
15
+ }
16
+
17
+ /** A `<link>` tag (deduped by `rel` + `href`); extra attrs pass through. */
18
+ export interface LinkTag {
19
+ readonly rel: string;
20
+ readonly href: string;
21
+ readonly [attr: string]: string | undefined;
22
+ }
23
+
24
+ /** A head contribution from one component. */
25
+ export interface HeadSpec {
26
+ /** Document title. */
27
+ readonly title?: string;
28
+ /** Template applied to a child's title, `%s` = the title (e.g. `'%s · toiljs'`). */
29
+ readonly titleTemplate?: string;
30
+ readonly meta?: readonly MetaTag[];
31
+ readonly link?: readonly LinkTag[];
32
+ }
33
+
34
+ /** The resolved head after merging all active specs. */
35
+ export interface ResolvedHead {
36
+ readonly title?: string;
37
+ readonly meta: MetaTag[];
38
+ readonly link: LinkTag[];
39
+ }
40
+
41
+ function metaKey(m: MetaTag): string {
42
+ if (m.name !== undefined) return `name:${m.name}`;
43
+ if (m.property !== undefined) return `property:${m.property}`;
44
+ return `meta:${JSON.stringify(m)}`;
45
+ }
46
+
47
+ /**
48
+ * Merges head specs in order: the last `title`/`titleTemplate` wins, `meta` dedupes by name/property
49
+ * and `link` by rel+href (last wins). A `titleTemplate` formats the resolved title via `%s`.
50
+ */
51
+ export function mergeHead(specs: readonly HeadSpec[]): ResolvedHead {
52
+ let title: string | undefined;
53
+ let titleTemplate: string | undefined;
54
+ const meta = new Map<string, MetaTag>();
55
+ const link = new Map<string, LinkTag>();
56
+ for (const spec of specs) {
57
+ if (spec.title !== undefined) title = spec.title;
58
+ if (spec.titleTemplate !== undefined) titleTemplate = spec.titleTemplate;
59
+ for (const m of spec.meta ?? []) meta.set(metaKey(m), m);
60
+ for (const l of spec.link ?? []) link.set(`${l.rel}:${l.href}`, l);
61
+ }
62
+ const resolvedTitle =
63
+ title !== undefined && titleTemplate !== undefined
64
+ ? titleTemplate.replace('%s', title)
65
+ : title;
66
+ return { title: resolvedTitle, meta: [...meta.values()], link: [...link.values()] };
67
+ }
68
+
69
+ const entries = new Map<number, HeadSpec>();
70
+ let order: number[] = [];
71
+ let seq = 0;
72
+ let baseTitle: string | null = null;
73
+ // The current route's resolved `metadata` export. Merged LAST (highest priority), so a route's
74
+ // metadata wins over a layout's `useHead`/`<Head>` defaults (e.g. a site-wide title/titleTemplate) for
75
+ // the keys it sets, while the layout still fills everything the route leaves unset. Set by the router
76
+ // via `setRouteHead` on each navigation.
77
+ let routeHead: HeadSpec | null = null;
78
+
79
+ function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
80
+ el.setAttribute('data-toil-head', '');
81
+ for (const [key, value] of Object.entries(attrs)) {
82
+ if (value !== undefined) el.setAttribute(key, value);
83
+ }
84
+ }
85
+
86
+ /** Reconciles `document.head` with the merged active specs. */
87
+ function apply(): void {
88
+ if (typeof document === 'undefined') return;
89
+ if (baseTitle === null) baseTitle = document.title;
90
+
91
+ const specs = [...order.map((id) => entries.get(id)), routeHead];
92
+ const resolved = mergeHead(specs.filter((s): s is HeadSpec => !!s));
93
+
94
+ document.title = resolved.title ?? baseTitle;
95
+
96
+ for (const stale of document.head.querySelectorAll('[data-toil-head]')) stale.remove();
97
+ for (const m of resolved.meta) {
98
+ const el = document.createElement('meta');
99
+ setAttrs(el, m);
100
+ document.head.appendChild(el);
101
+ }
102
+ for (const l of resolved.link) {
103
+ const el = document.createElement('link');
104
+ setAttrs(el, l);
105
+ document.head.appendChild(el);
106
+ }
107
+ }
108
+
109
+ function addHead(spec: HeadSpec): number {
110
+ const id = ++seq;
111
+ entries.set(id, spec);
112
+ order.push(id);
113
+ apply();
114
+ return id;
115
+ }
116
+
117
+ function removeHead(id: number): void {
118
+ entries.delete(id);
119
+ order = order.filter((x) => x !== id);
120
+ apply();
121
+ }
122
+
123
+ /**
124
+ * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
125
+ * Reverts on unmount. Compose freely, a root layout can set defaults a page overrides.
126
+ */
127
+ export function useHead(spec: HeadSpec): void {
128
+ const json = JSON.stringify(spec);
129
+ useEffect(() => {
130
+ const id = addHead(JSON.parse(json) as HeadSpec);
131
+ return () => {
132
+ removeHead(id);
133
+ };
134
+ }, [json]);
135
+ }
136
+
137
+ /** Sets `document.title` for the calling component's lifetime. */
138
+ export function useTitle(title: string): void {
139
+ useHead({ title });
140
+ }
141
+
142
+ /** Declarative form of {@link useHead}: `<Head title="…" meta={[…]} />`. Renders nothing. */
143
+ export function Head(props: HeadSpec): null {
144
+ useHead(props);
145
+ return null;
146
+ }
147
+
148
+ /** Sets the current route's baseline head (lowest priority). Pass `null` to clear it. */
149
+ export function setRouteHead(spec: HeadSpec | null): void {
150
+ routeHead = spec;
151
+ apply();
152
+ }
153
+
154
+ /**
155
+ * Applies a route's resolved `metadata` as the baseline head for the calling route's lifetime, and
156
+ * clears it on unmount. Used internally by the router; a layout-effect so the title updates before
157
+ * paint (no flicker).
158
+ */
159
+ export function useRouteHead(spec: HeadSpec | undefined): void {
160
+ const json = spec ? JSON.stringify(spec) : '';
161
+ useLayoutEffect(() => {
162
+ setRouteHead(json ? (JSON.parse(json) as HeadSpec) : null);
163
+ return () => {
164
+ setRouteHead(null);
165
+ };
166
+ }, [json]);
167
+ }
package/src/client/head/metadata.ts CHANGED
@@ -1,112 +1,112 @@
1
- /**
2
- * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
3
- * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
4
- * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
5
- * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
6
- */
7
- import { useHead, type HeadSpec, type LinkTag, type MetaTag } from './head.js';
8
- import type { RouteParams } from '../routing/match.js';
9
-
10
- /** OpenGraph fields, expanded to `og:*` meta tags. */
11
- export interface OpenGraph {
12
- readonly title?: string;
13
- readonly description?: string;
14
- readonly type?: string;
15
- readonly url?: string;
16
- readonly image?: string;
17
- readonly siteName?: string;
18
- }
19
-
20
- /** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
21
- export interface Metadata {
22
- /** Document title. */
23
- readonly title?: string;
24
- /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
25
- readonly titleTemplate?: string;
26
- /** `<meta name="description">`. */
27
- readonly description?: string;
28
- /** `<meta name="keywords">`, joined with `, ` if an array. */
29
- readonly keywords?: string | readonly string[];
30
- /** `<link rel="canonical">`. */
31
- readonly canonical?: string;
32
- /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
33
- readonly robots?: string;
34
- /** `<meta name="theme-color">`. */
35
- readonly themeColor?: string;
36
- /** OpenGraph (`og:*`) tags. */
37
- readonly openGraph?: OpenGraph;
38
- /** Escape hatch: extra raw `<meta>` tags. */
39
- readonly meta?: readonly MetaTag[];
40
- /** Escape hatch: extra raw `<link>` tags. */
41
- readonly link?: readonly LinkTag[];
42
- }
43
-
44
- /** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
45
- export interface GenerateMetadataArgs<T = unknown> {
46
- readonly params: RouteParams;
47
- readonly searchParams: URLSearchParams;
48
- readonly data: T;
49
- }
50
-
51
- /** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
52
- export type GenerateMetadata<T = unknown> = (
53
- args: GenerateMetadataArgs<T>,
54
- ) => Metadata | Promise<Metadata>;
55
-
56
- /** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
57
- export function resolveMetadata(metadata: Metadata): HeadSpec {
58
- const meta: MetaTag[] = [];
59
- if (metadata.description !== undefined) {
60
- meta.push({ name: 'description', content: metadata.description });
61
- }
62
- if (metadata.keywords !== undefined) {
63
- const content =
64
- typeof metadata.keywords === 'string'
65
- ? metadata.keywords
66
- : metadata.keywords.join(', ');
67
- meta.push({ name: 'keywords', content });
68
- }
69
- if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
70
- if (metadata.themeColor !== undefined) {
71
- meta.push({ name: 'theme-color', content: metadata.themeColor });
72
- }
73
- const og = metadata.openGraph;
74
- if (og) {
75
- const pairs: readonly [string, string | undefined][] = [
76
- ['og:title', og.title],
77
- ['og:description', og.description],
78
- ['og:type', og.type],
79
- ['og:url', og.url],
80
- ['og:image', og.image],
81
- ['og:site_name', og.siteName],
82
- ];
83
- for (const [property, content] of pairs) {
84
- if (content !== undefined) meta.push({ property, content });
85
- }
86
- }
87
- if (metadata.meta) meta.push(...metadata.meta);
88
-
89
- const link: LinkTag[] = [];
90
- if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
91
- if (metadata.link) link.push(...metadata.link);
92
-
93
- return { title: metadata.title, titleTemplate: metadata.titleTemplate, meta, link };
94
- }
95
-
96
- /**
97
- * Applies a route-style {@link Metadata} object from inside any component for that component's
98
- * lifetime, reverting on unmount. The runtime counterpart of a route's `metadata` export, for
99
- * content that isn't itself a route file (a rendered article, a widget, ...). Composes through the
100
- * head manager like {@link useHead}; a route's own `metadata` (applied last) still wins for keys it
101
- * sets, so this fills in for routes that declare none. Resolved fresh each render, the head manager
102
- * dedupes by value, so passing a computed object is fine.
103
- */
104
- export function useMetadata(metadata: Metadata): void {
105
- useHead(resolveMetadata(metadata));
106
- }
107
-
108
- /** Declarative form of {@link useMetadata}: `<Metadata title="…" openGraph={…} />`. Renders nothing. */
109
- export function Metadata(props: Metadata): null {
110
- useMetadata(props);
111
- return null;
112
- }
1
+ /**
2
+ * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
3
+ * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
4
+ * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
5
+ * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
6
+ */
7
+ import { useHead, type HeadSpec, type LinkTag, type MetaTag } from './head.js';
8
+ import type { RouteParams } from '../routing/match.js';
9
+
10
+ /** OpenGraph fields, expanded to `og:*` meta tags. */
11
+ export interface OpenGraph {
12
+ readonly title?: string;
13
+ readonly description?: string;
14
+ readonly type?: string;
15
+ readonly url?: string;
16
+ readonly image?: string;
17
+ readonly siteName?: string;
18
+ }
19
+
20
+ /** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
21
+ export interface Metadata {
22
+ /** Document title. */
23
+ readonly title?: string;
24
+ /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
25
+ readonly titleTemplate?: string;
26
+ /** `<meta name="description">`. */
27
+ readonly description?: string;
28
+ /** `<meta name="keywords">`, joined with `, ` if an array. */
29
+ readonly keywords?: string | readonly string[];
30
+ /** `<link rel="canonical">`. */
31
+ readonly canonical?: string;
32
+ /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
33
+ readonly robots?: string;
34
+ /** `<meta name="theme-color">`. */
35
+ readonly themeColor?: string;
36
+ /** OpenGraph (`og:*`) tags. */
37
+ readonly openGraph?: OpenGraph;
38
+ /** Escape hatch: extra raw `<meta>` tags. */
39
+ readonly meta?: readonly MetaTag[];
40
+ /** Escape hatch: extra raw `<link>` tags. */
41
+ readonly link?: readonly LinkTag[];
42
+ }
43
+
44
+ /** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
45
+ export interface GenerateMetadataArgs<T = unknown> {
46
+ readonly params: RouteParams;
47
+ readonly searchParams: URLSearchParams;
48
+ readonly data: T;
49
+ }
50
+
51
+ /** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
52
+ export type GenerateMetadata<T = unknown> = (
53
+ args: GenerateMetadataArgs<T>,
54
+ ) => Metadata | Promise<Metadata>;
55
+
56
+ /** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
57
+ export function resolveMetadata(metadata: Metadata): HeadSpec {
58
+ const meta: MetaTag[] = [];
59
+ if (metadata.description !== undefined) {
60
+ meta.push({ name: 'description', content: metadata.description });
61
+ }
62
+ if (metadata.keywords !== undefined) {
63
+ const content =
64
+ typeof metadata.keywords === 'string'
65
+ ? metadata.keywords
66
+ : metadata.keywords.join(', ');
67
+ meta.push({ name: 'keywords', content });
68
+ }
69
+ if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
70
+ if (metadata.themeColor !== undefined) {
71
+ meta.push({ name: 'theme-color', content: metadata.themeColor });
72
+ }
73
+ const og = metadata.openGraph;
74
+ if (og) {
75
+ const pairs: readonly [string, string | undefined][] = [
76
+ ['og:title', og.title],
77
+ ['og:description', og.description],
78
+ ['og:type', og.type],
79
+ ['og:url', og.url],
80
+ ['og:image', og.image],
81
+ ['og:site_name', og.siteName],
82
+ ];
83
+ for (const [property, content] of pairs) {
84
+ if (content !== undefined) meta.push({ property, content });
85
+ }
86
+ }
87
+ if (metadata.meta) meta.push(...metadata.meta);
88
+
89
+ const link: LinkTag[] = [];
90
+ if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
91
+ if (metadata.link) link.push(...metadata.link);
92
+
93
+ return { title: metadata.title, titleTemplate: metadata.titleTemplate, meta, link };
94
+ }
95
+
96
+ /**
97
+ * Applies a route-style {@link Metadata} object from inside any component for that component's
98
+ * lifetime, reverting on unmount. The runtime counterpart of a route's `metadata` export, for
99
+ * content that isn't itself a route file (a rendered article, a widget, ...). Composes through the
100
+ * head manager like {@link useHead}; a route's own `metadata` (applied last) still wins for keys it
101
+ * sets, so this fills in for routes that declare none. Resolved fresh each render, the head manager
102
+ * dedupes by value, so passing a computed object is fine.
103
+ */
104
+ export function useMetadata(metadata: Metadata): void {
105
+ useHead(resolveMetadata(metadata));
106
+ }
107
+
108
+ /** Declarative form of {@link useMetadata}: `<Metadata title="…" openGraph={…} />`. Renders nothing. */
109
+ export function Metadata(props: Metadata): null {
110
+ useMetadata(props);
111
+ return null;
112
+ }