stimeo-ui 0.6.0 → 0.7.0

package/dist/inspector/cli.d.ts

@@ -48,6 +48,16 @@ interface ControllerManifest {
      * {@link ConditionalTargetRule}.
      */
     readonly conditionalTargets: readonly ConditionalTargetRule[];
+    /**
+     * Actions required on a particular element in one Value configuration. See
+     * {@link RequiredActionRule}.
+     */
+    readonly requiredActions: readonly RequiredActionRule[];
+    /**
+     * States an action opens that the consumer's wiring has to close. See
+     * {@link ActionCompletionRule}.
+     */
+    readonly actionCompletion: readonly ActionCompletionRule[];
     /**
      * Accessibility requirements the *consumer's markup* must satisfy (stage 3):
      * ARIA attributes the controller does **not** set at runtime and therefore
@@ -140,6 +150,8 @@ interface ControllerManifest {
 interface ValueCondition {
     /** Value name (camelCase, as declared in `static values`). */
     readonly value: string;
+    /** Stimulus decoder used before comparing the effective value. */
+    readonly type: "boolean" | "string";
     /** Effective values that arm the rule. */
     readonly equals: readonly string[];
     /** The value's declared default, used when the attribute is absent. */
@@ -608,6 +620,85 @@ interface ConditionalTargetRule {
      * controller then refuses to build from.
      */
     readonly requireInside?: boolean;
+    /**
+     * Require each {@link require} entry to share its nearest enclosing host —
+     * the closest ancestor matching one of these selectors — with the
+     * `whenPresent` element.
+     *
+     * Neither presence nor {@link requireInside} can express a pair that must sit
+     * in the *same* container without being nested in one another. A controller
+     * that swaps one host's two halves reads them per host, so halves split
+     * across two hosts leave each host with an incomplete pair, and the swap
+     * silently does nothing on markup where both names are present.
+     *
+     * Only a pair whose halves both resolve to a host is judged. A template
+     * helper that emits the host leaves nothing in the parsed markup, so an
+     * element with no host above it is indistinguishable from one whose host is
+     * generated — reporting either would be a guess, and the check stays quiet.
+     */
+    readonly requireSameHost?: readonly HostSelector[];
+    /**
+     * What to call the shared host in the diagnostic (e.g. `submit control`).
+     * The selectors' tag names read as a disjunction of element names, which
+     * names the mechanism rather than the thing the author is looking at.
+     */
+    readonly hostLabel?: string;
+    /** Human-readable fix suggestion shown by the CLI (stage 4). */
+    readonly suggestion: string;
+}
+/**
+ * One element shape that can act as a host for {@link
+ * ConditionalTargetRule.requireSameHost}.
+ *
+ * A tag alone is too coarse where the element's `type` decides its role, so an
+ * optional attribute filter narrows it. Omitting {@link attr} accepts the tag
+ * however it is spelled.
+ */
+interface HostSelector {
+    /** Lowercased tag name. */
+    readonly tag: string;
+    /** Attribute that must carry one of {@link values} for the tag to qualify. */
+    readonly attr?: string;
+    /** Accepted lowercased values of {@link attr}. */
+    readonly values?: readonly string[];
+}
+/**
+ * An action that puts a controller into a state it cannot leave on its own.
+ *
+ * A controller whose busy state is opened declaratively has no way to know the
+ * consumer never wired the matching exit: nothing throws, the markup is
+ * well-formed, and the only symptom is a control that stays disabled for the
+ * rest of the page's life. The check reads the wiring the author did declare
+ * and says so before it ships.
+ */
+interface ActionCompletionRule {
+    /** Action that opens the state. */
+    readonly opens: string;
+    /** Any one of these actions closes it again. */
+    readonly closedBy: readonly string[];
+    /** Event types for {@link opens} that the controller cannot complete itself. */
+    readonly whenTriggeredBy: readonly string[];
+    /** Value whose non-zero number supplies an automatic exit instead. */
+    readonly escapeValue?: string;
+    /** Human-readable fix suggestion shown by the CLI (stage 4). */
+    readonly suggestion: string;
+}
+/**
+ * An action binding that must exist for one configured behavior to be usable.
+ *
+ * Declaring an action method on the controller only proves the method exists;
+ * Stimulus still needs the consumer to wire it. Optional interactive variants
+ * can otherwise enter the Tab order while every key silently does nothing.
+ */
+interface RequiredActionRule {
+    /** Target whose element must carry the action; `""` means the scope element. */
+    readonly target: string;
+    /** Public controller action method that must be wired. */
+    readonly action: string;
+    /** Event types that make the binding usable for this contract. */
+    readonly eventTypes: readonly string[];
+    /** Configuration in which the binding becomes mandatory. */
+    readonly when?: ValueCondition;
     /** Human-readable fix suggestion shown by the CLI (stage 4). */
     readonly suggestion: string;
 }
@@ -618,10 +709,10 @@ interface ConditionalTargetRule {
  * ""))`) before applying these bounds. ERB-generated values are undecidable and
  * skipped rather than guessed.
  */
-interface ValueConstraint {
+interface NumericValueConstraint {
     /** Value name (camelCase, as declared in `static values`). */
     readonly value: string;
-    /** Decoder family. Numeric bounds are the first supported semantic family. */
+    /** Decoder family. */
     readonly type: "number";
     /** Reject `NaN` and infinities when true. */
     readonly finite?: boolean;
@@ -632,6 +723,19 @@ interface ValueConstraint {
     /** Human-readable fix suggestion shown by the CLI (stage 4). */
     readonly suggestion: string;
 }
+/** A statically checkable finite set of accepted String Value literals. */
+interface StringValueConstraint {
+    /** Value name (camelCase, as declared in `static values`). */
+    readonly value: string;
+    /** Decoder family. */
+    readonly type: "string";
+    /** Exact authored literals accepted by the public contract. */
+    readonly allowedValues: readonly string[];
+    /** Human-readable fix suggestion shown by the CLI (stage 4). */
+    readonly suggestion: string;
+}
+/** A statically checkable semantic contract on one declared Stimulus Value. */
+type ValueConstraint = NumericValueConstraint | StringValueConstraint;
 /**
  * A statically checkable relationship between two numeric Stimulus Values.
  *
@@ -659,7 +763,7 @@ type DiagnosticSeverity = "error" | "warning";
  * for testing, machine-readable output, and `data-stimeo-ignore` suppression
  * lists (which is why the set also exists as a runtime array).
  */
-declare const DIAGNOSTIC_CODES: readonly ["unknown-controller", "unknown-target", "unknown-value", "invalid-value", "unknown-action-controller", "unknown-action-method", "orphan-target", "missing-required-target", "missing-conditional-target", "missing-aria", "invalid-aria-value", "keyboard-inaccessible", "invalid-host", "unresolved-idref", "managed-aria", "composition-mismatch", "missing-companion", "undeclared-target", "cardinality-violation", "forbidden-aria", "unknown-ignore-code"];
+declare const DIAGNOSTIC_CODES: readonly ["unknown-controller", "unknown-target", "unknown-value", "invalid-value", "unknown-action-controller", "unknown-action-method", "orphan-target", "missing-required-target", "missing-conditional-target", "missing-required-action", "missing-action-completion", "missing-aria", "invalid-aria-value", "keyboard-inaccessible", "invalid-host", "unresolved-idref", "managed-aria", "composition-mismatch", "missing-companion", "undeclared-target", "cardinality-violation", "forbidden-aria", "missing-announcer", "unknown-ignore-code"];
 /** See {@link DIAGNOSTIC_CODES}. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 /**

package/dist/inspector/cli.js

@@ -5,6 +5,65 @@ import { fileURLToPath } from 'url';
 
 // src/inspector/cli.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([
@@ -930,10 +989,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;
 }
@@ -952,6 +1017,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",
@@ -963,6 +1030,7 @@ var DIAGNOSTIC_CODES = [
   "undeclared-target",
   "cardinality-violation",
   "forbidden-aria",
+  "missing-announcer",
   "unknown-ignore-code"
 ];
 
@@ -973,6 +1041,19 @@ function isInside(node, ancestor) {
   }
   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));
@@ -991,7 +1072,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;
@@ -1064,6 +1147,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) {
@@ -1272,11 +1366,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
                 );
@@ -1287,8 +1382,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(
@@ -1372,19 +1471,87 @@ function checkSource(source, manifest) {
       if (!present.has(rule.whenPresent)) continue;
       const nodesOf = (target) => targetNodes.get(node)?.get(identifier)?.get(target) ?? [];
       const owners = nodesOf(rule.whenPresent);
-      const satisfied = (target) => rule.requireInside ? nodesOf(target).some((el) => owners.some((owner) => isInside(el, owner))) : present.has(target);
+      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",
-        rule.requireInside ? `"${identifier}" requires ${list(missing)} inside its "${rule.whenPresent}".` : `"${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;
@@ -1687,6 +1854,7 @@ 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;
@@ -1698,6 +1866,7 @@ 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}`);
@@ -1952,6 +2121,8 @@ var CONTROLLER_ARRAY_FIELDS = [
   "events",
   "requiredTargets",
   "conditionalTargets",
+  "requiredActions",
+  "actionCompletion",
   "a11y",
   "keyboard",
   "hosts",
@@ -2014,10 +2185,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}]`;
@@ -2150,13 +2327,14 @@ ${USAGE}`);
   const manifest = load();
   const cwd = process.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;