@ldkj/web-ui 0.13.0 → 0.14.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ldkj
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 ldkj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,4 @@
-# @ldkj/web-ui
+# @ldkj/web-ui
 
 由 shadcn-ui, Tailwind CSS 和 VitePress 构建的 React 组件库.
 
@@ -14,6 +14,9 @@ pnpm add @ldkj/web-ui
 import "@ldkj/web-ui/style.css";
 import { Button, Chip } from "@ldkj/web-ui";
 
+// 可选：如需启用设计系统基础重置（全局样式），再额外引入
+// import "@ldkj/web-ui/reset.css";
+
 export default function App() {
   return (
     <div className="p-4">
@@ -25,3 +28,4 @@ export default function App() {
   );
 }
 ```
+

package/components/data-display/avatar/Avatar.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+import { type SxProps } from "@/styling";
+import { type Rounded } from "@/components/shared/rounded";
+import { type Shadow } from "@/components/shared/shadow";
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | number | string;
+export type AvatarProps = React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root> & {
+    class?: string;
+    sx?: SxProps;
+    size?: AvatarSize;
+    rounded?: Rounded;
+    shadow?: Shadow;
+};
+export type AvatarImageProps = React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Image> & {
+    class?: string;
+    sx?: SxProps;
+};
+export type AvatarFallbackProps = React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback> & {
+    class?: string;
+    sx?: SxProps;
+};
+declare const AvatarRoot: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React.RefAttributes<HTMLSpanElement>, "ref"> & {
+    class?: string;
+    sx?: SxProps;
+    size?: AvatarSize;
+    rounded?: Rounded;
+    shadow?: Shadow;
+} & React.RefAttributes<HTMLSpanElement>>;
+declare const AvatarImage: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React.RefAttributes<HTMLImageElement>, "ref"> & {
+    class?: string;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLImageElement>>;
+declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarFallbackProps & React.RefAttributes<HTMLSpanElement>, "ref"> & {
+    class?: string;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLSpanElement>>;
+type AvatarComponent = typeof AvatarRoot & {
+    Image: typeof AvatarImage;
+    Fallback: typeof AvatarFallback;
+};
+export declare const Avatar: AvatarComponent;
+export { AvatarImage, AvatarFallback };

package/components/data-display/avatar/index.d.ts

@@ -0,0 +1 @@
+export * from "./Avatar";

package/components/data-display/skeleton/Skeleton.d.ts

@@ -0,0 +1,72 @@
+import * as React from "react";
+import { type Rounded } from "@/components/shared/rounded";
+import { type SxProps } from "@/styling";
+export type SkeletonVariant = "text" | "rect" | "circle";
+export type SkeletonSize = number | string;
+export type SkeletonProps = Omit<React.HTMLAttributes<HTMLDivElement>, "className"> & {
+    className?: string;
+    class?: string;
+    sx?: SxProps;
+    rounded?: Rounded;
+    width?: SkeletonSize;
+    height?: SkeletonSize;
+    inline?: boolean;
+    animated?: boolean;
+    variant?: SkeletonVariant;
+};
+export type SkeletonTextProps = Omit<React.HTMLAttributes<HTMLDivElement>, "className"> & {
+    className?: string;
+    class?: string;
+    sx?: SxProps;
+    rounded?: Rounded;
+    width?: SkeletonSize;
+    inline?: boolean;
+    animated?: boolean;
+    rows?: number;
+    rowHeight?: SkeletonSize;
+    gap?: SkeletonSize;
+    widths?: SkeletonSize[];
+};
+export type SkeletonAvatarProps = Omit<SkeletonProps, "children" | "variant" | "width" | "height"> & {
+    size?: SkeletonSize;
+};
+export type SkeletonButtonProps = Omit<SkeletonProps, "children" | "variant">;
+export type SkeletonCardProps = Omit<SkeletonProps, "children" | "variant" | "height"> & {
+    showAvatar?: boolean;
+    rows?: number;
+};
+/**
+ * Skeleton renders a neutral placeholder block for content that is still loading.
+ */
+export declare function Skeleton(props: SkeletonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Skeleton {
+    var displayName: string;
+}
+/**
+ * SkeletonText renders one or more text-like loading rows.
+ */
+export declare function SkeletonText(props: SkeletonTextProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SkeletonText {
+    var displayName: string;
+}
+/**
+ * SkeletonAvatar renders a circular placeholder for user or object avatars.
+ */
+export declare function SkeletonAvatar(props: SkeletonAvatarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SkeletonAvatar {
+    var displayName: string;
+}
+/**
+ * SkeletonButton renders a rounded placeholder sized like a common button.
+ */
+export declare function SkeletonButton(props: SkeletonButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SkeletonButton {
+    var displayName: string;
+}
+/**
+ * SkeletonCard renders a compact card loading layout composed from Skeleton parts.
+ */
+export declare function SkeletonCard(props: SkeletonCardProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SkeletonCard {
+    var displayName: string;
+}

package/components/data-display/skeleton/index.d.ts

@@ -0,0 +1,2 @@
+export { Skeleton, SkeletonAvatar, SkeletonButton, SkeletonCard, SkeletonText, } from "./Skeleton";
+export type { SkeletonAvatarProps, SkeletonButtonProps, SkeletonCardProps, SkeletonProps, SkeletonSize, SkeletonTextProps, SkeletonVariant, } from "./Skeleton";

package/components/form/select/Select.d.ts

@@ -0,0 +1,107 @@
+import * as React from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { type SxProps } from "@/styling";
+type StyledPrimitiveProps<TProps> = Omit<TProps, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+};
+export type SelectOption = {
+    label: React.ReactNode;
+    value: string;
+    disabled?: boolean;
+    textValue?: string;
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+};
+export type SelectOptionGroup = {
+    label?: React.ReactNode;
+    options: SelectOption[];
+    separator?: boolean;
+};
+export type SelectItemsProps = {
+    options: Array<SelectOption | SelectOptionGroup>;
+    itemProps?: Omit<SelectItemProps, "children" | "value" | "disabled" | "textValue">;
+    labelProps?: Omit<SelectLabelProps, "children">;
+    separatorProps?: SelectSeparatorProps;
+};
+export type SelectTriggerProps = StyledPrimitiveProps<React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>>;
+export type SelectScrollButtonProps = StyledPrimitiveProps<React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollUpButton>>;
+export type SelectContentProps = StyledPrimitiveProps<React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>>;
+export type SelectLabelProps = StyledPrimitiveProps<React.ComponentPropsWithoutRef<typeof SelectPrimitive.Label>>;
+export type SelectItemProps = StyledPrimitiveProps<React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item>>;
+export type SelectSeparatorProps = StyledPrimitiveProps<React.ComponentPropsWithoutRef<typeof SelectPrimitive.Separator>>;
+declare const Select: React.FC<SelectPrimitive.SelectProps>;
+declare const SelectGroup: React.ForwardRefExoticComponent<SelectPrimitive.SelectGroupProps & React.RefAttributes<HTMLDivElement>>;
+declare const SelectValue: React.ForwardRefExoticComponent<SelectPrimitive.SelectValueProps & React.RefAttributes<HTMLSpanElement>>;
+/**
+ * SelectTrigger 是 Select 的触发按钮，支持原生 Radix Trigger 属性与本库 `sx` 样式系统。
+ */
+declare const SelectTrigger: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * SelectScrollUpButton 用于长列表弹层的向上滚动控制。
+ */
+declare const SelectScrollUpButton: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectScrollUpButtonProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * SelectScrollDownButton 用于长列表弹层的向下滚动控制。
+ */
+declare const SelectScrollDownButton: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectScrollUpButtonProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * SelectContent 渲染下拉弹层，默认使用 Radix Portal 与 popper 定位。
+ */
+declare const SelectContent: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectContentProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * SelectLabel 用于在分组选项中显示不可选择的分组标题。
+ */
+declare const SelectLabel: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectLabelProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * SelectItem 是 Select 的可选项，需放在 SelectContent 内使用。
+ */
+declare const SelectItem: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectItemProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * SelectSeparator 用于在 SelectContent 内分隔选项区域。
+ */
+declare const SelectSeparator: React.ForwardRefExoticComponent<Omit<Omit<SelectPrimitive.SelectSeparatorProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * SelectItems 按配置快速渲染 SelectItem，同时保留 Select 的原始组合式能力。
+ */
+declare function SelectItems(props: SelectItemsProps): import("react/jsx-runtime").JSX.Element;
+export { Select, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton, SelectItems, };

package/components/form/select/index.d.ts

@@ -0,0 +1 @@
+export * from "./Select";

package/components/form/switch/Switch.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+import { type SxProps } from "@/styling";
+export type SwitchSize = "sm" | "md" | "lg";
+export type SwitchLabelPosition = "left" | "right";
+export type SwitchProps = Omit<React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    containerClass?: string;
+    containerClassName?: string;
+    containerStyle?: React.CSSProperties;
+    containerSx?: SxProps;
+    description?: React.ReactNode;
+    label?: React.ReactNode;
+    labelPosition?: SwitchLabelPosition;
+    size?: SwitchSize;
+    sx?: SxProps;
+    style?: React.CSSProperties;
+};
+/**
+ * 基于 Radix Switch 的开关组件，支持受控/非受控状态、标签说明与本库 `sx` 样式系统。
+ */
+declare const Switch: React.ForwardRefExoticComponent<Omit<Omit<SwitchPrimitive.SwitchProps & React.RefAttributes<HTMLButtonElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    containerClass?: string;
+    containerClassName?: string;
+    containerStyle?: React.CSSProperties;
+    containerSx?: SxProps;
+    description?: React.ReactNode;
+    label?: React.ReactNode;
+    labelPosition?: SwitchLabelPosition;
+    size?: SwitchSize;
+    sx?: SxProps;
+    style?: React.CSSProperties;
+} & React.RefAttributes<HTMLButtonElement>>;
+export { Switch };

package/components/form/switch/index.d.ts

@@ -0,0 +1 @@
+export * from "./Switch";

package/components/interact/button/Button.d.ts

@@ -13,8 +13,8 @@ type ButtonOwnProps = Omit<ButtonVariants, "rounded" | "shadow"> & {
     sx?: SxProps;
 };
 export type ButtonProps<T extends ElementType = "button"> = PolymorphicProps<T> & ButtonOwnProps;
-export declare function Button<T extends ElementType = "button">(props: ButtonProps<T>): import("react/jsx-runtime").JSX.Element;
-export declare namespace Button {
+declare function Button<T extends ElementType = "button">(props: ButtonProps<T>): import("react/jsx-runtime").JSX.Element;
+declare namespace Button {
     var displayName: string;
 }
-export {};
+export { Button };

package/components/interact/dialog/Dialog.d.ts

@@ -0,0 +1,121 @@
+import * as React from "react";
+import { type SxProps } from "@/styling";
+type StyledDomProps<T extends React.ElementType> = Omit<React.ComponentPropsWithoutRef<T>, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+};
+type AsChildProps = {
+    asChild?: boolean;
+    asChildWrapper?: React.ElementType;
+};
+export type DialogProps = {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    modal?: boolean;
+    lockScroll?: boolean;
+    destroyOnClose?: boolean;
+    closeOnMaskClick?: boolean;
+    scrollable?: boolean;
+    children?: React.ReactNode;
+};
+export type DialogTriggerProps = StyledDomProps<"button"> & AsChildProps;
+export type DialogCloseProps = StyledDomProps<"button"> & AsChildProps;
+export type DialogOverlayProps = StyledDomProps<"div"> & {
+    blur?: boolean;
+};
+export type DialogContentProps = StyledDomProps<"div"> & {
+    showClose?: boolean;
+    overlayClassName?: string;
+    overlaySx?: SxProps;
+    overlayBlur?: boolean;
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    onOpenAutoFocus?: (event: Event) => void;
+    onCloseAutoFocus?: (event: Event) => void;
+};
+export type DialogHeaderProps = React.HTMLAttributes<HTMLDivElement> & {
+    class?: string;
+    sx?: SxProps;
+};
+export type DialogFooterProps = React.HTMLAttributes<HTMLDivElement> & {
+    class?: string;
+    sx?: SxProps;
+};
+export type DialogTitleProps = StyledDomProps<"h2">;
+export type DialogDescriptionProps = StyledDomProps<"p">;
+declare const DialogTrigger: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & AsChildProps & React.RefAttributes<HTMLButtonElement>>;
+declare const DialogClose: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & AsChildProps & React.RefAttributes<HTMLButtonElement>>;
+type DialogPortalProps = {
+    children?: React.ReactNode;
+    container?: Element | DocumentFragment | null;
+};
+declare const DialogPortal: (props: DialogPortalProps) => React.ReactPortal | null;
+declare const DialogOverlay: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & {
+    blur?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DialogContent: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & {
+    showClose?: boolean;
+    overlayClassName?: string;
+    overlaySx?: SxProps;
+    overlayBlur?: boolean;
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    onOpenAutoFocus?: (event: Event) => void;
+    onCloseAutoFocus?: (event: Event) => void;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DialogHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    class?: string;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DialogFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    class?: string;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DialogTitle: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLHeadingElement>>;
+declare const DialogDescription: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLParagraphElement>>;
+type DialogCompound = ((props: DialogProps) => React.ReactElement) & {
+    Trigger: typeof DialogTrigger;
+    Portal: typeof DialogPortal;
+    Close: typeof DialogClose;
+    Overlay: typeof DialogOverlay;
+    Content: typeof DialogContent;
+    Header: typeof DialogHeader;
+    Footer: typeof DialogFooter;
+    Title: typeof DialogTitle;
+    Description: typeof DialogDescription;
+};
+declare const Dialog: DialogCompound;
+export { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, };

package/components/interact/dialog/index.d.ts

@@ -0,0 +1,2 @@
+export { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, } from "./Dialog";
+export type { DialogProps, DialogTriggerProps, DialogCloseProps, DialogOverlayProps, DialogContentProps, DialogHeaderProps, DialogFooterProps, DialogTitleProps, DialogDescriptionProps, } from "./Dialog";

package/components/interact/modal/Modal.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+import { type SxProps } from "@/styling";
+export type ModalBlur = boolean | number | string;
+export type ModalProps = Omit<React.HTMLAttributes<HTMLDivElement>, "className" | "style" | "onClose" | "onOpen"> & {
+    open?: boolean;
+    destroyOnClose?: boolean;
+    closeOnMaskClick?: boolean;
+    scrollable?: boolean;
+    alpha?: number;
+    blur?: ModalBlur;
+    x?: string;
+    y?: string;
+    translateX?: string;
+    translateY?: string;
+    onClose?: () => void;
+    onOpen?: () => void;
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+    contentClassName?: string;
+    contentClass?: string;
+    contentStyle?: React.CSSProperties;
+    contentSx?: SxProps;
+};
+/**
+ * Modal 全屏遮罩容器，适用于轻量弹层和临时聚焦内容。
+ */
+export declare function Modal(props: ModalProps): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace Modal {
+    var displayName: string;
+}

package/components/interact/modal/index.d.ts

@@ -0,0 +1,2 @@
+export { Modal } from "./Modal";
+export type { ModalProps, ModalBlur } from "./Modal";

package/components/interact/popover/Popover.d.ts

@@ -0,0 +1,119 @@
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import { type Rounded } from "@/components/shared/rounded";
+import { type Shadow } from "@/components/shared/shadow";
+import { type SxProps } from "@/styling";
+type RadixPopoverContentProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>;
+type RadixPopoverTriggerProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Trigger>;
+type RadixPopoverCloseProps = React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Close>;
+type PopoverWrapperProps<TProps> = Omit<TProps, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+};
+export type PopoverTriggerProps = PopoverWrapperProps<RadixPopoverTriggerProps>;
+export type PopoverCloseProps = PopoverWrapperProps<RadixPopoverCloseProps>;
+/**
+ * Popover 根组件，管理弹层的打开状态。
+ *
+ * 该组件保留 Radix Popover Root 的完整能力，支持非受控与受控两种用法。
+ */
+declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
+/**
+ * Popover 触发器。
+ *
+ * 使用 `asChild` 时会由本组件生成一层触发容器，业务子组件无需转发 ref。
+ */
+declare const PopoverTrigger: React.ForwardRefExoticComponent<Omit<Omit<PopoverPrimitive.PopoverTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLElement>>;
+/**
+ * Popover 锚点。
+ *
+ * 当弹层定位目标与触发器不是同一个元素时，可以使用 Anchor 明确定位参考元素。
+ */
+declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Popover 关闭按钮。
+ *
+ * 使用 `asChild` 时会由本组件生成一层关闭容器，业务子组件无需转发 ref。
+ */
+declare const PopoverClose: React.ForwardRefExoticComponent<Omit<Omit<PopoverPrimitive.PopoverCloseProps & React.RefAttributes<HTMLButtonElement>, "ref">, "className" | "style"> & {
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & React.RefAttributes<HTMLElement>>;
+/**
+ * PopoverContent 的属性。
+ */
+export type PopoverContentProps = Omit<RadixPopoverContentProps, "className" | "style"> & {
+    /**
+     * 弹层宽度。传入数字时自动转换为 px。
+     *
+     * @default 288
+     */
+    width?: number | string;
+    /**
+     * 弹层圆角，支持本库圆角预设或任意 CSS border-radius 值。
+     *
+     * @default "lg"
+     */
+    rounded?: Rounded;
+    /**
+     * 弹层阴影，支持本库阴影预设或任意 CSS box-shadow 值。
+     *
+     * @default "md"
+     */
+    shadow?: Shadow;
+    /**
+     * 本库 sx 样式入口，支持对象、数组、函数与嵌套选择器。
+     */
+    sx?: SxProps;
+    /**
+     * 兼容历史 class 写法。
+     */
+    class?: string;
+    className?: string;
+    style?: React.CSSProperties;
+};
+/**
+ * Popover 内容面板。
+ *
+ * 默认通过 Portal 渲染到 body，并保留 Radix Content 的定位、碰撞检测与焦点管理能力。
+ */
+declare const PopoverContent: React.ForwardRefExoticComponent<Omit<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref">, "className" | "style"> & {
+    /**
+     * 弹层宽度。传入数字时自动转换为 px。
+     *
+     * @default 288
+     */
+    width?: number | string;
+    /**
+     * 弹层圆角，支持本库圆角预设或任意 CSS border-radius 值。
+     *
+     * @default "lg"
+     */
+    rounded?: Rounded;
+    /**
+     * 弹层阴影，支持本库阴影预设或任意 CSS box-shadow 值。
+     *
+     * @default "md"
+     */
+    shadow?: Shadow;
+    /**
+     * 本库 sx 样式入口，支持对象、数组、函数与嵌套选择器。
+     */
+    sx?: SxProps;
+    /**
+     * 兼容历史 class 写法。
+     */
+    class?: string;
+    className?: string;
+    style?: React.CSSProperties;
+} & React.RefAttributes<HTMLDivElement>>;
+export { Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, };

package/components/interact/popover/index.d.ts

@@ -0,0 +1 @@
+export * from "./Popover";