# Toggletip

A click-triggered popover that shows rich content (title, body, footer) anchored to a trigger element. Cross-platform via `@xsolla/xui-primitives`; click-outside and Escape dismissal are web-only.

## Installation

```bash
npm install @xsolla/xui-toggletip
```

## Imports

```tsx
import {
  Toggletip,
  type ToggletipProps,
  type ToggletipPlacement,
} from "@xsolla/xui-toggletip";
```

## Quick start

```tsx
import * as React from "react";
import { Toggletip } from "@xsolla/xui-toggletip";
import { IconButton } from "@xsolla/xui-button";
import { HelpCircle } from "@xsolla/xui-icons-base";

export default function Example() {
  return (
    <Toggletip
      title="Help"
      content="Click here to learn more about this feature."
    >
      <IconButton
        icon={<HelpCircle size={20} />}
        variant="secondary"
        tone="mono"
        size="sm"
        aria-label="Help"
      />
    </Toggletip>
  );
}
```

## API Reference

### `<Toggletip>`

| Prop            | Type                 | Default   | Description                                                                                                   |
| --------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `children`      | `ReactNode`          | —         | Trigger element.                                                                                              |
| `title`         | `ReactNode`          | —         | Optional header content. Renders above the divider.                                                           |
| `content`       | `ReactNode`          | —         | Main content. Strings/numbers render as themed text; other nodes render as-is.                                |
| `footer`        | `ReactNode`          | —         | Optional footer (typically buttons).                                                                          |
| `direction`     | `ToggletipPlacement` | `"top"`   | Placement relative to trigger.                                                                                |
| `autoDirection` | `boolean`            | `true`    | Auto-adjust placement when near viewport edges.                                                               |
| `offset`        | `number`             | `12`      | Distance from trigger in pixels.                                                                              |
| `width`         | `string`             | `"288px"` | Popover width (CSS length).                                                                                   |
| `data-testid`   | `string`             | —         | Test identifier.                                                                                              |
| `testID`        | `string`             | —         | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |

Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).

`ToggletipPlacement` is `"top" | "top-left" | "top-right" | "bottom" | "bottom-left" | "bottom-right" | "left" | "right"`.

## Examples

### With footer actions

```tsx
import * as React from "react";
import { Toggletip } from "@xsolla/xui-toggletip";
import { Button } from "@xsolla/xui-button";
import { Info } from "@xsolla/xui-icons-base";

export default function WithFooter() {
  return (
    <Toggletip
      title="Confirmation"
      content="Are you sure you want to proceed?"
      footer={
        <>
          <Button size="sm" variant="secondary">
            Cancel
          </Button>
          <Button size="sm">Confirm</Button>
        </>
      }
    >
      <Button size="sm" iconLeft={<Info size={16} />}>
        Details
      </Button>
    </Toggletip>
  );
}
```

### Different directions

```tsx
import * as React from "react";
import { Toggletip } from "@xsolla/xui-toggletip";
import { Button } from "@xsolla/xui-button";

export default function Directions() {
  return (
    <div style={{ display: "flex", gap: 16, padding: 100 }}>
      <Toggletip direction="top" content="Appears above">
        <Button size="sm">Top</Button>
      </Toggletip>
      <Toggletip direction="bottom" content="Appears below">
        <Button size="sm">Bottom</Button>
      </Toggletip>
      <Toggletip direction="left" content="Appears left">
        <Button size="sm">Left</Button>
      </Toggletip>
      <Toggletip direction="right" content="Appears right">
        <Button size="sm">Right</Button>
      </Toggletip>
    </div>
  );
}
```

### Rich body content

```tsx
import * as React from "react";
import { Toggletip } from "@xsolla/xui-toggletip";
import { IconButton } from "@xsolla/xui-button";
import { HelpCircle } from "@xsolla/xui-icons-base";

export default function Rich() {
  return (
    <Toggletip
      title="Premium benefits"
      content={
        <ul style={{ margin: 0, paddingLeft: 20 }}>
          <li>Unlimited downloads</li>
          <li>Priority support</li>
          <li>Advanced analytics</li>
          <li>Custom branding</li>
        </ul>
      }
    >
      <IconButton
        icon={<HelpCircle size={16} />}
        aria-label="Premium benefits"
        variant="secondary"
        tone="mono"
        size="sm"
      />
    </Toggletip>
  );
}
```

### Quick actions menu

```tsx
import * as React from "react";
import { Toggletip } from "@xsolla/xui-toggletip";
import { Button, IconButton } from "@xsolla/xui-button";
import { MoreVertical, Edit, Copy, Trash } from "@xsolla/xui-icons-base";

export default function QuickActions() {
  return (
    <Toggletip
      direction="bottom-right"
      width="160px"
      content={
        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
          <Button
            size="sm"
            variant="secondary"
            iconLeft={<Edit size={16} />}
            fullWidth
          >
            Edit
          </Button>
          <Button
            size="sm"
            variant="secondary"
            iconLeft={<Copy size={16} />}
            fullWidth
          >
            Duplicate
          </Button>
          <Button
            size="sm"
            variant="secondary"
            tone="alert"
            iconLeft={<Trash size={16} />}
            fullWidth
          >
            Delete
          </Button>
        </div>
      }
    >
      <IconButton
        icon={<MoreVertical size={20} />}
        variant="secondary"
        tone="mono"
        size="sm"
        aria-label="More actions"
      />
    </Toggletip>
  );
}
```

## Behaviour

- Opens on trigger click; closes on click outside (web only).
- Closes on Escape (web only).
- Auto-adjusts position to stay in viewport when `autoDirection` is `true`.
- Uses theme `shadow.popover` for elevation.

## Toggletip vs Tooltip

| Feature       | Toggletip                           | Tooltip         |
| ------------- | ----------------------------------- | --------------- |
| Trigger       | Click                               | Hover/focus     |
| Content       | Rich (title, body, footer)          | Simple text     |
| Interactivity | Can contain interactive elements    | Non-interactive |
| Use case      | Help text, mini forms, action menus | Quick hints     |

## Accessibility

- Click-triggered, so the trigger must be a focusable element.
- Escape dismisses the popover (web only).
- Provide an accessible name on the trigger (e.g. `aria-label` on icon-only triggers).

## Related

- [Tooltip](./tooltip.md) — hover/focus-triggered hint variant.