From a11288b7d4c90102859e6ec9f6de3ee9506f069c Mon Sep 17 00:00:00 2001
From: Akshat Jawne <akshatjawne@gmail.com>
Date: Thu, 5 Sep 2024 09:50:59 -0400
Subject: [PATCH 1/9] docs: ui.text_field

---
 plugins/ui/docs/components/text_field.md | 264 +++++++++++++++++++++++
 1 file changed, 264 insertions(+)
 create mode 100644 plugins/ui/docs/components/text_field.md

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
new file mode 100644
index 000000000..cd1e331b1
--- /dev/null
+++ b/plugins/ui/docs/components/text_field.md
@@ -0,0 +1,264 @@
+# Text Field
+
+Text fields are single-line text inputs, ideal for cases where users have a smaller amount of text to enter.
+
+## Example
+
+```python
+from deephaven import ui
+
+
+my_text_field_basic = ui.text_field(
+    label="Description", on_change=lambda value: print(f"Text changed to {value}")
+)
+```
+
+## UI Recommendations
+
+Recommendations for creating text fields:
+
+1. Every text field should have a [label](#labeling) specified. Without one, the text field 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. Text field labels and help text should follow sentence casing.
+3. A text field should not use `is_quiet` styling if it has a fixed height, given that the field underline may be too far from the text to be considered part of the component.
+4. Use help text to provide instructions on input format, content, and requirements; the help text should not restate the same information as the label, or prompt a user to interact with the text field.
+5. Dynamically switch between help text and error messages based on input, ensuring both convey essential input requirements.
+
+Consider using [`text_area`](./text_area.md) for cases where multiline input is required.
+
+
+## Value
+
+A text field's value is empty by default, but an initial, uncontrolled, value can be set using the `default_value` prop, or, a controlled value can be set via the `value` prop.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_value_examples():
+    value, set_value = ui.use_state("sample_account@email.com")
+    return [
+        ui.text_field(
+            label="Email (Uncontrolled)", default_value="sample_account@email.com"
+        ),
+        ui.text_field(label="Email (controlled)", value=value, on_change=set_value),
+    ]
+
+
+my_text_field_value_examples = ui_text_field_value_examples()
+```
+
+## HTML Forms
+
+Text field'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_text_field_name_example = ui.form(
+    ui.text_field(label="Email", name="email", type="email")
+)
+```
+
+## Labeling
+
+To provide a visual label for the text field, use the `label` prop. To indicate that the text area is mandatory, use the `is_required` prop.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_is_required_examples():
+    return [
+        ui.text_field(label="Address"),
+        ui.text_field(label="Address", is_required=True),
+    ]
+
+
+my_text_field_is_required_example = ui_text_field_is_required_examples()
+```
+
+By setting `is_required` to True, the `necessity_indicator` is set to "icon" by default, but this can be changed. Also, the `necessity_indicator` can be used indepdendently to indicate that the text field is optional.
+
+When the `necessity_indicator` prop is set to "label", a localized string will be generated for "(required)" or "(optional)" automatically.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_necessity_indicator_examples():
+    return [
+        ui.text_field(label="Address", is_required=True, necessity_indicator="label"),
+        ui.text_field(label="Address", necessity_indicator="label"),
+    ]
+
+
+my_text_field_necessity_indicator_examples = (
+    ui_text_field_necessity_indicator_examples()
+)
+```
+
+
+## Events
+
+The `on_change` property is triggered whenever the value in the text field is edited.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_on_change_example():
+    value, set_value = ui.use_state("")
+    return [
+        ui.text_field(label="Your text", value=value, on_change=set_value),
+        ui.text(f"Text has been changed to: {value}"),
+    ]
+
+
+my_text_field_on_change_example = ui_text_field_on_change_example()
+```
+
+
+## Quiet State
+
+The `is_quiet` prop makes text fields "quiet". This can be useful when the text area and its corresponding styling should not distract users from surrounding content.
+
+```python
+from deephaven import ui
+
+
+my_text_field_is_quiet_example = ui.text_field(label="Email", is_quiet=True)
+```
+
+
+## Disabled State
+
+The `is_disabled` prop disables text fields to prevent user interaction. This is useful when the text field should be visible but not available for input.
+
+```python
+from deephaven import ui
+
+
+my_text_field_is_disabled_example = ui.text_field(label="Email", is_disabled=True)
+```
+
+
+## Read only
+
+The `is_read_only` prop makes text fields read-only to prevent user interaction. This is different than setting the `is_disabled` prop since the text field remains focusable, and the contents of the text field remain visible.
+
+```python
+from deephaven import ui
+
+
+my_text_field_is_read_only_example = ui.text_field(
+    label="Email", default_value="sample@email.com", is_read_only=True
+)
+```
+
+
+## Label position
+
+By default, the position of a text field's label is above the text field, but it can be changed to the side using the `label_position` prop.
+
+While labels can be placed either on top or on the side of the text field, top labels are the default recommendation. Top labels work better with longer copy, localization, and responsive layouts. Side labels are more useful when vertical space is limited.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_label_position_examples():
+    return [
+        ui.text_field(label="Sample Label"),
+        ui.text_field(label="Sample Label", label_position="side", label_align="start"),
+    ]
+
+
+my_text_field_label_position_examples = ui_text_field_label_position_examples()
+```
+
+
+## Help text
+
+A text field can have both a `description` and an `error_message`. The description remains visible at all times, except when the `validation_state` is set to "invalid" and an error message is present. Use the error message to offer specific guidance on how to correct the input.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_help_text_examples():
+    return [
+        ui.text_field(
+            label="Comment",
+            default_value="Awesome!",
+            validation_state="valid",
+            description="Enter a comment.",
+        ),
+        ui.text_field(
+            label="Comment",
+            validation_state="invalid",
+            error_message="Empty input is not allowed.",
+        ),
+    ]
+
+
+my_text_field_help_text_examples = ui_text_field_help_text_examples()
+```
+
+
+## Contextual Help
+
+Using the `contextual_help` prop, a `ui.contextual_help` can be placed next to the label to provide additional information about the text field.
+
+```python
+from deephaven import ui
+
+
+my_text_field_contextual_help_example = ui.text_field(
+    label="Email",
+    contextual_help=ui.contextual_help(
+        ui.heading("Information about emails"),
+        ui.content(
+            "Electronic mail, commonly shortened to 'email', is a method that uses electronic devices to deliver messages across networks"
+        ),
+    ),
+)
+```
+
+
+## Custom width
+
+The `width` prop adjusts the width of a text field, and the `max_width` prop enforces a maximum width.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_width_examples():
+    return [
+        ui.text_field(label="Email", width="size-3600"),
+        ui.text_field(label="Email", width="size-3600", max_width="100%"),
+    ]
+
+
+my_text_field_width_examples = ui_text_field_width_examples()
+```
+
+
+## API Reference
+```{eval-rst}
+.. dhautofunction:: deephaven.ui.text_field
+```
+
+
+
+
+
+

From e6a70705dc35295f386e9dde3dbaec193f8bc7bd Mon Sep 17 00:00:00 2001
From: Akshat Jawne <akshatjawne@gmail.com>
Date: Thu, 5 Sep 2024 09:52:04 -0400
Subject: [PATCH 2/9] get rid of empty space

---
 plugins/ui/docs/components/text_field.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index cd1e331b1..abc6c35b1 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -256,9 +256,3 @@ my_text_field_width_examples = ui_text_field_width_examples()
 ```{eval-rst}
 .. dhautofunction:: deephaven.ui.text_field
 ```
-
-
-
-
-
-

From c9d62f60fe8f2abfa46b8a56e27ad63d2751416b Mon Sep 17 00:00:00 2001
From: Akshat Jawne <akshatjawne@gmail.com>
Date: Thu, 5 Sep 2024 10:09:04 -0400
Subject: [PATCH 3/9] make changes according to review

---
 plugins/ui/docs/components/text_field.md             | 6 +++---
 plugins/ui/src/deephaven/ui/components/text_field.py | 3 +++
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index abc6c35b1..00ca9f882 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -19,7 +19,7 @@ Recommendations for creating text fields:
 
 1. Every text field should have a [label](#labeling) specified. Without one, the text field 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. Text field labels and help text should follow sentence casing.
-3. A text field should not use `is_quiet` styling if it has a fixed height, given that the field underline may be too far from the text to be considered part of the component.
+3. A text field should not use `is_quiet` styling if it has a fixed height, given that the line underneath the field may be too far from the text to be considered part of the component.
 4. Use help text to provide instructions on input format, content, and requirements; the help text should not restate the same information as the label, or prompt a user to interact with the text field.
 5. Dynamically switch between help text and error messages based on input, ensuring both convey essential input requirements.
 
@@ -28,7 +28,7 @@ Consider using [`text_area`](./text_area.md) for cases where multiline input is
 
 ## Value
 
-A text field's value is empty by default, but an initial, uncontrolled, value can be set using the `default_value` prop, or, a controlled value can be set via the `value` prop.
+A text field's value is empty by default, but the `default_value` prop can set an initial, uncontrolled value, or a controlled value can be set via the `value` prop.
 
 ```python
 from deephaven import ui
@@ -80,7 +80,7 @@ def ui_text_field_is_required_examples():
 my_text_field_is_required_example = ui_text_field_is_required_examples()
 ```
 
-By setting `is_required` to True, the `necessity_indicator` is set to "icon" by default, but this can be changed. Also, the `necessity_indicator` can be used indepdendently to indicate that the text field is optional.
+By setting `is_required` to True, the `necessity_indicator` is set to "icon" by default, but this can be changed. The `necessity_indicator` can also be used independently to indicate that the text field is optional.
 
 When the `necessity_indicator` prop is set to "label", a localized string will be generated for "(required)" or "(optional)" automatically.
 
diff --git a/plugins/ui/src/deephaven/ui/components/text_field.py b/plugins/ui/src/deephaven/ui/components/text_field.py
index 524626cd2..130c41f79 100644
--- a/plugins/ui/src/deephaven/ui/components/text_field.py
+++ b/plugins/ui/src/deephaven/ui/components/text_field.py
@@ -186,6 +186,9 @@ def text_field(
         aria_errormessage: The id of the element that provides an error message 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 text field element.
     """
 
     return component_element(

From 3de973f42a183163d97f3801fccee2b61feecdc4 Mon Sep 17 00:00:00 2001
From: Akshat Jawne <akshatjawne@gmail.com>
Date: Fri, 6 Sep 2024 10:13:45 -0400
Subject: [PATCH 4/9] make changes based on review

---
 plugins/ui/docs/components/text_field.md      | 34 ++++++++++---------
 .../src/deephaven/ui/components/text_field.py |  4 +--
 2 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index 00ca9f882..a0fc01bb6 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -19,11 +19,11 @@ Recommendations for creating text fields:
 
 1. Every text field should have a [label](#labeling) specified. Without one, the text field 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. Text field labels and help text should follow sentence casing.
-3. A text field should not use `is_quiet` styling if it has a fixed height, given that the line underneath the field may be too far from the text to be considered part of the component.
-4. Use help text to provide instructions on input format, content, and requirements; the help text should not restate the same information as the label, or prompt a user to interact with the text field.
-5. Dynamically switch between help text and error messages based on input, ensuring both convey essential input requirements.
+3. Use help text to provide instructions on input format, content, and requirements; the help text should not restate the same information as the label, or prompt a user to interact with the text field.
+4. Dynamically switch between help text and error messages based on input, ensuring both convey essential input requirements.
 
-Consider using [`text_area`](./text_area.md) for cases where multiline input is required.
+
+Use [`text_area`](./text_area.md) for cases where multiline input is required.
 
 
 ## Value
@@ -36,12 +36,12 @@ from deephaven import ui
 
 @ui.component
 def ui_text_field_value_examples():
-    value, set_value = ui.use_state("sample_account@email.com")
+    value, set_value = ui.use_state("Aardvark")
     return [
+        ui.text_field(label="Favorite animal (Uncontrolled)", default_value="Aardvark"),
         ui.text_field(
-            label="Email (Uncontrolled)", default_value="sample_account@email.com"
+            label="Favorite animal (controlled)", value=value, on_change=set_value
         ),
-        ui.text_field(label="Email (controlled)", value=value, on_change=set_value),
     ]
 
 
@@ -63,7 +63,7 @@ my_text_field_name_example = ui.form(
 
 ## Labeling
 
-To provide a visual label for the text field, use the `label` prop. To indicate that the text area is mandatory, use the `is_required` prop.
+To provide a visual label for the text field, use the `label` prop. To indicate that the text field is mandatory, use the `is_required` prop.
 
 ```python
 from deephaven import ui
@@ -131,7 +131,7 @@ The `is_quiet` prop makes text fields "quiet". This can be useful when the text
 from deephaven import ui
 
 
-my_text_field_is_quiet_example = ui.text_field(label="Email", is_quiet=True)
+my_text_field_is_quiet_example = ui.text_field(label="Favorite animal", is_quiet=True)
 ```
 
 
@@ -143,7 +143,9 @@ The `is_disabled` prop disables text fields to prevent user interaction. This is
 from deephaven import ui
 
 
-my_text_field_is_disabled_example = ui.text_field(label="Email", is_disabled=True)
+my_text_field_is_disabled_example = ui.text_field(
+    label="Favorite animal", is_disabled=True
+)
 ```
 
 
@@ -156,7 +158,7 @@ from deephaven import ui
 
 
 my_text_field_is_read_only_example = ui.text_field(
-    label="Email", default_value="sample@email.com", is_read_only=True
+    label="Favorite animal", default_value="Panda", is_read_only=True
 )
 ```
 
@@ -221,11 +223,11 @@ from deephaven import ui
 
 
 my_text_field_contextual_help_example = ui.text_field(
-    label="Email",
+    label="Favorite animal",
     contextual_help=ui.contextual_help(
-        ui.heading("Information about emails"),
+        ui.heading("Information about animals"),
         ui.content(
-            "Electronic mail, commonly shortened to 'email', is a method that uses electronic devices to deliver messages across networks"
+            "Animals are classified into two main categories – the vertebrates and the invertebrates."
         ),
     ),
 )
@@ -243,8 +245,8 @@ from deephaven import ui
 @ui.component
 def ui_text_field_width_examples():
     return [
-        ui.text_field(label="Email", width="size-3600"),
-        ui.text_field(label="Email", width="size-3600", max_width="100%"),
+        ui.text_field(label="Favorite animal", width="size-3600"),
+        ui.text_field(label="Favorite animal", width="size-3600", max_width="100%"),
     ]
 
 
diff --git a/plugins/ui/src/deephaven/ui/components/text_field.py b/plugins/ui/src/deephaven/ui/components/text_field.py
index 130c41f79..cd69dbb43 100644
--- a/plugins/ui/src/deephaven/ui/components/text_field.py
+++ b/plugins/ui/src/deephaven/ui/components/text_field.py
@@ -180,8 +180,8 @@ def text_field(
         aria_active_descendant: Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
         aria_auto_complete: Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
         aria_label: The label for the element.
-        aria_labelled_by: The id of the element that labels the current element.
-        aria_described_by: The id of the element that describes the current 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.
         aria_errormessage: The id of the element that provides an error message for the current element.
         UNSAFE_class_name: A CSS class to apply to the element.

From 25ead105122b0dc56664d11217ca5ed54fcfbff0 Mon Sep 17 00:00:00 2001
From: Akshat Jawne <akshatjawne@gmail.com>
Date: Fri, 6 Sep 2024 10:20:48 -0400
Subject: [PATCH 5/9] add missing comment for aria_haspopup

---
 plugins/ui/src/deephaven/ui/components/text_field.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/ui/src/deephaven/ui/components/text_field.py b/plugins/ui/src/deephaven/ui/components/text_field.py
index cd69dbb43..4a1972614 100644
--- a/plugins/ui/src/deephaven/ui/components/text_field.py
+++ b/plugins/ui/src/deephaven/ui/components/text_field.py
@@ -179,6 +179,7 @@ def text_field(
         exclude_from_tab_order: Whether the element should be excluded from the tab order.
         aria_active_descendant: Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
         aria_auto_complete: Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
+        aria_haspopup: Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
         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.

From 750f305238e9455d58b26920e07add17801cae98 Mon Sep 17 00:00:00 2001
From: Akshat Jawne <akshatjawne@gmail.com>
Date: Tue, 10 Sep 2024 11:01:11 -0400
Subject: [PATCH 6/9] add input types example

---
 plugins/ui/docs/components/text_field.md | 25 ++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index a0fc01bb6..5db9c574c 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -123,6 +123,31 @@ my_text_field_on_change_example = ui_text_field_on_change_example()
 ```
 
 
+## Input Types
+
+The `type` prop can be used to change the type of text field to render to suit different input requirements. 
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_text_field_input_types_examples():
+    return ui.form(
+        ui.text_field(label="Name", type="text", is_required=True),
+        ui.text_field(label="Personal Website", type="url", is_required=True),
+        ui.text_field(label="Phone", type="tel", is_required=True),
+        ui.text_field(label="Email", type="email", is_required=True),
+        ui.text_field(label="Password", type="password", is_required=True),
+        ui.text_field(label="Search Bar", type="search"),
+        validation_behavior="native",
+    )
+
+
+my_text_field_input_types_examples = ui_text_field_input_types_examples()
+```
+
+
 ## Quiet State
 
 The `is_quiet` prop makes text fields "quiet". This can be useful when the text area and its corresponding styling should not distract users from surrounding content.

From 97228cdcf889a4dc2e69b5adf10bdf6b81828972 Mon Sep 17 00:00:00 2001
From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com>
Date: Wed, 11 Sep 2024 09:49:09 -0400
Subject: [PATCH 7/9] Update plugins/ui/docs/components/text_field.md

Co-authored-by: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com>
---
 plugins/ui/docs/components/text_field.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index 5db9c574c..4f067f9aa 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -1,6 +1,6 @@
 # Text Field
 
-Text fields are single-line text inputs, ideal for cases where users have a smaller amount of text to enter.
+Text fields are single-line text inputs, ideal for cases where users have a small amount of text to enter.
 
 ## Example
 

From 20fabab120b4b28a4c036eec7df49f815937be9b Mon Sep 17 00:00:00 2001
From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com>
Date: Wed, 11 Sep 2024 09:49:17 -0400
Subject: [PATCH 8/9] Update plugins/ui/docs/components/text_field.md

Co-authored-by: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com>
---
 plugins/ui/docs/components/text_field.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index 4f067f9aa..029d7ce2c 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -50,7 +50,7 @@ my_text_field_value_examples = ui_text_field_value_examples()
 
 ## HTML Forms
 
-Text field's can support a `name` prop for integration with HTML forms, allowing for easy identification of a value on form submission.
+Text fields 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

From 220e7eaa3cd76a74e1e1c7c1bf3abd63fbd4cba1 Mon Sep 17 00:00:00 2001
From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com>
Date: Wed, 11 Sep 2024 09:49:25 -0400
Subject: [PATCH 9/9] Update plugins/ui/docs/components/text_field.md

Co-authored-by: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com>
---
 plugins/ui/docs/components/text_field.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/ui/docs/components/text_field.md b/plugins/ui/docs/components/text_field.md
index 029d7ce2c..a07db7fe4 100644
--- a/plugins/ui/docs/components/text_field.md
+++ b/plugins/ui/docs/components/text_field.md
@@ -125,7 +125,7 @@ my_text_field_on_change_example = ui_text_field_on_change_example()
 
 ## Input Types
 
-The `type` prop can be used to change the type of text field to render to suit different input requirements. 
+The `type` prop changes the type of text field that is rendered to suit different input requirements. 
 
 ```python
 from deephaven import ui