Increment current player at start of phase in TurnOrder.DEFAULT (#521)

* feat(core): Increment currentPlayer in TurnOrder.DEFAULT.first

Increments the current player at the start of phases when using TurnOrder.DEFAULT (which currently
maintains the player across phase changes). Includes a check so that the player is NOT incremented
at the start of a game.

BREAKING CHANGE: The current player is now incremented at the start of a new phase. Previously the
current player was unchanged when a phase ended.

* test(core): Fix TurnOrder.DEFAULT test for new behaviour

* test(core): Fix flow tests for new default turn order

* feat(core): Add TurnOrder.CONTINUE to provide legacy behaviour

This implements the previous TurnOrder.DEFAULT for those who need this 
less common pattern.

* test(core): Add test for TurnOrder.CONTINUE

* docs: Document TurnOrder.CONTINUE

docs/documentation/turn-order.md

@@ -63,10 +63,16 @@ specify any turn order.
 
 ##### RESET
 
-This is similar to `DEFAULT`, but instead of continuing
-from the previous position at the beginning of a phase, it
+This is similar to `DEFAULT`, but instead of incrementing
+the previous position at the beginning of a phase, it
 will always start from `0`.
 
+##### CONTINUE
+
+This is also similar to `DEFAULT`, but instead of incrementing
+the previous position at the beginning of a phase, it will
+start with the player who ended the previous phase.
+
 ##### ONCE
 
 This is another round-robin, but it goes around only once.

src/core/flow.test.js

@@ -137,7 +137,7 @@ describe('phases', () => {
     expect(state.ctx.phase).toBe(null);
   });
 
-  test('maintain playOrderPos on phase end', () => {
+  test('increment playOrderPos on phase end', () => {
     const flow = Flow({
       phases: { A: { start: true, next: 'B' }, B: { next: 'A' } },
     });
@@ -148,7 +148,7 @@ describe('phases', () => {
     state = flow.processEvent(state, gameEvent('endTurn'));
     expect(state.ctx.playOrderPos).toBe(1);
     state = flow.processEvent(state, gameEvent('endPhase'));
-    expect(state.ctx.playOrderPos).toBe(1);
+    expect(state.ctx.playOrderPos).toBe(2);
   });
 
   describe('setPhase', () => {
@@ -282,10 +282,11 @@ describe('turn', () => {
 
       expect(state.ctx.phase).toBe('B');
       expect(state.ctx.turn).toBe(3);
-      expect(state.ctx.currentPlayer).toBe('1');
+      expect(state.ctx.currentPlayer).toBe('0');
 
-      state = flow.processMove(state, makeMove('move', null, '1').payload);
+      state = flow.processMove(state, makeMove('move', null, '0').payload);
       expect(state.ctx.turn).toBe(4);
+      expect(state.ctx.currentPlayer).toBe('1');
     });
   });
 
@@ -364,7 +365,7 @@ describe('turn', () => {
     state = flow.processMove(state, makeMove().payload);
 
     expect(state.ctx.phase).toBe('B');
-    expect(state.ctx.currentPlayer).toBe('1');
+    expect(state.ctx.currentPlayer).toBe('0');
     expect(state.ctx.turn).toBe(3);
   });
 });

src/core/turn-order.js

@@ -314,7 +314,10 @@ export const TurnOrder = {
    * The default round-robin turn order.
    */
   DEFAULT: {
-    first: (G, ctx) => ctx.playOrderPos,
+    first: (G, ctx) =>
+      ctx.turn === 0
+        ? ctx.playOrderPos
+        : (ctx.playOrderPos + 1) % ctx.playOrder.length,
     next: (G, ctx) => (ctx.playOrderPos + 1) % ctx.playOrder.length,
   },
 
@@ -328,6 +331,16 @@ export const TurnOrder = {
     next: (G, ctx) => (ctx.playOrderPos + 1) % ctx.playOrder.length,
   },
 
+  /**
+   * CONTINUE
+   *
+   * Similar to DEFAULT, but starts with the player who ended the last phase.
+   */
+  CONTINUE: {
+    first: (G, ctx) => ctx.playOrderPos,
+    next: (G, ctx) => (ctx.playOrderPos + 1) % ctx.playOrder.length,
+  },
+
   /**
    * ONCE
    *

src/core/turn-order.test.js

@@ -58,6 +58,29 @@ describe('turn orders', () => {
     expect(state.ctx.currentPlayer).toBe('0');
     expect(state.ctx).not.toHaveUndefinedProperties();
 
+    state = flow.processEvent(state, gameEvent('endTurn'));
+    expect(state.ctx.currentPlayer).toBe('1');
+    state = flow.processEvent(state, gameEvent('endTurn'));
+    expect(state.ctx.currentPlayer).toBe('0');
+    state = flow.processEvent(state, gameEvent('endTurn'));
+    expect(state.ctx.currentPlayer).toBe('1');
+    expect(state.ctx.phase).toBe('A');
+    state = flow.processEvent(state, gameEvent('endPhase'));
+    expect(state.ctx.currentPlayer).toBe('0');
+    expect(state.ctx.phase).toBe('B');
+  });
+
+  test('CONTINUE', () => {
+    const flow = Flow({
+      turn: { order: TurnOrder.CONTINUE },
+      phases: { A: { start: true, next: 'B' }, B: {} },
+    });
+
+    let state = { ctx: flow.ctx(2) };
+    state = flow.init(state);
+    expect(state.ctx.currentPlayer).toBe('0');
+    expect(state.ctx).not.toHaveUndefinedProperties();
+
     state = flow.processEvent(state, gameEvent('endTurn'));
     expect(state.ctx.currentPlayer).toBe('1');
     state = flow.processEvent(state, gameEvent('endTurn'));