Fix Colors picker selection metadata layout and disabled swatches - PR_26159_026-colors-picker-metadata-layout

Author: ToolboxAid

docs_build/dev/reports/colors-picker-metadata-layout-report.md

@@ -0,0 +1,60 @@
+# PR_26159_026 Colors Picker Metadata Layout Report
+
+## Executive Summary
+PASS. The Colors picker regression is fixed and packaged. Picker swatches are selectable, selected/pinned swatches retain the generator settings that created them, metadata tooltips are present for generated and selected swatches, and the requested layout/control cleanup is implemented without page-local CSS, inline scripts, inline styles, or inline handlers.
+
+## Requirement Checklist
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Read project instructions first | PASS | Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` before implementation. |
+| Use PR_26159_024 and PR_26159_025 as base context | PASS | Changes build on existing Colors curated palette/generator and restored selection/tag/sort behavior in `toolbox/colors/colors.js`, `toolbox/colors/index.html`, and `tests/playwright/tools/PaletteToolMockRepository.spec.mjs`. |
+| Every visible picker swatch selectable unless documented disabled reason exists | PASS | `renderPaletteGeneratorPreview` renders enabled picker buttons; Playwright clicks all visible picker swatches and verifies selection count. |
+| Remove red/not-allowed mouse behavior from selectable picker swatches | PASS | No live `not-allowed` cursor code remains in Colors files; Playwright asserts picker swatch cursors are not `not-allowed`. |
+| Store picker settings when picker swatch is selected or pinned | PASS | `currentPickerSettings`, `generatedSwatchFromTile`, and repository `clonePickerSettings` preserve Theme Collection, Palette Type, Variant, Colors, Steps, Contrast, Saturation, Hue Shift, Sort field/direction, Active tags, and Swatch size. |
+| Add way to return to selected/pinned swatch picker settings | PASS | Added `data-palette-restore-picker-settings` button and `applyPickerSettings`; Playwright verifies changing settings away and restoring from selected swatch. |
+| Hover tooltip for picker/selected/pinned swatches includes requested metadata | PASS | `pickerTooltipText` and `swatchTooltipText` include color, name, Theme Collection, Palette Type, Variant, Colors, Steps, Contrast, Saturation, Hue Shift, and tags; Playwright checks generated/selected title metadata. |
+| Add deterministic generated color names when curated name is missing | PASS | `colorFamilyName` and `generatorSwatchName` derive stable names from generator settings, color family, row, and column. |
+| Rename center section Selected Swatches to Palette | PASS | Center H2 in `toolbox/colors/index.html` is now `Palette`; Playwright asserts the heading. |
+| Move pinned/selected swatches and controls into top accordion named Selected Swatches | PASS | Top accordion remains `Selected Swatches` and contains active palette controls/list; generated preview grid moved outside that accordion. |
+| Put Undo and Redo side by side | PASS | Undo/Redo are wrapped in an `action-group`; Playwright compares their positions. |
+| Remove Symbol UI and Symbol-specific code | PASS | Visible Symbol fields/hooks removed from `toolbox/colors/index.html` and UI JS; repository keeps only hidden compatibility key generation for existing palette contracts. Static scan found no live Symbol UI hooks. |
+| Theme Collection, Palette Type, and Variant side by side | PASS | Selector controls now render in a 3-column Theme V2 grid; Playwright verifies matching row positions. |
+| Remove Variant options 64/128/256 colors | PASS | `PALETTE_VARIANTS` and numeric variant counts exclude 64/128/256; Playwright and static scan verify options are absent. |
+| Keep requested smaller Variant options | PASS | Full, 32, 16, 8, 4, High Contrast, Color Blind Safe, Grayscale, Print Friendly, Day, Night, Dawn, Dusk, Winter, and Summer remain in `PALETTE_VARIANTS`. |
+| Contrast, Saturation, Hue Shift side by side with sliders below labels | PASS | Slider controls now use a 3-column Theme V2 grid with each range input inside its label group; Playwright verifies same row placement. |
+| Restore sorting display/control order | PASS | Sort/size controls render as Hue ^, Sat, Brit, Name, Tag, Small, Medium, Large; Playwright asserts exact order. |
+| Preserve tag checkbox behavior | PASS | Tag filtering remains in `renderUserPalette`; Playwright checks tag checkbox filtering/marking behavior in the batch tag test. |
+| Preserve no spacing between picker grid swatches | PASS | Existing generated grid gap-free styling/behavior preserved; Playwright validates picker interactions after layout changes. |
+| Preserve Admin unfiltered toolbox list and non-admin filtered list | PASS | `ToolboxRoutePages.spec.mjs` passed, including Admin all-tools and creator filtering. |
+| Preserve Colors on toolbox/index.html | PASS | `ToolboxRoutePages.spec.mjs` passed for toolbox route registration. |
+| No console errors | PASS | Targeted Palette Tool Playwright lane passed without console error failures. |
+| Playwright impacted | PASS | Targeted Playwright lanes were run and passed. |
+| Produce repo-structured ZIP | PASS | Created under `tmp/PR_26159_026-colors-picker-metadata-layout_delta.zip`. |
+
+## Validation Evidence
+| Lane | Status | Evidence |
+| --- | --- | --- |
+| Changed-file syntax | PASS | `node --check toolbox/colors/colors.js`; `node --check src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js`; `node --check tests/playwright/tools/PaletteToolMockRepository.spec.mjs`. |
+| Diff/static validation | PASS | `git diff --check` passed. Git reported LF/CRLF warnings only. |
+| Symbol/variant/cursor static scans | PASS | `rg` found no live Symbol UI hooks, no live 64/128/256 variant options, and no live not-allowed swatch behavior in active Colors files. |
+| Palette Tool runtime/UI lane | PASS | `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs --timeout=180000` -> 6 passed. |
+| Toolbox registration/navigation lane | PASS | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --timeout=180000` -> 2 passed. |
+
+## Skipped Lanes
+| Lane | Reason |
+| --- | --- |
+| Full samples validation | Skipped by request. This PR only touches Colors tool UI/runtime, the palette workspace repository compatibility path, and targeted Colors/toolbox Playwright coverage. |
+| Broad workspace smoke | Not run because no shared sample loader/framework or workspace shell code changed. Targeted toolbox route validation covered Colors visibility and role filtering. |
+
+## Changed Files
+- `toolbox/colors/index.html`
+- `toolbox/colors/colors.js`
+- `src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js`
+- `tests/playwright/tools/PaletteToolMockRepository.spec.mjs`
+- `docs_build/dev/reports/colors-picker-metadata-layout-report.md`
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+
+## Notes
+- The visible Symbol UI and Symbol-specific interactions were removed. A hidden generated palette key remains inside the repository because the existing palette persistence contract still needs a unique swatch key for updates, deletes, and legacy payload validation.
+- The picker settings metadata is copied into selected/pinned swatches so restoration and tooltip metadata survive normal repository cloning and UI rerenders.

