Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
17.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file TouchTimeField.tsx
 * @input Uses React, Field, BottomSheet, the wheels (TimeWheels under a finger,
 *   Wheel with a mouse), DateInput touch geometry tokens and time utilities
 * @output Exports TouchTimeField — the bottom-sheet surface behind TimeInput
 * @position Internal component; consumed by TimeInput.tsx for `presentation`
 *   sheet surfaces
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/TimeInput/TimeInput.tsx
 * - /packages/core/src/TimeInput/TimeInput.doc.mjs
 * - /packages/core/src/DateTimeInput/TouchDateTimeField.tsx (wheel behavior)
 */

import {
  useCallback,
  useId,
  useMemo,
  useOptimistic,
  useRef,
  useState,
  useTransition,
  type KeyboardEvent,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {BottomSheet} from '../BottomSheet';
import {Button} from '../Button';
import {
  Field,
  InputClearButton,
  inputWrapperStyles,
  inputStatusBorderStyles,
  inputStatusHoverShadowStyles,
  inputStatusFocusWithinStyles,
} from '../Field';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {useFieldInputStyling} from '../Field/fieldParts';
import {joinAriaIDs} from '../utils/inputAria';
import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {Icon} from '../Icon';
import {useLocale} from '../i18n';
import {formatLocaleTime} from '../utils/timeFormat';
import {sizeVars, spacingVars} from '../theme/tokens.stylex';
import {useSize} from '../SizeContext/SizeContext';
import {Spinner} from '../Spinner';
import {useTooltip} from '../Tooltip';
import {Wheel, type WheelOption} from '../DateInput/Wheel';
import {useTouchPresentation} from '../utils/touchPresentation';
import {dateInputTouchGeometry} from '../DateInput/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {themeProps} from '../utils/themeProps';
import {
  clampTime,
  formatISOTime,
  getInputARIA,
  isTimeInRange,
  mergeProps,
  parseISOTime,
  type ISOTimeString,
} from '../utils';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import type {TimeInputProps} from './TimeInput';
import {TimeWheels} from '../DateInput/datePickerTouch';
import {
  hour12From24,
  hour24From12,
  hourRowsInHalf,
  meridiemRows,
  minuteRows,
  secondRows,
  wheelBounds,
} from './timeWheelRules';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/TimeInput/TouchTimeField.generated';

registerEnglishFallback(english);

const sizeStyles = stylex.create({
  sm: {height: sizeVars['--size-element-sm'], minWidth: 120},
  md: {height: sizeVars['--size-element-md'], minWidth: 120},
  lg: {height: sizeVars['--size-element-lg'], minWidth: 120},
});

const styles = stylex.create({
  iconButton: {
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    padding: 0,
    margin: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: 'transparent',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    flexShrink: 0,
  },
  input: {
    display: 'block',
    flex: 1,
    minWidth: 0,
    borderWidth: 0,
    borderStyle: 'none',
    padding: 0,
    backgroundColor: 'transparent',
    outline: 'none',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
  },
  // Sheet chrome mirrors TouchDateTimeField: `touchSheetBody` insets (the
  // BottomSheet handle floats over the panel, so the wrapper supplies the top
  // clearance and the side/bottom insets) flattened with `touchPanel`'s column
  // layout, which is the wheels' direct parent there and spaces the footer.
  sheetBody: {
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    inlineSize: '100%',
    minInlineSize: 0,
    gap: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-4'],
    // The sheet keeps the band under its grab bar.
    paddingBlockStart: 0,
    paddingBlockEnd: spacingVars['--spacing-4'],
  },
  wheels: {
    display: 'flex',
    inlineSize: '100%',
    minInlineSize: 0,
    blockSize: dateInputTouchGeometry.paneBlockSize,
    gap: spacingVars['--spacing-2'],
  },
  footer: {
    display: 'flex',
    marginBlockStart: 'auto',
    paddingBlockStart: spacingVars['--spacing-1'],
  },
});

/**
 * The Astryx bottom-sheet time surface: a read-only closed field that opens
 * hour/minute(/second/meridiem) wheels in a BottomSheet. Wheels commit live,
 * clamped to `min`/`max`; the footer Save button only closes the sheet.
 */
export function TouchTimeField({
  label,
  isLabelHidden = false,
  description,
  isOptional = false,
  isRequired = false,
  isDisabled = false,
  disabledMessage,
  value,
  onChange,
  changeAction,
  isLoading = false,
  min,
  max,
  hasSeconds = false,
  hasClear = false,
  hourFormat = '12h',
  // Typed-field only: the wheels step by their own options and the sheet
  // opens on tap, so neither reaches this surface.
  increment: _increment,
  hasAutoFocus: _hasAutoFocus,
  placeholder: placeholderFromProps,
  size: sizeProp,
  status,
  statusVariant = 'attached',
  labelTooltip,
  width,
  containerXstyle,
  containerClassName,
  containerStyle,
  controlXstyle,
  controlClassName,
  controlStyle,
  ref,
  ...restProps
}: TimeInputProps) {
  const {rest, container} = useFieldInputStyling('TimeInput', restProps, {
    containerXstyle,
    containerClassName,
    containerStyle,
  });
  const {
    id: idProp,
    'aria-describedby': ariaDescribedByProp,
    'aria-labelledby': ariaLabelledByProp,
    onClick: onClickProp,
    ...controlProps
  } = rest;
  const t = useComponentTranslator();
  const locale = useLocale();
  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
  const placeholder =
    placeholderFromProps ?? t('@astryx.timeInput.placeholder');
  const size = useSize(sizeProp, 'md');
  const generatedID = useId();
  const id = idProp ?? generatedID;
  const fieldLabelID = useId();
  const inputLabelID = useId();
  const descriptionID = useId();
  const statusMessageID = useId();
  const inputRef = useRef<HTMLInputElement | null>(null);
  const mergedInputRef = useMergedRefs(ref, inputRef);
  const inputGroup = useInputGroup();
  const [isSheetOpen, setIsSheetOpen] = useState(false);
  const {isTouch} = useTouchPresentation();
  const [, startTransition] = useTransition();
  const [optimisticValue, setOptimisticValue] = useOptimistic(value);
  const isBusy = isLoading || optimisticValue !== value;
  const sheetBodyRef = useRef<HTMLDivElement | null>(null);
  // The busy Spinner is decorative; this control announces its busy start
  // (spec:AST-086 FR8). A change made in the open modal sheet starts it while
  // the sheet is open, so it is announced from inside the sheet.
  useBusyAnnouncement(
    isBusy,
    t('@astryx.spinner.loading'),
    isSheetOpen ? sheetBodyRef : inputRef,
  );
  const isEffectivelyDisabled = isDisabled || isLoading;

  const showsDisabledMessage = isDisabled && !!disabledMessage;
  const disabledMessageTooltip = useTooltip({
    placement: 'above',
    focusTrigger: 'always',
    isEnabled: showsDisabledMessage,
  });
  const {statusIcon, describedBy: statusTooltipDescribedBy} =
    useInputStatusIcon({status, statusVariant, isInGroup: !!inputGroup});
  const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
    inputLabelID,
    [
      description ? descriptionID : null,
      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
      statusTooltipDescribedBy,
      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
      ariaDescribedByProp,
    ],
    inputGroup,
  );

  const fireChange = useCallback(
    (newValue: ISOTimeString | undefined) => {
      if (isEffectivelyDisabled) {
        return;
      }
      onChange?.(newValue);
      if (changeAction) {
        startTransition(async () => {
          setOptimisticValue(newValue);
          await changeAction(newValue);
        });
      }
    },
    [changeAction, isEffectivelyDisabled, onChange, setOptimisticValue],
  );

  const displayValue = optimisticValue
    ? formatLocaleTime(optimisticValue, locale, hourFormat, hasSeconds)
    : '';

  const fallbackTime = useMemo(() => {
    const now = new Date();
    return formatISOTime(
      {
        hour: now.getHours(),
        minute: now.getMinutes(),
        second: now.getSeconds(),
      },
      hasSeconds,
    );
  }, [hasSeconds]);
  const parsedWheelTime = useMemo(
    () =>
      parseISOTime(optimisticValue ?? fallbackTime) ?? {
        hour: 0,
        minute: 0,
        second: 0,
      },
    [fallbackTime, optimisticValue],
  );

  const composeWheelTime = useCallback(
    (patch: {
      hour24?: number;
      hour12?: number;
      minute?: number;
      second?: number;
      meridiem?: number;
    }): ISOTimeString => {
      const meridiem = patch.meridiem ?? (parsedWheelTime.hour < 12 ? 0 : 1);
      let hour = parsedWheelTime.hour;
      if (patch.hour24 !== undefined) {
        hour = patch.hour24;
      } else if (patch.hour12 !== undefined) {
        hour = hour24From12(patch.hour12, meridiem);
      } else if (patch.meridiem !== undefined) {
        hour = hour24From12(hour12From24(hour), patch.meridiem);
      }
      return formatISOTime(
        {
          hour,
          minute: patch.minute ?? parsedWheelTime.minute,
          second: hasSeconds ? (patch.second ?? parsedWheelTime.second) : 0,
        },
        hasSeconds,
      );
    },
    [hasSeconds, parsedWheelTime],
  );

  const commitWheelTime = useCallback(
    (rawTime: ISOTimeString) => {
      const next = clampTime(rawTime, min, max, hasSeconds);
      if (next !== optimisticValue && isTimeInRange(next, min, max)) {
        fireChange(next);
      }
    },
    [fireChange, hasSeconds, max, min, optimisticValue],
  );

  const bounds = useMemo(() => wheelBounds(min, max), [min, max]);
  const hourOptions: WheelOption[] = useMemo(
    () => hourRowsInHalf(parsedWheelTime.hour, hourFormat, bounds),
    [bounds, hourFormat, parsedWheelTime.hour],
  );
  const minuteOptions: WheelOption[] = useMemo(
    () => minuteRows(parsedWheelTime.hour, hasSeconds, bounds),
    [bounds, hasSeconds, parsedWheelTime.hour],
  );
  const secondOptions: WheelOption[] = useMemo(
    () => secondRows(parsedWheelTime.hour, parsedWheelTime.minute, bounds),
    [bounds, parsedWheelTime.hour, parsedWheelTime.minute],
  );
  const meridiemOptions: WheelOption[] = useMemo(
    () =>
      meridiemRows(
        {
          am: t('@astryx.dateTimeInput.meridiemAM'),
          pm: t('@astryx.dateTimeInput.meridiemPM'),
        },
        bounds,
      ),
    [bounds, t],
  );

  const openSheet = useCallback(() => {
    if (!isEffectivelyDisabled) {
      setIsSheetOpen(true);
    }
  }, [isEffectivelyDisabled]);

  const inputWrapper = (
    <div
      ref={el => {
        disabledMessageTooltip.ref(el);
      }}
      {...(inputGroup ? inputGroupItemProps : undefined)}
      {...mergeProps(
        themeProps('time-input', {
          size,
          status: status?.type ?? null,
          disabled: isDisabled ? 'disabled' : null,
        }),
        stylex.props(
          inputWrapperStyles.base,
          inputWrapperStyles.textField,
          sizeStyles[size],
          isDisabled && inputWrapperStyles.disabled,
          isDisabled && inputDisabledFocusStyles.withinRing,
          status && inputStatusBorderStyles[status.type],
          status && !isDisabled && inputStatusHoverShadowStyles[status.type],
          status && inputStatusFocusWithinStyles[status.type],
          inputGroup && groupStyles.inGroup,
          controlXstyle,
        ),
        controlClassName,
        controlStyle,
      )}>
      <button
        type="button"
        onClick={openSheet}
        aria-disabled={isEffectivelyDisabled || undefined}
        aria-label={t('@astryx.timeInput.openPicker', {label})}
        tabIndex={-1}
        {...stylex.props(focusOutlineStyles.focusVisible, styles.iconButton)}>
        <Icon icon="clock" size="sm" color="secondary" />
      </button>
      <input
        {...controlProps}
        ref={mergedInputRef}
        id={id}
        type="text"
        role="combobox"
        value={displayValue}
        readOnly
        inputMode="none"
        onChange={() => {}}
        onClick={
          isEffectivelyDisabled
            ? undefined
            : chainEventHandlers(openSheet, onClickProp)
        }
        // Enter would submit a surrounding form while disabled (FR2).
        onKeyDown={chainEventHandlers((e: KeyboardEvent<HTMLInputElement>) => {
          if (isEffectivelyDisabled && e.key === 'Enter') {
            e.preventDefault();
          }
        }, controlProps.onKeyDown)}
        placeholder={placeholder}
        aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
        aria-describedby={ariaDescribedBy}
        aria-required={isEffectivelyRequired ? 'true' : undefined}
        aria-invalid={status?.type === 'error' ? 'true' : undefined}
        aria-busy={isBusy || undefined}
        aria-expanded={isSheetOpen}
        aria-haspopup="dialog"
        aria-autocomplete="none"
        autoComplete="off"
        aria-labelledby={
          ariaLabelledByProp != null
            ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
            : ariaLabelledBy
        }
        {...stylex.props(styles.input)}
      />
      {isBusy && <Spinner size="sm" aria-hidden="true" />}
      {hasClear && optimisticValue && !isEffectivelyDisabled && (
        <InputClearButton
          label={t('@astryx.timeInput.clearLabel', {label})}
          onClick={() => fireChange(undefined)}
        />
      )}
      {statusIcon}
      <BottomSheet
        isOpen={isSheetOpen}
        onOpenChange={setIsSheetOpen}
        label={label}
        height="hug"
        // sheetBody owns the inset; the sheet keeps the band under its grab
        // bar.
        padding={0}>
        <div ref={sheetBodyRef} {...stylex.props(styles.sheetBody)}>
          <div {...stylex.props(styles.wheels)}>
            {isTouch ? (
              <TimeWheels
                time={parsedWheelTime}
                hourFormat={hourFormat}
                hasSeconds={hasSeconds}
                min={min}
                max={max}
                isActive={isSheetOpen}
                onCommit={time =>
                  commitWheelTime(formatISOTime(time, hasSeconds))
                }
              />
            ) : (
              <>
                <Wheel
                  label={t('@astryx.dateTimeInput.hourWheel')}
                  options={hourOptions}
                  value={
                    hourFormat === '24h'
                      ? parsedWheelTime.hour
                      : hour12From24(parsedWheelTime.hour)
                  }
                  isActive={isSheetOpen}
                  onChange={hour =>
                    commitWheelTime(
                      hourFormat === '24h'
                        ? composeWheelTime({hour24: hour})
                        : composeWheelTime({hour12: hour}),
                    )
                  }
                />
                <Wheel
                  label={t('@astryx.dateTimeInput.minuteWheel')}
                  options={minuteOptions}
                  value={parsedWheelTime.minute}
                  isActive={isSheetOpen}
                  onChange={minute =>
                    commitWheelTime(composeWheelTime({minute}))
                  }
                />
                {hasSeconds && (
                  <Wheel
                    label={t('@astryx.dateTimeInput.secondWheel')}
                    options={secondOptions}
                    value={parsedWheelTime.second}
                    isActive={isSheetOpen}
                    onChange={second =>
                      commitWheelTime(composeWheelTime({second}))
                    }
                  />
                )}
                {hourFormat === '12h' && (
                  <Wheel
                    label={t('@astryx.dateTimeInput.meridiemWheel')}
                    options={meridiemOptions}
                    value={parsedWheelTime.hour < 12 ? 0 : 1}
                    isActive={isSheetOpen}
                    onChange={meridiem =>
                      commitWheelTime(composeWheelTime({meridiem}))
                    }
                  />
                )}
              </>
            )}
          </div>
          <div {...stylex.props(styles.footer)}>
            <Button
              variant="primary"
              size="md"
              width="100%"
              label={t('@astryx.dateInput.savePicking')}
              onClick={() => setIsSheetOpen(false)}
            />
          </div>
        </div>
      </BottomSheet>
      {showsDisabledMessage &&
        disabledMessageTooltip.renderTooltip(disabledMessage)}
    </div>
  );

  if (inputGroup) {
    return inputWrapper;
  }
  return (
    <Field
      {...container}
      label={label}
      isLabelHidden={isLabelHidden}
      description={description}
      inputID={id}
      labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
      descriptionID={description ? descriptionID : undefined}
      isOptional={isOptional}
      isRequired={isRequired}
      isDisabled={isDisabled}
      status={
        status
          ? {
              type: status.type,
              message: status.message,
              messageID: status.message ? statusMessageID : undefined,
            }
          : undefined
      }
      statusVariant={statusVariant}
      labelTooltip={labelTooltip}
      width={width}>
      {inputWrapper}
    </Field>
  );
}

TouchTimeField.displayName = 'TouchTimeField';