@tastic/hud 0.8.5 → 0.13.0

package/src/index.ts

@@ -1,4 +1,7 @@
+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'
 export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog'
@@ -7,16 +10,18 @@ export { ControlSchemePicker, type ControlSchemePickerProps } from './ControlSch
 export { CornerActionButtons } from './CornerActionButtons'
 export { CornerStatusBadges, type CornerStatusBadgeSeat, type CornerStatusBadgesProps, type OrientationMode } from './CornerStatusBadges'
 export { MONO_FONT } from './fonts'
-export { InlineColorPicker } from './InlineColorPicker'
+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 { type MenuOption, type MenuSection, type MultiSelectSection, SectionedDropdown, type SingleSelectSection } from './SectionedDropdown'
 export { SharedActionBand } from './SharedActionBand'
 export { SkiaGate, type SkiaGateProps } from './SkiaGate'
+export { getStaggeredWordDuration, StaggeredWord, type StaggeredWordProps } from './StaggeredWord'
 export { StatRow } from './StatRow'
 export { StatSection } from './StatSection'
 // TriggerGauge itself (the raw Skia-based component) is deliberately NOT exported here, even
@@ -29,5 +34,7 @@ export { StatSection } from './StatSection'
 export type { TriggerGaugeProps } from './TriggerGauge'
 export { default as TriggerGaugeHost } from './TriggerGaugeHost'
 export { UpdateDialog, type UpdateDialogProps } from './UpdateDialog'
-export { type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+export { type AlignResult, type PopoverAlign, type PopoverRotation, type PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
 export { type PopoverHost, usePopoverHost } from './usePopoverHost'
+export { type QuitConfirmation, useQuitConfirmation } from './useQuitConfirmation'
+export { useZoneClampedAlign } from './useZoneClampedAlign'

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%'
+  }
+})

package/src/useAutoAlign.ts

@@ -1,5 +1,5 @@
 import { type ViewRotation } from '@tastic/core'
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { RefObject, useCallback, useEffect, useRef, useState } from 'react'
 import { useWindowDimensions, View } from 'react-native'
 
 // Minimum breathing room between a popover's outer edge and the screen edge — matches the general
@@ -13,6 +13,22 @@ export type PopoverVerticalAlign = 'below' | 'above'
 // rotation" reads clearer at these call sites than the more general core name.
 export type PopoverRotation = ViewRotation
 
+// Same shape useAutoAlign itself returns — exported so a caller can substitute this package's own
+// plain, screen-edge-aware placement wholesale via a component's own `alignOverride` prop (see
+// LabeledDropdown's, SectionedDropdown's, and InlineColorPicker's own `alignOverride`), most often
+// with useZoneClampedAlign's result for a popover living inside a @tastic/split-screen zone, where
+// the plain window-relative decision can pick a direction that overflows into the shared row
+// instead of the zone's own boundary. Hand-declared rather than `ReturnType<typeof useAutoAlign>`
+// so this stays a stable, self-documented public type regardless of useAutoAlign's own internal
+// implementation shape.
+export interface AlignResult {
+  align: PopoverAlign
+  verticalAlign: PopoverVerticalAlign
+  maxHeight: number
+  measured: boolean
+  triggerRef: RefObject<View | null>
+}
+
 // Reflects a rect from the PRE-rotation layout frame measureInWindow actually reports (see
 // useAutoAlign's own comment below for why that's what it reports, not the post-rotation visual
 // position) into its true, post-rotation position — needed for a trigger sitting inside a

package/src/useQuitConfirmation.ts

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export interface QuitConfirmation {
+  /** Wire directly to <ConfirmDialog visible={...}>. */
+  confirmVisible: boolean
+  /** Wire directly to the back button's onPress (GameActionChips/IconButton onBack/onPress). */
+  requestBack: () => void
+  /** Wire directly to <ConfirmDialog onCancel={...}>. */
+  cancelBack: () => void
+}
+
+// Captures the onBackPress + ConfirmDialog "Quit Match?" pattern every fleet game.tsx already
+// hand-wires (Snake, AirHockey, BoxHockey, Pong, LightCycles): interrupt backing out of a match
+// with a confirmation only when there's something worth losing, otherwise back out immediately.
+//
+// `hasProgress` is a lazy () => boolean, not a plain boolean value taken directly - deliberately
+// corrected from this hook's own first version, which took a plain boolean and broke in practice
+// for AirHockey/BoxHockey/Pong: `paused` (derived from this hook's own confirmVisible) has to be
+// computed and handed to useGameState() BEFORE that call returns the very scores/lives/bricks state
+// hasProgress needs to read, so a plain-boolean argument creates a real render-order circular
+// dependency (confirmVisible -> paused -> useGameState -> state -> hasProgress -> confirmVisible).
+// All three apps independently worked around this with their own bespoke shadow-state ("read last
+// render's value, one commit behind"), converging on the same fix by three different names - a sign
+// the hook's own contract was wrong, not that each call site needed its own patch. A lazy getter
+// breaks the cycle by deferring the read to requestBack's own call time, exactly mirroring how the
+// pre-extraction, hand-rolled version of this pattern in every app read scores/bricks/lives fresh
+// from its own onBackPress closure rather than needing the value available earlier in the render.
+//
+// Mirrored into a ref via this fleet's standard effect-based idiom (useEffect with no dependency
+// array, not a bare render-time assignment - see @rific/core's createSettingsContext.tsx for the
+// same convention) rather than read directly, so a stale closure from an earlier render is never
+// what requestBack ends up calling. This also gives requestBack/cancelBack a stable identity across
+// every render (empty deps arrays), which the original plain-boolean version couldn't offer.
+//
+// Deliberately does NOT own or render a <ConfirmDialog> - title/message/icon/confirmLabel/
+// cancelLabel/rotation are all still game-specific (a score pairing, a lives/bricks count, a
+// round-history pip row) and stay authored at each call site; this only owns the open/closed
+// state and the "should this even ask" gate. onConfirmedBack is a plain callback (every current
+// caller passes its own app's safeBack from @/utils/navigation) rather than hardcoded, so this
+// package takes on no expo-router dependency.
+export function useQuitConfirmation(hasProgress: () => boolean, onConfirmedBack: () => void): QuitConfirmation {
+  const [confirmVisible, setConfirmVisible] = useState(false)
+
+  const hasProgressRef = useRef(hasProgress)
+  useEffect(() => {
+    hasProgressRef.current = hasProgress
+  })
+  const onConfirmedBackRef = useRef(onConfirmedBack)
+  useEffect(() => {
+    onConfirmedBackRef.current = onConfirmedBack
+  })
+
+  const requestBack = useCallback(() => {
+    if (hasProgressRef.current()) setConfirmVisible(true)
+    else onConfirmedBackRef.current()
+  }, [])
+
+  const cancelBack = useCallback(() => setConfirmVisible(false), [])
+
+  return { confirmVisible, requestBack, cancelBack }
+}

package/src/useZoneClampedAlign.ts

