@ubean/routes 0.2.1 → 0.3.0

package/dist/invoke-CzODqUg-.d.ts

@@ -0,0 +1,12 @@
+import { ActionResult, ServerAction } from "@ubean/shared";
+//#region src/actions/invoke.d.ts
+declare function unwrapActionResult<T>(result: ActionResult<T>): T;
+declare function unwrapServerFnResult<T>(value: unknown): Promise<T>;
+/**
+ * Call a server function from a loader, `useAsyncData`, or the client.
+ *
+ * Reuses the action ID / `POST /__actions` envelope. Does not invent RPC.
+ */
+declare function invokeServerFn<TInput = unknown, TOutput = unknown>(fn: ServerAction<TInput, TOutput>, input?: TInput): Promise<TOutput>;
+//#endregion
+export { unwrapActionResult as n, unwrapServerFnResult as r, invokeServerFn as t };

package/dist/runtime.d.ts

@@ -0,0 +1,149 @@
+import { n as unwrapActionResult, r as unwrapServerFnResult, t as invokeServerFn } from "./invoke-CzODqUg-.js";
+import { ActionResult, ServerAction } from "@ubean/shared";
+import { Ref } from "vue";
+//#region src/runtime.d.ts
+/**
+ * Create a client-side stub for a server action.
+ *
+ * The Vite plugin replaces `defineAction(...)` calls on the client with
+ * `createActionStub('<id>')` calls. The stub is a `ServerAction`-compatible
+ * object whose `handler` performs an RPC POST to `/__actions` with the
+ * action's stable ID.
+ *
+ * Application code should not call this directly — it is injected by the
+ * Vite plugin. Use `defineAction()` in source code; the plugin handles the
+ * client/server split automatically.
+ *
+ * @param actionId The stable action ID (e.g. `act_xxxxxxxxxxxx`)
+ */
+declare function createActionStub<TInput = unknown, TOutput = unknown>(actionId: string): ServerAction<TInput, TOutput>;
+/**
+ * Low-level RPC: invoke a registered server action by ID.
+ *
+ * Used by the Vite plugin's client-side RPC stubs (generated from
+ * `'use server'` modules). Application code should use `useAction()`
+ * instead — `callAction` is the building block.
+ *
+ * @param actionId The stable action ID (e.g. `act_xxxxxxxxxxxx`)
+ * @param args     Arguments to pass to the action handler (serialized as JSON)
+ * @returns The `ActionResult` returned by the server
+ */
+declare function callAction<T = unknown>(actionId: string, args?: unknown[]): Promise<ActionResult<T>>;
+interface UseActionReturn<TInput = unknown, TOutput = unknown> {
+  /** Reactive flag: `true` while the action is in flight. */
+  pending: Ref<boolean>;
+  /** The latest `ActionResult.data` (success), or `null` on error. */
+  data: Ref<TOutput | null>;
+  /** The latest `ActionResult.error`, or `null` on success. */
+  error: Ref<{
+    message: string;
+    code?: string;
+  } | null>;
+  /** The latest `ActionResult.errors` (field-level), or `null`. */
+  errors: Ref<Record<string, string> | null>;
+  /** The latest HTTP status code. */
+  status: Ref<number>;
+  /** The full `ActionResult` from the last invocation. */
+  result: Ref<ActionResult<TOutput> | null>;
+  /**
+   * Invoke the action. Pass either:
+   *  - the action's typed input (when no schema), or
+   *  - the validated data shape (when schema is provided)
+   *
+   * On the client, the action is an RPC stub created by the Vite plugin;
+   * arguments are forwarded positionally to the server handler.
+   */
+  submit: (...args: TInput extends unknown[] ? TInput : [TInput]) => Promise<ActionResult<TOutput>>;
+  /** Reset all reactive state to initial values. */
+  reset: () => void;
+}
+/**
+ * Composable for invoking a server action reactively.
+ *
+ * Two usage modes:
+ *
+ * ## 1. Action from `defineAction()` (typed input)
+ *
+ * ```ts
+ * import { useAction } from 'ubean/runtime/vue';
+ * import { login } from '~/actions/auth';
+ *
+ * const { submit, pending, data, error } = useAction(login);
+ * await submit({ email, password });
+ * ```
+ *
+ * ## 2. Action ID string
+ *
+ * ```ts
+ * const { submit, pending, data, error } = useAction('act_xxxxxxxxxxxx');
+ * await submit(email, password);
+ * ```
+ */
+declare function useAction<TInput = unknown, TOutput = unknown>(actionOrId: ServerAction<TInput, TOutput> | string): UseActionReturn<TInput, TOutput>;
+interface UseFormActionReturn {
+  /** The form `action` attribute value (e.g. `?/login`). */
+  action: string;
+  /** Reactive flag: `true` while the form is submitting via SPA. */
+  pending: Ref<boolean>;
+  /** The latest `ActionResult.data` from a SPA submit, or `null`. */
+  data: Ref<unknown | null>;
+  /** The latest `ActionResult.error`, or `null`. */
+  error: Ref<{
+    message: string;
+    code?: string;
+  } | null>;
+  /** The latest `ActionResult.errors` (field-level), or `null`. */
+  errors: Ref<Record<string, string> | null>;
+  /**
+   * Submit a `FormData` (or HTMLFormElement) via SPA-style navigation.
+   *
+   * Posts to the current page URL with `?/<actionName>` and the form's
+   * fields as the body. The server's `handlePageRequest` dispatches the
+   * named form action and returns a `PageObject` with `errors`/`props`.
+   *
+   * For progressive enhancement, set this as the form's `@submit` handler:
+   *
+   * ```vue
+   * <form method="POST" :action="formAction" @submit.prevent="formAction.onSubmit">
+   *   ...
+   * </form>
+   * ```
+   */
+  onSubmit: (event: Event | FormData) => Promise<ActionResult>;
+  /** Reset all reactive state. */
+  reset: () => void;
+}
+/**
+ * Composable for SvelteKit-style page-level form actions.
+ *
+ * Generates the form `action` attribute for progressive enhancement and
+ * provides a SPA-style submit handler. The form action is invoked via
+ * `POST /currentPage?/<actionName>` — the server dispatches it to the
+ * page module's `actions.<name>` handler.
+ *
+ * ```vue
+ * <script setup>
+ * import { useFormAction } from 'ubean/runtime/vue';
+ *
+ * const login = useFormAction('login');
+ * </script>
+ *
+ * <template>
+ *   <form method="POST" :action="login.action" @submit.prevent="login.onSubmit">
+ *     <input name="email" type="email" />
+ *     <input name="password" type="password" />
+ *     <button :disabled="login.pending.value">
+ *       {{ login.pending.value ? 'Logging in…' : 'Login' }}
+ *     </button>
+ *   </form>
+ *   <p v-if="login.error.value" class="error">{{ login.error.value.message }}</p>
+ * </template>
+ * ```
+ *
+ * Without JavaScript, the browser submits the form natively to
+ * `?/login` — the server renders the result HTML, providing full
+ * progressive enhancement.
+ */
+declare function useFormAction(actionName?: string): UseFormActionReturn;
+//#endregion
+export { UseActionReturn, UseFormActionReturn, callAction, createActionStub, invokeServerFn, unwrapActionResult, unwrapServerFnResult, useAction, useFormAction };

