@arolariu/components 0.4.2 → 1.0.0

package/src/components/ui/form-skeleton.tsx

@@ -0,0 +1,62 @@
+import * as React from "react";
+
+import {cn} from "@/lib/utilities";
+
+import styles from "./form-skeleton.module.css";
+import {Skeleton} from "./skeleton";
+
+/**
+ * Represents the configurable props for the {@link FormSkeleton} component.
+ *
+ * @remarks
+ * Extends native `<div>` attributes so form-shaped placeholders can be composed into
+ * dialogs, cards, and pages while still supporting accessibility annotations.
+ */
+interface FormSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Number of labeled field placeholders rendered before the submit action.
+   *
+   * @default 4
+   */
+  fields?: number;
+}
+
+/**
+ * Renders a skeleton placeholder shaped like a labeled form.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible presentational component.
+ *
+ * Uses stacked label and input placeholders plus a trailing submit action placeholder to
+ * preserve form layout during async initialization or schema-driven rendering.
+ *
+ * @example
+ * ```tsx
+ * <FormSkeleton fields={5} aria-label="Loading profile form" />
+ * ```
+ *
+ * @see {@link FormSkeletonProps} for available props
+ */
+const FormSkeleton = React.forwardRef<HTMLDivElement, FormSkeletonProps>(
+  ({fields = 4, className, ...props}: Readonly<FormSkeletonProps>, ref): React.JSX.Element => (
+    <div
+      ref={ref}
+      className={cn(styles.form, className)}
+      {...props}>
+      {Array.from({length: fields}, (_, index) => (
+        <div
+          key={index}
+          className={styles.field}>
+          <Skeleton className={styles.label} />
+          <Skeleton className={styles.input} />
+        </div>
+      ))}
+      <Skeleton className={styles.submit} />
+    </div>
+  ),
+);
+
+FormSkeleton.displayName = "FormSkeleton";
+
+export {FormSkeleton};
+export type {FormSkeletonProps};

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

@@ -0,0 +1,20 @@
+.item {
+  display: grid;
+  gap: var(--ac-space-2);
+}
+
+.labelError {
+  color: var(--ac-destructive);
+}
+
+.description {
+  color: var(--ac-muted-foreground);
+  font-size: 0.8rem;
+}
+
+.message {
+  color: var(--ac-destructive);
+  font-size: 0.8rem;
+  font-weight: 500;
+}
+

package/src/components/ui/form.tsx

@@ -1,14 +1,70 @@
 "use client";
 
-import * as LabelPrimitive from "@radix-ui/react-label";
-import {Slot} from "@radix-ui/react-slot";
+/* eslint-disable react/prop-types */
+
 import * as React from "react";
 import {Controller, FormProvider, useFormContext, type ControllerProps, type FieldPath, type FieldValues} from "react-hook-form";
 
-import {Label} from "@/components/ui/label";
 import {cn} from "@/lib/utilities";
 
-const Form = FormProvider;
+import styles from "./form.module.css";
+
+/**
+ * Provides the `react-hook-form` context to nested form primitives.
+ *
+ * @remarks
+ * - Renders the `FormProvider` component from `react-hook-form`
+ * - Built on `react-hook-form`
+ *
+ * @example
+ * ```tsx
+ * <Form {...form}>
+ *   <form>...</form>
+ * </Form>
+ * ```
+ *
+ * @see {@link https://react-hook-form.com/docs/formprovider | React Hook Form FormProvider Docs}
+ */
+const Form = Object.assign(FormProvider, {displayName: "Form"});
+
+type FormControlElementProps = React.HTMLAttributes<HTMLElement> & {
+  ref?: React.Ref<HTMLElement>;
+};
+
+interface FormControlProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  /**
+   * Single form control element or fallback content to receive field accessibility attributes.
+   * @default undefined
+   */
+  children: React.ReactNode;
+}
+
+function assignRef<TValue>(ref: React.Ref<TValue> | undefined, value: TValue | null): void {
+  if (typeof ref === "function") {
+    ref(value);
+    return;
+  }
+
+  if (ref) {
+    ref.current = value;
+  }
+}
+
+function composeRefs<TValue>(...refs: Array<React.Ref<TValue> | undefined>): React.RefCallback<TValue> {
+  return (value: TValue | null): void => {
+    for (const ref of refs) {
+      assignRef(ref, value);
+    }
+  };
+}
+
+function mergeAriaDescribedBy(...describedByValues: Array<string | undefined>): string | undefined {
+  const tokens = describedByValues
+    .flatMap((describedByValue) => describedByValue?.split(/\s+/u) ?? [])
+    .filter((token): token is string => token.length > 0);
+
+  return tokens.length > 0 ? [...new Set(tokens)].join(" ") : undefined;
+}
 
 type FormFieldContextValue<
   TFieldValues extends FieldValues = FieldValues,
