@bspk/ui 1.3.3 → 1.3.5

package/src/components/{TimeInput/TimeInput.tsx → TimePicker/TimePicker.tsx}

@@ -1,87 +1,105 @@
-import './time-input.scss';
+import './time-picker.scss';
 import { SvgSchedule } from '@bspk/icons/Schedule';
 import { FocusTrap } from 'focus-trap-react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { TimeInputListbox } from './Listbox';
-import { TimeInputSegment } from './Segment';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { TimePickerListbox } from './Listbox';
+import { TimePickerSegment } from './Segment';
+import {
+    HOUR_OPTIONS,
+    MINUTE_OPTIONS,
+    MERIDIEM_OPTIONS,
+    Meridiem,
+    partsToStringValue,
+    stringValueToParts,
+} from './utils';
 import { Button } from '-/components/Button';
+import { useFieldInit } from '-/components/Field';
+import { InputProps } from '-/components/Input';
 import { Menu } from '-/components/Menu';
 import { Portal } from '-/components/Portal';
-import { TextInputProps } from '-/components/TextInput';
 import { useFloating } from '-/hooks/useFloating';
-import { useId } from '-/hooks/useId';
 import { useOutsideClick } from '-/hooks/useOutsideClick';
+import { ElementProps, FieldControlProps } from '-/types/common';
 import { handleKeyDown } from '-/utils/handleKeyDown';
 
