@stacksjs/stx 0.2.174 → 0.2.176

package/dist/a11y.d.ts

@@ -36,6 +36,29 @@ export interface A11yViolation {
     /** URL to more information */
     helpUrl?: string;
 }
+/**
+ * Has this element declared itself decorative rather than semantic?
+ *
+ * `role="presentation"` and its synonym `role="none"` remove an element's
+ * implicit semantics from the accessibility tree. On a table that is exactly the
+ * declaration that it carries layout, not data — so demanding a `<th>` or a
+ * `<caption>` asks the author to reintroduce the semantics the role exists to
+ * remove (stacksjs/stx#1916).
+ *
+ * This is not a corner case. Every HTML email is nested layout tables: mail
+ * clients strip `<style>` and have no reliable box model, so `role="presentation"`
+ * is the standard, correct pattern there. One email template accounted for every
+ * remaining finding in an otherwise-clean app, and none of them was fixable —
+ * the correct markup was what triggered them. An advisory checker with a
+ * permanent finding nobody can close is one people learn to ignore, which costs
+ * more than the rule is worth.
+ *
+ * The rule itself is right to exist: a DATA table with no headers is a real
+ * problem. It just has to take the author's word for which kind it is.
+ */
+export declare function isPresentationalRole(role: string | null | undefined): boolean;
+/** Read one attribute out of a raw tag's attribute text. */
+export declare function attributeValue(attrs: string, name: string): string | null;
 /**
  * Process accessibility directives.
  * Handles @a11y hints, @screenReader content, and @ariaDescribe.
@@ -63,6 +86,23 @@ else {
  * ```
  */
 export declare function hasDOMSupport(): boolean;
+/**
+ * Regex-based accessibility checker for non-DOM environments.
+ * Provides a subset of checks that can be performed with regex parsing.
+ *
+ * @param html - HTML content to check
+ * @param _filePath - File path for error reporting
+ * @returns Array of accessibility violations found
+ */
+/**
+ * Regex-based checking, used when no DOM is available — which is the CLI.
+ *
+ * Exported so tests can exercise it directly. It and the DOM path implement the
+ * same rules twice, and the way two implementations of one rule go wrong is by
+ * disagreeing; pinning only whichever one the test environment happens to pick
+ * leaves the other free to drift (#1916).
+ */
+export declare function checkA11yWithRegex(html: string, _filePath: string): A11yViolation[];
 /**
  * Automatically check template for accessibility issues.
  *
@@ -81,9 +121,39 @@ export declare function hasDOMSupport(): boolean;
  * ```
  */
 export declare function checkA11y(html: string, filePath: string): Promise<A11yViolation[]>;
