[PLAY-1720] Phone Number Input formatAsYouType Prop (#4125)

**What does this PR do?**
- Add `formatAsYouType`/`format_as_you_type` prop to Phone Number Input
kit
- Keep most of Phone Number Input logic the same if this prop is false
- Replace `telInputInit` state, `itiInit`, with a ref, `itiRef`, so it's
available across renders
- In React, remove formatting (dashes, spaces, parentheses) in the
`number` prop in the onChange event
- Make docs and tests

**Screenshots:**
![Screenshot 2025-01-14 at 2 04
26 PM](https://github.com/user-attachments/assets/180ea59c-e8a5-4145-96f8-fe8b44f82169)

**How to test?** Steps to confirm the desired behavior:
1. Go to /kits/phone_number_input/react#format-as-you-type
2. Type numbers and note that it formats
3. Check other doc examples
4. Review Rails versions


#### Checklist:
- [x] **LABELS** Add a label: `enhancement`, `bug`, `improvement`, `new
kit`, `deprecated`, or `breaking`. See [Changelog &
Labels](https://github.com/powerhome/playbook/wiki/Changelog-&-Labels)
for details.
- [x] **DEPLOY** I have added the `milano` label to show I'm ready for a
review.
- [x] **TESTS** I have added test coverage to my code.

Author: kangaree

playbook/app/pb_kits/playbook/pb_phone_number_input/_phone_number_input.tsx

@@ -35,6 +35,7 @@ type PhoneNumberInputProps = {
   preferredCountries?: string[],
   required?: boolean,
   value?: string,
+  formatAsYouType?: boolean,
 }
 
 enum ValidationError {
@@ -87,6 +88,7 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
     required = false,
     preferredCountries = [],
     value = "",
+    formatAsYouType = false,
   } = props
 
   const ariaProps = buildAriaProps(aria)
@@ -99,8 +101,8 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
   )
 
   const inputRef = useRef<HTMLInputElement>()
+  const itiRef = useRef<any>(null);
   const [inputValue, setInputValue] = useState(value)
-  const [itiInit, setItiInit] = useState<any>()
   const [error, setError] = useState(props.error)
   const [dropDownIsOpen, setDropDownIsOpen] = useState(false)
   const [selectedData, setSelectedData] = useState()
@@ -130,8 +132,12 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
     }
   })
 
+  const unformatNumber = (formattedNumber: any) => {
+    return formattedNumber.replace(/\D/g, "")
+  }
+
   const showFormattedError = (reason = '') => {
-    const countryName = itiInit.getSelectedCountryData().name
+    const countryName = itiRef.current.getSelectedCountryData().name
     const reasonText = reason.length > 0 ? ` (${reason})` : ''
     setError(`Invalid ${countryName} phone number${reasonText}`)
     return true
@@ -189,12 +195,12 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
   }
 
   const validateErrors = () => {
-    if (itiInit) isValid(itiInit.isValidNumber())
-    if (validateOnlyNumbers(itiInit)) return
-    if (validateTooLongNumber(itiInit)) return
-    if (validateTooShortNumber(itiInit)) return
-    if (validateUnhandledError(itiInit)) return
-    if (validateMissingAreaCode(itiInit)) return
+    if (itiRef.current) isValid(itiRef.current.isValidNumber())
+    if (validateOnlyNumbers(itiRef.current)) return
+    if (validateTooLongNumber(itiRef.current)) return
+    if (validateTooShortNumber(itiRef.current)) return
+    if (validateUnhandledError(itiRef.current)) return
+    if (validateMissingAreaCode(itiRef.current)) return
   }
 
   const getCurrentSelectedData = (itiInit: any, inputValue: string) => {
@@ -203,10 +209,16 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
 
   const handleOnChange = (evt: React.ChangeEvent<HTMLInputElement>) => {
     setInputValue(evt.target.value)
-    const phoneNumberData = getCurrentSelectedData(itiInit, evt.target.value)
+    let phoneNumberData
+    if (formatAsYouType) {
+      const formattedPhoneNumberData = getCurrentSelectedData(itiRef.current, evt.target.value)
+      phoneNumberData = {...formattedPhoneNumberData, number: unformatNumber(formattedPhoneNumberData.number)}
+    } else {
+      phoneNumberData = getCurrentSelectedData(itiRef.current, evt.target.value)
+    }
     setSelectedData(phoneNumberData)
     onChange(phoneNumberData)
-    isValid(itiInit.isValidNumber())
+    isValid(itiRef.current.isValidNumber())
   }
 
   // Separating Concerns as React Docs Recommend
@@ -230,9 +242,11 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
       onlyCountries,
       countrySearch: false,
       fixDropdownWidth: false,
-      formatAsYouType: false,
+      formatAsYouType: formatAsYouType,
     })
 
