@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Pagination/Pagination.test.tsx

@@ -9,10 +9,26 @@
  * SYNC: When Pagination.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, within} from '@testing-library/react';
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  within,
+  fireEvent,
+  act,
+  waitFor,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
 
 // =============================================================================
 // generatePageRange helper
@@ -239,6 +255,65 @@ describe('Pagination', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // pageSize guarding
+  // ---------------------------------------------------------------------------
+
+  describe('pageSize guarding', () => {
+    it('does not crash the dots variant when pageSize is 0', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={5}
+          pageSize={0}
+          variant="dots"
+        />,
+      );
+      const group = screen.getByRole('group', {name: 'Page indicators'});
+      expect(within(group).getAllByRole('button')).toHaveLength(5);
+    });
+
+    it('treats NaN pageSize as the default', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={50}
+          pageSize={NaN}
+          variant="compact"
+        />,
+      );
+      expect(screen.getByText('Page 1 of 5')).toBeInTheDocument();
+    });
+
+    it('clamps negative pageSize to 1', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={5}
+          pageSize={-10}
+          variant="compact"
+        />,
+      );
+      expect(screen.getByText('Page 1 of 5')).toBeInTheDocument();
+    });
+
+    it('floors fractional pageSize', () => {
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          totalItems={50}
+          pageSize={2.5}
+          variant="compact"
+        />,
+      );
+      expect(screen.getByText('Page 1 of 25')).toBeInTheDocument();
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Variant: dots
   // ---------------------------------------------------------------------------
@@ -304,6 +379,38 @@ describe('Pagination', () => {
   // ---------------------------------------------------------------------------
 
   describe('page change callbacks', () => {
+    it('does not announce on initial mount', () => {
+      render(<Pagination page={1} onChange={() => {}} totalPages={10} />);
+      expect(politeRegion()).toBeNull();
+    });
+
+    it('announces the new page politely when navigating', async () => {
+      const user = userEvent.setup();
+      render(<Pagination page={2} onChange={() => {}} totalPages={10} />);
+      await user.click(screen.getByRole('button', {name: 'Go to page 3'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Page 3 of 10');
+      });
+    });
+
+    it('announces the next page when clicking next', async () => {
+      const user = userEvent.setup();
+      render(<Pagination page={2} onChange={() => {}} totalPages={5} />);
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Page 3 of 5');
+      });
+    });
+
+    it('announces without a total when only hasMore is known', async () => {
+      const user = userEvent.setup();
+      render(<Pagination page={1} onChange={() => {}} hasMore />);
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Page 2');
+      });
+    });
+
     it('calls onChange when clicking a page button', async () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
@@ -346,6 +453,145 @@ 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, 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(
+        within(screen.getByRole('navigation')).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 instead of
+      // being dropped by a re-entry guard.
+      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'});
+      const nav = screen.getByRole('navigation');
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      // Scope to the nav landmark: the live region on document.body also
+      // carries the announced page text.
+      expect(within(nav).getByText('Page 2 of 5')).toBeInTheDocument();
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(within(nav).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 +705,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 +721,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'}));

package/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,
@@ -34,6 +34,7 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Selector} from '../Selector';
 import {Text} from '../Text';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -335,7 +336,7 @@ export function Pagination({
   totalItems,
   totalPages: totalPagesProp,
   hasMore,
-  pageSize = 10,
+  pageSize: pageSizeProp = 10,
   pageSizeOptions,
   onPageSizeChange,
   variant = 'pages',
@@ -349,16 +350,36 @@ export function Pagination({
   style,
   ref,
 }: PaginationProps) {
-  const [isPending, startTransition] = useTransition();
+  const [, startTransition] = useTransition();
+
+  // pageSize is typed as number, so 0, NaN, and negatives are valid at the
+  // type level but yield Infinity/NaN page counts, and
+  // Array.from({length: Infinity}) crashes the dots variant. Coerce to a
+  // positive integer; non-finite values fall back to the default.
+  const pageSize = Number.isFinite(pageSizeProp)
+    ? Math.max(1, Math.floor(pageSizeProp))
+    : 10;
+
+  // Announce page changes politely (navigation-10). The controls carry no
+  // live region, so page transitions were previously silent to screen readers.
+  // Only user-driven changes go through handlePageChange, so initial mount is
+  // never announced.
+  const announce = useAnnounce();
+
+  // 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
   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 +389,52 @@ export function Pagination({
     return null;
   }
 
+  // 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 || isPending) {
+    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.
     onChange(newPage);
-    if (changeAction) {
-      startTransition(async () => {
-        await changeAction(newPage);
-      });
-    }
+    announce(
+      computedTotalPages != null
+        ? `Page ${newPage} of ${computedTotalPages}`
+        : `Page ${newPage}`,
+    );
+    startTransition(async () => {
+      setOptimisticPage(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 +446,7 @@ export function Pagination({
           return null;
         }
         const pageRange = generatePageRange(
-          page,
+          optimisticPage,
           computedTotalPages,
           siblingCount,
         );
@@ -443,7 +468,7 @@ export function Pagination({
                   </span>
                 );
               }
-              const isActive = item === page;
+              const isActive = item === optimisticPage;
               return (
                 <Button
                   key={item}
@@ -483,7 +508,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 +528,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,
                   ),
                 )}

package/src/Popover/usePopover.doc.mjs

@@ -14,7 +14,9 @@ export const docs = {
     {name: 'hasAutoFocus', type: 'boolean', description: 'Whether to automatically focus the first focusable element when opened.', default: 'true'},
     {name: 'hasCloseButton', type: 'boolean', description: 'Whether to include a hidden close button that appears for keyboard users.', default: 'true'},
     {name: 'closeButtonLabel', type: 'string', description: 'Accessible label for the hidden close button.', default: "'Close popover'"},
-    {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog. Provide one when there is no visible title.'},
+    {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog (only applies when role is "dialog"). Provide one when there is no visible title.'},
+    {name: 'role', type: "'dialog' | 'none'", description: 'ARIA role on the content wrapper. Use "dialog" for genuine dialog content; use "none" for listbox/menu popups whose own content role should be exposed and whose trigger keeps DOM focus.', default: "'dialog'"},
+    {name: 'isModal', type: 'boolean', description: 'Whether a dialog-role popover is modal (aria-modal). Only applies when role is "dialog".', default: 'true'},
     {name: 'hasSurface', type: 'boolean', description: 'Whether to apply the default popover surface background, radius, and shadow.', default: 'true'},
   ],
   returns: [
@@ -27,7 +29,7 @@ export const docs = {
     {name: 'isOpen', type: 'boolean', description: 'Whether the popover is currently open.'},
     {name: 'id', type: 'string', description: 'Unique ID for aria-describedby or aria-controls.'},
     {name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here.'},
-    {name: 'triggerProps', type: '{aria-haspopup: "dialog"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element.'},
+    {name: 'triggerProps', type: '{aria-haspopup: "dialog" | "true"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element. aria-haspopup reflects the popover role.'},
   ],
   usage: {
     description: 'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation.',
@@ -54,7 +56,9 @@ export const docsDense = {
     hasAutoFocus: 'whether first focusable element receives focus on open.',
     hasCloseButton: 'whether hidden keyboard close button is included.',
     closeButtonLabel: 'label for hidden close button.',
-    dialogLabel: 'accessible label for popover dialog.',
+    dialogLabel: 'accessible label for popover dialog (role="dialog" only).',
+    role: 'content wrapper ARIA role; "none" for listbox/menu popups.',
+    isModal: 'whether a dialog-role popover is modal (aria-modal).',
     hasSurface: 'apply default surface background/radius/shadow.',
   },
   returnDescriptions: {

package/src/Popover/usePopover.tsx

@@ -130,10 +130,35 @@ export interface UsePopoverOptions {
 
   /**
    * Accessible label for the dialog.
-   * Required for screen readers to announce the dialog purpose.
+   * Required for screen readers to announce the dialog purpose
+   * (only applies when `role` is `'dialog'`).
    */
   dialogLabel?: string;
 
+  /**
+   * ARIA role stamped on the popover content wrapper.
+   *
+   * - `'dialog'` (default): the wrapper is a `role="dialog"` and, when
+   *   `isModal` is true, carries `aria-modal`. Use for genuine dialog content.
+   * - `'none'`: the wrapper carries no role or `aria-modal`, so the popup's own
+   *   content role (e.g. a child `role="listbox"` or `role="menu"`) is the
+   *   exposed semantics. Use for comboboxes, listboxes, and menus — their
+   *   trigger keeps DOM focus, so announcing an unnamed modal dialog around
+   *   them is incorrect.
+   *
+   * @default 'dialog'
+   */
+  role?: 'dialog' | 'none';
+
+  /**
+   * Whether the dialog is modal (`aria-modal`). Only applies when `role` is
+   * `'dialog'`. Set to `false` for non-modal dialogs that do not inert the rest
+   * of the page.
+   *
+   * @default true
+   */
+  isModal?: boolean;
+
   /**
    * Whether to apply the default popover surface (background, border-radius,
    * box-shadow) to the content wrapper.
@@ -215,7 +240,7 @@ export interface UsePopoverReturn {
    * ARIA attributes to spread on the trigger element
    */
   triggerProps: {
-    'aria-haspopup': 'dialog';
+    'aria-haspopup': 'dialog' | 'true';
     'aria-expanded': boolean;
     'aria-controls': string;
   };
@@ -274,6 +299,8 @@ export function usePopover(
     hasCloseButton = true,
     closeButtonLabel = 'Close popover',
     dialogLabel,
+    role = 'dialog',
+    isModal = true,
   } = options;
 
   // Track the trigger element for returning focus
@@ -339,20 +366,34 @@ export function usePopover(
 
   // ARIA attributes for the trigger
   const triggerProps = {
-    'aria-haspopup': 'dialog' as const,
+    'aria-haspopup': role === 'dialog' ? ('dialog' as const) : ('true' as const),
     'aria-expanded': layer.isOpen,
     'aria-controls': layer.id,
   };
 
+  // Dev-time guardrail: a dialog popover should always be labeled. Warn once
+  // per hook instance (in an effect) rather than on every render.
+  const warnedUnnamedDialogRef = useRef(false);
+  useEffect(() => {
+    if (role === 'dialog' && !dialogLabel && !warnedUnnamedDialogRef.current) {
+      warnedUnnamedDialogRef.current = true;
+      console.warn(
+        'usePopover: role="dialog" without a `dialogLabel` renders an unnamed ' +
+          'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
+          'popups whose content already carries its own role.',
+      );
+    }
+  }, [role, dialogLabel]);
+
   // Wrapped render function that includes surface styles and optional hidden close button
   const render = useCallback(
     (children: ReactNode, props?: ContextRenderProps): ReactNode => {
       return layer.render(
         <div
           ref={contentRef}
-          role="dialog"
-          aria-modal="true"
-          aria-label={dialogLabel}
+          role={role === 'dialog' ? 'dialog' : undefined}
+          aria-modal={role === 'dialog' && isModal ? true : undefined}
+          aria-label={role === 'dialog' ? dialogLabel : undefined}
           {...stylex.props(
             styles.contentWrapper,
             hasSurface && styles.surface,
@@ -379,6 +420,8 @@ export function usePopover(
       closeButtonLabel,
       contentRef,
       dialogLabel,
+      role,
+      isModal,
       xstyle,
     ],
   );

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -71,6 +71,12 @@ export const docs = {
       description: 'Disables the entire component.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -136,6 +142,7 @@ export const docs = {
       { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
       { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
       { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -212,6 +219,12 @@ export const docsZh = {
       description: '禁用整个组件。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the search is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled PowerSearch in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -269,6 +282,7 @@ export const docsZh = {
       { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
       { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
       { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
 };
@@ -284,6 +298,7 @@ export const docsDense = {
       { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
       { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
       { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
+      { guidance: false, description: 'Wrap a disabled PowerSearch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
     ],
   },
   propDescriptions: {