@bspk/ui 1.1.32 → 1.1.34

package/src/components/Modal/Modal.tsx

@@ -0,0 +1,214 @@
+import { SvgClose } from '@bspk/icons/Close';
+import { ReactNode, useMemo, useRef } from 'react';
+
+import { CallToActionButton } from '-';
+import { Button, ButtonProps } from '-/components/Button';
+import { DialogProps, Dialog } from '-/components/Dialog';
+import { Txt } from '-/components/Txt';
+import { useEventListener } from '-/hooks/useAddEventListener';
+import { useDebounceCallback } from '-/hooks/useDebounceCallback';
+import { useUIContext } from '-/hooks/useUIContext';
+import './modal.scss';
+
+// This hook is used to set the height of the modal based on the dialog box height.
+// It listens to the resize event and updates the modal height accordingly.
+function useDialogHeight() {
+    const onResize = () => {
+        const { dialogBox, modal } = modalRefs.current || {};
+        if (!dialogBox || !modal) return;
+        modal.style.height = `${dialogBox.offsetHeight}px`;
+        modal.style.visibility = '';
+    };
+
+    useEventListener('resize', useDebounceCallback(onResize, 100));
+
+    const modalRefs = useRef<{
+        dialogBox: HTMLDivElement | null;
+        modal: HTMLDivElement | null;
+    } | null>(null);
+
+    return {
+        setModalRefs: (node: HTMLElement | null) => {
+            if (!node) return;
+            const dialogBox = node.querySelector<HTMLDivElement>('[data-dialog-box]');
+            const modal = node.querySelector<HTMLDivElement>('[data-bspk="modal"]');
+            modalRefs.current = {
+                dialogBox,
+                modal,
+            };
+            if (!dialogBox || !modal) return;
+            modal.style.height = `${dialogBox.offsetHeight}px`;
+            modal.style.visibility = '';
+        },
+    };
+}
+
+export type ModalCallToAction = Pick<ButtonProps, 'destructive'> & Pick<CallToActionButton, 'label' | 'onClick'>;
+
+export type ModalProps = Pick<DialogProps, 'data-bspk-owner' | 'id' | 'innerRef' | 'onClose' | 'open'> & {
+    /**
+     * Modal header.
+     *
+     * @example
+     *     Change your email
+     *
+     * @required
+     */
+    header: string;
+    /**
+     * Modal description. Used for the
+     * [aria-description](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-description)
+     * attribute.
+     *
+     * @example
+     *     Email change confirmation.
+     *
+     * @required
+     */
+    description: string;
+    /**
+     * Whether to show the cancel button in the footer.
+     *
+     * Providing a string will set the label of the cancel button.
+     *
+     * @default false
+     */
+    cancelButton?: boolean | string;
+    /**
+     * The call to action button to display in the footer of the modal.
+     *
+     * @example
+     *     {
+     *     label: 'Confirm',
+     *     onClick: () => action('Confirm clicked'),
+     *     }
+     */
+    callToAction?: ModalCallToAction;
+    /**
+     * The format of the buttons in the footer. Ignored if not mobile.
+     *
+     * @default horizontal
+     */
+    buttonFormat?: 'horizontal' | 'vertical';
+    /**
+     * The content of the modal.
+     *
+     * @example
+     *     Are you sure you want to change your email address? A confirmation email will be sent to your new address to verify the change. Please check your inbox and follow the instructions to complete the process.
+     *
+     * @type multiline
+     */
+    children?: ReactNode;
+};
+
+/**
+ * Modals display important information that users need to acknowledge. They appear over the interface and block further
+ * interactions until an action is selected. Modal is a wrapper around the Dialog component that provides a header and
+ * footer for the dialog.
+ *
+ * @example
+ *     import React from 'react';
+ *
+ *     import { Button } from '@bspk/ui/Button';
+ *     import { Modal } from '@bspk/ui/Modal';
+ *
+ *     export function Example() {
+ *         const [open, setOpen] = React.useState(false);
+ *
+ *         return (
+ *             <>
+ *                 <Button label="Open Dialog" onClick={() => setOpen(true)} />
+ *                 <Modal
+ *                     description="Example description"
+ *                     header="Example header"
+ *                     onClose={() => setOpen(false)}
+ *                     open={open}
+ *                 >
+ *                     Example Modal
+ *                 </Modal>
+ *             </>
+ *         );
+ *     }
+ *
+ * @ignoreRefs ButtonProps
+ *
+ * @name Modal
+ * @phase WorkInProgress
+ */
+function Modal({
+    header,
+    description,
+    children,
+    callToAction,
+    cancelButton,
+    buttonFormat = 'horizontal',
+    innerRef,
+    ...dialogProps
+}: ModalProps) {
+    const { isMobile } = useUIContext();
+
+    const buttons: ButtonProps[] = useMemo(() => {
+        const nextButtons: ButtonProps[] = [];
+
+        if (callToAction) {
+            nextButtons.push({
+                ...callToAction,
+                variant: 'primary',
+                size: isMobile ? 'medium' : 'small',
+            });
+        }
+
+        if (callToAction && cancelButton) {
+            nextButtons.push({
+                label: typeof cancelButton === 'string' ? cancelButton : 'Cancel',
+                onClick: dialogProps.onClose,
+                variant: 'tertiary',
+                size: isMobile ? 'medium' : 'small',
+            });
+        }
+
+        return nextButtons;
+    }, [callToAction, cancelButton, dialogProps.onClose, isMobile]);
+
+    const { setModalRefs } = useDialogHeight();
+
+    return (
+        <Dialog
+            {...dialogProps}
+            aria-description={description}
+            aria-label={header}
+            innerRef={setModalRefs}
+            placement="center"
+            showScrim={true}
+        >
+            <div data-bspk="modal" ref={(node) => innerRef?.(node)} style={{ visibility: 'hidden' }}>
+                <header>
+                    <Txt as="div" data-dialog-title variant="heading-h4">
+                        {header}
+                    </Txt>
+                    <Button
+                        icon={<SvgClose />}
+                        label="close"
+                        onClick={dialogProps.onClose}
+                        showLabel={false}
+                        variant="tertiary"
+                    />
+                </header>
+                <main>{children}</main>
+                {Array.isArray(buttons) && buttons.length > 0 && (
+                    <footer data-button-format={buttonFormat}>
+                        {buttons.map((buttonProps, idx) => (
+                            <Button key={idx} {...buttonProps} size={isMobile ? 'medium' : 'small'} />
+                        ))}
+                    </footer>
+                )}
+            </div>
+        </Dialog>
+    );
+}
+
+Modal.bspkName = 'Modal';
+
+export { Modal };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Modal/ModalExample.tsx

