Complete the layout documentation (#38)

* Complete the layout documentation
* Reorder GitHub actions
---------

Co-authored-by: Christiane Göhring <[email protected]>

.github/workflows/build-all-targets.yml → .github/workflows/code-checks.yml

@@ -1,8 +1,20 @@
-name: "Build all targets"
-run-name: Building all targets
+name: "Code checks"
+run-name: Running code checks
 on: [pull_request]
 jobs:
-  Build:
+  lint:
+    name: Run SwiftLint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: GitHub Action for SwiftLint
+        uses: norio-nomura/[email protected]
+        with:
+          args: --strict
+  build:
+    name: Build all targets
+    needs: lint
     runs-on: macos-14
     steps:
       - name: Print job info
@@ -23,3 +35,12 @@ jobs:
         run: |
           cd Example
           set -o pipefail && xcodebuild -scheme "StreamDeckKitExample App" -destination "platform=iOS Simulator,name=iPad Air (5th generation),OS=latest" -skipMacroValidation | xcpretty
+
+  test:
+    name: Run unit tests
+    runs-on: macos-14
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - name: Test StreamDeckKit
+        run: set -o pipefail && xcodebuild -scheme StreamDeckKit-Package test -destination "platform=iOS Simulator,name=iPhone 15,OS=latest" -skipMacroValidation | xcpretty

Sources/StreamDeckKit/Layout/Environment+Ext.swift

@@ -42,6 +42,9 @@ struct StreamDeckViewContextKey: EnvironmentKey {
 
 public extension EnvironmentValues {
 
+    /// The current context object of the view.
+    ///
+    /// Values depend on the currently rendered view.
     var streamDeckViewContext: StreamDeckViewContext {
         get { self[StreamDeckViewContextKey.self] }
         set { self[StreamDeckViewContextKey.self] = newValue }

Sources/StreamDeckKit/Layout/StreamDeckDialAreaLayout.swift

@@ -27,22 +27,30 @@
 
 import SwiftUI
 
-/// A View that draws the layout of a Stream Deck dial window area (The display above the ).
+/// A View that draws the layout of a dial window area (The display above the rotary encoders) on a Stream Deck +.
 ///
 /// Use this to render the window area of a Stream Deck Plus and handle its events.
-///
-/// The layout depends on the device from the current ``StreamDeckViewContext`` environment.
 public struct StreamDeckDialAreaLayout<Dial: View>: View {
-    /// A handler for rotation events on a rotary encoder(dial).
+    /// A handler for rotation events on a rotary encoder.
     ///
     /// The first parameter is the index of the dial. The second one is the rotation value. Negative values indicate a rotation to the left.
     public typealias DialRotationHandler = @MainActor (Int, Int) -> Void
 
-    /// A handler for press events on a rotary encoder(dial).
+    /// A handler for key-up/down events of a rotary encoder.
     ///
     /// The first parameter is the index of the dial. The second one indicates if the dial is down or not.
     public typealias DialPressHandler = @MainActor (_ index: Int, _ isPressed: Bool) -> Void
+    /// A handler for touch events on the window area.
     public typealias TouchHandler = @MainActor (CGPoint) -> Void
+    /// A handler for fling gestures on the window area.
+    ///
+    /// A fling gesture is a quick swipe-like motion performed by the user. Unlike a regular swipe gesture that tracks the movement of the
+    /// finger, a fling gesture is characterized by a rapid motion without continuous tracking. You will just receive a single event when the
+    /// gesture completes.
+    /// - Parameters:
+    ///   - start: The point where the fling began / where the finger first touched the display.
+    ///   - end: The point where the fling ended / where the finger was lifted from the display.
+    ///   - direction: The direction of the gesture.
     public typealias FlingHandler = @MainActor (_ start: CGPoint, _ end: CGPoint, _ direction: InputEvent.Direction) -> Void
     public typealias DialProvider = @MainActor (_ keyIndex: Int) -> Dial
 
@@ -54,6 +62,13 @@ public struct StreamDeckDialAreaLayout<Dial: View>: View {
     private let fling: FlingHandler?
     @ViewBuilder private let dial: DialProvider
 
+    /// Creates an instance of the view.
+    /// - Parameters:
+    ///   - rotate: A handler for rotation events of a rotary encoder. Values can be positive or negative.
+    ///   - press: A handler for key-up/down events of a rotary encoder.
+    ///   - touch: A handler for touch events on the window area.
+    ///   - fling: A handler for fling gestures on the window area. (See ``FlingHandler``)
+    ///   - dial: The SwiftUI view content to be rendered on the touch display.
     public init(
         rotate: DialRotationHandler? = nil,
         press: DialPressHandler? = nil,
@@ -68,6 +83,13 @@ public struct StreamDeckDialAreaLayout<Dial: View>: View {
         self.dial = dial
     }
 
+    /// Creates an instance of the view.
+    /// - Parameters:
+    ///   - rotate: A handler for rotation events of a rotary encoder. Values can be positive or negative.
+    ///   - press: A handler for key-down events of a rotary encoder.
+    ///   - touch: A handler for touch events on the window area.
+    ///   - fling: A handler for fling gestures on the window area. (See ``FlingHandler``)
+    ///   - dial: The SwiftUI view content to be rendered on the touch display.
     public init(
         rotate: DialRotationHandler? = nil,
         press: @escaping @MainActor (Int) -> Void,

Sources/StreamDeckKit/Layout/StreamDeckDialView.swift

@@ -28,9 +28,18 @@
 import Foundation
 import SwiftUI
 
+/// A view that renders a single Dial element in a ``StreamDeckLayout``.
+///
+/// A dial consists of a rotary encoder that can also be pressed, as well a as portion of the touch display on a Stream Deck +.
+///
+/// ![Dial](dial)
+/// - Note: This should be provided to the `dial`-factory parameter of one of  ``StreamDeckDialAreaLayout``s initializers, to be rendered properly.
 public struct StreamDeckDialView<Content: View>: View {
+    /// A handler for rotation events of the rotary encoder. Values can be positive or negative.
     public typealias DialRotationHandler = @MainActor (Int) -> Void
+    /// A handler for key-up/down events of the rotary encoder.
     public typealias DialPressHandler = @MainActor (Bool) -> Void
+    /// A handler for touch events on the touch area. Coordinates are relative to frame of the dial area.
     public typealias TouchHandler = @MainActor (CGPoint) -> Void
 
     @Environment(\.streamDeckViewContext) private var context
@@ -40,6 +49,12 @@ public struct StreamDeckDialView<Content: View>: View {
     private let touch: TouchHandler?
     @ViewBuilder private let content: @MainActor () -> Content
 
+    /// Creates an instance of the view.
+    /// - Parameters:
+    ///   - rotate: A handler for rotation events of the rotary encoder. Values can be positive or negative.
+    ///   - press: A handler for key-up/down events of the rotary encoder.
+    ///   - touch: A handler for touch events on the touch area. Coordinates are relative to frame of the dial area.
+    ///   - content: The SwiftUI view content to be rendered on the dial area of the touch display.
     public init(
         rotate: DialRotationHandler? = nil,
         press: DialPressHandler? = nil,
@@ -52,6 +67,12 @@ public struct StreamDeckDialView<Content: View>: View {
         self.content = content
     }
 
+    /// Creates an instance of the view.
+    /// - Parameters:
+    ///   - rotate: A handler for rotation events of the rotary encoder. Values can be positive or negative.
+    ///   - press: A handler for key-down events of the rotary encoder.
+    ///   - touch: A handler for touch events on the touch area. Coordinates are relative to frame of the dial area.
+    ///   - content: The SwiftUI view content to be rendered on the dial area of the touch display.
     public init(
         rotate: DialRotationHandler? = nil,
         press: @escaping @MainActor () -> Void,

Sources/StreamDeckKit/Layout/StreamDeckKeypadLayout.swift → Sources/StreamDeckKit/Layout/StreamDeckKeyAreaLayout.swift

@@ -43,6 +43,7 @@ public struct StreamDeckKeyAreaLayout<Key: View>: View {
 
     /// Creates an instance of the view.
     /// - Parameter keyView: A factory function that provides a view for a key.
+    /// To handle actions on keys, use instances ``StreamDeckKeyView``.
     public init(@ViewBuilder keyView: @escaping KeyViewProvider) {
         self.keyView = keyView
     }

Sources/StreamDeckKit/Layout/StreamDeckKeyView.swift

@@ -27,8 +27,12 @@
 
 import SwiftUI
 
+/// A view that renders a single LED key in a ``StreamDeckLayout``.
+///
+/// This should be provided to ``StreamDeckKeyAreaLayout/init(keyView:)`` to be rendered properly.
 public struct StreamDeckKeyView<Content: View>: View {
 
+    /// A handler for key-up/down events of LED keys.
     public typealias KeyAction = @MainActor (_ isPressed: Bool) -> Void
     public typealias ContentProvider = @MainActor () -> Content
 
@@ -37,6 +41,10 @@ public struct StreamDeckKeyView<Content: View>: View {
     let action: KeyAction
     @ViewBuilder let content: ContentProvider
 
+    /// Creates an instance of the view.
+    /// - Parameters:
+    ///   - action: A handler to be called when key-up/down events were triggered.
+    ///   - content: The SwiftUI view content to be rendered on the LED display of the key.
     public init(
         action: @escaping KeyAction,
         @ViewBuilder content: @escaping ContentProvider
@@ -45,6 +53,10 @@ public struct StreamDeckKeyView<Content: View>: View {
         self.content = content
     }
 
+    /// Creates an instance of the view.
+    /// - Parameters:
+    ///   - action: A handler to be called when key-down events were triggered.
+    ///   - content: The SwiftUI view content to be rendered on the LED display of the key.
     public init(
         action: @escaping @MainActor () -> Void,
         @ViewBuilder content: @escaping ContentProvider

Sources/StreamDeckKit/Layout/StreamDeckLayout.swift

@@ -33,8 +33,9 @@ import SwiftUI
 
 /// The basic view to build a layout for Stream Deck from.
 ///
-/// Provide this to the `content` parameter of ``StreamDeckSession/setUp(stateHandler:newDeviceHandler:content:)`` or ``StreamDeck/render(_:)``
-/// to draw a layout  onto a Stream Deck device.
+/// ![A schematic depiction of the Stream Deck layout system](layout)
+///
+/// Provide this to ``StreamDeck/render(_:)`` to draw a layout  onto a Stream Deck device.
 public struct StreamDeckLayout<KeyArea: View, WindowArea: View>: View {
     @Environment(\.streamDeckViewContext) var context
 

Sources/StreamDeckKit/StreamDeckKit.docc/Resources/Images.xcassets/Contents.json

@@ -0,0 +1,6 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

Sources/StreamDeckKit/StreamDeckKit.docc/Resources/Images.xcassets/dial.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images" : [
+    {
+      "filename" : "dial.jpg",
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

Sources/StreamDeckKit/StreamDeckKit.docc/Resources/Images.xcassets/layout.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images" : [
+    {
+      "filename" : "layout.jpg",
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

Sources/StreamDeckKit/StreamDeckKit.docc/Resources/Images.xcassets/logo.imageset/Contents.json

@@ -0,0 +1,21 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "scale" : "1x"
+    },
+    {
+      "filename" : "logo.png",
+      "idiom" : "universal",
+      "scale" : "2x"
+    },
+    {
+      "idiom" : "universal",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

Sources/StreamDeckKit/StreamDeckKit.docc/StreamDeckKit.md

@@ -0,0 +1,24 @@
+# ``StreamDeckKit``
+
+Communicate with a Stream Deck via Swift.
+
+@Metadata {
+    @PageImage(
+        purpose: icon, 
+        source: "logo", 
+        alt: "A technology icon representing the StreamDeckKit framework.")
+    @PageColor(blue)
+}
+
+## Overview
+
+Stream Deck Kit is a Swift Library for controlling physical [Elgato Stream Deck](https://www.elgato.com/stream-deck) devices with an iPadOS app.
+
+See [docs.elgato.com/ipad](https://docs.elgato.com/ipad) for the main documentation.
+
+## Topics
+
+### Essentials
+
+- ``StreamDeckSession``
+- ``StreamDeckLayout``