[sync] 2024/07/03

.github/workflows/build.yml

@@ -31,7 +31,7 @@ jobs:
             experimental: false
     continue-on-error: ${{ matrix.experimental }}
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           submodules: recursive
       - uses: subosito/flutter-action@44ac965b96f18d999802d4b807e3256d5a3f9fa1
@@ -55,16 +55,16 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository == 'cfug/flutter.cn'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           submodules: recursive
-      - uses: dart-lang/setup-dart@f0ead981b4d9a35b37f30d36160575d60931ec30
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
         with:
           sdk: stable
       - name: Fetch Dart dependencies
         run: dart pub get
       - name: Check if excerpts are up to date
-        run: dart run flutter_site refresh-excerpts --fail-on-update
+        run: dart run flutter_site refresh-excerpts --fail-on-update --dry-run
         continue-on-error: ${{ matrix.experimental }}
 
   linkcheck:
@@ -73,7 +73,7 @@ jobs:
     if: |
       github.repository == 'cfug/flutter.cn'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           submodules: recursive
       - name: Enable Corepack
@@ -86,7 +86,7 @@ jobs:
         run: corepack install
       - name: Install node dependencies
         run: pnpm install --frozen-lockfile
-      - uses: dart-lang/setup-dart@f0ead981b4d9a35b37f30d36160575d60931ec30
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
         with:
           sdk: stable
       - name: Fetch Dart dependencies
@@ -106,10 +106,10 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository == 'cfug/flutter.cn'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           submodules: recursive
-      - uses: dart-lang/setup-dart@f0ead981b4d9a35b37f30d36160575d60931ec30
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
         with:
           sdk: stable
       - name: Fetch Dart dependencies
@@ -126,7 +126,7 @@ jobs:
       github.ref == 'refs/heads/main' &&
       github.repository == 'cfug/flutter.cn'
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           submodules: recursive
       - name: Enable Corepack
@@ -139,7 +139,7 @@ jobs:
         run: corepack install
       - name: Install node dependencies
         run: pnpm install --frozen-lockfile
-      - uses: dart-lang/setup-dart@f0ead981b4d9a35b37f30d36160575d60931ec30
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
         with:
           sdk: stable
       - name: Fetch Dart dependencies

.github/workflows/compile_host_redirect_js.yml

@@ -40,6 +40,7 @@ jobs:
           add-paths: |
             ./src/content/assets/js/host-redirect.min.js
           title: '[🤖bot] Update: host-redirect.min.js'
+          body: 'GitHub Action: [.github/workflows/compile_host_redirect_js.yml](https://github.com/cfug/flutter.cn/blob/main/.github/workflows/compile_host_redirect_js.yml)'
           committer: 'cfug-dev <[email protected]>'
           commit-message: '[🤖bot] Update: host-redirect.min.js'
           branch-suffix: timestamp

.github/workflows/stage.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.event.pull_request.head.repo.full_name == 'cfug/flutter.cn' }}
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           submodules: recursive
       - name: Enable Corepack
@@ -33,7 +33,7 @@ jobs:
         run: corepack install
       - name: Install node dependencies
         run: pnpm install --frozen-lockfile
-      - uses: dart-lang/setup-dart@f0ead981b4d9a35b37f30d36160575d60931ec30
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
         with:
           sdk: stable
       - name: Fetch Dart dependencies

AUTHORS

@@ -17,3 +17,4 @@ Hidenori Matsubayashi <[email protected]>
 Pradumna Saraf <[email protected]>
 Alex Li <[email protected]>
 Parker Lougheed <[email protected]>
+LinXunFeng <[email protected]>

CONTRIBUTING.md

@@ -60,5 +60,5 @@ Happy Fluttering!
 [doc-PRs]: https://github.com/flutter/website/pulls
 [so]: https://stackoverflow.com/tags/flutter
 [mailinglist]: https://groups.google.com/d/forum/flutter-dev
-[chat]: https://github.com/flutter/flutter/wiki/Chat
+[chat]: https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
 [reddit]: https://www.reddit.com/r/FlutterDev

README.md

@@ -293,23 +293,28 @@ and we'll try our best to help you.
 You can also chat with us on the `#hackers-devrel` channel
 on the [Flutter contributors Discord][]!
 
-[Flutter contributors Discord]: https://github.com/flutter/flutter/wiki/Chat
+[Flutter contributors Discord]: https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
 
 ### Refresh code excerpts
 
 A build that fails with the error
 `Error: Some code excerpts needed to be updated!`
