@arolariu/components 0.5.0 → 1.0.0

package/src/components/ui/field.tsx

@@ -1,199 +1,405 @@
 "use client";
 
-import {cva, type VariantProps} from "class-variance-authority";
+/* eslint-disable jsx-a11y/label-has-associated-control */
+
 import * as React from "react";
 
-import {Label} from "@/components/ui/label";
 import {Separator} from "@/components/ui/separator";
 import {cn} from "@/lib/utilities";
+import styles from "./field.module.css";
+
+/** Supported layouts for {@link Field}. */
+export type FieldOrientation = "vertical" | "horizontal" | "responsive";
+
+/** Supported legend render styles for {@link FieldLegend}. */
+export type FieldLegendVariant = "legend" | "label";
+
+/** Shape of error objects accepted by {@link FieldError}. */
+export interface FieldErrorItem {
+  /** Human-readable validation error message. @default undefined */
+  message?: string;
+}
+
+/**
+ * Props for the {@link FieldSet} component.
+ */
+export type FieldSetProps = React.ComponentPropsWithoutRef<"fieldset">;
+
+/**
+ * Props for the {@link FieldLegend} component.
+ */
+export interface FieldLegendProps extends React.ComponentPropsWithoutRef<"legend"> {
+  /** Visual treatment used for the legend content. @default "legend" */
+  variant?: FieldLegendVariant;
+}
+
+/**
+ * Props for the {@link FieldGroup} component.
+ */
+export type FieldGroupProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Props for the {@link Field} component.
+ */
+export interface FieldProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Layout used to arrange labels and controls. @default "vertical" */
+  orientation?: FieldOrientation;
+}
+
+/**
+ * Props for the {@link FieldContent} component.
+ */
+export type FieldContentProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Props for the {@link FieldLabel} component.
+ */
+export type FieldLabelProps = React.ComponentPropsWithoutRef<"label">;
+
+/**
+ * Props for the {@link FieldTitle} component.
+ */
+export type FieldTitleProps = React.ComponentPropsWithoutRef<"div">;
 