package/dist/runtime.js

@@ -0,0 +1,278 @@
+import { a as ACTION_RESPONSE_HEADER, c as unwrapServerFnResult, i as ACTIONS_ENDPOINT, o as invokeServerFn, s as unwrapActionResult, t as buildFormActionUrl } from "./form-action-CZA0dSMO.js";
+import { ACTION_BRAND } from "@ubean/shared";
+import { ref } from "vue";
+//#region src/runtime.ts
+/**
+* Client-side runtime for server actions (P9-02).
+*
+* This module is browser-only — it MUST NOT import any Node.js APIs or
+* server-only types. The Vite plugin replaces `defineAction()` calls on
+* the client with `createActionStub()` calls (imported from here), and
+* `useAction()` / `useFormAction()` are auto-imported from
+* `ubean/runtime/vue` (which re-exports these).
+*
+* The runtime communicates with the server via the `/__actions` POST
+* endpoint (for RPC) or via page POST (for form actions with
+* progressive enhancement).
+*/
+/**
+* Create a client-side stub for a server action.
+*
+* The Vite plugin replaces `defineAction(...)` calls on the client with
+* `createActionStub('<id>')` calls. The stub is a `ServerAction`-compatible
+* object whose `handler` performs an RPC POST to `/__actions` with the
+* action's stable ID.
+*
+* Application code should not call this directly — it is injected by the
+* Vite plugin. Use `defineAction()` in source code; the plugin handles the
+* client/server split automatically.
+*
+* @param actionId The stable action ID (e.g. `act_xxxxxxxxxxxx`)
+*/
+function createActionStub(actionId) {
+	const rpc = ((...args) => callAction(actionId, args));
+	const stub = {
+		id: actionId,
+		handler: rpc,
+		name: "stub",
+		filePath: "client"
+	};
+	Object.defineProperty(stub, ACTION_BRAND, {
+		value: true,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	return stub;
+}
+/**
+* Low-level RPC: invoke a registered server action by ID.
+*
+* Used by the Vite plugin's client-side RPC stubs (generated from
+* `'use server'` modules). Application code should use `useAction()`
+* instead — `callAction` is the building block.
+*
+* @param actionId The stable action ID (e.g. `act_xxxxxxxxxxxx`)
+* @param args     Arguments to pass to the action handler (serialized as JSON)
+* @returns The `ActionResult` returned by the server
+*/
+async function callAction(actionId, args = []) {
+	const res = await fetch(ACTIONS_ENDPOINT, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			[ACTION_RESPONSE_HEADER]: "true"
+		},
+		body: JSON.stringify({
+			id: actionId,
+			args
+		}),
+		redirect: "manual"
+	});
+	if (!(res.headers.get("Content-Type") || "").includes("application/json")) return {
+		error: { message: `Unexpected response (status ${res.status})` },
+		status: res.status
+	};
+	try {
+		return await res.json();
+	} catch {
+		return {
+			error: { message: "Failed to parse action response" },
+			status: res.status
+		};
+	}
+}
+/**
+* Composable for invoking a server action reactively.
+*
+* Two usage modes:
+*
+* ## 1. Action from `defineAction()` (typed input)
+*
+* ```ts
+* import { useAction } from 'ubean/runtime/vue';
+* import { login } from '~/actions/auth';
+*
+* const { submit, pending, data, error } = useAction(login);
+* await submit({ email, password });
+* ```
+*
+* ## 2. Action ID string
+*
+* ```ts
+* const { submit, pending, data, error } = useAction('act_xxxxxxxxxxxx');
+* await submit(email, password);
+* ```
+*/
+function useAction(actionOrId) {
+	const pending = ref(false);
+	const data = ref(null);
+	const error = ref(null);
+	const errors = ref(null);
+	const status = ref(0);
+	const result = ref(null);
+	const actionId = typeof actionOrId === "string" ? actionOrId : actionOrId.id;
+	async function submit(...args) {
+		pending.value = true;
+		error.value = null;
+		errors.value = null;
+		try {
+			const res = await callAction(actionId, args);
+			result.value = res;
+			status.value = res.status;
+			if (res.error) {
+				error.value = res.error;
+				data.value = null;
+			} else if (res.errors) {
+				errors.value = res.errors;
+				data.value = null;
+			} else data.value = res.data ?? null;
+			return res;
+		} catch (err) {
+			const fallback = {
+				error: { message: err instanceof Error ? err.message : String(err) },
+				status: 0
+			};
+			result.value = fallback;
+			status.value = 0;
+			error.value = fallback.error;
+			return fallback;
+		} finally {
+			pending.value = false;
+		}
+	}
+	function reset() {
+		pending.value = false;
+		data.value = null;
+		error.value = null;
+		errors.value = null;
+		status.value = 0;
+		result.value = null;
+	}
+	return {
+		pending,
+		data,
+		error,
+		errors,
+		status,
+		result,
+		submit,
+		reset
+	};
+}
+/**
+* Composable for SvelteKit-style page-level form actions.
+*
+* Generates the form `action` attribute for progressive enhancement and
+* provides a SPA-style submit handler. The form action is invoked via
+* `POST /currentPage?/<actionName>` — the server dispatches it to the
+* page module's `actions.<name>` handler.
+*
+* ```vue
+* <script setup>
+* import { useFormAction } from 'ubean/runtime/vue';
+*
+* const login = useFormAction('login');
+* <\/script>
+*
+* <template>
+*   <form method="POST" :action="login.action" @submit.prevent="login.onSubmit">
+*     <input name="email" type="email" />
+*     <input name="password" type="password" />
+*     <button :disabled="login.pending.value">
+*       {{ login.pending.value ? 'Logging in…' : 'Login' }}
+*     </button>
+*   </form>
+*   <p v-if="login.error.value" class="error">{{ login.error.value.message }}</p>
+* </template>
+* ```
+*
+* Without JavaScript, the browser submits the form natively to
+* `?/login` — the server renders the result HTML, providing full
+* progressive enhancement.
+*/
+function useFormAction(actionName = "default") {
+	const action = buildFormActionUrl(actionName);
+	const pending = ref(false);
+	const data = ref(null);
+	const error = ref(null);
+	const errors = ref(null);
+	async function onSubmit(event) {
+		let formData;
+		if (event instanceof FormData) formData = event;
+		else {
+			const form = event.target;
+			formData = new FormData(form);
+		}
+		pending.value = true;
+		error.value = null;
+		errors.value = null;
+		try {
+			const url = window.location.pathname + action;
+			const res = await fetch(url, {
+				method: "POST",
+				body: formData,
+				headers: { "x-ubeanpages": "true" },
+				redirect: "manual"
+			});
+			const redirectUrl = res.headers.get("X-Ubean-Redirect");
+			if (redirectUrl) {
+				window.location.href = redirectUrl;
+				return {
+					data: { redirect: redirectUrl },
+					status: res.status
+				};
+			}
+			if ((res.headers.get("Content-Type") || "").includes("application/json")) {
+				const json = await res.json();
+				if (json.redirect && typeof json.redirect === "string") {
+					window.location.href = json.redirect;
+					return {
+						data: json,
+						status: res.status
+					};
+				}
+				const pageObj = json;
+				if (pageObj.errors) {
+					errors.value = pageObj.errors;
+					return {
+						errors: pageObj.errors,
+						status: res.status
+					};
+				}
+				data.value = pageObj.props ?? null;
+				return {
+					data: pageObj.props,
+					status: res.status
+				};
+			}
+			return { status: res.status };
+		} catch (err) {
+			const fallback = {
+				error: { message: err instanceof Error ? err.message : String(err) },
+				status: 0
+			};
+			error.value = fallback.error;
+			return fallback;
+		} finally {
+			pending.value = false;
+		}
+	}
+	function reset() {
+		pending.value = false;
+		data.value = null;
+		error.value = null;
+		errors.value = null;
+	}
+	return {
+		action,
+		pending,
+		data,
+		error,
+		errors,
+		onSubmit,
+		reset
+	};
+}
+//#endregion
+export { callAction, createActionStub, invokeServerFn, unwrapActionResult, unwrapServerFnResult, useAction, useFormAction };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ubean/routes",
-  "version": "0.2.1",
-  "description": "Server routes runtime for ubean (defineHandler, defineMiddleware, registerRoutes, rou3 server router, route rules, ISR, internal-fetch, OpenAPI)",
+  "version": "0.3.0",
+  "description": "Server routes runtime for ubean (defineHandler, defineMiddleware, registerRoutes, Server Actions, rou3 server router, route rules, ISR, internal-fetch, OpenAPI)",
   "files": [
     "dist"
   ],
@@ -13,6 +13,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
     }
   },
   "dependencies": {
@@ -23,21 +27,21 @@
     "hono": "4.13.3",
     "hono-openapi": "^1.3.1",
     "rou3": "^0.9.2",
-    "@ubean/actions": "0.2.1",
-    "@ubean/shared": "0.2.1"
+    "@ubean/shared": "0.3.0",
+    "@ubean/i18n": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "typescript": "7.0.2",
     "vite-plus": "0.2.9",
-    "@ubean/i18n": "0.2.1",
-    "@ubean/pages": "0.2.1",
-    "@ubean/scan": "0.2.1"
+    "vue": "^3.5.41",
+    "@ubean/pages": "0.3.0",
+    "@ubean/scan": "0.3.0"
   },
   "peerDependencies": {
-    "@ubean/i18n": "0.2.1",
-    "@ubean/scan": "0.2.1",
-    "@ubean/pages": "0.2.1"
+    "vue": "^3.0.0",
+    "@ubean/pages": "0.3.0",
+    "@ubean/scan": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@ubean/scan": {
@@ -46,7 +50,7 @@
     "@ubean/pages": {
       "optional": true
     },
-    "@ubean/i18n": {
+    "vue": {
       "optional": true
     }
   },