@tastic/hud 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Visual component kit for local-multiplayer React Native games: inline (non-modal) popovers, dropdowns, color pickers, gauges, ready buttons, and dialogs, built to stay scoped to one player's own zone on a shared screen",
   "keywords": [
     "react-native",
@@ -34,6 +34,13 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
     },
+    "./guide": {
+      "react-native": "./src/guide/index.ts",
+      "browser": "./src/guide/index.ts",
+      "types": "./dist/guide/index.d.ts",
+      "import": "./dist/guide/index.mjs",
+      "require": "./dist/guide/index.js"
+    },
     "./skia-gate": {
       "react-native": "./src/SkiaGate.tsx",
       "browser": "./src/SkiaGate.web.tsx",
@@ -102,12 +109,12 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@rific/auto-paper": ">=0.9.0",
-    "@rific/feedback-press": ">=0.10.0",
+    "@rific/auto-paper": ">=0.9.4",
+    "@rific/feedback-press": ">=0.10.2",
     "@rific/updater": ">=0.4.0",
     "@shopify/react-native-skia": ">=1.5.0",
-    "@tastic/achievements": ">=0.1.2",
-    "@tastic/core": ">=0.3.0",
+    "@tastic/achievements": ">=0.2.0",
+    "@tastic/core": ">=0.5.0",
     "@tastic/profile": ">=0.4.0",
     "@tastic/split-screen": ">=0.5.0",
     "react": ">=19.0.0",
@@ -116,6 +123,26 @@
     "react-native-reanimated": ">=3.0.0",
     "react-native-safe-area-context": ">=5.0.0"
   },
+  "peerDependenciesMeta": {
+    "@rific/updater": {
+      "optional": true
+    },
+    "@shopify/react-native-skia": {
+      "optional": true
+    },
+    "@tastic/achievements": {
+      "optional": true
+    },
+    "@tastic/core": {
+      "optional": true
+    },
+    "@tastic/profile": {
+      "optional": true
+    },
+    "@tastic/split-screen": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/AchievementUnlockList.tsx

@@ -0,0 +1,98 @@
+import { getContrastColor, useAutoPaperTheme } from '@rific/auto-paper'
+import type { AchievementTier } from '@tastic/achievements'
+import { type Profile, ProfileChip } from '@tastic/profile'
+import { StyleSheet, View, type ViewStyle } from 'react-native'
+import { Icon, Text } from 'react-native-paper'
+
+// The only fields a row reads - structural, so any app's own AchievementDefinition<Stats> fits
+// without this package caring about its stats type parameter.
+export interface UnlockedAchievement {
+  id: string
+  icon: string
+  title: string
+  tier: AchievementTier
+}
+
+// Who a seat's rows belong to: their ProfileChip when a profile is selected, otherwise a plain
+// avatar in the seat's own color (a guest seat has no tag to show). An app that draws profile colors
+// muted wraps its tree in @tastic/profile's ProfileColorProvider (ProfileChip reads it) and passes
+// an already-muted `color` here.
+export interface AchievementUnlockOwner {
+  profile?: Profile | null
+  color: string
+}
+
+interface Props<Seat extends number> {
+  unlocks: Partial<Record<Seat, UnlockedAchievement[]>>
+  // Row order: every unlock of the first seat, then the next.
+  seats: readonly Seat[]
+  owners: Record<Seat, AchievementUnlockOwner>
+  // Taken as a prop rather than imported: @tastic/achievements stays a type-only dependency of
+  // this package. Callers pass its ACHIEVEMENT_TIER_COLORS (or their own palette).
+  tierColors: Record<AchievementTier, string>
+  fg?: string
+  style?: ViewStyle
+}
+
+const AVATAR_SIZE = 18
+
+// The newly-unlocked achievements on a game-over / round-over card, one row per achievement:
+// owner avatar, tier-colored icon badge, title. Extracted from the per-app copies in Snake,
+// LightCycles, Pong, BoxHockey and AirHockey, which had drifted to three different owner markers;
+// this is the ProfileChip-or-color-avatar one most of them used. One row per achievement rather
+// than a per-seat summary, so the list stays aligned when only one seat unlocked anything.
+// Renders nothing when there are no unlocks at all.
+export function AchievementUnlockList<Seat extends number>({ unlocks, seats, owners, tierColors, fg: fgOverride, style }: Props<Seat>) {
+  const { dark } = useAutoPaperTheme()
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const rows = seats.flatMap((seat) => (unlocks[seat] ?? []).map((achievement) => ({ seat, achievement })))
+  if (rows.length === 0) return null
+
+  return (
+    <View style={[styles.list, style]}>
+      {rows.map(({ seat, achievement }) => {
+        const owner = owners[seat]
+        return (
+          <View key={`${seat}-${achievement.id}`} style={styles.row}>
+            {owner.profile ? (
+              <ProfileChip profile={owner.profile} size={AVATAR_SIZE} />
+            ) : (
+              <View style={[styles.circle, { backgroundColor: owner.color }]}>
+                <Icon source='account' size={10} color={getContrastColor(owner.color)} />
+              </View>
+            )}
+            <View style={[styles.circle, { backgroundColor: tierColors[achievement.tier] }]}>
+              <Icon source={achievement.icon} size={12} color='#000000' />
+            </View>
+            <Text style={[styles.label, { color: fg }]} numberOfLines={1}>
+              {achievement.title}
+            </Text>
+          </View>
+        )
+      })}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  circle: {
+    alignItems: 'center',
+    borderRadius: AVATAR_SIZE / 2,
+    height: AVATAR_SIZE,
+    justifyContent: 'center',
+    width: AVATAR_SIZE
+  },
+  label: {
+    flexShrink: 1,
+    fontSize: 12,
+    fontWeight: '700'
+  },
+  list: {
+    gap: 6
+  },
+  row: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 6
+  }
+})

