@auto-engineer/generate-react-client 1.33.0 → 1.35.0

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

@@ -21,6 +21,10 @@ const buttonGroupVariants = cva(
   },
 );
 
+/**
+ * Groups multiple Buttons together with connected borders, removing inner border-radius between siblings.
+ * Supports horizontal (default) and vertical orientation.
+ */
 function ButtonGroup({
   className,
   orientation,
@@ -37,6 +41,7 @@ function ButtonGroup({
   );
 }
 
+/** A non-interactive text label or addon segment within a ButtonGroup, styled to match adjacent buttons. */
 function ButtonGroupText({
   className,
   asChild = false,
@@ -57,6 +62,7 @@ function ButtonGroupText({
   );
 }
 
+/** A visual divider between buttons in a ButtonGroup, rendered as a Separator. */
 function ButtonGroupSeparator({
   className,
   orientation = 'vertical',

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

@@ -14,6 +14,7 @@ function CalendarDemo() {
   return <Calendar mode="single" selected={date} onSelect={setDate} className="rounded-md border" />;
 }
 
+/** Shows a single-date selection calendar with controlled state. */
 export const Default: Story = {
   render: () => <CalendarDemo />,
 };
@@ -33,6 +34,7 @@ function CalendarRangeDemo() {
   );
 }
 
+/** Demonstrates date range selection across two side-by-side months. */
 export const RangeSelection: Story = {
   render: () => <CalendarRangeDemo />,
 };

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

@@ -5,11 +5,16 @@ import { DayPicker, getDefaultClassNames, type DayButton } from 'react-day-picke
 import { cn } from '@/lib/utils';
 import { Button, buttonVariants } from '@/components/ui/Button';
 
+/**
+ * A date picker component built on react-day-picker supporting single date, multiple date, and date range selection.
+ * Supports month/year dropdowns, outside days visibility, keyboard navigation, and multi-month layouts.
+ */
 function Calendar({
   className,
   classNames,
   showOutsideDays = true,
   captionLayout = 'label',
+  /** The Button variant used for navigation arrows. Defaults to `"ghost"`. */
   buttonVariant = 'ghost',
   formatters,
   components,
@@ -126,6 +131,7 @@ function Calendar({
   );
 }
 
+/** Internal button rendered for each day cell, handling selection states, range highlighting, and focus management. */
 function CalendarDayButton({ className, day, modifiers, ...props }: React.ComponentProps<typeof DayButton>) {
   const defaultClassNames = getDefaultClassNames();
 

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

@@ -9,6 +9,7 @@ const meta: Meta<typeof Card> = {
 export default meta;
 type Story = StoryObj<typeof Card>;
 
+/** Shows a full card with header, content, and footer containing action buttons. */
 export const Default: Story = {
   render: () => (
     <Card className="w-[350px]">
@@ -27,6 +28,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a minimal card with only a header and content, without a footer. */
 export const Simple: Story = {
   render: () => (
     <Card className="w-[350px]">

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

@@ -2,6 +2,10 @@ import * as React from 'react';
 
 import { cn } from '@/lib/utils';
 
+/**
+ * A flexible container for grouping related content with a border, shadow, and rounded corners.
+ * Compose with CardHeader, CardTitle, CardDescription, CardContent, CardFooter, and CardAction.
+ */
 function Card({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -12,6 +16,7 @@ function Card({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** The top section of a Card, containing the title, description, and optional action slot. */
 function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -25,14 +30,17 @@ function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** The primary heading of a Card, rendered as semibold text. */
 function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="card-title" className={cn('leading-none font-semibold', className)} {...props} />;
 }
 
+/** A short summary below the CardTitle, styled in muted foreground. */
 function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="card-description" className={cn('text-muted-foreground text-sm', className)} {...props} />;
 }
 
+/** An optional action element (e.g., a button or menu) aligned to the top-right of the CardHeader. */
 function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -43,10 +51,12 @@ function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** The main body area of a Card for arbitrary content. */
 function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="card-content" className={cn('px-6', className)} {...props} />;
 }
 
+/** The bottom section of a Card, typically used for action buttons or metadata. */
 function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div data-slot="card-footer" className={cn('flex items-center px-6 [.border-t]:pt-6', className)} {...props} />

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

@@ -9,6 +9,7 @@ const meta: Meta<typeof Carousel> = {
 export default meta;
 type Story = StoryObj<typeof Carousel>;
 
+/** Shows a basic carousel with one full-width slide visible at a time and navigation arrows. */
 export const Default: Story = {
   render: () => (
     <div className="w-full max-w-xs mx-auto">
@@ -31,6 +32,7 @@ export const Default: Story = {
   ),
 };
 
+/** Demonstrates showing three slides simultaneously using `basis-1/3` on each CarouselItem. */
 export const ThirdWidth: Story = {
   render: () => (
     <div className="w-full max-w-sm mx-auto">

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

@@ -40,6 +40,11 @@ function useCarousel() {
   return context;
 }
 
+/**
+ * A slideshow component for cycling through content panels with arrow-key navigation.
+ * Built on Embla Carousel. Compose with CarouselContent, CarouselItem, CarouselPrevious, and CarouselNext.
+ * Supports horizontal and vertical orientation, and accepts Embla plugins (e.g., autoplay).
+ */
 function Carousel({
   orientation = 'horizontal',
   opts,
@@ -129,6 +134,7 @@ function Carousel({
   );
 }
 
+/** The scrollable container for carousel slides. Wraps CarouselItem children in a flex layout. */
 function CarouselContent({ className, ...props }: React.ComponentProps<'div'>) {
   const { carouselRef, orientation } = useCarousel();
 
@@ -139,6 +145,7 @@ function CarouselContent({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** A single slide within the carousel. Takes full width by default; use `basis-*` classes to show multiple slides. */
 function CarouselItem({ className, ...props }: React.ComponentProps<'div'>) {
   const { orientation } = useCarousel();
 
@@ -153,6 +160,7 @@ function CarouselItem({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Navigation button to scroll to the previous slide, automatically disabled at the beginning. */
 function CarouselPrevious({
   className,
   variant = 'outline',
@@ -183,6 +191,7 @@ function CarouselPrevious({
   );
 }
 
+/** Navigation button to scroll to the next slide, automatically disabled at the end. */
 function CarouselNext({
   className,
   variant = 'outline',

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

@@ -23,6 +23,7 @@ const chartConfig = {
   mobile: { label: 'Mobile', color: 'var(--chart-2)' },
 } satisfies ChartConfig;
 
+/** Shows a grouped bar chart with desktop and mobile data series, tooltips, and themed colors. */
 export const Default: Story = {
   render: () => (
     <ChartContainer config={chartConfig} className="min-h-[200px] w-full">

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

@@ -29,6 +29,10 @@ function useChart() {
   return context;
 }
 
+/**
+ * A themed wrapper for Recharts charts that provides responsive sizing, CSS custom property-based color theming, and a chart context for tooltips and legends.
+ * Pass a `config` object mapping data keys to labels, colors, and optional icons.
+ */
 function ChartContainer({
   id,
   className,
@@ -91,6 +95,10 @@ ${colorConfig
 
 const ChartTooltip = RechartsPrimitive.Tooltip;
 
+/**
+ * A styled tooltip content component for Recharts that reads labels and colors from ChartConfig.
+ * Supports dot, line, and dashed indicator styles.
+ */
 function ChartTooltipContent({
   active,
   payload,
@@ -219,6 +227,7 @@ function ChartTooltipContent({
 
 const ChartLegend = RechartsPrimitive.Legend;
 
+/** A styled legend content component for Recharts that reads labels, colors, and icons from ChartConfig. */
 function ChartLegendContent({
   className,
   hideIcon = false,

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

@@ -9,18 +9,22 @@ const meta: Meta<typeof Checkbox> = {
 export default meta;
 type Story = StoryObj<typeof Checkbox>;
 
+/** Shows an unchecked checkbox in its default state. */
 export const Default: Story = {
   render: () => <Checkbox />,
 };
 
+/** Shows a checkbox that starts in the checked state. */
 export const Checked: Story = {
   render: () => <Checkbox defaultChecked />,
 };
 
+/** Shows a disabled checkbox that cannot be interacted with. */
 export const Disabled: Story = {
   render: () => <Checkbox disabled />,
 };
 
+/** Shows a checkbox paired with a Label component for accessible form usage. */
 export const WithLabel: Story = {
   render: () => (
     <div className="flex items-center space-x-2">

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

@@ -6,6 +6,7 @@ import { Checkbox as CheckboxPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/** A toggleable boolean input with check icon. Supports checked, unchecked, and indeterminate states. Pair with Label for forms. */
 function Checkbox({ className, ...props }: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
   return (
     <CheckboxPrimitive.Root

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

@@ -31,10 +31,12 @@ function CollapsibleDemo() {
   );
 }
 
+/** Shows a controlled collapsible section that starts closed and can be toggled with a button. */
 export const Default: Story = {
   render: () => <CollapsibleDemo />,
 };
 
+/** Shows a collapsible section that starts in the open state using `defaultOpen`. */
 export const DefaultOpen: Story = {
   render: () => (
     <Collapsible defaultOpen className="w-[350px] space-y-2">

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

@@ -1,13 +1,16 @@
 import { Collapsible as CollapsiblePrimitive } from 'radix-ui';
 
+/** A disclosure widget that toggles content visibility. Compose with CollapsibleTrigger and CollapsibleContent. */
 function Collapsible({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
   return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
 }
 
+/** The interactive element that toggles the CollapsibleContent open or closed. */
 function CollapsibleTrigger({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
   return <CollapsiblePrimitive.CollapsibleTrigger data-slot="collapsible-trigger" {...props} />;
 }
 
+/** The content region that is shown or hidden when the Collapsible is toggled. */
 function CollapsibleContent({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
   return <CollapsiblePrimitive.CollapsibleContent data-slot="collapsible-content" {...props} />;
 }

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

@@ -64,10 +64,12 @@ const meta: Meta = {
 export default meta;
 type Story = StoryObj;
 
+/** Shows a searchable combobox with type-ahead filtering of framework options. */
 export const Default: Story = {
   render: () => <SearchableCombobox />,
 };
 
+/** Demonstrates the combobox with a clear button that resets the selection. */
 export const WithClear: Story = {
   render: () => <ClearableCombobox />,
 };

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

@@ -8,12 +8,22 @@ import { cn } from '@/lib/utils';
 import { Button } from '@/components/ui/Button';
 import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput } from '@/components/ui/InputGroup';
 
+/**
+ * An autocomplete input that combines a text field with a filterable dropdown list.
+ * Built on Base UI Combobox primitive. Supports single and multi-select with chips,
+ * custom filtering, grouped options, and clearable selections.
+ *
+ * Compose with ComboboxInput, ComboboxContent, ComboboxList, and ComboboxItem.
+ * For multi-select, use ComboboxChips, ComboboxChip, and ComboboxChipsInput.
+ */
 const Combobox = ComboboxPrimitive.Root;
 
+/** Renders the display text for the currently selected combobox value. */
 function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {
   return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />;
 }
 
+/** Button that toggles the combobox dropdown open/closed. Renders a chevron icon automatically. */
 function ComboboxTrigger({ className, children, ...props }: ComboboxPrimitive.Trigger.Props) {
   return (
     <ComboboxPrimitive.Trigger
@@ -27,6 +37,7 @@ function ComboboxTrigger({ className, children, ...props }: ComboboxPrimitive.Tr
   );
 }
 
+/** Button that clears the current combobox selection. Renders an X icon. */
 function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
   return (
     <ComboboxPrimitive.Clear
@@ -40,11 +51,16 @@ function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
   );
 }
 
+/**
+ * Text input for filtering combobox options, wrapped in an InputGroup with optional trigger and clear buttons.
+ */
 function ComboboxInput({
   className,
   children,
   disabled = false,
+  /** Whether to show the dropdown toggle chevron button. */
   showTrigger = true,
+  /** Whether to show a clear button when a value is selected. */
   showClear = false,
   ...props
 }: ComboboxPrimitive.Input.Props & {
@@ -74,6 +90,7 @@ function ComboboxInput({
   );
 }
 
+/** Positioned popover that contains the combobox dropdown list. Portals to the document body. */
 function ComboboxContent({
   className,
   side = 'bottom',
@@ -108,6 +125,7 @@ function ComboboxContent({
   );
 }
 
+/** Scrollable container for combobox option items. */
 function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
   return (
     <ComboboxPrimitive.List
@@ -121,6 +139,7 @@ function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
   );
 }
 
+/** A selectable option within the combobox list. Shows a check indicator when selected. */
 function ComboboxItem({ className, children, ...props }: ComboboxPrimitive.Item.Props) {
   return (
     <ComboboxPrimitive.Item
@@ -142,10 +161,12 @@ function ComboboxItem({ className, children, ...props }: ComboboxPrimitive.Item.
   );
 }
 
+/** Groups related combobox items together, typically with a ComboboxLabel. */
 function ComboboxGroup({ className, ...props }: ComboboxPrimitive.Group.Props) {
   return <ComboboxPrimitive.Group data-slot="combobox-group" className={cn(className)} {...props} />;
 }
 
+/** Non-interactive label heading for a ComboboxGroup. */
 function ComboboxLabel({ className, ...props }: ComboboxPrimitive.GroupLabel.Props) {
   return (
     <ComboboxPrimitive.GroupLabel
@@ -159,10 +180,12 @@ function ComboboxLabel({ className, ...props }: ComboboxPrimitive.GroupLabel.Pro
   );
 }
 
+/** Provides the collection of items for virtual scrolling or dynamic option sets. */
 function ComboboxCollection({ ...props }: ComboboxPrimitive.Collection.Props) {
   return <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />;
 }
 
+/** Displayed when no combobox items match the current filter query. */
 function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
   return (
     <ComboboxPrimitive.Empty
@@ -176,6 +199,7 @@ function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
   );
 }
 
+/** Visual divider between groups of combobox items. */
 function ComboboxSeparator({ className, ...props }: ComboboxPrimitive.Separator.Props) {
   return (
     <ComboboxPrimitive.Separator
@@ -186,6 +210,7 @@ function ComboboxSeparator({ className, ...props }: ComboboxPrimitive.Separator.
   );
 }
 
+/** Container for multi-select chips, styled as a form input. Use with ComboboxChip and ComboboxChipsInput. */
 function ComboboxChips({
   className,
   ...props
@@ -202,9 +227,11 @@ function ComboboxChips({
   );
 }
 
+/** Individual chip representing a selected value in multi-select mode. Optionally includes a remove button. */
 function ComboboxChip({
   className,
   children,
+  /** Whether to show the remove (X) button on the chip. */
   showRemove = true,
   ...props
 }: ComboboxPrimitive.Chip.Props & {
@@ -233,6 +260,7 @@ function ComboboxChip({
   );
 }
 
+/** Inline text input rendered alongside chips for multi-select filtering. */
 function ComboboxChipsInput({ className, children, ...props }: ComboboxPrimitive.Input.Props) {
   return (
     <ComboboxPrimitive.Input
@@ -243,6 +271,7 @@ function ComboboxChipsInput({ className, children, ...props }: ComboboxPrimitive
   );
 }
 
+/** Returns a ref to use as the anchor element for positioning the combobox popup (e.g. for chips layout). */
 function useComboboxAnchor() {
   return React.useRef<HTMLDivElement | null>(null);
 }

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

@@ -18,6 +18,7 @@ const meta: Meta<typeof Command> = {
 export default meta;
 type Story = StoryObj<typeof Command>;
 
+/** Shows the command palette with grouped items, icons, keyboard shortcuts, and a search input. */
 export const Default: Story = {
   render: () => (
     <Command className="rounded-lg border shadow-md md:min-w-[450px]">
@@ -57,6 +58,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows the empty state when no items match the search query. */
 export const WithNoResults: Story = {
   render: () => (
     <Command className="rounded-lg border shadow-md md:min-w-[450px]">

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

@@ -7,6 +7,12 @@ import { SearchIcon } from 'lucide-react';
 import { cn } from '@/lib/utils';
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@/components/ui/Dialog';
 
+/**
+ * A command palette / search interface for filtering and selecting from a list of actions or items.
+ * Built on cmdk with keyboard navigation, grouping, and search filtering.
+ *
+ * Compose with CommandInput, CommandList, CommandGroup, CommandItem, and CommandEmpty.
+ */
 function Command({ className, ...props }: React.ComponentProps<typeof CommandPrimitive>) {
   return (
     <CommandPrimitive
@@ -20,11 +26,18 @@ function Command({ className, ...props }: React.ComponentProps<typeof CommandPri
   );
 }
 
+/**
+ * Wraps Command in a modal Dialog for use as a keyboard-triggered command palette (e.g. Ctrl+K).
+ * Provides accessible title and description via screen-reader-only DialogHeader.
+ */
 function CommandDialog({
+  /** Accessible title for screen readers. */
   title = 'Command Palette',
+  /** Accessible description for screen readers. */
   description = 'Search for a command to run...',
   children,
   className,
+  /** Whether to show the X close button. */
   showCloseButton = true,
   ...props
 }: React.ComponentProps<typeof Dialog> & {
@@ -48,6 +61,7 @@ function CommandDialog({
   );
 }
 
+/** Search input with a built-in search icon for filtering command items. */
 function CommandInput({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Input>) {
   return (
     <div data-slot="command-input-wrapper" className="flex h-9 items-center gap-2 border-b px-3">
@@ -64,6 +78,7 @@ function CommandInput({ className, ...props }: React.ComponentProps<typeof Comma
   );
 }
 
+/** Scrollable container for command results. */
 function CommandList({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.List>) {
   return (
     <CommandPrimitive.List
@@ -74,10 +89,12 @@ function CommandList({ className, ...props }: React.ComponentProps<typeof Comman
   );
 }
 
+/** Displayed when no command items match the search query. */
 function CommandEmpty({ ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>) {
   return <CommandPrimitive.Empty data-slot="command-empty" className="py-6 text-center text-sm" {...props} />;
 }
 
+/** Groups related command items under a heading label. */
 function CommandGroup({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>) {
   return (
     <CommandPrimitive.Group
@@ -91,6 +108,7 @@ function CommandGroup({ className, ...props }: React.ComponentProps<typeof Comma
   );
 }
 
+/** Visual divider between command groups. */
 function CommandSeparator({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Separator>) {
   return (
     <CommandPrimitive.Separator
@@ -101,6 +119,7 @@ function CommandSeparator({ className, ...props }: React.ComponentProps<typeof C
   );
 }
 
+/** A selectable action or item within a command list. Supports icons and keyboard shortcuts via CommandShortcut. */
 function CommandItem({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Item>) {
   return (
     <CommandPrimitive.Item
@@ -114,6 +133,7 @@ function CommandItem({ className, ...props }: React.ComponentProps<typeof Comman
   );
 }
 
+/** Displays a keyboard shortcut hint aligned to the right side of a CommandItem. */
 function CommandShortcut({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span

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

@@ -18,6 +18,7 @@ const meta: Meta<typeof ContextMenu> = {
 export default meta;
 type Story = StoryObj<typeof ContextMenu>;
 
+/** Shows a context menu with shortcuts, submenus, separators, and a destructive action. */
 export const Default: Story = {
   render: () => (
     <ContextMenu>
@@ -50,6 +51,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a minimal context menu with basic cut/copy/paste actions. */
 export const Simple: Story = {
   render: () => (
     <ContextMenu>

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

@@ -6,30 +6,37 @@ import { ContextMenu as ContextMenuPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/** Right-click menu with keyboard navigation. Supports submenus, checkbox/radio items, separators, and shortcuts. */
 function ContextMenu({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />;
 }
 
+/** The element that opens the context menu on right-click. Wraps its children. */
 function ContextMenuTrigger({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Trigger>) {
   return <ContextMenuPrimitive.Trigger data-slot="context-menu-trigger" {...props} />;
 }
 
+/** Groups related context menu items for accessibility. */
 function ContextMenuGroup({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Group>) {
   return <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />;
 }
 
+/** Renders context menu content into a React portal. */
 function ContextMenuPortal({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Portal>) {
   return <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />;
 }
 
+/** Container for a submenu within the context menu. */
 function ContextMenuSub({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Sub>) {
   return <ContextMenuPrimitive.Sub data-slot="context-menu-sub" {...props} />;
 }
 
+/** Groups radio items for single-selection within the context menu. */
 function ContextMenuRadioGroup({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>) {
   return <ContextMenuPrimitive.RadioGroup data-slot="context-menu-radio-group" {...props} />;
 }
 
+/** Menu item that opens a nested submenu on hover or keyboard navigation. Shows a chevron indicator. */
 function ContextMenuSubTrigger({
   className,
   inset,
@@ -54,6 +61,7 @@ function ContextMenuSubTrigger({
   );
 }
 
+/** Popup content for a nested submenu. */
 function ContextMenuSubContent({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.SubContent>) {
   return (
     <ContextMenuPrimitive.SubContent
@@ -67,6 +75,7 @@ function ContextMenuSubContent({ className, ...props }: React.ComponentProps<typ
   );
 }
 
+/** The positioned popup container for context menu items. Portals to the document body. */
 function ContextMenuContent({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Content>) {
   return (
     <ContextMenuPrimitive.Portal>
@@ -82,9 +91,15 @@ function ContextMenuContent({ className, ...props }: React.ComponentProps<typeof
   );
 }
 
+/**
+ * A selectable action within the context menu.
+ * Use variant="destructive" for dangerous actions like delete.
+ */
 function ContextMenuItem({
   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 ContextMenuPrimitive.Item> & {
@@ -105,6 +120,7 @@ function ContextMenuItem({
   );
 }
 
+/** A toggleable checkbox item within the context menu. Shows a check indicator when active. */
 function ContextMenuCheckboxItem({
   className,
   children,
@@ -131,6 +147,7 @@ function ContextMenuCheckboxItem({
   );
 }
 
+/** A radio-selectable item within a ContextMenuRadioGroup. Shows a dot indicator when selected. */
 function ContextMenuRadioItem({
   className,
   children,
@@ -155,6 +172,7 @@ function ContextMenuRadioItem({
   );
 }
 
+/** Non-interactive label within a context menu, used for section headings. */
 function ContextMenuLabel({
   className,
   inset,
@@ -172,6 +190,7 @@ function ContextMenuLabel({
   );
 }
 
+/** Visual divider between groups of context menu items. */
 function ContextMenuSeparator({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Separator>) {
   return (
     <ContextMenuPrimitive.Separator
@@ -182,6 +201,7 @@ function ContextMenuSeparator({ className, ...props }: React.ComponentProps<type
   );
 }
 
+/** Displays a keyboard shortcut hint aligned to the right side of a context menu item. */
 function ContextMenuShortcut({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span