stimeo-ui 0.15.0 → 0.16.0

package/dist/inspector/cli.d.ts

@@ -38,6 +38,8 @@ interface ControllerManifest {
     readonly valueSyntaxConstraints?: readonly StringSyntaxConstraint[];
     /** Statically decidable relationships between literal Stimulus Values. */
     readonly valueRelations: readonly ValueRelation[];
+    /** What each action reads out of `event.params`. */
+    readonly actionParams: readonly ActionParamRule[];
     /**
      * Public action method names declared via `static actions`, wired by
      * consumers as `data-action="…-><identifier>#<action>"`.
@@ -55,6 +57,11 @@ interface ControllerManifest {
      * {@link ConditionalTargetRule}.
      */
     readonly conditionalTargets: readonly ConditionalTargetRule[];
+    /**
+     * `<template>` targets whose content must be exactly one row. See
+     * {@link TemplateRootRule}.
+     */
+    readonly templateRoots: readonly TemplateRootRule[];
     /**
      * Actions required on a particular element in one Value configuration. See
      * {@link RequiredActionRule}.
@@ -592,6 +599,33 @@ interface ForbiddenAriaRule {
     /** Human-readable fix suggestion shown by the CLI (stage 4). */
     readonly suggestion: string;
 }
+/**
+ * One `event.params` entry an action reads, written as the author writes it.
+ *
+ * Stimulus builds `event.params` from `data-<identifier>-<param>-param` attributes
+ * on the element carrying the `data-action`. Nothing about that spelling is
+ * reflected, so a name that never arrives is indistinguishable at runtime from one
+ * the author never meant to pass: the action runs and returns, and the control is
+ * dead with no diagnostic anywhere.
+ *
+ * `required` is reserved for an action that has **no other way** to reach the value.
+ * Where the reader falls back to `event.detail` or to an attribute, the param is
+ * genuinely optional and a page driving the action that way is correct.
+ */
+interface ActionParamRule {
+    /** The action method the param belongs to; must appear in `actions`. */
+    readonly action: string;
+    /** The param name, camelCase, as `event.params` reads it. */
+    readonly param: string;
+    /** Whether the action can reach the value no other way. */
+    readonly required?: boolean;
+    /** The literal values the reader accepts, when it accepts a fixed set. */
+    readonly allowedValues?: readonly string[];
+    /** Whether the reader takes a whole number and returns on anything else. */
+    readonly integer?: boolean;
+    /** Human-readable fix suggestion shown by the CLI. */
+    readonly suggestion: string;
+}
 /**
  * The bundled manifest. `schemaVersion` tracks the manifest *format*;
  * `packageVersion` tracks the `stimeo-ui` release it was generated from so a
@@ -603,6 +637,24 @@ interface Manifest {
     /** Keyed by controller identifier, e.g. `stimeo--menu`. */
     readonly controllers: Readonly<Record<string, ControllerManifest>>;
 }
+/**
+ * The shape a `<template>` target's content has to have: **exactly one element**,
+ * which is the row the controller clones.
+ *
+ * A row is cloned on its own so that the node appended is the node a later
+ * removal takes back. Content the row does not cover — a second element, a
+ * wrapper around it — is therefore never rendered, and the widget silently adds
+ * nothing. A controller that reports it names it on the console once per
+ * connection; this rule says so before the page is served.
+ */
+interface TemplateRootRule {
+    /** Target name of the `<template>`. */
+    readonly template: string;
+    /** Target name its one element must carry, when the row is a declared part. */
+    readonly rootTarget?: string;
+    /** What to write instead. */
+    readonly suggestion: string;
+}
 /**
  * A target requirement that only exists once another *optional* target is
  * present.
@@ -625,8 +677,8 @@ interface ConditionalTargetRule {
     /** Targets that become required once {@link whenPresent} appears. */
     readonly require: readonly string[];
     /**
-     * Require each {@link require} entry to sit **inside** the `whenPresent`
-     * element rather than anywhere in the scope.
+     * Require each {@link ConditionalTargetRule.require | require} entry to sit
+     * **inside** the `whenPresent` element rather than anywhere in the scope.
      *
      * A `<template>` is cloned at runtime, so a part declared outside it never
      * reaches the clone. Without this the presence check passes on markup the
@@ -634,9 +686,9 @@ interface ConditionalTargetRule {
      */
     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.
