@tastic/hud 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.3.0",
+  "version": "0.5.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",

package/src/AchievementRow.tsx

@@ -0,0 +1,132 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Icon, ProgressBar, Text } from 'react-native-paper'
+
+// A neutral gray for a locked badge's own background — exported so a caller computing its own
+// badge color (unlocked ? tierColor : LOCKED_BADGE_COLOR, matching LightCycles' own achievements.tsx)
+// doesn't need to invent or duplicate this exact tone.
+export const LOCKED_BADGE_COLOR = 'rgba(128,128,128,0.3)'
+
+interface Props {
+  icon: string
+  title: string
+  description: string
+  // The badge's own background — pass the achievement's tier color when unlocked, or
+  // LOCKED_BADGE_COLOR (this package's own export, above) when it isn't; this component doesn't
+  // infer that from unlockedLabel itself, since a locked-vs-unlocked badge color scheme is a
+  // caller-level design choice (see checkColor below for the identical reasoning on the status
+  // icon's own color).
+  badgeColor: string
+  // undefined = locked. A precomputed display string (e.g. "Unlocked 2 days ago"), not a raw
+  // timestamp — this component has no opinion on date formatting or streak conventions, which vary
+  // per app (see LightCycles' own calendar-day-difference convention in its achievements.tsx).
+  unlockedLabel?: string
+  // Color for the unlocked check-circle icon/badge glyph — typically the same tier color passed to
+  // badgeColor, kept as its own prop rather than reused internally so a caller can special-case it
+  // independently if its own tier scheme ever needs to (matching LightCycles' own call site, which
+  // does pass the identical value to both today).
+  checkColor?: string
+  // Only rendered while locked (unlockedLabel is undefined) — 0..1.
+  progress?: number
+  // The "Same for every profile" note LightCycles shows for a device-scoped achievement viewed
+  // from a specific profile's own tab — optional since only an app with per-profile stat views has
+  // this concept at all.
+  deviceMarker?: boolean
+  // Independently optional overrides for this row's own text/background colors — each defaults to
+  // the same dark-mode-derived formula as StatRow/StatSection/BaseStatsScreen (see that component's
+  // own doc for why) when omitted, so every existing caller renders identically to before. A caller
+  // with its own app-wide chrome palette passes whichever of the three it needs.
+  fg?: string
+  fgMuted?: string
+  sectionBg?: string
+}
+
+// One row per achievement — a tier-colored (or locked-gray) badge, title/description, an optional
+// progress bar while locked, and either an unlocked check-mark+label or a lock icon. Extracted
+// verbatim from LightCycles' own achievements.tsx, where this exact row shape backed its entire
+// "ALL ACHIEVEMENTS" list. fg/fgMuted/its own section background default to the same
+// useAutoPaperTheme()-derived formula as StatRow/StatSection/BaseStatsScreen (see BaseStatsScreen's
+// own doc for why), each independently overridable via the matching prop for a caller with its own
+// chrome palette. Has no opinion on what an achievement actually IS (id, unlock predicate, catalog)
+// — that stays entirely app-local; this is purely the presentational row.
+export function AchievementRow({ icon, title, description, badgeColor, unlockedLabel, checkColor, progress, deviceMarker, fg: fgOverride, fgMuted: fgMutedOverride, sectionBg: sectionBgOverride }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
+  const sectionBg = sectionBgOverride ?? (dark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.04)')
+  const unlocked = unlockedLabel !== undefined
+
+  return (
+    <View style={[styles.row, { backgroundColor: sectionBg }]}>
+      <View style={[styles.badge, { backgroundColor: badgeColor }]}>
+        <Icon source={icon} size={20} color={unlocked ? '#000000' : fgMuted} />
+      </View>
+      <View style={styles.text}>
+        <Text variant='bodyLarge' style={[styles.boldText, { color: fg }]}>
+          {title}
+        </Text>
+        <Text variant='bodySmall' style={{ color: fgMuted }}>
+          {description}
+        </Text>
+        {deviceMarker && (
+          <View style={styles.deviceMarker}>
+            <Icon source='earth' size={11} color={fgMuted} />
+            <Text variant='labelSmall' style={{ color: fgMuted }}>
+              Same for every profile
+            </Text>
+          </View>
+        )}
+        {!unlocked && progress !== undefined && <ProgressBar progress={progress} color={checkColor ?? badgeColor} style={styles.progressBar} />}
+      </View>
+      {unlocked ? (
+        <View style={styles.status}>
+          <Icon source='check-circle' size={20} color={checkColor ?? badgeColor} />
+          <Text variant='labelSmall' style={{ color: fgMuted }}>
+            {unlockedLabel}
+          </Text>
+        </View>
+      ) : (
+        <Icon source='lock-outline' size={20} color={fgMuted} />
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  badge: {
+    alignItems: 'center',
+    borderRadius: 10,
+    height: 36,
+    justifyContent: 'center',
+    width: 36
+  },
+  boldText: {
+    fontWeight: 'bold'
+  },
+  deviceMarker: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 4
+  },
+  progressBar: {
+    borderRadius: 4,
+    height: 6,
+    marginTop: 6
+  },
+  row: {
+    alignItems: 'center',
+    borderRadius: 12,
+    flexDirection: 'row',
+    gap: 12,
+    padding: 12
+  },
+  status: {
+    alignItems: 'center',
+    gap: 2,
+    width: 64
+  },
+  text: {
+    flex: 1,
+    gap: 2
+  }
+})

package/src/BaseStatsScreen.tsx

@@ -0,0 +1,192 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { Button, IconButton } from '@rific/feedback-press'
+import { ReactNode, useState } from 'react'
+import { ScrollView, StyleSheet, View } from 'react-native'
+import { Icon, Portal, Text } from 'react-native-paper'
+
+// react-native-paper's own MD3 Text variant names — mirrored locally rather than importing its
+// internal VariantProp/MD3TypescaleKey (not exported from the package's public entry point) just
+// to type one optional prop.
+type MD3TextVariant = 'displayLarge' | 'displayMedium' | 'displaySmall' | 'headlineLarge' | 'headlineMedium' | 'headlineSmall' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'labelLarge' | 'labelMedium' | 'labelSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall'
+
+interface Props {
+  // Live physical-hold rotation (see @tastic/split-screen's getViewRotation) — this dialog renders
+  // as a centered Portal modal, unaffected by whichever screen's own FakeLandscapeView wraps its
+  // trigger, so it has to rotate its own card content to read right-side-up for whichever way the
+  // phone is actually being held. Defaults to 0 for a caller that doesn't track one — matches
+  // BaseSettingsDialog's own identical prop, though the first apps consuming this screen shell
+  // don't wrap it in a FakeLandscapeView at all and so never have a nonzero one to give.
+  rotation?: number
+  title?: string
+  // 'headlineSmall' (this screen's own default, below) — was originally 'displaySmall' (the full
+  // display tier's own smallest step), then 'headlineLarge', both still read as oversized for a
+  // header that's paired with a small 24px back-button glyph rather than standing alone the way a
+  // title screen's own wordmark does; headlineSmall sits close to that icon's own size instead of
+  // towering over it. Any react-native-paper MD3 Text variant, not just the headline tier, for a
+  // caller that wants something else entirely.
+  titleVariant?: MD3TextVariant
+  onBack: () => void
+  insets: { top: number; left: number; bottom: number; right: number }
+  // Optional, and always passed as a pair — a caller with nothing resettable (or that deliberately
+  // doesn't want a reset action on this screen) omits both rather than one alone. Confirmation copy
+  // is caller-owned since "erases all stats and achievements" is only accurate for a caller that
+  // actually tracks both; a caller with only high scores, say, would want its own wording.
+  onReset?: () => void
+  resetLabel?: string
+  resetConfirmTitle?: string
+  resetConfirmBody?: string
+  // Independently optional overrides for this screen's own background/text colors — each defaults
+  // to the literal-black/white-by-appearance formula described below when omitted, so every
+  // existing caller (none of which pass these) renders identically to before. A caller with its own
+  // app-wide chrome palette (e.g. a tinted background rather than neutral black/white) passes
+  // whichever of the three it needs; cardBorder on the reset-confirm overlay stays fixed regardless,
+  // since its low alpha already reads fine against any cardBg.
+  fg?: string
+  bg?: string
+  cardBg?: string
+  // Overrides the confirm-overlay's alert icon/title, which otherwise default to auto-paper's
+  // colors.secondary. That default is tuned to read against auto-paper's OWN background role, not
+  // necessarily against a cardBg override above — a caller passing cardBg should generally pass a
+  // matching accentColor too, rather than risk colors.secondary landing close in hue/lightness to
+  // its own custom card background (this is what actually happened with a tinted felt cardBg in the
+  // app this was first overridden for). Every button on this screen (the reset trigger included)
+  // fills with colors.secondary/onSecondary as a self-contained, always-legible pair instead of
+  // relying on a text-only color read against the surrounding chrome, so none of them need this —
+  // only the bare icon/title do.
+  accentColor?: string
+  children: ReactNode
+}
+
+// The stats/achievements screen shell every @tastic game shares — back button + title header,
+// scrollable content area, and an optional reset-everything action with its own confirm-before-
+// destroying overlay — extracted after the same header/scroll/reset-confirm shape was independently
+// built into LightCycles' own achievements.tsx. Colors default to the same literal-black/white-by-
+// appearance formula BaseSettingsDialog hardcodes internally (same as this package's own
+// BaseSettingsDialog) — zero-config for every existing caller — but fg/bg/cardBg are each
+// independently overridable for a caller whose own app-wide chrome palette isn't that literal
+// black/white convention. `children` is the seam for whatever isn't shared: this component has no
+// opinion on what a "stat" is or how achievements are catalogued — see StatRow/StatSection/
+// AchievementRow for the smaller presentational pieces built to go inside it.
+export function BaseStatsScreen({ rotation = 0, title = 'Achievements', titleVariant = 'headlineSmall', onBack, insets, onReset, resetLabel = 'Reset All Stats', resetConfirmTitle = 'Reset Everything?', resetConfirmBody = 'This permanently erases all stats and achievements. This cannot be undone.', fg: fgOverride, bg: bgOverride, cardBg: cardBgOverride, accentColor: accentColorOverride, children }: Props) {
+  const { dark, colors } = useAutoPaperTheme()
+  const [confirmResetVisible, setConfirmResetVisible] = useState(false)
+  const showReset = !!onReset
+
+  // High-contrast retro look by default: literal black/white by appearance, matching every other
+  // screen in this ecosystem (title/loadout/settings all use this identical formula) rather than
+  // auto-paper's own (slightly tinted) background role — same convention BaseSettingsDialog's own
+  // fg/cardBg/cardBorder use internally. Overridable per-instance via the props above for a caller
+  // whose own chrome isn't that literal black/white convention; cardBorder has no override (see the
+  // Props doc above for why).
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const bg = bgOverride ?? (dark ? '#000000' : '#FFFFFF')
+  const cardBg = cardBgOverride ?? (dark ? '#111111' : '#F2F2F2')
+  const cardBorder = dark ? 'rgba(255,255,255,0.2)' : 'rgba(0,0,0,0.2)'
+  const accentColor = accentColorOverride ?? colors.secondary
+
+  return (
+    <View style={[styles.container, { backgroundColor: bg }]}>
+      <View style={[styles.header, { paddingTop: 8 + insets.top, paddingLeft: 8 + insets.left }]}>
+        <IconButton icon='arrow-left' iconColor={fg} size={24} onPress={onBack} />
+        <Text variant={titleVariant} style={[styles.title, { color: fg }]}>
+          {title}
+        </Text>
+      </View>
+
+      <ScrollView style={styles.scrollView} contentContainerStyle={[styles.content, { paddingBottom: 32 + insets.bottom }]} showsVerticalScrollIndicator={false}>
+        {children}
+
+        {showReset && (
+          <Button mode='contained' onPress={() => setConfirmResetVisible(true)} buttonColor={colors.secondary} textColor={colors.onSecondary} style={styles.resetButton}>
+            {resetLabel}
+          </Button>
+        )}
+      </ScrollView>
+
+      {confirmResetVisible && (
+        <Portal>
+          <View style={[styles.overlay, rotation % 360 !== 0 && { transform: [{ rotate: `${rotation}deg` }] }]}>
+            <View style={[styles.overlayCard, { backgroundColor: cardBg, borderColor: cardBorder }]}>
+              <Icon source='alert-outline' size={64} color={accentColor} />
+              <Text variant='headlineLarge' style={[styles.overlayTitle, { color: accentColor }]}>
+                {resetConfirmTitle}
+              </Text>
+              <Text variant='bodyLarge' style={[styles.overlayBody, { color: fg }]}>
+                {resetConfirmBody}
+              </Text>
+              <Button mode='contained' onPress={() => setConfirmResetVisible(false)} style={styles.overlayButton}>
+                Cancel
+              </Button>
+              <Button
+                mode='contained'
+                onPress={() => {
+                  onReset?.()
+                  setConfirmResetVisible(false)
+                }}
+                style={styles.overlayButton}
+                buttonColor={colors.secondary}
+                textColor={colors.onSecondary}
+              >
+                Reset
+              </Button>
+            </View>
+          </View>
+        </Portal>
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1
+  },
+  content: {
+    gap: 12,
+    paddingHorizontal: 20
+  },
+  header: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 4,
+    paddingBottom: 8
+  },
+  // Same overlay shape BaseSettingsDialog's own info overlay uses (backdrop + centered card),
+  // rotated in place the same way rather than via Portal-root transform for the same reason — see
+  // that component's own identical styles for the full rationale.
+  overlay: {
+    alignItems: 'center',
+    backgroundColor: 'rgba(0,0,0,0.72)',
+    bottom: 0,
+    justifyContent: 'center',
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0
+  },
+  overlayBody: { textAlign: 'center' },
+  overlayButton: { width: 160 },
+  overlayCard: {
+    alignItems: 'center',
+    borderRadius: 20,
+    borderWidth: 1,
+    gap: 16,
+    maxWidth: 360,
+    padding: 32
+  },
+  overlayTitle: { fontWeight: 'bold', marginBottom: -8 },
+  resetButton: {
+    marginTop: 16
+  },
+  // Bounds the ScrollView to the space `container`'s flex:1 actually gives it — without this, a
+  // ScrollView with only a contentContainerStyle isn't reliably height-constrained on native (it
+  // can render at its full unclipped content height instead of the screen's), which leaves the
+  // header's back button touch target unreliable underneath it.
+  scrollView: {
+    flex: 1
+  },
+  title: {
+    flexShrink: 1,
+    fontWeight: 'bold'
+  }
+})

package/src/StatRow.tsx

@@ -0,0 +1,49 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Text } from 'react-native-paper'
+
+interface Props {
+  label: string
+  value: string
+  // Independently optional overrides for this row's own text colors — default to the same
+  // useAutoPaperTheme()-derived formula as BaseStatsScreen (see that component's own doc for why)
+  // when omitted, so every existing caller renders identically to before.
+  fg?: string
+  fgMuted?: string
+}
+
+// A single labeled stat — label on the left (muted), value on the right (bold, full-contrast).
+// Extracted from LightCycles' own achievements.tsx, where this exact row shape backed every
+// section (Overall/Vs CPU/Two Player/Activity). fg/fgMuted default to the same
+// useAutoPaperTheme()-derived formula as BaseStatsScreen (see that component's own doc for why),
+// each independently overridable via the matching prop for a caller with its own chrome palette.
+// Deliberately just label+value text, not a color swatch or profile chip — an app needing a row
+// with a leading visual builds its own on top of this same dark-mode formula (see LightCycles' own
+// ColorStatRow/ProfileRankingRow for an example), since what that visual even is varies per game.
+export function StatRow({ label, value, fg: fgOverride, fgMuted: fgMutedOverride }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const fgMuted = fgMutedOverride ?? (dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)')
+
+  return (
+    <View style={styles.row}>
+      <Text variant='bodyMedium' style={{ color: fgMuted }}>
+        {label}
+      </Text>
+      <Text variant='bodyMedium' style={[styles.value, { color: fg }]}>
+        {value}
+      </Text>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  row: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    justifyContent: 'space-between'
+  },
+  value: {
+    fontWeight: 'bold'
+  }
+})

package/src/StatSection.tsx

@@ -0,0 +1,52 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { ReactNode } from 'react'
+import { StyleSheet, View } from 'react-native'
+import { Text } from 'react-native-paper'
+
+interface Props {
+  label: string
+  // Independently optional overrides for this section's own label color/background — default to
+  // the same useAutoPaperTheme()-derived formula as StatRow/BaseStatsScreen (see BaseStatsScreen's
+  // own doc for why) when omitted, so every existing caller renders identically to before.
+  fg?: string
+  sectionBg?: string
+  children: ReactNode
+}
+
+// A labeled, tinted-background grouping box — the "OVERALL"/"VS CPU"/"ACTIVITY"-style section
+// shape from LightCycles' own achievements.tsx, generalized to any content (typically a stack of
+// StatRow). fg/sectionBg default to the same useAutoPaperTheme()-derived formula as
+// StatRow/BaseStatsScreen (see BaseStatsScreen's own doc for why), each independently overridable
+// via the matching prop for a caller with its own chrome palette. The label itself carries the
+// section's own meaning (what it's a section OF), so this component has no opinion on that beyond
+// rendering the string it's given.
+export function StatSection({ label, fg: fgOverride, sectionBg: sectionBgOverride, children }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fg = fgOverride ?? (dark ? '#FFFFFF' : '#000000')
+  const sectionBg = sectionBgOverride ?? (dark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.04)')
+
+  return (
+    <View style={[styles.section, { backgroundColor: sectionBg }]}>
+      <Text variant='labelMedium' style={[styles.label, { color: fg }]}>
+        {label}
+      </Text>
+      {children}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  // Bold and full-contrast (fg), not the original fontless/fgMuted treatment — that read at the
+  // same visual weight as StatRow's own row labels below it (both used the identical muted color;
+  // letterSpacing/variant alone didn't separate them enough to read as "this is the group header"
+  // at a glance). Matches AchievementRow's own title styling (bold + fg) below it in the same list.
+  label: {
+    fontWeight: 'bold',
+    letterSpacing: 2
+  },
+  section: {
+    borderRadius: 12,
+    gap: 8,
+    padding: 16
+  }
+})

package/src/index.ts

@@ -1,4 +1,6 @@
+export { AchievementRow, LOCKED_BADGE_COLOR } from './AchievementRow'
 export { BaseSettingsDialog, type BaseSettingsDialogProps } from './BaseSettingsDialog'
+export { BaseStatsScreen } from './BaseStatsScreen'
 export { CornerActionButtons } from './CornerActionButtons'
 export { MONO_FONT } from './fonts'
 export { InlineColorPicker } from './InlineColorPicker'
@@ -9,6 +11,8 @@ 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 { StatRow } from './StatRow'
+export { StatSection } from './StatSection'
 // TriggerGauge itself (the raw Skia-based component) is deliberately NOT exported here, even
 // though a native-only consumer could safely skip TriggerGaugeHost's Suspense/lazy-load
 // indirection. A value re-export forces the bundler to fold TriggerGauge.tsx's own `Skia` import