feat(badge): add support for hint feature (#30213)

Issue number: internal

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Added new position prop.
- Based on the prop, a new badge-position css class is added on the
host.
- Removed css rule that prevented the badge to be rendered when empty.
- Added common and themes styles to support the position prop and new
scale size (on ios/md defaults to min-width variable, as size is not yet
supported on native themes).
- Added new tests specific for this new feature and added new
screenshots.
- Support to properly work inside Avatar, Button and TabButton will be
added on different tasks (in the meantime the snapshots will appear
wrong for these use-cases)

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

- [Ionic Theme
Sample](https://ionic-framework-6n0cn175k-ionic1.vercel.app/src/components/badge/test/hint?ionic:theme=ionic)
- [MD Theme
Sample](https://ionic-framework-6n0cn175k-ionic1.vercel.app/src/components/badge/test/hint?ionic:theme=md)
- [iOS Theme
Sample](https://ionic-framework-6n0cn175k-ionic1.vercel.app/src/components/badge/test/hint?ionic:theme=ios)

---------

Co-authored-by: ionitron <[email protected]>
Co-authored-by: Marta Carlos <[email protected]>
Co-authored-by: Brandy Smith <[email protected]>

Author: 4 people

core/api.txt

@@ -317,6 +317,7 @@ ion-badge,prop,mode,"ios" | "md",undefined,false,false
 ion-badge,prop,shape,"round | rectangular" | "soft" | undefined,undefined,false,false
 ion-badge,prop,size,"large" | "medium" | "small" | "xlarge" | "xsmall" | "xxsmall" | undefined,undefined,false,false
 ion-badge,prop,theme,"ios" | "md" | "ionic",undefined,false,false
+ion-badge,prop,vertical,"bottom" | "top" | undefined,undefined,false,false
 ion-badge,css-prop,--background,ionic
 ion-badge,css-prop,--background,ios
 ion-badge,css-prop,--background,md

core/src/components.d.ts

@@ -441,6 +441,10 @@ export namespace Components {
           * The theme determines the visual appearance of the component.
          */
         "theme"?: "ios" | "md" | "ionic";
+        /**
+          * Set to `"top"` to position the badge on top right absolute position of the parent element. Set to `"bottom"` to position the badge on bottom right absolute position of the parent element.
+         */
+        "vertical"?: 'top' | 'bottom';
     }
     interface IonBreadcrumb {
         /**
@@ -5805,6 +5809,10 @@ declare namespace LocalJSX {
           * The theme determines the visual appearance of the component.
          */
         "theme"?: "ios" | "md" | "ionic";
+        /**
+          * Set to `"top"` to position the badge on top right absolute position of the parent element. Set to `"bottom"` to position the badge on bottom right absolute position of the parent element.
+         */
+        "vertical"?: 'top' | 'bottom';
     }
     interface IonBreadcrumb {
         /**

core/src/components/avatar/avatar.common.scss

@@ -10,6 +10,8 @@
   @include border-radius(var(--border-radius));
 
   display: block;
+
+  position: relative;
 }
 
 ::slotted(ion-img),

core/src/components/avatar/avatar.ionic.scss

@@ -152,3 +152,22 @@
   width: globals.$ion-scale-1000;
   height: globals.$ion-scale-1000;
 }
+
+// Avatar Empty Badge (hint)
+// --------------------------------------------------
+
+:host(.avatar-xxsmall) ::slotted(ion-badge.badge-vertical-top:empty) {
+  transform: translate(globals.$ion-scale-100, calc(globals.$ion-scale-100 * -1));
+}
+
+:host(:not(.avatar-xxsmall)) ::slotted(ion-badge.badge-vertical-top:empty) {
+  transform: translate(globals.$ion-scale-050, calc(globals.$ion-scale-050 * -1));
+}
+
+:host(.avatar-xxsmall) ::slotted(ion-badge.badge-vertical-bottom:empty) {
+  transform: translate(globals.$ion-scale-100, calc(globals.$ion-scale-100));
+}
+
+:host(:not(.avatar-xxsmall)) ::slotted(ion-badge.badge-vertical-bottom:empty) {
+  transform: translate(0, globals.$ion-scale-100);
+}

core/src/components/avatar/avatar.md.scss

@@ -10,3 +10,14 @@
   width: $avatar-md-width;
   height: $avatar-md-height;
 }
+
+// Avatar Empty Badge (hint)
+// --------------------------------------------------
+
+::slotted(ion-badge.badge-vertical-top:empty) {
+  transform: translate(-50%, 50%);
+}
+
+::slotted(ion-badge.badge-vertical-bottom:empty) {
+  transform: translateX(-100%);
+}

core/src/components/badge/badge.common.scss

@@ -48,6 +48,18 @@
   color: #{color.current-color(contrast)};
 }
 
-:host(:empty) {
-  display: none;
+// Badge Empty (hint)
+// --------------------------------------------------
+
+:host([vertical]) {
+  @include position(null, 0, null, null);
+  position: absolute;
+}
+
+:host(:empty.badge-vertical-top) {
+  top: 0;
+}
+
+:host(:empty.badge-vertical-bottom) {
+  bottom: 0;
 }

core/src/components/badge/badge.ionic.scss

@@ -145,3 +145,32 @@
   width: globals.$ion-scale-1000;
   height: globals.$ion-scale-1000;
 }
+
+// Badge Empty
+// --------------------------------------------------
+
+:host(:empty) {
+  --padding-start: 0;
+  --padding-end: 0;
+}
+
+// Badge Sizes Empty
+// --------------------------------------------------
+
+/* sm */
+:host(.badge-small:empty) {
+  min-width: globals.$ion-scale-200;
+  height: globals.$ion-scale-200;
+}
+
+/* md */
+:host(.badge-medium:empty) {
+  min-width: globals.$ion-scale-300;
+  height: globals.$ion-scale-300;
+}
+
+/* lg */
+:host(.badge-large:empty) {
+  min-width: globals.$ion-scale-400;
+  height: globals.$ion-scale-400;
+}

core/src/components/badge/badge.native.scss

@@ -11,3 +11,16 @@
 
   font-family: $font-family-base;
 }
+
+// TODO(ROU-10747): Review size styles when sizes are defined for native themes.
+:host(:empty) {
+  --padding-start: 0;
+  --padding-end: 0;
+  --padding-bottom: 0;
+  --padding-top: 0;
+
+  @include border-radius(999px);
+
+  width: $badge-min-width;
+  height: $badge-min-width;
+}

core/src/components/badge/badge.tsx

@@ -47,6 +47,12 @@ export class Badge implements ComponentInterface {
    */
   @Prop() size?: 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
 
+  /**
+   * Set to `"top"` to position the badge on top right absolute position of the parent element.
+   * Set to `"bottom"` to position the badge on bottom right absolute position of the parent element.
+   */
+  @Prop() vertical?: 'top' | 'bottom';
+
   private getShape(): string | undefined {
     const theme = getIonTheme(this);
     const { shape } = this;
@@ -89,6 +95,7 @@ export class Badge implements ComponentInterface {
           [theme]: true,
           [`badge-${shape}`]: shape !== undefined,
           [`badge-${size}`]: size !== undefined,
+          [`badge-vertical-${this.vertical}`]: this.vertical !== undefined,
         })}
       >
         <slot></slot>

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

@@ -0,0 +1,24 @@
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+configs({ directions: ['ltr'], modes: ['md', 'ios', 'ionic-md'] }).forEach(({ config, screenshot, title }) => {
+  test.describe(title('badge: hint empty'), () => {
+    test('should not have visual regressions', async ({ page }) => {
+      await page.goto('/src/components/badge/test/hint', config);
+
+      const container = page.locator('#empty');
+
+      await expect(container).toHaveScreenshot(screenshot(`badge-hint-empty`));
+    });
+  });
+
+  test.describe(title('badge: hint inside avatar'), () => {
+    test('should not have visual regressions', async ({ page }) => {
+      await page.goto('/src/components/badge/test/hint', config);
+
+      const container = page.locator('#avatar');
+
+      await expect(container).toHaveScreenshot(screenshot(`badge-hint-avatar`));
+    });
+  });
+});