@tastic/hud 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Deaton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @tastic/hud
+
+Visual component kit for local-multiplayer React Native games — inline (non-modal) popovers,
+dropdowns, color pickers, gauges, ready buttons, and dialogs. Every interactive piece stays scoped
+to one player's own zone on a shared screen, so it never blocks the rest of the screen the way a
+full-screen modal would.
+
+Sibling to [`@tastic/split-screen`](https://github.com/jayrdeaton/react-native-split-screen), the
+two-player layout/orientation engine this kit's components are built to render correctly inside —
+in particular, `PopoverBody`'s positioning survives an ancestor's 180° rotation. Neither package
+depends on the other; they compose at your own screen.
+
+## Why not a modal?
+
+A full-screen `Dialog` blocks the whole screen. In a two-player lobby that's a non-starter — player
+2 can't touch anything while player 1's color picker is open. Every popover here renders **inline**,
+as an absolutely-positioned sibling of its own trigger, so it never blocks anything outside its own
+corner of the screen.
+
+## What's in here
+
+- **`usePopoverHost()`** — tracks which *one* popover (by id) is open within a group, so opening one
+  closes any sibling already open in the same group.
+- **`PopoverBody`** — the low-level popover shell (position, caret, alignment). `SectionedDropdown`
+  and `InlineColorPicker` are built on it.
+- **`useAutoAlign`** — measures a trigger's actual on-screen position and picks whichever alignment
+  (left/right/center, above/below) keeps a popover from overflowing a screen edge — including a
+  `maxHeight` for the caller to cap content and scroll when neither direction has enough room.
+- **`SectionedDropdown`** — a popover holding any mix of single-select ("pick one", radio-style) and
+  multi-select ("pick some", checkbox-style, optional all/clear footer) sections, divided by rules.
+- **`InlineColorPicker`** — swatch-grid color popover, auto-sized columns, with an optional "taken"
+  color (shown disabled, or swappable).
+- **`TriggerGauge`** — decorative ring of tick marks around a trigger, showing which option(s) are
+  active without opening the popover.
+- **`ReadyButton`** — a per-player or standalone ready toggle.
+- **`PressAwayOverlay`** — an invisible full-bleed tap-catcher for press-away-to-close. This is the
+  one piece that needs care in a split-screen layout — see below.
+
+## The press-away pattern (read this before wiring it up)
+
+A single full-screen `PressAwayOverlay` works fine for a one-player screen. It does **not** work
+for a two-player split screen: if player 1's press-away covers the whole screen, then any tap on
+player 2's side — even one that has nothing to do with player 1 — falls through and closes player
+1's popover. That defeats the point of letting both players drive their own settings at once.
+
+The fix is two overlays with an asymmetric relationship, not two independent halves:
+
+```tsx
+const p1Host = usePopoverHost()
+const p2Host = usePopoverHost()
+
+return (
+  <View style={styles.container}>
+    {/* Player 1's overlay covers the ENTIRE screen. This is correct even though player 1 visually
+    only owns "their side" — any shared-settings row that reads as "player 1's" (see your own
+    layout) may not stay confined to a literal half of the screen, and this overlay needs to cover
+    everywhere player 1 might have something open. */}
+    <PressAwayOverlay active={p1Host.openId !== null} onPress={p1Host.close} />
+
+    {/* Player 2's overlay is scoped to just their own zone (half the screen, whichever side
+    they're on — see @tastic/split-screen's panelLayout for how to size this) — and, being a later
+    sibling, it paints on top of player 1's overlay within that rect, so a tap there is always
+    player 2's to own.
+
+    Critically: this has to mount whenever EITHER host is open, not just p2Host. If it only mounted
+    for p2Host, then closing player 2's popover would unmount it — exposing player 1's full-screen
+    overlay underneath for the rest of that render, and the next tap anywhere on player 2's side
+    (even if player 2 has nothing open) would fall through and close player 1's popover instead.
+    Mounting it any time p1Host is open too "shields" player 2's zone from player 1's overlay
+    unconditionally; its onPress (p2Host.close) is just a harmless no-op when p2Host is already
+    closed. */}
+    <PressAwayOverlay active={p1Host.openId !== null || p2Host.openId !== null} onPress={p2Host.close} style={styles.p2Zone} />
+
+    {/* Real content goes after both overlays — plain paint order (later siblings on top) is what
+    keeps every real trigger/button directly tappable; only genuinely empty space falls through to
+    the overlays above. */}
+    <Player1Panel host={p1Host} />
+    <Player2Panel host={p2Host} style={styles.p2Zone} />
+  </View>
+)
+```
+
+The general rule for N players: the "owner" of the broadest zone (usually whoever's panel absorbs
+your shared/global settings) gets the whole-screen overlay; every other player's zone-scoped overlay
+must stay mounted (shielding, if not actually closing anything) whenever *any* host with broader
+reach is open — not just their own.
+
+## Install (local dev via yalc)
+
+Not published to the public npm registry yet.
+
+```bash
+cd react-native-hud
+npm run build
+yalc publish
+
+cd ../your-game
+yalc add @tastic/hud
+npm install
+```
+
+Re-run `npm run build && yalc push` from this package after any change to propagate it to every
+linked consumer at once.
+
+## Peer dependencies
+
+`react`, `react-native`, `react-native-paper` (`Icon`, `IconButton`, `Text`), `@rific/auto-paper`
+(`defaultColors`, `getContrastColor`, `getBlendedColor`, `SeedColor`), `@rific/feedback-press`
+(`IconButton`, `TouchableRipple`) — none of these are bundled, so use whatever versions your app
+already has.

package/dist/TriggerGauge-HIPRGEWJ.mjs

@@ -0,0 +1,117 @@
+// src/TriggerGauge.tsx
+import { Canvas, Path, Skia } from "@shopify/react-native-skia";
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { Easing, useDerivedValue, useSharedValue, withTiming } from "react-native-reanimated";
+import { jsx, jsxs } from "react/jsx-runtime";
+var UNLIT_THICKNESS = 3;
+var LIT_THICKNESS = 7;
+var DASH_GAP_PX = 9;
+var ARC_GAP = 2;
+var DEFAULT_START_DEG = 180;
+var MIN_DASH_ANGLE_DEG = 4;
+var MOUNT_DURATION_MS = 450;
+var MOUNT_STAGGER_MS = 40;
+var SELECTION_TRANSITION_DURATION_MS = 260;
+function TriggerGauge({ segments, litIndices, size, accentColor, mutedColor, dashWidth, startDeg = DEFAULT_START_DEG, endDeg = startDeg }) {
+  const totalDurationMs = MOUNT_DURATION_MS + Math.max(0, segments - 1) * MOUNT_STAGGER_MS;
+  const mountProgress = useSharedValue(0);
+  useLayoutEffect(() => {
+    mountProgress.value = withTiming(1, { duration: totalDurationMs, easing: Easing.out(Easing.cubic) });
+  }, []);
+  const rawSweepDeg = ((endDeg - startDeg) % 360 + 360) % 360;
+  const totalSweepDeg = rawSweepDeg === 0 ? 360 : rawSweepDeg;
+  const step = segments > 0 ? totalSweepDeg / segments : 0;
+  const centerDeg = useCallback((i) => startDeg + (i + 0.5) * step, [startDeg, step]);
+  const singleSelect = litIndices.length === 1;
+  const angleDeg = useSharedValue(centerDeg(litIndices[0] ?? 0));
+  const litIndicesKey = [...litIndices].sort((a, b) => a - b).join(",");
+  const [transitionFrom, setTransitionFrom] = useState(litIndices);
+  const transitionFromKey = [...transitionFrom].sort((a, b) => a - b).join(",");
+  const lastKeyRef = useRef(litIndicesKey);
+  const lastIndicesRef = useRef(litIndices);
+  const selectionProgress = useSharedValue(1);
+  useLayoutEffect(() => {
+    if (litIndicesKey !== lastKeyRef.current) {
+      if (singleSelect && lastIndicesRef.current.length === 1) {
+        angleDeg.value = withTiming(centerDeg(litIndices[0]), { duration: SELECTION_TRANSITION_DURATION_MS, easing: Easing.out(Easing.cubic) });
+      } else {
+        setTransitionFrom(lastIndicesRef.current);
+        selectionProgress.value = 0;
+        selectionProgress.value = withTiming(1, { duration: SELECTION_TRANSITION_DURATION_MS, easing: Easing.out(Easing.cubic) });
+      }
+      lastKeyRef.current = litIndicesKey;
+    }
+    lastIndicesRef.current = litIndices;
+  }, [litIndicesKey, litIndices, selectionProgress, angleDeg, singleSelect, centerDeg]);
+  const radius = size / 2 + ARC_GAP;
+  const slotDeg = step;
+  const gapDeg = DASH_GAP_PX / radius * (180 / Math.PI);
+  const autoDashAngleDeg = Math.max(MIN_DASH_ANGLE_DEG, slotDeg - gapDeg);
+  const dashAngleDeg = dashWidth != null ? Math.max(MIN_DASH_ANGLE_DEG, dashWidth / radius * (180 / Math.PI)) : autoDashAngleDeg;
+  const diameter = radius * 2;
+  const canvasSize = diameter + LIT_THICKNESS;
+  const oval = Skia.XYWHRect(LIT_THICKNESS / 2, LIT_THICKNESS / 2, diameter, diameter);
+  const unlitPath = useDerivedValue(() => {
+    const path = Skia.Path.Make();
+    for (let i = 0; i < segments; i++) {
+      if (litIndices.includes(i)) continue;
+      let local = 1;
+      if (mountProgress.value < 1) {
+        const startFrac = i * MOUNT_STAGGER_MS / totalDurationMs;
+        const endFrac = startFrac + MOUNT_DURATION_MS / totalDurationMs;
+        local = Math.min(1, Math.max(0, (mountProgress.value - startFrac) / (endFrac - startFrac)));
+      }
+      const sweep = dashAngleDeg * local;
+      if (sweep <= 0) continue;
+      const dashCenterDeg = startDeg + (i + 0.5) * step;
+      path.addArc(oval, dashCenterDeg - 90 - sweep / 2, sweep);
+    }
+    return path;
+  }, [segments, litIndicesKey, step, startDeg, dashAngleDeg, totalDurationMs, oval.x, oval.y, oval.width, oval.height]);
+  const litPath = useDerivedValue(() => {
+    const path = Skia.Path.Make();
+    if (mountProgress.value >= 1 && singleSelect) {
+      path.addArc(oval, angleDeg.value - 90 - dashAngleDeg / 2, dashAngleDeg);
+      return path;
+    }
+    for (let i = 0; i < segments; i++) {
+      const isLitNow = litIndices.includes(i);
+      const wasLit = transitionFrom.includes(i);
+      if (!isLitNow && !wasLit) continue;
+      let local;
+      if (mountProgress.value < 1) {
+        if (!isLitNow) continue;
+        const startFrac = i * MOUNT_STAGGER_MS / totalDurationMs;
+        const endFrac = startFrac + MOUNT_DURATION_MS / totalDurationMs;
+        local = Math.min(1, Math.max(0, (mountProgress.value - startFrac) / (endFrac - startFrac)));
+      } else if (isLitNow === wasLit) {
+        local = 1;
+      } else if (isLitNow) {
+        local = selectionProgress.value;
+      } else {
+        local = 1 - selectionProgress.value;
+      }
+      const sweep = dashAngleDeg * local;
+      if (sweep <= 0) continue;
+      const dashCenterDeg = startDeg + (i + 0.5) * step;
+      path.addArc(oval, dashCenterDeg - 90 - sweep / 2, sweep);
+    }
+    return path;
+  }, [segments, litIndicesKey, transitionFromKey, singleSelect, step, startDeg, dashAngleDeg, totalDurationMs, oval.x, oval.y, oval.width, oval.height]);
+  if (segments < 2) return null;
+  return /* @__PURE__ */ jsx(View, { style: [styles.container, { height: size, width: size }], pointerEvents: "none", children: /* @__PURE__ */ jsxs(Canvas, { style: { height: canvasSize, width: canvasSize }, children: [
+    /* @__PURE__ */ jsx(Path, { path: unlitPath, style: "stroke", strokeWidth: UNLIT_THICKNESS, strokeCap: "round", color: mutedColor, opacity: 0.35 }),
+    /* @__PURE__ */ jsx(Path, { path: litPath, style: "stroke", strokeWidth: LIT_THICKNESS, strokeCap: "round", color: accentColor, opacity: 1 })
+  ] }) });
+}
+var styles = StyleSheet.create({
+  container: {
+    alignItems: "center",
+    justifyContent: "center",
+    position: "absolute"
+  }
+});
+export {
+  TriggerGauge
+};

package/dist/index.d.mts

@@ -0,0 +1,127 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SeedColor } from '@rific/auto-paper';
+import { StyleProp, ViewStyle, View } from 'react-native';
+
+declare const MONO_FONT: string;
+
+interface PopoverHost {
+    openId: string | null;
+    toggle: (id: string) => void;
+    close: () => void;
+}
+declare function usePopoverHost(): PopoverHost;
+
+interface Props$4 {
+    id: string;
+    host: PopoverHost;
+    value: string;
+    onChange: (hex: string) => void;
+    swatches?: SeedColor[];
+    takenValue?: string;
+    allowSwapTaken?: boolean;
+    dark: boolean;
+    align?: 'left' | 'right' | 'center';
+    icon?: string;
+    autoDismiss?: boolean;
+    columns?: number;
+}
+declare function InlineColorPicker({ id, host, value, onChange, swatches, takenValue, allowSwapTaken, dark, align: alignOverride, icon, autoDismiss, columns }: Props$4): react.JSX.Element;
+
+declare function loadSkiaWeb(): Promise<void>;
+
+interface Props$3 {
+    visible: boolean;
+    children: ReactNode;
+    align?: 'left' | 'right' | 'center';
+    verticalAlign?: 'below' | 'above';
+    caretColor?: string;
+    caretBorderColor?: string;
+    caretBorderWidth?: number;
+    triggerSize?: number;
+}
+declare function PopoverBody({ visible, children, align, verticalAlign, caretColor, caretBorderColor, caretBorderWidth, triggerSize }: Props$3): react.JSX.Element | null;
+
+interface Props$2 {
+    active: boolean;
+    onPress: () => void;
+    style?: StyleProp<ViewStyle>;
+}
+declare function PressAwayOverlay({ active, onPress, style }: Props$2): react.JSX.Element | null;
+
+interface Props$1 {
+    color: string;
+    ready: boolean;
+    onToggleReady: () => void;
+    style?: StyleProp<ViewStyle>;
+    labelFontFamily?: string;
+}
+declare function ReadyButton({ color, ready, onToggleReady, style, labelFontFamily }: Props$1): react.JSX.Element;
+
+interface MenuOption<T extends string | number> {
+    value: T;
+    label: string;
+    description?: string;
+    icon?: string;
+    iconSize?: number;
+}
+interface SingleSelectSection<T extends string | number> {
+    kind: 'single';
+    id: string;
+    options: MenuOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+}
+interface MultiSelectSection<T extends string | number> {
+    kind: 'multi';
+    id: string;
+    options: MenuOption<T>[];
+    value: T[];
+    onChange: (value: T[]) => void;
+    allClear?: boolean;
+}
+type MenuSection = SingleSelectSection<any> | MultiSelectSection<any>;
+interface Props {
+    id: string;
+    host: PopoverHost;
+    icon: string;
+    accessibilityLabel: string;
+    sections: MenuSection[];
+    accentColor: string;
+    mutedColor: string;
+    onAccentColor?: string;
+    dark: boolean;
+    align?: 'left' | 'right' | 'center';
+    autoDismiss?: boolean;
+    labelFontFamily?: string;
+    allClearLabels?: {
+        all: string;
+        clear: string;
+    };
+}
+declare function SectionedDropdown({ id, host, icon, accessibilityLabel, sections, accentColor, mutedColor, onAccentColor, dark, align: alignOverride, autoDismiss, labelFontFamily, allClearLabels }: Props): react.JSX.Element;
+
+interface TriggerGaugeProps {
+    segments: number;
+    litIndices: number[];
+    size: number;
+    accentColor: string;
+    mutedColor: string;
+    dashWidth?: number;
+    startDeg?: number;
+    endDeg?: number;
+}
+
+declare function TriggerGaugeHost(props: TriggerGaugeProps): react.JSX.Element;
+
+type PopoverAlign = 'left' | 'right' | 'center';
+type PopoverVerticalAlign = 'below' | 'above';
+declare function useAutoAlign(open: boolean, contentWidth: number, contentHeight: number): {
+    align: PopoverAlign;
+    maxHeight: number;
+    measured: boolean;
+    triggerRef: react.RefObject<View | null>;
+    verticalAlign: PopoverVerticalAlign;
+};
+
+export { InlineColorPicker, MONO_FONT, type MenuOption, type MenuSection, type MultiSelectSection, type PopoverAlign, PopoverBody, type PopoverHost, type PopoverVerticalAlign, PressAwayOverlay, ReadyButton, SectionedDropdown, type SingleSelectSection, TriggerGaugeHost, type TriggerGaugeProps, loadSkiaWeb, useAutoAlign, usePopoverHost };

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SeedColor } from '@rific/auto-paper';
+import { StyleProp, ViewStyle, View } from 'react-native';
+
+declare const MONO_FONT: string;
+
+interface PopoverHost {
+    openId: string | null;
+    toggle: (id: string) => void;
+    close: () => void;
+}
+declare function usePopoverHost(): PopoverHost;
+
+interface Props$4 {
+    id: string;
+    host: PopoverHost;
+    value: string;
+    onChange: (hex: string) => void;
+    swatches?: SeedColor[];
+    takenValue?: string;
+    allowSwapTaken?: boolean;
+    dark: boolean;
+    align?: 'left' | 'right' | 'center';
+    icon?: string;
+    autoDismiss?: boolean;
+    columns?: number;
+}
+declare function InlineColorPicker({ id, host, value, onChange, swatches, takenValue, allowSwapTaken, dark, align: alignOverride, icon, autoDismiss, columns }: Props$4): react.JSX.Element;
+
+declare function loadSkiaWeb(): Promise<void>;
+
+interface Props$3 {
+    visible: boolean;
+    children: ReactNode;
+    align?: 'left' | 'right' | 'center';
+    verticalAlign?: 'below' | 'above';
+    caretColor?: string;
+    caretBorderColor?: string;
+    caretBorderWidth?: number;
+    triggerSize?: number;
+}
+declare function PopoverBody({ visible, children, align, verticalAlign, caretColor, caretBorderColor, caretBorderWidth, triggerSize }: Props$3): react.JSX.Element | null;
+
+interface Props$2 {
+    active: boolean;
+    onPress: () => void;
+    style?: StyleProp<ViewStyle>;
+}
+declare function PressAwayOverlay({ active, onPress, style }: Props$2): react.JSX.Element | null;
+
+interface Props$1 {
+    color: string;
+    ready: boolean;
+    onToggleReady: () => void;
+    style?: StyleProp<ViewStyle>;
+    labelFontFamily?: string;
+}
+declare function ReadyButton({ color, ready, onToggleReady, style, labelFontFamily }: Props$1): react.JSX.Element;
+
+interface MenuOption<T extends string | number> {
+    value: T;
+    label: string;
+    description?: string;
+    icon?: string;
+    iconSize?: number;
+}
+interface SingleSelectSection<T extends string | number> {
+    kind: 'single';
+    id: string;
+    options: MenuOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+}
+interface MultiSelectSection<T extends string | number> {
+    kind: 'multi';
+    id: string;
+    options: MenuOption<T>[];
+    value: T[];
+    onChange: (value: T[]) => void;
+    allClear?: boolean;
+}
+type MenuSection = SingleSelectSection<any> | MultiSelectSection<any>;
+interface Props {
+    id: string;
+    host: PopoverHost;
+    icon: string;
+    accessibilityLabel: string;
+    sections: MenuSection[];
+    accentColor: string;
+    mutedColor: string;
+    onAccentColor?: string;
+    dark: boolean;
+    align?: 'left' | 'right' | 'center';
+    autoDismiss?: boolean;
+    labelFontFamily?: string;
+    allClearLabels?: {
+        all: string;
+        clear: string;
+    };
+}
+declare function SectionedDropdown({ id, host, icon, accessibilityLabel, sections, accentColor, mutedColor, onAccentColor, dark, align: alignOverride, autoDismiss, labelFontFamily, allClearLabels }: Props): react.JSX.Element;
+
+interface TriggerGaugeProps {
+    segments: number;
+    litIndices: number[];
+    size: number;
+    accentColor: string;
+    mutedColor: string;
+    dashWidth?: number;
+    startDeg?: number;
+    endDeg?: number;
+}
+
+declare function TriggerGaugeHost(props: TriggerGaugeProps): react.JSX.Element;
+
+type PopoverAlign = 'left' | 'right' | 'center';
+type PopoverVerticalAlign = 'below' | 'above';
+declare function useAutoAlign(open: boolean, contentWidth: number, contentHeight: number): {
+    align: PopoverAlign;
+    maxHeight: number;
+    measured: boolean;
+    triggerRef: react.RefObject<View | null>;
+    verticalAlign: PopoverVerticalAlign;
+};
+
+export { InlineColorPicker, MONO_FONT, type MenuOption, type MenuSection, type MultiSelectSection, type PopoverAlign, PopoverBody, type PopoverHost, type PopoverVerticalAlign, PressAwayOverlay, ReadyButton, SectionedDropdown, type SingleSelectSection, TriggerGaugeHost, type TriggerGaugeProps, loadSkiaWeb, useAutoAlign, usePopoverHost };