@carbon-labs/react-date-picker 0.2.0

package/es/components/DatePicker.js

@@ -0,0 +1,182 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, { useRef, Children, isValidElement, cloneElement } from 'react';
+import classNames from 'classnames';
+import { useDatePicker } from '../hooks/useDatePicker.js';
+import { Calendar } from './Calendar.js';
+import { formatPlainDate } from '@carbon-labs/primitives/date-picker';
+
+/**
+ * DatePicker component props
+ * Maintains 100% backwards compatibility with Carbon React v11 API
+ */
+
+/**
+ * DatePicker component
+ * Main wrapper component that orchestrates date picker functionality
+ * Maintains 100% backwards compatibility with Carbon React v11
+ */
+function DatePicker({
+  datePickerType = 'single',
+  dateFormat = 'm/d/Y',
+  minDate,
+  maxDate,
+  locale = 'en',
+  readOnly = false,
+  light = false,
+  short = false,
+  allowInput = true,
+  closeOnSelect = true,
+  onChange,
+  onClose,
+  onOpen,
+  className,
+  children,
+  value
+}) {
+  const containerRef = useRef(null);
+
+  // Use Carbon's standard 'cds' prefix to match Carbon's date-picker styles
+  const prefix = 'cds';
+
+  // Use the date picker hook
+  const {
+    context,
+    isOpen,
+    selectDate,
+    openCalendar,
+    closeCalendar,
+    handleInputFocus,
+    handleInputBlur,
+    handleInputChange,
+    send,
+    startInputRef,
+    endInputRef,
+    calendarRef
+  } = useDatePicker({
+    datePickerType,
+    value,
+    minDate,
+    maxDate,
+    dateFormat,
+    closeOnSelect,
+    readOnly,
+    onChange,
+    onOpen,
+    onClose
+  });
+
+  // Handle calendar navigation
+  const handleNavigate = eventType => {
+    send(eventType);
+  };
+
+  // Handle calendar icon click - toggle calendar open/close
+  const handleIconClick = () => {
+    if (isOpen) {
+      closeCalendar();
+    } else {
+      openCalendar();
+    }
+  };
+
+  // Clone children and inject props
+  const childArray = Children.toArray(children);
+  const enhancedChildren = childArray.map((child, index) => {
+    if (! /*#__PURE__*/isValidElement(child)) {
+      return child;
+    }
+
+    // Determine which input this is (start or end for range mode)
+    const isStartInput = index === 0;
+    const isEndInput = index === 1 && datePickerType === 'range';
+
+    // Get the appropriate ref
+    const inputRef = isStartInput ? startInputRef : isEndInput ? endInputRef : undefined;
+
+    // Get the appropriate value - always use a string to keep input controlled
+    let inputValue = child.props.value ?? '';
+    if (inputValue === '') {
+      if (isStartInput && context.startDate) {
+        inputValue = formatPlainDate(context.startDate, context.dateFormat);
+      } else if (isEndInput && context.endDate) {
+        inputValue = formatPlainDate(context.endDate, context.dateFormat);
+      }
+    }
+
+    // Clone the child with enhanced props
+    const enhancedProps = {
+      ...child.props,
+      value: inputValue,
+      // Always a string, never undefined
+      disabled: child.props.disabled || context.isDisabled,
+      readOnly: child.props.readOnly || readOnly,
+      onFocus: e => {
+        child.props.onFocus?.(e);
+        handleInputFocus(isEndInput ? 'to' : 'from');
+      },
+      onBlur: e => {
+        child.props.onBlur?.(e);
+        handleInputBlur();
+      },
+      onChange: e => {
+        child.props.onChange?.(e);
+        handleInputChange(e.target.value, isEndInput ? 'to' : 'from');
+      },
+      onIconClick: () => {
+        child.props.onIconClick?.();
+        handleIconClick();
+      },
+      hideIcon: datePickerType === 'simple' || child.props.hideIcon
+    };
+
+    // Wrap each input in a container div with proper Carbon classes
+    const containerClasses = classNames(`${prefix}--date-picker-container`, {
+      [`${prefix}--date-picker-container--single`]: datePickerType === 'single',
+      [`${prefix}--date-picker-container--from`]: isStartInput && datePickerType === 'range',
+      [`${prefix}--date-picker-container--to`]: isEndInput && datePickerType === 'range'
+    });
+
+    // Use cloneElement with ref separately to avoid TypeScript issues
+    return /*#__PURE__*/React.createElement("div", {
+      key: child.props.id,
+      className: containerClasses
+    }, /*#__PURE__*/cloneElement(child, {
+      ...enhancedProps,
+      // @ts-expect-error - ref is valid but TypeScript doesn't recognize it in cloneElement
+      ref: inputRef
+    }));
+  });
+
+  // Generate class names
+  const wrapperClasses = classNames(`${prefix}--date-picker`, {
+    [`${prefix}--date-picker--simple`]: datePickerType === 'simple',
+    [`${prefix}--date-picker--single`]: datePickerType === 'single',
+    [`${prefix}--date-picker--range`]: datePickerType === 'range',
+    [`${prefix}--date-picker--light`]: light,
+    [`${prefix}--date-picker--short`]: short,
+    [`${prefix}--date-picker--open`]: isOpen
+  }, className);
+
+  // Don't render calendar for simple mode
+  const shouldRenderCalendar = datePickerType !== 'simple' && isOpen;
+  return /*#__PURE__*/React.createElement("div", {
+    ref: containerRef,
+    className: wrapperClasses
+  }, enhancedChildren, shouldRenderCalendar && /*#__PURE__*/React.createElement("div", {
+    ref: calendarRef,
+    className: `${prefix}--date-picker__calendar-container`
+  }, /*#__PURE__*/React.createElement(Calendar, {
+    context: context,
+    onDateSelect: selectDate,
+    onNavigate: handleNavigate
+  })));
+}
+DatePicker.displayName = 'DatePicker';
+
+export { DatePicker };

