From 58ce7b620c447e2b68afb921de30ac5c9902833b Mon Sep 17 00:00:00 2001 From: Sai Asish Y Date: Thu, 21 May 2026 02:39:45 -0700 Subject: [PATCH] docs(list, menu): clarify request-activation event audience --- docs/components/list.md | 2 +- docs/components/menu.md | 2 +- list/internal/listitem/list-item.ts | 5 ++++- menu/internal/submenu/sub-menu.ts | 6 +++++- 4 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/components/list.md b/docs/components/list.md index e4aaba19d2..aa53ce00a7 100644 --- a/docs/components/list.md +++ b/docs/components/list.md @@ -433,7 +433,7 @@ Token | Default value | Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | | --- | --- | --- | --- | --- | -| `request-activation` | `Event` | Yes | Yes | Requests the list to set `tabindex=0` on the item and focus it. | +| `request-activation` | `Event` | Yes | Yes | Requests the list to set `tabindex=0` on the item and focus it. Used internally for list keyboard navigation; most applications do not need to listen for this event. It is exposed for authors building their own list-item replacements or wrapping items in a custom controller. | diff --git a/docs/components/menu.md b/docs/components/menu.md index 08080706e0..9c7b362dc9 100644 --- a/docs/components/menu.md +++ b/docs/components/menu.md @@ -634,7 +634,7 @@ a sharp 0px border radius.](images/menu/theming.webp) | Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description | | --- | --- | --- | --- | --- | | `deactivate-items` | `Event` | Yes | Yes | Requests the parent menu to deselect other items when a submenu opens. | -| `request-activation` | `Event` | Yes | Yes | Requests the parent to make the slotted item focusable and focus the item. | +| `request-activation` | `Event` | Yes | Yes | Requests the parent to make the slotted item focusable and focus the item. Used internally for menu keyboard navigation; most applications do not need to listen for this event. It is exposed for authors building their own menu-item replacements, or for advanced cases where you want to call `preventDefault`/`stopPropagation` on it to override default focus handling. | | `deactivate-typeahead` | `Event` | Yes | Yes | Requests the parent menu to deactivate the typeahead functionality when a submenu opens. | | `activate-typeahead` | `Event` | Yes | Yes | Requests the parent menu to activate the typeahead functionality when a submenu closes. | diff --git a/list/internal/listitem/list-item.ts b/list/internal/listitem/list-item.ts index 1a644f1537..b0b51d2f80 100644 --- a/list/internal/listitem/list-item.ts +++ b/list/internal/listitem/list-item.ts @@ -30,7 +30,10 @@ const listItemBaseClass = mixinDelegatesAria(LitElement); /** * @fires request-activation {Event} Requests the list to set `tabindex=0` on - * the item and focus it. --bubbles --composed + * the item and focus it. Used internally for list keyboard navigation; most + * applications do not need to listen for this event. It is exposed for + * authors building their own list-item replacements or wrapping items in a + * custom controller. --bubbles --composed */ export class ListItemEl extends listItemBaseClass implements ListItem { /** @nocollapse */ diff --git a/menu/internal/submenu/sub-menu.ts b/menu/internal/submenu/sub-menu.ts index d395ee722a..b88ae6a173 100644 --- a/menu/internal/submenu/sub-menu.ts +++ b/menu/internal/submenu/sub-menu.ts @@ -30,7 +30,11 @@ import {Corner} from '../menu.js'; * @fires deactivate-items {Event} Requests the parent menu to deselect other * items when a submenu opens. --bubbles --composed * @fires request-activation {Event} Requests the parent to make the slotted item - * focusable and focus the item. --bubbles --composed + * focusable and focus the item. Used internally for menu keyboard navigation; + * most applications do not need to listen for this event. It is exposed for + * authors building their own menu-item replacements, or for advanced cases + * where you want to call `preventDefault`/`stopPropagation` on it to override + * default focus handling. --bubbles --composed * @fires deactivate-typeahead {Event} Requests the parent menu to deactivate * the typeahead functionality when a submenu opens. --bubbles --composed * @fires activate-typeahead {Event} Requests the parent menu to activate the