stimeo-ui 0.5.0 → 0.7.0

package/dist/inspector/cli_bin.js

@@ -1,12 +1,71 @@
 #!/usr/bin/env node
 import process2 from 'process';
-import { statSync, readdirSync, readFileSync } from 'fs';
+import { readFileSync, statSync, readdirSync } from 'fs';
 import { relative, join, dirname, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { createInterface } from 'readline';
 
 // src/inspector/cli_bin.ts
 
+// src/inspector/announcer_rules.ts
+var ANNOUNCER_IDENTIFIER = "stimeo--announcer";
+var ANNOUNCING_CONTROLLERS = [
+  "stimeo--auto-submit",
+  "stimeo--character-counter",
+  "stimeo--countdown",
+  "stimeo--direct-upload",
+  "stimeo--empty-state",
+  "stimeo--flash",
+  "stimeo--form-field",
+  "stimeo--frame-loading",
+  "stimeo--meter",
+  "stimeo--multi-select",
+  "stimeo--nested-form",
+  "stimeo--network-status",
+  "stimeo--progress",
+  "stimeo--skeleton",
+  "stimeo--spinner",
+  "stimeo--submit-once",
+  "stimeo--tags-input"
+];
+function positionAt(source, index) {
+  const before = source.slice(0, index);
+  const line = before.split("\n").length;
+  const lastBreak = before.lastIndexOf("\n");
+  return { line, column: index - lastBreak };
+}
+function firstAnnouncingHit(scanned) {
+  let best = null;
+  let bestIndex = Number.POSITIVE_INFINITY;
+  for (const identifier of ANNOUNCING_CONTROLLERS) {
+    const index = scanned.source.indexOf(identifier);
+    if (index === -1 || index >= bestIndex) continue;
+    bestIndex = index;
+    best = { file: scanned.file, identifier, ...positionAt(scanned.source, index) };
+  }
+  return best;
+}
+function announcerSeatingDiagnostic(sources) {
+  let speaker = null;
+  for (const scanned of sources) {
+    if (scanned.source.includes(ANNOUNCER_IDENTIFIER)) return null;
+    if (!speaker) speaker = firstAnnouncingHit(scanned);
+  }
+  if (!speaker) return null;
+  return {
+    file: speaker.file,
+    diagnostic: {
+      code: "missing-announcer",
+      severity: "warning",
+      message: `"${speaker.identifier}" speaks through the shared announcer, and none of the scanned files seats one.`,
+      line: speaker.line,
+      column: speaker.column,
+      length: speaker.identifier.length,
+      suggestion: `Add an element with data-controller="${ANNOUNCER_IDENTIFIER}" (and an assertive/polite target) to the layout, or include the layout in the checked paths.`
+    }
+  };
+}
+
 // src/inspector/html_parser.ts
 var ERB_ELEMENT_TAG = "#erb";
 var VOID_ELEMENTS = /* @__PURE__ */ new Set([
@@ -932,10 +991,16 @@ function actionDescriptors(dataActionValue) {
     if (hash === -1) continue;
     let lhs = descriptor.slice(0, hash);
     const arrow = lhs.indexOf("->");
-    if (arrow !== -1) lhs = lhs.slice(arrow + 2);
+    let eventType = "";
+    if (arrow !== -1) {
+      eventType = lhs.slice(0, arrow);
+      lhs = lhs.slice(arrow + 2);
+      const at = eventType.indexOf("@");
+      if (at !== -1) eventType = eventType.slice(0, at);
+    }
     if (!lhs.startsWith(NAMESPACE_PREFIX)) continue;
     const method = /^[a-zA-Z_$][\w$]*/.exec(descriptor.slice(hash + 1))?.[0] ?? "";
-    descriptors.push({ identifier: lhs, method });
+    descriptors.push({ identifier: lhs, method, eventType });
   }
   return descriptors;
 }
@@ -954,6 +1019,8 @@ var DIAGNOSTIC_CODES = [
   "orphan-target",
   "missing-required-target",
   "missing-conditional-target",
+  "missing-required-action",
+  "missing-action-completion",
   "missing-aria",
   "invalid-aria-value",
   "keyboard-inaccessible",
@@ -965,10 +1032,30 @@ var DIAGNOSTIC_CODES = [
   "undeclared-target",
   "cardinality-violation",
   "forbidden-aria",
+  "missing-announcer",
   "unknown-ignore-code"
 ];
 
 // src/inspector/check.ts
+function isInside(node, ancestor) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (current === ancestor) return true;
+  }
+  return false;
+}
+function matchesHost(node, selector) {
+  if (node.tag !== selector.tag) return false;
+  if (!selector.attr) return true;
+  const attr = node.attrs.find((candidate) => candidate.name === selector.attr);
+  return attr !== void 0 && (selector.values ?? []).includes(attr.value.trim().toLowerCase());
+}
+function nearestHost(node, selectors) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (current.origin !== "markup" || current.opaque) return void 0;
+    if (selectors.some((selector) => matchesHost(current, selector))) return current;
+  }
+  return null;
+}
 function checkSource(source, manifest) {
   const diagnostics = [];
   const tree = parseHtml(neutralizeErb(source), erbElements(source));
@@ -987,7 +1074,9 @@ function checkSource(source, manifest) {
       (a) => a.name === `data-${identifier}-${dasherize(when.value)}-value`
     );
     if (hostAttr && isDynamicValue(hostAttr)) return null;
-    return when.equals.includes(hostAttr ? hostAttr.value.trim() : when.default);
+    const raw = hostAttr ? hostAttr.value : when.default;
+    const effective = when.type === "boolean" ? String(!(raw === "0" || raw.toLowerCase() === "false")) : raw;
+    return when.equals.includes(effective);
   };
   const isContentEditable2 = (element) => {
     let current = element;
@@ -1060,6 +1149,17 @@ function checkSource(source, manifest) {
   const scopes = [];
   const presence = /* @__PURE__ */ new Map();
   const targetNodes = /* @__PURE__ */ new Map();
+  const wiredActions = /* @__PURE__ */ new Map();
+  const recordAction = (owner, identifier, element, method, eventType) => {
+    let byId = wiredActions.get(owner);
+    if (!byId) {
+      byId = /* @__PURE__ */ new Map();
+      wiredActions.set(owner, byId);
+    }
+    const found = byId.get(identifier);
+    if (found) found.push({ element, method, eventType });
+    else byId.set(identifier, [{ element, method, eventType }]);
+  };
   const recordPresence = (owner, identifier, target) => {
     let byId = presence.get(owner);
     if (!byId) {
@@ -1268,11 +1368,12 @@ function checkSource(source, manifest) {
                 (candidate) => dasherize(candidate.value) === parsed.valueToken
               );
               if (constraint && !valueSatisfiesConstraint(attr.value, constraint)) {
+                const literal = constraint.type === "string" ? attr.value : attr.value.trim();
                 report(
                   node,
                   "invalid-value",
                   "error",
-                  `Invalid value "${attr.value.trim()}" for "${parsed.identifier}.${parsed.valueToken}". Expected ${describeValueConstraint(constraint)}.`,
+                  `Invalid value "${literal}" for "${parsed.identifier}.${parsed.valueToken}". Expected ${describeValueConstraint(constraint)}.`,
                   attr,
                   constraint.suggestion
                 );
@@ -1283,8 +1384,12 @@ function checkSource(source, manifest) {
         }
       }
       if (attr.name === "data-action") {
-        for (const { identifier, method } of actionDescriptors(attr.value)) {
+        for (const { identifier, method, eventType } of actionDescriptors(attr.value)) {
           const controller = known[identifier];
+          if (controller && method.length > 0) {
+            const owner = findOwner(node, identifier);
+            if (owner) recordAction(owner, identifier, node, method, eventType);
+          }
           if (!controller) {
             const best = nearestName(identifier, knownIdentifiers);
             report(
@@ -1366,18 +1471,89 @@ function checkSource(source, manifest) {
     const present = presence.get(node)?.get(identifier) ?? /* @__PURE__ */ new Set();
     for (const rule of controller.conditionalTargets) {
       if (!present.has(rule.whenPresent)) continue;
-      const missing = rule.require.filter((target) => !present.has(target));
+      const nodesOf = (target) => targetNodes.get(node)?.get(identifier)?.get(target) ?? [];
+      const owners = nodesOf(rule.whenPresent);
+      const hosts = rule.requireSameHost;
+      const sharesHost = (target, selectors) => {
+        const ownerHosts = owners.map((owner) => nearestHost(owner, selectors));
+        if (ownerHosts.some((host) => !host)) return true;
+        const candidates = nodesOf(target);
+        if (candidates.length === 0) return false;
+        return candidates.some((el) => {
+          const host = nearestHost(el, selectors);
+          return host ? ownerHosts.includes(host) : true;
+        });
+      };
+      const satisfied = (target) => {
+        if (hosts) return sharesHost(target, hosts);
+        if (rule.requireInside)
+          return nodesOf(target).some((el) => owners.some((owner) => isInside(el, owner)));
+        return present.has(target);
+      };
+      const missing = rule.require.filter((target) => !satisfied(target));
       if (missing.length === 0) continue;
       report(
         node,
         "missing-conditional-target",
         complete ? "error" : "warning",
-        `"${identifier}" has a "${rule.whenPresent}" target, which also requires ${list(missing)}.`,
+        hosts ? `"${identifier}" requires ${list(missing)} in the same ${rule.hostLabel ?? "element"} as its "${rule.whenPresent}".` : rule.requireInside ? `"${identifier}" requires ${list(missing)} inside its "${rule.whenPresent}".` : `"${identifier}" has a "${rule.whenPresent}" target, which also requires ${list(missing)}.`,
         node,
         complete ? rule.suggestion : UNRESOLVED_TARGET_HINT
       );
     }
   }
+  for (const { node, identifier } of scopes) {
+    const controller = known[identifier];
+    if (!controller) continue;
+    const wired = wiredActions.get(node)?.get(identifier) ?? [];
+    for (const rule of controller.requiredActions) {
+      if (conditionHolds(node, identifier, rule.when) !== true) continue;
+      const elements = rule.target === "" ? [node] : targetNodes.get(node)?.get(identifier)?.get(rule.target) ?? [];
+      for (const element of elements) {
+        const actionAttr = element.attrs.find((attr) => attr.name === "data-action");
+        if (element.opaque || actionAttr && isDynamicValue(actionAttr)) continue;
+        const satisfied = wired.some(
+          (action) => action.element === element && action.method === rule.action && rule.eventTypes.includes(action.eventType)
+        );
+        if (satisfied) continue;
+        const where = rule.target === "" ? "scope element" : `"${rule.target}" target`;
+        report(
+          element,
+          "missing-required-action",
+          "error",
+          `The ${where} of "${identifier}" requires action "${rule.action}" on ${list(rule.eventTypes)} in this configuration.`,
+          element,
+          rule.suggestion
+        );
+      }
+    }
+  }
+  for (const { node, identifier } of scopes) {
+    const controller = known[identifier];
+    if (!controller) continue;
+    const wired = wiredActions.get(node)?.get(identifier) ?? [];
+    if (wired.length === 0) continue;
+    for (const rule of controller.actionCompletion) {
+      const opens = wired.some(
+        (action) => action.method === rule.opens && rule.whenTriggeredBy.includes(action.eventType)
+      );
+      if (!opens) continue;
+      if (wired.some((action) => rule.closedBy.includes(action.method))) continue;
+      if (rule.escapeValue) {
+        const attrName = `data-${identifier}-${dasherize(rule.escapeValue)}-value`;
+        const authored = node.attrs.find((attr) => attr.name === attrName);
+        if (authored && (isDynamicValue(authored) || Number(authored.value.trim()) !== 0)) continue;
+      }
+      report(
+        node,
+        "missing-action-completion",
+        "warning",
+        `"${identifier}" opens a state with "${rule.opens}" here, and nothing in this scope closes it.`,
+        node,
+        rule.suggestion
+      );
+    }
+  }
   for (const { node, identifier } of scopes) {
     const controller = known[identifier];
     if (!controller) continue;
@@ -1390,7 +1566,7 @@ function checkSource(source, manifest) {
         if (!hasReadableMarkup(el)) continue;
         if (!contentHolds(node, identifier, el, req.whenContains)) continue;
         if (!elementHolds(el, req.whenElement)) continue;
-        checkA11y(report, el, identifier, req, severity);
+        checkA11y(report, el, identifier, req, severity, isDynamicValue);
       }
     }
   }
@@ -1680,20 +1856,24 @@ function checkSource(source, manifest) {
   return diagnostics;
 }
 function valueSatisfiesConstraint(raw, constraint) {
+  if (constraint.type === "string") return constraint.allowedValues.includes(raw);
   const value = decodeNumericValue(raw);
   if (Number.isNaN(value)) return false;
   if (constraint.finite && !Number.isFinite(value)) return false;
   if (constraint.greaterThan !== void 0 && !(value > constraint.greaterThan)) return false;
+  if (constraint.integer && !Number.isInteger(value)) return false;
   return true;
 }
 function decodeNumericValue(raw) {
   return Number(raw.replace(/_/g, ""));
 }
 function describeValueConstraint(constraint) {
+  if (constraint.type === "string") return `one of ${list(constraint.allowedValues)}`;
   const parts = [constraint.finite ? "a finite number" : "a number"];
   if (constraint.greaterThan !== void 0) {
     parts.push(`greater than ${constraint.greaterThan}`);
   }
+  if (constraint.integer) parts.push("with no fractional part");
   return parts.join(" ");
 }
 var UNRESOLVED_TARGET_HINT = "Part of this scope is rendered by a helper or a non-literal data: hash, so the target may exist at runtime.";
@@ -1701,7 +1881,7 @@ var UNRESOLVED_HOST_HINT = "An enclosing helper's data: option is not a literal
 function hasReadableMarkup(el) {
   return el.origin === "markup";
 }
-function checkA11y(report, el, identifier, req, severity) {
+function checkA11y(report, el, identifier, req, severity, isDynamicValue) {
   const groups = [
     { attrs: req.attrs, values: req.values },
     ...req.or ?? []
@@ -1721,9 +1901,14 @@ function checkA11y(report, el, identifier, req, severity) {
   }
   const invalid = [];
   let anyPresent = false;
+  let blank;
   for (const [name, allowed] of allowedByAttr) {
     const attr = el.attrs.find((a) => a.name === name);
     if (!attr) continue;
+    if (allowed.anyValue && attr.value.trim() === "" && !isDynamicValue(attr)) {
+      blank ??= attr;
+      continue;
+    }
     anyPresent = true;
     if (!allowed.anyValue && !allowed.values.has(attr.value.trim())) {
       invalid.push({ attr, values: [...allowed.values] });
@@ -1735,8 +1920,8 @@ function checkA11y(report, el, identifier, req, severity) {
       el,
       "missing-aria",
       severity,
-      `"${identifier}" ${verb} ${describeAttrs([...allowedByAttr.keys()])} on its ${where}.`,
-      el,
+      blank ? `${blank.name} is empty on the ${where} of "${identifier}", which ${verb} a value there.` : `"${identifier}" ${verb} ${describeAttrs([...allowedByAttr.keys()])} on its ${where}.`,
+      blank ?? el,
       req.suggestion
     );
     return;
@@ -1938,6 +2123,8 @@ var CONTROLLER_ARRAY_FIELDS = [
   "events",
   "requiredTargets",
   "conditionalTargets",
+  "requiredActions",
+  "actionCompletion",
   "a11y",
   "keyboard",
   "hosts",
@@ -2000,10 +2187,16 @@ function collectFiles(target, out) {
   }
   if (isCheckableFile(target)) out.push(target);
 }
-function checkFile(file, manifest) {
-  const source = readFileSync(file, "utf8");
+function checkFile(file, source, manifest) {
   return { file, diagnostics: checkSource(source, manifest) };
 }
+function withAnnouncerSeating(reports, sources) {
+  const seating = announcerSeatingDiagnostic(sources);
+  if (!seating) return [...reports];
+  return reports.map(
+    (report) => report.file === seating.file ? { file: report.file, diagnostics: [...report.diagnostics, seating.diagnostic] } : report
+  );
+}
 function formatDiagnostic(d) {
   const where = `${d.line}:${d.column}`.padEnd(7);
   const head = `  ${where} ${d.severity.padEnd(7)} ${d.message} [${d.code}]`;
@@ -2136,13 +2329,14 @@ ${USAGE}`);
   const manifest = load();
   const cwd = process2.cwd();
   const reports = [];
+  const sources = [];
   for (const file of files.sort()) {
-    reports.push({
-      file: relative(cwd, file) || file,
-      diagnostics: checkFile(file, manifest).diagnostics
-    });
+    const path = relative(cwd, file) || file;
+    const source = readFileSync(file, "utf8");
+    sources.push({ file: path, source });
+    reports.push(checkFile(path, source, manifest));
   }
-  const summary = buildCheckReport(reports, files.length);
+  const summary = buildCheckReport(withAnnouncerSeating(reports, sources), files.length);
   if (json) {
     write(JSON.stringify(summary, null, 2));
     return summary.errorCount > 0 ? 1 : 0;
@@ -2372,6 +2566,17 @@ var EXAMPLE_RESULT_SCHEMA = {
   },
   required: ["id", "file", "source", "guidance"]
 };
+var VALUE_CONDITION_SCHEMA = {
+  type: "object",
+  description: "Own-value condition arming a rule; absent means unconditional.",
+  properties: {
+    value: { type: "string" },
+    type: { type: "string", enum: ["boolean", "string"] },
+    equals: STRING_ARRAY,
+    default: { type: "string" }
+  },
+  required: ["value", "type", "equals", "default"]
+};
 var CONTENT_CONDITION_SCHEMA = {
   type: "object",
   description: "Condition on the element's own contents arming the rule; absent means it does not depend on them. Evaluated per element, unlike the scope-level `when`.",
@@ -2420,9 +2625,14 @@ var CONTROLLER_CONTRACT_SCHEMA = {
         type: "object",
         properties: {
           value: { type: "string", description: "Camel-case declared Value name." },
-          type: { type: "string", enum: ["number"] },
+          type: { type: "string", enum: ["number", "string"] },
           finite: { type: "boolean" },
           greaterThan: { type: "number" },
+          integer: { type: "boolean" },
+          allowedValues: {
+            ...STRING_ARRAY,
+            description: "Accepted literals for a String Value constraint."
+          },
           suggestion: { type: "string" }
         },
         required: ["value", "type", "suggestion"]
@@ -2463,6 +2673,45 @@ var CONTROLLER_CONTRACT_SCHEMA = {
         required: ["whenPresent", "require", "suggestion"]
       }
     },
+    requiredActions: {
+      type: "array",
+      description: "Action bindings required on a particular element in one configured Value state.",
+      items: {
+        type: "object",
+        properties: {
+          target: { type: "string", description: 'Target name; "" means the scope element.' },
+          action: { type: "string", description: "Public action method that must be wired." },
+          eventTypes: {
+            ...STRING_ARRAY,
+            description: "Event types that make the binding usable for this contract."
+          },
+          when: VALUE_CONDITION_SCHEMA,
+          suggestion: { type: "string" }
+        },
+        required: ["target", "action", "eventTypes", "suggestion"]
+      }
+    },
+    actionCompletion: {
+      type: "array",
+      description: "States an action opens that the consumer's own wiring has to close. Wiring the opening action without any closing one leaves the controller busy for good, and nothing else in the markup reveals it.",
+      items: {
+        type: "object",
+        properties: {
+          opens: { type: "string", description: "Action that opens the state." },
+          whenTriggeredBy: {
+            ...STRING_ARRAY,
+            description: "Event types for that action the controller cannot complete itself."
+          },
+          closedBy: { ...STRING_ARRAY, description: "Any one of these closes it again." },
+          escapeValue: {
+            type: "string",
+            description: "Value whose non-zero number supplies an automatic exit instead."
+          },
+          suggestion: { type: "string" }
+        },
+        required: ["opens", "whenTriggeredBy", "closedBy", "suggestion"]
+      }
+    },
     a11y: {
       type: "array",
       description: "Author-supplied ARIA the controller relies on but never sets itself.",
@@ -2484,16 +2733,7 @@ var CONTROLLER_CONTRACT_SCHEMA = {
               required: ["attrs"]
             }
           },
-          when: {
-            type: "object",
-            description: "Own-value condition arming the requirement; absent means unconditional. Outside the named configuration the ARIA is not optional but wrong.",
-            properties: {
-              value: { type: "string" },
-              equals: STRING_ARRAY,
-              default: { type: "string" }
-            },
-            required: ["value", "equals", "default"]
-          },
+          when: VALUE_CONDITION_SCHEMA,
           whenContains: CONTENT_CONDITION_SCHEMA,
           whenElement: ELEMENT_CONDITION_SCHEMA,
           whenDocument: DOCUMENT_CONDITION_SCHEMA,
@@ -2577,16 +2817,7 @@ var CONTROLLER_CONTRACT_SCHEMA = {
             description: "Check the scope element when the target is absent."
           },
           coController: { type: "string", description: "Companion controller identifier." },
-          when: {
-            type: "object",
-            description: "Host-value condition arming the rule; absent means unconditional.",
-            properties: {
-              value: { type: "string" },
-              equals: STRING_ARRAY,
-              default: { type: "string" }
-            },
-            required: ["value", "equals", "default"]
-          },
+          when: VALUE_CONDITION_SCHEMA,
           require: {
             type: "object",
             description: "Companion-value requirement (first allowed value is canonical).",
@@ -2650,16 +2881,7 @@ var CONTROLLER_CONTRACT_SCHEMA = {
           values: { ...STRING_ARRAY, description: "Restrict the attribute to these values." },
           min: { type: "integer", description: "Smallest permitted count (inclusive)." },
           max: { type: "integer", description: "Largest permitted count (inclusive)." },
-          when: {
-            type: "object",
-            description: "Own-value condition arming the bound; absent means unconditional.",
-            properties: {
-              value: { type: "string" },
-              equals: STRING_ARRAY,
-              default: { type: "string" }
-            },
-            required: ["value", "equals", "default"]
-          },
+          when: VALUE_CONDITION_SCHEMA,
           suggestion: { type: "string" }
         },
         required: ["within", "target", "suggestion"]
@@ -2691,6 +2913,8 @@ var CONTROLLER_CONTRACT_SCHEMA = {
     "events",
     "requiredTargets",
     "conditionalTargets",
+    "requiredActions",
+    "actionCompletion",
     "a11y",
     "keyboard",
     "hosts",