@bspk/ui 1.3.2 → 1.3.4

package/src/components/InputPhone/InputPhone.tsx

@@ -0,0 +1,290 @@
+import './input-phone.scss';
+import { SvgIcon } from '@bspk/icons/SvgIcon';
+import { AsYouType, getCountryCallingCode } from 'libphonenumber-js';
+import { useMemo, useRef, useState } from 'react';
+import { Button } from '-/components/Button';
+import { useFieldInit } from '-/components/Field';
+import { InputElement, InputProps } from '-/components/Input';
+import { ListItem } from '-/components/ListItem';
+import { Menu } from '-/components/Menu';
+import { useArrowNavigation } from '-/hooks/useArrowNavigation';
+import { useFloating } from '-/hooks/useFloating';
+import { useOutsideClick } from '-/hooks/useOutsideClick';
+import { useUIContext } from '-/hooks/useUIContext';
+import { FieldControlProps } from '-/types/common';
+import { countryCodeData, countryCodes, SupportedCountryCode } from '-/utils/countryCodes';
+import { getElementById } from '-/utils/dom';
+import { guessUserCountryCode } from '-/utils/guessUserCountryCode';
+import { handleKeyDown } from '-/utils/handleKeyDown';
+import { scrollListItemsStyle, ScrollListItemsStyleProps } from '-/utils/scrollListItemsStyle';
+import { useIds } from '-/utils/useIds';
+
+const SELECT_OPTIONS = countryCodes.map((code) => {
+    const countryCodeDetails = countryCodeData[code];
+    return {
+        value: code,
+        label: `${countryCodeDetails?.name}`,
+        countryCallingCode: getCountryCallingCode(code),
+        flagIconName: countryCodeDetails?.flagIconName,
+    };
+});
+
+export type InputPhoneProps = FieldControlProps<string, SupportedCountryCode> &
+    Pick<InputProps, 'inputRef' | 'size'> &
+    ScrollListItemsStyleProps & {
+        /**
+         * The default country code to select when the component is rendered. If not provided, it will attempt to guess
+         * based on the user's locale. If the guessed country code is not supported, it will default to 'US'. Based on
+         * [ISO](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 2-digit country codes.
+         *
+         * @type string
+         */
+        initialCountryCode?: SupportedCountryCode;
+        /**
+         * Disables formatting of the phone number input in the UI. values returned by `onChange` are always
+         * unformatted.
+         *
+         * @type boolean
+         */
+        disableFormatting?: boolean;
+    };
+
+/**
+ * An input that allows users to enter text phone numbers and select country codes for the phone number.
+ *
+ * This is the base element and if used must contain the field label contextually.
+ *
+ * For a more complete example with field usage, see the InputPhoneField component.
+ *
+ * @example
+ *     import { InputPhone } from '@bspk/ui/InputPhone';
+ *
+ *     function ExampleStandalone() {
+ *         const [value, onChange] = React.useState<number | undefined>();
+ *
+ *         return <InputPhone aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
+ *     }
+ *
+ *     function ExampleWithField() {
+ *         const [value, onChange] = React.useState<number | undefined>();
+ *
+ *         return (
+ *             <Field>
+ *                 <FieldLabel>Example Input Phone</FieldLabel>
+ *                 <InputPhone aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />
+ *                 <FieldDescription>
+ *                     The phone input allows you to enter a phone number with country code.
+ *                 </FieldDescription>
+ *             </Field>
+ *         );
+ *     }
+ *
+ * @name InputPhone
+ * @phase UXReview
+ */
+export function InputPhone({
+    value,
+    onChange,
+    disableFormatting,
+    initialCountryCode,
+    disabled,
+    readOnly,
+    name,
+    id: idProp,
+    invalid: invalidProp,
+    required = false,
+    size = 'medium',
+    inputRef,
+    scrollLimit = 5,
+    'aria-label': ariaLabel = 'Phone number input',
+}: InputPhoneProps) {
+    const { id, ariaDescribedBy, ariaErrorMessage, invalid } = useFieldInit({
+        idProp,
+        required,
+        disabled,
+        readOnly,
+        invalidProp,
+    });
+    const menuId = useMemo(() => `${id}-menu`, [id]);
+
+    const items = useIds(`input-phone-${id}`, SELECT_OPTIONS);
+
+    const [countryCode, setCountryCode] = useState<SupportedCountryCode>(initialCountryCode || guessUserCountryCode());
+
+    const inputInternalRef = useRef<HTMLInputElement | null>(null);
+
+    const { activeElementId, setActiveElementId, arrowKeyCallbacks } = useArrowNavigation({
+        ids: items.map((i) => i.id),
+    });
+
+    const closeMenu = () => setActiveElementId(null);
+    const open = Boolean(activeElementId);
+
+    const { elements, floatingStyles } = useFloating({
+        hide: !open,
+        offsetOptions: 4,
+        refWidth: true,
+    });
+
+    useOutsideClick({
+        elements: [elements.floating, elements.reference],
+        callback: () => closeMenu(),
+        disabled: !open,
+    });
+
+    const spaceEnter = () => {
+        if (!open) {
+            elements.reference?.click();
+            return;
+        }
+        if (activeElementId) getElementById(activeElementId)?.click();
+    };
+
+    const { callingCode, selectedCodeData } = useMemo(() => {
+        const selectedValue = (countryCode || 'US') as SupportedCountryCode;
+        const data = countryCodeData[selectedValue] ?? countryCodeData.US;
+        return {
+            callingCode: getCountryCallingCode(countryCode),
+            selectedCodeData: data,
+        };
+    }, [countryCode]);
+
+    const handleChange = (newValue: string) => {
+        let rawNumber = newValue.replace(/\D/g, '');
+        if (rawNumber === value) return;
+
+        if (!disableFormatting) {
+            const formatter = new AsYouType(countryCode);
+            rawNumber = formatter.input(`${rawNumber}`);
+        }
+
+        onChange(rawNumber, countryCode);
+    };
+
+    const { sendAriaLiveMessage } = useUIContext();
+
+    return (
+        <>
+            <div
+                data-bspk="input-phone"
+                onKeyDownCapture={handleKeyDown({
+                    Tab: () => {
+                        //  if (open) closeMenu();
+                    },
+                })}
+            >
+                <InputElement
+                    aria-describedby={ariaDescribedBy}
+                    aria-errormessage={ariaErrorMessage}
+                    aria-label={ariaLabel || undefined}
+                    autoComplete="off"
+                    containerRef={elements.setReference}
+                    disabled={disabled}
+                    id={id}
+                    inputRef={(node) => {
+                        inputRef?.(node);
+                        inputInternalRef.current = node;
+                    }}
+                    invalid={invalid}
+                    leading={
+                        <>
+                            <Button
+                                aria-activedescendant={open ? activeElementId || undefined : undefined}
+                                aria-controls={open ? menuId : undefined}
+                                aria-disabled={disabled || undefined}
+                                aria-expanded={open}
+                                aria-haspopup="listbox"
+                                aria-label="select country code"
+                                aria-owns={menuId}
+                                aria-readonly={readOnly || undefined}
+                                disabled={disabled || readOnly}
+                                label="Open country code menu"
+                                name={`${name}-country-code`}
+                                onClick={(event) => {
+                                    const nextOpen = !open;
+                                    if (nextOpen) {
+                                        setActiveElementId(items[0]?.id || null);
+                                    } else {
+                                        setActiveElementId(null);
+                                    }
+                                    event.preventDefault();
+                                }}
+                                onKeyDown={handleKeyDown(
+                                    {
+                                        ...arrowKeyCallbacks,
+                                        ArrowDown: (event) => {
+                                            if (!open) spaceEnter();
+                                            arrowKeyCallbacks.ArrowDown?.(event);
+                                        },
+                                        Space: spaceEnter,
+                                        Enter: spaceEnter,
+                                        Escape: closeMenu,
+                                        'Ctrl+Option+Space': spaceEnter,
+                                    },
+                                    { preventDefault: true, stopPropagation: true },
+                                )}
+                                role="combobox"
+                                variant="tertiary"
+                            >
+                                <SvgIcon name={selectedCodeData.flagIconName} />
+                                <SvgIcon name="KeyboardArrowDown" />
+                            </Button>
+                            <span aria-hidden="true" style={{ cursor: 'default' }}>{`+${callingCode}`}</span>
+                        </>
+                    }
+                    name={name}
+                    onChange={handleChange}
+                    owner="input-phone"
+                    readOnly={readOnly}
+                    required={required}
+                    size={size}
+                    value={value}
+                />
+            </div>
+            {open && (
+                <Menu
+                    aria-autocomplete={undefined}
+                    aria-label="Select country code"
+                    as="div"
+                    id={menuId}
+                    innerRef={elements.setFloating}
+                    onClickCapture={() => {
+                        // Prevent the menu from closing when clicking inside it
+                        // maintain focus on the select control
+                        inputInternalRef.current?.focus();
+                    }}
+                    onFocus={() => {
+                        inputInternalRef.current?.focus();
+                    }}
+                    owner="input-phone"
+                    role="listbox"
+                    style={{
+                        ...(open ? scrollListItemsStyle(scrollLimit, items.length) : {}),
+                        ...floatingStyles,
+                    }}
+                    tabIndex={-1}
+                >
+                    {items.map(({ countryCallingCode, flagIconName, ...item }) => (
+                        <ListItem
+                            {...item}
+                            active={item.id === activeElementId}
+                            aria-selected={item.value === countryCode}
+                            key={item.id}
+                            leading={flagIconName ? <SvgIcon aria-hidden name={flagIconName} /> : null}
+                            onClick={() => {
+                                setCountryCode(item.value as SupportedCountryCode);
+                                sendAriaLiveMessage(`Selected country code ${item.label}`);
+                                closeMenu();
+                                inputInternalRef.current?.focus();
+                            }}
+                            role="option"
+                            trailing={`(+${countryCallingCode})`}
+                        />
+                    ))}
+                </Menu>
+            )}
+        </>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/InputPhone/InputPhoneExample.tsx

@@ -0,0 +1,9 @@
+import { InputPhoneProps } from '.';
+import { ComponentExample, Preset } from '-/utils/demo';
+
+export const presets: Preset<InputPhoneProps>[] = [];
+
+export const InputPhoneExample: ComponentExample<InputPhoneProps> = {
+    render: ({ props, Component }) => <Component {...props} />,
+    variants: true,
+};

package/src/components/InputPhone/index.tsx

@@ -0,0 +1 @@
+export * from './InputPhone';

package/src/components/{PhoneNumberInput/phone-number-input.scss → InputPhone/input-phone.scss}

@@ -1,39 +1,34 @@
-[data-bspk='phone-number-input'] {
+[data-bspk='input-phone'] {
     position: relative;
     width: 100%;
 }
 
-[data-bspk-owner='phone-number-input'] {
+[data-bspk-owner='input-phone'][data-bspk='input'] {
     padding-left: 0;
 
+    &:focus-within {
+        outline: none;
+    }
+
+    input:focus-visible {
+        outline: solid 2px var(--stroke-neutral-focus);
+        border-radius: var(--radius-sm);
+    }
+
     [data-bspk='divider'] {
         margin: 0 var(--spacing-sizing-02) 0 0;
     }
 
     [data-leading] {
-        overflow: hidden;
         position: relative;
 
-        [contentEditable] {
-            position: absolute;
-            opacity: 0;
-            inset: 0;
-            z-index: 2;
-        }
-
-        [contentEditable]:focus-visible {
-            outline: none;
-
-            & + [data-bspk='button'] {
-                outline: solid 2px var(--stroke-neutral-focus);
-            }
-        }
-
         [data-bspk='button'] {
             gap: var(--spacing-sizing-02);
             padding: 0 var(--spacing-sizing-03);
             min-height: 100%;
             margin-right: var(--spacing-sizing-02);
+            position: relative;
+            z-index: 2;
 
             &::after {
                 content: '';

package/src/components/InputPhoneField/InputPhoneField.rtl.test.tsx

@@ -0,0 +1,17 @@
+import { InputPhoneField } from '.';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <InputPhoneField label="Example field label" name="example-field-name" onChange={() => {}} value="" />
+);
+
+describe('InputPhoneField (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getAllByLabelText } = render(<TestBed />);
+
+        expect(getAllByLabelText('Example field label')[0]).toBeInTheDocument();
+    });
+});

package/src/components/InputPhoneField/InputPhoneField.tsx

@@ -0,0 +1,30 @@
+import { FormField, FormFieldControlProps } from '-/components/FormField';
+import { InputPhone, InputPhoneProps } from '-/components/InputPhone';
+
+export type InputPhoneFieldProps = FormFieldControlProps<InputPhoneProps>;
+
+/**
+ * A field wrapper for the InputPhone component.
+ *
+ * This component takes properties from the FormField and InputPhone components.
+ *
+ * @name InputPhoneField
+ * @phase UXReview
+ *
+ * @generated
+ */
+export function InputPhoneField({
+    label,
+    helperText,
+    labelTrailing,
+    errorMessage,
+    ...controlProps
+}: InputPhoneFieldProps) {
+    return (
+        <FormField errorMessage={errorMessage} helperText={helperText} label={label} labelTrailing={labelTrailing}>
+            <InputPhone {...controlProps} />
+        </FormField>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/InputPhoneField/index.tsx

@@ -0,0 +1 @@
+export * from './InputPhoneField';

package/src/components/Layout/Layout.tsx

@@ -44,7 +44,7 @@ export type LayoutProps<As extends ElementType = 'div'> = {
  * @example
  *     import { Layout } from '@bspk/ui/Layout';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <Layout>Low effort example</Layout>;
  *     }
  *

package/src/components/Link/Link.tsx

@@ -46,7 +46,7 @@ export type LinkProps = Pick<CommonPropsLibrary, 'disabled'> & {
  * @example
  *     import { Link } from '@bspk/ui/Link';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <Link href="https://bspk.dev" label="Example label" trailingIcon="external" />;
  *     }
  *

package/src/components/ListItem/ListItem.rtl.test.tsx

@@ -1,8 +1,11 @@
 import { ListItem } from './ListItem';
-import { presets } from './ListItemExample';
+import { presets as presentsFn } from './ListItemExample';
 import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
 import { render } from '-/rtl/util';
 
+// eslint-disable-next-line no-console
+const presets = presentsFn(console.log);
+
 describe('ListItem (RTL)', () => {
     presets.forEach((preset) => {
         it(`has no basic a11y issues - ${preset.label}`, hasNoBasicA11yIssues(<ListItem {...preset.propState} />));

package/src/components/ListItem/ListItem.tsx

@@ -7,15 +7,14 @@ import {
     AriaAttributes,
     HTMLAttributes,
     AriaRole,
+    ComponentProps,
 } from 'react';
 import { ListItemButton } from './ListItemButton';
 import { Truncated } from '-/components/Truncated';
 import { useId } from '-/hooks/useId';
 import { CommonProps, ElementProps, SetRef } from '-/types/common';
 
-export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
-    'active' | 'disabled' | 'owner' | 'readOnly'
-> &
+export type ListItemProps<As extends ElementType = ElementType> = CommonProps<'active' | 'owner'> &
     Pick<AriaAttributes, 'aria-label'> & {
         /**
          * The element type to render as.
@@ -33,12 +32,16 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
          * @options Icon, Img, Avatar
          */
         leading?: ReactNode;
+        /** Props to pass to the leading element wrapper span. */
+        leadingProps?: ComponentProps<'span'>;
         /**
          * The label to display in the ListItem.
          *
          * @required
          */
         label: string;
+        /** Props to pass to the label wrapper span. */
+        labelProps?: ComponentProps<'span'>;
         /** The subtext to display in the ListItem. */
         subText?: string;
         /**
@@ -51,6 +54,8 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
          * @options Checkbox, Icon, ListItemButton, Radio, Switch, Tag, Txt
          */
         trailing?: ReactNode;
+        /** Props to pass to the trailing element wrapper span. */
+        trailingProps?: ComponentProps<'span'>;
         /**
          * The [href](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#href) of the list item.
          *
@@ -77,18 +82,21 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
          * If not provided, a unique ID will be generated. This is useful for accessibility and testing purposes.
          */
         id?: string;
-        /**
-         * Whether to hide the label from screen readers. Use this when the label is redundant with other context, such
-         * as within a ListItemMenu or Label.
-         *
-         * @default false
-         */
-        hideAriaLabel?: boolean;
         /**
          * Indicates the current "selected" state of the list item when used in a selectable context, such as within a
          * ListItemMenu.
          */
         'aria-selected'?: boolean;
+        /**
+         * Determines how the ListItem uses horizontal space.
+         *
+         * If set to 'fill', options expand to fill the container's width.
+         *
+         * If set to 'hug', options only take up as much space as the content requires.
+         *
+         * @default fill
+         */
+        width?: 'fill' | 'hug';
     };
 
 /**
@@ -109,7 +117,7 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
  *     import { SvgSquare } from '@bspk/icons/Square';
  *     import { ListItem } from '@bspk/ui/ListItem';
  *
- *     export function Example() {
+ *     function Example() {
  *         return (
  *             <ListItem
  *                 label="Example label"
@@ -126,19 +134,22 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<
 function ListItem<As extends ElementType = ElementType>({
     active,
     as,
-    disabled,
     innerRef,
     label,
+    labelProps,
     leading,
-    readOnly,
+    leadingProps,
     owner,
     role: roleProp,
     subText,
     trailing,
+    trailingProps,
     id: idProp,
     'aria-label': ariaLabel,
     'aria-selected': ariaSelected,
-    hideAriaLabel,
+    'aria-disabled': ariaDisabled,
+    'aria-readonly': ariaReadonly,
+    width,
     ...props
 }: ElementProps<ListItemProps<As>, As>) {
     const id = useId(idProp);
@@ -146,35 +157,46 @@ function ListItem<As extends ElementType = ElementType>({
     if (!label) return null;
 
     const As = asLogic(as, props);
-    const role = roleLogic(roleProp, { as: As, props });
-    const actionable = (props.href || props.onClick) && !props.disabled && !props.readOnly;
+
+    const isReadOnly = Boolean(props.readOnly || ariaReadonly);
+    const isDisabled = Boolean(props.disabled || ariaDisabled);
+
+    const actionable = !!(props.href || props.onClick || as === 'button') && !isReadOnly && !isDisabled;
+
+    const role = roleLogic(roleProp, { as: As, props, actionable });
 
     return (
         <As
             {...props}
-            aria-disabled={disabled || undefined}
             aria-label={ariaLabel || undefined}
             aria-selected={ariaSelected}
             data-action={actionable || undefined}
             data-active={active || undefined}
             data-bspk="list-item"
             data-bspk-owner={owner || undefined}
-            data-readonly={readOnly || undefined}
+            data-disabled={isDisabled || undefined}
+            data-readonly={isReadOnly || undefined}
+            data-width={width === 'hug' ? 'hug' : undefined}
             id={id}
+            onClick={isReadOnly || isDisabled ? undefined : props.onClick}
             ref={innerRef}
             role={role}
-            tabIndex={props.tabIndex || (actionable ? 0 : undefined)}
+            tabIndex={props.tabIndex || (actionable ? 0 : -1)}
         >
             {leading && (
-                <span aria-hidden data-leading>
+                <span {...leadingProps} data-leading>
                     {leading}
                 </span>
             )}
-            <span aria-hidden={hideAriaLabel ? true : undefined} data-item-label>
+            <span {...labelProps} data-item-label>
                 <Truncated data-text>{label}</Truncated>
                 {subText && <span data-sub-text>{subText}</span>}
             </span>
-            {trailing && <span data-trailing>{trailing}</span>}
+            {trailing && (
+                <span {...trailingProps} data-trailing>
+                    {trailing}
+                </span>
+            )}
         </As>
     );
 }
@@ -190,18 +212,21 @@ function asLogic<As extends ElementType>(as: As | undefined, props: Partial<List
 }
 
 function roleLogic(
+    /** User provided role prop */
     existingRole: AriaRole | undefined,
     {
         as: As,
         props,
+        actionable,
     }: {
         as: ElementType;
         props: Partial<ListItemProps>;
+        actionable?: boolean;
     },
 ): HTMLAttributes<HTMLElement>['role'] | undefined {
     if (existingRole) return existingRole;
 
-    if (props.href) return As !== 'a' ? 'link' : undefined;
+    if (!actionable) return undefined;
 
     if (props.onClick && As !== 'button' && As !== 'label') return 'button';