schultek · schultek · Jan 12, 2025 · Jan 5, 2025 · Jan 7, 2025 · Jan 10, 2025
@@ -98,6 +98,7 @@
         {"title": "SyncStateMixin", "href": "/utils/sync_state_mixin"},
         {"title": "PreloadStateMixin", "href": "/utils/preload_state_mixin"},
         {"title": "@encoder/@decoder", "href": "/utils/at_encoder_decoder"},
+        {"title": "GlobalNodeKey", "href": "/utils/global_node_key"},
         {"title": "@Import", "href": "/utils/at_import"},
         {"title": "ViewTransitionMixin", "href": "/utils/view_transition_mixin"}
       ]

@@ -12,6 +12,10 @@ is only supported on one side, e.g.:
 - `dart:html` is only supported on the client,
 - `dart:io` is only supported on the server.
 
+<Info>
+When using `package:web` you should instead use `package:universal_web` which already works across web **and server** environments. No need to use conditional imports or the `@Import` annotation shown on this page.
+</Info>
+
 When you want to use such a library in your project, you would have to resort to *conditional imports*, 
 which are quite cumbersome to use since you have to create multiple files and stub everything you want to use.
 

@@ -0,0 +1,26 @@
+---
+title: "GlobalNodeKey"
+description: Get access to the unterlying dom node of a component.
+---
+
+---
+
+For accessing the underlying DOM node of a component, provide a `GlobalNodeKey` to the component and access the node using `myGlobalNodeKey.currentNode`.
+
+```dart
+// 1. Import universal_web
+import 'package:universal_web/web.dart';
+
+// 2. Create a GlobalNodeKey with a node type
+final GlobalNodeKey<HTMLFormElement> myFormKey = GlobalNodeKey();
+
+// 3. Provide to a html component
+yield form(key: myFormKey, [ ... ]);
+
+// 4. Access dom node from key
+myFormKey.currentNode?.checkValidity();
+```
+
+<Info>
+The `universal_web` package is a drop-in replacement for the `web` package that adds compatability for non-web platforms. Therefore its safe to use in components that are both rendered on the server and client.
+</Info>
@@ -1,5 +1,34 @@
-## Unreleased patch
+## Unreleased minor
 
+
+- **BREAKING** Removed `currentState` from `GlobalKey`, use `GlobalStateKey` instead.
+- Added `GlobalStateKey<T extends State>` to access the state of a component using `currentState`.
+
+  ```dart
+  // Use any State type as the type parameter.
+  final GlobalStateKey<MyComponentState> myComponentKey = GlobalStateKey();
+
+  /* ... */
+
+  // Access the state from the key.
+  MyComponentState? state = myComponentKey.currentState;
+  ```
+
+- Added `GlobalNodeKey<T extends Node>` to access native dom nodes using `currentNode`.
+
+  ```dart
+  import 'package:universal_web/web.dart';
+
+  // Use any Node type (from package:universal_web) as the type parameter.
+  final GlobalNodeKey<HTMLFormElement> myFormKey = GlobalNodeKey();
+
+  /* ... */
+
+  // Access the dom node from the key.
+  HTMLFormElement? node = myFormKey.currentNode;
+  ```
+
+- Migrated all web imports from `package:web` to `package:universal_web`.
 - Added `prefersColorScheme` parameter to `MediaQuery`.
 
 ## 0.16.4

@@ -13,7 +13,7 @@ export 'src/foundation/basic_types.dart';
 export 'src/foundation/binding.dart';
 export 'src/foundation/change_notifier.dart';
 export 'src/foundation/constants.dart';
-export 'src/foundation/events/events.dart';
+export 'src/foundation/events.dart';
 export 'src/foundation/object.dart';
 export 'src/foundation/options.dart';
 export 'src/foundation/scheduler.dart';

@@ -1,6 +1,6 @@
 import 'dart:async';
 
-import 'package:web/web.dart';
+import 'package:universal_web/web.dart';
 
 import '../foundation/basic_types.dart';
 import '../foundation/binding.dart';

@@ -1,7 +1,7 @@
 import 'dart:async';
 import 'dart:convert';
 
-import 'package:web/web.dart' as web;
+import 'package:universal_web/web.dart' as web;
 
 import '../foundation/marker_utils.dart';
 import '../framework/framework.dart';

