@ahrowe/ui 0.41.0 → 0.41.2

package/dist/types/common/hooks/useAnchorTracking.d.ts

@@ -9,10 +9,11 @@ export interface UseAnchorTrackingArgs {
      */
     elementRefs: RefObject<HTMLElement | null>[];
     /**
-     * Positions the popup. Called once on setup and then on every scroll, resize and tracked size
-     * change. Reads the caller's own refs for everything beyond the two arguments.
+     * Positions the popup. Called once on setup and then on every scroll, resize, tracked size
+     * change and end of a CSS animation that moved the trigger, plus whenever it calls `rerun` for
+     * an end none of those report. Reads the caller's own refs for everything else.
      */
-    update: (trigger: HTMLElement, ancestors: HTMLElement[]) => void;
+    update: (trigger: HTMLElement, ancestors: HTMLElement[], rerun: () => void) => void;
     /**
      * Elements whose own size changes must re-run `update`: a popup whose content changes size
      * while open (a filtered list shrinking, an async list loading in) otherwise keeps coordinates

package/dist/types/common/hooks/useOverlay.d.ts

@@ -6,7 +6,10 @@ export interface UseOverlayArgs {
     containerRef: RefObject<HTMLElement | null>;
     /** Called when Escape is pressed while this is the topmost overlay. Omit to not handle Escape. */
     onEscape?: () => void;
-    /** Keep Tab inside the panel and restore focus to the previously focused element on close. */
+    /**
+     * Keep Tab inside the panel and restore focus to the previously focused element on close, unless
+     * an overlay opened after this one is still open.
+     */
     trapFocus?: boolean;
     /** Prevent the page behind the overlay from scrolling. */
     lockScroll?: boolean;

package/dist/types/common/popover/popover.types.d.ts

@@ -53,7 +53,7 @@ export interface PopoverProps extends Omit<HtmlProps, 'content'> {
     offset?: number;
     /** Render the arrow pointing at the trigger (default `true`). */
     withArrow?: boolean;
-    /** Close when clicking outside the panel (default `true`). */
+    /** Close on a click outside, or when focus leaves the trigger and panel (default `true`). */
     closeOnOutsideClick?: boolean;
     /** Close when pressing Escape (default `true`). */
     closeOnEscape?: boolean;

package/dist/types/common/popover/usePopoverPosition.d.ts

@@ -32,6 +32,11 @@ export interface UsePopoverPositionArgs {
      * panel that overhangs it.
      */
     shrinkToFit?: boolean;
+    /**
+     * Called when a newly opened panel first becomes visible. Focus has to wait for it: a panel
+     * still hidden, waiting out an ancestor's animation, takes none.
+     */
+    onShown?: () => void;
 }
 /**
  * Positions a portaled, `position: fixed` popover on any of the four sides of its trigger with
@@ -42,4 +47,4 @@ export interface UsePopoverPositionArgs {
  * `useAnchorTracking` supplies the lifecycle around this: mount wait, ancestor resolution, and
  * re-running on scroll, viewport resize and panel size changes.
  */
-export declare function usePopoverPosition({ isOpen, placement, align, offset, triggerRef, floatingRef, panelRef, arrowRef, matchTriggerWidth, shrinkToFit, }: UsePopoverPositionArgs): void;
+export declare function usePopoverPosition({ isOpen, placement, align, offset, triggerRef, floatingRef, panelRef, arrowRef, matchTriggerWidth, shrinkToFit, onShown, }: UsePopoverPositionArgs): void;

package/docs/Modal.md

@@ -8,7 +8,7 @@
 
 The panel itself never scrolls: the header is fixed and the children scroll inside the `body` slot, so the title and close button stay visible no matter how long the content is. Pass `footer` for anything that should stay put below the content, typically the action buttons.
 
-While open, the modal traps focus (focus moves into the panel and returns to whatever was focused before on close), locks scrolling on the page behind it, and closes on Escape. Modals nest correctly: Escape closes only the topmost one, and the page stays locked until the last one closes. The same applies to anything opened from inside a modal — a `Menu`, `Dropdown` or `Popover` counts as the layer above it, so Escape closes that first, and the modal's focus trap leaves focus alone while it's open (all three render through the same portal, so their DOM sits beside the modal's panel rather than inside it).
+While open, the modal traps focus (focus moves into the panel and returns to whatever was focused before on close), locks scrolling on the page behind it, and closes on Escape. A key already held down when it opens does not repeat into it, so holding Enter on the button that opens it does not go on to press whatever the modal focused first. Modals nest correctly: Escape closes only the topmost one, and the page stays locked until the last one closes. Modal, Popover and Tooltip share one `z-index`, so whichever opened last paints on top, a Modal opened from a Popover included. The same applies to anything opened from inside a modal — a `Menu`, `Dropdown` or `Popover` counts as the layer above it, so Escape closes that first, and the modal's focus trap leaves focus alone while it's open (all three render through the same portal, so their DOM sits beside the modal's panel rather than inside it).
 
 ```tsx
 import { Modal, ActionButtons } from '@ahrowe/ui';

package/docs/Popover.md

@@ -65,7 +65,7 @@ const [anchor, setAnchor] = useState<HTMLElement | null>(null);
 | `onOpenChange` | `(isOpen, { fromKeyboard }) => void` | — | Open-state change callback. `fromKeyboard` says whether a key caused it, which is what a menu uses to decide between putting the focus on an entry and leaving it on the trigger |
 | `offset` | `number` | `10` | Gap in px between trigger and panel |
 | `withArrow` | `boolean` | `true` | Render the arrow pointing at the trigger |
-| `closeOnOutsideClick` | `boolean` | `true` | Close on click outside (ignored for hover trigger) |
+| `closeOnOutsideClick` | `boolean` | `true` | Close on a click outside, or when focus leaves the trigger and panel (ignored for hover trigger) |
 | `closeOnEscape` | `boolean` | `true` | Close on Escape |
 | `openDelay` | `number` | `100` | Hover open delay in ms |
 | `closeDelay` | `number` | `120` | Hover close delay in ms |
@@ -90,6 +90,6 @@ Only a `Click` trigger presents as a sheet. `Hover` and `Focus` open something s
 
 **Scrolling:** where the browser supports CSS anchor positioning, including the trigger's transforms, the panel is anchored to the trigger in CSS, so it moves with a scrolling trigger in the same frame instead of catching up a frame later. Firefox resolves anchors without transforms, so it keeps the pixel positioning. While it is open the trigger carries an inline `anchor-name`, added to any inline one it already has; an `anchor-name` your stylesheet gives the trigger is overridden for that time.
 
-**Keyboard & focus (click trigger):** the panel is portaled to the end of the DOM, so Tab can't reach it naturally. When the panel has focusable content and the keyboard opened it (Enter or Space on the trigger, or ArrowDown/ArrowUp), focus moves to the first focusable element and the panel gets `role="dialog"`; a pointer click leaves the focus where it already is. `focusOnOpen` forces either. Tabbing past the last element closes the popover and moves focus to the element after the trigger; Shift+Tab past the first element, and Escape, close it and return focus to the trigger. This is non-modal: focus is not trapped, and hover/focus triggers don't steal focus. Escape closes only the innermost open layer, so a popover inside a `Modal` closes on the first press and leaves the modal open. Popovers with only static content don't manage focus or claim the dialog role.
+**Keyboard & focus (click trigger):** the panel is portaled to the end of the DOM, so Tab can't reach it naturally. When the panel has focusable content and the keyboard opened it (Enter or Space on the trigger, or ArrowDown/ArrowUp), focus moves to the first focusable element and the panel gets `role="dialog"`; a pointer click leaves the focus where it already is. `focusOnOpen` forces either. Tabbing past the last element closes the popover and moves focus to the element after the trigger; Shift+Tab past the first element, and Escape, close it and return focus to the trigger. However else it closes, such as a button inside it setting `isOpen` to `false`, focus that is still inside the panel goes back to the trigger too, as the native `hidePopover()` does; focus that has already moved elsewhere, or onto the page after a click outside, stays where it is. A key already held down when the panel opens does not repeat into it, so a held Enter does not go on to pick the first entry; in the field it opened from, such as one showing suggestions while you type, it keeps repeating. This is non-modal: focus is not trapped, and hover/focus triggers don't steal focus. Escape closes only the innermost open layer, so a popover inside a `Modal` closes on the first press and leaves the modal open. Popovers with only static content don't manage focus or claim the dialog role.
 
 **Anchored (`anchor`):** your code opens the panel, not a key event Popover sees, so the default `focusOnOpen` looks at the click that opened it: Enter or Space on the anchor or on something inside it (a click with `detail === 0`) moves the focus into the panel, a pointer click leaves it where it is, and an open with no click at all, such as suggestions appearing while the user types into an anchored field, never takes it. Escape, Tab and Shift+Tab out of the panel continue from the anchor as they would from a trigger: from the anchor itself when it takes focus, otherwise from the first focusable element inside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.41.0",
+  "version": "0.41.2",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",