@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/DateInput/DateInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file DateInput.tsx
- * @input Uses React, useId, useState, useCallback, useRef, Field, Icon, Calendar, usePopover, InputGroupContext
+ * @input Uses React, useId, useCallback, useRef, useTypedDateField, Field, Icon, Calendar, usePopover, InputGroupContext
  * @output Exports DateInput component, DateInputProps
  * @position Core implementation; consumed by index.ts, tested by DateInput.test.tsx
  *
@@ -19,7 +19,6 @@
 import {
   use,
   useId,
-  useState,
   useCallback,
   useRef,
   useOptimistic,
@@ -66,24 +65,23 @@ import {usePopover} from '../Popover';
 import {
   isFocusInsideOwnedLayer,
   isPressInsideOwnedLayer,
+  noteOutsideDismissal,
   useOutsidePress,
 } from '../Layer/outsidePress';
 import {NativeDateField} from './NativeDateField';
 import {TouchDateField} from './TouchDateField';
 import {useTooltip} from '../Tooltip';
-import {getInputARIA, isImeKeyEvent, parseDateInput} from '../utils';
+import {getInputARIA, isImeKeyEvent} from '../utils';
 import {chainEventHandlers} from '../utils/chainEventHandlers';
-import {
-  plainDateFromISO,
-  plainDateToISO,
-  formatSharedDate,
-} from '../utils/plainDate';
+import type {CalendarSystem} from '../utils/calendarSystem';
+import {isRenderable} from '../utils/isRenderable';
+import {useTypedDateField} from './useTypedDate';
 import type {TimestampFormat} from '../Timestamp';
 import {
-  effectivePickerPresentation,
   resolvePickerPresentation,
   type PickerPresentation,
 } from '../utils/inputPresentation';
+import {useCalendarPresentation} from './useCalendarPresentation';
 import {useDevWarning} from '../hooks/useDevWarning';
 
 const styles = stylex.create({
@@ -204,7 +202,6 @@ import {
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
-import {useLocale} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
@@ -318,7 +315,8 @@ export interface DateInputProps extends Omit<
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
 
   /**
-   * Placeholder text shown when no date is selected.
+   * Placeholder text shown when no date is selected. A caller placeholder
+   * replaces the calendar format hint.
    * @default "Select a date"
    */
   placeholder?: string;
@@ -391,9 +389,10 @@ export interface DateInputProps extends Omit<
    * - `(value: ISODateString) => string`: fully custom display string
    *
    * Formatting applies only to the committed value — never to text the user is
-   * actively typing. A custom function's output that `parseDateInput` cannot
-   * read back can't be re-committed after an edit; external `value` changes
-   * always recompute the display from the ISO value.
+   * actively typing. Named formats write the date in the field's `calendar`;
+   * `'system_date'` stays the Gregorian ISO date. A custom function's output
+   * that the field cannot read back can't be re-committed after an edit;
+   * external `value` changes always recompute the display from the ISO value.
    *
    * @default 'date_long'
    * @example
@@ -409,6 +408,29 @@ export interface DateInputProps extends Omit<
    */
   format?: DateInputFormat | ((value: ISODateString) => string);
 
+  /**
+   * The calendar the field shows dates in, such as `'persian'`, `'hebrew'`, or
+   * `'buddhist'`: the text field, its calendar popover, and the bottom sheet's
+   * months and wheels. `value`, `onChange`, `min`, and `max` stay Gregorian
+   * ISO dates in every calendar. People type a date the way the locale writes
+   * it in this calendar, and the committed text uses it.
+   * Years are years of this calendar, so a Buddhist field reads `2026` as
+   * Buddhist year 2026; set `min` and `max` to catch a year typed in the
+   * wrong calendar. Calendars other than `gregory`, `iso8601`, `buddhist`,
+   * `roc`, and `japanese` need `Temporal`, native or a polyfill the
+   * application loads; without it the field uses the Gregorian calendar.
+   * The native date control is Gregorian, so with a calendar other than
+   * `gregory` or `iso8601` every presentation that would show it uses the
+   * popover on a fine pointer and the bottom sheet on a coarse pointer.
+   *
+   * @default the InternationalizationProvider's calendar, else `'gregory'`
+   * @example
+   * ```
+   * <DateInput label="Start date" calendar="persian" value={date} onChange={setDate} />
+   * ```
+   */
+  calendar?: CalendarSystem;
+
   /**
    * When date picking is handed to the browser/OS instead of Astryx's own
    * surfaces: the field becomes an `<input type="date">` and the platform
@@ -434,6 +456,9 @@ export interface DateInputProps extends Omit<
    * picker. `dateConstraints` is enforced the same way, on commit, and is
    * reason enough to prefer `'never'` on a field that uses it.
    *
+   * In a calendar other than `gregory` or `iso8601`, `'touch'` and `'always'`
+   * use the calendar popover on a mouse and the touch picker on a finger.
+   *
    * @default 'touch'
    * @deprecated Use `presentation` (`spec:AST-043` FR3):
    * `'touch'` → `'adaptive-native'`, `'always'` → `'native'`,
@@ -449,12 +474,15 @@ export interface DateInputProps extends Omit<
    * - `'popover'`: Astryx's typed field + calendar popover on every pointer
    * - `'bottom-sheet'`: Astryx's bottom-sheet calendar on every pointer
    * - `'native'`: the browser/OS picker on every pointer, with no Astryx
-   *   fallback (FR2)
+   *   fallback (FR2), except in a calendar other than `gregory` or
+   *   `iso8601`, where it is `'adaptive-bottom-sheet'` and warns in
+   *   development
    * - `'adaptive-bottom-sheet'`: popover on a fine pointer, bottom sheet on
    *   a coarse pointer
    * - `'adaptive-native'` (default): popover on a fine pointer, browser/OS
    *   picker on a coarse pointer, keeping the released Astryx fallbacks
-   *   where a native control cannot express the value (FR2)
+   *   where a native control cannot express the value (FR2), and the bottom
+   *   sheet in a calendar other than `gregory` or `iso8601`
    *
    * @default 'adaptive-native'
    */
@@ -523,6 +551,7 @@ function PointerDateField({
   numberOfMonths = 1,
   weekStartsOn,
   format = 'date_long',
+  calendar,
   width,
   containerXstyle,
   containerClassName,
@@ -544,11 +573,11 @@ function PointerDateField({
     'aria-labelledby': ariaLabelledByProp,
     onBlur: onBlurProp,
     onClick: onClickProp,
+    onFocus: onFocusProp,
     onKeyDown: onKeyDownProp,
     ...controlProps
   } = rest;
   const t = useComponentTranslator();
-  const locale = useLocale();
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.dateInput.placeholder');
@@ -559,9 +588,9 @@ function PointerDateField({
   const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  const calendarDescriptionID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const calendarRef = useRef<CalendarHandle | null>(null);
-  const lastFiredValueRef = useRef<ISODateString | undefined>(undefined);
   const inputGroup = useInputGroup();
 
   const [, startTransition] = useTransition();
@@ -591,9 +620,70 @@ function PointerDateField({
   // Constraint checking for text input validation (reuses calendar logic)
   const {isDateDisabled} = useCalendarConstraints({min, max, dateConstraints});
 
+  const fireChange = useCallback(
+    (newValue: ISODateString | undefined) => {
+      if (isEffectivelyDisabled) {
+        return;
+      }
+      onChange?.(newValue);
+      if (changeAction) {
+        startTransition(async () => {
+          setOptimisticValue(newValue);
+          await changeAction(newValue);
+        });
+      }
+    },
+    [
+      isEffectivelyDisabled,
+      onChange,
+      changeAction,
+      startTransition,
+      setOptimisticValue,
+    ],
+  );
+
+  const clearTypedDate = useCallback(() => {
+    if (value !== undefined) {
+      fireChange(undefined);
+    }
+  }, [value, fireChange]);
+  const navigateToTypedDate = useCallback((date: ISODateString) => {
+    calendarRef.current?.navigateTo(date);
+  }, []);
+  const {
+    typedDate,
+    displayValue,
+    formatHint,
+    isPending,
+    isInvalid,
+    fieldStatus,
+    alertMessage,
+    handleChange: handleTypedChange,
+    commit: commitPendingInput,
+    handleFocus,
+    handleBlur,
+    reset: resetTypedInput,
+  } = useTypedDateField({
+    source: 'DateInput',
+    calendar,
+    format,
+    min,
+    max,
+    isDateDisabled,
+    value,
+    shownValue: optimisticValue,
+    onChange: fireChange,
+    onClear: clearTypedDate,
+    onTypedDate: navigateToTypedDate,
+    isDisabled: isEffectivelyDisabled,
+    status,
+    isStatusAnnounced: !inputGroup,
+    hasPlaceholder: placeholderFromProps != null,
+  });
+
   const {statusIcon, describedBy: statusTooltipDescribedBy} =
     useInputStatusIcon({
-      status,
+      status: fieldStatus,
       statusVariant,
       isInGroup: !!inputGroup,
     });
@@ -602,7 +692,10 @@ function PointerDateField({
     inputLabelID,
     [
       description ? descriptionID : null,
-      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+      typedDate.calendarDescription != null ? calendarDescriptionID : null,
+      statusVariant !== 'tooltip' && fieldStatus?.message
+        ? statusMessageID
+        : null,
       // The tooltip variant renders no message box; describe the input by the
       // tooltip's content instead so the status is still announced.
       statusTooltipDescribedBy,
@@ -612,50 +705,6 @@ function PointerDateField({
     inputGroup,
   );
 
-  // Pending input while user is typing (null = show formatted value)
-  const [pendingInput, setPendingInput] = useState<string | null>(null);
-
-  // Clear pending input when value changes externally (computed during render
-  // via prev-value ref instead of useEffect to avoid an extra render cycle)
-  const prevValueRef = useRef(value);
-  if (value !== prevValueRef.current) {
-    prevValueRef.current = value;
-    if (value !== lastFiredValueRef.current) {
-      lastFiredValueRef.current = undefined;
-      if (pendingInput !== null) {
-        setPendingInput(null);
-      }
-    }
-  }
-
-  // Format a committed ISO value for display. The default `date_long` renders
-  // the long-month shape (byte-identical to the historical hardcoded
-  // DATE_FORMAT_LONG rendering, so still non-breaking); a function is called
-  // with the ISO value; every other named member reuses Timestamp's shared
-  // date mapping. Applies ONLY to the committed value, never to in-progress
-  // typed input.
-  const formatCommittedValue = useCallback(
-    (iso: ISODateString): string =>
-      typeof format === 'function'
-        ? format(iso)
-        : formatSharedDate(plainDateFromISO(iso), format, locale),
-    [format, locale],
-  );
-
-  // Display value: pending input if typing, otherwise formatted value
-  const displayValue =
-    pendingInput !== null
-      ? pendingInput
-      : optimisticValue && /^\d{4}-\d{2}-\d{2}$/.test(optimisticValue)
-        ? formatCommittedValue(optimisticValue)
-        : '';
-
-  // Check if current input is valid (for styling purposes)
-  const isInputValid =
-    pendingInput === null || !pendingInput.trim()
-      ? true
-      : parseDateInput(pendingInput, locale) !== null;
-
   const fieldElementRef = useRef<HTMLDivElement | null>(null);
   // Set just before a close that focus already left the field for, so onHide
   // does not pull focus back to the input.
@@ -717,29 +766,6 @@ function PointerDateField({
     }
   }, [isEffectivelyDisabled, popover]);
 
-  // Unified change handler that fires both onChange and changeAction
-  const fireChange = useCallback(
-    (newValue: ISODateString | undefined) => {
-      if (isEffectivelyDisabled) {
-        return;
-      }
-      onChange?.(newValue);
-      if (changeAction) {
-        startTransition(async () => {
-          setOptimisticValue(newValue);
-          await changeAction(newValue);
-        });
-      }
-    },
-    [
-      isEffectivelyDisabled,
-      onChange,
-      changeAction,
-      startTransition,
-      setOptimisticValue,
-    ],
-  );
-
   // Handle clear button click
   const handleClear = useCallback(
     (e?: React.MouseEvent<HTMLButtonElement>) => {
@@ -766,81 +792,19 @@ function PointerDateField({
         return;
       }
       fireChange(selectedDate);
-      setPendingInput(null);
+      resetTypedInput();
       popover.hide();
     },
-    [isDisabled, fireChange, popover],
+    [isDisabled, fireChange, resetTypedInput, popover],
   );
 
-  // Handle input text change - update immediately if valid and allowed
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
-      // The input is never natively disabled (spec:AST-085 FR1), so guard
-      // value mutation explicitly (readOnly also blocks typing).
-      if (isEffectivelyDisabled) {
-        return;
-      }
-      const newValue = e.target.value;
-      setPendingInput(newValue);
-
-      // If the input is valid and passes constraints, update immediately
-      const parsed = parseDateInput(newValue, locale);
-      if (
-        parsed &&
-        plainDateToISO(parsed) !== value &&
-        !isDateDisabled(parsed)
-      ) {
-        const parsedISO = plainDateToISO(parsed);
-        lastFiredValueRef.current = parsedISO;
-        fireChange(parsedISO);
-        // Navigate calendar to show the parsed date's month
-        calendarRef.current?.navigateTo(parsedISO);
-      }
+      handleTypedChange(e.target.value);
     },
-    [value, fireChange, isDateDisabled, isEffectivelyDisabled, locale],
+    [handleTypedChange],
   );
 
-  // Commit pending input (shared by blur and Enter key)
-  const commitPendingInput = useCallback(() => {
-    if (pendingInput === null) {
-      return;
-    }
-    // Disabled or busy: keep the value, drop the draft (spec:AST-085 FR2).
-    if (isEffectivelyDisabled) {
-      setPendingInput(null);
-      return;
-    }
-
-    if (!pendingInput.trim()) {
-      if (value !== undefined) {
-        fireChange(undefined);
-      }
-      setPendingInput(null);
-      return;
-    }
-
-    const parsed = parseDateInput(pendingInput, locale);
-    if (parsed && !isDateDisabled(parsed)) {
-      const parsedISO = plainDateToISO(parsed);
-      if (parsedISO !== value) {
-        fireChange(parsedISO);
-      }
-    }
-    setPendingInput(null);
-  }, [
-    pendingInput,
-    isEffectivelyDisabled,
-    value,
-    fireChange,
-    isDateDisabled,
-    locale,
-  ]);
-
-  // Handle blur - validate, check constraints, and clear pending input.
-  const handleBlur = useCallback(() => {
-    commitPendingInput();
-  }, [commitPendingInput]);
-
   // A manual popover has no auto-popover exclusivity, so without this close
   // the next field's calendar would open beside this one. Focus going nowhere
   // (a window switch) leaves it open.
@@ -855,6 +819,7 @@ function PointerDateField({
         return;
       }
       isFocusMovingAwayRef.current = true;
+      noteOutsideDismissal(e.currentTarget.ownerDocument);
       popover.hide();
     },
     [popover],
@@ -884,10 +849,7 @@ function PointerDateField({
         if (!isEffectivelyDisabled) {
           popover.show({skipAutoFocus: true});
         }
-      } else if (
-        e.key === 'Enter' &&
-        (pendingInput !== null || isEffectivelyDisabled)
-      ) {
+      } else if (e.key === 'Enter' && (isPending || isEffectivelyDisabled)) {
         // Typed text holds Enter back, or a form would submit the value from
         // before the commit. A disabled or busy field must not submit its
         // form either. Otherwise Enter keeps its default, as in any text field.
@@ -895,7 +857,7 @@ function PointerDateField({
         commitPendingInput();
       }
     },
-    [popover, commitPendingInput, isEffectivelyDisabled, pendingInput],
+    [popover, commitPendingInput, isEffectivelyDisabled, isPending],
   );
 
   const inputWrapper = (
@@ -913,7 +875,7 @@ function PointerDateField({
       {...mergeProps(
         themeProps('date-input', {
           size,
-          status: status?.type ?? null,
+          status: fieldStatus?.type ?? null,
           disabled: isDisabled ? 'disabled' : null,
         }),
         stylex.props(
@@ -924,11 +886,11 @@ function PointerDateField({
           // FR6, family:buttons FR4).
           isDisabled && inputWrapperStyles.disabled,
           isEffectivelyDisabled && inputDisabledFocusStyles.inputFocusRing,
-          status && inputStatusBorderStyles[status.type],
-          status &&
+          fieldStatus && inputStatusBorderStyles[fieldStatus.type],
+          fieldStatus &&
             !isEffectivelyDisabled &&
-            inputStatusHoverShadowStyles[status.type],
-          status && inputStatusFocusWithinStyles[status.type],
+            inputStatusHoverShadowStyles[fieldStatus.type],
+          fieldStatus && inputStatusFocusWithinStyles[fieldStatus.type],
           inputGroup && groupStyles.inGroup,
           controlXstyle,
         ),
@@ -978,13 +940,14 @@ function PointerDateField({
         value={displayValue}
         onChange={handleInputChange}
         onBlur={chainEventHandlers(handleBlur, onBlurProp)}
+        onFocus={chainEventHandlers(handleFocus, onFocusProp)}
         onClick={
           isEffectivelyDisabled
             ? undefined
             : chainEventHandlers(handleInputClick, onClickProp)
         }
         onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
-        placeholder={placeholder}
+        placeholder={formatHint ?? placeholder}
         aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
         readOnly={isEffectivelyDisabled || undefined}
         aria-labelledby={
@@ -995,7 +958,7 @@ function PointerDateField({
         aria-describedby={ariaDescribedBy}
         aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
-          status?.type === 'error' || !isInputValid ? 'true' : undefined
+          fieldStatus?.type === 'error' || isInvalid ? 'true' : undefined
         }
         aria-busy={isBusy || undefined}
         aria-expanded={popover.isOpen}
@@ -1006,17 +969,21 @@ function PointerDateField({
         {...stylex.props(
           styles.input,
           isEffectivelyDisabled && styles.inputDisabled,
-          !isInputValid && styles.inputInvalid,
+          isInvalid && styles.inputInvalid,
         )}
       />
       {/*
-          Live region announcing invalid typed input to assistive technology.
-          The value silently reverts on blur, so without this a screen-reader
-          user would get no feedback that their entry was rejected (WCAG 3.3.1).
+          Announces a typed rejection that the field status does not announce.
+          The field status announces the rest.
         */}
       <VisuallyHidden as="div" role="alert" aria-live="assertive">
-        {!isInputValid ? t('@astryx.dateInput.invalidDate') : ''}
+        {alertMessage}
       </VisuallyHidden>
+      {isRenderable(typedDate.calendarDescription) && (
+        <VisuallyHidden id={calendarDescriptionID}>
+          {typedDate.calendarDescription}
+        </VisuallyHidden>
+      )}
       {hasClear && value !== undefined && !isEffectivelyDisabled && (
         <InputClearButton
           label={t('@astryx.dateInput.clear', {label})}
@@ -1031,6 +998,7 @@ function PointerDateField({
         !popover.isOpen ? null : (
           <Calendar
             handleRef={calendarRef}
+            calendar={typedDate.calendar}
             mode="single"
             value={optimisticValue ?? null}
             onChange={handleDateSelect}
@@ -1065,11 +1033,11 @@ function PointerDateField({
       isRequired={isRequired}
       isDisabled={isDisabled}
       status={
-        status
+        fieldStatus
           ? {
-              type: status.type,
-              message: status.message,
-              messageID: status.message ? statusMessageID : undefined,
+              type: fieldStatus.type,
+              message: fieldStatus.message,
+              messageID: fieldStatus.message ? statusMessageID : undefined,
             }
           : undefined
       }
@@ -1138,22 +1106,40 @@ export function DateInput(props: DateInputProps) {
     '`nativePicker` is deprecated; use `presentation` instead (`touch` → `adaptive-native`, `always` → `native`, `never` → `adaptive-bottom-sheet`). `presentation` wins when both are set.',
     props.nativePicker !== undefined,
   );
-  const surface = resolvePickerPresentation(
-    effectivePickerPresentation(props.presentation, props.nativePicker),
-    isTouch,
+  const {calendar, presentation} = useCalendarPresentation(
+    'DateInput',
+    props.calendar,
+    props.presentation,
+    props.nativePicker,
   );
+  const surface = resolvePickerPresentation(presentation, isTouch);
   const {
     presentation: _presentation,
     nativePicker: _nativePicker,
+    calendar: _calendar,
     ...rest
   } = props;
   switch (surface) {
     case 'native':
       return <NativeDateField {...rest} isDisabled={isDisabled} />;
     case 'sheet':
-      return <TouchDateField {...rest} isDisabled={isDisabled} />;
+      return (
+        <TouchDateField
+          // Month indexes depend on the calendar. A new calendar remounts the sheet.
+          key={calendar}
+          {...rest}
+          calendar={calendar}
+          isDisabled={isDisabled}
+        />
+      );
     case 'desktop':
-      return <PointerDateField {...rest} isDisabled={isDisabled} />;
+      return (
+        <PointerDateField
+          {...rest}
+          calendar={calendar}
+          isDisabled={isDisabled}
+        />
+      );
   }
 }