Google Git
Sign in
dart / web / d96c01d2252372c9e0fa7ffa52d2d1df331c248b
commitd96c01d2252372c9e0fa7ffa52d2d1df331c248b[log] [tgz]
authorSrujan Gaddam <58529443+srujzs@users.noreply.github.com>Fri Feb 23 13:05:37 2024 -0800
committerGitHub <noreply@github.com>Fri Feb 23 13:05:37 2024 -0800
tree5b9e9d121a235362d02e5d2bd06734bd60b6ad3a
parent975e55cbe4ac683c33d5256a91f4133fa97b4c34 [diff]
Use extension types and generics internally (#184)

Migrate @staticInterop to extension types, which enables us
to use generic arguments to JSArray and JSPromise.
7 files changed
tree: 5b9e9d121a235362d02e5d2bd06734bd60b6ad3a
  1. .github/
  2. example/
  3. lib/
  4. test/
  5. test_fixes/
  6. tool/
  7. .gitignore
  8. analysis_options.yaml
  9. CHANGELOG.md
  10. LICENSE
  11. pubspec.yaml
  12. README.md
README.md

Dart CI pub package package publisher

Lightweight browser API bindings built around JS static interop.

What's this?

This package exposes browser APIs. It's generated from the Web IDL definitions and uses recent Dart language features for zero-overhead bindings.

This package is intended to replace dart:html and similar Dart SDK libraries. It will support access to browser APIs from Dart code compiled to either JavaScript or WebAssembly.

Usage

import 'package:web/web.dart';

void main() {
  final div = document.querySelector('div')!;
  div.text = 'Text set at ${DateTime.now()}';
}

Generation conventions

The generator scripts use a number of conventions to consistently handle Web IDL definitions:

Interfaces

  • Interfaces are emitted as extension types that wrap and implement JSObject.
  • Interface inheritance is maintained using implements between extension types.
  • Members of partial interfaces, partial mixins, and mixins are added to the interfaces that include them, and therefore do not have separate declarations.

Types

  • Generic types include the generic in the case of JSArray and JSPromise.
  • Enums are typedef'd to String.
  • Callbacks and callback interfaces are typedef'd to JSFunction.
  • In general, we prefer the Dart primitive over the JS type equivalent wherever possible. For example, APIs use String instead of JSString.
  • If a type appears in a generic position and it was typedef'd to a Dart primitive type, it is replaced with the JS type equivalent to respect the type bound of JSAny?.
  • Union types are computed by picking the least upper bound of the types in the JS type hierarchy, where every interface is equivalent to JSObject.

Compatibility

  • The generator uses the MDN compatibility data to determine what members and interfaces to emit. Currently, we only emit code that is standards track and supported on Chrome, Firefox, and Safari to reduce the number of breaking changes. This is currently WIP and some members may be added or removed.

Web IDL version

Based on:

For instructions on re-generating the DOM bindings, see the generator docs.