@cdx-ui/primitives 0.0.1-beta.99 → 0.1.1

package/src/menu/useMenuTrigger.ts

@@ -0,0 +1,161 @@
+import { useCallback, useMemo, useRef, type ForwardedRef, type RefCallback } from 'react';
+import { type GestureResponderEvent, type PressableProps } from 'react-native';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import { useFocus } from '@react-native-aria/focus';
+import { useHover } from '@react-native-aria/interactions';
+import type { InteractionState } from '../types';
+import { useMenuOverlayContext } from './overlayContext';
+
+export interface UseMenuTriggerOptions {
+  asChild?: boolean;
+  onPress?: PressableProps['onPress'];
+  onHoverIn?: PressableProps['onHoverIn'];
+  onHoverOut?: PressableProps['onHoverOut'];
+  onFocus?: (...args: unknown[]) => unknown;
+  onBlur?: (...args: unknown[]) => unknown;
+  onKeyDown?: (e: KeyboardEvent) => void;
+}
+
+export interface MenuTriggerAriaProps {
+  role: 'button';
+  id: string;
+  'aria-haspopup': 'menu';
+  'aria-expanded': boolean;
+  'aria-controls': string;
+  disabled: boolean;
+}
+
+export interface UseMenuTriggerReturn {
+  ariaProps: MenuTriggerAriaProps;
+  interactionState: Pick<InteractionState, 'hover' | 'focus' | 'disabled'>;
+  mergedRef: RefCallback<unknown>;
+  handlers: {
+    onPress: (e: GestureResponderEvent) => void;
+    onHoverIn: NonNullable<PressableProps['onHoverIn']>;
+    onHoverOut: NonNullable<PressableProps['onHoverOut']>;
+    onFocus: (...args: unknown[]) => unknown;
+    onBlur: (...args: unknown[]) => unknown;
+    onKeyDown: (e: KeyboardEvent) => void;
+  };
+}
+
+export function useMenuTrigger(
+  forwardedRef: ForwardedRef<unknown>,
+  options: UseMenuTriggerOptions,
+): UseMenuTriggerReturn {
+  const {
+    onPress: consumerOnPress,
+    onHoverIn: consumerOnHoverIn,
+    onHoverOut: consumerOnHoverOut,
+    onFocus: consumerOnFocus,
+    onBlur: consumerOnBlur,
+    onKeyDown: consumerOnKeyDown,
+  } = options;
+
+  const { open, setOpen, closeMenu, disabled, triggerRef, triggerId, menuId, focusOnOpenRef } =
+    useMenuOverlayContext();
+  const pendingKeyboardOpenRef = useRef<'first' | 'last' | null>(null);
+
+  const { isFocused, focusProps } = useFocus();
+  const { isHovered, hoverProps } = useHover();
+  const clearPendingKeyboardOpen = useCallback(() => {
+    pendingKeyboardOpenRef.current = null;
+  }, []);
+
+  const handlePress = useCallback(
+    (_e: GestureResponderEvent) => {
+      if (disabled) {
+        return;
+      }
+
+      if (open) {
+        pendingKeyboardOpenRef.current = null;
+        closeMenu('trigger');
+        return;
+      }
+
+      focusOnOpenRef.current = pendingKeyboardOpenRef.current ?? 'menu';
+      pendingKeyboardOpenRef.current = null;
+      setOpen(true);
+    },
+    [closeMenu, disabled, focusOnOpenRef, open, setOpen],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      if (disabled) {
+        return;
+      }
+
+      switch (e.key) {
+        case 'Enter':
+        case ' ': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = 'first';
+          break;
+        }
+        case 'ArrowDown': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = null;
+          focusOnOpenRef.current = 'first';
+          setOpen(true);
+          break;
+        }
+        case 'ArrowUp': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = null;
+          focusOnOpenRef.current = 'last';
+          setOpen(true);
+          break;
+        }
+      }
+    },
+    [disabled, focusOnOpenRef, setOpen],
+  );
+
+  const interactionState = useMemo(
+    () => ({
+      hover: !!isHovered,
+      focus: !!isFocused,
+      disabled: !!disabled,
+    }),
+    [isHovered, isFocused, disabled],
+  );
+
+  const mergedRef = mergeRefs(forwardedRef, triggerRef);
+
+  const ariaProps: MenuTriggerAriaProps = {
+    role: 'button',
+    id: triggerId,
+    'aria-haspopup': 'menu',
+    'aria-expanded': open,
+    'aria-controls': menuId,
+    disabled,
+  };
+
+  const handlers = {
+    onPress: composeEventHandlers(
+      consumerOnPress,
+      handlePress,
+    ) as UseMenuTriggerReturn['handlers']['onPress'],
+    onHoverIn: composeEventHandlers(
+      consumerOnHoverIn,
+      hoverProps.onHoverIn,
+    ) as UseMenuTriggerReturn['handlers']['onHoverIn'],
+    onHoverOut: composeEventHandlers(
+      consumerOnHoverOut,
+      hoverProps.onHoverOut,
+    ) as UseMenuTriggerReturn['handlers']['onHoverOut'],
+    onFocus: composeEventHandlers(consumerOnFocus, focusProps.onFocus),
+    onBlur: composeEventHandlers(
+      composeEventHandlers(consumerOnBlur, focusProps.onBlur),
+      clearPendingKeyboardOpen,
+    ),
+    onKeyDown: composeEventHandlers(
+      consumerOnKeyDown,
+      handleKeyDown,
+    ) as UseMenuTriggerReturn['handlers']['onKeyDown'],
+  };
+
+  return { ariaProps, interactionState, mergedRef, handlers };
+}

