react-form-action 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 MiroslavPetrik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# react-form-action
+
+Typesafe success & error state control for Next.js v14 form actions.
+
+## Install
+
+```
+npm i react-form-action
+```
+
+## Usage
+
+### Server Action (usable in Next.js)
+
+```ts
+// actions/updateUser.ts
+"use server";
+import { createFormAction } from "react-form-action";
+
+// Define custom serializable error & success data types
+type ErrorData = {
+  message: string;
+  validation?: boolean;
+};
+
+type SuccessData = string;
+
+export const updateUser = createFormAction<SuccessData, ErrorData>(
+  ({ success, failure }) =>
+    // success and failure helper functions create wrappers for success & error data respectively
+    async (prevState, formData) => {
+      if (prevState.type === "initial") {
+        // use the initialData passed to <Form /> here
+        // prevState.data === "foobar"
+      }
+
+      try {
+        const { name } = updateUserSchema.parse({
+          name: formData.get("name"),
+        });
+
+        const user = await updateCurrentUser(name);
+
+        if (user) {
+          const successState = success("Your profile has been updated.");
+          // {type: "success", data: "Your profile has been updated.", error: null }
+          return successState;
+        } else {
+          const errorState = failure({ message: "No current user." });
+          // {type: "error", data: null, error: { message: "No current user." } }
+          return errorState;
+        }
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return failure({
+            validation: true,
+            message: error.issues[0]?.message ?? "Validation error",
+          });
+        }
+
+        return failure({ message: "Failed to update user." });
+      }
+    }
+);
+```
+
+### `<Form>` Component
+
+```tsx
+"use client";
+// Form connects the formAction to the formState & provides the meta state props via render prop
+import { Form } from "react-form-action/client";
+
+import { updateUser } from "@/actions";
+
+export function UpdateUserForm() {
+  return (
+    <Form action={updateUser} initialData="foobar">
+      {({ error, data, isPending, isFailure, isSuccess, isInitial }) => (
+        <>
+          {/* safely access the data or error by checking the mutually exclusive boolean flags: */}
+          {isSuccess && <p className="success-message">{data}</p>}
+
+          {isFailure && !error.validation && (
+            <p className="error-message">{error.message}</p>
+          )}
+
+          <input type="text" name="name" disabled={isPending} />
+          {isFailure && error.validation && (
+            <span className="input-error">{error.message}</span>
+          )}
+
+          <button disabled={isPending}>
+            {isPending ? "Submitting..." : "Submit"}
+          </button>
+        </>
+      )}
+    </Form>
+  );
+}
+```
+
+### Bonus `<FormStatus>`
+
+The `useFormStatus` hook data exposed via render prop:
+
+```tsx
+import { FormStatus } from "react-form-action/client";
+
+// <FormStatus> alleviates the need to create a separate <SubmitButton> component using the useFormStatus hook
+
+return function MyForm() {
+  return (
+    <form action={action}>
+      <FormStatus>
+        {({ pending }) => (
+          <button type="submit">{pending ? "Submitting..." : "Submit"} </button>
+        )}
+      </FormStatus>
+    </form>
+  );
+};
+```

package/dist/client.d.mts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import React__default, { FormHTMLAttributes } from 'react';
+import { RenderProp } from 'react-render-prop-type';
+import { InitialState, FailureState, SuccessState, FormState } from './index.mjs';
+import { useFormStatus } from 'react-dom';
+
+type FormStateProps<Data, Error, Payload> = {
+    action: (state: FormState<Data, Error>, payload: Payload) => Promise<FormState<Data, Error>>;
+    initialData: Data;
+    permalink?: string;
+};
+type FormMetaState<T extends FormState<unknown, unknown>> = T & {
+    isPending: boolean;
+    isInitial: T["type"] extends "initial" ? true : false;
+    isFailure: T["type"] extends "failure" ? true : false;
+    isSuccess: T["type"] extends "success" ? true : false;
+};
+declare function Form<Data, Error>({ children, action, initialData, permalink, ...props }: Omit<FormHTMLAttributes<HTMLFormElement>, "action" | "children"> & FormStateProps<Data, Error, FormData> & RenderProp<FormMetaState<InitialState<Data>> | FormMetaState<FailureState<Error>> | FormMetaState<SuccessState<Data>>>): React__default.JSX.Element;
+
+declare function FormStatus({ children, }: RenderProp<ReturnType<typeof useFormStatus>>): React.ReactNode;
+
+export { Form, FormStatus };

package/dist/client.mjs

@@ -0,0 +1 @@
+"use client";import a from"react";import{useFormState as l}from"react-dom";import{useFormStatus as u}from"react-dom";function r({children:t}){return t(u())}function c(t){return{type:"initial",data:t,error:null}}function D({children:t,action:o,initialData:i,permalink:n,...s}){let[e,m]=l(o,c(i),n);return a.createElement("form",{action:m,...s},a.createElement(r,null,({pending:p})=>t({...e,isPending:p,isInitial:e.type==="initial",isFailure:e.type==="failure",isSuccess:e.type==="success"})))}export{D as Form,r as FormStatus};

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+type InitialState<T> = {
+    type: "initial";
+    data: T;
+    error: null;
+};
+type FailureState<T> = {
+    type: "failure";
+    data: null;
+    error: T;
+};
+type SuccessState<T> = {
+    type: "success";
+    data: T;
+    error: null;
+};
+type FormState<Data, Error> = InitialState<Data> | FailureState<Error> | SuccessState<Data>;
+declare function createFormAction<Data, Error = Data, Payload = FormData>(formAction: (params: {
+    success: (data: Data) => SuccessState<Data>;
+    failure: (data: Error) => FailureState<Error>;
+}) => (state: FormState<Data, Error>, payload: Payload) => Promise<FormState<Data, Error>>): (state: FormState<Data, Error>, payload: Payload) => Promise<FormState<Data, Error>>;
+
+export { FailureState, FormState, InitialState, SuccessState, createFormAction };

package/dist/index.mjs

@@ -0,0 +1 @@
+function u(t){function r(a){return{type:"success",data:a,error:null}}function e(a){return{type:"failure",data:null,error:a}}return(a,o)=>t({success:r,failure:e})(a,o)}export{u as createFormAction};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "react-form-action",
+  "version": "0.1.0",
+  "description": "State management helpers for the react form actions.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MiroslavPetrik/react-form-action.git"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "module": "./dist/index.mjs",
+      "default": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./client": {
+      "import": "./dist/client.mjs",
+      "module": "./dist/client.mjs",
+      "default": "./dist/client.mjs",
+      "types": "./dist/client.d.mts"
+    }
+  },
+  "keywords": [
+    "react",
+    "form",
+    "action",
+    "next",
+    "nextjs",
+    "server",
+    "action"
+  ],
+  "author": "Miroslav Petrik",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18.2",
+    "react-dom": ">=18.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.37",
+    "@types/react-dom": "^18.2.15",
+    "next": "^14.0.2",
+    "react-render-prop-type": "^0.1.0",
+    "tsup": "^7.2.0",
+    "typescript": "^5.2.2"
+  }
+}