feat: migrate figure and captioned images to jaspr (#12586)

Part of #12548 

Migrates both the `app-figure.md` and `captioned-image.md` files to a
`DashImage` Jaspr component.

Author: schultek

site/lib/main.dart

@@ -11,6 +11,7 @@ import 'jaspr_options.dart'; // Generated. Do not remove or edit.
 import 'src/components/card.dart';
 import 'src/components/client/archive_table.dart';
 import 'src/components/client/download_latest_button.dart';
+import 'src/components/dash_image.dart';
 import 'src/components/expansion_list.dart';
 import 'src/components/os_selector.dart';
 import 'src/components/pages/devtools_release_notes_index.dart';
@@ -71,6 +72,7 @@ final RegExp _passThroughPattern = RegExp(r'.*\.(txt|json|pdf)$');
 /// Custom "components" that can be used from Markdown files.
 List<CustomComponent> get _embeddableComponents => [
   const DashTabs(),
+  const DashImage(),
   CustomComponent(
     pattern: RegExp('OSSelector', caseSensitive: false),
     builder: (name, attributes, child) {

site/lib/src/components/dash_image.dart

@@ -0,0 +1,62 @@
+// Copyright 2025 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:jaspr/jaspr.dart';
+import 'package:jaspr_content/jaspr_content.dart';
+
+import '../markdown/markdown_parser.dart';
+
+class DashImage with CustomComponentBase {
+  const DashImage();
+
+  @override
+  Pattern get pattern => RegExp('DashImage', caseSensitive: false);
+
+  @override
+  Component apply(_, Map<String, String> attributes, _) {
+    final isFigure = attributes.containsKey('figure');
+    final imgSrc =
+        attributes['image'] ??
+        (throw Exception(
+          '<DashImage> component requires an "image" attribute.',
+        ));
+
+    final caption = attributes['caption'] ?? '';
+    final alt = attributes['alt'] ?? caption;
+
+    final figureClass = isFigure ? attributes['class'] : null;
+    final imgClass = attributes[isFigure ? 'img-class' : 'class'];
+
+    final style = [
+      if (attributes['img-style'] case final s?) s,
+      if (attributes['width'] case final w?) 'width: $w',
+      if (attributes['height'] case final h?) 'height: $h',
+    ].map((s) => s.trim()).map((s) => s.endsWith(';') ? s : '$s;').join(' ');
+
+    final child = Component.fragment([
+      img(
+        src: '/assets/images/docs/$imgSrc',
+        alt: alt,
+        classes: imgClass,
+        attributes: {
+          if (style.isNotEmpty) 'style': style,
+        },
+      ),
+      if (caption.isNotEmpty)
+        figcaption(classes: 'figure-caption', [
+          DashMarkdown(content: caption),
+        ]),
+    ]);
+
+    if (isFigure) {
+      return figure(classes: figureClass, [
+        div(classes: 'site-figure-container', [
+          child,
+        ]),
+      ]);
+    }
+
+    return child;
+  }
+}

src/_includes/docs/add-to-app/ios-project/link-and-embed.md

@@ -18,7 +18,7 @@ To link the necessary frameworks, follow this procedure.
 
    1. Expand **Link Binary With Libraries**.
 
-      {% render "docs/captioned-image.md", image:"development/add-to-app/ios/project-setup/linked-libraries.png", caption:"Expand the **Link Binary With Libraries** build phase in Xcode" %}
+      <DashImage image="development/add-to-app/ios/project-setup/linked-libraries.png" caption="Expand the **Link Binary With Libraries** build phase in Xcode" />
 
    1. Click **+** (plus sign).
 
@@ -29,7 +29,7 @@ To link the necessary frameworks, follow this procedure.
 
    1. Command-click the frameworks in that directory then click **Open**.
 
-      {% render "docs/captioned-image.md", image:"development/add-to-app/ios/project-setup/choose-libraries.png", caption:"Choose frameworks to link from the **Choose frameworks and libraries to add:** dialog box in Xcode" %}
+      <DashImage image="development/add-to-app/ios/project-setup/choose-libraries.png" caption="Choose frameworks to link from the **Choose frameworks and libraries to add:** dialog box in Xcode" />
 
 1. Update the paths to the libraries to account for build modes.
 
@@ -43,7 +43,7 @@ To link the necessary frameworks, follow this procedure.
    1. Open `project.pbxproj` with Xcode. The file opens in Xcode's text
       editor. This also locks **Project Navigator** until you close the text editor.
 
-      {% render "docs/captioned-image.md", image:"development/add-to-app/ios/project-setup/project-pbxproj.png", caption:"The `project-pbxproj` file open in the Xcode text editor" %}
+      <DashImage image="development/add-to-app/ios/project-setup/project-pbxproj.png" caption="The `project-pbxproj` file open in the Xcode text editor" />
 
    1. Find the lines that resemble the following text in the
       `/* Begin PBXFileReference section */`.
@@ -106,7 +106,7 @@ To link the necessary frameworks, follow this procedure.
    1. Type `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`
       and press <kbd>Enter</kbd>.
 
-      {% render "docs/captioned-image.md", image:"development/add-to-app/ios/project-setup/framework-search-paths.png", caption:"Update **Framework Search Paths** in Xcode" %}
+      <DashImage image="development/add-to-app/ios/project-setup/framework-search-paths.png" caption="Update **Framework Search Paths** in Xcode" />
 
 After linking the frameworks, they should display in the
 **Frameworks, Libraries, and Embedded Content**
@@ -121,7 +121,7 @@ To embed your dynamic frameworks, complete the following procedure.
 
 1. Click on each of your dynamic frameworks and select **Embed & Sign**.
 
-   {% render "docs/captioned-image.md", image:"development/add-to-app/ios/project-setup/choose-to-embed.png", caption:"Select **Embed & Sign** for each of your frameworks in Xcode" %}
+   <DashImage image="development/add-to-app/ios/project-setup/choose-to-embed.png" caption="Select **Embed & Sign** for each of your frameworks in Xcode" />
 
    Don't include any static frameworks,
    including `FlutterPluginRegistrant.xcframework`.
@@ -131,7 +131,7 @@ To embed your dynamic frameworks, complete the following procedure.
 1. Expand **Embed Frameworks**.
    Your dynamic frameworks should display in that section.
 
-   {% render "docs/captioned-image.md", image:"development/add-to-app/ios/project-setup/embed-xcode.png", caption:"The expanded **Embed Frameworks** build phase in Xcode" %}
+   <DashImage image="development/add-to-app/ios/project-setup/embed-xcode.png" caption="The expanded **Embed Frameworks** build phase in Xcode" />
 
 1. Build the project.
 

src/_includes/docs/app-figure.md

@@ -22,20 +22,20 @@ the following files in your issue:
 1. Open your app (`ios/Runner.xcworkspace`) in Xcode.
 1. Navigate to **Package Dependencies** for the project.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/package-dependencies.png", caption:"The project's package dependencies" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/package-dependencies.png" caption="The project's package dependencies" />
 
 1. Click <span class="material-symbols" translate="no">add</span>.
 1. In the dialog that opens, click **Add Local...**.
 1. Navigate to `ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage`
    and click **Add Package**.
 1. Ensure that it's added to the `Runner` target and click **Add Package**.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/choose-package-products.png", caption:"Ensure that the package is added to the `Runner` target" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/choose-package-products.png" caption="Ensure that the package is added to the `Runner` target" />
 
 1. Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks,
    Libraries, and Embedded Content**.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/add-generated-framework.png", caption:"Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/add-generated-framework.png" caption="Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**" />
 
 ### Step 2: Add Run Prepare Flutter Framework Script Pre-Action {:.no_toc}
 
@@ -59,15 +59,15 @@ the following files in your issue:
    "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare
    ```
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/add-flutter-pre-action.png", caption:"Add **Run Prepare Flutter Framework Script** build pre-action" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/add-flutter-pre-action.png" caption="Add **Run Prepare Flutter Framework Script** build pre-action" />
 
 ### Step 3: Run app {:.no_toc}
 
 1. Run the app in Xcode.
 1. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
    and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png", caption:"Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png" caption="Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" />
 
 1. Ensure that the app runs on the command line with `flutter run`.
 

src/_includes/docs/captioned-image.md

@@ -30,7 +30,7 @@ To migrate your project:
 1. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
    and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png", caption:"Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png" caption="Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" />
 
 [Turn on Swift Package Manager]: /packages-and-plugins/swift-package-manager/for-app-developers/#how-to-turn-on-swift-package-manager
 [manualIntegration]: /packages-and-plugins/swift-package-manager/for-app-developers/#add-to-a-flutter-app-manually

src/_includes/docs/swift-package-manager/migrate-ios-project-manually.md

@@ -22,20 +22,20 @@ the following files in your issue:
 1. Open your app (`macos/Runner.xcworkspace`) in Xcode.
 1. Navigate to **Package Dependencies** for the project.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/package-dependencies.png", caption:"The project's package dependencies" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/package-dependencies.png" caption="The project's package dependencies" />
 
 1. Click <span class="material-symbols" translate="no">add</span>.
 1. In the dialog that opens, click the **Add Local...**.
 1. Navigate to `macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage`
    and click the **Add Package**.
 1. Ensure that it's added to the Runner Target and click **Add Package**.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/choose-package-products.png", caption:"Ensure that the package is added to the `Runner` target" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/choose-package-products.png" caption="Ensure that the package is added to the `Runner` target" />
 
 1. Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks,
    Libraries, and Embedded Content**.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/add-generated-framework.png", caption:"Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/add-generated-framework.png" caption="Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**" />
 
 ### Step 2: Add Run Prepare Flutter Framework Script Pre-Action {:.no_toc}
 
@@ -59,15 +59,15 @@ the following files in your issue:
    "$FLUTTER_ROOT"/packages/flutter_tools/bin/macos_assemble.sh prepare
    ```
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/add-flutter-pre-action.png", caption:"Add **Run Prepare Flutter Framework Script** build pre-action" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/add-flutter-pre-action.png" caption="Add **Run Prepare Flutter Framework Script** build pre-action" />
 
 ### Step 3: Run app {:.no_toc}
 
 1. Run the app in Xcode.
 1. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
    and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png", caption:"Ensure `Run Prepare Flutter Framework Script` runs as a pre-action" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png" caption="Ensure `Run Prepare Flutter Framework Script` runs as a pre-action" />
 
 1. Ensure that the app runs on the command line with `flutter run`.
 

src/_includes/docs/swift-package-manager/migrate-ios-project.md

@@ -30,7 +30,7 @@ To migrate your project:
 1. Ensure that  **Run Prepare Flutter Framework Script** runs as a pre-action
    and that `FlutterGeneratedPluginSwiftPackage` is a target dependency.
 
-   {% render "docs/captioned-image.md", image:"development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png", caption:"Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" %}
+   <DashImage image="development/packages-and-plugins/swift-package-manager/flutter-pre-action-build-log.png" caption="Ensure **Run Prepare Flutter Framework Script** runs as a pre-action" />
 
 [Turn on Swift Package Manager]: /packages-and-plugins/swift-package-manager/for-app-developers/#how-to-turn-on-swift-package-manager
 [manualIntegration]: /packages-and-plugins/swift-package-manager/for-app-developers/#add-to-a-flutter-app-manually

src/_includes/docs/swift-package-manager/migrate-macos-project-manually.md

@@ -278,7 +278,7 @@ flutter build aar
 
 Then, follow the on-screen instructions to integrate.
 
-{% render "docs/app-figure.md", image:"development/add-to-app/android/project-setup/build-aar-instructions.png" %}
+<DashImage figure image="development/add-to-app/android/project-setup/build-aar-instructions.png" />
 
 More specifically, this command creates
 (by default all debug/profile/release modes)
@@ -417,7 +417,7 @@ check out [Using Flutter in China][] page.
 You can also build an AAR for your Flutter module in Android Studio using
 the `Build > Flutter > Build AAR` menu.
 
-{% render "docs/app-figure.md", image:"development/add-to-app/android/project-setup/ide-build-aar.png" %}
+<DashImage figure image="development/add-to-app/android/project-setup/ide-build-aar.png"/>
 :::
 
 </Tab>