init
This commit is contained in:
sokol
184
docs/main.md
Normal file
184
docs/main.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user