@arolariu/components 0.4.2 → 1.0.0

package/src/components/ui/fireworks-background.tsx

@@ -3,6 +3,7 @@
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./fireworks-background.module.css";
 
 const rand = (min: number, max: number): number => Math.random() * (max - min) + min;
 const randInt = (min: number, max: number): number => Math.floor(Math.random() * (max - min) + min);
@@ -87,7 +88,7 @@ interface FireworkType {
   angle: number;
   vx: number;
   vy: number;
-  trail: {x: number; y: number}[];
+  trail: Array<{x: number; y: number}>;
   trailLength: number;
   exploded: boolean;
   update: () => boolean;
@@ -104,12 +105,12 @@ const createFirework = (
   size: number,
   particleSpeed: {min: number; max: number} | number,
   particleSize: {min: number; max: number} | number,
-  onExplode: (particles: ParticleType[]) => void,
+  onExplode: (particles: ReadonlyArray<ParticleType>) => void,
 ): FireworkType => {
   const angle = -Math.PI / 2 + rand(-0.3, 0.3);
   const vx = Math.cos(angle) * speed;
   const vy = Math.sin(angle) * speed;
-  const trail: {x: number; y: number}[] = [];
+  const trail: Array<{x: number; y: number}> = [];
   const trailLength = randInt(10, 25);
 
   return {
@@ -140,9 +141,9 @@ const createFirework = (
       return true;
     },
     explode() {
-      const numParticles = randInt(50, 150);
-      const particles: ParticleType[] = [];
-      for (let i = 0; i < numParticles; i++) {
+      const numberOfParticles = randInt(50, 150);
+      const particles: Array<ParticleType> = [];
+      for (let index = 0; index < numberOfParticles; index += 1) {
         const particleAngle = rand(0, Math.PI * 2);
         const localParticleSpeed = getValueByRange(particleSpeed);
         const localParticleSize = getValueByRange(particleSize);
@@ -154,7 +155,7 @@ const createFirework = (
       ctx.save();
       ctx.beginPath();
       if (this.trail.length > 1) {
-        ctx.moveTo(this.trail[0].x, this.trail[0].y);
+        ctx.moveTo(this.trail[0]!.x, this.trail[0]!.y);
         for (const point of this.trail) {
           ctx.lineTo(point.x, point.y);
         }
@@ -175,26 +176,56 @@ const getValueByRange = (range: {min: number; max: number} | number): number =>
   if (typeof range === "number") {
     return range;
   }
+
   return rand(range.min, range.max);
 };
 
-const getColor = (color: string | string[] | undefined): string => {
+const getColor = (color: string | ReadonlyArray<string> | undefined): string => {
   if (Array.isArray(color)) {
-    return color[randInt(0, color.length)];
+    return color[randInt(0, color.length)] ?? randColor();
+  }
+
+  if (typeof color === "string") {
+    return color;
   }
-  return color ?? randColor();
+
+  return randColor();
 };
 
-interface FireworksBackgroundProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+/** Props accepted by {@link FireworksBackground}. */
+export interface FireworksBackgroundProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+  /** HTML attributes forwarded to the internal `<canvas>` element. @default undefined */
   canvasProps?: React.HTMLAttributes<HTMLCanvasElement>;
+  /** Relative launch frequency multiplier for automatic fireworks. @default 1 */
   population?: number;
-  color?: string | string[];
+  /** Fixed color or palette used for generated fireworks and particles. @default undefined */
+  color?: string | ReadonlyArray<string>;
+  /** Launch velocity or range used for ascending fireworks. @default {min: 4, max: 8} */
   fireworkSpeed?: {min: number; max: number} | number;
+  /** Stroke width or range used for the ascending firework trail. @default {min: 2, max: 5} */
   fireworkSize?: {min: number; max: number} | number;
+  /** Velocity or range used for explosion particles. @default {min: 2, max: 7} */
   particleSpeed?: {min: number; max: number} | number;
+  /** Size or range used for explosion particles. @default {min: 1, max: 5} */
   particleSize?: {min: number; max: number} | number;
 }
 
+/**
+ * Renders an auto-launching fireworks display inside a clickable background canvas.
+ *
+ * @remarks
+ * - Animated component using the `motion` library
+ * - Renders a `<div>` element containing a `<canvas>`
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ * - Client-side only (`"use client"` directive)
+ *
+ * @example
+ * ```tsx
+ * <FireworksBackground population={2} />
+ * ```
+ *
+ * @see {@link FireworksBackgroundProps} for available props
+ */
 const FireworksBackground = React.forwardRef<HTMLDivElement, FireworksBackgroundProps>(
   (
     {
@@ -212,38 +243,46 @@ const FireworksBackground = React.forwardRef<HTMLDivElement, FireworksBackground
   ) => {
     const canvasRef = React.useRef<HTMLCanvasElement>(null);
     const containerRef = React.useRef<HTMLDivElement>(null);
-    React.useImperativeHandle(ref, () => containerRef.current as HTMLDivElement);
+
+    React.useImperativeHandle(ref, () => containerRef.current!, []);
 
     React.useEffect(() => {
       const canvas = canvasRef.current;
       const container = containerRef.current;
-      if (!canvas || !container) return;
-      const ctx = canvas.getContext("2d");
-      if (!ctx) return;
+      if (!canvas || !container) {
+        return;
+      }
 
-      let maxX = window.innerWidth;
-      let ratio = container.offsetHeight / container.offsetWidth;
+      const context = canvas.getContext("2d");
+      if (!context) {
+        return;
+      }
+
+      let maxX = globalThis.window.innerWidth;
+      let ratio = container.offsetHeight / Math.max(container.offsetWidth, 1);
       let maxY = maxX * ratio;
+      let launchTimeoutId = 0;
       canvas.width = maxX;
       canvas.height = maxY;
 
-      const setCanvasSize = () => {
-        maxX = window.innerWidth;
-        ratio = container.offsetHeight / container.offsetWidth;
+      const setCanvasSize = (): void => {
+        maxX = globalThis.window.innerWidth;
+        ratio = container.offsetHeight / Math.max(container.offsetWidth, 1);
         maxY = maxX * ratio;
         canvas.width = maxX;
         canvas.height = maxY;
       };
-      window.addEventListener("resize", setCanvasSize);
 
-      const explosions: ParticleType[] = [];
-      const fireworks: FireworkType[] = [];
+      globalThis.window.addEventListener("resize", setCanvasSize);
+
+      const explosions: Array<ParticleType> = [];
+      const fireworks: Array<FireworkType> = [];
 
-      const handleExplosion = (particles: ParticleType[]) => {
+      const handleExplosion = (particles: ReadonlyArray<ParticleType>): void => {
         explosions.push(...particles);
       };
 
-      const launchFirework = () => {
+      const launchFirework = (): void => {
         const x = rand(maxX * 0.1, maxX * 0.9);
         const y = maxY;
         const targetY = rand(maxY * 0.1, maxY * 0.4);
@@ -252,68 +291,67 @@ const FireworksBackground = React.forwardRef<HTMLDivElement, FireworksBackground
         const size = getValueByRange(fireworkSize);
         fireworks.push(createFirework(x, y, targetY, fireworkColor, speed, size, particleSpeed, particleSize, handleExplosion));
         const timeout = rand(300, 800) / population;
-        setTimeout(launchFirework, timeout);
+        launchTimeoutId = globalThis.window.setTimeout(launchFirework, timeout);
       };
 
       launchFirework();
 
-      // eslint-disable-next-line init-declarations -- firework animation id
-      let animationFrameId: number;
-      const animate = () => {
-        ctx.clearRect(0, 0, maxX, maxY);
+      let animationFrameId = 0;
+      const animate = (): void => {
+        context.clearRect(0, 0, maxX, maxY);
 
-        for (let i = fireworks.length - 1; i >= 0; i--) {
-          const firework = fireworks[i];
+        for (let index = fireworks.length - 1; index >= 0; index -= 1) {
+          const firework = fireworks[index]!;
           if (firework.update()) {
-            firework.draw(ctx);
+            firework.draw(context);
           } else {
-            fireworks.splice(i, 1);
+            fireworks.splice(index, 1);
           }
         }
 
-        for (let i = explosions.length - 1; i >= 0; i--) {
-          const particle = explosions[i];
+        for (let index = explosions.length - 1; index >= 0; index -= 1) {
+          const particle = explosions[index]!;
           particle.update();
           if (particle.isAlive()) {
-            particle.draw(ctx);
+            particle.draw(context);
           } else {
-            explosions.splice(i, 1);
+            explosions.splice(index, 1);
           }
         }
 
-        animationFrameId = requestAnimationFrame(animate);
+        animationFrameId = globalThis.requestAnimationFrame(animate);
       };
 
       animate();
 
-      const handleClick = (event: MouseEvent) => {
-        const x = event.clientX;
-        const y = maxY;
-        const targetY = event.clientY;
+      const handleClick = (event: MouseEvent): void => {
         const fireworkColor = getColor(color);
         const speed = getValueByRange(fireworkSpeed);
         const size = getValueByRange(fireworkSize);
-        fireworks.push(createFirework(x, y, targetY, fireworkColor, speed, size, particleSpeed, particleSize, handleExplosion));
+        fireworks.push(
+          createFirework(event.clientX, maxY, event.clientY, fireworkColor, speed, size, particleSpeed, particleSize, handleExplosion),
+        );
       };
 
       container.addEventListener("click", handleClick);
 
       return () => {
-        window.removeEventListener("resize", setCanvasSize);
+        globalThis.window.removeEventListener("resize", setCanvasSize);
         container.removeEventListener("click", handleClick);
-        cancelAnimationFrame(animationFrameId);
+        globalThis.window.clearTimeout(launchTimeoutId);
+        globalThis.cancelAnimationFrame(animationFrameId);
       };
-    }, [population, color, fireworkSpeed, fireworkSize, particleSpeed, particleSize]);
+    }, [color, fireworkSize, fireworkSpeed, particleSize, particleSpeed, population]);
 
     return (
       <div
         ref={containerRef}
-        className={cn("relative size-full overflow-hidden", className)}
+        className={cn(styles.root, className)}
         {...props}>
         <canvas
           {...canvasProps}
           ref={canvasRef}
-          className={cn("absolute inset-0 size-full", canvasProps?.className)}
+          className={cn(styles.canvas, canvasProps?.className)}
         />
       </div>
     );
@@ -322,4 +360,4 @@ const FireworksBackground = React.forwardRef<HTMLDivElement, FireworksBackground
 
 FireworksBackground.displayName = "FireworksBackground";
 
-export {FireworksBackground, type FireworksBackgroundProps};
+export {FireworksBackground};

package/src/components/ui/flip-button.module.css

@@ -0,0 +1,44 @@
+.button {
+  position: relative;
+  display: inline-block;
+  height: 2.5rem;
+  padding: 0.5rem 1rem;
+  cursor: pointer;
+  font-size: var(--ac-text-sm);
+  font-weight: 500;
+  line-height: 1.25rem;
+  perspective: 1000px;
+  border: 0;
+  background: transparent;
+  color: inherit;
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--ac-ring);
+  outline-offset: 2px;
+}
+
+.face {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--ac-radius-lg);
+  backface-visibility: hidden;
+  transform-style: preserve-3d;
+}
+
+.front {
+  background: var(--ac-muted);
+  color: var(--ac-foreground);
+}
+
+.back {
+  background: var(--ac-primary);
+  color: var(--ac-primary-foreground);
+}
+
+.measure {
+  visibility: hidden;
+}

package/src/components/ui/flip-button.tsx

@@ -1,23 +1,46 @@
 "use client";
 
-import {type HTMLMotionProps, type Transition, type Variant, motion} from "motion/react";
+import {type HTMLMotionProps, motion, type Transition, type Variant} from "motion/react";
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./flip-button.module.css";
 
-type FlipDirection = "top" | "bottom" | "left" | "righ";
+/** Supported flip origins for the button animation. */
+export type FlipDirection = "top" | "bottom" | "left" | "righ";
 
-interface FlipButtonProps extends HTMLMotionProps<"button"> {
+/** Props accepted by {@link FlipButton}. */
+export interface FlipButtonProps extends HTMLMotionProps<"button"> {
+  /** Label rendered on the default face of the button. @default undefined */
   frontText: string;
+  /** Label revealed after the flip animation completes. @default undefined */
   backText: string;
+  /** Motion transition applied to both button faces. @default {type: "spring", stiffness: 280, damping: 20} */
   transition?: Transition;
+  /** Additional CSS classes merged with the front face. @default undefined */
   frontClassName?: string;
+  /** Additional CSS classes merged with the back face. @default undefined */
   backClassName?: string;
+  /** Direction from which the back face flips into view. @default "top" */
   from?: FlipDirection;
 }
 
-const defaultSpanClassName = "absolute inset-0 flex items-center justify-center rounded-lg";
-
+/**
+ * Renders a two-sided button that flips between front and back labels on hover.
+ *
+ * @remarks
+ * - Animated component using the `motion` library
+ * - Renders a `<button>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ * - Client-side only (`"use client"` directive)
+ *
+ * @example
+ * ```tsx
+ * <FlipButton frontText="Learn more" backText="Open" />
+ * ```
+ *
+ * @see {@link FlipButtonProps} for available props
+ */
 const FlipButton = React.forwardRef<HTMLButtonElement, FlipButtonProps>(
   (
     {
@@ -32,28 +55,39 @@ const FlipButton = React.forwardRef<HTMLButtonElement, FlipButtonProps>(
     },
     ref,
   ) => {
+    // eslint-disable-next-line sonarjs/no-unused-vars -- removing React key avoids implicit key spreading
+    const {key: _ignoredKey, ...restProps} = props;
     const isVertical = from === "top" || from === "bottom";
     const rotateAxis = isVertical ? "rotateX" : "rotateY";
 
     const frontOffset = from === "top" || from === "left" ? "50%" : "-50%";
     const backOffset = from === "top" || from === "left" ? "-50%" : "50%";
 
-    const buildVariant = (opacity: number, rotation: number, offset: string | null = null): Variant => ({
-      opacity,
-      [rotateAxis]: rotation,
-      ...(isVertical && offset !== null ? {y: offset} : {}),
-      ...(!isVertical && offset !== null ? {x: offset} : {}),
-    });
+    const buildVariant = React.useCallback(
+      (opacity: number, rotation: number, offset: string | null = null): Variant => ({
+        opacity,
+        [rotateAxis]: rotation,
+        ...(isVertical && offset !== null ? {y: offset} : {}),
+        ...(!isVertical && offset !== null ? {x: offset} : {}),
+      }),
+      [isVertical, rotateAxis],
+    );
 
-    const frontVariants = {
-      initial: buildVariant(1, 0, "0%"),
-      hover: buildVariant(0, 90, frontOffset),
-    };
+    const frontVariants = React.useMemo(
+      () => ({
+        initial: buildVariant(1, 0, "0%"),
+        hover: buildVariant(0, 90, frontOffset),
+      }),
+      [buildVariant, frontOffset],
+    );
 
-    const backVariants = {
-      initial: buildVariant(0, 90, backOffset),
-      hover: buildVariant(1, 0, "0%"),
-    };
+    const backVariants = React.useMemo(
+      () => ({
+        initial: buildVariant(0, 90, backOffset),
+        hover: buildVariant(1, 0, "0%"),
+      }),
+      [backOffset, buildVariant],
+    );
 
     return (
       <motion.button
@@ -61,24 +95,21 @@ const FlipButton = React.forwardRef<HTMLButtonElement, FlipButtonProps>(
         initial='initial'
         whileHover='hover'
         whileTap={{scale: 0.95}}
-        className={cn(
-          "relative inline-block h-10 cursor-pointer px-4 py-2 text-sm font-medium perspective-[1000px] focus:outline-none",
-          className,
-        )}
-        {...props}>
+        className={cn(styles.button, className)}
+        {...restProps}>
         <motion.span
           variants={frontVariants}
           transition={transition}
-          className={cn(defaultSpanClassName, "bg-muted text-black dark:text-white", frontClassName)}>
+          className={cn(styles.face, styles.front, frontClassName)}>
           {frontText}
         </motion.span>
         <motion.span
           variants={backVariants}
           transition={transition}
-          className={cn(defaultSpanClassName, "bg-primary text-primary-foreground", backClassName)}>
+          className={cn(styles.face, styles.back, backClassName)}>
           {backText}
         </motion.span>
-        <span className='invisible'>{frontText}</span>
+        <span className={styles.measure}>{frontText}</span>
       </motion.button>
     );
   },
@@ -86,4 +117,4 @@ const FlipButton = React.forwardRef<HTMLButtonElement, FlipButtonProps>(
 
 FlipButton.displayName = "FlipButton";
 
-export {FlipButton, type FlipButtonProps, type FlipDirection};
+export {FlipButton};

package/src/components/ui/focus-scope.module.css

@@ -0,0 +1,3 @@
+.scope {
+  outline: none;
+}

package/src/components/ui/focus-scope.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import * as React from "react";
+
+import {cn} from "@/lib/utilities";
+
+import styles from "./focus-scope.module.css";
+
+/**
+ * Represents the configurable props for the {@link FocusScope} component.
+ */
+interface FocusScopeProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Whether focus should be trapped within the scope.
+   *
+   * @defaultValue true
+   */
+  contain?: boolean;
+  /**
+   * Whether to restore focus to the previously focused element on unmount.
+   *
+   * @defaultValue true
+   */
+  restoreFocus?: boolean;
+  /**
+   * Whether to auto-focus the first focusable element on mount.
+   *
+   * @defaultValue false
+   */
+  autoFocus?: boolean;
+  /**
+   * Content rendered within the focus scope.
+   */
+  children: React.ReactNode;
+}
+
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not(:disabled)",
+  "input:not(:disabled)",
+  "select:not(:disabled)",
+  "textarea:not(:disabled)",
+  '[tabindex]:not([tabindex="-1"])',
+  "[contenteditable]",
+].join(", ");
+
+function getFocusableElements(container: HTMLElement): HTMLElement[] {
+  return [...container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+    (element) => !element.hasAttribute("disabled") && element.tabIndex >= 0,
+  );
+}
+
+/**
+ * Traps keyboard focus within a container element.
+ *
+ * @remarks
+ * Renders a `<div>` and cycles `Tab` and `Shift+Tab` navigation through its focusable
+ * descendants without allowing focus to escape the scope. Use it for custom dialogs,
+ * drawers, and composite widgets that need explicit focus containment and restoration.
+ *
+ * Base UI dialog-style primitives already manage focus internally, so prefer those
+ * built-in mechanisms when available.
+ *
+ * @example
+ * ```tsx
+ * <FocusScope contain autoFocus>
+ *   <input placeholder='First' />
+ *   <input placeholder='Second' />
+ *   <button type='submit'>Submit</button>
+ * </FocusScope>
+ * ```
+ */
+const FocusScope = React.forwardRef<HTMLDivElement, FocusScopeProps>(
+  ({contain = true, restoreFocus = true, autoFocus = false, children, className, ...props}, ref) => {
+    const containerRef = React.useRef<HTMLDivElement | null>(null);
+    const previousFocusRef = React.useRef<Element | null>(null);
+
+    React.useEffect(() => {
+      previousFocusRef.current = document.activeElement;
+
+      if (autoFocus && containerRef.current) {
+        const focusable = getFocusableElements(containerRef.current);
+
+        focusable[0]?.focus();
+      }
+
+      return () => {
+        if (restoreFocus && previousFocusRef.current instanceof HTMLElement) {
+          previousFocusRef.current.focus();
+        }
+      };
+    }, [autoFocus, restoreFocus]);
+
+    React.useEffect(() => {
+      const container = containerRef.current;
+
+      if (!container) {
+        return;
+      }
+
+      const handleKeyDown = (event: KeyboardEvent): void => {
+        if (!contain || event.key !== "Tab") {
+          return;
+        }
+
+        const focusable = getFocusableElements(container);
+
+        if (focusable.length === 0) {
+          return;
+        }
+
+        const [first] = focusable;
+        const last = focusable.at(-1);
+
+        if (event.shiftKey && first?.isSameNode(document.activeElement)) {
+          event.preventDefault();
+          last?.focus();
+          return;
+        }
+
+        if (!event.shiftKey && last?.isSameNode(document.activeElement)) {
+          event.preventDefault();
+          first?.focus();
+        }
+      };
+
+      container.addEventListener("keydown", handleKeyDown);
+
+      return () => {
+        container.removeEventListener("keydown", handleKeyDown);
+      };
+    }, [contain]);
+
+    return (
+      <div
+        ref={(node) => {
+          containerRef.current = node;
+
+          if (typeof ref === "function") {
+            ref(node);
+            return;
+          }
+
+          if (ref) {
+            ref.current = node;
+          }
+        }}
+        className={cn(styles.scope, className)}
+        role={props.role ?? "group"}
+        tabIndex={props.tabIndex ?? -1}
+        {...props}>
+        {children}
+      </div>
+    );
+  },
+);
+FocusScope.displayName = "FocusScope";
+
+export {FocusScope};
+export type {FocusScopeProps};

package/src/components/ui/form-skeleton.module.css

@@ -0,0 +1,28 @@
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ac-space-4);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ac-space-1);
+}
+
+.label {
+  width: 30%;
+  height: 0.875rem;
+}
+
+.input {
+  height: 2.5rem;
+  border-radius: var(--ac-radius-md);
+}
+
+.submit {
+  align-self: flex-end;
+  width: 8rem;
+  height: 2.5rem;
+  border-radius: var(--ac-radius-md);
+}