@arolariu/components 0.4.2 → 1.0.0

package/src/components/ui/alert.tsx

@@ -1,57 +1,150 @@
-"use client";
-
-import {cva, type VariantProps} from "class-variance-authority";
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./alert.module.css";
 
-const alertVariants = cva(
-  "relative w-full rounded-lg border border-neutral-200 px-4 py-3 text-sm [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-neutral-950 [&>svg~*]:pl-7 dark:border-neutral-800 dark:[&>svg]:text-neutral-50",
-  {
-    variants: {
-      variant: {
-        default: "bg-white text-neutral-950 dark:bg-neutral-950 dark:text-neutral-50",
-        destructive:
-          "border-red-500/50 text-red-500 dark:border-red-500 [&>svg]:text-red-500 dark:border-red-900/50 dark:text-red-900 dark:dark:border-red-900 dark:[&>svg]:text-red-900",
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-    },
-  },
-);
-
-const Alert = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>>(
-  ({className, variant, ...props}, ref) => (
-    <div
-      ref={ref}
-      role='alert'
-      className={cn(alertVariants({variant}), className)}
-      {...props}
-    />
-  ),
-);
-Alert.displayName = "Alert";
+/**
+ * Defines the supported visual treatments for the Alert component.
+ */
+export type AlertVariant = "default" | "destructive";
 
-const AlertTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(({className, ...props}, ref) => (
-  // eslint-disable-next-line jsx-a11y/heading-has-content -- this will be filled with children.
-  <h5
+const variantStyles: Record<AlertVariant, string> = {
+  default: styles.default!,
+  destructive: styles.destructive!,
+};
+
+/**
+ * Represents the configurable props for the Alert component.
+ *
+ * @remarks
+ * Extends native `<div>` attributes so alerts can expose ARIA relationships,
+ * data attributes, and custom event handlers while selecting a visual variant.
+ *
+ * @default variant `"default"`
+ */
+export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Additional CSS classes merged with the base alert surface styles.
+   */
+  className?: string;
+  /**
+   * The visual tone used to communicate neutral or destructive feedback.
+   *
+   * @default "default"
+   */
+  variant?: AlertVariant;
+}
+
+/**
+ * A bordered feedback container for inline status, warning, or error messaging.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible presentational component.
+ *
+ * Renders a `<div>` with `role="alert"` so assistive technologies announce urgent
+ * content. Use {@link AlertTitle} and {@link AlertDescription} to build a clear,
+ * accessible message structure.
+ *
+ * @example
+ * ```tsx
+ * <Alert variant="destructive">
+ *   <AlertTitle>Payment failed</AlertTitle>
+ *   <AlertDescription>Verify your card details and try again.</AlertDescription>
+ * </Alert>
+ * ```
+ *
+ * @see {@link AlertTitle}
+ * @see {@link AlertDescription}
+ * @see {@link https://base-ui.com/react/overview Base UI documentation}
+ */
+const Alert = React.forwardRef<HTMLDivElement, AlertProps>(({className, variant = "default", ...props}, ref) => (
+  <div
     ref={ref}
-    className={cn("mb-1 leading-none font-medium tracking-tight", className)}
+    role='alert'
+    className={cn(styles.alert, variantStyles[variant], className)}
     {...props}
   />
 ));
+Alert.displayName = "Alert";
+
+/**
+ * Represents the configurable props for the AlertTitle component.
+ *
+ * @remarks
+ * Extends native heading attributes and exposes a class override for styling.
+ */
+interface AlertTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  /**
+   * Additional CSS classes merged with the alert title styles.
+   */
+  className?: string;
+}
+
+/**
+ * The heading slot for the primary alert message.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible presentational component.
+ *
+ * Renders an `<h5>` element styled for compact but prominent messaging. Pair it with
+ * {@link AlertDescription} when the alert needs supporting explanatory text.
+ *
+ * @example
+ * ```tsx
+ * <AlertTitle>Heads up</AlertTitle>
+ * ```
+ *
+ * @see {@link AlertDescription}
+ * @see {@link https://base-ui.com/react/overview Base UI documentation}
+ */
+const AlertTitle = React.forwardRef<HTMLHeadingElement, AlertTitleProps>(({children, className, ...props}, ref) => (
+  <h5
+    ref={ref}
+    className={cn(styles.title, className)}
+    {...props}>
+    {children}
+  </h5>
+));
 AlertTitle.displayName = "AlertTitle";
 
-const AlertDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
-  ({className, ...props}, ref) => (
-    <div
-      ref={ref}
-      className={cn("text-sm [&_p]:leading-relaxed", className)}
-      {...props}
-    />
-  ),
-);
+/**
+ * Represents the configurable props for the AlertDescription component.
+ *
+ * @remarks
+ * Extends native `<div>` attributes so rich supporting content can be rendered inside
+ * an alert body while preserving the component's spacing and typography.
+ */
+interface AlertDescriptionProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Additional CSS classes merged with the alert description styles.
+   */
+  className?: string;
+}
+
+/**
+ * A supporting content slot for additional alert details.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible presentational component.
+ *
+ * Renders a styled `<div>` so the alert body can contain paragraphs, lists, links,
+ * or other rich inline content beneath the title.
+ *
+ * @example
+ * ```tsx
+ * <AlertDescription>API access will be restored after the billing issue is resolved.</AlertDescription>
+ * ```
+ *
+ * @see {@link AlertTitle}
+ * @see {@link https://base-ui.com/react/overview Base UI documentation}
+ */
+const AlertDescription = React.forwardRef<HTMLDivElement, AlertDescriptionProps>(({className, ...props}, ref) => (
+  <div
+    ref={ref}
+    className={cn(styles.description, className)}
+    {...props}
+  />
+));
 AlertDescription.displayName = "AlertDescription";
 
 export {Alert, AlertDescription, AlertTitle};

