@cdx-ui/primitives 0.0.1-beta.17 → 0.0.1-beta.170

package/src/date-field/segmentKeyboard.ts

@@ -0,0 +1,207 @@
+import { parseDateSegment, type DateSegment, type DateSegmentType } from '@cdx-ui/formatters';
+
+export interface SegmentKeyboardOptions {
+  /** When true, hour segments are 1–12; otherwise 0–23. */
+  hour12?: boolean;
+}
+
+export const SEGMENT_MAX_LENGTH: Partial<Record<DateSegmentType, number>> = {
+  month: 2,
+  day: 2,
+  year: 4,
+  hour: 2,
+  minute: 2,
+  second: 2,
+  dayPeriod: 1,
+};
+
+export function getSegmentMaxLength(type: DateSegmentType): number {
+  return SEGMENT_MAX_LENGTH[type] ?? 4;
+}
+
+/** True when another digit cannot produce a different valid value (auto-advance). */
+export function isSegmentDraftComplete(
+  type: DateSegmentType,
+  draft: string,
+  options?: SegmentKeyboardOptions,
+): boolean {
+  if (!draft) {
+    return false;
+  }
+  const maxLength = getSegmentMaxLength(type);
+  if (draft.length >= maxLength) {
+    return true;
+  }
+
+  const value = Number(draft);
+  if (Number.isNaN(value)) {
+    return false;
+  }
+
+  // Month 1-12: 2-9 cannot be a leading digit of a two-digit month.
+  if (type === 'month') {
+    return value >= 2 && value <= 9;
+  }
+
+  // Day 1-31: 4-9 cannot be a leading digit of a two-digit day.
+  if (type === 'day') {
+    return value >= 4 && value <= 9;
+  }
+
+  if (type === 'hour') {
+    if (options?.hour12) {
+      return value >= 2 && value <= 9;
+    }
+    // 0-23: 3-9 cannot start a valid two-digit hour.
+    return value >= 3 && value <= 9;
+  }
+
+  // Minute / second 0-59: 6-9 cannot start a valid two-digit value.
+  if (type === 'minute' || type === 'second') {
+    return value >= 6 && value <= 9;
+  }
+
+  return false;
+}
+
+function isValidSegmentDraft(
+  type: DateSegmentType,
+  draft: string,
+  options?: SegmentKeyboardOptions,
+): boolean {
+  if (!draft) {
+    return true;
+  }
+  const value = Number(draft);
+  if (Number.isNaN(value)) {
+    return false;
+  }
+  if (type === 'month') {
+    if (draft.length === 1) {
+      return value >= 0 && value <= 9;
+    }
+    return value >= 1 && value <= 12;
+  }
+  if (type === 'day') {
+    if (draft.length === 1) {
+      return value >= 0 && value <= 9;
+    }
+    return value >= 1 && value <= 31;
+  }
+  if (type === 'year') {
+    return draft.length <= 4;
+  }
+  if (type === 'hour') {
+    if (draft.length === 1) {
+      return value >= 0 && value <= 9;
+    }
+    if (options?.hour12) {
+      return value >= 1 && value <= 12;
+    }
+    return value >= 0 && value <= 23;
+  }
+  if (type === 'minute' || type === 'second') {
+    if (draft.length === 1) {
+      return value >= 0 && value <= 9;
+    }
+    return value >= 0 && value <= 59;
+  }
+  return true;
+}
+
+export function applySegmentDigit(
+  draft: string,
+  _committedText: string,
+  isDraftDirty: boolean,
+  digit: string,
+  type: DateSegmentType,
+  options?: SegmentKeyboardOptions,
+): {
+  draft: string;
+  isDraftDirty: boolean;
+  shouldCommit: boolean;
+  /** When set, commit `draft` then apply this digit to the next segment. */
+  spillDigit?: string;
+} {
+  const maxLength = getSegmentMaxLength(type);
+  const base = isDraftDirty ? draft : '';
+  const candidate = `${base}${digit}`.slice(0, maxLength + 1);
+
+  // e.g. month "1" + "5" → invalid 15: commit 1, spill 5 into day.
+  if (
+    base.length > 0 &&
+    candidate.length <= maxLength &&
+    !isValidSegmentDraft(type, candidate, options) &&
+    isValidSegmentDraft(type, base, options) &&
+    Number(base) >= 1
+  ) {
+    return {
+      draft: base,
+      isDraftDirty: true,
+      shouldCommit: true,
+      spillDigit: digit,
+    };
+  }
+
+  const nextDraft = candidate.slice(0, maxLength);
+  if (!isValidSegmentDraft(type, nextDraft, options)) {
+    // Replace with the new digit alone (e.g. starting fresh).
+    return {
+      draft: digit,
+      isDraftDirty: true,
+      shouldCommit: isSegmentDraftComplete(type, digit, options),
+    };
+  }
+
+  return {
+    draft: nextDraft,
+    isDraftDirty: true,
+    shouldCommit: isSegmentDraftComplete(type, nextDraft, options),
+  };
+}
+
+export function commitSegmentDraft(segment: DateSegment, draft: string): number | null {
+  const parsed = parseDateSegment(segment.type, draft || segment.text);
+  return parsed;
+}
+
+/** Parses day-period input (`A`/`P`/`1`/`2`) into 0 (AM) or 1 (PM). */
+export function commitDayPeriodDraft(draft: string): number | null {
+  const trimmed = draft.trim().toLowerCase();
+  if (!trimmed) {
+    return null;
+  }
+  if (trimmed === 'a' || trimmed === 'am' || trimmed === '1') {
+    return 0;
+  }
+  if (trimmed === 'p' || trimmed === 'pm' || trimmed === '2') {
+    return 1;
+  }
+  return null;
+}
+
+export function findAdjacentEditableIndex(
+  segments: DateSegment[],
+  fromIndex: number,
+  direction: -1 | 1,
+): number | null {
+  for (
+    let i = fromIndex + direction;
+    direction < 0 ? i >= 0 : i < segments.length;
+    i += direction
+  ) {
+    if (segments[i]?.isEditable) {
+      return i;
+    }
+  }
+  return null;
+}
+
+export function toHour24(hour12: number, period: number): number {
+  const normalized = hour12 % 12;
+  return normalized + (period === 1 ? 12 : 0);
+}
+
+export function toHour12(hour24: number): number {
+  return hour24 % 12 || 12;
+}

