Improve Palette Manager harmony swatch labeling - PR_26140_060-improve-harmony-swatch-labeling

Author: DavidQ

docs/dev/reports/palette_harmony_labeling_report.md

@@ -0,0 +1,43 @@
+# Palette Harmony Labeling Report
+
+PR: PR_26140_060-improve-harmony-swatch-labeling
+
+## Summary
+
+Improved Palette Manager V2 harmony result labels without changing harmony calculation or add behavior. Closest-match harmony cards now display the matched palette and swatch color name as the primary label, with the hex value on the next line.
+
+## Changes
+
+- Updated harmony closest-match metadata so palette id/name survives through `closestPaletteMatch`.
+- Added Palette Manager V2 display-name formatting for source palette ids, so `crayola008` is shown as `Crayola008` in harmony cards.
+- Updated harmony result construction:
+  - Calculated mode now displays clean generated labels such as `Complementary - +180 deg` with `#00FFFF` on the next line.
+  - Source Palette Closest Match now displays `<Palette Name> - <Swatch Name>` from the current source palette.
+  - All Palettes Closest Match now displays `<Palette Name> - <Swatch Name>` from the matched palette across all loaded palettes.
+- Updated harmony cards to expose display metadata in DOM data attributes for validation and keep the hex value as the second line.
+- Updated targeted Playwright coverage to confirm palette name, swatch name, hex display, calculated mode labeling, and removal of `Closest ...` display text.
+
+## Scope Notes
+
+- Add Selected and Add All behavior is preserved.
+- Harmony calculation behavior is unchanged.
+- No sample JSON was touched.
+- No full samples smoke test was run, per PR instruction.
+
+## Validation
+
+Passed:
+
+- `node --check tools/palette-manager-v2/modules/paletteHarmonyUtils.js; node --check tools/palette-manager-v2/controls/PaletteHarmonyControl.js; node --check tools/palette-manager-v2/modules/PaletteManagerApp.js; node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list --grep "generates Palette Manager V2 harmony schemes"`
+- `npm run test:workspace-v2` (59 passed)
+- `git diff --check` (passed; Git reported line-ending normalization warning for the modified Playwright spec only)
+
+## Manual Test Notes
+
+1. Open Palette Manager V2.
+2. Select or add a swatch and open Color Harmony Schemes.
+3. In Calculated mode, confirm cards use a clear harmony label and show the hex on the next line.
+4. In Source Palette Closest Match mode, confirm cards show the current source palette name and matched swatch name, with the hex below.
+5. In All Palettes Closest Match mode, confirm cards show the matched palette name and matched swatch name, with the hex below.
+6. Confirm Add Selected and Add All still add colors without duplicate hex entries.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -8104,6 +8104,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await page.locator("#harmonyMatchSourceSelect").selectOption("calculated");
       await page.locator("#harmonySchemeSelect").selectOption("complementary");
       await expect(page.locator("#harmonyColorList [data-harmony-index='0']")).toHaveAttribute("data-harmony-hex", "#00FFFF");
+      await expect(page.locator("#harmonyColorList [data-harmony-index='0'] .palette-manager-v2__harmony-text")).toHaveText("Complementary - +180 deg");
+      await expect(page.locator("#harmonyColorList [data-harmony-index='0'] .palette-manager-v2__harmony-meta")).toHaveText("#00FFFF");
       await page.locator("#addSelectedHarmonyButton").click();
       await expect(page.locator("#userPaletteCount")).toHaveText("2 user swatches");
       await expect(page.locator("#paletteStatus")).toHaveText(/OK Added selected harmony color/);
@@ -8126,21 +8128,47 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await page.locator("#harmonySchemeSelect").selectOption("complementary");
       await page.locator("#harmonyMatchSourceSelect").selectOption("source-palette");
       const sourceMatchState = await page.evaluate(() => {
+        const formatPaletteName = (value) => String(value || "").trim().replace(/^([a-z])/, (letter) => letter.toUpperCase());
         const sourceId = document.querySelector("#sourcePaletteSelect").value;
-        const harmonyHex = document.querySelector("#harmonyColorList [data-harmony-index='0']").dataset.harmonyHex;
-        const sourceHexes = (window.paletteList.SOURCE_PALETTES[sourceId] || []).map((swatch) => swatch.hex.toUpperCase());
-        return { harmonyHex, isFromCurrentSource: sourceHexes.includes(harmonyHex) };
+        const harmonyButton = document.querySelector("#harmonyColorList [data-harmony-index='0']");
+        const harmonyHex = harmonyButton.dataset.harmonyHex;
+        const paletteName = harmonyButton.dataset.harmonyPalette;
+        const swatchName = harmonyButton.dataset.harmonySwatchName;
+        const label = harmonyButton.querySelector(".palette-manager-v2__harmony-text").textContent;
+        const meta = harmonyButton.querySelector(".palette-manager-v2__harmony-meta").textContent;
+        const expectedPaletteName = formatPaletteName(window.paletteList.SOURCE_PALETTE_LABELS[sourceId] || sourceId);
+        const sourceMatch = (window.paletteList.SOURCE_PALETTES[sourceId] || [])
+          .find((swatch) => swatch.hex.toUpperCase() === harmonyHex && swatch.name === swatchName);
+        return { expectedPaletteName, harmonyHex, isFromCurrentSource: Boolean(sourceMatch), label, meta, paletteName, swatchName };
       });
       expect(sourceMatchState.isFromCurrentSource).toBe(true);
