@surea11y/core 1.0.0 → 1.0.1

package/docs/I18N.md

@@ -6,10 +6,10 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 | Locale | File | Keys | Coverage vs. English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.js` | 590 | 100% (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.js` | 287 | ~49% — **partial**, not every string is translated yet |
+| `en` (English) | `src/i18n/en.js` | 600 | 100% (the canonical/fallback set) |
+| `fr` (French) | `src/i18n/fr.js` | 600 | 100% |
 
-That `fr` number is real and worth being honest about: about half of the engine's translatable strings don't have a French entry yet. That's not a bug — see the fallback behavior below, which means a missing `fr` key never produces broken or missing text, just an English string in the middle of otherwise-French output.
+Both locales are fully translated as of this writing. That won't stay automatically true — every time a new rule (or a new i18n key) is added to `en.js`, `fr.js` needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). There's no automated check for this yet; diff `Object.keys(require('./src/i18n/en.js'))` against `fr.js` after adding a rule to catch drift before it ships.
 
 ## Selecting a locale
 

package/docs/OUTPUT_SCHEMA.md

@@ -103,7 +103,7 @@ Notes:
 
 ## An occurrence (`occurrences[i]`)
 
-Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` result has `occurrences: []` — this engine does not enumerate the elements it passed, only the ones it flagged; see the note in `docs/RULE_AUTHORING.md` on why "silence" from a `pass` rule is not the same as an enumerated list of passing elements).
+Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` result has `occurrences: []` — this engine does not enumerate the elements it passed, only the ones it flagged).
 
 ```ts
 {
@@ -114,7 +114,7 @@ Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` re
   hint: string,
   i18n: { summaryKey: string, hintKey: string, params: object } | null,
   data: {
-    visibilityFilter?: { targetSet: string, accEligible: boolean | null, reasons: string[] },
+    visibilityFilter?: { eligible: boolean, targetSet: string, accEligible: boolean | null, reasons: string[] },
     details?: object   // rule-specific, non-normative — see below
   }
 }
