pour-engine 1.44.1 → 1.44.2

package/config/project.config.js

@@ -6,6 +6,6 @@
 export default {
   engine: {
     name: 'pour engine',
-    version: '1.44.1',
+    version: '1.44.2',
   },
 };

package/engine/rules/wcag/3.1.1-html-lang.js

@@ -10,6 +10,40 @@
 // Keep this in step with 3.1.2-valid-lang-parts.js.
 const LANG_PATTERN = /^([a-zA-Z]{2,3}(-[a-zA-Z0-9]{1,8})*|[xXiI](-[a-zA-Z0-9]{1,8})+)$/;
 
+/** Elements that hold no words and draw nothing. */
+const WORDLESS = 'script, style, template, link, meta, base';
+
+/**
+ * Does this document hold nothing a language could apply to? 3.1.1 asks
+ * that "the default human language of each Web page can be programmatically
+ * determined", and a document with no words has no human language to
+ * determine: the placeholder about:blank frame a page parks for later, a
+ * frame a script has not written into yet. Its html element has no lang
+ * because it has no anything, and the frame's real fault, where it has one,
+ * is its missing title (4.1.2, frame-title). 3.1.2 draws the same line:
+ * a lang can only fail through words it governs.
+ *
+ * Blank is kept narrow so a doubtful document keeps its failure: no title
+ * text (a title is spoken), no text in the body, and no element in the
+ * body beyond scripts and metadata. Any other element counts as
+ * content, since an image, a control, a nested frame or a custom element
+ * can all carry words this check does not look for. An application shell
+ * waiting on its script (<div id="root"></div>) is therefore not blank.
+ */
+function blankDocument(element) {
+  const doc = element.ownerDocument;
+  if (doc.title?.trim()) return false;
+  const body = doc.body;
+  if (!body) return true;
+  // Direct children only: once every element child is wordless, the one
+  // place left for words is a text node of the body itself, and a
+  // script's source is not words.
+  return [...body.childNodes].every((node) => {
+    if (node.nodeType === 3) return !node.data.trim();
+    return node.nodeType !== 1 || node.matches(WORDLESS);
+  });
+}
+
 export default {
   id: 'html-lang',
   name: 'Page language',
@@ -20,6 +54,7 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
+    if (blankDocument(element)) return { status: 'pass' };
     const lang = element.getAttribute('lang')?.trim();
     if (!element.hasAttribute('lang')) {
       return {

package/engine/rules/wcag/4.1.2-aria-allowed-attr.js

@@ -46,6 +46,27 @@ const HANDLED_ELSEWHERE = new Set(['label', 'labelledby']);
 // Those are aria-state-unreachable's, which imports this.
 export const NATIVE_STATE = { readonly: 'readonly', required: 'required', disabled: 'disabled', checked: 'checked' };
 
+// What the author most likely meant, for the attributes that turn up most
+// on real pages, so the fix names the repair and not just the fault. Each
+// says where ARIA 1.2 puts the attribute (its "Used in Roles" list) and what
+// serves the same purpose on this role. An attribute with no entry gets the
+// general advice. Added 2026-09-21 after inclusion.hsbc.com marked the
+// chosen language with aria-selected on a link, where "move it to the
+// control that toggles this one" pointed nowhere: the repair there is
+// aria-current.
+const HINT = {
+  selected: (role) => (role === 'cell'
+    ? 'A table whose cells can be selected is a grid: aria-selected needs role="grid" on the table, which makes its cells gridcells.'
+    : `aria-selected belongs to option, tab, row and gridcell. To mark the current item in a set of ${role === 'link' ? 'links' : 'items'}, such as the current page, language or step, use aria-current, which is global and allowed on this role.`),
+  expanded: (role) => (role === 'textbox' || role === 'searchbox'
+    ? 'A text field that opens a list of suggestions is a combobox: aria-expanded needs role="combobox", which ARIA in HTML allows on a text input, with aria-controls pointing at the list.'
+    : 'aria-expanded belongs on the control that opens and closes the content, a button in most cases, and not on the content or its container. Put it on that control; if this element is itself what the user presses, it should be a button.'),
+  checked: (role) => (role === 'button'
+    ? 'A button that stays on or off takes aria-pressed, not aria-checked.'
+    : 'aria-checked belongs to checkbox, radio, switch, option and the checkable menu items. For something the user ticks, use a native checkbox or radio input.'),
+  pressed: () => 'aria-pressed belongs to button alone. If this element switches something on and off, make it a button element.',
+};
+
 /** The element's role and the non-global aria- attributes (names without
  *  the prefix) that role does not support, or null when there are none or
  *  the role is not modelled. Shared with aria-state-unreachable. */
@@ -66,6 +87,15 @@ export function unsupportedAria(element) {
   return names.length ? { role, names } : null;
 }
 
+/** The repair for each unsupported attribute: its own hint where there is
+ *  one, the general advice for the rest. */
+function repair(attrs, role) {
+  const hinted = attrs.filter((name) => HINT[name]).map((name) => HINT[name](role));
+  const rest = attrs.filter((name) => !HINT[name]).map((name) => `aria-${name}`);
+  if (rest.length) hinted.push(`Move ${rest.join('/')} to the element whose role supports it.`);
+  return hinted.join(' ');
+}
+
 export default {
   id: 'aria-allowed-attr',
   name: 'Allowed ARIA attributes',
@@ -86,7 +116,7 @@ export default {
     return {
       status: 'fail',
       message: `${names.join(', ')} is not supported on role "${role}" (ARIA 1.2 §8.6), so user agents drop it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. If the element really has that state, it is invisible to a screen reader; if it does not, the attribute is stray and no one is affected, but ARIA 1.2 still says authors MUST NOT write it.`,
-      fix: `Move ${names.join('/')} to the element whose role supports it, usually the control that toggles this one, or remove it if the element has no such state. Adding a role to this element to make the attribute legal is rarely right: the host language restricts which roles each element may take.`,
+      fix: `${repair(disallowed, role)} If the element has no such state, remove the attribute. Adding a role to this element to make the attribute legal is rarely right: the host language restricts which roles each element may take.`,
     };
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.44.1",
+  "version": "1.44.2",
   "description": "Accessibility (WCAG 2.2) audit engine written from the W3C specifications — runs entirely in the browser, no dependencies.",
   "type": "module",
   "main": "engine/index.js",