From 4a7748ad6bc49ff27ca9fba3d026fe3f3adcba15 Mon Sep 17 00:00:00 2001
From: Carson Katri <Carson.katri@gmail.com>
Date: Wed, 7 Jul 2021 18:09:13 -0400
Subject: [PATCH] Add `Material` to the HTML renderer (#418)

---
 .../Modifiers/StyleModifiers.swift            |  34 ++++++-
 .../Shapes/ShapeStyles/BackgroundStyle.swift  |  79 ++++++++++++++++
 .../Shapes/ShapeStyles/ForegroundStyle.swift  |  53 +++++++++++
 .../Shapes/ShapeStyles/Material.swift         |  57 ++++++++++++
 .../Shapes/ShapeStyles/ShapeStyle.swift       |  58 +-----------
 Sources/TokamakDOM/Core.swift                 |   3 +
 Sources/TokamakDemo/ShapeStyleDemo.swift      |  85 ++++++++++++++----
 Sources/TokamakStaticHTML/Core.swift          |   4 +-
 .../Modifiers/ViewModifier.swift              |   7 --
 .../Modifiers/_BackgroundShapeModifier.swift  |  24 +++++
 .../Modifiers/_BackgroundStyleModifier.swift  |  57 ++++++++++++
 .../RenderingTests.swift                      |  23 +++++
 .../RenderingTests/testMaterial.1.png         | Bin 0 -> 8097 bytes
 13 files changed, 400 insertions(+), 84 deletions(-)
 create mode 100644 Sources/TokamakCore/Shapes/ShapeStyles/BackgroundStyle.swift
 create mode 100644 Sources/TokamakCore/Shapes/ShapeStyles/Material.swift
 create mode 100644 Sources/TokamakStaticHTML/Modifiers/_BackgroundShapeModifier.swift
 create mode 100644 Sources/TokamakStaticHTML/Modifiers/_BackgroundStyleModifier.swift
 create mode 100644 Tests/TokamakStaticHTMLTests/__Snapshots__/RenderingTests/testMaterial.1.png

diff --git a/Sources/TokamakCore/Modifiers/StyleModifiers.swift b/Sources/TokamakCore/Modifiers/StyleModifiers.swift
index d2271a887..7d691a1b5 100644
--- a/Sources/TokamakCore/Modifiers/StyleModifiers.swift
+++ b/Sources/TokamakCore/Modifiers/StyleModifiers.swift
@@ -66,16 +66,42 @@ public extension View {
   ) -> some View where V: View {
     background(content(), alignment: alignment)
   }
+}
+
+@frozen public struct _BackgroundShapeModifier<Style, Bounds>: ViewModifier, EnvironmentReader
+  where Style: ShapeStyle, Bounds: Shape
+{
+  public var environment: EnvironmentValues!
+
+  public var style: Style
+  public var shape: Bounds
+  public var fillStyle: FillStyle
 
+  @inlinable
+  public init(style: Style, shape: Bounds, fillStyle: FillStyle) {
+    self.style = style
+    self.shape = shape
+    self.fillStyle = fillStyle
+  }
+
+  public func body(content: Content) -> some View {
+    content
+      .background(shape.fill(style, style: fillStyle))
+  }
+
+  public mutating func setContent(from values: EnvironmentValues) {
+    environment = values
+  }
+}
+
+public extension View {
   @inlinable
   func background<S, T>(
     _ style: S,
     in shape: T,
     fillStyle: FillStyle = FillStyle()
   ) -> some View where S: ShapeStyle, T: Shape {
-    background {
-      shape.fill(style, style: fillStyle)
-    }
+    modifier(_BackgroundShapeModifier(style: style, shape: shape, fillStyle: fillStyle))
   }
 
   @inlinable
@@ -83,7 +109,7 @@ public extension View {
     in shape: S,
     fillStyle: FillStyle = FillStyle()
   ) -> some View where S: Shape {
-    background(ForegroundStyle(), in: shape, fillStyle: fillStyle)
+    background(BackgroundStyle(), in: shape, fillStyle: fillStyle)
   }
 }
 
