feat(Pairing): add nextFocalId cycle math and expose slice API

src/entities/Pairing/domain/nextFocalId/nextFocalId.ts

@@ -0,0 +1,21 @@
+/**
+ * The id one step from `currentId` in board order, wrapping at both ends.
+ *
+ * @param orderedIds - Pairing ids in board order.
+ * @param currentId - The currently focal id to step from.
+ * @param direction - +1 for next, -1 for previous.
+ * @returns The neighbouring id (wrapped), `currentId` unchanged if it isn't in
+ * the list, or null for an empty list.
+ */
+export function nextFocalId(orderedIds: string[], currentId: string, direction: 1 | -1): string | null {
+    if (orderedIds.length === 0) {
+        return null;
+    }
+    const i = orderedIds.indexOf(currentId);
+    if (i === -1) {
+        return currentId;
+    }
+    const len = orderedIds.length;
+    const next = (i + direction + len) % len;
+    return orderedIds[next];
+}