package/src/components/ui/aspect-ratio.module.css

@@ -0,0 +1,7 @@
+.root {
+  position: relative;
+  display: block;
+  width: 100%;
+  overflow: hidden;
+  border-radius: inherit;
+}

package/src/components/ui/aspect-ratio.tsx

@@ -1,7 +1,42 @@
-"use client";
+import * as React from "react";
 
-import * as AspectRatioPrimitive from "@radix-ui/react-aspect-ratio";
+import {cn} from "@/lib/utilities";
+import styles from "./aspect-ratio.module.css";
 
-const AspectRatio = AspectRatioPrimitive.Root;
+/**
+ * Props for the {@link AspectRatio} component.
+ */
+export interface AspectRatioProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Aspect ratio applied to the wrapper element. @default 1 */
+  ratio?: number | string;
+}
+
+/**
+ * Preserves a predictable width-to-height ratio for arbitrary content.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <AspectRatio ratio={16 / 9}>Media</AspectRatio>
+ * ```
+ *
+ * @see {@link AspectRatioProps} for available props
+ */
+const AspectRatio = React.forwardRef<HTMLDivElement, AspectRatioProps>(
+  ({className, ratio = 1, style, ...props}: Readonly<AspectRatioProps>, ref): React.JSX.Element => (
+    <div
+      ref={ref}
+      className={cn(styles.root, className)}
+      style={{...style, aspectRatio: String(ratio)}}
+      {...props}
+    />
+  ),
+);
+
+AspectRatio.displayName = "AspectRatio";
 
 export {AspectRatio};

package/src/components/ui/async-boundary.tsx

