@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/tooltip.d.ts

@@ -5,9 +5,11 @@ import * as TooltipPrimitive from "@radix-ui/react-tooltip";
  *
  * 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
@@ -19,13 +21,31 @@ import * as TooltipPrimitive from "@radix-ui/react-tooltip";
  *
  * @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
  */
 declare function TooltipProvider({ delayDuration, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>): import("react/jsx-runtime").JSX.Element;
@@ -37,6 +57,11 @@ declare function TooltipProvider({ delayDuration, ...props }: React.ComponentPro
  * 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
@@ -69,10 +94,29 @@ declare function TooltipProvider({ delayDuration, ...props }: React.ComponentPro
  *
  * @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>
@@ -101,12 +145,15 @@ declare function TooltipProvider({ delayDuration, ...props }: React.ComponentPro
  * @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
@@ -117,13 +164,16 @@ declare function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimit
  *
  * 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>
@@ -131,20 +181,48 @@ declare function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimit
  *
  * @example
  * ```tsx
- * // With disabled element (requires wrapper)
+ * // With icon button
+ * <TooltipTrigger asChild>
+ *   <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>
- *     <Button disabled>Disabled</Button>
+ *   <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
  */
 declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
@@ -156,10 +234,10 @@ declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof Toolti
  * 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
@@ -171,30 +249,76 @@ declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof Toolti
  *
  * @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
  */
 declare function TooltipContent({ className, sideOffset, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/tooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tooltip.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,gBAAgB,MAAM,yBAAyB,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,eAAe,CAAC,EACvB,aAAiB,EACjB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,2CAQxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,iBAAS,OAAO,CAAC,EACf,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,2CAMpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,iBAAS,cAAc,CAAC,EACtB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,OAAO,CAAC,2CAEvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,UAAc,EACd,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,OAAO,CAAC,2CAiBvD;AAED,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tooltip.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,gBAAgB,MAAM,yBAAyB,CAAC;AA0F5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,iBAAS,eAAe,CAAC,EACvB,aAAmB,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,2CAQxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,iBAAS,OAAO,CAAC,EACf,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,2CAMpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,iBAAS,cAAc,CAAC,EACtB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,OAAO,CAAC,2CAEvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,UAAc,EACd,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,OAAO,CAAC,2CAiBvD;AAED,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}