@bspk/ui 1.3.3 → 1.3.5

package/src/components/DatePicker/DatePicker.tsx

@@ -0,0 +1,227 @@
+import './date-picker.scss';
+import { SvgEvent } from '@bspk/icons/Event';
+import { format, isValid, parse } from 'date-fns';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Button } from '-/components/Button';
+import { Calendar } from '-/components/Calendar';
+import { useFieldInit } from '-/components/Field';
+import { InputElement, InputProps } from '-/components/Input';
+import { Portal } from '-/components/Portal';
+import { useFloating } from '-/hooks/useFloating';
+import { useOutsideClick } from '-/hooks/useOutsideClick';
+import { FieldControlProps } from '-/types/common';
+
+const parsableDate = (dateString: string) => /^\d{1,2}\/\d{1,2}\/\d{4}$/.test(dateString);
+
+export type DatePickerProps = FieldControlProps<Date | undefined> &
+    Pick<InputProps, 'size'> & {
+        /**
+         * If the calendar should close when a date is selected.
+         *
+         * @default true
+         */
+        closeCalendarOnChange?: boolean;
+        /**
+         * The placeholder text for the date input field.
+         *
+         * @default mm/dd/yyyy
+         */
+        placeholder?: string;
+    };
+
+/**
+ * An input that allows a customer to manually type in a specific date or triggers a the Calendar component to select a
+ * date.
+ *
+ * For a more complete example with field usage, see the DatePickerField component.
+ *
+ * @example
+ *     import { DatePicker } from '@bspk/ui/DatePicker';
+ *     import { Field, FieldLabel } from '@bspk/ui/Field';
+ *     import { useState } from 'react';
+ *
+ *     function ExampleStandalone() {
+ *         const [date, setDate] = useState<Date | undefined>(new Date());
+ *         return <DatePicker aria-label="Date" name="date2" value={date} onChange={setDate} />;
+ *     }
+ *
+ *     function ExampleWithField() {
+ *         const [date, setDate] = useState<Date | undefined>(new Date());
+ *
+ *         return (
+ *             <Field>
+ *                 <FieldLabel>Date</FieldLabel>
+ *                 <DatePicker name="date1" value={date} onChange={setDate} />
+ *                 <FieldDescription>The date picker allows you to select a date.</FieldDescription>
+ *             </Field>
+ *         );
+ *     }
+ *
+ * @name DatePicker
+ * @phase UXReview
+ */
+export function DatePicker({
+    value: valueProp,
+    onChange,
+    disabled,
+    readOnly,
+    closeCalendarOnChange = true,
+    name,
+    placeholder,
+    invalid: invalidProp,
+    required = false,
+    size,
+    id: idProp,
+    'aria-label': ariaLabel = 'Date picker',
+}: DatePickerProps) {
+    const { id, ariaDescribedBy, ariaErrorMessage, invalid } = useFieldInit({
+        idProp,
+        required,
+        disabled,
+        readOnly,
+        invalidProp,
+    });
+
+    const value = useMemo(() => {
+        if (typeof valueProp === 'string') {
+            const parsedDate = new Date(valueProp);
+            return isValid(parsedDate) ? parsedDate : undefined;
+        }
+        return valueProp instanceof Date && isValid(valueProp) ? valueProp : undefined;
+    }, [valueProp]);
+
+    useEffect(() => {
+        const formattedValue = value ? format(value, 'MM/dd/yyyy') : '';
+        setTextValue(formattedValue);
+    }, [value]);
+    const [textValue, setTextValue] = useState(() => (value ? format(value, 'MM/dd/yyyy') : ''));
+
+    const [calendarVisible, setCalendarVisible] = useState(false);
+    const containerRef = useRef<HTMLSpanElement | null>(null);
+
+    const { elements, floatingStyles } = useFloating({
+        placement: 'bottom',
+        strategy: 'absolute',
+        offsetOptions: 4,
+        refWidth: true,
+    });
+
+    useOutsideClick({
+        elements: [elements.floating, containerRef.current],
+        callback: () => setCalendarVisible(false),
+        disabled: !calendarVisible,
+    });
+
+    const isValidDate = (next: string) => {
+        const parsedDate = parse(next, 'MM/dd/yyyy', new Date());
+        return isValid(parsedDate) ? parsedDate : undefined;
+    };
+
+    const validate = () => {
+        let nextDate: Date | undefined;
+        let nextTextValue = '';
+
+        if (parsableDate(textValue)) {
+            nextDate = isValidDate(textValue);
+            if (nextDate) nextTextValue = format(nextDate, 'MM/dd/yyyy');
+        }
+
+        setTextValue(nextTextValue);
+        onChange(nextDate);
+    };
+
+    const handleTextChange = (nextValue: string) => {
+        // Add slashes as the user types
+        if (/^\d{2}$/.test(nextValue) || /^\d{1,2}\/\d{2}$/.test(nextValue)) nextValue = `${nextValue}/`;
+
+        // Remove extra slashes
+        if (nextValue.endsWith('//')) nextValue = nextValue.slice(0, -1);
+
+        setTextValue(nextValue);
+
+        if (parsableDate(nextValue)) {
+            const next = isValidDate(nextValue);
+            if (next) onChange(next);
+        }
+    };
+
+    return (
+        <div
+            data-bspk="date-picker"
+            ref={(node) => {
+                containerRef.current = node;
+                elements.setReference(node);
+            }}
+        >
+            <InputElement
+                aria-describedby={ariaDescribedBy || undefined}
+                aria-errormessage={ariaErrorMessage || undefined}
+                aria-label={ariaLabel}
+                disabled={disabled || undefined}
+                id={id}
+                invalid={invalid || undefined}
+                name={name}
+                onBlur={() => validate()}
+                onChange={handleTextChange}
+                onKeyDown={(event) => {
+                    // allow select all and other keyboard shortcuts
+                    if (event.ctrlKey || event.metaKey) {
+                        return;
+                    }
+
+                    // handle backspace and delete to remove the slash and the number before it
+                    if (event.key === 'Backspace' || (event.key === 'Delete' && textValue.endsWith('/'))) {
+                        event.preventDefault();
+                        setTextValue((prev) => prev.slice(0, -2));
+                    }
+
+                    // if a single key and not a number or forward slash ignore
+                    if (event.key.length === 1 && !/[0-9/]/.test(event.key)) {
+                        event.preventDefault();
+                    }
+                }}
+                placeholder={placeholder || 'mm/dd/yyyy'}
+                readOnly={readOnly}
+                required={required}
+                showClearButton={false}
+                size={size}
+                trailing={
+                    !disabled &&
+                    !readOnly && (
+                        <Button
+                            icon={<SvgEvent />}
+                            iconOnly
+                            label="Toggle calendar"
+                            onClick={() => setCalendarVisible((prev) => !prev)}
+                            variant="tertiary"
+                        />
+                    )
+                }
+                value={textValue}
+            />
+            {calendarVisible && (
+                <Portal>
+                    <div
+                        data-placement="bottom"
+                        ref={(node) => {
+                            elements.setFloating(node);
+                        }}
+                        style={{ ...floatingStyles, zIndex: 'var( --z-index-dropdown)' }}
+                    >
+                        <Calendar
+                            focusTrap={true}
+                            onChange={(next) => {
+                                if (closeCalendarOnChange) setCalendarVisible(false);
+                                onChange(next);
+                            }}
+                            value={value}
+                            variant="elevated"
+                        />
+                    </div>
+                </Portal>
+            )}
+        </div>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/DatePicker/DatePickerExample.tsx

@@ -0,0 +1,12 @@
+import { DatePickerProps } from '.';
+import { ComponentExample } from '-/utils/demo';
+
+export const DatePickerExample: ComponentExample<DatePickerProps> = {
+    defaultState: {
+        value: new Date(1985, 5, 3),
+        'aria-label': 'Select date',
+    },
+    disableProps: [],
+    sections: [],
+    variants: false,
+};

package/src/components/{DateInput/date-input.scss → DatePicker/date-picker.scss}

@@ -1,11 +1,10 @@
-[data-bspk='date-input'] {
+[data-bspk='date-picker'] {
     display: flex;
     flex-direction: column;
     justify-content: center;
-    min-width: 360px;
     width: 100%;
 
-    [data-bspk='text-input'] {
+    [data-bspk='input'] {
         padding-right: 0;
     }
 }

package/src/components/DatePicker/index.tsx

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

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

@@ -0,0 +1,17 @@
+import { DatePickerField } from '.';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <DatePickerField label="Example field label" name="example-field-name" onChange={() => {}} value={undefined} />
+);
+
+describe('DatePickerField (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getAllByLabelText } = render(<TestBed />);
+
+        expect(getAllByLabelText('Example field label')[0]).toBeInTheDocument();
+    });
+});