@@ -0,0 +1,74 @@
+import { Button } from '-/components/Button';
+import { Checkbox } from '-/components/Checkbox';
+import { ListItem } from '-/components/ListItem';
+import { ComponentExampleFn } from '-/utils/demo';
+
+import { ModalProps, Modal } from '.';
+
+export const ModalExample: ComponentExampleFn<ModalProps> = ({ action }) => ({
+    hideVariants: true,
+    render: ({ props, setState }) => {
+        const label = 'Open Modal';
+
+        const { children, ...modalProps } = props;
+
+        return (
+            <>
+                <Button label={label} onClick={() => setState({ open: true })} />
+                <Modal data-example-component id="exampleId" {...modalProps} onClose={() => setState({ open: false })}>
+                    {children}
+                </Modal>
+            </>
+        );
+    },
+    presets: [
+        // confirmation modal
+        {
+            value: 'confirmation',
+            label: 'Modal (confirmation)',
+            propState: {
+                header: 'Confirmation Modal',
+                description: 'This modal has a call to action and a cancel button.',
+                children: (
+                    <>
+                        <p>
+                            This is a confirmation modal. It has a call to action and a cancel button. The call to
+                            action is the primary button and the cancel button is the tertiary button.
+                        </p>
+                    </>
+                ),
+                callToAction: {
+                    label: 'Call to Action',
+                    onClick: () => action('Call to Action clicked'),
+                },
+                cancelButton: 'Cancel',
+            },
+        },
+        {
+            value: 'super long content',
+            label: 'Modal (scrolling)',
+            propState: {
+                header: 'Header Only',
+                description: 'This modal has no buttons.',
+                children: (
+                    <>
+                        <p>
+                            This is a demo of a scrolling modal. Most modals won&apos;t scroll but mobile uses modals as
+                            dropdowns which may have more items than can fit in the screen.
+                        </p>
+                        {Array(30)
+                            .fill('')
+                            .map((_, index) => (
+                                <ListItem
+                                    key={`key${index}`}
+                                    label={`Option ${index + 1}`}
+                                    onClick={() => action(`Option ${index + 1} clicked`)}
+                                    trailing={<Checkbox aria-label="" name="" onChange={() => {}} value="" />}
+                                />
+                            ))}
+                    </>
+                ),
+            },
+        },
+    ],
+});

package/src/components/Modal/index.tsx

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

package/src/components/Modal/modal.scss

