zidanecomponents/floating/usePopover
import { … } from 'zidane-ui'ui/src/components/floating/usePopover.ts
Functions#
returnFocusFunction#
Send focus back to target after a surface closes, but only when the
surface held it (or nobody does): a pick that moved focus on purpose (into
the editor, a rename field) keeps it.
function returnFocus(
target: HTMLElement | null | undefined,
surface: HTMLElement | null | undefined,
): voidParameters
| Name | Type | Description |
|---|---|---|
| target | HTMLElement | null | undefined | The element to focus, normally the trigger. Ignored when it is |
| surface | HTMLElement | null | undefined | The closing surface. Focus moves only when it held focus, or when nothing did. |
useDismissFunction#
Outside press and Esc for an open surface. Listens in the capture phase so Esc can be stopped before App's global handler. The handlers are read fresh on each event, so callers may pass new closures every render without re-subscribing.
function useDismiss(
open: boolean,
inside: readonly (RefObject<HTMLElement | null> | undefined)[],
handlers: DismissHandlers,
): voidParameters
| Name | Type | Description |
|---|---|---|
| open | boolean | Whether the surface is open. Listeners are attached only while it is. |
| inside | readonly (RefObject<HTMLElement | null> | undefined)[] | Refs of the elements that count as inside the surface, usually the trigger and the surface itself. |
| handlers | DismissHandlers | The callbacks to run, see |
usePopoverFunction#
Owns the open state of a surface that floats off a trigger. An outside press or Esc closes
it and calls onDismiss; Esc also returns focus to the trigger without reaching the app's
global Esc handler.
function usePopover(
options?: { initialOpen?: boolean; onDismiss?: () => void },
): PopoverStateParameters
| Name | Type | Default | Description |
|---|---|---|---|
| options? | { initialOpen?: boolean; onDismiss?: () => void } | {} | Options: |
Returns
PopoverStateThe state, setters and the refs to attach to the trigger and the surface.
Interfaces#
DismissHandlersInterface#
Callbacks of useDismiss.
interface DismissHandlersProperties
| Name | Type | Description |
|---|---|---|
| onEscape | () => void | Esc, already kept from App's global handler. |
| onKeyDown? | (event: KeyboardEvent) => void | Any other key while open (capture phase, before the focused element). |
| onOutsidePress | () => void | A press outside every |
PopoverStateInterface#
State and refs returned by usePopover.
interface PopoverStateProperties
| Name | Type | Description |
|---|---|---|
| close | () => void | Close because the content finished (a pick): does not fire |
| open | boolean | Whether the surface is open. |
| setOpen | (open: boolean) => void | Opens or closes the surface. Closing this way fires |
| surfaceRef | RefObject<HTMLElement | null> | Ref for the floating surface. Presses inside it do not count as outside presses. |
| toggle | () => void | Opens the surface when closed, closes it when open. Closing fires |
| triggerRef | RefObject<HTMLElement | null> | Ref for the trigger element. Presses on it do not count as outside presses, and focus returns to it on Esc. |