@jeremyckahn/farmhand 1.20.1 → 1.20.2

package/src/hooks/useTabQueryParam.ts

@@ -0,0 +1,57 @@
+import { useEffect, useState } from 'react'
+
+import {
+  getHashQueryParams,
+  setHashQueryParam,
+} from '../utils/hashQueryParams.js'
+
+const TAB_QUERY_PARAM_NAME = 'tab'
+
+const getTabIndexFromHash = (tabLabels: readonly string[]): number => {
+  const tabLabelFromUrl = getHashQueryParams().get(TAB_QUERY_PARAM_NAME)
+  const tabIndexFromUrl = tabLabels.indexOf(tabLabelFromUrl ?? '')
+
+  return tabIndexFromUrl === -1 ? 0 : tabIndexFromUrl
+}
+
+/**
+ * Drop-in replacement for `useState(0)` for a MUI `Tabs`/`Tab` `value`,
+ * that also mirrors the active tab's label into the URL hash's `tab`
+ * query param so a page reload restores the same tab. Tabs are matched by
+ * label rather than raw index, since some screens conditionally omit tabs
+ * (e.g. Shop's Saplings tab), which shifts indices around depending on
+ * what's unlocked.
+ *
+ * `tabLabels` can legitimately change shape after the initial render (e.g.
+ * a screen mounts before its unlock-dependent tabs are known, then a
+ * persisted save loads a moment later and adds one) - re-deriving the
+ * index whenever the label list itself changes keeps the restored tab
+ * pointing at the right label instead of freezing on its first-render
+ * position.
+ */
+export const useTabQueryParam = (
+  tabLabels: readonly string[]
+): [number, (tabIndex: number) => void] => {
+  const [currentTab, setCurrentTabState] = useState(() =>
+    getTabIndexFromHash(tabLabels)
+  )
+
+  const tabLabelsKey = tabLabels.join('|')
+
+  useEffect(() => {
+    setCurrentTabState(getTabIndexFromHash(tabLabels))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tabLabelsKey])
+
+  const setCurrentTab = (tabIndex: number) => {
+    setCurrentTabState(tabIndex)
+
+    const tabLabel = tabLabels[tabIndex]
+
+    if (tabLabel) {
+      setHashQueryParam(TAB_QUERY_PARAM_NAME, tabLabel)
+    }
+  }
+
+  return [currentTab, setCurrentTab]
+}

package/src/setupTests.ts

@@ -52,4 +52,10 @@ beforeEach(() => {
 
 afterEach(() => {
   cleanup()
+  // Farmhand mirrors navigation state (current view, tabbed screens' active
+  // tab) into the real window.location.hash (see src/utils/hashQueryParams.ts),
+  // which - unlike React/component state - isn't reset between tests on its
+  // own and would otherwise leak into whichever test runs next in the same
+  // file.
+  window.history.replaceState({}, '', window.location.pathname)
 })

package/src/shell/hash-view-restoration.test.ts

@@ -0,0 +1,89 @@
+import { waitFor, within } from '@testing-library/react'
+
+import { saveDataStubFactory } from '../test-utils/stubs/saveDataStubFactory.js'
+import { farmhandStub } from '../test-utils/stubs/farmhandStub.js'
+
+describe('restoring stageFocus from the URL hash on boot', () => {
+  const getHeader = () => {
+    const [header] = Array.from(document.getElementsByTagName('header'))
+
+    return header
+  }
+
+  test('restores a view named in the URL hash when a fresh game has it unlocked', async () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FIELD`
+    )
+
+    await farmhandStub()
+
+    await waitFor(() => {
+      expect(within(getHeader()).getByText('Field')).toBeInTheDocument()
+    })
+  })
+
+  test('falls back to Home when a fresh game does not have the hash view unlocked', async () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FOREST`
+    )
+
+    await farmhandStub()
+
+    await waitFor(() => {
+      expect(within(getHeader()).getByText('Home')).toBeInTheDocument()
+    })
+    expect(within(getHeader()).queryByText('Forest')).not.toBeInTheDocument()
+  })
+
+  test('falls back to Home when the loaded save does not have the hash view unlocked', async () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FOREST`
+    )
+
+    const loadedState = saveDataStubFactory({
+      experience: 0,
+      purchasedForest: 0,
+    })
+
+    await farmhandStub({
+      localforage: {
+        getItem: () => Promise.resolve(loadedState),
+        setItem: (_key: string, data: unknown) => Promise.resolve(data),
+      },
+    })
+
+    await waitFor(() => {
+      expect(within(getHeader()).getByText('Home')).toBeInTheDocument()
+    })
+    expect(within(getHeader()).queryByText('Forest')).not.toBeInTheDocument()
+  })
+
+  test('restores the hash view when the loaded save does have it unlocked', async () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FOREST`
+    )
+
+    const loadedState = saveDataStubFactory({
+      experience: 20_000,
+    })
+
+    await farmhandStub({
+      localforage: {
+        getItem: () => Promise.resolve(loadedState),
+        setItem: (_key: string, data: unknown) => Promise.resolve(data),
+      },
+    })
+
+    await waitFor(() => {
+      expect(within(getHeader()).getByText('Forest')).toBeInTheDocument()
+    })
+  })
+})

