@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/stack.tsx

@@ -2,58 +2,158 @@ import * as React from "react";
 import { cn } from "@/lib/utils";
 
 /**
- * Props for the Stack component
+ * Spacing options for Stack component using Tailwind CSS spacing scale
  *
- * @public
+ * Maps to Tailwind spacing utilities:
+ * - 1 = 0.25rem (4px) - Ultra-tight spacing for dense layouts
+ * - 2 = 0.5rem (8px) - Tight spacing for compact components
+ * - 3 = 0.75rem (12px) - Close spacing for related items
+ * - 4 = 1rem (16px) - Default spacing for general layouts
+ * - 6 = 1.5rem (24px) - Loose spacing for section separation
+ * - 8 = 2rem (32px) - Wide spacing for distinct content areas
+ * - 12 = 3rem (48px) - Extra-wide spacing for major layout divisions
+ */
+type StackSpacing = 1 | 2 | 3 | 4 | 6 | 8 | 12;
+
+/**
+ * Layout direction options for Stack component
+ *
+ * - "vertical" - Flex column layout with space-y-* utilities
+ * - "horizontal" - Flex row layout with space-x-* utilities
  */
-export type StackProps = React.HTMLAttributes<HTMLDivElement> & {
+type StackDirection = "vertical" | "horizontal";
+
+/**
+ * Props for Stack (Documentation only - NOT used in component implementation)
+ *
+ * Extends standard HTML div attributes for flexible layout containers.
+ * Stack provides consistent spacing between child elements in either
+ * vertical or horizontal direction using Tailwind's spacing scale.
+ *
+ * Inherits all standard HTML div props including:
+ * - className: Additional CSS classes for custom styling
+ * - id: Element identifier for targeting and accessibility
+ * - role: ARIA role for semantic meaning
+ * - tabIndex: Tab order control for keyboard navigation
+ * - onClick, onKeyDown, etc.: Standard event handlers
+ * - data-*: Custom data attributes
+ * - aria-*: Accessibility attributes
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type StackDocsProps = React.HTMLAttributes<HTMLDivElement> & {
   /**
    * The spacing between stack items using Tailwind CSS spacing scale
    *
    * Controls the gap between child elements using Tailwind's space utilities.
-   * Each value corresponds to a Tailwind spacing unit (1 = 0.25rem, 4 = 1rem, etc.)
+   * Each value corresponds to a Tailwind spacing unit mapped to consistent
+   * rem values for predictable visual hierarchy.
+   *
+   * **Spacing Guidelines:**
+   * - Use `1-2` for tightly related items (button groups, form fields)
+   * - Use `3-4` for standard component spacing (default recommended)
+   * - Use `6-8` for section separation and content areas
+   * - Use `12` for major layout divisions and page sections
+   *
+   * **Technical Details:**
+   * - Uses `space-y-*` utilities for vertical stacks
+   * - Uses `space-x-*` utilities for horizontal stacks
+   * - Applies margin to all children except the first
+   * - Compatible with Tailwind's JIT compilation
    *
    * @defaultValue 4
    * @example
    * ```tsx
-   * // Tight spacing for compact layouts
+   * // Ultra-tight spacing for button groups
+   * <Stack spacing={1} direction="horizontal">
+   *   <Button size="sm">Edit</Button>
+   *   <Button size="sm" variant="outline">Delete</Button>
+   * </Stack>
+   *
+   * // Tight spacing for form fields
    * <Stack spacing={2}>
-   *   <Button>Save</Button>
-   *   <Button>Cancel</Button>
+   *   <Label htmlFor="email">Email</Label>
+   *   <Input id="email" type="email" />
+   *   <Input type="password" placeholder="Password" />
    * </Stack>
    *
-   * // Generous spacing for section separation
+   * // Standard spacing for content sections (default)
+   * <Stack spacing={4}>
+   *   <Card>User Profile</Card>
+   *   <Card>Account Settings</Card>
+   *   <Card>Privacy Controls</Card>
+   * </Stack>
+   *
+   * // Generous spacing for major page sections
    * <Stack spacing={8}>
-   *   <section>First section</section>
-   *   <section>Second section</section>
+   *   <header>Page Header</header>
+   *   <main>Main Content</main>
+   *   <footer>Page Footer</footer>
    * </Stack>
    * ```
    */
-  spacing?: 1 | 2 | 3 | 4 | 6 | 8 | 12;
+  spacing?: StackSpacing;
 
   /**
    * The layout direction of the stack
    *
-   * - `"vertical"` - Arranges children in a column with vertical spacing
-   * - `"horizontal"` - Arranges children in a row with horizontal spacing
+   * **Vertical Direction (default):**
+   * - Uses `flex flex-col` for column layout
+   * - Applies `space-y-*` utilities for vertical spacing
+   * - Ideal for forms, content sections, navigation lists
+   * - Maintains natural document flow for screen readers
+   *
+   * **Horizontal Direction:**
+   * - Uses `flex flex-row` for row layout
+   * - Applies `space-x-*` utilities for horizontal spacing
+   * - Perfect for button groups, navigation bars, toolbars
+   * - Consider using `flex-wrap` class for responsive layouts
+   *
+   * **Responsive Considerations:**
+   * - Can be combined with responsive classes for adaptive layouts
+   * - Consider switching from horizontal to vertical on smaller screens
+   * - Use additional Tailwind classes for overflow handling
    *
    * @defaultValue "vertical"
    * @example
    * ```tsx
-   * // Vertical stack (default)
+   * // Vertical stack for content hierarchy (default)
    * <Stack>
-   *   <Card>Item 1</Card>
-   *   <Card>Item 2</Card>
+   *   <h2>Section Title</h2>
+   *   <p>Section description text</p>
+   *   <Card>Card content</Card>
+   *   <Card>Another card</Card>
    * </Stack>
    *
    * // Horizontal stack for action buttons
-   * <Stack direction="horizontal">
-   *   <Button>Primary</Button>
+   * <Stack direction="horizontal" spacing={3}>
+   *   <Button>Primary Action</Button>
    *   <Button variant="outline">Secondary</Button>
+   *   <Button variant="ghost">Tertiary</Button>
+   * </Stack>
+   *
+   * // Responsive horizontal to vertical stack
+   * <Stack
+   *   direction="horizontal"
+   *   spacing={2}
+   *   className="flex-col sm:flex-row"
+   * >
+   *   <Button className="w-full sm:w-auto">Mobile Full Width</Button>
+   *   <Button variant="outline" className="w-full sm:w-auto">Desktop Inline</Button>
+   * </Stack>
+   *
+   * // Horizontal navigation with overflow scroll
+   * <Stack
+   *   direction="horizontal"
+   *   spacing={1}
+   *   className="overflow-x-auto pb-2"
+   * >
+   *   <Badge variant="secondary">Tag 1</Badge>
+   *   <Badge variant="secondary">Tag 2</Badge>
+   *   <Badge variant="secondary">Long Tag Name</Badge>
    * </Stack>
    * ```
    */
-  direction?: "vertical" | "horizontal";
+  direction?: StackDirection;
 };
 
 /**
@@ -61,119 +161,341 @@ export type StackProps = React.HTMLAttributes<HTMLDivElement> & {
  *
  * Stack is a fundamental layout primitive that arranges child elements in either
  * vertical or horizontal direction with consistent spacing. Built on flexbox principles,
- * it provides a clean API for common layout patterns without requiring custom CSS.
+ * it provides a clean, declarative API for common layout patterns without requiring
+ * custom CSS or complex flex configurations.
  *
- * This component is particularly useful for:
+ * **Core Features:**
+ * - Consistent spacing using Tailwind's design system
+ * - Flexible direction control (vertical/horizontal)
+ * - Zero-config flexbox layouts with predictable behavior
+ * - Composable with other UI components and layout utilities
+ * - Full accessibility support with semantic HTML structure
+ * - TypeScript-first with comprehensive prop validation
+ *
+ * **Common Use Cases:**
  * - Form layouts with consistent field spacing
  * - Button groups and action bars
  * - Content sections with uniform gaps
- * - Navigation lists and menus
- * - Card layouts and content grids
+ * - Navigation lists and menu structures
+ * - Card layouts and dashboard grids
+ * - Page sections and content hierarchy
+ * - Responsive component layouts
+ *
+ * **Design System Integration:**
+ * Stack integrates seamlessly with design systems by providing consistent
+ * spacing that aligns with Tailwind's spacing scale. This ensures visual
+ * harmony across your application and reduces the need for custom spacing
+ * utilities in most common layout scenarios.
  *
- * @example Basic vertical layout (default)
+ * @example Basic vertical content layout (default behavior)
  * ```tsx
  * <Stack>
- *   <Card>Profile Information</Card>
- *   <Card>Account Settings</Card>
- *   <Card>Privacy Controls</Card>
+ *   <h1>Dashboard</h1>
+ *   <Card>
+ *     <CardHeader>Profile Information</CardHeader>
+ *     <CardContent>User profile details</CardContent>
+ *   </Card>
+ *   <Card>
+ *     <CardHeader>Account Settings</CardHeader>
+ *     <CardContent>Account configuration options</CardContent>
+ *   </Card>
+ *   <Card>
+ *     <CardHeader>Privacy Controls</CardHeader>
+ *     <CardContent>Privacy and security settings</CardContent>
+ *   </Card>
  * </Stack>
  * ```
  *
- * @example Horizontal action bar
+ * @example Horizontal action button bar
  * ```tsx
- * <Stack direction="horizontal" spacing={3}>
- *   <Button>Save Changes</Button>
- *   <Button variant="outline">Cancel</Button>
- *   <Button variant="ghost">Reset</Button>
+ * <Stack direction="horizontal" spacing={3} className="justify-end">
+ *   <Button variant="ghost">Cancel</Button>
+ *   <Button variant="outline">Save Draft</Button>
+ *   <Button>Publish</Button>
  * </Stack>
  * ```
  *
- * @example Form sections with custom spacing
+ * @example Complex form layout with nested stacks
  * ```tsx
- * <Stack spacing={6}>
- *   <fieldset>
- *     <legend>Personal Information</legend>
- *     <Stack spacing={3}>
- *       <Input placeholder="Full Name" />
- *       <Input placeholder="Email Address" />
- *     </Stack>
- *   </fieldset>
- *   <fieldset>
- *     <legend>Preferences</legend>
- *     <Stack spacing={2}>
- *       <Checkbox>Email notifications</Checkbox>
- *       <Checkbox>Marketing updates</Checkbox>
+ * <form>
+ *   <Stack spacing={6}>
+ *     // Personal Information Section
+ *     <fieldset>
+ *       <legend className="text-lg font-semibold mb-4">Personal Information</legend>
+ *       <Stack spacing={3}>
+ *         <Stack spacing={1}>
+ *           <Label htmlFor="fullName">Full Name</Label>
+ *           <Input id="fullName" placeholder="Enter your full name" />
+ *         </Stack>
+ *         <Stack spacing={1}>
+ *           <Label htmlFor="email">Email Address</Label>
+ *           <Input id="email" type="email" placeholder="you@example.com" />
+ *         </Stack>
+ *       </Stack>
+ *     </fieldset>
+ *
+ *     // Preferences Section
+ *     <fieldset>
+ *       <legend className="text-lg font-semibold mb-4">Preferences</legend>
+ *       <Stack spacing={2}>
+ *         <div className="flex items-center space-x-2">
+ *           <Checkbox id="emailNotifications" />
+ *           <Label htmlFor="emailNotifications">Email notifications</Label>
+ *         </div>
+ *         <div className="flex items-center space-x-2">
+ *           <Checkbox id="marketingUpdates" />
+ *           <Label htmlFor="marketingUpdates">Marketing updates</Label>
+ *         </div>
+ *       </Stack>
+ *     </fieldset>
+ *
+ *     // Form Actions
+ *     <Stack direction="horizontal" spacing={2} className="justify-end">
+ *       <Button type="button" variant="outline">Reset</Button>
+ *       <Button type="submit">Save Changes</Button>
  *     </Stack>
- *   </fieldset>
- * </Stack>
+ *   </Stack>
+ * </form>
  * ```
  *
- * @example Responsive layout with additional styling
+ * @example Responsive navigation with adaptive direction
  * ```tsx
  * <Stack
- *   spacing={4}
- *   className="w-full max-w-md mx-auto p-6"
+ *   direction="horizontal"
+ *   spacing={1}
+ *   className="flex-col sm:flex-row overflow-x-auto sm:overflow-visible"
  * >
- *   <h2>User Dashboard</h2>
- *   <Stack direction="horizontal" spacing={2} className="justify-between">
- *     <Badge>Online</Badge>
- *     <Button size="sm">Edit Profile</Button>
- *   </Stack>
+ *   <Button variant="ghost" className="w-full sm:w-auto">Dashboard</Button>
+ *   <Button variant="ghost" className="w-full sm:w-auto">Analytics</Button>
+ *   <Button variant="ghost" className="w-full sm:w-auto">Settings</Button>
+ *   <Button variant="ghost" className="w-full sm:w-auto">Help</Button>
  * </Stack>
  * ```
  *
+ * @example Dashboard layout with mixed content types
+ * ```tsx
+ * <div className="container mx-auto p-6">
+ *   <Stack spacing={8}>
+ *     // Page Header
+ *     <Stack spacing={2}>
+ *       <h1 className="text-3xl font-bold">Analytics Dashboard</h1>
+ *       <p className="text-muted-foreground">Overview of your application metrics</p>
+ *     </Stack>
+ *
+ *     // Stats Cards
+ *     <Stack direction="horizontal" spacing={4} className="grid grid-cols-1 md:grid-cols-3 gap-4">
+ *       <Card>
+ *         <CardHeader>
+ *           <CardTitle>Total Users</CardTitle>
+ *         </CardHeader>
+ *         <CardContent>
+ *           <div className="text-2xl font-bold">2,543</div>
+ *         </CardContent>
+ *       </Card>
+ *       <Card>
+ *         <CardHeader>
+ *           <CardTitle>Revenue</CardTitle>
+ *         </CardHeader>
+ *         <CardContent>
+ *           <div className="text-2xl font-bold">$12,543</div>
+ *         </CardContent>
+ *       </Card>
+ *       <Card>
+ *         <CardHeader>
+ *           <CardTitle>Growth</CardTitle>
+ *         </CardHeader>
+ *         <CardContent>
+ *           <div className="text-2xl font-bold text-green-600">+12.5%</div>
+ *         </CardContent>
+ *       </Card>
+ *     </Stack>
+ *
+ *     // Content Sections
+ *     <Stack spacing={6}>
+ *       <Card>
+ *         <CardHeader>
+ *           <CardTitle>Recent Activity</CardTitle>
+ *         </CardHeader>
+ *         <CardContent>Activity timeline content</CardContent>
+ *       </Card>
+ *       <Card>
+ *         <CardHeader>
+ *           <CardTitle>Performance Metrics</CardTitle>
+ *         </CardHeader>
+ *         <CardContent>Charts and graphs</CardContent>
+ *       </Card>
+ *     </Stack>
+ *   </Stack>
+ * </div>
+ * ```
+ *
+ * @example Advanced usage with custom styling and semantic elements
+ * ```tsx
+ * <article className="prose max-w-none">
+ *   <Stack spacing={6}>
+ *     <header>
+ *       <Stack spacing={2}>
+ *         <h1>The Future of Web Development</h1>
+ *         <Stack direction="horizontal" spacing={4} className="text-sm text-muted-foreground">
+ *           <time dateTime="2024-01-15">January 15, 2024</time>
+ *           <address className="not-italic">By Jane Developer</address>
+ *           <span>5 min read</span>
+ *         </Stack>
+ *       </Stack>
+ *     </header>
+ *
+ *     <main>
+ *       <Stack spacing={4}>
+ *         <p>Introduction paragraph with key concepts...</p>
+ *         <section>
+ *           <h2>Key Technologies</h2>
+ *           <Stack spacing={3}>
+ *             <p>Discussion of modern web technologies...</p>
+ *             <ul>
+ *               <li>React and component architecture</li>
+ *               <li>Server-side rendering with Next.js</li>
+ *               <li>Type-safe development with TypeScript</li>
+ *             </ul>
+ *           </Stack>
+ *         </section>
+ *         <section>
+ *           <h2>Best Practices</h2>
+ *           <p>Guidelines for effective development...</p>
+ *         </section>
+ *       </Stack>
+ *     </main>
+ *
+ *     <footer>
+ *       <Stack direction="horizontal" spacing={2} className="justify-between items-center">
+ *         <Stack direction="horizontal" spacing={1}>
+ *           <Badge variant="secondary">React</Badge>
+ *           <Badge variant="secondary">TypeScript</Badge>
+ *           <Badge variant="secondary">Next.js</Badge>
+ *         </Stack>
+ *         <Stack direction="horizontal" spacing={2}>
+ *           <Button variant="outline" size="sm">Share</Button>
+ *           <Button variant="outline" size="sm">Save</Button>
+ *         </Stack>
+ *       </Stack>
+ *     </footer>
+ *   </Stack>
+ * </article>
+ * ```
+ *
  * @remarks
  * **Design Philosophy:**
- * - Follows the principle of consistent spacing throughout the UI
- * - Uses Tailwind's spacing scale for predictable sizing
- * - Composable with other layout components
- * - Maintains semantic HTML structure
- *
- * **Performance:**
- * - Lightweight wrapper around flexbox CSS
- * - No JavaScript overhead for layout calculations
- * - Leverages Tailwind's JIT compilation for minimal CSS
- *
- * **Accessibility:**
- * - Preserves natural document flow and reading order
- * - Compatible with screen readers and keyboard navigation
- * - Supports semantic HTML elements as children
- * - Does not interfere with focus management
+ * Stack follows the principle of consistent spacing throughout the UI, using Tailwind's
+ * carefully crafted spacing scale to create visual hierarchy and rhythm. The component
+ * prioritizes composability, allowing complex layouts to be built from simple, predictable
+ * building blocks while maintaining semantic HTML structure.
+ *
+ * **Technical Implementation:**
+ * - Uses CSS Flexbox for reliable cross-browser layout behavior
+ * - Leverages Tailwind's space-* utilities for optimal performance
+ * - Applies margins only to children (not first child) for clean edge handling
+ * - Compatible with Tailwind's JIT compilation for minimal bundle size
+ * - Supports all standard HTML div attributes for maximum flexibility
+ *
+ * **Performance Considerations:**
+ * - Zero JavaScript runtime overhead - pure CSS-based layout
+ * - Optimized for Tailwind's purging and JIT compilation
+ * - Efficient rendering with no layout calculation overhead
+ * - Scales well with large numbers of child elements
+ * - Memory-efficient with minimal DOM structure impact
+ *
+ * **Responsive Design Integration:**
+ * Stack works seamlessly with Tailwind's responsive utilities. You can easily
+ * create adaptive layouts that change direction, spacing, or additional styling
+ * based on screen size breakpoints.
+ *
+ * **Common Patterns:**
+ * - **Form Layouts**: Use nested stacks for sections, fields, and actions
+ * - **Content Hierarchies**: Vary spacing to create visual importance levels
+ * - **Component Composition**: Combine with Cards, Buttons, and other components
+ * - **Responsive Grids**: Use with CSS Grid classes for complex layouts
+ * - **Navigation Patterns**: Create horizontal and vertical navigation structures
+ *
+ * @accessibility
+ * **Keyboard Navigation:**
+ * - Preserves natural document flow and tab order
+ * - Does not interfere with focus management of child components
+ * - Maintains logical reading order for screen readers
+ * - Supports all standard keyboard navigation patterns
+ *
+ * **Screen Reader Support:**
+ * - Uses semantic HTML div element with no interference
+ * - Preserves natural content structure and hierarchy
+ * - Compatible with all ARIA attributes on child elements
+ * - Supports landmark roles when used with semantic HTML
+ * - Maintains proper heading structure and content relationships
+ *
+ * **ARIA Compatibility:**
+ * - Accepts all ARIA attributes for enhanced accessibility
+ * - Does not modify or interfere with child component ARIA properties
+ * - Supports role attributes for semantic meaning
+ * - Compatible with aria-label, aria-describedby, and other ARIA properties
+ *
+ * **Focus Management:**
+ * - Transparent to focus behavior - delegates to child components
+ * - Supports tabIndex for custom focus control when needed
+ * - Does not trap or redirect focus automatically
+ * - Maintains predictable focus flow in both directions
+ *
+ * @performance
+ * **Bundle Impact:**
+ * - Minimal JavaScript bundle size (primarily TypeScript types)
+ * - CSS-only layout solution with no runtime calculations
+ * - Leverages Tailwind's tree-shaking for optimal CSS output
+ * - No external dependencies beyond React and utility functions
+ *
+ * **Runtime Performance:**
+ * - Zero-cost abstraction over native flexbox
+ * - No re-renders triggered by prop changes (style-based)
+ * - Efficient DOM structure with single wrapper element
+ * - Compatible with React's concurrent features and optimizations
  *
  * @public
  * @since 1.0.0
+ * @see {@link Button} For action elements commonly used in horizontal stacks
+ * @see {@link Card} For content containers commonly arranged in stacks
  * @see {@link https://tailwindcss.com/docs/space} Tailwind CSS spacing utilities
+ * @see {@link https://tailwindcss.com/docs/flexbox-direction} Tailwind CSS flex direction
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout} MDN CSS Flexbox Guide
  */
