@bspk/ui 1.1.32 → 1.1.33

package/src/components/PhoneNumberField/PhoneNumberField.tsx

@@ -0,0 +1,80 @@
+import { FormField, FormFieldProps } from '-/components/FormField';
+import { PhoneNumberInput, PhoneNumberInputProps } from '-/components/PhoneNumberInput';
+
+export type PhoneNumberFieldProps = Pick<
+    PhoneNumberInputProps,
+    | 'autoComplete'
+    | 'disabled'
+    | 'disableFormatting'
+    | 'errorMessage'
+    | 'initialCountryCode'
+    | 'inputRef'
+    | 'invalid'
+    | 'name'
+    | 'onChange'
+    | 'placeholder'
+    | 'readOnly'
+    | 'required'
+    | 'size'
+    | 'type'
+    | 'value'
+> &
+    Pick<FormFieldProps, 'controlId' | 'helperText' | 'label' | 'labelTrailing'>;
+
+/**
+ * A text input that allows users to enter text phone numbers with country codes.
+ *
+ * @example
+ *     <PhoneNumberField label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
+ *
+ * @name PhoneNumberField
+ * @phase WorkInProgress
+ */
+function PhoneNumberField({
+    label,
+    errorMessage: errorMessageProp,
+    helperText,
+    controlId,
+    labelTrailing,
+    required,
+    value,
+    onChange,
+    disableFormatting,
+    initialCountryCode,
+    invalid,
+    ...inputProps
+}: PhoneNumberFieldProps) {
+    const errorMessage = (!inputProps.readOnly && !inputProps.disabled && errorMessageProp) || undefined;
+
+    return (
+        <FormField
+            controlId={controlId}
+            data-bspk="phone-number-field"
+            errorMessage={errorMessage}
+            helperText={helperText}
+            invalid={!inputProps.readOnly && !inputProps.disabled && invalid}
+            label={label}
+            labelTrailing={labelTrailing}
+            required={required}
+        >
+            {(fieldProps) => (
+                <PhoneNumberInput
+                    aria-label={label}
+                    disableFormatting={disableFormatting}
+                    errorMessage={errorMessage}
+                    initialCountryCode={initialCountryCode}
+                    onChange={onChange}
+                    value={value}
+                    {...fieldProps}
+                    {...inputProps}
+                />
+            )}
+        </FormField>
+    );
+}
+
+PhoneNumberField.bspkName = 'PhoneNumberField';
+
+export { PhoneNumberField };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/PhoneNumberField/index.tsx

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

package/src/components/PhoneNumberInput/PhoneNumberInput.tsx

