init

2026-02-18 11:38:25 +03:00
commit 83a5bb87c1
40 changed files with 5803 additions and 0 deletions
--- a/docs/config.json.xml
+++ b/docs/config.json.xml
@@ -0,0 +1,3 @@
+<engine>
+    <environment name="DEFAULT">
+        
--- a/docs/file_format_spec.md
+++ b/docs/file_format_spec.md
@@ -0,0 +1,10 @@
+The `config.json.xml` file defines environment-specific configurations and a template for generating JSON output. Key syntax points:
+
+- `<environment name="...">`: Defines a named environment (e.g., `DEFAULT`, `env1`, `env2`).
+- `<parameter name="..." value="..."/>`: Sets key-value pairs for parameters (e.g., `host`, `port`, `MessageBrokerHosts`).
+- `@param_name@`: Placeholder in the template that gets replaced with actual parameter values.
+- `@env_name@`: Placeholder replaced with the current environment name.
+- `"[ ... ]"`: Array syntax for list values like `MessageBrokerHosts`.
+- Template uses JSON format with placeholders for dynamic substitution.
+
+The template generates a final JSON config by replacing all `@...@` placeholders with corresponding parameter values from the active environment.
--- a/docs/main.md
+++ b/docs/main.md
@@ -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.