From a35642fafb763f52b97a4d6be273a7a310bcc22e Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Mon, 12 Feb 2024 13:43:32 -0600
Subject: [PATCH] Remove inconsistent top-level document helpers (#161)

* Remove inconsistent document-scoped helpers

* Add changelog entry

* Formatting fixes
---
 CHANGELOG.md         |  4 ++++
 lib/src/helpers.dart | 43 ++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b35606e..8e803d59 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,10 @@
   | `ContextEvent`        | `WebGLContextEvent`     |
   | `WebGL`               | `WebGLRenderingContext` |
 
+- Deprecate the top-level `createElementTag`, `createCanvasElement`,
+  `createIFrameElement`, and `querySelector` functions.
+  Instead, use the standard creation and query methods on `document`.
+
 ## 0.4.2
 
 - Undeprecate some APIs and helpers library that were deprecated in `0.4.1`.
diff --git a/lib/src/helpers.dart b/lib/src/helpers.dart
index 2771bf5e..ce7a4e70 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 an [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);