+     * Require each {@link ConditionalTargetRule.require | 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
@@ -650,6 +702,20 @@ interface ConditionalTargetRule {
      * generated — reporting either would be a guess, and the check stays quiet.
      */
     readonly requireSameHost?: readonly HostSelector[];
+    /**
+     * Require each {@link ConditionalTargetRule.require | require} entry to sit
+     * inside the same element carrying this controller's target of this name as the
+     * {@link whenPresent} entry does.
+     *
+     * Where {@link requireSameHost} describes the host by tag, this names it: the host
+     * is a declared target of the same controller, so a pair resolved per trigger can
+     * say so directly. Halves split across two of those hosts leave both incomplete,
+     * and neither swaps.
+     *
+     * A scope whose hosts are all generated leaves the question undecidable, so nothing
+     * is reported there.
+     */
+    readonly requireSameTargetHost?: string;
     /**
      * 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
@@ -806,7 +872,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-required-action", "missing-action-completion", "missing-action-event", "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"];
+declare const DIAGNOSTIC_CODES: readonly ["unknown-controller", "unknown-target", "unknown-value", "invalid-value", "unknown-action-controller", "unknown-action-method", "unknown-action-event", "orphan-target", "missing-required-target", "missing-conditional-target", "invalid-template-root", "missing-required-action", "missing-action-completion", "missing-action-event", "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", "missing-action-param", "invalid-action-param", "confusable-action-param", "unknown-ignore-code"];
 /** See {@link DIAGNOSTIC_CODES}. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 /**

package/dist/inspector/cli.js

@@ -980,12 +980,24 @@ var NAMESPACE_PREFIX = "stimeo--";
 function dasherize(value) {
   return value.replace(/([A-Z])/g, (_match, char) => `-${char.toLowerCase()}`);
 }
-function controllerIdentifiers(dataControllerValue) {
+function attributeTokens(value) {
+  const tokens = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const token of dataControllerValue.split(/\s+/)) {
-    if (token.startsWith(NAMESPACE_PREFIX)) seen.add(token);
+  const pattern = /\S+/g;
+  for (let match = pattern.exec(value); match; match = pattern.exec(value)) {
+    if (seen.has(match[0])) continue;
+    seen.add(match[0]);
+    tokens.push({ name: match[0], start: match.index });
   }
-  return [...seen];
+  return tokens;
+}
+function controllerIdentifiers(dataControllerValue) {
+  return controllerIdentifierTokens(dataControllerValue).map((token) => token.name);
+}
+function controllerIdentifierTokens(dataControllerValue) {
+  return attributeTokens(dataControllerValue).filter(
+    (token) => token.name.startsWith(NAMESPACE_PREFIX)
+  );
 }
 function parseTargetAttr(attrName) {
   const match = /^data-(stimeo--[a-z0-9][a-z0-9-]*)-target$/.exec(attrName);
@@ -1027,7 +1039,7 @@ function defaultEventFor(host) {
 }
 function actionDescriptors(dataActionValue, host) {
   const descriptors = [];
-  for (const descriptor of dataActionValue.split(/\s+/)) {
+  for (const { name: descriptor, start } of attributeTokens(dataActionValue)) {
     const hash = descriptor.indexOf("#");
     if (hash === -1) continue;
     let lhs = descriptor.slice(0, hash);
@@ -1043,7 +1055,14 @@ function actionDescriptors(dataActionValue, host) {
     }
     if (!lhs.startsWith(NAMESPACE_PREFIX)) continue;
     const method = /^[a-zA-Z_$][\w$]*/.exec(descriptor.slice(hash + 1))?.[0] ?? "";
-    descriptors.push({ identifier: lhs, method, eventType });
+    descriptors.push({
+      identifier: lhs,
+      identifierStart: start + (arrow === -1 ? 0 : arrow + 2),
+      method,
+      methodStart: start + hash + 1,
+      eventType,
+      eventStart: start
+    });
   }
   return descriptors;
 }