package/src/components/DatePickerField/DatePickerField.tsx

@@ -0,0 +1,37 @@
+import { DatePicker, DatePickerProps } from '-/components/DatePicker';
+import { FormField, FormFieldControlProps } from '-/components/FormField';
+
+export type DatePickerFieldProps = FormFieldControlProps<DatePickerProps>;
+
+/**
+ * A field wrapper for the DatePicker component.
+ *
+ * This component takes properties from the FormField and DatePicker components.
+ *
+ * @name DatePickerField
+ * @phase UXReview
+ *
+ * @generated
+ */
+export function DatePickerField({
+    label,
+    helperText,
+    labelTrailing,
+    errorMessage,
+    style,
+    ...controlProps
+}: DatePickerFieldProps) {
+    return (
+        <FormField
+            errorMessage={errorMessage}
+            helperText={helperText}
+            label={label}
+            labelTrailing={labelTrailing}
+            style={style}
+        >
+            <DatePicker {...controlProps} />
+        </FormField>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/DatePickerField/index.tsx

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

package/src/components/Drawer/Drawer.tsx

@@ -52,7 +52,7 @@ export type DrawerProps = Pick<DialogProps, 'container' | 'disableFocusTrap' | '
  *     import { Button } from '@bspk/ui/Button';
  *     import { Drawer } from '@bspk/ui/Drawer';
  *
- *     export function Example() {
+ *     function Example() {
  *         const [open, setOpen] = React.useState(false);
  *
  *         return (

package/src/components/Drawer/DrawerExample.tsx

@@ -5,11 +5,11 @@ import { ComponentExampleFn, Preset } from '-/utils/demo';
 export const presets: Preset<DrawerProps>[] = [
     {
         label: 'Left Responsive',
-        propState: { closeButton: true, modal: false, placement: 'left', children: <></> },
+        propState: { closeButton: true, modal: false, placement: 'left', children: null },
     },
     {
         label: 'Right Responsive',
-        propState: { closeButton: true, modal: false, placement: 'right', children: <></> },
+        propState: { closeButton: true, modal: false, placement: 'right', children: null },
     },
 ];
 

package/src/components/EmptyState/EmptyState.tsx

@@ -41,7 +41,7 @@ export type EmptyStateProps = {
  * @example
  *     import { EmptyState } from '@bspk/ui/EmptyState';
  *
- *     export function Example() {
+ *     function Example() {
  *         return (
  *             <EmptyState body="Example body" header="Example header">
  *                 Example EmptyState

package/src/components/Fab/Fab.tsx

@@ -6,7 +6,7 @@ import { ElementProps } from '-/types/common';
 
 export type FabVariant = 'neutral' | 'primary' | 'secondary';
 
-export type FabProps<As extends ElementType = 'button'> = Pick<
+export type FabProps<As extends ElementType = ElementType> = Pick<
     ButtonProps<As>,
     'as' | 'icon' | 'iconOnly' | 'onClick' | 'toolTip'
 > &
@@ -45,14 +45,14 @@ export type FabProps<As extends ElementType = 'button'> = Pick<
  *     import { SvgBolt } from '@bspk/icons/Bolt';
  *     import { Fab } from '@bspk/ui/Fab';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
  *     }
  *
  * @name Fab
  * @phase UXReview
  */
-export function Fab<As extends ElementType = 'button'>(props: AriaAttributes & ElementProps<FabProps<As>, As>) {
+export function Fab<As extends ElementType = ElementType>(props: AriaAttributes & ElementProps<FabProps<As>, As>) {
     const {
         size = 'small',
         variant = 'primary',

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

@@ -0,0 +1,23 @@
+import { Field, FieldDescription, FieldError, FieldLabel } from './';
+import { Input } from '-/components/Input';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <Field>
+        <FieldLabel>Example label</FieldLabel>
+        <Input name="example-text" onChange={() => {}} value="Input text" />
+        <FieldDescription>This is an example description.</FieldDescription>
+        <FieldError>This is an error message.</FieldError>
+    </Field>
+);
+
+describe('Field (RTL)', () => {
+    it('has no basic a11y issues', hasNoBasicA11yIssues(<TestBed />));
+
+    it('renders', () => {
+        const { getByText } = render(<TestBed />);
+
+        expect(getByText('Example label')).toBeInTheDocument();
+    });
+});

package/src/components/Field/Field.tsx

@@ -0,0 +1,110 @@
+import './field.scss';
+import { Children, ElementType, isValidElement, ReactNode, useMemo, useState } from 'react';
+
+import { describedById, errorMessageId, fieldContext, FieldContext, labelledById } from './utils';
+import { ElementProps } from '-/types/common';
+import { randomString } from '-/utils/random';
+
+export type FieldProps<As extends ElementType = ElementType> = {
+    /**
+     * The children of the form field. This should be a control such as DatePicker, Input, InputNumber, InputPhone,
+     * Password, Select, Textarea, or TimePicker.
+     *
+     * @required
+     */
+    children: ReactNode;
+    /**
+     * The element type to render the field as.
+     *
+     * @default div
+     * @type ElementType
+     */
+    as?: As;
+    /** The unique id for the field. */
+    id?: string;
+};
+
+const isComponentName = (
+    child: React.ReactElement<unknown, React.JSXElementConstructor<unknown> | string> | React.ReactPortal,
+    name: string,
+) => {
+    const componentType = child.type as { name?: string; displayName?: string };
+    return componentType.displayName === name || componentType.name === name;
+};
+
+/**
+ * Wrapper component for form controls.
+ *
+ * Children should be one of the following: DatePicker, Input, InputNumber, InputPhone, Password, Select, Textarea, or
+ * TimePicker.
+ *
+ * @example
+ *     import { Input } from '@bspk/ui/Input';
+ *     import { Field, FieldLabel, FieldDescription, FieldError } from '@bspk/ui/Field';
+ *
+ *     function Example() {
+ *         const [state, setState] = React.useState<string | undefined>(undefined);
+ *         const [error, setError] = React.useState<string | undefined>(undefined);
+ *
+ *         return (
+ *             <Field label="Example label">
+ *                 <FieldLabel>Example label</FieldLabel>
+ *                 <Input
+ *                     aria-label="example aria-label"
+ *                     name="example-text"
+ *                     onChange={(next) => {
+ *                         setState(next);
+ *                     }}
+ *                     value={state}
+ *                     {...fieldProps}
+ *                 />
+ *                 <FieldDescription>This is an example description.</FieldDescription>
+ *                 {error && <FieldError>{error}</FieldError>}
+ *             </Field>
+ *         );
+ *     }
+ *
+ * @name Field
+ * @phase Utility
+ */
+export function Field<As extends ElementType = ElementType>({
+    children,
+    as,
+    id: idProp,
+    ...props
+}: ElementProps<FieldProps<As>, As>) {
+    const id = useMemo(() => idProp || `field-${randomString(8)}`, [idProp]);
+
+    const childContext = useMemo(() => {
+        const next: Pick<FieldContext, 'ariaDescribedBy' | 'ariaErrorMessage' | 'ariaLabelledBy'> = {};
+        Children.forEach(children, (child) => {
+            if (!isValidElement(child) || typeof child.type === 'string' || !child.props.children) return;
+
+            if (isComponentName(child, 'FieldError')) next.ariaErrorMessage = errorMessageId(id);
+            else if (isComponentName(child, 'FieldLabel')) next.ariaLabelledBy = labelledById(id);
+            else if (isComponentName(child, 'FieldDescription')) next.ariaDescribedBy = describedById(id);
+        });
+        return next;
+    }, [children, id]);
+
+    const [contextState, setContext] = useState<Pick<FieldContext, 'htmlFor' | 'required'>>({});
+
+    const As = as || 'div';
+
+    return (
+        <fieldContext.Provider
+            value={{
+                ...childContext,
+                ...contextState,
+                id,
+                setContext,
+            }}
+        >
+            <As {...props} data-bspk-utility="field" id={id} role="group">
+                {children}
+            </As>
+        </fieldContext.Provider>
+    );
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/FieldDescription.tsx

@@ -0,0 +1,15 @@
+import { useFieldContext, describedById } from './utils';
+
+function FieldDescription({ children }: { children?: string }) {
+    const { id } = useFieldContext();
+
+    return children ? (
+        <p data-bspk="field-description" id={describedById(id)}>
+            {children}
+        </p>
+    ) : null;
+}
+
+FieldDescription.displayName = 'FieldDescription';
+
+export { FieldDescription };

package/src/components/Field/FieldError.tsx

@@ -0,0 +1,19 @@
+import { errorMessageId, useFieldContext } from './utils';
+import { InlineAlert } from '-/components/InlineAlert';
+
+export type FieldErrorProps = {
+    /** The error message text. */
+    children?: string;
+};
+
+export function FieldError({ children }: FieldErrorProps) {
+    const { id } = useFieldContext();
+
+    return (
+        children && (
+            <InlineAlert id={errorMessageId(id)} owner="field-error" variant="error">
+                {children}
+            </InlineAlert>
+        )
+    );
+}

package/src/components/Field/FieldExample.tsx

@@ -0,0 +1,21 @@
+import { Field, FieldDescription, FieldError, FieldLabel, FieldProps } from './';
+import { Input } from '-/components/Input';
+import { ComponentExample } from '-/utils/demo';
+import { randomString } from '-/utils/random';
+
+export const FieldExample: ComponentExample<FieldProps & { value?: string }> = {
+    render: ({ props, setState }) => {
+        return (
+            <Field {...props}>
+                <FieldLabel>Example label</FieldLabel>
+                <Input
+                    name={`example-${randomString(6)}`}
+                    onChange={(next: string) => setState({ value: next })}
+                    value={props.value}
+                />
+                <FieldDescription>This is an example description.</FieldDescription>
+                <FieldError>This is an error message.</FieldError>
+            </Field>
+        );
+    },
+};

package/src/components/Field/FieldLabel.tsx

@@ -0,0 +1,38 @@
+import { ElementType } from 'react';
+import { FieldContext, useFieldContext, labelledById } from './utils';
+import { ElementProps } from '-/types/common';
+
+export type FieldLabelProps<As extends ElementType = ElementType> = Pick<FieldContext, 'labelTrailing' | 'required'> & {
+    /** The label text. */
+    children: string;
+    /**
+     * The element type to render as.
+     *
+     * @default label
+     * @type ElementType
+     */
+    as?: As;
+};
+
+export function FieldLabel<As extends ElementType = ElementType>({
+    children,
+    labelTrailing,
+    as,
+    ...props
+}: ElementProps<FieldLabelProps<As>, As>) {
+    const As = as || 'label';
+
+    const { required, id, htmlFor, ...context } = useFieldContext();
+
+    return (
+        <As data-bspk="field-label" htmlFor={As === 'label' ? htmlFor : undefined} id={labelledById(id)} {...props}>
+            <span>{children}</span>
+            {required && <span data-required>{' (Required)'}</span>}
+            {(labelTrailing || context.labelTrailing) && (
+                <span aria-hidden data-trailing>
+                    {labelTrailing || context.labelTrailing}
+                </span>
+            )}
+        </As>
+    );
+}

package/src/components/Field/field.scss

@@ -0,0 +1,43 @@
+[data-bspk-utility='field'] {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-sizing-01);
+    border: none;
+}
+
+[data-bspk='field-label'] {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: var(--spacing-sizing-01);
+
+    span {
+        font: var(--labels-small);
+        color: var(--foreground-neutral-on-surface);
+
+        &[data-required] {
+            font: var(--body-small);
+            color: var(--foreground-neutral-on-surface-variant-01);
+        }
+
+        &[data-trailing] {
+            font: var(--body-small);
+            color: var(--foreground-neutral-on-surface-variant-02);
+            margin-left: auto;
+        }
+    }
+}
+
+[data-bspk='field-description'] {
+    font: var(--body-small);
+    color: var(--foreground-neutral-on-surface-variant-01);
+    margin: 0;
+    padding: 0;
+}
+
+[data-bspk-owner='field-error'] {
+    // Styles for FieldError component when used inside Field
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/components/Field/index.tsx

@@ -0,0 +1,5 @@
+export * from './Field';
+export * from './FieldLabel';
+export * from './FieldDescription';
+export * from './FieldError';
+export * from './utils';