stimeo-ui 0.4.0 → 0.6.0

package/dist/inspector/cli.d.ts

@@ -23,6 +23,14 @@ interface ControllerManifest {
     readonly targets: readonly string[];
     /** Value names (camelCase) declared via `static values`. */
     readonly values: readonly string[];
+    /**
+     * Authoring constraints for literal Stimulus Values (stage 1). Reflection can
+     * expose a Value's name and decoder, but not semantic bounds such as a
+     * strictly positive step, so those contracts stay explicit and reviewable.
+     */
+    readonly valueConstraints: readonly ValueConstraint[];
+    /** Statically decidable relationships between literal Stimulus Values. */
+    readonly valueRelations: readonly ValueRelation[];
     /**
      * Public action method names declared via `static actions`, wired by
      * consumers as `data-action="…-><identifier>#<action>"`.
@@ -57,6 +65,13 @@ interface ControllerManifest {
      * toolbar, radio group, …) are deliberately excluded.
      */
     readonly keyboard: readonly KeyboardRequirement[];
+    /**
+     * Host-element contracts (stage 3): scope or target elements that must avoid
+     * native interactive semantics the controller cannot safely compose with.
+     * A rule may explicitly admit non-submitting buttons when the controller
+     * delegates their native activation to the browser.
+     */
+    readonly hosts: readonly HostRequirement[];
     /**
      * Author-futile attributes (stage 3): ARIA the controller recomputes
      * wholesale at runtime, where an authored value can neither
@@ -212,9 +227,11 @@ interface DocumentCondition {
  * A single accessibility requirement on a controller's markup (Inspector
  * stage 3). At least one of {@link attrs} must be present on the
  * {@link target} element; when {@link values} is given, the present
- * attribute's value must be one of them. {@link or} widens the requirement
- * with alternative attribute/value groups — the requirement is satisfied when
- * *any* group is (e.g. `role="status"` **or** `aria-live`).
+ * attribute's value must be one of them, and when it is not, the value must be
+ * non-empty — ARIA derives no name from `aria-label=""`, so an empty value
+ * leaves the requirement unmet. {@link or} widens the requirement with
+ * alternative attribute/value groups — the requirement is satisfied when *any*
+ * group is (e.g. `role="status"` **or** `aria-live`).
  */
 interface A11yRequirement {
     /**
@@ -328,6 +345,27 @@ interface KeyboardRequirement {
     /** Human-readable fix suggestion shown by the CLI (stage 4). */
     readonly suggestion: string;
 }
+/**
+ * A host-element contract (stage 3): the element carrying a controller or one
+ * of its targets must use semantics the controller can own without competing
+ * with another native interaction.
+ *
+ * `"non-interactive"` admits only generic, non-interactive elements.
+ * `"non-interactive-or-button"` additionally admits a `<button>` whose
+ * literal `type` is listed in {@link buttonTypes}. The explicit type matters:
+ * a missing or invalid button type defaults to `submit`, so treating it as an
+ * ordinary action button would silently submit an enclosing form.
+ */
+interface HostRequirement {
+    /** Target name; the empty string `""` means the controller scope element. */
+    readonly target: string;
+    /** Static host shapes the controller supports. */
+    readonly mode: "non-interactive" | "non-interactive-or-button";
+    /** Literal button types admitted by `"non-interactive-or-button"`. */
+    readonly buttonTypes?: readonly string[];
+    /** Human-readable fix suggestion shown by the CLI (stage 4). */
+    readonly suggestion: string;
+}
 /**
  * An author-futile attribute rule (stage 3): authoring any of {@link attrs} on
  * the {@link target} element draws a `managed-aria` **warning** — the
@@ -561,6 +599,56 @@ interface ConditionalTargetRule {
     readonly whenPresent: string;
     /** 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.
+     *
+     * 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
+     * controller then refuses to build from.
+     */
+    readonly requireInside?: boolean;
+    /** Human-readable fix suggestion shown by the CLI (stage 4). */
+    readonly suggestion: string;
+}
+/**
+ * A statically checkable numeric contract on one declared Stimulus Value.
+ *
+ * The Inspector decodes literals like Stimulus (`Number(raw.replace(/_/g,
+ * ""))`) before applying these bounds. ERB-generated values are undecidable and
+ * skipped rather than guessed.
+ */
+interface ValueConstraint {
+    /** Value name (camelCase, as declared in `static values`). */
+    readonly value: string;
+    /** Decoder family. Numeric bounds are the first supported semantic family. */
+    readonly type: "number";
+    /** Reject `NaN` and infinities when true. */
+    readonly finite?: boolean;
+    /** Require a decoded number strictly greater than this bound. */
+    readonly greaterThan?: number;
+    /** Require a decoded number with no fractional part. */
+    readonly integer?: boolean;
+    /** Human-readable fix suggestion shown by the CLI (stage 4). */
+    readonly suggestion: string;
+}
+/**
+ * A statically checkable relationship between two numeric Stimulus Values.
+ *
+ * Missing attributes use the controller's public defaults. If either authored
+ * value is dynamic, the Inspector skips the relation rather than guessing.
+ */
+interface ValueRelation {
+    /** Value on the left side of the comparison (camelCase). */
+    readonly left: string;
+    /** Supported numeric comparison. */
+    readonly operator: "less-than-or-equal";
+    /** Value on the right side of the comparison (camelCase). */
+    readonly right: string;
+    /** Effective left value when its attribute is absent. */
+    readonly leftDefault: number;
+    /** Effective right value when its attribute is absent. */
+    readonly rightDefault: number;
     /** Human-readable fix suggestion shown by the CLI (stage 4). */
     readonly suggestion: string;
 }