@@ -19,9 +75,27 @@ type FormFieldContextValue<
 
 const FormFieldContext = React.createContext<FormFieldContextValue | null>(null);
 
+/**
+ * Binds a single field name to the shared form field context.
+ *
+ * @remarks
+ * - Renders the `Controller` component from `react-hook-form`
+ * - Built on `react-hook-form` controller primitives
+ *
+ * @example
+ * ```tsx
+ * <FormField
+ *   control={form.control}
+ *   name='email'
+ *   render={({field}) => <input {...field} />}
+ * />
+ * ```
+ *
+ * @see {@link https://react-hook-form.com/docs/usecontroller/controller | React Hook Form Controller Docs}
+ */
 const FormField = <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({
   ...props
-}: ControllerProps<TFieldValues, TName>) => {
+}: ControllerProps<TFieldValues, TName>): React.JSX.Element => {
   return (
     <FormFieldContext.Provider value={{name: props.name}}>
       <Controller {...props} />
@@ -29,7 +103,34 @@ const FormField = <TFieldValues extends FieldValues = FieldValues, TName extends
   );
 };
 
-const useFormField = () => {
+type UseFormFieldReturn = {
+  id: string;
+  name: FieldPath<FieldValues>;
+  formItemId: string;
+  formDescriptionId: string;
+  formMessageId: string;
+  invalid: boolean;
+  isDirty: boolean;
+  isTouched: boolean;
+  isValidating: boolean;
+  error?: ReturnType<ReturnType<typeof useFormContext>["getFieldState"]>["error"];
+};
+
+/**
+ * Returns the resolved form field metadata for nested form primitives.
+ *
+ * @remarks
+ * Reads the nearest {@link FormField} and {@link FormItem} contexts, then combines them
+ * with `react-hook-form` field state to expose stable IDs and validation metadata.
+ *
+ * @example
+ * ```tsx
+ * const field = useFormField();
+ * ```
+ *
+ * @see {@link https://react-hook-form.com/docs/useformcontext | React Hook Form useFormContext Docs}
+ */
+const useFormField = (): UseFormFieldReturn => {
   const fieldContext = React.useContext(FormFieldContext);
   const itemContext = React.useContext(FormItemContext);
   const {getFieldState, formState} = useFormContext();
@@ -43,16 +144,19 @@ const useFormField = () => {
   }
 
   const fieldState = getFieldState(fieldContext.name, formState);
-
   const {id} = itemContext;
 
   return {
-    id,
-    name: fieldContext.name,
-    formItemId: `${id}-form-item`,
+    error: fieldState.error,
     formDescriptionId: `${id}-form-item-description`,
+    formItemId: `${id}-form-item`,
     formMessageId: `${id}-form-item-message`,
-    ...fieldState,
+    id,
+    invalid: fieldState.invalid,
+    isDirty: fieldState.isDirty,
+    isTouched: fieldState.isTouched,
+    isValidating: fieldState.isValidating,
+    name: fieldContext.name as FieldPath<FieldValues>,
   };
 };
 
@@ -62,6 +166,22 @@ type FormItemContextValue = {
 
 const FormItemContext = React.createContext<FormItemContextValue | null>(null);
 
+/**
+ * Wraps a label, control, description, and message into a single form item.
+ *
+ * @remarks
+ * - Renders a `<div>` element
+ * - Built on the shared form item context
+ *
+ * @example
+ * ```tsx
+ * <FormItem>
+ *   <FormLabel>Email</FormLabel>
+ * </FormItem>
+ * ```
+ *
+ * @see {@link https://react-hook-form.com/docs/useformcontext | React Hook Form Docs}
+ */
 const FormItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(({className, ...props}, ref) => {
   const id = React.useId();
 
@@ -69,7 +189,7 @@ const FormItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivEl
     <FormItemContext.Provider value={{id}}>
       <div
         ref={ref}
-        className={cn("space-y-2", className)}
+        className={cn(styles.item, className)}
         {...props}
       />
     </FormItemContext.Provider>
@@ -77,16 +197,27 @@ const FormItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivEl
 });
 FormItem.displayName = "FormItem";
 
-const FormLabel = React.forwardRef<
-  React.ComponentRef<typeof LabelPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>
->(({className, ...props}, ref) => {
+/**
+ * Renders the accessible label for the current form item.
+ *
+ * @remarks
+ * - Renders a `<label>` element
+ * - Built on the shared form field metadata hook
+ *
+ * @example
+ * ```tsx
+ * <FormLabel>Email</FormLabel>
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/HTML/Element/label | HTML label element}
+ */
+const FormLabel = React.forwardRef<HTMLLabelElement, React.LabelHTMLAttributes<HTMLLabelElement>>(({className, ...props}, ref) => {
   const {error, formItemId} = useFormField();
 
   return (
-    <Label
+    <label
       ref={ref}
-      className={cn(error && "text-red-500 dark:text-red-900", className)}
+      className={cn(error && styles.labelError, className)}
       htmlFor={formItemId}
       {...props}
     />
@@ -94,21 +225,66 @@ const FormLabel = React.forwardRef<
 });
 FormLabel.displayName = "FormLabel";
 
-const FormControl = React.forwardRef<React.ComponentRef<typeof Slot>, React.ComponentPropsWithoutRef<typeof Slot>>(({...props}, ref) => {
-  const {error, formItemId, formDescriptionId, formMessageId} = useFormField();
+/**
+ * Provides react-hook-form field metadata to a single control element.
+ *
+ * @remarks
+ * This replaces the former Radix Slot-based implementation by cloning the
+ * direct child element and merging the accessibility attributes required by the
+ * surrounding form primitives. A fallback wrapper is rendered only when the
+ * child is not a valid React element.
+ */
+const FormControl = React.forwardRef<HTMLElement, FormControlProps>(
+  ({children, ...props}: Readonly<FormControlProps>, ref): React.JSX.Element => {
+    const {error, formDescriptionId, formItemId, formMessageId} = useFormField();
+    const describedBy = mergeAriaDescribedBy(
+      typeof props["aria-describedby"] === "string" ? props["aria-describedby"] : undefined,
+      formDescriptionId,
+      error ? formMessageId : undefined,
+    );
 
-  return (
-    <Slot
-      ref={ref}
-      id={formItemId}
-      aria-describedby={error ? `${formDescriptionId} ${formMessageId}` : `${formDescriptionId}`}
-      aria-invalid={Boolean(error)}
-      {...props}
-    />
-  );
-});
+    if (React.isValidElement(children)) {
+      const child = children as React.ReactElement<FormControlElementProps>;
+      const childDescribedBy = typeof child.props["aria-describedby"] === "string" ? child.props["aria-describedby"] : undefined;
+
+      // eslint-disable-next-line react-x/no-clone-element -- removes Radix Slot while preserving child element semantics
+      return React.cloneElement(child, {
+        ...props,
+        ref: composeRefs(ref, child.props.ref),
+        id: formItemId,
+        "aria-describedby": mergeAriaDescribedBy(childDescribedBy, describedBy),
+        "aria-invalid": Boolean(error),
+      });
+    }
+
+    return (
+      <div
+        ref={ref as React.Ref<HTMLDivElement>}
+        id={formItemId}
+        aria-describedby={describedBy}
+        aria-invalid={Boolean(error)}
+        {...props}>
+        {children}
+      </div>
+    );
+  },
+);
 FormControl.displayName = "FormControl";
 
+/**
+ * Renders helper text that describes the current form control.
+ *
+ * @remarks
+ * - Renders a `<p>` element
+ * - Built on the shared form field metadata hook
+ *
+ * @example
+ * ```tsx
+ * <FormDescription>We'll never share your email.</FormDescription>
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/HTML/Element/p | HTML paragraph element}
+ */
 const FormDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(({className, ...props}, ref) => {
   const {formDescriptionId} = useFormField();
 
@@ -116,17 +292,31 @@ const FormDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttribu
     <p
       ref={ref}
       id={formDescriptionId}
-      className={cn("text-[0.8rem] text-neutral-500 dark:text-neutral-400", className)}
+      className={cn(styles.description, className)}
       {...props}
     />
   );
 });
 FormDescription.displayName = "FormDescription";
 
+/**
+ * Renders the validation message or fallback message for the current form control.
+ *
+ * @remarks
+ * - Renders a `<p>` element when content is available
+ * - Built on the shared form field metadata hook
+ *
+ * @example
+ * ```tsx
+ * <FormMessage />
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid | ARIA invalid state}
+ */
 const FormMessage = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
   ({className, children, ...props}, ref) => {
     const {error, formMessageId} = useFormField();
-    const body = error ? String(error?.message ?? "") : children;
+    const body = error ? String(error.message ?? "") : children;
 
     if (!body) {
       return null;
@@ -136,7 +326,7 @@ const FormMessage = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<
       <p
         ref={ref}
         id={formMessageId}
-        className={cn("text-[0.8rem] font-medium text-red-500 dark:text-red-900", className)}
+        className={cn(styles.message, className)}
         {...props}>
         {body}
       </p>
@@ -144,5 +334,26 @@ const FormMessage = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<
   },
 );
 FormMessage.displayName = "FormMessage";
+FormField.displayName = "FormField";
 
+export {Controller, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch} from "react-hook-form";
+export type {
+  Control,
+  ControllerFieldState,
+  ControllerProps,
+  ControllerRenderProps,
+  DefaultValues,
+  FieldError,
+  FieldErrors,
+  FieldPath,
+  FieldValues,
+  Path,
+  RegisterOptions,
+  Resolver,
+  SubmitHandler,
+  UseControllerReturn,
+  UseFieldArrayReturn,
+  UseFormReturn,
+} from "react-hook-form";
 export {Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField};
+export type {FormControlProps};

package/src/components/ui/gradient-background.module.css

@@ -0,0 +1,6 @@
+.root {
+  width: 100%;
+  height: 100%;
+  background-image: linear-gradient(135deg, #3b82f6 0%, #a855f7 50%, #ec4899 100%);
+  background-size: 400% 400%;
+}

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

@@ -1,25 +1,47 @@
 "use client";
 
-import {HTMLMotionProps, motion, type Transition} from "motion/react";
+import {motion, type HTMLMotionProps, type Transition} from "motion/react";
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./gradient-background.module.css";
 
-interface GradientBackgroundProps extends HTMLMotionProps<"div"> {
+/** Props accepted by {@link GradientBackground}. */
+export interface GradientBackgroundProps extends HTMLMotionProps<"div"> {
+  /** Motion timing used for the animated background-position sweep. @default {duration: 15, ease: "easeInOut", repeat: Infinity} */
   transition?: Transition;
 }
 
+/**
+ * Renders a continuously shifting multicolor gradient background.
+ *
+ * @remarks
+ * - Animated component using the `motion` library
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ * - Client-side only (`"use client"` directive)
+ *
+ * @example
+ * ```tsx
+ * <GradientBackground />
+ * ```
+ *
+ * @see {@link GradientBackgroundProps} for available props
+ */
 const GradientBackground = React.forwardRef<HTMLDivElement, GradientBackgroundProps>(
   ({className, transition = {duration: 15, ease: "easeInOut", repeat: Infinity}, ...props}, ref) => {
+    // eslint-disable-next-line sonarjs/no-unused-vars -- removing React key avoids implicit key spreading
+    const {key: _ignoredKey, ...restProps} = props;
+
     return (
       <motion.div
         ref={ref}
-        className={cn("size-full bg-gradient-to-br from-blue-500 via-purple-500 to-pink-500 bg-[length:400%_400%]", className)}
+        className={cn(styles.root, className)}
         animate={{
           backgroundPosition: ["0% 50%", "100% 50%", "0% 50%"],
         }}
         transition={transition}
-        {...props}
+        {...restProps}
       />
     );
   },
@@ -27,4 +49,4 @@ const GradientBackground = React.forwardRef<HTMLDivElement, GradientBackgroundPr
 
 GradientBackground.displayName = "GradientBackground";
 
-export {GradientBackground, type GradientBackgroundProps};
+export {GradientBackground};

package/src/components/ui/gradient-text.module.css

@@ -0,0 +1,23 @@
+.root {
+  position: relative;
+  display: inline-block;
+}
+
+.text,
+.neon {
+  margin: 0;
+  color: transparent;
+  background-image: var(--ac-gradient-text-background);
+  background-position: 0% 0%;
+  background-size: 700% 100%;
+  -webkit-background-clip: text;
+  background-clip: text;
+}
+
+.neon {
+  position: absolute;
+  inset: 0;
+  filter: blur(8px);
+  mix-blend-mode: plus-lighter;
+  pointer-events: none;
+}

package/src/components/ui/gradient-text.tsx

@@ -4,14 +4,40 @@ import {motion, type Transition} from "motion/react";
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./gradient-text.module.css";
 
-interface GradientTextProps extends React.HTMLAttributes<HTMLSpanElement> {
+/** Props accepted by {@link GradientText}. */
+export interface GradientTextProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Text content rendered with the animated gradient fill. @default undefined */
   text: string;
+  /** CSS gradient string assigned to the animated text fill. @default "linear-gradient(90deg, #3b82f6 0%, #a855f7 20%, #ec4899 50%, #a855f7 80%, #3b82f6 100%)" */
   gradient?: string;
+  /** Adds a blurred neon duplicate behind the primary text layer. @default false */
   neon?: boolean;
+  /** Motion timing used for the animated gradient background. @default {duration: 50, repeat: Infinity, ease: "linear"} */
   transition?: Transition;
 }
 
+type GradientStyleProperties = React.CSSProperties & {
+  "--ac-gradient-text-background": string;
+};
+
+/**
+ * Renders animated gradient-filled text with an optional neon glow layer.
+ *
+ * @remarks
+ * - Animated component using the `motion` library
+ * - Renders a `<span>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ * - Client-side only (`"use client"` directive)
+ *
+ * @example
+ * ```tsx
+ * <GradientText text="Launch ready" />
+ * ```
+ *
+ * @see {@link GradientTextProps} for available props
+ */
 const GradientText = React.forwardRef<HTMLSpanElement, GradientTextProps>(
   (
     {
@@ -24,17 +50,17 @@ const GradientText = React.forwardRef<HTMLSpanElement, GradientTextProps>(
     },
     ref,
   ) => {
-    const baseStyle: React.CSSProperties = {
-      backgroundImage: gradient,
+    const baseStyle: GradientStyleProperties = {
+      "--ac-gradient-text-background": gradient,
     };
 
     return (
       <span
         ref={ref}
-        className={cn("relative inline-block", className)}
+        className={cn(styles.root, className)}
         {...props}>
         <motion.span
-          className='m-0 bg-[length:700%_100%] bg-clip-text bg-[position:0%_0%] text-transparent'
+          className={styles.text}
           style={baseStyle}
           initial={{backgroundPosition: "0% 0%"}}
           animate={{backgroundPosition: "500% 100%"}}
@@ -42,16 +68,17 @@ const GradientText = React.forwardRef<HTMLSpanElement, GradientTextProps>(
           {text}
         </motion.span>
 
-        {Boolean(neon) && (
+        {neon ? (
           <motion.span
-            className='absolute top-0 left-0 m-0 bg-[length:700%_100%] bg-clip-text bg-[position:0%_0%] text-transparent mix-blend-plus-lighter blur-[8px]'
+            aria-hidden='true'
+            className={styles.neon}
             style={baseStyle}
             initial={{backgroundPosition: "0% 0%"}}
             animate={{backgroundPosition: "500% 100%"}}
             transition={transition}>
             {text}
           </motion.span>
-        )}
+        ) : null}
       </span>
     );
   },
@@ -59,4 +86,4 @@ const GradientText = React.forwardRef<HTMLSpanElement, GradientTextProps>(
 
 GradientText.displayName = "GradientText";
 
-export {GradientText, type GradientTextProps};
+export {GradientText};

package/src/components/ui/highlight-text.module.css

@@ -0,0 +1,14 @@
+.highlight {
+  position: relative;
+  display: inline;
+  padding: 0.25rem 0.5rem;
+  border-radius: var(--ac-radius-lg);
+  background-image: linear-gradient(90deg, #dbeafe 0%, #f3e8ff 100%);
+  background-position: left center;
+  background-repeat: no-repeat;
+}
+
+:global(.dark) .highlight,
+:global([data-theme="dark"]) .highlight {
+  background-image: linear-gradient(90deg, color-mix(in oklch, var(--ac-primary), white 35%) 0%, color-mix(in oklch, #a855f7, white 15%) 100%);
+}