stimeo-ui 0.12.0 → 0.14.0

package/dist/inspector/cli.d.ts

@@ -2,7 +2,7 @@
  * Shared types for the Stimeo Inspector CLI (`stimeo check`).
  *
  * The Inspector statically checks HTML/ERB against a *manifest* describing the
- * official `stimeo--` controllers. The same engine powers both the library's
+ * `stimeo--` controllers this package ships. The same engine powers both the library's
  * own contract checks (e.g. `stimeo check app/views`) and the user-facing CLI;
  * it is therefore intentionally input-path agnostic.
  */
@@ -29,6 +29,13 @@ interface ControllerManifest {
      * strictly positive step, so those contracts stay explicit and reviewable.
      */
     readonly valueConstraints: readonly ValueConstraint[];
+    /**
+     * Grammar contracts on String Values whose accepted set cannot be enumerated
+     * (stage 1). Optional on the wire: a manifest written before the field existed
+     * omits it, and an engine written before it skips it, so either side pairs
+     * with the other. See {@link StringSyntaxConstraint}.
+     */
+    readonly valueSyntaxConstraints?: readonly StringSyntaxConstraint[];
     /** Statically decidable relationships between literal Stimulus Values. */
     readonly valueRelations: readonly ValueRelation[];
     /**
@@ -740,6 +747,36 @@ interface StringValueConstraint {
     /** Human-readable fix suggestion shown by the CLI (stage 4). */
     readonly suggestion: string;
 }
