Add support for setting the heading level for web semantics (#97894) #125771

victorgalo · 2023-04-30T13:59:23Z

This change adds a new property in Semantics widget that would take an integer corresponding to the heading levels defined by the ARIA heading role. This is necessary in order to get proper accessibility and usability in a website for users who rely on screen readers and other assistive technologies.

Issue fixed by this PR:
fixes #97894

Engine part:
flutter/engine#41435

Pre-launch Checklist

I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
I read the [Tree Hygiene] wiki page, which explains my responsibilities.
I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
I signed the [CLA].
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is [test-exempt].
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on [Discord].

…97894)

victorgalo · 2023-04-30T18:46:04Z

The build is failing because the engine part must be approved. I need to integrate both changes together (framework and engine part) for integration tests to pass. Please, someone can tell me how I should deal with this?.

Maybe @yjbanov can shed some light?

Thank you!

chunhtai

we should also have logic to automatically apply these when people using builtin text style in theme

chunhtai · 2023-05-16T22:19:39Z

packages/flutter/lib/src/semantics/semantics.dart


+  /// The hierarchy level of the widget as a header.
+  ///
+  /// This should only be set when [SemanticsFlag.isHeader] is set.


is this true? the isHeader may be closer to banner in aria.

Yes, a widget with isHeader attribute gets a "role=heading" aria attribute, not a "banner" role. For that reason I consider this change is needed, a "heading" role needs an "aria-level". Webs without this do not pass accessibility static analysis checks and we really need this for a specific project.

isHeader attribute gets a "role=heading

is this already the case in web? I remember when I last revisited this, only the Appbar has the isHeader = true. and Appbar is closer to banner in html https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role

The heading, ie h1, h2, h3 seams to be a different thing in html

cc @yjbanov

This doesn't seem to be answered yet

Hi @chunhtai, sorry for replying so late. Yes, I don't know what's the purpose of having that parameter enabled for the AppBar, but I can confirm applying the "header" attribute has the effect I mention, I tested it many times, also you can see evidence in this code (part of the engine)

Yes, I think flutter web's usage of role=heading is incorrect. It was my mistake, as I was misunderstood what isHeader meant. "banner" seems closer to what it means in Flutter.

If that's the case and we change isHeader to "banner", there won't be a way to add headings and levels in flutter web. Having a heading structure is an important feature in order to have decent web accessibility. Should we have another attribute for this?

isHeader is named after the similar widget in mobile platforms.

https://developer.apple.com/documentation/uikit/uiaccessibilitytraitheader?language=objc

Android called it heading

https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo#isHeading()

It seems to me the mobile header or heading is the equivalent banner in web.

Should we have another attribute for this?

Isn't the heading level enough for this? we need to make sure we document that the heading level has nothing to do with the isHeader property.

This seems not addressed yet?

This seems not addressed yet?

Sorry, not yet, but I will address it. If I understood correctly the idea is to separate both attributes, changing "heading" property to be used to establish a "banner" role in web, and dedicate the headingLevel attribute to add the element as a header role with its corresponding level.

chunhtai · 2023-05-16T22:21:32Z

packages/flutter/lib/src/semantics/semantics.dart

    _setFlag(SemanticsFlag.isHeader, value);
  }

+  /// Indicates the owning [RenderObject]'s hierarchy level.


This doc is a bit confusing. what is a hierarchy level?

Can you add more detail to this?

Sure, I tried to add more details. Please let me know if still should add more information. Thank you.

chunhtai · 2023-05-16T22:23:57Z

packages/flutter/lib/src/semantics/semantics.dart

  int? _currentValueLength;

-  bool _canPerformAction(SemanticsAction action) => _actions.containsKey(action);
+  /// The level of the widget (when it's defined as a header) within


First paragraph should be a brief sentence also this can use more explanation. can this parameter make sense out side of dom or markdown? If not, we should add document in terminologies in dom or markdown

Sure, I tried to add more specific explanation here, please let me know if I should add/change something else. Thank you!

chunhtai · 2023-05-16T22:24:07Z

packages/flutter/lib/src/semantics/semantics.dart

  /// [Directionality] or an explicit [textDirection] should be provided.
  final String? tooltip;

+  /// The level of the widget (when it's defined as a header) within


Also changed this, hope it's better now. Thank you.

victorgalo · 2023-05-21T21:23:01Z

we should also have logic to automatically apply these when people using builtin text style in theme

Sorry @chunhtai, I didn't get this. You mean the heading level should automatically be applied with a default value?

chunhtai · 2023-06-05T22:07:12Z