package/src/month-calendar/MonthCalendarCell.tsx

@@ -0,0 +1,53 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { Pressable, View, type ViewProps } from 'react-native';
+import { compareMonthIds, formatMonthId, type MonthId } from '@cdx-ui/formatters';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useMonthCalendarContext } from './context';
+
+export interface MonthCalendarCellProps extends Omit<ViewProps, 'children'> {
+  month: number;
+  asChild?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export const MonthCalendarCell = forwardRef<ComponentRef<typeof View>, MonthCalendarCellProps>(
+  ({ asChild, month, className, style, children, ...props }, ref) => {
+    const { visibleYear, value, onValueChange, disabled, minValue, maxValue } =
+      useMonthCalendarContext();
+    const monthId: MonthId = formatMonthId({ year: visibleYear, month });
+    const selected = value === monthId;
+    const outOfRange =
+      (minValue != null && compareMonthIds(monthId, minValue) < 0) ||
+      (maxValue != null && compareMonthIds(monthId, maxValue) > 0);
+    const cellDisabled = disabled || outOfRange;
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <Comp
+        ref={ref}
+        className={className}
+        style={style}
+        accessibilityRole="button"
+        accessibilityState={{ selected, disabled: cellDisabled }}
+        disabled={cellDisabled}
+        onPress={() => {
+          if (cellDisabled) {
+            return;
+          }
+          onValueChange?.(monthId);
+        }}
+        {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ selected, disabled: cellDisabled, slot: 'month-calendar-cell' }),
+        )}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+MonthCalendarCell.displayName = 'MonthCalendarCell';

package/src/month-calendar/MonthCalendarRoot.tsx

