Add readme

Show usage guide.

README.md

@@ -14,11 +14,114 @@ Powered by [formxtra](https://code.modal.sh/modal-soft/formxtra).
 
 * Emulate client-side behavior in a purely server-side manner
 * HTTP compliant (respects status code semantics)
-* Easy setup (adapts to how receiving requests are made in Next)
+* Easy setup (adapts to how receiving requests are made in the framework of choice)
 
+## Usage
+
+`iceform` defines two routes in the backend component: the API route used by client-side JavaScript, and the action
+route used by the form when client-side JavaScript is not available.
+
+### Next.js
+
+First, define the common business logic:
+```ts
+// [src/]handlers/greet.ts
+
+import {NextApiHandler} from 'next';
+
+export const greet: NextApiHandler = async (req, res) => {
+	const { name } = req.body;
+	res.status(202).json({
+		name: `Hello ${name}`,
+	});
+};
+```
+
+Then define the API route:
+```ts
+// [src/]pages/api/greet.ts
+
+import * as Iceform from '@modal-sh/iceform-next';
+import { greet } from '@/handlers/greet';
+
+const handler = Iceform.action.wrapApiHandler(greet);
+
+// you can extend the route config by passing an extra argument
+export const config = Iceform.action.getApiConfig();
+
+export default handler;
+```
+
+Next, define the action route:
+```ts
+// [src/]pages/a/greet.ts
+//
+// (we use `/a/**` routes but feel free to use something else)
+import {NextPage} from 'next';
+import * as Iceform from '@modal-sh/iceform-next';
+import {greet} from '@/handlers/greet';
+
+// render anything while form is being processed, or just return an empty component here
+const ActionGreetPage: NextPage = () => null;
+
+export default ActionGreetPage;
+
+export const getServerSideProps = Iceform.action.getServerSideProps(greet);
+```
+
+Lastly, define the form page:
+```tsx
+// [src/]pages/form.tsx
+
+import * as React from 'react';
+import * as Iceform from '@modal-sh/iceform-next';
+
+const FormPage: Iceform.NextPage = ({
+	req,
+	res,
+}) => {
+	const {response, ...isoformProps} = Iceform.useResponse(res);
+	// you may access the server-side body on `res.body`
+
+	const [responseData, setResponseData] = React.useState<unknown>();
+	React.useEffect(() => {
+		if (response?.bodyUsed === false) {
+			response?.json().then((responseData) => {
+				setResponseData(responseData);
+			});
+		}
+	}, [response]);	
+	
+	// set up your form fields
+	return (
+		<Iceform.Form
+			{...isoformProps}
+			method="post"
+			action="/a/greet"
+			clientAction="/api/greet"
+		>
+			<input
+				type="text"
+				name="name"
+			/>
+			<button
+				type="submit"
+			>
+				Submit
+			</button>
+		</Iceform.Form>
+	)
+};
+
+export const getServerSideProps = Iceform.destination.getServerSideProps();
+
+export default GreetPage;
+```
+
+In theory, any API route may have a corresponding action route.
 
 ## TODO
 
-* Content negotiation (custom request data)
-* Tests
-* Remix support
+- [X] Content negotiation (custom request data)
+- [ ] Tests
+- [ ] Remix support

packages/iceform-next-sandbox/README.md

@@ -1,38 +0,0 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
-
-## Getting Started
-
-First, run the development server:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
-
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
-
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
-
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.

packages/iceform-next-sandbox/src/pages/greet.tsx

@@ -9,9 +9,11 @@ const GreetPage: Iceform.NextPage = ({
 
   const [responseData, setResponseData] = React.useState<unknown>();
   React.useEffect(() => {
-    response?.json().then((responseData) => {
-      setResponseData(responseData);
-    });
+		if (response?.bodyUsed === false) {
+			response?.json().then((responseData) => {
+				setResponseData(responseData);
+			});
+		}
   }, [response]);
 
   return (