+/**
+ * A String Value whose text is only readable by handing it to a parser, so the
+ * contract is a grammar rather than a set of literals.
+ *
+ * The controller parses the same text at runtime and falls back to the Value's
+ * default when it does not read, so a violation is a silently degraded element
+ * rather than a crash — which is exactly what a static check is for. Selectors
+ * are deliberately absent: the Inspector parses HTML itself and has no DOM to
+ * ask, so it cannot tell a malformed selector from one that simply matches
+ * nothing.
+ *
+ * These live in their own manifest field rather than alongside
+ * {@link StringValueConstraint}: an engine that predates them reads every String
+ * entry of `valueConstraints` through `allowedValues`, so a grammar contract
+ * placed there would be accepted by the shape check and then fail on the first
+ * document that declares the Value. A field such an engine never looks at is
+ * skipped instead.
+ */
+interface StringSyntaxConstraint {
+    /** Value name (camelCase, as declared in `static values`). */
+    readonly value: string;
+    /** Decoder family. */
+    readonly type: "string";
+    /** Grammar the whole literal has to satisfy. */
+    readonly syntax: "regexp" | "json-object";
+    /** For `json-object`, the grammar every property value has to satisfy. */
+    readonly entries?: "regexp";
+    /** 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;
 /**
@@ -769,7 +806,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-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", "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"];
 /** See {@link DIAGNOSTIC_CODES}. */
 type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 /**

package/dist/inspector/cli.js

@@ -69,6 +69,30 @@ function announcerSeatingDiagnostic(sources) {
   };
 }
 
+// src/utils/declared_value.ts
+function parseDeclared(raw, parse, fallback) {
+  try {
+    return parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+function compileRegExp(source, anchor = "none") {
+  return parseDeclared(
+    source,
+    (text) => {
+      const bare = new RegExp(text);
+      return anchor === "exact" ? new RegExp(`^(?:${text})$`) : bare;
+    },
+    null
+  );
+}
+function parseJsonObject(raw) {
+  const parsed = parseDeclared(raw, (text) => JSON.parse(text), null);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  return parsed;
+}
+
 // src/inspector/html_parser.ts
 var ERB_ELEMENT_TAG = "#erb";
 var VOID_ELEMENTS = /* @__PURE__ */ new Set([
@@ -987,7 +1011,21 @@ function parseValueAttr(attrName, knownIdentifiers) {
   const valueGuess = dash === -1 ? "" : rest.slice(dash + 1);
   return { identifier: null, valueToken: valueGuess || identifierGuess };
 }
-function actionDescriptors(dataActionValue) {
+var DEFAULT_EVENT_NAMES = {
+  a: "click",
+  button: "click",
+  details: "toggle",
+  form: "submit",
+  input: "input",
+  select: "change",
+  textarea: "input"
+};
+function defaultEventFor(host) {
+  if (!host) return "";
+  if (host.tag === "input" && host.inputType === "submit") return "click";
+  return DEFAULT_EVENT_NAMES[host.tag] ?? "";
+}
+function actionDescriptors(dataActionValue, host) {
   const descriptors = [];
   for (const descriptor of dataActionValue.split(/\s+/)) {
     const hash = descriptor.indexOf("#");
@@ -1000,6 +1038,8 @@ function actionDescriptors(dataActionValue) {
       lhs = lhs.slice(arrow + 2);
       const at = eventType.indexOf("@");
       if (at !== -1) eventType = eventType.slice(0, at);
+    } else {
+      eventType = defaultEventFor(host);
     }
     if (!lhs.startsWith(NAMESPACE_PREFIX)) continue;
     const method = /^[a-zA-Z_$][\w$]*/.exec(descriptor.slice(hash + 1))?.[0] ?? "";
@@ -1024,6 +1064,7 @@ var DIAGNOSTIC_CODES = [
   "missing-conditional-target",
   "missing-required-action",
   "missing-action-completion",
+  "missing-action-event",
   "missing-aria",
   "invalid-aria-value",
   "keyboard-inaccessible",
@@ -1368,9 +1409,7 @@ function checkSource(source, manifest) {
                 didYouMean(parsed.valueToken, (controller?.values ?? []).map(dasherize))
               );
             } else if (!isDynamicValue(attr)) {
-              const constraint = controller?.valueConstraints.find(
-                (candidate) => dasherize(candidate.value) === parsed.valueToken
-              );
+              const constraint = declaredConstraint(controller, parsed.valueToken);
               if (constraint && !valueSatisfiesConstraint(attr.value, constraint)) {
                 const literal = constraint.type === "string" ? attr.value : attr.value.trim();
                 report(
@@ -1388,12 +1427,26 @@ function checkSource(source, manifest) {
         }
       }
       if (attr.name === "data-action") {
-        for (const { identifier, method, eventType } of actionDescriptors(attr.value)) {
+        const host = {
+          tag: node.tag,
+          inputType: node.attrs.find((a) => a.name === "type")?.value
+        };
+        for (const { identifier, method, eventType } of actionDescriptors(attr.value, host)) {
           const controller = known[identifier];
           if (controller && method.length > 0) {
             const owner = findOwner(node, identifier);
             if (owner) recordAction(owner, identifier, node, method, eventType);
           }
+          if (controller && method.length > 0 && eventType === "" && node.origin === "markup" && !isDynamicValue(attr)) {
+            report(
+              node,
+              "missing-action-event",
+              "error",
+              `"${identifier}#${method}" omits the event and <${node.tag}> has no default one, so Stimulus never binds it.`,
+              attr,
+              `Name the event: data-action="<event>->${identifier}#${method}".`
+            );
+          }
           if (!controller) {
             const best = nearestName(identifier, knownIdentifiers);
             report(
@@ -1859,8 +1912,13 @@ function checkSource(source, manifest) {
   diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
   return diagnostics;
 }
+function declaredConstraint(controller, valueToken) {
+  const matches = (candidate) => dasherize(candidate.value) === valueToken;
+  const syntax = controller?.valueSyntaxConstraints;
+  return controller?.valueConstraints.find(matches) ?? (Array.isArray(syntax) ? syntax.find(matches) : void 0);
+}
 function valueSatisfiesConstraint(raw, constraint) {
-  if (constraint.type === "string") return constraint.allowedValues.includes(raw);
+  if (constraint.type === "string") return stringValueSatisfies(raw, constraint);
   const value = decodeNumericValue(raw);
   if (Number.isNaN(value)) return false;
   if (constraint.finite && !Number.isFinite(value)) return false;
@@ -1871,8 +1929,18 @@ function valueSatisfiesConstraint(raw, constraint) {
 function decodeNumericValue(raw) {
   return Number(raw.replace(/_/g, ""));
 }
+function stringValueSatisfies(raw, constraint) {
+  if (!("syntax" in constraint)) return constraint.allowedValues.includes(raw);
+  if (constraint.syntax === "regexp") return compileRegExp(raw, "exact") !== null;
+  if (raw === "") return true;
+  const parsed = parseJsonObject(raw);
+  if (parsed === null) return false;
+  return Object.values(parsed).every(
+    (source) => typeof source === "string" && (constraint.entries !== "regexp" || compileRegExp(source, "exact") !== null)
+  );
+}
 function describeValueConstraint(constraint) {
-  if (constraint.type === "string") return `one of ${list(constraint.allowedValues)}`;
+  if (constraint.type === "string") return describeStringConstraint(constraint);
   const parts = [constraint.finite ? "a finite number" : "a number"];
   if (constraint.greaterThan !== void 0) {
     parts.push(`greater than ${constraint.greaterThan}`);
@@ -1880,6 +1948,11 @@ function describeValueConstraint(constraint) {
   if (constraint.integer) parts.push("with no fractional part");
   return parts.join(" ");
 }
+function describeStringConstraint(constraint) {
+  if (!("syntax" in constraint)) return `one of ${list(constraint.allowedValues)}`;
+  if (constraint.syntax === "regexp") return "a valid regular expression";
+  return constraint.entries === "regexp" ? "a JSON object whose values are valid regular expressions" : "a JSON object of strings";
+}
 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) {
@@ -2265,7 +2338,7 @@ Usage:
                                      Check HTML/ERB files (or directories) for
                                      unknown or misused stimeo--* controllers,
                                      targets, values and action methods.
-  stimeo catalog [--json]           Print the official controller catalog
+  stimeo catalog [--json]           Print the controller catalog
                                      (identifiers, targets, values, actions,
                                      events).
   stimeo mcp                        Run a Model Context Protocol server over