@noxickon/onyx 2.0.4 → 4.0.0

package/AI-README.md

@@ -0,0 +1,5034 @@
+# Onyx Component Library - AI Reference Guide
+
+**Version:** 3.0.0 • **Updated:** 2025-12-16 • **Built from:** bfdd6f72
+
+> 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.
+
+## Installation
+
+Install Onyx and its peer dependencies:
+
+```bash
+npm install @noxickon/onyx lucide-react
+```
+
+### Peer Dependencies
+
+**Required:**
+
+- `react` ^19.0.0
+- `react-dom` ^19.0.0
+- `lucide-react` ^0.500.0
+
+**Optional:**
+
+- `@apollo/client` ^4.0.0 (if using Apollo features)
+- `graphql` ^16.0.0 (if using GraphQL features)
+- `@mdi/js` ^7.4.47 (alternative icon library)
+- `@mdi/react` ^1.6.1 (alternative icon library)
+
+## Setup
+
+Import Onyx components and styles:
+
+```tsx
+import { OxButton, OxCard } from '@noxickon/onyx';
+import { Check } from 'lucide-react';
+import '@noxickon/onyx/styles';
+
+function App() {
+  return (
+    <OxButton variant="primary">
+      <OxIcon icon={Check} />
+      Click Me
+    </OxButton>
+  );
+}
+```
+
+## Package Exports
+
+Onyx uses a multi-entry build system for optimal tree-shaking:
+
+```tsx
+// UI Components (main export)
+import { OxButton, OxCard, OxDialog } from '@noxickon/onyx';
+
+// Forms
+import { OxCheckbox, OxInput, OxSelect } from '@noxickon/onyx/forms';
+
+// Typography
+import { OxHeading, OxLabel } from '@noxickon/onyx/typography';
+
+// Contexts
+import { OxAuthProvider, useOxAuth } from '@noxickon/onyx/contexts';
+
+// Hooks
+import { useForm, useFilterQuery, useFormState } from '@noxickon/onyx/hooks';
+
+// Layouts
+import { OxAppLayout, OxSidebar, OxMainContent } from '@noxickon/onyx/layouts';
+
+// Route Guard Factories
+import {
+  createOxProtectedRoute,
+  createOxGuestRoute,
+  createOxRoleRoute,
+} from '@noxickon/onyx/routes';
+
+// Utilities
+import { cn, buildUrl, validateEmail } from '@noxickon/onyx/utils';
+
+// Legacy Components (deprecated)
+import { OxFloating, useVirtualList } from '@noxickon/onyx/legacy';
+
+// Styles
+import '@noxickon/onyx/styles'; // Component styles (required)
+import '@noxickon/onyx/shared'; // Shared utility classes (optional)
+import '@noxickon/onyx/animations'; // Animations (optional)
+```
+
+---
+
+# UI Components (43)
+
+## OxAccordion
+
+Collapsible accordion component with single or multiple open items.
+
+**Pattern**: Compound Component
+**Sub-components**: `Content`, `Item`, `Trigger`
+
+### Props
+
+```tsx
+interface OxAccordionProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  defaultValue?: string | string[]; // Default open accordion items
+  onValueChange?: (value: string | string[]) => void;
+  type?: 'single' | 'multiple'; // Single or multiple items can be open
+  value?: string | string[]; // Controlled value
+}
+
+interface OxAccordionItemProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  disabled?: boolean;
+  value: string; // Required - Unique identifier for the item
+}
+
+interface OxAccordionTriggerProps extends ComponentPropsWithRef<'button'> {}
+interface OxAccordionContentProps extends ComponentPropsWithRef<'div'> {}
+```
+
+### Example
+
+```tsx
+<OxAccordion type="multiple" defaultValue={['item-1']}>
+  <OxAccordion.Item value="item-1">
+    <OxAccordion.Trigger>Is it accessible?</OxAccordion.Trigger>
+    <OxAccordion.Content>Yes. It adheres to the WAI-ARIA design pattern.</OxAccordion.Content>
+  </OxAccordion.Item>
+</OxAccordion>
+```
+
+---
+
+## OxAlert
+
+Alert component with different types and compound pattern.
+
+**Pattern**: Compound Component
+**Sub-components**: `Title`, `Description`
+
+### Props
+
+```tsx
+interface OxAlertProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  variant?: 'default' | 'destructive' | 'success' | 'warning' | 'info';
+}
+
+interface OxAlertTitleProps extends ComponentPropsWithRef<'div'> {}
+interface OxAlertDescriptionProps extends ComponentPropsWithRef<'div'> {}
+```
+
+### Example
+
+```tsx
+<OxAlert variant="success">
+  <OxAlert.Title>Success</OxAlert.Title>
+  <OxAlert.Description>Your changes have been saved.</OxAlert.Description>
+</OxAlert>
+```
+
+---
+
+## OxAspectRatio
+
+Container that maintains a specific aspect ratio for its content.
+
+**Pattern**: Compound Component
+**Sub-components**: `Fallback`, `Image`, `Video`
+
+### Props
+
+```tsx
+interface OxAspectRatioProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  children: ReactNode;
+  isLoading?: boolean;
+  ratio: number; // Width/height ratio (e.g., 16/9 = 1.78)
+}
+
+interface OxAspectRatioImageProps {
+  alt: string;
+  className?: string;
+  crossOrigin?: '' | 'anonymous' | 'use-credentials';
+  loading?: 'eager' | 'lazy';
+  objectFit?: 'contain' | 'cover' | 'fill';
+  referrerPolicy?: ReferrerPolicy;
+  src: string;
+}
+
+interface OxAspectRatioVideoProps {
+  alt?: string;
+  autoPlay?: boolean;
+  className?: string;
+  controls?: boolean;
+  crossOrigin?: '' | 'anonymous' | 'use-credentials';
+  loop?: boolean;
+  muted?: boolean;
+  objectFit?: 'contain' | 'cover' | 'fill';
+  playsInline?: boolean;
+  src: string;
+}
+
+interface OxAspectRatioFallbackProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+```
+
+### Usage
+
+```tsx
+<OxAspectRatio ratio={16 / 9}>
+  <OxAspectRatio.Image src="/image.jpg" alt="Example" objectFit="cover" />
+  <OxAspectRatio.Fallback>Loading...</OxAspectRatio.Fallback>
+</OxAspectRatio>
+
+<OxAspectRatio ratio={4 / 3}>
+  <OxAspectRatio.Video src="/video.mp4" controls autoPlay muted />
+</OxAspectRatio>
+```
+
+---
+
+## OxAvatar
+
+Avatar component with status indicators and loading states.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxAvatarProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  alt?: string;
+  fallback?: string | ReactNode; // Shown when image fails to load
+  isLoading?: boolean; // Shows loading state
+  shape?: 'rectangle' | 'circle';
+  showStatus?: boolean; // Display status indicator
+  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+  skeleton?: boolean; // Shows skeleton loader
+  src?: string;
+  status?: 'online' | 'offline' | 'away' | 'busy';
+}
+```
+
+### Example
+
+```tsx
+<OxAvatar
+  src="/avatar.jpg"
+  alt="User Name"
+  size="lg"
+  shape="circle"
+  showStatus
+  status="online"
+  fallback="UN"
+/>
+```
+
+---
+
+## OxBadge
+
+Notification badge for displaying counts or status indicators on UI elements. Designed for use with ghost buttons and icons.
+
+**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.
+
+### Props
+
+```tsx
+interface OxBadgeProps extends ComponentPropsWithRef<'span'> {
+  children?: ReactNode;
+  count?: number;
+  max?: number;
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+  showZero?: boolean;
+  type?: 'dot' | 'count';
+  variant?: ColorStyleName;
+}
+```
+
+### Example
+
+```tsx
+{/* Standalone count badge */}
+<OxBadge count={5} />
+
+{/* Badge on button */}
+<OxBadge count={12} position="top-right">
+  <OxButton variant="ghost" aria-label="Messages">
+    <OxIcon icon={Mail} />
+  </OxButton>
+</OxBadge>
+
+{/* Overflow handling */}
+<OxBadge count={100} max={99} /> {/* Shows "99+" */}
+
+{/* Dot badge for status */}
+<OxBadge type="dot" variant="green" position="top-right">
+  <OxIcon icon={Bell} className="size-6" />
+</OxBadge>
+```
+
+---
+
+## OxTag
+
+Inline label component for categorization and metadata display.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxTagProps extends ComponentPropsWithRef<'span'> {
+  children: ReactNode; // Tag content
+  color?: ColorStyleName; // Predefined theme color
+}
+```
+
+### Example
+
+```tsx
+{/* Basic tags */}
+<OxTag color="blue">New</OxTag>
+<OxTag color="green">Active</OxTag>
+<OxTag color="purple">Featured</OxTag>
+
+{/* In context */}
+<div className="flex gap-2">
+  <OxTag color="purple">React</OxTag>
+  <OxTag color="blue">TypeScript</OxTag>
+  <OxTag color="green">Tailwind</OxTag>
+</div>
+```
+
+---
+
+## OxBreadcrumb
+
+Breadcrumb navigation with asChild pattern support.
+
+**Pattern**: Compound Component
+**Sub-components**: `Ellipsis`, `Item`, `Link`, `Page`, `Separator`
+
+### Props
+
+```tsx
+interface OxBreadcrumbProps extends ComponentPropsWithRef<'ol'> {
+  children: ReactNode;
+}
+
+interface OxBreadcrumbItemProps extends ComponentPropsWithRef<'li'> {
+  children: ReactNode;
+}
+
+interface OxBreadcrumbLinkProps extends ComponentPropsWithRef<'a'> {
+  asChild?: boolean; // Renders as child component (e.g., Next.js Link)
+  children: ReactNode;
+  current?: boolean; // Marks as current page
+  href?: string;
+}
+
+interface OxBreadcrumbPageProps extends ComponentPropsWithRef<'span'> {
+  children: ReactNode;
+}
+
+interface OxBreadcrumbSeparatorProps extends ComponentPropsWithRef<'li'> {}
+interface OxBreadcrumbEllipsisProps extends ComponentPropsWithRef<'span'> {}
+```
+
+### Example
+
+```tsx
+<OxBreadcrumb>
+  <OxBreadcrumb.Item>
+    <OxBreadcrumb.Link href="/">Home</OxBreadcrumb.Link>
+  </OxBreadcrumb.Item>
+  <OxBreadcrumb.Separator />
+  <OxBreadcrumb.Item>
+    <OxBreadcrumb.Link href="/products">Products</OxBreadcrumb.Link>
+  </OxBreadcrumb.Item>
+  <OxBreadcrumb.Separator />
+  <OxBreadcrumb.Item>
+    <OxBreadcrumb.Page>Current Page</OxBreadcrumb.Page>
+  </OxBreadcrumb.Item>
+</OxBreadcrumb>;
+
+{
+  /* Using asChild with Next.js Link */
+}
+<OxBreadcrumb.Link asChild>
+  <Link to="/dashboard">Dashboard</Link>
+</OxBreadcrumb.Link>;
+```
+
+---
+
+## OxButton
+
+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.
+
+### Props
+
+```tsx
+interface OxButtonProps extends ComponentPropsWithRef<'button'> {
+  asChild?: 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';
+  variant?: 'gradient' | 'primary' | 'accent' | 'default' | 'secondary' | 'ghost' | 'danger';
+}
+```
+
+### Example
+
+```tsx
+<OxButton variant="primary" size="md" isLoading>
+  Save Changes
+</OxButton>;
+
+{
+  /* Render as Link while keeping button styling */
+}
+<OxButton asChild variant="primary">
+  <Link to="/dashboard">Dashboard</Link>
+</OxButton>;
+```
+
+---
+
+## OxCalendar
+
+Date picker component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxCalendarProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+  onChange?: (value: string) => void;
+  value?: string; // Date string
+}
+```
+
+### Example
+
+```tsx
+<OxCalendar value="2024-01-15" onChange={(date) => console.log(date)} />
+```
+
+---
+
+## OxCard
+
+Card component with hover effects and loading states.
+
+**Pattern**: Compound Component
+**Sub-components**: `Action`, `Content`, `Footer`, `Header`
+
+### Props
+
+```tsx
+interface OxCardProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  color?: Exclude<ColorStyleName, 'default'>; // Card accent color
+  equalHeight?: boolean; // Makes card take full height
+  hoverable?: boolean; // Enables hover effects
+  hoverVariant?: 'none' | 'lift' | 'border';
+  isLoading?: boolean; // Shows loading state
+  padding?: 'none' | 'sm' | 'md';
+}
+
+interface OxCardContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  flexGrow?: boolean; // Makes content grow to fill space
+}
+
+interface OxCardFooterProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxCardHeaderProps extends ComponentPropsWithRef<'div'> {}
+interface OxCardActionProps extends ComponentPropsWithRef<'div'> {}
+```
+
+### Example
+
+```tsx
+<OxCard hoverable hoverVariant="lift" color="blue" isLoading={false}>
+  <OxCard.Header>Card Title</OxCard.Header>
+  <OxCard.Content flexGrow>Main content here</OxCard.Content>
+  <OxCard.Footer>Footer content</OxCard.Footer>
+  <OxCard.Action>
+    <button>Action</button>
+  </OxCard.Action>
+</OxCard>
+```
+
+---
+
+## OxDescriptionList (beta)
+
+Semantic description list component.
+
+**Pattern**: Compound Component
+**Sub-components**: `Term`, `Value`
+
+### Props
+
+```tsx
+interface OxDescriptionListProps extends ComponentPropsWithRef<'dl'> {
+  children: ReactNode;
+  outline?: boolean; // Adds border outline
+}
+
+interface OxDescriptionListTermProps extends ComponentPropsWithRef<'dt'> {
+  children: ReactNode;
+}
+
+interface OxDescriptionListValueProps extends ComponentPropsWithRef<'dd'> {
+  children?: ReactNode;
+}
+```
+
+### Example
+
+```tsx
+<OxDescriptionList outline>
+  <OxDescriptionList.Term>Name</OxDescriptionList.Term>
+  <OxDescriptionList.Value>John Doe</OxDescriptionList.Value>
+  <OxDescriptionList.Term>Email</OxDescriptionList.Term>
+  <OxDescriptionList.Value>john@example.com</OxDescriptionList.Value>
+</OxDescriptionList>
+```
+
+---
+
+## OxDialog
+
+Modal dialog component.
+
+**Pattern**: Compound Component
+**Sub-components**: `Body`, `Footer`, `Header`
+
+### Props
+
+```tsx
+interface OxDialogProps extends ComponentPropsWithoutRef<'dialog'> {
+  children: ReactNode;
+  closeOnOutsideClick?: boolean; // Closes on backdrop click
+  isOpen: boolean; // Required - Controls visibility
+  onClose: () => void; // Required - Close callback
+  persistent?: boolean; // Prevents closing on outside click/escape
+  showCloseButton?: boolean;
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+}
+
+interface OxDialogHeaderProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDialogBodyProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDialogFooterProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+```
+
+### Example
+
+```tsx
+<OxDialog isOpen={open} onClose={() => setOpen(false)} size="md">
+  <OxDialog.Header>Confirm Action</OxDialog.Header>
+  <OxDialog.Body>Are you sure you want to continue?</OxDialog.Body>
+  <OxDialog.Footer>
+    <OxButton onClick={() => setOpen(false)}>Cancel</OxButton>
+    <OxButton variant="primary">Confirm</OxButton>
+  </OxDialog.Footer>
+</OxDialog>
+```
+
+---
+
+## OxDndContext
+
+Drag and drop context provider using @dnd-kit/core.
+
+**Pattern**: Compound Component (Context-based)
+**Sub-components**: `Draggable`, `Droppable`
+**Additional Exports**: `useDndContext`
+
+### Props
+
+```tsx
+interface DndDragEvent {
+  active: Active; // @dnd-kit Active type
+  over: Over | null; // @dnd-kit Over type
+}
+
+interface OxDndContextProps {
+  children: ReactNode;
+  onDragCancel?: (event: DndDragEvent) => void;
+  onDragEnd?: (event: DndDragEvent) => void;
+  onDragOver?: (event: DndDragEvent) => void;
+  onDragStart?: (event: DndDragEvent) => void;
+}
+
+interface OxDraggableProps extends Omit<ComponentPropsWithRef<'div'>, 'id'> {
+  children: ReactNode;
+  data?: Record<string, unknown>; // Custom data passed to drag events
+  disabled?: boolean;
+  id?: string;
+}
+
+interface OxDroppableProps extends Omit<ComponentPropsWithRef<'div'>, 'id'> {
+  children: ReactNode;
+  data?: Record<string, unknown>; // Custom data for drop zone identification
+  disabled?: boolean;
+  id?: string;
+}
+```
+
+### Usage
+
+```tsx
+<OxDndContext
+  onDragEnd={({ active, over }) => {
+    if (over) {
+      console.log(`Dropped ${active.id} onto ${over.id}`);
+    }
+  }}
+>
+  <OxDndContext.Droppable id="drop-zone">
+    <OxDndContext.Draggable id="item-1">Drag me</OxDndContext.Draggable>
+  </OxDndContext.Droppable>
+</OxDndContext>
+```
+
+**Note**: For simple reordering within a list, prefer `OxSortableList`. Use `OxDndContext` for complex drag-and-drop scenarios across different containers.
+
+---
+
+## OxDrawer
+
+Slide-out drawer component.
+
+**Pattern**: Compound Component
+**Sub-components**: `Body`, `Content`, `Footer`, `Header`, `Trigger`
+
+### Props
+
+```tsx
+interface OxDrawerProps {
+  children: ReactNode;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+}
+
+interface OxDrawerTriggerProps extends ComponentPropsWithRef<'button'> {
+  children: ReactNode;
+  disabled?: boolean;
+}
+
+interface OxDrawerContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  closeOnOutsideClick?: boolean;
+  side?: 'left' | 'right' | 'top' | 'bottom'; // Slide-in direction
+}
+
+interface OxDrawerHeaderProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDrawerBodyProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDrawerFooterProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+```
+
+### Example
+
+```tsx
+<OxDrawer>
+  <OxDrawer.Trigger>Open Drawer</OxDrawer.Trigger>
+  <OxDrawer.Content side="right">
+    <OxDrawer.Header>Drawer Title</OxDrawer.Header>
+    <OxDrawer.Body>Drawer content</OxDrawer.Body>
+    <OxDrawer.Footer>Footer</OxDrawer.Footer>
+  </OxDrawer.Content>
+</OxDrawer>
+```
+
+---
+
+## OxDropdown
+
+Dropdown menu with extensive sub-components.
+
+**Pattern**: Compound Component
+**Sub-components**: `Body`, `Content`, `Footer`, `Header`, `Item`, `Label`, `Separator`, `Shortcut`, `Trigger`
+
+### Props
+
+```tsx
+interface OxDropdownProps {
+  align?: 'start' | 'center' | 'end';
+  children: ReactNode;
+  defaultOpen?: boolean;
+  disabled?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+  side?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+interface OxDropdownTriggerProps extends ComponentPropsWithRef<'button'> {
+  animateIcon?: boolean; // Animates icon on open/close
+  asChild?: boolean; // Renders as child component (useful for custom triggers)
+  children: ReactNode;
+  hideIcon?: boolean;
+  icon?: LucideIcon;
+  size?: OxButtonProps['size'];
+  variant?: OxButtonProps['variant'];
+}
+
+interface OxDropdownContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  className?: string;
+}
+
+interface OxDropdownBodyProps extends ComponentPropsWithRef<'ul'> {
+  children: ReactNode;
+}
+
+// Item can be either button or link
+type OxDropdownItemProps = OxDropdownItemButtonProps | OxDropdownItemLinkProps;
+
+interface OxDropdownItemButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'type'> {
+  disabled?: boolean;
+}
+
+interface OxDropdownItemLinkProps extends ComponentPropsWithRef<'a'> {
+  disabled?: boolean; // Disables link navigation
+  href: string; // Required for link variant
+}
+
+interface OxDropdownLabelProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDropdownShortcutProps extends ComponentPropsWithRef<'span'> {
+  children: ReactNode;
+}
+
+interface OxDropdownHeaderProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDropdownFooterProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxDropdownSeparatorProps extends Omit<OxSeparatorProps, 'orientation' | 'vertical'> {}
+```
+
+### Example
+
+```tsx
+<OxDropdown side="bottom" align="start">
+  <OxDropdown.Trigger>Options</OxDropdown.Trigger>
+  <OxDropdown.Content>
+    <OxDropdown.Header>Actions</OxDropdown.Header>
+    <OxDropdown.Body>
+      <OxDropdown.Item onClick={handleEdit}>
+        Edit <OxDropdown.Shortcut>⌘E</OxDropdown.Shortcut>
+      </OxDropdown.Item>
+      <OxDropdown.Item href="/settings">Settings</OxDropdown.Item>
+      <OxDropdown.Separator />
+      <OxDropdown.Item onClick={handleDelete}>Delete</OxDropdown.Item>
+    </OxDropdown.Body>
+  </OxDropdown.Content>
+</OxDropdown>
+```
+
+---
+
+## OxEndlessList
+
+Virtualized infinite scroll list using @tanstack/react-virtual.
+
+**Pattern**: Compound Component
+**Sub-components**: `Empty`, `Error`, `Item`, `Items`, `Loader`
+
+### Props
+
+```tsx
+interface OxEndlessListProps<TData> extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  children: ReactNode;
+  data: TData[];
+  estimateSize: number | ((index: number) => number); // Estimated row height in pixels
+  gap?: number;
+  getItemKey: (item: TData, index: number) => string | number;
+  hasNextPage?: boolean;
+  isError?: boolean;
+  isLoading?: boolean;
+  loadMoreThreshold?: number; // Distance from bottom to trigger load (px)
+  onLoadMore?: () => void;
+  overscan?: number; // Number of items to render outside visible area
+}
+
+interface OxEndlessListItemsProps {
+  children: ReactNode;
+  className?: string;
+  paddingY?: number;
+}
+
+interface OxEndlessListItemProps<TData = unknown> {
+  children: (item: TData, index: number) => ReactNode; // Render function
+  className?: string;
+}
+
+interface OxEndlessListLoaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  children?: ReactNode;
+}
+
+interface OxEndlessListEmptyProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  children?: ReactNode;
+}
+
+interface OxEndlessListErrorProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  children?: ReactNode;
+}
+```
+
+### Usage
+
+```tsx
+<OxEndlessList
+  data={items}
+  estimateSize={50}
+  getItemKey={(item) => item.id}
+  hasNextPage={hasMore}
+  isLoading={isLoading}
+  onLoadMore={fetchMore}
+>
+  <OxEndlessList.Items>
+    <OxEndlessList.Item>{(item, index) => <div>{item.name}</div>}</OxEndlessList.Item>
+  </OxEndlessList.Items>
+  <OxEndlessList.Loader>Loading more...</OxEndlessList.Loader>
+  <OxEndlessList.Empty>No items found</OxEndlessList.Empty>
+  <OxEndlessList.Error>Failed to load</OxEndlessList.Error>
+</OxEndlessList>
+```
+
+---
+
+## OxFloating ⚠️ DEPRECATED
+
+> **Deprecated**: Moved to `@noxickon/onyx/legacy`. Use `OxPopper` or higher-level components (OxPopover, OxDropdown, OxTooltip) instead.
+
+Low-level floating UI primitive.
+
+**Import**: `import { OxFloating } from '@noxickon/onyx/legacy';`
+**Pattern**: Compound Component (Primitive)
+**Sub-components**: `Content`, `Trigger`
+**Additional Exports**: `OxFloatingContext`, `useOxFloatingContext`
+
+### Props
+
+```tsx
+interface OxFloatingProps {
+  align?: 'start' | 'center' | 'end';
+  animationDuration?: number; // Animation duration in ms
+  ariaHaspopup?: 'menu' | 'dialog' | 'listbox' | 'tree' | 'grid' | true;
+  children: ReactNode;
+  defaultOpen?: boolean;
+  disabled?: boolean;
+  hoverDelay?: number; // Delay before showing on hover (ms)
+  id?: string;
+  offset?: number; // Distance from trigger element
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  trigger?: 'hover' | 'click' | 'manual' | 'focus'; // Interaction type
+  useAriaControls?: boolean;
+}
+
+interface OxFloatingTriggerProps extends ComponentPropsWithRef<'div'> {
+  asChild?: boolean; // Renders as child component
+  children: ReactNode;
+}
+
+interface OxFloatingContentProps extends ComponentPropsWithoutRef<'div'> {
+  children: ReactNode;
+  portal?: boolean; // Renders in portal
+}
+```
+
+**Note**: Base component for Popover, Dropdown, and Tooltip. Use higher-level components instead when possible.
+
+---
+
+## OxHoverCard
+
+Card that appears on hover with configurable delays.
+
+**Pattern**: Compound Component
+**Sub-components**: `Content`, `Trigger`
+
+### Props
+
+```tsx
+type OxPopperSide = 'top' | 'right' | 'bottom' | 'left';
+type OxPopperAlign = 'start' | 'center' | 'end';
+
+interface OxHoverCardProps {
+  align?: OxPopperAlign;
+  children: ReactNode;
+  closeDelay?: number; // Delay before closing (ms)
+  defaultOpen?: boolean;
+  disabled?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+  openDelay?: number; // Delay before opening (ms)
+  side?: OxPopperSide;
+}
+
+interface OxHoverCardTriggerProps extends ComponentPropsWithoutRef<'div'> {
+  asChild?: boolean;
+  children: ReactNode;
+}
+
+interface OxHoverCardContentProps extends ComponentPropsWithoutRef<'div'> {
+  children: ReactNode;
+  forceMount?: boolean; // Keep mounted when closed
+}
+```
+
+### Usage
+
+```tsx
+<OxHoverCard openDelay={200} closeDelay={100}>
+  <OxHoverCard.Trigger asChild>
+    <OxButton>Hover me</OxButton>
+  </OxHoverCard.Trigger>
+  <OxHoverCard.Content>
+    <p>Additional information appears here</p>
+  </OxHoverCard.Content>
+</OxHoverCard>
+```
+
+---
+
+## OxIcon
+
+Icon component with Lucide icon support.
+
+**Pattern**: Compound Component
+**Sub-components**: `Box`
+
+### Props
+
+```tsx
+interface OxIconProps {
+  children?: React.ReactNode;
+  className?: string;
+  icon?: LucideIcon; // Lucide icon component
+  path?: string; // SVG path for custom icon
+  placeholder?: boolean; // Shows placeholder icon
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | number;
+}
+
+interface OxIconBoxProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+  children: ReactNode;
+  color?: ColorStyleName; // Background color
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+}
+```
+
+### Example
+
+```tsx
+import { Check } from 'lucide-react';
+
+<OxIcon icon={Check} size="lg" />
+<OxIcon path="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" />
+
+<OxIcon.Box color="blue" size="lg">
+  <OxIcon icon={Check} />
+</OxIcon.Box>
+```
+
+---
+
+## OxJsonField (alpha)
+
+JSON data display with syntax highlighting.
+
+**Pattern**: Compound Component
+**Sub-components**: `Node`
+
+### Props
+
+```tsx
+type OxJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | OxJsonValue[]
+  | { [key: string]: OxJsonValue };
+
+interface OxJsonFieldProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  value: string | OxJsonValue; // Required - JSON to display
+}
+
+interface OxJsonNodeProps {
+  data: OxJsonValue;
+  level: number; // Nesting level for indentation
+  trailingComma?: boolean;
+}
+```
+
+### Example
+
+```tsx
+<OxJsonField value={{ name: "John", age: 30, active: true }} />
+<OxJsonField value='{"key": "value"}' />
+```
+
+---
+
+## OxKanban
+
+Kanban board for drag-and-drop card management across columns.
+
+**Pattern**: Compound Component
+**Sub-components**: `Card`, `Card.Handle`, `Column`, `Column.Footer`, `Column.Header`
+
+### Props
+
+```tsx
+interface OxKanbanProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  columnGap?: number;
+  disabled?: boolean;
+  onMove: (cardId: string, fromColumn: string, toColumn: string, newIndex: number) => void;
+  onReorder?: (cardId: string, column: string, fromIndex: number, toIndex: number) => void;
+}
+
+interface OxKanbanColumnProps extends ComponentPropsWithRef<'div'> {
+  children?: ReactNode;
+  disabled?: boolean;
+  emptyState?: ReactNode; // Shown when column has no cards
+  gap?: number;
+  heading?: ReactNode;
+  id: string; // Unique column identifier
+}
+
+interface OxKanbanColumnHeaderProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxKanbanColumnFooterProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxKanbanCardProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  disabled?: boolean;
+  id: string; // Unique card identifier
+}
+
+interface OxKanbanCardHandleProps extends ComponentPropsWithRef<'button'> {
+  children?: ReactNode;
+}
+```
+
+### Usage
+
+```tsx
+<OxKanban
+  onMove={(cardId, from, to, index) => moveCard(cardId, from, to, index)}
+  onReorder={(cardId, column, from, to) => reorderCard(cardId, column, from, to)}
+>
+  <OxKanban.Column id="todo">
+    <OxKanban.Column.Header>To Do</OxKanban.Column.Header>
+    <OxKanban.Card id="task-1">
+      <OxKanban.Card.Handle />
+      <span>Task 1</span>
+    </OxKanban.Card>
+    <OxKanban.Column.Footer>
+      <OxButton>Add task</OxButton>
+    </OxKanban.Column.Footer>
+  </OxKanban.Column>
+  <OxKanban.Column id="done" emptyState="No completed tasks">
+    <OxKanban.Column.Header>Done</OxKanban.Column.Header>
+  </OxKanban.Column>
+</OxKanban>
+```
+
+---
+
+## OxLink
+
+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.
+
+### Props
+
+```tsx
+interface OxLinkProps extends ComponentPropsWithRef<'a'> {
+  asChild?: 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
+}
+```
+
+### Example
+
+```tsx
+<OxLink href="/about" variant="primary">
+  About Us
+</OxLink>;
+
+{
+  /* Use with React Router */
+}
+<OxLink asChild>
+  <Link to="/dashboard">Dashboard</Link>
+</OxLink>;
+```
+
+---
+
+## OxMasonry
+
+Responsive masonry layout with configurable columns.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+type Breakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+type ResponsiveColumns = {
+  default: number;
+} & Partial<Record<Breakpoint, number>>;
+
+interface OxMasonryProps {
+  children: ReactNode;
+  className?: string;
+  columns: number | ResponsiveColumns; // Fixed columns or responsive breakpoints
+  gap?: number;
+}
+```
+
+### Usage
+
+```tsx
+// Fixed columns
+<OxMasonry columns={3} gap={16}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</OxMasonry>
+
+// Responsive columns
+<OxMasonry
+  columns={{ default: 1, sm: 2, md: 3, lg: 4 }}
+  gap={24}
+>
+  {items.map(item => <Card key={item.id}>{item.content}</Card>)}
+</OxMasonry>
+```
+
+---
+
+## OxNotifications
+
+Notification center component.
+
+**Pattern**: Compound Component
+**Sub-components**: `Body`, `Button`, `Link`, `Trigger`
+
+### Props
+
+```tsx
+interface OxNotificationItemProps {
+  icon?: LucideIcon;
+  id: string; // Required - Unique ID
+  img?: string;
+  message?: string;
+  path?: string; // SVG path
+  read: boolean; // Required
+  timestamp: Date; // Required
+  title: string; // Required
+  type?: 'default' | 'info' | 'success' | 'warning' | 'error';
+}
+
+interface OxNotificationsProps extends ComponentPropsWithRef<'div'> {
+  children?: ReactNode;
+  disabled?: boolean;
+  emptyMessage?: string;
+  items?: OxNotificationItemProps[];
+  onItemClick?: (item: OxNotificationItemProps) => void;
+  onMarkAllRead?: () => void;
+  unreadCount?: number;
+}
+
+interface OxNotificationsTriggerProps extends ComponentPropsWithRef<'button'> {
+  children?: ReactNode;
+  customIcon?: LucideIcon;
+  unreadCount?: number; // Badge count
+}
+
+interface OxNotificationsBodyProps extends ComponentPropsWithRef<'ul'> {
+  children?: ReactNode;
+}
+
+interface OxNotificationsButtonProps extends Omit<
+  ComponentPropsWithRef<'button'>,
+  'children' | 'type' | 'onClick'
+> {
+  children?: ReactNode;
+  icon?: LucideIcon;
+  img?: string;
+  message?: string;
+  path?: string;
+  timestamp?: Date;
+  title?: string;
+  type?: 'default' | 'info' | 'success' | 'warning' | 'error';
+  unread?: boolean;
+}
+
+interface OxNotificationsLinkProps extends Omit<
+  ComponentPropsWithRef<'a'>,
+  'children' | 'type' | 'onClick'
+> {
+  children?: ReactNode;
+  href: string; // Required
+  icon?: LucideIcon;
+  img?: string;
+  message?: string;
+  path?: string;
+  timestamp?: Date;
+  title?: string;
+  type?: 'default' | 'info' | 'success' | 'warning' | 'error';
+  unread?: boolean;
+}
+```
+
+### Example
+
+```tsx
+<OxNotifications
+  items={notifications}
+  unreadCount={5}
+  onItemClick={(item) => console.log(item)}
+  onMarkAllRead={() => console.log('Mark all read')}
+>
+  <OxNotifications.Trigger unreadCount={5} />
+  <OxNotifications.Body>
+    <OxNotifications.Button title="New message" message="You have a new message" />
+    <OxNotifications.Link href="/notifications" title="View all" />
+  </OxNotifications.Body>
+</OxNotifications>
+```
+
+---
+
+## OxPageOutline
+
+Table of contents / page outline component with scroll spy.
+
+**Pattern**: Compound Component
+**Sub-components**: `Content`, `Header`, `Item`
+
+### Props
+
+```tsx
+type OxPageOutlineLevel = 1 | 2 | 3;
+
+interface OxPageOutlineProps extends ComponentPropsWithRef<'nav'> {
+  children: ReactNode;
+  scrollOffset?: number; // Offset for scroll position detection (px)
+}
+
+interface OxPageOutlineHeaderProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxPageOutlineContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxPageOutlineItemProps extends ComponentPropsWithRef<'a'> {
+  children: ReactNode;
+  href: string; // Anchor link (e.g., "#section-1")
+  level?: OxPageOutlineLevel; // Indentation level (1-3)
+}
+```
+
+### Usage
+
+```tsx
+<OxPageOutline scrollOffset={80}>
+  <OxPageOutline.Header>On this page</OxPageOutline.Header>
+  <OxPageOutline.Content>
+    <OxPageOutline.Item href="#introduction" level={1}>
+      Introduction
+    </OxPageOutline.Item>
+    <OxPageOutline.Item href="#getting-started" level={1}>
+      Getting Started
+    </OxPageOutline.Item>
+    <OxPageOutline.Item href="#installation" level={2}>
+      Installation
+    </OxPageOutline.Item>
+    <OxPageOutline.Item href="#configuration" level={2}>
+      Configuration
+    </OxPageOutline.Item>
+    <OxPageOutline.Item href="#api" level={1}>
+      API Reference
+    </OxPageOutline.Item>
+  </OxPageOutline.Content>
+</OxPageOutline>
+```
+
+---
+
+## OxPagination
+
+Pagination component with routing support.
+
+**Pattern**: Compound Component
+**Sub-components**: `Ellipsis`, `Item`, `Link`, `Next`, `Previous`
+
+### Props
+
+```tsx
+interface OxPaginationProps extends ComponentPropsWithRef<'nav'> {
+  children: ReactNode;
+}
+
+interface OxPaginationItemProps extends ComponentPropsWithRef<'li'> {
+  children: ReactNode;
+}
+
+interface OxPaginationLinkProps extends ComponentPropsWithRef<'a'> {
+  asChild?: boolean; // Renders as child component (for routing libraries)
+  children: ReactNode;
+  disabled?: boolean;
+  href?: string;
+  isActive?: boolean; // Marks as active page
+}
+
+interface OxPaginationPreviousProps extends ComponentPropsWithRef<'a'> {
+  asChild?: boolean; // Renders as child component
+  children?: ReactNode;
+  disabled?: boolean;
+  href?: string;
+}
+
+interface OxPaginationNextProps extends ComponentPropsWithRef<'a'> {
+  asChild?: boolean; // Renders as child component
+  children?: ReactNode;
+  disabled?: boolean;
+  href?: string;
+}
+
+interface OxPaginationEllipsisProps extends ComponentPropsWithRef<'span'> {}
+```
+
+### Example
+
+```tsx
+<OxPagination>
+  <OxPagination.Item>
+    <OxPagination.Previous href="?page=1" />
+  </OxPagination.Item>
+  <OxPagination.Item>
+    <OxPagination.Link href="?page=1">1</OxPagination.Link>
+  </OxPagination.Item>
+  <OxPagination.Item>
+    <OxPagination.Link href="?page=2" isActive>
+      2
+    </OxPagination.Link>
+  </OxPagination.Item>
+  <OxPagination.Item>
+    <OxPagination.Ellipsis />
+  </OxPagination.Item>
+  <OxPagination.Item>
+    <OxPagination.Next href="?page=3" />
+  </OxPagination.Item>
+</OxPagination>
+```
+
+---
+
+## OxPopover
+
+Popover component built on Floating.
+
+**Pattern**: Compound Component
+**Sub-components**: `Content`, `Trigger`
+
+### Props
+
+```tsx
+interface OxPopoverProps extends ComponentPropsWithRef<'div'> {
+  align?: 'start' | 'center' | 'end';
+  children: React.ReactNode;
+  defaultOpen?: boolean;
+  disabled?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+  side?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+interface OxPopoverTriggerProps extends ComponentPropsWithRef<'button'> {
+  asChild?: boolean; // Renders as child component
+  children: React.ReactNode;
+}
+
+interface OxPopoverContentProps extends ComponentPropsWithRef<'div'> {
+  children: React.ReactNode;
+  showCloseButton?: boolean;
+}
+```
+
+### Example
+
+```tsx
+<OxPopover side="bottom">
+  <OxPopover.Trigger>Click me</OxPopover.Trigger>
+  <OxPopover.Content showCloseButton>Popover content here</OxPopover.Content>
+</OxPopover>
+```
+
+---
+
+## OxPopper
+
+Low-level positioning primitive for floating elements. Built on @floating-ui/react.
+
+**Pattern**: Compound Component (Primitive)
+**Sub-components**: `Anchor`, `Arrow`, `Content`
+**Additional Exports**: `usePopperState`, `usePopperContext`, `usePopperContentContext`
+
+### Props
+
+```tsx
+type OxPopperSide = 'top' | 'right' | 'bottom' | 'left';
+type OxPopperAlign = 'start' | 'center' | 'end';
+type OxPopperSticky = 'partial' | 'always';
+
+interface OxPopperProps {
+  children: ReactNode;
+}
+
+interface OxPopperAnchorProps extends ComponentPropsWithoutRef<'div'> {
+  asChild?: boolean;
+  children?: ReactNode;
+  virtualRef?: RefObject<Measurable | null>; // For virtual anchor positioning
+}
+
+interface OxPopperContentProps extends ComponentPropsWithoutRef<'div'> {
+  align?: OxPopperAlign;
+  alignOffset?: number;
+  arrowPadding?: number;
+  avoidCollisions?: boolean;
+  children: ReactNode;
+  collisionPadding?: number;
+  hideWhenDetached?: boolean; // Hide when anchor is out of view
+  onPlaced?: () => void;
+  side?: OxPopperSide;
+  sideOffset?: number;
+  sticky?: OxPopperSticky; // How content sticks to viewport edges
+}
+```
+
+### Usage
+
+```tsx
+<OxPopper>
+  <OxPopper.Anchor asChild>
+    <button>Anchor element</button>
+  </OxPopper.Anchor>
+  <OxPopper.Content side="bottom" align="start" sideOffset={8}>
+    <OxPopper.Arrow />
+    <div>Positioned content</div>
+  </OxPopper.Content>
+</OxPopper>
+```
+
+**Note**: This is a low-level primitive. Prefer `OxPopover`, `OxDropdown`, or `OxTooltip` for common use cases.
+
+---
+
+## OxProgress
+
+Progress bar component with linear and circular variants.
+
+**Pattern**: Compound Component
+**Sub-components**: `Circular`
+
+### Props
+
+```tsx
+interface OxProgressProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  buffer?: number; // Buffer value for buffering state
+  max?: number;
+  value?: number;
+}
+
+interface OxProgressCircularProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  max?: number;
+  showPercentage?: boolean; // Shows percentage text in center
+  value?: number;
+}
+```
+
+### Example
+
+```tsx
+<OxProgress value={60} max={100} />
+<OxProgress value={30} buffer={60} max={100} />
+
+<OxProgress.Circular value={75} max={100} showPercentage />
+```
+
+---
+
+## OxSeparator
+
+Divider component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxSeparatorProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  decorative?: boolean; // Marks as decorative (aria-hidden)
+  orientation?: 'horizontal' | 'vertical';
+}
+```
+
+### Example
+
+```tsx
+<OxSeparator orientation="horizontal" />
+<OxSeparator orientation="vertical" decorative />
+```
+
+---
+
+## OxSkeleton
+
+Loading skeleton placeholder.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxSkeletonProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  animate?: boolean; // Enables pulse animation
+  shape?: 'rectangle' | 'circle';
+}
+```
+
+### Example
+
+```tsx
+<OxSkeleton animate shape="rectangle" />
+<OxSkeleton shape="circle" />
+```
+
+---
+
+## OxSlider
+
+Slider component with range support.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxSliderProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'onChange' | 'defaultValue' | 'children'
+> {
+  defaultValue?: number | [number, number]; // Single value or range
+  disabled?: boolean;
+  marks?: boolean | number[]; // Shows marks at positions
+  max?: number;
+  min?: number;
+  onChange?: (value: number | [number, number]) => void;
+  onChangeCommitted?: (value: number | [number, number]) => void; // Called when user releases
+  orientation?: 'horizontal' | 'vertical';
+  showValue?: boolean; // Shows current value
+  step?: number;
+  value?: number | [number, number]; // Controlled value
+}
+```
+
+### Example
+
+```tsx
+{
+  /* Single value slider */
+}
+<OxSlider min={0} max={100} value={50} onChange={setValue} />;
+
+{
+  /* Range slider */
+}
+<OxSlider value={[20, 80]} onChange={setRange} />;
+
+{
+  /* With marks */
+}
+<OxSlider marks={[0, 25, 50, 75, 100]} showValue />;
+```
+
+---
+
+## OxSortableList
+
+Sortable list with drag-and-drop reordering. Built on @dnd-kit.
+
+**Pattern**: Compound Component
+**Sub-components**: `Handle`, `Item`
+
+### Props
+
+```tsx
+type OxSortableListDirection = 'vertical' | 'horizontal' | 'grid';
+
+interface OxSortableListProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  columns?: number; // For grid direction
+  direction?: OxSortableListDirection;
+  disabled?: boolean;
+  gap?: number;
+  onReorder: (fromIndex: number, toIndex: number) => void;
+}
+
+interface OxSortableListItemProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  disabled?: boolean;
+}
+
+interface OxSortableListHandleProps extends ComponentPropsWithRef<'button'> {
+  children?: ReactNode;
+}
+```
+
+### Usage
+
+```tsx
+const [items, setItems] = useState(['Item 1', 'Item 2', 'Item 3']);
+
+const handleReorder = (from: number, to: number) => {
+  const newItems = [...items];
+  const [moved] = newItems.splice(from, 1);
+  newItems.splice(to, 0, moved);
+  setItems(newItems);
+};
+
+<OxSortableList direction="vertical" gap={8} onReorder={handleReorder}>
+  {items.map((item, index) => (
+    <OxSortableList.Item key={item}>
+      <OxSortableList.Handle />
+      <span>{item}</span>
+    </OxSortableList.Item>
+  ))}
+</OxSortableList>
+
+// Grid layout
+<OxSortableList direction="grid" columns={3} gap={16} onReorder={handleReorder}>
+  {items.map(item => (
+    <OxSortableList.Item key={item}>{item}</OxSortableList.Item>
+  ))}
+</OxSortableList>
+```
+
+---
+
+## OxSpinner
+
+Loading spinner.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxSpinnerProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | number;
+}
+```
+
+### Example
+
+```tsx
+<OxSpinner size="lg" />
+<OxSpinner size={48} />
+```
+
+---
+
+## OxStatusDisplay (beta)
+
+Status display for errors and states.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+type OxStatusType =
+  | 'loading'
+  | 'empty'
+  | 'offline'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 401
+  | 403
+  | 404
+  | 408
+  | 429
+  | 500
+  | 502
+  | 503
+  | 504; // HTTP status codes
+
+interface OxStatusDisplayProps extends ComponentPropsWithRef<'div'> {
+  action?: ReactNode; // Custom action element
+  inline?: boolean;
+  message?: string;
+  onBack?: () => void; // Back button callback
+  title?: string;
+  type: OxStatusType; // Required
+}
+```
+
+### Example
+
+```tsx
+<OxStatusDisplay type={404} title="Page Not Found" message="The page you're looking for doesn't exist." />
+<OxStatusDisplay type="loading" />
+<OxStatusDisplay type={500} onBack={() => navigate(-1)} />
+```
+
+---
+
+## OxStepper (experimental)
+
+Multi-step navigation component.
+
+**Pattern**: Compound Component
+**Sub-components**: `Actions`, `Item`
+
+### Props
+
+```tsx
+interface OxStepperProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  color?: ColorStyleName;
+  currentStep?: number; // Current active step index
+  onStepChange?: (step: number) => void;
+  orientation?: 'horizontal' | 'vertical';
+  type?: 'linear' | 'non-linear'; // Linear or non-linear navigation
+}
+
+interface OxStepperItemProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  description?: string;
+  icon?: LucideIcon;
+  state?: 'completed' | 'current' | 'upcoming' | 'error' | 'warning';
+  stepIndex?: number; // Auto-assigned
+  title: string; // Required
+}
+
+interface OxStepperActionsProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+```
+
+### Example
+
+```tsx
+<OxStepper currentStep={1} type="linear" orientation="horizontal">
+  <OxStepper.Item title="Account" description="Create account" state="completed" />
+  <OxStepper.Item title="Profile" description="Add profile" state="current" />
+  <OxStepper.Item title="Finish" description="Complete setup" state="upcoming" />
+  <OxStepper.Actions>
+    <OxButton>Previous</OxButton>
+    <OxButton variant="primary">Next</OxButton>
+  </OxStepper.Actions>
+</OxStepper>
+```
+
+---
+
+## OxTable
+
+Table component with selection and loading states.
+
+**Pattern**: Compound Component
+**Sub-components**: `Body`, `Cell`, `Controls`, `Footer`, `Head`, `Header`, `Row`, `SkeletonRow`
+
+### Props
+
+```tsx
+interface OxTableProps extends ComponentPropsWithRef<'table'> {
+  allRowIds?: string[]; // All row IDs for selection
+  children: ReactNode;
+  draggable?: boolean; // Enables row reordering via drag and drop
+  isLoading?: boolean; // Shows loading skeleton
+  onRowReorder?: (newOrder: string[]) => void; // Callback when rows are reordered
+  onSelectionChange?: (selectedRows: string[]) => void;
+  selectable?: boolean; // Enables row selection with checkboxes
+  selectedRows?: string[];
+  skeletonColumns?: number;
+  skeletonRows?: number;
+}
+
+interface OxTableCellProps extends ComponentPropsWithoutRef<'td'> {
+  children?: ReactNode;
+}
+
+interface OxTableHeadProps extends ComponentPropsWithRef<'th'> {
+  children?: ReactNode;
+}
+
+interface OxTableRowProps extends ComponentPropsWithRef<'tr'> {
+  children: ReactNode;
+  rowId?: string; // Required for selection
+}
+
+interface OxTableBodyProps extends ComponentPropsWithRef<'tbody'> {
+  children: ReactNode;
+}
+
+interface OxTableFooterProps extends ComponentPropsWithRef<'tfoot'> {
+  children: ReactNode;
+}
+
+interface OxTableControlsProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxTableHeaderProps extends ComponentPropsWithRef<'thead'> {
+  children: ReactNode;
+}
+```
+
+### Example
+
+```tsx
+<OxTable selectable selectedRows={selected} onSelectionChange={setSelected}>
+  <OxTable.Header>
+    <OxTable.Row>
+      <OxTable.Head>Name</OxTable.Head>
+      <OxTable.Head>Email</OxTable.Head>
+    </OxTable.Row>
+  </OxTable.Header>
+  <OxTable.Body>
+    <OxTable.Row rowId="1">
+      <OxTable.Cell>John Doe</OxTable.Cell>
+      <OxTable.Cell>john@example.com</OxTable.Cell>
+    </OxTable.Row>
+  </OxTable.Body>
+</OxTable>
+```
+
+---
+
+## OxTabs
+
+Tabs component with bordered and pills variants.
+
+**Pattern**: Compound Component
+**Sub-components**: `Content`, `List`, `Trigger`
+
+### Props
+
+```tsx
+interface OxTabsProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  value?: string; // Controlled active tab
+  variant?: 'bordered' | 'pills';
+}
+
+interface OxTabsListProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxTabsTriggerProps extends ComponentPropsWithRef<'button'> {
+  children: ReactNode;
+  value: string; // Required - Tab identifier
+}
+
+interface OxTabsContentProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  value: string; // Required - Tab identifier
+}
+```
+
+### Example
+
+```tsx
+<OxTabs defaultValue="account" variant="bordered">
+  <OxTabs.List>
+    <OxTabs.Trigger value="account">Account</OxTabs.Trigger>
+    <OxTabs.Trigger value="password">Password</OxTabs.Trigger>
+  </OxTabs.List>
+  <OxTabs.Content value="account">Account settings</OxTabs.Content>
+  <OxTabs.Content value="password">Password settings</OxTabs.Content>
+</OxTabs>
+```
+
+---
+
+## OxTimeline (alpha)
+
+Timeline component.
+
+**Pattern**: Compound Component
+**Sub-components**: `Item`
+
+### Props
+
+```tsx
+interface OxTimelineProps extends ComponentPropsWithRef<'ol'> {
+  children: ReactNode;
+}
+
+interface OxTimelineItemProps extends ComponentPropsWithRef<'li'> {
+  align?: 'left' | 'right';
+  color?: ColorStyleName;
+  description?: string;
+  icon?: LucideIcon;
+  label: string; // Required
+  showSeparator?: boolean; // Shows connecting line
+  timestamp?: string;
+}
+```
+
+### Example
+
+```tsx
+<OxTimeline>
+  <OxTimeline.Item
+    label="Created"
+    description="Project initialized"
+    timestamp="2024-01-01"
+    color="blue"
+  />
+  <OxTimeline.Item
+    label="Updated"
+    description="Files modified"
+    timestamp="2024-01-15"
+    color="green"
+  />
+</OxTimeline>
+```
+
+---
+
+## OxToast (beta)
+
+Toast notification system.
+
+**Pattern**: Context-based Component
+**Additional Exports**: `OxToastProvider`, `useOxToast`
+
+### Props
+
+```tsx
+interface OxToastData {
+  color?: ColorStyleName;
+  customContent?: ReactNode;
+  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
+}
+
+interface OxToastProps {
+  align: 'left' | 'center' | 'right'; // Required
+  onRemove: (id: string) => void; // Required
+  position: 'top' | 'bottom'; // Required
+  toasts: OxToastData[]; // Required
+}
+```
+
+### Hook
+
+```tsx
+const { showToast } = useOxToast();
+
+showToast({
+  title: 'Success!',
+  description: 'Your changes have been saved.',
+  type: 'success',
+  duration: 5000,
+});
+```
+
+### Example
+
+```tsx
+// Wrap app
+<OxToastProvider>
+  <App />
+</OxToastProvider>;
+
+// Use in component
+function MyComponent() {
+  const { showToast } = useOxToast();
+
+  return <button onClick={() => showToast({ title: 'Hello', type: 'info' })}>Show Toast</button>;
+}
+```
+
+---
+
+## OxToggle
+
+Toggle button component with groups.
+
+**Pattern**: Compound Component
+**Sub-components**: `Group`
+
+### Props
+
+```tsx
+interface OxToggleProps extends Omit<ComponentPropsWithRef<'button'>, 'onChange'> {
+  children?: ReactNode;
+  onPressedChange?: (pressed: boolean) => void;
+  pressed?: boolean; // Controlled pressed state
+  size?: 'sm' | 'md' | 'lg';
+  value?: string; // For use in groups
+}
+
+interface OxToggleGroupSingleProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+  children: ReactNode;
+  disabled?: boolean;
+  name?: string;
+  onValueChange?: (value: string) => void;
+  size?: 'sm' | 'md' | 'lg';
+  type?: 'single'; // Single selection
+  value?: string; // Controlled selected value
+}
+
+interface OxToggleGroupMultipleProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+  children: ReactNode;
+  disabled?: boolean;
+  name?: string;
+  onValueChange?: (value: string[]) => void;
+  size?: 'sm' | 'md' | 'lg';
+  type: 'multiple'; // Required - Multiple selection
+  value?: string[]; // Controlled selected values
+}
+```
+
+### Example
+
+```tsx
+{
+  /* Single toggle */
+}
+<OxToggle pressed={bold} onPressedChange={setBold}>
+  Bold
+</OxToggle>;
+
+{
+  /* Toggle group - single selection */
+}
+<OxToggle.Group type="single" value={alignment} onValueChange={setAlignment}>
+  <OxToggle value="left">Left</OxToggle>
+  <OxToggle value="center">Center</OxToggle>
+  <OxToggle value="right">Right</OxToggle>
+</OxToggle.Group>;
+
+{
+  /* Toggle group - multiple selection */
+}
+<OxToggle.Group type="multiple" value={formats} onValueChange={setFormats}>
+  <OxToggle value="bold">Bold</OxToggle>
+  <OxToggle value="italic">Italic</OxToggle>
+  <OxToggle value="underline">Underline</OxToggle>
+</OxToggle.Group>;
+```
+
+---
+
+## OxTooltip
+
+Tooltip component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxTooltipProps {
+  align?: 'start' | 'center' | 'end';
+  children: ReactNode; // Required - Trigger element
+  className?: string;
+  content: ReactNode; // Required - Tooltip content
+  disabled?: boolean;
+  hoverDelay?: number; // Delay before showing (ms)
+  interactive?: boolean; // Keep tooltip open when hovering over it
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  trigger?: 'hover' | 'click' | 'focus';
+}
+```
+
+### Example
+
+```tsx
+<OxTooltip content="Click to save" position="top">
+  <button>Save</button>
+</OxTooltip>
+
+<OxTooltip content="Error occurred" position="bottom">
+  <OxIcon icon={AlertCircle} />
+</OxTooltip>
+```
+
+---
+
+# Form Components (8)
+
+## OxCheckbox
+
+Checkbox component with group support.
+
+**Pattern**: Compound Component
+**Sub-components**: `Group`, `GroupItem`
+
+### Props
+
+```tsx
+type OxCheckedState = boolean | 'indeterminate';
+
+interface OxCheckboxProps extends Omit<
+  ComponentPropsWithoutRef<'input'>,
+  'type' | 'value' | 'children' | 'checked' | 'size' | 'defaultChecked'
+> {
+  checked?: OxCheckedState; // Can be boolean or 'indeterminate'
+  defaultChecked?: OxCheckedState;
+  error?: boolean; // Error state styling
+  onCheckedChange?: (checked: OxCheckedState) => void;
+  value?: string;
+}
+
+interface OxCheckboxGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+  children: ReactNode;
+  disabled?: boolean; // Disables all checkboxes in group
+  name: string; // Required
+  onChange?: (value: (string | number)[]) => void;
+  value?: (string | number)[]; // Controlled selected values
+}
+
+interface OxCheckboxGroupItemProps extends Omit<
+  ComponentPropsWithoutRef<'input'>,
+  'type' | 'size' | 'children' | 'checked' | 'defaultChecked' | 'value'
+> {
+  error?: boolean;
+  value: string | number; // Required
+}
+```
+
+### Example
+
+```tsx
+{
+  /* Single checkbox */
+}
+<OxCheckbox checked={agreed} onCheckedChange={setAgreed} />;
+
+{
+  /* Indeterminate state */
+}
+<OxCheckbox checked="indeterminate" />;
+
+{
+  /* Checkbox group */
+}
+<OxCheckbox.Group name="features" value={selected} onChange={setSelected}>
+  <OxCheckbox.GroupItem value="feature1" />
+  <OxCheckbox.GroupItem value="feature2" />
+</OxCheckbox.Group>;
+```
+
+---
+
+## OxFileUpload (experimental)
+
+File upload component with drag-and-drop.
+
+**Pattern**: Compound Component
+**Sub-components**: `Area`, `Button`, `Overlay`
+
+### Props
+
+```tsx
+interface OxFileUploadProps extends Omit<ComponentPropsWithRef<'div'>, 'onError'> {
+  accept?: string[]; // Allowed file types (e.g., ['.jpg', '.png', 'image/*'])
+  children: ReactNode; // Required
+  disabled?: boolean;
+  maxFiles?: number; // Maximum number of files
+  maxSize?: string; // Max file size (e.g., '5MB', '1GB')
+  minSize?: string; // Min file size
+  multiple?: boolean; // Allow multiple files
+  onError?: (error: string) => void; // Validation error callback
+  onFileSelect?: (files: File[]) => void; // Files selected callback
+}
+
+interface OxFileUploadAreaProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+
+interface OxFileUploadButtonProps extends ComponentPropsWithRef<'button'> {
+  children: ReactNode;
+  size?: 'sm' | 'md';
+  variant?: 'primary' | 'secondary' | 'ghost' | 'link' | 'danger';
+}
+
+interface OxFileUploadOverlayProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+}
+```
+
+### Example
+
+```tsx
+<OxFileUpload
+  accept={['image/*']}
+  maxSize="5MB"
+  multiple
+  onFileSelect={(files) => console.log(files)}
+  onError={(error) => console.error(error)}
+>
+  <OxFileUpload.Area>
+    <p>Drag files here or click to browse</p>
+    <OxFileUpload.Button>Select Files</OxFileUpload.Button>
+  </OxFileUpload.Area>
+  <OxFileUpload.Overlay>Drop files here</OxFileUpload.Overlay>
+</OxFileUpload>
+```
+
+---
+
+## OxForm
+
+Form container with field management.
+
+**Pattern**: Compound Component
+**Sub-components**: `Group`, `Field`, `Label`, `Description`, `Error`, `GroupTitle`
+
+### Props
+
+```tsx
+interface OxFormProps extends ComponentPropsWithRef<'form'> {
+  children: ReactNode; // Required
+  fullWidth?: boolean; // Makes form full width
+}
+
+interface OxFormGroupProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  layout?: 'grid'; // Optional grid layout
+}
+
+interface OxFormFieldProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode;
+  disabled?: boolean; // Disables all form controls within
+  error?: boolean | string; // Error state or message
+  id?: string; // Field ID for label association
+  labelPosition?: 'start' | 'end'; // Position of label relative to control (default: 'start')
+  orientation?: 'vertical' | 'horizontal'; // Layout direction
+  required?: boolean; // Marks field as required
+}
+
+interface OxFormLabelProps extends ComponentPropsWithRef<'label'> {
+  children: ReactNode; // Required
+  disabled?: boolean;
+  required?: boolean; // Shows required indicator (red asterisk)
+}
+
+interface OxFormDescriptionProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode; // Required
+  disabled?: boolean;
+}
+
+interface OxFormErrorProps extends ComponentPropsWithRef<'div'> {}
+
+interface OxFormGroupTitleProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+  as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'div';
+  children: ReactNode; // Required
+  level?: 1 | 2 | 3 | 4 | 5 | 6 | 7; // Heading level for styling
+}
+```
+
+### Example
+
+```tsx
+<OxForm>
+  <OxForm.Group>
+    <OxForm.GroupTitle level={2}>Account Information</OxForm.GroupTitle>
+    <OxForm.Field orientation="vertical">
+      <OxForm.Label required>Email</OxForm.Label>
+      <OxForm.Description>Your email address</OxForm.Description>
+      <input type="email" />
+      <OxForm.Error>Email is required</OxForm.Error>
+    </OxForm.Field>
+  </OxForm.Group>
+</OxForm>
+```
+
+---
+
+## Input Components
+
+### OxTextInput
+
+Text input with validation and various types.
+
+**Pattern**: Compound Component
+**Parts**: `Container`, input element, `Button`, `ClearButton`, `Counter`, `VisibilityButton`
+
+### Props
+
+```tsx
+type OxTextInputType = 'email' | 'password' | 'search' | 'tel' | 'text' | 'url';
+
+interface OxTextInputContainerProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+  defaultValue?: string;
+  disabled?: boolean;
+  error?: boolean;
+  onChange?: (value: string) => void;
+  required?: boolean;
+  type?: OxTextInputType;
+  validationMessage?: string; // Custom error message shown below input
+  value?: string; // Controlled value
+}
+
+// Input element props
+interface OxTextInputProps {
+  [key: `data-${string}`]?: string | undefined;
+  'aria-describedby'?: string;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  autoComplete?: string;
+  className?: string;
+  id?: string;
+  maxLength?: number;
+  minLength?: number;
+  name?: string;
+  pattern?: string; // Validation regex
+  placeholder?: string;
+  readOnly?: boolean;
+  spellCheck?: boolean;
+}
+
+interface OxTextInputButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'type'> {}
+
+interface OxTextInputCounterProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  currentLength?: number;
+  disabled?: boolean;
+  maxLength: number; // Required
+}
+```
+
+### Example
+
+```tsx
+<OxTextInput.Container
+  type="email"
+  value={email}
+  onChange={setEmail}
+  error={!!emailError}
+  validationMessage="Please enter a valid email"
+>
+  <OxTextInput placeholder="Enter email" maxLength={100} />
+  <OxTextInput.ClearButton />
+  <OxTextInput.Counter maxLength={100} />
+</OxTextInput.Container>;
+
+{
+  /* Password input */
+}
+<OxTextInput.Container type="password">
+  <OxTextInput placeholder="Password" />
+  <OxTextInput.VisibilityButton />
+</OxTextInput.Container>;
+```
+
+---
+
+### OxNumberInput
+
+Numeric input with increment/decrement controls.
+
+**Pattern**: Compound Component
+**Parts**: `Container`, input element, `Button`, `IncrementButton`, `DecrementButton`
+
+### Props
+
+```tsx
+interface OxNumberInputContainerProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+  defaultValue?: number;
+  disabled?: boolean;
+  error?: boolean;
+  locale?: string; // Locale for number formatting
+  max?: number; // Maximum value
+  maximumFractionDigits?: number; // Max decimal places
+  min?: number; // Minimum value
+  minimumFractionDigits?: number; // Min decimal places
+  onChange?: (value: number | undefined) => 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
+}
+
+interface OxNumberInputProps {
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  className?: string;
+  id?: string;
+  placeholder?: string;
+}
+
+interface OxNumberInputButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'type'> {}
+```
+
+### Example
+
+```tsx
+<OxNumberInput.Container
+  value={quantity}
+  onChange={setQuantity}
+  min={0}
+  max={100}
+  steps={5}
+  useGrouping
+>
+  <OxNumberInput.DecrementButton />
+  <OxNumberInput placeholder="Quantity" />
+  <OxNumberInput.IncrementButton />
+</OxNumberInput.Container>
+```
+
+---
+
+### OxDateInput
+
+Date input with picker.
+
+**Pattern**: Compound Component
+**Parts**: `Container`, `Button`, `PickerButton`
+
+### Props
+
+```tsx
+interface OxDateInputContainerProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'> {
+  defaultOpen?: boolean; // Default open state of picker
+  defaultValue?: string; // Date string
+  disabled?: boolean;
+  error?: boolean;
+  onChange?: (value: string) => void;
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+  pickOnly?: boolean; // Only allow picking from calendar, no manual input
+  readOnly?: boolean;
+  required?: boolean;
+  validationMessage?: string; // Custom error message shown below input
+  value?: string; // Controlled value
+}
+
+interface OxDateInputButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'type'> {}
+
+// Picker button - opens calendar
+interface OxDatePickerButtonProps extends Omit<
+  ComponentPropsWithRef<'button'>,
+  'type' | 'children'
+> {}
+```
+
+### Example
+
+```tsx
+<OxDateInput.Container value={date} onChange={setDate}>
+  <OxDateInput.PickerButton />
+</OxDateInput.Container>;
+
+{
+  /* Pick-only mode (no manual input) */
+}
+<OxDateInput.Container pickOnly>
+  <OxDateInput.PickerButton />
+</OxDateInput.Container>;
+```
+
+---
+
+### OxTimeInput
+
+Time input component.
+
+**Pattern**: Compound Component
+**Parts**: `Container`, `Button`
+
+### Props
+
+```tsx
+interface OxTimeInputContainerProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+  defaultValue?: string; // Time string
+  disabled?: boolean;
+  error?: boolean;
+  onChange?: (value: string) => void;
+  required?: boolean;
+  validationMessage?: string; // Custom error message shown below input
+  value?: string; // Controlled value
+}
+
+interface OxTimeInputButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'type'> {}
+```
+
+### Example
+
+```tsx
+<OxTimeInput.Container value={time} onChange={setTime}>
+  <input type="time" />
+</OxTimeInput.Container>
+```
+
+---
+
+### OxOtpInput
+
+One-Time Password input.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+type OxOtpInputType = 'numeric' | 'alphanumeric' | 'text';
+
+interface OxOtpInputProps {
+  className?: string;
+  disabled?: boolean;
+  error?: boolean;
+  length?: number; // Number of digits/characters
+  onComplete?: (value: string) => void; // Called when all digits filled
+  onValueChange?: (value: string) => void; // Called on any change
+  placeholder?: string;
+  type?: OxOtpInputType; // Type of characters allowed
+}
+```
+
+### Example
+
+```tsx
+<OxOtpInput
+  length={6}
+  type="numeric"
+  onComplete={(code) => verifyCode(code)}
+  onValueChange={(value) => console.log(value)}
+/>
+```
+
+---
+
+## OxRadio
+
+Radio button group.
+
+**Pattern**: Compound Component (Namespace - no standalone component)
+**Sub-components**: `Group`, `Item`
+
+### Props
+
+```tsx
+interface OxRadioGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+  children: ReactNode; // Required
+  defaultValue?: string | number;
+  disabled?: boolean; // Disables all radio buttons
+  error?: boolean;
+  name?: string;
+  onChange?: (value: string | number) => void;
+  required?: boolean;
+  value?: string | number; // Controlled selected value
+}
+
+interface OxRadioItemProps extends Omit<
+  ComponentPropsWithoutRef<'input'>,
+  'type' | 'size' | 'required'
+> {
+  error?: boolean;
+  onCheckedChange?: (checked: boolean) => void; // Called when this item is checked
+  value?: string | number;
+}
+```
+
+### Example
+
+```tsx
+<OxRadio.Group name="plan" value={plan} onChange={setPlan}>
+  <OxRadio.Item value="basic" />
+  <OxRadio.Item value="pro" />
+  <OxRadio.Item value="enterprise" />
+</OxRadio.Group>
+```
+
+**Note**: No standalone `OxRadio` component - only `OxRadio.Group` and `OxRadio.Item`.
+
+---
+
+## OxSelect
+
+Select dropdown with single and multi-select.
+
+**Pattern**: Compound Component
+**Sub-components**: `Trigger`, `Content`, `Group`, `Item`
+
+### Props
+
+```tsx
+interface OxSelectProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+  defaultOpen?: boolean;
+  defaultValue?: string | number | null | Array<string | number | null>;
+  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;
+  onOpenChange?: (open: boolean) => void;
+  open?: boolean; // Controlled open state
+  required?: boolean;
+  value?: string | number | null | Array<string | number | null>; // Controlled value
+}
+
+interface OxSelectTriggerProps extends ComponentPropsWithRef<'button'> {
+  displayAsTag?: boolean; // Display selected items as tags (multi-select)
+  placeholder?: string;
+  tagColor?: ColorStyleName;
+}
+
+interface OxSelectContentProps extends ComponentPropsWithRef<'ul'> {}
+
+interface OxSelectGroupProps extends ComponentPropsWithRef<'div'> {
+  label?: ReactNode; // Group label
+}
+
+interface OxSelectItemProps extends Omit<ComponentPropsWithRef<'button'>, 'value'> {
+  value: string | number | null; // Required
+}
+```
+
+### Example
+
+```tsx
+{
+  /* Single select */
+}
+<OxSelect value={country} onChange={setCountry}>
+  <OxSelect.Trigger placeholder="Select country" />
+  <OxSelect.Content>
+    <OxSelect.Item value="us">United States</OxSelect.Item>
+    <OxSelect.Item value="uk">United Kingdom</OxSelect.Item>
+  </OxSelect.Content>
+</OxSelect>;
+
+{
+  /* Multi-select with badges */
+}
+<OxSelect multiple value={tags} onChange={setTags}>
+  <OxSelect.Trigger displayAsTag tagColor="blue" />
+  <OxSelect.Content>
+    <OxSelect.Group label="Categories">
+      <OxSelect.Item value="react">React</OxSelect.Item>
+      <OxSelect.Item value="typescript">TypeScript</OxSelect.Item>
+    </OxSelect.Group>
+  </OxSelect.Content>
+</OxSelect>;
+```
+
+---
+
+## OxSwitch
+
+Toggle switch for boolean values.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxSwitchProps extends Omit<
+  ComponentPropsWithRef<'button'>,
+  'type' | 'size' | 'onChange' | 'children'
+> {
+  checked?: boolean; // Controlled checked state
+  error?: boolean;
+  onChange?: (checked: boolean) => void;
+  required?: boolean;
+}
+```
+
+### Example
+
+```tsx
+<OxSwitch checked={enabled} onChange={setEnabled} />
+```
+
+---
+
+## OxTextarea
+
+Multi-line text input.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxTextareaProps extends Omit<ComponentPropsWithRef<'textarea'>, 'children'> {
+  error?: boolean;
+  showMaxLength?: boolean; // Show character count indicator
+}
+```
+
+### Example
+
+```tsx
+<OxTextarea placeholder="Enter description" maxLength={500} showMaxLength rows={5} />
+```
+
+---
+
+# Layout Components (3)
+
+## OxAppLayout
+
+Top-level application layout wrapper.
+
+**Pattern**: Simple Wrapper
+
+### Props
+
+```tsx
+interface OxAppLayoutProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode; // Required
+  className?: string;
+}
+```
+
+### Example
+
+```tsx
+<OxSidebarProvider>
+  <OxAppLayout>
+    <OxSidebar>...</OxSidebar>
+    <OxMainContent>...</OxMainContent>
+  </OxAppLayout>
+</OxSidebarProvider>
+```
+
+**Notes**:
+
+- Responsive grid layout (single column on mobile, two-column on desktop)
+- Mobile breakpoint: 640px
+- Requires `OxSidebarProvider` in component tree
+- Max width: `max-w-16xl`
+
+---
+
+## OxMainContent
+
+Main content area with header and body.
+
+**Pattern**: Compound Component
+**Sub-components**: `Header`, `Body`
+
+### Props
+
+```tsx
+interface OxMainContentProps extends ComponentPropsWithRef<'main'> {
+  children: ReactNode; // Required
+  className?: string;
+}
+
+interface OxMainContentHeaderProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode; // Required
+  className?: string;
+}
+
+interface OxMainContentBodyProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode; // Required
+  className?: string;
+}
+```
+
+### Example
+
+```tsx
+<OxMainContent>
+  <OxMainContent.Header>
+    <h1>Page Title</h1>
+  </OxMainContent.Header>
+  <OxMainContent.Body>Page content here</OxMainContent.Body>
+</OxMainContent>
+```
+
+---
+
+## OxSidebar
+
+Comprehensive sidebar navigation system.
+
+**Pattern**: Complex Compound Component
+**Main Exports**: `OxSidebar`, `OxSidebarMenu`, `OxSidebarGroup`, `OxSidebarProvider`, `useOxSidebar`
+
+### Sidebar Sub-components
+
+- `OxSidebar.Header` - Top section
+- `OxSidebar.Content` - Main scrollable area
+- `OxSidebar.Footer` - Bottom section
+- `OxSidebar.Separator` - Visual divider
+- `OxSidebar.Trigger` - Toggle button (mobile)
+
+### Menu Sub-components
+
+- `OxSidebarMenu.Item` - Menu item wrapper
+- `OxSidebarMenu.Button` - Clickable button/link (polymorphic)
+- `OxSidebarMenu.Icon` - Icon for menu items
+- `OxSidebarMenu.Tag` - Tag/counter
+- `OxSidebarMenu.Action` - Action button
+- `OxSidebarMenu.Skeleton` - Loading skeleton
+- `OxSidebarMenu.Sub` - Submenu container
+- `OxSidebarMenu.SubItem` - Submenu item wrapper
+- `OxSidebarMenu.SubButton` - Submenu button
+
+### Group Sub-components
+
+- `OxSidebarGroup.Label` - Group heading
+- `OxSidebarGroup.Action` - Group action button
+- `OxSidebarGroup.Content` - Group content container
+
+### Props
+
+```tsx
+// Provider
+interface OxSidebarProviderProps {
+  children: ReactNode; // Required
+}
+
+// Root Sidebar
+interface OxSidebarProps extends ComponentPropsWithoutRef<'aside'> {
+  children: ReactNode; // Required
+  className?: string;
+}
+
+// Menu Item
+interface OxSidebarMenuItemProps extends ComponentPropsWithRef<'li'> {
+  children: ReactNode;
+  className?: string;
+  defaultOpen?: boolean; // Initial open state for submenu
+  hasSub?: boolean; // Indicates if item has submenu
+}
+
+// Menu Button (Polymorphic - renders as link or button)
+type OxSidebarMenuButtonProps =
+  | {
+      children: ReactNode;
+      href: string; // Required for link variant
+      disabled?: boolean;
+      className?: string;
+      onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    }
+  | {
+      children: ReactNode;
+      href?: never;
+      type?: 'button';
+      disabled?: boolean;
+      className?: string;
+      onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    };
+```
+
+### Hook
+
+```tsx
+const { isMobile, mobileOpen, openSidebar, closeSidebar, toggleSidebar } = useOxSidebar();
+
+// Returns:
+// - isMobile: boolean (viewport < 640px)
+// - mobileOpen: boolean (current mobile open state)
+// - openSidebar: () => void
+// - closeSidebar: () => void
+// - toggleSidebar: () => void
+```
+
+### Example
+
+```tsx
+<OxSidebarProvider>
+  <OxAppLayout>
+    <OxSidebar>
+      <OxSidebar.Header>
+        <img src="/logo.png" alt="Logo" />
+      </OxSidebar.Header>
+
+      <OxSidebar.Content>
+        <OxSidebarMenu>
+          {/* Simple menu item */}
+          <OxSidebarMenu.Item>
+            <OxSidebarMenu.Button href="/dashboard">
+              <OxSidebarMenu.Icon icon={Home} />
+              Dashboard
+            </OxSidebarMenu.Button>
+          </OxSidebarMenu.Item>
+
+          {/* Menu item with submenu */}
+          <OxSidebarMenu.Item hasSub defaultOpen>
+            <OxSidebarMenu.Button>
+              <OxSidebarMenu.Icon icon={Settings} />
+              Settings
+              <OxSidebarMenu.Tag>3</OxSidebarMenu.Tag>
+            </OxSidebarMenu.Button>
+            <OxSidebarMenu.Sub>
+              <OxSidebarMenu.SubItem>
+                <OxSidebarMenu.SubButton>Profile</OxSidebarMenu.SubButton>
+              </OxSidebarMenu.SubItem>
+            </OxSidebarMenu.Sub>
+          </OxSidebarMenu.Item>
+        </OxSidebarMenu>
+
+        <OxSidebarGroup>
+          <OxSidebarGroup.Label>Projects</OxSidebarGroup.Label>
+          <OxSidebarGroup.Content>{/* Group items */}</OxSidebarGroup.Content>
+        </OxSidebarGroup>
+      </OxSidebar.Content>
+
+      <OxSidebar.Footer>User info</OxSidebar.Footer>
+    </OxSidebar>
+
+    <OxMainContent>...</OxMainContent>
+  </OxAppLayout>
+</OxSidebarProvider>
+```
+
+**Notes**:
+
+- Responsive: Drawer on mobile (< 640px), fixed sidebar on desktop
+- Width: 256px on desktop
+- Automatically manages submenu state
+- MenuButton with `hasSub` automatically shows chevron and toggles submenu
+- Polymorphic MenuButton (renders as `<a>` if href provided, otherwise `<button>`)
+
+---
+
+# Typography Components (5)
+
+## OxDescription
+
+Helper text component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxDescriptionProps extends ComponentPropsWithRef<'div'> {
+  children: ReactNode; // Required
+  disabled?: boolean; // Applies disabled styling
+}
+```
+
+### Example
+
+```tsx
+<OxDescription>This field is required for verification.</OxDescription>
+<OxDescription disabled>This field is disabled.</OxDescription>
+```
+
+---
+
+## OxError
+
+Error message component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxErrorProps extends ComponentPropsWithRef<'div'> {
+  children?: ReactNode; // Returns null if not provided
+}
+```
+
+### Example
+
+```tsx
+<OxError>Email is required</OxError>
+<OxError>
+  <AlertCircle /> Invalid format
+</OxError>
+```
+
+**Notes**:
+
+- Renders with `role="alert"`
+- Returns `null` if no children
+- Auto-styles SVG children with proper sizing
+
+---
+
+## OxHeading
+
+Heading component with 7 visual levels.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxHeadingProps extends HTMLAttributes<HTMLElement> {
+  as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'div'; // Element to render (default: 'h2')
+  children: ReactNode; // Required
+  level?: 1 | 2 | 3 | 4 | 5 | 6 | 7; // Visual styling level
+}
+```
+
+**Level Styles**:
+
+- 1: `text-2xl font-bold`
+- 2: `text-xl font-semibold` (default)
+- 3: `text-lg font-semibold`
+- 4: `text-base font-semibold`
+- 5: `text-sm font-semibold`
+- 6: `text-sm font-medium`
+- 7: `text-sm`
+
+### Example
+
+```tsx
+<OxHeading as="h1" level={1}>Page Title</OxHeading>
+<OxHeading as="h2">Section Title</OxHeading>
+<OxHeading as="div" level={3}>Custom Element</OxHeading>
+```
+
+**Notes**:
+
+- Semantic level derived from `as` prop if `level` not provided
+- Adds `role="heading"` and `aria-level` when `as="div"`
+- No ref support
+
+---
+
+## OxLabel
+
+Form label component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxLabelProps extends ComponentPropsWithRef<'label'> {
+  children: ReactNode; // Required
+  disabled?: boolean;
+  required?: boolean; // Shows red asterisk (*)
+}
+```
+
+### Example
+
+```tsx
+<OxLabel htmlFor="email" required>Email Address</OxLabel>
+<OxLabel disabled>Disabled Field</OxLabel>
+```
+
+**Notes**:
+
+- Cursor changes to `pointer` when `htmlFor` provided and not disabled
+- Required indicator: red asterisk appended when `required={true}`
+
+---
+
+## OxLegend
+
+Fieldset legend component.
+
+**Pattern**: Simple Component
+
+### Props
+
+```tsx
+interface OxLegendProps extends ComponentPropsWithRef<'legend'> {
+  children: ReactNode; // Required
+  disabled?: boolean;
+  required?: boolean; // Shows red asterisk (*)
+}
+```
+
+### Example
+
+```tsx
+<fieldset>
+  <OxLegend required>Personal Information</OxLegend>
+  ...
+</fieldset>
+```
+
+**Notes**:
+
+- Use with `<fieldset>` elements
+- Similar to Label but larger font size (`text-base` vs `text-sm`)
+
+---
+
+# Contexts (3)
+
+## OxAuthContext
+
+Factory-based authentication context with custom fetcher pattern (backend-agnostic).
+
+**Exports**: `createOxAuth`
+
+### Factory Pattern
+
+```tsx
+type OxCheckFunction<T> = (user: T | null) => boolean;
+type OxChecks<T> = Record<string, OxCheckFunction<T>>;
+
+interface CreateOxAuthConfig<T, C extends OxChecks<T>> {
+  checks?: C; // Custom check functions defined at factory level
+}
+
+interface OxAuthProviderProps<T> {
+  children: ReactNode;
+  fetcher: () => Promise<T | null>; // Custom fetcher (REST, GraphQL, etc.)
+  pollInterval?: number; // Default: 300000 (5 minutes), 0 to disable
+}
+
+type OxAuthContextValue<T, C extends OxChecks<T>> = {
+  checks: { [K in keyof C]: boolean }; // Evaluated check results
+  error: Error | null;
+  isLoggedIn: boolean; // Computed from !!user
+  loading: boolean;
+  refreshUser: () => Promise<void>;
+  user: T | null;
+};
+
+// Factory returns typed Provider and Hook
+function createOxAuth<T, C extends OxChecks<T>>(
+  config: CreateOxAuthConfig<T, C>
+): {
+  OxAuthProvider: (props: OxAuthProviderProps<T>) => ReactNode;
+  useOxAuth: () => OxAuthContextValue<T, C>;
+};
+```
+
+### Example
+
+```tsx
+// 1. Define user type and create auth context (src/lib/auth.ts)
+interface MyUser {
+  id: string;
+  email: string;
+  role: 'admin' | 'user';
+  emailVerified: boolean;
+}
+
+export const { OxAuthProvider, useOxAuth } = createOxAuth<MyUser>({
+  checks: {
+    isAdmin: (user) => user?.role === 'admin',
+    isVerified: (user) => user?.emailVerified === true,
+  },
+});
+
+// 2. Wrap app with provider (REST example)
+import { OxAuthProvider } from '@/lib/auth';
+
+<OxAuthProvider
+  fetcher={async () => {
+    const res = await fetch('/api/auth/me', { credentials: 'include' });
+    if (!res.ok) return null;
+    return res.json();
+  }}
+  pollInterval={300000}
+>
+  <App />
+</OxAuthProvider>
+
+// 2. Wrap app with provider (GraphQL example)
+<OxAuthProvider
+  fetcher={async () => {
+    const { data } = await apolloClient.query({ query: GET_ME });
+    return data.me;
+  }}
+>
+  <App />
+</OxAuthProvider>
+
+// 3. Use hook in components (no generics needed - already typed!)
+import { useOxAuth } from '@/lib/auth';
+
+function MyComponent() {
+  const { user, isLoggedIn, checks, loading, refreshUser } = useOxAuth();
+
+  if (loading) return <Spinner />;
+  if (!isLoggedIn) return <Login />;
+  if (!checks.isVerified) return <VerifyEmail />;
+
+  return <Dashboard user={user} isAdmin={checks.isAdmin} />;
+}
+```
+
+**Notes**:
+
+- Factory pattern: checks defined once, full TypeScript inference
+- Backend-agnostic: works with REST, GraphQL, or any async fetcher
+- No generics at call site: hook is pre-typed from factory
+- No external dependencies (no Apollo required)
+- Throws error if hook used outside provider
+
+---
+
+## OxDialogContext
+
+Modal dialog management.
+
+**Exports**: `OxDialogProvider`, `useOxDialog`
+
+### Props
+
+```tsx
+interface OxDialogProviderProps {
+  children: ReactNode;
+  maxDialogs?: number; // Default: 3
+}
+
+interface OxDialogOptions {
+  className?: string;
+  closeOnOutsideClick?: boolean;
+  persistent?: boolean;
+  showCloseButton?: boolean;
+  size?: OxDialogSize;
+}
+
+// Callable API
+interface OxDialogContextApi {
+  // Shorthand
+  (content: ReactNode, options?: OxDialogOptions): string; // Returns dialog ID
+
+  // Methods
+  dismiss: () => void; // Close top dialog
+  dismissAll: () => void; // Close all dialogs
+  open: (content: ReactNode, options?: OxDialogOptions) => string;
+}
+```
+
+### Example
+
+```tsx
+// Wrap app
+<OxDialogProvider maxDialogs={3}>
+  <App />
+</OxDialogProvider>;
+
+// Use in component
+function MyComponent() {
+  const dialog = useOxDialog();
+
+  const showConfirm = () => {
+    dialog(
+      <div>
+        <h2>Confirm Action</h2>
+        <button onClick={dialog.dismiss}>Cancel</button>
+      </div>,
+      { size: 'md', showCloseButton: true }
+    );
+  };
+
+  return <button onClick={showConfirm}>Show Dialog</button>;
+}
+```
+
+**Notes**:
+
+- Stack-based management (LIFO)
+- Auto body scroll lock when dialogs open
+- Max dialog limit prevents too many concurrent dialogs
+
+---
+
+## OxFeatureFlagContext
+
+Feature flag system with dev mode.
+
+**Exports**: `OxFeatureProvider`, `OxFeatureFlag`, `useOxFeature`, `DEFAULT_GET_FEATURES`
+
+### Props
+
+```tsx
+interface OxFeatureProviderProps {
+  children: ReactNode;
+  enableDevMode?: boolean; // Default: false (enables all features)
+  getFeaturesQuery?: DocumentNode; // Custom GraphQL query
+  options?: Parameters<typeof useQuery>[1]; // Apollo options
+  pollInterval?: number; // Default: 300000 (5 minutes)
+}
+
+type FeatureFlags = Record<string, boolean>;
+
+type OxFeatureContextType = {
+  enableDevMode: boolean;
+  error: ErrorLike | null;
+  features: FeatureFlags;
+  isEnabled: (featureName: string) => boolean;
+  loading: boolean;
+  refreshFeatures: RefetchFunction;
+};
+
+interface OxFeatureFlagProps {
+  children: ReactNode;
+  className?: string;
+  fallback?: ReactNode; // Rendered when feature disabled
+  name: string; // Required - Feature flag name
+}
+```
+
+### Example
+
+```tsx
+// Wrap app
+<OxFeatureProvider enableDevMode={false}>
+  <App />
+</OxFeatureProvider>;
+
+// Use hook
+function MyComponent() {
+  const { isEnabled, features } = useOxFeature();
+
+  if (isEnabled('new-dashboard')) {
+    return <NewDashboard />;
+  }
+  return <OldDashboard />;
+}
+
+// Use component
+<OxFeatureFlag name="beta-feature" fallback={<ComingSoon />}>
+  <BetaFeature />
+</OxFeatureFlag>;
+```
+
+**Notes**:
+
+- Dev mode enables ALL features and skips GraphQL query
+- Apollo integration with auto-polling
+- Declarative `OxFeatureFlag` component for conditional rendering
+
+---
+
+# Hooks (13)
+
+## useControllableState
+
+Manages state that can be both controlled and uncontrolled.
+
+### Signature
+
+```tsx
+function useControllableState<T>(params: {
+  defaultValue?: T;
+  name?: string; // Default: 'Component'
+  onChange?: (value: T | undefined) => void;
+  value?: T;
+}): [
+  T | undefined, // Current value
+  (value: T | undefined | ((prev: T | undefined) => T | undefined)) => void, // Setter
+];
+```
+
+### Example
+
+```tsx
+function MyComponent({ value, defaultValue, onChange }) {
+  const [internalValue, setValue] = useControllableState({
+    value,
+    defaultValue,
+    onChange,
+  });
+
+  return <input value={internalValue} onChange={(e) => setValue(e.target.value)} />;
+}
+```
+
+**Notes**:
+
+- Provides dev warnings when switching between modes
+- Uses `Object.is()` for efficient comparison
+- Follows Radix UI patterns
+
+---
+
+## useFileUpload
+
+Handles file uploads with validation and progress.
+
+### Signature
+
+```tsx
+function useFileUpload<T extends Record<string, unknown>>(options: {
+  endpoint: string;  // Required
+  headers?: Record<string, string>;
+  initialData: T;  // Required
+  validationRules?: ValidatorConfig;
+}): UseFileUploadReturn<T>;
+
+// Returns UseFormStateReturn<T> + additional:
+{
+  cancel: () => void;
+  isUploading: boolean;
+  upload: (options?: {
+    onBefore?: () => void;
+    onCancel?: (error: unknown) => void;
+    onError?: (error: unknown) => void;
+    onFinish?: () => void;
+    onSuccess?: (response: AxiosResponse) => void;
+    onUpload?: (progressEvent: AxiosProgressEvent) => void;
+    skipValidation?: boolean;
+  }) => void;
+}
+```
+
+### Example
+
+```tsx
+function FileUploadForm() {
+  const { data, setData, upload, isUploading, cancel, errors } = useFileUpload({
+    endpoint: '/api/upload',
+    initialData: { file: null, description: '' },
+    validationRules: {
+      file: ['required', 'file', 'fileSize:5MB'],
+      description: ['required', 'minLength:10'],
+    },
+  });
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        upload();
+      }}
+    >
+      <input type="file" onChange={(e) => setData('file', e.target.files[0])} />
+      <input value={data.description} onChange={(e) => setData('description', e.target.value)} />
+      <button type="submit" disabled={isUploading}>
+        Upload
+      </button>
+      {isUploading && <button onClick={cancel}>Cancel</button>}
+    </form>
+  );
+}
+```
+
+**Notes**:
+
+- Axios `multipart/form-data` uploads
+- Upload progress tracking
+- Cancellation via `AbortController`
+- Pre-upload validation
+
+---
+
+## useFilterFetch
+
+Manages filter state with REST API fetch requests.
+
+### Signature
+
+```tsx
+function useFilterFetch<T extends Record<string, any>, TResponse = unknown>(options: {
+  headers?: Record<string, string>;
+  initialData: T; // Required - initial filter values
+  method?: 'GET' | 'POST'; // Default: 'GET'
+  url: string; // Required - API endpoint
+  validationRules?: ValidatorConfig;
+}): UseFilterFetchReturn<T, TResponse>;
+
+interface UseFilterFetchReturn<T, TResponse> {
+  data: TResponse | undefined; // Response data
+  error: unknown;
+  errors: Record<keyof T, string[]>; // Validation errors per field
+  filter: T; // Current filter values
+  isDirty: boolean;
+  isLoading: boolean;
+  isValid: boolean;
+  query: (options?: FilterFetchQueryOptions<TResponse>) => void;
+  refetch: () => void; // Re-run with current filters
+  reset: () => void;
+  setFilter: (key: keyof T, value: T[keyof T]) => void;
+  validate: () => boolean;
+}
+
+interface FilterFetchQueryOptions<TResponse> {
+  onBefore?: () => void;
+  onError?: (error: unknown) => void;
+  onFinish?: () => void;
+  onSuccess?: (response: TResponse) => void;
+  skipValidation?: boolean;
+}
+```
+
+### Example
+
+```tsx
+function ProductList() {
+  const { data, filter, setFilter, query, isLoading } = useFilterFetch<
+    { category: string; search: string },
+    Product[]
+  >({
+    url: '/api/products',
+    initialData: { category: '', search: '' },
+  });
+
+  return (
+    <div>
+      <input
+        value={filter.search}
+        onChange={(e) => setFilter('search', e.target.value)}
+        onKeyDown={(e) => e.key === 'Enter' && query()}
+      />
+      <select
+        value={filter.category}
+        onChange={(e) => {
+          setFilter('category', e.target.value);
+          query();
+        }}
+      >
+        <option value="">All</option>
+        <option value="electronics">Electronics</option>
+      </select>
+      {isLoading ? (
+        <Spinner />
+      ) : (
+        data?.map((product) => <ProductCard key={product.id} {...product} />)
+      )}
+    </div>
+  );
+}
+```
+
+**Notes**:
+
+- Similar to `useFilterQuery` but for REST APIs instead of GraphQL
+- Supports GET (query params) and POST (body) methods
+- Built on `useFormState` for validation and state management
+
+---
+
+## useFilterQuery
+
+Manages filter state with GraphQL queries.
+
+### Signature
+
+```tsx
+function useFilterQuery<T extends Record<string, any>, TResponse = unknown>(options: {
+  query: DocumentNode;  // Required
+  headers?: Record<string, string>;
+  initialData: T;  // Required
+  validationRules?: ValidatorConfig;
+  options?: Parameters<typeof useLazyQuery<TResponse>>[1];
+}): UseFilterQueryReturn<T, TResponse>;
+
+// Returns:
+{
+  data: TResponse | undefined;  // Query response
+  error: unknown;
+  filter: T;  // Filter values
+  setFilter: (data: Partial<T>) => void | ((path: string, value: any) => void);
+  isLoading: boolean;
+  query: (options?: QueryOptions<TResponse>) => void;
+  refetch: () => void;
+  // + UseFormState methods (errors, validate, etc.)
+}
+```
+
+### Example
+
+```tsx
+const GET_USERS = gql`
+  query GetUsers($filters: UserFilters) {
+    users(filters: $filters) {
+      id
+      name
+    }
+  }
+`;
+
+function UserFilter() {
+  const { filter, setFilter, query, data, isLoading } = useFilterQuery({
+    query: GET_USERS,
+    initialData: { name: '', role: '' },
+  });
+
+  return (
+    <div>
+      <input value={filter.name} onChange={(e) => setFilter('name', e.target.value)} />
+      <button onClick={() => query()}>Search</button>
+      {isLoading && <Spinner />}
+      {data?.users.map((user) => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Notes**:
+
+- Apollo `useLazyQuery` integration
+- Default fetch policy: `network-only`
+- Passes filters as `{ filters: data }` to query
+
+---
+
+## useFocus
+
+Manages focus within a container.
+
+### Signature
+
+```tsx
+function useFocus(params: {
+  containerRef: RefObject<HTMLElement | null>; // Required
+  options?: {
+    autoFocus?: boolean; // Default: false
+    enabled?: boolean; // Default: true
+    restoreFocus?: boolean; // Default: false
+    trapFocus?: boolean; // Default: false
+  };
+}): {
+  focusFirst: () => void;
+  focusLast: () => void;
+  getCurrentFocus: () => HTMLElement | null;
+  getFocusableElements: () => HTMLElement[];
+};
+```
+
+### Example
+
+```tsx
+function Modal() {
+  const containerRef = useRef(null);
+  const { focusFirst } = useFocus({
+    containerRef,
+    options: { autoFocus: true, trapFocus: true, restoreFocus: true },
+  });
+
+  return (
+    <div ref={containerRef}>
+      <button>First</button>
+      <button>Second</button>
+      <button>Last</button>
+    </div>
+  );
+}
+```
+
+**Notes**:
+
+- Auto-focus on mount
+- Circular Tab navigation with `trapFocus`
+- Focus restoration on unmount
+- Shift+Tab support
+
+---
+
+## useForm
+
+Form state with GraphQL mutations.
+
+### Signature
+
+```tsx
+function useForm<T extends Record<string, any>, TResponse = unknown>(options: {
+  operation: DocumentNode;  // Required - GraphQL mutation
+  headers?: Record<string, string>;
+  initialData: T;  // Required
+  validationRules?: ValidatorConfig;
+  options?: Parameters<typeof useMutation<TResponse>>[1];
+}): UseFormReturn<T, TResponse>;
+
+// Returns UseFormStateReturn<T> + additional:
+{
+  isLoading: boolean;
+  submit: (options?: {
+    onBefore?: () => void;
+    onError?: (error: unknown) => void;
+    onFinish?: () => void;
+    onSuccess?: (response: any) => void;
+    skipValidation?: boolean;
+  }) => void;
+  transform: (fn: (data: T) => unknown) => Omit<UseFormReturn<T, TResponse>, 'transform'>;
+}
+```
+
+### Example
+
+```tsx
+const CREATE_USER = gql`
+  mutation CreateUser($input: UserInput!) {
+    createUser(input: $input) {
+      id
+      name
+    }
+  }
+`;
+
+function UserForm() {
+  const { data, setData, submit, isLoading, errors } = useForm({
+    operation: CREATE_USER,
+    initialData: { name: '', email: '' },
+    validationRules: {
+      name: ['required', 'minLength:2'],
+      email: ['required', 'email'],
+    },
+  });
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <input value={data.name} onChange={(e) => setData('name', e.target.value)} />
+      {errors.name && <OxError>{errors.name}</OxError>}
+      <button type="submit" disabled={isLoading}>
+        Submit
+      </button>
+    </form>
+  );
+}
+```
+
+**Notes**:
+
+- Apollo `useMutation` integration
+- Passes data as `{ input: data }`
+- `transform()` for pre-submission data transformation
+- Pre-submission validation
+
+---
+
+## useFormFetch
+
+Form state management with REST API submission via fetch.
+
+### Signature
+
+```tsx
+function useFormFetch<T extends Record<string, any>, TResponse = unknown>(options: {
+  headers?: Record<string, string>;
+  initialData: T; // Required
+  method?: 'DELETE' | 'PATCH' | 'POST' | 'PUT'; // Default: 'POST'
+  url: string; // Required - API endpoint
+  validationRules?: ValidatorConfig;
+}): UseFormFetchReturn<T, TResponse>;
+
+interface UseFormFetchReturn<T, TResponse> extends UseFormStateReturn<T> {
+  isLoading: boolean;
+  submit: (options?: FormFetchSubmitOptions<TResponse>) => void;
+  transform: (fn: (data: T) => unknown) => Omit<UseFormFetchReturn<T, TResponse>, 'transform'>;
+}
+
+interface FormFetchSubmitOptions<TResponse> {
+  onBefore?: () => void;
+  onError?: (error: unknown) => void;
+  onFinish?: () => void;
+  onSuccess?: (response: TResponse) => void;
+  skipValidation?: boolean;
+}
+```
+
+### Example
+
+```tsx
+function CreateUserForm() {
+  const { data, setData, submit, errors, isLoading } = useFormFetch<
+    { email: string; name: string },
+    { id: string }
+  >({
+    url: '/api/users',
+    method: 'POST',
+    initialData: { email: '', name: '' },
+    validationRules: {
+      email: ['required', 'email'],
+      name: ['required', 'minLength:2'],
+    },
+  });
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); submit({ onSuccess: (res) => navigate(`/users/${res.id}`) }); }}>
+      <input value={data.name} onChange={(e) => setData('name', e.target.value)} />
+      {errors.name && <span>{errors.name[0]}</span>}
+      <input value={data.email} onChange={(e) => setData('email', e.target.value)} />
+      {errors.email && <span>{errors.email[0]}</span>}
+      <button type="submit" disabled={isLoading}>Create</button>
+    </form>
+  );
+}
+
+// With data transformation
+const { submit, transform } = useFormFetch({ ... });
+transform((data) => ({ ...data, timestamp: Date.now() })).submit();
+```
+
+**Notes**:
+
+- Similar to `useForm` but for REST APIs instead of GraphQL
+- Supports all HTTP methods (POST, PUT, PATCH, DELETE)
+- `transform()` allows modifying data before submission
+- Prevents duplicate submissions while loading
+
+---
+
+## useFormState
+
+Core form state management with Zod validation.
+
+### Signature
+
+```tsx
+function useFormState<T extends Record<string, unknown>>(options: {
+  initialData: T; // Required (cannot contain 'root' key)
+  validationRules?: ValidatorConfig;
+}): {
+  data: T;
+  setData: {
+    (data: Partial<T>): void; // Set multiple fields
+    (path: string, value: any): void; // Set single field by path
+  };
+  errors: Record<string, string | string[]>;
+  hasErrors: boolean;
+  isDirty: boolean;
+  clearError: (field: string) => void;
+  clearErrors: () => void;
+  setError: (field: string, error: string | string[]) => void;
+  hasError: (field: string) => boolean;
+  reset: () => void;
+  validate: () => boolean;
+};
+```
+
+### Built-in Validation Rules
+
+**Simple Rules**:
+
+- `'nullable'`, `'required'`, `'string'`, `'email'`, `'url'`, `'number'`, `'integer'`, `'positive'`, `'negative'`, `'ipv4'`, `'boolean'`, `'date'`, `'array'`, `'object'`, `'file'`
+
+**Parametrized Rules**:
+
+- `'min:${number}'`, `'max:${number}'`, `'minLength:${number}'`, `'maxLength:${number}'`, `'pattern:${string}'`, `'fileSize:${string}'` (e.g., '5MB'), `'fileType:${string}'` (e.g., 'image/\*'), `'arrayMinLength:${number}'`, `'arrayMaxLength:${number}'`
+
+**Array Rules**:
+
+- `'arrayEach:string'`, `'arrayEach:number'`, `'arrayEach:email'`, `'arrayEach:url'`, `'arrayEach:file'`, `'arrayEach:fileSize:${string}'`, `'arrayEach:fileType:${string}'`
+
+**Custom Validators**:
+
+```tsx
+import { validator } from '@/hooks';
+
+const customRule = validator((value) => value !== 'forbidden', 'This value is not allowed');
+```
+
+### Example
+
+```tsx
+function ContactForm() {
+  const { data, setData, errors, validate, isDirty } = useFormState({
+    initialData: { name: '', email: '', age: 0 },
+    validationRules: {
+      name: ['required', 'minLength:2'],
+      email: ['required', 'email'],
+      age: ['required', 'number', 'min:18'],
+    },
+  });
+
+  const handleSubmit = () => {
+    if (validate()) {
+      console.log('Valid data:', data);
+    }
+  };
+
+  return (
+    <form>
+      <input value={data.name} onChange={(e) => setData('name', e.target.value)} />
+      {errors.name && <span>{errors.name}</span>}
+      <button onClick={handleSubmit}>Submit</button>
+    </form>
+  );
+}
+```
+
+**Notes**:
+
+- Zod v4 validation
+- Nested path support (dot notation)
+- File size: B, KB, MB, GB, TB
+- File type wildcards: `image/*`
+
+---
+
+## useKeyboard
+
+Keyboard event handling.
+
+### Signature
+
+```tsx
+function useKeyboard(options: {
+  allowRepeat?: boolean; // Default: false
+  enabled?: boolean; // Default: true
+  onArrowDown?: () => void;
+  onArrowUp?: () => void;
+  onEnter?: () => void;
+  onEscape?: () => void;
+  onTab?: () => void;
+}): void;
+```
+
+### Example
+
+```tsx
+function SearchBox() {
+  const [results, setResults] = useState([]);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useKeyboard({
+    onArrowDown: () => setSelectedIndex((i) => Math.min(i + 1, results.length - 1)),
+    onArrowUp: () => setSelectedIndex((i) => Math.max(i - 1, 0)),
+    onEnter: () => selectResult(results[selectedIndex]),
+    onEscape: () => closeResults(),
+  });
+
+  return <div>...</div>;
+}
+```
+
+**Notes**:
+
+- Document-level listeners
+- Prevents default for all keys except Tab
+- Key repeat control
+
+---
+
+## useOverflowDetection
+
+Detects overflow and hides overflowing elements.
+
+### Signature
+
+```tsx
+function useOverflowDetection(options?: {
+  selector?: string; // Default: '[data-ox-state="selected"]'
+}): {
+  overflowAmount: number; // Number of hidden items
+  checkOverflow: () => void;
+  handleResize: (node: HTMLDivElement | null) => () => void; // Ref callback with cleanup
+};
+```
+
+### Example
+
+```tsx
+function TagList({ tags }) {
+  const { overflowAmount, handleResize } = useOverflowDetection();
+
+  return (
+    <div ref={handleResize}>
+      {tags.map((tag) => (
+        <span key={tag} data-ox-state="selected">
+          {tag}
+        </span>
+      ))}
+      {overflowAmount > 0 && <span>+{overflowAmount} more</span>}
+    </div>
+  );
+}
+```
+
+**Notes**:
+
+- ResizeObserver integration
+- Automatically hides overflow from end
+- Returns hidden element count
+
+---
+
+## useScrollSpy
+
+Tracks active section based on scroll position using IntersectionObserver.
+
+### Signature
+
+```tsx
+function useScrollSpy(
+  sectionIds: string[], // Array of element IDs to observe
+  options?: UseScrollSpyOptions
+): UseScrollSpyReturn;
+
+interface UseScrollSpyOptions {
+  root?: Element | null; // Scroll container (default: viewport)
+  rootMargin?: string; // Margin around root (default: '0px')
+  threshold?: number | number[]; // Visibility threshold (default: 0)
+}
+
+interface UseScrollSpyReturn {
+  activeId: string; // Currently visible section ID
+  setActiveId: (id: string) => void; // Manually set active section
+}
+```
+
+### Example
+
+```tsx
+function TableOfContents() {
+  const sectionIds = ['intro', 'features', 'installation', 'api'];
+  const { activeId } = useScrollSpy(sectionIds, { rootMargin: '-100px 0px -50% 0px' });
+
+  return (
+    <nav>
+      {sectionIds.map((id) => (
+        <a key={id} href={`#${id}`} className={activeId === id ? 'active' : ''}>
+          {id}
+        </a>
+      ))}
+    </nav>
+  );
+}
+```
+
+**Notes**:
+
+- Uses IntersectionObserver for efficient scroll tracking
+- Automatically updates as user scrolls through sections
+- Commonly used with `OxPageOutline` component
+
+---
+
+## useSize
+
+Tracks element dimensions using ResizeObserver.
+
+### Signature
+
+```tsx
+function useSize(element: Element | null): Size | undefined;
+
+interface Size {
+  height: number;
+  width: number;
+}
+```
+
+### Example
+
+```tsx
+function ResponsiveComponent() {
+  const [ref, setRef] = useState<HTMLDivElement | null>(null);
+  const size = useSize(ref);
+
+  return (
+    <div ref={setRef}>
+      {size && (
+        <p>
+          Width: {size.width}px, Height: {size.height}px
+        </p>
+      )}
+      {size && size.width < 400 ? <CompactView /> : <FullView />}
+    </div>
+  );
+}
+```
+
+**Notes**:
+
+- Returns `undefined` when element is null
+- Updates automatically on resize
+- Values are rounded to nearest integer
+
+---
+
+## useTheme
+
+Theme management with localStorage persistence.
+
+**Export alias**: `useOxTheme`
+
+### Signature
+
+```tsx
+function useTheme(options?: UseThemeOptions): UseThemeReturn;
+
+type Theme = 'light' | 'dark';
+
+interface UseThemeOptions {
+  defaultTheme?: Theme; // Default: 'light'
+  storageKey?: string; // localStorage key (default: 'ox-theme')
+}
+
+interface UseThemeReturn {
+  setTheme: (theme: Theme) => void;
+  theme: Theme;
+  toggleTheme: () => void;
+}
+```
+
+### Example
+
+```tsx
+function ThemeToggle() {
+  const { theme, toggleTheme } = useTheme();
+
+  return <button onClick={toggleTheme}>{theme === 'light' ? '🌙' : '☀️'}</button>;
+}
+
+// With custom storage key
+const { theme, setTheme } = useTheme({
+  defaultTheme: 'dark',
+  storageKey: 'my-app-theme',
+});
+```
+
+**Notes**:
+
+- Persists theme preference to localStorage
+- Syncs across browser tabs
+- Respects system preference as initial default
+
+---
+
+# Route Guards (3)
+
+Factory functions that create typed route components bound to your auth hook.
+
+## Setup
+
+```tsx
+// src/lib/auth.ts - Create routes once with your auth hook
+import { createOxAuth } from '@noxickon/onyx/contexts';
+import {
+  createOxProtectedRoute,
+  createOxGuestRoute,
+  createOxRoleRoute,
+} from '@noxickon/onyx/routes';
+
+interface User {
+  id: string;
+  role: 'admin' | 'user' | 'moderator';
+}
+
+const { OxAuthProvider, useOxAuth } = createOxAuth<User>({
+  checks: { isAdmin: (u) => u?.role === 'admin' },
+});
+
+// Create typed route components
+export const OxProtectedRoute = createOxProtectedRoute(useOxAuth);
+export const OxGuestRoute = createOxGuestRoute(useOxAuth);
+export const OxRoleRoute = createOxRoleRoute(useOxAuth);
+export { OxAuthProvider, useOxAuth };
+```
+
+---
+
+## createOxGuestRoute
+
+Factory for routes accessible only to unauthenticated users (e.g., login, signup).
+
+### Props
+
+```tsx
+interface OxGuestRouteProps {
+  children: ReactNode; // Required - Shown when NOT authenticated
+  onAuthenticated?: ReactNode; // Fallback when authenticated
+  onLoading?: ReactNode; // Fallback during auth check
+}
+```
+
+### Example
+
+```tsx
+import { OxGuestRoute } from '@/lib/auth';
+
+<OxGuestRoute onLoading={<Spinner />} onAuthenticated={<Navigate to="/dashboard" />}>
+  <LoginPage />
+</OxGuestRoute>;
+```
+
+---
+
+## createOxProtectedRoute
+
+Factory for routes requiring authentication.
+
+### Props
+
+```tsx
+interface OxProtectedRouteProps {
+  children: ReactNode; // Required - Shown when authenticated
+  onLoading?: ReactNode; // Fallback during auth check
+  onUnauthenticated?: ReactNode; // Fallback when NOT authenticated
+}
+```
+
+### Example
+
+```tsx
+import { OxProtectedRoute } from '@/lib/auth';
+
+<OxProtectedRoute onLoading={<Spinner />} onUnauthenticated={<Navigate to="/login" />}>
+  <Dashboard />
+</OxProtectedRoute>;
+```
+
+---
+
+## createOxRoleRoute
+
+Factory for routes requiring specific user roles.
+
+### Props
+
+```tsx
+interface OxRoleRouteProps<T extends { role: string }> {
+  children: ReactNode; // Required - Shown when user has role
+  onLoading?: ReactNode; // Fallback during auth check
+  onUnauthorized?: ReactNode; // Fallback when unauthorized
+  roleExtractor?: (user: T) => string; // Default: (u) => u.role
+  roles?: string[]; // Default: ['admin'] - Allowed roles (OR logic)
+}
+```
+
+### Example
+
+```tsx
+import { OxRoleRoute } from '@/lib/auth';
+
+{
+  /* Admin only (default) */
+}
+<OxRoleRoute onUnauthorized={<AccessDenied />}>
+  <AdminPanel />
+</OxRoleRoute>;
+
+{
+  /* Admin or moderator */
+}
+<OxRoleRoute roles={['admin', 'moderator']} onUnauthorized={<AccessDenied />}>
+  <ModerationTools />
+</OxRoleRoute>;
+```
+
+**Notes**:
+
+- Factory pattern: no prop drilling, hook called internally
+- User type must have a `role` property (TypeScript enforced)
+- User must have at least ONE of the specified roles
+- Empty roles array always shows `onUnauthorized`
+- Default role: `'admin'`
+- Custom `roleExtractor` for nested role properties
+
+---
+
+# Utilities (9)
+
+## Builder
+
+URL and mailto link construction.
+
+### Functions
+
+```tsx
+// Build URL with query params
+function buildUrl(
+  path: string,
+  params?: Record<string, string | number | boolean | null | undefined>,
+  options?: {
+    baseUrl?: string;
+    fragment?: string; // Auto-prefixes with # if needed
+  }
+): string;
+
+// Build mailto link
+function buildMailTo(
+  email: string | string[],
+  options?: {
+    bcc?: string | string[];
+    body?: string;
+    cc?: string | string[];
+    subject?: string;
+  }
+): string;
+```
+
+### Example
+
+```tsx
+buildUrl(
+  '/api/users',
+  { id: 123, active: true },
+  {
+    baseUrl: 'https://api.example.com',
+    fragment: 'section-1',
+  }
+);
+// "https://api.example.com/api/users?id=123&active=true#section-1"
+
+buildMailTo(['john@example.com', 'jane@example.com'], {
+  subject: 'Meeting Request',
+  cc: 'manager@example.com',
+});
+// "mailto:john@example.com,jane@example.com?cc=manager@example.com&subject=Meeting+Request"
+```
+
+---
+
+## cn
+
+Tailwind CSS class name merging.
+
+### Function
+
+```tsx
+function cn(...inputs: ClassValue[]): string;
+```
+
+### Example
+
+```tsx
+cn('px-4 py-2', 'bg-blue-500', { 'text-white': isActive });
+// "px-4 py-2 bg-blue-500 text-white" (if isActive)
+
+cn('px-2', 'px-4');
+// "px-4" (tailwind-merge resolves conflicts)
+```
+
+---
+
+## copyToClipboard
+
+Cross-browser clipboard copying.
+
+### Function
+
+```tsx
+async function copyToClipboard(text: string): Promise<boolean>;
+```
+
+### Example
+
+```tsx
+const success = await copyToClipboard('Hello, World!');
+if (success) {
+  console.log('Copied!');
+}
+```
+
+**Notes**:
+
+- Modern Clipboard API with fallback
+- Never throws errors (returns false)
+- Requires HTTPS for modern API
+
+---
+
+## createId
+
+Unique ID generation.
+
+### Functions
+
+```tsx
+// Overloaded function
+function createId(): string;
+function createId(prefix: string): string;
+function createId(prefix: string, options: { length?: number; separator?: string }): string;
+function createId(options: { length?: number; separator?: string }): string;
+
+function generateRandomString(length: number): string;
+```
+
+### Example
+
+```tsx
+createId();
+// "ox_lz8k3xa1abc123de"
+
+createId('user');
+// "user_lz8k3xb2xyz456gh"
+
+createId('order', { length: 12, separator: '-' });
+// "order-lz8k3xc3abcdefgh1234"
+
+generateRandomString(8);
+// "x7k2m9p4"
+```
+
+**Notes**:
+
+- Format: `{prefix}{separator}{timestamp}{counter}{randomString}`
+- Default prefix: `'ox'`, separator: `'_'`, length: `8`
+- Uses crypto.getRandomValues when available
+
+---
+
+## errorHelper
+
+GraphQL and form error handling.
+
+### Functions
+
+```tsx
+function parseGraphQLErrors(errors: OxGraphQLError[]): OxParsedError[];
+
+function handleFormErrors(errors: OxParsedError[], formState: OxFormState): void;
+
+function handleGraphQLFormErrors(errors: OxGraphQLError[], formState: OxFormState): void;
+```
+
+### Example
+
+```tsx
+const graphqlErrors = [
+  {
+    message: 'Invalid email',
+    extensions: { code: 'VALIDATION_ERROR', field: 'email' },
+  },
+];
+
+const parsed = parseGraphQLErrors(graphqlErrors);
+// [{ message: 'Invalid email', code: 'VALIDATION_ERROR', field: 'email' }]
+
+handleFormErrors(parsed, formState);
+// Calls formState.setError('email', 'Invalid email')
+
+// Or combined:
+handleGraphQLFormErrors(graphqlErrors, formState);
+```
+
+---
+
+## formatter
+
+Data formatting utilities.
+
+### Functions
+
+```tsx
+// Bytes to human-readable
+function formatBytes(
+  bytes: number,
+  options?: {
+    binary?: boolean; // Use 1024 base (default: false)
+    decimals?: number; // Default: 1
+    locale?: string; // Default: 'en-US'
+  }
+): string;
+
+// Currency formatting
+function formatCurrency(
+  amount: number,
+  options?: {
+    currency?: string; // Default: 'USD'
+    locale?: string; // Default: 'en-US'
+  }
+): string;
+
+// Date formatting
+function formatDate(
+  date: Date | string | number,
+  options?: {
+    format?: 'short' | 'medium' | 'long' | 'full'; // Default: 'medium'
+    locale?: string; // Default: 'en-US'
+  }
+): string;
+
+// Number formatting
+function formatNumber(
+  number: number,
+  options?: {
+    compact?: boolean; // Compact notation (e.g., 1.2K)
+    decimals?: number; // Default: 2
+    locale?: string; // Default: 'en-US'
+  }
+): string;
+
+// Relative time
+function formatTimestamp(date: Date): string;
+```
+
+### Example
+
+```tsx
+formatBytes(1234567);
+// "1.2 MB"
+
+formatCurrency(1234.56, { currency: 'EUR', locale: 'de-DE' });
+// "1.234,56 €"
+
+formatDate(new Date('2024-01-15'), { format: 'long' });
+// "January 15, 2024"
+
+formatNumber(1234567, { compact: true });
+// "1.23M"
+
+formatTimestamp(new Date(Date.now() - 5 * 60 * 1000));
+// "5m ago"
+```
+
+---
+
+## hasDataSlot
+
+React slot validation type guard.
+
+### Function
+
+```tsx
+function hasDataSlot(
+  element: React.ReactNode,
+  slot: string
+): element is React.ReactElement<{ 'data-ox-slot': string }>;
+```
+
+### Example
+
+```tsx
+const children = [
+  <div data-ox-slot="header">Header</div>,
+  <div data-ox-slot="content">Content</div>,
+];
+
+const headerSlot = children.find((child) => hasDataSlot(child, 'header'));
+// TypeScript knows headerSlot has data-ox-slot prop
+```
+
+**Notes**:
+
+- Type guard for TypeScript narrowing
+- Validates React element and slot attribute
+
+---
+
+## scrollToElement
+
+Promise-based smooth scrolling.
+
+### Function
+
+```tsx
+function scrollToElement(
+  target: string | Element,
+  options?: {
+    behavior?: 'smooth' | 'instant' | 'auto';
+    block?: 'start' | 'center' | 'end' | 'nearest';
+    inline?: 'start' | 'center' | 'end' | 'nearest';
+    offset?: number; // Pixels from element position
+    timeout?: number; // Default: 5000ms
+  }
+): Promise<void>;
+```
+
+### Example
+
+```tsx
+await scrollToElement('#my-section');
+await scrollToElement('.target', { offset: -100 }); // 100px above
+await scrollToElement(element, { behavior: 'smooth', block: 'center' });
+```
+
+**Notes**:
+
+- Smart selector parsing
+- Promise resolves when scroll completes
+- Rejects if element not found or timeout
+
+---
+
+## validation
+
+Input validation utilities.
+
+### Functions
+
+```tsx
+// Email validation
+function validateEmail(
+  email: string,
+  options?: {
+    allowLocalhost?: boolean;
+    requireTld?: boolean; // Default: true
+  }
+): boolean;
+
+// URL validation
+function validateUrl(
+  url: string,
+  options?: {
+    allowLocalhost?: boolean; // Default: false (blocks 127.0.0.1, 192.168.x.x, etc.)
+    protocols?: string[]; // Default: ['http:', 'https:']
+    requireProtocol?: boolean; // Default: false (auto-adds https://)
+  }
+): boolean;
+
+// Phone validation
+function validatePhone(
+  phone: string,
+  options?: {
+    allowedCountries?: string[]; // e.g., ['US', 'CA', 'UK']
+    strict?: boolean; // Default: false (requires E.164 format with +)
+  }
+): boolean;
+```
+
+### Example
+
+```tsx
+validateEmail('user@example.com');
+// true
+
+validateUrl('https://example.com');
+// true
+
+validateUrl('example.com', { requireProtocol: false });
+// true (auto-adds https://)
+
+validatePhone('+14155552671');
+// true
+
+validatePhone('(415) 555-2671');
+// true (non-strict mode)
+
+validatePhone('+14155552671', { strict: true });
+// true
+
+validatePhone('(415) 555-2671', { strict: true });
+// false (strict requires E.164)
+
+validatePhone('+14155552671', { allowedCountries: ['US', 'CA'] });
+// true
+```
+
+**Notes**:
+
+- Email: RFC 5321 compliant, max 254 chars
+- URL: Max 2083 chars (IE compatibility)
+- Phone: Supports 50+ country codes, 7-15 digits
+- Phone strict mode: E.164 format (+prefix, no formatting)
+
+---
+
+# Common Patterns
+
+## asChild 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.
+
+**Components with asChild**:
+
+- `OxBreadcrumb.Link`
+- `OxButton`
+- `OxDropdown.Trigger`
+- `OxFloating.Trigger` _(deprecated - use OxPopper.Anchor)_
+- `OxHoverCard.Trigger`
+- `OxLink`
+- `OxPagination.Link`, `OxPagination.Next`, `OxPagination.Previous`
+- `OxPopover.Trigger`
+
+**Example**:
+
+```tsx
+{
+  /* Render as Next.js Link while keeping button styling */
+}
+<OxButton asChild variant="primary">
+  <Link to="/dashboard">Dashboard</Link>
+</OxButton>;
+```
+
+---
+
+## Compound Components
+
+Components using the compound pattern provide sub-components accessed via dot notation. This allows flexible composition while maintaining type safety.
+
+**Compound Components**:
+
+- UI: Accordion, Alert, Breadcrumb, Card, DescriptionList, Dialog, Drawer, Dropdown, Floating, Icon, JsonField, Notifications, Pagination, Popover, Progress, Stepper, Table, Tabs, Timeline, Toggle
+- Forms: Checkbox, FileUpload, Form, Input (all variants), Radio, Select
+- Layouts: MainContent, Sidebar (+ Menu, Group)
+- Typography: (simple components)
+
+---
+
+## Controlled vs Uncontrolled
+
+Many components support both controlled and uncontrolled modes:
+
+**Controlled** (parent manages state):
+
+```tsx
+<OxSlider value={value} onChange={setValue} />
+```
+
+**Uncontrolled** (component manages state):
+
+```tsx
+<OxSlider defaultValue={50} />
+```
+
+**Components**:
+
+- Accordion, Dialog, Drawer, Dropdown, Floating, Popover, Slider, Tabs, Toggle
+
+---
+
+## Loading States
+
+Components with built-in loading states:
+
+- Avatar (`isLoading`, `skeleton`)
+- Button (`isLoading`)
+- Card (`isLoading`)
+- Select (`isLoading`)
+- Table (`isLoading` with skeleton rows)
+
+---
+
+## Validation
+
+Form components support validation via `useFormState` hook:
+
+**Built-in Rules**: `'required'`, `'email'`, `'url'`, `'min:N'`, `'max:N'`, `'minLength:N'`, `'maxLength:N'`, `'pattern:regex'`, `'fileSize:5MB'`, `'fileType:image/*'`
+
+**Example**:
+
+```tsx
+const { data, errors, validate } = useFormState({
+  initialData: { email: '' },
+  validationRules: {
+    email: ['required', 'email'],
+  },
+});
+```
+
+---
+
+## Color Customization
+
+Components accepting `ColorStyleName`:
+
+- Tag, Card, Icon.Box, Progress, Skeleton, Spinner, Stepper, Timeline
+
+**Available Colors**: purple, lime, red, yellow, green, blue, indigo, pink, amber, emerald, teal, cyan, sky, violet, fuchsia, orange, rose, gray
+
+---
+
+## Size Variants
+
+Common size props:
+
+- **XS-3XL**: Avatar, Icon, Spinner (`'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'`)
+- **SM-LG**: Button, Link, Toggle (`'sm' | 'md' | 'lg'`)
+- **SM-XL**: Dialog (`'sm' | 'md' | 'lg' | 'xl'`)
+
+---
+
+# Best Practices
+
+## Import Optimization
+
+Use specific imports for better tree-shaking:
+
+```tsx
+// Good - specific imports
+import { OxButton, OxCard } from '@noxickon/onyx';
+import { useForm } from '@noxickon/onyx/hooks';
+
+// Avoid - barrel imports everything
+import * as Onyx from '@noxickon/onyx';
+```
+
+## Form Handling
+
+Use `useForm` for GraphQL forms, `useFormState` for local forms:
+
+```tsx
+// GraphQL form
+const { data, submit, errors } = useForm({
+  operation: CREATE_USER_MUTATION,
+  initialData: { name: '', email: '' },
+  validationRules: { email: ['required', 'email'] },
+});
+
+// Local form
+const { data, validate } = useFormState({
+  initialData: { search: '' },
+  validationRules: { search: ['minLength:3'] },
+});
+```
+
+## Route Protection
+
+Layer route guards for complex authorization (routes created via factory pattern):
+
+```tsx
+// Import from your auth setup file
+import { OxProtectedRoute, OxGuestRoute, OxRoleRoute } from '@/lib/auth';
+
+{
+  /* Guest route wrapping protected content */
+}
+<OxGuestRoute onAuthenticated={<Navigate to="/dashboard" />}>
+  <LoginPage />
+</OxGuestRoute>;
+
+{
+  /* Protected route with role guard */
+}
+<OxProtectedRoute onUnauthenticated={<Navigate to="/login" />}>
+  <OxRoleRoute roles={['admin', 'moderator']} onUnauthorized={<AccessDenied />}>
+    <AdminPanel />
+  </OxRoleRoute>
+</OxProtectedRoute>;
+```
+
+## Accessibility
+
+All components are WCAG compliant. Ensure proper labels and ARIA attributes:
+
+```tsx
+<OxForm.Field>
+  <OxForm.Label htmlFor="email" required>
+    Email
+  </OxForm.Label>
+  <input id="email" aria-describedby="email-description email-error" />
+  <OxForm.Description id="email-description">Your email address</OxForm.Description>
+  <OxForm.Error id="email-error">Email is required</OxForm.Error>
+</OxForm.Field>
+```
+
+---
+
+# Type Definitions
+
+## Common Types
+
+```tsx
+// Lucide icon type
+import type { LucideIcon } from 'lucide-react';
+
+// Color names from theme
+type ColorStyleName =
+  | 'purple'
+  | 'lime'
+  | 'red'
+  | 'yellow'
+  | 'green'
+  | 'blue'
+  | 'indigo'
+  | 'pink'
+  | 'amber'
+  | 'emerald'
+  | 'teal'
+  | 'cyan'
+  | 'sky'
+  | 'violet'
+  | 'fuchsia'
+  | 'orange'
+  | 'rose'
+  | 'gray';
+
+type StatusType = 'default' | 'info' | 'success' | 'warning' | 'error';
+
+// Validation errors
+type ValidationErrors = Record<string, string | string[]>;
+type ValidationError = string | string[];
+
+// Form state
+interface OxFormState {
+  setError: (field: string, error: string | string[]) => void;
+}
+
+// AuthContext uses generics - define your own user type
+// See OxAuthContext section for examples
+```
+
+---
+
+# Maintenance Guide
+
+## For Library Maintainers
+
+This AI-README.md serves as the **single source of truth** for external API documentation. Update it whenever you make changes to the public API.
+
+### When to Update
+
+Update this document when:
+
+- ✅ Adding/removing a component, hook, or utility
+- ✅ Changing public props or API signatures
+- ✅ Modifying component behavior or usage patterns
+- ✅ Releasing a new version
+
+Do NOT update for:
+
+- ❌ Internal refactoring without API changes
+- ❌ Documentation typo fixes (unless they affect accuracy)
+- ❌ Build/test configuration changes
+
+### Update Workflow
+
+1. **Make code changes** in the source files.
+2. **Update AI-README.md** immediately:
+   - Update affected component/hook sections.
+   - Update the version header (date, version if applicable, commit after commit).
+3. **Verify accuracy** by comparing with actual type definitions.
+4. **Commit together** with code changes.
+
+### Version Header Maintenance
+
+After making changes:
+
+```bash
+# Update the header manually:
+# Version: Check package.json "version" field
+# Updated: Today's date (YYYY-MM-DD format)
+# Built from: Run `git rev-parse --short HEAD` after committing
+```
+
+### Structure Consistency
+
+Every component should follow this pattern:
+
+````markdown
+## OxComponentName
+
+Brief one-line description.
+
+**Pattern**: Standalone | Compound Component  
+**Sub-components**: `SubComp1`, `SubComp2` (if compound)
+
+### Props
+
+```tsx
+interface OxComponentNameProps {
+  // Full TypeScript interface
+}
+```
+````
+
+### Example
+
+```tsx
+<OxComponentName prop="value">Content</OxComponentName>
+```
+
+```
+
+---
+
+### Quality Checklist
+
+Before releasing:
+- Version header matches package.json
+- All new components documented
+- All examples tested and accurate
+- TypeScript interfaces match source code
+- No internal file paths exposed
+- Only Ox-prefixed exports documented
+
+---
+
+This AI-README provides comprehensive reference documentation for all Onyx components, hooks, contexts, utilities, and patterns. All information is extracted from the actual source code with accurate prop definitions and usage examples.
+```