Docs: DO-3248 docs fixes readme and components docstrings (#371)

* fix docs

* add missing import

* fix checkbox group cannot be undefined

* add to changelog

* adding images

* formatting

* update dropzone example to be more real world

packages/dara-components/changelog.md

@@ -3,7 +3,8 @@ title: Changelog
 ---
 
 ## NEXT
--   Fixes an issue where `Table` would sometimes convert timestamps in seconds as if they were in milliseconds.
+-   Fixed an issue where `Table` would sometimes convert timestamps in seconds as if they were in milliseconds.
+-   Fixed an issue where `CheckboxGroup` could not have an `undefined` value.
 
 ## 1.12.3
 

packages/dara-components/dara/components/common/__init__.py

@@ -33,7 +33,10 @@
 from dara.components.common.carousel import Carousel
 from dara.components.common.checkbox_group import CheckboxGroup
 from dara.components.common.code import Code
-from dara.components.common.component_select_list import ComponentSelectList
+from dara.components.common.component_select_list import (
+    ComponentItem,
+    ComponentSelectList,
+)
 from dara.components.common.datepicker import Datepicker
 from dara.components.common.dropzone import UploadDropzone
 from dara.components.common.form import Form
@@ -80,6 +83,7 @@
     'CheckboxGroup',
     'Code',
     'ComponentSelectList',
+    'ComponentItem',
     'Datepicker',
     'Direction',
     'Form',

packages/dara-components/dara/components/common/checkbox_group.py

@@ -37,7 +37,7 @@ class CheckboxGroup(FormComponent):
 
     ```python
     from dara.core import Variable
-    from dara.components.common import CheckboxGroup
+    from dara.components import CheckboxGroup
 
 
     CheckboxGroup(
@@ -50,25 +50,22 @@ class CheckboxGroup(FormComponent):
 
     ```python
     from dara.core import Variable
-    from dara.components.common import CheckboxGroup, Item
+    from dara.components import CheckboxGroup, Item
 
     CheckboxGroup(
         items=[Item(label='first',value=1), Item(label='second',value=2)],
-        value=Variable(1),
+        value=Variable([1]),
     )
     ```
 
     CheckboxGroup component with at most two values selectable at a time:
 
     ```python
     from dara.core import Variable
-    from dara.components.common import CheckboxGroup
-
-    var_to_update = Variable()
+    from dara.components import CheckboxGroup
 
     CheckboxGroup(
         items=['first', 'second', 'third', 'fourth', 'fifth'],
-        onchange=var_to_update.sync(),
         value=Variable(),
         select_max=2,
     )
@@ -81,11 +78,9 @@ class CheckboxGroup(FormComponent):
     from dara.components.common import CheckboxGroup
 
     var = Variable()
-    var_to_update = Variable()
 
     CheckboxGroup(
         items=['first', 'second', 'third', 'fourth', 'fifth'],
-        onchange=var_to_update.sync(),
         value=var,
         select_min=2,
         list_styling=True,

packages/dara-components/dara/components/common/component_select_list.py

@@ -31,7 +31,6 @@ class ComponentItem(BaseModel):
     component: ComponentInstanceType
 
 
-# TODO: update docs with examples once component is fixed
 class ComponentSelectList(LayoutComponent):
     """
     ![ComponentSelectList](../../../../docs/packages/dara-components/common/assets/ComponentSelectList.png)
@@ -41,11 +40,11 @@ class ComponentSelectList(LayoutComponent):
      A ComponentSelectList can be created via:
      ```python
      from dara.core import Variable
-     from dara.components.common import (
+     from dara.components import (
          ComponentSelectList,
+         ComponentItem,
          Text,
      )
-     from dara.components.common.component_select_list.component_select_list import ComponentItem
 
     ComponentSelectList(
          items=[

packages/dara-components/dara/components/common/dropzone.py

@@ -32,9 +32,35 @@
 
 class UploadDropzone(StyledComponentInstance):
     """
+    ![UploadDropzone](../../../../docs/packages/dara-components/common/assets/UploadDropzone.png)
+
     A component that exposes a dropzone for uploading files. Takes a DataVariable instance
     that will store the dataset uploaded and an on_drop action that is triggered when
     a file is successfully uploaded after being dropped or pasted.
+
+    ```python
+    import os
+    from dara.components import UploadDropzone
+
+    def handle_file_uploaded(file_data: bytes, file_name: str):
+        os.makedirs('data', exist_ok=True)
+        with open(os.path.join('data', file_name), 'wb') as f:
+            f.write(file_data)
+
+    UploadDropzone(
+        accept="image/png, image/jpeg",
+        resolver=handle_file_uploaded
+    )
+    ```
+
+    :param accept: optional comma-separated list of MIME-types or filename extensions accepted by the frontend; see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers for detail.
+        When not specified, defaults to accepting csv/xlsx; more specifically: `.csv, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/csv, text/x-csv, application/x-csv, text/comma-separated-values, text/x-comma-separated-values`
+    :param target: data variable storing the data
+    :param resolver: optional resolver accepting `bytes` and filename as a string
+        - if a target is specified, can be used to customise how the `bytes` received are turned into a `DataFrame`
+        - if a target is not specified, can be treated as a side effect function to run on the `bytes` received (to i.e. store on disk)
+    :param on_drop: optional action triggered when a file is successfully uploaded
+    :param enable_paste: determines if the component should listen for and handle paste events (e.g., CTRL+V or right-click and paste). When set to True, the component allows text to be pasted directly, creating a file from the pasted content. This feature is disabled by default to accommodate scenarios where pasting text is not intended or could interfere with the component's primary functionality.
     """
 
     js_module = '@darajs/components'
@@ -57,20 +83,6 @@ def __init__(
         enable_paste: Optional[bool] = False,
         **kwargs
     ):
-        """
-        A component that exposes a dropzone for uploading files. Takes a DataVariable instance
-        that will store the dataset uploaded and an on_drop action that is triggered when
-        a file is successfully uploaded after being dropped or pasted.
-
-        :param accept: optional comma-separated list of MIME-types or filename extensions accepted by the frontend; see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers for detail.
-            When not specified, defaults to accepting csv/xlsx; more specifically: `.csv, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/csv, text/x-csv, application/x-csv, text/comma-separated-values, text/x-comma-separated-values`
-        :param target: data variable storing the data
-        :param resolver: optional resolver accepting `bytes` and filename as a string
-            - if a target is specified, can be used to customise how the `bytes` received are turned into a `DataFrame`
-            - if a target is not specified, can be treated as a side effect function to run on the `bytes` received (to i.e. store on disk)
-        :param on_drop: optional action triggered when a file is successfully uploaded
-        :param enable_paste: determines if the component should listen for and handle paste events (e.g., CTRL+V or right-click and paste). When set to True, the component allows text to be pasted directly, creating a file from the pasted content. This feature is disabled by default to accommodate scenarios where pasting text is not intended or could interfere with the component's primary functionality.
-        """
         from dara.core.interactivity.any_data_variable import upload
         from dara.core.internal.registries import upload_resolver_registry
 

packages/dara-components/dara/components/smart/chat/chat.py

@@ -25,6 +25,8 @@
 
 class Chat(StyledComponentInstance):
     """
+    ![Chat](../../../../docs/packages/dara-components/common/assets/Chat.png)
+
     A Chat component which can be added anywhere in your page. When added a chat button will appear in the bottom right
     of your page and when clicked a chat sidebar will appear. This can be added on a page by page basis, with the chat
     state being store in a Variable.

packages/dara-components/js/common/checkbox-group/checkbox-group.tsx

@@ -64,7 +64,7 @@ function CheckboxGroup(props: CheckboxGroupProps): JSX.Element {
             selectMax={props.select_max}
             selectMin={props.select_min}
             style={style}
-            values={items.filter((item: Item) => value.includes(item.value))}
+            values={items.filter((item: Item) => value?.includes(item.value))}
         />
     );
 }

packages/dara-core/README.md

@@ -79,6 +79,21 @@ This repository covers the Dara Application Framework first-party packages.
 - `dara-components`: Components for the Dara Framework.
 - `create-dara-app`: A CLI tool for creating new Dara applications.
 
+And the supporting UI packages and tools.
+
+- `eslint-config` - base ESLint configuration
+- `prettier-config` - base Prettier configuration
+- `stylelint-config` - base Stylelint configuration
+- `styled-components` - styled-components theme
+- `ui-causal-graph-editor` - causal graph editor component
+- `ui-code-editor` - code editor component
+- `ui-components` - base UI components
+- `ui-hierarchy-viewer` - hierarchy viewer component
+- `ui-icons` - icon components for Dara packages
+- `ui-notifications` - notification components
+- `ui-utils` - miscellaneous utility functions
+- `ui-widgets` - widget components
+
 More information on the repository structure can be found in the [CONTRIBUTING.md](https://github.com/causalens/dara/blob/master/CONTRIBUTING.md) file.
 
 ## License