Reorder List

"use client";

// Ported from bencho Reorder list (MIT, © 2026 Lorenzo Cabra). See THIRD_PARTY_NOTICES.md.
import { cva, type VariantProps } from "class-variance-authority";
import {
  animate,
  motion,
  MotionConfig,
  motionValue,
  useSpring,
  type AnimationPlaybackControls,
  type MotionValue,
} from "motion/react";
import {
  useEffect,
  useId,
  useLayoutEffect,
  useRef,
  useState,
  useSyncExternalStore,
  type ComponentPropsWithRef,
  type KeyboardEvent,
  type PointerEvent,
  type ReactNode,
} from "react";

import { Avatar, AvatarFallback, AvatarImage } from "@/components/avatar";
import { disabledStyles, focusRing } from "@/lib/styles";
import { cn } from "@/lib/utils";

/*
 * A short list you put in order by dragging a pill or with the keyboard.
 *
 * `motion` earns its place here (ADR 0014): the held row follows the pointer
 * one to one and, on release, springs to its slot carrying the velocity of the
 * throw, and the held pill leans and squashes with that velocity. Neighbours
 * re-target mid-flight as the held row crosses them, which a CSS transition
 * cannot do without jumping.
 *
 * Two layers stack in one box. Underneath, an aria-hidden layer of pill
 * backgrounds runs through an SVG goo filter, so pills melt into each other as
 * they pass. On top, the real list: one button per row, crisp because the
 * filter never touches it. Each blob shares its row's y motion value.
 *
 * The keyboard path follows the APG / Atlassian sortable pattern: Space or
 * Enter picks a row up, arrows move it, Space or Enter drops it, Escape puts
 * it back. Moves are a draft until the drop, and a polite live region says
 * what happened at every step. Under reduced motion nothing deforms and rows
 * jump to their slots.
 */

/** Vertical distance between rows, in px. */
const STEP = 50;
/** Pill height, in px (the gap between pills is STEP − PILL). */
const PILL = 44;
/** Pointer travel before a press counts as a drag. */
const SLOP = 3;

const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";

function subscribeToMotionPreference(onChange: () => void) {
  const query = window.matchMedia(REDUCED_MOTION);
  query.addEventListener("change", onChange);
  return () => query.removeEventListener("change", onChange);
}

