playbook_ui 12.26.0 → 12.26.1.pre.alpha.PLAY860PhoneNumInputOptions836

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

@@ -1,12 +1,17 @@
-import React, { useEffect, useRef, useState } from 'react'
+import React, { forwardRef, useEffect, useRef, useState, useImperativeHandle } from 'react'
 import classnames from 'classnames'
-import { buildAriaProps, buildCss, buildDataProps } from '../utilities/props'
-import { globalProps } from '../utilities/globalProps'
+
 import intlTelInput from 'intl-tel-input'
 import 'intl-tel-input/build/css/intlTelInput.css'
-import TextInput from '../pb_text_input/_text_input'
 import 'intl-tel-input/build/js/utils.js'
 
+import { buildAriaProps, buildCss, buildDataProps } from '../utilities/props'
+import { globalProps } from '../utilities/globalProps'
+
+import TextInput from '../pb_text_input/_text_input'
+import { Callback } from '../types'
+import { isEmpty } from '../utilities/object'
+
 declare global {
   interface Window {
     intlTelInputGlobals: any
@@ -19,20 +24,25 @@ type PhoneNumberInputProps = {
   dark?: boolean,
   data?: { [key: string]: string },
   disabled?: boolean,
+  error?: string,
   id?: string,
   initialCountry?: string,
   isValid?: (valid: boolean) => void,
   label?: string,
   name?: string,
   onChange?: (e: React.FormEvent<HTMLInputElement>) => void,
+  onValidate?: Callback<boolean, void>,
   onlyCountries: string[],
   preferredCountries?: string[],
+  required?: boolean,
   value?: string,
 }
 
 enum ValidationError {
   TooShort = 2,
   TooLong = 3,
+  MissingAreaCode = 4,
+  SomethingWentWrong = -99
 }
 
 const formatToGlobalCountryName = (countryName: string) => {
@@ -40,10 +50,10 @@ const formatToGlobalCountryName = (countryName: string) => {
 }
 
 const formatAllCountries = () => {
-  let countryData = window.intlTelInputGlobals.getCountryData()
+  const countryData = window.intlTelInputGlobals.getCountryData()
 
   for (let i = 0; i < countryData.length; i++) {
-    let country = countryData[i]
+    const country = countryData[i]
     country.name = formatToGlobalCountryName(country.name)
   }
 }
@@ -54,7 +64,7 @@ const containOnlyNumbers = (value: string) => {
   return /^[()+\-\ .\d]*$/g.test(value)
 }
 
-const PhoneNumberInput = (props: PhoneNumberInputProps) => {
+const PhoneNumberInput = (props: PhoneNumberInputProps, ref?: React.MutableRefObject<unknown>) => {
   const {
     aria = {},
     className,
@@ -71,7 +81,9 @@ const PhoneNumberInput = (props: PhoneNumberInputProps) => {
     onChange = () => {
       void 0
     },
+    onValidate = () => null,
     onlyCountries = [],
+    required = false,
     preferredCountries = [],
     value = "",
   } = props
@@ -87,39 +99,100 @@ const PhoneNumberInput = (props: PhoneNumberInputProps) => {
   const inputRef = useRef<HTMLInputElement>()
   const [inputValue, setInputValue] = useState(value)
   const [itiInit, setItiInit] = useState<any>()
-  const [error, setError] = useState('')
+  const [error, setError] = useState(props.error)
   const [dropDownIsOpen, setDropDownIsOpen] = useState(false)
   const [selectedData, setSelectedData] = useState()
 
+  useEffect(() => {
+    if (error?.length > 0) {
+      onValidate(false)
+    } else {
+      onValidate(true)
+    }
+  }, [error, onValidate])
+
+  /*
+    useImperativeHandle exposes the kit's input element to a parent component via a ref.
+    See the Playbook docs for use cases.
+    Read: https://react.dev/reference/react/useImperativeHandle
+  */
+  useImperativeHandle(ref, () => {
+    return {
+      clearField() {
+        setInputValue("")
+        setError("")
+      },
+      inputNode() {
+        return inputRef.current
+      }
+    }
+  })
+
+  const showFormattedError = (reason = '') => {
+    const countryName = itiInit.getSelectedCountryData().name
+    const reasonText = reason.length > 0 ? ` (${reason})` : ''
+    setError(`Invalid ${countryName} phone number${reasonText}`)
+    return true
+  }
+
   const validateTooLongNumber = (itiInit: any) => {
-    const error = itiInit.getValidationError()
+    if (!itiInit) return
+    if (itiInit.getValidationError() === ValidationError.TooLong) {
+      return showFormattedError('too long')
+    } else {
+      setError('')
+    }
+  }
 
-    if (error === ValidationError.TooLong) {
-      const countryName = itiInit.getSelectedCountryData().name
-      setError(`Invalid ${countryName} phone number (too long)`)
+  const validateTooShortNumber = (itiInit: any) => {
+    if (!itiInit) return
+    if (itiInit.getValidationError() === ValidationError.TooShort) {
+      return showFormattedError('too short')
     } else {
-      setError("")
+      if (inputValue.length === 1) {
+        return showFormattedError('too short')
+      } else {
+        setError('')
+      }
     }
   }
 
-  const validateTooShortNumber = () => {
-    const error = itiInit.getValidationError()
+  const validateOnlyNumbers = (itiInit: any) => {
+    if (!itiInit) return
+    if (inputValue && !containOnlyNumbers(inputValue)) {
+      return showFormattedError('enter numbers only')
+    }
+  }
 
-    if (error === ValidationError.TooShort) {
-      const countryName = itiInit.getSelectedCountryData().name
-      setError(`Invalid ${countryName} phone number (too short)`)
+  const validateUnhandledError = (itiInit: any) => {
+    if (!required || !itiInit) return
+    if (itiInit.getValidationError() === ValidationError.SomethingWentWrong) {
+      if (inputValue.length === 1) {
+        return showFormattedError('too short')
+      } else if (inputValue.length === 0) {
+        setError('Missing phone number')
+        return true
+      } else {
+        return showFormattedError()
+      }
     }
   }
 
-  const validateOnlyNumbers = () => {
-    if (inputValue && !containOnlyNumbers(inputValue)) {
-      setError("Invalid phone number. Enter numbers only.")
+  const validateMissingAreaCode = (itiInit: any) => {
+    if (!required || !itiInit) return
+    if (itiInit.getValidationError() === ValidationError.MissingAreaCode) {
+      showFormattedError('missing area code')
+      return true
     }
   }
 
   const validateErrors = () => {
-    validateTooShortNumber()
-    validateOnlyNumbers()
+    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
   }
 
   const getCurrentSelectedData = (itiInit: any, inputValue: string) => {
@@ -128,7 +201,6 @@ const PhoneNumberInput = (props: PhoneNumberInputProps) => {
 
   const handleOnChange = (evt: React.ChangeEvent<HTMLInputElement>) => {
     setInputValue(evt.target.value)
-    validateTooLongNumber(itiInit)
     const phoneNumberData = getCurrentSelectedData(itiInit, evt.target.value)
     setSelectedData(phoneNumberData)
     onChange(phoneNumberData)
@@ -137,25 +209,24 @@ const PhoneNumberInput = (props: PhoneNumberInputProps) => {
 
   // Separating Concerns as React Docs Recommend
   // This also Fixes things for our react_component rendering on the Rails Side
-  useEffect(() => {
-    formatAllCountries()
-  }, [])
+  useEffect(formatAllCountries, [])
 
   useEffect(() => {
-    const telInputInit = new intlTelInput(inputRef.current, {
+    const telInputInit = intlTelInput(inputRef.current, {
       separateDialCode: true,
       preferredCountries,
       allowDropdown: !disabled,
+      autoInsertDialCode: false,
       initialCountry,
       onlyCountries,
-    }
-    )
+      utilsScript: "intl-tel-input/build/js/utils.js"
+    })
 
     inputRef.current.addEventListener("countrychange", (evt: Event) => {
-      validateTooLongNumber(telInputInit)
       const phoneNumberData = getCurrentSelectedData(telInputInit, (evt.target as HTMLInputElement).value)
       setSelectedData(phoneNumberData)
       onChange(phoneNumberData)
+      validateErrors()
     })
 
     inputRef.current.addEventListener("open:countrydropdown", () => setDropDownIsOpen(true))
@@ -164,24 +235,40 @@ const PhoneNumberInput = (props: PhoneNumberInputProps) => {
     setItiInit(telInputInit)
   }, [])
 
+  let textInputProps: {[key: string]: any} = {
+    className: dropDownIsOpen ? 'dropdown_open' : '',
+    dark,
+    "data-phone-number": JSON.stringify(selectedData),
+    disabled,
+    error,
+    type: 'tel',
+    id,
+    label,
+    name,
+    onBlur: validateErrors,
+    onChange: handleOnChange,
+    value: inputValue
+  }
+
+  let wrapperProps: Record<string, unknown> = { className: classes }
+
+  if (!isEmpty(aria)) textInputProps = {...textInputProps, ...ariaProps}
+  if (!isEmpty(data)) wrapperProps = {...wrapperProps, ...dataProps}
+  if (required) textInputProps.required = true
+
   return (
-    <div {...ariaProps} {...dataProps} className={classes}>
+    <div {...wrapperProps}>
       <TextInput
-        className={dropDownIsOpen ? 'dropdown_open' : ''}
-        dark={dark}
-        data-phone-number={JSON.stringify(selectedData)}
-        disabled={disabled}
-        error={error}
-        id={id}
-        label={label}
-        name={name}
-        onBlur={() => validateErrors()}
-        onChange={handleOnChange}
-        ref={inputRef}
-        value={inputValue}
+          ref={
+            inputNode => {
+              ref ? ref.current = inputNode : null
+              inputRef.current = inputNode
+            }
+          }
+          {...textInputProps}
       />
     </div>
   )
 }
 
-export default PhoneNumberInput
+export default forwardRef(PhoneNumberInput)

data/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_access_input_element.jsx

@@ -0,0 +1,26 @@
+import React, { useEffect, useRef } from 'react'
+import { Body, PhoneNumberInput } from '../..'
+
+const PhoneNumberInputAccessInputElement = (props) => {
+    // 1. Create a ref - this accesses the kit's input element.
+    const ref = useRef()
+
+    // 2. Add any event listener to ref.current.inputNode() inside a useEffect hook.
+    useEffect(() => {
+        ref.current.inputNode().addEventListener("click", () => alert("Clicked!"))
+    })
+
+    // 3. Pass the ref to the ref prop.
+    return (
+        <>
+            <Body text="Click the input field below:" />
+            <PhoneNumberInput
+                id="access-input-element"
+                ref={ref}
+                {...props}
+            />
+        </>
+    )
+}
+
+export default PhoneNumberInputAccessInputElement

data/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_access_input_element.md

@@ -0,0 +1,3 @@
+To access the kit's input element attributes or add event listeners, create a `ref` inside your parent component, pass it to the kit's `ref` prop, and use `ref.current.inputNode()` with your desired attribute or event listener inside a `useEffect` hook. `useEffect` is necessary because the `ref` will be initially `undefined`.
+
+`inputNode()` is a custom function inside the kit that returns the input DOM element and its attributes. For example, to get the `name` attribute, use `ref.current.inputNode().name`

data/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_clear_field.jsx

@@ -0,0 +1,30 @@
+import React, { useRef } from 'react'
+import { Button, PhoneNumberInput } from '../..'
+
+const PhoneNumberInputClearField = (props) => {
+    // 1. Create a ref - this accesses the kit's input element.
+    const ref = useRef()
+
+    // 2. Use clearField() to clear the field.
+    const handleClick = () => {
+        ref.current.clearField()
+    }
+
+    // 3. Pass the ref to the ref prop.
+    return (
+        <>
+            <PhoneNumberInput
+                id="clear-field"
+                ref={ref}
+                {...props}
+            />
+
+            <Button
+                onClick={handleClick}
+                text="Clear the Input Field"
+            />
+        </>
+    )
+}
+
+export default PhoneNumberInputClearField

data/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_clear_field.md

@@ -0,0 +1,3 @@
+To clear a number inside the input element, create a `ref` inside your parent component, pass it to the kit's `ref` prop, and use `ref.current.clearField()`.
+
+`clearField()` is a custom function inside the kit to clear numbers and the error message while still providing validation.

data/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_validation.html.erb

@@ -0,0 +1,14 @@
+<form id="example-form-validation" action="" method="get">
+    <%= pb_rails("phone_number_input", props: { error: "Missing phone number.", id: "validation", initial_country: "af", value: "", required: true }) %>
+    <%= pb_rails("button", props: {html_type: "submit", text: "Save Phone Number"}) %>
+</form>
+
+<% content_for(:pb_js) do %>
+    <%= javascript_tag do %>
+        document.addEventListener('DOMContentLoaded', function () {
+            document.querySelector('#example-form-validation').addEventListener('submit', function (e) {
+                if (e.target.querySelectorAll('[error]:not([error=""])').length > 0) e.preventDefault();
+            })
+        })
+    <% end %>
+<% end %>

data/app/pb_kits/playbook/pb_phone_number_input/docs/_phone_number_input_validation.jsx

@@ -0,0 +1,60 @@
+import React, { useEffect, useState } from "react";
+import { Button, FixedConfirmationToast, PhoneNumberInput } from "../../";
+
+const PhoneNumberInputValidation = (props) => {
+    const [formErrors, setFormErrors] = useState("");
+    const [showFormErrors, setShowFormErrors] = useState(false);
+    const [phoneNumber, setPhoneNumber] = useState("");
+    const [countryCode, setCountryCode] = useState("af");
+
+    const handleOnValidate = (valid) => {
+        setFormErrors(
+            valid ? "" : "Please correct the fields below and try again."
+        );
+    };
+
+    const handleOnChange = ({ iso2, number }) => {
+        setCountryCode(iso2);
+        setPhoneNumber(number);
+    };
+    
+    const handleOnSubmit = (e) => {
+        if (showFormErrors) e.preventDefault()
+    }
+
+    useEffect(() => {
+        setShowFormErrors(formErrors.length > 0);
+    }, [formErrors]);
+
+    return (
+        <form
+            action=""
+            method="get"
+            onSubmit={handleOnSubmit}
+        >
+            {showFormErrors && (
+                <FixedConfirmationToast
+                    marginBottom="md"
+                    status="error"
+                    text={formErrors}
+                />
+            )}
+            <PhoneNumberInput
+                error="Missing phone number."
+                id="validation"
+                initialCountry={countryCode}
+                onChange={handleOnChange}
+                onValidate={handleOnValidate}
+                required
+                value={phoneNumber}
+                {...props}
+            />
+            <Button
+                htmlType="submit"
+                text="Save Phone Number"
+            />
+        </form>
+    );
+};
+
+export default PhoneNumberInputValidation;

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

@@ -5,9 +5,13 @@ examples:
   - 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_clear_field: Clearing the Input Field
+  - phone_number_input_access_input_element: Accessing the Input Element
 
   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_only_countries: Limited Countries
+  - phone_number_input_validation: Form Validation

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

@@ -2,3 +2,6 @@ export { default as PhoneNumberInputDefault } from './_phone_number_input_defaul
 export { default as PhoneNumberInputPreferredCountries } from './_phone_number_input_preferred_countries'
 export { default as PhoneNumberInputInitialCountry } from './_phone_number_input_initial_country'
 export { default as PhoneNumberInputOnlyCountries } from './_phone_number_input_only_countries'
+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'

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

@@ -5,6 +5,8 @@ module Playbook
     class PhoneNumberInput < Playbook::KitBase
       prop :disabled, type: Playbook::Props::Boolean,
                       default: false
+      prop :required, type: Playbook::Props::Boolean,
+                      default: false
       prop :initial_country, type: Playbook::Props::String,
                              default: ""
       prop :label, type: Playbook::Props::String,
@@ -15,6 +17,8 @@ module Playbook
                             default: []
       prop :preferred_countries, type: Playbook::Props::Array,
                                  default: []
+      prop :error, type: Playbook::Props::String,
+                   default: ""
       prop :value, type: Playbook::Props::String,
                    default: ""
 
@@ -27,11 +31,13 @@ module Playbook
           id: id,
           dark: dark,
           disabled: disabled,
+          error: error,
           initialCountry: initial_country,
           label: label,
           name: name,
           onlyCountries: only_countries,
           preferredCountries: preferred_countries,
+          required: required,
           value: value,
         }
       end

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

@@ -1,74 +1,122 @@
-import React from 'react'
-import { render, screen } from '../utilities/test-utils'
-import PhoneNumberInput from './_phone_number_input'
+import React from "react";
+import { render, screen } from "../utilities/test-utils";
+import PhoneNumberInput from "./_phone_number_input";
 
-const testId = "phoneNumberInput"
+const testId = "phoneNumberInput";
 
-test('should be disabled', () => {
-  const props = {
-    disabled: true,
-    id: testId,
-  }
+test("should be disabled", () => {
+    const props = {
+        disabled: true,
+        id: testId,
+    };
 
-  render(<PhoneNumberInput {...props} />)
-  const kit = screen.getByRole("textbox")
-  expect(kit).toBeDisabled()
-})
+    render(<PhoneNumberInput {...props} />);
+    const kit = screen.getByRole("textbox");
+    expect(kit).toBeDisabled();
+});
 
-test('should be enabled by default', () => {
-  const props = {
-    id: testId,
-  }
+test("should be enabled by default", () => {
+    const props = {
+        id: testId,
+    };
 
-  render(<PhoneNumberInput {...props} />)
-  const kit = screen.getByRole("textbox")
-  expect(kit).not.toBeDisabled()
-})
+    render(<PhoneNumberInput {...props} />);
+    const kit = screen.getByRole("textbox");
+    expect(kit).not.toBeDisabled();
+});
 
-test('should have label', () => {
-  const label = 'Phone Number'
-  const props = {
-    id: testId,
-    label,
-  }
+test("should have label", () => {
+    const label = "Phone Number";
+    const props = {
+        id: testId,
+        label,
+    };
 
-  render(<PhoneNumberInput {...props} />)
-  const kit = screen.getByText(label)
-  expect(kit).toBeInTheDocument()
-})
+    render(<PhoneNumberInput {...props} />);
+    const kit = screen.getByText(label);
+    expect(kit).toBeInTheDocument();
+});
 
-test('should pass data prop', () => {
-  const props = {
-    data: { testid: testId },
-    id: testId,
-  }
+test("should pass data prop", () => {
+    const props = {
+        data: { testid: testId },
+        id: testId,
+    };
+
+    render(<PhoneNumberInput {...props} />);
+    const kit = screen.getByTestId(testId);
+    expect(kit).toBeInTheDocument();
+});
+
+test("should pass className prop", () => {
+    const className = "custom-class-name";
+    const props = {
+        className,
+        data: { testid: testId },
+        id: testId,
+    };
+
+    render(<PhoneNumberInput {...props} />);
+    const kit = screen.getByTestId(testId);
+    expect(kit).toHaveClass(className);
+});
+
+test("should pass value prop", () => {
+    const value = "1234567890";
+    const props = {
+        id: testId,
+        value,
+    };
 
-  render(<PhoneNumberInput {...props} />)
-  const kit = screen.getByTestId(testId)
-  expect(kit).toBeInTheDocument()
-})
+    render(<PhoneNumberInput {...props} />);
+    const kit = screen.getByRole("textbox");
+    expect(kit).toHaveDisplayValue(value);
+});
 
-test('should pass className prop', () => {
-  const className = 'custom-class-name'
+//TODO: test required field presence
+test("should pass required prop", () => {
+    const props = {
+        id: testId,
+    };
+
+    render(
+        <PhoneNumberInput
+            required
+            {...props}
+        />
+    );
+    const kit = screen.getByRole("textbox");
+    expect(kit).toHaveAttribute("required");
+});
+
+test("should have error attribute when invalid", () => {
   const props = {
-    className,
-    data: { testid: testId },
-    id: testId,
-  }
-
-  render(<PhoneNumberInput {...props} />)
-  const kit = screen.getByTestId(testId)
-  expect(kit).toHaveClass(className)
-})
-
-test('should pass value prop', () => {
-  const value = '1234567890'
+      id: testId,
+      error: "Something isn't right here."
+  };
+
+  render(
+      <PhoneNumberInput
+          {...props}
+      />
+  );
+  const kit = screen.getByRole("textbox");
+  expect(kit).toHaveAttribute("error");
+});
+
+test("should trigger callback", () => {
+  const handleOnValidate = jest.fn((valid) => valid)
+
   const props = {
-    id: testId,
-    value,
-  }
-
-  render(<PhoneNumberInput {...props} />)
-  const kit = screen.getByRole("textbox")
-  expect(kit).toHaveDisplayValue(value)
-})
+      id: testId,
+      onValidate: handleOnValidate
+  };
+
+  render(
+      <PhoneNumberInput
+          {...props}
+      />
+  );
+
+  expect(handleOnValidate).toBeCalledWith(true)
+});