[sync] 2024/08/02 (#473)

.github/workflows/build.yml

@@ -81,7 +81,7 @@ jobs:
       - name: Fetch Dart packages
         run: dart pub get
       - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2
-      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8
+      - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: 'pnpm'
@@ -150,7 +150,7 @@ jobs:
       - name: Fetch Dart packages
         run: dart pub get
       - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2
-      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8
+      - uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: 'pnpm'

examples/type_system/lib/common_fixes_analysis.dart

@@ -149,3 +149,15 @@ void infFix() {
       ints.fold<int?>(null, (a, b) => a == null || a < b ? b : a);
   // #enddocregion type-inf-fix
 }
+
+//-----------------------------------------------
+
+// #docregion compatible-generics
+abstract class C implements List<int> {}
+// #enddocregion compatible-generics
+
+// #docregion conflicting-generics
+// ignore: inconsistent_inheritance, conflicting_generic_interfaces,
+// ignore: duplicate_definition
+abstract class C implements List<int>, Iterable<num> {}
+// #enddocregion conflicting-generics

package.json

@@ -17,14 +17,14 @@
     "node": ">=20.12.0",
     "pnpm": ">=9.1.0"
   },
-  "packageManager": "pnpm@9.1.4",
+  "packageManager": "pnpm@9.6.0",
   "dependencies": {
     "bootstrap-scss": "^4.6.2"
   },
   "devDependencies": {
-    "@11ty/eleventy": "3.0.0-alpha.14",
-    "@11ty/eleventy-img": "5.0.0-beta.4",
-    "firebase-tools": "^13.12.0",
+    "@11ty/eleventy": "3.0.0-beta.1",
+    "@11ty/eleventy-img": "5.0.0-beta.10",
+    "firebase-tools": "^13.14.2",
     "hast-util-from-html": "^2.0.1",
     "hast-util-select": "^6.0.2",
     "hast-util-to-text": "^4.0.2",
@@ -36,7 +36,7 @@
     "markdown-it-container": "^4.0.0",
     "markdown-it-deflist": "^3.0.0",
     "markdown-it-table": "^4.1.1",
-    "sass": "^1.77.6",
-    "shiki": "^1.10.0"
+    "sass": "^1.77.8",
+    "shiki": "^1.12.0"
   }
-}
+}

src/_data/side-nav.yml

@@ -184,6 +184,8 @@
           permalink: /tools/pub/security-advisories
         - title: 版本管理
           permalink: /tools/pub/versioning
+    - title: 不应提交的内容
+      permalink: /guides/libraries/private-files
 
 - title: 开发文档
   expanded: false
@@ -334,9 +336,6 @@
         permalink: /guides/testing
       - title: 调试 Web 应用
         permalink: /web/debugging
-  - title: 不应提交的内容
-    permalink: /guides/libraries/private-files
-
 
 - divider
 - title: 资源

src/_data/site.yml

@@ -29,7 +29,7 @@ announce: https://groups.google.com/a/dartlang.org/g/announce
 android-dev: https://developer.android.com
 apple-dev: https://developer.apple.com
 
-show_banner: true
+show_banner: false
 
 # Increment this global og:image URL version number (used as a query parameter)
 # when you update any og:image file. (Also increment the corresponding number
@@ -38,4 +38,4 @@ og_image_vers: "?2"
 
 sdkInfo:
   channel: stable
-  version: 3.4.1
+  version: 3.4.4

src/content/404.html

@@ -4,6 +4,7 @@
 description: "dart.dev's 404 page."
 sitemap: false
 permalink: /404.html
+skipFreshness: true
 ---
 
 <div class="text-center">

src/content/brand.md

@@ -5,6 +5,7 @@ title: Dart 品牌指南
 #   The guidelines governing the usage of the Dart trademarks and assets.
 description: >-
   关于使用 Dart 品牌和资产的指导原则。
+skipFreshness: true
 ---
 
 The "Dart" name and logo are trademarks owned by Google.

src/content/community/code-of-conduct.md

@@ -3,6 +3,7 @@
 title: 行为准则
 description: Be excellent to each other.
 toc: false
+skipFreshness: true
 ---
 
 We expect Dart community members to act professionally and respectfully, and

src/content/get-dart/archive/_archives_table.html

@@ -27,7 +27,7 @@
     <tr class="template">
       {% if channel == 'stable' %}
       <td>0.0.0 (rev 00000)</td>
-      {% else if channel == 'beta' %}
+      {% elsif channel == 'beta' %}
       <td>0.0.0-0.0.beta (rev 00000)</td>
       {% else %}
       <td>0.0.0-0.0.dev (rev 00000)</td>

src/content/guides/environment-declarations.md

@@ -3,6 +3,7 @@ title: Configuring apps with compilation environment declarations
 description: >-
   Learn about using compilation environment declarations 
   to customize application behavior.
