Form Guardian для React

Полное руководство по использованию Form Guardian с React приложениями. Построено поверх @form-guardian/dom с React-специфичными хуками и утилитами.

⚠️ Уведомление о стабильности

Хук useFormAutosave в настоящее время нестабилен и может иметь проблемы в определенных случаях использования. Для production приложений мы рекомендуем использовать attachFormAutosave из @form-guardian/dom напрямую, что более стабильно и надежно.

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

Установка

npm install @form-guardian/react

Peer зависимости:

• react: ^16.8.0 || ^17.0.0 || ^18.0.0

Базовое использование

import { useFormAutosave } from '@form-guardian/react';

function MyForm() {
  const { formRef, hasDraft, clearDraft } = useFormAutosave('my-form', {
    autoRestore: true,
    debounceMs: 500,
  });

  const handleSubmit = async (e) => {
    e.preventDefault();
    await clearDraft();
    // Отправка формы...
  };

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      {hasDraft && <div className="alert">Обнаружены несохраненные изменения</div>}
      <input name="name" placeholder="Имя" />
      <input name="email" type="email" placeholder="Email" />
      <button type="submit">Отправить</button>
    </form>
  );
}

📚 Содержание раздела

Справочник API

Полная документация API для всех React хуков и утилит:

• useFormAutosave - Основной хук для автосохранения форм
• useDraftStatus - Легковесное отслеживание статуса черновика
• Все возвращаемые типы и интерфейсы

Интеграция с React Hook Form

Полное руководство по интеграции с React Hook Form:

• Настройка и конфигурация
• Контролируемые компоненты
• Автосохранение на уровне полей
• Интеграция валидации

Неконтролируемые формы

Работа с неконтролируемыми React компонентами:

• Лучшие практики
• Оптимизация производительности
• Распространенные паттерны

Примеры и паттерны

Реальные примеры и паттерны:

• Многошаговые формы
• Динамические поля
• Загрузка файлов
• WYSIWYG редакторы
• Сложная валидация

🎯 Частые случаи использования

Неконтролируемая форма (Рекомендуется)

Простые формы без внешнего управления состоянием:

import { useFormAutosave } from '@form-guardian/react';

function ContactForm() {
  const { formRef, hasDraft, draftTimestamp, clearDraft } = useFormAutosave(
    'contact-form',
    { autoRestore: true }
  );

  return (
    <form ref={formRef} onSubmit={async (e) => {
      e.preventDefault();
      await clearDraft();
      // Отправка...
    }}>
      {hasDraft && (
        <div className="draft-alert">
          Черновик от {new Date(draftTimestamp).toLocaleString()}
        </div>
      )}
      <input name="name" />
      <input name="email" type="email" />
      <textarea name="message" />
      <button type="submit">Отправить</button>
    </form>
  );
}

React Hook Form

Для контролируемых форм с валидацией:

import { useForm } from 'react-hook-form';
import { useFormAutosave } from '@form-guardian/react';
import { useEffect } from 'react';

function ProfileForm() {
  const { register, handleSubmit, setValue, getValues, watch } = useForm();
  const { formRef, restoreValues, clearDraft, saveValues } = useFormAutosave(
    'profile-form',
    { autoRestore: false }
  );

  // Восстановление при монтировании
  useEffect(() => {
    restoreValues(setValue, getValues);
  }, []);

  // Автосохранение при изменениях
  useEffect(() => {
    const subscription = watch(() => saveValues());
    return () => subscription.unsubscribe();
  }, [watch]);

  return (
    <form ref={formRef} onSubmit={handleSubmit(async (data) => {
      await clearDraft();
      // Отправка данных...
    })}>
      <input {...register('name', { required: true })} />
      <input {...register('email', { required: true })} />
      <button type="submit">Сохранить</button>
    </form>
  );
}

Индикатор статуса черновика

Показать статус черновика в любом месте приложения:

import { useDraftStatus } from '@form-guardian/react';

function AppHeader() {
  const { hasDraft, updatedAt } = useDraftStatus('contact-form');

  return (
    <header>
      <h1>Мое приложение</h1>
      {hasDraft && (
        <span className="draft-badge">
          📝 Черновик от {new Date(updatedAt).toLocaleTimeString()}
        </span>
      )}
    </header>
  );
}

🔥 Продвинутые возможности

События аналитики

Отслеживайте поведение пользователей с комплексными событиями:

const { formRef } = useFormAutosave('my-form', {
  onBeforeSave: async (values) => {
    console.log('Сохранение черновика...', values);
  },
  onAfterSave: async (values) => {
    analytics.track('draft_saved', { formId: 'my-form' });
  },
  onBeforeRestore: async (values) => {
    console.log('Восстановление черновика...', values);
  },
  onAfterRestore: async (values) => {
    analytics.track('draft_restored', { formId: 'my-form' });
  },
  onDraftExpired: async (draftId) => {
    console.log('Черновик истек:', draftId);
  },
});

Узнать больше о событиях аналитики →

Пакетное сохранение

Оптимизируйте производительность, группируя сохранения:

const { formRef } = useFormAutosave('my-form', {
  batchSaveInterval: 5000, // Сохранять каждые 5 секунд
  debounceMs: 300,
});

Узнать больше о пакетировании →

Безопасность

Автоматически исключать чувствительные поля:

const { formRef } = useFormAutosave('payment-form', {
  blacklist: [
    'input[type="password"]',
    'input[name="cvv"]',
    'input[name="cardNumber"]',
  ],
});

TTL (Время жизни)

Автоматически удалять черновики после периода:

const { formRef } = useFormAutosave('my-form', {
  ttl: { days: 7 }, // Истекает через 7 дней
  onDraftExpired: (draftId) => {
    console.log('Черновик истек:', draftId);
  },
});

📖 Узнать больше

• Справочник API - Полная документация API
• Руководство React Hook Form - Полное руководство по интеграции
• Лучшие практики - Советы и подводные камни

🆚 Когда использовать React пакет против DOM пакета

Используйте @form-guardian/react когда:

• ✅ Создаете React приложения
• ✅ Нужен API на основе React хуков
• ✅ Хотите статус черновика в React состоянии
• ✅ Нужны TypeScript типы для React

Используйте @form-guardian/dom в React когда:

• ✅ Хотите минимальный размер бандла
• ✅ Не нужны React-специфичные возможности
• ✅ Уже управляете рефами вручную
• ✅ Создаете кастомную React обертку

Оба пакета отлично работают с React! Выбирайте исходя из ваших потребностей.