initial proj

Author: elmetal

.github/workflows/deploy_docc.yml

@@ -0,0 +1,51 @@
+name: Deploy DocC
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - README.md
+      - .gitignore
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: macos-14
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_15.4.app/Contents/Developer
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build DocC
+        run: |
+          $(xcrun --find docc) convert \
+            --transform-for-static-hosting \
+            --hosting-base-path "" \
+            --output-path ./docs \
+            Sources/SwiftUIViewCodingGuidelines/Guidelines.docc
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: "https://cybozu.github.io/swiftui-view-coding-guidelines/documentation/swiftuiviewcodingguidelines/"
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -27,7 +27,7 @@ playground.xcworkspace
 #
 # Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
 # hence it is not needed unless you have added a package configuration file to your project
-# .swiftpm
+.swiftpm
 
 .build/
 

Package.swift

@@ -0,0 +1,24 @@
+// swift-tools-version: 5.10
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SwiftUIViewCodingGuidelines",
+    products: [
+        // Products define the executables and libraries a package produces, making them visible to other packages.
+        .library(
+            name: "SwiftUIViewCodingGuidelines",
+            targets: ["SwiftUIViewCodingGuidelines"]),
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .target(
+            name: "SwiftUIViewCodingGuidelines"),
+        .testTarget(
+            name: "SwiftUIViewCodingGuidelinesTests",
+            dependencies: ["SwiftUIViewCodingGuidelines"]
+        ),
+    ]
+)

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/AssignUniqueValueToForEachID.md

@@ -0,0 +1,17 @@
+# ForEachのIDにはuniqueな値を使う
+
+`ForEach`のIDには描画範囲を特定させるためにuniqueな値を使用します。
+
+## Overview
+
+`ForEach`のIDは繰り返しのうちどの要素であるかを特定するために利用されるView Identityです。  
+IDが変化すると値の変化の有無にかかわらず描画がアップデートされます。  
+適切なIDを与えることで不要な描画アップデートを防ぎ、良いパフォーマンスのViewを作成できます。
+
+### IDの有効期間
+IDにはViewのライフタイムより長い有効期間を持つuniqueな値を使用します。  
+例えば表示に用いるデータのArrayのindexはuniqueですが、先頭への要素の追加などの操作によって変化するため、Viewのライフタイムより短い有効期間となります。  
+ArrayのindexをIDとして用いると、先頭に要素が追加された場合に全ての要素で描画をアップデートすることとなり、パフォーマンスに悪影響を及ぼします。
+
+## See Also
+- <doc:WhatISViewIdentity>

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/ChangeValueWhenSwitchingStyle.md

@@ -0,0 +1,53 @@
+# Viewのスタイル変更は値の変更で行う
+
+条件によってViewのスタイルを変更する場合は値を変更します。
+
+## Overview
+
+条件によってViewのスタイルを変更する場合、不要な再描画を発生させないよう注意する必要があります。  
+`if`によるView全体の切り替えはコード上で表現される通りView全体が差し替えられます。  
+これは全体を完全に再描画することになり、本来不要な計算コストが発生します。
+
+### 値の変更でスタイルを切り替える
+
+単純なスタイルの変更の場合、三項演算子で値の変更を行います。
+
+```swift
+struct ContentView: View {
+    var body: some View {
+        Text("Hello!")
+            .foregroundStyle(condition ? .teal : .red)
+    }
+}
+```
+
+三項演算子で表現が難しい場合は関数などを用いて値を変更します。
+
+```swift
+enum TrafficSignal {
+    case go
+    case caution
+    case stop
+}
+```
+```swift
+extension TrafficSignal {
+    var lightColor: some ShapeStyle {
+        switch self {
+        case .go:      Color.green
+        case .caution: Color.yellow
+        case .stop:    Color.red
+        }
+    }
+}
+```
+```swift
+struct ContentView: View {
+    @State var signal: TrafficSignal
+
+    var body: some View {
+        Text("Hello!")
+            .foregroundStyle(signal.lightColor)
+    }
+}
+```

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/HideViewWithOpacityWhenAvailable.md

