From b62c8203b717e198f7afe7f3ab964a938cf4535d Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Thu, 25 Jun 2026 18:36:17 +0000
Subject: [PATCH 1/5] fix(Pagination): make changeAction interruptible with
 optimistic page state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pagination's changeAction now runs in a transition and tracks the page
optimistically, matching ToggleButton. The controls reflect the page being
navigated to while the action is pending, and rapid prev/next clicks advance
through pages (interrupting the in-flight transition) instead of being dropped
by a re-entry guard. A synchronous handler that suspends also drives the
pending state.

Button's clickAction keeps its single-fire guard — a re-click there is a
duplicate submit, not new intent — and now documents why, with a regression
test asserting a fast double-click fires clickAction only once.
---
 .../pagination-interruptible-button-guard.md  |  14 ++
 packages/core/src/Button/Button.test.tsx      |  40 +++--
 packages/core/src/Button/Button.tsx           |   8 +
 .../core/src/Pagination/Pagination.test.tsx   | 151 ++++++++++++++++--
 packages/core/src/Pagination/Pagination.tsx   |  66 ++++----
 5 files changed, 226 insertions(+), 53 deletions(-)
 create mode 100644 .changeset/pagination-interruptible-button-guard.md

diff --git a/.changeset/pagination-interruptible-button-guard.md b/.changeset/pagination-interruptible-button-guard.md
new file mode 100644
index 000000000000..eaf1139f58ed
--- /dev/null
+++ b/.changeset/pagination-interruptible-button-guard.md
@@ -0,0 +1,14 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Make `Pagination`'s `changeAction` interruptible with optimistic state.
+Page changes now run inside a transition and track the target page
+optimistically, so the controls (indicator, active page, prev/next enablement)
+reflect the page being navigated to while the action is pending. Rapid prev/next
+clicks now advance through pages instead of being dropped by a re-entry guard,
+and a synchronous handler that suspends (e.g. a router navigation) also drives
+the pending state — matching `ToggleButton`'s action behavior. `Button`'s
+`clickAction` keeps its single-fire guard (a re-click is a duplicate submit, not
+new intent) and now documents why.
+@cixzhang
diff --git a/packages/core/src/Button/Button.test.tsx b/packages/core/src/Button/Button.test.tsx
index 98f3d8c960e5..85eb84eb74a5 100644
--- a/packages/core/src/Button/Button.test.tsx
+++ b/packages/core/src/Button/Button.test.tsx
@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import {Badge} from '../Badge/Badge';
@@ -228,11 +228,7 @@ describe('Button', () => {
       order.push('clickAction');
     });
     render(
-      <Button
-        label="Test"
-        onClick={handleClick}
-        clickAction={handleAction}
-      />,
+      <Button label="Test" onClick={handleClick} clickAction={handleAction} />,
     );
 
     await user.click(screen.getByRole('button'));