+      expect(sourceMatchState.paletteName).toBe(sourceMatchState.expectedPaletteName);
+      expect(sourceMatchState.label).toBe(`${sourceMatchState.expectedPaletteName} - ${sourceMatchState.swatchName}`);
+      expect(sourceMatchState.label).not.toContain("Closest");
+      expect(sourceMatchState.meta).toBe(sourceMatchState.harmonyHex);
 
       await page.locator("#harmonyMatchSourceSelect").selectOption("all-palettes");
       const allMatchState = await page.evaluate(() => {
-        const harmonyHex = document.querySelector("#harmonyColorList [data-harmony-index='0']").dataset.harmonyHex;
-        const allHexes = Object.values(window.paletteList.SOURCE_PALETTES)
-          .flatMap((swatches) => swatches.map((swatch) => swatch.hex.toUpperCase()));
-        return { harmonyHex, isFromAnySource: allHexes.includes(harmonyHex) };
+        const formatPaletteName = (value) => String(value || "").trim().replace(/^([a-z])/, (letter) => letter.toUpperCase());
+        const harmonyButton = document.querySelector("#harmonyColorList [data-harmony-index='0']");
+        const harmonyHex = harmonyButton.dataset.harmonyHex;
+        const paletteName = harmonyButton.dataset.harmonyPalette;
+        const swatchName = harmonyButton.dataset.harmonySwatchName;
+        const label = harmonyButton.querySelector(".palette-manager-v2__harmony-text").textContent;
+        const meta = harmonyButton.querySelector(".palette-manager-v2__harmony-meta").textContent;
+        const allMatch = Object.entries(window.paletteList.SOURCE_PALETTES)
+          .flatMap(([sourceId, swatches]) => swatches.map((swatch) => ({ sourceId, swatch })))
+          .find(({ sourceId, swatch }) => {
+            return swatch.hex.toUpperCase() === harmonyHex
+              && swatch.name === swatchName
+              && formatPaletteName(window.paletteList.SOURCE_PALETTE_LABELS[sourceId] || sourceId) === paletteName;
+          });
+        return { harmonyHex, isFromAnySource: Boolean(allMatch), label, meta, paletteName, swatchName };
       });
       expect(allMatchState.isFromAnySource).toBe(true);
