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

package/src/date-time-list/DateTimeListRoot.tsx

@@ -0,0 +1,530 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import {
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+  Platform,
+  ScrollView,
+  View,
+  type ViewProps,
+  type ViewStyle,
+} from 'react-native';
+import {
+  clampDateTimeId,
+  compareDateIds,
+  dateRangeAroundDay,
+  eachDateIdInRange,
+  formatDateId,
+  formatDateTimeListDateRow,
+  formatDateTimeListHour,
+  formatDateTimeListMinute,
+  formatDateTimeListPeriod,
+  isLocaleHour12,
+  parseDateTimeId,
+  todayDateId,
+  type DateId,
+  type DateTimeGranularity,
+  type DateTimeId,
+} from '@cdx-ui/formatters';
+import { useControllableState } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { accessibleLabelAttributes, resolveAccessibleLabel } from '../utils/accessibleLabel';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { applyDateTimePartChange } from '../date-time-field/DateTimeFieldRoot';
+import {
+  DateTimeListContext,
+  DateTimeListColumnContext,
+  useDateTimeListContext,
+  type DateTimeListColumnType,
+} from './context';
+
+/**
+ * Visible days before/after the date-column anchor in the scroll wheel.
+ * Default anchor is today; when the selected date falls outside this window it becomes the anchor
+ * so controlled values always appear in the list.
+ */
+const DATE_COLUMN_WINDOW_DAYS = 90;
+
+/** Row height for wheel columns (must match styled component). */
+export const DATE_TIME_LIST_ITEM_HEIGHT = 40;
+
+/** Odd count so one row sits exactly in the center. */
+export const DATE_TIME_LIST_VISIBLE_ITEMS = 5;
+
+export const DATE_TIME_LIST_HEIGHT = DATE_TIME_LIST_ITEM_HEIGHT * DATE_TIME_LIST_VISIBLE_ITEMS;
+
+/** Top/bottom padding so first/last items can snap into the center highlight. */
+export const DATE_TIME_LIST_EDGE_PAD = (DATE_TIME_LIST_HEIGHT - DATE_TIME_LIST_ITEM_HEIGHT) / 2;
+
+/**
+ * Native snap tuned to match web CSS `scroll-snap-align: center` resting positions.
+ * With edge padding, `scrollY = index * itemHeight` centers row `index` — same as web.
+ * iOS: snapToInterval (interval API). Android: snapToOffsets (interval is iOS-only).
+ */
+const iosSnapProps = {
+  snapToInterval: DATE_TIME_LIST_ITEM_HEIGHT,
+  snapToAlignment: 'start' as const,
+};
+
+const WEB_SCROLL_SNAP: ViewStyle | undefined =
+  Platform.OS === 'web' ? ({ scrollSnapType: 'y mandatory' } as ViewStyle) : undefined;
+
+const WEB_ITEM_SNAP: ViewStyle | undefined =
+  Platform.OS === 'web'
+    ? ({ scrollSnapAlign: 'center', scrollSnapStop: 'always' } as ViewStyle)
+    : undefined;
+
+export interface DateTimeListRootProps extends Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  value?: DateTimeId;
+  defaultValue?: DateTimeId;
+  onValueChange?: (value: DateTimeId) => void;
+  onUserInteract?: () => void;
+  granularity?: DateTimeGranularity;
+  locale?: string;
+  /** Force a 12- or 24-hour clock. Defaults to the locale's convention when omitted. */
+  hour12?: boolean;
+  disabled?: boolean;
+  /** Earliest selectable date-time. Dates before it are hidden; times are clamped. Build with `dateTimeId(...)`. */
+  minValue?: DateTimeId;
+  /** Latest selectable date-time. Dates after it are hidden; times are clamped. Build with `dateTimeId(...)`. */
+  maxValue?: DateTimeId;
+}
+
+export const DateTimeListRoot = forwardRef<ComponentRef<typeof View>, DateTimeListRootProps>(
+  (
+    {
+      asChild,
+      children,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      onUserInteract,
+      granularity = 'minute',
+      locale = 'en-US',
+      hour12: hour12Prop,
+      disabled = false,
+      minValue,
+      maxValue,
+      accessibilityLabel: accessibilityLabelProp,
+      'aria-label': ariaLabelProp,
+      ...props
+    },
+    ref,
+  ) => {
+    const hour12 = hour12Prop ?? isLocaleHour12(locale);
+    const accessibilityLabel = resolveAccessibleLabel({
+      accessibilityLabel: accessibilityLabelProp,
+      'aria-label': ariaLabelProp,
+    });
+    const [value, setValue] = useControllableState<DateTimeId | undefined>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: (next) => {
+        if (next !== undefined) {
+          onValueChange?.(next);
+        }
+      },
+    });
+
+    const commitValue = useCallback(
+      (next: DateTimeId) => {
+        const clamped = clampDateTimeId(next, { min: minValue, max: maxValue });
+        if (clamped !== value) {
+          setValue(clamped);
+        } else {
+          onValueChange?.(clamped);
+        }
+      },
+      [maxValue, minValue, onValueChange, setValue, value],
+    );
+
+    const contextValue = useMemo(
+      () => ({
+        value,
+        onValueChange: commitValue,
+        onUserInteract,
+        granularity,
+        locale,
+        hour12,
+        disabled,
+        minValue,
+        maxValue,
+      }),
+      [
+        value,
+        commitValue,
+        onUserInteract,
+        granularity,
+        locale,
+        hour12,
+        disabled,
+        minValue,
+        maxValue,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <DateTimeListContext.Provider value={contextValue}>
+        <Comp
+          ref={ref}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ disabled }))}
+          {...accessibleLabelAttributes(accessibilityLabel)}
+        >
+          {children}
+        </Comp>
+      </DateTimeListContext.Provider>
+    );
+  },
+);
+
+DateTimeListRoot.displayName = 'DateTimeListRoot';
+
+function dateColumnAnchor(today: DateId, selectedDateId?: DateId): DateId {
+  const { startId, endId } = dateRangeAroundDay(
+    DATE_COLUMN_WINDOW_DAYS,
+    DATE_COLUMN_WINDOW_DAYS,
+    today,
+  );
+  if (
+    selectedDateId &&
+    (compareDateIds(selectedDateId, startId) < 0 || compareDateIds(selectedDateId, endId) > 0)
+  ) {
+    return selectedDateId;
+  }
+  return today;
+}
+
+function buildDateOptions(
+  locale: string,
+  selectedDateId?: DateId,
+  minDateId?: DateId,
+  maxDateId?: DateId,
+): { value: DateId; label: string }[] {
+  const today = todayDateId();
+  // Keep the window centered on an in-range anchor so the clamped ends never invert.
+  let anchor = dateColumnAnchor(today, selectedDateId);
+  if (minDateId && compareDateIds(anchor, minDateId) < 0) {
+    anchor = minDateId;
+  }
+  if (maxDateId && compareDateIds(anchor, maxDateId) > 0) {
+    anchor = maxDateId;
+  }
+
+  let { startId, endId } = dateRangeAroundDay(
+    DATE_COLUMN_WINDOW_DAYS,
+    DATE_COLUMN_WINDOW_DAYS,
+    anchor,
+  );
+  if (minDateId && compareDateIds(startId, minDateId) < 0) {
+    startId = minDateId;
+  }
+  if (maxDateId && compareDateIds(endId, maxDateId) > 0) {
+    endId = maxDateId;
+  }
+
+  return eachDateIdInRange(startId, endId).map((id) => ({
+    value: id,
+    label: formatDateTimeListDateRow(id, { todayDateId: today, locale }),
+  }));
+}
+
+function clampIndex(index: number, length: number): number {
+  if (length <= 0) {
+    return 0;
+  }
+  return Math.max(0, Math.min(length - 1, index));
+}
+
+function indexFromOffset(y: number, length: number): number {
+  return clampIndex(Math.round(y / DATE_TIME_LIST_ITEM_HEIGHT), length);
+}
+
+export interface DateTimeListColumnProps extends Omit<ViewProps, 'children'> {
+  column: DateTimeListColumnType;
+  asChild?: boolean;
+  className?: string;
+  children?: (option: {
+    value: string | number;
+    label: string;
+    selected: boolean;
+  }) => React.ReactNode;
+}
+
+export const DateTimeListColumn = forwardRef<ComponentRef<typeof View>, DateTimeListColumnProps>(
+  ({ column, asChild, className, style, children, ...props }, ref) => {
+    const { value, onValueChange, onUserInteract, hour12, locale, disabled, minValue, maxValue } =
+      useDateTimeListContext();
+    const parts = value ? parseDateTimeId(value) : null;
+    const selectedDateId = parts ? formatDateId(parts) : undefined;
+    const minDateId = useMemo(() => {
+      const p = minValue ? parseDateTimeId(minValue) : null;
+      return p ? formatDateId(p) : undefined;
+    }, [minValue]);
+    const maxDateId = useMemo(() => {
+      const p = maxValue ? parseDateTimeId(maxValue) : null;
+      return p ? formatDateId(p) : undefined;
+    }, [maxValue]);
+    const scrollRef = useRef<ScrollView>(null);
+    const isUserScrollingRef = useRef(false);
+    const lastEmittedIndexRef = useRef(-1);
+    const settleFrameRef = useRef<number | null>(null);
+
+    const options = useMemo(() => {
+      if (column === 'date') {
+        return buildDateOptions(locale, selectedDateId, minDateId, maxDateId);
+      }
+      if (column === 'hour') {
+        const hours = hour12
+          ? Array.from({ length: 12 }, (_, i) => i + 1)
+          : Array.from({ length: 24 }, (_, i) => i);
+        return hours.map((h) => ({
+          value: h,
+          label: formatDateTimeListHour(h, { hour12 }),
+        }));
+      }
+      if (column === 'minute' || column === 'second') {
+        return Array.from({ length: 60 }, (_, i) => ({
+          value: i,
+          label: formatDateTimeListMinute(i),
+        }));
+      }
+      return [
+        { value: 0, label: formatDateTimeListPeriod(0, { locale }) },
+        { value: 1, label: formatDateTimeListPeriod(12, { locale }) },
+      ];
+    }, [column, hour12, locale, selectedDateId, minDateId, maxDateId]);
+
+    const snapOffsets = useMemo(
+      () => options.map((_, index) => index * DATE_TIME_LIST_ITEM_HEIGHT),
+      [options],
+    );
+
+    const selectedValue = useMemo(() => {
+      if (!parts) {
+        return undefined;
+      }
+      if (column === 'date') {
+        return formatDateId(parts);
+      }
+      if (column === 'hour') {
+        return hour12 ? parts.hour % 12 || 12 : parts.hour;
+      }
+      if (column === 'minute') {
+        return parts.minute;
+      }
+      if (column === 'period') {
+        return parts.hour >= 12 ? 1 : 0;
+      }
+      return parts.second ?? 0;
+    }, [column, hour12, parts]);
+
+    const selectedIndex = useMemo(() => {
+      if (selectedValue === undefined) {
+        return -1;
+      }
+      return options.findIndex((option) => option.value === selectedValue);
+    }, [options, selectedValue]);
+
+    const commitIndex = useCallback(
+      (index: number) => {
+        if (disabled) {
+          return;
+        }
+        const nextIndex = clampIndex(index, options.length);
+        const option = options[nextIndex];
+        if (lastEmittedIndexRef.current === nextIndex) {
+          return;
+        }
+        lastEmittedIndexRef.current = nextIndex;
+
+        let next: DateTimeId | undefined;
+        if (column === 'date' && typeof option.value === 'string') {
+          next = applyDateTimePartChange(value, 'date', option.value);
+        } else if (column === 'hour' && typeof option.value === 'number') {
+          const hour = hour12
+            ? (parts && parts.hour >= 12 ? 12 : 0) + (option.value % 12)
+            : option.value;
+          next = applyDateTimePartChange(value, 'hour', hour);
+        } else if (column === 'minute' && typeof option.value === 'number') {
+          next = applyDateTimePartChange(value, 'minute', option.value);
+        } else if (column === 'second' && typeof option.value === 'number') {
+          next = applyDateTimePartChange(value, 'second', option.value);
+        } else if (column === 'period' && typeof option.value === 'number') {
+          next = applyDateTimePartChange(value, 'period', option.value);
+        }
+        if (next) {
+          onValueChange?.(next);
+        }
+      },
+      [column, disabled, hour12, onValueChange, options, parts, value],
+    );
+
+    const scrollToIndex = useCallback(
+      (index: number, animated: boolean) => {
+        const nextIndex = clampIndex(index, options.length);
+        scrollRef.current?.scrollTo({
+          y: nextIndex * DATE_TIME_LIST_ITEM_HEIGHT,
+          animated,
+        });
+      },
+      [options.length],
+    );
+
+    const settleToNearest = useCallback(
+      (y: number) => {
+        const index = indexFromOffset(y, options.length);
+        const targetY = index * DATE_TIME_LIST_ITEM_HEIGHT;
+        isUserScrollingRef.current = false;
+
+        if (settleFrameRef.current != null) {
+          cancelAnimationFrame(settleFrameRef.current);
+        }
+
+        // Animate into place, then lock the exact offset (mirrors CSS scroll-snap settle).
+        const needsAnimate = Math.abs(y - targetY) > 0.5;
+        scrollRef.current?.scrollTo({ y: targetY, animated: needsAnimate });
+        settleFrameRef.current = requestAnimationFrame(() => {
+          scrollRef.current?.scrollTo({ y: targetY, animated: false });
+          settleFrameRef.current = null;
+        });
+        commitIndex(index);
+      },
+      [commitIndex, options.length],
+    );
+
+    useEffect(() => {
+      return () => {
+        if (settleFrameRef.current != null) {
+          cancelAnimationFrame(settleFrameRef.current);
+        }
+      };
+    }, []);
+
+    useEffect(() => {
+      if (selectedIndex < 0 || isUserScrollingRef.current) {
+        return;
+      }
+      lastEmittedIndexRef.current = selectedIndex;
+      const frame = requestAnimationFrame(() => {
+        scrollToIndex(selectedIndex, false);
+      });
+      return () => cancelAnimationFrame(frame);
+    }, [scrollToIndex, selectedIndex]);
+
+    const onSelect = useCallback(
+      (optionValue: string | number) => {
+        const index = options.findIndex((option) => option.value === optionValue);
+        if (index < 0) {
+          return;
+        }
+        isUserScrollingRef.current = false;
+        onUserInteract?.();
+        scrollToIndex(index, true);
+        lastEmittedIndexRef.current = -1;
+        commitIndex(index);
+      },
+      [commitIndex, onUserInteract, options, scrollToIndex],
+    );
+
+    const handleScrollEnd = useCallback(
+      (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+        settleToNearest(event.nativeEvent.contentOffset.y);
+      },
+      [settleToNearest],
+    );
+
+    const columnContext = useMemo(
+      () => ({
+        column,
+        options,
+        selectedValue,
+        onSelect,
+      }),
+      [column, options, selectedValue, onSelect],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    const snapProps =
+      Platform.OS === 'ios'
+        ? iosSnapProps
+        : Platform.OS === 'android'
+          ? { snapToOffsets: snapOffsets, snapToAlignment: 'start' as const }
+          : {};
+
+    return (
+      <DateTimeListColumnContext.Provider value={columnContext}>
+        <Comp
+          ref={ref}
+          className={className}
+          style={style}
+          accessibilityRole="none"
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: `date-time-list-${column}` }))}
+        >
+          <ScrollView
+            ref={scrollRef}
+            showsVerticalScrollIndicator={false}
+            {...snapProps}
+            // Closest native match to CSS scroll-snap deceleration.
+            decelerationRate={Platform.OS === 'ios' ? 0.98 : 'fast'}
+            nestedScrollEnabled
+            disableIntervalMomentum
+            scrollEventThrottle={16}
+            style={WEB_SCROLL_SNAP}
+            onScrollBeginDrag={() => {
+              isUserScrollingRef.current = true;
+              onUserInteract?.();
+            }}
+            onMomentumScrollEnd={handleScrollEnd}
+            onScrollEndDrag={(event) => {
+              const velocityY = event.nativeEvent.velocity?.y ?? 0;
+              // Web / weak flings never get a reliable momentum end — settle here.
+              // Native strong flings wait for onMomentumScrollEnd (same as CSS snap).
+              if (Platform.OS === 'web' || Math.abs(velocityY) < 0.35) {
+                handleScrollEnd(event);
+              }
+            }}
+            contentContainerStyle={{
+              paddingTop: DATE_TIME_LIST_EDGE_PAD,
+              paddingBottom: DATE_TIME_LIST_EDGE_PAD,
+            }}
+          >
+            {options.map((option) => {
+              const selected = option.value === selectedValue;
+              return (
+                <View
+                  key={String(option.value)}
+                  style={[{ height: DATE_TIME_LIST_ITEM_HEIGHT }, WEB_ITEM_SNAP]}
+                >
+                  {children ? (
+                    children({ ...option, selected })
+                  ) : (
+                    <View accessibilityRole="button" accessibilityState={{ selected }}>
+                      {option.label}
+                    </View>
+                  )}
+                </View>
+              );
+            })}
+          </ScrollView>
+        </Comp>
+      </DateTimeListColumnContext.Provider>
+    );
+  },
+);
+
+DateTimeListColumn.displayName = 'DateTimeListColumn';

