@carbon-labs/react-date-picker 0.2.0

package/lib/hooks/useDatePicker.js

@@ -0,0 +1,366 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+var React = require('react');
+var datePicker = require('@carbon-labs/primitives/date-picker');
+
+/**
+ * Configuration for the useDatePicker hook
+ * Maintains 100% backwards compatibility with Carbon React v11 API
+ */
+
+/**
+ * Return type for the useDatePicker hook
+ */
+
+// Note: parseDate and temporalToDate functions removed - now using shared utilities
+// from @carbon-labs/primitives/date-picker:
+// - parseDateToPlainDate() handles mm/dd/yyyy, ISO, and Date object parsing
+// - plainDateToDate() converts Temporal.PlainDate to Date objects
+
+/**
+ * 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
+ */
+function useDatePicker(config = {}) {
+  const {
+    datePickerType = 'single',
+    value = '',
+    minDate = null,
+    maxDate = null,
+    dateFormat = 'm/d/Y',
+    closeOnSelect = true,
+    disabled = false,
+    readOnly = false,
+    onChange,
+    onOpen,
+    onClose
+  } = config;
+
+  // Refs for input elements
+  const startInputRef = React.useRef(null);
+  const endInputRef = React.useRef(null);
+  const calendarRef = React.useRef(null);
+
+  // State machine instance (persists across renders)
+  const machineRef = React.useRef(null);
+
+  // React state for triggering re-renders
+  const [context, setContext] = React.useState(() => {
+    // Initialize state machine on first render
+    const machine = new datePicker.DatePickerStateMachine({
+      mode: datePickerType,
+      value,
+      minDate: datePicker.parseDateToPlainDate(minDate),
+      maxDate: datePicker.parseDateToPlainDate(maxDate),
+      dateFormat,
+      isDisabled: disabled,
+      isReadonly: readOnly
+    });
+    machineRef.current = machine;
+    return machine.getContext();
+  });
+  const [state, setState] = React.useState(() => {
+    return machineRef.current?.getState() || datePicker.DatePickerState.IDLE;
+  });
+
+  // Subscribe to state machine changes
+  React.useEffect(() => {
+    const machine = machineRef.current;
+    if (!machine) {
+      return;
+    }
+    const unsubscribe = machine.subscribe(transition => {
+      setContext(transition.context);
+      setState(transition.to);
+
+      // Call Carbon API callbacks
+      if (transition.to === datePicker.DatePickerState.CALENDAR_OPEN && onOpen) {
+        onOpen();
+      }
+      if ((transition.to === datePicker.DatePickerState.IDLE || transition.to === datePicker.DatePickerState.FOCUSED) && transition.from === datePicker.DatePickerState.CALENDAR_OPEN && onClose) {
+        onClose();
+      }
+    });
+    return unsubscribe;
+  }, [onOpen, onClose, context.isOpen]);
+
+  // Track previous dates to prevent infinite loops
+  const prevDatesRef = React.useRef('');
+
+  // Handle onChange callback (convert Temporal.PlainDate to Date[])
+  React.useEffect(() => {
+    if (!onChange) {
+      return;
+    }
+    const dates = [];
+    if (context.startDate) {
+      const date = datePicker.plainDateToDate(context.startDate);
+      if (date) {
+        dates.push(date);
+      }
+    }
+    if (context.endDate) {
+      const date = datePicker.plainDateToDate(context.endDate);
+      if (date) {
+        dates.push(date);
+      }
+    }
+
+    // Create a string representation of dates for comparison
+    const datesKey = dates.map(d => d.toISOString()).join(',');
+
+    // Only call onChange if dates have actually changed
+    if (dates.length > 0 && datesKey !== prevDatesRef.current) {
+      prevDatesRef.current = datesKey;
+      onChange(dates);
+    }
+  }, [context.startDate, context.endDate, onChange]);
+
+  // Update state machine when config changes
+  React.useEffect(() => {
+    const machine = machineRef.current;
+    if (!machine) {
+      return;
+    }
+
+    // Update disabled state
+    if (disabled !== context.isDisabled) {
+      machine.send(disabled ? datePicker.DatePickerEvent.DISABLE : datePicker.DatePickerEvent.ENABLE);
+    }
+
+    // Update readonly state
+    if (readOnly !== context.isReadonly) {
+      machine.send(readOnly ? datePicker.DatePickerEvent.SET_READONLY : datePicker.DatePickerEvent.UNSET_READONLY);
+    }
+
+    // Update min/max dates
+    const newMinDate = datePicker.parseDateToPlainDate(minDate);
+    const newMaxDate = datePicker.parseDateToPlainDate(maxDate);
+    if (newMinDate) {
+      machine.send(datePicker.DatePickerEvent.SET_MIN_DATE, {
+        date: newMinDate
+      });
+    }
+    if (newMaxDate) {
+      machine.send(datePicker.DatePickerEvent.SET_MAX_DATE, {
+        date: newMaxDate
+      });
+    }
+  }, [disabled, readOnly, minDate, maxDate, context.isDisabled, context.isReadonly]);
+
+  // Event handlers
+  const send = React.useCallback((eventType, payload) => {
+    machineRef.current?.send(eventType, payload);
+  }, []);
+  const openCalendar = React.useCallback(() => {
+    // Send CALENDAR_ICON_CLICK to trigger the state transition from IDLE
+    // The state machine will handle transitioning to CALENDAR_OPEN state
+    send(datePicker.DatePickerEvent.CALENDAR_ICON_CLICK);
+  }, [send]);
+  const closeCalendar = React.useCallback(() => {
+    send(datePicker.DatePickerEvent.CALENDAR_CLOSE);
+  }, [send]);
+  const selectDate = React.useCallback(date => {
+    if (datePickerType === 'range') {
+      if (!context.startDate || context.endDate) {
+        // Select start date
+        send(datePicker.DatePickerEvent.RANGE_START_SELECT, {
+          date
+        });
+      } else {
+        // Select end date
+        send(datePicker.DatePickerEvent.RANGE_END_SELECT, {
+          date
+        });
+        if (closeOnSelect) {
+          closeCalendar();
+        }
+      }
+    } else {
+      // Single date selection
+      send(datePicker.DatePickerEvent.DATE_SELECT, {
+        date
+      });
+      if (closeOnSelect) {
+        closeCalendar();
+      }
+    }
+  }, [datePickerType, context.startDate, context.endDate, closeOnSelect, send, closeCalendar]);
+  const handleInputFocus = React.useCallback((inputType = 'from') => {
+    // Send INPUT_FOCUS to transition to FOCUSED state
+    send(datePicker.DatePickerEvent.INPUT_FOCUS, {
+      inputType
+    });
+    // Then send CALENDAR_OPEN to open the calendar
+    // This matches the expected state machine flow: IDLE -> FOCUSED -> CALENDAR_OPEN
+    send(datePicker.DatePickerEvent.CALENDAR_OPEN);
+  }, [send]);
+  const handleInputBlur = React.useCallback(() => {
+    send(datePicker.DatePickerEvent.INPUT_BLUR);
+  }, [send]);
+  const handleInputChange = React.useCallback((value, inputType = 'from') => {
+    send(datePicker.DatePickerEvent.VALUE_CHANGE, {
+      value,
+      inputType
+    });
+  }, [send]);
+
+  // Handle click outside to close calendar using shared utility
+  React.useEffect(() => {
+    if (!context.isOpen) {
+      return;
+    }
+    const handler = new datePicker.ClickOutsideHandler({
+      isOpen: context.isOpen,
+      /**
+       * Check if a node is contained within the date picker elements
+       * @param {Node} node - The node to check
+       * @returns {boolean} True if the node is within the date picker
+       */
+      containsNode: node => {
+        const calendarEl = calendarRef.current;
+        const startInputEl = startInputRef.current;
+        const endInputEl = endInputRef.current;
+        return (calendarEl?.contains(node) ?? false) || (startInputEl?.contains(node) ?? false) || (endInputEl?.contains(node) ?? false);
+      },
+      /**
+       * Handle clicks outside the date picker
+       */
+      onOutsideClick: () => send(datePicker.DatePickerEvent.OUTSIDE_CLICK),
+      useCapture: true,
+      attachDelay: 0
+    });
+    handler.attach();
+    return () => {
+      handler.detach();
+    };
+  }, [context.isOpen, send]);
+
+  // Handle keyboard events
+  React.useEffect(() => {
+    if (!context.isOpen) {
+      return;
+    }
+
+    /**
+     * Handle keyboard events for calendar navigation
+     *
+     * @param {KeyboardEvent} event - Keyboard event
+     */
+    const handleKeyDown = event => {
+      const {
+        key
+      } = event;
+      const target = event.target;
+
+      // Check if focus is in the calendar (not in input fields)
+      const calendarEl = calendarRef.current;
+      const startInputEl = startInputRef.current;
+      const endInputEl = endInputRef.current;
+      const isFocusInCalendar = calendarEl && (calendarEl.contains(target) || target === calendarEl || target.classList?.contains('cds--date-picker__calendar'));
+      const isFocusInInput = target === startInputEl || target === endInputEl || startInputEl && startInputEl.contains(target) || endInputEl && endInputEl.contains(target);
+
+      // Handle Escape key - close calendar (works from anywhere)
+      if (key === 'Escape') {
+        event.preventDefault();
+        send(datePicker.DatePickerEvent.ESCAPE_KEY);
+        return;
+      }
+
+      // Handle Tab key - complex focus management
+      if (key === 'Tab') {
+        // Case 1: Tab FROM input -> Focus the calendar container
+        if (isFocusInInput && !event.shiftKey) {
+          event.preventDefault();
+          // Focus the calendar container which has tabIndex={0}
+          if (calendarEl) {
+            setTimeout(() => {
+              const calendar = calendarEl.querySelector('.cds--date-picker__calendar');
+              if (calendar) {
+                calendar.focus();
+              }
+            }, 0);
+          }
+          return;
+        }
+
+        // Case 2: Shift+Tab FROM calendar -> Focus input
+        if (isFocusInCalendar && event.shiftKey) {
+          event.preventDefault();
+          // Focus the appropriate input based on mode
+          if (datePickerType === 'range' && context.lastFocusedInput === 'to' && endInputEl) {
+            endInputEl.focus();
+          } else if (startInputEl) {
+            startInputEl.focus();
+          }
+          return;
+        }
+
+        // Case 3: Tab FROM calendar -> Close and move to next element
+        if (isFocusInCalendar && !event.shiftKey) {
+          // Let the state machine handle closing
+          send(datePicker.DatePickerEvent.TAB_KEY);
+          // Don't prevent default - let browser move focus naturally
+          return;
+        }
+
+        // For other cases, let default Tab behavior work
+        return;
+      }
+
+      // Only handle navigation keys when focus is in calendar, not in input
+      if (!isFocusInCalendar || isFocusInInput) {
+        return;
+      }
+
+      // Use shared keyboard mapper for navigation keys
+      const mappedEvent = datePicker.mapKeyboardToStateMachineEvent({
+        key,
+        shiftKey: event.shiftKey,
+        mode: datePickerType,
+        state,
+        focusedDate: context.focusedDate
+      });
+      if (mappedEvent) {
+        if (mappedEvent.preventDefault) {
+          event.preventDefault();
+        }
+        if (mappedEvent.eventType) {
+          send(mappedEvent.eventType, mappedEvent.payload);
+        }
+        return;
+      }
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [context.isOpen, context.focusedDate, context.lastFocusedInput, state, datePickerType, send]);
+  return {
+    context,
+    state,
+    isOpen: context.isOpen,
+    send,
+    openCalendar,
+    closeCalendar,
+    selectDate,
+    handleInputFocus,
+    handleInputBlur,
+    handleInputChange,
+    startInputRef,
+    endInputRef,
+    calendarRef
+  };
+}
+
+exports.useDatePicker = useDatePicker;

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export { DatePicker } from './components/DatePicker';
+export { DatePickerInput } from './components/DatePickerInput';
+export { Calendar } from './components/Calendar';
+export { DatePickerSkeleton } from './components/DatePickerSkeleton';
+export { useDatePicker } from './hooks/useDatePicker';
+export type { DatePickerProps } from './components/DatePicker';
+export type { DatePickerInputProps } from './components/DatePickerInput';
+export type { CalendarProps } from './components/Calendar';
+export type { DatePickerSkeletonProps } from './components/DatePickerSkeleton';
+export type { UseDatePickerConfig, UseDatePickerReturn, } from './hooks/useDatePicker';
+export type { DatePickerContext, DatePickerMode, InputType, DateSelectPayload, InputFocusPayload, KeyboardPayload, ValueChangePayload, ValidationErrorPayload, StateTransition, } from '@carbon-labs/primitives/date-picker';
+export { DatePickerState, DatePickerEvent, } from '@carbon-labs/primitives/date-picker';

package/lib/index.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+var DatePicker = require('./components/DatePicker.js');
+var DatePickerInput = require('./components/DatePickerInput.js');
+var Calendar = require('./components/Calendar.js');
+var DatePickerSkeleton = require('./components/DatePickerSkeleton.js');
+var useDatePicker = require('./hooks/useDatePicker.js');
+var datePicker = require('@carbon-labs/primitives/date-picker');
+
+
+
+exports.DatePicker = DatePicker.DatePicker;
+exports.DatePickerInput = DatePickerInput.DatePickerInput;
+exports.Calendar = Calendar.Calendar;
+exports.DatePickerSkeleton = DatePickerSkeleton.DatePickerSkeleton;
+exports.useDatePicker = useDatePicker.useDatePicker;
+Object.defineProperty(exports, "DatePickerEvent", {
+  enumerable: true,
+  get: function () { return datePicker.DatePickerEvent; }
+});
+Object.defineProperty(exports, "DatePickerState", {
+  enumerable: true,
+  get: function () { return datePicker.DatePickerState; }
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@carbon-labs/react-date-picker",
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "description": "Carbon Labs - Date Picker for React",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/carbon-design-system/carbon-labs",
+    "directory": "packages/react/src/components/DatePicker"
+  },
+  "types": "./es/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./es/index.js",
+      "require": "./lib/index.js"
+    },
+    "./es/*": "./es/*",
+    "./lib/*": "./lib/*",
+    "./scss/*": "./scss/*"
+  },
+  "files": [
+    "es",
+    "lib",
+    "scss",
+    "telemetry.yml"
+  ],
+  "scripts": {
+    "build": "node ../../../tasks/build.js",
+    "clean": "rimraf es lib scss",
+    "postinstall": "ibmtelemetry --config=telemetry.yml",
+    "telemetry:config": "npx -y @ibm/telemetry-js-config-generator generate --id 40597fb8-d0ed-45fb-a95a-5b1751e22c36 --endpoint https://www-api.ibm.com/ibm-telemetry/v1/metrics --files ./components/**/*.(tsx|js|jsx)"
+  },
+  "dependencies": {
+    "@carbon-labs/primitives": "0.2.0",
+    "@ibm/telemetry-js": "^1.10.2",
+    "classnames": "^2.3.2"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@carbon-labs/utilities": "0.22.0"
+  },
+  "gitHead": "a90f7c900917a4a25e61fe92a80a564f81cdaa50"
+}

package/scss/date-picker.scss

@@ -0,0 +1,20 @@
+//
+// Copyright IBM Corp. 2019, 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 shared framework-agnostic styles from primitives (built output)
+// Uses Carbon's standard 'cds' prefix for compatibility with Carbon Design System
+@use '@carbon-labs/primitives/es/date-picker/styles/date-picker.scss';
+
+// =============================================================================
+// REACT SPECIFIC STYLES
+// All styles are already class-based in the shared file, so we just import it
+// No :host() or ::slotted() needed for React
+// React components use 'cds' prefix (hardcoded) to match the imported styles
+// =============================================================================
+
+// React uses standard class-based selectors, which are already defined
+// in the shared primitives SCSS file. No additional wrappers needed.

package/telemetry.yml

@@ -0,0 +1,6 @@
+projectId: 40597fb8-d0ed-45fb-a95a-5b1751e22c36
+version: 1
+endpoint: https://www-api.ibm.com/ibm-telemetry/v1/metrics
+collect:
+  - npm
+  - jsx