+      expect(allMatchState.label).toBe(`${allMatchState.paletteName} - ${allMatchState.swatchName}`);
+      expect(allMatchState.label).not.toContain("Closest");
+      expect(allMatchState.meta).toBe(allMatchState.harmonyHex);
       expect(pageErrors).toEqual([]);
     } finally {
       await workspaceV2CoverageReporter.stop(page);

tools/palette-manager-v2/controls/PaletteHarmonyControl.js

@@ -109,7 +109,10 @@ export class PaletteHarmonyControl {
     button.setAttribute("aria-pressed", String(index === this.app.getSelectedHarmonyColorIndex()));
     button.dataset.harmonyIndex = String(index);
     button.dataset.harmonyHex = normalizeHex(color.hex);
-    button.title = `${color.name}: ${normalizeHex(color.hex)}`;
+    button.dataset.harmonyLabel = color.displayName || color.name || "";
+    button.dataset.harmonyPalette = color.paletteName || "";
+    button.dataset.harmonySwatchName = color.swatchName || "";
+    button.title = `${color.displayName || color.name}: ${normalizeHex(color.hex)}`;
     button.addEventListener("click", () => {
       this.app.setSelectedHarmonyColorIndex(index);
     });
@@ -121,7 +124,7 @@ export class PaletteHarmonyControl {
 
     const text = this.document.createElement("span");
     text.className = "palette-manager-v2__harmony-text";
-    text.textContent = cleanSwatch.name || color.name || normalizeHex(color.hex);
+    text.textContent = color.displayName || cleanSwatch.name || color.name || normalizeHex(color.hex);
 
     const meta = this.document.createElement("span");
     meta.className = "palette-manager-v2__harmony-meta";

tools/palette-manager-v2/modules/PaletteManagerApp.js

@@ -118,6 +118,14 @@ function getRgbHexKey(hex) {
   return normalizeHex(hex).slice(0, 7);
 }
 
+function formatSourcePaletteName(value) {
+  const cleanValue = sanitizeText(value);
+  if (!cleanValue) {
+    return "";
+  }
+  return cleanValue.replace(/^([a-z])/, (letter) => letter.toUpperCase());
+}
+
 function formatDuplicateUserSwatchMessage(duplicateFields) {
   const parts = [];
   if (duplicateFields.symbol) {
@@ -538,22 +546,37 @@ export class PaletteManagerApp {
   }
 
   getCurrentSourcePaletteSwatches() {
-    return (this.sourcePalettes[this.state.sourcePaletteId] || [])
+    const sourceId = this.state.sourcePaletteId;
+    const paletteName = this.getHarmonySourcePaletteName(sourceId);
+    return (this.sourcePalettes[sourceId] || [])
       .map((swatch) => cloneSwatch({
         ...swatch,
-        source: swatch.source || this.state.sourcePaletteId
+        source: swatch.source || sourceId
+      }))
+      .map((swatch) => ({
+        ...swatch,
+        paletteId: sourceId,
+        paletteName
       }));
   }
 
   getAllSourcePaletteSwatches() {
     return Object.entries(this.sourcePalettes)
       .flatMap(([sourceId, swatches]) => (Array.isArray(swatches) ? swatches : [])
-        .map((swatch) => cloneSwatch({
-          ...swatch,
-          source: swatch.source || sourceId
+        .map((swatch) => ({
+          ...cloneSwatch({
+            ...swatch,
+            source: swatch.source || sourceId
+          }),
+          paletteId: sourceId,
+          paletteName: this.getHarmonySourcePaletteName(sourceId)
         })));
   }
 
+  getHarmonySourcePaletteName(sourceId) {
+    return formatSourcePaletteName(this.getSourcePaletteLabel(sourceId) || sourceId);
+  }
+
   getHarmonyColors() {
     const selectedSwatch = this.getSelectedSwatch();
     if (!selectedSwatch || !this.hexColorPattern.test(normalizeHex(selectedSwatch.hex))) {
@@ -564,21 +587,31 @@ export class PaletteManagerApp {
     const matchPalette = matchSource === "source-palette"
       ? this.getCurrentSourcePaletteSwatches()
       : (matchSource === "all-palettes" ? this.getAllSourcePaletteSwatches() : []);
-    return calculatedColors.map((color, index) => {
+    return calculatedColors.map((color) => {
       const matchedSwatch = matchPalette.length ? closestPaletteMatch(color.hex, matchPalette) : null;
       const cleanHex = normalizeHex(matchedSwatch?.hex || color.hex).slice(0, 7);
       const schemeLabel = findHarmonyScheme(this.state.harmonyScheme).label;
-      const matchLabel = matchedSwatch ? `Closest ${matchedSwatch.name}` : color.label;
+      const paletteName = matchedSwatch
+        ? (sanitizeText(matchedSwatch.paletteName) || this.getHarmonySourcePaletteName(matchedSwatch.paletteId || matchedSwatch.source))
+        : "";
+      const swatchName = sanitizeText(matchedSwatch?.name);
+      const calculationLabel = sanitizeText(color.label);
+      const displayName = matchedSwatch
+        ? `${paletteName} - ${swatchName}`
+        : `${schemeLabel} - ${calculationLabel || cleanHex}`;
       return {
         baseHex: normalizeHex(color.hex).slice(0, 7),
         hex: cleanHex,
-        name: `${schemeLabel} ${index + 1} - ${matchLabel}`,
+        name: displayName,
+        displayName,
+        paletteName,
+        swatchName,
         source: matchedSwatch?.source || findHarmonyMatchSource(this.state.harmonyMatchSource).label,
         swatch: cloneSwatch({
           symbol: "",
           hex: cleanHex,
-          name: `${schemeLabel} ${index + 1} - ${matchLabel}`,
-          source: matchedSwatch?.source || findHarmonyMatchSource(this.state.harmonyMatchSource).label,
+          name: displayName,
+          source: paletteName || findHarmonyMatchSource(this.state.harmonyMatchSource).label,
           tags: ["harmony"]
         })
       };

tools/palette-manager-v2/modules/paletteHarmonyUtils.js

@@ -246,7 +246,14 @@ export function closestPaletteMatch(targetHex, swatches) {
         + ((target.g - rgb.g) ** 2)
         + ((target.b - rgb.b) ** 2)
       );
-      return { distance, swatch: cloneSwatch(swatch) };
+      return {
+        distance,
+        swatch: {
+          ...cloneSwatch(swatch),
+          paletteId: sanitizeText(swatch?.paletteId),
+          paletteName: sanitizeText(swatch?.paletteName)
+        }
+      };
     })
     .filter(Boolean)
     .sort((left, right) => left.distance - right.distance)[0]?.swatch || null;