@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/tooltip.tsx

@@ -3,14 +3,102 @@ import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 
 import { cn } from "@/lib/utils";
 
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TooltipProviderDocsProps = {
+  /** Time in milliseconds to wait before showing tooltip when hovering over trigger @default 700 */
+  delayDuration?: number;
+  /** Time in milliseconds to wait before showing tooltip when moving between tooltips @default 300 */
+  skipDelayDuration?: number;
+  /** Disable hoverable content behavior for WCAG 2.1 compliance @default false */
+  disableHoverableContent?: boolean;
+  /** React children to wrap with tooltip context */
+  children?: React.ReactNode;
+};
+
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TooltipDocsProps = {
+  /** Whether tooltip is open by default in uncontrolled mode @default false */
+  defaultOpen?: boolean;
+  /** Control tooltip open state in controlled mode */
+  open?: boolean;
+  /** Callback fired when tooltip open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Override global delay duration for this specific tooltip @default 700 */
+  delayDuration?: number;
+  /** Disable hoverable content behavior for this specific tooltip @default false */
+  disableHoverableContent?: boolean;
+  /** React children containing trigger and content elements */
+  children?: React.ReactNode;
+};
+
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TooltipTriggerDocsProps = {
+  /** Merge props with child element instead of rendering wrapper @default false */
+  asChild?: boolean;
+  /** React children - the element that triggers tooltip display */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLButtonElement>;
+
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TooltipContentDocsProps = {
+  /** Merge props with child element instead of rendering wrapper @default false */
+  asChild?: boolean;
+  /** Accessible label for tooltip content when no visible text */
+  "aria-label"?: string;
+  /** Callback fired when escape key is pressed */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /** Callback fired when pointer down occurs outside tooltip */
+  onPointerDownOutside?: (event: PointerEvent) => void;
+  /** Force mount content even when not open for animation purposes @default false */
+  forceMount?: boolean;
+  /** Preferred side of trigger to display tooltip @default "top" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** Distance in pixels from trigger element @default 0 */
+  sideOffset?: number;
+  /** Alignment relative to trigger element @default "center" */
+  align?: "start" | "center" | "end";
+  /** Offset in pixels from aligned position @default 0 */
+  alignOffset?: number;
+  /** Enable collision detection to keep tooltip in viewport @default true */
+  avoidCollisions?: boolean;
+  /** Element or elements to check for collisions against */
+  collisionBoundary?: Element | Element[];
+  /** Padding in pixels from collision boundary edges */
+  collisionPadding?:
+    | number
+    | { top?: number; right?: number; bottom?: number; left?: number };
+  /** Padding in pixels between arrow and content edges @default 0 */
+  arrowPadding?: number;
+  /** Sticky positioning behavior @default "partial" */
+  sticky?: "partial" | "always";
+  /** Hide tooltip when trigger becomes fully occluded @default false */
+  hideWhenDetached?: boolean;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** React children - content to display in tooltip */
+  children?: React.ReactNode;
+};
+
+// eslint-disable-next-line unused-imports/no-unused-vars
+type TooltipPortalDocsProps = {
+  /** Force mount portal content even when not open @default false */
+  forceMount?: boolean;
+  /** Container element to portal content into @default document.body */
+  container?: HTMLElement;
+  /** React children to render in portal */
+  children?: React.ReactNode;
+};
+
 /**
  * TooltipProvider - Global context provider for tooltip functionality
  *
  * Wraps your application or component tree to enable tooltip functionality.
  * Controls global tooltip behavior such as delay duration before showing tooltips.
- * Required for tooltip components to function properly.
+ * Required for tooltip components to function properly across your app.
  *
- * @param delayDuration - Time in milliseconds to wait before showing tooltip (default: 0)
+ * The provider manages global settings that affect all tooltips within its tree,
+ * including timing behavior and accessibility features. Individual tooltips can
+ * override these settings as needed.
  *
  * @example
  * ```tsx
@@ -22,17 +110,35 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // With custom delay
- * <TooltipProvider delayDuration={700}>
+ * // With custom delay and skip behavior
+ * <TooltipProvider
+ *   delayDuration={500}
+ *   skipDelayDuration={200}
+ * >
  *   <MyComponent />
  * </TooltipProvider>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Disable hoverable content for stricter accessibility
+ * <TooltipProvider disableHoverableContent>
+ *   <Form />
+ * </TooltipProvider>
+ * ```
+ *
+ * @accessibility
+ * - Manages focus behavior and keyboard navigation globally
+ * - Controls WCAG 2.1 compliance through hoverable content settings
+ * - Provides consistent timing behavior across all tooltips
+ * - Enables skip delay optimization for tooltip-heavy interfaces
+ *
  * @see {@link https://ui.shadcn.com/docs/components/tooltip} for design patterns
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/tooltip} for Radix UI documentation
  * @since 1.0.0
  */
 function TooltipProvider({
-  delayDuration = 0,
+  delayDuration = 700,
   ...props
 }: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
   return (
@@ -52,6 +158,11 @@ function TooltipProvider({
  * for displaying help text, definitions, or additional context without cluttering
  * the interface. Automatically wraps content in a TooltipProvider for convenience.
  *
+ * The tooltip supports both controlled and uncontrolled usage patterns, with
+ * intelligent positioning, collision detection, and smooth animations. Built
+ * with accessibility as a priority, including proper ARIA attributes and
+ * keyboard navigation support.
+ *
  * @example
  * ```tsx
  * // Basic tooltip
@@ -84,10 +195,29 @@ function TooltipProvider({
  *
  * @example
  * ```tsx
- * // Disabled element with tooltip
+ * // Controlled tooltip with custom delay
+ * const [open, setOpen] = useState(false)
+ *
+ * <Tooltip
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   delayDuration={300}
+ * >
+ *   <TooltipTrigger asChild>
+ *     <Button onClick={() => setOpen(!open)}>Toggle</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <p>Controlled tooltip state</p>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled element with tooltip (requires wrapper)
  * <Tooltip>
  *   <TooltipTrigger asChild>
- *     <span>
+ *     <span className="inline-block">
  *       <Button disabled>Disabled Action</Button>
  *     </span>
  *   </TooltipTrigger>
@@ -116,12 +246,15 @@ function TooltipProvider({
  * @accessibility
  * - Fully keyboard accessible (shows on focus, hides on blur)
  * - Screen reader compatible with proper ARIA attributes
- * - Escape key dismisses tooltip
+ * - Escape key dismisses tooltip immediately
  * - Automatic positioning with collision detection
  * - Respects user's reduced motion preferences
- * - Portal rendering prevents z-index issues
+ * - Portal rendering prevents z-index stacking issues
+ * - WCAG 2.1 compliant with hoverable content support
+ * - Works with assistive technologies and voice controls
  *
  * @see {@link https://ui.shadcn.com/docs/components/tooltip} for design patterns
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/tooltip} for Radix UI documentation
  * @see {@link Popover} - For interactive floating content
  * @see {@link HoverCard} - For rich content previews
  * @since 1.0.0
@@ -141,13 +274,16 @@ function Tooltip({
  *
  * Wraps the element that will show the tooltip on hover or focus.
  * Use the `asChild` prop to merge props with the child element rather
- * than rendering an additional wrapper element.
+ * than rendering an additional wrapper element. Essential for maintaining
+ * semantic meaning and avoiding unnecessary DOM nesting.
  *
- * @param asChild - When true, merges props with the child element instead of rendering a wrapper
+ * The trigger automatically handles all interaction events including mouse hover,
+ * touch interactions, keyboard focus, and blur events. It preserves the original
+ * element's accessibility properties while adding tooltip functionality.
  *
  * @example
  * ```tsx
- * // Basic trigger
+ * // Basic trigger with button
  * <TooltipTrigger asChild>
  *   <Button>Hover me</Button>
  * </TooltipTrigger>
@@ -155,20 +291,48 @@ function Tooltip({
  *
  * @example
  * ```tsx
- * // With disabled element (requires wrapper)
+ * // With icon button
  * <TooltipTrigger asChild>
- *   <span>
- *     <Button disabled>Disabled</Button>
+ *   <Button variant="ghost" size="icon">
+ *     <Settings className="h-4 w-4" />
+ *   </Button>
+ * </TooltipTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With disabled element (requires wrapper for pointer events)
+ * <TooltipTrigger asChild>
+ *   <span className="inline-block cursor-not-allowed">
+ *     <Button disabled>Disabled Action</Button>
  *   </span>
  * </TooltipTrigger>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With custom element
+ * <TooltipTrigger asChild>
+ *   <div
+ *     role="button"
+ *     tabIndex={0}
+ *     className="cursor-pointer p-2 rounded hover:bg-gray-100"
+ *   >
+ *     Custom trigger element
+ *   </div>
+ * </TooltipTrigger>
+ * ```
+ *
  * @accessibility
  * - Automatically handles hover, focus, and blur events
  * - Preserves existing keyboard navigation patterns
- * - Maintains semantic meaning of wrapped element
- * - Works with disabled elements when properly wrapped
+ * - Maintains semantic meaning and ARIA attributes of wrapped element
+ * - Works with disabled elements when properly wrapped with pointer-events
+ * - Supports all standard HTML interactive elements
+ * - Respects existing tab order and focus management
+ * - Compatible with screen readers and assistive technologies
  *
+ * @see {@link https://www.radix-ui.com/primitives/docs/guides/composition} for asChild pattern
  * @since 1.0.0
  */
 function TooltipTrigger({
@@ -185,10 +349,10 @@ function TooltipTrigger({
  * the tooltip stays within the viewport. Includes smooth animations and an arrow
  * pointer for visual connection to the trigger.
  *
- * @param side - Preferred side of the trigger to display on ("top" | "right" | "bottom" | "left")
- * @param sideOffset - Distance in pixels from the trigger element (default: 0)
- * @param className - Additional CSS classes for custom styling
- * @param children - Content to display in the tooltip
+ * The content component handles complex positioning logic, including collision
+ * detection, viewport boundaries, and responsive positioning. It supports rich
+ * content including text, images, and interactive elements while maintaining
+ * accessibility standards.
  *
  * @example
  * ```tsx
@@ -200,30 +364,76 @@ function TooltipTrigger({
  *
  * @example
  * ```tsx
- * // Positioned tooltip with offset
- * <TooltipContent side="left" sideOffset={10}>
- *   <p>Appears on the left with spacing</p>
+ * // Positioned tooltip with custom offset
+ * <TooltipContent
+ *   side="left"
+ *   sideOffset={12}
+ *   align="start"
+ *   alignOffset={-4}
+ * >
+ *   <p>Precisely positioned tooltip</p>
  * </TooltipContent>
  * ```
  *
  * @example
  * ```tsx
- * // Rich content with custom width
- * <TooltipContent className="max-w-[300px]">
- *   <div className="space-y-1">
- *     <p className="font-medium">Feature Name</p>
- *     <p className="text-xs">Detailed description here</p>
+ * // Rich content with custom styling
+ * <TooltipContent className="max-w-[320px] p-4">
+ *   <div className="space-y-2">
+ *     <div className="flex items-center gap-2">
+ *       <InfoIcon className="h-4 w-4 text-blue-500" />
+ *       <p className="font-semibold">Pro Feature</p>
+ *     </div>
+ *     <p className="text-sm text-gray-600">
+ *       This feature is available in Pro plans. Upgrade to unlock
+ *       advanced functionality and premium support.
+ *     </p>
+ *     <Button size="sm" className="mt-2">Upgrade Now</Button>
  *   </div>
  * </TooltipContent>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Tooltip with collision boundary
+ * <TooltipContent
+ *   collisionPadding={{ top: 10, bottom: 10 }}
+ *   hideWhenDetached
+ *   sticky="always"
+ * >
+ *   <p>Stays within safe boundaries</p>
+ * </TooltipContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled tooltip with escape handling
+ * <TooltipContent
+ *   onEscapeKeyDown={(e) => {
+ *     console.log('Tooltip dismissed with Escape');
+ *     // Custom handling if needed
+ *   }}
+ *   onPointerDownOutside={(e) => {
+ *     console.log('Clicked outside tooltip');
+ *   }}
+ * >
+ *   <p>Interactive tooltip with event handlers</p>
+ * </TooltipContent>
+ * ```
+ *
  * @accessibility
  * - Rendered in a portal to avoid z-index stacking issues
  * - Properly announced by screen readers with role="tooltip"
  * - Smooth animations respect reduced motion preferences
  * - Arrow provides visual connection to trigger element
  * - Automatically dismisses when trigger loses focus
+ * - Escape key immediately closes tooltip
+ * - Supports aria-label for screen reader context
+ * - Focus is managed properly for hoverable content
+ * - Compatible with high contrast themes
  *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/tooltip#content} for positioning details
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/} for ARIA tooltip pattern
  * @since 1.0.0
  */
 function TooltipContent({