How aeastr/portal works
Project type and purpose
• This is a Swift Package library (not a full-stack app) that provides a set of SwiftUI view modifiers and container components to drive “portal”-style view transitions (floating animations) across view hierarchies, sheets, and navigation pushes.
File structure
• Top-level:
• Package.swift, README.md, LICENSE, Tests, Sources
• .github/workflows – CI setup for building/testing on Swift toolchains
• Sources/Portal:
• Core API / data types: AnchorKey.swift, CrossModel.swift, PortalInfo.swift
• Container/engine components: PortalContainer.swift, PassThroughWindow.swift, PortalLayerView.swift
• Public SwiftUI view modifiers and helpers: PortalSource.swift, PortalDestination.swift, PortalTransition.swift, SheetShow.swift, View+OnChangeCompat.swift
• Examples subfolder: CardsExample.swift, DifferExample.swift, NavigationExample.swift, SheetExample.swift
• Tests/PortalTests: unit tests for SheetShow behavior
README for additional insights
• Emphasizes a portal metaphor, SwiftUI compatibility (iOS 15+), no custom presentation modifiers required, and a small set of public APIs: .portalContainer(), .portalSource(…), .portalDestination(…), .portalTransition(…).
Main components
a. SwiftUI App (consumer)
b. PortalContainer
c. View hierarchy containing:
• PortalSource anchors
• PortalDestination anchors
• PortalTransition controllers (Binding<Bool> or Binding<Item?>)
d. Core engine:
• PortalInfo registry (maps source/destination IDs to view anchor info)
• CrossModel (coordinate conversion logic)
• AnchorKey (preference key for gathering anchor frames)
e. Overlay layer:
• PassThroughWindow (UIWindow subclass to host overlay above existing hierarchy)
• PortalLayerView (SwiftUI view that renders the floating snapshot and animates)
f. Examples & Tests (auxiliary components)
Relationships & data flow
1. App wraps its root in PortalContainer → installs PassThroughWindow + .environmentObject(PortalInfo).
2. A view marked with .portalSource(id:) publishes its anchor frame via AnchorKey into PortalInfo registry.
3. A separate view marked with .portalDestination(id:) also publishes its target anchor frame.
4. When .portalTransition(isActive: id:) becomes true, the controller:
• Reads source & destination frames from PortalInfo
• Generates a snapshot or moves the source view into PortalLayerView
• Animates its frame/scale across hierarchies using CrossModel coordinate conversions
• On completion, reintegrates the view into the destination location
5. PortalLayerView lives in PassThroughWindow, rendered above everything.
Architectural patterns & design principles
• SwiftUI + PreferenceKey pattern for gathering layout information (AnchorKey)
• EnvironmentObject (PortalInfo) for cross-hierarchy state sharing
• UIWindow overlay (PassThroughWindow) for out-of-tree rendering
• Decoupled source/destination registration & controller-driven animation
• Pure Swift Package (platform-agnostic, no storyboard or XIBs)
Details
• To show the separation of concerns: registration vs animation vs rendering
• How SwiftUI’s PreferenceKey and EnvironmentObject work together
• Don’t omit the overlay window: it’s the heart of cross-hierarchy transitions
• Example entry points to illustrate real-world usage paths