0.2.0 - update the project descriptions

Update the project description for explaining the usages of the React codes.

Author: cainmagi

CONTRIBUTING.md

@@ -13,8 +13,13 @@ This guide shows how to compile and test this project. Anyone who want to contri
 * Review our [code of conduct :memo:](./CODE_OF_CONDUCT.md) before contributing to this project.
 
 * The metadata of the project is defined in `pyproject.toml` and `package.json`. Modifying `package.json` will not automatically update `pyproject.toml`. Therefore, users need to ensure changes for both files if any part of the metadata needs to be changed.
+* The React source files are in the `src/lib/` folder. These codes are formatted by [`pretteir`:hammer:][tool-prettier].
 
-* The Python codes are in the package `dash_file_cache/` folder. These codes are formatted by [`black`:hammer:][tool-black]. Note that the automatically generated files (may be introduced in the future) will not be formatted.
+* The Python codes are in the package `dash_file_cache/` folder. These codes are formatted by [`black`:hammer:][tool-black].
+
+* The Python Compoenent codes are in the sub-package `dash_file_cache/components/` folder. Note that the automatically generated files like `_imports_.py` and `Downloader.py` will not be formatted.
+
+* Currently, we do not provide the React demo application. Therefore, please do not use `yarn start`.
 
 * The Dash demo apps are stored in `examples/`. These demos show the usages this package in different cases.
 
@@ -24,7 +29,11 @@ This guide shows how to compile and test this project. Anyone who want to contri
 
 * The tool configurations for `pytest`, `black`, and `pyright` are defined in `pyproject.toml`. However, the configurations for `flake8`, `pylint`, and `prettier` are still kept in their corresponding configurations files.
 
-* Remember to use [`black`:hammer:][tool-black] to format any modified Python codes. [Review your code :memo:](./review_checklist.md) before sending the pull request.
+* If any custom styles are defined but not imported as a part of the react codes, please add these custom CSS files into the distribution folder (`dash_json_grid`).
+    * Make sure that they are referenced in `MANIFEST.in` so that they get properly included when you're ready to publish your component.
+    * Make sure the stylesheets are added to the `_css_dist` dict in `dash_json_grid/__init__.py` so dash will serve them automatically when the component suite is requested.
+
+* Remember to use [`black`:hammer:][tool-black] and [`pretteir`:hammer:][tool-prettier] to format any modified Python and React codes, respectively. [Review your code :memo:](./review_checklist.md) before sending the pull request.
 
 ### 2. Work with Docker
 
@@ -119,6 +128,13 @@ At the **bottom left** corner, you should be able to see the name of the current
 
 Now you will be able to start the development. You can do the following things to test the codes.
 
+* Build the component
+
+    ``` sh
+    yarn install
+    yarn build
+    ```
+
 * Run the `pytest`:
 
     ``` sh
@@ -188,7 +204,7 @@ The following steps will help you configure the environment with `conda`:
 1. Create the environment
 
     ``` sh
-    conda create -c conda-forge -n dashdev-dfc python=3.12 wheel setuptools
+    conda create -c conda-forge -n dashdev-dfc python=3.12 wheel setuptools nodejs yarn
     ```
 
 2. Enter the environment
@@ -203,6 +219,13 @@ The following steps will help you configure the environment with `conda`:
     pip install -r requirements.txt -r requirements-dev.txt -r tests/requirements.txt
     ```
 
+4. Install the Node.js dependencies and build the first version.
+
+    ``` sh
+    yarn install
+    yarn build
+    ```
+
 #### 3.3. Run the test
 
 To verify whether you have correctly prepared the environment or not, you can run the following command:
@@ -215,6 +238,13 @@ python -m pytest --headless --with-dash
 
 You can do the following things to test the codes.
 
