@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/empty-state.tsx

@@ -1,305 +0,0 @@
-import * as React from "react";
-import { cn } from "@/lib/utils";
-import { Button } from "./button";
-
-/**
- * Props for EmptyState (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace HTML inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type EmptyStateDocsProps = {
-  /**
-   * Main title text displayed prominently in the empty state
-   *
-   * Rendered as an h3 element for proper heading hierarchy and screen reader navigation.
-   * Keep titles concise and descriptive, focusing on what's missing or the current state.
-   *
-   * @example "No results found", "Your inbox is empty", "No data available"
-   */
-  title: string;
-
-  /**
-   * Optional descriptive text providing additional context or guidance
-   *
-   * Displayed below the title as body text with muted styling. Use to explain why
-   * the empty state occurred or provide helpful next steps for the user. Maximum
-   * width is constrained to maintain readability (max-w-sm).
-   *
-   * @example "Try adjusting your search criteria", "New messages will appear here"
-   * @default undefined
-   */
-  description?: string;
-
-  /**
-   * Optional icon, illustration, or React element displayed above the title
-   *
-   * Should be a meaningful visual representation of the empty state. Recommended
-   * size is 48-64px (w-12 h-12 to w-16 h-16) for optimal visual balance. Icons
-   * are automatically styled with muted foreground color.
-   *
-   * @example <Inbox className="w-12 h-12" />, <Search className="w-16 h-16" />
-   * @default undefined
-   */
-  icon?: React.ReactNode;
-
-  /**
-   * Optional action button configuration for primary user action
-   *
-   * When provided, renders a Button component with default styling below the
-   * description. The button follows all Button component accessibility patterns
-   * and supports keyboard navigation. Use clear, action-oriented labels that
-   * indicate what will happen when clicked.
-   *
-   * @default undefined
-   */
-  action?: {
-    /**
-     * Text label for the action button
-     *
-     * Should be specific and action-oriented rather than generic.
-     * @example "Create your first post", "Import data", "Try again"
-     */
-    label: string;
-
-    /**
-     * Click handler function executed when the action button is pressed
-     *
-     * Called when the user activates the button via click or keyboard interaction.
-     * Should handle the primary action to resolve the empty state.
-     */
-    onClick: () => void;
-  };
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to display inside the container (not used - component has fixed structure) */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLDivElement>;
-
-/**
- * EmptyState - Displays empty or no-data states with consistent UX patterns
- *
- * A comprehensive component for handling empty states across applications. Provides
- * a standardized way to communicate when content is unavailable, data is missing,
- * or initial setup is required. Built with accessibility-first principles and
- * follows established empty state design patterns to guide users toward resolution.
- *
- * **Common Use Cases:**
- * - Search results with no matches
- * - Empty lists, tables, or dashboards
- * - Inbox or notification centers with no items
- * - Data visualization with no data
- * - Onboarding states for new users
- * - Error recovery scenarios
- *
- * **Component Structure:**
- * The component follows a top-down visual hierarchy: Icon → Title → Description → Action.
- * All elements except the title are optional, allowing for flexible implementation
- * across different contexts while maintaining visual consistency.
- *
- * @example
- * ```tsx
- * // Minimal empty state with just title
- * <EmptyState title="No notifications" />
- * ```
- *
- * @example
- * ```tsx
- * // Search results empty state
- * import { Search } from 'lucide-react';
- *
- * <EmptyState
- *   icon={<Search className="w-12 h-12" />}
- *   title="No results found"
- *   description="Try adjusting your search terms or filters"
- *   action={{
- *     label: "Clear filters",
- *     onClick: () => resetFilters()
- *   }}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Inbox empty state with call-to-action
- * import { Inbox, Plus } from 'lucide-react';
- *
- * <EmptyState
- *   icon={<Inbox className="w-16 h-16" />}
- *   title="Your inbox is empty"
- *   description="New messages and notifications will appear here"
- *   action={{
- *     label: "Compose message",
- *     onClick: () => openComposer()
- *   }}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Data dashboard empty state with custom styling
- * import { BarChart3, TrendingUp } from 'lucide-react';
- *
- * <EmptyState
- *   className="min-h-[400px] bg-gradient-to-br from-muted/20 to-muted/10 rounded-lg border border-dashed border-muted-foreground/20"
- *   icon={<BarChart3 className="w-14 h-14 opacity-60" />}
- *   title="No analytics data"
- *   description="Connect your data source or import historical data to view insights"
- *   action={{
- *     label: "Connect data source",
- *     onClick: () => showDataSourceModal()
- *   }}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // File manager empty state
- * import { FolderOpen, Upload } from 'lucide-react';
- *
- * <EmptyState
- *   icon={<FolderOpen className="w-12 h-12" />}
- *   title="This folder is empty"
- *   description="Drag and drop files here or use the upload button"
- *   action={{
- *     label: "Upload files",
- *     onClick: () => triggerFileUpload()
- *   }}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Error recovery empty state
- * import { AlertTriangle, RefreshCw } from 'lucide-react';
- *
- * <EmptyState
- *   icon={<AlertTriangle className="w-12 h-12 text-destructive" />}
- *   title="Failed to load data"
- *   description="There was a problem loading your content. Please try again."
- *   action={{
- *     label: "Retry",
- *     onClick: () => refetchData()
- *   }}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Team members empty state with multiple actions
- * import { Users, UserPlus, Mail } from 'lucide-react';
- *
- * function TeamEmptyState() {
- *   return (
- *     <div className="space-y-4">
- *       <EmptyState
- *         icon={<Users className="w-16 h-16" />}
- *         title="No team members yet"
- *         description="Invite colleagues to collaborate on projects"
- *         action={{
- *           label: "Invite members",
- *           onClick: () => openInviteModal()
- *         }}
- *       />
- *       <div className="flex justify-center gap-2">
- *         <Button variant="outline" size="sm" onClick={() => importFromCsv()}>
- *           <Mail className="w-4 h-4 mr-2" />
- *           Import from CSV
- *         </Button>
- *       </div>
- *     </div>
- *   );
- * }
- * ```
- *
- * @param props - Component props extending HTMLDivElement attributes
- * @param props.title - Main heading text that describes the empty state
- * @param props.description - Optional explanatory text or guidance for users
- * @param props.icon - Optional visual element (icon, illustration, or custom React element)
- * @param props.action - Optional primary action button configuration
- * @param props.className - Additional CSS classes for custom styling
- * @param props.children - Not used; component has fixed content structure
- * @param ref - Forwarded ref to the root div element for DOM access
- *
- * @accessibility
- * - **Semantic Structure**: Uses proper heading hierarchy with h3 for screen readers
- * - **Keyboard Navigation**: Action button fully keyboard accessible with Tab/Enter/Space
- * - **Screen Readers**: Title and description are properly associated and announced
- * - **Focus Management**: Action button receives proper focus indicators (3px ring)
- * - **Landmark Navigation**: No explicit landmark roles; inherits from container context
- * - **Content Flow**: Logical reading order from icon → title → description → action
- * - **Icon Accessibility**: Decorative icons don't interfere with screen readers
- * - **Button Integration**: Inherits full Button component accessibility features
- * - **High Contrast**: Text colors meet WCAG 2.1 AA contrast requirements
- * - **Responsive Design**: Adapts to different viewport sizes maintaining readability
- *
- * @remarks
- * **Visual Design:**
- * - Default padding of py-12 px-4 provides generous whitespace
- * - Centered alignment (flex-col items-center justify-center text-center)
- * - Icon rendered with muted foreground color for subtle prominence
- * - Title uses text-lg font-semibold with foreground color for prominence
- * - Description limited to max-w-sm (24rem) for optimal readability
- * - Action button positioned with mb-6 spacing from description
- * - Responsive spacing adapts to content presence (conditional margins)
- *
- * **Performance Considerations:**
- * - Lightweight component with minimal re-renders
- * - Icon rendering optimized for various React element types
- * - Button component lazy-loaded only when action is provided
- * - No state management or effects, purely presentational
- * - Supports React 18 concurrent features
- *
- * **Customization:**
- * - All Tailwind utility classes can be overridden via className
- * - Icon styling can be customized at the element level
- * - Button inherits default variant but supports additional props via composition
- * - Container div accepts all standard HTML attributes for event handling
- * - Supports ref forwarding for programmatic DOM manipulation
- *
- * **Design System Integration:**
- * - Uses design tokens (foreground, muted-foreground, etc.) for consistent theming
- * - Follows spacing scale (mb-2, mb-4, mb-6, py-12, px-4)
- * - Typography scale integration (text-lg for title, default for description)
- * - Color system compatibility with light/dark mode switching
- * - Button component integration maintains design system consistency
- *
- * @see {@link Button} for action button styling, variants, and accessibility
- * @see {@link https://ui.patterns.build/empty-states} Empty state design patterns
- * @see {@link https://www.nngroup.com/articles/empty-state-interface-design/} Nielsen Norman Group empty state guidelines
- * @since 1.0.0
- * @deprecated Use @neynar/ui Empty component instead
- */
-const EmptyState = React.forwardRef<
-  HTMLDivElement,
-  React.ComponentProps<"div"> & {
-    title: string;
-    description?: string;
-    icon?: React.ReactNode;
-    action?: {
-      label: string;
-      onClick: () => void;
-    };
-  }
->(({ className, title, description, icon, action, ...props }, ref) => {
-  return (
-    <div
-      ref={ref}
-      className={cn(
-        "flex flex-col items-center justify-center text-center py-12 px-4",
-        className,
-      )}
-      {...props}
-    >
-      {icon && <div className="mb-4 text-muted-foreground">{icon}</div>}
-      <h3 className="text-lg font-semibold text-foreground mb-2">{title}</h3>
-      {description && (
-        <p className="text-muted-foreground mb-6 max-w-sm">{description}</p>
-      )}
-      {action && <Button onClick={action.onClick}>{action.label}</Button>}
-    </div>
-  );
-});
-
-EmptyState.displayName = "EmptyState";
-
-export { EmptyState };