@cdx-ui/components 0.2.2 → 0.2.3

package/src/components/ListItem/index.tsx

@@ -1,5 +1,16 @@
-import { forwardRef, useMemo, type ReactNode } from 'react';
-import { Text, View, type TextProps, type ViewProps } from 'react-native';
+import {
+  Children,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  useEffect,
+  useMemo,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { Platform, Text, View, type TextProps, type ViewProps } from 'react-native';
+import { DragIndicator } from '@cdx-ui/icons';
 import {
   ListItemRoot as ListItemRootPrimitive,
   Slot,
@@ -8,12 +19,23 @@ import {
   type IListItemProps,
   type ListItemCrossAlign,
 } from '@cdx-ui/primitives';
-import { cn, ParentContext, useParentContext, useStyleContext } from '@cdx-ui/utils';
+import {
+  cn,
+  composeEventHandlers,
+  mergeRefs,
+  ParentContext,
+  useParentContext,
+  useStyleContext,
+} from '@cdx-ui/utils';
+import { Icon } from '../Icon';
+import { useReorderableRow } from '../ReorderableList/rowContext';
 import {
   listItemContentVariants,
   listItemDescriptionVariants,
+  listItemDragHandleVariants,
   listItemLeadingSlotVariants,
   listItemMetaVariants,
+  listItemPressableRegionVariants,
   listItemRootVariants,
   listItemSectionHeaderLabelVariants,
   listItemSectionHeaderVariants,
@@ -34,6 +56,40 @@ const useListItemStyleContext = (): Pick<ListItemVariantProps, 'crossAlign'> =>
 // ROOT
 // =============================================================================
 
+/**
+ * `true` inside a pressable row's interactive element. `ListItem.DragHandle` reads it to warn when it
+ * is nested there instead of being a direct child of the row.
+ */
+const ListItemPressableContext = createContext(false);
+
+interface DragHandlePartition {
+  handle: ReactElement;
+  position: 'start' | 'end';
+  rest: ReactNode[];
+  misplaced: boolean;
+  extra: boolean;
+}
+
+/** Finds a direct-child `ListItem.DragHandle` (matched by identity) of a pressable row. */
+function partitionDragHandle(children: ReactNode): DragHandlePartition | undefined {
+  const items = Children.toArray(children);
+  const handleIndexes: number[] = [];
+  items.forEach((child, index) => {
+    if (isValidElement(child) && child.type === ListItemDragHandle) handleIndexes.push(index);
+  });
+  if (handleIndexes.length === 0) return undefined;
+  const [first] = handleIndexes;
+  return {
+    handle: items[first] as ReactElement,
+    position: first === 0 ? 'start' : 'end',
+    rest: items.filter((_, index) => !handleIndexes.includes(index)),
+    misplaced: first !== 0 && first !== items.length - 1,
+    extra: handleIndexes.length > 1,
+  };
+}
+
+let hasWarnedDragHandlePlacement = false;
+
 export interface ListItemProps extends Omit<IListItemProps, 'crossAlign'>, ListItemVariantProps {
   /**
    * Vertical density. `compact` reduces padding and min-height; typography stays the same.
@@ -60,6 +116,13 @@ export interface ListItemProps extends Omit<IListItemProps, 'crossAlign'>, ListI
   className?: string;
 }
 
+/**
+ * A pressable row (`onPress`, or `asChild`) with a `ListItem.DragHandle` as its first or last
+ * direct child renders the handle beside the pressable element instead of inside it. The handle
+ * is matched by identity, so a `memo()` or wrapper component around it is not recognized. Under
+ * `asChild`, pass the handle and the single interactive element as siblings:
+ * `<ListItem asChild><ListItem.DragHandle /><Link>…</Link></ListItem>`.
+ */
 const ListItemRoot = forwardRef<View, ListItemProps>(
   (
     {
@@ -68,6 +131,7 @@ const ListItemRoot = forwardRef<View, ListItemProps>(
       crossAlign: crossAlignProp = 'center',
       className,
       style,
+      children,
       ...props
     },
     ref,
@@ -75,22 +139,60 @@ const ListItemRoot = forwardRef<View, ListItemProps>(
     const crossAlign: ListItemCrossAlign = crossAlignProp ?? 'center';
     const parent = useParentContext();
     const ctx = useMemo(() => ({ ...parent, [SCOPE]: { crossAlign } }), [parent, crossAlign]);
+    const isDragging = useReorderableRow()?.isDragging ?? false;
+    const isPressable = props.onPress != null || !!props.asChild;
+    const partition = isPressable ? partitionDragHandle(children) : undefined;
+    const misplacedHandle = !!partition && (partition.misplaced || partition.extra);
+
+    useEffect(() => {
+      if (__DEV__ && misplacedHandle && !hasWarnedDragHandlePlacement) {
+        hasWarnedDragHandlePlacement = true;
+        console.warn(
+          '[ListItem] Place one ListItem.DragHandle as the first or last child of a pressable ListItem. A handle elsewhere is moved to the end, and extra handles are dropped.',
+        );
+      }
+    }, [misplacedHandle]);
 
     const computedClassName = cn(
       listItemRootVariants({ size, showSeparator, crossAlign }),
       className,
     );
 
+    const splitProps = partition && {
+      accessory: (
+        <ListItemPressableContext.Provider value={false}>
+          {partition.handle}
+        </ListItemPressableContext.Provider>
+      ),
+      accessoryPosition: partition.position,
+      pressableClassName: listItemPressableRegionVariants({
+        size: size ?? 'default',
+        handlePosition: partition.position,
+      }),
+    };
+    const regionChildren =
+      partition && props.asChild && partition.rest.length === 1
+        ? partition.rest[0]
+        : partition?.rest;
+
     return (
       <ParentContext.Provider value={ctx}>
-        <ListItemRootPrimitive
-          ref={ref}
-          className={computedClassName}
-          crossAlign={crossAlign}
-          style={style}
-          {...props}
-          {...mergeDataAttributes(props, dataAttributes({ slot: 'list-item' }))}
-        />
+        <ListItemPressableContext.Provider value={isPressable}>
+          <ListItemRootPrimitive
+            ref={ref}
+            className={computedClassName}
+            crossAlign={crossAlign}
+            style={style}
+            {...props}
+            {...splitProps}
+            {...mergeDataAttributes(
+              props,
+              dataAttributes({ slot: 'list-item', dragging: isDragging }),
+            )}
+          >
+            {partition ? regionChildren : children}
+          </ListItemRootPrimitive>
+        </ListItemPressableContext.Provider>
       </ParentContext.Provider>
     );
   },
@@ -263,6 +365,116 @@ const ListItemTrailingSlot = forwardRef<View, ListItemTrailingSlotProps>(
 
 ListItemTrailingSlot.displayName = 'ListItem.TrailingSlot';
 
+function DefaultDragHandleGrip() {
+  return <Icon as={DragIndicator} className="size-5 text-content-secondary" />;
+}
+
+/**
+ * Screen reader hint for the default handle. Web omits it: react-native-web drops
+ * `accessibilityHint`, and dnd-kit describes the keyboard controls through `aria-describedby`.
+ */
+const DEFAULT_DRAG_HANDLE_HINT = Platform.select<string | undefined>({
+  ios: 'Drag to reorder, or swipe up or down to choose a move action.',
+  android: 'Drag to reorder, or open the actions menu to move this item.',
+  default: undefined,
+});
+
+const dragHandleOuterStyle = { flexShrink: 0 as const };
+
+let hasWarnedDragHandleOutsideList = false;
+let hasWarnedNestedDragHandle = false;
+
+export interface ListItemDragHandleProps extends ViewProps {
+  /**
+   * Merges the handle onto the consumer's single child (for example an `IconButton`) so that
+   * element is the one focusable handle.
+   */
+  asChild?: boolean;
+  className?: string;
+}
+
+/**
+ * Drag activator for a row rendered by `ReorderableList`. Renders `null` outside a list. On a
+ * pressable `ListItem`, place it as the first or last direct child so it sits beside the row's
+ * pressable element rather than inside it.
+ */
+const ListItemDragHandle = forwardRef<View, ListItemDragHandleProps>(
+  (
+    {
+      asChild,
+      className,
+      style,
+      children,
+      accessibilityLabel = 'Reorder',
+      accessibilityHint,
+      accessibilityActions,
+      onAccessibilityAction,
+      ...props
+    },
+    ref,
+  ) => {
+    const row = useReorderableRow();
+    const insidePressable = useContext(ListItemPressableContext);
+    const isOutsideList = row === null;
+
+    useEffect(() => {
+      if (!__DEV__) return;
+      if (isOutsideList && !hasWarnedDragHandleOutsideList) {
+        hasWarnedDragHandleOutsideList = true;
+        console.warn(
+          '[ListItem.DragHandle] Rendered outside a ReorderableList row, so it renders nothing. Use it inside ReorderableList renderItem.',
+        );
+      }
+      if (insidePressable && !hasWarnedNestedDragHandle) {
+        hasWarnedNestedDragHandle = true;
+        console.warn(
+          "[ListItem.DragHandle] Nested inside a pressable ListItem, so it is part of the row's pressable element. Make it the first or last direct child of ListItem so it renders beside it.",
+        );
+      }
+    }, [isOutsideList, insidePressable]);
+
+    const handleRef = row?.handle.ref;
+    const hostRef = useMemo(() => mergeRefs(ref, handleRef), [ref, handleRef]);
+
+    if (!row) return null;
+
+    const { handle } = row;
+    const handleProps = {
+      ...handle.props,
+      accessible: true,
+      accessibilityRole: 'button' as const,
+      accessibilityLabel,
+      accessibilityHint:
+        accessibilityHint ??
+        (row.accessibilityActions.length > 0 ? DEFAULT_DRAG_HANDLE_HINT : undefined),
+      accessibilityActions: [...row.accessibilityActions, ...(accessibilityActions ?? [])],
+      onAccessibilityAction: composeEventHandlers(onAccessibilityAction, row.onAccessibilityAction),
+      className: cn(listItemDragHandleVariants(), className),
+      ...props,
+      ...mergeDataAttributes(props, dataAttributes({ slot: 'list-item-drag-handle' })),
+      style: [handle.props.style, style],
+    };
+
+    if (asChild) {
+      return handle.wrap(
+        <Slot ref={hostRef} {...handleProps}>
+          {children}
+        </Slot>,
+        dragHandleOuterStyle,
+      );
+    }
+
+    return handle.wrap(
+      <View ref={hostRef} {...handleProps}>
+        {children ?? <DefaultDragHandleGrip />}
+      </View>,
+      dragHandleOuterStyle,
+    );
+  },
+);
+
+ListItemDragHandle.displayName = 'ListItem.DragHandle';
+
 const wrapSectionHeaderLabel = (children: ReactNode): ReactNode => {
   if (typeof children === 'string' || typeof children === 'number') {
     return <Text className={cn(listItemSectionHeaderLabelVariants())}>{children}</Text>;
@@ -367,6 +579,7 @@ ListItemSectionHeader.displayName = 'ListItem.SectionHeader';
 
 type ListItemCompound = typeof ListItemRoot & {
   LeadingSlot: typeof ListItemLeadingSlot;
+  DragHandle: typeof ListItemDragHandle;
   Content: typeof ListItemContent;
   Title: typeof ListItemTitle;
   Description: typeof ListItemDescription;
@@ -377,6 +590,7 @@ type ListItemCompound = typeof ListItemRoot & {
 
 export const ListItem = Object.assign(ListItemRoot, {
   LeadingSlot: ListItemLeadingSlot,
+  DragHandle: ListItemDragHandle,
   Content: ListItemContent,
   Title: ListItemTitle,
   Description: ListItemDescription,
@@ -389,8 +603,10 @@ export type { ListItemCrossAlign, ListItemSectionHeaderVariantProps, ListItemVar
 export {
   listItemContentVariants,
   listItemDescriptionVariants,
+  listItemDragHandleVariants,
   listItemLeadingSlotVariants,
   listItemMetaVariants,
+  listItemPressableRegionVariants,
   listItemRootVariants,
   listItemSectionHeaderLabelVariants,
   listItemSectionHeaderVariants,

package/src/components/ListItem/styles.ts

@@ -31,6 +31,10 @@ export const listItemRootVariants = cva(
       ].join(' '),
       default: 'data-[active=true]:bg-surface-primary-hover',
     }),
+    'data-[dragging=true]:bg-surface-secondary',
+    // Native: changing the dragged row's zIndex mid-drag cancels the handle's pan on Fabric iOS;
+    // the drag engine stacks the active row itself.
+    Platform.select({ web: 'data-[dragging=true]:z-20', default: '' }),
   ],
   {
     variants: {
@@ -58,6 +62,37 @@ export const listItemRootVariants = cva(
   },
 );
 
+// ── Pressable region (pressable row with a direct-child DragHandle) ─────────
+//
+// The root becomes a non-interactive container and keeps every visual above: the primitive
+// mirrors the region's hover/active/focus state onto it, so the overlay, focus ring, and native
+// tint still span the whole row. The region itself is transparent; negative margins extend it
+// over the container's padding (and the gap beside the handle) so the hit area matches a row
+// without a handle. A consumer `className` that changes the row's padding is not mirrored here.
+
+export const listItemPressableRegionVariants = cva(
+  [
+    'relative flex-1 min-w-0 flex-row self-stretch gap-3 bg-transparent',
+    Platform.select({ web: 'outline-none', default: '' }),
+  ],
+  {
+    variants: {
+      size: {
+        default: '-my-3 py-3',
+        compact: '-my-2 py-2',
+      },
+      handlePosition: {
+        start: '-ms-3 ps-3 -me-5 pe-5',
+        end: '-ms-5 ps-5 -me-3 pe-3',
+      },
+    },
+    defaultVariants: {
+      size: 'default',
+      handlePosition: 'start',
+    },
+  },
+);
+
 // ── Leading / trailing slots ─────────────────────────────────────────────────
 
 export const listItemLeadingSlotVariants = cva([
@@ -79,6 +114,11 @@ export const listItemTrailingSlotVariants = cva(
   },
 );
 
+export const listItemDragHandleVariants = cva([
+  'relative z-10 flex shrink-0 self-stretch items-center justify-center',
+  'web:cursor-grab web:active:cursor-grabbing',
+]);
+
 // ── Content stack (title / description / meta) ───────────────────────────────
 
 export const listItemContentVariants = cva('relative z-10 flex min-w-0 flex-1 flex-col gap-1', {

package/src/components/Menu/index.tsx

@@ -98,7 +98,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 +125,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 +152,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 +185,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;
 }
@@ -241,14 +256,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 +308,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 +357,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 +383,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 +449,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 +493,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 +560,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 +591,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 +669,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 +699,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 +731,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 +770,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 +794,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 +849,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;
 }