[@mantine/hooks]: Add swap handle

Author: mmounirf

docs/src/pages/hooks/use-list-state.mdx

@@ -36,13 +36,17 @@ const apply = () =>
 const reorder = () => handlers.reorder({ from: 2, to: 0 });
 // values -> [{ a: 4 }, { a: 0 }, { a: 5 }]
 
+// swap items positions
+const swap = () => handlers.swap({ from: 0, to: 2 });
+// values -> [{ a: 5 }, { a: 0 }, { a: 4 }]
+
 // apply function to each element that matches condition
 const applyWhere = () =>
   handlers.applyWhere(
     (item) => item.a > 0,
     (item) => ({ a: item.a + 2 })
   );
-// values -> [{ a: 6 }, { a: 0 }, { a: 7 }]
+// values -> [{ a: 7 }, { a: 0 }, { a: 6 }]
 
 // set entirely new state
 const setState = () => handlers.setState([{ a: 6 }, { a: 7 }]);
@@ -75,6 +79,7 @@ The hook provides handlers to work with array data:
 - `insert` – insert items at given index
 - `remove` – remove items at given indices
 - `reorder` – move item from one position to another
+- `swap` – swap items positions
 - `apply` – apply given function to all items in the list
 - `applyWhere` - apply given function to selective items using condition
 - `setItem` – replace item at given index
@@ -112,6 +117,7 @@ export interface UseListStateHandlers<T> {
   ) => void;
   remove: (...indices: number[]) => void;
   reorder: ({ from, to }: { from: number; to: number }) => void;
+  swap: ({ from, to }: { from: number; to: number }) => void;
   setItem: (index: number, item: T) => void;
   setItemProp: <K extends keyof T, U extends T[K]>(
     index: number,

packages/@mantine/hooks/src/use-list-state/use-list-state.test.ts

@@ -175,6 +175,18 @@ describe('@mantine/hooks/use-list-state', () => {
     expect(state).toStrictEqual([TEST_STATE[1], TEST_STATE[2], TEST_STATE[0]]);
   });
 
+  it('swap items positions with handlers.swap', () => {
+    const hook = renderHook(() => useListState(TEST_STATE));
+
+    act(() => {
+      const [, handlers] = hook.result.current;
+      handlers.swap({ from: 0, to: 2 });
+    });
+
+    const [state] = hook.result.current;
+    expect(state).toStrictEqual([TEST_STATE[2], TEST_STATE[1], TEST_STATE[0]]);
+  });
+
   it('sets item at given position with handlers.setItem', () => {
     const hook = renderHook(() => useListState(TEST_STATE));
 

packages/@mantine/hooks/src/use-list-state/use-list-state.ts

@@ -14,6 +14,7 @@ export interface UseListStateHandlers<T> {
   ) => void;
   remove: (...indices: number[]) => void;
   reorder: ({ from, to }: { from: number; to: number }) => void;
+  swap: ({ from, to }: { from: number; to: number }) => void;
   setItem: (index: number, item: T) => void;
   setItemProp: <K extends keyof T, U extends T[K]>(index: number, prop: K, value: U) => void;
   filter: (fn: (item: T, i: number) => boolean) => void;
@@ -61,6 +62,18 @@ export function useListState<T>(initialValue: T[] = []): UseListState<T> {
       return cloned;
     });
 
+  const swap = ({ from, to }: { from: number; to: number }) =>
+    setState((current) => {
+      const cloned = [...current];
+      const fromItem = cloned[from];
+      const toItem = cloned[to];
+
+      cloned.splice(to, 1, fromItem);
+      cloned.splice(from, 1, toItem);
+
+      return cloned;
+    });
+
   const setItem = (index: number, item: T) =>
     setState((current) => {
       const cloned = [...current];
@@ -100,6 +113,7 @@ export function useListState<T>(initialValue: T[] = []): UseListState<T> {
       applyWhere,
       remove,
       reorder,
+      swap,
       setItem,
       setItemProp,
       filter,