From ff5c7adc962832feb7082778e75f8ef14b0bfc76 Mon Sep 17 00:00:00 2001
From: Brent Rager <brent@rager.tech>
Date: Mon, 29 Jun 2026 08:48:48 -0400
Subject: [PATCH] SMOODEV-2153: Phone formatting + validation on pre-chat form
 (libphonenumber-js, US)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The pre-chat form's Phone field had no client-side formatting or validation —
visitors typed free-form numbers and only the backend's E.164 normalization
(smooai #2138) caught problems. This adds the frontend half so the field is
self-explaining and the value we send is already canonical when it parses.

- As-you-type formatting via AsYouType('US'). To avoid the standard AsYouType
  caret caveat (full-string reformat jumps the caret to the end), we only
  rewrite the value when the caret is at the end (the append-a-digit case) and
  never on a deletion — backspacing formatting characters works naturally.
- Inline, themed validity hint driven by isValidPhoneNumber(value,'US'). Empty
  stays neutral (the field is optional unless requirePhone).
- On submit: block + hint when requirePhone and the number is invalid; allow
  submit when optional. Send canonical E.164 (parsePhoneNumber.number) when it
  parses, else the raw value (the backend re-parses + normalizes/nulls).
- Autofill preserved: type="tel", autocomplete="tel", and the implicit <label>
  are unchanged, and we reformat/validate on `change` too so a browser-autofilled
  value is handled.
- Standalone IIFE bundle inlines libphonenumber-js/min (added to
  deps.alwaysBundle) — without it the IIFE left a bare `libphonenumber_js_min`
  external reference that would ReferenceError in a plain <script> embed.

Bundle-size impact (standalone IIFE chat-widget.global.js): 140 kB → 438 kB raw
(39 kB → 92 kB gzip) from the /min metadata. The recommended loader embed
lazy-loads this past the host's LCP. ESM index.js (lib externalized) is unchanged.

Version bumped to 0.8.0 (minor — new validation behavior) + changeset added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AxL4LdeChNivUCZM6No2NJ
---
 .changeset/phone-validation-pre-chat.md |  12 +++
 package.json                            |   3 +-
 pnpm-lock.yaml                          |   8 ++
 src/element.test.ts                     | 134 ++++++++++++++++++++++++
 src/element.ts                          | 123 +++++++++++++++++++++-
 src/styles.ts                           |  18 ++++
 tsdown.config.ts                        |  11 +-
 7 files changed, 300 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/phone-validation-pre-chat.md

diff --git a/.changeset/phone-validation-pre-chat.md b/.changeset/phone-validation-pre-chat.md
new file mode 100644
index 0000000..86558a3
--- /dev/null
+++ b/.changeset/phone-validation-pre-chat.md
@@ -0,0 +1,12 @@
+---
+'@smooai/chat-widget': minor
+---
+
+Pre-chat phone field now formats and validates as you type (libphonenumber-js, US default region).
+
+- **As-you-type formatting** via `AsYouType('US')` — appended digits are formatted live (e.g. `(213) 373-4253`). The formatter only rewrites when the caret is at the end and never while deleting, so backspacing the formatting characters works naturally.
+- **Inline validity hint** driven by `isValidPhoneNumber(value, 'US')` — a subtle, themed valid/invalid state on the field plus a small hint span. An empty field stays neutral (the field is optional unless `requirePhone`).
+- **On submit**: when `requirePhone` is set and the number is invalid, submission is blocked and the hint is shown; when optional, submission proceeds. A valid number is sent as canonical **E.164** (`parsePhoneNumber(value, 'US').number`), falling back to the raw value when it does not parse (the backend re-parses and normalizes/nulls authoritatively — SMOODEV-2153).
+- Autofill is preserved: `type="tel"`, `autocomplete="tel"`, and the implicit `<label>` are unchanged, and the value is also reformatted/validated on `change` so a browser-autofilled number gets handled too.
+
+The standalone IIFE bundle now inlines `libphonenumber-js/min` (added to `deps.alwaysBundle`) so a plain `<script>` embed has no undefined-global reference at load.
diff --git a/package.json b/package.json
index 9d393a4..aa663c3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@smooai/chat-widget",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "description": "Embeddable AI chat as a framework-light web component — the Aurora Glass design, streaming replies, grounded sources, and per-brand theming. Speaks the smooth-operator WebSocket protocol.",
     "license": "MIT",
     "author": "SmooAI",
@@ -71,6 +71,7 @@
     },
     "dependencies": {
         "@smooai/smooth-operator": "^1.8.0",
+        "libphonenumber-js": "^1.13.7",
         "zustand": "^5.0.14"
     },
     "devDependencies": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bd93d8f..9c45182 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12,6 +12,9 @@ importers:
       '@smooai/smooth-operator':
         specifier: ^1.8.0
         version: 1.8.0
