@chidchanun/bcp 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.11 - Form actions and server mutations
+
+### Route mutations
+
+- Added route-level `actions.ts` / `actions.tsx` files next to `page.tsx` for server-only create, update and delete operations without requiring an API route for every page-owned mutation.
+- Actions are named exports and receive browser `FormData` plus route `params`, target `searchParams`, merged `guardData` and the semantic mutation `method`.
+- Supported action methods are `POST`, `PUT`, `PATCH` and `DELETE`; GET remains a loader/API read concern.
+- Added `PageAction`, `PageActionContext` and `PageActionMethod` types through the server-only `bcp/server` entrypoint.
+- Action modules may use normal server-only application/database imports plus request/session APIs such as `cookies()`, `getSession()`, `requestUrl()` and `requestMethod()`.
+- `requestMethod()` reflects the semantic action method even though progressive HTML forms use POST as the browser transport.
+- Actions may return JSON-safe data, `undefined` (normalized to `null`) or a Web `Response` such as `redirect()`.
+- Action data uses JSON-safe validation and rejects unsupported/circular values before browser transport.
+
+### Form client API and progressive enhancement
+
+- Added public `<Form action="name">` with `post`, `put`, `patch` and `delete` semantic methods.
+- Added `useFormStatus()` for pending/action/method/error state, `useActionData<T>()` for the latest serializable mutation result and `useActionError()` for transport/runtime failures.
+- Enhanced submissions send the original `FormData` through the internal `/_bcp/action` transport without a document reload.
+- Named actions use strings instead of importing server functions into the client graph, preserving server-only boundaries until the later compiler-backed Server Actions milestone.
+- Same-origin redirects from enhanced actions continue through BCP client navigation while response cookies remain intact.
+- Forms without JavaScript use normal HTML POST and POST/Redirect/GET `303` behavior for data-returning actions, preventing duplicate resubmission on browser refresh.
+- Added optional `<Form refresh>` support to rerun the current BCP navigation/loader after a successful data-returning mutation.
+
+### Authorization, caching and production
+
+- Route guards execute before matching actions and can stop a mutation with a redirect/Response; merged authorization data is passed to the action through `context.guardData`.
+- Project middleware and framework security remain outside the action gateway, so mutation requests keep the existing request interception and body-limit policy.
+- Cookies created by actions or guards are preserved for data and redirect responses in both enhanced and progressive paths.
+- `revalidatePath()` and `revalidateTag()` can be called directly inside actions using the shared process-local BCP cache runtime.
+- Pages with sibling form actions are excluded from the automatic production response-cache manifest to avoid stale POST/Redirect/GET pages after mutations.
+- Standalone builds generate `server/actions.mjs` only when action routes exist and execute bundled action modules entirely on the server.
+- Added development and standalone action gateways without exposing action/database modules to browser bundles.
+
+### Reliability and documentation
+
+- Added `/action-demo/[id]` plus guarded mutation fixtures for FormData, semantic methods, cookies, redirects, cache revalidation hooks, progressive enhancement and guard-data handoff.
+- Added unit coverage for action naming, method normalization, route context, Response returns and serialization rejection.
+- Added development integration and standalone E2E coverage for enhanced mutations, no-JavaScript PRG behavior, response cookies and guards-before-actions ordering.
+- Added publish-artifact smoke checks for the public Form API, server mutation runtime, dev gateway, standalone action gateway and production action bundle.
+- Added dedicated Form Actions and Server Mutations documentation.
+
 ## 0.1.10 - Framework updater and protected route guards
 
 ### Framework updater
@@ -20,7 +61,7 @@ All notable framework changes are tracked here before release.
 ### Protected routes and auth guards
 
 - Added scoped `guard.ts` / `guard.tsx` files that protect pages in their route directory and descendant page directories.
-- Guards execute from app root toward the matched page and receive `params`, target `searchParams` and merged ancestor `parentData`.
+- Guards execute from app root toward the matched page and receive `params`, target `searchParams` and merged ancestor `guardData`.
 - A guard may return JSON-safe authorization data or a Web `Response`; redirects stop the pipeline before loader/page execution.
 - Guards run inside the normal BCP request context, so sessions, cookies, headers, request URLs, request IDs and other `bcp/server` helpers are available directly.
 - Loader context now receives merged `guardData`, avoiding repeated session/role lookups after a guard has already validated the request.
