@qaflo/forms-client 1.2.0 → 1.3.0

package/README.md

@@ -109,6 +109,12 @@ const { formProps, fieldProps, errors, composed } = forms.useContactForm({
     // A shape the service has no opinion on. Checked only when the field has
     // something in it, so an optional field with a pattern stays optional.
     licence: { pattern: /^[0-9]{6}$/ },
+    // And when no set of rules says it, write the function. It receives the
+    // whole form, and its message wins over the rules above.
+    area: {
+      check: (value, all) =>
+        all.enquiry === 'delivery' && !value ? 'We need an area to deliver to.' : undefined,
+    },
   },
 
   // The rules are the service's. The voice is yours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaflo/forms-client",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Client half of the shared qaflo contact-form service: transport, Turnstile lifecycle and visitor-facing status messages.",
   "license": "MIT",
   "type": "module",

package/validate.d.ts

@@ -5,6 +5,12 @@ export interface FieldRule {
   email?: boolean
   /** A site-specific shape. Checked only when the field is non-empty. */
   pattern?: RegExp
+  /**
+   * Anything the rules above cannot express. Returns the message, or
+   * undefined to pass. Runs only when the field is non-empty, and its message
+   * wins over every other rule.
+   */
+  check?: (value: string, values: Record<string, string>) => string | undefined
   /** Used in the default messages; defaults to the field's own name. */
   label?: string
 }

package/validate.js

@@ -80,6 +80,18 @@ export function validateFields(values, fields = DEFAULT_FIELDS, messages) {
       // is how a form ends up scolding someone for leaving Company blank.
       continue
     }
+    // An escape hatch for a rule this cannot express declaratively — a phone
+    // check with a different sentence for letters, for too short and for too
+    // long. It runs after the empty check, so an optional field stays optional,
+    // and it owns the field's message outright when it returns one.
+    if (rule.check) {
+      const own = rule.check(value, values)
+      if (own) {
+        errors[field] = own
+        continue
+      }
+    }
+
     if (rule.email && !EMAIL_RE.test(value)) {
       errors[field] = message(messages, field, 'email', label, 0, value)
     } else if (rule.pattern && !rule.pattern.test(value)) {