@bspk/ui 1.1.34 → 1.2.0

package/src/components/PhoneNumberField/PhoneNumberField.tsx

@@ -1,25 +1,7 @@
-import { FormField, FormFieldProps } from '-/components/FormField';
+import { FormField, FormFieldWrapProps } 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'>;
+export type PhoneNumberFieldProps = FormFieldWrapProps<PhoneNumberInputProps>;
 
 /**
  * A text input that allows users to enter text phone numbers with country codes.
@@ -28,53 +10,32 @@ export type PhoneNumberFieldProps = Pick<
  *     <PhoneNumberField label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
  *
  * @name PhoneNumberField
- * @phase WorkInProgress
+ * @phase UXReview
  */
-function PhoneNumberField({
-    label,
-    errorMessage: errorMessageProp,
-    helperText,
+export function PhoneNumberField({
     controlId,
+    errorMessage,
+    helperText,
+    invalid,
+    label,
     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}
+            invalid={invalid}
             label={label}
             labelTrailing={labelTrailing}
             required={required}
         >
-            {(fieldProps) => (
-                <PhoneNumberInput
-                    aria-label={label}
-                    disableFormatting={disableFormatting}
-                    errorMessage={errorMessage}
-                    initialCountryCode={initialCountryCode}
-                    onChange={onChange}
-                    value={value}
-                    {...fieldProps}
-                    {...inputProps}
-                />
-            )}
+            {(fieldProps) => <PhoneNumberInput {...inputProps} {...fieldProps} aria-label={label} invalid={invalid} />}
         </FormField>
     );
 }
 
-PhoneNumberField.bspkName = 'PhoneNumberField';
-
-export { PhoneNumberField };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/PhoneNumberInput/PhoneNumberInput.tsx

@@ -2,7 +2,6 @@ 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';
@@ -10,6 +9,7 @@ import { Modal } from '-/components/Modal';
 import { TextInput, TextInputProps } from '-/components/TextInput';
 import { useCombobox } from '-/hooks/useCombobox';
 import { useUIContext } from '-/hooks/useUIContext';
+import { FormFieldControlProps } from '-/types/common';
 import { countryCodeData, countryCodes, SupportedCountryCode } from '-/utils/countryCodes';
 import { guessUserCountryCode } from '-/utils/guessUserCountryCode';
 
@@ -36,13 +36,14 @@ const useCountryCodeSelectOptions = (initialCountryCode?: SupportedCountryCode)
     }, []);
 };
 
-export type PhoneNumberInputProps = InvalidPropsLibrary &
+export type PhoneNumberInputProps = FormFieldControlProps &
     Pick<
         TextInputProps,
         | 'aria-label'
         | 'autoComplete'
         | 'disabled'
         | 'inputRef'
+        | 'invalid'
         | 'name'
         | 'placeholder'
         | 'readOnly'
@@ -80,17 +81,17 @@ export type PhoneNumberInputProps = InvalidPropsLibrary &
  *     <PhoneNumberInput aria-label="Phone Number" initialCountryCode="US" value={value} onChange={onChange} />;
  *
  * @name PhoneNumberInput
- * @phase WorkInProgress
+ * @phase UXReview
  */
