@sanity/form-toolkit 1.1.0 → 1.2.0

package/README.md

@@ -158,6 +158,85 @@ export default defineType({
 })
 ```
 
+## formSchema and FormRenderer
+
+The `formSchema` plugin and `FormRenderer` React component are designed to be used together to build and render forms in Sanity. `formSchema` provides a Sanity schema for creating `form` documents made up of various `formFields`, then `FormRenderer` takes those `form` documents and renders them as React components. The `formSchema` plugin can be used by itself with your own logic for rendering the form. The `/examples` directory of this repository shows `FormRenderer` being used with popular form libraries.
+
+First add `formSchema` it as a plugin in `sanity.config.ts` (or .js):
+
+```ts
+import {defineConfig} from 'sanity'
+import {formSchema} from '@sanity/form-toolkit'
+
+export default defineConfig({
+  //...
+  plugins: [formSchema()],
+})
+```
+
+Then pass a `form` document to the `FormRenderer` component
+
+```tsx
+import React, {type FC} from 'react'
+import {FormRenderer, type FormDataProps} from '@sanity/form-toolkit'
+
+interface NativeFormExampleProps {
+  formData: FormDataProps
+  action?: string
+  method?: 'get' | 'post'
+}
+/**
+ * Example of using the `FormRenderer` as a native HTML form element.
+ */
+export const NativeFormExample: FC<NativeFormExampleProps> = ({
+  formData, // form document from Sanity
+  action = '/api/submit',
+  method = 'post',
+}) => {
+  return (
+    <FormRenderer
+      formData={formData}
+      action={action}
+      method={method}
+      encType="multipart/form-data"
+    />
+  )
+}
+```
+
+### FormRenderer
+
+The `FormRenderer` component takes documents created with the `formSchema` plugin and renders a form for your front-end. The `formSchema` plugin can be used by itself with your own logic for rendering the form. The `/examples` directory of this repository shows `FormRenderer` being used with popular form libraries. `FormRenderer` takes the following props
+
+#### All props for native `form` element
+
+`FormRenderer` can take all the typical props passed to the `form` element in React like `action`, `onSubmit`, `className`, etc.
+
+#### formData
+
+A `form` document created with the `formSchema` plugin.
+
+#### fieldComponents
+
+An object where the keys are possible input field type names and the values are components for that field's input.
+
+```tsx
+const fieldComponents = {
+  select: MyCustomSelectComponent
+}
+<FormRenderer
+  fieldComponents={fieldComponents}
+/>
+```
+
+#### getFieldState
+
+Function for managing each field as a piece of state (see `react-hook-form.tsx` and `tanstack-form.tsx` in the `/examples` directory)
+
+#### getFieldError
+
+Similar to `getFieldState`, a function for managing each field's errors as a piece of state (see `react-hook-form.tsx` and `tanstack-form.tsx` in the `/examples` directory)
+
 ## License
 
 [MIT](LICENSE) © Chris LaRocque
@@ -170,7 +249,6 @@ with default configuration for build & watch scripts.
 See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
 on how to run this plugin with hotreload in the studio.
 
-
 ### Release new version
 
 Run ["CI & Release" workflow](https://github.com/sanity-io/form-toolkit/actions/workflows/main.yml).

package/dist/index.d.mts

@@ -1,5 +1,8 @@
+import type {ComponentType} from 'react'
 import {EventHandler} from 'h3'
 import {EventHandlerRequest} from 'h3'
+import type {FC} from 'react'
+import type {HTMLProps} from 'react'
 import {IncomingMessage} from 'http'
 import {Plugin as Plugin_2} from 'sanity'
 import {ServerResponse} from 'http'
@@ -14,6 +17,63 @@ export declare function fetchMailchimpData({
   server: string
 }): Promise<unknown>
 
+declare type FieldChoice = {
+  label: string
+  value: string
+}
+
+declare interface FieldComponentProps {
+  field: FormField
+  fieldState: FieldState
+  error?: string
+}
+
+declare type FieldOptions = {
+  placeholder?: string
+  defaultValue?: string
+}
+
+declare interface FieldState {
+  value?: string | number | readonly string[]
+  onChange: (value: unknown) => void
+  onBlur?: () => void
+  ref?: unknown
+}
+
+export declare type FormDataProps = {
+  title: string
+  id: {
+    current: string
+  }
+  fields?: FormField[]
+  submitButton?: {
+    text: string
+    position: 'left' | 'center' | 'right'
+  }
+}
+
+declare type FormField = {
+  type: string
+  label?: string
+  name: string
+  required: boolean
+  validation?: ValidationRule[]
+  options?: FieldOptions
+  choices?: FieldChoice[]
+  _key: string
+}
+
+export declare const FormRenderer: FC<FormRendererProps>
+
+declare interface FormRendererProps extends HTMLProps<HTMLFormElement> {
+  formData: FormDataProps
+  getFieldState?: (fieldName: string) => FieldState
+  getFieldError?: (fieldName: string) => string | undefined
+  fieldComponents?: Record<string, ComponentType<FieldComponentProps>>
+}
+
+export declare const formSchema: Plugin_2<void>
+
 declare type HubSpotForm = {
   id: string
   name: string
@@ -97,4 +157,10 @@ declare type MappedResult = HubSpotForm & {
   value: string
 }
 
+declare type ValidationRule = {
+  type: string
+  value: string
+  message: string
+}
+
 export {}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+import type {ComponentType} from 'react'
 import {EventHandler} from 'h3'
 import {EventHandlerRequest} from 'h3'
+import type {FC} from 'react'
+import type {HTMLProps} from 'react'
 import {IncomingMessage} from 'http'
 import {Plugin as Plugin_2} from 'sanity'
 import {ServerResponse} from 'http'
@@ -14,6 +17,63 @@ export declare function fetchMailchimpData({
   server: string
 }): Promise<unknown>
 
+declare type FieldChoice = {
+  label: string
+  value: string
+}
+
+declare interface FieldComponentProps {
+  field: FormField
+  fieldState: FieldState
+  error?: string
+}
+
+declare type FieldOptions = {
+  placeholder?: string
+  defaultValue?: string
+}
+
+declare interface FieldState {
+  value?: string | number | readonly string[]
+  onChange: (value: unknown) => void
+  onBlur?: () => void
+  ref?: unknown
+}
+
+export declare type FormDataProps = {
+  title: string
+  id: {
+    current: string
+  }
+  fields?: FormField[]
+  submitButton?: {
+    text: string
+    position: 'left' | 'center' | 'right'
+  }
+}
+
+declare type FormField = {
+  type: string
+  label?: string
+  name: string
+  required: boolean
+  validation?: ValidationRule[]
+  options?: FieldOptions
+  choices?: FieldChoice[]
+  _key: string
+}
+
+export declare const FormRenderer: FC<FormRendererProps>
+
+declare interface FormRendererProps extends HTMLProps<HTMLFormElement> {
+  formData: FormDataProps
+  getFieldState?: (fieldName: string) => FieldState
+  getFieldError?: (fieldName: string) => string | undefined
+  fieldComponents?: Record<string, ComponentType<FieldComponentProps>>
+}
+
+export declare const formSchema: Plugin_2<void>
+
 declare type HubSpotForm = {
   id: string
   name: string
@@ -97,4 +157,10 @@ declare type MappedResult = HubSpotForm & {
   value: string
 }
 
+declare type ValidationRule = {
+  type: string
+  value: string
+  message: string
+}
+
 export {}

package/dist/index.js

@@ -1,11 +1,339 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: !0 });
-var sanityPluginAsyncList = require("@sanity/sanity-plugin-async-list"), sanity = require("sanity"), jsxRuntime = require("react/jsx-runtime"), ui = require("@sanity/ui"), h3 = require("h3"), mailchimp = require("@mailchimp/mailchimp_marketing");
+var sanity = require("sanity"), fa = require("react-icons/fa"), lu = require("react-icons/lu"), sanityPluginAsyncList = require("@sanity/sanity-plugin-async-list"), jsxRuntime = require("react/jsx-runtime"), ui = require("@sanity/ui"), h3 = require("h3"), mailchimp = require("@mailchimp/mailchimp_marketing");
 function _interopDefaultCompat(e) {
   return e && typeof e == "object" && "default" in e ? e : { default: e };
 }
 var mailchimp__default = /* @__PURE__ */ _interopDefaultCompat(mailchimp);
-const Option$1 = (option) => /* @__PURE__ */ jsxRuntime.jsxs(ui.Card, { "data-as": "button", padding: 3, radius: 2, tone: "inherit", children: [
+const DefaultField = ({ field, fieldState, error }) => {
+  const { type, label, name, options = {}, choices = [] } = field;
+  if (!type || !name) return null;
+  const { value, onChange, onBlur, ref } = fieldState, handleChange = (e) => {
+    onChange(e.target.value);
+  }, handleCheckboxChange = (e, choiceValue) => {
+    if (Array.isArray(value)) {
+      const newValue = e.target.checked ? [...value, choiceValue] : value.filter((v) => v !== choiceValue);
+      onChange(newValue);
+    } else
+      onChange(e.target.checked ? choiceValue : "");
+  }, renderInput = () => {
+    switch (type) {
+      case "textarea":
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          "textarea",
+          {
+            ref,
+            name,
+            value: value ?? "",
+            onChange: handleChange,
+            onBlur,
+            placeholder: options.placeholder
+          }
+        );
+      case "select":
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          "select",
+          {
+            ref,
+            name,
+            value: value ?? "",
+            onChange: handleChange,
+            onBlur,
+            children: choices?.map((choice, i) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: choice.value, children: choice.label }, i))
+          }
+        );
+      case "radio":
+        return choices?.map((choice, i) => /* @__PURE__ */ jsxRuntime.jsxs("label", { children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              type: "radio",
+              name,
+              ref,
+              value: choice.value,
+              checked: value === choice.value,
+              onChange: handleChange,
+              onBlur
+            }
+          ),
+          choice.label
+        ] }, i));
+      case "checkbox":
+        return choices?.map((choice, i) => /* @__PURE__ */ jsxRuntime.jsxs("label", { children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              type: "checkbox",
+              name,
+              ref,
+              value: choice.value,
+              checked: Array.isArray(value) ? value.includes(choice.value) : value === choice.value,
+              onChange: (e) => handleCheckboxChange(e, choice.value),
+              onBlur
+            }
+          ),
+          choice.label
+        ] }, i));
+      default:
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          "input",
+          {
+            type,
+            ref,
+            name,
+            value: value ?? options.defaultValue ?? "",
+            onChange: handleChange,
+            onBlur,
+            placeholder: options.placeholder
+          }
+        );
+    }
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    label && type != "hidden" && /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: name, children: label }),
+    renderInput(),
+    error && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "error", children: error })
+  ] });
+}, FormRenderer = (props) => {
+  const {
+    formData,
+    getFieldState = (name) => ({
+      value: void 0,
+      onChange: () => {
+      },
+      name
+      // Pass name to field for native form handling
+    }),
+    getFieldError,
+    fieldComponents = {},
+    children
+  } = props, renderField = (field) => {
+    const CustomComponent = fieldComponents[field.type], fieldState = getFieldState(field.name), error = getFieldError?.(field.name);
+    return CustomComponent ? /* @__PURE__ */ jsxRuntime.jsx(CustomComponent, { field, fieldState, error }) : /* @__PURE__ */ jsxRuntime.jsx(DefaultField, { field, fieldState, error });
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs("form", { ...props, id: props.id ?? formData?.id?.current, children: [
+    formData.fields?.map((field) => /* @__PURE__ */ jsxRuntime.jsx("div", { className: "form-field", children: renderField(field) }, field._key)),
+    children,
+    /* @__PURE__ */ jsxRuntime.jsx("button", { type: "submit", children: formData.submitButton?.text || "Submit" })
+  ] });
+}, formType = sanity.defineType({
+  name: "form",
+  title: "Form",
+  type: "document",
+  icon: fa.FaWpforms,
+  fields: [
+    sanity.defineField({
+      name: "title",
+      title: "Form Title",
+      type: "string",
+      description: "Internal title for the form",
+      validation: (Rule) => Rule.required()
+    }),
+    sanity.defineField({
+      name: "id",
+      title: "Form ID",
+      type: "slug",
+      options: {
+        source: "title"
+      }
+      // validation: (Rule) => Rule.required(),
+    }),
+    sanity.defineField({
+      name: "fields",
+      title: "Form Fields",
+      type: "array",
+      of: [{ type: "formField" }]
+    }),
+    sanity.defineField({
+      name: "submitButton",
+      title: "Submit Button",
+      type: "object",
+      fields: [
+        sanity.defineField({
+          name: "text",
+          title: "Button Text",
+          type: "string",
+          initialValue: "Submit"
+        })
+        // defineField({
+        //   name: 'position',
+        //   title: 'Button Position',
+        //   type: 'string',
+        //   options: {
+        //     list: ['left', 'center', 'right'],
+        //   },
+        //   initialValue: 'center',
+        // }),
+      ]
+    })
+  ]
+}), validationTypesByFieldType = {
+  checkbox: ["minSelectedCount", "maxSelectedCount", "custom"],
+  color: ["custom"],
+  date: ["minDate", "maxDate", "custom"],
+  "datetime-local": ["minDate", "maxDate", "custom"],
+  email: ["pattern", "custom"],
+  file: ["maxSize", "fileType", "custom"],
+  hidden: ["custom"],
+  number: ["min", "max", "custom"],
+  // password: ['minLength', 'pattern', 'custom'],
+  radio: ["custom"],
+  range: ["min", "max", "step", "custom"],
+  select: ["custom"],
+  tel: ["pattern", "custom"],
+  text: ["minLength", "maxLength", "pattern", "custom"],
+  textarea: ["minLength", "maxLength", "custom"],
+  time: ["custom"],
+  url: ["pattern", "custom"]
+}, formFieldType = sanity.defineType({
+  name: "formField",
+  title: "Form Field",
+  type: "object",
+  icon: lu.LuTextCursorInput,
+  fields: [
+    sanity.defineField({
+      name: "type",
+      title: "Field Type",
+      type: "string",
+      options: {
+        list: Object.keys(validationTypesByFieldType).map((type) => ({ title: ((fieldType) => {
+          switch (fieldType) {
+            case "datetime-local":
+              return "Date & Time";
+            case "textarea":
+              return "Text Area";
+            case "tel":
+              return "Phone Number";
+            default:
+              return fieldType.charAt(0).toUpperCase() + fieldType.slice(1);
+          }
+        })(type), value: type }))
+      }
+    }),
+    sanity.defineField({
+      name: "label",
+      title: "Field Label",
+      type: "string"
+    }),
+    sanity.defineField({
+      name: "name",
+      title: "Field Name",
+      type: "string",
+      description: "Must start with a letter and contain only letters, numbers, underscores, or hyphens. Must be unique within the form.",
+      validation: (Rule) => Rule.required().custom((name, context) => name ? /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name) ? (context.document?.fields?.map((field) => field.name) || []).filter((n) => n === name).length > 1 ? "Field name must be unique across all form fields" : [
+        "action",
+        "method",
+        "target",
+        "enctype",
+        "accept-charset",
+        "autocomplete",
+        "novalidate",
+        "rel",
+        "submit",
+        "reset"
+      ].includes(name.toLowerCase()) ? "This name is reserved for HTML form attributes. Please choose a different name." : !0 : "Field name must start with a letter and contain only letters, numbers, underscores, or hyphens" : "Required")
+    }),
+    sanity.defineField({
+      name: "required",
+      title: "Required",
+      type: "boolean",
+      initialValue: !1
+    }),
+    // defineField({
+    //   name: 'validation',
+    //   title: 'Validation Rules',
+    //   type: 'array',
+    //   of: [
+    //     {
+    //       type: 'object',
+    //       fields: [
+    //         defineField({
+    //           name: 'type',
+    //           title: 'Validation Type',
+    //           type: 'string',
+    //           hidden: ({parent}) => !parent?.type,
+    //           options: {
+    //             // TODO: I think this needs to be a custom input component?
+    //             // list: ({parent}) => (parent?.type ? validationTypesByFieldType[parent.type] : []),
+    //             list: [],
+    //           },
+    //         }),
+    //         defineField({
+    //           name: 'value',
+    //           title: 'Value',
+    //           type: 'string',
+    //         }),
+    //         defineField({
+    //           name: 'message',
+    //           title: 'Error Message',
+    //           type: 'string',
+    //         }),
+    //       ],
+    //     },
+    //   ],
+    // }),
+    sanity.defineField({
+      name: "choices",
+      title: "Choices",
+      type: "array",
+      hidden: ({ parent }) => !["select", "radio", "checkbox"].includes(parent?.type),
+      of: [
+        {
+          type: "object",
+          fields: [
+            sanity.defineField({
+              name: "label",
+              title: "Label",
+              type: "string"
+            }),
+            sanity.defineField({
+              name: "value",
+              title: "Value",
+              type: "string"
+            })
+          ]
+        }
+      ]
+    }),
+    sanity.defineField({
+      name: "options",
+      title: "Field Options",
+      type: "object",
+      hidden: ({ parent }) => ["select", "radio", "checkbox", "file"].includes(parent?.type),
+      fields: [
+        sanity.defineField({
+          name: "placeholder",
+          title: "Placeholder",
+          type: "string"
+        }),
+        sanity.defineField({
+          name: "defaultValue",
+          title: "Default Value",
+          type: "string"
+        })
+      ]
+    })
+  ],
+  preview: {
+    select: {
+      label: "label",
+      name: "name",
+      type: "type"
+    },
+    prepare({ label, name, type }) {
+      return {
+        title: label || name,
+        subtitle: type
+      };
+    }
+  }
+}), schema = {
+  types: [formType, formFieldType]
+}, formSchema = sanity.definePlugin(() => ({
+  name: "form-toolkit_form-schema",
+  schema
+  // plugins: [structureTool({defaultDocumentNode})],
+})), Option$1 = (option) => /* @__PURE__ */ jsxRuntime.jsxs(ui.Card, { "data-as": "button", padding: 3, radius: 2, tone: "inherit", children: [
   /* @__PURE__ */ jsxRuntime.jsx(ui.Text, { size: 2, textOverflow: "ellipsis", children: option.name }),
   /* @__PURE__ */ jsxRuntime.jsx(ui.Card, { paddingTop: 2, tone: "inherit", style: { background: "inherit" }, children: /* @__PURE__ */ jsxRuntime.jsx(ui.Text, { size: 1, textOverflow: "ellipsis", children: `ID: ${option.value}` }) })
 ] }), hubSpotInput = sanity.definePlugin((options) => ({
@@ -141,8 +469,10 @@ async function fetchMailchimpData({
   return signupForms;
 }
 const mailchimpHandler = (keys) => createHandler(() => fetchMailchimpData(keys));
+exports.FormRenderer = FormRenderer;
 exports.fetchHubSpotData = fetchHubSpotData;
 exports.fetchMailchimpData = fetchMailchimpData;
+exports.formSchema = formSchema;
 exports.hubSpotHandler = hubSpotHandler;
 exports.hubSpotInput = hubSpotInput;
 exports.mailchimpHandler = mailchimpHandler;