@cdx-ui/primitives 0.0.1-beta.140 → 0.0.1-beta.141

package/src/date-time-field/useDateTimeFieldSegmentState.ts

@@ -0,0 +1,672 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  formatDateSegment,
+  formatDateTimeId,
+  formatDateTimeListPeriod,
+  getDateTimeSegmentVisibility,
+  getEmptyDateSegmentText,
+  parseDateTimeId,
+  type DateSegment,
+  type DateSegmentType,
+  type DateTimeGranularity,
+  type DateTimeId,
+} from '@cdx-ui/formatters';
+import {
+  applySegmentDigit,
+  commitDayPeriodDraft,
+  commitSegmentDraft,
+  findAdjacentEditableIndex,
+  getSegmentMaxLength,
+  isSegmentDraftComplete,
+  toHour12,
+  toHour24,
+  type SegmentKeyboardOptions,
+} from '../date-field/segmentKeyboard';
+
+interface UseDateTimeFieldSegmentStateOptions {
+  granularity: DateTimeGranularity;
+  hour12: boolean;
+  locale: string;
+  segments: DateSegment[];
+  value: DateTimeId | undefined;
+  setValue: (value: DateTimeId | undefined) => void;
+  disabled: boolean;
+  readOnly: boolean;
+}
+
+/** In-progress parts. Wire `value` is only written when required parts are complete. */
+interface PartialParts {
+  year?: number;
+  month?: number;
+  day?: number;
+  /** Always 0–23 when set. */
+  hour?: number;
+  minute?: number;
+  second?: number;
+  /** 0 = AM, 1 = PM when hour12. */
+  dayPeriod?: number;
+}
+
+type NumericPartKey = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
+
+function partsFromValue(value: DateTimeId | undefined, hour12: boolean): PartialParts {
+  if (!value) {
+    return {};
+  }
+  const parsed = parseDateTimeId(value);
+  if (!parsed) {
+    return {};
+  }
+  return {
+    year: parsed.year,
+    month: parsed.month,
+    day: parsed.day,
+    hour: parsed.hour,
+    minute: parsed.minute,
+    second: parsed.second,
+    ...(hour12 ? { dayPeriod: parsed.hour >= 12 ? 1 : 0 } : {}),
+  };
+}
+
+function requiredPartKeys(
+  granularity: DateTimeGranularity,
+  hour12: boolean,
+): (keyof PartialParts)[] {
+  const keys: (keyof PartialParts)[] = ['year', 'month', 'day'];
+  if (granularity === 'day') {
+    return keys;
+  }
+
+  const { showMinute, showSecond } = getDateTimeSegmentVisibility(granularity);
+  keys.push('hour');
+  if (showMinute) {
+    keys.push('minute');
+  }
+  if (showSecond) {
+    keys.push('second');
+  }
+  if (hour12) {
+    keys.push('dayPeriod');
+  }
+  return keys;
+}
+
+function isComplete(
+  parts: PartialParts,
+  granularity: DateTimeGranularity,
+  hour12: boolean,
+): boolean {
+  return requiredPartKeys(granularity, hour12).every((key) => parts[key] != null);
+}
+
+function partialPartsToWire(
+  parts: PartialParts,
+  granularity: DateTimeGranularity,
+): DateTimeId | undefined {
+  const { year, month, day, hour, minute, second } = parts;
+  if (year == null || month == null || day == null) {
+    return undefined;
+  }
+  if (granularity === 'day') {
+    return formatDateTimeId({ year, month, day, hour: 0, minute: 0 });
+  }
+  if (hour == null) {
+    return undefined;
+  }
+  if (granularity === 'hour') {
+    return formatDateTimeId({ year, month, day, hour, minute: 0 });
+  }
+  if (minute == null) {
+    return undefined;
+  }
+  if (granularity === 'second') {
+    if (second == null) {
+      return undefined;
+    }
+    return formatDateTimeId({ year, month, day, hour, minute, second });
+  }
+  return formatDateTimeId({ year, month, day, hour, minute });
+}
+
+function formatHourDisplay(hour24: number, hour12: boolean): string {
+  if (hour12) {
+    return String(toHour12(hour24));
+  }
+  return formatDateSegment('hour', hour24);
+}
+
+function formatDayPeriodDisplay(period: number, locale: string): string {
+  return formatDateTimeListPeriod(period === 1 ? 13 : 9, { locale });
+}
+
+export function useDateTimeFieldSegmentState({
+  granularity,
+  hour12,
+  locale,
+  segments,
+  value,
+  setValue,
+  disabled,
+  readOnly,
+}: UseDateTimeFieldSegmentStateOptions) {
+  const keyboardOptions: SegmentKeyboardOptions = { hour12 };
+  const [focusedSegmentIndex, setFocusedSegmentIndex] = useState<number | null>(null);
+  const [segmentDraft, setSegmentDraft] = useState('');
+  const [isDraftDirty, setIsDraftDirty] = useState(false);
+  const [partialParts, setPartialParts] = useState<PartialParts>(() =>
+    partsFromValue(value, hour12),
+  );
+
+  const focusedSegmentIndexRef = useRef(focusedSegmentIndex);
+  const segmentDraftRef = useRef(segmentDraft);
+  const isDraftDirtyRef = useRef(isDraftDirty);
+  const segmentsRef = useRef(segments);
+  const valueRef = useRef(value);
+  const partialPartsRef = useRef(partialParts);
+  focusedSegmentIndexRef.current = focusedSegmentIndex;
+  segmentDraftRef.current = segmentDraft;
+  isDraftDirtyRef.current = isDraftDirty;
+  segmentsRef.current = segments;
+  valueRef.current = value;
+  partialPartsRef.current = partialParts;
+
+  useEffect(() => {
+    if (!value) {
+      if (focusedSegmentIndexRef.current == null && !isDraftDirtyRef.current) {
+        partialPartsRef.current = {};
+        setPartialParts({});
+      }
+      return;
+    }
+    const next = partsFromValue(value, hour12);
+    partialPartsRef.current = next;
+    setPartialParts(next);
+  }, [value, hour12]);
+
+  const setDraftState = (draft: string, dirty: boolean, index = focusedSegmentIndexRef.current) => {
+    if (index != null) {
+      setFocusedSegmentIndex(index);
+      focusedSegmentIndexRef.current = index;
+    }
+    setSegmentDraft(draft);
+    setIsDraftDirty(dirty);
+    segmentDraftRef.current = draft;
+    isDraftDirtyRef.current = dirty;
+  };
+
+  const writePartial = useCallback(
+    (next: PartialParts) => {
+      partialPartsRef.current = next;
+      setPartialParts(next);
+
+      // Only publish complete values — mid-entry keeps the last wire value for controlled parents
+      // whose `onValueChange` does not accept `undefined`.
+      if (isComplete(next, granularity, hour12)) {
+        const wire = partialPartsToWire(next, granularity);
+        if (wire !== undefined) {
+          setValue(wire);
+          valueRef.current = wire;
+        }
+      }
+    },
+    [granularity, hour12, setValue],
+  );
+
+  const clearAll = useCallback(() => {
+    partialPartsRef.current = {};
+    setPartialParts({});
+  }, []);
+
+  const commitNumericPart = useCallback(
+    (segmentType: DateSegmentType, segmentValue: number) => {
+      if (disabled || readOnly) {
+        return;
+      }
+
+      if (segmentType === 'hour') {
+        if (hour12) {
+          const period = partialPartsRef.current.dayPeriod ?? 0;
+          writePartial({
+            ...partialPartsRef.current,
+            hour: toHour24(segmentValue, period),
+            dayPeriod: period,
+          });
+          return;
+        }
+        writePartial({ ...partialPartsRef.current, hour: segmentValue });
+        return;
+      }
+
+      if (
+        segmentType === 'year' ||
+        segmentType === 'month' ||
+        segmentType === 'day' ||
+        segmentType === 'minute' ||
+        segmentType === 'second'
+      ) {
+        writePartial({
+          ...partialPartsRef.current,
+          [segmentType]: segmentValue,
+        });
+      }
+    },
+    [disabled, hour12, readOnly, writePartial],
+  );
+
+  const commitDayPeriod = useCallback(
+    (period: number) => {
+      if (disabled || readOnly) {
+        return;
+      }
+      const current = partialPartsRef.current;
+      const hour12Value = current.hour != null ? toHour12(current.hour) : undefined;
+      writePartial({
+        ...current,
+        dayPeriod: period,
+        ...(hour12Value != null ? { hour: toHour24(hour12Value, period) } : {}),
+      });
+    },
+    [disabled, readOnly, writePartial],
+  );
+
+  const clearSegmentValue = useCallback(
+    (segmentType: DateSegmentType) => {
+      if (segmentType === 'dayPeriod') {
+        const { dayPeriod: _cleared, ...next } = partialPartsRef.current;
+        writePartial(next);
+        return;
+      }
+      if (
+        segmentType === 'year' ||
+        segmentType === 'month' ||
+        segmentType === 'day' ||
+        segmentType === 'hour' ||
+        segmentType === 'minute' ||
+        segmentType === 'second'
+      ) {
+        const key = segmentType as NumericPartKey;
+        const { [key]: _cleared, ...next } = partialPartsRef.current;
+        writePartial(next);
+      }
+    },
+    [writePartial],
+  );
+
+  const commitFocusedSegment = useCallback(
+    (draft: string) => {
+      const index = focusedSegmentIndexRef.current;
+      if (index == null) {
+        return;
+      }
+      const segment = segmentsRef.current[index];
+      if (!segment?.isEditable) {
+        return;
+      }
+      if (draft === '') {
+        clearSegmentValue(segment.type);
+        return;
+      }
+      if (segment.type === 'dayPeriod') {
+        const parsed = commitDayPeriodDraft(draft);
+        if (parsed != null) {
+          commitDayPeriod(parsed);
+        }
+        return;
+      }
+      const parsed = commitSegmentDraft(segment, draft);
+      if (parsed != null) {
+        commitNumericPart(segment.type, parsed);
+      }
+    },
+    [clearSegmentValue, commitDayPeriod, commitNumericPart],
+  );
+
+  const initialDraftForSegment = (segment: DateSegment | undefined): string => {
+    if (!segment) {
+      return '';
+    }
+    if (segment.type === 'dayPeriod') {
+      if (partialPartsRef.current.dayPeriod != null) {
+        return formatDayPeriodDisplay(partialPartsRef.current.dayPeriod, locale);
+      }
+      if (segment.value == null) {
+        return '';
+      }
+      return segment.text;
+    }
+    if (segment.type === 'hour') {
+      if (partialPartsRef.current.hour != null) {
+        return formatHourDisplay(partialPartsRef.current.hour, hour12);
+      }
+      if (segment.value == null) {
+        return '';
+      }
+      return segment.text;
+    }
+    const partial = partialPartsRef.current[segment.type as NumericPartKey];
+    if (partial != null) {
+      return formatDateSegment(segment.type, partial);
+    }
+    if (segment.value == null) {
+      return '';
+    }
+    return segment.text;
+  };
+
+  const focusSegment = useCallback(
+    (index: number) => {
+      if (disabled || readOnly) {
+        return;
+      }
+      const segment = segmentsRef.current[index];
+      if (!segment?.isEditable) {
+        return;
+      }
+      setDraftState(initialDraftForSegment(segment), false, index);
+    },
+    [disabled, hour12, locale, readOnly],
+  );
+
+  const blurSegment = useCallback(
+    (index: number) => {
+      if (focusedSegmentIndexRef.current !== index) {
+        return;
+      }
+      const segment = segmentsRef.current[index];
+      if (segment?.isEditable && isDraftDirtyRef.current) {
+        commitFocusedSegment(segmentDraftRef.current);
+      }
+      setFocusedSegmentIndex(null);
+      setSegmentDraft('');
+      setIsDraftDirty(false);
+      focusedSegmentIndexRef.current = null;
+      segmentDraftRef.current = '';
+      isDraftDirtyRef.current = false;
+    },
+    [commitFocusedSegment],
+  );
+
+  const focusNextEditableSegment = useCallback(() => {
+    const current = focusedSegmentIndexRef.current;
+    if (current == null) {
+      return;
+    }
+    const next = findAdjacentEditableIndex(segmentsRef.current, current, 1);
+    if (next == null) {
+      return;
+    }
+    setDraftState(initialDraftForSegment(segmentsRef.current[next]), false, next);
+  }, [hour12, locale]);
+
+  const focusPrevEditableSegment = useCallback(() => {
+    const current = focusedSegmentIndexRef.current;
+    if (current == null) {
+      return;
+    }
+    const prev = findAdjacentEditableIndex(segmentsRef.current, current, -1);
+    if (prev == null) {
+      return;
+    }
+    setDraftState(initialDraftForSegment(segmentsRef.current[prev]), false, prev);
+  }, [hour12, locale]);
+
+  const advanceAfterCommit = (fromIndex: number, spillDigit?: string) => {
+    const next = findAdjacentEditableIndex(segmentsRef.current, fromIndex, 1);
+    if (next == null) {
+      return {
+        index: fromIndex,
+        draft: segmentDraftRef.current,
+        dirty: false,
+        spill: undefined as string | undefined,
+      };
+    }
+    return {
+      index: next,
+      draft: initialDraftForSegment(segmentsRef.current[next]),
+      dirty: false,
+      spill: spillDigit,
+    };
+  };
+
+  const handleSegmentDigit = useCallback(
+    (input: string) => {
+      if (focusedSegmentIndexRef.current == null || disabled || readOnly) {
+        return;
+      }
+
+      let index = focusedSegmentIndexRef.current;
+      let draft = segmentDraftRef.current;
+      let dirty = isDraftDirtyRef.current;
+      const currentSegments = segmentsRef.current;
+      const queue = input.split('').filter((char) => /^\d$/.test(char));
+
+      while (queue.length > 0) {
+        const digit = queue.shift() ?? '';
+        const segment = currentSegments[index];
+        if (!segment?.isEditable) {
+          break;
+        }
+
+        if (segment.type === 'dayPeriod') {
+          const parsed = commitDayPeriodDraft(digit);
+          if (parsed != null) {
+            commitDayPeriod(parsed);
+            const advanced = advanceAfterCommit(index);
+            index = advanced.index;
+            draft = advanced.draft;
+            dirty = advanced.dirty;
+          }
+          continue;
+        }
+
+        const {
+          draft: nextDraft,
+          isDraftDirty: nextDirty,
+          shouldCommit,
+          spillDigit,
+        } = applySegmentDigit(draft, segment.text, dirty, digit, segment.type, keyboardOptions);
+        draft = nextDraft;
+        dirty = nextDirty;
+        if (shouldCommit) {
+          const parsed = commitSegmentDraft(segment, draft);
+          if (parsed != null) {
+            commitNumericPart(segment.type, parsed);
+          }
+          const advanced = advanceAfterCommit(index, spillDigit);
+          index = advanced.index;
+          draft = advanced.draft;
+          dirty = advanced.dirty;
+          if (advanced.spill) {
+            queue.unshift(advanced.spill);
+          }
+        }
+      }
+
+      setDraftState(draft, dirty, index);
+    },
+    [commitDayPeriod, commitNumericPart, disabled, hour12, locale, readOnly],
+  );
+
+  const handleDayPeriodKey = useCallback(
+    (key: string) => {
+      if (focusedSegmentIndexRef.current == null || disabled || readOnly) {
+        return;
+      }
+      const index = focusedSegmentIndexRef.current;
+      const segment = segmentsRef.current[index];
+      if (segment?.type !== 'dayPeriod') {
+        return;
+      }
+      const parsed = commitDayPeriodDraft(key);
+      if (parsed == null) {
+        return;
+      }
+      commitDayPeriod(parsed);
+      const next = findAdjacentEditableIndex(segmentsRef.current, index, 1);
+      if (next == null) {
+        setDraftState(formatDayPeriodDisplay(parsed, locale), false, index);
+        return;
+      }
+      setDraftState(initialDraftForSegment(segmentsRef.current[next]), false, next);
+    },
+    [commitDayPeriod, disabled, hour12, locale, readOnly],
+  );
+
+  const handleSegmentInputChange = useCallback(
+    (raw: string) => {
+      if (focusedSegmentIndexRef.current == null || disabled || readOnly) {
+        return;
+      }
+
+      const index = focusedSegmentIndexRef.current;
+      const segment = segmentsRef.current[index];
+      if (!segment?.isEditable) {
+        return;
+      }
+
+      if (segment.type === 'dayPeriod') {
+        const letter = raw.replace(/[^aApP12]/g, '').slice(-1);
+        if (!letter) {
+          setDraftState('', true, index);
+          clearSegmentValue('dayPeriod');
+          return;
+        }
+        handleDayPeriodKey(letter);
+        return;
+      }
+
+      const maxLength = getSegmentMaxLength(segment.type);
+      const digits = raw.replace(/\D/g, '');
+      const prevDigits = segmentDraftRef.current.replace(/\D/g, '');
+
+      if (digits === prevDigits) {
+        return;
+      }
+
+      if (digits.length === 0) {
+        setDraftState('', true, index);
+        clearSegmentValue(segment.type);
+        return;
+      }
+
+      if (digits.length > prevDigits.length && digits.startsWith(prevDigits)) {
+        handleSegmentDigit(digits.slice(prevDigits.length));
+        return;
+      }
+
+      if (digits.length > maxLength) {
+        setDraftState('', true, index);
+        handleSegmentDigit(digits);
+        return;
+      }
+
+      setDraftState(digits, true, index);
+      if (isSegmentDraftComplete(segment.type, digits, keyboardOptions)) {
+        const parsed = commitSegmentDraft(segment, digits);
+        if (parsed != null) {
+          commitNumericPart(segment.type, parsed);
+        }
+        const next = findAdjacentEditableIndex(segmentsRef.current, index, 1);
+        if (next == null) {
+          setDraftState(digits, false, index);
+          return;
+        }
+        setDraftState(initialDraftForSegment(segmentsRef.current[next]), false, next);
+      }
+    },
+    [
+      clearSegmentValue,
+      commitNumericPart,
+      disabled,
+      handleDayPeriodKey,
+      handleSegmentDigit,
+      hour12,
+      locale,
+      readOnly,
+    ],
+  );
+
+  const handleSegmentBackspace = useCallback(() => {
+    if (focusedSegmentIndexRef.current == null || disabled || readOnly) {
+      return;
+    }
+
+    const index = focusedSegmentIndexRef.current;
+    const segment = segmentsRef.current[index];
+    const draft =
+      segment?.type === 'dayPeriod'
+        ? segmentDraftRef.current
+        : segmentDraftRef.current.replace(/\D/g, '');
+
+    if (draft.length > 0) {
+      const nextDraft = draft.slice(0, -1);
+      setDraftState(nextDraft, true, index);
+      if (nextDraft.length === 0 && segment) {
+        clearSegmentValue(segment.type);
+      }
+      return;
+    }
+
+    const prev = findAdjacentEditableIndex(segmentsRef.current, index, -1);
+    if (prev == null) {
+      clearAll();
+      return;
+    }
+    setDraftState(initialDraftForSegment(segmentsRef.current[prev]), false, prev);
+  }, [clearAll, clearSegmentValue, disabled, hour12, locale, readOnly]);
+
+  const getSegmentDisplayText = useCallback(
+    (index: number) => {
+      const segment = segments[index];
+      if (!segment) {
+        return '';
+      }
+      if (focusedSegmentIndex === index) {
+        if (segmentDraft === '') {
+          return getEmptyDateSegmentText(segment.type) || segment.text;
+        }
+        return segmentDraft;
+      }
+
+      if (segment.type === 'dayPeriod') {
+        if (partialParts.dayPeriod != null) {
+          return formatDayPeriodDisplay(partialParts.dayPeriod, locale);
+        }
+        return getEmptyDateSegmentText('dayPeriod') || segment.text;
+      }
+
+      if (segment.type === 'hour') {
+        if (partialParts.hour != null) {
+          return formatHourDisplay(partialParts.hour, hour12);
+        }
+        return getEmptyDateSegmentText('hour') || segment.text;
+      }
+
+      const partial = partialParts[segment.type as NumericPartKey];
+      if (partial != null) {
+        return formatDateSegment(segment.type, partial);
+      }
+
+      if (segment.value != null) {
+        return segment.text;
+      }
+
+      return getEmptyDateSegmentText(segment.type) || segment.text;
+    },
+    [focusedSegmentIndex, hour12, locale, partialParts, segmentDraft, segments],
+  );
+
+  return {
+    focusedSegmentIndex,
+    segmentDraft,
+    focusSegment,
+    blurSegment,
+    focusNextEditableSegment,
+    focusPrevEditableSegment,
+    handleSegmentDigit,
+    handleSegmentInputChange,
+    handleSegmentBackspace,
+    handleDayPeriodKey,
+    getSegmentDisplayText,
+  };
+}