@@ -0,0 +1,47 @@
+[data-bspk='modal'] {
+    max-height: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-sizing-02);
+    padding: var(--spacing-sizing-04);
+
+    > header {
+        display: flex;
+        flex-direction: row;
+        justify-content: space-between;
+        align-items: center;
+        gap: var(--spacing-sizing-04);
+    }
+
+    main {
+        flex: 1;
+        overflow-y: auto;
+        max-height: fit-content;
+    }
+
+    > footer {
+        display: flex;
+        flex-direction: row-reverse;
+        justify-content: flex-start;
+        gap: var(--spacing-sizing-04);
+    }
+
+    // we make the width responsive to the viewport
+    @media (width < 640px) {
+        > footer {
+            [data-bspk='button'] {
+                width: 50%;
+            }
+
+            &[data-button-format='vertical'] {
+                flex-direction: column-reverse;
+
+                [data-bspk='button'] {
+                    width: 100%;
+                }
+            }
+        }
+    }
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/NumberField/NumberField.tsx

@@ -0,0 +1,79 @@
+import { FormFieldProps, FormField } from '-/components/FormField';
+import { NumberInputProps, NumberInput } from '-/components/NumberInput';
+
+export type NumberFieldProps = Pick<
+    NumberInputProps,
+    | 'align'
+    | 'disabled'
+    | 'errorMessage'
+    | 'id'
+    | 'invalid'
+    | 'max'
+    | 'min'
+    | 'name'
+    | 'onChange'
+    | 'readOnly'
+    | 'size'
+    | 'value'
+> &
+    Pick<FormFieldProps, 'controlId' | 'helperText' | 'label' | 'labelTrailing' | 'required'>;
+
+/**
+ * A input element that allows users to either input a numerical value or singularly increase or decrease the values by
+ * pressing the (+) or (-).
+ *
+ * This component takes properties from the FormField and NumberInput components.
+ *
+ * @example
+ *     import React from 'react';
+ *
+ *     import { NumberField } from '@bspk/ui/NumberField';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState<number>();
+ *
+ *         return (
+ *             <NumberField
+ *                 controlId="Example controlId"
+ *                 label="Example label"
+ *                 name="Example name"
+ *                 onChange={(nextValue) => setState(nextValue)}
+ *                 value={state}
+ *             />
+ *         );
+ *     }
+ *
+ * @name NumberField
+ * @phase DesignReview
+ */
+function NumberField({
+    label,
+    errorMessage: errorMessageProp,
+    helperText,
+    controlId,
+    labelTrailing,
+    required,
+    ...inputProps
+}: NumberFieldProps) {
+    const errorMessage = (!inputProps.readOnly && !inputProps.disabled && errorMessageProp) || undefined;
+
+    return (
+        <FormField
+            controlId={controlId}
+            data-bspk="number-field"
+            errorMessage={errorMessage}
+            helperText={helperText}
+            label={label}
+            labelTrailing={labelTrailing}
+            required={required}
+        >
+            {(fieldProps) => <NumberInput {...inputProps} {...fieldProps} aria-label={label} id={controlId} />}
+        </FormField>
+    );
+}
+
+NumberField.bspkName = 'NumberField';
+
+export { NumberField };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/NumberField/index.tsx

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

package/src/components/NumberInput/NumberInput.tsx