@@ -65,7 +106,7 @@ All notable framework changes are tracked here before release.
 - Navigation loaders receive a request context for the target page URL rather than the internal navigation transport URL, preserving target query parameters, cookies, sessions and request helpers.
 - Loader redirects are converted to a navigation redirect payload while preserving all response cookies; same-origin redirects continue through the SPA router and cross-origin redirects use normal browser navigation.
 - Non-navigation Web `Response` values continue to fall back to a document request so their original HTTP semantics remain authoritative.
-- Client navigation explicitly sends same-origin credentials, aborts superseded requests and uses a monotonically increasing navigation sequence so stale responses cannot update router state after a newer navigation has started.
+- Client navigation explicitly sends same-origin credentials, aborts superseded requests and uses a monotonically increasing navigation sequence so stale responses cannot update the active route after a newer navigation has started.
 - Navigation redirect chains are capped at 10 redirects to prevent loops.
 - `useNavigation()` becomes active before the server request starts and route loading markup can be displayed while the target client runtime/assets finish after the payload arrives.
 - Standalone loader navigation is placed inside the existing middleware/security chain rather than bypassing application middleware or framework security gateways.

package/README.md

@@ -2,7 +2,7 @@
 
 BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
 
-> Current release target: `0.1.10`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current release target: `0.1.11`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -39,6 +39,7 @@ app/
 │  └─ users/
 │     └─ [id]/
 │        ├─ loader.ts
+│        ├─ actions.ts
 │        └─ page.tsx
 └─ api/
    └─ hello/
@@ -77,7 +78,7 @@ Server-only modules can declare:
 import "bcp/server-only";
 ```
 
-Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a hydrated page/client graph. Use an API route or a server-only route primitive such as `loader.ts` or `guard.ts`.
+Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a hydrated page/client graph. Use an API route or a server-only route primitive such as `loader.ts`, `guard.ts` or `actions.ts`.
 
 See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
 
@@ -116,7 +117,7 @@ bcp update --dry-run
 Or select a published version/dist-tag explicitly:
 
 ```bash