@@ -0,0 +1,153 @@
+import { forwardRef, useEffect, useMemo, useRef, type ComponentRef, type ReactNode } from 'react';
+import { View, type ViewProps } from 'react-native';
+import {
+  parseMonthId,
+  resolveDateComponentLabels,
+  type DateComponentLabels,
+  type MonthId,
+} 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 { MonthCalendarContext, type MonthCalendarView } from './context';
+
+export interface MonthCalendarRootProps extends Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  value?: MonthId;
+  defaultValue?: MonthId;
+  /** Called with the new `MonthId`, or `undefined` when the selection is cleared. */
+  onValueChange?: (value: MonthId | undefined) => void;
+  view?: MonthCalendarView;
+  defaultView?: MonthCalendarView;
+  onViewChange?: (view: MonthCalendarView) => void;
+  visibleYear?: number;
+  defaultVisibleYear?: number;
+  onVisibleYearChange?: (year: number) => void;
+  disabled?: boolean;
+  /** Earliest selectable month. Build with `monthId(...)` from `@cdx-ui/formatters`. */
+  minValue?: MonthId;
+  /** Latest selectable month. Build with `monthId(...)` from `@cdx-ui/formatters`. */
+  maxValue?: MonthId;
+  locale?: string;
+  labels?: Partial<DateComponentLabels>;
+  /** Accessible name for the month-calendar region. */
+  accessibilityLabel?: string;
+}
+
+export const MonthCalendarRoot = forwardRef<ComponentRef<typeof View>, MonthCalendarRootProps>(
+  (
+    {
+      asChild,
+      children,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      view: viewProp,
+      defaultView = 'month',
+      onViewChange,
+      visibleYear: visibleYearProp,
+      defaultVisibleYear,
+      onVisibleYearChange,
+      disabled = false,
+      minValue,
+      maxValue,
+      locale = 'en-US',
+      labels: labelsProp,
+      accessibilityLabel: accessibilityLabelProp,
+      'aria-label': ariaLabelProp,
+      ...props
+    },
+    ref,
+  ) => {
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const accessibilityLabel = resolveAccessibleLabel({
+      accessibilityLabel: accessibilityLabelProp,
+      'aria-label': ariaLabelProp,
+    });
+    const [value, setValue] = useControllableState<MonthId | undefined>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: onValueChange,
+    });
+
+    const parsed = value ? parseMonthId(value) : null;
+    const [view, setView] = useControllableState<MonthCalendarView>({
+      prop: viewProp,
+      defaultProp: defaultView,
+      onChange: onViewChange,
+    });
+
+    const [visibleYear, setVisibleYear] = useControllableState<number>({
+      prop: visibleYearProp,
+      defaultProp: defaultVisibleYear ?? parsed?.year ?? new Date().getFullYear(),
+      onChange: onVisibleYearChange,
+    });
+
+    const prevValueRef = useRef(value);
+    useEffect(() => {
+      if (visibleYearProp !== undefined) {
+        prevValueRef.current = value;
+        return;
+      }
+      if (value === undefined || prevValueRef.current === value) {
+        prevValueRef.current = value;
+        return;
+      }
+      prevValueRef.current = value;
+      const nextParsed = parseMonthId(value);
+      if (nextParsed) {
+        setVisibleYear(nextParsed.year);
+      }
+    }, [setVisibleYear, value, visibleYearProp]);
+
+    const contextValue = useMemo(
+      () => ({
+        value,
+        onValueChange: setValue,
+        view: view ?? 'month',
+        onViewChange: setView,
+        visibleYear: visibleYear ?? new Date().getFullYear(),
+        onVisibleYearChange: setVisibleYear,
+        disabled,
+        minValue,
+        maxValue,
+        locale,
+        labels,
+      }),
+      [
+        value,
+        setValue,
+        view,
+        setView,
+        visibleYear,
+        setVisibleYear,
+        disabled,
+        minValue,
+        maxValue,
+        locale,
+        labels,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <MonthCalendarContext.Provider value={contextValue}>
+        <Comp
+          ref={ref}
+          accessibilityRole="none"
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ disabled }))}
+          {...accessibleLabelAttributes(accessibilityLabel)}
+        >
+          {children}
+        </Comp>
+      </MonthCalendarContext.Provider>
+    );
+  },
+);
+
+MonthCalendarRoot.displayName = 'MonthCalendarRoot';

package/src/month-calendar/MonthCalendarYearCell.tsx

