@qaflo/forms-client 1.0.0

package/turnstile.js

@@ -0,0 +1,181 @@
+/**
+ * The Turnstile lifecycle, as a React hook.
+ *
+ * EXPLICIT rendering, with a widget id per hook instance. Implicit rendering
+ * (letting the script scan the DOM for `.cf-turnstile`) breaks in two ways this
+ * codebase has already met: the script never rescans after a client-side
+ * navigation, so a form reached by clicking a link gets no widget at all; and
+ * two forms on one page share `turnstile.reset()` with no argument, so
+ * submitting one blanks the other's token. royalshadescurtains renders a form
+ * in its footer AND on its contact page, on the same page.
+ *
+ * Everything that touches `window` is inside an effect. These are Gatsby sites
+ * and they server-render this component.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { submitTo, DEFAULT_ENDPOINT } from './submit.js'
+import { SECURITY_CHECK_PENDING } from './messages.js'
+
+/**
+ * `render=explicit` is what stops the script auto-scanning the DOM. The markup
+ * below may still carry `class="cf-turnstile"` — inert decoration once the
+ * script is in explicit mode, and worth keeping so the widget is recognisable.
+ */
+export const TURNSTILE_SCRIPT =
+  'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit'
+
+/**
+ * Hidden from people, visible to bots. Styled away rather than `type="hidden"`:
+ * a bot reads the markup either way, but a password manager will not autofill a
+ * positioned-off-screen text input, and an autofilled honeypot is a real
+ * visitor's enquiry silently dropped.
+ */
+export const honeypotStyle = {
+  position: 'absolute',
+  left: '-9999px',
+  width: 1,
+  height: 1,
+  overflow: 'hidden',
+}
+
+// One script tag for the whole page, however many forms mount.
+/** @type {Promise<any> | null} */
+let scriptPromise = null
+
+/** @returns {Promise<any>} */
+export function loadTurnstile() {
+  if (typeof window === 'undefined') return Promise.reject(new Error('turnstile: no window'))
+  if (window.turnstile) return Promise.resolve(window.turnstile)
+  if (!scriptPromise) {
+    scriptPromise = new Promise((resolve, reject) => {
+      const existing = document.querySelector(`script[src="${TURNSTILE_SCRIPT}"]`)
+      const script = existing || document.createElement('script')
+      script.addEventListener('load', () => resolve(window.turnstile))
+      script.addEventListener('error', () => {
+        scriptPromise = null // let the next mount try again
+        reject(new Error('turnstile failed to load'))
+      })
+      if (!existing) {
+        script.src = TURNSTILE_SCRIPT
+        script.async = true
+        script.defer = true
+        document.head.appendChild(script)
+      }
+    })
+  }
+  return scriptPromise
+}
+
+/**
+ * One widget per call.
+ *
+ * @param {{ sitekey: string, action: string, endpoint?: string, appearance?: string, messages?: Record<string|number, string>, fallbackEmail?: string, theme?: string }} config
+ */
+export function useTurnstile(config) {
+  const { sitekey, action, endpoint = DEFAULT_ENDPOINT, appearance = 'interaction-only' } = config
+
+  const containerRef = useRef(/** @type {HTMLElement | null} */ (null))
+  const widgetId = useRef(/** @type {string | null} */ (null))
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+    loadTurnstile()
+      .then((turnstile) => {
+        if (cancelled || !containerRef.current || widgetId.current !== null) return
+        widgetId.current = turnstile.render(containerRef.current, {
+          sitekey,
+          // MUST equal the site's site_key in the registry. The service compares
+          // it with the action Cloudflare reports, which is what stops a token
+          // solved on one of the thirty sites being spent on another.
+          action,
+          appearance,
+          ...(config.theme ? { theme: config.theme } : {}),
+        })
+        if (!cancelled) setReady(true)
+      })
+      .catch(() => {
+        // Blocked script, or an ad blocker. Submitting will say the check has
+        // not finished rather than posting a request that can only 403.
+      })
+    return () => {
+      cancelled = true
+      if (widgetId.current !== null && typeof window !== 'undefined' && window.turnstile) {
+        try {
+          window.turnstile.remove(widgetId.current)
+        } catch {
+          /* already gone */
+        }
+      }
+      widgetId.current = null
+    }
+    // sitekey/action/appearance are per-site constants; re-rendering the widget
+    // because an object literal was rebuilt would throw the token away.
+  }, [sitekey, action, appearance, config.theme])
+
+  /** Read this widget's token. `''` when it has not solved yet. */
+  const getToken = useCallback(() => {
+    if (widgetId.current === null || typeof window === 'undefined' || !window.turnstile) return ''
+    try {
+      return window.turnstile.getResponse(widgetId.current) || ''
+    } catch {
+      return ''
+    }
+  }, [])
+
+  /**
+   * Tokens are single-use and expire in five minutes, so reset whichever way a
+   * submit went; a second attempt on the old token is a 403 that looks like a
+   * broken captcha. Scoped to THIS widget's id.
+   */
+  const reset = useCallback(() => {
+    if (widgetId.current === null || typeof window === 'undefined' || !window.turnstile) return
+    try {
+      window.turnstile.reset(widgetId.current)
+    } catch {
+      /* widget not mounted; nothing to reset */
+    }
+  }, [])
+
+  /**
+   * Spread on an empty <div /> for a site that wants the markup handed to it.
+   * A site that owns its own markup uses `containerRef` directly instead.
+   */
+  const widgetProps = {
+    ref: containerRef,
+    className: 'cf-turnstile',
+    'data-sitekey': sitekey,
+    'data-action': action,
+    'data-appearance': appearance,
+  }
+
+  /**
+   * Submit through THIS widget: read its token, refuse without one, post, and
+   * reset it afterwards. The refusal deliberately does not reset — the widget is
+   * probably still solving, and resetting would discard that.
+   *
+   * @param {Record<string, unknown>} body
+   */
+  const submit = useCallback(
+    async (body) => {
+      const token = getToken()
+      if (!token) {
+        return { ok: false, status: 0, message: SECURITY_CHECK_PENDING }
+      }
+      try {
+        return await submitTo(endpoint, body, {
+          token,
+          messages: config.messages,
+          fallbackEmail: config.fallbackEmail,
+        })
+      } finally {
+        reset()
+      }
+    },
+    [endpoint, getToken, reset, config.messages, config.fallbackEmail],
+  )
+
+  return { containerRef, widgetProps, getToken, reset, submit, ready }
+}

