chore: merge main

rubencarvalho · rubencarvalho · commit 001069921e96 · 2025-10-29T17:13:09.000+01:00
diff --git a/.changeset/weak-streets-raise.md b/.changeset/weak-streets-raise.md
@@ -0,0 +1,5 @@
+---
+'@spectrum-web-components/overlay': patch
+---
+
+- **Fixed**: Expanded `<overlay-trigger>` `type` property to accept all overlay types ('auto', 'hint', 'manual', 'modal', 'page') instead of the incorrect, previous restricted subset.
diff --git a/1st-gen/packages/combobox/README.md b/1st-gen/packages/combobox/README.md
@@ -236,7 +236,7 @@ For exceptional cases, provide an accessible label via the `label` attribute.
 
 #### Provide help text and tooltips in the correct location
 
-It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="help-text-negative"` and tooltips must be included via the `slot="tooltip"`.
+It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="negative-help-text"` and tooltips must be included via the `slot="tooltip"`.
 
 See [help text](../help-text) and [tooltip](../tooltip) for more information.
 
diff --git a/1st-gen/packages/help-text/README.md b/1st-gen/packages/help-text/README.md
@@ -100,7 +100,7 @@ For help text, usually the error is related to something that needs to be fixed
     <sp-help-text slot="help-text">
         Create a password with at least 8 characters.
     </sp-help-text>
-    <sp-help-text variant="negative" slot="help-text-negative">
+    <sp-help-text variant="negative" slot="negative-help-text">
         Passwords must be at least 8 characters
     </sp-help-text>
 </sp-textfield>
@@ -149,12 +149,12 @@ When the content associated to the element is disabled, use the `disabled` attri
 
 Good, descriptive help text includes 1-2 short sentences of information such as:
 
--   An overall description of an input field or controls
--   Hints for what kind of information needs to be inputted or selected
--   Specific formatting examples or requirements
+- An overall description of an input field or controls
+- Hints for what kind of information needs to be inputted or selected
+- Specific formatting examples or requirements
 
 #### Ensure help text and field share the same root
 
-It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="help-text-negative"` in an `<sp-text-field>`, `<sp-field-group>`, `<sp-combobox>` or `<sp-picker>`.
+It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="negative-help-text"` in an `<sp-text-field>`, `<sp-field-group>`, `<sp-combobox>` or `<sp-picker>`.
 
 To add help text to your own custom element, see [Help Text Mixin](./help-text-mixin/).
diff --git a/1st-gen/packages/overlay/README.md b/1st-gen/packages/overlay/README.md
@@ -267,10 +267,42 @@ Some Overlays will always be passed focus (e.g. modal or page Overlays). When th
 
 #### trigger
 
-The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which to position the Overlay.
+The `trigger` attribute accepts a string ID reference for the trigger element combined with the interaction type.
+
+The format is `"elementId@interaction"`, where:
+
+- `elementId` is the ID of the HTML element to use as the trigger
+- `interaction` is required and can be `click`, `hover`, or `longpress`
+
+Examples:
+
+```html
+<sp-button id="my-button">Open Overlay</sp-button>
+
+<!-- Explicit click interaction -->
+<sp-overlay trigger="my-button@click" placement="top-start">
+    <sp-popover>Click popover</sp-popover>
+</sp-overlay>
+
+<!-- Explicit hover interaction -->
+<sp-overlay trigger="my-button@hover" placement="right-start">
+    <sp-popover>Hover popover</sp-popover>
+</sp-overlay>
+
+<!-- Explicit longpress interaction -->
+<sp-overlay trigger="my-button@longpress" placement="bottom-start">
+    <sp-popover>Longpress popover</sp-popover>
+</sp-overlay>
+```
+
+#### triggerElement
+
+The `triggerElement` property accepts an `HTMLElement` or a `VirtualTrigger` from which to position the Overlay.
 
 - You can import the `VirtualTrigger` class from the overlay package to create a virtual trigger that can be used to position an Overlay. This is useful when you want to position an Overlay relative to a point on the screen that is not an element in the DOM, like the mouse cursor.
 
+#### type
+
 The `type` of an Overlay outlines a number of things about the interaction model within which it works:
 
 <sp-tabs selected="modal" auto label="Type attribute options">
