import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';

<Meta title="Media/FloatingMediaWrapper" />

<Title>FloatingMediaWrapper</Title>
<Subtitle>Draggable, resizable floating portal wrapper for video and audio players.</Subtitle>

---

## Overview

`FloatingMediaWrapper` wraps any media player (`VideoPlayer`, `AudioPlayer`, etc.) and provides two states:

- **Inline** — The player renders in its normal document position.
- **Floating** — The player detaches into a fixed, draggable, resizable overlay portal (`document.body`) while a placeholder occupies the original position.

Position and size are persisted to `localStorage` per `playerId`, so the user's floating window survives page navigation.

```tsx
import { FloatingMediaWrapper } from 'xertica-ui/media';
import { VideoPlayer } from 'xertica-ui/media';

function MyPage() {
  const [isFloating, setIsFloating] = React.useState(false);

  return (
    <FloatingMediaWrapper
      isFloating={isFloating}
      setIsFloating={setIsFloating}
      title="Tutorial Video"
      playerId="tutorial-v1"
    >
      <VideoPlayer src="https://example.com/video.mp4" />
    </FloatingMediaWrapper>
  );
}
```

---

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `ReactNode` | **Required** | The media player to wrap. |
| `isFloating` | `boolean` | **Required** | Controlled floating state. |
| `setIsFloating` | `(floating: boolean) => void` | **Required** | Setter for the floating state. |
| `title` | `string` | `'Reproduzindo Mídia'` | Title shown in the floating window's drag handle bar. |
| `onClose` | `() => void` | — | Called when the close (X) button is clicked. |
| `onCloseMedia` | `() => void` | — | Alternative close handler that takes priority over `onClose`. |
| `aspectRatio` | `number` | `16/9` | Aspect ratio used for the inline placeholder height. |
| `minWidth` | `number` | `320` | Minimum floating window width in pixels. |
| `minHeight` | `number` | `110` | Minimum floating window height in pixels. |
| `colorVariant` | `'default' \| 'primary'` | `'default'` | Floating window chrome color. `primary` uses brand colors. |
| `playerId` | `string` | `'default'` | Unique key for persisting position/size to `localStorage`. |
| `enablePadding` | `boolean` | `false` | Adds inner padding around the player inside the floating container. |
| `className` | `string` | — | CSS classes applied to the inline container or placeholder. |

---

## Resize Handles

When floating, all eight directional resize handles are active (top, bottom, left, right, and all four corners). The window respects `minWidth` and `minHeight` constraints.

---

## AI Best Practices

> [!IMPORTANT]
> - **Unique `playerId`** — Always provide a unique `playerId` per player instance. If two players share an ID, their saved positions will overwrite each other in `localStorage`.
> - **Controlled state** — Manage `isFloating` in the parent component. A "Picture-in-Picture" or "Float" button in the player UI should call `setIsFloating(true)`.
> - **Close vs. close media** — Use `onCloseMedia` to stop playback and `onClose` for navigation. `onCloseMedia` takes priority if both are provided.
> - **SSR** — The portal uses `createPortal(…, document.body)`, which requires a browser DOM. Guard with `isMounted` state (already handled internally) when using SSR frameworks.
> - **Aspect ratio** — Set `aspectRatio` to match your media source (e.g., `4/3` for legacy video, `1` for square audio art) so the inline placeholder has the correct height.