@aishware/react-a11y-rules-web 0.1.0

package/dist/rules/contrast.js

@@ -0,0 +1,60 @@
+import { colorContrastFinding, inlineStyleNumber, targetSizeTier, INTERACTIVE_TAGS, INTERACTIVE_ROLES, hasAttr, staticString, } from '@aishware/react-a11y-core';
+import { defineRule } from '../util.js';
+/**
+ * WCAG 1.4.3 contrast for inline styles where both colors are literal.
+ * Below 3:1 fails even for large text → serious. Between 3:1 and 4.5:1 is
+ * only flagged when the font size is also known to be small, so unknown-size
+ * text that might be large never false-positives.
+ */
+export const colorContrast = defineRule({
+    id: 'color-contrast',
+    description: 'Text color must meet WCAG contrast against its background (4.5:1, or 3:1 for large text).',
+    severity: 'serious',
+    wcag: ['1.4.3'],
+    partial: true,
+}, (el, ctx) => {
+    if (el.isComponent || !el.hasTextChild)
+        return;
+    const finding = colorContrastFinding(el);
+    if (finding)
+        ctx.report({ el, ...finding });
+});
+/**
+ * WCAG 2.5.8 (AA, new in 2.2): pointer targets need 24×24 CSS px minimum.
+ * Only statically-sized inline styles are checked.
+ */
+export const targetSize = defineRule({
+    id: 'target-size',
+    description: 'Interactive targets should be at least 24×24px (44×44 recommended).',
+    severity: 'serious',
+    wcag: ['2.5.8', '2.5.5'],
+    partial: true,
+}, (el, ctx) => {
+    if (el.isComponent)
+        return;
+    const interactive = ((el.name === 'a' || el.name === 'area') && hasAttr(el, 'href')) ||
+        el.name === 'button' ||
+        el.name === 'input' ||
+        INTERACTIVE_ROLES.has(staticString(el, 'role')?.trim() ?? '') ||
+        (INTERACTIVE_TAGS.has(el.name) && hasAttr(el, 'onClick'));
+    if (!interactive)
+        return;
+    const width = inlineStyleNumber(el, 'width');
+    const height = inlineStyleNumber(el, 'height');
+    if (width === undefined || height === undefined)
+        return;
+    const tier = targetSizeTier(width, height);
+    if (tier === 'below-min') {
+        ctx.report({
+            el,
+            message: `${width}×${height}px target is below the 24×24px WCAG 2.5.8 (AA) minimum — hard to hit for users with motor impairments.`,
+        });
+    }
+    else if (tier === 'below-recommended') {
+        ctx.report({
+            el,
+            message: `${width}×${height}px target is below the recommended 44×44px (WCAG 2.5.5 AAA).`,
+            severity: 'minor',
+        });
+    }
+});

package/dist/rules/document.d.ts

@@ -0,0 +1,7 @@
+/** Blocking pinch-zoom prevents low-vision users from reading the page. */
+export declare const metaViewportZoomable: import("@aishware/react-a11y-core").Rule;
+/** Meta refresh redirects/reloads on a timer users cannot control. */
+export declare const noMetaRefresh: import("@aishware/react-a11y-core").Rule;
+/** Empty <title> leaves the page unnamed in tabs, history and screen readers. */
+export declare const titleHasContent: import("@aishware/react-a11y-core").Rule;
+//# sourceMappingURL=document.d.ts.map

package/dist/rules/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/rules/document.ts"],"names":[],"mappings":"AAGA,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,0CAsBhC,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,aAAa,0CAczB,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,eAAe,0CAY3B,CAAC"}

package/dist/rules/document.js