package/validate.d.ts

@@ -0,0 +1,37 @@
+export interface FieldRule {
+  required?: boolean
+  min?: number
+  max?: number
+  email?: boolean
+  /** Used in the default messages; defaults to the field's own name. */
+  label?: string
+}
+
+export type FieldMessage =
+  | string
+  | ((ctx: { value: string; limit: number; label: string; field: string }) => string)
+
+export interface FieldMessages {
+  required?: FieldMessage
+  email?: FieldMessage
+  min?: FieldMessage
+  max?: FieldMessage
+}
+
+/** `true` means "the rule the service applies to a field of this name". */
+export type FieldSpec = Record<string, FieldRule | true>
+
+/** A bare string overrides the `required` message. */
+export type MessageSpec = Record<string, FieldMessages | string>
+
+export declare const SERVER_RULES: Record<
+  'name' | 'email' | 'phone' | 'subject' | 'message',
+  FieldRule
+>
+export declare const DEFAULT_FIELDS: FieldSpec
+
+export declare function validateFields(
+  values: Record<string, string>,
+  fields?: FieldSpec,
+  messages?: MessageSpec,
+): Record<string, string>

package/validate.js

@@ -0,0 +1,91 @@
+/**
+ * Client-side validation, mirroring the service's own rules.
+ *
+ * **The server is the authority** (`internal/api/validate.go`) and every rule
+ * here is duplicated there. This exists so that nothing the service would
+ * reject costs a network round trip — because a rejection there comes back as
+ * one banner at the bottom of the form with no indication of which field caused
+ * it. Nothing here is a security control; a browser can always be bypassed.
+ */
+
+/**
+ * The service's own limits, copied from internal/api/validate.go. A site that
+ * names no fields gets exactly these.
+ */
+export const SERVER_RULES = {
+  name: { required: true, min: 2, max: 100 },
+  email: { required: true, email: true, max: 254 },
+  phone: { max: 32 },
+  subject: { max: 150 },
+  message: { required: true, min: 10, max: 5000 },
+}
+
+/** The four a contact form almost always has. */
+export const DEFAULT_FIELDS = {
+  name: SERVER_RULES.name,
+  email: SERVER_RULES.email,
+  phone: SERVER_RULES.phone,
+  message: SERVER_RULES.message,
+}
+
+// Deliberately loose. Anything stricter starts rejecting addresses that exist,
+// and the service parses the address properly anyway.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+const DEFAULTS = {
+  required: (label) => `Please enter your ${label}.`,
+  email: () => 'That does not look like a valid email address.',
+  min: (label, n) => `That looks too short — please enter at least ${n} characters.`,
+  max: (label, n) => `That is too long — ${n} characters at most.`,
+}
+
+/**
+ * Resolve one message. A site may override with a string or a function, so the
+ * dynamic ones ("three more characters") stay possible.
+ *
+ * @param {Record<string, any>|undefined} overrides
+ * @param {string} field
+ * @param {'required'|'email'|'min'|'max'} rule
+ */
+function message(overrides, field, rule, label, limit, value) {
+  const own = overrides && overrides[field]
+  const candidate = own && typeof own === 'object' ? own[rule] : rule === 'required' ? own : undefined
+  if (typeof candidate === 'function') return candidate({ value, limit, label, field })
+  if (typeof candidate === 'string') return candidate
+  return DEFAULTS[rule](label, limit)
+}
+
+/**
+ * @param {Record<string, string>} values
+ * @param {Record<string, any>} fields
+ * @param {Record<string, any>} [messages]
+ * @returns {Record<string, string>} one entry per INVALID field
+ */
+export function validateFields(values, fields = DEFAULT_FIELDS, messages) {
+  /** @type {Record<string, string>} */
+  const errors = {}
+
+  for (const [field, raw] of Object.entries(fields)) {
+    // `true` means "use the service's own rule for a field of this name".
+    const rule = raw === true ? SERVER_RULES[field] || { required: true } : raw
+    if (!rule) continue
+
+    const label = rule.label || field
+    const value = (values[field] ?? '').trim()
+
+    if (!value) {
+      if (rule.required) errors[field] = message(messages, field, 'required', label, 0, value)
+      // An empty optional field is not short, and not a bad address. Saying so
+      // is how a form ends up scolding someone for leaving Company blank.
+      continue
+    }
+    if (rule.email && !EMAIL_RE.test(value)) {
+      errors[field] = message(messages, field, 'email', label, 0, value)
+    } else if (rule.min && value.length < rule.min) {
+      errors[field] = message(messages, field, 'min', label, rule.min, value)
+    } else if (rule.max && value.length > rule.max) {
+      errors[field] = message(messages, field, 'max', label, rule.max, value)
+    }
+  }
+  return errors
+}