feat(button): improve badge spacing and stacking

BREAKING.md

@@ -62,11 +62,12 @@ The following breaking changes apply to `ion-button`:
 5. Icon-only buttons are now squares as tall as a text button of the same size. In `md`, this makes them a few pixels smaller at the small and default sizes and larger at the large size. To change their size, set the size's `min.height` as described above.
 6. The `md` button follows Material Design 2 for its spacing, outline, elevation and disabled state. <sup>[6](#version-10x-button-md-material-design-2)</sup>
 7. The `ios` button follows iOS 17 for its font, icons and disabled state. <sup>[7](#version-10x-button-ios-17)</sup>
-8. CSS variables have been replaced. <sup>[8](#version-10x-button-replaced-css-variables)</sup>
-9. `--padding-*` CSS variables are no longer part of the documented public API (but remain functional). <sup>[9](#version-10x-button-padding-variables)</sup>
-10. The fill, size, shape and expand classes have been renamed. <sup>[10](#version-10x-button-renamed-classes)</sup>
-11. The `default` size has been deprecated. <sup>[11](#version-10x-button-deprecated-default-size)</sup>
-12. Theme classes (`ion-button.md`, `ion-button.ios`) are no longer supported. <sup>[12](#version-10x-button-theme-classes)</sup>
+8. A badge without a `vertical` position now has a gap between it and the label, and no longer makes the button taller than its `min.height`. To remove the gap, set `IonButton.size.<size>.badge.margin.start` for global styles or `--ion-button-size-<size>-badge-margin-start` for component-specific styles to `0`.
+9. CSS variables have been replaced. <sup>[9](#version-10x-button-replaced-css-variables)</sup>
+10. `--padding-*` CSS variables are no longer part of the documented public API (but remain functional). <sup>[10](#version-10x-button-padding-variables)</sup>
+11. The fill, size, shape and expand classes have been renamed. <sup>[11](#version-10x-button-renamed-classes)</sup>
+12. The `default` size has been deprecated. <sup>[12](#version-10x-button-deprecated-default-size)</sup>
+13. Theme classes (`ion-button.md`, `ion-button.ios`) are no longer supported. <sup>[13](#version-10x-button-theme-classes)</sup>
 
 <h5 id="version-10x-button-md-material-design-2">Material Design 2 in <code>md</code></h5>
 

core/api.txt

@@ -580,6 +580,10 @@ ion-button,css-prop,--ion-button-shape-crisp-border-radius
 ion-button,css-prop,--ion-button-shape-rectangular-border-radius
 ion-button,css-prop,--ion-button-shape-round-border-radius
 ion-button,css-prop,--ion-button-shape-soft-border-radius
+ion-button,css-prop,--ion-button-size-large-badge-margin-bottom
+ion-button,css-prop,--ion-button-size-large-badge-margin-end
+ion-button,css-prop,--ion-button-size-large-badge-margin-start
+ion-button,css-prop,--ion-button-size-large-badge-margin-top
 ion-button,css-prop,--ion-button-size-large-font-size
 ion-button,css-prop,--ion-button-size-large-icon-font-size
 ion-button,css-prop,--ion-button-size-large-icon-leading-margin-bottom
@@ -619,6 +623,10 @@ ion-button,css-prop,--ion-button-size-large-spinner-trailing-margin-bottom
 ion-button,css-prop,--ion-button-size-large-spinner-trailing-margin-end
 ion-button,css-prop,--ion-button-size-large-spinner-trailing-margin-start
 ion-button,css-prop,--ion-button-size-large-spinner-trailing-margin-top
+ion-button,css-prop,--ion-button-size-medium-badge-margin-bottom
+ion-button,css-prop,--ion-button-size-medium-badge-margin-end
+ion-button,css-prop,--ion-button-size-medium-badge-margin-start
+ion-button,css-prop,--ion-button-size-medium-badge-margin-top
 ion-button,css-prop,--ion-button-size-medium-font-size
 ion-button,css-prop,--ion-button-size-medium-icon-font-size
 ion-button,css-prop,--ion-button-size-medium-icon-leading-margin-bottom
@@ -658,6 +666,10 @@ ion-button,css-prop,--ion-button-size-medium-spinner-trailing-margin-bottom
 ion-button,css-prop,--ion-button-size-medium-spinner-trailing-margin-end
 ion-button,css-prop,--ion-button-size-medium-spinner-trailing-margin-start
 ion-button,css-prop,--ion-button-size-medium-spinner-trailing-margin-top
+ion-button,css-prop,--ion-button-size-small-badge-margin-bottom
+ion-button,css-prop,--ion-button-size-small-badge-margin-end
+ion-button,css-prop,--ion-button-size-small-badge-margin-start
+ion-button,css-prop,--ion-button-size-small-badge-margin-top
 ion-button,css-prop,--ion-button-size-small-font-size
 ion-button,css-prop,--ion-button-size-small-icon-font-size
 ion-button,css-prop,--ion-button-size-small-icon-leading-margin-bottom

core/src/components/button/_button.docs.scss

@@ -52,6 +52,10 @@
  * @prop --ion-button-size-small-spinner-trailing-margin-end: Right margin if direction is left-to-right, and left margin if direction is right-to-left of a spinner in the `end` slot of the `small` button size
  * @prop --ion-button-size-small-spinner-trailing-margin-bottom: Bottom margin of a spinner in the `end` slot of the `small` button size
  * @prop --ion-button-size-small-spinner-trailing-margin-start: Left margin if direction is left-to-right, and right margin if direction is right-to-left of a spinner in the `end` slot of the `small` button size
+ * @prop --ion-button-size-small-badge-margin-top: Top margin of a badge without a `vertical` position in a text button of the `small` size, added to the negative margin that cancels the button's top padding
+ * @prop --ion-button-size-small-badge-margin-end: Margin on the side away from the label of a badge without a `vertical` position in a text button of the `small` size
+ * @prop --ion-button-size-small-badge-margin-bottom: Bottom margin of a badge without a `vertical` position in a text button of the `small` size, added to the negative margin that cancels the button's bottom padding
+ * @prop --ion-button-size-small-badge-margin-start: Gap between the label and a badge without a `vertical` position in a text button of the `small` size
  * @prop --ion-button-size-medium-min-width: Minimum width of the `medium` button size
  * @prop --ion-button-size-medium-min-height: Minimum height of the `medium` button size, and the width and height of an icon-only button of that size
  * @prop --ion-button-size-medium-font-size: Font size of the `medium` button size
@@ -91,6 +95,10 @@
  * @prop --ion-button-size-medium-spinner-trailing-margin-end: Right margin if direction is left-to-right, and left margin if direction is right-to-left of a spinner in the `end` slot of the `medium` button size
  * @prop --ion-button-size-medium-spinner-trailing-margin-bottom: Bottom margin of a spinner in the `end` slot of the `medium` button size
  * @prop --ion-button-size-medium-spinner-trailing-margin-start: Left margin if direction is left-to-right, and right margin if direction is right-to-left of a spinner in the `end` slot of the `medium` button size
+ * @prop --ion-button-size-medium-badge-margin-top: Top margin of a badge without a `vertical` position in a text button of the `medium` size, added to the negative margin that cancels the button's top padding
+ * @prop --ion-button-size-medium-badge-margin-end: Margin on the side away from the label of a badge without a `vertical` position in a text button of the `medium` size
+ * @prop --ion-button-size-medium-badge-margin-bottom: Bottom margin of a badge without a `vertical` position in a text button of the `medium` size, added to the negative margin that cancels the button's bottom padding
+ * @prop --ion-button-size-medium-badge-margin-start: Gap between the label and a badge without a `vertical` position in a text button of the `medium` size
  * @prop --ion-button-size-large-min-width: Minimum width of the `large` button size
  * @prop --ion-button-size-large-min-height: Minimum height of the `large` button size, and the width and height of an icon-only button of that size
  * @prop --ion-button-size-large-font-size: Font size of the `large` button size
@@ -130,6 +138,10 @@
  * @prop --ion-button-size-large-spinner-trailing-margin-end: Right margin if direction is left-to-right, and left margin if direction is right-to-left of a spinner in the `end` slot of the `large` button size
  * @prop --ion-button-size-large-spinner-trailing-margin-bottom: Bottom margin of a spinner in the `end` slot of the `large` button size
  * @prop --ion-button-size-large-spinner-trailing-margin-start: Left margin if direction is left-to-right, and right margin if direction is right-to-left of a spinner in the `end` slot of the `large` button size
+ * @prop --ion-button-size-large-badge-margin-top: Top margin of a badge without a `vertical` position in a text button of the `large` size, added to the negative margin that cancels the button's top padding
+ * @prop --ion-button-size-large-badge-margin-end: Margin on the side away from the label of a badge without a `vertical` position in a text button of the `large` size
+ * @prop --ion-button-size-large-badge-margin-bottom: Bottom margin of a badge without a `vertical` position in a text button of the `large` size, added to the negative margin that cancels the button's bottom padding
+ * @prop --ion-button-size-large-badge-margin-start: Gap between the label and a badge without a `vertical` position in a text button of the `large` size
  * @prop --ion-button-shape-crisp-border-radius: Border radius of the `crisp` button shape
  * @prop --ion-button-shape-soft-border-radius: Border radius of the `soft` button shape
  * @prop --ion-button-shape-round-border-radius: Border radius of the `round` button shape

core/src/components/button/button.interface.ts

@@ -238,6 +238,16 @@ type IonButtonSizeDefinition = {
   icon?: IonButtonIconDefinition;
   iconOnly?: IonButtonIconOnlyDefinition;
   spinner?: IonButtonSpinnerDefinition;
+
+  /** A badge without a `vertical` position, next to the label of a text button */
+  badge?: {
+    /**
+     * `start` is the gap on the label's side and `end` is the margin on the
+     * other side. `top` and `bottom` add to the negative margins that cancel
+     * the button's vertical padding.
+     */
+    margin?: IonMargin;
+  };
 };
 
 type IonButtonShapeDefinition = {

core/src/components/button/button.scss

@@ -473,6 +473,42 @@ $spinner-sizes: xsmall, small, medium, large, xlarge;
 // Button: With a Badge
 // --------------------------------------------------
 
+// A badge can overflow its button, so the button sits above its siblings to keep the badge visible
+:host(.button-has-badge) {
+  position: relative;
+
+  z-index: 1;
+}
+
 :host(.button-has-badge) .button-native {
   overflow: visible;
 }
+
+@each $size in $sizes {
+  // The badge overlaps the vertical padding, so a badge taller than the label doesn't make the button taller than its min height.
+  // The block margins fall back to 0px because no theme sets them, and calc() needs a unit.
+  :host(.button-size-#{$size}:not(.button-has-icon-only)) ::slotted(ion-badge:not([vertical])) {
+    @include mixins.margin(
+      calc(
+        var(--ion-button-size-#{$size}-badge-margin-top, 0px) -
+          var(--padding-top, var(--ion-button-size-#{$size}-padding-top, 0px))
+      ),
+      var(--ion-button-size-#{$size}-badge-margin-end),
+      calc(
+        var(--ion-button-size-#{$size}-badge-margin-bottom, 0px) -
+          var(--padding-bottom, var(--ion-button-size-#{$size}-padding-bottom, 0px))
+      ),
+      var(--ion-button-size-#{$size}-badge-margin-start)
+    );
+  }
+
+  // A badge before the label keeps the gap on the label's side
+  :host(.button-size-#{$size}:not(.button-has-icon-only)) ::slotted(ion-badge[slot="start"]:not([vertical])) {
+    @include mixins.margin(
+      null,
+      var(--ion-button-size-#{$size}-badge-margin-start),
+      null,
+      var(--ion-button-size-#{$size}-badge-margin-end)
+    );
+  }
+}

core/src/components/button/test/badge/button.e2e.ts

@@ -83,5 +83,93 @@ configs({ modes: ['md', 'ios', 'ionic-md'] }).forEach(({ config, screenshot, tit
 
       await expect(container).toHaveScreenshot(screenshot(`button-badge`));
     });
+
+    test('should space a badge without a position from the label', async ({ page }) => {
+      const rows = ION_BUTTON_SIZES.map(
+        (buttonSize) => `<div class="row">${contents
+          .flatMap((html) =>
+            ION_BADGE_SIZES.map(
+              (badgeSize) => `<ion-button size="${buttonSize}" shape="round">
+                Button
+                <ion-badge hue="bold" shape="round" color="danger" size="${badgeSize}">${html}</ion-badge>
+              </ion-button>`
+            )
+          )
+          .join('\n')}
+        </div>`
+      ).join('\n');
+
+      await page.setContent(
+        `
+          <style>
+            .row {
+              display: grid;
+              grid-template-columns: repeat(3, auto);
+              justify-items: start;
+              align-items: center;
+              padding-bottom: 10px;
+              row-gap: 5px;
+              column-gap: 30px;
+            }
+
+            .badge-container {
+              width: max-content;
+            }
+          </style>
+
+          <div class="badge-container">
+            ${rows}
+          </div>
+        `,
+        config
+      );
+
+      const container = page.locator('.badge-container');
+
+      // Content wider than the viewport is cut off at the left edge in rtl
+      const box = await container.boundingBox();
+      await page.setViewportSize({ width: Math.ceil(box!.width), height: Math.ceil(box!.height) });
+
+      await expect(container).toHaveScreenshot(screenshot(`button-badge-no-position`));
+    });
+  });
+});
+
+/**
+ * Stacking does not vary across modes or directions
+ */
+configs({ modes: ['md'], directions: ['ltr'] }).forEach(({ title, config }) => {
+  test.describe(title('button: badge stacking'), () => {
+    test('should keep a badge above the next button', async ({ page }) => {
+      await page.setContent(
+        `
+        <div style="display: flex">
+          <ion-button id="with-badge">
+            Button
+            <ion-badge vertical="top">999+</ion-badge>
+          </ion-button>
+          <ion-button id="next">Button</ion-button>
+        </div>
+      `,
+        config
+      );
+
+      const badgeBox = (await page.locator('#with-badge ion-badge').boundingBox())!;
+      const nextBox = (await page.locator('#next').boundingBox())!;
+
+      // The area where the badge overflows into the next button
+      const left = Math.max(badgeBox.x, nextBox.x);
+      const right = Math.min(badgeBox.x + badgeBox.width, nextBox.x + nextBox.width);
+      const top = Math.max(badgeBox.y, nextBox.y);
+      const bottom = Math.min(badgeBox.y + badgeBox.height, nextBox.y + nextBox.height);
+      expect(right).toBeGreaterThan(left);
+      expect(bottom).toBeGreaterThan(top);
+
+      const topmost = await page.evaluate(
+        ([x, y]) => document.elementFromPoint(x, y)?.closest('ion-badge, ion-button')?.tagName,
+        [(left + right) / 2, (top + bottom) / 2]
+      );
+      expect(topmost).toBe('ION-BADGE');
+    });
   });
 });

core/src/themes/ionic/default.tokens.ts

@@ -674,6 +674,13 @@ export const defaultTheme: DefaultTheme = {
               },
             },
           },
+
+          badge: {
+            margin: {
+              end: 'var(--ion-spacing-0)',
+              start: 'var(--ion-spacing-sm)',
+            },
+          },
         },
 
         medium: {
@@ -779,6 +786,13 @@ export const defaultTheme: DefaultTheme = {
               },
             },
           },
+
+          badge: {
+            margin: {
+              end: 'var(--ion-spacing-0)',
+              start: 'var(--ion-spacing-250)',
+            },
+          },
         },
 
         large: {
@@ -884,6 +898,13 @@ export const defaultTheme: DefaultTheme = {
               },
             },
           },
+
+          badge: {
+            margin: {
+              end: 'var(--ion-spacing-0)',
+              start: 'var(--ion-spacing-md)',
+            },
+          },
         },
       },
 

core/src/themes/ios/default.tokens.ts

@@ -585,18 +585,18 @@ export const defaultTheme: DefaultTheme = {
 
             leading: {
               margin: {
-                top: '0',
+                top: 'var(--ion-spacing-0)',
                 end: '0.2222em',
-                bottom: '0',
-                start: '0',
+                bottom: 'var(--ion-spacing-0)',
+                start: 'var(--ion-spacing-0)',
               },
             },
 
             trailing: {
               margin: {
-                top: '0',
-                end: '0',
-                bottom: '0',
+                top: 'var(--ion-spacing-0)',
+                end: 'var(--ion-spacing-0)',
+                bottom: 'var(--ion-spacing-0)',
                 start: '0.2222em',
               },
             },
@@ -650,6 +650,13 @@ export const defaultTheme: DefaultTheme = {
               },
             },
           },
+
+          badge: {
+            margin: {
+              end: 'var(--ion-spacing-0)',
+              start: 'var(--ion-spacing-xxs)',
+            },
+          },
         },
 
         medium: {
@@ -675,18 +682,18 @@ export const defaultTheme: DefaultTheme = {
 
             leading: {
               margin: {
-                top: '0',
+                top: 'var(--ion-spacing-0)',
                 end: '0.2222em',
-                bottom: '0',
-                start: '0',
+                bottom: 'var(--ion-spacing-0)',
+                start: 'var(--ion-spacing-0)',
               },
             },
 
             trailing: {
               margin: {
-                top: '0',
-                end: '0',
-                bottom: '0',
+                top: 'var(--ion-spacing-0)',
+                end: 'var(--ion-spacing-0)',
+                bottom: 'var(--ion-spacing-0)',
                 start: '0.2222em',
               },
             },
@@ -740,6 +747,13 @@ export const defaultTheme: DefaultTheme = {
               },
             },
           },
+
+          badge: {
+            margin: {
+              end: 'var(--ion-spacing-0)',
+              start: 'var(--ion-spacing-xxs)',
+            },
+          },
         },
 
         large: {
@@ -765,18 +779,18 @@ export const defaultTheme: DefaultTheme = {
 
             leading: {
               margin: {
-                top: '0',
+                top: 'var(--ion-spacing-0)',
                 end: '0.2222em',
-                bottom: '0',
-                start: '0',
+                bottom: 'var(--ion-spacing-0)',
+                start: 'var(--ion-spacing-0)',
               },
             },
 
             trailing: {
               margin: {
-                top: '0',
-                end: '0',
-                bottom: '0',
+                top: 'var(--ion-spacing-0)',
+                end: 'var(--ion-spacing-0)',
+                bottom: 'var(--ion-spacing-0)',
                 start: '0.2222em',
               },
             },
@@ -830,6 +844,13 @@ export const defaultTheme: DefaultTheme = {
               },
             },
           },
+
+          badge: {
+            margin: {
+              end: 'var(--ion-spacing-0)',
+              start: 'var(--ion-spacing-xxs)',
+            },
+          },
         },
       },