9.9 KiB
JSONPrism Roadmap
This document is the single source of truth for what's done, what's next, and why.
Update it as work lands — keep the project status honest.
Phase 0 — Scaffold ✅
Status: complete (2026-05-12) Duration: ~1 day
Foundation: build tooling, app shell, converter framework, four working converters, full docs.
What landed:
- Vite 6 + React 19 + TypeScript 5.7 strict
- Tailwind v4 + shadcn-ready theme tokens
- Routing, theming, i18n (EN + VI), error boundary
- Converter interface + registry + shape detection
- Working: JSONL, CSV, TSV, YAML
- Stubs with detailed plans: XML, TOML, Markdown, SQL, RESX
- CI + GH Pages deploy workflows
- Full documentation suite
Phase 1 — Polish & Foundations ✅
Status: complete (2026-05-12) Actual: ~1 day
Goal: make the four working converters production-quality and the UX delightful enough to share publicly.
Tasks
1.1 Editor upgrade
- Replace
<textarea>input with CodeMirror 6 +@codemirror/lang-json - Line numbers + active-line highlight
- Folding for nested structures
- Theme: custom Prism Spectrum tokens applied to lezer highlight tags
- Parse-error linting (visible gutter markers)
- Output panel uses CodeMirror in read-only mode with format-specific syntax — deferred to Phase 2 (needs per-format language packages: yaml, xml, sql)
1.2 Settings panel
- Side sheet (Radix Dialog) that opens per-converter options
- Form widgets auto-generated from
optionSchema: Switch, segmented enum, number input, text input - Settings persist to localStorage per format
- "Reset to defaults" button with toast confirmation
1.3 Per-format options exposed in UI
- JSONL: pretty toggle
- CSV/TSV: header toggle, newline (LF/CRLF), nested strategy (json/flatten)
- YAML: indent (2–8), quote style
1.4 File handling
- Drag-drop a single
.jsonfile onto the input panel - "Open file…" button via hidden file input
- Drop overlay with Prism Spectrum styling
- Auto-detect file encoding — non-issue; FileReader uses UTF-8 by default and modern editors don't emit BOM
1.5 Notifications
- Sonner toast for: copy success/failure, download started, file loaded/failed, options reset
- Dismissible, bottom-right, dark/light aware via ThemeProvider integration
1.6 Testing
- Vitest + @testing-library/react + jsdom configured
- Unit tests for all Phase 1 converters (happy path + edge cases): 35+ tests
- Tests for
parseJsonInput,detectShape,options-storage - CI runs tests between typecheck and build
1.7 Polish
- Keyboard shortcuts: ⌘/Ctrl+K (clear), ⌘/Ctrl+S (download)
- Status bar showing: input bytes, output bytes, parse time, shortcut hints
- Shape detection hint (scalar / object / array / flat-object / array-of-objects)
- Disabled-format chips show "P2"/"P3" badge with tooltip
- Cmd/Ctrl+, to open settings — deferred; Sheet trigger handles its own keyboard nav via Radix
Deliverable
A polished, single-file converter UX with four production-grade converters. Ready to demo publicly and share in the Discord open-source server. 35+ unit tests passing.
Phase 2 — Four more formats + batch + Tauri
Split into three sub-phases for digestibility.
Phase 2A — Four new converters ✅
Status: complete (2026-05-12) Actual: ~1 day
XML converter
fast-xml-parserXMLBuilderintegration- Configurable root element name, item name, declaration, indent
- Attribute convention: keys starting with
@_become attributes - Array handling: each item wrapped with
itemNameelement when array is root - XML declaration prepended conditionally
- 8 unit tests including round-trip via
XMLParser
TOML converter
smol-tomlstringifyintegration- Rejects non-object roots (array, scalar, null) with clear error
sortKeysoption, recursive- Nested tables emitted naturally via smol-toml
- 7 unit tests including round-trip via
parse
Markdown table converter
- Hand-rolled, zero deps
- Header row from union of all object keys (preserve insertion order)
- Alignment markers per column (left/center/right/none)
- Pipe escaping in cell values
- Newlines →
<br>per GFM - Nested values JSON-stringified
- 11 unit tests
SQL INSERT converter
- Hand-rolled, zero deps
- Dialect support: standard / postgres / mysql / sqlite / mssql
- Identifier quoting per dialect (double-quote / backtick / bracket) with proper escaping
- Value escaping per dialect (booleans differ across all 5)
- Multi-row INSERT with configurable chunk size
- Optional
CREATE TABLEinference from first row's types - Missing keys across rows →
NULL - 19 unit tests (helpers + integration; 5 dialects × value types)
Phase 2B — Batch processing ✅
Status: complete (2026-05-12) Actual: ~1 day
- Drag-drop multiple files onto a dropzone (
react-dropzone) - Batch queue panel showing: filename, size, status (queued/processing/done/error), output size
- Hard limit: 500 files (
BATCH_MAX_FILES) - Process in chunks to keep UI responsive (
requestIdleCallbackwithsetTimeout(0)fallback) - "Download all (.zip)" via fflate (chosen over JSZip for ~12× smaller bundle)
- Per-file error display without blocking the rest of the queue
- AbortController-based cancellation
- Smart drop routing: 1 file → editor, 2+ files → batch panel auto-opens
- Zustand store with item map + display order for O(1) per-item updates
- Filename collision handling in the zip
- 20+ unit tests including round-trip zip decode
Phase 2C — Tauri 2 desktop wrapper ✅
Status: complete (2026-05-12) Actual: ~1 day
src-tauri/scaffold with Tauri 2.x (Cargo.toml,tauri.conf.json,lib.rs)- Tauri serves Vite-built
dist/; dev mode runs Vite + Tauri window with HMR - Native file open/save dialogs via
plugin-dialog+plugin-fs - OS drag-drop integration via
tauri://drag-dropevents (hook:useTauriDragDrop) - App icons: SVG source committed (
src-tauri/icons/icon.svg), generated formats vianpm run tauri:icon - Bundle targets: Windows (MSI + NSIS
.exe), macOS (DMG + .app, min 12.0), Linux (AppImage + deb) - CSP and capability file locked down (scoped to user dirs only)
- Custom Rust command
host_infofor diagnostics - GitHub Actions release workflow (matrix: Windows / macOS ARM / macOS Intel / Linux); draft release on
v*tag - Vite config detects Tauri context and adjusts base path + dev server
- Frontend
isTauri()runtime gate keeps web bundle free of Tauri imports (tree-shaken) Velopackskipped — using Tauri's native bundler (avoids the two-tool overhead PhantomMAC has)
Deliverable (full Phase 2)
8/9 formats production-ready. Batch up to 500 files. Desktop builds for Windows / macOS / Linux. JSONPrism becomes a "real" tool, not just a website.
Currently at Phase 2A — only RESX (Phase 3) remains as a stub.
Phase 3 — RESX & i18n integration ✅
Status: complete (2026-05-12) Actual: ~1 day
Goal: ship the .NET RESX converter and integrate with existing AutoClickForge / PhantomMAC localization workflows.
Tasks
3.1 RESX converter
- Hand-rolled XML output (skip fast-xml-parser; the template is too rigid)
- Standard RESX 2.0 header with
xsd:schema+ 4resheaderelements (resmimetype, version, reader, writer) - Input contract: flat object
{ "Key": "value" }; nested objects → reject with helpful error - Optional
_commentkey (configurable viacommentKeyoption) → emits<comment>element on the<data> - XML escaping for text content (&, <, >) and attribute context (quotes)
- Number and boolean coercion to string
- Null/undefined coerced to empty string
sortKeysoption for stable diffs across locale filesincludeSchemaoption (Visual Studio expects schema; tests verify byte-exact match)- 17 unit tests covering schema, comment shape, escaping, sort order, error paths
3.2 Smart UI for the RESX use case
- Format picker highlights suggested formats based on
detectShapeoutput via subtle ring - Flat-object detection surfaces RESX first in the suggestion list
- Batch processor preserves locale segment in filenames:
strings.vi.json→strings.vi.resx
3.3 Documentation
docs/RESX-MIGRATION.md— tutorial: i18next JSON → .NET RESX, with flatten script, batch flow, Visual Studio verification, comment support, CI sketch- Cross-link with PhantomMAC / AutoClickForge i18n docs in the worked example
Deliverable
9/9 formats production-ready. RESX integration documented as a real migration path between i18next-based web projects and .NET WPF projects. JSONPrism reaches 1.0.
Beyond Phase 3 — Ideas (no commitment)
- JSON → Excel (.xlsx) via SheetJS — possible if Markdown/CSV doesn't cover the use case
- Reverse direction (other format → JSON): different mental model; might warrant a sibling app
- Schema inference: emit JSON Schema, TypeScript types, or Go structs from sample JSON
- CLI version: same converter modules, exposed as a Node CLI for CI pipelines
- VS Code extension: surface the converters in the editor command palette
- Sharing: hash-based shareable URLs (
#data=...) for sample inputs (privacy: opt-in only)
These are deliberately deferred — Phase 1–3 first.
Tracking
Update this file when:
- A task is completed (mark it
- [x]and add a date if significant) - An estimate changes meaningfully
- The phase plan changes (and explain why in the commit message)
- A new phase is added to the "Beyond" section
The goal: anyone reading this should be able to answer "What's the current state of JSONPrism?" in 30 seconds.