package/src/date-time-list/context.tsx

@@ -0,0 +1,45 @@
+import { createContext, useContext } from 'react';
+import type { DateTimeGranularity, DateTimeId } from '@cdx-ui/formatters';
+
+export type DateTimeListColumnType = 'date' | 'hour' | 'minute' | 'second' | 'period';
+
+export interface DateTimeListContextValue {
+  value?: DateTimeId;
+  onValueChange?: (value: DateTimeId) => void;
+  onUserInteract?: () => void;
+  granularity: DateTimeGranularity;
+  locale: string;
+  hour12: boolean;
+  disabled: boolean;
+  /** Earliest selectable date-time (`YYYY-MM-DDTHH:MM`). */
+  minValue?: DateTimeId;
+  /** Latest selectable date-time (`YYYY-MM-DDTHH:MM`). */
+  maxValue?: DateTimeId;
+}
+
+export const DateTimeListContext = createContext<DateTimeListContextValue | null>(null);
+
+export function useDateTimeListContext(): DateTimeListContextValue {
+  const ctx = useContext(DateTimeListContext);
+  if (!ctx) {
+    throw new Error('DateTimeList compound components must be used within DateTimeListRoot');
+  }
+  return ctx;
+}
+
+export interface DateTimeListColumnContextValue {
+  column: DateTimeListColumnType;
+  options: { value: string | number; label: string }[];
+  selectedValue?: string | number;
+  onSelect: (value: string | number) => void;
+}
+
+export const DateTimeListColumnContext = createContext<DateTimeListColumnContextValue | null>(null);
+
+export function useDateTimeListColumnContext(): DateTimeListColumnContextValue {
+  const ctx = useContext(DateTimeListColumnContext);
+  if (!ctx) {
+    throw new Error('DateTimeListColumn must be used within DateTimeListRoot column setup');
+  }
+  return ctx;
+}

package/src/date-time-list/index.ts

@@ -0,0 +1,16 @@
+export {
+  DateTimeListRoot,
+  DateTimeListColumn,
+  DATE_TIME_LIST_ITEM_HEIGHT,
+  DATE_TIME_LIST_VISIBLE_ITEMS,
+  DATE_TIME_LIST_HEIGHT,
+  DATE_TIME_LIST_EDGE_PAD,
+} from './DateTimeListRoot';
+export type { DateTimeListRootProps, DateTimeListColumnProps } from './DateTimeListRoot';
+export {
+  DateTimeListContext,
+  useDateTimeListContext,
+  useDateTimeListColumnContext,
+  type DateTimeListColumnType,
+  type DateTimeListContextValue,
+} from './context';