package/src/date-field/types.ts

@@ -0,0 +1,40 @@
+import type { ViewProps } from 'react-native';
+import type { DateComponentLabels, DateFieldMode, DateId, MonthId } from '@cdx-ui/formatters';
+
+export interface IDateFieldProps {
+  /**
+   * Controlled value: a `DateId` (`YYYY-MM-DD`) in date mode, or a `MonthId`
+   * (`YYYY-MM-01`) in month mode. Build one with `dateId(...)` / `monthId(...)`
+   * from `@cdx-ui/formatters` — a bare string will not type-check.
+   */
+  value?: DateId | MonthId;
+  /** Uncontrolled initial value, in the same format as `value`. */
+  defaultValue?: DateId | MonthId;
+  /** Called with the new value once every segment is filled, or `undefined` when the field is cleared. */
+  onValueChange?: (value: DateId | MonthId | undefined) => void;
+  /** Which segments to render: `date` shows month, day, and year; `month` shows month and year only. */
+  mode?: DateFieldMode;
+  /** BCP-47 locale that controls segment order and separators. Defaults to `en-US`. */
+  locale?: string;
+  /** Overrides the accessible labels announced for each segment. */
+  labels?: Partial<DateComponentLabels>;
+  isDisabled?: boolean;
+  isReadOnly?: boolean;
+  isInvalid?: boolean;
+  isRequired?: boolean;
+}
+
+export interface IDateFieldInputProps extends Omit<ViewProps, 'children'> {
+  children: (segment: import('@cdx-ui/formatters').DateSegment) => React.ReactNode;
+  /**
+   * Range-composition hint. Only meaningful when a `DateField.Input` is rendered
+   * inside a `DateRangePicker` — it binds the input to the range's start or end
+   * endpoint via the internal range bridge. Ignored for a standalone `DateField`.
+   */
+  slot?: 'start' | 'end';
+}
+
+export interface IDateFieldSegmentProps {
+  segment: import('@cdx-ui/formatters').DateSegment;
+  segmentIndex?: number;
+}

