@astryxdesign/core 0.1.2 → 0.1.3

package/dist/NavMenu/NavHeadingMenu.js

@@ -11,12 +11,13 @@
  * SYNC: When modified, update:
  * - /packages/core/src/NavMenu/index.ts
  */
-import React, { useMemo } from 'react';
+import React, { useCallback, useMemo } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useListFocus } from "../hooks/useListFocus.js";
+import { useTypeahead } from "../hooks/useTypeahead.js";
 import { themeProps } from "../utils/themeProps.js";
 import { NavHeadingMenuContext, useNavHeadingCloseContext } from "./NavMenuContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -79,10 +80,40 @@ export function NavHeadingMenu({
   const closeMenu = closeCtx?.closeMenu;
   const {
     listRef,
-    handleKeyDown
+    handleKeyDown,
+    focusItem
   } = useListFocus({
+    itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',
     onEscape: closeMenu
   });
+
+  // First-character typeahead over the (enabled) menu items (menus-11).
+  const getMenuItems = useCallback(() => listRef.current ? Array.from(listRef.current.querySelectorAll('[role="menuitem"]:not([aria-disabled="true"])')) : [], [listRef]);
+  const typeahead = useTypeahead({
+    getItemLabels: () => getMenuItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () => getMenuItems().findIndex(el => el === document.activeElement || el.contains(document.activeElement))
+  });
+
+  // Extend useListFocus with Enter/Space activation. Items rendered without an
+  // `href` are `<div role="menuitem">` elements, which have no native keyboard
+  // activation — without this, Enter/Space on a focused onClick-only item does
+  // nothing. Anchor items (with `href`) already activate on Enter natively.
+  const listKeyDown = useCallback(e => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      const focused = document.activeElement;
+      if (focused?.getAttribute('role') === 'menuitem') {
+        e.preventDefault();
+        focused.click();
+        return;
+      }
+    }
+    if (typeahead.onKeyDown(e)) {
+      e.preventDefault();
+      return;
+    }
+    handleKeyDown(e);
+  }, [handleKeyDown, typeahead]);
   const ctx = useMemo(() => ({
     closeMenu: closeMenu ?? (() => {}),
     size
@@ -96,7 +127,7 @@ export function NavHeadingMenu({
     children: /*#__PURE__*/_jsx("div", {
       ref: mergeRefs(ref, listRef),
       role: "menu",
-      onKeyDown: handleKeyDown,
+      onKeyDown: listKeyDown,
       "data-testid": testId,
       ...mergeProps(themeProps('nav-heading-menu', {
         size

package/dist/NumberInput/NumberInput.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file NumberInput.tsx
- * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon
+ * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon, InputGroupContext
  * @output Exports NumberInput component, NumberInputProps
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
@@ -61,6 +61,27 @@ interface NumberInputPropsBase extends Omit<BaseProps, 'onChange' | 'defaultValu
      * @default false
      */
     isDisabled?: boolean;
+    /**
+     * Explains why the input is disabled. When set together with `isDisabled`,
+     * the input shows a tooltip with this text on hover and keyboard focus, and
+     * stays focusable (via `aria-disabled`) so the reason is discoverable by
+     * keyboard and assistive technology. The field cannot be edited (it becomes
+     * read-only) while disabled.
+     *
+     * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+     * controls don't emit the pointer events an external tooltip needs.
+     *
+     * @example
+     * ```
+     * <NumberInput
+     *   label="Quantity"
+     *   value={quantity}
+     *   isDisabled
+     *   disabledMessage="Editing is locked while the order is processing"
+     * />
+     * ```
+     */
+    disabledMessage?: string;
     /**
      * Icon to display at the start of the input.
      * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -186,7 +207,7 @@ export type NumberInputProps = NumberInputPropsNonClearable | NumberInputPropsCl
  * <NumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />
  * ```
  */
-export declare function NumberInput({ label, isLabelHidden, description, isOptional, isRequired, isDisabled, startIcon, labelIcon, status, size: sizeProp, onChange, value, placeholder, labelTooltip, hasAutoFocus, htmlName, autoComplete, min, max, step, units, isIntegerOnly, onFocus, onBlur, hasClear, onEnter, onKeyDown, width, xstyle, className, style, ref, ...rest }: NumberInputProps): import("react").JSX.Element;
+export declare function NumberInput({ label, isLabelHidden, description, isOptional, isRequired, isDisabled, disabledMessage, startIcon, labelIcon, status, size: sizeProp, onChange, value, placeholder, labelTooltip, hasAutoFocus, htmlName, autoComplete, min, max, step, units, isIntegerOnly, onFocus, onBlur, hasClear, onEnter, onKeyDown, width, xstyle, className, style, ref, ...rest }: NumberInputProps): import("react").JSX.Element;
 export declare namespace NumberInput {
     var displayName: string;
 }

package/dist/NumberInput/NumberInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NumberInput.d.ts","sourceRoot":"","sources":["../../src/NumberInput/NumberInput.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"NumberInput.d.ts","sourceRoot":"","sources":["../../src/NumberInput/NumberInput.tsx"],"names":[],"mappings":"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"}

package/dist/NumberInput/NumberInput.js

@@ -4,7 +4,7 @@
 
 /**
  * @file NumberInput.tsx
- * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon
+ * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon, InputGroupContext
  * @output Exports NumberInput component, NumberInputProps
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
@@ -21,6 +21,9 @@ import "../theme/tokens.stylex.js";
 import { colorVars, sizeVars, radiusVars, typographyVars, typeScaleVars, borderVars } from "../theme/tokens.stylex.js";
 import { Field, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles } from "../Field/index.js";
 import { Icon, renderIconSlot } from "../Icon/index.js";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
+import { useTooltip } from "../Tooltip/index.js";
+import { getInputARIA } from "../utils/index.js";
 import { useSize } from "../SizeContext/SizeContext.js";
 import { useInputContainer } from "../hooks/useInputContainer.js";
 import { useInputGroup } from "../InputGroup/InputGroupContext.js";
@@ -55,7 +58,7 @@ import { themeProps } from "../utils/themeProps.js";
  * Without `hasClear`, onChange only receives valid numbers.
  * With `hasClear`, onChange also receives `null` when the user clears the input.
  */
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
  * Parse and validate a string input as a number.
  * Returns null if the input is not a valid number or fails validation.
@@ -104,6 +107,7 @@ export function NumberInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   startIcon,
   labelIcon,
   status,
@@ -134,6 +138,7 @@ export function NumberInput({
 }) {
   const size = useSize(sizeProp, 'md');
   const id = useId();
+  const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef(null);
@@ -142,6 +147,20 @@ export function NumberInput({
 
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState(null);
+
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input container (which already exists) and
+  // the input stays perceivable via aria-disabled instead of the native
+  // disabled attribute. The field is made read-only so it can't be typed into,
+  // and value mutation is blocked by the isDisabled guard in the handlers.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage
+  });
   const statusIconMap = {
     warning: 'warning',
     error: 'error',
@@ -152,7 +171,10 @@ export function NumberInput({
     error: 'error',
     success: 'success'
   };
-  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null].filter(Boolean).join(' ') || undefined;
+  const {
+    ariaLabelledBy,
+    ariaDescribedBy
+  } = getInputARIA(inputLabelID, [description ? descriptionID : null, status?.message ? statusMessageID : null, showsDisabledMessage ? disabledMessageTooltip.describedBy : null], inputGroup);
 
   // Display value: pending input if typing, otherwise the raw value
   // Note: With type="number", we can't use formatted display values
@@ -180,6 +202,12 @@ export function NumberInput({
 
   // Handle input text change - update immediately if valid
   const handleInputChange = useCallback(e => {
+    // Value can't change while showing a disabled message (the field is
+    // read-only and non-native-disabled), but guard the handler too so the
+    // pending value and onChange never fire.
+    if (isDisabled) {
+      return;
+    }
     const newValue = e.target.value;
     setPendingInput(newValue);
 
@@ -192,7 +220,7 @@ export function NumberInput({
     if (parsed !== null && parsed !== value) {
       onChange(parsed);
     }
-  }, [value, onChange, min, max, isIntegerOnly]);
+  }, [value, onChange, min, max, isIntegerOnly, isDisabled]);
 
   // Handle focus
   const handleFocus = useCallback(e => {
@@ -255,7 +283,13 @@ export function NumberInput({
     disabled: isDisabled
   });
   const inputWrapper = /*#__PURE__*/_jsxs("div", {
-    ref: containerRef,
+    ref: el => {
+      containerRef.current = el;
+      // Anchor + hover/focus listeners for the disabled-message tooltip.
+      // Handlers are gated internally by isEnabled, and anchor names
+      // compose, so attaching unconditionally is safe.
+      disabledMessageTooltip.ref(el);
+    },
     onClick: handleWrapperClick,
     onMouseUp: handleWrapperMouseUp,
     ...mergeProps(themeProps('number-input', {
@@ -265,6 +299,9 @@ export function NumberInput({
     children: [startIcon && renderIconSlot(startIcon, {
       size: 'sm',
       color: 'secondary'
+    }), inputGroup && /*#__PURE__*/_jsx(VisuallyHidden, {
+      id: inputLabelID,
+      children: label
     }), /*#__PURE__*/_jsx("input", {
       ...rest,
       ref: mergeRefs(ref, inputRef),
@@ -277,8 +314,14 @@ export function NumberInput({
       onFocus: handleFocus,
       onBlur: handleBlur,
       onKeyDown: handleKeyDown,
-      placeholder: placeholder,
-      disabled: isDisabled,
+      placeholder: placeholder
+      // With a disabledMessage the input keeps focusability via aria-disabled
+      // so the reason is focus-discoverable; readOnly + the handler guards
+      // keep the value from changing.
+      ,
+      disabled: isDisabled && !showsDisabledMessage,
+      "aria-disabled": showsDisabledMessage ? 'true' : undefined,
+      readOnly: showsDisabledMessage || undefined,
       autoFocus: hasAutoFocus,
       "data-autofocus": hasAutoFocus || undefined,
       min: min ?? undefined,
@@ -286,8 +329,8 @@ export function NumberInput({
       step: step ?? undefined,
       "aria-describedby": ariaDescribedBy,
       "aria-required": isRequired === true ? 'true' : undefined,
-      "aria-invalid": status?.type === 'error' ? 'true' : undefined,
-      "aria-label": inputGroup ? label : undefined,
+      "aria-invalid": status?.type === 'error' || !isInputValid ? 'true' : undefined,
+      "aria-labelledby": ariaLabelledBy,
       ...{
         0: {
           className: "x1lliihq x98rzlu xeuugli xc342km xng3xce x1717udv x9ynric xjm74w1 x6pjikd xw6l6zx x1tgivj0 xjbqb8w x1a2a7pz xeyghm5"
@@ -307,6 +350,11 @@ export function NumberInput({
         className: "x9ynric xjm74w1 xw6l6zx xv1l7n4 x2lah0s"
       },
       children: units
+    }), /*#__PURE__*/_jsx(VisuallyHidden, {
+      as: "div",
+      role: "alert",
+      "aria-live": "assertive",
+      children: !isInputValid ? 'Invalid number' : ''
     }), hasClear && value != null && !isDisabled && /*#__PURE__*/_jsx("button", {
       type: "button",
       onClick: handleClear,
@@ -326,9 +374,11 @@ export function NumberInput({
     })]
   });
   if (inputGroup) {
-    return inputWrapper;
+    return /*#__PURE__*/_jsxs(_Fragment, {
+      children: [inputWrapper, showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
+    });
   }
-  return /*#__PURE__*/_jsx(Field, {
+  return /*#__PURE__*/_jsxs(Field, {
     label: label,
     isLabelHidden: isLabelHidden,
     description: description,
@@ -345,7 +395,7 @@ export function NumberInput({
     } : undefined,
     labelTooltip: labelTooltip,
     width: width,
-    children: inputWrapper
+    children: [inputWrapper, showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
   });
 }
 NumberInput.displayName = 'NumberInput';

package/dist/Pagination/Pagination.d.ts

@@ -116,7 +116,7 @@ export declare function generatePageRange(currentPage: number, totalPages: numbe
  * />
  * ```
  */
-export declare function Pagination({ page, onChange, changeAction, totalItems, totalPages: totalPagesProp, hasMore, pageSize, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled, label, 'data-testid': testId, xstyle, className, style, ref, }: PaginationProps): import("react").JSX.Element | null;
+export declare function Pagination({ page, onChange, changeAction, totalItems, totalPages: totalPagesProp, hasMore, pageSize: pageSizeProp, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled, label, 'data-testid': testId, xstyle, className, style, ref, }: PaginationProps): import("react").JSX.Element | null;
 export declare namespace Pagination {
     var displayName: string;
 }

package/dist/Pagination/Pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pagination.d.ts","sourceRoot":"","sources":["../../src/Pagination/Pagination.tsx"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,oBAAoB,CAAC;AAE3D,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzC,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,WAAW,CAAC,EACtB,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGtD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAGlB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAG9C;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAGtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IAGrB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAiGD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,CAAC,MAAM,GAAG,KAAK,CAAC,EAAE,CA6CpB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,UAAU,EAAE,cAAc,EAC1B,OAAO,EACP,QAAa,EACb,eAAe,EACf,gBAAgB,EAChB,OAAiB,EACjB,YAAgB,EAChB,IAAW,EACX,UAAkB,EAClB,KAAoB,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,GACJ,EAAE,eAAe,sCA8OjB;yBAlQe,UAAU"}
+{"version":3,"file":"Pagination.d.ts","sourceRoot":"","sources":["../../src/Pagination/Pagination.tsx"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAO5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,oBAAoB,CAAC;AAE3D,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzC,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,WAAW,CAAC,EACtB,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGtD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAGlB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAG9C;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAGtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IAGrB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAiGD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,CAAC,MAAM,GAAG,KAAK,CAAC,EAAE,CA6CpB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,UAAU,EAAE,cAAc,EAC1B,OAAO,EACP,QAAQ,EAAE,YAAiB,EAC3B,eAAe,EACf,gBAAgB,EAChB,OAAiB,EACjB,YAAgB,EAChB,IAAW,EACX,UAAkB,EAClB,KAAoB,EACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,GACJ,EAAE,eAAe,sCAiQjB;yBArRe,UAAU"}

package/dist/Pagination/Pagination.js

@@ -26,6 +26,7 @@ import { Button } from "../Button/index.js";
 import { Icon } from "../Icon/index.js";
 import { Selector } from "../Selector/index.js";
 import { Text } from "../Text/index.js";
+import { useAnnounce } from "../hooks/useAnnounce.js";
 import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 
@@ -159,7 +160,7 @@ export function Pagination({
   totalItems,
   totalPages: totalPagesProp,
   hasMore,
-  pageSize = 10,
+  pageSize: pageSizeProp = 10,
   pageSizeOptions,
   onPageSizeChange,
   variant = 'pages',
@@ -175,6 +176,18 @@ export function Pagination({
 }) {
   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);
@@ -202,6 +215,7 @@ export function Pagination({
     // Keep onChange urgent so controlled page state updates in the same commit
     // as the click; only the optimistic indicator and changeAction defer.
     onChange(newPage);
+    announce(computedTotalPages != null ? `Page ${newPage} of ${computedTotalPages}` : `Page ${newPage}`);
     startTransition(async () => {
       setOptimisticPage(newPage);
       await changeAction?.(newPage);

package/dist/Popover/Popover.d.ts

@@ -128,6 +128,22 @@ export interface PopoverProps extends Pick<BaseProps, 'xstyle' | 'className' | '
      * @default true
      */
     hasAutoFocus?: boolean;
+    /**
+     * Whether clicking outside dismisses the popover.
+     * Set to `false` for surfaces that should stay open until explicitly
+     * dismissed, like onboarding coachmarks or multi-step flows.
+     * @default true
+     */
+    hasLightDismiss?: boolean;
+    /**
+     * Whether pressing Escape dismisses the popover.
+     *
+     * Only takes full effect together with `hasLightDismiss={false}`: with
+     * light dismiss on, the browser's native light dismiss also closes on
+     * Escape. Set both to `false` for explicit-dismiss-only surfaces.
+     * @default true
+     */
+    hasEscapeDismiss?: boolean;
     /**
      * Test ID for the popover container.
      */
@@ -144,7 +160,7 @@ export interface PopoverProps extends Pick<BaseProps, 'xstyle' | 'className' | '
  * (immune to pressed-state transforms like `:active { scale(0.98) }`).
  *
  * Focus is trapped inside the popover when open.
- * Supports light dismiss (click outside or Escape to close).
+ * Supports light dismiss by default (click outside or Escape to close).
  *
  * For hover-triggered overlays, use {@link HoverCard} instead.
  *
@@ -168,7 +184,7 @@ export interface PopoverProps extends Pick<BaseProps, 'xstyle' | 'className' | '
  * />
  * ```
  */
-export declare function Popover({ children, anchorRef, content, placement, alignment, isOpen, onOpenChange, isEnabled, width, label, hasCloseButton, closeButtonLabel, hasAutoFocus, xstyle, className, style, 'data-testid': testId, }: PopoverProps): ReactElement;
+export declare function Popover({ children, anchorRef, content, placement, alignment, isOpen, onOpenChange, isEnabled, width, label, hasCloseButton, closeButtonLabel, hasAutoFocus, hasLightDismiss, hasEscapeDismiss, xstyle, className, style, 'data-testid': testId, }: PopoverProps): ReactElement;
 export declare namespace Popover {
     var displayName: string;
 }

package/dist/Popover/Popover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Popover.d.ts","sourceRoot":"","sources":["../../src/Popover/Popover.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,EAGZ,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AA4BtE;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC,sCAAsC;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,+DAA+D;IAC/D,eAAe,EAAE,QAAQ,CAAC;IAC1B,6DAA6D;IAC7D,eAAe,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,yBAAyB,KAAK,SAAS,CAAC,CAAC;IAEzE;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAEzC;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,SAAS,EACT,OAAO,EACP,SAAmB,EACnB,SAAmB,EACnB,MAAM,EACN,YAAY,EACZ,SAAgB,EAChB,KAAK,EACL,KAAK,EACL,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,GACtB,EAAE,YAAY,GAAG,YAAY,CA+Q7B;yBAjSe,OAAO"}
+{"version":3,"file":"Popover.d.ts","sourceRoot":"","sources":["../../src/Popover/Popover.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,EAGZ,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AA4BtE;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC,sCAAsC;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,+DAA+D;IAC/D,eAAe,EAAE,QAAQ,CAAC;IAC1B,6DAA6D;IAC7D,eAAe,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,yBAAyB,KAAK,SAAS,CAAC,CAAC;IAEzE;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAEzC;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,SAAS,EACT,OAAO,EACP,SAAmB,EACnB,SAAmB,EACnB,MAAM,EACN,YAAY,EACZ,SAAgB,EAChB,KAAK,EACL,KAAK,EACL,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAsB,EACtB,gBAAuB,EACvB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,GACtB,EAAE,YAAY,GAAG,YAAY,CAgR7B;yBApSe,OAAO"}

package/dist/Popover/Popover.js

@@ -97,7 +97,7 @@ const styles = {
  * (immune to pressed-state transforms like `:active { scale(0.98) }`).
  *
  * Focus is trapped inside the popover when open.
- * Supports light dismiss (click outside or Escape to close).
+ * Supports light dismiss by default (click outside or Escape to close).
  *
  * For hover-triggered overlays, use {@link HoverCard} instead.
  *
@@ -135,6 +135,8 @@ export function Popover({
   hasCloseButton,
   closeButtonLabel,
   hasAutoFocus,
+  hasLightDismiss = true,
+  hasEscapeDismiss = true,
   xstyle,
   className,
   style,
@@ -154,7 +156,8 @@ export function Popover({
   }, [onOpenChange]);
   const popover = usePopover({
     dialogLabel: label,
-    hasLightDismiss: true,
+    hasLightDismiss,
+    hasEscapeDismiss,
     hasCloseButton,
     closeButtonLabel,
     hasAutoFocus,

package/dist/Popover/usePopover.d.ts

@@ -42,6 +42,18 @@ export interface UsePopoverOptions {
      * @default true
      */
     hasLightDismiss?: boolean;
+    /**
+     * Whether pressing Escape dismisses the popover.
+     *
+     * Takes effect together with `hasLightDismiss: false`: with light dismiss
+     * on, the native popover uses `popover="auto"`, whose browser-level light
+     * dismiss also closes on Escape, so Escape handling stays registered to
+     * keep topmost-only dismissal intact. Set both to `false` for
+     * explicit-dismiss-only surfaces like onboarding coachmarks.
+     *
+     * @default true
+     */
+    hasEscapeDismiss?: boolean;
     /**
      * Whether to automatically focus the first focusable element when opened.
      * @default true
@@ -60,9 +72,32 @@ export interface UsePopoverOptions {
     closeButtonLabel?: string;
     /**
      * 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.
@@ -136,7 +171,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;
     };
@@ -148,7 +183,7 @@ export interface UsePopoverReturn {
  * - `useLayer` for popover positioning using CSS anchor positioning
  * - `useFocusTrap` for trapping focus within the popover content
  * - Auto-focus first element on open
- * - Escape key to close
+ * - Escape key to close (configurable via hasEscapeDismiss)
  * - Hidden close button that reveals on focus for accessibility
  *
  * The render function automatically wraps your content in a focus trap container

package/dist/Popover/usePopover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopover.d.ts","sourceRoot":"","sources":["../../src/Popover/usePopover.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE5E,OAAO,EAAW,KAAK,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAEpE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAyDnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAE7C;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IAEpD;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAEvE;;OAEG;IACH,YAAY,EAAE;QACZ,eAAe,EAAE,QAAQ,CAAC;QAC1B,eAAe,EAAE,OAAO,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAoIlB"}
+{"version":3,"file":"usePopover.d.ts","sourceRoot":"","sources":["../../src/Popover/usePopover.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE5E,OAAO,EAAW,KAAK,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAEpE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAyDnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAE7C;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IAEpD;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAEvE;;OAEG;IACH,YAAY,EAAE;QACZ,eAAe,EAAE,QAAQ,GAAG,MAAM,CAAC;QACnC,eAAe,EAAE,OAAO,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CA0J5E"}

package/dist/Popover/usePopover.js

@@ -50,7 +50,7 @@ const styles = {
  * - `useLayer` for popover positioning using CSS anchor positioning
  * - `useFocusTrap` for trapping focus within the popover content
  * - Auto-focus first element on open
- * - Escape key to close
+ * - Escape key to close (configurable via hasEscapeDismiss)
  * - Hidden close button that reveals on focus for accessibility
  *
  * The render function automatically wraps your content in a focus trap container
@@ -89,11 +89,14 @@ export function usePopover(options = {}) {
     onHide,
     xstyle,
     hasLightDismiss = true,
+    hasEscapeDismiss = true,
     hasAutoFocus = true,
     hasSurface = true,
     hasCloseButton = true,
     closeButtonLabel = 'Close popover',
-    dialogLabel
+    dialogLabel,
+    role = 'dialog',
+    isModal = true
   } = options;
 
   // Track the trigger element for returning focus
@@ -110,13 +113,15 @@ export function usePopover(options = {}) {
     onHide
   });
 
-  // Focus trap for the popover content
+  // Focus trap for the popover content. Escape stays registered while light
+  // dismiss is on (native popover="auto" closes on Escape regardless), so a
+  // host Dialog keeps deferring to this trap instead of double-dismissing.
   const {
     containerRef: contentRef,
     focusFirst
   } = useFocusTrap({
     isActive: layer.isOpen,
-    onEscape: layer.hide
+    onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined
   });
 
   // Auto-focus first element when popover opens (unless skipped)
@@ -156,18 +161,28 @@ export function usePopover(options = {}) {
 
   // ARIA attributes for the trigger
   const triggerProps = {
-    'aria-haspopup': 'dialog',
+    'aria-haspopup': role === 'dialog' ? 'dialog' : 'true',
     '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, props) => {
     return layer.render(/*#__PURE__*/_jsxs("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, xstyle),
       children: [children, hasCloseButton && /*#__PURE__*/_jsx("div", {
         ...{
@@ -183,7 +198,7 @@ export function usePopover(options = {}) {
       ...props,
       xstyle: props?.xstyle
     });
-  }, [layer, hasCloseButton, hasSurface, closeButtonLabel, contentRef, dialogLabel, xstyle]);
+  }, [layer, hasCloseButton, hasSurface, closeButtonLabel, contentRef, dialogLabel, role, isModal, xstyle]);
   return {
     triggerRef,
     contentRef,

package/dist/PowerSearch/PowerSearch.d.ts

@@ -37,6 +37,16 @@ export interface PowerSearchProps extends Omit<BaseProps<HTMLElement>, 'onChange
     isReadOnly?: boolean;
     /** Whether the input is disabled. @default false */
     isDisabled?: boolean;
+    /**
+     * Explains why the search is disabled. When set together with `isDisabled`,
+     * the search shows a tooltip with this text on hover and keyboard focus, and
+     * the input stays focusable (via `aria-disabled`) so the reason is
+     * discoverable by keyboard and assistive technology. Input stays blocked.
+     *
+     * Use this instead of wrapping a disabled PowerSearch in `Tooltip` — disabled
+     * controls don't emit the pointer events an external tooltip needs.
+     */
+    disabledMessage?: string;
     /**
      * Icon to display at the start of the input.
      * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -155,7 +165,7 @@ export interface PowerSearchProps extends Omit<BaseProps<HTMLElement>, 'onChange
  * };
  * ```
  */
-export declare function PowerSearch({ config: configProp, filters, onChange, label, isLabelHidden, placeholder, hasAutoFocus, hasClear, isReadOnly, isDisabled, startIcon, onFocus, onBlur, status, maxTokenLength, popoverSaveButtonLabel, timezoneID, tokenOverflowBehavior, endContent, resultCount, ref, handleRef, size: sizeProp, 'data-testid': testId, xstyle, className, style, components: componentOverrides, }: PowerSearchProps): React.JSX.Element;
+export declare function PowerSearch({ config: configProp, filters, onChange, label, isLabelHidden, placeholder, hasAutoFocus, hasClear, isReadOnly, isDisabled, disabledMessage, startIcon, onFocus, onBlur, status, maxTokenLength, popoverSaveButtonLabel, timezoneID, tokenOverflowBehavior, endContent, resultCount, ref, handleRef, size: sizeProp, 'data-testid': testId, xstyle, className, style, components: componentOverrides, }: PowerSearchProps): React.JSX.Element;
 export declare namespace PowerSearch {
     var displayName: string;
 }