package/src/BaseSettingsDialog.tsx

@@ -67,6 +67,10 @@ export interface BaseSettingsDialogProps {
   // toast system wired up; the check itself still runs and still reports success/no-update through
   // the ordinary info overlay either way. Meaningless (never called) when hideUpdateCheck is set.
   onUpdateError?: (message: string) => void
+  // Omit to hide the row entirely (a game with no how-to-play flow, or a screen where replaying one
+  // would be disruptive — e.g. over a live match). Called AFTER this dialog's own onDismiss, so the
+  // two overlays never stack: wire it straight to @tastic/hud/guide's `useGuide().open`.
+  onShowHowToPlay?: () => void
   // App-specific extra settings sections (board options, CPU difficulty, stats backup, ...),
   // rendered between Appearance and Check for Updates — this component only owns the settings
   // every game shares, never anything about how a particular game plays.
@@ -80,7 +84,7 @@ export interface BaseSettingsDialogProps {
 // is the seam for whatever isn't shared: a game with its own board/difficulty settings (or a stats
 // backup flow, or anything else genuinely specific to it) renders those below Appearance, not by
 // forking this component.
-export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverride, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, children }: BaseSettingsDialogProps) {
+export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverride, version, lockOrientation, onLockOrientationChange, deferBottomEdgeGestures, onDeferBottomEdgeGestures, hideSound = false, hideHaptics = false, hideAppearance = false, hideUpdateCheck = false, onUpdateError, onShowHowToPlay, children }: BaseSettingsDialogProps) {
   const { colors } = useAutoPaperTheme()
   const ambientRotation = useRotation()
   const rotation = rotationOverride ?? ambientRotation
@@ -235,6 +239,33 @@ export function BaseSettingsDialog({ visible, onDismiss, rotation: rotationOverr
                   )}
                 </View>
               )}