@@ -0,0 +1,54 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { Pressable, View, type ViewProps } from 'react-native';
+import { parseMonthId } from '@cdx-ui/formatters';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useMonthCalendarContext } from './context';
+
+export interface MonthCalendarYearCellProps extends Omit<ViewProps, 'children'> {
+  year: number;
+  asChild?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export const MonthCalendarYearCell = forwardRef<
+  ComponentRef<typeof View>,
+  MonthCalendarYearCellProps
+>(({ asChild, year, className, style, children, ...props }, ref) => {
+  const { visibleYear, onVisibleYearChange, onViewChange, disabled, minValue, maxValue } =
+    useMonthCalendarContext();
+  const selected = visibleYear === year;
+  const minYear = minValue ? parseMonthId(minValue)?.year : undefined;
+  const maxYear = maxValue ? parseMonthId(maxValue)?.year : undefined;
+  const outOfRange = (minYear != null && year < minYear) || (maxYear != null && year > maxYear);
+  const cellDisabled = disabled || outOfRange;
+  const Comp = asChild ? Slot : Pressable;
+
+  return (
+    <Comp
+      ref={ref}
+      className={className}
+      style={style}
+      accessibilityRole="button"
+      accessibilityState={{ selected, disabled: cellDisabled }}
+      disabled={cellDisabled}
+      onPress={() => {
+        if (cellDisabled) {
+          return;
+        }
+        onVisibleYearChange(year);
+        onViewChange('month');
+      }}
+      {...props}
+      {...mergeDataAttributes(
+        props,
+        dataAttributes({ selected, disabled: cellDisabled, slot: 'month-calendar-year-cell' }),
+      )}
+    >
+      {children}
+    </Comp>
+  );
+});
+
+MonthCalendarYearCell.displayName = 'MonthCalendarYearCell';

package/src/month-calendar/context.tsx

@@ -0,0 +1,30 @@
+import { createContext, useContext } from 'react';
+import type { DateComponentLabels, MonthId } from '@cdx-ui/formatters';
+
+export type MonthCalendarView = 'month' | 'year';
+
+export interface MonthCalendarContextValue {
+  value?: MonthId;
+  onValueChange?: (value: MonthId | undefined) => void;
+  view: MonthCalendarView;
+  onViewChange: (view: MonthCalendarView) => void;
+  visibleYear: number;
+  onVisibleYearChange: (year: number) => void;
+  disabled: boolean;
+  /** Earliest selectable month (`YYYY-MM-01`). Months before this are disabled. */
+  minValue?: MonthId;
+  /** Latest selectable month (`YYYY-MM-01`). Months after this are disabled. */
+  maxValue?: MonthId;
+  locale: string;
+  labels: DateComponentLabels;
+}
+
+export const MonthCalendarContext = createContext<MonthCalendarContextValue | null>(null);
+
+export function useMonthCalendarContext(): MonthCalendarContextValue {
+  const ctx = useContext(MonthCalendarContext);
+  if (!ctx) {
+    throw new Error('MonthCalendar compound components must be used within MonthCalendarRoot');
+  }
+  return ctx;
+}

package/src/month-calendar/index.ts

@@ -0,0 +1,6 @@
+export { MonthCalendarRoot } from './MonthCalendarRoot';
+export type { MonthCalendarRootProps } from './MonthCalendarRoot';
+export { MonthCalendarCell } from './MonthCalendarCell';
+export { MonthCalendarYearCell } from './MonthCalendarYearCell';
+export { useMonthCalendarContext } from './context';
+export type { MonthCalendarView } from './context';

package/src/month-picker/MonthPickerRoot.tsx

@@ -0,0 +1,183 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import type { DateComponentLabels, MonthId } from '@cdx-ui/formatters';
+import { resolveDateComponentLabels } from '@cdx-ui/formatters';
+import { mergeRefs, useControllableState } from '@cdx-ui/utils';
+import { DateFieldRoot } from '../date-field/DateFieldRoot';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { PickerSurfaceType } from '../date-picker/context';
+import { MonthPickerContext } from './context';
+
+export interface MonthPickerRootProps extends Omit<ViewProps, 'children'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  value?: MonthId;
+  defaultValue?: MonthId;
+  /** Called with the new `MonthId`, or `undefined` when the selection is cleared. */
+  onValueChange?: (value: MonthId | undefined) => void;
+  /** Controlled open state. Use `defaultOpen` for the uncontrolled variant. */
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  isDisabled?: boolean;
+  isReadOnly?: boolean;
+  isInvalid?: boolean;
+  isRequired?: boolean;
+  /** Earliest selectable month, applied to the embedded calendar. Build with `monthId(...)`. */
+  minValue?: MonthId;
+  /** Latest selectable month, applied to the embedded calendar. Build with `monthId(...)`. */
+  maxValue?: MonthId;
+  name?: string;
+  locale?: string;
+  labels?: Partial<DateComponentLabels>;
+}
+
+export const MonthPickerRoot = forwardRef<ComponentRef<typeof View>, MonthPickerRootProps>(
+  (
+    {
+      asChild,
+      children,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      isOpen: openProp,
+      defaultOpen = false,
+      onOpenChange,
+      isDisabled: disabled = false,
+      isReadOnly,
+      isInvalid,
+      isRequired,
+      minValue,
+      maxValue,
+      locale = 'en-US',
+      labels: labelsProp,
+      ...props
+    },
+    ref,
+  ) => {
+    const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const [value, setValue] = useControllableState<MonthId | undefined>({
+      prop: valueProp,
+      defaultProp: defaultValue,
+      onChange: onValueChange,
+    });
+
+    const [open, setOpenState] = useControllableState<boolean>({
+      prop: openProp,
+      defaultProp: defaultOpen,
+      onChange: onOpenChange,
+    });
+
+    const [draftValue, setDraftValue] = useState<MonthId | undefined>(value);
+
+    const surfacesRef = useRef<Set<PickerSurfaceType>>(new Set());
+    const anchorRef = useRef<ComponentRef<typeof View>>(null);
+    const triggerRef = useRef<ComponentRef<typeof View>>(null);
+
+    const setOpen = useCallback(
+      (next: boolean) => {
+        if (disabled && next) {
+          return;
+        }
+        if (next) {
+          setDraftValue(value);
+        }
+        setOpenState(next);
+      },
+      [disabled, setOpenState, value],
+    );
+
+    const registerSurface = useCallback((type: PickerSurfaceType) => {
+      if (surfacesRef.current.has(type)) {
+        return;
+      }
+      surfacesRef.current.add(type);
+      if (surfacesRef.current.size > 1) {
+        console.warn(
+          '[Forge UI] MonthPicker: multiple presentation surfaces detected. Use only one of Popover, Dialog, or BottomSheet.',
+        );
+      }
+    }, []);
+
+    useEffect(() => {
+      setDraftValue(value);
+    }, [value]);
+
+    useEffect(() => {
+      if (!open) {
+        surfacesRef.current.clear();
+      }
+    }, [open]);
+
+    const contextValue = useMemo(
+      () => ({
+        value,
+        onValueChange: setValue,
+        draftValue,
+        setDraftValue,
+        open: open ?? false,
+        setOpen,
+        disabled,
+        minValue,
+        maxValue,
+        locale,
+        labels,
+        registerSurface,
+        anchorRef,
+        triggerRef,
+      }),
+      [
+        value,
+        setValue,
+        draftValue,
+        open,
+        setOpen,
+        disabled,
+        minValue,
+        maxValue,
+        locale,
+        labels,
+        registerSurface,
+      ],
+    );
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <MonthPickerContext.Provider value={contextValue}>
+        <Comp
+          ref={mergeRefs(ref, anchorRef)}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ disabled, open }))}
+        >
+          <DateFieldRoot
+            value={value}
+            onValueChange={(next) => setValue(next as MonthId | undefined)}
+            mode="month"
+            locale={locale}
+            labels={labelsProp}
+            isDisabled={disabled}
+            isReadOnly={isReadOnly}
+            isInvalid={isInvalid}
+            isRequired={isRequired}
+          >
+            {children}
+          </DateFieldRoot>
+        </Comp>
+      </MonthPickerContext.Provider>
+    );
+  },
+);
+
+MonthPickerRoot.displayName = 'MonthPickerRoot';

