@cdx-ui/components 0.2.2 → 0.2.4

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>;
@@ -310,11 +522,12 @@ export interface ListItemSectionHeaderProps extends ViewProps {
   trailing?: ReactNode;
   /**
    * Background treatment. `ghost` has no fill and a bottom border; `subtle` adds a neutral fill
-   * (matching `subtle` on Avatar, Chip, and IconButton) and drops the bottom border.
-   * Label typography is the same for both.
+   * (matching `subtle` on Avatar, Chip, and IconButton) and drops the bottom border. `gradient`
+   * fades from the primary surface into a brand tint, left to right, and keeps the bottom border.
+   * Label typography is the same for all three.
    * @default 'ghost'
-   * @remarks `'ghost' | 'subtle'`
-   * @fumadocsType `'ghost' | 'subtle'`
+   * @remarks `'ghost' | 'subtle' | 'gradient'`
+   * @fumadocsType `'ghost' | 'subtle' | 'gradient'`
    */
   variant?: ListItemSectionHeaderVariant;
   /**
@@ -367,6 +580,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 +591,7 @@ type ListItemCompound = typeof ListItemRoot & {
 
 export const ListItem = Object.assign(ListItemRoot, {
   LeadingSlot: ListItemLeadingSlot,
+  DragHandle: ListItemDragHandle,
   Content: ListItemContent,
   Title: ListItemTitle,
   Description: ListItemDescription,
@@ -389,8 +604,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', {
@@ -114,6 +154,7 @@ export const listItemSectionHeaderVariants = cva(
         ghost: [],
         // The fill separates the header from its rows, so the bottom border is dropped.
         subtle: 'bg-surface-neutral-subtle border-b-0',
+        gradient: 'bg-gradient-to-r from-surface-primary to-surface-brand-tint',
       },
       showDivider: {
         true: ['border-t-4 border-solid border-t-surface-brand-strong/40', 'border-x-0'],