npm package: @ghg/formish
Description: grmn-se-formish is a powerful and flexible form management library for React applications. It provides a set of components and hooks to simplify form handling, state management, and validation.
Author: Jim de Ronde
Latest version: 0.1.10

# grmn-se-formish

grmn-se-formish is a powerful and flexible form management library for React applications. It provides a set of components and hooks to simplify form handling, state management, and validation.

## Table of Contents

- [Installation](#installation)
- [Key Features](#key-features)
- [Usage](#usage)
  - [Basic Example](#basic-example)
  - [Using Zod for Validation](#using-zod-for-validation)
- [API Reference](#api-reference)
  - [Components](#components)
    - [Form](#form)
    - [FormContextProvider](#formcontextprovider)
  - [Hooks](#hooks)
    - [useForm](#useform)
    - [useField](#usefield)
    - [useFormContext](#useformcontext)
- [Advanced Usage](#advanced-usage)
- [TypeScript Support](#typescript-support)
- [Contributing](#contributing)
- [License](#license)

## Installation

To install grmn-se-formish, use npm or yarn:

```bash
npm install grmn-se-formish
# or
yarn add grmn-se-formish
```

## Key Features

- Easy form state management
- Field-level and form-level validation using Zod
- TypeScript support
- Flexible API with hooks and components
- Support for complex nested forms
- Debug mode for easier development

## Usage

### Basic Example

Here's a simple example of how to use grmn-se-formish:

```jsx
import React from "react";
import { Form, useForm } from "grmn-se-formish";

const MyForm = () => {
  const { register, handleSubmit } = useForm();

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("name")} placeholder="Name" />
      <input {...register("email")} placeholder="Email" type="email" />
      <button type="submit">Submit</button>
    </Form>
  );
};

export default MyForm;
```

### Using Zod for Validation

grmn-se-formish integrates seamlessly with Zod for form validation:

```jsx
import React from "react";
import { Form, useForm } from "grmn-se-formish";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(2, "Name must be at least 2 characters"),
  email: z.string().email("Invalid email address"),
});

const MyForm = () => {
  const { register, handleSubmit, errors } = useForm({
    schema,
    validateOnChange: true,
  });

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("name")} placeholder="Name" />
      {errors.name && <span>{errors.name}</span>}
      <input {...register("email")} placeholder="Email" type="email" />
      {errors.email && <span>{errors.email}</span>}
      <button type="submit">Submit</button>
    </Form>
  );
};

export default MyForm;
```

## API Reference

### Components

#### Form

The \`Form\` component is a wrapper for your form elements. It handles form submission and provides context for form state.

Props:

- \`onSubmit\`: Function called when the form is submitted
- \`children\`: React nodes to be rendered inside the form
- \`debug\`: Boolean to enable debug mode
- \`validateOnChange\`: Boolean to enable validation on field change

#### FormContextProvider

The \`FormContextProvider\` component provides form context to its children. It's usually not needed to use this directly, as the \`Form\` component uses it internally.

### Hooks

#### useForm

The \`useForm\` hook is the main entry point for form functionality.

```typescript
const {
  values,
  errors,
  register,
  handleSubmit,
  setFieldValue,
  validateForm,
  // ... other properties and methods
} = useForm(options);
```

Options:

- \`initialSchema\`: Zod schema for form validation
- \`initialValues\`: Initial form values
- \`validateOnChange\`: Boolean to enable validation on field change
- \`debug\`: Boolean to enable debug mode

#### useField

The \`useField\` hook provides access to individual field state and methods.

```typescript
const {
  value,
  error,
  setFieldValue,
  clearFieldValue,
  // ... other properties and methods
} = useField(name, props);
```

#### useFormContext

The \`useFormContext\` hook allows access to the form context from any component within the form.

```typescript
const { values, errors, schema, setValues, setErrors, setSchema } =
  useFormContext(schema, initialValues, debug);
```

## Advanced Usage

grmn-se-formish supports advanced use cases such as:

- Nested form structures
- Dynamic form fields
- Custom validation logic
- Integration with UI libraries

For more detailed examples and advanced usage, please refer to our Advanced Guide.

## TypeScript Support

grmn-se-formish is written in TypeScript and provides full type definitions for all its components and hooks. This ensures type safety and improves developer experience when using the library in TypeScript projects.

## Contributing

We welcome contributions to grmn-se-formish! Please see our Contributing Guide for more information on how to get started.

## License

grmn-se-formish is released under the MIT License. See the LICENSE file for more details.