Skip to content

epic: netlify-forms - Capture website submissions #16

Open
0 of 9 issues completed
Open

Description

@ashleyshaw

Epic Summary

Deliver reliable capture of draft requests, waitlist registrations and contact enquiries for the book website in ThisOneTimeOnAcidCom, a React/Vite site rather than WordPress.

Netlify work below is capture planning, not an approved verification or confirmation-email architecture. Applicable processing/access decisions require reconciliation before implementation.

Replace mock submissions with three Netlify identities across five existing routes:

Identity Routes Submitted fields
draft-unlock /, /read-the-draft, /read-the-book email, source-route, bot-field, form-name
waitlist /waitlist email, source-route, bot-field, form-name
contact /contact name, email, optional organisation, enquiry-type, message, source-route, bot-field, form-name

Newsletter delivery, /newsletter, Brevo embedded signup and double opt-in are owned separately by #374. Draft requests, waitlist registrations and contact enquiries do not automatically enrol subscribers. Capture success requires verified Netlify receipt, not frontend messages alone; newsletter subscription verification belongs to the newsletter epic.

Linked Child Issues/Stories/Tasks/PRs

The nine capture and shared verification/documentation children are in This One Time on Acid — book, with approved T-shirt estimates and template defaults. Existing statuses remain authoritative:

Implementation detail and verification belong in the children. No implementation PR is currently verified; record creation does not start coding or change provider settings.

Milestones & Timeline

No milestone, cycle, due date or release date added. Preserve existing parent fields.

Sequence: deployment/toolchain/routing → shared capture → individual forms and thank-you → deployed QA and operations evidence. Newsletter sequencing and account/consent prerequisites are tracked separately in #374. Shared testing and documentation remain under this epic in #214 and #215.

Acceptance Criteria

  • Contact/About/confirmation and both thank-you outcomes satisfy REQ-011–012 without treating page visits as conversions.
  • All linked stories/tasks completed
  • Five capture routes store intended fields under three Netlify identities, preserving exact pathname including /read-the-book without query strings/fragments/full URLs
  • Static/runtime schemas match and intended forms detected after deployment; historical forms/submissions preserved
  • Required validation, optional organisation, contact enquiry values and Unicode/multiline payloads preserved
  • Pending prevents duplicates; network/non-success responses retain values, allow explicit retry and never navigate/reset/confetti/display success
  • Labels/live feedback/focus/keyboard/mobile/light-dark/reduced motion verified
  • Both thank-you links resolve only to explicitly agreed destination, without chapter-deep-link or secure-access promises
  • No cross-form enrolment or fourth Netlify detector; newsletter routing, pending/confirmed subscription, consent and unsubscribe acceptance are owned by TOA-322
  • Spam handling, approved scoped notifications, monitoring, consent, retention/export ownership documented
  • Deployed records/SHA and production checks prove receipt; search/demo/legacy Typeform/reader preferences unchanged
  • Documentation and changelog updated
  • Tests/QA complete
  • PR description updated with relevant details
  • Changelog entry prepared for PR (if applicable)
  • Labels/types match org standards

Dependencies / Blockers

  • Authorised Netlify access and verified project/production branch/deployed SHA/effective build settings/detection/history.
  • Reproducible Node/package-manager/lockfile agreement. Historical npm success, pnpm ERR_PNPM_VERIFY_DEPS_BEFORE_RUN, nested pnpm run build and absent pnpm-lock.yaml must be reproduced before called current.
  • Reviewed root configuration/SPA fallback repair, preserving headers/specific redirects/assets and verifying form POST handling. Do not use src/app base merely to discover nested configuration.
  • Reader access—outcome approved; mechanism unresolved. The entire website-specific short manuscript requires verified-email access, including direct reader/chapter URLs. Receipt alone grants none. Exact routes, verification/returning-reader behaviour, retention and offline reconciliation remain unresolved. task: thank-you - Repair reader links and acknowledgement copy #208 remains draft acknowledgement work, not contact/newsletter thank-you implementation.
  • Newsletter-specific dependencies belong to TOA-322: authorised Brevo account/list/sender, current free-plan allowances, supported embed, approved consent/privacy text and newsletter navigation placement. No paid upgrade, public campaign or DNS change authorised.
  • Approved capture notification recipients, monitoring responsibility and retention/export ownership.

Original audit 76b1528 and October 3 build/test findings are historical; source inspected during scoping was cb53d2c. Recheck missing jsdom, unrelated failures and TypeScript configuration diagnostic. Passing build alone is not green tests/typechecking.

Additional Context

Follow repository AGENTS.md, CONTRIBUTING.md and guidelines: BEM/token styling, centralised copy, Figma Make syntax, protected images and no Supabase. Preserve existing visual direction and project Figma Make reference.

