@noxickon/onyx 4.1.6 → 5.0.0

package/AI-README.md

@@ -1,6 +1,6 @@
 # Onyx Component Library - AI Reference Guide
 
-**Version:** 3.0.0 • **Updated:** 2025-12-16 • **Built from:** bfdd6f72
+**Version:** 3.0.0 • **Updated:** 2026-02-04 • **Built from:** a0a8ed34
 
 > This comprehensive reference guide provides detailed information about all components, hooks, contexts, utilities, and patterns in the Onyx component library. Designed for AI assistants and developers to quickly understand component APIs and usage.
 
@@ -90,7 +90,7 @@ import '@noxickon/onyx/animations'; // Animations (optional)
 
 ---
 
-# UI Components (43)
+# UI Components (45)
 
 ## OxAccordion
 
@@ -226,7 +226,8 @@ interface OxAspectRatioFallbackProps extends ComponentPropsWithRef<'div'> {
 
 Avatar component with status indicators and loading states.
 
-**Pattern**: Simple Component
+**Pattern**: Simple Component + Compound Component (OxAvatarField)
+**Sub-components**: `OxAvatarField`, `OxAvatarField.Content`, `OxAvatarField.Name`, `OxAvatarField.Subtitle`
 
 ### Props
 
@@ -242,11 +243,31 @@ interface OxAvatarProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
   src?: string;
   status?: 'online' | 'offline' | 'away' | 'busy';
 }
+
+interface OxAvatarFieldProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  orientation?: 'horizontal' | 'vertical'; // Layout direction
+}
+
+interface OxAvatarFieldContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxAvatarFieldNameProps extends ComponentPropsWithRef<'span'> {
+  children: ReactNode;
+}
+
+interface OxAvatarFieldSubtitleProps extends ComponentPropsWithRef<'span'> {
+  children: ReactNode;
+}
 ```
 
 ### Example
 
 ```tsx
+{
+  /* Basic avatar */
+}
 <OxAvatar
   src="/avatar.jpg"
   alt="User Name"
@@ -255,7 +276,18 @@ interface OxAvatarProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
   showStatus
   status="online"
   fallback="UN"
-/>
+/>;
+
+{
+  /* Avatar with field layout */
+}
+<OxAvatarField orientation="horizontal">
+  <OxAvatar src="/avatar.jpg" alt="John Doe" size="md" />
+  <OxAvatarField.Content>
+    <OxAvatarField.Name>John Doe</OxAvatarField.Name>
+    <OxAvatarField.Subtitle>Software Engineer</OxAvatarField.Subtitle>
+  </OxAvatarField.Content>
+</OxAvatarField>;
 ```
 
 ---
@@ -266,7 +298,7 @@ Notification badge for displaying counts or status indicators on UI elements. De
 
 **Pattern**: Simple Component
 
-> **Note:** Badges are optimized for ghost buttons and icons. For colored backgrounds, use the `bgColor` prop for custom solutions. Count badges use subtle backgrounds; dot badges use solid colors for status indicators.
+> **Note:** Badges are optimized for ghost buttons and icons. Count badges use subtle backgrounds; dot badges use solid colors for status indicators. Use the `variant` prop to change colors.
 
 ### Props
 
@@ -341,7 +373,7 @@ interface OxTagProps extends ComponentPropsWithRef<'span'> {
 
 ## OxBreadcrumb
 
-Breadcrumb navigation with asChild pattern support.
+Breadcrumb navigation with asSlot pattern support.
 
 **Pattern**: Compound Component
 **Sub-components**: `Ellipsis`, `Item`, `Link`, `Page`, `Separator`
@@ -358,7 +390,7 @@ interface OxBreadcrumbItemProps extends ComponentPropsWithRef<'li'> {
 }
 
 interface OxBreadcrumbLinkProps extends ComponentPropsWithRef<'a'> {
-  asChild?: boolean; // Renders as child component (e.g., Next.js Link)
+  asSlot?: boolean; // Renders as child component (e.g., Next.js Link)
   children: ReactNode;
   current?: boolean; // Marks as current page
   href?: string;
@@ -390,9 +422,9 @@ interface OxBreadcrumbEllipsisProps extends ComponentPropsWithRef<'span'> {}
 </OxBreadcrumb>;
 
 {
-  /* Using asChild with Next.js Link */
+  /* Using asSlot with Next.js Link */
 }
-<OxBreadcrumb.Link asChild>
+<OxBreadcrumb.Link asSlot>
   <Link to="/dashboard">Dashboard</Link>
 </OxBreadcrumb.Link>;
 ```