package/src/month-picker/context.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext, type RefObject } from 'react';
+import type { View } from 'react-native';
+import type { DateComponentLabels, MonthId } from '@cdx-ui/formatters';
+import type { PickerSurfaceType } from '../date-picker/context';
+
+export interface MonthPickerContextValue {
+  value?: MonthId;
+  onValueChange?: (value: MonthId | undefined) => void;
+  draftValue?: MonthId;
+  setDraftValue: (value: MonthId | undefined) => void;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  disabled: boolean;
+  minValue?: MonthId;
+  maxValue?: MonthId;
+  locale: string;
+  labels: DateComponentLabels;
+  registerSurface: (type: PickerSurfaceType) => void;
+  anchorRef: RefObject<View | null>;
+  triggerRef: RefObject<View | null>;
+}
+
+export const MonthPickerContext = createContext<MonthPickerContextValue | null>(null);
+
+export function useMonthPickerContext(): MonthPickerContextValue {
+  const ctx = useContext(MonthPickerContext);
+  if (!ctx) {
+    throw new Error('MonthPicker compound components must be used within MonthPickerRoot');
+  }
+  return ctx;
+}

package/src/month-picker/index.ts

@@ -0,0 +1,3 @@
+export { MonthPickerRoot } from './MonthPickerRoot';
+export type { MonthPickerRootProps } from './MonthPickerRoot';
+export { MonthPickerContext, useMonthPickerContext, type MonthPickerContextValue } from './context';