@arolariu/components 0.5.0 → 1.0.0

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

@@ -0,0 +1,84 @@
+.empty {
+  display: flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ac-space-6);
+  padding: var(--ac-space-6);
+  border: 1px dashed var(--ac-border);
+  border-radius: var(--ac-radius-lg);
+  text-align: center;
+}
+
+.header {
+  display: flex;
+  max-width: 24rem;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--ac-space-2);
+  text-align: center;
+}
+
+.media {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: var(--ac-space-2);
+  flex-shrink: 0;
+}
+
+.media svg {
+  flex-shrink: 0;
+}
+
+.mediaIcon {
+  width: 2.5rem;
+  height: 2.5rem;
+  border: 1px solid var(--ac-border);
+  border-radius: var(--ac-radius-lg);
+  background-color: var(--ac-muted);
+  color: var(--ac-foreground);
+}
+
+.mediaIcon svg {
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
+.title {
+  color: var(--ac-foreground);
+  font-size: var(--ac-text-lg);
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+
+.description {
+  color: var(--ac-muted-foreground);
+  font-size: var(--ac-text-sm);
+  line-height: 1.6;
+}
+
+.description a {
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 4px;
+}
+
+@media (hover: hover) {
+  .description a:hover {
+    color: var(--ac-foreground);
+  }
+}
+
+.content {
+  display: flex;
+  width: 100%;
+  max-width: 24rem;
+  min-width: 0;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--ac-space-4);
+  font-size: var(--ac-text-sm);
+}

package/src/components/ui/empty.tsx

@@ -1,86 +1,210 @@
-"use client";
+import * as React from "react";
 
 import {cn} from "@/lib/utilities";
-import {cva, type VariantProps} from "class-variance-authority";
-import * as React from "react";
+import styles from "./empty.module.css";
+
+/** Supported visual treatments for {@link EmptyMedia}. */
+export type EmptyMediaVariant = "default" | "icon";
+
+/**
+ * Props for the {@link Empty} component.
+ */
+export type EmptyProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Props for the {@link EmptyHeader} component.
+ */
+export type EmptyHeaderProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Props for the {@link EmptyMedia} component.
+ */
+export interface EmptyMediaProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Visual presentation applied to the media container. @default "default" */
+  variant?: EmptyMediaVariant;
+}
+
+/**
+ * Props for the {@link EmptyTitle} component.
+ */
+export type EmptyTitleProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Props for the {@link EmptyDescription} component.
+ */
+export type EmptyDescriptionProps = React.ComponentPropsWithoutRef<"p">;
 
