asterui 0.10.3 → 0.12.0

package/README.md

@@ -102,106 +102,7 @@ export default function App() {
 
 ## Components
 
-### General
-- **Typography** - Text, Title, Paragraph, and Link components with consistent styling
-
-### Actions
-- **Button** - Buttons with multiple types, sizes, and variants
-- **Dropdown** - Composable dropdown menu with trigger, items, and dividers
-- **FloatButton** - Floating action button with BackTop variant
-- **ThemeController** - Theme switcher with swap and dropdown modes
-
-### Data Entry
-- **Autocomplete** - Search and select with keyboard navigation and filtering
-- **Cascader** - Cascade selection for hierarchical data
-- **Checkbox** - Checkboxes with sizes, colors, and indeterminate state
-- **ColorPicker** - Color selection with presets and custom colors
-- **DatePicker** - Interactive calendar date picker with custom formatting
-- **Fieldset** - Fieldset container with legend
-- **FileInput** - File input with sizes and colors
-- **Form** - Form component with React Hook Form integration and validation
-- **Input** - Text inputs with types, sizes, colors, and input masking
-- **InputNumber** - Numeric input with increment/decrement controls
-- **Label** - Form labels with required indicator and floating labels
-- **Mention** - Input with @mention support for tagging users
-- **Radio** - Radio buttons with group support
-- **Range** - Range slider with min, max, and step support
-- **Rating** - Star rating component
-- **Select** - Select dropdown with sizes and colors
-- **Textarea** - Multiline text input
-- **TimePicker** - Time input with hour and minute selection
-- **Toggle** - Toggle switches with sizes and colors
-- **Transfer** - Double-column transfer for moving items between lists
-- **TreeSelect** - Tree selection dropdown for hierarchical data
-- **Upload** - File upload with drag and drop support
-
-### Data Display
-- **Avatar** - User avatars with sizes, shapes, and group support
-- **Badge** - Notification badges, status indicators, and ribbons
-- **Card** - Composable card component with body, title, actions, and figure
-- **Carousel** - Image carousel with navigation and indicators
-- **Chart** - Data visualization with ApexCharts and theme integration
-- **Chat** - Chat message bubbles with avatars and timestamps
-- **Collapse** - Collapsible content panels
-- **Descriptions** - Display multiple read-only fields in groups
-- **Empty** - Empty state placeholder with custom images and actions
-- **Image** - Image component with fallback and preview support
-- **List** - Vertical list layout with customizable rows
-- **Pagination** - Page navigation with multiple sizes
-- **QRCode** - QR code generator
-- **Stats** - Statistics display with figures and actions
-- **Steps** - Step progress indicator
-- **Table** - Feature-rich data table with sorting and pagination
-- **Tag** - Categorization labels with colors and close button
-- **Timeline** - Timeline component for displaying chronological events
-- **Tree** - Hierarchical tree view with expand/collapse and selection
-
-### Layout
-- **Affix** - Make elements stick to viewport when scrolling
-- **Divider** - Horizontal and vertical dividers with optional text
-- **Drawer** - Sidebar drawer with multiple placements
-- **Footer** - Footer component with title sections
-- **Grid** - Flexible grid system with Row and Col components
-- **Hero** - Hero section with overlay and content wrapping
-- **Indicator** - Position indicators on elements
-- **Join** - Join multiple elements together seamlessly
-- **Layout** - Page layout with Header, Sider, Content, and Footer
-- **Masonry** - Responsive masonry grid layout
-- **Space** - Layout component for consistent spacing between elements
-- **Splitter** - Resizable split panes for adjustable layouts
-
-### Responsive
-- **Show/Hide** - Conditionally render content based on breakpoint
-- **useBreakpoint** - Hook for detecting current breakpoint and screen width
-
-### Navigation
-- **Breadcrumb** - Breadcrumb navigation trail
-- **Menu** - Menu with vertical, horizontal, and inline modes
-- **Navbar** - Navigation bar with start, center, and end sections
-- **Tabs** - Tab navigation with multiple variants
-
-### Feedback
-- **Alert** - Alert messages with multiple types and dismissible option
-- **Loading** - Loading spinners with sizes and overlay support
-- **Modal** - Modal dialogs with imperative API
-- **Notification** - Toast notifications with auto-dismiss and stacking
-- **Popconfirm** - Confirmation popover for actions
-- **Popover** - Floating content triggered by hover or click
-- **Progress** - Progress bars with colors and indeterminate state
-- **RadialProgress** - Circular progress indicator
-- **Result** - Result pages for operation outcomes
-- **Skeleton** - Loading placeholder with animated shimmer effect
-- **Tooltip** - Tooltips with multiple placements
-
-### Mockup
-- **Browser** - Browser window mockup with URL bar
-- **Code** - Terminal-style code display with line highlighting
-- **Phone** - iPhone-style phone frame mockup
-- **Window** - OS-style window frame mockup
-
-## Demo
-
-View live examples and documentation at [https://asterui.com](https://asterui.com)
+80+ components including forms, data display, navigation, feedback, and layout. See the full list at [asterui.com/components](https://asterui.com/components).
 
 ## Requirements
 

package/dist/components/Anchor.d.ts

@@ -0,0 +1,45 @@
+import { default as React } from 'react';
+export interface AnchorLinkItem {
+    /** Target element id (without #) */
+    href: string;
+    /** Link title */
+    title: React.ReactNode;
+    /** Nested links */
+    children?: AnchorLinkItem[];
+}
+export interface AnchorProps {
+    /** Anchor links (alternative to Anchor.Link children) */
+    items?: AnchorLinkItem[];
+    /** Layout direction */
+    direction?: 'horizontal' | 'vertical';
+    /** Offset from top when calculating scroll position */
+    offsetTop?: number;
+    /** Target scroll container (default: window) */
+    getContainer?: () => HTMLElement | Window;
+    /** Callback when active link changes */
+    onChange?: (activeLink: string) => void;
+    /** Callback when link is clicked */
+    onClick?: (e: React.MouseEvent, link: {
+        href: string;
+        title: React.ReactNode;
+    }) => void;
+    /** Currently active link (controlled) */
+    activeLink?: string;
+    /** Custom class name */
+    className?: string;
+    /** Anchor.Link children */
+    children?: React.ReactNode;
+}
+export interface AnchorLinkProps {
+    /** Target element id (without #) */
+    href: string;
+    /** Link title */
+    title: React.ReactNode;
+    /** Nested links */
+    children?: React.ReactNode;
+    /** Custom class name */
+    className?: string;
+}
+export declare const Anchor: React.FC<AnchorProps> & {
+    Link: React.FC<AnchorLinkProps>;
+};

package/dist/components/Diff.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+export interface DiffProps {
+    /** Left side content (revealed when dragging) */
+    left: React.ReactNode;
+    /** Right side content (hidden when dragging) */
+    right: React.ReactNode;
+    /** Aspect ratio class (e.g., "aspect-16/9", "aspect-4/3", "aspect-square") */
+    aspect?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Diff: React.FC<DiffProps>;

package/dist/components/Kbd.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+export interface KbdProps extends React.HTMLAttributes<HTMLElement> {
+    /** Size of the kbd */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** Key content */
+    children?: React.ReactNode;
+}
+export declare const Kbd: React.FC<KbdProps>;

package/dist/components/Segmented.d.ts

@@ -0,0 +1,37 @@
+import { default as React } from 'react';
+export type SegmentedValue = string | number;
+export interface SegmentedItemProps {
+    /** Option value */
+    value: SegmentedValue;
+    /** Disable this option */
+    disabled?: boolean;
+    /** Icon to display before label */
+    icon?: React.ReactNode;
+    /** Label content */
+    children: React.ReactNode;
+    /** Additional CSS class */
+    className?: string;
+}
+declare const SegmentedItem: React.FC<SegmentedItemProps>;
+export interface SegmentedProps {
+    /** Currently selected value (controlled) */
+    value?: SegmentedValue;
+    /** Default selected value (uncontrolled) */
+    defaultValue?: SegmentedValue;
+    /** Callback when selection changes */
+    onChange?: (value: SegmentedValue) => void;
+    /** Size variant */
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    /** Take full width of container */
+    block?: boolean;
+    /** Disable all options */
+    disabled?: boolean;
+    /** Additional CSS class */
+    className?: string;
+    /** Segmented.Item children */
+    children: React.ReactNode;
+}
+export declare const Segmented: React.FC<SegmentedProps> & {
+    Item: typeof SegmentedItem;
+};
+export {};

package/dist/components/TextRotate.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+export type TextRotateDuration = 6000 | 9000 | 12000 | 15000 | 18000;
+export interface TextRotateProps {
+    /** Text items to rotate through (max 6) */
+    items: React.ReactNode[];
+    /** Animation duration in ms (default 10000) */
+    duration?: TextRotateDuration;
+    /** Center text horizontally */
+    centered?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const TextRotate: React.FC<TextRotateProps>;

package/dist/components/Tour.d.ts

@@ -0,0 +1,61 @@
+import { default as React } from 'react';
+export type TourPlacement = 'top' | 'topLeft' | 'topRight' | 'bottom' | 'bottomLeft' | 'bottomRight' | 'left' | 'leftTop' | 'leftBottom' | 'right' | 'rightTop' | 'rightBottom' | 'center';
+export interface TourStepProps {
+    /** Target element ref or function returning element */
+    target?: React.RefObject<HTMLElement | null> | (() => HTMLElement | null) | null;
+    /** Step title */
+    title: React.ReactNode;
+    /** Step description */
+    description?: React.ReactNode;
+    /** Cover image or content above title */
+    cover?: React.ReactNode;
+    /** Placement of popover relative to target */
+    placement?: TourPlacement;
+    /** Custom class for this step's popover */
+    className?: string;
+    /** Called when this step becomes active */
+    onOpen?: () => void;
+    /** Called when leaving this step */
+    onClose?: () => void;
+}
+export interface TourProps {
+    /** Whether tour is visible */
+    open?: boolean;
+    /** Callback when tour closes */
+    onClose?: () => void;
+    /** Callback when tour finishes (last step completed) */
+    onFinish?: () => void;
+    /** Tour steps */
+    steps: TourStepProps[];
+    /** Current step (controlled) */
+    current?: number;
+    /** Callback when step changes */
+    onChange?: (current: number) => void;
+    /** Show mask overlay */
+    mask?: boolean;
+    /** Type affects styling */
+    type?: 'default' | 'primary';
+    /** Gap between highlight and target [radius, offset] or single number */
+    gap?: number | [number, number];
+    /** Text for prev button */
+    prevButtonText?: React.ReactNode;
+    /** Text for next button */
+    nextButtonText?: React.ReactNode;
+    /** Text for finish button */
+    finishButtonText?: React.ReactNode;
+    /** Text for skip button */
+    skipButtonText?: React.ReactNode;
+    /** Show skip button */
+    showSkip?: boolean;
+    /** Show step indicators */
+    showIndicators?: boolean;
+    /** Close on mask click */
+    closeOnMaskClick?: boolean;
+    /** Close on escape key */
+    closeOnEscape?: boolean;
+    /** Scroll target into view */
+    scrollIntoView?: boolean;
+    /** Z-index for tour overlay */
+    zIndex?: number;
+}
+export declare const Tour: React.FC<TourProps>;

package/dist/hooks/useClickOutside.d.ts

@@ -0,0 +1,17 @@
+import { RefObject } from 'react';
+/**
+ * Hook that detects clicks outside of a referenced element.
+ * Useful for closing dropdowns, modals, or menus.
+ *
+ * @param handler - Callback when click outside is detected
+ * @param enabled - Whether the listener is active (default: true)
+ * @returns Ref to attach to the element
+ *
+ * @example
+ * const ref = useClickOutside(() => setIsOpen(false))
+ *
+ * <div ref={ref}>
+ *   <Dropdown>...</Dropdown>
+ * </div>
+ */
+export declare function useClickOutside<T extends HTMLElement = HTMLElement>(handler: (event: MouseEvent | TouchEvent) => void, enabled?: boolean): RefObject<T | null>;

package/dist/hooks/useClipboard.d.ts

@@ -0,0 +1,20 @@
+export interface UseClipboardReturn {
+    copy: (text: string) => Promise<boolean>;
+    copied: boolean;
+    error: Error | null;
+    reset: () => void;
+}
+/**
+ * Hook for copying text to clipboard with success/error state.
+ *
+ * @param timeout - Duration in ms to show copied state (default: 2000)
+ * @returns Object with copy function and state
+ *
+ * @example
+ * const { copy, copied } = useClipboard()
+ *
+ * <Button onClick={() => copy('Hello!')}>
+ *   {copied ? 'Copied!' : 'Copy'}
+ * </Button>
+ */
+export declare function useClipboard(timeout?: number): UseClipboardReturn;

package/dist/hooks/useDebounce.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hook that delays updating a value until after a specified delay.
+ * Useful for search inputs to avoid excessive API calls.
+ *
+ * @param value - Value to debounce
+ * @param delay - Delay in milliseconds (default: 300)
+ * @returns Debounced value
+ *
+ * @example
+ * const [search, setSearch] = useState('')
+ * const debouncedSearch = useDebounce(search, 500)
+ *
+ * useEffect(() => {
+ *   // This runs 500ms after user stops typing
+ *   fetchResults(debouncedSearch)
+ * }, [debouncedSearch])
+ */
+export declare function useDebounce<T>(value: T, delay?: number): T;

package/dist/hooks/useDisclosure.d.ts

@@ -0,0 +1,20 @@
+export interface UseDisclosureReturn {
+    isOpen: boolean;
+    onOpen: () => void;
+    onClose: () => void;
+    onToggle: () => void;
+    setIsOpen: (value: boolean) => void;
+}
+/**
+ * Hook for managing open/close state of modals, drawers, dropdowns, etc.
+ *
+ * @param defaultIsOpen - Initial open state (default: false)
+ * @returns Object with isOpen state and control functions
+ *
+ * @example
+ * const { isOpen, onOpen, onClose } = useDisclosure()
+ *
+ * <Button onClick={onOpen}>Open Modal</Button>
+ * <Modal open={isOpen} onClose={onClose}>Content</Modal>
+ */
+export declare function useDisclosure(defaultIsOpen?: boolean): UseDisclosureReturn;

package/dist/hooks/useHover.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from 'react';
+export interface UseHoverReturn<T extends HTMLElement> {
+    ref: RefObject<T | null>;
+    isHovered: boolean;
+}
+/**
+ * Hook that tracks hover state of an element.
+ *
+ * @returns Object with ref and isHovered state
+ *
+ * @example
+ * const { ref, isHovered } = useHover<HTMLDivElement>()
+ *
+ * <div ref={ref} className={isHovered ? 'bg-blue-500' : 'bg-gray-500'}>
+ *   Hover me!
+ * </div>
+ */
+export declare function useHover<T extends HTMLElement = HTMLElement>(): UseHoverReturn<T>;

package/dist/hooks/useKeyPress.d.ts

@@ -0,0 +1,40 @@
+export interface UseKeyPressOptions {
+    /** Target element (default: window) */
+    target?: HTMLElement | Window | null;
+    /** Event type: 'keydown' | 'keyup' (default: 'keydown') */
+    event?: 'keydown' | 'keyup';
+    /** Prevent default browser behavior */
+    preventDefault?: boolean;
+}
+/**
+ * Hook that detects when a specific key is pressed.
+ *
+ * @param targetKey - Key to detect (e.g., 'Enter', 'Escape', 'a')
+ * @param options - Configuration options
+ * @returns Whether the key is currently pressed
+ *
+ * @example
+ * const enterPressed = useKeyPress('Enter')
+ * const escapePressed = useKeyPress('Escape')
+ *
+ * useEffect(() => {
+ *   if (escapePressed) closeModal()
+ * }, [escapePressed])
+ *
+ * @example
+ * // With callback for immediate action
+ * useKeyPress('Escape', { preventDefault: true })
+ */
+export declare function useKeyPress(targetKey: string, options?: UseKeyPressOptions): boolean;
+/**
+ * Hook that calls a callback when a specific key is pressed.
+ *
+ * @param targetKey - Key to detect
+ * @param callback - Function to call when key is pressed
+ * @param options - Configuration options
+ *
+ * @example
+ * useKeyPressCallback('Escape', () => closeModal())
+ * useKeyPressCallback('Enter', () => submitForm(), { preventDefault: true })
+ */
+export declare function useKeyPressCallback(targetKey: string, callback: (event: KeyboardEvent) => void, options?: UseKeyPressOptions): void;

package/dist/hooks/useLocalStorage.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hook for persisting state to localStorage.
+ *
+ * @param key - localStorage key
+ * @param initialValue - Initial value if key doesn't exist
+ * @returns [value, setValue, removeValue] tuple
+ *
+ * @example
+ * const [theme, setTheme] = useLocalStorage('theme', 'light')
+ * const [user, setUser, removeUser] = useLocalStorage('user', null)
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void, () => void];

package/dist/hooks/usePrevious.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hook that returns the previous value of a variable.
+ * Useful for comparing current and previous values in effects.
+ *
+ * @param value - Current value
+ * @returns Previous value (undefined on first render)
+ *
+ * @example
+ * const [count, setCount] = useState(0)
+ * const prevCount = usePrevious(count)
+ *
+ * // prevCount is the value from previous render
+ * console.log(`Changed from ${prevCount} to ${count}`)
+ */
+export declare function usePrevious<T>(value: T): T | undefined;

package/dist/hooks/useWindowSize.d.ts

@@ -0,0 +1,21 @@
+export interface WindowSize {
+    width: number;
+    height: number;
+}
+/**
+ * Hook that tracks window dimensions.
+ * Updates on window resize.
+ *
+ * @returns Object with current width and height
+ *
+ * @example
+ * const { width, height } = useWindowSize()
+ *
+ * return (
+ *   <div>
+ *     Window: {width} x {height}
+ *     {width < 768 && <MobileNav />}
+ *   </div>
+ * )
+ */
+export declare function useWindowSize(): WindowSize;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { Affix } from './components/Affix';
 export type { AffixProps } from './components/Affix';
+export { Anchor } from './components/Anchor';
+export type { AnchorProps, AnchorLinkProps, AnchorLinkItem } from './components/Anchor';
 export { Alert } from './components/Alert';
 export type { AlertProps } from './components/Alert';
 export { Autocomplete } from './components/Autocomplete';
@@ -38,6 +40,8 @@ export { DatePicker } from './components/DatePicker';
 export type { DatePickerProps } from './components/DatePicker';
 export { Descriptions } from './components/Descriptions';
 export type { DescriptionsProps, DescriptionsItemProps, DescriptionsSize, DescriptionsLayout } from './components/Descriptions';
+export { Diff } from './components/Diff';
+export type { DiffProps } from './components/Diff';
 export { Divider } from './components/Divider';
 export type { DividerProps } from './components/Divider';
 export { Drawer } from './components/Drawer';
@@ -72,6 +76,8 @@ export { InputNumber } from './components/InputNumber';
 export type { InputNumberProps } from './components/InputNumber';
 export { Join } from './components/Join';
 export type { JoinProps } from './components/Join';
+export { Kbd } from './components/Kbd';
+export type { KbdProps } from './components/Kbd';
 export { Label } from './components/Label';
 export type { LabelProps, FloatingLabelProps } from './components/Label';
 export { Layout, useSiderContext } from './components/Layout';
@@ -126,6 +132,8 @@ export { Result } from './components/Result';
 export type { ResultProps, ResultStatus } from './components/Result';
 export { Select } from './components/Select';
 export type { SelectProps } from './components/Select';
+export { Segmented } from './components/Segmented';
+export type { SegmentedProps, SegmentedItemProps, SegmentedValue } from './components/Segmented';
 export { Skeleton } from './components/Skeleton';
 export type { SkeletonProps } from './components/Skeleton';
 export { Space } from './components/Space';
@@ -144,6 +152,8 @@ export { Tabs } from './components/Tabs';
 export type { TabsProps, TabPanelProps } from './components/Tabs';
 export { Textarea } from './components/Textarea';
 export type { TextareaProps } from './components/Textarea';
+export { TextRotate } from './components/TextRotate';
+export type { TextRotateProps, TextRotateDuration } from './components/TextRotate';
 export { Tag, CheckableTag } from './components/Tag';
 export type { TagProps, CheckableTagProps } from './components/Tag';
 export { ThemeController } from './components/ThemeController';
@@ -154,6 +164,8 @@ export { Timeline } from './components/Timeline';
 export type { TimelineProps, TimelineItemProps } from './components/Timeline';
 export { Toggle } from './components/Toggle';
 export type { ToggleProps } from './components/Toggle';
+export { Tour } from './components/Tour';
+export type { TourProps, TourStepProps, TourPlacement } from './components/Tour';
 export { Tooltip } from './components/Tooltip';
 export type { TooltipProps } from './components/Tooltip';
 export { Transfer } from './components/Transfer';
@@ -170,3 +182,17 @@ export { Show, Hide } from './components/Responsive';
 export type { ShowProps, HideProps } from './components/Responsive';
 export { useBreakpoint } from './hooks/useBreakpoint';
 export type { Breakpoint, UseBreakpointReturn } from './hooks/useBreakpoint';
+export { useDisclosure } from './hooks/useDisclosure';
+export type { UseDisclosureReturn } from './hooks/useDisclosure';
+export { useClipboard } from './hooks/useClipboard';
+export type { UseClipboardReturn } from './hooks/useClipboard';
+export { useLocalStorage } from './hooks/useLocalStorage';
+export { useDebounce } from './hooks/useDebounce';
+export { useClickOutside } from './hooks/useClickOutside';
+export { usePrevious } from './hooks/usePrevious';
+export { useHover } from './hooks/useHover';
+export type { UseHoverReturn } from './hooks/useHover';
+export { useKeyPress, useKeyPressCallback } from './hooks/useKeyPress';
+export type { UseKeyPressOptions } from './hooks/useKeyPress';
+export { useWindowSize } from './hooks/useWindowSize';
+export type { WindowSize } from './hooks/useWindowSize';