[Eval] Update to @staticInterop docs

[MaryaBelanger]

This is an evaluation issue

Evaluating the possible need for doc updates due to dart-lang/sdk#49350 , dart-lang/sdk#48730 in particular

Summary

Limitations to @staticInterop package:js classes to simplify future implementation and support of JSinterop.

Evaluation

Because @staticInterop is fairly new, there is no documentation to update in dart.dev for the 2.19 release.
With the introduction of views inline classes in the future, more content will need to be added:

1. Views come out: Polished @staticInterop syntax changes released in a core library

• Add docs to /libraries/library-tour

2. Full interop with views inline classes ready: Cleaner language-feature syntax of the same feature

• Completely shift docs to updated syntax, remove syntax added in 1

The greater documentation on views will include information on interop with views inline classes

References

• Examples and summary added to API docs: dart-lang/sdk@81ba8a2
• dart-lang/sdk@20e689e

[parlough]

It will be exciting to have some documentation of this new functionality once views are released. Is there an example of the expected syntax with views or what will be in a core library?

Without the complete context, it doesn't currently sound like a perfect fit for the library tour (outside of maybe a small mention if something is added to a core dart: library). I wonder if it would be better in its own page, such as JavaScript Interoperability which is currently lacking.

[srujzs]

Sorry Parker, I missed your comment. I agree that the JS interop page on dart.dev is the best place for it to exist. I'd like for that page to be the goto for interop. Ideally, I'd like for it to mention what not to use as well (like dart:js and other attempts at interop).

I don't think we're going to release a polished syntax (1), since we expect to have interop with views (now called inline classes) ready by Dart 3. So, we're going to lean into (2) directly here.

An example syntax was kind of up in the air until recently because the specification for inline classes changed up a bit. :) I can come back with one once we have a prototype we can start working with.

[mnordine]

@srujzs just curious, any update on the expected syntax?

[srujzs]

It'll be based on inline classes in conjunction with external members for Dart 3. If you're curious about inline classes, the finalized spec with syntax is here: https://github.com/dart-lang/language/blob/master/accepted/future-releases/inline-classes/feature-specification.md

[mnordine]

Sorry, I know about inline classes, I should have asked for a specific example. What would it look like in this webgpu example?

inline class Gpu {
  /// ??????
}

void main() {
  final gpu = Gpu();
  final adapter = await gpu.requestAdapter();
  if (adapter == null) {
    print('no adapter');
    return;
  }

  final device = await adapter.requestDevice();
  print(device.capabilities);
}

[srujzs]

Ah, I see, the syntax would be very similar to what we have today except with inline classes. I'm working on lowerings to adapt them, so the final accepted syntax might be slightly different (specifically around constructors), but here's what I'm imagining:

@JS() // We still need an annotation to signal that this is a JS interop inline class vs other inline classes and for renaming
inline class Gpu {
  final JSObject _gpu;
  external factory Gpu(); // Like before, assumes there's a `globalThis.Gpu` constructor.

  @JS('requestAdapter')
  external Promise _requestAdapter();
  Future<Adapter?> requestAdapter => js_util.promiseToFuture(_requestAdapter());
}

@JS()
inline class Promise {
  final JSObject _promise;
  Promise(this._promise);
}

@JS()
inline class Adapter {
  final JSObject _adapter;
  Adapter(this._adapter);
  
  @JS('requestDevice')
  external Promise _requestDevice();
  Future<Device?> _requestDevice => js_util.promiseToFuture(_requestDevice());
}

@JS()
inline class Device {
  final JSObject _device;
  Device(this._device);

  external Object get capabilities;
}

[parlough]

Thanks all! I'm closing in favor of the new static interop and package-web umbrella issue as initial evaluation of the necessity of these docs has been completed.

#5438