105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
# XSLT tools
|
|
|
|
Browser-only MVP for testing local XML/XSLT transformations. Nothing is uploaded; the app uses browser APIs, LocalStorage, and local file open/save dialogs where available.
|
|
|
|
## Features in this MVP
|
|
|
|
- Three-column workbench:
|
|
- XML input
|
|
- XSL transformation code
|
|
- XML output
|
|
- CodeMirror editors with:
|
|
- line numbers
|
|
- XML syntax highlighting
|
|
- editor undo/redo
|
|
- cut/copy/paste helpers
|
|
- find support via CodeMirror shortcuts
|
|
- Transformation engines:
|
|
- SaxonJS 2.7 as the default engine for XSLT 1.0/2.0/3.0-style workflows
|
|
- Browser-native `XSLTProcessor` as a lightweight XSLT 1.0 fallback
|
|
- XML and XSLT well-formedness checks
|
|
- Basic XSLT root/version checks
|
|
- Snippet toolbox for common XSLT constructs
|
|
- Open/save local files
|
|
- File System Access API when supported
|
|
- file input/download fallback otherwise
|
|
- Output → Input action for chained transformations
|
|
- Confirmation dialog before destructive overwrites
|
|
- LocalStorage persistence
|
|
- Approximate “explain transformation” table after a run
|
|
|
|
## SaxonJS note
|
|
|
|
SaxonJS is bundled through the `saxon-js` npm package and loaded lazily when the SaxonJS engine runs. The browser build may show Vite warnings about Node modules such as `fs`, `path`, or `stream` being externalized. Those warnings come from the package containing Node.js support as well; the app does not use file-based SaxonJS APIs in the browser.
|
|
|
|
SaxonJS itself is free to use but not open source. Check `node_modules/saxon-js/LICENSE.txt` after installation before distributing a packaged version.
|
|
|
|
## Run locally
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Then open the local Vite URL shown in your terminal.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
npm run build
|
|
npm run preview
|
|
```
|
|
|
|
## Suggested next steps
|
|
|
|
1. Add parameter handling for `xsl:param`.
|
|
2. Add a real diagnostics/lint bridge into CodeMirror gutter markers.
|
|
3. Add transformation test cases with expected output assertions.
|
|
4. Add project import/export as a single `.xslt-tools.json` file.
|
|
5. Improve explain mode through stylesheet instrumentation.
|
|
6. Add optional precompiled SEF import/export support for larger SaxonJS projects.
|
|
|
|
## Structure
|
|
|
|
```text
|
|
src/
|
|
├── components/ # Layout, toolbar, editor panels, dialogs
|
|
├── editor/ # CodeMirror integration and XSLT snippets
|
|
├── file/ # Local file open/save helpers
|
|
├── transform/ # Transform engine abstraction, SaxonJS, native engine
|
|
├── validation/ # XML/XSLT validation helpers
|
|
└── workspace/ # LocalStorage-backed workbench state
|
|
```
|
|
|
|
## Development checks
|
|
|
|
Use Node.js 22 or newer. The main local quality gate is:
|
|
|
|
```bash
|
|
npm run check
|
|
```
|
|
|
|
Useful individual commands:
|
|
|
|
```bash
|
|
npm run typecheck # TypeScript only
|
|
npm run lint # ESLint
|
|
npm run lint:fix # ESLint autofix where possible
|
|
npm run format:check # Prettier check
|
|
npm run format # Prettier write
|
|
npm run test # Vitest/jsdom test suite
|
|
npm run build # Production build
|
|
npm run clean # Remove generated build/cache files
|
|
```
|
|
|
|
The vendored SaxonJS browser file is intentionally excluded from ESLint and Prettier because it is a third-party distribution artifact.
|
|
|
|
## Transformation engines
|
|
|
|
The app currently exposes two engines:
|
|
|
|
- **SaxonJS 2 dynamic XSLT 3.0**: default engine. It lazy-loads `public/vendor/saxon/SaxonJS2.js`, compiles raw XSLT text to SEF in the browser, then executes the generated SEF locally.
|
|
- **Native browser XSLTProcessor**: XSLT 1.0 fallback using the browser implementation.
|
|
|
|
The SaxonJS runtime is loaded only when a Saxon transformation is requested, so the initial app shell does not block on the large compiler/runtime file.
|