package/src/shell/navigation.test.ts

@@ -13,7 +13,7 @@ describe('navigation', () => {
       await nextView()
       expect(within(header).getByText(viewName)).toBeInTheDocument()
     }
-  })
+  }, 10000)
 
   test('cycles backwards through the standard views', async () => {
     await farmhandStub()
@@ -23,7 +23,7 @@ describe('navigation', () => {
       await previousView()
       expect(within(header).getByText(viewName)).toBeInTheDocument()
     }
-  })
+  }, 10000)
 
   test('cycles forwards through the unlocked views', async () => {
     const loadedState = saveDataStubFactory({
@@ -43,7 +43,7 @@ describe('navigation', () => {
       await nextView()
       expect(within(header).getByText(viewName)).toBeInTheDocument()
     }
-  })
+  }, 10000)
 
   test('cycles backwards through the unlocked views', async () => {
     const loadedState = saveDataStubFactory({
@@ -63,5 +63,5 @@ describe('navigation', () => {
       await previousView()
       expect(within(header).getByText(viewName)).toBeInTheDocument()
     }
-  })
+  }, 10000)
 })

package/src/utils/getGrowingPhase.test.ts

@@ -11,4 +11,19 @@ describe('getGrowingPhase', () => {
 
     expect(getGrowingPhase(crop as any)).toEqual(phase)
   })
+
+  test.each([
+    [0, 2.5],
+    [4, 6.5],
+    [5, 7.5],
+    [6, 8.5],
+  ])(
+    'it handles fractional daysWatered correctly (returns phase %s when days watered is %s for pumpkin)',
+    (phase, daysWatered) => {
+      // pumpkin cropTimeline: [3, 1, 1, 1, 1, 1]
+      const crop = { itemId: 'pumpkin', daysWatered }
+
+      expect(getGrowingPhase(crop as any)).toEqual(phase)
+    }
+  )
 })

package/src/utils/getGrowingPhase.ts

@@ -2,23 +2,14 @@ import { itemsMap } from '../data/maps.js'
 import { LARGEST_PURCHASABLE_FIELD_SIZE } from '../constants.js'
 
 import { memoize } from './memoize.js'