-function FieldSet({className, ...props}: React.ComponentProps<"fieldset">) {
-  return (
+/**
+ * Props for the {@link FieldDescription} component.
+ */
+export type FieldDescriptionProps = React.ComponentPropsWithoutRef<"p">;
+
+/**
+ * Props for the {@link FieldSeparator} component.
+ */
+export type FieldSeparatorProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Props for the {@link FieldError} component.
+ */
+export interface FieldErrorProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Validation errors rendered when children are not provided. @default undefined */
+  errors?: Array<FieldErrorItem | undefined>;
+}
+
+function getFieldOrientationClass(orientation: FieldOrientation): string {
+  switch (orientation) {
+    case "horizontal": {
+      return styles.horizontal;
+    }
+    case "responsive": {
+      return styles.responsive;
+    }
+    default: {
+      return styles.vertical;
+    }
+  }
+}
+
+/**
+ * Groups related controls within a semantic fieldset.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<fieldset>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Preferences</FieldLegend>
+ * </FieldSet>
+ * ```
+ *
+ * @see {@link FieldSetProps} for available props
+ */
+const FieldSet = React.forwardRef<HTMLFieldSetElement, FieldSetProps>(
+  ({className, ...props}: Readonly<FieldSetProps>, ref): React.JSX.Element => (
     <fieldset
+      ref={ref}
       data-slot='field-set'
-      className={cn("flex flex-col gap-6", "has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3", className)}
+      className={cn(styles.fieldSet, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function FieldLegend({className, variant = "legend", ...props}: React.ComponentProps<"legend"> & {variant?: "legend" | "label"}) {
-  return (
+/**
+ * Labels a grouped set of controls within {@link FieldSet}.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<legend>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldLegend variant='label'>Billing address</FieldLegend>
+ * ```
+ *
+ * @see {@link FieldLegendProps} for available props
+ */
+const FieldLegend = React.forwardRef<HTMLLegendElement, FieldLegendProps>(
+  ({className, variant = "legend", ...props}: Readonly<FieldLegendProps>, ref): React.JSX.Element => (
     <legend
+      ref={ref}
       data-slot='field-legend'
       data-variant={variant}
-      className={cn("mb-3 font-medium", "data-[variant=legend]:text-base", "data-[variant=label]:text-sm", className)}
+      className={cn(styles.legend, variant === "label" ? styles.legendLabel : styles.legendDefault, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function FieldGroup({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Stacks multiple field rows under a shared container.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldGroup>
+ *   <Field />
+ * </FieldGroup>
+ * ```
+ *
+ * @see {@link FieldGroupProps} for available props
+ */
+const FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(
+  ({className, ...props}: Readonly<FieldGroupProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='field-group'
-      className={cn(
-        "group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4",
-        className,
-      )}
+      className={cn(styles.group, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-const fieldVariants = cva("group/field data-[invalid=true]:text-red-500 flex w-full gap-3 dark:data-[invalid=true]:text-red-900", {
-  variants: {
-    orientation: {
-      vertical: ["flex-col [&>*]:w-full [&>.sr-only]:w-auto"],
-      horizontal: [
-        "flex-row items-center",
-        "[&>[data-slot=field-label]]:flex-auto",
-        "has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px has-[>[data-slot=field-content]]:items-start",
-      ],
-      responsive: [
-        "@md/field-group:flex-row @md/field-group:items-center @md/field-group:[&>*]:w-auto flex-col [&>*]:w-full [&>.sr-only]:w-auto",
-        "@md/field-group:[&>[data-slot=field-label]]:flex-auto",
-        "@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
-      ],
-    },
-  },
-  defaultVariants: {
-    orientation: "vertical",
-  },
-});
-
-function Field({className, orientation = "vertical", ...props}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
-  return (
+/**
+ * Creates a styled field row for labels, descriptions, and controls.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <Field orientation='responsive'>...</Field>
+ * ```
+ *
+ * @see {@link FieldProps} for available props
+ */
+const Field = React.forwardRef<HTMLDivElement, FieldProps>(
+  ({className, orientation = "vertical", ...props}: Readonly<FieldProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       role='group'
       data-slot='field'
       data-orientation={orientation}
-      className={cn(fieldVariants({orientation}), className)}
+      className={cn(styles.field, getFieldOrientationClass(orientation), className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function FieldContent({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Wraps field controls and supporting content.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldContent>{control}</FieldContent>
+ * ```
+ *
+ * @see {@link FieldContentProps} for available props
+ */
+const FieldContent = React.forwardRef<HTMLDivElement, FieldContentProps>(
+  ({className, ...props}: Readonly<FieldContentProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='field-content'
-      className={cn("group/field-content flex flex-1 flex-col gap-1.5 leading-snug", className)}
+      className={cn(styles.content, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function FieldLabel({className, ...props}: React.ComponentProps<typeof Label>) {
-  return (
-    <Label
-      data-slot='field-label'
-      className={cn(
-        "group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50",
-        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>[data-slot=field]]:p-4",
-        "has-data-[state=checked]:border-neutral-900 has-data-[state=checked]:bg-neutral-900/5 dark:has-data-[state=checked]:border-neutral-50 dark:dark:has-data-[state=checked]:bg-neutral-50/10 dark:has-data-[state=checked]:bg-neutral-50/5 dark:has-data-[state=checked]:bg-neutral-900/10",
-        className,
-      )}
-      {...props}
-    />
-  );
-}
+/**
+ * Renders the label associated with a form control.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<label>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldLabel htmlFor='email'>Email</FieldLabel>
+ * ```
+ *
+ * @see {@link FieldLabelProps} for available props
+ */
+const FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(
+  ({className, ...props}: Readonly<FieldLabelProps>, ref): React.JSX.Element => {
+    return (
+      <label
+        ref={ref}
+        data-slot='field-label'
+        className={cn(styles.label, className)}
+        {...props}
+      />
+    );
+  },
+);
 
-function FieldTitle({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Displays the leading title content for a field row.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldTitle>Account</FieldTitle>
+ * ```
+ *
+ * @see {@link FieldTitleProps} for available props
+ */
+const FieldTitle = React.forwardRef<HTMLDivElement, FieldTitleProps>(
+  ({className, ...props}: Readonly<FieldTitleProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='field-label'
-      className={cn(
-        "flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50",
-        className,
-      )}
+      className={cn(styles.title, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function FieldDescription({className, ...props}: React.ComponentProps<"p">) {
-  return (
+/**
+ * Renders supplementary descriptive text for a field.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<p>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldDescription>Used for account recovery.</FieldDescription>
+ * ```
+ *
+ * @see {@link FieldDescriptionProps} for available props
+ */
+const FieldDescription = React.forwardRef<HTMLParagraphElement, FieldDescriptionProps>(
+  ({className, ...props}: Readonly<FieldDescriptionProps>, ref): React.JSX.Element => (
     <p
+      ref={ref}
       data-slot='field-description'
-      className={cn(
-        "text-sm leading-normal font-normal text-neutral-500 group-has-[[data-orientation=horizontal]]/field:text-balance dark:text-neutral-400",
-        "last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5",
-        "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-neutral-900 dark:[&>a:hover]:text-neutral-50",
-        className,
-      )}
+      className={cn(styles.description, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function FieldSeparator({
-  children,
-  className,
-  ...props
-}: React.ComponentProps<"div"> & {
-  children?: React.ReactNode;
-}) {
-  return (
+/**
+ * Separates field sections with optional inline content.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldSeparator>or</FieldSeparator>
+ * ```
+ *
+ * @see {@link FieldSeparatorProps} for available props
+ */
+const FieldSeparator = React.forwardRef<HTMLDivElement, FieldSeparatorProps>(
+  ({children, className, ...props}: Readonly<FieldSeparatorProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='field-separator'
-      data-content={Boolean(children) || undefined}
-      className={cn("relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2", className)}
+      data-content={children ? "true" : undefined}
+      className={cn(styles.separator, className)}
       {...props}>
-      <Separator className='absolute inset-0 top-1/2' />
-      {Boolean(children) && (
-        <span
-          className='relative mx-auto block w-fit bg-white px-2 text-neutral-500 dark:bg-neutral-950 dark:text-neutral-400'
-          data-slot='field-separator-content'>
-          {children}
-        </span>
-      )}
+      <Separator className={styles.separatorLine} />
+      {children ? <span className={styles.separatorContent}>{children}</span> : null}
     </div>
-  );
-}
+  ),
+);
 
-function FieldError({
-  className,
-  children,
-  errors,
-  ...props
-}: React.ComponentProps<"div"> & {
-  errors?: Array<{message?: string} | undefined>;
-}) {
-  // eslint-disable-next-line sonarjs/function-return-type -- expected different return type.
-  const content = React.useMemo(() => {
-    if (children) {
-      return children;
-    }
+/**
+ * Presents validation feedback for a field.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element when content exists
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <FieldError errors={[{message: "Required"}]} />
+ * ```
+ *
+ * @see {@link FieldErrorProps} for available props
+ */
+const FieldError = React.forwardRef<HTMLDivElement, FieldErrorProps>(
+  ({className, children, errors, ...props}: Readonly<FieldErrorProps>, ref): React.JSX.Element | null => {
+    const content = React.useMemo((): React.JSX.Element | null => {
+      if (children) {
+        return <span>{children}</span>;
+      }
 
-    if (!errors) {
-      return null;
-    }
+      if (!errors) {
+        return null;
+      }
+
+      if (errors.length === 1 && errors[0]?.message) {
+        return <span>{errors[0].message}</span>;
+      }
 
-    if (errors?.length === 1 && errors[0]?.message) {
-      return errors[0].message;
+      return (
+        <ul className={styles.errorList}>{errors.map((error, index) => (error?.message ? <li key={index}>{error.message}</li> : null))}</ul>
+      );
+    }, [children, errors]);
+
+    if (!content) {
+      return null;
     }
 
     return (
-      <ul className='ml-4 flex list-disc flex-col gap-1'>
-        {errors.map((error, index) => error?.message && <li key={index}>{error.message}</li>)}
-      </ul>
+      <div
+        ref={ref}
+        role='alert'
+        data-slot='field-error'
+        className={cn(styles.error, className)}
+        {...props}>
+        {content}
+      </div>
     );
-  }, [children, errors]);
-
-  if (!content) {
-    return null;
-  }
+  },
+);
 
-  return (
-    <div
-      role='alert'
-      data-slot='field-error'
-      className={cn("text-sm font-normal text-red-500 dark:text-red-900", className)}
-      {...props}>
-      {content}
-    </div>
-  );
-}
+FieldSet.displayName = "FieldSet";
+FieldLegend.displayName = "FieldLegend";
+FieldGroup.displayName = "FieldGroup";
+Field.displayName = "Field";
+FieldContent.displayName = "FieldContent";
+FieldLabel.displayName = "FieldLabel";
+FieldTitle.displayName = "FieldTitle";
+FieldDescription.displayName = "FieldDescription";
+FieldSeparator.displayName = "FieldSeparator";
+FieldError.displayName = "FieldError";
 
 export {Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle};

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

@@ -0,0 +1,13 @@
+.root {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+.canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}