diff --git a/Sources/TokamakCore/Shapes/ShapeStyles/BackgroundStyle.swift b/Sources/TokamakCore/Shapes/ShapeStyles/BackgroundStyle.swift
new file mode 100644
index 000000000..c2dd4fe7a
--- /dev/null
+++ b/Sources/TokamakCore/Shapes/ShapeStyles/BackgroundStyle.swift
@@ -0,0 +1,79 @@
+// Copyright 2020-2021 Tokamak contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//  Created by Carson Katri on 7/6/21.
+//
+
+public struct BackgroundStyle: ShapeStyle {
+  public init() {}
+
+  public func _apply(to shape: inout _ShapeStyle_Shape) {
+    if let backgroundStyle = shape.environment._backgroundStyle {
+      backgroundStyle._apply(to: &shape)
+    } else {
+      shape.result = .none
+    }
+  }
+
+  public static func _apply(to shape: inout _ShapeStyle_ShapeType) {}
+}
+
+extension EnvironmentValues {
+  private struct BackgroundStyleKey: EnvironmentKey {
+    static let defaultValue: AnyShapeStyle? = nil
+  }
+
+  public var _backgroundStyle: AnyShapeStyle? {
+    get {
+      self[BackgroundStyleKey.self]
+    }
+    set {
+      self[BackgroundStyleKey.self] = newValue
+    }
+  }
+}
+
+public extension View {
+  @inlinable
+  func background() -> some View {
+    modifier(_BackgroundStyleModifier(style: BackgroundStyle()))
+  }
+
+  @inlinable
+  func background<S>(_ style: S) -> some View where S: ShapeStyle {
+    modifier(_BackgroundStyleModifier(style: style))
+  }
+}
+
+@frozen public struct _BackgroundStyleModifier<Style>: ViewModifier, EnvironmentModifier,
+  EnvironmentReader
+  where Style: ShapeStyle
+{
+  public var environment: EnvironmentValues!
+  public var style: Style
+
+  @inlinable
+  public init(style: Style) {
+    self.style = style
+  }
+
+  public typealias Body = Never
+  public mutating func setContent(from values: EnvironmentValues) {
+    environment = values
+  }
+
+  public func modifyEnvironment(_ values: inout EnvironmentValues) {
+    values._backgroundStyle = .init(styles: [style, style, style], environment: values)
+  }
+}
diff --git a/Sources/TokamakCore/Shapes/ShapeStyles/ForegroundStyle.swift b/Sources/TokamakCore/Shapes/ShapeStyles/ForegroundStyle.swift
index 8efcfb13b..892489bb8 100644
--- a/Sources/TokamakCore/Shapes/ShapeStyles/ForegroundStyle.swift
+++ b/Sources/TokamakCore/Shapes/ShapeStyles/ForegroundStyle.swift
@@ -28,3 +28,56 @@ public struct ForegroundStyle: ShapeStyle {
 
   public static func _apply(to shape: inout _ShapeStyle_ShapeType) {}
 }