@@ -0,0 +1,53 @@
+import { staticString } from '@aishware/react-a11y-core';
+import { defineRule, isDomTag } from '../util.js';
+/** Blocking pinch-zoom prevents low-vision users from reading the page. */
+export const metaViewportZoomable = defineRule({
+    id: 'meta-viewport-zoomable',
+    description: 'The viewport meta tag must not disable or limit zoom.',
+    severity: 'serious',
+    wcag: ['1.4.4'],
+}, (el, ctx) => {
+    if (!isDomTag(el, 'meta'))
+        return;
+    if (staticString(el, 'name')?.trim().toLowerCase() !== 'viewport')
+        return;
+    const content = staticString(el, 'content');
+    if (content === undefined)
+        return;
+    const normalized = content.toLowerCase().replace(/\s/g, '');
+    if (/user-scalable=(no|0)/.test(normalized)) {
+        ctx.report({ el, message: 'user-scalable=no prevents pinch-zoom — low-vision users cannot enlarge text.' });
+        return;
+    }
+    const maxScale = normalized.match(/maximum-scale=([\d.]+)/);
+    if (maxScale && Number(maxScale[1]) < 2) {
+        ctx.report({ el, message: `maximum-scale=${maxScale[1]} limits zoom below 200% (WCAG requires text resizable to 200%).` });
+    }
+});
+/** Meta refresh redirects/reloads on a timer users cannot control. */
+export const noMetaRefresh = defineRule({
+    id: 'no-meta-refresh',
+    description: 'Do not use <meta http-equiv="refresh">.',
+    severity: 'serious',
+    wcag: ['2.2.1'],
+}, (el, ctx) => {
+    if (!isDomTag(el, 'meta'))
+        return;
+    const httpEquiv = staticString(el, 'httpEquiv') ?? staticString(el, 'http-equiv');
+    if (httpEquiv?.trim().toLowerCase() === 'refresh') {
+        ctx.report({ el, message: '<meta http-equiv="refresh"> reloads or redirects on a timer users cannot adjust or disable.' });
+    }
+});
+/** Empty <title> leaves the page unnamed in tabs, history and screen readers. */
+export const titleHasContent = defineRule({
+    id: 'title-has-content',
+    description: '<title> must not be empty.',
+    severity: 'serious',
+    wcag: ['2.4.2'],
+}, (el, ctx) => {
+    if (!isDomTag(el, 'title'))
+        return;
+    if (el.hasTextChild || el.hasExpressionChild || el.hasSpread)
+        return;
+    ctx.report({ el, message: '<title> is empty — the page has no name in tabs, bookmarks or screen reader announcements.' });
+});

package/dist/rules/forms.d.ts

@@ -0,0 +1,19 @@
+/** input type="button"/"image" have no default label. */
+export declare const inputButtonHasName: import("@aishware/react-a11y-core").Rule;
+/**
+ * WCAG 3.3.8 (new in 2.2): authentication must not rely on transcription.
+ * Blocking password managers or paste forces users to retype credentials.
+ */
+export declare const accessibleAuthentication: import("@aishware/react-a11y-core").Rule;
+/**
+ * WCAG 3.3.1: a control marked invalid must point at a text description of
+ * the error, or screen reader users only hear "invalid" with no explanation.
+ */
+export declare const errorIdentification: import("@aishware/react-a11y-core").Rule;
+/**
+ * WCAG 3.3.7 (new in 2.2): users must not re-enter information the site
+ * already has. autoComplete="off" on identity fields blocks the browser
+ * from re-filling data the user already provided.
+ */
+export declare const noAutocompleteOff: import("@aishware/react-a11y-core").Rule;
+//# sourceMappingURL=forms.d.ts.map

package/dist/rules/forms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.d.ts","sourceRoot":"","sources":["../../src/rules/forms.ts"],"names":[],"mappings":"AAGA,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,0CAkB9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,0CAwBpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,0CAkB/B,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,0CAqB7B,CAAC"}

package/dist/rules/forms.js