@@ -0,0 +1,31 @@
+# 利用できる時はopacityでViewを隠す
+
+レイアウト上選択できる場合は`.opacity(_:)`でViewを隠します。
+
+## Overview
+
+Viewを条件によって隠す必要がある場合に選択肢が複数あります。  
+`.opacity(_:)`を使うと三項演算子でViewを隠すことができるため、`.hidden()`より効率が良くなります。
+
+```swift
+var body: some View {
+    Text("Hello World")
+        .opacity(condition ? 0 : 1)
+}
+```
+
+> <doc:ChangeValueWhenSwitchingStyle>
+
+ただし、レイアウト上の必要性を考慮して`if`文での切り替えを選択する場合があります。
+
+### 他のViewの配置への影響を考慮する
+`.opacity(_:)`によるViewの削除は、他のViewの配置へ影響を与えません。
+
+例えば、`VStack`の中で`.opacity(_:)`による削除を行なった場合、表示するために確保されたスペースは削除後も確保されたままとなります。  
+ユーザー名とパスワードを入力するフォームでエラーメッセージを出す時に、エラーメッセージの有無で全体のレイアウトを変えない時などに利用します。
+
+また、注文フォームで配送先と請求先に異なる住所を使用することを選択した場合に、2つ目の住所フィールドを表示することもできます。  
+住所欄のようなスクロールが必要なコンテンツには、`if`文を使用してコンテンツが表示されているときだけスペースを確保し、他のコンテンツは表示状態に従って移動するようにします。
+
+
+> [Choosing the right way to hide a view](https://developer.apple.com/tutorials/swiftui-concepts/choosing-the-right-way-to-hide-a-view)

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/ProvidesContainerViewAccessViaProxy.md

@@ -0,0 +1,30 @@
+# Proxyを通じてContent Viewにアクセスする
+
+Container ViewからContent Viewの値を取得したり、Content Viewの操作を行う際はProxyを提供します。
+
+## Overview
+
+Container Viewで任意のコンテンツに対して実行中の値を取得したり、programmaticallyに操作を行いたいことがあります。  
+この時`Proxy`を提供することで利用側は任意のタイミングでアクセスできます。  
+標準では[`GeometryReader`](https://developer.apple.com/documentation/swiftui/geometryreader)や[`ScrollViewReader`](https://developer.apple.com/documentation/swiftui/scrollviewreader)で行われています。
+
+### Proxyを通じてprogrammaticallyにContent Viewを操作する
+
+[WebUI](https://github.com/cybozu/WebUI)の例を見てみましょう。
+
+```swift
+struct ContentView: View {
+    var body: some View {
+        WebViewReader { proxy in
+            WebView()
+                .onAppear {
+                    proxy.load(request: URLRequest(url: URL(string: "https://www.example.com")!))
+                }
+        }
+        .padding()
+    }
+}
+```
+
+`WebView`の`load`をprogrammaticallyに行うために、`proxy`が提供されています。  
+この場合、`WebView`の構築が終わった後に特定のURLを`load`したいので、`onAppear`のタイミングで`load`を発火するために`proxy`を使っています。

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/SelectImplementationOfViewOverlap.md

@@ -0,0 +1,27 @@
+# Viewの重ね合わせの実装を選択する
+
+レイアウトのサイズが決定される状況に応じて、Viewの重ね合わせの実装を選択します。
+
+## Overview
+
+Viewの重ね合わせには`ZStack`と`.overlay`/`.background`を使うことができます。  
+最終的なサイズを含まれる全ての子Viewの集計から決定する場合は、`ZStack`を選択します。
+レイアウトのサイズがビュー1つだけで決まる場合は、modifierを選択します。  
+
+### 重ね合わせにModifierを使う
+例えば、以下のコードは`ProfileDetail`ビューを`Image`ビューに重ね合わせます。
+```swift
+struct ProfileViewWithOverlay: View {
+    var body: some View {
+        VStack {
+            Image("ProfilePicture")
+                .resizable()
+                .aspectRatio(contentMode: .fit)
+                .overlay(ProfileDetail(), alignment: .bottom)
+        }
+    }
+}
+```
+
+## See Also
+- [Building layouts with stack views - Add depth in alternative ways](https://developer.apple.com/documentation/swiftui/building-layouts-with-stack-views#Add-depth-in-alternative-ways)

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/SendViewUpdatesToConsole.md

@@ -0,0 +1,19 @@
+# Viewのアップデートをコンソールに出力する
+
+`._printChanges()`でViewのアップデートをコンソールに出力します。
+
+## Overview
+`Self._printChanges()`を呼び出してViewのアップデートをコンソールに出力できます。
+
+```swift
+var body: some View {
+    let _ = Self._printChanges()
+    // View code 
+}
+```
+
+`._printChanges()`はどのプロパティがビューの更新を引き起こしたかを記録し、その情報をコンソールに送信します。
+
+## See Also
+
+- [Debugging an App Playground using the Console - Understand when and why your views change](https://developer.apple.com/documentation/swift-playgrounds/console-print-debugging#Understand-when-and-why-your-views-change)

Sources/SwiftUIViewCodingGuidelines/Guidelines.docc/Articles/SeparateContentUnavailableCases.md

@@ -0,0 +1,46 @@
+# コンテンツが利用できないケースをメインケースと分離する
+
+コンテンツが利用できないケースをメインのケースとコードブロックごと分離し、可読性を高めます。
+
+## Overview
+
+リストに表示するアイテムが0件になったり、サーバーとの通信エラーで取得できなかったりして表示すべきコンテンツが利用できないことがあります。  
+このようなケースでは`.overlay`と`ContentUnavailableView`を使って主要なケースとコードブロックを分離することで可読性が高まります。
+
+### コンテンツが利用できないケースを分離する
+
+`ContentUnavailableView`のサンプルを見てみましょう。
+
+```swift
+struct ContentView: View {
+    @ObservedObject private var viewModel = ContactsViewModel()
+
+
+    var body: some View {
+        NavigationStack {
+            List {
+                ForEach(viewModel.searchResults) { contact in
+                    NavigationLink {
+                        ContactsView(contact)
+                    } label: {
+                        Text(contact.name)
+                    }
+                }
+            }
+            .navigationTitle("Contacts")
+            .searchable(text: $viewModel.searchText)
+            .overlay {
+                if searchResults.isEmpty {
+                    ContentUnavailableView.search
+                }
+            }
+        }
+    }
+}
+```
+
+ここではリスト上にアイテムが1件以上存在するメインケースと、検索結果が0件だった場合のケースを`.overlay`で分離しています。  
+これによりメインケースのコードブロックではメインケース自身のレイアウトに集中することができます。
+
+また、検索結果が空の場合だけでなく、通信がエラーになるなどコンテンツが利用できない理由が複数存在することも考えられます。  
+その場合でも`.overlay`のブロックでハンドリングに集中することでメインケースのコードブロックの肥大化を防げます。