23475c0192564b8fca9b6c3c03652ea31882acc3 - web

commit	23475c0192564b8fca9b6c3c03652ea31882acc3	[log] [tgz]
author	Devon Carew <devoncarew@google.com>	Wed Feb 28 12:01:52 2024 -0800
committer	GitHub <noreply@github.com>	Wed Feb 28 12:01:52 2024 -0800
tree	1ca1bae1e1de8457f0c632215ca8bb84f51eb83e
parent	fa4280c061f0043f1d3c5346ab1495512de4bef2 [diff]

Include MDN API documentation as class and member dartdoc comments (#143)

* scrape MDN for API documentation

* commit the parsed documentation information

* review feedback

* Update tool/scrape_mdn.dart

Co-authored-by: Kevin Moore <kevmoo@users.noreply.github.com>

* switch to reading from markdown files from the git repo

* regenerate the mdn.json file

* update copyright

* Bump actions/stale from 8.0.0 to 9.0.0 (#132)

Bumps [actions/stale](https://github.com/actions/stale) from 8.0.0 to 9.0.0.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a href="https://github.com/actions/stale/releases">actions/stale's releases</a>.</em></p>
<blockquote>
<h2>v9.0.0</h2>
<h2>Breaking Changes</h2>
<ol>
<li>Action is now stateful: If the action ends because of <a href="https://github.com/actions/stale#operations-per-run">operations-per-run</a> then the next run will start from the first unprocessed issue skipping the issues processed during the previous run(s). The state is reset when all the issues are processed. This should be considered for scheduling workflow runs.</li>
<li>Version 9 of this action updated the runtime to Node.js 20. All scripts are now run with Node.js 20 instead of Node.js 16 and are affected by any breaking changes between Node.js 16 and 20.</li>
</ol>
<h2>What Else Changed</h2>
<ol>
<li>Performance optimization that removes unnecessary API calls by <a href="https://github.com/dsame"><code>@âdsame</code></a> <a href="https://redirect.github.com/actions/stale/pull/1033/">#1033</a> fixes <a href="https://redirect.github.com/actions/stale/issues/792">#792</a></li>
<li>Logs displaying current github API rate limit by <a href="https://github.com/dsame"><code>@âdsame</code></a> <a href="https://redirect.github.com/actions/stale/pull/1032">#1032</a> addresses <a href="https://redirect.github.com/actions/stale/issues/1029">#1029</a></li>
</ol>
<p>For more information, please read the <a href="https://github.com/actions/stale#readme">action documentation</a> and its <a href="https://github.com/actions/stale#statefulness">section about statefulness</a></p>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/jmeridth"><code>@âjmeridth</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/984">actions/stale#984</a></li>
<li><a href="https://github.com/nikolai-laevskii"><code>@ânikolai-laevskii</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/1020">actions/stale#1020</a></li>
<li><a href="https://github.com/dusan-trickovic"><code>@âdusan-trickovic</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/1056">actions/stale#1056</a></li>
<li><a href="https://github.com/aparnajyothi-y"><code>@âaparnajyothi-y</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/1110">actions/stale#1110</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a href="https://github.com/actions/stale/compare/v8...v9.0.0">https://github.com/actions/stale/compare/v8...v9.0.0</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a href="https://github.com/actions/stale/commit/28ca1036281a5e5922ead5184a1bbf96e5fc984e"><code>28ca103</code></a> Upgrade Node to v20 (<a href="https://redirect.github.com/actions/stale/issues/1110">#1110</a>)</li>
<li><a href="https://github.com/actions/stale/commit/b69b346013879cedbf50c69f572cd85439a41936"><code>b69b346</code></a> build(deps-dev): bump <code>@âtypes/node</code> from 18.16.18 to 20.5.1 (<a href="https://redirect.github.com/actions/stale/issues/1079">#1079</a>)</li>
<li><a href="https://github.com/actions/stale/commit/88a6f4f6cbe6984b66da80d3d448d5f0c4d1a42d"><code>88a6f4f</code></a> build(deps-dev): bump typescript from 5.1.3 to 5.2.2 (<a href="https://redirect.github.com/actions/stale/issues/1083">#1083</a>)</li>
<li><a href="https://github.com/actions/stale/commit/796531a7b39835671cd9f436d7205b1556bbcff6"><code>796531a</code></a> Merge pull request <a href="https://redirect.github.com/actions/stale/issues/1080">#1080</a> from akv-platform/fix-delete-cache</li>
<li><a href="https://github.com/actions/stale/commit/8986f6218b4935e254d5b844e8c36b4d953f2643"><code>8986f62</code></a> Don not try to delete cache if it does not exists</li>
<li><a href="https://github.com/actions/stale/commit/cab99b362baa5afbbd8c7c78234e6b071b80687d"><code>cab99b3</code></a> fix typo proceeded/processed</li>
<li><a href="https://github.com/actions/stale/commit/184e7afe930f6b5c7ce52c4b3f087692c6e912f3"><code>184e7af</code></a> Merge pull request <a href="https://redirect.github.com/actions/stale/issues/1064">#1064</a> from actions/dependabot/npm_and_yarn/typescript-esli...</li>
<li><a href="https://github.com/actions/stale/commit/523885cf3c115dcdcbed573c7eaf0f5621f124e2"><code>523885c</code></a> chore: update eslint-plugin, parser and eslint-plugin-jest</li>
<li><a href="https://github.com/actions/stale/commit/2487a1dc2b501176ca975d2d8b4d3293d72180a2"><code>2487a1d</code></a> build(deps-dev): bump <code>@âtypescript-eslint/eslint-plugin</code></li>
<li><a href="https://github.com/actions/stale/commit/60c722ee97faafece819a7c41b03ec113f99717d"><code>60c722e</code></a> Merge pull request <a href="https://redirect.github.com/actions/stale/issues/1063">#1063</a> from actions/dependabot/npm_and_yarn/jest-29.6.2</li>
<li>Additional commits viewable in <a href="https://github.com/actions/stale/compare/1160a2240286f5da8ec72b1c0816ce2481aabf84...28ca1036281a5e5922ead5184a1bbf96e5fc984e">compare view</a></li>
</ul>
</details>
<br />

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=actions/stale&package-manager=github_actions&previous-version=8.0.0&new-version=9.0.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`.

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

</details>

* write additional version info into the readme (#126)

* generate mdn docs as library dartdoc

* re-generate package:web w/ dartdoc comments

* update changelog

* regenerate lib/src/dom

* update changelog

* refactor mdn.json into a third_party directory

* Add docs for added trusted-types, fix changelog

* update the changelog

* review comments

* add a todo to improve dartdoc comment formatting

---------

Co-authored-by: Kevin Moore <kevmoo@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Kevin Moore <kevmoo@google.com>

132 files changed

tree: 1ca1bae1e1de8457f0c632215ca8bb84f51eb83e

README.md

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()}';
}

Migrating to package:web

package:web is replacing dart:html and other web libraries as Dart's long-term web interop solution. To learn how to migrate from dart:html APIs to package:web, see our migration guide.

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:

@webref/idl 3.43.1
@webref/css 6.11.0

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