@@ -0,0 +1,56 @@
+import * as React from "react";
+
+import {ErrorBoundary, type ErrorBoundaryProps} from "./error-boundary";
+import {Spinner} from "./spinner";
+
+/**
+ * Represents the configurable props for the {@link AsyncBoundary} component.
+ *
+ * @remarks
+ * Extends the shared error boundary contract with a Suspense fallback so async child
+ * trees can handle loading and error states through a single composition primitive.
+ */
+interface AsyncBoundaryProps extends Omit<ErrorBoundaryProps, "children"> {
+  /**
+   * Content that may suspend or throw during rendering.
+   */
+  children: React.ReactNode;
+  /**
+   * Fallback UI rendered while descendants are suspended.
+   *
+   * @default <Spinner />
+   */
+  loadingFallback?: React.ReactNode;
+}
+
+/**
+ * Combines Suspense loading behavior with error boundary recovery semantics.
+ *
+ * @remarks
+ * **Rendering Context**: Server- and client-compatible composition component.
+ *
+ * Wrap async child trees with this component to centralize loading and error handling.
+ * The loading fallback is rendered by `React.Suspense`, while rendering errors are
+ * delegated to the shared client-side {@link ErrorBoundary}.
+ *
+ * @example
+ * ```tsx
+ * <AsyncBoundary loadingFallback={<CardSkeleton />}>
+ *   <AsyncDataPanel />
+ * </AsyncBoundary>
+ * ```
+ *
+ * @see {@link AsyncBoundaryProps} for available props
+ */
+function AsyncBoundary({children, loadingFallback, ...errorBoundaryProps}: Readonly<AsyncBoundaryProps>): React.JSX.Element {
+  return (
+    <ErrorBoundary {...errorBoundaryProps}>
+      <React.Suspense fallback={loadingFallback ?? <Spinner />}>{children}</React.Suspense>
+    </ErrorBoundary>
+  );
+}
+
+AsyncBoundary.displayName = "AsyncBoundary";
+
+export {AsyncBoundary};
+export type {AsyncBoundaryProps};

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

