iOS/KMP-utvikling

Denne guiden dekker iOS-utvikling i Impulse AI: KMP shared module, SwiftUI-moonstre, design-tokens og lokalisering.

Tips

For bygg, signing og TestFlight-deployment, se iOS bygg og deployment.

KMP shared module

Kotlin Multiplatform (KMP) deler forretningslogikk mellom iOS og Android. Shared-modulen inneholder domenemodeller, store-er, API-klient og i18n.

shared/src/commonMain/kotlin/com/im/shared/
├── domain/            # Domenemodeller (Impulse, Entry, Insight, etc.)
├── store/             # FlowMVI stores (HomeStore, InsightsStore, etc.)
├── data/              # Repository-implementasjoner + API-klient
├── i18n/              # Strings.kt (moko-wrappere)
└── util/              # Delte verktoy

Bygg-kommandoer

# Rask kompileringssjekk (13s) -- bruk dette for validering
cd apps/mobile-kmp && ./gradlew :shared:compileKotlinIosSimulatorArm64

# Full shared-modul build (3+ min)
cd apps/mobile-kmp && ./gradlew :shared:build

# Rens og bygg pa nytt
cd apps/mobile-kmp && ./gradlew clean

Tips

Bruk alltid compileKotlinIosSimulatorArm64 for rask validering av KMP-endringer. Full :shared:build tar 3+ minutter og er sjelden nodvendig lokalt.

Byggeytelse

Gradle-daemon er aktivert og gir 10-15s raskere bygg. Incremental compilation er konfigurert i gradle.properties:

Byggemodus	Tid
Forste build	~15-20s
Inkrementelt	~8-10s
Shared-kode	~10-12s

Forsiktig

Ikke bruk --no-daemon — daemon gir betydelig raskere builds. Unnga ogsa piping med | tail -20 som buffrer og venter pa hele bygget. Bruk | grep -E "(BUILD|error:)" for live feedback.

Device-testing mot staging/production

iOS-appen bruker DEVELOPMENT (localhost) som standard. For a teste mot staging eller production fra fysisk enhet eller simulator, bruk Xcode scheme environment variables.

Oppsett

1. Xcode → Product → Scheme → Edit Scheme (⌘<)
2. Run → Arguments → Environment Variables
3. Legg til:

Name	Value	Resultat
APP_ENVIRONMENT	STAGING	api-stg.impulseai.app + Supabase staging
APP_ENVIRONMENT	PRODUCTION	api.impulseai.app + Supabase production
APP_ENVIRONMENT	DEVELOPMENT	Tilbake til localhost (fjerner override)

4. Bygg og kjor (⌘R)

Slik fungerer det

Valget persisteres i UserDefaults — appen husker miljoet selv etter at du kobler fra Xcode eller stopper debuggeren. Du trenger kun a sette variabelen en gang.

Tilbakestilling: Sett APP_ENVIRONMENT=DEVELOPMENT og kjor en gang, eller slett appen fra enheten.

Fil: ImpulseApp.swift (init) — leser ProcessInfo → fallback til UserDefaults.

Miljo-oversikt

Miljo	API URL	Supabase
Development	http://localhost:3001	Lokal (localhost:54331)
Staging	https://api-stg.impulseai.app	conxpuqktkeiphnnpfiv.supabase.co
Production	https://api.impulseai.app	jksqfeutntcvukrisrno.supabase.co

Forsiktig

Staging og production krever ekte autentisering (Apple Sign In). Dev-token og seed-brukere finnes kun lokalt. Supabase staging ma ha Apple OAuth-provider konfigurert med gyldig secret.

Forutsetninger for staging-autentisering

For at Apple Sign In skal fungere mot staging:

1. Supabase staging → Authentication → Providers → Apple:

   • Client ID: com.digiteers.impulseai
   • Secret Key: Gyldig Apple JWT (samme som production)
   • Callback URL: https://conxpuqktkeiphnnpfiv.supabase.co/auth/v1/callback

2. Doppler stg ma ha:

   • SUPABASE_URL — Supabase staging URL
   • SUPABASE_SECRET_KEY — Service role key
   • API_CLIENT_KEY — Matcher verdien i Environment.kt
   • NODE_ENV=production — Aktiverer API-key middleware

3. Railway staging custom domain aktiv: api-stg.impulseai.app

SwiftUI + @Observable-regler

Kritisk regel: aldri .map KMP-typer

Bruk KMP-typer (shared.Impulse, shared.Entry, etc.) direkte i SwiftUI views. Aldri transformer med .map { SwiftWrapper(...) } — dette bryter @Observable-tracking og forhindrer UI-oppdateringer.

// FEIL -- bryter observation:
private var entries: [EntryDisplayData] {
    entriesStore.entries.map { EntryDisplayData(...) }
}

