@bspk/ui 1.1.34 → 1.3.0

package/src/components/Popover/Popover.tsx

@@ -1,44 +1,57 @@
+import './popover.scss';
 import { SvgClose } from '@bspk/icons/Close';
-import { ReactElement, cloneElement, useId, useMemo, useRef, useState } from 'react';
-
-import { CallToActionButton, CommonProps } from '-';
+import { FocusTrap } from 'focus-trap-react';
+import { ReactElement, useRef, useState } from 'react';
 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 './popover.scss';
+import { CallToActionButton, CommonProps, ElementProps } from '-/types/common';
+import { cssWithVars } from '-/utils/cwv';
 
-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 PopoverTriggerProps = {
+    onClick?: () => void;
+    'aria-describedby'?: string;
 };
 
+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 callback to render the trigger element.
+         *
+         * @required
+         */
+        children: (triggerProps: PopoverTriggerProps) => ReactElement;
+    };
+
 /**
  * Brief message that provide additional guidance and helps users perform an action if needed.
  *
@@ -69,9 +82,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,
+    ...props
+}: ElementProps<PopoverProps, 'div'>) {
     const id = useId();
     const [show, setShow] = useState(false);
     const arrowRef = useRef<HTMLElement | null>(null);
@@ -82,75 +105,103 @@ function Popover({ placement = 'top', header, content, callToAction, children, d
         offsetOptions: 22,
         arrowRef,
         hide: !show,
+        refWidth,
     });
 
-    useOutsideClick([elements.floating], () => setShow(false));
+    useOutsideClick({
+        elements: [elements.floating],
+        callback: () => setShow(false),
+    });
 
-    const child = useMemo(
-        () =>
-            !disabled &&
-            children &&
-            cloneElement(children, {
-                onClick: () => setShow((prev) => !prev),
-                'aria-describedby': id,
-            }),
-        [children, disabled, id],
-    );
+    const basicArrowX = middlewareData?.arrow?.x ? `${middlewareData.arrow.x}px` : '0px';
 
-    return disabled ? (
-        children
-    ) : (
+    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';
+    };
+
+    if (disabled) return children({});
+    return (
         <>
-            {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`,
+            {children({
+                onClick: () => setShow(!show),
+                'aria-describedby': id,
+            })}
+            {show && (
+                <Portal>
+                    <FocusTrap
+                        focusTrapOptions={{
+                            fallbackFocus: () => elements.floating || document.body,
+                            clickOutsideDeactivates: true,
                         }}
-                    />
-                </div>
-            </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, ...props.style }}
+                        >
+                            <header>
+                                <Txt variant="heading-h6">{header}</Txt>
+                                <Button
+                                    data-close
+                                    icon={<SvgClose />}
+                                    iconOnly
+                                    label="Close"
+                                    onClick={() => setShow(false)}
+                                    variant="tertiary"
+                                />
+                            </header>
+                            <div data-content>
+                                <Txt as="div" variant="body-small">
+                                    {content}
+                                </Txt>
+                                <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={cssWithVars({
+                                    '--position-left': refWidth ? getArrowX() : basicArrowX,
+                                    '--position-top': `${middlewareData?.arrow?.y || 0}px`,
+                                })}
+                            />
+                        </div>
+                    </FocusTrap>
+                </Portal>
+            )}
         </>
     );
 }
 
-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" />
+                    {(triggerProps) => <Button label={`${props.placement}`} variant="secondary" {...triggerProps} />}
                 </Component>
             </>
         );
@@ -17,11 +19,31 @@ export const PopoverExample: ComponentExampleFn<PopoverProps> = ({ action }) =>
         {
             label: 'With CallToAction',
             propState: {
+                header: 'With CallToAction',
+                content: 'With CallToAction body',
                 callToAction: {
-                    label: 'Click me',
+                    label: 'CTA Button',
                     onClick: () => action('Call to action clicked!'),
                 },
+                children: () => <></>,
+            },
+        },
+        {
+            label: 'With both CallToActions',
+            propState: {
+                header: 'With both CallToActions',
+                content: 'With both CallToActions body',
+                callToAction: {
+                    label: 'Primary',
+                    onClick: () => action('Primary call to action clicked!'),
+                },
+                secondaryCallToAction: {
+                    label: 'Secondary',
+                    onClick: () => action('Secondary call to action clicked!'),
+                },
+                children: () => <></>,
             },
         },
     ],
+    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;
@@ -16,26 +16,17 @@
         margin-bottom: var(--spacing-sizing-02);
         gap: var(--spacing-sizing-04);
 
-        button {
-            background: none;
-            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);
-
-            svg {
-                width: var(--spacing-sizing-06);
-                height: var(--spacing-sizing-06);
-            }
+        [data-bspk='button'][data-close] {
+            margin-right: calc(var(--spacing-sizing-02) * -1);
+            margin-top: calc(var(--spacing-sizing-02) * -1);
         }
     }
 
     --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 +41,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 +80,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.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { Portal } from './Portal';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <Portal>Child content</Portal>;
+
+describe('Portal (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Child content')).toBeInTheDocument();
+    });
+});

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.rtl.test.tsx

@@ -0,0 +1,15 @@
+import { ProgressBar } from './ProgressBar';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <ProgressBar completion={50} label="Example label" />;
+
+describe('ProgressBar (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example label')).toBeInTheDocument();
+    });
+});

package/src/components/ProgressBar/ProgressBar.tsx

@@ -1,8 +1,6 @@
-import { useId } from 'react';
-
-import { cssWithVars } from '-/utils/cwv';
-
 import './progress-bar.scss';
+import { useId } from '-/hooks/useId';
+import { cssWithVars } from '-/utils/cwv';
 
 export type ProgressBarProps = {
     /**
@@ -32,6 +30,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 +58,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 +98,4 @@ function ProgressBar({ size = 'large', completion = 0, align = 'center', label }
     );
 }
 
-ProgressBar.bspkName = 'ProgressBar';
-
-export { ProgressBar };
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/ProgressBar/progress-bar.scss

@@ -34,6 +34,12 @@
         }
     }
 
+    &[data-success='color'] {
+        [data-bar]::after {
+            background-color: var(--status-success);
+        }
+    }
+
     label {
         font-size: var(--labels-small);
         width: 100%;

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

@@ -0,0 +1,15 @@
+import { ProgressCircle } from './ProgressCircle';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => <ProgressCircle label="Example label" />;
+
+describe('ProgressCircle (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByLabelText } = render(<TestBed />);
+
+        expect(getByLabelText('Example label')).toBeInTheDocument();
+    });
+});

package/src/components/ProgressCircle/ProgressCircle.tsx

@@ -1,8 +1,8 @@
-/* eslint-disable react/no-multi-comp */ import { useId } from 'react';
-
+import './progress-circle.scss';
+import { ProgressCircleSVG } from './ProgressCircleSVG';
 import { Txt } from '-/components/Txt';
