@bspk/ui 1.1.32 → 1.1.33

package/src/components/Dialog/Dialog.tsx

@@ -0,0 +1,175 @@
+import { FocusTrap } from 'focus-trap-react';
+import { ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+
+import { CommonProps, ElementProps, SetRef } from '-';
+import { Portal } from '-/components/Portal';
+import { Scrim } from '-/components/Scrim';
+import { useId } from '-/hooks/useId';
+import { useOutsideClick } from '-/hooks/useOutsideClick';
+import './dialog.scss';
+
+export type DialogProps = CommonProps<'data-bspk-owner' | 'id'> & {
+    /** The content of the dialog. */
+    children?: ReactNode;
+    /** A ref to the dialog element. */
+    innerRef?: SetRef<HTMLDivElement>;
+    /**
+     * If the dialog should appear.
+     *
+     * @example
+     *     false;
+     *
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Function to call when the dialog is closed.
+     *
+     * @type () => void
+     * @required
+     */
+    onClose: () => void;
+    /**
+     * The placement of the dialog on the screen.
+     *
+     * @default center
+     */
+    placement?: 'bottom' | 'center' | 'left' | 'right' | 'top';
+    /**
+     * Whether the dialog should have a scrim behind it.
+     *
+     * @default true
+     */
+    showScrim?: boolean;
+};
+
+/**
+ * Dialogs display important information that users need to acknowledge. They appear over the interface and block
+ * further interactions until an action is selected.
+ *
+ * @example
+ *     import { Dialog } from '@bspk/ui/Dialog';
+ *     import { Button } from '@bspk/ui/Button';
+ *
+ *     function Example() {
+ *         const [open, setOpen] = React.useState(false);
+ *
+ *         return (
+ *             <>
+ *                 <Button label="Open Dialog" onClick={() => setOpen(true)} />
+ *                 <Dialog open={open} onClose={() => setOpen(false)}>
+ *                     <h1>Dialog Title</h1>
+ *                     <p>This is the content of the dialog.</p>
+ *                     <button onClick={() => setOpen(false)}>Close</button>
+ *                 </Dialog>
+ *             </>
+ *         );
+ *     }
+ *
+ * @name Dialog
+ * @phase Utility
+ */
+function Dialog({
+    //
+    children,
+    innerRef,
+    onClose,
+    open,
+    placement = 'center',
+    showScrim = true,
+    id: idProp,
+    ...containerProps
+}: ElementProps<DialogProps, 'div'>) {
+    const id = useId(idProp);
+    const boxRef = useRef<HTMLDivElement | null>(null);
+    const [visibility, setVisibilityState] = useState<'hidden' | 'hiding' | 'show' | 'showing'>(
+        open ? 'show' : 'hidden',
+    );
+
+    const prevVisibility = useRef(visibility);
+
+    const setVisibility = useCallback((next: typeof visibility) => {
+        setVisibilityState((prev) => {
+            prevVisibility.current = prev;
+            return next;
+        });
+    }, []);
+
+    const handleKeyDown = useCallback((e: KeyboardEvent) => e.key === 'Escape' && onClose(), [onClose]);
+
+    useEffect(() => {
+        if (open) {
+            if (prevVisibility.current.startsWith('show')) return;
+            setVisibility('showing');
+            return;
+        }
+
+        if (prevVisibility.current.startsWith('hid')) return;
+        setVisibility('hiding');
+    }, [open, setVisibility]);
+
+    useEffect(() => {
+        if (prevVisibility.current === visibility) return;
+
+        if (visibility === 'showing') {
+            document.body.style.overflow = 'hidden';
+            setTimeout(() => setVisibility('show'), 10);
+        }
+
+        if (visibility === 'hiding') {
+            document.body.style.overflow = '';
+            setTimeout(() => setVisibility('hidden'), 10);
+        }
+    }, [setVisibility, visibility]);
+
+    useEffect(() => {
+        if (visibility.startsWith('hid')) return;
+
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [handleKeyDown, visibility]);
+
+    useOutsideClick([boxRef.current], onClose, !open);
+
+    return (
+        visibility !== 'hidden' && (
+            <Portal>
+                <Scrim data-bspk-owner="dialog" onClick={onClose} variant="dialog" visible={showScrim !== false} />
+                <div
+                    {...containerProps}
+                    data-bspk="dialog"
+                    data-placement={placement}
+                    data-visibility={visibility}
+                    id={id}
+                    ref={innerRef}
+                    role="presentation"
+                >
+                    <FocusTrap
+                        focusTrapOptions={{
+                            fallbackFocus: () => boxRef.current!,
+                            clickOutsideDeactivates: true,
+                        }}
+                    >
+                        <div
+                            data-dialog-box
+                            ref={(node) => {
+                                boxRef.current = node;
+                            }}
+                            tabIndex={-1}
+                        >
+                            {children}
+                        </div>
+                    </FocusTrap>
+                </div>
+            </Portal>
+        )
+    );
+}
+
+Dialog.bspkName = 'Dialog';
+
+export { Dialog };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Dialog/DialogExample.tsx

@@ -0,0 +1,27 @@
+import { Button } from '-/components/Button';
+import { ComponentExample } from '-/utils/demo';
+
+import { DialogProps } from '.';
+
+export const DialogExample: ComponentExample<DialogProps> = {
+    render: ({ props, setState, Component }) => {
+        const label = 'Open Dialog';
+
+        const { children, ...modalProps } = props;
+
+        return (
+            <>
+                <Button label={label} onClick={() => setState({ open: true })} />
+                <Component
+                    data-example-component
+                    id="exampleId"
+                    {...modalProps}
+                    onClose={() => setState({ open: false })}
+                >
+                    {children}
+                </Component>
+            </>
+        );
+    },
+    hideVariants: true,
+};

package/src/components/Dialog/dialog.scss

@@ -0,0 +1,153 @@
+[data-bspk='dialog'] {
+    position: fixed;
+    inset: 0;
+    z-index: var(--z-index-dialog);
+
+    [data-dialog-box] {
+        text-align: start;
+        position: relative;
+        border-radius: var(--radius-large);
+        box-shadow: var(--drop-shadow-float);
+        background: var(--surface-neutral-t1-base);
+        color: var(--foreground-neutral-on-surface);
+        max-height: calc(100vh - var(--spacing-sizing-24));
+        z-index: 2;
+
+        > :first-of-type {
+            margin-top: 0;
+        }
+
+        > :last-child {
+            margin-bottom: 0;
+        }
+
+        width: calc(100% - var(--spacing-sizing-08));
+
+        // we make the width responsive to the viewport
+        @media (width >= 640px) {
+            width: 90%;
+        }
+
+        @media (width >= 768px) {
+            width: 80%;
+        }
+
+        @media (width >= 1024px) {
+            width: 60%;
+        }
+
+        @media (width >= 1280px) {
+            width: 50%;
+        }
+    }
+
+    [data-dialog-backdrop] {
+        z-index: 1;
+        position: fixed;
+        inset: 0;
+        background-color: var(--background-scrim);
+        opacity: 0;
+        transition: opacity 0.3s;
+    }
+
+    &[data-visibility='show'] {
+        [data-dialog-backdrop] {
+            opacity: 1;
+        }
+    }
+
+    &[data-placement='center'] {
+        display: flex;
+        justify-content: center;
+        align-items: center;
+
+        [data-dialog-box] {
+            transition: opacity 1s;
+            opacity: 0;
+        }
+
+        &[data-visibility='show'] {
+            [data-dialog-box] {
+                opacity: 1;
+            }
+        }
+    }
+
+    &[data-placement='bottom'] {
+        [data-dialog-box] {
+            position: absolute;
+            border-bottom-left-radius: 0;
+            border-bottom-right-radius: 0;
+            width: 600px;
+            left: 50%;
+            transform: translateX(-50%);
+            bottom: -100vh;
+            transition: bottom 0.3s;
+        }
+
+        &[data-visibility='show'] {
+            [data-dialog-box] {
+                bottom: 0;
+            }
+        }
+    }
+
+    &[data-placement='top'] {
+        [data-dialog-box] {
+            position: absolute;
+            border-top-left-radius: 0;
+            border-top-right-radius: 0;
+            width: 600px;
+            left: 50%;
+            transform: translateX(-50%);
+            top: -100vh;
+            transition: top 0.3s;
+        }
+
+        &[data-visibility='show'] {
+            [data-dialog-box] {
+                top: 0;
+            }
+        }
+    }
+
+    &[data-placement='left'] {
+        [data-dialog-box] {
+            position: absolute;
+            max-height: unset;
+            width: 280px;
+            height: 100vh;
+            border-bottom-left-radius: 0;
+            border-top-left-radius: 0;
+            left: -100vw;
+            transition: left 0.3s;
+        }
+
+        &[data-visibility='show'] {
+            [data-dialog-box] {
+                left: 0;
+            }
+        }
+    }
+
+    &[data-placement='right'] {
+        [data-dialog-box] {
+            position: absolute;
+            max-height: unset;
+            width: 280px;
+            height: 100vh;
+            border-bottom-right-radius: 0;
+            border-top-right-radius: 0;
+            right: -100vw;
+            transition: right 0.3s;
+        }
+
+        &[data-visibility='show'] {
+            [data-dialog-box] {
+                right: 0;
+            }
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Dialog/index.tsx

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

package/src/components/Divider/Divider.tsx

@@ -0,0 +1,90 @@
+import { ElementProps } from '-';
+import { cssWithVars } from '-/utils/cwv';
+import './divider.scss';
+
+export type DividerProps = {
+    /**
+     * The orientation of the divider.
+     *
+     * @default horizontal
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * The thickness of the divider.
+     *
+     * @default light
+     */
+    thickness?: 'heavy' | 'light';
+    /**
+     * If the divider padding is shown.
+     *
+     * @default true
+     */
+    padding?: boolean;
+    /**
+     * The inset (margin) of the divider. The value is a number between 0 and 12, which corresponds to the spacing
+     * sizing variables defined in the theme. The inset is applied to the left and right sides of the divider when the
+     * orientation is horizontal, and to the top and bottom when the orientation is vertical.
+     *
+     * @default 0
+     */
+    inset?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+};
+
+const insetToVariable = (insetProp: number | string) => {
+    const inset = Number(insetProp);
+    if (inset === undefined || inset === null || inset < 1 || inset > 12) return '0px';
+    return `var(--spacing-sizing-${inset.toString().padStart(2, '0')})`;
+};
+
+/**
+ * Horizontal thin lines that separates grouped content in a list or other containers with an optional section/group
+ * label.
+ *
+ * Vertical thin lines that separates grouped content or other visual elements within a container.
+ *
+ * @example
+ *     import { Divider } from '@bspk/ui/Divider';
+ *
+ *     function Example() {
+ *         return (
+ *             <div>
+ *                 <p>Content above the divider</p>
+ *                 <Divider orientation="horizontal" />
+ *                 <p>Content below the divider</p>
+ *             </div>
+ *         );
+ *     }
+ *
+ * @name Divider
+ * @phase DesignReview
+ */
+function Divider({
+    padding = true,
+    orientation = 'horizontal',
+    thickness = 'light',
+    inset = 0,
+    ...props
+}: ElementProps<DividerProps, 'div'>) {
+    return (
+        <div
+            {...props}
+            aria-orientation={orientation}
+            data-bspk="divider"
+            data-hide-padding={!padding || undefined}
+            data-orientation={orientation}
+            data-thickness={thickness}
+            role="separator"
+            style={cssWithVars({
+                ...props.style,
+                '--inset': insetToVariable(inset),
+            })}
+        />
+    );
+}
+
+Divider.bspkName = 'Divider';
+
+export { Divider };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Divider/DividerExample.tsx

@@ -0,0 +1,26 @@
+import { CSSProperties } from 'react';
+
+import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
+import { ComponentExample } from '-/utils/demo';
+
+export const DividerExample: ComponentExample = {
+    render: ({ props, Component }) => {
+        const style: CSSProperties =
+            props.orientation === 'vertical' ? { height: 300, width: 100 } : { height: 100, width: '300px' };
+        return (
+            <div
+                style={{
+                    display: 'flex',
+                    flexDirection: props.orientation === 'vertical' ? 'row' : 'column',
+                    alignItems: props.orientation === 'vertical' ? 'center' : 'stretch',
+                    justifyContent: props.orientation === 'vertical' ? 'center' : 'stretch',
+                    maxWidth: props.orientation !== 'vertical' ? '300px' : 'auto',
+                }}
+            >
+                <ExamplePlaceholder direction={props.orientation !== 'vertical' ? 'row' : 'column'} style={style} />
+                <Component {...props} />
+                <ExamplePlaceholder direction={props.orientation !== 'vertical' ? 'row' : 'column'} style={style} />
+            </div>
+        );
+    },
+};

package/src/components/Divider/index.tsx

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

package/src/components/EmptyState/EmptyState.tsx

@@ -0,0 +1,91 @@
+import { ReactNode } from 'react';
+
+import { CallToActionButton } from '-';
+import { Button } from '-/components/Button';
+import { Layout } from '-/components/Layout';
+import { Txt } from '-/components/Txt';
+
+export type EmptyStateProps = {
+    /** The image or icon to display in the empty state. */
+    children?: ReactNode;
+    /**
+     * The header of the empty state.
+     *
+     * @required
+     */
+    header: string;
+    /**
+     * The body of the empty state.
+     *
+     * @type multiline
+     * @required
+     */
+    body: string;
+    /**
+     * The text alignment of the body.
+     *
+     * @default center
+     */
+    bodyAlign?: 'center' | 'left';
+    /**
+     * Optional CallToActionButton properties.
+     *
+     * @type CallToActionButton
+     */
+    callToAction?: CallToActionButton;
+};
+
+/**
+ * A design pattern component that indicates to users that system has no content to display.
+ *
+ * @example
+ *     import { EmptyState } from '@bspk/ui/EmptyState';
+ *
+ *     export function Example() {
+ *         return (
+ *             <EmptyState body="Example body" header="Example header">
+ *                 Example EmptyState
+ *             </EmptyState>
+ *         );
+ *     }
+ *
+ * @name EmptyState
+ * @phase DesignReview
+ */
+function EmptyState({ children, header, body, callToAction, bodyAlign = 'center' }: EmptyStateProps) {
+    return (
+        <Layout
+            align="center"
+            column
+            data-bspk="empty-state"
+            style={{
+                margin: 'var(--spacing-sizing-04)',
+                maxWidth: '500px',
+            }}
+        >
+            {children}
+            <Layout align="center" column gap="4">
+                <Txt as="header" variant="heading-h5">
+                    {header}
+                </Txt>
+                <Txt as="p" style={{ textAlign: bodyAlign }} variant="body-base">
+                    {body}
+                </Txt>
+            </Layout>
+            {callToAction && (
+                <Button
+                    label={callToAction.label}
+                    onClick={callToAction.onClick}
+                    size={callToAction.size || 'medium'}
+                    variant="primary"
+                />
+            )}
+        </Layout>
+    );
+}
+
+EmptyState.bspkName = 'EmptyState';
+
+export { EmptyState };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/EmptyState/EmptyStateExample.tsx

@@ -0,0 +1,37 @@
+import { ExamplePlaceholder } from '-/components/ExamplePlaceholder';
+import { ComponentExampleFn } from '-/utils/demo';
+
+import { EmptyStateProps } from '.';
+
+export const EmptyStateExample: ComponentExampleFn<EmptyStateProps> = ({ action }) => ({
+    containerStyle: { width: '100%' },
+    render: ({ props: { children, ...props }, context, Component }) => (
+        <Component {...props}>
+            {context?.preset?.label === 'With Image' ? (
+                <ExamplePlaceholder
+                    style={{
+                        height: '200px',
+                        width: '60%',
+                        minWidth: '250px',
+                    }}
+                />
+            ) : (
+                children
+            )}
+        </Component>
+    ),
+    presets: [
+        {
+            label: 'With CallToAction',
+            propState: {
+                callToAction: {
+                    label: 'Add payment method',
+                    onClick: () => action('Add payment method clicked!'),
+                },
+            },
+        },
+        {
+            label: 'With Image',
+        },
+    ],
+});

package/src/components/EmptyState/index.tsx

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

package/src/components/ExamplePlaceholder/ExamplePlaceholder.tsx

@@ -0,0 +1,56 @@
+import { useRef } from 'react';
+
+import { ElementProps } from '-';
+import { Txt } from '-/components/Txt';
+
+const dimension = (value: number | string) => (typeof value === 'number' ? `${value}px` : `${value}`);
+
+/**
+ * A utility component that serves as a placeholder for examples.
+ *
+ * @name ExamplePlaceholder
+ * @phase Utility
+ */
+function ExamplePlaceholder({
+    hideSize = false,
+    height = 100,
+    width = '100%',
+    direction = 'row',
+    ...props
+}: ElementProps<
+    {
+        hideSize?: boolean;
+        height?: number | string;
+        width?: number | string;
+        direction?: 'column' | 'row';
+    },
+    'div'
+>) {
+    const ref = useRef<HTMLDivElement | null>(null);
+
+    return (
+        <div
+            {...props}
+            data-example-placeholder
+            ref={ref}
+            style={{
+                ...props.style,
+                width: dimension(width),
+                height: dimension(height),
+                flexDirection: direction,
+            }}
+        >
+            {!hideSize && (
+                <>
+                    <Txt variant="labels-large">{dimension(width)}</Txt>
+                    <Txt>&times;</Txt>
+                    <Txt variant="labels-large">{dimension(height)}</Txt>
+                </>
+            )}
+        </div>
+    );
+}
+
+ExamplePlaceholder.bspkName = 'ExamplePlaceholder';
+
+export { ExamplePlaceholder };

package/src/components/ExamplePlaceholder/index.tsx

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