@cdx-ui/components 0.2.1 → 0.2.3

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';

package/src/components/ReorderableList/index.web.tsx

@@ -0,0 +1,254 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
+  type Ref,
+} from 'react';
+import { ScrollView, Text, View, type ViewProps, type ViewStyle } from 'react-native';
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  useDndContext,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import { cn } from '@cdx-ui/utils';
+import { ReorderableListShared, type ReorderableRowInfo } from './ReorderableListShared';
+import { reorderItems } from './reorderItems';
+import { ReorderableRowProvider, type ReorderableRowHandle } from './rowContext';
+import type { ReorderableListProps } from './types';
+import { useReorderableRowValue, useReorderController, type ReorderController } from './useReorder';
+import { createReorderAnnouncements, resolveDragEnd } from './webDnd';
+
+export type {
+  ReorderableListLabels,
+  ReorderableListProps,
+  ReorderableListRenderItemInfo,
+} from './types';
+
+const handleTouchStyle = { touchAction: 'none' } as ViewStyle;
+const passThrough: ReorderableRowHandle['wrap'] = (host) => host;
+
+/**
+ * react-native-web's `Pressable` stops Enter/Space `keydown` from bubbling, so when the handle is a
+ * pressable control (`asChild` with an `IconButton`) the drop key never reaches dnd-kit's document
+ * listener. While dragging, take the key at the handle and hand it to the document directly.
+ */
+function forwardDropKeyToDocument(event: ReactKeyboardEvent) {
+  const { key, code } = event.nativeEvent;
+  if (key !== 'Enter' && key !== ' ' && code !== 'Enter' && code !== 'Space') return;
+  event.preventDefault();
+  event.stopPropagation();
+  const { ownerDocument } = event.currentTarget as unknown as Node;
+  ownerDocument?.dispatchEvent(new KeyboardEvent('keydown', { key, code, cancelable: true }));
+}
+
+interface SortableRowProps<T> {
+  info: ReorderableRowInfo<T>;
+  renderItem: ReorderableListProps<T>['renderItem'];
+  controller: ReorderController<T>;
+}
+
+function SortableRow<T>({ info, renderItem, controller }: SortableRowProps<T>) {
+  const { item, index, count, key } = info;
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    setActivatorNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: key });
+  const { activatorEvent } = useDndContext();
+
+  const nodeRef = useRef<HTMLElement | null>(null);
+  const swallowNextClickRef = useRef(false);
+
+  const setRowRef = useCallback(
+    (node: View | null) => {
+      const element = node as unknown as HTMLElement | null;
+      nodeRef.current = element;
+      setNodeRef(element);
+    },
+    [setNodeRef],
+  );
+
+  // dnd-kit's shift/drop animation is written to the row's DOM node; React never owns these keys.
+  useLayoutEffect(() => {
+    const node = nodeRef.current;
+    if (!node) return;
+    node.style.transform = transform ? (CSS.Translate.toString({ ...transform, x: 0 }) ?? '') : '';
+    node.style.transition = transition ?? '';
+  }, [transform, transition]);
+
+  // A pointer drag ends with a click on the row; swallow that one click so a pressable row does
+  // not fire after a drop or cancel. Scoped to this row, and reset by the next pointerdown.
+  useEffect(() => {
+    if (isDragging && activatorEvent?.type.startsWith('pointer')) {
+      swallowNextClickRef.current = true;
+    }
+  }, [activatorEvent, isDragging]);
+
+  useEffect(() => {
+    const node = nodeRef.current;
+    if (!node) return undefined;
+    const onClick = (event: MouseEvent) => {
+      if (!swallowNextClickRef.current) return;
+      swallowNextClickRef.current = false;
+      event.stopPropagation();
+      event.preventDefault();
+    };
+    const onPointerDown = () => {
+      swallowNextClickRef.current = false;
+    };
+    node.addEventListener('click', onClick, true);
+    node.addEventListener('pointerdown', onPointerDown, true);
+    return () => {
+      node.removeEventListener('click', onClick, true);
+      node.removeEventListener('pointerdown', onPointerDown, true);
+    };
+  }, []);
+
+  const handle = useMemo<ReorderableRowHandle>(() => {
+    const { tabIndex, role, ...aria } = attributes;
+    return {
+      props: {
+        ...aria,
+        role: role as ViewProps['role'],
+        tabIndex: tabIndex === 0 || tabIndex === -1 ? tabIndex : undefined,
+        style: handleTouchStyle,
+        ...listeners,
+        onKeyDownCapture: isDragging ? forwardDropKeyToDocument : undefined,
+      },
+      ref: (node) => setActivatorNodeRef(node as unknown as HTMLElement | null),
+      wrap: passThrough,
+    };
+  }, [attributes, isDragging, listeners, setActivatorNodeRef]);
+
+  const rowValue = useReorderableRowValue({
+    index,
+    count,
+    isDragging,
+    handle,
+    labels: controller.labels,
+    moveItem: controller.moveItem,
+  });
+
+  return (
+    <ReorderableRowProvider value={rowValue}>
+      <View ref={setRowRef} className={cn(isDragging && 'relative z-20')}>
+        {renderItem({ item, index, isDragging })}
+      </View>
+    </ReorderableRowProvider>
+  );
+}
+
+function ReorderableListInner<T>(
+  {
+    data,
+    keyExtractor,
+    renderItem,
+    onReorder,
+    onReorderIndices,
+    getItemLabel,
+    labels,
+    ...rest
+  }: ReorderableListProps<T>,
+  ref: Ref<ScrollView>,
+) {
+  const [announcement, setAnnouncement] = useState('');
+
+  const controller = useReorderController({
+    data,
+    onReorder,
+    onReorderIndices,
+    getItemLabel,
+    labels,
+    announce: setAnnouncement,
+  });
+
+  const sortableIds = useMemo(
+    () => data.map((item, index) => keyExtractor(item, index)),
+    [data, keyExtractor],
+  );
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: 4 },
+    }),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    }),
+  );
+
+  const { describe, labels: resolvedLabels } = controller;
+  const accessibility = useMemo(
+    () => ({
+      announcements: createReorderAnnouncements(sortableIds, describe),
+      screenReaderInstructions: { draggable: resolvedLabels.screenReaderInstructions },
+    }),
+    [describe, resolvedLabels, sortableIds],
+  );
+
+  const handleDragEnd = useCallback(
+    ({ active, over }: DragEndEvent) => {
+      const move = resolveDragEnd(sortableIds, active.id, over?.id);
+      if (!move) return;
+      onReorder(reorderItems(data, move.from, move.to));
+      onReorderIndices?.(move.from, move.to);
+    },
+    [data, onReorder, onReorderIndices, sortableIds],
+  );
+
+  const renderRow = useCallback(
+    (info: ReorderableRowInfo<T>) => (
+      <SortableRow info={info} renderItem={renderItem} controller={controller} />
+    ),
+    [controller, renderItem],
+  );
+
+  return (
+    <DndContext
+      accessibility={accessibility}
+      collisionDetection={closestCenter}
+      onDragEnd={handleDragEnd}
+      sensors={sensors}
+    >
+      <SortableContext items={sortableIds} strategy={verticalListSortingStrategy}>
+        <ReorderableListShared
+          ref={ref}
+          data={data}
+          keyExtractor={keyExtractor}
+          renderRow={renderRow}
+          {...rest}
+        />
+      </SortableContext>
+      <View aria-live="polite" className="sr-only">
+        <Text>{announcement}</Text>
+      </View>
+    </DndContext>
+  );
+}
+
+export const ReorderableList = forwardRef(ReorderableListInner) as <T>(
+  props: ReorderableListProps<T> & { ref?: Ref<ScrollView> },
+) => ReactElement | null;
+
+(ReorderableList as { displayName?: string }).displayName = 'ReorderableList';

