@govela/app 0.1.1 → 0.2.0

package/README.md

@@ -3,7 +3,22 @@
 The client router of Vela App, the application layer above the Vela compiler
 with a Go server. The contract is [docs/APP.md](../../docs/APP.md).
 
-This package is not published yet. `@govela/app/match` has the built-in
+It also installs the `vela-app` command, which generates the app sources,
+runs the development loop and makes production builds:
+
+```sh
+npm install @govela/app @govela/runtime
+npx vela-app dev
+npx vela-app build
+```
+
+`bin/vela-app.js` runs the binary of the optional dependency
+`@govela/app-<os>-<cpu>` for this platform (linux x64/arm64, macOS
+x64/arm64, Windows x64), or `$VELA_APP_BINARY`. Do not install with
+`--omit=optional`. The guide is
+[docs/VELA_APP.md](../../docs/VELA_APP.md).
+
+`@govela/app/match` has the built-in
 matchers (`int`, `uuid`, `slug`) and `matchPath`, which the route table that
 `vela-app gen` writes (`src/_app/routes.js`) uses; the Go package
 `github.com/elauven/vela/app` matches with the same rules.

package/bin/vela-app.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// The `vela-app` command of @govela/app: runs the vela-app binary of this
+// platform (the optional dependency @govela/app-<os>-<cpu>), or
+// $VELA_APP_BINARY, with the arguments, standard streams and exit code of
+// the command.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const platforms = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'win32-x64'];
+
+function binaryPath() {
+  if (process.env.VELA_APP_BINARY) {
+    return process.env.VELA_APP_BINARY;
+  }
+  const platform = `${process.platform}-${process.arch}`;
+  const name = `${manifest.name}-${platform}`;
+  if (!platforms.includes(platform)) {
+    throw new Error(`vela-app: no prebuilt binary for ${platform}; supported: ${platforms.join(', ')}. Install it with \`go install github.com/elauven/vela/app/cmd/vela-app@v${manifest.version}\` and set VELA_APP_BINARY to it.`);
+  }
+  const file = `bin/vela-app${process.platform === 'win32' ? '.exe' : ''}`;
+  try {
+    return require.resolve(`${name}/${file}`);
+  } catch {
+    throw new Error(`vela-app: the package ${name} is not installed. It is an optional dependency of ${manifest.name}; reinstall without --no-optional / --omit=optional, or set VELA_APP_BINARY to a vela-app binary.`);
+  }
+}
+
+let binary;
+try {
+  binary = binaryPath();
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit', windowsHide: true });
+if (result.error) {
+  console.error(`vela-app: cannot run ${binary}: ${result.error.message}`);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);

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. */
@@ -82,3 +88,22 @@ export const protocolVersion: 1;
 
 /** The request headers of a navigation (N-2). */
 export const headers: Readonly<{ navigate: string; have: string; build: 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@govela/app",
-  "version": "0.1.1",
-  "description": "Client router of Vela App (docs/APP.md): hydration, data navigation and route matching.",
+  "version": "0.2.0",
+  "description": "Vela App (docs/APP.md): the client router (hydration, data navigation, route matching) and the vela-app command.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,6 +9,9 @@
     "directory": "packages/app"
   },
   "type": "module",
+  "bin": {
+    "vela-app": "bin/vela-app.js"
+  },
   "sideEffects": false,
   "exports": {
     "./client": {
@@ -21,6 +24,7 @@
     }
   },
   "files": [
+    "bin/vela-app.js",
     "client.js",
     "client.d.ts",
     "match.js",
@@ -32,6 +36,16 @@
     "protocol": 1
   },
   "peerDependencies": {
-    "@govela/runtime": ">=0.4.8"
+    "@govela/runtime": ">=0.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@govela/app-darwin-arm64": "0.2.0",
+    "@govela/app-darwin-x64": "0.2.0",
+    "@govela/app-linux-arm64": "0.2.0",
+    "@govela/app-linux-x64": "0.2.0",
+    "@govela/app-win32-x64": "0.2.0"
   }
 }