@tastic/profile 0.3.8 → 0.7.0

package/src/redux/profileSelectionSlice.ts

@@ -0,0 +1,81 @@
+import { ActionCreator, createActionCreator } from './createActionCreator'
+
+// redux-persist's own REHYDRATE action-type constant, inlined as a literal rather than taking a
+// dependency on the package itself — this factory otherwise has no opinion on whether the
+// consuming app uses redux-persist at all, and the string itself is a long-stable part of
+// redux-persist's own public contract (unchanged across every major version). See the reducer's
+// own REHYDRATE case below for why this needs handling at all.
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface SelectProfilePayload<TSeat> {
+  profileId: string | null
+  seat: TSeat
+}
+
+export interface ProfileSelectionActions<TSeat> {
+  clearProfile: ActionCreator<string>
+  select: ActionCreator<SelectProfilePayload<TSeat>>
+}
+
+export type ProfileSelectionState<TSeat extends string | number> = Record<TSeat, string | null>
+
+export interface ProfileSelectionSlice<TSeat extends string | number> {
+  actions: ProfileSelectionActions<TSeat>
+  reducer: (state: ProfileSelectionState<TSeat> | undefined, action: { type: string; payload?: unknown }) => ProfileSelectionState<TSeat>
+}
+
+// Which profile each seat last picked — always local, never part of the shared App Group roster
+// (this package's own profiles slice, see profilesSlice.ts): who's selected on THIS device is
+// naturally a per-app, per-device thing, not something a sibling @tastic game should see or
+// influence. Five @tastic games (AirHockey, BoxHockey, Pong, LightCycles, Snake) each hand-rolled
+// an identical Record<Seat, string | null> reducer before this factory existed — same duplication
+// createProfileExtensionSlice generalized away for per-profile extensions, this is that shape for
+// per-seat selection instead.
+//
+// `namespace` prefixes every action type (e.g. 'profileSelection/loadout/select') so an app with
+// more than one independent seat-selection concern never collides between them — same convention
+// createProfileExtensionSlice's own namespace argument follows.
+//
+// Unlike createProfileExtensionSlice, the seat set can't be derived from TSeat alone (types don't
+// exist at runtime), so callers pass their own `defaultState` — the same literal object (e.g.
+// `{ 1: null, 2: null }`) each app already declares as its own `defaultProfileSelectionState`
+// constant today. `clearProfile` walks that state's own keys rather than assuming any particular
+// seat count, so it reproduces the 5 apps' current two-seat behavior without hardcoding "1"/"2".
+//
+// `mountKey` defaults to 'profileSelection' — the literal key every current consumer (AirHockey,
+// BoxHockey, Pong, LightCycles, Snake) already mounts this reducer under in its own
+// combineReducers({...}) call (e.g. `combineReducers({ ..., profileSelection })`). It has to be
+// passed explicitly rather than inferred, since redux-persist's REHYDRATE payload is keyed by
+// whatever name the app's own root reducer happens to use, which this factory has no way to see
+// from inside its own reducer function — only worth overriding if some future consumer ever mounts
+// this under a different key. Note `namespace` above is a different thing: it's the app's own name
+// (e.g. 'airhockey', 'boxhockey'), used only to prefix action types, not the mount key.
+export function createProfileSelectionSlice<TSeat extends string | number>(namespace: string, defaultState: ProfileSelectionState<TSeat>, mountKey = 'profileSelection'): ProfileSelectionSlice<TSeat> {
+  const select = createActionCreator<SelectProfilePayload<TSeat>>(`profileSelection/${namespace}/select`)
+  const clearProfile = createActionCreator<string>(`profileSelection/${namespace}/clearProfile`)
+
+  function reducer(state: ProfileSelectionState<TSeat> = defaultState, action: { type: string; payload?: unknown }): ProfileSelectionState<TSeat> {
+    // redux-persist's own default stateReconciler (autoMergeLevel1) HARD-REPLACES this slice's
+    // entire persisted sub-state on rehydration rather than backfilling missing fields (confirmed
+    // against autoMergeLevel1's actual source: `newState[key] = inboundState[key]`, not a merge) —
+    // so a device with a blob persisted before a new seat existed would otherwise rehydrate with
+    // that seat's key missing entirely, and every consumer indexes into it (`state[seat]`) with no
+    // fallback. Spreading `defaultState` first, then the incoming persisted value, backfills exactly
+    // that gap — the same pattern createSeatColorsSlice's own REHYDRATE case already uses.
+    if (action.type === REHYDRATE) {
+      const persisted = (action.payload as Record<string, Partial<ProfileSelectionState<TSeat>>> | undefined)?.[mountKey]
+      return { ...defaultState, ...state, ...persisted }
+    }
+    if (select.match(action)) return { ...state, [action.payload.seat]: action.payload.profileId } as ProfileSelectionState<TSeat>
+    if (clearProfile.match(action)) {
+      const next = { ...state }
+      for (const seat of Object.keys(state) as TSeat[]) {
+        if (next[seat] === action.payload) next[seat] = null
+      }
+      return next
+    }
+    return state
+  }
+
+  return { actions: { clearProfile, select }, reducer }
+}

package/src/redux/profilesSlice.ts

@@ -0,0 +1,47 @@
+import { Profile } from '../types'
+import { createActionCreator } from './createActionCreator'
+
+export interface UpdateProfilePayload {
+  id: string
+  patch: Partial<Pick<Profile, 'name' | 'color' | 'tag'>>
+}
+
+// setAll: full-replace, for hydrating from resolveInitialProfiles or a remote refresh
+// (useSharedProfilesSync's onRemoteChange). add/update/remove: the actual roster CRUD every
+// @tastic game already hand-rolled an identical version of in its own useProfiles.tsx.
+const setAll = createActionCreator<Profile[]>('profiles/setAll')
+const add = createActionCreator<Profile>('profiles/add')
+const update = createActionCreator<UpdateProfilePayload>('profiles/update')
+const remove = createActionCreator<string>('profiles/remove')
+
+export const profilesActions = { add, remove, setAll, update }
+
+export function profilesReducer(state: Profile[] = [], action: { type: string }): Profile[] {
+  if (setAll.match(action)) return action.payload
+  if (add.match(action)) return [...state, action.payload]
+  if (update.match(action)) {
+    const { id, patch } = action.payload
+    return state.map((p) => (p.id === id ? { ...p, ...patch, updatedAt: Date.now() } : p))
+  }
+  if (remove.match(action)) return state.filter((p) => p.id !== action.payload)
+  return state
+}
+
+function generateProfileId(): string {
+  return `profile-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+export interface CreateProfileInput {
+  name: string
+  color: string
+  tag: string
+}
+
+// Builds a complete Profile (id + timestamps) ready to dispatch via profilesActions.add. Kept as
+// its own plain function rather than folded into the `add` action creator, so `add` itself stays a
+// simple "append this exact record" primitive (useful for rehydration/tests too, where the record
+// already exists and shouldn't get a second, different id/timestamp minted for it).
+export function createProfileRecord(input: CreateProfileInput): Profile {
+  const now = Date.now()
+  return { color: input.color, createdAt: now, id: generateProfileId(), name: input.name, tag: input.tag, updatedAt: now }
+}

package/src/redux/resolveInitialProfiles.ts

@@ -0,0 +1,26 @@
+import { isSharedProfileStoreAvailable, loadSharedProfiles, saveSharedProfiles } from '../sharedProfileStore'
+import { Profile } from '../types'
+
+// Resolves the roster an app should start with, given whatever it already had saved in its own
+// local fallback storage (however that app stores it — this never touches AsyncStorage itself,
+// only the shared App Group store via loadSharedProfiles/saveSharedProfiles). Every @tastic game
+// hand-rolled an identical version of this exact decision inline in its own useProfiles.tsx; this
+// is that logic, extracted verbatim.
+//
+// - Shared store unavailable (Android/web, or an iOS build that hasn't run `expo prebuild` since
+//   the entitlement was added): `localFallback` IS the roster, verbatim.
+// - Shared store available, and genuinely empty: either a first launch, or the first time THIS
+//   app has synced since the App Group entitlement was added — seed it from `localFallback` (so
+//   an upgrading user's own profiles don't just vanish), and mirror that seed to the shared store
+//   (fire-and-forget; a failed seed write just means the next successful write catches up).
+// - Shared store available and non-empty: shared always wins over a stale local snapshot, never
+//   merged with it — avoids resurrecting a profile that was deleted from another app.
+export async function resolveInitialProfiles(groupId: string, localFallback: Profile[]): Promise<Profile[]> {
+  if (!isSharedProfileStoreAvailable) return localFallback
+  const shared = await loadSharedProfiles(groupId)
+  if (shared.length === 0 && localFallback.length > 0) {
+    saveSharedProfiles(groupId, localFallback).catch(() => {})
+    return localFallback
+  }
+  return shared
+}

package/src/redux/seatColorsSlice.ts

@@ -0,0 +1,96 @@
+import { ActionCreator, createActionCreator } from './createActionCreator'
+
+// redux-persist's own REHYDRATE action-type constant, inlined as a literal rather than taking a
+// dependency on the package itself — this factory otherwise has no opinion on whether the
+// consuming app uses redux-persist at all, and the string itself is a long-stable part of
+// redux-persist's own public contract (unchanged across every major version). See the reducer's
+// own REHYDRATE case below for why this needs handling at all.
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface SetLastGuestColorPayload<TSeat> {
+  color: string
+  seat: TSeat
+}
+
+export interface SetProfileOverridePayload<TSeat> {
+  color: string | null
+  seat: TSeat
+}
+
+export interface SeatColorsActions<TSeat> {
+  setLastCpuColor: ActionCreator<string>
+  setLastGuestColor: ActionCreator<SetLastGuestColorPayload<TSeat>>
+  setProfileOverride: ActionCreator<SetProfileOverridePayload<TSeat>>
+}
+
+export type SeatColorsState<TSeat extends string | number> = {
+  lastCpuColor: string
+  lastGuestColor: Record<TSeat, string>
+  profileOverride: Record<TSeat, string | null>
+}
+
+export interface SeatColorsSlice<TSeat extends string | number> {
+  actions: SeatColorsActions<TSeat>
+  reducer: (state: SeatColorsState<TSeat> | undefined, action: { type: string; payload?: unknown }) => SeatColorsState<TSeat>
+}
+
+// Which color a seat should show right now, remembered independently for three sources that must
+// never fight over one value: a guest seat's own last pick, the CPU seat's own last pick, and a
+// manual recolor/clash-swap override landing on a seat that currently has a profile selected (null
+// meaning "no override, track that profile's own saved color live"). Four @tastic games (AirHockey,
+// BoxHockey, LightCycles, Pong) each hand-rolled an identical dedicated seatColorsSlice.ts — same
+// three fields, same createSlice-based reducer, differing only in their own seat type's name
+// (Player) and default-color constants — before this factory existed; this is that shape,
+// generalized over the seat type exactly like createProfileSelectionSlice generalized per-seat
+// profile selection.
+//
+// Snake has the same three fields too, but folded directly into its own catch-all gameSlice.ts
+// alongside a dozen unrelated persisted settings (wrapEdges, cpuDifficulty, speedTier, ...) rather
+// than in a standalone slice of their own. There's no separate `seatColors` sub-state there for this
+// factory's reducer to own without restructuring gameSlice's top-level shape to nest these three
+// fields under their own key first — a real state-shape migration (and a redux-persist rehydration
+// concern, see gameSlice's own REHYDRATE extraReducer), not a drop-in swap. This factory
+// intentionally targets the standalone-slice shape the other four apps already have; Snake staying
+// hand-rolled inside gameSlice is a deliberate scope call for this pass, not an oversight.
+//
+// `namespace` prefixes every action type (e.g. 'seatColors/loadout/setLastGuestColor') so an app
+// with more than one independent seat-colors concern never collides between them — same convention
+// createProfileSelectionSlice's and createProfileExtensionSlice's own namespace arguments follow.
+//
+// Unlike createProfileExtensionSlice, the seat set can't be derived from TSeat alone (types don't
+// exist at runtime), so callers pass their own `defaultState` — same reasoning, and the same
+// {1: ..., 2: ...}-shaped literal each app already declares as its own defaultSeatColorsState
+// constant today, as createProfileSelectionSlice's own defaultState parameter.
+//
+// `mountKey` defaults to 'seatColors' — the literal key every current consumer (AirHockey,
+// BoxHockey, Pong) already mounts this reducer under in its own combineReducers({...}) call (e.g.
+// `combineReducers({ ..., seatColors })`). It has to be passed explicitly rather than inferred,
+// since redux-persist's REHYDRATE payload is keyed by whatever name the app's own root reducer
+// happens to use, which this factory has no way to see from inside its own reducer function — only
+// worth overriding if some future consumer ever mounts this under a different key.
+export function createSeatColorsSlice<TSeat extends string | number>(namespace: string, defaultState: SeatColorsState<TSeat>, mountKey = 'seatColors'): SeatColorsSlice<TSeat> {
+  const setLastCpuColor = createActionCreator<string>(`seatColors/${namespace}/setLastCpuColor`)
+  const setLastGuestColor = createActionCreator<SetLastGuestColorPayload<TSeat>>(`seatColors/${namespace}/setLastGuestColor`)
+  const setProfileOverride = createActionCreator<SetProfileOverridePayload<TSeat>>(`seatColors/${namespace}/setProfileOverride`)
+
+  function reducer(state: SeatColorsState<TSeat> = defaultState, action: { type: string; payload?: unknown }): SeatColorsState<TSeat> {
+    // redux-persist's own default stateReconciler (autoMergeLevel1) HARD-REPLACES this slice's
+    // entire persisted sub-state on rehydration rather than backfilling missing fields (confirmed
+    // against autoMergeLevel1's actual source: `newState[key] = inboundState[key]`, not a merge) —
+    // so a device with a blob persisted before `profileOverride` existed would otherwise rehydrate
+    // with `state.profileOverride === undefined`, and every consumer indexes into it (`profileOverride[seat]`)
+    // with no fallback, throwing. Spreading `defaultState` first, then the incoming persisted
+    // value, backfills exactly that gap — the same pattern Snake's own hand-rolled `gameSlice.ts`
+    // already uses for its equivalent (non-factory) fields via its own REHYDRATE extraReducer.
+    if (action.type === REHYDRATE) {
+      const persisted = (action.payload as Record<string, Partial<SeatColorsState<TSeat>>> | undefined)?.[mountKey]
+      return { ...defaultState, ...state, ...persisted }
+    }
+    if (setLastCpuColor.match(action)) return { ...state, lastCpuColor: action.payload }
+    if (setLastGuestColor.match(action)) return { ...state, lastGuestColor: { ...state.lastGuestColor, [action.payload.seat]: action.payload.color } as Record<TSeat, string> }
+    if (setProfileOverride.match(action)) return { ...state, profileOverride: { ...state.profileOverride, [action.payload.seat]: action.payload.color } as Record<TSeat, string | null> }
+    return state
+  }
+
+  return { actions: { setLastCpuColor, setLastGuestColor, setProfileOverride }, reducer }
+}

package/src/redux/useSharedProfilesSync.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useRef } from 'react'
+import { AppState } from 'react-native'
+
+import { isSharedProfileStoreAvailable, loadSharedProfiles, saveSharedProfiles } from '../sharedProfileStore'
+import { Profile } from '../types'
+
+export interface UseSharedProfilesSyncOptions {
+  groupId: string
+  // Called with a freshly-read shared roster whenever the app returns to the foreground — the
+  // shared store has no cross-process change notification, so this is what catches "edited a
+  // profile in a different @tastic app, then switched back to this one." Skipped while a
+  // syncToShared write is still in flight (see pendingWriteRef below), and never called at all
+  // when the shared store isn't available.
+  onRemoteChange: (profiles: Profile[]) => void
+}
+
+export interface UseSharedProfilesSyncResult {
+  // Call right after applying a roster change locally (dispatching profilesActions.setAll/add/
+  // update/remove) to mirror it to the shared store. No-ops when the shared store isn't available
+  // — the caller is responsible for its own local persistence in that case, same as before this
+  // hook existed. Fire-and-forget: never throws, never awaited by this hook itself.
+  syncToShared: (next: Profile[]) => void
+}
+
+// Bundles the two things every @tastic game needs around the shared App Group roster once
+// `profiles` lives in its own Redux store: mirroring local writes out to the shared store, and
+// picking up remote writes a sibling app made while this one was backgrounded. Deliberately
+// separate from resolveInitialProfiles — that one's for the one-time initial load, this one's for
+// the app's whole lifetime after that.
+export function useSharedProfilesSync({ groupId, onRemoteChange }: UseSharedProfilesSyncOptions): UseSharedProfilesSyncResult {
+  // True for the duration of an in-flight syncToShared write — the foreground-refresh effect below
+  // skips a refresh while this is true, rather than risk reading back a pre-write snapshot and
+  // handing the caller an onRemoteChange that reverts the write still landing. A ref, not state:
+  // read from inside the AppState listener's closure, which is only created once per subscription
+  // and would otherwise see whatever this was at mount time, forever.
+  const pendingWriteRef = useRef(false)
+  // Same reasoning, for onRemoteChange itself — an app typically passes an inline callback that
+  // closes over its own latest dispatch/state, so the listener must always call the current one,
+  // not whichever was in scope when the effect below first subscribed.
+  const onRemoteChangeRef = useRef(onRemoteChange)
+  useEffect(() => {
+    onRemoteChangeRef.current = onRemoteChange
+  }, [onRemoteChange])
+
+  useEffect(() => {
+    if (!isSharedProfileStoreAvailable) return
+    let cancelled = false
+    const sub = AppState.addEventListener('change', (next) => {
+      if (next !== 'active' || pendingWriteRef.current) return
+      loadSharedProfiles(groupId).then((shared) => {
+        if (!cancelled) onRemoteChangeRef.current(shared)
+      })
+    })
+    return () => {
+      cancelled = true
+      sub.remove()
+    }
+  }, [groupId])
+
+  const syncToShared = useCallback(
+    (next: Profile[]) => {
+      if (!isSharedProfileStoreAvailable) return
+      pendingWriteRef.current = true
+      saveSharedProfiles(groupId, next)
+        .catch(() => {})
+        .finally(() => {
+          pendingWriteRef.current = false
+        })
+    },
+    [groupId]
+  )
+
+  return { syncToShared }
+}