📦 ASAP Reactive Forms Engine

Библиотека для создания мощных, гибких и типобезопасных форм в React-приложениях с акцентом на реактивность, читаемость и расширяемость.

✨ Возможности

• Поддержка вложенных форм
• Реактивная модель данных
• Типобезопасность (TypeScript-first)
• Интеграция с UI-библиотекой Mantine
• Поддержка клиентской и серверной валидации
• Валидация с использованием zod
• Простой API

🔧 Установка

npm i @asap-devs/forms

🚀 Быстрый старт

import { useState } from "react";
import {
  createForm,
  Configure,
  FormProvider,
  createConnectedComponents,
  required,
} from "@asap-devs/forms";
import { Button, Title } from "@mantine/core";

// Form type
type TNameForm = {
  name: string;
  surname: string;
};

// Form object model
const NameForm = createForm<TNameForm>({
  validators: [
    ({ field }) => {
      required.eager(field("name"));
    },
  ], // client-side validators for current form
});

export function BasicForm() {
  const [formInstance] = useState(
    () =>
      new NameForm({
        name: "",
        surname: "",
      })
  );

  return (
    <FormProvider
      instance={formInstance}
      onSubmit={(v) => {
        alert(JSON.stringify(v, undefined, 2));
      }}
    >
      <NameFormContent />
    </FormProvider>
  );
}

// Create typed connected components
const { InputField } = createConnectedComponents<TNameForm>();

const NameFormContent = () => {
  return (
    <>
      <InputField 
        getter="name"
        label="Name"
        description="Plaese enter yourname"
      />
      <InputField getter="surname" label="Surname" />
      <Button type="submit" mt="sm">
        Submit
      </Button>
    </>
  );
};

Все примеры использования можно посмотреть в src/examples

✅ Валидация

Библиотека поддерживает декларативную валидацию полей на уровне схемы формы. Все валидаторы указываются при инициализации формы через опцию validators.

📦 Предустановленные валидаторы

| Валидатор | Описание | |-------------|------------------------------------------------------------| | required | Проверяет, что значение не undefined, null или '', для массивов - выбрано хотя бы одно значение | | notNull | Проверяет, что значение не null | | truly | Проверяет, что значение строго true | | pattern | Проверка значения по регулярному выражению (RegExp) | | zodField | Проверяет поле на соотвествие zod схеме | | zod | Проверяет всю форму на соотвествие zod схеме |

🧾 Синтаксис использования

const NameForm = createForm<TNameForm>({
  validators: [
    ({ field }) => {
      required.eager(field("name"));
    },
  ],
});

💎 Валидация с использованием zod

const nameFormSchema = z.object({
  name: z
    .string()
    .nonempty("Error! Must be filled")
    .max(100)
    .refine((_) => _.startsWith("J"), "Error! Must starts with J"),
  surname: z.string(),
  info: z.string().nullable().pipe(z.string("Error! Must be selected").nonempty()),
});

// Form type
type TNameForm = z.input<typeof nameFormSchema>;

// Form object model
const NameForm = createForm({
  validators: [
    // some additional validators
  ],
});

🧱 Компоненты

Ниже перечислены доступные компоненты формы и их статус реализации.

| Компонент | Статус | Версия | Описание | |----------------------|---------|----------|-------------------------------------| | InputField | ✅ | v1.0.0 | Базовое текстовое поле | | InputPasswordField | ✅ | v1.0.0 | Поле для ввода пароля | | InputNumberField | ✅ | v1.0.0 | Числовое поле ввода | | CheckboxField | ✅ | v1.0.0 | Одиночный флажок | | CheckboxGroupField | ✅ | v1.0.0 | Группа флажков | | RadioGroupField | ✅ | v1.0.0 | Группа радио-кнопок | | SwitchField | ✅ | v1.0.0 | Компонент-переключатель | | TextareaField | ✅ | v1.1.0 | Многострочное текстовое поле | | SelectField | ✅ | v1.1.0 | Выпадающий список (select) | | InputDateField | ✅ | v1.5.0 | Поле ввода одиночной даты | | DatePickerField | ✅ | v1.5.0 | Выбор даты (множественный, периоды) | | MultiselectField | 🚧 | | Множественный выбор | | DateRangeField | 🚧 | | Выбор диапазона дат | | FileField | 🚧 | | Загрузка одного или нескольких файлов |

📚 Документация

Проект использует Storybook для интерактивной демонстрации компонентов и примеров использования формы.

🔄 Запуск Storybook локально

npm run storybook

После запуска открой http://localhost:6006 в браузере.