[interop] Adding support for dart:js_interop and package:web types (#403)

* Adding types input

* Added support for primitive types represented in `dart:js_interop`

* Added support for generating web_rename_map.dart

for names that are renamed in package:web

* completed integration of `package:web` types

* formatting and analyzing

* comment resolution

* minor change

* Removed `BuiltinTypeGenerator` callable type to use static `BuiltinType.referred` for supported types in `dart:js_interop`

* fixed analyzer issue

* completed nits in merge

* removed completed TODO

Author: nikeokoronkwo

web_generator/lib/src/ast/builtin.dart

@@ -7,6 +7,7 @@
 import 'package:code_builder/code_builder.dart';
 
 import '../interop_gen/namer.dart';
+import '../web_rename_map.dart';
 import 'base.dart';
 
 /// A built in type supported by `dart:js_interop` or by this library
@@ -83,20 +84,90 @@ class BuiltinType extends Type {
       PrimitiveType.any || PrimitiveType.unknown => anyType,
       PrimitiveType.object => BuiltinType(
           name: 'JSObject', fromDartJSInterop: true, isNullable: isNullable),
+      PrimitiveType.symbol => BuiltinType(
+          name: 'JSSymbol', fromDartJSInterop: true, isNullable: isNullable),
+      PrimitiveType.bigint => BuiltinType(
+          name: 'JSBigInt', fromDartJSInterop: true, isNullable: isNullable),
       PrimitiveType.array => BuiltinType(
           name: 'JSArray',
           typeParams: [typeParams.single],
           fromDartJSInterop: true,
           isNullable: isNullable),
-      PrimitiveType.promise => BuiltinType(
-          name: 'JSPromise',
-          typeParams: [typeParams.single],
-          fromDartJSInterop: true,
-          isNullable: isNullable),
-      PrimitiveType.function => BuiltinType(
-          name: 'JSFunction', fromDartJSInterop: true, isNullable: isNullable),
     };
   }