+/** What a scan actually read, alongside what it found. */
+export interface A11yScanResult {
+    /** Files that had at least one violation, mapped to their violations. */
+    results: Record<string, A11yViolation[]>;
+    /**
+     * Every file the scan READ.
+     *
+     * Reported separately because "no violations" and "no files" are different
+     * answers that used to be the same one: `results` only ever contains files
+     * WITH violations, so an empty map means both "everything is clean" and
+     * "nothing was scanned", and the success banner was printed for both
+     * (stacksjs/stx#1918).
+     */
+    scannedFiles: string[];
+}
+/**
+ * Scan a directory, a file, or a glob for accessibility issues.
+ *
+ * The argument used to be joined into a scan pattern, so only a directory
+ * worked: a file path became `<file>/**` + `/*.stx` and a glob became a doubled
+ * pattern, both matching nothing and both reported as a clean pass. See
+ * `resolve-stx-targets.ts` for what that cost.
+ */
+export declare function scanA11yTargets(target: string | readonly string[], options?: {
+    recursive?: boolean;
+    ignorePaths?: string[];
+}): Promise<A11yScanResult>;
 /**
- * Scan a directory of stx files for accessibility issues.
- * Returns a map of file paths to their violations.
+ * Back-compatible wrapper: violations only.
+ *
+ * Kept so existing callers keep working, but it cannot say whether the scan read
+ * anything — which is the distinction #1918 turned on. Prefer
+ * {@link scanA11yTargets}.
  */
 export declare function scanA11yIssues(directory: string, options?: {
     recursive?: boolean;

package/dist/a11y.js

@@ -1,4 +1,16 @@
 import path from "node:path";
+import { resolveStxTargets } from "./resolve-stx-targets.js";
+export function isPresentationalRole(role) {
+  if (!role)
+    return !1;
+  return role.trim().split(/\s+/)[0]?.toLowerCase() === "presentation" || role.trim().split(/\s+/)[0]?.toLowerCase() === "none";
+}
+export function attributeValue(attrs, name) {
+  const match = new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(attrs);
+  if (!match)
+    return null;
+  return match[2] ?? match[3] ?? match[4] ?? null;
+}
 export function processA11yDirectives(template, _context, _filePath, _options) {
   let output = template;
   output = output.replace(/@a11y\(\s*['"]([^'"]+)['"]\s*(?:,\s*['"]([^'"]+)['"]\s*)?\)/g, (_, hintType, customMessage) => {
@@ -58,7 +70,7 @@ function protectStxComponentTags(source) {
     })
   };
 }
-function checkA11yWithRegex(html, _filePath) {
+export function checkA11yWithRegex(html, _filePath) {
   const violations = [], imgRegex = /<img\s+([^>]*)>/gi;
   let match;
   match = imgRegex.exec(html);
@@ -156,11 +168,11 @@ function checkA11yWithRegex(html, _filePath) {
       help: "Add lang attribute to the html element",
       helpUrl: "https://web.dev/learn/accessibility/more-html/#language"
     });
-  const tableRegex = /<table[^>]*>([\s\S]*?)<\/table>/gi;
+  const tableRegex = /<table([^>]*)>([\s\S]*?)<\/table>/gi;
   match = tableRegex.exec(html);
   while (match !== null) {
-    const tableContent = match[1];
-    if (!/<th\b/i.test(tableContent))
+    const tableContent = match[2];
+    if (!isPresentationalRole(attributeValue(match[1], "role")) && !/<th\b/i.test(tableContent))
       violations.push({
         type: "table-missing-headers",
         element: "<table>",
@@ -321,6 +333,8 @@ export async function checkA11y(html, filePath) {
         });
     }
     container.querySelectorAll("table").forEach((table) => {
+      if (isPresentationalRole(table.getAttribute("role")))
+        return;
       const hasCaption = table.querySelector("caption");
       if (!table.querySelector("th"))
         violations.push({
@@ -411,23 +425,24 @@ export async function checkA11y(html, filePath) {
   }
   return violations;
 }
-export async function scanA11yIssues(directory, options = {}) {
-  const results = {}, { recursive = !0, ignorePaths = [] } = options, pattern = path.join(directory, recursive ? "**/*.stx" : "*.stx"), glob = new Bun.Glob(pattern), files = [];
-  for await (const file of glob.scan())
-    if (!ignorePaths.some((ignorePath) => file.includes(path.normalize(ignorePath))))
-      files.push(file);
+export async function scanA11yTargets(target, options = {}) {
+  const results = {}, { recursive = !0, ignorePaths = [] } = options, targets = Array.isArray(target) ? target : [target], files = await resolveStxTargets(targets, { recursive, ignorePaths }), scannedFiles = [];
   for (const file of files)
     try {
       const content = await Bun.file(file).text();
       if (file.endsWith("good-a11y.stx"))
         continue;
       const violations = await checkA11y(content, file);
+      scannedFiles.push(file);
       if (violations.length > 0)
         results[file] = violations;
     } catch (error) {
       console.error(`Error scanning ${file}:`, error);
     }
-  return results;
+  return { results, scannedFiles };
+}
+export async function scanA11yIssues(directory, options = {}) {
+  return (await scanA11yTargets(directory, options)).results;
 }
 const defaultAutoFixConfig = {
   fixMissingAlt: !0,