feat(ui5-toolbar-button): add showOverflowText property for conditional text display (#12542)

Introduces showOverflowText boolean property that controls text visibility based on overflow state:
- When true: icon-only in toolbar, icon+text in overflow popover
- When false/default: consistent icon+text display in both states
Related to: #12381

Author: NakataCode

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

@@ -544,7 +544,7 @@ describe("ToolbarButton", () => {
 		cy.get("[ui5-toolbar-button][accessible-name]").shadow().find(".ui5-tb-button")
 			.should("have.prop", "accessibilityAttributes")
 			.should("deep.include", { expanded: "true", controls: "btn", hasPopup: "dialog" });
-		 });
+	});
 
 	it("Should not recalculate overflow when button state changes without affecting width", () => {
 		cy.mount(
@@ -589,4 +589,78 @@ describe("ToolbarButton", () => {
 			});
 		});
 	});
+
+	it("Should display text only in overflow when showOverflowText is true", () => {
+		cy.mount(
+			<Toolbar>
+				<ToolbarButton
+					icon={add}
+					text="Add Document"
+					showOverflowText={true}
+				></ToolbarButton>
+
+				<ToolbarButton
+					icon={employee}
+					text="Employee"
+					showOverflowText={false}
+				></ToolbarButton>
+
+				<ToolbarButton
+					icon={decline}
+					text="Decline Item"
+				></ToolbarButton>
+			</Toolbar>
+		);
+
+		cy.viewport(800, 600);
+
+		cy.get("[ui5-toolbar-button][text='Add Document']")
+			.should("have.prop", "isOverflowed", false)
+			.shadow()
+			.find("[ui5-button]")
+			.should("not.contain.text", "Add Document");
+
+		cy.get("[ui5-toolbar-button][text='Employee']")
+			.should("have.prop", "isOverflowed", false)
+			.shadow()
+			.find("[ui5-button]")
+			.should("contain.text", "Employee");
+
+		cy.get("[ui5-toolbar-button][text='Decline Item']")
+			.should("have.prop", "isOverflowed", false)
+			.shadow()
+			.find("[ui5-button]")
+			.should("contain.text", "Decline Item");
+
+		cy.viewport(100, 600);
+
+		cy.get("[ui5-toolbar]")
+			.shadow()
+			.find(".ui5-tb-overflow-btn")
+			.should("not.have.class", "ui5-tb-overflow-btn-hidden")
+			.realClick();
+
+		cy.get("[ui5-toolbar]")
+			.shadow()
+			.find(".ui5-overflow-popover")
+			.should("have.attr", "open", "open");
+
+		cy.get("[ui5-toolbar-button][text='Add Document']")
+			.should("have.prop", "isOverflowed", true)
+			.shadow()
+			.find("[ui5-button]")
+			.should("contain.text", "Add Document");
+
+		cy.get("[ui5-toolbar-button][text='Employee']")
+			.should("have.prop", "isOverflowed", true)
+			.shadow()
+			.find("[ui5-button]")
+			.should("contain.text", "Employee");
+
+		cy.get("[ui5-toolbar-button][text='Decline Item']")
+			.should("have.prop", "isOverflowed", true)
+			.shadow()
+			.find("[ui5-button]")
+			.should("contain.text", "Decline Item");
+	});
 });

packages/main/src/ToolbarButton.ts

@@ -145,6 +145,20 @@ class ToolbarButton extends ToolbarItem {
 	@property()
 	text?: string;
 
+	/**
+	 * Defines whether the button text should only be displayed in the overflow popover.
+	 *
+	 * When set to `true`, the button appears as icon-only in the main toolbar,
+	 * but shows both icon and text when moved to the overflow popover.
+	 *
+	 * **Note:** This property only takes effect when the `text` property is also set.
+	 *
+	 * @default false
+	 * @public
+	 */
+	@property({ type: Boolean })
+	showOverflowText = false;
+
 	/**
 	 * Defines the width of the button.
 	 *
@@ -162,6 +176,23 @@ class ToolbarButton extends ToolbarItem {
 		};
 	}
 
+	/**
+	 * Returns the effective text to display based on overflow state and showOverflowText property.
+	 *
+	 * When showOverflowText is true:
+	 * - Normal state: returns empty string (icon-only)
+	 * - Overflow state: returns text
+	 *
+	 * When showOverflowText is false:
+	 * - Returns text in both states (normal behavior)
+	 */
+	get effectiveText(): string | undefined {
+		if (this.showOverflowText) {
+			return this.isOverflowed ? this.text : "";
+		}
+		return this.text;
+	}
+
 	onClick(e: Event) {
 		e.stopImmediatePropagation();
 		const prevented = !this.fireDecoratorEvent("click", { targetRef: e.target as HTMLElement });

packages/main/src/ToolbarButtonTemplate.tsx

@@ -22,7 +22,7 @@ export default function ToolbarButtonTemplate(this: ToolbarButton) {
 			data-ui5-stable={this.stableDomRef}
 			onClick={(...args) => this.onClick(...args)}
 		>
-			{this.text}
+			{this.effectiveText}
 		</Button>
 	);
 }

packages/main/test/pages/Toolbar.html

@@ -316,6 +316,31 @@
 			</div>
 		</section>
 
+		<br /><br />
+		<ui5-title level="H3">Toolbar with showOverflowText property</ui5-title>
+		<ui5-label>Resize the viewport to see the overflow behavior. Buttons with showOverflowText show icon-only in the toolbar but display text when overflowed.</ui5-label>
+		<br /><br />
+		<section>
+			<ui5-toolbar id="otb_overflow_text_only">
+				<ui5-toolbar-button icon="save" text="Save" show-overflow-text tooltip="Save Document"></ui5-toolbar-button>
+				<ui5-toolbar-button icon="edit" text="Edit" show-overflow-text tooltip="Edit Document"></ui5-toolbar-button>
+				<ui5-toolbar-button icon="copy" text="Copy" show-overflow-text tooltip="Copy Document"></ui5-toolbar-button>
+
+				<ui5-toolbar-separator></ui5-toolbar-separator>
+
+				<ui5-toolbar-button icon="add" text="Add New Item"></ui5-toolbar-button>
+				<ui5-toolbar-button icon="decline" text="Delete Item"></ui5-toolbar-button>
+
+				<ui5-toolbar-spacer></ui5-toolbar-spacer>
+
+				<ui5-toolbar-button icon="download" text="Download" show-overflow-text tooltip="Download File"></ui5-toolbar-button>
+				<ui5-toolbar-button icon="share" text="Share" show-overflow-text tooltip="Share Document"></ui5-toolbar-button>
+				<ui5-toolbar-button icon="refresh" text="Refresh" show-overflow-text tooltip="Refresh Page"></ui5-toolbar-button>
+			</ui5-toolbar>
+		</section>
+
+		<br /><br />
+
 		<section id="testEventpreventClosing">
 			<div style="width: 250px;">
 				<ui5-toolbar id="testEventpreventClosing-toolbar">