Skip to content

Commit 7604578

Browse files
srujzssrujzs
authored
Only emit APIs that are standards track and not experimental (#239)
* Only emit APIs that are standards track and not experimental The current implementation only emits APIs that are on the standards track and supported in Chrome, Firefox, and Safari. This leaves out widely used APIs like Trusted Types, so this change relaxes those requirements. In order to support this change, a number of changes are included: - BrowserCompatData is modified to handle some slight discrepancies in how compatibility data is stored, including global APIs, namespaces, static members, and event handlers. - Interfaces and namespaces are generated based on whether they are standards track and experimental. If they are not generated, any references to them will be replaced by the equivalent JS type. - Likewise, inheritance for interfaces is modified to subtype the first generated interface in the inheritance hierarchy. - Dictionaries and typedef-like types are generated based on whether they are used as they don't have compatibility data. In order to determine this, whenever we generate a _RawType, we mark it as used, and recursively generate the types needed. - For each API within an interface, compat data in that interface and its superinterfaces are used to determine if an API is generated. - In order to support the above changes, intermediate representations for some members (attributes, fields, constants) are added. There are other members that might be worth moving to an IR, but that refactoring can be done in a future CL. Closes a number of issues: #209 #234 #216 #205 #203 #192 * Generate APIs based on standards track and not experimental * Handle some TODOs that came up when addressing #209 - Removes an unnecessary null-check - Refactors getTypeForUnionCalculation to a shared _getJSTypeEquivalent function - Avoids shadowing an instance variable * Address some lints * Update CHANGELOG and README * Add types to the field declaration
1 parent d776645 commit 7604578

File tree

106 files changed

+7133
-4871
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

106 files changed

+7133
-4871
lines changed

‎CHANGELOG.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@
88
- Update the docs for generated interface types to reference the MDN Web Docs
99
project.
1010
- Address several broken links in API documentation.
11+
- Generate APIs based on if they're on track to be a standard and not
12+
experimental. This is a looser restriction from the previous requirement that
13+
APIs need to be implemented by Chrome, Firefox, and Safari. As part of this,
14+
dictionaries and typedefs are only emitted if they're used by a generated API.
1115

1216
## 0.5.1
1317

@@ -42,7 +46,7 @@
4246
- Deprecate a few type aliases in favor of their standardized versions:
4347

4448
| Deprecated | Preferred |
45-
|-----------------------|-------------------------|
49+
| --------------------- | ----------------------- |
4650
| `AudioElement` | `HTMLAudioElement` |
4751
| `HtmlElement` | `HTMLElement` |
4852
| `CanvasElement` | `HTMLCanvasElement` |

‎README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -58,15 +58,15 @@ definitions:
5858
bound of `JSAny?`.
5959
- Union types are computed by picking the least upper bound of the types in the
6060
JS type hierarchy, where every interface is equivalent to `JSObject`.
61+
- Dictionary and typedef types are only emitted if they're used by another API.
6162

6263
### Compatibility
6364

6465
- The generator uses the
6566
[MDN compatibility data](https://github.com/mdn/browser-compat-data) to
66-
determine what members and interfaces to emit. Currently, we only emit code
67-
that is standards track and supported on Chrome, Firefox, and Safari to reduce
68-
the number of breaking changes. This is currently WIP and some members may be
69-
added or removed.
67+
determine what members, interfaces, and namespaces to emit. Currently, we only
68+
emit code that is standards track and is not experimental to reduce the number
69+
of breaking changes.
7070

7171
## Generation and updating the package
7272

‎lib/src/dom.dart

+50-2
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,14 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5+
export 'dom/accelerometer.dart';
56
export 'dom/angle_instanced_arrays.dart';
7+
export 'dom/attribution_reporting_api.dart';
8+
export 'dom/battery_status.dart';
69
export 'dom/clipboard_apis.dart';
710
export 'dom/compression.dart';
811
export 'dom/console.dart';
12+
export 'dom/cookie_store.dart';
913
export 'dom/credential_management.dart';
1014
export 'dom/csp.dart';
1115
export 'dom/css_animations.dart';
@@ -18,46 +22,60 @@ export 'dom/css_font_loading.dart';
1822
export 'dom/css_fonts.dart';
1923
export 'dom/css_highlight_api.dart';
2024
export 'dom/css_masking.dart';
25+
export 'dom/css_paint_api.dart';
2126
export 'dom/css_properties_values_api.dart';
2227
export 'dom/css_transitions.dart';
2328
export 'dom/css_transitions_2.dart';
2429
export 'dom/css_typed_om.dart';
25-
export 'dom/css_view_transitions.dart';
2630
export 'dom/cssom.dart';
2731
export 'dom/cssom_view.dart';
2832
export 'dom/dom.dart';
2933
export 'dom/dom_parsing.dart';
3034
export 'dom/encoding.dart';
3135
export 'dom/encrypted_media.dart';
3236
export 'dom/entries_api.dart';
37+
export 'dom/event_timing.dart';
3338
export 'dom/ext_blend_minmax.dart';
3439
export 'dom/ext_color_buffer_float.dart';
3540
export 'dom/ext_color_buffer_half_float.dart';
41+
export 'dom/ext_disjoint_timer_query.dart';
42+
export 'dom/ext_disjoint_timer_query_webgl2.dart';
3643
export 'dom/ext_float_blend.dart';
3744
export 'dom/ext_frag_depth.dart';
3845
export 'dom/ext_shader_texture_lod.dart';
3946
export 'dom/ext_srgb.dart';
4047
export 'dom/ext_texture_compression_bptc.dart';
4148
export 'dom/ext_texture_compression_rgtc.dart';
4249
export 'dom/ext_texture_filter_anisotropic.dart';
50+
export 'dom/ext_texture_norm16.dart';
51+
export 'dom/fedcm.dart';
4352
export 'dom/fetch.dart';
53+
export 'dom/fido.dart';
4454
export 'dom/fileapi.dart';
4555
export 'dom/filter_effects.dart';
4656
export 'dom/fs.dart';
57+
export 'dom/fullscreen.dart';
4758
export 'dom/gamepad.dart';
59+
export 'dom/generic_sensor.dart';
4860
export 'dom/geolocation.dart';
4961
export 'dom/geometry.dart';
62+
export 'dom/gyroscope.dart';
5063
export 'dom/hr_time.dart';
5164
export 'dom/html.dart';
65+
export 'dom/image_capture.dart';
5266
export 'dom/indexeddb.dart';
5367
export 'dom/intersection_observer.dart';
68+
export 'dom/khr_parallel_shader_compile.dart';
69+
export 'dom/largest_contentful_paint.dart';
5470
export 'dom/mathml_core.dart';
5571
export 'dom/media_capabilities.dart';
5672
export 'dom/media_playback_quality.dart';
5773
export 'dom/media_source.dart';
74+
export 'dom/mediacapture_fromelement.dart';
5875
export 'dom/mediacapture_streams.dart';
5976
export 'dom/mediasession.dart';
6077
export 'dom/mediastream_recording.dart';
78+
export 'dom/mst_content_hint.dart';
6179
export 'dom/navigation_timing.dart';
6280
export 'dom/notifications.dart';
6381
export 'dom/oes_draw_buffers_indexed.dart';
@@ -70,18 +88,27 @@ export 'dom/oes_texture_half_float.dart';
7088
export 'dom/oes_texture_half_float_linear.dart';
7189
export 'dom/oes_vertex_array_object.dart';
7290
export 'dom/orientation_event.dart';
91+
export 'dom/orientation_sensor.dart';
92+
export 'dom/ovr_multiview2.dart';
7393
export 'dom/paint_timing.dart';
7494
export 'dom/payment_request.dart';
7595
export 'dom/performance_timeline.dart';
7696
export 'dom/permissions.dart';
97+
export 'dom/picture_in_picture.dart';
7798
export 'dom/pointerevents.dart';
99+
export 'dom/private_network_access.dart';
78100
export 'dom/push_api.dart';
79101
export 'dom/referrer_policy.dart';
102+
export 'dom/remote_playback.dart';
80103
export 'dom/reporting.dart';
104+
export 'dom/requestidlecallback.dart';
81105
export 'dom/resize_observer.dart';
82106
export 'dom/resource_timing.dart';
107+
export 'dom/scheduling_apis.dart';
108+
export 'dom/screen_capture.dart';
83109
export 'dom/screen_orientation.dart';
84110
export 'dom/screen_wake_lock.dart';
111+
export 'dom/secure_payment_confirmation.dart';
85112
export 'dom/selection_api.dart';
86113
export 'dom/server_timing.dart';
87114
export 'dom/service_workers.dart';
@@ -91,32 +118,53 @@ export 'dom/streams.dart';
91118
export 'dom/svg.dart';
92119
export 'dom/svg_animations.dart';
93120
export 'dom/touch_events.dart';
121+
export 'dom/trust_token_api.dart';
94122
export 'dom/trusted_types.dart';
95123
export 'dom/uievents.dart';
96124
export 'dom/url.dart';
97125
export 'dom/user_timing.dart';
98126
export 'dom/vibration.dart';
127+
export 'dom/video_rvfc.dart';
128+
export 'dom/wasm_js_api.dart';
99129
export 'dom/web_animations.dart';
100130
export 'dom/web_animations_2.dart';
131+
export 'dom/web_bluetooth.dart';
101132
export 'dom/web_locks.dart';
133+
export 'dom/web_otp.dart';
134+
export 'dom/web_share.dart';
102135
export 'dom/webaudio.dart';
103136
export 'dom/webauthn.dart';
137+
export 'dom/webcodecs.dart';
138+
export 'dom/webcodecs_av1_codec_registration.dart';
139+
export 'dom/webcodecs_avc_codec_registration.dart';
140+
export 'dom/webcodecs_hevc_codec_registration.dart';
141+
export 'dom/webcodecs_vp9_codec_registration.dart';
104142
export 'dom/webcryptoapi.dart';
105143
export 'dom/webgl1.dart';
106144
export 'dom/webgl2.dart';
107145
export 'dom/webgl_color_buffer_float.dart';
108146
export 'dom/webgl_compressed_texture_astc.dart';
147+
export 'dom/webgl_compressed_texture_etc.dart';
148+
export 'dom/webgl_compressed_texture_etc1.dart';
149+
export 'dom/webgl_compressed_texture_pvrtc.dart';
109150
export 'dom/webgl_compressed_texture_s3tc.dart';
110151
export 'dom/webgl_compressed_texture_s3tc_srgb.dart';
111152
export 'dom/webgl_debug_renderer_info.dart';
112153
export 'dom/webgl_debug_shaders.dart';
113154
export 'dom/webgl_depth_texture.dart';
114155
export 'dom/webgl_draw_buffers.dart';
115156
export 'dom/webgl_lose_context.dart';
157+
export 'dom/webgl_multi_draw.dart';
158+
export 'dom/webgpu.dart';
116159
export 'dom/webidl.dart';
160+
export 'dom/webmidi.dart';
117161
export 'dom/webrtc.dart';
118162
export 'dom/webrtc_encoded_transform.dart';
119-
export 'dom/webrtc_stats.dart';
163+
export 'dom/webrtc_identity.dart';
164+
export 'dom/webrtc_priority.dart';
120165
export 'dom/websockets.dart';
166+
export 'dom/webtransport.dart';
121167
export 'dom/webvtt.dart';
168+
export 'dom/webxr.dart';
169+
export 'dom/webxr_hand_input.dart';
122170
export 'dom/xhr.dart';

‎lib/src/dom/accelerometer.dart

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
//
5+
// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web).
6+
// Attributions and copyright licensing by Mozilla Contributors is licensed
7+
// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/.
8+
9+
// Generated from Web IDL definitions.
10+
11+
@JS()
12+
library;
13+
14+
import 'dart:js_interop';
15+
16+
import 'generic_sensor.dart';
17+
18+
typedef AccelerometerLocalCoordinateSystem = String;
19+
extension type AccelerometerSensorOptions._(JSObject _)
20+
implements SensorOptions, JSObject {
21+
external factory AccelerometerSensorOptions({
22+
num frequency,
23+
AccelerometerLocalCoordinateSystem referenceFrame,
24+
});
25+
26+
external AccelerometerLocalCoordinateSystem get referenceFrame;
27+
external set referenceFrame(AccelerometerLocalCoordinateSystem value);
28+
}
29+
30+
/// The **`LinearAccelerationSensor`** interface of the
31+
/// [Sensor APIs](https://developer.mozilla.org/en-US/docs/Web/API/Sensor_APIs)
32+
/// provides on each reading the acceleration applied to the device along all
33+
/// three axes, but without the contribution of gravity.
34+
///
35+
/// To use this sensor, the user must grant permission to the `'accelerometer'`
36+
/// device sensor through the
37+
/// [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API).
38+
/// In addition, this feature may be blocked by a
39+
/// [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy)
40+
/// set on your server.
41+
///
42+
/// ---
43+
///
44+
/// API documentation sourced from
45+
/// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/LinearAccelerationSensor).
46+
extension type LinearAccelerationSensor._(JSObject _)
47+
implements Sensor, JSObject {
48+
external factory LinearAccelerationSensor(
49+
[AccelerometerSensorOptions options]);
50+
}
51+
52+
/// The **`GravitySensor`** interface of the
53+
/// [Sensor APIs](https://developer.mozilla.org/en-US/docs/Web/API/Sensor_APIs)
54+
/// provides on each reading the gravity applied to the device along all three
55+
/// axes.
56+
///
57+
/// To use this sensor, the user must grant permission to the `'accelerometer'`
58+
/// device sensor through the
59+
/// [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API).
60+
/// In addition, this feature may be blocked by a
61+
/// [Permissions Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy)
62+
/// set on your server.
63+
///
64+
/// ---
65+
///
66+
/// API documentation sourced from
67+
/// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/GravitySensor).
68+
extension type GravitySensor._(JSObject _) implements Sensor, JSObject {
69+
external factory GravitySensor([AccelerometerSensorOptions options]);
70+
}

‎lib/src/dom/attribution_reporting_api.dart

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
//
5+
// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web).
6+
// Attributions and copyright licensing by Mozilla Contributors is licensed
7+
// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/.
8+
9+
// Generated from Web IDL definitions.
10+
11+
@JS()
12+
library;
13+
14+
import 'dart:js_interop';
15+
16+
extension type AttributionReportingRequestOptions._(JSObject _)
17+
implements JSObject {
18+
external factory AttributionReportingRequestOptions({
19+
required bool eventSourceEligible,
20+
required bool triggerEligible,
21+
});
22+
23+
external bool get eventSourceEligible;
24+
external set eventSourceEligible(bool value);
25+
external bool get triggerEligible;
26+
external set triggerEligible(bool value);
27+
}

‎lib/src/dom/battery_status.dart

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
//
5+
// API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web).
6+
// Attributions and copyright licensing by Mozilla Contributors is licensed
7+
// under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/.
8+
9+
// Generated from Web IDL definitions.
10+
11+
@JS()
12+
library;
13+
14+
import 'dart:js_interop';
15+
16+
import 'dom.dart';
17+
import 'html.dart';
18+
19+
/// The `BatteryManager` interface of the [Battery Status API] provides
20+
/// information about the system's battery charge level. The
21+
/// [navigator.getBattery] method returns a promise that resolves with a
22+
/// `BatteryManager` interface.
23+
///
24+
/// Since Chrome 103, the `BatteryManager` interface of [Battery Status API]
25+
/// only expose to secure context.
26+
///
27+
/// ---
28+
///
29+
/// API documentation sourced from
30+
/// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/BatteryManager).
31+
extension type BatteryManager._(JSObject _) implements EventTarget, JSObject {
32+
/// The **`BatteryManager.charging`** property is a Boolean value indicating
33+
/// whether or not the device's battery is currently being charged. When its
34+
/// value changes, the [BatteryManager.chargingchange_event] event is fired.
35+
///
36+
/// If the battery is charging or the user agent is unable to report the
37+
/// battery status information, this value is `true`. Otherwise, it is
38+
/// `false`.
39+
external bool get charging;
40+
41+
/// The **`BatteryManager.chargingTime`** property indicates the amount of
42+
/// time, in seconds, that remain until the battery is fully charged, or `0`
43+
/// if the battery is already fully charged or the user agent is unable to
44+
/// report the battery status information.
45+
/// If the battery is currently discharging, its value is `Infinity`.
46+
/// When its value changes, the [BatteryManager.chargingtimechange_event]
47+
/// event is fired.
48+
///
49+
/// > **Note:** Even if the time returned is precise to the second,
50+
/// > browsers round them to a higher interval
51+
/// > (typically to the closest 15 minutes) for privacy reasons.
52+
external num get chargingTime;
53+
54+
/// The **`BatteryManager.dischargingTime`** property indicates the amount of
55+
/// time, in seconds, that remains until the battery is fully discharged,
56+
/// or `Infinity` if the battery is currently charging rather than discharging
57+
/// or the user agent is unable to report the battery status information.
58+
/// When its value changes, the [BatteryManager.dischargingtimechange_event]
59+
/// event is fired.
60+
///
61+
/// > **Note:** Even if the time returned is precise to the second, browsers
62+
/// > round them to a higher
63+
/// > interval (typically to the closest 15 minutes) for privacy reasons.
64+
external num get dischargingTime;
65+
66+
/// The **`BatteryManager.level`** property indicates the current battery
67+
/// charge level as a value between `0.0` and `1.0`.
68+
/// A value of `0.0` means the battery is empty and the system is about to be
69+
/// suspended.
70+
/// A value of `1.0` means the battery is full or the user agent is unable to
71+
/// report the battery status information.
72+
/// When its value changes, the [BatteryManager.levelchange_event] event is
73+
/// fired.
74+
external num get level;
75+
external EventHandler get onchargingchange;
76+
external set onchargingchange(EventHandler value);
77+
external EventHandler get onchargingtimechange;
78+
external set onchargingtimechange(EventHandler value);
79+
external EventHandler get ondischargingtimechange;
80+
external set ondischargingtimechange(EventHandler value);
81+
external EventHandler get onlevelchange;
82+
external set onlevelchange(EventHandler value);
83+
}

0 commit comments

Comments
 (0)