@pylonsync/react 0.3.248 → 0.3.250

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.248",
+  "version": "0.3.250",
   "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.250",
+    "@pylonsync/sync": "0.3.250"
   },
   "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.
@@ -18,8 +20,13 @@ export type {
   SsrCookieOptions,
   Metadata,
   GenerateMetadata,
+  RouteSegmentConfig,
   ErrorBoundaryProps,
   NotFoundProps,
+  FormFields,
+  FormDb,
+  FormRequest,
+  RouteHandler,
 } from "./ssr";
 
 // Client navigation hooks for SSR pages (Next-style).

package/src/ssr.ts

@@ -206,6 +206,40 @@ export type GenerateMetadata<
   props: PageProps<TParams, TSearchParams>,
 ) => Metadata | Promise<Metadata>;
 
+/**
+ * Per-route configuration, declared as top-level `export const` in a
+ * `page.tsx` (Next-shaped). All optional. The runtime reads these statically
+ * before the render.
+ *
+ * ```ts
+ * export const revalidate = 60;          // CDN + origin-disk cache for 60s
+ * export const dynamic = "force-dynamic"; // never cache
+ * export const streaming = true;          // progressive Suspense streaming
+ * ```
+ *
+ * - `revalidate` — seconds an auth-independent render stays cacheable
+ *   (`public, s-maxage=N`); also kept in the origin disk cache. See the
+ *   "Anonymous output caching" rules — it only takes effect if the render
+ *   never reads `auth`, sets no cookie, and isn't running strict policies.
+ * - `dynamic` — `"force-static"` caches until the next deploy; `"force-dynamic"`
+ *   opts out of all caching.
+ * - `streaming` — opt into PROGRESSIVE streaming: the shell + each inner
+ *   `<Suspense>` fallback flush immediately, then each boundary's real content
+ *   streams in as its data resolves (instead of buffering the whole document).
+ *   A page with a `loading.tsx` already streams at the route level; this
+ *   extends it to a page's OWN inner boundaries. Mutually exclusive with
+ *   caching: a streaming render commits its HTTP head before suspended
+ *   subtrees finish, so it can never be marked cacheable (and a deep
+ *   `<Suspense>` throw resolves via its `error.tsx` at HTTP 200, not a 5xx).
+ *   Set `response.*` (status/cookies) only in the synchronous shell — late
+ *   calls from a suspended subtree are dropped (the runtime warns).
+ */
+export interface RouteSegmentConfig {
+  revalidate?: number;
+  dynamic?: "force-static" | "force-dynamic";
+  streaming?: boolean;
+}
+
 /**
  * Props an `app/.../error.tsx` boundary receives. Error boundaries are now
  * HYDRATED (interactive — useState/onClick/effects work), so `reset` is a
@@ -239,3 +273,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>;