@govela/app 0.1.2 → 0.3.0

package/client.d.ts

@@ -1,4 +1,7 @@
-// Types of @govela/app/client for editors (docs/APP.md).
+// Types of @govela/app/client (docs/APP.md).
+
+import type { Component, ComponentInstance } from '@govela/runtime';
+import type { MismatchReport } from '@govela/runtime/hydrate';
 
 /** The route table of src/_app/routes.js, which vela-app generates. */
 export interface RouteTable {
@@ -7,12 +10,15 @@ export interface RouteTable {
   match(path: string): { route: { id: string }; params: Record<string, string> } | null;
 }
 
-/** The route prop of route components (R-1). */
-export interface Route {
+/**
+ * The route prop of route components (R-1). P are the parameters of the
+ * path: `Route<Params>` of the route's `$types` (docs/TYPESCRIPT.md TS-8.2).
+ */
+export interface Route<P extends Record<string, string | undefined> = Record<string, string>> {
   id: string;
   url: string;
   path: string;
-  params: Record<string, string>;
+  params: P;
   query: Record<string, string>;
 }
 
@@ -37,19 +43,19 @@ export interface BeforeNavigation extends Navigation {
 
 export interface StartOptions {
   /** The generated app root, src/_app/VelaApp.vela. */
-  VelaApp: Function;
+  VelaApp: Component<any, any, any>;
   /** The generated route table, src/_app/routes.js. Without it links load documents. */
   routes?: RouteTable;
   /** The element that holds the app root, or its id. */
   root?: string | Element;
   /** Receives hydration mismatch reports. */
-  onMismatch?: (report: unknown) => void;
+  onMismatch?: (report: MismatchReport) => void;
   /** The default prefetch of links; data-vela-preload on a link or an ancestor overrides it. */
   preload?: 'hover' | 'viewport' | 'off';
 }
 
 /** Hydrates the server document and installs the router. */
-export function start(options: StartOptions): Promise<{ app: unknown; routes?: RouteTable }>;
+export function start(options: StartOptions): Promise<{ app: ComponentInstance; routes?: RouteTable }>;
 
 export interface GotoOptions {
   /** Replace the current history entry instead of adding one. */
@@ -81,4 +87,23 @@ export function afterNavigate(fn: (navigation: Navigation) => void): () => void;
 export const protocolVersion: 1;
 
 /** The request headers of a navigation (N-2). */
-export const headers: Readonly<{ navigate: string; have: string; build: string }>;
+export const headers: Readonly<{ navigate: string; have: string; build: string; purpose: string }>;
+
+/** The detail of `vela:form`: a failed form action (`app.Fail`). */
+export interface FormFailure {
+  /** The HTTP status of the failure, 400–499. */
+  status: number;
+  /** The value the action failed with: the page's `form` prop. */
+  form: unknown;
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    /** The app root hydrated (start()). */
+    'vela:hydrated': CustomEvent<{ app: ComponentInstance }>;
+    /** A navigation of the router ended. */
+    'vela:navigated': CustomEvent<Navigation>;
+    /** A form action failed; the page's `form` prop changed. */
+    'vela:form': CustomEvent<FormFailure>;
+  }
+}

package/client.js

@@ -12,6 +12,8 @@ export const headers = Object.freeze({
   navigate: 'X-Vela-Navigate',
   have: 'X-Vela-Have',
   build: 'X-Vela-Build',
+  // "prefetch" on a prefetch (G-4): the answer sets no cookies.
+  purpose: 'X-Vela-Purpose',
 });
 
 // A chain of redirects longer than this loads the document (N-5).
@@ -210,11 +212,13 @@ function createRouter({ VelaApp, app, routes, target, route, chain, preload }) {
   // fetchNavigation asks the server for the navigation to url (N-2). It
   // resolves with the JSON body, or { redirected } when something other
   // than the app redirected the request.
-  async function fetchNavigation(url, have, signal) {
+  async function fetchNavigation(url, have, signal, purpose) {
+    const requestHeaders = { [headers.navigate]: `auto;v=${protocolVersion}`, [headers.have]: have, [headers.build]: build };
+    if (purpose) requestHeaders[headers.purpose] = purpose;
     const response = await fetch(url.href, {
       credentials: 'same-origin',
       signal,
-      headers: { [headers.navigate]: `auto;v=${protocolVersion}`, [headers.have]: have, [headers.build]: build },
+      headers: requestHeaders,
     });
     if (response.redirected) return { redirected: response.url };
     return response.json();
@@ -303,7 +307,10 @@ function createRouter({ VelaApp, app, routes, target, route, chain, preload }) {
   // or when it enters the viewport, as data-vela-preload on it or an
   // ancestor says ("hover", "viewport" or "off"; start({ preload }) is the
   // default). The answer serves one navigation within 30 s, for the same
-  // URL and X-Vela-Have.
+  // URL and X-Vela-Have; an answer marked cache: "once" (a user-dependent
+  // one, G-4) never serves more. The request says X-Vela-Purpose: prefetch,
+  // so the server sets no cookies on it. Every action and invalidate()
+  // clear the cache: an answer prefetched before a logout is not shown.
   const prefetched = new Map();
   const prefetchTTL = 30000;
 
@@ -334,7 +341,7 @@ function createRouter({ VelaApp, app, routes, target, route, chain, preload }) {
     if (match.route.render === 'data') {
       for (const level of match.route.chain) components(routes, level.id)?.load().catch(() => {});
     }
-    const body = fetchNavigation(url, have, undefined);
+    const body = fetchNavigation(url, have, undefined, 'prefetch');
     prefetched.set(key, { at: now, body });
     // What the answer needs loads too; a failure only drops the entry.
     body.then((answer) => (answer && answer.v === protocolVersion && (answer.type === 'data' || answer.type === 'fragment') ? prepareModules(answer) : null))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govela/app",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Vela App (docs/APP.md): the client router (hydration, data navigation, route matching) and the vela-app command.",
   "license": "MIT",
   "repository": {
@@ -32,20 +32,20 @@
     "LICENSE"
   ],
   "govela": {
-    "runtimeContract": 4,
+    "runtimeContract": 5,
     "protocol": 1
   },
   "peerDependencies": {
-    "@govela/runtime": ">=0.4.8"
+    "@govela/runtime": ">=0.7.0"
   },
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@govela/app-darwin-arm64": "0.1.2",
-    "@govela/app-darwin-x64": "0.1.2",
-    "@govela/app-linux-arm64": "0.1.2",
-    "@govela/app-linux-x64": "0.1.2",
-    "@govela/app-win32-x64": "0.1.2"
+    "@govela/app-darwin-arm64": "0.3.0",
+    "@govela/app-darwin-x64": "0.3.0",
+    "@govela/app-linux-arm64": "0.3.0",
+    "@govela/app-linux-x64": "0.3.0",
+    "@govela/app-win32-x64": "0.3.0"
   }
 }