@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/resizable.tsx

@@ -5,68 +5,209 @@ import * as ResizablePrimitive from "react-resizable-panels";
 import { cn } from "@/lib/utils";
 
 /**
- * Container for creating resizable panel groups with keyboard accessibility
+ * Props for ResizablePanelGroup component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace react-resizable-panels inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ResizablePanelGroupDocsProps = {
+  /** Layout direction for panels within the group */
+  direction: "horizontal" | "vertical";
+  /** Optional identifier for automatic save/restore of panel layouts @default undefined */
+  autoSaveId?: string | null;
+  /** Unique identifier for the panel group @default undefined */
+  id?: string | null;
+  /** Keyboard resize increment in percentage points @default undefined */
+  keyboardResizeBy?: number | null;
+  /** Callback fired when panel layout changes with array of panel sizes */
+  onLayout?: (layout: number[]) => void;
+  /** Custom storage implementation for persisting panel layouts @default localStorage */
+  storage?: {
+    getItem(name: string): string | null;
+    setItem(name: string, value: string): void;
+  };
+  /** Text direction for RTL/LTR layout support @default "ltr" */
+  dir?: "auto" | "ltr" | "rtl";
+  /** HTML element tag name to render @default "div" */
+  tagName?: keyof React.JSX.IntrinsicElements;
+  /** Additional CSS classes */
+  className?: string;
+  /** Inline styles for the panel group */
+  style?: React.CSSProperties;
+  /** Child components - should contain ResizablePanel and ResizableHandle components */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for ResizablePanel component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace react-resizable-panels inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ResizablePanelDocsProps = {
+  /** Unique identifier for the panel - required for conditional rendering @default undefined */
+  id?: string;
+  /** Display order within the panel group - important for conditional rendering @default undefined */
+  order?: number;
+  /** Initial size as percentage (0-100) when panel is first rendered @default undefined */
+  defaultSize?: number;
+  /** Minimum size constraint as percentage (0-100) @default undefined */
+  minSize?: number;
+  /** Maximum size constraint as percentage (0-100) @default undefined */
+  maxSize?: number;
+  /** Whether panel can be collapsed to zero or collapsedSize @default false */
+  collapsible?: boolean;
+  /** Size when collapsed - must be between 0 and minSize @default 0 */
+  collapsedSize?: number;
+  /** Callback fired when panel is collapsed to its minimum size */
+  onCollapse?: () => void;
+  /** Callback fired when panel is expanded from collapsed state */
+  onExpand?: () => void;
+  /** Callback fired when panel is resized with current and previous sizes */
+  onResize?: (size: number, prevSize: number | undefined) => void;
+  /** HTML element tag name to render @default "div" */
+  tagName?: keyof React.JSX.IntrinsicElements;
+  /** Additional CSS classes */
+  className?: string;
+  /** Inline styles for the panel */
+  style?: React.CSSProperties;
+  /** Panel content */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for ResizableHandle component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace react-resizable-panels inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ResizableHandleDocsProps = {
+  /** Whether to show a visual grip handle @default false */
+  withHandle?: boolean;
+  /** Unique identifier for the resize handle @default undefined */
+  id?: string | null;
+  /** Whether the handle is disabled and non-interactive @default false */
+  disabled?: boolean;
+  /** Custom hit area margins for easier interaction @default { coarse: 15, fine: 5 } */
+  hitAreaMargins?: {
+    coarse: number;
+    fine: number;
+  };
+  /** Callback fired when dragging state changes */
+  onDragging?: (isDragging: boolean) => void;
+  /** Callback fired when handle loses focus */
+  onBlur?: () => void;
+  /** Callback fired when handle is clicked */
+  onClick?: () => void;
+  /** Callback fired when handle gains focus */
+  onFocus?: () => void;
+  /** Callback fired when pointer is pressed down on handle */
+  onPointerDown?: () => void;
+  /** Callback fired when pointer is released from handle */
+  onPointerUp?: () => void;
+  /** Tab index for keyboard navigation @default 0 */
+  tabIndex?: number;
+  /** HTML element tag name to render @default "div" */
+  tagName?: keyof React.JSX.IntrinsicElements;
+  /** Additional CSS classes */
+  className?: string;
+  /** Inline styles for the handle */
+  style?: React.CSSProperties;
+  /** Custom handle content - overrides withHandle prop */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Container for creating resizable panel groups with full keyboard accessibility
  *
- * ResizablePanelGroup provides a flexible container for organizing multiple resizable panels.
- * Panels can be resized by dragging handles between them, with full keyboard support.
- * Built on top of react-resizable-panels with enhanced styling and accessibility features.
+ * ResizablePanelGroup provides a flexible container for organizing multiple resizable panels
+ * that can be resized by dragging handles between them or using keyboard navigation.
+ * Built on react-resizable-panels with enhanced styling, accessibility, and persistence features.
+ * Supports both horizontal and vertical layouts with automatic layout saving and restoration.
  *
  * @example
  * ```tsx
  * // Basic horizontal layout
  * <ResizablePanelGroup direction="horizontal" className="h-full">
  *   <ResizablePanel defaultSize={50}>
- *     <div className="p-4">Left panel</div>
+ *     <div className="p-4">Left panel content</div>
  *   </ResizablePanel>
  *   <ResizableHandle />
  *   <ResizablePanel defaultSize={50}>
- *     <div className="p-4">Right panel</div>
+ *     <div className="p-4">Right panel content</div>
  *   </ResizablePanel>
  * </ResizablePanelGroup>
  * ```
  *
  * @example
  * ```tsx
- * // Vertical layout with handle
+ * // Vertical layout with visual handles
  * <ResizablePanelGroup direction="vertical" className="min-h-[400px]">
  *   <ResizablePanel defaultSize={30}>
- *     <header>Header content</header>
+ *     <header className="p-4">Header content</header>
  *   </ResizablePanel>
  *   <ResizableHandle withHandle />
  *   <ResizablePanel defaultSize={70}>
- *     <main>Main content</main>
+ *     <main className="p-4">Main content area</main>
  *   </ResizablePanel>
  * </ResizablePanelGroup>
  * ```
  *
  * @example
  * ```tsx
- * // Complex layout with size constraints
- * <ResizablePanelGroup direction="horizontal">
+ * // Persistent layout with auto-save
+ * <ResizablePanelGroup
+ *   direction="horizontal"
+ *   autoSaveId="main-layout"
+ *   onLayout={(sizes) => console.log('Layout changed:', sizes)}
+ * >
  *   <ResizablePanel defaultSize={25} minSize={20} maxSize={40}>
  *     <nav>Sidebar (20-40%)</nav>
  *   </ResizablePanel>
  *   <ResizableHandle withHandle />
  *   <ResizablePanel defaultSize={75} minSize={60}>
- *     <main>Content (min 60%)</main>
+ *     <main>Content area (min 60%)</main>
+ *   </ResizablePanel>
+ * </ResizablePanelGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom keyboard resize increment
+ * <ResizablePanelGroup
+ *   direction="horizontal"
+ *   keyboardResizeBy={5}
+ *   dir="ltr"
+ * >
+ *   <ResizablePanel defaultSize={50} id="left-panel">
+ *     <div>Panel content</div>
+ *   </ResizablePanel>
+ *   <ResizableHandle />
+ *   <ResizablePanel defaultSize={50} id="right-panel">
+ *     <div>Panel content</div>
  *   </ResizablePanel>
  * </ResizablePanelGroup>
  * ```
  *
- * @param direction - Layout direction: "horizontal" or "vertical"
- * @param className - Additional CSS classes
+ * @param direction - Layout direction: "horizontal" for side-by-side, "vertical" for top-to-bottom
+ * @param autoSaveId - Unique identifier for automatically saving/restoring panel layouts
+ * @param onLayout - Callback fired when panel sizes change, receives array of percentages
+ * @param keyboardResizeBy - Increment in percentage points for keyboard-based resizing
+ * @param storage - Custom storage implementation for layout persistence (defaults to localStorage)
+ * @param dir - Text direction for RTL/LTR layout support
+ * @param className - Additional CSS classes for custom styling
  * @param children - ResizablePanel and ResizableHandle components
  *
  * @accessibility
- * - Full keyboard navigation with arrow keys when handles are focused
- * - Screen reader support with proper ARIA labels
- * - Respects prefers-reduced-motion for users with motion sensitivity
- * - Maintains focus management during resize operations
+ * - Full keyboard navigation: Arrow keys resize panels when handles are focused
+ * - Screen reader announcements for panel size changes and resize operations
+ * - Respects prefers-reduced-motion to disable animations for motion-sensitive users
+ * - Maintains logical focus order and proper tab navigation
+ * - Provides ARIA labels and roles for assistive technology
+ * - Keyboard shortcuts: Home/End keys jump to min/max sizes
  *
- * @see {@link https://ui.shadcn.com/docs/components/resizable} for design patterns
+ * @see {@link https://react-resizable-panels.vercel.app/} Official react-resizable-panels documentation
+ * @see {@link https://ui.shadcn.com/docs/components/resizable} Design patterns and examples
+ * @see {@link ResizablePanel} Individual panel configuration options
+ * @see {@link ResizableHandle} Handle customization and interaction options
  * @since 1.0.0
- * @see {@link ResizablePanel} for individual panel configuration
- * @see {@link ResizableHandle} for handle customization options
  */
 function ResizablePanelGroup({
   className,
@@ -85,11 +226,12 @@ function ResizablePanelGroup({
 }
 
 /**
- * Individual resizable panel within a panel group
+ * Individual resizable panel within a panel group with size constraints and callbacks
  *
- * ResizablePanel represents a single section that can be resized within a ResizablePanelGroup.
- * Supports size constraints, default sizing, and programmatic control. Each panel automatically
- * handles overflow and maintains content accessibility during resize operations.
+ * ResizablePanel represents a single resizable section within a ResizablePanelGroup.
+ * Supports flexible sizing constraints, collapse/expand behavior, and programmatic control
+ * through imperative API. Each panel automatically handles content overflow and maintains
+ * accessibility during resize operations with proper focus and scroll management.
  *
  * @example
  * ```tsx
@@ -101,31 +243,78 @@ function ResizablePanelGroup({
  *
  * @example
  * ```tsx
- * // Panel with size constraints
+ * // Panel with size constraints and callbacks
  * <ResizablePanel
+ *   id="sidebar"
  *   defaultSize={30}
  *   minSize={20}
  *   maxSize={60}
  *   collapsible
+ *   onCollapse={() => console.log('Sidebar collapsed')}
+ *   onExpand={() => console.log('Sidebar expanded')}
+ *   onResize={(size, prevSize) => console.log(`Resized from ${prevSize}% to ${size}%`)}
+ * >
+ *   <aside className="p-4">Collapsible sidebar content</aside>
+ * </ResizablePanel>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Panel with conditional rendering support
+ * <ResizablePanel
+ *   id="dynamic-panel"
+ *   order={1}
+ *   defaultSize={40}
+ *   collapsible
+ *   collapsedSize={5}
  * >
- *   <aside>Collapsible sidebar</aside>
+ *   {isExpanded ? <FullContent /> : <CollapsedView />}
  * </ResizablePanel>
  * ```
  *
- * @param defaultSize - Initial size as percentage (0-100)
- * @param minSize - Minimum size as percentage
- * @param maxSize - Maximum size as percentage
- * @param collapsible - Whether panel can be collapsed to zero size
- * @param order - Display order within the group
- * @param id - Unique identifier for programmatic control
- * @param onCollapse - Callback when panel is collapsed
- * @param onExpand - Callback when panel is expanded
- * @param onResize - Callback when panel size changes
+ * @example
+ * ```tsx
+ * // Panel with imperative control via ref
+ * function PanelWithControl() {
+ *   const panelRef = useRef<ImperativePanelHandle>(null);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => panelRef.current?.collapse()}>
+ *         Collapse Panel
+ *       </button>
+ *       <ResizablePanel ref={panelRef} defaultSize={50} collapsible>
+ *         <div>Controlled panel content</div>
+ *       </ResizablePanel>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param id - Unique identifier for programmatic control and conditional rendering
+ * @param order - Display order within group, important when panels are conditionally rendered
+ * @param defaultSize - Initial size as percentage (0-100) when panel first mounts
+ * @param minSize - Minimum size constraint as percentage (0-100)
+ * @param maxSize - Maximum size constraint as percentage (0-100)
+ * @param collapsible - Whether panel can collapse beyond minSize to collapsedSize
+ * @param collapsedSize - Size when fully collapsed, must be between 0 and minSize
+ * @param onCollapse - Callback fired when panel collapses to minimum size
+ * @param onExpand - Callback fired when panel expands from collapsed state
+ * @param onResize - Callback fired during resize with current and previous sizes
+ * @param className - Additional CSS classes for custom styling
+ * @param children - Panel content elements
  *
  * @accessibility
- * - Maintains focus within panel during resize
- * - Preserves scroll position when possible
- * - Announces size changes to screen readers when significant
+ * - Preserves focus within panel content during resize operations
+ * - Maintains scroll position when panel dimensions change
+ * - Announces significant size changes to screen readers
+ * - Supports keyboard navigation when combined with ResizableHandle
+ * - Respects reduced motion preferences for smooth resize animations
+ *
+ * @see {@link https://react-resizable-panels.vercel.app/} API documentation and examples
+ * @see {@link ResizablePanelGroup} Container component for panel organization
+ * @see {@link ResizableHandle} Interactive handles for resizing panels
+ * @since 1.0.0
  */
 function ResizablePanel({
   ...props
@@ -134,15 +323,16 @@ function ResizablePanel({
 }
 
 /**
- * Draggable handle for resizing panels with optional visual indicator
+ * Interactive handle for resizing panels with full keyboard and pointer support
  *
- * ResizableHandle provides the interactive area between panels that allows users to
- * resize them via mouse, touch, or keyboard. The handle can display an optional
- * visual grip indicator for improved usability and accessibility.
+ * ResizableHandle provides the draggable area between panels that allows users to
+ * resize them via mouse, touch, or keyboard interaction. Supports optional visual
+ * grip indicators, custom hit areas, and comprehensive event callbacks for advanced
+ * interaction patterns. Automatically adapts styling based on panel group direction.
  *
  * @example
  * ```tsx
- * // Basic invisible handle
+ * // Basic invisible handle (common for clean designs)
  * <ResizableHandle />
  * ```
  *
@@ -154,40 +344,76 @@ function ResizablePanel({
  *
  * @example
  * ```tsx
- * // Custom styled handle
+ * // Custom styled handle with interaction callbacks
  * <ResizableHandle
  *   withHandle
- *   className="bg-blue-200 hover:bg-blue-300"
+ *   className="bg-blue-200 hover:bg-blue-300 transition-colors"
+ *   onDragging={(isDragging) => {
+ *     console.log(isDragging ? 'Started dragging' : 'Stopped dragging');
+ *   }}
+ *   hitAreaMargins={{ coarse: 20, fine: 10 }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled handle for non-interactive layouts
+ * <ResizableHandle
+ *   disabled
+ *   className="opacity-50 cursor-not-allowed"
  * />
  * ```
  *
- * @param withHandle - Whether to display visual grip indicator
- * @param className - Additional CSS classes for styling
- * @param disabled - Whether the handle is disabled
- * @param hitAreaMargins - Margins around the hit area for easier interaction
- * @param onDragging - Callback during drag operations
+ * @example
+ * ```tsx
+ * // Custom handle with event handling
+ * <ResizableHandle
+ *   id="main-handle"
+ *   onFocus={() => console.log('Handle focused')}
+ *   onBlur={() => console.log('Handle blurred')}
+ *   onClick={() => console.log('Handle clicked')}
+ *   tabIndex={0}
+ * >
+ *   <CustomGripIcon />
+ * </ResizableHandle>
+ * ```
+ *
+ * @param withHandle - Whether to display built-in visual grip indicator
+ * @param id - Unique identifier for the resize handle
+ * @param disabled - Whether handle is disabled and non-interactive
+ * @param hitAreaMargins - Custom hit area margins for easier grabbing (coarse: touch devices, fine: mouse)
+ * @param onDragging - Callback fired when drag state changes with boolean indicating if currently dragging
+ * @param onFocus - Callback fired when handle receives keyboard focus
+ * @param onBlur - Callback fired when handle loses keyboard focus
+ * @param onClick - Callback fired when handle is clicked
+ * @param onPointerDown - Callback fired when pointer/touch starts on handle
+ * @param onPointerUp - Callback fired when pointer/touch ends on handle
+ * @param tabIndex - Tab order for keyboard navigation (0 makes it focusable)
+ * @param className - Additional CSS classes for custom styling
+ * @param children - Custom handle content (overrides withHandle prop)
  *
  * @accessibility
- * - Keyboard resizable using arrow keys when focused
+ * - Full keyboard support: Arrow keys resize panels when handle is focused
  * - Proper ARIA roles and labels for screen readers
- * - Focus indicators that meet WCAG contrast requirements
- * - Touch-friendly hit area of at least 44x44px
- * - Announces resize actions and current sizes to assistive technology
+ * - High contrast focus indicators that meet WCAG AAA requirements
+ * - Touch-friendly hit area with minimum 44x44px interactive zone
+ * - Announces resize actions and panel sizes to assistive technology
+ * - Supports reduced motion preferences for drag animations
+ * - Maintains logical tab order within panel layouts
  *
- * @see {@link https://ui.shadcn.com/docs/components/resizable} for usage examples
+ * @see {@link https://react-resizable-panels.vercel.app/} Interactive demos and API reference
+ * @see {@link https://ui.shadcn.com/docs/components/resizable} Design patterns and styling examples
+ * @see {@link ResizablePanelGroup} Container component for handle placement
+ * @see {@link ResizablePanel} Panels that handles resize between
  * @since 1.0.0
  */
 function ResizableHandle({
   withHandle,
   className,
   ...props
-}: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & {
-  /**
-   * Whether to show a visual grip handle
-   * @default false
-   */
-  withHandle?: boolean;
-}) {
+}: { withHandle?: boolean } & React.ComponentProps<
+  typeof ResizablePrimitive.PanelResizeHandle
+>) {
   return (
     <ResizablePrimitive.PanelResizeHandle
       data-slot="resizable-handle"