+      libphonenumber-js:
+        specifier: ^1.13.7
+        version: 1.13.7
       zustand:
         specifier: ^5.0.14
         version: 5.0.14
@@ -1004,6 +1007,9 @@ packages:
   jsonfile@4.0.0:
     resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
 
+  libphonenumber-js@1.13.7:
+    resolution: {integrity: sha512-rvr3HIMdOgzhz1RFGjftji+wjoAFlzhqCNqJOU/MKTZQ8d9NZxAR/tI+0weDicyoucqVR0U1GCniqHJ0f8aM2A==}
+
   locate-path@5.0.0:
     resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==}
     engines: {node: '>=8'}
@@ -2419,6 +2425,8 @@ snapshots:
     optionalDependencies:
       graceful-fs: 4.2.11
 
+  libphonenumber-js@1.13.7: {}
+
   locate-path@5.0.0:
     dependencies:
       p-locate: 4.1.0
diff --git a/src/element.test.ts b/src/element.test.ts
index ff077a9..e70a863 100644
--- a/src/element.test.ts
+++ b/src/element.test.ts
@@ -116,4 +116,138 @@ describe('<smooth-agent-chat> render', () => {
         expect(overlay?.classList.contains('hidden')).toBe(true);
         expect(overlay?.childElementCount).toBe(0);
     });
