diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..2ddc3ce --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +root = true + +[*] +indent_style = space +indent_size = 2 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false + +[*.{yml,yaml}] +indent_size = 2 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..d7d864c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,49 @@ +--- +name: Bug report +about: Report a bug in JSONPrism +title: '[BUG] ' +labels: ['bug', 'needs-triage'] +assignees: [] +--- + +## Describe the bug + +A clear description of what the bug is. + +## To reproduce + +1. Go to '...' +2. Paste this JSON: '...' +3. Pick format '...' +4. See error + +## Sample JSON + +Please provide a **minimal** JSON sample that triggers the bug: + +```json +{ "your": "sample here" } +``` + +## Expected behavior + +What you expected to happen. + +## Actual behavior + +What actually happened. Include the error message and target format. + +## Environment + +- Browser: [e.g. Chrome 130, Firefox 132, Safari 18] +- OS: [e.g. Windows 11, macOS 15, Ubuntu 24.04] +- JSONPrism version: [e.g. 0.1.0 — check the footer] +- Is this on the hosted version (poli0981.github.io/jsonprism/) or local dev? + +## Screenshots + +If applicable, attach screenshots. + +## Additional context + +Anything else relevant. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..12fc08f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,43 @@ +--- +name: Feature request +about: Suggest a new feature for JSONPrism +title: '[FEATURE] ' +labels: ['enhancement', 'needs-triage'] +assignees: [] +--- + +## Problem + +What problem does this feature solve? What workflow are you trying to support? + +## Proposed solution + +How would you like JSONPrism to handle it? + +## Alternatives considered + +Other approaches you thought about, and why this one fits better. + +## Sample data (if applicable) + +If your feature involves a specific JSON shape, paste a sample: + +```json +{ "example": "input" } +``` + +And the expected output: + +``` +expected output here +``` + +## Scope check + +- [ ] This fits the "one JSON → many formats" core mission +- [ ] This can be done client-side (no server required) +- [ ] I have a real use case for this (not just hypothetical) + +## Additional context + +Links, screenshots, references to similar tools. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..db14750 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,59 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + name: Lint, typecheck, build + runs-on: ubuntu-latest + timeout-minutes: 10 + + strategy: + matrix: + node-version: [22.x] + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: npm + + - name: Install dependencies + run: npm ci --no-audit --no-fund + + - name: Format check + run: npm run format:check + + - name: Lint + run: npm run lint + + - name: Typecheck + run: npm run typecheck + + - name: Test + run: npm test + + - name: Build + run: npm run build + + - name: Upload build artifact + uses: actions/upload-artifact@v4 + with: + name: dist + path: dist + retention-days: 7 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..81dd157 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,61 @@ +name: Deploy to GitHub Pages + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + name: Build + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node 22 + uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: npm + + - name: Install dependencies + run: npm ci --no-audit --no-fund + + - name: Build + run: npm run build + + # SPA fallback so deep links (/jsonprism/about) work on GH Pages. + - name: Copy index.html → 404.html + run: cp dist/index.html dist/404.html + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: dist + + deploy: + name: Deploy + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..8a9a35c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,92 @@ +name: Release Tauri bundles + +on: + push: + tags: + - 'v*' + workflow_dispatch: + +permissions: + contents: write + +jobs: + build: + name: Build · ${{ matrix.platform.name }} + runs-on: ${{ matrix.platform.runner }} + timeout-minutes: 40 + + strategy: + fail-fast: false + matrix: + platform: + - name: Windows + runner: windows-latest + args: '' + - name: macOS (Apple Silicon) + runner: macos-14 + args: '--target aarch64-apple-darwin' + - name: macOS (Intel) + runner: macos-13 + args: '--target x86_64-apple-darwin' + - name: Linux + runner: ubuntu-22.04 + args: '' + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Linux build dependencies + if: matrix.platform.runner == 'ubuntu-22.04' + run: | + sudo apt-get update + sudo apt-get install -y \ + libwebkit2gtk-4.1-dev \ + libappindicator3-dev \ + librsvg2-dev \ + patchelf \ + libssl-dev \ + libgtk-3-dev + + - name: Setup Node 22 + uses: actions/setup-node@v4 + with: + node-version: 22.x + cache: npm + + - name: Setup Rust (stable) + uses: dtolnay/rust-toolchain@stable + with: + targets: ${{ matrix.platform.runner == 'macos-14' && 'aarch64-apple-darwin' || matrix.platform.runner == 'macos-13' && 'x86_64-apple-darwin' || '' }} + + - name: Cache Cargo build artifacts + uses: swatinem/rust-cache@v2 + with: + workspaces: './src-tauri -> target' + + - name: Install npm dependencies + run: npm ci --no-audit --no-fund + + - name: Generate icons (Linux & macOS) + if: matrix.platform.runner != 'windows-latest' + run: npm run tauri:icon + + - name: Generate icons (Windows) + if: matrix.platform.runner == 'windows-latest' + run: npm run tauri:icon + shell: pwsh + + - name: Build, sign, and create release + uses: tauri-apps/tauri-action@v0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tagName: ${{ github.ref_name }} + releaseName: 'JSONPrism ${{ github.ref_name }}' + releaseBody: | + Native desktop builds for Windows, macOS, and Linux. + + See the [CHANGELOG](https://github.com/poli0981/jsonprism/blob/main/CHANGELOG.md) for what's new. + releaseDraft: true + prerelease: false + args: ${{ matrix.platform.args }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..217f653 --- /dev/null +++ b/.gitignore @@ -0,0 +1,45 @@ +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* + +node_modules +dist +dist-ssr +*.local + +# Editor directories and files +.vscode/* +!.vscode/settings.json +!.vscode/extensions.json +.idea +.DS_Store +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? + +# Env +.env +.env.local +.env.*.local +!.env.example + +# Tauri (Phase 2C) +src-tauri/target +src-tauri/Cargo.lock +src-tauri/gen +src-tauri/icons/*.png +src-tauri/icons/*.ico +src-tauri/icons/*.icns + +# Test artifacts +coverage +.nyc_output + +.claude/ diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..2bd5a0a --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +22 diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..1d1e9ac --- /dev/null +++ b/.prettierignore @@ -0,0 +1,6 @@ +dist +node_modules +pnpm-lock.yaml +package-lock.json +yarn.lock +src/components/ui diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..a623579 --- /dev/null +++ b/.prettierrc @@ -0,0 +1,11 @@ +{ + "semi": true, + "singleQuote": true, + "trailingComma": "all", + "printWidth": 100, + "tabWidth": 2, + "useTabs": false, + "arrowParens": "always", + "endOfLine": "lf", + "plugins": ["prettier-plugin-tailwindcss"] +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ef459bb --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,166 @@ +# Changelog + +All notable changes to JSONPrism are documented here. + +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +Project is feature-complete for the original Phase 0–3 plan. Future work tracked in `docs/ROADMAP.md` under "Beyond Phase 3". + +## [1.0.0] — 2026-05-12 + +### Added — Phase 3: RESX + i18n migration + +- **RESX converter** (`.resx`) — hand-rolled XML output byte-aligned with Visual Studio's editor. 9/9 formats now production-ready. + - Accepts flat string-to-string objects: `{ "Key": "value", ... }` + - Supports the `{ value, _comment }` shape per entry; emits both `` and `` elements + - Options: `commentKey` (default `_comment`), `includeSchema`, `sortKeys` + - Full RESX 2.0 schema header + `resmimetype` / `version` / `reader` / `writer` resheaders + - Proper XML escaping: `&`, `<`, `>` in text; quotes in `name=` attributes + - Rejects nested objects (the only valid use of nesting is the `{ value, _comment }` shape) +- **Smart format suggestions** — picker now highlights formats matching the detected JSON shape with a subtle ring: + - `flat-object` → RESX surfaces first + - `array-of-objects` → CSV/TSV/Markdown/SQL/JSONL + - `object` → YAML/TOML/XML + - `array` → JSONL/YAML/XML + - `scalar` → YAML +- **Migration tutorial** (`docs/RESX-MIGRATION.md`) — step-by-step guide for taking i18next JSON locales into .NET RESX, with batch flow, Visual Studio verification, comment support, and a worked example using PhantomMAC's 30+ locale files + +### Status + +**JSONPrism reaches 1.0.** All 9 formats production-ready; web + desktop; bilingual; 110+ tests. + +### Tests + +- **15+ new tests**: RESX converter (escaping, comment shape, sort order, error paths, Visual Studio byte-match), suggestions module +- Total tests: **115+** + +## [0.5.0] — 2026-05-12 + +### Added — Phase 2C: Tauri 2 desktop wrapper + +- **`src-tauri/` Rust workspace** with Tauri 2.x: `Cargo.toml`, `tauri.conf.json`, `src/lib.rs`, `src/main.rs`, `build.rs` +- **App identifier**: `com.kokone.jsonprism` +- **Bundle targets**: Windows (MSI via WiX + NSIS installer), macOS (DMG, min 12.0), Linux (AppImage + deb) +- **Window config**: 1280×820 default, 800×560 minimum, drag-drop enabled, theme follows system +- **CSP locked down** to: self + Google Fonts (existing fonts) + IPC channel only +- **Tauri 2 plugin integration**: `plugin-dialog`, `plugin-fs`, `plugin-os`, `plugin-shell` +- **Capability file** (`capabilities/default.json`) scoped to `$HOME`, `$DOCUMENT`, `$DOWNLOAD`, `$DESKTOP` +- **Custom Rust command `host_info`** exposes OS / arch / app version for diagnostics +- **Frontend Tauri bridge** (`src/lib/tauri.ts`): `isTauri()`, `nativeOpenFiles()`, `nativeSaveBlob()`, `nativeReadText()`, `fileFromNativePath()`, `tauriHostInfo()` +- **Native drag-drop hook** (`useTauriDragDrop`) listens to `tauri://drag-drop` events and feeds File objects into the existing batch store +- **InputPanel + BatchPanel** branch on `isTauri()`: native dialogs in Tauri, web inputs in browser +- **Single source of truth**: same React UI, same converters, same tests — only I/O boundaries branch +- **Vite config Tauri-aware**: detects `TAURI_ENV_PLATFORM`, switches base to `/`, skips clearing screen, respects `TAURI_DEV_HOST` for mobile dev +- **Icon source** (`src-tauri/icons/icon.svg`, 1024×1024) — generates all platform icons via `npm run tauri:icon` +- **GitHub Actions release workflow** (`.github/workflows/release.yml`): matrix-builds Windows, macOS (Apple Silicon + Intel), Linux on `v*` tag push; creates draft GitHub release + +### Dependencies + +- Added `@tauri-apps/api`, `@tauri-apps/plugin-dialog`, `@tauri-apps/plugin-fs`, `@tauri-apps/plugin-os`, `@tauri-apps/plugin-shell` (^2.0.0 each) +- Added `@tauri-apps/cli` (devDep) + +### New npm scripts + +- `tauri:dev` — runs Tauri window in dev mode with HMR +- `tauri:build` — produces the platform's native bundle +- `tauri:icon` — generates all platform icons from `src-tauri/icons/icon.svg` + +## [0.4.0] — 2026-05-12 + +### Added — Phase 2B: Batch processing + +- **Multi-file queue** — drop up to **500 JSON files** at once for parallel conversion to any ready format +- **Batch panel** (Sheet drawer) — per-file status (queued / processing / done / error), inline drop zone, per-row remove +- **Cooperative scheduling** — yields to the UI between files via `requestIdleCallback` with `setTimeout(0)` fallback, so the browser stays responsive on large queues +- **Per-file error isolation** — broken JSON or converter errors don't stop the rest of the batch; each failure is surfaced inline +- **AbortController-based cancellation** — Cancel button stops the run mid-batch +- **`.zip` export** via **fflate** (~8KB gzipped, much smaller than JSZip), with automatic filename collision handling (`data.csv`, `data_2.csv`, …) +- **Smart drop routing in input panel** — single file goes into the editor, 2+ files auto-open the batch panel and queue them +- **Zustand `batchStore`** — `Record` + `itemOrder` for O(1) per-item updates without re-rendering the whole list +- **Trigger pill in toolbar** shows current queue size + +### Tests + +- **20+ new Vitest tests** covering `batchStore` mutations, `processBatch` cooperative scheduling and abort, `zipOutputs` round-trip (decode and verify contents), filename uniquification +- Total tests: **100+** + +### Dependencies + +- Added `fflate ^0.8.2` (zip) + +## [0.3.0] — 2026-05-12 + +### Added — Phase 2A: four new converters + +- **XML converter** via fast-xml-parser. Options: `indent`, `rootName`, `itemName`, `declaration`. Supports attributes via the `@_` key prefix convention. +- **TOML converter** via smol-toml. Option: `sortKeys` (recursive). Rejects non-object roots with a clear error. +- **Markdown table converter** (hand-rolled). Options: `alignment` (left/center/right/none), `escapePipes`. Newlines in cells become `
` per GFM. +- **SQL INSERT converter** (hand-rolled). Options: `tableName`, `dialect` (standard/postgres/mysql/sqlite/mssql), `multiRow`, `chunkSize`, `includeCreate`. Per-dialect identifier quoting, value escaping, and `CREATE TABLE` type inference. + +### Tests + +- **45+ new Vitest tests** across XML, TOML, Markdown, and SQL converters (helpers tested in isolation: `quoteIdentifier`, `formatSqlValue`, `inferSqlType`) +- Round-trip tests for XML (via `XMLParser`) and TOML (via `parse`) +- Per-dialect SQL coverage (5 dialects × value types) +- Total Vitest tests: **80+** + +### Changed + +- All 8 user-visible converters now report `ready: true`. RESX remains Phase 3. +- `xml.ts`, `toml.ts`, `markdown.ts`, `sql.ts` are no longer stubs. + +## [0.2.0] — 2026-05-12 + +### Added — Phase 1 polish + +- **CodeMirror 6** input editor with JSON syntax highlighting and parse-error linting +- **Settings panel** (Sheet drawer) auto-generated from each converter's `optionSchema` +- **Per-format options exposed** in the UI: + - JSONL: `pretty` toggle + - CSV/TSV: `header` toggle, `newline` (LF/CRLF), `nestedStrategy` (json/flatten) + - YAML: `indent` (2–8), `quoteStyle` (auto/single/double) +- **Settings persist** to `localStorage` per format; survive reload and tabs +- **File handling**: drag-drop + "Open" button for single `.json` / `.txt` files +- **Sonner toasts** for copy success, download, file load, options reset, errors +- **Keyboard shortcuts**: `Cmd/Ctrl+K` clear input, `Cmd/Ctrl+S` download output +- **Status bar** showing input/output byte counts, parse time, and shortcut hints +- **Shape detection hint** above the format picker (scalar / object / array / flat-object / array-of-objects) +- **Format selection persists** to localStorage +- **Tests**: 35+ Vitest tests covering all Phase 1 converters, registry, shape detection, options storage + +### Changed + +- `Converter` interface now requires `optionSchema: ReadonlyArray>` +- YAML `indent` option changed from `2 | 4` literal to `number` (range 2–8 via integer schema) +- Stub converters (XML/TOML/Markdown/SQL/RESX) declare empty `optionSchema: []` to satisfy the interface +- `InputPanel` and `OutputPanel` updated to use `CodeEditor` and toast notifications + +### Developer experience + +- **Vitest** + `@testing-library/react` + `jsdom` configured +- `npm test`, `npm run test:watch`, `npm run test:coverage` scripts +- CI runs tests between typecheck and build + +## [0.1.0] — 2026-05-12 + +### Added — Phase 0 scaffold + +- Project scaffold with Vite 6 + React 19 + TypeScript 5.7 strict +- Tailwind CSS v4 setup using `@theme inline` syntax +- "Prism Spectrum" theme with violet / cyan / amber / rose accents +- Dark + light theme with system preference detection +- Bilingual interface (English + Vietnamese) via i18next +- React Router v7 with `/` and `/about` routes +- Converter framework: `Converter` interface, registry, shape detection +- **Phase 1 working converters**: JSONL, CSV, TSV, YAML +- **Phase 2 stubs with implementation plans**: XML, TOML, Markdown table, SQL INSERT +- **Phase 3 stub**: RESX (.NET resources) +- UI: header with brand mark, hero, format picker, side-by-side input/output panels +- Copy + download actions with proper MIME types +- shadcn/ui configuration (`components.json`) +- GitHub Actions CI workflow (format, lint, typecheck, build) +- GitHub Actions deploy workflow → GitHub Pages +- Apache License 2.0 +- Full documentation: `README.md` (EN + VI), `CLAUDE.md`, `CONTRIBUTING.md`, `docs/ROADMAP.md` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9d706cd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,124 @@ +# CLAUDE.md + +Guidance for Claude (and other AI assistants) working on this repository. + +## Project context + +**JSONPrism** is a client-side JSON converter web app. Single JSON input → many formats (JSONL, CSV, TSV, YAML, XML, TOML, RESX, Markdown table, SQL INSERT). Deployed to GitHub Pages; later wrapped in Tauri 2 as a desktop app. + +The maintainer is **Kokone** ([@poli0981](https://github.com/poli0981)). Audience: developer community on the open-source Discord server + YouTube viewers who watch indie/visual-novel gameplay and occasionally want a quick devtool. + +**Project phase**: Phase 0 scaffold complete. Phase 1 polishes the four working converters and adds CodeMirror. Phase 2 implements XML/TOML/Markdown/SQL and the Tauri build. Phase 3 implements RESX. + +## Stack — exact versions matter + +- **Node.js** 22.x LTS (minimum 22.0.0; enforced in `package.json` `engines`) +- **React** 19.x (uses new JSX transform, `use()` hook, ref-as-prop) +- **TypeScript** 5.7+ (strict mode; `verbatimModuleSyntax`; `erasableSyntaxOnly`) +- **Vite** 6.x (ES2022 target, `@tailwindcss/vite` plugin) +- **Tailwind CSS** v4 (new `@theme inline` syntax in CSS, NOT `tailwind.config.ts`) +- **shadcn/ui** New York style, neutral base, configured in `components.json` +- **ESLint** v9 flat config + `typescript-eslint` v8 +- **Prettier** 3.x with `prettier-plugin-tailwindcss` + +Do not propose downgrading or "modernizing" to deprecated patterns. + +## Tauri 2 desktop wrapper + +JSONPrism is shipped as both a web app (GitHub Pages) and a native desktop app (Tauri 2 bundles). The same React UI runs in both contexts. + +**Runtime detection**: `isTauri()` from `src/lib/tauri.ts` is the single source of truth. The web bundle never imports Tauri modules statically — they're behind dynamic imports gated by `isTauri()` so tree-shaking keeps web builds clean. + +**When to branch on `isTauri()`**: + +- File dialogs: web uses hidden ``; Tauri uses `plugin-dialog` +- Save .zip: web uses Blob URL download; Tauri uses native save dialog + `plugin-fs.writeFile` +- Drag-drop from File Explorer / Finder: web uses `react-dropzone`; Tauri uses `tauri://drag-drop` event via `useTauriDragDrop` + +**Don't branch on `isTauri()`** for things that work in both: clipboard, in-memory operations, the converters themselves. Keep the Tauri-specific code at the I/O boundary. + +**Adding a new Tauri-only command**: declare in `src-tauri/src/lib.rs` with `#[tauri::command]`, register in `invoke_handler!`, expose a typed wrapper in `src/lib/tauri.ts` using `invoke()`. Update the capability JSON if it needs new permissions. + +**Icon updates**: edit `src-tauri/icons/icon.svg` (1024×1024 canvas) then run `npm run tauri:icon`. The generated PNG/ICO/ICNS files are gitignored — CI regenerates them per build. + +**Permission model**: Tauri 2 uses capability files. Edits to `src-tauri/capabilities/default.json` change which APIs the main window can call. Default capability already grants dialog, fs (scoped to `$HOME`, `$DOCUMENT`, `$DOWNLOAD`, `$DESKTOP`), os, and shell:open. + +**Bundling**: `npm run tauri:build` produces the platform bundle of whatever OS you're on. For cross-platform releases, push a `v*` tag — `.github/workflows/release.yml` matrix-builds for Windows, macOS Intel/ARM, and Linux. + +**Velopack note**: PhantomMAC uses Velopack for `.exe` deltas; JSONPrism uses Tauri's native bundler instead. Don't mix the two — Tauri's bundler produces `.msi` + `.exe` (NSIS) for Windows which covers the same ground. + +## Code style — non-negotiable + +- **Pure functions for converters**. Each converter is a pure, synchronous module implementing the `Converter` interface in `src/converters/types.ts`. No I/O, no DOM access, no global state. +- **Errors as values**. Converters return `{ ok: true, output } | { ok: false, error }`. Never throw across converter boundaries. +- **No `any`**. Use `unknown` for JSON values and narrow with type guards. The only sanctioned `any` is in `registry.ts` for the heterogeneous record type — keep it there. +- **Type-only imports**: `import type { Converter } from './types'`. Enforced by ESLint rule `consistent-type-imports`. +- **Use the `@/*` path alias** for imports inside `src/`. Don't write `../../lib/utils`. +- **Tailwind class order**: rely on `prettier-plugin-tailwindcss` — never hand-sort. +- **Don't fight the theme system**. Use the CSS variables (`--color-prism-*`, `bg-background`, etc.) instead of hard-coded hex. +- **i18n everything user-facing**. Hard-coded English strings in components are a bug. Add to both `en.json` and `vi.json`. + +## File layout — where things go + +``` +src/ +├── app/ # Top-level App component + routes +├── components/ +│ ├── ui/ # shadcn components — generated by CLI, don't hand-edit +│ ├── layout/ # Header, Footer, theme/language toggles +│ ├── converter/ # The workspace UI +│ └── common/ # Reusable bits not specific to converters +├── converters/ # ONE file per format. Self-contained. +├── hooks/ # React hooks +├── i18n/ # i18next setup + locales +├── lib/ # Pure utilities: detect, theme, sample, utils +├── pages/ # Route components +└── styles/ # globals.css ONLY — no per-component CSS files +``` + +If you find yourself wanting to add a new top-level folder, stop and reconsider. + +## Adding a new converter — checklist + +1. Create `src/converters/myformat.ts` exporting `myFormatConverter` (camelCase). +2. Implement the `Converter` interface. Return errors as values. +3. Add the format ID to the `FormatId` union in `src/converters/types.ts`. +4. Register in `src/converters/registry.ts` (both `CONVERTERS` and `ALL_FORMATS`). +5. Add `formats.myformat` label to BOTH `src/i18n/locales/en.json` AND `src/i18n/locales/vi.json`. +6. If introducing a new parsing library, add it to `vite.config.ts` `manualChunks.parsers` so it splits cleanly. +7. Update the format table in `README.md` and `README.vi.md`. +8. Update `docs/ROADMAP.md` to mark the phase done. +9. Write unit tests (Phase 1+ when Vitest lands). + +## Pitfalls observed in the wild + +- **Don't put options inside the converter call signature**. Options are passed separately so the UI can introspect `defaultOptions` to render a settings panel. +- **Don't use `JSON.parse` directly in components**. Always go through `parseJsonInput` in `src/lib/detect.ts` so error positions surface uniformly. +- **CSV nested values**: stringify nested objects as JSON by default (`nestedStrategy: 'json'`). The `flatten` strategy is alpha — keep it but don't make it default. +- **YAML force-quoting**: js-yaml's `forceQuotes` only works in conjunction with `quotingType`. Leaving one undefined produces unquoted output. Tested. +- **GitHub Pages basename**: production builds use base `/jsonprism/`. The router uses `import.meta.env.PROD` to switch basename. Do not hard-code. +- **Tailwind v4 dark mode**: uses the new `@custom-variant dark (&:is(.dark *));` syntax. The `.dark` class on `` triggers all dark-mode variants. Don't add `darkMode: 'class'` configs — that's v3 syntax. + +## Commands the maintainer actually runs + +```bash +npm run dev # 99% of the time +npm run typecheck # before pushing +npm run lint # CI does this anyway +npm run build # to verify production output +``` + +Format check happens automatically via Prettier in CI. The maintainer typically uses **WebStorm** (JetBrains license), so Prettier and ESLint run on save. + +## Communication preferences + +- Reply in **Vietnamese** unless the maintainer writes in English. +- Be direct. Skip unnecessary preamble. +- When proposing changes, show the diff or full file; don't just describe. +- Match the file-naming and patterns already established (`*Converter`, `useFoo`, kebab-case for files, PascalCase for components). +- The maintainer dislikes excessive emoji; reserve them for status indicators in docs (✅ 🔜 📋). +- When unsure between two equally-valid approaches, pick one and explain briefly — don't ask which the maintainer prefers unless it's a meaningful tradeoff. + +## Roadmap reference + +See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the canonical phase plan. Update it as work lands. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..35e844f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,98 @@ +# Contributing to JSONPrism + +Thanks for considering a contribution! JSONPrism is an open-source project under Apache License 2.0. + +## Quick start + +```bash +git clone https://github.com/poli0981/jsonprism.git +cd jsonprism +npm install +npm run dev +``` + +Open . + +## Before opening a PR + +1. **Run the checks locally**: + + ```bash + npm run format + npm run lint + npm run typecheck + npm run build + ``` + + CI runs all four. If any fails, your PR can't be merged. + +2. **Match the project style.** Read [`CLAUDE.md`](CLAUDE.md) for non-negotiable conventions (converter shape, error handling, i18n requirements). + +3. **Keep PRs focused.** One feature or one fix per PR. Refactors as separate PRs. + +4. **Write a clear PR description**: what changed, why, screenshots if UI. + +## Ways to contribute + +### 🐛 Bug reports + +Use the [Bug Report](https://github.com/poli0981/jsonprism/issues/new?template=bug_report.md) template. Include: + +- Browser + OS +- Steps to reproduce +- Sample JSON that triggers the bug (minimal, please) +- Expected vs actual output + +### 💡 Feature requests + +Use the [Feature Request](https://github.com/poli0981/jsonprism/issues/new?template=feature_request.md) template. We prioritize features that: + +- Fit the "one JSON → many formats" core mission +- Don't require server-side processing (we're client-only by design) +- Have a clear use case from a real workflow + +### 🌍 Translations + +Currently bundled: **English** and **Tiếng Việt**. To add a new language: + +1. Copy `src/i18n/locales/en.json` to `src/i18n/locales/.json` +2. Translate every value +3. Register in `src/i18n/index.ts` +4. Add to the `supportedLngs` array +5. Add the language to `LanguageSwitcher.tsx` +6. Open a PR + +### ➕ Adding a new converter + +See the **"Adding a new converter — checklist"** section in [`CLAUDE.md`](CLAUDE.md). + +Briefly: + +1. New file `src/converters/myformat.ts` implementing `Converter` +2. Register in `registry.ts` and `types.ts` +3. Add i18n labels (EN + VI minimum) +4. Update README format tables +5. Mark roadmap entry done + +## Commit messages + +We follow a relaxed version of [Conventional Commits](https://www.conventionalcommits.org): + +``` +feat(converter): add TOML converter with smol-toml +fix(csv): escape pipes in cell values +docs: clarify Tauri build steps +chore(deps): bump react to 19.1 +``` + +Prefixes: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `style`. + +## Code of Conduct + +Be kind. Assume good faith. Disagreements about technical choices are fine; personal attacks are not. + +Reports to the maintainer via GitHub (DM or email on profile). + +## License + +By contributing, you agree your contributions will be licensed under [Apache License 2.0](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3fef1a6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for describing the origin of the Work and + reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may accept and charge a + fee for acceptance of support, warranty, indemnity, or other liability + obligations and/or rights consistent with this License. However, in + accepting such obligations, You may act only on Your own behalf + and on Your sole responsibility, not on behalf of any other + Contributor, and only if You agree to indemnify, defend, and hold + each Contributor harmless for any liability incurred by, or claims + asserted against, such Contributor by reason of your accepting any + such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 Kokone (https://github.com/poli0981) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..e8a10c1 --- /dev/null +++ b/README.md @@ -0,0 +1,191 @@ +
+ +# JSONPrism + +**Disperse JSON into many formats.** + +One JSON input. Eight target formats. Fully in your browser. + +[![CI](https://github.com/poli0981/jsonprism/actions/workflows/ci.yml/badge.svg)](https://github.com/poli0981/jsonprism/actions/workflows/ci.yml) +[![Deploy](https://github.com/poli0981/jsonprism/actions/workflows/deploy.yml/badge.svg)](https://github.com/poli0981/jsonprism/actions/workflows/deploy.yml) +[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) + +[Live demo](https://poli0981.github.io/jsonprism/) · [Tiếng Việt](README.vi.md) · [Roadmap](docs/ROADMAP.md) + +
+ +--- + +JSONPrism is a refracting tool for developers. It takes a single JSON input and disperses it into many target formats — like white light through a prism. **Everything runs client-side**, so your data never leaves your device. + +## Target formats + +| Format | Extension | Status | +| ----------------- | --------- | ------------- | +| JSONL | `.jsonl` | ✅ Phase 1 | +| CSV | `.csv` | ✅ Phase 1 | +| TSV | `.tsv` | ✅ Phase 1 | +| YAML | `.yaml` | ✅ Phase 1 | +| XML | `.xml` | ✅ Phase 2 | +| TOML | `.toml` | ✅ Phase 2 | +| Markdown table | `.md` | ✅ Phase 2 | +| SQL `INSERT` | `.sql` | ✅ Phase 2 | +| RESX (.NET) | `.resx` | ✅ Phase 3 | + +## Features + +- **Client-side only** — no server, no telemetry, no upload. Your JSON stays in your browser. +- **Batch processing** — up to 500 files at once (Phase 2). +- **Smart shape detection** — recognizes flat objects, arrays of objects, scalars; suggests the best target format. +- **Per-format options** — pretty-print, indentation, dialect (for SQL), alignment (for Markdown), and more. +- **Dark + light themes** — Prism Spectrum palette with violet / cyan / amber / rose accents. +- **EN + VI** — bilingual interface out of the box. More languages welcome. +- **Tauri desktop build** — drag-and-drop file workflow, offline-first (Phase 2 milestone). + +## Tech stack + +- **Vite 6** + **React 19** + **TypeScript 5.7** +- **Tailwind CSS v4** + **shadcn/ui** (New York style, neutral base) +- **CodeMirror 6** for the input editor (Phase 1 polish) +- **PapaParse**, **js-yaml**, **smol-toml**, **fast-xml-parser** for parsing/serialization +- **i18next** for translations, **Zustand** for state, **Sonner** for toasts +- **Tauri 2** wrapper (Phase 2) + +## Quick start + +**Requirements**: Node.js **22 LTS** or newer. + +```bash +git clone https://github.com/poli0981/jsonprism.git +cd jsonprism +npm install +npm run dev # http://localhost:5173 +``` + +## Desktop app (Tauri 2) + +JSONPrism also ships as a native desktop app via Tauri 2. The app uses the same React UI, with native OS dialogs and drag-drop hooked into the existing batch flow. + +**Additional requirements**: + +- **Rust toolchain** (`rustup`) with the stable channel +- **Platform build deps**: + - **Windows**: Visual Studio Build Tools (C++ workload) + WebView2 (preinstalled on Windows 11) + - **macOS**: Xcode Command Line Tools (`xcode-select --install`) + - **Linux**: `libwebkit2gtk-4.1-dev`, `libappindicator3-dev`, `librsvg2-dev`, `patchelf`, `libssl-dev` + +**Generate icons once** (uses Tauri's CLI to render the SVG to PNG/ICO/ICNS): + +```bash +npm run tauri:icon +``` + +**Run in dev mode** (Vite + Tauri window with hot reload): + +```bash +npm run tauri:dev +``` + +**Build native bundles**: + +```bash +npm run tauri:build +``` + +Output: + +- Windows → `src-tauri/target/release/bundle/msi/*.msi` + `nsis/*-setup.exe` +- macOS → `src-tauri/target/release/bundle/dmg/*.dmg` + `macos/*.app` +- Linux → `src-tauri/target/release/bundle/appimage/*.AppImage` + `deb/*.deb` + +**Automated releases**: pushing a `v*` tag triggers `.github/workflows/release.yml`, which builds for all platforms in parallel and creates a draft GitHub release. + +### Scripts + +| Script | What it does | +| --------------------- | --------------------------------------------- | +| `npm run dev` | Start Vite dev server with HMR | +| `npm run build` | Production build to `dist/` | +| `npm run preview` | Preview the built site locally | +| `npm run lint` | Run ESLint | +| `npm run lint:fix` | Run ESLint with autofix | +| `npm run typecheck` | TypeScript type-check, no emit | +| `npm run format` | Format with Prettier | +| `npm run format:check`| Check formatting (CI uses this) | + +### shadcn/ui components + +The `components.json` is preconfigured. Add components on demand: + +```bash +npx shadcn@latest add button input textarea tabs select card dialog sheet \ + dropdown-menu switch badge progress tooltip sonner resizable +``` + +## Architecture + +``` +src/ +├── app/ # Router + global providers +├── components/ +│ ├── ui/ # shadcn components (added on demand) +│ ├── layout/ # Header, Footer, ThemeToggle +│ ├── converter/ # Workspace, panels, format picker +│ └── common/ # ErrorBoundary, LanguageSwitcher +├── converters/ # One module per target format +│ ├── types.ts # Converter interface +│ ├── registry.ts # Lookup table +│ └── *.ts # Per-format implementations +├── hooks/ # Custom hooks +├── i18n/ # Translations (en, vi) +├── lib/ # detect, theme, utils, sample +├── pages/ # Home, About +├── styles/ # globals.css (Tailwind + theme tokens) +└── main.tsx +``` + +### Adding a new format + +Each format is a self-contained module implementing the `Converter` interface: + +```ts +import type { Converter } from './types'; + +interface MyFormatOptions { + indent: 2 | 4; +} + +export const myFormatConverter: Converter = { + meta: { + id: 'myformat', + labelKey: 'formats.myformat', + extension: 'myf', + mimeType: 'application/x-myformat', + phase: 1, + ready: true, + }, + defaultOptions: { indent: 2 }, + convert({ data }, options) { + try { + const output = serialize(data, options); + return { ok: true, output }; + } catch (err) { + return { ok: false, error: (err as Error).message }; + } + }, +}; +``` + +Then register it in `src/converters/registry.ts` and add label keys to `src/i18n/locales/*.json`. + +See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full phase plan. + +## Contributing + +Pull requests welcome — please read [`CONTRIBUTING.md`](CONTRIBUTING.md) first. + +For bug reports and feature requests, use [GitHub Issues](https://github.com/poli0981/jsonprism/issues). + +## License + +[Apache License 2.0](LICENSE) — © 2026 Kokone. diff --git a/README.vi.md b/README.vi.md new file mode 100644 index 0000000..15e4ee6 --- /dev/null +++ b/README.vi.md @@ -0,0 +1,191 @@ +
+ +# JSONPrism + +**Tán sắc JSON ra nhiều định dạng.** + +Một JSON đầu vào. Tám định dạng đích. Chạy hoàn toàn trong trình duyệt. + +[![CI](https://github.com/poli0981/jsonprism/actions/workflows/ci.yml/badge.svg)](https://github.com/poli0981/jsonprism/actions/workflows/ci.yml) +[![Deploy](https://github.com/poli0981/jsonprism/actions/workflows/deploy.yml/badge.svg)](https://github.com/poli0981/jsonprism/actions/workflows/deploy.yml) +[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) + +[Bản demo](https://poli0981.github.io/jsonprism/) · [English](README.md) · [Lộ trình](docs/ROADMAP.md) + +
+ +--- + +JSONPrism là công cụ "tán sắc" cho developer. Nhận một JSON đầu vào và phân tách ra nhiều định dạng đích — như ánh sáng trắng đi qua lăng kính. **Mọi thứ chạy client-side**, dữ liệu của bạn không bao giờ rời khỏi máy. + +## Định dạng hỗ trợ + +| Định dạng | Phần mở rộng | Trạng thái | +| ----------------- | ------------ | -------------- | +| JSONL | `.jsonl` | ✅ Phase 1 | +| CSV | `.csv` | ✅ Phase 1 | +| TSV | `.tsv` | ✅ Phase 1 | +| YAML | `.yaml` | ✅ Phase 1 | +| XML | `.xml` | ✅ Phase 2 | +| TOML | `.toml` | ✅ Phase 2 | +| Bảng Markdown | `.md` | ✅ Phase 2 | +| SQL `INSERT` | `.sql` | ✅ Phase 2 | +| RESX (.NET) | `.resx` | ✅ Phase 3 | + +## Tính năng + +- **Chạy hoàn toàn client-side** — không server, không telemetry, không upload. JSON của bạn ở lại trong trình duyệt. +- **Xử lý batch** — tới 500 file cùng lúc (Phase 2). +- **Phát hiện shape thông minh** — nhận diện flat object, mảng object, scalar; gợi ý format đích phù hợp. +- **Tuỳ chọn theo từng format** — pretty-print, indentation, dialect (SQL), alignment (Markdown), v.v. +- **Theme sáng/tối** — bảng màu Prism Spectrum với violet / cyan / amber / rose. +- **Đa ngôn ngữ EN + VI** — sẵn sàng từ ngày đầu. Hoan nghênh thêm ngôn ngữ khác. +- **Bản desktop Tauri** — drag-and-drop file, hoạt động offline (mốc Phase 2). + +## Tech stack + +- **Vite 6** + **React 19** + **TypeScript 5.7** +- **Tailwind CSS v4** + **shadcn/ui** (style New York, base neutral) +- **CodeMirror 6** cho editor đầu vào (Phase 1 polish) +- **PapaParse**, **js-yaml**, **smol-toml**, **fast-xml-parser** để parse/serialize +- **i18next** cho dịch thuật, **Zustand** cho state, **Sonner** cho toast +- **Tauri 2** wrapper (Phase 2) + +## Bắt đầu nhanh + +**Yêu cầu**: Node.js **22 LTS** trở lên. + +```bash +git clone https://github.com/poli0981/jsonprism.git +cd jsonprism +npm install +npm run dev # http://localhost:5173 +``` + +## Bản desktop (Tauri 2) + +JSONPrism cũng có bản desktop native qua Tauri 2. App dùng cùng React UI, với dialog OS native và drag-drop tích hợp vào batch flow hiện có. + +**Yêu cầu thêm**: + +- **Rust toolchain** (`rustup`) với channel stable +- **Build deps theo platform**: + - **Windows**: Visual Studio Build Tools (workload C++) + WebView2 (cài sẵn trên Windows 11) + - **macOS**: Xcode Command Line Tools (`xcode-select --install`) + - **Linux**: `libwebkit2gtk-4.1-dev`, `libappindicator3-dev`, `librsvg2-dev`, `patchelf`, `libssl-dev` + +**Generate icon một lần** (dùng Tauri CLI render SVG ra PNG/ICO/ICNS): + +```bash +npm run tauri:icon +``` + +**Chạy dev mode** (Vite + Tauri window có hot reload): + +```bash +npm run tauri:dev +``` + +**Build bundle native**: + +```bash +npm run tauri:build +``` + +Output: + +- Windows → `src-tauri/target/release/bundle/msi/*.msi` + `nsis/*-setup.exe` +- macOS → `src-tauri/target/release/bundle/dmg/*.dmg` + `macos/*.app` +- Linux → `src-tauri/target/release/bundle/appimage/*.AppImage` + `deb/*.deb` + +**Release tự động**: push tag `v*` sẽ trigger `.github/workflows/release.yml`, build cho tất cả platform song song và tạo draft GitHub release. + +### Các script + +| Script | Chức năng | +| --------------------- | ---------------------------------------- | +| `npm run dev` | Chạy Vite dev server với HMR | +| `npm run build` | Build production vào `dist/` | +| `npm run preview` | Xem trước bản build trên máy local | +| `npm run lint` | Chạy ESLint | +| `npm run lint:fix` | Chạy ESLint với autofix | +| `npm run typecheck` | Type-check TypeScript, không emit | +| `npm run format` | Format bằng Prettier | +| `npm run format:check`| Kiểm tra format (CI dùng cái này) | + +### Components shadcn/ui + +`components.json` đã được cấu hình sẵn. Thêm component theo nhu cầu: + +```bash +npx shadcn@latest add button input textarea tabs select card dialog sheet \ + dropdown-menu switch badge progress tooltip sonner resizable +``` + +## Kiến trúc + +``` +src/ +├── app/ # Router + providers +├── components/ +│ ├── ui/ # shadcn components (thêm theo nhu cầu) +│ ├── layout/ # Header, Footer, ThemeToggle +│ ├── converter/ # Workspace, panels, format picker +│ └── common/ # ErrorBoundary, LanguageSwitcher +├── converters/ # Một module cho mỗi định dạng đích +│ ├── types.ts # Interface Converter +│ ├── registry.ts # Bảng tra cứu +│ └── *.ts # Cài đặt theo từng format +├── hooks/ # Custom hooks +├── i18n/ # Dịch thuật (en, vi) +├── lib/ # detect, theme, utils, sample +├── pages/ # Home, About +├── styles/ # globals.css (Tailwind + theme tokens) +└── main.tsx +``` + +### Thêm định dạng mới + +Mỗi format là một module độc lập, cài đặt interface `Converter`: + +```ts +import type { Converter } from './types'; + +interface MyFormatOptions { + indent: 2 | 4; +} + +export const myFormatConverter: Converter = { + meta: { + id: 'myformat', + labelKey: 'formats.myformat', + extension: 'myf', + mimeType: 'application/x-myformat', + phase: 1, + ready: true, + }, + defaultOptions: { indent: 2 }, + convert({ data }, options) { + try { + const output = serialize(data, options); + return { ok: true, output }; + } catch (err) { + return { ok: false, error: (err as Error).message }; + } + }, +}; +``` + +Sau đó đăng ký nó trong `src/converters/registry.ts` và thêm label key vào `src/i18n/locales/*.json`. + +Xem [`docs/ROADMAP.md`](docs/ROADMAP.md) để biết kế hoạch phase đầy đủ. + +## Đóng góp + +Welcome pull request — vui lòng đọc [`CONTRIBUTING.md`](CONTRIBUTING.md) trước. + +Báo bug hoặc đề xuất tính năng tại [GitHub Issues](https://github.com/poli0981/jsonprism/issues). + +## Giấy phép + +[Apache License 2.0](LICENSE) — © 2026 Kokone. diff --git a/components.json b/components.json new file mode 100644 index 0000000..285033d --- /dev/null +++ b/components.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://ui.shadcn.com/schema.json", + "style": "new-york", + "rsc": false, + "tsx": true, + "tailwind": { + "config": "", + "css": "src/styles/globals.css", + "baseColor": "neutral", + "cssVariables": true, + "prefix": "" + }, + "aliases": { + "components": "@/components", + "utils": "@/lib/utils", + "ui": "@/components/ui", + "lib": "@/lib", + "hooks": "@/hooks" + }, + "iconLibrary": "lucide" +} diff --git a/docs/RESX-MIGRATION.md b/docs/RESX-MIGRATION.md new file mode 100644 index 0000000..8ea6b9a --- /dev/null +++ b/docs/RESX-MIGRATION.md @@ -0,0 +1,229 @@ +# Migrating i18next JSON to .NET RESX + +This guide walks you through converting i18next-style locale files (used by JSONPrism's frontend, YTDescGen, the F2P Tracker, and most React projects) into .NET RESX resource files (used by AutoClickForge, PhantomMAC, and other WPF / Avalonia / WinForms projects). + +It's the canonical workflow for keeping a single source-of-truth translation across your web and desktop projects. + +--- + +## The problem + +Most JS/TS projects ship translations as namespaced JSON: + +```json +{ + "app": { + "name": "PhantomMAC", + "tagline": "Randomize your MAC address" + }, + "buttons": { + "ok": "OK", + "cancel": "Cancel" + } +} +``` + +.NET projects expect RESX: + +```xml + + PhantomMAC + + + OK + +``` + +Two mismatches: + +1. **Shape**: i18next allows arbitrary nesting; RESX requires a flat string-to-string map. +2. **Key convention**: web typically uses `dot.separated.paths` already; native .NET sometimes uses `PascalCase`. JSONPrism doesn't impose either — preserve whatever you have. + +--- + +## Step 1 — Flatten nested JSON + +JSONPrism's RESX converter rejects nested objects by design (RESX has no concept of nesting). You need a flat object first. + +If your translations are nested, flatten them with a one-liner. Save this as `flatten.mjs`: + +```js +import { readFileSync, writeFileSync } from 'node:fs'; + +function flatten(obj, prefix = '', out = {}) { + for (const [k, v] of Object.entries(obj)) { + const key = prefix ? `${prefix}.${k}` : k; + if (v !== null && typeof v === 'object' && !Array.isArray(v)) { + flatten(v, key, out); + } else { + out[key] = typeof v === 'string' ? v : JSON.stringify(v); + } + } + return out; +} + +const input = JSON.parse(readFileSync(process.argv[2], 'utf8')); +writeFileSync(process.argv[3], JSON.stringify(flatten(input), null, 2)); +console.log(`Flattened to ${process.argv[3]}`); +``` + +Run it: + +```bash +node flatten.mjs strings.en.json strings.en.flat.json +node flatten.mjs strings.vi.json strings.vi.flat.json +``` + +You now have flat objects like: + +```json +{ + "app.name": "PhantomMAC", + "app.tagline": "Randomize your MAC address", + "buttons.ok": "OK", + "buttons.cancel": "Cancel" +} +``` + +--- + +## Step 2 — Convert to RESX with JSONPrism + +### Option A — Single file via the web UI + +1. Open JSONPrism (web or desktop) +2. Drop or paste `strings.en.flat.json` into the input panel +3. The format picker highlights **RESX** (a flat object is its native shape) +4. Click **RESX** +5. (Optional) Open the settings panel — enable **Sort entries alphabetically** if you want stable diffs +6. Click **Download** → you get `output.resx` +7. Rename to match your .NET project convention, e.g. `Strings.resx` or `Resources.resx` + +### Option B — Batch convert all locales at once + +1. Drop **all** your flattened locale files into the input area at the same time (2+ files automatically open the batch panel) +2. Pick **RESX** in the format picker +3. Click **Process** in the batch panel +4. Click **Download .zip** + +The output zip contains one `.resx` per input file, with the locale segment preserved: + +``` +strings.en.flat.json → strings.en.flat.resx +strings.vi.flat.json → strings.vi.flat.resx +strings.ja.flat.json → strings.ja.flat.resx +``` + +Rename to the .NET convention `Resources.en.resx`, `Resources.vi.resx`, etc. before dropping into your project. + +--- + +## Step 3 — Verify in Visual Studio + +1. Drop the generated `.resx` into your .NET project's resources folder +2. Open in Visual Studio — the .resx editor should display every key/value as a flat table +3. Build the project — if VS regenerates a `Resources.Designer.cs` automatically, you'll have strongly-typed access: + + ```csharp + var greeting = Resources.app_name; // "PhantomMAC" + ``` + + The default tooling replaces `.` with `_` in the property name. + +4. Round-trip check: save the file from Visual Studio's editor; the diff against JSONPrism's output should be minimal (whitespace at most). If you see structural diffs, file an issue with the input JSON. + +--- + +## Adding comments + +If your translators need context, use the `{ value, _comment }` shape: + +```json +{ + "app.name": "PhantomMAC", + "buttons.ok": { "value": "OK", "_comment": "Confirmation dialog primary action" } +} +``` + +JSONPrism emits both `` and `` elements. The comment column shows up in Visual Studio's .resx editor and is preserved through `ResXResourceWriter`. + +Change the comment key in the settings panel if your convention is different (e.g. `note`, `description`). + +--- + +## Round-trip safety notes + +- **Special characters**: `&`, `<`, `>` are XML-escaped automatically in values; `"` is also escaped in `name=` attributes. You don't need to pre-escape. +- **Whitespace**: `` elements get `xml:space="preserve"`, so leading/trailing spaces in values survive. +- **Empty values**: `null` and `undefined` in JSON become empty `` elements. +- **Numbers and booleans**: coerced to their string representation (`true`, `false`, `42`). If you want explicit nullability, wrap in a string in your source JSON. +- **Schema header**: JSONPrism emits the standard RESX 2.0 schema. Visual Studio expects this — leave the **Include xsd:schema header** option on unless you're diffing manually. + +--- + +## Reverse direction (RESX → JSON) + +JSONPrism doesn't do this — it's a one-way "JSON → many formats" tool. If you need RESX → JSON for round-tripping, the simplest path is a small .NET console app using `ResXResourceReader`: + +```csharp +using System.Resources; +using System.Text.Json; + +var dict = new Dictionary(); +using var reader = new ResXResourceReader("Resources.en.resx"); +foreach (System.Collections.DictionaryEntry entry in reader) +{ + dict[(string)entry.Key] = entry.Value?.ToString() ?? ""; +} +File.WriteAllText("strings.en.flat.json", JsonSerializer.Serialize(dict, new JsonSerializerOptions { WriteIndented = true })); +``` + +Run once after editing in Visual Studio's editor, then your JS project sees the changes. + +--- + +## CI integration sketch + +If you maintain translations in `strings.*.json` and your .NET project under the same monorepo: + +```yaml +# .github/workflows/sync-resx.yml +name: Sync RESX from JSON + +on: + push: + paths: + - 'locales/strings.*.json' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22.x + - name: Flatten locales + run: | + for f in locales/strings.*.json; do + node scripts/flatten.mjs "$f" "$f.flat" + done + # Then either: + # a) use a CLI build of JSONPrism (Phase 4 idea), or + # b) commit the .flat.json and have a separate workflow open JSONPrism manually +``` + +A CLI version of JSONPrism is on the "Beyond Phase 3" wishlist in `docs/ROADMAP.md`. Until then, batch through the web/desktop UI manually when locales change. + +--- + +## Worked example: PhantomMAC + +PhantomMAC has 30+ locale files maintained as `.resx` originally. Going forward: + +1. Maintain the canonical source as JSON (easier for translators using web tools like Crowdin or Lokalise) +2. On release, flatten + batch-convert through JSONPrism into `Resources..resx` +3. Drop into the .NET project, commit +4. Visual Studio rebuilds the strongly-typed `Resources.Designer.cs` + +The same approach works for AutoClickForge (~85 files, EN/VI) and any future MVVM project you scaffold. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..523567c --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,244 @@ +# 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 + +- [x] Replace `