@cdx-ui/primitives 0.0.1-beta.98 → 0.1.0

package/src/tooltip/TooltipTrigger.tsx

@@ -0,0 +1,160 @@
+import { forwardRef, useCallback, type ComponentRef } from 'react';
+import { Platform, Pressable, 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 { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useTooltipContext } from './context';
+import type { ITooltipTriggerProps } from './types';
+
+export interface TooltipTriggerProps extends ITooltipTriggerProps {}
+
+export const TooltipTrigger = forwardRef<ComponentRef<typeof Pressable>, TooltipTriggerProps>(
+  (
+    {
+      asChild = true,
+      children,
+      onHoverIn,
+      onHoverOut,
+      onFocus,
+      onBlur,
+      onLongPress,
+      onPress,
+      onLayout,
+      ...props
+    },
+    ref,
+  ) => {
+    const {
+      open,
+      setOpen,
+      requestOpen,
+      requestClose,
+      isDisabled,
+      trigger,
+      triggerRef,
+      contentId,
+      triggerId,
+    } = useTooltipContext();
+
+    const mergedRef = mergeRefs(ref, triggerRef);
+    const { hoverProps, isHovered } = useHover({}, mergedRef);
+    const { focusProps, isFocused } = useFocus();
+
+    const handleOpen = useCallback(() => {
+      if (isDisabled) {
+        return;
+      }
+      requestOpen();
+    }, [isDisabled, requestOpen]);
+
+    const handleClose = useCallback(() => {
+      requestClose();
+    }, [requestClose]);
+
+    const isWeb = Platform.OS === 'web';
+    const usesLongPressOnNative = !isWeb && (trigger === 'hover' || trigger === 'focus');
+    const usesClickToggle = trigger === 'click';
+
+    const handlePress = composeEventHandlers(onPress, () => {
+      if (!usesClickToggle || isDisabled) {
+        return;
+      }
+      setOpen(!open);
+    });
+
+    const handleHoverIn = composeEventHandlers(
+      composeEventHandlers(onHoverIn, hoverProps.onHoverIn),
+      () => {
+        if (isWeb && trigger === 'hover') {
+          handleOpen();
+        }
+      },
+    );
+
+    const handleHoverOut = composeEventHandlers(
+      composeEventHandlers(onHoverOut, hoverProps.onHoverOut),
+      () => {
+        if (isWeb && trigger === 'hover') {
+          handleClose();
+        }
+      },
+    );
+
+    const handleFocus = composeEventHandlers(
+      composeEventHandlers(onFocus, focusProps.onFocus),
+      () => {
+        if (!isWeb) {
+          return;
+        }
+        if (trigger === 'focus' || trigger === 'hover') {
+          handleOpen();
+        }
+      },
+    );
+
+    const handleBlur = composeEventHandlers(composeEventHandlers(onBlur, focusProps.onBlur), () => {
+      if (!isWeb) {
+        return;
+      }
+      if (trigger === 'focus' || trigger === 'hover') {
+        handleClose();
+      }
+    });
+
+    const handleLongPress = composeEventHandlers(onLongPress, () => {
+      if (usesLongPressOnNative) {
+        handleOpen();
+      }
+    });
+
+    const webHoverProps =
+      isWeb && trigger === 'hover'
+        ? ({
+            onPointerEnter: handleHoverIn,
+            onPointerLeave: handleHoverOut,
+          } as const)
+        : {};
+
+    const webA11yProps = isWeb
+      ? ({
+          id: triggerId,
+          'aria-describedby': open ? contentId : undefined,
+          ...(trigger === 'click' ? { 'aria-expanded': open } : {}),
+        } as const)
+      : {};
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <Comp
+        ref={mergedRef}
+        disabled={isDisabled}
+        {...(props as PressableProps)}
+        {...webA11yProps}
+        {...focusProps}
+        {...webHoverProps}
+        onLayout={onLayout}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({
+            triggerHover: isHovered,
+            triggerFocus: isFocused,
+            disabled: isDisabled,
+          }),
+        )}
+        onHoverIn={handleHoverIn}
+        onHoverOut={handleHoverOut}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onLongPress={handleLongPress}
+        onPress={handlePress}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+TooltipTrigger.displayName = 'TooltipTrigger';

package/src/tooltip/context.tsx

@@ -0,0 +1,5 @@
+import { createContext } from '@cdx-ui/utils';
+import type { TooltipContextValue } from './types';
+
+export const [TooltipProvider, useTooltipContext] =
+  createContext<TooltipContextValue>('TooltipContext');

package/src/tooltip/getTooltipPosition.ts

@@ -0,0 +1,80 @@
+import { Platform, type ViewStyle } from 'react-native';
+import type { AnchorLayout } from '../overlay/useAnchorPosition';
+import {
+  getAnchoredOverlayPosition,
+  OVERLAY_PLACEMENTS,
+  type OverlayAlign,
+  type OverlayPlacement,
+  type OverlaySide,
+  type ResolvedOverlayPlacement,
+} from '../overlay/getAnchoredOverlayPosition';
+
+export const TOOLTIP_PLACEMENTS = OVERLAY_PLACEMENTS;
+
+export type TooltipPlacement = OverlayPlacement;
+export type TooltipTriggerMode = 'hover' | 'focus' | 'click';
+export type TooltipSide = OverlaySide;
+export type TooltipAlign = OverlayAlign;
+export type ResolvedTooltipPlacement = Readonly<ResolvedOverlayPlacement>;
+
+export const TOOLTIP_Z_INDEX = 9999;
+
+function getCompatibilityTransform({
+  side,
+  align,
+}: ResolvedTooltipPlacement): ViewStyle['transform'] {
+  if (side === 'top') {
+    return align === 'center'
+      ? ([{ translateX: '-50%' }, { translateY: '-100%' }] as ViewStyle['transform'])
+      : align === 'end'
+        ? ([{ translateX: '-100%' }, { translateY: '-100%' }] as ViewStyle['transform'])
+        : ([{ translateY: '-100%' }] as ViewStyle['transform']);
+  }
+
+  if (side === 'bottom') {
+    return align === 'center'
+      ? ([{ translateX: '-50%' }] as ViewStyle['transform'])
+      : align === 'end'
+        ? ([{ translateX: '-100%' }] as ViewStyle['transform'])
+        : undefined;
+  }
+
+  if (side === 'left') {
+    return align === 'center'
+      ? ([{ translateX: '-100%' }, { translateY: '-50%' }] as ViewStyle['transform'])
+      : align === 'end'
+        ? ([{ translateX: '-100%' }, { translateY: '-100%' }] as ViewStyle['transform'])
+        : ([{ translateX: '-100%' }] as ViewStyle['transform']);
+  }
+
+  return align === 'center'
+    ? ([{ translateY: '-50%' }] as ViewStyle['transform'])
+    : align === 'end'
+      ? ([{ translateY: '-100%' }] as ViewStyle['transform'])
+      : undefined;
+}
+
+export function getTooltipAnchorStyle(
+  anchor: AnchorLayout,
+  placement: TooltipPlacement,
+  offset: number,
+  viewport: { width: number; height: number },
+): { style: ViewStyle; resolved: ResolvedTooltipPlacement } {
+  const result = getAnchoredOverlayPosition(anchor, { width: 0, height: 0 }, viewport, {
+    placement,
+    offset,
+    collisionBehavior: 'none',
+  });
+  const resolved = result.resolvedPlacement;
+  const position = (Platform.OS === 'web' ? 'fixed' : 'absolute') as ViewStyle['position'];
+  return {
+    style: {
+      position,
+      left: result.style.left,
+      top: result.style.top,
+      zIndex: TOOLTIP_Z_INDEX,
+      transform: getCompatibilityTransform(resolved),
+    },
+    resolved,
+  };
+}

package/src/tooltip/index.ts

@@ -0,0 +1,19 @@
+export { TooltipProvider, useTooltipContext } from './context';
+export { TooltipRoot, type TooltipRootProps } from './TooltipRoot';
+export { TooltipTrigger, type TooltipTriggerProps } from './TooltipTrigger';
+export { TooltipContent, type TooltipContentProps } from './TooltipContent';
+export {
+  TOOLTIP_PLACEMENTS,
+  getTooltipAnchorStyle,
+  type TooltipPlacement,
+  type TooltipTriggerMode,
+  type TooltipSide,
+  type TooltipAlign,
+  type ResolvedTooltipPlacement,
+} from './getTooltipPosition';
+export type {
+  ITooltipProps,
+  ITooltipTriggerProps,
+  ITooltipContentProps,
+  TooltipContextValue,
+} from './types';

package/src/tooltip/types.ts

@@ -0,0 +1,85 @@
+import type { ComponentRef, ReactNode, RefObject } from 'react';
+import type { PressableProps, View, ViewProps } from 'react-native';
+import type {
+  ResolvedTooltipPlacement,
+  TooltipPlacement,
+  TooltipTriggerMode,
+} from './getTooltipPosition';
+
+export interface ITooltipProps extends Omit<ViewProps, 'children'> {
+  readonly children?: ReactNode;
+  readonly isDisabled?: boolean;
+  /**
+   * Milliseconds to wait before showing the tooltip.
+   * @default `0`
+   */
+  readonly enterDelay?: number;
+  /**
+   * Milliseconds to wait before hiding the tooltip.
+   * @default `0`
+   */
+  readonly leaveDelay?: number;
+  /**
+   * Controlled open state.
+   */
+  readonly isOpen?: boolean;
+  /**
+   * Uncontrolled initial open state.
+   * @default `false`
+   */
+  readonly defaultOpen?: boolean;
+  /**
+   * Called when the tooltip opens.
+   */
+  readonly onOpen?: () => void;
+  /**
+   * Called when the tooltip closes.
+   */
+  readonly onClose?: () => void;
+  /**
+   * Preferred placement relative to the trigger.
+   * @default `'top'`
+   */
+  readonly placement?: TooltipPlacement;
+  /**
+   * Distance in pixels between the tooltip and the trigger.
+   * @default `8`
+   */
+  readonly offset?: number;
+  /**
+   * Interaction that opens the tooltip. On web, `hover` opens on hover and focus; on native, long press.
+   * `focus` opens on focus (web) or long press (native). `click` toggles on press — on web, dismisses on outside click or Escape.
+   * @default `'hover'`
+   */
+  readonly trigger?: TooltipTriggerMode;
+}
+
+export interface TooltipContextValue {
+  readonly open: boolean;
+  readonly setOpen: (open: boolean) => void;
+  readonly requestOpen: () => void;
+  readonly requestClose: () => void;
+  readonly clearTimers: () => void;
+  readonly isDisabled: boolean;
+  readonly enterDelay: number;
+  readonly leaveDelay: number;
+  readonly placement: TooltipPlacement;
+  readonly offset: number;
+  readonly trigger: TooltipTriggerMode;
+  readonly triggerRef: RefObject<ComponentRef<typeof View> | null>;
+  readonly contentId: string;
+  readonly triggerId: string;
+  readonly resolvedPlacement: ResolvedTooltipPlacement | null;
+  readonly setResolvedPlacement: (placement: ResolvedTooltipPlacement) => void;
+}
+
+export interface ITooltipTriggerProps extends PressableProps {
+  /** When true, merges trigger props onto the single child element. */
+  readonly asChild?: boolean;
+  readonly children?: ReactNode;
+}
+
+export interface ITooltipContentProps extends ViewProps {
+  readonly asChild?: boolean;
+  readonly children?: ReactNode;
+}

package/src/utils/accessibleLabel.ts

@@ -0,0 +1,22 @@
+export interface AccessibleLabelProps {
+  accessibilityLabel?: string;
+  'aria-label'?: string;
+}
+
+export function resolveAccessibleLabel({
+  accessibilityLabel,
+  'aria-label': ariaLabel,
+}: AccessibleLabelProps): string | undefined {
+  return accessibilityLabel ?? ariaLabel;
+}
+
+export function accessibleLabelAttributes(label: string | undefined) {
+  if (label === undefined) {
+    return {};
+  }
+
+  return {
+    accessibilityLabel: label,
+    'aria-label': label,
+  };
+}

package/src/utils/assignRef.ts

@@ -0,0 +1,11 @@
+import type { ForwardedRef } from 'react';
+
+export function assignRef<T>(ref: ForwardedRef<T>, value: T | null) {
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+  if (ref) {
+    ref.current = value;
+  }
+}

package/src/utils/createPortal.ts

@@ -10,8 +10,10 @@ type CreatePortalFn = (children: React.ReactNode, container: Element) => React.R
  * `react-dom`, which would cause a build error on native platforms.
  */
 export const createPortalFn: CreatePortalFn | undefined = (() => {
-  if (Platform.OS !== 'web') return undefined;
   try {
+    if (Platform.OS !== 'web') {
+      return undefined;
+    }
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return (require('react-dom') as { createPortal: CreatePortalFn }).createPortal;
   } catch {

package/src/utils/createPortal.web.ts

@@ -0,0 +1,18 @@
+import type React from 'react';
+import { createPortal } from 'react-dom';
+
+type CreatePortalFn = (children: React.ReactNode, container: Element) => React.ReactPortal;
+
+/**
+ * Web implementation — statically imports `ReactDOM.createPortal`.
+ *
+ * The base (`.ts`) module resolves `react-dom` lazily via `require` so native
+ * bundles never reference it. That `require` is `undefined` in browser ESM
+ * bundles that don't transform mixed CommonJS/ESM (e.g. the docs site's Vite
+ * build), so the base module silently resolves `createPortalFn` to `undefined`
+ * there. That forces `OverlayContainer` onto its native `Modal` + Reanimated
+ * layout-animation path, leaving web overlays (Select, DatePicker) stuck at
+ * opacity 0. A static ESM import guarantees `createPortalFn` resolves on web
+ * regardless of the bundler's CommonJS interop.
+ */
+export const createPortalFn: CreatePortalFn = createPortal;

package/src/utils/domDataAttributes.ts

@@ -34,8 +34,9 @@ export function domDataAttributes(
 /**
  * Merges multiple sources of DOM data attributes into a single flat object of
  * `data-*` keys. Each source can be a `domDataAttributes()` output or any props
- * object — non-`data-*` keys are ignored. Later sources override earlier sources
- * on key conflicts.
+ * object. RNW `dataSet` objects are flattened first, then `data-*` keys on that
+ * same source are applied (explicit `data-*` wins). Later sources override
+ * earlier sources on key conflicts. Non-data keys are ignored.
  *
  * Use this when an element receives `data-*` attributes from more than one
  * source (e.g. a styled layer's `data-slot` and a primitive's interaction-state
@@ -49,6 +50,12 @@ export function mergeDomDataAttributes(
   const result: Record<string, string> = {};
   for (const source of sources) {
     if (!source) continue;
+
+    const dataSet = source.dataSet;
+    if (dataSet && typeof dataSet === 'object' && !Array.isArray(dataSet)) {
+      Object.assign(result, domDataAttributes(dataSet as Record<string, DomDataAttributeValue>));
+    }
+
     for (const key in source) {
       if (!key.startsWith('data-')) continue;
       const value = source[key];

package/src/utils/mapViewPropsToDom.ts

@@ -0,0 +1,125 @@
+/** RN View/Text/Pressable props that must not be forwarded to raw HTML elements. */
+const VIEW_PROPS_OMIT = new Set<string>([
+  'hitSlop',
+  'pressRetentionOffset',
+  'android_ripple',
+  'android_disableSound',
+  'unstable_pressDelay',
+  'onLongPress',
+  'delayLongPress',
+  'onPress',
+  'onPressIn',
+  'onPressOut',
+  'onHoverIn',
+  'onHoverOut',
+  'onLayout',
+  'onStartShouldSetResponder',
+  'onMoveShouldSetResponder',
+  'onResponderEnd',
+  'onResponderGrant',
+  'onResponderMove',
+  'onResponderReject',
+  'onResponderRelease',
+  'onResponderStart',
+  'onResponderTerminate',
+  'onResponderTerminationRequest',
+  'onStartShouldSetResponderCapture',
+  'onMoveShouldSetResponderCapture',
+  'pointerEvents',
+  'collapsable',
+  'needsOffscreenAlphaCompositing',
+  'shouldRasterizeIOS',
+  'removeClippedSubviews',
+  'focusable',
+  'accessible',
+  'accessibilityActions',
+  'accessibilityElementsHidden',
+  'accessibilityHint',
+  'accessibilityIgnoresInvertColors',
+  'accessibilityLabel',
+  'accessibilityLabelledBy',
+  'accessibilityLiveRegion',
+  'accessibilityRole',
+  'accessibilityState',
+  'accessibilityValue',
+  'accessibilityViewIsModal',
+  'importantForAccessibility',
+  'onAccessibilityAction',
+  'onAccessibilityEscape',
+  'onAccessibilityTap',
+  'nativeID',
+  'dataSet',
+  'testID',
+]);
+
+interface ViewPropsForDom {
+  testID?: string;
+  nativeID?: string;
+  accessibilityLabel?: string;
+  accessibilityLabelledBy?: string | string[];
+  accessibilityElementsHidden?: boolean;
+  accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
+}
+
+export interface MapViewPropsToDomOptions {
+  /** Host keys the caller applies itself (e.g. `onFocus` remapped to a DOM handler). */
+  extraOmit?: Iterable<string>;
+}
+
+/**
+ * Maps RN View/Text props onto DOM-safe attributes for raw HTML hosts.
+ * Strips RN-only props and translates `accessibilityLabel` / `testID` / `nativeID`
+ * to `aria-label` / `data-testid` / `id`. Consumer `dataSet` is omitted here —
+ * flatten and merge it with `mergeDomDataAttributes`.
+ */
+export function mapViewPropsToDom(
+  props: object,
+  options?: MapViewPropsToDomOptions,
+): Record<string, unknown> {
+  const {
+    testID,
+    nativeID,
+    accessibilityLabel,
+    accessibilityLabelledBy,
+    accessibilityElementsHidden,
+    accessibilityLiveRegion,
+    ...rest
+  } = props as ViewPropsForDom & Record<string, unknown>;
+
+  const omit = options?.extraOmit
+    ? new Set([...VIEW_PROPS_OMIT, ...options.extraOmit])
+    : VIEW_PROPS_OMIT;
+
+  const domProps = Object.fromEntries(
+    Object.entries(rest).filter(([key]) => !omit.has(key)),
+  ) as Record<string, unknown>;
+
+  if (domProps['aria-label'] == null && accessibilityLabel != null) {
+    domProps['aria-label'] = accessibilityLabel;
+  }
+
+  const labelledBy = Array.isArray(accessibilityLabelledBy)
+    ? accessibilityLabelledBy.join(' ')
+    : accessibilityLabelledBy;
+  if (domProps['aria-labelledby'] == null && labelledBy != null) {
+    domProps['aria-labelledby'] = labelledBy;
+  }
+
+  if (testID != null) {
+    domProps['data-testid'] = testID;
+  }
+
+  if (domProps.id == null && nativeID != null) {
+    domProps.id = nativeID;
+  }
+
+  if (accessibilityElementsHidden === true) {
+    domProps['aria-hidden'] = true;
+  }
+
+  if (accessibilityLiveRegion != null && accessibilityLiveRegion !== 'none') {
+    domProps['aria-live'] = accessibilityLiveRegion;
+  }
+
+  return domProps;
+}