@@ -0,0 +1,226 @@
+import { SvgIcon } from '@bspk/icons/SvgIcon';
+import { AsYouType, getCountryCallingCode } from 'libphonenumber-js';
+import { useMemo, useState } from 'react';
+
+import { InvalidPropsLibrary } from '-';
+import { Divider } from '-/components/Divider';
+import { ListItem, ListItemProps } from '-/components/ListItem';
+import { Listbox } from '-/components/Listbox';
+import { Modal } from '-/components/Modal';
+import { TextInput, TextInputProps } from '-/components/TextInput';
+import { useCombobox } from '-/hooks/useCombobox';
+import { useUIContext } from '-/hooks/useUIContext';
+import { countryCodeData, countryCodes, SupportedCountryCode } from '-/utils/countryCodes';
+import { guessUserCountryCode } from '-/utils/guessUserCountryCode';
+
+import './phone-number-input.scss';
+
+const useCountryCodeSelectOptions = (initialCountryCode?: SupportedCountryCode) => {
+    return useMemo(() => {
+        const selectOptions = countryCodes.map((code): ListItemProps & { value: string } => {
+            const countryCodeDetails = countryCodeData[code];
+            const callingCodeString = `(+${getCountryCallingCode(code)})`;
+
+            return {
+                value: code,
+                label: `${countryCodeDetails?.name}`,
+                leading: countryCodeDetails?.flagIconName ? <SvgIcon name={countryCodeDetails?.flagIconName} /> : null,
+                trailing: callingCodeString,
+            };
+        });
+
+        const defaultCode = initialCountryCode || guessUserCountryCode();
+
+        return { countryCodeSelectOptions: selectOptions, defaultCountryCode: defaultCode };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+};
+
+export type PhoneNumberInputProps = InvalidPropsLibrary &
+    Pick<
+        TextInputProps,
+        | 'aria-label'
+        | 'autoComplete'
+        | 'disabled'
+        | 'inputRef'
+        | 'name'
+        | 'placeholder'
+        | 'readOnly'
+        | 'required'
+        | 'size'
+        | 'type'
+        | 'value'
+    > & {
+        /**
+         * 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;
+        /** Handler for change events. Contains the raw phone number value and the selected country code. */
+        onChange: (value: string, countryCode: SupportedCountryCode) => void;
+    };
+
+/**
+ * A text input that allows users to enter text phone numbers with country codes.
+ *
+ * This is the base element and if used must contain the field label contextually. This will more often be used in the
+ * PhoneNumberField component.
+ *
+ * @example
+ *     <PhoneNumberInput aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
+ *
+ * @name PhoneNumberInput
+ * @phase WorkInProgress
+ */
+function PhoneNumberInput({
+    errorMessage,
+    value,
+    onChange,
+    disableFormatting,
+    initialCountryCode,
+    disabled,
+    invalid,
+    readOnly,
+    ...inputProps
+}: PhoneNumberInputProps) {
+    const { isMobile } = useUIContext();
+    const {
+        toggleProps,
+        menuProps,
+        closeMenu,
+        elements,
+        isOpen: showCountryCodeSelectMenu,
+        activeIndex,
+    } = useCombobox({
+        placement: 'bottom',
+        disabled,
+        invalid,
+        readOnly,
+        errorMessage,
+    });
+
+    const { countryCodeSelectOptions, defaultCountryCode } = useCountryCodeSelectOptions(initialCountryCode);
+
+    const [countryCode, setCountryCode] = useState<SupportedCountryCode>(defaultCountryCode);
+
+    const formattedValue = useMemo(() => {
+        if (disableFormatting) {
+            return value;
+        }
+
+        const formatter = new AsYouType(countryCode);
+
+        return formatter.input(value || '');
+    }, [value, countryCode, disableFormatting]);
+
+    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) => {
+        const rawNumber = newValue.replace(/\D/g, '');
+        if (rawNumber === value) return;
+
+        onChange(rawNumber, countryCode);
+    };
+
+    const setRef = (el: HTMLDivElement | null) => {
+        elements.setReference(el);
+    };
+
+    return (
+        <div data-bspk="phone-number-input" ref={setRef}>
+            <TextInput
+                onChange={handleChange}
+                value={formattedValue}
+                {...inputProps}
+                disabled={disabled}
+                errorMessage={errorMessage}
+                invalid={invalid}
+                leading={
+                    <div style={{ display: 'flex', alignItems: 'center' }}>
+                        <button
+                            {...(disabled ? {} : toggleProps)}
+                            aria-label="Open country code menu"
+                            data-bspk="country-code-select"
+                        >
+                            <SvgIcon name={selectedCodeData.flagIconName} />
+
+                            <SvgIcon name="KeyboardArrowDown" />
+                        </button>
+                        <Divider orientation="vertical" />
+                        <span aria-label="Country code" style={{ cursor: 'default' }}>{`+${callingCode}`}</span>
+                    </div>
+                }
+                readOnly={readOnly}
+            />
+            {showCountryCodeSelectMenu && (
+                <>
+                    {isMobile ? (
+                        <Modal
+                            data-bspk-owner="phone-number-input"
+                            description="select a country code for your phone number"
+                            header="Country Code"
+                            onClose={closeMenu}
+                            open={showCountryCodeSelectMenu}
+                        >
+                            {countryCodeSelectOptions.map((option, index) => (
+                                <ListItem
+                                    active={activeIndex === index || undefined}
+                                    aria-selected={countryCode === option.value}
+                                    data-bspk="country-code-select-option"
+                                    id={`${option.value}-country-code-select-option`}
+                                    key={option.value}
+                                    label={option.label}
+                                    leading={option.leading}
+                                    onClick={() => {
+                                        setCountryCode(option.value as SupportedCountryCode);
+                                        closeMenu();
+                                    }}
+                                    trailing={option.trailing}
+                                />
+                            ))}
+                        </Modal>
+                    ) : (
+                        <Listbox
+                            activeIndex={activeIndex}
+                            data-bspk-owner="phone-number-input"
+                            innerRef={elements.setFloating}
+                            itemDisplayCount={countryCodeSelectOptions.length}
+                            items={countryCodeSelectOptions}
+                            onChange={(next, event) => {
+                                event?.preventDefault();
+                                closeMenu();
+                                setCountryCode(next[0] as SupportedCountryCode);
+                            }}
+                            selectedValues={[countryCode]}
+                            {...menuProps}
+                        />
+                    )}
+                </>
+            )}
+        </div>
+    );
+}
+
+PhoneNumberInput.bspkName = 'PhoneNumberInput';
+
+export { PhoneNumberInput };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/PhoneNumberInput/index.tsx

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

package/src/components/PhoneNumberInput/phone-number-input.scss

@@ -0,0 +1,49 @@
+[data-bspk='phone-number-input'] {
+    width: 100%;
+
+    [data-bspk='text-input'] {
+        padding-left: 0;
+    }
+
+    [data-bspk='divider'] {
+        margin-left: 0;
+        margin-top: var(--spacing-sizing-01);
+        margin-bottom: var(--spacing-sizing-01);
+    }
+
+    [data-bspk='country-code-select'] {
+        border: 0;
+        padding: var(--spacing-sizing-02);
+        background: none;
+        cursor: pointer;
+        outline: none;
+
+        [data-bspk-name='KeyboardArrowDown'] {
+            margin-left: var(--spacing-sizing-02);
+        }
+    }
+
+    [data-bspk='country-code'] {
+        font: var(--body-base);
+        color: var(--foreground-neutral-on-surface);
+    }
+
+    [data-bspk='txt'] {
+        cursor: default;
+    }
+
+    [data-disabled] {
+        [data-bspk='country-code-select'] {
+            cursor: default;
+        }
+    }
+}
+
+[data-bspk-owner='phone-number-input'] {
+    [data-bspk='list-item'] {
+        [data-trailing] {
+            font: var(--body-base);
+            color: var(--foreground-neutral-on-surface);
+        }
+    }
+}

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,156 @@
+import { SvgClose } from '@bspk/icons/Close';
+import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
+
+import { CallToActionButton, CommonProps } from '-';
+import { Button } from '-/components/Button';
+import { Portal } from '-/components/Portal';
+import { Txt } from '-/components/Txt';
+import { Placement, useFloating } from '-/hooks/useFloating';
+import { useOutsideClick } from '-/hooks/useOutsideClick';
+import './popover.scss';
+
+export type PopoverProps = CommonProps<'disabled'> & {
+    /**
+     * The placement of the popover.
+     *
+     * @default top
+     */
+    placement?: Placement;
+    /** The popover header. */
+    header: string;
+    /**
+     * The content of the popover.
+     *
+     * @type multiline
+     */
+    content: string;
+    /**
+     * The call to action button properties.
+     *
+     * @type CallToActionButton
+     */
+    callToAction?: CallToActionButton;
+    /**
+     * A single element that will trigger the popover when clicked.
+     *
+     * @type ReactElement
+     * @required
+     */
+    children: ReactElement;
+};
+
+/**
+ * Brief message that provide additional guidance and helps users perform an action if needed.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { Popover } from '@bspk/ui/Popover';
+ *     import { Button } from '@bspk/ui/Button';
+ *
+ *     export function Example() {
+ *         const [showPopover, setShowPopover] = useState<boolean>(false);
+ *
+ *         const togglePopover = () => setShowPopover(!showPopover);
+ *         const onPopoverCallToActionClick = () => alert('Action clicked');
+ *
+ *         return (
+ *             <Popover
+ *                 placement="bottom"
+ *                 content="This is a popover content"
+ *                 header="Popover Header"
+ *                 callToAction={{
+ *                     label: 'Action',
+ *                     onClick: onPopoverCallToActionClick,
+ *                 }}
+ *             >
+ *                 <Button label="Toggle popover" onClick={togglePopover} />
+ *             </Popover>
+ *         );
+ *     }
+ *
+ * @name Popover
+ * @phase DesignReview
+ */
+function Popover({ placement = 'top', header, content, callToAction, children, disabled = false }: PopoverProps) {
+    const id = useId();
+    const [show, setShow] = useState(false);
+    const arrowRef = useRef<HTMLElement | null>(null);
+
+    const { elements, floatingStyles, middlewareData } = useFloating({
+        placement: placement,
+        strategy: 'absolute',
+        offsetOptions: 22,
+        arrowRef,
+        hide: !show,
+    });
+
+    useOutsideClick([elements.floating], () => setShow(false));
+
+    const child = useMemo(
+        () =>
+            !disabled &&
+            children &&
+            cloneElement(children, {
+                onClick: () => setShow((prev) => !prev),
+                'aria-describedby': id,
+            }),
+        [children, disabled, id],
+    );
+
+    return disabled ? (
+        children
+    ) : (
+        <>
+            {child}
+            <Portal>
+                <div
+                    data-bspk="popover"
+                    data-placement={middlewareData?.offset?.placement}
+                    id={id}
+                    ref={(node) => {
+                        elements.setFloating(node);
+                        elements.setReference(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
+                    }}
+                    style={floatingStyles}
+                >
+                    <header>
+                        <Txt variant="heading-h6">{header}</Txt>
+                        <button aria-label="Close" onClick={() => setShow(false)}>
+                            <SvgClose />
+                        </button>
+                    </header>
+                    <div data-content>
+                        <Txt as="div" variant="body-small">
+                            {content}
+                        </Txt>
+                        {callToAction?.label && callToAction?.onClick && (
+                            <Button
+                                data-call-to-action
+                                label={callToAction.label}
+                                onClick={callToAction.onClick}
+                                size="small"
+                                variant="secondary"
+                            />
+                        )}
+                    </div>
+                    <div
+                        data-arrow
+                        ref={(node) => {
+                            arrowRef.current = node;
+                        }}
+                        style={{
+                            left: `${middlewareData?.arrow?.x}px`,
+                            top: `${middlewareData?.arrow?.y}px`,
+                        }}
+                    />
+                </div>
+            </Portal>
+        </>
+    );
+}
+
+Popover.bspkName = 'Popover';
+
+export { Popover };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Popover/PopoverExample.tsx

@@ -0,0 +1,27 @@
+import { Button } from '-/components/Button';
+import { ComponentExampleFn } from '-/utils/demo';
+
+import { PopoverProps } from '.';
+
+export const PopoverExample: ComponentExampleFn<PopoverProps> = ({ action }) => ({
+    render: ({ props, Component }) => {
+        return (
+            <>
+                <Component {...props}>
+                    <Button label={`Click me (${props.placement})`} variant="secondary" />
+                </Component>
+            </>
+        );
+    },
+    presets: [
+        {
+            label: 'With CallToAction',
+            propState: {
+                callToAction: {
+                    label: 'Click me',
+                    onClick: () => action('Call to action clicked!'),
+                },
+            },
+        },
+    ],
+});

package/src/components/Popover/index.tsx

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

package/src/components/Portal/Portal.tsx

@@ -0,0 +1,42 @@
+import { ReactNode, useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+export type PortalProps = {
+    /**
+     * The content to render in the portal.
+     *
+     * @required
+     */
+    children: ReactNode;
+    /**
+     * The container to render the portal in.
+     *
+     * @optional
+     */
+    container?: HTMLElement;
+};
+
+/**
+ * Utility component to render children in the portals container provided by the BaseProvider.
+ *
+ * Initial SRR is supported.
+ *
+ * @name Portal
+ * @phase Utility
+ */
+function Portal({ children, container }: PortalProps) {
+    const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(container || null);
+
+    useEffect(() => {
+        if (!portalContainer && typeof window !== 'undefined') setPortalContainer(document.body);
+    }, [portalContainer]);
+
+    // data-bspk="portal" can't be used here
+    return portalContainer && createPortal(children, portalContainer);
+}
+
+Portal.bspkName = 'Portal';
+
+export { Portal };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Portal/index.tsx

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

package/src/components/ProgressBar/ProgressBar.tsx

@@ -0,0 +1,78 @@
+import { useId } from 'react';
+
+import { cssWithVars } from '-/utils/cwv';
+
+import './progress-bar.scss';
+
+export type ProgressBarProps = {
+    /**
+     * The size of the progressbar.
+     *
+     * @default large
+     */
+    size?: 'large' | 'small';
+    /**
+     * The current progress of the progressbar.
+     *
+     * @example
+     *     42;
+     *
+     * @default 0
+     * @minimum 0
+     * @maximum 100
+     *
+     * @required
+     */
+    completion: number;
+    /**
+     * The label alignment of the progressbar.
+     *
+     * @default center
+     */
+    align?: 'center' | 'left';
+    /** The label of the progressbar. */
+    label: string;
+};
+
+/**
+ * A progress bar is a horizontal visual indicator that let’s the user know the progression of a task or operation
+ * occurring in the background.
+ *
+ * @example
+ *     import { ProgressBar } from '@bspk/ui/ProgressBar';
+ *
+ *     export function Example() {
+ *         return <ProgressBar label="Example label" completion={50} />;
+ *     }
+ *
+ * @name ProgressBar
+ * @phase DesignReview
+ */
+function ProgressBar({ size = 'large', completion = 0, align = 'center', label }: ProgressBarProps) {
+    const id = useId();
+
+    return (
+        <div data-align={align} data-bspk="progress-bar" data-size={size}>
+            <progress
+                aria-busy={completion < 100}
+                aria-label="A bounded progress bar from 0 to 100"
+                aria-valuemax={100}
+                aria-valuemin={0}
+                aria-valuenow={completion}
+                id={id}
+                max="100"
+                value={completion}
+            >
+                {completion}%
+            </progress>
+            <div aria-hidden data-bar style={cssWithVars({ '--width': `${completion}%` })} />
+            <label htmlFor={id}>{label}</label>
+        </div>
+    );
+}
+
+ProgressBar.bspkName = 'ProgressBar';
+
+export { ProgressBar };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ProgressBar/index.tsx

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