Guardrails: three static schemas in active root HTML outside React mount; URL-encoded POST with form-name, not JSON; no separate draft-alias detectors. Capture payload synchronously before disabling/awaiting; immediate in-flight guard and explicit retry, not automatic retry. No personal-data logs/browser storage. Preserve enquiry values media/speaking/events/publisher/general and optional organisation; no unapproved tracking/consent fields.

Netlify capture alone does not evidence verified manuscript access or confirmation-email delivery. Required contact confirmation belongs to #210; provider and method remain unresolved. Brevo embedded DOI is separate approved scope owned by TOA-322; no Function bridge/API credentials/custom backend. Dashboard/provider records prove receipt; Vite preview/HTTP acknowledgement alone do not. Inspect Verified/Spam, test honeypot rejection separately; preview data is real unless isolation verified. Preserve history/export before separately approved deletion.

Preserved file references

Original line ranges are historical, not refreshed handler line references. New implementation paths remain proposals:

  • src/app/components/pages/book-site/: BookHomePage.tsx:13–21,51–60; ReadDraftPage.tsx:14–22,46–56; WaitlistPage.tsx:45–53,126–136; ContactPage.tsx:23–26,91–134; ThankYouPage.tsx. Components.
  • AGENTS.md, CONTRIBUTING.md, root index.html/public/, package.json, tracked package-lock.json, absent pnpm-lock.yaml; existing src/app/netlify.toml and proposed root netlify.toml. Contributing guidance.
  • public/_redirects is a directory containing public/_redirects/main.tsx; original redirect asset. dist/, dist/index.html and prospective regular dist/_redirects are generated verification targets. Inactive src/app/index.html and src/app/public/ are not detector locations.
  • Proposed src/app/utils/netlifyForms.ts; src/app/hooks/useNetlifyForm.ts; src/app/data/mock/ui/book-forms.ts; src/app/components/common/NetlifyFormFields.tsx; src/app/components/common/FormSubmissionStatus.tsx; src/styles/blocks/form-submission.css.
  • Existing tests/; proposed tests/netlify-forms.test.ts, tests/book-site-forms.test.tsx, tests/netlify-form-detection.test.mjs. Use Node/tsx approach; DOM dependency explicit/pinned. Children retain encoding, state, deployment and regression coverage/verification commands.
  • Proposed docs/netlify-forms.md; root CHANGELOG.md. Resolve CONTRIBUTING’s differing src/app/CHANGELOG.md reference rather than silently substitute.

Documentation references

Current setup docs govern implementation; older framework articles support context. Functions are reference material, not implementation authorisation.

Epic template basis; retain existing parent ownership/status/priority/other labels. Children retain approved Backlog/status:needs-triage and Documentation meta:no-changelog/changelog-checklist conflicts rather than taxonomy cleanup.


Definition of Ready (DoR)

  • Epic goal and scope defined
  • Linked stories/tasks listed
  • Milestones and timeline mapped
  • Dependencies/blockers identified
  • Estimate added (if applicable)
  • Stakeholders/approvers listed

Definition of Done (DoD)

  • Approved by at least one maintainer
  • All linked stories/tasks completed and closed
  • Documentation/changelog updated
  • QA and testing complete
  • All child issues closed before epic can be closed
  • Epic issue must be updated with latest status before being closed

Unanswered clarification questions

These questions clarify existing capture requirements; they do not authorise provider changes, secure reader access or newsletter enrolment.

  1. Which notification recipients, if any, are approved for each captured form?
  2. Which success destinations and acknowledgement copy are approved for each form, including the unresolved reader destination?
  3. Who owns submission monitoring, and what provider-side evidence must demonstrate receipt?
  4. What consent/privacy wording is approved for draft requests, waitlist registrations and contact enquiries?
  5. Who owns retention and export of captured submissions, and what policy should the operating documentation record?

Activity

  1. linear-code commented on Oct 3, 2026

    @linear-code
  2. changed the title [-]Add real Forms to the netlify.com website[/-] [+]feat: netlify-forms - Collect and store website submissions[/+] on Oct 3, 2026
  3. self-assigned this
    on Oct 3, 2026
  4. added theissue type on Oct 5, 2026
  5. changed the title [-]feat: netlify-forms - Collect and store website submissions[/-] [+]epic: netlify-forms - Capture submissions and newsletter signups[/+] on Oct 5, 2026
  6. changed the title [-]epic: netlify-forms - Capture submissions and newsletter signups[/-] [+]epic: netlify-forms - Capture website submissions[/+] on Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Fields

Priority

None yet

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions