@tastic/hud 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastic/hud",
-  "version": "0.2.0",
+  "version": "0.4.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,124 @@
+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
+}
+
+// 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. Derives fg/fgMuted/its own section background from useAutoPaperTheme(),
+// same as StatRow/StatSection/BaseStatsScreen — see BaseStatsScreen's own doc for why. 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 }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fg = dark ? '#FFFFFF' : '#000000'
+  const fgMuted = dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)'
+  const sectionBg = 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,158 @@
+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'
+
+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
+  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
+  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. Derives its own colors from useAutoPaperTheme(),
+// same as this package's own BaseSettingsDialog, rather than taking fg/bg/cardBg/etc as props — a
+// stats screen is app-wide chrome, not a per-player surface, so there's no reason to make every
+// caller re-derive and thread through the identical dark-mode formula BaseSettingsDialog already
+// hardcodes internally. `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', onBack, insets, onReset, resetLabel = 'Reset All Stats', resetConfirmTitle = 'Reset Everything?', resetConfirmBody = 'This permanently erases all stats and achievements. This cannot be undone.', children }: Props) {
+  const { dark, colors } = useAutoPaperTheme()
+  const [confirmResetVisible, setConfirmResetVisible] = useState(false)
+  const showReset = !!onReset
+
+  // High-contrast retro look: 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.
+  const fg = dark ? '#FFFFFF' : '#000000'
+  const bg = dark ? '#000000' : '#FFFFFF'
+  const cardBg = dark ? '#111111' : '#F2F2F2'
+  const cardBorder = dark ? 'rgba(255,255,255,0.2)' : 'rgba(0,0,0,0.2)'
+
+  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='displaySmall' 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='outlined' onPress={() => setConfirmResetVisible(true)} textColor={colors.secondary} 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={colors.secondary} />
+              <Text variant='headlineLarge' style={[styles.overlayTitle, { color: colors.secondary }]}>
+                {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/CornerActionButtons.tsx

@@ -0,0 +1,39 @@
+import { IconButton } from '@rific/feedback-press'
+import { StyleSheet } from 'react-native'
+
+interface Props {
+  onBack: () => void
+  onSettings: () => void
+  // Full-contrast foreground — same convention as every other component keying off a `dark` prop
+  // (BaseSettingsDialog, SectionedDropdown, etc.), just resolved by the caller since this component
+  // never reads theme state itself.
+  fg: string
+  // Safe-area insets already remapped onto the screen's real visual edges (see
+  // @tastic/split-screen's rotateInsets) — this component just adds the fixed 8px margin on top,
+  // it doesn't know anything about physical device orientation itself.
+  insets: { top: number; left: number; right: number }
+}
+
+// Back (top-left) + Settings (top-right) icon buttons, fixed at the screen's rotated corners — the
+// default reachability answer for a two-player screen: correct any time both players share one
+// screen but only one of them (or neither, in vs-CPU) is on the far side of a rotated zone. Not the
+// right answer for a screen where the top corners themselves fall *inside* one player's own rotated
+// zone (two-player face-to-face) — see SharedActionBand for that case instead, which callers select
+// between based on their own game-mode/orientation state (this component has no opinion on which).
+export function CornerActionButtons({ onBack, onSettings, fg, insets }: Props) {
+  return (
+    <>
+      <IconButton icon='arrow-left' iconColor={fg} size={24} style={[styles.back, { top: 8 + insets.top, left: 8 + insets.left }]} onPress={onBack} accessibilityLabel='Back' />
+      <IconButton icon='cog' iconColor={fg} size={24} style={[styles.topRight, { top: 8 + insets.top, right: 8 + insets.right }]} onPress={onSettings} accessibilityLabel='Settings' />
+    </>
+  )
+}
+
+const styles = StyleSheet.create({
+  back: {
+    position: 'absolute'
+  },
+  topRight: {
+    position: 'absolute'
+  }
+})

package/src/LabeledDropdown.tsx

@@ -0,0 +1,175 @@
+import { getContrastColor } from '@rific/auto-paper'
+import { TouchableRipple } from '@rific/feedback-press'
+import { RefObject } from 'react'
+import { ScrollView, StyleSheet, View } from 'react-native'
+import { Icon, Text } from 'react-native-paper'
+
+import { PopoverBody } from './PopoverBody'
+import { PopoverAlign, PopoverVerticalAlign, useAutoAlign } from './useAutoAlign'
+import { PopoverHost } from './usePopoverHost'
+
+const TRIGGER_HEIGHT = 28
+const POPOVER_WIDTH = 180
+const ROW_HEIGHT = 36
+const LIST_PADDING = 8
+
+// Exported so a caller that needs to independently compute this popover's own placement — to feed
+// alignOverride with, say, a @tastic/split-screen-zone-aware hook's result — can match its real
+// content dimensions exactly, rather than hardcoding or re-deriving this component's own internal
+// sizing (which alignOverride itself deliberately doesn't take a dependency on any particular
+// zone-awareness package to compute).
+export const LABELED_DROPDOWN_POPOVER_WIDTH = POPOVER_WIDTH
+export function getLabeledDropdownContentHeight(optionCount: number): number {
+  return LIST_PADDING * 2 + optionCount * ROW_HEIGHT
+}
+
+export interface LabeledDropdownOption<T extends string> {
+  value: T
+  label: string
+  icon?: string
+}
+
+// Same shape useAutoAlign itself returns — lets a caller inside a @tastic/split-screen zone (or
+// any other layout this package doesn't know about) substitute its own alignment decision via
+// `alignOverride` below, without this package taking a dependency on that caller's own hook.
+interface AlignResult {
+  align: PopoverAlign
+  verticalAlign: PopoverVerticalAlign
+  maxHeight: number
+  measured: boolean
+  triggerRef: RefObject<View | null>
+}
+
+interface Props<T extends string> {
+  id: string
+  host: PopoverHost
+  options: LabeledDropdownOption<T>[]
+  value: T
+  onChange: (value: T) => void
+  color: string
+  dark: boolean
+  // Forces a specific horizontal alignment instead of letting whichever placement result applies
+  // (see alignOverride below) decide. Matches PopoverBody's own align prop meaning.
+  align?: 'left' | 'right' | 'center'
+  // Substitutes this package's own plain useAutoAlign-based placement wholesale (align,
+  // verticalAlign, maxHeight, measured, triggerRef) with a caller-supplied one — e.g. 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 actual zone boundary. Omit for the
+  // ordinary case (a popover with nothing but the screen edge to avoid).
+  alignOverride?: AlignResult
+}
+
+// A name-trigger + selection popover in the same visual style as @tastic/profile's own
+// ProfilePicker trigger — an uppercase text label + chevron, opening a list whose selected row
+// fills entirely with the seat's own accent color — rather than this package's own
+// SectionedDropdown, whose trigger is a fixed icon with a gauge ring around it. For a choice that
+// reads more like "who/what you're playing" than "a game setting" (a CPU seat's own difficulty,
+// occupying the same slot a human seat's ProfilePicker would), the always-visible text label
+// carries more of the meaning than an icon would on its own.
+export function LabeledDropdown<T extends string>({ id, host, options, value, onChange, color, dark, align: forcedAlign, alignOverride }: Props<T>) {
+  const menuBg = dark ? '#000000' : '#FFFFFF'
+  const fg = dark ? '#FFFFFF' : '#000000'
+
+  const open = host.openId === id
+  const selected = options.find((o) => o.value === value) ?? null
+  const contentHeight = LIST_PADDING * 2 + options.length * ROW_HEIGHT
+  // Always called, even when alignOverride is supplied and this result goes unused — hooks can't be
+  // called conditionally. A caller passing alignOverride (e.g. LightCycles' own useZoneClampedAlign,
+  // which already wraps this same hook) does end up measuring the trigger twice; an acceptable
+  // tradeoff for keeping this component's own hook usage unconditional and override-shaped rather
+  // than needing a second, hook-free code path.
+  const auto = useAutoAlign(open, POPOVER_WIDTH, contentHeight)
+  const placement = alignOverride ?? auto
+  const { maxHeight, measured, triggerRef, verticalAlign } = placement
+  const align = forcedAlign ?? placement.align
+
+  const handleSelect = (option: LabeledDropdownOption<T>) => {
+    onChange(option.value)
+    host.close()
+  }
+
+  return (
+    <View style={[styles.anchor, open && styles.anchorOpen]}>
+      <TouchableRipple onPress={() => host.toggle(id)} style={styles.trigger}>
+        <View ref={triggerRef} collapsable={false} style={styles.triggerInner}>
+          <Text style={[styles.triggerLabel, { color }]} numberOfLines={1}>
+            {(selected?.label ?? '').toUpperCase()}
+          </Text>
+          <Icon source='menu-down' size={16} color={color} />
+        </View>
+      </TouchableRipple>
+
+      {/* Gated on `measured`, not just `open` — see InlineColorPicker's identical fix. */}
+      <PopoverBody visible={open && measured} align={align} verticalAlign={verticalAlign} caretColor={menuBg} caretBorderColor={color} caretBorderWidth={2} triggerSize={TRIGGER_HEIGHT}>
+        <ScrollView style={[styles.menu, { backgroundColor: menuBg, borderColor: color, width: POPOVER_WIDTH, maxHeight }]} contentContainerStyle={styles.menuContent} showsVerticalScrollIndicator={false}>
+          {options.map((option) => {
+            const isSelected = option.value === value
+            const onColor = getContrastColor(color)
+            return (
+              <TouchableRipple key={option.value} onPress={() => handleSelect(option)} style={[styles.row, isSelected && { backgroundColor: color }]}>
+                <View style={styles.rowInner}>
+                  {option.icon && <Icon source={option.icon} size={18} color={isSelected ? onColor : fg} />}
+                  <Text style={[styles.rowLabel, { color: isSelected ? onColor : fg }]} numberOfLines={1}>
+                    {option.label}
+                  </Text>
+                </View>
+              </TouchableRipple>
+            )
+          })}
+        </ScrollView>
+      </PopoverBody>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  anchor: {
+    position: 'relative'
+  },
+  // React Native Web gives every position:'relative' view its own stacking context, so the
+  // elevation has to live on the anchor itself — see PopoverBody's own stacking-context notes.
+  anchorOpen: {
+    zIndex: 100
+  },
+  menu: {
+    borderRadius: 12,
+    borderWidth: 2,
+    elevation: 8,
+    shadowColor: '#000000',
+    shadowOffset: { height: 2, width: 0 },
+    shadowOpacity: 0.3,
+    shadowRadius: 8
+  },
+  menuContent: {
+    padding: LIST_PADDING
+  },
+  row: {
+    borderRadius: 8,
+    height: ROW_HEIGHT
+  },
+  rowInner: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    flex: 1,
+    gap: 8,
+    paddingHorizontal: 12
+  },
+  rowLabel: {
+    flex: 1,
+    fontSize: 14
+  },
+  trigger: {
+    alignSelf: 'flex-start'
+  },
+  triggerInner: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 2,
+    height: TRIGGER_HEIGHT
+  },
+  triggerLabel: {
+    fontSize: 13,
+    fontWeight: '700',
+    letterSpacing: 1
+  }
+})

package/src/SharedActionBand.tsx

@@ -0,0 +1,61 @@
+import { IconButton } from '@rific/feedback-press'
+import { ReactNode } from 'react'
+import { StyleSheet, View } from 'react-native'
+
+interface Props {
+  onBack: () => void
+  onSettings: () => void
+  // Optional, and expected to be passed together in practice (either a screen has both a randomize
+  // and a reset action, or neither) — kept as two independently-optional props rather than one pair
+  // flag so a caller with only one of the two isn't forced to fake the other.
+  onRandomize?: () => void
+  onReset?: () => void
+  fg: string
+  // Whether one of THIS band's own popovers (i.e. something rendered inside `children`) is
+  // currently open — the caller computes this (typically `host.openId !== null &&
+  // OWN_IDS.includes(host.openId)`), since only the caller knows which popover ids belong to its
+  // own children. Elevates the whole column above sibling panels when true — React Native Web gives
+  // every position:'relative' view its own stacking context, so a popover escaping `children` needs
+  // this wrapper itself elevated, not just the popover content, to paint above a later sibling
+  // (e.g. a player panel) rather than underneath it.
+  popoverOpen: boolean
+  // The screen's own per-round option row (grid size, arena, etc.) — rendered directly below the
+  // action row, inside the same elevating column.
+  children: ReactNode
+}
+
+// The reachability fix for a two-player screen where the plain top-left/top-right corners (see
+// CornerActionButtons) would land inside one player's own rotated zone — most concretely, two-
+// player face-to-face, where the far player's zone always covers the top half of the screen. Folds
+// back/randomize/reset/settings into one row that sits on neutral ground instead (the shared band
+// between the two players' zones), directly above the caller's own per-round option row. The
+// caller decides *when* this applies (it owns gameMode/orientationMode) — this component only
+// renders the result once that decision's already been made.
+export function SharedActionBand({ onBack, onSettings, onRandomize, onReset, fg, popoverOpen, children }: Props) {
+  return (
+    <View style={[styles.column, popoverOpen && styles.columnOpen]}>
+      <View style={styles.actionsRow}>
+        <IconButton icon='arrow-left' iconColor={fg} size={20} onPress={onBack} accessibilityLabel='Back' />
+        {onRandomize && <IconButton icon='dice-multiple' iconColor={fg} size={18} onPress={onRandomize} accessibilityLabel='Randomize match settings' />}
+        {onReset && <IconButton icon='restore' iconColor={fg} size={18} onPress={onReset} accessibilityLabel='Reset match settings to defaults' />}
+        <IconButton icon='cog' iconColor={fg} size={20} onPress={onSettings} accessibilityLabel='Settings' />
+      </View>
+      {children}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  actionsRow: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    gap: 16
+  },
+  column: {
+    alignItems: 'center',
+    gap: 8
+  },
+  columnOpen: {
+    zIndex: 100
+  }
+})

package/src/StatRow.tsx

@@ -0,0 +1,44 @@
+import { useAutoPaperTheme } from '@rific/auto-paper'
+import { StyleSheet, View } from 'react-native'
+import { Text } from 'react-native-paper'
+
+interface Props {
+  label: string
+  value: 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). Derives its own colors from useAutoPaperTheme(),
+// same as BaseStatsScreen — see that component's own doc for why a stats-screen row doesn't take
+// fg/fgMuted as props. 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 }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fg = dark ? '#FFFFFF' : '#000000'
+  const fgMuted = 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,40 @@
+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
+  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). Derives its own colors from useAutoPaperTheme(), same as StatRow/BaseStatsScreen — see
+// BaseStatsScreen's own doc for why. 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, children }: Props) {
+  const { dark } = useAutoPaperTheme()
+  const fgMuted = dark ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)'
+  const sectionBg = 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: fgMuted }]}>
+        {label}
+      </Text>
+      {children}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  label: {
+    letterSpacing: 2
+  },
+  section: {
+    borderRadius: 12,
+    gap: 8,
+    padding: 16
+  }
+})

package/src/index.ts

@@ -1,11 +1,18 @@
+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'
+export { getLabeledDropdownContentHeight, LABELED_DROPDOWN_POPOVER_WIDTH, LabeledDropdown, type LabeledDropdownOption } from './LabeledDropdown'
 export { loadSkiaWeb } from './loadSkiaWeb'
 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 { 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