-bcp update 0.1.10
+bcp update 0.1.11
 bcp update next
 ```
 
@@ -158,7 +159,7 @@ Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD
 
 ## Server request APIs
 
-BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. These helpers are server-only and are available from API handlers, server data loaders and route guards.
+BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. These helpers are server-only and are available from API handlers, server data loaders, route guards and form actions.
 
 ```ts
 import {
@@ -309,7 +310,7 @@ See [Server Data Loaders](docs/server-data-loaders.md) for serialization rules,
 
 ## Protected routes and auth guards
 
-The `0.1.10` release target adds scoped `guard.ts` / `guard.tsx` files for page authorization. A guard protects the pages in its directory and descendant route directories, runs before the page loader, and can use the same request/session APIs as a loader.
+BCP 0.1.10 adds scoped `guard.ts` / `guard.tsx` files for page authorization. A guard protects the pages in its directory and descendant route directories, runs before the page loader, and can use the same request/session APIs as a loader.
 
 ```text
 app/dashboard/
@@ -395,10 +396,129 @@ export default function DashboardPage() {
 }
 ```
 
-Nested guards execute from root to child and receive ancestor output as `parentData`. Guard redirects and response cookies work for both direct document requests and SPA navigation. Guarded pages are excluded from the automatic production response cache, and standalone production strips user-supplied internal guard transport headers before evaluating authorization.
+Nested guards execute from root to child and receive merged ancestor output as `guardData`. Guard redirects and response cookies work for both direct document requests and SPA navigation. Guarded pages are excluded from the automatic production response cache, and standalone production strips user-supplied internal guard transport headers before evaluating authorization.
 
 See [Protected Route Guards](docs/route-guards.md) for nested role policies, serialization rules, middleware ordering, cookie behavior and production hardening.
 
+## Form actions and server mutations
+
+BCP 0.1.11 adds route-owned server mutations with `actions.ts` / `actions.tsx`. Actions stay on the server and let page forms perform create, update and delete operations without creating a dedicated API route for every mutation.
+
+```text
+app/users/[id]/
+├─ guard.ts
+├─ loader.ts
+├─ actions.ts
+└─ page.tsx
+```
+
+```ts
+// app/users/[id]/actions.ts
+import "bcp/server-only";
+
+import {
+    redirect,
+    type PageActionContext,
+} from "bcp/server";
+
+import {
+    revalidatePath,
+} from "bcp/cache";
+
+export async function saveUser(
+    formData: FormData,
+    context: PageActionContext
+) {
+    const name =
+        String(
+            formData.get("name") ?? ""
+        ).trim();
+
+    // await db.execute(...)
+
+    revalidatePath("/users");
+
+    if (!name) {
+        return {
+            ok: false,
+            message: "Name is required",
+        };
+    }
+
+    if (
+        context.searchParams.get("done") === "1"
+    ) {
+        return redirect(
+            "/users",
+            303
+        );
+    }
+
+    return {
+        ok: true,
+        id: context.params.id,
+        name,
+        method: context.method,
+    };
+}
+```
+
+Client forms reference the named server action without importing it into the browser graph:
+
+```tsx
+"use client";
+
+import {
+    Form,
+    useActionData,
+    useActionError,
+    useFormStatus,
+} from "bcp";
+
+function SubmitButton() {
+    const status =
+        useFormStatus();
+
+    return (
+        <button
+            type="submit"
+            disabled={status.pending}
+        >
+            {status.pending
+                ? "Saving..."
+                : "Save"}
+        </button>
+    );
+}
+
+export default function UserForm() {
+    const result =
+        useActionData<{
+            ok: boolean;
+            message?: string;
+        }>();
+    const error =
+        useActionError();
+
+    return (
+        <Form
+            action="saveUser"
+            method="patch"
+            refresh
+        >
+            <input name="name" />
+            <SubmitButton />
+            {result?.message}
+            {error?.message}
+        </Form>
+    );
+}
+```
+
+Supported semantic methods are POST, PUT, PATCH and DELETE. Guards execute before actions and pass merged authorization state through `context.guardData`. Actions can use cookies, JWT sessions, `requestMethod()`, redirects and cache revalidation. Enhanced forms submit through the BCP SPA transport; forms without JavaScript fall back to standard HTML POST with POST/Redirect/GET semantics. Action-backed pages are excluded from automatic production response caching.
+
+See [Form Actions and Server Mutations](docs/form-actions.md) for action return values, pending/error state, progressive enhancement, guards, redirects, cookies, cache invalidation and standalone behavior.
+
 ## JWT cookie sessions
 
 BCP 0.1.8 adds HS256 JWT cookie sessions directly to `bcp/server`. Configure a server-only secret of at least 32 bytes:
@@ -538,7 +658,7 @@ import {
 } from "bcp/cache";
 ```
 
-The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances. Loader-backed and route-guarded pages are excluded from the automatic production response-cache manifest because their output may depend on request/session identity. Cache server data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
+The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances. Loader-backed, route-guarded and action-backed pages are excluded from the automatic production response-cache manifest when their output or mutation flow may depend on request/session state. Cache server data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
 
 ## Middleware
 
@@ -563,7 +683,7 @@ export function middleware(
 }
 ```
 
-Use middleware for request-wide interception and `guard.ts` for page-subtree authorization that needs to feed identity/role data into loaders and pages. In standalone production, project middleware runs before route guards.
+Use middleware for request-wide interception and `guard.ts` for page-subtree authorization that needs to feed identity/role data into loaders, actions and pages. In standalone production, project middleware runs before route guards and form actions.
 
 ## Configuration
 
@@ -617,11 +737,12 @@ The standalone output is generated under:
    ├─ server.mjs
    ├─ middleware.mjs
    ├─ guards.mjs
+   ├─ actions.mjs
    ├─ cache-manifest.json
    └─ config.json
 ```
 
-`guards.mjs` is generated only when the application contains protected route guards.
+`guards.mjs` is generated only when the application contains protected route guards. `actions.mjs` is generated only when the application contains route form actions.
 
 ## Package preparation
 
@@ -655,6 +776,7 @@ No real npm publish command is run automatically by the repository.
 - [Server Request APIs](docs/server-request-apis.md)
 - [Server Data Loaders](docs/server-data-loaders.md)
 - [Protected Route Guards](docs/route-guards.md)
+- [Form Actions and Server Mutations](docs/form-actions.md)
 - [JWT Cookie Sessions](docs/session-auth.md)
 - [Updating BCP Framework](docs/updating.md)
 - [Routing](docs/routing.md)

package/docs/form-actions.md

@@ -0,0 +1,314 @@
+# Form Actions and Server Mutations
+
+BCP form actions provide a route-scoped server mutation primitive for application forms without requiring an API route for every create, update or delete operation.
+
+This feature is intentionally separate from future BCP Server Actions. In this release, client pages do **not** import a server function directly. A page submits a named action such as `"saveUser"`, and BCP resolves that name from the sibling `actions.ts` / `actions.tsx` file on the server.
+
+## Route convention
+
+```text
+app/users/[id]/
+├─ guard.ts        # optional
+├─ loader.ts       # optional read path
+├─ actions.ts      # server-only mutation path
+└─ page.tsx
+```
+
+Only one of `actions.ts` or `actions.tsx` may exist next to a page.
+
+## Defining an action
+
+```ts
+// app/users/[id]/actions.ts
+import "bcp/server-only";
+
+import {
+    cookies,
+    redirect,
+    type PageActionContext,
+} from "bcp/server";
+
+import {
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+
+export async function saveUser(
+    formData: FormData,
+    context: PageActionContext
+) {
+    const name =
+        String(
+            formData.get("name") ?? ""
+        ).trim();
+
+    // Perform the database mutation here.
+
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "last-user",
+        context.params.id,
+        {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+        }
+    );
+
+    revalidatePath("/users");
+    revalidateTag("users");
+
+    return {
+        ok: true,
+        id: context.params.id,
+        name,
+    };
+}
+
+export async function removeUser(
+    _formData: FormData,
+    context: PageActionContext
+) {
+    // Delete from the database.
+
+    revalidatePath("/users");
+
+    return redirect(
+        "/users",
+        303
+    );
+}
+```
+
+An action receives:
+
+- `formData` — the submitted browser `FormData`.
+- `context.params` — matched dynamic route parameters.
+- `context.searchParams` — a fresh `URLSearchParams` for the target page URL.
+- `context.guardData` — merged data from route guards that ran before the action.
+- `context.method` — the semantic mutation method: `POST`, `PUT`, `PATCH`, or `DELETE`.
+
+The normal `bcp/server` request context is active while the action runs, so `cookies()`, `headers()`, `requestUrl()`, `requestMethod()`, `requestId()`, `getSession()` and other server helpers work directly. `requestMethod()` reflects the semantic action method rather than the internal POST transport.
+
+## Rendering a form
+
+```tsx
+"use client";
+
+import {
+    Form,
+    useActionData,
+    useActionError,
+    useFormStatus,
+} from "bcp";
+
+interface SaveResult {
+    ok: boolean;
+    id: string;
+    name: string;
+}
+
+export default function UserEditor() {
+    return (
+        <Form
+            action="saveUser"
+            method="patch"
+        >
+            <input
+                name="name"
+                required
+            />
+
+            <SubmitButton />
+            <Result />
+        </Form>
+    );
+}
+
+function SubmitButton() {
+    const status =
+        useFormStatus();
+
+    return (
+        <button
+            type="submit"
+            disabled={status.pending}
+        >
+            {status.pending
+                ? "Saving..."
+                : "Save"}
+        </button>
+    );
+}
+
+function Result() {
+    const data =
+        useActionData<SaveResult>();
+    const error =
+        useActionError();
+
+    if (error) {
+        return (
+            <p role="alert">
+                {error.message}
+            </p>
+        );
+    }
+
+    if (!data) {
+        return null;
+    }
+
+    return (
+        <p>
+            Saved {data.name}
+        </p>
+    );
+}
+```
+
+## Supported mutation methods
+
+`<Form>` supports:
+
+```tsx
+<Form action="createUser" method="post" />
+<Form action="replaceUser" method="put" />
+<Form action="updateUser" method="patch" />
+<Form action="deleteUser" method="delete" />
+```
+
+Browsers only support GET and POST as native HTML form methods. BCP therefore uses POST as the wire transport for progressive enhancement and preserves the intended method separately. The action context and `requestMethod()` still report `PUT`, `PATCH`, or `DELETE` as requested.
+
+GET is deliberately not an action method. Reads belong in page loaders or API GET handlers.
+
+## Action return values
+
+A mutation may return either:
+
+1. JSON-safe action data.
+2. `undefined`, which BCP normalizes to `null`.
+3. A Web `Response`, commonly `redirect()`.
+
+Serializable action data follows the same safety model as loader data: primitives, arrays and plain objects are allowed. Functions, symbols, BigInt, non-finite numbers, Date/Map/Set/class instances and circular references are rejected before transport.
+
+For validation-style UI in this release, return a serializable object such as:
+
+```ts
+return {
+    ok: false,
+    fieldErrors: {
+        email: "Email is required",
+    },
+};
+```
+
+Typed validation helpers and CSRF-specific APIs are planned as a separate security/validation milestone.
+
+## Pending, data, and transport errors
+
+Inside a `<Form>` subtree:
+
+- `useFormStatus()` exposes `pending`, `action`, `method`, and the current transport/server error.
+- `useActionData<T>()` exposes the most recent serializable action result.
+- `useActionError()` exposes the most recent thrown transport/runtime error.
+
+Submitting the form again clears the previous action data before the new request begins.
+
+## Redirects
+
+Actions can return a normal BCP redirect:
+
+```ts
+return redirect(
+    "/users",
+    303
+);
+```
+
+With JavaScript enabled, BCP converts the redirect into an action transport payload and continues with client navigation. Without JavaScript, the browser receives the normal HTTP redirect.
+
+Cookies set before the redirect are preserved in both paths.
+
+## Revalidation and refreshing loaders
+
+`revalidatePath()` and `revalidateTag()` can be called directly inside an action to invalidate BCP data cache entries:
+
+```ts
+revalidatePath("/users");
+revalidateTag("users");
+```
+
+If the current page should immediately rerun its loader after a successful data-returning action, enable the form's `refresh` option:
+
+```tsx
+<Form
+    action="saveUser"
+    method="patch"
+    refresh
+>
+    ...
+</Form>
+```
+
+`refresh` uses the existing BCP router refresh path after the action result is received. Redirecting actions do not need `refresh`.
+
+## Progressive enhancement
+
+The rendered HTML form posts to BCP's internal action endpoint using a normal browser POST. The target page is recovered from the same-origin referrer when JavaScript is unavailable.
+
+When an action returns serializable data and no explicit `Response`, the no-JavaScript path uses POST/Redirect/GET with HTTP `303` back to the original target page. This prevents duplicate browser resubmission on refresh.
+
+With JavaScript enabled, `<Form>` intercepts the submit and sends the same `FormData` through the action transport without reloading the document.
+
+## Middleware, guards, and request order
+
+For a mutation, the effective server order is:
+
+```text
+Security gateway
+    ↓
+Project middleware
+    ↓
+Resolve target page
+    ↓
+Route guards (root → child)
+    ↓
+Named action
+    ↓
+Response cookies / redirect / data
+```
+
+A guard redirect prevents the action from running. Guard data is passed into `context.guardData`, so an authorization lookup does not need to be repeated in the action.
+
+## Why action names are strings
+
+This release intentionally uses:
+
+```tsx
+<Form action="saveUser">
+```
+
+and not:
+
+```tsx
+<Form action={saveUser}>
+```
+
+Passing a server function through a client bundle requires a compiler-generated server reference, serialization protocol and action identifier system. That belongs to the later BCP Server Actions milestone. Keeping named route actions separate now prevents server/database modules from being pulled into hydrated client graphs.
+
+## When to use an API route instead
+
+Use a form action when the mutation belongs to a BCP page UI.
+
+Keep an API route when the caller is an external client such as:
+
+- a mobile application,
+- another backend service,
+- a webhook provider,
+- Postman/API consumers,
+- a public or versioned HTTP API.
+
+A project can use both patterns: loaders for page reads, guards for authorization, form actions for page-owned mutations, and API routes for external HTTP contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",