@pylonsync/react 0.3.248 → 0.3.249

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.248",
+  "version": "0.3.249",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.248",
-    "@pylonsync/sync": "0.3.248"
+    "@pylonsync/sdk": "0.3.249",
+    "@pylonsync/sync": "0.3.249"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/Form.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+
+// Pylon's progressive-enhancement form. Renders a plain `<form method="post">`
+// that works WITHOUT client JS: the browser POSTs to `action` (a route.ts
+// path), the handler processes + redirects (303 See Other), and the browser
+// follows with a GET (POST-redirect-GET). WITH JS, the runtime's global submit
+// handler intercepts (via `data-pylon-form`), `fetch()`es the same endpoint,
+// and follows the redirect through client-side navigation — no full reload.
+//
+// `<form method>` is POST-only without JS (browsers only do GET/POST natively),
+// so POST is the default + the no-JS-safe choice. Set `navigate={false}` to
+// force a native full-page submit even when JS is available.
+export interface FormProps
+  extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "method" | "action"> {
+  /** The `route.ts` handler path (e.g. "/notes"). */
+  action: string;
+  /** HTTP method. Default "post" (the only method usable without JS). */
+  method?: "post" | "put" | "patch" | "delete";
+  /** Opt out of client interception — force a native full-page submit. */
+  navigate?: boolean;
+  children?: React.ReactNode;
+}
+
+export function Form({
+  action,
+  method = "post",
+  navigate = true,
+  children,
+  ...rest
+}: FormProps) {
+  return (
+    <form
+      method={method}
+      action={action}
+      {...(navigate ? { "data-pylon-form": "" } : {})}
+      {...rest}
+    >
+      {children}
+    </form>
+  );
+}

package/src/index.ts

@@ -7,6 +7,8 @@ export { Link } from "./Link";
 export type { LinkProps } from "./Link";
 export { Image } from "./Image";
 export type { ImageProps } from "./Image";
+export { Form } from "./Form";
+export type { FormProps } from "./Form";
 
 // SSR page-author types — the contract every `app/**/page.tsx` is handed
 // in props, plus `metadata` / `generateMetadata`. Type-only.
@@ -20,6 +22,10 @@ export type {
   GenerateMetadata,
   ErrorBoundaryProps,
   NotFoundProps,
+  FormFields,
+  FormDb,
+  FormRequest,
+  RouteHandler,
 } from "./ssr";
 
 // Client navigation hooks for SSR pages (Next-style).

package/src/ssr.ts

@@ -239,3 +239,72 @@ export interface ErrorBoundaryProps {
  * Same shape as a page.
  */
 export type NotFoundProps = PageProps;
+
+/**
+ * Parsed form fields handed to a `route.ts` handler. Mirrors URLSearchParams
+ * `get`/`getAll`/`has` semantics over the submitted body.
+ */
+export interface FormFields {
+  /** First value for `name`, or null. */
+  get(name: string): string | null;
+  /** All values for `name` (empty array if none). */
+  getAll(name: string): string[];
+  has(name: string): boolean;
+  /** Raw map: name → value (single) or values (repeated field). */
+  readonly fields: Record<string, string | string[]>;
+}
+
+/**
+ * Read + write DB handle for a `route.ts` form handler (mutation-shaped). The
+ * read surface is `ServerData`; writes go through the same policy-checked,
+ * broadcast-firing path a mutation's `ctx.db` uses.
+ */
+export interface FormDb extends ServerData {
+  insert<T = Record<string, unknown>>(
+    entity: string,
+    data: Record<string, unknown>,
+  ): Promise<T>;
+  update<T = Record<string, unknown>>(
+    entity: string,
+    id: string,
+    data: Record<string, unknown>,
+  ): Promise<T>;
+  delete(entity: string, id: string): Promise<void>;
+}
+
+/**
+ * The request a `route.ts` POST/PUT/PATCH/DELETE handler receives. Shape the
+ * reply through `response` — usually `response.redirect("/x?ok=1")` (303
+ * POST-redirect-GET, the default) after a write, so a no-JS browser follows
+ * with a GET. Enforce trust with `auth` inside the handler (forms run with the
+ * standard function trust model).
+ *
+ * ```ts
+ * import type { RouteHandler } from "@pylonsync/react";
+ * export const POST: RouteHandler = async ({ form, db, response, auth }) => {
+ *   const body = form.get("body");
+ *   if (!body) return response.redirect("/notes?error=empty");
+ *   await db.insert("Note", { body });
+ *   response.redirect("/notes?created=1");
+ * };
+ * ```
+ */
+export interface FormRequest<
+  TParams extends Record<string, string> = Record<string, string>,
+  TSearchParams extends Record<string, string> = Record<string, string>,
+> {
+  form: FormFields;
+  params: TParams;
+  searchParams: TSearchParams;
+  auth: PageAuth;
+  cookies: Record<string, string>;
+  headers: Record<string, string>;
+  db: FormDb;
+  response: SsrResponse;
+}
+
+/** Signature of a `route.ts` method handler export (POST/PUT/PATCH/DELETE). */
+export type RouteHandler<
+  TParams extends Record<string, string> = Record<string, string>,
+  TSearchParams extends Record<string, string> = Record<string, string>,
+> = (req: FormRequest<TParams, TSearchParams>) => void | Promise<void>;