+import { useId } from '-/hooks/useId';
 import { TxtVariant } from '-/utils/txtVariants';
-import './progress-circle.scss';
 
 export type ProgressCircleProps = {
     /** The label of the progress circle. */
@@ -32,7 +32,7 @@ export type ProgressCircleProps = {
  *     }
  *
  * @name ProgressCircle
- * @phase AccessibilityReview
+ * @phase UXReview
  */
 function ProgressCircle({ label, labelPosition, size = 'medium' }: ProgressCircleProps) {
     let variant: TxtVariant = 'labels-base';
@@ -58,47 +58,8 @@ function ProgressCircle({ label, labelPosition, size = 'medium' }: ProgressCircl
     );
 }
 
-ProgressCircle.bspkName = 'ProgressCircle';
+ProgressCircle.SVG = ProgressCircleSVG;
 
 export { ProgressCircle };
 
-const ProgressCircleSVG = (props: { strokeWidth?: number }) => {
-    const strokeWidth = props.strokeWidth || 10;
-    const width = 100;
-    const id = useId();
-
-    return (
-        <svg {...props} data-animated fill="none" viewBox={`0 0 ${width * 2} ${width * 2}`}>
-            <defs>
-                <linearGradient id={`${id}spinner-secondHalf`}>
-                    <stop offset="50%" stopColor="currentColor" stopOpacity={0} />
-                    <stop offset="100%" stopColor="currentColor" stopOpacity="0.375" />
-                </linearGradient>
-                <linearGradient id={`${id}spinner-firstHalf`}>
-                    <stop offset="0%" stopColor="currentColor" stopOpacity={1} />
-                    <stop offset="100%" stopColor="currentColor" stopOpacity="0.375" />
-                </linearGradient>
-            </defs>
-            <g strokeWidth={strokeWidth * 2}>
-                <path
-                    d={`M ${strokeWidth} ${width} A ${width - strokeWidth} ${width - strokeWidth} 0 0 1 ${width + (width - strokeWidth)} ${width}`}
-                    stroke={`url(#${id}spinner-secondHalf)`}
-                />
-                <path
-                    d={`M ${width + (width - strokeWidth)} ${width} A ${width - strokeWidth} ${width - strokeWidth} 0 0 1 ${strokeWidth} ${width}`}
-                    stroke={`url(#${id}spinner-firstHalf)`}
-                />
-                {/* 1deg extra path to have the round end cap */}
-                <path
-                    d={`M ${strokeWidth} ${width} A ${width - strokeWidth} ${width - strokeWidth} 0 0 1 ${strokeWidth} ${width - 2}`}
-                    stroke="currentColor"
-                    strokeLinecap="round"
-                />
-            </g>
-        </svg>
-    );
-};
-
-ProgressCircle.SVG = ProgressCircleSVG;
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */