@bspk/ui 1.1.31 → 1.1.33

package/src/components/Combobox/Combobox.tsx

@@ -0,0 +1,314 @@
+/* eslint-disable react/no-multi-comp */ import { ReactNode, useMemo } from 'react';
+
+import { CommonProps, ElementProps } from '-';
+import { Checkbox } from '-/components/Checkbox';
+import { ListItem, ListItemProps } from '-/components/ListItem';
+import { Menu, MenuProps } from '-/components/Menu';
+import { Modal, ModalProps } from '-/components/Modal';
+import { ToggleProps, useCombobox, UseComboboxProps } from '-/hooks/useCombobox';
+import { useId } from '-/hooks/useId';
+import { useUIContext } from '-/hooks/useUIContext';
+import { cssWithVars } from '-/utils/cwv';
+
+const DEFAULT = {
+    selectAll: 'Select All',
+};
+
+export const MIN_ITEM_COUNT = 3;
+export const MAX_ITEM_COUNT = 10;
+
+/** The props for the listbox items. */
+export type ComboboxItemProps = CommonProps<'disabled'> &
+    ListItemProps & {
+        /** The content to display in the listbox item. */
+        label: string;
+        /** The value of the listbox item. */
+        value: string;
+    };
+
+export type ComboboxProps<Item extends ComboboxItemProps = ComboboxItemProps> = CommonProps<'data-bspk-owner' | 'id'> &
+    Pick<MenuProps, 'itemDisplayCount'> &
+    Pick<ModalProps, 'description' | 'header'> &
+    Pick<UseComboboxProps, 'disabled' | 'errorMessage' | 'invalid' | 'offsetOptions' | 'readOnly' | 'refWidth'> & {
+        /**
+         * Content to display in the listbox.
+         *
+         * @example
+         *     [
+         *         { value: '1', label: 'Option 1' },
+         *         { value: '2', label: 'Option 2' },
+         *         { value: '3', label: 'Option 3' },
+         *         { value: '4', label: 'Option 4' },
+         *         { value: '5', label: 'Option 5' },
+         *         { value: '6', label: 'Option 6' },
+         *         { value: '7', label: 'Option 7' },
+         *         { value: '8', label: 'Option 8' },
+         *         { value: '9', label: 'Option 9' },
+         *         { value: '10', label: 'Option 10' },
+         *     ];
+         *
+         * @type Array<MenuItem>
+         */
+        items?: Item[];
+        /**
+         * Array of selected values
+         *
+         * @type Array<string>
+         */
+        value?: Array<string>;
+        /**
+         * Whether the listbox allows multiple selections.
+         *
+         * @default false
+         */
+        isMulti?: boolean;
+        /**
+         * The label for the "Select All" option.
+         *
+         * Ignored if `isMulti` is false.
+         *
+         * If `isMulti` is `true`, defaults to "Select All". If a string, it will be used as the label. If false the
+         * select all option will not be rendered.
+         *
+         * @default false
+         */
+        selectAll?: boolean | string;
+        /**
+         * The function to call when the selected values change.
+         *
+         * @example
+         *     (selectedValues, event) => setState({ selectedValues });
+         *
+         * @required
+         */
+        onChange: (selectedValues: string[], event?: React.MouseEvent<HTMLElement, MouseEvent>) => void;
+        /**
+         * The children of the listbox added after the items.
+         *
+         * Usually only used for showing no items found.
+         */
+        children: (params: { setReference: (node: HTMLElement) => void; toggleProps: ToggleProps }) => ReactNode;
+        /**
+         * The label for the select element, used for accessibility, and the dropdown modal header.
+         *
+         * @required
+         */
+        label: string;
+    };
+
+/**
+ * A utility widget that allows users to select one or more items from a list of choices.
+ *
+ * @name Combobox
+ * @phase Utility
+ */
+function Combobox<Item extends ComboboxItemProps>({
+    itemDisplayCount,
+    items = [],
+    onChange,
+    value: selectedValues = [],
+    disabled,
+    id: idProp,
+    isMulti,
+    selectAll: selectAllProp,
+    children,
+    invalid,
+    readOnly,
+    errorMessage,
+    refWidth,
+    offsetOptions = 4,
+    header,
+    description,
+    ...props
+}: ElementProps<ComboboxProps<Item>, 'div'>) {
+    const menuId = useId(idProp);
+    const { isMobile } = useUIContext();
+
+    const { toggleProps, activeIndex, menuProps, closeMenu, isOpen, elements } = useCombobox({
+        refOutsideClick: !isMobile,
+        refWidth,
+        placement: 'bottom-start',
+        disabled,
+        invalid,
+        readOnly,
+        errorMessage,
+        offsetOptions,
+    });
+
+    const selectAll = useMemo((): string | false => {
+        if (!isMulti) return false;
+        if (selectAllProp && typeof selectAllProp === 'string') return selectAllProp;
+        return selectAllProp === true ? DEFAULT.selectAll : false;
+    }, [isMulti, selectAllProp]);
+
+    const allSelected = useMemo(
+        () => !!(items.length && items.every((item) => selectedValues.includes(item.value))),
+        [items, selectedValues],
+    );
+
+    if (!isOpen) return <>{children({ toggleProps, setReference: elements.setReference })}</>;
+
+    /* data-bspk="combobox" -- I don't need a wrapper here and this passes lint. :) */
+    return (
+        <>
+            {children({ toggleProps, setReference: elements.setReference })}
+            {isMobile ? (
+                <Modal
+                    data-bspk-owner={props['data-bspk-owner'] || undefined}
+                    description={description}
+                    header={header}
+                    onClose={closeMenu}
+                    open={isOpen}
+                >
+                    <ListItems
+                        activeIndex={activeIndex}
+                        allSelected={allSelected}
+                        data-testid="listbox-items"
+                        isMulti={isMulti}
+                        items={items}
+                        menuId={menuId}
+                        onChange={(next) => {
+                            onChange(next);
+                            if (!isMulti) closeMenu();
+                        }}
+                        selectAll={selectAll}
+                        selectedValues={selectedValues}
+                    />
+                </Modal>
+            ) : (
+                <Menu
+                    aria-multiselectable={isMulti || undefined}
+                    data-bspk="listbox"
+                    data-disabled={disabled || undefined}
+                    data-no-items={!items.length || undefined}
+                    id={menuId}
+                    innerRef={(node) => {
+                        elements.setFloating(node);
+                    }}
+                    itemCount={items.length}
+                    itemDisplayCount={itemDisplayCount}
+                    onOutsideClick={closeMenu}
+                    role="listbox"
+                    style={cssWithVars({
+                        ...props.style,
+                        ...menuProps.style,
+                    })}
+                    tabIndex={-1}
+                >
+                    <ListItems
+                        activeIndex={activeIndex}
+                        allSelected={allSelected}
+                        data-testid="listbox-items"
+                        isMulti={isMulti}
+                        items={items}
+                        menuId={menuId}
+                        onChange={(nextValue) => {
+                            onChange(nextValue);
+                            if (!isMulti) closeMenu();
+                        }}
+                        selectAll={selectAll}
+                        selectedValues={selectedValues}
+                    />
+                </Menu>
+            )}
+        </>
+    );
+}
+
+Combobox.bspkName = 'Combobox';
+
+export { Combobox };
+
+// ListItems component to render the items in the listbox or modal.
+// This is a separate component to keep the Combobox component clean and focused on its main functionality
+function ListItems({
+    isMulti = false,
+    items = [],
+    activeIndex,
+    selectedValues = [],
+    onChange,
+    selectAll = false,
+    menuId = '',
+    allSelected = false,
+}: {
+    isMulti?: boolean;
+    items?: ComboboxItemProps[];
+    activeIndex?: number;
+    selectedValues?: string[];
+    onChange?: (nextSelectedValues: string[], event?: React.MouseEvent<HTMLElement, MouseEvent>) => void;
+    selectAll?: string | false;
+    menuId?: string;
+    allSelected?: boolean;
+}) {
+    const multiSelectValue = (selected: boolean, itemValue: string) => {
+        return selected ? selectedValues.filter((value) => value !== itemValue) : [...selectedValues, itemValue];
+    };
+
+    return (
+        <>
+            {isMulti && selectAll && (
+                <ListItem
+                    data-selected={allSelected || undefined}
+                    key="select-all"
+                    label={selectAll}
+                    onClick={(event: React.MouseEvent<HTMLElement, MouseEvent>) => {
+                        onChange?.(allSelected ? [] : items.map((item) => item.value), event);
+                    }}
+                    role="option"
+                    tabIndex={-1}
+                    trailing={
+                        <Checkbox
+                            aria-label={selectAll}
+                            checked={!!allSelected}
+                            indeterminate={!allSelected && selectedValues.length > 0}
+                            name=""
+                            onChange={(checked) => {
+                                onChange?.(checked ? items.map((item) => item.value) : []);
+                            }}
+                            value=""
+                        />
+                    }
+                />
+            )}
+            {items.map((item, index) => {
+                const selected = Boolean(Array.isArray(selectedValues) && selectedValues.includes(item.value));
+                return (
+                    <ListItem
+                        {...item}
+                        active={activeIndex === index || undefined}
+                        aria-disabled={item.disabled || undefined}
+                        aria-posinset={index + 1}
+                        as="button"
+                        disabled={item.disabled || undefined}
+                        id={`${menuId}-item-${index}`}
+                        key={`${menuId}-item-${index}`}
+                        label={item.label}
+                        onClick={(event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+                            onChange?.(isMulti ? multiSelectValue(selected, item.value) : [item.value], event);
+                        }}
+                        role="option"
+                        selected={selected || undefined}
+                        tabIndex={-1}
+                        trailing={
+                            isMulti ? (
+                                <Checkbox
+                                    aria-label={item.label}
+                                    checked={selected}
+                                    name={item.value}
+                                    onChange={(checked) => {
+                                        onChange?.(multiSelectValue(checked, item.value));
+                                    }}
+                                    value={item.value}
+                                />
+                            ) : (
+                                item.trailing || undefined
+                            )
+                        }
+                    />
+                );
+            })}
+        </>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Combobox/index.tsx

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

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';