@@ -0,0 +1,31 @@
+.root {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  flex-shrink: 0;
+  overflow: hidden;
+  border-radius: 9999px;
+}
+
+.image {
+  aspect-ratio: 1 / 1;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.fallback {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: 9999px;
+  background-color: var(--ac-muted);
+  color: var(--ac-muted-foreground);
+  font-size: var(--ac-text-sm);
+  font-weight: 500;
+}

package/src/components/ui/avatar.tsx

@@ -1,44 +1,154 @@
 "use client";
 
-import * as AvatarPrimitive from "@radix-ui/react-avatar";
+import {Avatar as BaseAvatar} from "@base-ui/react/avatar";
+import {mergeProps} from "@base-ui/react/merge-props";
+import {useRender} from "@base-ui/react/use-render";
 import * as React from "react";
 
 import {cn} from "@/lib/utilities";
+import styles from "./avatar.module.css";
 
-const Avatar = React.forwardRef<
-  React.ComponentRef<typeof AvatarPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>
->(({className, ...props}, ref) => (
-  <AvatarPrimitive.Root
-    ref={ref}
-    className={cn("relative flex h-10 w-10 shrink-0 overflow-hidden rounded-full", className)}
-    {...props}
-  />
-));
-Avatar.displayName = AvatarPrimitive.Root.displayName;
-
-const AvatarImage = React.forwardRef<
-  React.ComponentRef<typeof AvatarPrimitive.Image>,
-  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Image>
->(({className, ...props}, ref) => (
-  <AvatarPrimitive.Image
-    ref={ref}
-    className={cn("aspect-square h-full w-full", className)}
-    {...props}
-  />
-));
-AvatarImage.displayName = AvatarPrimitive.Image.displayName;
-
-const AvatarFallback = React.forwardRef<
-  React.ComponentRef<typeof AvatarPrimitive.Fallback>,
-  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback>
->(({className, ...props}, ref) => (
-  <AvatarPrimitive.Fallback
-    ref={ref}
-    className={cn("flex h-full w-full items-center justify-center rounded-full bg-neutral-100 dark:bg-neutral-800", className)}
-    {...props}
-  />
-));
-AvatarFallback.displayName = AvatarPrimitive.Fallback.displayName;
+/**
+ * Props for the shared avatar root.
+ */
+interface AvatarProps extends Omit<React.ComponentPropsWithRef<typeof BaseAvatar.Root>, "className"> {
+  /** Additional CSS classes merged with the avatar root styles. @default undefined */
+  className?: string;
+}
+
+/**
+ * Props for the shared avatar image.
+ */
+interface AvatarImageProps extends Omit<React.ComponentPropsWithRef<typeof BaseAvatar.Image>, "className"> {
+  /** Additional CSS classes merged with the avatar image styles. @default undefined */
+  className?: string;
+}
+
+/**
+ * Props for the shared avatar fallback.
+ */
+interface AvatarFallbackProps extends Omit<React.ComponentPropsWithRef<typeof BaseAvatar.Fallback>, "className"> {
+  /** Additional CSS classes merged with the avatar fallback styles. @default undefined */
+  className?: string;
+}
+
+/**
+ * Displays a user avatar container with shared sizing and shape styles.
+ *
+ * @remarks
+ * - Renders a `<span>` element by default
+ * - Built on {@link https://base-ui.com/react/components/avatar | Base UI Avatar}
+ * - Supports the `render` prop for element composition
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Avatar>
+ *   <AvatarImage src="/profile.png" alt="Profile" />
+ *   <AvatarFallback>AO</AvatarFallback>
+ * </Avatar>
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/avatar | Base UI Documentation}
+ */
+function Avatar(props: Readonly<Avatar.Props>): React.ReactElement {
+  const {className, children, render, ...otherProps} = props;
+
+  return (
+    <BaseAvatar.Root
+      {...otherProps}
+      render={useRender({
+        defaultTagName: "span",
+        render: render as never,
+        props: mergeProps({className: cn(styles.root, className)}, {}),
+      })}>
+      {children}
+    </BaseAvatar.Root>
+  );
+}
+Avatar.displayName = "Avatar";
+
+/**
+ * Renders the primary avatar image inside the avatar root.
+ *
+ * @remarks
+ * - Renders an `<img>` element by default
+ * - Built on {@link https://base-ui.com/react/components/avatar | Base UI Avatar}
+ * - Supports the `render` prop for element composition
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example Basic usage
+ * ```tsx
+ * <AvatarImage src="/profile.png" alt="Profile" />
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/avatar | Base UI Documentation}
+ */
+function AvatarImage(props: Readonly<AvatarImage.Props>): React.ReactElement {
+  const {className, render, ...otherProps} = props;
+
+  return (
+    <BaseAvatar.Image
+      {...otherProps}
+      render={useRender({
+        defaultTagName: "img",
+        render: render as never,
+        props: mergeProps({className: cn(styles.image, className)}, {}),
+      })}
+    />
+  );
+}
+AvatarImage.displayName = "AvatarImage";
+
+/**
+ * Renders fallback content when the avatar image is unavailable.
+ *
+ * @remarks
+ * - Renders a `<span>` element by default
+ * - Built on {@link https://base-ui.com/react/components/avatar | Base UI Avatar}
+ * - Supports the `render` prop for element composition
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example Basic usage
+ * ```tsx
+ * <AvatarFallback>AO</AvatarFallback>
+ * ```
+ *
+ * @see {@link https://base-ui.com/react/components/avatar | Base UI Documentation}
+ */
+function AvatarFallback(props: Readonly<AvatarFallback.Props>): React.ReactElement {
+  const {className, children, render, ...otherProps} = props;
+
+  return (
+    <BaseAvatar.Fallback
+      {...otherProps}
+      render={useRender({
+        defaultTagName: "span",
+        render: render as never,
+        props: mergeProps({className: cn(styles.fallback, className)}, {}),
+      })}>
+      {children}
+    </BaseAvatar.Fallback>
+  );
+}
+AvatarFallback.displayName = "AvatarFallback";
+
+// eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
+namespace Avatar {
+  export type Props = AvatarProps;
+  export type State = BaseAvatar.Root.State;
+}
+
+// eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
+namespace AvatarImage {
+  export type Props = AvatarImageProps;
+  export type State = BaseAvatar.Image.State;
+}
+
+// eslint-disable-next-line no-redeclare -- required for the canonical component namespace typing API
+namespace AvatarFallback {
+  export type Props = AvatarFallbackProps;
+  export type State = BaseAvatar.Fallback.State;
+}
 
 export {Avatar, AvatarFallback, AvatarImage};

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

@@ -0,0 +1,20 @@
+.root {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  width: 100%;
+  height: 100%;
+  align-items: center;
+  justify-content: center;
+  mask-repeat: no-repeat;
+  mask-size: 40px;
+}
+
+.svg {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}