we should also have logic to automatically apply these when people using builtin text style in theme

Sorry @chunhtai, I didn't get this. You mean the heading level should automatically be applied with a default value?

The Text theme has h1~h6 style (which was replace by displayLarge, displayMedium.. etc). I was wondering where we may have a way to auto apply the semantics headinglevel if these style are in use. One idea would be make TextStyle carry heading level

chunhtai

Hi @victorgalo , are you still planning on coming back to this pr?

chunhtai · 2023-06-16T19:21:56Z

packages/flutter/lib/src/semantics/semantics.dart


+  /// The hierarchy level of the widget as a header.
+  ///
+  /// This should only be set when [SemanticsFlag.isHeader] is set.


This doesn't seem to be answered yet

chunhtai · 2023-06-16T19:22:55Z

we should also have logic to automatically apply these when people using builtin text style in theme

Sorry @chunhtai, I didn't get this. You mean the heading level should automatically be applied with a default value?

The Text theme has h1~h6 style (which was replace by displayLarge, displayMedium.. etc). I was wondering where we may have a way to auto apply the semantics headinglevel if these style are in use. One idea would be make TextStyle carry heading level

This can be a separate pr though

victorgalo · 2023-06-22T15:17:50Z

Hi @victorgalo , are you still planning on coming back to this pr?

Hi @chunhtai. Yes, sorry for taking so long to reply. I would really appreciate my changes to be included.

victorgalo · 2023-06-22T15:19:57Z

we should also have logic to automatically apply these when people using builtin text style in theme

Sorry @chunhtai, I didn't get this. You mean the heading level should automatically be applied with a default value?

The Text theme has h1~h6 style (which was replace by displayLarge, displayMedium.. etc). I was wondering where we may have a way to auto apply the semantics headinglevel if these style are in use. One idea would be make TextStyle carry heading level

Oh I understand, sounds like a nice idea, but not sure how to handle that, because as you said, the h1-h6 were replaced and I don't see any way to relate the levels. Maybe it made more sense when those theme styles existed. If you are ok, we can deal with that in another PR.

chunhtai · 2023-07-21T17:43:37Z

Hi @victorgalo are you still planning on working on this pr? The discussion seems to not be resolved yet #125771 (comment)

victorgalo · 2023-08-08T09:02:33Z

Hi @victorgalo are you still planning on working on this pr? The discussion seems to not be resolved yet #125771 (comment)

Yes I will, sorry for the delay.

flutter-dashboard · 2023-08-28T09:03:46Z

This pull request executed golden file tests, but it has not been updated in a while (20+ days). Test results from Gold expire after as many days, so this pull request will need to be updated with a fresh commit in order to get results from Gold.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

# Conflicts: # packages/flutter/test/semantics/semantics_update_test.dart

auto-submit · 2024-06-06T18:26:22Z

auto label is removed for flutter/flutter/125771, due to This PR has not met approval requirements for merging. The PR author is not a member of flutter-hackers and needs 1 more review(s) in order to merge this PR.

Merge guidelines: A PR needs at least one approved review if the author is already part of flutter-hackers or two member reviews if the author is not a flutter-hacker before re-applying the autosubmit label. Reviewers: If you left a comment approving, please use the "approve" review action instead.

justinmc

LGTM 👍

…#97894) (flutter/flutter#125771)