-function PhoneNumberInput({
-    errorMessage,
+export function PhoneNumberInput({
     value,
     onChange,
     disableFormatting,
     initialCountryCode,
     disabled,
-    invalid,
     readOnly,
+    'aria-describedby': ariaDescribedBy,
+    'aria-errormessage': ariaErrorMessage,
     ...inputProps
 }: PhoneNumberInputProps) {
     const { isMobile } = useUIContext();
@@ -104,9 +105,7 @@ function PhoneNumberInput({
     } = useCombobox({
         placement: 'bottom',
         disabled,
-        invalid,
         readOnly,
-        errorMessage,
     });
 
     const { countryCodeSelectOptions, defaultCountryCode } = useCountryCodeSelectOptions(initialCountryCode);
@@ -147,12 +146,10 @@ function PhoneNumberInput({
     return (
         <div data-bspk="phone-number-input" ref={setRef}>
             <TextInput
-                onChange={handleChange}
-                value={formattedValue}
                 {...inputProps}
+                aria-describedby={ariaDescribedBy || undefined}
+                aria-errormessage={ariaErrorMessage || undefined}
                 disabled={disabled}
-                errorMessage={errorMessage}
-                invalid={invalid}
                 leading={
                     <div style={{ display: 'flex', alignItems: 'center' }}>
                         <button
@@ -165,20 +162,22 @@ function PhoneNumberInput({
                             <SvgIcon name="KeyboardArrowDown" />
                         </button>
                         <Divider orientation="vertical" />
-                        <span aria-label="Country code" style={{ cursor: 'default' }}>{`+${callingCode}`}</span>
+                        <span style={{ cursor: 'default' }}>{`+${callingCode}`}</span>
                     </div>
                 }
+                onChange={handleChange}
                 readOnly={readOnly}
+                value={formattedValue}
             />
             {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}
+                            owner="phone-number-input"
                         >
                             {countryCodeSelectOptions.map((option, index) => (
                                 <ListItem
@@ -186,6 +185,7 @@ function PhoneNumberInput({
                                     aria-selected={countryCode === option.value}
                                     data-bspk="country-code-select-option"
                                     id={`${option.value}-country-code-select-option`}
+                                    includeAriaLabel={false}
                                     key={option.value}
                                     label={option.label}
                                     leading={option.leading}
@@ -201,14 +201,19 @@ function PhoneNumberInput({
                         <Listbox
                             activeIndex={activeIndex}
                             data-bspk-owner="phone-number-input"
+                            includeAriaLabel={false}
                             innerRef={elements.setFloating}
-                            itemDisplayCount={countryCodeSelectOptions.length}
+                            itemCount={countryCodeSelectOptions.length}
+                            itemDisplayCount={
+                                countryCodeSelectOptions.length <= 10 ? countryCodeSelectOptions.length : 10
+                            }
                             items={countryCodeSelectOptions}
                             onChange={(next, event) => {
                                 event?.preventDefault();
                                 closeMenu();
                                 setCountryCode(next[0] as SupportedCountryCode);
                             }}
+                            owner="phone-number-input"
                             selectedValues={[countryCode]}
                             {...menuProps}
                         />
@@ -219,8 +224,4 @@ function PhoneNumberInput({
     );
 }
 
-PhoneNumberInput.bspkName = 'PhoneNumberInput';
-
-export { PhoneNumberInput };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Popover/Popover.tsx

@@ -1,43 +1,53 @@
 import { SvgClose } from '@bspk/icons/Close';
-import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
+import { ReactElement, cloneElement, 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 { Placement, useFloating, UseFloatingProps } from '-/hooks/useFloating';
+import { useId } from '-/hooks/useId';
 import { useOutsideClick } from '-/hooks/useOutsideClick';
+import { CallToActionButton, CommonProps, ElementProps } from '-/types/common';
+import { cssWithVars } from '-/utils/cwv';
+
 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;
-};
+export type PopoverProps = CommonProps<'disabled'> &
+    Pick<UseFloatingProps, 'refWidth'> & {
+        /**
+         * 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;
+        /**
+         * The secondary call to action button properties.
+         *
+         * @type CallToActionButton
+         */
+        secondaryCallToAction?: 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.
@@ -69,9 +79,19 @@ export type PopoverProps = CommonProps<'disabled'> & {
  *     }
  *
  * @name Popover
- * @phase DesignReview
+ * @phase UXReview
  */
-function Popover({ placement = 'top', header, content, callToAction, children, disabled = false }: PopoverProps) {
+export function Popover({
+    placement = 'top',
+    header,
+    content,
+    callToAction,
+    secondaryCallToAction,
+    children,
+    disabled = false,
+    refWidth = false,
+    ...props
+}: ElementProps<PopoverProps, 'div'>) {
     const id = useId();
     const [show, setShow] = useState(false);
     const arrowRef = useRef<HTMLElement | null>(null);
@@ -82,9 +102,13 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
         offsetOptions: 22,
         arrowRef,
         hide: !show,
+        refWidth: refWidth,
     });
 
-    useOutsideClick([elements.floating], () => setShow(false));
+    useOutsideClick({
+        elements: [elements.floating],
+        callback: () => setShow(false),
+    });
 
     const child = useMemo(
         () =>
@@ -97,6 +121,18 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
         [children, disabled, id],
     );
 
+    const basicArrowX = middlewareData?.arrow?.x ? `${middlewareData.arrow.x}px` : '0px';
+
+    const getArrowX = () => {
+        if (middlewareData?.arrow?.x) {
+            if (placement === 'top-start' || placement === 'bottom-start') return '16px';
+            if (placement === 'top' || placement === 'bottom') return `${middlewareData.arrow.x}px`;
+            if (placement === 'top-end' || placement === 'bottom-end')
+                return `${(middlewareData.arrow.x * 2 || 32) - 16}px`;
+        }
+        return '0px';
+    };
+
     return disabled ? (
         children
     ) : (
@@ -111,7 +147,7 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
                         elements.setFloating(node);
                         elements.setReference(document.querySelector<HTMLElement>(`[aria-describedby="${id}"]`));
                     }}
-                    style={floatingStyles}
+                    style={{ ...floatingStyles, ...props.style }}
                 >
                     <header>
                         <Txt variant="heading-h6">{header}</Txt>
@@ -123,25 +159,34 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
                         <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 data-cta-row>
+                            {secondaryCallToAction?.label && secondaryCallToAction?.onClick && (
+                                <Button
+                                    label={secondaryCallToAction.label}
+                                    onClick={secondaryCallToAction.onClick}
+                                    size="small"
+                                    variant="secondary"
+                                />
+                            )}
+                            {callToAction?.label && callToAction?.onClick && (
+                                <Button
+                                    label={callToAction.label}
+                                    onClick={callToAction.onClick}
+                                    size="small"
+                                    variant="primary"
+                                />
+                            )}
+                        </div>
                     </div>
                     <div
                         data-arrow
                         ref={(node) => {
                             arrowRef.current = node;
                         }}
-                        style={{
-                            left: `${middlewareData?.arrow?.x}px`,
-                            top: `${middlewareData?.arrow?.y}px`,
-                        }}
+                        style={cssWithVars({
+                            '--position-left': refWidth ? getArrowX() : basicArrowX,
+                            '--position-top': `${middlewareData?.arrow?.y || 0}px`,
+                        })}
                     />
                 </div>
             </Portal>
@@ -149,8 +194,4 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
     );
 }
 
-Popover.bspkName = 'Popover';
-
-export { Popover };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Popover/PopoverExample.tsx

@@ -1,14 +1,16 @@
+import { PopoverProps } from '.';
 import { Button } from '-/components/Button';
+import { Txt } from '-/components/Txt';
 import { ComponentExampleFn } from '-/utils/demo';
 
-import { PopoverProps } from '.';
-
 export const PopoverExample: ComponentExampleFn<PopoverProps> = ({ action }) => ({
+    containerStyle: { width: '100%' },
     render: ({ props, Component }) => {
         return (
             <>
+                <Txt style={{ marginBottom: `var(--spacing-sizing-02)` }}>Click button for a Popover</Txt>
                 <Component {...props}>
-                    <Button label={`Click me (${props.placement})`} variant="secondary" />
+                    <Button label={`${props.placement}`} variant="secondary" />
                 </Component>
             </>
         );
@@ -18,10 +20,24 @@ export const PopoverExample: ComponentExampleFn<PopoverProps> = ({ action }) =>
             label: 'With CallToAction',
             propState: {
                 callToAction: {
-                    label: 'Click me',
+                    label: 'CTA Button',
                     onClick: () => action('Call to action clicked!'),
                 },
             },
         },
+        {
+            label: 'With both CallToActions',
+            propState: {
+                callToAction: {
+                    label: 'Primary',
+                    onClick: () => action('Primary call to action clicked!'),
+                },
+                secondaryCallToAction: {
+                    label: 'Secondary',
+                    onClick: () => action('Secondary call to action clicked!'),
+                },
+            },
+        },
     ],
+    variants: false,
 });

package/src/components/Popover/popover.scss

@@ -4,10 +4,10 @@
     background: var(--surface-neutral-t1-base);
     box-shadow: var(--drop-shadow-float);
     padding: var(--spacing-sizing-04);
-    width: 300px;
-    border-radius: var(--radius-large);
+    border-radius: var(--radius-lg);
     display: flex;
     flex-direction: column;
+    max-width: 300px;
 
     header {
         display: flex;
@@ -21,7 +21,6 @@
             border: none;
             cursor: pointer;
             padding: 0;
-            margin: 0 0 0 auto;
             color: var(--foreground-neutral-on-surface-variant-01);
             height: var(--spacing-sizing-06);
             width: var(--spacing-sizing-06);
@@ -36,6 +35,8 @@
     --arrow-size: var(--spacing-sizing-02);
     --arrow-offset: calc(var(--arrow-size) * -2);
     --arrow-background-color: var(--surface-neutral-t1-base);
+    --position-left: 0px;
+    --position-top: 0px;
 
     [data-arrow] {
         z-index: 1;
@@ -50,44 +51,36 @@
     &[data-placement^='top'] {
         [data-arrow] {
             bottom: var(--arrow-offset);
+            left: var(--position-left);
             border-top-color: var(--arrow-background-color);
-            filter: drop-shadow(0 2px 1px var(--shadow-10));
+            filter: drop-shadow(0 1px 1px var(--shadow-10));
         }
     }
 
     &[data-placement^='right'] {
         [data-arrow] {
+            top: var(--position-top);
             margin-left: calc(var(--arrow-offset) * 2);
             border-right-color: var(--arrow-background-color);
-            filter: drop-shadow(-2px 0 1px var(--shadow-10));
+            filter: drop-shadow(-1px 0 1px var(--shadow-10));
         }
     }
 
     &[data-placement^='bottom'] {
         [data-arrow] {
-            top: var(--arrow-offset);
+            left: var(--position-left);
+            top: -15px;
             border-bottom-color: var(--arrow-background-color);
-            filter: drop-shadow(0 -2px 1px var(--shadow-10));
-        }
-    }
-
-    &[data-placement='bottom-start'] {
-        [data-arrow] {
-            margin-left: var(--arrow-offset);
-        }
-    }
-
-    &[data-placement='bottom-end'] {
-        [data-arrow] {
-            margin-left: calc(var(--arrow-offset) * -1);
+            filter: drop-shadow(0 -1px 1px var(--shadow-10));
         }
     }
 
     &[data-placement^='left'] {
         [data-arrow] {
+            top: var(--position-top);
             right: var(--arrow-offset);
             border-left-color: var(--arrow-background-color);
-            filter: drop-shadow(2px 0 1px var(--shadow-10));
+            filter: drop-shadow(1px 0 1px var(--shadow-10));
         }
     }
 
@@ -97,16 +90,11 @@
         flex-direction: column;
     }
 
-    [data-call-to-action] {
+    [data-cta-row] {
+        display: flex;
+        align-items: end;
+        gap: var(--spacing-sizing-02);
         margin: 0 0 0 auto;
-
-        /* background: none;
-    border: none;
-    cursor: pointer;
-    padding: 0 var(--spacing-sizing-03);
-    height: var(--spacing-sizing-12);
-    font: var(--labels-small);
-    color: var(--foreground-brand-primary); */
     }
 }
 

package/src/components/Portal/Portal.tsx

@@ -24,19 +24,17 @@ export type PortalProps = {
  * @name Portal
  * @phase Utility
  */
-function Portal({ children, container }: PortalProps) {
+export function Portal({ children, container }: PortalProps) {
     const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(container || null);
 
     useEffect(() => {
         if (!portalContainer && typeof window !== 'undefined') setPortalContainer(document.body);
     }, [portalContainer]);
 
+    if (!portalContainer) return null;
+
     // data-bspk="portal" can't be used here
-    return portalContainer && createPortal(children, portalContainer);
+    return <>{createPortal(children, portalContainer)}</>;
 }
 
-Portal.bspkName = 'Portal';
-
-export { Portal };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ProgressBar/ProgressBar.tsx

@@ -1,5 +1,4 @@
-import { useId } from 'react';
-
+import { useId } from '-/hooks/useId';
 import { cssWithVars } from '-/utils/cwv';
 
 import './progress-bar.scss';
@@ -32,6 +31,20 @@ export type ProgressBarProps = {
     align?: 'center' | 'left';
     /** The label of the progressbar. */
     label: string;
+    /**
+     * If true and completion = 100, displays the progress bar in the success color.
+     *
+     * @deprecated This has a very narrow use-case. See guidelines for more information.
+     * @default false
+     */
+    successColor?: boolean;
+    /**
+     * Whether to hide the success color when the progress bar is complete.
+     *
+     * @deprecated This has a very narrow use-case. See guidelines for more information.
+     * @default false
+     */
+    successHidden?: boolean;
 };
 
 /**
@@ -46,13 +59,28 @@ export type ProgressBarProps = {
  *     }
  *
  * @name ProgressBar
- * @phase DesignReview
+ * @phase UXReview
  */
-function ProgressBar({ size = 'large', completion = 0, align = 'center', label }: ProgressBarProps) {
+export function ProgressBar({
+    size = 'large',
+    completion: completionProp = 0,
+    align = 'center',
+    label,
+    successColor = false,
+    successHidden = false,
+}: ProgressBarProps) {
     const id = useId();
+    const completion = Math.max(0, Math.min(100, Math.round(completionProp))); // Ensure completion is between 0 and 100
+
+    if (successHidden && completion === 100) return null;
 
     return (
-        <div data-align={align} data-bspk="progress-bar" data-size={size}>
+        <div
+            data-align={align}
+            data-bspk="progress-bar"
+            data-size={size}
+            data-success={successColor && completion === 100 ? 'color' : undefined}
+        >
             <progress
                 aria-busy={completion < 100}
                 aria-label="A bounded progress bar from 0 to 100"
@@ -71,8 +99,4 @@ function ProgressBar({ size = 'large', completion = 0, align = 'center', label }
     );
 }
 
-ProgressBar.bspkName = 'ProgressBar';
-
-export { ProgressBar };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */