@tastic/hud 0.12.0 → 0.14.0

package/src/guide/SwipeHint.tsx

@@ -0,0 +1,115 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { useEffect } from 'react'
+import { StyleSheet, View } from 'react-native'
+import { Icon } from 'react-native-paper'
+import Animated, { Easing, useAnimatedStyle, useReducedMotion, useSharedValue, withRepeat, withSequence, withTiming } from 'react-native-reanimated'
+
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right'
+export type SwipePointer = 'finger' | 'mouse'
+
+export interface SwipeHintProps {
+  direction?: SwipeDirection
+  // What sweeps along the path: a fingertip ring (a touch screen) or a mouse (a desktop seat that
+  // plays by dragging). The mouse variant also relabels itself "Drag" for screen readers, since a
+  // desktop player should never be told to swipe.
+  pointer?: SwipePointer
+  // Defaults to the theme's own primary — i.e. the player's own seat color in the fleet games.
+  color?: string
+  // Length of the dotted path in points, arrowhead excluded.
+  length?: number
+}
+
+const DOT_COUNT = 7
+const FINGER_SIZE = 28
+const MOUSE_SIZE = 30
+const SWEEP_MS = 900
+const PAUSE_MS = 500
+
+const ARROW_ICON: Record<SwipeDirection, string> = { up: 'arrow-up', down: 'arrow-down', left: 'arrow-left', right: 'arrow-right' }
+
+// A finger-sized ring (or, with pointer='mouse', a mouse) sweeping along a dotted path toward an
+// arrowhead, on a loop — the "swipe this way" illustration the arcade games (LightCycles, Snake, Pong,
+// AirHockey, BoxHockey) each need for their first card, so it lives here once rather than being
+// redrawn per app. The mouse variant is the same card on desktop web for a seat that plays by
+// dragging; Snake and AirHockey each drew their own before it existed. Plain Views plus Reanimated:
+// no Skia, no SVG, so it renders identically in every consuming app (Hangman, which has neither,
+// included). Under reduced motion the pointer just rests at the midpoint, still visible.
+export function SwipeHint({ direction = 'right', pointer = 'finger', color, length = 96 }: SwipeHintProps) {
+  const { colors } = useAutoPaperTheme()
+  const tint = color ?? colors.primary
+  const reducedMotion = useReducedMotion()
+  const progress = useSharedValue(0.5)
+  const horizontal = direction === 'left' || direction === 'right'
+  // Which way the finger travels along its own axis — left/up run against the positive x/y axes.
+  const sign = direction === 'right' || direction === 'down' ? 1 : -1
+
+  useEffect(() => {
+    if (reducedMotion) {
+      progress.value = 0.5
+      return
+    }
+    // Sweep out, hold (the ring fades while it rests at the end), then snap back to the start.
+    progress.value = 0
+    progress.value = withRepeat(withSequence(withTiming(1, { duration: SWEEP_MS, easing: Easing.out(Easing.cubic) }), withTiming(1, { duration: PAUSE_MS }), withTiming(0, { duration: 0 })), -1)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reducedMotion])
+
+  const fingerStyle = useAnimatedStyle(() => {
+    const travel = (progress.value - 0.5) * length * sign
+    return {
+      opacity: reducedMotion ? 1 : Math.min(1, progress.value * 6, (1 - progress.value) * 6 + 0.001),
+      transform: horizontal ? [{ translateX: travel }] : [{ translateY: travel }]
+    }
+  })
+
+  const axis = horizontal ? (sign > 0 ? 'row' : 'row-reverse') : sign > 0 ? 'column' : 'column-reverse'
+
+  return (
+    <View accessibilityLabel={`${pointer === 'mouse' ? 'Drag' : 'Swipe'} ${direction}`} accessible style={[styles.path, { flexDirection: axis }]}>
+      <View style={[styles.dots, { flexDirection: axis, [horizontal ? 'width' : 'height']: length }]}>
+        {Array.from({ length: DOT_COUNT }, (_, i) => (
+          <View key={i} style={[styles.dot, { backgroundColor: tint, opacity: 0.35 + (0.65 * i) / (DOT_COUNT - 1) }]} />
+        ))}
+      </View>
+      <Icon source={ARROW_ICON[direction]} size={28} color={tint} />
+      {pointer === 'mouse' ? (
+        <Animated.View style={[styles.mouse, fingerStyle]}>
+          <Icon source='mouse' size={MOUSE_SIZE} color={tint} />
+        </Animated.View>
+      ) : (
+        <Animated.View style={[styles.finger, { borderColor: tint }, fingerStyle]} />
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  dot: {
+    borderRadius: 3,
+    height: 6,
+    width: 6
+  },
+  dots: {
+    alignItems: 'center',
+    justifyContent: 'space-between'
+  },
+  // Centered on the whole path (not on the dots row alone) by the container's own alignItems/
+  // justifyContent, then pushed along the axis by its own animated translate — absolute so it never
+  // takes space from the dots and arrowhead it's drawn over.
+  finger: {
+    borderRadius: FINGER_SIZE / 2,
+    borderWidth: 3,
+    height: FINGER_SIZE,
+    position: 'absolute',
+    width: FINGER_SIZE
+  },
+  // Positioned exactly like `finger` (absolute, centered by the container, moved by the same animated
+  // translate); only what's drawn differs.
+  mouse: {
+    position: 'absolute'
+  },
+  path: {
+    alignItems: 'center',
+    justifyContent: 'center'
+  }
+})

package/src/guide/guideSlice.ts

@@ -0,0 +1,131 @@
+// redux-persist's own REHYDRATE action-type constant, inlined as a literal rather than taking a
+// dependency on the package itself — same reasoning as @tastic/profile's createSeatColorsSlice, whose
+// factory shape this follows: this file has no opinion on whether the consuming app uses
+// redux-persist at all, and the string is a long-stable part of its public contract.
+const REHYDRATE = 'persist/REHYDRATE'
+
+export interface GuideState {
+  // The highest guide version this player has finished or skipped — 0 means "never". Compared
+  // against the app's own `currentVersion`, so bumping that later re-prompts everyone (only worth
+  // doing for a genuine controls/rules change, not a copy tweak).
+  versionSeen: number
+}
+
+// A `type` alias, not an `interface`, on purpose: redux's UnknownAction has a string index signature,
+// and only an object-literal type alias (never an interface) is implicitly assignable to one — with an
+// interface here `configureStore` rejects the reducer at the consuming app's own typecheck.
+export type GuideAction = {
+  type: string
+  payload?: unknown
+  // Present on redux-persist's own REHYDRATE action (the persistConfig `key` it belongs to).
+  key?: string
+}
+
+export interface GuideSliceOptions {
+  // What a player who has already seen (or been grandfathered past) the guide is stamped with.
+  currentVersion: number
+  // The key the reducer is mounted under in the app's own combineReducers({...}) — redux-persist's
+  // REHYDRATE payload is keyed by it, and a reducer has no way to see its own mount key.
+  mountKey?: string
+  // The persistConfig `key` of the store this reducer lives in. A REHYDRATE for any OTHER persisted
+  // reducer (a nested persistReducer) carries that reducer's own substate, which would otherwise
+  // look exactly like "an existing player with no guide key".
+  persistKey?: string
+}
+
+export interface GuideSlice {
+  actions: { markSeen: (version: number) => { type: string; payload: number } }
+  reducer: (state: GuideState | undefined, action: GuideAction) => GuideState
+  selectVersionSeen: (rootState: object) => number
+}
+
+// The persisted "has this player seen the how-to-play flow" flag, as its own slice rather than a
+// field on any app's settings blob — every fleet app already has a redux-persist root store behind a
+// PersistGate, and a dedicated key survives 'Reset stats'/'Reset match settings' (neither touches
+// Redux) without needing any of the four strict per-app settings validators to learn a new field.
+//
+// The one thing a plain settings field can't do, and the reason this is a factory instead of a
+// createSettingsSlice call: tell a FRESH install from an EXISTING player who just updated. On a
+// fresh install redux-persist's getStoredState finds nothing under the persistConfig key and
+// REHYDRATE arrives with `payload === undefined`; an existing player has a payload object that
+// simply predates this slice and so has no `[mountKey]` entry. The first shows the guide; the
+// second is grandfathered — stamped as already having seen `currentVersion` — so nobody who has been
+// playing gets a "how to play" screen after an over-the-air update. Both can still replay it from
+// Settings.
+//
+// redux-persist's default stateReconciler (autoMergeLevel1) skips any substate a reducer already
+// changed while handling REHYDRATE, so the value returned here for an existing player wins rather
+// than being overwritten.
+export function createGuideSlice({ currentVersion, mountKey = 'guide', persistKey = 'root' }: GuideSliceOptions): GuideSlice {
+  const MARK_SEEN = `${mountKey}/markSeen`
+  const initialState: GuideState = { versionSeen: 0 }
+
+  function markSeen(version: number) {
+    return { type: MARK_SEEN, payload: version }
+  }
+
+  function reducer(state: GuideState = initialState, action: GuideAction): GuideState {
+    if (action.type === REHYDRATE) {
+      if (action.key !== undefined && action.key !== persistKey) return state
+      const payload = action.payload as Record<string, Partial<GuideState> | undefined> | undefined
+      // Nothing persisted at all (fresh install) — or the read failed, which shows the guide once
+      // more rather than silently skipping it.
+      if (!payload) return state
+      const persisted = payload[mountKey]
+      if (typeof persisted?.versionSeen === 'number') return { versionSeen: persisted.versionSeen }
+      return { versionSeen: currentVersion }
+    }
+    if (action.type === MARK_SEEN && typeof action.payload === 'number') {
+      return { versionSeen: Math.max(state.versionSeen, action.payload) }
+    }
+    return state
+  }
+
+  function selectVersionSeen(rootState: object): number {
+    return (rootState as Record<string, GuideState | undefined>)[mountKey]?.versionSeen ?? 0
+  }
+
+  return { actions: { markSeen }, reducer, selectVersionSeen }
+}
+
+// The one AsyncStorage call createReturningPlayerMigrate needs, passed in (apps pass AsyncStorage
+// itself) so this entry point never imports it.
+export interface GuideStorageReader {
+  getItem: (key: string) => Promise<string | null>
+}
+
+// Structurally identical to redux-persist's own PersistedState, so the returned function drops straight
+// into a persistConfig's `migrate` without this package depending on redux-persist.
+export type GuidePersistedState = { _persist: { version: number; rehydrated: boolean } } | undefined
+
+// For a persistConfig's `migrate`. createGuideSlice grandfathers a player by finding a persisted root
+// store with no guide entry in it, which only works for a player whose last build already HAD that root
+// store. Most of the fleet (LightCycles, AirHockey, BoxHockey, Pong) only got a redux-persist root store
+// after its last shipped update, so their current players have no root store at all: on their first
+// launch of a guide build REHYDRATE would arrive with no payload, exactly like a fresh install, and the
+// guide would greet people who've been playing for weeks.
+//
+// Those earlier builds did write their own AsyncStorage keys (settings, stats, appearance, ...), which
+// are passed in as `legacyKeys`. So: no root store, but any legacy key present, means "played an earlier
+// build", and that player is rehydrated with an empty payload instead, which the guide slice reads as an
+// existing player and stamps as seen. An empty payload is a no-op for every other slice (nothing to merge,
+// and redux-persist's reconciler skips `_persist`). A root store that already exists passes through
+// untouched, so this is a no-op for every launch after the first. A failed read falls back to the
+// fresh-install behavior (the guide shows once), the same as the slice itself.
+//
+// Runs before REHYDRATE and before PersistGate lets anything render, so there's no race with Home's
+// auto-show. List the keys the shipped builds actually wrote (read them from the last shipped commit, not
+// today's source). The one thing to avoid is a key today's build writes BEFORE PersistGate opens: on a
+// fresh install that would already exist by the time this runs, and the fresh install would be taken for
+// a returning player.
+export function createReturningPlayerMigrate(storage: GuideStorageReader, legacyKeys: readonly string[]) {
+  return async (state: GuidePersistedState, version: number): Promise<GuidePersistedState> => {
+    if (state !== undefined || legacyKeys.length === 0) return state
+    try {
+      const values = await Promise.all(legacyKeys.map((key) => storage.getItem(key)))
+      return values.some((value) => value !== null) ? { _persist: { version, rehydrated: false } } : undefined
+    } catch {
+      return undefined
+    }
+  }
+}

package/src/guide/index.ts

@@ -0,0 +1,14 @@
+// The how-to-play entry point (`@tastic/hud/guide`) — a standalone build reachable without ever
+// touching the main barrel, the same reason `@tastic/hud/skia-gate` is. This file and everything it
+// imports must stay free of @tastic/core, @tastic/profile, @tastic/split-screen, @tastic/achievements,
+// @rific/updater and Skia: those are optional peers of this package (see package.json's
+// peerDependenciesMeta) precisely so an app like Hangman, which has none of them, can install
+// @tastic/hud and use only this. src/__tests__/guideImports.test.ts enforces it.
+export { type DirectionKeyLabels, type DirectionKeysAxis, DirectionKeysHint, type DirectionKeysHintProps } from './DirectionKeysHint'
+export { GuideProvider, type GuideProviderProps, useAutoShowGuide, useGuide } from './GuideProvider'
+export { createGuideSlice, createReturningPlayerMigrate, type GuideAction, type GuidePersistedState, type GuideSlice, type GuideSliceOptions, type GuideState, type GuideStorageReader } from './guideSlice'
+export { getGuideCardSize, HowToPlayDialog, type HowToPlayDialogProps } from './HowToPlayDialog'
+export { type SeatDevice, SeatDevicesHint, type SeatDevicesHintProps } from './SeatDevicesHint'
+export { SeatDiagram, type SeatDiagramProps } from './SeatDiagram'
+export { type SwipeDirection, SwipeHint, type SwipeHintProps, type SwipePointer } from './SwipeHint'
+export type { GuideRotation, GuideStep } from './types'

package/src/guide/types.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react'
+
+// One card of a game's how-to-play flow. Content is app-local data, not something this package
+// authors: only the app knows its own controls, its own key schemes on desktop web, its own win
+// condition. `art` is whatever illustrates the idea — a `SwipeHint`/`SeatDiagram` from this same
+// entry point, or anything the app draws itself (plain Views + Reanimated keeps it renderer-free).
+export interface GuideStep {
+  title: string
+  body: string
+  art?: ReactNode
+}
+
+// The fleet's fake-landscape rotation (structurally @tastic/core's ViewRotation, restated here so this
+// entry point never imports @tastic/core). Pass the app's LIVE rotation (useRotation/getViewRotation):
+// the guide renders in the app-root Portal host, outside any rotated screen, so it turns itself.
+export type GuideRotation = 0 | 90 | 180 | -90

package/src/index.ts

@@ -1,5 +1,6 @@
 export { AchievementCatalogSection } from './AchievementCatalogSection'
 export { AchievementRow, LOCKED_BADGE_COLOR } from './AchievementRow'
+export { AchievementUnlockList, type AchievementUnlockOwner, type UnlockedAchievement } from './AchievementUnlockList'
 export { ActivityStatSection } from './ActivityStatSection'
 export { BaseSettingsDialog, type BaseSettingsDialogProps } from './BaseSettingsDialog'
 export { BaseStatsScreen } from './BaseStatsScreen'
@@ -12,11 +13,12 @@ export { MONO_FONT } from './fonts'
 export { getInlineColorPickerContentSize, InlineColorPicker } from './InlineColorPicker'
 export { getLabeledDropdownContentHeight, LABELED_DROPDOWN_POPOVER_WIDTH, LabeledDropdown, type LabeledDropdownOption } from './LabeledDropdown'
 export { loadSkiaWeb } from './loadSkiaWeb'
-export { getOverlayCardColors, type OverlayCardColors, overlayStyles } from './overlayCard'
+export { getOverlayCardColors, overlayActionStyles, type OverlayCardColors, overlayStyles } from './overlayCard'
 export { getColorPopoverId, getCpuDifficultyPopoverId, PlayerSetupPanel, type PlayerSetupPanelProps } from './PlayerSetupPanel'
 export { PopoverBody } from './PopoverBody'
 export { PressAwayOverlay } from './PressAwayOverlay'
 export { ReadyButton } from './ReadyButton'
+export { RotatedFrame, type RotatedFrameProps } from './RotatedFrame'
 export { type MenuOption, type MenuSection, type MultiSelectSection, SectionedDropdown, type SingleSelectSection } from './SectionedDropdown'
 export { SharedActionBand } from './SharedActionBand'
 export { SkiaGate, type SkiaGateProps } from './SkiaGate'

package/src/overlayCard.ts

@@ -22,10 +22,10 @@ export function getOverlayCardColors(dark: boolean): OverlayCardColors {
 }
 
 // Only the shell shape every overlay card shares (backdrop + card geometry) — deliberately not the
-// button/title/body styling, which already legitimately varies by consumer (BaseSettingsDialog's
-// single centered OK button vs. ConfirmDialog's two-button flexBasis-wrap row vs. each app's own
-// score/badge/zone content). A consumer applies `{backgroundColor: cardBg, borderColor: cardBorder}`
-// from getOverlayCardColors on top of `card` itself, same as every existing call site already does.
+// title/body styling, which already legitimately varies by consumer (each app's own score/badge/zone
+// content). A consumer applies `{backgroundColor: cardBg, borderColor: cardBorder}` from
+// getOverlayCardColors on top of `card` itself, same as every existing call site already does. The
+// one button row every overlay card with actions shares lives in overlayActionStyles below.
 export const overlayStyles = StyleSheet.create({
   card: {
     alignItems: 'center',
@@ -46,3 +46,50 @@ export const overlayStyles = StyleSheet.create({
     top: 0
   }
 })
+
+// The action row ConfirmDialog and guide/HowToPlayDialog share: an outlined secondary (Cancel, Skip,
+// Back) on the left, a contained primary on the right, each growing to split the row but never
+// narrower than 128. Moved here from ConfirmDialog when the how-to-play card needed the identical
+// row, so the two can't drift into different button shapes (the guide briefly shipped text-mode
+// Skip/Back — the only text buttons in the fleet).
+export const overlayActionStyles = StyleSheet.create({
+  // minWidth (not flexBasis) is each button's real floor - whenever both fit side by side, flexGrow
+  // still splits any leftover width evenly beyond that floor, same visual result as a plain flex: 1
+  // on a roomy screen, but a button can never be squeezed narrower than 128, only wrap to its own
+  // row instead (see actions' flexWrap below). This used to be flexBasis: 128, which measured
+  // correctly on web but rendered every button roughly SQUARE on iOS - confirmed live (see the
+  // "Quit Match?" Cancel/Quit buttons and the single-button "OK" dialogs both coming out ~128pt
+  // tall instead of wide). Root cause: react-native-paper's Button renders its Surface as two
+  // nested views on iOS only (Surface.tsx's SurfaceIOS, for shadow rendering) - only a curated
+  // allowlist of style keys (flex/flexGrow/flexShrink/width/height/position/... - notably NOT
+  // flexBasis) reaches the outer view, which is the real flex item inside this row; every other
+  // key, flexBasis included, falls through to an inner view whose own unspecified flexDirection
+  // defaults to column. flexGrow: 1 landed on the (row-context) outer view and grew width
+  // correctly; flexBasis: 128 landed on the (column-context) inner view instead, where a flexBasis
+  // sets HEIGHT, not width. minWidth isn't axis-relative like flexBasis, so it constrains width
+  // correctly regardless of which of the two views it ends up on. react-native-paper's Button also
+  // hardcodes numberOfLines={1} on its label with no override, so a button squeezed under its
+  // label's natural width silently ellipsizes ("Cancel" -> "Can...") instead of wrapping - assumed
+  // fixable by just giving the row more width, until confirmed live that these two-word labels
+  // (Cancel/Reset/New Game) can still lose the truncation fight even with the extra room ConfirmDialog's own
+  // card width fix provides, on a narrow enough screen.
+  actionButton: {
+    flexGrow: 1,
+    minWidth: 128
+  },
+  // A lone confirm button (no cancel - BaseSettingsDialog's info-only "OK" dialogs, e.g. the
+  // update-check "no update found" message) has nothing left to share actions' width with, so
+  // actionButton's own flexGrow: 1 would stretch it across the entire row instead of reading as a
+  // normal button. Same 128 floor, no flexGrow, so it stays at that natural size instead of filling
+  // the card - centered by actions' own justifyContent below.
+  actionButtonSingle: {
+    minWidth: 128
+  },
+  actions: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    gap: 12,
+    justifyContent: 'center',
+    width: '100%'
+  }
+})