@@ -405,13 +437,13 @@ Button component with variants, sizes, and loading states.
 
 **Pattern**: Simple Component
 
-> **Note:** For links styled as buttons, use `OxButton` with `asChild` prop. Use `OxLink` only for text-based links with underline.
+> **Note:** For links styled as buttons, use `OxButton` with `asSlot` prop. Use `OxLink` only for text-based links with underline.
 
 ### Props
 
 ```tsx
 interface OxButtonProps extends ComponentPropsWithRef<'button'> {
-  asChild?: boolean; // Renders as child element (useful for Link components)
+  asSlot?: boolean; // Renders as child element (useful for Link components)
   fullWidth?: boolean; // Expands to full container width
   isLoading?: boolean; // Shows spinner, disables interaction
   size?: 'sm' | 'md' | 'lg';
@@ -429,7 +461,7 @@ interface OxButtonProps extends ComponentPropsWithRef<'button'> {
 {
   /* Render as Link while keeping button styling */
 }
-<OxButton asChild variant="primary">
+<OxButton asSlot variant="primary">
   <Link to="/dashboard">Dashboard</Link>
 </OxButton>;
 ```
@@ -712,7 +744,7 @@ interface OxDrawerFooterProps extends ComponentPropsWithRef<'div'> {
 Dropdown menu with extensive sub-components.
 
 **Pattern**: Compound Component
-**Sub-components**: `Body`, `Content`, `Footer`, `Header`, `Item`, `Label`, `Separator`, `Shortcut`, `Trigger`
+**Sub-components**: `Body`, `CheckboxItem`, `Content`, `Footer`, `Group`, `Header`, `Item`, `RadioGroup`, `RadioItem`, `Separator`, `Shortcut`, `SubMenu`, `SubMenuContent`, `SubMenuTrigger`, `Trigger`
 
 ### Props
 
@@ -720,6 +752,7 @@ Dropdown menu with extensive sub-components.
 interface OxDropdownProps {
   align?: 'start' | 'center' | 'end';
   children: ReactNode;
+  closeOnOutsideClick?: boolean; // Close when clicking outside
   defaultOpen?: boolean;
   disabled?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -729,7 +762,7 @@ interface OxDropdownProps {
 
 interface OxDropdownTriggerProps extends ComponentPropsWithRef<'button'> {
   animateIcon?: boolean; // Animates icon on open/close
-  asChild?: boolean; // Renders as child component (useful for custom triggers)
+  asSlot?: boolean; // Renders as child component (useful for custom triggers)
   children: ReactNode;
   hideIcon?: boolean;
   icon?: LucideIcon;
@@ -754,14 +787,50 @@ interface OxDropdownItemButtonProps extends Omit<ComponentPropsWithRef<'button'>
 }
 
 interface OxDropdownItemLinkProps extends ComponentPropsWithRef<'a'> {
-  disabled?: boolean; // Disables link navigation
+  disabled?: boolean;
   href: string; // Required for link variant
 }
 
-interface OxDropdownLabelProps extends ComponentPropsWithRef<'div'> {
+interface OxDropdownCheckboxItemProps extends Omit<
+  ComponentPropsWithRef<'button'>,
+  'type' | 'onChange'
+> {
+  checked?: boolean;
+  closeOnSelect?: boolean; // Close dropdown when selected
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+}
+
+interface OxDropdownRadioGroupProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+  children: ReactNode;
+  closeOnSelect?: boolean; // Close dropdown when item selected
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  value?: string;
+}
+
+interface OxDropdownRadioItemProps extends Omit<ComponentPropsWithRef<'button'>, 'type' | 'value'> {
+  value: string; // Required
+}
+
+interface OxDropdownGroupProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  label?: string; // Group label
+}
+
+interface OxDropdownSubMenuProps {
   children: ReactNode;
 }
 
+interface OxDropdownSubMenuTriggerProps extends Omit<ComponentPropsWithRef<'button'>, 'type'> {
+  disabled?: boolean;
+}
+
+interface OxDropdownSubMenuContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  className?: string;
+}
+
 interface OxDropdownShortcutProps extends ComponentPropsWithRef<'span'> {
   children: ReactNode;
 }
@@ -790,6 +859,33 @@ interface OxDropdownSeparatorProps extends Omit<OxSeparatorProps, 'orientation'
       </OxDropdown.Item>
       <OxDropdown.Item href="/settings">Settings</OxDropdown.Item>
       <OxDropdown.Separator />
+
+      {/* Checkbox items */}
+      <OxDropdown.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+        Show Grid
+      </OxDropdown.CheckboxItem>
+
+      {/* Radio group */}
+      <OxDropdown.RadioGroup value={view} onValueChange={setView}>
+        <OxDropdown.RadioItem value="list">List View</OxDropdown.RadioItem>
+        <OxDropdown.RadioItem value="grid">Grid View</OxDropdown.RadioItem>
+      </OxDropdown.RadioGroup>
+
+      {/* Grouped items */}
+      <OxDropdown.Group label="More Actions">
+        <OxDropdown.Item>Archive</OxDropdown.Item>
+        <OxDropdown.Item>Export</OxDropdown.Item>
+      </OxDropdown.Group>
+
+      {/* Submenu */}
+      <OxDropdown.SubMenu>
+        <OxDropdown.SubMenuTrigger>Share</OxDropdown.SubMenuTrigger>
+        <OxDropdown.SubMenuContent>
+          <OxDropdown.Item>Copy Link</OxDropdown.Item>
+          <OxDropdown.Item>Email</OxDropdown.Item>
+        </OxDropdown.SubMenuContent>
+      </OxDropdown.SubMenu>
+
       <OxDropdown.Item onClick={handleDelete}>Delete</OxDropdown.Item>
     </OxDropdown.Body>
   </OxDropdown.Content>
@@ -900,7 +996,7 @@ interface OxFloatingProps {
 }
 
 interface OxFloatingTriggerProps extends ComponentPropsWithRef<'div'> {
-  asChild?: boolean; // Renders as child component
+  asSlot?: boolean; // Renders as child component
   children: ReactNode;
 }
 
@@ -940,7 +1036,7 @@ interface OxHoverCardProps {
 }
 
 interface OxHoverCardTriggerProps extends ComponentPropsWithoutRef<'div'> {
-  asChild?: boolean;
+  asSlot?: boolean;
   children: ReactNode;
 }
 
@@ -954,7 +1050,7 @@ interface OxHoverCardContentProps extends ComponentPropsWithoutRef<'div'> {
 
 ```tsx
 <OxHoverCard openDelay={200} closeDelay={100}>
-  <OxHoverCard.Trigger asChild>
+  <OxHoverCard.Trigger asSlot>
     <OxButton>Hover me</OxButton>
   </OxHoverCard.Trigger>
   <OxHoverCard.Content>
@@ -1006,6 +1102,40 @@ import { Check } from 'lucide-react';
 
 ---
 
+## OxImage
+
+Image component with loading states and fallback support.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxImageProps extends Omit<ComponentPropsWithRef<'img'>, 'onLoad' | 'onError'> {
+  alt: string; // Required - Alt text for accessibility
+  fallback?: ReactNode; // Content shown when image fails to load
+  objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+  onLoadComplete?: () => void; // Called when image loads successfully
+  onLoadError?: () => void; // Called when image fails to load
+  src: string; // Required - Image source URL
+}
+```
+
+### Example
+
+```tsx
+<OxImage
+  src="/photo.jpg"
+  alt="Profile photo"
+  objectFit="cover"
+  onLoadComplete={() => console.log('Loaded')}
+  onLoadError={() => console.log('Failed')}
+  fallback={<OxSkeleton shape="rectangle" />}
+/>
+```
+
+---
+
 ## OxJsonField (alpha)
 
 JSON data display with syntax highlighting.
@@ -1122,13 +1252,13 @@ Link component for text-based navigation with hover underline.
 
 **Pattern**: Simple Component
 
-> **Note:** For button-styled links (e.g., call-to-action buttons), use `OxButton` with `asChild` instead. `OxLink` is for inline and text-based links only.
+> **Note:** For button-styled links (e.g., call-to-action buttons), use `OxButton` with `asSlot` instead. `OxLink` is for inline and text-based links only.
 
 ### Props
 
 ```tsx
 interface OxLinkProps extends ComponentPropsWithRef<'a'> {
-  asChild?: boolean; // Renders as child element (useful for routing libraries)
+  asSlot?: boolean; // Renders as child element (useful for routing libraries)
   disabled?: boolean; // Disables link navigation
   size?: 'sm' | 'md' | 'lg';
   variant?: 'primary' | 'secondary' | 'accent'; // primary = violet text, secondary = white text
@@ -1145,7 +1275,7 @@ interface OxLinkProps extends ComponentPropsWithRef<'a'> {
 {
   /* Use with React Router */
 }
-<OxLink asChild>
+<OxLink asSlot>
   <Link to="/dashboard">Dashboard</Link>
 </OxLink>;
 ```
@@ -1367,7 +1497,7 @@ interface OxPaginationItemProps extends ComponentPropsWithRef<'li'> {
 }
 
 interface OxPaginationLinkProps extends ComponentPropsWithRef<'a'> {
-  asChild?: boolean; // Renders as child component (for routing libraries)
+  asSlot?: boolean; // Renders as child component (for routing libraries)
   children: ReactNode;
   disabled?: boolean;
   href?: string;
@@ -1375,14 +1505,14 @@ interface OxPaginationLinkProps extends ComponentPropsWithRef<'a'> {
 }
 
 interface OxPaginationPreviousProps extends ComponentPropsWithRef<'a'> {
-  asChild?: boolean; // Renders as child component
+  asSlot?: boolean; // Renders as child component
   children?: ReactNode;
   disabled?: boolean;
   href?: string;
 }
 
 interface OxPaginationNextProps extends ComponentPropsWithRef<'a'> {
-  asChild?: boolean; // Renders as child component
+  asSlot?: boolean; // Renders as child component
   children?: ReactNode;
   disabled?: boolean;
   href?: string;
@@ -1419,7 +1549,7 @@ interface OxPaginationEllipsisProps extends ComponentPropsWithRef<'span'> {}
 
 ## OxPopover
 
-Popover component built on Floating.
+Popover component built on Popper.
 
 **Pattern**: Compound Component
 **Sub-components**: `Content`, `Trigger`
@@ -1427,9 +1557,10 @@ Popover component built on Floating.
 ### Props
 
 ```tsx
-interface OxPopoverProps extends ComponentPropsWithRef<'div'> {
+interface OxPopoverProps {
   align?: 'start' | 'center' | 'end';
-  children: React.ReactNode;
+  children: ReactNode;
+  closeOnOutsideClick?: boolean; // Close when clicking outside
   defaultOpen?: boolean;
   disabled?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -1437,13 +1568,13 @@ interface OxPopoverProps extends ComponentPropsWithRef<'div'> {
   side?: 'top' | 'bottom' | 'left' | 'right';
 }
 
-interface OxPopoverTriggerProps extends ComponentPropsWithRef<'button'> {
-  asChild?: boolean; // Renders as child component
-  children: React.ReactNode;
+interface OxPopoverTriggerProps extends ComponentPropsWithoutRef<'button'> {
+  asSlot?: boolean; // Renders as child component
+  children: ReactNode;
 }
 
-interface OxPopoverContentProps extends ComponentPropsWithRef<'div'> {
-  children: React.ReactNode;
+interface OxPopoverContentProps extends ComponentPropsWithoutRef<'div'> {
+  children: ReactNode;
   showCloseButton?: boolean;
 }
 ```
@@ -1451,7 +1582,7 @@ interface OxPopoverContentProps extends ComponentPropsWithRef<'div'> {
 ### Example
 
 ```tsx
-<OxPopover side="bottom">
+<OxPopover side="bottom" closeOnOutsideClick>
   <OxPopover.Trigger>Click me</OxPopover.Trigger>
   <OxPopover.Content showCloseButton>Popover content here</OxPopover.Content>
 </OxPopover>
@@ -1479,7 +1610,7 @@ interface OxPopperProps {
 }
 
 interface OxPopperAnchorProps extends ComponentPropsWithoutRef<'div'> {
-  asChild?: boolean;
+  asSlot?: boolean;
   children?: ReactNode;
   virtualRef?: RefObject<Measurable | null>; // For virtual anchor positioning
 }
@@ -1503,7 +1634,7 @@ interface OxPopperContentProps extends ComponentPropsWithoutRef<'div'> {
 
 ```tsx
 <OxPopper>
-  <OxPopper.Anchor asChild>
+  <OxPopper.Anchor asSlot>
     <button>Anchor element</button>
   </OxPopper.Anchor>
   <OxPopper.Content side="bottom" align="start" sideOffset={8}>
@@ -1949,6 +2080,43 @@ interface OxTabsContentProps extends ComponentPropsWithRef<'div'> {
 
 ---
 
+## OxThemeSwitcher
+
+Theme toggle button for switching between light, dark, and system themes.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+type Theme = 'light' | 'dark' | 'system';
+type ThemeSwitcherSize = 'sm' | 'md' | 'lg';
+
+interface OxThemeSwitcherProps extends Omit<ComponentPropsWithRef<'button'>, 'onChange'> {
+  onThemeChange?: (theme: Theme) => void; // Called when theme changes
+  size?: ThemeSwitcherSize;
+  theme?: Theme; // Controlled theme value
+}
+```
+
+### Example
+
+```tsx
+{
+  /* Uncontrolled - uses useTheme hook internally */
+}
+<OxThemeSwitcher size="md" />;
+
+{
+  /* Controlled */
+}
+<OxThemeSwitcher theme={currentTheme} onThemeChange={setCurrentTheme} size="lg" />;
+```
+
+**Note**: Works with the `useTheme` hook for theme management.
+
+---
+
 ## OxTimeline (alpha)
 
 Timeline component.
@@ -1995,63 +2163,123 @@ interface OxTimelineItemProps extends ComponentPropsWithRef<'li'> {
 
 ---
 
-## OxToast (beta)
+## OxToast
 
-Toast notification system.
+Toast notification system built on Sonner.
 
 **Pattern**: Context-based Component
-**Additional Exports**: `OxToastProvider`, `useOxToast`
+**Additional Exports**: `OxToastProvider`, `useOxToast`, `toast`
 
 ### Props
 
 ```tsx
-interface OxToastData {
-  color?: ColorStyleName;
-  customContent?: ReactNode;
+type OxToastPosition =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+interface OxToastOptions {
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+  cancel?: {
+    label: string;
+    onClick?: () => void;
+  };
   description?: string;
   duration?: number; // Auto-dismiss duration in ms
-  icon?: LucideIcon;
-  id: string; // Required - Unique ID
-  isRemoving?: boolean; // Internal removal state
-  path?: string; // SVG path
-  title: string; // Required
-  type: StatusType; // Required
+  icon?: LucideIcon | ReactNode;
+  onAutoClose?: () => void;
+  onDismiss?: () => void;
 }
 
-interface OxToastProps {
-  align: 'left' | 'center' | 'right'; // Required
-  onRemove: (id: string) => void; // Required
-  position: 'top' | 'bottom'; // Required
-  toasts: OxToastData[]; // Required
+interface OxToastProviderProps {
+  children: ReactNode;
+  closeButton?: boolean; // Show close button on toasts
+  expand?: boolean; // Expand toasts on hover
+  gap?: number; // Gap between toasts
+  offset?: string | number; // Offset from viewport edge
+  position?: OxToastPosition; // Default: 'bottom-right'
+  richColors?: boolean; // Use rich semantic colors
+  theme?: 'light' | 'dark' | 'system';
+  visibleToasts?: number; // Max visible toasts
+}
+```
+
+### Hook API
+
+```tsx
+interface OxToastContextApi {
+  (title: string, options?: OxToastOptions): string | number; // Default toast
+  success: (title: string, options?: OxToastOptions) => string | number;
+  error: (title: string, options?: OxToastOptions) => string | number;
+  warning: (title: string, options?: OxToastOptions) => string | number;
+  info: (title: string, options?: OxToastOptions) => string | number;
+  loading: (title: string, options?: OxToastOptions) => string | number;
+  destructive: (title: string, options?: OxToastOptions) => string | number;
+  custom: (content: ReactNode, options?: { duration?: number }) => string | number;
+  promise: <T>(
+    promise: Promise<T>,
+    messages: {
+      loading: string;
+      success: string | ((data: T) => string);
+      error: string | ((error: unknown) => string);
+    }
+  ) => Promise<T>;
+  dismiss: (id?: string | number) => void; // Dismiss specific or all toasts
 }
 ```
 
-### Hook
-
-```tsx
-const { showToast } = useOxToast();
-
-showToast({
-  title: 'Success!',
-  description: 'Your changes have been saved.',
-  type: 'success',
-  duration: 5000,
-});
-```
-
 ### Example
 
 ```tsx
-// Wrap app
-<OxToastProvider>
+// Wrap app with provider
+<OxToastProvider position="bottom-right" richColors>
   <App />
 </OxToastProvider>;
 
-// Use in component
+// Use hook in component
 function MyComponent() {
-  const { showToast } = useOxToast();
+  const toast = useOxToast();
 
-  return <button onClick={() => showToast({ title: 'Hello', type: 'info' })}>Show Toast</button>;
+  return (
+    <div>
+      <button onClick={() => toast('Default notification')}>Default</button>
+      <button onClick={() => toast.success('Changes saved!')}>Success</button>
+      <button onClick={() => toast.error('Something went wrong')}>Error</button>
+      <button onClick={() => toast.warning('Please review')}>Warning</button>
+      <button onClick={() => toast.info('New update available')}>Info</button>
+
+      {/* With description and action */}
+      <button
+        onClick={() =>
+          toast.success('File uploaded', {
+            description: 'Your file has been uploaded successfully.',
+            action: { label: 'View', onClick: () => navigate('/files') },
+          })
+        }
+      >
+        With Action
+      </button>
+
+      {/* Promise toast */}
+      <button
+        onClick={() =>
+          toast.promise(saveData(), {
+            loading: 'Saving...',
+            success: 'Data saved!',
+            error: 'Failed to save',
+          })
+        }
+      >
+        Promise
+      </button>
+    </div>
+  );
 }
 ```
 
@@ -2188,12 +2416,18 @@ interface OxCheckboxProps extends Omit<
   value?: string;
 }
 
-interface OxCheckboxGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+interface OxCheckboxGroupProps extends Omit<
+  ComponentPropsWithoutRef<'div'>,
+  'defaultValue' | 'onChange'
+> {
   children: ReactNode;
+  defaultValue?: string[]; // Uncontrolled default values
   disabled?: boolean; // Disables all checkboxes in group
+  error?: boolean; // Error state styling
   name: string; // Required
-  onChange?: (value: (string | number)[]) => void;
-  value?: (string | number)[]; // Controlled selected values
+  onValueChange?: (value: string[]) => void; // Called when selection changes
+  orientation?: 'horizontal' | 'vertical'; // Layout direction
+  value?: string[]; // Controlled selected values
 }
 
 interface OxCheckboxGroupItemProps extends Omit<
@@ -2201,7 +2435,7 @@ interface OxCheckboxGroupItemProps extends Omit<
   'type' | 'size' | 'children' | 'checked' | 'defaultChecked' | 'value'
 > {
   error?: boolean;
-  value: string | number; // Required
+  value: string; // Required
 }
 ```
 
@@ -2221,7 +2455,12 @@ interface OxCheckboxGroupItemProps extends Omit<
 {
   /* Checkbox group */
 }
-<OxCheckbox.Group name="features" value={selected} onChange={setSelected}>
+<OxCheckbox.Group
+  name="features"
+  value={selected}
+  onValueChange={setSelected}
+  orientation="vertical"
+>
   <OxCheckbox.GroupItem value="feature1" />
   <OxCheckbox.GroupItem value="feature2" />
 </OxCheckbox.Group>;
@@ -2561,8 +2800,11 @@ Numeric input with increment/decrement controls.
 ### Props
 
 ```tsx
-interface OxNumberInputContainerProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
-  defaultValue?: number;
+interface OxNumberInputContainerProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'defaultValue' | 'onChange'
+> {
+  defaultValue?: number | null;
   disabled?: boolean;
   error?: boolean;
   locale?: string; // Locale for number formatting
@@ -2570,12 +2812,12 @@ interface OxNumberInputContainerProps extends Omit<ComponentPropsWithRef<'div'>,
   maximumFractionDigits?: number; // Max decimal places
   min?: number; // Minimum value
   minimumFractionDigits?: number; // Min decimal places
-  onChange?: (value: number | undefined) => void;
+  onChange?: (value: number | null) => void;
   required?: boolean;
   steps?: number; // Increment/decrement step value
   useGrouping?: boolean; // Use thousand separators
   validationMessage?: string; // Custom error message shown below input
-  value?: number; // Controlled value
+  value?: number | null; // Controlled value
 }
 
 interface OxNumberInputProps {
@@ -2740,29 +2982,28 @@ Radio button group.
 ```tsx
 interface OxRadioGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
   children: ReactNode; // Required
-  defaultValue?: string | number;
+  defaultValue?: string; // Uncontrolled default value
   disabled?: boolean; // Disables all radio buttons
   error?: boolean;
   name?: string;
-  onChange?: (value: string | number) => void;
+  onValueChange?: (value: string) => void; // Called when selection changes
+  orientation?: 'horizontal' | 'vertical'; // Layout direction
   required?: boolean;
-  value?: string | number; // Controlled selected value
+  value?: string; // Controlled selected value
 }
 
-interface OxRadioItemProps extends Omit<
+interface OxRadioGroupItemProps extends Omit<
   ComponentPropsWithoutRef<'input'>,
-  'type' | 'size' | 'required'
+  'type' | 'size' | 'required' | 'value' | 'name'
 > {
-  error?: boolean;
-  onCheckedChange?: (checked: boolean) => void; // Called when this item is checked
-  value?: string | number;
+  value: string; // Required - unique value for this option
 }
 ```
 
 ### Example
 
 ```tsx
-<OxRadio.Group name="plan" value={plan} onChange={setPlan}>
+<OxRadio.Group name="plan" value={plan} onValueChange={setPlan} orientation="vertical">
   <OxRadio.Item value="basic" />
   <OxRadio.Item value="pro" />
   <OxRadio.Item value="enterprise" />
@@ -2783,21 +3024,44 @@ Select dropdown with single and multi-select.
 ### Props
 
 ```tsx
-interface OxSelectProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+type OxSelectValue = string | number | null;
+
+// Single select
+interface OxSelectSingleProps extends Omit<ComponentPropsWithRef<'div'>, 'defaultValue'> {
+  children: ReactNode;
   defaultOpen?: boolean;
-  defaultValue?: string | number | null | Array<string | number | null>;
+  defaultValue?: OxSelectValue;
   disabled?: boolean;
   error?: boolean;
   id?: string;
   isLoading?: boolean; // Shows loading state
-  multiple?: boolean; // Enable multi-select
-  onChange?: (value: string | number | null | Array<string | number | null>) => void;
+  multiple?: false; // Single select (default)
   onOpenChange?: (open: boolean) => void;
+  onValueChange?: (value: OxSelectValue) => void;
   open?: boolean; // Controlled open state
   required?: boolean;
-  value?: string | number | null | Array<string | number | null>; // Controlled value
+  value?: OxSelectValue; // Controlled value
 }
 
+// Multi-select
+interface OxSelectMultipleProps extends Omit<ComponentPropsWithRef<'div'>, 'defaultValue'> {
+  children: ReactNode;
+  defaultOpen?: boolean;
+  defaultValue?: OxSelectValue[];
+  disabled?: boolean;
+  error?: boolean;
+  id?: string;
+  isLoading?: boolean;
+  multiple: true; // Required for multi-select
+  onOpenChange?: (open: boolean) => void;
+  onValueChange?: (value: OxSelectValue[]) => void;
+  open?: boolean;
+  required?: boolean;
+  value?: OxSelectValue[];
+}
+
+type OxSelectProps = OxSelectSingleProps | OxSelectMultipleProps;
+
 interface OxSelectTriggerProps extends ComponentPropsWithRef<'button'> {
   displayAsTag?: boolean; // Display selected items as tags (multi-select)
   placeholder?: string;
@@ -2811,7 +3075,7 @@ interface OxSelectGroupProps extends ComponentPropsWithRef<'div'> {
 }
 
 interface OxSelectItemProps extends Omit<ComponentPropsWithRef<'button'>, 'value'> {
-  value: string | number | null; // Required
+  value: OxSelectValue; // Required
 }
 ```
 
@@ -2821,7 +3085,7 @@ interface OxSelectItemProps extends Omit<ComponentPropsWithRef<'button'>, 'value
 {
   /* Single select */
 }
-<OxSelect value={country} onChange={setCountry}>
+<OxSelect value={country} onValueChange={setCountry}>
   <OxSelect.Trigger placeholder="Select country" />
   <OxSelect.Content>
     <OxSelect.Item value="us">United States</OxSelect.Item>
@@ -2832,7 +3096,7 @@ interface OxSelectItemProps extends Omit<ComponentPropsWithRef<'button'>, 'value
 {
   /* Multi-select with badges */
 }
-<OxSelect multiple value={tags} onChange={setTags}>
+<OxSelect multiple value={tags} onValueChange={setTags}>
   <OxSelect.Trigger displayAsTag tagColor="blue" />
   <OxSelect.Content>
     <OxSelect.Group label="Categories">
@@ -3523,7 +3787,7 @@ function MyComponent() {
 
 ---
 
-# Hooks (13)
+# Hooks (14)
 
 ## useControllableState
 
@@ -4266,6 +4530,105 @@ function ResponsiveComponent() {
 
 ---
 
+## useSort
+
+Client-side and server-side sorting with flexible API.
+
+### Signature
+
+```tsx
+// Client-side (with data)
+function useSort<T, K extends string = string>(
+  data: T[],
+  options?: UseSortOptions<K>
+): UseSortReturnWithData<T, K>;
+
+// Server-side (state only)
+function useSort<K extends string = string>(options?: UseSortOptions<K>): UseSortReturnStateOnly<K>;
+
+type SortDirection = 'asc' | 'desc';
+
+interface SortState<K extends string = string> {
+  direction: SortDirection;
+  key: K;
+}
+
+interface UseSortOptions<K extends string = string> {
+  defaultDirection?: SortDirection;
+  defaultKey?: K;
+}
+
+interface UseSortReturnBase<K extends string = string> {
+  clearSort: () => void;
+  setSortState: (state: SortState<K> | null) => void;
+  sortState: SortState<K> | null;
+  toggleSort: (key: K) => void;
+}
+
+interface UseSortReturnWithData<T, K extends string = string> extends UseSortReturnBase<K> {
+  sortedData: T[];
+}
+
+type UseSortReturnStateOnly<K extends string = string> = UseSortReturnBase<K>;
+```
+
+### Example
+
+```tsx
+// Client-side sorting
+function UsersTable() {
+  const { sortedData, sortState, toggleSort, clearSort } = useSort(users, {
+    defaultKey: 'name',
+    defaultDirection: 'asc',
+  });
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th onClick={() => toggleSort('name')}>Name</th>
+          <th onClick={() => toggleSort('age')}>Age</th>
+        </tr>
+      </thead>
+      <tbody>
+        {sortedData.map((user) => (
+          <tr key={user.id}>
+            <td>{user.name}</td>
+            <td>{user.age}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+// Server-side sorting
+function ServerSideTable() {
+  const { sortState, toggleSort, clearSort } = useSort({
+    defaultKey: 'name',
+    defaultDirection: 'asc',
+  });
+
+  useEffect(() => {
+    fetchUsers({
+      sortBy: sortState?.key,
+      sortOrder: sortState?.direction,
+    });
+  }, [sortState]);
+
+  return <table>{/* ... */}</table>;
+}
+```
+
+**Notes**:
+
+- Toggle cycle: none → asc → desc → none
+- Supports nested paths (e.g., `profile.score`)
+- `sortedData` is memoized for performance
+- Uses `es-toolkit` for sorting
+
+---
+
 ## useTheme
 
 Theme management with localStorage persistence.
@@ -4697,7 +5060,7 @@ formatTimestamp(new Date(Date.now() - 5 * 60 * 1000));
 
 ## hasDataSlot
 
-React slot validation type guard.
+React slot validation type guard for slot-based component composition.
 
 ### Function
 
@@ -4724,6 +5087,7 @@ const headerSlot = children.find((child) => hasDataSlot(child, 'header'));
 
 - Type guard for TypeScript narrowing
 - Validates React element and slot attribute
+- Used for slot-based component composition (NOT related to `asSlot` prop)
 
 ---
 
@@ -4837,11 +5201,11 @@ validatePhone('+14155552671', { allowedCountries: ['US', 'CA'] });
 
 # Common Patterns
 
-## asChild Pattern
+## asSlot Pattern
 
-The `asChild` prop enables polymorphic rendering using Radix Slot. When `asChild={true}`, the component renders as its child element while preserving the component's styling and functionality.
+The `asSlot` prop enables polymorphic rendering using Radix Slot. When `asSlot={true}`, the component renders as its child element while preserving the component's styling and functionality.
 
-**Components with asChild**:
+**Components with asSlot**:
 
 - `OxBreadcrumb.Link`
 - `OxButton`
@@ -4858,7 +5222,7 @@ The `asChild` prop enables polymorphic rendering using Radix Slot. When `asChild
 {
   /* Render as Next.js Link while keeping button styling */
 }
-<OxButton asChild variant="primary">
+<OxButton asSlot variant="primary">
   <Link to="/dashboard">Dashboard</Link>
 </OxButton>;
 ```