-export const MINUTE_OPTIONS = ['00', '05', '10', '15', '20', '25', '30', '35', '40', '45', '50', '55'];
-export const HOUR_OPTIONS = ['01', '02', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12'];
-export const MERIDIEM_OPTIONS = ['AM', 'PM'];
-
-type Minute = (typeof MINUTE_OPTIONS)[number];
-type Hour = (typeof HOUR_OPTIONS)[number];
-type Meridiem = (typeof MERIDIEM_OPTIONS)[number];
-
-export type TimeInputProps = Pick<
-    TextInputProps,
-    | 'aria-describedby'
-    | 'aria-errormessage'
-    | 'aria-label'
-    | 'disabled'
-    | 'id'
-    | 'invalid'
-    | 'name'
-    | 'readOnly'
-    | 'size'
-> & {
-    value?: string;
-};
+export type TimePickerProps = FieldControlProps & Pick<InputProps, 'size'>;
 
 /**
  * An input field that allows a customer to manually type in a specific time or triggers a time picker combobox to
  * select a date.
  *
+ * For a more complete example with field usage, see the TimePickerField component.
+ *
  * @example
- *     import { TimeInput } from '@bspk/ui/TimeInput';
+ *     import { TimePicker } from '@bspk/ui/TimePicker';
+ *
+ *     function ExampleStandalone() {
+ *         const [value, onChange] = React.useState('');
+ *
+ *         return <TimePicker aria-label="Time" name="time" value={value} onChange={onChange} />;
+ *     }
  *
- *     function Example() {
- *         return <TimeInput>Example TimeInput</TimeInput>;
+ *     function ExampleWithField() {
+ *         const [value, onChange] = React.useState('');
+ *
+ *         return (
+ *             <Field>
+ *                 <FieldLabel>Time</FieldLabel>
+ *                 <TimePicker value={value} onChange={onChange} />
+ *                 <FieldDescription>The time picker allows you to select a time.</FieldDescription>
+ *             </Field>
+ *         );
  *     }
  *
- * @name TimeInput
+ * @name TimePicker
  * @phase UXReview
  */
-export function TimeInput({
+export function TimePicker({
     value,
-    'aria-label': ariaLabel,
     disabled,
     id: idProp,
-    invalid,
+    invalid: invalidProp,
     readOnly,
     name,
     size,
-    'aria-describedby': ariaDescribedBy,
-    'aria-errormessage': ariaErrorMessage,
-}: TimeInputProps) {
-    const id = useId(idProp);
+    required = false,
+    onChange: onChangeProp,
+    'aria-label': ariaLabel = 'Time picker',
+    ...props
+}: ElementProps<TimePickerProps, 'div'>) {
+    const { id, ariaDescribedBy, ariaErrorMessage, invalid } = useFieldInit({
+        idProp,
+        required,
+        disabled,
+        readOnly,
+        invalidProp,
+    });
 
-    const [inputValue, setInputValue] = useState(value);
+    const menuId = `${id}-time-picker-menu`;
 
-    const [hours, setHours] = useState<(typeof HOUR_OPTIONS)[number]>();
-    const [minutes, setMinutes] = useState<(typeof MINUTE_OPTIONS)[number]>();
-    const [meridiem, setMeridiem] = useState<(typeof MERIDIEM_OPTIONS)[number]>('AM');
+    const { hours, minutes, meridiem } = useMemo(() => stringValueToParts(value || '00:00'), [value]);
 
-    useEffect(() => {
-        setInputValue(
-            `${hours?.toString().padStart(2, '0')}:${minutes?.toString().padStart(2, '0')} ${meridiem || ''}`.trim(),
-        );
-        if (hours !== undefined && minutes === undefined) setMinutes('00');
-    }, [hours, minutes, meridiem]);
+    const setValue = useCallback(
+        (
+            params: Partial<{
+                hours?: string;
+                minutes?: string;
+                meridiem?: Meridiem;
+            }>,
+        ) => {
+            const nextValue = { hours, minutes, meridiem, ...params };
+            onChangeProp(
+                partsToStringValue(nextValue.hours?.toString(), nextValue.minutes?.toString(), nextValue.meridiem),
+            );
+        },
+        [hours, minutes, meridiem, onChangeProp],
+    );
 
     const [open, setOpenState] = useState(false);
 
     const { floatingStyles, elements } = useFloating({
         strategy: 'fixed',
-        refWidth: true,
+        refWidth: false,
         offsetOptions: 4,
         hide: !open,
     });
@@ -132,20 +150,22 @@ export function TimeInput({
     } | null>(null);
     const buttonRef = useRef<HTMLElement | null>(null);
 
+    const [firstField, setFirstField] = useState<HTMLElement | null>(null);
+
     return (
         <>
             <div
+                {...props}
                 aria-describedby={ariaErrorMessage || ariaDescribedBy || undefined}
-                data-aria-label={ariaLabel || undefined}
-                data-bspk="time-input"
+                aria-label={ariaLabel || undefined}
+                data-bspk="time-picker"
                 data-disabled={disabled || undefined}
                 data-invalid={invalid || undefined}
                 data-name={name || undefined}
                 data-open={open || undefined}
                 data-readonly={readOnly || undefined}
                 data-size={size || undefined}
-                data-value={inputValue || undefined}
-                id={id}
+                data-value={value || undefined}
                 onClickCapture={() => {
                     if (disabled || readOnly) return;
                     elements.reference?.querySelector<HTMLElement>('[tabIndex]')?.focus();
@@ -155,34 +175,49 @@ export function TimeInput({
                     elements.setReference(node);
                 }}
                 role="group"
-                tabIndex={disabled || readOnly ? -1 : 0}
+                tabIndex={-1}
             >
-                <TimeInputSegment
+                <input
+                    aria-hidden
+                    data-sr-only
+                    id={id}
+                    name={name}
+                    onChange={(e) => onChangeProp(e.target.value)}
+                    onFocus={() => firstField?.focus()}
+                    tabIndex={-1}
+                    value={value}
+                />
+                <TimePickerSegment
                     disabled={disabled}
                     name={`${name}-hours`}
-                    onChange={(next) => setHours(next || undefined)}
+                    onChange={(next) => setValue({ hours: next || undefined })}
                     readOnly={readOnly}
+                    setRef={setFirstField}
                     type="hours"
                     value={hours}
                 />
                 <span aria-hidden="true">:</span>
-                <TimeInputSegment
+                <TimePickerSegment
                     disabled={disabled}
                     name={`${name}-minutes`}
-                    onChange={(next) => setMinutes(next || undefined)}
+                    onChange={(next) => setValue({ minutes: next || undefined })}
                     readOnly={readOnly}
                     type="minutes"
                     value={minutes}
                 />
-                <TimeInputSegment
+                <TimePickerSegment
                     disabled={disabled}
                     name={`${name}-meridiem`}
-                    onChange={(next) => setMeridiem(next || 'AM')}
+                    onChange={(next) => setValue({ meridiem: next || 'AM' })}
                     readOnly={readOnly}
                     type="meridiem"
                     value={meridiem}
                 />
                 <Button
+                    aria-controls={open ? menuId : undefined}
+                    aria-expanded={open}
+                    aria-haspopup="listbox"
+                    as="span"
                     disabled={disabled || readOnly}
                     icon={<SvgSchedule />}
                     iconOnly
@@ -191,19 +226,22 @@ export function TimeInput({
                     }}
                     label={`${open ? 'Close' : 'Open'} Time Picker`}
                     onClick={() => setOpen(!open)}
+                    role="combobox"
                     variant="tertiary"
                 />
             </div>
-            {!!open && (
+            {open && (
                 <Portal>
                     <Menu
+                        id={menuId}
                         innerRef={(node) => {
                             if (!node) return;
                             elements.setFloating(node as HTMLElement);
                         }}
                         label="Select time"
-                        owner="time-input"
+                        owner="time-picker"
                         style={floatingStyles}
+                        width="fit-content"
                     >
                         <FocusTrap
                             focusTrapOptions={{
@@ -219,30 +257,39 @@ export function TimeInput({
                                         minutes: node?.querySelector('[data-scroll-column="minutes"]') as HTMLElement,
                                         meridiem: node?.querySelector('[data-scroll-column="meridiem"]') as HTMLElement,
                                     };
-                                    listBoxRefs.current.hours?.focus();
+                                    const activeHour =
+                                        listBoxRefs.current.hours?.querySelector<HTMLElement>('[data-active]');
+                                    const activeMinute =
+                                        listBoxRefs.current.minutes?.querySelector<HTMLElement>('[data-active]');
+                                    const activeMeridiem =
+                                        listBoxRefs.current.meridiem?.querySelector<HTMLElement>('[data-active]');
+                                    activeHour?.scrollIntoView({ block: 'nearest' });
+                                    activeMinute?.scrollIntoView({ block: 'nearest' });
+                                    activeMeridiem?.scrollIntoView({ block: 'nearest' });
+                                    activeHour?.focus();
                                 }}
                             >
-                                <TimeInputListbox
+                                <TimePickerListbox
                                     onSelect={(next) => {
-                                        setHours(next as Hour);
+                                        setValue({ hours: next });
                                         setTimeout(() => listBoxRefs.current?.minutes?.focus(), 10);
                                     }}
                                     options={hourOptions}
                                     selectedValue={hours}
                                     type="hours"
                                 />
-                                <TimeInputListbox
+                                <TimePickerListbox
                                     onSelect={(next) => {
-                                        setMinutes(next as Minute);
+                                        setValue({ minutes: next });
                                         setTimeout(() => listBoxRefs.current?.meridiem?.focus(), 10);
                                     }}
                                     options={minuteOptions}
                                     selectedValue={minutes}
                                     type="minutes"
                                 />
-                                <TimeInputListbox
+                                <TimePickerListbox
                                     onSelect={(next) => {
-                                        setMeridiem(next as Meridiem);
+                                        setValue({ meridiem: next as Meridiem });
                                         setOpen(false);
                                         setTimeout(() => buttonRef.current?.focus(), 10);
                                     }}

package/src/components/TimePicker/TimePickerExample.tsx

@@ -0,0 +1,8 @@
+import { TimePickerProps } from './TimePicker';
+import { ComponentExample } from '-/utils/demo';
+
+export const TimePickerExample: ComponentExample<TimePickerProps> = {
+    variants: false,
+
+    render: ({ props, Component }) => <Component {...props} />,
+};

package/src/components/TimePicker/index.tsx

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

package/src/components/{TimeInput/time-input.scss → TimePicker/time-picker.scss}

@@ -1,4 +1,4 @@
-[data-bspk='time-input'] {
+[data-bspk='time-picker'] {
     --border-color: var(--stroke-neutral-base);
 
     display: flex;
@@ -7,18 +7,18 @@
     border: solid 1px var(--border-color);
     height: var(--field-height);
     border-radius: var(--radius-sm);
-    padding: 0 0 0 var(--field-padding);
+    padding: 0 0 0 var(--field-padding, var(--spacing-sizing-02));
     width: 100%;
     justify-content: flex-start;
     align-items: center;
 
-    &:hover:not(:focus-within) {
+    &:hover:not(:focus-within, [data-disabled], [data-readonly]) {
         background:
             linear-gradient(var(--interactions-hover-opacity), var(--interactions-hover-opacity)),
             linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
     }
 
-    &:active:not(:focus-within) {
+    &:active:not(:focus-within, [data-disabled], [data-readonly]) {
         background:
             linear-gradient(var(--interactions-press-opacity), var(--interactions-press-opacity)),
             linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
@@ -27,6 +27,7 @@
     &[data-readonly] {
         --border-color: var(--stroke-neutral-disabled-light);
 
+        pointer-events: none;
         background:
             linear-gradient(var(--interactions-disabled-opacity), var(--interactions-disabled-opacity)),
             linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
@@ -36,6 +37,7 @@
     &:has(input[disabled]) {
         --border-color: var(--stroke-neutral-disabled-light);
 
+        pointer-events: none;
         background:
             linear-gradient(var(--interactions-disabled-opacity), var(--interactions-disabled-opacity)),
             linear-gradient(var(--surface-neutral-t1-base), var(--surface-neutral-t1-base));
@@ -110,7 +112,7 @@
     }
 }
 
-[data-bspk-owner='time-input'][data-bspk-utility='menu'] {
+[data-bspk-owner='time-picker'][data-bspk-utility='menu'] {
     overflow: hidden;
     height: 324px;
 

package/src/components/TimePicker/utils.test.tsx

@@ -0,0 +1,26 @@
+import { stringValueToParts, Meridiem, partsToStringValue } from './utils';
+
+const FIXTURES: {
+    hours: string;
+    minutes: string;
+    meridiem: Meridiem;
+    str: string;
+}[] = [
+    { hours: '12', minutes: '00', meridiem: 'AM', str: '00:00' },
+    { hours: '01', minutes: '15', meridiem: 'AM', str: '01:15' },
+    { hours: '12', minutes: '30', meridiem: 'PM', str: '12:30' },
+    { hours: '03', minutes: '45', meridiem: 'PM', str: '15:45' },
+    { hours: '11', minutes: '59', meridiem: 'PM', str: '23:59' },
+];
+
+describe('stringValueToParts', () => {
+    FIXTURES.forEach(({ str, hours, minutes, meridiem }) => {
+        it(`should parse "${str}" correctly`, () => {
+            expect(stringValueToParts(str)).toEqual({ hours, minutes, meridiem, str });
+        });
+
+        it(`should unParse "${JSON.stringify({ hours, minutes, meridiem })}" correctly`, () => {
+            expect(partsToStringValue(hours, minutes, meridiem)).toEqual(str);
+        });
+    });
+});

package/src/components/TimePicker/utils.ts

@@ -0,0 +1,44 @@
+import { format, isValid, parse } from 'date-fns';
+
+export const MINUTE_OPTIONS = ['00', '05', '10', '15', '20', '25', '30', '35', '40', '45', '50', '55'];
+export const HOUR_OPTIONS = ['01', '02', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12'];
+export const MERIDIEM_OPTIONS = ['AM', 'PM'];
+
+export type Meridiem = 'AM' | 'PM';
+
+export function stringValueToParts(timeString: string) {
+    // Parse the 24-hour time string into a Date object
+    // 'HH:mm' is the format for 24-hour time (e.g., '14:30')
+    // new Date() provides a base date for parsing, which is necessary
+    // but the date part won't affect the time parsing here.
+
+    const dateObj = parse(timeString, 'HH:mm', new Date());
+
+    const isValidDate = isValid(dateObj);
+
+    // Extract hours, minutes, and AM/PM using format
+    return {
+        hours: isValidDate ? format(dateObj, 'hh') : undefined,
+        minutes: isValidDate ? format(dateObj, 'mm') : undefined,
+        meridiem: isValidDate ? (format(dateObj, 'a') as Meridiem) : 'AM',
+        str: timeString,
+    };
+}
+
+export function partsToStringValue(hours: string | undefined, minutes: string | undefined, meridiem: Meridiem): string {
+    if (typeof hours === 'undefined' || typeof minutes === 'undefined') {
+        return '';
+    }
+
+    const minutesNumber = Number(minutes);
+
+    let hours24 = Number(hours);
+    if (meridiem === 'PM' && hours24 < 12) {
+        hours24 += 12;
+    } else if (meridiem === 'AM' && hours24 === 12) {
+        hours24 = 0;
+    }
+
+    // Format the date object back to a 24-hour time string
+    return `${hours24.toString().padStart(2, '0')}:${minutesNumber.toString().padStart(2, '0')}`;
+}

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

@@ -0,0 +1,17 @@
+import { TimePickerField } from '.';
+import { hasNoBasicA11yIssues } from '-/rtl/hasNoBasicA11yIssues';
+import { render } from '-/rtl/util';
+
+const TestBed = () => (
+    <TimePickerField label="Example field label" name="example-field-name" onChange={() => {}} value="" />
+);
+
+describe('TimePickerField (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/TimePickerField/TimePickerField.tsx

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

package/src/components/TimePickerField/index.tsx

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

package/src/components/ToggleOption/ToggleOption.tsx

@@ -1,27 +1,28 @@
 import './toggle-option.scss';
 import { ReactElement } from 'react';
+import { ListItem, ListItemProps } from '-/components/ListItem';
 import { CommonProps } from '-/types/common';
 
 export type ToggleOptionControlProps<T extends { 'aria-label'?: string }> = Omit<T, 'aria-label'> &
     Pick<ToggleOptionProps, 'description' | 'label'>;
 
-export type ToggleOptionProps = CommonProps<'disabled' | 'readOnly'> & {
-    /**
-     * The label of the option. Also used as the aria-label of the control.
-     *
-     * @required
-     */
-    label: string;
-    /**
-     * The description of the option.
-     *
-     * @type multiline
-     * @type multiline
-     */
-    description?: string;
-    /** The control element to use. */
-    children?: ReactElement;
-};
+export type ToggleOptionProps = CommonProps<'disabled' | 'readOnly'> &
+    Omit<ListItemProps, 'as' | 'label' | 'leading' | 'subtext' | 'trailing'> & {
+        /**
+         * The label of the option. Also used as the aria-label of the control.
+         *
+         * @required
+         */
+        label: string;
+        /**
+         * The description of the option.
+         *
+         * @type multiline
+         */
+        description?: string;
+        /** The control element to use. */
+        children?: ReactElement;
+    };
 
 /**
  * A utility component that wraps a checkbox, radio, and switch.
@@ -29,13 +30,18 @@ export type ToggleOptionProps = CommonProps<'disabled' | 'readOnly'> & {
  * @name ToggleOption
  * @phase Utility
  */
-export function ToggleOption({ label, description, children, disabled, readOnly }: ToggleOptionProps) {
+export function ToggleOption({ label, description, children, disabled, readOnly, ...props }: ToggleOptionProps) {
     return (
-        <label aria-disabled={!!disabled || !!readOnly || undefined} data-bspk="toggle-option">
-            <span data-control>{children}</span>
-            <span data-label>{label}</span>
-            {description && <span data-description>{description}</span>}
-        </label>
+        <ListItem
+            {...props}
+            as="label"
+            data-disabled={disabled}
+            data-readonly={readOnly}
+            label={label}
+            leading={children}
+            subText={description}
+            width="hug"
+        />
     );
 }
 

package/src/components/Tooltip/Tooltip.tsx

@@ -44,7 +44,7 @@ export type TooltipProps = {
  *     import { Tooltip } from '@bspk/ui/Tooltip';
  *     import { Button } from '@bspk/ui/Button';
  *
- *     export function Example() {
+ *     function Example() {
  *         return (
  *             <Tooltip label="I explain what this button does" placement="top">
  *                 {(triggerProps) => <Button {...triggerProps}>Click me</Button>}

package/src/components/Tooltip/TooltipExample.tsx

@@ -5,15 +5,13 @@ import { ComponentExample } from '-/utils/demo';
 export const TooltipExample: ComponentExample<TooltipProps> = {
     render: ({ props: state, Component }) => {
         return (
-            <>
-                <Component
-                    {...state}
-                    label={`Hover over me ${state.label || ''}`}
-                    placement={[state.placement].flat()[0] || 'top'}
-                >
-                    {(triggerProps) => <Button {...triggerProps} label="Hover over me" variant="secondary" />}
-                </Component>
-            </>
+            <Component
+                {...state}
+                label={`Hover over me ${state.label || ''}`}
+                placement={[state.placement].flat()[0] || 'top'}
+            >
+                {(triggerProps) => <Button {...triggerProps} label="Hover over me" variant="secondary" />}
+            </Component>
         );
     },
 };

package/src/components/Truncated/Truncated.tsx

@@ -4,7 +4,7 @@ import { Tooltip, TooltipTriggerProps } from '-/components/Tooltip';
 import { useTruncatedText } from '-/hooks/useTruncatedText';
 import { ElementConstructorProps } from '-/types/common';
 
-export type TruncatedProps<As extends ElementType = 'span'> = {
+export type TruncatedProps<As extends ElementType = ElementType> = {
     /**
      * The element type to render as.
      *
@@ -35,7 +35,7 @@ export type TruncatedProps<As extends ElementType = 'span'> = {
  * @name Truncated
  * @phase Utility
  */
-export function Truncated<As extends ElementType = 'span'>({
+export function Truncated<As extends ElementType = ElementType>({
     children,
     label,
     ...props

package/src/components/Txt/Txt.tsx

@@ -4,7 +4,7 @@ import { SkeletonText } from '-/components/SkeletonText';
 import { ElementProps } from '-/types/common';
 import { TxtVariant } from '-/utils/txtVariants';
 
-export type TxtProps<As extends ElementType = 'span'> = {
+export type TxtProps<As extends ElementType = ElementType> = {
     /**
      * The element type to render as.
      *
@@ -49,14 +49,14 @@ export type TxtProps<As extends ElementType = 'span'> = {
  * @example
  *     import { Txt } from '@bspk/ui/Txt';
  *
- *     export function Example() {
+ *     function Example() {
  *         return <Txt>Example Txt</Txt>;
  *     }
  *
  * @name Txt
  * @phase UXReview
  */
-export function Txt<As extends ElementType = 'span'>({
+export function Txt<As extends ElementType = ElementType>({
     children,
     as,
     variant = 'body-base',