+
+  static BuiltinType? referred(String name,
+      {bool? isNullable, List<Type> typeParams = const []}) {
+    final jsName = switch (name) {
+      'Array' => 'JSArray',
+      'Promise' => 'JSPromise',
+      'ArrayBuffer' => 'JSArrayBuffer',
+      'Function' => 'JSFunction',
+      'DataView' => 'JSDataView',
+      'Float32Array' => 'JSFloat32Array',
+      'Float64Array' => 'JSFloat64Array',
+      'Int8Array' => 'JSInt8Array',
+      'Int16Array' => 'JSInt16Array',
+      'Int32Array' => 'JSInt32Array',
+      'Int64Array' => 'JSInt64Array',
+      'Uint8Array' => 'JSUint8Array',
+      'Uint16Array' => 'JSUint16Array',
+      'Uint32Array' => 'JSUint32Array',
+      'Uint8ClampedArray' => 'JSUint8ClampedArray',
+      _ => null
+    };
+    final jsTypeArgs = switch (name) { 'Array' || 'Promise' => 1, _ => 0 };
+    if (jsName case final typeName?) {
+      return BuiltinType(
+          name: typeName,
+          fromDartJSInterop: true,
+          typeParams: typeParams.take(jsTypeArgs).toList(),
+          isNullable: isNullable);
+    }
+    return null;
+  }
+}
+
+class PackageWebType extends Type {
+  @override
+  final String name;
+
+  final List<Type> typeParams;
+
+  final bool? isNullable;
+
+  @override
+  ID get id => ID(type: 'type', name: name);
+
+  @override
+  String? get dartName => null;
+
+  PackageWebType._(
+      {required this.name, this.typeParams = const [], this.isNullable});
+
+  @override
+  Reference emit([TypeOptions? options]) {
+    options ??= TypeOptions();
+
+    // TODO: We can make this a shared function as it is called a lot
+    //  between types
+    return TypeReference((t) => t
+      ..symbol = name
+      ..types.addAll(typeParams
+          // if there is only one type param, and it is void, ignore
+          .where((p) => typeParams.length != 1 || p != BuiltinType.$voidType)
+          .map((p) => p.emit(TypeOptions())))
+      ..url = 'package:web/web.dart'
+      ..isNullable = isNullable ?? options!.nullable);
+  }
+
+  static PackageWebType parse(String name,
+      {bool? isNullable, List<Type> typeParams = const []}) {
+    return PackageWebType._(
+        name: renameMap.containsKey(name) ? renameMap[name]! : name,
+        isNullable: isNullable,
+        typeParams: typeParams);
+  }
 }
 
 enum PrimitiveType {
@@ -110,7 +181,7 @@ enum PrimitiveType {
   object,
   unknown,
   undefined,
+  symbol,
   array,
-  promise,
-  function
+  bigint
 }

web_generator/lib/src/ast/helpers.dart

@@ -9,20 +9,6 @@ import 'builtin.dart';
 import 'declarations.dart';
 import 'types.dart';
 
-BuiltinType? getSupportedType(String name, [List<Type> typeParams = const []]) {
-  final type = switch (name) {
-    'Array' => PrimitiveType.array,
-    'Promise' => PrimitiveType.promise,
-    _ => null
-  };
-
-  if (type == null) return null;
-
-  return BuiltinType.primitiveType(type, typeParams: [
-    getJSTypeAlternative(typeParams.singleOrNull ?? BuiltinType.anyType)
-  ]);
-}
-
 Type getJSTypeAlternative(Type type) {
   if (type is BuiltinType) {
     if (type.fromDartJSInterop) return type;

web_generator/lib/src/dart_main.dart

@@ -16,6 +16,7 @@ import 'generate_bindings.dart';
 import 'interop_gen/parser.dart';
 import 'interop_gen/transform.dart';
 import 'js/filesystem_api.dart';
+import 'js/node.dart';
 import 'util.dart';
 
 // Generates DOM bindings for Dart.
@@ -102,9 +103,30 @@ Future<void> generateIDLBindings({
 
     ensureDirectoryExists('$output/$librarySubDir');
 
-    final bindings = await generateBindings(packageRoot, librarySubDir,
+    final (bindings, renameMap) = await generateBindings(
+        packageRoot, librarySubDir,
         generateAll: generateAll);
 
+    if (renameMap.isNotEmpty) {
+      final lib = code.Library((l) => l
+        ..comments.add('''
+// Copyright (c) ${DateTime.now().year}, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// AUTO GENERATED: DO NOT EDIT
+''')
+        ..body.add(code.Field((f) => f
+          ..name = 'renameMap'
+          ..type = code.refer('Map<String, String>')
+          ..modifier = code.FieldModifier.constant
+          ..assignment = code.literalConstMap(renameMap).code)));
+      final libCode = _emitLibrary(lib, languageVersion);
+      fs.writeFileSync(
+          p.join(p.dirname(p.fromUri(url)), 'web_rename_map.dart').toJS,
+          libCode.toJS);
+    }
+
     for (var entry in bindings.entries) {
       final libraryPath = entry.key;
       final library = entry.value;

web_generator/lib/src/generate_bindings.dart

@@ -71,7 +71,7 @@ Future<Map<String, Set<String>>> _generateElementTagMap() async {
   return elementMap;
 }
 
-Future<TranslationResult> generateBindings(
+Future<(TranslationResult, Map<String, String>)> generateBindings(
     String packageRoot, String librarySubDir,
     {required bool generateAll}) async {
   final cssStyleDeclarations = await _generateCSSStyleDeclarations();
@@ -87,7 +87,10 @@ Future<TranslationResult> generateBindings(
     translator.collect(shortname, ast);
   }
   translator.addInterfacesAndNamespaces();
-  return translator.translate();
+  final result = translator.translate();
+  final renamedTypes = translator.renamedClasses;
+
+  return (result, renamedTypes);
 }
 
 Future<TranslationResult> generateBindingsForFiles(

web_generator/lib/src/interop_gen/transform/transformer.dart

@@ -3,6 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'dart:js_interop';
+import 'package:path/path.dart' as p;
 import '../../ast/base.dart';
 import '../../ast/builtin.dart';
 import '../../ast/declarations.dart';
@@ -180,16 +181,6 @@ class Transformer {
     }).toList();
   }
 
-  TSNode? _getDeclarationByName(TSIdentifier name) {
-    final symbol = typeChecker.getSymbolAtLocation(name);
-
-    final declarations = symbol?.getDeclarations();
-    // TODO(https://github.com/dart-lang/web/issues/387): Some declarations may not be defined on file,
-    //  and may be from an import statement
-    //  We should be able to handle these
-    return declarations?.toDart.first;
-  }
-
   TypeAliasDeclaration _transformTypeAlias(TSTypeAliasDeclaration typealias) {
     final name = typealias.name.text;
 
@@ -205,9 +196,6 @@ class Transformer {
 
     return TypeAliasDeclaration(
         name: name,
-        // TODO: Can we find a way not to make the types be JS types
-        //  by default if possible. Leaving this for now,
-        //  so that using such typealiases in generics does not break
         type: _transformType(type),
         typeParameters:
             typeParams?.map(_transformTypeParamDeclaration).toList() ?? [],
@@ -293,22 +281,41 @@ class Transformer {
           // TODO(https://github.com/dart-lang/web/issues/380): A better name
           //  for this, and adding support for "supported declarations"
           //  (also a better name for that)
-          final supportedType = getSupportedType(
-              name,
-              (typeArguments ?? [])
-                  .map((type) => _transformType(type, typeArg: true))
+          final supportedType = BuiltinType.referred(name,
+              typeParams: (typeArguments ?? [])
+                  .map((t) => getJSTypeAlternative(_transformType(t)))
                   .toList());
-          if (supportedType != null) {
-            return supportedType;
+          if (supportedType case final resultType?) {
+            return resultType;
           }
 
+          final symbol = typeChecker.getSymbolAtLocation(refType.typeName);
+          final declarations = symbol?.getDeclarations();
+
           // TODO: In the case of overloading, should/shouldn't we handle more than one declaration?
-          final declaration = _getDeclarationByName(refType.typeName);
+          // TODO(https://github.com/dart-lang/web/issues/387): Some declarations may not be defined on file,
+          //  and may be from an import statement
+          //  We should be able to handle these
+          final declaration = declarations?.toDart.first;
 
           if (declaration == null) {
             throw Exception('Found no declaration matching $name');
           }
 
+          // check if this is from dom
+          final declarationSource = declaration.getSourceFile().fileName;
+          if (p.basename(declarationSource) == 'lib.dom.d.ts' ||
+              declarationSource.contains('dom')) {
+            // dom declaration: supported by package:web
+            // TODO(nikeokoronkwo): It is possible that we may get a type
+            //  that isn't in `package:web`
+            return PackageWebType.parse(name,
+                typeParams: (typeArguments ?? [])
+                    .map(_transformType)
+                    .map(getJSTypeAlternative)
+                    .toList());
+          }
+
           if (declaration.kind == TSSyntaxKind.TypeParameter) {
             return GenericType(name: name);
           }
@@ -430,6 +437,8 @@ class Transformer {
           TSSyntaxKind.UnknownKeyword => PrimitiveType.unknown,
           TSSyntaxKind.BooleanKeyword => PrimitiveType.boolean,
           TSSyntaxKind.VoidKeyword => PrimitiveType.$void,
+          TSSyntaxKind.BigIntKeyword => PrimitiveType.bigint,
+          TSSyntaxKind.SymbolKeyword => PrimitiveType.symbol,
           _ => throw UnsupportedError(
               'The given type with kind ${type.kind} is not supported yet')
         };

web_generator/lib/src/js/node.dart

@@ -0,0 +1,8 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:js_interop';
+
+@JS()
+external String get url;

web_generator/lib/src/js/typescript.dart

@@ -43,7 +43,9 @@ extension type TSTypeChecker._(JSObject _) implements JSObject {
 }
 
 @JS('SourceFile')
-extension type TSSourceFile._(JSObject _) implements TSNode {}
+extension type TSSourceFile._(JSObject _) implements TSDeclaration {
+  external String fileName;
+}
 
 extension type TSNodeCallback<T extends JSAny>._(JSObject _)
     implements JSObject {

web_generator/lib/src/js/typescript.types.dart

@@ -51,6 +51,8 @@ extension type const TSSyntaxKind._(num _) {
   static const TSSyntaxKind SetKeyword = TSSyntaxKind._(153);
   static const TSSyntaxKind UnknownKeyword = TSSyntaxKind._(159);
   static const TSSyntaxKind VoidKeyword = TSSyntaxKind._(116);
+  static const TSSyntaxKind BigIntKeyword = TSSyntaxKind._(163);
+  static const TSSyntaxKind SymbolKeyword = TSSyntaxKind._(155);
 
   // types
   static const TSSyntaxKind UnionType = TSSyntaxKind._(192);
@@ -80,6 +82,7 @@ extension type TSNode._(JSObject _) implements JSObject {
   external TSNodeFlags get flags;
   external String getText([TSSourceFile? sourceFile]);
   external String getFullText([TSSourceFile? sourceFile]);
+  external TSSourceFile getSourceFile();
 }
 
 @JS('TypeNode')

web_generator/lib/src/main.mjs

@@ -23,6 +23,7 @@ globalThis.idl = idl;
 globalThis.webidl2 = webidl2;
 globalThis.ts = ts;
 globalThis.location = { href: `file://${process.cwd()}/` }
+globalThis.url = import.meta.url;
 
 globalThis.dartMainRunner = async function (main, args) {
   const dartArgs = process.argv.slice(2);

web_generator/lib/src/translator.dart

@@ -661,6 +661,9 @@ class Translator {
   final _interfacelikes = <String, _PartialInterfacelike>{};
   final _includes = <String, List<String>>{};
   final _usedTypes = <idl.Node>{};
+  final _renamedClasses = <String, String>{};
+
+  Map<String, String> get renamedClasses => _renamedClasses;
 
   late String _currentlyTranslatingUrl;
   late DocProvider docProvider;
@@ -1356,6 +1359,10 @@ class Translator {
 
     final rawType = _RawType(dartClassName, false);
 
+    if (!isNamespace && jsName != dartClassName) {
+      _renamedClasses[jsName] = dartClassName;
+    }
+
     return [
       if (getterName != null) _topLevelGetter(rawType, getterName),
       _extensionType(