package/src/components/ReorderableList/labels.ts

@@ -0,0 +1,52 @@
+import type { ReorderableListLabels } from './types';
+
+export const DEFAULT_REORDERABLE_LIST_LABELS: ReorderableListLabels = {
+  item: 'item {position}',
+  pickedUp: 'Picked up {item}. Position {position} of {count}.',
+  movedTo: 'Moved {item} to position {position} of {count}.',
+  dropped: 'Dropped {item} at position {position} of {count}.',
+  cancelled: 'Reorder cancelled. {item} returned to position {position} of {count}.',
+  screenReaderInstructions:
+    'To pick up an item, press Space or Enter. Use the arrow keys to move it, then press Space or Enter to drop it, or Escape to cancel.',
+  moveUp: 'Move up',
+  moveDown: 'Move down',
+  moveToTop: 'Move to top',
+  moveToBottom: 'Move to bottom',
+};
+
+export function resolveReorderableListLabels(
+  partial?: Partial<ReorderableListLabels>,
+): ReorderableListLabels {
+  return { ...DEFAULT_REORDERABLE_LIST_LABELS, ...partial };
+}
+
+export type ReorderMessageKey = 'pickedUp' | 'movedTo' | 'dropped' | 'cancelled';
+
+export interface ReorderMessageInput<T> {
+  labels: ReorderableListLabels;
+  getItemLabel?: (item: T, index: number) => string;
+  item: T;
+  /** Zero-based position of the item before the move — names the item. */
+  fromIndex: number;
+  /** Zero-based position announced in the message. */
+  position: number;
+  count: number;
+}
+
+function fill(template: string, values: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (match, name: string) => values[name] ?? match);
+}
+
+export function formatReorderMessage<T>(
+  key: ReorderMessageKey,
+  { labels, getItemLabel, item, fromIndex, position, count }: ReorderMessageInput<T>,
+): string {
+  const itemName = getItemLabel
+    ? getItemLabel(item, fromIndex)
+    : fill(labels.item, { position: String(fromIndex + 1) });
+  return fill(labels[key], {
+    item: itemName,
+    position: String(position + 1),
+    count: String(count),
+  });
+}