-const Stack = React.forwardRef<HTMLDivElement, StackProps>(
-  ({ className, spacing = 4, direction = "vertical", ...props }, ref) => {
-    return (
-      <div
-        ref={ref}
-        className={cn(
-          direction === "vertical" ? "flex flex-col" : "flex flex-row",
-          {
-            "space-y-1": direction === "vertical" && spacing === 1,
-            "space-y-2": direction === "vertical" && spacing === 2,
-            "space-y-3": direction === "vertical" && spacing === 3,
-            "space-y-4": direction === "vertical" && spacing === 4,
-            "space-y-6": direction === "vertical" && spacing === 6,
-            "space-y-8": direction === "vertical" && spacing === 8,
-            "space-y-12": direction === "vertical" && spacing === 12,
-            "space-x-1": direction === "horizontal" && spacing === 1,
-            "space-x-2": direction === "horizontal" && spacing === 2,
-            "space-x-3": direction === "horizontal" && spacing === 3,
-            "space-x-4": direction === "horizontal" && spacing === 4,
-            "space-x-6": direction === "horizontal" && spacing === 6,
-            "space-x-8": direction === "horizontal" && spacing === 8,
-            "space-x-12": direction === "horizontal" && spacing === 12,
-          },
-          className,
-        )}
-        {...props}
-      />
-    );
-  },
-);
+const Stack = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & {
+    spacing?: StackSpacing;
+    direction?: StackDirection;
+  }
+>(({ className, spacing = 4, direction = "vertical", ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        direction === "vertical" ? "flex flex-col" : "flex flex-row",
+        {
+          "space-y-1": direction === "vertical" && spacing === 1,
+          "space-y-2": direction === "vertical" && spacing === 2,
+          "space-y-3": direction === "vertical" && spacing === 3,
+          "space-y-4": direction === "vertical" && spacing === 4,
+          "space-y-6": direction === "vertical" && spacing === 6,
+          "space-y-8": direction === "vertical" && spacing === 8,
+          "space-y-12": direction === "vertical" && spacing === 12,
+          "space-x-1": direction === "horizontal" && spacing === 1,
+          "space-x-2": direction === "horizontal" && spacing === 2,
+          "space-x-3": direction === "horizontal" && spacing === 3,
+          "space-x-4": direction === "horizontal" && spacing === 4,
+          "space-x-6": direction === "horizontal" && spacing === 6,
+          "space-x-8": direction === "horizontal" && spacing === 8,
+          "space-x-12": direction === "horizontal" && spacing === 12,
+        },
+        className,
+      )}
+      {...props}
+    />
+  );
+});
 
 Stack.displayName = "Stack";