@neynar/ui 0.1.1

package/src/components/ui/tooltip.tsx

@@ -0,0 +1,253 @@
+import * as React from "react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * 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.
+ *
+ * @param delayDuration - Time in milliseconds to wait before showing tooltip (default: 0)
+ *
+ * @example
+ * ```tsx
+ * // Wrap your entire app
+ * <TooltipProvider>
+ *   <App />
+ * </TooltipProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom delay
+ * <TooltipProvider delayDuration={700}>
+ *   <MyComponent />
+ * </TooltipProvider>
+ * ```
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/tooltip} for design patterns
+ * @since 1.0.0
+ */
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Tooltip - Display contextual information on hover or focus
+ *
+ * A versatile tooltip component built on Radix UI primitives that provides
+ * contextual information when users hover over or focus on an element. Perfect
+ * for displaying help text, definitions, or additional context without cluttering
+ * the interface. Automatically wraps content in a TooltipProvider for convenience.
+ *
+ * @example
+ * ```tsx
+ * // Basic tooltip
+ * <Tooltip>
+ *   <TooltipTrigger asChild>
+ *     <Button variant="outline">Hover me</Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <p>This is a helpful tooltip</p>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon button with tooltip
+ * import { Info } from "lucide-react"
+ *
+ * <Tooltip>
+ *   <TooltipTrigger asChild>
+ *     <Button variant="ghost" size="icon">
+ *       <Info className="h-4 w-4" />
+ *     </Button>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <p>Additional information</p>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled element with tooltip
+ * <Tooltip>
+ *   <TooltipTrigger asChild>
+ *     <span>
+ *       <Button disabled>Disabled Action</Button>
+ *     </span>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <p>You need to complete setup first</p>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Positioned tooltip with rich content
+ * <Tooltip>
+ *   <TooltipTrigger asChild>
+ *     <Badge variant="secondary">API Key</Badge>
+ *   </TooltipTrigger>
+ *   <TooltipContent side="right" className="max-w-[250px]">
+ *     <div className="space-y-1">
+ *       <p className="font-medium">API Authentication</p>
+ *       <p className="text-xs">Your key is used to authenticate requests</p>
+ *     </div>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
+ * @accessibility
+ * - Fully keyboard accessible (shows on focus, hides on blur)
+ * - Screen reader compatible with proper ARIA attributes
+ * - Escape key dismisses tooltip
+ * - Automatic positioning with collision detection
+ * - Respects user's reduced motion preferences
+ * - Portal rendering prevents z-index issues
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/tooltip} for design patterns
+ * @see {@link Popover} - For interactive floating content
+ * @see {@link HoverCard} - For rich content previews
+ * @since 1.0.0
+ */
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipProvider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+    </TooltipProvider>
+  );
+}
+
+/**
+ * TooltipTrigger - The element that triggers the tooltip display
+ *
+ * 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.
+ *
+ * @param asChild - When true, merges props with the child element instead of rendering a wrapper
+ *
+ * @example
+ * ```tsx
+ * // Basic trigger
+ * <TooltipTrigger asChild>
+ *   <Button>Hover me</Button>
+ * </TooltipTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With disabled element (requires wrapper)
+ * <TooltipTrigger asChild>
+ *   <span>
+ *     <Button disabled>Disabled</Button>
+ *   </span>
+ * </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
+ *
+ * @since 1.0.0
+ */
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+/**
+ * TooltipContent - The floating tooltip content container
+ *
+ * Contains the content displayed in the tooltip popup. Automatically positioned
+ * relative to the trigger element with intelligent collision detection to ensure
+ * 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
+ *
+ * @example
+ * ```tsx
+ * // Simple text tooltip
+ * <TooltipContent>
+ *   <p>This is helpful information</p>
+ * </TooltipContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Positioned tooltip with offset
+ * <TooltipContent side="left" sideOffset={10}>
+ *   <p>Appears on the left with spacing</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>
+ *   </div>
+ * </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
+ *
+ * @since 1.0.0
+ */
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-primary text-primary-foreground animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="bg-primary fill-primary z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