+
+              {/* Not a toggle, but it reads like one of the rows above and belongs with them rather than
+                down in `children` (which sits below Appearance) — this is the "replay the intro"
+                entry point every game's own how-to-play flow shares. Dismisses this dialog first so
+                the guide's own overlay never opens on top of a still-visible Settings card. */}
+              {onShowHowToPlay && (
+                <TouchableRipple
+                  onPress={() => {
+                    onDismiss()
+                    onShowHowToPlay()
+                  }}
+                  style={styles.toggleButton}
+                  accessibilityLabel='How to Play'
+                >
+                  <View style={styles.toggleContent}>
+                    <SettingIcon source='help-circle-outline' color={colors.secondary} containerColor={colors.secondaryContainer} />
+                    <View style={styles.flexShrink}>
+                      <Text variant='bodyLarge' style={{ color: colors.onSurface }}>
+                        How to Play
+                      </Text>
+                      <Text variant='bodySmall' numberOfLines={1} style={{ color: colors.onSurfaceVariant }}>
+                        Replay the quick intro
+                      </Text>
+                    </View>
+                  </View>
+                </TouchableRipple>
+              )}
             </View>
 
             {showAppearance && (

package/src/ConfirmDialog.tsx

@@ -5,7 +5,7 @@ import { type ReactNode } from 'react'
 import { StyleSheet, View } from 'react-native'
 import { Icon, Portal, Text } from 'react-native-paper'
 
-import { getOverlayCardColors, overlayStyles } from './overlayCard'
+import { getOverlayCardColors, overlayActionStyles, overlayStyles } from './overlayCard'
 
 export interface ConfirmDialogProps {
   visible: boolean
@@ -55,13 +55,13 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
           <Text variant='bodyLarge' style={[styles.body, { color: fg }]}>
             {message}
           </Text>
-          <View style={styles.actions}>
+          <View style={overlayActionStyles.actions}>
             {showCancel && (
-              <Button mode='outlined' onPress={onCancel} style={styles.actionButton}>
+              <Button mode='outlined' onPress={onCancel} style={overlayActionStyles.actionButton}>
                 {cancelLabel}
               </Button>
             )}
-            <Button mode='contained' onPress={onConfirm} style={showCancel ? styles.actionButton : styles.actionButtonSingle} buttonColor={accent} textColor={onAccent}>
+            <Button mode='contained' onPress={onConfirm} style={showCancel ? overlayActionStyles.actionButton : overlayActionStyles.actionButtonSingle} buttonColor={accent} textColor={onAccent}>
               {confirmLabel}
             </Button>
           </View>
@@ -72,45 +72,6 @@ export function ConfirmDialog({ visible, title, message, confirmLabel, cancelLab
 }
 
 const styles = 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 card's own
-  // width fix below 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%'
-  },
   body: {
     textAlign: 'center'
   },

package/src/ContentGutter.tsx

@@ -1,6 +1,6 @@
-import { computeContentBounds } from '@tastic/core'
+import { computeContentBounds, useRotatedWindowDimensions } from '@tastic/core'
 import { ReactNode } from 'react'
-import { StyleProp, StyleSheet, useWindowDimensions, View, ViewStyle } from 'react-native'
+import { StyleProp, StyleSheet, View, ViewStyle } from 'react-native'
 
 interface Props {
   // Upper bound on the centered content region's width, in px. Omitted (the default) means no
@@ -25,13 +25,20 @@ interface Props {
 // any further stops being useful. Below maxContentWidth - or with it omitted entirely - this is a
 // no-op passthrough: children render at the full window width, no gutters.
 //
-// See @tastic/core's computeContentBounds for the actual clamp math this just wires up to a live
-// useWindowDimensions() read - deliberately the only geometry source this component owns itself; a
+// The width it clamps against is @tastic/core's useRotatedWindowDimensions(), not a raw
+// useWindowDimensions(): under a fake-landscape ancestor (FakeLandscapeView - the OS window stays
+// portrait-locked, the screen is only visually rotated) the raw window width never changes, so a
+// raw read would cap a rotated play area at the portrait width while everything inside laid out for
+// the swapped landscape footprint, clipping it. That hook is an exact identity with
+// useWindowDimensions() whenever no rotation applies, so nothing changes at rotation 0.
+//
+// See @tastic/core's computeContentBounds for the actual clamp math this just wires up to that live
+// read - deliberately the only geometry source this component owns itself; a
 // caller that also needs to fold in device safe-area insets or a split-screen zone boundary
 // composes those together on its own side, the same way LightCycles' useZoneClampedAlign composes
 // useAutoAlign with its own extra geometry (see that hook for the pattern this follows).
 export function ContentGutter({ maxContentWidth, leftGutter, rightGutter, style, children }: Props) {
-  const { width: windowWidth } = useWindowDimensions()
+  const { width: windowWidth } = useRotatedWindowDimensions()
   const { contentWidth, gutterWidth } = computeContentBounds(windowWidth, maxContentWidth ?? Infinity)
 
   return (

package/src/guide/DirectionKeysHint.tsx

@@ -0,0 +1,96 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Icon, Text } from 'react-native-paper'
+
+export interface DirectionKeyLabels {
+  up: string
+  left: string
+  down: string
+  right: string
+}
+
+export type DirectionKeysAxis = 'both' | 'vertical'
+
+export interface DirectionKeysHintProps {
+  // What's printed on each cap — e.g. { up: 'W', left: 'A', down: 'S', right: 'D' }. Omit for the
+  // arrow keys themselves, drawn as arrow icons (so does any single cap left out). Pass whatever the
+  // seat's own key scheme actually is, not a guess: the fleet games let each seat pick WASD, arrows,
+  // IJKL and so on.
+  labels?: Partial<DirectionKeyLabels>
+  // 'both' (default) draws the four-key inverted T. 'vertical' draws only up above down, for a game
+  // whose controls only ever read those two (Pong's paddles).
+  axis?: DirectionKeysAxis
+  // Defaults to the theme's own primary — i.e. player 1's seat color in the fleet games.
+  color?: string
+}
+
+const CAP_SIZE = 34
+
+const ARROWS: DirectionKeyLabels = { up: 'arrow-up', left: 'arrow-left', down: 'arrow-down', right: 'arrow-right' }
+
+function KeyCap({ label, icon, color }: { label?: string; icon: string; color: string }) {
+  return (
+    <View style={[styles.cap, { borderColor: color }]}>
+      {label !== undefined ? (
+        <Text variant='titleMedium' style={[styles.capLabel, { color }]}>
+          {label}
+        </Text>
+      ) : (
+        <Icon source={icon} size={20} color={color} />
+      )}
+    </View>
+  )
+}
+
+// Key caps in the inverted-T every keyboard player already knows (or just up over down, see `axis`) —
+// the desktop counterpart to SwipeHint for the "how do I steer" card, since a desktop browser steers by
+// key, not by swipe. Plain Views, no animation, so there's nothing for reduced motion to switch off.
+export function DirectionKeysHint({ labels, axis = 'both', color }: DirectionKeysHintProps) {
+  const { colors } = useAutoPaperTheme()
+  const tint = color ?? colors.primary
+
+  if (axis === 'vertical') {
+    const accessibilityLabel = labels?.up && labels.down ? `Keys ${labels.up} and ${labels.down}` : 'Up and down arrow keys'
+    return (
+      <View accessible accessibilityLabel={accessibilityLabel} style={styles.cluster}>
+        <KeyCap label={labels?.up} icon={ARROWS.up} color={tint} />
+        <KeyCap label={labels?.down} icon={ARROWS.down} color={tint} />
+      </View>
+    )
+  }
+
+  const accessibilityLabel = labels?.up && labels.left && labels.down && labels.right ? `Keys ${labels.up}, ${labels.left}, ${labels.down}, ${labels.right}` : 'Arrow keys'
+
+  return (
+    <View accessible accessibilityLabel={accessibilityLabel} style={styles.cluster}>
+      <KeyCap label={labels?.up} icon={ARROWS.up} color={tint} />
+      <View style={styles.row}>
+        <KeyCap label={labels?.left} icon={ARROWS.left} color={tint} />
+        <KeyCap label={labels?.down} icon={ARROWS.down} color={tint} />
+        <KeyCap label={labels?.right} icon={ARROWS.right} color={tint} />
+      </View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  cap: {
+    alignItems: 'center',
+    borderRadius: 8,
+    borderWidth: 2,
+    height: CAP_SIZE,
+    justifyContent: 'center',
+    width: CAP_SIZE
+  },
+  capLabel: {
+    fontWeight: 'bold'
+  },
+  cluster: {
+    alignItems: 'center',
+    gap: 6
+  },
+  row: {
+    flexDirection: 'row',
+    gap: 6
+  }
+})

package/src/guide/GuideProvider.tsx

@@ -0,0 +1,87 @@
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+
+import { HowToPlayDialog } from './HowToPlayDialog'
+import type { GuideRotation, GuideStep } from './types'
+
+interface GuideContextValue {
+  isOpen: boolean
+  // Opens the guide unconditionally — the Settings "How to play" row's whole job. Never persists
+  // anything on its own: only finishing or skipping does, and only while the player hasn't already
+  // seen this version.
+  open: () => void
+  close: () => void
+  // Opens it once per session, and only if this player hasn't seen `currentVersion` yet — see
+  // useAutoShowGuide.
+  requestAutoShow: () => void
+}
+
+const noop = () => {}
+
+// A default that does nothing rather than throwing when there's no provider above — an app's own
+// existing tests render its Settings dialog or Home screen without one, and a "How to play" row that
+// silently does nothing in that harness is a far better failure than every such test breaking.
+const GuideContext = createContext<GuideContextValue>({ isOpen: false, open: noop, close: noop, requestAutoShow: noop })
+
+export interface GuideProviderProps {
+  steps: GuideStep[]
+  // Bumped by the app only for a genuine controls/rules change, to re-prompt everyone.
+  currentVersion: number
+  // Read from the app's own persisted store (see createGuideSlice's selectVersionSeen).
+  seenVersion: number
+  // Called with `currentVersion` when the player finishes or skips a guide they hadn't seen yet.
+  onSeen: (version: number) => void
+  // The app's live fake-landscape rotation (see GuideRotation). The card rotates and sizes itself for it.
+  rotation?: GuideRotation
+  children?: ReactNode
+}
+
+// Mounted once at the app root, next to <UpdateDialog /> — the fleet's existing "self-presenting
+// app-level dialog" seat — so any screen can open it through useGuide() without prop-drilling, and
+// the Portal it renders sits above every route. Inside PersistGate, so `seenVersion` is already the
+// rehydrated value by the time this first renders.
+export function GuideProvider({ steps, currentVersion, seenVersion, onSeen, rotation, children }: GuideProviderProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  // Once per session, not once per Home mount — Home remounts every time the player backs out of a
+  // match, and skipping shouldn't be something they have to do again a minute later just because the
+  // persisted flag hadn't been written back through the store yet.
+  const autoShownRef = useRef(false)
+  const unseen = seenVersion < currentVersion
+
+  const open = useCallback(() => setIsOpen(true), [])
+
+  const close = useCallback(() => {
+    setIsOpen(false)
+    if (unseen) onSeen(currentVersion)
+  }, [unseen, onSeen, currentVersion])
+
+  const requestAutoShow = useCallback(() => {
+    if (!unseen || autoShownRef.current) return
+    autoShownRef.current = true
+    setIsOpen(true)
+  }, [unseen])
+
+  const value = useMemo(() => ({ isOpen, open, close, requestAutoShow }), [isOpen, open, close, requestAutoShow])
+
+  return (
+    <GuideContext.Provider value={value}>
+      {children}
+      <HowToPlayDialog visible={isOpen} steps={steps} onFinish={close} onSkip={close} rotation={rotation} />
+    </GuideContext.Provider>
+  )
+}
+
+export function useGuide(): GuideContextValue {
+  return useContext(GuideContext)
+}
+
+// Call this from the Home screen and nowhere else — that placement, not any route check in here, is
+// what keeps it from ever firing over a live match or a two-seat loadout. Home is the one screen
+// with a single reader, before any seating, so a face-to-face two-player phone doesn't need per-seat
+// rotated copies of the card. `enabled` lets a caller hold it back (e.g. while a shared-link import
+// is being handled) without breaking the rules of hooks by conditionally calling this.
+export function useAutoShowGuide(enabled = true) {
+  const { requestAutoShow } = useGuide()
+  useEffect(() => {
+    if (enabled) requestAutoShow()
+  }, [enabled, requestAutoShow])
+}