@chassis-ui/react 0.1.0 → 0.1.1

package/src/components/otp-input/OtpInput.tsx

@@ -14,6 +14,7 @@ import { useControllableState, useForkedRef, useFormField } from '../../hooks'
 import { validationClassName } from '../../utils/validationClassName'
 import { renderFormField } from '../form-field/renderFormField'
 import { OtpBox } from './OtpBox'
+import { isRTL } from '../../utils/direction'
 
 export interface OtpInputProps extends Omit<
   HTMLAttributes<HTMLDivElement>,
@@ -101,9 +102,9 @@ export interface OtpInputProps extends Omit<
    */
   separator?: ReactNode
   /**
-   * Size the boxes small or large.
+   * Size the boxes sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   /**
    * Set component validation state to valid.
    */
@@ -218,17 +219,17 @@ export const OtpInput = forwardRef<HTMLDivElement, OtpInputProps>(
           commit(nextBoxes)
           break
         }
-        case 'ArrowLeft': {
-          if (index > 0) {
-            event.preventDefault()
-            focusBox(index - 1)
-          }
-          break
-        }
+        // Arrow keys move by *visual* direction, so they mirror under RTL: the box to the left of
+        // the focused one is the next box, not the previous. `Carousel` and `MenuSubmenu` already
+        // mirror their own arrow handling this way; this used to hardcode the LTR mapping and sent
+        // an RTL user backwards through the field.
+        case 'ArrowLeft':
         case 'ArrowRight': {
-          if (index < total - 1) {
+          const movesForward = (event.key === 'ArrowRight') !== isRTL(event.currentTarget)
+          const nextIndex = movesForward ? index + 1 : index - 1
+          if (nextIndex >= 0 && nextIndex < total) {
             event.preventDefault()
-            focusBox(index + 1)
+            focusBox(nextIndex)
           }
           break
         }

package/src/components/pagination/Pagination.tsx

@@ -67,9 +67,9 @@ export interface PaginationProps extends HTMLAttributes<HTMLElement> {
    */
   showPrevNext?: boolean
   /**
-   * Size the component small or large.
+   * Size the component sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
 }
 
 function getPageRange(activePage: number, pages: number, maxVisible: number): (number | '...')[] {

package/src/components/pagination/PaginationItem.tsx

@@ -13,7 +13,8 @@ import { useButtonSemantics } from '../../hooks'
 import {
   createPolymorphicComponent,
   PolymorphicComponentProps,
-  PolymorphicRef
+  PolymorphicRef,
+  PolymorphicRefWithFallback
 } from '../../utils/polymorphic'
 
 type PaginationItemOwnProps<C extends ElementType> = {
@@ -41,7 +42,9 @@ export type PaginationItemProps<C extends ElementType = 'button'> = PolymorphicC
 >
 
 type PaginationItemComponent = (<C extends ElementType = 'button'>(
-  props: PaginationItemProps<C> & { ref?: PolymorphicRef<C> }
+  props: PaginationItemProps<C> & {
+    ref?: PolymorphicRefWithFallback<C, HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement>
+  }
 ) => ReactElement | null) & { displayName?: string }
 
 function PaginationItemRender<C extends ElementType = 'button'>(
@@ -66,7 +69,15 @@ function PaginationItemRender<C extends ElementType = 'button'>(
     className
   )
 
-  const Component = (component ?? (active ? 'span' : href ? 'a' : 'button')) as ElementType
+  // The active page keeps whatever element it would render anyway (`<button>`, or `<a>` when
+  // given `href`) rather than collapsing to a `<span>`. Swapping the tag on activation made React
+  // unmount the focused control and mount a different element in its place, so a keyboard user who
+  // activated a page was dropped to `<body>` and had to tab in from the top of the document again
+  // (WCAG 2.4.3). The `<span>` wasn't even inert: `Pagination`'s smart mode passes an `onClick`,
+  // so `useButtonSemantics` gave it `role="button"` and `tabIndex={0}` — a synthetic button,
+  // strictly worse than the real one it replaced. Styling is unaffected either way: chassis-css
+  // matches `.pagination-link { &.active, .active > & }`, and `active` still lands on the `<li>`.
+  const Component = (component ?? (href ? 'a' : 'button')) as ElementType
 
   // `<a>` has no real `disabled` attribute, so a disabled anchor pagination item still fires
   // click (and still navigates) unless it's blocked here, same guard `Button` applies.
@@ -86,8 +97,13 @@ function PaginationItemRender<C extends ElementType = 'button'>(
     onClick: onClick as MouseEventHandler<HTMLElement> | undefined
   })
 
+  // `aria-current="page"` goes on the control itself, not the wrapping `<li>` — that's where the
+  // WAI-ARIA pagination pattern puts it, and it's what a screen reader conveys when focus lands on
+  // the control. On the `<li>` it was attached to a presentational list item nothing focuses.
+  const currentProps = active ? { 'aria-current': 'page' as const } : {}
+
   return (
-    <li className={_className} {...(active && { 'aria-current': 'page' })}>
+    <li className={_className}>
       {Component === 'button' ? (
         <button
           {...(rest as Record<string, unknown>)}
@@ -95,6 +111,7 @@ function PaginationItemRender<C extends ElementType = 'button'>(
           type="button"
           disabled={disabled}
           onClick={handleClick}
+          {...currentProps}
           ref={ref as Ref<HTMLButtonElement>}
         >
           {children}
@@ -106,6 +123,7 @@ function PaginationItemRender<C extends ElementType = 'button'>(
           href={href}
           onClick={handleClick}
           {...(disabled && { 'aria-disabled': true, tabIndex: -1 })}
+          {...currentProps}
           ref={ref as Ref<HTMLAnchorElement>}
         >
           {children}
@@ -118,6 +136,7 @@ function PaginationItemRender<C extends ElementType = 'button'>(
             unknown
           >)}
           {...(!needsButtonSemantics && { onClick: handleClick })}
+          {...currentProps}
           ref={needsButtonSemantics ? forkedRef : ref}
         >
           {children}

package/src/components/popover/Popover.tsx

@@ -4,6 +4,7 @@ import React, {
   ReactElement,
   ReactNode,
   RefObject,
+  useCallback,
   useEffect,
   useRef
 } from 'react'
@@ -13,13 +14,19 @@ import { mergeProps, useDialog, useOverlayPosition, useOverlayTrigger } from 're
 import { useOverlayTriggerState } from 'react-stately'
 import { Transition } from 'react-transition-group'
 
-import { getOverlayArrowStyle, getOverlayTransitionClass, useFloatingOverlay } from '../../hooks'
+import {
+  getOverlayArrowStyle,
+  getOverlayTransitionClass,
+  useFloatingOverlay,
+  useForkedRef
+} from '../../hooks'
 import { Placement, resolveDataPlacement, toAriaPlacement } from '../../utils/overlayPlacement'
+import { asTriggerElement, getTriggerRef } from '../../utils/triggerElement'
 
 interface PopoverPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'content'> {
   arrowProps: HTMLAttributes<HTMLDivElement>
   content: ReactNode | string
-  overlayRef: RefObject<HTMLDivElement>
+  overlayRef: RefObject<HTMLDivElement | null>
   overlayTriggerProps: HTMLAttributes<HTMLDivElement>
   title?: ReactNode | string
 }
@@ -103,6 +110,16 @@ export const Popover: FC<PopoverProps> = ({
   const triggerRef = useRef<HTMLElement | null>(null)
   const floatingRef = useRef<HTMLDivElement>(null)
 
+  // `cloneElement`'s config replaces the child's own `ref` outright rather than merging with it,
+  // so capturing the trigger node has to be forked with whatever ref the caller already put on
+  // that child — otherwise `<Popover><Button ref={mine} /></Popover>` silently never populates
+  // `mine`.
+  const setTriggerRef = useCallback((node: HTMLElement | null) => {
+    triggerRef.current = node
+  }, [])
+  const triggerElement = asTriggerElement(children)
+  const forkedTriggerRef = useForkedRef<HTMLElement>(setTriggerRef, getTriggerRef(triggerElement))
+
   const state = useOverlayTriggerState({ defaultOpen: !!visible })
   const {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -189,15 +206,12 @@ export const Popover: FC<PopoverProps> = ({
 
   return (
     <>
-      {React.cloneElement(children, {
-        ref: (node: HTMLElement | null) => {
-          triggerRef.current = node
-        },
-        ...triggerProps,
-        onClick: (event: React.MouseEvent) => {
-          children.props.onClick?.(event)
-          state.toggle()
-        }
+      {/* `mergeProps` chains the child's own `onClick` ahead of this one, so this no longer
+          calls `children.props.onClick` itself the way it did when it spread `triggerProps`
+          raw — doing both would fire the caller's handler twice per click. */}
+      {React.cloneElement(triggerElement, {
+        ...mergeProps(triggerElement.props, triggerProps, { onClick: () => state.toggle() }),
+        ref: forkedTriggerRef
       })}
       {typeof window !== 'undefined' &&
         createPortal(
@@ -207,9 +221,21 @@ export const Popover: FC<PopoverProps> = ({
             nodeRef={floatingRef}
             onExited={() => {
               const trigger = triggerRef.current
-              if (trigger && document.contains(trigger)) {
-                trigger.focus()
-              }
+              if (!trigger || !document.contains(trigger)) return
+              // Only reclaim focus when the popover still owns it, or when nothing does.
+              // `useDialog` moves focus into the panel on open, so the panel still holds it here
+              // for an Escape/inside close (`onExited` runs before `unmountOnExit` detaches the
+              // node, so this reads the pre-removal state); an outside click on plain page
+              // content instead leaves focus loose on `<body>`. Both are worth restoring. Any
+              // other active element means the user deliberately put focus there — dismissing by
+              // clicking another control, or the app closing the popover via `visible` while
+              // they were typing somewhere else — and this used to steal it straight back off
+              // them. Mirrors react-aria's own `shouldRestoreFocus` condition.
+              const active = document.activeElement
+              const focusIsLoose = !active || active === document.body
+              const focusIsInPanel = !!active && !!floatingRef.current?.contains(active)
+              if (!focusIsLoose && !focusIsInPanel) return
+              trigger.focus()
             }}
             timeout={{
               enter: 0,

package/src/components/progress/Progress.tsx

@@ -132,7 +132,7 @@ function ProgressRender<C extends ElementType = 'div'>(
   if (!hasCaption) return progressElement
 
   return (
-    <div className="d-flex flex-column gap-xsmall">
+    <div className="d-flex flex-column gap-xs">
       <div
         className={classNames('d-flex', label ? 'justify-content-between' : 'justify-content-end')}
       >

package/src/components/progress/ProgressBar.tsx

@@ -77,7 +77,7 @@ function ProgressBarRender<C extends ElementType = 'div'>(
       style={{ width: `${clampedValue}%`, ...style }}
       ref={ref}
     >
-      <span className="mx-2xsmall">{children}</span>
+      <span className="mx-2xs">{children}</span>
     </Component>
   )
 }

package/src/components/radio/Radio.tsx

@@ -34,9 +34,9 @@ export interface RadioProps extends Omit<
    */
   label?: ReactNode
   /**
-   * Size the component small or large.
+   * Size the component sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   /**
    * The value of the radio button, used to identify it within its `<RadioGroup>`.
    */

package/src/components/radio/RadioGroup.tsx

@@ -127,7 +127,7 @@ export const RadioGroup = forwardRef<HTMLFieldSetElement, RadioGroupProps>(
             {label}
           </legend>
         )}
-        {orientation === 'horizontal' ? <Flex gap="medium">{items}</Flex> : items}
+        {orientation === 'horizontal' ? <Flex gap="md">{items}</Flex> : items}
         {description && <FormHelp {...descriptionProps}>{description}</FormHelp>}
         {invalid && errorMessage && (
           <FormFeedback invalid {...errorMessageProps}>

package/src/components/select/Select.tsx

@@ -11,6 +11,7 @@ import classNames from 'classnames'
 import { useForkedRef, useFormField } from '../../hooks'
 import { validationClassName } from '../../utils/validationClassName'
 import { renderFormField } from '../form-field/renderFormField'
+import { devWarning } from '../../utils/devWarning'
 
 export interface SelectOptionDef {
   /**
@@ -98,9 +99,9 @@ export interface SelectProps extends Omit<InputHTMLAttributes<HTMLSelectElement>
    */
   placeholder?: string
   /**
-   * Size the component small or large.
+   * Size the component sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   /**
    * Set component validation state to valid.
    */
@@ -151,12 +152,11 @@ export const Select = forwardRef<HTMLSelectElement, SelectProps>(
           .map((option) => String(option.value ?? ''))
       : []
 
-    if (!multiple && selectedValues.length > 1) {
-      console.warn(
-        'Select: more than one option has `selected: true` but `multiple` is not set — only ' +
-          'the last one will be selected, matching native <select> behavior.'
-      )
-    }
+    devWarning(
+      !multiple && selectedValues.length > 1,
+      'Select: more than one option has `selected: true` but `multiple` is not set — only ' +
+        'the last one will be selected, matching native <select> behavior.'
+    )
 
     // React warns against setting `selected` directly on <option>, recommending `defaultValue`/
     // `value` on <select> instead — so `options[].selected` is resolved into a `defaultValue`

package/src/components/skeleton/Skeleton.tsx

@@ -44,7 +44,7 @@ type SkeletonOwnProps<C extends ElementType> = {
   /**
    * Overrides `span` at a breakpoint and up.
    *
-   * @type { Partial<Record<'small' | 'medium' | 'large' | 'xlarge' | '2xlarge', 'auto' | number | string | boolean>> }
+   * @type { Partial<Record<'sm' | 'md' | 'lg' | 'xl' | '2xl', 'auto' | number | string | boolean>> }
    */
   responsive?: Partial<Record<Breakpoint, Span>>
 }

package/src/components/spinner/Spinner.tsx

@@ -22,9 +22,9 @@ type SpinnerOwnProps<C extends ElementType> = {
    */
   component?: C
   /**
-   * Size the component small.
+   * Size the component sm.
    */
-  size?: 'small'
+  size?: 'sm'
   /**
    * Set the button variant to an outlined button or a ghost button.
    */

package/src/components/stepper/Stepper.tsx

@@ -65,11 +65,11 @@ type StepperOwnProps<C extends ElementType> = {
    */
   layout?:
     | 'horizontal'
-    | 'small:horizontal'
-    | 'medium:horizontal'
-    | 'large:horizontal'
-    | 'xlarge:horizontal'
-    | '2xlarge:horizontal'
+    | 'sm:horizontal'
+    | 'md:horizontal'
+    | 'lg:horizontal'
+    | 'xl:horizontal'
+    | '2xl:horizontal'
   /**
    * Wraps the stepper in a horizontally scrollable container so steps keep their natural width
    * instead of shrinking to fit.

package/src/components/switch/Switch.tsx

@@ -46,9 +46,9 @@ export interface SwitchProps extends Omit<
    */
   onChange?: (isSelected: boolean) => void
   /**
-   * Size the component small or large.
+   * Size the component sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   /**
    * Specifies the type of component.
    */
@@ -91,7 +91,7 @@ interface RenderSwitchInputOptions {
   inputProps: InputHTMLAttributes<HTMLInputElement>
   invalid?: boolean
   label?: ReactNode
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   valid?: boolean
 }
 

package/src/components/table/Table.css

@@ -9,7 +9,7 @@
 
 .table-sort-icon {
   display: inline-block;
-  margin-inline-start: var(--cx-space-2xsmall);
+  margin-inline-start: var(--cx-space-2xs);
   font-size: .75em;
   opacity: .6;
 }
@@ -34,6 +34,6 @@
 .table [role="gridcell"]:focus-visible,
 .table [role="columnheader"]:focus-visible,
 .table [role="rowheader"]:focus-visible {
-  outline: var(--cx-border-width-xlarge) solid var(--cx-primary);
+  outline: var(--cx-border-width-xl) solid var(--cx-primary);
   outline-offset: -2px;
 }

package/src/components/table/Table.tsx

@@ -103,7 +103,7 @@ export interface TableProps<T extends object> {
   /**
    * Make any table responsive across all viewports or pick a maximum breakpoint.
    */
-  responsive?: boolean | 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge'
+  responsive?: boolean | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
   /**
    * The currently selected row keys (controlled).
    */
@@ -115,7 +115,7 @@ export interface TableProps<T extends object> {
   /**
    * Make table more compact by cutting all cell padding.
    */
-  small?: boolean
+  sm?: boolean
   /**
    * The current sort column and direction.
    */
@@ -127,7 +127,7 @@ export interface TableProps<T extends object> {
    * separately, since stacking needs the same `.table-responsive` container-query ancestor.
    * Labels come from each `TableColumn`'s text (or its `textValue`, for non-text headers).
    */
-  stacked?: boolean | 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge'
+  stacked?: boolean | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
   /**
    * Add zebra-striping to table rows.
    */
@@ -152,7 +152,7 @@ const TableInner = <T extends object>(
     responsive,
     selectedKeys,
     selectionMode = 'none',
-    small,
+    sm,
     sortDescriptor,
     stacked,
     striped,
@@ -187,7 +187,7 @@ const TableInner = <T extends object>(
       bordered,
       borderless,
       hoverable: hover,
-      small,
+      sm,
       stacked: stacked === true,
       striped
     },
@@ -296,6 +296,12 @@ const TableColumnHeader = <T extends object>({ column, state }: TableColumnHeade
       {...columnHeaderProps}
       className={column.props?.className || undefined}
       colSpan={column.colSpan ?? undefined}
+      // react-aria's `useTableColumnHeader` supplies `role="columnheader"` for the ARIA grid
+      // pattern but no `scope`, so the native table semantics were left ambiguous — a `<th>` with
+      // no `scope` fails WCAG H63, and assistive technology reading the table natively (rather
+      // than through the grid roles) has to guess whether the header applies to its column or its
+      // row. These are always column headers; the row-header case doesn't exist in this API.
+      scope="col"
       ref={ref}
     >
       {column.rendered}
@@ -319,7 +325,7 @@ const TableSelectAllCell = <T extends object>({ column, state }: TableSelectAllC
   const { checkboxProps } = useTableSelectAllCheckbox(state)
 
   return (
-    <th {...columnHeaderProps} className="table-selection-cell" ref={ref}>
+    <th {...columnHeaderProps} className="table-selection-cell" scope="col" ref={ref}>
       <TableCheckbox checkboxProps={checkboxProps} />
     </th>
   )

package/src/components/text-input/TextInput.tsx

@@ -63,9 +63,9 @@ export interface TextInputProps extends Omit<
    */
   readOnly?: boolean
   /**
-   * Size the component small or large.
+   * Size the component sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   /**
    * Specifies the type of component. For `color` or `file` inputs, use the dedicated `ColorInput` or `FileInput` components instead.
    */

package/src/components/textarea/Textarea.tsx

@@ -55,9 +55,9 @@ export interface TextareaProps extends Omit<
    */
   rows?: number
   /**
-   * Size the component small or large.
+   * Size the component sm or lg.
    */
-  size?: 'small' | 'large'
+  size?: 'sm' | 'lg'
   /**
    * Set component validation state to valid.
    */

package/src/components/toast/ToastBody.tsx

@@ -47,7 +47,7 @@ function ToastBodyRender<C extends ElementType = 'div'>(
   const Component = component ?? 'div'
   const _className = classNames(
     'toast-body',
-    { 'd-flex align-items-start justify-content-between gap-small': closeButton },
+    { 'd-flex align-items-start justify-content-between gap-sm': closeButton },
     className
   )
   return (

package/src/components/toast/ToastHeader.tsx

@@ -81,11 +81,11 @@ function ToastHeaderRender<C extends ElementType = 'div'>(
     <Component className={_className} {...rest} ref={ref}>
       {icon != null &&
         (typeof icon === 'string' ? (
-          <span aria-hidden="true" className="me-small">
+          <span aria-hidden="true" className="me-sm">
             <ToastIcon name={icon} />
           </span>
         ) : (
-          <span className="me-small">{icon}</span>
+          <span className="me-sm">{icon}</span>
         ))}
       {children != null && (
         <strong id={titleId} className="me-auto">

package/src/components/toast/Toaster.tsx

@@ -43,7 +43,7 @@ export const Toaster = forwardRef<HTMLDivElement, ToasterProps>(
     const { forkedRef, regionProps, state } = useToastRegionQueue(toastQueue, ref)
 
     const _className = classNames(
-      'toaster toast-container p-medium',
+      'toaster toast-container p-md',
       {
         'position-fixed': placement,
         'position-static': !placement,

package/src/components/tooltip/Tooltip.tsx

@@ -1,12 +1,18 @@
-import React, { FC, ReactElement, ReactNode, useRef } from 'react'
+import React, { FC, ReactElement, ReactNode, useCallback, useRef } from 'react'
 import { createPortal } from 'react-dom'
 import classNames from 'classnames'
 import { mergeProps, useOverlayPosition, useTooltip, useTooltipTrigger } from 'react-aria'
 import { useTooltipTriggerState } from 'react-stately'
 import { Transition } from 'react-transition-group'
 
-import { getOverlayArrowStyle, getOverlayTransitionClass, useFloatingOverlay } from '../../hooks'
+import {
+  getOverlayArrowStyle,
+  getOverlayTransitionClass,
+  useFloatingOverlay,
+  useForkedRef
+} from '../../hooks'
 import { Placement, resolveDataPlacement, toAriaPlacement } from '../../utils/overlayPlacement'
+import { asTriggerElement, getTriggerRef } from '../../utils/triggerElement'
 
 export type { Placement }
 
@@ -59,6 +65,18 @@ export const Tooltip: FC<TooltipProps> = ({
   const triggerRef = useRef<HTMLElement | null>(null)
   const floatingRef = useRef<HTMLDivElement>(null)
 
+  // `cloneElement`'s config replaces the child's own `ref` outright rather than merging with it,
+  // so capturing the trigger node has to be forked with whatever ref the caller already put on
+  // that child — otherwise `<Tooltip><Button ref={mine} /></Tooltip>` silently never populates
+  // `mine`. Same reasoning for merging (rather than overwriting) the child's own props below:
+  // `triggerProps` carries the focus/hover handlers this component needs, and spreading them raw
+  // would drop a handler the caller put on their own trigger.
+  const setTriggerRef = useCallback((node: HTMLElement | null) => {
+    triggerRef.current = node
+  }, [])
+  const triggerElement = asTriggerElement(children)
+  const forkedTriggerRef = useForkedRef<HTMLElement>(setTriggerRef, getTriggerRef(triggerElement))
+
   // react-stately defaults to a 1500ms warmup delay (and 500ms cooldown) before a first tooltip
   // shows, spectrum-style — chassis-css's own JS plugin defaults to instant (`delay: 0`), so
   // match that here rather than leaving new adopters to wonder why the first hover lags.
@@ -107,11 +125,9 @@ export const Tooltip: FC<TooltipProps> = ({
 
   return (
     <>
-      {React.cloneElement(children, {
-        ref: (node: HTMLElement | null) => {
-          triggerRef.current = node
-        },
-        ...triggerProps
+      {React.cloneElement(triggerElement, {
+        ...mergeProps(triggerElement.props, triggerProps),
+        ref: forkedTriggerRef
       })}
       {typeof window !== 'undefined' &&
         createPortal(

package/src/hooks/useAutoDismiss.ts

@@ -36,7 +36,10 @@ export function useAutoDismiss({
   visible,
   onHide
 }: UseAutoDismissOptions): UseAutoDismissResult {
-  const timeout = useRef<number>()
+  // `useRef<number>()` (no argument) isn't valid under @types/react 19 — the overload requires
+  // an initial value, and the ref has to admit `undefined` for `clearAutoDismissTimeout` to reset
+  // it back to "no timer scheduled".
+  const timeout = useRef<number | undefined>(undefined)
   const hasMouseInteraction = useRef(false)
   const hasKeyboardInteraction = useRef(false)
 

package/src/hooks/useDialogElement.ts

@@ -1,6 +1,7 @@
 import {
   ForwardedRef,
   MouseEvent as ReactMouseEvent,
+  MouseEventHandler,
   SyntheticEvent,
   useEffect,
   useRef,
@@ -38,6 +39,13 @@ export interface UseDialogElementOptions {
    * show effect, used to auto-close every other open drawer first.
    */
   onBeforeShow?: (dialog: HTMLDialogElement) => void
+  /**
+   * The caller's own `onClick`, chained ahead of the backdrop-click handling below rather than
+   * left in the props spread — a `<dialog>` needs `onClick` for its own backdrop detection, so
+   * spreading the caller's alongside it silently dropped one of the two. Fires for every click
+   * on the dialog, not just backdrop ones.
+   */
+  onClick?: MouseEventHandler<HTMLDialogElement>
   onClose?: () => void
   onClosePrevented?: () => void
   onHidden?: () => void
@@ -62,6 +70,7 @@ export const useDialogElement = ({
   isModal,
   keyboard = true,
   onBeforeShow,
+  onClick,
   onClose,
   onClosePrevented,
   onHidden,
@@ -204,6 +213,7 @@ export const useDialogElement = ({
   }
 
   const handleBackdropClick = (event: ReactMouseEvent<HTMLDialogElement>) => {
+    onClick?.(event)
     if (event.target !== dialogRef.current || !openedAsModalRef.current) return
     if (backdrop === 'static') {
       triggerStaticBounce()

package/src/hooks/useFloatingOverlay.ts

@@ -60,11 +60,21 @@ export function useFloatingOverlay({
     else close()
   }, [visible])
 
+  // `onShow`/`onHide` report *transitions*, so neither fires for the initial commit — mounting
+  // closed is not a hide. Without this guard the `else` branch ran on mount and every
+  // `<Popover onHide>`/`<Tooltip onHide>` on the page reported a close that never happened,
+  // before `onShow` had ever fired once. The portal container still resolves on mount, since
+  // an overlay mounted already-open needs one immediately.
+  const mountedRef = useRef(false)
+
   useEffect(() => {
+    const isInitialCommit = !mountedRef.current
+    mountedRef.current = true
+
     if (isOpen) {
       setPortalContainer(resolvePortalContainer())
-      onShow?.()
-    } else {
+      if (!isInitialCommit) onShow?.()
+    } else if (!isInitialCommit) {
       onHide?.()
     }
   }, [isOpen])