+
+extension EnvironmentValues {
+  private struct ForegroundStyleKey: EnvironmentKey {
+    static let defaultValue: AnyShapeStyle? = nil
+  }
+
+  public var _foregroundStyle: AnyShapeStyle? {
+    get {
+      self[ForegroundStyleKey.self]
+    }
+    set {
+      self[ForegroundStyleKey.self] = newValue
+    }
+  }
+}
+
+public extension View {
+  @inlinable
+  func foregroundStyle<S>(_ style: S) -> some View
+    where S: ShapeStyle
+  {
+    foregroundStyle(style, style, style)
+  }
+
+  @inlinable
+  func foregroundStyle<S1, S2>(_ primary: S1, _ secondary: S2) -> some View
+    where S1: ShapeStyle, S2: ShapeStyle
+  {
+    foregroundStyle(primary, secondary, secondary)
+  }
+
+  @inlinable
+  func foregroundStyle<S1, S2, S3>(_ primary: S1, _ secondary: S2,
+                                   _ tertiary: S3) -> some View
+    where S1: ShapeStyle, S2: ShapeStyle, S3: ShapeStyle
+  {
+    modifier(_ForegroundStyleModifier(styles: [primary, secondary, tertiary]))
+  }
+}
+
+@frozen public struct _ForegroundStyleModifier: ViewModifier, EnvironmentModifier {
+  public var styles: [ShapeStyle]
+
+  @inlinable
+  public init(styles: [ShapeStyle]) {
+    self.styles = styles
+  }
+
+  public typealias Body = Never
+  public func modifyEnvironment(_ values: inout EnvironmentValues) {
+    values._foregroundStyle = .init(styles: styles, environment: values)
+  }
+}
diff --git a/Sources/TokamakCore/Shapes/ShapeStyles/Material.swift b/Sources/TokamakCore/Shapes/ShapeStyles/Material.swift
new file mode 100644
index 000000000..75cf279b3
--- /dev/null
+++ b/Sources/TokamakCore/Shapes/ShapeStyles/Material.swift
@@ -0,0 +1,57 @@
+// Copyright 2020-2021 Tokamak contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//  Created by Carson Katri on 7/6/21.
+//
+
+public struct Material {
+  private let style: _MaterialStyle
+
+  private init(_ style: _MaterialStyle) {
+    self.style = style
+  }
+
+  public static let regular = Self(.regular)
+  public static let thick = Self(.thick)
+  public static let thin = Self(.thin)
+  public static let ultraThin = Self(.ultraThin)
+  public static let ultraThick = Self(.ultraThick)
+}
+
+public enum _MaterialStyle {
+  case regular
+  case thick
+  case thin
+  case ultraThin
+  case ultraThick
+}
+
+extension Material: ShapeStyle {
+  public func _apply(to shape: inout _ShapeStyle_Shape) {
+    shape.result = .resolved(
+      .foregroundMaterial(
+        _ColorProxy(Color._withScheme {
+          $0 == .light ? Color.white : Color.black
+        }).resolve(in: shape.environment),
+        style
+      )
+    )
+  }
+
+  public static func _apply(to shape: inout _ShapeStyle_ShapeType) {}
+}
+
+public extension Material {
+  static let bar = Self.regular
+}
diff --git a/Sources/TokamakCore/Shapes/ShapeStyles/ShapeStyle.swift b/Sources/TokamakCore/Shapes/ShapeStyles/ShapeStyle.swift
index b50ef276b..43e49e743 100644
--- a/Sources/TokamakCore/Shapes/ShapeStyles/ShapeStyle.swift
+++ b/Sources/TokamakCore/Shapes/ShapeStyles/ShapeStyle.swift
@@ -127,8 +127,7 @@ public struct _ShapeStyle_ShapeType {}
 public indirect enum _ResolvedStyle {
   case color(AnyColorBox.ResolvedValue)
 //  case paint(AnyResolvedPaint) // I think is used for Image as a ShapeStyle (SwiftUI.ImagePaint).
-  // TODO: Material
-//  case foregroundMaterial(AnyColorBox.ResolvedValue, MaterialStyle)
+  case foregroundMaterial(AnyColorBox.ResolvedValue, _MaterialStyle)
 //  case backgroundMaterial(AnyColorBox.ResolvedValue)
   case array([_ResolvedStyle])
   case opacity(Float, _ResolvedStyle)
@@ -138,6 +137,8 @@ public indirect enum _ResolvedStyle {
     switch self {
     case let .color(resolved):
       return Color(_ConcreteColorBox(resolved))
+    case let .foregroundMaterial(resolved, _):
+      return Color(_ConcreteColorBox(resolved))
     case let .array(children):
       return children[level].color(at: level)
     case let .opacity(opacity, resolved):
@@ -146,56 +147,3 @@ public indirect enum _ResolvedStyle {
     }
   }
 }
-
-extension EnvironmentValues {
-  private struct ForegroundStyleKey: EnvironmentKey {
-    static let defaultValue: AnyShapeStyle? = nil
-  }
-
-  public var _foregroundStyle: AnyShapeStyle? {
-    get {
-      self[ForegroundStyleKey.self]
-    }
-    set {
-      self[ForegroundStyleKey.self] = newValue
-    }
-  }
-}
-
-public extension View {
-  @inlinable
-  func foregroundStyle<S>(_ style: S) -> some View
-    where S: ShapeStyle
-  {
-    foregroundStyle(style, style, style)
-  }
-
-  @inlinable
-  func foregroundStyle<S1, S2>(_ primary: S1, _ secondary: S2) -> some View
-    where S1: ShapeStyle, S2: ShapeStyle
-  {
-    foregroundStyle(primary, secondary, secondary)
-  }
-
-  @inlinable
-  func foregroundStyle<S1, S2, S3>(_ primary: S1, _ secondary: S2,
-                                   _ tertiary: S3) -> some View
-    where S1: ShapeStyle, S2: ShapeStyle, S3: ShapeStyle
-  {
-    modifier(_ForegroundStyleModifier(styles: [primary, secondary, tertiary]))
-  }
-}
-
-@frozen public struct _ForegroundStyleModifier: ViewModifier, EnvironmentModifier {
-  public var styles: [ShapeStyle]
-
-  @inlinable
-  public init(styles: [ShapeStyle]) {
-    self.styles = styles
-  }
-
-  public typealias Body = Never
-  public func modifyEnvironment(_ values: inout EnvironmentValues) {
-    values._foregroundStyle = .init(styles: styles, environment: values)
-  }
-}
diff --git a/Sources/TokamakDOM/Core.swift b/Sources/TokamakDOM/Core.swift
index 09b505b8a..d061a3c32 100644
--- a/Sources/TokamakDOM/Core.swift
+++ b/Sources/TokamakDOM/Core.swift
@@ -83,6 +83,9 @@ public typealias Rectangle = TokamakCore.Rectangle
 public typealias RoundedRectangle = TokamakCore.RoundedRectangle
 public typealias ContainerRelativeShape = TokamakCore.ContainerRelativeShape
 
+public typealias ForegroundStyle = TokamakCore.ForegroundStyle
+public typealias Material = TokamakCore.Material
+
 // MARK: Primitive values
 
 public typealias Color = TokamakCore.Color
diff --git a/Sources/TokamakDemo/ShapeStyleDemo.swift b/Sources/TokamakDemo/ShapeStyleDemo.swift
index ec7e43533..af4ac7a2d 100644
--- a/Sources/TokamakDemo/ShapeStyleDemo.swift
+++ b/Sources/TokamakDemo/ShapeStyleDemo.swift
@@ -18,25 +18,76 @@ import TokamakShim
 struct ShapeStyleDemo: View {
   var body: some View {
     #if compiler(>=5.5) || os(WASI)
-    HStack {
-      VStack {
-        Text("Red Style")
-        Rectangle()
-          .frame(width: 25, height: 25)
+    VStack {
+      HStack {
+        VStack {
+          Text("Red Style")
+          Rectangle()
+            .frame(width: 50, height: 50)
+        }
+        .foregroundStyle(Color.red)
+        VStack {
+          Text("Green Style")
+          Rectangle()
+            .frame(width: 25, height: 25)
+        }
+        .foregroundStyle(Color.green)
+        VStack {
+          Text("Blue Style")
+          Rectangle()
+            .frame(width: 25, height: 25)
+        }
+        .foregroundStyle(Color.blue)
       }
-      .foregroundStyle(Color.red)
-      VStack {
-        Text("Green Style")
-        Rectangle()
-          .frame(width: 25, height: 25)
+      ZStack {
+        HStack(spacing: 0) {
+          Rectangle()
+            .foregroundStyle(Color.red)
+            .frame(width: 60, height: 100)
+          Rectangle()
+            .foregroundStyle(Color.orange)
+            .frame(width: 60, height: 100)
+          Rectangle()
+            .foregroundStyle(Color.yellow)
+            .frame(width: 60, height: 100)
+          Rectangle()
+            .foregroundStyle(Color.green)
+            .frame(width: 60, height: 100)
+          Rectangle()
+            .foregroundStyle(Color.blue)
+            .frame(width: 60, height: 100)
+          Rectangle()
+            .foregroundStyle(Color.purple)
+            .frame(width: 60, height: 100)
+        }
+        VStack(spacing: 0) {
+          HStack {
+            Text("Ultra Thin")
+            Spacer()
+          }
+          .background(Material.ultraThin)
+          HStack {
+            Text("Thin")
+            Spacer()
+          }
+          .background(Material.thin)
+          HStack {
+            Text("Regular")
+            Spacer()
+          }
+          .background(Material.regular)
+          HStack {
+            Text("Thick")
+            Spacer()
+          }
+          .background(Material.thick, in: Rectangle())
+          HStack {
+            Text("Ultra Thick")
+            Spacer()
+          }
+          .background(Material.ultraThick, in: Rectangle())
+        }
       }
-      .foregroundStyle(Color.green)
-      VStack {
-        Text("Blue Style")
-        Rectangle()
-          .frame(width: 25, height: 25)
-      }
-      .foregroundStyle(Color.blue)
     }
     #endif
   }
diff --git a/Sources/TokamakStaticHTML/Core.swift b/Sources/TokamakStaticHTML/Core.swift
index d9e6d3de5..1b79cf635 100644
--- a/Sources/TokamakStaticHTML/Core.swift
+++ b/Sources/TokamakStaticHTML/Core.swift
@@ -42,9 +42,11 @@ public typealias Ellipse = TokamakCore.Ellipse
 public typealias Path = TokamakCore.Path
 public typealias Rectangle = TokamakCore.Rectangle
 public typealias RoundedRectangle = TokamakCore.RoundedRectangle
-
 public typealias ContainerRelativeShape = TokamakCore.ContainerRelativeShape
 
+public typealias ForegroundStyle = TokamakCore.ForegroundStyle
+public typealias Material = TokamakCore.Material
+
 // MARK: Primitive values
 
 public typealias Color = TokamakCore.Color
diff --git a/Sources/TokamakStaticHTML/Modifiers/ViewModifier.swift b/Sources/TokamakStaticHTML/Modifiers/ViewModifier.swift
index cf5f7dfbf..e4827e7b2 100644
--- a/Sources/TokamakStaticHTML/Modifiers/ViewModifier.swift
+++ b/Sources/TokamakStaticHTML/Modifiers/ViewModifier.swift
@@ -44,10 +44,3 @@ extension _ZIndexModifier: DOMViewModifier {
     ["style": "z-index: \(index);"]
   }
 }
-
-extension _BackgroundModifier: DOMViewModifier where Background == Color {
-  public var isOrderDependent: Bool { true }
-  public var attributes: [HTMLAttribute: String] {
-    ["style": "background-color: \(background.cssValue(environment))"]
-  }
-}
diff --git a/Sources/TokamakStaticHTML/Modifiers/_BackgroundShapeModifier.swift b/Sources/TokamakStaticHTML/Modifiers/_BackgroundShapeModifier.swift
new file mode 100644
index 000000000..e9935e386
--- /dev/null
+++ b/Sources/TokamakStaticHTML/Modifiers/_BackgroundShapeModifier.swift
@@ -0,0 +1,24 @@
+// Copyright 2020 Tokamak contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import TokamakCore
+
+extension _BackgroundShapeModifier: DOMViewModifier where Bounds == Rectangle {
+  public var isOrderDependent: Bool { true }
+  public var attributes: [HTMLAttribute: String] {
+    var backgroundStyleModifier = _BackgroundStyleModifier(style: style)
+    backgroundStyleModifier.environment = environment
+    return backgroundStyleModifier.attributes
+  }
+}
diff --git a/Sources/TokamakStaticHTML/Modifiers/_BackgroundStyleModifier.swift b/Sources/TokamakStaticHTML/Modifiers/_BackgroundStyleModifier.swift
new file mode 100644
index 000000000..a321324c2
--- /dev/null
+++ b/Sources/TokamakStaticHTML/Modifiers/_BackgroundStyleModifier.swift
@@ -0,0 +1,57 @@
+// Copyright 2020 Tokamak contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import TokamakCore
+
+extension _BackgroundStyleModifier: DOMViewModifier {
+  public var isOrderDependent: Bool { true }
+  public var attributes: [HTMLAttribute: String] {
+    if let resolved = style.resolve(
+      for: .resolveStyle(levels: 0..<1),
+      in: environment,
+      role: .fill
+    ) {
+      if case let .foregroundMaterial(rgba, material) = resolved {
+        let blur: (opacity: Double, radius: Double)
+        switch material {
+        case .ultraThin:
+          blur = (0.2, 20)
+        case .thin:
+          blur = (0.4, 25)
+        case .regular:
+          blur = (0.5, 30)
+        case .thick:
+          blur = (0.6, 40)
+        case .ultraThick:
+          blur = (0.6, 50)
+        }
+        return [
+          "style":
+            """
+            background-color: rgba(\(rgba.red * 255), \(rgba.green * 255), \(rgba
+              .blue * 255), \(blur
+              .opacity));
+            -webkit-backdrop-filter: blur(\(blur.radius)px);
+            backdrop-filter: blur(\(blur.radius)px);
+            """,
+        ]
+      } else if let color = resolved.color(at: 0) {
+        return [
+          "style": "background-color: \(color.cssValue(environment))",
+        ]
+      }
+    }
+    return [:]
+  }
+}
diff --git a/Tests/TokamakStaticHTMLTests/RenderingTests.swift b/Tests/TokamakStaticHTMLTests/RenderingTests.swift
index 086da17e6..018940b76 100644
--- a/Tests/TokamakStaticHTMLTests/RenderingTests.swift
+++ b/Tests/TokamakStaticHTMLTests/RenderingTests.swift
@@ -199,6 +199,29 @@ final class RenderingTests: XCTestCase {
       timeout: defaultSnapshotTimeout
     )
   }
+
+  func testMaterial() {
+    assertSnapshot(
+      matching: ZStack {
+        HStack(spacing: 0) {
+          Color.red
+          Color.orange
+          Color.yellow
+          Color.green
+          Color.blue
+          Color.purple
+        }
+        VStack(spacing: 0) {
+          Color.clear
+            .background(Material.ultraThin)
+          Color.clear
+            .background(Material.ultraThick)
+        }
+      },
+      as: .image(size: .init(width: 100, height: 100)),
+      timeout: defaultSnapshotTimeout
+    )
+  }
 }
 
 #endif
diff --git a/Tests/TokamakStaticHTMLTests/__Snapshots__/RenderingTests/testMaterial.1.png b/Tests/TokamakStaticHTMLTests/__Snapshots__/RenderingTests/testMaterial.1.png
new file mode 100644
index 0000000000000000000000000000000000000000..bcba5e93991d53870088c1018b4cd4392e1a3566
GIT binary patch
literal 8097
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

literal 0
HcmV?d00001