Improve MIDI Studio V2 Song Sheet and Instrument Settings responsive field layouts - PR_26146_064-midi-studio-v2-field-grid-layouts

Author: ToolboxAid

docs/dev/reports/PR_26146_064-midi-studio-v2-field-grid-layouts_validation.md

@@ -0,0 +1,56 @@
+# PR_26146_064 MIDI Studio V2 Field Grid Layouts Validation
+
+## Scope
+
+- Continued from `PR_26146_063`.
+- Refined Song Setup > Song Sheet into responsive editable and read-only/display field grids.
+- Preserved Song Sheet structure-only ownership for Sections and Loop sections.
+- Added shared MIDI Studio field-card states for editable, read-only, and unwired controls.
+- Refined Instruments > Instrument Settings into a responsive bucket/field grid.
+- Added a read-only derived Audible preview display field in Instrument Settings.
+- Preserved Instruments as the SSoT owner for GM Type, GM Instrument/Patch, volume, and related configuration.
+- Preserved Song Details Notes full-width bottom row, Octave Timeline Instruments accordion, selectedInstrumentId sync, canvas-backed Octave Timeline, Play/Stop, manifest import, multiple songs, Export tab ownership, and launch-specific NAV.
+
+## Validation
+
+PASS - `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+
+PASS - `node --check tools/midi-studio-v2/js/controls/SongSheetControl.js`
+
+PASS - `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+
+PASS - HTML restriction check found no inline script blocks, style blocks, inline event handlers, or inline style attributes in `tools/midi-studio-v2/index.html`.
+
+PASS - `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright -g "PR064"`
+
+Result: 1 passed.
+
+PASS - `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright -g "PR064|PR063|PR062|PR061|PR060"`
+
+Result: 5 passed.
+
+PASS - `git diff --check`
+
+PASS - Playwright V8 coverage report generated at `docs/dev/reports/playwright_v8_coverage_report.txt`.
+
+PASS - Changed runtime JS coverage guardrail generated at `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+
+## Playwright Evidence
+
+- Song Sheet editable fields render in a responsive grid with multiple columns when width is available.
+- Song Sheet editable fields use editable field-card styling and remain enabled.
+- Song Sheet derived fields render in a responsive read-only/display grid with no editable controls.
+- Song Sheet derived fields expose read-only state.
+- Song Sheet Sections and Loop sections continue updating the canonical song model.
+- Instrument Settings buckets render in a responsive grid with multiple columns when width is available.
+- Instrument Settings fields inside buckets render in responsive grids.
+- Instrument editable fields use editable styling and remain enabled.
+- Instrument derived Audible preview uses read-only/display styling.
+- Future instrument controls remain red/unwired with tooltip/status.
+- Instrument configuration edits continue updating canonical instrument data.
+- Play and Stop still transition correctly.
+
+## Samples Decision
+
+SKIP - Full samples smoke test was not run per PR instruction. This PR is scoped to MIDI Studio V2 form layout and targeted tool behavior.
+

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -3051,6 +3051,134 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("keeps PR064 Song Sheet and Instrument Settings fields in responsive editable/read-only grids", async ({ page }) => {
+    await page.setViewportSize({ width: 1600, height: 900 });
+    const server = await openMidiStudioForImport(page);
+    try {
+      await page.locator("#toolImportManifestInput").setInputFiles(uatManifestPath);
+      await selectMidiStudioTab(page, "song-setup");
+
+      await page.locator("#songSheetSectionsInput").fill("intro: C F\nbridge: Dm G\nloop: F G C C");
+      await page.locator("#songSheetLoopSectionsInput").fill("bridge, loop");
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='bars'] dd")).toHaveText("8");
+      const songSheetLayout = await page.locator("#songSheetContent").evaluate((content) => {
+        const columnCount = (element) => getComputedStyle(element).gridTemplateColumns.split(" ").filter(Boolean).length;
+        const fieldRows = (fields) => new Set(fields.map((field) => Math.round(field.getBoundingClientRect().top))).size;
+        const editableGrid = content.querySelector(".midi-studio-v2__song-sheet-grid");
+        const summary = content.querySelector("#songSheetSummary");
+        const editableFields = Array.from(editableGrid.querySelectorAll("[data-midi-studio-field-state='editable']"));
+        const readonlyFields = Array.from(summary.querySelectorAll("[data-midi-studio-field-state='readonly']"));
+        return {
+          editableBackgrounds: editableFields.map((field) => getComputedStyle(field).backgroundColor),
+          editableBorderStyles: editableFields.map((field) => getComputedStyle(field).borderStyle),
+          editableColumns: columnCount(editableGrid),
+          editableControls: editableGrid.querySelectorAll("textarea:not([readonly]):not([disabled])").length,
+          editableFieldRows: fieldRows(editableFields),
+          readonlyAria: readonlyFields.every((field) => field.getAttribute("aria-readonly") === "true"),
+          readonlyBorderStyles: readonlyFields.map((field) => getComputedStyle(field).borderStyle),
+          readonlyControls: summary.querySelectorAll("input, select, textarea").length,
+          readonlyFields: readonlyFields.length,
+          summaryColumns: columnCount(summary),
+          summaryFieldRows: fieldRows(readonlyFields)
+        };
+      });
+      expect(songSheetLayout.editableColumns).toBeGreaterThan(1);
+      expect(songSheetLayout.summaryColumns).toBeGreaterThan(1);
+      expect(songSheetLayout.editableFieldRows).toBe(1);
+      expect(songSheetLayout.summaryFieldRows).toBeLessThan(songSheetLayout.readonlyFields);
+      expect(songSheetLayout.editableControls).toBe(2);
+      expect(songSheetLayout.readonlyControls).toBe(0);
+      expect(songSheetLayout.readonlyFields).toBeGreaterThanOrEqual(6);
+      expect(songSheetLayout.readonlyAria).toBe(true);
+      expect(songSheetLayout.editableBorderStyles.every((style) => style === "solid")).toBe(true);
+      expect(songSheetLayout.readonlyBorderStyles.every((style) => style === "dashed")).toBe(true);
+      expect(new Set(songSheetLayout.editableBackgrounds).size).toBe(1);
+
+      const songSheetCanonical = await page.evaluate(() => window.__midiStudioV2App.selectedSong().studioArrangement.songSheet);
+      expect(songSheetCanonical).toEqual({
+        loopSections: "bridge, loop",
+        sections: "intro: C F\nbridge: Dm G\nloop: F G C C"
+      });
+
+      await selectMidiStudioTab(page, "instruments");
+      const editor = page.locator("#selectedInstrumentEditor");
+      await expect(editor).toHaveAttribute("data-selected-instrument-id", "lead");
+      const instrumentLayout = await editor.evaluate((instrumentEditor) => {
+        const columnCount = (element) => getComputedStyle(element).gridTemplateColumns.split(" ").filter(Boolean).length;
+        const buckets = Array.from(instrumentEditor.querySelectorAll(".midi-studio-v2__instrument-editor-bucket"));
+        const bucketRows = new Set(buckets.map((bucket) => Math.round(bucket.getBoundingClientRect().top))).size;
+        const identityBucket = instrumentEditor.querySelector("[data-instrument-editor-bucket='identity']");
+        const editableFields = Array.from(instrumentEditor.querySelectorAll("[data-midi-studio-field-state='editable']"));
+        const readonlyFields = Array.from(instrumentEditor.querySelectorAll("[data-midi-studio-field-state='readonly']"));
+        const unwiredFields = Array.from(instrumentEditor.querySelectorAll("[data-midi-studio-field-state='unwired']"));
+        const readonlyOutput = instrumentEditor.querySelector("[data-instrument-derived-field='audible-preview']");
+        return {
+          bucketRows,
+          buckets: buckets.length,
+          editorColumns: columnCount(instrumentEditor),
+          editableBorderStyles: editableFields.map((field) => getComputedStyle(field).borderStyle),
+          editableControls: editableFields.map((field) => field.querySelector("input, select, textarea")?.disabled === false),
+          identityColumns: columnCount(identityBucket),
+          readonlyBorderStyles: readonlyFields.map((field) => getComputedStyle(field).borderStyle),
+          readonlyOutputText: readonlyOutput?.textContent || "",
+          readonlyOutputs: readonlyFields.filter((field) => field.querySelector("output[aria-readonly='true']")).length,
+          unwiredControls: unwiredFields.map((field) => {
+            const control = field.querySelector("[data-midi-studio-future-control]");
+            return {
+              borderStyle: getComputedStyle(field).borderStyle,
+              controlClass: control?.classList.contains("midi-studio-v2__unwired-control") || false,
+              disabled: control?.disabled || false,
+              status: control?.dataset.midiStudioUnwired || "",
+              title: control?.title || ""
+            };
+          }),
+          unwiredFields: unwiredFields.length
+        };
+      });
+      expect(instrumentLayout.editorColumns).toBeGreaterThan(1);
+      expect(instrumentLayout.identityColumns).toBeGreaterThan(1);
+      expect(instrumentLayout.bucketRows).toBeLessThan(instrumentLayout.buckets);
+      expect(instrumentLayout.editableControls.every(Boolean)).toBe(true);
+      expect(instrumentLayout.editableBorderStyles.every((style) => style === "solid")).toBe(true);
+      expect(instrumentLayout.readonlyOutputs).toBeGreaterThanOrEqual(1);
+      expect(instrumentLayout.readonlyOutputText).toContain("Lead");
+      expect(instrumentLayout.readonlyBorderStyles.every((style) => style === "dashed")).toBe(true);
+      expect(instrumentLayout.unwiredFields).toBeGreaterThanOrEqual(8);
+      expect(instrumentLayout.unwiredControls.every((control) => control.borderStyle === "solid" && control.controlClass && control.disabled && control.status === "not-implemented" && control.title.includes("Not implemented:"))).toBe(true);
+
+      await page.locator("#previewDisplayNameLeadInput").fill("Lead Grid Voice");
+      await setInputValue(page, "#previewVolumeLeadInput", "0.75");
+      await instrumentTypeSelect(page, "lead").selectOption("Bass");
+      await instrumentSelect(page, "lead").selectOption("gm-electric-bass-finger");
+      await expect(editor.locator("[data-instrument-derived-field='audible-preview']")).toHaveText("Synth Bass 1");
+      expect(await page.evaluate(() => {
+        const settings = window.__midiStudioV2App.selectedSong().studioArrangement.previewLaneSettings;
+        return {
+          displayName: settings.displayNames.lead,
+          instrument: settings.instruments.lead,
+          instrumentType: settings.instrumentTypes.lead,
+          volume: settings.volumes.lead
+        };
+      })).toEqual({
+        displayName: "Lead Grid Voice",
+        instrument: "gm-electric-bass-finger",
+        instrumentType: "Bass",
+        volume: 0.75
+      });
+
+      await selectMidiStudioTab(page, "studio");
+      await page.locator("#playButton").click();
+      await expect(page.locator("#playButton")).toBeDisabled();
+      await expect(page.locator("#stopButton")).toBeEnabled();
+      await page.locator("#stopButton").click();
+      await expect(page.locator("#stopButton")).toBeDisabled();
+      await expect(page.locator("#playButton")).toBeEnabled();
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("derives primary song, instrument, grid, playback, and diagnostics views from the canonical selected song", async ({ page }) => {
     const server = await openMidiStudioForImport(page);
     try {

tools/midi-studio-v2/index.html

@@ -261,11 +261,11 @@ <h3 id="exportStatusHeading">Export Status</h3>
           </button>
           <div id="songSheetContent" class="accordion-v2__content midi-studio-v2__stack midi-studio-v2__song-sheet-panel" aria-label="Song Sheet">
             <div class="midi-studio-v2__song-sheet-grid">
-              <label class="tool-starter__field" for="songSheetSectionsInput">
+              <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetSectionsInput">
                 <span>Sections</span>
                 <textarea id="songSheetSectionsInput" rows="4" placeholder="intro: Am F&#10;loop: Am F C G"></textarea>
               </label>
-              <label class="tool-starter__field" for="songSheetLoopSectionsInput">
+              <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetLoopSectionsInput">
                 <span>Loop sections</span>
                 <textarea id="songSheetLoopSectionsInput" rows="2" placeholder="loop"></textarea>
               </label>

tools/midi-studio-v2/js/controls/InstrumentGridControl.js

@@ -1027,13 +1027,16 @@ export class InstrumentGridControl {
     const displayName = this.createDisplayNameInput(lane);
     const typeSelect = this.createInstrumentTypeSelect(lane);
     const instrumentSelect = this.createInstrumentSelect(lane);
+    const previewMapping = this.createInstrumentDisplayOutput("audible-preview", this.previewMappingForLane(lane));
     this.selectedEditorControls.displayName = displayName;
     this.selectedEditorControls.instrumentType = typeSelect;
     this.selectedEditorControls.instrument = instrumentSelect;
+    this.selectedEditorControls.previewMapping = previewMapping;
     return this.createInstrumentEditorBucket("Identity", "identity", [
       this.createEditorField("Instrument display name", displayName),
       this.createEditorField("GM Type", typeSelect),
-      this.createEditorField("GM Instrument", instrumentSelect)
+      this.createEditorField("GM Instrument", instrumentSelect),
+      this.createEditorField("Audible preview", previewMapping)
     ]);
   }
 
@@ -1132,12 +1135,34 @@ export class InstrumentGridControl {
   createEditorField(labelText, control) {
     const label = document.createElement("label");
     const text = document.createElement("span");
-    label.className = "tool-starter__field midi-studio-v2__instrument-editor-field";
+    const controlElement = this.primaryEditorControl(control);
+    label.className = "tool-starter__field midi-studio-v2__field-card midi-studio-v2__instrument-editor-field";
+    label.dataset.midiStudioFieldState = this.editorFieldState(controlElement);
     text.textContent = labelText;
     label.append(text, control);
     return label;
   }
 
+  primaryEditorControl(control) {
+    if (control?.matches?.("input, select, textarea, output")) {
+      return control;
+    }
+    return control?.querySelector?.("input, select, textarea, output") || null;
+  }
+
+  editorFieldState(control) {
+    if (!control) {
+      return "readonly";
+    }
+    if (control.dataset?.midiStudioFutureControl !== undefined || control.dataset?.midiStudioUnwired) {
+      return "unwired";
+    }
+    if (control.disabled || control.readOnly || control.tagName === "OUTPUT") {
+      return "readonly";
+    }
+    return "editable";
+  }
+
   createOctaveRangeField(lowInput, highInput) {
     const group = document.createElement("span");
     group.className = "midi-studio-v2__octave-range-field";
@@ -1167,6 +1192,31 @@ export class InstrumentGridControl {
     return input;
   }
 
+  createInstrumentDisplayOutput(kind, value) {
+    const output = document.createElement("output");
+    output.dataset.instrumentDerivedField = kind;
+    output.value = value;
+    output.textContent = value;
+    output.setAttribute("aria-readonly", "true");
+    return output;
+  }
+
+  previewMappingForLane(lane) {
+    const state = this.previewLaneState[lane] || {};
+    return audiblePreviewLabel(state.instrument) || "No audible preview selected";
+  }
+
+  updateSelectedInstrumentDisplayFields(lane) {
+    if (this.selectedEditorControls?.lane !== lane) {
+      return;
+    }
+    if (this.selectedEditorControls.previewMapping) {
+      const value = this.previewMappingForLane(lane);
+      this.selectedEditorControls.previewMapping.value = value;
+      this.selectedEditorControls.previewMapping.textContent = value;
+    }
+  }
+
   createInstrumentNumberInput(lane, kind, { ariaLabel, datasetName, max, min, step, value }) {
     const input = document.createElement("input");
     input.id = `preview${kind.charAt(0).toUpperCase()}${kind.slice(1)}${laneId(lane)}Input`;
@@ -1981,6 +2031,7 @@ export class InstrumentGridControl {
         this.populateInstrumentOptions(lane, this.selectedEditorControls.instrument);
       }
       this.updateLaneTitle(lane);
+      this.updateSelectedInstrumentDisplayFields(lane);
       this.syncQuickInstrumentControls();
       this.renderAuditionKeyboard();
       this.renderSelectionDetails();
@@ -2018,6 +2069,7 @@ export class InstrumentGridControl {
         editorControls.instrumentType.value = nextType;
       }
       this.updateLaneTitle(lane);
+      this.updateSelectedInstrumentDisplayFields(lane);
       this.syncQuickInstrumentControls();
       this.renderAuditionKeyboard();
       this.renderSelectionDetails();
@@ -2366,6 +2418,7 @@ export class InstrumentGridControl {
             this.selectedEditorControls.octaveHigh.value = String(highOctave);
           }
         }
+        this.updateSelectedInstrumentDisplayFields(lane);
       }
     }
     this.syncQuickInstrumentControls();

tools/midi-studio-v2/js/controls/SongSheetControl.js

@@ -158,7 +158,10 @@ export class SongSheetControl {
       const term = document.createElement("dt");
       const description = document.createElement("dd");
       const token = fieldToken(label);
+      row.className = "midi-studio-v2__field-card midi-studio-v2__song-sheet-display-field";
       row.dataset.songSheetSummaryField = token;
+      row.dataset.midiStudioFieldState = "readonly";
+      row.setAttribute("aria-readonly", "true");
       term.textContent = label;
       description.textContent = value === undefined || value === null || value === "" ? "not declared" : String(value);
       description.dataset.songSheetReadonly = token;