feat: ui.meter (#1032)

Closes #939

plugins/ui/docs/components/meter.md

@@ -0,0 +1,158 @@
+# Meter
+
+Meters visually represent a quantity or achievement, displaying progress on a bar with a label.
+
+## Example
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter():
+    return ui.meter(label="RAM Usage", value=35)
+
+
+my_meter = ui_meter()
+```
+
+## Value
+
+The `value` prop controls the meter and represents the current percentage of progress. By default, the minimum and maximum values are 0 and 100 but a different scale can be used by setting the `min_value` and `max_value` props. 
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter_value():
+    return ui.meter(label="Tutorials completed", value=100, min_value=50, max_value=150)
+
+
+my_meter_value = ui_meter_value()
+```
+
+## Formatting
+
+The `format_options` prop dictates how the value is displayed and which characters can be inputted. This parameter supports three styles: Percentage, Currency, and Units.
+
+Note: This prop is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat).
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter_format():
+    return ui.meter(
+        label="Currency",
+        value=75,
+        format_options={"style": "currency", "currency": "USD"},
+    )
+
+
+my_meter_format = ui_meter_format()
+```
+
+## Labeling
+
+When a label is provided, value labels are positioned above the meter by default. The `label_position` prop can change where these labels are placed, while the `show_value_prop` can hide them entirely.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter_label():
+    return [
+        ui.meter(
+            label="Label",
+            value=50,
+        ),
+        ui.meter(
+            label="Label",
+            value=50,
+            label_position="side",
+        ),
+        ui.meter(label="Label", value=50, show_value_label=False),
+    ]
+
+
+my_meter_label = ui_meter_label()
+```
+
+The `value_label` prop can update the value label directly where showing a different scale makes sense.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter_value_label():
+    return ui.meter(label="Currency", value=20, value_label="1 of 5")
+
+
+my_meter_value_label = ui_meter_value_label()
+```
+
+## Size
+
+The `size` prop controls how thick the meter bar is displayed.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter_size():
+    return [
+        ui.meter(label="Progress", value=75, size="S"),
+        ui.meter(label="Progress", value=75, size="L"),
+    ]
+
+
+my_meter_size = ui_meter_size()
+```
+
+## Variants
+
+The `variant` prop changes the meter's visual style. It supports four options: informative, positive, critical, and warning. 
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_meter_variant():
+    return [
+        ui.meter(
+            label="Progress",
+            value=75,
+            variant="informative",
+        ),
+        ui.meter(
+            label="Progress",
+            value=75,
+            variant="positive",
+        ),
+        ui.meter(
+            label="Progress",
+            value=75,
+            variant="critical",
+        ),
+        ui.meter(
+            label="Progress",
+            value=75,
+            variant="warning",
+        ),
+    ]
+
+
+my_meter_variant = ui_meter_variant()
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.ui.meter
+```

plugins/ui/docs/sidebar.json

@@ -150,6 +150,10 @@
             "label": "markdown",
             "path": "components/markdown.md"
           },
+          {
+            "label": "meter",
+            "path": "components/meter.md"
+          },
           {
             "label": "number_field",
             "path": "components/number_field.md"

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

@@ -38,6 +38,7 @@
 from .list_view import list_view
 from .make_component import make_component as component
 from .markdown import markdown
+from .meter import meter
 from .number_field import number_field
 from .panel import panel
 from .picker import picker
@@ -109,6 +110,7 @@
     "list_action_menu",
     "html",
     "markdown",
+    "meter",
     "number_field",
     "panel",
     "picker",

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

@@ -0,0 +1,194 @@
+from __future__ import annotations
+from typing import Any
+from .types import (
+    AlignSelf,
+    CSSProperties,
+    DimensionValue,
+    JustifySelf,
+    LayoutFlex,
+    Position,
+    LabelPosition,
+    NumberFormatOptions,
+    MeterVariants,
+    MeterSizes,
+)
+from .basic import component_element
+from ..elements import Element
+
+
+def meter(
+    variant: MeterVariants = "informative",
+    size: MeterSizes = "L",
+    label_position: LabelPosition = "top",
+    show_value_label: bool | None = None,
+    label: Any | None = None,
+    format_options: NumberFormatOptions | None = None,
+    value_label: Any | None = None,
+    value: float = 0,
+    min_value: float = 0,
+    max_value: float = 100,
+    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_row_start: str | None = None,
+    grid_row_end: str | None = None,
+    grid_column: 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,
+    start: DimensionValue | None = None,
+    end: DimensionValue | None = None,
+    left: DimensionValue | None = None,
+    right: 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:
+    """
+    Meters visually represent a quantity or achievement, displaying progress on a bar with a label.
+
+    Args:
+        variant: The visual style of the meter.
+        size: How thick the bar should be.
+        label_position: The position of the label relative to the input.
+        show_value_label: Whether to show the value label.
+        label: The label for the input.
+        format_options: Options for formatting the displayed value, which also restricts input characters.
+        value_label: The label for the value (e.g. 1 of 4).
+        value: The current value of the input
+        min_value: The minimum value of the input
+        max_value: The maximum value of the input
+        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.
+        min_width: The minimum width of the element.
+        max_width: The maximum width of the element.
+        height: The height of the element.
+        min_height: The minimum height of the element.
+        max_height: The maximum height of the element.
+        position: The position of the element.
+        top: The distance from the top of the containing element.
+        bottom: The distance from the bottom of the containing element.
+        left: The distance from the left of the containing element.
+        right: The distance from the right of the containing element.
+        start: The distance from the start of the containing element, depending on layout direction.
+        end: The distance from the end of the containing element, depending on layout direction.
+        z_index: The stack order of the element.
+        is_hidden: Whether the element is hidden.
+        id: The unique identifier of the element.
+        aria_label: The label for the element.
+        aria_labelledby: The id of the element that labels the current element.
+        aria_describedby: The id of the element that describes the current element.
+        aria_details: The id of the element that provides additional information about the current element.
+        UNSAFE_class_name: A CSS class to apply to the element.
+        UNSAFE_style: A CSS style to apply to the element.
+        key: A unique identifier used by React to render elements in a list.
+
+    Returns:
+        The rendered meter element.
+    """
+
+    return component_element(
+        "Meter",
+        variant=variant,
+        size=size,
+        label_position=label_position,
+        show_value_label=show_value_label,
+        label=label,
+        format_options=format_options,
+        value_label=value_label,
+        value=value,
+        min_value=min_value,
+        max_value=max_value,
+        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_row_start=grid_row_start,
+        grid_row_end=grid_row_end,
+        grid_column=grid_column,
+        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,
+        start=start,
+        end=end,
+        left=left,
+        right=right,
+        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/components/number_field.py

@@ -12,7 +12,7 @@
     LayoutFlex,
     Position,
     LabelPosition,
-    NumberFieldFormatOptions,
+    NumberFormatOptions,
     Alignment,
 )
 from .basic import component_element
@@ -25,7 +25,7 @@ def number_field(
     decrement_aria_label: str | None = None,
     increment_aria_label: str | None = None,
     is_wheel_disabled: bool | None = None,
-    format_options: NumberFieldFormatOptions | None = None,
+    format_options: NumberFormatOptions | None = None,
     is_disabled: bool | None = None,
     is_read_only: bool | None = None,
     is_required: bool | None = None,