@neynar/ui 0.4.0 → 1.0.0

package/src/components/ui/stack.tsx

@@ -1,508 +0,0 @@
-import * as React from "react";
-import { cn } from "@/lib/utils";
-
-/**
- * Spacing options for Stack component using Tailwind CSS spacing scale
- *
- * Maps to Tailwind spacing utilities:
- * - 0 = 0rem (0px) - No spacing
- * - 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 = 0 | 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
- */
-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 mapped to consistent
-   * rem values for predictable visual hierarchy.
-   *
-   * **Spacing Guidelines:**
-   * - Use `0` for no spacing, good for typography and inline elements
-   * - 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
-   * // 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}>
-   *   <Label htmlFor="email">Email</Label>
-   *   <Input id="email" type="email" />
-   *   <Input type="password" placeholder="Password" />
-   * </Stack>
-   *
-   * // 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}>
-   *   <header>Page Header</header>
-   *   <main>Main Content</main>
-   *   <footer>Page Footer</footer>
-   * </Stack>
-   * ```
-   */
-  spacing?: StackSpacing;
-
-  /**
-   * The layout direction of the stack
-   *
-   * **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 for content hierarchy (default)
-   * <Stack>
-   *   <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" 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?: StackDirection;
-};
-
-/**
- * Stack - A flexible layout component for consistent spacing between elements
- *
- * 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, declarative API for common layout patterns without requiring
- * custom CSS or complex flex configurations.
- *
- * **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 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 content layout (default behavior)
- * ```tsx
- * <Stack>
- *   <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 button bar
- * ```tsx
- * <Stack direction="horizontal" spacing={3} className="justify-end">
- *   <Button variant="ghost">Cancel</Button>
- *   <Button variant="outline">Save Draft</Button>
- *   <Button>Publish</Button>
- * </Stack>
- * ```
- *
- * @example Complex form layout with nested stacks
- * ```tsx
- * <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>
- *   </Stack>
- * </form>
- * ```
- *
- * @example Responsive navigation with adaptive direction
- * ```tsx
- * <Stack
- *   direction="horizontal"
- *   spacing={1}
- *   className="flex-col sm:flex-row overflow-x-auto sm:overflow-visible"
- * >
- *   <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:**
- * 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,
-  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 items-center",
-        {
-          "space-y-0": direction === "vertical" && spacing === 0,
-          "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-0": direction === "horizontal" && spacing === 0,
-          "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";
-
-export { Stack };