@arolariu/components 0.5.0 → 1.1.0

package/src/index.ts

@@ -1,3 +1,18 @@
+// @arolariu/components — Base UI + CSS Modules component library
+// Version 1.0.0 — Built on @base-ui/react primitives
+
+// ============================================================
+// Base UI Utilities (re-exported for consumer convenience)
+// ============================================================
+export {CSPProvider} from "@base-ui/react/csp-provider";
+export {DirectionProvider} from "@base-ui/react/direction-provider";
+export {mergeProps} from "@base-ui/react/merge-props";
+export {useRender} from "@base-ui/react/use-render";
+
+// ============================================================
+// Components
+// ============================================================
+
 export {Accordion, AccordionContent, AccordionItem, AccordionTrigger} from "./components/ui/accordion";
 
 export {
@@ -15,12 +30,14 @@ export {
 } from "./components/ui/alert-dialog";
 
 export {Alert, AlertDescription, AlertTitle} from "./components/ui/alert";
+export type {AlertProps, AlertVariant} from "./components/ui/alert";
 
 export {AspectRatio} from "./components/ui/aspect-ratio";
 
 export {Avatar, AvatarFallback, AvatarImage} from "./components/ui/avatar";
 
 export {Badge, badgeVariants} from "./components/ui/badge";
+export type {BadgeProps, BadgeVariant} from "./components/ui/badge";
 
 export {
   Breadcrumb,
@@ -33,29 +50,115 @@ export {
 } from "./components/ui/breadcrumb";
 
 export {Button, buttonVariants} from "./components/ui/button";
+export type {ButtonProps, ButtonSize, ButtonState, ButtonVariant} from "./components/ui/button";
 
 export {ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants} from "./components/ui/button-group";
 
 export {Calendar} from "./components/ui/calendar";
+export type {CalendarProps, DateRange, DayPickerProps, Matcher} from "./components/ui/calendar";
 
 export {Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle} from "./components/ui/card";
 
 export {Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, type CarouselApi} from "./components/ui/carousel";
+export type {CarouselOptions, CarouselPlugin, CarouselProps} from "./components/ui/carousel";
+
+export {CheckboxGroup} from "./components/ui/checkbox-group";
 
 export {
+  // Recharts series elements
+  Area,
+  // Recharts chart containers
+  AreaChart,
+  Bar,
+  BarChart,
+  BarStack,
+  // Recharts annotations & overlays
+  Brush,
+  // Recharts axis & grid
+  CartesianGrid,
+  // Recharts shapes
+  Cell,
   ChartContainer,
   ChartLegend,
   ChartLegendContent,
   ChartStyle,
   ChartTooltip,
   ChartTooltipContent,
+  ComposedChart,
+  Cross,
+  Curve,
+  Customized,
+  DefaultZIndexes,
+  Dot,
+  ErrorBar,
+  Funnel,
+  FunnelChart,
+  LabelList,
+  Line,
+  LineChart,
+  Pie,
+  PieChart,
+  PolarAngleAxis,
+  PolarGrid,
+  PolarRadiusAxis,
+  Polygon,
+  Radar,
+  RadarChart,
+  RadialBar,
+  RadialBarChart,
+  RechartsLabel,
+  Rectangle,
+  ReferenceArea,
+  ReferenceDot,
+  ReferenceLine,
+  // Recharts layout
+  ResponsiveContainer,
+  Sankey,
+  Scatter,
+  ScatterChart,
+  Sector,
+  SunburstChart,
+  Symbols,
+  Trapezoid,
+  Treemap,
+  XAxis,
+  YAxis,
+  ZAxis,
+  // Recharts z-index (v3.4+)
+  ZIndexLayer,
+  useActiveTooltipCoordinate,
+  useActiveTooltipDataPoints,
+  useActiveTooltipLabel,
+  useChartHeight,
+  // Recharts hooks (v3+)
+  useChartWidth,
+  useIsTooltipActive,
+  useMargin,
+  useOffset,
+  usePlotArea,
+  useXAxisDomain,
+  useYAxisDomain,
   type ChartConfig,
+  type DefaultLegendContentProps,
+  // Recharts types
+  type DefaultTooltipContentProps,
+  type TooltipValueType,
 } from "./components/ui/chart";
 
 export {Checkbox} from "./components/ui/checkbox";
 
 export {Collapsible, CollapsibleContent, CollapsibleTrigger} from "./components/ui/collapsible";
 
+export {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxItem,
+  ComboboxSeparator,
+  ComboboxTrigger,
+} from "./components/ui/combobox";
+
 export {
   Command,
   CommandDialog,
@@ -145,11 +248,62 @@ export {
   FieldTitle,
 } from "./components/ui/field";
 
-export {Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField} from "./components/ui/form";
+export {
+  Controller,
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  useController,
+  useFieldArray,
+  useForm,
+  useFormContext,
+  useFormField,
+  useFormState,
+  useWatch,
+  type FormControlProps,
+} from "./components/ui/form";
+export type {
+  Control,
+  ControllerFieldState,
+  ControllerProps,
+  ControllerRenderProps,
+  DefaultValues,
+  FieldErrors,
+  FieldPath,
+  FieldValues,
+  Path,
+  FieldError as RHFFieldError,
+  RegisterOptions,
+  Resolver,
+  SubmitHandler,
+  UseControllerReturn,
+  UseFieldArrayReturn,
+  UseFormReturn,
+} from "./components/ui/form";
 
 export {HoverCard, HoverCardContent, HoverCardTrigger} from "./components/ui/hover-card";
 
-export {InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot} from "./components/ui/input-otp";
+export {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+  REGEXP_ONLY_CHARS,
+  REGEXP_ONLY_DIGITS,
+  REGEXP_ONLY_DIGITS_AND_CHARS,
+} from "./components/ui/input-otp";
+export type {
+  InputOTPGroupProps,
+  InputOTPProps,
+  InputOTPSeparatorProps,
+  InputOTPSlotProps,
+  OTPInputProps,
+  SlotProps,
+} from "./components/ui/input-otp";
 
 export {Input} from "./components/ui/input";
 
@@ -179,6 +333,8 @@ export {Kbd, KbdGroup} from "./components/ui/kbd";
 
 export {Label} from "./components/ui/label";
 
+export {Meter, MeterIndicator, MeterLabel, MeterTrack} from "./components/ui/meter";
+
 export {
   Menubar,
   MenubarCheckboxItem,
@@ -210,6 +366,15 @@ export {
   navigationMenuTriggerStyle,
 } from "./components/ui/navigation-menu";
 
+export {
+  NumberField,
+  NumberFieldDecrement,
+  NumberFieldGroup,
+  NumberFieldIncrement,
+  NumberFieldInput,
+  NumberFieldScrubArea,
+} from "./components/ui/number-field";
+
 export {
   Pagination,
   PaginationContent,
@@ -227,6 +392,13 @@ export {Progress} from "./components/ui/progress";
 export {RadioGroup, RadioGroupItem} from "./components/ui/radio-group";
 
 export {ResizableHandle, ResizablePanel, ResizablePanelGroup} from "./components/ui/resizable";
+export type {
+  ImperativePanelGroupHandle,
+  ImperativePanelHandle,
+  ResizableHandleProps,
+  ResizablePanelGroupProps,
+  ResizablePanelProps,
+} from "./components/ui/resizable";
 
 export {ScrollArea, ScrollBar} from "./components/ui/scroll-area";
 
@@ -292,6 +464,7 @@ export {Spinner} from "./components/ui/spinner";
 export {Slider} from "./components/ui/slider";
 
 export {Toaster, toast} from "./components/ui/sonner";
+export type {Toast} from "./components/ui/sonner";
 
 export {Switch} from "./components/ui/switch";
 
@@ -301,19 +474,54 @@ export {Tabs, TabsContent, TabsList, TabsTrigger} from "./components/ui/tabs";
 
 export {Textarea} from "./components/ui/textarea";
 
+export {Toolbar, ToolbarButton, ToolbarGroup, ToolbarLink, ToolbarSeparator} from "./components/ui/toolbar";
+
 export {ToggleGroup, ToggleGroupItem} from "./components/ui/toggle-group";
+export type {ToggleGroupItemProps, ToggleGroupProps} from "./components/ui/toggle-group";
 
 export {Toggle, toggleVariants} from "./components/ui/toggle";
+export type {ToggleProps, ToggleSize, ToggleVariant} from "./components/ui/toggle";
 
 export {Tooltip, TooltipContent, TooltipProvider, TooltipTrigger} from "./components/ui/tooltip";
 
+export {CopyButton, type CopyButtonProps} from "./components/ui/copy-button";
+export {Stepper, type StepperProps} from "./components/ui/stepper";
+export {
+  Timeline,
+  TimelineContent,
+  TimelineDot,
+  TimelineItem,
+  type TimelineContentProps,
+  type TimelineDotProps,
+  type TimelineItemProps,
+  type TimelineProps,
+} from "./components/ui/timeline";
+export {VisuallyHidden, type VisuallyHiddenProps} from "./components/ui/visually-hidden";
+
+export {useBreakpoint, type Breakpoint} from "./hooks/useBreakpoint";
+export {useClipboard, type UseClipboardOptions, type UseClipboardReturn} from "./hooks/useClipboard";
+export {useColorScheme, type ColorScheme} from "./hooks/useColorScheme";
+export {useControllableState, type UseControllableStateOptions} from "./hooks/useControllableState";
+export {useDebounce} from "./hooks/useDebounce";
+export {useEventCallback} from "./hooks/useEventCallback";
+export {useFocusVisible} from "./hooks/useFocusVisible";
+export {useId} from "./hooks/useId";
+export {useIntersectionObserver} from "./hooks/useIntersectionObserver";
+export {useInterval} from "./hooks/useInterval";
 export {useIsMobile} from "./hooks/useIsMobile";
+export {useLocalStorage} from "./hooks/useLocalStorage";
+export {useMediaQuery} from "./hooks/useMediaQuery";
+export {useMergedRefs} from "./hooks/useMergedRefs";
+export {useOnClickOutside} from "./hooks/useOnClickOutside";
+export {usePrefersContrast} from "./hooks/usePrefersContrast";
+export {usePrevious} from "./hooks/usePrevious";
+export {useReducedMotion} from "./hooks/useReducedMotion";
+export {useThrottle} from "./hooks/useThrottle";
+export {useTimeout} from "./hooks/useTimeout";
 export {useWindowSize} from "./hooks/useWindowSize";
 
 export {
-  // New descriptive names
   adjustHexColorLightness,
-  // Legacy aliases (deprecated)
   adjustLightness,
   calculateComplementaryHexColor,
   convertHexToHslString,
@@ -327,25 +535,18 @@ export {
   validateHexColorFormat,
 } from "./lib/color-conversion-utilities";
 export {cn} from "./lib/utilities";
+export type {ClassValue} from "./lib/utilities";
 
 // Animate-UI exports:
-export {FlipButton, type FlipButtonProps, type FlipDirection} from "./components/ui/flip-button";
-
-export {RippleButton, type RippleButtonProps} from "./components/ui/ripple-button";
-
-export {CountingNumber, type CountingNumberProps} from "./components/ui/counting-number";
-
-export {GradientText, type GradientTextProps} from "./components/ui/gradient-text";
-
-export {HighlightText, type HighlightTextProps} from "./components/ui/highlight-text";
-
 export {BubbleBackground, type BubbleBackgroundProps} from "./components/ui/bubble-background";
-
+export {CountingNumber, type CountingNumberProps} from "./components/ui/counting-number";
 export {FireworksBackground, type FireworksBackgroundProps} from "./components/ui/fireworks-background";
-
+export {FlipButton, type FlipButtonProps, type FlipDirection} from "./components/ui/flip-button";
 export {GradientBackground, type GradientBackgroundProps} from "./components/ui/gradient-background";
-
+export {GradientText, type GradientTextProps} from "./components/ui/gradient-text";
+export {HighlightText, type HighlightTextProps} from "./components/ui/highlight-text";
 export {HoleBackground, type HoleBackgroundProps} from "./components/ui/hole-background";
+export {RippleButton, type RippleButtonProps} from "./components/ui/ripple-button";
 
 // Magic UI exports:
 export {DotBackground} from "./components/ui/dot-background";
@@ -355,7 +556,7 @@ export {Scratcher} from "./components/ui/scratcher";
 export {BackgroundBeams} from "./components/ui/background-beams";
 export {TypewriterText, TypewriterTextSmooth} from "./components/ui/typewriter";
 
-// Jia Wei Ng export (https://github.com/jiaweing/DropDrawer):
+// DropDrawer export:
 export {
   DropDrawer,
   DropDrawerContent,

package/src/lib/utilities.ts

@@ -1,12 +1,13 @@
-import {clsx, type ClassValue} from "clsx";
-import {twMerge} from "tailwind-merge";
+import {clsx} from "clsx";
+
+export type {ClassValue} from "clsx";
 
 /**
- * Helper function that merges tailwindcss
- * class names in the given input array.
+ * Helper function that merges CSS class names.
+ * Uses clsx for conditional class name composition.
  * @param inputs Array of class names
- * @returns Merged class names
+ * @returns Merged class names string
  */
-export function cn(...inputs: ReadonlyArray<ClassValue>): Readonly<string> {
-  return twMerge(clsx(inputs));
+export function cn(...inputs: ReadonlyArray<import("clsx").ClassValue>): string {
+  return clsx(inputs);
 }

package/src/motion/Collapse.module.css

@@ -0,0 +1,22 @@
+.collapse {
+  display: grid;
+  grid-template-rows: 0fr;
+  overflow: hidden;
+  transition: grid-template-rows var(--ac-transition-normal), opacity var(--ac-transition-normal);
+  opacity: 0;
+}
+
+.collapse[data-state="open"] {
+  grid-template-rows: 1fr;
+  opacity: 1;
+}
+
+.inner {
+  min-height: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .collapse {
+    transition: none;
+  }
+}

package/src/motion/Collapse.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import * as React from "react";
+
+import {cn} from "@/lib/utilities";
+import styles from "./Collapse.module.css";
+
+/**
+ * Represents the configurable props for the {@link Collapse} component.
+ *
+ * @remarks
+ * Extends native `<div>` attributes so consumers can provide ARIA metadata,
+ * testing hooks, and custom classes while keeping the animated container typed.
+ */
+interface CollapseProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Whether the content is expanded.
+   */
+  open: boolean;
+  /**
+   * Content to show or hide with animation.
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Animated height collapse and expand using CSS grid-template-rows.
+ *
+ * @remarks
+ * Supports reduced motion through a CSS `prefers-reduced-motion` media query and keeps
+ * content mounted so assistive technologies and measurement logic remain stable.
+ *
+ * @example
+ * ```tsx
+ * <Collapse open={isExpanded}>
+ *   <p>Collapsible content</p>
+ * </Collapse>
+ * ```
+ */
+const Collapse = React.forwardRef<HTMLDivElement, CollapseProps>(({open, children, className, ...props}, ref) => (
+  <div
+    ref={ref}
+    data-state={open ? "open" : "closed"}
+    className={cn(styles.collapse, className)}
+    {...props}>
+    <div className={styles.inner}>{children}</div>
+  </div>
+));
+Collapse.displayName = "Collapse";
+
+export {Collapse};
+export type {CollapseProps};

package/src/motion/Presence.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import {AnimatePresence} from "motion/react";
+import * as React from "react";
+
+/**
+ * Represents the configurable props for the {@link Presence} component.
+ */
+interface PresenceProps {
+  /**
+   * Whether the child should be mounted and visible.
+   */
+  present: boolean;
+  /**
+   * The animated child element.
+   */
+  children: React.ReactNode;
+  /**
+   * AnimatePresence mode.
+   * @default "sync"
+   */
+  mode?: "wait" | "sync" | "popLayout";
+}
+
+/**
+ * Simplified mount/unmount animation wrapper built on `AnimatePresence`.
+ *
+ * @example
+ * ```tsx
+ * <Presence present={isOpen}>
+ *   <motion.div {...fadeIn}>Content</motion.div>
+ * </Presence>
+ * ```
+ *
+ * @see {@link https://motion.dev/docs/react-animate-presence | motion AnimatePresence}
+ */
+function Presence({present, children, mode = "sync"}: Readonly<PresenceProps>): React.JSX.Element {
+  return <AnimatePresence mode={mode}>{present ? children : null}</AnimatePresence>;
+}
+
+Presence.displayName = "Presence";
+
+export {Presence};
+export type {PresenceProps};

package/src/motion/index.ts

@@ -0,0 +1,13 @@
+// Motion tokens
+export {durations, easings, type Duration, type Easing} from "./tokens";
+
+// Animation presets
+export {fadeIn, fadeInDown, fadeInUp, reducedMotion, scaleIn, slideInFromLeft, slideInFromRight} from "./presets";
+
+// Components
+export {Collapse, type CollapseProps} from "./Collapse";
+export {Presence, type PresenceProps} from "./Presence";
+
+// Re-exports from motion/react for convenience
+export {AnimatePresence, motion, stagger, useAnimate, useAnimation, useInView, useMotionValue, useSpring} from "motion/react";
+export type {HTMLMotionProps, SpringOptions, Transition, UseInViewOptions, Variant} from "motion/react";

package/src/motion/presets.ts

@@ -0,0 +1,77 @@
+import {durations, easings} from "./tokens";
+
+/**
+ * Reusable animation variant presets for common transitions.
+ * Each preset includes `initial`, `animate`, and `exit` states.
+ * All presets respect reduced-motion preferences when used with `useReducedMotion`.
+ */
+
+/**
+ * Fades content in and out without positional movement.
+ */
+export const fadeIn = {
+  initial: {opacity: 0},
+  animate: {opacity: 1},
+  exit: {opacity: 0},
+  transition: {duration: durations.normal, ease: easings.ease},
+} as const;
+
+/**
+ * Fades content upward into view.
+ */
+export const fadeInUp = {
+  initial: {opacity: 0, y: 8},
+  animate: {opacity: 1, y: 0},
+  exit: {opacity: 0, y: 8},
+  transition: {duration: durations.normal, ease: easings.easeOut},
+} as const;
+
+/**
+ * Fades content downward into view.
+ */
+export const fadeInDown = {
+  initial: {opacity: 0, y: -8},
+  animate: {opacity: 1, y: 0},
+  exit: {opacity: 0, y: -8},
+  transition: {duration: durations.normal, ease: easings.easeOut},
+} as const;
+
+/**
+ * Fades and scales content into view.
+ */
+export const scaleIn = {
+  initial: {opacity: 0, scale: 0.95},
+  animate: {opacity: 1, scale: 1},
+  exit: {opacity: 0, scale: 0.95},
+  transition: {duration: durations.fast, ease: easings.easeOut},
+} as const;
+
+/**
+ * Slides content in from the left.
+ */
+export const slideInFromLeft = {
+  initial: {opacity: 0, x: -16},
+  animate: {opacity: 1, x: 0},
+  exit: {opacity: 0, x: -16},
+  transition: {duration: durations.slow, ease: easings.easeOut},
+} as const;
+
+/**
+ * Slides content in from the right.
+ */
+export const slideInFromRight = {
+  initial: {opacity: 0, x: 16},
+  animate: {opacity: 1, x: 0},
+  exit: {opacity: 0, x: 16},
+  transition: {duration: durations.slow, ease: easings.easeOut},
+} as const;
+
+/**
+ * No-op preset for reduced motion — instant state change, no animation.
+ */
+export const reducedMotion = {
+  initial: {},
+  animate: {},
+  exit: {},
+  transition: {duration: 0},
+} as const;

package/src/motion/tokens.ts

@@ -0,0 +1,37 @@
+/**
+ * Standard motion duration constants in seconds.
+ * Aligned with `--ac-transition-*` CSS custom properties in `index.css`.
+ *
+ * @example
+ * ```tsx
+ * <motion.div animate={{opacity: 1}} transition={{duration: durations.normal}} />
+ * ```
+ */
+export const durations = {
+  fast: 0.1,
+  normal: 0.15,
+  slow: 0.2,
+  slower: 0.3,
+  slowest: 0.5,
+} as const;
+
+/**
+ * Standard easing curves for consistent motion across the library.
+ */
+export const easings = {
+  ease: [0.25, 0.1, 0.25, 1],
+  easeIn: [0.42, 0, 1, 1],
+  easeOut: [0, 0, 0.58, 1],
+  easeInOut: [0.42, 0, 0.58, 1],
+  spring: {type: "spring" as const, stiffness: 300, damping: 24},
+} as const;
+
+/**
+ * Represents a named motion duration token.
+ */
+export type Duration = keyof typeof durations;
+
+/**
+ * Represents a named motion easing token.
+ */
+export type Easing = keyof typeof easings;

package/src/stories/DesignPrinciples.mdx

@@ -0,0 +1,48 @@
+{/* @meta title: Introduction/Design Principles */}
+
+# Design Principles
+
+## 🎯 Accessibility First
+
+Every component is built on **Base UI** primitives, ensuring:
+- Correct ARIA attributes and roles
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus management
+- Color contrast compliance (WCAG 2.1 AA)
+
+## 🎨 Design Tokens
+
+We use **OKLCH** color space for perceptually uniform colors:
+- Colors stay visually consistent across light and dark themes
+- Tokens are CSS custom properties (`--ac-*` prefix)
+- Override any token to create custom themes
+
+## 🧩 Composition Over Configuration
+
+Components follow the **compound component** pattern:
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+  <CardFooter>Footer</CardFooter>
+</Card>
+```
+
+## 🔧 Progressive Enhancement
+
+- Server Components by default
+- `"use client"` only when hooks/interactivity needed
+- CSS Modules for scoped, predictable styles
+- No runtime CSS-in-JS overhead
+
+## 📐 Consistent API
+
+Every component follows these conventions:
+- `className` prop for custom styling
+- `forwardRef` for DOM access
+- `displayName` for debugging
+- JSDoc for API documentation
+- Co-located tests and stories