grailwind 0.8.1 → 0.9.0

package/furs.js

@@ -1,8 +1,21 @@
 /*
- * Grailwind CSS: furs, as a tiled pattern of spots over a ground tincture.
+ * Grailwind CSS: furs, as a tiled pattern over a ground tincture: ermine's spots, or the vair
+ * family's panes.
  */
 import plugin from "tailwindcss/plugin";
-import { FURS } from "./data.js";
+import { FUR_PATTERNS, FURS } from "./data.js";
+
+/**
+ * An SVG image as a CSS background-image value.
+ * @param {string} viewBox The SVG's viewBox, e.g. "0 0 50 60".
+ * @param {string} fill A CSS colour, e.g. "#f2f2f2", for everything in `body`.
+ * @param {string} body SVG elements, drawn in `fill`.
+ * @returns {string} A CSS `url("data:image/svg+xml,…")`.
+ */
+const svg = (viewBox, fill, body) =>
+  `url("data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns='http://www.w3.org/2000/svg' viewBox='${viewBox}'><g fill='${fill}'>${body}</g></svg>`,
+  )}")`;
 
 const SPOT = [
   `<circle cx='0' cy='-8.5' r='1.9'/><circle cx='-3.4' cy='-5.6' r='1.9'/><circle cx='3.4' cy='-5.6' r='1.9'/>`,
@@ -18,30 +31,170 @@ export const AT = [
   [0, 60],
   [50, 60],
 ];
-const tile = (fill) =>
-  `url("data:image/svg+xml,${encodeURIComponent(
-    `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 50 60'><g fill='${fill}'>${AT.map(
-      ([x, y]) => `<g transform='translate(${x} ${y})'>${SPOT}</g>`,
-    ).join("")}</g></svg>`,
-  )}")`;
+/**
+ * Ermine's tile: the spots, on a transparent ground.
+ * @param {string} fill A CSS colour for the spots.
+ * @returns {string} A CSS `url(…)`, from svg().
+ */
+const ermineTile = (fill) =>
+  svg(
+    "0 0 50 60",
+    fill,
+    AT.map(([x, y]) => `<g transform='translate(${x} ${y})'>${SPOT}</g>`).join(""),
+  );
 
-// The spots are baked into an SVG, which can't read CSS variables, so they take the theme's
-// value at build time.
-const spots = (fur, theme) => tile(theme(`colors.${FURS[fur][1]}`));
+// The vair family's pane is PANE wide, and its row as high as its outline. Each outline is the
+// pane's right side, from its top down to its base, about the pane's centre line; the left side
+// mirrors it. Each side is symmetric about its own midpoint, so the gap between two panes is the
+// same pane reversed.
+const PANE = 30;
+const VAIR_ROW = 32;
+const SLOPE = VAIR_ROW / 4;
+const POTENT_ROW = 18;
+const OUTLINES = {
+  // Slope to the shoulder, upright side, flare to the base corner.
+  vair: [
+    [0, 0],
+    [PANE / 4, SLOPE],
+    [PANE / 4, VAIR_ROW - SLOPE],
+    [PANE / 2, VAIR_ROW],
+  ],
+  // A T: the crossbar on top, twice the stem.
+  potent: [
+    [PANE / 3, 0],
+    [PANE / 3, POTENT_ROW / 2],
+    [PANE / 6, POTENT_ROW / 2],
+    [PANE / 6, POTENT_ROW],
+  ],
+};
 
-// Spots across the field, one per tile in each row.
-const ACROSS = 6;
+/**
+ * @param {string} pattern A value of FUR_PATTERNS, e.g. "counter-vair".
+ * @returns {"ermine" | "vair" | "potent"} The family, which sets the pane's outline and density.
+ */
+const family = (pattern) =>
+  pattern.endsWith("potent") ? "potent" : pattern.endsWith("vair") ? "vair" : "ermine";
+
+/**
+ * One pane, pointing up, with its top centre at (0, 0).
+ * @param {number[][]} outline The pane's right side as [x, y] points, e.g. OUTLINES.vair.
+ * @returns {string} An SVG `<path>`, with no fill of its own.
+ */
+const pane = (outline) => {
+  const right = outline.map(([x, y]) => `${x},${y}`);
+  const left = outline.toReversed().map(([x, y]) => `${-x},${y}`);
+  return `<path d='M${[...right, ...left].join(" L")} Z'/>`;
+};
 
