Remove inconsistent top-level document helpers (#161)

* Remove inconsistent document-scoped helpers

* Add changelog entry

* Formatting fixes

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`.

lib/src/helpers.dart

@@ -35,21 +35,58 @@ 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;
   if (height != null) result.height = 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;
 
 @JS('Audio')
 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);