From 73a4af6f1800eefd8bdb2f3c8469a6fe25b40b3c Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Fri, 23 Aug 2024 11:50:20 -0600 Subject: [PATCH 1/9] docs: ui.switch --- plugins/ui/docs/components/slider.md | 1 + plugins/ui/docs/components/switch.md | 0 2 files changed, 1 insertion(+) create mode 100644 plugins/ui/docs/components/switch.md diff --git a/plugins/ui/docs/components/slider.md b/plugins/ui/docs/components/slider.md index bdb1cf090..d362226f2 100644 --- a/plugins/ui/docs/components/slider.md +++ b/plugins/ui/docs/components/slider.md @@ -8,6 +8,7 @@ Sliders allow users to quickly select a value within a fixed range and should be ```python from deephaven import ui + my_slider_basic = ui.slider(default_value=12, label="Cookies to buy") ``` diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md new file mode 100644 index 000000000..e69de29bb From 0e3b5efaf62ec23b363a5ae19a0e5a7aafc1f896 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Tue, 3 Sep 2024 09:50:07 -0400 Subject: [PATCH 2/9] docs:ui.switch --- plugins/ui/docs/components/switch.md | 136 +++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index e69de29bb..ebe842d32 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -0,0 +1,136 @@ +# Switch + +Switches allow users to turn a single option on or off. + +## Example + +```python +from deephaven import ui + +my_switch_basic = ui.switch("Low power mode") +``` + +## UI recommendations + +Recommendations for creating switches: + +1. Every switch should have a [label](#labeling) specified. Without one, the switch is ambiguous. In the rare case that context is sufficient, the label is unnecessary; you must still include an aria-label via the `aria_label` prop. +2. The label should be in sentence case. + +Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related options, use a [`checkbox_group`](./checkbox_group.md) to manage multiple selections within a group. For when users need to provide specific information that cannot be communicated by a switch, consider using the `text` component. + +## Value + +Switches 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_switch_value_examples(): + selected, set_selected = ui.use_state(False) + return [ + ui.switch("Low power mode (uncontrolled)", default_selected=True), + ui.switch( + "Low power mode (controlled)", is_selected=selected, on_change=set_selected + ), + ] + + +my_switch_value_examples = ui_switch_value_examples() +``` + + +## HTML Forms + +Switches 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_switch_name_example = ui.form(ui.switch("Low Power Mode", name="power", value="low")) +``` + +## Labeling + +The switch can be labeled by passing in a a child. If no label is provided, an `aria_label` must be provided to identify the control for accessibility purposes. + +```python +from deephaven import ui + + +@ui.component +def ui_switch_label_examples(): + return [ + ui.switch("Switch Label", name="value"), + ui.switch(aria_label="Switch Label", name="value"), + ] + + +my_switch_label_examples = ui_switch_label_examples() +``` + + +## Events + +The `on_change` property is triggered whenever the switch is pressed. + +```python +from deephaven import ui + + +@ui.component +def ui_switch_on_change_example(): + selected, set_selected = ui.use_state(False) + return [ + ui.switch("Switch Label", on_change=set_selected, is_selected=selected), + ui.text(f"The switch is {'on' if selected else 'off'}."), + ] + + +my_switch_on_change_example = ui_switch_on_change_example() +``` + + +## Disabled + +Setting the `is_disabled` prop disables the switch. + +```python +from deephaven import ui + + +my_switch_is_disabled_example = ui.switch("Switch Label", is_disabled=True) +``` + + +## Emphasized + +The `is_emphasized` prop makes the fill of the switch be the user's accent color, adding a visual prominence to the selection. + +```python +from deephaven import ui + + +my_switch_is_emphasized_example = ui.switch("Switch Label", is_emphasized=True) +``` + + +## Read only + +The `is_read_only` prop makes the switch read-only to prevent user interaction. This is different from setting the `is_disabled` prop since the switch remains focusable. + +```python +from deephaven import ui + + +my_switch_is_read_only_example = ui.switch( + "Switch Label", is_read_only=True, default_selected=True +) +``` +## API Reference +```{eval-rst} +.. dhautofunction:: deephaven.ui.switch +``` \ No newline at end of file From d2d9d0b1825b431172c6bec37aeb2817be3e5ab6 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Tue, 3 Sep 2024 10:12:15 -0400 Subject: [PATCH 3/9] add missing line --- plugins/ui/docs/components/switch.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index ebe842d32..3026514e1 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -131,6 +131,7 @@ my_switch_is_read_only_example = ui.switch( ) ``` ## API Reference + ```{eval-rst} .. dhautofunction:: deephaven.ui.switch ``` \ No newline at end of file From de0827ed83af5962b16d37f9665acb602aee1c2e Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Tue, 3 Sep 2024 10:18:27 -0400 Subject: [PATCH 4/9] add returns comment to pydoc --- plugins/ui/src/deephaven/ui/components/switch.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/plugins/ui/src/deephaven/ui/components/switch.py b/plugins/ui/src/deephaven/ui/components/switch.py index a41aca3e6..2e8c78f56 100644 --- a/plugins/ui/src/deephaven/ui/components/switch.py +++ b/plugins/ui/src/deephaven/ui/components/switch.py @@ -142,6 +142,9 @@ def switch( aria_details: The details for the 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 switch element. """ return component_element( From 999449123d737ee5b650abda71c9aadb964bd879 Mon Sep 17 00:00:00 2001 From: Akshat Jawne Date: Wed, 4 Sep 2024 10:30:25 -0400 Subject: [PATCH 5/9] modify ui reccomendations --- plugins/ui/docs/components/switch.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index 3026514e1..897f53511 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -14,8 +14,11 @@ my_switch_basic = ui.switch("Low power mode") Recommendations for creating switches: -1. Every switch should have a [label](#labeling) specified. Without one, the switch is ambiguous. In the rare case that context is sufficient, the label is unnecessary; you must still include an aria-label via the `aria_label` prop. -2. The label should be in sentence case. +1. Emphasized switches are ideal for forms and settings where the switch being noticed is crucial, while non-emphasized switches suit monochrome application panels to maintain focus on the canvas. +2. Use a standalone switch when the context is clear without a text label, such as next to a panel's title to enable or disable panel options. +3. Use switches for activation and checkboxes for selection; switches cannot have an error state, unlike checkboxes. +4. When a switch represents multiple differing values, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them. +5. Switches can only be on or off; for partial states, use a checkbox as indeterminate switches are not accessible. Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related options, use a [`checkbox_group`](./checkbox_group.md) to manage multiple selections within a group. For when users need to provide specific information that cannot be communicated by a switch, consider using the `text` component. From 5b403834eaac9a337c47c9f1a343b9656730692c Mon Sep 17 00:00:00 2001 From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:01:46 -0400 Subject: [PATCH 6/9] Update plugins/ui/docs/components/switch.md Co-authored-by: Don --- plugins/ui/docs/components/switch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index 897f53511..226bbe208 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -14,7 +14,7 @@ my_switch_basic = ui.switch("Low power mode") Recommendations for creating switches: -1. Emphasized switches are ideal for forms and settings where the switch being noticed is crucial, while non-emphasized switches suit monochrome application panels to maintain focus on the canvas. +1. Emphasized switches are ideal for forms and settings where the switch being noticed is crucial, while non-emphasized switches suit monochrome application panels to maintain focus on the content. 2. Use a standalone switch when the context is clear without a text label, such as next to a panel's title to enable or disable panel options. 3. Use switches for activation and checkboxes for selection; switches cannot have an error state, unlike checkboxes. 4. When a switch represents multiple differing values, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them. From f9dc2a679b92acd60e7d5981736bdceee8b677a2 Mon Sep 17 00:00:00 2001 From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:01:55 -0400 Subject: [PATCH 7/9] Update plugins/ui/docs/components/switch.md Co-authored-by: Don --- plugins/ui/docs/components/switch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index 226bbe208..738783a95 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -17,7 +17,7 @@ Recommendations for creating switches: 1. Emphasized switches are ideal for forms and settings where the switch being noticed is crucial, while non-emphasized switches suit monochrome application panels to maintain focus on the content. 2. Use a standalone switch when the context is clear without a text label, such as next to a panel's title to enable or disable panel options. 3. Use switches for activation and checkboxes for selection; switches cannot have an error state, unlike checkboxes. -4. When a switch represents multiple differing values, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them. +4. When a switch represents multiple values from other switches, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them. 5. Switches can only be on or off; for partial states, use a checkbox as indeterminate switches are not accessible. Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related options, use a [`checkbox_group`](./checkbox_group.md) to manage multiple selections within a group. For when users need to provide specific information that cannot be communicated by a switch, consider using the `text` component. From a276bfbf85807b40273e0a8d02c82ba23ba44625 Mon Sep 17 00:00:00 2001 From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com> Date: Fri, 6 Sep 2024 10:02:05 -0400 Subject: [PATCH 8/9] Update plugins/ui/docs/components/switch.md Co-authored-by: Don --- plugins/ui/docs/components/switch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index 738783a95..0d89a1fc1 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -20,7 +20,7 @@ Recommendations for creating switches: 4. When a switch represents multiple values from other switches, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them. 5. Switches can only be on or off; for partial states, use a checkbox as indeterminate switches are not accessible. -Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related options, use a [`checkbox_group`](./checkbox_group.md) to manage multiple selections within a group. For when users need to provide specific information that cannot be communicated by a switch, consider using the `text` component. +Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. ## Value From a57987ef9f7f868614eb2b8ae763378cd0c045fc Mon Sep 17 00:00:00 2001 From: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com> Date: Mon, 9 Sep 2024 12:58:47 -0400 Subject: [PATCH 9/9] Update switch.md Typo; punctuation --- plugins/ui/docs/components/switch.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/plugins/ui/docs/components/switch.md b/plugins/ui/docs/components/switch.md index 0d89a1fc1..6a94deb50 100644 --- a/plugins/ui/docs/components/switch.md +++ b/plugins/ui/docs/components/switch.md @@ -15,10 +15,10 @@ my_switch_basic = ui.switch("Low power mode") Recommendations for creating switches: 1. Emphasized switches are ideal for forms and settings where the switch being noticed is crucial, while non-emphasized switches suit monochrome application panels to maintain focus on the content. -2. Use a standalone switch when the context is clear without a text label, such as next to a panel's title to enable or disable panel options. -3. Use switches for activation and checkboxes for selection; switches cannot have an error state, unlike checkboxes. +2. Use a standalone switch when the context is clear without a text label, such as next to a panel's title, to enable or disable panel options. +3. Use switches for activation and checkboxes for selection; unlike checkboxes, switches cannot have an error state. 4. When a switch represents multiple values from other switches, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them. -5. Switches can only be on or off; for partial states, use a checkbox as indeterminate switches are not accessible. +5. Switches can only be on or off; for partial states, use a checkbox, as indeterminate switches are not accessible. Consider using a [`checkbox`](./checkbox.md) for individual selections or when marking a single item as selected. @@ -58,7 +58,7 @@ my_switch_name_example = ui.form(ui.switch("Low Power Mode", name="power", value ## Labeling -The switch can be labeled by passing in a a child. If no label is provided, an `aria_label` must be provided to identify the control for accessibility purposes. +The switch can be labeled by passing in a child. If no label is provided, an `aria_label` must be provided to identify the control for accessibility purposes. ```python from deephaven import ui @@ -111,7 +111,7 @@ my_switch_is_disabled_example = ui.switch("Switch Label", is_disabled=True) ## Emphasized -The `is_emphasized` prop makes the fill of the switch be the user's accent color, adding a visual prominence to the selection. +The `is_emphasized` prop makes the switch's fill color the user's accent color, adding visual prominence to the selection. ```python from deephaven import ui @@ -123,7 +123,7 @@ my_switch_is_emphasized_example = ui.switch("Switch Label", is_emphasized=True) ## Read only -The `is_read_only` prop makes the switch read-only to prevent user interaction. This is different from setting the `is_disabled` prop since the switch remains focusable. +The `is_read_only` prop makes the switch read-only to prevent user interaction. This differs from setting the `is_disabled` prop since the switch remains focusable. ```python from deephaven import ui @@ -137,4 +137,4 @@ my_switch_is_read_only_example = ui.switch( ```{eval-rst} .. dhautofunction:: deephaven.ui.switch -``` \ No newline at end of file +```