@@ -0,0 +1,102 @@
+import { attrProvidesValue, hasAttr, staticString } from '@aishware/react-a11y-core';
+import { defineRule, isDomTag } from '../util.js';
+/** input type="button"/"image" have no default label. */
+export const inputButtonHasName = defineRule({
+    id: 'input-button-has-name',
+    description: '<input type="button"> needs a value; <input type="image"> needs alt.',
+    severity: 'serious',
+    wcag: ['4.1.2', '1.1.1'],
+}, (el, ctx) => {
+    if (!isDomTag(el, 'input') || el.hasSpread)
+        return;
+    const type = staticString(el, 'type')?.trim().toLowerCase();
+    if (type === 'button') {
+        if (attrProvidesValue(el, 'value') || attrProvidesValue(el, 'aria-label') || attrProvidesValue(el, 'aria-labelledby'))
+            return;
+        ctx.report({ el, message: '<input type="button"> has no value or aria-label — it is announced as an unnamed button.' });
+    }
+    else if (type === 'image') {
+        if (attrProvidesValue(el, 'alt') || attrProvidesValue(el, 'aria-label') || attrProvidesValue(el, 'aria-labelledby'))
+            return;
+        ctx.report({ el, message: '<input type="image"> has no alt text — the button\'s purpose is invisible to screen readers.' });
+    }
+});
+/**
+ * WCAG 3.3.8 (new in 2.2): authentication must not rely on transcription.
+ * Blocking password managers or paste forces users to retype credentials.
+ */
+export const accessibleAuthentication = defineRule({
+    id: 'accessible-authentication',
+    description: 'Password fields must not block password managers or paste.',
+    severity: 'serious',
+    wcag: ['3.3.8'],
+}, (el, ctx) => {
+    if (!isDomTag(el, 'input'))
+        return;
+    if (staticString(el, 'type')?.trim().toLowerCase() !== 'password')
+        return;
+    if (staticString(el, 'autoComplete')?.trim().toLowerCase() === 'off') {
+        ctx.report({
+            el,
+            message: 'autoComplete="off" on a password field blocks password managers, forcing users with cognitive or motor disabilities to transcribe. Use "current-password" or "new-password".',
+        });
+    }
+    if (hasAttr(el, 'onPaste')) {
+        ctx.report({
+            el,
+            message: 'onPaste on a password field — if it prevents pasting, users cannot use password managers (WCAG 3.3.8). Verify paste is not blocked.',
+            severity: 'moderate',
+        });
+    }
+});
+/**
+ * WCAG 3.3.1: a control marked invalid must point at a text description of
+ * the error, or screen reader users only hear "invalid" with no explanation.
+ */
+export const errorIdentification = defineRule({
+    id: 'error-identification',
+    description: 'Controls with aria-invalid must reference an error description.',
+    severity: 'moderate',
+    wcag: ['3.3.1'],
+    partial: true,
+}, (el, ctx) => {
+    if (!isDomTag(el, 'input', 'select', 'textarea') || el.hasSpread)
+        return;
+    const invalid = el.attrs.get('aria-invalid');
+    if (!invalid || (invalid.kind === 'static' && (invalid.value === false || invalid.value === 'false')))
+        return;
+    if (hasAttr(el, 'aria-describedby') || hasAttr(el, 'aria-errormessage'))
+        return;
+    ctx.report({
+        el,
+        message: `<${el.name}> is marked aria-invalid but has no aria-describedby/aria-errormessage — screen reader users hear "invalid" with no explanation of what is wrong.`,
+    });
+});
+const IDENTITY_FIELD = /(name|email|phone|tel|address|city|country|zip|postal|company|organi[sz]ation)/i;
+/**
+ * WCAG 3.3.7 (new in 2.2): users must not re-enter information the site
+ * already has. autoComplete="off" on identity fields blocks the browser
+ * from re-filling data the user already provided.
+ */
+export const noAutocompleteOff = defineRule({
+    id: 'no-autocomplete-off',
+    description: 'Do not disable autofill on fields asking for user information.',
+    severity: 'moderate',
+    wcag: ['3.3.7', '1.3.5'],
+    partial: true,
+}, (el, ctx) => {
+    if (!isDomTag(el, 'input'))
+        return;
+    if (staticString(el, 'autoComplete')?.trim().toLowerCase() !== 'off')
+        return;
+    const type = staticString(el, 'type')?.trim().toLowerCase();
+    if (type === 'password')
+        return; // covered by accessible-authentication
+    const fieldHint = `${staticString(el, 'name') ?? ''} ${staticString(el, 'id') ?? ''} ${type ?? ''}`;
+    if (type === 'email' || type === 'tel' || IDENTITY_FIELD.test(fieldHint)) {
+        ctx.report({
+            el,
+            message: 'autoComplete="off" on a personal-data field forces users to retype information they already entered (WCAG 3.3.7) and defeats 1.3.5. Use a proper autofill token instead.',
+        });
+    }
+});

package/dist/rules/interactions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * WCAG 2.5.2: activating on down-events (mousedown/touchstart) means users
+ * cannot abort by sliding off the control before releasing.
+ */
+export declare const pointerCancellation: import("@aishware/react-a11y-core").Rule;
+/** Removing the focus outline without a replacement hides keyboard position. */
+export declare const noOutlineNone: import("@aishware/react-a11y-core").Rule;
+//# sourceMappingURL=interactions.d.ts.map

package/dist/rules/interactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactions.d.ts","sourceRoot":"","sources":["../../src/rules/interactions.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,eAAO,MAAM,mBAAmB,0CAoB/B,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,aAAa,0CA0BzB,CAAC"}

package/dist/rules/interactions.js