@@ -1,10 +1,10 @@
 import 'dart:async';
 import 'dart:js_interop';
 
-import 'package:web/web.dart' as web;
+import 'package:universal_web/web.dart' as web;
 
 import '../foundation/constants.dart';
-import '../foundation/events/events.dart';
+import '../foundation/events.dart';
 import '../framework/framework.dart';
 import 'utils.dart';
 
@@ -15,7 +15,9 @@ const xmlns = {
 };
 
 class DomRenderObject extends RenderObject {
+  @override
   web.Node? node;
+
   List<web.Node> toHydrate = [];
 
   Map<String, EventBinding>? events;

@@ -1,4 +1,4 @@
-import 'package:web/web.dart' as web;
+import 'package:universal_web/web.dart' as web;
 
 extension NodeListIterable on web.NodeList {
   Iterable<web.Node> toIterable() sync* {

@@ -1,6 +1,6 @@
 import 'dart:js_interop';
 
-import 'package:web/web.dart' as web;
+import 'package:universal_web/web.dart' as web;
 
 import '../../../browser.dart';
 import '../../browser/utils.dart';

@@ -111,8 +111,12 @@ abstract class Document implements Component {
   }) = AttachDocument.body;
 }
 
-// only allow a single document
-const _documentKey = GlobalKey();
+// Only allow a single Document.
+const _documentKey = _DocumentKey();
+
+class _DocumentKey extends GlobalKey {
+  const _DocumentKey() : super.constructor();
+}
 
 class BaseDocument extends StatelessComponent implements Document {
   const BaseDocument({

@@ -1,5 +1,5 @@
 import '../../foundation/basic_types.dart';
-import '../../foundation/events/events.dart';
+import '../../foundation/events.dart';
 import '../../foundation/styles/styles.dart';
 import '../../framework/framework.dart';
 import '../raw_text/raw_text.dart';

@@ -1,6 +1,6 @@
 import 'dart:js_interop';
 
-import 'package:web/web.dart' as web;
+import 'package:universal_web/web.dart' as web;
 
 import '../../../browser.dart';
 import '../../browser/utils.dart';

@@ -1,8 +1,8 @@
-import '../../components/html/html.dart';
-import '../basic_types.dart';
-import 'web.dart' if (dart.library.io) 'web_stub.dart' as web;
+import 'package:universal_web/js_interop.dart';
+import 'package:universal_web/web.dart' as web;
 
-export 'web.dart' if (dart.library.io) 'web_stub.dart' show Event;
+import '../components/html/html.dart';
+import 'basic_types.dart';
 
 typedef EventCallback = void Function(web.Event event);
 typedef EventCallbacks = Map<String, EventCallback>;

@@ -16,3 +16,20 @@
   }());
   return optimizedValue;
 }
+
+/// Returns a 5 character long hexadecimal string generated from
+/// [Object.hashCode]'s 20 least-significant bits.
+String shortHash(Object? object) {
+  return object.hashCode.toUnsigned(20).toRadixString(16).padLeft(5, '0');
+}
+
+/// Returns a summary of the runtime type and hash code of `object`.
+///
+/// See also:
+///
+///  * [Object.hashCode], a value used when placing an object in a [Map] or
+///    other similar data structure, and which is also used in debug output to
+///    distinguish instances of the same class (hash collisions are
+///    possible, but rare enough that its use in debug output is useful).
+///  * [Object.runtimeType], the [Type] of an object.
+String describeIdentity(Object? object) => '${objectRuntimeType(object, '<optimized out>')}#${shortHash(object)}';
@@ -2,7 +2,7 @@ import 'dart:async';
 import 'dart:js_interop';
 import 'dart:js_interop_unsafe';
 
-import 'package:web/web.dart';
+import 'package:universal_web/web.dart';
 
 FutureOr<void> startViewTransition(void Function() callback) {
   if (!document.has('startViewTransition')) {

@@ -8,10 +8,11 @@ import 'dart:async';
 import 'dart:collection';
 
 import 'package:meta/meta.dart';
+import 'package:universal_web/web.dart' as web;
 
 import '../foundation/basic_types.dart';
 import '../foundation/binding.dart';
-import '../foundation/events/events.dart';
+import '../foundation/events.dart';
 import '../foundation/object.dart';
 import '../foundation/styles/styles.dart';