From b77a09d8d96a775d57e91de90f3e9475c6ed6487 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Tue, 6 Feb 2024 23:40:04 -0600
Subject: [PATCH 1/3] Remove inconsistent document-scoped helpers

---
 lib/src/helpers.dart | 43 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/lib/src/helpers.dart b/lib/src/helpers.dart
index 2771bf5e..ba78a91b 100644
--- a/lib/src/helpers.dart
+++ b/lib/src/helpers.dart
@@ -35,9 +35,28 @@ export 'helpers/http.dart';
 export 'helpers/lists.dart';
 export 'helpers/renames.dart';
 
-HTMLElement createElementTag(String s) =>
-    document.createElement(s) as HTMLElement;
+/// Create an [HTMLElement] with the specified [tagName].
+/// If no element with [tagName] exists, returns a [HTMLUnknownElement].
+///
+/// Deprecated in favor of creating the element like other HTML elements:
+///
+/// ```dart
+/// final anchor = document.createElement('a') as HTMLElement;
+/// ```
+@Deprecated('Directly use document.createElement instead.')
+HTMLElement createElementTag(String tagName) =>
+    document.createElement(tagName) as HTMLElement;
 
+/// Create an [HTMLCanvasElement] in the current [document].
+///
+/// Deprecated in favor of creating the element like other HTML elements:
+///
+/// ```dart
+/// final canvas = document.createElement('canvas') as HTMLCanvasElement
+///   ..width = 256
+///   ..height = 256;
+/// ```
+@Deprecated('Directly use document.createElement instead.')
 HTMLCanvasElement createCanvasElement({int? width, int? height}) {
   final result = document.createElement('canvas') as HTMLCanvasElement;
   if (width != null) result.width = width;
@@ -45,6 +64,14 @@ HTMLCanvasElement createCanvasElement({int? width, int? height}) {
   return result;
 }
 
+/// Create an [HTMLIFrameElement] in the current [document].
+///
+/// Deprecated in favor of creating the element like other HTML elements:
+///
+/// ```dart
+/// final embed = document.createElement('iframe') as HTMLIFrameElement;
+/// ```
+@Deprecated('Directly use document.createElement instead.')
 HTMLIFrameElement createIFrameElement() =>
     document.createElement('iframe') as HTMLIFrameElement;
 
@@ -52,4 +79,14 @@ HTMLIFrameElement createIFrameElement() =>
 external JSFunction get _audioConstructor;
 HTMLAudioElement createAudioElement() => _audioConstructor.callAsConstructor();
 
-Element? querySelector(String selectors) => document.querySelector(selectors);
+/// Finds and returns the first element within the [document]
+/// that matches the specified CSS [selector] string.
+/// If no match is found, `null` is returned.
+///
+/// Deprecated in favor of querying directly on the [document].
+///
+/// ```dart
+/// final dartDiv = document.querySelector('div.dart');
+/// ```
+@Deprecated('Directly use document.querySelector instead.')
+Element? querySelector(String selector) => document.querySelector(selector);

From 35711fcc48b0dbfd422d7c0ab28ff5b69e13eaba Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Tue, 6 Feb 2024 23:42:44 -0600
Subject: [PATCH 2/3] Add changelog entry

---
 CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d282545d..b4f08ca7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,9 @@
 - Changed `record` types to be `JSObject` instead of `JSAny`.
 - Reduce the number of DOM APIs we generate code for. Currently, the API needs
   to be standards-track, and be suported by Safari, Chrome, and Firefox.
+- Deprecate the top-level `createElementTag`, `createCanvasElement`,
+  `createIFrameElement`, and `querySelector` functions.
+  Instead, use the standard creation and query methods on `document`.
 
 ## 0.4.2
 

From a086eea8194711eaf44e8e03b73f0783b962d4a7 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Tue, 6 Feb 2024 23:44:24 -0600
Subject: [PATCH 3/3] Formatting fixes

---
 lib/src/helpers.dart | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/src/helpers.dart b/lib/src/helpers.dart
index ba78a91b..ce7a4e70 100644
--- a/lib/src/helpers.dart
+++ b/lib/src/helpers.dart
@@ -36,7 +36,7 @@ export 'helpers/lists.dart';
 export 'helpers/renames.dart';
 
 /// Create an [HTMLElement] with the specified [tagName].
-/// If no element with [tagName] exists, returns a [HTMLUnknownElement].
+/// If no element with [tagName] exists, returns an [HTMLUnknownElement].
 ///
 /// Deprecated in favor of creating the element like other HTML elements:
 ///
@@ -83,7 +83,7 @@ HTMLAudioElement createAudioElement() => _audioConstructor.callAsConstructor();
 /// that matches the specified CSS [selector] string.
 /// If no match is found, `null` is returned.
 ///
-/// Deprecated in favor of querying directly on the [document].
+/// Deprecated in favor of querying directly on the [document]:
 ///
 /// ```dart
 /// final dartDiv = document.querySelector('div.dart');