+* Build the component
+
+    ``` sh
+    yarn install
+    yarn build
+    ```
+
 * Run the `pytest`:
 
     ``` sh

Changelog.md

@@ -27,6 +27,7 @@
 4. Update the `docker` configurations.
 5. Remove the unused command `yarn start` from the `package.json`.
 6. Update the project configurations to the newest standard.
+7. Update the project descriptions for explaining the usages of the React codes.
 
 ### 0.1.2 @ 10/13/2024
 

README.md

@@ -20,7 +20,7 @@ The data cache enables the following features:
 1. Load a server-side file dynamically and send the file to users (the frontend).
 2. Support in-memory files (like `io.BytesIO()`) or on-disk files (specified by a path).
 3. Support different kinds of cache (single-thread, multi-processing, or file-based).
-4. A customized component helping the dashboard trigger a download event from the server side.
+4. Customized components helping the dashboard trigger download events from the server side.
 
 ## 1. Install
 
@@ -30,15 +30,26 @@ Intall the **latest released version** of this package by using the PyPI source:
 python -m pip install dash-file-cache
 ```
 
-Or use the following commands to install **the developing version** from the GitHub Source when you have already installed [Git :hammer:][tool-git]:
+If users want to install the developer's version, they need to ensure that the following packages are installed.
+
+* [Git :hammer:][tool-git]
+* [NodeJS][tool-nodejs]
+* [Yarn][tool-yarn]
+
+Then use the following commands to install it.
 
 ```bash
-git clone https://github.com/cainmagi/dash-file-cache
+git clone --depth 1 --single-branch https://github.com/cainmagi/dash-file-cache
 cd dash-file-cache
 python -m pip install -r requirements.txt -r requirements-dev.txt
-python -m pip install .
+yarn install
+yarn dlx @yarnpkg/sdks vscode
+yarn build
+python -m pip install .[dev]
 ```
 
+For VSCode users, please install the recommended extensions specified in the project workspace file.
+
 ## 2. Usage
 
 The following codes show a minimal example of this package

SECURITY.md

@@ -6,6 +6,7 @@ The following list shows the maintenance status of all versions.
 
 | Version | Supported          | Available on [PyPI :link:][link-pypi] |
 | ------- | ------------------ | ------------------------------------- |
+| `0.2.x` | :white_check_mark: | :white_check_mark:                    |
 | `0.1.x` | :white_check_mark: | :white_check_mark:                    |
 
 ## Reporting a Vulnerability

review_checklist.md

@@ -18,12 +18,27 @@
 *   Scan your code for expensive operations (large computations, DOM queries, React re-renders). Have you done your possible to limit their impact? If not, it is going to slow your app down.
 *   Can you think of cases where your current code will break? How are you handling errors? Should the user see them as notifications? Should your app try to auto-correct them for them?
 
+## Component API
+
+-   Have you tested your component on the Python side by creating an app in `usage.py` ?
+
+    Do all of your component's props work when set from the back-end?
+
+    Should all of them be settable from the back-end or are some only relevant to user interactions in the front-end?
+
+-   Have you provided some basic documentation about your component? The Dash community uses [react docstrings](https://github.com/plotly/dash-docs/blob/master/tutorial/plugins.py#L45) to provide basic information about dash components. Take a look at this [Checklist component example](https://github.com/plotly/dash-core-components/blob/master/src/components/Checklist.react.js) and others from the dash-core-components repository.
+
+    At a minimum, you should describe what your component does, and describe its props and the features they enable.
+
+    Be careful to use the correct formatting for your docstrings for them to be properly recognized.
+
 ## Tests
 
 -   The Dash team uses integration tests extensively, and we highly encourage you to write tests for the main functionality of your component. In the `tests` folder of the boilerplate, you can see a sample integration test. By launching it, you will run a sample Dash app in a browser. You can run the test with:
     ```
-    python -m pytest
+    python -m tests.test_render
     ```
+    [Browse the Dash component code on GitHub for more examples of testing.](https://github.com/plotly/dash-core-components)
 
 ## Ready to publish? Final scan