+/**
+ * The vair family's tile, PANE wide and two rows high. Only the first tincture's panes are drawn;
+ * the ground shows through the gaps between them as the second tincture's panes.
+ *
+ * Row 1 has one pane, centred. Row 2 is offset half a pane in vair and potent, drawn at both edges
+ * so the halves join across tiles; in the counter- forms it's mirrored, base to base with row 1.
+ *
+ * @param {"vair" | "counter-vair" | "potent" | "counter-potent"} pattern
+ * @param {string} fill A CSS colour for the drawn panes, e.g. argent's "#f2f2f2" in vair.
+ * @returns {string} A CSS `url(…)`, from svg().
+ */
+const paneTile = (pattern, fill) => {
+  const outline = OUTLINES[family(pattern)];
+  const row = outline.at(-1)[1];
+  const at = (x, y, path) => `<g transform='translate(${x} ${y})'>${path}</g>`;
+  const viewBox = `0 0 ${PANE} ${2 * row}`;
+  if (pattern.startsWith("counter-")) {
+    // Both rows as one outline: two paths meeting base to base leave a hairline where each one's
+    // edge is antialiased.
+    const mirrored = outline.toReversed().map(([x, y]) => [x, 2 * row - y]);
+    return svg(viewBox, fill, at(PANE / 2, 0, pane([...outline, ...mirrored])));
+  }
+  const path = pane(outline);
+  return svg(
+    viewBox,
+    fill,
+    [at(PANE / 2, 0, path), at(0, row, path), at(PANE, row, path)].join(""),
+  );
+};
+
+/**
+ * A fur's tile. The SVG can't read CSS variables, so it takes the theme's colour at build time.
+ * @param {string} fur A key of FURS, e.g. "vairy-or-gules".
+ * @param {Function} theme Tailwind's theme() lookup.
+ * @returns {string} A CSS `url(…)` of the drawn tincture only; the ground isn't in it.
+ */
+const tile = (fur, theme) => {
+  const pattern = FUR_PATTERNS[fur];
+  const fill = theme(`colors.${FURS[fur][1]}`);
+  return pattern === "ermine" ? ermineTile(fill) : paneTile(pattern, fill);
+};
+
+/**
+ * `fur-<n>` sets --fur-across, n whole tiles across the field. It's left unregistered, so each
+ * family keeps its own default: 6 for ermine; 4 for vair, which Fox-Davies calls vair, between
+ * beffroi (3) and menu-vair (6); and 3 for potent, as in Fox-Davies' and Parker's figures.
+ * @param {number} fallback Tiles across when no `fur-<n>` is set.
+ * @returns {string} A CSS var() for the number of tiles across.
+ */
+const across = (fallback) => `var(--fur-across, ${fallback})`;
 // A quarter of a tile up and left, so whole spots sit along the top and sides. A % position is a
-// share of (box - tile), which is (ACROSS - 1) tiles.
-const SHIFT = `${-100 / (4 * (ACROSS - 1))}%`;
-const FIELD = { size: `calc(100% / ${ACROSS}) auto`, position: `${SHIFT} ${SHIFT}` };
+// share of (box - tile), which is (n - 1) tiles.
+const SHIFT = `calc(-100% / (4 * (${across(6)} - 1)))`;
+const FIELDS = {
+  ermine: { size: `calc(100% / ${across(6)}) auto`, position: `${SHIFT} ${SHIFT}` },
+  // A whole number of panes, from the top left.
+  vair: { size: `calc(100% / ${across(4)}) auto`, position: "0 0" },
+  potent: { size: `calc(100% / ${across(3)}) auto`, position: "0 0" },
+};
+/**
+ * @param {string} fur A key of FURS.
+ * @returns {{ size: string, position: string }} The CSS background-size and -position of its tile.
+ */
+const field = (fur) => FIELDS[family(FUR_PATTERNS[fur])];
 
