@bloomreach/react-banana-ui 1.31.2 → 1.32.0

package/dist/components/{inputs → date}/calendar-grid/calendar-grid.types.d.ts

@@ -4,6 +4,13 @@ export interface CalendarGridProps {
      * Custom class name for the container of the component.
      */
     className?: string;
+    /**
+     * The locale for the calendar.
+     * Follows BCP 47 language tag format (e.g., 'en-US', 'de-DE', 'ja-JP').
+     * When not provided, uses the user's browser locale.
+     * @example 'en-US', 'de-DE', 'fr-FR'
+     */
+    locale?: string;
     /**
      * The state for the calendar from `useCalendarState` or `useRangeCalendarState` hook.
      */

package/dist/components/date/date-time-picker/date-time-picker.d.ts

@@ -0,0 +1,74 @@
+import { DateTimePickerProps } from './date-time-picker.types';
+/**
+ * DateTimePicker is a composite component that combines date and time selection.
+ * It provides a text field for entering date/time values and a popup with both
+ * a calendar for date selection and time selectors for hour, minute, and second.
+ *
+ * Built on top of React Aria's date picker primitives with extended time support.
+ * The component automatically handles keyboard navigation, accessibility, and
+ * internationalization for both date and time components.
+ *
+ * ## Features
+ *
+ * - **Unified Date/Time Selection**: Single component for both date and time
+ * - **Calendar Integration**: Full calendar for date selection
+ * - **Time Selectors**: Dropdown selectors for hour, minute, and second
+ * - **Granularity Control**: Configure precision from day to second level
+ * - **Keyboard Navigation**: Full keyboard support with Enter/Space to open
+ * - **Accessibility**: Screen reader support and proper focus management
+ * - **Internationalization**: Automatic formatting based on locale
+ * - **Validation**: Built-in min/max date/time validation
+ * - **Form Integration**: Works seamlessly with HTML forms
+ *
+ * ## Usage
+ *
+ * ### Basic Usage
+ * ```tsx
+ * import { DateTimePicker } from '@bloomreach/react-banana-ui';
+ *
+ * function MyComponent() {
+ *   const [value, setValue] = useState<Date | null>(new Date());
+ *
+ *   return (
+ *     <DateTimePicker
+ *       value={value}
+ *       onChange={(newValue) => setValue(newValue)}
+ *       granularity="minute"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ### With Validation
+ * ```tsx
+ * <DateTimePicker
+ *   value={value}
+ *   onChange={(newValue, context) => {
+ *     if (context.valid) {
+ *       setValue(newValue);
+ *     } else {
+ *       setError(context.validationMessage.join(' '));
+ *     }
+ *   }}
+ *   minDate={new Date('2024-01-01')}
+ *   maxDate={new Date('2024-12-31')}
+ *   granularity="second"
+ *   required
+ * />
+ * ```
+ *
+ * ## Accessibility
+ *
+ * The component follows WAI-ARIA guidelines for both date and time selection:
+ * - Proper focus management between input, calendar, and time selectors
+ * - Screen reader announcements for value changes
+ * - Keyboard navigation with arrow keys in calendar
+ * - Escape key to close, Enter/Space to open
+ * - Support for assistive technologies
+ *
+ * @param props - The props for the DateTimePicker component
+ * @param forwardedRef - Ref to be forwarded to the container element
+ * @returns A comprehensive date and time picker component
+ */
+declare const DateTimePicker: import('react').ForwardRefExoticComponent<DateTimePickerProps & import('react').RefAttributes<HTMLDivElement>>;
+export default DateTimePicker;

package/dist/components/date/date-time-picker/date-time-picker.stories.d.ts

@@ -0,0 +1,19 @@
+import { DateTimePicker } from './index';
+import { Meta, StoryObj } from '@storybook/react';
+declare const meta: Meta<typeof DateTimePicker>;
+export default meta;
+type Story = StoryObj<typeof DateTimePicker>;
+export declare const Basic: Story;
+export declare const WithInitialValue: Story;
+export declare const Controlled: Story;
+export declare const GranularityComparison: Story;
+export declare const HourCycleComparison: Story;
+export declare const WithMinMaxDates: Story;
+export declare const ErrorState: Story;
+export declare const Disabled: Story;
+export declare const ReadOnly: Story;
+export declare const LocaleComparison: Story;
+export declare const WithTimezone: Story;
+export declare const EventHandlers: Story;
+export declare const ComplexValidation: Story;
+export declare const FormIntegration: Story;

package/dist/components/date/date-time-picker/date-time-picker.types.d.ts

@@ -0,0 +1,245 @@
+import { DateFieldAria, DatePickerAria } from '@react-aria/datepicker';
+import { CalendarState } from '@react-stately/calendar';
+import { DateFieldState, DatePickerState } from '@react-stately/datepicker';
+import { DOMAttributes, FocusEventHandler, InputHTMLAttributes, KeyboardEventHandler, MouseEventHandler, RefObject } from 'react';
+import { DateValidationResult } from '../../../utils/date';
+import { ButtonProps } from '../../buttons';
+/**
+ * Context object passed to the onChange handler of DateTimePicker.
+ * Contains validation information and state for error handling.
+ */
+export interface DateTimePickerChangeHandlerContext extends DateValidationResult {
+    /**
+     * Whether the current date/time value is valid.
+     */
+    valid: boolean;
+}
+/**
+ * Props for the DateTimePicker component.
+ *
+ * The DateTimePicker combines date and time selection in a single component.
+ * It uses DateTimeInput for the input field and provides a popup with both
+ * calendar for date selection and time selectors for hour, minute, and second.
+ */
+export interface DateTimePickerProps {
+    /**
+     * Custom class name for the container of the dropdown component.
+     */
+    className?: string;
+    /**
+     * The date and time that is selected when the component first mounts (uncontrolled).
+     * Should be a JavaScript Date object representing the initial value.
+     */
+    defaultValue?: Date;
+    /**
+     * Whether the date-time picker is disabled.
+     * When disabled, the user cannot interact with the picker and it appears grayed out.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the date-time picker is in an error state.
+     * When true, the picker will display error styling to indicate validation issues.
+     * @default false
+     */
+    error?: boolean;
+    /**
+     * The <form> element to associate the input with.
+     * The value of this attribute must be the id of a <form> in the same document.
+     */
+    form?: string;
+    /**
+     * Determines which date and time segments are displayed and editable.
+     * - `'day'`: Shows only date segments (year, month, day)
+     * - `'hour'`: Shows date and hour segments
+     * - `'minute'`: Shows date, hour, and minute segments
+     * - `'second'`: Shows date, hour, minute, and second segments
+     * @default 'minute'
+     */
+    granularity?: 'day' | 'hour' | 'minute' | 'second';
+    /**
+     * Whether to display time in 12 or 24 hour format.
+     * By default, this is determined by the user's locale.
+     * - `12`: Shows time in 12-hour format with AM/PM
+     * - `24`: Shows time in 24-hour format
+     * @default 12
+     */
+    hourCycle?: 12 | 24;
+    /**
+     * The ID of the input element.
+     * Used for accessibility and form association.
+     */
+    id?: string;
+    /**
+     * The locale to use for formatting the date and time.
+     * Follows BCP 47 language tag format (e.g., 'en-US', 'de-DE', 'ja-JP').
+     * When not provided, uses the user's browser locale.
+     * @example 'en-US', 'de-DE', 'fr-FR'
+     */
+    locale?: string;
+    /**
+     * The maximum date and time that a user can enter.
+     * Dates after this value will be considered invalid.
+     * Should be a JavaScript Date object.
+     */
+    maxDate?: Date;
+    /**
+     * The minimum date and time that a user can enter.
+     * Dates before this value will be considered invalid.
+     * Should be a JavaScript Date object.
+     */
+    minDate?: Date;
+    /**
+     * The name of the input element, used when submitting an HTML form.
+     * See @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name.
+     */
+    name?: string;
+    /**
+     * Handler that is called when the input loses focus.
+     * Receives the blur event from the date/time input.
+     */
+    onBlur?: FocusEventHandler<Element>;
+    /**
+     * Handler that is called when the date/time value changes.
+     * Receives the new Date object or null if the input is cleared,
+     * along with a context object containing validation information.
+     *
+     * @param value - The new date/time value as a Date object, or null if cleared
+     * @param context - Validation context with validity state and messages
+     *
+     * @example
+     * ```tsx
+     * const handleChange = (value: Date | null, context: DateTimePickerChangeHandlerContext) => {
+     *   if (context.valid && value) {
+     *     console.log('Valid date/time selected:', value.toISOString());
+     *   } else {
+     *     console.log('Invalid date/time or validation errors:', context.validationMessage);
+     *   }
+     * };
+     * ```
+     */
+    onChange?: (value: Date | null, context: DateTimePickerChangeHandlerContext) => void;
+    /**
+     * Handler that is called when the input is clicked.
+     * Can be used to programmatically open the picker.
+     */
+    onClick?: MouseEventHandler<Element>;
+    /**
+     * Handler that is called when the input receives focus.
+     * Receives the focus event from the date/time input.
+     */
+    onFocus?: FocusEventHandler<Element>;
+    /**
+     * Handler that is called when a key is pressed within the input.
+     * Receives keyboard events from the date/time input.
+     */
+    onKeyDown?: KeyboardEventHandler<Element>;
+    /**
+     * Handler that is called when a key is released within the input.
+     * Receives keyboard events from the date/time input.
+     */
+    onKeyUp?: KeyboardEventHandler<Element>;
+    /**
+     * Handler that is called when the popup with calendar and time selectors changes state.
+     * Use this to track when the picker is opened or closed.
+     *
+     * @param open - Whether the popup is currently open
+     *
+     * @example
+     * ```tsx
+     * const handleOpenChange = (open: boolean) => {
+     *   console.log(open ? 'Picker opened' : 'Picker closed');
+     * };
+     * ```
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * A placeholder date that influences the format and default values of empty segments.
+     * This date is used to determine the format and structure but is not the actual value.
+     * Useful for setting the year when only month/day are relevant, or timezone context.
+     * Defaults to today's date.
+     *
+     * @default new Date()
+     * @example new Date('2024-12-31T23:59:59') // Shows full format structure
+     */
+    placeholderValue?: Date;
+    /**
+     * Whether the date-time picker is read-only.
+     * When true, the user can see the value but cannot edit it.
+     * The picker will still be focusable and the popup can be opened to view the calendar.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Whether the date-time picker is required for form submission.
+     * When true, the picker must have a value for the form to be valid.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Whether to show the timezone in the date and time picker.
+     * @default false
+     */
+    showTimezone?: boolean;
+    /**
+     * The current date and time value (controlled).
+     * Should be a JavaScript Date object representing the current value,
+     * or null if no value is selected.
+     *
+     * @example
+     * ```tsx
+     * const [value, setValue] = useState<Date | null>(new Date());
+     * return <DateTimePicker value={value} onChange={(newValue) => setValue(newValue)} />;
+     * ```
+     */
+    value?: Date | null;
+}
+/**
+ * Return type for the useDateTimePicker hook.
+ */
+export interface UseDateTimePickerReturn {
+    /** Calendar-related props and state */
+    calendarProps: {
+        /** Props for the calendar component */
+        calendarProps: DOMAttributes<HTMLElement>;
+        /** Ref for the calendar component */
+        calendarRef: RefObject<HTMLDivElement>;
+        /** Calendar state object for date selection */
+        calendarState: CalendarState;
+        /** Props for the next month button */
+        nextButtonProps: Omit<ButtonProps, 'type'>;
+        /** Props for the previous month button */
+        prevButtonProps: Omit<ButtonProps, 'type'>;
+        /** Calendar title string */
+        title: string;
+    };
+    /** Date field-related props and state */
+    dateFieldProps: {
+        /** Ref for the date field hidden input component */
+        dateFieldInputRef: RefObject<HTMLInputElement>;
+        /** Props for the date field component */
+        dateFieldProps: DateFieldAria['fieldProps'];
+        /** Ref for the date field component */
+        dateFieldRef: RefObject<HTMLElement>;
+        /** Date field state object */
+        dateFieldState: DateFieldState;
+        /** Props for the input group container */
+        groupProps: DatePickerAria['groupProps'];
+        /** Props for the hidden input element */
+        hiddenInputProps: InputHTMLAttributes<HTMLInputElement>;
+    };
+    /** The React Aria date picker state object */
+    datePickerState: DatePickerState;
+    /** Props for the popup component */
+    popupProps: {
+        /** Props for the popup dialog container */
+        dialogProps: DatePickerAria['dialogProps'];
+    };
+    /** Time field-related props and handlers */
+    timeFieldProps: {
+        /** Handler for time value changes */
+        onTimeChange: (newTime: Date) => void;
+        /** Current time value as a Date object */
+        timeValue: Date | null;
+    };
+}

package/dist/components/date/date-time-picker/index.d.ts

@@ -0,0 +1,3 @@
+export { default as DateTimePicker } from './date-time-picker';
+export { useDateTimePicker } from './use-date-time-picker';
+export type { DateTimePickerChangeHandlerContext, DateTimePickerProps } from './date-time-picker.types';

package/dist/components/date/date-time-picker/use-date-time-picker.d.ts

@@ -0,0 +1,35 @@
+import { RefObject } from 'react';
+import { DateTimePickerProps, UseDateTimePickerReturn } from './date-time-picker.types';
+/**
+ * Custom hook for the DateTimePicker component.
+ *
+ * This hook manages the interaction between the DateTimeInput, Calendar, and TimeSelectorPanel
+ * components. It handles state synchronization, focus management, and event coordination
+ * between the different parts of the date-time picker.
+ *
+ * ## Features
+ *
+ * - **Unified State Management**: Coordinates date and time state across components
+ * - **Focus Management**: Handles focus trapping and keyboard navigation
+ * - **Event Coordination**: Manages opening/closing and value updates
+ * - **Input Integration**: Provides props for DateTimeInput component
+ * - **Calendar Integration**: Manages calendar state and interactions
+ * - **Time Integration**: Handles time selector state and changes
+ *
+ * @param props - DateTimePicker component props
+ * @param ref - React ref to the container element
+ * @returns Object with calendar state, input props, and time handling
+ *
+ * @example
+ * ```tsx
+ * const state = useDateTimePickerState(props);
+ * const {
+ *   calendarState,
+ *   dateTimeInputProps,
+ *   lockFocus,
+ *   timeValue,
+ *   onTimeChange
+ * } = useDateTimePicker(props, state);
+ * ```
+ */
+export declare const useDateTimePicker: (props: DateTimePickerProps, ref: RefObject<Element>) => UseDateTimePickerReturn;

package/dist/components/date/date-time-range-picker/date-time-range-picker.d.ts

@@ -0,0 +1,94 @@
+import { DateTimeRangePickerProps } from './date-time-range-picker.types';
+/**
+ * DateTimeRangePicker is a composite component that allows users to select a range of dates and times.
+ * It combines two DateTimeInput components for start and end values with a popup containing
+ * a calendar for date selection and time selectors for precise time control.
+ *
+ * Built on top of React Aria's date range picker primitives with extended time support.
+ * The component automatically handles keyboard navigation, accessibility, and
+ * internationalization for both date and time components.
+ *
+ * ## Features
+ *
+ * - **Unified Date/Time Range Selection**: Single component for both date and time ranges
+ * - **Dual Input Fields**: Separate inputs for start and end date/time
+ * - **Calendar Integration**: Full calendar for date range selection
+ * - **Time Selectors**: Dropdown selectors for hour, minute, and second
+ * - **Granularity Control**: Configure precision from day to second level
+ * - **Keyboard Navigation**: Full keyboard support with Enter/Space to open
+ * - **Accessibility**: Screen reader support and proper focus management
+ * - **Internationalization**: Automatic formatting based on locale
+ * - **Validation**: Built-in min/max date/time validation
+ * - **Form Integration**: Works seamlessly with HTML forms
+ *
+ * ## Usage
+ *
+ * ### Basic Usage
+ * ```tsx
+ * import { DateTimeRangePicker } from '@bloomreach/react-banana-ui';
+ *
+ * function MyComponent() {
+ *   const [value, setValue] = useState<DateRangeValue | null>({
+ *     start: new Date('2024-01-01T09:00:00'),
+ *     end: new Date('2024-01-01T17:00:00')
+ *   });
+ *
+ *   return (
+ *     <DateTimeRangePicker
+ *       value={value}
+ *       onChange={(newValue) => setValue(newValue)}
+ *       granularity="minute"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ### With Validation
+ * ```tsx
+ * <DateTimeRangePicker
+ *   value={value}
+ *   onChange={(newValue, context) => {
+ *     if (context.valid) {
+ *       setValue(newValue);
+ *     } else {
+ *       setError(context.validationMessage.join(' '));
+ *     }
+ *   }}
+ *   minDate={new Date('2024-01-01')}
+ *   maxDate={new Date('2024-12-31')}
+ *   granularity="second"
+ *   required
+ * />
+ * ```
+ *
+ * ### Different Granularities
+ * ```tsx
+ * // Date range only
+ * <DateTimeRangePicker granularity="day" />
+ *
+ * // Date and hour range
+ * <DateTimeRangePicker granularity="hour" />
+ *
+ * // Date, hour, and minute range (default)
+ * <DateTimeRangePicker granularity="minute" />
+ *
+ * // Full precision with seconds
+ * <DateTimeRangePicker granularity="second" />
+ * ```
+ *
+ * ## Accessibility
+ *
+ * The component follows WAI-ARIA guidelines for both date and time selection:
+ * - Proper focus management between inputs, calendar, and time selectors
+ * - Screen reader announcements for value changes
+ * - Keyboard navigation with arrow keys in calendar
+ * - Escape key to close, Enter/Space to open
+ * - Support for assistive technologies
+ * - Proper labeling and role attributes
+ *
+ * @param props - The props for the DateTimeRangePicker component
+ * @param forwardedRef - Ref to be forwarded to the container element
+ * @returns A comprehensive date and time range picker component
+ */
+declare const DateTimeRangePicker: import('react').ForwardRefExoticComponent<DateTimeRangePickerProps & import('react').RefAttributes<HTMLDivElement>>;
+export default DateTimeRangePicker;

package/dist/components/date/date-time-range-picker/date-time-range-picker.stories.d.ts

@@ -0,0 +1,19 @@
+import { DateTimeRangePicker } from './index';
+import { Meta, StoryObj } from '@storybook/react';
+declare const meta: Meta<typeof DateTimeRangePicker>;
+export default meta;
+type Story = StoryObj<typeof DateTimeRangePicker>;
+export declare const Basic: Story;
+export declare const WithInitialValue: Story;
+export declare const Controlled: Story;
+export declare const GranularityComparison: Story;
+export declare const HourCycleComparison: Story;
+export declare const WithMinMaxDates: Story;
+export declare const ErrorState: Story;
+export declare const Disabled: Story;
+export declare const ReadOnly: Story;
+export declare const LocaleComparison: Story;
+export declare const WithTimezoneDisplay: Story;
+export declare const RangeScenarios: Story;
+export declare const InteractiveDemo: Story;
+export declare const ComplexValidation: Story;