affora 0.1.0

package/rules/generic.js

@@ -0,0 +1,299 @@
+// Generic rules — behavioural detection only, no site-specific class names.
+// These fire on any page whose widgets follow common structure or ARIA, which is
+// what makes them safe defaults for a compiled site whose class names are build
+// output. Site files (magento.js, mui.js, …) layer on top and may override.
+({
+  // A choice control: native <select>, or a custom widget claiming the role.
+  select: {
+    // Native selects always; custom choice controls only when probing them is
+    // SAFE. Probing means clicking, and a documentation site's search opens a
+    // full-screen modal that unmounts the page — on mui.com that deleted all 85
+    // sidebar links from the DOM, and parity then reported 130 severed navigation
+    // paths for a site that was working perfectly. A probe must not be able to
+    // destroy the page it is reading.
+    find: () => {
+      const safe = (e) => {
+        // A portalled listbox BELONGS to a trigger; it is not a control of its own.
+        // Replacing it separately minted a second select from the popup and left a
+        // label pointing at the popup's id after the popup closed.
+        if (e.getAttribute('role') === 'listbox') {
+          const id = e.getAttribute('id');
+          if (id && document.querySelector(
+              '[aria-controls~="' + id + '"],[aria-owns~="' + id + '"]')) return false;
+        }
+        // A LINK is not a choice control, whatever ARIA it carries, and probing
+        // means clicking: a fixture link marked aria-haspopup=listbox took the
+        // probe straight off the page.
+        if (e.tagName === 'A' || e.hasAttribute('href')) return false;
+        if (e.getAttribute('aria-haspopup') === 'dialog') return false;
+        if (e.matches('input[type="search"]')) return false;
+        if (e.closest('[role="search"],form[role="search"]')) return false;
+        const hint = ((e.getAttribute('aria-label') || '') + ' ' +
+                      (e.getAttribute('placeholder') || '') + ' ' +
+                      (e.getAttribute('name') || '')).toLowerCase();
+        return !/search|find/.test(hint);
+      };
+      // aria-haspopup="listbox" is the ARIA signature React Aria and Base UI emit;
+      // neither puts role="combobox" on the trigger, so detecting it here is the
+      // difference between covering two more libraries and writing two more files.
+      return [
+        ...document.querySelectorAll('select'),
+        ...[...document.querySelectorAll(
+              '[role="combobox"],[role="listbox"],[aria-haspopup="listbox"]')].filter(safe),
+      ];
+    },
+    extract: (el) => {
+      let opts = [];
+      if (el.tagName === 'SELECT') {
+        // Carry the GROUP each option belongs to. Flattening an <optgroup> away
+        // deletes the label that says what the group is — 'Movies', 'Europe' —
+        // which is a fact the page states and, on a grouped select, often the only
+        // thing distinguishing two identically-named options.
+        opts = [...el.options].map(o => ({
+          value: o.value, label: rsRendered(o),
+          group: o.parentElement && o.parentElement.tagName === 'OPTGROUP'
+            ? (o.parentElement.getAttribute('label') || '') : '',
+        }));
+      } else {
+        const owned = el.getAttribute('aria-controls') || el.getAttribute('aria-owns');
+        // A combobox that names its listbox is the easy case. Many do not — Mantine
+        // ships none — so fall back to the listbox that BELONGS to this control:
+        // walk up a few levels and take the first one found in that subtree. Bounded
+        // deliberately, because searching the document would attach a stray
+        // listbox's options to whichever control happened to be probed first.
+        let box = owned ? document.getElementById(owned) : null;
+        if (!box) {
+          for (let n = el, i = 0; n && i < 4; n = n.parentElement, i++) {
+            const found = n.querySelector && n.querySelector('[role="listbox"]');
+            if (found) { box = found; break; }
+          }
+        }
+        if (!box) box = el;
+        // A listbox groups its options with [role=group], and the group's name is
+        // a fact the page states — 'Movies', 'Europe' — often the only thing
+        // telling two identically-named options apart. Read it from wherever ARIA
+        // puts it: an explicit label, a referenced element, or the group's own
+        // heading text (the child that is not an option).
+        const groupName = (o) => {
+          const g = o.closest('[role="group"],optgroup');
+          if (!g) return '';
+          const byRef = g.getAttribute('aria-labelledby');
+          return (g.getAttribute('label') || g.getAttribute('aria-label')
+            || (byRef ? rsRendered(document.getElementById(byRef)) : '')
+            || rsRendered([...g.children].find(c => !c.matches('[role="option"],option,li')))
+            || '').trim();
+        };
+        opts = [...(box ? box.querySelectorAll('[role="option"],li,option') : [])]
+          .map(o => ({ value: o.getAttribute('data-value') || rsRendered(o),
+                       label: rsRendered(o), group: groupName(o) }))
+          .filter(o => o.label);
+      }
+      if (!opts.length) {
+        // PROBE. A popup's options do not exist until it opens, so a passive read
+        // can only ever skip — which is why every library that portals its options
+        // needed its own file. Open it with the page's own interaction, let the
+        // options mount, and read what the page itself rendered. Bounded at three
+        // attempts, after which the instance is skipped honestly; native selects
+        // never reach here, and a control that yields nothing is left alone.
+        if (el.tagName !== 'SELECT') {
+          const tries = +(el.getAttribute('data-rs-probe') || 0);
+          if (tries < 3) {
+            el.setAttribute('data-rs-probe', String(tries + 1));
+            el.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+            el.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }));
+            el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+            try { el.click(); } catch (e) {}
+            return 'retry';
+          }
+        }
+        return null;                                     // options unreachable: skip
+      }
+      // If the page ALREADY labels this control, do not add a second one. The
+      // replacement keeps the original id, so the existing label[for] still
+      // resolves to it — rendering our own produced a visible "Sort By Sort By"
+      // and put a duplicate of every rewritten control's label into the page.
+      // Close whatever the probe opened: leaving a popup up would let the next
+      // control's probe harvest THIS one's options.
+      if (el.getAttribute('data-rs-probe'))
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+      const id0 = el.getAttribute('id') || '';
+      const external = id0 && document.querySelector('label[for="' + CSS.escape(id0) + '"]');
+      // What the CLOSED control displays is a fact too — a placeholder ("Select
+      // movie") or the current choice. It is not one of the options, so listing
+      // only the options deleted it.
+      return { label: external ? '' : rsLabel(el), opts,
+               shown: el.tagName === 'SELECT' ? '' : rsRendered(el),
+               value: el.tagName === 'SELECT' ? el.value : '',
+               name: el.getAttribute('name') || '',
+               id: el.getAttribute('id') || '',          // keep the id: label[for] must survive
+               orig: el.tagName === 'SELECT' ? el : null,
+               trigger: el.tagName === 'SELECT' ? null : el };
+    },
+    render: (d) => {
+      const id = d.id || ('rs-' + (++window.__rsSeq));
+      const one = (o) =>
+        `<option value="${rsEsc(o.value)}"${o.value === d.value ? ' selected' : ''}>${rsEsc(o.label)}</option>`;
+      // Rebuild the groups rather than listing their members loose.
+      let opts = '', open = null;
+      d.opts.forEach(o => {
+        const g = o.group || '';
+        if (g !== open) {
+          if (open) opts += '</optgroup>';
+          if (g) opts += `<optgroup label="${rsEsc(g)}">`;
+          open = g;
+        }
+        opts += one(o);
+      });
+      if (open) opts += '</optgroup>';
+      // Lead with whatever the control was showing when closed, unless that text
+      // is already one of the options.
+      if (d.shown && !d.opts.some(o => o.label === d.shown))
+        opts = `<option value="" selected>${rsEsc(d.shown)}</option>` + opts;
+      return `<div class="rs rs-field">
+        ${d.label ? `<label class="rs-label" for="${id}">${rsEsc(d.label)}</label>` : ''}
+        <select class="rs-select" id="${id}"${d.name ? ` name="${rsEsc(d.name)}"` : ''}>${opts}</select>
+      </div>`;
+    },
+    // SHADOW-DRIVE a native select. Rebuilding one produces an element with the
+    // same options and NO BEHAVIOUR: the host's change handler stayed with the
+    // original, so choosing an option did nothing. Parity could not see it — it
+    // compares which affordances exist, not what using them does — and the sort
+    // task failed on the rewritten arm while passing on the baseline.
+    // The original rides along hidden and receives the real event.
+    after: (d, holder) => {
+      // A CUSTOM trigger gets the same treatment as a native select, for the same
+      // reason: the application holds the state and a rebuilt control has no
+      // connection to it, so the replacement would display a choice nothing
+      // receives. The original rides along hidden and is driven the way a person
+      // drives it — opened, then the matching option clicked.
+      if (d.trigger) {
+        d.trigger.style.display = 'none';
+        d.trigger.setAttribute('data-rs-done', '');
+        holder.appendChild(d.trigger);
+        const shownSel = holder.querySelector('select.rs-select');
+        if (shownSel) shownSel.addEventListener('change', () => {
+          const want = shownSel.selectedOptions[0] && shownSel.selectedOptions[0].textContent.trim();
+          if (!want) return;
+          d.trigger.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+          d.trigger.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }));
+          try { d.trigger.click(); } catch (e) {}
+          setTimeout(() => {
+            const opt = [...document.querySelectorAll('[role="option"]')]
+              .find(o => rsRendered(o) === want);
+            if (opt) opt.click();
+            else document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+          }, 140);
+        });
+        return;
+      }
+      if (!d.orig) return;
+      d.orig.style.display = 'none';
+      d.orig.setAttribute('data-rs-done', '');
+      holder.appendChild(d.orig);
+      const shown = holder.querySelector('select.rs-select');
+      if (!shown) return;
+      shown.addEventListener('change', () => {
+        d.orig.value = shown.value;
+        d.orig.dispatchEvent(new Event('input', { bubbles: true }));
+        d.orig.dispatchEvent(new Event('change', { bubbles: true }));
+      });
+    },
+  },
+
+  // A tab strip: ARIA tablists, plus the commoner un-ARIA'd form — a cluster of
+  // sibling buttons whose handlers name sibling panels. Replaced by plain
+  // sections, every panel's content present; the panels MOVE (removes/after), so
+  // nothing is duplicated and nothing is lost.
+  tabs: {
+    // flattening: the tab/section controls exist to reveal content this
+    // output reveals structurally, so they are subsumed, not lost
+    subsumes: true,
+    find: () => {
+      // A NAVIGATION switcher is not a content tab strip. Magento's mobile nav is
+      // a two-tab switch between menu and account links; flattening it revealed a
+      // mobile-only region on a desktop page and, with it, five pre-existing
+      // colour-contrast failures that were previously not rendered. Revealing
+      // content is the point of this rule; revealing a different VIEWPORT's
+      // chrome is not.
+      const contentTabs = (el) => !el.closest('nav,[role="navigation"]')
+        && !/nav-sections|switcher|viewport/i.test(String(el.className || ''));
+      const out = new Set([...document.querySelectorAll('[role="tablist"]')].filter(contentTabs));
+      document.querySelectorAll('button,[role="button"],a').forEach(b => {
+        const h = (b.getAttribute('onclick') || '') + (b.className || '');
+        if (!/tab|panel|switch/i.test(h)) return;
+        const g = b.parentElement;
+        if (!g) return;
+        const peers = [...g.children].filter(c => /^(BUTTON|A)$/.test(c.tagName) &&
+          /tab|panel|switch/i.test((c.getAttribute('onclick') || '') + (c.className || '')));
+        if (peers.length >= 2 && contentTabs(g)) out.add(g);
+      });
+      return [...out];
+    },
+    extract: (el) => {
+      const tabs = [], controls = [];
+      [...el.querySelectorAll('[role="tab"],button,[role="button"],a')].forEach(t => {
+        const title = rsRendered(t);
+        if (!title) return;
+        let panel = null;
+        const owned = t.getAttribute('aria-controls');
+        if (owned) panel = document.getElementById(owned);
+        if (!panel) {
+          const m = (t.getAttribute('onclick') || '').match(/['"]([\w -]+)['"]/);
+          if (m) panel = document.getElementById('tab-' + m[1]) || document.getElementById(m[1]);
+        }
+        if (panel) { tabs.push({ title, html: panel.innerHTML, panel }); controls.push(t); }
+      });
+      return tabs.length >= 2 ? { tabs, controls } : null;
+    },
+    anchor: (el, d) => d.controls[0],
+    render: (d) => `<div class="rs rs-sections">` + d.tabs.map(t =>
+        `<section class="rs-section"><h3 class="rs-section-title">${rsEsc(t.title)}</h3>
+         <div class="rs-section-body">${t.html}</div></section>`).join('') + `</div>`,
+    removes: (d) => [...d.controls.slice(1), ...d.tabs.map(t => t.panel)],
+    after: (d) => {
+      d.controls.slice(1).forEach(c => c.remove());
+      d.tabs.forEach(t => t.panel && t.panel.remove());
+    },
+  },
+
+  // An icon-only control — the commonest unnamed target anywhere. Its name exists
+  // in title/alt/aria-label; the swap puts that name into the DOM as visible text.
+  // No name anywhere means naming it would invent a fact: skip.
+  icon_control: {
+    find: () => [...document.querySelectorAll('button,[role="button"],a')]
+      .filter(b => !(b.textContent || '').trim() && !b.closest('.rs')),
+    extract: (el) => {
+      const name = el.getAttribute('aria-label') || el.getAttribute('title')
+        || (el.querySelector('img') || {}).alt
+        || rsRendered(el.querySelector('svg title')) || '';
+      if (!name.trim()) return null;
+      return { name: name.trim(), href: el.getAttribute('href') || '',
+               tag: el.tagName === 'A' ? 'a' : 'button', inner: el.innerHTML, src: el };
+    },
+    render: (d) => d.tag === 'a'
+      ? `<a class="rs rs-iconbtn" href="${rsEsc(d.href)}">${d.inner}<span class="rs-iconbtn-name">${rsEsc(d.name)}</span></a>`
+      : `<button type="button" class="rs rs-iconbtn">${d.inner}<span class="rs-iconbtn-name">${rsEsc(d.name)}</span></button>`,
+    // SHADOW-DRIVE the original. A rebuilt button carries the name and none of
+    // the behaviour: where the page's handler is a framework listener rather
+    // than an href, the replacement is inert, and the arm that was supposed to
+    // gain a name silently loses a control. Found on a data grid whose next-page
+    // button stopped paging; effect parity could not see it, because it only
+    // exercises controls BOTH arms name and a replaced trigger is not one.
+    after: (d, holder) => {
+      const src = d.src;
+      if (!src) return;
+      src.style.display = 'none';
+      src.setAttribute('data-rs-shadow', '');
+      holder.appendChild(src);
+      const shown = holder.querySelector('.rs-iconbtn');
+      if (!shown || shown === src) return;
+      shown.addEventListener('click', (e) => {
+        if (d.tag === 'a' && d.href) return;      // a link needs no forwarding
+        e.preventDefault();
+        src.style.display = '';
+        src.click();
+        src.style.display = 'none';
+      });
+    },
+  },
+})

