@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/collapsible.tsx

@@ -1,29 +1,105 @@
 import * as React from "react";
 import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
 
+/**
+ * Props for Collapsible root container (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CollapsibleDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child, merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+
+  /**
+   * The open state of the collapsible when it is initially rendered. Use when you do not need to control its open state.
+   * @default undefined
+   */
+  defaultOpen?: boolean;
+
+  /**
+   * The controlled open state of the collapsible. Must be used in conjunction with onOpenChange.
+   * @default undefined
+   */
+  open?: boolean;
+
+  /**
+   * Event handler called when the open state of the collapsible changes.
+   * @param open - The new open state
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * When true, prevents the user from interacting with the collapsible.
+   * @default undefined
+   */
+  disabled?: boolean;
+} & React.ComponentProps<"div">;
+
+/**
+ * Props for CollapsibleTrigger (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CollapsibleTriggerDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child, merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+} & React.ComponentProps<"button">;
+
+/**
+ * Props for CollapsibleContent (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CollapsibleContentDocsProps = {
+  /**
+   * Change the default rendered element for the one passed as a child, merging their props and behavior.
+   * @default false
+   */
+  asChild?: boolean;
+
+  /**
+   * Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
+   * @default undefined
+   */
+  forceMount?: boolean;
+} & React.ComponentProps<"div">;
+
 /**
  * An interactive component which expands/collapses a panel
  *
- * A flexible container component built on Radix UI primitives that allows users to
+ * A flexible container component built on Radix UI Collapsible primitives that allows users to
  * toggle the visibility of content sections. Unlike Accordion, Collapsible provides
- * more flexibility without enforcing specific visual structures. Perfect for FAQ sections,
- * expandable details, settings panels, and any content that should be initially hidden.
+ * more flexibility without enforcing specific visual structures or mutual exclusivity.
+ * Perfect for FAQ sections, expandable details, settings panels, sidebar navigation,
+ * and any content that should be conditionally visible.
+ *
+ * Built on `@radix-ui/react-collapsible` with enhanced TypeScript support and
+ * comprehensive prop documentation.
  *
  * @component
  * @example
  * ```tsx
- * // Basic controlled collapsible
+ * // Basic controlled collapsible with state management
  * const [isOpen, setIsOpen] = React.useState(false)
  *
  * <Collapsible open={isOpen} onOpenChange={setIsOpen}>
  *   <CollapsibleTrigger asChild>
- *     <Button variant="outline">
+ *     <Button variant="outline" className="w-full justify-between">
  *       Can I use this in my project?
- *       <ChevronDown className="h-4 w-4" />
+ *       <ChevronDown className={cn(
+ *         "h-4 w-4 transition-transform duration-200",
+ *         isOpen && "rotate-180"
+ *       )} />
  *     </Button>
  *   </CollapsibleTrigger>
- *   <CollapsibleContent>
- *     <div className="p-4 border rounded-md bg-muted/50">
+ *   <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down">
+ *     <div className="p-4 border rounded-md bg-muted/50 mt-2">
  *       Yes. Free to use for personal and commercial projects.
  *       No attribution required.
  *     </div>
@@ -33,14 +109,14 @@ import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
  *
  * @example
  * ```tsx
- * // Uncontrolled collapsible with custom styling
- * <Collapsible className="w-full space-y-2">
+ * // Uncontrolled collapsible with default state
+ * <Collapsible defaultOpen={true} className="w-full space-y-2">
  *   <div className="flex items-center justify-between">
  *     <h4 className="text-sm font-semibold">@radix-ui/primitives</h4>
  *     <CollapsibleTrigger asChild>
  *       <Button variant="ghost" size="sm">
- *         <ChevronDown className="h-4 w-4" />
- *         <span className="sr-only">Toggle</span>
+ *         <ChevronDown className="h-4 w-4 transition-transform duration-200 group-data-[state=open]/collapsible:rotate-180" />
+ *         <span className="sr-only">Toggle package list</span>
  *       </Button>
  *     </CollapsibleTrigger>
  *   </div>
@@ -48,41 +124,75 @@ import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
  *     <div className="rounded-md border px-4 py-2 text-sm shadow-sm">
  *       @radix-ui/react-collapsible
  *     </div>
+ *     <div className="rounded-md border px-4 py-2 text-sm shadow-sm">
+ *       @radix-ui/react-accordion
+ *     </div>
  *   </CollapsibleContent>
  * </Collapsible>
  * ```
  *
  * @example
  * ```tsx
- * // FAQ-style implementation
- * <Collapsible>
- *   <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-sm font-medium transition-all hover:underline">
+ * // FAQ-style implementation with custom animations
+ * <Collapsible className="group" data-orientation="vertical">
+ *   <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-sm font-medium transition-all hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring">
  *     How do I get started?
- *     <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+ *     <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200 group-data-[state=open]:rotate-180" />
  *   </CollapsibleTrigger>
- *   <CollapsibleContent className="overflow-hidden text-sm transition-all">
+ *   <CollapsibleContent className="overflow-hidden text-sm transition-all data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down">
  *     <div className="pb-4 pt-0">
- *       Getting started is easy! Simply follow our quick setup guide...
+ *       Getting started is easy! Simply follow our quick setup guide,
+ *       install the required dependencies, and begin building your application.
+ *       Check out our documentation for detailed instructions.
+ *     </div>
+ *   </CollapsibleContent>
+ * </Collapsible>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled collapsible state
+ * <Collapsible disabled className="opacity-50 cursor-not-allowed">
+ *   <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-sm font-medium">
+ *     This section is temporarily unavailable
+ *     <ChevronDown className="h-4 w-4" />
+ *   </CollapsibleTrigger>
+ *   <CollapsibleContent>
+ *     <div className="pb-4 pt-0 text-sm text-muted-foreground">
+ *       This content is currently disabled and cannot be accessed.
  *     </div>
  *   </CollapsibleContent>
  * </Collapsible>
  * ```
  *
  * @accessibility
- * - Full keyboard navigation support (Space/Enter to toggle)
- * - ARIA expanded state automatically managed
- * - Content properly hidden from screen readers when collapsed
- * - Focus management and screen reader announcements
- * - Built on WAI-ARIA design patterns for disclosure widgets
- *
- * @see {@link https://ui.shadcn.com/docs/components/collapsible} for design patterns
- * @see {@link CollapsibleTrigger} - Interactive element to toggle visibility
- * @see {@link CollapsibleContent} - Content container that can be hidden/shown
+ * - **Keyboard Navigation**: Space and Enter keys toggle the collapsed state
+ * - **ARIA States**: `aria-expanded` automatically reflects current state (true/false)
+ * - **ARIA Controls**: `aria-controls` automatically connects trigger to content panel
+ * - **Focus Management**: Proper focus handling and focus-visible indicators
+ * - **Screen Reader Support**: Content properly hidden/announced based on state
+ * - **Disabled States**: Supports disabled prop with appropriate ARIA attributes
+ * - **Role Management**: Trigger has `button` role, content has proper labeling
+ * - **State Announcements**: State changes properly announced to assistive technology
+ *
+ * **Data Attributes for Styling:**
+ * - `[data-state="open"|"closed"]` - Reflects current expanded state
+ * - `[data-disabled]` - Present when disabled prop is true
+ *
+ * **CSS Variables for Animation:**
+ * - `--radix-collapsible-content-width` - Natural width of content
+ * - `--radix-collapsible-content-height` - Natural height of content for smooth animations
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/collapsible} Radix UI Collapsible Documentation
+ * @see {@link https://ui.shadcn.com/docs/components/collapsible} shadcn/ui Design Patterns
+ * @see {@link CollapsibleTrigger} Interactive button element to toggle visibility
+ * @see {@link CollapsibleContent} Content container with automatic height animations
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/} WAI-ARIA Disclosure Pattern
  * @since 1.0.0
  */
