Repository Public
1// SP Notes Core2// File: Sources/SPNotesFeatures/Support/FeatureViews.swift3// Description: The chrome every feature screen shares: the scaffold (background, serif title, actions, layout resolution),4// the calm status banner (offline / cached copy with its date / error with retry), the loading and failure5// states, and the card that marks AI content (always under `NVAIBadge`).6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import SPNotesDesign10import SwiftUI1112/// Root of a feature screen: resolves compact / regular, paints the background, shows the title row and the banner.13/// `content` owns its scrolling.14public struct FeatureScaffold<Actions: View, Content: View>: View {15 private let title: String16 private let subtitle: String?17 private let phase: LoadPhase18 private let freshness: Freshness?19 private let retry: (() -> Void)?20 private let showsHeader: Bool21 private let actions: () -> Actions22 private let content: (FeatureSizeClass) -> Content2324 public init(title: String, subtitle: String? = nil, phase: LoadPhase = .loaded, freshness: Freshness? = nil, showsHeader: Bool = true,25 retry: (() -> Void)? = nil, @ViewBuilder actions: @escaping () -> Actions, @ViewBuilder content: @escaping (FeatureSizeClass) -> Content) {26 self.title = title27 self.subtitle = subtitle28 self.phase = phase29 self.freshness = freshness30 self.showsHeader = showsHeader31 self.retry = retry32 self.actions = actions33 self.content = content34 }3536 public var body: some View {37 FeatureLayoutReader { sizeClass in38 VStack(alignment: .leading, spacing: 0) {39 if showsHeader {40 FeatureHeader(title: title, subtitle: subtitle, compact: sizeClass.isCompact, actions: actions)41 }42 FeatureStatusBanner(failure: phase.failure, freshness: freshness, retry: retry)43 .padding(.horizontal, sizeClass.isCompact ? NVSpace.lg : NVSpace.xl)44 content(sizeClass)45 .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)46 }47 .background(NVColor.bg)48 }49 }50}5152public extension FeatureScaffold where Actions == EmptyView {53 init(title: String, subtitle: String? = nil, phase: LoadPhase = .loaded, freshness: Freshness? = nil, showsHeader: Bool = true,54 retry: (() -> Void)? = nil, @ViewBuilder content: @escaping (FeatureSizeClass) -> Content) {55 self.init(title: title, subtitle: subtitle, phase: phase, freshness: freshness, showsHeader: showsHeader, retry: retry, actions: { EmptyView() }, content: content)56 }57}5859/// Title row of a screen: serif title, muted subtitle, trailing actions.60public struct FeatureHeader<Actions: View>: View {61 private let title: String62 private let subtitle: String?63 private let compact: Bool64 private let actions: () -> Actions6566 public init(title: String, subtitle: String? = nil, compact: Bool, @ViewBuilder actions: @escaping () -> Actions) {67 self.title = title68 self.subtitle = subtitle69 self.compact = compact70 self.actions = actions71 }7273 public var body: some View {74 HStack(alignment: .firstTextBaseline, spacing: NVSpace.md) {75 VStack(alignment: .leading, spacing: NVSpace.xxs) {76 Text(title)77 .nvFont(compact ? .h2 : .h1)78 .foregroundStyle(NVColor.fg)79 .lineLimit(2)80 .accessibilityAddTraits(.isHeader)81 if let subtitle, !subtitle.isEmpty {82 Text(subtitle)83 .nvFont(.ui)84 .foregroundStyle(NVColor.fgMuted)85 .lineLimit(2)86 }87 }88 Spacer(minLength: NVSpace.sm)89 HStack(spacing: NVSpace.sm) { actions() }90 }91 .padding(.horizontal, compact ? NVSpace.lg : NVSpace.xl)92 .padding(.top, compact ? NVSpace.lg : NVSpace.xl)93 .padding(.bottom, NVSpace.md)94 }95}9697/// The calm banner: « Hors ligne — copie du … », « Mis à jour il y a … » for a cached copy, or an error with « Réessayer ».98/// Renders nothing when there is nothing to say.99public struct FeatureStatusBanner: View {100 @Environment(\.featureNow) private var fixedNow101 private let failure: FeatureFailure?102 private let freshness: Freshness?103 private let retry: (() -> Void)?104105 public init(failure: FeatureFailure?, freshness: Freshness?, retry: (() -> Void)? = nil) {106 self.failure = failure107 self.freshness = freshness108 self.retry = retry109 }110111 /// What the banner says (also its VoiceOver label); nil = no banner. Exposed for tests.112 public static func text(failure: FeatureFailure?, freshness: Freshness?, now: Date = Date()) -> String? {113 if let failure {114 if failure.isOffline, let freshness { return LF("Hors ligne · %@", freshness.label(now: now)) }115 return failure.message116 }117 if let freshness, freshness.fromCache { return LF("Copie de l'appareil · %@", freshness.label(now: now)) }118 return nil119 }120121 public var body: some View {122 if let text = Self.text(failure: failure, freshness: freshness, now: fixedNow ?? Date()) {123 let calm = failure == nil || failure?.isOffline == true124 HStack(spacing: NVSpace.sm) {125 Image(systemName: failure == nil ? "clock.arrow.circlepath" : (calm ? "wifi.slash" : "exclamationmark.triangle"))126 .foregroundStyle(calm ? NVColor.fgMuted : NVColor.danger)127 .accessibilityHidden(true)128 Text(text)129 .nvFont(.ui)130 .foregroundStyle(calm ? NVColor.fgMuted : NVColor.dangerText)131 .fixedSize(horizontal: false, vertical: true)132 Spacer(minLength: NVSpace.sm)133 if let retry {134 Button(L("Réessayer"), action: retry)135 .buttonStyle(.plain)136 .nvFont(.uiStrong)137 .foregroundStyle(NVColor.accent)138 }139 }140 .padding(.horizontal, NVSpace.md)141 .padding(.vertical, NVSpace.sm)142 .background(NVColor.bgSunken, in: NVRadius.shape(NVRadius.md))143 .overlay(NVRadius.shape(NVRadius.md).strokeBorder(NVColor.line, lineWidth: 1))144 .padding(.bottom, NVSpace.sm)145 .accessibilityElement(children: .combine)146 .accessibilityLabel(text)147 }148 }149}150151/// Chooses between the loading state, the failure state, the empty state and the content. A screen that has data shows152/// it whatever the phase (the banner tells the rest): never a spinner forever, never an error over usable data.153public struct FeaturePhaseView<Empty: View, Content: View>: View {154 private let phase: LoadPhase155 private let hasData: Bool156 private let retry: (() -> Void)?157 private let empty: () -> Empty158 private let content: () -> Content159160 public init(phase: LoadPhase, hasData: Bool, retry: (() -> Void)? = nil, @ViewBuilder empty: @escaping () -> Empty, @ViewBuilder content: @escaping () -> Content) {161 self.phase = phase162 self.hasData = hasData163 self.retry = retry164 self.empty = empty165 self.content = content166 }167168 public var body: some View {169 if hasData {170 content()171 } else {172 switch phase {173 case .idle, .loading:174 FeatureLoadingView()175 case .failed(let failure):176 FeatureFailureView(failure: failure, retry: retry)177 case .loaded:178 empty().frame(maxWidth: .infinity, maxHeight: .infinity)179 }180 }181 }182}183184public struct FeatureLoadingView: View {185 private let label: String186 public init(_ label: String = L("Chargement…")) { self.label = label }187 public var body: some View {188 VStack(spacing: NVSpace.md) {189 NVProgressDots()190 Text(label).nvFont(.ui).foregroundStyle(NVColor.fgMuted)191 }192 .frame(maxWidth: .infinity, maxHeight: .infinity)193 .accessibilityElement(children: .combine)194 .accessibilityLabel(label)195 }196}197198/// Full-surface failure (only when there is nothing to show).199public struct FeatureFailureView: View {200 private let failure: FeatureFailure201 private let retry: (() -> Void)?202203 public init(failure: FeatureFailure, retry: (() -> Void)? = nil) {204 self.failure = failure205 self.retry = retry206 }207208 public static func symbol(_ kind: FeatureFailure.Kind) -> String {209 switch kind {210 case .offline, .notCached: return "wifi.slash"211 case .unsupported: return "server.rack"212 case .signedOut: return "person.crop.circle.badge.exclamationmark"213 case .notFound: return "questionmark.folder"214 default: return "exclamationmark.triangle"215 }216 }217218 public static func title(_ kind: FeatureFailure.Kind) -> String {219 switch kind {220 case .offline, .notCached: return L("Hors ligne")221 case .unsupported: return L("Fonction indisponible")222 case .signedOut: return L("Session expirée")223 case .notFound: return L("Introuvable")224 default: return L("Une erreur est survenue")225 }226 }227228 public var body: some View {229 NVEmptyState(systemImage: Self.symbol(failure.kind), title: Self.title(failure.kind), message: failure.message,230 actionTitle: retry == nil ? nil : L("Réessayer"), action: retry)231 .frame(maxWidth: .infinity, maxHeight: .infinity)232 }233}234235/// The only container AI-generated content may appear in: violet-soft surface, `NVAIBadge` on top. The content is a236/// suggestion; applying it is always a separate explicit control supplied by the caller.237public struct FeatureAICard<Content: View>: View {238 private let model: String?239 private let title: String?240 private let content: () -> Content241242 public init(model: String? = nil, title: String? = nil, @ViewBuilder content: @escaping () -> Content) {243 self.model = model244 self.title = title245 self.content = content246 }247248 public var body: some View {249 VStack(alignment: .leading, spacing: NVSpace.sm) {250 HStack(spacing: NVSpace.sm) {251 NVAIBadge(model: model)252 if let title { Text(title).nvFont(.uiStrong).foregroundStyle(NVColor.fg) }253 Spacer(minLength: 0)254 }255 content()256 }257 .padding(NVSpace.lg)258 .frame(maxWidth: .infinity, alignment: .leading)259 .background(NVColor.aiSoft, in: NVRadius.shape(NVRadius.lg))260 .overlay(NVRadius.shape(NVRadius.lg).strokeBorder(NVColor.ai.opacity(0.35), lineWidth: 1))261 }262}263264/// A small icon button with a mandatory VoiceOver label.265public struct FeatureIconButton: View {266 private let systemImage: String267 private let label: String268 private let tone: NVTone269 private let action: () -> Void270271 public init(_ systemImage: String, label: String, tone: NVTone = .neutral, action: @escaping () -> Void) {272 self.systemImage = systemImage273 self.label = label274 self.tone = tone275 self.action = action276 }277278 public var body: some View {279 Button(action: action) {280 Image(systemName: systemImage)281 .font(.system(size: 15, weight: .medium))282 .foregroundStyle(tone == .neutral ? NVColor.fgMuted : tone.foreground)283 .frame(minWidth: 32, minHeight: 32)284 .background(NVColor.bgHover.opacity(0.6), in: NVRadius.shape(NVRadius.sm))285 .contentShape(Rectangle())286 }287 .buttonStyle(.plain)288 .accessibilityLabel(label)289 #if os(macOS)290 .help(label)291 #endif292 }293}294295/// A filled or quiet text button in the system's accent.296public struct FeatureButton: View {297 public enum Kind: Sendable { case primary, secondary, ai, destructive }298 private let title: String299 private let systemImage: String?300 private let kind: Kind301 private let action: () -> Void302303 public init(_ title: String, systemImage: String? = nil, kind: Kind = .secondary, action: @escaping () -> Void) {304 self.title = title305 self.systemImage = systemImage306 self.kind = kind307 self.action = action308 }309310 public var body: some View {311 Button(action: action) {312 HStack(spacing: NVSpace.xs) {313 if let systemImage { Image(systemName: systemImage).accessibilityHidden(true) }314 Text(title)315 }316 .nvFont(.uiStrong)317 .foregroundStyle(foreground)318 .padding(.horizontal, NVSpace.md)319 .frame(minHeight: 32)320 .background(background, in: NVRadius.shape(NVRadius.sm))321 .overlay(NVRadius.shape(NVRadius.sm).strokeBorder(kind == .secondary ? NVColor.lineStrong : .clear, lineWidth: 1))322 .contentShape(Rectangle())323 }324 .buttonStyle(.plain)325 }326327 private var foreground: Color {328 switch kind {329 case .primary: return NVColor.accentFg330 case .secondary: return NVColor.fg331 case .ai: return NVColor.ai332 case .destructive: return NVColor.dangerText333 }334 }335336 private var background: Color {337 switch kind {338 case .primary: return NVColor.accent339 case .secondary: return NVColor.bgElevated340 case .ai: return NVColor.aiSoft341 case .destructive: return NVColor.danger.opacity(0.12)342 }343 }344}345