package/rules/hidden-radio.js

@@ -0,0 +1,94 @@
+// A radio group whose inputs are hidden by CSS and whose labels are styled as
+// buttons — the commonest way a designer turns a choice into a row of chips.
+//
+// The pattern is behavioural, not site-specific: an <input type="radio"> made
+// imperceptible (zero size, opacity 0, clipped off-screen) beside a visible
+// <label for>. A person sees and clicks the label; a reader that enumerates the
+// action space sees neither, because the label is not a control and the input is
+// not perceivable. The option names sit in the page text with nothing to act on.
+//
+// Written for the idiom rather than for any one site, and first measured on
+// WebShop, whose own stylesheet does exactly this to every product option.
+// It is NOT part of the rule set Section 6 ran; it is the extension arm.
+({
+  hidden_radio_group: {
+    find: () => {
+      const imperceptible = (el) => {
+        const s = getComputedStyle(el);
+        if (s.display === 'none' || s.visibility === 'hidden') return true;
+        if (+s.opacity === 0) return true;
+        const r = el.getBoundingClientRect();
+        return r.width < 2 || r.height < 2;
+      };
+      const visible = (el) => {
+        if (!el) return false;
+        const s = getComputedStyle(el);
+        if (s.display === 'none' || s.visibility === 'hidden' || +s.opacity === 0) return false;
+        const r = el.getBoundingClientRect();
+        return r.width > 2 && r.height > 2;
+      };
+      const heads = new Map();
+      for (const r of document.querySelectorAll('input[type="radio"][name]')) {
+        if (r.closest('.rs')) continue;
+        if (!imperceptible(r)) continue;                  // a visible radio is fine as it is
+        const lab = r.id && document.querySelector('label[for="' + CSS.escape(r.id) + '"]');
+        if (!visible(lab)) continue;                      // hidden group, hidden label: not this pattern
+        if (!heads.has(r.name)) heads.set(r.name, lab);
+      }
+      return [...heads.values()];
+    },
+    extract: (el) => {
+      const first = document.getElementById(el.getAttribute('for'));
+      if (!first) return null;
+      const opts = [];
+      for (const r of document.querySelectorAll('input[type="radio"][name="' + CSS.escape(first.name) + '"]')) {
+        const lab = r.id && document.querySelector('label[for="' + CSS.escape(r.id) + '"]');
+        const text = lab ? rsRendered(lab) : (r.value || '');
+        if (text) opts.push({ value: text, label: text, radio: r, el: lab });
+      }
+      if (opts.length < 2) return null;
+      const chosen = opts.find((o) => o.radio.checked);
+      // The group's name is what the page already calls it: the radios' name
+      // attribute is the page's own word, and it is the only one there is. If a
+      // heading beside the group already says it, the replacement does not say
+      // it twice — a person would read the same word stacked on itself.
+      let head = el.parentElement;
+      let titled = false;
+      for (let i = 0; i < 3 && head; i++, head = head.parentElement) {
+        const h = head.querySelector('h1,h2,h3,h4,h5,legend,label:not([for])');
+        if (h && rsRendered(h).trim().toLowerCase() === String(first.name).toLowerCase()) {
+          titled = true;
+          break;
+        }
+      }
+      return { name: first.name, opts, current: chosen ? chosen.label : '', titled };
+    },
+    render: (d) => {
+      const id = 'hr-' + (++window.__rsSeq);
+      return `<div class="rs rs-field">
+        ${d.titled ? '' : `<label class="rs-label" for="${id}">${rsEsc(d.name)}</label>`}
+        <select class="rs-select" id="${id}">
+          ${d.current ? '' : `<option value="" selected>Choose ${rsEsc(d.name)}</option>`}
+          ${d.opts.map((o) => `<option value="${rsEsc(o.value)}"${o.label === d.current ? ' selected' : ''}>${rsEsc(o.label)}</option>`).join('')}
+        </select>
+      </div>`;
+    },
+    // The labels are the widget as a person sees it; they are consumed by the
+    // swap so the page does not show the same choice twice.
+    removes: (d) => d.opts.map((o) => o.el).filter(Boolean),
+    after: (d, holder) => {
+      const shown = holder.querySelector('select.rs-select');
+      if (!shown) return;
+      for (const o of d.opts) if (o.el && o.el.isConnected) o.el.remove();
+      // Drive the page's own control rather than replacing its behaviour: the
+      // hidden radio still carries the handler the application installed.
+      shown.addEventListener('change', () => {
+        const want = shown.value;
+        const hit = d.opts.find((o) => o.value === want);
+        if (!hit) return;
+        hit.radio.style.display = '';
+        hit.radio.click();
+      });
+    },
+  },
+})