184 lines
6.2 KiB
Markdown
184 lines
6.2 KiB
Markdown
# Project Guide: XML Environment Configuration Editor
|
|
|
|
## 1. Project Overview
|
|
|
|
This is a **React-based web application** designed to manage environment configurations stored in XML format. It allows users to:
|
|
- Load `.xml` configuration files (via file picker)
|
|
- View and edit environment variables
|
|
- Save changes with simulated persistence delay
|
|
- Generate valid XML output from in-memory data
|
|
|
|
The core idea is to provide a **visual editor for XML-based engine configurations**, particularly useful for applications that rely on structured environment definitions.
|
|
|
|
[File format](file_format_spec.md)
|
|
|
|
### Key Technologies
|
|
- **TypeScript**: Full type safety across the codebase
|
|
- **React**: Component-based UI architecture
|
|
- **Vite**: Fast development server and build system
|
|
- **XML Parsing & Serialization**: Custom logic in `ConfigReader.tsx` and `EnvBuilder.ts`
|
|
|
|
### High-Level Architecture
|
|
```
|
|
User Interface (React)
|
|
│
|
|
▼
|
|
File Chooser → ConfigReader → Config (JSON-like) → AppState
|
|
│ │ │
|
|
└─────────→ EnvBuilder ←─┘ │
|
|
(Save/Update)│
|
|
▼
|
|
State Update (async)
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Getting Started
|
|
|
|
### Prerequisites
|
|
- Node.js (v16 or higher)
|
|
- npm or pnpm
|
|
- A modern browser (Chrome/Firefox)
|
|
|
|
### Installation
|
|
```bash
|
|
# Clone the repo (if not already done)
|
|
git clone <your-repo-url>
|
|
cd your-project
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
### Running Tests
|
|
No test files (`*.test.ts`) are present in the current codebase. Consider adding Jest or Vitest for future testing.
|
|
|
|
### Basic Usage
|
|
1. Open the app in your browser.
|
|
2. Click "Create new" to initialize a default config with an `DEFAULT` environment.
|
|
3. Upload an `.xml` file using the file picker.
|
|
4. Edit environments and parameters in the UI.
|
|
5. Changes are saved asynchronously (simulated 1-second delay).
|
|
|
|
---
|
|
|
|
## 3. Project Structure
|
|
|
|
| Directory | Purpose |
|
|
|------------------|--------|
|
|
| `src/` | Main source code |
|
|
| `src/App.tsx` | Central state manager (`AppState`) and config loading/saving logic |
|
|
| `src/main.tsx` | React root rendering entry point |
|
|
| `src/models/` | Core data models and parsers (`Env`, `EnvParam`, `ConfigReader`) |
|
|
| `src/builders/` | Utilities to convert objects into XML strings (`EnvBuilder`) |
|
|
| `src/components/`| UI components (`FileChoiser`, `Content`) |
|
|
| `src/vite-env.d.ts` | Vite environment type definitions |
|
|
|
|
### Key Files
|
|
- `App.tsx`: Manages global state (`AppState.Instance`) and handles config loading/saving.
|
|
- `ConfigReader.tsx`: Parses XML into `Config` object. Uses DOM API to traverse nodes.
|
|
- `EnvBuilder.ts`: Serializes `Env` objects into valid XML strings using template literals.
|
|
- `FileChoiser.tsx`: Handles file input and creation of new configs.
|
|
|
|
---
|
|
|
|
## 4. Development Workflow
|
|
|
|
### Coding Standards
|
|
- Use TypeScript with strict type checking (enforced by `tsconfig.json`)
|
|
- Follow React functional component patterns
|
|
- Use `async/await` for I/O operations (e.g., file parsing, saving)
|
|
- Avoid side effects in pure functions
|
|
|
|
### Testing
|
|
Currently no tests are included. Add:
|
|
```bash
|
|
npm install --save-dev jest @testing-library/react @testing-library/jest-dom
|
|
```
|
|
Then create test files in `__tests__/`.
|
|
|
|
### Build & Deployment
|
|
- Build: `npm run build`
|
|
- Output: `dist/` directory
|
|
- Deploy static files via GitHub Pages, Vercel, Netlify, etc.
|
|
|
|
### Contribution Guidelines
|
|
- Fork the repo and create a feature branch
|
|
- Write descriptive commit messages
|
|
- Open a PR with clear summary of changes
|
|
- Ensure no breaking changes without version bump
|
|
|
|
---
|
|
|
|
## 5. Key Concepts
|
|
|
|
| Concept | Description |
|
|
|--------|-------------|
|
|
| `Env` | Represents an environment (e.g., "DEV", "PROD") with a name and list of parameters |
|
|
| `EnvParam` | A key-value pair representing a configuration variable |
|
|
| `Config` | Root container for multiple `Env` objects |
|
|
| `ConfigReader` | Parses XML files into `Config` objects using DOM traversal |
|
|
| `EnvBuilder` | Converts `Env` objects back into valid XML strings |
|
|
| `AppState` | Singleton managing global state (currently only holds `envs`) |
|
|
|
|
### Design Patterns
|
|
- **Singleton**: `AppState.Instance`
|
|
- **Builder Pattern**: `EnvBuilder` for generating structured XML output
|
|
- **Observer/State Management**: `saveEnv()` updates state and logs, simulates async persistence
|
|
|
|
---
|
|
|
|
## 6. Common Tasks
|
|
|
|
### Load a Config File
|
|
1. Click the file input button in the top-right.
|
|
2. Select an `.xml` file that follows the expected structure:
|
|
```xml
|
|
<engine>
|
|
<environment name="DEV">
|
|
<parameter name="API_URL" value="http://localhost:3000" />
|
|
</environment>
|
|
</engine>
|
|
```
|
|
3. The app parses and loads it into memory.
|
|
|
|
### Create a New Config
|
|
1. Click **"Create new"** in the `FileChoiser`.
|
|
2. A default config with one environment (`DEFAULT`) is created.
|
|
3. You can now edit or save it.
|
|
|
|
### Save an Environment
|
|
- Call `AppState.Instance.saveEnv(env)` when updating.
|
|
- Returns a promise that resolves after 1 second (simulates backend delay).
|
|
- Index of the updated env is returned (`-1` if not found).
|
|
|
|
### Export to XML
|
|
- Use `new EnvBuilder().src(env).build()` to generate XML string from an `Env`.
|
|
- Useful for saving or sharing configurations.
|
|
|
|
---
|
|
|
|
## 7. Troubleshooting
|
|
|
|
| Issue | Solution |
|
|
|------|----------|
|
|
| File not loading | Ensure the file is `.xml` and valid (check structure in `ConfigReader`) |
|
|
| Missing `envs` after load | Verify `ConfigReader.parse()` returns a non-null `Config` |
|
|
| "Invalid Chalk template style argument" error | This comes from `Content.tsx` — likely a typo or placeholder. Should be replaced with proper error message. |
|
|
| XML not rendering correctly | Check that `EnvBuilder` uses correct escaping (`\r\n`, proper tags) |
|
|
|
|
> 💡 Tip: Use browser DevTools to inspect the DOM and console logs during file parsing.
|
|
|
|
---
|
|
|
|
## 8. References
|
|
|
|
- [Vite Documentation](https://vitejs.dev/guide/)
|
|
- [React Docs](https://react.dev/)
|
|
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
|
|
- [XML DOM API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/XML_DOM)
|
|
|
|
> 🔗 **Note**: The XML schema used is not documented. You may want to define a `.xsd` or schema file for validation. |