Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

iOS shell: edge-to-edge settings, stable geometry, touch Cover Flow, state help

v0lumehi033e5f0ebff5
diff --git a/frontend-ios/Sources/ShellDemo/Resources/Localizable.xcstrings b/frontend-ios/Sources/ShellDemo/Resources/Localizable.xcstrings
index 9a9cd316..f9b5e527 100644
--- a/frontend-ios/Sources/ShellDemo/Resources/Localizable.xcstrings
+++ b/frontend-ios/Sources/ShellDemo/Resources/Localizable.xcstrings
@@ -151,6 +151,16 @@
}
}
},
+ "Game files damaged": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "Game files damaged"
+ }
+ }
+ }
+ },
"Handheld": {
"localizations": {
"en": {
@@ -311,32 +321,32 @@
}
}
},
- "The game's display and performance profile.": {
+ "Some of this game's bundled files could not be verified.": {
"localizations": {
"en": {
"stringUnit": {
"state": "translated",
- "value": "The game's display and performance profile."
+ "value": "Some of this game's bundled files could not be verified."
}
}
}
},
- "This app's folder": {
+ "The game's display and performance profile.": {
"localizations": {
"en": {
"stringUnit": {
"state": "translated",
- "value": "This app's folder"
+ "value": "The game's display and performance profile."
}
}
}
},
- "This game's bundled files could not be verified. Rebuild the app to restore them.": {
+ "This app's folder": {
"localizations": {
"en": {
"stringUnit": {
"state": "translated",
- "value": "This game's bundled files could not be verified. Rebuild the app to restore them."
+ "value": "This app's folder"
}
}
}
diff --git a/frontend-ios/Sources/ShellDemo/SampleData.swift b/frontend-ios/Sources/ShellDemo/SampleData.swift
index d220b66c..eb46c868 100644
--- a/frontend-ios/Sources/ShellDemo/SampleData.swift
+++ b/frontend-ios/Sources/ShellDemo/SampleData.swift
@@ -22,7 +22,7 @@ func demoText(_ key: String.LocalizationValue) -> String {
SampleArt.tile("moon", title: "Moonlit Express", version: "3.1.0", real: RealTitle("Super Smash Bros. Ultimate", "01006A800016E000", "super-smash-bros-ultimate.jpg"),
state: .needsAppUpdate),
SampleArt.tile("wild", title: "Wild Gardens", version: "1.2.0", real: RealTitle("Batman: Arkham Knight", "0100ACD0163D0000", "batman-arkham-knight.jpg"),
- state: .broken(reason: demoText("This game's bundled files could not be verified. Rebuild the app to restore them."))),
+ state: .broken(reason: demoText("Game files damaged"), detail: demoText("Some of this game's bundled files could not be verified."))),
SampleArt.tile("drift", title: "Drift Atlas", version: "1.1.0", real: RealTitle("Celeste", "01002B30028F6000", "celeste.jpg")),
// Always fictional: the icon-only fallback, a square icon inside a wide card.
SampleArt.tile("amber", title: "Amber Hours", version: "1.0.2", real: nil)
diff --git a/frontend-ios/Sources/ShellUI/ControllersView.swift b/frontend-ios/Sources/ShellUI/ControllersView.swift
index 99ede869..ed04b44f 100644
--- a/frontend-ios/Sources/ShellUI/ControllersView.swift
+++ b/frontend-ios/Sources/ShellUI/ControllersView.swift
@@ -9,6 +9,8 @@ public struct ControllersView: View {
self.onBack = onBack
}
public var body: some View {
+ // Scrolls under the home indicator to the bottom edge, with room for the last row to clear it.
+ GeometryReader { geometry in
ScrollView {
VStack(alignment: .leading, spacing: 30) {
HStack(alignment: .center) {
@@ -49,10 +51,12 @@ public struct ControllersView: View {
hint(ButtonGlyph(letter: "X"), ShellStrings.text("Game settings"))
hint(ButtonGlyph(letter: "Y"), ShellStrings.text("Controllers"))
}.padding(.horizontal, 4)
- }.padding(24).frame(maxWidth: 640)
+ }.padding(24).padding(.bottom, geometry.safeAreaInsets.bottom).frame(maxWidth: 640)
.frame(maxWidth: .infinity, alignment: .leading)
}
.scrollIndicators(.hidden)
+ .ignoresSafeArea(edges: .bottom)
+ }
.foregroundStyle(.white).preferredColorScheme(.dark)
}
private func hint(_ icon: some View, _ label: String) -> some View {
diff --git a/frontend-ios/Sources/ShellUI/CoverFlowView.swift b/frontend-ios/Sources/ShellUI/CoverFlowView.swift
index 7bd4898b..c3e56a2f 100644
--- a/frontend-ios/Sources/ShellUI/CoverFlowView.swift
+++ b/frontend-ios/Sources/ShellUI/CoverFlowView.swift
@@ -15,6 +15,8 @@ struct CoverFlowView: View {
/// How far the carousel is scrolled: 0 with the first cover in the middle.
@State private var scrolled: CGFloat = 0
@State private var userScrolling = false
+ /// False while the carousel scrolls, decelerates or snaps: a tap on the centre card then does nothing.
+ @State private var settled = true
@Environment(\.accessibilityReduceMotion) private var reduceMotion
@Environment(\.dynamicTypeSize) private var typeSize
@@ -23,7 +25,7 @@ struct CoverFlowView: View {
let short = geometry.size.height < 520
// A wide card as large as the Mac console's focused tile: what the height allows, never so wide that the
// neighbours vanish.
- let cardHeight = max(90, min(geometry.size.height * (short ? 0.5 : 0.42), geometry.size.width * 0.52 * 9 / 16))
+ let cardHeight = max(90, min(geometry.size.height * 0.42, geometry.size.width * 0.52 * 9 / 16))
let cover = cardHeight * 16 / 9
VStack(spacing: 0) {
topBar.padding(.horizontal, 24).padding(.top, short ? 4 : 16)
@@ -85,12 +87,22 @@ struct CoverFlowView: View {
scrolled = offset
}
.onScrollPhaseChange { _, phase in
+ // A touch scroll goes interacting, decelerating, sometimes animating (the snap), then idle. The flag holds
+ // until idle, so the snap that ends a swipe still counts as the player's. A scroll this view animates
+ // starts from idle and never sets it.
+ settled = phase == .idle
switch phase {
case .interacting, .decelerating: userScrolling = true
case .idle:
- if userScrolling, let id = centredID, id != selected.id { select(id) }
+ if userScrolling {
+ // The card in the middle once the scroll has settled, from the offset itself.
+ let index = min(games.count - 1, max(0, Int((scrolled / stride).rounded())))
+ let id = games[index].id
+ if centredID != id { centredID = id }
+ if id != selected.id { select(id) }
+ }
userScrolling = false
- default: userScrolling = false
+ default: break
}
}
.scrollIndicators(.hidden)
@@ -118,7 +130,12 @@ struct CoverFlowView: View {
private func coverButton(_ detail: GameDetail, cover: CGFloat) -> some View {
let chosen = detail.id == selected.id
return Button {
- if chosen { return }
+ // The centred card acts like the button under it, once the carousel has settled. A side card only comes
+ // to the middle and never starts anything.
+ if chosen {
+ if settled { primary(detail) }
+ return
+ }
withAnimation(reduceMotion ? nil : .smooth(duration: 0.32)) { centredID = detail.id }
select(detail.id)
} label: {
@@ -130,34 +147,31 @@ struct CoverFlowView: View {
.shellTarget("lib.tile.\(detail.id)", radius: cover * 0.03) { primary(detail) }
.accessibilityLabel(detail.game.title + ", " + detail.game.state.title)
.accessibilityAddTraits(chosen ? .isSelected : [])
+ .accessibilityHint(chosen ? detail.game.state.actionTitle : ShellStrings.text("Double-tap to select"))
.accessibilityIdentifier("tile.\(detail.id)")
}
- @ViewBuilder private func info(short: Bool, width: CGFloat) -> some View {
+ /// Under the centre card, the same on a phone and a tablet: the title centred with room for two lines, one status or
+ /// reason line, then the buttons at a fixed place. The space is reserved, so nothing moves when the selection
+ /// changes, only the words crossfade.
+ private func info(short: Bool, width: CGFloat) -> some View {
let game = selected.game
- if short {
- // A phone on its side: one line of title and state beside the buttons, so the cover keeps the height.
- HStack(spacing: 28) {
- VStack(alignment: .leading, spacing: 5) {
- title(game, size: 20).lineLimit(2).minimumScaleFactor(0.85)
- StatusLabel(state: game.state)
- }.frame(maxWidth: min(340, width * 0.4), alignment: .leading).fixedSize(horizontal: true, vertical: true)
- actions(game)
- }
- .frame(maxWidth: .infinity)
- .dynamicTypeSize(...DynamicTypeSize.xxLarge)
- } else {
- VStack(spacing: 12) {
- title(game, size: 30).lineLimit(2).multilineTextAlignment(.center)
- StatusLabel(state: game.state, prominent: true)
- if !game.state.explanation.isEmpty {
- Text(game.state.explanation).shellText(14).foregroundStyle(.white.opacity(0.68))
- .multilineTextAlignment(.center).frame(maxWidth: 440).fixedSize(horizontal: false, vertical: true)
+ let size: CGFloat = short ? 20 : 28
+ return VStack(spacing: short ? 10 : 14) {
+ ZStack(alignment: .top) {
+ VStack(spacing: 6) {
+ Text("M\nM").shellText(size, .heavy, relativeTo: .title)
+ StatusLabel(state: .playable, prominent: true)
+ }.hidden().accessibilityHidden(true)
+ VStack(spacing: 6) {
+ title(game, size: size).lineLimit(2).truncationMode(.tail).multilineTextAlignment(.center)
+ StatusLabel(state: game.state, prominent: true)
}
- actions(game).padding(.top, 6)
}
- .dynamicTypeSize(...DynamicTypeSize.accessibility1)
+ .frame(maxWidth: min(560, width - 48))
+ actions(game)
}
+ .dynamicTypeSize(...(short ? DynamicTypeSize.xxLarge : DynamicTypeSize.accessibility1))
}
private func title(_ game: GameTile, size: CGFloat) -> some View {
@@ -170,7 +184,10 @@ struct CoverFlowView: View {
private func actions(_ game: GameTile) -> some View {
HStack(spacing: 12) {
- Button { primary(selected) } label: { Label(game.state.actionTitle, systemImage: game.state.actionSymbol) }
+ // A fixed width that holds every state's label, so the row does not shift between games.
+ Button { primary(selected) } label: {
+ Label(game.state.actionTitle, systemImage: game.state.actionSymbol).frame(minWidth: 190)
+ }
.buttonStyle(PrimaryPillStyle())
.accessibilityLabel(game.state.actionTitle + ", " + game.title)
.accessibilityIdentifier("state.action")
diff --git a/frontend-ios/Sources/ShellUI/GameDetailView.swift b/frontend-ios/Sources/ShellUI/GameDetailView.swift
index 1d7e50bc..b719fb12 100644
--- a/frontend-ios/Sources/ShellUI/GameDetailView.swift
+++ b/frontend-ios/Sources/ShellUI/GameDetailView.swift
@@ -31,11 +31,11 @@ public struct GameDetailView: View {
title: detail.dataSource.isEmpty ? ShellStrings.text("No data selected") : detail.dataSource,
note: detail.dataNote) {
Button(ShellStrings.text("Choose…")) { actions.onPickGameData(detail.id) }
- .buttonStyle(ShellButtonStyle()).accessibilityLabel(ShellStrings.text("Choose game data…"))
+ .buttonStyle(ShellButtonStyle(fills: true)).accessibilityLabel(ShellStrings.text("Choose game data…"))
.shellTarget("set.data") { actions.onPickGameData(detail.id) }
if !detail.dataSource.isEmpty {
Button(ShellStrings.text("Use app data")) { actions.onUseAppData(detail.id) }
- .buttonStyle(ShellButtonStyle()).shellTarget("set.appdata") { actions.onUseAppData(detail.id) }
+ .buttonStyle(ShellButtonStyle(fills: true)).shellTarget("set.appdata") { actions.onUseAppData(detail.id) }
}
}
divider
@@ -47,17 +47,17 @@ public struct GameDetailView: View {
title: detail.cloudSaves ?? ShellStrings.text("Off"),
note: detail.cloudNote.isEmpty ? ShellStrings.text("Choose the same iCloud Drive folder you use on your Mac.") : detail.cloudNote) {
Button(ShellStrings.text("Choose folder…")) { actions.onPickCloudSaves(detail.id) }
- .buttonStyle(ShellButtonStyle()).shellTarget("set.cloud") { actions.onPickCloudSaves(detail.id) }
+ .buttonStyle(ShellButtonStyle(fills: true)).shellTarget("set.cloud") { actions.onPickCloudSaves(detail.id) }
if detail.cloudSaves != nil {
Button(ShellStrings.text("Turn off")) { actions.onDisableCloudSaves(detail.id) }
- .buttonStyle(ShellButtonStyle()).accessibilityLabel(ShellStrings.text("Turn off cloud saves"))
+ .buttonStyle(ShellButtonStyle(fills: true)).accessibilityLabel(ShellStrings.text("Turn off cloud saves"))
.shellTarget("set.cloud.off") { actions.onDisableCloudSaves(detail.id) }
}
}
}
VStack(alignment: .leading, spacing: 10) {
Button(ShellStrings.text("Reset to tested defaults")) { actions.onResetDefaults(detail.id) }
- .buttonStyle(ShellButtonStyle())
+ .buttonStyle(ShellButtonStyle(fills: true))
.disabled(!detail.hasModifiedSettings)
.shellTarget("set.reset", enabled: detail.hasModifiedSettings) { actions.onResetDefaults(detail.id) }
Text(ShellStrings.text("Brings back the settings this game was tested with."))
@@ -128,10 +128,11 @@ private struct SourceRow<Buttons: View>: View {
}
}
}
+ // The buttons share the card's width in equal parts, or stack full width when their labels do not fit.
ViewThatFits(in: .horizontal) {
- HStack(spacing: 10) { buttons() }
- VStack(alignment: .leading, spacing: 10) { buttons() }
- }.padding(.leading, 32)
+ EqualRow(spacing: 10) { buttons() }
+ VStack(spacing: 10) { buttons() }
+ }
}
}
}
@@ -149,13 +150,15 @@ private struct SettingControl: View {
.shellTarget("set.row.\(row.id)", enabled: row.enabled) { change(row.value == on ? off : on) }
case .choice(let options):
label
- if options.count <= 3 && !typeSize.isAccessibilitySize {
+ // Equal segments across the card. When the labels do not fit one row: two rows of equal cells, then a list.
+ if typeSize.isAccessibilitySize {
+ list(options)
+ } else {
ViewThatFits(in: .horizontal) {
- segmented(options)
+ segmented([options])
+ segmented(stride(from: 0, to: options.count, by: 2).map { Array(options[$0..<min($0 + 2, options.count)]) })
list(options)
}
- } else {
- list(options)
}
case .range(let min, let max, let step, let unit):
HStack(alignment: .firstTextBaseline) {
@@ -183,22 +186,26 @@ private struct SettingControl: View {
if !row.note.isEmpty { Text(row.note).shellText(12.5).foregroundStyle(.white.opacity(0.5)).fixedSize(horizontal: false, vertical: true) }
}
}
- /// The Mac's segmented choice: a dim track, the chosen value in cream.
- private func segmented(_ options: [SettingOption]) -> some View {
- HStack(spacing: 2) {
- ForEach(options) { option in
- let chosen = row.value == option.id
- Button { change(option.id) } label: {
- Text(option.label).shellText(13.5, chosen ? .bold : .medium).lineLimit(1)
- .padding(.horizontal, 16).frame(minHeight: 40)
- .foregroundStyle(chosen ? .black : .white.opacity(0.75))
- .background(chosen ? ShellPalette.cream : .clear, in: RoundedRectangle(cornerRadius: 8))
- .contentShape(RoundedRectangle(cornerRadius: 8))
+ /// The Mac's segmented choice, across the whole card: a dim track, equal segments, the chosen value in cream.
+ private func segmented(_ rows: [[SettingOption]]) -> some View {
+ VStack(spacing: 2) {
+ ForEach(Array(rows.enumerated()), id: \.offset) { _, options in
+ EqualRow(spacing: 2) {
+ ForEach(options) { option in
+ let chosen = row.value == option.id
+ Button { change(option.id) } label: {
+ Text(option.label).shellText(13.5, chosen ? .bold : .medium).lineLimit(1)
+ .padding(.horizontal, 14).frame(maxWidth: .infinity, minHeight: 40)
+ .foregroundStyle(chosen ? .black : .white.opacity(0.75))
+ .background(chosen ? ShellPalette.cream : .clear, in: RoundedRectangle(cornerRadius: 8))
+ .contentShape(RoundedRectangle(cornerRadius: 8))
+ }
+ .buttonStyle(.plain)
+ .accessibilityLabel(row.label + ", " + option.label)
+ .accessibilityAddTraits(chosen ? .isSelected : [])
+ .shellTarget("set.row.\(row.id).\(option.id)", enabled: row.enabled, radius: 8) { change(option.id) }
+ }
}
- .buttonStyle(.plain).fixedSize()
- .accessibilityLabel(row.label + ", " + option.label)
- .accessibilityAddTraits(chosen ? .isSelected : [])
- .shellTarget("set.row.\(row.id).\(option.id)", enabled: row.enabled, radius: 8) { change(option.id) }
}
}
.padding(3)
@@ -238,3 +245,26 @@ private struct SettingControl: View {
.shellTarget("set.row.\(row.id).\(symbol)", enabled: row.enabled, radius: 22, action: action)
}
}
+
+/// Children side by side in equal widths that fill the row. Its ideal width is the widest child times the count, so
+/// a `ViewThatFits` can fall back when the labels would not fit at equal widths.
+struct EqualRow: Layout {
+ var spacing: CGFloat
+ func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
+ let sizes = subviews.map { $0.sizeThatFits(.unspecified) }
+ let gaps = spacing * CGFloat(max(0, subviews.count - 1))
+ let natural = (sizes.map(\.width).max() ?? 0) * CGFloat(subviews.count) + gaps
+ let width = proposal.width.map { $0.isFinite ? $0 : natural } ?? natural
+ let cell = subviews.isEmpty ? 0 : (width - gaps) / CGFloat(subviews.count)
+ let height = subviews.map { $0.sizeThatFits(ProposedViewSize(width: cell, height: nil)).height }.max() ?? 0
+ return CGSize(width: width, height: height)
+ }
+ func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
+ guard !subviews.isEmpty else { return }
+ let cell = (bounds.width - spacing * CGFloat(subviews.count - 1)) / CGFloat(subviews.count)
+ for (index, subview) in subviews.enumerated() {
+ subview.place(at: CGPoint(x: bounds.minX + CGFloat(index) * (cell + spacing), y: bounds.minY),
+ proposal: ProposedViewSize(width: cell, height: bounds.height))
+ }
+ }
+}
diff --git a/frontend-ios/Sources/ShellUI/GameStateView.swift b/frontend-ios/Sources/ShellUI/GameStateView.swift
index 1404904a..a964be35 100644
--- a/frontend-ios/Sources/ShellUI/GameStateView.swift
+++ b/frontend-ios/Sources/ShellUI/GameStateView.swift
@@ -5,6 +5,8 @@ public struct GameStateView: View {
public let game: GameTile
public var actions: ShellActions
public var showsExplanation: Bool
+ @Environment(\.shellShowHelp) private var showHelp
+ @State private var localHelp = false
public init(game: GameTile, actions: ShellActions = ShellActions(), showsExplanation: Bool = true) {
self.game = game
self.actions = actions
@@ -25,8 +27,17 @@ public struct GameStateView: View {
.accessibilityLabel(game.state.actionTitle + ", " + game.title)
.shellTarget("set.play", radius: 25, action: perform)
}
+ .sheet(isPresented: $localHelp) {
+ StateHelpView(game: game, actions: actions) { localHelp = false }
+ .presentationDetents([.medium])
+ .presentationBackground(ShellPalette.background)
+ }
}
private func perform() {
+ if game.state.needsHelp {
+ if let showHelp { showHelp(game) } else { localHelp = true }
+ return
+ }
switch game.state {
case .playable: actions.onPlay(game.id)
case .needsGameData: actions.onPickGameData(game.id)
@@ -36,6 +47,61 @@ public struct GameStateView: View {
}
}
+/// How to fix a broken game or update the app: both happen on the Mac, so this says so in two sentences and offers
+/// what can be done here. The log stays available for a bug report.
+public struct StateHelpView: View {
+ public let game: GameTile
+ public var actions: ShellActions
+ public var onClose: () -> Void
+ public init(game: GameTile, actions: ShellActions = ShellActions(), onClose: @escaping () -> Void = {}) {
+ self.game = game
+ self.actions = actions
+ self.onClose = onClose
+ }
+ public var body: some View {
+ VStack(alignment: .leading, spacing: 16) {
+ StatusLabel(state: game.state, prominent: true)
+ Text(game.state.actionTitle).shellText(26, .heavy, relativeTo: .title).tracking(-0.7)
+ .accessibilityAddTraits(.isHeader).accessibilityIdentifier("help.title")
+ Text(message).shellText(15).foregroundStyle(.white.opacity(0.78)).fixedSize(horizontal: false, vertical: true)
+ if case .broken(_, let detail) = game.state, !detail.isEmpty {
+ Text(detail).shellText(13).foregroundStyle(.white.opacity(0.5)).fixedSize(horizontal: false, vertical: true)
+ }
+ VStack(spacing: 10) {
+ Button(action: onClose) { Text(ShellStrings.text("Done")).frame(maxWidth: .infinity) }
+ .buttonStyle(PrimaryPillStyle(expands: true))
+ .accessibilityIdentifier("help.done")
+ .shellTarget("help.done", radius: 25, action: onClose)
+ switch game.state {
+ case .broken:
+ Button(ShellStrings.text("Show log")) { actions.onShowLog(game.id) }
+ .buttonStyle(ShellButtonStyle(fills: true))
+ .accessibilityHint(ShellStrings.text("For a bug report"))
+ .accessibilityIdentifier("help.log")
+ .shellTarget("help.log") { actions.onShowLog(game.id) }
+ case .needsAppUpdate:
+ Button(ShellStrings.text("Update app")) { actions.onAppUpdate() }
+ .buttonStyle(ShellButtonStyle(fills: true))
+ .accessibilityIdentifier("help.update")
+ .shellTarget("help.update") { actions.onAppUpdate() }
+ default:
+ EmptyView()
+ }
+ }.padding(.top, 8)
+ }
+ .padding(28)
+ .frame(maxWidth: .infinity, alignment: .leading)
+ .foregroundStyle(.white)
+ }
+ private var message: String {
+ switch game.state {
+ case .broken: ShellStrings.text("Build this game again on your Mac and install it on this device. The Mac app checks every file while it builds, so the new copy is complete.")
+ case .needsAppUpdate: ShellStrings.text("This game needs a newer version of this app. Update it with the Mac app on your Mac, then install it on this device again.")
+ default: ""
+ }
+ }
+}
+
/// No game in the app yet: an empty shelf, said plainly.
public struct EmptyLibraryView: View {
public init() {}
diff --git a/frontend-ios/Sources/ShellUI/LibraryView.swift b/frontend-ios/Sources/ShellUI/LibraryView.swift
index 6cb5beba..3567c71f 100644
--- a/frontend-ios/Sources/ShellUI/LibraryView.swift
+++ b/frontend-ios/Sources/ShellUI/LibraryView.swift
@@ -39,11 +39,14 @@ public struct LibraryView: View {
@State private var selectedID: String?
@State private var settingsOpen: Bool
@State private var controllersOpen: Bool
+ /// The game whose How to fix or How to update explanation is open.
+ @State private var helpGameID: String?
@State private var focus: FocusAppearance
@State private var targets = FocusTargetBuffer()
@State private var settingsPosition = ScrollPosition()
@State private var libraryPosition = ScrollPosition()
@State private var layout: ShellLayout = .column
+ @State private var returnFocus: String?
@Environment(\.accessibilityReduceMotion) private var reduceMotion
@Environment(\.dynamicTypeSize) private var typeSize
@@ -83,11 +86,11 @@ public struct LibraryView: View {
ControllerChip(count: controllers.count, action: openControllers).padding(.top, 6).padding(.trailing, 16)
}
} else if let selected {
- library(selected, layout: layout, size: geometry.size, topInset: insets.top)
+ library(selected, layout: layout, size: geometry.size, insets: insets)
.frame(width: width, height: geometry.size.height)
.opacity(paneCovers ? 0 : 1)
.allowsHitTesting(!settingsOpen)
- .accessibilityHidden(settingsOpen)
+ .accessibilityHidden(settingsOpen || helpGameID != nil)
.transformPreference(FocusTargets.self) { if settingsOpen { $0.removeAll() } }
if panelOverLibrary {
Color.black.opacity(0.5).ignoresSafeArea()
@@ -97,7 +100,8 @@ public struct LibraryView: View {
}
// One settings view in one place for every layout, so its state, scroll position and focus survive
// a fold, a rotation or a Stage Manager resize.
- settingsPane(selected, floating: floating, width: pane - (floating ? 24 : 0))
+ settingsPane(selected, floating: floating, width: pane - (floating ? 24 : 0),
+ insets: floating ? EdgeInsets() : insets)
.frame(width: pane - (floating ? 24 : 0))
.frame(maxHeight: .infinity)
.background {
@@ -108,7 +112,9 @@ public struct LibraryView: View {
ShellPalette.background.ignoresSafeArea()
}
}
- .clipShape(RoundedRectangle(cornerRadius: floating ? 26 : 0))
+ // Rounded as a panel. Full screen the clip reaches far past the edges, so the banner and the
+ // scrolling settings run under the status bar and the home indicator.
+ .clipShape(RoundedRectangle(cornerRadius: floating ? 26 : 0).inset(by: floating ? 0 : -400))
.shadow(color: .black.opacity(floating ? 0.5 : 0), radius: 40, x: -8)
.padding(floating ? 12 : 0)
.offset(x: settingsOpen ? 0 : pane + 40)
@@ -119,6 +125,20 @@ public struct LibraryView: View {
.accessibilityAddTraits(settingsOpen ? .isModal : [])
.transformPreference(FocusTargets.self) { if !settingsOpen { $0.removeAll() } }
}
+ if let id = helpGameID, let game = games.first(where: { $0.id == id })?.game {
+ Color.black.opacity(0.55).ignoresSafeArea().accessibilityHidden(true)
+ .onTapGesture { closeHelp() }
+ .transition(.opacity)
+ StateHelpView(game: game, actions: actions, onClose: closeHelp)
+ .frame(maxWidth: 460)
+ .background(Color(red: 0.075, green: 0.075, blue: 0.082), in: RoundedRectangle(cornerRadius: 26))
+ .overlay(RoundedRectangle(cornerRadius: 26).strokeBorder(.white.opacity(0.10)))
+ .shadow(color: .black.opacity(0.5), radius: 40)
+ .padding(16)
+ .frame(maxWidth: .infinity, maxHeight: .infinity)
+ .accessibilityAddTraits(.isModal)
+ .transition(.opacity.combined(with: .scale(scale: 0.96)))
+ }
if controllersOpen {
Color.black.opacity(0.55).ignoresSafeArea().accessibilityHidden(true)
.onTapGesture { back() }
@@ -133,7 +153,11 @@ public struct LibraryView: View {
}
}
.transformPreference(FocusTargets.self) { values in
- values = values.filter { controllersOpen ? $0.id.hasPrefix("ctl.") : !$0.id.hasPrefix("ctl.") }
+ values = values.filter { target in
+ if controllersOpen { return target.id.hasPrefix("ctl.") }
+ if helpGameID != nil { return target.id.hasPrefix("help.") }
+ return !target.id.hasPrefix("ctl.") && !target.id.hasPrefix("help.")
+ }
}
.coordinateSpace(name: "shell")
.onPreferenceChange(FocusTargets.self) { all in targets.values = all.filter { $0.frame.width > 1 } }
@@ -143,6 +167,8 @@ public struct LibraryView: View {
.animation(reduceMotion ? nil : .smooth(duration: 0.35), value: layout)
.animation(reduceMotion ? nil : .smooth(duration: 0.3), value: settingsOpen)
.animation(reduceMotion ? nil : .smooth(duration: 0.3), value: controllersOpen)
+ .animation(reduceMotion ? nil : .smooth(duration: 0.25), value: helpGameID)
+ .environment(\.shellShowHelp, { game in openHelp(game.id) })
.environment(\.shellFocus, focus)
.foregroundStyle(.white)
.font(ShellFonts.font(15)).tint(ShellPalette.cream).preferredColorScheme(.dark)
@@ -160,13 +186,13 @@ public struct LibraryView: View {
}
}
- @ViewBuilder private func library(_ selected: GameDetail, layout: ShellLayout, size: CGSize, topInset: CGFloat) -> some View {
+ @ViewBuilder private func library(_ selected: GameDetail, layout: ShellLayout, size: CGSize, insets: EdgeInsets) -> some View {
if layout.isCoverFlow {
CoverFlowView(games: games, selected: selected, controllers: controllers.count, showsHints: !controllers.isEmpty,
select: select, primary: primary, openSettings: openSettings, openControllers: openControllers)
.transition(.opacity)
} else {
- PortraitLibrary(games: games, selected: selected, wide: layout == .grid, size: size, topInset: topInset,
+ PortraitLibrary(games: games, selected: selected, wide: layout == .grid, size: size, topInset: insets.top, bottomInset: insets.bottom,
controllers: controllers.count, select: select, primary: primary,
openSettings: openSettings, openControllers: openControllers, position: $libraryPosition)
.transition(.opacity)
@@ -175,44 +201,49 @@ public struct LibraryView: View {
/// The settings for the selected game: its banner as the header, with the title over it and Back on top, then
/// the primary action and the setting groups. A panel or the whole screen, the same view.
- private func settingsPane(_ selected: GameDetail, floating: Bool, width: CGFloat) -> some View {
- ScrollViewReader { proxy in
- ScrollView {
- VStack(alignment: .leading, spacing: 0) {
- PaneBanner(game: selected.game, width: width).id("set.top")
- GameDetailView(detail: selected, actions: actions, showsPrimaryAction: true, showsHeader: false)
- .padding(.horizontal, 24).padding(.top, 18).padding(.bottom, 32)
- // A phone on its side: a readable column, not rows stretched across the whole width.
- .frame(maxWidth: 640, alignment: .leading)
+ /// The settings for the selected game: its banner as the header, with the title below it and Back on top, then
+ /// the primary action and the setting groups. A panel or the whole screen, the same view. Full screen, the banner
+ /// runs under the status bar and the settings scroll under the home indicator, while Back keeps its inset.
+ private func settingsPane(_ selected: GameDetail, floating: Bool, width: CGFloat, insets: EdgeInsets) -> some View {
+ ZStack(alignment: .topLeading) {
+ ScrollViewReader { proxy in
+ ScrollView {
+ VStack(alignment: .leading, spacing: 0) {
+ PaneBanner(game: selected.game, width: width, topInset: insets.top).id("set.top")
+ GameDetailView(detail: selected, actions: actions, showsPrimaryAction: true, showsHeader: false)
+ .padding(.horizontal, 24).padding(.top, 18).padding(.bottom, 32 + insets.bottom)
+ // A phone on its side: a readable column, not rows stretched across the whole width.
+ .frame(maxWidth: 640, alignment: .leading)
+ .padding(.leading, insets.leading).padding(.trailing, insets.trailing)
+ }
+ .frame(maxWidth: .infinity, alignment: .leading)
}
- .frame(maxWidth: .infinity, alignment: .leading)
- }
- .scrollPosition($settingsPosition)
- .scrollIndicators(.hidden)
- .ignoresSafeArea(edges: floating ? [] : .top)
- .overlay(alignment: .topLeading) {
- Button(action: closeSettings) {
- if typeSize.isAccessibilitySize { Image(systemName: "chevron.left").frame(minWidth: 24) }
- else { Label(ShellStrings.text("Library"), systemImage: "chevron.left") }
+ .scrollPosition($settingsPosition)
+ .scrollIndicators(.hidden)
+ .ignoresSafeArea(edges: floating ? [] : .all)
+ .onChange(of: focus.id) { _, id in
+ guard let id, id.hasPrefix("set.") else { return }
+ withAnimation(reduceMotion ? nil : .easeOut(duration: 0.18)) {
+ proxy.scrollTo(id == "set.back" ? "set.top" : id, anchor: id == "set.back" ? .top : .center)
+ }
}
- .buttonStyle(ChipButtonStyle())
- .accessibilityLabel(ShellStrings.text("Library"))
- .accessibilityIdentifier("library.back")
- .shellTarget("set.back", radius: 22, action: closeSettings)
- .padding(.leading, 16).padding(.top, floating ? 14 : 6)
}
- .onChange(of: focus.id) { _, id in
- guard let id, id.hasPrefix("set.") else { return }
- withAnimation(reduceMotion ? nil : .easeOut(duration: 0.18)) {
- proxy.scrollTo(id == "set.back" ? "set.top" : id, anchor: id == "set.back" ? .top : .center)
- }
+ Button(action: closeSettings) {
+ if typeSize.isAccessibilitySize { Image(systemName: "chevron.left").frame(minWidth: 24) }
+ else { Label(ShellStrings.text("Library"), systemImage: "chevron.left") }
}
+ .buttonStyle(ChipButtonStyle())
+ .accessibilityLabel(ShellStrings.text("Library"))
+ .accessibilityIdentifier("library.back")
+ .shellTarget("set.back", radius: 22, action: closeSettings)
+ .padding(.leading, 16).padding(.top, floating ? 14 : 6)
}
}
// MARK: Actions and focus
private func primary(_ detail: GameDetail) {
+ if detail.game.state.needsHelp { openHelp(detail.id); return }
switch detail.game.state {
case .playable: actions.onPlay(detail.id)
case .needsGameData: actions.onPickGameData(detail.id)
@@ -235,8 +266,11 @@ public struct LibraryView: View {
focus.id = "lib.settings"
}
private func openControllers() { controllersOpen = true; focus.id = "ctl.close" }
+ private func openHelp(_ id: String) { returnFocus = focus.id; helpGameID = id; focus.id = "help.done" }
+ private func closeHelp() { helpGameID = nil; focus.id = returnFocus }
private func back() {
- if controllersOpen { controllersOpen = false; focus.id = "lib.controllers" }
+ if helpGameID != nil { closeHelp() }
+ else if controllersOpen { controllersOpen = false; focus.id = "lib.controllers" }
else if settingsOpen { closeSettings() }
else { actions.onBack() }
}
@@ -271,6 +305,7 @@ public struct LibraryView: View {
if let id = focus.id, id.hasPrefix("lib.tile.") { select(String(id.dropFirst("lib.tile.".count))) }
}
private var defaultFocus: String? {
+ if helpGameID != nil { return "help.done" }
if controllersOpen { return "ctl.close" }
if settingsOpen { return "set.back" }
return selected.map { "lib.tile.\($0.id)" } ?? "lib.controllers"
@@ -282,13 +317,19 @@ public struct LibraryView: View {
private struct PaneBanner: View {
let game: GameTile
let width: CGFloat
+ /// The status bar's height where the banner runs under it.
+ var topInset: CGFloat = 0
var body: some View {
- let bannerHeight = min(width * 9 / 16, 220)
+ let bannerHeight = min(width * 9 / 16, 220) + topInset
VStack(alignment: .leading, spacing: 8) {
StatusLabel(state: game.state, prominent: true)
- Text(game.title).shellText(26, .heavy, relativeTo: .title).tracking(-0.7)
- .fixedSize(horizontal: false, vertical: true)
- .accessibilityAddTraits(.isHeader).accessibilityIdentifier("detail.title")
+ // Two lines are always reserved, so the settings below start at the same place for every game.
+ ZStack(alignment: .topLeading) {
+ Text("M\nM").shellText(26, .heavy, relativeTo: .title).hidden().accessibilityHidden(true)
+ Text(game.title).shellText(26, .heavy, relativeTo: .title).tracking(-0.7)
+ .lineLimit(2)
+ .accessibilityAddTraits(.isHeader).accessibilityIdentifier("detail.title")
+ }
HStack(spacing: 8) {
SectionHeading(title: ShellStrings.text("Game settings"))
if !game.subtitle.isEmpty {
@@ -302,6 +343,13 @@ private struct PaneBanner: View {
.background(alignment: .top) {
ArtView(game: game, lettering: false)
.frame(width: width, height: bannerHeight)
+ .overlay(alignment: .top) {
+ // Darker under the status bar, so the time and battery stay legible on any art.
+ if topInset > 0 {
+ LinearGradient(colors: [.black.opacity(0.5), .clear], startPoint: .top, endPoint: .bottom)
+ .frame(height: topInset + 50)
+ }
+ }
.mask {
LinearGradient(stops: [.init(color: .black, location: 0), .init(color: .black, location: 0.55),
.init(color: .clear, location: 1)], startPoint: .top, endPoint: .bottom)
diff --git a/frontend-ios/Sources/ShellUI/PortraitLibrary.swift b/frontend-ios/Sources/ShellUI/PortraitLibrary.swift
index de635bdf..1018bcf9 100644
--- a/frontend-ios/Sources/ShellUI/PortraitLibrary.swift
+++ b/frontend-ios/Sources/ShellUI/PortraitLibrary.swift
@@ -10,6 +10,8 @@ struct PortraitLibrary: View {
let wide: Bool
let size: CGSize
let topInset: CGFloat
+ /// The home indicator's height. Without a bottom bar the library scrolls under it to the bottom edge.
+ var bottomInset: CGFloat = 0
let controllers: Int
let select: (String) -> Void
let primary: (GameDetail) -> Void
@@ -40,7 +42,7 @@ struct PortraitLibrary: View {
ScrollView {
VStack(alignment: .leading, spacing: 0) {
HeroView(game: selected.game, width: size.width, topInset: topInset,
- titleSize: wide ? 34 : short ? 26 : 32) {
+ titleSize: wide ? 34 : short ? 24 : 32, short: short, fullHeight: size.height + topInset) {
if wide {
HStack(spacing: 12) {
Button { primary(selected) } label: {
@@ -56,11 +58,11 @@ struct PortraitLibrary: View {
}
collection.padding(.top, short ? 6 : 14)
recent.padding(.top, 34)
- }.padding(.bottom, 28)
+ }.padding(.bottom, 28 + (wide ? bottomInset : 0))
}
.scrollPosition($position)
.scrollIndicators(.hidden)
- .ignoresSafeArea(edges: .top)
+ .ignoresSafeArea(edges: wide ? [.top, .bottom] : .top)
.safeAreaInset(edge: .bottom, spacing: 0) { if !wide { bottomBar } }
.overlay(alignment: .topTrailing) {
ControllerChip(count: controllers, action: openControllers).padding(.top, 6).padding(.trailing, 16)
@@ -187,27 +189,32 @@ struct HeroView<Accessory: View>: View {
let width: CGFloat
let topInset: CGFloat
var titleSize: CGFloat = 34
+ /// A short screen (the folded foldable): a lower banner, cropped at the sides, and one line of hint.
+ var short = false
+ var fullHeight: CGFloat = .infinity
@ViewBuilder let accessory: () -> Accessory
@Environment(\.accessibilityReduceMotion) private var reduceMotion
var body: some View {
- let bannerHeight = width * 9 / 16
+ let bannerHeight = short ? min(width * 9 / 16, fullHeight * 0.28) : width * 9 / 16
VStack(alignment: .leading, spacing: 10) {
- StatusLabel(state: game.state, prominent: true)
- Text(game.title).shellText(titleSize, .heavy, relativeTo: .largeTitle).tracking(-titleSize * 0.03)
- .lineLimit(3).minimumScaleFactor(0.75).fixedSize(horizontal: false, vertical: true)
- .accessibilityAddTraits(.isHeader).accessibilityIdentifier("hero.title")
- if !meta.isEmpty {
- Text(meta).shellText(13).foregroundStyle(.white.opacity(0.62))
- }
- if !game.state.explanation.isEmpty {
- Text(game.state.explanation).shellText(14.5).foregroundStyle(.white.opacity(0.78))
- .fixedSize(horizontal: false, vertical: true).padding(.top, 2)
+ // A stable height for every game: the hidden template reserves the status, a two-line title, the meta line
+ // and a two-line hint, so the cards below never move when the selection changes. Only the text inside
+ // crossfades.
+ ZStack(alignment: .topLeading) {
+ HeroText(status: GameState.needsGameData, title: "M\nM", meta: "M",
+ explanation: short ? "M" : "M\nM", titleSize: titleSize, hintLines: short ? 1 : 2)
+ .hidden().accessibilityHidden(true)
+ HeroText(status: game.state, title: game.title, meta: meta, explanation: game.state.explanation, titleSize: titleSize,
+ hintLines: short ? 1 : 2)
+ .id(game.id).transition(.opacity)
}
+ .animation(reduceMotion ? .linear(duration: 0.12) : .easeInOut(duration: 0.25), value: game.id)
accessory()
}
.padding(.horizontal, 24)
- .padding(.top, max(topInset, bannerHeight - 26))
+ // The text starts where the banner has faded out, never over the art's own lettering.
+ .padding(.top, max(topInset, bannerHeight - 4))
.padding(.bottom, 18)
.frame(maxWidth: .infinity, alignment: .bottomLeading)
.background {
@@ -220,8 +227,8 @@ struct HeroView<Accessory: View>: View {
ArtView(game: game, lettering: false)
.frame(width: width, height: bannerHeight)
.mask {
- LinearGradient(stops: [.init(color: .black, location: 0), .init(color: .black, location: 0.72),
- .init(color: .clear, location: 1)], startPoint: .top, endPoint: .bottom)
+ LinearGradient(stops: [.init(color: .black, location: 0), .init(color: .black, location: 0.62),
+ .init(color: .clear, location: 0.98)], startPoint: .top, endPoint: .bottom)
}
LinearGradient(stops: [.init(color: .black.opacity(0.45), location: 0),
.init(color: .clear, location: min(0.3, (topInset + 40) / max(1, bannerHeight * 2)))],
@@ -241,3 +248,28 @@ struct HeroView<Accessory: View>: View {
[game.subtitle, game.recentlyPlayed ?? ""].filter { !$0.isEmpty }.joined(separator: " · ")
}
}
+
+/// The hero's words: the state, the title on at most two lines (the full name is in settings), the meta line and a
+/// hint of at most two lines.
+struct HeroText: View {
+ let status: GameState
+ let title: String
+ let meta: String
+ let explanation: String
+ let titleSize: CGFloat
+ var hintLines = 2
+ var body: some View {
+ VStack(alignment: .leading, spacing: 10) {
+ StatusLabel(state: status, prominent: true)
+ Text(title).shellText(titleSize, .heavy, relativeTo: .largeTitle).tracking(-titleSize * 0.03)
+ .lineLimit(2).truncationMode(.tail)
+ .accessibilityAddTraits(.isHeader).accessibilityIdentifier("hero.title")
+ if !meta.isEmpty {
+ Text(meta).shellText(13).foregroundStyle(.white.opacity(0.62)).lineLimit(1)
+ }
+ if !explanation.isEmpty {
+ Text(explanation).shellText(14.5).foregroundStyle(.white.opacity(0.78)).lineLimit(hintLines).padding(.top, 2)
+ }
+ }
+ }
+}
diff --git a/frontend-ios/Sources/ShellUI/Resources/Localizable.xcstrings b/frontend-ios/Sources/ShellUI/Resources/Localizable.xcstrings
index c43688a7..10a68532 100644
--- a/frontend-ios/Sources/ShellUI/Resources/Localizable.xcstrings
+++ b/frontend-ios/Sources/ShellUI/Resources/Localizable.xcstrings
@@ -51,6 +51,16 @@
}
}
},
+ "Build this game again on your Mac and install it on this device. The Mac app checks every file while it builds, so the new copy is complete.": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "Build this game again on your Mac and install it on this device. The Mac app checks every file while it builds, so the new copy is complete."
+ }
+ }
+ }
+ },
"Charging": {
"localizations": {
"en": {
@@ -161,6 +171,26 @@
}
}
},
+ "Done": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "Done"
+ }
+ }
+ }
+ },
+ "For a bug report": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "For a bug report"
+ }
+ }
+ }
+ },
"Game data": {
"localizations": {
"en": {
@@ -181,6 +211,26 @@
}
}
},
+ "How to fix": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "How to fix"
+ }
+ }
+ }
+ },
+ "How to update": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "How to update"
+ }
+ }
+ }
+ },
"Increase": {
"localizations": {
"en": {
@@ -361,6 +411,16 @@
}
}
},
+ "This game needs a newer version of this app. Update it with the Mac app on your Mac, then install it on this device again.": {
+ "localizations": {
+ "en": {
+ "stringUnit": {
+ "state": "translated",
+ "value": "This game needs a newer version of this app. Update it with the Mac app on your Mac, then install it on this device again."
+ }
+ }
+ }
+ },
"Turn off": {
"localizations": {
"en": {
diff --git a/frontend-ios/Sources/ShellUI/ShellInputs.swift b/frontend-ios/Sources/ShellUI/ShellInputs.swift
index da73fb20..c68b9d2d 100644
--- a/frontend-ios/Sources/ShellUI/ShellInputs.swift
+++ b/frontend-ios/Sources/ShellUI/ShellInputs.swift
@@ -5,7 +5,9 @@ public enum GameState: Equatable, Sendable {
case playable
case needsGameData
case needsAppUpdate
- case broken(reason: String)
+ /// `reason` is one short line for under the title, such as "Game files damaged". `detail` may add a sentence
+ /// for the How to fix sheet.
+ case broken(reason: String, detail: String = "")
}
public struct GameTile: Identifiable, Equatable, Sendable {
diff --git a/frontend-ios/Sources/ShellUI/ShellStyle.swift b/frontend-ios/Sources/ShellUI/ShellStyle.swift
index 34c722af..d57e9a8e 100644
--- a/frontend-ios/Sources/ShellUI/ShellStyle.swift
+++ b/frontend-ios/Sources/ShellUI/ShellStyle.swift
@@ -66,10 +66,12 @@ struct SectionHeading: View {
/// The Mac's secondary button: white 0.055, a 0.10 hairline, radius 9.
struct ShellButtonStyle: ButtonStyle {
+ /// Take all the width offered, as the buttons inside a settings card do.
+ var fills = false
@Environment(\.isEnabled) private var enabled
func makeBody(configuration: Configuration) -> some View {
- configuration.label.shellText(14, .semibold)
- .frame(minHeight: 44).padding(.horizontal, 14)
+ configuration.label.shellText(14, .semibold).lineLimit(1)
+ .padding(.horizontal, 14).frame(maxWidth: fills ? .infinity : nil, minHeight: 44)
.foregroundStyle(.white.opacity(0.92))
.background(.white.opacity(configuration.isPressed ? 0.13 : 0.055), in: RoundedRectangle(cornerRadius: 9))
.overlay(RoundedRectangle(cornerRadius: 9).strokeBorder(.white.opacity(0.10)))
@@ -240,7 +242,7 @@ extension GameState {
case .playable: ShellStrings.text("Ready to play")
case .needsGameData: ShellStrings.text("Needs game data")
case .needsAppUpdate: ShellStrings.text("App update needed")
- case .broken: ShellStrings.text("Unavailable")
+ case .broken(let reason, _): reason.isEmpty ? ShellStrings.text("Unavailable") : reason
}
}
var color: Color {
@@ -255,15 +257,15 @@ extension GameState {
case .playable: ""
case .needsGameData: ShellStrings.text("Choose this game's data to get ready to play.")
case .needsAppUpdate: ShellStrings.text("Install a newer version of this app to play this game.")
- case .broken(let reason): reason
+ case .broken(_, let detail): detail
}
}
var actionTitle: String {
switch self {
case .playable: ShellStrings.text("Play")
case .needsGameData: ShellStrings.text("Choose game data…")
- case .needsAppUpdate: ShellStrings.text("Update app")
- case .broken: ShellStrings.text("Show log")
+ case .needsAppUpdate: ShellStrings.text("How to update")
+ case .broken: ShellStrings.text("How to fix")
}
}
var actionSymbol: String {
@@ -271,7 +273,7 @@ extension GameState {
case .playable: "play.fill"
case .needsGameData: "folder"
case .needsAppUpdate: "arrow.up.circle"
- case .broken: "doc.text"
+ case .broken: "wrench.and.screwdriver"
}
}
}
@@ -313,3 +315,25 @@ struct GlyphHint: View {
}.foregroundStyle(.white.opacity(0.6))
}
}
+
+extension GameState {
+ /// Broken and needs-an-update are fixed on the Mac. Their primary action explains how, instead of acting.
+ var needsHelp: Bool {
+ switch self {
+ case .broken, .needsAppUpdate: true
+ default: false
+ }
+ }
+}
+
+/// Shows the How to fix or How to update explanation for a game. The library provides it. Without one, the state
+/// view presents the explanation itself.
+private struct ShellHelpKey: EnvironmentKey {
+ nonisolated(unsafe) static let defaultValue: ((GameTile) -> Void)? = nil
+}
+extension EnvironmentValues {
+ var shellShowHelp: ((GameTile) -> Void)? {
+ get { self[ShellHelpKey.self] }
+ set { self[ShellHelpKey.self] = newValue }
+ }
+}
diff --git a/frontend-ios/UITests/ShellAdditionalTests.swift b/frontend-ios/UITests/ShellAdditionalTests.swift
index 85ad0169..d99d6f55 100644
--- a/frontend-ios/UITests/ShellAdditionalTests.swift
+++ b/frontend-ios/UITests/ShellAdditionalTests.swift
@@ -115,4 +115,77 @@ import XCTest
app.buttons["library.back"].tap()
XCTAssertEqual(app.staticTexts["hero.title"].label, "The Quiet Tide")
}
+
+ /// The middle of the centred card, measured from the title under it. The tilted cards' accessibility frames are
+ /// skewed by their 3D transform, so a tap on the element itself can land on a neighbour.
+ private func centreCard() -> XCUICoordinate {
+ let window = app.windows.firstMatch.frame
+ let title = app.staticTexts["hero.title"].frame
+ return app.windows.firstMatch.coordinate(withNormalizedOffset: .zero)
+ .withOffset(CGVector(dx: window.midX - window.minX, dy: title.minY - window.minY - 80))
+ }
+ private let sampleTitles = ["Orbit Valley", "The Quiet Tide", "Paper Trails", "Moonlit Express", "Wild Gardens", "Drift Atlas", "Amber Hours"]
+
+ /// A touch swipe that snaps to another card makes it the selection: title, counter and buttons follow.
+ private func swipeCoverFlow(_ arguments: [String]) {
+ XCUIDevice.shared.orientation = .landscapeLeft
+ app.launchArguments = arguments
+ app.launch()
+ XCTAssertTrue(app.buttons["tile.orbit"].waitForExistence(timeout: 10))
+ XCTAssertEqual(app.staticTexts["hero.title"].label, "Orbit Valley")
+ let start = centreCard()
+ start.press(forDuration: 0.05, thenDragTo: start.withOffset(CGVector(dx: -260, dy: 0)), withVelocity: .fast, thenHoldForDuration: 0)
+ sleep(2)
+ let counter = app.staticTexts.matching(NSPredicate(format: "label ENDSWITH ' of 7'")).firstMatch
+ XCTAssertTrue(counter.exists)
+ let place = Int(counter.label.split(separator: " ").first ?? "") ?? 1
+ XCTAssertGreaterThan(place, 1, "the swipe moved the carousel")
+ XCTAssertEqual(app.staticTexts["hero.title"].label, sampleTitles[place - 1])
+ XCTAssertFalse(app.alerts["Demo action"].exists, "a swipe that ends on a card never launches it")
+ capture("cover-flow-swiped")
+ XCUIDevice.shared.orientation = .portrait
+ }
+ func testCoverFlowTouchSwipeSelects() { swipeCoverFlow(["--screen", "library"]) }
+ func testCoverFlowTouchSwipeSelectsUnfolded() throws {
+ try XCTSkipUnless(UIDevice.current.userInterfaceIdiom == .pad, "The fold stand-in needs an iPad canvas")
+ swipeCoverFlow(["--screen", "library", "--fold-test", "--unfolded"])
+ }
+
+ /// A broken game says what is wrong and explains the fix, the log stays one step away for a bug report.
+ func testBrokenGameExplainsTheFix() {
+ XCUIDevice.shared.orientation = .portrait
+ app.launchArguments = ["--screen", "broken"]
+ app.launch()
+ XCTAssertTrue(app.staticTexts["hero.title"].waitForExistence(timeout: 10))
+ XCTAssertTrue(app.descendants(matching: .any).matching(NSPredicate(format: "label CONTAINS[c] 'game files damaged'")).firstMatch.exists)
+ let fix = app.buttons.matching(identifier: "state.action").allElementsBoundByIndex.first { $0.isHittable }
+ XCTAssertEqual(fix?.label, "How to fix, Wild Gardens")
+ fix?.tap()
+ XCTAssertTrue(app.staticTexts["help.title"].waitForExistence(timeout: 5))
+ capture("broken-how-to-fix")
+ app.buttons["help.log"].tap()
+ XCTAssertTrue(app.alerts["Demo action"].waitForExistence(timeout: 5))
+ app.alerts.buttons["OK"].tap()
+ app.buttons["help.done"].tap()
+ XCTAssertFalse(app.staticTexts["help.title"].waitForExistence(timeout: 1))
+ }
+
+ /// Tapping a side card centres it and starts nothing. Tapping the centred card runs its primary action once.
+ func testCoverFlowTaps() {
+ XCUIDevice.shared.orientation = .landscapeLeft
+ app.launchArguments = ["--screen", "library"]
+ app.launch()
+ let side = app.buttons["tile.tide"]
+ XCTAssertTrue(side.waitForExistence(timeout: 10))
+ side.tap()
+ sleep(1)
+ XCTAssertEqual(app.staticTexts["hero.title"].label, "The Quiet Tide")
+ XCTAssertFalse(app.alerts["Demo action"].exists, "a side card only comes to the middle")
+ centreCard().tap()
+ XCTAssertTrue(app.alerts["Demo action"].waitForExistence(timeout: 5))
+ XCTAssertTrue(app.alerts.staticTexts["Play requested. The demo does not launch games."].exists)
+ app.alerts.buttons["OK"].tap()
+ XCTAssertFalse(app.alerts["Demo action"].waitForExistence(timeout: 1), "the action ran once")
+ XCUIDevice.shared.orientation = .portrait
+ }
}
diff --git a/frontend-ios/UITests/ShellCaptureTests.swift b/frontend-ios/UITests/ShellCaptureTests.swift
index 9556ade7..e140f8fc 100644
--- a/frontend-ios/UITests/ShellCaptureTests.swift
+++ b/frontend-ios/UITests/ShellCaptureTests.swift
@@ -45,6 +45,12 @@ import XCTest
shot("three-games-\(suffix)")
launch(["--screen", "library", "--select", "drift"])
shot("library-drift-\(suffix)")
+ for (screen, name) in [("broken", "help-broken"), ("needs-update", "help-update")] {
+ launch(["--screen", screen])
+ app.buttons.matching(identifier: "state.action").allElementsBoundByIndex.first { $0.isHittable }?.tap()
+ sleep(1)
+ shot("\(name)-\(suffix)")
+ }
}
XCUIDevice.shared.orientation = .portrait
}