@@ -128,7 +128,7 @@ Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` re
 | `summary` | Human-readable, already localized ("This button has no accessible name."). |
 | `hint` | Human-readable remediation guidance, already localized. |
 | `i18n` | The raw translation keys behind `summary`/`hint`, if you want to re-render them in a different locale yourself without re-running the scan. `null` if the occurrence didn't use key-based i18n. |
-| `data.visibilityFilter` | Present on most occurrences: why the engine considered this element eligible for accessibility-tree evaluation (or not). `reasons` is a list of machine-readable exclusion codes when `accEligible: false`. |
+| `data.visibilityFilter` | Present on most occurrences: why the engine considered this element eligible (or not) under whichever eligibility model the rule used. `eligible` is that result; `targetSet` says which model produced it (`'dom'`: raw DOM/CSS visibility — most rules; `'acc'`: accessibility-tree eligibility). `accEligible` mirrors `eligible` only when `targetSet` is `'acc'`, otherwise `null` — don't read it as a second, independent signal. `reasons` is a list of machine-readable exclusion codes when `eligible: false`. |
 | `data.details` | Rule-specific structured data (e.g. `reasonCode`, computed metrics, resolved references) — **non-normative**: useful for building richer UI or debugging, but never changes what `outcome`/`severity` mean. Shape varies per rule; treat as best-effort extra context, not a stable contract. |
 
 ## A composite result (`rulesResults[i]`)
@@ -202,7 +202,7 @@ const result = runDomRulesInPage(
         {
           "selector": "html > body > button",
           "html": "<button></button>",
-          "structuralPath": [1, 0],
+          "structuralPath": [1, 1],
           "summary": "This button has no accessible name.",
           "hint": "Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.",
           "data": {
@@ -222,7 +222,7 @@ const result = runDomRulesInPage(
         {
           "selector": "html > body > img",
           "html": "<img src=\"logo.png\">",
-          "structuralPath": [1, 1],
+          "structuralPath": [1, 0],
           "summary": "Missing alt attribute on <img>.",
           "hint": "Add an alt attribute (use alt=\"\" only for decorative images)."
         }

package/docs/RULE_TAXONOMY.md

@@ -12,7 +12,7 @@ Encoded by: `meta.type`
 
 - `automatic`
     - Rule makes a **normative decision**
-    - Allowed outcomes: `pass`, `fail`, `notApplicable`
+    - Allowed outcomes: `pass`, `fail`, `notApplicable`, and `cantTell` as a defensive fallback only (e.g. an internal-failure safety net, or a computability gate a rule can't resolve — see `contrast-minimum.js`/`contrast-enhanced.js`/`contrast-computable.js`/`target-size-minimum.js`), never as its primary intended path
 - `manual`
     - Rule signals **human review required**
     - Allowed outcomes: `cantTell`, `notApplicable`
@@ -24,7 +24,7 @@ Manual rules MUST NOT make normative failure decisions.
 ### 1.2 Intent
 Encoded by: **rule id suffix**
 
-Current intents:
+Illustrative intents (from the image-alternatives family used as the running example in §2, not an exhaustive list — the ruleset's 125 rules use dozens of distinct suffixes; `docs/RULE_CATALOG.md` is the generated, always-current list):
 
 - `present`
     - Verifies that a required **mechanism exists**
@@ -43,7 +43,7 @@ Intent determines whether a rule can be automatic.
 ### 1.3 Target Family
 Encoded by: **rule id prefix**
 
-Current families include:
+Illustrative families, from the image-alternatives cluster (WCAG 1.1.1) used as the running example in §2 — not an exhaustive list. The ruleset's 125 rules span dozens of families (`aria-*`, `contrast-*`, `dialog-*`, `iframe-*`, `label-*`, `link-*`, `list-*`, `landmark-*`, and more); see `docs/RULE_CATALOG.md` for the generated, always-current list:
 
 - `img`
 - `area`
@@ -67,12 +67,13 @@ Rules MUST NOT mix families.
 ### 1.4 Target Set (Tree Scope)
 Encoded by: `data.visibilityFilter.targetSet`
 
-Current value used by this ruleset:
-- `acc` (accessibility tree)
+Values used by this ruleset:
+- `acc` (accessibility tree) — most rules
+- `dom` (raw DOM/CSS visibility, no accessibility-tree computation) — e.g. `label-in-name.js`
 
-Rules explicitly log eligibility against the accessibility tree using:
-- `helpers.isAccTreeEligible`
-- `helpers.getEligibilityInfo(..., { targetSet: "acc" })`
+Rules log eligibility against whichever tree scope they target using:
+- `helpers.isAccTreeEligible` / `helpers.isDomVisibleEligible`
+- `helpers.getEligibilityInfo(..., { targetSet: "acc" | "dom" })`
 
 This is a semantic constraint, not logging noise.
 

package/docs/TROUBLESHOOTING.md

@@ -39,9 +39,9 @@ No — see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md). A `pass` means every
 
 Treat it as "needs a human to look" — it's neither pass nor fail by design. Most teams log `cantTell` findings without failing CI on them, since failing a build on something the engine explicitly couldn't determine tends to train people to ignore the gate. See [`POLICY.md`](./POLICY.md) if you want to reshape this behavior (e.g. via a custom policy contract), and [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result) for a concrete CI-gating example.
 
-## "Why is French only partially translated?"
+## "What happens if a locale is only partially translated?"
 
-It genuinely is — see [`I18N.md`](./I18N.md) for the exact current coverage. Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright.
+Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright — see [`I18N.md`](./I18N.md) for the mechanism and current coverage. Both shipped locales (`en`, `fr`) are at full parity as of this writing, but that's not guaranteed to stay true automatically: adding a new rule adds a new key to `en.js`, and unless the same key is added to `fr.js` (or any other locale file you maintain), that string falls back to English until it is.
 
 ## "`runDomRulesInPage` vs `runa11yCoreInPage` — which one do I want?"
 

package/docs/WCAG_CONFORMANCE.md

@@ -4,7 +4,7 @@ How individual rule results relate to a WCAG Success Criterion (SC), and what su
 
 ## The three layers
 
-1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 123.
+1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 125.
 2. **Facets** — a WCAG SC is usually bigger than any one rule can decide deterministically. Internally, each SC is broken into named "facets" (e.g. 1.1.1 Non-text Content has facets like `img-alt-attr-present`, `text-alternative-quality`, `decorative-null`) tracked in `src/coverage/wcag-facets.js`, each marked `full` (a rule decides it with high confidence), `partial` (a rule decides *part* of it — see each rule's own scope notes), or `manual` (no safe automated heuristic exists at all). Run `npm run coverage` to regenerate `coverage/coverage-report.md`, the per-SC facet breakdown.
 3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See [`RULE_CATALOG.md`](./RULE_CATALOG.md#composite-wcag-sc-rollup-rules-31) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@surea11y/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Lightweight DOM rules accessibility core with modular rules.",
   "main": "src/index.js",
   "bin": {
-    "surea11y": "./bin/core.js"
+    "surea11y": "bin/core.js"
   },
   "author": "Jorge Rumoroso",
   "license": "MIT",

package/src/checks/automatic/aria-allowed-attr.js

@@ -22,12 +22,7 @@
  * - SUPPORTED_ATTRS_BY_ROLE widened 2026-07-21 (7 new roles), cross-checked
  *   against a widely-used reference engine's own per-role `allowedAttrs`
  *   table AND verified each addition is an unambiguous, well-established ARIA
- *   fact rather than a blind import — that engine's own table has ~68 roles,
- *   far more than were reconciled here; this pass deliberately took only the
- *   additions with clear, specific supported attributes (not just the
- *   near-universal, thin `aria-expanded` that engine allows on most roles), and
- *   left the rest for a dedicated future full-reconciliation pass rather
- *   than rushing all 68 through at lower confidence:
+ *   fact rather than a blind import:
  *   - `searchbox`: identical to the already-covered `textbox` (ARIA
  *     explicitly defines searchbox as textbox's subclass, same supported
  *     set).
@@ -47,6 +42,34 @@
  *   - `menu`/`menubar`/`toolbar`: activedescendant/orientation — standard
  *     composite-widget properties, same family as the already-covered
  *     `tablist`.
+ * - SUPPORTED_ATTRS_BY_ROLE full-reconciliation pass 2026-07-28: the
+ *   2026-07-21 pass deliberately deferred ~61 roles where the reference
+ *   engine (axe-core) allows `aria-expanded`, treating it as too thin/
+ *   near-universal to import blindly. Checked against `aria-query`
+ *   (tracks the published WAI-ARIA 1.2 Recommendation, 6 June 2023 — the
+ *   latest actually-published version, as opposed to the in-progress 1.3
+ *   Editor's Draft) instead of axe-core directly, because axe-core's own
+ *   source comments (`// Spec difference: Aria-expanded removed in 1.2`)
+ *   show that most of its `aria-expanded` allowances are deliberate
+ *   ARIA-1.1 legacy/AT-compat carryovers axe-core keeps on purpose, not
+ *   current-spec facts — importing them wholesale would have re-added
+ *   exactly the kind of unverified allowance the 07-21 pass was avoiding.
+ *   `aria-query`'s per-role tables (with superclass inheritance resolved,
+ *   e.g. `aria-activedescendant` via the abstract `composite` role) gave a
+ *   spec-grounded diff instead. Net changes from that diff:
+ *   - `aria-expanded` added to: checkbox, columnheader, gridcell, listbox,
+ *     menuitemcheckbox, menuitemradio, row, rowheader, switch, tab —
+ *     confirmed present in current spec for these roles specifically
+ *     (unlike e.g. `listitem`, `dialog`, `alertdialog`, `heading`, which
+ *     the spec does NOT list it for — those stay excluded).
+ *   - `aria-activedescendant` added to: combobox, grid, listbox,
+ *     radiogroup, row, spinbutton, tablist, treegrid (inherited from the
+ *     abstract `composite` role for any composite/managed-focus widget).
+ *   - `aria-readonly`/`aria-required` added to: switch, menuitemcheckbox,
+ *     menuitemradio. `aria-posinset`/`aria-setsize` added to: tab, radio,
+ *     menuitemcheckbox, menuitemradio. `aria-level` added to: tablist.
+ *   - `tree`'s `aria-readonly` removed: not in aria-query's resolved
+ *     props for `tree` (was an unverified carryover, not spec-backed).
  * - Not gated on isAccTreeEligible: this is a static markup property.
  */
 
