Skip to content

Commit 6abd4c7

Browse files
committed
Merge branch 'main' into web-350-docs
Keep all six Flutter 3.50 breaking-change index entries in alphabetical order.
2 parents af67472 + fbe2b9d commit 6abd4c7

37 files changed

Lines changed: 1222 additions & 144 deletions

File tree

‎.agents/skills/contribute-blog/references/post-format.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,13 @@ layout: blog
7979
: Static image override (WebP or PNG under 5 MB) for social sharing metadata
8080
when `coverImage` is animated or exceeds 5 MB.
8181

82+
`showToc` (optional)
83+
: Whether to show the "In this article" table of contents
84+
generated from the post's `##` and `###` headings.
85+
Defaults to `true`, though the TOC only appears
86+
when the post has at least two `##` headings.
87+
To explicitly hide the TOC, set `showToc: false`.
88+
8289
## Card and social images
8390

8491
`coverImage` is optional but recommended when suitable artwork exists.

‎.github/workflows/codeql-analysis.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jobs:
3636

3737
# Initializes the CodeQL tools for scanning.
3838
- name: Initialize CodeQL
39-
uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d
39+
uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee
4040
with:
4141
languages: ${{ matrix.language }}
4242
# If you wish to specify custom queries, you can do so here or in a config file.
@@ -47,7 +47,7 @@ jobs:
4747
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
4848
# If this step fails, then you should remove it and run the build manually (see below)
4949
- name: Autobuild
50-
uses: github/codeql-action/autobuild@24c54180a607b1449ed407dd24f251e4e9147c8d
50+
uses: github/codeql-action/autobuild@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee
5151

5252
# ℹ️ Command-line programs to run using the OS shell.
5353
# 📚 https://git.io/JvXDl
@@ -61,4 +61,4 @@ jobs:
6161
# make release
6262

6363
- name: Perform CodeQL Analysis
64-
uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d
64+
uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee

‎packages/site_shared/lib/_sass/components/_blog.scss‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -537,6 +537,67 @@
537537
}
538538
}
539539

