@ptengine/design-components 0.3.0

package/src/components/ui/message.tsx

@@ -0,0 +1,85 @@
+import * as React from 'react';
+
+import { cn } from '../../lib/utils';
+
+function MessageGroup({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+    return (
+        <div
+            data-slot="message-group"
+            className={cn('flex min-w-0 flex-col gap-[8px]', className)}
+            {...props}
+        />
+    );
+}
+
+function Message({
+    className,
+    align = 'start',
+    ...props
+}: React.HTMLAttributes<HTMLDivElement> & { align?: 'start' | 'end' }) {
+    return (
+        <div
+            data-slot="message"
+            data-align={align}
+            className={cn(
+                'group/message relative flex w-full min-w-0 gap-[8px] text-[14px] leading-[20px] data-[align=end]:flex-row-reverse',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+function MessageAvatar({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+    return (
+        <div
+            data-slot="message-avatar"
+            className={cn(
+                'flex w-fit min-w-[32px] shrink-0 items-center justify-center self-end overflow-hidden rounded-full bg-muted group-has-[[data-slot=message-footer]]/message:-translate-y-[32px]',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+function MessageContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+    return (
+        <div
+            data-slot="message-content"
+            className={cn(
+                'flex w-full min-w-0 flex-col gap-[10px] break-words group-data-[align=end]/message:[&>[data-slot]]:self-end',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+function MessageHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+    return (
+        <div
+            data-slot="message-header"
+            className={cn(
+                'flex max-w-full min-w-0 items-center px-[12px] text-[13px] leading-[20px] font-medium text-muted-foreground group-has-[[data-variant=ghost]]/message:px-0',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+function MessageFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+    return (
+        <div
+            data-slot="message-footer"
+            className={cn(
+                'flex max-w-full min-w-0 items-center px-[12px] text-[13px] leading-[20px] font-medium text-muted-foreground group-has-[[data-variant=ghost]]/message:px-0 group-data-[align=end]/message:justify-end',
+                className
+            )}
+            {...props}
+        />
+    );
+}
+
+export { MessageGroup, Message, MessageAvatar, MessageContent, MessageFooter, MessageHeader };

package/src/components/ui/native-select.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { ChevronDown } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+
+const NativeSelect = React.forwardRef<
+    HTMLSelectElement,
+    React.SelectHTMLAttributes<HTMLSelectElement>
+>(({ className, children, ...props }, ref) => (
+    <div className="relative w-full">
+        <select
+            ref={ref}
+            className={cn(
+                'h-[32px] w-full appearance-none rounded-[var(--pt-radius-md)] border border-input bg-transparent pl-[12px] pr-[32px] text-[13px] leading-[20px] text-foreground transition-colors enabled:hover:border-neutral focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-destructive aria-[invalid=true]:enabled:hover:border-destructive aria-[invalid=true]:focus-visible:ring-destructive/30',
+                className
+            )}
+            {...props}
+        >
+            {children}
+        </select>
+        <ChevronDown
+            className="pointer-events-none absolute right-[10px] top-1/2 size-[16px] -translate-y-1/2 text-muted-foreground"
+            aria-hidden="true"
+        />
+    </div>
+));
+NativeSelect.displayName = 'NativeSelect';
+
+export { NativeSelect };

package/src/components/ui/navigation-menu.tsx

@@ -0,0 +1,120 @@
+import * as React from 'react';
+import * as NavigationMenuPrimitive from '@radix-ui/react-navigation-menu';
+import { cva } from 'class-variance-authority';
+import { ChevronDown } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+
+const NavigationMenu = React.forwardRef<
+    React.ElementRef<typeof NavigationMenuPrimitive.Root>,
+    React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Root>
+>(({ className, children, ...props }, ref) => (
+    <NavigationMenuPrimitive.Root
+        ref={ref}
+        className={cn('relative z-10 flex max-w-max flex-1 items-center justify-center', className)}
+        {...props}
+    >
+        {children}
+        <NavigationMenuViewport />
+    </NavigationMenuPrimitive.Root>
+));
+NavigationMenu.displayName = NavigationMenuPrimitive.Root.displayName;
+
+const NavigationMenuList = React.forwardRef<
+    React.ElementRef<typeof NavigationMenuPrimitive.List>,
+    React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.List>
+>(({ className, ...props }, ref) => (
+    <NavigationMenuPrimitive.List
+        ref={ref}
+        className={cn('group flex flex-1 list-none items-center justify-center gap-[4px]', className)}
+        {...props}
+    />
+));
+NavigationMenuList.displayName = NavigationMenuPrimitive.List.displayName;
+
+const NavigationMenuItem = NavigationMenuPrimitive.Item;
+
+const navigationMenuTriggerStyle = cva(
+    'state-layer group inline-flex h-[32px] w-max items-center justify-center rounded-[var(--pt-radius-md)] bg-background px-[16px] py-[8px] text-[14px] leading-[20px] font-medium text-foreground transition-colors focus:bg-accent focus:text-accent-foreground focus:outline-none disabled:cursor-not-allowed disabled:opacity-50 data-[state=open]:bg-accent'
+);
+
+const NavigationMenuTrigger = React.forwardRef<
+    React.ElementRef<typeof NavigationMenuPrimitive.Trigger>,
+    React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Trigger>
+>(({ className, children, ...props }, ref) => (
+    <NavigationMenuPrimitive.Trigger
+        ref={ref}
+        className={cn(navigationMenuTriggerStyle(), 'group', className)}
+        {...props}
+    >
+        {children}{' '}
+        <ChevronDown
+            className="relative top-[1px] ml-[4px] h-[12px] w-[12px] transition duration-300 group-data-[state=open]:rotate-180"
+            aria-hidden="true"
+        />
+    </NavigationMenuPrimitive.Trigger>
+));
+NavigationMenuTrigger.displayName = NavigationMenuPrimitive.Trigger.displayName;
+
+const NavigationMenuContent = React.forwardRef<
+    React.ElementRef<typeof NavigationMenuPrimitive.Content>,
+    React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Content>
+>(({ className, ...props }, ref) => (
+    <NavigationMenuPrimitive.Content
+        ref={ref}
+        className={cn(
+            'left-0 top-0 w-full data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 md:absolute md:w-auto',
+            className
+        )}
+        {...props}
+    />
+));
+NavigationMenuContent.displayName = NavigationMenuPrimitive.Content.displayName;
+
+const NavigationMenuLink = NavigationMenuPrimitive.Link;
+
+const NavigationMenuViewport = React.forwardRef<
+    React.ElementRef<typeof NavigationMenuPrimitive.Viewport>,
+    React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Viewport>
+>(({ className, ...props }, ref) => (
+    <div className={cn('absolute left-0 top-full flex justify-center')}>
+        <NavigationMenuPrimitive.Viewport
+            className={cn(
+                'origin-top-center relative mt-[6px] h-[var(--radix-navigation-menu-viewport-height)] w-full overflow-hidden rounded-[var(--pt-radius-md)] border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 md:w-[var(--radix-navigation-menu-viewport-width)]',
+                className
+            )}
+            ref={ref}
+            {...props}
+        />
+    </div>
+));
+NavigationMenuViewport.displayName = NavigationMenuPrimitive.Viewport.displayName;
+
+const NavigationMenuIndicator = React.forwardRef<
+    React.ElementRef<typeof NavigationMenuPrimitive.Indicator>,
+    React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Indicator>
+>(({ className, ...props }, ref) => (
+    <NavigationMenuPrimitive.Indicator
+        ref={ref}
+        className={cn(
+            'top-full z-[1] flex h-[6px] items-end justify-center overflow-hidden data-[state=visible]:animate-in data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:fade-in',
+            className
+        )}
+        {...props}
+    >
+        <div className="relative top-[60%] h-[8px] w-[8px] rotate-45 rounded-tl-[var(--pt-radius-sm)] bg-border" />
+    </NavigationMenuPrimitive.Indicator>
+));
+NavigationMenuIndicator.displayName = NavigationMenuPrimitive.Indicator.displayName;
+
+export {
+    navigationMenuTriggerStyle,
+    NavigationMenu,
+    NavigationMenuList,
+    NavigationMenuItem,
+    NavigationMenuContent,
+    NavigationMenuTrigger,
+    NavigationMenuLink,
+    NavigationMenuIndicator,
+    NavigationMenuViewport
+};

package/src/components/ui/pagination.tsx

@@ -0,0 +1,108 @@
+import * as React from 'react';
+import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+import { type ButtonProps, buttonVariants } from './button';
+
+const Pagination = ({ className, ...props }: React.ComponentProps<'nav'>) => (
+    <nav
+        role="navigation"
+        aria-label="pagination"
+        className={cn('mx-auto flex w-full justify-center', className)}
+        {...props}
+    />
+);
+Pagination.displayName = 'Pagination';
+
+const PaginationContent = React.forwardRef<HTMLUListElement, React.ComponentProps<'ul'>>(
+    ({ className, ...props }, ref) => (
+        <ul ref={ref} className={cn('flex flex-row items-center gap-[4px]', className)} {...props} />
+    )
+);
+PaginationContent.displayName = 'PaginationContent';
+
+const PaginationItem = React.forwardRef<HTMLLIElement, React.ComponentProps<'li'>>(
+    ({ ...props }, ref) => <li ref={ref} {...props} />
+);
+PaginationItem.displayName = 'PaginationItem';
+
+type PaginationLinkProps = {
+    isActive?: boolean;
+} & Pick<ButtonProps, 'size'> &
+    React.ComponentProps<'a'>;
+
+const PaginationLink = ({ className, isActive, size = 'icon', ...props }: PaginationLinkProps) => (
+    <a
+        aria-current={isActive ? 'page' : undefined}
+        className={cn(
+            buttonVariants({
+                variant: isActive ? 'secondary' : 'ghost',
+                size
+            }),
+            className
+        )}
+        {...props}
+    />
+);
+PaginationLink.displayName = 'PaginationLink';
+
+/* 库不做 i18n:可见文案与无障碍标签由消费方传入,默认英文(同 SearchInput 的 clearLabel) */
+const PaginationPrevious = ({
+    className,
+    label = 'Previous',
+    ...props
+}: React.ComponentProps<typeof PaginationLink> & { label?: string }) => (
+    <PaginationLink
+        aria-label={label}
+        size="default"
+        className={cn('gap-[4px] pl-[10px]', className)}
+        {...props}
+    >
+        <ChevronLeft className="h-[16px] w-[16px]" />
+        <span>{label}</span>
+    </PaginationLink>
+);
+PaginationPrevious.displayName = 'PaginationPrevious';
+
+const PaginationNext = ({
+    className,
+    label = 'Next',
+    ...props
+}: React.ComponentProps<typeof PaginationLink> & { label?: string }) => (
+    <PaginationLink
+        aria-label={label}
+        size="default"
+        className={cn('gap-[4px] pr-[10px]', className)}
+        {...props}
+    >
+        <span>{label}</span>
+        <ChevronRight className="h-[16px] w-[16px]" />
+    </PaginationLink>
+);
+PaginationNext.displayName = 'PaginationNext';
+
+const PaginationEllipsis = ({
+    className,
+    label = 'More pages',
+    ...props
+}: React.ComponentProps<'span'> & { label?: string }) => (
+    <span
+        aria-hidden
+        className={cn('flex h-[32px] w-[36px] items-center justify-center text-foreground', className)}
+        {...props}
+    >
+        <MoreHorizontal className="h-[16px] w-[16px]" />
+        <span className="sr-only">{label}</span>
+    </span>
+);
+PaginationEllipsis.displayName = 'PaginationEllipsis';
+
+export {
+    Pagination,
+    PaginationContent,
+    PaginationLink,
+    PaginationItem,
+    PaginationPrevious,
+    PaginationNext,
+    PaginationEllipsis
+};

package/src/components/ui/popover.tsx

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+
+import { cn } from '../../lib/utils';
+
+const Popover = PopoverPrimitive.Root;
+
+const PopoverTrigger = PopoverPrimitive.Trigger;
+
+const PopoverAnchor = PopoverPrimitive.Anchor;
+
+const PopoverContent = React.forwardRef<
+    React.ElementRef<typeof PopoverPrimitive.Content>,
+    React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
+>(({ className, align = 'center', sideOffset = 4, ...props }, ref) => (
+    <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Content
+            ref={ref}
+            align={align}
+            sideOffset={sideOffset}
+            className={cn(
+                'z-[var(--pt-z-popup,50)] w-[288px] rounded-[var(--pt-radius-md)] border bg-popover p-[16px] text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+                className
+            )}
+            {...props}
+        />
+    </PopoverPrimitive.Portal>
+));
+PopoverContent.displayName = PopoverPrimitive.Content.displayName;
+
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor };

package/src/components/ui/progress.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import * as ProgressPrimitive from '@radix-ui/react-progress';
+
+import { cn } from '../../lib/utils';
+
+const Progress = React.forwardRef<
+    React.ElementRef<typeof ProgressPrimitive.Root>,
+    React.ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>
+>(({ className, value, ...props }, ref) => (
+    <ProgressPrimitive.Root
+        ref={ref}
+        className={cn('relative h-[8px] w-full overflow-hidden rounded-full bg-secondary', className)}
+        {...props}
+    >
+        <ProgressPrimitive.Indicator
+            className="h-full w-full flex-1 bg-primary transition-all"
+            style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+        />
+    </ProgressPrimitive.Root>
+));
+Progress.displayName = ProgressPrimitive.Root.displayName;
+
+export { Progress };

package/src/components/ui/radio-group.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import { Circle } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+
+const RadioGroup = React.forwardRef<
+    React.ElementRef<typeof RadioGroupPrimitive.Root>,
+    React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
+>(({ className, ...props }, ref) => {
+    return <RadioGroupPrimitive.Root className={cn('grid gap-[8px]', className)} {...props} ref={ref} />;
+});
+RadioGroup.displayName = RadioGroupPrimitive.Root.displayName;
+
+const RadioGroupItem = React.forwardRef<
+    React.ElementRef<typeof RadioGroupPrimitive.Item>,
+    React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
+>(({ className, ...props }, ref) => {
+    return (
+        <RadioGroupPrimitive.Item
+            ref={ref}
+            className={cn(
+                'aspect-square h-[16px] w-[16px] rounded-full border border-neutral text-primary transition-colors enabled:hover:border-strong data-[state=unchecked]:enabled:active:bg-press focus:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:border-weak disabled:bg-disable disabled:text-disabled enabled:data-[state=checked]:border-primary',
+                className
+            )}
+            {...props}
+        >
+            <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
+                <Circle className="h-[14px] w-[14px] fill-current" />
+            </RadioGroupPrimitive.Indicator>
+        </RadioGroupPrimitive.Item>
+    );
+});
+RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName;
+
+export { RadioGroup, RadioGroupItem };

package/src/components/ui/resizable.tsx

@@ -0,0 +1,40 @@
+import { GripVertical } from 'lucide-react';
+import * as ResizablePrimitive from 'react-resizable-panels';
+
+import { cn } from '../../lib/utils';
+
+const ResizablePanelGroup = ({
+    className,
+    ...props
+}: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) => (
+    <ResizablePrimitive.PanelGroup
+        className={cn('flex h-full w-full data-[panel-group-direction=vertical]:flex-col', className)}
+        {...props}
+    />
+);
+
+const ResizablePanel = ResizablePrimitive.Panel;
+
+const ResizableHandle = ({
+    withHandle,
+    className,
+    ...props
+}: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & {
+    withHandle?: boolean;
+}) => (
+    <ResizablePrimitive.PanelResizeHandle
+        className={cn(
+            'relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-[4px] after:-translate-x-1/2 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1 data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-[4px] data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0 [&[data-panel-group-direction=vertical]>div]:rotate-90',
+            className
+        )}
+        {...props}
+    >
+        {withHandle && (
+            <div className="z-10 flex h-[16px] w-[12px] items-center justify-center rounded-[var(--pt-radius-sm)] border bg-border">
+                <GripVertical className="h-[10px] w-[10px]" />
+            </div>
+        )}
+    </ResizablePrimitive.PanelResizeHandle>
+);
+
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle };

package/src/components/ui/scroll-area.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
+
+import { cn } from '../../lib/utils';
+
+const ScrollArea = React.forwardRef<
+    React.ElementRef<typeof ScrollAreaPrimitive.Root>,
+    React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
+>(({ className, children, ...props }, ref) => (
+    <ScrollAreaPrimitive.Root
+        ref={ref}
+        className={cn('relative overflow-hidden', className)}
+        {...props}
+    >
+        <ScrollAreaPrimitive.Viewport className="h-full w-full rounded-[inherit]">
+            {children}
+        </ScrollAreaPrimitive.Viewport>
+        <ScrollBar />
+        <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+));
+ScrollArea.displayName = ScrollAreaPrimitive.Root.displayName;
+
+const ScrollBar = React.forwardRef<
+    React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
+    React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>
+>(({ className, orientation = 'vertical', ...props }, ref) => (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+        ref={ref}
+        orientation={orientation}
+        className={cn(
+            'flex touch-none select-none transition-colors',
+            orientation === 'vertical' && 'h-full w-[10px] border-l border-l-transparent p-[1px]',
+            orientation === 'horizontal' && 'h-[10px] flex-col border-t border-t-transparent p-[1px]',
+            className
+        )}
+        {...props}
+    >
+        <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-border" />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+));
+ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName;
+
+export { ScrollArea, ScrollBar };

package/src/components/ui/search-input.tsx

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import { Search, X } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from './input-group';
+
+/* 三档:高 24/32/40 · 字 12/13/14 · 辅助图标 12/16/16 · 左右间距 8/10/12(带 icon 组件档) */
+const SIZE_CLASSES = {
+    sm: 'h-[24px] px-[8px] rounded-[var(--pt-radius-sm)] [&_input]:text-[12px] [&_input]:leading-[16px]',
+    default: 'h-[32px] px-[10px]',
+    lg: 'h-[40px] px-[12px] [&_input]:text-[14px] [&_input]:leading-[20px]'
+} as const;
+
+/* 放大镜(寓意图标):16 / 16 / 20 */
+const ICON_CLASSES = {
+    sm: '[&_svg]:size-[16px]',
+    default: '[&_svg]:size-[16px]',
+    lg: '[&_svg]:size-[20px]'
+} as const;
+
+/* 清空钮(按钮里的辅助图标):sm 12 · default 12 · lg 16;容器与按钮同值,避免跨元素层叠打架 */
+const CLEAR_ADDON_CLASSES = {
+    sm: '[&_svg]:size-[12px]',
+    default: '[&_svg]:size-[12px]',
+    lg: '[&_svg]:size-[16px]'
+} as const;
+
+const CLEAR_BUTTON_CLASSES = {
+    sm: 'size-[20px] p-0 [&_svg]:size-[12px]',
+    default: 'size-[24px] p-0 [&_svg]:size-[12px]',
+    lg: 'size-[24px] p-0 [&_svg]:size-[16px]'
+} as const;
+
+export interface SearchInputProps
+    extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type' | 'size'> {
+    /** 尺寸:sm 24px(行内)· default 32px(常规)· lg 36px(页面级主搜索) */
+    size?: keyof typeof SIZE_CLASSES;
+    /** 受控值 */
+    value: string;
+    /** 值变化回调(输入 / 点清空 / Esc 清空统一经由这里) */
+    onValueChange: (value: string) => void;
+    /** 清空(点 ✕ 或 Esc)后的附加回调,如重置分页 */
+    onClear?: () => void;
+    /** 清空钮的无障碍标签(库不做 i18n,消费方传译文) */
+    clearLabel?: string;
+    /** 容器 className(只用于宽度等布局) */
+    className?: string;
+}
+
+const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
+    (
+        { value, onValueChange, onClear, clearLabel = 'Clear', size = 'default', className, onKeyDown, disabled, ...props },
+        ref
+    ) => {
+        const clear = () => {
+            onValueChange('');
+            onClear?.();
+        };
+
+        return (
+            <InputGroup className={cn(SIZE_CLASSES[size], className)}>
+                <InputGroupAddon align="inline-start" className={ICON_CLASSES[size]}>
+                    <Search />
+                </InputGroupAddon>
+                <InputGroupInput
+                    ref={ref}
+                    role="searchbox"
+                    value={value}
+                    disabled={disabled}
+                    onChange={e => onValueChange(e.target.value)}
+                    onKeyDown={e => {
+                        if (e.key === 'Escape' && value) {
+                            e.stopPropagation();
+                            clear();
+                        }
+                        onKeyDown?.(e);
+                    }}
+                    {...props}
+                />
+                {value && !disabled && (
+                    <InputGroupAddon align="inline-end" className={CLEAR_ADDON_CLASSES[size]}>
+                        <InputGroupButton
+                            aria-label={clearLabel}
+                            className={CLEAR_BUTTON_CLASSES[size]}
+                            onClick={clear}
+                        >
+                            <X />
+                        </InputGroupButton>
+                    </InputGroupAddon>
+                )}
+            </InputGroup>
+        );
+    }
+);
+SearchInput.displayName = 'SearchInput';
+
+export { SearchInput };