function usePrefersReducedMotion() {
  return useSyncExternalStore(
    subscribeToMotionPreference,
    () => window.matchMedia(REDUCED_MOTION).matches,
    () => false,
  );
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

function moveTo(list: string[], id: string, to: number) {
  const next = list.filter((entry) => entry !== id);
  next.splice(to, 0, id);
  return next;
}

/** Spring for rows settling. `give` 0 is stiff and exact, 100 soft and bouncy. */
export function reorderSpring(give: number) {
  const g = clamp(give, 0, 100) / 100;
  return {
    type: "spring" as const,
    stiffness: 720 - 500 * g,
    damping: 44 - 26 * g,
    restDelta: 0.5,
  };
}

/**
 * How the held pill deforms at a velocity (px/s). `lean` is 0–100; at the
 * default 18 a brisk drag gives about scaleX 0.8, scaleY 1.1, skewY 1.4°.
 */
export function leanFor(velocity: number, lean: number) {
  const gain = clamp(lean, 0, 100) / 100;
  const amount = Math.min(1, Math.abs(velocity) / 1000) * gain;
  return {
    scaleX: Math.max(0.55, 1 - amount * 1.1),
    scaleY: Math.min(1.5, 1 + amount * 0.55),
    skewY: Math.sign(velocity) * amount * 8,
  };
}

export interface ReorderListItem {
  id: string;
  /** The row's name. Announced, and names its button. */
  label: string;
  /** Avatar image URL. Decorative: the label already names the row. */
  avatar?: string;
  /** Shown when there is no image, or it fails to load. */
  initials?: string;
  /** CSS colour behind the avatar, e.g. `var(--color-primary)`. */
  accent?: string;
  /** Shows a presence dot (success token) and adds "online" to the name. */
  online?: boolean;
}

export interface ReorderListAnnouncementDetails {
  item: ReorderListItem;
  /** 1-based. */
  position: number;
  total: number;
}

export interface ReorderListAnnouncements {
  grabbed: (details: ReorderListAnnouncementDetails) => string;
  moved: (details: ReorderListAnnouncementDetails) => string;
  dropped: (details: ReorderListAnnouncementDetails) => string;
  cancelled: (details: ReorderListAnnouncementDetails) => string;
}

const ANNOUNCEMENTS: ReorderListAnnouncements = {
  grabbed: ({ item, position, total }) =>
    `${item.label} grabbed. Current position ${String(position)} of ${String(total)}. ` +
    "Use the arrow keys to move, Space to drop, Escape to cancel.",
  moved: ({ item, position, total }) =>
    `${item.label} moved to position ${String(position)} of ${String(total)}`,
  dropped: ({ item, position, total }) =>
    `${item.label} dropped at position ${String(position)} of ${String(total)}`,
  cancelled: ({ item, position, total }) =>
    `Reorder cancelled. ${item.label} returned to position ${String(position)} of ${String(total)}`,
};

const reorderListVariants = cva("relative w-[12.25rem] text-[0.78125rem] select-none", {
  variants: {
    /** Pill tone. `light` is the card surface; `dark` inverts it. */
    fill: {
      light: "text-card-foreground/80 [--reorder-list-pill:var(--color-card)]",
      dark: "text-background/85 [--reorder-list-pill:var(--color-foreground)]",
    },
  },
  defaultVariants: { fill: "light" },
});

export interface ReorderListProps
  extends
    Omit<ComponentPropsWithRef<"div">, "defaultValue" | "children">,
    VariantProps<typeof reorderListVariants> {
  items: ReorderListItem[];
  /** Order as item ids (controlled). */
  value?: string[];
  /** Initial order (uncontrolled). Defaults to the order of `items`. */
  defaultValue?: string[];
  /** Called with the new order after a drop that changed it. */
  onValueChange?: (value: string[]) => void;
  /** Replaces the avatar and label inside a row. The label still names the button. */
  renderItem?: (item: ReorderListItem, state: { grabbed: boolean; index: number }) => ReactNode;
  /** Pill corner radius, 0–22 px. */
  corner?: number;
  /** Spring softness for rows settling, 0–100. */
  give?: number;
  /** How much the held pill skews and squashes with velocity, 0–100. */
  lean?: number;
  /** 1px inset hairline on each pill. */
  stroke?: boolean;
  disabled?: boolean;
  /** Overrides for the live-region messages (i18n). */
  announcements?: Partial<ReorderListAnnouncements>;
  /** Describes the keyboard operation; referenced by every row's button. */
  instructions?: string;
}

function RowAvatar({ item }: { item: ReorderListItem }) {
  return (
    <span aria-hidden="true" className="relative shrink-0">
      <Avatar
        size="sm"
        data-slot="reorder-list-avatar"
        style={{ backgroundColor: item.accent }}
        className={cn(!item.accent && "bg-muted")}
      >
        {item.avatar ? <AvatarImage src={item.avatar} alt="" draggable={false} /> : null}
        <AvatarFallback
          className="bg-transparent text-xs font-medium text-primary-foreground"
          style={item.accent ? undefined : { color: "var(--color-muted-foreground)" }}
        >
          {item.initials ?? item.label.slice(0, 1)}
        </AvatarFallback>
      </Avatar>
      {item.online ? (
        <span
          data-slot="reorder-list-presence"
          className="absolute -end-px -bottom-px size-[0.5625rem] rounded-full bg-success ring-2 ring-(--reorder-list-pill)"
        />
      ) : null}
    </span>
  );
}

/** A list you reorder by dragging liquid pills, or with Space and the arrow keys. */
export function ReorderList({
  className,
  items,
  value,
  defaultValue,
  onValueChange,
  renderItem,
  corner = 22,
  give = 50,
  lean = 18,
  fill,
  stroke = false,
  disabled = false,
  announcements,
  instructions = "Press Space or Enter to pick up, the arrow keys to move, Space or Enter to drop, Escape to cancel.",
  style,
  "aria-label": ariaLabel,
  "aria-labelledby": ariaLabelledBy,
  ...props
}: ReorderListProps) {
  const uid = useId().replace(/:/g, "");
  const filterId = `dowel-reorder-list-goo-${uid}`;
  const hintId = `dowel-reorder-list-hint-${uid}`;
  const reduceMotion = usePrefersReducedMotion();
  const messages = { ...ANNOUNCEMENTS, ...announcements };
  const radius = clamp(corner, 0, 22);
  const byId = new Map(items.map((item) => [item.id, item]));

  const [uncontrolled, setUncontrolled] = useState(
    () => defaultValue ?? items.map((item) => item.id),
  );
  const requested = value ?? uncontrolled;
  // Known ids in the requested order, then any items it left out.
  const order = requested
    .filter((id, i) => byId.has(id) && requested.indexOf(id) === i)
    .concat(items.map((item) => item.id).filter((id) => !requested.includes(id)));
  const total = order.length;

  /** The order being arranged, before a drop commits it. */
  const [draft, setDraftState] = useState<string[] | null>(null);
  const draftRef = useRef<string[] | null>(null);
  function setDraft(next: string[] | null) {
    draftRef.current = next;
    setDraftState(next);
  }
  const visual = draft ?? order;

  /** The row lifted by keyboard or pointer. */
  const [held, setHeld] = useState<string | null>(null);
  const grab = useRef<{ id: string; from: number } | null>(null);
  const drag = useRef<{
    id: string;
    pointerId: number;
    startY: number;
    originY: number;
    from: number;
    moved: boolean;
  } | null>(null);
  const [dragging, setDragging] = useState<string | null>(null);

  const [announcement, setAnnouncement] = useState("");
  function announce(kind: keyof ReorderListAnnouncements, id: string, index: number) {
    const item = byId.get(id);
    if (item) setAnnouncement(messages[kind]({ item, position: index + 1, total }));
  }

  // One y per row, shared by the row and its blob so the goo tracks the text.
  const [ys] = useState(() => new Map<string, MotionValue<number>>());
  const controls = useRef(new Map<string, AnimationPlaybackControls>());
  function yFor(id: string) {
    let y = ys.get(id);
    if (!y) {
      y = motionValue(Math.max(0, visual.indexOf(id)) * STEP);
      ys.set(id, y);
    }
    return y;
  }

  const skinX = useSpring(1, { stiffness: 420, damping: 26 });
  const skinY = useSpring(1, { stiffness: 420, damping: 26 });
  const skew = useSpring(0, { stiffness: 420, damping: 26 });
  const relax = useRef<ReturnType<typeof setTimeout>>(undefined);
  function deform(velocity: number) {
    if (reduceMotion) return;
    const shape = leanFor(velocity, lean);
    skinX.set(shape.scaleX);
    skinY.set(shape.scaleY);
    skew.set(shape.skewY);
    clearTimeout(relax.current);
    // A held pill relaxes as soon as the pointer is still.
    relax.current = setTimeout(() => deform(0), 80);
  }

  const visualKey = visual.join("\u0000");
  const spring = reorderSpring(give);
  useEffect(() => {
    visual.forEach((id, index) => {
      if (id === dragging) return;
      const y = yFor(id);
      const target = index * STEP;
      controls.current.get(id)?.stop();
      if (reduceMotion) {
        y.set(target);
      } else if (y.get() !== target) {
        controls.current.set(id, animate(y, target, spring));
      }
    });
    // `visualKey` stands for `visual`; the spring is read fresh on each run.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [visualKey, dragging, reduceMotion]);

  useEffect(() => {
    const running = controls.current;
    return () => {
      clearTimeout(relax.current);
      running.forEach((control) => control.stop());
    };
  }, []);

  // Committing reorders the DOM, which can drop focus from the moved button.
  const handles = useRef(new Map<string, HTMLButtonElement>());
  const refocus = useRef<string | null>(null);
  const orderKey = order.join("\u0000");
  useLayoutEffect(() => {
    const id = refocus.current;
    refocus.current = null;
    if (id && document.activeElement !== handles.current.get(id)) {
      handles.current.get(id)?.focus();
    }
  }, [orderKey]);

  function commit(next: string[]) {
    setDraft(null);
    if (next.join("\u0000") === orderKey) return;
    if (value === undefined) setUncontrolled(next);
    onValueChange?.(next);
  }

  function cancelGrab() {
    const current = grab.current;
    if (!current) return;
    grab.current = null;
    setHeld(null);
    setDraft(null);
    announce("cancelled", current.id, current.from);
  }

  function handleKeyDown(event: KeyboardEvent<HTMLButtonElement>, id: string) {
    if (drag.current) return;
    const list = draftRef.current ?? order;
    const index = list.indexOf(id);
    const last = list.length - 1;
    const key = event.key;
    const pick = key === " " || key === "Enter";

    if (grab.current?.id === id) {
      const to =
        key === "ArrowUp"
          ? index - 1
          : key === "ArrowDown"
            ? index + 1
            : key === "Home"
              ? 0
              : key === "End"
                ? last
                : null;
      if (to !== null) {
        event.preventDefault();
        const target = clamp(to, 0, last);
        if (target === index) return;
        setDraft(moveTo(list, id, target));
        announce("moved", id, target);
      } else if (pick) {
        event.preventDefault();
        grab.current = null;
        setHeld(null);
        refocus.current = id;
        commit(list);
        announce("dropped", id, index);
      } else if (key === "Escape") {
        event.preventDefault();
        cancelGrab();
      }
      return;
    }

    if (pick) {
      event.preventDefault();
      grab.current = { id, from: index };
      setHeld(id);
      setDraft(list);
      announce("grabbed", id, index);
      return;
    }
    const focusTo =
      key === "ArrowUp"
        ? index - 1
        : key === "ArrowDown"
          ? index + 1
          : key === "Home"
            ? 0
            : key === "End"
              ? last
              : null;
    if (focusTo === null) return;
    event.preventDefault();
    const next = list[clamp(focusTo, 0, last)];
    if (next) handles.current.get(next)?.focus();
  }

  function handlePointerDown(event: PointerEvent<HTMLButtonElement>, id: string) {
    if (disabled || grab.current || event.button !== 0) return;
    const index = order.indexOf(id);
    try {
      event.currentTarget.setPointerCapture(event.pointerId);
    } catch {
      // Synthetic pointers cannot be captured; the drag still works.
    }
    controls.current.get(id)?.stop();
    drag.current = {
      id,
      pointerId: event.pointerId,
      startY: event.clientY,
      originY: index * STEP,
      from: index,
      moved: false,
    };
    setDraft(order);
    setHeld(id);
    setDragging(id);
  }

  function handlePointerMove(event: PointerEvent<HTMLButtonElement>) {
    const current = drag.current;
    if (current?.pointerId !== event.pointerId) return;
    const dy = event.clientY - current.startY;
    if (!current.moved && Math.abs(dy) < SLOP) return;
    current.moved = true;
    const y = clamp(current.originY + dy, -STEP / 2, (total - 1) * STEP + STEP / 2);
    const row = yFor(current.id);
    row.set(y);
    deform(row.getVelocity());
    const list = draftRef.current ?? order;
    // A neighbour gives way once the held row is half a step past it.
    const slot = clamp(Math.round(y / STEP), 0, total - 1);
    if (list.indexOf(current.id) !== slot) setDraft(moveTo(list, current.id, slot));
  }

  function handlePointerUp(event: PointerEvent<HTMLButtonElement>) {
    const current = drag.current;
    if (current?.pointerId !== event.pointerId) return;
    drag.current = null;
    clearTimeout(relax.current);
    deform(0);
    const list = draftRef.current ?? order;
    setHeld(null);
    setDragging(null);
    if (!current.moved) {
      setDraft(null);
      return;
    }
    if (document.activeElement === event.currentTarget) refocus.current = current.id;
    commit(list);
    announce("dropped", current.id, list.indexOf(current.id));
  }

  const blobStyle = { height: PILL, borderRadius: radius };

  return (
    <MotionConfig reducedMotion="user">
      <div
        data-slot="reorder-list"
        data-disabled={disabled ? "" : undefined}
        className={cn(reorderListVariants({ fill }), className)}
        style={{ height: total > 0 ? (total - 1) * STEP + PILL : 0, ...style }}
        {...props}
      >
        <svg aria-hidden="true" className="absolute size-0">
          <defs>
            <filter id={filterId} x="-20%" y="-50%" width="140%" height="200%">
              <feGaussianBlur in="SourceGraphic" stdDeviation="2.6" result="blur" />
              <feColorMatrix
                in="blur"
                type="matrix"
                values="1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 28 -14"
                result="goo"
              />
              <feComposite in="SourceGraphic" in2="goo" operator="atop" />
            </filter>
          </defs>
        </svg>

        <div
          aria-hidden="true"
          data-slot="reorder-list-blobs"
          className="pointer-events-none absolute inset-0"
          style={{ filter: reduceMotion ? undefined : `url(#${filterId})` }}
        >
          {order.map((id) => {
            const isHeld = id === held;
            return (
              <motion.div
                key={id}
                data-slot="reorder-list-blob"
                className="absolute inset-x-0 top-0"
                style={{ ...blobStyle, y: yFor(id), zIndex: isHeld ? 2 : 1 }}
              >
                <motion.div
                  data-slot="reorder-list-skin"
                  className={cn(
                    "size-full bg-(--reorder-list-pill) shadow-xs",
                    stroke && "ring-1 ring-border ring-inset",
                  )}
                  style={{
                    borderRadius: radius,
                    ...(id === dragging ? { scaleX: skinX, scaleY: skinY, skewY: skew } : null),
                  }}
                />
              </motion.div>
            );
          })}
        </div>

        <ol
          aria-label={ariaLabel}
          aria-labelledby={ariaLabelledBy}
          data-slot="reorder-list-list"
          className="absolute inset-0 m-0 list-none p-0"
        >
          {order.map((id) => {
            const item = byId.get(id);
            if (!item) return null;
            const isHeld = id === held;
            const index = visual.indexOf(id);
            return (
              <motion.li
                key={id}
                data-slot="reorder-list-row"
                data-index={index}
                data-held={isHeld ? "" : undefined}
                className="absolute inset-x-0 top-0"
                style={{ height: PILL, y: yFor(id), zIndex: isHeld ? 2 : 1 }}
              >
                <button
                  ref={(node) => {
                    if (node) handles.current.set(id, node);
                    else handles.current.delete(id);
                  }}
                  type="button"
                  disabled={disabled}
                  aria-describedby={hintId}
                  aria-pressed={isHeld && dragging === null}
                  data-slot="reorder-list-handle"
                  data-grabbed={isHeld ? "" : undefined}
                  className={cn(
                    "flex size-full touch-none items-center gap-[0.6875rem] bg-transparent ps-1.5 pe-4 text-start",
                    "cursor-grab data-grabbed:cursor-grabbing",
                    focusRing,
                    disabledStyles,
                  )}
                  style={{ borderRadius: radius }}
                  onKeyDown={(event) => handleKeyDown(event, id)}
                  onBlur={() => {
                    if (grab.current?.id === id) cancelGrab();
                  }}
                  onPointerDown={(event) => handlePointerDown(event, id)}
                  onPointerMove={handlePointerMove}
                  onPointerUp={handlePointerUp}
                  onPointerCancel={handlePointerUp}
                >
                  {renderItem ? (
                    <>
                      <span aria-hidden="true" className="contents">
                        {renderItem(item, { grabbed: isHeld, index })}
                      </span>
                      <span className="sr-only">{item.label}</span>
                    </>
                  ) : (
                    <>
                      <motion.span
                        className="flex shrink-0"
                        initial={false}
                        animate={{ scale: isHeld ? 1.08 : 1 }}
                        transition={{ type: "spring", stiffness: 520, damping: 20 }}
                      >
                        <RowAvatar item={item} />
                      </motion.span>
                      <span data-slot="reorder-list-label" className="min-w-0 truncate">
                        {item.label}
                      </span>
                    </>
                  )}
                  {item.online ? <span className="sr-only">, online</span> : null}
                </button>
              </motion.li>
            );
          })}
        </ol>

        <span id={hintId} className="sr-only">
          {instructions}
        </span>
        <span role="status" aria-live="polite" className="sr-only">
          {announcement}
        </span>
      </div>
    </MotionConfig>
  );
}

export { reorderListVariants };