# components/floating/usePopover (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/components/floating/usePopover.ts](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/usePopover.ts).

## Functions

### `returnFocus`

Function.

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.

```ts
function returnFocus(
  target: HTMLElement | null | undefined,
  surface: HTMLElement | null | undefined,
): void
```

**Parameters**

- `target` (`HTMLElement | null | undefined`): The element to focus, normally the trigger. Ignored when it is `null` or
  disconnected.
- `surface` (`HTMLElement | null | undefined`): The closing surface. Focus moves only when it held focus, or when nothing did.

Source: [ui/src/components/floating/usePopover.ts:98](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/usePopover.ts#L98)

### `useDismiss`

Function.

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.

```ts
function useDismiss(
  open: boolean,
  inside: readonly (RefObject<HTMLElement | null> | undefined)[],
  handlers: DismissHandlers,
): void
```

**Parameters**

- `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 [`DismissHandlers`](https://zidane.si/docs/reference/ui-components-floating-use-popover.md#DismissHandlers).

Source: [ui/src/components/floating/usePopover.ts:53](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/usePopover.ts#L53)

### `usePopover`

Function.

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.

```ts
function usePopover(
  options?: { initialOpen?: boolean; onDismiss?: () => void },
): PopoverState
```

**Parameters**

- `options?` (`{ initialOpen?: boolean; onDismiss?: () => void }`, default `{}`): Options: `onDismiss`, called for every close the content did not ask for itself,
  and `initialOpen`, whether it starts open (default `false`).

**Returns** `PopoverState`: The state, setters and the refs to attach to the trigger and the surface.

Source: [ui/src/components/floating/usePopover.ts:113](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/usePopover.ts#L113)

## Interfaces

### `DismissHandlers`

Interface.

Callbacks of [`useDismiss`](https://zidane.si/docs/reference/ui-components-floating-use-popover.md#useDismiss).

```ts
interface DismissHandlers
```

**Properties**

- `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 `inside` element.

Source: [ui/src/components/floating/usePopover.ts:33](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/usePopover.ts#L33)

### `PopoverState`

Interface.

State and refs returned by [`usePopover`](https://zidane.si/docs/reference/ui-components-floating-use-popover.md#usePopover).

```ts
interface PopoverState
```

**Properties**

- `close` (`() => void`): Close because the content finished (a pick): does not fire `onDismiss`.
- `open` (`boolean`): Whether the surface is open.
- `setOpen` (`(open: boolean) => void`): Opens or closes the surface. Closing this way fires `onDismiss`.
- `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 `onDismiss`.
- `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.

Source: [ui/src/components/floating/usePopover.ts:14](https://github.com/Tahul/zidane/blob/main/ui/src/components/floating/usePopover.ts#L14)