+import { getGrowingPhaseForTimeline } from './getGrowingPhaseForTimeline.js'
 
 export const getGrowingPhase = memoize(
   (crop: farmhand.crop) => {
     const { itemId, daysWatered = 0 } = crop
     const { cropTimeline = [] } = itemsMap[itemId]
 
-    let daysGrowing = daysWatered + 1
-    let phase = 0
-
-    for (let value of cropTimeline) {
-      if (daysGrowing - value <= 0) break
-
-      daysGrowing -= value
-      phase += 1
-    }
-
-    return phase
+    return getGrowingPhaseForTimeline(cropTimeline, daysWatered)
   },
   {
     cacheSize:

package/src/utils/getGrowingPhaseForTimeline.ts

@@ -2,7 +2,7 @@ export const getGrowingPhaseForTimeline = (
   timeline: number[],
   daysElapsed: number
 ): number => {
-  let daysGrowing = daysElapsed + 1
+  let daysGrowing = Math.floor(daysElapsed) + 1
   let phase = 0
 
   for (const value of timeline) {

package/src/utils/getValidatedStageFocusFromHash.test.ts

@@ -0,0 +1,72 @@
+import { stageFocusType } from '../enums.js'
+
+import { getValidatedStageFocusFromHash } from './getValidatedStageFocusFromHash.js'
+
+const { FIELD, FOREST, HOME } = stageFocusType
+
+const defaultState = {
+  experience: 0,
+  purchasedCellar: 0,
+  purchasedCowPen: 0,
+  showHomeScreen: true,
+}
+
+describe('getValidatedStageFocusFromHash', () => {
+  test('returns undefined when the hash has no view param', () => {
+    window.history.replaceState({}, '', `${window.location.pathname}`)
+
+    expect(getValidatedStageFocusFromHash(defaultState)).toBeUndefined()
+  })
+
+  test('returns the view when it is unlocked for the given state', () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FIELD`
+    )
+
+    expect(getValidatedStageFocusFromHash(defaultState)).toEqual(FIELD)
+  })
+
+  test('returns undefined when the view is not unlocked for the given state', () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FOREST`
+    )
+
+    expect(getValidatedStageFocusFromHash(defaultState)).toBeUndefined()
+  })
+
+  test('returns the view once its unlock requirement is met', () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=FOREST`
+    )
+
+    expect(
+      getValidatedStageFocusFromHash({ ...defaultState, experience: 20_000 })
+    ).toEqual(FOREST)
+  })
+
+  test('returns undefined when the hash names a view outside stageFocusType entirely', () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=NOT_A_REAL_VIEW`
+    )
+
+    expect(getValidatedStageFocusFromHash(defaultState)).toBeUndefined()
+  })
+
+  test('returns HOME when showHomeScreen is true, matching the default view list', () => {
+    window.history.replaceState(
+      {},
+      '',
+      `${window.location.pathname}#?view=HOME`
+    )
+
+    expect(getValidatedStageFocusFromHash(defaultState)).toEqual(HOME)
+  })
+})

package/src/utils/getValidatedStageFocusFromHash.ts

@@ -0,0 +1,43 @@
+import { stageFocusType } from '../enums.js'
+
+import { getLevelEntitlements } from './getLevelEntitlements.js'
+import { getViewList } from './getViewList.js'
+import {
+  getHashQueryParams,
+  VIEW_QUERY_PARAM_NAME,
+} from './hashQueryParams.js'
+import { levelAchieved } from './levelAchieved.js'
+
+/**
+ * Reads the URL hash's `view` param and returns it only if it names a view
+ * that's actually unlocked for the given state - guards against a
+ * bookmarked/shared URL (or a stale browser history entry reached via
+ * back/forward) pointing at a screen the current save hasn't unlocked,
+ * since Stage.tsx renders whichever view stageFocus names with no unlock
+ * check of its own. Used both at boot and when reacting to popstate.
+ */
+export const getValidatedStageFocusFromHash = (
+  candidateState: Pick<
+    farmhand.state,
+    'experience' | 'purchasedCellar' | 'purchasedCowPen' | 'showHomeScreen'
+  >
+): farmhand.stageFocusType | undefined => {
+  const stageFocusFromUrl = getHashQueryParams().get(VIEW_QUERY_PARAM_NAME)
+
+  if (!stageFocusFromUrl) return undefined
+
+  const isForestUnlockedForState = getLevelEntitlements(
+    levelAchieved(candidateState.experience)
+  ).stageFocusType[stageFocusType.FOREST]
+
+  const availableViews = getViewList({
+    isForestUnlocked: isForestUnlockedForState,
+    purchasedCellar: candidateState.purchasedCellar,
+    purchasedCowPen: candidateState.purchasedCowPen,
+    showHomeScreen: candidateState.showHomeScreen,
+  })
+
+  return availableViews.find(
+    availableView => availableView === stageFocusFromUrl
+  )
+}