// RIKTIG -- observation fungerer:
private var entries: [shared.Entry] {
    entriesStore.entries
}

Tillatte operasjoner pa KMP-typer:

• .filter { } — returnerer samme objekter
• .prefix() / .suffix() — OK
• .sorted { } — OK
• Direkte tilgang til store-properties — OK

Forbudte operasjoner:

• .map { NewType(...) } — bryter observation
• Wrapper-typer som EntryDisplayData — unnga

KMP-typer med id-property trenger extension for sheet(item:):

extension shared.Entry: Identifiable {}

State Sync Pattern

Nar en view holder en lokal @State-kopi av et store-objekt, synkroniser med en enkelt onChange:

// EN onChange -- updatedAt endres ved ALLE server-side felt-mutasjoner
.onChange(of: storeObject?.updatedAt) { _, _ in
    if let updated = storeObject {
        localCopy = updated
    }
}

Aldri legg til separate onChange-handlere for individuelle felter. updatedAt-timestampet dekker alle mutasjoner.

Derived View State Pattern

Nar en SwiftUI-views rendering avhenger av flere @Observable-stores, bruk en computed enum — aldri if-else-kjeder i view body.

Monster (2 filer per skjerm)

// 1. FooState.swift -- enum med alle mulige display-tilstander
enum FooContentState {
    case loading
    case empty
    case content
    case error(String)
}

// 2. FooView.swift -- computed property utleder tilstand fra stores
private var contentState: FooContentState {
    if store.isLoading && !store.hasData { return .loading }
    if let error = store.error, !store.hasData { return .error(error) }
    if !store.hasData { return .empty }
    return .content
}

// Exhaustive switch -- kompilatoren hjelper
switch contentState {
case .loading: ProgressView()
case .empty: EmptyState()
case .content: ContentView()
case .error(let msg): ErrorView(msg)
}

Never-Fetched = Loading-konvensjonen

if store.isLoading || (!store.hasData && store.lastFetched == nil) {
    return .loading
}

lastFetched == nil betyr at data aldri ble hentet — vis spinner, ikke tom tilstand. KMP RetryableLoadingState-grensesnittet gir lastFetched: Long? pa tvers av alle stores.

Eksisterende bruk

View	Enum	Fil
ImpulseDetailView	SessionSectionState	Features/Impulses/SessionSectionState.swift
InsightsView	InsightsContentState	Features/Insights/InsightsContentState.swift
JourneyView	JourneyContentState	Features/Journey/JourneyContentState.swift
UnifiedSessionView	SessionLayer	Definert inline

Accent Surface Token System

Designsystemet bygger pa en aksent-farge med fire opasitetsniva:

Fargehjelpere (Colors.swift)

extension Color {
    func accentSurface() -> Color { self.opacity(0.08) }      // Kort-bakgrunner
    func accentInteractive() -> Color { self.opacity(0.10) }   // Ghost CTA-er
    func accentBadge() -> Color { self.opacity(0.15) }         // Status-piller, tags
    // 1.00 -- direkte farge for tekst/ikoner
}

ViewModifiers (AccentSurface.swift)

Modifier	Funksjon
.imCard(accent:, padding:, cornerRadius:)	Kort med padding + maxWidth + accentSurface-bakgrunn. nil accent -> backgroundSecondary
.imGhostCTA(accent:)	Ghost-CTA med foregroundColor + accentInteractive-bakgrunn
.imBadge(accent:)	Status-pille med accentBadge-bakgrunn
.imSheet(dismiss:)	Sheet med backgroundPrimary + toolbar xmark.circle.fill

Aksentfarge-valg

Kontekst	Aksent
Kontraksjons-impuls/sesjon	.classContraction
Ekspansjons-impuls/sesjon	.classExpansion
Brand/noytral (insights, stats, home)	.brand
Ingen kontekst (profil, tab bar)	nil -> backgroundSecondary

CTA-hierarki (2 niva)

Tier	Stil	Jobb	Bruk
Invite	.imGhostCTA(accent:)	Brukerhandlinger	Start sesjon, fang impuls, fortsett, los
Progress	Solid SessionColors.primaryText	Sesjonsnavigasjon	Sesjon-intro, steg-knapper, Done

Toolbar Close-knapper

Alle sheets og modale skjermer bruker:

Button { dismiss() } label: {
    Image(systemName: "xmark.circle.fill")
        .foregroundColor(.textMetadata)
}

Eksklusjonsliste (forblir backgroundSecondary)

• ProfileView list-rader
• CustomTabBar
• JourneyFilterChips / GroupingToggle
• Editor-overflater (ContractionEditor, ExpansionEditor, NoteEditor)
• AIClassificationLoadingView gradient
• HomeEmptyStates

Text Style Conventions