@@ -101,39 +124,39 @@ function runInPage(ctx) {
   // role/attribute pairings from the WAI-ARIA role definitions are listed.
   const SUPPORTED_ATTRS_BY_ROLE = {
     alertdialog: ['aria-modal'],
-    checkbox: ['aria-checked', 'aria-readonly', 'aria-required'],
-    columnheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected'],
-    combobox: ['aria-expanded', 'aria-autocomplete', 'aria-readonly', 'aria-required'],
+    checkbox: ['aria-checked', 'aria-readonly', 'aria-required', 'aria-expanded'],
+    columnheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected', 'aria-expanded'],
+    combobox: ['aria-expanded', 'aria-autocomplete', 'aria-readonly', 'aria-required', 'aria-activedescendant'],
     dialog: ['aria-modal'],
-    grid: ['aria-multiselectable', 'aria-readonly', 'aria-colcount', 'aria-rowcount'],
-    gridcell: ['aria-selected', 'aria-readonly', 'aria-required', 'aria-colindex', 'aria-colspan', 'aria-rowindex', 'aria-rowspan'],
+    grid: ['aria-multiselectable', 'aria-readonly', 'aria-colcount', 'aria-rowcount', 'aria-activedescendant'],
+    gridcell: ['aria-selected', 'aria-readonly', 'aria-required', 'aria-colindex', 'aria-colspan', 'aria-rowindex', 'aria-rowspan', 'aria-expanded'],
     heading: ['aria-level'],
-    listbox: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation'],
+    listbox: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-expanded', 'aria-activedescendant'],
     listitem: ['aria-level', 'aria-posinset', 'aria-setsize'],
     menu: ['aria-activedescendant', 'aria-orientation'],
     menubar: ['aria-activedescendant', 'aria-orientation'],
-    menuitemcheckbox: ['aria-checked'],
-    menuitemradio: ['aria-checked'],
+    menuitemcheckbox: ['aria-checked', 'aria-expanded', 'aria-readonly', 'aria-required', 'aria-posinset', 'aria-setsize'],
+    menuitemradio: ['aria-checked', 'aria-expanded', 'aria-readonly', 'aria-required', 'aria-posinset', 'aria-setsize'],
     meter: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext'],
     option: ['aria-selected', 'aria-checked', 'aria-posinset', 'aria-setsize'],
     progressbar: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext'],
-    radio: ['aria-checked'],
-    radiogroup: ['aria-readonly', 'aria-required', 'aria-orientation'],
-    row: ['aria-selected', 'aria-level', 'aria-posinset', 'aria-setsize', 'aria-colindex', 'aria-rowindex'],
-    rowheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected'],
+    radio: ['aria-checked', 'aria-posinset', 'aria-setsize'],
+    radiogroup: ['aria-readonly', 'aria-required', 'aria-orientation', 'aria-activedescendant'],
+    row: ['aria-selected', 'aria-level', 'aria-posinset', 'aria-setsize', 'aria-colindex', 'aria-rowindex', 'aria-expanded', 'aria-activedescendant'],
+    rowheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected', 'aria-expanded'],
     scrollbar: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation', 'aria-controls'],
     searchbox: ['aria-activedescendant', 'aria-autocomplete', 'aria-multiline', 'aria-placeholder', 'aria-readonly', 'aria-required'],
     separator: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation'],
     slider: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation', 'aria-readonly'],
-    spinbutton: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-readonly', 'aria-required'],
-    switch: ['aria-checked'],
-    tab: ['aria-selected'],
+    spinbutton: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-readonly', 'aria-required', 'aria-activedescendant'],
+    switch: ['aria-checked', 'aria-expanded', 'aria-readonly', 'aria-required'],
+    tab: ['aria-selected', 'aria-expanded', 'aria-posinset', 'aria-setsize'],
     table: ['aria-colcount', 'aria-rowcount'],
-    tablist: ['aria-multiselectable', 'aria-orientation'],
+    tablist: ['aria-multiselectable', 'aria-orientation', 'aria-level', 'aria-activedescendant'],
     textbox: ['aria-activedescendant', 'aria-autocomplete', 'aria-multiline', 'aria-placeholder', 'aria-readonly', 'aria-required'],
     toolbar: ['aria-activedescendant', 'aria-orientation'],
-    tree: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation'],
-    treegrid: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-colcount', 'aria-rowcount'],
+    tree: ['aria-multiselectable', 'aria-required', 'aria-orientation', 'aria-activedescendant'],
+    treegrid: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-colcount', 'aria-rowcount', 'aria-activedescendant'],
     treeitem: ['aria-checked', 'aria-selected', 'aria-expanded', 'aria-level', 'aria-posinset', 'aria-setsize']
   };