From 29d417ec93b8f9c34f826f2ff2b13581c4cd30a1 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:04:59 +0700 Subject: [PATCH] =?UTF-8?q?feat:=202.2.0=20=E2=80=94=20accessibility=20sta?= =?UTF-8?q?tement=20and=20fixes=20(#177)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ACCESSIBILITY.md (+ Vietnamese mirror) states the WCAG 2.2 AA goal, what works, a keyboard reference, what was tested, known limitations and how to report a barrier; new accessibility issue template. Fixes from an audit: skip link, focus after navigation and consent, visible focus everywhere incl. forced-colors, Esc-then-Tab hint and aria-invalid on the input editor, a quieter status bar, names that match visible labels, translated screen-reader strings, page zoom in the desktop apps. axe-core scan in CI. Docs synced (vi PRIVACY/dev_env, README credits, ROADMAP). Version 2.2.0. Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/accessibility.md | 58 ++++ .github/ISSUE_TEMPLATE/bug_report.md | 6 +- .github/ISSUE_TEMPLATE/feature_request.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 1 + ACCESSIBILITY.md | 323 ++++++++++++++++++ CHANGELOG.md | 73 ++++ CLAUDE.md | 11 +- CONTRIBUTING.md | 22 +- DISCLAIMER.md | 4 +- MAINTAINERS.md | 4 + README.md | 18 +- README.vi.md | 18 +- SECURITY.md | 2 +- THIRD-PARTY.md | 5 +- docs/ROADMAP.md | 60 +++- docs/TAURI-NOTES.md | 13 + docs/i18n/vi/ACCESSIBILITY.md | 321 +++++++++++++++++ docs/i18n/vi/PRIVACY.md | 16 +- docs/i18n/vi/dev_env.md | 2 +- docs/tested-viewports.md | 6 + package-lock.json | 15 +- package.json | 3 +- src-tauri/Cargo.lock | 2 +- src-tauri/Cargo.toml | 2 +- src-tauri/capabilities/default.json | 3 +- src-tauri/license.rtf | 8 +- src-tauri/tauri.conf.json | 3 +- src/app/__tests__/a11y.test.tsx | 179 ++++++++++ src/components/common/ConsentGate.tsx | 6 + src/components/common/LanguageSwitcher.tsx | 3 +- src/components/common/RouteFallback.tsx | 7 +- src/components/common/ScrollToTop.tsx | 3 + src/components/common/ToolbarButton.tsx | 4 + .../__tests__/LanguageSwitcher.test.tsx | 18 +- .../common/__tests__/RouteFallback.test.tsx | 3 +- .../common/__tests__/ScrollToTop.test.tsx | 12 + src/components/converter/BatchPanel.tsx | 3 +- src/components/converter/CodeEditor.tsx | 42 ++- src/components/converter/CodeEditorLazy.tsx | 6 +- .../converter/ConverterWorkspace.tsx | 16 +- src/components/converter/FormatPicker.tsx | 12 +- src/components/converter/InputPanel.tsx | 6 +- src/components/converter/OutputPanel.tsx | 7 +- src/components/converter/SettingsPanel.tsx | 2 + src/components/converter/StatusBar.tsx | 17 +- .../converter/__tests__/CodeEditor.test.tsx | 20 ++ .../__tests__/ConverterWorkspace.test.tsx | 2 + .../converter/__tests__/OutputPanel.test.tsx | 6 +- .../converter/__tests__/StatusBar.test.tsx | 6 + src/components/layout/AppearanceMenu.tsx | 3 +- src/components/layout/Layout.tsx | 39 ++- .../layout/__tests__/AppearanceMenu.test.tsx | 3 +- src/components/ui/sonner.tsx | 1 + .../__tests__/useKeyboardShortcuts.test.tsx | 13 +- src/hooks/useKeyboardShortcuts.ts | 5 + src/i18n/locales/en.json | 31 +- src/i18n/locales/ja.json | 33 +- src/i18n/locales/vi.json | 33 +- src/i18n/locales/zh-CN.json | 33 +- src/lib/focus.ts | 14 + src/pages/About.tsx | 7 +- src/pages/Home.tsx | 2 + src/styles/globals.css | 36 ++ src/test/axe.ts | 20 ++ 64 files changed, 1545 insertions(+), 109 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/accessibility.md create mode 100644 ACCESSIBILITY.md create mode 100644 docs/i18n/vi/ACCESSIBILITY.md create mode 100644 src/app/__tests__/a11y.test.tsx create mode 100644 src/lib/focus.ts create mode 100644 src/test/axe.ts diff --git a/.github/ISSUE_TEMPLATE/accessibility.md b/.github/ISSUE_TEMPLATE/accessibility.md new file mode 100644 index 0000000..ec45a02 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/accessibility.md @@ -0,0 +1,58 @@ +--- +name: Accessibility issue +about: Something is hard or impossible to use with a keyboard, screen reader, zoom or other assistive technology +title: '[A11Y] ' +labels: ['accessibility', 'needs-triage'] +assignees: [] +--- + + + +## What were you trying to do? + +For example: convert JSON to CSV, open a file, download the output, run a +batch, change an option, get past the consent screen. + +## What happened? + +What you expected, and what you got instead (for example: nothing was +announced, focus got stuck, text was unreadable at 200 % zoom). + +## Steps to reproduce + +1. Go to '...' +2. Press / say '...' +3. See '...' + +## Your setup + +- Assistive technology and version: [e.g. NVDA 2026.3, VoiceOver, TalkBack, Narrator, Dragon, screen magnifier, none] +- How you use the app: [keyboard only / screen reader / voice control / switch access / zoom or magnification / Windows contrast theme / other] +- Platform: [Web / Windows / macOS / Linux / Android] +- JSONPrism version: [e.g. 2.2.0 — see About → Build info] +- Browser (web) or OS version (apps): [e.g. Firefox on Windows 11, Safari on macOS 15, Android 15] + +## How much does it block you? + +- [ ] **Critical** — I can't complete the task at all +- [ ] **High** — I can, but only with a lot of effort or a workaround +- [ ] **Medium** — confusing or inconsistent, but I can finish the task +- [ ] **Low** — a minor annoyance + +## Workaround + +Did you find a way around it? It helps others while a fix is on the way. + +## Diagnostics, recordings or screenshots + +Optional. **About → Build info → Copy diagnostics** gives the version, +platform and recent log lines (check it for anything private first). A +short screen or screen-reader recording also helps. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c701e7b..cb5ea8b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -10,6 +10,9 @@ assignees: [] Security vulnerabilities do NOT belong in a public issue. Report them privately through https://github.com/poli0981/jsonPrism/security/advisories/new or by email to security@poli0981.dev. + +Something hard or impossible to use with a keyboard, screen reader, zoom or +other assistive technology? Use the "Accessibility issue" template instead. --> ## Describe the bug @@ -42,9 +45,10 @@ What actually happened. Include the error message and target format. ## Environment - Platform: [Web / Windows / macOS / Linux / Android] -- JSONPrism version: [e.g. 2.0.0 — see About → Build info] +- JSONPrism version: [e.g. 2.2.0 — see About → Build info] - Browser (web) or OS version (apps): [e.g. Firefox on Windows 11, Safari on macOS 15, Ubuntu 24.04, Android 15] - Where: [the website https://jsonprism.poli0981.dev / an installed release / a local dev build] +- Assistive technology, if any: [e.g. NVDA 2026.3, VoiceOver, keyboard only, 200 % zoom] ## Diagnostics diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 6d84560..0c15ae7 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -22,7 +22,7 @@ Other approaches you thought about, and why this one fits better. Where would you use it? [All / Web / Windows / macOS / Linux / Android] -Version you're on: [e.g. 2.0.0 — see About → Build info] +Version you're on: [e.g. 2.2.0 — see About → Build info] ## Sample data (if applicable) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b11532e..c2e7ee8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -35,6 +35,7 @@ CI must pass before the PR can be merged. - [ ] `npm run cf:check` - [ ] Rust changed: `cargo fmt --check` and `cargo clippy --all-targets --locked -- -D warnings` in `src-tauri/` - [ ] Manual smoke (describe what you clicked / loaded, and on which platform: Web / Windows / macOS / Linux / Android) +- [ ] UI changed: keyboard-only pass of what changed (visible focus, nothing stuck), accessible names in all four locales, `motion-safe:` animations, no colour-only meaning — see [ACCESSIBILITY.md](https://github.com/poli0981/jsonPrism/blob/main/ACCESSIBILITY.md#contributor-expectations). Screen reader used, if any: ## Screenshots / recordings (UI changes only) diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md new file mode 100644 index 0000000..9a599a3 --- /dev/null +++ b/ACCESSIBILITY.md @@ -0,0 +1,323 @@ +# Accessibility + +**Last reviewed**: 2026-11-09 · **Applies to**: JSONPrism 2.2.0 (website, desktop and Android apps) + +JSONPrism should work for everyone who needs to convert JSON, whatever +input device, screen reader, display setting or language they use. This +statement covers our goals, what works today, how it was tested, what is +known not to work yet, and how to report a barrier. + +JSONPrism is a one-person project (see [DISCLAIMER.md](DISCLAIMER.md)). +This page describes honest best effort, not a certified result. + +## Goals + +- **Target: [WCAG 2.2](https://www.w3.org/TR/WCAG22/) level AA.** The + website and the apps share one interface, so the target covers all of + them. It is a goal, not a claim of conformance: there has been no formal + audit. +- **Priorities, in order:** + 1. Every task works with the keyboard alone: converting, opening and + saving files, batch conversion, options and the consent screen. + 2. Every control has a name, role and state that screen readers + announce, in the interface language. + 3. Content stays readable with high contrast, zoom, light or dark + themes, reduced motion and Windows contrast themes. +- **Accessibility regressions are bugs.** They are triaged and fixed like + any other bug (see [Reporting accessibility + issues](#reporting-accessibility-issues)). + +## What works today + +### Keyboard + +- Every interactive element is a native button, link or form control, or + a Radix UI component with built-in keyboard support. No element has a + positive `tabindex`. +- **Skip to content** is the first tab stop. After you move to another + page, focus moves to that page's content. +- Every focused control shows a visible focus indicator. +- **Dialogs and sheets** (Options, Batch, format picker): + - focus stays inside them while they are open; + - Escape closes them; + - focus then returns to the button that opened them. +- **The consent screen** keeps focus inside and must be answered; after + you accept, focus moves to the page content. +- **The input editor:** Tab indents. To leave it, press **Escape, then + Tab** (WCAG 2.1.2). The editor's screen-reader description and the + status bar both say so. +- The read-only output and the other scroll areas take focus and scroll + with the arrow and Page keys. +- **Drop zones have keyboard equivalents:** **Open** in the input panel, + **click to browse** in Batch. + +### Screen readers + +- **Page structure:** + - landmarks (banner, navigation, main, content info); + - one `h1` per page; + - a translated page title on every route. +- `` follows the interface language. Each language name in the + switcher has its own `lang`. +- **The editors:** + - Both have names, such as "Input JSON" and "CSV output (read-only)". + - The input editor reports whether its content parses (`aria-invalid`). + - The input editor is described by the current error message + (`aria-describedby`). +- **Live regions announce:** + - parse errors with line and column, and conversion failures (as alerts); + - the conversion state, but not the byte counts or timing; + - batch progress and the human check; + - the offline notice and page loading; + - notifications. +- **States and shortcuts:** + - Toggle buttons expose `aria-pressed`. + - Theme choices are radio buttons, and on/off settings are switches. + - The download and options shortcuts are exposed with `aria-keyshortcuts`. +- Decorative icons are hidden from assistive technology, and icon-only + buttons have names. +- The editor's own announcements (search, replace, folding) and its + search and error panels are translated into all four interface + languages. + +### Visual + +- **Themes:** light, dark and system. + - Text colours were checked against 4.5:1 on their backgrounds in both + themes. + - The focus indicator uses the theme's ring colour, at 3:1 or more. +- **Reduced motion:** with `prefers-reduced-motion`, animations and + transitions are switched off, and Back to top jumps instead of scrolling. +- **Windows contrast themes** (`forced-colors`): focus, selected toggles and + switches are drawn in system colours. +- **No meaning from colour alone:** + - the status dot comes with a text state; + - batch rows have icons and text; + - the new-output dot on the narrow layout's Output tab also says "(new)". +- **Touch targets** meet WCAG 2.5.8: at least 24 × 24 CSS px, or spaced + so that a 24 px circle around each one doesn't overlap its neighbours. + +### Zoom and reflow + +- **Website:** browser zoom and text resizing work, and pinch-zoom is + never blocked. +- **Desktop apps:** from 2.2.0, Ctrl/⌘ + = and Ctrl/⌘ + − zoom the window. + On Windows, Ctrl + mouse wheel also works. +- **Narrow screens:** the layout reflows to 320 CSS px wide without + horizontal scrolling. It is designed for 360 × 640 and up + ([tested viewports](docs/tested-viewports.md)). + +### Language + +The interface, including all screen-reader text, is available in English, +Tiếng Việt, 日本語 and 简体中文. + +## Keyboard reference + +| Keys | Where | Does | +| --- | --- | --- | +| Tab / Shift+Tab | Everywhere | Next / previous control | +| Enter on **Skip to content** | First Tab on a page | Jump to the page content | +| Ctrl+S (⌘S on macOS) | Converter | Download the output | +| Ctrl+, (⌘, on macOS) | Converter | Open Options | +| Escape | Dialog, sheet, Appearance menu | Close, and return focus to its button | +| ↑ ↓ Home End | Appearance menu | Move between items | +| ← → | Input / Output tabs (narrow screens) | Switch tab | +| Escape, then Tab | Input editor | Leave the editor (Tab alone indents) | +| Ctrl+M (Shift+Alt+M on macOS) | Input editor | Toggle "Tab moves focus" | +| Ctrl+] / Ctrl+[ (⌘] / ⌘[) | Input editor | Indent / outdent | +| Ctrl+F (⌘F), then F3 / Shift+F3 | Either editor | Search, next / previous match | +| Ctrl+Alt+G (⌘⌥G) | Either editor | Go to line | +| Ctrl+Shift+M (⌘⇧M), F8 | Input editor | Open the error list, next error | +| Alt+T | Anywhere | Focus notifications (pauses them) | +| Ctrl/⌘ + = and − | Desktop apps | Zoom in / out | + +## How we test + +### Tested with + +| Date | Version | Platform | Method | Result | +| --- | --- | --- | --- | --- | +| 2026-11 | 2.1.1 | Windows 11: website in Edge, Brave and Firefox; Windows app (WebView2) | Narrator; keyboard only, no mouse (maintainer) | No blocking issues | +| 2026-11-09 | 2.2.0 | Chromium (development build) | Keyboard walk-through of the 2.2.0 changes: skip link, focus after navigation and consent, focus indicators | Pass | +| Every pull request | — | jsdom in CI | [axe-core](https://github.com/dequelabs/axe-core) on every page, the consent screen and each sheet; role and name assertions with Testing Library | Must pass | +| 2026-10-22 | 2.0.0 | Chromium device emulation, 360 × 740 to 1280 × 800, light and dark | Visual layout check | See [tested viewports](docs/tested-viewports.md) | + +The automated scan runs without a real layout engine, so it can't +measure colour contrast; contrast is checked by hand. + +**Not tested yet** (reports are very welcome): + +- **Screen readers:** NVDA and JAWS (Windows), VoiceOver (macOS, iOS), + TalkBack (Android), Orca (Linux). +- **Voice control:** Dragon, Voice Access. +- **On real devices:** Windows contrast themes, and Android system font + size. + +### Manual check before a release + +1. **Keyboard only.** Work through every main flow: + - convert, open a file, download; + - run a batch to a `.zip`; + - change options, theme and language; + - pass the consent screen. + + Check that focus is always visible and never stuck. +2. **Screen reader.** Use Narrator, NVDA or VoiceOver for the same flows. + Listen for names, states, errors and the conversion state. +3. **Zoom.** Check at 200 % and at 400 % in a 1280 px wide window, plus + text-only zoom where the browser offers it. +4. **Display settings.** Check with a Windows contrast theme, with reduced + motion, and in light and dark themes. +5. **Automated scan.** Run `npm test`, which includes the axe-core scan. + +## Supported environments + +| Surface | Engine | Assistive technology checked | +| --- | --- | --- | +| Website | Current Chrome, Edge, Brave, Firefox and Safari (engine floor: Chromium 111, WebKit of macOS 12) | Narrator with Edge, Brave and Firefox | +| Windows app | Microsoft Edge WebView2 | Narrator | +| macOS app (12+) | WKWebView | — | +| Linux app (Ubuntu 22.04+) | WebKitGTK | — | +| Android app (12+) | Android System WebView, Chromium 111+ | — | + +## Known limitations + +These are the barriers we know about, with workarounds where one exists. +They are tracked in [`docs/ROADMAP.md`](docs/ROADMAP.md). + +1. **Long output in a screen reader's browse mode.** The editor keeps only + the visible lines in the page, so a virtual cursor can't read a long + result to the end. *Workaround:* **Copy** or **Download** the output and + read it in another app. +2. **Tab indents in the input editor.** *Workaround:* press Escape, then + Tab; or press Ctrl+M (Shift+Alt+M on macOS) to make Tab move focus. +3. **Small or short windows.** + - Below about 600 CSS px of height, the editors get very short. This + includes 400 % zoom in a 1280 px window. + - On phones, only portrait orientation is fully supported. + - Crossing 768 CSS px of width, for example by zooming, switches between + the side-by-side and tabbed layouts. The editors are recreated: your + text is kept, but focus and undo history are not. + + *Workaround:* zoom to 200–300 % instead. +4. **Human check (website only).** Cloudflare Turnstile runs in a + Cloudflare frame, so its accessibility is Cloudflare's. If it fails or + takes longer than 20 seconds, **Continue without the check** appears. +5. **Notifications close after 4 seconds.** Screen readers announce them + when they appear. *Workaround:* hover them, or press Alt+T to focus and + pause them. +6. **Low non-text contrast.** Text-field and switch outlines are below + 3:1 (WCAG 1.4.11). Every field is labelled, but the field boundary is + faint. +7. **Unavailable formats.** The reason a format is unavailable is in its + tooltip. Screen readers get it as the button's description, but touch + users can't see it. +8. **New tabs aren't announced.** Links that open in a new tab, or in the + system browser from the apps, don't say so. +9. **Desktop apps.** The smallest window is 800 × 560. Page zoom arrived + in 2.2.0. +10. **Android app.** It uses the WebView's default handling of system font + size and pinch-zoom, which hasn't been verified on a real device. +11. **Translations.** The Japanese and Chinese texts, including the + screen-reader texts, are AI-generated; native speakers' fixes are + welcome. + +## Contributor expectations + +Contributors check these for every change to the interface (see also +[CONTRIBUTING.md](CONTRIBUTING.md)): + +- **Elements.** Use native elements or the components in + `src/components/ui/`. Don't put click handlers on `div` or `span`, and + don't use a positive `tabindex`. +- **Names.** Every control has an accessible name from the locale files, + in all four languages. Icon-only buttons get `aria-label`, and + decorative icons get `aria-hidden`. +- **Focus.** + - Don't use `outline-none` without a `focus-visible:` replacement. + - A scroll area that takes focus gets `role="region"` and a label. + - The only exception is an element focused from code with + `tabIndex={-1}`, such as `
`. +- **Motion and colour.** Animations go behind `motion-safe:`. Don't show + meaning with colour alone. +- **Announcements.** Use the existing live regions, and keep + announcements short. Don't announce text that changes on every + keystroke. +- **Testing.** + - `npm test` must pass, including the axe-core scan in + `src/app/__tests__/a11y.test.tsx`. Extend the scan for new pages and + dialogs. + - Do a keyboard-only pass of what you changed and say so in the pull + request. + - A screen-reader spot check is welcome too. +- **This file.** Update it when behaviour or a known limitation changes. + +## Reporting accessibility issues + +Open an issue with the **[Accessibility +issue](https://github.com/poli0981/jsonPrism/issues/new?template=accessibility.md)** +template. Include: + +- what you were trying to do and what happened instead; +- your assistive technology and its version; +- the browser or app version, and your operating system. + +You don't need to know the cause. + +If you can't or would rather not use GitHub, email +**code@poli0981.dev** with "Accessibility" in the subject. Security +problems go through [SECURITY.md](SECURITY.md) instead. + +### Severity + +| Severity | Meaning | Example | +| --- | --- | --- | +| Critical | Blocks a core task, with no workaround | You can't convert, open, save or get past the consent screen with your keyboard or screen reader | +| High | Major difficulty, but a workaround exists | An error is never announced, but it shows in the output panel | +| Medium | Inconsistent or confusing, but the task is possible | A wrong or missing label; focus lands in an odd place | +| Low | Minor annoyance | Verbose announcements; an untranslated hint | + +### How we respond + +- We thank you and ask questions if something is unclear. We never ask + you to justify why you need an accessibility feature. +- We add the `accessibility` label, set a severity, and triage blockers + before cosmetic issues. +- We share a workaround as soon as we know one. +- When a fix is ready, we ask you to confirm it, if you are willing. Fixes + are listed in [CHANGELOG.md](CHANGELOG.md). + +### Response times + +This is best effort from a one-person project: + +| Severity | First response | Fix released | +| --- | --- | --- | +| Critical | within 7 days | next patch release | +| High | within 14 days | next release | +| Medium / Low | within 30 days | when practical, usually the next minor release | + +## Ownership and maintenance + +Kokone ([@poli0981](https://github.com/poli0981)), the sole maintainer +(see [MAINTAINERS.md](MAINTAINERS.md)), owns accessibility. That covers: + +- triaging reports; +- tracking them with the `accessibility` label; +- running the [manual check](#manual-check-before-a-release) before + releases; +- keeping this statement current, including its review date. + +## Feedback + +Suggestions for this statement are welcome as an issue or a pull request. + +A [Vietnamese translation](docs/i18n/vi/ACCESSIBILITY.md) is available. If +the two differ, this English version prevails. + +This statement follows the structure recommended by the Open Source Guides +([Accessibility best practices for your +project](https://opensource.guide/accessibility-best-practices-for-your-project/)) +and the [Open Source Accessibility +toolkit](https://github.com/open-source-accessibility/accessibility-toolkit). diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a35b35..7800142 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,79 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and No unreleased changes at this time. Future work tracked in `docs/ROADMAP.md` under "Beyond". +## [2.2.0] — 2026-11-09 + +An accessibility release. JSONPrism now has an accessibility statement, [`ACCESSIBILITY.md`](ACCESSIBILITY.md), which targets WCAG 2.2 AA. The maintainer's keyboard-only and Narrator pass on 2.1.1 found no blocking issues; this release fixes the gaps an audit found beyond that pass. `bundle.android.versionCode` 20200. + +### Added + +- **Skip to content.** The first Tab stop on every page jumps past the header to the page content. +- **Focus follows you.** + - After you move to another page, focus moves to its content. + - After you accept the consent screen, focus moves to the page instead of being lost. + - **Back to top** returns focus to the page it scrolled. +- **Zoom in the desktop apps.** Ctrl/⌘ + = and Ctrl/⌘ + − zoom the window; on Windows, Ctrl + mouse wheel works too. This adds the `core:webview:allow-set-webview-zoom` permission, which macOS and Linux need for zooming. +- **How to leave the input editor.** Tab still indents. Screen readers now hear "press Escape, then Tab, to leave the editor", and the status bar shows the same hint on wide screens. +- **Screen-reader states for the input editor:** + - The input editor reports invalid input (`aria-invalid`). + - It is described by the current error message. + - **Download** and **Options** announce their keyboard shortcuts (`aria-keyshortcuts`). +- **Accessibility statement.** [`ACCESSIBILITY.md`](ACCESSIBILITY.md) and its [Vietnamese translation](docs/i18n/vi/ACCESSIBILITY.md) cover: + - goals; + - what works; + - a keyboard reference; + - what has been tested; + - known limitations with workarounds; + - how to report a barrier, with severity levels and response times. + + The About page links the statement, and there is a new **Accessibility issue** template. + +### Changed + +- **Focus is always visible.** + - Controls without their own ring now get a themed outline. + - Scroll areas, the editors, the narrow-screen tab panels and the theme choices now show a ring. + - Windows contrast themes keep focus, pressed and selected states, and switches visible. +- **The status bar is quieter for screen readers.** Only the conversion state is announced, not the byte counts and timing that change on every keystroke. +- **Accessible names match what you see** (WCAG 2.5.3): + - The language buttons are named "EN English", "JA 日本語" and so on. + - **Copy** is named **Copied** while it says so. +- **The unread-output dot** on the narrow layout's Output tab is also announced, as "(new)". +- **Navigation labels** in Vietnamese, Japanese and Chinese no longer repeat the word "navigation". +- **Translations.** These now follow the interface language: + - the Home page title; + - the notification close button; + - CodeMirror's screen-reader announcements for search, replace, folding and deleted selections. + +### Fixed + +- **The Appearance button** no longer claims to open a menu (`aria-haspopup`). It is a disclosure for a panel. +- **The About page and the batch queue.** Their scroll areas are labelled regions, so the label is valid ARIA. +- **The format picker sheet** on phones has a description, which also removes Radix's console warning. +- **Page loading** is announced (`role="status"`), and the output panel's loading spinner is exposed as an image with a label. + +### Tests + +- **axe-core scan.** It covers every page, the input in an error state, the consent screen, and the Options, Batch and format-picker sheets. A guard test checks that the scan really reports violations. +- **Focus tests.** They cover the skip link, focus after navigation and after consent, and Back to top. +- **Unit tests** for the new attributes and labels. + +### Docs + +- **Accessibility guidance** for contributors: + - CONTRIBUTING, CLAUDE.md and the PR template have accessibility checks. + - The bug report template asks about assistive technology. + - [`docs/tested-viewports.md`](docs/tested-viewports.md) links the accessibility checks to run before a release. +- **The Vietnamese mirrors**, `docs/i18n/vi/PRIVACY.md` and `docs/i18n/vi/dev_env.md`, now describe the site-wide rate limits added in 2.0.2. +- **Other fixes:** + - The README credits match DISCLAIMER and THIRD-PARTY. + - Outdated ROADMAP notes are corrected. + - Version examples now use 2.2.0. + +### Dependencies + +- `axe-core` 4.14.0 (MPL-2.0), test-only; nothing new ships to users. + ## [2.1.1] — 2026-11-04 A maintenance release: every dependency at its latest version, no feature or behavior change. It supersedes Dependabot PRs #163–#169. `bundle.android.versionCode` 20101. diff --git a/CLAUDE.md b/CLAUDE.md index 20cf0f1..c1cbf22 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,7 @@ GitHub Pages (`poli0981.github.io/jsonPrism`) now only redirects to the new doma The maintainer is **Kokone** ([@poli0981](https://github.com/poli0981)). Audience: the developer community on the open-source Discord server plus YouTube viewers who watch indie/visual-novel gameplay and occasionally want a quick devtool. -**Current release**: 2.1.1. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for what is next. +**Current release**: 2.2.0. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for what is next. ## Stack — exact versions matter @@ -87,6 +87,15 @@ The same React UI runs in the browser and in Tauri (desktop + Android). - **Tailwind class order**: rely on `prettier-plugin-tailwindcss`; never hand-sort. - **Don't fight the theme system**. Use the tokens (`--color-prism-*`, `--color-success`, `--color-warning`, `bg-background`, …), which have separate light and dark values. No hard-coded hex. Animations go behind `motion-safe:`. - **i18n everything user-facing** in all four locales: `en.json`, `vi.json`, `ja.json`, `zh-CN.json` (`src/i18n/__tests__/locales.test.ts` enforces key parity). Libraries return error *codes*; components translate them. +- **Accessibility** (target WCAG 2.2 AA; see [`ACCESSIBILITY.md`](ACCESSIBILITY.md)). There is no `eslint-plugin-jsx-a11y` (it doesn't support ESLint 10); the axe-core scan in `src/app/__tests__/a11y.test.tsx` is the automated check, so extend it for new pages and dialogs. + - **Elements:** native elements or the Radix-based `ui/` components only. No click handlers on `div`/`span`, no positive `tabIndex`. + - **Names:** every control has an accessible name from i18n. Icon-only buttons get `aria-label` and decorative icons `aria-hidden`. The name starts with the visible label (WCAG 2.5.3). + - **Focus:** + - Never `outline-none` without a `focus-visible:ring-*` replacement; the one exception is an element focused only from code with `tabIndex={-1}`, like `
`. + - A focusable scroll area needs `role="region"` and an `aria-label`. + - Move focus with `focusMain()` (`src/lib/focus.ts`) when content is replaced. + - **Announcements:** use the existing live regions (input error, output alert, status-bar state, batch chips, toasts). Never announce text that changes on every keystroke. + - **Docs:** a behaviour change or new known limitation updates `ACCESSIBILITY.md` and its Vietnamese mirror. - **Logging**: use `createLogger(scope)` from `src/lib/logger.ts`, not `console.*` (ESLint warns). Logs stay in memory and feed About → Copy diagnostics; never log user content. - **Heavy work off the main thread**: conversions of large inputs and batch jobs go through `src/lib/convert-client.ts` (Web Worker); keep `convert-worker.ts` free of DOM access. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f56fba..c800475 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,9 +59,17 @@ npm run tauri:android:dev # Android emulator or device requirements). For tool versions, `package.json` and this file are authoritative. -3. **Keep PRs focused.** One feature or one fix per PR. Refactors as separate PRs. +3. **Keep the UI accessible.** For any UI change: + - Do a keyboard-only pass of what you changed: focus is visible and never stuck. + - Give every control an accessible name in all four locales. + - Put animations behind `motion-safe:`. + - Extend the axe-core scan in `src/app/__tests__/a11y.test.tsx` when you add a page or dialog. -4. **Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md)**: what + [`ACCESSIBILITY.md`](ACCESSIBILITY.md#contributor-expectations) has the full list. + +4. **Keep PRs focused.** One feature or one fix per PR. Refactors as separate PRs. + +5. **Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md)**: what changed, why, how you tested it, screenshots if UI, and whether AI tools helped. @@ -170,6 +178,16 @@ Use the [Bug Report](https://github.com/poli0981/jsonPrism/issues/new?template=b Security vulnerabilities never go in a public issue. See [SECURITY.md](SECURITY.md). +### Accessibility issues + +Something hard or impossible to use with a keyboard, screen reader, zoom or other assistive technology? Use the [Accessibility issue](https://github.com/poli0981/jsonPrism/issues/new?template=accessibility.md) template. You don't need to know the cause. [ACCESSIBILITY.md](ACCESSIBILITY.md) covers: + +- what is supported and tested; +- the known limitations; +- how reports are triaged. + +Fixes for those limitations are welcome. + ### Feature requests Use the [Feature Request](https://github.com/poli0981/jsonPrism/issues/new?template=feature_request.md) template. We prioritize features that: diff --git a/DISCLAIMER.md b/DISCLAIMER.md index d5def58..40e198d 100644 --- a/DISCLAIMER.md +++ b/DISCLAIMER.md @@ -1,6 +1,6 @@ # Disclaimer -**Last updated**: 2026-10-22 +**Last updated**: 2026-11-09 ## Project status @@ -28,7 +28,7 @@ Apache 2.0 disclaimer-of-warranty clause applies in full. This project openly uses AI tools during development: - **Claude Chat** and **Claude Code** — Claude Opus 4.7 and 4.8 for the 1.x - releases, Claude Opus 5.5 for 2.0 — used for drafting code, + releases, Claude Opus 5.5 for 2.x — used for drafting code, refactoring, writing tests and documentation, generating translations and reviewing changes. - All AI-generated code is reviewed by the maintainer before it is merged. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 5965891..eec878c 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -20,6 +20,9 @@ merged PR. Cloudflare Workers Builds. - **Translations review** — the AI-generated Japanese and Simplified Chinese strings and the partly AI-generated Vietnamese ones. +- **Accessibility** — triages reports labelled `accessibility`, runs the + manual checks before a release and keeps + [ACCESSIBILITY.md](ACCESSIBILITY.md) current. - **Community** — issues, Discussions and the Discord server, and enforcement of the [Code of Conduct](CODE_OF_CONDUCT.md). Vulnerability reports are triaged as described in [SECURITY.md](SECURITY.md). @@ -27,6 +30,7 @@ merged PR. ## Contact - Bug reports & feature requests: [GitHub Issues](https://github.com/poli0981/jsonPrism/issues) +- Accessibility barriers: the [Accessibility issue](https://github.com/poli0981/jsonPrism/issues/new?template=accessibility.md) template, or [code@poli0981.dev](mailto:code@poli0981.dev) — see [ACCESSIBILITY.md](ACCESSIBILITY.md) - Discussion / Q&A: [GitHub Discussions](https://github.com/poli0981/jsonPrism/discussions) - Community chat: [Discord](https://discord.gg/2aNR3aVt) - Project, maintainer & Code of Conduct: [code@poli0981.dev](mailto:code@poli0981.dev) diff --git a/README.md b/README.md index 6222b5c..1490a77 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,19 @@ Twelve target formats. Six of them — JSONL, CSV, TSV, YAML, TOML and RESX — Details: [`PRIVACY.md`](PRIVACY.md). +## Accessibility + +JSONPrism aims for **WCAG 2.2 AA** on the website and in the apps: + +- **Keyboard:** everything works with the keyboard alone, with a skip link and a visible focus indicator. +- **Screen readers:** controls have names, and errors and state changes are announced, in all four languages. +- **Display:** light, dark or system theme with text at 4.5:1 or better, plus support for reduced motion and Windows contrast themes. +- **Zoom:** works on the website, and in the desktop apps with Ctrl/⌘ + = and −. + +The maintainer tests it with Narrator and the keyboard alone, and every pull request runs an axe-core scan. + +Known limitations and how to report a barrier: [`ACCESSIBILITY.md`](ACCESSIBILITY.md). + ## Tech stack - **Vite 8** + **React 19.3** + **TypeScript 7** (native compiler; the `typescript` dependency is a TS 6 alias kept only for typescript-eslint) @@ -328,6 +341,7 @@ Bug reports and feature requests belong in [GitHub Issues](https://github.com/po | [`PRIVACY.md`](PRIVACY.md) | What stays on your device, and the web-only Cloudflare services (hosting, Turnstile, Web Analytics). | | [`TERMS.md`](TERMS.md) | ToS / EULA — acceptable use, license inheritance, user data ownership. | | [`SECURITY.md`](SECURITY.md) | How to report vulnerabilities; response SLAs. | +| [`ACCESSIBILITY.md`](ACCESSIBILITY.md) | Accessibility goals (WCAG 2.2 AA), what's tested, known limitations, how to report a barrier. | | [`DISCLAIMER.md`](DISCLAIMER.md) | One-person + AI-assisted project; no warranty. | | [`THIRD-PARTY.md`](THIRD-PARTY.md) | Every dependency: version, license, link. | | [`MAINTAINERS.md`](MAINTAINERS.md) | Who's responsible for what. | @@ -353,8 +367,8 @@ Hang out, ask questions, or follow updates: Substantial parts of JSONPrism's code, tests, translations, and docs were drafted with AI assistance: **Claude Chat** and **Claude Code -(Opus 4.7, 1M context)** for v1.x, and **Claude Code (Opus 5.5)** for -v2.0.0. See [DISCLAIMER.md](DISCLAIMER.md) for the full AI-assist +(Opus 4.7 and 4.8)** for v1.x, and **Claude Code (Opus 5.5)** for +v2.x. See [DISCLAIMER.md](DISCLAIMER.md) for the full AI-assist disclosure. The Japanese and Simplified Chinese translations, and parts of the Vietnamese one, are AI-generated and best-effort; contributions from native speakers are welcomed. diff --git a/README.vi.md b/README.vi.md index 63a411e..7e852fb 100644 --- a/README.vi.md +++ b/README.vi.md @@ -62,6 +62,19 @@ Tổng cộng 12 định dạng đích. Sáu trong số đó — JSONL, CSV, TSV Chi tiết: [`PRIVACY.md`](PRIVACY.md). +## Trợ năng (Accessibility) + +JSONPrism hướng tới **WCAG 2.2 AA** trên website lẫn các app: + +- **Bàn phím:** mọi thao tác dùng được chỉ bằng bàn phím, có skip link và chỉ báo focus rõ ràng. +- **Trình đọc màn hình:** control có tên, lỗi và thay đổi trạng thái được đọc lên, đủ bốn ngôn ngữ. +- **Hiển thị:** theme sáng, tối hoặc theo hệ thống với chữ tương phản từ 4.5:1, hỗ trợ giảm chuyển động và contrast theme của Windows. +- **Phóng to:** dùng được trên website, và trong app desktop bằng Ctrl/⌘ + = và −. + +Maintainer kiểm thử bằng Narrator và chỉ dùng bàn phím, mỗi pull request đều chạy bài quét axe-core. + +Hạn chế đã biết và cách báo rào cản: [`ACCESSIBILITY.md`](ACCESSIBILITY.md) ([bản tiếng Việt](docs/i18n/vi/ACCESSIBILITY.md)). + ## Tech stack - **Vite 8** + **React 19.3** + **TypeScript 7** (compiler native; dependency `typescript` là alias TS 6, chỉ giữ lại cho typescript-eslint) @@ -328,6 +341,7 @@ Báo bug và đề xuất tính năng vui lòng gửi qua [GitHub Issues](https: | [`PRIVACY.md`](PRIVACY.md) | Những gì ở lại trên thiết bị, và các dịch vụ Cloudflare chỉ dùng cho website (hosting, Turnstile, Web Analytics). | | [`TERMS.md`](TERMS.md) | ToS / EULA — acceptable use, kế thừa giấy phép, quyền sở hữu dữ liệu. | | [`SECURITY.md`](SECURITY.md) | Cách report vulnerability, SLA. | +| [`ACCESSIBILITY.md`](ACCESSIBILITY.md) · [`docs/i18n/vi/ACCESSIBILITY.md`](docs/i18n/vi/ACCESSIBILITY.md) | Mục tiêu trợ năng (WCAG 2.2 AA), những gì đã kiểm thử, hạn chế đã biết, cách báo rào cản. | | [`DISCLAIMER.md`](DISCLAIMER.md) | Project 1 người + AI-assisted, không bảo hành. | | [`THIRD-PARTY.md`](THIRD-PARTY.md) | Mỗi dependency: version, giấy phép, link. | | [`MAINTAINERS.md`](MAINTAINERS.md) | Ai chịu trách nhiệm gì. | @@ -352,8 +366,8 @@ Trò chuyện, hỏi đáp, hoặc theo dõi cập nhật: ## Ghi nhận Phần lớn code, test, bản dịch và tài liệu của JSONPrism được draft với -sự hỗ trợ của AI: **Claude Chat** và **Claude Code (Opus 4.7, 1M -context)** cho v1.x, **Claude Code (Opus 5.5)** cho v2.0.0. Xem +sự hỗ trợ của AI: **Claude Chat** và **Claude Code (Opus 4.7 và +4.8)** cho v1.x, **Claude Code (Opus 5.5)** cho v2.x. Xem [DISCLAIMER.md](DISCLAIMER.md) để biết chi tiết về AI-assist. Bản dịch tiếng Nhật, tiếng Trung giản thể và một phần bản tiếng Việt do AI tạo, chất lượng ở mức best-effort — rất hoan nghênh đóng góp từ người bản ngữ. diff --git a/SECURITY.md b/SECURITY.md index 79dfc19..d9b7f6c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -78,7 +78,7 @@ attestations generated in GitHub Actions: ```bash sha256sum -c SHA256SUMS.txt --ignore-missing -gh attestation verify JSONPrism_2.0.0_x64-setup.exe --repo poli0981/jsonPrism +gh attestation verify JSONPrism_2.2.0_x64-setup.exe --repo poli0981/jsonPrism ``` The desktop installers are not yet code-signed, so Windows SmartScreen diff --git a/THIRD-PARTY.md b/THIRD-PARTY.md index e0627b5..f138429 100644 --- a/THIRD-PARTY.md +++ b/THIRD-PARTY.md @@ -3,7 +3,7 @@ JSONPrism is built on top of open-source libraries. This page lists each direct dependency declared in [`package.json`](package.json) and [`src-tauri/Cargo.toml`](src-tauri/Cargo.toml), the exact version used by -**JSONPrism 2.1.1**, the upstream license, and a link to the project. It +**JSONPrism 2.2.0**, the upstream license, and a link to the project. It also lists the third-party services the website uses. Versions are the ones locked in [`package-lock.json`](package-lock.json) @@ -145,6 +145,7 @@ shipped in the app. | `@testing-library/dom` | 10.4.2 | MIT | [testing-library.com](https://testing-library.com/) | | `@testing-library/jest-dom` | 7.0.1 | MIT | [testing-library.com](https://testing-library.com/) | | `@testing-library/user-event` | 14.6.8 | MIT | [testing-library.com](https://testing-library.com/) | +| `axe-core` | 4.14.0 | MPL-2.0 | [github.com/dequelabs/axe-core](https://github.com/dequelabs/axe-core) | | `@types/node` | 26.6.6 | MIT | [github.com/DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) | | `@types/papaparse` | 5.5.2 | MIT | [github.com/DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) | | `@types/react` | 19.3.0 | MIT | [github.com/DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) | @@ -192,7 +193,7 @@ of the project. Substantial portions of JSONPrism's code, tests, translations, and docs were drafted with AI assistance from Anthropic: **Claude Chat** + **Claude Code** with Claude Opus 4.7 and 4.8 for the 1.x releases, and -**Claude Code** with Claude Opus 5.5 for 2.0.0. The Japanese and Simplified +**Claude Code** with Claude Opus 5.5 for 2.x. The Japanese and Simplified Chinese translations, and parts of the Vietnamese one, are AI-generated. The maintainer reviews every change before it is merged. See [DISCLAIMER.md](DISCLAIMER.md). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 5ebea11..78f935e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -4,7 +4,7 @@ This document is the **single source of truth** for what's done, what's next, an Update it as work lands — keep the project status honest. -**Current release: v2.1.1 (2026-11-04).** The web app runs at https://jsonprism.poli0981.dev (Cloudflare Workers); desktop and Android builds are on [GitHub Releases](https://github.com/poli0981/jsonPrism/releases). +**Current release: v2.2.0 (2026-11-09).** The web app runs at https://jsonprism.poli0981.dev (Cloudflare Workers); desktop and Android builds are on [GitHub Releases](https://github.com/poli0981/jsonPrism/releases). --- @@ -83,8 +83,8 @@ Goal: make the four working converters production-quality and the UX delightful - [x] Keyboard shortcuts: ⌘/Ctrl+K (clear), ⌘/Ctrl+S (download) — *⌘/Ctrl+K removed in 2.0.0: it clashed with the browser's search shortcut* - [x] Status bar showing: input bytes, output bytes, parse time, shortcut hints - [x] Shape detection hint (scalar / object / array / flat-object / array-of-objects) -- [x] Disabled-format chips show "P2"/"P3" badge with tooltip -- [x] Cmd/Ctrl+, to open settings — *deferred at the time; added in a later 1.x release* +- [x] Disabled-format chips show "P2"/"P3" badge with tooltip — *badges retired once every format shipped; a disabled chip now explains why in its tooltip* +- [x] Cmd/Ctrl+, to open settings — *deferred at the time; added in 2.0.0* ### Deliverable @@ -178,7 +178,7 @@ Split into three sub-phases for digestibility. 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.** +*Written during Phase 2A, when only RESX (Phase 3) was still a stub; Phase 3 has since shipped.* --- @@ -243,7 +243,7 @@ Codebase hygiene plus a small UX addition — no converter behavior changed. - [x] Decomposed three oversized components (`BatchPanel`, `ConverterWorkspace`, `InputPanel`) into focused pure utilities, leaf components, and hooks — behavior-preserving, all 193 tests still green. - [x] Integrated `knip` for dead-code analysis: `knip.json` config, `npm run knip` script, and a CI step. Initial sweep removed orphaned code and a phantom dependency. -- [x] Scroll-to-top button on the long, scrollbar-hidden About page (respects `prefers-reduced-motion`). +- [x] Scroll-to-top button on the long, scrollbar-hidden About page (respects `prefers-reduced-motion`). — *since 2.0.0 the scrollbar shows unless **Appearance → Hide scrollbars** is on; since 2.2.0 the button hands focus back to the page* --- @@ -373,8 +373,58 @@ The most common "this isn't valid JSON" paste — config files with comments — --- +## Phase 10 — 2.2.0: Accessibility ✅ + +**Status**: complete (shipped in v2.2.0, 2026-11-09) + +The release adds an accessibility statement and fixes the gaps that an audit against WCAG 2.2 AA found. The maintainer's keyboard-only and Narrator pass on 2.1.1 found no blockers; these fixes cover what that pass didn't reach. + +- [x] **Docs and process:** + - [`ACCESSIBILITY.md`](../ACCESSIBILITY.md) and its [Vietnamese mirror](i18n/vi/ACCESSIBILITY.md): goals, what works, keyboard reference, tested-with table, supported environments, known limitations, contributor expectations, and reporting with severity levels and response times. + - An accessibility issue template and a PR checklist item. + - Rules in CONTRIBUTING and CLAUDE.md. +- [x] **Focus:** + - A skip link. + - Focus moves to `
` after a navigation and after the consent gate. + - Visible focus everywhere: a global `:focus-visible` outline, and inset rings on scroll areas and the editors. + - In Windows contrast themes (`forced-colors`), focus, the pressed or selected state, and switches stay visible. +- [x] **Input editor:** an "Escape, then Tab" hint (screen-reader description and status bar), and `aria-invalid` with `aria-describedby` pointing at the current error. +- [x] **Screen readers:** + - Only the status bar's state is a live region. + - The language buttons and Copy have names that start with their visible labels. + - Download and Options expose `aria-keyshortcuts`. + - The unread-output dot has text. + - The format-picker sheet has a description. + - Loading has `role="status"`. + - Back to top hands focus back to the content. +- [x] **Translated screen-reader strings:** + - the toast close button; + - CodeMirror's search, replace, fold and delete announcements; + - the Home page title. + + Navigation labels no longer repeat "navigation". +- [x] **Desktop apps:** page zoom with Ctrl/⌘ + = and − (`zoomHotkeysEnabled`, with the `core:webview:allow-set-webview-zoom` permission). +- [x] **Automated check:** an axe-core scan of every page, the consent gate and each sheet runs in `npm test`. The About page links the statement. + +### Deliverable + +An accessibility statement backed by tests. **949 tests in 95 files.** + +--- + ## Beyond — Ideas (no commitment) +### Accessibility follow-ups + +These are tracked as known limitations in [`ACCESSIBILITY.md`](../ACCESSIBILITY.md#known-limitations). + +- **Non-text contrast:** text-field and switch outlines at 3:1 (WCAG 1.4.11). +- **Android:** follow the system font size and allow pinch-zoom in the WebView; a TalkBack pass on a real device. +- **More screen readers:** NVDA, VoiceOver and Orca passes, and Windows contrast themes checked on real hardware. +- **Layout switch:** keep editor focus and undo history when the layout changes at 768 px. +- **New tabs:** announce links that open a new tab or the system browser. +- **Long output:** a way to read it in a screen reader's browse mode, such as a plain-text view. + ### Deferred from 2.0.0 - **Lazy-load non-English locales** — about 20 KB gzip off the first load diff --git a/docs/TAURI-NOTES.md b/docs/TAURI-NOTES.md index e3d187b..b93dc51 100644 --- a/docs/TAURI-NOTES.md +++ b/docs/TAURI-NOTES.md @@ -60,6 +60,7 @@ intentionally narrow (trimmed in 2.0.0): | Permission | Why | | --- | --- | | `core:default` | Tauri's core set (app, event, path, window, webview, …), including the `tauri://drag-drop` events. | +| `core:webview:allow-set-webview-zoom` | Page zoom (2.2.0). On macOS and Linux, `zoomHotkeysEnabled` injects a script that zooms with Ctrl/⌘ + = and − through this command. On Windows, WebView2's own zoom controls are used. | | `opener:default` | Opens `https://` and `mailto:` links in the system browser / mail app via `openUrl`. Works on Android, where the shell plugin's `open()` has no URL handler. | | `dialog:allow-open`, `dialog:allow-save` | Native open / save dialogs only — no message, ask or confirm dialogs. | | `fs:default` | The fs plugin's baseline: the app's own data directories; denies the webview data folder. | @@ -100,6 +101,18 @@ default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline' external blocking script rather than an inline one, so neither CSP needs `'unsafe-inline'` for scripts (the reason is spelled out in `index.html`). +## Page zoom + +`app.windows[0].zoomHotkeysEnabled` is `true` since 2.2.0. It is off by default in Tauri, and before 2.2.0 the desktop apps could only scale with the OS display setting (WCAG 1.4.4 Resize Text). + +| Platform | Behaviour | +| --- | --- | +| Windows | Sets WebView2's `IsZoomControlEnabled`: Ctrl + = / − and Ctrl + mouse wheel both work. | +| macOS, Linux | Tauri injects a script for Ctrl/⌘ + = / −, in 20 % steps from 20 % to 1000 %. It calls `set_webview_zoom`, so it needs the permission above. | +| Android | Not supported by Tauri. Pinch-zoom and text size follow the system WebView defaults; see the known limitations in [`ACCESSIBILITY.md`](../ACCESSIBILITY.md#known-limitations). | + +The zoom level isn't saved between launches. + ## Consent gate The first-launch Consent Gate (License, Terms, Privacy Policy, Disclaimer) diff --git a/docs/i18n/vi/ACCESSIBILITY.md b/docs/i18n/vi/ACCESSIBILITY.md new file mode 100644 index 0000000..c306a8e --- /dev/null +++ b/docs/i18n/vi/ACCESSIBILITY.md @@ -0,0 +1,321 @@ +> **Lưu ý:** Đây là bản dịch tiếng Việt chỉ mang tính tham khảo. Nếu có +> bất kỳ khác biệt nào giữa bản dịch này và +> [bản gốc tiếng Anh](../../../ACCESSIBILITY.md), bản tiếng Anh được ưu +> tiên áp dụng. + +# Trợ năng (Accessibility) + +**Rà soát lần cuối**: 2026-11-09 · **Áp dụng cho**: JSONPrism 2.2.0 (website, ứng dụng desktop và Android) + +JSONPrism muốn ai cần chuyển đổi JSON cũng dùng được, bất kể họ dùng +thiết bị nhập nào, trình đọc màn hình nào, thiết lập hiển thị hay ngôn +ngữ nào. Tài liệu này nêu mục tiêu, những gì đang hoạt động, cách đã kiểm +thử, những gì còn chưa ổn và cách báo một rào cản. + +JSONPrism do một người duy trì (xem [DISCLAIMER.md](../../../DISCLAIMER.md)). +Đây là nỗ lực thành thật hết mức có thể, không phải kết quả được chứng nhận. + +## Mục tiêu + +- **Đích: [WCAG 2.2](https://www.w3.org/TR/WCAG22/) mức AA.** Website và + các ứng dụng dùng chung một giao diện, nên mục tiêu áp dụng cho tất cả. + Đây là mục tiêu, không phải tuyên bố đã đạt chuẩn: chưa có đợt audit + chính thức nào. +- **Ưu tiên, theo thứ tự:** + 1. Mọi việc đều làm được chỉ bằng bàn phím: chuyển đổi, mở và lưu tệp, + chuyển đổi hàng loạt (batch), tuỳ chọn và màn hình đồng ý điều khoản. + 2. Mọi control đều có tên, vai trò và trạng thái để trình đọc màn hình + đọc được, bằng ngôn ngữ của giao diện. + 3. Nội dung luôn dễ đọc khi tăng độ tương phản, phóng to, dùng theme + sáng hoặc tối, giảm chuyển động hoặc bật contrast theme của Windows. +- **Lỗi hồi quy về trợ năng là bug.** Chúng được phân loại và sửa như mọi + bug khác (xem [Báo lỗi trợ năng](#báo-lỗi-trợ-năng)). + +## Những gì đang hoạt động + +### Bàn phím + +- Mọi phần tử tương tác đều là nút, liên kết hay control form gốc của + HTML, hoặc component Radix UI có sẵn hỗ trợ bàn phím. Không phần tử nào + có `tabindex` dương. +- **Bỏ qua, tới nội dung chính** (skip link) là điểm dừng Tab đầu tiên. + Khi bạn chuyển sang trang khác, focus chuyển vào nội dung của trang đó. +- Control nào đang có focus cũng hiện chỉ báo focus. +- **Hộp thoại và sheet** (Tuỳ chọn, Batch, chọn định dạng): + - focus nằm gọn bên trong khi chúng đang mở; + - Escape đóng chúng; + - sau đó focus quay về nút đã mở chúng. +- **Màn hình đồng ý** giữ focus bên trong và phải được trả lời; sau khi + bạn đồng ý, focus chuyển vào nội dung trang. +- **Ô nhập (editor):** Tab dùng để thụt lề. Để rời khỏi editor, nhấn + **Esc rồi Tab** (WCAG 2.1.2). Mô tả cho trình đọc màn hình và thanh + trạng thái đều ghi điều này. +- Ô kết quả chỉ đọc và các vùng cuộn khác nhận được focus và cuộn bằng + phím mũi tên, Page Up/Down. +- **Vùng kéo thả có cách tương đương bằng bàn phím:** **Mở** ở ô nhập, + **click để duyệt…** trong Batch. + +### Trình đọc màn hình + +- **Cấu trúc trang:** + - landmark (banner, điều hướng, nội dung chính, chân trang); + - mỗi trang một `h1`; + - tiêu đề trang đã dịch cho mọi route. +- `` theo ngôn ngữ giao diện. Mỗi tên ngôn ngữ trong bộ chuyển + ngôn ngữ có `lang` riêng. +- **Các editor:** + - Cả hai đều có tên, ví dụ "JSON đầu vào" và "Kết quả CSV (chỉ đọc)". + - Ô nhập báo nội dung có hợp lệ hay không (`aria-invalid`). + - Ô nhập được mô tả bằng thông báo lỗi hiện tại (`aria-describedby`). +- **Live region đọc lên:** + - lỗi phân tích kèm dòng và cột, và lỗi chuyển đổi (dạng cảnh báo); + - trạng thái chuyển đổi, nhưng không đọc số byte hay thời gian; + - tiến độ batch và bước xác minh con người; + - thông báo mất mạng và trạng thái đang tải trang; + - các thông báo (notification). +- **Trạng thái và phím tắt:** + - Nút bật/tắt có `aria-pressed`. + - Lựa chọn theme là radio, các thiết lập bật/tắt là switch. + - Phím tắt tải về và mở tuỳ chọn được khai báo bằng `aria-keyshortcuts`. +- Icon trang trí được ẩn khỏi công nghệ hỗ trợ, nút chỉ có icon đều có tên. +- Các thông báo riêng của editor (tìm kiếm, thay thế, thu gọn) cùng bảng + tìm kiếm và bảng lỗi đã được dịch sang cả bốn ngôn ngữ giao diện. + +### Hiển thị + +- **Theme:** sáng, tối và theo hệ thống. + - Màu chữ đã được kiểm tra đạt 4.5:1 so với nền ở cả hai theme. + - Chỉ báo focus dùng màu ring của theme, tương phản từ 3:1 trở lên. +- **Giảm chuyển động:** khi bật `prefers-reduced-motion`, hiệu ứng động và + chuyển cảnh bị tắt, nút Về đầu trang nhảy thẳng thay vì cuộn mượt. +- **Contrast theme của Windows** (`forced-colors`): focus, nút đang được + chọn và switch được vẽ bằng màu hệ thống. +- **Không truyền tải ý nghĩa chỉ bằng màu:** + - chấm trạng thái luôn đi kèm chữ; + - các dòng trong batch có icon và chữ; + - chấm báo có kết quả mới trên tab Kết quả (bố cục hẹp) còn kèm chữ "(mới)". +- **Vùng chạm** đạt WCAG 2.5.8: tối thiểu 24 × 24 CSS px, hoặc cách nhau + đủ để vòng tròn 24 px quanh mỗi vùng không chồng lên vùng bên cạnh. + +### Phóng to và dàn lại bố cục + +- **Website:** phóng to của trình duyệt và tăng cỡ chữ đều dùng được, + không bao giờ chặn pinch-zoom. +- **Ứng dụng desktop:** từ 2.2.0, Ctrl/⌘ + = và Ctrl/⌘ + − phóng to, thu + nhỏ cửa sổ. Trên Windows dùng được cả Ctrl + con lăn chuột. +- **Màn hình hẹp:** bố cục dàn lại tới bề rộng 320 CSS px mà không cần + cuộn ngang. Bố cục được thiết kế cho 360 × 640 trở lên + ([các viewport đã kiểm thử](../../tested-viewports.md)). + +### Ngôn ngữ + +Giao diện, kể cả mọi đoạn chữ dành cho trình đọc màn hình, có tiếng Anh, +tiếng Việt, tiếng Nhật và tiếng Trung giản thể. + +## Bảng phím tắt + +| Phím | Ở đâu | Tác dụng | +| --- | --- | --- | +| Tab / Shift+Tab | Mọi nơi | Control tiếp theo / trước đó | +| Enter trên **Bỏ qua, tới nội dung chính** | Lần Tab đầu tiên của trang | Nhảy tới nội dung trang | +| Ctrl+S (⌘S trên macOS) | Trang chuyển đổi | Tải kết quả về | +| Ctrl+, (⌘, trên macOS) | Trang chuyển đổi | Mở Tuỳ chọn | +| Esc | Hộp thoại, sheet, menu Giao diện | Đóng, focus quay về nút đã mở | +| ↑ ↓ Home End | Menu Giao diện | Di chuyển giữa các mục | +| ← → | Tab Đầu vào / Kết quả (màn hình hẹp) | Chuyển tab | +| Esc rồi Tab | Ô nhập | Rời editor (chỉ Tab thì thụt lề) | +| Ctrl+M (Shift+Alt+M trên macOS) | Ô nhập | Bật/tắt chế độ "Tab chuyển focus" | +| Ctrl+] / Ctrl+[ (⌘] / ⌘[) | Ô nhập | Thụt lề / bỏ thụt lề | +| Ctrl+F (⌘F), rồi F3 / Shift+F3 | Cả hai editor | Tìm, kết quả tiếp / trước | +| Ctrl+Alt+G (⌘⌥G) | Cả hai editor | Đến dòng | +| Ctrl+Shift+M (⌘⇧M), F8 | Ô nhập | Mở danh sách lỗi, lỗi tiếp theo | +| Alt+T | Mọi nơi | Focus vào thông báo (tạm dừng chúng) | +| Ctrl/⌘ + = và − | Ứng dụng desktop | Phóng to / thu nhỏ | + +## Cách kiểm thử + +### Đã kiểm thử với + +| Ngày | Phiên bản | Nền tảng | Cách kiểm | Kết quả | +| --- | --- | --- | --- | --- | +| 2026-11 | 2.1.1 | Windows 11: website trên Edge, Brave và Firefox; ứng dụng Windows (WebView2) | Narrator; chỉ bàn phím, không dùng chuột (maintainer) | Không có lỗi chặn | +| 2026-11-09 | 2.2.0 | Chromium (bản development) | Đi bằng bàn phím qua các thay đổi của 2.2.0: skip link, focus sau khi chuyển trang và sau màn hình đồng ý, chỉ báo focus | Đạt | +| Mỗi pull request | — | jsdom trong CI | [axe-core](https://github.com/dequelabs/axe-core) trên mọi trang, màn hình đồng ý và từng sheet; kiểm tra vai trò và tên bằng Testing Library | Bắt buộc đạt | +| 2026-10-22 | 2.0.0 | Giả lập thiết bị trên Chromium, từ 360 × 740 tới 1280 × 800, sáng và tối | Kiểm tra bố cục bằng mắt | Xem [các viewport đã kiểm thử](../../tested-viewports.md) | + +Bài quét tự động chạy không có engine layout thật nên không đo được độ +tương phản màu; độ tương phản được kiểm tra thủ công. + +**Chưa kiểm thử** (rất mong nhận báo cáo): + +- **Trình đọc màn hình:** NVDA và JAWS (Windows), VoiceOver (macOS, iOS), + TalkBack (Android), Orca (Linux). +- **Điều khiển bằng giọng nói:** Dragon, Voice Access. +- **Trên thiết bị thật:** contrast theme của Windows, cỡ chữ hệ thống trên + Android. + +### Kiểm tra thủ công trước khi phát hành + +1. **Chỉ bàn phím.** Đi qua mọi luồng chính: + - chuyển đổi, mở tệp, tải về; + - chạy một batch ra tệp `.zip`; + - đổi tuỳ chọn, theme và ngôn ngữ; + - qua màn hình đồng ý. + + Kiểm tra focus luôn nhìn thấy và không bao giờ bị kẹt. +2. **Trình đọc màn hình.** Dùng Narrator, NVDA hoặc VoiceOver cho các + luồng trên. Nghe tên, trạng thái, lỗi và trạng thái chuyển đổi. +3. **Phóng to.** Kiểm tra ở 200 % và 400 % trong cửa sổ rộng 1280 px, cùng + chế độ chỉ phóng to chữ nếu trình duyệt có. +4. **Thiết lập hiển thị.** Kiểm tra với contrast theme của Windows, với + giảm chuyển động, và ở theme sáng lẫn tối. +5. **Quét tự động.** Chạy `npm test`, lệnh này bao gồm bài quét axe-core. + +## Môi trường hỗ trợ + +| Bề mặt | Engine | Công nghệ hỗ trợ đã kiểm | +| --- | --- | --- | +| Website | Chrome, Edge, Brave, Firefox và Safari bản hiện hành (engine tối thiểu: Chromium 111, WebKit của macOS 12) | Narrator với Edge, Brave và Firefox | +| Ứng dụng Windows | Microsoft Edge WebView2 | Narrator | +| Ứng dụng macOS (12+) | WKWebView | — | +| Ứng dụng Linux (Ubuntu 22.04+) | WebKitGTK | — | +| Ứng dụng Android (12+) | Android System WebView, Chromium 111+ | — | + +## Hạn chế đã biết + +Đây là các rào cản đã biết, kèm cách khắc phục tạm nếu có. Chúng được +theo dõi trong [`docs/ROADMAP.md`](../../ROADMAP.md). + +1. **Kết quả dài khi trình đọc màn hình ở chế độ duyệt (browse mode).** + Editor chỉ giữ trong trang các dòng đang hiển thị, nên con trỏ ảo không + đọc được hết một kết quả dài. *Cách khắc phục:* **Sao chép** hoặc **Tải + về** kết quả rồi đọc bằng ứng dụng khác. +2. **Tab thụt lề trong ô nhập.** *Cách khắc phục:* nhấn Esc rồi Tab; hoặc + nhấn Ctrl+M (Shift+Alt+M trên macOS) để Tab chuyển focus. +3. **Cửa sổ nhỏ hoặc thấp.** + - Khi chiều cao dưới khoảng 600 CSS px, các editor trở nên rất thấp, + kể cả khi phóng to 400 % trong cửa sổ rộng 1280 px. + - Trên điện thoại, chỉ chiều dọc được hỗ trợ đầy đủ. + - Khi bề rộng vượt qua mốc 768 CSS px, ví dụ do phóng to, bố cục chuyển + giữa dạng hai cột và dạng tab. Các editor được tạo lại: chữ của bạn + vẫn còn, nhưng focus và lịch sử hoàn tác (undo) thì không. + + *Cách khắc phục:* phóng to ở mức 200–300 %. +4. **Xác minh con người (chỉ trên website).** Cloudflare Turnstile chạy + trong một khung của Cloudflare, nên khả năng truy cập của nó thuộc về + Cloudflare. Nếu bước này lỗi hoặc quá 20 giây, nút **Tiếp tục không xác + minh** sẽ hiện ra. +5. **Thông báo tự đóng sau 4 giây.** Trình đọc màn hình đọc chúng ngay khi + xuất hiện. *Cách khắc phục:* rê chuột lên, hoặc nhấn Alt+T để focus và + tạm dừng chúng. +6. **Tương phản phi văn bản thấp.** Viền ô nhập và switch dưới 3:1 + (WCAG 1.4.11). Ô nào cũng có nhãn, nhưng đường viền mờ. +7. **Định dạng không dùng được.** Lý do một định dạng không dùng được nằm + trong tooltip. Trình đọc màn hình nhận được nó dưới dạng mô tả của nút, + nhưng người dùng màn hình cảm ứng không xem được. +8. **Không báo khi mở tab mới.** Các liên kết mở tab mới, hoặc mở trình + duyệt hệ thống từ ứng dụng, không nói điều đó. +9. **Ứng dụng desktop.** Cửa sổ nhỏ nhất là 800 × 560. Phóng to trang mới + có từ 2.2.0. +10. **Ứng dụng Android.** Ứng dụng dùng cách xử lý mặc định của WebView + với cỡ chữ hệ thống và pinch-zoom, chưa được kiểm chứng trên thiết bị + thật. +11. **Bản dịch.** Chữ tiếng Nhật và tiếng Trung, kể cả chữ dành cho trình + đọc màn hình, do AI tạo; rất hoan nghênh người bản ngữ sửa. + +## Yêu cầu với người đóng góp + +Người đóng góp kiểm tra các điểm sau với mọi thay đổi giao diện (xem thêm +[CONTRIBUTING.md](../../../CONTRIBUTING.md)): + +- **Phần tử.** Dùng phần tử HTML gốc hoặc các component trong + `src/components/ui/`. Không gắn click handler cho `div` hay `span`, không + dùng `tabindex` dương. +- **Tên.** Mọi control đều có tên accessible lấy từ các file locale, đủ cả + bốn ngôn ngữ. Nút chỉ có icon có `aria-label`, icon trang trí có + `aria-hidden`. +- **Focus.** + - Không dùng `outline-none` nếu không có thứ thay thế dạng `focus-visible:`. + - Vùng cuộn nhận focus phải có `role="region"` và nhãn. + - Ngoại lệ duy nhất là phần tử được focus từ code với `tabIndex={-1}`, + như `
`. +- **Chuyển động và màu.** Hiệu ứng động đặt sau `motion-safe:`. Không + truyền tải ý nghĩa chỉ bằng màu. +- **Thông báo.** Dùng các live region có sẵn, giữ thông báo ngắn gọn. + Không đọc lên đoạn chữ thay đổi sau mỗi lần gõ phím. +- **Kiểm thử.** + - `npm test` phải đạt, kể cả bài quét axe-core trong + `src/app/__tests__/a11y.test.tsx`. Mở rộng bài quét khi thêm trang hay + hộp thoại mới. + - Tự đi bằng bàn phím qua phần mình thay đổi và ghi lại trong pull request. + - Kiểm tra nhanh bằng trình đọc màn hình thì càng tốt. +- **Tài liệu này.** Cập nhật khi hành vi hoặc một hạn chế đã biết thay đổi. + +## Báo lỗi trợ năng + +Mở issue bằng template **[Accessibility +issue](https://github.com/poli0981/jsonPrism/issues/new?template=accessibility.md)**, +kèm theo: + +- bạn định làm gì và chuyện gì đã xảy ra; +- công nghệ hỗ trợ bạn dùng và phiên bản; +- phiên bản trình duyệt hoặc ứng dụng, và hệ điều hành. + +Bạn không cần biết nguyên nhân. + +Nếu không thể hoặc không muốn dùng GitHub, hãy email +**code@poli0981.dev**, tiêu đề có chữ "Accessibility". Vấn đề bảo mật đi +theo [SECURITY.md](../../../SECURITY.md). + +### Mức độ + +| Mức độ | Ý nghĩa | Ví dụ | +| --- | --- | --- | +| Critical | Chặn một việc chính, không có cách khắc phục | Không thể chuyển đổi, mở, lưu tệp hoặc qua màn hình đồng ý bằng bàn phím hay trình đọc màn hình | +| High | Rất khó khăn nhưng có cách khắc phục | Lỗi không bao giờ được đọc lên, nhưng có hiện trong ô kết quả | +| Medium | Không nhất quán hoặc gây khó hiểu, nhưng vẫn làm được | Nhãn sai hoặc thiếu; focus rơi vào chỗ lạ | +| Low | Phiền nhỏ | Đọc lên quá dài dòng; một gợi ý chưa được dịch | + +### Cách chúng tôi phản hồi + +- Cảm ơn bạn và hỏi lại nếu có gì chưa rõ. Không bao giờ yêu cầu bạn giải + thích vì sao bạn cần một tính năng trợ năng. +- Gắn nhãn `accessibility`, đặt mức độ, ưu tiên lỗi chặn trước lỗi về + hình thức. +- Chia sẻ cách khắc phục tạm ngay khi biết. +- Khi có bản sửa, nhờ bạn xác nhận nếu bạn sẵn lòng. Các bản sửa được ghi + trong [CHANGELOG.md](../../../CHANGELOG.md). + +### Thời gian phản hồi + +Đây là nỗ lực hết mức có thể của một dự án một người: + +| Mức độ | Phản hồi đầu tiên | Phát hành bản sửa | +| --- | --- | --- | +| Critical | trong vòng 7 ngày | bản patch kế tiếp | +| High | trong vòng 14 ngày | bản phát hành kế tiếp | +| Medium / Low | trong vòng 30 ngày | khi có thể, thường là bản minor kế tiếp | + +## Trách nhiệm và duy trì + +Kokone ([@poli0981](https://github.com/poli0981)), maintainer duy nhất +(xem [MAINTAINERS.md](../../../MAINTAINERS.md)), chịu trách nhiệm về trợ +năng, gồm: + +- phân loại báo cáo; +- theo dõi chúng bằng nhãn `accessibility`; +- chạy [bước kiểm tra thủ công](#kiểm-tra-thủ-công-trước-khi-phát-hành) + trước khi phát hành; +- giữ tài liệu này luôn cập nhật, kể cả ngày rà soát. + +## Góp ý + +Mọi góp ý cho tài liệu này đều được hoan nghênh qua issue hoặc pull request. + +Cấu trúc tài liệu theo khuyến nghị của Open Source Guides +([Accessibility best practices for your +project](https://opensource.guide/accessibility-best-practices-for-your-project/)) +và [Open Source Accessibility +toolkit](https://github.com/open-source-accessibility/accessibility-toolkit). + +[English](../../../ACCESSIBILITY.md) diff --git a/docs/i18n/vi/PRIVACY.md b/docs/i18n/vi/PRIVACY.md index fbcc677..1e69728 100644 --- a/docs/i18n/vi/PRIVACY.md +++ b/docs/i18n/vi/PRIVACY.md @@ -47,13 +47,15 @@ Cloudflare, Inc. phục vụ trang web và xử lý dữ liệu mà mọi yêu c tin TLS) để cung cấp các trang và bảo vệ dịch vụ trước hành vi lạm dụng. Phần mã phía máy chủ của riêng JSONPrism chỉ xử lý API xác minh con người (`/api/turnstile/verify`) và một điểm kiểm tra tình trạng hoạt động -(health check). Với API đó, phần mã này ghi lại các sự kiện có cấu trúc — -kết quả, trạng thái HTTP, mã trung tâm dữ liệu của Cloudflare, thời lượng -và mã lỗi Turnstile — vào Cloudflare Workers Logs, được lưu giữ trong 7 -ngày. Các sự kiện này không bao giờ chứa địa chỉ IP, token Turnstile hay -bất cứ nội dung nào bạn chuyển đổi. API này được Cloudflare giới hạn tần -suất truy cập (rate limit) theo từng máy khách; JSONPrism không lưu trữ -khoá máy khách (client key). +(health check), đồng thời tính các yêu cầu tới trang và API vào giới hạn +tần suất truy cập (rate limit) theo từng máy khách trước khi phục vụ. +Phần mã này ghi lại các sự kiện có cấu trúc — kết quả, trạng thái HTTP, +mã trung tâm dữ liệu của Cloudflare, thời lượng, mã lỗi Turnstile và các +yêu cầu bị từ chối vì vượt giới hạn — vào Cloudflare Workers Logs, được +lưu giữ trong 7 ngày. Các sự kiện này không bao giờ chứa địa chỉ IP, token +Turnstile hay bất cứ nội dung nào bạn chuyển đổi. Bộ đếm giới hạn tần +suất do Cloudflare lưu giữ, theo khoá là địa chỉ IP của bạn (với IPv6 là +mạng /64 của địa chỉ đó); JSONPrism không lưu trữ khoá này. ### Xác minh con người (trang web) diff --git a/docs/i18n/vi/dev_env.md b/docs/i18n/vi/dev_env.md index 7780de2..72236da 100644 --- a/docs/i18n/vi/dev_env.md +++ b/docs/i18n/vi/dev_env.md @@ -58,7 +58,7 @@ npm run preview:cf # wrangler dev tại http://localhost:8787 (t - `.dev.vars` chứa secret `TURNSTILE_SECRET` của Worker khi chạy local. File này đã được gitignore; tuyệt đối không đưa secret production vào đây. - `npm run preview:cf` phục vụ `dist/` giống hệt production (`_headers`, - `_redirects`, SPA fallback) cùng với Worker `/api/*`. Trên localhost app + `_redirects`, SPA fallback) phía sau Worker (rate limit, `/api/*`). Trên localhost app dùng sitekey test của Cloudflare, nên bước kiểm tra Turnstile trong Consent Gate tự pass. - `npm run cf:types` — tạo lại `worker-configuration.d.ts` (đã gitignore) sau diff --git a/docs/tested-viewports.md b/docs/tested-viewports.md index 89a66f3..12d72d7 100644 --- a/docs/tested-viewports.md +++ b/docs/tested-viewports.md @@ -68,5 +68,11 @@ Also checked in this round: 3. Pick a device from the dropdown or set a custom viewport. 4. Verify on the Home page: Header navigation visible, Input/Output Tabs accessible, FormatPicker trigger fits, no horizontal scroll on ``. 5. Repeat in light and dark (Appearance menu), pass the Consent Gate (the Turnstile test key passes on its own), and check the console for CSP violations. +6. Run the accessibility checks in [`ACCESSIBILITY.md` → Manual check before a release](../ACCESSIBILITY.md#manual-check-before-a-release): + - keyboard only; + - a screen reader; + - 200 % and 400 % zoom; + - a Windows contrast theme; + - reduced motion. Test results contributed by the maintainer. PRs welcome to expand the matrix. diff --git a/package-lock.json b/package-lock.json index 30d77ba..fe33868 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "jsonprism", - "version": "2.1.1", + "version": "2.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "jsonprism", - "version": "2.1.1", + "version": "2.2.0", "license": "Apache-2.0", "dependencies": { "@codemirror/lang-json": "^6.0.2", @@ -69,6 +69,7 @@ "@typescript/native": "npm:typescript@^7.0.2", "@vitejs/plugin-react": "^6.2.1", "@vitest/coverage-v8": "^5.1.0", + "axe-core": "^4.14.0", "eslint": "^10.14.0", "eslint-plugin-react-hooks": "^7.1.1", "eslint-plugin-react-refresh": "^0.5.7", @@ -5787,6 +5788,16 @@ "node": ">= 22" } }, + "node_modules/axe-core": { + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.14.0.tgz", + "integrity": "sha512-9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==", + "dev": true, + "license": "MPL-2.0", + "engines": { + "node": ">=4" + } + }, "node_modules/balanced-match": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", diff --git a/package.json b/package.json index c60cc66..3d22e29 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "jsonprism", "private": true, - "version": "2.1.1", + "version": "2.2.0", "type": "module", "description": "Disperse JSON into 12 formats (six convert back, plus JSONC → JSON) — JSONL, CSV, TSV, YAML, XML, TOML, RESX, Markdown, SQL, BSON, CBOR, MessagePack. Conversion runs locally in your browser or desktop app.", "author": "poli0981 (https://github.com/poli0981)", @@ -103,6 +103,7 @@ "@typescript/native": "npm:typescript@^7.0.2", "@vitejs/plugin-react": "^6.2.1", "@vitest/coverage-v8": "^5.1.0", + "axe-core": "^4.14.0", "eslint": "^10.14.0", "eslint-plugin-react-hooks": "^7.1.1", "eslint-plugin-react-refresh": "^0.5.7", diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock index fa03d56..b77b732 100644 --- a/src-tauri/Cargo.lock +++ b/src-tauri/Cargo.lock @@ -1870,7 +1870,7 @@ dependencies = [ [[package]] name = "jsonprism" -version = "2.1.1" +version = "2.2.0" dependencies = [ "serde", "serde_json", diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index e494f44..11e5ff1 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "jsonprism" -version = "2.1.1" +version = "2.2.0" description = "Disperse JSON into many formats." authors = ["poli0981 "] license = "Apache-2.0" diff --git a/src-tauri/capabilities/default.json b/src-tauri/capabilities/default.json index e75c50d..3eff4dd 100644 --- a/src-tauri/capabilities/default.json +++ b/src-tauri/capabilities/default.json @@ -1,10 +1,11 @@ { "$schema": "../gen/schemas/desktop-schema.json", "identifier": "default", - "description": "JSONPrism main window: native open/save dialogs, reading files the user picks or drops, writing where they choose to save, and opening links in the system browser. Picked and dropped paths are added to the fs scope at runtime; the static scope only covers common folders.", + "description": "JSONPrism main window: native open/save dialogs, reading files the user picks or drops, writing where they choose to save, opening links in the system browser, and page zoom (Ctrl/Cmd + and -). Picked and dropped paths are added to the fs scope at runtime; the static scope only covers common folders.", "windows": ["main"], "permissions": [ "core:default", + "core:webview:allow-set-webview-zoom", "opener:default", "dialog:allow-open", "dialog:allow-save", diff --git a/src-tauri/license.rtf b/src-tauri/license.rtf index 5504dae..d28a186 100644 --- a/src-tauri/license.rtf +++ b/src-tauri/license.rtf @@ -6,12 +6,12 @@ By installing and using JSONPrism, you agree to the terms below.\par \par JSONPrism is free, open-source software licensed under the Apache License 2.0:\par -https://github.com/poli0981/jsonPrism/blob/v2.1.1/LICENSE\par +https://github.com/poli0981/jsonPrism/blob/v2.2.0/LICENSE\par \par Your use is also governed by the following documents (version 2.0, effective 2026-10-22):\par -\bullet\tab Terms of Service (EULA): https://github.com/poli0981/jsonPrism/blob/v2.1.1/TERMS.md\par -\bullet\tab Privacy Policy: https://github.com/poli0981/jsonPrism/blob/v2.1.1/PRIVACY.md\par -\bullet\tab Disclaimer: https://github.com/poli0981/jsonPrism/blob/v2.1.1/DISCLAIMER.md\par +\bullet\tab Terms of Service (EULA): https://github.com/poli0981/jsonPrism/blob/v2.2.0/TERMS.md\par +\bullet\tab Privacy Policy: https://github.com/poli0981/jsonPrism/blob/v2.2.0/PRIVACY.md\par +\bullet\tab Disclaimer: https://github.com/poli0981/jsonPrism/blob/v2.2.0/DISCLAIMER.md\par \par JSONPrism is provided \ldblquote as is\rdblquote , without warranty of any kind. The desktop app converts everything on your device and makes no network requests of its own.\par \par diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index cac712d..725b8ef 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -22,6 +22,7 @@ "fullscreen": false, "transparent": false, "dragDropEnabled": true, + "zoomHotkeysEnabled": true, "theme": null } ], @@ -78,7 +79,7 @@ }, "android": { "minSdkVersion": 31, - "versionCode": 20101 + "versionCode": 20200 } }, "plugins": { diff --git a/src/app/__tests__/a11y.test.tsx b/src/app/__tests__/a11y.test.tsx new file mode 100644 index 0000000..1b81b09 --- /dev/null +++ b/src/app/__tests__/a11y.test.tsx @@ -0,0 +1,179 @@ +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'; +import { render, screen, waitFor, within } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { MemoryRouter } from 'react-router'; +import '@/i18n'; +import { App } from '../App'; +import { axeViolations } from '@/test/axe'; +import { useConsentStore } from '@/stores/consentStore'; +import { useWorkspaceStore } from '@/stores/workspaceStore'; + +vi.mock('@/lib/analytics', () => ({ loadWebAnalytics: vi.fn(() => false) })); + +// jsdom has no layout engine; CodeMirror measures text ranges to draw the +// cursor and selection layers. Empty geometry is enough here. +const emptyRect = { x: 0, y: 0, width: 0, height: 0, top: 0, right: 0, bottom: 0, left: 0 }; +const rangeGeometry = ['getClientRects', 'getBoundingClientRect'] as const; +const originalGeometry = rangeGeometry.map((key) => + Object.getOwnPropertyDescriptor(Range.prototype, key), +); + +beforeAll(() => { + Range.prototype.getClientRects = () => [] as unknown as DOMRectList; + Range.prototype.getBoundingClientRect = () => ({ ...emptyRect, toJSON: () => emptyRect }); +}); + +beforeEach(() => { + // axe probes for icon fonts; jsdom only logs "not implemented". + vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(null); +}); + +afterAll(() => { + rangeGeometry.forEach((key, i) => { + const original = originalGeometry[i]; + if (original) Object.defineProperty(Range.prototype, key, original); + else Reflect.deleteProperty(Range.prototype, key); + }); +}); + +function renderApp(path = '/') { + const user = userEvent.setup(); + render( + + + , + ); + return user; +} + +/** + * Waits for the real CodeMirror editor, which loads as its own chunk. Until + * then a plain