@@ -0,0 +1,135 @@
+import { useZoneBounds } from '@tastic/split-screen'
+import { useEffect, useState } from 'react'
+import { useWindowDimensions } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+import { PopoverRotation, PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+
+// Matches useAutoAlign's own EDGE_MARGIN convention — not exported from that file, so re-declared
+// here rather than reaching into its internals.
+const EDGE_MARGIN = 12
+
+interface OwnBounds {
+  verticalAlign: PopoverVerticalAlign
+  maxHeight: number
+}
+
+// Wraps useAutoAlign with a zone-aware vertical decision for popovers that live inside a
+// @tastic/split-screen zone (see useZoneBounds' own doc) — a no-op outside one (e.g. a solo,
+// non-split-screen screen), where useAutoAlign's own decision is returned untouched.
+//
+// useAutoAlign picks above-vs-below and its own maxHeight by comparing room against the *full
+// device window* — for a trigger inside a zone, that's wrong in a way a simple clamp on top can't
+// fix: capping its chosen direction after the fact still leaves it capable of *choosing* the
+// direction that points into the shared row (or the opposite player's own zone), which, once
+// correctly capped at that boundary, often has hardly any room at all — nearly useless rather than
+// merely mis-sized. The fix has to re-derive the whole vertical decision using the zone's real
+// boundary instead of the window edge, preferring whichever real-world direction is actually safe
+// (away from the shared row — that direction's room really is bounded by the screen edge, same as
+// useAutoAlign already assumes) and only reaching toward the shared row when the content doesn't
+// fit the safe side and the shared side genuinely has more room — the same "only flips when
+// genuinely better" bias useAutoAlign itself uses, just comparing against the zone's own boundary
+// instead of the opposite screen edge.
+//
+// One more twist specific to p2's 180°-rotated zone: PopoverBody positions itself with plain
+// relative CSS (`top:'100%'`/`bottom:'100%'`) against its trigger, resolved in *local*
+// (pre-rotation) space and then rotated along with everything else in the zone — which inverts it,
+// local 'below' the trigger paints as real-world *above* it once the whole zone flips 180°, and
+// vice versa. This hook's result has to be flipped back to the *local* label PopoverBody expects
+// whenever the zone itself is rotated (zone.rotated), or it ends up choosing the real-world
+// direction it meant to avoid — which is exactly the bug an earlier version of this hook had for
+// p2 specifically (it worked correctly for p1, which isn't rotated, and that's what made the bug
+// easy to miss during testing).
+//
+// CORRECTION (2026-09-18): the paragraph above used to also claim "this hook's own direction math
+// is all real-world (from measureInWindow, which — unlike onLayout — already resolves
+// post-transform)" — that's the exact claim useAutoAlign.ts's own doc documents as having already
+// shipped one real, unnoticed bug once (measureInWindow reports the PRE-transform frame, not
+// post-transform; see that file's own comment). This hook still doesn't apply useAutoAlign's own
+// rotateRect(...) correction to its raw measureInWindow read below (awayRoom/towardRoom are
+// computed straight from the uncorrected y/height) — that's a real, currently-unfixed gap, left
+// alone deliberately rather than guessed at: DualZoneLayout's own sharedEdgeY (see
+// React-Native-Split-Screen's DualZoneLayout.tsx, measureShared) has the identical uncorrected-
+// measureInWindow gap, since sharedRef sits under the same live-rotating outer FakeLandscapeView
+// every real caller wraps this in — and zone.rotated alone isn't sufficient to fix just this
+// hook's own half of it (it captures a trigger's own net rotation for p1/p2 specifically, which
+// happens to fully account for the outer rotation there, but sharedEdgeY's own correction needs
+// the outer rotation directly, which differs from zone.rotated for whichever seat zone.rotated is
+// currently true for). Correcting one side without the other risks making the comparison *more*
+// wrong, not less. No current caller in the fleet actually exercises this path today — every real
+// cpuDifficultyAlignOverride call site across the fleet is a confirmed no-op, never actually
+// rendering inside a live DualZoneLayout zone — so nothing currently miscalculates in practice, but
+// this needs real rotated-zone test coverage (ideally live device testing, not just a unit test
+// stubbing measureInWindow) before either hook's room-size/direction math under live device
+// rotation is trustworthy.
+//
+// `rotation` IS threaded through below, though — that part's unambiguous and low-risk on its own:
+// it only ever reaches useAutoAlign's own (rotation-aware) horizontal align decision, which is
+// exactly what a caller gets back verbatim via the `if (!zone) return auto` fallback whenever this
+// hook is used outside a zone at all (its own documented "safe to reach for even in a component
+// that might or might not end up inside one" case) — matching every sibling rotation-aware
+// component's own default of an ambient `useRotation()` read when the caller omits it.
+//
+// The "away" direction's own room also has to stop at the physical safe area, not the raw window
+// edge — useAutoAlign's own windowHeight is the full device height, notch/status bar and home
+// indicator included, so left alone this hook's fix for the shared-row boundary would just trade
+// one overflow (into the other zone) for another (under the status bar, or behind the home
+// indicator). The toward-shared direction doesn't need this: sharedEdgeY already sits well inside
+// the safe content area on its own.
+export function useZoneClampedAlign(open: boolean, contentWidth: number, contentHeight: number, rotation: PopoverRotation = 0): ReturnType<typeof useAutoAlign> {
+  const auto = useAutoAlign(open, contentWidth, contentHeight, rotation)
+  const zone = useZoneBounds()
+  const { height: windowHeight } = useWindowDimensions()
+  const insets = useSafeAreaInsets()
+  const shouldMeasure = open && auto.measured && zone !== null
+
+  // null until this popover's own zone-aware measurement lands (see the effect below) — separate
+  // from auto.measured, which only covers useAutoAlign's own (zone-blind) measurement.
+  const [ownBounds, setOwnBounds] = useState<OwnBounds | null>(null)
+  // Resets synchronously during render, not in the effect below, the instant shouldMeasure flips
+  // either direction — same "adjust state during render" pattern useAutoAlign itself uses for its
+  // own measured reset (see that hook's own comment), so a stale ownBounds from a previous
+  // open/zone never survives into a render it doesn't apply to, not even for the one frame before
+  // an effect would otherwise catch up.
+  const [prevShouldMeasure, setPrevShouldMeasure] = useState(shouldMeasure)
+  if (shouldMeasure !== prevShouldMeasure) {
+    setPrevShouldMeasure(shouldMeasure)
+    setOwnBounds(null)
+  }
+
+  // Re-measures the same trigger node useAutoAlign itself measures, once *its* measurement has
+  // landed (auto.measured, folded into shouldMeasure) so the ref is guaranteed mounted and settled.
+  // A second measureInWindow call on the same node, not a shared one with useAutoAlign — that
+  // hook's own measurement is fully internal to it, with nothing exposed to piggyback on beyond the
+  // ref itself.
+  useEffect(() => {
+    if (!shouldMeasure) return
+    auto.triggerRef.current?.measureInWindow((_x, y, _width, height) => {
+      const belowShared = zone!.zoneSide === 'belowShared'
+      // Same shape as useAutoAlign's own roomBelow/roomAbove — this is the direction with nothing
+      // else between the popover and the real screen edge — but stopping at the safe area inset
+      // instead of the raw window edge (insets.top/insets.bottom are always real physical-device
+      // edges, unaffected by any rotation applied further down the tree, so this is correct as-is
+      // for p2's rotated zone too, not just p1's).
+      const awayRoom = belowShared ? windowHeight - insets.bottom - (y + height) - EDGE_MARGIN : y - insets.top - EDGE_MARGIN
+      // The other direction runs into the shared row instead of the screen edge.
+      const towardRoom = belowShared ? y - zone!.sharedEdgeY - EDGE_MARGIN : zone!.sharedEdgeY - (y + height) - EDGE_MARGIN
+      const useToward = contentHeight > awayRoom && towardRoom > awayRoom
+      // Real-world direction, before any rotation compensation.
+      let awaySide: PopoverVerticalAlign = belowShared ? 'below' : 'above'
+      let towardSide: PopoverVerticalAlign = belowShared ? 'above' : 'below'
+      // See this hook's own doc — PopoverBody's local-then-rotate positioning inverts 'above'/
+      // 'below' for a rotated zone, so the real-world label chosen above has to flip back to the
+      // local one that actually produces it once painted.
+      if (zone!.rotated) {
+        awaySide = awaySide === 'above' ? 'below' : 'above'
+        towardSide = towardSide === 'above' ? 'below' : 'above'
+      }
+      setOwnBounds({ maxHeight: Math.max(useToward ? towardRoom : awayRoom, 0), verticalAlign: useToward ? towardSide : awaySide })
+    })
+  }, [shouldMeasure, zone, auto.triggerRef, contentHeight, windowHeight, insets.top, insets.bottom])
+
+  if (!zone) return auto
+  if (!ownBounds) return { ...auto, measured: false }
+  return { ...auto, maxHeight: ownBounds.maxHeight, measured: auto.measured, verticalAlign: ownBounds.verticalAlign }
+}