feat(badge): add hue property for the ionic theme (#30307)

Issue number: internal

---------

## What is the current behavior?
The badge component does not support the `hue` property.

## What is the new behavior?
Adds support for the `subtle` hue for the badge. Defaults to `subtle`
when the badge contains icon or text. Defaults to `bold` when the badge
is empty or when it is inside of a button or tab button.

## Does this introduce a breaking change?
- [ ] Yes
- [x] No

core/api.txt

@@ -314,6 +314,7 @@ ion-backdrop,event,ionBackdropTap,void,true
 
 ion-badge,shadow
 ion-badge,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
+ion-badge,prop,hue,"bold" | "subtle" | undefined,undefined,false,false
 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

core/src/components.d.ts

@@ -429,6 +429,10 @@ export namespace Components {
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
         "color"?: Color;
+        /**
+          * Set to `"bold"` for a badge with vibrant, bold colors or to `"subtle"` for a badge with muted, subtle colors.  Only applies to the `ionic` theme.
+         */
+        "hue"?: 'bold' | 'subtle';
         /**
           * The mode determines the platform behaviors of the component.
          */
@@ -5870,6 +5874,10 @@ declare namespace LocalJSX {
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
         "color"?: Color;
+        /**
+          * Set to `"bold"` for a badge with vibrant, bold colors or to `"subtle"` for a badge with muted, subtle colors.  Only applies to the `ionic` theme.
+         */
+        "hue"?: 'bold' | 'subtle';
         /**
           * The mode determines the platform behaviors of the component.
          */

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

@@ -43,11 +43,6 @@
   vertical-align: baseline;
 }
 
-:host(.ion-color) {
-  background: #{color.current-color(base)};
-  color: #{color.current-color(contrast)};
-}
-
 // Badge (hint)
 // --------------------------------------------------
 

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

@@ -5,8 +5,6 @@
 // --------------------------------------------------
 
 :host {
-  --background: #{globals.ion-color(primary, base)};
-  --color: #{globals.ion-color(primary, contrast)};
   --padding-start: #{globals.$ion-space-200};
   --padding-end: #{globals.$ion-space-200};
   --padding-top: #{globals.$ion-space-0};
@@ -20,6 +18,32 @@
   font-weight: globals.$ion-font-weight-medium;
 }
 
+// Bold Badge
+// --------------------------------------------------
+
+:host(.badge-bold) {
+  --background: #{globals.ion-color(primary, base)};
+  --color: #{globals.ion-color(primary, contrast)};
+}
+
+:host(.badge-bold.ion-color) {
+  background: globals.current-color(base);
+  color: globals.current-color(contrast);
+}
+
+// Subtle Badge
+// --------------------------------------------------
+
+:host(.badge-subtle) {
+  --background: #{globals.ion-color(primary, base, $subtle: true)};
+  --color: #{globals.ion-color(primary, contrast, $subtle: true)};
+}
+
+:host(.badge-subtle.ion-color) {
+  background: globals.current-color(base, $subtle: true);
+  color: globals.current-color(contrast, $subtle: true);
+}
+
 // Badge Shapes
 // --------------------------------------------------
 

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

@@ -12,6 +12,11 @@
   font-family: $font-family-base;
 }
 
+:host(.ion-color) {
+  background: current-color(base);
+  color: current-color(contrast);
+}
+
 // TODO(ROU-10747): Review size styles when sizes are defined for native themes.
 :host([vertical]:not(.in-button):not(.in-tab-button)),
 :host(:empty) {

core/src/components/badge/badge.tsx

@@ -28,6 +28,14 @@ export class Badge implements ComponentInterface {
    */
   @Prop({ reflect: true }) color?: Color;
 
+  /**
+   * Set to `"bold"` for a badge with vibrant, bold colors or to `"subtle"` for
+   * a badge with muted, subtle colors.
+   *
+   * Only applies to the `ionic` theme.
+   */
+  @Prop() hue?: 'bold' | 'subtle';
+
   /**
    * Set to `"rectangular"` for non-rounded corners.
    * Set to `"soft"` for slightly rounded corners.
@@ -87,7 +95,33 @@ export class Badge implements ComponentInterface {
     return size;
   }
 
+  // The 'subtle' hue is the default for badges containing text or icons
+  // The 'bold' hue is used when inside of an avatar, button, tab button,
+  // or when the badge is empty (no text or icon).
+  private getHue(): string | undefined {
+    const { hue } = this;
+
+    if (hue !== undefined) {
+      return hue;
+    }
+
+    const inAvatar = hostContext('ion-avatar', this.el);
+    const inButton = hostContext('ion-button', this.el);
+    const inTabButton = hostContext('ion-tab-button', this.el);
+    const hasContent = this.el.textContent?.trim() !== '' || this.el.querySelector('ion-icon') !== null;
+
+    // Return 'bold' if the badge is inside an avatar, button, tab button,
+    // or has no content
+    if (inAvatar || inButton || inTabButton || !hasContent) {
+      return 'bold';
+    }
+
+    // Return 'subtle' if the badge contains visible text or an icon
+    return 'subtle';
+  }
+
   render() {
+    const hue = this.getHue();
     const shape = this.getShape();
     const size = this.getSize();
     const theme = getIonTheme(this);
@@ -96,6 +130,7 @@ export class Badge implements ComponentInterface {
       <Host
         class={createColorClasses(this.color, {
           [theme]: true,
+          [`badge-${hue}`]: hue !== undefined,
           [`badge-${shape}`]: shape !== undefined,
           [`badge-${size}`]: size !== undefined,
           [`badge-vertical-${this.vertical}`]: this.vertical !== undefined,

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

@@ -0,0 +1,80 @@
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+configs({ directions: ['ltr'], modes: ['ionic-md'] }).forEach(({ config, screenshot, title }) => {
+  test.describe(title('badge: hue'), () => {
+    test('should render subtle badges', async ({ page }) => {
+      await page.setContent(
+        `
+        <div id="container">
+          <ion-badge>99</ion-badge>
+          <ion-badge color="primary">99</ion-badge>
+          <ion-badge color="secondary">99</ion-badge>
+          <ion-badge color="tertiary">99</ion-badge>
+          <ion-badge color="success">99</ion-badge>
+          <ion-badge color="warning">99</ion-badge>
+          <ion-badge color="danger">99</ion-badge>
+          <ion-badge color="light">99</ion-badge>
+          <ion-badge color="medium">99</ion-badge>
+          <ion-badge color="dark">99</ion-badge>
+
+          <br>
+
+          <ion-badge><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="primary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="secondary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="tertiary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="success"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="warning"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="danger"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="light"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="medium"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge color="dark"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        </div>
+      `,
+        config
+      );
+
+      const container = page.locator('#container');
+
+      await expect(container).toHaveScreenshot(screenshot(`badge-hue-subtle`));
+    });
+
+    test('should render bold badges', async ({ page }) => {
+      await page.setContent(
+        `
+        <div id="container">
+          <ion-badge hue="bold">99</ion-badge>
+          <ion-badge hue="bold" color="primary">99</ion-badge>
+          <ion-badge hue="bold" color="secondary">99</ion-badge>
+          <ion-badge hue="bold" color="tertiary">99</ion-badge>
+          <ion-badge hue="bold" color="success">99</ion-badge>
+          <ion-badge hue="bold" color="warning">99</ion-badge>
+          <ion-badge hue="bold" color="danger">99</ion-badge>
+          <ion-badge hue="bold" color="light">99</ion-badge>
+          <ion-badge hue="bold" color="medium">99</ion-badge>
+          <ion-badge hue="bold" color="dark">99</ion-badge>
+
+          <br>
+
+          <ion-badge hue="bold"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="primary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="secondary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="tertiary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="success"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="warning"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="danger"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="light"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="medium"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+          <ion-badge hue="bold" color="dark"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        </div>
+      `,
+        config
+      );
+
+      const container = page.locator('#container');
+
+      await expect(container).toHaveScreenshot(screenshot(`badge-hue-bold`));
+    });
+  });
+});

core/src/components/badge/test/hue/index.html

@@ -0,0 +1,78 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Badge - Hue</title>
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <link href="../../../../../css/ionic.bundle.css" rel="stylesheet" />
+    <link href="../../../../../scripts/testing/styles.css" rel="stylesheet" />
+    <script src="../../../../../scripts/testing/scripts.js"></script>
+    <script nomodule src="../../../../../dist/ionic/ionic.js"></script>
+    <script type="module" src="../../../../../dist/ionic/ionic.esm.js"></script>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-header>
+        <ion-toolbar>
+          <ion-title>Badge - Hue</ion-title>
+        </ion-toolbar>
+      </ion-header>
+
+      <ion-content id="content">
+        <h2>Badge Hue: Subtle</h2>
+        <ion-badge>99</ion-badge>
+        <ion-badge color="primary">99</ion-badge>
+        <ion-badge color="secondary">99</ion-badge>
+        <ion-badge color="tertiary">99</ion-badge>
+        <ion-badge color="success">99</ion-badge>
+        <ion-badge color="warning">99</ion-badge>
+        <ion-badge color="danger">99</ion-badge>
+        <ion-badge color="light">99</ion-badge>
+        <ion-badge color="medium">99</ion-badge>
+        <ion-badge color="dark">99</ion-badge>
+
+        <br />
+
+        <ion-badge><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="primary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="secondary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="tertiary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="success"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="warning"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="danger"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="light"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="medium"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge color="dark"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+
+        <h2>Badge Hue: Bold</h2>
+        <ion-badge hue="bold">99</ion-badge>
+        <ion-badge hue="bold" color="primary">99</ion-badge>
+        <ion-badge hue="bold" color="secondary">99</ion-badge>
+        <ion-badge hue="bold" color="tertiary">99</ion-badge>
+        <ion-badge hue="bold" color="success">99</ion-badge>
+        <ion-badge hue="bold" color="warning">99</ion-badge>
+        <ion-badge hue="bold" color="danger">99</ion-badge>
+        <ion-badge hue="bold" color="light">99</ion-badge>
+        <ion-badge hue="bold" color="medium">99</ion-badge>
+        <ion-badge hue="bold" color="dark">99</ion-badge>
+
+        <br />
+
+        <ion-badge hue="bold"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="primary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="secondary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="tertiary"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="success"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="warning"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="danger"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="light"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="medium"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+        <ion-badge hue="bold" color="dark"><ion-icon name="logo-ionic"></ion-icon></ion-badge>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>