@stacksjs/stx 0.2.175 → 0.2.177

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,

package/dist/builtins/attrs.d.ts

@@ -28,3 +28,22 @@ import type { ResolvedProps } from '../component-registry';
  * @param consumed - Prop names the builtin has already rendered itself.
  */
 export declare function forwardStaticAttrs(props: ResolvedProps, consumed: Set<string>): string[];
+/**
+ * Render the server-evaluated `:prop` bindings a builtin did not consume.
+ *
+ * Only `static` was ever forwarded, so `<StxLink to="/x" :title="pageTitle">`
+ * emitted an `<a>` with no title and no warning — the binding was resolved,
+ * stored, and thrown away (stacksjs/stx#1930). Client-reactive `:prop` and
+ * `@event` bindings already reach the element by another route (the component
+ * renderer re-applies them to the root), which is what made the gap specific to
+ * the server-evaluated ones and easy to miss.
+ *
+ * `null`, `undefined` and `false` DROP the attribute rather than rendering the
+ * word — that is what makes `:aria-current="active ? 'page' : null"` express
+ * "this attribute is conditional", which is the whole reason to reach for a
+ * binding instead of a literal. `true` renders bare, as HTML booleans do.
+ *
+ * @param props - The component's resolved props.
+ * @param consumed - Prop names the builtin has already rendered itself.
+ */
+export declare function forwardResolvedAttrs(props: ResolvedProps, consumed: Set<string>): string[];

package/dist/builtins/attrs.js

@@ -19,3 +19,21 @@ export function forwardStaticAttrs(props, consumed) {
   }
   return attrs;
 }
+export function forwardResolvedAttrs(props, consumed) {
+  const attrs = [];
+  for (const [key, value] of Object.entries(props.serverDynamic ?? {})) {
+    if (consumed.has(key))
+      continue;
+    if (value === null || value === void 0 || value === !1)
+      continue;
+    const name = props.serverDynamicNames?.[key] ?? key;
+    if (value === !0) {
+      attrs.push(escapeAttr(name));
+      continue;
+    }
+    if (typeof value === "object")
+      continue;
+    attrs.push(`${escapeAttr(name)}="${escapeAttr(stripControlChars(String(value)))}"`);
+  }
+  return attrs;
+}

package/dist/builtins/safe-image.js

@@ -1,4 +1,4 @@
-import { forwardStaticAttrs } from "./attrs.js";
+import { forwardResolvedAttrs, forwardStaticAttrs } from "./attrs.js";
 const DEFAULT_FALLBACK = "/images/safe-image-default.svg";
 function escapeAttr(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -34,6 +34,7 @@ export const SafeImageBuiltin = {
       "fallbackClassName"
     ]);
     imgAttrs.push(...forwardStaticAttrs(props, consumed));
+    imgAttrs.push(...forwardResolvedAttrs(props, consumed));
     const imgTag = `<img ${imgAttrs.join(" ")} />`, renderCtx = ctx.context;
     if (!renderCtx.__safeImageHandlerEmitted) {
       renderCtx.__safeImageHandlerEmitted = !0;

package/dist/builtins/stx-image.js

@@ -1,4 +1,4 @@
-import { forwardStaticAttrs } from "./attrs.js";
+import { forwardResolvedAttrs, forwardStaticAttrs } from "./attrs.js";
 const DEFAULT_BREAKPOINTS = {
   sm: 640,
   md: 768,
@@ -165,6 +165,7 @@ export const StxImageBuiltin = {
       "picture"
     ]);
     imgAttrs.push(...forwardStaticAttrs(props, consumedStatic));
+    imgAttrs.push(...forwardResolvedAttrs(props, consumedStatic));
     const imgTag = `<img ${imgAttrs.join(" ")} />`;
     let preloadTag = "";
     if (preload) {

package/dist/builtins/stx-link.js

@@ -1,4 +1,4 @@
-import { forwardStaticAttrs } from "./attrs.js";
+import { forwardResolvedAttrs, forwardStaticAttrs } from "./attrs.js";
 function escapeAttr(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -29,6 +29,7 @@ export const StxLinkBuiltin = {
       attrs.push("data-stx-prefetch");
     const consumedStatic = new Set(["to", "class", "className", "activeClass", "exactActiveClass", "prefetch"]);
     attrs.push(...forwardStaticAttrs(props, consumedStatic));
+    attrs.push(...forwardResolvedAttrs(props, consumedStatic));
     return `<a ${attrs.join(" ")}>${slotContent}</a>`;
   }
 };

package/dist/cli-flags.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Read a flag that may legitimately appear more than once.
+ *
+ * The CLI parser collapses repeats to the LAST value — `--lib a --lib b` arrives
+ * as the string `"b"`, and the same is true of `<path...>` and `[path...]`, so
+ * there is no option spec that expresses "repeatable". The typecheck command
+ * documented `--lib` as repeatable and had an `Array.isArray(options.lib)`
+ * branch that could therefore never run: a project splitting its ambient
+ * declarations across two files silently got whichever one it listed last
+ * (stacksjs/stx#1925, stacksjs/stx#1926).
+ *
+ * The failure points the wrong way, which is what made it expensive. Listing
+ * every declaration file — the obvious move, and what "repeatable" invites —
+ * lands on the UNHELPED baseline, because the one file that was helping got
+ * replaced by one that does not cover those names. That reads as "the flag does
+ * nothing" rather than "the flag is dropping all but one of my files", and it
+ * changes which errors are reported rather than merely how many: names that
+ * would resolve come back as `Cannot find name`, hiding the real diagnostics
+ * underneath them.
+ *
+ * So the values are read from argv, where all of them still are.
+ *
+ * @module cli-flags
+ */
+/**
+ * Every value given for `flag`, in the order written.
+ *
+ * Accepts both spellings — `--lib a` and `--lib=a` — because a user who has
+ * been told a flag repeats will reasonably try either.
+ *
+ * Values are returned verbatim; resolving them against a directory is the
+ * caller's business, since it is the caller that knows what they name.
+ */
+export declare function collectRepeatedFlag(argv: readonly string[], flag: string): string[];

package/dist/cli-flags.js

@@ -0,0 +1,20 @@
+export function collectRepeatedFlag(argv, flag) {
+  const values = [], inline = `${flag}=`;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith(inline)) {
+      const value = arg.slice(inline.length);
+      if (value)
+        values.push(value);
+      continue;
+    }
+    if (arg === flag) {
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("-")) {
+        values.push(next);
+        i++;
+      }
+    }
+  }
+  return values;
+}