package/src/components/ui/typography.tsx

@@ -0,0 +1,468 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Typography variant configuration using class-variance-authority
+ *
+ * Defines all possible typography variants, sizes, and styling options.
+ * Uses Tailwind CSS 4 with custom CSS properties for theming.
+ *
+ * @see {@link https://cva.style/docs} - CVA documentation
+ * @see {@link https://ui.shadcn.com/docs/components/typography} - Typography component inspiration
+ * @since 1.0.0
+ */
+const typographyVariants = cva("", {
+  variants: {
+    /**
+     * Typography variant types based on semantic meaning and visual hierarchy
+     *
+     * @variant heading - Primary headings for page/section titles (20px)
+     * @variant subheading - Secondary headings for subsections (17px)
+     * @variant body - Standard body text for content (14px)
+     * @variant bodyEmphasized - Emphasized body text with medium weight (14px)
+     * @variant details - Smaller text for details and descriptions (12px)
+     * @variant field - Text for form fields and labels (17px)
+     * @variant code - Monospace text for code snippets (17px)
+     * @variant microcopy - Very small text for captions and fine print (10px)
+     * @variant tableCell - Text for table cell content (17px)
+     * @variant tableHeader - Text for table headers with emphasis (17px)
+     */
+    variant: {
+      heading: "text-lg font-semibold leading-tight",
+      subheading: "text-base font-medium leading-relaxed",
+      body: "text-sm leading-relaxed",
+      bodyEmphasized: "text-sm font-medium leading-relaxed",
+      details: "text-xs leading-normal",
+      field: "text-base leading-normal",
+      code: "text-base font-mono leading-normal",
+      microcopy: "text-microcopy leading-tight",
+      tableCell: "text-base leading-normal",
+      tableHeader: "text-base font-medium leading-normal",
+    },
+    /**
+     * Color variants for different semantic meanings
+     *
+     * @color default - Default text color based on theme
+     * @color muted - Muted text color for secondary information
+     * @color accent - Accent color for emphasis
+     * @color destructive - Red color for destructive actions or errors
+     * @color success - Green color for success states
+     * @color warning - Orange/yellow color for warnings
+     */
+    color: {
+      default: "text-foreground",
+      muted: "text-muted-foreground",
+      accent: "text-accent-foreground",
+      destructive: "text-destructive",
+      success: "text-success",
+      warning: "text-warning",
+    },
+    /**
+     * Text alignment options
+     */
+    align: {
+      left: "text-left",
+      center: "text-center",
+      right: "text-right",
+      justify: "text-justify",
+    },
+    /**
+     * Text transformation options
+     */
+    transform: {
+      uppercase: "uppercase",
+      lowercase: "lowercase",
+      capitalize: "capitalize",
+    },
+    /**
+     * Font weight variations
+     */
+    weight: {
+      normal: "font-normal",
+      medium: "font-medium",
+      semibold: "font-semibold",
+      bold: "font-bold",
+    },
+  },
+  defaultVariants: {
+    variant: "body",
+    color: "default",
+    align: "left",
+  },
+});
+
+/**
+ * Props interface for the Typography component
+ */
+export interface TypographyProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "color">,
+    VariantProps<typeof typographyVariants> {
+  /**
+   * The HTML element or component to render as
+   * @default "p"
+   */
+  as?: React.ElementType;
+  /**
+   * For label elements, the associated input ID
+   */
+  htmlFor?: string;
+  /**
+   * Whether to render as a Slot component for composition
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * Whether the text should be italic
+   * @default false
+   */
+  italic?: boolean;
+  /**
+   * Whether the text should be underlined
+   * @default false
+   */
+  underline?: boolean;
+  /**
+   * Whether the text should be struck through
+   * @default false
+   */
+  strikethrough?: boolean;
+  /**
+   * Whether the text should have a truncated overflow with ellipsis
+   * @default false
+   */
+  truncate?: boolean;
+  /**
+   * Screen reader only text (visually hidden but accessible)
+   * @default false
+   */
+  srOnly?: boolean;
+}
+
+/**
+ * Typography component for consistent text styling across the application
+ *
+ * Provides a comprehensive set of typography variants based on design system
+ * specifications. Supports semantic HTML elements, accessibility features,
+ * and flexible styling options.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic heading
+ * <Typography variant="heading" as="h1">
+ *   Welcome to Neynar
+ * </Typography>
+ *
+ * // Body text with color
+ * <Typography variant="body" color="muted">
+ *   This is some body text with muted color.
+ * </Typography>
+ *
+ * // Code snippet
+ * <Typography variant="code" as="code">
+ *   const message = "Hello, world!";
+ * </Typography>
+ *
+ * // Table header
+ * <Typography variant="tableHeader" as="th">
+ *   Column Header
+ * </Typography>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With additional styling
+ * <Typography
+ *   variant="subheading"
+ *   color="accent"
+ *   align="center"
+ *   italic
+ *   underline
+ * >
+ *   Styled Subheading
+ * </Typography>
+ *
+ * // Truncated text
+ * <Typography variant="body" truncate className="max-w-xs">
+ *   This is a very long text that will be truncated with ellipsis
+ * </Typography>
+ *
+ * // Screen reader only
+ * <Typography variant="details" srOnly>
+ *   Additional context for screen readers
+ * </Typography>
+ * ```
+ *
+ * @param props - Typography component props
+ * @param props.variant - Typography variant for semantic styling
+ * @param props.color - Color variant for different semantic meanings
+ * @param props.align - Text alignment
+ * @param props.transform - Text transformation
+ * @param props.weight - Font weight override
+ * @param props.as - HTML element to render as
+ * @param props.asChild - Render as Slot for composition
+ * @param props.italic - Apply italic styling
+ * @param props.underline - Apply underline styling
+ * @param props.strikethrough - Apply strikethrough styling
+ * @param props.truncate - Apply text truncation with ellipsis
+ * @param props.srOnly - Hide visually but keep accessible
+ * @param props.className - Additional CSS classes
+ * @param props.children - Content to render
+ *
+ * @accessibility
+ * - Uses semantic HTML elements when specified via `as` prop
+ * - Supports screen reader only content with `srOnly` prop
+ * - Maintains proper color contrast ratios across all color variants
+ * - Respects user preferences for reduced motion and high contrast
+ *
+ * @since 1.0.0
+ */
+export function Typography({
+  className,
+  variant,
+  color,
+  align,
+  transform,
+  weight,
+  as: Element = "p",
+  asChild = false,
+  italic = false,
+  underline = false,
+  strikethrough = false,
+  truncate = false,
+  srOnly = false,
+  ...props
+}: TypographyProps) {
+  const Comp = asChild ? Slot : Element;
+
+
+  return (
+    <Comp
+      className={cn(
+        typographyVariants({ variant, color, align, transform, weight }),
+        {
+          italic,
+          underline,
+          "line-through": strikethrough,
+          "truncate overflow-hidden text-ellipsis whitespace-nowrap": truncate,
+          "sr-only": srOnly,
+        },
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual semantic typography components with pre-configured defaults
+ */
+
+/**
+ * H1 heading component
+ *
+ * @example
+ * ```tsx
+ * <H1>Main Page Title</H1>
+ * <H1 color="muted">Subtle heading</H1>
+ * ```
+ */
+export function H1(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="heading" as="h1" {...props} />;
+}
+
+/**
+ * H2 heading component
+ *
+ * @example
+ * ```tsx
+ * <H2>Section Title</H2>
+ * <H2 color="accent">Highlighted section</H2>
+ * ```
+ */
+export function H2(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="subheading" as="h2" {...props} />;
+}
+
+/**
+ * H3 heading component
+ *
+ * @example
+ * ```tsx
+ * <H3>Subsection Title</H3>
+ * ```
+ */
+export function H3(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="subheading" as="h3" {...props} />;
+}
+
+/**
+ * H4 heading component
+ *
+ * @example
+ * ```tsx
+ * <H4>Minor Heading</H4>
+ * ```
+ */
+export function H4(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="bodyEmphasized" as="h4" {...props} />;
+}
+
+/**
+ * H5 heading component
+ *
+ * @example
+ * ```tsx
+ * <H5>Small Heading</H5>
+ * ```
+ */
+export function H5(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="bodyEmphasized" as="h5" {...props} />;
+}
+
+/**
+ * H6 heading component
+ *
+ * @example
+ * ```tsx
+ * <H6>Smallest Heading</H6>
+ * ```
+ */
+export function H6(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="details" as="h6" {...props} />;
+}
+
+/**
+ * Paragraph component for body text
+ *
+ * @example
+ * ```tsx
+ * <P>Standard paragraph text content.</P>
+ * <P color="muted">Secondary paragraph text.</P>
+ * <P className="mb-4">Paragraph with custom margin.</P>
+ * ```
+ */
+export function P(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="body" as="p" {...props} />;
+}
+
+/**
+ * Span component for inline text
+ *
+ * @example
+ * ```tsx
+ * <span>Regular text with <Span color="accent">highlighted</Span> content</span>
+ * <Span variant="details">Small inline text</Span>
+ * ```
+ */
+export function Span(props: Omit<TypographyProps, "as">) {
+  return <Typography as="span" {...props} />;
+}
+
+/**
+ * Code component for inline code snippets
+ *
+ * @example
+ * ```tsx
+ * <Code>const hello = "world";</Code>
+ * <Code color="muted">npm install</Code>
+ * ```
+ */
+export function Code(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="code" as="code" {...props} />;
+}
+
+
+/**
+ * Small component for fine print and microcopy
+ *
+ * @example
+ * ```tsx
+ * <Small>Terms and conditions apply</Small>
+ * <Small color="muted">Updated 2 minutes ago</Small>
+ * ```
+ */
+export function Small(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="microcopy" as="small" {...props} />;
+}
+
+/**
+ * Strong component for emphasized text
+ *
+ * @example
+ * ```tsx
+ * <Strong>Important information</Strong>
+ * <Strong color="destructive">Critical warning</Strong>
+ * ```
+ */
+export function Strong(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="bodyEmphasized" as="strong" {...props} />;
+}
+
+/**
+ * Lead component for introductory text
+ *
+ * @example
+ * ```tsx
+ * <Lead>This is the introduction to the article...</Lead>
+ * ```
+ */
+export function Lead(props: Omit<TypographyProps, "as" | "variant">) {
+  return <Typography variant="subheading" as="p" color="muted" {...props} />;
+}
+
+/**
+ * Anchor/Link component for interactive text links
+ *
+ * @example
+ * ```tsx
+ * <A href="https://example.com">Visit our website</A>
+ * <A href="/about" color="accent">Learn more</A>
+ * <A asChild><Link href="/about">Learn more</Link></A>
+ * ```
+ */
+export function A({ 
+  href, 
+  asChild = false, 
+  className,
+  ...props 
+}: Omit<TypographyProps, "as" | "variant"> & React.AnchorHTMLAttributes<HTMLAnchorElement>) {
+  return (
+    <Typography
+      variant="body"
+      as={asChild ? undefined : "a"}
+      asChild={asChild}
+      className={cn("underline underline-offset-2 hover:text-primary transition-colors", className)}
+      {...(href ? { href } : {})}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Blockquote component for quoted text
+ *
+ * @example
+ * ```tsx
+ * <Blockquote>"The best way to predict the future is to invent it."</Blockquote>
+ * ```
+ */
+export function Blockquote(props: Omit<TypographyProps, "as" | "variant">) {
+  return (
+    <Typography
+      variant="body"
+      as="blockquote"
+      italic
+      className="border-l-4 border-border pl-4"
+      {...props}
+    />
+  );
+}
+
+/**
+ * Type export for external use
+ */
+export type { VariantProps as TypographyVariantProps } from "class-variance-authority";