@tastic/hud 0.13.0 → 0.14.0

package/README.md

@@ -94,6 +94,43 @@ position can be nowhere near where the trigger actually is on screen, which is e
 rotation-awareness fixes: without it, a popover can pick an alignment for where its trigger *used to
 be* before rotating, clipping off the edge it's actually now near instead of the one it was near.
 
+### `BaseSettingsDialog` lays out in its own turned frame
+
+The settings sheet doesn't rotate its card in place. It renders through one Paper `Portal` into a
+`RotatedFrame` (below) turned by its `rotation`, sized to the turned footprint, with rotated safe-area
+insets and its own `Portal.Host`, and the Dialog portals into that host. So at +/-90 the sheet's
+`maxHeight: '90%'` is measured against the phone's short edge and the whole list scrolls, instead of
+running off the screen with its top row (Lock Orientation) out of reach. The frame is pass-through and
+an identity frame at 0, so nothing changes in portrait. Pass `rotation={0}` when the dialog already
+sits under a `Portal.Host` inside a turned frame of your own.
+
+This needs `@rific/auto-paper` 0.12.2 or later: the Dialog's own body now renders at the portal host,
+and only 0.12.2+ mounts that host inside auto-paper's own contexts (blur, Reanimated, defaults).
+
+### `RotatedFrame`
+
+The frame itself, exported for a screen or overlay that should follow the phone as one piece:
+
+```tsx
+import { RotatedFrame } from '@tastic/hud'
+
+<RotatedFrame portalHost rotatedSafeArea maxContentWidth={640}>
+  <StatsList />
+</RotatedFrame>
+```
+
+- `rotation`: the angle to turn by; defaults to the live `useRotation()`.
+- `rotatedSafeArea`: re-provide the safe-area insets remapped onto the frame's own edges, for content
+  that reads `useSafeAreaInsets()` itself. Leave it off for content that rotates insets on its own.
+- `portalHost`: mount a Paper `Portal.Host` inside the frame, so dialogs lay out and turn with it (tell
+  them `rotation={0}`). Must be static per call site: flipping it remounts the contents.
+- `passThrough`: let touches fall through the frame's own boxes, for a frame laid over other content.
+- `maxContentWidth`: cap the centred content column, in the wide (landscape) footprint only.
+
+The tree is identical at every angle, so turning the phone never remounts what's inside. Tap-driven
+content only: react-native-gesture-handler's deltas are untransformed, so never put a gesture-tracked
+board inside it.
+
 ## 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
@@ -545,10 +582,10 @@ resolve module".
 | `react`, `react-native` | >=19.0.0, >=0.76.0 | every entry |
 | `react-native-paper` | >=5.0.0 | main entry, `./guide` |
 | `react-native-reanimated` | >=3.0.0 | main entry (`StaggeredWord`), `./guide` |
-| `@rific/auto-paper` | >=0.9.4 | main entry (`AutoAppearancePicker` first shipped in 0.9.4), `./guide` |
+| `@rific/auto-paper` | >=0.12.2 | main entry (`BaseSettingsDialog` needs the nested `Portal.Host` first shipped in 0.12.2), `./guide` |
 | `@rific/feedback-press` | >=0.10.2 | main entry (`useSoundSettings` first shipped in 0.10.2), `./guide` |
 | `react-native-safe-area-context` | >=5.0.0 | main entry (`useZoneClampedAlign`) |
-| `@tastic/core` | >=0.5.0, optional | main entry: `useRotation()` and most dialogs; `ContentGutter` needs `useRotatedWindowDimensions()`, first shipped in 0.5.0 |
+| `@tastic/core` | >=0.12.0, optional | main entry: `useRotation()` and most dialogs; `RotatedFrame` and `BaseSettingsDialog` need `FakeLandscapeView`'s `rotation`/`passThrough`, first shipped in 0.12.0 |
 | `@rific/updater` | >=0.4.0, optional | main entry: `BaseSettingsDialog`, `UpdateDialog` |
 | `@tastic/profile` | >=0.4.0, optional | main entry: `PlayerSetupPanel`, `AchievementUnlockList` (`ProfileChip`) |
 | `@tastic/split-screen` | >=0.5.0, optional | main entry: `useZoneClampedAlign` |

package/dist/index.d.mts

