@sapudex/web-components 2.56.0 → 2.58.0

package/README.md

@@ -0,0 +1,258 @@
+# Quickstart guide for UDEx Components
+
+Follow along these few steps to get you successfully using our provided web components.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Importing the component/-s you intend to use](#importing-the-component-s-you-intend-to-use)
+- [Using the component](#using-the-component)
+- [Using our custom theme](#using-our-custom-theme)
+  - [Import our asset bundle and theme css](#import-our-asset-bundle-and-theme-css)
+  - [Activate the theme](#activate-the-theme)
+- [Configuration options](#configuration-options)
+  - [Controlling default tooltips](#controlling-default-tooltips)
+  - [Language](#language)
+  - [UDEx Custom Translation](#udex-custom-translation)
+- [Using UDEx components with UI5 components](#using-ui5-components)
+  - [Scoping configuration](#scoping-configuration)
+  - [Using UI5 icons](#using-ui5-icons)
+
+## Installation
+
+To use our provided components, it's necessary to add the package to your project as a dependancy:
+
+Using npm:
+
+```bash
+npm install @sapudex/web-components
+```
+
+Or with yarn:
+
+```bash
+yarn add @sapudex/web-components
+```
+
+## Importing the component/-s you intend to use
+
+Next we're going to import and register the components we need, this should be done at the root of application(`src/main.js`, etc) to ensure the components are loaded appropriately.
+Registering the components will tell the browser what to do with them once it encounters their HTML markup tags in source.
+
+Replace `<component-name>` with the name of the desired component.
+
+```javascript
+import '@sapudex/web-components/dist/<component-name>.js';
+```
+
+For example, to use the "Button" component:
+
+```javascript
+import '@sapudex/web-components/dist/Button.js';
+```
+
+## Using the component
+
+And finally, once the component is imported, you can use it just like any other standard HTML element, typically by adding it to your rendered HTML markup.
+
+```html
+<html>
+  <body>
+    <section>
+      <udex-button>UDEx Button</udex-button>
+    </section>
+  </body>
+</html>
+```
+
+```jsx
+const renderSectionWithButton = (title = 'UDEx Button') => (
+  <section>
+    <udex-button>{title}</udex-button>
+  </section>
+);
+```
+
+## Using our custom theme
+
+While our components come out-of-the-box with default styling, it's recommended to include our theming assets as well.
+
+### Import our asset bundle and theme css
+
+Import our `Assets.js` in your root javascript - `main.js`, `index.js` or similar.
+
+```javascript
+import '@sapudex/web-components/dist/Assets.js';
+```
+
+and add the following HTML snippet to your root `.html` file - `index.html` or similar, depending on your setup.
+
+```html
+<link rel="stylesheet" type="text/css" href="path/to/@sapudex/design-tokens/dist/themes/sap_glow/css_variables.css">
+```
+
+Where you should adjust the path to the theme("css_variables.css") file provided by our `@sapudex/design-tokens` package.
+
+An alternative way for setting up the theme is to import our `css_variables.css` before the `Assets.js` in the root javascript.
+
+```javascript
+import '@sapudex/design-tokens/dist/themes/sap_glow/css_variables.css';
+import '@sapudex/web-components/dist/Assets.js';
+```
+
+Another option, if acceptable by technical requirements, you can use theme files from our CDN, e.g.:
+
+```html
+<link rel="stylesheet" type="text/css" href="https://cdn.udex.services.sap.com/dds/design-tokens/latest/themes/sap_glow/css_variables.css">
+```
+
+### Activate the theme
+
+You have several options on activating the theme but the simplest is to add a
+small HTML snippet to your root `.html` file:
+
+```html
+<script data-ui5-config type="application/json">
+  {
+    "theme": "sap_glow"
+  }
+</script>
+```
+
+Visit [SAP Web Components](https://ui5.github.io/webcomponents/docs/advanced/theming-part2/) to see other ways to activate our theme or just generally integrate with the SAP Web Components/Theme Designer theming ecosystem.
+
+## Configuration options
+
+### Controlling default tooltips
+
+Configuration options are inherited from UI5 settings. For more information, please visit [UI5 Configuration documentation](https://ui5.github.io/webcomponents/docs/advanced/configuration/).
+
+This configuration option controls whether components will display default tooltips in specific cases.
+
+Default tooltips are generally recommended to cover accessibility standards and typically you would not need to modify this setting. However, in rare cases you may want to implement custom tooltip visualization and turn off the default tooltips. To do so, set `enableDefaultTooltips` to `false`.
+
+```html
+<script data-ui5-config type="application/json">
+{
+  "enableDefaultTooltips": false
+}
+</script>
+
+```
+
+### Language
+
+Configuration options are inherited from UI5 settings. For more information, please visit [UI5 Configuration documentation](https://ui5.github.io/webcomponents/docs/advanced/configuration/).
+
+Language to be used for translatable texts. The `en` language is built in all UI5/UDEx Web Components that have translatable texts. Thus, components are always translated. Configuring another language will additionally fetch and use that language. Any language is fetched once.
+
+```html
+<script data-ui5-config type="application/json">
+{
+  "language": "zh_cn"
+}
+</script>
+
+```
+
+or
+
+```javascript
+import { setLanguage } from "@ui5/webcomponents-base/dist/config/Language.js";
+setLanguage("zh_cn");
+```
+
+### UDEx custom Translation
+
+UDEx custom translation is a feature that allows to overwrite default UI5 automatic translation of components hardcoded text.
+This setting will overwrite translated texts, regardless of configured language.
+To setup custom translations, push an object with proper `[key: string] :string` values into `window["udex-config"].translations` object, before component loads.
+
+```javascript
+window["udex-config"] = {
+  translations: {
+    MAIN_LINKS: "custom main links",
+    LOGOUT: "custom logout"
+  }
+};
+```
+
+List of all translatable keys can be found under `@sapudex/web-components/dist/generated/i18n/i18n-defaults.js`.
+
+## Using UI5 components
+
+In order to use UDEx components together with [UI5 components library](https://ui5.github.io/webcomponents/) , you need to make sure to use matching version for both libraries. UDEx components, under the hood uses following UI5 packages:
+
+- `@ui5/webcomponents`
+- `@ui5/webcomponents-base`
+- `@ui5/webcomponents-fiori`
+
+If any of this package is used at the same project scope, all of those packages version need to match with the one used internal in `@sapudex/web-components`.
+
+### Scoping configuration
+
+In case it is not possible to keep in sync ui5 and udex packages version or in case of conflicting functionalities, it is possible to keep both packages detached and use as separate libraries. When scoping is configured, components can be used under tags with custom suffix.
+
+Scoping configuration example:
+
+```javascript
+import {
+  setCustomElementsScopingSuffix,
+  setCustomElementsScopingRules,
+} from "@ui5/webcomponents-base/dist/CustomElementsScope.js";
+
+setCustomElementsScopingRules({ include: [/^udex-/, /^ui5-/], exclude: [] });
+setCustomElementsScopingSuffix("lib");
+```
+
+Usage example:
+
+```html
+<udex-checkbox-lib></udex-checkbox-lib>
+<ui5-checkbox-lib></ui5-checkbox-lib>
+```
+
+Please read more detailed information about the scoping on [UI5 documentation page](https://ui5.github.io/webcomponents/docs/advanced/scoping/).
+
+### Using UI5 icons
+
+UDEx components do not include icons, please use UI5 provided [icon library](https://ui5.github.io/webcomponents/icons/) available with following packages:
+
+- `@ui5/webcomponents-icons`
+- `@ui5/webcomponents-icons-tnt`
+- `@ui5/webcomponents-icons-business-suite`
+
+Those libraries contains only set of icons, without UI5 components or utility functions. It is not required to import `@ui5/webcomponents` package (or other components packages) in order to use icons with UDEx components.
+
+Single icon should be imported to be used by its name in UDEx components, e.g.:
+
+```javascript
+import "@ui5/webcomponents-icons/dist/action";
+```
+
+```html
+<udex-button icon="action">Button Text</udex-button>
+```
+
+In cases where UDEx do not provide option for component icon or there is special need to icon styling, custom UI5 [Icon](https://ui5.github.io/webcomponents/components/Icon/) component can be use as a slot, e.g.:
+
+```javascript
+import Icon from "@ui5/webcomponents/dist/Icon.js";
+import "@ui5/webcomponents-icons/dist/action";
+```
+
+```html
+<udex-tile>
+  <ui5-icon name="action"></ui5-icon>
+  <h3>Title</h3>
+  ...
+</udex-tile>
+```
+
+## Additional resources
+
+- [UI5: Importing components](https://ui5.github.io/webcomponents/docs/getting-started/components-packages/#usage)
+- [UI5: Understanding Web Component APIs](https://ui5.github.io/webcomponents/docs/getting-started/components-APIs/)
+- [UI5: Theming configuration](https://ui5.github.io/webcomponents/docs/advanced/configuration/#theme)
+- [UI5: i18n for Apps](https://ui5.github.io/webcomponents/docs/advanced/using-i18n-for-apps/)
+- [UI5: Using Icons](https://ui5.github.io/webcomponents/docs/advanced/using-icons/)

package/cypress/specs/FilterMenu.cy.tsx

@@ -104,6 +104,23 @@ filter-name="Filter Name">
 </UDExFilterMenuGroupHeader>
 </UDExFilterMenu>
 
+const filterMenuTwoGroups = <UDExFilterMenu
+  id="filter-menu-two-groups"
+  mode={UDExListMode.MultiSelect}
+  filter-name="Filter Name">
+  <UDExFilterMenuGroupHeader collapsible label="Backend Languages">
+    <UDExFilterMenuItem label="Python"></UDExFilterMenuItem>
+    <UDExFilterMenuItem label="Ruby"></UDExFilterMenuItem>
+    <UDExFilterMenuItem label="Node.js"></UDExFilterMenuItem>
+  </UDExFilterMenuGroupHeader>
+  <UDExFilterMenuGroupHeader collapsible label="Frontend Languages">
+    <UDExFilterMenuItem label="JavaScript"></UDExFilterMenuItem>
+    <UDExFilterMenuItem label="Swift"></UDExFilterMenuItem>
+    <UDExFilterMenuItem label="HTML"></UDExFilterMenuItem>
+    <UDExFilterMenuItem label="CSS"></UDExFilterMenuItem>
+  </UDExFilterMenuGroupHeader>
+</UDExFilterMenu>
+
 const filterMenuRadioGroup = <UDExFilterMenu
   id="filter-menu-radio-group"
   disable-target-overlap="true"
@@ -576,6 +593,51 @@ describe("Filter Menu component", () => {
     });
   });
 
+  describe("Filter Menu grouped tree — per-group position", () => {
+    beforeEach(() => {
+      cy.mount(filterMenuTwoGroups);
+      cy.get("[udex-filter-menu]").shadow().find(".udex-filter-menu__trigger").click();
+    });
+
+    // Regression: the sibling-group tree markup makes JAWS/NVDA compute a flattened
+    // posinset/setsize across every group's children (e.g. "5 of 7" instead of
+    // "1 of 4"). Explicit per-group aria-posinset/aria-setsize on each child treeitem
+    // restores the within-group count. Two groups of different sizes (Backend x3,
+    // Frontend x4) prove the count restarts per group rather than spanning all 7.
+    it('exposes per-group aria-posinset/aria-setsize on child treeitems so screen readers count within each group', () => {
+      // Backend Languages children: 1..3 within their own group of 3.
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(0)
+        .find("udex-list-item").then($items => {
+          expect($items).to.have.length(3);
+        });
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(0)
+        .find("udex-list-item").eq(0).shadow().find("[part=item]")
+        .should("have.attr", "aria-posinset", "1").and("have.attr", "aria-setsize", "3");
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(0)
+        .find("udex-list-item").eq(2).shadow().find("[part=item]")
+        .should("have.attr", "aria-posinset", "3").and("have.attr", "aria-setsize", "3");
+
+      // Frontend Languages children: count restarts at 1 with its own setsize (4),
+      // NOT continued as "4 of 7" across both groups.
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(1)
+        .find("udex-list-item").eq(0).shadow().find("[part=item]")
+        .should("have.attr", "aria-posinset", "1").and("have.attr", "aria-setsize", "4");
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(1)
+        .find("udex-list-item").eq(3).shadow().find("[part=item]")
+        .should("have.attr", "aria-posinset", "4").and("have.attr", "aria-setsize", "4");
+    });
+
+    it('positions each group header among the groups (N of group count)', () => {
+      // The collapsible MultiSelect header treeitem is the inner list-item's [part=item].
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(0)
+        .shadow().find("udex-list-item").shadow().find("[part=item]")
+        .should("have.attr", "aria-posinset", "1").and("have.attr", "aria-setsize", "2");
+      cy.get("[udex-filter-menu]").shadow().find("udex-list-group-header").eq(1)
+        .shadow().find("udex-list-item").shadow().find("[part=item]")
+        .should("have.attr", "aria-posinset", "2").and("have.attr", "aria-setsize", "2");
+    });
+  });
+
   describe("Filter Menu Single with search", () => {
     beforeEach(() => {
       cy.mount(filterMenuSingleWithSearch);
@@ -1597,6 +1659,16 @@ describe("Filter Menu component", () => {
           .find(".udex-list__group-list__content [role=listbox]").should("not.exist");
       });
 
+      it("content region (role=\"group\") is a sibling of the header list-item, not nested in its subtree slot", () => {
+        // Sibling-group structure: the content region is emitted alongside the
+        // header list-item inside .udex-list__group-list, and the header item
+        // carries no _subtree marker (no nested composition).
+
+        cy.get("#filter-menu-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-list > .udex-list__group-list__content[role='group']").should("exist");
+      });
+
       // Updated: host udex-list-item has role="none"; the treeitem role is set via
       // accessible-role on the host (which the template renders onto [part=item]).
       it("child items get accessible-role=\"treeitem\" on their host element", () => {
@@ -1687,10 +1759,28 @@ describe("Filter Menu component", () => {
           .find("#udex-list").should("have.attr", "role", "tree");
       });
 
-      it("non-collapsible group's list container has role=\"group\" (not \"listbox\") in tree mode", () => {
+      it("non-collapsible group's list container is transparent (role=\"none\") in tree mode so the header sits at the top level", () => {
         cy.get("#filter-menu-tree-non-collapsible").shadow()
           .find("udex-list-group-header").shadow()
-          .find(".udex-list__group-list").should("have.attr", "role", "group");
+          .find(".udex-list__group-list").should("have.attr", "role", "none");
+      });
+
+      it("children are wrapped in a nested role=\"group\" that sits as a sibling of the header treeitem", () => {
+        // Sibling-group structure: the role="group" container is emitted alongside
+        // the header inside .udex-list__group-list; the header item is not composed
+        // into a subtree slot.
+        cy.get("#filter-menu-tree-non-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-list > [role='group']").should("exist");
+
+        cy.get("#filter-menu-tree-non-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find("udex-list-item").should("not.have.attr", "_subtree");
+
+        cy.get("#filter-menu-tree-non-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find("udex-list-item").shadow()
+          .find("[part=item] slot[name='subtree']").should("not.exist");
       });
 
       it("non-collapsible active header's inner udex-list-item has accessible-role=\"treeitem\"", () => {
@@ -1707,6 +1797,8 @@ describe("Filter Menu component", () => {
           .should("have.attr", "role", "treeitem")
           .and("have.attr", "aria-checked", "false");
       });
+
+
     });
 
     describe("Non-interactive group header in tree mode", () => {
@@ -1799,6 +1891,69 @@ describe("Filter Menu component", () => {
           .should("have.attr", "role", "treeitem");
       });
 
+      it("nests the content region (role=\"group\") inside the treeitem div (conformant tree)", () => {
+        // Conformant nesting: the role="group" content region is a DESCENDANT of the
+        // .udex-list__group-content treeitem, so screen readers count children per group
+        // natively (no author aria-posinset needed — matches the List component). This is
+        // what restores JAWS per-item counting under arrow navigation.
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-list > .udex-list__group-content--nested[role='treeitem']").should("exist");
+
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-content--nested[role='treeitem'] .udex-list__group-list__content[role='group']").should("exist");
+
+        // The content region is no longer emitted as a sibling of the treeitem.
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-list > .udex-list__group-list__content[role='group']").should("not.exist");
+
+        // The visible header row wrapper now sits inside the treeitem (ring/layout target).
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-content--nested[role='treeitem'] > .udex-list__group-header-row").should("exist");
+      });
+
+      it("emits explicit aria-posinset/aria-setsize on single-select child treeitems (forces JAWS re-announcement)", () => {
+        // Conformant nesting makes the structural count match the explicit values, so
+        // JAWS trusts and re-announces on every arrow step — not just on group entry.
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header")
+          .find("udex-list-item").eq(0).shadow()
+          .find("[part=item]").should("have.attr", "aria-posinset", "1");
+
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header")
+          .find("udex-list-item").eq(0).shadow()
+          .find("[part=item]").should("have.attr", "aria-setsize");
+      });
+
+
+      it("group header div does NOT render a -treeposition describedby node", () => {
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find("[id$=-treeposition]").should("not.exist");
+
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-content")
+          .should("not.have.attr", "aria-describedby");
+      });
+
+      // The chevron button inside the collapsible header carries an "Expand"/"Collapse"
+      // accessible-name (a mouse affordance). Without an explicit aria-labelledby, that
+      // label folds into the treeitem's computed name, so VoiceOver announces the state
+      // twice ("… Collapse … expanded"). Pinning the name to the heading (+ supporting
+      // text) keeps the chevron's label out; aria-expanded still conveys the state.
+      it("group header div pins its accessible name to the heading (excludes the chevron's label)", () => {
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-content")
+          .should("have.attr", "aria-labelledby")
+          .and("match", /^group-heading/);
+      });
+
       it("group header div has aria-expanded=\"true\" when expanded (default)", () => {
         cy.get("#filter-menu-single-tree-collapsible").shadow()
           .find("udex-list-group-header").shadow()
@@ -1923,7 +2078,7 @@ describe("Filter Menu component", () => {
       it("clicking the header body does NOT select any child", () => {
         cy.get("#filter-menu-single-tree-collapsible").shadow()
           .find("udex-list-group-header").shadow()
-          .find(".udex-list__group-content").click();
+          .find(".udex-list__group-header-row").click();
 
         cy.get("#filter-menu-single-tree-collapsible").shadow()
           .find("udex-list-group-header")
@@ -2000,6 +2155,16 @@ describe("Filter Menu component", () => {
           .find("udex-list-group-header").shadow()
           .find(".udex-list__group-content");
 
+      // The visible header body. In the conformant nested tree the treeitem div
+      // (.udex-list__group-content) wraps the whole subtree, so its geometric centre is
+      // over a child item — clicking it is "covered". The header row is the actual body
+      // (it sits above the children), so clicks target it while attribute assertions stay
+      // on the treeitem div above.
+      const headerRow = () =>
+        cy.get("#filter-menu-single-tree-collapsible").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group-header-row");
+
       const arrowButton = () =>
         cy.get("#filter-menu-single-tree-collapsible").shadow()
           .find("udex-list-group-header").shadow()
@@ -2020,14 +2185,14 @@ describe("Filter Menu component", () => {
         headerDiv().should("not.have.attr", "aria-selected");
         headerDiv().should("not.have.attr", "aria-checked");
 
-        headerDiv().click();
+        headerRow().click();
 
         headerDiv().should("not.have.attr", "aria-selected");
         headerDiv().should("not.have.attr", "aria-checked");
       });
 
       it("clicking the header body does NOT set the selected property on the host group header", () => {
-        headerDiv().click();
+        headerRow().click();
 
         cy.get("#filter-menu-single-tree-collapsible").shadow()
           .find("udex-list-group-header").then($gh => {
@@ -2036,7 +2201,7 @@ describe("Filter Menu component", () => {
       });
 
       it("clicking the header body does NOT select any child item", () => {
-        headerDiv().click();
+        headerRow().click();
 
         childItems().each($item => {
           cy.wrap($item).shadow()
@@ -2049,7 +2214,7 @@ describe("Filter Menu component", () => {
       it("clicking the header body does NOT collapse the group", () => {
         headerDiv().should("have.attr", "aria-expanded", "true");
 
-        headerDiv().click();
+        headerRow().click();
 
         headerDiv().should("have.attr", "aria-expanded", "true");
         cy.get("#filter-menu-single-tree-collapsible").shadow()
@@ -2143,24 +2308,49 @@ describe("Filter Menu component", () => {
           .find("[udex-list]").should("not.have.attr", "aria-multiselectable");
       });
 
-      // Updated: `accessibleRoleForList` no longer collapses to `"group"` for grouped
-      // non-tree mode — it now returns `defaultAccessibleRole` (`"listbox"`) in every
-      // non-tree case. JAWS enters forms mode on `role="listbox"` but stays in virtual
-      // buffer mode on `role="group"`, so the fix is to keep the widget role stable.
-      it("inner list div has role=\"listbox\", not \"tree\"", () => {
+      // Per-group-listbox pattern: JAWS ignores role="group" boundaries and author
+      // aria-posinset within a single listbox (it read the flat total "1 of 8" instead of
+      // "1 of 4"), but counts options natively within a flat listbox. So each group becomes
+      // its own role="listbox" and the outer #udex-list drops its listbox role (it would
+      // otherwise be an invalid nested listbox). Not a tree.
+      it("inner list div is presentational (role=\"presentation\"), not listbox or tree", () => {
         cy.get("#filter-menu-single-group").shadow()
           .find("[udex-list]").shadow()
-          .find("#udex-list").should("have.attr", "role", "listbox");
+          .find("#udex-list")
+          .should("have.attr", "role", "presentation");
+      });
+
+      it("each group renders its own role=\"listbox\" labelled by its heading", () => {
+        cy.get("#filter-menu-single-group").shadow()
+          .find("udex-list-group-header").shadow()
+          .find("[role=listbox]")
+          .should("have.attr", "aria-labelledby", "group-heading");
       });
 
-      // Updated: `accessible-role="tree"` on the group header host was replaced by the
-      // `_tree-mode` boolean attribute. SingleSelect must not activate tree mode, so the
-      // attribute must be absent (and the host role stays "group" for non-tree grouped
-      // mode).
-      it("group header host has role=\"group\" and no _tree-mode attribute", () => {
+      it("the outer group wrapper is transparent (role=\"none\") so the label is not announced twice", () => {
+        cy.get("#filter-menu-single-group").shadow()
+          .find("udex-list-group-header").shadow()
+          .find(".udex-list__group")
+          .should("have.attr", "role", "none")
+          .and("not.have.attr", "aria-labelledby");
+      });
+
+      it("group child items have role=\"option\" (inside the per-group listbox), not treeitem", () => {
+        cy.get("#filter-menu-single-group").shadow()
+          .find("udex-list-group-header")
+          .find("udex-list-item").eq(0).shadow()
+          .find("[part=item]")
+          .should("have.attr", "role", "option")
+          .and("not.have.attr", "role", "treeitem");
+      });
+
+      // The group header host stays role="none" (transparent). The widget role now lives on
+      // the inner per-group role="listbox" (asserted above), not on the host or the outer
+      // div.udex-list__group, so the heading is announced once.
+      it("group header host has role=\"none\" and no _tree-mode attribute", () => {
         cy.get("#filter-menu-single-group").shadow()
           .find("udex-list-group-header")
-          .should("have.attr", "role", "group")
+          .should("have.attr", "role", "none")
           .and("not.have.attr", "_tree-mode");
       });