@cdx-ui/components 0.2.2 → 0.2.4

package/src/components/Menu/index.tsx

@@ -35,6 +35,7 @@ import {
   type IMenuTriggerProps,
 } from '@cdx-ui/primitives';
 import { cn, ParentContext, useParentContext, useStyleContext } from '@cdx-ui/utils';
+import { ScrollShadow } from '../ScrollShadow';
 import { Icon, type IconProps } from '../Icon';
 import { checkboxIconVariants, checkboxIndicatorVariants } from '../Checkbox/styles';
 import { radioIndicatorVariants, radioInnerDotVariants } from '../Radio/styles';
@@ -98,7 +99,10 @@ const useMenuItemStyleValue = (
 // =============================================================================
 
 export interface MenuProps extends ViewProps, IMenuOverlayRootProps {
+  /** Additional Uniwind/Tailwind classes, merged after the root's own styles. */
   className?: string;
+  /** The `Menu.Trigger` and `Menu.Popup`. */
+  children?: ReactNode;
 }
 
 const MenuOverlayRoot = forwardRef<View, MenuProps>(
@@ -122,7 +126,9 @@ MenuOverlayRoot.displayName = 'Menu';
 // =============================================================================
 
 export interface MenuTriggerProps extends IMenuTriggerProps {
+  /** Additional Uniwind/Tailwind classes, merged after the trigger's own styles. */
   className?: string;
+  /** Trigger content (or the element to render when `asChild` is set). */
   children?: ReactNode;
 }
 
@@ -147,7 +153,9 @@ MenuTrigger.displayName = 'Menu.Trigger';
 // =============================================================================
 
 export interface MenuPopupProps extends IMenuPopupProps {
+  /** Additional Uniwind/Tailwind classes, merged after the popup's own styles. */
   className?: string;
+  /** Popup content, typically a `Menu.Content`. */
   children?: ReactNode;
 }
 
@@ -178,8 +186,16 @@ MenuPopup.displayName = 'Menu.Popup';
 // =============================================================================
 
 export interface MenuContentProps
-  extends ViewProps, Omit<IMenuProps, 'scrollable'>, MenuRootVariantProps {
+  extends ViewProps, Omit<IMenuProps, 'scrollable'>, Omit<MenuRootVariantProps, 'scrollable'> {
+  /** Additional Uniwind/Tailwind classes, merged after the menu surface's own styles. */
   className?: string;
+  /**
+   * Caps the surface height and scrolls its items. Content inside a `Menu.Popup` always scrolls.
+   * @default false
+   */
+  scrollable?: MenuRootVariantProps['scrollable'];
+  /** The menu's items, groups and separators. */
+  children?: ReactNode;
   /** Visual-only surface without menu semantics (e.g. inside Select listbox). */
   asSurface?: boolean;
 }
@@ -207,14 +223,16 @@ const MenuContent = forwardRef<View, MenuContentProps>(
       : mergeDataAttributes(props, dataAttributes({ slot: 'menu-content' }));
 
     const content = shouldScroll ? (
-      <ScrollView
-        className="shrink"
-        style={[MENU_SCROLL_STYLE, constrainedStyle]}
-        scrollEventThrottle={16}
-        nestedScrollEnabled
-      >
-        {children}
-      </ScrollView>
+      <ScrollShadow className="shrink" style={constrainedStyle} surface="primary">
+        <ScrollView
+          className="shrink"
+          style={[MENU_SCROLL_STYLE, constrainedStyle]}
+          scrollEventThrottle={16}
+          nestedScrollEnabled
+        >
+          {children}
+        </ScrollView>
+      </ScrollShadow>
     ) : (
       children
     );
@@ -241,14 +259,28 @@ MenuContent.displayName = 'Menu.Content';
 // ITEM
 // =============================================================================
 
-export interface MenuItemProps extends Omit<MenuItemVariantProps, 'color'>, IMenuItemProps {
+export interface MenuItemProps
+  extends Omit<MenuItemVariantProps, 'color' | 'inset' | 'layout'>, IMenuItemProps {
+  /** Render the consumer's child element in place of the default `Pressable` host. */
   asChild?: boolean;
   /**
    * Color theme applied to the item content and interaction states.
    * @default 'neutral'
    */
   color?: 'neutral' | 'danger';
+  /**
+   * Indents the item content so its label lines up with items that have a leading icon.
+   * @default false
+   */
+  inset?: MenuItemVariantProps['inset'];
+  /**
+   * Set automatically: `filter` when the item contains a `Menu.ItemControl` or `Menu.ItemAction`.
+   * @internal
+   */
+  layout?: MenuItemVariantProps['layout'];
+  /** Additional Uniwind/Tailwind classes, merged after the item's own styles. */
   className?: string;
+  /** Item content, typically a `Menu.ItemLabel` with optional icon, shortcut and indicator slots. */
   children?: ReactNode;
 }
 
@@ -279,10 +311,27 @@ const MenuItem = forwardRef<View, MenuItemProps>(
 MenuItem.displayName = 'Menu.Item';
 
 export interface MenuCheckboxItemProps
-  extends Omit<MenuItemVariantProps, 'color'>, IMenuCheckboxItemProps {
+  extends Omit<MenuItemVariantProps, 'color' | 'inset' | 'layout'>, IMenuCheckboxItemProps {
+  /** Render the consumer's child element in place of the default `Pressable` host. */
   asChild?: boolean;
+  /**
+   * Color theme applied to the item content and interaction states.
+   * @default 'neutral'
+   */
   color?: 'neutral' | 'danger';
+  /**
+   * Indents the item content so its label lines up with items that have a leading icon.
+   * @default false
+   */
+  inset?: MenuItemVariantProps['inset'];
+  /**
+   * Set automatically: `filter` when the item contains a `Menu.ItemControl` or `Menu.ItemAction`.
+   * @internal
+   */
+  layout?: MenuItemVariantProps['layout'];
+  /** Additional Uniwind/Tailwind classes, merged after the item's own styles. */
   className?: string;
+  /** Item content, typically a `Menu.ItemLabel` with optional icon, shortcut and indicator slots. */
   children?: ReactNode;
 }
 
@@ -311,8 +360,11 @@ const MenuCheckboxItem = forwardRef<View, MenuCheckboxItemProps>(
 MenuCheckboxItem.displayName = 'Menu.CheckboxItem';
 
 export interface MenuRadioGroupProps extends IMenuRadioGroupProps {
+  /** Render the consumer's child element in place of the default `View` host. */
   asChild?: boolean;
+  /** Additional Uniwind/Tailwind classes, merged after the group's own styles. */
   className?: string;
+  /** The `Menu.RadioItem` options in the group. */
   children?: ReactNode;
 }
 
@@ -334,10 +386,27 @@ const MenuRadioGroup = forwardRef<View, MenuRadioGroupProps>(
 MenuRadioGroup.displayName = 'Menu.RadioGroup';
 
 export interface MenuRadioItemProps
-  extends Omit<MenuItemVariantProps, 'color'>, IMenuRadioItemProps {
+  extends Omit<MenuItemVariantProps, 'color' | 'inset' | 'layout'>, IMenuRadioItemProps {
+  /** Render the consumer's child element in place of the default `Pressable` host. */
   asChild?: boolean;
+  /**
+   * Color theme applied to the item content and interaction states.
+   * @default 'neutral'
+   */
   color?: 'neutral' | 'danger';
+  /**
+   * Indents the item content so its label lines up with items that have a leading icon.
+   * @default false
+   */
+  inset?: MenuItemVariantProps['inset'];
+  /**
+   * Set automatically: `filter` when the item contains a `Menu.ItemControl` or `Menu.ItemAction`.
+   * @internal
+   */
+  layout?: MenuItemVariantProps['layout'];
+  /** Additional Uniwind/Tailwind classes, merged after the item's own styles. */
   className?: string;
+  /** Item content, typically a `Menu.ItemLabel` with optional icon, shortcut and indicator slots. */
   children?: ReactNode;
 }
 
@@ -383,8 +452,12 @@ MenuRadioItem.displayName = 'Menu.RadioItem';
 // =============================================================================
 
 export interface MenuItemLabelProps extends TextProps {
+  /** Render the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
+  /** Additional Uniwind/Tailwind classes, merged after the label's own styles. */
   className?: string;
+  /** Label text. */
+  children?: ReactNode;
   /** Checked state when used outside a selectable Menu item (e.g. `Select.ItemLabel`). */
   isChecked?: boolean;
 }
@@ -423,10 +496,18 @@ const MenuItemLabel = forwardRef<Text, MenuItemLabelProps>(
 MenuItemLabel.displayName = 'Menu.ItemLabel';
 
 export interface MenuItemIconProps extends Omit<IconProps, 'as' | 'children' | 'color'> {
+  /** Render the consumer's child element in place of the icon. */
   asChild?: boolean;
+  /** The `@cdx-ui/icons` component to render. */
   as?: IconProps['as'];
+  /**
+   * Side of the label the icon sits on; sets the spacing between them.
+   * @default 'leading'
+   */
   position?: IconSlotPosition;
+  /** Additional Uniwind/Tailwind classes, merged after the icon's own styles. */
   className?: string;
+  /** The element to render when `asChild` is set. */
   children?: ReactNode;
 }
 
@@ -482,8 +563,12 @@ const MenuItemIcon = ({
 MenuItemIcon.displayName = 'Menu.ItemIcon';
 
 export interface MenuItemShortcutProps extends TextProps {
+  /** Render the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
+  /** Additional Uniwind/Tailwind classes, merged after the shortcut's own styles. */
   className?: string;
+  /** Shortcut hint text, such as `⌘C`. */
+  children?: ReactNode;
 }
 
 const MenuItemShortcut = forwardRef<Text, MenuItemShortcutProps>(
@@ -509,11 +594,23 @@ const MenuItemShortcut = forwardRef<Text, MenuItemShortcutProps>(
 MenuItemShortcut.displayName = 'Menu.ItemShortcut';
 
 export interface MenuItemIndicatorProps extends Omit<IconProps, 'as' | 'children' | 'color'> {
+  /** Render the consumer's child element in place of the icon. */
   asChild?: boolean;
+  /**
+   * The `@cdx-ui/icons` component to render.
+   * @default Check
+   */
   as?: IconProps['as'];
+  /** Shows the indicator. Defaults to the checked state of the enclosing item. */
   isChecked?: boolean;
+  /**
+   * Side of the label the indicator sits on; sets the spacing between them.
+   * @default 'trailing'
+   */
   position?: IconSlotPosition;
+  /** Additional Uniwind/Tailwind classes, merged after the indicator's own styles. */
   className?: string;
+  /** The element to render when `asChild` is set. */
   children?: ReactNode;
 }
 
@@ -575,8 +672,12 @@ MenuItemIndicator.displayName = 'Menu.ItemIndicator';
 // =============================================================================
 
 export interface MenuSectionLabelProps extends TextProps {
+  /** Render the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
+  /** Additional Uniwind/Tailwind classes, merged after the section label's own styles. */
   className?: string;
+  /** Section heading text. */
+  children?: ReactNode;
 }
 
 const MenuSectionLabel = forwardRef<Text, MenuSectionLabelProps>(
@@ -601,7 +702,10 @@ const MenuSectionLabel = forwardRef<Text, MenuSectionLabelProps>(
 MenuSectionLabel.displayName = 'Menu.SectionLabel';
 
 export interface MenuSeparatorProps extends ViewProps {
+  /** Additional Uniwind/Tailwind classes, merged after the separator's own styles. */
   className?: string;
+  /** Not rendered; the separator draws its own line. */
+  children?: ReactNode;
 }
 
 const MenuSeparator = forwardRef<View, MenuSeparatorProps>(
@@ -630,8 +734,11 @@ MenuSeparator.displayName = 'Menu.Separator';
 // =============================================================================
 
 export interface MenuGroupHeaderProps extends ViewProps {
+  /** Render the consumer's child element in place of the default `View` host. */
   asChild?: boolean;
+  /** Additional Uniwind/Tailwind classes, merged after the group header's own styles. */
   className?: string;
+  /** Header content, typically a `Menu.ItemLabel` and an optional `Menu.ItemAction`. */
   children?: ReactNode;
 }
 
@@ -666,7 +773,9 @@ const MenuGroupHeader = forwardRef<View, MenuGroupHeaderProps>(
 MenuGroupHeader.displayName = 'Menu.GroupHeader';
 
 export interface MenuItemActionProps extends IMenuItemActionProps {
+  /** Additional Uniwind/Tailwind classes, merged after the action's own styles. */
   className?: string;
+  /** The trailing interactive control, such as a `Button`. */
   children?: ReactNode;
 }
 
@@ -688,7 +797,10 @@ const MenuItemAction = forwardRef<View, MenuItemActionProps>(
 MenuItemAction.displayName = 'Menu.ItemAction';
 
 export interface MenuItemControlProps extends ViewProps {
+  /** Additional Uniwind/Tailwind classes, merged after the control's own styles. */
   className?: string;
+  /** Not rendered; the control draws a checkbox or radio that mirrors the enclosing item. */
+  children?: ReactNode;
 }
 
 const MenuItemControl = ({ className, style, ...props }: MenuItemControlProps) => {
@@ -740,8 +852,12 @@ const MenuItemControl = ({ className, style, ...props }: MenuItemControlProps) =
 MenuItemControl.displayName = 'Menu.ItemControl';
 
 export interface MenuItemCountProps extends TextProps {
+  /** Render the consumer's child element in place of the default `Text` host. */
   asChild?: boolean;
+  /** Additional Uniwind/Tailwind classes, merged after the count's own styles. */
   className?: string;
+  /** The count to display. */
+  children?: ReactNode;
 }
 
 const MenuItemCount = forwardRef<Text, MenuItemCountProps>(

package/src/components/RangeCalendar/index.tsx

@@ -22,7 +22,9 @@ import { calendarRootVariants } from '../Calendar/styles';
 
 export interface RangeCalendarProps
   extends Omit<RangeCalendarRootProps, 'children'>, Omit<ViewProps, 'children'> {
+  /** Additional Uniwind/Tailwind classes, merged after the calendar's own styles. */
   className?: string;
+  /** Custom calendar body. Omit to render the default header and month grid. */
   children?: ReactNode;
 }
 

package/src/components/ReorderableList/ReorderableListShared.tsx

@@ -0,0 +1,113 @@
+import {
+  Fragment,
+  forwardRef,
+  useEffect,
+  useMemo,
+  type ForwardedRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { ScrollView, StyleSheet, type ScrollViewProps, type ViewStyle } from 'react-native';
+import { dataAttributes, mergeDataAttributes } from '@cdx-ui/primitives';
+import { findDuplicateKeys } from './useReorder';
+
+export interface ReorderableRowInfo<T> {
+  item: T;
+  /** Consumer key from `keyExtractor`. */
+  key: string;
+  /** Position of `item` in `data`. */
+  index: number;
+  count: number;
+}
+
+export interface ReorderableListSharedProps<T> extends Omit<ScrollViewProps, 'children'> {
+  data: T[];
+  keyExtractor: (item: T, index: number) => string;
+  /** Renders each row. Ignored when `children` is set. */
+  renderRow?: (info: ReorderableRowInfo<T>) => ReactNode;
+  /** Replaces the per-row rendering (native renders the engine's own container here). */
+  children?: ReactNode;
+  /** Scroll host. Defaults to `ScrollView`. */
+  ScrollComponent?: typeof ScrollView;
+  className?: string;
+}
+
+let hasWarnedDuplicateKeys = false;
+
+const styles = StyleSheet.create({
+  root: { flexGrow: 0, minHeight: 0 },
+  content: { flexGrow: 0 },
+});
+
+/**
+ * Longhands for a consumer `flex`, placed between the `flexGrow: 0` default and the consumer style.
+ * Yoga lets a longhand beat the shorthand, so `flex: 1` alone keeps grow 0 with basis 0 and the
+ * list collapses to zero height.
+ */
+export function flexLonghands(flex: number | undefined): ViewStyle | undefined {
+  if (flex === undefined) return undefined;
+  if (flex > 0) return { flexGrow: flex, flexShrink: 1, flexBasis: 0 };
+  if (flex < 0) return { flexGrow: 0, flexShrink: -flex };
+  return { flexGrow: 0, flexShrink: 0 };
+}
+
+function ReorderableListSharedInner<T>(
+  {
+    data,
+    keyExtractor,
+    renderRow,
+    children,
+    ScrollComponent = ScrollView,
+    style,
+    contentContainerStyle,
+    ...props
+  }: ReorderableListSharedProps<T>,
+  ref: ForwardedRef<ScrollView>,
+) {
+  const keyToIndex = useMemo(() => {
+    const map = new Map<string, number>();
+    data.forEach((item, index) => map.set(keyExtractor(item, index), index));
+    return map;
+  }, [data, keyExtractor]);
+
+  useEffect(() => {
+    if (!__DEV__ || hasWarnedDuplicateKeys) return;
+    const duplicates = findDuplicateKeys(data, keyExtractor);
+    if (duplicates.length > 0) {
+      hasWarnedDuplicateKeys = true;
+      console.warn(
+        `[ReorderableList] keyExtractor returned duplicate keys (${duplicates.join(', ')}). Keys must be stable and unique per item — do not derive them from the index.`,
+      );
+    }
+  }, [data, keyExtractor]);
+
+  return (
+    <ScrollComponent
+      ref={ref}
+      style={[styles.root, flexLonghands(StyleSheet.flatten(style)?.flex), style]}
+      contentContainerStyle={[styles.content, contentContainerStyle]}
+      {...props}
+      role="list"
+      {...mergeDataAttributes(props, dataAttributes({ slot: 'reorderable-list' }))}
+    >
+      {children ??
+        data.map((item, index) => {
+          const key = keyExtractor(item, index);
+          return (
+            <Fragment key={key}>
+              {renderRow?.({
+                item,
+                key,
+                index: keyToIndex.get(key) ?? index,
+                count: data.length,
+              })}
+            </Fragment>
+          );
+        })}
+    </ScrollComponent>
+  );
+}
+
+export const ReorderableListShared = forwardRef(ReorderableListSharedInner) as <T>(
+  props: ReorderableListSharedProps<T> & { ref?: ForwardedRef<ScrollView> },
+) => ReactElement | null;

package/src/components/ReorderableList/index.tsx

@@ -0,0 +1,162 @@
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactElement,
+  type Ref,
+} from 'react';
+import { AccessibilityInfo, ScrollView } from 'react-native';
+import Animated, { useAnimatedReaction, useAnimatedRef } from 'react-native-reanimated';
+import Sortable, {
+  useItemContext,
+  type SortableGridDragEndParams,
+  type SortableGridRenderItemInfo,
+} from 'react-native-sortables';
+import { scheduleOnRN } from 'react-native-worklets';
+import { mergeRefs } from '@cdx-ui/utils';
+import { ReorderableListShared } from './ReorderableListShared';
+import { ReorderableRowProvider, type ReorderableRowHandle } from './rowContext';
+import type { ReorderableListProps } from './types';
+import { useReorderableRowValue, useReorderController, type ReorderController } from './useReorder';
+
+export type {
+  ReorderableListLabels,
+  ReorderableListProps,
+  ReorderableListRenderItemInfo,
+} from './types';
+
+const nativeHandle: ReorderableRowHandle = {
+  props: {},
+  ref: undefined,
+  wrap: (host, style) => <Sortable.Handle style={style}>{host}</Sortable.Handle>,
+};
+
+const AnimatedScrollView = Animated.ScrollView as unknown as typeof ScrollView;
+
+interface NativeListContextValue<T> {
+  renderItem: ReorderableListProps<T>['renderItem'];
+  controller: ReorderController<T>;
+}
+
+const NativeListContext = createContext<NativeListContextValue<unknown> | null>(null);
+
+/**
+ * sortables keeps rendered rows mounted and only re-renders a row when its item, index, or the
+ * grid's `renderItem` identity changes. The grid gets a stable `renderItem`; the consumer's
+ * (usually inline) `renderItem` reaches rows through context instead.
+ */
+function NativeRow<T>({ item, index }: SortableGridRenderItemInfo<T>) {
+  const list = useContext(NativeListContext) as NativeListContextValue<T>;
+  const { isActive } = useItemContext();
+  const [isDragging, setIsDragging] = useState(false);
+
+  useAnimatedReaction(
+    () => isActive.get(),
+    (active, previous) => {
+      if (active !== (previous ?? false)) scheduleOnRN(setIsDragging, active);
+    },
+  );
+
+  const rowValue = useReorderableRowValue({
+    index,
+    count: list.controller.data.length,
+    isDragging,
+    handle: nativeHandle,
+    labels: list.controller.labels,
+    moveItem: list.controller.moveItem,
+  });
+
+  return (
+    <ReorderableRowProvider value={rowValue}>
+      {list.renderItem({ item, index, isDragging })}
+    </ReorderableRowProvider>
+  );
+}
+
+const renderGridItem = (info: SortableGridRenderItemInfo<unknown>) => <NativeRow {...info} />;
+
+function ReorderableListInner<T>(
+  {
+    data,
+    keyExtractor,
+    onReorder,
+    onReorderIndices,
+    renderItem,
+    getItemLabel,
+    labels,
+    scrollEventThrottle = 16,
+    ...rest
+  }: ReorderableListProps<T>,
+  ref: Ref<ScrollView>,
+) {
+  const scrollableRef = useAnimatedRef<ScrollView>();
+  const mergedRef = useMemo(() => mergeRefs(ref, scrollableRef), [ref, scrollableRef]);
+
+  const controller = useReorderController({
+    data,
+    onReorder,
+    onReorderIndices,
+    getItemLabel,
+    labels,
+    announce: AccessibilityInfo.announceForAccessibility,
+  });
+
+  const listValue = useMemo(
+    () => ({ renderItem, controller }) as NativeListContextValue<unknown>,
+    [controller, renderItem],
+  );
+
+  const gridKeyExtractor = useMemo(() => {
+    const keys = new Map<T, string>();
+    data.forEach((item, index) => keys.set(item, keyExtractor(item, index)));
+    return (item: T) => keys.get(item) ?? keyExtractor(item, data.indexOf(item));
+  }, [data, keyExtractor]);
+
+  const handleDragEnd = useCallback(
+    ({ fromIndex, toIndex, data: reordered }: SortableGridDragEndParams<T>) => {
+      if (fromIndex === toIndex) return;
+      const message = controller.describe('dropped', fromIndex, toIndex);
+      onReorder(reordered);
+      onReorderIndices?.(fromIndex, toIndex);
+      if (message) AccessibilityInfo.announceForAccessibility(message);
+    },
+    [controller, onReorder, onReorderIndices],
+  );
+
+  return (
+    <NativeListContext.Provider value={listValue}>
+      <ReorderableListShared
+        ref={mergedRef}
+        ScrollComponent={AnimatedScrollView}
+        data={data}
+        keyExtractor={keyExtractor}
+        scrollEventThrottle={scrollEventThrottle}
+        {...rest}
+      >
+        <Sortable.Grid
+          columns={1}
+          data={data}
+          keyExtractor={gridKeyExtractor}
+          renderItem={renderGridItem as (info: SortableGridRenderItemInfo<T>) => ReactElement}
+          scrollableRef={scrollableRef}
+          customHandle
+          dragActivationDelay={0}
+          overDrag="vertical"
+          activeItemScale={1}
+          inactiveItemOpacity={1}
+          activeItemShadowOpacity={0}
+          onDragEnd={handleDragEnd}
+        />
+      </ReorderableListShared>
+    </NativeListContext.Provider>
+  );
+}
+
+export const ReorderableList = forwardRef(ReorderableListInner) as <T>(
+  props: ReorderableListProps<T> & { ref?: Ref<ScrollView> },
+) => ReactElement | null;
+
+(ReorderableList as { displayName?: string }).displayName = 'ReorderableList';