-means that one or more code excerpts in the markdown file
-aren't identical to the
-code in the corresponding `.dart` file.
+means that one or more code excerpts in the site Markdown files
+aren't identical to the code regions declared
+in the corresponding `.dart` files.
 
-To resolve this error,
+The `.dart` files are the source of truth for code snippets,
+and the preceding `<?code-excerpt>` instructions in Markdown files specify
+how the snippets are copied from the `.dart` files. 
+
+To resolve this error and update the Markdown snippets to match,
 from the root of the `website` directory,
 run `./dash_site refresh-excerpts`.
 
-For more information see [Code excerpts][] .
+To learn more about creating, editing, and using code excerpts,
+check out the [excerpt updater package documentation][].
 
-[Code excerpts]: https://github.com/dart-lang/site-shared/blob/main/doc/code-excerpts.md
+[excerpt updater package documentation]: https://github.com/dart-lang/site-shared/tree/main/packages/excerpter#readme
 
 ## [Optional] Deploy to a staging site
 

eleventy.config.js

@@ -2,14 +2,8 @@
 // It configures the core 11ty behavior and registers
 // plugins and customization that live in `/src/_11ty`.
 
-import {
-  activeNavForPage,
-  arrayToSentenceString,
-  breadcrumbsForPage,
-  generateToc,
-  regexReplace,
-  toISOString,
-} from './src/_11ty/filters.js';
+import { registerFilters } from './src/_11ty/filters.js';
+import { registerShortcodes } from './src/_11ty/shortcodes.js';
 import { markdown } from './src/_11ty/plugins/markdown.js';
 import { configureHighlighting } from './src/_11ty/plugins/highlight.js';
 
