Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explicitly call out legacy JS interop as deprecated #6310

Merged
merged 1 commit into from
Jan 7, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions src/content/interop/js-interop/package-web.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,12 @@ by addressing several concerns with the existing Dart web libraries:
if they use [`dart:js_interop`][] and [`dart:js_interop_unsafe`][].
`package:web` is based on `dart:js_interop`,
so by default, it's supported on `dart2wasm`.

Dart core web libraries, like [`dart:html`][html] and [`dart:svg`][svg],
are **not supported** when compiling to Wasm.
are deprecated and **not supported** when compiling to Wasm.

2. **Staying modern**

`package:web` uses the [Web IDL][idl] to automatically generate
[interop members][] and [interop types][]
for each declaration in the IDL.
Expand Down
31 changes: 14 additions & 17 deletions src/content/interop/js-interop/past-js-interop.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,22 @@
---
title: Past JS interop
description: Archive of past JS interop implementations.
description: Archive of Dart's previous JS interop support.
---

:::warning
None of these legacy interop libraries are supported when compiling to [Wasm][].
:::

This page addresses previous iterations of JS interop for Dart that are
considered legacy. They are not deprecated yet, but will likely be in the
future. Therefore, prefer using [`dart:js_interop`] going forwards and migrate
usages of old interop libraries when possible. While [`dart:html`] and other web
libraries are closely related, they're covered in the [`package:web`] page.
This page addresses previous iterations of JS interop for Dart that
have been considered legacy and are deprecated as of Dart 3.7.
Therefore, prefer using [`dart:js_interop`][] going forwards and
migrate usages of old interop libraries when possible.
While [`dart:html`][] and other web libraries are closely related,
they're covered in the [`package:web`][] page.

[`dart:js_interop`]: {{site.dart-api}}/dart-js_interop/dart-js_interop-library.html
[`dart:html`]: {{site.dart-api}}/dart-html/dart-html-library.html
[`package:web`]: /interop/js-interop/package-web

## `dart:js`

Expand All @@ -23,8 +28,8 @@ code-completion as you couldn't declare interop members and instead relied on
Strings. Many of the functionalities exposed in `dart:js` like [`allowInterop`]
were later re-exposed through other interop libraries.

This library has been legacy ever since `package:js` and `dart:js_util` were
released. It will likely be the first to be deprecated.
This library has been legacy since
`package:js` and `dart:js_util` were released.

## `package:js`

Expand All @@ -50,7 +55,7 @@ There are significant differences, however:
`package:js` type to `dynamic` and called an interop member on it, it would
forward to the right member. This is no longer possible with
`dart:js_interop`.
- `package:js`' [`@JS`] has no soundness guarantees as return types of
- `package:js`' `@JS` has no soundness guarantees as return types of
`external` members were not checked. `dart:js_interop` is sound.
- `package:js` types could not rename instance members or have non-`external`
members.
Expand Down Expand Up @@ -101,20 +106,12 @@ and forth. This included members like:
`dart:js_interop` and `dart:js_interop_unsafe` contain these helpers now with
possibly alternate syntax.

{% comment %}
TODO: add links (with stable) when ready:
TODO: Link to `package:web` section
{% endcomment %}

[`dart:js_interop`]: {{site.dart-api}}/dart-js_interop/dart-js_interop-library.html
[`dart:html`]: {{site.dart-api}}/dart-html/dart-html-library.html
[`package:web`]: /interop/js-interop/package-web
[`dart:js`]: {{site.dart-api}}/dart-js/dart-js-library.html
[`object wrapper`]: {{site.dart-api}}/dart-js/JsObject-class.html
[`allowInterop`]: {{site.dart-api}}/dart-js_util/allowInterop.html
[`package:js`]: {{site.pub-pkg}}/js
[`JSObject`]: {{site.dart-api}}/dart-js_interop/JSObject-extension-type.html
[`@JS`]: {{site.repo.dart.sdk}}/blob/main/sdk/lib/js/_js_annotations.dart#L11
[tutorial on mocking]: /interop/js-interop/mock
[`@anonymous`]: {{site.repo.dart.sdk}}/blob/main/sdk/lib/js/_js_annotations.dart#L40
[`@staticInterop`]: {{site.repo.dart.sdk}}/blob/main/sdk/lib/js/_js_annotations.dart#L48
Expand Down
Loading