src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js

@@ -55,14 +55,40 @@ const SOURCE_ID_RENAMES = Object.freeze({
 });
 const SYMBOL_CANDIDATES = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@$%^&*()-+=[]{};:,.?";
 
-function cloneSwatch(swatch) {
+function clonePickerSettings(settings) {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    return null;
+  }
   return {
+    activeTags: Array.isArray(settings.activeTags) ? [...settings.activeTags] : [],
+    colors: settings.colors,
+    contrast: settings.contrast,
+    hueShift: settings.hueShift,
+    paletteType: settings.paletteType,
+    saturation: settings.saturation,
+    sortDirection: settings.sortDirection,
+    sortField: settings.sortField,
+    steps: settings.steps,
+    swatchSize: settings.swatchSize,
+    themeCollection: settings.themeCollection,
+    variant: settings.variant,
+    variantValue: settings.variantValue
+  };
+}
+
+function cloneSwatch(swatch) {
+  const cloned = {
     symbol: swatch.symbol,
     hex: swatch.hex,
     name: swatch.name,
     source: swatch.source,
     tags: [...swatch.tags]
   };
+  const pickerSettings = clonePickerSettings(swatch.pickerSettings);
+  if (pickerSettings) {
+    cloned.pickerSettings = pickerSettings;
+  }
+  return cloned;
 }
 
 function cloneSourcePaletteRow(row) {
@@ -217,25 +243,28 @@ export function normalizePaletteSwatchInput(input = {}, options = {}) {
   const hex = normalizeHex(source.hex);
   const name = normalizeText(source.name);
   const tags = normalizeTags(source.tags);
+  const pickerSettings = clonePickerSettings(source.pickerSettings);
 
-  return {
+  const swatch = {
     symbol,
     hex,
     name,
     source: normalizeSource(source.source || options.source),
     tags
   };
+  if (pickerSettings) {
+    swatch.pickerSettings = pickerSettings;
+  }
+  return swatch;
 }
 
 export function validatePaletteSwatchInput(input = {}, existingSwatches = [], options = {}) {
   const swatch = normalizePaletteSwatchInput(input, options);
-  const excludeSymbol = normalizeText(options.excludeSymbol);
+  const excludeSymbol = normalizeText(options.excludeSymbol || options.excludeKey);
   const issues = [];
 
-  if (!swatch.symbol) {
-    issues.push(createIssue("symbol", "Symbol", "Enter a symbol for this swatch."));
-  } else if (!isOneCharacter(swatch.symbol)) {
-    issues.push(createIssue("symbol", "Symbol", "Symbol must be exactly one character."));
+  if (options.requireSymbol && !swatch.symbol) {
+    issues.push(createIssue("symbol", "Palette Key", "Palette key is missing."));
   }
 
   if (!swatch.hex) {
@@ -303,7 +332,7 @@ export function validatePaletteWorkspacePayload(payload = {}) {
   const normalizedSwatches = [];
   swatches.forEach((candidate, index) => {
     const normalized = normalizePaletteSwatchInput(candidate);
-    const validation = validatePaletteSwatchInput(normalized, normalizedSwatches);
+    const validation = validatePaletteSwatchInput(normalized, normalizedSwatches, { requireSymbol: true });
     if (validation.issues.length) {
       validation.issues.forEach((issue) => {
         issues.push({
@@ -569,7 +598,17 @@ function nextAvailableSymbol(existingSwatches, seedText = "") {
   const used = new Set(existingSwatches.map((swatch) => swatch.symbol));
   const seedCandidates = Array.from(normalizeText(seedText).toUpperCase().replace(/[^A-Z0-9]/g, ""));
   const candidates = [...seedCandidates, ...Array.from(SYMBOL_CANDIDATES)];
-  return candidates.find((candidate) => !used.has(candidate)) || "";
+  const compactCandidate = candidates.find((candidate) => !used.has(candidate));
+  if (compactCandidate) {
+    return compactCandidate;
+  }
+  let index = existingSwatches.length + 1;
+  let candidate = `swatch-${index}`;
+  while (used.has(candidate)) {
+    index += 1;
+    candidate = `swatch-${index}`;
+  }
+  return candidate;
 }
 
 function generatedHarmonyNameRoot(name) {
@@ -652,6 +691,7 @@ export function createProjectWorkspacePaletteRepository(options = {}) {
       .map((row) => ({
         hex: row.hex,
         name: row.name,
+        pickerSettings: clonePickerSettings(row.pickerSettings) || undefined,
         source: row.source,
         symbol: row.symbol,
         tags: [...row.tags]
@@ -681,6 +721,7 @@ export function createProjectWorkspacePaletteRepository(options = {}) {
         hex: swatch.hex,
         id: `${projectId}-palette-color-${index + 1}`,
         name: swatch.name,
+        pickerSettings: clonePickerSettings(swatch.pickerSettings) || undefined,
         projectId,
         source: swatch.source,
         symbol: swatch.symbol,
@@ -770,7 +811,11 @@ export function createProjectWorkspacePaletteRepository(options = {}) {
   function saveSwatch(input = {}, optionsForSave = {}) {
     const projectId = activeProjectId();
     const swatches = getActiveSwatches();
-    const validation = validatePaletteSwatchInput(input, swatches, {
+    const inputWithKey = {
+      ...input,
+      symbol: normalizeText(input.symbol) || optionsForSave.excludeSymbol || nextAvailableSymbol(swatches, `${input.name || ""} ${input.hex || ""}`)
+    };
+    const validation = validatePaletteSwatchInput(inputWithKey, swatches, {
       excludeSymbol: optionsForSave.excludeSymbol,
       source: optionsForSave.source || PALETTE_SOURCE_USER
     });
@@ -833,6 +878,7 @@ export function createProjectWorkspacePaletteRepository(options = {}) {
     return saveSwatch(
       {
         ...input,
+        symbol: selectedSwatch.symbol,
         source: selectedSwatch.source || PALETTE_SOURCE_USER,
         tags: [...selectedSwatch.tags]
       },