updating docs and cleanup

src/Field.tsx

@@ -155,6 +155,13 @@ export type FieldProps<
         children?: ReactNode;
     };
 
+/**
+ * The `<Field />` component is the main building-block of forms in
+ * Formularity. It drastically reduces the amount of boilerplate code
+ * needed to manage the state of a form field by taking care of many basic
+ * actions such as handling change, blur, and showing errors. **Must be used
+ * underneath a `<Formularity />` component.**
+ */
 export const Field = <
     TFormValues extends FormValues
     , TFieldName extends DeepKeys<TFormValues> = DeepKeys<TFormValues>

src/Form.tsx

@@ -8,6 +8,15 @@ import { useFormularityContext } from './FormularityContext';
 
 export type FormProps = PropsWithChildren<ComponentProps<'form'>>;
 
+/**
+ * The <Form /> component is a simple
+ * wrapper around an html `<form>`
+ * that abstracts away the `onSubmit` and
+ * `onReset` handlers and allows `<Formularity />`
+ * to take control of them. `<Formularity />` uses this
+ * component by default but can be turned off if a
+ * manual implementation of a form is desired.
+ */
 export const Form = ( {
     children
     , ...props

src/Formularity.tsx

@@ -19,7 +19,15 @@ import { FormularityContext } from './FormularityContext';
 export type FormularityComponentProps<TFormValues extends FormValues> =
     UseFormularityParams<TFormValues>
     & {
+        /**
+         * By default, `<Formularity />` uses the `<Form />` component to wrap its children.
+         * If you want to use a custom form component or none at all, set this to `false`.
+         */
         useFormComponent?: boolean;
+        /**
+         * The function that will be called to render the children of the `<Formularity />` component.
+         * The Formularity props and components are passed to this function for an easy form-building experience.
+         */
         children: ( formularity: FormularityProps<TFormValues> ) => ReactNode;
     };
 

src/ResetButton.tsx

@@ -13,6 +13,11 @@ export type ResetButtonProps<TComponentProps extends Record<string, unknown> = E
     & { component?: ReactNode }
     & TComponentProps;
 
+/**
+ * This component is an abstraction of the `<button type='reset' />` pattern in forms.
+ * Use this component to reduce reset button boilerplate code and ensure proper
+ * resetting of the form.
+ */
 export const ResetButton = memo( <TComponentProps extends Record<string, unknown> = EmptyObject>( {
     component
     , children

src/SubmitButton.tsx

@@ -67,6 +67,12 @@ export type SubmitButtonProps<
             : Omit<NoInfer<TComponentProps>, 'type' | 'children'>
     );
 
+/**
+ * This component is an abstraction of the `<button type='submit' />` pattern in forms,
+ * as well as a simple way to set common submit disabling logic on the form.
+ * Use this component to reduce submit button boilerplate code and ensure proper
+ * submitting of the form.
+ */
 export const SubmitButton = <
         TDisableInvalid extends boolean
         , TComponentProps = undefined

src/createFormStore.ts

@@ -39,6 +39,11 @@ export type CreateFormStoreParams<TFormValues extends FormValues> = {
     onSubmit?: ( formValues: TFormValues ) => void | Promise<void>;
 };
 
+/**
+ * This function creates a `FormStore` that can be used to manage the state of a form.
+ * **Must be used in conjunction with the `Formularity` component or `useFormularity`
+ * in order for Formularity-based forms to work.**
+ */
 export const createFormStore
     = <TFormValues extends FormValues>( formStoreParams: CreateFormStoreParams<TFormValues> ): FormStore<TFormValues> => {
         let storeState = {

src/disableLogicUtils.ts

@@ -1,6 +1,10 @@
 // Types
 import { FormularityProps } from './types';
 
+/**
+ * Allow the user to submit once, and if errors
+ * exist after that first submission, disable.
+ */
 export const disableAfterFirstSubmit = ( {
     submitCount
     , isValid
@@ -10,6 +14,11 @@ export const disableAfterFirstSubmit = ( {
         : false;
 };
 
+/**
+ * Allow the user to submit once, and if errors
+ * exist after that first submission, disable, unless
+ * editing mode as been turned on.
+ */
 export const disableAfterFirstSubmitUnlessEditing = ( {
     submitCount
     , isValid
@@ -23,6 +32,9 @@ export const disableAfterFirstSubmitUnlessEditing = ( {
             : false;
 };
 
+/**
+ * Disable the form if it is not valid and not dirty.
+ */
 export const isFormDisabledNotDirty = ( {
     isValid
     , isDirty

src/types.ts

@@ -256,6 +256,13 @@ FormStoreState<TFormValues>
 
 ////// COMPONENTS //////
 export type FormularityComponents<TFormValues extends FormValues> = {
+    /**
+     * The `<Field />` component is the main building-block of forms in
+     * Formularity. It drastically reduces the amount of boilerplate code
+     * needed to manage the state of a form field by taking care of many basic
+     * actions such as handling change, blur, and showing errors. **Must be used
+     * underneath a `<Formularity />` component.**
+     */
     Field: FieldComponent<TFormValues>;
     /**
      * `<FieldList />` is a component that helps you
@@ -294,7 +301,18 @@ export type FormularityComponents<TFormValues extends FormValues> = {
     * ```
     */
     FieldList: FieldListComponent<TFormValues>;
+    /**
+     * This component is an abstraction of the `<button type='submit' />` pattern in forms,
+     * as well as a simple way to set common submit disabling logic on the form.
+     * Use this component to reduce submit button boilerplate code and ensure proper
+     * submitting of the form.
+     */
     SubmitButton: SubmitButtonComponent;
+    /**
+     * This component is an abstraction of the `<button type='reset' />` pattern in forms.
+     * Use this component to reduce reset button boilerplate code and ensure proper
+     * resetting of the form.
+     */
     ResetButton: ResetButtonComponent;
 };
 

src/useFormularity.ts

@@ -117,6 +117,14 @@ export type UseFormularityParams<TFormValues extends FormValues> = {
     validateOnSubmit?: boolean;
 };
 
+/**
+ * `useFormularity` is the heart and brains of Formularity. Under the hood, it powers
+ * the `<Formularity />` component and its child components. This form may be used to manually
+ * implement a custom version of Formularity, but it is recommended to only go this route if
+ * absolutely necessary. This hook may also be used to access form state from outside of the `<Formularity />`
+ * component bounds. This should also be used on a conditional basis, when absolutely needed, to
+ * avoid potential, undesired side-effects.
+ */
 export const useFormularity = <TFormValues extends FormValues>( {
     formStore
     , isEditing = false