package/src/utils/getViewList.test.ts

@@ -0,0 +1,73 @@
+import { stageFocusType } from '../enums.js'
+
+import { getViewList } from './getViewList.js'
+
+const { CELLAR, COW_PEN, FIELD, HOME, SHOP, WORKSHOP, FOREST } = stageFocusType
+
+describe('getViewList', () => {
+  test('returns the standard views plus Home and Workshop by default', () => {
+    expect(
+      getViewList({
+        isForestUnlocked: false,
+        purchasedCellar: 0,
+        purchasedCowPen: 0,
+        showHomeScreen: true,
+      })
+    ).toEqual([HOME, SHOP, FIELD, WORKSHOP])
+  })
+
+  test('omits Home when showHomeScreen is false', () => {
+    expect(
+      getViewList({
+        isForestUnlocked: false,
+        purchasedCellar: 0,
+        purchasedCowPen: 0,
+        showHomeScreen: false,
+      })
+    ).toEqual([SHOP, FIELD, WORKSHOP])
+  })
+
+  test('includes Forest only when isForestUnlocked is true', () => {
+    expect(
+      getViewList({
+        isForestUnlocked: true,
+        purchasedCellar: 0,
+        purchasedCowPen: 0,
+        showHomeScreen: true,
+      })
+    ).toEqual([HOME, SHOP, FIELD, FOREST, WORKSHOP])
+  })
+
+  test('includes Cow Pen only when purchasedCowPen is truthy', () => {
+    expect(
+      getViewList({
+        isForestUnlocked: false,
+        purchasedCellar: 0,
+        purchasedCowPen: 1,
+        showHomeScreen: true,
+      })
+    ).toEqual([HOME, SHOP, FIELD, COW_PEN, WORKSHOP])
+  })
+
+  test('includes Cellar only when purchasedCellar is truthy', () => {
+    expect(
+      getViewList({
+        isForestUnlocked: false,
+        purchasedCellar: 1,
+        purchasedCowPen: 0,
+        showHomeScreen: true,
+      })
+    ).toEqual([HOME, SHOP, FIELD, WORKSHOP, CELLAR])
+  })
+
+  test('includes every optional view in the correct order when all are unlocked', () => {
+    expect(
+      getViewList({
+        isForestUnlocked: true,
+        purchasedCellar: 1,
+        purchasedCowPen: 1,
+        showHomeScreen: true,
+      })
+    ).toEqual([HOME, SHOP, FIELD, FOREST, COW_PEN, WORKSHOP, CELLAR])
+  })
+})

package/src/utils/getViewList.ts

@@ -0,0 +1,46 @@
+import { STANDARD_VIEW_LIST } from '../constants.js'
+import { stageFocusType } from '../enums.js'
+
+/**
+ * The ordered list of views available for a given state, mirroring what's
+ * actually unlocked (Home screen preference, Forest, Cow Pen, Cellar).
+ * Pulled out as a standalone function (rather than only living inline as a
+ * useMemo in useFarmhand.ts) so it can also be used to validate an
+ * externally-supplied view (e.g. from the URL hash) against a specific
+ * state snapshot - which may not be the live, currently-rendered state,
+ * such as a save being loaded during boot or import.
+ */
+export const getViewList = ({
+  isForestUnlocked,
+  purchasedCellar,
+  purchasedCowPen,
+  showHomeScreen,
+}: {
+  isForestUnlocked: boolean
+  purchasedCellar: number
+  purchasedCowPen: number
+  showHomeScreen: boolean
+}): farmhand.stageFocusType[] => {
+  const { CELLAR, COW_PEN, HOME, WORKSHOP, FOREST } = stageFocusType
+  const list: farmhand.stageFocusType[] = [...STANDARD_VIEW_LIST]
+
+  if (showHomeScreen) {
+    list.unshift(HOME)
+  }
+
+  if (isForestUnlocked) {
+    list.push(FOREST)
+  }
+
+  if (purchasedCowPen) {
+    list.push(COW_PEN)
+  }
+
+  list.push(WORKSHOP)
+
+  if (purchasedCellar) {
+    list.push(CELLAR)
+  }
+
+  return list
+}

