@neynar/ui 0.1.1

package/src/components/ui/button.tsx

@@ -0,0 +1,195 @@
+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";
+
+/**
+ * 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.
+ *
+ * @see {@link https://cva.style/docs} - CVA documentation
+ * @since 1.0.0
+ */
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+  {
+    variants: {
+      /**
+       * Visual style variants for the button
+       *
+       * @variant default - Primary action button with brand colors
+       * @variant destructive - Dangerous actions (delete, remove, etc.)
+       * @variant outline - Secondary action with border
+       * @variant secondary - Alternative secondary styling
+       * @variant ghost - Minimal styling, often used in toolbars
+       * @variant link - Text-only button that looks like a link
+       */
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
+        ghost:
+          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      /**
+       * Size variants for the button
+       *
+       * @size default - Standard button height (36px)
+       * @size sm - Small button height (32px)
+       * @size lg - Large button height (40px)
+       * @size icon - Square button for icons only (36px × 36px)
+       */
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Button>Click me</Button>
+ * ```
+ *
+ * @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>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icons (automatically styled)
+ * import { Download, ArrowRight, Plus } from "lucide-react";
+ *
+ * <Button>
+ *   <Download /> Download File
+ * </Button>
+ *
+ * <Button>
+ *   Continue <ArrowRight />
+ * </Button>
+ *
+ * // Icon-only button
+ * <Button size="icon" aria-label="Add item">
+ *   <Plus />
+ * </Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // As other elements using asChild (composition pattern)
+ * import Link from "next/link";
+ *
+ * <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>
+ * </Button>
+ * ```
+ *
+ * @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>
+ * ```
+ *
+ * @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
+ * @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;
+  };
+
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: ButtonProps) {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+Button.displayName = "Button";
+
+export { Button, buttonVariants, type ButtonProps };

package/src/components/ui/calendar.tsx

@@ -0,0 +1,371 @@
+import * as React from "react";
+import {
+  ChevronDownIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+} from "lucide-react";
+import { DayButton, DayPicker, getDefaultClassNames } from "react-day-picker";
+
+import { cn } from "@/lib/utils";
+import { Button, buttonVariants } from "@/components/ui/button";
+
+/**
+ * Calendar - A comprehensive date selection calendar component
+ *
+ * A fully-featured calendar component built on react-day-picker that provides intuitive
+ * date selection with extensive customization options. Supports single dates, date ranges,
+ * multiple dates, and custom validation rules with built-in accessibility features.
+ *
+ * @component
+ *
+ * @example Basic single date selection
+ * ```tsx
+ * const [date, setDate] = useState<Date | undefined>()
+ *
+ * <Calendar
+ *   mode="single"
+ *   selected={date}
+ *   onSelect={setDate}
+ *   className="rounded-md border"
+ * />
+ * ```
+ *
+ * @example Date range selection with two months
+ * ```tsx
+ * const [dateRange, setDateRange] = useState<DateRange | undefined>()
+ *
+ * <Calendar
+ *   mode="range"
+ *   selected={dateRange}
+ *   onSelect={setDateRange}
+ *   numberOfMonths={2}
+ *   className="rounded-md border"
+ * />
+ * ```
+ *
+ * @example Multiple date selection
+ * ```tsx
+ * const [dates, setDates] = useState<Date[] | undefined>()
+ *
+ * <Calendar
+ *   mode="multiple"
+ *   selected={dates}
+ *   onSelect={setDates}
+ *   className="rounded-md border"
+ * />
+ * ```
+ *
+ * @example Calendar with disabled dates and custom validation
+ * ```tsx
+ * <Calendar
+ *   mode="single"
+ *   selected={date}
+ *   onSelect={setDate}
+ *   disabled={[
+ *     { before: new Date() }, // Disable past dates
+ *     { dayOfWeek: [0, 6] }, // Disable weekends
+ *     { from: new Date(2024, 0, 15), to: new Date(2024, 0, 20) } // Disable range
+ *   ]}
+ *   className="rounded-md border"
+ * />
+ * ```
+ *
+ * @example Calendar with month/year dropdowns
+ * ```tsx
+ * <Calendar
+ *   mode="single"
+ *   captionLayout="dropdown"
+ *   selected={date}
+ *   onSelect={setDate}
+ *   fromYear={2020}
+ *   toYear={2030}
+ *   className="rounded-md border"
+ * />
+ * ```
+ *
+ * @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
+ *
+ * @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
+ *
+ * @performance
+ * The component is optimized for performance with minimal re-renders and efficient
+ * DOM updates. Large date ranges and multiple months are handled efficiently.
+ *
+ * @styling
+ * Fully customizable with Tailwind CSS classes. Supports CSS custom properties
+ * for cell sizing (`--cell-size`) and integrates with the design system theme.
+ *
+ * @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
+ * @since 1.0.0
+ */
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  captionLayout = "label",
+  buttonVariant = "ghost",
+  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"];
+}) {
+  const defaultClassNames = getDefaultClassNames();
+
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn(
+        "bg-background group/calendar p-3 [--cell-size:--spacing(8)] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
+        String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
+        String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
+        className,
+      )}
+      captionLayout={captionLayout}
+      formatters={{
+        formatMonthDropdown: (date) =>
+          date.toLocaleString("default", { month: "short" }),
+        ...formatters,
+      }}
+      classNames={{
+        root: cn("w-fit", defaultClassNames.root),
+        months: cn(
+          "flex gap-4 flex-col md:flex-row relative",
+          defaultClassNames.months,
+        ),
+        month: cn("flex flex-col w-full gap-4", defaultClassNames.month),
+        nav: cn(
+          "flex items-center gap-1 w-full absolute top-0 inset-x-0 justify-between",
+          defaultClassNames.nav,
+        ),
+        button_previous: cn(
+          buttonVariants({ variant: buttonVariant }),
+          "size-(--cell-size) aria-disabled:opacity-50 p-0 select-none",
+          defaultClassNames.button_previous,
+        ),
+        button_next: cn(
+          buttonVariants({ variant: buttonVariant }),
+          "size-(--cell-size) aria-disabled:opacity-50 p-0 select-none",
+          defaultClassNames.button_next,
+        ),
+        month_caption: cn(
+          "flex items-center justify-center h-(--cell-size) w-full px-(--cell-size)",
+          defaultClassNames.month_caption,
+        ),
+        dropdowns: cn(
+          "w-full flex items-center text-sm font-medium justify-center h-(--cell-size) gap-1.5",
+          defaultClassNames.dropdowns,
+        ),
+        dropdown_root: cn(
+          "relative has-focus:border-ring border border-input shadow-xs has-focus:ring-ring/50 has-focus:ring-[3px] rounded-md",
+          defaultClassNames.dropdown_root,
+        ),
+        dropdown: cn(
+          "absolute bg-popover inset-0 opacity-0",
+          defaultClassNames.dropdown,
+        ),
+        caption_label: cn(
+          "select-none font-medium",
+          captionLayout === "label"
+            ? "text-sm"
+            : "rounded-md pl-2 pr-1 flex items-center gap-1 text-sm h-8 [&>svg]:text-muted-foreground [&>svg]:size-3.5",
+          defaultClassNames.caption_label,
+        ),
+        table: "w-full border-collapse",
+        weekdays: cn("flex", defaultClassNames.weekdays),
+        weekday: cn(
+          "text-muted-foreground rounded-md flex-1 font-normal text-[0.8rem] select-none",
+          defaultClassNames.weekday,
+        ),
+        week: cn("flex w-full mt-2", defaultClassNames.week),
+        week_number_header: cn(
+          "select-none w-(--cell-size)",
+          defaultClassNames.week_number_header,
+        ),
+        week_number: cn(
+          "text-[0.8rem] select-none text-muted-foreground",
+          defaultClassNames.week_number,
+        ),
+        day: cn(
+          "relative w-full h-full p-0 text-center [&:first-child[data-selected=true]_button]:rounded-l-md [&:last-child[data-selected=true]_button]:rounded-r-md group/day aspect-square select-none",
+          defaultClassNames.day,
+        ),
+        range_start: cn(
+          "rounded-l-md bg-accent",
+          defaultClassNames.range_start,
+        ),
+        range_middle: cn("rounded-none", defaultClassNames.range_middle),
+        range_end: cn("rounded-r-md bg-accent", defaultClassNames.range_end),
+        today: cn(
+          "bg-accent text-accent-foreground rounded-md data-[selected=true]:rounded-none",
+          defaultClassNames.today,
+        ),
+        outside: cn(
+          "text-muted-foreground aria-selected:text-muted-foreground",
+          defaultClassNames.outside,
+        ),
+        disabled: cn(
+          "text-muted-foreground opacity-50",
+          defaultClassNames.disabled,
+        ),
+        hidden: cn("invisible", defaultClassNames.hidden),
+        ...classNames,
+      }}
+      components={{
+        Root: ({ className, rootRef, ...props }: { className?: string; rootRef?: React.Ref<HTMLDivElement> } & React.ComponentProps<"div">) => {
+          return (
+            <div
+              data-slot="calendar"
+              ref={rootRef}
+              className={cn(className)}
+              {...props}
+            />
+          );
+        },
+        Chevron: ({ className, orientation, ...props }: { className?: string; orientation?: "left" | "right" | "up" | "down" } & React.ComponentProps<"svg">) => {
+          if (orientation === "left") {
+            return (
+              <ChevronLeftIcon className={cn("size-4", className)} {...props} />
+            );
+          }
+
+          if (orientation === "right") {
+            return (
+              <ChevronRightIcon
+                className={cn("size-4", className)}
+                {...props}
+              />
+            );
+          }
+
+          return (
+            <ChevronDownIcon className={cn("size-4", className)} {...props} />
+          );
+        },
+        DayButton: CalendarDayButton,
+        WeekNumber: ({ children, ...props }) => {
+          return (
+            <td {...props}>
+              <div className="flex size-(--cell-size) items-center justify-center text-center">
+                {children}
+              </div>
+            </td>
+          );
+        },
+        ...components,
+      }}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CalendarDayButton - Individual day button component for calendar dates
+ *
+ * Renders a single interactive day button with appropriate styling for different states
+ * including selected, today, disabled, and range selection indicators. This component
+ * is used internally by the Calendar component but can be customized if needed.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Used internally by Calendar component
+ * <CalendarDayButton
+ *   day={dayObject}
+ *   modifiers={{
+ *     selected: true,
+ *     today: false,
+ *     disabled: false,
+ *     range_start: false,
+ *     range_end: false,
+ *     range_middle: false
+ *   }}
+ * />
+ * ```
+ *
+ * @param day - The day object containing date information from react-day-picker
+ * @param modifiers - State modifiers object controlling appearance and behavior
+ * @param modifiers.selected - Whether this day is currently selected
+ * @param modifiers.today - Whether this day represents today's date
+ * @param modifiers.disabled - Whether this day is disabled for selection
+ * @param modifiers.range_start - Whether this day is the start of a date range
+ * @param modifiers.range_end - Whether this day is the end of a date range
+ * @param modifiers.range_middle - Whether this day is in the middle of a date range
+ * @param modifiers.focused - Whether this day currently has keyboard focus
+ *
+ * @accessibility
+ * - **Keyboard Navigation**: Fully keyboard accessible with arrow key support
+ * - **Screen Reader Support**: Announces date and selection state to assistive technology
+ * - **Focus Management**: Proper focus indicators and focus restoration
+ * - **State Announcement**: Clear visual and auditory feedback for selection states
+ *
+ * @since 1.0.0
+ */
+function CalendarDayButton({
+  className,
+  day,
+  modifiers,
+  ...props
+}: React.ComponentProps<typeof DayButton>) {
+  const defaultClassNames = getDefaultClassNames();
+
+  const ref = React.useRef<HTMLButtonElement>(null);
+  React.useEffect(() => {
+    if (modifiers.focused) ref.current?.focus();
+  }, [modifiers.focused]);
+
+  return (
+    <Button
+      ref={ref}
+      variant="ghost"
+      size="icon"
+      data-day={day.date.toLocaleDateString()}
+      data-selected-single={
+        modifiers.selected &&
+        !modifiers.range_start &&
+        !modifiers.range_end &&
+        !modifiers.range_middle
+      }
+      data-range-start={modifiers.range_start}
+      data-range-end={modifiers.range_end}
+      data-range-middle={modifiers.range_middle}
+      className={cn(
+        "data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring/50 dark:hover:text-accent-foreground flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-[3px] data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md [&>span]:text-xs [&>span]:opacity-70",
+        defaultClassNames.day,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Calendar, CalendarDayButton };