@@ -1059,9 +1078,11 @@ var DIAGNOSTIC_CODES = [
   "invalid-value",
   "unknown-action-controller",
   "unknown-action-method",
+  "unknown-action-event",
   "orphan-target",
   "missing-required-target",
   "missing-conditional-target",
+  "invalid-template-root",
   "missing-required-action",
   "missing-action-completion",
   "missing-action-event",
@@ -1077,11 +1098,14 @@ var DIAGNOSTIC_CODES = [
   "cardinality-violation",
   "forbidden-aria",
   "missing-announcer",
+  "missing-action-param",
+  "invalid-action-param",
+  "confusable-action-param",
   "unknown-ignore-code"
 ];
 
 // src/inspector/check.ts
-function isInside(node, ancestor) {
+function isDescendantOf(node, ancestor) {
   for (let current = node.parent; current; current = current.parent) {
     if (current === ancestor) return true;
   }
@@ -1174,11 +1198,13 @@ function checkSource(source, manifest) {
   const unnamedTargets = [];
   const targetsUnreadable = (container, scope, identifier) => {
     for (const node of unresolved) {
-      if (isWithin(node, container) && findOwner(node, identifier) === scope) return true;
+      if (isSelfOrDescendantOf(node, container) && findOwner(node, identifier) === scope)
+        return true;
     }
     for (const { node, identifier: hidden } of unnamedTargets) {
       if (hidden !== identifier) continue;
-      if (isWithin(node, container) && findOwner(node, identifier) === scope) return true;
+      if (isSelfOrDescendantOf(node, container) && findOwner(node, identifier) === scope)
+        return true;
     }
     return false;
   };
@@ -1237,7 +1263,7 @@ function checkSource(source, manifest) {
     const nodes = targetNodes.get(scope)?.get(identifier)?.get(condition.target) ?? [];
     const container = condition.within === "scope" ? scope : element;
     let held = 0;
-    for (const node of nodes) if (isWithin(node, container)) held += 1;
+    for (const node of nodes) if (isSelfOrDescendantOf(node, container)) held += 1;
     if (condition.min !== void 0 && held < condition.min) return false;
     if (condition.max !== void 0 && held > condition.max) return false;
     return true;
@@ -1274,9 +1300,9 @@ function checkSource(source, manifest) {
     const authoredValueIdentifiers = /* @__PURE__ */ new Set();
     for (const attr of node.attrs) {
       if (attr.name === IGNORE_ATTR) {
-        for (const token of attr.value.split(/\s+/).filter((t) => t.length > 0)) {
-          if (!DIAGNOSTIC_CODES.includes(token)) {
-            const best = nearestName(token, DIAGNOSTIC_CODES);
+        for (const token of attributeTokens(attr.value)) {
+          if (!DIAGNOSTIC_CODES.includes(token.name)) {
+            const best = nearestName(token.name, DIAGNOSTIC_CODES);
             push(
               diagnostics,
               "unknown-ignore-code",
@@ -1291,7 +1317,7 @@ function checkSource(source, manifest) {
         continue;
       }
       if (attr.name === FRAGMENT_ATTR) {
-        const identifiers = attr.value.split(/\s+/).filter((token) => token.length > 0);
+        const identifiers = attributeTokens(attr.value);
         if (identifiers.length === 0) {
           report(
             node,
@@ -1302,13 +1328,13 @@ function checkSource(source, manifest) {
           );
         }
         for (const identifier of identifiers) {
-          if (!(identifier in known)) {
-            const best = nearestName(identifier, knownIdentifiers);
+          if (!(identifier.name in known)) {
+            const best = nearestName(identifier.name, knownIdentifiers);
             report(
               node,
               "unknown-controller",
               "error",
-              `Fragment declaration references unknown Stimeo controller "${identifier}".`,
+              `Fragment declaration references unknown Stimeo controller "${identifier.name}".`,
               attr,
               asDidYouMean(best),
               tokenFix(attr, identifier, best)
@@ -1318,7 +1344,8 @@ function checkSource(source, manifest) {
         continue;
       }
       if (attr.name === "data-controller") {
-        for (const identifier of controllerIdentifiers(attr.value)) {
+        for (const token of controllerIdentifierTokens(attr.value)) {
+          const identifier = token.name;
           if (identifier in known) {
             scopes.push({ node, identifier });
           } else {
@@ -1330,7 +1357,7 @@ function checkSource(source, manifest) {
               `Unknown Stimeo controller "${identifier}".`,
               attr,
               asDidYouMean(best),
-              tokenFix(attr, identifier, best)
+              tokenFix(attr, token, best)
             );
           }
         }
@@ -1350,24 +1377,27 @@ function checkSource(source, manifest) {
           );
           continue;
         }
-        const targetName = isDynamicValue(attr) ? "" : attr.value.trim();
-        if (targetName.length > 0 && !controller.targets.includes(targetName)) {
-          const best = nearestName(targetName, controller.targets);
+        const declared = isDynamicValue(attr) ? [] : attributeTokens(attr.value);
+        for (const token of declared) {
+          if (controller.targets.includes(token.name)) continue;
+          const best = nearestName(token.name, controller.targets);
           report(
             node,
             "unknown-target",
             "error",
-            `Unknown target "${targetName}" for "${targetIdentifier}". Known targets: ${list(controller.targets)}.`,
+            `Unknown target "${token.name}" for "${targetIdentifier}". Known targets: ${list(controller.targets)}.`,
             attr,
             asDidYouMean(best),
-            tokenFix(attr, targetName, best)
+            tokenFix(attr, token, best)
           );
         }
         const owner = findOwner(node, targetIdentifier);
         if (owner) {
-          if (targetName.length > 0) {
-            recordPresence(owner, targetIdentifier, targetName);
-            recordTargetNode(owner, targetIdentifier, targetName, node);
+          if (declared.length > 0) {
+            for (const token of declared) {
+              recordPresence(owner, targetIdentifier, token.name);
+              recordTargetNode(owner, targetIdentifier, token.name, node);
+            }
           } else if (isDynamicValue(attr)) {
             unnamedTargets.push({ node, identifier: targetIdentifier });
           }
@@ -1431,7 +1461,15 @@ function checkSource(source, manifest) {
           tag: node.tag,
           inputType: node.attrs.find((a) => a.name === "type")?.value
         };
-        for (const { identifier, method, eventType } of actionDescriptors(attr.value, host)) {
+        const paramsChecked = /* @__PURE__ */ new Set();
+        for (const {
+          identifier,
+          identifierStart,
+          method,
+          methodStart,
+          eventType,
+          eventStart
+        } of actionDescriptors(attr.value, host)) {
           const controller = known[identifier];
           if (controller && method.length > 0) {
             const owner = findOwner(node, identifier);
@@ -1456,7 +1494,7 @@ function checkSource(source, manifest) {
               `Action references unknown Stimeo controller "${identifier}".`,
               attr,
               asDidYouMean(best),
-              tokenFix(attr, identifier, best)
+              tokenFix(attr, { name: identifier, start: identifierStart }, best)
             );
           } else if (method.length > 0 && !controller.actions.includes(method)) {
             const best = nearestName(method, controller.actions);
@@ -1467,12 +1505,124 @@ function checkSource(source, manifest) {
               `Unknown action "${method}" for "${identifier}". Known actions: ${list(controller.actions)}.`,
               attr,
               asDidYouMean(best),
-              tokenFix(attr, method, best)
+              tokenFix(attr, { name: method, start: methodStart }, best)
             );
           }
+          if (controller && method.length > 0 && !paramsChecked.has(`${identifier}#${method}`)) {
+            paramsChecked.add(`${identifier}#${method}`);
+            checkActionParams(node, attr, identifier, method, controller);
+          }
+          if (!isDynamicValue(attr)) {
+            const emitted = /^(stimeo--[a-z0-9-]+):(.+)$/.exec(eventType);
+            const source2 = emitted ? known[emitted[1]] : void 0;
+            const name = emitted?.[2];
+            if (source2 && name !== void 0 && !source2.events.includes(name)) {
+              const best = nearestName(name, source2.events);
+              report(
+                node,
+                "unknown-action-event",
+                "error",
+                `Unknown event "${name}" for "${emitted?.[1]}". Known events: ${list(source2.events)}.`,
+                attr,
+                asDidYouMean(best),
+                tokenFix(attr, { name, start: eventStart + eventType.length - name.length }, best)
+              );
+            }
+          }
         }
       }
     }
+    function checkActionParams(element, action, identifier, method, controller) {
+      const rules = controller.actionParams.filter((rule) => rule.action === method);
+      if (rules.length === 0) return;
+      const readable = !isDynamicValue(action) && element.origin === "markup" && !element.opaque;
+      const expected = new Map(
+        rules.map((rule) => [`data-${identifier}-${dasherize(rule.param)}-param`, rule])
+      );
+      for (const [attrName, rule] of expected) {
+        const written = element.attrs.find((candidate) => candidate.name === attrName);
+        if (!written) {
+          if (!rule.required || !readable) continue;
+          const confusable = confusableParamAttr(element, attrName, rule.param);
+          report(
+            element,
+            "missing-action-param",
+            "error",
+            confusable ? `"${identifier}#${method}" reads its "${rule.param}" param, and "${confusable.name}" is not the attribute Stimulus builds it from.` : `"${identifier}#${method}" reads its "${rule.param}" param, which nothing on this element supplies.`,
+            confusable ?? action,
+            rule.suggestion
+          );
+          continue;
+        }
+        if (isDynamicValue(written)) continue;
+        const value = written.value;
+        if (value.length === 0) {
+          if (!rule.required || !readable) continue;
+          report(
+            element,
+            "missing-action-param",
+            "error",
+            `"${identifier}#${method}" reads its "${rule.param}" param, and "${attrName}" carries no value.`,
+            written,
+            rule.suggestion
+          );
+          continue;
+        }
+        if (rule.integer && !Number.isInteger(Number(value))) {
+          report(
+            element,
+            "invalid-action-param",
+            "error",
+            `"${value}" is not an "${rule.param}" this action reads. It accepts a whole number.`,
+            written,
+            rule.suggestion
+          );
+          continue;
+        }
+        if (!rule.allowedValues || rule.allowedValues.includes(value)) continue;
+        const best = nearestName(value, rule.allowedValues);
+        report(
+          element,
+          "invalid-action-param",
+          "error",
+          `"${value}" is not a "${rule.param}" this action reads. It accepts ${list(rule.allowedValues)}.`,
+          written,
+          asDidYouMean(best) ?? rule.suggestion,
+          best !== void 0 && written.valueStart !== void 0 ? {
+            start: written.valueStart,
+            end: written.valueStart + written.value.length,
+            text: best,
+            title: `Replace with "${best}"`
+          } : void 0
+        );
+      }
+      if (!readable) return;
+      for (const candidate of element.attrs) {
+        if (!candidate.name.startsWith(`data-${identifier}-`)) continue;
+        if (expected.has(candidate.name)) continue;
+        if (parseTargetAttr(candidate.name) || candidate.name.endsWith("-value")) continue;
+        const best = [...expected.keys()].find((name) => namesTheParam(candidate.name, name));
+        if (best === void 0) continue;
+        report(
+          element,
+          "confusable-action-param",
+          "warning",
+          `"${candidate.name}" is not an attribute Stimulus reads. Action params are named "<param>-param".`,
+          candidate,
+          `Did you mean ${best}?`
+        );
+      }
+    }
+    function namesTheParam(written, attrName) {
+      if (written === attrName) return false;
+      return `${written}-param` === attrName || nearestName(written, [attrName]) !== void 0;
+    }
+    function confusableParamAttr(element, attrName, param) {
+      const bare = `data-${dasherize(param)}`;
+      return element.attrs.find(
+        (candidate) => candidate.name === bare || namesTheParam(candidate.name, attrName)
+      );
+    }
     for (const identifier of authoredValueIdentifiers) {
       const controller = known[identifier];
       if (!controller) continue;
@@ -1532,19 +1682,30 @@ function checkSource(source, manifest) {
       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 hostOf = (el) => nearestHost(el, selectors);
+        const ownerHosts = owners.map(hostOf).filter((host) => host !== null && host !== void 0);
         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;
-        });
+        return ownerHosts.every(
+          (ownerHost) => candidates.some((el) => {
+            const host = hostOf(el);
+            if (host === null) return false;
+            return host ? host === ownerHost : true;
+          })
+        );
+      };
+      const sharesTargetHost = (target, hostTarget) => {
+        const hostNodes = nodesOf(hostTarget);
+        const hostOf = (el) => hostNodes.find((host) => isDescendantOf(el, host)) ?? null;
+        const ownerHosts = owners.map(hostOf).filter((host) => host !== null);
+        const candidates = nodesOf(target);
+        return ownerHosts.every((ownerHost) => candidates.some((el) => hostOf(el) === ownerHost));
       };
       const satisfied = (target) => {
+        const hostTarget = rule.requireSameTargetHost;
+        if (hostTarget) return sharesTargetHost(target, hostTarget);
         if (hosts) return sharesHost(target, hosts);
         if (rule.requireInside)
-          return nodesOf(target).some((el) => owners.some((owner) => isInside(el, owner)));
+          return nodesOf(target).some((el) => owners.some((owner) => isDescendantOf(el, owner)));
         return present.has(target);
       };
       const missing = rule.require.filter((target) => !satisfied(target));
@@ -1553,12 +1714,62 @@ function checkSource(source, manifest) {
         node,
         "missing-conditional-target",
         complete ? "error" : "warning",
-        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)}.`,
+        rule.requireSameTargetHost ? `"${identifier}" requires ${list(missing)} in the same "${rule.requireSameTargetHost}" as its "${rule.whenPresent}".` : 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 complete = scopeIsComplete(node, node, identifier);
+    const nodesOf = (target) => targetNodes.get(node)?.get(identifier)?.get(target) ?? [];
+    const hint = complete ? void 0 : UNRESOLVED_TARGET_HINT;
+    for (const rule of controller.templateRoots) {
+      for (const template of nodesOf(rule.template)) {
+        if (template.origin === "markup" && template.tag !== "template") {
+          report(
+            node,
+            "invalid-template-root",
+            complete ? "error" : "warning",
+            `"${identifier}" requires its "${rule.template}" to be a <template>, and it is a <${template.tag}>.`,
+            template,
+            hint ?? rule.suggestion
+          );
+          continue;
+        }
+        if (template.children.some((child) => child.origin === "erb")) continue;
+        const rows = template.children;
+        const row = rows[0];
+        if (rows.length === 0) continue;
+        if (rows.length !== 1 || !row) {
+          report(
+            node,
+            "invalid-template-root",
+            complete ? "error" : "warning",
+            `"${identifier}" requires its "${rule.template}" to hold exactly one element, and it holds ${rows.length}.`,
+            template,
+            hint ?? rule.suggestion
+          );
+          continue;
+        }
+        if (!rule.rootTarget) continue;
+        if (unnamedTargets.some((entry) => entry.node === row && entry.identifier === identifier)) {
+          continue;
+        }
+        if (nodesOf(rule.rootTarget).includes(row)) continue;
+        report(
+          node,
+          "invalid-template-root",
+          complete ? "error" : "warning",
+          `"${identifier}" requires the one element in its "${rule.template}" to be its "${rule.rootTarget}" itself.`,
+          row,
+          hint ?? rule.suggestion
+        );
+      }
+    }
+  }
   for (const { node, identifier } of scopes) {
     const controller = known[identifier];
     if (!controller) continue;
@@ -1809,7 +2020,7 @@ function checkSource(source, manifest) {
         if (rule.values && !rule.values.includes(value)) continue;
         if (findOwner(el, identifier) !== node) continue;
         const declaredAs = el.attrs.find((a) => a.name === targetAttrName);
-        if (declaredAs && !isDynamicValue(declaredAs) && declaredAs.value.trim() === rule.target) {
+        if (declaredAs && !isDynamicValue(declaredAs) && attributeTokens(declaredAs.value).some((token) => token.name === rule.target)) {
           continue;
         }
         if (declaredAs && isDynamicValue(declaredAs)) continue;
@@ -1837,7 +2048,7 @@ function checkSource(source, manifest) {
       for (const container of containers) {
         const matched = [];
         for (const el of counted) {
-          if (!isWithin(el, container)) continue;
+          if (!isSelfOrDescendantOf(el, container)) continue;
           if (rule.attr === void 0) {
             matched.push({ el, at: el });
             continue;
@@ -1893,14 +2104,14 @@ function checkSource(source, manifest) {
   for (const el of anchored) {
     for (const attr of el.attrs) {
       if (!IDREF_ATTRS.has(attr.name) || isDynamicValue(attr)) continue;
-      for (const token of attr.value.split(/\s+/).filter((t) => t.length > 0)) {
-        if (!ids.has(token)) {
-          const best = nearestName(token, [...ids]);
+      for (const token of attributeTokens(attr.value)) {
+        if (!ids.has(token.name)) {
+          const best = nearestName(token.name, [...ids]);
           report(
             el,
             "unresolved-idref",
             "warning",
-            `${attr.name} references id "${token}", but no element in this file declares it.`,
+            `${attr.name} references id "${token.name}", but no element in this file declares it.`,
             attr,
             asDidYouMean(best),
             tokenFix(attr, token, best)
@@ -2016,7 +2227,7 @@ function checkA11y(report, el, identifier, req, severity, isDynamicValue) {
     );
   }
 }
-function isWithin(node, container) {
+function isSelfOrDescendantOf(node, container) {
   let current = node;
   while (current) {
     if (current === container) return true;
@@ -2121,15 +2332,13 @@ function push(out, code, severity, message, at, suggestion, fix) {
   });
 }
 function tokenFix(attr, token, replacement) {
-  if (replacement === void 0 || attr.valueStart === void 0 || token.length === 0) {
+  if (replacement === void 0 || attr.valueStart === void 0 || token.name.length === 0) {
     return void 0;
   }
-  const index = attr.value.indexOf(token);
-  if (index < 0) return void 0;
-  const start = attr.valueStart + index;
+  const start = attr.valueStart + token.start;
   return {
     start,
-    end: start + token.length,
+    end: start + token.name.length,
     text: replacement,
     title: `Replace with "${replacement}"`
   };
@@ -2196,10 +2405,12 @@ var CONTROLLER_ARRAY_FIELDS = [
   "values",
   "valueConstraints",
   "valueRelations",
+  "actionParams",
   "actions",
   "events",
   "requiredTargets",
   "conditionalTargets",
+  "templateRoots",
   "requiredActions",
   "actionCompletion",
   "a11y",