@neynar/ui 0.1.1 → 0.1.2

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

@@ -1,12 +1,25 @@
 import * as React from "react";
-import { type VariantProps } from "class-variance-authority";
 /**
  * Button variant configuration using class-variance-authority
  *
  * Defines all possible visual variants and sizes for the Button component.
- * Uses Tailwind CSS 4 with custom CSS properties for theming.
+ * Uses Tailwind CSS with custom CSS properties for theming and comprehensive
+ * accessibility features including focus management and ARIA support.
+ *
+ * @variant default - Primary action button with brand colors and elevated appearance
+ * @variant destructive - Dangerous/destructive actions (delete, remove, etc.) with red theming
+ * @variant outline - Secondary action with subtle border and background hover states
+ * @variant secondary - Alternative secondary styling with muted colors
+ * @variant ghost - Minimal styling with hover states, often used in toolbars or menus
+ * @variant link - Text-only button styled like a hyperlink with underline on hover
+ *
+ * @size default - Standard button height (36px) with balanced padding
+ * @size sm - Small button height (32px) for compact interfaces
+ * @size lg - Large button height (40px) for prominent actions
+ * @size icon - Square button (36px × 36px) optimized for icon-only usage
  *
  * @see {@link https://cva.style/docs} - CVA documentation
+ * @see {@link https://ui.shadcn.com/docs/components/button} - shadcn/ui button documentation
  * @since 1.0.0
  */
 declare const buttonVariants: (props?: ({
@@ -14,60 +27,137 @@ declare const buttonVariants: (props?: ({
     size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
- * Button - A versatile button component with multiple style variants and sizes
- *
- * The Button component is a fundamental UI element used to trigger actions or navigate
- * through the application. Built on Radix UI's Slot primitive, it supports multiple
- * visual variants, sizes, and can be composed with other components using the asChild
- * prop for maximum flexibility. Icons placed within the button are automatically
- * styled with proper spacing and sizing.
+ * Props for Button component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CVA/Radix inferred types
+ */
+type ButtonDocsProps = {
+    /** Visual style variant that determines the button's appearance and semantic meaning */
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
+    /** Size variant that controls the button's dimensions and padding */
+    size?: "default" | "sm" | "lg" | "icon";
+    /**
+     * Render the button as its child element instead of a button element.
+     * Enables composition patterns for creating button-styled links or other elements.
+     * When true, all props are forwarded to the child element via Radix UI Slot.
+     *
+     * @example
+     * ```tsx
+     * <Button asChild>
+     *   <Link href="/dashboard">Dashboard</Link>
+     * </Button>
+     * ```
+     *
+     * @default false
+     */
+    asChild?: boolean;
+    /** Content to display inside the button (text, icons, or React components) */
+    children?: React.ReactNode;
+    /** Additional CSS classes to apply to the button for custom styling */
+    className?: string;
+    /** Whether the button is disabled and cannot be interacted with @default false */
+    disabled?: boolean;
+    /** Button type for form submission behavior @default "button" */
+    type?: "button" | "submit" | "reset";
+    /** Click handler function called when the button is activated */
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+    /** Focus handler called when the button receives focus */
+    onFocus?: React.FocusEventHandler<HTMLButtonElement>;
+    /** Blur handler called when the button loses focus */
+    onBlur?: React.FocusEventHandler<HTMLButtonElement>;
+    /** Mouse enter handler for hover interactions */
+    onMouseEnter?: React.MouseEventHandler<HTMLButtonElement>;
+    /** Mouse leave handler for hover interactions */
+    onMouseLeave?: React.MouseEventHandler<HTMLButtonElement>;
+    /** Accessible label for screen readers (required for icon-only buttons) */
+    "aria-label"?: string;
+    /** Describes the button for screen readers */
+    "aria-describedby"?: string;
+    /** Indicates invalid state for form validation */
+    "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling";
+    /** Indicates expanded state for disclosure buttons */
+    "aria-expanded"?: React.AriaAttributes['aria-expanded'];
+    /** Associates button with elements it controls */
+    "aria-controls"?: string;
+    /** Indicates pressed state for toggle buttons */
+    "aria-pressed"?: boolean | "false" | "true" | "mixed";
+    /** Tab index for focus management @default 0 */
+    tabIndex?: number;
+    /** Auto focus the button when component mounts @default false */
+    autoFocus?: boolean;
+    /** Form attribute to associate button with a form element */
+    form?: string;
+    /** Form action URL or function for submit buttons */
+    formAction?: string | ((formData: FormData) => void | Promise<void>);
+    /** Form encoding type for submit buttons */
+    formEncType?: string;
+    /** Form method for submit buttons */
+    formMethod?: string;
+    /** Form validation bypass for submit buttons @default false */
+    formNoValidate?: boolean;
+    /** Form target for submit buttons */
+    formTarget?: string;
+    /** Button name for form submission */
+    name?: string;
+    /** Button value for form submission */
+    value?: string | ReadonlyArray<string> | number;
+} & React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    /** Ref to access the button element */
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * Button - A versatile, accessible button component with multiple style variants
  *
- * @component
- * @example
- * ```tsx
- * // Basic usage
- * <Button>Click me</Button>
- * ```
+ * A fundamental UI element built on Radix UI's Slot primitive that supports extensive
+ * customization through variants, composition patterns, and comprehensive accessibility
+ * features. The component automatically handles icon styling, focus management, form
+ * integration, and can be rendered as other elements using the asChild pattern.
  *
  * @example
  * ```tsx
- * // With variants and sizes
- * <Button variant="outline" size="lg">Large Outline Button</Button>
- * <Button variant="destructive" size="sm">Delete</Button>
- * <Button variant="ghost">Ghost Button</Button>
+ * // Basic usage with different variants
+ * <Button>Default Button</Button>
+ * <Button variant="destructive">Delete Item</Button>
+ * <Button variant="outline" size="lg">Large Outline</Button>
+ * <Button variant="ghost" size="sm">Small Ghost</Button>
+ * <Button variant="link">Link Button</Button>
  * ```
  *
  * @example
  * ```tsx
- * // With icons (automatically styled)
- * import { Download, ArrowRight, Plus } from "lucide-react";
+ * // Icon usage (automatically styled with proper spacing)
+ * import { Download, ArrowRight, Plus, Trash2 } from "lucide-react";
  *
  * <Button>
- *   <Download /> Download File
+ *   <Download className="mr-2" /> Download File
  * </Button>
  *
- * <Button>
- *   Continue <ArrowRight />
+ * <Button variant="outline">
+ *   Continue <ArrowRight className="ml-2" />
  * </Button>
  *
- * // Icon-only button
- * <Button size="icon" aria-label="Add item">
+ * // Icon-only button (always include aria-label)
+ * <Button size="icon" aria-label="Add new item">
  *   <Plus />
  * </Button>
+ *
+ * <Button size="icon" variant="destructive" aria-label="Delete item">
+ *   <Trash2 />
+ * </Button>
  * ```
  *
  * @example
  * ```tsx
- * // As other elements using asChild (composition pattern)
+ * // Composition with asChild (render as different elements)
  * import Link from "next/link";
+ * import { ExternalLink } from "lucide-react";
  *
  * <Button asChild>
  *   <Link href="/dashboard">Go to Dashboard</Link>
  * </Button>
  *
  * <Button asChild variant="outline">
- *   <a href="https://example.com" target="_blank" rel="noopener">
- *     External Link
+ *   <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+ *     External Link <ExternalLink className="ml-2 h-4 w-4" />
  *   </a>
  * </Button>
  * ```
@@ -75,55 +165,83 @@ declare const buttonVariants: (props?: ({
  * @example
  * ```tsx
  * // Form integration and states
- * <Button disabled>Loading...</Button>
- * <Button type="submit">Submit Form</Button>
- * <Button aria-invalid={hasError}>Validate</Button>
- *
- * // Loading state with spinner
- * <Button disabled>
- *   <LoadingSpinner className="size-4" />
- *   Processing...
+ * <Button type="submit" disabled={isSubmitting}>
+ *   {isSubmitting ? "Submitting..." : "Submit Form"}
+ * </Button>
+ *
+ * <Button
+ *   variant="destructive"
+ *   onClick={() => handleDelete()}
+ *   aria-describedby="delete-warning"
+ * >
+ *   Delete Account
+ * </Button>
+ * <p id="delete-warning" className="sr-only">
+ *   This action cannot be undone
+ * </p>
+ *
+ * // Toggle button with pressed state
+ * <Button
+ *   variant="outline"
+ *   aria-pressed={isToggled}
+ *   onClick={() => setIsToggled(!isToggled)}
+ * >
+ *   {isToggled ? "Enabled" : "Disabled"}
+ * </Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Loading states and advanced usage
+ * import { Loader2, Save } from "lucide-react";
+ *
+ * <Button disabled={isLoading}>
+ *   {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+ *   {isLoading ? "Saving..." : "Save Changes"}
+ * </Button>
+ *
+ * // With custom styling
+ * <Button
+ *   className="bg-gradient-to-r from-purple-500 to-pink-500 hover:from-purple-600 hover:to-pink-600"
+ *   size="lg"
+ * >
+ *   Gradient Button
  * </Button>
  * ```
  *
  * @accessibility
- * - Supports keyboard navigation (Enter/Space to activate)
- * - Properly handles disabled state with pointer-events-none and opacity
- * - Focus visible ring (3px ring-ring/50) for keyboard navigation
- * - Supports aria-invalid for form validation states with destructive ring
- * - Icons are automatically marked as non-interactive (pointer-events-none)
- * - Screen reader friendly with proper semantic button element
- * - When used with asChild, preserves accessibility of child element
- * - Icon-only buttons should include aria-label for screen readers
- *
- * @see {@link buttonVariants} - For all available style variants and sizes
- * @see {@link https://ui.shadcn.com/docs/components/button} - shadcn/ui button documentation
+ * - Full keyboard support (Enter/Space activation, Tab navigation)
+ * - ARIA attributes for screen readers (role="button" implicit)
+ * - Focus management with visible focus indicators (3px ring)
+ * - Disabled state properly communicated to assistive technologies
+ * - Support for ARIA states (pressed, expanded, invalid, controls)
+ * - Icon-only buttons require aria-label for screen reader users
+ * - Form integration with proper submit/reset behavior
+ * - High contrast focus indicators that meet WCAG 2.1 AA standards
+ * - Respects user's reduced motion preferences in transitions
+ * - When using asChild, accessibility is inherited from the child element
+ *
+ * @variant default - Primary action button with brand colors and subtle shadow
+ * @variant destructive - For dangerous actions (delete, remove) with red theming
+ * @variant outline - Secondary actions with border and subtle background on hover
+ * @variant secondary - Alternative styling with muted background colors
+ * @variant ghost - Minimal appearance with hover states, ideal for toolbars
+ * @variant link - Appears as a text link with underline on hover
+ *
+ * @size default - Standard height (36px) suitable for most interfaces
+ * @size sm - Compact height (32px) for dense layouts or secondary actions
+ * @size lg - Large height (40px) for prominent primary actions
+ * @size icon - Square (36px × 36px) optimized for single icons
+ *
+ * @see {@link buttonVariants} CVA configuration with all styling variants
+ * @see {@link https://ui.shadcn.com/docs/components/button} shadcn/ui Button documentation
+ * @see {@link https://www.radix-ui.com/primitives/docs/utilities/slot} Radix UI Slot for composition patterns
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/button/} WAI-ARIA Button Pattern
  * @since 1.0.0
  */
-/**
- * Button component props type
- *
- * Extends all standard HTML button attributes with additional variant and composition props.
- */
-type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
-    /**
-     * If true, the button will render its child element instead of a button element.
-     * This enables composition patterns like turning links into buttons.
-     *
-     * @example
-     * ```tsx
-     * <Button asChild>
-     *   <Link href="/dashboard">Dashboard</Link>
-     * </Button>
-     * ```
-     *
-     * @default false
-     */
-    asChild?: boolean;
-};
-declare function Button({ className, variant, size, asChild, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+declare function Button({ className, variant, size, asChild, ...props }: ButtonDocsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Button {
     var displayName: string;
 }
-export { Button, buttonVariants, type ButtonProps };
+export { Button, buttonVariants };
 //# sourceMappingURL=button.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../../src/components/ui/button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAIlE;;;;;;;;GAQG;AACH,QAAA,MAAM,cAAc;;;8EA+CnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH;;;;GAIG;AACH,KAAK,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,GAC/C,YAAY,CAAC,OAAO,cAAc,CAAC,GAAG;IACpC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEJ,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,OAAO,EACP,IAAI,EACJ,OAAe,EACf,GAAG,KAAK,EACT,EAAE,WAAW,2CAUb;kBAhBQ,MAAM;;;AAoBf,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,CAAC"}
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../../src/components/ui/button.tsx"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,16 @@
 import * as React from "react";
 import { DayButton, DayPicker } from "react-day-picker";
-import { Button } from "@/components/ui/button";
+/**
+ * Actual props type used by the Calendar component implementation
+ * Uses react-day-picker's inferred types for perfect compatibility
+ */
+type CalendarProps = React.ComponentProps<typeof DayPicker> & {
+    /**
+     * Button variant for navigation arrows and interactive elements
+     * @default "ghost"
+     */
+    buttonVariant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
+};
 /**
  * Calendar - A comprehensive date selection calendar component
  *
@@ -8,6 +18,10 @@ import { Button } from "@/components/ui/button";
  * date selection with extensive customization options. Supports single dates, date ranges,
  * multiple dates, and custom validation rules with built-in accessibility features.
  *
+ * Built on the powerful react-day-picker library, this component provides a complete
+ * calendar interface with advanced features like custom formatters, modifiers, disabled
+ * dates, localization, and extensive styling options.
+ *
  * @component
  *
  * @example Basic single date selection
@@ -35,7 +49,7 @@ import { Button } from "@/components/ui/button";
  * />
  * ```
  *
- * @example Multiple date selection
+ * @example Multiple date selection with limits
  * ```tsx
  * const [dates, setDates] = useState<Date[] | undefined>()
  *
@@ -43,6 +57,8 @@ import { Button } from "@/components/ui/button";
  *   mode="multiple"
  *   selected={dates}
  *   onSelect={setDates}
+ *   min={2} // Minimum 2 dates required
+ *   max={5} // Maximum 5 dates allowed
  *   className="rounded-md border"
  * />
  * ```
@@ -62,7 +78,7 @@ import { Button } from "@/components/ui/button";
  * />
  * ```
  *
- * @example Calendar with month/year dropdowns
+ * @example Calendar with month/year dropdowns and navigation limits
  * ```tsx
  * <Calendar
  *   mode="single"
@@ -71,57 +87,197 @@ import { Button } from "@/components/ui/button";
  *   onSelect={setDate}
  *   fromYear={2020}
  *   toYear={2030}
+ *   startMonth={new Date(2023, 0)} // Don't go before Jan 2023
+ *   endMonth={new Date(2025, 11)} // Don't go past Dec 2025
+ *   className="rounded-md border"
+ * />
+ * ```
+ *
+ * @example International calendar with custom locale
+ * ```tsx
+ * import { es } from 'date-fns/locale'
+ *
+ * <Calendar
+ *   mode="single"
+ *   selected={date}
+ *   onSelect={setDate}
+ *   locale={es} // Spanish locale
+ *   weekStartsOn={1} // Start weeks on Monday
+ *   dir="ltr"
  *   className="rounded-md border"
  * />
  * ```
  *
+ * @example Calendar with custom formatters and styling
+ * ```tsx
+ * <Calendar
+ *   mode="single"
+ *   showWeekNumber
+ *   formatters={{
+ *     formatDay: (date) => date.getDate().toString(),
+ *     formatWeekNumber: (weekNumber) => `W${weekNumber}`,
+ *     formatMonthCaption: (date) =>
+ *       date.toLocaleDateString('en', { month: 'long', year: 'numeric' })
+ *   }}
+ *   classNames={{
+ *     day: "hover:bg-blue-100 transition-colors",
+ *     selected: "bg-blue-500 text-white font-semibold",
+ *     today: "bg-blue-100 font-bold"
+ *   }}
+ *   className="rounded-lg border-2 shadow-lg"
+ * />
+ * ```
+ *
+ * @example Calendar with custom modifiers and event handling
+ * ```tsx
+ * const holidays = [new Date(2024, 11, 25), new Date(2024, 0, 1)]
+ * const weekends = { dayOfWeek: [0, 6] }
+ *
+ * <Calendar
+ *   mode="single"
+ *   modifiers={{
+ *     holiday: holidays,
+ *     weekend: weekends,
+ *     available: (date) => availableDates.includes(date.toDateString())
+ *   }}
+ *   onDayClick={(day, modifiers) => {
+ *     if (modifiers.holiday) {
+ *       alert('Holiday selected!')
+ *     }
+ *   }}
+ *   onWeekNumberClick={(weekNumber, dates) => {
+ *     console.log(`Week ${weekNumber} contains:`, dates)
+ *   }}
+ *   classNames={{
+ *     holiday: "bg-red-100 text-red-800",
+ *     weekend: "bg-gray-100 text-gray-600",
+ *     available: "bg-green-100 text-green-800"
+ *   }}
+ * />
+ * ```
+ *
+ * @example Calendar with custom components
+ * ```tsx
+ * <Calendar
+ *   mode="single"
+ *   components={{
+ *     DayContent: ({ date }) => (
+ *       <div className="relative">
+ *         {date.getDate()}
+ *         {date.getDate() === 1 && (
+ *           <span className="absolute -top-1 -right-1 text-xs">🎉</span>
+ *         )}
+ *       </div>
+ *     ),
+ *     MonthCaption: ({ displayMonth }) => (
+ *       <div className="flex items-center justify-center py-2">
+ *         <h2 className="text-lg font-bold text-blue-600">
+ *           {displayMonth.toLocaleDateString('en', {
+ *             month: 'long',
+ *             year: 'numeric'
+ *           })}
+ *         </h2>
+ *       </div>
+ *     )
+ *   }}
+ * />
+ * ```
+ *
+ * @example Advanced range selection with custom styling
+ * ```tsx
+ * const [dateRange, setDateRange] = useState<DateRange>()
+ *
+ * <Calendar
+ *   mode="range"
+ *   selected={dateRange}
+ *   onSelect={setDateRange}
+ *   numberOfMonths={2}
+ *   showOutsideDays={false}
+ *   fixedWeeks
+ *   classNames={{
+ *     range_start: "bg-blue-500 text-white rounded-l-md",
+ *     range_end: "bg-blue-500 text-white rounded-r-md",
+ *     range_middle: "bg-blue-100 text-blue-900",
+ *     selected: "bg-blue-500 text-white"
+ *   }}
+ *   footer={dateRange && (
+ *     <div className="p-3 border-t">
+ *       <p className="text-sm text-gray-600">
+ *         {dateRange.from && `From: ${dateRange.from.toLocaleDateString()}`}
+ *         {dateRange.to && ` • To: ${dateRange.to.toLocaleDateString()}`}
+ *         {dateRange.from && dateRange.to && (
+ *           ` • ${Math.ceil((dateRange.to.getTime() - dateRange.from.getTime()) / (1000 * 60 * 60 * 24) + 1)} days`
+ *         )}
+ *       </p>
+ *     </div>
+ *   )}
+ * />
+ * ```
+ *
  * @features
- * - **Selection modes**: Single date, date ranges, multiple dates
- * - **Navigation**: Month/year navigation with keyboard support
- * - **Validation**: Flexible date disabling and validation rules
- * - **Customization**: Multiple caption layouts, button variants, styling
- * - **Internationalization**: Built-in locale support via react-day-picker
- * - **Accessibility**: Full WCAG compliance with keyboard navigation
+ * - **Selection Modes**: Single date, date ranges, multiple dates, or no selection
+ * - **Navigation**: Month/year navigation with buttons or dropdowns, keyboard support
+ * - **Validation**: Flexible date disabling, custom matchers, min/max constraints
+ * - **Customization**: Custom formatters, modifiers, components, styling
+ * - **Internationalization**: Full locale support, RTL languages, custom week start
+ * - **Accessibility**: WCAG 2.1 AA compliant, screen reader support, keyboard navigation
+ * - **Performance**: Optimized rendering, minimal re-renders, efficient DOM updates
  *
  * @accessibility
- * - **Keyboard Navigation**: Arrow keys for date navigation, Page Up/Down for months
- * - **Screen Reader Support**: Comprehensive ARIA labels and announcements
- * - **Focus Management**: Proper focus handling and restoration
- * - **Standards Compliance**: WCAG 2.1 AA compliant
- * - **RTL Support**: Right-to-left language support
+ * - **Keyboard Navigation**:
+ *   - Arrow keys navigate between dates
+ *   - Page Up/Down navigate months
+ *   - Home/End navigate to start/end of week
+ *   - Ctrl+Page Up/Down navigate years
+ *   - Enter/Space select dates
+ *   - Escape closes popover/dropdown states
+ * - **Screen Reader Support**:
+ *   - Comprehensive ARIA labels and descriptions
+ *   - Live region announcements for month changes
+ *   - Proper role and state management
+ *   - Selected dates and ranges announced clearly
+ * - **Focus Management**:
+ *   - Visible focus indicators with 3px ring
+ *   - Focus restoration after month navigation
+ *   - Logical tab order through interactive elements
+ *   - Trapped focus in dropdown modes
+ * - **Standards Compliance**:
+ *   - WCAG 2.1 AA color contrast requirements
+ *   - Proper heading structure and landmarks
+ *   - Compatible with screen readers and assistive technology
+ * - **RTL Support**:
+ *   - Right-to-left text direction support
+ *   - Mirrored navigation button orientation
+ *   - Locale-aware date formatting
  *
  * @performance
- * The component is optimized for performance with minimal re-renders and efficient
- * DOM updates. Large date ranges and multiple months are handled efficiently.
+ * - **Optimized Rendering**: Minimal re-renders through memoization and efficient state management
+ * - **Large Date Ranges**: Efficiently handles calendars spanning multiple months and years
+ * - **Event Handling**: Debounced and optimized event handlers for smooth interactions
+ * - **Memory Management**: Proper cleanup and garbage collection for long-running applications
+ * - **Bundle Size**: Tree-shakeable with minimal runtime overhead
  *
  * @styling
- * Fully customizable with Tailwind CSS classes. Supports CSS custom properties
- * for cell sizing (`--cell-size`) and integrates with the design system theme.
+ * - **Design System Integration**: Built with shadcn/ui design tokens and Tailwind CSS
+ * - **CSS Custom Properties**: Supports `--cell-size` and other CSS variables for sizing
+ * - **Theming**: Dark mode support and custom theme integration
+ * - **Responsive**: Mobile-friendly with touch interactions and responsive layouts
+ * - **Customizable**: Override any visual aspect through classNames, components, or CSS
  *
- * @see {@link CalendarDayButton} Individual day button component
- * @see [react-day-picker docs](https://react-day-picker.js.org/) for advanced configuration
- * @see {@link https://ui.shadcn.com/docs/components/calendar} - shadcn/ui Calendar documentation
+ * @browser-support
+ * - **Modern Browsers**: Chrome 91+, Firefox 90+, Safari 15+, Edge 91+
+ * - **Mobile**: iOS Safari 15+, Android Chrome 91+
+ * - **Accessibility**: Compatible with NVDA, JAWS, VoiceOver screen readers
+ *
+ * @see {@link CalendarDayButton} Individual day button component with custom styling
+ * @see {@link CalendarProps} Complete props interface with TypeScript definitions
+ * @see {@link https://react-day-picker.js.org/} react-day-picker documentation for advanced configuration
+ * @see {@link https://ui.shadcn.com/docs/components/calendar} shadcn/ui Calendar documentation
+ * @see {@link https://date-fns.org/docs/I18n} date-fns internationalization guide
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/} WAI-ARIA Authoring Practices Guide
  * @since 1.0.0
  */
-declare function Calendar({ className, classNames, showOutsideDays, captionLayout, buttonVariant, formatters, components, ...props }: React.ComponentProps<typeof DayPicker> & {
-    /**
-     * Button variant for navigation arrows and interactive elements
-     *
-     * Controls the visual style of the previous/next month navigation buttons.
-     * Choose from shadcn/ui button variants to match your design system.
-     *
-     * @default "ghost"
-     * @example
-     * ```tsx
-     * // Outline style navigation buttons
-     * <Calendar buttonVariant="outline" />
-     *
-     * // Secondary style for subtle navigation
-     * <Calendar buttonVariant="secondary" />
-     * ```
-     */
-    buttonVariant?: React.ComponentProps<typeof Button>["variant"];
-}): import("react/jsx-runtime").JSX.Element;
+declare function Calendar({ className, classNames, showOutsideDays, captionLayout, buttonVariant, formatters, components, ...props }: CalendarProps): import("react/jsx-runtime").JSX.Element;
 /**
  * CalendarDayButton - Individual day button component for calendar dates
  *
@@ -166,4 +322,5 @@ declare function Calendar({ className, classNames, showOutsideDays, captionLayou
  */
 declare function CalendarDayButton({ className, day, modifiers, ...props }: React.ComponentProps<typeof DayButton>): import("react/jsx-runtime").JSX.Element;
 export { Calendar, CalendarDayButton };
+export type { CalendarProps };
 //# sourceMappingURL=calendar.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/calendar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B,OAAO,EAAE,SAAS,EAAE,SAAS,EAAwB,MAAM,kBAAkB,CAAC;AAG9E,OAAO,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,iBAAS,QAAQ,CAAC,EAChB,SAAS,EACT,UAAU,EACV,eAAsB,EACtB,aAAuB,EACvB,aAAuB,EACvB,UAAU,EACV,UAAU,EACV,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,SAAS,CAAC,GAAG;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC;CAChE,2CAoJA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,GAAG,EACH,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,SAAS,CAAC,2CA+BxC;AAED,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/calendar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B,OAAO,EACL,SAAS,EACT,SAAS,EAIV,MAAM,kBAAkB,CAAC;AAioB1B;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,SAAS,CAAC,GAAG;IAC5D;;;OAGG;IACH,aAAa,CAAC,EACV,SAAS,GACT,aAAa,GACb,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,CAAC;CACZ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyQG;AACH,iBAAS,QAAQ,CAAC,EAChB,SAAS,EACT,UAAU,EACV,eAAsB,EACtB,aAAuB,EACvB,aAAuB,EACvB,UAAU,EACV,UAAU,EACV,GAAG,KAAK,EACT,EAAE,aAAa,2CAqKf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,iBAAS,iBAAiB,CAAC,EACzB,SAAS,EACT,GAAG,EACH,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,SAAS,CAAC,2CA+BxC;AAED,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,CAAC"}