@kiwicom/orbit-components/es/NotificationBadge/index.js

Orbit-components is a React component library which provides developers with the easiest possible way of building Kiwi.com's products.

"use client";

import * as React from "react";
import Badge from "../Badge";
/**
 * @orbit-doc-start
 * README
 * ----------
 * # NotificationBadge
 *
 * To implement NotificationBadge component into your project you'll need to add the import:
 *
 * ```jsx
 * import NotificationBadge from "@kiwicom/orbit-components/lib/NotificationBadge";
 * ```
 *
 * After adding import into your project you can use it simply like:
 *
 * ```jsx
 * <NotificationBadge>3</NotificationBadge>
 * ```
 *
 * ## Props
 *
 * Table below contains all types of the props available in NotificationBadge component.
 *
 * | Name      | Type            | Default     | Description                                                               |
 * | :-------- | :-------------- | :---------- | :------------------------------------------------------------------------ |
 * | children  | `React.Node`    |             | The content of the NotificationBadge.                                     |
 * | dataTest  | `string`        |             | Optional prop for testing purposes.                                       |
 * | id        | `string`        |             | Sets the `id` attribute for the Badge component inside NotificationBadge. |
 * | icon      | `React.Node`    |             | The displayed icon. If provided, children content will not be rendered.   |
 * | type      | [`enum`](#enum) | `"neutral"` | The color type of the NotificationBadge.                                  |
 * | ariaLabel | `string`        |             | Specifies the accessible name of the badge. See the Accessibility tab.    |
 *
 * ### enum
 *
 * | type               |
 * | :----------------- |
 * | `"neutral"`        |
 * | `"dark"`           |
 * | `"info"`           |
 * | `"success"`        |
 * | `"warning"`        |
 * | `"critical"`       |
 * | `"infoSubtle"`     |
 * | `"criticalSubtle"` |
 *
 *
 * Accessibility
 * -------------
 * ## Accessibility
 *
 * The NotificationBadge component has been designed with accessibility in mind, providing a way to display important notifications with proper screen reader support.
 *
 * ### Accessibility Props
 *
 * The following props are available to improve the accessibility of your NotificationBadge component:
 *
 * | Name      | Type         | Description                                                                                          |
 * | :-------- | :----------- | :--------------------------------------------------------------------------------------------------- |
 * | ariaLabel | `string`     | Provides an accessible name for the notification badge that will be announced by screen readers.     |
 * | icon      | `React.Node` | The displayed icon. When used, `ariaLabel` should be provided to ensure screen reader accessibility. |
 *
 * ### Automatic Accessibility Features
 *
 * The NotificationBadge component automatically sets `role="status"` to announce updates to assistive technologies.
 *
 * ### The `ariaLabel` Prop
 *
 * The `ariaLabel` prop is crucial for making NotificationBadge components accessible:
 *
 * - It sets the `aria-label` attribute on the badge, providing context for screen readers
 * - When provided, it completely replaces what screen readers would announce about the badge's visual content
 * - It's essential when using icons or when the numerical content alone isn't sufficient to convey meaning
 * - For number-only badges (like "3"), it can be used to add context about what the number represents (e.g., "3 unread messages")
 *
 * ### Best Practices
 *
 * #### Screen Reader Support
 *
 * - Always provide a descriptive `ariaLabel` that clearly explains what the notification badge represents
 * - Ensure all `ariaLabel` text is translated to the user's language
 * - Make the label concise but informative, focusing on the count and its meaning
 *
 * #### Using Icons
 *
 * - When using the `icon` prop, always provide an `ariaLabel` on the NotificationBadge component while adding `ariaHidden` to the icon itself
 * - Choose icons that visually reinforce the meaning of the notification
 *
 * #### Visual Design Considerations
 *
 * - Do not rely on color alone to convey the meaning of notifications
 * - While color types (critical, warning, info, etc.) help visually distinguish importance, always ensure meaning is conveyed through additional means like text, icons, or aria-label
 * - This approach ensures users with color vision impairments can understand the notification's importance
 * - Example: Combine a "critical" type notification with an appropriate icon and descriptive `ariaLabel`
 *
 * ### Examples
 *
 * #### Basic usage with numerical content
 *
 * ```jsx
 * <NotificationBadge ariaLabel="3 unread messages">3</NotificationBadge>
 * ```
 *
 * Screen reader announces: "3 unread messages, status".
 *
 * #### Usage with an icon
 *
 * ```jsx
 * <NotificationBadge type="critical" icon={<Email ariaHidden />} ariaLabel="Urgent unread message" />
 * ```
 *
 * Screen reader announces: "Urgent unread message, status".
 *
 * In this example, because an icon is provided, any children content would not be displayed. The `ariaLabel` ensures screen reader users still receive the notification information.
 *
 *
 * @orbit-doc-end
 */
const NotificationBadge = ({
  type,
  children,
  icon,
  ariaLabel,
  dataTest,
  id
}) => {
  return /*#__PURE__*/React.createElement("div", {
    className: "[&_.orbit-badge-primitive]:w-icon-large [&_.orbit-badge-primitive]:p-0"
  }, /*#__PURE__*/React.createElement(Badge, {
    type: type,
    dataTest: dataTest,
    id: id,
    icon: icon,
    ariaLabel: ariaLabel
  }, !icon && children));
};
export default NotificationBadge;