From 06b914ec1f3758b7cb056e03a0ccededcc74891f Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Tue, 21 Jul 2026 16:15:09 -0700
Subject: [PATCH 1/2] refactor(docs): restyle playground edit toggles as
 buttons

The playground's per-file "Edit" control was a bare checkbox in each of
the three views (CodeView, React Virtualizer, and vanilla Virtualizer).
It is now a bordered pill button: a filled checkbox plus "Editing" when
active, an outline icon plus "Edit" when idle.

Styling is shared through one `.playground-edit-toggle` class in
globals.css, driven by `aria-pressed`. Both state icons and both labels
are always present so CSS shows the matching pair. The vanilla view
builds its DOM by hand and inlines the two glyphs as SVG, so it only has
to flip the attribute; its metadata slot is light-DOM, so the app
stylesheet reaches it.
---
 .../(diffs)/playground/PlaygroundCodeView.tsx | 33 ++++++++----
 .../PlaygroundVirtualizerElementView.tsx      | 22 +++++---
 .../playground/PlaygroundVirtualizerView.tsx  | 54 ++++++++++---------
 apps/docs/app/globals.css                     | 35 ++++++++++++
 4 files changed, 102 insertions(+), 42 deletions(-)

diff --git a/apps/docs/app/(diffs)/playground/PlaygroundCodeView.tsx b/apps/docs/app/(diffs)/playground/PlaygroundCodeView.tsx
index 813a0f88e..8c43c5a6a 100644
--- a/apps/docs/app/(diffs)/playground/PlaygroundCodeView.tsx
+++ b/apps/docs/app/(diffs)/playground/PlaygroundCodeView.tsx
@@ -17,6 +17,7 @@ import {
   type CodeViewReactOptions,
   useStableCallback,
 } from '@pierre/diffs/react';
+import { IconCheckboxFill, IconSquircleLg } from '@pierre/icons';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { flushSync } from 'react-dom';
 