Manual roll Flutter from 4608a89 to fc19ecf (38 revisions) Manual roll requested by [email protected] flutter/flutter@4608a89...fc19ecf 2024-06-07 [email protected] Fix `SegmentedButton` clipping when drawing segments (flutter/flutter#149739) 2024-06-07 [email protected] Shift consistently passing tests on mokey to prod (flutter/flutter#149902) 2024-06-07 [email protected] Prepare images for tests individually to enable clean up of cache. (flutter/flutter#149693) 2024-06-07 [email protected] Roll Packages from 586faa6 to 8a2c4e4 (8 revisions) (flutter/flutter#149900) 2024-06-07 [email protected] Roll Flutter Engine from 98e9393bf2e9 to 1cdbebee1901 (4 revisions) (flutter/flutter#149899) 2024-06-07 [email protected] Roll Flutter Engine from 087feab9922b to 98e9393bf2e9 (1 revision) (flutter/flutter#149875) 2024-06-07 [email protected] Refactor `widget_inspector_test.dart` (flutter/flutter#149850) 2024-06-07 [email protected] Add test for dropdown_menu.1.dart (flutter/flutter#149547) 2024-06-07 [email protected] Add test for standard_fab_location.0.dart (flutter/flutter#149225) 2024-06-07 [email protected] [native_assets] Fix framework name deduplication (flutter/flutter#149761) 2024-06-07 [email protected] Roll Flutter Engine from 47b15dfba1da to 087feab9922b (1 revision) (flutter/flutter#149871) 2024-06-07 [email protected] Roll Flutter Engine from 5d5e0ee9102c to 47b15dfba1da (2 revisions) (flutter/flutter#149870) 2024-06-07 [email protected] Roll Flutter Engine from fea8e51b0280 to 5d5e0ee9102c (2 revisions) (flutter/flutter#149867) 2024-06-07 [email protected] Roll Flutter Engine from 5a0a49939c64 to fea8e51b0280 (2 revisions) (flutter/flutter#149865) 2024-06-07 [email protected] Roll pub packages (flutter/flutter#149864) 2024-06-06 [email protected] Roll Flutter Engine from bf1a4877da0b to 5a0a49939c64 (1 revision) (flutter/flutter#149861) 2024-06-06 [email protected] Remove some vestigial /*!*/ comments (flutter/flutter#149361) 2024-06-06 [email protected] Attempt to fix some web test flakiness. (flutter/flutter#149828) 2024-06-06 [email protected] Remove abi key permanently from golden file testing (flutter/flutter#149858) 2024-06-06 [email protected] [CupertinoActionSheet] Add sliding tap gesture (flutter/flutter#149471) 2024-06-06 [email protected] Roll pub packages (flutter/flutter#149852) 2024-06-06 [email protected] SliverResizingHeader (flutter/flutter#143325) 2024-06-06 [email protected] Run tests on macOS 13 or 14 (flutter/flutter#149827) 2024-06-06 [email protected] Fix leaky test. (flutter/flutter#149823) 2024-06-06 [email protected] Roll Flutter Engine from 31804a222f97 to bf1a4877da0b (3 revisions) (flutter/flutter#149848) 2024-06-06 [email protected] Add support for setting the heading level for web semantics (#97894) (flutter/flutter#125771) 2024-06-06 98614782+auto-submit[bot]@users.noreply.github.com Reverts "Introduce `ChipAnimationStyle` to override default chips animations durations (#149245)" (flutter/flutter#149847) 2024-06-06 [email protected] 3.22.2 release notes (flutter/flutter#149818) 2024-06-06 [email protected] Roll Flutter Engine from 25bcbb888939 to 31804a222f97 (3 revisions) (flutter/flutter#149837) 2024-06-06 [email protected] Introduce `ChipAnimationStyle` to override default chips animations durations (flutter/flutter#149245) 2024-06-06 [email protected] Roll Flutter Engine from f5a9690c6061 to 25bcbb888939 (1 revision) (flutter/flutter#149835) 2024-06-06 [email protected] Fix leaky test. (flutter/flutter#149822) 2024-06-06 [email protected] Unpin archive package from tool, update to version without security advisories (flutter/flutter#149430) 2024-06-06 [email protected] Roll pub packages (flutter/flutter#149630) 2024-06-06 [email protected] Roll Flutter Engine from d9684a37af06 to f5a9690c6061 (7 revisions) (flutter/flutter#149832) 2024-06-06 [email protected] Roll Packages from 11e192a to 586faa6 (13 revisions) (flutter/flutter#149820) 2024-06-06 [email protected] Fix some links in the "Handling breaking change" section (flutter/flutter#149821) 2024-06-06 [email protected] Roll Flutter Engine from 92d0cd9370f7 to d9684a37af06 (1 revision) (flutter/flutter#149793) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected],[email protected] on the revert to ensure that a human is aware of the problem. ...

…#97894) (flutter/flutter#125771)

k0psutin · 2024-10-03T06:10:43Z

I don't think the headingLevel is working?

Try this with MacOS Voice Over:

https://dartpad.dev/?id=a8e32aa25ea01fe79a590b4a9138687e

Try to select heading with voice over, it says that the Flutter Demo Home Page is the last heading. You can't navigate to the second heading with keyboard arrows either.

chunhtai · 2024-10-03T16:15:13Z

Hi @k0psutin it hasn't hook up to desktop embedding i believe. can you open a new issue for this?

k0psutin · 2024-10-04T08:57:56Z

Hi @chunhtai I made a new issue #156203

Add support for setting the heading level for web semantics (flutter#…

e06d47e

…97894)

flutter-dashboard bot added a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) framework flutter/packages/flutter repository. See also f: labels. labels Apr 30, 2023

victorgalo mentioned this pull request Apr 30, 2023

