From d208d3f0c2b909551b47fa99e64021132baf6799 Mon Sep 17 00:00:00 2001
From: Sergey Vinogradov <mr.vursen@gmail.com>
Date: Fri, 17 Jan 2025 09:34:37 +0400
Subject: [PATCH] explain how to make disabled buttons focusable

---
 packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts | 15 +++++++++++++++
 packages/menu-bar/src/vaadin-menu-bar-mixin.js   | 15 +++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts b/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts
index f3b7733ba9..00a1ed057e 100644
--- a/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts
+++ b/packages/menu-bar/src/vaadin-menu-bar-mixin.d.ts
@@ -99,6 +99,21 @@ export declare class MenuBarMixinClass {
    *   {text: 'Help'}
    * ];
    * ```
+   *
+   * #### Disabled items
+   *
+   * When an item is disabled, it prevents any user interaction with it, such as
+   * focusing, clicking, or opening a sub-menu. However, for better accessibility,
+   * disabled root-level items (menu bar buttons) can be made focusable so that
+   * screen readers can reach and properly announce them to users. This behavior
+   * can be enabled with the feature flag:
+   *
+   * ```
+   * // Enable before any menu bar is attached to the DOM.
+   * window.Vaadin.featureFlags.focusableDisabledComponents = true
+   * ```
+   *
+   * In Vaadin 25, disabled menu bar buttons will be focusable by default.
    */
   items: MenuBarItem[];
 
diff --git a/packages/menu-bar/src/vaadin-menu-bar-mixin.js b/packages/menu-bar/src/vaadin-menu-bar-mixin.js
index 4d5e37de8d..fece532902 100644
--- a/packages/menu-bar/src/vaadin-menu-bar-mixin.js
+++ b/packages/menu-bar/src/vaadin-menu-bar-mixin.js
@@ -78,6 +78,21 @@ export const MenuBarMixin = (superClass) =>
          * ];
          * ```
          *
+         * #### Disabled items
+         *
+         * When an item is disabled, it prevents any user interaction with it, such as
+         * focusing, clicking, or opening a sub-menu. However, for better accessibility,
+         * disabled root-level items (menu bar buttons) can be made focusable so that
+         * screen readers can reach and properly announce them to users. This behavior
+         * can be enabled with the feature flag:
+         *
+         * ```
+         * // Enable before any menu bar is attached to the DOM.
+         * window.Vaadin.featureFlags.focusableDisabledComponents = true
+         * ```
+         *
+         * In Vaadin 25, disabled menu bar buttons will be focusable by default.
+         *
          * @type {!Array<!MenuBarItem>}
          */
         items: {