@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/container.tsx

@@ -1,114 +1,266 @@
 import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
 import { cn } from "@/lib/utils";
 
 /**
- * Props for the Container component
+ * Container variant configuration using class-variance-authority
+ *
+ * Defines responsive layout container with consistent horizontal centering and padding
+ * across different viewport sizes. Uses Tailwind CSS for responsive design patterns
+ * and maintains consistent spacing throughout the application.
  *
- * @public
+ * @variant sm - Optimal reading width (48rem) for articles, blog posts, and long-form content
+ * @variant md - Medium container (64rem) suitable for forms, documentation, and structured layouts
+ * @variant lg - Large container (80rem) ideal for main application content, dashboards, and data tables
+ * @variant xl - Extra-large container with no max-width but maintains responsive padding for specialized layouts
+ * @variant full - Full-width container for edge-to-edge designs, hero sections, and complex grid layouts
+ *
+ * @see {@link https://cva.style/docs} - CVA documentation
+ * @see {@link https://tailwindcss.com/docs/container} - Tailwind CSS container documentation
+ * @since 1.0.0
  */
-export type ContainerProps = React.HTMLAttributes<HTMLDivElement> & {
+const containerVariants = cva("mx-auto w-full px-4 sm:px-6 lg:px-8", {
+  variants: {
+    size: {
+      sm: "max-w-3xl",
+      md: "max-w-5xl",
+      lg: "max-w-7xl",
+      xl: "max-w-none",
+      full: "max-w-full",
+    },
+  },
+  defaultVariants: {
+    size: "lg",
+  },
+});
+
+/**
+ * Props for Container (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CVA inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ContainerDocsProps = {
   /**
-   * The maximum width size of the container
+   * Container size variant that determines the maximum width and responsive behavior
    *
-   * - `sm`: max-w-3xl (48rem) - Optimal for reading content, articles, and blog posts
-   * - `md`: max-w-5xl (64rem) - Suitable for forms, documentation, and medium-width layouts
-   * - `lg`: max-w-7xl (80rem) - Default size, ideal for main application content and dashboards
-   * - `xl`: max-w-none - No max-width constraint but maintains responsive padding
-   * - `full`: max-w-full - Full width container for edge-to-edge designs
+   * Controls the container's max-width while maintaining consistent horizontal padding
+   * across all breakpoints. Each size is optimized for different content types and layouts.
    *
    * @default "lg"
    */
   size?: "sm" | "md" | "lg" | "xl" | "full";
-};
+  /** Content to display inside the container (text, components, or React elements) */
+  children?: React.ReactNode;
+  /** Additional CSS classes to apply to the container for custom styling */
+  className?: string;
+  /** Unique identifier for the container element */
+  id?: string;
+  /** ARIA role to define the semantic purpose of the container */
+  role?: string;
+  /** ARIA label for screen reader accessibility */
+  "aria-label"?: string;
+  /** Associates the container with elements that label it */
+  "aria-labelledby"?: string;
+  /** Associates the container with elements that describe it */
+  "aria-describedby"?: string;
+  /** Indicates if the container holds live content that should be announced to screen readers */
+  "aria-live"?: "off" | "polite" | "assertive";
+  /** Tab index for focus management @default undefined (not focusable) */
+  tabIndex?: number;
+  /** Click handler function called when the container is clicked */
+  onClick?: React.MouseEventHandler<HTMLDivElement>;
+  /** Focus handler called when the container receives focus */
+  onFocus?: React.FocusEventHandler<HTMLDivElement>;
+  /** Blur handler called when the container loses focus */
+  onBlur?: React.FocusEventHandler<HTMLDivElement>;
+  /** Key down handler for keyboard interactions */
+  onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+  /** Mouse enter handler for hover interactions */
+  onMouseEnter?: React.MouseEventHandler<HTMLDivElement>;
+  /** Mouse leave handler for hover interactions */
+  onMouseLeave?: React.MouseEventHandler<HTMLDivElement>;
+} & React.HTMLAttributes<HTMLDivElement>;
 
 /**
- * A responsive content wrapper component that provides consistent max-width constraints and horizontal padding
+ * Container - A responsive layout wrapper with flexible width constraints and consistent padding
+ *
+ * A fundamental layout component built with class-variance-authority (CVA) that provides consistent
+ * horizontal centering, responsive padding, and flexible max-width constraints. Designed to be the
+ * primary content wrapper for pages, sections, and layout regions throughout the application.
  *
- * Container is inspired by layout patterns from shadcn/ui and Tailwind UI, offering a flexible foundation
- * for page layouts. It automatically centers content horizontally and applies responsive padding that
- * adapts gracefully across different screen sizes (px-4 on mobile, px-6 on small screens, px-8 on large screens).
+ * The component automatically applies responsive horizontal padding (px-4 on mobile, px-6 on small
+ * screens, px-8 on large screens) and centers content using mx-auto. Five size variants accommodate
+ * different content types from optimal reading widths to full-width layouts.
  *
- * The component supports five size variants optimized for different content types:
- * - Small containers for optimal reading experiences
- * - Medium containers for forms and documentation
- * - Large containers for application dashboards
- * - Extra-large and full-width for specialized layouts
+ * Built following shadcn/ui and Tailwind UI patterns for maximum compatibility and consistency
+ * with modern React applications and design systems.
  *
- * @example Basic usage with default large size
+ * @example
  * ```tsx
+ * // Basic usage with default large size (80rem max-width)
  * <Container>
- *   <h1>Dashboard Title</h1>
- *   <p>Main application content with optimal width constraints</p>
+ *   <h1>Dashboard Overview</h1>
+ *   <p>Main application content with balanced width constraints</p>
+ *   <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+ *     <Card>Dashboard Widget</Card>
+ *     <Card>Analytics Panel</Card>
+ *     <Card>Recent Activity</Card>
+ *   </div>
  * </Container>
  * ```
  *
- * @example Reading-optimized container for articles
+ * @example
  * ```tsx
+ * // Reading-optimized container for articles and blog posts
  * <Container size="sm">
- *   <article>
- *     <h1>Blog Post Title</h1>
- *     <p>Long-form content with line lengths optimized for readability</p>
+ *   <article className="prose prose-lg max-w-none">
+ *     <h1>The Future of Web Development</h1>
+ *     <p>
+ *       Long-form content with line lengths optimized for readability
+ *       and comfortable reading experience across all device sizes.
+ *     </p>
+ *     <p>
+ *       The small container (48rem) provides the ideal measure for
+ *       typography-focused content and sustained reading.
+ *     </p>
  *   </article>
  * </Container>
  * ```
  *
- * @example Full-width layout for complex interfaces
+ * @example
  * ```tsx
+ * // Medium container for forms and structured layouts
+ * <Container size="md">
+ *   <div className="space-y-8">
+ *     <div className="text-center">
+ *       <h2>Account Settings</h2>
+ *       <p>Manage your account preferences and profile information</p>
+ *     </div>
+ *
+ *     <form className="space-y-6">
+ *       <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+ *         <Input label="First Name" />
+ *         <Input label="Last Name" />
+ *       </div>
+ *       <Input label="Email Address" type="email" />
+ *       <Button type="submit" className="w-full">Update Profile</Button>
+ *     </form>
+ *   </div>
+ * </Container>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full-width container for complex layouts and hero sections
  * <Container size="full">
- *   <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
- *     <DashboardWidget />
- *     <DashboardWidget />
- *     <DashboardWidget />
+ *   <div className="bg-gradient-to-r from-blue-600 to-purple-600 text-white py-20">
+ *     <div className="text-center space-y-6">
+ *       <h1 className="text-4xl md:text-6xl font-bold">
+ *         Welcome to Our Platform
+ *       </h1>
+ *       <p className="text-xl md:text-2xl opacity-90 max-w-3xl mx-auto">
+ *         Edge-to-edge hero section with full viewport width
+ *       </p>
+ *       <Button size="lg" variant="secondary">
+ *         Get Started
+ *       </Button>
+ *     </div>
+ *   </div>
+ * </Container>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Extra-large container for data-heavy interfaces
+ * <Container size="xl" className="py-8">
+ *   <div className="space-y-6">
+ *     <div className="flex justify-between items-center">
+ *       <h1 className="text-3xl font-bold">Analytics Dashboard</h1>
+ *       <Button variant="outline">Export Data</Button>
+ *     </div>
+ *
+ *     // Wide data table that needs maximum available width
+ *     <DataTable
+ *       columns={analyticsColumns}
+ *       data={analyticsData}
+ *       className="min-w-[1200px]"
+ *     />
+ *
+ *     <div className="grid grid-cols-1 lg:grid-cols-4 gap-6">
+ *       <MetricCard />
+ *       <MetricCard />
+ *       <MetricCard />
+ *       <MetricCard />
+ *     </div>
  *   </div>
  * </Container>
  * ```
  *
- * @example Composing with other layout components
+ * @example
  * ```tsx
- * <Container size="lg" className="py-8">
- *   <Stack spacing="lg">
- *     <Heading size="xl">Section Title</Heading>
- *     <Text>Section description</Text>
- *     <Card>Content card</Card>
- *   </Stack>
+ * // Advanced usage with custom styling and ARIA landmarks
+ * <Container
+ *   size="lg"
+ *   className="min-h-screen py-12 bg-gray-50 dark:bg-gray-900"
+ *   role="main"
+ *   aria-label="Application content"
+ * >
+ *   <div className="space-y-10">
+ *     <header className="text-center space-y-4">
+ *       <Badge variant="secondary">New Feature</Badge>
+ *       <h1 className="text-4xl font-bold tracking-tight">
+ *         Product Announcement
+ *       </h1>
+ *       <p className="text-lg text-muted-foreground max-w-2xl mx-auto">
+ *         Discover the latest improvements to our platform
+ *       </p>
+ *     </header>
+ *
+ *     <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
+ *       <FeatureCard />
+ *       <FeatureCard />
+ *       <FeatureCard />
+ *     </div>
+ *   </div>
  * </Container>
  * ```
  *
  * @accessibility
- * - Uses semantic HTML `div` element that works well with screen readers
+ * - Uses semantic HTML `div` element with proper ARIA support
+ * - Supports all ARIA landmark roles (main, section, article, etc.)
  * - Maintains proper focus management and keyboard navigation flow
- * - Responsive design ensures content remains accessible across all device sizes
+ * - Responsive design ensures content accessibility across all device sizes
  * - Text content automatically reflows for optimal readability
- * - Compatible with high contrast themes and browser zoom levels up to 200%
+ * - Compatible with screen readers and assistive technologies
+ * - Supports high contrast themes and respects user preference settings
+ * - Browser zoom support up to 200% with maintained usability
+ * - Responsive padding prevents content from touching screen edges
+ * - Container centering provides consistent visual balance
  *
+ * @variant sm - Small container (48rem max-width) for optimal reading and articles
+ * @variant md - Medium container (64rem max-width) for forms and documentation
+ * @variant lg - Large container (80rem max-width) for main app content and dashboards
+ * @variant xl - Extra-large container (no max-width) for data-heavy interfaces
+ * @variant full - Full-width container for hero sections and edge-to-edge layouts
+ *
+ * @see {@link containerVariants} CVA configuration with all styling variants
  * @see {@link https://ui.shadcn.com/docs/components/sidebar} Sidebar component for app layouts
  * @see {@link https://ui.shadcn.com/blocks} shadcn/ui blocks for complete layout examples
- *
- * @public
+ * @see {@link https://tailwindcss.com/docs/container} Tailwind CSS container patterns
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/} ARIA Landmark Patterns
  * @since 1.0.0
  */
-const Container = React.forwardRef<HTMLDivElement, ContainerProps>(
-  ({ className, size = "lg", ...props }, ref) => {
-    return (
-      <div
-        ref={ref}
-        className={cn(
-          "mx-auto w-full px-4 sm:px-6 lg:px-8",
-          {
-            "max-w-3xl": size === "sm",
-            "max-w-5xl": size === "md",
-            "max-w-7xl": size === "lg",
-            "max-w-none": size === "xl",
-            "max-w-full": size === "full",
-          },
-          className,
-        )}
-        {...props}
-      />
-    );
-  },
-);
+function Container({
+  className,
+  size,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof containerVariants>) {
+  return (
+    <div className={cn(containerVariants({ size, className }))} {...props} />
+  );
+}
 
 Container.displayName = "Container";
 
-export { Container };
+export { Container, containerVariants };