@@ -0,0 +1,199 @@
+import { SvgAdd } from '@bspk/icons/Add';
+import { SvgRemove } from '@bspk/icons/Remove';
+import { useState } from 'react';
+
+import { CommonProps, InvalidPropsLibrary } from '-';
+import { useId } from '-/hooks/useId';
+import { useLongPress } from '-/hooks/useLongPress';
+import './number-input.scss';
+
+const MAX = 99;
+const MIN = 0;
+
+const DEFAULT = {
+    align: 'center',
+    size: 'medium',
+    disabled: false,
+    readOnly: false,
+} as const;
+
+function isNumber(value: unknown, fallbackValue: number | undefined = undefined): number | undefined {
+    if (typeof value === 'number') return value;
+    if (typeof value !== 'string') return fallbackValue;
+    const num = Number(value);
+    return isNaN(num) ? fallbackValue : num;
+}
+
+export type NumberInputProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'name' | 'readOnly' | 'size'> &
+    InvalidPropsLibrary & {
+        /** The value of the control. */
+        value?: number | string;
+        /**
+         * Callback when the value changes.
+         *
+         * @required
+         */
+        onChange: (value: number | string | undefined) => void;
+        /**
+         * The alignment of the input box. Centered between the plus and minus buttons or to the left of the buttons.
+         *
+         * @default center
+         */
+        align?: 'center' | 'left';
+        /**
+         * Defines the [maximum](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max) value that is
+         * accepted.
+         *
+         * @default 99
+         * @maximum 99
+         * @minimum 1
+         */
+        max?: number;
+        /**
+         * Defines the [minimum](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/min) value that is
+         * accepted.
+         *
+         * @default 0
+         * @minimum 0
+         */
+        min?: number;
+    };
+
+/**
+ * A input element that allows users to either input a numerical value or singularly increase or decrease the values by
+ * pressing the (+) or (-).
+ *
+ * The value of the input is a number. The value is clamped to the min and max values if they are provided.
+ *
+ * @example
+ *     import { NumberInput } from '@bspk/ui/NumberInput';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState<number>();
+ *
+ *         return (
+ *             <NumberInput
+ *                 aria-label="Example aria-label"
+ *                 name="Example name"
+ *                 onChange={(nextValue) => setState(nextValue)}
+ *                 value={state}
+ *             />
+ *         );
+ *     }
+ *
+ * @name NumberInput
+ * @phase DesignReview
+ */
+function NumberInput({
+    value,
+    onChange,
+    align = DEFAULT.align,
+    size = DEFAULT.size,
+    disabled = DEFAULT.disabled,
+    readOnly = DEFAULT.readOnly,
+    name,
+    id: inputIdProp,
+    invalid,
+    'aria-label': ariaLabel,
+    max: maxProp,
+    min: minProp,
+}: NumberInputProps) {
+    const centered = align !== 'left';
+    const inputId = useId(inputIdProp);
+    const max = Math.min(MAX, isNumber(maxProp) || MAX);
+    const min = Math.max(MIN, isNumber(minProp) || MIN);
+    const valueNumber = isNumber(value) || 0;
+
+    const [inputElement, setInputElement] = useState<HTMLInputElement | null>(null);
+
+    const onIncrement = (increment: -1 | 1) => {
+        let nextValue = (isNumber(inputElement!.value) || 0) + increment;
+        if (nextValue > max) nextValue = max;
+        if (nextValue < min) nextValue = min;
+        inputElement!.value = String(nextValue);
+        onChange(nextValue);
+    };
+
+    return (
+        <div
+            data-bspk="number-input"
+            data-centered={centered || undefined}
+            data-disabled={disabled || undefined}
+            data-invalid={invalid || undefined}
+            data-readonly={readOnly || undefined}
+            data-size={size}
+            data-stepper-input
+        >
+            {!!centered && (
+                <IncrementButton disabled={valueNumber + -1 < min} increment={-1} onIncrement={onIncrement} />
+            )}
+            <input
+                aria-label={ariaLabel}
+                defaultValue={String(valueNumber)}
+                disabled={disabled}
+                id={inputId}
+                max={max}
+                min={min}
+                name={name}
+                onBlur={() => {
+                    if (!inputElement) return;
+
+                    let nextValue = isNumber(inputElement.value);
+
+                    if (typeof nextValue === 'undefined') {
+                        onChange(undefined);
+                        inputElement.value = '';
+                        return;
+                    }
+
+                    nextValue = Math.max(min, nextValue);
+                    nextValue = Math.min(max || 99, nextValue);
+                    onChange(nextValue);
+                    inputElement.value = nextValue.toString();
+                }}
+                readOnly={readOnly}
+                ref={(node) => node && setInputElement(node)}
+                type="number"
+            />
+            {!centered && (
+                <>
+                    <div aria-hidden data-divider />
+                    <IncrementButton disabled={valueNumber + -1 < min} increment={-1} onIncrement={onIncrement} />
+                </>
+            )}
+            <IncrementButton disabled={valueNumber + 1 > max} increment={1} onIncrement={onIncrement} />
+        </div>
+    );
+}
+
+type IncrementButtonProps = {
+    disabled: boolean;
+    increment: -1 | 1;
+    onIncrement: (increment: -1 | 1) => void;
+};
+
+// eslint-disable-next-line react/no-multi-comp
+function IncrementButton({ increment, disabled, onIncrement }: IncrementButtonProps) {
+    const add = increment === 1;
+
+    const { setTriggerElement, ...handlers } = useLongPress(() => onIncrement(increment), disabled);
+
+    return (
+        <button
+            aria-label={`${add ? 'Increase' : 'Decrease'} value`}
+            data-increment={increment}
+            disabled={disabled}
+            ref={setTriggerElement}
+            type="button"
+            {...handlers}
+        >
+            {add ? <SvgAdd /> : <SvgRemove />}
+        </button>
+    );
+}
+
+NumberInput.bspkName = 'NumberInput';
+
+export { NumberInput };
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/NumberInput/index.tsx

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