-function Collapsible({
-  ...props
-}: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
+function Collapsible(
+  props: React.ComponentProps<typeof CollapsiblePrimitive.Root>,
+) {
   return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
 }
 
@@ -90,50 +200,98 @@ function Collapsible({
  * Interactive trigger element that toggles collapsible content visibility
  *
  * The clickable element that controls the expanded/collapsed state of the associated
- * CollapsibleContent. Supports the asChild prop for composition with custom elements
- * like buttons or other interactive components.
+ * CollapsibleContent. Built on Radix UI CollapsibleTrigger primitive with automatic
+ * ARIA management and keyboard support. Supports the asChild prop for composition
+ * with custom button components or other interactive elements.
+ *
+ * **Key Features:**
+ * - Automatic `aria-expanded` state management
+ * - Built-in keyboard navigation (Space/Enter)
+ * - Flexible composition via `asChild` pattern
+ * - Seamless integration with any interactive element
  *
  * @component
  * @example
  * ```tsx
- * // Simple text trigger
- * <CollapsibleTrigger>
+ * // Simple text trigger with default button styling
+ * <CollapsibleTrigger className="font-medium hover:underline">
  *   Can I use this in my project?
  * </CollapsibleTrigger>
  * ```
  *
  * @example
  * ```tsx
- * // Composed with Button component
+ * // Composed with Button component for consistent styling
  * <CollapsibleTrigger asChild>
  *   <Button variant="outline" className="w-full justify-between">
  *     Advanced Settings
- *     <ChevronDown className="h-4 w-4" />
+ *     <ChevronDown className="h-4 w-4 transition-transform duration-200 group-data-[state=open]:rotate-180" />
  *   </Button>
  * </CollapsibleTrigger>
  * ```
  *
  * @example
  * ```tsx
- * // Custom styled trigger
- * <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-left text-sm font-medium transition-all hover:underline">
+ * // Custom styled trigger with icon animation
+ * <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-left text-sm font-medium transition-all hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring">
  *   How does it work?
- *   <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+ *   <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200 data-[state=open]:rotate-180" />
+ * </CollapsibleTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Trigger composed with icon button
+ * <CollapsibleTrigger asChild>
+ *   <Button variant="ghost" size="sm" className="h-8 w-8 p-0">
+ *     <MoreHorizontal className="h-4 w-4" />
+ *     <span className="sr-only">Toggle options</span>
+ *   </Button>
+ * </CollapsibleTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Trigger with custom element using asChild
+ * <CollapsibleTrigger asChild>
+ *   <div
+ *     role="button"
+ *     tabIndex={0}
+ *     className="flex items-center gap-2 p-2 rounded cursor-pointer hover:bg-accent"
+ *   >
+ *     <FolderIcon className="h-4 w-4" />
+ *     <span>Project Files</span>
+ *     <ChevronRight className="h-3 w-3 transition-transform data-[state=open]:rotate-90" />
+ *   </div>
  * </CollapsibleTrigger>
  * ```
  *
  * @accessibility
- * - Keyboard activation with Space or Enter keys
- * - aria-expanded attribute reflects current expanded state
- * - aria-controls connects trigger to its content panel
- * - Role of button for screen reader compatibility
- * - Focus visible indicator for keyboard navigation
+ * - **Keyboard Navigation**: Space and Enter keys activate the trigger
+ * - **ARIA Expanded**: `aria-expanded` attribute automatically reflects current state (true/false)
+ * - **ARIA Controls**: `aria-controls` automatically connects trigger to its content panel ID
+ * - **Role Management**: Has `button` role for screen reader compatibility
+ * - **Focus Management**: Proper focus handling with focus-visible indicators
+ * - **Disabled State**: When parent Collapsible is disabled, trigger becomes non-interactive
+ * - **Screen Reader Announcements**: State changes properly announced to assistive technology
+ *
+ * **Data Attributes:**
+ * - `[data-state="open"|"closed"]` - Reflects current expanded state for styling
+ * - `[data-disabled]` - Present when the trigger is disabled
  *
+ * @param asChild - When true, merges props onto immediate child instead of rendering button
+ * @param className - Additional CSS classes for styling
+ * @param onClick - Custom click handler (called after internal toggle logic)
+ * @param onKeyDown - Custom keyboard handler (Space/Enter keys handled internally)
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/collapsible#trigger} Radix UI CollapsibleTrigger API
+ * @see {@link Collapsible} Parent container component
+ * @see {@link CollapsibleContent} Content container that this trigger controls
  * @since 1.0.0
  */
-function CollapsibleTrigger({
-  ...props
-}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+function CollapsibleTrigger(
+  props: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>,
+) {
   return (
     <CollapsiblePrimitive.CollapsibleTrigger
       data-slot="collapsible-trigger"
@@ -146,15 +304,23 @@ function CollapsibleTrigger({
  * Content container that can be expanded or collapsed
  *
  * The panel containing content that is shown or hidden based on the collapsible state.
- * Automatically handles smooth animations, height transitions, and accessibility attributes
- * when toggling between expanded and collapsed states.
+ * Built on Radix UI CollapsibleContent primitive with automatic height animations,
+ * accessibility attributes, and smooth transitions when toggling between expanded
+ * and collapsed states.
+ *
+ * **Key Features:**
+ * - Automatic height animations using CSS variables
+ * - Proper accessibility tree management (hidden when collapsed)
+ * - CSS data attributes for custom styling and animations
+ * - Support for forceMount to keep content in DOM when collapsed
+ * - Seamless composition via asChild pattern
  *
  * @component
  * @example
  * ```tsx
- * // Basic content panel
- * <CollapsibleContent>
- *   <div className="rounded-md border px-4 py-2 text-sm">
+ * // Basic content panel with simple styling
+ * <CollapsibleContent className="pt-2">
+ *   <div className="rounded-md border px-4 py-2 text-sm bg-muted/50">
  *     Yes. Free to use for personal and commercial projects.
  *     No attribution required.
  *   </div>
@@ -163,12 +329,15 @@ function CollapsibleTrigger({
  *
  * @example
  * ```tsx
- * // Content with custom styling and multiple elements
- * <CollapsibleContent className="space-y-2">
- *   <div className="rounded-md border px-4 py-3 font-mono text-sm">
+ * // Content with multiple elements and spacing
+ * <CollapsibleContent className="space-y-2 pt-2">
+ *   <div className="rounded-md border px-4 py-3 font-mono text-sm shadow-sm">
  *     @radix-ui/react-collapsible
  *   </div>
- *   <div className="rounded-md border px-4 py-3 font-mono text-sm">
+ *   <div className="rounded-md border px-4 py-3 font-mono text-sm shadow-sm">
+ *     @radix-ui/react-accordion
+ *   </div>
+ *   <div className="rounded-md border px-4 py-3 font-mono text-sm shadow-sm">
  *     @radix-ui/react-dialog
  *   </div>
  * </CollapsibleContent>
@@ -176,26 +345,111 @@ function CollapsibleTrigger({
  *
  * @example
  * ```tsx
- * // Content with overflow handling
+ * // Content with custom animations using CSS variables
  * <CollapsibleContent className="overflow-hidden text-sm transition-all data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down">
- *   <div className="pb-4 pt-0">
- *     Content with custom animations and overflow handling.
+ *   <div className="pb-4 pt-0 px-1">
+ *     Content with smooth height animations. The CSS variables
+ *     --radix-collapsible-content-height and --radix-collapsible-content-width
+ *     are available for custom animation implementations.
+ *   </div>
+ * </CollapsibleContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Force mounted content (stays in DOM when collapsed)
+ * <CollapsibleContent forceMount className="data-[state=closed]:hidden">
+ *   <div className="p-4 text-sm">
+ *     This content remains in the DOM even when collapsed,
+ *     useful for maintaining form state or for SSR consistency.
+ *   </div>
+ * </CollapsibleContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with asChild composition
+ * <CollapsibleContent asChild>
+ *   <motion.div
+ *     initial={{ height: 0 }}
+ *     animate={{ height: "auto" }}
+ *     exit={{ height: 0 }}
+ *     className="overflow-hidden"
+ *   >
+ *     <div className="p-4">
+ *       Content with custom Framer Motion animations
+ *     </div>
+ *   </motion.div>
+ * </CollapsibleContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with complex nested structure
+ * <CollapsibleContent className="overflow-hidden">
+ *   <div className="border-t pt-4 mt-2">
+ *     <div className="grid grid-cols-2 gap-4">
+ *       <div className="space-y-2">
+ *         <h4 className="font-medium">Documentation</h4>
+ *         <ul className="text-sm space-y-1 text-muted-foreground">
+ *           <li>Getting Started</li>
+ *           <li>Installation</li>
+ *           <li>Configuration</li>
+ *         </ul>
+ *       </div>
+ *       <div className="space-y-2">
+ *         <h4 className="font-medium">Examples</h4>
+ *         <ul className="text-sm space-y-1 text-muted-foreground">
+ *           <li>Basic Usage</li>
+ *           <li>Advanced Patterns</li>
+ *           <li>Custom Styling</li>
+ *         </ul>
+ *       </div>
+ *     </div>
  *   </div>
  * </CollapsibleContent>
  * ```
  *
  * @accessibility
- * - Automatically hidden from accessibility tree when collapsed
- * - Smooth height animations with data-state attributes
- * - Properly associated with trigger via aria-controls
- * - Supports custom animation classes and transitions
- * - Content is announced by screen readers when expanded
+ * - **Screen Reader Management**: Automatically hidden from accessibility tree when collapsed
+ * - **ARIA Association**: Properly associated with trigger via `aria-controls` relationship
+ * - **Content Announcements**: Content changes announced by screen readers when expanded
+ * - **Height Animations**: Smooth height transitions with CSS variables for natural motion
+ * - **Focus Management**: Focus properly managed when content becomes visible/hidden
+ * - **Disabled State**: Content appropriately disabled when parent Collapsible is disabled
+ *
+ * **Data Attributes for Styling:**
+ * - `[data-state="open"|"closed"]` - Reflects current expanded state
+ * - `[data-disabled]` - Present when the parent collapsible is disabled
+ *
+ * **CSS Variables for Animation:**
+ * - `--radix-collapsible-content-width` - The natural width of the content
+ * - `--radix-collapsible-content-height` - The natural height for smooth animations
+ *
+ * **Animation Classes:**
+ * Use data-state attributes to apply conditional animations:
+ * ```css
+ * .CollapsibleContent[data-state="open"] {
+ *   animation: slideDown 300ms ease-out;
+ * }
+ * .CollapsibleContent[data-state="closed"] {
+ *   animation: slideUp 300ms ease-out;
+ * }
+ * ```
+ *
+ * @param asChild - When true, merges props onto immediate child instead of rendering div
+ * @param forceMount - When true, forces content to stay in DOM even when collapsed
+ * @param className - Additional CSS classes for styling and animations
+ * @param children - The content to be shown/hidden
  *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/collapsible#content} Radix UI CollapsibleContent API
+ * @see {@link Collapsible} Parent container component
+ * @see {@link CollapsibleTrigger} Trigger component that controls this content
  * @since 1.0.0
  */
-function CollapsibleContent({
-  ...props
-}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
+function CollapsibleContent(
+  props: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>,
+) {
   return (
     <CollapsiblePrimitive.CollapsibleContent
       data-slot="collapsible-content"