@@ -529,7 +561,7 @@ This means that in both cases, if the transition is meant to be a part of the op
     placement=${Placement}
     receives-focus=${'true' | 'false' | 'auto' (default)
     trigger=${string | ${string}@${string}}
-    .triggerElement=${HTMLElement}
+    .triggerElement=${HTMLElement | VirtualTrigger}
     .triggerInteraction=${'click' | 'longpress' | 'hover'}
     type=${'auto' | 'hint' | 'manual' | 'modal' | 'page'}
     ?allow-outside-click=${boolean}
diff --git a/1st-gen/packages/overlay/overlay-trigger.md b/1st-gen/packages/overlay/overlay-trigger.md
@@ -77,78 +77,129 @@ When using the `placement` attribute of an `<overlay-trigger>` (`"top" |"top-sta
 
 #### Type
 
-<sp-tabs selected="inline" auto label="Type attribute options">
-<sp-tab value="inline">Inline</sp-tab>
-<sp-tab-panel value="inline">
+The `type` of an Overlay outlines a number of things about the interaction model within which it works:
 
-`'inline'` type inserts the overlay after the trigger in the tab order. This creates a natural flow where:
+**Note:** The `type` attribute only affects click-triggered overlays. Hover overlays always use `hint` type behavior, and longpress overlays always use `auto` type behavior. For more control over hover and longpress overlay types, use `<sp-overlay>` directly.
 
-- Forward tab: Goes to the next logical element
-- Backward tab (shift): Returns to the trigger
+<sp-tabs selected="modal" auto label="Type attribute options">
+<sp-tab value="modal">Modal</sp-tab>
+<sp-tab-panel value="modal">
+
+`'modal'` Overlays create a modal context that traps focus within the content and prevents interaction with the rest of the page. The overlay manages focus trapping and accessibility features like `aria-modal="true"` to ensure proper screen reader behavior.
+
+They should be used when you need to ensure that the user has interacted with the content of the Overlay before continuing with their work. This is commonly used for dialogs that require a user to confirm or cancel an action before continuing.
 
 ```html
-<overlay-trigger type="inline" placement="bottom">
-    <sp-button slot="trigger">Open Menu</sp-button>
-    <sp-popover slot="click-content">
-        <sp-menu>
-            <sp-menu-item>Option 1</sp-menu-item>
-            <sp-menu-item>Option 2</sp-menu-item>
-        </sp-menu>
-    </sp-popover>
+<overlay-trigger type="modal" triggered-by="click">
+    <sp-button slot="trigger">Open modal</sp-button>
+    <sp-dialog-wrapper
+        slot="click-content"
+        headline="Signin form"
+        dismissable
+        underlay
+    >
+        <p>I am a modal type overlay.</p>
+        <sp-field-label>Enter your email</sp-field-label>
+        <sp-textfield placeholder="test@gmail.com"></sp-textfield>
+        <sp-action-button
+            onClick="
+                this.dispatchEvent(
+                    new Event('close', {
+                        bubbles: true,
+                        composed: true,
+                    })
+                );
+            "
+        >
+            Sign in
+        </sp-action-button>
+    </sp-dialog-wrapper>
 </overlay-trigger>
 ```
 
 </sp-tab-panel>
-<sp-tab value="replace">Replace</sp-tab>
-<sp-tab-panel value="replace">
+<sp-tab value="page">Page</sp-tab>
+<sp-tab-panel value="page">
 
-`'replace'` type inserts the overlay as if it were the trigger itself in the tab order. This means:
+`'page'` Overlays behave similarly to `'modal'` Overlays by creating a modal context and trapping focus, but they will not be allowed to close via the "light dismiss" algorithm (e.g. the Escape key).
 
-- Forward tab: Goes to the next logical element
-- Backward tab (shift): Goes to the element before the trigger
+A page overlay could be used for a full-screen menu on a mobile website. When the user clicks on the menu button, the entire screen is covered with the menu options.
 
 ```html
-<overlay-trigger type="replace" placement="bottom">
-    <sp-button slot="trigger">Show Details</sp-button>
-    <sp-popover slot="click-content">
-        <sp-dialog>
-            <p>Details panel that replaces trigger in tab order</p>
-            <sp-button
-                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }))"
-            >
-                Close
-            </sp-button>
-        </sp-dialog>
+<overlay-trigger type="page" triggered-by="click">
+    <sp-button slot="trigger">Open page</sp-button>
+    <sp-dialog-wrapper
+        slot="click-content"
+        headline="Full screen menu"
+        mode="fullscreenTakeover"
+        cancel-label="Close"
+    >
+        <p>I am a page type overlay.</p>
+    </sp-dialog-wrapper>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="hint">Hint</sp-tab>
+<sp-tab-panel value="hint">
+
+`'hint'` Overlays are much like tooltips so they are not just ephemeral, but they are delivered primarily as a visual helper and exist outside of the tab order. In this way, be sure _not_ to place interactive content within this type of Overlay.
+
+This overlay type does not accept focus and does not interfere with the user's interaction with the rest of the page.
+
+```html
+<overlay-trigger type="hint" triggered-by="hover">
+    <sp-button slot="trigger">Open hint</sp-button>
+    <sp-tooltip slot="click-content">
+        I am a hint type overlay. I am not interactive and will close when the
+        user interacts with the page.
+    </sp-tooltip>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="auto">Auto</sp-tab>
+<sp-tab-panel value="auto">
+
+`'auto'` Overlays provide a place for content that is ephemeral _and_ interactive. These Overlays can accept focus and remain open while interacting with their content. They will close when focus moves outside the overlay or when clicking elsewhere on the page.
+
+```html
+<overlay-trigger type="auto" triggered-by="click" placement="bottom">
+    <sp-button slot="trigger">Open overlay</sp-button>
+    <sp-popover slot="click-content" dialog>
+        <p>
+            My slider in overlay element:
+            <sp-slider label="Slider Label - Editable" editable></sp-slider>
+        </p>
     </sp-popover>
 </overlay-trigger>
 ```
 
 </sp-tab-panel>
-<sp-tab value="modal">Modal</sp-tab>
-<sp-tab-panel value="modal">
+<sp-tab value="manual">Manual</sp-tab>
+<sp-tab-panel value="manual">
+
+`'manual'` Overlays act much like `'auto'` Overlays, but do not close when losing focus or interacting with other parts of the page.
 
-`'modal'` type creates a separate tab order and traps focus within the overlay content until the required interaction is complete. This is ideal for important interactions that need user attention.
+Note: When a `'manual'` Overlay is at the top of the "overlay stack", it will still respond to the Escape key and close.
 
 ```html
