From df2c6718442ff9f7fcb30c1f4a0726033fbe4575 Mon Sep 17 00:00:00 2001 From: Yoshihiro OKUMURA Date: Wed, 9 Sep 2026 12:45:01 +0900 Subject: [PATCH] docs: rewrite readme and split out the changelog The README still described the Create React App scaffold and mixed the release history into the same file. - Document the current stack, requirements, project structure, routes, data model, and build output - Move the release history to CHANGELOG.md and add entries for 3.0.0, 3.0.1, and 3.0.2 --- CHANGELOG.md | 70 ++++++++++++++++++++++++++ README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 194 insertions(+), 16 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ac66bcc --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,70 @@ +# Changelog + +All notable changes to this project are documented in this file. Entries are grouped by released version, from +newest to oldest. + +## [3.0.2] - 2026-09-09 + +### Added + +- `lint` and `lint:check` scripts backed by the Biome linter. +- CSpell as a development dependency, with a `spell:check` script. +- `CHANGELOG.md` as a dedicated release history, separate from `README.md`. + +### Changed + +- Upgraded TypeScript to 7. +- Enabled the Biome `useComponentExportOnlyModules` rule to retain React Fast Refresh checks. +- Rewrote `README.md` to describe the current stack, requirements, project structure, routes, data model, and + build output. + +### Removed + +- ESLint, its configuration file, and its plugins. Linting is handled by Biome. +- `package-lock.json` from version control. + +## [3.0.1] - 2026-06-11 + +### Added + +- Shared `Notice` component extracted from the contact and news pages. +- CSpell dictionary and VS Code workspace configuration. + +### Changed + +- Replaced `react-helmet-async` with `@dr.pogodin/react-helmet` for document head management. + +### Fixed + +- Corrected a misspelling of "Arrangements" in the figure captions of the dataset metadata files. + +## [3.0.0] - 2026-06-11 + +### Added + +- Vite-based development and build pipeline with manual vendor chunk splitting. +- Biome configuration for formatting, linting, and import sorting. +- Local `nl2br` utility. + +### Changed + +- Migrated the build tooling from Create React App to Vite. The development server now runs on port 5173 and + production output is written to `dist` instead of `build`. +- Upgraded React to 19, React Router to 7, Redux Toolkit to 2, three.js to 0.186, and TypeScript to 6. +- Replaced `axios` with `ky` for HTTP requests and `react-nl2br` with a local utility. +- Reworked the 3D viewer to cancel in-flight dataset requests with `AbortController`, and removed synchronous + state updates from effects in the dataset detail component. +- Updated Google Analytics page view tracking to the `hitType`/`page` payload form. + +### Removed + +- Create React App tooling (`react-scripts`), the Jest and Testing Library setup, `web-vitals` reporting, and + `react-app-polyfill`. + +### Fixed + +- Corrected a typo in the 3D viewer manual link text on the help page. + +## [2.0.0] - 2022-06-07 + +Last release built with Create React App. diff --git a/README.md b/README.md index eef8259..17de650 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,42 @@ # CelLoc-3D -React project for celloc3d.brain.riken.jp +React single-page application for celloc3d.brain.riken.jp. + +CelLoc-3D is a database of the 3D arrangement of neocortical cells (glutamatergic/excitatory, GABAergic/inhibitory +and/or astrocytes) identified in vivo in layer 2/3 of the primary visual cortex of the mouse by two-photon imaging. +The application provides dataset search, dataset detail pages, downloadable data files, and a WebGL-based 3D viewer. + +## Tech Stack + +| Area | Technology | +| --- | --- | +| Build tool | Vite 8 with `@vitejs/plugin-react` | +| Language | TypeScript 7 | +| UI | React 19, CSS Modules | +| Routing | React Router 7 (`react-router-dom`) | +| State management | Redux Toolkit, React Redux | +| HTTP client | ky | +| 3D rendering | three.js | +| Document head | `@dr.pogodin/react-helmet` | +| Analytics | `react-ga4` | +| Lint / format | Biome | +| Spell check | CSpell | + +## Requirements + +- Node.js `^20.19.0` or `>=22.12.0` (required by Vite 8) +- npm + +## Getting Started + +Install the dependencies and start the development server: + +```sh +npm install +npm run dev +``` + +Open [http://localhost:5173](http://localhost:5173) to view the application. ## Available Scripts @@ -8,19 +44,13 @@ In the project directory, you can run: ### `npm run dev` -Runs the app in the development mode.
+Runs the app in development mode with hot module replacement.
Open [http://localhost:5173](http://localhost:5173) to view it in the browser. -The page will reload if you make edits.
-You will also see any lint errors in the console. - ### `npm run build` -Builds the app for production to the `dist` folder.
-It correctly bundles React in production mode and optimizes the build for the best performance. - -The build is minified and the filenames include the hashes.
-Your app is ready to be deployed! +Type-checks the project with `tsc -b` and builds the app for production into the `dist` folder.
+The build is minified and the filenames include content hashes. ### `npm run preview` @@ -28,18 +58,96 @@ Locally preview the production build. ### `npm run lint` -Run ESLint to check for code quality issues. +Run the Biome linter and apply the available fixes. + +### `npm run lint:check` + +Check for code quality issues without making changes. ### `npm run format` -Format code using Biome. +Run Biome formatter, linter, and import sorting, and apply the available fixes. ### `npm run format:check` -Check code formatting without making changes. +Run the same checks without making changes. + +### `npm run spell:check` + +Run CSpell over the project files. + +## Project Structure + +```text +. +├── index.html # Vite entry HTML +├── vite.config.ts # Build configuration and manual chunk splitting +├── biome.json # Formatter and linter configuration +├── cspell.json # Spell checker dictionary +├── public/ +│ ├── data/ # Per-dataset .dat, .json, and .png files +│ └── images/ +└── src/ + ├── index.tsx # Application entry point + ├── App.tsx # Layout, navigation, routes, GA initialization + ├── app/ # Redux store and typed hooks + ├── assets/ # data.json (dataset index), news.json + ├── features/ # Feature components, each with its own CSS Module + └── utils/ # Shared helpers +``` + +### Routes + +| Path | Component | Description | +| --- | --- | --- | +| `/` | `News` | Landing page with news entries | +| `/search` | `SearchForm` | Dataset search form | +| `/search/results` | `SearchResults` | Search results list | +| `/data/:name` | `DataDetail` | Dataset detail and downloads | +| `/data/:name/viewer` | `DataViewer` | three.js 3D viewer | +| `/help/*` | `Help` | Help pages | +| `/contact` | `Contact` | Contact information | +| `*` | `CompatRedirect` | Redirects legacy `.html` and CGI URLs, otherwise renders `NotFound` | + +`CompatRedirect` maps the URLs of the previous static site (for example `/Search.html`, `/Help_S1.html`, +`/DB/TE/TE0001.html`, and `/cgi-bin/SearchResult.cgi`) to their current equivalents. + +### Data Model + +The dataset index is bundled from `src/assets/data.json` and is keyed by dataset name. Each entry holds the +postnatal day (`pd`), `recordingVolume`, `imagingDepth`, `cellType`, `area`, `cellNum`, `expDate`, `releaseDate`, +`geneType`, and `remark` fields. `src/features/data/DataUtils.ts` exposes `exists(name)` and `search(params)` +over this index. + +Per-dataset files are served statically from `public/data/`: + +| File | Purpose | +| --- | --- | +| `.dat` | Cell coordinate data loaded by the 3D viewer | +| `.json` | Dataset metadata shown on the detail page | +| `.png` | Preview image | + +### Build Output + +`vite.config.ts` targets `es2023` and splits vendor code into three chunks: `vendor` (React and React DOM), +`three` (three.js), and `vendor-lib` (remaining dependencies). + +## Code Quality + +Biome handles formatting, linting, and import sorting. The configuration uses the recommended rule preset with +the React domain enabled, single quotes, trailing commas, two-space indentation, and a line width of 120. + +CSpell checks spelling across the project. Project-specific vocabulary and ignored paths are maintained in +`cspell.json`. + +The `.vscode/settings.json` file registers Biome as the default formatter and enables `source.fixAll.biome` on +save. + +## Changelog + +See [CHANGELOG.md](./CHANGELOG.md) for the release history. ## Learn More -You can learn more in the [Vite documentation](https://vite.dev/guide/). - -To learn React, check out the [React documentation](https://react.dev/). +- [Vite documentation](https://vite.dev/guide/) +- [React documentation](https://react.dev/)