540+
.blog-toc {
541+
--toc-icon-size: 24px;
542+
543+
margin: 1.5rem 0;
544+
padding: 1rem;
545+
background: var(--site-inset-bgColor);
546+
border: 1px solid var(--site-inset-borderColor);
547+
border-radius: var(--ui-border-radius-sm);
548+
549+
summary {
550+
display: flex;
551+
align-items: center;
552+
gap: 0.25rem;
553+
font-family: var(--site-ui-fontFamily);
554+
font-weight: var(--site-fontWeight-bold);
555+
cursor: pointer;
556+
list-style: none;
557+
user-select: none;
558+
559+
&::-webkit-details-marker {
560+
display: none;
561+
}
562+
563+
.material-symbols {
564+
font-size: var(--toc-icon-size);
565+
transition: transform 0.15s var(--ui-anim-func);
566+
567+
@media (prefers-reduced-motion: reduce) {
568+
transition: none;
569+
}
570+
}
571+
}
572+
573+
details[open] summary .material-symbols {
574+
transform: rotate(90deg);
575+
}
576+
577+
ul {
578+
margin: 0;
579+
padding-left: 0.75em;
580+
list-style: none;
581+
}
582+
583+
details > ul {
584+
margin-top: 0.75rem;
585+
// Center the 1px border under the chevron and
586+
// align the entries with the summary text.
587+
margin-left: calc(var(--toc-icon-size) / 2 - 0.5px);
588+
padding-left: calc(var(--toc-icon-size) / 2 + 0.25rem - 0.5px);
589+
border-left: 1px solid var(--site-outline-variant);
590+
}
591+
592+
li {
593+
margin: 0.5rem 0;
594+
}
595+
596+
a {
597+
overflow-wrap: anywhere;
598+
}
599+
}
600+
540601
.blog-next-posts {
541602
margin: 4rem 0;
542603
padding-top: 4rem;
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Copyright 2026, the Flutter authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that
3+
// can be found in the LICENSE file.
4+
5+
import 'package:jaspr/dom.dart';
6+
import 'package:jaspr/jaspr.dart';
7+
import 'package:jaspr_content/jaspr_content.dart';
8+
9+
import '../common/material_icon.dart';
10+
11+
/// The minimum number of top-level entries an article needs to have
12+
/// before a table of contents is worth showing.
13+
const int _minEntriesForToc = 2;
14+
15+
/// A collapsible table of contents for a blog post,
16+
/// listing the post's `h2` and `h3` headings.
17+
///
18+
/// Requires [TableOfContentsExtension] to be registered,
19+
/// which stores the headings in the page's `toc` data.
20+
/// Renders nothing if the post sets `showToc: false` in its front matter or
21+
/// has fewer than two `h2` headings.
22+
final class BlogTableOfContents extends StatelessComponent {
23+
const BlogTableOfContents({super.key});
24+
25+
@override
26+
Component build(BuildContext context) {
27+
final page = context.page;
28+
final pageData = page.data;
29+
final toc = pageData['toc'];
30+
if (pageData.page['showToc'] == false ||
31+
toc is! TableOfContents ||
32+
toc.entries.length < _minEntriesForToc) {
33+
return const .empty();
34+
}
35+
36+
return nav(
37+
classes: 'blog-toc',
38+
attributes: {'aria-label': 'In this article'},
39+
[
40+
details(
41+
[
42+
const summary(
43+
[
44+
MaterialIcon('chevron_right'),
45+
.text('In this article'),
46+
],
47+
),
48+
_buildList(toc.entries, page.url),
49+
],
50+
),
51+
],
52+
);
53+
}
54+
55+
static Component _buildList(List<TocEntry> entries, String pageUrl) => ul([
56+
for (final entry in entries)
57+
li([
58+
a(href: '$pageUrl#${entry.id}', [.text(entry.text)]),
59+
if (entry.children.isNotEmpty) _buildList(entry.children, pageUrl),
60+
]),
61+
]);
62+
}

‎packages/site_shared/lib/page_extensions.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ library;
88
export 'src/extensions/attribute_processor.dart';
99
export 'src/extensions/code_block_processor.dart';
1010
export 'src/extensions/header_extractor.dart';
11+
export 'src/extensions/header_id_deduplication.dart';
1112
export 'src/extensions/header_processor.dart';
1213
export 'src/extensions/mermaid_processor.dart';
1314
export 'src/extensions/table_processor.dart';
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Copyright 2026 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:jaspr_content/jaspr_content.dart';
6+
7+
/// An extension that makes existing IDs unique among
8+
/// `h1` through `h6` headings.
9+
///
10+
/// Appends numeric suffixes to repeated IDs,
11+
/// leaving headings without IDs alone.
12+
/// A suffixed ID never takes the original ID of another heading,
13+
/// so a later "Step 1" heading keeps `step-1` even if
14+
/// two earlier "Step" headings share `step`.
15+
///
16+
/// Apply this after heading attributes are resolved and
17+
/// before extensions that extract heading IDs or generate heading links.
18+
final class HeaderIdDeduplicationExtension implements PageExtension {
19+
const HeaderIdDeduplicationExtension();
20+
21+
@override
22+
Future<List<Node>> apply(Page page, List<Node> nodes) async {
23+
final headings = [
24+
for (final heading in _findHeadings(nodes))
25+
if (heading.attributes['id'] case final id?) (heading, id),
26+
];
27+
28+
// Start with every original ID taken so a suffixed ID never reuses one.
29+
final takenIds = {for (final (_, id) in headings) id};
30+
final seenIds = <String>{};
31+
32+
for (final (heading, id) in headings) {
33+
// The first heading with each ID keeps it.
34+
if (seenIds.add(id)) continue;
35+
36+
var suffix = 1;
37+
while (takenIds.contains('$id-$suffix')) {
38+
suffix += 1;
39+
}
40+
41+
final uniqueId = '$id-$suffix';
42+
takenIds.add(uniqueId);
43+
heading.attributes['id'] = uniqueId;
44+
}
45+
46+
return nodes;
47+
}
48+
49+
/// Finds all `h1` through `h6` elements in [nodes], in document order.
50+
static List<ElementNode> _findHeadings(List<Node> nodes) {
51+
const headingTags = {'h1', 'h2', 'h3', 'h4', 'h5', 'h6'};
52+
53+
return [
54+
for (final node in nodes)
55+
if (node is ElementNode)
56+
if (headingTags.contains(node.tag.toLowerCase()))
57+
node
58+
else if (node.children case final children?)
59+
..._findHeadings(children),
60+
];
61+
}
62+
}

‎packages/site_shared/lib/src/extensions/header_processor.dart‎

Lines changed: 13 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,22 @@
44

55
import 'package:jaspr_content/jaspr_content.dart';
66

7-
/// A node-processing, page extension for Jaspr Content that
8-
/// wraps each `h1` -> `h5` element in a div with the `header-wrapper` class
9-
/// and adds an anchor that can clicked and linked to.
7+
/// An extension that wraps `h2` through `h5` headings and
8+
/// adds permalink anchors.
9+
///
10+
/// Heading IDs must already be unique.
1011
final class HeaderWrapperExtension implements PageExtension {
1112
const HeaderWrapperExtension();
1213

1314
@override
14-
Future<List<Node>> apply(Page page, List<Node> nodes) async {
15-
final usedIds = <String>{};
16-
return _processNodes(nodes, usedIds);
17-
}
15+
Future<List<Node>> apply(Page page, List<Node> nodes) async =>
16+
_processNodes(nodes);
1817

19-
List<Node> _processNodes(List<Node> nodes, Set<String> usedIds) {
20-
return [for (final node in nodes) _processNode(node, usedIds)];
21-
}
18+
List<Node> _processNodes(List<Node> nodes) => [
19+
for (final node in nodes) _processNode(node),
20+
];
2221

23-
Node _processNode(Node node, Set<String> usedIds) {
22+
Node _processNode(Node node) {
2423
if (node is! ElementNode) return node;
2524

2625
final tagName = node.tag.toLowerCase();
@@ -31,23 +30,12 @@ final class HeaderWrapperExtension implements PageExtension {
3130
return ElementNode(
3231
node.tag,
3332
node.attributes,
34-
nodeChildren != null ? _processNodes(nodeChildren, usedIds) : null,
33+
nodeChildren != null ? _processNodes(nodeChildren) : null,
3534
);
3635
}
3736

38-
final rawHeaderId = node.attributes['id'];
39-
if (rawHeaderId == null) return node;
40-
41-
// Account for headers with the same base id,
42-
// appending a dash and an integer until the header has a unique id.
43-
var headerId = rawHeaderId;
44-
for (var i = 1; usedIds.contains(headerId); i += 1) {
45-
headerId = '$rawHeaderId-$i';
46-
}
47-
usedIds.add(headerId);
48-
49-
// Update header ID to be the unique one as well.
50-
node.attributes['id'] = headerId;
37+
final headerId = node.attributes['id'];
38+
if (headerId == null) return node;
5139

5240
final headerText = node.innerText;
5341

‎sites/docs/firebase.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -499,7 +499,7 @@
499499
{ "source": "/go/flavor-specific-assets", "destination": "https://docs.google.com/document/d/1_3GwdRZ1WPBqR9koNxESfAXHqynv36__ctMqN-NRG0k/edit?usp=sharing", "type": 301 },
500500
{ "source": "/go/floating-snackbar-offset", "destination": "https://docs.google.com/document/d/1elP-y83PtvfAZHNcpHCtnOFhZO9VnnlobwfQ33QO4hg/edit", "type": 301 },
501501
{ "source": "/go/floating-widgetspans", "destination": "https://docs.google.com/document/d/1I-VqCxvszXGAas_6EE9b6ZIzyMY3HjxDxGW9_DWWd7M/edit", "type": 301 },
502-
{ "source": "/go/flutter-android-embedder-api-migration", "destination": "https://docs.google.com/document/d/1pFgFYzAKrIFEQQfSz6NbOvKXG6K3oksPQqhKSQZ7t68", "type": 301 },
502+
{ "source": "/go/flutter-android-embedder-api-migration", "destination": "https://github.com/flutter/rfc/pull/24", "type": 301 },
503503
{ "source": "/go/flutter-android-emulator-testing", "destination": "https://docs.google.com/document/d/10wYUcLcSTF4Epg2EUGoBqOkkOe4zxKHvYKjXFZAOgGs/edit?usp=sharing&resourcekey=0-pltjPvEtVezXDADMbUwFHQ", "type": 301 },
504504
{ "source": "/go/flutter-dependency-hosting", "destination": "https://docs.google.com/document/d/1EKb1VypI0ArXqwBWJKGTsiQ2WU0ruYb55JpIeKxWaDs/edit", "type": 301 },
505505
{ "source": "/go/flutter-developer-tooling-plugins", "destination": "https://docs.google.com/document/d/189A-T-pcHPuds8pOtbzLS8Wl6Hr0AIAIl0aRTPvLKec/", "type": 301 },

‎sites/docs/lib/src/extensions/registry.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import 'tutorial_structure_processor.dart';
1313
/// content loaded with Jaspr Content.
1414
const List<PageExtension> allNodeProcessingExtensions = [
1515
AttributeProcessor(),
16+
HeaderIdDeduplicationExtension(),
1617
HeaderExtractorExtension(),
1718
HeaderWrapperExtension(),
1819
TableWrapperExtension(),

0 commit comments

Comments
 (0)