feat: S2 notification badge (#7930)

* initialize notification badge

* fix width in different locales

* fix lint

* update lock file

* fix story

* updates fromr review

* fix lint

* fix text color in light mode + forced colors

* fix VO, rename isEmpty to isIndicatorOnly

* remove extra space

* fix VO

* ensure value is integer

* update stories

* fix aria label

* small change

* update stories

Author: yihuiliao

packages/@react-spectrum/s2/intl/en-US.json

@@ -17,6 +17,8 @@
   "label.(required)": "(required)",
   "label.(optional)": "(optional)",
   "menu.moreActions": "More actions",
+  "notificationbadge.plus": "{notifications}+",
+  "notificationbadge.indicatorOnly": "New activity",
   "picker.placeholder": "Select…",
   "slider.minimum": "Minimum",
   "slider.maximum": "Maximum",

packages/@react-spectrum/s2/package.json

@@ -129,6 +129,7 @@
     "jest": "^29.5.0"
   },
   "dependencies": {
+    "@internationalized/number": "^3.6.0",
     "@react-aria/collections": "3.0.0-beta.1",
     "@react-aria/focus": "^3.20.1",
     "@react-aria/i18n": "^3.12.7",

packages/@react-spectrum/s2/src/ActionButton.tsx

@@ -19,6 +19,7 @@ import {createContext, forwardRef, ReactNode, useContext} from 'react';
 import {FocusableRef, FocusableRefValue} from '@react-types/shared';
 import {getAllowedOverrides, staticColor, StyleProps} from './style-utils' with { type: 'macro' };
 import {IconContext} from './Icon';
+import {NotificationBadgeContext} from './NotificationBadge';
 import {pressScale} from './pressScale';
 import {SkeletonContext} from './Skeleton';
 import {Text, TextContext} from './Content';
@@ -59,6 +60,7 @@ export interface ActionButtonProps extends Omit<ButtonProps, 'className' | 'styl
 
 // These styles handle both ActionButton and ToggleButton
 const iconOnly = ':has([slot=icon], [slot=avatar]):not(:has([data-rsp-slot=text]))';
+const textOnly = ':has([data-rsp-slot=text]):not(:has([slot=icon], [slot=avatar]))';
 export const btnStyles = style<ButtonRenderProps & ActionButtonStyleProps & ToggleButtonStyleProps & ActionGroupItemStyleProps & {isInGroup: boolean, isStaticColor: boolean}>({
   ...focusRing(),
   ...staticColor(),
@@ -216,7 +218,34 @@ export const btnStyles = style<ButtonRenderProps & ActionButtonStyleProps & Togg
   zIndex: {
     isFocusVisible: 2
   },
-  disableTapHighlight: true
+  disableTapHighlight: true,
+  '--badgeTop': {
+    type: 'top',
+    value: {
+      default: '[calc(self(height)/2 - var(--iconWidth)/2)]',
+      [iconOnly]: '[calc(self(height)/2 - var(--iconWidth)/2)]',
+      [textOnly]: 0
+    }
+  },
+  '--buttonPaddingX': {
+    type: 'paddingStart',
+    value: {
+      default: '[calc(self(height, self(minHeight)) * 3 / 8)]',
+      [iconOnly]: 0
+    }
+  },
+  '--iconWidth': {
+    type: 'width',
+    value: fontRelative(20)
+  },
+  '--badgePosition': {
+    type: 'width',
+    value: {
+      default: '[calc(var(--buttonPaddingX) + var(--iconWidth))]',
+      [iconOnly]: '[calc(self(minWidth)/2 + var(--iconWidth)/2)]',
+      [textOnly]: 'full'
+    }
+  }
 }, getAllowedOverrides());
 
 // Matching icon sizes. TBD.
@@ -232,7 +261,7 @@ export const ActionButtonContext = createContext<ContextValue<Partial<ActionButt
 
 /**
  * ActionButtons allow users to perform an action.
- * They’re used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren’t meant to draw a lot of attention.
+ * They're used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren't meant to draw a lot of attention.
  */
 export const ActionButton = forwardRef(function ActionButton(props: ActionButtonProps, ref: FocusableRef<HTMLButtonElement>) {
   [props, ref] = useSpectrumContextProps(props, ref, ActionButtonContext);
@@ -251,6 +280,7 @@ export const ActionButton = forwardRef(function ActionButton(props: ActionButton
     isDisabled = props.isDisabled
   } = ctx || {};
 
+
   return (
     <RACButton
       {...props}
@@ -281,6 +311,10 @@ export const ActionButton = forwardRef(function ActionButton(props: ActionButton
           [AvatarContext, {
             size: avatarSize[size],
             styles: style({marginStart: '--iconMargin', flexShrink: 0, order: 0})
+          }],
+          [NotificationBadgeContext, {
+            size: props.size === 'XS' ? undefined : props.size,
+            styles: style({position: 'absolute', top: '--badgeTop', insetStart: '[var(--badgePosition)]', marginTop: '[calc((self(height) * -1)/2)]', marginStart: '[calc((self(height) * -1)/2)]'})
           }]
         ]}>
         {typeof props.children === 'string' ? <Text>{props.children}</Text> : props.children}

packages/@react-spectrum/s2/src/NotificationBadge.tsx

@@ -0,0 +1,160 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {AriaLabelingProps, DOMProps, DOMRef, DOMRefValue} from '@react-types/shared';
+import {ContextValue, SlotProps} from 'react-aria-components';
+import {filterDOMProps} from '@react-aria/utils';
+import {fontRelative, style} from '../style' with {type: 'macro'};
+import {getAllowedOverrides, StyleProps} from './style-utils' with {type: 'macro'};
+// @ts-ignore
+import intlMessages from '../intl/*.json';
+import {NumberFormatter} from '@internationalized/number';
+import React, {createContext, forwardRef} from 'react';
+import {useDOMRef} from '@react-spectrum/utils';
+import {useLocale, useLocalizedStringFormatter} from '@react-aria/i18n';
+import {useSpectrumContextProps} from './useSpectrumContextProps';
+
+export interface NotificationBadgeStyleProps {
+  /**
+   * The size of the notification badge.
+   *
+   * @default 'S'
+   */
+  size?: 'S' | 'M' | 'L' | 'XL'
+}
+
+export interface NotificationBadgeProps extends DOMProps, AriaLabelingProps, StyleProps, NotificationBadgeStyleProps, SlotProps {
+  /**
+   * The value to be displayed in the notification badge.
+   */
+  value?: number | null
+}
+
+export const NotificationBadgeContext = createContext<ContextValue<Partial<NotificationBadgeProps>, DOMRefValue<HTMLDivElement>>>(null);
+
+const badge = style({
+  display: 'flex',
+  font: 'control',
+  color: {
+    default: 'white',
+    forcedColors: 'ButtonText'
+  },
+  fontSize: {
+    size: {
+      S: 'ui-xs',
+      M: 'ui-xs',
+      L: 'ui-sm',
+      XL: 'ui'
+    }
+  },
+  borderStyle: {
+    forcedColors: 'solid'
+  },
+  borderWidth: {
+    forcedColors: '[1px]'
+  },
+  borderColor: {
+    forcedColors: 'ButtonBorder'
+  },
+  justifyContent: 'center',
+  alignItems: 'center',
+  backgroundColor: {
+    default: 'accent',
+    forcedColors: 'ButtonFace'
+  },
+  height: {
+    size: {
+      S: {
+        default: 12,
+        isIndicatorOnly: 8
+      },
+      M: {
+        default: fontRelative(18), // sort of arbitrary? tried to get as close to the figma designs as possible
+        isIndicatorOnly: 8
+      },
+      L: {
+        default: 16,
+        isIndicatorOnly: fontRelative(12)
+      },
+      XL: {
+        default: 18,
+        isIndicatorOnly: fontRelative(12)
+      }
+    }
+  },
+  aspectRatio: {
+    isIndicatorOnly: 'square',
+    isSingleDigit: 'square'
+  },
+  width: 'fit',
+  paddingX: {
+    isDoubleDigit: 'edge-to-text'
+  },
+  borderRadius: 'pill'
+}, getAllowedOverrides());
+
+/**
+ * Notification badges are used to indicate new or pending activity .
+ */
+export const NotificationBadge = forwardRef(function Badge(props: NotificationBadgeProps, ref: DOMRef<HTMLDivElement>) {
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-spectrum/s2');
+  [props, ref] = useSpectrumContextProps(props, ref, NotificationBadgeContext);
+  let {
+    size = 'S',
+    value,
+    ...otherProps
+  } = props;
+  let domRef = useDOMRef(ref);
+  let {locale} = useLocale();
+  let formattedValue = '';
+
+  let isIndicatorOnly = false;
+  let isSingleDigit = false;
+  let isDoubleDigit = false;
+
+  if (value == null) {
+    isIndicatorOnly = true;
+  } else if (value <= 0) {
+    throw new Error('Value cannot be negative or zero');
+  } else if (!Number.isInteger(value)) {
+    throw new Error('Value must be a positive integer');
+  } else {
+    formattedValue = new NumberFormatter(locale).format(Math.min(value, 99));
+    let length = Math.log(value <= 99 ? value : 99) * Math.LOG10E + 1 | 0;  // for positive integers (https://stackoverflow.com/questions/14879691/get-number-of-digits-with-javascript)
+    if (length === 1) {
+      isSingleDigit = true;
+    } else if (length === 2) {
+      isDoubleDigit = true;
+    }
+
+    if (value > 99) {
+      formattedValue = stringFormatter.format('notificationbadge.plus', {notifications: formattedValue});
+    }
+  }
+
+  let ariaLabel = props['aria-label'] || undefined;
+  if (ariaLabel === undefined && isIndicatorOnly) {
+    ariaLabel = stringFormatter.format('notificationbadge.indicatorOnly');
+  }
+
+  return (
+    <span
+      {...filterDOMProps(otherProps, {labelable: true})}
+      role={ariaLabel && 'img'}
+      aria-label={ariaLabel}
+      className={(props.UNSAFE_className || '') + badge({size, isIndicatorOnly, isSingleDigit, isDoubleDigit}, props.styles)}
+      style={props.UNSAFE_style}
+      ref={domRef}>
+      {formattedValue}
+    </span>
+  );
+});

packages/@react-spectrum/s2/src/index.ts

@@ -53,6 +53,7 @@ export {InlineAlert, InlineAlertContext} from './InlineAlert';
 export {Link, LinkContext} from './Link';
 export {MenuItem, MenuTrigger, Menu, MenuSection, SubmenuTrigger, MenuContext} from './Menu';
 export {Meter, MeterContext} from './Meter';
+export {NotificationBadge, NotificationBadgeContext} from './NotificationBadge';
 export {NumberField, NumberFieldContext} from './NumberField';
 export {Picker, PickerItem, PickerSection, PickerContext} from './Picker';
 export {Popover} from './Popover';
@@ -123,6 +124,7 @@ export type {ImageCoordinatorProps} from './ImageCoordinator';
 export type {LinkProps} from './Link';
 export type {MenuTriggerProps, MenuProps, MenuItemProps, MenuSectionProps, SubmenuTriggerProps} from './Menu';
 export type {MeterProps} from './Meter';
+export type {NotificationBadgeProps} from './NotificationBadge';
 export type {PickerProps, PickerItemProps, PickerSectionProps} from './Picker';
 export type {PopoverProps} from './Popover';
 export type {ProgressBarProps} from './ProgressBar';

packages/@react-spectrum/s2/stories/ActionButton.stories.tsx

@@ -10,12 +10,15 @@
  * governing permissions and limitations under the License.
  */
 
-import {ActionButton, Avatar, Text} from '../src';
+import {ActionButton, Avatar, NotificationBadge, Text} from '../src';
+import BellIcon from '../s2wf-icons/S2_Icon_Bell_20_N.svg';
 import {categorizeArgTypes, StaticColorDecorator} from './utils';
+import CommentIcon from '../s2wf-icons/S2_Icon_Comment_20_N.svg';
 import type {Meta, StoryObj} from '@storybook/react';
 import NewIcon from '../s2wf-icons/S2_Icon_New_20_N.svg';
 import {style} from '../style' with { type: 'macro' };
 import './unsafe.css';
+import {useNumberFormatter} from 'react-aria';
 
 const meta: Meta<typeof ActionButton> = {
   component: ActionButton,
@@ -198,3 +201,41 @@ export const Avatars: Story = {
     );
   }
 };
+
+const NotificationBadgesExample = (args) => {
+  let badgeValue = 10;
+  let formattedValue = useNumberFormatter().format(badgeValue);
+
+  return (
+    <div style={{display: 'flex', gap: 8, padding: 8, justifyContent: 'center'}}>
+      <ActionButton aria-label="Messages has new activity" {...args}><CommentIcon /><NotificationBadge /></ActionButton>
+      <ActionButton aria-label={`${formattedValue} notifications`} {...args}><BellIcon /><NotificationBadge value={badgeValue} /></ActionButton>
+      <ActionButton {...args}><CommentIcon /><Text>Messages</Text><NotificationBadge value={5} /></ActionButton>
+      <ActionButton {...args}><Text>Notifications</Text><NotificationBadge value={105} /></ActionButton>
+    </div>
+  );
+};
+
+export const NotificationBadges: Story = {
+  render: NotificationBadgesExample
+};
+
+NotificationBadges.parameters = {
+  docs: {
+    source: {
+      transform: () => {
+        return `let badgeValue = 10;
+        let formattedValue = useNumberFormatter().format(badgeValue);
+      
+        return (
+          <div style={{display: 'flex', gap: 8, padding: 8, justifyContent: 'center'}}>
+            <ActionButton aria-label="Messages has new activity" {...props}><CommentIcon /><NotificationBadge /></ActionButton>
+            <ActionButton aria-label={\`\${formattedValue} notifications\`}  {...props}><BellIcon /><NotificationBadge value={badgeValue} /></ActionButton>
+            <ActionButton {...props}><CommentIcon /><Text>Messages</Text><NotificationBadge value={5} /></ActionButton>
+            <ActionButton {...props}><Text>Notifications</Text><NotificationBadge value={105} /></ActionButton>
+          </div>
+        )`;
+      }
+    }
+  }
+};

packages/@react-spectrum/s2/stories/NotificationBadge.stories.tsx

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {NotificationBadge} from '../src';
+
+const meta: Meta<typeof NotificationBadge> = {
+  component: NotificationBadge,
+  parameters: {
+    layout: 'centered'
+  },
+  tags: ['autodocs'],
+  title: 'NotificationBadge'
+};
+
+export default meta;
+
+type Story = StoryObj<typeof NotificationBadge>;
+export const Example: Story = {
+  render: (args) => {
+    return (
+      <div style={{display: 'flex', flexWrap: 'wrap', gap: 8, maxWidth: '600px'}}>
+        <NotificationBadge {...args} />
+        <NotificationBadge {...args} value={1} />
+        <NotificationBadge {...args} value={24} />
+        <NotificationBadge {...args} value={100} />
+      </div>
+    );
+  }
+};

yarn.lock

@@ -7935,6 +7935,7 @@ __metadata:
   resolution: "@react-spectrum/s2@workspace:packages/@react-spectrum/s2"
   dependencies:
     "@adobe/spectrum-tokens": "npm:^13.0.0-beta.56"
+    "@internationalized/number": "npm:^3.6.0"
     "@parcel/macros": "npm:^2.14.0"
     "@react-aria/collections": "npm:3.0.0-beta.1"
     "@react-aria/focus": "npm:^3.20.1"