All tekststyling i appen er konvensjonsdrevet gjennom 18 modifiers definert i TextStyles.swift. Ingen rå .font() på Text-elementer — all tekst bruker en navngitt konvensjon.

Navnekonvensjon

im + TextRole [+ Variant]

Prefiks im, etterfulgt av tekstens rolle (ikke utseende). Varianter som suffix: .imBodyLight(), ikke .imLightBody().

Innholdshierarki

Modifier	Spesifikasjon	Rolle
.imHeroTitle(size:)	28pt bold, textPrimary, sentrert	Store titler (onboarding, splash, completion)
.imSectionTitle()	title3 (20pt) bold, textPrimary	Primære seksjonsoverskrifter, tier-navn
.imCardTitle()	subheadline (15pt) semibold, textPrimary	Kort-titler (“Your Insight”, “Mental”)
.imSectionLabel()	subheadline semibold, textSecondary, leading	Seksjonsetiketter (“Analysis”, “Releases”)
.imBody()	16pt regular, textPrimary, 4pt lineSpacing	All lesetekst
.imBodyLight()	17pt light, textSecondary, sentrert	Onboarding/tour-tekst
.imMetadata()	caption (12pt), textMetadata	Tidsstempler, tall, hints
.imLegalText()	caption2 (11pt), textMetadata	Juridisk tekst, fine print

Interaktiv

Modifier	Spesifikasjon	Rolle
.imToolbarTitle()	headline (17pt) semibold, textPrimary	Navigasjonsbar-titler
.imTabLabel(isSelected:)	subheadline, semibold/regular basert på state	Tabs, pickers, filter chips
.imActionLabel()	subheadline medium	Inline CTAer, text-linker
.imNavButton()	16pt semibold	Solid CTA-knapper

Dekorativ/display

Modifier	Spesifikasjon	Rolle
.imDisplayNumber()	40pt regular, textPrimary	Store metrikk-tall
.imBadgeLabel()	caption2 (11pt) medium	Pill/badge-tekst
.imProductLabel()	footnote (13pt) semibold, uppercase	Produkt-header titler

Spesialisert

Modifier	Spesifikasjon	Rolle
.imGuidanceTitle()	20pt semibold, expanded tracking	Inspirasjonskort step-navn
.imGuidanceBody()	18pt light, sentrert, spacious lineSpacing	Meditasjonstekst
.imErrorBanner()	callout (16pt), textPrimary	Feilmeldinger

Regler for lesetekst (.imBody)

All tekst der formålet er å lese og forstå innholdet bruker .imBody():

• Alltid textPrimary (hvit). Avvik fra dette er å style tekst for et annet formål enn lesing.
• Alltid regular vekt. Bold/semibold er reservert for headings, labels og CTAer.
• 16pt (KMP bodyLarge token). Cross-platform konsistens med Android.

// Lesetekst — bruker alltid .imBody()
Text(insight.narrative)
    .imBody()

// Støttetekst — bruker .imMetadata() eller .imSectionLabel()
Text("April 2, 2026")
    .imMetadata()

Fargekonvensjon for modifiers

Noen modifiers setter farge, andre ikke. Konvensjonen:

Setter farge	Setter IKKE farge (sett separat)
.imBody() → textPrimary	.imBadgeLabel() — badge-farge varierer
.imMetadata() → textMetadata	.imTabLabel() — state-avhengig
.imSectionLabel() → textSecondary	.imActionLabel() — typisk .brand
.imHeroTitle() → textPrimary	.imNavButton() — typisk .textOnColor
.imErrorBanner() → textPrimary	.imGuidanceTitle() — SessionColors
.imLegalText() → textMetadata	.imGuidanceBody() — SessionColors
.imToolbarTitle() → textPrimary	.imProductLabel() — aktiv/inaktiv

Når du trenger en annen farge enn konvensjonens default, legg til .foregroundColor() etter modifieren.

Line Spacing Tokens

Definert i Typography.swift som IMLineSpacing:

Token	Verdi	Bruk
.tight	3pt	Kompakt caption-tekst i korte kort
.body	4pt	Standard brødtekst
.comfortable	6pt	Onboarding, lett tekst
.spacious	8pt	Guidance, affirmations

Tracking Tokens

Definert i Typography.swift som IMTracking:

Token	Verdi	Bruk
.subtle	0.5pt	Seksjon-headere
.wide	2pt	Splash-undertitler, completion-labels
.expanded	4pt	Splash-titler, session step-labels

Filer

Beskrivelse	Sti
Text-konvensjoner (18 modifiers)	iosApp/Components/Modifiers/TextStyles.swift
Line Spacing + Tracking tokens	iosApp/Theme/Typography.swift
Layout-constraints	IMConstraints i TextStyles.swift

Session Design Tokens

Sesjons-spesifikke tokens bygger pa accent surface-systemet:

