From b38a178f52ea6a06b2d33fa2a16f7a76ee06b8ce Mon Sep 17 00:00:00 2001
From: Tochukwu Ibe-Ekeocha
 <114026179+tochukwuIbeEkeocha@users.noreply.github.com>
Date: Fri, 1 Nov 2024 11:20:17 -0700
Subject: [PATCH] Update specs/WindowControlsOverlayConfiguration.md

---
 specs/WindowControlsOverlayConfiguration.md | 24 +++++++++++++--------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/specs/WindowControlsOverlayConfiguration.md b/specs/WindowControlsOverlayConfiguration.md
index 19b018f8..a203ffc7 100644
--- a/specs/WindowControlsOverlayConfiguration.md
+++ b/specs/WindowControlsOverlayConfiguration.md
@@ -10,6 +10,10 @@ The overlay Settings lives on the controller object.
 
 This API is designed to be used in addition with the other non-client region APIs 
 and features. These include `app-region: drag`, and `IsNonClientRegionSupportEnabled`.
+
+# Conceptual pages (How To)
+Here is a concept doc on the window controls overlay: https://wicg.github.io/window-controls-overlay/#concepts. This was written for the PWA counterpart  for this feature. From the perspective of HTML & Javascript layers, everything there applies in Webview2 as well.
+
 # Examples
 
 ## Win32 C++
@@ -30,12 +34,12 @@ void  AppWindow::OnCreateWebview2ControllerCompleted(HRESULT hr, ICoreWebview2Co
     wil::com_ptr<ICoreWebView2Controller5> controller5;
     CHECK_FAILURE(controller->QueryInterface(&controller5));
 
-    wil::com_ptr<ICoreWebView2WindowControlsOverlaySettings> wco_config;
+    wil::com_ptr<ICoreWebView2WindowControlsOverlaySettings> windowControlsOverlaySettings;
     CHECK_FAILURE(controller5->get_WindowControlsOverlaySettings(&wco_config));
 
-    wco_config->put_IsEnabled(true);
+    CHECK_FAILURE(wco_config->put_IsEnabled(true));
     COREWEBVIEW2_COLOR color {1, 0, 0, 225};
-    wco_config->put_TitleBarColor(color);
+    CHECK_FAILURE(wco_config->put_TitleBarBackgroundColor(color));
 }
 ```
 ## .NET C#
@@ -97,7 +101,8 @@ interface ICoreWebView2WindowControlsOverlaySettings : IUnknown {
   /// 
   /// The Overlay buttons will sit on top of the HTML content, and will prevent mouse interactions
   /// with any elements directly below it, so you should avoid placing content there. 
-  /// To that end, there are four CSS environment vairables defined to help you 
+  /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) 
+  /// titlebar-area-x, titlebar-area-y, titlebar-area-width defined to help you 
   /// get the dimensions of the available titlebar area to the left of the overlay.
   /// Similarly the navigator object wil contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay)
   /// which can be used to get the titlebar area as a rect, and listen for changes
@@ -105,14 +110,14 @@ interface ICoreWebView2WindowControlsOverlaySettings : IUnknown {
   ///
   [propput] HRESULT IsEnabled([in] BOOL value);
 
-  /// Gets the `TitleBarColor` property.
-  [propget] HRESULT TitleBarColor([out, retval] COREWEBVIEW2_COLOR* value);
+  /// Gets the `TitleBarBackgroundColor` property.
+  [propget] HRESULT TitleBarBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value);
 
-  /// The `TitleBarColor` property allows you to set a background color
+  /// The `TitleBarBackgroundColor` property allows you to set a background color
   /// for the overlay. Based on the background color you choose, Webview2 
   ///will automatically calculate a foreground and hover color that will
   /// provide you the best contrast while maintaining accessibility.
-  /// Defaults to #f3f3f3
+  /// Defaults to #f3f3f3. This API supports transparency.
   [propput] HRESULT TitleBarBackgroundColor([in] COREWEBVIEW2_COLOR value);
 }
 ```
@@ -135,8 +140,9 @@ namespace Microsoft.Web.WebView2.Core
         {
             Boolean IsEnabled { get; set; };
             UInt32 Height { get; set; };
-            Windows.UI.Color TitleBarColor { get; set; }
+            Windows.UI.Color TitleBarBackgroundColor { get; set; }
         }
     }
 }
 ```
+