package/src/utils/hashQueryParams.test.ts

@@ -0,0 +1,153 @@
+import {
+  getHashQueryParams,
+  removeHashQueryParam,
+  setHashQueryParam,
+  withCurrentHashQuery,
+} from './hashQueryParams.js'
+
+describe('hashQueryParams', () => {
+  describe('getHashQueryParams', () => {
+    test('returns an empty URLSearchParams when there is no hash', () => {
+      window.history.replaceState({}, '', `${window.location.pathname}`)
+
+      expect(getHashQueryParams().toString()).toEqual('')
+    })
+
+    test('parses query params from the hash', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#?view=SHOP&tab=Upgrades`
+      )
+
+      const params = getHashQueryParams()
+
+      expect(params.get('view')).toEqual('SHOP')
+      expect(params.get('tab')).toEqual('Upgrades')
+    })
+
+    test('parses query params from a hash with a router path prefix', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#online/my-room?view=FIELD`
+      )
+
+      expect(getHashQueryParams().get('view')).toEqual('FIELD')
+    })
+  })
+
+  describe('setHashQueryParam', () => {
+    test('adds a query param to an empty hash', () => {
+      window.history.replaceState({}, '', `${window.location.pathname}`)
+
+      setHashQueryParam('view', 'SHOP')
+
+      expect(window.location.hash).toEqual('#?view=SHOP')
+    })
+
+    test('preserves the hash path prefix', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#online/my-room`
+      )
+
+      setHashQueryParam('view', 'SHOP')
+
+      expect(window.location.hash).toEqual('#online/my-room?view=SHOP')
+    })
+
+    test('preserves other existing query params', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#?tab=Upgrades`
+      )
+
+      setHashQueryParam('view', 'SHOP')
+
+      const params = getHashQueryParams()
+
+      expect(params.get('view')).toEqual('SHOP')
+      expect(params.get('tab')).toEqual('Upgrades')
+    })
+
+    test('overwrites an existing value for the same key', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#?view=SHOP`
+      )
+
+      setHashQueryParam('view', 'FIELD')
+
+      expect(getHashQueryParams().get('view')).toEqual('FIELD')
+    })
+  })
+
+  describe('removeHashQueryParam', () => {
+    test('removes the given key, leaving other params intact', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#?view=SHOP&tab=Upgrades`
+      )
+
+      removeHashQueryParam('tab')
+
+      const params = getHashQueryParams()
+
+      expect(params.get('view')).toEqual('SHOP')
+      expect(params.has('tab')).toEqual(false)
+    })
+
+    test('drops the "?" entirely when removing the last param', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#online/my-room?tab=Upgrades`
+      )
+
+      removeHashQueryParam('tab')
+
+      expect(window.location.hash).toEqual('#online/my-room')
+    })
+
+    test('is a no-op when the key is not present', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#?view=SHOP`
+      )
+
+      removeHashQueryParam('tab')
+
+      expect(window.location.hash).toEqual('#?view=SHOP')
+    })
+  })
+
+  describe('withCurrentHashQuery', () => {
+    test('returns the path unchanged when the hash has no query params', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#online/my-room`
+      )
+
+      expect(withCurrentHashQuery('/')).toEqual('/')
+    })
+
+    test('appends the current hash query params to the given path', () => {
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}#?view=SHOP&tab=Upgrades`
+      )
+
+      expect(withCurrentHashQuery('/online/my-room')).toEqual(
+        '/online/my-room?view=SHOP&tab=Upgrades'
+      )
+    })
+  })
+})