-<overlay-trigger type="modal">
-    <sp-button slot="trigger">Open Settings</sp-button>
-    <sp-dialog-wrapper
-        slot="click-content"
-        headline="Settings"
-        dismissable
-        underlay
-    >
-        <sp-field-label>Theme</sp-field-label>
-        <sp-picker>
-            <sp-menu-item>Light</sp-menu-item>
-            <sp-menu-item>Dark</sp-menu-item>
-        </sp-picker>
-        <sp-button
-            onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }))"
-        >
-            Save
-        </sp-button>
-    </sp-dialog-wrapper>
+<style>
+    .chat-container {
+        position: fixed;
+        bottom: 1em;
+        left: 1em;
+    }
+</style>
+<overlay-trigger type="manual" triggered-by="click">
+    <sp-button slot="trigger">Open manual</sp-button>
+    <sp-popover slot="click-content" class="chat-container">
+        <sp-dialog dismissable>
+            <span slot="heading">Chat Window</span>
+            <sp-textfield placeholder="Enter your message"></sp-textfield>
+            <sp-action-button>Send</sp-action-button>
+        </sp-dialog>
+    </sp-popover>
 </overlay-trigger>
 ```
 
diff --git a/1st-gen/packages/overlay/src/OverlayTrigger.ts b/1st-gen/packages/overlay/src/OverlayTrigger.ts
@@ -26,7 +26,8 @@ import type { Placement } from '@floating-ui/dom';
 
 import type { BeforetoggleOpenEvent } from './events.js';
 import type { Overlay } from './Overlay.js';
-import type { OverlayTriggerInteractions } from './overlay-types';
+import type { OverlayTypes } from './overlay-types.js';
+// eslint-disable-next-line import/no-extraneous-dependencies
 import '@spectrum-web-components/overlay/sp-overlay.js';
 
 import overlayTriggerStyles from './overlay-trigger.css.js';
@@ -90,7 +91,7 @@ export class OverlayTrigger extends SpectrumElement {
     public placement?: Placement;
 
     @property()
-    public type?: OverlayTriggerInteractions;
+    public type?: OverlayTypes;
 
     @property({ type: Number })
     public offset = 6;
@@ -225,7 +226,7 @@ export class OverlayTrigger extends SpectrumElement {
                 .placement=${this.clickPlacement || this.placement}
                 .triggerElement=${this.targetContent[0]}
                 .triggerInteraction=${'click'}
-                .type=${this.type !== 'modal' ? 'auto' : 'modal'}
+                .type=${this.type || 'auto'}
                 @beforetoggle=${this.handleBeforetoggle}
                 .receivesFocus=${this.receivesFocus}
             >
diff --git a/1st-gen/packages/overlay/src/overlay-types.ts b/1st-gen/packages/overlay/src/overlay-types.ts
@@ -23,6 +23,15 @@ export { Placement };
 
 export type OverlayTypes = 'auto' | 'hint' | 'manual' | 'modal' | 'page';
 
+// Constant array for runtime use (tests, validation, etc.)
+export const OVERLAY_TYPES = [
+    'auto',
+    'hint',
+    'manual',
+    'modal',
+    'page',
+] as const satisfies readonly OverlayTypes[];
+
 export type TriggerInteraction = 'click' | 'longpress' | 'hover';
 
 export type TriggerInteractions = OverlayTypes;
diff --git a/1st-gen/packages/overlay/test/index.ts b/1st-gen/packages/overlay/test/index.ts
@@ -24,8 +24,8 @@ import { Button } from '@spectrum-web-components/button';
 import '@spectrum-web-components/button/sp-button.js';
 import '@spectrum-web-components/dialog/sp-dialog.js';
 import {
+    OVERLAY_TYPES,
     OverlayTrigger,
-    TriggerInteractions,
 } from '@spectrum-web-components/overlay';
 import { Popover } from '@spectrum-web-components/popover';
 import '@spectrum-web-components/popover/sp-popover.js';
@@ -113,10 +113,10 @@ export const runOverlayTriggerTests = (type: string): void => {
 
                 this.innerTrigger = this.testDiv.querySelector(
                     '#inner-trigger'
-                ) as OverlayTrigger;
+                )! as OverlayTrigger;
                 this.outerTrigger = this.testDiv.querySelector(
                     '#trigger'
-                ) as OverlayTrigger;
+                )! as OverlayTrigger;
                 this.innerButton = this.testDiv.querySelector(
                     '#inner-button'
                 ) as Button;
@@ -213,20 +213,19 @@ export const runOverlayTriggerTests = (type: string): void => {
                 ).to.be.true;
             });
 
-            ['modal', 'replace', 'inline'].map((type: string) => {
+            OVERLAY_TYPES.map((type) => {
                 it(`opens a popover - [type="${type}"]`, async function () {
-                    this.outerTrigger.type = type as Extract<
-                        TriggerInteractions,
-                        'inline' | 'modal' | 'replace'
-                    >;
-                    await elementUpdated(this.outerTrigger);
+                    const outerTrigger = this.outerTrigger as OverlayTrigger;
+
+                    outerTrigger.type = type;
+                    await elementUpdated(outerTrigger);
                     expect(
                         await isOnTopLayer(this.outerClickContent),
                         'popover not available at point'
                     ).to.be.false;
 
                     expect(this.outerButton).to.exist;
-                    const opened = oneEvent(this.outerTrigger, 'sp-opened');
+                    const opened = oneEvent(outerTrigger, 'sp-opened');
                     this.outerButton.click();
                     await opened;
                     expect(
diff --git a/1st-gen/packages/picker/test/index.ts b/1st-gen/packages/picker/test/index.ts
@@ -1085,11 +1085,9 @@ export function runPickerTests(): void {
             el.insertAdjacentElement('afterend', input);
 
             el.focus();
-            if (!isWebKit()) {
-                await sendTabKey();
-                expect(document.activeElement).to.equal(input);
-                await sendShiftTabKey();
-            }
+            await sendTabKey();
+            expect(document.activeElement).to.equal(input);
+            await sendShiftTabKey();
             expect(document.activeElement).to.equal(el);
             const opened = oneEvent(el, 'sp-opened');
             await sendKeys({ press: 'Enter' });
@@ -1124,11 +1122,9 @@ export function runPickerTests(): void {
             el.insertAdjacentElement('afterend', input);
 
             el.focus();
-            if (!isWebKit()) {
-                await sendTabKey();
-                expect(document.activeElement).to.equal(input);
-                await sendKeys({ press: 'Shift+Tab' });
-            }
+            await sendTabKey();
+            expect(document.activeElement).to.equal(input);
+            await sendKeys({ press: 'Shift+Tab' });
             expect(document.activeElement).to.equal(el);
             const opened = oneEvent(el, 'sp-opened');
             await sendKeys({ down: 'Enter' });
diff --git a/1st-gen/packages/radio/radio-group.md b/1st-gen/packages/radio/radio-group.md
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@spectrum-web-components/overlay': patch
 +---
++
 +- **Fixed**: Expanded `<overlay-trigger>` `type` property to accept all overlay types ('auto', 'hint', 'manual', 'modal', 'page') instead of the incorrect, previous restricted subset.