@neynar/ui 0.1.1

package/dist/components/ui/alert-dialog.d.ts

@@ -0,0 +1,247 @@
+import * as React from "react";
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
+/**
+ * Alert dialog component for critical confirmations and destructive actions
+ *
+ * A specialized modal dialog built on Radix UI Alert Dialog primitives that interrupts
+ * users with important information requiring immediate acknowledgment or decision.
+ * Unlike regular dialogs, alert dialogs cannot be dismissed by clicking outside and
+ * focus the action button by default for critical decisions.
+ *
+ * Based on the WAI-ARIA Alert Dialog design pattern, this component is specifically
+ * designed for destructive actions, confirmations, or critical warnings that need
+ * immediate attention before the user can continue.
+ *
+ * @example
+ * ```tsx
+ * // Basic destructive confirmation
+ * <AlertDialog>
+ *   <AlertDialogTrigger asChild>
+ *     <Button variant="destructive">Delete Account</Button>
+ *   </AlertDialogTrigger>
+ *   <AlertDialogContent>
+ *     <AlertDialogHeader>
+ *       <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+ *       <AlertDialogDescription>
+ *         This action cannot be undone. This will permanently delete
+ *         your account and remove your data from our servers.
+ *       </AlertDialogDescription>
+ *     </AlertDialogHeader>
+ *     <AlertDialogFooter>
+ *       <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *       <AlertDialogAction>Delete Account</AlertDialogAction>
+ *     </AlertDialogFooter>
+ *   </AlertDialogContent>
+ * </AlertDialog>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Simple confirmation
+ * <AlertDialog>
+ *   <AlertDialogTrigger asChild>
+ *     <Button variant="outline">Sign Out</Button>
+ *   </AlertDialogTrigger>
+ *   <AlertDialogContent>
+ *     <AlertDialogHeader>
+ *       <AlertDialogTitle>Sign Out</AlertDialogTitle>
+ *       <AlertDialogDescription>
+ *         Are you sure you want to sign out of your account?
+ *       </AlertDialogDescription>
+ *     </AlertDialogHeader>
+ *     <AlertDialogFooter>
+ *       <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *       <AlertDialogAction>Sign Out</AlertDialogAction>
+ *     </AlertDialogFooter>
+ *   </AlertDialogContent>
+ * </AlertDialog>
+ * ```
+ *
+ * @accessibility
+ * - Follows WAI-ARIA Alert Dialog design pattern
+ * - Focus is trapped within the dialog when open
+ * - Cannot be dismissed by clicking outside (intentional for alerts)
+ * - Escape key closes the dialog (unless preventDefault is called)
+ * - Proper ARIA roles and attributes for screen readers
+ * - Focus returns to trigger element when closed
+ * - Action button receives initial focus by default
+ * - Supports keyboard navigation between focusable elements
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/alert-dialog} shadcn/ui Alert Dialog docs
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/alert-dialog} Radix UI Alert Dialog
+ * @see {@link Dialog} For general modal content that can be dismissed
+ * @see {@link Sheet} For side panel overlays
+ * @since 1.0.0
+ */
+/**
+ * Root component of the alert dialog
+ *
+ * Provides the context and state management for the entire alert dialog.
+ * Controls the open/closed state and manages focus behavior.
+ *
+ * @param props - All props are forwarded to the underlying Radix AlertDialog.Root
+ */
+declare function AlertDialog({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Trigger element that opens the alert dialog
+ *
+ * The element that opens the alert dialog when activated. Usually a button,
+ * but can be any interactive element. Use the `asChild` prop to compose
+ * with other components.
+ *
+ * @param props - All props are forwarded to the underlying Radix AlertDialog.Trigger
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTrigger asChild>
+ *   <Button variant="destructive">Delete</Button>
+ * </AlertDialogTrigger>
+ * ```
+ */
+declare function AlertDialogTrigger({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Portal component for rendering dialog outside normal DOM tree
+ *
+ * Renders the alert dialog content into a portal, typically at the end of the document body.
+ * This ensures the dialog appears above other content and is properly accessible.
+ * Usually not used directly - AlertDialogContent includes this automatically.
+ *
+ * @param props - All props are forwarded to the underlying Radix AlertDialog.Portal
+ */
+declare function AlertDialogPortal({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Portal>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Overlay backdrop behind the alert dialog
+ *
+ * A semi-transparent backdrop that covers the entire viewport when the dialog is open.
+ * Provides visual separation and prevents interaction with background content.
+ * Includes fade in/out animations using data-state attributes.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Overlay
+ */
+declare function AlertDialogOverlay({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Main content container for the alert dialog
+ *
+ * The primary container that holds all alert dialog content. Automatically includes
+ * the portal and overlay, and provides default styling with responsive design.
+ * Centered on screen with fade and zoom animations.
+ *
+ * @param className - Additional CSS classes to apply to the content container
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Content
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogContent>
+ *   <AlertDialogHeader>
+ *     <AlertDialogTitle>Confirm Action</AlertDialogTitle>
+ *     <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+ *   </AlertDialogHeader>
+ *   <AlertDialogFooter>
+ *     <AlertDialogCancel>Cancel</AlertDialogCancel>
+ *     <AlertDialogAction>Continue</AlertDialogAction>
+ *   </AlertDialogFooter>
+ * </AlertDialogContent>
+ * ```
+ */
+declare function AlertDialogContent({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Header section of the alert dialog
+ *
+ * Contains the title and description of the alert dialog. Provides consistent
+ * spacing and alignment, with responsive text alignment (centered on mobile,
+ * left-aligned on larger screens).
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying div element
+ */
+declare function AlertDialogHeader({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/**
+ * Footer section of the alert dialog
+ *
+ * Contains the action buttons (cancel and confirm). Uses responsive layout
+ * with stacked buttons on mobile (cancel on top) and horizontal layout
+ * on larger screens (cancel on left, action on right).
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying div element
+ */
+declare function AlertDialogFooter({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/**
+ * Title heading of the alert dialog
+ *
+ * The main heading that describes the alert or action being confirmed.
+ * Automatically provides proper ARIA labeling for screen readers.
+ * Should be concise and clearly state what the dialog is asking.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Title
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+ * <AlertDialogTitle>Delete Account</AlertDialogTitle>
+ * ```
+ */
+declare function AlertDialogTitle({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Title>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Description text of the alert dialog
+ *
+ * Provides additional context and explanation for the alert or action.
+ * Should clearly explain the consequences of the action being confirmed.
+ * Automatically provides proper ARIA description for screen readers.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Description
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogDescription>
+ *   This action cannot be undone. This will permanently delete your
+ *   account and remove your data from our servers.
+ * </AlertDialogDescription>
+ * ```
+ */
+declare function AlertDialogDescription({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Description>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Primary action button of the alert dialog
+ *
+ * The button that confirms or executes the action being alerted about.
+ * Automatically receives focus when the dialog opens. Styled as a primary
+ * button by default, but can be customized for destructive actions.
+ * Closes the dialog when clicked.
+ *
+ * @param className - Additional CSS classes to apply (useful for destructive styling)
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Action
+ *
+ * @example
+ * ```tsx
+ * // Default action
+ * <AlertDialogAction>Continue</AlertDialogAction>
+ *
+ * // Destructive action
+ * <AlertDialogAction className="bg-red-600 hover:bg-red-700">
+ *   Delete Account
+ * </AlertDialogAction>
+ * ```
+ */
+declare function AlertDialogAction({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Action>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Cancel button of the alert dialog
+ *
+ * The button that dismisses the dialog without performing the action.
+ * Styled as an outline button by default to de-emphasize compared to
+ * the primary action. Closes the dialog when clicked.
+ *
+ * @param className - Additional CSS classes to apply
+ * @param props - All other props are forwarded to the underlying Radix AlertDialog.Cancel
+ *
+ * @example
+ * ```tsx
+ * <AlertDialogCancel>Cancel</AlertDialogCancel>
+ * <AlertDialogCancel>No, keep it</AlertDialogCancel>
+ * ```
+ */
+declare function AlertDialogCancel({ className, ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Cancel>): import("react/jsx-runtime").JSX.Element;
+export { AlertDialog, AlertDialogPortal, AlertDialogOverlay, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel, };
+//# sourceMappingURL=alert-dialog.d.ts.map

package/dist/components/ui/alert-dialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-dialog.d.ts","sourceRoot":"","sources":["../../../src/components/ui/alert-dialog.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAC;AAKrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH;;;;;;;GAOG;AACH,iBAAS,WAAW,CAAC,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,2CAExD;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,OAAO,CAAC,2CAI3D;AAED;;;;;;;;GAQG;AACH,iBAAS,iBAAiB,CAAC,EACzB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,MAAM,CAAC,2CAI1D;AAED;;;;;;;;;GASG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,OAAO,CAAC,2CAW3D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,OAAO,CAAC,2CAc3D;AAED;;;;;;;;;GASG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAQ7B;AAED;;;;;;;;;GASG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAW7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,KAAK,CAAC,2CAQzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,sBAAsB,CAAC,EAC9B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,WAAW,CAAC,2CAQ/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,MAAM,CAAC,2CAO1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,MAAM,CAAC,2CAO1D;AAED,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,GAClB,CAAC"}

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

@@ -0,0 +1,187 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const alertVariants: (props?: ({
+    variant?: "default" | "destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * Alert - Display important messages and notifications to users
+ *
+ * A flexible alert component for displaying important messages, notifications, and status updates.
+ * Built with shadcn/ui design patterns and Tailwind CSS. Alerts are used to communicate
+ * critical information that requires user attention and potentially action.
+ *
+ * ## When to use
+ * - System-wide notifications and announcements
+ * - Form validation errors and success messages
+ * - Important warnings that need persistent visibility
+ * - Status updates that don't require immediate action
+ * - Progress indicators and completion messages
+ *
+ * ## Features
+ * - Two built-in variants: `default` and `destructive`
+ * - Automatic icon grid layout with proper spacing using CSS Grid
+ * - Semantic HTML with proper ARIA attributes (`role="alert"`)
+ * - Responsive design with consistent spacing
+ * - Dark mode support via CSS custom properties
+ * - Composition pattern with AlertTitle and AlertDescription
+ * - Support for custom styling through className prop
+ * - Icon-aware layout that adapts to presence of SVG icons
+ *
+ * ## Design Philosophy
+ * Follows the shadcn/ui principle of providing unstyled, accessible components that
+ * can be easily customized. The alert uses CSS Grid for intelligent layout that
+ * automatically adjusts based on whether an icon is present.
+ *
+ * @example
+ * ```tsx
+ * // Basic informational alert
+ * <Alert>
+ *   <Info className="size-4" />
+ *   <AlertTitle>Heads up!</AlertTitle>
+ *   <AlertDescription>
+ *     You can add components to your app using the cli.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Destructive error alert
+ * import { AlertCircle } from "lucide-react";
+ *
+ * <Alert variant="destructive">
+ *   <AlertCircle className="size-4" />
+ *   <AlertTitle>Error</AlertTitle>
+ *   <AlertDescription>
+ *     Your session has expired. Please log in again.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled success alert
+ * <Alert className="border-green-200 bg-green-50 text-green-800 dark:border-green-800 dark:bg-green-950 dark:text-green-200">
+ *   <CheckCircle className="size-4" />
+ *   <AlertTitle>Success</AlertTitle>
+ *   <AlertDescription>
+ *     Your changes have been saved successfully.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Alert without icon
+ * <Alert>
+ *   <AlertTitle>Simple Notice</AlertTitle>
+ *   <AlertDescription>
+ *     This alert doesn't use an icon.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Alert with only description
+ * <Alert variant="destructive">
+ *   <AlertCircle className="size-4" />
+ *   <AlertDescription>
+ *     Something went wrong. Please try again.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @param variant - Visual style variant determining colors and emphasis
+ * @param className - Additional CSS classes to merge with default styles
+ * @param children - Alert content including optional icon, title, and description
+ * @param props - Additional HTML div element props
+ *
+ * @accessibility
+ * - Uses `role="alert"` for immediate screen reader announcements
+ * - Supports keyboard navigation when containing interactive elements
+ * - WCAG AA color contrast compliance for all variants
+ * - Semantic HTML structure with proper heading hierarchy
+ * - Icon support with automatic grid layout and accessible sizing
+ * - Icons receive `text-current` color for proper contrast inheritance
+ *
+ * @see {@link AlertTitle} - Alert title component for headings
+ * @see {@link AlertDescription} - Alert description component for body text
+ * @see {@link https://ui.shadcn.com/docs/components/alert} - shadcn/ui Alert documentation
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/alert/} - ARIA alert pattern
+ * @since 1.0.0
+ */
+declare function Alert({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>): import("react/jsx-runtime").JSX.Element;
+/**
+ * AlertTitle - The title/heading component for alerts
+ *
+ * Provides a prominent title or heading for the alert message. Automatically styled
+ * with medium font weight, line clamping, and proper grid positioning. Used to
+ * give context and immediate recognition of the alert's purpose.
+ *
+ * ## Features
+ * - Medium font weight for visual hierarchy
+ * - Single line with overflow handling (line-clamp-1)
+ * - Consistent minimum height for layout stability
+ * - Proper grid positioning (col-start-2) for icon layout
+ * - Tight character spacing (tracking-tight) for readability
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Alert>
+ *   <Info className="size-4" />
+ *   <AlertTitle>Payment Successful</AlertTitle>
+ *   <AlertDescription>Your payment has been processed.</AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Title-only alert (no description)
+ * <Alert variant="destructive">
+ *   <AlertCircle className="size-4" />
+ *   <AlertTitle>Connection Failed</AlertTitle>
+ * </Alert>
+ * ```
+ *
+ * @param className - Additional CSS classes to apply
+ * @param children - Title text content
+ *
+ * @accessibility
+ * - Semantically associated with the alert container via DOM structure
+ * - Proper visual hierarchy with medium font weight
+ * - Readable character spacing and line height
+ * - Works with screen readers as part of alert announcement
+ *
+ * @see {@link Alert} - Parent alert container component
+ * @see {@link AlertDescription} - Companion description component
+ * @since 1.0.0
+ */
+declare function AlertTitle({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/**
+ * AlertDescription - Detailed description text for an alert
+ *
+ * Provides additional context or instructions related to the alert.
+ * Supports multiple paragraphs and rich text content.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Alert>
+ *   <AlertTitle>Note</AlertTitle>
+ *   <AlertDescription>
+ *     Your changes have been saved. You can continue editing or publish when ready.
+ *   </AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @accessibility
+ * - Uses appropriate text color for readability
+ * - Supports paragraph spacing for long content
+ *
+ * @since 1.0.0
+ */
+declare function AlertDescription({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+export { Alert, AlertTitle, AlertDescription };
+//# sourceMappingURL=alert.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"alert.d.ts","sourceRoot":"","sources":["../../../src/components/ui/alert.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAIlE,QAAA,MAAM,aAAa;;8EAclB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,OAAO,EACP,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,2CASlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAWvE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAW7B;AAED,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/components/ui/aspect-ratio.d.ts

@@ -0,0 +1,94 @@
+import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
+/**
+ * AspectRatio component for maintaining consistent width-to-height ratios
+ *
+ * A foundational layout component that preserves specific aspect ratios regardless
+ * of container size. Essential for responsive images, videos, and media content that
+ * needs consistent proportions across different screen sizes. Built on Radix UI
+ * primitives with zero JavaScript runtime overhead.
+ *
+ * This component creates a CSS-based aspect ratio container using the modern
+ * `aspect-ratio` property, ensuring content maintains its intended proportions
+ * without layout shifts or JavaScript calculations.
+ *
+ * @example Basic image with 16:9 aspect ratio
+ * ```tsx
+ * <div className="w-[450px]">
+ *   <AspectRatio ratio={16 / 9}>
+ *     <img
+ *       src="landscape.jpg"
+ *       alt="Beautiful landscape"
+ *       className="w-full h-full object-cover rounded-md"
+ *     />
+ *   </AspectRatio>
+ * </div>
+ * ```
+ *
+ * @example Square avatar container (1:1 ratio)
+ * ```tsx
+ * <AspectRatio ratio={1}>
+ *   <img
+ *     src="avatar.jpg"
+ *     alt="User profile"
+ *     className="w-full h-full object-cover rounded-full"
+ *   />
+ * </AspectRatio>
+ * ```
+ *
+ * @example Video player container
+ * ```tsx
+ * <div className="w-full max-w-2xl">
+ *   <AspectRatio ratio={16 / 9}>
+ *     <video
+ *       src="video.mp4"
+ *       controls
+ *       className="w-full h-full object-cover rounded-lg"
+ *     />
+ *   </AspectRatio>
+ * </div>
+ * ```
+ *
+ * @example Responsive image gallery with portrait orientation
+ * ```tsx
+ * <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+ *   {images.map((image) => (
+ *     <AspectRatio key={image.id} ratio={3 / 4}>
+ *       <img
+ *         src={image.src}
+ *         alt={image.alt}
+ *         className="w-full h-full object-cover rounded-md"
+ *       />
+ *     </AspectRatio>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * @example Placeholder content for loading states
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>
+ *   <div className="flex items-center justify-center bg-muted border-2 border-dashed border-muted-foreground/25 rounded-md">
+ *     <div className="text-center text-muted-foreground">
+ *       <ImageIcon className="h-12 w-12 mx-auto mb-2" />
+ *       <p className="text-sm">Loading image...</p>
+ *     </div>
+ *   </div>
+ * </AspectRatio>
+ * ```
+ *
+ * @param ratio - The desired aspect ratio as width/height (e.g., 16/9, 4/3, 1)
+ * @param children - Content to be constrained within the aspect ratio
+ * @param className - Additional CSS classes for styling
+ *
+ * @accessibility
+ * - Inherits all accessibility features from Radix UI AspectRatio primitive
+ * - Preserves semantic meaning of child content
+ * - Does not interfere with screen reader navigation
+ * - Maintains keyboard navigation for interactive child elements
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/aspect-ratio} shadcn/ui documentation
+ * @since 1.0.0
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/aspect-ratio} Radix UI AspectRatio
+ */
+declare function AspectRatio({ ...props }: React.ComponentProps<typeof AspectRatioPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+export { AspectRatio };
+//# sourceMappingURL=aspect-ratio.d.ts.map

package/dist/components/ui/aspect-ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aspect-ratio.d.ts","sourceRoot":"","sources":["../../../src/components/ui/aspect-ratio.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,iBAAS,WAAW,CAAC,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,2CAExD;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}