+
+    describe('pre-chat phone field (libphonenumber-js, US default)', () => {
+        // Mount with the phone field present (requireName forces the gate; phone
+        // shows by default via collectPhone). Returns the input + its field wrapper.
+        function mountPhone(cfg: Record<string, unknown> = {}): {
+            el: HTMLElement;
+            sr: ShadowRoot;
+            input: HTMLInputElement;
+            field: HTMLElement;
+            hint: HTMLElement;
+        } {
+            const el = mountCfg({ requireName: true, ...cfg });
+            const sr = el.shadowRoot!;
+            const input = sr.querySelector('input[name="phone"]') as HTMLInputElement;
+            const field = input.closest('.pc-field') as HTMLElement;
+            const hint = field.querySelector('.pc-hint') as HTMLElement;
+            return { el, sr, input, field, hint };
+        }
+
+        // jsdom doesn't synthesize InputEvent.inputType; pass it explicitly.
+        function type(input: HTMLInputElement, value: string, inputType = 'insertText'): void {
+            input.value = value;
+            input.setSelectionRange(value.length, value.length);
+            input.dispatchEvent(new InputEvent('input', { bubbles: true, inputType }));
+        }
+
+        // Stub the controller seam so submit captures setUserInfo without a real
+        // WebSocket. `disconnect` is needed for the afterEach teardown (the element's
+        // disconnectedCallback calls it).
+        function stubController(el: HTMLElement): Array<Record<string, unknown>> {
+            const captured: Array<Record<string, unknown>> = [];
+            (el as unknown as { controller: unknown }).controller = {
+                setUserInfo: (i: Record<string, unknown>) => captured.push(i),
+                connect: () => Promise.resolve(),
+                disconnect: () => {},
+            };
+            return captured;
+        }
+
+        it('preserves autofill-critical attributes: type=tel, autocomplete=tel, and the implicit <label>', () => {
+            const { input, field } = mountPhone();
+            expect(input.type).toBe('tel');
+            expect(input.getAttribute('autocomplete')).toBe('tel');
+            // Implicit label association: the input is nested inside its <label>.
+            expect(field.tagName).toBe('LABEL');
+            expect(field.querySelector('span')?.textContent).toBe('Phone');
+            expect(field.contains(input)).toBe(true);
+        });
+
+        it('formats a US number as-you-type when typing at the end', () => {
+            const { input } = mountPhone();
+            type(input, '2133734253');
+            // libphonenumber-js AsYouType('US') → "(213) 373-4253".
+            expect(input.value).toBe('(213) 373-4253');
+        });
+
+        it('flags a garbage number invalid and a good number valid via the inline hint', () => {
+            const { input, field, hint } = mountPhone();
+            type(input, '12'); // too short → invalid
+            expect(field.classList.contains('invalid')).toBe(true);
+            expect(field.classList.contains('valid')).toBe(false);
+            expect(hint.textContent).toBeTruthy();
+
+            type(input, '2133734253'); // valid US number
+            expect(field.classList.contains('valid')).toBe(true);
+            expect(field.classList.contains('invalid')).toBe(false);
+            expect(hint.textContent).toBe('');
+        });
+
+        it('empty phone is neutral (no valid/invalid) — the field is optional', () => {
+            const { input, field } = mountPhone();
+            type(input, '2133734253');
+            type(input, '', 'deleteContentBackward');
+            expect(field.classList.contains('valid')).toBe(false);
+            expect(field.classList.contains('invalid')).toBe(false);
+        });
+
+        it('does not reformat while the user is deleting characters', () => {
+            const { input } = mountPhone();
+            type(input, '2133734253'); // → "(213) 373-4253"
+            // Simulate a backspace that removed the trailing digit.
+            type(input, '(213) 373-425', 'deleteContentBackward');
+            // Value is left as the user typed it — we don't re-add formatting.
+            expect(input.value).toBe('(213) 373-425');
+        });
+
+        it('reformats + validates a browser-autofilled value on `change`', () => {
+            const { input, field } = mountPhone();
+            input.value = '2133734253';
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+            expect(input.value).toBe('(213) 373-4253');
+            expect(field.classList.contains('valid')).toBe(true);
+        });
+
+        it('sends E.164 on submit when the (formatted) number is valid', () => {
+            const { el, sr, input } = mountPhone();
+            const captured = stubController(el);
+            (sr.querySelector('input[name="name"]') as HTMLInputElement).value = 'Ada';
+            type(input, '(213) 373-4253');
+            (sr.querySelector('.pc-form') as HTMLFormElement).dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            expect(captured).toHaveLength(1);
+            expect(captured[0]?.phone).toBe('+12133734253');
+        });
+
+        it('blocks submit on an invalid number when requirePhone is set', () => {
+            const { el, sr, input, field } = mountPhone({ requirePhone: true });
+            const captured = stubController(el);
+            (sr.querySelector('input[name="name"]') as HTMLInputElement).value = 'Ada';
+            type(input, '12'); // invalid
+            const form = sr.querySelector('.pc-form') as HTMLFormElement;
+            // reportValidity is unavailable in jsdom for this path; stub to true so we
+            // exercise our own phone gate rather than the native required check.
+            form.reportValidity = () => true;
+            form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            expect(captured).toHaveLength(0);
+            expect(field.classList.contains('invalid')).toBe(true);
+        });
+
+        it('allows submit with the raw value when phone is optional + unparseable', () => {
+            const { el, sr, input } = mountPhone();
+            const captured = stubController(el);
+            (sr.querySelector('input[name="name"]') as HTMLInputElement).value = 'Ada';
+            type(input, '12'); // invalid but optional — formatter renders it "1 2"
+            const form = sr.querySelector('.pc-form') as HTMLFormElement;
+            form.reportValidity = () => true;
+            form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+            // Optional → submit proceeds; the unparseable value is forwarded as-is
+            // (the field's current, as-you-type-formatted text) so the backend
+            // normalizes/nulls authoritatively.
+            expect(captured).toHaveLength(1);
+            expect(captured[0]?.phone).toBe(input.value);
+            expect(captured[0]?.phone).not.toMatch(/^\+/); // not E.164 — it didn't parse
+        });
+    });
 });
