@arolariu/components 0.4.2 → 1.0.0

package/src/lib/color-conversion-utilities.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Utility functions for color conversion and manipulation.
+ * Provides hex-to-HSL conversion and color validation for CSS custom properties.
+ * @module lib/color-conversion-utilities
+ */
+
+/**
+ * Converts a hexadecimal color code to an HSL string for CSS variables.
+ * The output format matches Tailwind CSS HSL variable format: "h s% l%"
+ *
+ * @param hexColor - Hex color code (e.g., "#06b6d4" or "06b6d4")
+ * @returns HSL values as "h s% l%" string suitable for CSS variables
+ *
+ * @example
+ * ```typescript
+ * convertHexToHslString("#06b6d4"); // "187 94% 43%"
+ * convertHexToHslString("#ec4899"); // "330 81% 60%"
+ * ```
+ */
+export function convertHexToHslString(hexColor: string): string {
+  // Remove # if present
+  const cleanHex = hexColor.replace("#", "");
+
+  // Parse RGB values
+  const r = Number.parseInt(cleanHex.slice(0, 2), 16) / 255;
+  const g = Number.parseInt(cleanHex.slice(2, 4), 16) / 255;
+  const b = Number.parseInt(cleanHex.slice(4, 6), 16) / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let h = 0;
+  let s = 0;
+  const l = (max + min) / 2;
+
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+    // max is always r, g, or b - no default case needed
+    if (max === r) {
+      h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+    } else if (max === g) {
+      h = ((b - r) / d + 2) / 6;
+    } else {
+      h = ((r - g) / d + 4) / 6;
+    }
+  }
+
+  return `${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`;
+}
+
+/**
+ * Converts HSL color values to a hexadecimal color string.
+ *
+ * @param hue - Hue value (0-360)
+ * @param saturation - Saturation percentage (0-100)
+ * @param lightness - Lightness percentage (0-100)
+ * @returns Hex color code (e.g., "#06b6d4")
+ */
+export function convertHslToHexString(hue: number, saturation: number, lightness: number): string {
+  const sNorm = saturation / 100;
+  const lNorm = lightness / 100;
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm;
+  const x = c * (1 - Math.abs(((hue / 60) % 2) - 1));
+  const m = lNorm - c / 2;
+
+  const getRgb = (): [number, number, number] => {
+    if (hue >= 0 && hue < 60) return [c, x, 0];
+    if (hue >= 60 && hue < 120) return [x, c, 0];
+    if (hue >= 120 && hue < 180) return [0, c, x];
+    if (hue >= 180 && hue < 240) return [0, x, c];
+    if (hue >= 240 && hue < 300) return [x, 0, c];
+    return [c, 0, x];
+  };
+
+  const rgb = getRgb();
+
+  const toHex = (n: number) =>
+    Math.round((n + m) * 255)
+      .toString(16)
+      .padStart(2, "0");
+
+  return `#${toHex(rgb[0])}${toHex(rgb[1])}${toHex(rgb[2])}`;
+}
+
+/**
+ * Validates whether a string is a valid 6-digit hexadecimal color code.
+ *
+ * @param hexColor - String to validate
+ * @returns True if valid 6-digit hex color (with or without #)
+ *
+ * @example
+ * ```typescript
+ * validateHexColorFormat("#06b6d4"); // true
+ * validateHexColorFormat("06b6d4");  // true
+ * validateHexColorFormat("#FFF");    // false (3-digit not supported)
+ * validateHexColorFormat("invalid"); // false
+ * ```
+ */
+export function validateHexColorFormat(hexColor: string): boolean {
+  return /^#?[\dA-Fa-f]{6}$/u.test(hexColor);
+}
+
+/**
+ * Generates the complementary (inverse) color for a given hex color.
+ *
+ * @param hexColor - Hex color code
+ * @returns Complementary hex color code
+ */
+export function calculateComplementaryHexColor(hexColor: string): string {
+  const cleanHex = hexColor.replace("#", "");
+  const r = 255 - Number.parseInt(cleanHex.slice(0, 2), 16);
+  const g = 255 - Number.parseInt(cleanHex.slice(2, 4), 16);
+  const b = 255 - Number.parseInt(cleanHex.slice(4, 6), 16);
+
+  return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Adjusts the lightness of a hexadecimal color by a specified amount.
+ *
+ * @param hexColor - Hex color code
+ * @param lightnessAdjustment - Amount to adjust lightness (-100 to 100)
+ * @returns Adjusted hex color code
+ */
+export function adjustHexColorLightness(hexColor: string, lightnessAdjustment: number): string {
+  const hsl = convertHexToHslString(hexColor);
+  const [h, s, l] = hsl.split(" ").map((v, i) => (i === 0 ? Number.parseInt(v, 10) : Number.parseInt(v.replace("%", ""), 10)));
+
+  const newL = Math.max(0, Math.min(100, (l ?? 50) + lightnessAdjustment));
+  return convertHslToHexString(h ?? 0, s ?? 50, newL);
+}
+
+/**
+ * Parses an HSL CSS variable string into its numeric components.
+ *
+ * @param hslString - HSL string in format "h s% l%"
+ * @returns Object with hue, saturation, lightness values or null if invalid
+ */
+export function parseHslStringToComponents(hslString: string): {hue: number; saturation: number; lightness: number} | null {
+  const pattern = /^(?<hue>\d+)\s+(?<sat>\d+)%\s+(?<light>\d+)%$/u;
+  const match = pattern.exec(hslString);
+  if (!match?.groups) return null;
+
+  return {
+    hue: Number.parseInt(match.groups["hue"] ?? "0", 10),
+    saturation: Number.parseInt(match.groups["sat"] ?? "0", 10),
+    lightness: Number.parseInt(match.groups["light"] ?? "0", 10),
+  };
+}
+
+// Legacy aliases for backwards compatibility (deprecated)
+/** @deprecated Use convertHexToHslString instead */
+export const hexToHsl = convertHexToHslString;
+/** @deprecated Use convertHslToHexString instead */
+export const hslToHex = convertHslToHexString;
+/** @deprecated Use validateHexColorFormat instead */
+export const isValidHexColor = validateHexColorFormat;
+/** @deprecated Use calculateComplementaryHexColor instead */
+export const getComplementaryColor = calculateComplementaryHexColor;
+/** @deprecated Use adjustHexColorLightness instead */
+export const adjustLightness = adjustHexColorLightness;
+/** @deprecated Use parseHslStringToComponents instead */
+export const parseHslString = parseHslStringToComponents;

package/src/lib/utilities.ts

@@ -1,12 +1,13 @@
 import {clsx, type ClassValue} from "clsx";
-import {twMerge} from "tailwind-merge";
 
 /**
- * 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<ClassValue>): string {
+  return clsx(inputs);
 }
+
+export type {ClassValue};

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.0],
+  easeIn: [0.42, 0, 1.0, 1.0],
+  easeOut: [0, 0, 0.58, 1.0],
+  easeInOut: [0.42, 0, 0.58, 1.0],
+  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;