Add support for setting the heading level for web semantics (#97894) flutter/engine#41435

Merged

8 tasks

Add support for setting the heading level for web semantics (flutter#…

a03e771

…97894)

victorgalo marked this pull request as ready for review April 30, 2023 18:46

goderbauer requested a review from chunhtai May 2, 2023 10:10

chunhtai reviewed May 16, 2023

View reviewed changes

victorgalo added 2 commits May 21, 2023 20:14

Merge branch 'master' into add-semantics-heading-level

04fae16

Improve documentation comments for headingLevel semantics property

f6c15f0

goderbauer requested a review from chunhtai May 30, 2023 22:09

chunhtai reviewed Jun 16, 2023

View reviewed changes

chunhtai requested review from chunhtai and yjbanov June 22, 2023 15:56

victorgalo added 2 commits September 10, 2023 14:53

Merge branch 'master' into add-semantics-heading-level

94bdf73

# Conflicts: # packages/flutter/test/semantics/semantics_update_test.dart

Change documentation adapted to new behaviour for headingLevel

fcbbc3a

victorgalo requested a review from christopherfujino as a code owner September 11, 2023 20:12

github-actions bot added a: tests "flutter test", flutter_test, or one of our tests a: text input Entering text in a text field or keyboard related problems platform-ios iOS applications specifically tool Affects the "flutter" command-line tool. See also t: labels. labels Sep 11, 2023

github-actions bot added the a: tests "flutter test", flutter_test, or one of our tests label Jun 5, 2024

Merge branch 'master' into add-semantics-heading-level

bf68295

chunhtai added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 6, 2024

auto-submit bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 6, 2024

justinmc approved these changes Jun 6, 2024

View reviewed changes

chunhtai added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 6, 2024

auto-submit bot merged commit 7d525ea into flutter:master Jun 6, 2024

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Roll Flutter from 4608a8913767 to d849b91ffc07 (33 revisions) flutter/packages#6884

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

fb7c08f

…#97894) (flutter/flutter#125771)

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Roll Flutter from 4608a8913767 to 538183963a7f (34 revisions) flutter/packages#6885

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

8c88b38

…#97894) (flutter/flutter#125771)

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Roll Flutter from 4608a8913767 to 1fdb40ea9588 (35 revisions) flutter/packages#6886

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

23300b0

…#97894) (flutter/flutter#125771)

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Roll Flutter from 4608a8913767 to 35a4933ba885 (36 revisions) flutter/packages#6887

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

f53aa54

…#97894) (flutter/flutter#125771)

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Roll Flutter from 4608a8913767 to bb831b7a6420 (37 revisions) flutter/packages#6888

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

934e887

…#97894) (flutter/flutter#125771)

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Roll Flutter from 4608a8913767 to fc19ecfc585a (38 revisions) flutter/packages#6889

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

c110f91

…#97894) (flutter/flutter#125771)

engine-flutter-autoroll mentioned this pull request Jun 7, 2024

Manual roll Flutter from 4608a8913767 to fc19ecfc585a (38 revisions) flutter/packages#6890

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Jun 7, 2024

7d525ea Add support for setting the heading level for web semantics (…

fcb3336

…#97894) (flutter/flutter#125771)

Piinks mentioned this pull request Jun 7, 2024

Flutter Framework Team: Notable Commits #121415

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Aug 6, 2024

7d525ea Add support for setting the heading level for web semantics (…

512bc2a

…#97894) (flutter/flutter#125771)

k0psutin mentioned this pull request Oct 4, 2024

[a11y][web]: Semantics headingLevel is not working #156203

Closed

Add support for setting the heading level for web semantics (#97894) #125771

Add support for setting the heading level for web semantics (#97894) #125771

Uh oh!

Conversation

victorgalo commented Apr 30, 2023 • edited by chunhtai Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

victorgalo commented Apr 30, 2023

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

victorgalo commented May 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chunhtai commented Jun 5, 2023

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chunhtai commented Jun 16, 2023

Uh oh!

victorgalo commented Jun 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

victorgalo commented Jun 22, 2023

Uh oh!

chunhtai commented Jul 21, 2023

Uh oh!

victorgalo commented Aug 8, 2023

Uh oh!

flutter-dashboard bot commented Aug 28, 2023

Uh oh!

auto-submit bot commented Jun 6, 2024

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

k0psutin commented Oct 3, 2024

Uh oh!

chunhtai commented Oct 3, 2024

Uh oh!

k0psutin commented Oct 4, 2024

victorgalo commented Apr 30, 2023 •

edited by chunhtai

Loading

victorgalo commented May 21, 2023 •

edited

Loading

victorgalo commented Jun 22, 2023 •

edited

Loading