From 94ef5431130078ddc9a44a754e6905beefe8be9e Mon Sep 17 00:00:00 2001 From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com> Date: Tue, 21 May 2024 14:37:49 -0600 Subject: [PATCH] docs: contextual_help (#480) Closes https://github.com/deephaven/deephaven-plugins/issues/473 **Changes Implemented:** - Add documentation for contextual_help Adobe Spectrum element --- .../ui/components/spectrum/__init__.py | 1 + .../deephaven/ui/components/spectrum/basic.py | 8 - .../ui/components/spectrum/contextual_help.py | 185 ++++++++++++++++++ .../ui/components/spectrum/layout.py | 24 +++ .../ui/components/spectrum/validate.py | 2 + 5 files changed, 212 insertions(+), 8 deletions(-) create mode 100644 plugins/ui/src/deephaven/ui/components/spectrum/contextual_help.py diff --git a/plugins/ui/src/deephaven/ui/components/spectrum/__init__.py b/plugins/ui/src/deephaven/ui/components/spectrum/__init__.py index da4feedc6..028446059 100644 --- a/plugins/ui/src/deephaven/ui/components/spectrum/__init__.py +++ b/plugins/ui/src/deephaven/ui/components/spectrum/__init__.py @@ -2,6 +2,7 @@ from .basic import * from .button_group import * from .button import * +from .contextual_help import * from .text_field import * from .toggle_button import * from .flex import * diff --git a/plugins/ui/src/deephaven/ui/components/spectrum/basic.py b/plugins/ui/src/deephaven/ui/components/spectrum/basic.py index 4b3269828..118a25354 100644 --- a/plugins/ui/src/deephaven/ui/components/spectrum/basic.py +++ b/plugins/ui/src/deephaven/ui/components/spectrum/basic.py @@ -27,14 +27,6 @@ def content(*children, **props): return spectrum_element("Content", *children, **props) -def contextual_help(*children, **props): - """ - Python implementation for the Adobe React Spectrum ContextualHelp component. - https://react-spectrum.adobe.com/react-spectrum/ContextualHelp.html - """ - return spectrum_element("ContextualHelp", *children, **props) - - def grid(*children, **props): """ Python implementation for the Adobe React Spectrum Grid component. diff --git a/plugins/ui/src/deephaven/ui/components/spectrum/contextual_help.py b/plugins/ui/src/deephaven/ui/components/spectrum/contextual_help.py new file mode 100644 index 000000000..6055e384d --- /dev/null +++ b/plugins/ui/src/deephaven/ui/components/spectrum/contextual_help.py @@ -0,0 +1,185 @@ +from __future__ import annotations +from numbers import Number +from typing import Any, Callable +from .validate import ContextualHelperVariant +from .layout import ( + AlignSelf, + CSSProperties, + DimensionValue, + JustifySelf, + LayoutFlex, + Placement, + Position, +) +from .basic import spectrum_element +from ...elements import Element + + +def contextual_help( + *children: Any, + variant: ContextualHelperVariant | None = "help", + placement: Placement | None = "bottom start", + is_open: bool | None = None, + default_open: bool | None = None, + container_padding: Number | None = None, + offset: Number | None = None, + cross_offset: Number | None = None, + should_flip: bool | None = None, + on_open_change: Callable[[bool], None] | None = None, + flex: LayoutFlex | None = None, + flex_grow: Number | None = None, + flex_shrink: Number | None = None, + flex_basis: DimensionValue | None = None, + align_self: AlignSelf | None = None, + justify_self: JustifySelf | None = None, + order: Number | None = None, + grid_area: str | None = None, + grid_row: str | None = None, + grid_column: str | None = None, + grid_column_start: str | None = None, + grid_column_end: str | None = None, + grid_row_start: str | None = None, + grid_row_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: Number | 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, +) -> Element: + """ + A contextual help is a quiet action button that triggers an informational popover. + Args: + *children: The children of the contextual help popover. + variant: Indicates whether contents are informative or provides helpful guidance. + placement: The placement of the popover relative to the action button. + is_open: Whether the popover is open by default (controlled). + default_open: Whether the popover is open by default (uncontrolled). + container_padding: The placement padding that should be applied between the element and its surrounding container. + offset: The additional offset applied along the main axis between the element and its anchor element. + cross_offset: The additional offset applied along the cross axis between the element and its anchor element. + should_flip: Whether the element should flip its orientation when there is insufficient room for it to render completely. + on_open_change: Handler that is called when the overlay's open state changes. + 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. + """ + return spectrum_element( + "ContextualHelp", + *children, + variant=variant, + placement=placement, + is_open=is_open, + default_open=default_open, + container_padding=container_padding, + offset=offset, + cross_offset=cross_offset, + should_flip=should_flip, + on_open_change=on_open_change, + 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_column_start=grid_column_start, + grid_column_end=grid_column_end, + grid_row_start=grid_row_start, + grid_row_end=grid_row_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, + ) diff --git a/plugins/ui/src/deephaven/ui/components/spectrum/layout.py b/plugins/ui/src/deephaven/ui/components/spectrum/layout.py index febde194f..83f8073a0 100644 --- a/plugins/ui/src/deephaven/ui/components/spectrum/layout.py +++ b/plugins/ui/src/deephaven/ui/components/spectrum/layout.py @@ -6,6 +6,30 @@ Direction = Literal["row", "column", "row-reverse", "column-reverse"] Wrap = Literal["wrap", "nowrap", "wrap-reverse"] +Placement = Literal[ + "bottom", + "bottom left", + "bottom right", + "bottom start", + "bottom end", + "top", + "top left", + "top right", + "top start", + "top end", + "left", + "left top", + "left bottom", + "start", + "start top", + "start bottom", + "right", + "right top", + "right bottom", + "end", + "end top", +] + AlignContent = Literal[ "start", "end", diff --git a/plugins/ui/src/deephaven/ui/components/spectrum/validate.py b/plugins/ui/src/deephaven/ui/components/spectrum/validate.py index 222ec33c7..9c1caccf1 100644 --- a/plugins/ui/src/deephaven/ui/components/spectrum/validate.py +++ b/plugins/ui/src/deephaven/ui/components/spectrum/validate.py @@ -9,3 +9,5 @@ ] TextFieldValidationState = Literal["valid", "invalid"] TextFieldNecessityIndicator = Literal["icon", "label"] + +ContextualHelperVariant = Literal["help", "info"]