# aheze/setting architecture

> Architecture diagram of the GitHub repository aheze/setting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aheze/setting
- Repository: https://github.com/aheze/setting

## Overview

#### 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: [`Sources/Setting.swift`](https://github.com/aheze/setting/blob/main/Sources/Setting.swift) (Setting DSL), [`Sources/Views/SettingView.swift`](https://github.com/aheze/setting/blob/main/Sources/Views/SettingView.swift) (SettingView), [`Sources/Views/SettingStack.swift`](https://github.com/aheze/setting/blob/main/Sources/Views/SettingStack.swift) (SettingStack), [`Example/SettingExample/PlaygroundView.swift`](https://github.com/aheze/setting/blob/main/Example/SettingExample/PlaygroundView.swift) (Example Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["Consumer & Example"]
  node_consumer_app["Consumer SwiftUI App<br/>library consumer"]
  node_example_app["Example App Root<br/>SwiftUI app"]
  node_example_compositions["Example Settings<br/>settings compositions"]
end

subgraph group_dsl["Declarative DSL"]
  node_setting_dsl{{"Setting DSL<br/>protocol + result builder<br/>[Setting.swift]"}}
  node_tuple_content["Tuple Composition<br/>aggregate content"]
  node_dsl_adapters["DSL Extensions &amp; Modifiers<br/>DSL adaptation"]
end

subgraph group_presentation["Hierarchy &amp; Rendering"]
  node_setting_stack["SettingStack<br/>panel coordinator<br/>[SettingStack.swift]"]
  node_pages_groups["Pages &amp; Groups<br/>hierarchy views<br/>[SettingPage.swift]"]
  node_setting_path["SettingPath<br/>navigation identity<br/>[SettingPath.swift]"]
  node_setting_view["SettingView<br/>rendering surface<br/>[SettingView.swift]"]
  node_custom_view["Custom Setting View<br/>custom embedding"]
  node_bound_controls["Bound Controls<br/>SwiftUI controls"]
  node_visual_primitives["Visual Primitives<br/>shared UI utilities<br/>[SettingIcon.swift]"]
end

subgraph group_state["State, Search &amp; Style"]
  node_view_model["SettingViewModel<br/>panel state"]
  node_environment["Setting Environment<br/>environment propagation"]
  node_search_results["Search Results<br/>search model"]
  node_styles["Styles &amp; Modifiers<br/>appearance API"]
end

node_package["Swift Package<br/>package manifest<br/>[Package.swift]"]
node_swiftui_platform[("SwiftUI &amp; AppStorage<br/>Apple platform runtime")]

node_package -->|"ships"| node_setting_dsl
node_consumer_app -->|"roots UI in"| node_setting_stack
node_consumer_app -->|"declares"| node_setting_dsl
node_example_app -->|"hosts"| node_example_compositions
node_example_compositions -->|"uses"| node_setting_stack
node_example_compositions -->|"declares"| node_setting_dsl
node_setting_dsl -->|"composes"| node_tuple_content
node_dsl_adapters -->|"extends"| node_setting_dsl
node_setting_dsl -->|"supplies content"| node_setting_stack
node_setting_stack -->|"presents hierarchy"| node_pages_groups
node_pages_groups -->|"uses identity"| node_setting_path
node_pages_groups -->|"renders through"| node_setting_view
node_setting_stack -->|"injects"| node_view_model
node_view_model -->|"propagates via"| node_environment
node_setting_dsl -->|"collects searchable nodes"| node_search_results
node_view_model -->|"filters with search text"| node_search_results
node_search_results -->|"drives results rendering"| node_setting_view
node_setting_view -->|"renders"| node_bound_controls
node_setting_view -->|"embeds"| node_custom_view
node_styles -->|"configures appearance"| node_setting_view
node_visual_primitives -->|"supports"| node_setting_view
node_bound_controls -->|"uses bindings"| node_swiftui_platform
node_consumer_app -->|"owns state and persistence"| node_swiftui_platform