@@ -571,7 +659,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", "unknown-action-controller", "unknown-action-method", "orphan-target", "missing-required-target", "missing-conditional-target", "missing-aria", "invalid-aria-value", "keyboard-inaccessible", "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-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"];
 /** See {@link DIAGNOSTIC_CODES}. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 /**

package/dist/inspector/cli.js

@@ -610,6 +610,26 @@ function readEntry(code, start, base) {
       };
     }
   }
+  const number = /^[+-]?\d(?:_?\d)*(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?/.exec(
+    code.slice(valueStart)
+  )?.[0];
+  if (number !== void 0) {
+    const end = valueStart + number.length;
+    const after = skipTrivia(code, end);
+    const whole = after >= code.length || code[after] === "," || code[after] === "}";
+    if (whole) {
+      return {
+        attr: {
+          name,
+          value: number,
+          ...anchor,
+          valueStart: base + valueStart,
+          valueEnd: base + end
+        },
+        end
+      };
+    }
+  }
   return { attr: { name, value: null, ...anchor }, end: skipValue(code, valueStart) };
 }
 function readKey(code, start) {
@@ -926,6 +946,7 @@ var DIAGNOSTIC_CODES = [
   "unknown-controller",
   "unknown-target",
   "unknown-value",
+  "invalid-value",
   "unknown-action-controller",
   "unknown-action-method",
   "orphan-target",
@@ -934,6 +955,7 @@ var DIAGNOSTIC_CODES = [
   "missing-aria",
   "invalid-aria-value",
   "keyboard-inaccessible",
+  "invalid-host",
   "unresolved-idref",
   "managed-aria",
   "composition-mismatch",
@@ -945,6 +967,12 @@ var DIAGNOSTIC_CODES = [
 ];
 
 // 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 checkSource(source, manifest) {
   const diagnostics = [];
   const tree = parseHtml(neutralizeErb(source), erbElements(source));
@@ -965,6 +993,36 @@ function checkSource(source, manifest) {
     if (hostAttr && isDynamicValue(hostAttr)) return null;
     return when.equals.includes(hostAttr ? hostAttr.value.trim() : when.default);
   };
+  const isContentEditable2 = (element) => {
+    let current = element;
+    while (current && current.tag !== "#root") {
+      const attr = current.attrs.find((candidate) => candidate.name === "contenteditable");
+      if (attr) {
+        if (isDynamicValue(attr)) return null;
+        const value = attr.value.trim().toLowerCase();
+        if (value === "false") return false;
+        if (value === "" || value === "true" || value === "plaintext-only") return true;
+      }
+      current = current.parent;
+    }
+    return false;
+  };
+  const hostIsAllowed = (element, rule) => {
+    if (element.tag === "button") {
+      if (rule.mode === "non-interactive") return false;
+      const type = element.attrs.find((attr) => attr.name === "type");
+      if (type && isDynamicValue(type)) return null;
+      const effectiveType = type?.value.trim().toLowerCase() || "submit";
+      return (rule.buttonTypes ?? []).includes(effectiveType);
+    }
+    if (ALWAYS_INTERACTIVE_HOSTS.has(element.tag)) return false;
+    if ((element.tag === "a" || element.tag === "area") && hasAttr(element, "href")) return false;
+    if ((element.tag === "audio" || element.tag === "video") && hasAttr(element, "controls")) {
+      return false;
+    }
+    const editable = isContentEditable2(element);
+    return editable === null ? null : !editable;
+  };
   const suppressed = (node, code) => {
     if (code === "unknown-ignore-code") return false;
     let current = node;
@@ -1072,6 +1130,7 @@ function checkSource(source, manifest) {
         focusableRoleTally.set(role, (focusableRoleTally.get(role) ?? 0) + 1);
       }
     }
+    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)) {
@@ -1196,6 +1255,7 @@ function checkSource(source, manifest) {
               attr
             );
           } else {
+            authoredValueIdentifiers.add(parsed.identifier);
             const controller = known[parsed.identifier];
             const valid = controller?.values.some((v) => dasherize(v) === parsed.valueToken) ?? false;
             if (!valid) {
@@ -1207,6 +1267,20 @@ function checkSource(source, manifest) {
                 attr,
                 didYouMean(parsed.valueToken, (controller?.values ?? []).map(dasherize))
               );
+            } else if (!isDynamicValue(attr)) {
+              const constraint = controller?.valueConstraints.find(
+                (candidate) => dasherize(candidate.value) === parsed.valueToken
+              );
+              if (constraint && !valueSatisfiesConstraint(attr.value, constraint)) {
+                report(
+                  node,
+                  "invalid-value",
+                  "error",
+                  `Invalid value "${attr.value.trim()}" for "${parsed.identifier}.${parsed.valueToken}". Expected ${describeValueConstraint(constraint)}.`,
+                  attr,
+                  constraint.suggestion
+                );
+              }
             }
           }
           continue;
@@ -1241,6 +1315,34 @@ function checkSource(source, manifest) {
         }
       }
     }
+    for (const identifier of authoredValueIdentifiers) {
+      const controller = known[identifier];
+      if (!controller) continue;
+      for (const relation of controller.valueRelations) {
+        const leftAttr = node.attrs.find(
+          (attr) => attr.name === `data-${identifier}-${dasherize(relation.left)}-value`
+        );
+        const rightAttr = node.attrs.find(
+          (attr) => attr.name === `data-${identifier}-${dasherize(relation.right)}-value`
+        );
+        const at = rightAttr ?? leftAttr;
+        if (!at || leftAttr && isDynamicValue(leftAttr) || rightAttr && isDynamicValue(rightAttr)) {
+          continue;
+        }
+        const left = leftAttr ? decodeNumericValue(leftAttr.value) : relation.leftDefault;
+        const right = rightAttr ? decodeNumericValue(rightAttr.value) : relation.rightDefault;
+        if (!Number.isFinite(left) || !Number.isFinite(right)) continue;
+        if (relation.operator === "less-than-or-equal" && left <= right) continue;
+        report(
+          node,
+          "invalid-value",
+          "error",
+          `Invalid values for "${identifier}": "${relation.left}" (${left}) must be less than or equal to "${relation.right}" (${right}).`,
+          at,
+          relation.suggestion
+        );
+      }
+    }
   });
   const scopeIsComplete = (container, scope, identifier) => container.origin === "markup" && !targetsUnreadable(container, scope, identifier);
   for (const { node, identifier } of scopes) {
@@ -1268,13 +1370,16 @@ 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 satisfied = (target) => rule.requireInside ? nodesOf(target).some((el) => owners.some((owner) => isInside(el, owner))) : 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)}.`,
+        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
       );
@@ -1292,7 +1397,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);
       }
     }
   }
@@ -1318,6 +1423,28 @@ function checkSource(source, manifest) {
       }
     }
   }
+  for (const { node, identifier } of scopes) {
+    const controller = known[identifier];
+    if (!controller) continue;
+    for (const rule of controller.hosts) {
+      const elements = rule.target === "" ? [node] : targetNodes.get(node)?.get(identifier)?.get(rule.target) ?? [];
+      const where = rule.target === "" ? "scope element" : `"${rule.target}" target`;
+      for (const element of elements) {
+        if (!hasReadableMarkup(element)) continue;
+        if (hostIsAllowed(element, rule) !== false) continue;
+        const type = element.attrs.find((attr) => attr.name === "type");
+        const detail = element.tag === "button" ? `the unsupported ${type ? `type="${type.value}"` : 'implicit type="submit"'}` : `an unsupported interactive <${element.tag}>`;
+        report(
+          element,
+          "invalid-host",
+          "error",
+          `The ${where} of "${identifier}" uses ${detail} host.`,
+          type ?? element,
+          rule.suggestion
+        );
+      }
+    }
+  }
   for (const { node, identifier } of scopes) {
     const controller = known[identifier];
     if (!controller) continue;
@@ -1559,12 +1686,31 @@ function checkSource(source, manifest) {
   diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
   return diagnostics;
 }
+function valueSatisfiesConstraint(raw, constraint) {
+  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) {
+  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.";
 var UNRESOLVED_HOST_HINT = "An enclosing helper's data: option is not a literal hash, so the host controller may be declared at runtime.";
 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 ?? []
@@ -1584,9 +1730,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] });
@@ -1598,8 +1749,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;
@@ -1631,6 +1782,20 @@ function describeCounted(target, attr, values) {
   return `"${target}" targets with ${attr}${constrained}`;
 }
 var NATIVE_FOCUSABLE_TAGS = /* @__PURE__ */ new Set(["button", "select", "textarea", "summary"]);
+var ALWAYS_INTERACTIVE_HOSTS = /* @__PURE__ */ new Set([
+  "input",
+  "select",
+  "textarea",
+  "label",
+  "summary",
+  "details",
+  "iframe",
+  "object",
+  "embed"
+]);
+function hasAttr(element, name) {
+  return element.attrs.some((attr) => attr.name === name);
+}
 function isNativelyFocusable(el) {
   if (NATIVE_FOCUSABLE_TAGS.has(el.tag)) return true;
   if (el.tag === "input") {
@@ -1781,12 +1946,15 @@ function isCheckableFile(path) {
 var CONTROLLER_ARRAY_FIELDS = [
   "targets",
   "values",
+  "valueConstraints",
+  "valueRelations",
   "actions",
   "events",
   "requiredTargets",
   "conditionalTargets",
   "a11y",
   "keyboard",
+  "hosts",
   "managedAria",
   "compositions",
   "companions",