package/src/date-field/useDateFieldSegmentState.ts

@@ -0,0 +1,455 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  formatDateId,
+  formatDateSegment,
+  formatMonthId,
+  getEmptyDateSegmentText,
+  parseDateId,
+  parseMonthId,
+  type DateFieldMode,
+  type DateId,
+  type DateSegment,
+  type DateSegmentType,
+  type MonthId,
+} from '@cdx-ui/formatters';
+import type { DateFieldValue } from './context';
+import {
+  applySegmentDigit,
+  commitSegmentDraft,
+  findAdjacentEditableIndex,
+  getSegmentMaxLength,
+  isSegmentDraftComplete,
+} from './segmentKeyboard';
+
+interface UseDateFieldSegmentStateOptions {
+  mode: DateFieldMode;
+  segments: DateSegment[];
+  value: DateFieldValue;
+  setValue: (value: DateFieldValue) => void;
+  disabled: boolean;
+  readOnly: boolean;
+}
+
+/** In-progress segment values. Wire `value` is only written when this is complete. */
+interface PartialParts {
+  year?: number;
+  month?: number;
+  day?: number;
+}
+
+type PartialPartKey = keyof PartialParts;
+
+function isPartialPartKey(type: DateSegmentType): type is PartialPartKey {
+  return type === 'year' || type === 'month' || type === 'day';
+}
+
+function requiredSegmentTypes(mode: DateFieldMode): PartialPartKey[] {
+  return mode === 'month' ? ['month', 'year'] : ['month', 'day', 'year'];
+}
+
+function isComplete(parts: PartialParts, mode: DateFieldMode): boolean {
+  return requiredSegmentTypes(mode).every((type) => parts[type] != null);
+}
+
+function partialPartsToWire(parts: PartialParts, mode: DateFieldMode): DateFieldValue {
+  const { year, month, day } = parts;
+  if (year == null || month == null) {
+    return undefined;
+  }
+  if (mode === 'month') {
+    return formatMonthId({ year, month });
+  }
+  if (day == null) {
+    return undefined;
+  }
+  return formatDateId({ year, month, day });
+}
+
+function partsFromValue(value: DateFieldValue, mode: DateFieldMode): PartialParts {
+  if (!value) {
+    return {};
+  }
+  if (mode === 'month') {
+    const parsed = parseMonthId(value as MonthId);
+    return parsed ? { year: parsed.year, month: parsed.month } : {};
+  }
+  const parsed = parseDateId(value as DateId);
+  return parsed ? { year: parsed.year, month: parsed.month, day: parsed.day } : {};
+}
+
+function formatPartialSegment(type: DateSegmentType, value: number): string {
+  return formatDateSegment(type, value);
+}
+
+export function useDateFieldSegmentState({
+  mode,
+  segments,
+  value,
+  setValue,
+  disabled,
+  readOnly,
+}: UseDateFieldSegmentStateOptions) {
+  const [focusedSegmentIndex, setFocusedSegmentIndex] = useState<number | null>(null);
+  const [segmentDraft, setSegmentDraft] = useState('');
+  const [isDraftDirty, setIsDraftDirty] = useState(false);
+  const [partialParts, setPartialParts] = useState<PartialParts>(() => partsFromValue(value, mode));
+
+  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;
+
+  // Keep partial parts aligned when a complete controlled value is provided.
+  // Do not reset partials when value becomes undefined mid-entry (incomplete date).
+  useEffect(() => {
+    if (!value) {
+      if (focusedSegmentIndexRef.current == null && !isDraftDirtyRef.current) {
+        partialPartsRef.current = {};
+        setPartialParts({});
+      }
+      return;
+    }
+    const next = partsFromValue(value, mode);
+    partialPartsRef.current = next;
+    setPartialParts(next);
+  }, [value, mode]);
+
+  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);
+
+      if (isComplete(next, mode)) {
+        const wire = partialPartsToWire(next, mode);
+        if (wire !== undefined) {
+          setValue(wire);
+          valueRef.current = wire;
+        }
+        return;
+      }
+
+      // Incomplete — never invent year/day defaults onto the wire value.
+      if (valueRef.current !== undefined) {
+        setValue(undefined);
+        valueRef.current = undefined;
+      }
+    },
+    [mode, setValue],
+  );
+
+  const clearAll = useCallback(() => {
+    partialPartsRef.current = {};
+    setPartialParts({});
+    setValue(undefined);
+    valueRef.current = undefined;
+  }, [setValue]);
+
+  const commitSegmentValue = useCallback(
+    (segmentType: DateSegment['type'], segmentValue: number) => {
+      if (disabled || readOnly || !isPartialPartKey(segmentType)) {
+        return;
+      }
+      writePartial({
+        ...partialPartsRef.current,
+        [segmentType]: segmentValue,
+      });
+    },
+    [disabled, readOnly, writePartial],
+  );
+
+  const clearSegmentValue = useCallback(
+    (segmentType: DateSegment['type']) => {
+      if (!isPartialPartKey(segmentType)) {
+        return;
+      }
+      const { [segmentType]: _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;
+      }
+      const parsed = commitSegmentDraft(segment, draft);
+      if (parsed != null) {
+        commitSegmentValue(segment.type, parsed);
+      }
+    },
+    [clearSegmentValue, commitSegmentValue],
+  );
+
+  const initialDraftForSegment = (segment: DateSegment | undefined): string => {
+    if (!segment) {
+      return '';
+    }
+    const partial = partialPartsRef.current[segment.type as keyof PartialParts];
+    if (partial != null) {
+      return formatPartialSegment(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, 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);
+  }, []);
+
+  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);
+  }, []);
+
+  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;
+        }
+        const {
+          draft: nextDraft,
+          isDraftDirty: nextDirty,
+          shouldCommit,
+          spillDigit,
+        } = applySegmentDigit(draft, segment.text, dirty, digit, segment.type);
+        draft = nextDraft;
+        dirty = nextDirty;
+        if (shouldCommit) {
+          const parsed = commitSegmentDraft(segment, draft);
+          if (parsed != null) {
+            commitSegmentValue(segment.type, parsed);
+          }
+          const next = findAdjacentEditableIndex(currentSegments, index, 1);
+          if (next == null) {
+            dirty = false;
+            break;
+          }
+          index = next;
+          draft = initialDraftForSegment(currentSegments[next]);
+          dirty = false;
+          if (spillDigit) {
+            queue.unshift(spillDigit);
+          }
+        }
+      }
+
+      setDraftState(draft, dirty, index);
+    },
+    [commitSegmentValue, disabled, 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;
+      }
+
+      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;
+      }
+
+      // Same-length replace or shorten — also auto-advance when draft is unambiguous.
+      setDraftState(digits, true, index);
+      if (isSegmentDraftComplete(segment.type, digits)) {
+        const parsed = commitSegmentDraft(segment, digits);
+        if (parsed != null) {
+          commitSegmentValue(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, commitSegmentValue, disabled, handleSegmentDigit, readOnly],
+  );
+
+  const handleSegmentBackspace = useCallback(() => {
+    if (focusedSegmentIndexRef.current == null || disabled || readOnly) {
+      return;
+    }
+
+    const index = focusedSegmentIndexRef.current;
+    const segment = segmentsRef.current[index];
+    const draft = 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, 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;
+      }
+
+      const partial = partialParts[segment.type as keyof PartialParts];
+      if (partial != null) {
+        return formatPartialSegment(segment.type, partial);
+      }
+
+      if (segment.value != null) {
+        return segment.text;
+      }
+
+      return getEmptyDateSegmentText(segment.type) || segment.text;
+    },
+    [focusedSegmentIndex, partialParts, segmentDraft, segments],
+  );
+
+  return {
+    focusedSegmentIndex,
+    segmentDraft,
+    setFocusedSegmentIndex,
+    focusSegment,
+    blurSegment,
+    focusNextEditableSegment,
+    focusPrevEditableSegment,
+    handleSegmentDigit,
+    handleSegmentInputChange,
+    handleSegmentBackspace,
+    getSegmentDisplayText,
+    onSegmentChange: commitSegmentValue,
+  };
+}