@auto-engineer/generate-react-client 1.34.0 → 1.36.0

package/dist/starter/src/components/ui/Form.tsx

@@ -14,7 +14,13 @@ import {
 import { cn } from '@/lib/utils';
 import { Label } from '@/components/ui/Label';
 
-const Form = FormProvider;
+/**
+ * Form context provider that wraps react-hook-form's FormProvider.
+ * Use with FormField, FormItem, FormLabel, FormControl, FormDescription, and FormMessage for accessible form layouts with validation.
+ */
+function Form({ ...props }: React.ComponentProps<typeof FormProvider>) {
+  return <FormProvider {...props} />;
+}
 
 type FormFieldContextValue<
   TFieldValues extends FieldValues = FieldValues,
@@ -25,12 +31,13 @@ type FormFieldContextValue<
 
 const FormFieldContext = React.createContext<FormFieldContextValue>({} as FormFieldContextValue);
 
-const FormField = <
+/** Connects a form input to react-hook-form via Controller, providing field context to child components. */
+function FormField<
   TFieldValues extends FieldValues = FieldValues,
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
 >({
   ...props
-}: ControllerProps<TFieldValues, TName>) => {
+}: ControllerProps<TFieldValues, TName>) {
   return (
     <FormFieldContext.Provider value={{ name: props.name }}>
       <Controller {...props} />
@@ -67,6 +74,7 @@ type FormItemContextValue = {
 
 const FormItemContext = React.createContext<FormItemContextValue>({} as FormItemContextValue);
 
+/** Container for a single form field that provides ID context for accessibility linking between label, input, description, and error message. */
 function FormItem({ className, ...props }: React.ComponentProps<'div'>) {
   const id = React.useId();
 
@@ -77,6 +85,7 @@ function FormItem({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Label for a form field that automatically links to its input and displays error styling when validation fails. */
 function FormLabel({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
   const { error, formItemId } = useFormField();
 
@@ -91,6 +100,7 @@ function FormLabel({ className, ...props }: React.ComponentProps<typeof LabelPri
   );
 }
 
+/** Wrapper that merges accessibility attributes (id, aria-describedby, aria-invalid) onto the form input element. */
 function FormControl({ ...props }: React.ComponentProps<typeof Slot.Root>) {
   const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
 
@@ -105,6 +115,7 @@ function FormControl({ ...props }: React.ComponentProps<typeof Slot.Root>) {
   );
 }
 
+/** Helper text displayed below a form input, linked via aria-describedby for screen readers. */
 function FormDescription({ className, ...props }: React.ComponentProps<'p'>) {
   const { formDescriptionId } = useFormField();
 
@@ -118,6 +129,7 @@ function FormDescription({ className, ...props }: React.ComponentProps<'p'>) {
   );
 }
 
+/** Displays validation error messages for a form field. Automatically shows the field's error message or custom children. */
 function FormMessage({ className, ...props }: React.ComponentProps<'p'>) {
   const { error, formMessageId } = useFormField();
   const body = error ? String(error?.message ?? '') : props.children;

package/dist/starter/src/components/ui/HoverCard.stories.tsx

@@ -9,6 +9,7 @@ const meta: Meta<typeof HoverCard> = {
 export default meta;
 type Story = StoryObj<typeof HoverCard>;
 
+/** Shows a user profile preview card triggered by hovering over a username link. */
 export const Default: Story = {
   render: () => (
     <HoverCard>
@@ -33,6 +34,7 @@ export const Default: Story = {
   ),
 };
 
+/** Minimal hover card with just text content. */
 export const Simple: Story = {
   render: () => (
     <HoverCard>

package/dist/starter/src/components/ui/HoverCard.tsx

@@ -3,14 +3,17 @@ import { HoverCard as HoverCardPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/** A popup card that appears when hovering over a trigger element. Ideal for previewing content like user profiles or link destinations. */
 function HoverCard({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
   return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />;
 }
 
+/** Element that activates the hover card on mouse enter. */
 function HoverCardTrigger({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
   return <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />;
 }
 
+/** The popup content that appears when hovering. Portals to body and animates in/out. */
 function HoverCardContent({
   className,
   align = 'center',

package/dist/starter/src/components/ui/Input.stories.tsx

@@ -9,10 +9,12 @@ const meta: Meta<typeof Input> = {
 export default meta;
 type Story = StoryObj<typeof Input>;
 
+/** Basic empty input field. */
 export const Default: Story = {
   args: {},
 };
 
+/** Email input with placeholder text. */
 export const WithPlaceholder: Story = {
   args: {
     placeholder: 'Enter your email...',
@@ -20,6 +22,7 @@ export const WithPlaceholder: Story = {
   },
 };
 
+/** Disabled input that cannot be edited. */
 export const Disabled: Story = {
   args: {
     placeholder: 'Disabled input',
@@ -28,6 +31,7 @@ export const Disabled: Story = {
   },
 };
 
+/** Input paired with a label for accessibility. */
 export const WithLabel: Story = {
   render: () => (
     <div className="grid w-full max-w-sm items-center gap-1.5">

package/dist/starter/src/components/ui/Input.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 
 import { cn } from '@/lib/utils';
 
+/** A styled text input field. Supports all native input types including file uploads. Shows validation error styling via aria-invalid. */
 function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
   return (
     <input

package/dist/starter/src/components/ui/InputGroup.stories.tsx

@@ -9,6 +9,7 @@ const meta: Meta<typeof InputGroup> = {
 export default meta;
 type Story = StoryObj<typeof InputGroup>;
 
+/** Input with a leading email icon addon. */
 export const Default: Story = {
   render: () => (
     <InputGroup className="max-w-sm">
@@ -22,6 +23,7 @@ export const Default: Story = {
   ),
 };
 
+/** URL input with text addons on both sides. */
 export const WithPrefixAndSuffix: Story = {
   render: () => (
     <InputGroup className="max-w-sm">
@@ -36,6 +38,7 @@ export const WithPrefixAndSuffix: Story = {
   ),
 };
 
+/** Search input with a magnifying glass icon. */
 export const SearchInput: Story = {
   render: () => (
     <InputGroup className="max-w-sm">

package/dist/starter/src/components/ui/InputGroup.tsx

@@ -6,6 +6,7 @@ import { Button } from '@/components/ui/Button';
 import { Input } from '@/components/ui/Input';
 import { Textarea } from '@/components/ui/Textarea';
 
+/** Container that combines an input with addons like icons, buttons, or text. Supports inline and block-positioned addons. */
 function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -52,6 +53,7 @@ const inputGroupAddonVariants = cva(
   },
 );
 
+/** Positioned container for icons, text, or buttons alongside the input. Use align prop to position at inline-start, inline-end, block-start, or block-end. */
 function InputGroupAddon({
   className,
   align = 'inline-start',
@@ -88,6 +90,7 @@ const inputGroupButtonVariants = cva('text-sm shadow-none flex gap-2 items-cente
   },
 });
 
+/** A compact button sized for use inside InputGroupAddon. */
 function InputGroupButton({
   className,
   type = 'button',
@@ -106,6 +109,7 @@ function InputGroupButton({
   );
 }
 
+/** Static text or icon displayed in an InputGroupAddon. */
 function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span
@@ -118,6 +122,7 @@ function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
   );
 }
 
+/** Input element styled to integrate seamlessly within an InputGroup. */
 function InputGroupInput({ className, ...props }: React.ComponentProps<'input'>) {
   return (
     <Input
@@ -131,6 +136,7 @@ function InputGroupInput({ className, ...props }: React.ComponentProps<'input'>)
   );
 }
 
+/** Textarea element styled to integrate seamlessly within an InputGroup. */
 function InputGroupTextarea({ className, ...props }: React.ComponentProps<'textarea'>) {
   return (
     <Textarea

package/dist/starter/src/components/ui/InputOTP.stories.tsx

@@ -8,6 +8,7 @@ const meta: Meta<typeof InputOTP> = {
 export default meta;
 type Story = StoryObj<typeof InputOTP>;
 
+/** 6-digit OTP input split into two groups of three with a separator. */
 export const Default: Story = {
   render: () => (
     <InputOTP maxLength={6}>
@@ -26,6 +27,7 @@ export const Default: Story = {
   ),
 };
 
+/** Compact 4-digit PIN input without separator. */
 export const FourDigits: Story = {
   render: () => (
     <InputOTP maxLength={4}>

package/dist/starter/src/components/ui/InputOTP.tsx

@@ -6,6 +6,7 @@ import { MinusIcon } from 'lucide-react';
 
 import { cn } from '@/lib/utils';
 
+/** One-time password input with individual digit slots. Handles paste, backspace, and arrow key navigation automatically. */
 function InputOTP({
   className,
   containerClassName,
@@ -23,10 +24,12 @@ function InputOTP({
   );
 }
 
+/** Groups InputOTPSlot elements together visually. */
 function InputOTPGroup({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="input-otp-group" className={cn('flex items-center', className)} {...props} />;
 }
 
+/** A single digit slot in the OTP input. Shows a blinking caret when active. */
 function InputOTPSlot({
   index,
   className,
@@ -57,6 +60,7 @@ function InputOTPSlot({
   );
 }
 
+/** Visual separator between groups of OTP slots, typically a dash. */
 function InputOTPSeparator({ ...props }: React.ComponentProps<'div'>) {
   return (
     <div data-slot="input-otp-separator" role="separator" {...props}>

package/dist/starter/src/components/ui/Item.stories.tsx

@@ -9,6 +9,7 @@ const meta: Meta<typeof Item> = {
 export default meta;
 type Story = StoryObj<typeof Item>;
 
+/** Standard item with title, description, and action buttons. */
 export const Default: Story = {
   render: () => (
     <Item>
@@ -28,6 +29,7 @@ export const Default: Story = {
   ),
 };
 
+/** Item with visible border using the outline variant. */
 export const OutlineVariant: Story = {
   render: () => (
     <Item variant="outline">
@@ -44,6 +46,7 @@ export const OutlineVariant: Story = {
   ),
 };
 
+/** Compact item with reduced padding for dense lists. */
 export const SmallSize: Story = {
   render: () => (
     <Item size="sm">

package/dist/starter/src/components/ui/Item.tsx

@@ -5,12 +5,14 @@ import { Slot } from 'radix-ui';
 import { cn } from '@/lib/utils';
 import { Separator } from '@/components/ui/Separator';
 
+/** Container for a list of Item components. Provides list semantics for accessibility. */
 function ItemGroup({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div role="list" data-slot="item-group" className={cn('group/item-group flex flex-col', className)} {...props} />
   );
 }
 
+/** Horizontal divider between items in an ItemGroup. */
 function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
   return <Separator data-slot="item-separator" orientation="horizontal" className={cn('my-0', className)} {...props} />;
 }
@@ -36,6 +38,7 @@ const itemVariants = cva(
   },
 );
 
+/** A flexible list item for displaying structured content like notifications, settings rows, or search results. Compose with ItemMedia, ItemContent, ItemTitle, ItemDescription, and ItemActions. */
 function Item({
   className,
   variant = 'default',
@@ -71,6 +74,7 @@ const itemMediaVariants = cva(
   },
 );
 
+/** Container for an icon, avatar, or image at the start of an Item. Use variant="icon" for styled icon backgrounds or variant="image" for thumbnails. */
 function ItemMedia({
   className,
   variant = 'default',
@@ -86,6 +90,7 @@ function ItemMedia({
   );
 }
 
+/** Main content area of an Item, containing title and description. */
 function ItemContent({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -96,6 +101,7 @@ function ItemContent({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Primary text label for an Item. */
 function ItemTitle({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -106,6 +112,7 @@ function ItemTitle({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Secondary text below the title, limited to 2 lines. */
 function ItemDescription({ className, ...props }: React.ComponentProps<'p'>) {
   return (
     <p
@@ -120,10 +127,12 @@ function ItemDescription({ className, ...props }: React.ComponentProps<'p'>) {
   );
 }
 
+/** Container for action buttons at the end of an Item. */
 function ItemActions({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="item-actions" className={cn('flex items-center gap-2', className)} {...props} />;
 }
 
+/** Full-width header row spanning the top of an Item, with space-between layout. */
 function ItemHeader({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -134,6 +143,7 @@ function ItemHeader({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Full-width footer row spanning the bottom of an Item, with space-between layout. */
 function ItemFooter({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div

package/dist/starter/src/components/ui/Kbd.stories.tsx

@@ -13,24 +13,28 @@ const meta: Meta<typeof Kbd> = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/** Shows a single keyboard key shortcut. */
 export const Default: Story = {
   args: {
     children: '⌘K',
   },
 };
 
+/** Shows a key with a text label like "Ctrl". */
 export const WithText: Story = {
   args: {
     children: 'Ctrl',
   },
 };
 
+/** Shows a key with an arrow symbol. */
 export const ArrowKeys: Story = {
   args: {
     children: '→',
   },
 };
 
+/** Shows two keys composed together to represent a shortcut combination. */
 export const Multiple: Story = {
   render: () => (
     <div className="flex gap-2 items-center">
@@ -41,6 +45,7 @@ export const Multiple: Story = {
   ),
 };
 
+/** Shows a three-key combination shortcut. */
 export const Combination: Story = {
   render: () => (
     <div className="flex gap-2 items-center">

package/dist/starter/src/components/ui/Kbd.tsx

@@ -6,6 +6,10 @@ interface KbdProps {
   className?: string;
 }
 
+/**
+ * Renders inline keyboard key indicators, styled to look like physical keys.
+ * Use to display keyboard shortcuts or key combinations in documentation and UI hints.
+ */
 export function Kbd({ children, className }: KbdProps) {
   return (
     <kbd

package/dist/starter/src/components/ui/Label.stories.tsx

@@ -28,6 +28,7 @@ const meta: Meta<typeof Label> = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/** Shows a basic label associated with a form field. */
 export const Default: Story = {
   args: {
     children: 'Email address',
@@ -35,6 +36,7 @@ export const Default: Story = {
   },
 };
 
+/** Shows the label with the required prop, which appends a red asterisk. */
 export const Required: Story = {
   args: {
     children: 'Email address',
@@ -43,6 +45,7 @@ export const Required: Story = {
   },
 };
 
+/** Shows the label using the "required" variant prop directly. */
 export const RequiredVariant: Story = {
   args: {
     children: 'Email address',
@@ -51,6 +54,7 @@ export const RequiredVariant: Story = {
   },
 };
 
+/** Shows the label paired with a text input in a form layout. */
 export const WithForm: Story = {
   render: (args) => (
     <div className="space-y-2">
@@ -67,6 +71,7 @@ export const WithForm: Story = {
   ),
 };
 
+/** Demonstrates the dimmed appearance when the associated input is disabled. */
 export const DisabledField: Story = {
   render: (args) => (
     <div className="space-y-2">

package/dist/starter/src/components/ui/Label.tsx

@@ -23,6 +23,10 @@ export interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement>,
   children?: React.ReactNode;
 }
 
+/**
+ * An accessible label associated with a form control via the htmlFor prop.
+ * Supports a "required" variant that appends a red asterisk, and automatically dims when its peer input is disabled.
+ */
 const Label = React.forwardRef<HTMLLabelElement, LabelProps>(({ className, variant, required, ...props }, ref) => {
   const effectiveVariant = required ? 'required' : variant || 'default';
 

package/dist/starter/src/components/ui/Menubar.stories.tsx

@@ -17,6 +17,7 @@ const meta: Meta<typeof Menubar> = {
 export default meta;
 type Story = StoryObj<typeof Menubar>;
 
+/** Shows a menubar with File and Edit menus containing items and keyboard shortcuts. */
 export const Default: Story = {
   render: () => (
     <Menubar>
@@ -56,6 +57,7 @@ export const Default: Story = {
   ),
 };
 
+/** Demonstrates menu sections organized with labels to group related items. */
 export const WithLabels: Story = {
   render: () => (
     <Menubar>

package/dist/starter/src/components/ui/Menubar.tsx

@@ -6,6 +6,10 @@ import { Menubar as MenubarPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/**
+ * A horizontal menu bar for desktop applications, built on Radix UI Menubar primitive.
+ * Compose with MenubarMenu, MenubarTrigger, and MenubarContent to create top-level menu groups with keyboard navigation.
+ */
 function Menubar({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.Root>) {
   return (
     <MenubarPrimitive.Root
@@ -16,6 +20,7 @@ function Menubar({ className, ...props }: React.ComponentProps<typeof MenubarPri
   );
 }
 
+/** A single menu within the menubar that wraps a trigger and its dropdown content. */
 function MenubarMenu({ ...props }: React.ComponentProps<typeof MenubarPrimitive.Menu>) {
   return <MenubarPrimitive.Menu data-slot="menubar-menu" {...props} />;
 }
@@ -32,6 +37,7 @@ function MenubarRadioGroup({ ...props }: React.ComponentProps<typeof MenubarPrim
   return <MenubarPrimitive.RadioGroup data-slot="menubar-radio-group" {...props} />;
 }
 
+/** The button that toggles a menu open within the menubar. */
 function MenubarTrigger({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.Trigger>) {
   return (
     <MenubarPrimitive.Trigger
@@ -45,6 +51,7 @@ function MenubarTrigger({ className, ...props }: React.ComponentProps<typeof Men
   );
 }
 
+/** The dropdown panel that appears when a MenubarTrigger is activated. Renders via a portal. */
 function MenubarContent({
   className,
   align = 'start',
@@ -69,9 +76,12 @@ function MenubarContent({
   );
 }
 
+/** An interactive item within a menubar dropdown. Supports an inset layout and a destructive variant. */
 function MenubarItem({
   className,
+  /** Adds left padding to align with items that have icons or indicators. */
   inset,
+  /** Use "destructive" for dangerous actions. */
   variant = 'default',
   ...props
 }: React.ComponentProps<typeof MenubarPrimitive.Item> & {
@@ -92,6 +102,7 @@ function MenubarItem({
   );
 }
 
+/** A menu item with a checkbox indicator for toggling boolean options. */
 function MenubarCheckboxItem({
   className,
   children,
@@ -118,6 +129,7 @@ function MenubarCheckboxItem({
   );
 }
 
+/** A menu item within a MenubarRadioGroup that shows a radio dot when selected. */
 function MenubarRadioItem({ className, children, ...props }: React.ComponentProps<typeof MenubarPrimitive.RadioItem>) {
   return (
     <MenubarPrimitive.RadioItem
@@ -165,6 +177,7 @@ function MenubarSeparator({ className, ...props }: React.ComponentProps<typeof M
   );
 }
 
+/** Displays a keyboard shortcut hint aligned to the right of a menu item. */
 function MenubarShortcut({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span
@@ -179,6 +192,7 @@ function MenubarSub({ ...props }: React.ComponentProps<typeof MenubarPrimitive.S
   return <MenubarPrimitive.Sub data-slot="menubar-sub" {...props} />;
 }
 
+/** The trigger for a nested submenu, rendering a chevron icon to indicate expandability. */
 function MenubarSubTrigger({
   className,
   inset,
@@ -203,6 +217,7 @@ function MenubarSubTrigger({
   );
 }
 
+/** The dropdown content panel for a nested submenu. */
 function MenubarSubContent({ className, ...props }: React.ComponentProps<typeof MenubarPrimitive.SubContent>) {
   return (
     <MenubarPrimitive.SubContent

package/dist/starter/src/components/ui/NativeSelect.stories.tsx

@@ -8,6 +8,7 @@ const meta: Meta<typeof NativeSelect> = {
 export default meta;
 type Story = StoryObj<typeof NativeSelect>;
 
+/** Shows a native select with pre-selected value and several options. */
 export const Default: Story = {
   render: () => (
     <NativeSelect defaultValue="react">
@@ -19,6 +20,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows the compact size variant with a disabled placeholder option. */
 export const Small: Story = {
   render: () => (
     <NativeSelect size="sm" defaultValue="">
@@ -32,6 +34,7 @@ export const Small: Story = {
   ),
 };
 
+/** Shows the select in a disabled state. */
 export const Disabled: Story = {
   render: () => (
     <NativeSelect disabled defaultValue="react">

package/dist/starter/src/components/ui/NativeSelect.tsx

@@ -3,6 +3,10 @@ import { ChevronDownIcon } from 'lucide-react';
 
 import { cn } from '@/lib/utils';
 
+/**
+ * A styled wrapper around the browser's native <select> element.
+ * Use instead of the custom Select component when native mobile pickers or simpler accessibility is preferred.
+ */
 function NativeSelect({
   className,
   size = 'default',
@@ -33,10 +37,12 @@ function NativeSelect({
   );
 }
 
+/** An individual option within a NativeSelect dropdown. */
 function NativeSelectOption({ ...props }: React.ComponentProps<'option'>) {
   return <option data-slot="native-select-option" {...props} />;
 }
 
+/** Groups related options under a label within a NativeSelect. */
 function NativeSelectOptGroup({ className, ...props }: React.ComponentProps<'optgroup'>) {
   return <optgroup data-slot="native-select-optgroup" className={cn(className)} {...props} />;
 }

package/dist/starter/src/components/ui/NavigationMenu.stories.tsx

@@ -15,6 +15,7 @@ const meta: Meta<typeof NavigationMenu> = {
 export default meta;
 type Story = StoryObj<typeof NavigationMenu>;
 
+/** Shows a navigation menu with dropdown content panels and a direct link item. */
 export const Default: Story = {
   render: () => (
     <NavigationMenu>
@@ -59,6 +60,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a flat navigation menu with simple link items and no dropdowns. */
 export const SimpleLinks: Story = {
   render: () => (
     <NavigationMenu>

package/dist/starter/src/components/ui/NavigationMenu.tsx

@@ -5,9 +5,14 @@ import { NavigationMenu as NavigationMenuPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/**
+ * A site-wide navigation component with dropdown content panels, built on Radix UI NavigationMenu primitive.
+ * Compose with NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, and NavigationMenuContent for rich mega-menu layouts.
+ */
 function NavigationMenu({
   className,
   children,
+  /** Whether to render the shared viewport container for content panels. Set to false for inline dropdowns. */
   viewport = true,
   ...props
 }: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & {
@@ -26,6 +31,7 @@ function NavigationMenu({
   );
 }
 
+/** The horizontal list container for navigation menu items. */
 function NavigationMenuList({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.List>) {
   return (
     <NavigationMenuPrimitive.List
@@ -46,6 +52,7 @@ const navigationMenuTriggerStyle = cva(
   'group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=open]:hover:bg-accent data-[state=open]:text-accent-foreground data-[state=open]:focus:bg-accent data-[state=open]:bg-accent/50 focus-visible:ring-ring/50 outline-none transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-1',
 );
 
+/** The button that opens a NavigationMenuContent dropdown, with an animated chevron indicator. */
 function NavigationMenuTrigger({
   className,
   children,
@@ -66,6 +73,7 @@ function NavigationMenuTrigger({
   );
 }
 
+/** The expandable content panel that appears below a NavigationMenuTrigger with animated transitions. */
 function NavigationMenuContent({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Content>) {
   return (
     <NavigationMenuPrimitive.Content
@@ -98,6 +106,7 @@ function NavigationMenuViewport({
   );
 }
 
+/** A styled link within the navigation menu, used for both top-level and dropdown links. */
 function NavigationMenuLink({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Link>) {
   return (
     <NavigationMenuPrimitive.Link
@@ -111,6 +120,7 @@ function NavigationMenuLink({ className, ...props }: React.ComponentProps<typeof
   );
 }
 
+/** An animated arrow indicator that tracks the active menu item position. */
 function NavigationMenuIndicator({
   className,
   ...props