package/es/components/DatePickerInput.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+/**
+ * DatePickerInput component props
+ * Maintains 100% backwards compatibility with Carbon React v11 API
+ */
+export interface DatePickerInputProps {
+    /**
+     * The unique identifier for the input (required)
+     */
+    id: string;
+    /**
+     * The label text
+     */
+    labelText?: React.ReactNode;
+    /**
+     * The placeholder text
+     */
+    placeholder?: string;
+    /**
+     * The input size
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Whether the input is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Whether the input is invalid
+     */
+    invalid?: boolean;
+    /**
+     * The invalid text to display
+     */
+    invalidText?: React.ReactNode;
+    /**
+     * Whether the input has a warning
+     */
+    warn?: boolean;
+    /**
+     * The warning text to display
+     */
+    warnText?: React.ReactNode;
+    /**
+     * Helper text to display below the input
+     */
+    helperText?: React.ReactNode;
+    /**
+     * Whether to hide the label visually (still accessible)
+     */
+    hideLabel?: boolean;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * The input value
+     */
+    value?: string;
+    /**
+     * Default value for uncontrolled component
+     */
+    defaultValue?: string;
+    /**
+     * Change handler
+     */
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * Focus handler
+     */
+    onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
+    /**
+     * Blur handler
+     */
+    onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
+    /**
+     * Keydown handler
+     */
+    onKeyDown?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+    /**
+     * Icon description for accessibility
+     */
+    iconDescription?: string;
+    /**
+     * Calendar icon click handler
+     */
+    onIconClick?: () => void;
+    /**
+     * Whether to show the calendar icon
+     */
+    hideIcon?: boolean;
+    /**
+     * Pattern for input validation
+     */
+    pattern?: string;
+    /**
+     * Type of input
+     */
+    type?: string;
+    /**
+     * Whether the input is read-only
+     */
+    readOnly?: boolean;
+    /**
+     * Autocomplete attribute
+     */
+    autoComplete?: string;
+    /**
+     * Name attribute
+     */
+    name?: string;
+    /**
+     * Whether the field is required
+     */
+    required?: boolean;
+    /**
+     * Callback when calendar opens (for internal use)
+     */
+    onOpen?: () => void;
+    /**
+     * Decorator component (e.g., AI Label)
+     */
+    decorator?: React.ReactNode;
+    /**
+     * @deprecated Use `decorator` instead. Will be removed in next major version.
+     */
+    slug?: React.ReactNode;
+}
+/**
+ * DatePickerInput component
+ * Input field for date picker with Carbon Design System styling
+ * Maintains 100% backwards compatibility with Carbon React v11
+ */
+export declare const DatePickerInput: React.ForwardRefExoticComponent<DatePickerInputProps & React.RefAttributes<HTMLInputElement>>;

