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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

## 2.31.0 — 2026-11-20

- Overhaul HTML and CSS-based image hiding (`HideImagesController` default `mode="all"` and dedicated `HideDecorativeImagesController` `mode="decorative"`):
- Hide all non-protected host `<img>` (including non-empty `alt` and missing `alt`), `<picture>`, `<object type="image/*">`, `<embed type="image/*">`, and explicitly decorative `<svg>` elements in `HideImagesController` (`mode="all"`), while preserving strict decorative-only filtering on `HideDecorativeImagesController` and `<HideImagesController mode="decorative" />`.
- Export `HIDE_IMAGES_MODES`, `HideImagesMode`, and `HideImagesValue` from `accessibility-plugin-react` and update `builtins.hideImages` schema validation to accept `boolean | "all" | "decorative"`.
- Fix CSS image hiding across `background-image`, `background` shorthand, CSS variables (`var(...)`), `image-set()` / `-webkit-image-set()` / `cross-fade()`, `list-style-image`, element `content: url(...)`, `document.documentElement`/`document.body` host roots, and `::before`/`::after` pseudo-elements (via CSP-nonce-aware `#arap-hide-images-style`, `ShadowRoot` styles, and stylesheet rule scanning) while preserving pure CSS gradients.
- Eliminate false-positive CSS container exclusions on landmarks (`<section aria-label>`, `role="banner"`) and word substrings (`.paragraph`, `.typography`, `.photography`, `.roadmap`, `.sitemap`, `.charter`, `.aftermath`, `.faqRow`) via word-boundary token matching, while keeping widget UI, `[data-arap-ignore]`/`[data-arap-exempt]`, buttons/controls, icon-only links, CAPTCHAs, charts, maps, QR/barcodes, and math protected.
- Handle dynamic `style`, `class`, and media-attribute mutations incrementally via `applyMediaIncremental()` with `observer.takeRecords()` feedback-loop protection and memoized effect options in `AccessibilityPlugin`.

## 2.30.1 — 2026-11-18