-function Empty({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Props for the {@link EmptyContent} component.
+ */
+export type EmptyContentProps = React.ComponentPropsWithoutRef<"div">;
+
+/**
+ * Creates a structured empty-state container.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <Empty>
+ *   <EmptyHeader />
+ * </Empty>
+ * ```
+ *
+ * @see {@link EmptyProps} for available props
+ */
+const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
+  ({className, ...props}: Readonly<EmptyProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='empty'
-      className={cn(
-        "flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance md:p-12",
-        className,
-      )}
+      className={cn(styles.empty, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function EmptyHeader({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Groups the leading header content for an empty state.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <EmptyHeader>Nothing here yet</EmptyHeader>
+ * ```
+ *
+ * @see {@link EmptyHeaderProps} for available props
+ */
+const EmptyHeader = React.forwardRef<HTMLDivElement, EmptyHeaderProps>(
+  ({className, ...props}: Readonly<EmptyHeaderProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='empty-header'
-      className={cn("flex max-w-sm flex-col items-center gap-2 text-center", className)}
+      className={cn(styles.header, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-const emptyMediaVariants = cva("mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0", {
-  variants: {
-    variant: {
-      default: "bg-transparent",
-      icon: "bg-neutral-100 text-neutral-950 flex size-10 shrink-0 items-center justify-center rounded-lg [&_svg:not([class*='size-'])]:size-6 dark:bg-neutral-800 dark:text-neutral-50",
-    },
-  },
-  defaultVariants: {
-    variant: "default",
-  },
-});
-
-function EmptyMedia({className, variant = "default", ...props}: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>) {
-  return (
+/**
+ * Hosts media or icon content for an empty state.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <EmptyMedia variant='icon'>📭</EmptyMedia>
+ * ```
+ *
+ * @see {@link EmptyMediaProps} for available props
+ */
+const EmptyMedia = React.forwardRef<HTMLDivElement, EmptyMediaProps>(
+  ({className, variant = "default", ...props}: Readonly<EmptyMediaProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='empty-icon'
       data-variant={variant}
-      className={cn(emptyMediaVariants({variant, className}))}
+      className={cn(styles.media, variant === "icon" && styles.mediaIcon, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function EmptyTitle({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Renders the primary title for an empty state.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <EmptyTitle>No results found</EmptyTitle>
+ * ```
+ *
+ * @see {@link EmptyTitleProps} for available props
+ */
+const EmptyTitle = React.forwardRef<HTMLDivElement, EmptyTitleProps>(
+  ({className, ...props}: Readonly<EmptyTitleProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='empty-title'
-      className={cn("text-lg font-medium tracking-tight", className)}
+      className={cn(styles.title, className)}
       {...props}
     />
-  );
-}
+  ),
+);
 
-function EmptyDescription({className, ...props}: React.ComponentProps<"p">) {
-  return (
-    <div
+/**
+ * Renders supporting copy for an empty state.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<p>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <EmptyDescription>Try adjusting your filters.</EmptyDescription>
+ * ```
+ *
+ * @see {@link EmptyDescriptionProps} for available props
+ */
+const EmptyDescription = React.forwardRef<HTMLParagraphElement, EmptyDescriptionProps>(
+  ({className, ...props}: Readonly<EmptyDescriptionProps>, ref): React.JSX.Element => (
+    <p
+      ref={ref}
       data-slot='empty-description'
-      className={cn(
-        "text-sm/relaxed text-neutral-500 dark:text-neutral-400 [&>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 EmptyContent({className, ...props}: React.ComponentProps<"div">) {
-  return (
+/**
+ * Hosts trailing actions or supplemental content for an empty state.
+ *
+ * @remarks
+ * - Pure CSS component (no Base UI primitive)
+ * - Renders a `<div>` element
+ * - Styling via CSS Modules with `--ac-*` custom properties
+ *
+ * @example
+ * ```tsx
+ * <EmptyContent>
+ *   <button type='button'>Create item</button>
+ * </EmptyContent>
+ * ```
+ *
+ * @see {@link EmptyContentProps} for available props
+ */
+const EmptyContent = React.forwardRef<HTMLDivElement, EmptyContentProps>(
+  ({className, ...props}: Readonly<EmptyContentProps>, ref): React.JSX.Element => (
     <div
+      ref={ref}
       data-slot='empty-content'
-      className={cn("flex w-full max-w-sm min-w-0 flex-col items-center gap-4 text-sm text-balance", className)}
+      className={cn(styles.content, className)}
       {...props}
     />
-  );
-}
+  ),
+);
+
+Empty.displayName = "Empty";
+EmptyHeader.displayName = "EmptyHeader";
+EmptyMedia.displayName = "EmptyMedia";
+EmptyTitle.displayName = "EmptyTitle";
+EmptyDescription.displayName = "EmptyDescription";
+EmptyContent.displayName = "EmptyContent";
 
 export {Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle};

package/src/components/ui/error-boundary.module.css

@@ -0,0 +1,36 @@
+.fallback {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ac-space-3);
+  padding: var(--ac-space-8);
+  text-align: center;
+}
+
+.title {
+  color: var(--ac-destructive);
+  font-size: var(--ac-text-lg);
+  font-weight: 600;
+}
+
+.message {
+  max-width: 32rem;
+  color: var(--ac-muted-foreground);
+  font-size: var(--ac-text-sm);
+}
+
+.retry {
+  cursor: pointer;
+  border: 1px solid var(--ac-border);
+  border-radius: var(--ac-radius-md);
+  background-color: var(--ac-background);
+  padding: var(--ac-space-2) var(--ac-space-4);
+  color: var(--ac-foreground);
+  font-size: var(--ac-text-sm);
+  transition: background-color var(--ac-transition-fast);
+}
+
+.retry:hover {
+  background-color: var(--ac-accent);
+}

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

@@ -0,0 +1,127 @@
+"use client";
+
+import * as React from "react";
+
+import styles from "./error-boundary.module.css";
+
+/**
+ * Represents the configurable props for the {@link ErrorBoundary} component.
+ *
+ * @remarks
+ * Accepts child content plus an optional fallback renderer and error callback for
+ * recovery-oriented error handling in React client trees.
+ */
+interface ErrorBoundaryProps {
+  /**
+   * Content rendered when no error has been captured.
+   */
+  children: React.ReactNode;
+  /**
+   * Custom fallback UI or render function invoked with the current error and reset action.
+   */
+  fallback?: React.ReactNode | ((error: Error, reset: () => void) => React.ReactNode);
+  /**
+   * Callback invoked after an error has been captured.
+   */
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+
+/**
+ * Represents the tracked state for the {@link ErrorBoundary} component.
+ *
+ * @remarks
+ * Stores the most recent rendering error so the boundary can swap to fallback UI and
+ * later clear that error when `reset()` is invoked.
+ */
+interface ErrorBoundaryState {
+  /**
+   * The latest captured error, or `null` when the subtree is healthy.
+   */
+  error: Error | null;
+}
+
+/**
+ * Catches JavaScript errors in descendant client components and renders fallback UI.
+ *
+ * @remarks
+ * **Rendering Context**: Client component.
+ *
+ * React currently requires class components for error boundaries. This implementation
+ * captures render-time and lifecycle errors, not asynchronous event handler exceptions,
+ * and exposes a `reset()` pathway so callers can retry the failed subtree.
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <div>
+ *       <p>Error: {error.message}</p>
+ *       <button onClick={reset}>Try again</button>
+ *     </div>
+ *   )}>
+ *   <DashboardPanel />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @see {@link ErrorBoundaryProps} for available props
+ */
+class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return {error};
+  }
+
+  static readonly displayName = "ErrorBoundary";
+
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = {error: null};
+  }
+
+  override shouldComponentUpdate(nextProps: Readonly<ErrorBoundaryProps>, nextState: Readonly<ErrorBoundaryState>): boolean {
+    const {children, fallback, onError} = this.props;
+    const {error} = this.state;
+
+    return nextProps.children !== children || nextProps.fallback !== fallback || nextProps.onError !== onError || nextState.error !== error;
+  }
+
+  override componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    const {onError} = this.props;
+
+    onError?.(error, errorInfo);
+  }
+
+  handleReset = (): void => {
+    // eslint-disable-next-line react/no-set-state -- Error boundaries must clear internal error state to retry rendering.
+    this.setState({error: null});
+  };
+
+  // eslint-disable-next-line sonarjs/function-return-type -- Error boundary render paths intentionally return generic ReactNode content.
+  override render(): React.ReactNode {
+    const {error} = this.state;
+    const {children, fallback} = this.props;
+    const content: React.ReactNode =
+      error === null
+        ? children
+        : typeof fallback === "function"
+          ? fallback(error, this.handleReset)
+          : (fallback ?? (
+              <div
+                className={styles.fallback}
+                role='alert'>
+                <p className={styles.title}>Something went wrong</p>
+                <p className={styles.message}>{error.message}</p>
+                <button
+                  type='button'
+                  className={styles.retry}
+                  onClick={this.handleReset}>
+                  Try again
+                </button>
+              </div>
+            ));
+
+    return content;
+  }
+}
+
+export {ErrorBoundary};
+export type {ErrorBoundaryProps};

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

@@ -0,0 +1,179 @@
+.fieldSet {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ac-space-6);
+}
+
+.legend {
+  margin-bottom: var(--ac-space-3);
+  color: var(--ac-foreground);
+  font-weight: 600;
+}
+
+.legendDefault {
+  font-size: var(--ac-text-base);
+}
+
+.legendLabel {
+  font-size: var(--ac-text-sm);
+}
+
+.group {
+  display: flex;
+  width: 100%;
+  flex-direction: column;
+  gap: calc(var(--ac-space-6) + var(--ac-space-1));
+}
+
+.group > .group {
+  gap: var(--ac-space-4);
+}
+
+.field {
+  display: flex;
+  width: 100%;
+  gap: var(--ac-space-3);
+}
+
+.field[data-invalid="true"] {
+  color: var(--ac-destructive);
+}
+
+.vertical {
+  flex-direction: column;
+}
+
+.vertical > * {
+  width: 100%;
+}
+
+.horizontal {
+  flex-direction: row;
+  align-items: center;
+}
+
+.horizontal > [data-slot="field-label"] {
+  flex: 0 0 auto;
+}
+
+.responsive {
+  flex-direction: column;
+}
+
+.responsive > * {
+  width: 100%;
+}
+
+@media (min-width: 768px) {
+  .responsive {
+    flex-direction: row;
+    align-items: center;
+  }
+
+  .responsive > * {
+    width: auto;
+  }
+
+  .responsive > [data-slot="field-label"] {
+    flex: 0 0 auto;
+    min-width: 10rem;
+  }
+}
+
+.content {
+  display: flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: var(--ac-space-2);
+  line-height: 1.4;
+}
+
+.label {
+  display: flex;
+  width: fit-content;
+  gap: var(--ac-space-2);
+  color: var(--ac-foreground);
+  font-size: var(--ac-text-sm);
+  font-weight: 500;
+  line-height: 1.4;
+  cursor: default;
+  user-select: none;
+}
+
+.field[data-disabled="true"] .label {
+  opacity: 0.5;
+}
+
+.label:has([data-slot="field"]) {
+  width: 100%;
+  flex-direction: column;
+  padding: var(--ac-space-4);
+  border: 1px solid var(--ac-border);
+  border-radius: var(--ac-radius-md);
+}
+
+.title {
+  display: flex;
+  width: fit-content;
+  align-items: center;
+  gap: var(--ac-space-2);
+  color: var(--ac-foreground);
+  font-size: var(--ac-text-sm);
+  line-height: 1.4;
+  font-weight: 500;
+}
+
+.description {
+  color: var(--ac-muted-foreground);
+  font-size: var(--ac-text-sm);
+  line-height: 1.5;
+}
+
+.description a {
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 4px;
+}
+
+@media (hover: hover) {
+  .description a:hover {
+    color: var(--ac-foreground);
+  }
+}
+
+.separator {
+  position: relative;
+  min-height: 1.25rem;
+  margin: calc(var(--ac-space-2) * -1) 0;
+  font-size: var(--ac-text-sm);
+}
+
+.separatorLine {
+  position: absolute;
+  inset: 50% 0 auto;
+  transform: translateY(-50%);
+}
+
+.separatorContent {
+  position: relative;
+  display: block;
+  width: fit-content;
+  margin: 0 auto;
+  padding: 0 var(--ac-space-2);
+  background-color: var(--ac-background);
+  color: var(--ac-muted-foreground);
+}
+
+.error {
+  color: var(--ac-destructive);
+  font-size: var(--ac-text-sm);
+}
+
+.errorList {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ac-space-1);
+  padding-left: var(--ac-space-4);
+  margin: 0;
+}