Skip to content

022_web3forms-integration_feature.md

Latest commit

 

History

History
110 lines (75 loc) · 3.74 KB

022_web3forms-integration_feature.md

File metadata and controls

110 lines (75 loc) · 3.74 KB
Raw

Feature: Web3Forms Email Integration

Feature ID: 022 Category: integrations Source: ScriptHammer/docs/specs/009-web3forms-integration Status: Complete (2026-04-08) — src/hooks/useWeb3Forms.ts with unit tests, ContactForm component integrates the hook, form E2E tested in tests/e2e/form-submission.spec.ts. Activates when NEXT_PUBLIC_WEB3FORMS_ACCESS_KEY is set (per-fork configuration).

Description

A contact form integration using Web3Forms as the primary email provider. Provides proper validation, error handling, and user feedback for form submissions without exposing server-side email credentials. Serverless-friendly with no backend configuration required.

User Scenarios

US-1: Submit Contact Form (P1)

A user fills out the contact form and submits their inquiry, receiving immediate feedback on submission status.

Acceptance Criteria:

  1. Given a valid form, when user submits, then data is sent to Web3Forms API
  2. Given submission successful, when user sees feedback, then they see a success message
  3. Given submission failed, when user sees error, then they see a clear error message with retry option

US-2: Form Validation (P1)

Form fields are validated before submission to prevent invalid data and provide immediate feedback.

Acceptance Criteria:

  1. Given name field, when less than 2 characters, then validation error is shown
  2. Given email field, when invalid format, then validation error is shown
  3. Given message field, when less than 10 characters, then validation error is shown

US-3: Honeypot Spam Protection (P2)

The form includes hidden fields to prevent automated spam submissions.

Acceptance Criteria:

  1. Given honeypot field, when filled by bot, then submission is silently rejected
  2. Given legitimate user, when form submitted, then honeypot is ignored
  3. Given spam protection, when active, then it does not affect legitimate users

US-4: Offline Queue (P3)

When offline, form submissions are queued for later delivery.

Acceptance Criteria:

  1. Given user offline, when form submitted, then it is queued locally
  2. Given queued submission, when back online, then submission is retried
  3. Given queue exists, when viewing form, then user sees pending count

Requirements

Functional

  • FR-001: Contact form submits successfully to Web3Forms API
  • FR-002: Form validation with Zod schema (name, email, subject, message)
  • FR-003: User receives clear feedback on submission status
  • FR-004: Form data is sanitized before submission
  • FR-005: Honeypot field for basic spam protection
  • FR-006: Loading states during submission
  • FR-007: Accessibility standards met (WCAG AA)
  • FR-008: Works offline with background sync queue

Non-Functional

  • NFR-001: Form interactive within 100ms
  • NFR-002: API response handling < 3 seconds
  • NFR-003: Bundle size impact < 5KB (excluding existing deps)
  • NFR-004: 96%+ Lighthouse accessibility score

Key Components

  • ContactForm: Main form component with react-hook-form
  • contactSchema: Zod validation schema
  • useWeb3Forms: Hook for submission state management
  • web3forms.ts: API utility functions

Dependencies

# Already installed
react-hook-form
@hookform/resolvers
zod

Configuration

NEXT_PUBLIC_WEB3FORMS_ACCESS_KEY=your_access_key_here

Out of Scope

  • Email template customization
  • Multi-step forms
  • File attachments
  • Database storage of submissions

Success Criteria

  • SC-001: Contact form submits successfully to Web3Forms API
  • SC-002: Form validation prevents invalid submissions
  • SC-003: User receives clear feedback on submission status
  • SC-004: Form data is sanitized before submission
  • SC-005: Accessibility standards met (WCAG AA) - 96% compliance
  • SC-006: Coverage > 80% for new code