diff --git a/src/element.ts b/src/element.ts
index cc7f62a..020caf2 100644
--- a/src/element.ts
+++ b/src/element.ts
@@ -14,6 +14,7 @@
  *   <smooth-agent-chat endpoint="ws://localhost:8787/ws" agent-id="…"></smooth-agent-chat>
  * or programmatically via {@link mountChatWidget}.
  */
+import { AsYouType, isValidPhoneNumber, parsePhoneNumber } from 'libphonenumber-js/min';
 import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
 import { needsUserInfo, resolveConfig } from './config.js';
 import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt } from './conversation.js';
@@ -23,6 +24,31 @@ import { buildStyles } from './styles.js';
 
 export const ELEMENT_TAG = 'smooth-agent-chat';
 
+/**
+ * Default region for phone parsing/formatting on the pre-chat form. The widget
+ * is US-first; the backend does the authoritative E.164 normalization (SMOODEV-2153),
+ * so this only governs the as-you-type display + the inline validity hint and the
+ * best-effort E.164 we send when the number already parses as valid.
+ */
+const PHONE_DEFAULT_REGION = 'US' as const;
+
+/**
+ * Best-effort E.164 for an as-typed phone number. Returns the canonical
+ * `+1…` form when the value parses to a valid number in {@link PHONE_DEFAULT_REGION},
+ * otherwise `null` (caller falls back to sending the raw value — the backend
+ * re-parses and normalizes/nulls authoritatively).
+ */
+function phoneToE164(value: string): string | null {
+    const v = value.trim();
+    if (!v) return null;
+    try {
+        if (!isValidPhoneNumber(v, PHONE_DEFAULT_REGION)) return null;
+        return parsePhoneNumber(v, PHONE_DEFAULT_REGION).number;
+    } catch {
+        return null;
+    }
+}
+
 const OBSERVED = ['endpoint', 'agent-id', 'agent-name', 'placeholder', 'greeting', 'start-open', 'mode'] as const;
 
 /**
@@ -270,8 +296,10 @@ export class SmoothAgentChatElement extends HTMLElement {
         // Phone is collected by default (optional unless requirePhone). Consent
         // checkboxes default to shown, explicit + unchecked (ADR-048 §a/§3).
         const showPhone = resolved.requirePhone || resolved.collectPhone;
-        const field = (name: string, type: string, label: string, autocomplete: string, required: boolean) =>
-            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}"${required ? ' required' : ''} /></label>`;
+        const field = (name: string, type: string, label: string, autocomplete: string, required: boolean, hint = false) =>
+            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}"${required ? ' required' : ''} />${
+                hint ? '<span class="pc-hint" aria-live="polite"></span>' : ''
+            }</label>`;
         const consentBox = (name: string, label: string) =>
             `<label class="pc-consent"><input name="${name}" type="checkbox" /><span>${escapeHtml(label)}</span></label>`;
         const consentHtml = resolved.collectConsent
@@ -289,7 +317,7 @@ export class SmoothAgentChatElement extends HTMLElement {
                 <form class="pc-form" novalidate>
                     ${resolved.requireName ? field('name', 'text', 'Name', 'name', true) : ''}
                     ${resolved.requireEmail ? field('email', 'email', 'Email', 'email', true) : ''}
-                    ${showPhone ? field('phone', 'tel', 'Phone', 'tel', resolved.requirePhone) : ''}
+                    ${showPhone ? field('phone', 'tel', 'Phone', 'tel', resolved.requirePhone, true) : ''}
                     ${consentHtml}
                     <button type="submit" class="pc-submit">Start chat</button>
                 </form>
@@ -351,6 +379,12 @@ export class SmoothAgentChatElement extends HTMLElement {
             this.handlePrechatSubmit(pcForm as HTMLFormElement);
         });
 
+        // Live phone formatting + validity hint (libphonenumber-js, US default).
+        // The implicit <label>, type="tel", and autocomplete="tel" from field()
+        // are preserved — autofill keeps working — and we also reformat on
+        // `change` so a browser-autofilled value gets formatted/validated too.
+        this.wirePhoneField(pcForm as HTMLFormElement | null);
+
         // Cross-device "Restore my chats": open the panel + start the email entry.
         // AWAIT connect() before showing the email step so a `sessionId` exists by
         // the time the visitor submits — otherwise request-otp could go out with no
@@ -651,16 +685,97 @@ export class SmoothAgentChatElement extends HTMLElement {
         }
     }
 
+    /**
+     * Wire as-you-type formatting + an inline validity hint onto the pre-chat
+     * phone input (libphonenumber-js, US default region). Autofill is preserved:
+     * the input keeps its `type="tel"` + `autocomplete="tel"` + implicit <label>,
+     * and we also reformat on `change` so a browser-autofilled value gets
+     * formatted/validated too.
+     *
+     * As-you-type caret note: `AsYouType` reformats the entire string, which
+     * moves the caret to the end on a mid-string edit. To avoid fighting the
+     * user, we only rewrite the value when the caret is at the end (the typical
+     * append-a-digit case) and never on a deletion — so backspacing the
+     * formatting characters works naturally.
+     */
+    private wirePhoneField(form: HTMLFormElement | null): void {
+        const input = form?.querySelector('input[name="phone"]') as HTMLInputElement | null;
+        if (!input) return;
+        const hint = input.parentElement?.querySelector('.pc-hint') as HTMLElement | null;
+
+        const updateHint = () => {
+            const v = input.value.trim();
+            const field = input.closest('.pc-field');
+            if (!v) {
+                // Empty is neutral — the field is optional unless requirePhone.
+                field?.classList.remove('valid', 'invalid');
+                if (hint) hint.textContent = '';
+                return;
+            }
+            const ok = isValidPhoneNumber(v, PHONE_DEFAULT_REGION);
+            field?.classList.toggle('valid', ok);
+            field?.classList.toggle('invalid', !ok);
+            if (hint) hint.textContent = ok ? '' : 'Enter a valid phone number';
+        };
+
+        const reformat = () => {
+            const atEnd = input.selectionStart === input.value.length && input.selectionEnd === input.value.length;
+            // Only reformat when appending at the end; never fight a mid-string
+            // edit or a deletion (see the caret note above).
+            if (atEnd) {
+                const formatted = new AsYouType(PHONE_DEFAULT_REGION).input(input.value);
+                // Avoid clobbering when the user is deleting: only grow/normalize,
+                // not when the formatter would re-add a character they just removed.
+                if (formatted.length >= input.value.length) {
+                    input.value = formatted;
+                }
+            }
+            updateHint();
+        };
+
+        input.addEventListener('input', (ev) => {
+            const ie = ev as InputEvent;
+            // Don't reformat while deleting — let the user clear characters freely.
+            if (typeof ie.inputType === 'string' && ie.inputType.startsWith('delete')) {
+                updateHint();
+                return;
+            }
+            reformat();
+        });
+        // Browser autofill / paste-then-blur lands here; format + validate it too.
+        input.addEventListener('change', reformat);
+    }
+
     /** Collect identity + consent from the pre-chat form, then drop into the chat view. */
     private handlePrechatSubmit(form: HTMLFormElement): void {
         if (!form.reportValidity()) return;
         const data = new FormData(form);
         const val = (k: string) => ((data.get(k) as string | null)?.trim() || undefined);
         const checked = (k: string) => data.get(k) === 'on';
+
+        // Phone: when required, block on an invalid number and surface the hint.
+        // When optional, allow submit — the backend normalizes/nulls authoritatively.
+        const rawPhone = val('phone');
+        const phoneInput = form.querySelector('input[name="phone"]') as HTMLInputElement | null;
+        if (rawPhone && phoneInput && !isValidPhoneNumber(rawPhone, PHONE_DEFAULT_REGION)) {
+            const required = phoneInput.hasAttribute('required');
+            const field = phoneInput.closest('.pc-field');
+            field?.classList.add('invalid');
+            const hint = field?.querySelector('.pc-hint');
+            if (hint) hint.textContent = 'Enter a valid phone number';
+            if (required) {
+                phoneInput.focus();
+                return;
+            }
+        }
+        // Prefer canonical E.164 when it parses; fall back to the raw value
+        // otherwise (the backend re-parses + normalizes either way).
+        const phone = rawPhone ? (phoneToE164(rawPhone) ?? rawPhone) : undefined;
+
         this.controller?.setUserInfo({
             name: val('name'),
             email: val('email'),
-            phone: val('phone'),
+            phone,
             consent: { emailOptIn: checked('emailOptIn'), smsOptIn: checked('smsOptIn') },
         });
         this.userInfoSatisfied = true;
diff --git a/src/styles.ts b/src/styles.ts
index 1e7b7eb..f66109d 100644
--- a/src/styles.ts
+++ b/src/styles.ts
@@ -515,6 +515,24 @@ export function buildStyles(theme: ResolvedTheme, mode: ChatWidgetMode = 'popove
     border-color: color-mix(in srgb, var(--sac-primary) 60%, transparent);
     box-shadow: 0 0 0 4px color-mix(in srgb, var(--sac-primary) 14%, transparent);
 }
+/* Inline phone validity — subtle, themed. Empty stays neutral (optional field). */
+.pc-field.valid input {
+    border-color: color-mix(in srgb, var(--sac-primary) 55%, #2faa6a 45%);
+}
+.pc-field.invalid input {
+    border-color: color-mix(in srgb, #e2566b 62%, var(--sac-border) 38%);
+}
+.pc-field.invalid input:focus {
+    box-shadow: 0 0 0 4px color-mix(in srgb, #e2566b 16%, transparent);
+}
+.pc-field .pc-hint {
+    min-height: 13px;
+    margin-top: 1px;
+    font-size: 11.5px;
+    font-weight: 500;
+    line-height: 1.2;
+    color: color-mix(in srgb, #e2566b 78%, var(--sac-text) 22%);
+}
 .pc-submit {
     margin-top: 4px;
     border: none;
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 8a1c98c..d73db55 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -45,10 +45,13 @@ export default defineConfig([
         platform: 'browser',
         target: browserTarget,
         globalName: 'SmoothAgentChat',
-        // Bundle the protocol client AND zustand into the standalone global — a
-        // plain `<script>` embed has no module resolver, so every runtime dep must
-        // be inlined or it resolves to an undefined global at load.
-        deps: { alwaysBundle: [/@smooai\/smooth-operator/, /^zustand/] },
+        // Bundle the protocol client, zustand, AND libphonenumber-js into the
+        // standalone global — a plain `<script>` embed has no module resolver, so
+        // every runtime dep must be inlined or it resolves to an undefined global
+        // at load. (Without the libphonenumber-js entry the IIFE leaves a bare
+        // `libphonenumber_js_min` external reference → ReferenceError on the
+        // pre-chat form's phone validation. SMOODEV-2153.)
+        deps: { alwaysBundle: [/@smooai\/smooth-operator/, /^zustand/, /^libphonenumber-js/] },
         alias: {
             '@smooai/smooth-operator': agentClientEntry,
         },