From ee00ad9e4d1ea4ce0704e5a8f8cf5a0fe5fd9b1e Mon Sep 17 00:00:00 2001 From: Kilian Schulte Date: Mon, 3 Nov 2025 09:43:21 +0100 Subject: [PATCH 1/4] Add FileTree component to docs --- site/lib/_sass/components/_code.scss | 22 +++++ site/lib/jaspr_options.dart | 3 +- site/lib/main.dart | 2 + site/lib/src/components/common/tabs.dart | 4 +- site/lib/src/style_hash.dart | 2 +- site/pubspec.yaml | 7 ++ .../add-to-app/ios-project/embed-cocoapods.md | 19 +++-- .../embed-framework-directory-tree.md | 40 ++++----- .../migrate-objective-c-plugin.md | 32 +++++--- .../migrate-swift-plugin.md | 31 ++++--- .../add-to-app/android/project-setup.md | 44 +++++----- src/content/add-to-app/ios/project-setup.md | 23 +++--- .../app-architecture/case-study/index.md | 82 +++++++++---------- .../flutter-for/react-native-devs.md | 31 +++---- 14 files changed, 194 insertions(+), 148 deletions(-) diff --git a/site/lib/_sass/components/_code.scss b/site/lib/_sass/components/_code.scss index 66ef2bd3219..e66748563ad 100644 --- a/site/lib/_sass/components/_code.scss +++ b/site/lib/_sass/components/_code.scss @@ -254,3 +254,25 @@ iframe[src^="https://dartpad"] { resize: vertical; width: 100%; } + +.file-tree { + --file-tree-bg: var(--site-inset-bgColor); + --file-tree-text: var(--site-base-fgColor); + --file-tree-icon: var(--site-base-fgColor-alt); + --file-tree-highlight: var(--site-link-fgColor); + + font-family: var(--site-code-fontFamily); + + border: 1px solid var(--site-inset-borderColor); + margin-block-start: 1rem; + margin-block-end: 1rem; + + details { + margin: unset; + + summary { + font-weight: unset; + user-select: unset; + } + } +} \ No newline at end of file diff --git a/site/lib/jaspr_options.dart b/site/lib/jaspr_options.dart index 831027edc6c..74202dc61e1 100644 --- a/site/lib/jaspr_options.dart +++ b/site/lib/jaspr_options.dart @@ -33,6 +33,7 @@ import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_fil as prefix12; import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters_sidebar.dart' as prefix13; +import 'package:jaspr_content/components/file_tree.dart' as prefix14; /// Default [JasprOptions] for use with your jaspr project. /// @@ -115,7 +116,7 @@ JasprOptions get defaultJasprOptions => JasprOptions( 'src/components/pages/learning_resource_filters_sidebar', ), }, - styles: () => [], + styles: () => [...prefix14.FileTree.styles], ); Map _prefix2CopyButton(prefix2.CopyButton c) => { diff --git a/site/lib/main.dart b/site/lib/main.dart index 04c6037d586..c81a2ee9c21 100644 --- a/site/lib/main.dart +++ b/site/lib/main.dart @@ -3,6 +3,7 @@ // found in the LICENSE file. import 'package:jaspr/server.dart'; +import 'package:jaspr_content/components/file_tree.dart'; import 'package:jaspr_content/jaspr_content.dart'; import 'package:jaspr_content/theme.dart'; import 'package:path/path.dart' as path; @@ -75,6 +76,7 @@ List get _embeddableComponents => [ const DashTabs(), const DashImage(), const YoutubeEmbed(), + const FileTree(), CustomComponent( pattern: RegExp('OSSelector', caseSensitive: false), builder: (_, _, _) => const OsSelector(), diff --git a/site/lib/src/components/common/tabs.dart b/site/lib/src/components/common/tabs.dart index 026eca8676f..ae684abe0b3 100644 --- a/site/lib/src/components/common/tabs.dart +++ b/site/lib/src/components/common/tabs.dart @@ -8,11 +8,11 @@ import 'package:jaspr_content/jaspr_content.dart'; import '../../util.dart'; /// A tabs component where children tabs can be switched between by the user. -class DashTabs implements CustomComponent { +class DashTabs extends CustomComponent { static int _currentTabWrapperId = 0; static int _currentTabId = 0; - const DashTabs(); + const DashTabs() : super.base(); @override Component? create(Node node, NodesBuilder builder) { diff --git a/site/lib/src/style_hash.dart b/site/lib/src/style_hash.dart index 758bd7907d3..fe0d833938b 100644 --- a/site/lib/src/style_hash.dart +++ b/site/lib/src/style_hash.dart @@ -2,4 +2,4 @@ // dart format off /// The generated hash of the `main.css` file. -const generatedStylesHash = 'nvTevrLjFn98'; +const generatedStylesHash = 'HKnanMAZrYgJ'; diff --git a/site/pubspec.yaml b/site/pubspec.yaml index bfb581f28ad..231f3b64067 100644 --- a/site/pubspec.yaml +++ b/site/pubspec.yaml @@ -37,5 +37,12 @@ dev_dependencies: sass: ^1.93.2 sass_builder: ^2.4.0 +dependency_overrides: + jaspr_content: + git: + url: https://github.com/schultek/jaspr + path: packages/jaspr_content + ref: feat/file-tree + jaspr: mode: static diff --git a/src/_includes/docs/add-to-app/ios-project/embed-cocoapods.md b/src/_includes/docs/add-to-app/ios-project/embed-cocoapods.md index e2a6e406325..446d9fd9ef8 100644 --- a/src/_includes/docs/add-to-app/ios-project/embed-cocoapods.md +++ b/src/_includes/docs/add-to-app/ios-project/embed-cocoapods.md @@ -35,15 +35,16 @@ If you have a different directory structure, adjust the relative paths. The example directory structure resembles the following: -```plaintext -/path/to/MyApp -├── my_flutter/ -│ └── .ios/ -│ └── Flutter/ -│ └── podhelper.rb -└── MyApp/ - └── Podfile -``` + + +- my_flutter/ + - .ios/ + - Flutter/ + - podhelper.rb +- MyApp/ + - Podfile + + #### Update your Podfile diff --git a/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md b/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md index 2295296cdde..7a62eb54c0e 100644 --- a/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md +++ b/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md @@ -9,25 +9,27 @@ Run this _every time_ you change code in your Flutter module. The resulting project structure should resemble this directory tree. -```plaintext -/path/to/MyApp/ -└── Flutter/ - ├── Debug/ - │ ├── Flutter.xcframework - │   ├── App.xcframework - │   ├── FlutterPluginRegistrant.xcframework (only if you have plugins with iOS platform code) - │   └── example_plugin.xcframework (each plugin is a separate framework) - ├── Profile/ - │ ├── Flutter.xcframework - │ ├── App.xcframework - │ ├── FlutterPluginRegistrant.xcframework - │ └── example_plugin.xcframework - └── Release/ - ├── Flutter.xcframework - ├── App.xcframework - ├── FlutterPluginRegistrant.xcframework - └── example_plugin.xcframework -``` + + +- /path/to/MyApp/ + - Flutter/ + - Debug/ + - Flutter.xcframework + - App.xcframework + - FlutterPluginRegistrant.xcframework (only if you have plugins with iOS platform code) + - example_plugin.xcframework (each plugin is a separate framework) + - Profile/ + - Flutter.xcframework + - App.xcframework + - FlutterPluginRegistrant.xcframework + - example_plugin.xcframework + - Release/ + - Flutter.xcframework + - App.xcframework + - FlutterPluginRegistrant.xcframework + - example_plugin.xcframework + + :::warning Always use `Flutter.xcframework` and `App.xcframework` bundles diff --git a/src/_includes/docs/swift-package-manager/migrate-objective-c-plugin.md b/src/_includes/docs/swift-package-manager/migrate-objective-c-plugin.md index 7eb5badaff1..6636474b8a5 100644 --- a/src/_includes/docs/swift-package-manager/migrate-objective-c-plugin.md +++ b/src/_includes/docs/swift-package-manager/migrate-objective-c-plugin.md @@ -7,11 +7,14 @@ The example below uses `ios`, replace `ios` with `macos`/`darwin` as applicable. directories. Name this new directory the name of the platform package. - ```plaintext highlightLines=3 - plugin_name/ios/ - ├── ... - └── plugin_name/ - ``` + + + - plugin_name/ + - ios/ + - ... + - **plugin_name/** + + 1. Within this new directory, create the following files/directories: @@ -27,14 +30,17 @@ The example below uses `ios`, replace `ios` with `macos`/`darwin` as applicable. Your plugin should look like: - ```plaintext highlightLines=4-6 - plugin_name/ios/ - ├── ... - └── plugin_name/ - ├── Package.swift - └── Sources/plugin_name/include/plugin_name/ - └── .gitkeep - ``` + + + - plugin_name/ + - ios/ + - ... + - plugin_name/ + - **Package.swift** + - **Sources/plugin_name/include/plugin_name/** + - **.gitkeep/** + + 1. Use the following template in the `Package.swift` file: diff --git a/src/_includes/docs/swift-package-manager/migrate-swift-plugin.md b/src/_includes/docs/swift-package-manager/migrate-swift-plugin.md index d60522e4ebf..11d51bc6ea4 100644 --- a/src/_includes/docs/swift-package-manager/migrate-swift-plugin.md +++ b/src/_includes/docs/swift-package-manager/migrate-swift-plugin.md @@ -7,11 +7,14 @@ The example below uses `ios`, replace `ios` with `macos`/`darwin` as applicable. directories. Name this new directory the name of the platform package. - ```plaintext highlightLines=3 - plugin_name/ios/ - ├── ... - └── plugin_name/ - ``` + + + - plugin_name/ + - ios/ + - ... + - **plugin_name/** + + 1. Within this new directory, create the following files/directories: @@ -21,13 +24,17 @@ The example below uses `ios`, replace `ios` with `macos`/`darwin` as applicable. Your plugin should look like: - ```plaintext highlightLines=4-5 - plugin_name/ios/ - ├── ... - └── plugin_name/ - ├── Package.swift - └── Sources/plugin_name/ - ``` + + + - plugin_name/ + - ios/ + - ... + - plugin_name/ + - **Package.swift** + - **Sources/** + - **plugin_name/** + + 1. Use the following template in the `Package.swift` file: diff --git a/src/content/add-to-app/android/project-setup.md b/src/content/add-to-app/android/project-setup.md index 7e16525ebe6..f3679a2d016 100644 --- a/src/content/add-to-app/android/project-setup.md +++ b/src/content/add-to-app/android/project-setup.md @@ -284,27 +284,29 @@ More specifically, this command creates (by default all debug/profile/release modes) a [local repository][], with the following files: -```plaintext -build/host/outputs/repo -└── com - └── example - └── flutter_module - ├── flutter_release - │ ├── 1.0 - │ │   ├── flutter_release-1.0.aar - │ │   ├── flutter_release-1.0.aar.md5 - │ │   ├── flutter_release-1.0.aar.sha1 - │ │   ├── flutter_release-1.0.pom - │ │   ├── flutter_release-1.0.pom.md5 - │ │   └── flutter_release-1.0.pom.sha1 - │ ├── maven-metadata.xml - │ ├── maven-metadata.xml.md5 - │ └── maven-metadata.xml.sha1 - ├── flutter_profile - │ ├── ... - └── flutter_debug - └── ... -``` + + +- build/host/outputs/repo + - com + - example + - flutter_module + - flutter_release + - 1.0 + - flutter_release-1.0.aar + - flutter_release-1.0.aar.md5 + - flutter_release-1.0.aar.sha1 + - flutter_release-1.0.pom + - flutter_release-1.0.pom.md5 + - flutter_release-1.0.pom.sha1 + - maven-metadata.xml + - maven-metadata.xml.md5 + - maven-metadata.xml.sha1 + - flutter_profile + - ... + - flutter_debug + - ... + + To depend on the AAR, the host app must be able to find these files. diff --git a/src/content/add-to-app/ios/project-setup.md b/src/content/add-to-app/ios/project-setup.md index a8cedc42b9d..a4588b477ef 100644 --- a/src/content/add-to-app/ios/project-setup.md +++ b/src/content/add-to-app/ios/project-setup.md @@ -60,16 +60,19 @@ This helps when testing the Flutter-only parts of your code. The `my_flutter` module directory structure resembles a typical Flutter app. -```plaintext -my_flutter/ -├── .ios/ -│ ├── Runner.xcworkspace -│ └── Flutter/podhelper.rb -├── lib/ -│ └── main.dart -├── test/ -└── pubspec.yaml -``` + + +- my_flutter/ + - .ios/ + - Runner.xcworkspace + - Flutter/ + - podhelper.rb + - lib/ + - main.dart + - test/ + - pubspec.yaml + + Your Dart code should be added to the `lib/` directory. Your Flutter dependencies, packages, and plugins must be added to the diff --git a/src/content/app-architecture/case-study/index.md b/src/content/app-architecture/case-study/index.md index f6ce2fd84d1..8c974aaca3b 100644 --- a/src/content/app-architecture/case-study/index.md +++ b/src/content/app-architecture/case-study/index.md @@ -82,48 +82,46 @@ Data layer objects (repositories and services) aren't tied to a single feature, while UI layer objects (views and view models) are. The following is how the code is organized within the Compass application. -```plaintext -lib -├─┬─ ui -│ ├─┬─ core -│ │ ├─┬─ ui -│ │ │ └─── -│ │ └─── themes -│ └─┬─ -│ ├─┬─ view_model -│ │ └─── .dart -│ └─┬─ widgets -│ ├── _screen.dart -│ └── -├─┬─ domain -│ └─┬─ models -│ └─── .dart -├─┬─ data -│ ├─┬─ repositories -│ │ └─── .dart -│ ├─┬─ services -│ │ └─── .dart -│ └─┬─ model -│ └─── .dart -├─── config -├─── utils -├─── routing -├─── main_staging.dart -├─── main_development.dart -└─── main.dart - -// The test folder contains unit and widget tests -test -├─── data -├─── domain -├─── ui -└─── utils - -// The testing folder contains mocks other classes need to execute tests -testing -├─── fakes -└─── models -``` + + +- lib/ + - ui/ + - core/ + - ui/ + - + - themes/ + - / + - view_model/ + - .dart + - widgets/ + - _screen.dart + - + - domain/ + - models/ + - .dart + - data/ + - repositories/ + - .dart + - services/ + - .dart + - model/ + - .dart + - config/ + - utils/ + - routing/ + - main_staging.dart + - main_development.dart + - main.dart +- test/ // The test folder contains unit and widget tests + - data/ + - domain/ + - ui/ + - utils/ +- testing/ // The testing folder contains mocks other classes need to execute tests + - fakes/ + - models/ + + Most of the application code lives in the `data`, `domain`, and `ui` folders. diff --git a/src/content/get-started/flutter-for/react-native-devs.md b/src/content/get-started/flutter-for/react-native-devs.md index a353a502172..d84f8344a81 100644 --- a/src/content/get-started/flutter-for/react-native-devs.md +++ b/src/content/get-started/flutter-for/react-native-devs.md @@ -633,24 +633,19 @@ When you create a new Flutter project, it builds the following directory structure. You can customize it later, but this is where you start. -```plaintext -┬ -└ project_name - ┬ - ├ android - Contains Android-specific files. - ├ build - Stores iOS and Android build files. - ├ ios - Contains iOS-specific files. - ├ lib - Contains externally accessible Dart source files. - ┬ - └ src - Contains additional source files. - └ main.dart - The Flutter entry point and the start of a new app. - This is generated automatically when you create a Flutter - project. - It's where you start writing your Dart code. - ├ test - Contains automated test files. - └ pubspec.yaml - Contains the metadata for the Flutter app. - This is equivalent to the package.json file in React Native. -``` + + +- / + - android/ // Contains Android-specific files. + - build/ // Stores iOS and Android build files. + - ios/ // Contains iOS-specific files. + - lib/ // Contains externally accessible Dart source files. + - src/ // Contains additional source files. + - main.dart // The Flutter entry point and the start of a new app. This is generated automatically when you create a Flutter project. It's where you start writing your Dart code. + - test/ // Contains automated test files. + - pubspec.yaml // Contains the metadata for the Flutter app. This is equivalent to the package.json file in React Native. + + ### Where do I put my resources and assets and how do I use them? From 33a23d5923fa8e9bd30f3b7c47362547d1fe588c Mon Sep 17 00:00:00 2001 From: Kilian Schulte Date: Wed, 5 Nov 2025 11:06:27 +0100 Subject: [PATCH 2/4] update jaspr_content version --- site/pubspec.yaml | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/site/pubspec.yaml b/site/pubspec.yaml index 231f3b64067..94743cb11a8 100644 --- a/site/pubspec.yaml +++ b/site/pubspec.yaml @@ -13,7 +13,7 @@ dependencies: html: ^0.15.6 http: ^1.5.0 jaspr: ^0.21.6 - jaspr_content: ^0.4.2 + jaspr_content: ^0.4.3 # Used as our template engine. liquify: ^1.3.1 markdown: ^7.3.0 @@ -37,12 +37,5 @@ dev_dependencies: sass: ^1.93.2 sass_builder: ^2.4.0 -dependency_overrides: - jaspr_content: - git: - url: https://github.com/schultek/jaspr - path: packages/jaspr_content - ref: feat/file-tree - jaspr: mode: static From 7e15aa855018e0ae866fc5f193f854940213321d Mon Sep 17 00:00:00 2001 From: Kilian Schulte Date: Wed, 5 Nov 2025 11:12:49 +0100 Subject: [PATCH 3/4] apply review --- site/lib/_sass/components/_code.scss | 2 +- .../add-to-app/ios-project/embed-framework-directory-tree.md | 4 ++-- src/content/app-architecture/case-study/index.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/site/lib/_sass/components/_code.scss b/site/lib/_sass/components/_code.scss index e66748563ad..165892a59d0 100644 --- a/site/lib/_sass/components/_code.scss +++ b/site/lib/_sass/components/_code.scss @@ -275,4 +275,4 @@ iframe[src^="https://dartpad"] { user-select: unset; } } -} \ No newline at end of file +} diff --git a/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md b/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md index 7a62eb54c0e..652d8feca1f 100644 --- a/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md +++ b/src/_includes/docs/add-to-app/ios-project/embed-framework-directory-tree.md @@ -16,8 +16,8 @@ The resulting project structure should resemble this directory tree. - Debug/ - Flutter.xcframework - App.xcframework - - FlutterPluginRegistrant.xcframework (only if you have plugins with iOS platform code) - - example_plugin.xcframework (each plugin is a separate framework) + - FlutterPluginRegistrant.xcframework (If you have plugins with iOS-platform code) + - example_plugin.xcframework (One framework file for each plugin) - Profile/ - Flutter.xcframework - App.xcframework diff --git a/src/content/app-architecture/case-study/index.md b/src/content/app-architecture/case-study/index.md index 8c974aaca3b..730ed0b86b9 100644 --- a/src/content/app-architecture/case-study/index.md +++ b/src/content/app-architecture/case-study/index.md @@ -112,12 +112,12 @@ The following is how the code is organized within the Compass application. - main_staging.dart - main_development.dart - main.dart -- test/ // The test folder contains unit and widget tests +- test/ // Contains unit and widget tests. - data/ - domain/ - ui/ - utils/ -- testing/ // The testing folder contains mocks other classes need to execute tests +- testing/ // Contains mocks that other classes need to execute tests. - fakes/ - models/ From 8e33d8d503dd4777054e5590473ff063b74bc405 Mon Sep 17 00:00:00 2001 From: Kilian Schulte Date: Mon, 10 Nov 2025 09:37:48 +0100 Subject: [PATCH 4/4] fix style hash --- site/lib/src/layouts/dash_layout.dart | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/site/lib/src/layouts/dash_layout.dart b/site/lib/src/layouts/dash_layout.dart index 2a5c322d8db..82b4d991cae 100644 --- a/site/lib/src/layouts/dash_layout.dart +++ b/site/lib/src/layouts/dash_layout.dart @@ -2,8 +2,6 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -import 'dart:convert' show htmlEscape; - import 'package:jaspr/jaspr.dart'; import 'package:jaspr_content/jaspr_content.dart'; @@ -102,9 +100,7 @@ abstract class FlutterDocsLayout extends PageLayoutBase { ), link( rel: 'stylesheet', - href: - '/assets/css/main.css?' - 'hash=${htmlEscape.convert(generatedStylesHash)}', + href: '/assets/css/main.css?hash=$generatedStylesHash', ), if (pageData['js'] case final List jsList)