Định vị (Positioning)

Sau khi định vị, Radix ghi data-side và data-align thực tế (kể cả khi đã lật) lên bề mặt, và cung cấp biến CSS --radix-popover-content-available-height, --radix-popover-trigger-width… (tiền tố đổi theo component: tooltip, dropdown-menu, select, hover-card).

{/* Chừa chỗ cho thanh trên cùng cao 74px và lề 16px ở các cạnh còn lại */}
<PopoverSurface
  side="bottom"
  align="start"
  collisionPadding={{ top: 80, right: 16, bottom: 16, left: 16 }}
  className="max-h-(--radix-popover-content-available-height) overflow-y-auto data-[side=top]:origin-bottom"
>
  …
</PopoverSurface>

{/* Bám cố định theo phía đã chọn, chấp nhận bị cắt (hiếm khi cần) */}
<MenuPopover avoidCollisions={false}>…</MenuPopover>

• Header sticky không được Radix biết tới — dùng collisionPadding ở cạnh tương ứng để bề mặt không chui dưới header.
• Danh sách dài: giới hạn chiều cao bằng biến --radix-*-content-available-height và cho cuộn, thay vì để bề mặt cao quá khung nhìn (Dropdown đã làm sẵn).
• Animation theo hướng xuất hiện: style bằng data-[side=top]:… vì cạnh thực tế có thể khác cạnh bạn chọn.

<YugenProvider theme="dark" brand="web" className="p-4">
  <Popover>
    <PopoverTrigger asChild>
      <Button appearance="primary">Mở popover</Button>
    </PopoverTrigger>
    {/* Tự nhận theme tối + brand Web của provider lồng, dù render vào <body> */}
    <PopoverSurface withArrow>Nền tối, brand Web.</PopoverSurface>
  </Popover>
</YugenProvider>

// Tự viết bề mặt portal mới? Gắn props của provider gần nhất:
import { usePortalThemeProps } from "@/components/ui";

function MyFloatingSurface(props) {
  const portalTheme = usePortalThemeProps(); // {} khi ở provider gốc
  return <SomePrimitive.Portal><SomePrimitive.Content {...portalTheme} {...props} /></SomePrimitive.Portal>;
}

• Theme cho cả ứng dụng: luôn dùng <YugenProvider applyToDocument> ở gốc — attribute nằm trên <html> nên mọi portal tự đúng.
• Theme lồng: mọi bề mặt nổi của Yugen (PopoverSurface, MenuPopover, TooltipContent, HoverCardContent, DialogSurface, DrawerSurface, ContextMenu, Menubar, listbox Dropdown / Combobox / TagPicker) tự gắn data-theme / data-brand /dir của provider lồng qua hook usePortalThemeProps(). Bề mặt tự viết thì gọi hook này.
• Hướng chữ không cần xử lý: các bề mặt nổi (PopoverSurface, TooltipContent, HoverCardContent, DialogSurface, DrawerSurface, menu và listbox) tự gắn dir của provider gần nhất, vì context React (kể cả DirectionProvider) đi xuyên qua portal.

// Cả app: giữ thanh cuộn khi Menu, ContextMenu, Dropdown mở
<YugenProvider applyToDocument scrollLock="keep-scrollbar">
  <App />
</YugenProvider>

// Không dùng provider: đặt attribute trên <html>
<html data-yugen-scroll-lock="keep-scrollbar">

// Một menu không khoá cuộn
<Menu modal={false}>…</Menu>

• scrollLock="keep-scrollbar" trên provider gốc ghi data-yugen-scroll-lock lên <html>: thanh cuộn vẫn hiện và không có gì xê dịch, nhưng lăn chuột / vuốt bên ngoài bề mặt vẫn bị chặn. App không dùng provider thì tự đặt attribute này. Mặc định hiện tại là "hide-scrollbar"; bản 1.0 sẽ đổi sang "keep-scrollbar".
• modal={false} trên Menu hoặc ContextMenu: trang vẫn cuộn được, bấm ra ngoài tới trang ngay, và phần còn lại của trang không bị ẩn khỏi trình đọc màn hình. Hợp với menu mở từ thanh công cụ trong vùng nội dung dài.
• Phần tử position: fixed sát mép phải (header, nút nổi) xê dịch theo bề rộng thanh cuộn khi thanh cuộn ẩn, trừ khi có class right-scroll-bar-position (hoặc width-before-scroll-bar cho phần tử rộng hết trang). Với keep-scrollbar thì không cần.