+lastVerified: 2023-02-23
 ---
 
 You can specify compilation environment declarations

src/content/guides/language/evolution.md

@@ -2,6 +2,7 @@
 title: Dart language evolution
 short-title: Language evolution
 description: Notable changes and additions to the Dart programming language.
+lastVerified: 2024-05-14
 ---
 
 This page lists notable changes and additions to the

src/content/guides/language/language-tour.md

@@ -8,6 +8,7 @@ js: [{url: '/assets/js/language-tour-redirector.js'}]
 sitemap: false
 canonical: https://dart.cn/language
 noindex: true
+skipFreshness: true
 ---
 
 :::warning

src/content/guides/language/sound-problems.md

@@ -496,6 +496,35 @@ var maximumOrNull =
 
 <hr>
 
+### Conflicting Superinterfaces
+
+A class which `implements` more than one superinterface must be able to
+implement valid overrides for every member of every superinterface.
+Each member with a given name requires compatible signatures across the
+superinterfaces.
+
+Superinterfaces must not include conflicting generics.
+A class can't implement both `C<A>` and `C<B>`, including indirect
+superinterfaces.
+
+#### Example
+
+In the following code,
+class `C` has conflicting generic interfaces.
+Definitions of valid overrides for some members would be impossible.
+
+<?code-excerpt "lib/common_fixes_analysis.dart (conflicting-generics)"?>
+```dart tag=fails-sa
+abstract class C implements List<int>, Iterable<num> {}
+```
+
+#### Fix: Use consistent generics or avoid repeating transitive interfaces
+
+<?code-excerpt "lib/common_fixes_analysis.dart (compatible-generics)"?>
+```dart tag=passes-sa
+abstract class C implements List<int> {}
+```
+
 <a id="common-errors-and-warnings"></a>
 
 ## Runtime errors

src/content/guides/libraries/create-packages.md