package/es/components/DatePickerInput.js

@@ -0,0 +1,149 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
+import React, { forwardRef, isValidElement, cloneElement } from 'react';
+import classNames from 'classnames';
+
+var _span, _svg;
+
+/**
+ * DatePickerInput component props
+ * Maintains 100% backwards compatibility with Carbon React v11 API
+ */
+
+/**
+ * DatePickerInput component
+ * Input field for date picker with Carbon Design System styling
+ * Maintains 100% backwards compatibility with Carbon React v11
+ */
+const DatePickerInput = /*#__PURE__*/forwardRef(function DatePickerInput({
+  id,
+  labelText,
+  placeholder = 'mm/dd/yyyy',
+  size = 'md',
+  disabled = false,
+  invalid = false,
+  invalidText,
+  warn = false,
+  warnText,
+  helperText,
+  hideLabel = false,
+  className,
+  value,
+  defaultValue,
+  onChange,
+  onFocus,
+  onBlur,
+  onKeyDown,
+  iconDescription = 'Open calendar',
+  onIconClick,
+  hideIcon = false,
+  pattern,
+  type = 'text',
+  readOnly = false,
+  autoComplete = 'off',
+  name,
+  required = false,
+  onOpen: _onOpen,
+  decorator,
+  slug,
+  ...rest
+}, ref) {
+  // Use Carbon's standard 'cds' prefix to match Carbon's date-picker styles
+  const prefix = 'cds';
+
+  // Check if decorator/slug is an AILabel component
+  const candidate = decorator || slug;
+  const isAILabel = candidate && /*#__PURE__*/isValidElement(candidate) && candidate.type?.displayName === 'AILabel';
+
+  // Clone AILabel with size='mini' if it's an AILabel
+  const normalizedDecorator = isAILabel && /*#__PURE__*/isValidElement(candidate) ? /*#__PURE__*/cloneElement(candidate, {
+    size: 'mini'
+  }) : candidate;
+
+  // Generate class names following Carbon Design System patterns
+  const wrapperClasses = classNames(`${prefix}--date-picker-input__wrapper`, className, {
+    [`${prefix}--date-picker-input__wrapper--slug`]: slug,
+    [`${prefix}--date-picker-input__wrapper--decorator`]: decorator
+  });
+  const inputClasses = classNames(`${prefix}--date-picker__input`, {
+    [`${prefix}--date-picker__input--sm`]: size === 'sm',
+    [`${prefix}--date-picker__input--lg`]: size === 'lg',
+    [`${prefix}--date-picker__input--invalid`]: invalid,
+    [`${prefix}--date-picker__input--warn`]: warn && !invalid
+  });
+  const labelClasses = classNames(`${prefix}--label`, {
+    [`${prefix}--visually-hidden`]: hideLabel,
+    [`${prefix}--label--disabled`]: disabled
+  });
+
+  // Determine which validation message to show
+  const showInvalidText = invalid && invalidText;
+  const showWarnText = !invalid && warn && warnText;
+  const showHelperText = !invalid && !warn && helperText;
+  return /*#__PURE__*/React.createElement(React.Fragment, null, labelText && /*#__PURE__*/React.createElement("label", {
+    htmlFor: id,
+    className: labelClasses
+  }, labelText, required && (_span || (_span = /*#__PURE__*/React.createElement("span", {
+    className: `${prefix}--label__required`
+  }, "*")))), /*#__PURE__*/React.createElement("div", {
+    className: wrapperClasses
+  }, /*#__PURE__*/React.createElement("span", null, /*#__PURE__*/React.createElement("input", _extends({}, rest, {
+    ref: ref,
+    id: id,
+    name: name,
+    type: type,
+    className: inputClasses,
+    placeholder: placeholder,
+    value: value,
+    defaultValue: defaultValue,
+    disabled: disabled,
+    readOnly: readOnly,
+    pattern: pattern,
+    autoComplete: autoComplete,
+    required: required,
+    onChange: onChange,
+    onFocus: onFocus,
+    onBlur: onBlur,
+    onKeyDown: onKeyDown,
+    "aria-invalid": invalid || undefined,
+    "aria-describedby": showInvalidText ? `${id}-error` : showWarnText ? `${id}-warn` : showHelperText ? `${id}-helper` : undefined
+  })), slug ? normalizedDecorator : decorator ? /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--date-picker-input-inner-wrapper--decorator`
+  }, normalizedDecorator) : null, !hideIcon && /*#__PURE__*/React.createElement("button", {
+    type: "button",
+    className: `${prefix}--date-picker__icon`,
+    onClick: onIconClick,
+    disabled: disabled || readOnly,
+    "aria-label": iconDescription,
+    tabIndex: -1
+  }, _svg || (_svg = /*#__PURE__*/React.createElement("svg", {
+    focusable: "false",
+    preserveAspectRatio: "xMidYMid meet",
+    xmlns: "http://www.w3.org/2000/svg",
+    fill: "currentColor",
+    width: "16",
+    height: "16",
+    viewBox: "0 0 32 32",
+    "aria-hidden": "true"
+  }, /*#__PURE__*/React.createElement("path", {
+    d: "M26,4h-4V2h-2v2h-8V2h-2v2H6C4.9,4,4,4.9,4,6v20c0,1.1,0.9,2,2,2h20c1.1,0,2-0.9,2-2V6C28,4.9,27.1,4,26,4z M26,26H6V12h20  V26z M26,10H6V6h4v2h2V6h8v2h2V6h4V10z"
+  })))))), showInvalidText && /*#__PURE__*/React.createElement("div", {
+    id: `${id}-error`,
+    className: `${prefix}--form-requirement`
+  }, invalidText), showWarnText && /*#__PURE__*/React.createElement("div", {
+    id: `${id}-warn`,
+    className: `${prefix}--form-requirement`
+  }, warnText), showHelperText && /*#__PURE__*/React.createElement("div", {
+    id: `${id}-helper`,
+    className: `${prefix}--form__helper-text`
+  }, helperText));
+});
+DatePickerInput.displayName = 'DatePickerInput';
+
+export { DatePickerInput };

package/es/components/DatePickerSkeleton.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright IBM Corp. 2016, 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+export interface DatePickerSkeletonProps {
+    /**
+     * Specify whether the skeleton should be a range date picker
+     */
+    range?: boolean;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+}
+/**
+ * DatePickerSkeleton component for loading states
+ */
+export declare const DatePickerSkeleton: React.FC<DatePickerSkeletonProps>;
+export default DatePickerSkeleton;

package/es/components/DatePickerSkeleton.js

@@ -0,0 +1,39 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+var _div, _div2;
+/**
+ * DatePickerSkeleton component for loading states
+ */
+const DatePickerSkeleton = ({
+  range = false,
+  className
+}) => {
+  // Use 'cds' prefix to match Carbon's skeleton styles
+  const prefix = 'cds';
+  return /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--form-item`
+  }, /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--date-picker ${prefix}--date-picker--${range ? 'range' : 'single'} ${prefix}--skeleton ${className || ''}`
+  }, _div || (_div = /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--date-picker-container`
+  }, /*#__PURE__*/React.createElement("span", {
+    className: `${prefix}--label ${prefix}--skeleton`
+  }), /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--date-picker__input ${prefix}--skeleton`
+  }))), range && (_div2 || (_div2 = /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--date-picker-container`
+  }, /*#__PURE__*/React.createElement("span", {
+    className: `${prefix}--label ${prefix}--skeleton`
+  }), /*#__PURE__*/React.createElement("div", {
+    className: `${prefix}--date-picker__input ${prefix}--skeleton`
+  }))))));
+};
+
+export { DatePickerSkeleton };