@@ -246,11 +242,7 @@ describe('Button', () => {
     const handleClick = vi.fn((e: React.MouseEvent) => e.preventDefault());
     const handleAction = vi.fn();
     render(
-      <Button
-        label="Test"
-        onClick={handleClick}
-        clickAction={handleAction}
-      />,
+      <Button label="Test" onClick={handleClick} clickAction={handleAction} />,
     );
 
     await user.click(screen.getByRole('button'));
@@ -258,6 +250,32 @@ describe('Button', () => {
     expect(handleAction).not.toHaveBeenCalled();
   });
 
+  it('fires clickAction once on a fast double-click (no double-submit)', async () => {
+    // clickAction is a fire-once command, so a second synchronous click while
+    // the first action is still pending must not fire it again. Guards the
+    // re-entry protection in handleClick from regressing.
+    let resolveAction: (() => void) | undefined;
+    const handleAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+    render(<Button label="Pay" clickAction={handleAction} />);
+
+    const button = screen.getByRole('button');
+    await act(async () => {
+      fireEvent.click(button);
+      fireEvent.click(button);
+    });
+    expect(handleAction).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+  });
+
   // type/name/value/form props
   it('defaults type to button', () => {
     render(<Button label="Test" />);
diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsx
index 4a599cf33727..03a972face11 100644
--- a/packages/core/src/Button/Button.tsx
+++ b/packages/core/src/Button/Button.tsx
@@ -513,6 +513,14 @@ export function Button({
   const buttonGroup = useButtonGroup();
 
   const [isPending, startTransition] = useTransition();
+  // Synchronous re-entry guard against double-submit. Unlike a toggle (where a
+  // re-click is a *new* intent and the action should stay interruptible),
+  // clickAction is a fire-once command (submit/save/pay) — a second fire is a
+  // duplicate, not new intent. isPending and useOptimistic don't help here:
+  // neither commits within the same tick, so a fast double-click would fire
+  // clickAction twice before the disabled state lands. The ref is the only
+  // same-tick-safe dedupe — keep it. (cf. ToggleButton/Pagination, which are
+  // interruptible state transitions and intentionally have no guard.)
   const actionInFlightRef = useRef(false);
   const isLoadingState = isLoading || isPending;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
diff --git a/packages/core/src/Pagination/Pagination.test.tsx b/packages/core/src/Pagination/Pagination.test.tsx
index 1aa20970aaa8..a37879fe8d9d 100644
--- a/packages/core/src/Pagination/Pagination.test.tsx
+++ b/packages/core/src/Pagination/Pagination.test.tsx
@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, within} from '@testing-library/react';
+import {render, screen, within, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
 
@@ -346,6 +346,141 @@ describe('Pagination', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // changeAction (interruptible, optimistic)
+  // ---------------------------------------------------------------------------
+
+  describe('changeAction', () => {
+    it('fires onChange then changeAction with the new page', async () => {
+      const user = userEvent.setup();
+      const order: string[] = [];
+      const onChange = vi.fn(() => order.push('onChange'));
+      const changeAction = vi.fn(() => {
+        order.push('changeAction');
+      });
+      render(
+        <Pagination
+          page={1}
+          onChange={onChange}
+          changeAction={changeAction}
+          totalPages={5}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(onChange).toHaveBeenCalledWith(2);
+      expect(changeAction).toHaveBeenCalledWith(2);
+      expect(order).toEqual(['onChange', 'changeAction']);
+    });
+
+    it('shows the optimistic page while changeAction is pending', async () => {
+      const user = userEvent.setup();
+      let resolveAction: (() => void) | undefined;
+      const changeAction = vi.fn(
+        async () =>
+          new Promise<void>(resolve => {
+            resolveAction = resolve;
+          }),
+      );
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          variant="compact"
+        />,
+      );
+
+      // The committed `page` prop stays at 1 (the consumer hasn't re-rendered),
+      // but the indicator optimistically reflects the page being navigated to.
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(changeAction).toHaveBeenCalledWith(2);
+      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+
+      await act(async () => {
+        resolveAction?.();
+        await Promise.resolve();
+      });
+    });
+
+    it('interrupts an in-flight action on rapid next clicks', async () => {
+      // Each click derives its target from the optimistic page, so clicking
+      // next twice before the action settles advances 1 -> 2 -> 3 rather than
+      // being dropped by a re-entry guard. The consumer never re-renders here,
+      // so the committed `page` prop stays at 1 the whole time.
+      const resolvers: (() => void)[] = [];
+      const changeAction = vi.fn(
+        async () =>
+          new Promise<void>(resolve => {
+            resolvers.push(resolve);
+          }),
+      );
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          variant="compact"
+        />,
+      );
+
+      const next = screen.getByRole('button', {name: 'Go to next page'});
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(screen.getByText('Page 3 of 5')).toBeInTheDocument();
+
+      expect(changeAction).toHaveBeenCalledTimes(2);
+      expect(changeAction).toHaveBeenNthCalledWith(1, 2);
+      expect(changeAction).toHaveBeenNthCalledWith(2, 3);
+
+      await act(async () => {
+        resolvers.forEach(resolve => resolve());
+        await Promise.resolve();
+      });
+    });
+
+    it('supports a synchronous changeAction', async () => {
+      const user = userEvent.setup();
+      const changeAction = vi.fn((_page: number) => {});
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          changeAction={changeAction}
+          totalPages={5}
+        />,
+      );
+      await user.click(
+        screen.getByRole('button', {name: 'Go to previous page'}),
+      );
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(changeAction).toHaveBeenCalledWith(1);
+    });
+
+    it('does not fire changeAction when disabled', async () => {
+      const user = userEvent.setup();
+      const changeAction = vi.fn();
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          isDisabled
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(changeAction).not.toHaveBeenCalled();
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Boundary states
   // ---------------------------------------------------------------------------
@@ -459,12 +594,7 @@ describe('Pagination', () => {
   describe('disabled state', () => {
     it('disables all page buttons when isDisabled', () => {
       render(
-        <Pagination
-          page={3}
-          onChange={() => {}}
-          totalPages={5}
-          isDisabled
-        />,
+        <Pagination page={3} onChange={() => {}} totalPages={5} isDisabled />,
       );
       expect(
         screen.getByRole('button', {name: 'Go to previous page'}),
@@ -480,12 +610,7 @@ describe('Pagination', () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
       render(
-        <Pagination
-          page={3}
-          onChange={onChange}
-          totalPages={5}
-          isDisabled
-        />,
+        <Pagination page={3} onChange={onChange} totalPages={5} isDisabled />,
       );
       // Disabled buttons can't be clicked
       await user.click(screen.getByRole('button', {name: 'Go to page 1'}));
diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index 6f3f68e0709d..a40b105e4d3b 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -19,7 +19,7 @@
  *   label, data-testid, xstyle
  */
 
-import {useTransition} from 'react';
+import {useOptimistic, useTransition} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -349,16 +349,24 @@ export function Pagination({
   style,
   ref,
 }: PaginationProps) {
-  const [isPending, startTransition] = useTransition();
+  const [, startTransition] = useTransition();
+
+  // Track the page optimistically. While a changeAction is pending the controls
+  // reflect the page the user is navigating to, and a click mid-flight derives
+  // its target from this value — so rapid prev/next clicks advance instead of
+  // stalling on the last committed page.
+  const [optimisticPage, setOptimisticPage] = useOptimistic(page);
 
   // Compute pagination state
   const computedTotalPages =
     totalPagesProp ??
     (totalItems != null ? Math.ceil(totalItems / pageSize) : undefined);
 
-  const hasPrevious = page > 1;
+  const hasPrevious = optimisticPage > 1;
   const hasNext =
-    computedTotalPages != null ? page < computedTotalPages : (hasMore ?? false);
+    computedTotalPages != null
+      ? optimisticPage < computedTotalPages
+      : (hasMore ?? false);
 
   // Return null for empty state
   if (totalItems != null && totalItems <= 0) {
@@ -368,48 +376,48 @@ export function Pagination({
     return null;
   }
 
+  // Run the page change inside a transition so changeAction drives a pending
+  // state. The transition is interruptible — clicking again before it settles
+  // starts a fresh transition with the next optimistic page rather than being
+  // dropped, so there is no re-entry guard. A synchronous handler that suspends
+  // (e.g. a router navigation that suspends on data) also drives the pending
+  // state, not just promises.
   const handlePageChange = (newPage: number) => {
-    if (isDisabled || isPending) {
+    if (isDisabled) {
       return;
     }
-    onChange(newPage);
-    if (changeAction) {
-      startTransition(async () => {
-        await changeAction(newPage);
-      });
-    }
+    startTransition(async () => {
+      setOptimisticPage(newPage);
+      onChange(newPage);
+      await changeAction?.(newPage);
+    });
   };
 
   const handlePrevious = () => {
     if (hasPrevious) {
-      handlePageChange(page - 1);
+      handlePageChange(optimisticPage - 1);
     }
   };
 
   const handleNext = () => {
     if (hasNext) {
-      handlePageChange(page + 1);
+      handlePageChange(optimisticPage + 1);
     }
   };
 
   const handlePageSizeChange = (value: string) => {
     const newSize = Number(value);
     onPageSizeChange?.(newSize);
-    // Reset to page 1 when page size changes
-    onChange(1);
-    if (changeAction) {
-      startTransition(async () => {
-        await changeAction(1);
-      });
-    }
+    // Reset to page 1 when page size changes.
+    handlePageChange(1);
   };
 
   // Item range for count display
-  const rangeStart = (page - 1) * pageSize + 1;
+  const rangeStart = (optimisticPage - 1) * pageSize + 1;
   const rangeEnd =
     totalItems != null
-      ? Math.min(page * pageSize, totalItems)
-      : page * pageSize;
+      ? Math.min(optimisticPage * pageSize, totalItems)
+      : optimisticPage * pageSize;
 
   const buttonSize = size === 'sm' ? 'sm' : 'md';
   const isSm = size === 'sm';
@@ -421,7 +429,7 @@ export function Pagination({
           return null;
         }
         const pageRange = generatePageRange(
-          page,
+          optimisticPage,
           computedTotalPages,
           siblingCount,
         );
@@ -443,7 +451,7 @@ export function Pagination({
                   </span>
                 );
               }
-              const isActive = item === page;
+              const isActive = item === optimisticPage;
               return (
                 <Button
                   key={item}
@@ -483,7 +491,7 @@ export function Pagination({
         return (
           <span {...stylex.props(styles.infoText)}>
             <Text type="body" size="sm" color="secondary">
-              {`Page ${page} of ${computedTotalPages}`}
+              {`Page ${optimisticPage} of ${computedTotalPages}`}
             </Text>
           </span>
         );
@@ -503,18 +511,18 @@ export function Pagination({
                 key={i + 1}
                 type="button"
                 aria-label={`Go to page ${i + 1}`}
-                aria-current={i + 1 === page ? 'page' : undefined}
+                aria-current={i + 1 === optimisticPage ? 'page' : undefined}
                 onClick={() => handlePageChange(i + 1)}
                 disabled={isDisabled}
                 {...mergeProps(
                   themeProps('pagination-dot', {
-                    active: i + 1 === page ? 'active' : null,
+                    active: i + 1 === optimisticPage ? 'active' : null,
                     size,
                   }),
                   stylex.props(
                     styles.dot,
                     isSm && styles.dotSm,
-                    i + 1 === page && styles.dotActive,
+                    i + 1 === optimisticPage && styles.dotActive,
                     isDisabled && styles.dotDisabled,
                   ),
                 )}

From 57f61ea9f411ae4d73739ba57e4c9d3328c467c9 Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Fri, 26 Jun 2026 00:19:13 +0000
Subject: [PATCH 2/5] fix(Pagination): keep onChange urgent so controlled page
 state updates synchronously

Moving onChange into the transition deferred the consumer's page-state
update (e.g. the Table pagination plugin's row slicing) to a low-priority
transition commit, racing assertions under parallel CI workers. Call
onChange urgently before starting the transition; the optimistic indicator
and changeAction still run inside it, preserving interruptibility.
---
 packages/core/src/Pagination/Pagination.tsx | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index a40b105e4d3b..53aa9199bb5c 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -386,9 +386,14 @@ export function Pagination({
     if (isDisabled) {
       return;
     }
+    // Notify the consumer urgently so controlled page state (and any data it
+    // drives, e.g. the Table pagination plugin slicing rows) updates in the
+    // same commit as the click. Only the optimistic indicator and changeAction
+    // run inside the transition — keeping onChange urgent avoids deferring the
+    // real page update behind the low-priority transition.
+    onChange(newPage);
     startTransition(async () => {
       setOptimisticPage(newPage);
-      onChange(newPage);
       await changeAction?.(newPage);
     });
   };

From 3e43397f2f1c6589390dfe99d786a50501465351 Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Fri, 26 Jun 2026 11:35:42 +0000
Subject: [PATCH 3/5] docs(changeset): trim Pagination changeset to
 release-note length

---
 .changeset/pagination-interruptible-button-guard.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/.changeset/pagination-interruptible-button-guard.md b/.changeset/pagination-interruptible-button-guard.md
index eaf1139f58ed..ab285b585045 100644
--- a/.changeset/pagination-interruptible-button-guard.md
+++ b/.changeset/pagination-interruptible-button-guard.md
@@ -2,13 +2,5 @@
 '@astryxdesign/core': patch
 ---
 
-[fix] Make `Pagination`'s `changeAction` interruptible with optimistic state.
-Page changes now run inside a transition and track the target page
-optimistically, so the controls (indicator, active page, prev/next enablement)
-reflect the page being navigated to while the action is pending. Rapid prev/next
-clicks now advance through pages instead of being dropped by a re-entry guard,
-and a synchronous handler that suspends (e.g. a router navigation) also drives
-the pending state — matching `ToggleButton`'s action behavior. `Button`'s
-`clickAction` keeps its single-fire guard (a re-click is a duplicate submit, not
-new intent) and now documents why.
+[fix] `Pagination`'s `changeAction` is now interruptible — page changes run in a transition with optimistic page state, so rapid prev/next clicks advance through pages instead of being dropped. `Button`'s `clickAction` keeps its single-fire guard.
 @cixzhang

From 8f800e74c9d7d03d96d2ede111886a361c34ecc8 Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Fri, 26 Jun 2026 16:04:23 +0000
Subject: [PATCH 4/5] docs(core): trim over-explained comments in
 Button/Pagination
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Condense the rationale comments added with the interruptible-action work to
match the sibling ToggleButton style — explain why, not every mechanism.
No logic changes.
---
 packages/core/src/Button/Button.test.tsx      |  3 ---
 packages/core/src/Button/Button.tsx           | 12 ++++------
 .../core/src/Pagination/Pagination.test.tsx   |  9 ++++----
 packages/core/src/Pagination/Pagination.tsx   | 23 ++++++++-----------
 4 files changed, 18 insertions(+), 29 deletions(-)

diff --git a/packages/core/src/Button/Button.test.tsx b/packages/core/src/Button/Button.test.tsx
index 85eb84eb74a5..6b70636c5b8d 100644
--- a/packages/core/src/Button/Button.test.tsx
+++ b/packages/core/src/Button/Button.test.tsx
@@ -251,9 +251,6 @@ describe('Button', () => {
   });
 
   it('fires clickAction once on a fast double-click (no double-submit)', async () => {
-    // clickAction is a fire-once command, so a second synchronous click while
-    // the first action is still pending must not fire it again. Guards the
-    // re-entry protection in handleClick from regressing.
     let resolveAction: (() => void) | undefined;
     const handleAction = vi.fn(
       async () =>
diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsx
index 03a972face11..3751f2182818 100644
--- a/packages/core/src/Button/Button.tsx
+++ b/packages/core/src/Button/Button.tsx
@@ -513,14 +513,10 @@ export function Button({
   const buttonGroup = useButtonGroup();
 
   const [isPending, startTransition] = useTransition();
-  // Synchronous re-entry guard against double-submit. Unlike a toggle (where a
-  // re-click is a *new* intent and the action should stay interruptible),
-  // clickAction is a fire-once command (submit/save/pay) — a second fire is a
-  // duplicate, not new intent. isPending and useOptimistic don't help here:
-  // neither commits within the same tick, so a fast double-click would fire
-  // clickAction twice before the disabled state lands. The ref is the only
-  // same-tick-safe dedupe — keep it. (cf. ToggleButton/Pagination, which are
-  // interruptible state transitions and intentionally have no guard.)
+  // clickAction is a fire-once command (submit/save/pay), not a state
+  // transition — a re-click is a duplicate, not new intent. Neither isPending
+  // nor useOptimistic dedupes a same-tick double-click, so this ref is the only
+  // reliable guard. Keep it (unlike the interruptible ToggleButton/Pagination).
   const actionInFlightRef = useRef(false);
   const isLoadingState = isLoading || isPending;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
diff --git a/packages/core/src/Pagination/Pagination.test.tsx b/packages/core/src/Pagination/Pagination.test.tsx
index a37879fe8d9d..6a0cc3e3ad6c 100644
--- a/packages/core/src/Pagination/Pagination.test.tsx
+++ b/packages/core/src/Pagination/Pagination.test.tsx
@@ -391,8 +391,8 @@ describe('Pagination', () => {
         />,
       );
 
-      // The committed `page` prop stays at 1 (the consumer hasn't re-rendered),
-      // but the indicator optimistically reflects the page being navigated to.
+      // The committed `page` prop stays at 1, but the indicator optimistically
+      // reflects the page being navigated to.
       await user.click(screen.getByRole('button', {name: 'Go to next page'}));
       expect(changeAction).toHaveBeenCalledWith(2);
       expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
@@ -405,9 +405,8 @@ describe('Pagination', () => {
 
     it('interrupts an in-flight action on rapid next clicks', async () => {
       // Each click derives its target from the optimistic page, so clicking
-      // next twice before the action settles advances 1 -> 2 -> 3 rather than
-      // being dropped by a re-entry guard. The consumer never re-renders here,
-      // so the committed `page` prop stays at 1 the whole time.
+      // next twice before the action settles advances 1 -> 2 -> 3 instead of
+      // being dropped by a re-entry guard.
       const resolvers: (() => void)[] = [];
       const changeAction = vi.fn(
         async () =>
diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index 53aa9199bb5c..2fe9ad7c678e 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -352,8 +352,8 @@ export function Pagination({
   const [, startTransition] = useTransition();
 
   // Track the page optimistically. While a changeAction is pending the controls
-  // reflect the page the user is navigating to, and a click mid-flight derives
-  // its target from this value — so rapid prev/next clicks advance instead of
+  // reflect the page being navigated to, and a click mid-flight derives its
+  // target from this value — so rapid prev/next clicks advance instead of
   // stalling on the last committed page.
   const [optimisticPage, setOptimisticPage] = useOptimistic(page);
 
@@ -376,21 +376,18 @@ export function Pagination({
     return null;
   }
 
-  // Run the page change inside a transition so changeAction drives a pending
-  // state. The transition is interruptible — clicking again before it settles
-  // starts a fresh transition with the next optimistic page rather than being
-  // dropped, so there is no re-entry guard. A synchronous handler that suspends
-  // (e.g. a router navigation that suspends on data) also drives the pending
-  // state, not just promises.
+  // Run the page change in a transition so changeAction drives a pending state.
+  // The transition is interruptible — clicking again before it settles starts a
+  // fresh transition with the next optimistic page rather than being dropped, so
+  // there is no re-entry guard. A synchronous handler that suspends drives the
+  // pending state too, not just promises.
   const handlePageChange = (newPage: number) => {
     if (isDisabled) {
       return;
     }
-    // Notify the consumer urgently so controlled page state (and any data it
-    // drives, e.g. the Table pagination plugin slicing rows) updates in the
-    // same commit as the click. Only the optimistic indicator and changeAction
-    // run inside the transition — keeping onChange urgent avoids deferring the
-    // real page update behind the low-priority transition.
+    // Keep onChange urgent so controlled page state updates in the same commit
+    // as the click; only the optimistic indicator and changeAction defer to the
+    // transition.
     onChange(newPage);
     startTransition(async () => {
       setOptimisticPage(newPage);

From 5a0d86bbc8f070c05201846e31a0bb786d19a753 Mon Sep 17 00:00:00 2001
From: cixzhang <cindyxz@meta.com>
Date: Fri, 26 Jun 2026 22:20:02 +0000
Subject: [PATCH 5/5] style(Button,Pagination): trim redundant inline comments

Condense the interruptible-action rationale comments to the why, dropping
mechanism narration. No logic changes.
---
 packages/core/src/Button/Button.tsx         |  6 ++----
 packages/core/src/Pagination/Pagination.tsx | 17 ++++++-----------
 2 files changed, 8 insertions(+), 15 deletions(-)

diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsx
index 3751f2182818..83fcb8623851 100644
--- a/packages/core/src/Button/Button.tsx
+++ b/packages/core/src/Button/Button.tsx
@@ -513,10 +513,8 @@ export function Button({
   const buttonGroup = useButtonGroup();
 
   const [isPending, startTransition] = useTransition();
-  // clickAction is a fire-once command (submit/save/pay), not a state
-  // transition — a re-click is a duplicate, not new intent. Neither isPending
-  // nor useOptimistic dedupes a same-tick double-click, so this ref is the only
-  // reliable guard. Keep it (unlike the interruptible ToggleButton/Pagination).
+  // clickAction is fire-once (submit/save/pay), so a same-tick double-click must
+  // dedupe — which neither isPending nor useOptimistic do. Hence the ref guard.
   const actionInFlightRef = useRef(false);
   const isLoadingState = isLoading || isPending;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index 2fe9ad7c678e..3885ffdb603f 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -351,10 +351,8 @@ export function Pagination({
 }: PaginationProps) {
   const [, startTransition] = useTransition();
 
-  // Track the page optimistically. While a changeAction is pending the controls
-  // reflect the page being navigated to, and a click mid-flight derives its
-  // target from this value — so rapid prev/next clicks advance instead of
-  // stalling on the last committed page.
+  // Track the page optimistically so rapid prev/next clicks advance from the
+  // in-flight target instead of stalling on the last committed page.
   const [optimisticPage, setOptimisticPage] = useOptimistic(page);
 
   // Compute pagination state
@@ -376,18 +374,15 @@ export function Pagination({
     return null;
   }
 
-  // Run the page change in a transition so changeAction drives a pending state.
-  // The transition is interruptible — clicking again before it settles starts a
-  // fresh transition with the next optimistic page rather than being dropped, so
-  // there is no re-entry guard. A synchronous handler that suspends drives the
-  // pending state too, not just promises.
+  // Interruptible: re-clicking before the transition settles starts a fresh one
+  // with the next optimistic page rather than being dropped, so there is no
+  // re-entry guard.
   const handlePageChange = (newPage: number) => {
     if (isDisabled) {
       return;
     }
     // Keep onChange urgent so controlled page state updates in the same commit
-    // as the click; only the optimistic indicator and changeAction defer to the
-    // transition.
+    // as the click; only the optimistic indicator and changeAction defer.
     onChange(newPage);
     startTransition(async () => {
       setOptimisticPage(newPage);