click node_package "https://github.com/aheze/setting/blob/main/Package.swift"
click node_example_app "https://github.com/aheze/setting/blob/main/Example/SettingExample/SettingExampleApp.swift"
click node_example_compositions "https://github.com/aheze/setting/blob/main/Example/SettingExample/PlaygroundView.swift"
click node_setting_dsl "https://github.com/aheze/setting/blob/main/Sources/Setting.swift"
click node_tuple_content "https://github.com/aheze/setting/blob/main/Sources/Views/SettingTupleView.swift"
click node_dsl_adapters "https://github.com/aheze/setting/blob/main/Sources/SettingExtensions.swift"
click node_setting_stack "https://github.com/aheze/setting/blob/main/Sources/Views/SettingStack.swift"
click node_pages_groups "https://github.com/aheze/setting/blob/main/Sources/Views/SettingPage.swift"
click node_setting_path "https://github.com/aheze/setting/blob/main/Sources/SettingPath.swift"
click node_setting_view "https://github.com/aheze/setting/blob/main/Sources/Views/SettingView.swift"
click node_custom_view "https://github.com/aheze/setting/blob/main/Sources/Views/SettingCustomView.swift"
click node_bound_controls "https://github.com/aheze/setting/blob/main/Sources/Views/SettingToggle.swift"
click node_view_model "https://github.com/aheze/setting/blob/main/Sources/SettingViewModel.swift"
click node_environment "https://github.com/aheze/setting/blob/main/Sources/SettingEnvironment.swift"
click node_search_results "https://github.com/aheze/setting/blob/main/Sources/SettingSearchResult.swift"
click node_styles "https://github.com/aheze/setting/blob/main/Sources/SettingStyles.swift"
click node_visual_primitives "https://github.com/aheze/setting/blob/main/Sources/Utilities/SettingIcon.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_consumer_app,node_example_app,node_example_compositions toneBlue
class node_setting_dsl,node_tuple_content,node_dsl_adapters toneAmber
class node_setting_stack,node_pages_groups,node_setting_path,node_setting_view,node_custom_view,node_bound_controls,node_visual_primitives toneMint
class node_view_model,node_environment,node_search_results,node_styles toneRose
class node_package,node_swiftui_platform toneNeutral
```

## Components

### Consumer & Example

- **Consumer SwiftUI App**: library consumer · Imports Setting and owns bindings and persisted values.
- [Example App Root](https://github.com/aheze/setting/blob/main/Example/SettingExample/SettingExampleApp.swift): SwiftUI app · Runnable integration entry point. · `Example/SettingExample/SettingExampleApp.swift`
- [Example Settings](https://github.com/aheze/setting/blob/main/Example/SettingExample/PlaygroundView.swift): settings compositions · `Example/SettingExample/PlaygroundView.swift`

### Declarative DSL

- [Setting DSL](https://github.com/aheze/setting/blob/main/Sources/Setting.swift): protocol + result builder · Converts declarative setting content into library nodes. · `Sources/Setting.swift`
- [Tuple Composition](https://github.com/aheze/setting/blob/main/Sources/Views/SettingTupleView.swift): aggregate content · Handles multi-child and conditional DSL content. · `Sources/Views/SettingTupleView.swift`
- [DSL Extensions & Modifiers](https://github.com/aheze/setting/blob/main/Sources/SettingExtensions.swift): DSL adaptation · `Sources/SettingExtensions.swift`

### Hierarchy & Rendering

- [SettingStack](https://github.com/aheze/setting/blob/main/Sources/Views/SettingStack.swift): panel coordinator · Top-level presentation and state-injection boundary. · `Sources/Views/SettingStack.swift`
- [Pages & Groups](https://github.com/aheze/setting/blob/main/Sources/Views/SettingPage.swift): hierarchy views · Pages create navigation; groups organize rows and headers. · `Sources/Views/SettingPage.swift`
- [SettingPath](https://github.com/aheze/setting/blob/main/Sources/SettingPath.swift): navigation identity · Carries page navigation identity through the hierarchy. · `Sources/SettingPath.swift`
- [SettingView](https://github.com/aheze/setting/blob/main/Sources/Views/SettingView.swift): rendering surface · Renders declared setting nodes as SwiftUI rows and pages. · `Sources/Views/SettingView.swift`
- [Custom Setting View](https://github.com/aheze/setting/blob/main/Sources/Views/SettingCustomView.swift): custom embedding · `Sources/Views/SettingCustomView.swift`
- [Bound Controls](https://github.com/aheze/setting/blob/main/Sources/Views/SettingToggle.swift): SwiftUI controls · Toggle, picker, and slider bind directly to consumer-owned state. · `Sources/Views/SettingToggle.swift`
- [Visual Primitives](https://github.com/aheze/setting/blob/main/Sources/Utilities/SettingIcon.swift): shared UI utilities · Icons, divided stacks, and page jump links. · `Sources/Utilities/SettingIcon.swift`

### State, Search & Style

- [SettingViewModel](https://github.com/aheze/setting/blob/main/Sources/SettingViewModel.swift): panel state · Owns mutable panel state including search text and customization. · `Sources/SettingViewModel.swift`
- [Setting Environment](https://github.com/aheze/setting/blob/main/Sources/SettingEnvironment.swift): environment propagation · `Sources/SettingEnvironment.swift`
- [Search Results](https://github.com/aheze/setting/blob/main/Sources/SettingSearchResult.swift): search model · Collects and filters setting-tree results, including no-results handling. · `Sources/SettingSearchResult.swift`
- [Styles & Modifiers](https://github.com/aheze/setting/blob/main/Sources/SettingStyles.swift): appearance API · Applies library styling alongside native SwiftUI modifiers. · `Sources/SettingStyles.swift`

### Other components

- [Swift Package](https://github.com/aheze/setting/blob/main/Package.swift): package manifest · Publishes the Setting library product. · `Package.swift`
- **SwiftUI & AppStorage**: Apple platform runtime · Native UI framework and persistence facilities.

## Connections

- 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