• SessionColors.cardBackground(for:) — returnerer aksenttintet kortfarge basert pa sesjonsklassifisering
• SessionColors.backgroundGradient — sesjonsgradient-bakgrunn
• Sesjonskomponenter mottar en accent: Color-parameter (standard: .brand)

Fil: iosApp/Features/Sessions/Shared/SessionDesignTokens.swift

Store-kommunikasjonsarkitektur

Appen bruker tre distinkte kommunikasjonsmekanismer:

Mekanisme	Jobb	Retning	Eksempel
@Observable state	Reaktive UI-oppdateringer	Store -> View (automatisk)	Loading, lister, feil
Callbacks	Navigasjonsside-effekter	Store -> View (imperativ)	Apne fullScreenCover, dismiss
AppEventBus	Cross-store-koordinering	Store -> Store (KMP)	“Analyse ferdig” -> HomeStore refresher

Callback-regler

Callbacks pa store-wrappere er strengt for navigasjonseffekter som ikke kan uttrykkes via @Observable-state.

1. Tilordne i onAppear, rydd i onDisappear — forhindre foreldede callbacks
2. Aldri legg til callbacks for state-endringer — bruk @Observable store-properties
3. Singleton = siste skriver vinner — kun en view kan eie en callback om gangen

Gold standard: UnifiedSessionView.setupStoreCallbacks() + cleanupIfNeeded().

Moko Strings — trippel oppdatering

Ny lokalisert streng krever oppdatering i 3 filer:

1. strings.xml (base + nb)           -- moko source of truth (snake_case)
2. Strings.kt                         -- KMP camelCase wrapper
3. LocalizedString.swift               -- iOS Swift wrapper (L.propertyName)

Filer

Fil	Sti
Engelsk	shared/src/commonMain/moko-resources/base/strings.xml
Norsk	shared/src/commonMain/moko-resources/nb/strings.xml
KMP-wrapper	shared/src/commonMain/kotlin/com/im/shared/i18n/Strings.kt
iOS-wrapper	iosApp/Utilities/LocalizedString.swift

Bruk

// iOS
L.sessionHelloWorld

// Android
mokoStringResource(MR.strings.session_hello_world)

Forsiktig

NSLocale “no”->“nb”-bug: Apple normaliserer “no” til “nb” via NSLocale. Moko source-katalogen ma vaere nb/ (ikke no/) slik at generert nb.lproj matcher NSLocale-oppslag.

Merk

Etter a legge til strenger — kjor KMP compile for Xcode-build. Xcode vil feile hvis Strings.kt-wrapperen mangler.

Nøkkelfiler

Beskrivelse	Sti
Fargetokens	iosApp/Theme/Colors.swift
Typografi + LineSpacing + Tracking	iosApp/Theme/Typography.swift
Spacing	iosApp/Theme/Spacing.swift
Tekstkonvensjoner (18 modifiers)	iosApp/Components/Modifiers/TextStyles.swift
Overflatemodifiers	iosApp/Components/Modifiers/AccentSurface.swift
Press-effekt	iosApp/Components/Modifiers/PressEffect.swift
Sesjonstokens	iosApp/Features/Sessions/Shared/SessionDesignTokens.swift
Lokalisering	strings.xml -> Strings.kt -> LocalizedString.swift
Store-wrappere	iosApp/Stores/
KMP store provider	iosApp/Stores/KMPStoreProvider.swift

---

SKIE og SwiftUI Preview

SKIE (Swift/Kotlin Interface Enhancer) genererer forskjellige Swift-typer for simulator vs device:

Target	Kotlin Double?	Kotlin String i ForEach
Simulator (arm64-simulator)	Double?	Fungerer direkte
Device (arm64)	KotlinDouble?	Kan gi generics-feil

Regler

1. #Preview ma wrappes i simulator-guard:

#if targetEnvironment(simulator)
#Preview {
    MyView(data: shared.SomeKMPType(...))
}
#endif

Uten dette feiler device-builds fordi preview-data bruker simulator-spesifikke typer.

2. ForEach med KMP-lister — bruk enumerated():

// Robust — fungerer pa tvers av targets
ForEach(Array(items.enumerated()), id: \.offset) { _, item in
    ItemView(item: item)
}

// Fragilt — kan feile pa device
ForEach(items, id: \.self) { item in ... }

3. KotlinDouble i preview-data:

// Simulator: bruk plain Double
shared.AreaAssignment(relevanceScore: 0.95)

// Device: krever KotlinDouble
shared.AreaAssignment(relevanceScore: KotlinDouble(double: 0.95))

// Losning: wrap preview i #if targetEnvironment(simulator)

Forsiktig

Disse forskjellene gjelder kun for typer som konstrueres direkte i Swift (preview-data, test-data). Normal bruk av KMP-typer fra store-er er ikke pavirket — SKIE handterer konverteringen automatisk.