feat(ui5-toolbar-item): expose :state(overflowed) CSS custom state

Add CSS custom state that allows styling toolbar items differently
when they are in the overflow popover. The state is managed via
the existing isOverflowed property using ElementInternals.states.

- Add getter/setter for isOverflowed to manage the custom state
- Document the CSS custom state in class JSDoc
- Add test sample and Cypress test

Author: dobrinyonkov

packages/main/cypress/specs/ToolbarItem.cy.tsx

@@ -1,5 +1,6 @@
 import Toolbar from "../../src/Toolbar.js";
 import ToolbarItem from "../../src/ToolbarItem.js";
+import ToolbarButton from "../../src/ToolbarButton.js";
 import Button from "../../src/Button.js";
 import Switch from "../../src/Switch.js";
 import MultiComboBox from "../../src/MultiComboBox.js";
@@ -9,6 +10,8 @@ import ComboBoxItem from "../../src/ComboBoxItem.js";
 import DatePicker from "../../src/DatePicker.js";
 import Select from "../../src/Select.js";
 import Option from "../../src/Option.js";
+import CheckBox from "../../src/CheckBox.js";
+import add from "@ui5/webcomponents-icons/dist/add.js";
 
 describe("Toolbar Item Properties", () => {
 	it("Should render ui5-toolbar-item with correct properties and not suppress events", () => {
@@ -764,4 +767,27 @@ describe("Toolbar Item Closing Events - overflowCloseEvents functionality (IOver
 				expect(closingEvents).to.include("extra-event");
 			});
 	});
+});
+
+describe("ToolbarItem CSS Custom State", () => {
+	it("Should set :state(overflowed) when item is in overflow", () => {
+		cy.mount(
+			<div style={{ width: "200px" }}>
+				<Toolbar>
+					<ToolbarButton text="Button 1" icon={add}></ToolbarButton>
+					<ToolbarItem id="test-item" overflow-priority="AlwaysOverflow">
+						<CheckBox text="Check"></CheckBox>
+					</ToolbarItem>
+				</Toolbar>
+			</div>
+		);
+
+		cy.wait(500);
+
+		cy.get("#test-item").then($item => {
+			const item = $item[0] as ToolbarItem;
+			// @ts-ignore
+			expect(item._internals.states.has("overflowed")).to.be.true;
+		});
+	});
 });

packages/main/src/ToolbarItem.ts

@@ -42,10 +42,25 @@ interface IOverflowToolbarItem extends HTMLElement {
  * @class
  *
  * Represents an abstract class for items, used in the `ui5-toolbar`.
+ *
+ * ### CSS Custom States
+ *
+ * The `ui5-toolbar-item` exposes the following CSS custom states for styling:
+ *
+ * | State | Description |
+ * |-------|-------------|
+ * | `:state(overflowed)` | Applied when the item is displayed in the overflow popover. Use this state to apply different styles when the item is overflowed. |
+ *
+ * **Example:**
+ * ```css
+ * ui5-toolbar-item:state(overflowed) {
+ *     flex-direction: column;
+ * }
+ * ```
+ *
  * @constructor
  * @extends UI5Element
  * @public
- * @experimental This module is experimental and its API might change significantly in future.
  * @since 1.17.0
  */
 class ToolbarItem extends UI5Element {
@@ -78,13 +93,24 @@ class ToolbarItem extends UI5Element {
 	 * @protected
 	 * @since 2.11.0
 	 */
+	get isOverflowed(): boolean {
+		return this._isOverflowed;
+	}
 
-	@property({ type: Boolean })
-	isOverflowed: boolean = false;
+	set isOverflowed(value: boolean) {
+		this._isOverflowed = value;
+
+		if (value) {
+			this._internals.states.add("overflowed");
+		} else {
+			this._internals.states.delete("overflowed");
+		}
+	}
 
 	_isRendering = true;
 	_maxWidth = 0;
 	_wrapperChecked = false;
+	_isOverflowed: boolean = false;
 	fireCloseOverflowRef = this.fireCloseOverflow.bind(this);
 
 	closeOverflowSet = {

packages/main/test/pages/ToolbarItems.html

@@ -183,12 +183,49 @@
             </ui5-toolbar-item>
 
             <!-- Toolbar Item with Date Picker -->
-            <ui5-toolbar-item>
+            <ui5:toolbar-item>
                 <ui5-date-picker placeholder="Select a date"></ui5-date-picker>
-            </ui5-toolbar-item>
+            </ui5:toolbar-item>
         </ui5-toolbar>
     </section>
+
+		<!-- Test section for CSS custom state :state(overflowed) -->
+		<ui5-title level="H3">Toolbar with :state(overflowed) CSS Custom State (resize to test)</ui5-title>
+		<br />
+		<style>
+			/* Use CSS custom state :state(overflowed) to style items when in overflow popover */
+			#overflow-state-toolbar [ui5-toolbar-item]:state(overflowed) {
+				/* When overflowed, change checkboxes and radio buttons to column layout */
+				display: flex;
+				flex-direction: column;
+			}
+
+			/* Visual indicator for the test */
+			#overflow-state-toolbar [ui5-toolbar-item]:state(overflowed)::before {
+				content: "Overflowed:";
+				font-size: 0.75rem;
+				color: var(--sapNeutralTextColor);
+				margin-bottom: 0.25rem;
+			}
+		</style>
+		<section>
+			<ui5-toolbar id="overflow-state-toolbar" style="max-width: 400px;">
+				<ui5-toolbar-button icon="add" text="Add"></ui5-toolbar-button>
+				<!-- Toolbar Item with Radio Buttons - should display in column when overflowed -->
+				<ui5-toolbar-item id="overflow-state-radio-item">
+					<ui5-radio-button name="overflow-group" text="Option A" selected></ui5-radio-button>
+					<ui5-radio-button name="overflow-group" text="Option B"></ui5-radio-button>
+					<ui5-radio-button name="overflow-group" text="Option C"></ui5-radio-button>
+				</ui5-toolbar-item>
+				<!-- Toolbar Item with Checkboxes - should display in column when overflowed -->
+				<ui5-toolbar-item id="overflow-state-checkbox-item">
+					<ui5-checkbox text="Check A"></ui5-checkbox>
+					<ui5-checkbox text="Check B" checked></ui5-checkbox>
+					<ui5-checkbox text="Check C"></ui5-checkbox>
+				</ui5-toolbar-item>
+				<ui5-toolbar-button icon="decline" text="Remove"></ui5-toolbar-button>
+			</ui5-toolbar>
+		</section>
 	</div>
 </body>
-
 </html>