paint-boolean-ops: improve UX — better descriptions, tooltips, swap subtract default to punch-through

Author: griffpatch

addons-l10n/en/paint-boolean-ops.json

@@ -1,14 +1,18 @@
 {
   "paint-boolean-ops/shaping": "Shaping",
   "paint-boolean-ops/unite": "Unite",
+  "paint-boolean-ops/unite-desc": "Unite — merge selected shapes into one, filling all overlapping areas",
   "paint-boolean-ops/subtract": "Subtract",
-  "paint-boolean-ops/subtract-alt": "Subtract (Shift: Punch Through)",
+  "paint-boolean-ops/subtract-alt": "Subtract — cut the front shape out of every selected shape beneath it (Alt: keep the cutter; Shift: subtract all fronts from back shape only)",
   "paint-boolean-ops/intersect": "Intersect",
-  "paint-boolean-ops/intersect-alt": "Intersect (Alt: Divide)",
+  "paint-boolean-ops/intersect-alt": "Intersect — keep only where shapes overlap (Alt: divide at all intersections)",
   "paint-boolean-ops/divide": "Divide",
   "paint-boolean-ops/combine": "Combine",
+  "paint-boolean-ops/combine-desc": "Combine — merge shapes into a compound path; overlapping areas become transparent holes",
   "paint-boolean-ops/release": "Release",
+  "paint-boolean-ops/release-desc": "Release — split this compound path back into separate individual shapes",
   "paint-boolean-ops/expand": "Expand",
+  "paint-boolean-ops/expand-desc": "Expand — grow (positive) or shrink (negative) the shape outline by a set amount",
   "paint-boolean-ops/open-path": "Open Path",
   "paint-boolean-ops/close-path": "Close Path"
 }

addons/paint-boolean-ops/addon.json

@@ -1,6 +1,33 @@
 {
   "name": "Boolean shape operations",
-  "description": "Adds boolean path operations to the vector costume editor: unite, subtract, intersect, exclude, combine, release, expand, open/close path, and a shaping sub-menu.",
+  "description": "Adds a Shaping panel to the vector costume editor: Unite · Subtract · Intersect · Combine/Release · Expand",
+  "info": [
+    {
+      "type": "info",
+      "text": "Unite — merge all selected shapes into one filled shape",
+      "id": "infoUnite"
+    },
+    {
+      "type": "info",
+      "text": "Subtract — front shape cuts a hole in every selected shape below it (Shift: cuts back shape only; Alt: keeps the cutter)",
+      "id": "infoSubtract"
+    },
+    {
+      "type": "info",
+      "text": "Intersect — keep only the overlapping areas of selected shapes (Alt: divide all into distinct regions)",
+      "id": "infoIntersect"
+    },
+    {
+      "type": "info",
+      "text": "Combine / Release — Combine groups shapes into a compound path where overlaps become transparent holes; Release splits it back into separate shapes",
+      "id": "infoCombine"
+    },
+    {
+      "type": "info",
+      "text": "Expand — grow a shape by its outline width",
+      "id": "infoExpand"
+    }
+  ],
   "credits": [
     {
       "name": "griffpatch",

addons/paint-boolean-ops/userscript.js

@@ -75,11 +75,11 @@ export default async function ({ addon, msg }) {
     return btn;
   };
 
-  const uniteBtn = makeItem("unite.svg", msg("unite"), msg("unite"), "unite");
+  const uniteBtn = makeItem("unite.svg", msg("unite"), msg("unite-desc"), "unite");
   const subtractBtn = makeItem("subtract.svg", msg("subtract"), msg("subtract-alt"), "subtract");
   const intersectBtn = makeItem("intersect.svg", msg("intersect"), msg("intersect-alt"), "intersect");
-  const compoundBtn = makeItem("combine.svg", msg("combine"), msg("combine"), "combine");
-  const expandBtn = makeItem("expand.svg", msg("expand"), msg("expand"), "expand");
+  const compoundBtn = makeItem("combine.svg", msg("combine"), msg("combine-desc"), "combine");
+  const expandBtn = makeItem("expand.svg", msg("expand"), msg("expand-desc"), "expand");
   const allItems = [uniteBtn, subtractBtn, intersectBtn, compoundBtn, expandBtn];
 
   // Initially place items in the dropdown rows (collapsed is the default until measured).
@@ -163,8 +163,8 @@ export default async function ({ addon, msg }) {
     else if (op === "release") performRelease();
     else if (op === "expand") performOffset();
     else if (op === "intersect" && e.altKey) performDivide();
-    else if (op === "subtract" && e.shiftKey && e.altKey) performPunchThrough(true);
-    else if (op === "subtract" && e.shiftKey) performPunchThrough(false);
+    else if (op === "subtract" && e.shiftKey) performBooleanOp("subtract", e.altKey);
+    else if (op === "subtract") performPunchThrough(e.altKey);
     else performBooleanOp(op, e.altKey);
   };
   shapingSection.addEventListener("click", handleClick);
@@ -211,7 +211,7 @@ export default async function ({ addon, msg }) {
     // Compound button morphs: combine ↔ release based on selection.
     const compoundOp = hasMultiple ? "combine" : hasCompound ? "release" : "combine";
     compoundBtn.dataset.saOp = compoundOp;
-    compoundBtn.title = msg(compoundOp);
+    compoundBtn.title = msg(`${compoundOp}-desc`);
     compoundBtn.querySelector(".sa-shaping-item-icon").src = `${addon.self.dir}/icons/${compoundOp}.svg`;
     compoundBtn.querySelector(".sa-shaping-item-label").textContent = msg(compoundOp);
     // Open/Close button morphs: "Open Path" when selection is closed, "Close Path" when open.
@@ -989,7 +989,7 @@ export default async function ({ addon, msg }) {
         // Extract layout and separator classes from native toolbar elements.
         const nativeDashedGroup = fixedToolsRow.querySelector("[class*='mod-dashed-border']");
         dashedBorderClass = nativeDashedGroup
-          ? [...nativeDashedGroup.classList].find((c) => c.includes("mod-dashed-border")) ?? ""
+          ? ([...nativeDashedGroup.classList].find((c) => c.includes("mod-dashed-border")) ?? "")
           : "";
 
         // Add a dashed separator to the LEFT of our section (right border on preceding group).
@@ -1012,7 +1012,9 @@ export default async function ({ addon, msg }) {
         const anyTitle = fixedToolsRow.querySelector("[class*='labeled-icon-button_edit-field-title']");
 
         const anyDisabled = document.querySelector("[class*='button_mod-disabled']");
-        modDisabledClass = anyDisabled ? [...anyDisabled.classList].find((c) => c.includes("mod-disabled")) ?? "" : "";
+        modDisabledClass = anyDisabled
+          ? ([...anyDisabled.classList].find((c) => c.includes("mod-disabled")) ?? "")
+          : "";
 
         if (anyBtn) shapingBtn.className += " " + anyBtn.className;
         if (anyIcon) shapingIcon.className += " " + anyIcon.className;