- Fix decorative image classification inside `<figure>` and add client-side Google Translate adapter (#201):
Expand Down
65 changes: 33 additions & 32 deletions docs/API.md

Large diffs are not rendered by default.

146 changes: 55 additions & 91 deletions docs/DECORATIVE_IMAGES.md
Original file line number Diff line number Diff line change
@@ -1,109 +1,68 @@
# Decorative Image Handling
# Image Hiding & Decorative Image Handling

This document specifies how `accessibility-plugin-react` identifies, scopes, and manages decorative images and CSS background images in accordance with WCAG 2.1 / 2.2 Success Criterion 1.1.1 (Non-text Content) and issue [A11Y-207](https://github.com/prabothcharith/accessibility-react/issues/47).
This document specifies how `accessibility-plugin-react` hides HTML and CSS-based images while preserving interactive controls, essential visualizations, and opt-out boundaries in accordance with WCAG 2.1 / 2.2 Success Criterion 1.1.1 (Non-text Content) and issue [A11Y-207](https://github.com/prabothcharith/accessibility-react/issues/47).

---

## 1. Core Principles

1. **Hide only eligible decorative imagery**:
Only images that are unambiguously decorative are hidden when image hiding is activated.
2. **Never hide functional or interactive controls**:
Images inside `<a>`, `<button>`, `<input>`, or elements with interactive ARIA roles (`button`, `link`, `menuitem`, `tab`) must remain visible so users do not lose critical interface affordances or touch targets.
3. **Never hide essential, informative, or security content**:
- **CAPTCHA**: Verification puzzles and audio/visual challenge widgets are strictly protected.
- **Charts & Graphs**: Analytical visual representations, figures, and diagrams (`role="graphics-document"`, `role="figure"`, `.chart`, `.graph`, `.diagram`) remain fully available.
- **Maps**: Geolocation tiles, satellite maps, and interactive maps (`[role="region"][aria-label*="map"]`, `.map`, tile servers) remain visible.
- **QR & Barcodes**: Payment, login, and verification codes (`.qr`, `.barcode`) remain visible.
- **Math & Formulas**: Formulas (`role="math"`, `math`, `.math`) remain intact.
- **Meaningful Alt & Labels**: Any image with non-empty `alt`, `aria-label`, `aria-labelledby`, or `title` is considered informative and preserved.
4. **Never fabricate alt text**:
## 1. Modes & Core Principles

The image-hiding system supports two explicit controller modes sharing the `hideImages` preference:

1. **General Image Hiding (`HideImagesController`, default `mode="all"`)**:
- Hides all eligible host `<img>` (including non-empty `alt` and missing `alt`), `<picture>`, `<object type="image/*">`, `<embed type="image/*">`, and explicitly decorative `<svg>` elements.
- Hides all CSS-based images across host elements (including `html`/`body` in host-wide scope), covering `background-image`, `background` shorthand, CSS custom properties (`var(...)`), `image-set()`, `list-style-image`, element `content: url(...)`, and `::before` / `::after` pseudo-element images (`background-image` and `content: url(...)`).
- Preserves pure CSS gradients (`linear-gradient`, `radial-gradient`, etc.), widget UI, `[data-arap-ignore]` / `[data-arap-exempt]` regions, `<button>` / interactive controls, icon-only/image-only links (`<a>` / `[role="link"]` with no text content), CAPTCHAs, charts/graphs/diagrams, maps, QR/barcodes, and math formulas.
2. **Strict Decorative-Only Mode (`HideDecorativeImagesController` or `<HideImagesController mode="decorative" />`)**:
- Hides only explicitly decorative HTML images (`alt=""`, `role="presentation"`, `role="none"`, `aria-hidden="true"`, `data-decorative`, `.decorative`, `.deco`) and decorative CSS-based images.
- Strictly preserves informative images with non-empty `alt`, `aria-label`, `aria-labelledby`, or `title`, missing-`alt` `<img>` elements, meaningful `<picture>` elements, linked images, and informative CSS `role="img"` containers.
3. **Never fabricate alt text**:
The plugin never mutates, synthesizes, or generates AI/heuristic `alt` text or accessible names. It strictly acts as a client-side display-preference modifier.
5. **Scoped CSS Background Images**:
CSS background images are only stripped from non-functional, non-meaningful layout containers. Buttons, links, CAPTCHA, charts, and maps retain their background graphics.
6. **Idempotent and Reversible Lifecycle**:
Every visual override is tracked inline with priority preservation and completely restored upon toggle-off, reset, or plugin unmount.
4. **Word-boundary token matching (zero false positives)**:
Protection selectors split camelCase and match protected tokens (`captcha`, `chart`/`graph`/`diagram`, `map`, `qr`/`barcode`, `math`) on token boundaries so ordinary class names such as `.paragraph`, `.typography`, `.photography`, `.roadmap`, `.sitemap`, `.charter`, or `.aftermath` are never mistakenly excluded.
5. **Idempotent, dynamic, and reversible lifecycle**:
Inline style overrides, dynamic `<style id="arap-hide-images-style">` pseudo-element rules (with optional CSP `nonce`), and `data-arap-hide-*` attributes are tracked and cleanly restored upon toggle-off, reset, or plugin unmount. Dynamic DOM additions as well as class, style, and media-attribute mutations are applied incrementally.

---

## 2. Classification Logic

### A. Functional or Meaningful Images (`isFunctionalOrMeaningfulImage`)

An image or element is deemed functional/meaningful and **MUST NEVER BE HIDDEN** if it satisfies any of the following:
An image or element is deemed functional/meaningful for strict decorative filtering (`mode="decorative"`) if it satisfies any of the following:

- **Inside an interactive control**:
```ts
el.closest(
"a, button, [role='button'], [role='link'], [role='menuitem'], [role='tab'], input, select, textarea, summary",
);
```
- **CAPTCHA verification**:
```ts
el.closest(
"[id*='captcha' i], [class*='captcha' i], [aria-label*='captcha' i], [data-captcha]",
) ||
el.matches(
"[src*='captcha' i], [alt*='captcha' i], [title*='captcha' i], [id*='captcha' i], [class*='captcha' i]",
);
```
- **Charts, Graphs, Figures, and Diagrams**:
```ts
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]",
) ||
el.matches(
"[role='graphics-document'], [role='graphics-symbol'], [aria-roledescription*='chart' i]",
);
```
- **Maps**:
```ts
el.closest(
"[role='region'][aria-label*='map' i], [class*='map' i], [id*='map' i], [data-map]",
) ||
el.matches(
"[src*='maps' i], [src*='tiles' i], [src*='openstreetmap' i], [src*='mapbox' i]",
);
```
- **QR Codes and Barcodes**:
```ts
el.closest(
"[class*='qr' i], [id*='qr' i], [class*='barcode' i], [id*='barcode' i]",
) ||
el.matches(
"[src*='qr' i], [alt*='qr' i], [src*='barcode' i], [alt*='barcode' i]",
);
```
- **Math Content**:
```ts
el.closest("[role='math'], math, [class*='math' i]");
```
- **Meaningful Authorship Attributes**:
- **Widget or explicit opt-out**: inside `[data-arap-ui]`, `[data-arap-diagnostics]`, `.arap-root`, `[data-arap-ignore]`, or `[data-arap-exempt]`.
- **Inside an interactive control or link**: `a`, `button`, `[role='button']`, `[role='link']`, `[role='menuitem']`, `[role='tab']`, `input`, `select`, `textarea`, `summary`.
- **CAPTCHA verification**: `data-captcha`, CAPTCHA tokens in `id`/`class`/`aria-label`, or `captcha` in `src`/`alt`/`title`.
- **Charts, Graphs, and Diagrams**: `role="graphics-document"`, `role="graphics-symbol"`, `aria-roledescription`, or token-bounded `chart`/`graph`/`diagram` classes or IDs.
- **Maps**: `data-map`, `[role="region"]` with map `aria-label`, token-bounded `map` classes/IDs, or recognized map/tile URLs.
- **QR Codes and Barcodes**: token-bounded `qr`/`qrcode`/`barcode` classes/IDs/alt/src.
- **Math Content**: `role="math"`, `<math>`, or token-bounded `math`/`mathjax`/`katex`/`formula`/`equation` classes or IDs.
- **Meaningful Authorship Attributes** (overridden when an explicit decorative marker is present on the element or parent `<picture>`):
- `alt` is non-empty (`alt.trim().length > 0`)
- `aria-label` is non-empty
- `aria-labelledby` is non-empty
- `title` is non-empty
- `role` is an informative role (not `presentation`, `none`, or bare unlabeled `img`)

_(In `mode="all"`, critical protections still keep widget UI, `[data-arap-ignore]`/`[data-arap-exempt]`, buttons/controls, icon-only/image-only links, CAPTCHAs, charts/graphs/diagrams, maps, QR/barcodes, and math visible while hiding standard editorial `<img>` tags, missing-`alt` `<img>` tags, `<picture>`, `<object type="image/*">`, `<embed type="image/*">`, and CSS images.)_

---

### B. Eligible Decorative Images (`isEligibleDecorativeImage`)

An image or `<picture>` element is eligible to be hidden only if `isFunctionalOrMeaningfulImage(el)` is `false` AND it exhibits explicit decorative markup:
An image element is eligible in strict decorative mode only if `isFunctionalOrMeaningfulImage(el)` is `false` AND it exhibits explicit decorative markup:

1. **Empty alt attribute**: `el.hasAttribute("alt") && el.getAttribute("alt")?.trim() === ""`
2. **Presentational ARIA role**: `el.getAttribute("role") === "presentation"` or `"none"`
3. **Hidden from AT**: `el.getAttribute("aria-hidden") === "true"`
4. **Explicit decorative cue**: `data-decorative="true"`, `.decorative`, or `.deco`
5. **`<picture>` containers**: Any `<picture>` containing an eligible decorative child `<img>` is hidden as a unit.

Images that lack an `alt` attribute entirely without any decorative marker are **NOT** assumed decorative; omitting `alt` is an authoring defect, not proof of decorative intent. Hiding such images could remove informative visuals.
5. **`<picture>`, `<object type="image/*">`, `<embed type="image/*">`, and explicitly decorative `<svg>`**: `<picture>` elements inherit decorative status from their child `<img>` or own markers.

---

## 3. Component Usage

### Standard Export: `HideImagesController`
### General Image Hiding: `HideImagesController`

```tsx
import {
Expand All @@ -125,13 +84,19 @@ export function Settings() {
}
```

### Semantic Alias: `HideDecorativeImagesController`
### Decorative-Only Image Hiding: `HideDecorativeImagesController`

```tsx
import { HideDecorativeImagesController } from "accessibility-plugin-react";
import {
HideDecorativeImagesController,
HideImagesController,
} from "accessibility-plugin-react";

// Drop-in alias with semantic naming
// Dedicated decorative-only component (defaults to mode="decorative")
<HideDecorativeImagesController label="Hide Decorative Images" />;

// Equivalent explicit mode prop on HideImagesController
<HideImagesController label="Hide Decorative Images" mode="decorative" />;
```

---
Expand Down Expand Up @@ -159,18 +124,17 @@ if (isFunctionalOrMeaningfulImage(img)) {

## 5. Verification Matrix

| Target | Condition | Expected Behavior |
| :----------------------------------------- | :---------------------------- | :---------------------------------- |
| `img[alt=""]` | Independent decorative image | `visibility: hidden` |
| `img[role="presentation"]` | Presentational image | `visibility: hidden` |
| `img[aria-hidden="true"]` | Screen-reader hidden image | `visibility: hidden` |
| `img[data-decorative]` | Marked decorative | `visibility: hidden` |
| `a > img[alt=""]` | Linked control image | **Visible** (retained) |
| `button > img` | Button control image | **Visible** (retained) |
| `img.captcha` | Security verification | **Visible** (retained) |
| `img.chart` / `[role="graphics-document"]` | Analytical visualization | **Visible** (retained) |
| `img[src*="tile.openstreetmap.org"]` | Map tile | **Visible** (retained) |
| `img.qr` | QR code | **Visible** (retained) |
| `div[style*="background-image"]` | Decorative container | `background-image: none !important` |
| `button[style*="background-image"]` | Functional control background | **Visible** (retained) |
| Reset / Unmount | Preferences cleared | All original styles restored |
| Target | Mode | Expected Behavior |
| :---------------------------------------- | :------------------- | :------------------------------------------------ |
| `img[alt=""]` / `[data-decorative]` | `all` / `decorative` | `visibility: hidden` |
| `img[alt="Editorial photo"]` | `all` | `visibility: hidden` |
| `img[alt="Editorial photo"]` | `decorative` | **Visible** (preserved) |
| `img` (missing `alt`) | `all` | `visibility: hidden` |
| `img` (missing `alt`) | `decorative` | **Visible** (preserved) |
| `a:not(:has-text) > img` (icon-only link) | `all` / `decorative` | **Visible** (retained) |
| `button > img` / `button[style*="url("]` | `all` / `decorative` | **Visible** (retained) |
| `img.captcha` / `img.chart` / `img.qr` | `all` / `decorative` | **Visible** (retained) |
| `div` / `body` / `.paragraph` `url(...)` | `all` / `decorative` | `background-image: none !important` |
| `::before` / `::after` CSS `url(...)` | `all` / `decorative` | Pseudo image hidden via `#arap-hide-images-style` |
| `div[style*="linear-gradient(...)"]` | `all` / `decorative` | **Visible** (gradient retained) |
| Reset / Toggle OFF / Unmount | `all` / `decorative` | All original styles & attrs restored |
Loading