stimeo-ui 0.4.0 → 0.6.0

package/dist/inspector/cli_bin.js

@@ -612,6 +612,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) {
@@ -928,6 +948,7 @@ var DIAGNOSTIC_CODES = [
   "unknown-controller",
   "unknown-target",
   "unknown-value",
+  "invalid-value",
   "unknown-action-controller",
   "unknown-action-method",
   "orphan-target",
@@ -936,6 +957,7 @@ var DIAGNOSTIC_CODES = [
   "missing-aria",
   "invalid-aria-value",
   "keyboard-inaccessible",
+  "invalid-host",
   "unresolved-idref",
   "managed-aria",
   "composition-mismatch",
@@ -947,6 +969,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));
@@ -967,6 +995,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;
@@ -1074,6 +1132,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)) {
@@ -1198,6 +1257,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) {
@@ -1209,6 +1269,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;
@@ -1243,6 +1317,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) {
@@ -1270,13 +1372,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
       );
@@ -1294,7 +1399,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);
       }
     }
   }
@@ -1320,6 +1425,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;
@@ -1561,12 +1688,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 ?? []
@@ -1586,9 +1732,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] });
@@ -1600,8 +1751,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;
@@ -1633,6 +1784,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") {
@@ -1783,12 +1948,15 @@ function isCheckableFile(path) {
 var CONTROLLER_ARRAY_FIELDS = [
   "targets",
   "values",
+  "valueConstraints",
+  "valueRelations",
   "actions",
   "events",
   "requiredTargets",
   "conditionalTargets",
   "a11y",
   "keyboard",
+  "hosts",
   "managedAria",
   "compositions",
   "companions",
@@ -2261,6 +2429,37 @@ var CONTROLLER_CONTRACT_SCHEMA = {
     id: { type: "string", description: 'Controller identifier, e.g. "stimeo--tabs".' },
     targets: STRING_ARRAY,
     values: STRING_ARRAY,
+    valueConstraints: {
+      type: "array",
+      description: "Statically checkable semantic bounds on authored Stimulus Values.",
+      items: {
+        type: "object",
+        properties: {
+          value: { type: "string", description: "Camel-case declared Value name." },
+          type: { type: "string", enum: ["number"] },
+          finite: { type: "boolean" },
+          greaterThan: { type: "number" },
+          suggestion: { type: "string" }
+        },
+        required: ["value", "type", "suggestion"]
+      }
+    },
+    valueRelations: {
+      type: "array",
+      description: "Statically checkable relationships between authored Stimulus Values.",
+      items: {
+        type: "object",
+        properties: {
+          left: { type: "string", description: "Camel-case left Value name." },
+          operator: { type: "string", enum: ["less-than-or-equal"] },
+          right: { type: "string", description: "Camel-case right Value name." },
+          leftDefault: { type: "number" },
+          rightDefault: { type: "number" },
+          suggestion: { type: "string" }
+        },
+        required: ["left", "operator", "right", "leftDefault", "rightDefault", "suggestion"]
+      }
+    },
     actions: STRING_ARRAY,
     events: STRING_ARRAY,
     requiredTargets: {
@@ -2342,6 +2541,30 @@ var CONTROLLER_CONTRACT_SCHEMA = {
         required: ["target", "suggestion"]
       }
     },
+    hosts: {
+      type: "array",
+      description: "Scope or target host-element contracts that prevent the controller from competing with an incompatible native interaction.",
+      items: {
+        type: "object",
+        properties: {
+          target: {
+            type: "string",
+            description: 'Target name; "" means the data-controller element itself.'
+          },
+          mode: {
+            type: "string",
+            enum: ["non-interactive", "non-interactive-or-button"],
+            description: "Supported static host family."
+          },
+          buttonTypes: {
+            ...STRING_ARRAY,
+            description: "Literal button types admitted by non-interactive-or-button."
+          },
+          suggestion: { type: "string" }
+        },
+        required: ["target", "mode", "suggestion"]
+      }
+    },
     managedAria: {
       type: "array",
       description: "ARIA the controller recomputes at runtime; authoring it is a warning.",
@@ -2478,12 +2701,15 @@ var CONTROLLER_CONTRACT_SCHEMA = {
     "id",
     "targets",
     "values",
+    "valueConstraints",
+    "valueRelations",
     "actions",
     "events",
     "requiredTargets",
     "conditionalTargets",
     "a11y",
     "keyboard",
+    "hosts",
     "managedAria",
     "compositions",
     "companions",
@@ -2502,7 +2728,7 @@ var TOOL_DESCRIPTORS = [
   {
     name: "stimeo_check",
     title: "Check Stimeo UI markup",
-    description: "Statically check HTML or ERB source that uses Stimeo UI (stimeo--*) controllers \u2014 the headless, accessible Stimulus UI component library for Rails. Returns a CheckReport with diagnostics \u2014 unknown controllers/targets/values/action methods, missing required targets, missing or invalid author-supplied ARIA, keyboard-focusability prerequisites, and misaligned cross-controller composition values \u2014 each with a fix suggestion when available. Call this to validate any Rails view, ERB template, or HTML you write or edit with these components, before finalizing it; ok=true means no errors.",
+    description: "Statically check HTML or ERB source that uses Stimeo UI (stimeo--*) controllers \u2014 the headless, accessible Stimulus UI component library for Rails. Returns a CheckReport with diagnostics \u2014 unknown controllers/targets/values/action methods, missing required targets, missing or invalid author-supplied ARIA, keyboard-focusability prerequisites, incompatible interactive hosts, and misaligned cross-controller composition values \u2014 each with a fix suggestion when available. Call this to validate any Rails view, ERB template, or HTML you write or edit with these components, before finalizing it; ok=true means no errors.",
     annotations: READ_ONLY_ANNOTATIONS,
     inputSchema: {
       type: "object",
@@ -2536,7 +2762,7 @@ var TOOL_DESCRIPTORS = [
   {
     name: "stimeo_controller",
     title: "Get one controller's usage contract",
-    description: 'Fetch the full usage contract of one Stimeo UI controller by identifier (e.g. "stimeo--tabs"): targets, values, actions, events, required targets, and the accessibility contract \u2014 author-supplied ARIA requirements, keyboard-focusability prerequisites, the ARIA attributes the controller manages at runtime (which the author must NOT hardcode), and cross-controller composition value alignments. Use it after stimeo_catalog to write correct, accessible Rails ERB or HTML markup for that Stimulus component.',
+    description: 'Fetch the full usage contract of one Stimeo UI controller by identifier (e.g. "stimeo--tabs"): targets, values, actions, events, required targets, and the accessibility contract \u2014 author-supplied ARIA requirements, keyboard-focusability prerequisites, supported host-element shapes, the ARIA attributes the controller manages at runtime (which the author must NOT hardcode), and cross-controller composition value alignments. Use it after stimeo_catalog to write correct, accessible Rails ERB or HTML markup for that Stimulus component.',
     annotations: READ_ONLY_ANNOTATIONS,
     inputSchema: {
       type: "object",