@@ -0,0 +1,52 @@
+import { INTERACTIVE_ROLES, INTERACTIVE_TAGS, hasAttr, inlineStyleValue, staticString, } from '@aishware/react-a11y-core';
+import { defineRule } from '../util.js';
+/**
+ * WCAG 2.5.2: activating on down-events (mousedown/touchstart) means users
+ * cannot abort by sliding off the control before releasing.
+ */
+export const pointerCancellation = defineRule({
+    id: 'pointer-cancellation',
+    description: 'Do not trigger actions on mousedown/touchstart — use click/up events.',
+    severity: 'moderate',
+    wcag: ['2.5.2'],
+    partial: true,
+}, (el, ctx) => {
+    if (el.isComponent || el.hasSpread)
+        return;
+    if (el.name !== 'button' && el.name !== 'a')
+        return;
+    const hasDown = hasAttr(el, 'onMouseDown') || hasAttr(el, 'onTouchStart');
+    const hasUp = hasAttr(el, 'onClick') || hasAttr(el, 'onMouseUp') || hasAttr(el, 'onTouchEnd') || hasAttr(el, 'onPointerUp');
+    if (hasDown && !hasUp) {
+        ctx.report({
+            el,
+            message: `<${el.name}> acts on a down-event only — users cannot cancel by sliding off before release. Move the action to onClick.`,
+        });
+    }
+});
+/** Removing the focus outline without a replacement hides keyboard position. */
+export const noOutlineNone = defineRule({
+    id: 'no-outline-none',
+    description: 'Do not remove the focus outline via inline styles without a visible replacement.',
+    severity: 'moderate',
+    wcag: ['2.4.7'],
+}, (el, ctx) => {
+    if (el.isComponent)
+        return;
+    const interactive = INTERACTIVE_TAGS.has(el.name) ||
+        hasAttr(el, 'tabIndex') ||
+        hasAttr(el, 'onClick') ||
+        INTERACTIVE_ROLES.has(staticString(el, 'role')?.trim() ?? '');
+    if (!interactive)
+        return;
+    for (const prop of ['outline', 'outlineStyle', 'outlineWidth']) {
+        const v = inlineStyleValue(el, prop);
+        if (v === 'none' || v === 'hidden' || v === 0 || v === '0') {
+            ctx.report({
+                el,
+                message: `Inline style removes the focus outline (${prop}: ${JSON.stringify(v)}) — keyboard users lose track of where they are unless a visible :focus style replaces it.`,
+            });
+            return;
+        }
+    }
+});

package/dist/rules/names.d.ts

@@ -0,0 +1,14 @@
+/** Buttons (and role="button" elements) must have an accessible name. */
+export declare const buttonHasName: import("@aishware/react-a11y-core").Rule;
+/**
+ * WCAG 2.5.3: the visible label must be contained in the accessible name,
+ * or voice-control users saying the visible text cannot activate the control.
+ * Only fires when both the aria-label and the entire visible text are static.
+ */
+export declare const labelInName: import("@aishware/react-a11y-core").Rule;
+/**
+ * Auto-playing audio talks over screen readers. Muted media is fine;
+ * media with controls is downgraded since users can stop it.
+ */
+export declare const mediaNoAutoplay: import("@aishware/react-a11y-core").Rule;
+//# sourceMappingURL=names.d.ts.map

package/dist/rules/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/rules/names.ts"],"names":[],"mappings":"AAWA,yEAAyE;AACzE,eAAO,MAAM,aAAa,0CAkBzB,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,WAAW,0CAyBvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,0CAwB3B,CAAC"}

package/dist/rules/names.js

