@grailwind/eslint-plugin 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -1,6 +1,10 @@
 # @grailwind/eslint-plugin
 
-ESLint rules for [Grailwind](https://pafirmin.github.io/grailwind/) markup in JSX and HTML.
+[![Test](https://github.com/pafirmin/grailwind/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/pafirmin/grailwind/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/@grailwind/eslint-plugin/beta)](https://www.npmjs.com/package/@grailwind/eslint-plugin)
+[![License: MIT](https://img.shields.io/npm/l/@grailwind/eslint-plugin)](https://github.com/pafirmin/grailwind/blob/main/packages/eslint-plugin/LICENSE)
+
+ESLint rules for [Grailwind](https://grailwind.dev/) markup in JSX and HTML.
 
 > **Beta.** Rules, their options and the `recommended` config may change between releases.
 
@@ -9,7 +13,7 @@ npm install --save-dev @grailwind/eslint-plugin@beta
 ```
 
 It reads the tinctures, ordinaries and charges from your installed `grailwind`, so it needs
-`grailwind` 0.4.x. For typos and other class errors, see
+`grailwind` 0.6.x. For typos and other class errors, see
 [Linting](https://github.com/pafirmin/grailwind#linting) in the Grailwind README.
 
 ## Setup
@@ -53,19 +57,23 @@ export default [
 No metal (`or`, `argent`) on metal, and no colour on colour.
 
 - An ordinary, chief or bordure is checked against the field on the same element:
-  `escutcheon or fess-argent` is metal on metal. So are engrailed and invected ones
-  (`fess-engrailed-argent`).
+  `escutcheon or fess-argent` is metal on metal. So are engrailed, invected and voided ones
+  (`fess-engrailed-argent`, `cross-voided-argent`).
 - A fimbriated ordinary is checked against its fimbriation, and the fimbriation against the
   field: `or chevron-sable fimbriated-argent` is metal on metal (Argent on Or).
 - Charges in a `charges` container are checked against the field.
 - Charges in a `charges on` container are checked against the ordinary they lie on.
-- Charges at `in-dexter-chief`, `in-chief` or `in-sinister-chief` are checked against the chief,
-  if there is one.
+- Charges at `in-dexter-chief`, `in-chief-point` or `in-sinister-chief`, or in a
+  `charges in-chief` container, are checked against the chief, if there is one.
+- A plain canton or inescutcheon, one with nothing on it, is checked against the field it lies
+  on. One with charges, an ordinary or a division counts as arms of its own and is exempt.
 
 A divided field (`per-pale-or-gules`) has no single tincture, so nothing is checked against it.
 Neither are `<img>` charges, charges with no tincture, or `bordure-*` with a non-heraldic colour.
 Counterchanged ordinaries and charges take the field's tinctures swapped, so they're skipped too.
 
+`of-the-first` is checked as the shield's first tincture, and reported if it can't be seen.
+
 Furs count by their ground: `ermine` and `erminois` as metals, `ermines` and `pean` as colours.
 `ermine fess-argent` is metal on metal. Authorities differ, so the `furs` option changes this:
 
@@ -84,6 +92,8 @@ A fur left out of the map counts by its ground.
 Charges (`mullet`, `bezant`, `charge-[…]` and so on) must be direct children of a `charges`
 container.
 
+An arrangement (`in-chief`, `in-pale`, `between` and so on) goes on the container, not a charge.
+
 ### `arrangement-needs-ordinary`
 
 `charges between` and `charges on` take their positions from the ordinary on the shield. Without
@@ -94,7 +104,7 @@ one, other than a chief, they have nowhere to go.
 An element draws one ordinary plus, optionally, a chief. With two, such as
 `fess-azure chevron-gules`, only one shows. Two chiefs are flagged too. A `charges` container
 takes one arrangement: `between`, `on`, `in-pale`, `in-fess`, `in-bend` or `in-bend-sinister`.
-Counterchanged, engrailed, invected and fur ordinaries count as ordinaries.
+Counterchanged, engrailed, invected, voided and fur ordinaries count as ordinaries.
 
 A charge at a named point (`in-dexter-chief` and so on) is a separate group in the blazon, so it
 goes in its own `charges` container. Among other charges, it still counts towards their number
@@ -109,8 +119,8 @@ Modifiers that would otherwise do nothing:
   element, e.g. `per-pale-argent-gules`.
 - `counterchanged` on `charges`, or on a charge, needs a divided field on the shield that holds
   the container.
-- `fimbriated-*` needs a plain tinctured ordinary. A chief, and an engrailed, invected, fur or
-  counterchanged ordinary, aren't fimbriated.
+- `fimbriated-*` needs a plain tinctured ordinary. A chief, and an engrailed, invected, voided,
+  fur or counterchanged ordinary, aren't fimbriated.
 - `counterchanged` doesn't work on a charge with a transform (`rotate-*`, `scale-*`, `skew-*`,
   `translate-*`): the charge shows its own small copy of the field instead.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grailwind/eslint-plugin",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "description": "ESLint rules for Grailwind heraldry markup: the rule of tincture and charge structure",
   "type": "module",
   "main": "./src/index.js",
@@ -26,7 +26,7 @@
   "peerDependencies": {
     "@html-eslint/parser": "*",
     "eslint": "^9.0.0 || ^10.0.0",
-    "grailwind": "^0.4.0"
+    "grailwind": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@html-eslint/parser": {
@@ -41,7 +41,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://pafirmin.github.io/grailwind/",
+  "homepage": "https://grailwind.dev/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pafirmin/grailwind.git",

package/src/blazon.js

@@ -1,6 +1,7 @@
 /*
  * Reading heraldry from a set of class names.
  */
+import { UNKNOWN } from "./tree.js";
 import {
   ARRANGEMENTS,
   CHARGES,
@@ -9,10 +10,12 @@ import {
   FURS,
   LINES,
   METALS,
+  OF_THE_FIRST,
   ORDINARIES,
   POINTS,
   ROUNDELS,
   TINCTURES,
+  VOIDABLE,
 } from "grailwind/data";
 
 const METAL = new Set(METALS);
@@ -20,9 +23,11 @@ const COLOUR = new Set(COLOURS);
 const FUR = new Set(Object.keys(FURS));
 // Anything a field, ordinary or charge can be painted in.
 const TINCTURE = new Set([...TINCTURES, ...FUR]);
+// What a class can paint in: a tincture, or the field's first.
+const PAINT = new Set([...TINCTURE, OF_THE_FIRST]);
 const CHARGE = new Set([...CHARGES, ...Object.keys(ROUNDELS)]);
-const FIMBRIATIONS = new Set(TINCTURES.map((t) => `fimbriated-${t}`));
-const CHIEF_POINTS = new Set(["in-dexter-chief", "in-chief", "in-sinister-chief"]);
+const FIMBRIATIONS = new Set([...TINCTURES, OF_THE_FIRST].map((t) => `fimbriated-${t}`));
+const CHIEF_POINTS = new Set(["in-dexter-chief", "in-chief-point", "in-sinister-chief"]);
 const POINT_CLASSES = new Set(Object.keys(POINTS).map((point) => `in-${point}`));
 export const ALL_ARRANGEMENTS = ["between", "on", ...ARRANGEMENTS];
 
@@ -30,7 +35,7 @@ export const ALL_ARRANGEMENTS = ["between", "on", ...ARRANGEMENTS];
 // `bordure-or`, mapped to its parts. A counterchanged ordinary has no tincture of its own.
 const ORDINARY_CLASSES = new Map();
 for (const ordinary of ORDINARIES) {
-  for (const tincture of TINCTURE) {
+  for (const tincture of PAINT) {
     const fur = FUR.has(tincture);
     ORDINARY_CLASSES.set(`${ordinary}-${tincture}`, { ordinary, tincture, fur });
     for (const line of LINES) {
@@ -43,24 +48,41 @@ for (const ordinary of ORDINARIES) {
     counterchanged: true,
   });
 }
-for (const tincture of TINCTURES) {
+for (const ordinary of VOIDABLE) {
+  for (const tincture of PAINT) {
+    const fur = FUR.has(tincture);
+    ORDINARY_CLASSES.set(`${ordinary}-voided-${tincture}`, {
+      ordinary,
+      tincture,
+      fur,
+      voided: true,
+    });
+  }
+  ORDINARY_CLASSES.set(`${ordinary}-voided-counterchanged`, {
+    ordinary,
+    tincture: null,
+    counterchanged: true,
+    voided: true,
+  });
+}
+for (const tincture of [...TINCTURES, OF_THE_FIRST]) {
   ORDINARY_CLASSES.set(`bordure-${tincture}`, { ordinary: "bordure", tincture });
 }
 
-// Two furs in one division aren't generated.
-const DIVISION_CLASSES = new Set();
+// Each division class, mapped to its first tincture. Two furs in one division aren't generated.
+const DIVISION_CLASSES = new Map();
 for (const division of DIVISIONS) {
   for (const a of TINCTURE) {
     for (const b of TINCTURE) {
       if (a !== b && !(FUR.has(a) && FUR.has(b))) {
-        DIVISION_CLASSES.add(`${division}-${a}-${b}`);
+        DIVISION_CLASSES.set(`${division}-${a}-${b}`, a);
       }
     }
   }
 }
 
 // Only a plain, tinctured ordinary is fimbriated (see ordinaries.js).
-export const isFimbriable = (o) => !o.counterchanged && !o.line && !o.fur;
+export const isFimbriable = (o) => !o.counterchanged && !o.line && !o.fur && !o.voided;
 
 export const isFur = (tincture) => FUR.has(tincture);
 
@@ -128,17 +150,66 @@ export function fieldTincture(classes) {
   if (isDivided(classes)) {
     return null;
   }
-  const tinctures = [...classes].filter((cls) => TINCTURE.has(cls));
+  const tinctures = [...classes].filter((cls) => PAINT.has(cls));
   return tinctures.length === 1 ? tinctures[0] : null;
 }
 
+const isEmptyNode = (node) => {
+  switch (node.type) {
+    case "Comment": {
+      return true;
+    }
+    case "JSXExpressionContainer": {
+      return node.expression.type === "JSXEmptyExpression";
+    }
+    case "Text":
+    case "JSXText": {
+      return node.value.trim() === "";
+    }
+    default: {
+      return false;
+    }
+  }
+};
+
+// A canton or inescutcheon with nothing on it. Cantons/inescutcheons with their
+// own arms are exempt from rule-of-tincture.
+export function isPlain(el) {
+  const { ordinaries, chiefs, bordures } = ordinariesOf(el.classes);
+  return (
+    fieldTincture(el.classes) !== null &&
+    !ordinaries.length &&
+    !chiefs.length &&
+    !bordures.length &&
+    (el.node.children ?? []).every(isEmptyNode)
+  );
+}
+
+// A field's first tincture: its bare tincture, or its division's first.
+const fieldFirst = (classes) => {
+  const division = [...classes].find((cls) => DIVISION_CLASSES.has(cls));
+  return division ? DIVISION_CLASSES.get(division) : fieldTincture(classes);
+};
+
+// `of-the-first` on an element: the nearest escutcheon's or quarter's first (not a canton's).
+// Null if the shield can't be seen.
+export function firstOf(el) {
+  for (let node = el; node && node !== UNKNOWN; node = node.parent) {
+    if (node.classes?.has("escutcheon") || node.parent?.classes?.has("quarterly")) {
+      const first = fieldFirst(node.classes);
+      return first === OF_THE_FIRST ? null : first;
+    }
+  }
+  return null;
+}
+
 // A charge's tincture, and the class that gives it, e.g. `bezant` → or.
 export function chargeTincture(classes) {
   const roundel = [...classes].find((cls) => ROUNDELS[cls]);
   if (roundel) {
     return { cls: roundel, tincture: ROUNDELS[roundel] };
   }
-  const tinctures = [...classes].filter((cls) => TINCTURE.has(cls));
+  const tinctures = [...classes].filter((cls) => PAINT.has(cls));
   return tinctures.length === 1 ? { cls: tinctures[0], tincture: tinctures[0] } : null;
 }
 
@@ -158,7 +229,11 @@ export const isCharge = (classes) => chargeName(classes) !== null;
 
 export const pointOf = (classes) => [...classes].find((cls) => POINT_CLASSES.has(cls));
 
-export const atChiefPoint = (classes) => [...classes].some((cls) => CHIEF_POINTS.has(cls));
+const atChiefPoint = (classes) => [...classes].some((cls) => CHIEF_POINTS.has(cls));
+
+// A charge on the chief, if the shield has one: at a chief point, or arranged `in-chief`.
+export const inChief = (container, charge) =>
+  atChiefPoint(charge.classes) || container.classes.has("in-chief");
 
 export const arrangementsOf = (classes) => ALL_ARRANGEMENTS.filter((name) => classes.has(name));
 

package/src/rules/charges-in-container.js

@@ -1,16 +1,27 @@
 import { getElements, UNKNOWN } from "../tree.js";
-import { chargeName } from "../blazon.js";
+import { arrangementsOf, chargeName } from "../blazon.js";
+
+// The tail of the `arranged` message: where to place one charge instead, or "" for none.
+const hint = (cls) => {
+  return (
+    {
+      "in-chief": "; to place one charge, use `in-chief-point`",
+      "in-base": "; to place one charge, use `in-base-point`",
+    }[cls] ?? ""
+  );
+};
 
 export default {
   meta: {
     type: "problem",
     docs: {
-      description: "Require charges to be inside a `charges` container",
+      description: "Require charges to be inside a `charges` container, and arrangements on it",
       url: "https://github.com/pafirmin/grailwind/tree/main/packages/eslint-plugin#charges-in-container",
     },
     schema: [],
     messages: {
       outside: "`{{charge}}` must be inside a `charges` container",
+      arranged: "`{{cls}}` arranges a `charges` container, not a charge{{hint}}",
     },
   },
 
@@ -21,10 +32,20 @@ export default {
           if (!el.classes || el.parent === UNKNOWN || !el.parent.classes) {
             continue;
           }
+          const inContainer = el.parent.classes.has("charges");
           const charge = chargeName(el.classes);
-          if (charge && !el.parent.classes.has("charges")) {
+          if (charge && !inContainer) {
             context.report({ node: el.reportNode, messageId: "outside", data: { charge } });
           }
+          if (inContainer) {
+            for (const cls of arrangementsOf(el.classes)) {
+              context.report({
+                node: el.reportNode,
+                messageId: "arranged",
+                data: { cls, hint: hint(cls) },
+              });
+            }
+          }
         }
       },
     };

package/src/rules/rule-of-tincture.js

@@ -1,15 +1,17 @@
-import { FURS } from "grailwind/data";
-import { getElements } from "../tree.js";
+import { FURS, OF_THE_FIRST } from "grailwind/data";
+import { getElements, UNKNOWN } from "../tree.js";
 import {
-  atChiefPoint,
   chargeName,
   chargeTincture,
   describe,
   fieldTincture,
   fimbriationOf,
+  firstOf,
   furKinds,
+  inChief,
   isFimbriable,
   isFur,
+  isPlain,
   kind,
   ordinariesOf,
   sameKind,
@@ -21,7 +23,8 @@ const article = (thing) => (/^[aeiou]/.test(thing) ? `an ${thing}` : `a ${thing}
 const KINDS = ["metal", "colour", "exempt"];
 
 // e.g. "fess engrailed", as blazoned.
-const name = ({ ordinary, line }) => describe(line ? `${ordinary} ${line}` : ordinary);
+const name = ({ ordinary, line, voided }) =>
+  describe([ordinary, line, voided && "voided"].filter(Boolean).join(" "));
 
 // e.g. " (ermine counts as a metal)", or " (ermine and erminois count as metals)".
 const furNote = (tinctures, kind) => {
@@ -64,22 +67,40 @@ export default {
     messages: {
       violation:
         "`{{cls}}` puts {{thing}} {{tincture}} on {{ground}}: {{kind}} on {{kind}}{{note}}",
+      invisible:
+        "`{{cls}}` puts {{thing}} of the first on {{ground}}, its own tincture: it can't be seen",
+      plain:
+        "`{{cls}}` puts {{thing}} {{tincture}} on {{ground}}: {{kind}} on {{kind}}{{note}}. Change its tincture, or give it arms of its own",
     },
   },
 
   create(context) {
     const furs = furKinds(context.options[0]?.furs);
-    const check = (node, cls, thing, tincture, ground) => {
+    // `el` is the element whose field or ordinary it is, for resolving `of-the-first`.
+    const check = (el, node, cls, thing, painted, ground, messageId = "violation") => {
+      const first = [painted, ground].includes(OF_THE_FIRST) ? firstOf(el) : null;
+      const tincture = painted === OF_THE_FIRST ? first : painted;
+      if (ground === OF_THE_FIRST) {
+        ground = first;
+      }
+      if (painted === OF_THE_FIRST && tincture && tincture === ground) {
+        context.report({
+          node,
+          messageId: "invisible",
+          data: { cls, thing: article(thing), ground: titleCase(ground) },
+        });
+        return;
+      }
       if (!sameKind(tincture, ground, furs)) {
         return;
       }
       context.report({
         node,
-        messageId: "violation",
+        messageId,
         data: {
           cls,
           thing: article(thing),
-          tincture: titleCase(tincture),
+          tincture: titleCase(tincture) + (painted === OF_THE_FIRST ? " (of the first)" : ""),
           ground: titleCase(ground),
           kind: kind(tincture, furs),
           note: furNote([ground, tincture], kind(tincture, furs)),
@@ -96,14 +117,22 @@ export default {
           const field = fieldTincture(el.classes);
           const { ordinaries, chiefs, bordures } = ordinariesOf(el.classes);
           const fimbriation = fimbriationOf(el.classes);
+
+          // A plain sub-shield lies on its parent's field. A charged or divided one is arms.
+          const sub = ["canton", "inescutcheon"].find((c) => el.classes.has(c));
+          if (sub && isPlain(el) && el.parent !== UNKNOWN && el.parent.classes) {
+            const ground = fieldTincture(el.parent.classes);
+            check(el, el.reportNode, field, `plain ${sub}`, field, ground, "plain");
+          }
           const isFimbriated = fimbriation && ordinaries.some(isFimbriable);
 
           if (isFimbriated) {
-            check(el.reportNode, fimbriation.cls, "fimbriation", fimbriation.tincture, field);
+            check(el, el.reportNode, fimbriation.cls, "fimbriation", fimbriation.tincture, field);
           }
 
           for (const o of ordinaries) {
             check(
+              el,
               el.reportNode,
               o.cls,
               name(o),
@@ -114,7 +143,7 @@ export default {
 
           // An ordinary abuts the chief rather than lying on it, so both are checked against the field.
           for (const o of [...chiefs, ...bordures]) {
-            check(el.reportNode, o.cls, name(o), o.tincture, field);
+            check(el, el.reportNode, o.cls, name(o), o.tincture, field);
           }
 
           for (const container of el.children) {
@@ -137,12 +166,12 @@ export default {
               let ground = field;
               if (container.classes.has("on") && ordinaries.length) {
                 ground = ordinaries[0].tincture;
-              } else if (chiefs.length && atChiefPoint(charge.classes)) {
+              } else if (chiefs.length && inChief(container, charge)) {
                 ground = chiefs[0].tincture;
               }
 
               const thing = describe(chargeName(charge.classes) ?? "charge");
-              check(charge.reportNode, found.cls, thing, found.tincture, ground);
+              check(el, charge.reportNode, found.cls, thing, found.tincture, ground);
             }
           }
         }