@carbon/utilities 0.23.0 → 0.24.0

package/es/date-picker/index.d.ts

@@ -0,0 +1,993 @@
+//#region src/date-picker/primitives/states.d.ts
+/**
+ * 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.
+ */
+/**
+ * Date picker state machine states
+ */
+declare enum DatePickerState {
+  /**
+   * Initial state - calendar closed, no focus
+   */
+  IDLE = "idle",
+  /**
+   * Input has focus, calendar closed
+   */
+  FOCUSED = "focused",
+  /**
+   * Calendar dropdown is open
+   */
+  CALENDAR_OPEN = "calendar_open",
+  /**
+   * User is selecting the start date (range mode)
+   */
+  SELECTING_START = "selecting_start",
+  /**
+   * User is selecting the end date (range mode)
+   */
+  SELECTING_END = "selecting_end",
+  /**
+   * Date(s) have been selected
+   */
+  DATE_SELECTED = "date_selected",
+  /**
+   * Component is disabled
+   */
+  DISABLED = "disabled",
+  /**
+   * Component is read-only
+   */
+  READONLY = "readonly",
+  /**
+   * Component is in an error state
+   */
+  ERROR = "error"
+}
+/**
+ * Date picker events
+ */
+declare enum DatePickerEvent {
+  INPUT_FOCUS = "INPUT_FOCUS",
+  INPUT_BLUR = "INPUT_BLUR",
+  INPUT_CHANGE = "INPUT_CHANGE",
+  CALENDAR_ICON_CLICK = "CALENDAR_ICON_CLICK",
+  CALENDAR_OPEN = "CALENDAR_OPEN",
+  CALENDAR_CLOSE = "CALENDAR_CLOSE",
+  PREV_MONTH = "PREV_MONTH",
+  NEXT_MONTH = "NEXT_MONTH",
+  PREV_YEAR = "PREV_YEAR",
+  NEXT_YEAR = "NEXT_YEAR",
+  GO_TO_TODAY = "GO_TO_TODAY",
+  DATE_SELECT = "DATE_SELECT",
+  RANGE_START_SELECT = "RANGE_START_SELECT",
+  RANGE_END_SELECT = "RANGE_END_SELECT",
+  OUTSIDE_CLICK = "OUTSIDE_CLICK",
+  ESCAPE_KEY = "ESCAPE_KEY",
+  TAB_KEY = "TAB_KEY",
+  SHIFT_TAB_KEY = "SHIFT_TAB_KEY",
+  ENTER_KEY = "ENTER_KEY",
+  ARROW_UP = "ARROW_UP",
+  ARROW_DOWN = "ARROW_DOWN",
+  ARROW_LEFT = "ARROW_LEFT",
+  ARROW_RIGHT = "ARROW_RIGHT",
+  PAGE_UP = "PAGE_UP",
+  PAGE_DOWN = "PAGE_DOWN",
+  HOME_KEY = "HOME_KEY",
+  END_KEY = "END_KEY",
+  DISABLE = "DISABLE",
+  ENABLE = "ENABLE",
+  SET_READONLY = "SET_READONLY",
+  UNSET_READONLY = "UNSET_READONLY",
+  VALUE_CHANGE = "VALUE_CHANGE",
+  VALIDATION_ERROR = "VALIDATION_ERROR",
+  CLEAR_ERROR = "CLEAR_ERROR",
+  SET_MIN_DATE = "SET_MIN_DATE",
+  SET_MAX_DATE = "SET_MAX_DATE",
+  SET_DATE_FORMAT = "SET_DATE_FORMAT"
+}
+//#endregion
+//#region src/date-picker/primitives/types.d.ts
+/**
+ * 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.
+ */
+/**
+ * Temporal API type declarations
+ * Using Temporal for modern date handling
+ */
+declare global {
+  namespace Temporal {
+    interface PlainDate {
+      readonly year: number;
+      readonly month: number;
+      readonly day: number;
+      readonly daysInMonth: number;
+      toString(): string;
+      with(dateLike: {
+        year?: number;
+        month?: number;
+        day?: number;
+      }): PlainDate;
+      add(duration: {
+        days?: number;
+        months?: number;
+        years?: number;
+      }): PlainDate;
+      until(other: PlainDate): {
+        days: number;
+      };
+      toPlainYearMonth(): PlainYearMonth;
+    }
+    interface PlainYearMonth {
+      readonly year: number;
+      readonly month: number;
+      readonly daysInMonth: number;
+      toString(): string;
+      toPlainDate(dayLike: {
+        day: number;
+      }): PlainDate;
+      add(duration: {
+        months?: number;
+        years?: number;
+      }): PlainYearMonth;
+      subtract(duration: {
+        months?: number;
+        years?: number;
+      }): PlainYearMonth;
+    }
+    interface PlainYearMonthConstructor {
+      from(item: string | {
+        year: number;
+        month: number;
+      }): PlainYearMonth;
+      compare(one: PlainYearMonth, two: PlainYearMonth): number;
+    }
+    const PlainYearMonth: PlainYearMonthConstructor;
+    interface PlainDateConstructor {
+      from(item: string | {
+        year: number;
+        month: number;
+        day: number;
+      }): PlainDate;
+      compare(one: PlainDate, two: PlainDate): number;
+    }
+    const PlainDate: PlainDateConstructor;
+    interface Now {
+      plainDateISO(): PlainDate;
+    }
+    const Now: Now;
+  }
+}
+/**
+ * Date picker modes
+ */
+type DatePickerMode = 'simple' | 'single' | 'range';
+/**
+ * Input type for range mode
+ */
+type InputType = 'from' | 'to';
+/**
+ * Input target for focus restoration
+ */
+type FocusRestoreTarget = InputType | null;
+/**
+ * Date picker state machine context
+ * Contains all the state needed to manage the datepicker
+ * Uses Temporal.PlainDate for robust date handling
+ */
+interface DatePickerContext {
+  /** The mode of the date picker */
+  mode: DatePickerMode;
+  /** The current value as ISO date string(s) */
+  value: string;
+  /** The selected start date (using Temporal API) */
+  startDate: Temporal.PlainDate | null;
+  /** The selected end date (range mode only, using Temporal API) */
+  endDate: Temporal.PlainDate | null;
+  /** Whether the calendar dropdown is open */
+  isOpen: boolean;
+  /** Whether an input has focus */
+  isFocused: boolean;
+  /** Whether the component is disabled */
+  isDisabled: boolean;
+  /** Whether the component is readonly */
+  isReadonly: boolean;
+  /** Whether the component is in an invalid state */
+  isInvalid: boolean;
+  /** The last focused input (for range mode) */
+  lastFocusedInput: InputType | null;
+  /** The input that should receive focus after a selection-driven close */
+  restoreFocusTo: FocusRestoreTarget;
+  /** Whether focus should be restored after the next close/render cycle */
+  shouldRestoreFocus: boolean;
+  /** Minimum selectable date (using Temporal API) */
+  minDate: Temporal.PlainDate | null;
+  /** Maximum selectable date (using Temporal API) */
+  maxDate: Temporal.PlainDate | null;
+  /** Date format string */
+  dateFormat: string;
+  /** Whether to allow manual input */
+  allowInput: boolean;
+  /** Whether to close calendar on date selection */
+  closeOnSelect: boolean;
+  /** Error message if any */
+  errorMessage?: string;
+  /** The currently viewed month in the calendar (using Temporal API) */
+  viewDate: Temporal.PlainDate | null;
+  /** The date that currently has keyboard focus in the calendar */
+  focusedDate: Temporal.PlainDate | null;
+}
+/**
+ * Event payload types
+ */
+interface DateSelectPayload {
+  date: Temporal.PlainDate;
+  inputType?: InputType;
+}
+interface InputFocusPayload {
+  inputType: InputType;
+}
+interface KeyboardPayload {
+  key: string;
+  shiftKey?: boolean;
+}
+interface ValueChangePayload {
+  value: string;
+}
+interface ValidationErrorPayload {
+  message: string;
+}
+/**
+ * Date picker event
+ */
+interface DatePickerEvent$1<T = unknown> {
+  type: string;
+  payload?: T;
+  timestamp: number;
+}
+/**
+ * State transition information
+ */
+interface StateTransition {
+  from: string;
+  to: string;
+  event: DatePickerEvent$1;
+  context: DatePickerContext;
+}
+/**
+ * Guard function type - determines if a transition is allowed
+ */
+type StateGuard = (context: DatePickerContext, event: DatePickerEvent$1) => boolean;
+/**
+ * Action function type - updates context during transition
+ */
+type StateAction = (context: DatePickerContext, event: DatePickerEvent$1) => Partial<DatePickerContext>;
+/**
+ * Side effect function type - performs side effects after transition
+ */
+type SideEffect = (context: DatePickerContext, event: DatePickerEvent$1) => void;
+/**
+ * Transition listener function type
+ */
+type TransitionListener = (transition: StateTransition) => void;
+/**
+ * State configuration
+ */
+interface StateConfig {
+  guards?: Record<string, StateGuard>;
+  actions?: Record<string, StateAction>;
+  effects?: Record<string, SideEffect>;
+}
+/**
+ * Transition map type
+ */
+type TransitionMap = Record<string, Partial<Record<string, string>>>;
+//#endregion
+//#region src/date-picker/primitives/machine.d.ts
+/**
+ * Date picker state machine
+ * Manages state transitions and context updates for the date picker
+ */
+declare class DatePickerStateMachine {
+  private currentState;
+  private context;
+  private listeners;
+  /**
+   * Create a new date picker state machine
+   *
+   * @param {Partial<DatePickerContext>} initialContext - Initial context values
+   */
+  constructor(initialContext?: Partial<DatePickerContext>);
+  /**
+   * Create initial context with defaults
+   *
+   * @param {Partial<DatePickerContext>} partial - Partial context to merge with defaults
+   * @returns Complete context object
+   */
+  private createInitialContext;
+  /**
+   * Send an event to the state machine
+   * This is the primary method for triggering state transitions
+   *
+   * @param {string} eventType - The type of event to send
+   * @param {unknown} payload - Optional event payload
+   * @returns The updated context
+   */
+  send(eventType: string, payload?: unknown): DatePickerContext;
+  /**
+   * Get the current state
+   *
+   * @returns The current state
+   */
+  getState(): DatePickerState;
+  /**
+   * Get the current context
+   *
+   * @returns A copy of the current context
+   */
+  getContext(): DatePickerContext;
+  /**
+   * Update context directly (use sparingly)
+   *
+   * @param {Partial<DatePickerContext>} updates - Partial context updates
+   * @returns The updated context
+   */
+  updateContext(updates: Partial<DatePickerContext>): DatePickerContext;
+  /**
+   * Subscribe to state transitions
+   *
+   * @param {TransitionListener} listener - Function to call on each transition
+   * @returns Unsubscribe function
+   */
+  subscribe(listener: TransitionListener): () => void;
+  /**
+   * Check if a transition is valid from the current state
+   *
+   * @param {string} eventType - The event type to check
+   * @returns True if the transition is valid
+   */
+  canTransition(eventType: string): boolean;
+  /**
+   * Get the next state for a given event
+   *
+   * @param {DatePickerState} from - Current state
+   * @param {DatePickerEvent} event - The event
+   * @returns Next state or null if no transition exists
+   */
+  private getNextState;
+  /**
+   * Notify all listeners of a state transition
+   *
+   * @param {StateTransition} transition - The state transition
+   */
+  private notifyListeners;
+  /**
+   * Reset the state machine to initial state
+   *
+   * @param {Partial<DatePickerContext>} initialContext - Optional new initial context
+   */
+  reset(initialContext?: Partial<DatePickerContext>): void;
+}
+//#endregion
+//#region src/date-picker/primitives/guards.d.ts
+/**
+ * Guard map - determines if transitions are allowed
+ */
+type GuardMap = Record<DatePickerState, Partial<Record<string, StateGuard>>>;
+/**
+ * Check if component is in single mode
+ * @param {DatePickerContext} context - Current context
+ * @returns {boolean} True if in single mode
+ */
+declare const isSingleMode: (context: DatePickerContext) => boolean;
+/**
+ * Guards for state transitions
+ */
+declare const guards: GuardMap;
+/**
+ * Get guard for a specific state and event
+ *
+ * @param {DatePickerState} state - The current state
+ * @param {string} eventType - The event type
+ * @returns {StateGuard | undefined} The guard function or undefined
+ */
+declare function getGuard(state: DatePickerState, eventType: string): StateGuard | undefined;
+/**
+ * Check if a transition is guarded and allowed
+ *
+ * @param {DatePickerState} state - The current state
+ * @param {string} eventType - The event type
+ * @param {DatePickerContext} context - The current context
+ * @param {DatePickerEvent} event - The event
+ * @returns {boolean} True if guard passes
+ */
+declare function checkGuard(state: DatePickerState, eventType: string, context: DatePickerContext, event: DatePickerEvent$1): boolean;
+//#endregion
+//#region src/date-picker/primitives/actions.d.ts
+/**
+ * Action map - updates context during transitions
+ */
+type ActionMap = Record<DatePickerState, Partial<Record<string, StateAction>>>;
+/**
+ * Actions for state transitions
+ */
+declare const actions: ActionMap;
+/**
+ * Get action for a specific state and event
+ *
+ * @param {DatePickerState} state - The current state
+ * @param {string} eventType - The event type
+ * @returns {StateAction | undefined} The action function or undefined
+ */
+declare function getAction(state: DatePickerState, eventType: string): StateAction | undefined;
+/**
+ * Execute an action and return context updates
+ *
+ * @param {DatePickerState} state - The current state
+ * @param {string} eventType - The event type
+ * @param {DatePickerContext} context - The current context
+ * @param {DatePickerEvent} event - The event
+ * @returns {Partial<DatePickerContext>} Partial context updates
+ */
+declare function executeAction(state: DatePickerState, eventType: string, context: DatePickerContext, event: DatePickerEvent$1): Partial<DatePickerContext>;
+//#endregion
+//#region src/date-picker/primitives/effects.d.ts
+/**
+ * Effect map - performs side effects after transitions
+ */
+type EffectMap = Record<DatePickerState, Partial<Record<string, SideEffect>>>;
+/**
+ * Side effects for state transitions
+ * These are executed after the state transition is complete
+ */
+declare const effects: EffectMap;
+/**
+ * Get effect for a specific state and event
+ *
+ * @param {DatePickerState} state - The current state
+ * @param {string} eventType - The event type
+ * @returns The effect function or undefined
+ */
+declare function getEffect(state: DatePickerState, eventType: string): SideEffect | undefined;
+/**
+ * Execute an effect
+ *
+ * @param {DatePickerState} state - The current state
+ * @param {string} eventType - The event type
+ * @param {DatePickerContext} context - The current context
+ * @param {DatePickerEvent} event - The event
+ */
+declare function executeEffect(state: DatePickerState, eventType: string, context: DatePickerContext, event: DatePickerEvent$1): void;
+//#endregion
+//#region src/date-picker/primitives/click-outside-handler.d.ts
+/**
+ * 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.
+ */
+/**
+ * Configuration for click outside detection
+ */
+interface ClickOutsideConfig {
+  /**
+   * Whether the component is currently open/active
+   */
+  isOpen: boolean;
+  /**
+   * Function to check if a node is within the component
+   *
+   * React example:
+   * ```typescript
+   * containsNode: (node) => {
+   *   return (
+   *     (calendarRef.current?.contains(node) ?? false) ||
+   *     (startInputRef.current?.contains(node) ?? false) ||
+   *     (endInputRef.current?.contains(node) ?? false)
+   *   );
+   * }
+   * ```
+   *
+   * Web Components example:
+   * ```typescript
+   * containsNode: (node) => {
+   *   return this.contains(node) || (this.shadowRoot?.contains(node) ?? false);
+   * }
+   * ```
+   */
+  containsNode: (node: Node) => boolean;
+  /**
+   * Callback when click outside is detected
+   */
+  onOutsideClick: () => void;
+  /**
+   * Whether to use capture phase (default: true)
+   * Using capture phase ensures the handler runs before other click handlers
+   */
+  useCapture?: boolean;
+  /**
+   * Delay in milliseconds before attaching listener (default: 0)
+   *
+   * Setting this to 0 uses a defensive approach where the listener is attached
+   * on the next event loop tick, preventing the click that opened the component
+   * from immediately triggering a close.
+   *
+   * This is particularly important when the same click that opens the calendar
+   * might otherwise be caught by the outside click handler.
+   */
+  attachDelay?: number;
+}
+/**
+ * Creates a click outside handler with proper lifecycle management
+ *
+ * This utility provides a framework-agnostic way to detect clicks outside
+ * a component and trigger a callback. It combines best practices from both
+ * React and Web Components implementations:
+ *
+ * - Uses defensive timing (from React) to prevent the opening click from closing
+ * - Supports flexible element detection (from Web Components)
+ * - Provides clean lifecycle management
+ * - Fully testable and reusable
+ *
+ * @example React usage
+ * ```typescript
+ * useEffect(() => {
+ *   if (!context.isOpen) {
+ *     return;
+ *   }
+ *
+ *   const handler = new ClickOutsideHandler({
+ *     isOpen: context.isOpen,
+ *     containsNode: (node: 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)
+ *       );
+ *     },
+ *     onOutsideClick: () => send(DatePickerEvent.OUTSIDE_CLICK),
+ *     useCapture: true,
+ *     attachDelay: 0,
+ *   });
+ *
+ *   handler.attach();
+ *
+ *   return () => {
+ *     handler.detach();
+ *   };
+ * }, [context.isOpen, send]);
+ * ```
+ *
+ * @example Web Components usage
+ * ```typescript
+ * connectedCallback() {
+ *   super.connectedCallback();
+ *
+ *   this._clickOutsideHandler = new ClickOutsideHandler({
+ *     isOpen: this.open,
+ *     containsNode: (node: Node) => {
+ *       return this.contains(node) || (this.shadowRoot?.contains(node) ?? false);
+ *     },
+ *     onOutsideClick: () => {
+ *       if (this._adapter) {
+ *         this._adapter.send(DatePickerEvent.OUTSIDE_CLICK);
+ *       }
+ *     },
+ *     useCapture: true,
+ *     attachDelay: 0,
+ *   });
+ *
+ *   this._clickOutsideHandler.attach();
+ * }
+ *
+ * disconnectedCallback() {
+ *   super.disconnectedCallback();
+ *   this._clickOutsideHandler?.detach();
+ *   this._clickOutsideHandler = null;
+ * }
+ *
+ * updated(changedProperties: PropertyValues) {
+ *   super.updated(changedProperties);
+ *
+ *   if (changedProperties.has('open')) {
+ *     this._clickOutsideHandler?.updateConfig({ isOpen: this.open });
+ *   }
+ * }
+ * ```
+ */
+declare class ClickOutsideHandler {
+  private handler;
+  private timeoutId;
+  private config;
+  /**
+   * Creates a new ClickOutsideHandler instance
+   *
+   * @param {ClickOutsideConfig} config - Configuration for the click outside handler
+   */
+  constructor(config: ClickOutsideConfig);
+  /**
+   * The actual click handler that checks if click is outside
+   *
+   * @param {MouseEvent} event - The mouse event
+   */
+  private handleClick;
+  /**
+   * Attach the click outside listener
+   *
+   * This method adds the click event listener to the document.
+   * If attachDelay is configured, it will delay the attachment to prevent
+   * the opening click from immediately triggering a close.
+   *
+   * Calling attach() multiple times is safe - it will only attach once.
+   */
+  attach(): void;
+  /**
+   * Detach the click outside listener
+   *
+   * This method removes the click event listener and cleans up any pending timeouts.
+   * It's safe to call detach() multiple times or even if attach() was never called.
+   *
+   * Always call detach() when the component unmounts or when you no longer need
+   * click outside detection to prevent memory leaks.
+   */
+  detach(): void;
+  /**
+   * Update configuration
+   *
+   * This is useful in React when dependencies change, or in Web Components
+   * when properties update. You can update any part of the configuration
+   * without needing to detach and reattach the handler.
+   *
+   * @param {Partial<ClickOutsideConfig>} config - Partial configuration to update
+   *
+   * @example
+   * ```typescript
+   * // Update just the isOpen state
+   * handler.updateConfig({ isOpen: true });
+   *
+   * // Update multiple properties
+   * handler.updateConfig({
+   *   isOpen: true,
+   *   onOutsideClick: newCallback
+   * });
+   * ```
+   */
+  updateConfig(config: Partial<ClickOutsideConfig>): void;
+  /**
+   * Check if the handler is currently attached
+   *
+   * @returns true if the handler is attached, false otherwise
+   */
+  isAttached(): boolean;
+  /**
+   * Check if there's a pending attachment
+   *
+   * @returns true if attachment is pending (waiting for delay), false otherwise
+   */
+  isPending(): boolean;
+}
+//#endregion
+//#region src/date-picker/primitives/keyboard-utils.d.ts
+/**
+ * Information needed to map a keyboard event to a state machine event
+ */
+interface KeyboardEventInfo {
+  /** The keyboard key that was pressed */
+  key: string;
+  /** Whether the shift key was held */
+  shiftKey: boolean;
+  /** The current date picker mode */
+  mode: DatePickerMode;
+  /** The current state machine state */
+  state: DatePickerState;
+  /** The currently focused date in the calendar */
+  focusedDate: Temporal.PlainDate | null;
+}
+/**
+ * Result of mapping a keyboard event to a state machine event
+ */
+interface KeyboardEventResult {
+  /** The state machine event type to dispatch, or null if key not handled */
+  eventType: string | null;
+  /** Optional payload for the event */
+  payload?: {
+    date: Temporal.PlainDate;
+  };
+  /** Whether to call preventDefault on the keyboard event */
+  preventDefault: boolean;
+}
+/**
+ * Map a keyboard event to a state machine event
+ * This provides a single source of truth for keyboard shortcuts across React and Web Components
+ *
+ * @param {KeyboardEventInfo} info - Information about the keyboard event and current state
+ * @returns {KeyboardEventResult | null} The state machine event to dispatch, or null if key not handled
+ */
+declare function mapKeyboardToStateMachineEvent(info: KeyboardEventInfo): KeyboardEventResult | null;
+//#endregion
+//#region src/date-picker/primitives/calendar-grid.d.ts
+/**
+ * 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.
+ */
+/**
+ * A single day cell in the calendar grid.
+ */
+interface CalendarDay {
+  date: Temporal.PlainDate;
+  isCurrentMonth: boolean;
+  isDisabled: boolean;
+  isToday: boolean;
+}
+/**
+ * Generate the calendar grid for the month containing `viewDate`.
+ *
+ *
+ * @param {Temporal.PlainDate} viewDate - The date to generate calendar for
+ * @param {Temporal.PlainDate | null} minDate - Minimum selectable date (inclusive), or `null` for no lower bound.
+ * @param {Temporal.PlainDate | null} maxDate - Maximum selectable date (inclusive), or `null` for no upper bound.
+ * @param {number} weekStartsOn - First day of the week: 0 = Sunday (default) through 6 = Saturday.
+ * @returns {CalendarDay[][]} 6×7 grid of day cells (weeks × days).
+ */
+declare function generateCalendarGrid(viewDate: Temporal.PlainDate, minDate?: Temporal.PlainDate | null, maxDate?: Temporal.PlainDate | null, weekStartsOn?: number): CalendarDay[][];
+//#endregion
+//#region src/date-picker/primitives/calendar-labels.d.ts
+/**
+ * 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.
+ */
+/**
+ * Get the month-and-year heading for the calendar (e.g. "January 2026").
+ *
+ * @param {Temporal.PlainDate} viewDate - Any date within the displayed month.
+ * @param {string} locale - BCP 47 locale tag (default 'en').
+ * @returns {string} Localized "month year" label.
+ */
+declare function getMonthYearLabel(viewDate: Temporal.PlainDate, locale?: string): string;
+/**
+ * Get a full, localized label for a single date (e.g. "January 1, 2026"),
+ * suitable for a day cell's `aria-label`.
+ *
+ * @param {Temporal.PlainDate} date - The date to label.
+ * @param {string} locale - BCP 47 locale tag (default 'en').
+ * @returns {string} Localized full-date label.
+ */
+declare function getFullDateLabel(date: Temporal.PlainDate, locale?: string): string;
+/**
+ * Get the ordered weekday header labels.
+ *
+ * For English locales this returns `S M T W Th F S`,
+ * with `Th` disambiguating Thursday from Tuesday). Other
+ * locales get their `Intl` short weekday names unchanged.
+ *
+ * @param {string} locale - BCP 47 locale tag (default 'en').
+ * @param {number} weekStartsOn - First day of the week: 0 = Sunday (default) through 6 = Saturday.
+ * @returns {string[]} Seven weekday labels, ordered from `weekStartsOn`.
+ */
+declare function getWeekdayLabels(locale?: string, weekStartsOn?: number): string[];
+//#endregion
+//#region src/date-picker/primitives/temporal-utils.d.ts
+/**
+ * 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.
+ */
+/**
+ * Temporal API utilities for date picker
+ * Uses the modern Temporal API for robust date handling
+ */
+/**
+ * Convert a Date object to Temporal.PlainDate
+ *
+ * @param {Date} date - JavaScript Date object
+ * @returns Temporal.PlainDate
+ */
+declare function dateToPlainDate(date: Date): Temporal.PlainDate;
+/**
+ * Convert Temporal.PlainDate to Date object
+ *
+ * @param {Temporal.PlainDate} plainDate - Temporal.PlainDate
+ * @returns JavaScript Date object
+ */
+declare function plainDateToDate(plainDate: Temporal.PlainDate): Date;
+/**
+ * Convert Temporal.PlainDate to ISO date string (YYYY-MM-DD)
+ *
+ * @param {Temporal.PlainDate} plainDate - Temporal.PlainDate
+ * @returns ISO date string
+ */
+declare function plainDateToISOString(plainDate: Temporal.PlainDate): string;
+/**
+ * Parse ISO date string to Temporal.PlainDate
+ *
+ * @param {string} isoString - ISO date string (YYYY-MM-DD)
+ * @returns Temporal.PlainDate or null if invalid
+ */
+declare function parseISOToPlainDate(isoString: string): Temporal.PlainDate | null;
+/**
+ * Parse a date string in various formats to Temporal.PlainDate
+ * Supports: ISO (YYYY-MM-DD), US (MM/DD/YYYY), and JavaScript Date objects
+ *
+ * @param {string | Date} dateInput - Date string or Date object
+ * @returns Temporal.PlainDate or null if invalid
+ */
+declare function parseDateToPlainDate(dateInput: string | Date | null | undefined): Temporal.PlainDate | null;
+/**
+ * Compare two Temporal.PlainDate objects
+ *
+ * @param {Temporal.PlainDate} date1 - First date
+ * @param {Temporal.PlainDate} date2 - Second date
+ * @returns -1 if date1 < date2, 0 if equal, 1 if date1 > date2
+ */
+declare function comparePlainDates(date1: Temporal.PlainDate, date2: Temporal.PlainDate): number;
+/**
+ * Check if a date is within a range
+ *
+ * @param {Temporal.PlainDate} date - Date to check
+ * @param {Temporal.PlainDate | null} minDate - Minimum date (inclusive)
+ * @param {Temporal.PlainDate | null} maxDate - Maximum date (inclusive)
+ * @returns True if date is within range
+ */
+declare function isDateInRange(date: Temporal.PlainDate, minDate: Temporal.PlainDate | null, maxDate: Temporal.PlainDate | null): boolean;
+/**
+ * Format a Temporal.PlainDate according to a format string
+ * Supports Flatpickr-compatible format tokens:
+ * - Y: 4-digit year (e.g., 2026)
+ * - y: 2-digit year (e.g., 26)
+ * - m: 2-digit month with leading zero (01-12)
+ * - n: month without leading zero (1-12)
+ * - d: 2-digit day with leading zero (01-31)
+ * - j: day without leading zero (1-31)
+ *
+ * @param {Temporal.PlainDate} date - Date to format
+ * @param {string} format - Format string (e.g., 'd/m/Y', 'm/d/Y', 'Y-m-d')
+ * @returns Formatted date string
+ */
+declare function formatPlainDate(date: Temporal.PlainDate, format: string): string;
+/**
+ * Get today's date as Temporal.PlainDate
+ *
+ * @returns Today's date
+ */
+declare function getToday(): Temporal.PlainDate;
+/**
+ * Add days to a date
+ *
+ * @param {Temporal.PlainDate} date - Starting date
+ * @param {number} days - Number of days to add (can be negative)
+ * @returns New date
+ */
+declare function addDays(date: Temporal.PlainDate, days: number): Temporal.PlainDate;
+/**
+ * Add months to a date
+ *
+ * @param {Temporal.PlainDate} date - Starting date
+ * @param {number} months - Number of months to add (can be negative)
+ * @returns New date
+ */
+declare function addMonths(date: Temporal.PlainDate, months: number): Temporal.PlainDate;
+/**
+ * Get the number of days between two dates
+ *
+ * @param {Temporal.PlainDate} date1 - First date
+ * @param {Temporal.PlainDate} date2 - Second date
+ * @returns Number of days (positive if date2 is after date1)
+ */
+declare function daysBetween(date1: Temporal.PlainDate, date2: Temporal.PlainDate): number;
+/**
+ * Check if two dates are equal
+ *
+ * @param {Temporal.PlainDate} date1 - First date
+ * @param {Temporal.PlainDate} date2 - Second date
+ * @returns True if dates are equal
+ */
+declare function areDatesEqual(date1: Temporal.PlainDate | null, date2: Temporal.PlainDate | null): boolean;
+/**
+ * Get the start of the month for a given date
+ *
+ * @param {Temporal.PlainDate} date - Input date
+ * @returns First day of the month
+ */
+declare function getMonthStart(date: Temporal.PlainDate): Temporal.PlainDate;
+/**
+ * Get the end of the month for a given date
+ *
+ * @param {Temporal.PlainDate} date - Input date
+ * @returns Last day of the month
+ */
+declare function getMonthEnd(date: Temporal.PlainDate): Temporal.PlainDate;
+/**
+ * Check if a date is today
+ *
+ * @param {Temporal.PlainDate} date - Date to check
+ * @returns True if date is today
+ */
+declare function isToday(date: Temporal.PlainDate): boolean;
+/**
+ * Check if a date is in the past
+ *
+ * @param {Temporal.PlainDate} date - Date to check
+ * @returns True if date is before today
+ */
+declare function isPast(date: Temporal.PlainDate): boolean;
+/**
+ * Check if a date is in the future
+ *
+ * @param {Temporal.PlainDate} date - Date to check
+ * @returns True if date is after today
+ */
+declare function isFuture(date: Temporal.PlainDate): boolean;
+/**
+ * Parse a date string with a specific format
+ * Supports common format tokens: Y, m, d
+ *
+ * @param {string} dateString - Date string to parse
+ * @param {string} format - Format string (e.g., 'm/d/Y', 'Y-m-d')
+ * @returns Temporal.PlainDate or null if invalid
+ */
+declare function parseDateString(dateString: string, format: string): Temporal.PlainDate | null;
+/**
+ * Polyfill check for Temporal API
+ *
+ * @returns True if Temporal API is available
+ */
+declare function isTemporalAvailable(): boolean;
+/**
+ * Get a fallback date handler if Temporal is not available
+ * This provides a migration path for browsers without Temporal support
+ */
+declare function getDateHandler(): {
+  type: "temporal";
+  toISOString: typeof plainDateToISOString;
+  fromISOString: typeof parseISOToPlainDate;
+  compare: typeof comparePlainDates;
+  format: typeof formatPlainDate;
+  isInRange: typeof isDateInRange;
+} | {
+  type: "date";
+  /**
+   *
+   * @param {Temporal.PlainDate} date - The date to convert
+   */
+  toISOString: (date: Date) => string;
+  /**
+   *
+   * @param {string} str - The ISO string to parse
+   */
+  fromISOString: (str: string) => Date | null;
+  /**
+   *
+   * @param {Temporal.PlainDate} d1 - First date
+   * @param {Temporal.PlainDate} d2 - Second date
+   */
+  compare: (d1: Date, d2: Date) => number;
+  /**
+   *
+   * @param {Temporal.PlainDate} date - The date to format
+   * @param {string} format - The format string
+   */
+  format: (date: Date, format: string) => string;
+  /**
+   *
+   * @param {Temporal.PlainDate} date - The date to check
+   * @param {Temporal.PlainDate | null} min - Minimum date
+   * @param {Temporal.PlainDate | null} max - Maximum date
+   */
+  isInRange: (date: Date, min: Date | null, max: Date | null) => boolean;
+};
+//#endregion
+export { type CalendarDay, type ClickOutsideConfig, ClickOutsideHandler, type DatePickerContext, DatePickerEvent, type DatePickerEvent$1 as DatePickerEventType, type DatePickerMode, DatePickerState, DatePickerStateMachine, type DateSelectPayload, type FocusRestoreTarget, type InputFocusPayload, type InputType, type KeyboardEventInfo, type KeyboardEventResult, type KeyboardPayload, type SideEffect, type StateAction, type StateConfig, type StateGuard, type StateTransition, type TransitionListener, type TransitionMap, type ValidationErrorPayload, type ValueChangePayload, actions, addDays, addMonths, areDatesEqual, checkGuard, comparePlainDates, dateToPlainDate, daysBetween, effects, executeAction, executeEffect, formatPlainDate, generateCalendarGrid, getAction, getDateHandler, getEffect, getFullDateLabel, getGuard, getMonthEnd, getMonthStart, getMonthYearLabel, getToday, getWeekdayLabels, guards, isDateInRange, isFuture, isPast, isSingleMode, isTemporalAvailable, isToday, mapKeyboardToStateMachineEvent, parseDateString, parseDateToPlainDate, parseISOToPlainDate, plainDateToDate, plainDateToISOString };