@@ -27,6 +21,7 @@ import * as sass from 'sass';
  */
 export default function (eleventyConfig) {
   const isProduction = process.env.PRODUCTION === 'true';
+  const shouldOptimize = process.env.OPTIMIZE === 'true';
 
   eleventyConfig.on('eleventy.before', async () => {
     await configureHighlighting(markdown);
@@ -49,68 +44,8 @@ export default function (eleventyConfig) {
 
   eleventyConfig.addPlugin(EleventyRenderPlugin);
 
-  let _currentTabsTitle = '';
-  let _currentTabIsActive = false;
-
-  // TODO(parlough): Replace samplecode with something easier.
-  eleventyConfig.addShortcode('samplecode', function (tabsTitle, tabsString) {
-    _currentTabsTitle = tabsTitle.toLowerCase();
-    let tabMarkup = `<ul class="nav nav-tabs sample-code-tabs" id="${_currentTabsTitle}-language" role="tablist">`;
-
-    let activeTab = true;
-    _currentTabIsActive = true;
-
-    const tabs = tabsString.split(',').map((tab) => tab.trim());
-    tabs.forEach((tabName) => {
-      const tabId = `${_currentTabsTitle}-${tabName.toLowerCase().replaceAll("+", "-plus")}`;
-      tabMarkup += `<li class="nav-item">
-  <a class="nav-link ${activeTab ? "active" : ""}" id="${tabId}-tab" href="#${tabId}" role="tab" aria-controls="${tabId}" aria-selected="true">${tabName}</a>
-</li>`;
-      activeTab = false;
-    });
-
-    tabMarkup += `</ul><div class="tab-content">
-`;
-    return tabMarkup;
-  });
-
-  eleventyConfig.addShortcode('endsamplecode', function () {
-    return `</div>`
-  });
-
-  eleventyConfig.addPairedShortcode('sample', function (content, tabName) {
-    const tabId = `${_currentTabsTitle}-${tabName.toLowerCase().replaceAll("+", "-plus")}`;
-    const tabContent = `<div class="tab-pane ${_currentTabIsActive ? "active" : ""}" id="${tabId}" role="tabpanel" aria-labelledby="${tabId}-tab">
-
-${content}
-
-</div>
-`;
-
-    _currentTabIsActive = false;
-
-    return tabContent;
-  });
-
-  // TODO(parlough): Make this more generic.
-  eleventyConfig.addFilter('children_pages', function (pages, pageUrl) {
-    return pages.filter((page) => page.url.includes(pageUrl) && page.url !== pageUrl);
-  });
-
-  // TODO(parlough): Make this more generic.
-  eleventyConfig.addFilter('widget_filter', function (widgets, field, subName) {
-    return widgets.filter((comp) => comp[field]?.includes(subName) ?? false);
-  });
-
-  eleventyConfig.addFilter('regex_replace', regexReplace);
-  eleventyConfig.addFilter('toISOString', toISOString);
-  eleventyConfig.addFilter('active_nav_for_page', activeNavForPage);
-  eleventyConfig.addFilter('array_to_sentence_string', arrayToSentenceString);
-  eleventyConfig.addFilter('throw_error', function (error) {
-    throw new Error(error);
-  });
-  eleventyConfig.addFilter('generate_toc', generateToc);
-  eleventyConfig.addFilter('breadcrumbsForPage', breadcrumbsForPage);
+  registerFilters(eleventyConfig);
+  registerShortcodes(eleventyConfig);
 
   eleventyConfig.addTemplateFormats('scss');
   eleventyConfig.addWatchTarget('src/_sass');
@@ -123,7 +58,7 @@ ${content}
       }
 
       const result = sass.compileString(inputContent, {
-        style: isProduction ? 'compressed' : 'expanded',
+        style: shouldOptimize ? 'compressed' : 'expanded',
         quietDeps: true,
         loadPaths: [parsedPath.dir, 'src/_sass'],
       });
@@ -156,7 +91,7 @@ ${content}
     filter: (path) => path.includes('src') || path.includes('images'),
   });
 
-  if (isProduction) {
+  if (shouldOptimize) {
     // If building for production, minify/optimize the HTML output.
     // Doing so during serving isn't worth the extra build time.
     eleventyConfig.addTransform('minify-html', async function (content) {

examples/animation/animate3/lib/main.dart

@@ -62,3 +62,4 @@ class _LogoAppState extends State<LogoApp> with SingleTickerProviderStateMixin {
   }
   // #docregion print-state
 }
+// #enddocregion print-state

examples/animation/animate4/lib/main.dart

@@ -2,11 +2,11 @@ import 'package:flutter/material.dart';
 
 void main() => runApp(const LogoApp());
 
-// #docregion LogoWidget
+// #docregion logo-widget
 class LogoWidget extends StatelessWidget {
   const LogoWidget({super.key});
 
-  // Leave out the height and width so it fills the animating parent
+  // Leave out the height and width so it fills the animating parent.
   @override
   Widget build(BuildContext context) {
     return Container(
@@ -15,9 +15,9 @@ class LogoWidget extends StatelessWidget {
     );
   }
 }
-// #enddocregion LogoWidget
+// #enddocregion logo-widget
 
-// #docregion GrowTransition
+// #docregion grow-transition
 class GrowTransition extends StatelessWidget {
   const GrowTransition(
       {required this.child, required this.animation, super.key});
@@ -42,7 +42,7 @@ class GrowTransition extends StatelessWidget {
     );
   }
 }
-// #enddocregion GrowTransition
+// #enddocregion grow-transition
 
 class LogoApp extends StatefulWidget {
   const LogoApp({super.key});
@@ -81,3 +81,4 @@ class _LogoAppState extends State<LogoApp> with SingleTickerProviderStateMixin {
   }
   // #docregion print-state
 }
+// #enddocregion print-state

examples/animation/animate5/lib/main.dart

@@ -47,10 +47,10 @@ class _LogoAppState extends State<LogoApp> with SingleTickerProviderStateMixin {
   @override
   void initState() {
     super.initState();
-    // #docregion AnimationController, tweens
+    // #docregion animation-controller, tweens
     controller =
         AnimationController(duration: const Duration(seconds: 2), vsync: this);
-    // #enddocregion AnimationController, tweens
+    // #enddocregion animation-controller, tweens
     animation = CurvedAnimation(parent: controller, curve: Curves.easeIn)
       ..addStatusListener((status) {
         if (status == AnimationStatus.completed) {

examples/cookbook/animation/physics_simulation/lib/step2.dart

@@ -38,14 +38,14 @@ class _DraggableCardState extends State<DraggableCard>
   // #enddocregion alignment
   // #enddocregion animation
 
-  // #docregion initState
+  // #docregion init-state
   @override
   void initState() {
     super.initState();
     _controller =
         AnimationController(vsync: this, duration: const Duration(seconds: 1));
   }
-  // #enddocregion initState
+  // #enddocregion init-state
 
   @override
   void dispose() {

examples/cookbook/animation/physics_simulation/lib/step3.dart

@@ -37,7 +37,7 @@ class _DraggableCardState extends State<DraggableCard>
   Alignment _dragAlignment = Alignment.center;
   // #enddocregion animation
 
-  // #docregion initState
+  // #docregion init-state
   @override
   void initState() {
     super.initState();
@@ -49,7 +49,7 @@ class _DraggableCardState extends State<DraggableCard>
       });
     });
   }
-  // #enddocregion initState
+  // #enddocregion init-state
 
   @override
   void dispose() {