feat: ui.badge

plugins/ui/docs/components/badge.md

@@ -0,0 +1,85 @@
+# Badge
+
+Badges display small, color-coded pieces of metadata to capture a user's attention. They are useful for highlighting important information, such as notifications, statuses, or counts.
+
+## Example
+
+```python
+from deephaven import ui
+
+my_badge_basic = ui.badge("Licensed", variant="positive")
+```
+
+## UI recommendations
+
+Consider using [`text`](./text.md) to provide descriptive text for elements without the colored emphasis of a badge.
+
+
+## Content
+
+Badges can include a label, an icon, or both as children.
+
+```python
+from deephaven import ui
+
+
+my_badge_context_example = ui.badge(
+    ui.icon("vsWarning"), "Rejected", variant="negative"
+)
+```
+
+
+## Variants
+
+Badges can have different colors to indicate their purpose.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_badge_variant_examples():
+    return [
+        ui.badge(
+            "Green: Approved, Complete, Success, New, Purchased, Licensed",
+            variant="positive",
+        ),
+        ui.badge("Blue: Active, In Use, Live, Published", variant="info"),
+        ui.badge("Red: Error, Alert, Rejected, Failed", variant="negative"),
+        ui.badge(
+            "Gray: Archived, Deleted, Paused, Draft, Not Started, Ended",
+            variant="neutral",
+        ),
+    ]
+
+
+my_badge_variant_examples = ui_badge_variant_examples()
+```
+
+Use badges with label colors to color-code categories, ideally for 8 or fewer categories.
+
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_badge_variant_color_examples():
+    return [
+        ui.badge("Seafoam", variant="seafoam"),
+        ui.badge("Indigo", variant="indigo"),
+        ui.badge("Purple", variant="purple"),
+        ui.badge("Fuchsia", variant="fuchsia"),
+        ui.badge("Magenta", variant="magenta"),
+        ui.badge("Yellow", variant="yellow"),
+    ]
+
+
+my_badge_variant_color_examples = ui_badge_variant_color_examples()
+```
+
+## API reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.ui.badge
+```

plugins/ui/docs/sidebar.json

@@ -29,6 +29,10 @@
             "label": "action_group",
             "path": "components/action_group.md"
           },
+          {
+            "label": "badge",
+            "path": "components/badge.md"
+          },
           {
             "label": "button",
             "path": "components/button.md"

plugins/ui/src/deephaven/ui/components/__init__.py

@@ -4,6 +4,7 @@
 from .basic import (
     component_element,
 )
+from .badge import badge
 from .button import button
 from .button_group import button_group
 from .calendar import calendar
@@ -65,6 +66,7 @@
     "action_group",
     "action_menu",
     "component_element",
+    "badge",
     "button",
     "button_group",
     "calendar",

plugins/ui/src/deephaven/ui/components/badge.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+from typing import Any
+from .types import (
+    # Layout
+    AlignSelf,
+    CSSProperties,
+    DimensionValue,
+    JustifySelf,
+    LayoutFlex,
+    Position,
+)
+from .basic import component_element
+from ..elements import Element
+from ..types import BadgeVariant
+
+
+def badge(
+    *children: Any,
+    variant: BadgeVariant | None = None,
+    flex: LayoutFlex | None = None,
+    flex_grow: float | None = None,
+    flex_shrink: float | None = None,
+    flex_basis: DimensionValue | None = None,
+    align_self: AlignSelf | None = None,
+    justify_self: JustifySelf | None = None,
+    order: int | None = None,
+    grid_area: str | None = None,
+    grid_row: str | None = None,
+    grid_column: str | None = None,
+    grid_row_start: str | None = None,
+    grid_row_end: str | None = None,
+    grid_column_start: str | None = None,
+    grid_column_end: str | None = None,
+    margin: DimensionValue | None = None,
+    margin_top: DimensionValue | None = None,
+    margin_bottom: DimensionValue | None = None,
+    margin_start: DimensionValue | None = None,
+    margin_end: DimensionValue | None = None,
+    margin_x: DimensionValue | None = None,
+    margin_y: DimensionValue | None = None,
+    width: DimensionValue | None = None,
+    height: DimensionValue | None = None,
+    min_width: DimensionValue | None = None,
+    min_height: DimensionValue | None = None,
+    max_width: DimensionValue | None = None,
+    max_height: DimensionValue | None = None,
+    position: Position | None = None,
+    top: DimensionValue | None = None,
+    bottom: DimensionValue | None = None,
+    left: DimensionValue | None = None,
+    right: DimensionValue | None = None,
+    start: DimensionValue | None = None,
+    end: DimensionValue | None = None,
+    z_index: int | None = None,
+    is_hidden: bool | None = None,
+    id: str | None = None,
+    aria_label: str | None = None,
+    aria_labelledby: str | None = None,
+    aria_describedby: str | None = None,
+    aria_details: str | None = None,
+    UNSAFE_class_name: str | None = None,
+    UNSAFE_style: CSSProperties | None = None,
+    key: str | None = None,
+) -> Element:
+    """
+    A badge is used for showing a small amount of color-categorized metadata.
+
+    Args:
+        *children: The content to display in the badge.
+        variant: The background color of the badge.
+        flex: When used in a flex layout, specifies how the element will grow or shrink to fit the space available.
+        flex_grow: When used in a flex layout, specifies how the element will grow to fit the space available.
+        flex_shrink: When used in a flex layout, specifies how the element will shrink to fit the space available.
+        flex_basis: When used in a flex layout, specifies the initial main size of the element.
+        align_self: Overrides the alignItems property of a flex or grid container.
+        justify_self: Species how the element is justified inside a flex or grid container.
+        order: The layout order for the element within a flex or grid container.
+        grid_area: When used in a grid layout specifies, specifies the named grid area that the element should be placed in within the grid.
+        grid_row: When used in a grid layout, specifies the row the element should be placed in within the grid.
+        grid_column: When used in a grid layout, specifies the column the element should be placed in within the grid.
+        grid_row_start: When used in a grid layout, specifies the starting row to span within the grid.
+        grid_row_end: When used in a grid layout, specifies the ending row to span within the grid.
+        grid_column_start: When used in a grid layout, specifies the starting column to span within the grid.
+        grid_column_end: When used in a grid layout, specifies the ending column to span within the grid.
+        margin: The margin for all four sides of the element.
+        margin_top: The margin for the top side of the element.
+        margin_bottom: The margin for the bottom side of the element.
+        margin_start: The margin for the logical start side of the element, depending on layout direction.
+        margin_end: The margin for the logical end side of the element, depending on layout direction.
+        margin_x: The margin for the left and right sides of the element.
+        margin_y: The margin for the top and bottom sides of the element.
+        width: The width of the element.
+        height: The height of the element.
+        min_width: The minimum width of the element.
+        min_height: The minimum height of the element.
+        max_width: The maximum width of the element.
+        max_height: The maximum height of the element.
+        position: Specifies how the element is position.
+        top: The top position of the element.
+        bottom: The bottom position of the element.
+        left: The left position of the element.
+        right: The right position of the element.
+        start: The logical start position of the element, depending on layout direction.
+        end: The logical end position of the element, depending on layout direction.
+        z_index: The stacking order for the element
+        is_hidden: Hides the element.
+        id: The unique identifier of the element.
+        aria_label: Defines a string value that labels the current element.
+        aria_labelledby: Identifies the element (or elements) that labels the current element.
+        aria_describedby: Identifies the element (or elements) that describes the object.
+        aria_details: Identifies the element (or elements) that provide a detailed, extended description for the object.
+        UNSAFE_class_name: Set the CSS className for the element. Only use as a last resort. Use style props instead.
+        UNSAFE_style: Set the inline style for the element. Only use as a last resort. Use style props instead.
+        key: A unique identifier used by React to render elements in a list.
+
+    Returns:
+        The rendered badge element.
+
+    """
+    return component_element(
+        "Badge",
+        *children,
+        variant=variant,
+        flex=flex,
+        flex_grow=flex_grow,
+        flex_shrink=flex_shrink,
+        flex_basis=flex_basis,
+        align_self=align_self,
+        justify_self=justify_self,
+        order=order,
+        grid_area=grid_area,
+        grid_row=grid_row,
+        grid_column=grid_column,
+        grid_row_start=grid_row_start,
+        grid_row_end=grid_row_end,
+        grid_column_start=grid_column_start,
+        grid_column_end=grid_column_end,
+        margin=margin,
+        margin_top=margin_top,
+        margin_bottom=margin_bottom,
+        margin_start=margin_start,
+        margin_end=margin_end,
+        margin_x=margin_x,
+        margin_y=margin_y,
+        width=width,
+        height=height,
+        min_width=min_width,
+        min_height=min_height,
+        max_width=max_width,
+        max_height=max_height,
+        position=position,
+        top=top,
+        bottom=bottom,
+        left=left,
+        right=right,
+        start=start,
+        end=end,
+        z_index=z_index,
+        is_hidden=is_hidden,
+        id=id,
+        aria_label=aria_label,
+        aria_labelledby=aria_labelledby,
+        aria_describedby=aria_describedby,
+        aria_details=aria_details,
+        UNSAFE_class_name=UNSAFE_class_name,
+        UNSAFE_style=UNSAFE_style,
+        key=key,
+    )

plugins/ui/src/deephaven/ui/types/types.py

@@ -506,6 +506,18 @@ class SliderChange(TypedDict):
 ListViewOverflowMode = Literal["truncate", "wrap"]
 ActionGroupDensity = Literal["compact", "regular"]
 TabDensity = Literal["compact", "regular"]
+BadgeVariant = Literal[
+    "neutral",
+    "info",
+    "positive",
+    "negative",
+    "indigo",
+    "yellow",
+    "magenta",
+    "fuchsia",
+    "purple",
+    "seafoam",
+]
 Dependencies = Union[Tuple[Any], List[Any]]
 Selection = Sequence[Key]
 LocalTime = DType

plugins/ui/src/js/src/elements/Badge.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import {
+  Badge as DHCBadge,
+  BadgeProps as DHCBadgeProps,
+} from '@deephaven/components';
+
+export function Badge(props: DHCBadgeProps): JSX.Element {
+  const { variant } = props;
+  return (
+    // eslint-disable-next-line react/jsx-props-no-spreading
+    <DHCBadge {...props} variant={variant} />
+  );
+}
+
+Badge.displayName = 'Badge';
+
+export default Badge;

plugins/ui/src/js/src/elements/index.ts

@@ -1,5 +1,6 @@
 export * from './ActionButton';
 export * from './ActionGroup';
+export * from './Badge';
 export * from './Button';
 export * from './Calendar';
 export * from './ComboBox';

plugins/ui/src/js/src/elements/model/ElementConstants.ts

@@ -26,6 +26,7 @@ export const ELEMENT_NAME = {
   actionButton: uiComponentName('ActionButton'),
   actionGroup: uiComponentName('ActionGroup'),
   actionMenu: uiComponentName('ActionMenu'),
+  badge: uiComponentName('Badge'),
   button: uiComponentName('Button'),
   buttonGroup: uiComponentName('ButtonGroup'),
   calendar: uiComponentName('Calendar'),

plugins/ui/src/js/src/widget/WidgetUtils.tsx

@@ -6,6 +6,7 @@ import type { JSONRPCServerAndClient } from 'json-rpc-2.0';
 // wrapped due to how Spectrum collection components consume them.
 import {
   ActionMenu,
+  Badge,
   ButtonGroup,
   SpectrumCheckbox as Checkbox,
   CheckboxGroup,
@@ -107,6 +108,7 @@ export const elementComponentMap = {
   [ELEMENT_NAME.actionButton]: ActionButton,
   [ELEMENT_NAME.actionGroup]: ActionGroup,
   [ELEMENT_NAME.actionMenu]: ActionMenu,
+  [ELEMENT_NAME.badge]: Badge,
   [ELEMENT_NAME.button]: Button,
   [ELEMENT_NAME.buttonGroup]: ButtonGroup,
   [ELEMENT_NAME.calendar]: Calendar,