+    itiRef.current = telInputInit;
+
     inputRef.current.addEventListener("countrychange", (evt: Event) => {
       const phoneNumberData = getCurrentSelectedData(telInputInit, (evt.target as HTMLInputElement).value)
       setSelectedData(phoneNumberData)
@@ -243,7 +257,11 @@ const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefOb
     inputRef.current.addEventListener("open:countrydropdown", () => setDropDownIsOpen(true))
     inputRef.current.addEventListener("close:countrydropdown", () => setDropDownIsOpen(false))
 
-    setItiInit(telInputInit)
+    if (formatAsYouType) {
+      inputRef.current?.addEventListener("input", (evt) => {
+        handleOnChange(evt as unknown as React.ChangeEvent<HTMLInputElement>);
+      });
+    }
   }, [])
 
   let textInputProps: {[key: string]: any} = {

playbook/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_format.html.erb

@@ -0,0 +1,15 @@
+<%= pb_rails("phone_number_input", props: {
+    id: "phone_number_input",
+    format_as_you_type: true
+}) %>
+
+<%= pb_rails("button", props: {id: "clickable", text: "Save Phone Number"}) %>
+
+<%= javascript_tag do %>
+    document.querySelector('#clickable').addEventListener('click', () => {
+        const formattedPhoneNumber = document.querySelector('#phone_number_input').value
+        const unformattedPhoneNumber = formattedPhoneNumber.replace(/\D/g, "")
+
+        alert(`Formatted: ${formattedPhoneNumber}. Unformatted: ${unformattedPhoneNumber}`)
+    })
+<% end %>

playbook/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_format.jsx

@@ -0,0 +1,24 @@
+import React, { useState } from "react";
+import { PhoneNumberInput, Body } from "playbook-ui";
+
+const PhoneNumberInputFormat = (props) => {
+    const [phoneNumber, setPhoneNumber] = useState("");
+
+    const handleOnChange = ({ number }) => {
+        setPhoneNumber(number);
+    };
+
+    return (
+        <>
+            <PhoneNumberInput
+                formatAsYouType
+                id="format"
+                onChange={handleOnChange}
+                {...props}
+            />
+            {phoneNumber && <Body>Unformatted number: {phoneNumber}</Body>}
+        </>
+    );
+};
+
+export default PhoneNumberInputFormat;

playbook/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_format.md

@@ -0,0 +1 @@
+NOTE: the `number` in the React `onChange` event will not include formatting (no spaces, dashes, and parentheses). For Rails, the `value` will include formatting and its value must be sanitized manually. 

playbook/app/pb_kits/playbook/pb_phone_number_input/docs/example.yml

@@ -8,10 +8,12 @@ examples:
   - phone_number_input_validation: Form Validation
   - phone_number_input_clear_field: Clearing the Input Field
   - phone_number_input_access_input_element: Accessing the Input Element
+  - phone_number_input_format: Format as You Type
 
   rails:
   - phone_number_input_default: Default
   - phone_number_input_preferred_countries: Preferred Countries
   - phone_number_input_initial_country: Initial Country
   - phone_number_input_only_countries: Limited Countries
-  - phone_number_input_validation: Form Validation
+  - phone_number_input_validation: Form Validation
+  - phone_number_input_format: Format as You Type

playbook/app/pb_kits/playbook/pb_phone_number_input/docs/index.js

@@ -5,3 +5,4 @@ export { default as PhoneNumberInputOnlyCountries } from './_phone_number_input_
 export { default as PhoneNumberInputValidation } from './_phone_number_input_validation'
 export { default as PhoneNumberInputClearField } from './_phone_number_input_clear_field'
 export { default as PhoneNumberInputAccessInputElement } from './_phone_number_input_access_input_element'
+export { default as PhoneNumberInputFormat } from './_phone_number_input_format'

playbook/app/pb_kits/playbook/pb_phone_number_input/phone_number_input.rb

@@ -21,6 +21,8 @@ class PhoneNumberInput < Playbook::KitBase
                    default: ""
       prop :value, type: Playbook::Props::String,
                    default: ""
+      prop :format_as_you_type, type: Playbook::Props::Boolean,
+                                default: false
 
       def classname
         generate_classname("pb_phone_number_input")
@@ -32,6 +34,7 @@ def phone_number_input_options
           dark: dark,
           disabled: disabled,
           error: error,
+          formatAsYouType: format_as_you_type,
           initialCountry: initial_country,
           label: label,
           name: name,

playbook/app/pb_kits/playbook/pb_phone_number_input/phone_number_input.test.js

@@ -1,5 +1,5 @@
 import React from "react";
-import { render, screen } from "../utilities/test-utils";
+import { render, screen, act } from "../utilities/test-utils";
 import PhoneNumberInput from "./_phone_number_input";
 
 const testId = "phoneNumberInput";
@@ -120,3 +120,22 @@ test("should trigger callback", () => {
 
   expect(handleOnValidate).toBeCalledWith(true)
 });
+
+test("should format phone number as '555-555-5555' with formatAsYouType and 'us' country", () => {
+    const props = {
+        initialCountry: 'us',
+        formatAsYouType: true,
+        id: testId,
+    };
+
+    render(<PhoneNumberInput {...props} />);
+    
+    const input = screen.getByRole("textbox");
+    
+    act(() => {
+        input.value = "5555555555";
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+
+    expect(input.value).toBe("555-555-5555");
+});

playbook/spec/pb_kits/playbook/kits/phone_number_input_spec.rb

@@ -14,6 +14,7 @@
   it { is_expected.to define_array_prop(:preferred_countries).with_default([]) }
   it { is_expected.to define_prop(:error).with_default("") }
   it { is_expected.to define_prop(:value).with_default("") }
+  it { is_expected.to define_boolean_prop(:format_as_you_type).with_default(false) }
 
   describe "#classname" do
     it "returns namespaced class name", :aggregate_failures do