-// The layers under a fur in a divided field: the spots, then the ground.
+// Ermine's spots on a bordure are 1.4 bordure widths across. At the default eighth, the side
+// columns are then on the ring's centre lines (3.5 widths = 5 half-tiles), whatever the width.
+const RING_ERMINE_TILE = 1.4;
+// A bordure's panes are one row across its width, so the tile is as wide as the pane's share of it.
+const RINGS = {
+  ermine: {
+    size: `calc(${RING_ERMINE_TILE} * var(--bordure-width)) auto`,
+    position: `center calc(var(--bordure-width) / 2)`,
+  },
+  vair: { size: `calc(var(--bordure-width) * ${PANE} / ${VAIR_ROW}) auto`, position: "center 0" },
+  potent: {
+    size: `calc(var(--bordure-width) * ${PANE} / ${POTENT_ROW}) auto`,
+    position: "center 0",
+  },
+};
+
+/**
+ * A fur on a frame's bordure ring, sized to the bordure's width, not to `fur-<n>`.
+ * @param {string} fur A key of FURS.
+ * @param {Function} theme Tailwind's theme() lookup.
+ * @returns {Record<string, string>} CSS background declarations for the ring's ::after.
+ */
+export const ringBackground = (fur, theme) => {
+  const ring = RINGS[family(FUR_PATTERNS[fur])];
+  return {
+    "background-color": `var(--color-${FURS[fur][0]})`,
+    "background-image": tile(fur, theme),
+    "background-size": ring.size,
+    "background-position": ring.position,
+    "background-repeat": "repeat",
+  };
+};
+
+/**
+ * The layers under a fur in a divided field: the pattern, then the ground.
+ * @param {string} fur A key of FURS.
+ * @param {Function} theme Tailwind's theme() lookup.
+ * @returns {{ image: string, size: string, position: string, repeat: string }[]} Background
+ *   layers, top first.
+ */
 export const furLayers = (fur, theme) => {
   const ground = `var(--color-${FURS[fur][0]})`;
   return [
-    { image: spots(fur, theme), ...FIELD, repeat: "repeat" },
+    { image: tile(fur, theme), ...field(fur), repeat: "repeat" },
     {
       image: `linear-gradient(${ground}, ${ground})`,
       size: "100% 100%",
@@ -51,12 +204,17 @@ export const furLayers = (fur, theme) => {
   ];
 };
 
-// A fur on its own, as on the field or an ordinary.
+/**
+ * A fur on its own, as on the field or an ordinary.
+ * @param {string} fur A key of FURS.
+ * @param {Function} theme Tailwind's theme() lookup.
+ * @returns {Record<string, string>} CSS background declarations.
+ */
 export const furBackground = (fur, theme) => ({
   "background-color": `var(--color-${FURS[fur][0]})`,
-  "background-image": spots(fur, theme),
-  "background-size": FIELD.size,
-  "background-position": FIELD.position,
+  "background-image": tile(fur, theme),
+  "background-size": field(fur).size,
+  "background-position": field(fur).position,
   "background-repeat": "repeat",
 });
 
@@ -66,7 +224,7 @@ export default plugin(({ addUtilities, theme }) => {
   for (const fur of Object.keys(FURS)) {
     utilities[`.${fur}`] = {
       ...furBackground(fur, theme),
-      // Two tiles across a charge, centred, so a whole spot sits in its middle.
+      // Two tiles across a charge, centred, so ermine has a whole spot in its middle.
       ".charges > &": {
         "background-size": "50% auto",
         "background-position": "center",

package/grailwind.css

@@ -78,19 +78,37 @@
   syntax: "*";
   inherits: false;
 }
-/* A field's first tincture. The escutcheon copies it to --the-first, which inherits,
+/* A field's first tincture. The heater's field copies it to --the-first, which inherits,
  * so a canton's own field can't change it. */
 @property --field-first {
   syntax: "*";
   inherits: false;
 }
-/* A field's own bordure width, 0 without one. The shield copies it to --outer-inset, which
+/* The shield's first tincture, on the heater, for a bordure ring of the first. It inherits, so
+ * the ring on a frame's ::after sees it, an inescutcheon's included: of the first is the
+ * shield's. */
+@property --frame-first {
+  syntax: "*";
+  inherits: true;
+}
+/* A field's own bordure width, 0 without one. A frame's field copies it to --outer-inset, which
  * inherits, so a canton can step out over the shield's bordure and not its own. */
 @property --bordure-inset {
   syntax: "<length>";
   inherits: false;
   initial-value: 0px;
 }
+/* A part's bordure has none on its palar side: 0 there, and the chief steps out by it. Unset
+ * elsewhere, so the chief falls back to --bordure-inset, and not inherited, so a canton's own
+ * doesn't take its part's. */
+@property --bordure-inset-dexter {
+  syntax: "*";
+  inherits: false;
+}
+@property --bordure-inset-sinister {
+  syntax: "*";
+  inherits: false;
+}
 
 /* ---------------------------------------------------------------------------
  * Tinctures
@@ -117,30 +135,51 @@
 @utility or {
   background-color: var(--color-or);
   --field-first: var(--color-or);
+  .heater:has(> &) {
+    --frame-first: var(--color-or);
+  }
 }
 @utility argent {
   background-color: var(--color-argent);
   --field-first: var(--color-argent);
+  .heater:has(> &) {
+    --frame-first: var(--color-argent);
+  }
 }
 @utility gules {
   background-color: var(--color-gules);
   --field-first: var(--color-gules);
+  .heater:has(> &) {
+    --frame-first: var(--color-gules);
+  }
 }
 @utility azure {
   background-color: var(--color-azure);
   --field-first: var(--color-azure);
+  .heater:has(> &) {
+    --frame-first: var(--color-azure);
+  }
 }
 @utility vert {
   background-color: var(--color-vert);
   --field-first: var(--color-vert);
+  .heater:has(> &) {
+    --frame-first: var(--color-vert);
+  }
 }
 @utility purpure {
   background-color: var(--color-purpure);
   --field-first: var(--color-purpure);
+  .heater:has(> &) {
+    --frame-first: var(--color-purpure);
+  }
 }
 @utility sable {
   background-color: var(--color-sable);
   --field-first: var(--color-sable);
+  .heater:has(> &) {
+    --frame-first: var(--color-sable);
+  }
 }
 /* The field's first tincture, for charges and for a canton or inescutcheon field. */
 @utility of-the-first {
@@ -151,7 +190,9 @@
  * Field divisions
  * ------------------------------------------------------------------------- */
 
-/* Per pale: split vertically into dexter | sinister. */
+/* Per pale: split vertically into dexter | sinister. A split field's parts are its children that
+ * aren't charges, an inescutcheon or a canton: those lie over all of it. The same selector is
+ * PART in ordinaries.js. */
 @utility per-pale {
   display: grid;
   grid-auto-flow: column;
@@ -159,9 +200,10 @@
 
   /* On a shield, each part is a coat of its own: what's in it is placed, stacked and
    * counterchanged within it. */
-  &:is(.escutcheon, .escutcheon *) > * {
+  &:is(.heater, .heater *) > :not(.charges, .inescutcheon, .canton) {
     position: relative;
     contain: layout;
+    --layer-inset: 0px;
   }
 }
 
@@ -173,15 +215,20 @@
 
   /* On a shield, two parts split at the fess point, FESS_POINT in divisions.js.
    * More parts stay equal. */
-  &:is(.escutcheon, .escutcheon *) {
-    &:has(> :last-child:nth-child(2)) {
+  &:is(.heater, .heater *) {
+    &:has(
+      > :nth-child(2 of :not(.charges, .inescutcheon, .canton)):nth-last-child(
+          1 of :not(.charges, .inescutcheon, .canton)
+        )
+    ) {
       grid-template-rows: 45fr 55fr;
     }
 
     /* See per-pale. */
-    & > * {
+    & > :not(.charges, .inescutcheon, .canton) {
       position: relative;
       contain: layout;
+      --layer-inset: 0px;
     }
   }
 }
@@ -194,19 +241,20 @@
   grid-template-rows: 1fr 1fr;
 
   /* Each quarter is a coat of its own, so it starts its own count. */
-  & > * {
+  & > :not(.charges, .inescutcheon, .canton) {
     --the-first: var(--field-first);
     --outer-inset: 0px;
   }
 
   /* On a shield, split at the fess point, as per-fess. */
-  &:is(.escutcheon, .escutcheon *) {
+  &:is(.heater, .heater *) {
     grid-template-rows: 45fr 55fr;
 
     /* See per-pale. */
-    & > * {
+    & > :not(.charges, .inescutcheon, .canton) {
       position: relative;
       contain: layout;
+      --layer-inset: 0px;
     }
   }
 }
@@ -215,37 +263,117 @@
  * Subordinaries
  * ------------------------------------------------------------------------- */
 
-/* Bordure: a border in a given tincture, e.g. `bordure-or`. */
+/* Bordure, e.g. `bordure-or`: a border, so what's inside it lays out within it. On a frame's
+ * field the border is transparent, and a ring on the frame's ::after (see ordinaries.js)
+ * paints it, following the frame's outline. On a per-pale part the ring is on that half, and
+ * the part has no border on the palar side. A chief on the part goes under the ring. Anywhere
+ * else, such as on a quarter or a canton, the border is painted. */
 @utility bordure-* {
   border-style: solid;
   border-width: var(--bordure-width, 0.75rem);
   border-color: --value(--color-*);
   --bordure-inset: var(--bordure-width, 0.75rem);
+
+  :is(.heater, .inescutcheon) > & {
+    border-color: transparent;
+  }
+  :is(.heater, .inescutcheon):has(> &)::after {
+    content: "";
+    background-color: --value(--color-*);
+  }
+  :is(.heater, .inescutcheon)
+    > .per-pale
+    > &:nth-child(1 of :not(.charges, .inescutcheon, .canton)) {
+    border-color: transparent;
+    border-right-width: 0;
+    --bordure-inset-sinister: 0px;
+  }
+  :is(.heater, .inescutcheon):has(
+      > .per-pale > &:nth-child(1 of :not(.charges, .inescutcheon, .canton))
+    )::after {
+    content: "";
+    --ring-dexter: --value(--color-*);
+  }
+  :is(.heater, .inescutcheon)
+    > .per-pale
+    > &:nth-last-child(1 of :not(.charges, .inescutcheon, .canton)) {
+    border-color: transparent;
+    border-left-width: 0;
+    --bordure-inset-dexter: 0px;
+  }
+  :is(.heater, .inescutcheon):has(
+      > .per-pale
+        > &:nth-last-child(1 of :not(.charges, .inescutcheon, .canton))
+    )::after {
+    content: "";
+    --ring-sinister: --value(--color-*);
+  }
 }
 @utility bordure-of-the-first {
   border-style: solid;
   border-width: var(--bordure-width, 0.75rem);
   border-color: var(--the-first, transparent);
   --bordure-inset: var(--bordure-width, 0.75rem);
+
+  :is(.heater, .inescutcheon) > & {
+    border-color: transparent;
+  }
+  :is(.heater, .inescutcheon):has(> &)::after {
+    content: "";
+    background-color: var(--frame-first, transparent);
+  }
+  :is(.heater, .inescutcheon)
+    > .per-pale
+    > &:nth-child(1 of :not(.charges, .inescutcheon, .canton)) {
+    border-color: transparent;
+    border-right-width: 0;
+    --bordure-inset-sinister: 0px;
+  }
+  :is(.heater, .inescutcheon):has(
+      > .per-pale > &:nth-child(1 of :not(.charges, .inescutcheon, .canton))
+    )::after {
+    content: "";
+    --ring-dexter: var(--frame-first, transparent);
+  }
+  :is(.heater, .inescutcheon)
+    > .per-pale
+    > &:nth-last-child(1 of :not(.charges, .inescutcheon, .canton)) {
+    border-color: transparent;
+    border-left-width: 0;
+    --bordure-inset-dexter: 0px;
+  }
+  :is(.heater, .inescutcheon):has(
+      > .per-pale
+        > &:nth-last-child(1 of :not(.charges, .inescutcheon, .canton))
+    )::after {
+    content: "";
+    --ring-sinister: var(--frame-first, transparent);
+  }
 }
 
-/* Inescutcheon: a shield a third as wide, centred on the fess point (50%, 45%),
- * over everything else on the shield. As both are 5:6, it's a third as tall too. */
+/* Inescutcheon: a heater a third as wide round its own field, centred on the fess point
+ * (50%, 45%), over everything else on the shield. As both are 5:6, it's a third as tall too.
+ * Its field takes the shield's first, as "of the first" means the shield's. */
 @utility inescutcheon {
   position: absolute;
-  z-index: 2;
+  z-index: 5;
   width: 33%;
   left: 33.5%;
   top: 28.5%;
+  display: grid;
   aspect-ratio: 5 / 6;
   overflow: clip;
-  overflow-clip-margin: border-box;
-  border-radius: 0 0 50% 50% / 0 0 45% 45%;
-  box-shadow: 0 0 0 2px var(--color-sable);
   contain: layout;
-  /* In proportion with the shield's own bordure. */
-  --bordure-width: 0.25rem;
-  --outer-inset: var(--bordure-inset);
+  container-type: inline-size;
+  /* An eighth of its own width, like the shield's. */
+  --bordure-width: calc(100cqw / 8);
+
+  /* See heater. */
+  & > * {
+    position: relative;
+    --outer-inset: var(--bordure-inset);
+    --layer-inset: var(--bordure-inset);
+  }
 }
 
 /* Canton: a third of the shield each way in dexter chief, so a ninth of it, and
@@ -253,7 +381,7 @@
  * ordinary and charge, as a later addition to the arms, and over the bordure. */
 @utility canton {
   position: absolute;
-  z-index: 2;
+  z-index: 5;
   width: calc((100% + 2 * var(--outer-inset, 0px)) / 3);
   left: calc(-1 * var(--outer-inset, 0px));
   top: calc(-1 * var(--outer-inset, 0px));
@@ -262,26 +390,46 @@
   overflow: clip;
   overflow-clip-margin: border-box;
   contain: layout;
-  --bordure-width: 0.25rem;
+  --layer-inset: 0px;
+  /* A third of the shield's, as cqw is the shield's width: an eighth of the canton's own. */
+  --bordure-width: calc(100cqw / 24);
 }
 
 /* ---------------------------------------------------------------------------
  * The shield itself
  * ------------------------------------------------------------------------- */
 
-/* Escutcheon: a shield shape to draw arms in. */
-@utility escutcheon {
+/* Heater: a pointed shield round its one child, the field, which carries the blazon. The
+ * outline and the clip are in ordinaries.js, from drawings/heater.svg. */
+@utility heater {
   position: relative;
+  display: grid;
   aspect-ratio: 5 / 6;
-  /* At the border's edge, so a canton or chief can surmount the bordure. */
   overflow: clip;
-  overflow-clip-margin: border-box;
-  border-radius: 0 0 50% 50% / 0 0 45% 45%;
-  box-shadow: 0 0 0 2px var(--color-sable);
   /* The containing block for counterchanged charges' fixed layers. */
   contain: layout;
-  --the-first: var(--field-first);
-  --outer-inset: var(--bordure-inset);
+  container-type: inline-size;
+  /* An eighth of the shield's width (BORDURE_WIDTH in ordinaries.js). */
+  --bordure-width: calc(100cqw / 8);
+
+  /* The field. A canton steps out over its bordure, and a counterchanged charge's fixed layer
+   * in by it, to the field's padding box. */
+  & > * {
+    position: relative;
+    --the-first: var(--field-first);
+    --outer-inset: var(--bordure-inset);
+    --layer-inset: var(--bordure-inset);
+  }
+}
+
+/* ---------------------------------------------------------------------------
+ * Fur density
+ * ------------------------------------------------------------------------- */
+
+/* Whole fur tiles across the field, e.g. `fur-3` for beffroi or `fur-6` for menu-vair. Ermine
+ * defaults to 6 and vair to 4. */
+@utility fur-* {
+  --fur-across: --value(integer);
 }
 
 /* ---------------------------------------------------------------------------