feat: implement InspectDialog and TweakPanel for design customization in gallery

Author: bronz3beard

e2e/a11y.spec.ts

@@ -38,6 +38,26 @@ const openPage = async (page: Page, path: string) => {
     .toBe(true);
 };
 
+// The inspect dialog is the only interactive matrix on the gallery, and the only
+// place tweak controls exist, so it is scanned as its own state of the page.
+// (Scheduled for S10c, pulled forward to the batch that introduced it.)
+test('the open inspect dialog has no WCAG 2.2 A/AA violations', async ({ page }) => {
+  await openPage(page, './');
+  await page.getByRole('button', { name: 'Inspect Noir' }).click();
+  await expect(page.getByRole('dialog', { name: 'Noir design' })).toBeVisible();
+
+  const allButContrast = await new AxeBuilder({ page })
+    .withTags(WCAG_TAGS)
+    .disableRules(['color-contrast'])
+    .analyze();
+  const contrast = await new AxeBuilder({ page })
+    .withRules(['color-contrast'])
+    .exclude(DATA_COLOURED_CELLS)
+    .analyze();
+
+  expect(summarise([...allButContrast.violations, ...contrast.violations])).toEqual([]);
+});
+
 for (const [label, path] of PAGES) {
   test(`the ${label} has no WCAG 2.2 A/AA violations`, async ({ page }) => {
     await openPage(page, path);

e2e/gallery.spec.ts

@@ -26,7 +26,11 @@ test('shows every design as a live preview card', async ({ page }) => {
 test('previews are not interactive, so the grid adds no cell tab stops', async ({ page }) => {
   await page.goto(GALLERY);
 
-  await expect(page.getByRole('list', { name: 'Designs' }).getByRole('button')).toHaveCount(0);
+  // Each card has one Inspect button; the 26 × 25 preview cells add none.
+  const { total } = await shownCount(page);
+  const grid = page.getByRole('list', { name: 'Designs' });
+  await expect(grid.locator('.rdm-root button')).toHaveCount(0);
+  await expect(grid.getByRole('button')).toHaveCount(total);
 });
 
 test('filter chips narrow the designs and are kept in the URL', async ({ page }) => {

e2e/inspect.spec.ts

@@ -0,0 +1,110 @@
+import { expect, test, type Page } from '@playwright/test';
+
+const GALLERY = './';
+
+// Noir is a palette design with square corners and filled cells, so every tweak
+// below is a visible change from how it comes.
+const openNoir = async (page: Page) => {
+  await page.goto(GALLERY);
+  await page.getByRole('button', { name: 'Inspect Noir' }).click();
+  const dialog = page.getByRole('dialog', { name: 'Noir design' });
+  await expect(dialog).toBeVisible();
+  return dialog;
+};
+
+test('a design opens large, with the code needed to use it', async ({ page }) => {
+  const dialog = await openNoir(page);
+
+  await expect(dialog.getByRole('table', { name: /React Matrix/ })).toBeVisible();
+  await expect(dialog.locator('.tweak-snippet')).toHaveText(
+    "import ReactMatrix, { noir } from 'react-data-matrix';\n\n" +
+      '<ReactMatrix data={data} theme={noir} />'
+  );
+  // The token table is generated from the theme being rendered, so it cannot
+  // drift from it.
+  await expect(dialog.getByRole('row', { name: /^cellVariant/ })).toContainText('fill');
+
+  await page.keyboard.press('Escape');
+  await expect(dialog).toBeHidden();
+});
+
+test('tweaking a design changes both the preview and the snippet', async ({ page }) => {
+  const dialog = await openNoir(page);
+  const cell = dialog.locator('td.rdm-cell').first();
+  const before = await cell.evaluate((element) => getComputedStyle(element).borderRadius);
+
+  await dialog.getByRole('radio', { name: 'Pill' }).check();
+  await dialog.getByRole('radio', { name: 'Score' }).check();
+
+  await expect(dialog.locator('.tweak-snippet')).toContainText(
+    "theme={{ ...noir, radius: '999px', emphasis: 'score' }}"
+  );
+  expect(await cell.evaluate((element) => getComputedStyle(element).borderRadius)).not.toBe(before);
+  await expect(dialog.getByRole('row', { name: /^radius/ })).toContainText('999px');
+
+  // "As it comes" must return the design to its published form.
+  await dialog.getByRole('radio', { name: 'As it comes' }).first().check();
+  await expect(dialog.locator('.tweak-snippet')).toContainText("theme={{ ...noir, emphasis:");
+  await expect(dialog.locator('.tweak-snippet')).not.toContainText('radius');
+});
+
+test('choosing cells shows what the click handler receives, newest first', async ({ page }) => {
+  const dialog = await openNoir(page);
+  const log = dialog.locator('.inspect-log li');
+
+  await expect(log).toHaveCount(0);
+  await dialog.getByRole('button', { name: /Likelihood Rare, Consequence Minor/ }).click();
+  await expect(log).toHaveText(['Rare × Minor — low (1)']);
+
+  await dialog
+    .getByRole('button', { name: /Likelihood Almost Certain, Consequence Catastrophic/ })
+    .focus();
+  await page.keyboard.press('Enter');
+  await expect(log.first()).toHaveText('Almost Certain × Catastrophic — extreme (25)');
+
+  // Only the last five are kept, so the log cannot grow without bound.
+  for (const name of await dialog.getByRole('button', { name: /Likelihood/ }).all()) {
+    await name.click();
+  }
+  await expect(log).toHaveCount(5);
+});
+
+test('the inspected matrix is shown whole on a desktop screen', async ({ page }) => {
+  test.skip((page.viewportSize()?.width ?? 0) < 1024, 'phones scroll the matrix inside the dialog');
+  await openNoir(page);
+
+  // Either side of the one-column/two-column split: a side panel that leaves the
+  // matrix too little room clips it, which is how it shipped the first time.
+  for (const width of [1280, 1360, 1600, 2400]) {
+    await page.setViewportSize({ width, height: 900 });
+    const clipped = await page
+      .locator('.inspect-preview .rdm-root')
+      .evaluate((root) => root.scrollWidth > root.clientWidth);
+    expect(clipped, `clipped at ${width}px`).toBe(false);
+  }
+});
+
+test('the snippet can be copied to the clipboard', async ({ page, browserName, context }) => {
+  test.skip(browserName !== 'chromium', 'clipboard permissions are Chromium-only in Playwright');
+  await context.grantPermissions(['clipboard-read', 'clipboard-write']);
+  const dialog = await openNoir(page);
+
+  await dialog.getByRole('button', { name: 'Copy' }).click();
+
+  await expect(dialog.getByRole('status')).toHaveText('Copied');
+  const clipboard = await page.evaluate(() => navigator.clipboard.readText());
+  expect(clipboard).toContain('<ReactMatrix data={data} theme={noir} />');
+});
+
+test('each design opens with its own tokens and an empty log', async ({ page }) => {
+  const noir = await openNoir(page);
+  await noir.getByRole('button', { name: /Likelihood Rare, Consequence Minor/ }).click();
+  await expect(noir.locator('.inspect-log li')).toHaveCount(1);
+  await page.keyboard.press('Escape');
+
+  await page.getByRole('button', { name: 'Inspect Aurora' }).click();
+  const aurora = page.getByRole('dialog', { name: 'Aurora design' });
+
+  await expect(aurora.locator('.tweak-snippet')).toContainText('theme={aurora}');
+  await expect(aurora.locator('.inspect-log li')).toHaveCount(0);
+});

src/gallery/Gallery.tsx

@@ -3,6 +3,7 @@ import { presets, type MatrixData, type PresetName } from '../../lib';
 import { catalog } from './catalog';
 import FilterChips from './FilterChips';
 import { matchesFilters, readFilters, writeFilters, type GalleryFilters } from './filters';
+import InspectDialog from './InspectDialog';
 import PresetCard from './PresetCard';
 import './gallery.css';
 
@@ -12,6 +13,7 @@ const NAMES = Object.keys(presets) as PresetName[];
 // grid instead of hiding designs behind a dropdown.
 const Gallery = ({ data }: { data: MatrixData }) => {
   const [filters, setFilters] = useState<GalleryFilters>(() => readFilters(location.search));
+  const [inspected, setInspected] = useState<PresetName | null>(null);
 
   useEffect(() => {
     history.replaceState(
@@ -47,11 +49,27 @@ const Gallery = ({ data }: { data: MatrixData }) => {
         <ul className="gallery-grid" aria-label="Designs">
           {visible.map((name) => (
             <li key={name}>
-              <PresetCard theme={presets[name]} info={catalog[name]} data={data} />
+              <PresetCard
+                theme={presets[name]}
+                info={catalog[name]}
+                data={data}
+                onInspect={() => setInspected(name)}
+              />
             </li>
           ))}
         </ul>
       )}
+      {inspected && (
+        // Remounted per design, so tweaks and the event log start clean.
+        <InspectDialog
+          key={inspected}
+          preset={inspected}
+          theme={presets[inspected]}
+          info={catalog[inspected]}
+          data={data}
+          onClose={() => setInspected(null)}
+        />
+      )}
     </main>
   );
 };

src/gallery/InspectDialog.tsx

@@ -0,0 +1,126 @@
+import { useEffect, useRef, useState } from 'react';
+import ReactMatrix, { type MatrixData, type MatrixTheme } from '../../lib';
+import type { PresetInfo } from './catalog';
+import TweakPanel from './TweakPanel';
+import { applyTweaks, type Tweaks } from './tweaks';
+
+interface InspectDialogProps {
+  /** The preset's export name, used in the copyable snippet. */
+  preset: string;
+  theme: MatrixTheme;
+  info: PresetInfo;
+  data: MatrixData;
+  onClose: () => void;
+}
+
+const LOG_LIMIT = 5;
+
+interface LoggedClick {
+  id: number;
+  text: string;
+}
+
+// The gallery's previews are plain text; this is the one place a design is
+// shown large, tweakable and interactive.
+const InspectDialog = ({ preset, theme, info, data, onClose }: InspectDialogProps) => {
+  const dialog = useRef<HTMLDialogElement>(null);
+  // The log keeps only the last five entries, so its length is not a usable key.
+  const nextId = useRef(0);
+  const [tweaks, setTweaks] = useState<Tweaks>({});
+  const [log, setLog] = useState<LoggedClick[]>([]);
+
+  // `showModal` is what makes Escape, the focus trap and inertness work; it can
+  // only be called imperatively, and never during render.
+  useEffect(() => {
+    dialog.current?.showModal();
+  }, []);
+
+  const applied = applyTweaks({ theme, tweaks });
+
+  return (
+    <dialog className="inspect" ref={dialog} onClose={onClose} aria-label={`${theme.name} design`}>
+      <div className="inspect-head">
+        <div>
+          <h2>{theme.name}</h2>
+          <p>{info.description}</p>
+        </div>
+        <button type="button" onClick={() => dialog.current?.close()}>
+          Close
+        </button>
+      </div>
+
+      <div className="inspect-body">
+        <div className="inspect-preview">
+          <ReactMatrix
+            data={data}
+            theme={applied}
+            onCellClick={(cell, { row, column }) =>
+              setLog((entries) =>
+                [
+                  {
+                    id: nextId.current++,
+                    text: `${row.row_header_title} × ${column.header_title} — ${cell.description} (${cell.score_value})`,
+                  },
+                  ...entries,
+                ].slice(0, LOG_LIMIT)
+              )
+            }
+          />
+          <h3>Cell selections</h3>
+          <p className="inspect-hint">
+            Choose a cell with a pointer, Enter or Space: this is what{' '}
+            <code>onCellClick</code> receives.
+          </p>
+          {/* The live region is this wrapper, so it stays in place while its
+              contents change from the empty state to the list. */}
+          <div className="inspect-log" aria-live="polite">
+            {log.length === 0 ? (
+              <p>Nothing chosen yet.</p>
+            ) : (
+              <ol>
+                {log.map((entry) => (
+                  <li key={entry.id}>{entry.text}</li>
+                ))}
+              </ol>
+            )}
+          </div>
+        </div>
+
+        <div className="inspect-side">
+          <TweakPanel preset={preset} tweaks={tweaks} onChange={setTweaks} />
+
+          <h3>Tokens</h3>
+          <table className="inspect-tokens">
+            <caption>Every value in this design, as it is being rendered.</caption>
+            <tbody>
+              {Object.entries(applied).map(([token, value]) => (
+                <tr key={token}>
+                  <th scope="row">{token}</th>
+                  <td>
+                    {Array.isArray(value) ? (
+                      <span className="inspect-swatches">
+                        {value.map((step: { bg: string; fg: string }) => (
+                          <span
+                            key={step.bg}
+                            style={{ backgroundColor: step.bg, color: step.fg }}
+                            title={`${step.fg} on ${step.bg}`}
+                          >
+                            A
+                          </span>
+                        ))}
+                      </span>
+                    ) : (
+                      String(value)
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </dialog>
+  );
+};
+
+export default InspectDialog;

src/gallery/PresetCard.tsx

@@ -6,11 +6,12 @@ interface PresetCardProps {
   theme: MatrixTheme;
   info: PresetInfo;
   data: MatrixData;
+  onInspect: () => void;
 }
 
 // A live, non-interactive preview: no `onCellClick`, so the gallery grid adds no
 // cell tab stops however many designs it shows.
-const PresetCard = ({ theme, info, data }: PresetCardProps) => {
+const PresetCard = ({ theme, info, data, onInspect }: PresetCardProps) => {
   const headingId = useId();
 
   return (
@@ -23,6 +24,9 @@ const PresetCard = ({ theme, info, data }: PresetCardProps) => {
         ))}
       </ul>
       <ReactMatrix data={data} theme={theme} style={{ '--rdm-font-size': '0.75rem' }} />
+      <button type="button" className="preset-inspect" onClick={onInspect}>
+        Inspect <span className="sr-only">{theme.name}</span>
+      </button>
     </article>
   );
 };