@estiva-app/ui 0.35.1 → 0.36.0

package/dist/eslint/escape.d.ts

@@ -3,15 +3,21 @@ import type { AST, Rule } from 'eslint';
  * The escape marker (UIG-3, seam S4 in docs/GATES.md §16): one written reason
  * why one element stays as it is.
  *
- * A line comment directly above the element,
+ * A line comment directly above the element, naming the rule it keeps off,
  *
- *     // @estiva-escape: <reason>
+ *     // @estiva-escape(no-raw-element): <reason>
  *
  * or, where the element is a JSX child, the JSX comment on the line above,
  *
- *     {/* @estiva-escape: <reason> *\/}
+ *     {/* @estiva-escape(no-raw-element): <reason> *\/}
  *
- * with at least ten characters of reason, spaces not counted.
+ * with at least ten characters of reason, spaces not counted. It escapes only
+ * the rules it names (Katerina's ruling B3, 25 September: one reason used to
+ * switch off every rule on the element, so a raw button that also wrote a
+ * dialog's role by hand passed under one reason). Two rules on one element are
+ * named together, `@estiva-escape(no-raw-element, no-rebuilt-behaviour)`, each
+ * on purpose. A marker that names no rule escapes nothing, and says which name
+ * to write.
  *
  * Not `eslint-disable`. A directive switches a rule off without saying it was
  * meant, and the count of escapes (`.gates-count.json`) could not see it. A
@@ -33,10 +39,21 @@ export declare const SETTINGS_KEY = "estiva";
  * reports through the rule that called it.
  */
 export declare const ESCAPE_MESSAGES: {
-    readonly escapeWithoutReason: "An escape needs its reason, at least 10 characters: `// @estiva-escape: <why this stays>`. An escape with no reason hides nothing.";
-    readonly escapeInDirective: "Write the escape as its own comment on the line above: `// @estiva-escape: <reason>`. Inside an eslint-disable comment it switches the rule off instead of recording why.";
+    readonly escapeWithoutReason: "An escape needs its reason, at least 10 characters: `// @estiva-escape({{rule}}): <why this stays>`. An escape with no reason hides nothing.";
+    readonly escapeInDirective: "Write the escape as its own comment on the line above: `// @estiva-escape({{rule}}): <reason>`. Inside an eslint-disable comment it switches the rule off instead of recording why.";
+    readonly escapeWithoutRule: "Name the rule this escape keeps off: `@estiva-escape({{rule}}): <reason>`. An escape now keeps off only the rules it names.";
     readonly escaped: "Escaped: {{reason}}";
 };
+/** A rule's name as a marker writes it: `no-raw-element` for `estiva/no-raw-element`. */
+export declare const shortRuleName: (id: string) => string;
+/**
+ * What a marker says, read from a comment's text: the rules it names (none when
+ * it names none) and its reason. Null when the comment carries no marker.
+ */
+export declare function readMarker(text: string): {
+    rules: string[];
+    reason: string;
+} | null;
 export interface EstivaSettings {
     /**
      * Report every sanctioned escape as a message with the id `escaped`, so a

package/dist/eslint/escape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../../src/eslint/escape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa,mBAAmB,CAAA;AAE7C,gDAAgD;AAChD,eAAO,MAAM,UAAU,KAAK,CAAA;AAE5B,2DAA2D;AAC3D,eAAO,MAAM,YAAY,WAAW,CAAA;AAEpC;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAA;AAEV,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,UAAU,OAAO;IACf,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,GAAG,IAAI,CAAA;IAC/B,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAmC3E"}
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../../src/eslint/escape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,aAAa,mBAAmB,CAAA;AAE7C,gDAAgD;AAChD,eAAO,MAAM,UAAU,KAAK,CAAA;AAE5B,2DAA2D;AAC3D,eAAO,MAAM,YAAY,WAAW,CAAA;AAEpC;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;CAKlB,CAAA;AAEV,yFAAyF;AACzF,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,WAAsC,CAAA;AAE9E;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQnF;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,UAAU,OAAO;IACf,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,GAAG,IAAI,CAAA;IAC/B,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACzB;AAaD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAwC3E"}

package/dist/eslint/index.js

@@ -9,10 +9,21 @@ var ESCAPE_MARKER = "@estiva-escape";
 var MIN_REASON = 10;
 var SETTINGS_KEY = "estiva";
 var ESCAPE_MESSAGES = {
-  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}: <why this stays>\`. An escape with no reason hides nothing.`,
-  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}: <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escapeWithoutReason: `An escape needs its reason, at least ${MIN_REASON} characters: \`// ${ESCAPE_MARKER}({{rule}}): <why this stays>\`. An escape with no reason hides nothing.`,
+  escapeInDirective: `Write the escape as its own comment on the line above: \`// ${ESCAPE_MARKER}({{rule}}): <reason>\`. Inside an eslint-disable comment it switches the rule off instead of recording why.`,
+  escapeWithoutRule: `Name the rule this escape keeps off: \`${ESCAPE_MARKER}({{rule}}): <reason>\`. An escape now keeps off only the rules it names.`,
   escaped: "Escaped: {{reason}}"
 };
+var shortRuleName = (id) => id.slice(id.lastIndexOf("/") + 1);
+function readMarker(text) {
+  const at = text.indexOf(ESCAPE_MARKER);
+  if (at === -1) return null;
+  const rest = text.slice(at + ESCAPE_MARKER.length);
+  const named = /^\s*\(([^)]*)\)/.exec(rest);
+  const rules2 = named ? named[1].split(/[\s,]+/).filter(Boolean).map(shortRuleName) : [];
+  const reason = (named ? rest.slice(named[0].length) : rest).replace(/^\s*:/, "").trim();
+  return { rules: rules2, reason };
+}
 var DIRECTIVE = /^\s*eslint-disable(?:-next-line|-line)?(?=\s|$)([^]*)$/;
 function directiveRules(rest) {
   const dashes = rest.search(/(?:^|\s)--(?:\s|$)/);
@@ -26,18 +37,24 @@ function isEscaped(context, node) {
   const nodeStart = node.range[0];
   const comment = sourceCode.getAllComments().find((c) => c.loc && c.range && c.loc.end.line === line - 1 && BETWEEN.test(sourceCode.text.slice(c.range[1], nodeStart)));
   if (!comment?.loc) return false;
-  const at = comment.value.indexOf(ESCAPE_MARKER);
-  if (at === -1) return false;
+  const marker = readMarker(comment.value);
+  if (!marker) return false;
+  const rule = shortRuleName(context.id);
   const directive = DIRECTIVE.exec(comment.value);
   if (directive) {
     const rules2 = directiveRules(directive[1]);
     if (rules2.length > 0 && !rules2.includes(context.id)) return false;
-    context.report({ loc: comment.loc, messageId: "escapeInDirective" });
+    context.report({ loc: comment.loc, messageId: "escapeInDirective", data: { rule } });
+    return false;
+  }
+  if (marker.rules.length > 0 && !marker.rules.includes(rule)) return false;
+  if (marker.rules.length === 0) {
+    context.report({ loc: comment.loc, messageId: "escapeWithoutRule", data: { rule } });
     return false;
   }
-  const reason = comment.value.slice(at + ESCAPE_MARKER.length).replace(/^:/, "").trim();
+  const { reason } = marker;
   if (reason.replace(/\s/g, "").length < MIN_REASON) {
-    context.report({ loc: comment.loc, messageId: "escapeWithoutReason" });
+    context.report({ loc: comment.loc, messageId: "escapeWithoutReason", data: { rule } });
     return false;
   }
   const settings = context.settings[SETTINGS_KEY];
@@ -175,6 +192,7 @@ var PLACEMENT = [
   // Draws nothing: it names the part, so what is inside can answer its hover (`group-hover:`).
   { what: "a name for hover", pattern: /^(?:group|peer)(?:\/[\w-]+)?$/ }
 ];
+var PLACEMENT_STYLE = /^(?:margin|padding|inset|scrollMargin)(?:Top|Right|Bottom|Left|Block|Inline|BlockStart|BlockEnd|InlineStart|InlineEnd)?$|^(?:width|height|minWidth|minHeight|maxWidth|maxHeight|inlineSize|blockSize|minInlineSize|minBlockSize|maxInlineSize|maxBlockSize)$|^(?:display|flex|flexGrow|flexShrink|flexBasis|order|gap|rowGap|columnGap|alignSelf|justifySelf|placeSelf|gridArea|gridColumn|gridColumnStart|gridColumnEnd|gridRow|gridRowStart|gridRowEnd)$|^(?:position|top|right|bottom|left|zIndex|transform|translate)$/;
 var REACHING_VARIANT = /^\[|^(?:before|after|placeholder|file|marker|selection|first-letter|first-line|backdrop|\*|\*\*)$/;
 function splitClass(token) {
   const variants = [];
@@ -606,6 +624,7 @@ var noRestyledPart = {
     schema: [],
     messages: {
       restyled: "{{classes}} on {{where}} changes how it looks. A part of @estiva-app/ui is placed from outside, never restyled: only space, size, flex and grid, and position pass in.{{use}} A look for what is around it goes on your own element around it.",
+      restyledStyle: "{{keys}} in the `style` of {{where}} changes how it looks. A part of @estiva-app/ui is placed from outside, never restyled, by class or by style: only space, size, flex and grid, and position pass in.{{use}} A look for what is around it goes on your own element around it.",
       emptyStatePadding: "{{classes}} pads {{where}}. EmptyState takes no padding (Katerina, 14 September): its room comes from the box its rows live in, so put the padding on that box.",
       ...ESCAPE_MESSAGES
     }
@@ -639,6 +658,19 @@ var noRestyledPart = {
       }
       if (padding.length) context.report({ loc: at.loc, messageId: "emptyStatePadding", data: { classes: code(padding), where } });
     };
+    const checkStyle = (element, binding, value, at) => {
+      if (binding.props !== "all" || value?.type !== "JSXExpressionContainer") return;
+      let object = child(value, "expression");
+      if (object?.type === "Identifier") object = constantOf(object, scopeOf(object));
+      while (object?.type === "TSAsExpression" || object?.type === "TSSatisfiesExpression") object = child(object, "expression");
+      if (object?.type !== "ObjectExpression") return;
+      const keys = children(object, "properties").map((property) => property?.type === "Property" && !property.computed ? nameOf(child(property, "key")) : void 0).filter((key) => !!key && !key.startsWith("--") && !PLACEMENT_STYLE.test(key));
+      if (!keys.length || escaped(element)) return;
+      const props = PART_LOOK_PROPS[binding.part];
+      const use = props ? ` Use its ${or(props)}.` : ` \`${binding.part}\` has no prop for this yet: ask Katerina, and it gets made in @estiva-app/ui.`;
+      const where = binding.via && binding.via !== binding.part ? `\`${binding.via}\` (it hands its props to \`${binding.part}\`)` : `\`${binding.part}\``;
+      context.report({ loc: at.loc, messageId: "restyledStyle", data: { keys: code([...new Set(keys)]), where, use } });
+    };
     return {
       Program(program) {
         locals = moduleParts(file, program, parser, /* @__PURE__ */ new Set([file])).locals;
@@ -652,6 +684,7 @@ var noRestyledPart = {
           if (attribute3.type === "JSXAttribute") {
             const prop = nameOf(child(attribute3, "name"));
             if (prop && CLASS_PROP.test(prop)) check(element, binding, prop, child(attribute3, "value"), attribute3);
+            else if (prop === "style") checkStyle(element, binding, child(attribute3, "value"), attribute3);
             continue;
           }
           let spread = child(attribute3, "argument");
@@ -1452,6 +1485,28 @@ function isOn(element, name) {
   const attr = attribute2(element, name);
   return attr !== void 0 && literal(attr) !== false;
 }
+var CLICK_HANDLERS = ["onClick", "onMouseDown", "onMouseUp", "onPointerDown", "onPointerUp", "onDoubleClick"];
+function onlyStops(handler) {
+  if (!handler || handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression") return false;
+  const body = handler.body;
+  const calls = body.type === "BlockStatement" ? body.body.map((s) => s.type === "ExpressionStatement" ? s.expression : s) : [body];
+  return calls.length > 0 && calls.every((call) => {
+    if (call.type !== "CallExpression") return false;
+    const callee = call.callee;
+    const property = callee.type === "MemberExpression" ? callee.property : void 0;
+    return property?.type === "Identifier" && (property.name === "stopPropagation" || property.name === "preventDefault");
+  });
+}
+function clickHandler(element) {
+  for (const name of CLICK_HANDLERS) {
+    const attr = attribute2(element, name);
+    if (!attr) continue;
+    const value = attr.value;
+    const handler = value?.type === "JSXExpressionContainer" ? value.expression : void 0;
+    if (!onlyStops(handler)) return name;
+  }
+  return void 0;
+}
 function classify(element) {
   if (element.name.type !== "JSXIdentifier" || !element.name.name) return null;
   const name = element.name.name;
@@ -1466,7 +1521,11 @@ function classify(element) {
     const shown = `<input type="${key}">`;
     return part2 ? { report: "raw", element: shown, part: part2 } : { report: "noPart", element: shown };
   }
-  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) return null;
+  if (!Object.hasOwn(RAW_ELEMENT_PARTS, name)) {
+    if (!/^[a-z][a-z0-9]*$/.test(name) || name === "option" || name === "summary") return null;
+    const handler = clickHandler(element);
+    return handler ? { report: "clickable", element: `<${name} ${handler}>` } : null;
+  }
   if ((name === "audio" || name === "video") && !isOn(element, "controls")) return null;
   if (name === "img" && !attribute2(element, "usemap") && !attribute2(element, "useMap")) return null;
   const part = RAW_ELEMENT_PARTS[name];
@@ -1479,6 +1538,7 @@ var noRawElement = {
     schema: [],
     messages: {
       raw: "Use `{{use}}` from @estiva-app/ui instead of a raw {{element}}.{{more}}",
+      clickable: "A clickable {{element}} is a button made by hand: it takes no focus and answers no key. Use `Button` from @estiva-app/ui; for a whole card that opens something, `Card` with `href`. A handler that only stops the click (`e.stopPropagation()`) is fine.",
       noPart: "@estiva-app/ui has no part for a raw {{element}} yet. Do not build one here: ask Katerina, and it gets made in @estiva-app/ui.",
       ...ESCAPE_MESSAGES
     }
@@ -1491,7 +1551,8 @@ var noRawElement = {
         const found = classify(element);
         if (!found) return;
         if (isEscaped(context, element)) return;
-        if (found.report === "noPart") context.report({ loc: element.loc, messageId: "noPart", data: { element: found.element } });
+        if (found.report === "clickable") context.report({ loc: element.loc, messageId: "clickable", data: { element: found.element } });
+        else if (found.report === "noPart") context.report({ loc: element.loc, messageId: "noPart", data: { element: found.element } });
         else context.report({ loc: element.loc, messageId: "raw", data: { element: found.element, use: found.part.use, more: found.part.more ?? "" } });
       }
     };