From 3ea6f7a33c4c8bdcce8a0c5fe740619f8c55be58 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Fri, 9 Aug 2024 15:19:35 -0600 Subject: [PATCH 1/9] docs: ui.checkbox --- plugins/ui/docs/components/checkbox.md | 131 +++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 plugins/ui/docs/components/checkbox.md diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md new file mode 100644 index 000000000..c2bd723cb --- /dev/null +++ b/plugins/ui/docs/components/checkbox.md @@ -0,0 +1,131 @@ +# Checkbox + +Checkboxes enable users to select multiple items from a list or mark a single item as selected. + +## Example + +```python +from deephaven import ui + +cb = ui.checkbox("Unsubscribe") +``` + +## UI recommendations + +Recommendations for creating checkboxes: + +1. Use emphasized checkboxes for forms, settings, or to highlight selected items like cards or table rows. Use non-emphasized checkboxes in application panels with monochrome components to keep the focus on the main content. +2. Use standalone checkboxes when the context is clear without a text label, such as when a checkbox is associated with other controls within a panel. +3. Checkboxes and radio buttons should not be used interchangably. Use checkboxes to allow multiple selections (or none) from a list. Use radio buttons to select only one option from a list of mutually exclusive choices. +4. Checkboxes should be used when selecting (ie. multiple table rows), whereas, switches should be used for activation (ie. on/off states). + + +## Content + +Checkbox's accept a child, which is rendered as the label of the checkbox. + +```python +from deephaven import ui + +my_checkbox_basic = ui.checkbox("Basic Checkbox") +``` + +## Value + +Checkboxes are not selected by default. Use the `default_selected` prop to set the initial state (uncontrolled) or the `is_selected` prop to control the selected state. + +```python +from deephaven import ui + + +@ui.component +def ui_checkbox_content_examples(): + selected, set_selected = ui.use_state(False) + return ui.flex( + ui.checkbox("Subscribe (uncontrolled)", default_selected=True), + ui.checkbox( + "Subscribe (uncontrolled)", is_selected=selected, on_change=set_selected + ), + direction="column", + ) + + +my_checkbox_content_examples = ui_checkbox_content_examples() +``` + + +## Indeterminate state + +A Checkbox can be set to an indeterminate state using the `is_indeterminate` prop, which overrides its appearance. The Checkbox remains visually indeterminate until prop is set to false, regardless of user interaction. + + +```python +from deephaven import ui + + +my_checkbox_is_indeterminate_example = ui.checkbox( + "Indeterminate State", is_indeterminate=True +) +``` + +## HTML Forms + +Checkbox's can support a `name` prop for integration with HTML forms, allowing for easy identification of a value on form submission. + +```python +from deephaven import ui + + +my_picker_name_example = ui.form( + ui.flex(ui.checkbox("Sample Label", name="Sample Name")) +) +``` + +## Events + +Checkboxes accept an `on_change` prop, which is triggered whenever the Checkbox is clicked + +```python +from deephaven import ui + + +@ui.component +def ui_checkbox_event_example(): + selected, set_selected = ui.use_state(False) + return ui.flex( + ui.checkbox("Subscribe", is_selected=selected, on_change=set_selected), + ui.text_field(value="Subscribed!" if selected else "Not subscribed!"), + direction="column", + ) + + +my_checkbox_event_example = ui_checkbox_event_example() +``` +## Validation + +Checkboxes can indicate a validation state to show if the current value is invalid, via the `is_invalid` prop. Since the invalid state is only shown through a color change, ensure the validation error is also communicated in another accessible way. + +```python +from deephaven import ui + + +@ui.component +def ui_checkbox_validation_example(): + invalid, set_invalid = ui.use_state(False) + return [ + ui.button( + "Make checkbox valid" if invalid else "Make checkbox invalid", + on_press=lambda: set_invalid(not invalid), + ), + ui.checkbox("I accept the terms and conditions", is_invalid=invalid), + ] + + +my_checkbox_validation_example = ui_checkbox_validation_example() +``` + +## API reference + +```{eval-rst} +.. dhautofunction:: deephaven.ui.checkbox +``` From 75b96db5c0e451d991fac03872053062b3def2b0 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Fri, 9 Aug 2024 15:20:43 -0600 Subject: [PATCH 2/9] fix typo --- plugins/ui/docs/components/checkbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index c2bd723cb..353b7c5ea 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -76,7 +76,7 @@ Checkbox's can support a `name` prop for integration with HTML forms, allowing f from deephaven import ui -my_picker_name_example = ui.form( +my_checkbox_name_example = ui.form( ui.flex(ui.checkbox("Sample Label", name="Sample Name")) ) ``` From 0ada58497cf4d048db2efbe8f17811cc7d44ca52 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Mon, 12 Aug 2024 08:28:24 -0600 Subject: [PATCH 3/9] add section of when to use what --- plugins/ui/docs/components/checkbox.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index 353b7c5ea..ddb990905 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -20,6 +20,8 @@ Recommendations for creating checkboxes: 4. Checkboxes should be used when selecting (ie. multiple table rows), whereas, switches should be used for activation (ie. on/off states). +Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related checkboxes, use a [`checkbox_group`](./checkbox_group.md) to manage multiple selections within a group. If you need to display a list of checkboxes driven by a Deephaven table, use a [`list_view`](./list_view.md) to dynamically generate the checkboxes. + ## Content Checkbox's accept a child, which is rendered as the label of the checkbox. From 046f9b2be2dda5c9a6922664693913a19cd3ec07 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Fri, 16 Aug 2024 15:48:16 -0600 Subject: [PATCH 4/9] make changes based on review --- plugins/ui/docs/components/checkbox.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index ddb990905..b3947507a 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -1,6 +1,8 @@ # Checkbox -Checkboxes enable users to select multiple items from a list or mark a single item as selected. +Checkbox allows users to select or mark a single item as selected. + +If wanting to use multiple checkboxes, use `checkbox_group`. ## Example From 7958f4b49fd6abc93b99805bd6336a50c930f507 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Mon, 19 Aug 2024 08:17:07 -0600 Subject: [PATCH 5/9] fix returns statement --- plugins/ui/src/deephaven/ui/components/checkbox.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/ui/src/deephaven/ui/components/checkbox.py b/plugins/ui/src/deephaven/ui/components/checkbox.py index d8bb1029d..be74ab9e4 100644 --- a/plugins/ui/src/deephaven/ui/components/checkbox.py +++ b/plugins/ui/src/deephaven/ui/components/checkbox.py @@ -153,6 +153,9 @@ def checkbox( aria_errormessage: The id of the element that provides error information for the current element. UNSAFE_class_name: A CSS class to apply to the element. UNSAFE_style: A CSS style to apply to the element. + + Returns: + The rendered checkbox. """ return component_element( From 1b5ab5c15be9361a4fefa0c9b83e8bdb72348073 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Mon, 19 Aug 2024 09:43:08 -0600 Subject: [PATCH 6/9] make change according to review --- plugins/ui/docs/components/checkbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index b3947507a..990856cd8 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -2,7 +2,7 @@ Checkbox allows users to select or mark a single item as selected. -If wanting to use multiple checkboxes, use `checkbox_group`. +To use multiple checkboxes together, use the `checkbox_group` component. ## Example From 9fef154b5c1c3ce98a9ef817238202b1e86f617a Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Mon, 19 Aug 2024 10:09:50 -0600 Subject: [PATCH 7/9] change text field to text --- plugins/ui/docs/components/checkbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index 990856cd8..c328b43e7 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -98,7 +98,7 @@ def ui_checkbox_event_example(): selected, set_selected = ui.use_state(False) return ui.flex( ui.checkbox("Subscribe", is_selected=selected, on_change=set_selected), - ui.text_field(value="Subscribed!" if selected else "Not subscribed!"), + ui.text(value="Subscribed!" if selected else "Not subscribed!"), direction="column", ) From eef33470d45307162bbdfabaa9b80cde304893ac Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Mon, 19 Aug 2024 11:34:47 -0600 Subject: [PATCH 8/9] make changes based on review --- plugins/ui/docs/components/checkbox.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index c328b43e7..4e0bda676 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -80,9 +80,7 @@ Checkbox's can support a `name` prop for integration with HTML forms, allowing f from deephaven import ui -my_checkbox_name_example = ui.form( - ui.flex(ui.checkbox("Sample Label", name="Sample Name")) -) +my_checkbox_name_example = ui.form(ui.checkbox("Sample Label", name="Sample Name")) ``` ## Events From f1a6643dcdc44bf00ed247cd5bef8fa0e4592b26 Mon Sep 17 00:00:00 2001 From: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com> Date: Mon, 19 Aug 2024 14:10:05 -0400 Subject: [PATCH 9/9] Apply suggestions from code review --- plugins/ui/docs/components/checkbox.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md index 4e0bda676..dae59265f 100644 --- a/plugins/ui/docs/components/checkbox.md +++ b/plugins/ui/docs/components/checkbox.md @@ -19,7 +19,7 @@ Recommendations for creating checkboxes: 1. Use emphasized checkboxes for forms, settings, or to highlight selected items like cards or table rows. Use non-emphasized checkboxes in application panels with monochrome components to keep the focus on the main content. 2. Use standalone checkboxes when the context is clear without a text label, such as when a checkbox is associated with other controls within a panel. 3. Checkboxes and radio buttons should not be used interchangably. Use checkboxes to allow multiple selections (or none) from a list. Use radio buttons to select only one option from a list of mutually exclusive choices. -4. Checkboxes should be used when selecting (ie. multiple table rows), whereas, switches should be used for activation (ie. on/off states). +4. Checkboxes should be used when selecting (ie., multiple table rows), whereas switches should be used for activation (ie., on/off states). Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related checkboxes, use a [`checkbox_group`](./checkbox_group.md) to manage multiple selections within a group. If you need to display a list of checkboxes driven by a Deephaven table, use a [`list_view`](./list_view.md) to dynamically generate the checkboxes. @@ -60,7 +60,7 @@ my_checkbox_content_examples = ui_checkbox_content_examples() ## Indeterminate state -A Checkbox can be set to an indeterminate state using the `is_indeterminate` prop, which overrides its appearance. The Checkbox remains visually indeterminate until prop is set to false, regardless of user interaction. +A checkbox can be set to an indeterminate state using the `is_indeterminate` prop, which overrides its appearance. The Checkbox remains visually indeterminate until the prop is set to false, regardless of user interaction. ```python