Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Changelog

## 2.30.1 — 2026-11-18

- Fix decorative image classification inside `<figure>` and add client-side Google Translate adapter (#201):
- Remove `figure` and `[role='figure']` from blocking decorative image hiding in `isFunctionalOrMeaningfulImage()`, prioritize explicit decorative markers (`data-decorative`, `.decorative`, `.deco`, `role="presentation"|"none"`, `aria-hidden="true"`), expand `hideVideos` selectors to cover `[data-video]` / `.video-placeholder`, and apply active contrast palette tokens to `targetRoot`.
- Add and export `createGoogleTranslateAdapter()` (querying Google Translate after explicit consent with in-memory caching and clean offline fallback) and set it as the default provider in `TranslationController`.
- Update `TRANSLATION.md`, `API.md`, `CSP.md`, and `examples/next-app/next.config.mjs` to document optional `connect-src 'self' https://translate.googleapis.com`.

## 2.30.0 — 2026-11-16

- UI, accessibility, modal, typography, and bug-fix improvements (#182, #183, #184, #185, #186, #187, #188, #189, #190, #191, #192, #193, #194, #195, #196, #197, #199):
Expand Down
1 change: 1 addition & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,7 @@ Opt-in research prototype controller enabling host application content translati
- `extractTranslatableNodes(root: Element, maxNodes?: number): TranslatableNode[]`: Traverses DOM tree starting from root and collects translatable text nodes, strictly skipping sensitive elements.
- `sanitizeTranslationOutput(raw: string): string`: Sanitizes translated strings, stripping control characters and null bytes.
- `applyTranslations(nodes: TranslatableNode[], translations: string[]): () => void`: Safely assigns translated strings to text nodes via `textContent` and returns an idempotent restore callback.
- `createGoogleTranslateAdapter(options?: GoogleTranslateAdapterOptions): TranslationAdapter`: Default adapter for `<TranslationController />` querying Google Translate (`translate.googleapis.com/translate_a/single`) after explicit consent, with caching and automatic offline fallback.
- `createOfflineMockTranslationAdapter(options?): TranslationAdapter`: Creates a local offline mock translation adapter operating with zero network requests.
- `translateHostContent(options): Promise<TranslationSession>`: Coordinates end-to-end translation, enforcing consent, provider language support, sensitive element exclusion, and DOM restoration.
- `TRANSLATION_DISCLAIMER`: Constant string disclaimer emphasizing prototype status and zero official WCAG compliance claims.
Expand Down
17 changes: 10 additions & 7 deletions docs/CSP.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ const cspHeader = `
style-src-attr 'unsafe-inline';
img-src 'self' data:;
font-src 'self' data:;
connect-src 'self' https://translate.googleapis.com;
object-src 'none';
base-uri 'self';
form-action 'self';
Expand Down Expand Up @@ -116,6 +117,7 @@ export function middleware(request: NextRequest) {
style-src-attr 'unsafe-inline';
img-src 'self' data:;
font-src 'self' data:;
connect-src 'self' https://translate.googleapis.com;
base-uri 'self';
form-action 'self';
`
Expand Down Expand Up @@ -169,6 +171,7 @@ For Vite applications, configure CSP headers either through your production web
style-src-attr 'unsafe-inline';
img-src 'self' data:;
font-src 'self' data:;
connect-src 'self' https://translate.googleapis.com;
"
/>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
Expand All @@ -185,10 +188,10 @@ For Vite applications, configure CSP headers either through your production web

## 4. Verification Checklist

| Requirement | Directive | Why It Is Needed |
| :---------------------------- | :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| **Widget UI Styles** | `style-src 'self'` (with static `style.css` import) | Renders the Clean light widget panel, trigger, and control cards |
| **Dynamic Host Effects** | `style-src-attr 'unsafe-inline'` | Applies runtime font-size, line-height, and filter adjustments to host elements |
| **Big High-Contrast Cursor** | `img-src 'self' data:` | Allows SVG data URI pointer rendering |
| **No External Font Requests** | `font-src 'self'` | The plugin does not load external web fonts; all font-legibility features use local and system fallbacks |
| **No Network Calls** | No special `connect-src` | All preferences, state persistence, and effects operate 100% locally on the client |
| Requirement | Directive | Why It Is Needed |
| :---------------------------- | :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Widget UI Styles** | `style-src 'self'` (with static `style.css` import) | Renders the Clean light widget panel, trigger, and control cards |
| **Dynamic Host Effects** | `style-src-attr 'unsafe-inline'` | Applies runtime font-size, line-height, and filter adjustments to host elements |
| **Big High-Contrast Cursor** | `img-src 'self' data:` | Allows SVG data URI pointer rendering |
| **No External Font Requests** | `font-src 'self'` | The plugin does not load external web fonts; all font-legibility features use local and system fallbacks |
| **No Network Calls** | No special `connect-src` (unless using `TranslationController`) | Core preferences, state persistence, and effects operate 100% locally; opt-in `TranslationController` (`createGoogleTranslateAdapter()`) connects to `https://translate.googleapis.com` only after explicit user consent (`connect-src 'self' https://translate.googleapis.com`), with automatic offline fallback if blocked |
32 changes: 20 additions & 12 deletions docs/TRANSLATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ The host-content translation adapter (**A11Y-409**) provides a decoupled, privac

### Strict Distinction from Widget Localization

| Dimension | Widget UI Localization (`docs/LOCALES.md`) | Host-Content Translation (`docs/TRANSLATION.md`) |
| :------------------- | :---------------------------------------------- | :----------------------------------------------------- |
| **Target Scope** | Widget buttons, labels, and dialog strings only | Arbitrary host document content (articles, headings) |
| **Network Requests** | **Zero** — 100% static bundled locale packs | **Zero by default** — opt-in custom adapter only |
| **Privacy Risk** | None (no host content read) | High (host text transmitted to provider if configured) |
| **User Consent** | Not required (local interface strings) | **Mandatory explicit consent** prior to transmission |
| Dimension | Widget UI Localization (`docs/LOCALES.md`) | Host-Content Translation (`docs/TRANSLATION.md`) |
| :------------------- | :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| **Target Scope** | Widget buttons, labels, and dialog strings only | Arbitrary host document content (articles, headings) |
| **Network Requests** | **Zero** — 100% static bundled locale packs | **Opt-in after consent** — `createGoogleTranslateAdapter()` (default on `<TranslationController />`) or custom/offline adapter |
| **Privacy Risk** | None (no host content read) | High (host text transmitted to provider if configured) |
| **User Consent** | Not required (local interface strings) | **Mandatory explicit consent** prior to transmission |

---

Expand Down Expand Up @@ -94,11 +94,11 @@ The engine automatically scans element tags, attributes, and ancestor trees (`is

### 3. Content Security Policy (CSP)

If a host application uses a remote translation API (e.g. Google Cloud, DeepL, LibreTranslate):
If a host application uses the default Google Translate adapter or a custom remote translation API (e.g. Google Cloud, DeepL, LibreTranslate):

- The host's `connect-src` CSP directive must explicitly permit the provider endpoint:
```http
Content-Security-Policy: default-src 'self'; connect-src 'self' https://api.deepl.com;
Content-Security-Policy: default-src 'self'; connect-src 'self' https://translate.googleapis.com;
```
- If an on-device local model (e.g., Transformers.js via WebAssembly or browser native Translation API `ai.translator`) is used, no external `connect-src` is required, though `wasm-unsafe-eval` may be needed for WebAssembly execution.

Expand Down Expand Up @@ -139,14 +139,22 @@ session.restore();

## Example Custom Providers

### 1. Local Offline Mock (Default)
### 1. Google Translate Adapter (Default on `<TranslationController />`) & Offline Fallback

Included for zero-network development and testing:
`<TranslationController />` defaults to `createGoogleTranslateAdapter()`, which performs client-side Google Translate requests only after explicit user consent and automatically falls back to local offline lexicons if offline or blocked:

```typescript
import { createOfflineMockTranslationAdapter } from "accessibility-plugin-react";
import {
createGoogleTranslateAdapter,
createOfflineMockTranslationAdapter,
} from "accessibility-plugin-react";

const googleAdapter = createGoogleTranslateAdapter({
fallbackToOffline: true,
});

const adapter = createOfflineMockTranslationAdapter({
// Zero-network alternative for air-gapped development and testing:
const offlineAdapter = createOfflineMockTranslationAdapter({
prefix: "[ES]",
supportedLanguages: ["es", "fr", "de", "si", "ta"],
});
Expand Down
1 change: 1 addition & 0 deletions examples/next-app/next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ const cspHeader = `
style-src-attr 'unsafe-inline';
img-src 'self' data:;
font-src 'self' data:;
connect-src 'self' https://translate.googleapis.com;
object-src 'none';
base-uri 'self';
form-action 'self';
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "accessibility-plugin-react",
"version": "2.30.0",
"version": "2.30.1",
"description": "A composable React display-preference widget with a clean light design, persistent settings and movable accessible controls.",
"main": "dist/index.js",
"module": "dist/index.mjs",
Expand Down
112 changes: 86 additions & 26 deletions src/core/effects.ts
Original file line number Diff line number Diff line change
Expand Up @@ -599,10 +599,10 @@ export function isFunctionalOrMeaningfulImage(el: Element): boolean {
return true;
}

// 3. Charts, graphs, diagrams, and figures
// 3. Charts, graphs, and diagrams
if (
el.closest(
"[role='graphics-document'], [role='graphics-symbol'], [role='figure'], figure, [class*='chart' i], [id*='chart' i], [class*='graph' i], [id*='graph' i], [class*='diagram' i], [id*='diagram' i]",
"[role='graphics-document'], [role='graphics-symbol'], [class*='chart' i], [id*='chart' i], [class*='graph' i], [id*='graph' i], [class*='diagram' i], [id*='diagram' i]",
) ||
el.matches(
"[role='graphics-document'], [role='graphics-symbol'], [aria-roledescription*='chart' i]",
Expand Down Expand Up @@ -640,6 +640,35 @@ export function isFunctionalOrMeaningfulImage(el: Element): boolean {
return true;
}

// Explicit decorative markers override alt/aria-label/title attributes
const hasExplicitDecorativeMarker = (node: Element) => {
if (
node.hasAttribute("data-decorative") &&
node.getAttribute("data-decorative") !== "false"
) {
return true;
}
if (
node.classList.contains("decorative") ||
node.classList.contains("deco")
) {
return true;
}
const nodeRole = node.getAttribute("role");
if (nodeRole === "presentation" || nodeRole === "none") {
return true;
}
return node.getAttribute("aria-hidden") === "true";
};

if (
hasExplicitDecorativeMarker(el) ||
(el.parentElement?.matches("picture") &&
hasExplicitDecorativeMarker(el.parentElement))
) {
return false;
}

// 7. Meaningful accessible names or semantic roles
if (el.hasAttribute("alt")) {
const alt = el.getAttribute("alt")?.trim();
Expand Down Expand Up @@ -711,7 +740,8 @@ export function isEligibleDecorativeImage(el: Element): boolean {

// 4. Explicit decorative marker
if (
el.hasAttribute("data-decorative") ||
(el.hasAttribute("data-decorative") &&
el.getAttribute("data-decorative") !== "false") ||
el.classList.contains("decorative") ||
el.classList.contains("deco")
) {
Expand Down Expand Up @@ -779,6 +809,35 @@ export function resolveEffectScope(
return document.body ?? null;
}

function resolveActiveContrastPalette(values: Record<string, unknown>): {
activePalette: ContrastPalette | null;
fallbackColors: [string, string] | null;
} {
if (isForcedColorsActive()) {
return { activePalette: null, fallbackColors: null };
}
const activeContrastKey =
values.contrastMode &&
values.contrastMode !== "off" &&
values.contrastMode !== "original"
? String(values.contrastMode)
: values.contrast !== undefined &&
values.contrast !== 0 &&
values.contrast !== "0" &&
values.contrast !== "off" &&
values.contrast !== "original"
? String(values.contrast)
: null;

const activePalette = activeContrastKey
? (CONTRAST_PALETTES[activeContrastKey] ?? null)
: null;
const fallbackColors = !activePalette
? (palette[String(values.contrast)] ?? null)
: null;
return { activePalette, fallbackColors };
}

function applyToElements(
elements: HTMLElement[],
values: Record<string, unknown>,
Expand Down Expand Up @@ -1035,23 +1094,8 @@ function applyToElements(
}

// Active contrast mode / palette
const activeContrastKey =
values.contrastMode &&
values.contrastMode !== "off" &&
values.contrastMode !== "original"
? String(values.contrastMode)
: values.contrast !== undefined &&
values.contrast !== 0 &&
values.contrast !== "0" &&
values.contrast !== "off" &&
values.contrast !== "original"
? String(values.contrast)
: null;

const activePalette =
activeContrastKey && !isForcedColorsActive()
? CONTRAST_PALETTES[activeContrastKey]
: null;
const { activePalette, fallbackColors } =
resolveActiveContrastPalette(values);

if (activePalette) {
for (const el of targetElements) {
Expand Down Expand Up @@ -1114,14 +1158,13 @@ function applyToElements(
if (
values.hideVideos &&
el.matches(
'video, iframe[src*="youtube.com/embed/"], iframe[src*="youtube-nocookie.com/embed/"], iframe[src*="youtu.be/"], iframe[src*="player.vimeo.com/video/"], iframe[src*="player.twitch.tv/"], iframe[src*="dailymotion.com/embed/"], iframe[src*="loom.com/embed/"], iframe[src*="wistia."], iframe[data-src*="youtube"], iframe[data-src*="vimeo"], iframe[data-src*="twitch.tv"], iframe[data-src*="dailymotion"], iframe[data-src*="loom.com"]',
'video, [data-video], .video-placeholder, iframe[src*="youtube.com/embed/"], iframe[src*="youtube-nocookie.com/embed/"], iframe[src*="youtu.be/"], iframe[src*="player.vimeo.com/video/"], iframe[src*="player.twitch.tv/"], iframe[src*="dailymotion.com/embed/"], iframe[src*="loom.com/embed/"], iframe[src*="wistia."], iframe[data-src*="youtube"], iframe[data-src*="vimeo"], iframe[data-src*="twitch.tv"], iframe[data-src*="dailymotion"], iframe[data-src*="loom.com"]',
)
)
set(el, "visibility", "hidden");
const colors = palette[String(values.contrast)];
if (colors && !activePalette && !isForcedColorsActive()) {
set(el, "color", colors[0]);
set(el, "background-color", colors[1]);
if (fallbackColors) {
set(el, "color", fallbackColors[0]);
set(el, "background-color", fallbackColors[1]);
}
if (
values.linkHighlight &&
Expand Down Expand Up @@ -1242,6 +1285,21 @@ export function applyPageSession(
}
}

const rootContrast = resolveActiveContrastPalette(values);
if (targetRoot && !targetRoot.matches(EXCLUDED)) {
if (rootContrast.activePalette) {
set(targetRoot, "color", rootContrast.activePalette.text);
set(
targetRoot,
"background-color",
rootContrast.activePalette.background,
);
} else if (rootContrast.fallbackColors) {
set(targetRoot, "color", rootContrast.fallbackColors[0]);
set(targetRoot, "background-color", rootContrast.fallbackColors[1]);
}
}

// Smart contrast research prototype: measured relative luminance assistance
const smartContrastVal = values.smartContrast;
if (
Expand Down Expand Up @@ -1773,7 +1831,9 @@ export function useBuiltinEffects(
!record.target.closest(
"[data-arap-ui], [data-arap-diagnostics], .arap-root",
) &&
record.target.matches("img, picture, video, iframe")
record.target.matches(
"img, picture, video, [data-video], .video-placeholder, iframe",
)
) {
added.push(record.target);
}
Expand Down
Loading