Add more docs for the table data hooks

- Add explanation for sentinel object
- Add examples with null value

plugins/ui/docs/hooks/use_cell_data.md

@@ -24,7 +24,76 @@ In the above example, `ui_table_first_cell` is a component that listens to the l
 1. **Use `use_cell_data` for listening to table updates**: If you need to listen to a table for one cell of data, use `use_cell_data`.
 2. **Use table operations to filter to one cell**: Because `use_cell_data` always uses the top-left cell of the table, you can filter your table to determine what cell to listen to. If your table has multiple rows and columns, use table operations such as `.where` and `.select` to filter to the desired cell.
 
-## API Reference
+## Empty tables
+
+If the table is empty, the value of `cell_value` will return the value of `None`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_first_cell(table):
+    cell_value = ui.use_cell_data(table)
+    if cell_value is None:
+        return ui.heading("No data yet.")
+    return ui.heading(f"The first cell value is {cell_value}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_first_cell = ui_table_first_cell(
+    time_table("PT1s", start_time=start_time).tail(1)
+)
+```
+
+You can optionally provide a `sentinel` value to return when the table is empty instead.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_first_cell(table):
+    cell_value = ui.use_cell_data(table, sentinel="No data yet.")
+    return ui.heading(f"Cell value: {cell_value}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_first_cell = ui_table_first_cell(
+    time_table("PT1s", start_time=start_time).tail(1)
+)
+```
+
+## Null values
+
+If the table cell is a `null` value, the value of `cell_value` will be `pandas.NA`. You can check for `null` values using the `pandas.isna` function.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+import pandas as pd
+
+
+@ui.component
+def ui_table_first_cell(table):
+    cell_value = ui.use_cell_data(table)
+    if cell_value is None:
+        return ui.heading("No data yet.")
+    if pd.isna(cell_value):
+        return ui.heading("Cell value is null.")
+    return ui.heading(f"Cell value: {cell_value}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_first_cell = ui_table_first_cell(
+    time_table("PT1s", start_time=start_time)
+    .update("x=i%2==0?null:i")
+    .select("x")
+    .tail(1)
+)
+```
 
 ```{eval-rst}
 .. dhautofunction:: deephaven.ui.use_cell_data

plugins/ui/docs/hooks/use_column_data.md

@@ -24,6 +24,7 @@ In the above example, `ui_table_column` is a component that listens to the last
 1. **Use `use_column_data` for listening to table updates**: If you need to listen to a table for one column of data, use `use_column_data`.
 2. **Use table operations to filter to one column**: If your table has multiple rows and columns, use table operations such as `.where` and `.select` to filter to the column you want to listen to. `use_column_data` always uses the first column of the table.
 3. **Do not use `use_column_data` with [`list_view`](../components/list_view.md) or [`picker`](../components/picker.md)**: Some components are optimized to work with large tables of data, and will take a table passed in directly as their data source, only pulling in the options currently visible to the user. In those cases, pass the table directly to the component, otherwise you will fetch the entire column of data unnecessarily.
+4. **Pass a Sentinel value to `use_column_data`**: If you want to use a default value when the table is empty, pass a sentinel value to `use_column_data`. The default sentinel value is `None`, which is returned when the table is empty.
 
 ## Tab switcher with `use_column_data`
 