@@ -398,6 +398,40 @@ interface Props$3 {
 }
 declare function ReadyButton({ color, ready, onToggleReady, style, labelFontFamily }: Props$3): react.JSX.Element;
 
+interface RotatedFrameProps {
+    children: ReactNode;
+    /** The angle to turn the frame by. Defaults to the live physical hold (@tastic/core's useRotation); pass it
+     * when the caller already has the exact angle it wants, e.g. a dialog handed its caller's rotation, or 0 for
+     * one that already sits inside a turned frame. */
+    rotation?: ViewRotation;
+    /** Give everything inside the frame the safe-area insets already remapped onto the frame's own edges (see
+     * @tastic/core's rotateInsets), so a component that reads `useSafeAreaInsets()` itself (a library screen,
+     * Paper's Modal, a toaster) lands on the right edge when the frame is turned. Leave it off for content that
+     * rotates the insets itself, which would otherwise rotate them twice. */
+    rotatedSafeArea?: boolean;
+    /** Mount a Paper Portal.Host INSIDE the frame, so a dialog (Paper's Portal otherwise mounts at the app root,
+     * outside the frame) is laid out against the frame's footprint and turned with it. The dialog must then be
+     * told `rotation={0}`. */
+    portalHost?: boolean;
+    /** Let touches fall through the frame to whatever is beneath it, so only its children claim them. For a frame
+     * laid OVER other content (a dialog layer, a root-level overlay); a screen that owns the window leaves it off. */
+    passThrough?: boolean;
+    /** Cap on the content column's width in the WIDE layout only (the rotated footprint is landscape), centred: a
+     * stats list or a roster stretched across an 874pt-wide landscape screen reads badly. Portrait is never capped,
+     * so a portrait iPad or desktop window keeps its full width. Omit for no cap. */
+    maxContentWidth?: number;
+}
+/** A frame turned to follow the phone while the OS stays portrait-locked (see @tastic/core's FakeLandscapeView),
+ * sized to the turned footprint so its content lays out against the short edge at +/-90. The tree is IDENTICAL
+ * at every angle, so a rotation never remounts what is inside: `FakeLandscapeView > SafeArea provider >
+ * [Portal.Host] > column`. `rotation`, `rotatedSafeArea`, `passThrough` and `maxContentWidth` only change styles
+ * and values, but `portalHost` adds or removes the Portal.Host element, so it must be STATIC per call site
+ * (flipping it at runtime would remount everything inside).
+ *
+ * Safe for tap-driven content only: react-native-gesture-handler's translation deltas are untransformed, so
+ * never put a gesture-tracked game board inside it. */
+declare function RotatedFrame({ children, rotation: rotationOverride, rotatedSafeArea, portalHost, passThrough, maxContentWidth }: RotatedFrameProps): react.JSX.Element;
+
 interface Props$2 {
     onBack: () => void;
     onSettings: () => void;
@@ -474,4 +508,4 @@ declare function useQuitConfirmation(hasProgress: () => boolean, onConfirmedBack
 
 declare function useZoneClampedAlign(open: boolean, contentWidth: number, contentHeight: number, rotation?: PopoverRotation): ReturnType<typeof useAutoAlign>;
 
-export { AchievementCatalogSection, AchievementRow, AchievementUnlockList, type AchievementUnlockOwner, ActivityStatSection, type AlignResult, BaseSettingsDialog, type BaseSettingsDialogProps, BaseStatsScreen, ConfirmDialog, type ConfirmDialogProps, ContentGutter, ControlSchemePicker, type ControlSchemePickerProps, CornerActionButtons, type CornerStatusBadgeSeat, CornerStatusBadges, type CornerStatusBadgesProps, InlineColorPicker, LABELED_DROPDOWN_POPOVER_WIDTH, LOCKED_BADGE_COLOR, LabeledDropdown, type LabeledDropdownOption, MONO_FONT, type MenuOption, type MenuSection, type MultiSelectSection, type OrientationMode, type OverlayCardColors, PlayerSetupPanel, type PlayerSetupPanelProps, type PopoverAlign, PopoverBody, type PopoverHost, type PopoverRotation, type PopoverVerticalAlign, PressAwayOverlay, type QuitConfirmation, ReadyButton, SectionedDropdown, SharedActionBand, type SingleSelectSection, StaggeredWord, type StaggeredWordProps, StatRow, StatSection, TriggerGaugeHost, type TriggerGaugeProps, type UnlockedAchievement, UpdateDialog, type UpdateDialogProps, getColorPopoverId, getCpuDifficultyPopoverId, getInlineColorPickerContentSize, getLabeledDropdownContentHeight, getOverlayCardColors, getStaggeredWordDuration, loadSkiaWeb, overlayActionStyles, overlayStyles, useAutoAlign, usePopoverHost, useQuitConfirmation, useZoneClampedAlign };
+export { AchievementCatalogSection, AchievementRow, AchievementUnlockList, type AchievementUnlockOwner, ActivityStatSection, type AlignResult, BaseSettingsDialog, type BaseSettingsDialogProps, BaseStatsScreen, ConfirmDialog, type ConfirmDialogProps, ContentGutter, ControlSchemePicker, type ControlSchemePickerProps, CornerActionButtons, type CornerStatusBadgeSeat, CornerStatusBadges, type CornerStatusBadgesProps, InlineColorPicker, LABELED_DROPDOWN_POPOVER_WIDTH, LOCKED_BADGE_COLOR, LabeledDropdown, type LabeledDropdownOption, MONO_FONT, type MenuOption, type MenuSection, type MultiSelectSection, type OrientationMode, type OverlayCardColors, PlayerSetupPanel, type PlayerSetupPanelProps, type PopoverAlign, PopoverBody, type PopoverHost, type PopoverRotation, type PopoverVerticalAlign, PressAwayOverlay, type QuitConfirmation, ReadyButton, RotatedFrame, type RotatedFrameProps, SectionedDropdown, SharedActionBand, type SingleSelectSection, StaggeredWord, type StaggeredWordProps, StatRow, StatSection, TriggerGaugeHost, type TriggerGaugeProps, type UnlockedAchievement, UpdateDialog, type UpdateDialogProps, getColorPopoverId, getCpuDifficultyPopoverId, getInlineColorPickerContentSize, getLabeledDropdownContentHeight, getOverlayCardColors, getStaggeredWordDuration, loadSkiaWeb, overlayActionStyles, overlayStyles, useAutoAlign, usePopoverHost, useQuitConfirmation, useZoneClampedAlign };

package/dist/index.d.ts

@@ -398,6 +398,40 @@ interface Props$3 {
 }
 declare function ReadyButton({ color, ready, onToggleReady, style, labelFontFamily }: Props$3): react.JSX.Element;
 
+interface RotatedFrameProps {
+    children: ReactNode;
+    /** The angle to turn the frame by. Defaults to the live physical hold (@tastic/core's useRotation); pass it
+     * when the caller already has the exact angle it wants, e.g. a dialog handed its caller's rotation, or 0 for
+     * one that already sits inside a turned frame. */
+    rotation?: ViewRotation;
+    /** Give everything inside the frame the safe-area insets already remapped onto the frame's own edges (see
+     * @tastic/core's rotateInsets), so a component that reads `useSafeAreaInsets()` itself (a library screen,
+     * Paper's Modal, a toaster) lands on the right edge when the frame is turned. Leave it off for content that
+     * rotates the insets itself, which would otherwise rotate them twice. */
+    rotatedSafeArea?: boolean;
+    /** Mount a Paper Portal.Host INSIDE the frame, so a dialog (Paper's Portal otherwise mounts at the app root,
+     * outside the frame) is laid out against the frame's footprint and turned with it. The dialog must then be
+     * told `rotation={0}`. */
+    portalHost?: boolean;
+    /** Let touches fall through the frame to whatever is beneath it, so only its children claim them. For a frame
+     * laid OVER other content (a dialog layer, a root-level overlay); a screen that owns the window leaves it off. */
+    passThrough?: boolean;
+    /** Cap on the content column's width in the WIDE layout only (the rotated footprint is landscape), centred: a
+     * stats list or a roster stretched across an 874pt-wide landscape screen reads badly. Portrait is never capped,
+     * so a portrait iPad or desktop window keeps its full width. Omit for no cap. */
+    maxContentWidth?: number;
+}
+/** A frame turned to follow the phone while the OS stays portrait-locked (see @tastic/core's FakeLandscapeView),
+ * sized to the turned footprint so its content lays out against the short edge at +/-90. The tree is IDENTICAL
+ * at every angle, so a rotation never remounts what is inside: `FakeLandscapeView > SafeArea provider >
+ * [Portal.Host] > column`. `rotation`, `rotatedSafeArea`, `passThrough` and `maxContentWidth` only change styles
+ * and values, but `portalHost` adds or removes the Portal.Host element, so it must be STATIC per call site
+ * (flipping it at runtime would remount everything inside).
+ *
+ * Safe for tap-driven content only: react-native-gesture-handler's translation deltas are untransformed, so
+ * never put a gesture-tracked game board inside it. */
+declare function RotatedFrame({ children, rotation: rotationOverride, rotatedSafeArea, portalHost, passThrough, maxContentWidth }: RotatedFrameProps): react.JSX.Element;
+
 interface Props$2 {
     onBack: () => void;
     onSettings: () => void;
@@ -474,4 +508,4 @@ declare function useQuitConfirmation(hasProgress: () => boolean, onConfirmedBack
 
 declare function useZoneClampedAlign(open: boolean, contentWidth: number, contentHeight: number, rotation?: PopoverRotation): ReturnType<typeof useAutoAlign>;
 
-export { AchievementCatalogSection, AchievementRow, AchievementUnlockList, type AchievementUnlockOwner, ActivityStatSection, type AlignResult, BaseSettingsDialog, type BaseSettingsDialogProps, BaseStatsScreen, ConfirmDialog, type ConfirmDialogProps, ContentGutter, ControlSchemePicker, type ControlSchemePickerProps, CornerActionButtons, type CornerStatusBadgeSeat, CornerStatusBadges, type CornerStatusBadgesProps, InlineColorPicker, LABELED_DROPDOWN_POPOVER_WIDTH, LOCKED_BADGE_COLOR, LabeledDropdown, type LabeledDropdownOption, MONO_FONT, type MenuOption, type MenuSection, type MultiSelectSection, type OrientationMode, type OverlayCardColors, PlayerSetupPanel, type PlayerSetupPanelProps, type PopoverAlign, PopoverBody, type PopoverHost, type PopoverRotation, type PopoverVerticalAlign, PressAwayOverlay, type QuitConfirmation, ReadyButton, SectionedDropdown, SharedActionBand, type SingleSelectSection, StaggeredWord, type StaggeredWordProps, StatRow, StatSection, TriggerGaugeHost, type TriggerGaugeProps, type UnlockedAchievement, UpdateDialog, type UpdateDialogProps, getColorPopoverId, getCpuDifficultyPopoverId, getInlineColorPickerContentSize, getLabeledDropdownContentHeight, getOverlayCardColors, getStaggeredWordDuration, loadSkiaWeb, overlayActionStyles, overlayStyles, useAutoAlign, usePopoverHost, useQuitConfirmation, useZoneClampedAlign };
+export { AchievementCatalogSection, AchievementRow, AchievementUnlockList, type AchievementUnlockOwner, ActivityStatSection, type AlignResult, BaseSettingsDialog, type BaseSettingsDialogProps, BaseStatsScreen, ConfirmDialog, type ConfirmDialogProps, ContentGutter, ControlSchemePicker, type ControlSchemePickerProps, CornerActionButtons, type CornerStatusBadgeSeat, CornerStatusBadges, type CornerStatusBadgesProps, InlineColorPicker, LABELED_DROPDOWN_POPOVER_WIDTH, LOCKED_BADGE_COLOR, LabeledDropdown, type LabeledDropdownOption, MONO_FONT, type MenuOption, type MenuSection, type MultiSelectSection, type OrientationMode, type OverlayCardColors, PlayerSetupPanel, type PlayerSetupPanelProps, type PopoverAlign, PopoverBody, type PopoverHost, type PopoverRotation, type PopoverVerticalAlign, PressAwayOverlay, type QuitConfirmation, ReadyButton, RotatedFrame, type RotatedFrameProps, SectionedDropdown, SharedActionBand, type SingleSelectSection, StaggeredWord, type StaggeredWordProps, StatRow, StatSection, TriggerGaugeHost, type TriggerGaugeProps, type UnlockedAchievement, UpdateDialog, type UpdateDialogProps, getColorPopoverId, getCpuDifficultyPopoverId, getInlineColorPickerContentSize, getLabeledDropdownContentHeight, getOverlayCardColors, getStaggeredWordDuration, loadSkiaWeb, overlayActionStyles, overlayStyles, useAutoAlign, usePopoverHost, useQuitConfirmation, useZoneClampedAlign };