@@ -15,7 +15,6 @@ This page tells you how to create a standard shared
 本章将通过最常见的 [Package](/tools/pub/glossary#package)
 来介绍如何创建一个 Package。
 
-
 ## Creating a new package
 
 ## 创建一个新的 package
@@ -32,10 +31,6 @@ and the `package` template:
 $ dart create -t package <PACKAGE_NAME>
 ```
 
-{% comment %}
-TODO: Add coverage of packages that contain tools.
-{% endcomment %}
-
 ## What makes a package
 
 ## Package 的组成
@@ -101,12 +96,17 @@ you have a situation where two classes are tightly coupled.
 
 :::note
 
-You may have heard of the `part` directive, which allows
-you to split a library into multiple Dart files. We recommend
-that you avoid using `part` and create mini libraries instead.
-
-在文件的头部使用 `part` 命令，能够将一个 Library 分割成多个 Dart 文件。
-这里，我们建议应该创建 Mini Library ，而避免使用 `part` 命令。
+You might know about the `part` directive.
+This directive allows you to split a library into multiple Dart files.
+Though part files can incorporate generated code into a library,
+the Dart team doesn't recommend using them.
+Instead, create small libraries.
+
+你也许知道 `part` 指令。
+该指令允许你将一个 library 分割成多个 Dart 文件。
+虽然 part 文件可以将生成的代码整合到 library 中，
+但 Dart 团队并不推荐使用它们。
+取而代之更推荐创建 Mini Library。
 
 :::
 

src/content/guides/libraries/library-tour.md

@@ -6,6 +6,7 @@ js: [{url: '/assets/js/library-tour-redirector.js'}]
 sitemap: false
 canonical: https://dart.cn/libraries
 noindex: true
+skipFreshness: true
 ---
 
 :::warning

src/content/interop/js-interop/mock.md

@@ -97,9 +97,10 @@ void main() {
 
 `@JSExport` allows you to declare a class that can be used in
 `createJSInteropWrapper`. `createJSInteropWrapper` will create an object literal
-that maps each of the class' instance member names (or renames) to a JS callback
-that triggers the instance member when called. In the above example, getting and
-setting `counter.value` gets and sets `fakeCounter.value`.
+that maps each of the class' instance member names (or renames) to a JS
+callback, which is created using [`Function.toJS`]. When called, the JS callback
+will in turn call the instance member. In the above example, getting and setting
+`counter.value` gets and sets `fakeCounter.value`.
 
 You can specify only some members of a class to be exported by omitting the
 annotation from the class and instead only annotate the specific members. You
@@ -117,6 +118,7 @@ non-instance members unless the user explicitly replaces the real API in JS.
 
 [Usage]: /interop/js-interop/usage
 [`createJSInteropWrapper`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/createJSInteropWrapper.html
+[`Function.toJS`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/FunctionToJSExportedDartFunction/toJS.html
 [`@JSExport`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/JSExport-class.html
 [limitation is true for extension members]: {{site.repo.dart.org}}/mockito/blob/master/FAQ.md#how-do-i-mock-an-extension-method
 [extension types]: /language/extension-types

src/content/interop/js-interop/usage.md

@@ -389,6 +389,45 @@ but can often be elided on and within interop types and on extension members as
 the compiler can tell it is a JS interop type from the representation type and
 on-type.
 
+## Exporting Dart functions and objects to JS
+
+The above sections show how to call JS members from Dart. It's also useful to
+*export* Dart code so that it can be used in JS. To export a Dart function to
+JS, first convert it using [`Function.toJS`], which wraps the Dart function with
+a JS function. Then, pass the wrapped function to JS through an interop member.
+At that point, it's ready to be called by other JS code.
+
+For example, this code converts a Dart function and uses interop to set it in a
+global property, which is then called in JS:
+
+```dart
+import 'dart:js_interop';
+
+@JS()
+external set exportedFunction(JSFunction value);
+
+void printString(JSString string) {
+  print(string.toDart);
+}
+
+void main() {
+  exportedFunction = printString.toJS;
+}
+```
+
+```js
+globalThis.exportedFunction('hello world');
+```
+
+Functions that are exported this way have type [restrictions] similar to those
+of interop members.
+
+Sometimes it's useful to export an entire Dart interface so that JS can interact
+with a Dart object. To do this, mark the Dart class as exportable using
+[`@JSExport`] and wrap instances of that class using [`createJSInteropWrapper`].
+For a more detailed explanation of this technique, including how to mock JS
+values, see the [mocking tutorial].
+
 ## `dart:js_interop` and `dart:js_interop_unsafe`
 
 [`dart:js_interop`] contains all the necessary members you should need,
@@ -443,6 +482,10 @@ TODO: Some of these are not available on stable. How do we link to dev?
 [property accessors]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Property_accessors#bracket_notation
 [utility functions]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/JSAnyOperatorExtension.html
 [`@JS()`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/JS-class.html
+[`Function.toJS`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/FunctionToJSExportedDartFunction/toJS.html
+[`@JSExport`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/JSExport-class.html
+[`createJSInteropWrapper`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/createJSInteropWrapper.html
+[mocking tutorial]: /interop/js-interop/mock
 [`dart:js_interop`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop
 [`globalContext`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/globalContext.html
 [Helpers to inspect the type of JS values]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-js_interop/JSAnyUtilityExtension.html

src/content/language/concurrency.md

@@ -3,6 +3,7 @@ title: Concurrency in Dart
 description: >-
   Use isolates to enable parallel code execution on multiple processor cores.
 short-title: Concurrency
+lastVerified: 2023-12-14
 prevpage:
   url: /language/modifier-reference
   title: Class modifiers reference
@@ -238,7 +239,8 @@ shared-memory threads running concurrently. However, shared-state concurrency is
 lead to complicated code.
 
 Instead of threads, all Dart code runs inside isolates.
-Using isolates, your Dart code can perform multiple independent tasks at once.
+Using isolates, your Dart code can perform multiple independent tasks at once,
+using additional processor cores if they're available.
 Isolates are like threads or processes, but each isolate has its own memory
 and a single thread running an event loop.
 
@@ -252,11 +254,6 @@ won't occur in Dart. That said, isolates don't prevent race conditions all
 together. For more information on this concurrency model, read about
 the [Actor model](https://en.wikipedia.org/wiki/Actor_model).
 
-Using isolates, your Dart code can perform multiple independent tasks at once,
-using additional processor cores if they're available. Isolates are like threads
-or processes, but each isolate has its own memory and a single thread running an
-event loop. 
-
 :::note Platform note
 Only the [Dart Native platform][] implements isolates.
 To learn more about the Dart Web platform,

src/content/language/functions.md

@@ -280,7 +280,7 @@ An anonymous function resembles a named function as it has:
 The following code block contains the function's body:
 
 ```dart
-([[Type]] param1[, ...]]) {
+([[Type] param1[, ...]]) {
   codeBlock;
 }
 ```

src/content/language/index.md

@@ -19,7 +19,7 @@ To learn more about the Dart language,
 visit the in-depth, individual topic pages
 listed under **Language** in the left side menu.
 
-想要深度学习 Dart 语言，请访问左侧栏 **语言** 的具体内容。
+想要深度学习 Dart 语言，请访问左侧栏 **Dart 开发语言** 的具体内容。
 
 For coverage of Dart's core libraries,
 check out the [core library documentation](/libraries).

src/content/language/isolates.md

@@ -2,6 +2,7 @@
 title: Isolates
 description: Information on writing isolates in Dart.
 short-title: Isolates
+lastVerified: 2024-01-04
 prevpage:
   url: /language/async
   title: Asynchronous support