@godxjp/ui 19.6.0 → 20.0.0

package/dist/components/navigation/dropdown-menu.d.ts

@@ -1,24 +1,205 @@
 import * as React from "react";
-import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
-export declare function DropdownMenu(props: React.ComponentProps<typeof DropdownMenuPrimitive.Root>): React.JSX.Element;
-export declare function DropdownMenuTrigger(props: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>): React.JSX.Element;
-export declare function DropdownMenuPortal(props: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>): React.JSX.Element;
-export declare function DropdownMenuGroup(props: React.ComponentProps<typeof DropdownMenuPrimitive.Group>): React.JSX.Element;
-export declare function DropdownMenuRadioGroup(props: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>): React.JSX.Element;
-export declare function DropdownMenuSub(props: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>): React.JSX.Element;
-export declare const DropdownMenuContent: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuItem: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+import { type MenuItemRenderProps, type PopoverProps, type PopoverRenderProps } from "react-aria-components";
+/**
+ * Dịch trạng thái item của RAC sang bộ `data-*` mà Radix phát ra và CSS của kho đang bám.
+ *
+ * `data-highlighted` là móc tô sáng bàn phím (`.ui-dropdown-menu-item[data-highlighted]`);
+ * `data-state` mang cả hai nghĩa của Radix — "open" cho sub-trigger, "checked" cho hàng có chọn.
+ */
+export declare function radixItemState(state: MenuItemRenderProps): Record<string, string | undefined>;
+/**
+ * Dịch trạng thái popover của RAC sang `data-state` / `data-side` của Radix.
+ *
+ * ĐI KÈM: hai chỗ gọi nó đều bỏ `role` khỏi DOM (`role={undefined}`). RAC tự gắn `role="dialog"`
+ * cho MỌI popover modal — "Automatically render Popover with role=dialog except when isNonModal is
+ * true" — kể cả khi ruột của nó là một `role="menu"`. Radix không làm thế, và hợp đồng của tệp này
+ * là giữ hình dạng Radix ở CẢ cây a11y chứ không chỉ ở tên prop.
+ *
+ * Cái giá, đo được ở consumer chuột bạch (godx-chat, 08/09/2026): mở một hộp thoại TỪ một mục menu
+ * để lại HAI phần tử `role="dialog"` trong DOM suốt ~300ms — popover của menu đang chạy animation
+ * thoát (`data-exiting`), cộng chính hộp thoại vừa mở. 12 phép kiểm Playwright đỏ bằng "strict mode
+ * violation" trên `getByRole('dialog')`, thứ Playwright KHÔNG thử lại. Và với trình đọc màn hình,
+ * một menu vẫn tự xưng là "dialog".
+ *
+ * Bỏ đúng THUỘC TÍNH, không đụng hành vi: state `isDialog` bên trong RAC không đổi, nên việc đưa
+ * tiêu điểm vào popover lúc mở vẫn chạy nguyên như cũ.
+ */
+export declare function radixSurfaceState(state: PopoverRenderProps): Record<string, string | undefined>;
+/** Radix `side` + `align` → `placement` của RAC. `align="center"` là placement trần. */
+export declare function toPlacement(side?: "top" | "right" | "bottom" | "left", align?: "start" | "center" | "end"): PopoverProps["placement"];
+/**
+ * Radix trao cho `onSelect` một `Event` huỷ được. RAC's `onAction` không có sự kiện nào, nên ta
+ * dựng một cái tương đương để consumer gọi `preventDefault()` không nổ — nhưng nó KHÔNG còn giữ
+ * menu mở được nữa (xem báo cáo di trú).
+ */
+export declare function selectEvent(name: string): Event;
+interface DropdownMenuPropsOwn {
+    /** Trạng thái mở có kiểm soát (Radix). Bên trong là `isOpen` của RAC. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** `modal={false}` → `isNonModal` của RAC: nền không bị khoá cuộn, không bị `inert`. */
+    modal?: boolean;
+    /**
+     * Radix đọc `dir` để đảo mũi tên trái/phải. RAC lấy hướng từ locale (`I18nProvider` /
+     * `useLocale`), nên prop này còn trong API vì hợp đồng, nhưng không tự đảo hướng.
+     */
+    dir?: "ltr" | "rtl";
+}
+type DropdownMenuProps = React.PropsWithChildren<DropdownMenuPropsOwn>;
+export declare function DropdownMenu({ children, open, defaultOpen, onOpenChange, modal, dir, }: DropdownMenuProps): React.JSX.Element;
+interface DropdownMenuTriggerProps extends React.ComponentPropsWithoutRef<"button"> {
+    /** Giao hành vi mở cho phần tử con thay vì `<button>` mặc định — như Radix. */
+    asChild?: boolean;
+}
+/**
+ * RAC không nhận một `<button>` trần làm trigger: hành vi nhấn đi qua `PressResponder`, và chỉ
+ * `Pressable` (hoặc một component gọi `usePress`) mới nhận được nó. `asChild` vì vậy trở thành
+ * "bọc con trong `Pressable`" thay vì "hợp nhất props vào con" — kết quả với consumer là như nhau:
+ * chính phần tử của họ mang `aria-haspopup` / `aria-expanded` và nhận cú nhấn.
+ */
+export declare function DropdownMenuTrigger({ asChild, children, ...props }: DropdownMenuTriggerProps): React.JSX.Element;
+interface DropdownMenuPortalPropsOwn {
+    /** Giữ tên vì hợp đồng: RAC `Popover` tự cổng ra `document.body`, không có bản dựng cưỡng bức. */
+    forceMount?: true;
+}
+type DropdownMenuPortalProps = React.PropsWithChildren<DropdownMenuPortalPropsOwn>;
+/** RAC `Popover` đã tự cổng, nên Portal chỉ còn là chỗ giữ hình dạng cây của Radix. */
+export declare function DropdownMenuPortal({ children }: DropdownMenuPortalProps): React.JSX.Element;
+interface DropdownMenuGroupPropsOwn {
+    className?: string;
+}
+type DropdownMenuGroupProps = React.PropsWithChildren<DropdownMenuGroupPropsOwn>;
+/** Radix dựng `<div role="group">`; RAC `MenuSection` dựng `<section role="group">`. */
+export declare function DropdownMenuGroup({ children, className }: DropdownMenuGroupProps): React.JSX.Element;
+interface DropdownMenuRadioGroupPropsOwn {
+    className?: string;
+    value?: string;
+    onValueChange?: (value: string) => void;
+}
+type DropdownMenuRadioGroupProps = React.PropsWithChildren<DropdownMenuRadioGroupPropsOwn>;
+/**
+ * Radix giữ trạng thái chọn ở chính RadioGroup; RAC giữ ở collection, khoá theo `id` của item.
+ * Nên `value` của consumer trở thành `selectedKeys` và `value` của RadioItem trở thành khoá.
+ */
+export declare function DropdownMenuRadioGroup({ children, className, value, onValueChange, }: DropdownMenuRadioGroupProps): React.JSX.Element;
+interface DropdownMenuSubPropsOwn {
+    /**
+     * RAC `SubmenuTrigger` tự giữ trạng thái mở của submenu và không phơi ra chỗ nào để điều khiển
+     * nó. Ba prop này còn trong API vì hợp đồng, nhưng không còn tác dụng.
+     */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+type DropdownMenuSubProps = React.PropsWithChildren<DropdownMenuSubPropsOwn>;
+/**
+ * `SubmenuTrigger` đọc children THEO VỊ TRÍ — `children[0]` là item mở submenu, `children[1]` là
+ * popover — nên thứ tự `<SubTrigger/>` rồi `<SubContent/>` của Radix ánh xạ thẳng.
+ */
+export declare function DropdownMenuSub({ children }: DropdownMenuSubProps): React.JSX.Element;
+interface DropdownMenuContentPropsOwn {
+    className?: string;
+    side?: "top" | "right" | "bottom" | "left";
+    align?: "start" | "center" | "end";
+    sideOffset?: number;
+    alignOffset?: number;
+    avoidCollisions?: boolean;
+    collisionPadding?: number;
+    /** Radix `loop` cho điều hướng bàn phím → `shouldFocusWrap` của RAC. */
+    loop?: boolean;
+    /** Giữ tên vì hợp đồng; RAC không có bản dựng cưỡng bức và không tự tháo khi trigger rời màn. */
+    forceMount?: true;
+    hideWhenDetached?: boolean;
+    sticky?: "partial" | "always";
+}
+type DropdownMenuContentProps = React.PropsWithChildren<DropdownMenuContentPropsOwn>;
+/**
+ * Một phần tử của Radix (`Content`) tách thành HAI ở RAC: `Popover` là hộp được định vị, `Menu` là
+ * phần tử mang `role="menu"`. `data-slot` và lớp `ui-dropdown-menu-content` ở lại trên HỘP, cùng
+ * chỗ với `data-state` / `data-side` mà các utility animate đang đọc.
+ *
+ * `useInertHiddenBackground` đã được gỡ ở đây: RAC gọi `ariaHideOutside(..., {shouldUseInert:
+ * true})` — nền thành `inert` thật chứ không chỉ `aria-hidden`, nên axe `aria-hidden-focus` không
+ * còn cửa để nổ. Và hiệu ứng đó khoá theo `state.isOpen`, không theo unmount, nên `inert` được nhả
+ * NGAY ở ý định đóng: đúng lớp lỗi gh#385, đã sửa ở thượng nguồn. Phép đo là
+ * `src/components/__tests__/overlay-inert-release-385.test.tsx`.
+ */
+export declare function DropdownMenuContent({ children, className, side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding, loop, hideWhenDetached, sticky, forceMount, }: DropdownMenuContentProps): React.JSX.Element;
+interface DropdownMenuItemPropsOwn {
+    className?: string;
     inset?: boolean;
     variant?: "default" | "destructive";
-} & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuLabel: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuLabelProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    disabled?: boolean;
+    onSelect?: (event: Event) => void;
+    textValue?: string;
+    /** Mượn thẻ của con thay vì dựng `<div>` riêng — chỗ để nhét một `<Link>` vào một mục menu. */
+    asChild?: boolean;
+}
+type DropdownMenuItemProps = React.PropsWithChildren<DropdownMenuItemPropsOwn>;
+export declare function DropdownMenuItem({ children, className, inset, variant, disabled, onSelect, textValue, asChild, }: DropdownMenuItemProps): React.JSX.Element;
+interface DropdownMenuLabelPropsOwn {
+    className?: string;
     inset?: boolean;
-} & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuSeparator: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuCheckboxItem: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuCheckboxItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuRadioItem: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuRadioItemProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuSubTrigger: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSubTriggerProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /** Mượn thẻ của con thay vì dựng `<header>` riêng. */
+    asChild?: boolean;
+}
+type DropdownMenuLabelProps = React.PropsWithChildren<DropdownMenuLabelPropsOwn>;
+/**
+ * Radix dựng `<div>`; nút nhãn của một collection RAC là `Header`, tức `<header>`.
+ *
+ * `Header` không đi qua `useRenderProps`, nên `props.children` trong `render` CHÍNH là children của
+ * consumer — không có `Provider` chen vào như ở `MenuItem`. `Slot` vì thế nhận thẳng gói props.
+ */
+export declare function DropdownMenuLabel({ children, className, inset, asChild }: DropdownMenuLabelProps): React.JSX.Element;
+interface DropdownMenuSeparatorProps {
+    className?: string;
+}
+export declare function DropdownMenuSeparator({ className }: DropdownMenuSeparatorProps): React.JSX.Element;
+interface DropdownMenuCheckboxItemPropsOwn {
+    className?: string;
+    checked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    textValue?: string;
+    /** Mượn thẻ của con thay vì dựng `<div>` riêng; ô đánh dấu vẫn nằm bên trong thẻ mượn. */
+    asChild?: boolean;
+}
+type DropdownMenuCheckboxItemProps = React.PropsWithChildren<DropdownMenuCheckboxItemPropsOwn>;
+export declare function DropdownMenuCheckboxItem({ children, className, checked, onCheckedChange, disabled, textValue, asChild, }: DropdownMenuCheckboxItemProps): React.JSX.Element;
+interface DropdownMenuRadioItemPropsOwn {
+    className?: string;
+    value: string;
+    disabled?: boolean;
+    textValue?: string;
+    /** Mượn thẻ của con thay vì dựng `<div>` riêng. */
+    asChild?: boolean;
+}
+type DropdownMenuRadioItemProps = React.PropsWithChildren<DropdownMenuRadioItemPropsOwn>;
+export declare function DropdownMenuRadioItem({ children, className, value, disabled, textValue, asChild, }: DropdownMenuRadioItemProps): React.JSX.Element;
+interface DropdownMenuSubTriggerPropsOwn {
+    className?: string;
     inset?: boolean;
-} & React.RefAttributes<HTMLDivElement>>;
-export declare const DropdownMenuSubContent: React.ForwardRefExoticComponent<Omit<DropdownMenuPrimitive.DropdownMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+    disabled?: boolean;
+    textValue?: string;
+    /** Mượn thẻ của con thay vì dựng `<div>` riêng; mũi tên submenu vẫn nằm bên trong thẻ mượn. */
+    asChild?: boolean;
+}
+type DropdownMenuSubTriggerProps = React.PropsWithChildren<DropdownMenuSubTriggerPropsOwn>;
+export declare function DropdownMenuSubTrigger({ children, className, inset, disabled, textValue, asChild, }: DropdownMenuSubTriggerProps): React.JSX.Element;
+interface DropdownMenuSubContentPropsOwn {
+    className?: string;
+    align?: "start" | "center" | "end";
+    alignOffset?: number;
+    sideOffset?: number;
+    avoidCollisions?: boolean;
+    collisionPadding?: number;
+    loop?: boolean;
+    forceMount?: true;
+    hideWhenDetached?: boolean;
+    sticky?: "partial" | "always";
+}
+type DropdownMenuSubContentProps = React.PropsWithChildren<DropdownMenuSubContentPropsOwn>;
+export declare function DropdownMenuSubContent({ children, className, align, alignOffset, sideOffset, avoidCollisions, collisionPadding, loop, forceMount, hideWhenDetached, sticky, }: DropdownMenuSubContentProps): React.JSX.Element;
 export declare const DropdownMenuShortcut: ({ className, ...props }: React.HTMLAttributes<HTMLSpanElement>) => React.JSX.Element;
+export {};