Refine Palette Manager harmony swatch display and names - PR_26140_061-refine-harmony-swatch-display-and-names

Author: DavidQ

docs/dev/reports/palette_harmony_swatch_display_report.md

@@ -0,0 +1,52 @@
+# Palette Harmony Swatch Display Report
+
+PR: PR_26140_061-refine-harmony-swatch-display-and-names
+
+## Summary
+
+Refined Palette Manager V2 harmony results so generated harmony colors render as swatch-only color tiles. The visible tile no longer contains label text, while title, ARIA label, and DOM readout metadata retain the palette name, swatch name, harmony label, and hex value for hover/focus discovery.
+
+## Changes
+
+- Updated `PaletteHarmonyControl` so each harmony result button renders as a color-only swatch tile with no visible child text.
+- Increased harmony swatch tiles to 40px by 40px and added focus-visible styling.
+- Preserved metadata/readout behavior through:
+  - `title` tooltip text
+  - `aria-label`
+  - `data-harmony-label`
+  - `data-harmony-palette`
+  - `data-harmony-swatch-name`
+  - `data-harmony-hex`
+- Kept the no-selection/empty harmony message readable by spanning it across the harmony grid.
+- Updated add behavior for closest-match colors so added user-palette swatches use only the matched swatch color name.
+  - Example: display metadata may be `Crayola008 - Black`, but the added user swatch name is `Black`.
+- Preserved calculated-mode names such as `Complementary - +180 deg`.
+
+## Validation Coverage
+
+The targeted Playwright test now confirms:
+
+- Harmony swatches are 40px by 40px.
+- Harmony swatches have no visible text content.
+- Hover/focus metadata contains palette name, swatch name, and hex for matched colors.
+- Calculated mode keeps useful generated names.
+- Add Selected creates a matched `Black` swatch without a palette-name prefix.
+- Add All applies the same closest-match naming rule to all newly added matched colors.
+- Existing Add Selected/Add All duplicate behavior is preserved.
+
+## Validation
+
+Passed:
+
+- `node --check tools/palette-manager-v2/controls/PaletteHarmonyControl.js; node --check tools/palette-manager-v2/modules/PaletteManagerApp.js; node --check tools/palette-manager-v2/modules/paletteHarmonyUtils.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 warnings for the modified Playwright spec and Palette Manager CSS only)
+
+## Scope Notes
+
+- Harmony calculations were not changed.
+- Closest-match calculation behavior was not changed.
+- No sample JSON was touched.
+- Full samples smoke test was not run, per PR instruction.
+- No commit was made by Codex.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -8103,12 +8103,20 @@ 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");
+      const calculatedHarmonyTile = page.locator("#harmonyColorList [data-harmony-index='0']");
+      await expect(calculatedHarmonyTile).toHaveAttribute("data-harmony-hex", "#00FFFF");
+      await expect(calculatedHarmonyTile).toHaveAttribute("data-harmony-label", "Complementary - +180 deg");
+      await expect(calculatedHarmonyTile).toHaveAttribute("title", /Name: Complementary - \+180 deg[\s\S]*Hex: #00FFFF/);
+      await expect(calculatedHarmonyTile).toHaveText("");
+      const calculatedHarmonyTileBox = await calculatedHarmonyTile.boundingBox();
+      expect(Math.round(calculatedHarmonyTileBox.width)).toBe(40);
+      expect(Math.round(calculatedHarmonyTileBox.height)).toBe(40);
       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/);
+      await expect.poll(async () => {
+        return page.evaluate(() => window.paletteManagerV2App.getPaletteValue().swatches.at(-1).name);
+      }).toBe("Complementary - +180 deg");
 
       await page.locator('#userSwatchList [aria-label="Edit Harmony Base Red"]').click();
       await expect(page.locator("#harmonyColorList [data-harmony-index='0']")).toHaveAttribute("data-harmony-hex", "#00FFFF");
@@ -8134,18 +8142,24 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         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 label = harmonyButton.dataset.harmonyLabel;
+        const readout = harmonyButton.getAttribute("title");
+        const ariaLabel = harmonyButton.getAttribute("aria-label");
+        const textContent = harmonyButton.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 };
+        return { ariaLabel, expectedPaletteName, harmonyHex, isFromCurrentSource: Boolean(sourceMatch), label, paletteName, readout, swatchName, textContent };
       });
       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);
+      expect(sourceMatchState.textContent).toBe("");
+      expect(sourceMatchState.readout).toContain(`Palette: ${sourceMatchState.expectedPaletteName}`);
+      expect(sourceMatchState.readout).toContain(`Name: ${sourceMatchState.swatchName}`);
+      expect(sourceMatchState.readout).toContain(`Hex: ${sourceMatchState.harmonyHex}`);
+      expect(sourceMatchState.ariaLabel).toContain(sourceMatchState.harmonyHex);
 
       await page.locator("#harmonyMatchSourceSelect").selectOption("all-palettes");
       const allMatchState = await page.evaluate(() => {
@@ -8154,21 +8168,78 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         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 label = harmonyButton.dataset.harmonyLabel;
+        const readout = harmonyButton.getAttribute("title");
+        const textContent = harmonyButton.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 };
+        return { harmonyHex, isFromAnySource: Boolean(allMatch), label, paletteName, readout, swatchName, textContent };
       });
       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(allMatchState.textContent).toBe("");
+      expect(allMatchState.readout).toContain(`Palette: ${allMatchState.paletteName}`);
+      expect(allMatchState.readout).toContain(`Name: ${allMatchState.swatchName}`);
+      expect(allMatchState.readout).toContain(`Hex: ${allMatchState.harmonyHex}`);
+
+      await page.locator('#userSwatchList [aria-label="Edit Harmony Base Red"]').click();
+      await page.locator("#harmonyMatchSourceSelect").selectOption("source-palette");
+      await page.locator("#harmonySchemeSelect").selectOption("achromatic");
+      const matchedBlackTile = page.locator("#harmonyColorList [data-harmony-index='1']");
+      await expect(matchedBlackTile).toHaveAttribute("data-harmony-swatch-name", "Black");
+      await expect(matchedBlackTile).toHaveText("");
+      await expect(matchedBlackTile).toHaveAttribute("aria-label", /Palette: .*Name: Black.*Hex:/);
+      const matchedBlackTileBox = await matchedBlackTile.boundingBox();
+      expect(Math.round(matchedBlackTileBox.width)).toBe(40);
+      expect(Math.round(matchedBlackTileBox.height)).toBe(40);
+      await matchedBlackTile.focus();
+      await expect(matchedBlackTile).toBeFocused();
+      await matchedBlackTile.click();
+      const matchedBlackState = await matchedBlackTile.evaluate((button) => ({
+        hex: button.dataset.harmonyHex,
+        label: button.dataset.harmonyLabel,
+        paletteName: button.dataset.harmonyPalette,
+        swatchName: button.dataset.harmonySwatchName
+      }));
+      await page.locator("#addSelectedHarmonyButton").click();
+      await expect(page.locator("#userPaletteCount")).toHaveText("5 user swatches");
+      const addedBlackSwatch = await page.evaluate(() => window.paletteManagerV2App.getPaletteValue().swatches.at(-1));
+      expect(addedBlackSwatch.hex).toBe(matchedBlackState.hex);
+      expect(addedBlackSwatch.name).toBe("Black");
+      expect(addedBlackSwatch.name).toBe(matchedBlackState.swatchName);
+      expect(addedBlackSwatch.name).not.toContain(matchedBlackState.paletteName);
+      expect(matchedBlackState.label).toBe(`${matchedBlackState.paletteName} - Black`);
+
+      await page.locator('#userSwatchList [aria-label="Edit Harmony Base Red"]').click();
+      await page.locator("#harmonyMatchSourceSelect").selectOption("source-palette");
+      await page.locator("#harmonySchemeSelect").selectOption("achromatic");
+      const sourceAchromaticMatches = await page.evaluate(() => {
+        return Array.from(document.querySelectorAll("#harmonyColorList [data-harmony-index]"))
+          .map((button) => ({
+            hex: button.dataset.harmonyHex,
+            paletteName: button.dataset.harmonyPalette,
+            swatchName: button.dataset.harmonySwatchName
+          }));
+      });
+      const beforeAddAllCount = await page.evaluate(() => window.paletteManagerV2App.getPaletteValue().swatches.length);
+      await page.locator("#addAllHarmonyButton").click();
+      await expect(page.locator("#paletteStatus")).toHaveText(/OK Added \d+ harmony colors\. Skipped \d+ duplicates\./);
+      const addAllNamingState = await page.evaluate((beforeCount) => {
+        return window.paletteManagerV2App.getPaletteValue().swatches.slice(beforeCount);
+      }, beforeAddAllCount);
+      expect(addAllNamingState.length).toBeGreaterThan(0);
+      addAllNamingState.forEach((swatch) => {
+        const match = sourceAchromaticMatches.find((candidate) => candidate.hex === swatch.hex);
+        expect(match).toBeTruthy();
+        expect(swatch.name).toBe(match.swatchName);
+        expect(swatch.name).not.toContain(match.paletteName);
+      });
       expect(pageErrors).toEqual([]);
     } finally {
       await workspaceV2CoverageReporter.stop(page);

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

@@ -1,4 +1,22 @@
-import { cloneSwatch, normalizeHex } from "../modules/paletteUtils.js";
+import { normalizeHex } from "../modules/paletteUtils.js";
+
+function getHarmonyDisplayName(color, hex) {
+  return color.displayName || color.name || hex;
+}
+
+function createHarmonyReadout(color) {
+  const hex = normalizeHex(color.hex);
+  const lines = [];
+  if (color.paletteName) {
+    lines.push(`Palette: ${color.paletteName}`);
+  }
+  lines.push(`Name: ${color.swatchName || color.name || color.displayName || hex}`);
+  lines.push(`Hex: ${hex}`);
+  if (color.displayName && color.displayName !== color.name && color.displayName !== color.swatchName) {
+    lines.push(`Harmony: ${color.displayName}`);
+  }
+  return lines.join("\n");
+}
 
 export class PaletteHarmonyControl {
   constructor({ documentRef, refs, app }) {
@@ -101,36 +119,25 @@ export class PaletteHarmonyControl {
   }
 
   createHarmonyColorButton(color, index) {
-    const cleanSwatch = cloneSwatch(color.swatch || {});
+    const hex = normalizeHex(color.hex);
+    const displayName = getHarmonyDisplayName(color, hex);
+    const readout = createHarmonyReadout(color);
     const button = this.document.createElement("button");
     button.type = "button";
     button.className = "palette-manager-v2__harmony-color";
     button.classList.toggle("is-selected", index === this.app.getSelectedHarmonyColorIndex());
     button.setAttribute("aria-pressed", String(index === this.app.getSelectedHarmonyColorIndex()));
+    button.setAttribute("aria-label", readout.replace(/\n/g, ". "));
     button.dataset.harmonyIndex = String(index);
-    button.dataset.harmonyHex = normalizeHex(color.hex);
-    button.dataset.harmonyLabel = color.displayName || color.name || "";
+    button.dataset.harmonyHex = hex;
+    button.dataset.harmonyLabel = displayName;
     button.dataset.harmonyPalette = color.paletteName || "";
     button.dataset.harmonySwatchName = color.swatchName || "";
-    button.title = `${color.displayName || color.name}: ${normalizeHex(color.hex)}`;
+    button.title = readout;
+    button.style.background = hex;
     button.addEventListener("click", () => {
       this.app.setSelectedHarmonyColorIndex(index);
     });
-
-    const chip = this.document.createElement("span");
-    chip.className = "palette-manager-v2__harmony-chip";
-    chip.style.background = normalizeHex(color.hex);
-    chip.setAttribute("aria-hidden", "true");
-
-    const text = this.document.createElement("span");
-    text.className = "palette-manager-v2__harmony-text";
-    text.textContent = color.displayName || cleanSwatch.name || color.name || normalizeHex(color.hex);
-
-    const meta = this.document.createElement("span");
-    meta.className = "palette-manager-v2__harmony-meta";
-    meta.textContent = normalizeHex(color.hex);
-
-    button.append(chip, text, meta);
     return button;
   }
 }

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

@@ -599,18 +599,23 @@ export class PaletteManagerApp {
       const displayName = matchedSwatch
         ? `${paletteName} - ${swatchName}`
         : `${schemeLabel} - ${calculationLabel || cleanHex}`;
+      const addName = matchedSwatch
+        ? (swatchName || cleanHex)
+        : displayName;
       return {
         baseHex: normalizeHex(color.hex).slice(0, 7),
         hex: cleanHex,
-        name: displayName,
+        name: addName,
+        addName,
+        addNameIsExact: Boolean(matchedSwatch),
         displayName,
         paletteName,
         swatchName,
         source: matchedSwatch?.source || findHarmonyMatchSource(this.state.harmonyMatchSource).label,
         swatch: cloneSwatch({
           symbol: "",
           hex: cleanHex,
-          name: displayName,
+          name: addName,
           source: paletteName || findHarmonyMatchSource(this.state.harmonyMatchSource).label,
           tags: ["harmony"]
         })
@@ -1234,10 +1239,13 @@ export class PaletteManagerApp {
   }
 
   harmonyColorToSwatch(color) {
+    const colorName = color?.addNameIsExact
+      ? sanitizeText(color?.addName || color?.name)
+      : this.getUniqueHarmonyName(color?.addName || color?.name);
     return cloneSwatch({
       symbol: nextHarmonySymbol(this.state.userSwatches),
       hex: normalizeHex(color?.hex).slice(0, 7),
-      name: this.getUniqueHarmonyName(color?.name),
+      name: colorName,
       source: sanitizeText(color?.source) || "Harmony",
       tags: ["harmony"]
     });

tools/palette-manager-v2/paletteManagerV2.css

@@ -745,34 +745,40 @@ body.tools-platform-surface :is(input, select, textarea):hover {
 .palette-manager-v2__harmony-list {
   min-height: 52px;
   display: grid;
+  grid-template-columns: repeat(auto-fill, 40px);
   gap: 8px;
   border: 1px solid var(--pm-line);
   border-radius: 8px;
   background: var(--pm-surface-strong);
   padding: 8px;
 }
 
+.palette-manager-v2__harmony-list > .palette-manager-v2__meta {
+  grid-column: 1 / -1;
+}
+
 .palette-manager-v2__harmony-color {
-  width: 100%;
-  min-width: 0;
-  display: grid;
-  grid-template-columns: 30px minmax(0, 1fr);
-  gap: 4px 8px;
-  align-items: center;
+  width: 40px;
+  min-width: 40px;
+  height: 40px;
   border: 1px solid var(--pm-line);
   border-radius: 8px;
   background: rgba(0, 0, 0, 0.2);
   color: inherit;
   cursor: pointer;
-  padding: 6px;
-  text-align: left;
+  padding: 0;
 }
 
 .palette-manager-v2__harmony-color.is-selected {
   border-color: var(--pm-accent);
   box-shadow: inset 0 0 0 1px var(--pm-accent);
 }
 
+.palette-manager-v2__harmony-color:focus-visible {
+  outline: 2px solid var(--pm-accent);
+  outline-offset: 2px;
+}
+
 .palette-manager-v2__harmony-chip {
   grid-row: span 2;
   width: 30px;