@@ -54,6 +55,72 @@ _stocks = dx.data.stocks()
 table_tabs = ui_table_tabs(_stocks, "Exchange")
 ```
 
+## Empty tables
+
+If the table is empty, the value of `column_data` will return the value of `None`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_column(table):
+    column_data = ui.use_column_data(table)
+    if column_data is None:
+        return ui.heading("No data yet.")
+    return ui.heading(f"Column data: {column_data}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_column = ui_table_column(time_table("PT1s", start_time=start_time).tail(5))
+```
+
+You can optionally provide a `sentinel` value to return when the table is empty instead.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_column(table):
+    column_data = ui.use_column_data(table, sentinel="No data yet.")
+    return ui.heading(f"Column data: {column_data}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_column = ui_table_column(time_table("PT1s", start_time=start_time).tail(5))
+```
+
+## Null values
+
+If the table has a `null` value in the first column, the value for that cell will be `pandas.NA`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_column(table):
+    column_data = ui.use_column_data(table)
+    if column_data is None:
+        return ui.heading("No data yet.")
+    if pd.isna(column_data[0]):
+        return ui.heading("Value of first cell is null.")
+    return ui.heading(f"Column data: {column_data}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_column = ui_table_column(
+    time_table("PT1s", start_time=start_time)
+    .update("x=i%2==0?null:i")
+    .select("x")
+    .tail(4)
+)
+```
+
 ## API Reference
 
 ```{eval-rst}

plugins/ui/docs/hooks/use_row_data.md

@@ -25,7 +25,75 @@ In the above example, `ui_table_row` is a component that listens to a table and
 
 1. **Use `use_row_data` for listening to table updates**: If you need to listen to a table for one row of data, use `use_row_data`.
 2. **Use table operations to filter to one row**: If your table has multiple rows and columns, use table operations such as `.where`, `.select` and `.reverse` to filter to the row you want to listen to. `use_row_data` always uses the first row of the table.
-3. **Pass a Sentinel value to `use_row_data`**: If you want to use a default value when the table is empty, pass a sentinel value to `use_row_data`. The default sentinel value is `()`, which is returned when the table is empty.
+3. **Pass a Sentinel value to `use_row_data`**: If you want to use a default value when the table is empty, pass a sentinel value to `use_row_data`. The default sentinel value is `None`, which is returned when the table is empty.
+
+## Empty tables
+
+If the table is empty, the value of `row_data` will return the value of `None`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_row(table):
+    row_data = ui.use_row_data(table)
+    if row_data is None:
+        return ui.heading("No data yet.")
+    return ui.heading(f"Row data: {row_data}.")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_row = ui_table_row(
+    time_table("PT1s", start_time=start_time).update("x=i").tail(1)
+)
+```
+
+You can optionally provide a `sentinel` value to return when the table is empty instead.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_row(table):
+    row_data = ui.use_row_data(table, sentinel={"Timestamp": "No data yet."})
+    return ui.heading(f"Row data: {row_data}. Value of 'x' is {row_data['x']}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_row = ui_table_row(
+    time_table("PT1s", start_time=start_time).update("x=i").tail(1)
+)
+```
+
+## Null values
+
+If the table has a `null` value in the first row, the value for that cell will be `pandas.NA`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+import pandas as pd
+
+
+@ui.component
+def ui_table_row(table):
+    row_data = ui.use_row_data(table)
+    if row_data is None:
+        return ui.heading("No data yet.")
+    if pd.isna(row_data["x"]):
+        return ui.heading("Value of 'x' is null.")
+    return ui.heading(f"Row data: {row_data}. Value of 'x' is {row_data['x']}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_row = ui_table_row(
+    time_table("PT1s", start_time=start_time).update("x=i%2==0?null:i").tail(1)
+)
+```
 
 ## API reference
 

plugins/ui/docs/hooks/use_row_list.md

@@ -25,7 +25,75 @@ In the above example, `ui_table_row_list` is a component that listens to a table
 
 1. **Use `use_row_list` for listening to table updates**: If you need to listen to a table for one row of data as a list, use `use_row_list`.
 2. **Use table operations to filter to one row**: If your table has multiple rows and columns, use table operations such as `.where`, `.select` and `.reverse` to filter to the row you want to listen to. `use_row_list` always uses the first row of the table.
-3. **Pass a Sentinel value to `use_row_list`**: If you want to use a default value when the table is empty, pass a sentinel value to `use_row_list`. The default sentinel value is `()`, which is returned when the table is empty.
+3. **Pass a Sentinel value to `use_row_list`**: If you want to use a default value when the table is empty, pass a sentinel value to `use_row_list`. The default sentinel value is `None`, which is returned when the table is empty.
+
+## Empty tables
+
+If the table is empty, the value of `row_list` will return the value of `None`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_row_list(table):
+    row_list = ui.use_row_list(table)
+    if row_list is None:
+        return ui.heading("No data yet.")
+    return ui.heading(f"Row list: {row_list}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_row_list = ui_table_row_list(
+    time_table("PT1s", start_time=start_time).update("x=i").tail(1)
+)
+```
+
+You can optionally provide a `sentinel` value to return when the table is empty instead.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_row_list(table):
+    row_list = ui.use_row_list(table, sentinel="No data yet.")
+    return ui.heading(f"Row list: {row_list}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_row_list = ui_table_row_list(
+    time_table("PT1s", start_time=start_time).update("x=i").tail(1)
+)
+```
+
+## Null values
+
+If the table has a `null` value in the first row, the value for that cell will be `pandas.NA`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+import pandas as pd
+
+
+@ui.component
+def ui_table_row_list(table):
+    row_list = ui.use_row_list(table)
+    if row_list is None:
+        return ui.heading("No data yet.")
+    if pd.isna(row_list[1]):
+        return ui.heading("x is null value.")
+    return ui.heading(f"Row list: {row_list}. Value of X is {row_list[1]}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_row_list = ui_table_row_list(
+    time_table("PT1s", start_time=start_time).update("x=i%2==0?null:i").tail(1)
+)
+```
 
 ## API reference
 

plugins/ui/docs/hooks/use_table_data.md

@@ -23,6 +23,74 @@ In the above example, `ui_table_data` is a component that listens to the last 5
 
 1. **Use `use_table_data` for listening to table updates**: If you need to listen to a table for all the data, use `use_table_data`.
 2. **Use table operations to filter to the data you want**: If your table has multiple rows and columns, use table operations such as `.where` and `.select` to filter to the data you want to listen to.
+3. **Pass a Sentinel value to `use_table_data`**: If you want to use a default value when the table is empty, pass a sentinel value to `use_table_data`. The default sentinel value is `None`, which is returned when the table is empty.
+
+## Empty tables
+
+If the table is empty, the value of `table_data` will return the value of `None`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_data(table):
+    table_data = ui.use_table_data(table)
+    if table_data is None:
+        return ui.heading("No data yet.")
+    return ui.heading(f"Table data: {table_data}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_data = ui_table_data(
+    time_table("PT1s", start_time=start_time).update("x=i").tail(5)
+)
+```
+
+You can optionally provide a `sentinel` value to return when the table is empty instead.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_data(table):
+    table_data = ui.use_table_data(table, sentinel="No data yet.")
+    return ui.heading(f"Table data: {table_data}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_data = ui_table_data(
+    time_table("PT1s", start_time=start_time).update("x=i").tail(5)
+)
+```
+
+## Null values
+
+If the table has null values, they will be represented in the data with `pandas.NA`.
+
+```python
+from deephaven import time_table, ui
+import datetime as dt
+
+
+@ui.component
+def ui_table_data(table):
+    table_data = ui.use_table_data(table)
+    if table_data is None:
+        return ui.heading("No data yet.")
+    if pd.isna(table_data["x"][0]):
+        return ui.heading("First value of 'x' is null.")
+    return ui.heading(f"Table data: {table_data}")
+
+
+start_time = dt.datetime.now() + dt.timedelta(seconds=2)
+table_data = ui_table_data(
+    time_table("PT1s", start_time=start_time).update("x=i%2==0?null:i").tail(3)
+)
+```
 
 ## API Reference