@loveluthien/carta-frontend 6.0.0-dev

package/docs_website/docs/contributing/documentation-guidelines.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 4
+---
+
+# Documentation guidelines
+
+Guidelines for building and writing this website.
+
+## Building documentation
+
+The website is hosted on GitHub Pages, and whenever the `dev` branch is updated, the website is automatically updated using GitHub Actions.
+
+To build and test the website locally, navigate to the `docs_website/` directory and install package dependencies:
+
+```
+cd docs_website
+npm install
+```
+
+and run the development server:
+
+```
+npm start
+```
+
+If you make changes to the files in the `docs/` and `api/` folders, the site will automatically reload and display the changes.
+
+To create a local production build:
+
+```
+npm run build
+```
+
+To test the local production build:
+
+```
+npm run serve
+```
+
+Please note that the search feature is only available in production builds.
+
+## Writing documentation pages
+
+The "Docs" pages and the "API/Overview" page are generated from markdown files in the `docs/` and `api/` directories. Simply edit these directories to modify the content or add new pages.
+
+For links to the "Docs" index pages and "API" subpages, it is required to use the `DocsIndexLink` and `ApiLink` MDX components to ensure the corresponding version is linked. If the file contains MDX components, it is recommended to use the `.mdx` extension.
+
+### Formatting
+
+To check the format of the changes, run (from the `docs_website/` folder):
+
+```
+npm run checkformat
+```
+
+To automatically fix the format:
+
+```
+npm run reformat
+```
+
+This maintains consistent markdown styling, including indentation, maximum line length, and list numbering. Please refer to the [Prettier documentation](https://prettier.io/blog/2017/11/07/1.8.0.html#markdown-support) for more information.
+
+## Writing API documentation
+
+The "API" subpages are generated from TSDoc documentation in the codebase. Catalogs are created based on the `index.ts` files, and elements need to be exported in the respective `index.ts` file to appear on the catalog subpages. Private and projected elements are not displayed.
+
+Please note that the development server does not automatically re-parse TSDoc. Therefore, if you modify TSDoc in the codebase, you will need to rebuild it to display the changes.
+
+### Formatting
+
+For TSDoc format, please refer to the [TSDoc documentation](https://tsdoc.org). ESLint is applied to check for the required format. To run the lint checks (from the repository root):
+
+```
+npm run check-eslint
+```
+
+## Versioning
+
+To tag a new version, run (from the `docs_website/` folder):
+
+```
+npm run docusaurus docs:version 1.2.3
+npm run docusaurus api:version 1.2.3
+```
+
+This will append the new version to `versions.json` and create files in the `versioned_docs/` and `versioned_sidebars/` folders. To modify the content or add new pages for a specific version, edit the files in these folders.

package/docs_website/docs/contributing/github-workflow.md

@@ -0,0 +1,146 @@
+---
+sidebar_position: 2
+---
+
+# GitHub workflow
+
+The workflow for contributing to the codebase.
+
+## Creating new issues
+
+When creating new issues, please refer to [this page](https://github.com/CARTAvis/carta-frontend/labels) for the available labels that can be added.
+
+If the issue is related to bug fixing, please use the [bug report template](https://github.com/CARTAvis/carta-frontend/blob/dev/.github/ISSUE_TEMPLATE/bug_report.md). Please make sure to fill in the template with all the necessary information, including the description, reproduction steps, and platform information. Providing reproduction steps is particularly helpful for resolving issues. Additionally, including testing images can be helpful for reproducing the issue.
+
+## Contributing to the codebase
+
+### Cloning and building the codebase
+
+To clone the codebase to your computer:
+
+```
+git clone git@github.com:CARTAvis/carta-frontend.git
+```
+
+For detailed instructions on building the codebase from source, please refer to the [README file](https://github.com/CARTAvis/carta-frontend/blob/dev/README.md#development).
+
+### Creating a branch
+
+Before making any changes to the codebase, create and check out to a new branch. It's recommended to use the following format for branch names:
+
+```
+git checkout -b "[author]/[issue id]_[description_with_underscores]"
+```
+
+If the issue doesn't exist yet, please create a new issue. When you start working on the issue, update the GitHub Project status of the issue to "In Progress".
+
+### Pushing changes
+
+To stage and commit your changes:
+
+```
+git add .
+git commit -m "a short description of the change"
+```
+
+Please note that Husky hooks run automatically during `commit` and `push`.
+
+-   If the hook checks fail, fix the reported issues and retry.
+-   If hooks are not available in your local clone, run `npm install` (or `npm run prepare` if install scripts were skipped).
+
+To push the branch to the remote repository:
+
+```
+git push
+```
+
+### Making a pull request
+
+#### Pull request template
+
+When making a pull request from your branch, please use the [pull request template](https://github.com/CARTAvis/carta-frontend/blob/dev/.github/pull_request_template.md).
+
+In the description section, please provide details about your changes, including linked issues and companion pull requests (if there are), what is implemented or fixed, and how to test it.
+
+Each check item in the checklist section is explained below:
+
+For linked issues (if there are): this section is for checking the status of the issues that are linked in the above description.
+
+-   assignee and label added: assign yourself to the issue you are working on. Add labels to the issue.
+
+-   GitHub Project estimate added: provide an estimate for the time required to complete the issue. This estimation is useful for future development planning.
+
+For the pull request: this section is for checking the status of the pull request and reviewing the code changes.
+
+-   reviewers and assignee added: assign reviewers and an assignee to the pull request. The assignee will be responsible for merging the pull request.
+
+-   GitHub Project estimate added: provide an estimate for the time required to review the pull request.
+
+-   changelog updated / no changelog update needed: updating the changelog is required when the issue exists in the latest release and the changes have an impact on users. It is recommended to update the changelog when sending the pull request and to resolve changelog merge conflicts using the GitHub UI.
+
+-   unit test added (for functions with no dependenies): it is recommended to add unit tests for functions that are related to the code changes.
+
+-   API documentation added (for public variables and methods in stores): it is recommended to add API documentation for public variables and methods in stores that are related to the code changes. Check [here](./documentation-guidelines/#writing-api-documentation) for adding API documentation.
+
+For dependencies: this section is for checking repositories that have dependencies on carta-frontend or are dependencies of carta-frontend.
+
+-   e2e test passing / corresponding fix added: check if the end-to-end tests are passing. This will be checked during the review.
+
+-   protobuf version bumped / no protobuf version bumped needed: updating the protobuf version is required when the behavior of the protobuf messages is changed.
+
+-   protobuf updated to the latest dev commit / no protobuf update needed: updating the protobuf is required when there are changes in the carta-protobuf submodule. This can be done when the pull request is ready for merge. Check [here](#merging-a-pull-request-with-protobuf-changes-required) for the steps.
+
+-   corresponding ICD test fix added (`BackendService` changed) / no ICD test fix needed (`BackendService` unchanged): updating ICD tests is required when there are changes in `BackendService`.
+
+-   user manual prepared (for large new features): preparing user manual updates in advance is required for large new features.
+
+#### CI checks
+
+Please ensure that the CI passes successfully when making the pull request. The CI checks various items:
+
+-   Codebase formatting: Check [here](./developer-tips/#checking-and-fixing-code-format) for automatic codebase formatting.
+-   Production builds with different Node versions: The build will not be successful if the lint check fails. Check [here](./developer-tips/#code-linting) for details.
+-   Documentation page formatting: Check [here](./documentation-guidelines/#formatting) for automatic formatting.
+-   Production build of the documentation website: Details of building the website locally can be found [here](./documentation-guidelines/#building-documentation).
+
+### Merging a pull request
+
+The assignee of the pull request is responsible for merging the pull request. When merging the pull request, ensure the following:
+
+-   Sufficient reviewers have approved the pull request.
+-   All items in the checklist are completed.
+-   All CI checks have passed successfully.
+
+After merging the pull request, make sure to close the linked issue if necessary. GitHub automatically closes issues when they are linked properly. Remember to delete the branch after the merge.
+
+#### Merging a pull request with protobuf changes required
+
+If the pull request requires changes in the carta-protobuf submodule and is ready for merge, follow these steps:
+
+1. Merge the carta-protobuf branch in the repository.
+
+2. Check out the frontend branch:
+
+    ```
+    git checkout [the frontend branch]
+    ```
+
+3. Check out the dev branch of the protobuf submodule and pull the latest version:
+
+    ```
+    cd protobuf
+    git checkout dev
+    git pull
+    cd ..
+    ```
+
+4. Commit and push the changes:
+
+    ```
+    git commit -a -m "update protobuf"
+    git push
+    ```
+
+5. Finally, you can check the item "protobuf updated to the latest dev commit" in the check list. The pull request is ready for merge if all the other checklist items are completed and the CI checks have passed.
+
+6. For the carta-backend repository, follow similar steps for the corresponding backend branch as in steps 2 to 5. Merge the frontend and backend pull requests simultaneously.

package/docs_website/docs/contributing/release-guidelines.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 5
+---
+
+# Release guidelines
+
+In this document, 123 is a placeholder for the current release number, and 124 for the following release number.
+
+## Beta releases
+
+### Beta release
+
+1. `dev` branch: update `CHANGELOG.md`. Change the `Unreleased` heading to `123.0.0-beta.0`.
+2. `dev` branch: update the user manual URL if necessary.
+3. Create a `release/123.0` branch using the `dev` branch.
+4. `release/123.0` branch: update the `package.json` version string to `123.0.0-beta.0`. Run `npm install` to update `package-lock.json`.
+5. Create a `v123.0.0-beta.0` tag using the release branch.
+6. Test the release branch. Make any required fixes in the `dev` branch, and merge them into the release branch. Ideally, bump the version and create a new tag every time changes are merged. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+7. Create packages from the release branch.
+
+### After beta release
+
+1. `dev` branch: update `CHANGELOG.md`. Create a new `Unreleased` section.
+2. `dev` branch: update the documentation website ([guidelines](./documentation-guidelines/#versioning)). Create a new version `123.0.0-beta.0`.
+
+### Additional beta release
+
+This process should be followed if changes have to be made after the beta packages have already been published (or even provided to a limited number of users). If there are significant changes in `dev` that should _not_ be included in the beta release, follow the point release procedure instead (but adjust the version strings as required).
+
+1. Make the required fixes in `dev`.
+2. `dev` branch: update `CHANGELOG.md`. Change the `Unreleased` heading to `123.0.0-beta.1`.
+3. `dev` branch: update the user manual URL if necessary.
+4. Merge the `dev` branch into the `release/123.0` branch.
+5. `release/123.0` branch: update the `package.json` version string to `123.0.0-beta.1`. Run `npm install` to update `package-lock.json`.
+6. Create a `v123.0.0-beta.1` tag using the release branch.
+7. Test the release branch. Make any required fixes in the `dev` branch, and merge them into the release branch. Ideally, bump the version and create a new tag every time changes are merged. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+8. Create packages from the release branch.
+
+## Stable releases
+
+### Final release
+
+1. `dev` branch: update `CHANGELOG.md`. Change the `Unreleased` heading to `123.0.0`.
+2. `dev` branch: update the user manual URL if necessary.
+3. Merge the `dev` branch into the `release/123.0` branch.
+4. `release/123.0` branch: update the `package.json` version string to `123.0.0-rc.0`. Run `npm install` to update `package-lock.json`.
+5. Create a `v123.0.0-rc.0` tag using the release branch.
+6. Test the release branch. Make any required fixes in the `dev` branch, and merge them into the release branch. Ideally, bump the version and create a new tag every time changes are merged. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+7. `release/123.0` branch: update the `package.json` version string to `123.0.0`. Run `npm install` to update `package-lock.json`.
+8. Create a `v123.0.0` tag using the release branch.
+9. Create packages from the release branch.
+
+### After final release
+
+1. `dev` branch: update the `package.json` version string to `124.0.0-dev`. Run `npm install` to update `package-lock.json`.
+2. `dev` branch: update `CHANGELOG.md`. Create a new `Unreleased` section.
+3. `dev` branch: update the documentation website ([guidelines](./documentation-guidelines/#versioning)). Create a new version `123.0.0`.
+
+### Point release
+
+This process should be followed if important bug fixes have to be released after the final release packages have already been published (or even provided to a limited number of users). If there are no changes in `dev` that should not be included in the point release, follow the additional beta release procedure instead (but adjust the version strings as required).
+
+1. Make the required fixes in `dev`. Cherry-pick them into the release branch.
+2. `dev` branch: update `CHANGELOG.md`. Move the cherry-picked changes from the `Unreleased` section to a new `123.0.1` section _under_ `Unreleased`.
+3. `release/123.0` branch: update `CHANGELOG.md`. Copy only the `123.0.1` section from the changelog in the `dev` branch.
+4. `release/123.0` branch: update the `package.json` version string to `123.0.1`. Run `npm install` to update `package-lock.json`.
+5. Create a `v123.0.1` tag using the release branch.
+6. Test the release branch. If an issue affects both `dev` and the release branch, fix it in `dev` and cherry-pick the changes into the release branch. If an issue is caused by changes in `dev` which are not included in the point release, make the minimal required changes in the release branch. Ideally, bump the version and create a new tag every time changes are made. If you don't want to bump the version, remember to destroy and recreate the latest tag.
+7. Create packages from the release branch.
+
+### After point release
+
+-   `dev` branch: update the documentation website ([guidelines](./documentation-guidelines/#versioning)). Replace version `123.0.0` with `123.0.1`.

package/docs_website/docs/contributing/unit-test-guidelines.md

@@ -0,0 +1,79 @@
+---
+sidebar_position: 3
+---
+
+# Unit test guidelines
+
+Guidelines for running and writing unit tests.
+
+## Running unit tests
+
+1. Install package dependencies:
+
+    ```
+    npm install
+    ```
+
+2. Build carta-protobuf and WebAssembly libraries:
+
+    ```
+    npm run build-protobuf
+
+    npm run build-libs
+    npm run build-wrappers
+    ```
+
+3. Run unit tests:
+
+    ```
+    npm test
+    ```
+
+    By default, Jest runs tests related to changed files.
+
+    To display individual test results, use the `--verbose` flag:
+
+    ```
+    npm test --verbose
+    ```
+
+    For more options available in Jest, please refer to the [Jest documentation](https://jestjs.io/docs/cli).
+
+## Writing unit tests
+
+### Structures
+
+-   Directory structure: colocate the test file in the same directory and name with `.test.ts/tsx` suffix. For example,
+    ```
+    .
+    └── src
+        └── components
+            └── AComponent
+                ├── AComponent.tsx
+                ├── AComponent.scss
+                └── AComponent.test.tsx
+        └── utilities
+            └── math
+                ├── math.ts
+                └── math.test.ts
+    ```
+-   Test code structure: use `describe` to structure the tests. For example,
+
+    ```javascript
+    describe("[unit]", () => {
+        test("[expected behavior]", () => {});
+
+        describe("[sub unit]", () => {
+            test("[expected behavior]", () => {});
+        });
+    });
+    ```
+
+-   Make sure to implement low-level tests that focus on a certain class or function. Mock imported classes and functions with Jest when necessary.
+-   TypeScript enum: import TypeScript enum without index files to avoid compile failure.
+
+### Testing React components
+
+-   Avoid mocking blueprint.js objects to prevent having complex setups.
+-   Avoid testing snapshots to prevent having large files in the codebase.
+-   Follow [the order of priority](https://testing-library.com/docs/queries/about/#priority) suggested by React Testing Library when querying elements.

package/docs_website/docs/documents.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Documents
+
+### Table of Contents
+
+-   <DocsIndexLink path="/code-snippet-tutorial">
+        <h4>Code snippet tutorial</h4>
+    </DocsIndexLink>
+-   <DocsIndexLink path="/contributing">
+        <h4>Contributing</h4>
+    </DocsIndexLink>

package/docs_website/docusaurus.config.js

@@ -0,0 +1,167 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+const {themes} = require("prism-react-renderer");
+const path = require("path");
+const versions = require("./versions.json");
+const packageJson = require("../package.json");
+
+const lightCodeTheme = themes.github;
+const darkCodeTheme = themes.dracula;
+const devVersion = packageJson.version;
+
+const apiOnClick = `
+    const versionLink = document.querySelector('.navbar__item.dropdown.dropdown--hoverable.dropdown--right .navbar__link');
+    const currentVersion = versionLink?.textContent;
+    let version = '';
+    if (currentVersion) {
+        if (currentVersion === 'Next' || currentVersion === '${devVersion}') {
+            version = '/next';
+        } else if (currentVersion !== '${versions?.[0]}') {
+            version = '/' + currentVersion;
+        }
+    }
+    
+    window.location.href = '/carta-frontend/api' + version;
+`;
+
+const apiButton = `
+    <a class="navbar__link menu__link api_link" onclick="${apiOnClick}">API</a>
+`;
+
+// eslint-disable-next-line tsdoc/syntax
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+    title: "CARTA Frontend Documentation",
+    tagline: "Welcome to the CARTA frontend documentation",
+    favicon: "img/carta_icon_128px.png",
+
+    // Set the production url of your site here
+    url: "https://cartavis.org",
+    // Set the /<baseUrl>/ pathname under which your site is served
+    // For GitHub pages deployment, it is often '/<projectName>/'
+    baseUrl: "/carta-frontend",
+
+    // GitHub pages deployment config.
+    // If you aren't using GitHub pages, you don't need these.
+    organizationName: "CARTAvis", // Usually your GitHub org/user name.
+    projectName: "carta-frontend", // Usually your repo name.
+    trailingSlash: false,
+
+    onBrokenLinks: "warn",
+
+    markdown: {
+        hooks: {
+            onBrokenMarkdownLinks: "warn"
+        }
+    },
+
+    // Even if you don't use internalization, you can use this field to set useful
+    // metadata like html lang. For example, if your site is Chinese, you may want
+    // to replace "en" with "zh-Hans".
+    i18n: {
+        defaultLocale: "en",
+        locales: ["en"]
+    },
+
+    presets: [
+        [
+            "classic",
+            // eslint-disable-next-line tsdoc/syntax
+            /** @type {import('@docusaurus/preset-classic').Options} */
+            ({
+                docs: {
+                    versions: {
+                        current: {
+                            label: devVersion
+                        },
+                        "5.0.0": {
+                            banner: "none"
+                        }
+                    },
+                    sidebarPath: require.resolve("./sidebars.js")
+                },
+                theme: {
+                    customCss: require.resolve("./src/css/custom.css")
+                }
+            })
+        ]
+    ],
+
+    themeConfig:
+        // eslint-disable-next-line tsdoc/syntax
+        /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+        ({
+            navbar: {
+                title: "CARTA Frontend Documentation",
+                logo: {
+                    alt: "CARTA Logo",
+                    src: "img/carta_icon_128px.png"
+                },
+                items: [
+                    {
+                        type: "docSidebar",
+                        sidebarId: "docsSidebar",
+                        position: "left",
+                        label: "Docs"
+                    },
+                    {
+                        type: "html",
+                        position: "left",
+                        value: apiButton,
+                        className: "navbar__link"
+                    },
+                    {
+                        type: "docsVersionDropdown",
+                        position: "right",
+                        dropdownActiveClassDisabled: true
+                    },
+                    {
+                        href: "https://github.com/CARTAvis/carta-frontend",
+                        label: "GitHub",
+                        position: "right"
+                    }
+                ]
+            },
+            footer: {
+                style: "dark",
+                copyright: `Copyright © ${new Date().getFullYear()} CARTA development team. Built with Docusaurus.`
+            },
+            prism: {
+                theme: lightCodeTheme,
+                darkTheme: darkCodeTheme
+            }
+        }),
+
+    plugins: [
+        [
+            "@loveluthien/docusaurus-plugin-typedoc-api",
+            {
+                projectRoot: path.join(__dirname, ".."),
+                packages: [
+                    {
+                        path: ".",
+                        entry: {
+                            index: {path: "src/index.tsx", entry: "."}, // index.tsx has no exports; work-around for displaying the overview page
+                            components: {path: "src/components/index.ts", entry: ".", label: "Components"},
+                            "components/Dialogs": {path: "src/components/Dialogs/index.ts", entry: ".", label: "Components - Dialogs"},
+                            "components/Shared": {path: "src/components/Shared/index.ts", entry: ".", label: "Components - Shared"},
+                            enums: {path: "src/enums/index.ts", entry: ".", label: "Enums"},
+                            models: {path: "src/models/index.ts", entry: ".", label: "Models"},
+                            services: {path: "src/services/index.ts", entry: ".", label: "Services"},
+                            stores: {path: "src/stores/index.ts", entry: ".", label: "Stores"},
+                            utilities: {path: "src/utilities/index.ts", entry: ".", label: "Utilities"}
+                        }
+                    }
+                ],
+                readmes: true,
+                readmeName: "docs_website/api/api.md",
+                changelogs: true,
+                tsconfigName: "tsconfig.json"
+            }
+        ],
+        require.resolve("docusaurus-lunr-search")
+    ]
+};
+
+module.exports = config;