package/es/hooks/useDatePicker.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { DatePickerState, type DatePickerContext } from '@carbon-labs/primitives/date-picker';
+/**
+ * Configuration for the useDatePicker hook
+ * Maintains 100% backwards compatibility with Carbon React v11 API
+ */
+export interface UseDatePickerConfig {
+    /**
+     * The type of date picker (Carbon API uses datePickerType, not mode)
+     */
+    datePickerType?: 'simple' | 'single' | 'range';
+    /**
+     * Initial value as ISO date string
+     */
+    value?: string;
+    /**
+     * Minimum selectable date (mm/dd/yyyy format - Carbon API)
+     */
+    minDate?: string | null;
+    /**
+     * Maximum selectable date (mm/dd/yyyy format - Carbon API)
+     */
+    maxDate?: string | null;
+    /**
+     * Date format string (Flatpickr-compatible format)
+     */
+    dateFormat?: string;
+    /**
+     * Whether to allow manual input
+     */
+    allowInput?: boolean;
+    /**
+     * Whether to close calendar on date selection
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Whether the picker is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Whether the picker is read-only (Carbon uses readOnly, not readonly)
+     */
+    readOnly?: boolean;
+    /**
+     * Locale for date formatting
+     */
+    locale?: string;
+    /**
+     * Change handler - receives array of Date objects (Carbon API)
+     */
+    onChange?: (dates: Date[]) => void;
+    /**
+     * Open handler
+     */
+    onOpen?: () => void;
+    /**
+     * Close handler
+     */
+    onClose?: () => void;
+}
+/**
+ * Return type for the useDatePicker hook
+ */
+export interface UseDatePickerReturn {
+    /**
+     * Current state machine context
+     */
+    context: DatePickerContext;
+    /**
+     * Current state
+     */
+    state: DatePickerState;
+    /**
+     * Whether the calendar is open
+     */
+    isOpen: boolean;
+    /**
+     * Send an event to the state machine
+     */
+    send: (eventType: string, payload?: any) => void;
+    /**
+     * Open the calendar
+     */
+    openCalendar: () => void;
+    /**
+     * Close the calendar
+     */
+    closeCalendar: () => void;
+    /**
+     * Select a date
+     */
+    selectDate: (date: Temporal.PlainDate) => void;
+    /**
+     * Handle input focus
+     */
+    handleInputFocus: (inputType?: 'from' | 'to') => void;
+    /**
+     * Handle input blur
+     */
+    handleInputBlur: () => void;
+    /**
+     * Handle input value change
+     */
+    handleInputChange: (value: string, inputType?: 'from' | 'to') => void;
+    /**
+     * Ref for the start input
+     */
+    startInputRef: React.RefObject<HTMLInputElement>;
+    /**
+     * Ref for the end input (range mode)
+     */
+    endInputRef: React.RefObject<HTMLInputElement>;
+    /**
+     * Ref for the calendar container
+     */
+    calendarRef: React.RefObject<HTMLDivElement>;
+}
+/**
+ * React hook for managing date picker state using the shared state machine
+ * Maintains 100% backwards compatibility with Carbon React v11 API
+ *
+ * @param {UseDatePickerConfig} config - Configuration options
+ * @returns {UseDatePickerReturn} Hook return object with state and handlers
+ */
+export declare function useDatePicker(config?: UseDatePickerConfig): UseDatePickerReturn;