@@ -390,16 +391,30 @@ export function PlaygroundCodeView({
   );
 
   const renderHeaderMetadata = useStableCallback((item: PlaygroundItem) => {
+    const isEditing = item.edit === true;
     return (
-      <label className="flex cursor-pointer items-center gap-[4px] text-xs select-none">
-        <input
-          type="checkbox"
-          className="cursor-pointer"
-          checked={item.edit === true}
-          onChange={(event) => toggleEdit(item.id, event.target.checked)}
-        />
-        Edit
-      </label>
+      <button
+        type="button"
+        onClick={() => toggleEdit(item.id, !isEditing)}
+        aria-pressed={isEditing}
+        className={`-mr-[8px] flex cursor-pointer items-center gap-1 rounded-sm border py-1 pr-2 pl-1.5 text-xs transition ${
+          isEditing
+            ? 'border-blue-400/50 bg-blue-500/25 text-blue-600'
+            : 'border bg-transparent text-neutral-500 hover:border-neutral-300 hover:bg-neutral-100 hover:text-neutral-700'
+        }`}
+      >
+        {isEditing ? (
+          <>
+            <IconCheckboxFill size={12} />
+            Editing
+          </>
+        ) : (
+          <>
+            <IconSquircleLg size={12} className="opacity-50" />
+            Edit
+          </>
+        )}
+      </button>
     );
   });
 
diff --git a/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx b/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx
index d9a54e6ef..94d39f1d6 100644
--- a/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx
+++ b/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx
@@ -10,6 +10,7 @@ import {
 } from '@pierre/diffs';
 import type { EditorOptions } from '@pierre/diffs/editor';
 import { FileDiff, useStableCallback, Virtualizer } from '@pierre/diffs/react';
+import { IconCheckboxFill, IconSquircleLg } from '@pierre/icons';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { flushSync } from 'react-dom';
 
@@ -221,15 +222,20 @@ function ElementVirtualizerDiff({
 
   const renderHeaderMetadata = useStableCallback(() => {
     return (
-      <label className="flex cursor-pointer items-center gap-[4px] text-xs select-none">
-        <input
-          type="checkbox"
-          className="cursor-pointer"
-          checked={editing}
-          onChange={(event) => setEditing(event.target.checked)}
+      <button
+        type="button"
+        onClick={() => setEditing((current) => !current)}
+        aria-pressed={editing}
+        className="playground-edit-toggle"
+      >
+        <IconCheckboxFill
+          size={12}
+          className="playground-edit-toggle-icon-on"
         />
-        Edit
-      </label>
+        <IconSquircleLg size={12} className="playground-edit-toggle-icon-off" />
+        <span className="playground-edit-toggle-label-on">Editing</span>
+        <span className="playground-edit-toggle-label-off">Edit</span>
+      </button>
     );
   });
 
diff --git a/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerView.tsx b/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerView.tsx
index 268085fb4..af3a803ed 100644
--- a/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerView.tsx
+++ b/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerView.tsx
@@ -25,28 +25,29 @@ interface PlaygroundVirtualizerViewProps {
   showAnnotations: boolean;
 }
 
-// Builds the per-file "Edit" checkbox rendered into a diff header's metadata
-// slot. The header lives in the diff's shadow root (outside app CSS), so the
-// control is styled inline. Returns the label element plus its input so the
-// caller can wire the change handler once the diff instance exists.
-function createEditToggle(): { element: HTMLElement; input: HTMLInputElement } {
-  const label = document.createElement('label');
-  label.style.display = 'inline-flex';
-  label.style.alignItems = 'center';
-  label.style.gap = '4px';
-  label.style.cursor = 'pointer';
-  label.style.fontSize = '12px';
-  label.style.userSelect = 'none';
+// Both edit-toggle state icons, inlined as SVG markup. @pierre/icons ships
+// React components (used by the CodeView and React-Virtualizer toggles), but
+// this vanilla view builds DOM directly, so the same two glyphs
+// (IconCheckboxFill / IconSquircleLg) are inlined here. The shared
+// `.playground-edit-toggle` styles show whichever matches `aria-pressed`.
+const EDIT_TOGGLE_ICON_ON = `<svg class="playground-edit-toggle-icon-on" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 16 16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M8 0C1.412 0 0 1.412 0 8s1.412 8 8 8 8-1.412 8-8-1.412-8-8-8m4.08 5.975a.75.75 0 0 0-1.16-.95L6.943 9.884 5.03 7.97a.75.75 0 0 0-1.06 1.06l2.5 2.5a.75.75 0 0 0 1.11-.055z"/></svg>`;
+const EDIT_TOGGLE_ICON_OFF = `<svg class="playground-edit-toggle-icon-off" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 16 16" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.788 4.296C1.588 5.194 1.5 6.387 1.5 8s.088 2.806.288 3.704c.196.88.478 1.381.802 1.706s.826.607 1.706.802c.898.2 2.091.288 3.704.288s2.806-.088 3.704-.288c.88-.195 1.381-.478 1.706-.802s.607-.826.802-1.706c.2-.898.288-2.091.288-3.704s-.088-2.806-.288-3.704c-.195-.88-.478-1.381-.802-1.706s-.826-.606-1.706-.802C10.806 1.588 9.613 1.5 8 1.5s-2.806.088-3.704.288c-.88.196-1.381.478-1.706.802s-.606.826-.802 1.706M0 8c0-6.588 1.412-8 8-8s8 1.412 8 8-1.412 8-8 8-8-1.412-8-8"/></svg>`;
 
-  const input = document.createElement('input');
-  input.type = 'checkbox';
-  input.style.cursor = 'pointer';
-
-  const text = document.createElement('span');
-  text.textContent = 'Edit';
-
-  label.append(input, text);
-  return { element: label, input };
+// Builds the per-file "Edit" toggle rendered into a diff header's metadata
+// slot. Slotted content is a light-DOM child of the diffs container, so the
+// app stylesheet reaches it: styling lives in the shared
+// `.playground-edit-toggle` class (globals.css), matching the CodeView and
+// React-Virtualizer toggles. Both state icons and both labels ("Edit" /
+// "Editing") are always present; CSS shows the pair matching `aria-pressed`,
+// so the caller only flips the attribute (and wires edit/cleanup) once the diff
+// instance exists.
+function createEditToggle(): HTMLButtonElement {
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = 'playground-edit-toggle';
+  button.setAttribute('aria-pressed', 'false');
+  button.innerHTML = `${EDIT_TOGGLE_ICON_ON}${EDIT_TOGGLE_ICON_OFF}<span class="playground-edit-toggle-label-on">Editing</span><span class="playground-edit-toggle-label-off">Edit</span>`;
+  return button;
 }
 
 const VIRTUALIZER_CUSTOM_CSS = `${ITEM_UNSAFE_CSS}
@@ -176,7 +177,7 @@ export function PlaygroundVirtualizerView({
         },
       });
       editors.push(editor);
-      const { element: editToggle, input } = createEditToggle();
+      const editToggle = createEditToggle();
 
       const rerenderWithAnnotations = () => {
         instance.render({
@@ -286,9 +287,12 @@ export function PlaygroundVirtualizerView({
         );
 
       // Attaching the editor flips the new-file surface to contentEditable;
-      // detaching restores read-only review.
-      input.addEventListener('change', () => {
-        if (input.checked) {
+      // detaching restores read-only review. The button tracks its own state on
+      // `aria-pressed` (which also drives the shared toggle styles).
+      editToggle.addEventListener('click', () => {
+        const editing = editToggle.getAttribute('aria-pressed') !== 'true';
+        editToggle.setAttribute('aria-pressed', editing ? 'true' : 'false');
+        if (editing) {
           editor.edit(instance);
         } else {
           editor.cleanUp();
diff --git a/apps/docs/app/globals.css b/apps/docs/app/globals.css
index 64a63fb5c..3e5ca80a6 100644
--- a/apps/docs/app/globals.css
+++ b/apps/docs/app/globals.css
@@ -264,6 +264,41 @@
   @apply overflow-hidden rounded-lg border border-transparent dark:border-neutral-800;
 }
 
+/* Per-file "Edit" toggle shared by the playground React Virtualizer and vanilla
+   Virtualizer views, matching the CodeView view's toggle. The vanilla view
+   renders it into a diff header's metadata slot; slotted content lives in the
+   light DOM, so this app stylesheet reaches it. Active state is driven by
+   `aria-pressed`; both state icons and both labels ("Edit" / "Editing") are
+   always present and CSS shows the matching pair, so the vanilla toggle only
+   has to flip the attribute. */
+.playground-edit-toggle {
+  @apply -mr-[8px] flex cursor-pointer items-center gap-1 rounded-sm border py-1 pr-2 pl-1.5 text-xs transition;
+  @apply bg-transparent text-neutral-500;
+}
+.playground-edit-toggle:hover:not([aria-pressed='true']) {
+  @apply border-neutral-300 bg-neutral-100 text-neutral-700;
+}
+.playground-edit-toggle[aria-pressed='true'] {
+  @apply border-blue-400/50 bg-blue-500/25 text-blue-600;
+}
+.playground-edit-toggle-icon-off {
+  @apply block opacity-50;
+}
+.playground-edit-toggle-icon-on,
+.playground-edit-toggle-label-on {
+  @apply hidden;
+}
+.playground-edit-toggle[aria-pressed='true'] .playground-edit-toggle-icon-off,
+.playground-edit-toggle[aria-pressed='true'] .playground-edit-toggle-label-off {
+  @apply hidden;
+}
+.playground-edit-toggle[aria-pressed='true'] .playground-edit-toggle-icon-on {
+  @apply block;
+}
+.playground-edit-toggle[aria-pressed='true'] .playground-edit-toggle-label-on {
+  @apply inline;
+}
+
 .cv-scrollbar {
   --cv-scrollbar-thumb-bg: light-dark(
     color-mix(in lab, var(--background) 85%, black),

From 16f27091fe859cc2ddf45242c79521a6a8422898 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Tue, 21 Jul 2026 16:15:41 -0700
Subject: [PATCH 2/2] fix(docs): sync element virtualizer edit toggle with its
 state

Toggle Edit on a file in the playground's React Virtualizer view: the
button's pressed state lagged one click behind, showing the previous
value instead of the current one.

renderHeaderMetadata read `editing` from the render closure but was
wrapped in useStableCallback, which only refreshes its inner ref in a
commit-phase insertion effect. FileDiff calls the callback during
render, so it ran the previous render's closure. Use a useCallback keyed
on `editing` so each toggle renders with the current value.
---
 .../playground/PlaygroundVirtualizerElementView.tsx    | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx b/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx
index 94d39f1d6..364ec52c0 100644
--- a/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx
+++ b/apps/docs/app/(diffs)/playground/PlaygroundVirtualizerElementView.tsx
@@ -220,7 +220,13 @@ function ElementVirtualizerDiff({
     }
   );
 
-  const renderHeaderMetadata = useStableCallback(() => {
+  // Must NOT be a stable callback: FileDiff invokes renderHeaderMetadata
+  // synchronously during render, but useStableCallback only refreshes its inner
+  // ref in a commit-phase insertion effect. Reading `editing` (render-phase
+  // state) through a stable wrapper would render the button one toggle behind —
+  // the header would reflect the previous `editing` value. A per-`editing`
+  // useCallback hands renderDiffChildren the current closure each toggle.
+  const renderHeaderMetadata = useCallback(() => {
     return (
       <button
         type="button"
@@ -237,7 +243,7 @@ function ElementVirtualizerDiff({
         <span className="playground-edit-toggle-label-off">Edit</span>
       </button>
     );
-  });
+  }, [editing]);
 
   return (
     <FileDiff