package/src/components/ReorderableList/reorderItems.ts

@@ -0,0 +1,16 @@
+/** Immutable insert-strategy move. No-ops when indices are equal or out of range. */
+export function reorderItems<T>(data: T[], fromIndex: number, toIndex: number): T[] {
+  if (
+    fromIndex === toIndex ||
+    fromIndex < 0 ||
+    toIndex < 0 ||
+    fromIndex >= data.length ||
+    toIndex >= data.length
+  ) {
+    return data;
+  }
+
+  const next = data.slice();
+  next.splice(toIndex, 0, ...next.splice(fromIndex, 1));
+  return next;
+}

package/src/components/ReorderableList/rowContext.tsx

@@ -0,0 +1,72 @@
+import { createContext, useContext, type ReactElement, type RefCallback } from 'react';
+import type {
+  AccessibilityActionEvent,
+  AccessibilityActionInfo,
+  StyleProp,
+  View,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+
+/**
+ * Props that make a host element the row's drag activator.
+ *
+ * - **Web:** dnd-kit `attributes` (`role`, `tabIndex`, `aria-*`), `listeners` (`onPointerDown`,
+ *   `onKeyDown`), and `style: { touchAction: 'none' }`. Some keys (`aria-roledescription`,
+ *   `aria-describedby`) are outside `ViewProps`, hence the index signature.
+ * - **Native:** empty — the gesture is attached by `wrap`.
+ */
+export type ReorderableHandleHostProps = ViewProps & Readonly<Record<string, unknown>>;
+
+/**
+ * Binds a handle element to the row's drag gesture without adding a focusable wrapper.
+ *
+ * Render one host (a `View`, or the consumer child under `asChild` via `Slot`), then:
+ * 1. spread `props` onto it before consumer props (handlers compose through `Slot`),
+ * 2. compose `ref` with the host's own ref,
+ * 3. return `wrap(host)`.
+ *
+ * Web: `ref` is dnd-kit's `setActivatorNodeRef` and `wrap` returns the host unchanged.
+ * Native: `ref` is `undefined` and `wrap` places the host inside `Sortable.Handle`, which must
+ * wrap because react-native-sortables only attaches its handle gesture through that component. It
+ * renders a non-accessible `View`, so the host stays the single focusable element; pass layout
+ * styles that must sit on the outer box (flex, alignSelf, margin) as `wrap`'s second argument.
+ */
+export interface ReorderableRowHandle {
+  props: ReorderableHandleHostProps;
+  ref: RefCallback<View> | undefined;
+  wrap: (host: ReactElement, style?: StyleProp<ViewStyle>) => ReactElement;
+}
+
+/** Per-row reorder state and actions, provided to every row rendered by `ReorderableList`. */
+export interface ReorderableRowContextValue {
+  /** `true` while this row is dragged. */
+  isDragging: boolean;
+  /** Zero-based position of the row in `data`. */
+  index: number;
+  /** Number of rows in the list. */
+  count: number;
+  /**
+   * Moves this row to `toIndex` (clamped to the list), calls `onReorder`/`onReorderIndices`, and
+   * announces the new position. No-op when the position does not change.
+   */
+  move: (toIndex: number) => void;
+  /**
+   * `Move up` / `Move down` / `Move to top` / `Move to bottom`, omitting those that do not apply at
+   * the ends. Spread with `onAccessibilityAction` onto the handle host. Native screen readers
+   * expose them as custom actions; react-native-web drops both props, and web keyboard users
+   * reorder through dnd-kit's keyboard sensor on the handle instead.
+   */
+  accessibilityActions: AccessibilityActionInfo[];
+  onAccessibilityAction: (event: AccessibilityActionEvent) => void;
+  handle: ReorderableRowHandle;
+}
+
+const ReorderableRowContext = createContext<ReorderableRowContextValue | null>(null);
+
+export const ReorderableRowProvider = ReorderableRowContext.Provider;
+
+/** Reorder state for the enclosing `ReorderableList` row, or `null` outside a list. */
+export function useReorderableRow(): ReorderableRowContextValue | null {
+  return useContext(ReorderableRowContext);
+}