@poly-ds/positioning

Portal manual (reparenting para document.body) + posicionamento flutuante (@floating-ui/dom). TypeScript puro, zero dependência de framework.

Usado internamente por @poly-ds/react, @poly-ds/vue e @poly-ds/angular para posicionar o painel do Select, Tooltip e Popover — a maioria dos consumidores finais nunca importa este pacote diretamente. Ele é publicado separadamente para quem estiver construindo um componente flutuante próprio sobre o mesmo modelo.

Instalação

npm install @poly-ds/positioning

API

import { attachFloatingPanel, observeHiddenAttribute } from '@poly-ds/positioning';
import type { AttachOptions } from '@poly-ds/positioning';

const detach = attachFloatingPanel(triggerEl, panelEl, {
  placement: 'bottom', // ou 'top'
  matchReferenceWidth: true, // painel assume a largura do gatilho (ex.: Select)
});

// mais tarde
detach();

attachFloatingPanel aplica position: fixed calculado contra o elemento de referência, resolvendo corte por ancestrais overflow: hidden e colisão com a borda da janela (flip/shift via @floating-ui/dom). observeHiddenAttribute observa o atributo hidden de um elemento e notifica quando ele abre/fecha — usado para religar/desligar o posicionamento sem manter um listener sempre ativo.

Por que o painel não é movido no DOM (reparenting), e os limites conhecidos dessa abordagem, estão documentados no apêndice de COMPONENTES.md.