How aheze/setting works
Purpose and delivery
Setting is a Swift Package library for composing searchable, hierarchical SwiftUI preference panels on iOS 15+ and macOS Monterey+. Its public product is a declarative settings DSL built around result builders, native bindings/AppStorage, and reusable controls. Package definition: Package.swift; primary library sources: Sources/.
Consumer and demo entry points
Library consumers import Setting and root their UI in SettingStack, then declare SettingPage/SettingGroup content. The runnable integration example is the SwiftUI app rooted at Example/SettingExample/SettingExampleApp.swift, with settings compositions in Example/SettingExample/PlaygroundView.swift and Example/SettingExample/PreferencesView.swift.
Declarative settings model
The core protocol/result-builder layer represents settings content and supports composition, conditional branches, and split declarations. Sources/Setting.swift defines the base DSL; tuple/aggregate handling is in Sources/Views/SettingTupleView.swift; extensions and modifiers adapt the DSL in Sources/SettingExtensions.swift and Sources/SettingModifiers.swift. This is the boundary between an app’s declarative setting tree and library rendering.
Hierarchy and navigation
SettingStack is the top-level coordinator for settings presentation, while pages and groups establish nested information architecture. Key components are Sources/Views/SettingStack.swift, Sources/Views/SettingPage.swift, and Sources/Views/SettingGroup.swift. Nested pages become navigable destination rows; groups organize rows and headers within a page. Sources/SettingPath.swift likely carries page-navigation identity/path state across this hierarchy.
Rendering and controls
The library converts declared setting nodes into SwiftUI row/page views. The shared rendering surface is Sources/Views/SettingView.swift, with custom embedding through Sources/Views/SettingCustomView.swift. Built-in bound controls include Sources/Views/SettingToggle.swift, Sources/Views/SettingPicker.swift, Sources/Views/SettingSlider.swift, plus text, text field, and button implementations in Sources/Views/. User bindings remain owned by the consuming app, allowing @State, @AppStorage, and observable bindings to drive controls.
State, environment, and search
SettingViewModel centralizes mutable panel state, including search text and customization via injection into SettingStack: Sources/SettingViewModel.swift. Environment propagation is defined in Sources/SettingEnvironment.swift. Search results are modeled separately in Sources/SettingSearchResult.swift; the primary flow is setting tree → searchable result collection/filtering → results or caller-supplied no-results view. Identity is important when titles collide, so explicit IDs preserve correct rendering/navigation behavior.
Styling and platform boundary
Appearance is expressed through native SwiftUI modifiers plus library-specific styles/configuration in Sources/SettingStyles.swift and Sources/SettingModifiers.swift. Shared visual primitives—such as icons, divided stacks, and page jump links—live in Sources/Utilities/SettingIcon.swift, Sources/Utilities/SettingDividedVStack.swift, and Sources/Utilities/SettingJumpLink.swift. There is no backend, network service, or server infrastructure; runtime dependencies are SwiftUI and Apple platform persistence facilities such as AppStorage/UserDefaults.
Main entry points: Setting.swift Setting DSL · SettingView.swift SettingView · SettingStack.swift SettingStack · PlaygroundView.swift Example Settings
Components 19
Consumer & Example
- Consumer SwiftUI App · Imports Setting and owns bindings and persisted values.
- Example App Root · Runnable integration entry point.
Example/SettingExample/SettingExampleApp.swift - Example Settings
Example/SettingExample/PlaygroundView.swift
Declarative DSL
- Setting DSL · Converts declarative setting content into library nodes.
Sources/Setting.swift - Tuple Composition · Handles multi-child and conditional DSL content.
Sources/Views/SettingTupleView.swift - DSL Extensions & Modifiers
Sources/SettingExtensions.swift
Hierarchy & Rendering
- SettingStack · Top-level presentation and state-injection boundary.
Sources/Views/SettingStack.swift - Pages & Groups · Pages create navigation; groups organize rows and headers.
Sources/Views/SettingPage.swift - SettingPath · Carries page navigation identity through the hierarchy.
Sources/SettingPath.swift - SettingView · Renders declared setting nodes as SwiftUI rows and pages.
Sources/Views/SettingView.swift - Custom Setting View
Sources/Views/SettingCustomView.swift - Bound Controls · Toggle, picker, and slider bind directly to consumer-owned state.
Sources/Views/SettingToggle.swift - Visual Primitives · Icons, divided stacks, and page jump links.
Sources/Utilities/SettingIcon.swift
State, Search & Style
- SettingViewModel · Owns mutable panel state including search text and customization.
Sources/SettingViewModel.swift - Setting Environment
Sources/SettingEnvironment.swift - Search Results · Collects and filters setting-tree results, including no-results handling.
Sources/SettingSearchResult.swift - Styles & Modifiers · Applies library styling alongside native SwiftUI modifiers.
Sources/SettingStyles.swift
Other components
- Swift Package · Publishes the Setting library product.
Package.swift - SwiftUI & AppStorage · Native UI framework and persistence facilities.
Connections 23
- Swift Package → Setting DSL: ships
- Consumer SwiftUI App → SettingStack: roots UI in
- Consumer SwiftUI App → Setting DSL: declares
- Example App Root → Example Settings: hosts
- Example Settings → SettingStack: uses
- Example Settings → Setting DSL: declares
- Setting DSL → Tuple Composition: composes
- DSL Extensions & Modifiers → Setting DSL: extends
- Setting DSL → SettingStack: supplies content
- SettingStack → Pages & Groups: presents hierarchy
- Pages & Groups → SettingPath: uses identity
- Pages & Groups → SettingView: renders through
- SettingStack → SettingViewModel: injects
- SettingViewModel → Setting Environment: propagates via
- Setting DSL → Search Results: collects searchable nodes
- SettingViewModel → Search Results: filters with search text
- Search Results → SettingView: drives results rendering
- SettingView → Bound Controls: renders
- SettingView → Custom Setting View: embeds
- Styles & Modifiers → SettingView: configures appearance
- Visual Primitives → SettingView: supports
- Bound Controls → SwiftUI & AppStorage: uses bindings
- Consumer SwiftUI App → SwiftUI & AppStorage: owns state and persistence