@@ -0,0 +1,82 @@
+import { INTERACTIVE_ROLES, deepStaticText, hasAccessibleName, hasAttr, isAriaHidden, staticString, staticValue, } from '@aishware/react-a11y-core';
+import { defineRule, isDomTag } from '../util.js';
+/** Buttons (and role="button" elements) must have an accessible name. */
+export const buttonHasName = defineRule({
+    id: 'button-has-accessible-name',
+    description: 'Buttons must have an accessible name.',
+    severity: 'critical',
+    wcag: ['4.1.2'],
+}, (el, ctx) => {
+    const isButtonTag = isDomTag(el, 'button');
+    const hasButtonRole = !el.isComponent && staticString(el, 'role')?.trim() === 'button';
+    if (!isButtonTag && !hasButtonRole)
+        return;
+    if (isAriaHidden(el))
+        return;
+    if (hasAccessibleName(el))
+        return;
+    ctx.report({
+        el,
+        message: `<${el.name}${hasButtonRole && !isButtonTag ? ' role="button"' : ''}> has no accessible name. Icon-only buttons need aria-label.`,
+    });
+});
+const normalize = (s) => s.toLowerCase().replace(/[^\p{L}\p{N} ]/gu, '').replace(/\s+/g, ' ').trim();
+/**
+ * WCAG 2.5.3: the visible label must be contained in the accessible name,
+ * or voice-control users saying the visible text cannot activate the control.
+ * Only fires when both the aria-label and the entire visible text are static.
+ */
+export const labelInName = defineRule({
+    id: 'label-in-name',
+    description: 'aria-label must contain the visible text of the control.',
+    severity: 'moderate',
+    wcag: ['2.5.3'],
+}, (el, ctx) => {
+    const ariaLabel = staticString(el, 'aria-label');
+    if (!ariaLabel?.trim())
+        return;
+    const interactive = isDomTag(el, 'button', 'a', 'summary') ||
+        INTERACTIVE_ROLES.has(staticString(el, 'role')?.trim() ?? '');
+    if (!interactive)
+        return;
+    const visible = deepStaticText(el);
+    if (!visible)
+        return; // dynamic or empty — can't compare
+    const label = normalize(ariaLabel);
+    const text = normalize(visible);
+    if (text && !label.includes(text)) {
+        ctx.report({
+            el,
+            message: `aria-label="${ariaLabel}" does not contain the visible text "${visible}" — voice-control users saying what they see cannot activate it.`,
+        });
+    }
+});
+/**
+ * Auto-playing audio talks over screen readers. Muted media is fine;
+ * media with controls is downgraded since users can stop it.
+ */
+export const mediaNoAutoplay = defineRule({
+    id: 'media-no-autoplay',
+    description: 'Media must not autoplay with sound.',
+    severity: 'serious',
+    wcag: ['1.4.2'],
+}, (el, ctx) => {
+    if (!isDomTag(el, 'video', 'audio'))
+        return;
+    if (!hasAttr(el, 'autoPlay') || staticValue(el, 'autoPlay') === false)
+        return;
+    if (staticValue(el, 'muted') === true)
+        return;
+    if (hasAttr(el, 'controls')) {
+        ctx.report({
+            el,
+            message: `<${el.name}> autoplays with sound. Users can stop it via controls, but prefer starting paused.`,
+            severity: 'moderate',
+        });
+        return;
+    }
+    ctx.report({
+        el,
+        message: `<${el.name}> autoplays with sound and has no controls — it talks over screen readers with no way to stop it. Add muted, or remove autoPlay.`,
+    });
+});

package/dist/rules/roles.d.ts

@@ -0,0 +1,33 @@
+/**
+ * An element given an interactive role but unreachable by keyboard: it needs
+ * tabIndex to be focusable, or assistive-technology users cannot operate it.
+ */
+export declare const interactiveSupportsFocus: import("@react-a11y/core").Rule;
+/**
+ * Event handlers on semantic non-interactive elements (li, main, h2, …) are
+ * unreachable by keyboard and screen reader users. Move the handler to a
+ * <button>/<a>, or give the element an interactive role and focus support.
+ */
+export declare const noNoninteractiveElementInteractions: import("@react-a11y/core").Rule;
+/**
+ * An interactive element whose role removes its interactive semantics
+ * (e.g. <button role="article">) becomes invisible to assistive technology
+ * as a control.
+ */
+export declare const noInteractiveElementToNoninteractiveRole: import("@react-a11y/core").Rule;
+/**
+ * A semantic non-interactive element given an interactive role (e.g.
+ * <li role="button">) should be a generic container or a native control —
+ * native elements carry behavior the role alone does not.
+ */
+export declare const noNoninteractiveElementToInteractiveRole: import("@react-a11y/core").Rule;
+/** tabIndex on a non-interactive element adds a tab stop that does nothing. */
+export declare const noNoninteractiveTabindex: import("@react-a11y/core").Rule;
+/**
+ * A role on a generic <div>/<span> that has a native element equivalent —
+ * prefer the native tag for built-in keyboard handling and semantics.
+ * (Redundant roles on the matching element itself are handled by
+ * no-redundant-roles.)
+ */
+export declare const preferTagOverRole: import("@react-a11y/core").Rule;
+//# sourceMappingURL=roles.d.ts.map

package/dist/rules/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/rules/roles.ts"],"names":[],"mappings":"AAoEA;;;GAGG;AACH,eAAO,MAAM,wBAAwB,iCAmBpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,iCAsB/C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wCAAwC,iCAkBpD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wCAAwC,iCAiBpD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,iCAsBpC,CAAC;AAgCF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,iCAkB7B,CAAC"}